@cueplusplus/ui 0.16.0 → 0.17.0

package/dist/system/published.d.ts

@@ -0,0 +1 @@
+import "react";

package/dist/system/published.js

@@ -0,0 +1,131 @@
+"use client";
+import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
+import * as React from "react";
+//#region src/system/published.ts
+/**
+* One per provider instance and context, for the provider's whole life.
+*
+* Internal.
+*/
+var Overlay = class {
+	posted = null;
+	listeners = /* @__PURE__ */ new Set();
+	subscribe = (listener) => {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	};
+	/** The value `held` stands for now: its correction if one is posted for it, else its own value. */
+	resolve(held) {
+		const posted = this.posted;
+		return posted !== null && posted.key === held ? posted.value : held.value;
+	}
+	/**
+	* Say that `held` now stands for `value`.
+	*
+	* Nothing is told when nothing changes for a reader of `held`: a value equal
+	* to `held.value` clears only a post made for `held`, and one made for an
+	* older key is left alone, because no reader of the current key reads it.
+	*/
+	post(held, value) {
+		const posted = this.posted;
+		if (Object.is(value, held.value)) {
+			if (posted === null || posted.key !== held) return;
+			this.posted = null;
+		} else {
+			if (posted !== null && posted.key === held && Object.is(posted.value, value)) return;
+			this.posted = {
+				key: held,
+				value
+			};
+		}
+		for (const listener of [...this.listeners]) listener();
+	}
+};
+/** A value published once and never corrected: a context's value outside any provider. */
+function published(value) {
+	return {
+		value,
+		server: value,
+		overlay: new Overlay()
+	};
+}
+function sameInputs(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i += 1) if (!Object.is(a[i], b[i])) return false;
+	return true;
+}
+/**
+* Publish `value` from a provider.
+*
+* `inputs` are what may move the context: the provider's props and the edits
+* its setters make, and the `Published` objects it read from the providers
+* around it (`React.useContext`, not {@link useRead} — the object, whose
+* identity changes only when theirs did). What must NOT be among them is
+* anything a client-only correction moves: a root's restored state, the OS
+* colour scheme, or a value read through {@link useRead}.
+*
+* When `inputs` change and `value` differs from what readers see now, the
+* published object is new and holds this render's `value`: the context moves,
+* as any context moves when its value does. When `value` is what readers
+* already see — an edit that changed nothing this context carries — the object
+* stays, so a new pack is no news to a reader of the rungs on offer. And when
+* `inputs` did not change and `value` moved anyway, it moved because a
+* correction reached this provider: the object stays, and the new value is
+* posted to the overlay after the commit (the layout phase, still before the
+* browser paints), for the readers below to pick up. A missing input therefore
+* costs a synchronous catch-up render, never a wrong value.
+*
+* `served`, when given, is what this provider's first render put in the
+* server's HTML where that differs from `value` — the one root whose first
+* client render knowingly differs from the server's (see `ThemeProvider`'s
+* pairing). Called once, on mount.
+*/
+function usePublish(value, inputs, served) {
+	const [overlay] = React.useState(() => new Overlay());
+	const [held, setHeld] = React.useState(() => ({
+		inputs,
+		published: {
+			value,
+			server: served === void 0 ? value : served(),
+			overlay
+		}
+	}));
+	let current = held.published;
+	if (!sameInputs(held.inputs, inputs)) {
+		if (!Object.is(value, overlay.resolve(held.published))) current = {
+			value,
+			server: held.published.server,
+			overlay
+		};
+		setHeld({
+			inputs,
+			published: current
+		});
+	}
+	useIsomorphicLayoutEffect(() => {
+		overlay.post(current, value);
+	});
+	return current;
+}
+/** Read what a provider published: against the server's value while hydrating, corrected after. */
+function useRead(context) {
+	const held = React.useContext(context);
+	return React.useSyncExternalStore(held.overlay.subscribe, () => held.overlay.resolve(held), () => held.server);
+}
+/**
+* Read one slice of what a provider published, and re-render only when that
+* slice changes.
+*
+* `select` must return the same object for the same input — a field of the
+* value, not a copy of it. A reader that needs one part of a larger value (the
+* registered themes, which no restore moves, out of a registry rebuilt for every
+* active theme) then sits out every correction it does not read.
+*/
+function useReadSelected(context, select) {
+	const held = React.useContext(context);
+	return React.useSyncExternalStore(held.overlay.subscribe, () => select(held.overlay.resolve(held)), () => select(held.server));
+}
+//#endregion
+export { Overlay, published, usePublish, useRead, useReadSelected };

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

@@ -1,3 +1,4 @@
+import "./published.js";
 import { TokenOverrides } from "./overrides.js";
 import * as React from "react";
 import { Paint, StyleSet } from "@cueplusplus/tokens";
