Module Cascade.CssSource

Selector syntax, matching and specificity.

The type for CSS declarations (property-value pairs).

The type for CSS statements.

Cascade origins from CSS Cascading and Inheritance.

rule ~selector ?nested ?merge_key declarations creates a CSS rule statement with the given selector and declarations. When merge_key is provided, the optimizer can combine this rule with other rules sharing the same key and identical declarations.

statement_selector stmt returns Some selector if the statement is a rule, None otherwise.

as_rule stmt returns Some (selector, declarations, nested) if the statement is a rule, None otherwise. The declarations are the run written before the first nested statement; a run written after one is a nested declarations rule inside nested, at the position it was written.

as_layer stmt returns Some (name, statements) if the statement is a layer, None otherwise.

as_media stmt returns Some (condition, statements) if the statement is a media query, None otherwise.

as_container stmt returns Some (name, condition, statements) if the statement is a container query, None otherwise.

as_supports stmt returns Some (condition, statements) if the statement is a supports query, None otherwise.

is_nested_media stmt returns true if the statement is a media query containing bare declarations (CSS nesting style), false otherwise.

is_nested_supports stmt returns true if the statement is a supports query containing bare declarations (CSS nesting style), false otherwise.

as_declarations stmt returns Some decls if the statement is a bare declarations block (used in CSS nesting), None otherwise.

unknown_at_rule ~name ~prelude ?block () is the at-rule \@name prelude with block as its body, or the reason its parts cannot make one. It is the way to emit an at-rule cascade has no grammar for, such as one a tool of the caller's own defines. Omitting block gives the statement form, \@name prelude;.

name is the at-keyword without its @. block is the text between the at-rule's braces, since an unknown at-rule has no grammar to re-serialise a body from; to_string ~minify:true statements is that text for a block cascade does model, so placing one needs no re-read of a printed sheet.

A part that would not read back as that part is refused rather than printed, and the refusal names one at-rule rather than the sheet it sits in: building each at-rule on its own loses the malformed one, where re-reading an assembled sheet loses every at-rule in it.

with_origin cascade_origin statements records the cascade origin for a stylesheet block. This is an API-level wrapper with no CSS syntax.

as_origin stmt returns Some (origin, statements) if the statement is an origin wrapper, None otherwise.

origin_importance_rank ~important origin returns the cascade precedence rank for the origin/importance criterion. Larger ranks have higher precedence.

eval_declaration ctx decl rewrites decl to a more-defined declaration under ctx, preserving unresolved subtrees as CSS syntax.

eval_value ctx property value evaluates value in the CSS declaration context of property, returning the evaluated declaration.

eval_rule ctx rule evaluates every declaration in rule and its nested statements.

eval_stylesheet ctx stylesheet evaluates every declaration in stylesheet.

import_layer_name rule returns the layer name declared by an @import rule: None means no layer, Some [] means an anonymous layer, and Some name is a named layer.

layer_block_name stmt returns the declared name of an @layer block rule. Anonymous layer blocks return Some [].

layer_statement_name_list stmt returns the declared name list for statement-form @layer rules.

cascade_layer_precedence_rank returns the same-origin layer precedence rank for a layer. Larger ranks have higher precedence.

compare_cascade_layer_candidate compares same-origin/same-specificity candidates by importance, layer precedence, then source order.

winning_cascade_layer_candidate returns the winning candidate using compare_cascade_layer_candidate.

cascade_revert_layer_candidates returns same-importance candidates in lower-priority layers than the current revert-layer declaration.

compare_cascade_origin_candidate compares same-specificity candidates by origin/importance precedence, then source order.

winning_cascade_origin_candidate returns the winning candidate using compare_cascade_origin_candidate.

cascade_revert_origin_candidates returns same-importance candidates in the origins exposed by a revert declaration from current_origin.

declared_values ?property declarations returns declared values in source order, optionally filtered to one property.

cascaded_value candidates returns the winning cascaded value payload, or None when no candidate contributes a value.

compare_cascade_candidate ~layer_order a b compares full same-property cascade candidates by origin/importance, layer, specificity, scoping proximity, and source order.

winning_cascade_candidate ~layer_order candidates returns the highest priority full cascade candidate.

value ~inherits ~initial ~inherited ~cascaded models the defaulting step from cascaded value to specified value for the non-layout cases represented by this library.

specified_value_after_revert chains revert rollbacks through the origin stack until a non-revert winner remains, then defaults.

specified_value_after_revert_layer is the revert-layer analogue, chained through the layer stack.

