@cueplusplus/ui 0.7.0 → 0.9.0

package/manifest/components/ledger.json

@@ -5,7 +5,7 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": false,
-  "description": "A grouped run of dense rows under sticky headings: the ledger idiom.\n\nThe flattest of the three surfaces this package ships over one row model, and\nthe one that does the least: headings, slugs, rows. **Nothing here collapses.**\nA ledger with a disclosure on it would be a tree with worse semantics, so the\ncomponent emits no `aria-expanded` anywhere, and a test holds it to that —\ncollapse belongs to `DataTree`, and grouping-with-columns belongs to a\ngrouped `Table`.\n\nWhat it does own is the document outline. Tiers and groups are real `<h2>` /\n`<h3>` elements at caller-chosen levels, because in a list of two hundred\nrows the heading list *is* how a screen-reader user navigates.\n\nStatic markup — no `\"use client\"`. The rows inside it may be anything;\n`DataRow` is the intended tenant.",
+  "description": "A grouped run of dense rows under sticky headings: the ledger idiom.\n\nThe flattest of the three surfaces this package ships over one row model:\nheadings, slugs, rows. What it owns above all is the document outline. Tiers\nand groups are real `<h2>` / `<h3>` elements at caller-chosen levels, because\nin a list of two hundred rows the heading list *is* how a screen-reader user\nnavigates.\n\n## Folding: the accordion pattern, opt-in, and why it lives here\n\nThis component used to refuse disclosure outright, on the grounds that *a\nledger which folds is a tree with worse semantics*. That ruling was right\nabout rows and wrong about places, and the distinction is the whole of\n{@link LedgerTierProps.collapsible}:\n\n- **`DataTree` folds a row.** Its `role=\"treeitem\"` rows carry their own\n  `aria-expanded`, its chevron is `role=\"presentation\"` because in tree\n  semantics the row owns its expansion, and a tier and a subgroup drawn\n  through it stop being places and become rows. A consumer who measured this\n  exact shape through `DataTree` counted **zero** `h2`/`h3` elements and zero\n  `button[aria-expanded]`, which is `DataTree` working correctly and still\n  not being what a grouped document needs.\n- **`Ledger` folds a place.** A tier is already an `<h2>`, which is already\n  the right element for it, so the disclosure goes *inside* the heading as a\n  real `<button aria-expanded aria-controls>` — the accordion pattern, and\n  the same one `Table.GroupRow`'s note has always pointed at for a table that\n  genuinely needs to fold. The outline is untouched: the heading list of a\n  folding ledger and a plain one are identical, which is what lets a page\n  offer both idioms over one dataset without the outline moving under a\n  reader who switches.\n\nSo it is one component with two forms rather than a `DisclosureLedger` beside\nit: everything a folding ledger needs — the gutter track, the sticky offsets,\nthe label recipe, the type contract — is this component, and a sibling would\nhave been a copy of all of it wrapped around one `<button>`.\n\nExpansion is controllable and stores nothing. *Which* places a reader has\nfolded is a fact about the reader; consumers keep that set themselves and\npass it back in. A folded run of rows is hidden rather than unmounted, so a\ngroup that keeps its own fold inside a tier still keeps it after the tier has\nbeen shut and opened over it.\n\nStatic markup — no `\"use client\"` — **until a heading is asked to fold**, at\nwhich point that heading and its rows become a small client island and the\nrest of the ledger keeps rendering on the server.",
   "props": [],
   "typeReferences": [],
   "subcomponents": [
@@ -71,6 +71,34 @@
           "required": false,
           "defaultValue": null,
           "description": "A qualifier printed after the name — a date, a source, a state."
+        },
+        {
+          "name": "collapsible",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Put a disclosure in the tier's heading that folds its rows away. Defaults\nto `false`, and a tier with no `heading` has nothing to fold from, so it\nignores this and renders as it always has.\n\n**This is the accordion pattern, not the tree pattern.** What folds is the\nheading — a *place* — and the `<h2>` stays exactly where it was with a real\n`<button aria-expanded aria-controls>` inside it. The rows below are hidden\nwhile it is shut, which takes them out of the accessibility tree and out of\nthe layout but keeps whatever state they hold. If what you are folding is a\n*row*, and the thing under it is that row's children rather than that\nplace's contents, you want `DataTree` and its `treeitem` semantics instead."
+        },
+        {
+          "name": "expanded",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Whether the tier is open, when the caller owns the state.\n\n**Persistence is the caller's.** Which places a reader has folded is a fact\nabout the reader, not about the list, and it belongs wherever that consumer\nkeeps the rest of them — `localStorage`, a URL, a profile. This library\nstores nothing. Pass this with {@link LedgerTierProps.onExpandedChange};\nomit both and the tier keeps its own state from\n{@link LedgerTierProps.defaultExpanded}. Ignored unless `collapsible`."
+        },
+        {
+          "name": "defaultExpanded",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Whether an uncontrolled tier starts open. Defaults to `true`.\n\nOpen, because a ledger whose content is folded away on first paint has\nhidden the thing the reader came for; the reader folds what they are done\nwith. Ignored unless `collapsible`, and ignored entirely once\n{@link LedgerTierProps.expanded} is passed."
+        },
+        {
+          "name": "onExpandedChange",
+          "type": "((expanded: boolean) => void)",
+          "required": false,
+          "defaultValue": null,
+          "description": "Called with the tier's next state each time the reader presses the\ndisclosure — `true` when it is being opened, `false` when it is being shut.\n\nFires in both the controlled and the uncontrolled form, so a consumer can\nrecord what was folded without also having to own the state."
         }
       ],
       "typeReferences": [
@@ -102,6 +130,34 @@
           "required": false,
           "defaultValue": "true",
           "description": "Dock the slug under the tier heading while the group's rows scroll past.\nDefaults to `true`.\n\nThe offset is a custom property, `--cue-ledger-slug-top` (default `2.5rem`):\nhow far down the slug docks depends on how tall the tier heading above it\nrenders, which is a function of the density and the type the *caller*\nconfigured. Set it on the ledger — `className=\"[--cue-ledger-slug-top:2rem]\"` —\nrather than measuring at runtime."
+        },
+        {
+          "name": "collapsible",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Put a disclosure in the group's slug that folds its rows away. Defaults to\n`false`, and an unlabelled group has no slug to fold from, so it ignores\nthis. The same accordion pattern the tier takes — see\n{@link LedgerTierProps.collapsible} for why it is not the tree pattern."
+        },
+        {
+          "name": "expanded",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Whether the group is open, when the caller owns the state. Persistence is\nthe caller's; see {@link LedgerTierProps.expanded}."
+        },
+        {
+          "name": "defaultExpanded",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Whether an uncontrolled group starts open. Defaults to `true`."
+        },
+        {
+          "name": "onExpandedChange",
+          "type": "((expanded: boolean) => void)",
+          "required": false,
+          "defaultValue": null,
+          "description": "Called with the group's next state each time the reader presses the slug."
         }
       ],
       "typeReferences": [
@@ -121,11 +177,13 @@
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [
+    "--cue-accent",
     "--cue-bg",
     "--cue-data-row-cols",
     "--cue-fg",
     "--cue-fg-subtle",
     "--cue-font-mono",
+    "--cue-icon-sm",
     "--cue-ledger-gutter",
     "--cue-ledger-slug-top",
     "--cue-pad-row-x",
@@ -135,7 +193,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "Grouped dense rows under sticky tier headings and gutter slugs, with no disclosure anywhere.",
+  "summary": "Grouped dense rows under sticky tier headings and gutter slugs, with an opt-in disclosure that folds a heading without leaving the outline.",
   "examples": [
     {
       "title": "Tiers, groups, rows",
@@ -147,9 +205,14 @@
       "code": "<Ledger.Tier>\n  <Ledger.Group>\n    <DataRow.Root>…</DataRow.Root>\n  </Ledger.Group>\n</Ledger.Tier>",
       "language": "tsx"
     },
+    {
+      "title": "Folded places, persisted by the caller",
+      "code": "<Ledger.Tier\n  heading=\"Ours\"\n  count={13}\n  collapsible\n  expanded={!folded.includes(\"ours\")}\n  onExpandedChange={(open) => remember(\"ours\", open)}\n>\n  <Ledger.Group label=\"released\" collapsible defaultExpanded={false}>\n    <DataRow.Root>…</DataRow.Root>\n  </Ledger.Group>\n</Ledger.Tier>",
+      "language": "tsx"
+    },
     {
       "title": "Usage",
-      "code": "<Ledger.Root className=\"[--cue-data-row-cols:1fr_8rem_auto]\">\n  <Ledger.Tier heading=\"Ours\" count={12}>\n    <Ledger.Group label=\"released\">\n      <DataRow.Root interactive onActivate={open}>…</DataRow.Root>\n    </Ledger.Group>\n    <Ledger.Group label=\"lab\">\n      <Ledger.Empty>Nothing yet.</Ledger.Empty>\n    </Ledger.Group>\n  </Ledger.Tier>\n</Ledger.Root>",
+      "code": "<Ledger.Root className=\"[--cue-data-row-cols:1fr_8rem_auto]\">\n  <Ledger.Tier heading=\"Ours\" count={12}>\n    <Ledger.Group label=\"released\">\n      <DataRow.Root interactive onActivate={open}>…</DataRow.Root>\n    </Ledger.Group>\n    <Ledger.Group label=\"lab\">\n      <Ledger.Empty>Nothing yet.</Ledger.Empty>\n    </Ledger.Group>\n  </Ledger.Tier>\n</Ledger.Root>\n// Folded places are the reader's, so the reader's storage holds them.\n<Ledger.Tier\n  heading=\"Ours\"\n  count={13}\n  collapsible\n  expanded={!folded.includes(\"ours\")}\n  onExpandedChange={(open) => remember(\"ours\", open)}\n>\n  <Ledger.Group label=\"released\">…</Ledger.Group>\n</Ledger.Tier>",
       "language": "tsx"
     }
   ],
@@ -158,16 +221,18 @@
   "mdUrl": "/docs/components/ledger.md",
   "jsonUrl": "/r/components/ledger.json",
   "whenToUse": [
-    "A long list that is grouped but never folded: a corpus by source, a patch by direction, a run log by day.",
-    "A surface whose groups should be reachable by heading, since the tiers and slugs are real `h2`/`h3` elements."
+    "A long grouped list: a corpus by source, a patch by direction, a run log by day.",
+    "A surface whose groups should be reachable by heading, since the tiers and slugs are real `h2`/`h3` elements.",
+    "A grouped list the reader folds *by place* — `collapsible` puts a real `button[aria-expanded]` inside the heading and leaves the `h2`/`h3` outline exactly as it was."
   ],
   "whenNotToUse": [
-    "A hierarchy the reader folds. Use `DataTree`, which owns collapse and the tree semantics that go with it.",
+    "A hierarchy whose *rows* fold into their own children. Use `DataTree`, where the row is the treeitem and owns its expansion.",
     "Rows meant to be compared down a named column. Use a grouped `Table`, where the columns are named once in a `thead`.",
     "A handful of rows in a panel. Use `Row` inside `Panel`; a tier heading over three rows is furniture with nothing to organise."
   ],
   "commonMistakes": [
-    "Adding a toggle to a tier. A ledger that folds is a tree with worse semantics — the component emits no `aria-expanded`, and a test holds it to that.",
+    "Reaching for `DataTree` to fold a grouped list. A tree turns every tier and subgroup into a `treeitem` row and leaves zero headings behind — if the thing folding is a *place*, `collapsible` is the prop.",
+    "Storing the folded set inside the component. Which places a reader folded is a fact about the reader: pass `expanded` and `onExpandedChange` and keep it wherever the rest of that reader's preferences live.",
     "Framing each group in a `Panel`. A card per group turns one list into a stack of little tables and breaks the top-to-bottom scan.",
     "Leaving `--cue-ledger-slug-top` at its default after changing the density or the heading type, which docks the slug over the tier heading instead of under it.",
     "Passing an `empty` string as a prop. `Ledger.Empty` takes the words because \"this place is empty\" and \"your filter emptied it\" are different sentences."
@@ -182,6 +247,16 @@
       "code": "<Panel className=\"w-full\">\n  <div className=\"max-h-[18rem] overflow-y-auto\">\n    <Ledger.Root className={PATCH_TRACKS}>\n      <Ledger.Tier heading=\"Patch\" count={PATCH_DEVICES.length} note=\"polled 18:04\">\n        {PATCH_GROUPS.map((group) => (\n          <Ledger.Group key={group.id} label={group.label}>\n            {group.rows.map((device) => (\n              <DataRow.Root key={device.id} interactive>\n                <PatchRowSlots device={device} />\n              </DataRow.Root>\n            ))}\n          </Ledger.Group>\n        ))}\n        <Ledger.Group label=\"spare\">\n          <Ledger.Empty>Nothing yet.</Ledger.Empty>\n        </Ledger.Group>\n      </Ledger.Tier>\n    </Ledger.Root>\n  </div>\n</Panel>",
       "note": "The same rows as tiers and slugs: sticky headings, a gutter for the group name, and no disclosure anywhere — the ledger does not collapse.",
       "interaction": "the tier heading and the group slug dock as the rows scroll under them; scroll the pane to see it."
+    },
+    {
+      "title": "Ledger — collapsible",
+      "group": "instruments",
+      "components": [
+        "Ledger"
+      ],
+      "code": "<Panel className=\"w-full\">\n  <div className=\"max-h-[18rem] overflow-y-auto\">\n    <Ledger.Root className={PATCH_TRACKS}>\n      <Ledger.Tier\n        heading=\"Patch\"\n        count={PATCH_DEVICES.length}\n        collapsible\n        expanded={patchOpen}\n        onExpandedChange={setPatchOpen}\n      >\n        {PATCH_GROUPS.map((group, index) => (\n          <Ledger.Group\n            key={group.id}\n            label={group.label}\n            collapsible\n            defaultExpanded={index === 0}\n          >\n            {group.rows.map((device) => (\n              <DataRow.Root key={device.id} interactive>\n                <PatchRowSlots device={device} />\n              </DataRow.Root>\n            ))}\n          </Ledger.Group>\n        ))}\n      </Ledger.Tier>\n    </Ledger.Root>\n  </div>\n</Panel>",
+      "note": "The same ledger with `collapsible` on the tier and on one group. The disclosure is a real `button[aria-expanded aria-controls]` *inside* the `h2`/`h3`, so the heading outline is identical to the bench above it. A folded run of rows is hidden rather than unmounted — out of the layout and out of the accessibility tree, but still holding its state, which is what lets a group keep its own fold while the tier above it is shut and reopened. Which places are folded is the caller's to keep; this bench keeps it in React state and nothing is stored by the library.",
+      "interaction": "press a tier heading or a group slug to fold it; the chevron turns, the sibling group stays open, and Tab reaches each disclosure as a real button with Enter and Space. Fold the first group, then fold and reopen the tier over it: the group is still folded."
     }
   ]
 }

