@cueplusplus/ui 0.13.0 → 0.14.1

package/manifest/components/color-area.json

@@ -34,7 +34,7 @@
     "--cue-fg",
     "--cue-radius-control"
   ],
-  "summary": "The two-axis colour field — saturation against brightness, by default.",
+  "summary": "The two-axis colour field — saturation against brightness by default.",
   "examples": [
     {
       "title": "Usage",
@@ -42,10 +42,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/color-area",
   "mdUrl": "/docs/components/color-area.md",
   "jsonUrl": "/r/components/color-area.json",
+  "whenToUse": [
+    "Inside a colour picker, for the coarse visual pick."
+  ],
+  "whenNotToUse": [
+    "On its own without a hue control, which leaves two of three dimensions unreachable."
+  ],
+  "commonMistakes": [
+    "Rebuilding the pointer maths. The two hidden range inputs are what make it keyboard- and screen-reader-operable, and they come from the library."
+  ],
   "specimens": [
     {
       "title": "ColorArea",
@@ -57,6 +66,5 @@
       "note": "The two-axis plane. Saturation across, brightness down, with a thumb that reports both.",
       "interaction": "arrow keys move one axis at a time; the thumb keeps a ring in the background colour so it stays visible on any hue."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/color-field.json

@@ -71,10 +71,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/color-field",
   "mdUrl": "/docs/components/color-field.md",
   "jsonUrl": "/r/components/color-field.json",
+  "whenToUse": [
+    "An exact value the user knows or must paste.",
+    "Beside other text controls: it rides the same recessed chassis."
+  ],
+  "whenNotToUse": [
+    "A visual pick. Use `ColorArea` or `ColorPicker`."
+  ],
+  "commonMistakes": [
+    "Parsing the input yourself. Parsing, arrow-key stepping and commit-on-blur are the library's."
+  ],
   "specimens": [
     {
       "title": "ColorField",
@@ -86,6 +96,5 @@
       "note": "The text half of the suite, on the form chassis. Invalid input is rejected rather than silently coerced.",
       "interaction": "same rim and ring as Input; arrow keys step the channel under the caret."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/color-picker.json

@@ -207,7 +207,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A colour, edited in a popover: two-axis area, hue rail, optional alpha rail, a text field that speaks hex *and* oklch, and an eyedropper where the browser has one.",
+  "summary": "A colour, edited in a popover: area, hue rail, optional alpha, a hex/oklch field and an eyedropper where the browser has one.",
   "examples": [
     {
       "title": "Usage",
@@ -215,10 +215,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/color-picker",
   "mdUrl": "/docs/components/color-picker.md",
   "jsonUrl": "/r/components/color-picker.json",
+  "whenToUse": [
+    "Any full colour edit where the user needs both a visual pick and an exact value."
+  ],
+  "whenNotToUse": [
+    "One channel. Use `ColorSlider`.",
+    "A typed value only. Use `ColorField`.",
+    "Showing a colour. Use `ColorSwatch`."
+  ],
+  "commonMistakes": [
+    "Looking for a single primitive to wrap. It is composed from the React Aria colour parts because no primitive owns the combination."
+  ],
   "specimens": [
     {
       "title": "ColorPicker",
@@ -230,6 +241,5 @@
       "note": "Swatch, popover, area, hue slider and a text field, in one control. Reads and writes hex or oklch, so a token authored in oklch survives a round trip unchanged.",
       "interaction": "the swatch is the trigger; inside the popup, the area takes both arrow axes and the slider takes one."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/color-slider.json

@@ -64,10 +64,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/color-slider",
   "mdUrl": "/docs/components/color-slider.md",
   "jsonUrl": "/r/components/color-slider.json",
+  "whenToUse": [
+    "A single channel the user adjusts directly.",
+    "Alpha — it gets the transparency checkerboard, without which 'half transparent' and 'half grey' look identical."
+  ],
+  "whenNotToUse": [
+    "A whole colour. Use `ColorPicker`."
+  ],
+  "commonMistakes": [
+    "Painting the gradient yourself. The library owns it along with the keyboard and pointer behaviour."
+  ],
   "specimens": [
     {
       "title": "ColorSlider",
@@ -79,6 +89,5 @@
       "note": "One channel at a time. The track paints the gradient for the channel it controls.",
       "interaction": "arrow keys step, Home and End jump to the channel bounds; the value is spoken as a colour, not a number."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/color-swatch.json

@@ -59,10 +59,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/color-swatch",
   "mdUrl": "/docs/components/color-swatch.md",
   "jsonUrl": "/r/components/color-swatch.json",
+  "whenToUse": [
+    "Displaying a colour — a legend, a palette row, a token value.",
+    "Anywhere transparency must read as transparency: the frame carries the checkerboard."
+  ],
+  "whenNotToUse": [
+    "Editing. Use `ColorPicker`.",
+    "A chart legend. Use `ChartSwatch`, which pairs the colour with a label."
+  ],
+  "commonMistakes": [
+    "Collapsing it to one element. It is two on purpose: the library writes the colour into inline `background-color`, which paints *behind* a background image, so one element cannot carry both the colour and the checkerboard."
+  ],
   "specimens": [
     {
       "title": "ColorSwatch",
@@ -74,6 +85,5 @@
       "note": "A colour as a readable object: three sizes, a checkerboard behind anything translucent, and a spoken description of the colour.",
       "interaction": "none. A swatch is a readout unless a picker wraps it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/colors-section.json

@@ -54,7 +54,7 @@
     "--cue-text-micro",
     "--cue-text-ui"
   ],
-  "summary": "Section 2 — every colour the active theme declares, one row each.",
+  "summary": "Section 2 of the configurator — every colour the active theme declares, one row each.",
   "examples": [
     {
       "title": "Usage",
@@ -62,9 +62,17 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/colors-section",
   "mdUrl": "/docs/components/colors-section.md",
   "jsonUrl": "/r/components/colors-section.json",
-  "todo": true
+  "whenToUse": [
+    "Inside `ThemeConfigurator`, where the rows are grouped by what each colour does."
+  ],
+  "whenNotToUse": [
+    "As a colour picker of your own. Use `TokenEditor`, which is the stateless, reusable half."
+  ],
+  "commonMistakes": [
+    "Reimplementing the rows. The editing lives in `TokenEditor` precisely so anything else can reuse it."
+  ]
 }

package/manifest/components/combobox.json

@@ -237,7 +237,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A {@link Select } you can type into: one value out of a known, filterable set.",
+  "summary": "A `Select` you can type into: one value out of a known, filterable set.",
   "examples": [
     {
       "title": "Usage",
@@ -245,10 +245,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/combobox",
   "mdUrl": "/docs/components/combobox.md",
   "jsonUrl": "/r/components/combobox.json",
+  "whenToUse": [
+    "A list too long to scroll comfortably — timezones, fixtures, users — where the value must still be one of the list.",
+    "Anywhere `Select` is right in contract but wrong in ergonomics."
+  ],
+  "whenNotToUse": [
+    "A value the user may invent. Use `Autocomplete`; anything not in `items` cannot be chosen here.",
+    "A short list that fits on screen. `Select` costs the user nothing to open and nothing to learn."
+  ],
+  "commonMistakes": [
+    "Treating the typed text as the value. It is a filter; the value is always an item.",
+    "Choosing between this and `Autocomplete` on appearance. They differ in what a value is allowed to be, which is the thing downstream code depends on."
+  ],
   "specimens": [
     {
       "title": "Combobox",
@@ -260,6 +272,5 @@
       "note": "A filtered list with a committed value. An item can be disabled; the empty message is a real string, not a blank popup.",
       "interaction": "arrow keys move the highlight, Enter commits, Escape reverts to the committed value."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/compaction-row.json

@@ -108,10 +108,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/compaction-row",
   "mdUrl": "/docs/components/compaction-row.md",
   "jsonUrl": "/r/components/compaction-row.json",
+  "whenToUse": [
+    "Marking a compaction in a transcript — the text above it is not the text below it any more.",
+    "Anywhere the reader needs to act on it: `128k → 24k tokens · 214 → 31 messages` explains why the model stopped remembering something."
+  ],
+  "whenNotToUse": [
+    "A time gap. Use `TimeBoundary`, which is the same `role=\"separator\"` for a different break."
+  ],
+  "commonMistakes": [
+    "Writing 'compacted' as prose. Alone it tells a reader nothing they can act on — the pair of numbers on both axes is the whole point."
+  ],
   "specimens": [
     {
       "title": "CompactionRow",
@@ -123,6 +133,5 @@
       "note": "A rule like TimeBoundary, because that is what it is: the transcript above it is not the transcript below it any more. What makes it a component is the pair of numbers on both axes — 'compacted' alone tells a reader nothing they can act on, while 128k → 24k tokens · 214 → 31 messages tells them why the model stopped remembering the thing they mentioned an hour ago. Five states, which is two more than most implementations have and exactly the two that matter: failed leaves the window full, and skipped leaves it full on purpose.",
       "interaction": "none. The whole rule is one accessible name, because a separator announces its label and never its children."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/comparison-card.json

@@ -78,10 +78,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/comparison-card",
   "mdUrl": "/docs/components/comparison-card.md",
   "jsonUrl": "/r/components/comparison-card.json",
+  "whenToUse": [
+    "A recommendation the reader may overrule — `recommendedId` names the pick and `reason` argues it."
+  ],
+  "whenNotToUse": [
+    "More than two options. Use a table.",
+    "A choice with no recommendation. Then it is just a comparison."
+  ],
+  "commonMistakes": [
+    "Naming a pick with no reason, which asks for trust instead of offering an argument."
+  ],
   "specimens": [
     {
       "title": "ComparisonCard",
@@ -93,6 +103,5 @@
       "note": "Two options side by side with the pick named, argued, and tinted in the streaming hue — not left for the reader to infer from a longer column. A trait that is `false` collapses to the label in grey with a minus, so the absence lines up with the presences instead of leaving a hole.",
       "interaction": "none. It is a read-only comparison; choosing is `RecommendationCard`'s job, one bench along."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-actions.json

@@ -39,10 +39,19 @@
   ],
   "summary": "One cluster of controls in the toolbar.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-actions",
   "mdUrl": "/docs/components/composer-actions.md",
   "jsonUrl": "/r/components/composer-actions.json",
+  "whenToUse": [
+    "Grouping the controls at one end of the composer toolbar."
+  ],
+  "whenNotToUse": [
+    "A third cluster in the middle. There are two of them, one at each end."
+  ],
+  "commonMistakes": [
+    "Putting every control into one cluster, which collapses the two-ended layout the toolbar is built around."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -60,6 +69,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/composer-attach-button.json

@@ -39,10 +39,19 @@
   ],
   "summary": "The paperclip, as a plus.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-attach-button",
   "mdUrl": "/docs/components/composer-attach-button.md",
   "jsonUrl": "/r/components/composer-attach-button.json",
+  "whenToUse": [
+    "Opening a file picker from the composer toolbar."
+  ],
+  "whenNotToUse": [
+    "An affordance with nothing behind it. With no handler it renders disabled."
+  ],
+  "commonMistakes": [
+    "Rendering it without a handler and expecting it to stay live. It disables itself rather than rendering a control that does nothing."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -60,6 +69,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/composer-attachment-chip.json

@@ -62,10 +62,21 @@
   ],
   "summary": "One attached file as a chip: an icon for its kind, its name and size, and — while it uploads — a progress hairline along the bottom edge.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-attachment-chip",
   "mdUrl": "/docs/components/composer-attachment-chip.md",
   "jsonUrl": "/r/components/composer-attachment-chip.json",
+  "whenToUse": [
+    "Each file attached to a message, including while it is still uploading.",
+    "A failed upload, which says so in its own meta line."
+  ],
+  "whenNotToUse": [
+    "A file the model produced rather than one the person attached."
+  ],
+  "commonMistakes": [
+    "Omitting `onRemove` and expecting a remove button. Without it a finished chip shows a tick instead.",
+    "Drawing your own progress bar. The hairline along the bottom edge is the upload progress."
+  ],
   "specimens": [
     {
       "title": "ComposerAttachments / ComposerAttachmentChip",
@@ -78,6 +89,5 @@
       "note": "The rail above the input, and one chip per file. A chip carries its own state: uploading draws a hairline of progress along its bottom edge, done offers a remove button, and a failure says why in the line that would otherwise hold a size. The icon is the file's kind, not its extension, so an unknown type still lands on something.",
       "interaction": "remove is a labelled icon button (`Remove front-truss.pdf`) and only exists on a finished chip — there is nothing to remove from an upload that has not landed, and a failed one is removed by fixing it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-attachments.json

@@ -39,10 +39,19 @@
   ],
   "summary": "The rail the attachment chips wrap in, above the input.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-attachments",
   "mdUrl": "/docs/components/composer-attachments.md",
   "jsonUrl": "/r/components/composer-attachments.json",
+  "whenToUse": [
+    "Holding the attachment chips above the composer input."
+  ],
+  "whenNotToUse": [
+    "Controls that belong in the toolbar under the input."
+  ],
+  "commonMistakes": [
+    "Laying the chips out with a flex row of your own, which drops the wrapping the rail already provides."
+  ],
   "specimens": [
     {
       "title": "ComposerAttachments / ComposerAttachmentChip",
@@ -55,6 +64,5 @@
       "note": "The rail above the input, and one chip per file. A chip carries its own state: uploading draws a hairline of progress along its bottom edge, done offers a remove button, and a failure says why in the line that would otherwise hold a size. The icon is the file's kind, not its extension, so an unknown type still lands on something.",
       "interaction": "remove is a labelled icon button (`Remove front-truss.pdf`) and only exists on a finished chip — there is nothing to remove from an upload that has not landed, and a failed one is removed by fixing it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-bar.json

@@ -50,10 +50,20 @@
   ],
   "summary": "The bar itself: the paper the input, the attachments and the toolbar sit on.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-bar",
   "mdUrl": "/docs/components/composer-bar.md",
   "jsonUrl": "/r/components/composer-bar.json",
+  "whenToUse": [
+    "Wrapping the input, the attachment rail and the toolbar into one surface.",
+    "Signalling a drop target: `dragActive` tints the bar while a file is over it."
+  ],
+  "whenNotToUse": [
+    "A control meant to sit outside the composer surface."
+  ],
+  "commonMistakes": [
+    "Leaving `dragActive` unwired. The tint is the only feedback a drop target gets before the drop."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -71,6 +81,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/composer-command-item.json

@@ -60,10 +60,21 @@
   ],
   "summary": "A slash command in the menu: its icon, `/name`, what it does, and the return key on the active row.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-command-item",
   "mdUrl": "/docs/components/composer-command-item.md",
   "jsonUrl": "/r/components/composer-command-item.json",
+  "whenToUse": [
+    "Each slash command offered in the composer menu.",
+    "The row Enter would run, which is the one that carries the return key."
+  ],
+  "whenNotToUse": [
+    "An entry that is not a runnable command. `command` takes a `ComposerCommand`."
+  ],
+  "commonMistakes": [
+    "Marking more than one row `active`. It is the row Enter would run, so exactly one carries it.",
+    "Drawing the return key hint yourself. It already appears on the active row."
+  ],
   "specimens": [
     {
       "title": "ComposerMenu / useSlashMatches / useMentionMatches",
@@ -80,6 +91,5 @@
       "note": "One input, two menus, and two hooks that decide which of them has anything to say. `useSlashMatches` answers only while the value starts with a slash; `useMentionMatches` only while the caret is inside a trailing @word — so an empty result is the menu's own instruction to stay shut. `applyMention` writes the choice back into the value, which is the one piece of text editing the family does for you. Type in either field below and the menu above it follows.",
       "interaction": "the menu animates rather than mounting, so the caret never moves under it. A row is a button and takes cue's focus ring; the active one shows the return key it would answer to."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-context.json

@@ -51,10 +51,21 @@
   ],
   "summary": "The context-window dial in the toolbar, with the breakdown on hover or focus.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-context",
   "mdUrl": "/docs/components/composer-context.md",
   "jsonUrl": "/r/components/composer-context.json",
+  "whenToUse": [
+    "Showing how much of the context window has gone, and where, from the composer toolbar.",
+    "A usage readout that has to stay reachable by keyboard, since the breakdown opens on hover or focus."
+  ],
+  "whenNotToUse": [
+    "A generic progress meter. It is shaped around a `ComposerUsage` breakdown."
+  ],
+  "commonMistakes": [
+    "Adding a warning threshold of your own. It turns danger-coloured past 85%, which is the point where the next long tool result starts costing the conversation its own history.",
+    "Treating the dial as decoration and putting the breakdown out of keyboard reach. It opens on hover or focus."
+  ],
   "specimens": [
     {
       "title": "ComposerContext",
@@ -66,6 +77,5 @@
       "note": "The context window as a dial small enough to leave in the toolbar, with the arithmetic behind it on hover or focus. It turns the danger hue past 85% — the point where the next long tool result starts costing the conversation its own history rather than its headroom. Everything is in thousands of tokens and nothing is rounded here: the element divides, the caller counts.",
       "interaction": "the dial is a labelled button (`Context usage`) and the breakdown opens on hover *or* focus-within, so it is reachable from the keyboard without a click target that does nothing."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-input.json

@@ -51,10 +51,19 @@
   ],
   "summary": "The text field.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-input",
   "mdUrl": "/docs/components/composer-input.md",
   "jsonUrl": "/r/components/composer-input.json",
+  "whenToUse": [
+    "The message field of a composer, where Enter submits."
+  ],
+  "whenNotToUse": [
+    "A field inside a multi-step form. Enter here sends the message."
+  ],
+  "commonMistakes": [
+    "Adding your own Enter handler on top of it. Submission is already guarded against IME composition, so accepting a candidate does not send — a hand-rolled handler loses that."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -72,6 +81,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/composer-menu-item.json

@@ -50,10 +50,20 @@
   ],
   "summary": "One row of a `ComposerMenu`, and the chassis the command, person and model rows are built on.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-menu-item",
   "mdUrl": "/docs/components/composer-menu-item.md",
   "jsonUrl": "/r/components/composer-menu-item.json",
+  "whenToUse": [
+    "A row in a `ComposerMenu` that none of the built rows already covers."
+  ],
+  "whenNotToUse": [
+    "A command, a person or a model row, which are already built on this chassis."
+  ],
+  "commonMistakes": [
+    "Using `active` for selection. It says where the keyboard is, not what has been chosen.",
+    "Rebuilding the command, person or model rows from scratch. They are already built on this chassis."
+  ],
   "specimens": [
     {
       "title": "ComposerMenu / useSlashMatches / useMentionMatches",
@@ -70,6 +80,5 @@
       "note": "One input, two menus, and two hooks that decide which of them has anything to say. `useSlashMatches` answers only while the value starts with a slash; `useMentionMatches` only while the caret is inside a trailing @word — so an empty result is the menu's own instruction to stay shut. `applyMention` writes the choice back into the value, which is the one piece of text editing the family does for you. Type in either field below and the menu above it follows.",
       "interaction": "the menu animates rather than mounting, so the caret never moves under it. A row is a button and takes cue's focus ring; the active one shows the return key it would answer to."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-menu.json

@@ -64,10 +64,21 @@
   ],
   "summary": "The popover the slash and mention menus are drawn in, anchored above the bar.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-menu",
   "mdUrl": "/docs/components/composer-menu.md",
   "jsonUrl": "/r/components/composer-menu.json",
+  "whenToUse": [
+    "Drawing the slash or mention menu over the composer.",
+    "Hanging the menu from either edge, with `align`."
+  ],
+  "whenNotToUse": [
+    "A menu that must unmount when closed. Closed is animated out, not unmounted.",
+    "A menu that should hang below the input. It is anchored above the bar."
+  ],
+  "commonMistakes": [
+    "Conditionally rendering it instead of toggling `open`. It animates open rather than mounting, so the caret never moves under it."
+  ],
   "specimens": [
     {
       "title": "ComposerMenu / useSlashMatches / useMentionMatches",
@@ -84,6 +95,5 @@
       "note": "One input, two menus, and two hooks that decide which of them has anything to say. `useSlashMatches` answers only while the value starts with a slash; `useMentionMatches` only while the caret is inside a trailing @word — so an empty result is the menu's own instruction to stay shut. `applyMention` writes the choice back into the value, which is the one piece of text editing the family does for you. Type in either field below and the menu above it follows.",
       "interaction": "the menu animates rather than mounting, so the caret never moves under it. A row is a button and takes cue's focus ring; the active one shows the return key it would answer to."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/composer-model-item.json

@@ -61,10 +61,21 @@
   ],
   "summary": "One model in the menu, with its metadata and a tick on the chosen one.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/composer-model-item",
   "mdUrl": "/docs/components/composer-model-item.md",
   "jsonUrl": "/r/components/composer-model-item.json",
+  "whenToUse": [
+    "Each model offered in the composer's model menu.",
+    "Showing each model's metadata beside its name, rather than in a second column."
+  ],
+  "whenNotToUse": [
+    "A row whose entry is not a `ComposerModel`."
+  ],
+  "commonMistakes": [
+    "Drawing your own tick beside the current model. `selected` draws it.",
+    "Using `selected` as the keyboard cursor. It marks the model in use."
+  ],
   "specimens": [
     {
       "title": "ComposerModelTrigger / ComposerModelItem",
@@ -77,6 +88,5 @@
       "note": "The model as a word in the toolbar rather than a settings page. The trigger shows what is in use and carries `aria-expanded` for the menu it opens; each row shows the model and its one line of metadata, with a tick on the chosen one. Three rows is the point at which this stops being right and `ModelPicker` starts.",
       "interaction": "the trigger is a plain button and the menu is the same `ComposerMenu` the slash and mention lists use — nothing here portals, so an island's values reach it without any carriage."
     }
-  ],
-  "todo": true
+  ]
 }