@cueplusplus/ui 0.8.0 → 0.10.0

package/manifest/components/textarea.json

@@ -12,14 +12,20 @@
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Extra classes, merged over the chassis."
+      "description": "Extra classes, merged over the chassis.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "rows",
       "type": "number",
       "required": false,
       "defaultValue": "3",
-      "description": "Visible rows before the box starts scrolling. Defaults to `3`."
+      "description": "Visible rows before the box starts scrolling. Defaults to `3`.",
+      "control": {
+        "kind": "number"
+      }
     }
   ],
   "typeReferences": [
@@ -30,7 +36,6 @@
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [
-    "--cue-accent",
     "--cue-border",
     "--cue-border-strong",
     "--cue-control-lg",

package/manifest/components/theme-configurator.json

@@ -14,63 +14,101 @@
       "type": "\"floating\" | \"docked-right\"",
       "required": false,
       "defaultValue": null,
-      "description": "Placement, controlled. Pair with `onPositionChange`."
+      "description": "Placement, controlled. Pair with `onPositionChange`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "floating",
+          "docked-right"
+        ]
+      }
     },
     {
       "name": "defaultPosition",
       "type": "\"floating\" | \"docked-right\"",
       "required": false,
       "defaultValue": "floating",
-      "description": "Initial placement. A stored one wins. Defaults to `\"floating\"`."
+      "description": "Initial placement. A stored one wins. Defaults to `\"floating\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "floating",
+          "docked-right"
+        ]
+      }
     },
     {
       "name": "onPositionChange",
       "type": "((position: ConfiguratorPosition) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called when the user docks or floats the panel."
+      "description": "Called when the user docks or floats the panel.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "defaultCollapsed",
       "type": "boolean",
       "required": false,
       "defaultValue": "false",
-      "description": "Start furled to the title bar. A stored value wins. Defaults to `false`."
+      "description": "Start furled to the title bar. A stored value wins. Defaults to `false`.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "storageKey",
       "type": "string",
       "required": false,
       "defaultValue": "cue-configurator",
-      "description": "`localStorage` key holding the overrides, the placement and the zoom.\nDefaults to `\"cue-configurator\"`."
+      "description": "`localStorage` key holding the overrides, the placement and the zoom.\nDefaults to `\"cue-configurator\"`.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "onChange",
       "type": "((tokens: Record<string, string>) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called with the full resolved `--cue-*` map — never a diff — whenever the\noverrides, the theme or the mode change, and once on mount."
+      "description": "Called with the full resolved `--cue-*` map — never a diff — whenever the\noverrides, the theme or the mode change, and once on mount.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "zoomShortcuts",
       "type": "boolean",
       "required": false,
       "defaultValue": "true",
-      "description": "Bind ⌘/Ctrl with `+`, `-` and `0` to the zoom valve. Defaults to `true`."
+      "description": "Bind ⌘/Ctrl with `+`, `-` and `0` to the zoom valve. Defaults to `true`.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "title",
       "type": "ReactNode",
       "required": false,
       "defaultValue": "Theme",
-      "description": "Panel heading. Defaults to `\"Theme\"`."
+      "description": "Panel heading. Defaults to `\"Theme\"`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
     },
     {
       "name": "className",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Extra classes for the panel."
+      "description": "Extra classes for the panel.",
+      "control": {
+        "kind": "string"
+      }
     }
   ],
   "typeReferences": [],