package/manifest/components/preset-section.json

@@ -45,17 +45,16 @@
     "--cue-fg-muted",
     "--cue-fg-subtle",
     "--cue-font-mono",
-    "--cue-font-pairing-mono",
     "--cue-font-sans",
     "--cue-font-scale",
-    "--cue-font-theme-mono",
     "--cue-radius-control",
     "--cue-radius-scale",
     "--cue-space-1",
     "--cue-space-2",
     "--cue-space-4",
     "--cue-text-label",
-    "--cue-text-micro"
+    "--cue-text-micro",
+    "--cue-text-ui"
   ],
   "summary": "Section 1 — the four choices that are not token edits at all.",
   "examples": [

package/manifest/components/shape-section.json

@@ -38,17 +38,16 @@
     "--cue-fg-muted",
     "--cue-fg-subtle",
     "--cue-font-mono",
-    "--cue-font-pairing-mono",
     "--cue-font-sans",
     "--cue-font-scale",
-    "--cue-font-theme-mono",
     "--cue-radius-control",
     "--cue-radius-scale",
     "--cue-space-1",
     "--cue-space-2",
     "--cue-space-4",
     "--cue-text-label",
-    "--cue-text-micro"
+    "--cue-text-micro",
+    "--cue-text-ui"
   ],
   "summary": "Section 3 — the geometry and type knobs, which belong to the *density* axis rather than to the theme.",
   "examples": [

package/manifest/components/theme-configurator.json

@@ -89,14 +89,11 @@
     "--cue-fg-muted",
     "--cue-fg-subtle",
     "--cue-font-mono",
-    "--cue-font-pairing-mono",
     "--cue-font-sans",
     "--cue-font-scale",
-    "--cue-font-theme-mono",
     "--cue-icon-sm",
     "--cue-radius-control",
     "--cue-radius-overlay",
-    "--cue-radius-scale",
     "--cue-scrim",
     "--cue-space-1",
     "--cue-space-2",

package/manifest/components/theme-provider.json

@@ -5,21 +5,28 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": true,
-  "description": "Root of the theme system: stamps `data-theme`, `data-density` and `data-mode`\nso the token layer resolves, puts `data-font` on `<html>`, publishes\n`--cue-font-scale`, and owns the persisted user preference.\n\nRendering: `<div data-cue-root data-theme data-density data-mode style={{ colorScheme, --cue-font-scale }}>`\n(or the single child when `asChild`). The `theme`/`density`/`font`/`mode` props are\n*initial* values — the provider holds the state so `setTheme` and friends can\ndrive it — but a changed prop is adopted after mount, so a controlling parent\nstill works.\n\nThe font pairing is the one axis that never lands on this element: it has no\nisland form, `<html>` is its only home, and restating it here would shadow the\npre-paint stamp for the whole page on the first frame. See the `stamp` object\nbelow.\n\nPersistence and the pre-paint contract: setters write\n`{ theme, density, font, mode }` to `localStorage[storageKey]`, which is exactly what\n{@link prepaintScript } reads to stamp `<html>` before the first paint. The\noutermost provider keeps `<html>` in sync while the app runs (and restores the\nprevious stamp on unmount) so the page ground, UA scrollbars and form controls\nfollow the theme; nested providers never touch `<html>`, and never own the\nfont pairing — `useTheme().font` and `setFont` inside one are the root's.",
+  "description": "Root of the theme system: stamps `data-theme`, `data-density` and `data-mode`\nso the token layer resolves, puts `data-font` on `<html>`, publishes\n`--cue-font-scale`, owns the persisted user preference, and publishes the\nregistry the three axis hooks read.\n\nRendering: `<div data-cue-root data-theme data-density data-mode style={{ colorScheme, --cue-font-scale }}>`\n(or the single child when `asChild`). The `theme`/`density`/`font`/`mode` props are\n*initial* values — the provider holds the state so `setTheme` and friends can\ndrive it — but a changed prop is adopted after mount, so a controlling parent\nstill works.\n\nThe font pairing is the one axis that never lands on this element: it has no\nisland form, `<html>` is its only home, and restating it here would shadow the\npre-paint stamp for the whole page on the first frame. See the `stamp` object\nbelow.\n\nPersistence and the pre-paint contract: setters write\n`{ theme, density, font, mode }` to `localStorage[storageKey]`, which is exactly what\n{@link prepaintScript } reads to stamp `<html>` before the first paint. The\noutermost provider keeps `<html>` in sync while the app runs (and restores the\nprevious stamp on unmount) so the page ground, UA scrollbars and form controls\nfollow the theme; nested providers never touch `<html>`, and never own the\nfont pairing — `useTheme().font` and `setFont` inside one are the root's.",
   "props": [
+    {
+      "name": "themes",
+      "type": "readonly ThemeManifest[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "The registry: an ordered array of theme manifests, the first of which is\nthe default theme.\n\nA prop rather than a side effect, so the server render and the client\nrender are handed the same array and nothing depends on which module an app\nhappened to import first. Each entry is a `manifest.json` from a\n`@cueplusplus/theme-<name>` package; this library never discovers a theme by\nitself, because which themes a product ships is an application decision.\n\nOptional for one release, defaulting to `[]` with a development warning. An\napp that registers nothing gets the base axes and no registry: any\nwell-formed name is accepted as a theme (so a visitor's stored preference\nstill restores on first paint), density and font validate against the base\nladder and pairings, and `useTheme().manifest` is `null`. What it *paints*\nis a separate question with a separate answer — whichever `[data-theme]`\nblocks its stylesheets declare, which is the blank base only when none of\nthem declares the stamped name.\n\nA nested provider that passes none inherits the ambient registry.\n\nOne disclosure to be aware of: {@link prepaintScript } inlines the\nregistered **names** — and each theme's `supportsLight` flag, and the names\nof any rung or pairing it adds — into the blocking script in every page's\nHTML, because first paint has to judge a stored preference before any\nmodule loads. No colours, no geometry, no package names, and only what an\napp passes here. But an app that registers\na per-customer theme is publishing that customer's name to every visitor\nwho views source, so register per-customer themes per response rather than\nglobally."
+    },
     {
       "name": "theme",
-      "type": "\"terminal\" | \"cue\" | \"signal\" | \"venu\" | \"hivehub\" | \"dusk\" | \"luma\" | \"snuffle\" | \"requestport\" | \"quotamate\"",
+      "type": "string",
       "required": false,
-      "defaultValue": "cue",
-      "description": "Initial theme preset. Defaults to `\"cue\"`. Changing it after mount adopts the new value."
+      "defaultValue": null,
+      "description": "Initial theme preset. Defaults to the first registered manifest's name, or\n`\"cue\"` with nothing registered. Changing it after mount adopts the new value."
     },
     {
       "name": "density",
       "type": "\"normal\" | \"large\" | \"compact\" | \"ultra-compact\" | \"ultra-large\"",
       "required": false,
-      "defaultValue": "compact",
-      "description": "Initial density level. Defaults to `\"compact\"`."
+      "defaultValue": null,
+      "description": "Initial density level.\n\nDefaults to the rung the active theme's manifest names in\n`densities.default`, and to `\"compact\"` when it names none — spec §5's\nrule, and the same one `resolve()` applies when no rung is wanted, so a\ntheme opens on the rung it prefers whether it is read from JS or painted\nby its own stylesheet. Naming a rung here overrides that for every theme:\na consumer who named one named it deliberately.\n\nChanging it after mount adopts the new value; dropping it does not — a\nparent that stops naming a rung is not asking to move back to the theme's."
     },
     {
       "name": "mode",
@@ -32,8 +39,8 @@
       "name": "font",
       "type": "\"source\" | \"system\" | \"geist\" | \"inter\" | \"plex\" | \"roboto\" | \"apple\" | \"office\"",
       "required": false,
-      "defaultValue": "DEFAULT_FONT",
-      "description": "Initial font pairing. Defaults to `\"system\"` — the platform's own faces,\nnothing downloaded, and the theme keeps whatever monospace it authored.\n\nA pairing that needs delivering is a set of *names*: this library ships no\nfont files, and a pairing nobody delivers falls through its stack to the\nplatform rather than failing. See `FONT_PAIRINGS[font].faces` for the\ncustom properties an app assigns to make one resolve.\n\n**Root-level only.** There is no font island: a nested provider forwards\nthis axis to the root, ignores this prop, and its `setFont` drives the root.\nA page that changed face halfway down is a page with a bug, and a specimen\nthat genuinely wants one — a picker row, a docs page showing all eight —\nneeds nothing from this library but `data-font` on a `<div>`."
+      "defaultValue": null,
+      "description": "Initial font pairing.\n\nDefaults to the pairing the active theme's manifest names in\n`fontPairings.default` — §5's rule, the density prop's rule one axis over\n— and to `\"system\"` when it names none: the platform's own faces, nothing\ndownloaded, and the theme keeps whatever monospace it authored.\n\nA pairing that needs delivering is a set of *names*: this library ships no\nfont files, and a pairing nobody delivers falls through its stack to the\nplatform rather than failing. See `FONT_PAIRINGS[font].faces` for the\ncustom properties an app assigns to make one resolve.\n\n**Root-level only.** There is no font island: a nested provider forwards\nthis axis to the root, ignores this prop, and its `setFont` drives the root.\nA page that changed face halfway down is a page with a bug, and a specimen\nthat genuinely wants one — a picker row, a docs page showing all eight —\nneeds nothing from this library but `data-font` on a `<div>`."
     },
     {
       "name": "fontScale",
@@ -49,6 +56,13 @@
       "defaultValue": null,
       "description": "Optional app-owned font stacks, published as inline CUE font custom properties."
     },
+    {
+      "name": "overrides",
+      "type": "TokenOverrides",
+      "required": false,
+      "defaultValue": null,
+      "description": "Typed token edits layered over the active theme: colours per mode, geometry\nper rung, and the three font stacks.\n\nFor the band of edits that sit below \"publish a theme package\": one accent\nfor a tenant, a stack the app already loads, a rung with two more pixels in\na touch build. Anything larger belongs in a `@cueplusplus/theme-<name>`\npackage, where a build measures it; anything smaller than this is a\n`!important` in a stray stylesheet, which outranks the token layer\neverywhere at once.\n\n**Colours and fonts are inline on this element**, so they inherit down the\nsubtree, beat every stylesheet without `!important`, and are re-stamped\nonto portal containers — which mount on `<body>` and inherit nothing from\nhere. They do not leak *out* of this provider: a nested provider's colour\nedit is scoped to its own subtree, and to portals opened from inside it.\n\n**Densities are one document-scoped `<style>` element**, because a rung is\nselected by attribute rather than inherited, and because\n`useControlHeight()`'s measuring probe hangs off `document.body`, where\na subtree-scoped rule would not reach it — leaving the measured height and\nthe painted control disagreeing by exactly the override. The consequence is\nworth knowing before you nest one: a nested provider's `densities` edit\nreaches the whole page, exactly as a theme's own rung rules do. Colours and\nfonts in the same object do not.\n\nAnd it cuts the other way as well, which is the half that surprises: two\nproviders editing the same rung produce two document-scoped rules of equal\nspecificity, so the **later** one in document order wins everywhere — and\nthe later one is the outer provider's, because a nested provider renders\ninside it. A nested `densities` edit does not merely leak out; an ancestor\nthat edits the same rung overrules it *inside the nested subtree too*. If\nan island needs geometry of its own, it needs a rung of its own — a name no\nancestor is editing — not the same rung with different numbers.\n\nIts rules are `[data-density=\"x\"][data-density=\"x\"]` — (0,2,0), tying a\ntheme's own `[data-theme=\"t\"] [data-density=\"x\"]` and winning on source\norder — so the precedence is: **`overrides`, then the configurator's\npersisted snapshot, then the theme, then base.**\n\n**A font override shadows the pairing for this subtree.** `data-font` is\nthe document's axis and this element deliberately never restates it (see\nthe note by `stamp` below), but `overrides.fonts` writes the resolved\n`--cue-font-*` properties directly, which is a stronger claim than the\nattribute and is the point: this is how an app says \"this product's face,\nwhatever pairing the visitor picked\".\n\nIn development the resulting palette is measured, and any required contrast\npair the edit broke — or made worse — is named on the console."
+    },
     {
       "name": "storageKey",
       "type": "string",
@@ -98,6 +112,7 @@
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [
+    "--cue-font-",
     "--cue-font-mono",
     "--cue-font-sans",
     "--cue-font-scale"
@@ -111,7 +126,7 @@
     },
     {
       "title": "Usage",
-      "code": "<ThemeProvider theme=\"terminal\" density=\"ultra-compact\" font=\"plex\" mode=\"system\">\n  <App />\n</ThemeProvider>",
+      "code": "// `cue` and `terminal` are the `manifest.json` each theme package ships, read\n// from the `…/manifest.json` subpath of `@cueplusplus/theme-cue` and\n// `@cueplusplus/theme-terminal`. Written that way round on purpose: a literal\n// import statement in this comment reads, to every import-graph gate in this\n// repository, as `ui` depending on a theme package — which is the one thing\n// it may not do.\n<ThemeProvider themes={[cue, terminal]} theme=\"terminal\" density=\"ultra-compact\" font=\"plex\" mode=\"system\">\n  <App />\n</ThemeProvider>",
       "language": "tsx"
     }
   ],

package/manifest/components/token-editor.json

@@ -64,11 +64,8 @@
     "--cue-fg-muted",
     "--cue-fg-subtle",
     "--cue-font-mono",
-    "--cue-font-pairing-mono",
     "--cue-font-sans",
     "--cue-font-scale",
-    "--cue-font-theme-mono",
-    "--cue-radius-scale",
     "--cue-space-2",
     "--cue-space-4",
     "--cue-text-label",