value_processing_requires_document_context stage reports whether stage needs caller-supplied document, layout, rendering, or device context rather than CSS text alone.

map f stmts applies f to every rule in stmts: the ones at the top level, the ones inside a conditional group at-rule such as @media, @supports, @layer, @container, @scope or @starting-style, however deeply nested, and the ones nested inside a rule.

• Traversal is depth-first, and a statement that is not a rule is kept with its block rewritten.
• Non-rule statements maintain their relative order.
• When f returns a rule holding no nested statements, the original nested tree is kept with map applied to it; one holding its own replaces it.

sort cmp stmts reorders the rules of stmts with cmp, and the rules of every block below them: inside a conditional group at-rule such as @media, @supports, @layer, @container, @scope or @starting-style, however deeply nested, and inside the nested statements of a rule.

• Each block is sorted on its own, so a rule never leaves the block it sits in.
• Sort is stable: rules cmp calls equal maintain their relative order.
• Non-rule statements sort after the rules of their block and maintain their relative order among themselves, so an @else still follows the @when it answers.

Existential type for property information that preserves type safety

as_property stmt returns Some (Property_info {...}) if the statement is a @property declaration, None otherwise. The existential type preserves the relationship between syntax type and initial value type.

Type for keyframe selectors and their declarations

keyframe ~selector ~declarations is a single keyframe whose selector is parsed via Keyframe.selector_of_string (e.g. "from", "to", "50%", "50%, 100%"). Raises Invalid_argument if selector is not a valid keyframe selector.

keyframes name frames creates a @keyframes rule.

Example:

open Cascade.Css

let pulse =
  keyframes "pulse"
    [
      keyframe ~selector:"50%"
        ~declarations:[ opacity (Opacity_number 0.5) ];
    ]

produces @keyframes pulse { 50% { opacity: 0.5 } }.

as_keyframes stmt returns Some (name, frames) if the statement is a @keyframes animation, None otherwise.

as_font_face stmt returns Some descriptors if the statement is a @font-face rule, None otherwise.

as_import stmt returns Some import_rule if the statement is an @import rule, None otherwise.

The type for CSS stylesheets.

empty is an empty stylesheet.

concat stylesheets concatenates multiple stylesheets into one.

v statements creates a stylesheet from a list of statements.

rule_statements t returns the top-level rule statements from the stylesheet.

statements t returns all top-level statements from the stylesheet.

equal_statement a b is Stylesheet.equal_statement: whether a and b are the same statement, each part read through the equality its own module states.

hash_statement stmt is Stylesheet.hash_statement: a fingerprint consistent with equal_statement, for keying a statement in a hash table without rendering it to CSS text.

fold f acc css folds f over every statement in css and over every statement reachable from one, in source order: a rule nested in a rule, a block at-rule inside a group, and whatever those hold in turn. The walk descends through Stylesheet.statement_children, so it reaches every statement the AST can hold rather than a listed set of at-rules.

Example: Collect all selectors from all rules (including nested ones):

open Cascade

let selectors css =
  Css.fold
    (fun acc stmt ->
      match Css.as_rule stmt with
      | Some (sel, _, _) -> Css.Selector.to_string sel :: acc
      | None -> acc)
    [] css

media_queries t is every @media in t, at any depth, paired with the rule statements below its brace. A query inside a group at-rule counts, and a rule nested in another rule or held by an inner group is one of the query's rules; a nested rule keeps the relative selector it was written with.

layers t is every cascade layer t declares, one path per layer (a.b is the sublayer b of a, however it was written), in the order the sheet first names them. Each path is its idents, so a . one ident carries is not the separator between two. A layer named inside a conditional group counts: the group decides whether its contents apply, not whether the layer exists. A sublayer of an anonymous @layer { ... } has no name to report.

This is what a sheet declares, not the order a cascade resolves in. Resolve.layer_order answers that, and leaves out a layer named inside any block the resolver does not enter: a conditional group rule, @starting-style, @scope or an origin wrapper.

layer_block name sheet is the statements of the layer name, wherever it is declared and whatever form declares it: a dotted name, a nested block, or a block inside a conditional group. It is None when no @layer block opens that layer, so a name only an @layer a, b; statement declares is None as well.

rules_of_statements stmts extracts all CSS rules (selector + declarations) from a list of statements, filtering out at-rules and other non-rule statements.

custom_prop_names decls extracts all custom property names from a list of declarations.

theme_guarded ~var_name decl wraps decl so it is only emitted when var_name is present in the theme.

as_theme_guarded decl returns Some (var_name, inner_decl) if decl is a theme-guarded declaration, None otherwise.

