@cueplusplus/ui 0.13.0

package/dist/system/prepaint.js

@@ -0,0 +1,120 @@
+import { vocabulary } from "./vocabulary.js";
+import { DEFAULT_DENSITY, DEFAULT_FONT, STYLE_SETS } 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";
+/** `<` and `>` escaped, so no value can close the host `<script>` element. */
+const scriptSafe = (json) => json.replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
+/**
+* Embed a string in JavaScript source that will itself be embedded in HTML.
+* `<` becomes `\u003c` so no value can close the host `<script>` element.
+*/
+function jsStringLiteral(value) {
+	return scriptSafe(JSON.stringify(value));
+}
+function prepaintScript(storageKeyOrOptions = DEFAULT_STORAGE_KEY, defaultTheme = "cue", defaultDensity = DEFAULT_DENSITY, defaultFont = DEFAULT_FONT) {
+	const options = typeof storageKeyOrOptions === "string" ? {
+		storageKey: storageKeyOrOptions,
+		defaults: {
+			theme: defaultTheme,
+			density: defaultDensity,
+			mode: "dark",
+			font: defaultFont
+		},
+		readStoredPreferences: true
+	} : storageKeyOrOptions;
+	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.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 ?? vocab.preferredDensity(defaults.theme));
+	const fallbackMode = jsStringLiteral(defaults.mode);
+	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 other two axes, `supportsLight`, and each theme's own preference, **per theme**.
+	*
+	* 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 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]));
+	/**
+	* The three sets, and the app's own, inlined for the same reason the rungs and
+	* pairings are: this script runs before any module does and cannot import a
+	* list. `null` is a legal fallback here and means "no set" — the one axis
+	* whose absence is a value.
+	*/
+	const styleSets = scriptSafe(JSON.stringify([...STYLE_SETS]));
+	const fallbackStyleSet = defaults.styleSet === void 0 ? "null" : jsStringLiteral(defaults.styleSet);
+	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};var S=${styleSets},y=S.indexOf(s.style)>-1?s.style:${fallbackStyleSet};e.setAttribute("data-theme",t);e.setAttribute("data-density",d);e.setAttribute("data-font",f);e.setAttribute("data-mode",m);y?e.setAttribute("data-style",y):e.removeAttribute("data-style");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

