/** * Built-in CSS class definitions combining composites, keyword classes, and * token classes, and the definition types custom classes are authored with * (`CssClassDefinition`, `CssClassDefinitionInterpreter`). * * Token classes map to CSS variables (design tokens), and keyword classes are * CSS value keywords that identify their property (`flex`, `sticky`). For * other CSS values, use CSS-literal syntax like `justify-content:center` or * `overflow:hidden`. * * @module */ import type { InterpreterDiagnostic } from './diagnostics.ts'; import type { ClassDefinitionsOption } from './css_plugin_options.ts'; import { generate_classes, generate_property_classes, generate_directional_classes, generate_border_radius_corners, generate_shadow_classes, format_spacing_value } from './css_class_generators.ts'; import { space_variants, distance_variants, palette_variants, intent_variants, intensity_variants, shade_variants, shade_scale_variants, text_scale_variants, font_size_variants, icon_size_variants, line_height_variants, border_radius_variants, border_width_variants, shadow_size_variants, shadow_semantic_values, shadow_alpha_variants, darken_lighten_variants } from './variable_data.ts'; import { css_class_composites } from './css_class_composites.ts'; import { css_class_keywords } from './css_class_keywords.ts'; export interface CssClassDefinitionBase { /** * Whether the class is a composite, rendered in the * `fuz.utilities.composites` sublayer beneath every single-purpose class, * so a token or literal class on the same element always wins over the * composite's declaration of the same property. Defaults to `true` for * `composes` and `ruleset` definitions, `false` for a `declaration` * without `composes`. */ composite?: boolean; /** * Whether the class orders late within its bucket: after every rule that * ties with it on color scheme, media query, property rank, and state * order, interpreted literals included, so `display:flex hidden` hides * while a media query still outranks it (`hidden md:flex` shows at `md` * and up). For an override that should win its ties whatever else names * the same property, like `hidden`. Composites order by their registry * position, which no two share, so the flag only reorders single-purpose * classes. */ late?: boolean; } /** Pure utility composition (composes only). */ export interface CssClassDefinitionComposition extends CssClassDefinitionBase { composes: Array; declaration?: never; ruleset?: never; } /** Custom CSS declaration (optionally seeded with composes). */ export interface CssClassDefinitionDeclaration extends CssClassDefinitionBase { declaration: string; composes?: Array; ruleset?: never; } /** Full ruleset with selectors. */ export interface CssClassDefinitionRuleset extends CssClassDefinitionBase { ruleset: string; composes?: never; declaration?: never; } /** Static definitions (not interpreter-based). */ export type CssClassDefinitionStatic = CssClassDefinitionComposition | CssClassDefinitionDeclaration | CssClassDefinitionRuleset; /** Full union including interpreters. */ export type CssClassDefinition = CssClassDefinitionStatic | CssClassDefinitionInterpreter; /** * Context passed to CSS class interpreters. * Provides access to diagnostics collection and the class registry. */ export interface CssClassInterpreterContext { /** * Diagnostics array to collect warnings and errors. Each carries a `code` - * `class_interpreter` unless a more specific `DiagnosticCode` fits; an error * coded `class_property_unknown`, `class_modifier_unknown`, or * `class_value_uncontained` warns instead for a class nobody named * explicitly. */ diagnostics: Array; /** All known CSS class definitions (token + composite classes). */ class_definitions: Record; /** Valid CSS properties for literal validation, or null to skip validation. */ css_properties: Set | null; } /** * Interpreter for dynamic CSS class generation based on pattern matching. * * An interpreter sees a class name with its modifiers already stripped - * `md:hover:grid-cols-4` reaches it as `grid-cols-4` - and returns a * definition like a static one, so modifiers, ordering, and layering apply to * what it returns the same as to a static class. A `ruleset` names the class * it was given; the generator renames it to the full modified class. What * an interpreter returns renders verbatim, so containing values built from * class names found in markup is the interpreter's job. * * Leading segments named like modifiers are stripped greedily, and the * generator backs off one at a time, so an interpreter is offered the * shortest base first: `marker:none` arrives as `none` before the full * literal, since `marker` is also a pseudo-element modifier (`cue` likewise). * A broad pattern shouldn't claim such a sub-base. */ export interface CssClassDefinitionInterpreter extends CssClassDefinitionBase { pattern: RegExp; /** * @mutates `ctx.diagnostics` - implementations push errors/warnings to the diagnostics array */ interpret: ( matched: RegExpMatchArray, ctx: CssClassInterpreterContext ) => CssClassDefinitionStatic | null; } // `0` as-is, a radius variant as its `--border_radius_*` variable const format_border_radius_value = (value: string): string => value === '0' ? '0' : `var(--border_radius_${value})`; // TODO add animation support, either as a separate thing or rename `css_class_definitions` to be more generic, like `css_by_name` - need to collect `animation: foo ...` names like we do classes /** * All built-in CSS class definitions (composites, keyword classes, and token classes). * * @see `generate_classes_css` */ export const css_class_definitions: Record = { // Composite classes go first, so they can be overridden by the more specific classes. ...css_class_composites, // Keyword classes - bare CSS value keywords like `flex` and `sticky`, plus `hidden` ...css_class_keywords, /* typography */ font_family_sans: { declaration: 'font-family: var(--font_family_sans);' }, font_family_serif: { declaration: 'font-family: var(--font_family_serif);' }, font_family_mono: { declaration: 'font-family: var(--font_family_mono);' }, ...generate_property_classes( 'line-height', line_height_variants, (v) => `var(--line_height_${v})` ), ...generate_property_classes( 'font-size', font_size_variants, (v) => `var(--font_size_${v}); --font_size: var(--font_size_${v})` ), ...generate_property_classes( 'font-size', icon_size_variants, (v) => `var(--icon_size_${v}); --font_size: var(--icon_size_${v}); --icon_size: var(--icon_size_${v})`, 'icon_size' ), /* colors */ // Text colors (flipped scale: low numbers = subtle, high numbers = bold) ...generate_property_classes( 'color', text_scale_variants, (v) => `var(--text_${v}); --text_color: var(--text_${v})`, 'text' ), // Shade scale (tinted backgrounds) ...generate_property_classes( 'background-color', shade_scale_variants, (v) => `var(--shade_${v})`, 'shade' ), // Palette intensity classes (text color); property-first like the other // applications of the palette variables (`bg_`, `border_`, `outline_`, // `shadow_`) - the letter alone implies the palette ...generate_classes( (letter: string, intensity: string) => ({ name: `color_${letter}_${intensity}`, css: `color: var(--palette_${letter}_${intensity}); --text_color: var(--palette_${letter}_${ intensity });` }), palette_variants, intensity_variants ), // Palette intensity classes (background color) ...generate_classes( (letter: string, intensity: string) => ({ name: `bg_${letter}_${intensity}`, css: `background-color: var(--palette_${letter}_${intensity});` }), palette_variants, intensity_variants ), // Intent intensity classes (text color) - meaning-first twins of the palette classes ...generate_classes( (intent: string, intensity: string) => ({ name: `${intent}_${intensity}`, css: `color: var(--${intent}_${intensity}); --text_color: var(--${intent}_${intensity});` }), intent_variants, intensity_variants ), // Intent intensity classes (background color) ...generate_classes( (intent: string, intensity: string) => ({ name: `bg_${intent}_${intensity}`, css: `background-color: var(--${intent}_${intensity});` }), intent_variants, intensity_variants ), // Darken/lighten overlays (non-adaptive, alpha-based) ...generate_property_classes( 'background-color', darken_lighten_variants, (v) => `var(--darken_${v})`, 'darken' ), ...generate_property_classes( 'background-color', darken_lighten_variants, (v) => `var(--lighten_${v})`, 'lighten' ), // The adaptive alpha overlay variables (`--ink_*`, a wash toward the text // color, and `--paper_*`, toward the ground) have no token classes - `bg_` // stays the opaque background prefix (`bg_a_50`, `bg_positive_50`). Reach // the overlays with literals - `background-color:var(--ink_10)`. /* borders */ // Border color alpha ramp - the letterless `border_color_NN` family sets both // the property and the contextual variable (`outline_shade_NN` is the opaque shade ramp) ...generate_property_classes( 'border-color', darken_lighten_variants, (v) => `var(--border_color_${v}); --border_color: var(--border_color_${v})`, 'border_color' ), // Border colors using palette hue + intensity (sets both property and contextual variable); // the letter alone implies the palette - the alpha-ramp family is `border_color_NN` ...generate_classes( (letter: string, intensity: string) => ({ name: `border_${letter}_${intensity}`, css: `border-color: var(--palette_${letter}_${intensity}); --border_color: var(--palette_${ letter }_${intensity});` }), palette_variants, intensity_variants ), // Intent border colors - meaning-first twins of the palette border classes ...generate_classes( (intent: string, intensity: string) => ({ name: `border_${intent}_${intensity}`, css: `border-color: var(--${intent}_${intensity}); --border_color: var(--${intent}_${intensity});` }), intent_variants, intensity_variants ), // Outline colors using shade scale (sets both property and contextual variable, // so hover and focus borders follow it like the palette family) ...generate_property_classes( 'outline-color', shade_variants, (v) => `var(--shade_${v}); --outline_color: var(--shade_${v})`, 'outline_shade' ), // Outline colors using palette hue + intensity (sets both property and contextual variable); // the letter alone implies the palette - the shade family is `outline_shade_NN` ...generate_classes( (letter: string, intensity: string) => ({ name: `outline_${letter}_${intensity}`, css: `outline-color: var(--palette_${letter}_${intensity}); --outline_color: var(--palette_${ letter }_${intensity});` }), palette_variants, intensity_variants ), // Intent outline colors - meaning-first twins of the palette outline classes ...generate_classes( (intent: string, intensity: string) => ({ name: `outline_${intent}_${intensity}`, css: `outline-color: var(--${intent}_${intensity}); --outline_color: var(--${intent}_${intensity});` }), intent_variants, intensity_variants ), ...generate_property_classes( 'border-width', border_width_variants.map(String), (v) => `var(--border_width_${v})` ), ...generate_property_classes( 'outline-width', border_width_variants.map(String), (v) => `var(--border_width_${v})` ), outline_width_focus: { declaration: 'outline-width: var(--outline_width_focus);' }, outline_width_active: { declaration: 'outline-width: var(--outline_width_active);' }, ...generate_property_classes( 'border-radius', ['0', ...border_radius_variants], format_border_radius_value ), ...generate_border_radius_corners(['0', ...border_radius_variants], format_border_radius_value), /* shadows */ ...generate_shadow_classes(shadow_size_variants, { xs: '30', sm: '40', md: '50', lg: '60', xl: '70' }), ...generate_classes( (value: string) => ({ name: `shadow_color_${value}`, css: `--shadow_color: var(--shadow_color_${value});` }), shadow_semantic_values ), ...generate_classes( (alpha: string) => ({ name: `shadow_alpha_${alpha}`, css: `--shadow_alpha: var(--shadow_alpha_${alpha});` }), shadow_alpha_variants ), // Shadow colors using palette hue + intensity (sets contextual variable only); // the letter alone implies the palette - semantic colors are `shadow_color_umbra` etc. ...generate_classes( (letter: string, intensity: string) => ({ name: `shadow_${letter}_${intensity}`, css: `--shadow_color: var(--palette_${letter}_${intensity});` }), palette_variants, intensity_variants ), // Intent shadow colors - meaning-first twins of the palette shadow classes ...generate_classes( (intent: string, intensity: string) => ({ name: `shadow_${intent}_${intensity}`, css: `--shadow_color: var(--${intent}_${intensity});` }), intent_variants, intensity_variants ), /* layout */ ...generate_classes( (v: string) => ({ name: `width_atmost_${v}`, css: `width: 100%; max-width: var(--distance_${v});` }), distance_variants ), ...generate_classes( (v: string) => ({ name: `width_atleast_${v}`, css: `width: 100%; min-width: var(--distance_${v});` }), distance_variants ), ...generate_classes( (v: string) => ({ name: `height_atmost_${v}`, css: `height: 100%; max-height: var(--distance_${v});` }), distance_variants ), ...generate_classes( (v: string) => ({ name: `height_atleast_${v}`, css: `height: 100%; min-height: var(--distance_${v});` }), distance_variants ), ...generate_directional_classes('padding', ['0', ...space_variants], format_spacing_value), ...generate_directional_classes('margin', ['0', 'auto', ...space_variants], format_spacing_value), ...generate_property_classes('gap', ['0', ...space_variants], format_spacing_value), ...generate_property_classes('column-gap', ['0', ...space_variants], format_spacing_value), ...generate_property_classes('row-gap', ['0', ...space_variants], format_spacing_value) }; /** * Resolves the `class_definitions` option against the built-in definitions. * A record merges over the defaults, taking precedence over a default with * the same name, and a callback receives a copy of the defaults and returns * the whole set. * * @param option - the `class_definitions` option * @returns the class definitions to generate with * @throws Error - if a callback returns something other than an object */ export const resolve_class_definitions = ( option: ClassDefinitionsOption ): Record => { if (typeof option === 'function') { const result: unknown = option({ ...css_class_definitions }); if (typeof result !== 'object' || result === null || Array.isArray(result)) { throw new Error( `The class_definitions callback must return an object of definitions, got ${ result === null ? 'null' : Array.isArray(result) ? 'an array' : typeof result }` ); } return result as Record; } return option ? { ...css_class_definitions, ...option } : css_class_definitions; };