@cueplusplus/ui 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,323 @@
 # @cueplusplus/ui
 
+## 0.11.0
+
+### Minor Changes
+
+- 8a41dcb: Three new components — `Preview`, `Inspector` and `CodeBlock`, each also exported from the root
+  barrel — plus a layout fix to `Bento.Tile` and newly documented `aria-label` and `placeholder`
+  props on the text inputs and `Toggle`.
+
+  **Nothing to do: every addition is a new export, and nothing that already compiled changed.** The
+  snippets below are fragments; each component has a full, copy-paste quick start in the package
+  README (`node_modules/@cueplusplus/ui/README.md`).
+
+  **`Preview`** (`@cueplusplus/ui/layout`) frames one component: a stage that can carry its own
+  theme, a slot for tools at the top right, and a footer. `label` is required, because the frame is
+  a `role="group"` named by it.
+
+  ```tsx
+  import { Chip } from "@cueplusplus/ui";
+  import { Preview } from "@cueplusplus/ui/layout";
+
+  <Preview label="Chip preview" theme="terminal" density="compact" resizable>
+    <Chip tone="accent">Standby</Chip>
+  </Preview>;
+  ```
+
+  - **The stage is a theme island; the chrome is not.** `theme`, `mode`, `density` and `font` land
+    on the stage and nowhere else. `tools`, `footer`, the resize grips and anything they open stay in
+    the page's scope. With none of the four set, the stage carries no attribute at all and inherits
+    the page.
+  - **Naming a theme does not load it.** The stage is scoped with `[data-theme="<name>"]`, so that
+    theme's stylesheet (`@cueplusplus/theme-<name>/theme.css`) must already be on the page.
+  - A stage `mode` with no `theme` restates the page's theme beside it, and a stage `theme` with no
+    `mode` repeats the page's mode, because a theme's light block is one compound selector. A stage
+    `density` names the nearest theme, as `<Density>` does.
+  - Overlays opened on the stage follow its theme, mode and density. A font pairing stops at the
+    stage: portals keep the page's. A stage that sets `theme` or `mode` also keeps the page's
+    `ThemeProvider` `overrides` off those overlays, so a popover matches the stage it opened from.
+    Inside a stage whose `mode` is `"dark"` or `"light"`, `useTheme().resolvedMode` reports that
+    mode; with `"system"` it reports the page's.
+  - Changing `theme`, `mode`, `density` or `font` keeps the specimen mounted, so its uncontrolled
+    state — a typed value, an open disclosure — survives the switch.
+  - The specimen sits centred on a dot grid. One wider than the stage keeps its start edge in view
+    and the frame scrolls to the rest. The stage reserves a minimum height before its specimen
+    loads, and with no `footer` its bottom corners follow the frame's rounded border.
+  - **The tools never cover the specimen.** With `tools`, the stage reserves their corner: it pads
+    its top by the tools' whole depth, measured in the page's density where the tools are drawn,
+    so a stage given a `density` of its own still clears them. The stage reserves this space only
+    when `tools` is set; a Preview without tools draws exactly the same markup.
+
+  `resizable` makes the stage resizable by pointer and keyboard:
+
+  - `resizable` (`true`, or `{ axis, minWidth, maxWidth, minHeight, maxHeight }`) adds a grip on
+    each axis, within 160–1280 × 96–960 px by default; `axis: "x"` or `"y"` keeps one. Each edge grip
+    is a focusable `separator` valued in pixels: arrow keys step 8 px, Shift+arrow 64 px, and
+    Home/End jump to the bounds. A corner grip drags both axes with the pointer, a double-click
+    resets an axis (the corner resets both), and a `W × H` readout shows while dragging.
+  - A resizable Preview fills its container's width. Its width bound in force is the smaller of
+    `maxWidth` and the frame's own width, re-measured with a `ResizeObserver`, so it stays inside a
+    grid track as the viewport changes; a frame narrower than `minWidth` lowers the floor with it,
+    and a width a reader chose comes back when the track widens again. The height is bounded by
+    `maxHeight` alone, and a taller stage grows the frame.
+  - An axis nobody has resized follows the stage's natural size live — a specimen that grows after
+    it loads, a track that widens, a Preview mounted hidden and shown later — and is drawn within the
+    same bounds its grip announces, so the first key press or drag starts from what is on screen.
+  - Without `resizable` there are no grips, and nothing is measured or observed. `Preview` is a
+    client component (`"use client"`).
+
+  **`Inspector`** (`@cueplusplus/ui/chrome`) is the layout of a settings panel, a properties sidebar
+  or a wrench menu: titled sections of label-and-control rows, with a footer. The controls are the
+  library's own.
+
+  ```tsx
+  import { Inspector } from "@cueplusplus/ui/chrome";
+
+  <Inspector.Root>
+    <Inspector.Section label="Variants">
+      <Inspector.Row label="Size">
+        <SegmentedControl items={sizes} />
+      </Inspector.Row>
+      <Inspector.Row label="Label" htmlFor="label">
+        <Input id="label" />
+      </Inspector.Row>
+    </Inspector.Section>
+    <Inspector.Footer note="preset · primary" action={<Button>Reset</Button>} />
+  </Inspector.Root>;
+  ```
+
+  - `Inspector.Section` takes a `label`, drawn as a `SectionHeader` and used as the group's name.
+  - `Inspector.Row` is one column until the Inspector itself is 18rem wide, then label beside
+    control. It is a container query, so a row follows the width of the popover or sidebar it sits
+    in, not the viewport's.
+  - **How a row names its control.** With `htmlFor`, the label is a `<label>` for that id. Without
+    it, the row lays its `label` on the control as `aria-label`, but only when the control is a
+    single element not already named by `aria-label` or `aria-labelledby`; text, lists and fragments
+    are left as they are. The row has no role of its own and never names itself, so a
+    `SegmentedControl`, which is already a group, is not announced twice.
+  - `Inspector.Footer` puts a quiet `note` at the start and one `action` at the end. A lone `action`
+    still sits at the end edge.
+  - Static markup — no hooks, no `"use client"` — so a server component can render it.
+
+  **`CodeBlock`** (`@cueplusplus/ui/instruments`) is a block of code with a caption and a copy
+  button, and no syntax-highlighter palette.
+
+  ```tsx
+  import { CodeBlock } from "@cueplusplus/ui/instruments";
+
+  <CodeBlock
+    label="JSX"
+    language="jsx"
+    code={'<Button variant="primary">Take cue</Button>'}
+  />;
+  ```
+
+  - `code` is printed verbatim, and the copy button copies exactly that. `label` is the caption and
+    defaults to the language. `language` defaults to `"tsx"` and lands on the `<pre>` as
+    `data-language`.
+  - `language="jsx"` adds emphasis in three inks the theme already has: tag names in `--cue-fg`,
+    attribute names in `--cue-fg-muted`, punctuation in `--cue-fg-subtle`. It reads string literals
+    whole, so a brace or a `<` inside a quoted string does not break it, and a `{…}` expression child
+    stays plain. Every other language prints plain.
+  - No directive: the copy button is its only client code, so a server page can render the rest.
+
+  **Changes to existing components:**
+
+  - **`Bento.Tile`**: a long `eyebrow` now truncates on one line instead of running under the tile's
+    `meta` and `action` in a narrow track. This is the only runtime change to an existing component.
+  - **`Input`** (and with it `PasswordInput` and `SearchInput`) and **`Textarea`** now declare
+    `aria-label` and `placeholder` in their props, and **`Toggle`** declares `aria-label`. This is
+    documentation only: all of them were already accepted as inherited HTML attributes and forwarded
+    to the element, so nothing you pass behaves differently. They now have rows in the props table
+    and in the manifest.
+
+  **Manifest.** `manifest/manifest.json` indexes the three new components, and
+  `manifest/components/{preview,inspector,code-block}.json` are new. The records for `input`,
+  `password-input`, `search-input`, `textarea` and `toggle` were regenerated with their new rows.
+  `manifest/fixtures.json` gains `children.label` ("A short label"), a one-word text fixture for a
+  playground or propSet to pick by hand; no prop's `control.fixture` names it.
+
+### Patch Changes
+
+- @cueplusplus/tokens@0.11.0
+
+## 0.10.0
+
+### Minor Changes
+
+- ddce99e: `@cueplusplus/ui/layout` — and the root barrel with it — now exports `Bento`, a grid of unequal
+  tiles whose span is a prop on the tile rather than a class you count out on the container.
+
+  **Nothing to do: it is a new export, and nothing that already compiled changed.** Adopt it where
+  you were writing a bare grid and hand-counting `col-span-*`:
+
+  ```tsx
+  import { Bento } from "@cueplusplus/ui/layout";
+
+  <Bento.Root cols={3} rows={2} gap={5}>
+    <Bento.Tile span={2} rowSpan={2} minHeight="hero" title="Kitchen sink">
+      Every component, on one page.
+    </Bento.Tile>
+    <Bento.Tile href="/docs/components" title="Components">
+      Props, variants and a live example.
+    </Bento.Tile>
+  </Bento.Root>;
+  ```
+
+  `Bento.Root` takes `cols` (2, 3 or 4; defaults to 3), `rows` (1–4), `dense`, and a `gap` off the
+  density space ladder (defaults to `4`). `Bento.Tile` takes a `span` (1–4) and a `rowSpan` (1–2)
+  from closed sets, plus `minHeight`, `eyebrow`, `title` and `meta`. The container clamps every span
+  to its own tracks on the way past — the columns always, and the rows wherever it declared any. The
+  column clamp is per breakpoint, because every bento is two tracks wide between 640 px and 1024 px
+  whatever it was asked for, and CSS Grid answers an over-wide span by growing an implicit track
+  rather than by refusing it.
+
+  Two things a props table cannot show you, both of them compile-time where a compiler can reach:
+
+  - **A tile is one thing or the other, in the type.** Either a **link** — `href`, optionally with
+    `render`, a router's own element which is cloned, keeps its own `href` because `next/link`
+    requires it to declare one, and has its `className` merged with the tile's rather than replaced
+    — whose whole surface is a single `<a>` and whose content is therefore static. Or a **panel**,
+    whose children may be live and whose link or control is a visible sibling in `action`. `href`
+    and `action` are mutually exclusive in the type, and a dev-time `console.error` names any tile
+    that puts an interactive child inside an anchor.
+  - **Static markup throughout** — no hooks and no `"use client"` — so a server component can draw a
+    bento without opening a client boundary. That is why the router escape hatch is an element to
+    clone rather than a render function: a directive is per module, and the hook that reads a render
+    function is a hook.
+
+  `manifest/manifest.json` and the new `manifest/components/bento.json` were regenerated with it.
+
+- 16d2cae: `@cueplusplus/ui/system` now exports `isSafeTokenValue(value: string): boolean` — whether a string
+  may be written into the density stylesheet `ThemeProvider` builds from its `overrides` prop.
+
+  **Nothing to do.** Nothing about that stylesheet changed: this is the rule `overridesCss()` has
+  always applied, exported. Adopt it if you assemble a `TokenOverrides` out of anything a person or
+  an API supplies, so a value is refused at your own input rather than discovered from a
+  `console.warn` one render later, with half of what you built never having reached the sheet:
+
+  ```ts
+  import {
+    isSafeTokenValue,
+    type TokenOverrides,
+  } from "@cueplusplus/ui/system";
+
+  isSafeTokenValue("Iosevka, monospace"); // → true
+  isSafeTokenValue("red;}"); // → false
+  ```
+
+  It lands against `./system`'s standing policy — that the prop's _shape_ is public while
+  `inlineOverrides()`, `overridesCss()` and `OverridesContext` stay internal, because a consumer
+  reaching for those would be writing the custom properties by hand — and it lands on the right side
+  of it: a _writer_ of custom properties is what the policy excludes, and a _reader_ that refuses a
+  value before it is ever written is the opposite of one. `@cueplusplus/ui/configurator`'s
+  `isSafeCssValue` is unchanged and unmoved; it is the same rule behind a subpath that also carries
+  `ThemeConfigurator`, `ExportDialog` and an optional `react-aria-components` peer, and a caller
+  that only wants the question answered should not have to take that graph to ask it.
+
+- 88cf751: The component manifest's `schemaVersion` is now `2`, and every `PropDoc` in it — root props and
+  every compound part's props alike — carries a required `control`: `{ kind, members?, min?, max?,
+nullable?, fixture? }`, where `kind` is one of `boolean`, `enum`, `number`, `string`, `node`,
+  `callback`, `array`, `object` or `opaque`. It answers the question `type` never could: _what edits
+  this prop_.
+
+  **What a reader of `manifest.json` must change: the version pin, and nothing else.** A consumer
+  that asserts `schemaVersion === 1` will reject every document this release publishes and has to
+  move to `2`; a consumer that ignores the field keeps working once the pin moves. Both published
+  manifests (`manifest/manifest.json` and every document under `manifest/components/`) were
+  regenerated, as was `manifest/tokens.json`, whose `schemaVersion` moves with them — so all three
+  have to be read at the same version.
+
+  A `variant` prop's `members` are its `cva` recipe's, in the recipe's order; a numeric literal union
+  carries its own `min`/`max`, and a prop whose JSDoc states a range with `@min`/`@max` carries that;
+  a union with an explicit `| null` is `nullable`.
+
+  ## Migrating
+  - **`type` is unchanged.** It still prints the TypeScript type verbatim, literal unions included,
+    and it is still the field to render when a reader wants to know what a prop _is_. `control` is a
+    new field beside it, not a replacement for it: nothing was renamed and nothing was removed.
+  - **A consumer pinned to `schemaVersion === 1` must move to `2`.** The number changed because
+    `control` is _required_: a consumer that reads it needs to know whether the document it fetched
+    has one, and an optional field could never tell it — absent would mean both "no control" and
+    "an older manifest". A consumer that ignores the field keeps working after changing the pin.
+
+### Patch Changes
+
+- c469f49: `Button` now **declares** `children` in `ButtonProps`, so the published manifest documents it and
+  the props table has a row for it.
+
+  **Nothing to do.** The component did not change — it has always taken children, through
+  `React.ComponentPropsWithoutRef<"button">`. What changed is what the package says about itself:
+  docgen documents a prop only where the library declares it, so the system's most used control
+  published no `children` at all. The page did not list it, and a propSet could not name it, which
+  is how `/play/button` came to preview an unlabelled `<button>` behind a standing accessibility
+  exemption. Declaring it is what lets that exemption expire.
+
+  If you read `manifest/components/button.json` to generate code or to drive a playground,
+  `children` is now in `props` and can be set like any other prop.
+
+- 481e8c5: `manifest/components/ledger.json` said `Ledger` could not fold. It can, and the note now says so.
+
+  **Nothing to do unless you read the manifest.** No API changed, no component moved, and nothing
+  you have written needs editing. The documentation that ships inside the package described the
+  plain bench as having "no disclosure anywhere — the ledger does not collapse", which was true
+  before 0.8.0 and false in it: `collapsible` puts a real
+  `button[aria-expanded aria-controls]` inside the `h2`/`h3` and folds the run of rows below it.
+
+  The corrected note says what shipped — folding is opt-in per heading, and a ledger nobody asks to
+  fold still emits no control and no expansion state at all. The manifest is the only published
+  surface this touches.
+
+- 64b4bab: Every package manifest's `repository` field now names `cueplusplus/cue-ui`, following the
+  repository's rename from an earlier working title.
+
+  **Nothing to do.** No code, no exports, no types, and no package name: the scope is the
+  organisation, not the repository, so every specifier you already import is the one you keep
+  importing. What moves is metadata — GitHub Packages matches a package to a repository through that
+  field, so from this release the "source" link on each package's registry page, and the repository
+  the next publish is attributed to, name `cue-ui`. The `directory` beside it is unchanged, so each
+  link still lands on that package rather than on the monorepo root.
+
+  If you have a bookmark or a script pointing at the old URL, GitHub's rename redirect answers it;
+  updating it to `https://github.com/cueplusplus/cue-ui` is tidiness rather than repair.
+
+- 3471a15: `tokensUsed` in the published component manifest is now scanned from code rather than from bytes,
+  so it stops attributing tokens to components that never resolve them.
+
+  **What to do: re-read the manifest before you trust a `tokensUsed` list you cached.** No API
+  changed and nothing you render moves, but the manifest says something different about 48 of 321
+  components, and the old answer was padded — in thirteen cases wholly wrong. If you read
+  `tokensUsed` to decide which tokens to define when restyling a component, the list you had was
+  too wide. It is narrower now, and true.
+
+  The scanner matched `--cue-*` anywhere in a file's text, comments included. A docblock sentence
+  naming a token published it as one the component uses, and a sentence arguing _against_ one
+  published the opposite of what it said: `forms/_chassis.ts` explains that the ring reads
+  `--cue-focus`, **not** `--cue-accent`, and eleven controls on that chassis published
+  `--cue-accent` because of it.
+
+  What moved, exactly:
+
+  - **Thirty-four components lose one to four tokens they never painted.**
+  - **Thirteen now correctly publish none** — `agent-surface`, `animated-number`,
+    `chart-container` and the ten container icons — because their lists were comment-derived in
+    their entirety: they paint through classes rather than resolving custom properties by name, and
+    the ten icons render no `className` at all. An empty array renders as no Tokens section rather
+    than an empty one, which is what the four components that already shipped one do.
+  - **One gains four.** `MarkdownText` painted `--cue-accent`, `--cue-fg`, `--cue-fg-muted` and
+    `--cue-fg-subtle` and published none of them: the literal pass pairs quotes across the whole
+    file, and the apostrophes in that file's prose desynced the pairing so the class strings below
+    were read as the insides of strings. Blanking the comments re-pairs them.
+  - **Two entries that were never tokens are gone**, `--cue-icon-` and `--cue-space-`: the regex had
+    been stopping at the `*` in `--cue-icon-*` and the `$` in `gap-(--cue-space-${n})`.
+
+- Updated dependencies [64b4bab]
+- Updated dependencies [362cdda]
+- Updated dependencies [c2238cc]
+  - @cueplusplus/tokens@0.10.0
+  - @cueplusplus/theme-base@1.0.1
+
 ## 0.9.0
 
 ### Minor Changes
