@cueplusplus/ui 0.13.0

package/manifest/components/textarea.json

@@ -0,0 +1,104 @@
+{
+  "name": "Textarea",
+  "slug": "textarea",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The multi-line text control.\n\nRendered through Base UI's `Field.Control`, so it joins a {@link Field } on the\nsame terms as {@link Input } — label wiring, `aria-describedby`, `data-invalid`\n— while still being a real `<textarea>`.\n\nWears the recessed chassis minus the fixed control height: a textarea's job is\nto be taller than one rung. Height comes from `rows`, and the user may drag it\ntaller (`resize-y`) but never wider, which would break the panel grid.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "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`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the textarea, when no `FieldLabel` names it. Declared\nhere rather than left to the inherited attribute so the props table carries\nthe row: a bare textarea outside a `Field` has no other way to be named.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "An example of what goes in the box, shown while it is empty. Not a name:\nit disappears on the first keystroke, so pair it with `aria-label` or a\n`FieldLabel`. Declared for the props-table row, as `aria-label` is above.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"textarea\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-focus",
+    "--cue-font-mono",
+    "--cue-leading-ui",
+    "--cue-radius-control",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The multi-line text control.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Textarea placeholder=\"Notes for the operator\" />\n<Field><FieldLabel>Cue notes</FieldLabel><Textarea rows={6} /></Field>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/textarea",
+  "mdUrl": "/docs/components/textarea.md",
+  "jsonUrl": "/r/components/textarea.json",
+  "specimens": [
+    {
+      "title": "Textarea",
+      "group": "forms",
+      "components": [
+        "Textarea"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-3\">\n  <Textarea aria-label=\"Cue notes\" rows={3} defaultValue={\"House to half.\\nHold for VO.\"} />\n  <Textarea aria-label=\"Empty notes\" rows={3} placeholder=\"Notes for the operator\" />\n  <Textarea aria-label=\"Disabled notes\" rows={3} defaultValue=\"Read-only\" disabled />\n</div>",
+      "note": "The same chassis, grown to a block.",
+      "interaction": "same rim and ring as Input: one flush focus-colour ring, no outer halo."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/theme-configurator.json

@@ -0,0 +1,158 @@
+{
+  "name": "ThemeConfigurator",
+  "slug": "theme-configurator",
+  "group": "configurator",
+  "importPath": "@cueplusplus/ui/configurator",
+  "peerDependencies": [
+    "react-aria-components"
+  ],
+  "clientOnly": true,
+  "description": "The floating theme configurator: the panel that edits the design system it is\ndrawn with.\n\nIt is a **component**, not a devtool bolted onto the kitchensink — mount it in\nany app behind a flag and a designer can retune that app's theme in place. The\nwhole thing rests on one rule, and the rule is what keeps it from being a toy:\n*everything it does is a `--cue-*` declaration in one stylesheet.* No inline\nstyles on the root, no parallel token vocabulary, no runtime theme engine. The\nCSS it exports is byte for byte the CSS the page is wearing, which is the only\nreason the export dialog can promise a round trip at all.\n\nWhat it owns:\n\n- **Preset, mode and density** are the provider's, driven through `useTheme()`\n  so a switch restamps `<html>`, every portal, and the persisted preference.\n- **Colour, type and geometry overrides** go into\n  `<style id=\"cue-configurator-overrides\">`, scoped so they win where they\n  have to and lose where they should — the cascade reasoning is in\n  `_overrides.ts`, and it is the interesting part of this group.\n- **Text scale and root zoom**, the two relief valves the density ladder is\n  paired with.\n- **Its own placement**, furled state and every override, in `localStorage`\n  under one key.\n\nRenders in place as a `position: fixed` region, so mount it inside the\nprovider — it needs the theme context — but outside any transformed ancestor,\nwhich would turn `fixed` into `absolute` and take the panel with the page.",
+  "props": [
+    {
+      "name": "position",
+      "type": "\"floating\" | \"docked-right\"",
+      "required": false,
+      "defaultValue": null,
+      "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\"`.",
+      "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.",
+      "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`.",
+      "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\"`.",
+      "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.",
+      "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`.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "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.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-lg",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-font-sans",
+    "--cue-icon-sm",
+    "--cue-leading-ui",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The floating theme configurator: the panel that edits the design system it is drawn with.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ThemeProvider>\n  <App />\n  {devMode ? <ThemeConfigurator /> : null}\n</ThemeProvider>\n<ThemeConfigurator position=\"docked-right\" onChange={(tokens) => report(tokens)} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/theme-configurator",
+  "mdUrl": "/docs/components/theme-configurator.md",
+  "jsonUrl": "/r/components/theme-configurator.json",
+  "todo": true
+}

package/manifest/components/theme-provider.json

@@ -0,0 +1,228 @@
+{
+  "name": "ThemeProvider",
+  "slug": "theme-provider",
+  "group": "system",
+  "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`, 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`), plus `data-style` when — and only when —\na style set is in force. The `theme`/`density`/`font`/`mode`/`styleSet` 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]`, plus a `style`\nkey holding the style set when there is one — omitted entirely when there is\nnot, so an application that never touches that axis writes the same four-key\nobject it always wrote. That 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": "string",
+      "required": false,
+      "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": 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`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "system",
+          "dark",
+          "light"
+        ]
+      }
+    },
+    {
+      "name": "font",
+      "type": "\"source\" | \"system\" | \"geist\" | \"inter\" | \"plex\" | \"roboto\" | \"apple\" | \"office\"",
+      "required": false,
+      "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": "styleSet",
+      "type": "\"console\" | \"editorial\" | \"marketing\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Page composition for this subtree: `console`, `editorial` or `marketing`.\n\n**`styleSet`, not `style`.** This interface already has a\n`style?: React.CSSProperties` a few lines below, applied to the provider\nroot, and a second meaning for that name would be the one collision every\nconsumer of this component would have to think about. The DOM attribute is\n`data-style`, matching the four public axes — `data-cue-*` is this tree's\nprefix for *internal* attributes (`data-cue-theme`, `data-cue-fidelity`), and\na public axis wearing the internal prefix would be the more confusing of the\ntwo mistakes.\n\nUnset, **no attribute is stamped at all**, and that is the promise: an\napplication that has never heard of this axis renders the markup it rendered\nbefore it existed and stores the preference object it stored before it\nexisted. A style set is opt-in page composition, not a fourth thing every\npage has.\n\nLike the other three axes this is an *initial* value the provider then holds\nas state, so `setStyleSet` can drive it; a changed prop is adopted after\nmount. Unlike the font pairing it has an island form, so a nested provider\nholds its own rather than handing the axis up to the root.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "console",
+          "editorial",
+          "marketing"
+        ]
+      }
+    },
+    {
+      "name": "fontScale",
+      "type": "number",
+      "required": false,
+      "defaultValue": "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.",
+      "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.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "persistPreferences",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "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>`.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "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.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The application subtree.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-font-mono",
+    "--cue-font-sans",
+    "--cue-font-scale"
+  ],
+  "summary": "The root that stamps theme, density and mode, and publishes the setters.",
+  "examples": [
+    {
+      "title": "The document root",
+      "code": "<html lang=\"en\" suppressHydrationWarning>\n  <head>\n    <script dangerouslySetInnerHTML={{ __html: prepaintScript() }} />\n  </head>\n  <body>\n    <ThemeProvider theme=\"terminal\" density=\"normal\">\n      {children}\n    </ThemeProvider>\n  </body>\n</html>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "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"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/theme-provider",
+  "mdUrl": "/docs/components/theme-provider.md",
+  "jsonUrl": "/r/components/theme-provider.json",
+  "whenToUse": [
+    "Once at the root of an app, around everything that renders a component.",
+    "Around a subtree that has to render in a fixed preset, such as a theme preview pane."
+  ],
+  "whenNotToUse": [
+    "Changing geometry for one region. Use `Density`, which stamps the density attribute and leaves colour alone.",
+    "Holding app state. It owns theme, density and mode, and nothing else."
+  ],
+  "commonMistakes": [
+    "Leaving `prepaintScript()` out of the document head, which paints the default theme for one frame and then flips.",
+    "Mounting two providers on the same `storageKey`, which makes them fight over the stored preference."
+  ]
+}

package/manifest/components/thinking-indicator.json

@@ -0,0 +1,69 @@
+{
+  "name": "ThinkingIndicator",
+  "slug": "thinking-indicator",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A live status line that names what the agent is doing right now, with elapsed time.",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "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.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"label\" | \"elapsed\"> & {\n  /** What the agent is doing right now. Swapping it replays the entrance animation. */\n  label: string;\n  /** Elapsed time rendered in mono next to the label. Omit to hide the timer. */\n  elapsed?: string;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-stream",
+    "--cue-text-body"
+  ],
+  "summary": "A live status line that names what the agent is doing right now, with elapsed time.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ThinkingIndicator } from \"@cueplusplus/ui/elements\";\n\n<ThinkingIndicator label=\"Reading thread.tsx\" elapsed=\"12s\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/thinking-indicator",
+  "mdUrl": "/docs/components/thinking-indicator.md",
+  "jsonUrl": "/r/components/thinking-indicator.json",
+  "specimens": [
+    {
+      "title": "ThinkingIndicator",
+      "group": "elements-thread",
+      "components": [
+        "ThinkingIndicator"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"reading\" wide>\n    <ThinkingIndicator label=\"Reading front-truss.gdtf\" elapsed=\"0:04\" />\n  </Specimen>\n  <Specimen label=\"patching, no clock\" wide>\n    <ThinkingIndicator label=\"Patching universe 3\" />\n  </Specimen>\n</Specimens>",
+      "note": "One line that says what is happening right now, with the elapsed clock beside it. The label is keyed, so replacing it re-runs the entrance and the change reads as a change rather than as a re-render.",
+      "interaction": "none. It is a status line, not a control — the dot pulses and the label sweeps, and both stop for a reduced-motion reader."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/thread-list.json

@@ -0,0 +1,87 @@
+{
+  "name": "ThreadList",
+  "slug": "thread-list",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Conversation history with unread marks and actions that wait for hover.",
+  "props": [
+    {
+      "name": "threads",
+      "type": "readonly ThreadItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Conversation rows with title, time, and optional unread mark.",
+      "control": {
+        "kind": "array",
+        "fixture": "composer.threads"
+      }
+    },
+    {
+      "name": "activeIndex",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "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.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"threads\" | \"activeIndex\" | \"onActiveIndexChange\"\n> & {\n  /** Conversation rows with title, time, and optional unread mark. */\n  threads: readonly ThreadItem[];\n  /** Index of the currently selected thread. An index outside the list selects nothing. */\n  activeIndex: number;\n  /** Called when the user clicks a thread row. */\n  onActiveIndexChange?: (index: number) => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "Conversation history with unread marks and actions that wait for hover.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ThreadList } from \"@cueplusplus/ui/elements\";\n\n<ThreadList\n  threads={[\n    { title: \"Composer polish\", time: \"2m\", unread: true },\n    { title: \"Runtime migration\", time: \"1h\" },\n  ]}\n  activeIndex={activeIndex}\n  onActiveIndexChange={setActiveIndex}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/thread-list",
+  "mdUrl": "/docs/components/thread-list.md",
+  "jsonUrl": "/r/components/thread-list.json",
+  "specimens": [
+    {
+      "title": "ThreadList",
+      "group": "elements-composer",
+      "components": [
+        "ThreadList"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"one open\">\n    <ThreadList threads={THREADS} activeIndex={thread} onActiveIndexChange={setThread} />\n  </Specimen>\n  <Specimen label=\"nothing open\">\n    <ThreadList threads={THREADS} activeIndex={-1} />\n  </Specimen>\n</Specimens>",
+      "note": "Conversation history at its smallest: a title, how long ago, and an unread dot. The row's actions replace the timestamp on hover rather than sitting beside it, which is what keeps a 240px rail from becoming a toolbar — and the active row never shows an unread mark, because reading it is what cleared it.",
+      "interaction": "the selected row carries `aria-current`; the rename and delete affordances appear on hover in the space the time was using, so nothing moves when they arrive."
+    }
+  ],
+  "todo": true
+}