css_bundled_resolution.ts

CSS resolution algorithm for bundled CSS generation.

Combines theme variables, base styles, and utility classes into a single bundled output. Resolves which CSS rules and variables to include based on what elements and classes are actually used in the project.

This module provides low-level CSS resolution for advanced use cases. Most users should use gen_fuz_css (Gro) or vite_plugin_fuz_css (Vite) which handle extraction and caching automatically. See those modules for reference implementations.

view source

Declarations
#

6 declarations

CssResolutionOptions
#

css_bundled_resolution.ts view source

CssResolutionOptions import type {CssResolutionOptions} from '@fuzdev/fuz_css/css_bundled_resolution.js';

Options for CSS resolution.

style_rule_index

Index of style.css rules

type StyleRuleIndex

variable_graph

Dependency graph for theme variables

type VariableDependencyGraph

detected_elements

HTML elements detected in source files

type Set<string>

detected_classes

CSS classes detected in source files

type Set<string>

detected_css_variables

CSS variables directly referenced in source files

type Set<string>

utility_variables_used

CSS variables used by generated utility classes

type Set<string>

additional_elements?

Additional elements to always include, or 'all' to include all base styles

type Iterable<string, any, any> | "all"

additional_variables?

Additional variables to always include, or 'all' to include all theme variables

type Iterable<string, any, any> | "all"

include_stats?

Whether to include resolution statistics in result

type boolean

warn_unmatched_elements?

Warn when detected elements have no matching style rules (default false)

type boolean

exclude_elements?

Elements to exclude from base CSS output, even if detected.

type Iterable<string, any, any>

exclude_variables?

CSS variables to exclude from theme output, even if referenced.

type Iterable<string, any, any>

explicit_elements?

Elements explicitly annotated via @fuz-elements comments. These produce errors (not warnings) if they have no matching style rules.

type Set<string> | null

explicit_variables?

Variables explicitly annotated via @fuz-variables comments. These produce errors (not warnings) if they don't exist in the theme.

type Set<string> | null

CssResolutionResult
#

css_bundled_resolution.ts view source

CssResolutionResult import type {CssResolutionResult} from '@fuzdev/fuz_css/css_bundled_resolution.js';

Result from CSS resolution.

theme_css

CSS for theme variables (light and dark)

type string

base_css

CSS for base styles (from style.css), destined for fuz.base

type string

preferences_css

CSS for the OS user-preference mappings, destined for fuz.preferences

type string

resolved_variables

All resolved variable names (including transitive deps)

type Set<string>

included_rule_indices

Indices of rules included from the style index

type Set<number>

included_elements

Element names that were matched

type Set<string>

diagnostics

Diagnostics from resolution

type GenerationDiagnostic[]

stats?

Resolution statistics (only when include_stats is true)

type CssResolutionStats

CssResolutionStats
#

css_bundled_resolution.ts view source

CssResolutionStats import type {CssResolutionStats} from '@fuzdev/fuz_css/css_bundled_resolution.js';

Statistics from CSS resolution (only included when include_stats is true).

element_count

Number of HTML elements included

type number

elements

List of HTML element names included

type string[]

included_rules

Number of rules included from style.css

type number

total_rules

Total number of rules in style.css

type number

variable_count

Number of CSS variables resolved (including transitive deps)

type number

generate_bundled_css
#

css_bundled_resolution.ts view source

(result: CssResolutionResult, utility_css: string, options?: GenerateBundledCssOptions): string import {generate_bundled_css} from '@fuzdev/fuz_css/css_bundled_resolution.js';

Generates combined CSS output from resolution result.

result

resolution result from resolve_css

type CssResolutionResult

utility_css

generated utility CSS (from generate_classes_css)

type string

options

output options

type GenerateBundledCssOptions
default {}

returns

string

combined CSS string

GenerateBundledCssOptions
#

css_bundled_resolution.ts view source

GenerateBundledCssOptions import type {GenerateBundledCssOptions} from '@fuzdev/fuz_css/css_bundled_resolution.js';

Options for bundled CSS output generation.

include_theme?

Include theme variables section.

type boolean

default true

include_base?

Include base styles section.

type boolean

default true

include_utilities?

Include utility classes section.

type boolean

default true

theme_overlay_css?

A baked theme's own overlay (its variables + stance mirror + color-scheme pin), rendered unlayered - emitted into the FUZ_BAKED_THEME_LAYER sublayer so it outranks the fuz.preferences OS mappings like the runtime renderer's output does, and loses to it.

type string | null

resolve_css
#

css_bundled_resolution.ts view source

(options: CssResolutionOptions): CssResolutionResult import {resolve_css} from '@fuzdev/fuz_css/css_bundled_resolution.js';

Resolves which CSS to include based on detected usage.

Algorithm:

  1. Collect rules: core rules + element-matching + class-matching
  2. Collect variables: from rules, generated utility CSS, detected vars, additional_variables
  3. Resolve transitive variable dependencies
  4. Generate output: theme_css (light+dark), base_css (source order)

options

resolution options including indexes, detected usage, and config

type CssResolutionOptions

returns

CssResolutionResult

resolution result with theme CSS, base CSS, and diagnostics

Depends on
#

Imported by
#