variable.ts

The schemas for the theme data shapes: a style variable and the theme that carries a set of them.

These live together, and apart from theme.ts, so the renderer stays free of zod - theme.ts imports the types type-only, which keeps mounting a theme at roughly a kilobyte.

view source

Declarations
#

6 declarations

parse_theme
#

variable.ts view source

(value: unknown): { name: string; variables: { name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; }[]; summary?: string | undefined; scheme?: "dark" | "light" | "dual" | undefined; scheme_mirror?: { ...; }[] | undefined; } | null import {parse_theme} from '@fuzdev/fuz_css/variable.js';

Parses an unknown value as a Theme, returning null when it doesn't match. For untrusted input - a theme restored from storage, a theme handed across a boundary - where a malformed value should fall back to a default rather than throw. Use Theme.safeParse directly when the failure detail matters, or validate_theme in theme_validate.ts for the full lint.

value

the value to parse

type unknown

returns

Theme | null

the theme, or null when the value isn't one

STYLE_VARIABLE_NAME_MATCHER
#

StyleVariable
#

variable.ts view source

value + type

{ name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; } import {StyleVariable} from '@fuzdev/fuz_css/variable.js';

A style variable: a custom property name with a value per color scheme.

The slots follow the renderer's cascade: light is the base position, rendered on :root, and dark renders on :root.dark. A theme variable with only light therefore applies in both color schemes (its fuz.theme :root beats the fuz.base dark default by layer order), while dark alone applies in dark only - which is why the shipped themes author a scheme-agnostic knob as a single light value.

Strict: a misspelled slot is an error, not a silently dropped scheme. A slot must also be a contained CSS value (see css_containment.ts), since it renders verbatim.

name

type string

light?

type string

dark?

type string

summary?

type string

StyleVariableName
#

Theme
#

variable.ts view source

value + type

{ name: string; variables: { name: string; light?: string | undefined; dark?: string | undefined; summary?: string | undefined; }[]; summary?: string | undefined; scheme?: "dark" | "light" | "dual" | undefined; scheme_mirror?: { ...; }[] | undefined; } import {Theme} from '@fuzdev/fuz_css/variable.js';

name

type string

variables

type StyleVariable[]

summary?

A sentence or two on what the theme looks like, for a theme picker to show beside the name. Never rendered into CSS.

type string

scheme?

The scheme stance, defaulting to 'dual'. A single-scheme stance pins color-scheme on the scope so form controls and native scrollbars agree. A stanced theme's own variables are best authored single-slot in the light/base position.

Rendering a stanced theme faithfully also needs the scheme-adaptive defaults mirrored into the stanced scheme; that is resolve_theme_stance in theme_stance.ts, applied before rendering. The renderer only pins color-scheme - it holds no variable data of its own, so the mirror stays off the theme path of consumers who don't use a stanced theme.

type "dark" | "light" | "dual"

scheme_mirror?

The stance mirror computed by resolve_theme_stance: scheme-adaptive defaults re-slotted so a single-scheme theme's appearance holds in both color schemes. Rendered before variables, so the theme's own values win by order.

Kept apart from variables so the authored knobs stay distinguishable from the derived ones.

type StyleVariable[]

ThemeScheme
#

variable.ts view source

value + type

"dark" | "light" | "dual"

type "dark" | "light" | "dual"

import {ThemeScheme} from '@fuzdev/fuz_css/variable.js';

A theme's scheme stance: which color schemes it supports. 'dual' themes render light and dark appearances from each variable's slots; 'light' and 'dark' themes render that single appearance in both color schemes.

Depends on
#

Imported by
#