CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-fluentui--merge-styles

Runtime CSS-in-JavaScript utilities for dynamic styling with high performance, RTL support, and TypeScript integration.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

configuration.mddocs/

Configuration and Utilities

Global configuration options, RTL support, Shadow DOM configuration, and utility functions for advanced use cases.

Capabilities

RTL Configuration

Global right-to-left language support with automatic style transformation.

/**
 * Sets global RTL (right-to-left) mode
 * @param isRTL - Whether to enable RTL transformations
 */
function setRTL(isRTL: boolean): void;

/**
 * Gets current global RTL mode state
 * @returns Current RTL mode setting
 */
function getRTL(): boolean;

Usage Examples:

import { setRTL, mergeStyles } from "@fluentui/merge-styles";

// Enable RTL globally
setRTL(true);

// These styles will be automatically flipped
const styles = mergeStyles({
  marginLeft: "10px",      // becomes marginRight: "10px"
  paddingLeft: "5px",      // becomes paddingRight: "5px"
  textAlign: "left",       // becomes textAlign: "right"
  borderLeft: "1px solid", // becomes borderRight: "1px solid"
  left: "0px",            // becomes right: "0px"
  float: "left"           // becomes float: "right"
});

// Disable RTL
setRTL(false);

// Language-specific RTL setup
function setupLanguage(locale: string) {
  const rtlLanguages = ["ar", "he", "fa", "ur"];
  const isRTL = rtlLanguages.some(lang => locale.startsWith(lang));
  setRTL(isRTL);
}

Server-Side Rendering

Server-side rendering utility for extracting CSS during HTML generation.

/**
 * Renders HTML and extracts generated CSS for server-side rendering
 * @param onRender - Function that renders HTML content using styles
 * @param namespace - Optional namespace to prepend to CSS class names
 * @returns Object with generated HTML string and CSS rules
 */
function renderStatic(onRender: () => string, namespace?: string): { html: string; css: string };

Usage Examples:

import { renderStatic } from "@fluentui/merge-styles/lib/server";
import { mergeStyles } from "@fluentui/merge-styles";

// Server-side rendering function
function renderApp() {
  const className = mergeStyles({
    color: "blue",
    fontSize: "16px"
  });
  
  return `<div class="${className}">Hello World</div>`;
}

// Extract HTML and CSS for SSR
const { html, css } = renderStatic(renderApp, "my-app");

// html: '<div class="my-app-css-0">Hello World</div>'
// css: '.my-app-css-0{color:blue;font-size:16px;}'

// Send to client
const fullHtml = `
<!DOCTYPE html>
<html>
<head>
  <style>${css}</style>
</head>
<body>
  ${html}
</body>
</html>
`;

Shadow DOM Configuration

Configuration utilities for Shadow DOM stylesheet management.

/**
 * Creates Shadow DOM configuration object
 * @param stylesheetKey - Unique key for the stylesheet
 * @param inShadow - Whether styles are within Shadow DOM
 * @param window - Window object reference
 * @returns Shadow DOM configuration
 */
function makeShadowConfig(
  stylesheetKey: string, 
  inShadow: boolean, 
  window?: Window
): ShadowConfig;

interface ShadowConfig {
  /** Unique identifier for the stylesheet */
  stylesheetKey: string;
  /** Whether stylesheet is in Shadow DOM */
  inShadow: boolean;
  /** Window object reference */
  window?: Window;
  /** Internal type marker */
  __isShadowConfig__: true;
}

/** Default global shadow configuration */
const DEFAULT_SHADOW_CONFIG: ShadowConfig;

/** Global stylesheet key constant */
const GLOBAL_STYLESHEET_KEY = "__global__";

Usage Examples:

import { 
  makeShadowConfig, 
  mergeStyles, 
  DEFAULT_SHADOW_CONFIG,
  GLOBAL_STYLESHEET_KEY 
} from "@fluentui/merge-styles";

// Create Shadow DOM configuration for a component
const componentShadowConfig = makeShadowConfig("my-component", true, window);

// Use with mergeStyles
const shadowStyle = mergeStyles(
  componentShadowConfig,
  {
    color: "blue",
    padding: "10px"
  }
);

// Multiple shadow roots
const dialogShadowConfig = makeShadowConfig("dialog", true);
const tooltipShadowConfig = makeShadowConfig("tooltip", true);

// Global styles (default behavior)
const globalStyle = mergeStyles(
  DEFAULT_SHADOW_CONFIG,
  { fontSize: "14px" }
);

