@cueplusplus/ui 0.8.0 → 0.10.0

package/dist/system/prepaint.js

@@ -1,9 +1,20 @@
-import { DEFAULT_DENSITY, DEFAULT_FONT, DENSITIES, FONTS, MODES, THEMES } from "@cueplusplus/tokens";
+import { vocabulary } from "./vocabulary.js";
+import { DEFAULT_DENSITY, DEFAULT_FONT } from "@cueplusplus/tokens";
+import { MODES } from "@cueplusplus/theme-base";
 //#region src/system/prepaint.ts
 /**
 * Pre-paint stamping. Server-safe by design: no `"use client"`, no React, no
 * DOM access at module scope — `app/layout.tsx` calls `prepaintScript()` on the
 * server and inlines the result before hydration.
+*
+* That is also why the vocabulary comes from `./vocabulary` and never from
+* `./theme-registry`: the registry's React half carries a `"use client"`
+* directive, and a module reached through a client boundary arrives in a server
+* graph as a client *reference* rather than a function — calling one throws at
+* prerender, in the app's root layout, where nothing has rendered yet.
+* `test/system/server-safe.test.ts` pins the exact set of files this one
+* reaches, so the next import that would break the rule fails a test instead of
+* a deployment.
 */
 /** localStorage key the ThemeProvider and the pre-paint script share by default. */
 const DEFAULT_STORAGE_KEY = "cue-ui";
@@ -22,39 +33,80 @@ function prepaintScript(storageKeyOrOptions = DEFAULT_STORAGE_KEY, defaultTheme
 		defaults: {
 			theme: defaultTheme,
 			density: defaultDensity,
-			mode: "dark"
+			mode: "dark",
+			font: defaultFont
 		},
 		readStoredPreferences: true
 	} : storageKeyOrOptions;
-	if (options === null || typeof options !== "object" || options.defaults === void 0) throw new TypeError("prepaintScript options require a complete default triple");
+	if (options === null || typeof options !== "object" || options.defaults === void 0) throw new TypeError("prepaintScript options require a defaults object with theme and mode");
 	const defaults = options.defaults;
-	if (defaults.theme === void 0 || defaults.density === void 0 || defaults.mode === void 0) throw new TypeError("prepaintScript options require a complete default triple");
-	if (!THEMES.includes(defaults.theme)) throw new TypeError("prepaintScript defaults contain an invalid theme");
-	if (!DENSITIES.includes(defaults.density)) throw new TypeError("prepaintScript defaults contain an invalid density");
-	if (!MODES.includes(defaults.mode)) throw new TypeError("prepaintScript defaults contain an invalid mode");
-	if (defaults.font !== void 0 && !FONTS.includes(defaults.font)) throw new TypeError("prepaintScript defaults contain an invalid font");
+	if (defaults.theme === void 0 || defaults.mode === void 0) throw new TypeError("prepaintScript options require defaults.theme and defaults.mode");
+	const vocab = vocabulary(options.themes ?? []);
+	if (!vocab.acceptsTheme(defaults.theme)) throw new TypeError(vocab.themes === null ? `prepaintScript defaults.theme ${JSON.stringify(defaults.theme)} is not a valid theme name` : `prepaintScript defaults.theme ${JSON.stringify(defaults.theme)} is not a registered theme`);
+	if (defaults.density !== void 0 && !vocab.acceptsDensity(defaults.theme, defaults.density)) throw new TypeError(`prepaintScript defaults.density ${JSON.stringify(defaults.density)} is not offered by theme ${JSON.stringify(defaults.theme)}`);
+	if (!MODES.includes(defaults.mode)) throw new TypeError(`prepaintScript defaults.mode ${JSON.stringify(defaults.mode)} is not one of ${MODES.join(", ")}`);
+	if (defaults.font !== void 0 && !vocab.acceptsFont(defaults.theme, defaults.font)) throw new TypeError(`prepaintScript defaults.font ${JSON.stringify(defaults.font)} is not offered by theme ${JSON.stringify(defaults.theme)}`);
 	if (options.readStoredPreferences !== void 0 && typeof options.readStoredPreferences !== "boolean") throw new TypeError("prepaintScript readStoredPreferences must be boolean");
 	const storageKey = options.storageKey ?? "cue-ui";
 	if (typeof storageKey !== "string") throw new TypeError("prepaintScript storageKey must be a string");
 	const readStoredPreferences = options.readStoredPreferences ?? true;
 	const key = jsStringLiteral(storageKey);
 	const fallbackTheme = jsStringLiteral(defaults.theme);
