@cueplusplus/ui 0.14.0 → 0.14.1

package/manifest/components/context-usage.json

@@ -70,7 +70,7 @@
     "--cue-text-body",
     "--cue-warn"
   ],
-  "summary": "Where the window went, what share each part of it took, and what that cost.",
+  "summary": "Where the window went, what share each part took, and what that cost.",
   "examples": [
     {
       "title": "Usage",
@@ -78,10 +78,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/context-usage",
   "mdUrl": "/docs/components/context-usage.md",
   "jsonUrl": "/r/components/context-usage.json",
+  "whenToUse": [
+    "Answering 'why did it forget the thing I said an hour ago' with *the venue's documents are 38k of it* rather than a number going up.",
+    "Anywhere the cost belongs beside the shape — the bar, the table and the stat rows are three readings of one thing."
+  ],
+  "whenNotToUse": [
+    "A limit alone. A context limit tells a reader nothing they can act on.",
+    "The breakdown without the bill. Use `ContextBreakdown`."
+  ],
+  "commonMistakes": [
+    "Rebuilding the breakdown as a grid of divs. It is a real table with real column headers, because three columns of numbers whose meaning is carried by the header is exactly what a table is for."
+  ],
   "specimens": [
     {
       "title": "ContextUsage",
@@ -93,6 +104,5 @@
       "note": "Where the window went, what share each part took, and what that cost — Cursor's tray, opencode's labels and Claude Code's table, which between them are a complete spec. The breakdown is a real table with real column headers because three columns of numbers whose meaning lives in the heading above them is exactly what a table is for. A category that names no tone takes the next hue in the family's rotation, so five rows are legible without the caller choosing five colours that fight.",
       "interaction": "none. The bar is aria-hidden — every figure in it is written out in the table under it — and pressure is stated on the element as `data-pressure`, so a console can style the whole card from one attribute rather than from a threshold of its own."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/conversation-search.json

@@ -91,10 +91,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/conversation-search",
   "mdUrl": "/docs/components/conversation-search.md",
   "jsonUrl": "/r/components/conversation-search.json",
+  "whenToUse": [
+    "Searching a long transcript, where the hits should be visible on the scroll rail and not only in a list."
+  ],
+  "whenNotToUse": [
+    "Searching across threads rather than inside one."
+  ],
+  "commonMistakes": [
+    "Looking up surrounding text per hit. Each `SearchHit` carries its own, so nothing needs fetching to render the preview.",
+    "Expecting `onStep` to hand you a new index. It is called with -1 or 1 and you wrap the index yourself.",
+    "Re-clamping `activeIndex` when the results narrow. It is already clamped to the current hit set, so narrowing cannot strand it out of range."
+  ],
   "specimens": [
     {
       "title": "ConversationSearch",
@@ -106,6 +117,5 @@
       "note": "Find inside one long thread, with every hit marked down the scrollbar so the shape of the answer is visible before you walk it. Each hit carries its own surrounding text, so the preview needs no lookup back into the transcript — which is what lets a search box render before the thread it is searching has loaded.",
       "interaction": "the counter and the rail agree because `activeIndex` is clamped to the current hit set: narrowing the results cannot strand the marker out of range. Stepping is `-1` and `1`; wrapping is the caller's."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/copy-button.json

@@ -98,10 +98,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/copy-button",
   "mdUrl": "/docs/components/copy-button.md",
   "jsonUrl": "/r/components/copy-button.json",
+  "whenToUse": [
+    "Any value the reader is meant to take elsewhere: an id, a token, a command.",
+    "Anywhere the confirmation must be heard as well as seen — the label lives in an `aria-live` region."
+  ],
+  "whenNotToUse": [
+    "A whole document or a selection. That is the browser's copy, not a button."
+  ],
+  "commonMistakes": [
+    "Replacing the label swap with a toast. At console density a toast for 'copied an id' is heavier than the action itself.",
+    "Confirming on a colour change alone, which is never announced (WCAG 1.4.1).",
+    "Treating a failed copy as success. Both the async clipboard and the fallback can fail, and `onCopyError` is how you find out."
+  ],
   "specimens": [
     {
       "title": "CopyButton",
@@ -113,6 +125,5 @@
       "note": "Copies, then says so for a beat. The confirmation is text, not a colour change.",
       "interaction": "the label swaps to the copied state and reverts after the timeout; the accessible name swaps with it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/cost-meter.json

@@ -64,10 +64,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/cost-meter",
   "mdUrl": "/docs/components/cost-meter.md",
   "jsonUrl": "/r/components/cost-meter.json",
+  "whenToUse": [
+    "Any surface where spend is a fact the user acts on.",
+    "Multi-model runs, where the split is the interesting part."
+  ],
+  "whenNotToUse": [
+    "Context pressure. Use `ContextUsage` — tokens held and money spent are different questions."
+  ],
+  "commonMistakes": [
+    "Showing the run cost with no session total, which removes the only context that makes it mean anything."
+  ],
   "specimens": [
     {
       "title": "CostMeter",
@@ -79,6 +89,5 @@
       "note": "What the run spent, against what the session has spent — two numbers, then the arithmetic under them. Every figure arrives pre-formatted: the element does no currency maths and no rounding, so a bench and a billing page cannot disagree about what `$3.12` means.",
       "interaction": "none. `share` drives the bar and the lines are given largest-first, so the bar reads left to right in the same order as the rows."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/cue-portal-frame.json

@@ -49,7 +49,7 @@
     "--cue-font-sans",
     "--cue-font-scale"
   ],
-  "summary": "Inline version of the portal contract, for portals whose container cannot be chosen (a third-party overlay, or content already portaled by something else).",
+  "summary": "Inline version of the portal contract, for portals whose container you cannot choose.",
   "examples": [
     {
       "title": "Usage",
@@ -57,9 +57,18 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/cue-portal-frame",
   "mdUrl": "/docs/components/cue-portal-frame.md",
   "jsonUrl": "/r/components/cue-portal-frame.json",
-  "todo": true
+  "whenToUse": [
+    "A third-party overlay, or content already portalled by something else, that must still carry the theme, density, font, mode and style stamps."
+  ],
+  "whenNotToUse": [
+    "A portal you control. Prefer the `useCuePortalProps` hook — this exists for the case where you cannot reach the container."
+  ],
+  "commonMistakes": [
+    "Reaching for it first. It is the fallback, not the default, and wrapping in `display: contents` where the hook would do is one more element for nothing.",
+    "Stamping only `data-theme`. The contract is the whole set — theme, density, font, mode, style, skin, fidelity, font scale and overrides — or a portal renders half-themed."
+  ]
 }

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

@@ -76,10 +76,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/data-table-pagination",
   "mdUrl": "/docs/components/data-table-pagination.md",
   "jsonUrl": "/r/components/data-table-pagination.json",
+  "whenToUse": [
+    "Any paged table.",
+    "Tables that get sorted to put the interesting row at one end — first and last exist because stepping there one page at a time is not a navigation strategy."
+  ],
+  "whenNotToUse": [
+    "A table short enough to scroll.",
+    "A non-table list. Use `Pagination`."
+  ],
+  "commonMistakes": [
+    "Rebuilding the buttons as bare glyphs. Every one is an `IconButton` with a real accessible name — an arrow alone announces as nothing."
+  ],
   "specimens": [
     {
       "title": "DataTable recipe",
@@ -92,6 +103,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/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
+  ]
 }