Class StyleSheetResolve

Dynamically parses and indexes a CSSStyleSheet at runtime, exposing a selector-to-style mapping by individual selector parts. CSS variable resolution is also possible and this enables the ability to flatten and resolve complex nested var(--...) chains defined across multiple selectors and layers.

When retrieving specific selector styles via StyleSheetResolve.get and StyleSheetResolve.getProperty it is possible to provide additional parent selectors that may define scoped CSS variables. These parent variable definitions will be substituted in the target selector data allowing specific element scoping of CSS variables to be flattened.

Core features:

  • Parses all or specific relevant @layer blocks.
  • Can filter out and exclude undesired CSS selector parts for parsing via excludeSelectorParts option.
  • Can filter out and include just desired CSS layers via includeCSSLayers option.
  • Can filter out and include just desired CSS selector parts via includeSelectorPartSet option.
  • Enables resolution of scoped CSS variables using a parent-selector fallback chain.
  • Provides both direct and resolved access to styles via .get() and .getProperty().

TODO: There are a few improvements to make including supporting CSS variable fallback resolution.

Example

import { StyleSheetResolve } from '#runtime/util/dom/style';

// Parse first stylesheet in the browser `document`.
const parsedStyles = new StyleSheetResolve(document.styleSheets[0]);

// The `props` object has styles w/ CSS variables resolved from `input[type="text"]` for the dark theme.
const props = parsedStyles.get('input[type="text"]', { resolve: '.themed.theme-dark input' });

Constructors

constructor

Accessors

frozen size

Methods

clone entries freeze get getProperty has keys merge

Constructors

constructor

  • new StyleSheetResolve(
        styleSheetOrMap: CSSStyleSheet | Map<string, { [key: string]: string }>,
        options?: {
            excludeSelectorParts?: Iterable<RegExp>;
            includeCSSLayers?: Iterable<RegExp>;
            includeSelectorPartSet?: Set<string>;
        },
    ): StyleSheetResolve

  • Parameters

    • styleSheetOrMap: CSSStyleSheet | Map<string, { [key: string]: string }>

      The stylesheet element to parse or an existing parsed stylesheet Map.

    • Optionaloptions: {
          excludeSelectorParts?: Iterable<RegExp>;
          includeCSSLayers?: Iterable<RegExp>;
          includeSelectorPartSet?: Set<string>;
      }

      Options for parsing stylesheet.

      • OptionalexcludeSelectorParts?: Iterable<RegExp>

        A list of RegExp instance used to exclude CSS selector parts from parsed stylesheet data.

      • OptionalincludeCSSLayers?: Iterable<RegExp>

        A list of RegExp instance used to specifically include in parsing for specific allowed CSS layers if present in the stylesheet.

      • OptionalincludeSelectorPartSet?: Set<string>

        A Set of strings to exactly match selector parts to include in parsed stylesheet data.

    Returns StyleSheetResolve

Accessors

frozen

  • get frozen(): boolean

  • Returns boolean

    Current frozen state; when true no more modifications are possible.

size

  • get size(): number

  • Returns number

    Returns the size / count of selector properties tracked.

Methods

clone

entries

  • entries(): MapIterator<[string, { [key: string]: string }]>

  • Entries iterator of selector / style properties objects.

    Returns MapIterator<[string, { [key: string]: string }]>

    Tracked CSS selector key / value iterator.

freeze

  • freeze(): void

  • Freezes this instance disallowing further modifications to the stylesheet data.

    Returns void

get

  • get(
        selector: string | Iterable<string>,
        opts?: {
            camelCase?: boolean;
            depth?: number;
            resolve?: string | Iterable<string>;
        },
    ): { [key: string]: string }

  • Gets all properties associated with the given selector(s). You may combine multiple selectors for a combined result. You may also provide additional selectors as the resolve option to substitute any CSS variables in the target selector(s).

    Parameters

    • selector: string | Iterable<string>

      A selector or array of selectors to retrieve.

    • Optionalopts: { camelCase?: boolean; depth?: number; resolve?: string | Iterable<string> }

      Options.

      • OptionalcamelCase?: boolean

        When true, property keys will be in camel case.

      • Optionaldepth?: number

        Resolution depth for CSS variable substitution. By default, the depth is the length of the provided resolve selectors, but you may opt to provide a specific depth even with multiple resolution selectors.

      • Optionalresolve?: string | Iterable<string>

        Additional selectors as CSS variable resolution sources.

    Returns { [key: string]: string }

    Style properties object.

getProperty

  • getProperty(
        selector: string | string[],
        property: string,
        options?: { depth?: number; resolve?: string | string[] },
    ): string

  • Gets a specific property value from the given selector and property key. Try and use a direct selector match otherwise all keys are iterated to find a selector string that includes selector.

    Parameters

    • selector: string | string[]

      Selector to find.

    • property: string

      Specific property to locate.

    • Optionaloptions: { depth?: number; resolve?: string | string[] }

      Options.

      • Optionaldepth?: number

        Resolution depth for CSS variable substitution. By default, the depth is the length of the provided resolve selectors, but you may opt to provide a specific depth even with multiple resolution selectors.

      • Optionalresolve?: string | string[]

        Additional selectors as CSS variable resolution sources.

    Returns string

    Style property value.

has

  • has(selector: string): boolean

  • Test if StyleSheetResolve tracks the given selector.

    Parameters

    • selector: string

      CSS selector to check.

    Returns boolean

    StyleSheetResolve tracks the given selector.

keys

merge

  • merge(
        source: StyleSheetResolve,
        options?: { exactMatch?: boolean; strategy?: "override" | "preserve" },
    ): void

  • Merges styles from another StyleSheetResolve instance into this one.

    Parameters

    • source: StyleSheetResolve

      Another instance to merge from.

    • Optionaloptions: { exactMatch?: boolean; strategy?: "override" | "preserve" }

      Options.

      • OptionalexactMatch?: boolean

        Only merge if selector part keys match exactly.

      • Optionalstrategy?: "override" | "preserve"

        By default, the source overrides existing values. You may also provide a preserve strategy which only merges property keys that do not exist already.

    Returns void

Settings

Member Visibility

On This Page

Constructors
Accessors
Methods