-	const fallbackDensity = jsStringLiteral(defaults.density);
+	const fallbackDensity = jsStringLiteral(defaults.density ?? vocab.preferredDensity(defaults.theme));
 	const fallbackMode = jsStringLiteral(defaults.mode);
-	const fallbackFont = jsStringLiteral(defaults.font ?? defaultFont);
-	const themes = scriptSafe(JSON.stringify([...THEMES]));
-	const densities = scriptSafe(JSON.stringify([...DENSITIES]));
-	const modes = scriptSafe(JSON.stringify([...MODES]));
+	const fallbackFont = jsStringLiteral(defaults.font ?? vocab.preferredFont(defaults.theme));
+	const baseDensity = jsStringLiteral(DEFAULT_DENSITY);
+	const baseFont = jsStringLiteral(DEFAULT_FONT);
+	/**
+	* The registered names, or `null`.
+	*
+	* `null` tells the script "any well-formed name", which is the empty-registry
+	* rule (see `vocabulary`) and is what the positional overload — every app
+	* that has not migrated — gets. Anything else is the exact list the provider
+	* will validate against a moment later, inlined so the two cannot disagree.
+	*/
+	const themes = scriptSafe(JSON.stringify(vocab.themes));
 	/**
-	* The pairings, from the package that authors them, for the same reason.
+	* The other two axes, `supportsLight`, and each theme's own preference, **per theme**.
 	*
-	* This is also the axis where an unvalidated read is worst: a stale or
-	* hand-edited `font` would stamp an attribute the stylesheet has no block
-	* for, `--cue-font-sans` would keep the base stack, and the page would render
-	* in a family the picker says is not selected.
+	* Per theme, because a rung a theme adds is scoped by the cascade to that
+	* theme's `data-theme`; accepting it under another theme stamps an attribute
+	* no block will match, and the page renders at the rung it fell back from
+	* while the picker says otherwise. The keys are short (`d`, `f`, `l`, `p`,
+	* `q`) because this is inlined into every document this app serves, once per
+	* response, and with ten themes registered the long names would cost more
+	* bytes than the whole rest of the script.
+	*
+	* `p` and `q` are §5's `densities.default` / `fontPairings.default` — the
+	* rung and the pairing that theme prefers when nobody named one — read
+	* through `vocabulary()`, which is the same function `acceptedPreferences()`
+	* asks on the client. Two implementations of one rule, one of them written
+	* out as a string of JavaScript, is exactly the asymmetry the round-trip
+	* tests exist to catch; inlining the *answers* rather than re-deriving them
+	* is what makes the two sides agree by construction.
+	*
+	* They are omitted when they equal the base default, which is what every one
+	* of the ten shipped presets does — none of them declares either. The final
+	* clause already ends at the base literal, so an entry that repeats it is
+	* bytes in every response that change no answer. `a.p&&…` below is what
+	* reads an absent key as "no opinion".
+	*
+	* With nothing registered there is one entry under the empty key: the base
+	* ladder, the base pairings, and a light block, which the blank base has.
 	*/
