@cueplusplus/ui 0.14.0 → 0.14.1

package/manifest/components/threshold-rail.json

@@ -203,10 +203,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/threshold-rail",
   "mdUrl": "/docs/components/threshold-rail.md",
   "jsonUrl": "/r/components/threshold-rail.json",
+  "whenToUse": [
+    "Any threshold chosen *relative to a signal* — this is the one control where the level, the peak-hold needle and the trigger point are visible at once.",
+    "A band rather than a point: `lower` gives the second handle, and `minGap` keeps them apart."
+  ],
+  "whenNotToUse": [
+    "A number with no signal behind it. A `NumberField` holds it perfectly well."
+  ],
+  "commonMistakes": [
+    "Writing every drag to the model. Use `onCommit` for the settled value, the way `Slider` splits change from commit.",
+    "Rebuilding it per panel. It exists because three near-identical threshold editors did."
+  ],
   "specimens": [
     {
       "title": "ThresholdRail",
@@ -218,6 +229,5 @@
       "note": "A dual-handle rail with tone zones below and above, a level bar and a peak-hold needle.",
       "interaction": "each handle is a slider with its own name; both scale up while dragging, and `onCommit` fires once on release."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/time-boundary.json

@@ -48,10 +48,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/time-boundary",
   "mdUrl": "/docs/components/time-boundary.md",
   "jsonUrl": "/r/components/time-boundary.json",
+  "whenToUse": [
+    "A transcript assembled from a row union, where the boundary has to be a member of that union — one row, placed by the caller."
+  ],
+  "whenNotToUse": [
+    "A message list you want to insert its own rules into. That is `DaySeparator`, which takes the whole list and places the rules itself."
+  ],
+  "commonMistakes": [
+    "Expecting date arithmetic. `label` is pre-formatted — `Today`, `Yesterday`, `14 March` — because this family owns no locale.",
+    "Skipping `dateTime`. It renders the label inside a `time` element, which is what lets a test, a scraper or a deep link find the boundary without parsing the words a human reads.",
+    "Worrying that the label will be read twice. It is a `role=\"separator\"` carrying the label as its accessible name, with the visible text `aria-hidden`."
+  ],
   "specimens": [
     {
       "title": "TimeBoundary",
@@ -63,6 +74,5 @@
       "note": "One row, placed by the caller — which is the difference between this and DaySeparator, which takes a whole message list and inserts its own. A transcript assembled from a row union needs the boundary as a member of that union. It is a role=separator carrying its label as its name, with the text inside aria-hidden so a reader hears 'Today' once rather than twice, and the caller pre-formats the words because this family owns no locale.",
       "interaction": "none. It is a rule with a word on it, and nothing here takes focus."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/time-field.json

@@ -65,7 +65,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A typed time of day, segment by segment.",
+  "summary": "A typed time of day, segment by segment — the sibling of `DateField`.",
   "examples": [
     {
       "title": "Usage",
@@ -73,10 +73,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/time-field",
   "mdUrl": "/docs/components/time-field.md",
   "jsonUrl": "/r/components/time-field.json",
+  "whenToUse": [
+    "The half of a schedule a calendar cannot express.",
+    "A control room: pass `hourCycle={24}` for a show clock, so the AM/PM segment is not one more thing to tab through."
+  ],
+  "whenNotToUse": [
+    "A date. Use `DateField`.",
+    "A duration. A time of day and a length are different quantities."
+  ],
+  "commonMistakes": [
+    "Passing a string. Values are `@internationalized/date` `Time` objects.",
+    "Leaving the 12-hour cycle in a 24-hour room, which adds a segment nobody there reads."
+  ],
   "specimens": [
     {
       "title": "TimeField",
@@ -88,6 +100,5 @@
       "note": "The same field, for a clock time. Granularity decides how many segments there are.",
       "interaction": "same segment stepping; 24-hour or 12-hour follows the locale, not a prop."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/timeline-ruler.json

@@ -158,10 +158,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/timeline-ruler",
   "mdUrl": "/docs/components/timeline-ruler.md",
   "jsonUrl": "/r/components/timeline-ruler.json",
+  "whenToUse": [
+    "Above any arrangement or timeline the user scrolls and zooms.",
+    "Anywhere the tick density must stay readable across zoom levels — `targetPx` is the spacing it aims for."
+  ],
+  "whenNotToUse": [
+    "A fixed, short timeline. Ticks you can hard-code need no ladder."
+  ],
+  "commonMistakes": [
+    "Multiplying the chosen interval after picking it from the ladder, which is what made the original four times sparser than the spacing it aimed for.",
+    "Setting the cull margin in beats. At a tight zoom fifty beats is an enormous overdraw — `bufferPx` is in pixels for that reason."
+  ],
   "specimens": [
     {
       "title": "TimelineRuler",
@@ -173,6 +184,5 @@
       "note": "Zoom-adaptive tick density, targeting roughly one tick per centimetre. The interval choice is a pure exported function, so it can be tested without a DOM.",
       "interaction": "none itself; it is the coordinate system a track editor draws under. `pxPerBeat` stays in pixels on purpose."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/timeline.json

@@ -111,10 +111,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/timeline",
   "mdUrl": "/docs/components/timeline.md",
   "jsonUrl": "/r/components/timeline.json",
+  "whenToUse": [
+    "Events whose order in time is the point, and where the gaps between them carry meaning.",
+    "A history the reader scans downward rather than searches."
+  ],
+  "whenNotToUse": [
+    "Records the reader needs to sort, filter or compare across columns. Use a data table.",
+    "A sequence the user is stepping through now. Use `Stepper`."
+  ],
+  "commonMistakes": [
+    "Using it for an unordered list, where the rail asserts a sequence that is not there."
+  ],
   "specimens": [
     {
       "title": "Timeline",
@@ -126,6 +137,5 @@
       "note": "An ordered list with tone markers taken from `StatusDot`, so a timeline and a status row agree on what amber means.",
       "interaction": "none. A timeline is a record."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/title-bar.json

@@ -77,10 +77,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/title-bar",
   "mdUrl": "/docs/components/title-bar.md",
   "jsonUrl": "/r/components/title-bar.json",
+  "whenToUse": [
+    "A desktop-shaped surface with its own window chrome.",
+    "Anywhere the bar must be draggable as a window handle — that is what `platformDrag` is for."
+  ],
+  "whenNotToUse": [
+    "A page header inside a browser tab. Use `PageShell`'s header.",
+    "A panel's top bar. Use `PanelHeader`."
+  ],
+  "commonMistakes": [
+    "Putting interactive controls inside the drag region without exempting them, so a click starts a window drag instead of pressing the control."
+  ],
   "specimens": [
     {
       "title": "TitleBar",
@@ -92,6 +103,5 @@
       "note": "Window furniture, sized from the chrome rung rather than the control ladder.",
       "interaction": "the drag region is inert in a browser; `platformDrag` turns it on for Electron and Tauri."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/todo-list.json

@@ -56,10 +56,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/todo-list",
   "mdUrl": "/docs/components/todo-list.md",
   "jsonUrl": "/r/components/todo-list.json",
+  "whenToUse": [
+    "A plan the agent rewrites as it goes — items added, reordered and completed in any order between renders."
+  ],
+  "whenNotToUse": [
+    "A checklist the user owns and ticks. This is the agent's list as it stands right now."
+  ],
+  "commonMistakes": [
+    "Diffing the previous list to preserve statuses. Each item carries its own status, so pass the list as it stands.",
+    "Passing `revision` when you are not counting rewrites. Omit it and the header shows a plain done/total count instead."
+  ],
   "specimens": [
     {
       "title": "TodoList",
@@ -71,6 +81,5 @@
       "note": "The agent's own working list, which is not the plan: it is rewritten mid-run as the job turns out to be bigger. Items carry their own status, so more than one can be active, and `revision` is what makes a rewrite legible rather than alarming.",
       "interaction": "none, and deliberately: a reader who could tick these off would be editing the agent's mind."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/toggle-group.json

@@ -105,7 +105,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A cluster of {@link Toggle }s sharing one pressed state.",
+  "summary": "A cluster of toggles sharing one pressed state — and it may be empty.",
   "examples": [
     {
       "title": "Usage",
@@ -113,10 +113,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/toggle-group",
   "mdUrl": "/docs/components/toggle-group.md",
   "jsonUrl": "/r/components/toggle-group.json",
+  "whenToUse": [
+    "A filter bar, where 'no filter' must be reachable: pressing the pressed item unpresses it.",
+    "Several answers at once, with `multiple`."
+  ],
+  "whenNotToUse": [
+    "A view switcher or anything where the answer is always one of N. Use `SegmentedControl` — offering an empty state there is a bug.",
+    "Actions rather than a choice. Use `ButtonGroup`."
+  ],
+  "commonMistakes": [
+    "Choosing between this and `SegmentedControl` on looks. The difference is not cosmetic: only one of them can be empty.",
+    "Setting `size` on the children. The group publishes its density rung through context."
+  ],
   "specimens": [
     {
       "title": "Toggle / ToggleGroup",
@@ -129,6 +141,5 @@
       "note": "A button that stays pressed, and a set of them. `aria-pressed` carries the state.",
       "interaction": "hover tints the ground; pressed is accent-soft, on the same ruling as the active tab."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/toggle.json

@@ -111,7 +111,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A two-state button: solo, mute, snap-to-grid, \"show hidden\".",
+  "summary": "A two-state button: solo, mute, snap-to-grid, 'show hidden'.",
   "examples": [
     {
       "title": "Usage",
@@ -119,10 +119,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/toggle",
   "mdUrl": "/docs/components/toggle.md",
   "jsonUrl": "/r/components/toggle.json",
+  "whenToUse": [
+    "A mode you switch from a toolbar, next to other buttons.",
+    "Anywhere the control should read as a button that stays down rather than a setting."
+  ],
+  "whenNotToUse": [
+    "A setting in a list. Use `Switch`, which reads as a physical throw and announces `aria-checked`.",
+    "One of N. Use `SegmentedControl`."
+  ],
+  "commonMistakes": [
+    "Reaching for `Switch` because both are two-state. The distinction is where it lives and what it announces: `aria-pressed` for a toggle, `aria-checked` for a switch.",
+    "Faking the pressed state on a plain `Button` with a class. Assistive technology hears nothing."
+  ],
   "specimens": [
     {
       "title": "Toggle / ToggleGroup",
@@ -135,6 +147,5 @@
       "note": "A button that stays pressed, and a set of them. `aria-pressed` carries the state.",
       "interaction": "hover tints the ground; pressed is accent-soft, on the same ruling as the active tab."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/token-editor.json

@@ -90,7 +90,7 @@
     "--cue-text-label",
     "--cue-text-micro"
   ],
-  "summary": "The grouped colour rows.",
+  "summary": "The grouped colour rows — stateless by design.",
   "examples": [
     {
       "title": "Usage",
@@ -98,9 +98,18 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/token-editor",
   "mdUrl": "/docs/components/token-editor.md",
   "jsonUrl": "/r/components/token-editor.json",
-  "todo": true
+  "whenToUse": [
+    "Anywhere token rows are wanted: it renders the values it is handed and reports edits back.",
+    "Reusing the configurator's editing surface without adopting its override model."
+  ],
+  "whenNotToUse": [
+    "Owning state. It has none; the caller owns the override model."
+  ],
+  "commonMistakes": [
+    "Importing it expecting `react-aria-components` to come along. That is an **optional peer** — install it where you use these rows."
+  ]
 }

package/manifest/components/tool-call.json

@@ -127,10 +127,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/tool-call",
   "mdUrl": "/docs/components/tool-call.md",
   "jsonUrl": "/r/components/tool-call.json",
+  "whenToUse": [
+    "A single tool call in a transcript, collapsed to a row with its name, a query chip and a status."
+  ],
+  "whenNotToUse": [
+    "Several calls issued together, or a call that failed. The trigger here has two states — a spinner while `running`, a success check otherwise."
+  ],
+  "commonMistakes": [
+    "Passing objects to `request` and `result`. Both are strings shown in the expanded disclosure, so serialise before you pass.",
+    "Setting `activeLabel` to the same words as `label`. The active one is the verb shown with a shimmer while the tool runs — `Searching the docs` against `Searched`.",
+    "Owning `open` inside. It is required alongside `onOpenChange`, so the disclosure belongs to the caller."
+  ],
   "specimens": [
     {
       "title": "ToolCall",
@@ -142,6 +153,5 @@
       "note": "One invocation, with the request and the result behind a disclosure. While it runs the verb shimmers and the row is wider; when it settles the label swaps, the box shrinks to fit and a check lands. Both payloads are printed as text, never parsed.",
       "interaction": "the whole trigger row is the toggle, and it takes focus. The check fades in rather than appearing, so a settled call reads as having settled."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/tool-error.json

@@ -113,7 +113,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "One call failed.",
+  "summary": "One call failed: the error, the attempt count, and a retry that doesn't restart the turn.",
   "examples": [
     {
       "title": "Usage",
@@ -121,10 +121,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/tool-error",
   "mdUrl": "/docs/components/tool-error.md",
   "jsonUrl": "/r/components/tool-error.json",
+  "whenToUse": [
+    "A single failed tool call inside a turn that can carry on — retry the call, or skip it and let the turn continue."
+  ],
+  "whenNotToUse": [
+    "A reworded, friendly error. `message` is the raw error, shown in mono rather than reworded."
+  ],
+  "commonMistakes": [
+    "Wiring `onRetry` to re-run the turn. It runs the call again without restarting it.",
+    "Leaving `retrying` false during the retry, so the control stays live instead of swapping for a spinner and disabling itself.",
+    "Passing `attempt` without a truthful `maxAttempts`. The pair is what tells the reader whether the runtime will try again."
+  ],
   "specimens": [
     {
       "title": "ToolError",
@@ -136,6 +147,5 @@
       "note": "One call failed, and the turn did not. The message is the raw error in mono rather than a reworded one, the attempt count is the runtime's, and Retry re-runs the call in place. Skip is disabled unless the host offers one, because a control that cannot do anything should say so.",
       "interaction": "Retry raises the attempt count here; Skip puts it back. While retrying, the control is a spinner and takes no clicks."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/tool-group.json

@@ -77,10 +77,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/tool-group",
   "mdUrl": "/docs/components/tool-group.md",
   "jsonUrl": "/r/components/tool-group.json",
+  "whenToUse": [
+    "A parallel fan-out — `Read 4 files in parallel` — where the summary is enough until it is not."
+  ],
+  "whenNotToUse": [
+    "Calls that ran one after another for different reasons. This is about calls issued together, summarised as one line."
+  ],
+  "commonMistakes": [
+    "Writing your own count into `label`. The header summarises the calls itself: progress while any run, failures if any failed, otherwise the count.",
+    "Owning `open` inside. It is required, with `onOpenChange` reporting the toggle."
+  ],
   "specimens": [
     {
       "title": "ToolGroup",
@@ -92,6 +102,5 @@
       "note": "Calls that went out together, rolled up to one row. The summary counts rather than describes: progress while any are still out, the failure count if any failed, otherwise the total.",
       "interaction": "the header is one button with aria-expanded; the rows underneath are a list, not a menu."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/tool-timeline.json

@@ -119,7 +119,7 @@
     "--cue-text-body",
     "--cue-text-label"
   ],
-  "summary": "A whole working session summarized as verbs, targets, and file stats.",
+  "summary": "A whole working session summarised as verbs, targets, and file stats.",
   "examples": [
     {
       "title": "Usage",
@@ -127,10 +127,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/tool-timeline",
   "mdUrl": "/docs/components/tool-timeline.md",
   "jsonUrl": "/r/components/tool-timeline.json",
+  "whenToUse": [
+    "A session's worth of work under one trigger: verbs and chips as steps, with per-file addition and removal counts beneath them."
+  ],
+  "whenNotToUse": [
+    "A single live call. This is the session summary, with a resting label for after and a live one for during."
+  ],
+  "commonMistakes": [
+    "Passing the same string as `restingLabel` and `activeLabel`. One is `Worked for 12s` once streaming stops; the other is the full-size live label, `Working for 12s`.",
+    "Slicing `steps` to what has been revealed. `visibleSteps` is how many from the start are shown.",
+    "Leaving `stats` out. It is required, and it is the per-file added and removed counts listed under the steps."
+  ],
   "specimens": [
     {
       "title": "ToolTimeline",
@@ -142,6 +153,5 @@
       "note": "A whole working session folded into one line — `Read 4 files, ran 1 command` — that opens into the verbs, the things they were done to, and the files that ended up changed. It is the summary a transcript gets *after* the fact, where `ToolCall` is what it looks like during.",
       "interaction": "the trigger is a labelled button taking cue's focus ring; the chevron turns with the panel, which animates its own height through Base UI. While streaming the label shimmers and the live step's verb shimmers with it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/toolbar.json

@@ -164,7 +164,7 @@
     "--cue-surface-2",
     "--cue-text-ui"
   ],
-  "summary": "The strip of controls across the top of a view.",
+  "summary": "The strip of controls across the top of a view — one tab stop, arrow keys inside.",
   "examples": [
     {
       "title": "Usage",
@@ -172,10 +172,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/toolbar",
   "mdUrl": "/docs/components/toolbar.md",
   "jsonUrl": "/r/components/toolbar.json",
+  "whenToUse": [
+    "Any row of controls acting on the view beneath it.",
+    "Anywhere a keyboard user should reach the bar once and move within it, rather than tabbing through every button."
+  ],
+  "whenNotToUse": [
+    "A page header. Use `PanelHeader` or `TitleBar`.",
+    "A set of choices. Use `SegmentedControl` or `ToggleGroup`."
+  ],
+  "commonMistakes": [
+    "Hand-rolling it as a flex row of buttons, which puts every button in the tab order and loses the ARIA toolbar pattern that is the entire point."
+  ],
   "specimens": [
     {
       "title": "Toolbar",
@@ -187,6 +198,5 @@
       "note": "Borderless text-colour feedback: a pressed tool changes ink, not ground. Boxed to 16rem below, the bar scrolls rather than clipping — it stays one chrome rung tall, because a second row would be stolen from the work area.",
       "interaction": "hover lifts the ink to `--cue-fg`; arrow keys move between tools and reach the ones off-screen, Tab leaves the toolbar."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/trace-waterfall.json

@@ -64,10 +64,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/trace-waterfall",
   "mdUrl": "/docs/components/trace-waterfall.md",
   "jsonUrl": "/r/components/trace-waterfall.json",
+  "whenToUse": [
+    "A run's spans on a shared axis, where the question is which part took the time."
+  ],
+  "whenNotToUse": [
+    "A tree you expect to be laid out from parent links. The list is flat, in start order, and nesting comes from each span's own depth."
+  ],
+  "commonMistakes": [
+    "Passing the widest span's duration as `totalMs`. Bars are positioned against the axis you give, not against the widest span, so a wrong total silently rescales every bar.",
+    "Sorting spans by duration. Start order is what makes a waterfall readable."
+  ],
   "specimens": [
     {
       "title": "TraceWaterfall",
@@ -79,6 +89,5 @@
       "note": "Where the run's time actually went. Bars are positioned against `totalMs` rather than against the widest span, which is the difference between a trace and a bar chart: a 20ms retry at the end stays 20ms wide.",
       "interaction": "none. Running spans pulse in the stream hue, failed ones are red, and both are spelled out in the row rather than only tinted."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/tree-visibility-toggle.json

@@ -78,10 +78,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/tree-visibility-toggle",
   "mdUrl": "/docs/components/tree-visibility-toggle.md",
   "jsonUrl": "/r/components/tree-visibility-toggle.json",
+  "whenToUse": [
+    "A rig or scene graph where 'there but out of the way' is a real answer.",
+    "Anywhere ghosting keeps a reference visible while the user works behind it."
+  ],
+  "whenNotToUse": [
+    "A two-answer visibility flag. Use `Checkbox` or `Switch`; a third state nobody needs is a click nobody wants."
+  ],
+  "commonMistakes": [
+    "Collapsing ghost into hidden. That is what makes people toggle things off and lose their bearings — ghost is the state that earns the extra step.",
+    "Relying on the glyph alone. Pass `labels` so each state has a name."
+  ],
   "specimens": [
     {
       "title": "Tree",
@@ -94,6 +105,5 @@
       "note": "Roving tabindex, `└` indent guides, a hover-revealed control slot and the three-state visibility toggle.",
       "interaction": "arrow keys move and expand, Enter selects; the row controls appear on hover and stay put for keyboard users."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/tree.json

@@ -161,10 +161,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/tree",
   "mdUrl": "/docs/components/tree.md",
   "jsonUrl": "/r/components/tree.json",
+  "whenToUse": [
+    "Nested structure the user expands, collapses and navigates by keyboard.",
+    "Large outlines — it is one tab stop with arrow keys inside, so eighty rows never mean eighty presses of Tab."
+  ],
+  "whenNotToUse": [
+    "A flat list. Use `Stack` of `Item`, or a table.",
+    "Navigation between routes. Use `Sidebar`."
+  ],
+  "commonMistakes": [
+    "Rebuilding it from nested `<ul>`s with click handlers. The cost is in three details together — roving tabindex, a flat DOM carrying `aria-level` / `aria-posinset` / `aria-setsize`, and the keyboard contract — and a hand-rolled version gets at most two.",
+    "Putting each row in the tab order, which is the defect the roving tabindex exists to prevent."
+  ],
   "specimens": [
     {
       "title": "Tree",
@@ -177,6 +189,5 @@
       "note": "Roving tabindex, `└` indent guides, a hover-revealed control slot and the three-state visibility toggle.",
       "interaction": "arrow keys move and expand, Enter selects; the row controls appear on hover and stay put for keyboard users."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/turn-footer.json

@@ -113,10 +113,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/turn-footer",
   "mdUrl": "/docs/components/turn-footer.md",
   "jsonUrl": "/r/components/turn-footer.json",
+  "whenToUse": [
+    "Under a settled turn, with only the controls the product actually has — passing no handler draws no button.",
+    "A read-only shared transcript: one `onCopy` and a timestamp, and nothing else is drawn."
+  ],
+  "whenNotToUse": [
+    "A row that should appear on hover. Revealing is a decision about the turn, not this row — two lines of CSS keyed off the turn's own hover state, and instant rather than a fade, which reads as lag."
+  ],
+  "commonMistakes": [
+    "Passing every handler because the four look like one set. They are not: a footer that drew disabled controls for what a product lacks would be a row of things nobody can press.",
+    "Setting `copied` on the press rather than on the clipboard write. The glyph crossfades to a check and stays there until the caller clears it.",
+    "Restating all four strings to localise two. `labels` is partial, merged over `TURN_ACTION_LABELS`."
+  ],
   "specimens": [
     {
       "title": "TurnFooter",
@@ -128,6 +140,5 @@
       "note": "The row under a finished turn: copy, reply, fork, and when it happened. Every control is opt-in, because the four are not one set — a read-only shared transcript has a copy button and nothing else, and a footer that drew disabled controls would be a row of things nobody can press. The timestamp is three levels at once: 2m ago at a glance, the exact time on the title where it costs nothing, and how long the work took beside it, which is the only one of the three that is about the agent rather than the clock.",
       "interaction": "four named icon buttons; copy crossfades to a check in place and renames itself Copied. The four names come from TURN_ACTION_LABELS and a partial override merges over it, so localising two of them does not mean restating the other three."
     }
-  ],
-  "todo": true
+  ]
 }