@@ -79,7 +117,6 @@
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [
-    "--cue-accent",
     "--cue-accent-soft",
     "--cue-border",
     "--cue-border-overlay",
@@ -89,14 +126,10 @@
     "--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,91 +5,170 @@
   "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.",
+      "control": {
+        "kind": "array"
+      }
+    },
     {
       "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.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "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.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "normal",
+          "large",
+          "compact",
+          "ultra-compact",
+          "ultra-large"
+        ]
+      }
     },
     {
       "name": "mode",
       "type": "\"system\" | \"dark\" | \"light\"",
       "required": false,
       "defaultValue": "dark",
-      "description": "Initial mode. Defaults to `\"dark\"`; `\"system\"` tracks `prefers-color-scheme`."
+      "description": "Initial mode. Defaults to `\"dark\"`; `\"system\"` tracks `prefers-color-scheme`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "system",
+          "dark",
+          "light"
+        ]
+      }
     },
     {
       "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>`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "source",
+          "system",
+          "geist",
+          "inter",
+          "plex",
+          "roboto",
+          "apple",
+          "office"
+        ]
+      }
     },
     {
       "name": "fontScale",
       "type": "number",
       "required": false,
       "defaultValue": "1",
-      "description": "Multiplier on every text token, published as `--cue-font-scale`. Defaults to `1`."
+      "description": "Multiplier on every text token, published as `--cue-font-scale`. Defaults to `1`.",
+      "control": {
+        "kind": "number"
+      }
     },
     {
       "name": "fontFamilies",
       "type": "FontFamilies",
       "required": false,
       "defaultValue": null,
-      "description": "Optional app-owned font stacks, published as inline CUE font custom properties."
+      "description": "Optional app-owned font stacks, published as inline CUE font custom properties.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "opaque"
+      }
     },
     {
       "name": "storageKey",
       "type": "string",
       "required": false,
       "defaultValue": "cue-ui",
-      "description": "localStorage key holding `{ theme, density, font, mode }`. Defaults to `\"cue-ui\"`.\nOnly the outermost provider reads or writes it — a nested provider is an\nisland whose explicit props are the point, not a second preference store."
+      "description": "localStorage key holding `{ theme, density, font, mode }`. Defaults to `\"cue-ui\"`.\nOnly the outermost provider reads or writes it — a nested provider is an\nisland whose explicit props are the point, not a second preference store.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "persistPreferences",
       "type": "boolean",
       "required": false,
       "defaultValue": "true",
-      "description": "Restore and write root preferences in localStorage. Defaults to `true`."
+      "description": "Restore and write root preferences in localStorage. Defaults to `true`.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "asChild",
       "type": "boolean",
       "required": false,
       "defaultValue": "false",
-      "description": "Stamp the single child element instead of rendering a wrapper `<div>`."
+      "description": "Stamp the single child element instead of rendering a wrapper `<div>`.",
+      "control": {
+        "kind": "boolean"
+      }
     },
     {
       "name": "className",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Extra classes for the provider root."
+      "description": "Extra classes for the provider root.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "style",
       "type": "CSSProperties",
       "required": false,
       "defaultValue": null,
-      "description": "Inline styles for the provider root, merged after the token style."
+      "description": "Inline styles for the provider root, merged after the token style.",
+      "control": {
+        "kind": "opaque"
+      }
     },
     {
       "name": "children",
       "type": "ReactNode",
       "required": false,
       "defaultValue": null,
-      "description": "The application subtree."
+      "description": "The application subtree.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
     }
   ],
   "typeReferences": [],
@@ -111,7 +190,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/thinking-indicator.json

@@ -12,14 +12,20 @@
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "What the agent is doing right now. Swapping it replays the entrance animation."
+      "description": "What the agent is doing right now. Swapping it replays the entrance animation.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "elapsed",
       "type": "string",
       "required": false,
       "defaultValue": null,
-      "description": "Elapsed time rendered in mono next to the label. Omit to hide the timer."
+      "description": "Elapsed time rendered in mono next to the label. Omit to hide the timer.",
+      "control": {
+        "kind": "string"
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/thread-list.json

@@ -14,21 +14,31 @@
       "type": "readonly ThreadItem[]",
       "required": true,
       "defaultValue": null,
-      "description": "Conversation rows with title, time, and optional unread mark."
+      "description": "Conversation rows with title, time, and optional unread mark.",
+      "control": {
+        "kind": "array"
+      }
     },
     {
       "name": "activeIndex",
       "type": "number",
       "required": true,
       "defaultValue": null,
-      "description": "Index of the currently selected thread. An index outside the list selects nothing."
+      "description": "Index of the currently selected thread. An index outside the list selects nothing.",
+      "control": {
+        "kind": "number"
+      }
     },
     {
       "name": "onActiveIndexChange",
       "type": "((index: number) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called when the user clicks a thread row."
+      "description": "Called when the user clicks a thread row.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     }
   ],
   "typeReferences": [

package/manifest/components/thread-search.json

@@ -14,35 +14,52 @@
       "type": "readonly SearchableThread[]",
       "required": true,
       "defaultValue": null,
-      "description": "All threads. Filtering matches title and preview together."
+      "description": "All threads. Filtering matches title and preview together.",
+      "control": {
+        "kind": "array"
+      }
     },
     {
       "name": "query",
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "Current search text."
+      "description": "Current search text.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "activeId",
       "type": "string",
       "required": true,
       "defaultValue": null,
-      "description": "Which thread is open."
+      "description": "Which thread is open.",
+      "control": {
+        "kind": "string"
+      }
     },
     {
       "name": "onQueryChange",
       "type": "((query: string) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called as the search is typed."
+      "description": "Called as the search is typed.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     },
     {
       "name": "onSelect",
       "type": "((id: string) => void)",
       "required": false,
       "defaultValue": null,
-      "description": "Called when a thread is opened."
+      "description": "Called when a thread is opened.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
     }
   ],
   "typeReferences": [