@cueplusplus/ui 0.8.0 → 0.10.0

package/dist/system/use-density.js

@@ -1,12 +1,23 @@
 "use client";
 import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
-import { DensityContext } from "./density.js";
+import { DEFAULT_DENSITY, DensityContext } from "./density.js";
+import { warnOnce } from "./vocabulary.js";
+import { ThemeRegistryContext } from "./theme-registry.js";
+import { ThemeContext } from "./theme-provider.js";
 import * as React from "react";
 //#region src/system/use-density.ts
 /**
-* The control ladder in rem, mirroring `packages/tokens/src/density/*.tokens.json`.
-* Only a fallback: {@link useControlHeight} measures the live CSS first, so
-* per-app token overrides and the `@media (pointer: coarse)` re-raise win.
+* The **base** control ladder in rem, mirroring
+* `packages/tokens/src/density/*.tokens.json`.
+*
+* Keyed by `BaseDensity` — the closed five — and not by the open `Density`,
+* because those five are the only rungs this package can know at build time. A
+* rung a theme adds exists nowhere in `ui`'s source; it arrives at runtime on a
+* manifest, and {@link ladderFor} is what goes and gets it.
+*
+* Only a fallback either way: {@link useControlHeight} measures the live CSS
+* first, so per-app token overrides and the `@media (pointer: coarse)` re-raise
+* win.
 */
 const CONTROL_REM = {
 	"ultra-compact": {
@@ -37,16 +48,112 @@ const CONTROL_REM = {
 };
 /** Root font size assumed before the first measurement, so SSR and hydration agree. */
 const ASSUMED_ROOT_FONT_SIZE = 16;
+/** The three tokens the ladder is made of, in the order a warning should name them. */
+const CONTROL_TOKENS = [
+	"control-sm",
+	"control-md",
+	"control-lg"
+];
+/**
+* A `"1.25rem"` geometry value as a number of rem, or `null`.
+*
+* `null` rather than a throw, and rem rather than any length, because the three
+* `control-*` tokens are rem *by convention*: `validateManifest` requires only a
+* non-empty string, and the base geometry block itself ships `radius-control:
+* "3px"`, so a manifest that passes validation can perfectly well carry a value
+* this cannot use. See {@link ladderFor} for what happens then.
+*
+* Strictly positive, too. `"0rem"` and `"-1rem"` parse perfectly well and are
+* not control heights: a virtualiser handed a row height of zero divides by it
+* or renders every row in the list, and a negative one is not a height at all.
+* Both are manifest defects, and a defect is better reported than propagated.
+*/
+function rem(value) {
+	if (value === void 0) return null;
+	const match = /^(-?\d*\.?\d+)rem$/.exec(value.trim());
+	if (match === null) return null;
+	const parsed = Number.parseFloat(match[1]);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+/**
+* The rem ladder for a rung: the base table, else the registry, else a warning.
+*
+* The registry is the only place an added rung's geometry exists on the client.
+* The stylesheet has it — `theme-tools` emitted a `[data-theme="foo"]
+* [data-density="foo-dense"]` block for it — but CSS is not readable as data
+* before layout, and this value is needed by a `useState` initializer, which is
+* the one moment nothing has been laid out yet.
+*
+* Every failure degrades rather than throws, and the reason is that this runs
+* during render from a `useState` initializer with no error boundary anywhere
+* near it: a throw there unmounts the application, in production, over a
+* pre-measurement seed. And the seed really is only a seed — the added rung's
+* CSS exists whatever this returns, so the layout effect's probe measures the
+* true height one tick later and the fallback is visible for one commit. A
+* `control-*` rem rule in `validateManifest` is what would make this
+* impossible, and that is a Plan 4 carry.
+*/
+function ladderFor(registry, density) {
+	const base = CONTROL_REM[density];
+	if (base !== void 0) return base;
+	const added = registry?.densities.find((d) => d.name === density)?.geometry;
+	if (added !== void 0) {
+		const ladder = {
+			sm: rem(added["control-sm"]),
+			md: rem(added["control-md"]),
+			lg: rem(added["control-lg"])
+		};
+		if (ladder.sm !== null && ladder.md !== null && ladder.lg !== null) return ladder;
+		const offender = CONTROL_TOKENS.find((token) => rem(added[token]) === null);
+		warnOnce(`density "${density}" declares ${offender} as ${JSON.stringify(added[offender])}, which is not a positive rem length; the ${DEFAULT_DENSITY} ladder seeds the measurement instead`);
+		return CONTROL_REM[DEFAULT_DENSITY];
+	}
+	warnOnce(`density "${density}" is not a base rung and no registered theme adds it; the ${DEFAULT_DENSITY} ladder is used until the probe measures it`);
+	return CONTROL_REM[DEFAULT_DENSITY];
+}
 function rootFontSize() {
 	if (typeof document === "undefined") return ASSUMED_ROOT_FONT_SIZE;
 	const size = Number.parseFloat(getComputedStyle(document.documentElement).fontSize);
 	return Number.isFinite(size) && size > 0 ? size : ASSUMED_ROOT_FONT_SIZE;
 }
-function measureControlHeight(density, size) {
-	const fallback = CONTROL_REM[density][size] * rootFontSize();
+/**
+* Measure `--cue-control-<size>` on a throwaway element stamped like the caller.
+*
+* `theme` as well as `density`, because a rung a theme adds is emitted under
+* that theme's `[data-theme]`: a bare `data-density` div on `document.body`
+* matches the **root** theme's rules, so under a nested provider of another
+* theme it would measure a ladder the caller is not on. `null` stamps nothing,
+* which is right for a caller with no provider above it at all.
+*
+* `data-cue-theme` rides beside `data-theme`, both from the same value: an
+* inert attribute nothing here reads back, but the emitters' exact-match
+* selector does — see `densityRules`/`themeSelector`'s comment on why a CSS
+* ancestor guard alone cannot tell *nearest* theme from *any* theme in the
+* chain, and how a runtime-published stamp closes that where the DOM shape
+* lets it.
+*
+* `ladder` is passed in rather than looked up here so that both reads — this
+* one and the state seed — go through {@link ladderFor} exactly once each, and
+* so this stays a plain function that a test can reason about without a tree.
+*
+* What this element cannot see is the standing concession of the whole
+* approach, and it is worth naming where it is caused rather than where it is
+* felt: hanging off `document.body` puts the probe outside every provider
+* root, so a rule scoped under `[data-cue-root]` does not reach it. That is the
+* reason the provider's density override layer is emitted as one
+* document-scoped `<style>` instead — a subtree-scoped rule would leave this
+* measuring unoverridden geometry while the control beside it rendered the
+* override, and the two would disagree by exactly the override.
+*/
+function measureControlHeight(ladder, density, theme, size) {
+	const fallback = ladder[size] * rootFontSize();
 	if (typeof document === "undefined" || document.body === null) return fallback;
 	const probe = document.createElement("div");
 	probe.setAttribute("data-density", density);
+	if (theme !== null) {
+		probe.setAttribute("data-theme", theme);
+		probe.setAttribute("data-cue-theme", theme);
+	}
 	probe.setAttribute("aria-hidden", "true");
 	probe.style.cssText = `position:absolute;top:-9999px;left:-9999px;width:0;visibility:hidden;pointer-events:none;height:var(--cue-control-${size})`;
 	document.body.appendChild(probe);
@@ -81,10 +188,18 @@ function useDensity() {
 * canvas renderer needs when it cannot ask CSS.
 *
 * Measured from a throwaway `document.body` probe stamped with the ambient
-* density, so app-wide token overrides and the `@media (pointer: coarse)`
-* re-raise of `ultra-compact` are honoured (overrides scoped to a subtree the
-* probe is not in are not). Falls back to the authored ladder × 16px during SSR
-* and before the first layout effect, which keeps hydration stable.
+* density *and the ambient theme*, so app-wide token overrides, the `@media
+* (pointer: coarse)` re-raise of `ultra-compact`, and a rung a theme adds are
+* all honoured. Overrides scoped to a subtree the probe is not in are still
+* not: the probe hangs off `document.body`, outside every provider root.
+*
+* Falls back to the authored ladder × 16px during SSR and before the first
+* layout effect, which keeps hydration stable. A rung the ambient theme does
+* not declare falls back to the default ladder with a development warning
+* rather than throwing — the probe corrects it on the next tick either way.
+*
+* Safe outside a `<ThemeProvider>`: it reads the theme and the registry from
+* context directly instead of through `useTheme()`, which throws.
 *
 * @param size - Which rung to measure. Defaults to `"md"`.
 * @returns Height in CSS pixels.
@@ -93,10 +208,24 @@ function useDensity() {
 */
 function useControlHeight(size = "md") {
 	const density = useDensity();
-	const [height, setHeight] = React.useState(() => CONTROL_REM[density][size] * ASSUMED_ROOT_FONT_SIZE);
+	const theme = React.useContext(ThemeContext)?.theme ?? null;
+	const ladder = ladderFor(React.useContext(ThemeRegistryContext), density);
+	const { sm, md, lg } = ladder;
+	const [height, setHeight] = React.useState(() => ladder[size] * ASSUMED_ROOT_FONT_SIZE);
 	useIsomorphicLayoutEffect(() => {
-		setHeight(measureControlHeight(density, size));
-	}, [density, size]);
+		setHeight(measureControlHeight({
+			sm,
+			md,
+			lg
+		}, density, theme, size));
+	}, [
+		sm,
+		md,
+		lg,
+		density,
+		theme,
+		size
+	]);
 	return height;
 }
 //#endregion

package/dist/system/use-theme.d.ts

@@ -3,12 +3,14 @@ import { ThemeContextValue } from "./theme-provider.js";
 /**
  * Read and drive the ambient theme state.
  *
- * Returns `{ theme, density, mode, font, resolvedMode, setTheme, setDensity,
- * setMode, setFont }`.
+ * Returns `{ theme, manifest, density, mode, font, resolvedMode, setTheme,
+ * setDensity, setMode, setFont }`.
  * `density` here is the *provider's* level — a nested `<Density>` island does not
  * change it; use `useDensity()` when you want the level that actually applies
  * where you are. `font` is the pairing the provider holds; it has no island, so
- * it is always the one in force.
+ * it is always the one in force. `manifest` is the active theme's, or `null`
+ * when that name is not in the provider's `themes` — which is every name in an
+ * app that has registered none; `useThemes()` is what was registered.
  *
  * @throws If called outside a `<ThemeProvider>`. Theme state is never guessed:
  *   a missing provider is a wiring bug, not a fallback situation.

package/dist/system/use-theme.js

@@ -5,12 +5,14 @@ import * as React from "react";
 /**
 * Read and drive the ambient theme state.
 *
-* Returns `{ theme, density, mode, font, resolvedMode, setTheme, setDensity,
-* setMode, setFont }`.
+* Returns `{ theme, manifest, density, mode, font, resolvedMode, setTheme,
+* setDensity, setMode, setFont }`.
 * `density` here is the *provider's* level — a nested `<Density>` island does not
 * change it; use `useDensity()` when you want the level that actually applies
 * where you are. `font` is the pairing the provider holds; it has no island, so
-* it is always the one in force.
+* it is always the one in force. `manifest` is the active theme's, or `null`
+* when that name is not in the provider's `themes` — which is every name in an
+* app that has registered none; `useThemes()` is what was registered.
 *
 * @throws If called outside a `<ThemeProvider>`. Theme state is never guessed:
 *   a missing provider is a wiring bug, not a fallback situation.

package/dist/system/vocabulary.d.ts

@@ -0,0 +1,15 @@
+import { Density, DensityEntry, FontEntry, FontName, ThemeManifest } from "@cueplusplus/theme-base";
+//#region src/system/vocabulary.d.ts
+/** What the three registry hooks read: the manifests, and the axes the ACTIVE theme offers. */
+interface ThemeRegistry {
+  /** Every registered manifest, in registration order. */
+  readonly themes: readonly ThemeManifest[];
+  /** First registered manifest's name, or `null` with nothing registered. */
+  readonly defaultTheme: string | null;
+  /** The rungs the ACTIVE theme offers: base five, then its adds. */
+  readonly densities: readonly DensityEntry[];
+  /** The pairings the ACTIVE theme offers, by the same rule. */
+  readonly fonts: readonly FontEntry[];
+}
+//#endregion
+export { ThemeRegistry };

package/dist/system/vocabulary.js

@@ -0,0 +1,111 @@
+import { DEFAULT_DENSITY, DEFAULT_FONT } from "@cueplusplus/tokens";
+import { DENSITIES, FONTS, THEME_NAME_PATTERN, resolveDensities, resolveFonts } from "@cueplusplus/theme-base";
+//#region src/system/vocabulary.ts
+/**
+* The registry's pure half: what a set of manifests accepts, and what an app
+* may offer under one of them.
+*
+* No `"use client"` and no React, on purpose. `prepaint.ts` is server-safe by
+* contract — the docs app's root layout is a Server Component and calls
+* `prepaintScript()` during render — and it reaches this module to inline the
+* vocabulary into the blocking script. A module reached through a client
+* boundary arrives in a server graph as a client *reference* rather than a
+* function, and calling one throws at prerender. So the pure half lives here,
+* directive-free, and `theme-registry.tsx` holds the context and the hooks and
+* re-exports this file so the barrel still has one source.
+* `test/system/server-safe.test.ts` holds this file, and every file
+* `prepaint.ts` reaches, to that rule.
+*/
+/**
+* What each axis accepts, and the one place that is decided.
+*
+* Six code paths validated a name before this existed — three against a frozen
+* list from `@cueplusplus/tokens`, two against local copies, one against
+* nothing at all — and they disagreed with each other at the edges. They all
+* ask this now, so a stored preference means the same thing to the pre-paint
+* script, the restore effect, and a portal.
+*
+* An empty registry is the deliberate case, not the degenerate one: an app that
+* registers nothing has the base axes and no registry, and for one release that
+* is every app that has not migrated — this repository's own docs site
+* included. (It does not follow that such an app is unpainted: a stylesheet it
+* imported may well declare the block the provider stamps. Colour is a question
+* for CSS; this file only decides what a name is allowed to be.) Refusing every theme name there would reject a visitor's stored
+* preference on first paint. So with nothing registered, theme validation is
+* *off* (any name the selector grammar allows), and density and font validate
+* against the base ladder and pairings alone. A registered set closes all
+* three: only registered themes, and a theme's added rung or pairing only under
+* that theme, which is what the cascade actually scopes it to.
+*
+* The order matters wherever a whole stored quadruple is read: resolve the
+* theme first, then each axis under the theme resolution chose. See
+* `acceptedPreferences()` in `theme-provider.tsx`, which is the one place that
+* rule is applied, and the pre-paint script, which applies it the same way.
+*/
+function vocabulary(themes) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const manifest of themes) if (!byName.has(manifest.name)) byName.set(manifest.name, manifest);
+	const names = themes.length === 0 ? null : [...byName.keys()];
+	const densitiesFor = (theme) => [...DENSITIES, ...Object.keys((theme === null ? void 0 : byName.get(theme))?.densities.adds ?? {})];
+	const fontsFor = (theme) => [...FONTS, ...Object.keys((theme === null ? void 0 : byName.get(theme))?.fontPairings.adds ?? {})];
+	const preferredDensity = (theme) => {
+		const wanted = (theme === null ? void 0 : byName.get(theme))?.densities.default;
+		return wanted !== void 0 && densitiesFor(theme).includes(wanted) ? wanted : DEFAULT_DENSITY;
+	};
+	const preferredFont = (theme) => {
+		const wanted = (theme === null ? void 0 : byName.get(theme))?.fontPairings.default;
+		return wanted !== void 0 && fontsFor(theme).includes(wanted) ? wanted : DEFAULT_FONT;
+	};
+	return {
+		themes: names,
+		densitiesFor,
+		fontsFor,
+		preferredDensity,
+		preferredFont,
+		acceptsTheme: (name) => typeof name === "string" && (names === null ? THEME_NAME_PATTERN.test(name) : names.includes(name)),
+		acceptsDensity: (theme, name) => typeof name === "string" && densitiesFor(theme).includes(name),
+		acceptsFont: (theme, name) => typeof name === "string" && fontsFor(theme).includes(name),
+		supportsLight: (theme) => theme === null ? true : byName.get(theme)?.supportsLight ?? true
+	};
+}
+/** Derive the context value. Pure; the provider memoises it on `themes` and the active name. */
+function buildRegistry(themes, active) {
+	return {
+		themes,
+		defaultTheme: themes[0]?.name ?? null,
+		densities: resolveDensities(themes, active),
+		fonts: resolveFonts(themes, active)
+	};
+}
+const seen = /* @__PURE__ */ new Set();
+/**
+* A development warning, once per distinct message per process.
+*
+* Once, because the things this warns about — a `themes` prop nobody passed, a
+* rung a theme does not offer — are configuration, and configuration is wrong
+* the same way on every render. A warning per render is a warning nobody reads,
+* and fourteen provider tests would otherwise be fourteen copies of one line.
+*/
+function warnOnce(message) {
+	if (process.env.NODE_ENV === "production" || seen.has(message)) return;
+	seen.add(message);
+	console.warn(`[cue] ${message}`);
+}
+/**
+* {@link warnOnce}, one tier quieter.
+*
+* `contrastReport()` keeps two lists on purpose — a *failure* is what makes a
+* screen unreadable, an *advisory* is a focus ring nobody has been failed on
+* yet — and folding the second into `console.warn` would either train a reader
+* to ignore the first or push a repository to turn both off. They share the
+* `seen` set so "once per distinct message" is one budget and `resetWarnings()`
+* clears both; the two message texts cannot collide, since a failure and an
+* advisory for one pair say different things about it.
+*/
+function noteOnce(message) {
+	if (process.env.NODE_ENV === "production" || seen.has(message)) return;
+	seen.add(message);
+	console.info(`[cue] ${message}`);
+}
+//#endregion
+export { buildRegistry, noteOnce, vocabulary, warnOnce };

package/dist/theming/contrast.d.ts

@@ -1,122 +1,2 @@
-//#region src/theming/contrast.d.ts
-/** Non-text and large-text AA: UI components, graphics, status dots. */
-declare const WCAG_AA_NON_TEXT = 3;
-/** Body-text AA. The floor for anything a reader is expected to read. */
-declare const WCAG_AA_TEXT = 4.5;
-/** Body-text AAA. What this portfolio holds its primary ink to. */
-declare const WCAG_AAA_TEXT = 7;
-/**
- * WCAG relative luminance: 0 for black, 1 for white.
- *
- * Alpha is ignored — a translucent colour has no luminance of its own, only one
- * in front of something. {@link contrastRatio} is where that composite happens.
- *
- * @param color - Any CSS colour string.
- * @returns Relative luminance in `[0, 1]`.
- * @throws TypeError if the value is not a colour.
- * @example
- * relativeLuminance("#767676"); // → 0.1845…
- */
-declare function relativeLuminance(color: string): number;
-/**
- * WCAG contrast ratio between two colours, from 1:1 to 21:1.
- *
- * Symmetric, because a ratio has no direction — the arguments are named for
- * readability, not for order. A **translucent foreground is composited over the
- * background first**, which is not decoration: half this system's `fg-muted`
- * tokens are white-alpha ink, and measuring them raw would report the ratio of
- * pure white and pass everything.
- *
- * @param foreground - The ink. Composited over `background` if it has alpha.
- * @param background - The ground. Its own alpha is ignored — nothing is behind it.
- * @returns The ratio, `>= 1`.
- * @throws TypeError naming whichever value could not be read.
- * @example
- * contrastRatio("#767676", "#ffffff"); // → 4.5422…
- */
-declare function contrastRatio(foreground: string, background: string): number;
-/** One pair a theme is checked on. */
-interface ContrastRequirement {
-  /** `"<foreground>/<background>"` — stable, and readable in a failure message. */
-  id: string;
-  /** Bare token name of the ink. */
-  foreground: string;
-  /** Bare token name of the ground. */
-  background: string;
-  /** The ratio the pair has to reach. */
-  minimum: number;
-  /** Why this minimum, in one line — the configurator surfaces it. */
-  reason: string;
-}
-/**
- * The eleven pairs that decide whether a theme is usable.
- *
- * Not every pair in the palette: the ones a reader's comprehension actually
- * depends on. Primary ink is held to AAA because it carries the prose; secondary
- * ink and accent ink to AA because they carry labels; the five status colours
- * and the live hue to the non-text AA floor because they are read as *signals*
- * — a dot, a rim, a bar — never as body copy.
- *
- * `danger` and `warn` each appear twice, and they are the only tones that do.
- * `ok`, `busy`, `info` and `stream` are *only* ever signals, so the non-text
- * floor is the whole truth about them. The red and the amber are also grounds:
- * they are the two tones this system fills a control with, and what they fill is
- * the confirm on something irreversible and the confirm on something merely
- * consequential. Text on either fill is text, so its ink is held to the text
- * floor against the tone it sits on rather than against the page.
- *
- * `stream` is measured for the same reason `ok` is: `createTheme()` darkens it
- * to this floor when it has to invent a light block, and a report that did not
- * check what the derivation targets would be checking the wrong thing.
- */
-declare const CONTRAST_REQUIREMENTS: readonly ContrastRequirement[];
-/** One measured pair. */
-interface ContrastCheck extends ContrastRequirement {
-  /** Which block the pair was measured in. */
-  mode: "dark" | "light";
-  /** The colour the foreground token resolved to. */
-  foregroundValue: string;
-  /** The colour the background token resolved to. */
-  backgroundValue: string;
-  /** The measured ratio. */
-  ratio: number;
-  /** Whether {@link ContrastRequirement.minimum} was reached. */
-  passes: boolean;
-  /** Whether the values were derived rather than authored — see the light variant. */
-  provisional: boolean;
-}
-/** One block's worth of resolved colours. */
-interface ContrastInput {
-  /** Which block these are. */
-  mode: "dark" | "light";
-  /** Bare token name → resolved CSS colour. Pairs with a missing token are skipped. */
-  tokens: Readonly<Record<string, string>>;
-  /** Mark the resulting checks provisional. Defaults to `false`. */
-  provisional?: boolean;
-}
-/** Every pair, measured, plus the verdict. */
-interface ContrastReport {
-  /** True when nothing failed. */
-  passes: boolean;
-  /** True when any measured block was derived rather than authored. */
-  provisional: boolean;
-  /** Every pair that could be measured, in requirement order, dark block first. */
-  checks: readonly ContrastCheck[];
-  /** The subset that failed. Empty when {@link ContrastReport.passes}. */
-  failures: readonly ContrastCheck[];
-}
-/**
- * Measure every requirement against every block handed in.
- *
- * A pair whose tokens are missing is **skipped**, not failed: the report says
- * what it measured, and a caller checking a partial palette should not be told
- * that a colour it never supplied is unreadable.
- *
- * @param inputs - One entry per block, dark first by convention.
- * @returns The report.
- * @example
- * contrastReport([{ mode: "dark", tokens: { fg: "#fff", bg: "#000" } }]).passes; // → true
- */
-declare function contrastReport(inputs: readonly ContrastInput[]): ContrastReport;
-//#endregion
-export { CONTRAST_REQUIREMENTS, ContrastCheck, ContrastInput, ContrastReport, ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport, relativeLuminance };
+import { CONTRAST_REQUIREMENTS, ContrastCheck, ContrastInput, ContrastReport, ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport as contrastReport$1, relativeLuminance } from "@cueplusplus/theme-base/contrast";
+export { CONTRAST_REQUIREMENTS, type ContrastCheck, type ContrastInput, type ContrastReport, type ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport$1 as contrastReport, relativeLuminance };