@cueplusplus/ui 0.14.0 → 0.15.0

package/manifest/components/grid.json

@@ -112,10 +112,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/grid",
   "mdUrl": "/docs/components/grid.md",
   "jsonUrl": "/r/components/grid.json",
+  "whenToUse": [
+    "A card grid, a tile wall, any set of peers laid out in both directions.",
+    "Responsive column counts without media queries: give `minItemWidth` and let it fit as many as it can."
+  ],
+  "whenNotToUse": [
+    "A single row or column. Use `Stack`.",
+    "A table. Use the data-table instruments, which carry the semantics a grid of divs cannot."
+  ],
+  "commonMistakes": [
+    "Setting `cols` and `minItemWidth` together and expecting both to apply.",
+    "Hand-picking the gap. It is a rung of the density ladder for the same reason `Stack`'s is — a card grid should tighten with the rest of the console."
+  ],
   "specimens": [
     {
       "title": "Grid",
@@ -127,6 +139,5 @@
       "note": "Fixed columns, or auto-fit from a minimum item width.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/group-bar.json

@@ -102,10 +102,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/group-bar",
   "mdUrl": "/docs/components/group-bar.md",
   "jsonUrl": "/r/components/group-bar.json",
+  "whenToUse": [
+    "A breakdown where the proportions are the reading and exact numbers are not.",
+    "Anywhere a stacked bar should carry no axis — the shape is the answer."
+  ],
+  "whenNotToUse": [
+    "Values that must be compared precisely. Use a table or a labelled chart.",
+    "A single value against a maximum. Use `Progress`."
+  ],
+  "commonMistakes": [
+    "Rendering zero-valued groups. Empty groups get no cell: a minimum width is what makes a two-pixel sliver visible, and a minimum width on a zero draws a group that is not there."
+  ],
   "specimens": [
     {
       "title": "GroupBar",
@@ -117,6 +128,5 @@
       "note": "The distribution strip: one flex cell per item, coloured by tone, with a legend that names each share.",
       "interaction": "none. It is a picture of a breakdown, and the legend is the text version of it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/guardrail-notice.json

@@ -89,10 +89,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/guardrail-notice",
   "mdUrl": "/docs/components/guardrail-notice.md",
   "jsonUrl": "/r/components/guardrail-notice.json",
+  "whenToUse": [
+    "A refusal that should say where the line actually sits and offer the nearest things it can do."
+  ],
+  "whenNotToUse": [
+    "A failure the system could simply try again.",
+    "A refusal with no rule behind it. `policy` is a required short label for the rule that applied."
+  ],
+  "commonMistakes": [
+    "Writing an apology into `title`. It is the refusal in one line, stated plainly rather than apologetically.",
+    "Omitting `alternatives` to hide the section. Pass an empty array; it is a required prop."
+  ],
   "specimens": [
     {
       "title": "GuardrailNotice",
@@ -104,6 +115,5 @@
       "note": "A refusal in its own shape: what it will not do, why, the rule that applied, and the nearest things it *can* do. The alternatives are the whole point — a refusal that ends at 'no' hands the work back with nothing attached, and this one hands back three next moves.",
       "interaction": "each alternative is a button reporting its own text to `onPick`. With an empty list the section disappears rather than leaving an empty rule."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/hover-card.json

@@ -159,9 +159,10 @@
     "--cue-surface-2",
     "--cue-text-emphasis",
     "--cue-text-label",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
-  "summary": "A richer preview than a tooltip, revealed by hovering a link or a name: the fixture behind a profile string, the operator behind an initial.",
+  "summary": "A richer preview than a tooltip, revealed by hovering a link or a name.",
   "examples": [
     {
       "title": "Usage",
@@ -169,10 +170,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/hover-card",
   "mdUrl": "/docs/components/hover-card.md",
   "jsonUrl": "/r/components/hover-card.json",
+  "whenToUse": [
+    "A preview the pointer can travel into — the fixture behind a profile string, the operator behind an initial.",
+    "Content with its own links or controls."
+  ],
+  "whenNotToUse": [
+    "A short description of a control. Use `Tooltip`, which is announced as the trigger's description.",
+    "Anything that must be reachable by keyboard alone. Hover is the trigger."
+  ],
+  "commonMistakes": [
+    "Using it as a big tooltip. It is deliberately not one: the card is reachable and its content is not announced as the trigger's description."
+  ],
   "specimens": [
     {
       "title": "HoverCard",
@@ -184,6 +196,5 @@
       "note": "A preview card: richer than a tooltip, and never the only way to reach the information.",
       "interaction": "opens on hover after a delay and on focus; the card itself is hoverable, so a link inside it is reachable."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/icon-button.json

@@ -86,10 +86,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/icon-button",
   "mdUrl": "/docs/components/icon-button.md",
   "jsonUrl": "/r/components/icon-button.json",
+  "whenToUse": [
+    "A control whose meaning is carried by a familiar glyph in a place with no room for a label: a close, a copy, a kebab menu.",
+    "A dense toolbar where visible rims would be noise. The default `ghost` variant stays invisible until hovered."
+  ],
+  "whenNotToUse": [
+    "An action whose icon is not unambiguous on its own. Use `Button` with `icon` and real text.",
+    "A destructive action that deserves confirmation in place. Use `TwoStepButton`."
+  ],
+  "commonMistakes": [
+    "Treating `aria-label` as optional because the icon 'obviously' means close. It is required, and it is the only name the control has.",
+    "Putting a title or tooltip on the icon instead of labelling the button. The tooltip is a hint; the label is the accessible name.",
+    "Wrapping the icon in extra sizing markup. Pass the component to `icon` and it is rendered `aria-hidden` at the right rung."
+  ],
   "specimens": [
     {
       "title": "IconButton",
@@ -101,6 +114,5 @@
       "note": "A square button with a required accessible name. There is no unlabelled variant.",
       "interaction": "same ring as Button; the hit target stays at the control height even when the glyph shrinks."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/image-generation.json

@@ -53,10 +53,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/image-generation",
   "mdUrl": "/docs/components/image-generation.md",
   "jsonUrl": "/r/components/image-generation.json",
+  "whenToUse": [
+    "An image being generated, where the frame should hold its size before there is anything in it.",
+    "A result that should stay tied to its prompt, which is printed under the frame."
+  ],
+  "whenNotToUse": [
+    "An image that already exists and has no generating phase."
+  ],
+  "commonMistakes": [
+    "Leaving `generating` true after the image lands, which keeps a pulsing dot grid over a finished picture.",
+    "Dropping the prompt. It is shown under the frame, and it is what ties the result back to what was asked."
+  ],
   "specimens": [
     {
       "title": "ImageGeneration",
@@ -68,6 +79,5 @@
       "note": "A dot grid holds the square while the image resolves out of a blur — the frame is the right size from the first frame, so nothing below it moves when the picture lands. While generating, the prompt is replaced by a shimmering label; when it settles, the prompt is what is left under the image.",
       "interaction": "regenerate is a labelled icon button. The grid and the image are both `aria-hidden`: the prompt underneath is the description, and a decorative placeholder should not be announced as a picture."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/info-tip.json

@@ -104,7 +104,7 @@
     "--cue-font-mono",
     "--cue-text-micro"
   ],
-  "summary": "The 13px circular \"i\" badge: a footnote marker for a field, a column or a number whose definition is not obvious.",
+  "summary": "The 13px circular 'i' badge: a footnote marker for a field, a column or a number.",
   "examples": [
     {
       "title": "Usage",
@@ -112,10 +112,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/info-tip",
   "mdUrl": "/docs/components/info-tip.md",
   "jsonUrl": "/r/components/info-tip.json",
+  "whenToUse": [
+    "A definition that is not obvious and does not deserve permanent space.",
+    "Anywhere the explanation must be reachable from the keyboard — it is a real `<button>`."
+  ],
+  "whenNotToUse": [
+    "Text the reader needs. Use `FieldDescription`; a footnote most people never open is the wrong home for a requirement.",
+    "A control's name. Use a label."
+  ],
+  "commonMistakes": [
+    "Rebuilding it as a `<span>` with a hover handler, which puts the explanation out of keyboard reach.",
+    "Filling it with a paragraph. It is a footnote marker, not a panel."
+  ],
   "specimens": [
     {
       "title": "Tooltip / InfoTip",
@@ -128,6 +140,5 @@
       "note": "A tooltip names a control; an InfoTip is the 13px `i` badge that explains one.",
       "interaction": "tooltips open on hover and on keyboard focus, and never on touch; the InfoTip badge is a real button."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/inline-citation.json

@@ -70,10 +70,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/inline-citation",
   "mdUrl": "/docs/components/inline-citation.md",
   "jsonUrl": "/r/components/inline-citation.json",
+  "whenToUse": [
+    "Numbered markers set in a sentence, each previewing the source behind it.",
+    "A preview that carries the source's domain, title and snippet without leaving the sentence."
+  ],
+  "whenNotToUse": [
+    "A standalone source card outside a sentence. These markers live inline."
+  ],
+  "commonMistakes": [
+    "Using `-1` for closed. `openIndex` is `number | null`, and `null` is the closed value.",
+    "Leaving `onOpenIndexChange` off. It is required, because which preview is open is state you hold rather than state the element keeps."
+  ],
   "specimens": [
     {
       "title": "InlineCitation",
@@ -85,6 +96,5 @@
       "note": "The marker inside the sentence, rather than the list under it: a numbered chip the paragraph flows around, and behind each one the page it stands on. `Sources` is the bibliography; this is the footnote, and the two are meant to be read together — the chip says a claim is attributable without spending a clause saying so.",
       "interaction": "each marker is a button, so the preview is reachable from a keyboard as well as a pointer; the open one inverts to the accent fill. The card is the family's one portal, and it carries the island stamp — opened inside an `AgentSurface`, it paints in that island's values rather than the document's."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/input-group.json

@@ -84,7 +84,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A control and its adornments, drawn as a single field.",
+  "summary": "A control and its adornments, drawn as a single field — one rim, one fill, however many affordances.",
   "examples": [
     {
       "title": "Usage",
@@ -92,10 +92,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/input-group",
   "mdUrl": "/docs/components/input-group.md",
   "jsonUrl": "/r/components/input-group.json",
+  "whenToUse": [
+    "A prefix or suffix that belongs to the field: a unit, a currency, a copy button, a scheme.",
+    "Anywhere two controls must read as one: the group owns the chassis and publishes that through context."
+  ],
+  "whenNotToUse": [
+    "Two independent fields. Give them their own rims; a shared one says they are one value.",
+    "A label. Use `FieldLabel`; `leading` is part of the control, not its name."
+  ],
+  "commonMistakes": [
+    "Styling the `Input` inside. It strips its own border, background, height and padding by design and inherits the group's font size — restyling it puts the rim back and breaks the single-field illusion.",
+    "Assuming focus styling comes free. A `<div>` matches neither `:focus` nor `:focus-visible`, which is why the group handles it; do not reimplement it with `:focus-within`."
+  ],
   "specimens": [
     {
       "title": "InputGroup",
@@ -107,6 +119,5 @@
       "note": "One rim around a control and its adornments, so the group focuses as a unit.",
       "interaction": "any focus inside strengthens the whole rim; the ring waits for a keyboard-visible descendant, so a click on an adornment does not light the cluster up. The inner control never rings — the group owns the rim."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/item.json

@@ -135,7 +135,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "One thing in a list, with room for a glyph, a name, a line of detail and a control — the shape a settings entry, a search hit and a device row all want.",
+  "summary": "One thing in a list, with room for a glyph, a name, a line of detail and a control.",
   "examples": [
     {
       "title": "Usage",
@@ -143,10 +143,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/item",
   "mdUrl": "/docs/components/item.md",
   "jsonUrl": "/r/components/item.json",
+  "whenToUse": [
+    "A settings entry, a search hit, a device row — a self-contained object that can stand alone, sit in a `Stack` or fill a `Grid` cell.",
+    "Anything clickable: it renders a real `<button>` when interactive, so keyboard users get it for free."
+  ],
+  "whenNotToUse": [
+    "A line of a hairline table. Use `Row` — that is a row of a grid, this is an object.",
+    "A whole summary surface. Use `Card`."
+  ],
+  "commonMistakes": [
+    "Wrapping a non-interactive `Item` in a `<div onClick>`. Pass `interactive` and let it be a button.",
+    "Putting the control inside `children` instead of `actions`, which loses the reserved slot and the alignment with every other row."
+  ],
   "specimens": [
     {
       "title": "Item",
@@ -158,6 +170,5 @@
       "note": "A media, title, description and actions row. Three variants, plus interactive and disabled.",
       "interaction": "the interactive variant takes a hover ground and a focus ring; it is a button, so Enter and Space activate it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/job-progress.json

@@ -96,10 +96,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/job-progress",
   "mdUrl": "/docs/components/job-progress.md",
   "jsonUrl": "/r/components/job-progress.json",
+  "whenToUse": [
+    "Long work with named stages, where a long install should not read the same as a fast clone.",
+    "Anything a person may need to abandon — `onCancel` is the way out, and it hides once the job finishes."
+  ],
+  "whenNotToUse": [
+    "A wait short enough that stages and an estimate are noise."
+  ],
+  "commonMistakes": [
+    "Giving every stage the same weight, which is exactly what the relative weights exist to avoid.",
+    "Special-casing the finished state. Passing `stages.length` as `stageIndex` marks the job finished, and the bar never runs past its track.",
+    "Passing a duration object to `eta`. It is a pre-formatted estimate, replaced by done once finished."
+  ],
   "specimens": [
     {
       "title": "JobProgress",
@@ -111,6 +123,5 @@
       "note": "Work measured in minutes rather than steps. The stages are weighted, so a six-minute render does not read the same length as a one-second export, and the bar is filled from those weights plus the fraction of the current stage — which is why it never jumps backwards when a short stage ends.",
       "interaction": "cancel is a labelled icon button and disappears once the job finishes: there is nothing left to stop, and a dead X beside a green tick reads as an error."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/kbd.json

@@ -32,10 +32,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/kbd",
   "mdUrl": "/docs/components/kbd.md",
   "jsonUrl": "/r/components/kbd.json",
+  "whenToUse": [
+    "Naming a shortcut in prose, a menu row or an empty state — reference material the reader's eye can skip.",
+    "Anywhere a `Chip` sits on the same row. It is sized off the chip height so the two line up."
+  ],
+  "whenNotToUse": [
+    "A button. This is static markup that renders on the server and has no press behaviour.",
+    "A code fragment or a token name. Use inline code; a key cap says 'press this'."
+  ],
+  "commonMistakes": [
+    "Building a chord out of one `Kbd` containing `⌘ + K`. Emit one per key and put the separator between them, so each cap reads as a key.",
+    "Reaching for it as a small badge. It is set in the micro type step on purpose; `Chip` is the badge."
+  ],
   "specimens": [
     {
       "title": "Kbd",
@@ -47,6 +59,5 @@
       "note": "A key cap, in the mono face. Static markup, so it renders on the server.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/launcher-bubble.json

@@ -110,10 +110,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/launcher-bubble",
   "mdUrl": "/docs/components/launcher-bubble.md",
   "jsonUrl": "/r/components/launcher-bubble.json",
+  "whenToUse": [
+    "An assistant that lives in the corner of a product rather than owning the page: a bubble that opens into a greeting and a few ways in.",
+    "A first run with nothing typed yet — `prompts` exists so the first message does not have to be invented."
+  ],
+  "whenNotToUse": [
+    "A launcher with no starters to offer. `prompts` is required, and an empty panel is the case the component is shaped against.",
+    "A panel whose open state lives inside it. `open` is required and the bubble only reports the press through `onToggle`."
+  ],
+  "commonMistakes": [
+    "Driving `unread` to zero and expecting a `0` badge. It is hidden at zero, and hidden again the whole time the panel is open.",
+    "Wiring the panel's Start a conversation action to `onPick`. That callback fires only for a starter prompt; the empty thread is `onStart`."
+  ],
   "specimens": [
     {
       "title": "LauncherBubble",
@@ -125,6 +137,5 @@
       "note": "The floating entry point and the panel it opens into — the shape an assistant takes on somebody else's site. The badge counts unread and disappears the moment the panel is open, because a count of things you are currently looking at is noise. The starter prompts exist so the first message does not have to be invented by a visitor who has no idea what this thing knows.",
       "interaction": "the bubble carries `aria-expanded` and its label changes with it (`Open the assistant` / `Close the assistant`); the two icons cross-fade in one grid cell so nothing reflows."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/ledger.json

@@ -259,7 +259,8 @@
     "--cue-space-2",
     "--cue-space-3",
     "--cue-text-label",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
   "summary": "Grouped dense rows under sticky tier headings and gutter slugs, with an opt-in disclosure that folds a heading without leaving the outline.",
   "examples": [

package/manifest/components/link.json

@@ -74,10 +74,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/link",
   "mdUrl": "/docs/components/link.md",
   "jsonUrl": "/r/components/link.json",
+  "whenToUse": [
+    "Navigation — somewhere the user can middle-click, copy the address of, or open in a new tab.",
+    "An outbound destination: `external` marks it as leaving."
+  ],
+  "whenNotToUse": [
+    "An action that happens on this page. Use `Button`, or `Button` with `render={<NextLink/>}` when it must look like one but navigate."
+  ],
+  "commonMistakes": [
+    "Using a `Button` with an `onClick` that navigates, which takes away middle-click and copy-address.",
+    "Marking an in-app route `external`, which promises a new context the click does not deliver."
+  ],
   "specimens": [
     {
       "title": "Link",
@@ -89,6 +100,5 @@
       "note": "Two variants. Links do not underline by default; the underline variant offsets by 4px so descenders survive.",
       "interaction": "hover moves the ink to the accent."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/live-region-announcer.json

@@ -67,7 +67,7 @@
   "variants": {},
   "defaultVariants": {},
   "tokensUsed": [],
-  "summary": "One polite region, and a queue that makes it audible.",
+  "summary": "One polite region with a queue behind it, so a run's state changes are actually spoken.",
   "examples": [
     {
       "title": "Usage",
@@ -75,10 +75,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/live-region-announcer",
   "mdUrl": "/docs/components/live-region-announcer.md",
   "jsonUrl": "/r/components/live-region-announcer.json",
+  "whenToUse": [
+    "Any agent console that has to be usable without a screen: it spaces announcements so each is spoken instead of overwritten.",
+    "One per surface, mounted for the life of the transcript — the region is mounted empty and stays mounted, which is the only way a live region is reliably announced."
+  ],
+  "whenNotToUse": [
+    "Alongside a second speaker. Mounting this takes the speech away from `TailStatus` automatically; two live regions read every state out twice, out of step.",
+    "Deciding what to say. The words are the caller's — `ANNOUNCEMENTS` carries the nine transitions the study found announced, and this only queues and speaks them."
+  ],
+  "commonMistakes": [
+    "Trimming `messages` at the head. It is append-only and the announcer remembers how far it has read, so trimmed entries are lost — keep the log growing, or remount with a new `key` for a new run.",
+    "Dropping `spacing` towards zero to keep up. A polite announcement that arrives while another is being spoken replaces it; the `400` default is roughly how long a short phrase takes to speak.",
+    "Expecting a restored session to be read out. `announceOnMount` is `false` by default, and the pause rules hold over it — a backlog handed to a hidden tab waits rather than spending its first line."
+  ],
   "specimens": [
     {
       "title": "LiveRegionAnnouncer",
@@ -90,6 +103,5 @@
       "note": "The element with no visual design at all, and the one that decides whether the rest of this family can be used without a screen. An agent transcript is a stream of state changes, and a live region wired straight to it announces almost none of them: polite announcements replace each other, so a region updated four times a second speaks once and swallows the rest. So it is a queue — 400ms of spacing, five deep with the oldest dropped, held while the page is hidden or a modal has the reader, and an identical sentence re-announced by appending a space, which changes the string without changing a word of it.",
       "interaction": "press the button and nothing visible happens, which is the point — the list below is a mirror of what the region said, drawn only so the bench has something to look at. Press it twice quickly and the second announcement waits its 400ms rather than replacing the first; press it faster than five times and the oldest waiting one is dropped, because five deep behind a busy run the newest is the true one. The second specimen is the composition with TailStatus: that row is a role=status too, so mounting this takes the speaking off it — inspect the row and it carries data-announces=false and no role, which is how a console gets one voice instead of two."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/log-viewer.json

@@ -152,10 +152,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/log-viewer",
   "mdUrl": "/docs/components/log-viewer.md",
   "jsonUrl": "/r/components/log-viewer.json",
+  "whenToUse": [
+    "Streaming output of any length — build logs, run output, a device trace.",
+    "Anywhere the reader needs to follow the tail and still be able to scroll back without being yanked forward."
+  ],
+  "whenNotToUse": [
+    "A handful of static lines. A `<pre>` is simpler and costs nothing.",
+    "Structured records the reader filters and sorts. Use a data table."
+  ],
+  "commonMistakes": [
+    "Rendering the lines yourself. Five thousand DOM rows is a frozen tab, which is why this is virtualised.",
+    "Overriding `rowHeight` to something variable. Rows are fixed at the short control rung so the virtualiser never has to measure, which is also what keeps the scrollbar honest while lines stream in.",
+    "Omitting `height`. It is required because a virtualiser cannot work without a viewport."
+  ],
   "specimens": [
     {
       "title": "LogViewer",
@@ -167,6 +180,5 @@
       "note": "Virtualised rows at the small control height, ANSI decoded to text nodes (never innerHTML), level filter chips, and a stick-to-bottom scroller that offers a `N new lines` pill once you scroll away.",
       "interaction": "the filter chips are toggles; the new-lines pill is a button that returns you to the tail."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/map-answer.json

@@ -77,10 +77,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/map-answer",
   "mdUrl": "/docs/components/map-answer.md",
   "jsonUrl": "/r/components/map-answer.json",
+  "whenToUse": [
+    "A model answer that is a set of places, where the plot and the list beside it must stay in step.",
+    "An ordered itinerary — `route` draws a dashed path through the pins in the order they were given."
+  ],
+  "whenNotToUse": [
+    "A real map. Pins are positioned as percentages precisely so the element needs no tiles, and it knows nothing about geography."
+  ],
+  "commonMistakes": [
+    "Keeping two selections, one for the plot and one for the list. Both surfaces report the same id through `onSelect`, and `activeId` selects in both.",
+    "Expecting `route` to work out an order. It follows the order of `pins`, which is the caller's."
+  ],
   "specimens": [
     {
       "title": "MapAnswer",
@@ -92,6 +103,5 @@
       "note": "A location answer as a plan and a list at once: pins on a ruled ground, the same pins as rows underneath, and one selection driving both. The grid is drawn, not tiled — there is no map provider here, and `x`/`y` are percentages the caller decides.",
       "interaction": "pin and row are both buttons for the same id, and both carry `aria-current`; the pin's own label is what a screen reader gets, since the plan itself is aria-hidden."
     }
-  ],
-  "todo": true
+  ]
 }