style_rule_parser.ts

Base stylesheet parser for bundled CSS generation.

Parses a base stylesheet - the fuz_css style.css, or whatever the base_css generator option supplies - into a structured index that maps its top-level rules to the HTML elements and classes they style, so the bundled CSS generator includes only the rules a project uses.

The contract is pass-through with shallow tree-shaking, for any CSS the parser (parseCss from svelte/compiler) accepts:

  • Top-level style rules and top-level conditional group rules (@media, @supports, @container) are tree-shaken by the elements and classes they target. A group is one unit - it ships whole or not at all. A rule with a selector the index can't match always ships.
  • Every other at-rule (@keyframes, @font-face, @property, @scope, ...) ships as written.
  • Every var() reference in a rule that ships is tracked, however deeply it is nested, so the theme includes the variables it needs.
  • The generator owns layering: everything lands in fuz.base, except the contents of a top-level @layer fuz.preferences block. Any other @layer rule is an error, as are @import and @namespace, which are invalid inside a layer block. An error never removes CSS - the construct ships as written with the rule it sits in.
  • The one construct left out is @charset: an encoding marker that means nothing in a string, which preprocessors emit for non-ASCII output.
view source

Declarations
#

14 declarations

collect_rule_variables
#

style_rule_parser.ts view source

(index: StyleRuleIndex, included_indices: Set<number>): Set<string> import {collect_rule_variables} from '@fuzdev/fuz_css/style_rule_parser.js';

Collects all CSS variables used by the included rules.

index

type StyleRuleIndex

included_indices

set of rule indices to include

type Set<number>

returns

Set<string>

set of variable names (without -- prefix)

CoreReason
#

style_rule_parser.ts view source

CoreReason

type "universal" | "root" | "body" | "conditional_core" | "html" | "host" | "at_rule" | "untargetable"

import type {CoreReason} from '@fuzdev/fuz_css/style_rule_parser.js';

Reasons a rule is considered "core" and always included. conditional_core marks a conditional group rule (@media, @supports, @container) that contains something which always ships on its own - a core rule or an at_rule. at_rule marks every at-rule that is not a conditional group (@keyframes, @font-face, @property, @scope, ...): detection has no way to tell whether one is used, so it ships as written. untargetable marks rules with a selector the index can't match - one that names no element or class at all (pseudo-element or attribute selectors like ::selection and [hidden]), or one with an escaped or non-ASCII identifier (.md\:flex, .café) - so tree-shaking would drop them whether or not the project uses them.

CoreStyleRule
#

create_style_rule_index
#

style_rule_parser.ts view source

(css: string): StyleRuleIndex import {create_style_rule_index} from '@fuzdev/fuz_css/style_rule_parser.js';

Creates a StyleRuleIndex from the stylesheet a base_css option supplies, reporting a value that can't be parsed as a base_css problem.

css

the base_css string, or the string its callback returned

type string

returns

StyleRuleIndex

throws

  • if - `css` is not syntactically valid CSS, with the parser's error as the `cause`

generate_base_css_by_layer
#

style_rule_parser.ts view source

(index: StyleRuleIndex, included_indices: Set<number>): Record<RuleLayer, string> import {generate_base_css_by_layer} from '@fuzdev/fuz_css/style_rule_parser.js';

Generates CSS from a StyleRuleIndex with only the included rules, partitioned by destination cascade layer in one sorted pass.

index

type StyleRuleIndex

included_indices

set of rule indices to include

type Set<number>

returns

Record<RuleLayer, string>

per-layer CSS strings, each in original rule order

get_matching_rules
#

style_rule_parser.ts view source

(index: StyleRuleIndex, detected_elements: Set<string>, detected_classes: Set<string>): Set<number> import {get_matching_rules} from '@fuzdev/fuz_css/style_rule_parser.js';

Gets rules that should be included based on detected elements and classes.

index

the StyleRuleIndex to query

type StyleRuleIndex

detected_elements

set of HTML element names found in source

type Set<string>