custom_props_of_rules rules extracts all custom property names from the declarations in the rules.

custom_props ?layer sheet is the name of every custom property sheet declares for an element: the ones in a style rule or a bare nesting block, at the top level and inside a conditional group at-rule such as @media, @supports, @container, @scope or @starting-style, however deeply nested. A name declared in @keyframes, @page, @position-try or @supports-condition belongs to another cascade origin or to no element at all (CSS Cascading 5 sec. 6.1) and is not among them. When layer is given, the names are those declared inside the @layer of that name.

media ~condition statements creates a @media statement with the given condition.

media_nested ~condition declarations creates a @media statement for CSS nesting, containing bare declarations (no selector). Used inside rules where the selector is inherited from the parent.

declarations decls creates a bare declarations block (used in CSS nesting).

layer ?name statements creates a @layer statement with the given statements.

layer_decl names creates a @layer declaration statement that declares layer names without any content (e.g., @layer theme, base, components, utilities;).

layer_of ?name stylesheet wraps an entire stylesheet in @layer, preserving @supports and other at-rules within it.

container ?name ~condition statements creates a @container statement with the given statements.

supports ~condition statements creates a @supports statement with the given condition.

starting_style statements creates a @starting-style statement with the given statements. Used for CSS entry animations.

starting_style_nested declarations creates a @starting-style statement for CSS nesting, containing bare declarations (no selector). Used inside rules where the selector is inherited from the parent.

The type of CSS variable holding values of type 'a.

CSS env() reference.

var_name v is v's variable name (without --).

var_layer v is the optional layer where v is defined.

with_fallback var_ref fallback_value creates a new variable reference with the same variable name but a different fallback value. This is useful when you need to reference a variable from another module with a specific fallback, without creating a declaration.

The type of CSS variables.

vars_of_rules statements is vars_of_stylesheet of statements: a statement list is a stylesheet, and the two answer the same question.

vars_of_declarations decls extracts all CSS variables referenced in the declarations list.

vars_of_stylesheet stylesheet is every variable stylesheet references, from the declarations of every statement it holds: a rule nested in a rule, a rule inside any grouping at-rule, and an at-rule carrying declarations of its own such as @keyframes or @page. Deduplicated, in source order.

any_var_name v is the name of a CSS variable (with -- prefix).

custom_declarations ?layer decls is only the custom property declarations from decls. If layer is provided, only declarations from that layer are returned.

all v is the all shorthand. It resets every longhand to v but the two writing-mode ones CSS Cascading 5 sec. 3.3 excepts.

CSS calc operations.

CSS Values 4 sec. 10.7 math constants - emitted at the source byte sequence so pretty pp preserves calc(2 * pi) instead of writing calc(6.28318530718).

CSS Values 4 (ED) sec. 9.1 numeric math function arguments.

CSS Values 4 (ED) sec. 9.1 numeric math functions.

sin / cos / tan arg: an <angle> or unitless <number> (radians). Operation and Grouped support arithmetic over angles.

CSS calc values.

Parsed CSS component values preserved for fallback and invalid-value round-tripping. Prefer typed values in normal user code.

Spec-invalid value fragments preserved until optimization decides whether to drop the containing declaration.

CSS custom-property token stream.

CSS length values.

Supports absolute, relative, viewport (including dynamic/large/small), character-based units, keywords, and calculated expressions.

Builder functions for calc() expressions.

GADT for typed CSS properties.

CSS color spaces for color-mix()

CSS named colors as defined in the CSS Color Module specification.

CSS channel values (for RGB)

CSS alpha values (for HSL/HWB/etc)

CSS hue values (for HSL/HWB)

CSS color component values

CSS percentage values

CSS length or percentage values.

CSS number or percentage values (for properties like scale, brightness)

CSS hue interpolation options

CSS system colors - case-insensitive keywords that map to OS/browser colors. These are semantic colors that adapt to user preferences and system settings.

CSS color values.

hex s is a hexadecimal color. Accepts with or without leading #. Examples: hex "#3b82f6", hex "ffffff". Raises Invalid_argument when s is not one of #rgb, #rrggbb, #rgba or #rrggbbaa; see hex_opt to decide.

hex_opt s is hex without the exception: the colour when s is a hex spelling, and nothing otherwise.

rgb ?alpha r g b is an RGB color (0-255 components) with optional alpha.

hsl h s l is an HSL color with h in degrees, s and l in percentages (0-100).

hsla h s l a is an HSLA color with alpha in 0., 1..