@@ -289,6 +607,25 @@
 
 ### Patch Changes
 
+- edb938d: `Table.Row interactive` draws a focus ring. The prop supplied the
+  pointer half — the row-hover wash and a pointer cursor — and nothing for
+  focus, while the row-activation reading above tells a caller to put `tabIndex`
+  on the `<tr>` so `activateRowFromKeyDown` has something to fire on. The two
+  together made a row a keyboard user could reach and activate with nothing on
+  screen changing. **This is a WCAG 2.4.7 (Focus Visible, AA) fix you inherit by
+  upgrading.**
+
+  The ring is the one `Row` already draws: 2px solid in `--cue-accent`, pulled
+  inside the row by `-outline-offset-2` rather than floating outside it, because
+  these tables live in clipped panes and scroll regions where an outset ring on
+  the first or last row is cut off by the pane's own rim. It is `focus-visible`,
+  so a pointer press still paints nothing, and it rides on `interactive` alone:
+  a static table of figures is untouched. Nothing to change — and if you drew a
+  ring of your own on a focusable row, the library's is now under it.
+
+  Added after the fact: this shipped in 0.7.0 with no changeset, and a late entry
+  beats a hole in the record.
+
 - @cueplusplus/tokens@0.7.0
 
 ## 0.6.0

package/README.md