detected_classes

set of CSS class names found in source

type Set<string>

returns

Set<number>

set of rule indices to include

load_default_style_css
#

style_rule_parser.ts view source

(deps: CacheDeps): Promise<string> import {load_default_style_css} from '@fuzdev/fuz_css/style_rule_parser.js';

Loads the raw content of the package's default style.css.

deps

filesystem deps for dependency injection

type CacheDeps

returns

Promise<string>

promise resolving to the CSS string

load_style_rule_index
#

NonCoreStyleRule
#

style_rule_parser.ts view source

NonCoreStyleRule import type {NonCoreStyleRule} from '@fuzdev/fuz_css/style_rule_parser.js';

A non-core style rule included only when its elements/classes are detected.

inheritance

extends: StyleRuleBase

is_core

type false

core_reason

type null

parse_style_css
#

style_rule_parser.ts view source

(css: string): StyleRuleIndex import {parse_style_css} from '@fuzdev/fuz_css/style_rule_parser.js';

Parses a base stylesheet into a StyleRuleIndex.

Each top-level style rule and at-rule becomes one indexed rule that ships whole or not at all. A top-level @layer fuz.base or `@layer fuz.preferences` block is unwrapped first, so its contents are top-level too and bundled output re-layers the selected rules; the shipped layer order statement is skipped because the bundle emits its own, and so is @charset, which means nothing in a string. Every other @layer rule, and each @import/@namespace, becomes an error in the index's diagnostics and is still indexed as written - an error never removes CSS.

css

raw CSS string (e.g., contents of style.css)

type string

returns

StyleRuleIndex

StyleRuleIndex with rules, lookup maps, and diagnostics

throws

  • if - `css` is not syntactically valid

RuleLayer
#

style_rule_parser.ts view source

RuleLayer

type "fuz.base" | "fuz.preferences"

import type {RuleLayer} from '@fuzdev/fuz_css/style_rule_parser.js';

The cascade layer a rule is emitted into in bundled output. A base stylesheet's rules land in fuz.base; the contents of a top-level @layer fuz.preferences block keep that identity, because the OS user-preference mappings must stay above the fuz.base defaults. No other layer survives parsing - see parse_style_css.

StyleRule
#

StyleRuleBase
#

style_rule_parser.ts view source

StyleRuleBase import type {StyleRuleBase} from '@fuzdev/fuz_css/style_rule_parser.js';

Base fields shared by all style rules.

css

The full CSS text for this rule (including selector and declarations)

type string

elements

HTML element names this rule targets (e.g., 'button', 'input')

type Set<string>

classes

CSS class names this rule targets (e.g., 'unstyled', 'selected')

type Set<string>

variables_used

CSS variables referenced anywhere in the rule's text, nested rules included. Read from the raw text, so it can only over-include - which never leaves a var() undefined.

type Set<string>

variables_required

The subset of variables_used that something outside the rule must define: referenced with no fallback outside a comment, and not declared by the rule itself.

type Set<string>

variables_defined

Custom properties the rule defines for the whole document: the ones a top-level style rule declares when a selector in its list is exactly :root, :host, html, body, or *. Empty for every other rule.

type Set<string>

order

Original order in the stylesheet (for preserving cascade)

type number

layer

The cascade layer this rule is emitted into in bundled output

type RuleLayer

StyleRuleIndex
#

style_rule_parser.ts view source

StyleRuleIndex import type {StyleRuleIndex} from '@fuzdev/fuz_css/style_rule_parser.js';

Index of parsed style rules for efficient lookup.

rules

All rules in original order

type StyleRule[]

by_element

Rules indexed by element name

type Map<string, number[]>

by_class

Rules indexed by class name

type Map<string, number[]>

diagnostics

Problems found while parsing: constructs the stylesheet contains that don't belong in a base stylesheet (base_css_layer, base_css_unsupported_at_rule). resolve_css forwards them with its own diagnostics.

type GenerationDiagnostic[]

Depends on
#

Imported by
#