-	const pairings = scriptSafe(JSON.stringify([...FONTS]));
-	return `!function(){try{var k=${key},e=document.documentElement,s=null;` + (readStoredPreferences ? "try{var r=localStorage.getItem(k);s=r?JSON.parse(r):null}catch(_){}" : "") + `s=s&&typeof s=="object"?s:{};var t=${themes}.indexOf(s.theme)>-1?s.theme:${fallbackTheme};var d=${densities}.indexOf(s.density)>-1?s.density:${fallbackDensity};var f=${pairings}.indexOf(s.font)>-1?s.font:${fallbackFont};var m=${modes}.indexOf(s.mode)>-1?s.mode:${fallbackMode};e.setAttribute("data-theme",t);e.setAttribute("data-density",d);e.setAttribute("data-font",f);e.setAttribute("data-mode",m);e.style.colorScheme=m==="system"?"light dark":m}catch(_){}}()`;
+	const axes = scriptSafe(JSON.stringify(Object.fromEntries((vocab.themes ?? [null]).map((name) => {
+		const preferredDensity = vocab.preferredDensity(name);
+		const preferredFont = vocab.preferredFont(name);
+		return [name ?? "", {
+			d: vocab.densitiesFor(name),
+			f: vocab.fontsFor(name),
+			l: vocab.supportsLight(name),
+			...preferredDensity === DEFAULT_DENSITY ? {} : { p: preferredDensity },
+			...preferredFont === DEFAULT_FONT ? {} : { q: preferredFont }
+		}];
+	}))));
+	const modes = scriptSafe(JSON.stringify([...MODES]));
+	return `!function(){try{var k=${key},e=document.documentElement,s=null;` + (readStoredPreferences ? "try{var r=localStorage.getItem(k);s=r?JSON.parse(r):null}catch(_){}" : "") + `s=s&&typeof s=="object"?s:{};var T=${themes},A=${axes},P=/^[a-z][a-z0-9-]*$/i;var t=T?(T.indexOf(s.theme)>-1?s.theme:${fallbackTheme}):(typeof s.theme=="string"&&P.test(s.theme)?s.theme:${fallbackTheme});var a=A[T?t:""]||A[""]||{d:[],f:[]};var d=a.d.indexOf(s.density)>-1?s.density:(a.d.indexOf(${fallbackDensity})>-1?${fallbackDensity}:(a.p&&a.d.indexOf(a.p)>-1?a.p:${baseDensity}));var f=a.f.indexOf(s.font)>-1?s.font:(a.f.indexOf(${fallbackFont})>-1?${fallbackFont}:(a.q&&a.f.indexOf(a.q)>-1?a.q:${baseFont}));var m=${modes}.indexOf(s.mode)>-1?s.mode:${fallbackMode};e.setAttribute("data-theme",t);e.setAttribute("data-density",d);e.setAttribute("data-font",f);e.setAttribute("data-mode",m);e.style.colorScheme=a.l===false?"dark":(m==="system"?"light dark":m)}catch(_){}}()`;
 }
 //#endregion
 export { DEFAULT_STORAGE_KEY, prepaintScript };

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

@@ -1,5 +1,6 @@
+import { TokenOverrides } from "./overrides.js";
 import * as React from "react";
-import { Density, FontName, Mode, ThemeName } from "@cueplusplus/tokens";
+import { Density, FontName, Mode, ThemeManifest, ThemeName } from "@cueplusplus/theme-base";
 //#region src/system/theme-provider.d.ts
 /** A mode that has been resolved to an actual palette — `"system"` never survives this far. */
 type ResolvedMode = "dark" | "light";