Style Concatenation Utilities

Utility functions for combining styles without CSS generation.

/**
 * Combine style sets without generating CSS classes
 * @param styleSets - Style sets to concatenate
 * @returns Combined style set with merged styles
 */
function concatStyleSets<TStyleSet>(
  ...styleSets: Array<TStyleSet | Missing>
): IConcatenatedStyleSet<ObjectOnly<TStyleSet>>;

function concatStyleSets<TStyleSet1, TStyleSet2>(
  styleSet1: TStyleSet1 | Missing,
  styleSet2: TStyleSet2 | Missing
): IConcatenatedStyleSet<ObjectOnly<TStyleSet1> & ObjectOnly<TStyleSet2>>;

function concatStyleSets<TStyleSet1, TStyleSet2, TStyleSet3>(
  styleSet1: TStyleSet1 | Missing,
  styleSet2: TStyleSet2 | Missing,
  styleSet3: TStyleSet3 | Missing
): IConcatenatedStyleSet<ObjectOnly<TStyleSet1> & ObjectOnly<TStyleSet2> & ObjectOnly<TStyleSet3>>;

function concatStyleSets<TStyleSet1, TStyleSet2, TStyleSet3, TStyleSet4>(
  styleSet1: TStyleSet1 | Missing,
  styleSet2: TStyleSet2 | Missing,
  styleSet3: TStyleSet3 | Missing,
  styleSet4: TStyleSet4 | Missing
): IConcatenatedStyleSet<ObjectOnly<TStyleSet1> & ObjectOnly<TStyleSet2> & ObjectOnly<TStyleSet3> & ObjectOnly<TStyleSet4>>;

function concatStyleSets<TStyleSet1, TStyleSet2, TStyleSet3, TStyleSet4, TStyleSet5>(
  styleSet1: TStyleSet1 | Missing,
  styleSet2: TStyleSet2 | Missing,
  styleSet3: TStyleSet3 | Missing,
  styleSet4: TStyleSet4 | Missing,
  styleSet5: TStyleSet5 | Missing
): IConcatenatedStyleSet<ObjectOnly<TStyleSet1> & ObjectOnly<TStyleSet2> & ObjectOnly<TStyleSet3> & ObjectOnly<TStyleSet4> & ObjectOnly<TStyleSet5>>;

function concatStyleSets<TStyleSet1, TStyleSet2, TStyleSet3, TStyleSet4, TStyleSet5, TStyleSet6>(
  styleSet1: TStyleSet1 | Missing,
  styleSet2: TStyleSet2 | Missing,
  styleSet3: TStyleSet3 | Missing,
  styleSet4: TStyleSet4 | Missing,
  styleSet5: TStyleSet5 | Missing,
  styleSet6: TStyleSet6 | Missing
): IConcatenatedStyleSet<ObjectOnly<TStyleSet1> & ObjectOnly<TStyleSet2> & ObjectOnly<TStyleSet3> & ObjectOnly<TStyleSet4> & ObjectOnly<TStyleSet5> & ObjectOnly<TStyleSet6>>;

Usage Examples:

import { concatStyleSets } from "@fluentui/merge-styles";

// Combine base and theme styles
const baseStyles = {
  container: { display: "flex" },
  header: { fontSize: "18px" }
};

const themeStyles = {
  container: { backgroundColor: "white" },
  header: { color: "black" }
};

// Concatenate without generating CSS classes yet
const combinedStyles = concatStyleSets(baseStyles, themeStyles);
// Result: {
//   container: [{ display: "flex" }, { backgroundColor: "white" }],
//   header: [{ fontSize: "18px" }, { color: "black" }]
// }

// Later generate CSS classes
import { mergeStyleSets } from "@fluentui/merge-styles";
const classNames = mergeStyleSets(combinedStyles);

Functional Style Processing

Utility for processing functional style sets with props.

/**
 * Concatenates style sets resolving functional sets with props
 * @param styleProps - Props to pass to functional style sets
 * @param allStyles - Style sets which can be functions or objects
 * @returns Resolved style set with computed values
 */
function concatStyleSetsWithProps<TStyleProps, TStyleSet extends IStyleSetBase>(
  styleProps: TStyleProps,
  ...allStyles: (IStyleFunctionOrObject<TStyleProps, TStyleSet> | undefined)[]
): DeepPartial<TStyleSet>;