@@ -0,0 +1,290 @@
+import { TokenOverrides } from "./overrides.js";
+import * as React from "react";
+import { StyleSet } from "@cueplusplus/tokens";
+import { Density as Density$1, 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";
+/** What `useTheme()` returns. */
+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$1;
+  /** Mode as chosen, including the literal `"system"`. */
+  mode: Mode;
+  /** Active font pairing. */
+  font: FontName;
+  /**
+   * The style set in force, or `null` when nothing has chosen one — which is
+   * every application that has not asked for page composition. `null` rather
+   * than the default set's name, because the two are different facts: no
+   * attribute is stamped, and `console` is the set a subtree stamps to say it is
+   * the ordinary thing inside a page that is not.
+   *
+   * *In force*, not *named here*: a provider that names no set reports the one
+   * stamped around it, exactly as the DOM resolves it, so this and the
+   * `StyleSetContext` the portal and stage stamps read are one value.
+   */
+  styleSet: StyleSet | null;
+  /** Mode after resolving `"system"` against `prefers-color-scheme`. */
+  resolvedMode: ResolvedMode;
+  /** Switch theme and persist the new preference triple. */
+  setTheme: (theme: ThemeName) => void;
+  /** Switch the provider-level density and persist the new preference triple. */
+  setDensity: (density: Density$1) => void;
+  /** Switch mode (`"system"` included) and persist the new preference triple. */
+  setMode: (mode: Mode) => void;
+  /** Switch the font pairing and persist the new preference. */
+  setFont: (font: FontName) => void;
+  /**
+   * Switch the style set this provider names, and persist the preference.
+   *
+   * `null` means *this provider names none* — not *no set applies*. The
+   * provider stops stamping `data-style`, so a nested one under an outer
+   * `editorial` page goes back to inheriting `editorial`, and `styleSet`
+   * above reports it, because that is what the DOM resolves to. At the root,
+   * where nothing is stamped around it, `null` and "no set" coincide.
+   *
+   * To positively leave an inherited set rather than stop naming one, pass
+   * {@link DEFAULT_STYLE_SET}: it stamps an attribute whose block restates the
+   * `:root` defaults token for token, which is the only thing that can
+   * out-specify an ancestor's in a cascade.
+   */
+  setStyleSet: (next: StyleSet | null) => void;
+}
+/** Provider-owned font-family overrides that detached portals must republish. */
+interface FontFamilies {
+  /** Value for `--cue-font-sans`. */
+  sans?: string;
+  /** Value for `--cue-font-mono`. */
+  mono?: string;
+}
+interface ThemeProviderProps {
+  /**
+   * 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 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$1;
+  /** Initial mode. Defaults to `"dark"`; `"system"` tracks `prefers-color-scheme`. */
+  mode?: Mode;
+  /**
+   * 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
+   * platform rather than failing. See `FONT_PAIRINGS[font].faces` for the
+   * custom properties an app assigns to make one resolve.
+   *
+   * **Root-level only.** There is no font island: a nested provider forwards
+   * this axis to the root, ignores this prop, and its `setFont` drives the root.
+   * A page that changed face halfway down is a page with a bug, and a specimen
+   * that genuinely wants one — a picker row, a docs page showing all eight —
+   * needs nothing from this library but `data-font` on a `<div>`.
+   */
+  font?: FontName;
+  /**
+   * Page composition for this subtree: `console`, `editorial` or `marketing`.
+   *
+   * **`styleSet`, not `style`.** This interface already has a
+   * `style?: React.CSSProperties` a few lines below, applied to the provider
+   * root, and a second meaning for that name would be the one collision every
+   * consumer of this component would have to think about. The DOM attribute is
+   * `data-style`, matching the four public axes — `data-cue-*` is this tree's
+   * prefix for *internal* attributes (`data-cue-theme`, `data-cue-fidelity`), and
+   * a public axis wearing the internal prefix would be the more confusing of the
+   * two mistakes.
+   *
+   * Unset, **no attribute is stamped at all**, and that is the promise: an
+   * application that has never heard of this axis renders the markup it rendered
+   * before it existed and stores the preference object it stored before it
+   * existed. A style set is opt-in page composition, not a fourth thing every
+   * page has.
+   *
+   * Like the other three axes this is an *initial* value the provider then holds
+   * as state, so `setStyleSet` can drive it; a changed prop is adopted after
+   * mount. Unlike the font pairing it has an island form, so a nested provider
+   * holds its own rather than handing the axis up to the root.
+   */
+  styleSet?: StyleSet;
+  /** Multiplier on every text token, published as `--cue-font-scale`. Defaults to `1`. */
+  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
+   * island whose explicit props are the point, not a second preference store.
+   */
+  storageKey?: string;
+  /** Restore and write root preferences in localStorage. Defaults to `true`. */
+  persistPreferences?: boolean;
+  /** Stamp the single child element instead of rendering a wrapper `<div>`. */
+  asChild?: boolean;
+  /** Extra classes for the provider root. */
+  className?: string;
+  /** Inline styles for the provider root, merged after the token style. */
+  style?: React.CSSProperties;
+  /** The application subtree. */
+  children?: React.ReactNode;
+}
+/**
+ * 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`, 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`), plus `data-style` when — and only when —
+ * a style set is in force. The `theme`/`density`/`font`/`mode`/`styleSet` props are
+ * *initial* values — the provider holds the state so `setTheme` and friends can
+ * drive it — but a changed prop is adopted after mount, so a controlling parent
+ * still works.
+ *
+ * The font pairing is the one axis that never lands on this element: it has no
+ * island form, `<html>` is its only home, and restating it here would shadow the
+ * pre-paint stamp for the whole page on the first frame. See the `stamp` object
+ * below.
+ *
+ * Persistence and the pre-paint contract: setters write
+ * `{ theme, density, font, mode }` to `localStorage[storageKey]`, plus a `style`
+ * key holding the style set when there is one — omitted entirely when there is
+ * not, so an application that never touches that axis writes the same four-key
+ * object it always wrote. That is exactly what
+ * {@link prepaintScript} reads to stamp `<html>` before the first paint. The
+ * outermost provider keeps `<html>` in sync while the app runs (and restores the
+ * previous stamp on unmount) so the page ground, UA scrollbars and form controls
+ * follow the theme; nested providers never touch `<html>`, and never own the
+ * font pairing — `useTheme().font` and `setFont` inside one are the root's.
+ *
+ * @example
+ * // `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({ themes: themesProp, theme: themeProp, density: densityProp, mode: modeProp, font: fontProp, styleSet: styleSetProp, fontScale, fontFamilies, overrides, storageKey, persistPreferences, asChild, className, style: styleProp, children }: ThemeProviderProps): React.JSX.Element;
+//#endregion
+export { FontFamilies, ResolvedMode, ThemeContextValue, ThemeProvider, ThemeProviderProps };