@@ -7,6 +8,12 @@ type ResolvedMode = "dark" | "light";
 interface ThemeContextValue {
   /** Active theme preset. */
   theme: ThemeName;
+  /**
+   * The active theme's manifest, or `null` when the active name is not
+   * registered — which is every name in an app that passes no `themes`, and the
+   * one a `setTheme` for an unknown preset leaves behind.
+   */
+  manifest: ThemeManifest | null;
   /** Density the *provider* holds — a nested `<Density>` island does not change it. */
   density: Density;
   /** Mode as chosen, including the literal `"system"`. */
@@ -32,15 +39,66 @@ interface FontFamilies {
   mono?: string;
 }
 interface ThemeProviderProps {
-  /** Initial theme preset. Defaults to `"cue"`. Changing it after mount adopts the new value. */
+  /**
+   * The registry: an ordered array of theme manifests, the first of which is
+   * the default theme.
+   *
+   * A prop rather than a side effect, so the server render and the client
+   * render are handed the same array and nothing depends on which module an app
+   * happened to import first. Each entry is a `manifest.json` from a
+   * `@cueplusplus/theme-<name>` package; this library never discovers a theme by
+   * itself, because which themes a product ships is an application decision.
+   *
+   * Optional for one release, defaulting to `[]` with a development warning. An
+   * app that registers nothing gets the base axes and no registry: any
+   * well-formed name is accepted as a theme (so a visitor's stored preference
+   * still restores on first paint), density and font validate against the base
+   * ladder and pairings, and `useTheme().manifest` is `null`. What it *paints*
+   * is a separate question with a separate answer — whichever `[data-theme]`
+   * blocks its stylesheets declare, which is the blank base only when none of
+   * them declares the stamped name.
+   *
+   * A nested provider that passes none inherits the ambient registry.
+   *
+   * One disclosure to be aware of: {@link prepaintScript} inlines the
+   * registered **names** — and each theme's `supportsLight` flag, and the names
+   * of any rung or pairing it adds — into the blocking script in every page's
+   * HTML, because first paint has to judge a stored preference before any
+   * module loads. No colours, no geometry, no package names, and only what an
+   * app passes here. But an app that registers
+   * a per-customer theme is publishing that customer's name to every visitor
+   * who views source, so register per-customer themes per response rather than
+   * globally.
+   */
+  themes?: readonly ThemeManifest[];
+  /**
+   * Initial theme preset. Defaults to the first registered manifest's name, or
+   * `"cue"` with nothing registered. Changing it after mount adopts the new value.
+   */
   theme?: ThemeName;
-  /** Initial density level. Defaults to `"compact"`. */
+  /**
+   * Initial density level.
+   *
+   * Defaults to the rung the active theme's manifest names in
+   * `densities.default`, and to `"compact"` when it names none — spec §5's
+   * rule, and the same one `resolve()` applies when no rung is wanted, so a
+   * theme opens on the rung it prefers whether it is read from JS or painted
+   * by its own stylesheet. Naming a rung here overrides that for every theme:
+   * a consumer who named one named it deliberately.
+   *
+   * Changing it after mount adopts the new value; dropping it does not — a
+   * parent that stops naming a rung is not asking to move back to the theme's.
+   */
   density?: Density;
   /** Initial mode. Defaults to `"dark"`; `"system"` tracks `prefers-color-scheme`. */
   mode?: Mode;
   /**
-   * Initial font pairing. Defaults to `"system"` — the platform's own faces,
-   * nothing downloaded, and the theme keeps whatever monospace it authored.
+   * Initial font pairing.
+   *
+   * Defaults to the pairing the active theme's manifest names in
+   * `fontPairings.default` — §5's rule, the density prop's rule one axis over
+   * — and to `"system"` when it names none: the platform's own faces, nothing
+   * downloaded, and the theme keeps whatever monospace it authored.
    *
    * A pairing that needs delivering is a set of *names*: this library ships no
    * font files, and a pairing nobody delivers falls through its stack to the
@@ -58,6 +116,66 @@ interface ThemeProviderProps {
   fontScale?: number;
   /** Optional app-owned font stacks, published as inline CUE font custom properties. */
   fontFamilies?: FontFamilies;
+  /**
+   * Typed token edits layered over the active theme: colours per mode, geometry
+   * per rung, and the three font stacks.
+   *
+   * For the band of edits that sit below "publish a theme package": one accent
+   * for a tenant, a stack the app already loads, a rung with two more pixels in
+   * a touch build. Anything larger belongs in a `@cueplusplus/theme-<name>`
+   * package, where a build measures it; anything smaller than this is a
+   * `!important` in a stray stylesheet, which outranks the token layer
+   * everywhere at once.
+   *
+   * **Colours and fonts are inline on this element**, so they inherit down the
+   * subtree, beat every stylesheet without `!important`, and are re-stamped
+   * onto portal containers — which mount on `<body>` and inherit nothing from
+   * here. They do not leak *out* of this provider: a nested provider's colour
+   * edit is scoped to its own subtree, and to portals opened from inside it.
+   *
+   * **Densities are one document-scoped `<style>` element**, because a rung is
+   * selected by attribute rather than inherited, and because
+   * `useControlHeight()`'s measuring probe hangs off `document.body`, where
+   * a subtree-scoped rule would not reach it — leaving the measured height and
+   * the painted control disagreeing by exactly the override. The consequence is
+   * worth knowing before you nest one: a nested provider's `densities` edit
+   * reaches the whole page, exactly as a theme's own rung rules do. Colours and
+   * fonts in the same object do not.
+   *
+   * And it cuts the other way as well, which is the half that surprises: two
+   * providers editing the same rung produce two document-scoped rules of equal
+   * specificity, so the **later** one in document order wins everywhere — and
+   * the later one is the outer provider's, because a nested provider renders
+   * inside it. A nested `densities` edit does not merely leak out; an ancestor
+   * that edits the same rung overrules it *inside the nested subtree too*. If
+   * an island needs geometry of its own, it needs a rung of its own — a name no
+   * ancestor is editing — not the same rung with different numbers.
+   *
+   * Its rules are `[data-density="x"][data-density="x"]` — (0,2,0), tying a
+   * theme's own `[data-theme="t"] [data-density="x"]` and winning on source
+   * order — so the precedence is: **`overrides`, then the configurator's
+   * persisted snapshot, then the theme, then base.**
+   *
+   * **A font override shadows the pairing for this subtree.** `data-font` is
+   * the document's axis and this element deliberately never restates it (see
+   * the note by `stamp` below), but `overrides.fonts` writes the resolved
+   * `--cue-font-*` properties directly, which is a stronger claim than the
+   * attribute and is the point: this is how an app says "this product's face,
+   * whatever pairing the visitor picked".
+   *
+   * In development the resulting palette is measured, and any required contrast
+   * pair the edit broke — or made worse — is named on the console.
+   *
+   * @example
+   * <ThemeProvider themes={[cue]} overrides={{
+   *   colors: { dark: { accent: "#ff8800" }, light: { accent: "#b35900" } },
+   *   densities: { compact: { "control-md": "1.75rem" } },
+   *   fonts: { sans: '"Tenant Sans", ui-sans-serif, sans-serif' },
+   * }}>
+   *   <App />
+   * </ThemeProvider>
+   */
+  overrides?: TokenOverrides;
   /**
    * localStorage key holding `{ theme, density, font, mode }`. Defaults to `"cue-ui"`.
    * Only the outermost provider reads or writes it — a nested provider is an
@@ -78,7 +196,8 @@ interface ThemeProviderProps {
 /**
  * Root of the theme system: stamps `data-theme`, `data-density` and `data-mode`
  * so the token layer resolves, puts `data-font` on `<html>`, publishes
- * `--cue-font-scale`, and owns the persisted user preference.
+ * `--cue-font-scale`, owns the persisted user preference, and publishes the
+ * registry the three axis hooks read.
  *
  * Rendering: `<div data-cue-root data-theme data-density data-mode style={{ colorScheme, --cue-font-scale }}>`
  * (or the single child when `asChild`). The `theme`/`density`/`font`/`mode` props are
@@ -100,10 +219,16 @@ interface ThemeProviderProps {
  * font pairing — `useTheme().font` and `setFont` inside one are the root's.
  *
  * @example
- * <ThemeProvider theme="terminal" density="ultra-compact" font="plex" mode="system">
+ * // `cue` and `terminal` are the `manifest.json` each theme package ships, read
+ * // from the `…/manifest.json` subpath of `@cueplusplus/theme-cue` and
+ * // `@cueplusplus/theme-terminal`. Written that way round on purpose: a literal
+ * // import statement in this comment reads, to every import-graph gate in this
+ * // repository, as `ui` depending on a theme package — which is the one thing
+ * // it may not do.
+ * <ThemeProvider themes={[cue, terminal]} theme="terminal" density="ultra-compact" font="plex" mode="system">
  *   <App />
  * </ThemeProvider>
  */
-declare function ThemeProvider({ theme: themeProp, density: densityProp, mode: modeProp, font: fontProp, fontScale, fontFamilies, storageKey, persistPreferences, asChild, className, style: styleProp, children }: ThemeProviderProps): React.JSX.Element;
+declare function ThemeProvider({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp, font: fontProp, fontScale, fontFamilies, overrides, storageKey, persistPreferences, asChild, className, style: styleProp, children }: ThemeProviderProps): React.JSX.Element;
 //#endregion
 export { FontFamilies, ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps };