@cueplusplus/ui 0.14.0 → 0.15.0

package/manifest/components/unread-divider.json

@@ -28,9 +28,10 @@
   "tokensUsed": [
     "--cue-accent",
     "--cue-border",
-    "--cue-fg-subtle"
+    "--cue-fg-subtle",
+    "--cue-tracking-caps"
   ],
-  "summary": "The rule that says \"you have read down to here\": an accented line with its label at the end.",
+  "summary": "The rule that says you have read down to here: an accented line with its label at the end.",
   "examples": [
     {
       "title": "Usage",
@@ -38,10 +39,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/unread-divider",
   "mdUrl": "/docs/components/unread-divider.md",
   "jsonUrl": "/r/components/unread-divider.json",
+  "whenToUse": [
+    "Marking where a reader was in a transcript. The caller decides where it goes and when it leaves."
+  ],
+  "whenNotToUse": [
+    "A marker that follows the last-seen message. One that chased it would vanish the moment it appeared, which is why this takes no messages, no counts and no scroll position."
+  ],
+  "commonMistakes": [
+    "Expecting it to move itself or to know anything about scrolling. The row is only ever the mark.",
+    "Writing a sentence into `label`. It defaults to `New` — one word, because the row is a place marker and not an announcement, and the sentence a reader wants is the one below the rule.",
+    "Centring it or neutralising its colour. It is accented and asymmetric so it can never be mistaken for a `TimeBoundary` two rows above it."
+  ],
   "specimens": [
     {
       "title": "UnreadDivider",
@@ -53,6 +65,5 @@
       "note": "The second rule Cursor's row union has and no catalogue ships: where you had read down to. It takes no messages, no count and no scroll position, because the one rule it must obey is that it does not move while you read — a divider that chased the last-seen message would vanish the moment it appeared. Accented and asymmetric, so it can never be mistaken for a time boundary two rows above it.",
       "interaction": "none, deliberately. The mark is the whole component; when it leaves is the caller's decision."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/usage-chart.json

@@ -142,10 +142,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/usage-chart",
   "mdUrl": "/docs/components/usage-chart.md",
   "jsonUrl": "/r/components/usage-chart.json",
+  "whenToUse": [
+    "Usage against a limit, where the ceiling is the reading.",
+    "Anywhere a gap in the data must show as a gap — `gapMs` is what keeps a missing hour from being drawn as a straight line through it."
+  ],
+  "whenNotToUse": [
+    "General charting. Reach for a real chart library when you need axes, legends and several series.",
+    "A value with no ceiling. Half the honesty here comes from the fixed axis."
+  ],
+  "commonMistakes": [
+    "Auto-scaling the y axis, which makes a flat 3% look identical to a flat 95%.",
+    "Adding a charting dependency for this shape. One line and five gridlines is a large price, and a library draws none of the three rules that make this honest."
+  ],
   "specimens": [
     {
       "title": "UsageChart",
@@ -157,6 +169,5 @@
       "note": "A dependency-free SVG chart pinned to 0–100, with gap-aware path segmentation: a hole in the data is a hole in the line, not a straight edge across it.",
       "interaction": "hover draws a crosshair at the nearest point and a tooltip chip; the whole chart carries a text summary for readers who get no hover."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/verdict-row.json

@@ -86,10 +86,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/verdict-row",
   "mdUrl": "/docs/components/verdict-row.md",
   "jsonUrl": "/r/components/verdict-row.json",
+  "whenToUse": [
+    "Any scorer with an answer — a critic model, a test run, a linter. `title` defaults to `Verification` rather than `Critic` precisely so the same row fits all three.",
+    "The problems a scorer thinks are likely, each with how sure it is. Order is the caller's, and most likely first reads best."
+  ],
+  "whenNotToUse": [
+    "A score that does not live on a 0-1 scale. `score` is `0`-`1` and clamped, and a non-finite score is worth no stars."
+  ],
+  "commonMistakes": [
+    "Sanitising the score before passing it. Scores arrive from a model, so `NaN`, `Infinity` and out-of-range values are normal traffic and all of them clamp — the row will not render `NaN out of 5`.",
+    "Restyling the tone from a prop. `data-verdict` carries it, from OpenHands' thresholds (`ok` at 0.6, `warn` at 0.4, `danger` below), and the issue chips take theirs from the probability (`danger` at 0.7, `warn` at 0.5).",
+    "Worrying the stars will be read out one at a time. They are one `role=\"img\"` with the rating as its accessible name."
+  ],
   "specimens": [
     {
       "title": "VerdictRow",
@@ -101,6 +113,5 @@
       "note": "What the run thought of its own work, attached to the turn that did it. A finished turn says what it changed and how long it took; whether it is any good is the question the reader actually has, and every runtime that runs a critic, a test suite or a self-review already has an answer. The scorer is unnamed on purpose — the same row fits a critic model, a linter and a second pair of eyes. The stars are the shape and the percentage is the number, because 0.58 against 0.62 is a decision and rounding it away hides the thing that moved the colour.",
       "interaction": "none, but every number is defended: scores arrive from a model over a network, so NaN, Infinity and out-of-range values all clamp rather than reaching the DOM. The rating is one role=img with `Rated 4 out of 5` as its name, not five glyphs read out one at a time."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/voice-conversation.json

@@ -121,10 +121,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/voice-conversation",
   "mdUrl": "/docs/components/voice-conversation.md",
   "jsonUrl": "/r/components/voice-conversation.json",
+  "whenToUse": [
+    "A live voice session, with `amplitude` fed from the analyser node — only `listening` and `speaking` react to it."
+  ],
+  "whenNotToUse": [
+    "Playback of a finished answer. This is the call itself, with `connecting`, `listening`, `thinking` and `speaking` as its modes."
+  ],
+  "commonMistakes": [
+    "Clamping `amplitude` before passing it. It is 0 to 1 and clamped internally.",
+    "Expecting the orb to interrupt in every mode. It is inert except while the assistant is speaking, so the caption only offers the interrupt when one is possible.",
+    "Driving `muted` from the hardware alone. It marks the mic control as engaged and swaps the hint, and `onToggleMute` reports the press."
+  ],
   "specimens": [
     {
       "title": "VoiceConversation",
@@ -136,6 +147,5 @@
       "note": "A live call as a surface of its own: the orb tracks your voice, the caption names the turn, and the transcript follows underneath. Only `listening` and `speaking` react to amplitude — a connecting or thinking orb pulses on its own, because pretending to track a level nobody is producing is a lie the eye catches. The transcript keeps a minimum height so the card does not grow as the call goes on.",
       "interaction": "the orb is only pressable while the assistant is speaking, and the hint under the caption says so (`Tap to interrupt`) — an inert orb offers nothing rather than looking pressable and doing nothing."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/web-preview.json

@@ -85,10 +85,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/web-preview",
   "mdUrl": "/docs/components/web-preview.md",
   "jsonUrl": "/r/components/web-preview.json",
+  "whenToUse": [
+    "Framing a sandboxed preview an agent produced, with the sandbox origin in the bar so the isolation is legible."
+  ],
+  "whenNotToUse": [
+    "Anything that needs this component to provide isolation. It renders `children` as given and enforces none of its own — the caller passes an already-sandboxed frame."
+  ],
+  "commonMistakes": [
+    "Showing your own host in `origin`. Show the sandbox origin; displaying it does not create the isolation, and the wrong one misstates it.",
+    "Passing inline markup as `children` in production, where the child should be a sandboxed iframe.",
+    "Leaving `loading` true after the sandbox is up, so the frame stays faded behind a shimmering status."
+  ],
   "specimens": [
     {
       "title": "WebPreview",
@@ -100,6 +111,5 @@
       "note": "Chrome around a page the agent opened: origin, reload, open-in-new. It renders whatever you hand it and isolates nothing of its own — an `iframe` here has to arrive already sandboxed, and that is the caller's job, not the element's.",
       "interaction": "reload and open-in-new are named buttons; while `loading` the reload glyph spins, the frame is hidden from assistive tech, and a shimmering label sits in its place."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/web-search.json

@@ -88,10 +88,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/web-search",
   "mdUrl": "/docs/components/web-search.md",
   "jsonUrl": "/r/components/web-search.json",
+  "whenToUse": [
+    "A web search inside a turn, with result cards revealed as they are read."
+  ],
+  "whenNotToUse": [
+    "Scored passages behind a retrieval answer. This shows result cards for a query and ranks nothing."
+  ],
+  "commonMistakes": [
+    "Appending to `results` as they arrive instead of moving `visibleResults`. The array is everything available to reveal.",
+    "Leaving `cycle` constant between searches. It is the identity key that remounts the list so the entrance animation can replay.",
+    "Leaving `searching` true once results have landed, so the shimmering Searching label keeps replacing the result count."
+  ],
   "specimens": [
     {
       "title": "WebSearch",
@@ -103,6 +114,5 @@
       "note": "The query as a pill, then the pages landing under it one at a time as they are read. It is the counterpart to `RetrievalChunks`: the same shape of answer, from outside rather than from the corpus, and the same rule that the caller advances the count.",
       "interaction": "none. `cycle` keys the rows, so a new search re-runs the entrance instead of mutating three lines in place."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/work-collapse.json

@@ -97,7 +97,7 @@
     "--cue-surface-1",
     "--cue-text-ui"
   ],
-  "summary": "A finished run, folded into one row: `Worked for 4m 12s and made 14 tool calls`.",
+  "summary": "A finished run, folded into one row: worked for so long and made so many tool calls.",
   "examples": [
     {
       "title": "Usage",
@@ -105,10 +105,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/work-collapse",
   "mdUrl": "/docs/components/work-collapse.md",
   "jsonUrl": "/r/components/work-collapse.json",
+  "whenToUse": [
+    "Fourteen rows of tool calls and reasoning nobody needs any more, folded to one line — still there, one click away, in their original order.",
+    "A collapsed run that is still going: `running` puts the label in the present tense and runs the sweep, so a folded live run cannot claim to be finished."
+  ],
+  "whenNotToUse": [
+    "Saying what is happening while it happens. That is `TailStatus`, of which this is the counterpart."
+  ],
+  "commonMistakes": [
+    "Wrapping the children in a rail, an indent or a border. The expanded body draws none deliberately: the rows inside already carry their own nesting when they open, and a second level makes a transcript that steps rightwards every time it explains itself.",
+    "Owning `open` inside. It is a prop, so a scripted replay is a caller changing it; a component that owned the disclosure could not be replayed at all.",
+    "Trying to compose a category summary out of `durationMs` and `toolCalls`. Pass `label` instead - `Explored 3 files, ran 5 commands` is a sentence no formatter over a duration and a count could produce."
+  ],
   "specimens": [
     {
       "title": "WorkCollapse",
@@ -120,6 +132,5 @@
       "note": "Fourteen rows of work, folded into the one sentence a reader wants: Worked for 4m 12s and made 14 tool calls. It is the counterpart to TailStatus — that one narrates while it happens, this one is what the narration becomes once nobody needs it — and the open body deliberately draws no rail and no indent, because the rows inside already nest themselves when they open. formatWorkLabel has an answer for every combination including the empty one, since a trigger labelled undefined is a row nobody can decide whether to open.",
       "interaction": "the summary line is the whole trigger and carries aria-expanded. Open it and the calls come back at transcript level, each still its own disclosure; a live run keeps the present tense and sweeps the label instead."
     }
-  ],
-  "todo": true
+  ]
 }