@cueplusplus/ui 0.13.0 → 0.14.1

package/manifest/components/data-table-toolbar.json

@@ -106,10 +106,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/data-table-toolbar",
   "mdUrl": "/docs/components/data-table-toolbar.md",
   "jsonUrl": "/r/components/data-table-toolbar.json",
+  "whenToUse": [
+    "Any filterable table.",
+    "Anywhere the reader needs to tell an empty table from an over-tight filter — that is what `count`/`total` is for."
+  ],
+  "whenNotToUse": [
+    "A table with nothing to filter or act on."
+  ],
+  "commonMistakes": [
+    "Leaving out the count. '12/340' beside a filter box is the difference between 'the table is empty' and 'the filter is too tight', and it is the first thing a hand-rolled toolbar drops."
+  ],
   "specimens": [
     {
       "title": "DataTable recipe",
@@ -122,6 +132,5 @@
       "note": "Not a component: `useCueTable` wires four TanStack v9 features, `DataTableToolbar` and `DataTablePagination` supply the chrome, and the markup stays at the call site. Rendered through the same Table above.",
       "interaction": "the header cells are buttons that toggle sorting; the pager disables at the ends rather than hiding."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/date-field.json

@@ -73,10 +73,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/date-field",
   "mdUrl": "/docs/components/date-field.md",
   "jsonUrl": "/r/components/date-field.json",
+  "whenToUse": [
+    "A date the user already knows. Typing is faster than three clicks.",
+    "Anywhere `03/04` must not be ambiguous — segments cannot produce it."
+  ],
+  "whenNotToUse": [
+    "A date the user needs to *find*. Use `DatePicker`, which shows the month."
+  ],
+  "commonMistakes": [
+    "Rebuilding it from three number inputs, which loses locale-aware segment order, overflow between segments and the `spinbutton` ARIA."
+  ],
   "specimens": [
     {
       "title": "DateField",
@@ -88,6 +98,5 @@
       "note": "Typed, one segment at a time, with no calendar. Values are `@internationalized/date` objects, which can hold a day without a timezone attached.",
       "interaction": "each segment is a `spinbutton`: arrow keys step it, typing overflows into the next one."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/date-picker.json

@@ -235,10 +235,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/date-picker",
   "mdUrl": "/docs/components/date-picker.md",
   "jsonUrl": "/r/components/date-picker.json",
+  "whenToUse": [
+    "A date the user wants to see in context — weekends, a month's shape.",
+    "Anywhere the trigger must line up with the inputs beside it: it is a control-chassis button at every density."
+  ],
+  "whenNotToUse": [
+    "A known date. Use `DateField`.",
+    "A span. Use `DateRangePicker`."
+  ],
+  "commonMistakes": [
+    "Rendering the calendar outside the kit's `Popover`, which drops it out of the portal contract and renders it at the wrong theme and density."
+  ],
   "specimens": [
     {
       "title": "DatePicker",
@@ -250,6 +261,5 @@
       "note": "The calendar inside a popover, on the form chassis. The trigger prints the formatted date, or the placeholder when there is none.",
       "interaction": "the popup is portalled through the stamping contract, so it keeps the theme and density of the island it was opened from."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/date-range-picker.json

@@ -235,10 +235,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/date-range-picker",
   "mdUrl": "/docs/components/date-range-picker.md",
   "jsonUrl": "/r/components/date-range-picker.json",
+  "whenToUse": [
+    "A from/to range — a report window, a run of shows."
+  ],
+  "whenNotToUse": [
+    "One day. Use `DatePicker`."
+  ],
+  "commonMistakes": [
+    "Expecting it to dismiss like `DatePicker`. A range takes two clicks, so the popup stays open through the first and the caller hears about both — close it from `onValueChange` when `to` arrives if a one-shot flow suits the page."
+  ],
   "specimens": [
     {
       "title": "DateRangePicker",
@@ -250,6 +259,5 @@
       "note": "Two days in one control, formatted as one string.",
       "interaction": "the first click sets the start, the second the end; clicking before the start restarts the range."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/day-separator.json

@@ -43,10 +43,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/day-separator",
   "mdUrl": "/docs/components/day-separator.md",
   "jsonUrl": "/r/components/day-separator.json",
+  "whenToUse": [
+    "Threads long enough that 'when' stops being obvious."
+  ],
+  "whenNotToUse": [
+    "A compaction. Use `CompactionRow`.",
+    "A short conversation, where every message is clearly from the same sitting."
+  ],
+  "commonMistakes": [
+    "Stamping every message with a full date, which is the noise this replaces."
+  ],
   "specimens": [
     {
       "title": "DaySeparator",
@@ -58,6 +68,5 @@
       "note": "Chronology in a thread long enough to have some: a rule wherever the day changes, and per-message times that only appear when you go looking. The caller pre-formats both — the element compares the day strings and does no date arithmetic at all.",
       "interaction": "hover a turn and its timestamp fades up beside it. The rules are decorative; nothing here is a control."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/delegation-card.json

@@ -168,7 +168,7 @@
     "--cue-text-micro",
     "--cue-text-ui"
   ],
-  "summary": "One delegation, folded into a card.",
+  "summary": "One delegation, folded into a card: who was asked, what for, and their transcript behind a disclosure.",
   "examples": [
     {
       "title": "Usage",
@@ -176,10 +176,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/delegation-card",
   "mdUrl": "/docs/components/delegation-card.md",
   "jsonUrl": "/r/components/delegation-card.json",
+  "whenToUse": [
+    "Any multi-agent run. A tree rendered flat is what turns a transcript into noise.",
+    "Anywhere nesting depth must stay legible — the rail takes the sub-agent's colour."
+  ],
+  "whenNotToUse": [
+    "A single-agent conversation. Use `Message`."
+  ],
+  "commonMistakes": [
+    "Rendering sub-agent turns inline beside the parent's, which loses which turns belong to whom and how deep they are.",
+    "Opening every delegation by default, which undoes the fold."
+  ],
   "specimens": [
     {
       "title": "DelegationCard",
@@ -191,6 +202,5 @@
       "note": "A nested transcript with a per-agent left rail in that agent's colour. Collapsible, because a delegation is usually a detail.",
       "interaction": "the header row is the toggle; the status is spelled out as well as tinted."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/density.json

@@ -85,9 +85,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/density",
   "mdUrl": "/docs/components/density.md",
   "jsonUrl": "/r/components/density.json",
-  "todo": true
+  "whenToUse": [
+    "A region that should be denser or roomier than the page around it — a compact table inside a comfortable page.",
+    "Anywhere nesting must be free: it renders a plain `<div>` and the geometry properties inherit down, so no JS runs."
+  ],
+  "whenNotToUse": [
+    "The whole document. Set density on the provider.",
+    "One control's height. Use that control's `size`."
+  ],
+  "commonMistakes": [
+    "Reading the React context to style something. The DOM attributes are the source of truth; the context exists for the rare JS reads like portal stamping."
+  ]
 }

package/manifest/components/description-list.json

@@ -69,12 +69,24 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "The `<dl>` family: {@link DescriptionListRoot}, `Term` and `Detail`.",
+  "summary": "The `<dl>` family: a root, `Term` and `Detail`.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/description-list",
   "mdUrl": "/docs/components/description-list.md",
   "jsonUrl": "/r/components/description-list.json",
+  "whenToUse": [
+    "Name/value pairs that belong together: metadata, a settings summary, a specification.",
+    "Anywhere the pairing should exist in the accessibility tree rather than only in the layout."
+  ],
+  "whenNotToUse": [
+    "Tabular data with more than one value per row. Use a table.",
+    "A form. A description list shows values; it does not edit them."
+  ],
+  "commonMistakes": [
+    "Faking it with a two-column `Grid`, which loses the `<dl>` semantics that make the pairing real.",
+    "Putting a `Detail` with no `Term`, which leaves a value nothing names."
+  ],
   "specimens": [
     {
       "title": "DescriptionList",
@@ -86,6 +98,5 @@
       "note": "Two layouts: inline pairs for a sidebar, stacked for a page.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/diagram.json

@@ -106,10 +106,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/diagram",
   "mdUrl": "/docs/components/diagram.md",
   "jsonUrl": "/r/components/diagram.json",
+  "whenToUse": [
+    "A rendered graphic that needs a titled frame with zoom, reset and expand around it.",
+    "A drawing small enough to sit inline but worth opening full screen, through `onExpand`."
+  ],
+  "whenNotToUse": [
+    "Markup you want the element to parse. It never parses or injects markup itself, so whatever renders your chart stays your choice."
+  ],
+  "commonMistakes": [
+    "Expecting the zoom controls to clamp. `onZoomIn` and `onZoomOut` only report the press — clamp the range yourself.",
+    "Passing `zoom` as a percentage. 1 is fit, and the header prints the percentage for you."
+  ],
   "specimens": [
     {
       "title": "Diagram",
@@ -121,6 +132,5 @@
       "note": "A drawn answer with a viewport around it: zoom, reset, full-bleed. The graphic is yours — the element supplies the frame, the percentage readout and the transform, and never parses or renders anything itself.",
       "interaction": "four named icon buttons; expand disables itself when no handler is given, which is the honest state for a bench with nowhere to expand to. The scale transition stops under reduced motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/disclosure.json

@@ -106,7 +106,7 @@
     "--cue-text-micro",
     "--cue-text-ui"
   ],
-  "summary": "The \"advanced\" idiom: a chromeless `▸ advanced` toggle over the fields most users never touch.",
+  "summary": "The 'advanced' idiom: a chromeless `▸ advanced` toggle over the fields most users never touch.",
   "examples": [
     {
       "title": "Usage",
@@ -114,10 +114,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/disclosure",
   "mdUrl": "/docs/components/disclosure.md",
   "jsonUrl": "/r/components/disclosure.json",
+  "whenToUse": [
+    "Optional fields inside a form — the ones that matter to a few people and would otherwise lengthen the page for everyone.",
+    "Anywhere the toggle should read as an annotation on the form rather than a division of it."
+  ],
+  "whenNotToUse": [
+    "A section that peers with the sections around it. Use `Collapsible`.",
+    "Content the user is expected to read. Progressive disclosure hides it; if it matters, show it."
+  ],
+  "commonMistakes": [
+    "Reaching for `Collapsible` instead. It is deliberately not one: giving these fields a summary row that looks like a section header is what makes forms read as twice as long as they are.",
+    "Dressing it up with a rim or a fill. It is drawn as quietly as the system can draw anything — one triangle and micro caption ink."
+  ],
   "specimens": [
     {
       "title": "Disclosure",
@@ -129,6 +141,5 @@
       "note": "The `advanced` idiom: a chromeless mono `▸ label` toggle for the settings most people never open.",
       "interaction": "the caret rotates; nothing else moves."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/dmx-bar.json

@@ -87,10 +87,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/dmx-bar",
   "mdUrl": "/docs/components/dmx-bar.md",
   "jsonUrl": "/r/components/dmx-bar.json",
+  "whenToUse": [
+    "A live universe readout that must stay cheap enough to leave running at wire rate.",
+    "Under a node in a routing graph, where the shape of the output is the reading."
+  ],
+  "whenNotToUse": [
+    "Per-channel inspection. Use `ChannelMatrix`."
+  ],
+  "commonMistakes": [
+    "Re-rendering it from React state per frame. The whole design is about what happens *between* frames."
+  ],
   "specimens": [
     {
       "title": "DmxBar",
@@ -102,6 +112,5 @@
       "note": "The whole universe as one 512×1 texture, scaled up with `image-rendering: pixelated` on a true-black ground. Interpolating between two channels would draw levels nobody sent.",
       "interaction": "hovering reports `CH n · v` through a portaled readout, positioned by percentage so it survives a scaled container; the number is written to a span through a ref rather than re-rendering at 40 Hz."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/dmx-strip.json

@@ -97,10 +97,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/dmx-strip",
   "mdUrl": "/docs/components/dmx-strip.md",
   "jsonUrl": "/r/components/dmx-strip.json",
+  "whenToUse": [
+    "Marketing and docs, where the device should look alive without a wire behind it."
+  ],
+  "whenNotToUse": [
+    "Real output. Use `DmxBar`, which draws actual channel data."
+  ],
+  "commonMistakes": [
+    "Presenting it as live data. It is a model of a plausible rig — the same canvas the bridge uses, driven by a simulation."
+  ],
   "specimens": [
     {
       "title": "DmxStrip",
@@ -112,6 +121,5 @@
       "note": "A seeded fixture simulation: mulberry32 from the `seed` prop, so the same seed draws the same rig every time. Values ramp rather than jump.",
       "interaction": "the readout updates through a ref; under prefers-reduced-motion the strip paints one static frame instead of animating."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/document-reference.json

@@ -88,10 +88,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/document-reference",
   "mdUrl": "/docs/components/document-reference.md",
   "jsonUrl": "/r/components/document-reference.json",
+  "whenToUse": [
+    "Showing which passages of a source the answer drew on, each pinned to a page.",
+    "Sending the reader to the page an anchor sits on, through `onJump`."
+  ],
+  "whenNotToUse": [
+    "A source with no page structure. `pages` and per-page anchors are the shape of the element."
+  ],
+  "commonMistakes": [
+    "Assuming every page highlights something. A page with no anchor highlights nothing.",
+    "Expecting `onJump` to move `activePage` for you. It reports the page to open; the state stays yours."
+  ],
   "specimens": [
     {
       "title": "DocumentReference",
@@ -103,6 +114,5 @@
       "note": "One document the answer leans on, with the passages it quoted and the page each is on. Several anchors can cite one page — two of these are both page 31 — so the current one is marked by `aria-current` rather than by matching the number, which is what stops the wrong row lighting up.",
       "interaction": "every quote is a button that reports its page to `onJump`; the active row takes the recessed field ground, the others only on hover."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/draft-restore.json

@@ -76,10 +76,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/draft-restore",
   "mdUrl": "/docs/components/draft-restore.md",
   "jsonUrl": "/r/components/draft-restore.json",
+  "whenToUse": [
+    "Returning to a thread that has unsent composer text saved against it.",
+    "A one-line preview of that text with when it was last touched beside it."
+  ],
+  "whenNotToUse": [
+    "A long draft you want shown in full. `draft` is truncated to one line."
+  ],
+  "commonMistakes": [
+    "Passing a timestamp to `savedAt`. It is printed as given, so pre-format it.",
+    "Wiring only `onRestore`. Without `onDiscard` the prompt has no way to go away for good."
+  ],
   "specimens": [
     {
       "title": "DraftRestore",
@@ -91,6 +102,5 @@
       "note": "Come back to a thread and the sentence you never sent is still sitting there. One line of what it was, when it was saved, and the two answers anybody ever has for it. `savedAt` is pre-formatted like every other time in this family — the element does no date maths, so a server-rendered draft and a client-rendered one cannot disagree.",
       "interaction": "restore is a worded button and discard is a labelled icon (`Discard the draft`): the destructive one is the one that has to be aimed at."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/drawer.json

@@ -176,7 +176,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A swipe-dismissable edge panel — the touch-first cousin of {@link Sheet }.",
+  "summary": "A swipe-dismissable edge panel — the touch-first cousin of `Sheet`.",
   "examples": [
     {
       "title": "Usage",
@@ -184,10 +184,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/drawer",
   "mdUrl": "/docs/components/drawer.md",
   "jsonUrl": "/r/components/drawer.json",
+  "whenToUse": [
+    "Touch surfaces, where dragging a panel away is the natural dismissal.",
+    "Stacked panels: nested-drawer stacking comes from the primitive."
+  ],
+  "whenNotToUse": [
+    "Pointer-first consoles. Use `Sheet`."
+  ],
+  "commonMistakes": [
+    "Setting the edge and the gesture separately. `swipeDirection` picks both together on purpose, so a drawer can never be dragged in a direction that does not dismiss it."
+  ],
   "specimens": [
     {
       "title": "Drawer",
@@ -199,6 +209,5 @@
       "note": "The touch-first sheet: a grab handle and a swipe direction.",
       "interaction": "drag the handle to dismiss; on a pointer device it behaves as an ordinary sheet."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/edit-message.json

@@ -111,10 +111,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/edit-message",
   "mdUrl": "/docs/components/edit-message.md",
   "jsonUrl": "/r/components/edit-message.json",
+  "whenToUse": [
+    "Editing a message already in the transcript, where the cost — the replies after it — should be stated before sending.",
+    "A turn that reads as a plain bubble until it is clicked, with `onStartEdit` opening the composer."
+  ],
+  "whenNotToUse": [
+    "Composing a new message. This swaps between a resting bubble and an edit composer for a turn that already exists."
+  ],
+  "commonMistakes": [
+    "Expecting `onCancel` to put the old text back. Restore the original yourself.",
+    "Passing `discardedReplies={0}` while replies exist. The warning hides at zero, which silently removes the one thing the element is for."
+  ],
   "specimens": [
     {
       "title": "EditMessage",
@@ -126,6 +137,5 @@
       "note": "Rewriting a turn you already sent, told up front what it throws away. The count is the point: editing the third message of a thread discards everything after it, and a control that hid that would be a data-loss trap wearing a pencil icon.",
       "interaction": "resting, the whole bubble is the button that starts an edit. Editing, the textarea is labelled and takes cue's focus ring; Send leads and Cancel is a ghost."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elements-command-palette.json

@@ -102,10 +102,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elements-command-palette",
   "mdUrl": "/docs/components/elements-command-palette.md",
   "jsonUrl": "/r/components/elements-command-palette.json",
+  "whenToUse": [
+    "A keystroke-away list of every runnable command in the app.",
+    "A list where the arrow keys and Enter should already work, because the element owns the key handling."
+  ],
+  "whenNotToUse": [
+    "A menu whose grouping you want to control. Groups are derived from the entries and keep first-seen order."
+  ],
+  "commonMistakes": [
+    "Adding your own arrow-key and Enter handling. The element owns the key handling and reports where it landed through `onActiveChange`.",
+    "Treating `activeId` as the element's own state. It stays yours to hold; the element only reports the move."
+  ],
   "specimens": [
     {
       "title": "ElementsCommandPalette",
@@ -117,6 +128,5 @@
       "note": "Everything the console can do, one keystroke away and grouped by where it acts. The element owns the arrow keys and reports where they landed, so the highlighted row stays the caller's state — and `aria-activedescendant` moves the highlight without moving focus, which is what keeps typing and walking the list the same gesture. Groups are derived from the commands and keep first-seen order, so the palette cannot be re-ordered by accident.",
       "interaction": "the input is a combobox over a listbox; arrows walk, Enter runs, and a query that filters the active row out drops the descendant reference rather than pointing at nothing."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elements-composer.json

@@ -45,10 +45,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elements-composer",
   "mdUrl": "/docs/components/elements-composer.md",
   "jsonUrl": "/r/components/elements-composer.json",
+  "whenToUse": [
+    "A full message input that needs attachments, slash commands, mentions, a model picker, voice and context usage together.",
+    "A composer that has to show how much of the context window is gone alongside the input itself."
+  ],
+  "whenNotToUse": [
+    "A screen that only needs the shape of a composer rather than a working one."
+  ],
+  "commonMistakes": [
+    "Putting `ComposerInput` outside `ComposerBar`. The bar is the surface the input, the attachments and the toolbar sit on.",
+    "Hanging controls straight off `ComposerToolbar`. They go in `ComposerActions` clusters, one at each end."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -66,6 +77,5 @@
       "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
       "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elements-data-table.json

@@ -55,10 +55,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elements-data-table",
   "mdUrl": "/docs/components/elements-data-table.md",
   "jsonUrl": "/r/components/elements-data-table.json",
+  "whenToUse": [
+    "A short comparison the model produced as part of an answer — model name, context window and cost."
+  ],
+  "whenNotToUse": [
+    "A sortable, paginated dataset. `rows` is a small `ModelUsage[]` shaped for an answer."
+  ],
+  "commonMistakes": [
+    "Holding `cycle` constant and expecting the row entrance to replay. It is an identity key that remounts the body."
+  ],
   "specimens": [
     {
       "title": "ElementsDataTable",
@@ -70,6 +79,5 @@
       "note": "A small table the model can answer with directly — three columns, no sorting, no virtualisation, no header menu. It is `ElementsDataTable` because the package already sells a real one at `@cueplusplus/ui/instruments`: that one is a data grid, this one is a paragraph shaped like a grid, and the rename keeps a consumer from reaching for the wrong one.",
       "interaction": "none. `cycle` remounts the body, so a new answer's rows stagger in rather than mutating in place."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elements-timeline.json

@@ -57,10 +57,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elements-timeline",
   "mdUrl": "/docs/components/elements-timeline.md",
   "jsonUrl": "/r/components/elements-timeline.json",
+  "whenToUse": [
+    "Past and scheduled events shown together on one axis.",
+    "A run where the scheduled events should be visible before they resolve, with `visibleCount` moving as they do."
+  ],
+  "whenNotToUse": [
+    "Work that branches and rejoins rather than running along a single axis."
+  ],
+  "commonMistakes": [
+    "Passing only the resolved events. `events` holds past and scheduled together, and `visibleCount` says how many have resolved.",
+    "Ordering by resolution rather than chronologically. The events are expected in chronological order."
+  ],
   "specimens": [
     {
       "title": "ElementsTimeline",
@@ -72,6 +83,5 @@
       "note": "Events on one axis, with what already happened and what is still coming in the same list — `past`, `now` and `future` are one union, so a schedule and a history are the same component. It publishes as `ElementsTimeline` because cue already sells a `Timeline`; the spec asked for `ToolTimeline`, which turned out to be the next bench's name.",
       "interaction": "none. The now marker is the only one that pulses, and it holds still for a reader who asked for less motion."
     }
-  ],
-  "todo": true
+  ]
 }