@cueplusplus/ui 0.3.0 → 0.6.0

package/manifest/components/subagent-list.json

@@ -0,0 +1,88 @@
+{
+  "name": "SubagentList",
+  "slug": "subagent-list",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "Parallel workers with their own progress, models, and completions.",
+  "props": [
+    {
+      "name": "agents",
+      "type": "readonly SubagentItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Parallel workers shown as cards with name and model."
+    },
+    {
+      "name": "completedCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many agents from the start are marked complete."
+    },
+    {
+      "name": "progress",
+      "type": "readonly number[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Per-agent progress widths used while a worker is still running."
+    },
+    {
+      "name": "showSummary",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true the summary agent card is revealed under the list."
+    },
+    {
+      "name": "summaryAgent",
+      "type": "SubagentItem",
+      "required": true,
+      "defaultValue": null,
+      "description": "Agent shown in the summary card once showSummary is true."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"agents\"\n  | \"completedCount\"\n  | \"progress\"\n  | \"showSummary\"\n  | \"summaryAgent\"\n> & {\n  /** Parallel workers shown as cards with name and model. */\n  agents: readonly SubagentItem[];\n  /** How many agents from the start are marked complete. */\n  completedCount: number;\n  /** Per-agent progress widths used while a worker is still running. */\n  progress: readonly number[];\n  /** When true the summary agent card is revealed under the list. */\n  showSummary: boolean;\n  /** Agent shown in the summary card once showSummary is true. */\n  summaryAgent: SubagentItem;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "Parallel workers with their own progress, models, and completions.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { SubagentList } from \"@cueplusplus/ui/elements\";\n\n<SubagentList\n  agents={[{ name: \"Researcher\", model: \"Sonnet\" }]}\n  completedCount={0}\n  progress={[40]}\n  showSummary={false}\n  summaryAgent={{ name: \"Summarizer\", model: \"Haiku\" }}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/subagent-list",
+  "mdUrl": "/docs/components/subagent-list.md",
+  "jsonUrl": "/r/components/subagent-list.json",
+  "specimens": [
+    {
+      "title": "SubagentList",
+      "group": "elements",
+      "components": [
+        "SubagentList"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"two running\" wide>\n    <SubagentList\n      agents={WORKERS}\n      completedCount={1}\n      progress={[100, 62, 24]}\n      showSummary={false}\n      summaryAgent={SUMMARISER}\n    />\n  </Specimen>\n  <Specimen label=\"summarising\" wide>\n    <SubagentList\n      agents={WORKERS}\n      completedCount={WORKERS.length}\n      progress={[100, 100, 100]}\n      showSummary\n      summaryAgent={SUMMARISER}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Parallel workers, each with its own model and its own progress. `completedCount` marks the finished ones from the start of the list, and the summary card appears under them when the agent that folds their answers together starts work.",
+      "interaction": "none. Delegation is something to watch, not something to steer from here."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/suggestions.json

@@ -0,0 +1,84 @@
+{
+  "name": "Suggestions",
+  "slug": "suggestions",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Prompt pills that stagger in after a reply and invite the next turn.",
+  "props": [
+    {
+      "name": "suggestions",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Follow-up prompt pills rendered in order."
+    },
+    {
+      "name": "selectedSuggestion",
+      "type": "string | null",
+      "required": true,
+      "defaultValue": null,
+      "description": "The pill currently pressed, or null when none is selected."
+    },
+    {
+      "name": "cycle",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Identity key that remounts the row so the stagger entrance can replay."
+    },
+    {
+      "name": "onSuggestion",
+      "type": "(suggestion: string) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when a suggestion pill is pressed."
+    },
+    {
+      "name": "variant",
+      "type": "\"list\" | \"pills\"",
+      "required": false,
+      "defaultValue": "pills",
+      "description": "pills wraps suggestions into a centered row; list stacks them as full-width rows."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\"\n>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-radius-overlay",
+    "--cue-text-body"
+  ],
+  "summary": "Prompt pills that stagger in after a reply and invite the next turn.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { Suggestions } from \"@cueplusplus/ui/elements\";\n\n<Suggestions\n  suggestions={[\"Explain more\", \"Show an example\"]}\n  selectedSuggestion={null}\n  cycle={0}\n  onSuggestion={setSelected}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/suggestions",
+  "mdUrl": "/docs/components/suggestions.md",
+  "jsonUrl": "/r/components/suggestions.json",
+  "specimens": [
+    {
+      "title": "Suggestions",
+      "group": "elements-thread",
+      "components": [
+        "Suggestions"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"pills\" wide>\n    <Suggestions\n      suggestions={FOLLOW_UPS}\n      selectedSuggestion={suggestion}\n      cycle={0}\n      onSuggestion={setSuggestion}\n    />\n  </Specimen>\n  <Specimen label=\"list\" wide>\n    <Suggestions\n      suggestions={FOLLOW_UPS}\n      selectedSuggestion={FOLLOW_UPS[0] ?? null}\n      cycle={1}\n      onSuggestion={setSuggestion}\n      variant=\"list\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Where the conversation could go next, staggered in after a reply. Pills for a centred empty state, a list for a side panel; either way `cycle` is the key that re-runs the entrance when a new set replaces the old one.",
+      "interaction": "each pill is a button carrying aria-pressed, lifts a pixel on hover and presses in on click. The selected one inverts."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/sup.json

@@ -0,0 +1,44 @@
+{
+  "name": "Sup",
+  "slug": "sup",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A superscript inside an expression: an exponent or an index, set upright inside the\nitalic.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-text-emphasis"
+  ],
+  "summary": "A superscript inside an expression: an exponent or an index, set upright inside the italic.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/sup",
+  "mdUrl": "/docs/components/sup.md",
+  "jsonUrl": "/r/components/sup.json",
+  "specimens": [
+    {
+      "title": "MathBlock",
+      "group": "elements-knowledge",
+      "components": [
+        "MathBlock",
+        "Frac",
+        "Sub",
+        "Sup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"worked through\" wide>\n    <MathBlock label=\"illuminance at the deck\" steps={MATH} visibleSteps={MATH.length} />\n  </Specimen>\n  <Specimen label=\"first step only\" wide>\n    <MathBlock steps={MATH} visibleSteps={1} />\n  </Specimen>\n</Specimens>",
+      "note": "Maths with the working shown, a step at a time. The expressions are nodes rather than a string, so there is no parser and no KaTeX in the bundle — `Frac` stacks a numerator over a rule, `Sup` and `Sub` set an index upright inside the serif italic, and anything else is text.",
+      "interaction": "none. Each step's note says what justified it, which is what turns three lines of algebra into an explanation."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/swap-label.json

@@ -0,0 +1,71 @@
+{
+  "name": "SwapLabel",
+  "slug": "swap-label",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Two labels stacked in one cell, with the box's width animating between them.\n\nA `ResizeObserver` measures the layer that is showing, because the crossfade\nis only half the effect — a \"Searching…\" that becomes \"Searched\" has to make\nthe row shrink, and neither layer can size the box while both are in it.\n\nThe layer that is leaving is `aria-hidden`, so the outgoing text is neither\nannounced nor copied into a selection.",
+  "props": [
+    {
+      "name": "active",
+      "type": "0 | 1",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which of the two children is showing."
+    },
+    {
+      "name": "children",
+      "type": "[ReactNode, ReactNode]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Exactly two labels: the resting one and the active one."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the measured box."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-accent-hover",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-stream",
+    "--cue-sunken",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-label"
+  ],
+  "summary": "Two labels stacked in one cell, with the box's width animating between them.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/swap-label",
+  "mdUrl": "/docs/components/swap-label.md",
+  "jsonUrl": "/r/components/swap-label.json",
+  "specimens": [
+    {
+      "title": "SwapLabel",
+      "group": "elements",
+      "components": [
+        "SwapLabel"
+      ],
+      "code": "<Specimens>\n  <Specimen label={swapped === 0 ? \"active 0\" : \"active 1\"}>\n    <span className=\"flex items-center gap-(--cue-space-3)\">\n      <SwapLabel active={swapped}>\n        <ShimmerLabel className=\"relative inline-block leading-none\">\n          Patching universe 3\n        </ShimmerLabel>\n        <>Patched</>\n      </SwapLabel>\n      <Button size=\"sm\" onClick={() => setSwapped((current) => (current === 0 ? 1 : 0))}>\n        Swap\n      </Button>\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "Two labels in one cell, crossfading, with the box measuring itself to whichever is showing. The width is half the effect: 'Patching universe 3' becoming 'Patched' has to make the row shrink, and the outgoing layer is aria-hidden so it is neither announced nor copied.",
+      "interaction": "swap it and watch the box, not the text. Everything after the label on that row moves with it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/table-scroll-region.json

@@ -24,14 +24,20 @@
   "defaultVariants": {},
   "tokensUsed": [
     "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-bg",
     "--cue-border",
     "--cue-fg",
     "--cue-fg-subtle",
     "--cue-font-mono",
+    "--cue-hair-strong",
     "--cue-pad-row-x",
     "--cue-pad-row-y",
+    "--cue-row-hover",
+    "--cue-space-2",
     "--cue-space-3",
     "--cue-surface-1",
+    "--cue-table-group-top",
     "--cue-text-label",
     "--cue-text-ui"
   ],

package/manifest/components/table.json

@@ -5,7 +5,7 @@
   "importPath": "@cueplusplus/ui",
   "peerDependencies": [],
   "clientOnly": false,
-  "description": "The canonical console table: hairlines, mono figures, no zebra striping.\n\nSemantic `<table>` markup throughout — a grid of divs loses row/column\nannouncement, and a console table is exactly the place a screen reader user\nneeds it. Zebra rows are deliberately absent: at console density the stripes\nare thicker than the data.\n\nStatic markup — no `\"use client\"`. Compose it with `Panel` for the rim.\nUse {@link TableScrollRegion} only when the table can exceed its container.",
+  "description": "The canonical console table: hairlines, mono figures, no zebra striping.\n\nSemantic `<table>` markup throughout — a grid of divs loses row/column\nannouncement, and a console table is exactly the place a screen reader user\nneeds it. Zebra rows are deliberately absent: at console density the stripes\nare thicker than the data.\n\nStatic markup — no `\"use client\"`. Compose it with `Panel` for the rim.\nUse {@link TableScrollRegion} only when the table can exceed its container.\n\nFor a grouped list, the table stays *one* table: `Table.Head sticky` docks the\ncolumn names, and one `Table.Body` per group opens with a `Table.GroupRow`\ndivider — so the columns are named once and scan straight through every group\nboundary. Rows may hold `DataRow` slots, and `DataRow.Actions` reveals inside\na cell on hover and on selection exactly as it does in a `Ledger` row — on\nfocus too, once the row holds something focusable outside the track, which a\n`<tr>` never is by itself. See {@link TableRowProps.interactive}.",
   "props": [],
   "typeReferences": [],
   "subcomponents": [
@@ -13,6 +13,7 @@
     "Header",
     "Body",
     "Row",
+    "GroupRow",
     "Head",
     "Cell",
     "Caption"
@@ -48,16 +49,76 @@
     {
       "name": "Row",
       "usage": "Table.Row",
-      "description": "One row, separated by a hairline underneath — dropped on the last row so the\ntable never draws a rule against the panel rim it sits in. In a `<thead>` the\n\"last row\" is the header row itself, so the header's own bottom border (on\nthe cells) is the only rule there and the two can never stack into 2px.",
-      "props": [],
+      "description": "One row, separated by a hairline underneath — dropped on the last row so the\ntable never draws a rule against the panel rim it sits in. In a `<thead>` the\n\"last row\" is the header row itself, so the header's own bottom border (on\nthe cells) is the only rule there and the two can never stack into 2px.\n\nEvery row carries the `group/data-row` name unconditionally. It paints\nnothing by itself, and it is what lets a `DataRow.Actions` cluster inside a\n`Table.Cell` reveal on hover, on focus and on selection with no second\nimplementation of that idiom for the table — the whole point of the three\nidioms sharing one row anatomy.\n\n**The focus half of that reveal is the caller's to supply here.** A `<tr>` is\nnot focusable and this component does not make it one — a tab stop on every\nrow of a long table is a tab stop a keyboard user has to walk past hundreds\nof times, which is the reason `Ledger` rows opt in individually. So the\nreveal-on-focus only happens if the row *contains* something focusable\noutside the hidden track: a link on the row's name, a checkbox in the leading\ncell, any real control. Without one, `:focus-within` can never fire — content\ninside a `visibility: hidden` subtree cannot be focused, so the track cannot\nbootstrap its own reveal — and a hidden action cluster is then reachable by\npointer only, which is a WCAG 2.1.1 failure the screen gives no sign of. A\ntable whose only per-row controls live in a hidden track wants either a\nfocusable cell beside it or an always-visible cluster.\n\nThe selected tint is the row's, not the cell's: a `background` on the `<tr>`\nshows through every cell in it, so the fill cannot end up ragged where one\ncell sets a ground of its own.",
+      "props": [
+        {
+          "name": "interactive",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "The row responds to a pointer: the row-hover wash and a pointer cursor\nacross the whole row. Defaults to `false`.\n\nOpt-in rather than automatic, because a table of figures nobody can click\nthat lit up under the pointer would be promising an interaction it does not\nhave. Wiring the row up to actually do something — a click handler, a\nkeyboard path to the same thing — stays the caller's job; this is the paint."
+        },
+        {
+          "name": "selected",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Draw the row as picked out of the table. Defaults to `false`.\n\nSets `data-selected`, which is what the tint and the hover-revealed\n`DataRow.Actions` inside the row both key off — so a hand-written\n`<tr data-selected>` in a data-driven body gets exactly the same treatment."
+        }
+      ],
       "typeReferences": [
         "React.ComponentPropsWithoutRef<\"tr\">"
       ]
     },
+    {
+      "name": "GroupRow",
+      "usage": "Table.GroupRow",
+      "description": "A group divider inside one continuous table.\n\nThe whole point is that it is *inside*: a grouped list drawn as one table per\ngroup names its columns once per group, so a reader scanning a column\ntop-to-bottom crosses a fresh header band at every boundary and a screen\nreader announces four tables where there is one dataset. So the table stays\none `<table>` with one `<thead>`, and each group is its own `<tbody>` — which\nis valid HTML, keeps the group's rows together, and gives the divider a row\ngroup to be the header of.\n\nThat last part is why the cell is a `<th scope=\"rowgroup\">` rather than a\nstyled `<td>`: `rowgroup` scope is exactly the statement \"this heading names\nthe rows of this `<tbody>`\", and it leaves the column headers' associations\nuntouched. A `<td colSpan>` divider is invisible to assistive technology as a\nheading, and a `<th scope=\"col\">` one would quietly re-scope the columns.\n\nNo `aria-expanded` here, and no toggle: groups in a table divide, they do not\nfold. A hierarchy that folds is `DataTree`, whose treeitem rows own their own\nexpansion — and if a table genuinely needs to fold rows, the pattern is a real\n`<button aria-expanded aria-controls>` inside this cell, never the row itself.",
+      "props": [
+        {
+          "name": "span",
+          "type": "number",
+          "required": true,
+          "defaultValue": null,
+          "description": "How many columns the divider spans. Required: it must equal the table's\ncolumn count, or the group's cell stops covering the row and the columns\nbelow it shift by one."
+        },
+        {
+          "name": "label",
+          "type": "ReactNode",
+          "required": true,
+          "defaultValue": null,
+          "description": "What the group is called."
+        },
+        {
+          "name": "count",
+          "type": "number",
+          "required": false,
+          "defaultValue": null,
+          "description": "How many rows the group holds, printed beside its name."
+        },
+        {
+          "name": "sticky",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Dock the divider under the header band while the group's rows scroll past.\nDefaults to `false`.\n\nThe offset is the custom property `--cue-table-group-top` (default `0`):\nhow far down the divider docks is the rendered height of the sticky header\nabove it, which depends on the density and type the caller configured. Set\nit on the table — `className=\"[--cue-table-group-top:2rem]\"` — rather than\nmeasuring at runtime."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Classes for the divider's *cell*, not its row.\n\nThe `<tr>` paints nothing — the ground, the type and the sticky offset all\nlive on the `<th>` that spans it, and a background on the row would sit\nbehind the cell's own. Every other prop, and the ref, go to the row."
+        }
+      ],
+      "typeReferences": [
+        "Omit<React.ComponentPropsWithoutRef<\"tr\">, \"children\">"
+      ]
+    },
     {
       "name": "Head",
       "usage": "Table.Head",
-      "description": "A column heading: the same mono uppercase label as `SectionHeader` and\n`Eyebrow`, on the raised surface so the band reads as chrome rather than as\nthe first row of data.",
+      "description": "A column heading: the same mono uppercase label as `SectionHeader` and\n`Eyebrow`, on the raised surface so the band reads as chrome rather than as\nthe first row of data.\n\n**Sticky swaps the bottom border for an inset shadow.** `Table.Root` collapses\nits borders, and a collapsed border belongs to the table's shared grid rather\nthan to the cell — so when a cell detaches to stay at the top of the scroll\ncontainer, its rule stays behind with the rows and the stuck band appears to\nlose its edge. An inset `box-shadow` is a paint effect on the cell itself, so\nit travels with it. The alternative — putting the whole table on\n`border-separate` — would change the geometry of every table in the library\nto fix one that scrolls.\n\nThe opaque `bg-surface-1` is not decoration either: a transparent sticky cell\nis a sticky cell you read the rows through. A caller who wants the header on\nthe page's own ground can pass `className=\"bg-bg\"` — what it must not pass is\nnothing.",
       "props": [
         {
           "name": "numeric",
@@ -65,6 +126,13 @@
           "required": false,
           "defaultValue": "false",
           "description": "Right-align this column and set it in tabular figures."
+        },
+        {
+          "name": "sticky",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Dock the header band to the top of the scroll container while the rows\nscroll under it. Defaults to `false`.\n\nSet it on the cells, not on the `<tr>`: sticky on a table row is honoured\ninconsistently across engines, and the cell is the reliable baseline\neverywhere."
         }
       ],
       "typeReferences": [
@@ -102,14 +170,20 @@
   "defaultVariants": {},
   "tokensUsed": [
     "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-bg",
     "--cue-border",
     "--cue-fg",
     "--cue-fg-subtle",
     "--cue-font-mono",
+    "--cue-hair-strong",
     "--cue-pad-row-x",
     "--cue-pad-row-y",
+    "--cue-row-hover",
+    "--cue-space-2",
     "--cue-space-3",
     "--cue-surface-1",
+    "--cue-table-group-top",
     "--cue-text-label",
     "--cue-text-ui"
   ],
@@ -150,6 +224,16 @@
       "code": "<Panel className=\"w-full\">\n  <TableScrollRegion aria-label=\"Cue list table\">\n    <Table.Root>\n      <Table.Caption>Cue list</Table.Caption>\n      <Table.Header>\n        <Table.Row>\n          <Table.Head numeric>#</Table.Head>\n          <Table.Head>Label</Table.Head>\n          <Table.Head numeric>Fade</Table.Head>\n          <Table.Head>Follow</Table.Head>\n          <Table.Head numeric>Level</Table.Head>\n        </Table.Row>\n      </Table.Header>\n      <Table.Body>\n        {CUES.map((cue) => (\n          <Table.Row key={cue.id}>\n            <Table.Cell numeric>{cue.id}</Table.Cell>\n            <Table.Cell>{cue.label}</Table.Cell>\n            <Table.Cell numeric>{cue.time}</Table.Cell>\n            <Table.Cell>{cue.follow}</Table.Cell>\n            <Table.Cell numeric>{cue.level}%</Table.Cell>\n          </Table.Row>\n        ))}\n      </Table.Body>\n    </Table.Root>\n  </TableScrollRegion>\n</Panel>",
       "note": "The canonical console table inside its named horizontal scroll region: hairline rows, mono headers, and `numeric` cells that are right-aligned and tabular.",
       "interaction": "the scroll region is keyboard-focusable. Sorting, filtering and paging come from the DataTable recipe below."
+    },
+    {
+      "title": "Table — grouped",
+      "group": "instruments",
+      "components": [
+        "Table"
+      ],
+      "code": "<Panel className=\"w-full\">\n  <div className=\"max-h-[18rem] overflow-y-auto [--cue-table-group-top:1.75rem]\">\n    <Table.Root>\n      <Table.Caption>Patch, one table, two row groups.</Table.Caption>\n      <Table.Header>\n        <Table.Row>\n          <Table.Head sticky>Device</Table.Head>\n          <Table.Head sticky>Detail</Table.Head>\n          <Table.Head sticky numeric>\n            Latency\n          </Table.Head>\n          <Table.Head sticky className=\"sr-only\">\n            Actions\n          </Table.Head>\n        </Table.Row>\n      </Table.Header>\n      {PATCH_GROUPS.map((group) => (\n        <Table.Body key={group.id}>\n          <Table.GroupRow\n            span={4}\n            label={group.label}\n            count={group.rows.length}\n            sticky\n          />\n          {group.rows.map((device) => (\n            <Table.Row key={device.id} interactive>\n              {/* The name is a link, and that is load-bearing rather\n                  than decorative. A `<tr>` is not focusable, so\n                  without a real control somewhere outside the hidden\n                  action track nothing in the row can take focus,\n                  `:focus-within` never fires, and the Copy and\n                  Actions buttons are reachable by pointer only —\n                  visible to a mouse user, invisible to Tab. The\n                  ledger and the tree get this for free because their\n                  rows are focusable themselves; the table has to be\n                  given it. */}\n              <Table.Cell>\n                <Link href={`#patch-${device.id}`}>{device.name}</Link>\n              </Table.Cell>\n              <Table.Cell className=\"text-fg-muted\">{device.detail}</Table.Cell>\n              <Table.Cell numeric>{device.latency}</Table.Cell>\n              {/* The action column's width is a sum of the tokens it\n                  holds — two small controls, the gap between them and\n                  the cell's own padding on each side — so it stays\n                  right whatever the density does to any of them. */}\n              <Table.Cell className=\"w-[calc(2_*_var(--cue-control-sm)_+_var(--cue-space-1)_+_2_*_var(--cue-pad-row-x))]\">\n                <DataRow.Actions>\n                  <CopyButton\n                    value={device.id}\n                    size=\"sm\"\n                    className=\"w-control-sm px-0\"\n                  />\n                  <IconButton\n                    icon={MoreVertical}\n                    size=\"sm\"\n                    aria-label={`Actions for ${device.name}`}\n                  />\n                </DataRow.Actions>\n              </Table.Cell>\n            </Table.Row>\n          ))}\n        </Table.Body>\n      ))}\n    </Table.Root>\n  </div>\n</Panel>",
+      "note": "The same rows as one continuous table: `Table.Head sticky` docks the column names, and one `Table.Body` per group opens with a `Table.GroupRow` divider — a `th` with `scope='rowgroup'`, so the columns are named once and scan straight through every boundary.",
+      "interaction": "rows marked `interactive` take the row-hover wash across the whole row; `selected` tints it and reveals the action track. Tab reaches each row through its name link, which is what lets `:focus-within` reveal the track at all — a `tr` cannot take focus, so a table row whose only controls are in the hidden cluster would be pointer-only."
     }
   ]
 }

package/manifest/components/tags-input.json

@@ -137,6 +137,7 @@
     "--cue-accent-soft",
     "--cue-border",
     "--cue-border-overlay",
+    "--cue-border-strong",
     "--cue-chip-h",
     "--cue-control-lg",
     "--cue-control-md",
@@ -145,6 +146,7 @@
     "--cue-fg",
     "--cue-fg-muted",
     "--cue-fg-subtle",
+    "--cue-focus",
     "--cue-font-mono",
     "--cue-icon-sm",
     "--cue-radius-control",

package/manifest/components/tail-status.json

@@ -0,0 +1,109 @@
+{
+  "name": "TailStatus",
+  "slug": "tail-status",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The live row at the foot of a transcript: what the run is doing, right now.\n\nThe one row every shipping agent UI has and no component catalogue ships. It\nis not a spinner and not a toast — it is a transcript row with\n`role=\"status\"`, which is what makes it the *only* element in this family a\nscreen reader is told about without being asked. Everything else here is\ndrawn and left alone; this one announces itself politely each time the action\nchanges, which is exactly the behaviour a person who cannot see the spinner\nneeds and exactly the behaviour that becomes unbearable if it is used for\nanything else. One per transcript, at the foot, and nowhere else.\n\n**Unless something better is speaking.** {@link LiveRegionAnnouncer } is this\nfamily's other live region, and its table of transitions covers what this row\nnarrates; a console that mounts both would have the run read out twice. So\nmounting an announcer takes the speech away from this row automatically — the\nwords stay on the screen, the `role=\"status\"` goes, and `data-announces` says\nwhich of the two it is doing. {@link TailStatusProps.announce} overrules it in\neither direction.\n\nThe action and the detail are separate props rather than one composed string\nbecause they truncate differently: the action is short and must survive, the\ndetail is a path and must not push it off the row.\n\nState is a prop, as everywhere in this family. The row holds no timer, counts\nnothing, and does not know whether the run is healthy — `active` says whether\nthe sweep runs, `action` says what it says, and the caller changes both.",
+  "props": [
+    {
+      "name": "action",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is happening, in two or three words: `Running commands`,\n`Searching the codebase`. `TAIL_ACTIONS` is the shipped vocabulary and this\nprop is a plain string, so a product with its own verbs is not stuck with\nthese ten."
+    },
+    {
+      "name": "detail",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The thing the action is happening to — a path, a query, a topic. Truncates\non its own so the action never has to; a sidebar transcript is 280px wide\nand a status line that elides its verb has said nothing."
+    },
+    {
+      "name": "active",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Whether the action is still going. `true` by default, because this row is\nthe live one; turn it off for `Idle`, `Interrupted` and `Aborted`, which\nstops the sweep and empties the spinner's slot without moving the text."
+    },
+    {
+      "name": "updatesInPlace",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Whether a new `action` animates into the row that is already there, or\nsimply replaces the text.\n\nCursor's flag, and the reason it needs one: a narration line that changes\nevery few hundred milliseconds should read as one row being updated, while\na line that means something *different* should read as a new row. `true`\n(the default) keys the label on its own text so each new action fades in\nwhere the last one was; `false` leaves it unkeyed, and the words change\nwith no motion at all. A reduced-motion reader gets the second behaviour\neither way."
+    },
+    {
+      "name": "priority",
+      "type": "\"normal\" | \"attention\"",
+      "required": false,
+      "defaultValue": "normal",
+      "description": "How loudly this row is speaking. See {@link TailPriority}."
+    },
+    {
+      "name": "onCancel",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Stop the run. The inline control exists only when this is given — Cursor's\nrule, and the right one: a Cancel that cannot cancel is worse than no\nCancel."
+    },
+    {
+      "name": "cancelLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Cancel",
+      "description": "What the stop control is called. `Cancel` is Cursor's word; opencode uses\n`Interrupt` and `Stop` for the same button."
+    },
+    {
+      "name": "announce",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Whether this row is a live region — whether a screen reader is told each\ntime the action changes.\n\n**Answers itself by default, and that default is the interesting part.**\nLeft alone the row speaks when it is the only thing that can, and goes\nquiet the moment a {@link LiveRegionAnnouncer } is mounted anywhere on the\npage: the announcer's table covers the same transitions this row narrates,\nso a console with both — the ordinary composition — would otherwise have\nevery state read out twice, out of step, because the two regions update at\ndifferent moments.\n\nThe row is the one that defers because the announcer is the better speaker:\nit is a queue, spaced and depth-limited and paused while the page is hidden\nor a modal has the reader, and it is mounted empty and left mounted, which\nis the only way a live region is reliably announced. This row changes\nseveral times a second and comes and goes with the run.\n\nSet it explicitly to overrule that — `true` for a console whose announcer\nis fed something other than these actions, `false` for one that narrates\nthe foot of the transcript some other way. An explicit answer always wins."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-stream",
+    "--cue-text-ui"
+  ],
+  "summary": "The live row at the foot of a transcript: what the run is doing, right now.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { TailStatus, TAIL_ACTIONS } from \"@cueplusplus/ui/elements\";\n\n<TailStatus\n  action={TAIL_ACTIONS.searchingCode}\n  detail=\"composer.tsx\"\n  onCancel={stop}\n/>\n// Settled: no sweep, no spinner, and the text changes without motion.\n<TailStatus action={TAIL_ACTIONS.interrupted} active={false} updatesInPlace={false} />\n// Composed with the announcer: this row draws the state, the queue speaks it.\n<>\n  <TailStatus action={TAIL_ACTIONS.running} detail=\"pnpm test\" />\n  <LiveRegionAnnouncer messages={log} />\n</>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/tail-status",
+  "mdUrl": "/docs/components/tail-status.md",
+  "jsonUrl": "/r/components/tail-status.json",
+  "specimens": [
+    {
+      "title": "TailStatus",
+      "group": "elements-thread",
+      "components": [
+        "TailStatus"
+      ],
+      "code": "<Specimens>\n  <Specimen label={stopped ? \"settled\" : \"live, cancellable\"} wide>\n    <div className=\"w-full max-w-md\">\n      <TailStatus\n        action={stopped ? TAIL_ACTIONS.interrupted : TAIL_ACTIONS.running}\n        detail={stopped ? undefined : \"ola-patch --universe 3\"}\n        active={!stopped}\n        updatesInPlace={!stopped}\n        onCancel={stopped ? undefined : () => setStopped(true)}\n      />\n    </div>\n  </Specimen>\n  <Specimen label=\"thinking, with a topic\" wide>\n    <div className=\"w-full max-w-md\">\n      <TailStatus action={TAIL_ACTIONS.thinking} detail=\"which universe has room\" />\n    </div>\n  </Specimen>\n  <Specimen label=\"attention\" wide>\n    <div className=\"w-full max-w-md\">\n      <TailStatus\n        action=\"Waiting for you\"\n        detail=\"approve the shell command\"\n        priority=\"attention\"\n      />\n    </div>\n  </Specimen>\n</Specimens>",
+      "note": "The live row at the foot of the transcript, and the only element in this family a screen reader is told about without being asked: it is a role=status, so each new action is announced politely as it lands — unless a LiveRegionAnnouncer is mounted, in which case it hands the speaking over and draws the state without saying it, because two polite regions narrating the same run is the transcript read out twice. Two props rather than one string — the action is short and must survive, the detail is a path and must not push it off a 280px sidebar — and an inline Cancel that exists only when there is something to cancel. The copy is TAIL_ACTIONS, a table, not ten strings baked into the markup.",
+      "interaction": "press Cancel and the row settles: the sweep stops, the spinner leaves its slot without the words moving, and the last thing it says is what stopped it. updatesInPlace goes off with it, because 'Interrupted' is a different sentence rather than the next frame of the same one."
+    }
+  ],
+  "todo": true
+}