hwb h w b is an HWB color with h in degrees, w and b in percentages (0-100).

hwba h w b a is an HWB color with alpha in 0., 1..

oklch l c h is an OKLCH color. L in percentage (0-100), h in degrees.

oklcha l c h a is an OKLCH color with alpha in 0., 1..

oklch_none_hue l c is an OKLCH color whose hue is none. The hue of an achromatic color is powerless, and none keeps the component missing, so interpolation takes the other color's hue rather than 0.

oklab l a b is an OKLAB color. L in percentage (0-100).

oklaba l a b alpha is an OKLAB color with alpha in 0., 1..

oklaba_none_zeros l a b alpha is like oklaba but uses none for zero a/b components.

lch l c h is an LCH color. L in percentage (0-100), h in degrees.

lcha l c h a is an LCH color with alpha in 0., 1..

color_name n is a named color as defined in the CSS Color specification.

current_color is the CSS currentcolor value.

transparent is the CSS transparent value.

color_mix ?in_space ?percent1 ?percent2 c1 c2 is a color-mix value. Defaults: in_space = Srgb, percent1 = None, percent2 = None.

color_mix_var_percent ?in_space ?hue ~var_name c1 c2 is like color_mix but uses a CSS var reference for the first percentage.

color_mix_var_pct_fallback ?in_space ?hue ~var_name ~fallback c1 c2 is like color_mix_var_percent but with an explicit fallback on the percentage variable. Used for named opacity modifiers.

CSS angle values

CSS number values (unitless numbers for filters, transforms, etc.)

CSS aspect-ratio values

ratio width height is an aspect-ratio value such as 16 / 9.

auto_ratio width height is an aspect-ratio value such as auto 16 / 9.

CSS blend-mode values

The optional value paired with an OpenType feature tag.

One OpenType feature tag and its optional value.

CSS font-feature-settings values.

One OpenType variation axis and its numeric value.

CSS font-variation-settings values.

important decl is decl marked as !important.

declaration_is_important decl returns true if decl has the !important flag.

declaration_name decl returns the property name of decl.

declaration_value ~minify ~inline decl returns the value of decl as a string. If minify is true (default: false), the output is minified. If inline is true (default: false), variables are resolved to their default values.

declaration_value_for_equivalence decl is the minified value of decl, so a structural diff keys a typed property on its shortest spelling and padding: 0.50px and padding: .5px compare equal.

A custom-property token stream, whose bytes declaration_value keeps verbatim, also loses the whitespace CSS reads as nothing: the whitespace CSS Values 4 (ED) sec. 10.8 leaves optional around a math * and /, and the whitespace a closing bracket already accounts for. So --r: 16 / 9 and --r: 16/9 compare equal, while the space sec. 10.8 requires around a math + or -, and the space beside a var(), env() or attr() that sec. 2.5 substitutes textually into its neighbour, keep two spellings apart.

A quoted family name in that stream is rewritten as the equivalent unquoted <ident> sequence, one word or several, when a generic family in the stream proves the stream is a font-family list, where CSS Fonts 4 sec. 2.1.1 spells the one name both ways: --font: ui-sans-serif,"Noto Color Emoji" and --font: ui-sans-serif,Noto Color Emoji compare equal, as do --font: "Arial",sans-serif and --font: Arial,sans-serif. Without that proof the stream is arbitrary tokens, in which one <string> is not an <ident> sequence, and the two spellings keep distinct keys.

Not for emission, where every one of these forms stays verbatim.

CSS box sizing values.

CSS field sizing values.

CSS caption side values.

width len is the width property.

height len is the height property.

min_width len is the min-width property.

max_width len is the max-width property.

min_height len is the min-height property.

max_height len is the max-height property.

inline_size len is the inline-size logical property.

min_inline_size len is the min-inline-size logical property.

max_inline_size len is the max-inline-size logical property.

block_size len is the block-size logical property.

min_block_size len is the min-block-size logical property.

max_block_size len is the max-block-size logical property.

padding values is the padding shorthand property. Accepts 1-4 values.

padding_top len is the padding-top property.

padding_right len is the padding-right property.

padding_bottom len is the padding-bottom property.

padding_left len is the padding-left property.

margin values is the margin shorthand property. Accepts 1-4 values.

margin_top len is the margin-top property.

margin_right len is the margin-right property.

margin_bottom len is the margin-bottom property.

margin_left len is the margin-left property.

box_sizing sizing is the box-sizing property.

field_sizing sizing is the field-sizing property.

caption_side side is the caption-side property.

aspect_ratio ratio is the aspect-ratio property.