@cueplusplus/ui 0.1.0

package/dist/theming/create-theme.js

@@ -0,0 +1,442 @@
+import { formatColorString } from "../color/_convert.js";
+import { BASE_FONT_STACKS, DEFAULT_DENSITY_LEVEL, DENSITY_RADIUS_SCALE, THEME_COLOR_TOKENS, THEME_PRESETS } from "./_presets.js";
+import { WCAG_AA_TEXT, contrastRatio, contrastReport } from "./contrast.js";
+import { assertCssValue, assertThemeName, derivedTokens, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
+import { clampChroma, converter, formatHex, inGamut, parse } from "culori";
+//#region src/theming/create-theme.ts
+/**
+* `createTheme()` — the typed generator behind the spec's second theming tier.
+*
+* Three things it is not, because each of them is a trap this deliberately
+* avoids:
+*
+* - **Not a runtime engine.** It is a pure function of its arguments, called at
+*   build time (or once, in the configurator's export dialog), and what comes
+*   out is a plain `[data-theme]` stylesheet — tier 1, the guaranteed contract.
+*   Nothing about a shipped app depends on this module existing.
+* - **Not a palette generator.** Handed a preset and nothing else it returns the
+*   preset, byte for byte. Derivation is what happens to the tokens hanging off
+*   an anchor you actually moved, and only those: swap the accent and the hover,
+*   the ink on it, the focus ring and the selection wash follow; the ground, the
+*   ink and the five status tones do not. That rule is the whole reason
+*   "start from `terminal`, make it orange" is a two-line call rather than a
+*   fork of a palette.
+* - **Not a colour opinion.** Every derivation happens in oklch, where a
+*   lightness step is a step the eye agrees with, and every result is measured
+*   against WCAG before you are told it is fine. A failing pair comes back in
+*   the report rather than being silently repaired — with one exception, noted
+*   below, where the value was this module's invention in the first place.
+*/
+/** The preset a theme starts from when the caller names none. */
+const DEFAULT_THEME_BASE = "cue";
+/**
+* How far the sunken ground sits below the page, in oklch lightness.
+*
+* Small on purpose: sunken is a well, not a second theme. Across the eight
+* shipped presets the authored gap runs −0.011 to −0.031.
+*/
+const SUNKEN_LIGHTNESS_STEP = -.02;
+/**
+* The three raised surfaces, as lightness above the ground.
+*
+* Even spacing, because the ladder encodes *elevation* and a reader counts
+* rungs. The shipped presets cluster around these three values.
+*/
+const SURFACE_LIGHTNESS_STEPS = [
+	.03,
+	.05,
+	.07
+];
+/**
+* The hairline and its stronger sibling, as lightness above the ground.
+*
+* Above the top surface, so a border still reads as a line when it is drawn on
+* `surface-3`. `border-overlay` reuses the strong value: an overlay floats over
+* everything, so its rim has to hold against the brightest thing under it.
+*/
+const BORDER_LIGHTNESS_STEPS = [.08, .14];
+/** How far secondary ink recedes from primary ink. */
+const FG_MUTED_LIGHTNESS_STEP = -.25;
+/** How far tertiary ink recedes from primary ink. */
+const FG_SUBTLE_LIGHTNESS_STEP = -.45;
+/**
+* Chroma each rung of the ink ramp keeps from the rung above.
+*
+* Ink greys as it recedes rather than staying saturated: a muted label that held
+* full chroma would read as a *coloured* label — a status, a link — instead of a
+* quiet one. The hue is preserved throughout, so the ramp still belongs to the
+* theme. `fg-subtle` takes the square, being two rungs down.
+*/
+const INK_RAMP_CHROMA_SCALE = .6;
+/** How far the accent darkens on hover. */
+const ACCENT_HOVER_LIGHTNESS_STEP = -.05;
+/** How much accent a derived selection wash carries. */
+const SELECTION_ACCENT_PERCENT = 22;
+/** What a label on a solid accent has to reach before this module accepts it. */
+const ACCENT_FG_MINIMUM = WCAG_AA_TEXT;
+/**
+* How much of the dark ground's lightness survives the flip to paper.
+*
+* A ground's job is to be the extreme, so inverting it means going to the *other*
+* extreme rather than to the arithmetic mirror: `1 − L` of a 0.16 near-black is a
+* 0.84 mid-grey, which is not a page. Compressing instead maps the ladder of
+* dark grounds onto a narrow paper band — a deeper dark theme gets a cleaner
+* white page — and lands within 0.01 of all eight authored light presets.
+*/
+const LIGHT_GROUND_COMPRESSION = .1;
+/** Lightness a derived light colour steps down by while hunting for contrast. */
+const LIGHT_DARKEN_STEP = .02;
+/** How many steps that hunt may take before it gives up and returns its darkest. */
+const LIGHT_DARKEN_LIMIT = 40;
+const toOklch = converter("oklch");
+const inSrgb = inGamut("rgb");
+/** Read an anchor into oklch, or say which anchor could not be read. */
+function readColor(value, label) {
+	const color = toOklch(parse(value));
+	if (color === void 0) throw new TypeError(`${label} is not a colour: ${JSON.stringify(value)}`);
+	return {
+		mode: "oklch",
+		l: color.l,
+		c: color.c,
+		h: color.h ?? 0
+	};
+}
+/**
+* Print a derived colour.
+*
+* Chroma is **clamped** into sRGB rather than clipped — clipping a too-saturated
+* step turns it into a different hue, whereas clamping only gives up the
+* saturation no display was going to show. Then it goes out through the same
+* formatter the colour picker writes with, so a generated token and a
+* hand-picked one are spelled the same way.
+*/
+function emit(color) {
+	const hex = formatHex(inSrgb(color) ? color : clampChroma(color, "oklch", "rgb"));
+	return formatColorString(hex, "oklch") ?? hex;
+}
+const clampLightness = (lightness) => Math.min(1, Math.max(0, lightness));
+/** The same hue, moved along the lightness axis and optionally greyed. */
+function shift(color, delta, chromaScale = 1) {
+	return emit({
+		mode: "oklch",
+		l: clampLightness(color.l + delta),
+		c: color.c * chromaScale,
+		h: color.h
+	});
+}
+/**
+* The candidate that can be read on `ground`, preferring the theme's own ink.
+*
+* Tried in order: the colours the theme already owns, then pure black and white
+* as a last resort. A theme's own ground or ink keeps the palette coherent; the
+* fallback exists because an accent at mid lightness contrasts with neither.
+*/
+function pickInk(ground, candidates) {
+	let best = candidates[0] ?? "#000000";
+	let bestRatio = -1;
+	for (const candidate of candidates) {
+		const ratio = contrastRatio(candidate, ground);
+		if (ratio > bestRatio) [best, bestRatio] = [candidate, ratio];
+	}
+	if (bestRatio >= ACCENT_FG_MINIMUM) return best;
+	for (const candidate of ["#000000", "#ffffff"]) {
+		const ratio = contrastRatio(candidate, ground);
+		if (ratio > bestRatio) [best, bestRatio] = [candidate, ratio];
+	}
+	return best;
+}
+/**
+* Darken a colour until it can be read on `ground`.
+*
+* Only ever applied to values this module invented — the light variant's accent
+* and status tones, which have to survive being moved from a near-black ground
+* to paper. An authored colour is never quietly adjusted; it is reported.
+*/
+function darkenToContrast(value, ground, minimum, label) {
+	const start = readColor(value, label);
+	for (let step = 0; step <= LIGHT_DARKEN_LIMIT; step += 1) {
+		const candidate = emit({
+			...start,
+			l: clampLightness(start.l - step * LIGHT_DARKEN_STEP)
+		});
+		if (contrastRatio(candidate, ground) >= minimum) return candidate;
+	}
+	return emit({
+		...start,
+		l: clampLightness(start.l - LIGHT_DARKEN_LIMIT * LIGHT_DARKEN_STEP)
+	});
+}
+/** Own-property lookup that admits a token may be absent. */
+function lookup(map, token) {
+	return map != null && Object.hasOwn(map, token) ? map[token] : void 0;
+}
+/**
+* A derived selection wash, as a live expression rather than a resolved colour.
+*
+* `var(--cue-accent)` is a self-reference — it resolves inside whichever block
+* declares it — so one string is correct in the dark block and the light one,
+* and stays correct if a consumer overrides the accent in tier 1 later.
+*/
+const SELECTION_WASH = `color-mix(in oklch, var(--cue-accent) 22%, transparent)`;
+/** The five status tones, in the order every theme block declares them. */
+const STATUSES = [
+	"ok",
+	"busy",
+	"warn",
+	"danger",
+	"info"
+];
+/** The three raised surfaces, in ladder order. */
+const SURFACES = [
+	"surface-1",
+	"surface-2",
+	"surface-3"
+];
+/**
+* Resolve the dark block.
+*
+* The shape of every branch is the same: an explicit override wins; otherwise
+* the preset's value stands *unless the anchor this token hangs off has moved*;
+* only then is anything derived.
+*/
+function resolveDark(anchors, preset) {
+	const colors = {};
+	const authored = /* @__PURE__ */ new Set();
+	const surfaces = anchors.surfaces ?? {};
+	const status = anchors.status ?? {};
+	/**
+	* One token. `derive` is omitted for the anchors themselves — a preset that
+	* declares no ground is not something to paper over with an invented one.
+	*/
+	const define = (token, explicit, moved, derive) => {
+		if (explicit !== void 0) {
+			readColor(explicit, token);
+			colors[token] = explicit;
+			return;
+		}
+		const inherited = lookup(preset, token);
+		if (!moved && inherited !== void 0) {
+			colors[token] = inherited;
+			authored.add(token);
+			return;
+		}
+		if (derive === void 0) throw new TypeError(`the base preset declares no ${token}`);
+		colors[token] = derive();
+	};
+	const groundMoved = anchors.bg !== void 0;
+	const inkMoved = anchors.fg !== void 0;
+	const accentMoved = anchors.accent !== void 0;
+	define("bg", anchors.bg, false);
+	const ground = readColor(colors["bg"], "bg");
+	define("sunken", surfaces.sunken, groundMoved, () => shift(ground, SUNKEN_LIGHTNESS_STEP));
+	SURFACES.forEach((token, index) => {
+		define(token, surfaces[token], groundMoved, () => shift(ground, SURFACE_LIGHTNESS_STEPS[index]));
+	});
+	define("fg", anchors.fg, false);
+	const ink = readColor(colors["fg"], "fg");
+	define("fg-muted", void 0, inkMoved, () => shift(ink, FG_MUTED_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE));
+	define("fg-subtle", void 0, inkMoved, () => shift(ink, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE ** 2));
+	define("border", void 0, groundMoved, () => shift(ground, BORDER_LIGHTNESS_STEPS[0]));
+	define("border-strong", void 0, groundMoved, () => shift(ground, BORDER_LIGHTNESS_STEPS[1]));
+	define("border-overlay", void 0, groundMoved, () => colors["border-strong"]);
+	define("accent", anchors.accent, false);
+	const accent = colors["accent"];
+	define("accent-hover", void 0, accentMoved, () => shift(readColor(accent, "accent"), ACCENT_HOVER_LIGHTNESS_STEP));
+	define("accent-fg", void 0, accentMoved, () => pickInk(accent, [colors["bg"], colors["fg"]]));
+	for (const tone of STATUSES) define(tone, status[tone], false);
+	define("selection", void 0, accentMoved, () => SELECTION_WASH);
+	define("focus", void 0, accentMoved, () => accent);
+	define("data-ground", void 0, false);
+	define("scrim", void 0, false);
+	return {
+		colors,
+		authored
+	};
+}
+/**
+* Resolve the light block.
+*
+* Per token: if the dark value came from the preset untouched and the preset
+* ships a light block, the authored light value stands. Everything else is
+* inverted — which is guesswork, and is why any derivation here marks the report
+* provisional.
+*
+* The inversion is not `1 − L` across the board. The ground goes to paper (see
+* {@link LIGHT_GROUND_COMPRESSION}) and the ladder then steps *down* from it,
+* because paper leaves no headroom above: a "raised" surface on a white page is
+* the slightly grey one, and the sunken well — the one rung that cannot keep its
+* sign — folds to the far end, which is still the deepest thing on the page.
+*/
+function resolveLight(dark, preset) {
+	const colors = {};
+	let provisional = false;
+	const define = (token, derive) => {
+		const inherited = dark.authored.has(token) ? lookup(preset, token) : void 0;
+		if (inherited !== void 0) {
+			colors[token] = inherited;
+			return;
+		}
+		colors[token] = derive();
+		provisional = true;
+	};
+	const darkGround = readColor(dark.colors["bg"], "bg");
+	define("bg", () => emit({
+		mode: "oklch",
+		l: clampLightness(1 - LIGHT_GROUND_COMPRESSION * darkGround.l),
+		c: darkGround.c,
+		h: darkGround.h
+	}));
+	const paper = readColor(colors["bg"], "bg");
+	/** Deepest rung: past the top surface by the sunken step. */
+	const sunkenDepth = (SURFACE_LIGHTNESS_STEPS.at(-1) ?? 0) + Math.abs(SUNKEN_LIGHTNESS_STEP);
+	define("sunken", () => shift(paper, -sunkenDepth));
+	SURFACES.forEach((token, index) => {
+		define(token, () => shift(paper, -SURFACE_LIGHTNESS_STEPS[index]));
+	});
+	const darkInk = readColor(dark.colors["fg"], "fg");
+	define("fg", () => emit({
+		mode: "oklch",
+		l: clampLightness(1 - darkInk.l),
+		c: darkInk.c,
+		h: darkInk.h
+	}));
+	const ink = readColor(colors["fg"], "fg");
+	define("fg-muted", () => shift(ink, .25, INK_RAMP_CHROMA_SCALE));
+	define("fg-subtle", () => shift(ink, .45, INK_RAMP_CHROMA_SCALE ** 2));
+	define("border", () => shift(paper, -BORDER_LIGHTNESS_STEPS[0]));
+	define("border-strong", () => shift(paper, -BORDER_LIGHTNESS_STEPS[1]));
+	define("border-overlay", () => colors["border-strong"]);
+	const paperGround = colors["bg"];
+	define("accent", () => darkenToContrast(dark.colors["accent"], paperGround, WCAG_AA_TEXT, "accent"));
+	const accent = colors["accent"];
+	define("accent-hover", () => shift(readColor(accent, "accent"), ACCENT_HOVER_LIGHTNESS_STEP));
+	define("accent-fg", () => pickInk(accent, [colors["bg"], colors["fg"]]));
+	for (const tone of STATUSES) define(tone, () => darkenToContrast(dark.colors[tone], paperGround, 3, tone));
+	define("selection", () => SELECTION_WASH);
+	define("focus", () => accent);
+	define("data-ground", () => dark.colors["data-ground"]);
+	define("scrim", () => dark.colors["scrim"]);
+	return {
+		colors,
+		provisional
+	};
+}
+/** The font declarations a theme block carries. */
+function resolveFonts(anchors, preset) {
+	const fonts = anchors.fonts ?? {};
+	const declared = [];
+	if (fonts.sans !== void 0) declared.push(["font-sans", fonts.sans]);
+	declared.push(["font-mono", fonts.mono ?? lookup(preset, "font-mono") ?? BASE_FONT_STACKS["font-mono"]]);
+	if (fonts.display !== void 0) declared.push(["font-display", fonts.display]);
+	return declared.map(([name, value]) => [tokenProperty(name), assertCssValue(name, value)]);
+}
+/** Round a product of two scales to something a stylesheet can print. */
+const scaled = (a, b) => String(Number((a * b).toFixed(4)));
+/**
+* The radius rules for a theme that asked for one.
+*
+* Geometry belongs to the density axis, so the multiplier is **crossed** with it
+* rather than declared flat: an uncrossed `--cue-radius-scale` in a theme block
+* outranks the density block that set it and would freeze `ultra-compact`'s 0.75
+* at 1. The base block carries the product for the default density — that is the
+* value an unstamped document falls back to — and every density whose own scale
+* differs gets one crossed rule.
+*/
+function radiusBlocks(name, radiusScale) {
+	const property = tokenProperty("radius-scale");
+	const fallback = DENSITY_RADIUS_SCALE[DEFAULT_DENSITY_LEVEL];
+	const blocks = [];
+	for (const [level, scale] of Object.entries(DENSITY_RADIUS_SCALE)) {
+		if (scale === fallback) continue;
+		blocks.push({
+			selector: themeSelector(name, { density: level }),
+			sections: [{ declarations: [[property, scaled(radiusScale, scale)]] }]
+		});
+	}
+	return {
+		base: [[property, scaled(radiusScale, fallback)]],
+		blocks
+	};
+}
+/** `[--cue-token, value]` pairs, in the order the contract lists them. */
+function colorDeclarations(colors) {
+	return THEME_COLOR_TOKENS.map((token) => [tokenProperty(token), colors[token]]);
+}
+const DERIVED_COMMENT = "derived — kept inside the block so color-mix() reads this theme's values";
+const FONT_COMMENT = "font — the theme's override, or the base stack restated";
+const SHAPE_COMMENT = "shape — crossed with the density ladder below, never flat";
+/**
+* Generate a theme: a stylesheet, its token map, and a contrast report.
+*
+* Pure and synchronous. Call it in a build script, in a test, or in the
+* configurator's export dialog — never in a render path, because there is
+* nothing here a stylesheet is not already doing faster.
+*
+* @param anchors - The name, the preset to start from, and whatever you moved.
+* @returns The stylesheet, the resolved tokens for both modes, and the report.
+* @throws TypeError if the name is not a CSS identifier, an anchor is not a
+*   colour, a font stack carries CSS punctuation, or the base preset is unknown.
+* @example
+* const { css, report } = createTheme({ name: "acme", base: "terminal", accent: "#ff8800" });
+* if (!report.passes) console.warn(report.failures);
+*/
+function createTheme(anchors) {
+	const name = assertThemeName(anchors.name);
+	const baseName = anchors.base ?? "cue";
+	const preset = THEME_PRESETS[baseName];
+	if (preset === void 0) throw new TypeError(`unknown base theme: ${JSON.stringify(baseName)}`);
+	if (anchors.radiusScale !== void 0 && !(anchors.radiusScale > 0)) throw new TypeError(`radiusScale must be a positive number, got ${anchors.radiusScale}`);
+	const dark = resolveDark(anchors, preset.dark);
+	const light = anchors.supportsLight ?? preset.light !== null ? resolveLight(dark, preset.light) : null;
+	const derived = Object.entries(derivedTokens());
+	const fonts = resolveFonts(anchors, preset.fonts);
+	const radius = anchors.radiusScale === void 0 ? null : radiusBlocks(name, anchors.radiusScale);
+	const darkSections = [
+		{ declarations: colorDeclarations(dark.colors) },
+		{
+			comment: DERIVED_COMMENT,
+			declarations: derived
+		},
+		{
+			comment: FONT_COMMENT,
+			declarations: fonts
+		},
+		...radius === null ? [] : [{
+			comment: SHAPE_COMMENT,
+			declarations: radius.base
+		}]
+	];
+	const blocks = [
+		{
+			selector: themeSelector(name),
+			colorScheme: "dark",
+			sections: darkSections
+		},
+		...light === null ? [] : [{
+			selector: themeSelector(name, { mode: "light" }),
+			colorScheme: "light",
+			sections: [{ declarations: colorDeclarations(light.colors) }, {
+				comment: DERIVED_COMMENT,
+				declarations: derived
+			}]
+		}],
+		...radius?.blocks ?? []
+	];
+	const inputs = [{
+		mode: "dark",
+		tokens: dark.colors
+	}, ...light === null ? [] : [{
+		mode: "light",
+		tokens: light.colors,
+		provisional: light.provisional
+	}]];
+	return {
+		name,
+		css: serializeThemeCss(blocks, { banner: `@cueplusplus/ui — theme "${name}"` }),
+		tokens: Object.fromEntries(darkSections.flatMap((section) => section.declarations)),
+		light: light === null ? null : Object.fromEntries([...colorDeclarations(light.colors), ...derived]),
+		report: contrastReport(inputs)
+	};
+}
+//#endregion
+export { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, DEFAULT_THEME_BASE, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, THEME_COLOR_TOKENS, createTheme };

package/dist/theming/index.d.ts

@@ -0,0 +1,5 @@
+import { CONTRAST_REQUIREMENTS, ContrastCheck, ContrastInput, ContrastReport, ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport, relativeLuminance } from "./contrast.js";
+import { THEME_COLOR_TOKENS, ThemeColorToken } from "./_presets.js";
+import { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, CreatedTheme, DEFAULT_THEME_BASE, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, ThemeAnchors, createTheme } from "./create-theme.js";
+import { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, SerializeThemeCssOptions, THEME_NAME_PATTERN, ThemeBlock, ThemeBlockSection, ThemeSelectorOptions, assertCssValue, assertThemeName, derivedTokens, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
+export { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, CONTRAST_REQUIREMENTS, CUE_TOKEN_PREFIX, type ContrastCheck, type ContrastInput, type ContrastReport, type ContrastRequirement, type CreatedTheme, DEFAULT_THEME_BASE, DERIVED_TOKEN_TEMPLATES, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, type SerializeThemeCssOptions, THEME_COLOR_TOKENS, THEME_NAME_PATTERN, type ThemeAnchors, type ThemeBlock, type ThemeBlockSection, type ThemeColorToken, type ThemeSelectorOptions, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, assertCssValue, assertThemeName, contrastRatio, contrastReport, createTheme, derivedTokens, relativeLuminance, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };

package/dist/theming/index.js

@@ -0,0 +1,5 @@
+import { THEME_COLOR_TOKENS } from "./_presets.js";
+import { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport, relativeLuminance } from "./contrast.js";
+import { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, THEME_NAME_PATTERN, assertCssValue, assertThemeName, derivedTokens, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty } from "./serialize.js";
+import { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, DEFAULT_THEME_BASE, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, createTheme } from "./create-theme.js";
+export { ACCENT_FG_MINIMUM, ACCENT_HOVER_LIGHTNESS_STEP, BORDER_LIGHTNESS_STEPS, CONTRAST_REQUIREMENTS, CUE_TOKEN_PREFIX, DEFAULT_THEME_BASE, DERIVED_TOKEN_TEMPLATES, FG_MUTED_LIGHTNESS_STEP, FG_SUBTLE_LIGHTNESS_STEP, INK_RAMP_CHROMA_SCALE, LIGHT_GROUND_COMPRESSION, SELECTION_ACCENT_PERCENT, SUNKEN_LIGHTNESS_STEP, SURFACE_LIGHTNESS_STEPS, THEME_COLOR_TOKENS, THEME_NAME_PATTERN, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, assertCssValue, assertThemeName, contrastRatio, contrastReport, createTheme, derivedTokens, relativeLuminance, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };

package/dist/theming/serialize.d.ts

@@ -0,0 +1,145 @@
+import { Density } from "@cueplusplus/tokens";
+//#region src/theming/serialize.d.ts
+/**
+ * Turning a resolved token map back into the stylesheet the tokens build would
+ * have written.
+ *
+ * This module exists so there is exactly **one** spelling of the output format.
+ * The spec's whole third-party theming story is "tier 2 always compiles down to
+ * tier 1" — a generated theme has to be indistinguishable from a hand-authored
+ * `[data-theme]` block, or a consumer ends up with two vocabularies and the
+ * generator becomes a toy. So the shapes below mirror `build.mjs` deliberately,
+ * comments included: same selector form, same declaration order, same section
+ * breaks. `test/theming/presets.test.ts` diffs the two.
+ *
+ * It is also the only place that touches raw strings, which makes it the place
+ * to stop injection. A theme name lands inside an attribute selector and a font
+ * stack lands inside a declaration; both are checked here rather than trusted.
+ */
+/** The one custom-property prefix this design system emits. */
+declare const CUE_TOKEN_PREFIX = "--cue-";
+/**
+ * What a theme may be called.
+ *
+ * The name is interpolated into `[data-theme="…"]`, so the pattern is a
+ * whitelist rather than an escape: a CSS identifier, which is also what a
+ * `data-theme` attribute is expected to hold and what a file called
+ * `<name>.css` can be named.
+ */
+declare const THEME_NAME_PATTERN: RegExp;
+/**
+ * Check a theme name and hand it back.
+ *
+ * @param name - The proposed theme name.
+ * @returns The same name, once it is known to be safe to interpolate.
+ * @throws TypeError if the name is not a CSS identifier.
+ * @example
+ * assertThemeName("acme-dark"); // → "acme-dark"
+ */
+declare function assertThemeName(name: string): string;
+/**
+ * Check a free-text declaration value and hand it back.
+ *
+ * @param name - The token the value belongs to, for the error message.
+ * @param value - The proposed value.
+ * @returns The same value, once it is known to stay inside its declaration.
+ * @throws TypeError if the value could end the declaration or the block.
+ * @example
+ * assertCssValue("font-mono", '"Berkeley Mono", monospace');
+ */
+declare function assertCssValue(name: string, value: string): string;
+/**
+ * The custom property a token is emitted as.
+ *
+ * Idempotent, so code that already holds `--cue-bg` can pass it straight back
+ * through instead of stripping the prefix first.
+ *
+ * @param name - A bare token name, or an already-prefixed property.
+ * @returns The `--cue-*` custom property name.
+ * @example
+ * tokenProperty("surface-1"); // → "--cue-surface-1"
+ */
+declare function tokenProperty(name: string): string;
+interface ThemeSelectorOptions {
+  /** Cross with the mode axis. Only `"light"` needs a selector; dark is the base block. */
+  mode?: "dark" | "light";
+  /** Cross with the density axis. Used only for the radius multiplier. */
+  density?: Density;
+}
+/**
+ * The selector a theme's declarations live under.
+ *
+ * Attribute selectors, not classes, because the two axes have to compose: a
+ * `[data-theme]` on the root and another on a portal, a `[data-mode]` crossed
+ * over either, all at the same specificity so later blocks win predictably.
+ *
+ * @param name - The theme name. Not re-checked — {@link assertThemeName} owns that.
+ * @param options - Which axes to cross with.
+ * @returns The CSS selector.
+ * @example
+ * themeSelector("acme", { mode: "light" }); // → '[data-theme="acme"][data-mode="light"]'
+ */
+declare function themeSelector(name: string, options?: ThemeSelectorOptions): string;
+/**
+ * The derived colours every theme block carries, as `[token, value]` pairs.
+ *
+ * They are `color-mix()` expressions over `var(--cue-*)` rather than resolved
+ * literals, and they are emitted **inside** the theme block rather than once on
+ * `:root`, for the same reason the build does it: a custom property's `var()`
+ * references are substituted at the element that declares it, so a `:root`-level
+ * mix would freeze the default theme's accent into every nested theme.
+ */
+declare const DERIVED_TOKEN_TEMPLATES: ReadonlyArray<readonly [string, string]>;
+/**
+ * {@link DERIVED_TOKEN_TEMPLATES} as a property → value map.
+ *
+ * @returns The eleven derived declarations, keyed by custom property.
+ * @example
+ * derivedTokens()["--cue-accent-soft"];
+ */
+declare function derivedTokens(): Record<string, string>;
+/** One run of declarations, optionally introduced by a comment. */
+interface ThemeBlockSection {
+  /** Comment printed above the run. Omit on the first section. */
+  comment?: string;
+  /** `[property, value]` pairs, in emission order. */
+  declarations: ReadonlyArray<readonly [string, string]>;
+}
+/** One CSS rule of a generated theme. */
+interface ThemeBlock {
+  /** The selector the rule declares under. */
+  selector: string;
+  /** Emitted as `color-scheme`, ahead of the custom properties. Omit to skip it. */
+  colorScheme?: "dark" | "light";
+  /** The declarations, grouped into commented sections. */
+  sections: readonly ThemeBlockSection[];
+}
+/**
+ * One rule, printed.
+ *
+ * Empty sections vanish rather than leaving a comment with nothing under it —
+ * which is what makes "emit the fonts section only if there are fonts" a
+ * data decision instead of a branch at every call site.
+ *
+ * @param block - Selector, colour scheme and sections.
+ * @returns The rule, without a trailing newline.
+ * @example
+ * serializeThemeBlock({ selector: ":root", sections: [{ declarations: [["--cue-bg", "#000"]] }] });
+ */
+declare function serializeThemeBlock(block: ThemeBlock): string;
+interface SerializeThemeCssOptions {
+  /** Text of the leading `/*! … *\/` banner. Omit for a bare stylesheet. */
+  banner?: string;
+}
+/**
+ * A whole generated stylesheet: banner, then one rule per block.
+ *
+ * @param blocks - The rules, in cascade order — later blocks win ties.
+ * @param options - Banner text.
+ * @returns The stylesheet, newline-terminated.
+ * @example
+ * serializeThemeCss(blocks, { banner: "@cueplusplus/ui — createTheme()" });
+ */
+declare function serializeThemeCss(blocks: readonly ThemeBlock[], options?: SerializeThemeCssOptions): string;
+//#endregion
+export { CUE_TOKEN_PREFIX, DERIVED_TOKEN_TEMPLATES, SerializeThemeCssOptions, THEME_NAME_PATTERN, ThemeBlock, ThemeBlockSection, ThemeSelectorOptions, assertCssValue, assertThemeName, derivedTokens, serializeThemeBlock, serializeThemeCss, themeSelector, tokenProperty };