Stylesheet Cloning Utilities

Utilities for cloning CSSStyleSheet objects.

/**
 * Clone CSSStyleSheet from source to target
 * @param srcSheet - Source stylesheet to clone from
 * @param targetSheet - Target stylesheet to clone to
 * @returns The target stylesheet
 */
function cloneCSSStyleSheet(srcSheet: CSSStyleSheet, targetSheet: CSSStyleSheet): CSSStyleSheet;

/**
 * Clone extended CSSStyleSheet with metadata
 * @param srcSheet - Source extended stylesheet
 * @param targetSheet - Target extended stylesheet
 * @returns The target extended stylesheet
 */
function cloneExtendedCSSStyleSheet(
  srcSheet: ExtendedCSSStyleSheet, 
  targetSheet: ExtendedCSSStyleSheet
): ExtendedCSSStyleSheet;

Usage Examples:

import { cloneCSSStyleSheet } from "@fluentui/merge-styles";

// Clone styles between stylesheets
const sourceSheet = new CSSStyleSheet();
const targetSheet = new CSSStyleSheet();

sourceSheet.insertRule('.example { color: red; }');
cloneCSSStyleSheet(sourceSheet, targetSheet);
// targetSheet now has the same rules as sourceSheet

Core Configuration Types

interface IStyleOptions {
  /** Enable RTL style transformations */
  rtl?: boolean;
  /** Shadow DOM configuration */
  shadowConfig?: ShadowConfig;
  /** Custom stylesheet instance */
  stylesheet?: Stylesheet;
  /** CSS specificity multiplier */
  specificityMultiplier?: number;
}

type ObjectOnly<TArg> = TArg extends {} ? TArg : {};

type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends Array<infer U> 
    ? Array<DeepPartial<U>> 
    : T[P] extends object 
      ? DeepPartial<T[P]> 
      : T[P];
};

interface IStyleSetBase {
  [key: string]: any;
  subComponentStyles?: any;
}

type IStyleFunctionOrObject<TStylesProps, TStyleSet extends IStyleSetBase> = 
  IStyleFunction<TStylesProps, TStyleSet> | DeepPartial<TStyleSet>;

type IStyleFunction<TStylesProps, TStyleSet extends IStyleSetBase> = 
  (props: TStylesProps) => DeepPartial<TStyleSet>;

Advanced Configuration Examples

Component-Specific Stylesheets

import { 
  Stylesheet, 
  makeShadowConfig, 
  mergeStyles,
  IStyleSheetConfig 
} from "@fluentui/merge-styles";

// Create isolated stylesheet for a component
class MyComponent {
  private stylesheet: Stylesheet;
  
  constructor() {
    const config: IStyleSheetConfig = {
      namespace: "my-component",
      defaultPrefix: "mc",
      injectionMode: 1 // insertNode
    };
    
    this.stylesheet = new Stylesheet(config);
  }
  
  getStyles() {
    return {
      root: this.stylesheet.insertRule(".root { display: flex; }"),
      content: this.stylesheet.insertRule(".content { padding: 10px; }")
    };
  }
}

Multi-Environment Configuration

// Environment-specific configuration
function createStyleConfig() {
  if (typeof window === 'undefined') {
    // Server-side rendering
    return {
      injectionMode: 0, // none
      rtl: false
    };
  } else if (window.ShadowRoot) {
    // Modern browsers with Shadow DOM
    return makeShadowConfig("app", true, window);
  } else {
    // Legacy browsers
    return {
      injectionMode: 2, // appendChild
      rtl: document.dir === 'rtl'
    };
  }
}

const styleConfig = createStyleConfig();

Theme System Integration

interface ThemeConfig {
  rtl: boolean;
  colors: { primary: string; secondary: string };
  spacing: { small: string; medium: string; large: string };
}

function createThemedStyles(theme: ThemeConfig) {
  // Configure RTL based on theme
  setRTL(theme.rtl);
  
  // Create theme-aware style functions
  const themeStyles = (baseStyles: any) => 
    concatStyleSetsWithProps(theme, baseStyles);
  
  return {
    button: themeStyles((props: ThemeConfig) => ({
      root: {
        backgroundColor: props.colors.primary,
        padding: props.spacing.medium,
        marginInlineStart: props.spacing.small // RTL-aware
      }
    }))
  };
}

docs

configuration.md

css-features.md

index.md

style-merging.md

style-sets.md

stylesheet-management.md

tile.json