@cueplusplus/ui 0.14.0 → 0.15.0

package/manifest/components/chat-panel.json

@@ -33,10 +33,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/chat-panel",
   "mdUrl": "/docs/components/chat-panel.md",
   "jsonUrl": "/r/components/chat-panel.json",
+  "whenToUse": [
+    "A compact chat surface that needs a transcript and a composer in one frame.",
+    "A transcript where the pause before the first token has a rest state of its own, via `ChatPanelTyping`."
+  ],
+  "whenNotToUse": [
+    "A single message on its own. The panel is the frame around the transcript and the composer, not a message wrapper."
+  ],
+  "commonMistakes": [
+    "Rendering turns directly inside `ChatPanel`. They go in `ChatPanelMessages`.",
+    "Leaving `ChatPanelTyping` mounted once tokens arrive — it stands for the pause before the reply, not the reply."
+  ],
   "specimens": [
     {
       "title": "ChatPanel",
@@ -53,6 +64,5 @@
       "note": "The six parts working together, which is what the whole family is for. The person's turn is a filled bubble on the trailing edge, the model's is plain text on the leading one, and the transcript is bottom-aligned so a short conversation sits on the composer rather than floating.",
       "interaction": "the send control is the only live thing here; use it and the reply is replaced by the three-dot pause, then comes back."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/checkbox-group.json

@@ -41,7 +41,7 @@
     "--cue-sunken",
     "--cue-text-ui"
   ],
-  "summary": "Shared state for a set of {@link Checkbox}es: one `value` array in, one out.",
+  "summary": "Shared state for a set of checkboxes: one `value` array in, one out.",
   "examples": [
     {
       "title": "Usage",
@@ -49,10 +49,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/checkbox-group",
   "mdUrl": "/docs/components/checkbox-group.md",
   "jsonUrl": "/r/components/checkbox-group.json",
+  "whenToUse": [
+    "Any number of options, including none — filters, permissions, capabilities.",
+    "Anywhere the selected set should be read and written as one array rather than N booleans."
+  ],
+  "whenNotToUse": [
+    "Exactly one answer. Use `RadioGroup`.",
+    "A single independent toggle. Use `Checkbox`, or `Switch` for a setting."
+  ],
+  "commonMistakes": [
+    "Leaving it unnamed. A group of checkboxes with no accessible name is a list of unrelated toggles as far as a screen reader is concerned.",
+    "Keeping a separate boolean per option beside the group's array, which gives two sources of truth that drift."
+  ],
   "specimens": [
     {
       "title": "Checkbox / CheckboxGroup",
@@ -65,6 +77,5 @@
       "note": "Two sizes and a real indeterminate state, wired as a parent of its group.",
       "interaction": "Space toggles; the group's parent box drives and reflects its children."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/checkpoint-history.json

@@ -71,10 +71,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/checkpoint-history",
   "mdUrl": "/docs/components/checkpoint-history.md",
   "jsonUrl": "/r/components/checkpoint-history.json",
+  "whenToUse": [
+    "A run with restore points, where the user needs to see what returning to one would give back."
+  ],
+  "whenNotToUse": [
+    "A plain event log with nothing to restore to.",
+    "Choosing between possible futures. These are points already behind the run, listed oldest first."
+  ],
+  "commonMistakes": [
+    "Passing `checkpoints` newest first. They are expected oldest first.",
+    "Leaving `currentId` stale after a restore. Everything after it dims, because restoring would discard it."
+  ],
   "specimens": [
     {
       "title": "CheckpointHistory",
@@ -86,6 +97,5 @@
       "note": "Points the run can be put back to, oldest first, each with what a fallback would cost in files. Everything after the current point dims, because restoring would discard it — the list is the undo stack drawn as a place rather than a count.",
       "interaction": "each row carries a labelled restore button (`Restore to …`), so the control is named even though it draws as a glyph."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/chip.json

@@ -123,6 +123,7 @@
     "--cue-surface-2",
     "--cue-text-label",
     "--cue-text-micro",
+    "--cue-tracking-caps",
     "--cue-warn"
   ],
   "summary": "The status pill, at three volumes: tinted fill, bare outline, or a hairline tag.",

package/manifest/components/clamp.json

@@ -105,10 +105,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/clamp",
   "mdUrl": "/docs/components/clamp.md",
   "jsonUrl": "/r/components/clamp.json",
+  "whenToUse": [
+    "Anything a transcript truncates: command output, a pasted file, a reasoning trace, a quoted message.",
+    "Anywhere the cut must look the same everywhere — the alternative is five slightly different cuts."
+  ],
+  "whenNotToUse": [
+    "Content short enough to show. A fade over nothing is chrome."
+  ],
+  "commonMistakes": [
+    "Painting a gradient of the surface colour over the content instead. The fade is a **mask**, so it needs no idea of what is behind it — the overlay version is the one that hard-codes a colour and breaks in light mode."
+  ],
   "specimens": [
     {
       "title": "Clamp",
@@ -120,6 +130,5 @@
       "note": "The truncation trio as one element: a height, a dissolve of a fixed number of pixels at the cut, and a way back. The fixed depth is the part worth copying — ten pixels of dissolve is the same cut over a two-line row and a forty-line one, which is why the reference's five different truncations read as one idea. The fade is a mask rather than a gradient of the surface colour, which is the bug the reference shipped: its diff variant hard-codes a dark grey and smears on a light theme. A mask fades the content itself, so it has no colour to get wrong in any theme, either mode, or inside the island.",
       "interaction": "the reveal is always present and always focusable; hover and focus decide only how loudly it is drawn, and Show less is never dimmed at all. That is the one place this does not copy the reference, whose Show more chip appears on hover only and is unreachable for anyone not holding a pointer. The height and the fade are published as custom properties on the root, and the mask is written in terms of them, so a height overridden in a stylesheet moves the dissolve with it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/cli-tool-icon.json

@@ -17,10 +17,19 @@
   "tokensUsed": [],
   "summary": "A CLI tool in the registry: a thing that runs in a terminal.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/cli-tool-icon",
   "mdUrl": "/docs/components/cli-tool-icon.md",
   "jsonUrl": "/r/components/cli-tool-icon.json",
+  "whenToUse": [
+    "A catalogue row for something invoked from a shell."
+  ],
+  "whenNotToUse": [
+    "A running service. Use `McpServerIcon`."
+  ],
+  "commonMistakes": [
+    "Using a bare chevron. A chevron is a disclosure everywhere else in this library, and a navigation row that appeared to expand and then navigated instead is a worse failure than a slightly busier glyph at 10px."
+  ],
   "specimens": [
     {
       "title": "The container icon set",
@@ -41,6 +50,5 @@
       "note": "One grid and one weight across all ten, at size-icon-md — the size a navigation row draws them at. Each is a plain <svg> that takes every SVG prop.",
       "interaction": "none. They are decorative by default: aria-hidden, announced by nothing, because the row they mark already carries its name."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/code-block.json

@@ -57,7 +57,8 @@
     "--cue-space-4",
     "--cue-sunken",
     "--cue-text-micro",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
   "summary": "A block of code with a copy button and no highlighter palette; `language=\"jsx\"` adds emphasis in three inks the theme already has.",
   "examples": [

package/manifest/components/code-diff.json

@@ -84,10 +84,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/code-diff",
   "mdUrl": "/docs/components/code-diff.md",
   "jsonUrl": "/r/components/code-diff.json",
+  "whenToUse": [
+    "One file's unified diff inside a transcript, with its path and counts in the header.",
+    "A diff that should replay its entrance animation when the turn changes, by moving `cycle`."
+  ],
+  "whenNotToUse": [
+    "A change spanning many files. This is one file, one `lines` array of context, added and removed.",
+    "A side-by-side comparison. `lines` is a single unified list."
+  ],
+  "commonMistakes": [
+    "Deriving `additions` and `deletions` from `lines` and expecting them to agree. They are separate props and the header prints what you pass.",
+    "Holding `cycle` constant and wondering why the entrance animation never replays. It is an identity key that remounts the body."
+  ],
   "specimens": [
     {
       "title": "CodeDiff",
@@ -99,6 +111,5 @@
       "note": "A unified diff sized for a chat column: added and removed rows carry both a gutter mark and a tint, so the diff survives being read in greyscale. Rows animate in on `cycle`, which is an identity rather than a trigger.",
       "interaction": "none. Scrolls sideways rather than wrapping, because a wrapped diff line is a lie about the file."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/code-runner.json

@@ -104,10 +104,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/code-runner",
   "mdUrl": "/docs/components/code-runner.md",
   "jsonUrl": "/r/components/code-runner.json",
+  "whenToUse": [
+    "Executable code in a transcript, with its output attached to it rather than in a second block.",
+    "A settled run, where `durationMs` prints how long it took."
+  ],
+  "whenNotToUse": [
+    "Code that is only there to be read. The run control is the point of the element."
+  ],
+  "commonMistakes": [
+    "Passing highlighted markup to `code`. It is rendered as plain mono; wrap it yourself for highlighting.",
+    "Using `state=\"idle\"` for a finished run that produced nothing. idle hides the output pane entirely."
+  ],
   "specimens": [
     {
       "title": "CodeRunner",
@@ -119,6 +130,5 @@
       "note": "A snippet with a run button and the output it produced attached underneath, rather than in a console somewhere else. `idle` hides the output pane entirely — an empty black box is not a result — `error` tints what came back in the danger hue, and the duration prints once it settles.",
       "interaction": "the run control is a labelled icon button (`Run this snippet`); while running it spins and the output arrives a line at a time."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/collapsible.json

@@ -103,7 +103,8 @@
     "--cue-space-4",
     "--cue-text-label",
     "--cue-text-micro",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
   "summary": "One section that opens and closes — an accordion of exactly one.",
   "examples": [
@@ -113,10 +114,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/collapsible",
   "mdUrl": "/docs/components/collapsible.md",
   "jsonUrl": "/r/components/collapsible.json",
+  "whenToUse": [
+    "A single section of a page that peers with the sections around it.",
+    "Anywhere it should look identical to a member of an `Accordion`, because it wears the same summary-row skin."
+  ],
+  "whenNotToUse": [
+    "Several sections. Use `Accordion`, which coordinates which are open.",
+    "Advanced fields inside a form. Use `Disclosure` — this is a peer section, that is an annotation on the form."
+  ],
+  "commonMistakes": [
+    "Using it for the 'advanced' idiom. The summary row is the tell: it announces a section where the form wanted a footnote."
+  ],
   "specimens": [
     {
       "title": "Collapsible",
@@ -128,6 +140,5 @@
       "note": "One panel, one trigger, no grouping rules.",
       "interaction": "same height animation as the accordion panel."
     }
-  ],
-  "todo": true
+  ]
 }

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

@@ -52,9 +52,10 @@
     "--cue-space-4",
     "--cue-text-label",
     "--cue-text-micro",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
-  "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 +63,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

@@ -235,9 +235,10 @@
     "--cue-text-body",
     "--cue-text-emphasis",
     "--cue-text-label",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
-  "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 +246,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 +273,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/command-palette.json

@@ -176,7 +176,8 @@
     "--cue-text-emphasis",
     "--cue-text-label",
     "--cue-text-micro",
-    "--cue-text-ui"
+    "--cue-text-ui",
+    "--cue-tracking-caps"
   ],
   "summary": "The keyboard entry point: type, filter, run.",
   "examples": [

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
+  ]
 }