@@ -15,7 +16,11 @@ interface ThemeContextValue {
    * 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 the *provider* holds — a nested `<Density>` island does not change
+   * it. In a nested provider that names none, the rung stamped around it, which
+   * is what its subtree inherits.
+   */
   density: Density$1;
   /** Mode as chosen, including the literal `"system"`. */
   mode: Mode;
@@ -34,7 +39,7 @@ interface ThemeContextValue {
    */
   styleSet: StyleSet | null;
   /**
-   * The look pack in force on this subtree, or `null`.
+   * The paint pack in force on this subtree, or `null`.
    *
    * *In force*, not *named here*, exactly as `styleSet` is: a provider that
    * names no pack reports the one stamped around it, so this and the
@@ -55,10 +60,11 @@ interface ThemeContextValue {
    * 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.
+   * provider stops stamping a set of its own, so a nested one under an outer
+   * `editorial` page goes back to `editorial` — inherited, or restated beside
+   * the theme if it names one — 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
@@ -66,7 +72,11 @@ interface ThemeContextValue {
    * out-specify an ancestor's in a cascade.
    */
   setStyleSet: (next: StyleSet | null) => void;
-  /** Switch the look pack and persist it. `null` clears the attribute. */
+  /**
+   * Switch the paint pack this provider names, and persist it at the root.
+   * `null` clears the attribute; in a nested provider that means following the
+   * pack stamped around it again, exactly as `setStyleSet(null)` does.
+   */
   setPaint: (next: Paint | null) => void;
 }
 /** Provider-owned font-family overrides that detached portals must republish. */
@@ -112,6 +122,13 @@ interface ThemeProviderProps {
   /**
    * Initial theme preset. Defaults to the first registered manifest's name, or
    * `"cue"` with nothing registered. Changing it after mount adopts the new value.
+   *
+   * A nested provider that names **none** holds none: it stamps no
+   * `data-theme`, so the theme around it inherits through its element, and
+   * `useTheme().theme` inside it — and every portal opened inside it — follows
+   * that theme **live**, a theme the root restores from storage after mount
+   * included. Naming one makes it this provider's, stamped with the rung and
+   * mode in force beside it, whatever the root does.
    */
   theme?: ThemeName;
   /**
@@ -126,9 +143,23 @@ interface ThemeProviderProps {
    *
    * 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.
+   *
+   * A nested provider that names **none** follows the rung stamped around it
+   * live — the outer provider's, or a `<Density>` island's between them — and
+   * stamps none unless it re-themes or re-modes, in which case it restates the
+   * rung it follows. Naming one stamps it as a `<Density>` island would.
    */
   density?: Density$1;
-  /** Initial mode. Defaults to `"dark"`; `"system"` tracks `prefers-color-scheme`. */
+  /**
+   * Initial mode. Defaults to `"dark"` at the root; `"system"` tracks
+   * `prefers-color-scheme`.
+   *
+   * A nested provider that names **none** follows the mode around it live and
+   * stamps no `data-mode` or `color-scheme` of its own; `useTheme().mode` and
+   * `resolvedMode` inside it report the ambient pair. Naming one stamps it
+   * beside the theme in force, because a theme's light block is the compound
+   * `[data-theme][data-mode]`.
+   */
   mode?: Mode;
   /**
    * Initial font pairing.
@@ -146,12 +177,13 @@ interface ThemeProviderProps {
    * **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 —
+   * that genuinely wants one — a picker row, a docs page showing all twelve —
    * needs nothing from this library but `data-font` on a `<div>`.
    */
   font?: FontName;
   /**
-   * Page composition for this subtree: `console`, `editorial` or `marketing`.
+   * Page composition for this subtree: `console`, `editorial`, `marketing` or
+   * `graphite`.
    *
    * **`styleSet`, not `style`.** This interface already has a
    * `style?: React.CSSProperties` a few lines below, applied to the provider
@@ -171,15 +203,39 @@ interface ThemeProviderProps {
    * 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.
+   * that names a set holds its own rather than handing the axis up to the root.
+   *
+   * A nested provider that names **none** holds none: the set around it
+   * inherits through its element, and `useTheme().styleSet` inside it reports
+   * that set **live** — a stored set the root restores after mount, or a later
+   * `setStyleSet` at the root, reaches it and its portals. If it names a
+   * `theme` or a `mode`, it also restates that set as `data-style` on its
+   * element — still the page's set, followed live, never its own — because a
+   * set's block declares values that read the theme (a band's rule and
+   * ground), and a custom property resolves where it is declared: restated,
+   * they resolve against this island's theme instead of the page's.
    */
   styleSet?: StyleSet;
   /**
-   * A look pack for this subtree. Opt-in: a provider that names none stamps no
-   * `data-paint`, and a nested one inherits the pack stamped around it.
+   * A paint pack for this subtree. Opt-in: a provider that names none stamps no
+   * `data-paint` of its own. A nested one that names none follows the pack
+   * stamped around it **live**, through inheritance in the DOM and through
+   * `useTheme().paint` and its portals in React — and, if it names a `theme` or
+   * a `mode`, restates that pack as `data-paint` on its element, so the pack's
+   * strokes and inks (mixes of the theme's colours) resolve against this
+   * island's theme rather than the page's. One that names a pack keeps it
+   * whatever the root does.
    */
   paint?: Paint;
-  /** Multiplier on every text token, published as `--cue-font-scale`. Defaults to `1`. */
+  /**
+   * Multiplier on every text token, published as `--cue-font-scale`. Defaults to `1`.
+   *
+   * At a root that persists, pass the same number to
+   * `prepaintScript({ fontScale })`: until the root has restored the visitor's
+   * preferences, the type tokens the page reads are declared on `<html>`, and
+   * the script is what puts the scale there for the first frame. The root keeps
+   * it on `<html>` after that.
+   */
   fontScale?: number;
   /** Optional app-owned font stacks, published as inline CUE font custom properties. */
   fontFamilies?: FontFamilies;
@@ -199,6 +255,13 @@ interface ThemeProviderProps {
    * 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.
+   * Under a root that persists, the server cannot know the visitor's mode, so
+   * until a root has restored, and until a nested provider whose mode is the
+   * root's has mounted, the colours are instead one small `<style>` beside this
+   * element, keyed on it and on `<html>`'s mode (and on `<html>`'s theme,
+   * where that decides the mode): the first frame is the visitor's mode with
+   * that mode's edit, never the other mode's. It carries `nonce`; refused by a
+   * policy, the edit waits for the mount.
    *
    * **Densities are one document-scoped `<style>` element**, because a rung is
    * selected by attribute rather than inherited, and because
@@ -244,7 +307,9 @@ interface ThemeProviderProps {
    */
   overrides?: TokenOverrides;
   /**
-   * localStorage key holding `{ theme, density, font, mode }`. Defaults to `"cue-ui"`.
+   * localStorage key holding `{ theme, density, font, mode }`, plus `style` when a
+   * style set has been chosen and `paint` when a pack has — each omitted, never
+   * stored as `null`, when none has. 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.
    */
@@ -265,7 +330,10 @@ interface ThemeProviderProps {
    * {@link ThemeProviderProps.overrides}) — takes its nonce **from this prop
    * alone**: not from an outer `CSPProvider`, and not from an outer
    * `ThemeProvider`. A nested provider that sets its own `overrides.densities`
-   * needs its own `nonce`.
+   * needs its own `nonce`. So does the colour layer — one `<style
+   * data-cue-colors-for>` while `overrides.colors` waits on a mode that is
+   * `<html>`'s (see {@link ThemeProviderProps.overrides}); refused, the edit
+   * applies from the restore or the mount instead of the first frame.
    *
    * Base UI's scrollbar rule gets the nonce wherever React creates it in the
    * browser. **It does not get it in server-rendered HTML** under a framework
@@ -307,7 +375,16 @@ interface ThemeProviderProps {
    * warning of its own.
    */
   nonce?: string;
-  /** Stamp the single child element instead of rendering a wrapper `<div>`. */
+  /**
+   * Stamp the single child element instead of rendering a wrapper `<div>`.
+   *
+   * A nested provider over a host element (`<section>`, `<main>`) behaves as
+   * its `<div>` would. Over a component it follows nothing from a persisting
+   * root before it mounts: it stamps the root's theme, mode and density from
+   * the server's first render, because the re-render that would correct them
+   * renders the component again, and a `<Suspense>` boundary the component
+   * creates would lose its streamed server HTML to it.
+   */
   asChild?: boolean;
   /** Extra classes for the provider root. */
   className?: string;
@@ -324,21 +401,41 @@ interface ThemeProviderProps {
  *
  * 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
+ * a style set is in force, and `data-paint` on the same terms for a pack. The
+ * `theme`/`density`/`font`/`mode`/`styleSet`/`paint` 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.
  *
+ * A **nested** provider stamps only what it names. One that names no theme,
+ * rung, mode, set or pack follows each of them from around it, live — a
+ * preference the root restores after mount, or a setter called at the root,
+ * reaches it, its `useTheme()` and its portals — and restates none of them on
+ * its element, so inheritance carries the outer attributes through. Naming a
+ * theme or a mode stamps theme, rung and mode together (a theme's light block
+ * and its rung rules are compound selectors), and restates the set and the pack
+ * in force beside them, so their blocks — whose values read the theme — resolve
+ * against this element's theme rather than the page's; naming only a rung
+ * stamps it as a `<Density>` island does.
+ *
  * 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.
  *
+ * The other axes wait for the same reason at a root that persists: its server
+ * markup, and its first client render, carry `data-cue-root` and no axis
+ * attribute or `color-scheme`, so the page inherits the visitor's stored axes
+ * from the pre-paint stamp on `<html>`. The restore lands before the first
+ * paint, and the element then states what it restored. Read the document's
+ * axes off `<html>`, not off this element, before hydration.
+ *
  * 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
+ * key holding the style set when there is one and a `paint` key holding the pack
+ * when there is one — each omitted entirely when there is not, so an application
+ * that never touches either 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