@cueplusplus/ui 0.14.0 → 0.14.1

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/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-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

@@ -113,10 +113,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 +139,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

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