@@ -3,11 +3,45 @@
 Components for console software: dense, keyboard-first interfaces where a screen is mostly data.
 Base UI underneath for behaviour and accessibility, Tailwind v4 on top for the paint.
 
+## Install
+
+The `@cueplusplus` scope is served by **GitHub Packages**, not npmjs.com, and GitHub Packages
+authenticates *every* install. That is two settings, in two places, and the split is not
+cosmetic — pnpm ignores an env-expanded credential in a project `.npmrc` and the install fails
+with `401`.
+
+Commit the scope routing, and nothing else, at the root of your project:
+
+```ini
+# .npmrc
+@cueplusplus:registry=https://npm.pkg.github.com
+```
+
+Then write the credential once, at the **user** level, where pnpm reads it from. It is a
+**classic** personal access token with `read:packages` — GitHub Packages accepts neither
+fine-grained PATs nor OIDC:
+
+```sh
+pnpm config set //npm.pkg.github.com/:_authToken ghp_…
+```
+
 ```sh
 pnpm add @cueplusplus/ui @cueplusplus/tokens @cueplusplus/theme-cue @base-ui/react
 ```
 
+Three peers are required and declared: `react` ^19, `react-dom` ^19 and `@base-ui/react` ^1.7.
+`tailwindcss` ^4 is a declared peer too, but an optional one — needed for the default styling
+lane, and without it you own the CSS. Every other peer is optional and scoped to a subpath.
+`@cueplusplus/tokens` arrives as a dependency; installing it by name just makes the token
+constants importable in your own code. The theme package is not a peer at all — see below.
+
+CI, Vercel and the token's expiry are in
+[`docs/CONSUMING.md` §1](https://github.com/cueplusplus/cue-ui/blob/main/docs/CONSUMING.md#1-registry-access).
+
+## Quick start
+
 ```css
+/* app/globals.css */
 @import "tailwindcss";
 @import "@cueplusplus/ui/styles.css";
 @import "@cueplusplus/theme-cue/theme.css";
@@ -15,11 +49,16 @@ pnpm add @cueplusplus/ui @cueplusplus/tokens @cueplusplus/theme-cue @base-ui/rea
 
 ```tsx
 import cue from "@cueplusplus/theme-cue";
+import { Button } from "@cueplusplus/ui";
 import { ThemeProvider } from "@cueplusplus/ui/system";
 
-<ThemeProvider themes={[cue]} theme="cue" density="compact" mode="system">
-  <App />
-</ThemeProvider>;
+export default function App() {
+  return (
+    <ThemeProvider themes={[cue]} theme="cue" density="compact" mode="system">
+      <Button variant="primary">Run cue</Button>
+    </ThemeProvider>
+  );
+}
 ```
 
 The order of those three `@import`s is load-bearing, and the `themes` prop is not optional in
@@ -27,23 +66,172 @@ practice: this library contains no palette. Install and register a `@cueplusplus
 or every surface paints `@cueplusplus/theme-base`'s blank base — greys, one desaturated accent,
 the platform monospace — with nothing erroring to tell you.
 
+To stop the defaults flashing on first paint, add `prepaintScript()` beside the provider and hand
+both the same array — [§4 of `CONSUMING.md`](https://github.com/cueplusplus/cue-ui/blob/main/docs/CONSUMING.md#4-the-provider)
+is the whole layout.
+
+## What it ships
+
 Common components come from the root entry. Groups that need an optional peer have a subpath of
-their own (`/charts`, `/date`, `/flow`, `/color`, `/agent-runtime`, and the rest), so importing a
-button never pulls a charting library into your bundle.
+their own, so importing a button never pulls a charting library into your bundle.
+
+| Import specifier | What is in it |
+| --- | --- |
+| `@cueplusplus/ui` | the root barrel: every component that costs no optional peer, the brand marks and the container icons included |
+| `@cueplusplus/ui/primitives` | the leaves: buttons, chips, avatars, dots and the two loading shapes |
+| `@cueplusplus/ui/forms` | everything a user types into, toggles, picks from or drags |
+| `@cueplusplus/ui/overlays` | everything that floats: dialogs, sheets, menus, tooltips, the command palette |
+| `@cueplusplus/ui/chrome` | console furniture: panels, rows, bars, tabs, the tree outline and the `Inspector` layout |
+| `@cueplusplus/ui/layout` | page structure: cards, stacks, grids, `Bento`, the `Preview` frame, disclosure and the navigation shapes |
+| `@cueplusplus/ui/layout/carousel` | needs `embla-carousel-react` |
+| `@cueplusplus/ui/layout/resizable` | needs `react-resizable-panels` |
+| `@cueplusplus/ui/instruments` | the readouts: meters, sparklines, tables, logs, `CodeBlock` and the two device frames |
+| `@cueplusplus/ui/instruments/data-table` | needs `@tanstack/react-table` |
+| `@cueplusplus/ui/instruments/log-viewer` | needs `@tanstack/react-virtual`, `anser` |
+| `@cueplusplus/ui/charts` | Recharts in this system's tokens, plus the categorical palette and the ramps; needs `recharts` |
+| `@cueplusplus/ui/date` | calendars, pickers and segmented date/time fields; needs `react-day-picker`, `date-fns`, `react-aria-components`, `@internationalized/date` |
+| `@cueplusplus/ui/color` | the picker suite the configurator edits with, hex and oklch; needs `react-aria-components` |
+| `@cueplusplus/ui/configurator` | the floating panel that edits the token layer live and exports what it edited; needs `react-aria-components` |
+| `@cueplusplus/ui/flow` | React Flow wearing the tokens: node cards, handles, signal-carrying wires; needs `@xyflow/react` (+ `./flow.css`) |
+| `@cueplusplus/ui/chat` | the multi-agent transcript: messages, composer, HITL questions, agent colour |
+| `@cueplusplus/ui/agent-runtime` | the streaming layer under Chat; needs `@assistant-ui/react` |
+| `@cueplusplus/ui/elements` | the agent's own surface, vendored from assistant-ui and repainted onto the tokens; needs `lucide-react` and `heat-graph` (+ `./elements.css`) |
+| `@cueplusplus/ui/elements/markdown` | `MarkdownText`; needs `react-markdown`, `rehype-sanitize` |
+| `@cueplusplus/ui/elements/generative` | the generative-UI renderer and its spec (+ `./elements/generative.css`) |
+| `@cueplusplus/ui/elements/replay` | the scripted session-replay frame |
+| `@cueplusplus/ui/dmx` | 512 bytes at wire rate: the bar, the strip, the patch bar, the channel grid |
+| `@cueplusplus/ui/midi` | sequencer instruments: keyboard, musical clock, ruler, analyser, threshold rail |
+| `@cueplusplus/ui/system` | `ThemeProvider`, `prepaintScript`, the `Density` island, the portal frame, `isSafeTokenValue` |
+| `@cueplusplus/ui/theming` | `createTheme()`, `contrastReport()` and the `--cue-*` vocabulary as constants |
+
+Four stylesheet exports. `@cueplusplus/ui/styles.css` is always imported; the other three are
+imported only if you use what they paint — `@cueplusplus/ui/elements.css`,
+`@cueplusplus/ui/flow.css` and `@cueplusplus/ui/elements/generative.css`.
+
+## Showing a component: `Preview`, `Inspector`, `CodeBlock`
+
+Three pieces for a page that shows components rather than only using them — a docs page, a design
+review, a settings screen with a live sample. Each is exported from the root barrel as well as from
+its group's subpath, and none needs an optional peer.
+
+### `Preview` — one component on a stage
+
+From `@cueplusplus/ui/layout`. A frame with a stage for the specimen, a `tools` slot at the top
+right and a `footer`. `label` is required, because the frame is a `role="group"` named by it. The
+stage can carry its own `theme`, `mode`, `density` and `font`; with none of them set it carries no
+attribute and inherits the page.
+
+**A stage `theme` needs that theme's stylesheet on the page.** Naming a theme does not load it: the
+stage is scoped with `[data-theme="<name>"]`, so `@cueplusplus/theme-<name>/theme.css` has to be
+imported like any other palette, or the stage paints the blank base with nothing erroring. The
+example below shows `terminal` on a `cue` page, so both are imported and both are registered:
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "@cueplusplus/ui/styles.css";
+@import "@cueplusplus/theme-cue/theme.css";
+@import "@cueplusplus/theme-terminal/theme.css";
+```
+
+```tsx
+import cue from "@cueplusplus/theme-cue";
+import terminal from "@cueplusplus/theme-terminal";
+import { Chip } from "@cueplusplus/ui";
+import { Preview } from "@cueplusplus/ui/layout";
+import { ThemeProvider } from "@cueplusplus/ui/system";
+
+export default function ChipPage() {
+  return (
+    <ThemeProvider themes={[cue, terminal]} theme="cue" density="compact" mode="system">
+      <Preview label="Chip preview" theme="terminal" resizable footer="terminal · compact">
+        <Chip tone="accent">Standby</Chip>
+      </Preview>
+    </ThemeProvider>
+  );
+}
+```
+
+- Only the stage changes theme. `tools`, `footer`, the resize grips and anything they open stay in
+  the page's theme, so the controls that drive a specimen always look like the page around them.
+- `resizable` adds a grip per axis, 160–1280 × 96–960 px by default, that works by pointer and by
+  keyboard (arrows step 8 px, Shift+arrow 64 px). Pass `{ axis, minWidth, maxWidth, minHeight,
+  maxHeight }` to narrow it. A resizable Preview fills its container's width.
+- It is a client component (`"use client"`).
+
+### `Inspector` — the layout of a settings panel
+
+From `@cueplusplus/ui/chrome`. Titled sections of label-and-control rows, then a footer — the shape
+of a properties sidebar or a wrench menu. The controls are the library's own.
+
+```tsx
+import { Button, Input, SegmentedControl } from "@cueplusplus/ui";
+import { Inspector } from "@cueplusplus/ui/chrome";
+
+const sizes = [
+  { value: "sm", label: "Small" },
+  { value: "md", label: "Medium" },
+  { value: "lg", label: "Large" },
+];
+
+export function ButtonInspector() {
+  return (
+    <Inspector.Root>
+      <Inspector.Section label="Variants">
+        <Inspector.Row label="Size">
+          <SegmentedControl items={sizes} defaultValue="md" />
+        </Inspector.Row>
+        <Inspector.Row label="Label" htmlFor="button-label">
+          <Input id="button-label" defaultValue="Run cue" />
+        </Inspector.Row>
+      </Inspector.Section>
+      <Inspector.Footer note="preset · primary" action={<Button size="sm">Reset</Button>} />
+    </Inspector.Root>
+  );
+}
+```
+
+- A row names its control. With `htmlFor` the label is a `<label>` for that id; without it the row
+  lays `label` on the control as `aria-label`, unless the control already names itself.
+- A row is one column until the Inspector is 18rem wide, then label beside control. It is a
+  container query, so it follows the popover or sidebar the Inspector sits in, not the viewport.
+- `Inspector` itself has no hooks and no `"use client"`, so a server component can render it.
+
+### `CodeBlock` — code with a caption and a copy button
+
+From `@cueplusplus/ui/instruments`.
+
+```tsx
+import { CodeBlock } from "@cueplusplus/ui/instruments";
+
+export function ButtonSource() {
+  return <CodeBlock label="button.tsx" language="jsx" code={'<Button variant="primary">Run cue</Button>'} />;
+}
+```
+
+- `code` is printed verbatim, and the copy button copies exactly that. `label` is the caption and
+  defaults to the language; `language` defaults to `"tsx"`.
+- There is no syntax-highlighter palette. `language="jsx"` picks out tag names, attribute names and
+  punctuation in three inks the theme already has; every other language prints plain.
 
 ## The machine-readable half
 
 This package ships its own manifest: `@cueplusplus/ui/manifest.json` is an index of every
 component with a SHA-256 for each companion document, and
 `@cueplusplus/ui/manifest/components/<name>.json` is one component in full — props, variants, the
-tokens it paints with, and the hand-written notes on when it is the wrong choice. An agent or a
-code generator should read that rather than guess a prop name.
+tokens it paints with, and the hand-written notes on when it is the wrong choice. Beside them,
+`@cueplusplus/ui/manifest/tokens.json` is the token vocabulary and
+`@cueplusplus/ui/manifest/fixtures.json` the playground fixture catalogue. An agent or a code
+generator should read those rather than guess a prop name.
 
 The same surfaces are published at <https://ui.cueplusplus.com>, with the docs site, the live
 kitchen sink and the CUE++ agent skills beside them.
 
-## Full documentation
+## Where the rest is
 
-- Installing and using it from another project: [`docs/CONSUMING.md`](https://github.com/cueplusplus/product-design-system/blob/main/docs/CONSUMING.md)
+- Installing and using it from another project: [`docs/CONSUMING.md`](https://github.com/cueplusplus/cue-ui/blob/main/docs/CONSUMING.md)
 - Every component, with props and a live example: <https://ui.cueplusplus.com/docs/components>
 - Theming, density and the `--cue-*` contract: <https://ui.cueplusplus.com/docs/theming>
+- The whole surface on one page: <https://ui.cueplusplus.com/kitchen-sink>
+- Every machine-readable surface, with copy-paste snippets: <https://ui.cueplusplus.com/ai>
+- What changed in the version you have: `node_modules/@cueplusplus/ui/CHANGELOG.md`

package/dist/chrome/index.d.ts

@@ -6,6 +6,7 @@ import { AppShell, AppShellAsideProps, AppShellBarProps, AppShellBodyProps, AppS
 import { EmptyState, EmptyStateProps } from "./empty-state.js";
 import { Eyebrow, EyebrowProps } from "./eyebrow.js";
 import { Footer, FooterProps } from "./footer.js";
+import { Inspector, InspectorFooterProps, InspectorRootProps, InspectorRowProps, InspectorSectionProps } from "./inspector.js";
 import { NavigationMenu, NavigationMenuContentProps, NavigationMenuItemProps, NavigationMenuLinkProps, NavigationMenuListProps, NavigationMenuRootProps, NavigationMenuTriggerProps, NavigationMenuViewportProps } from "./navigation-menu.js";
 import { PageShell, PageShellProps, PageWidth } from "./page-shell.js";
 import { Panel, PanelHeader, PanelHeaderProps, PanelProps } from "./panel.js";
@@ -19,4 +20,4 @@ import { ScrollableTabsList, ScrollableTabsListProps, Tabs, TabsListProps, TabsP
 import { TitleBar, TitleBarProps } from "./title-bar.js";
 import { Tree, TreeProps, TreeVisibility, TreeVisibilityToggle, TreeVisibilityToggleProps } from "./tree.js";
 import { Toolbar, ToolbarButtonProps, ToolbarGroupProps, ToolbarRootProps, ToolbarSeparatorProps } from "./toolbar.js";
-export { AppBar, type AppBarActionsProps, type AppBarBrandProps, type AppBarLinkProps, type AppBarNavProps, type AppBarRegister, type AppBarRootProps, type AppBarSeparatorProps, AppShell, type AppShellAsideProps, type AppShellBarProps, type AppShellBodyProps, type AppShellContentProps, type AppShellNavTriggerProps, type AppShellRootProps, type AppShellScrollerProps, type AppShellSidebarProps, type BarOverflow, EmptyState, type EmptyStateProps, Eyebrow, type EyebrowProps, Footer, type FooterProps, NavigationMenu, type NavigationMenuContentProps, type NavigationMenuItemProps, type NavigationMenuLinkProps, type NavigationMenuListProps, type NavigationMenuRootProps, type NavigationMenuTriggerProps, type NavigationMenuViewportProps, PageShell, type PageShellProps, type PageWidth, Panel, PanelHeader, type PanelHeaderProps, type PanelProps, Row, type RowProps, ScrollArea, type ScrollAreaOrientation, type ScrollAreaProps, type ScrollEdges, ScrollableTabsList, type ScrollableTabsListProps, SeamList, type SeamListProps, SectionHeader, type SectionHeaderProps, SegmentedControl, type SegmentedControlItem, type SegmentedControlProps, type SegmentedControlSize, StatusBar, type StatusBarGroupProps, type StatusBarItemProps, type StatusBarProminence, type StatusBarProps, type StatusBarTone, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Tabs, type TabsListProps, type TabsPanelProps, type TabsRootProps, type TabsTabProps, TitleBar, type TitleBarProps, Toolbar, type ToolbarButtonProps, type ToolbarGroupProps, type ToolbarRootProps, type ToolbarSeparatorProps, Tree, type TreeGuide, type TreeItem, type TreeProps, type TreeRow, type TreeVisibility, TreeVisibilityToggle, type TreeVisibilityToggleProps, computeScrollEdges, edgeFadeMask, flattenTree, rowVariants };
+export { AppBar, type AppBarActionsProps, type AppBarBrandProps, type AppBarLinkProps, type AppBarNavProps, type AppBarRegister, type AppBarRootProps, type AppBarSeparatorProps, AppShell, type AppShellAsideProps, type AppShellBarProps, type AppShellBodyProps, type AppShellContentProps, type AppShellNavTriggerProps, type AppShellRootProps, type AppShellScrollerProps, type AppShellSidebarProps, type BarOverflow, EmptyState, type EmptyStateProps, Eyebrow, type EyebrowProps, Footer, type FooterProps, Inspector, type InspectorFooterProps, type InspectorRootProps, type InspectorRowProps, type InspectorSectionProps, NavigationMenu, type NavigationMenuContentProps, type NavigationMenuItemProps, type NavigationMenuLinkProps, type NavigationMenuListProps, type NavigationMenuRootProps, type NavigationMenuTriggerProps, type NavigationMenuViewportProps, PageShell, type PageShellProps, type PageWidth, Panel, PanelHeader, type PanelHeaderProps, type PanelProps, Row, type RowProps, ScrollArea, type ScrollAreaOrientation, type ScrollAreaProps, type ScrollEdges, ScrollableTabsList, type ScrollableTabsListProps, SeamList, type SeamListProps, SectionHeader, type SectionHeaderProps, SegmentedControl, type SegmentedControlItem, type SegmentedControlProps, type SegmentedControlSize, StatusBar, type StatusBarGroupProps, type StatusBarItemProps, type StatusBarProminence, type StatusBarProps, type StatusBarTone, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Tabs, type TabsListProps, type TabsPanelProps, type TabsRootProps, type TabsTabProps, TitleBar, type TitleBarProps, Toolbar, type ToolbarButtonProps, type ToolbarGroupProps, type ToolbarRootProps, type ToolbarSeparatorProps, Tree, type TreeGuide, type TreeItem, type TreeProps, type TreeRow, type TreeVisibility, TreeVisibilityToggle, type TreeVisibilityToggleProps, computeScrollEdges, edgeFadeMask, flattenTree, rowVariants };

package/dist/chrome/index.js

@@ -5,16 +5,17 @@ import { AppShell } from "./app-shell.js";
 import { EmptyState } from "./empty-state.js";
 import { Eyebrow } from "./eyebrow.js";
 import { Footer } from "./footer.js";
+import { SectionHeader } from "./section-header.js";
+import { Inspector } from "./inspector.js";
 import { NavigationMenu } from "./navigation-menu.js";
 import { PageShell } from "./page-shell.js";
 import { Panel, PanelHeader } from "./panel.js";
 import { Row, SeamList, rowVariants } from "./row.js";
 import { ScrollArea } from "./scroll-area.js";
-import { SectionHeader } from "./section-header.js";
 import { SegmentedControl } from "./segmented-control.js";
 import { StatusBar } from "./status-bar.js";
 import { ScrollableTabsList, Tabs } from "./tabs.js";
 import { TitleBar } from "./title-bar.js";
 import { Tree, TreeVisibilityToggle } from "./tree.js";
 import { Toolbar } from "./toolbar.js";
-export { AppBar, AppShell, EmptyState, Eyebrow, Footer, NavigationMenu, PageShell, Panel, PanelHeader, Row, ScrollArea, ScrollableTabsList, SeamList, SectionHeader, SegmentedControl, StatusBar, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Tabs, TitleBar, Toolbar, Tree, TreeVisibilityToggle, computeScrollEdges, edgeFadeMask, flattenTree, rowVariants };
+export { AppBar, AppShell, EmptyState, Eyebrow, Footer, Inspector, NavigationMenu, PageShell, Panel, PanelHeader, Row, ScrollArea, ScrollableTabsList, SeamList, SectionHeader, SegmentedControl, StatusBar, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Tabs, TitleBar, Toolbar, Tree, TreeVisibilityToggle, computeScrollEdges, edgeFadeMask, flattenTree, rowVariants };