@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScThinkingStepIcon.md

@@ -0,0 +1,249 @@
+---
+component: ScThinkingStepIcon
+package: "@streamoid/ui"
+category: chat-agent
+status: stable
+renders: span
+tags: [chat, agent, spinner, status, step, thinking, reasoning, tick, error, glyph, inchat]
+related: [ScInChatList, ScSubAgent, ScProgressBar, ScBeacon, ScTodoList]
+do_not_confuse_with: [ScBeacon, ScProgressBar, ScBadges, ScInChatList]
+---
+
+# ScThinkingStepIcon
+
+**The 12px status glyph for one agent reasoning step.** Four mutually exclusive
+inline-SVG paths in one `<span>`: a hollow ring (not started), a spinning 8-spoke
+asterisk (working), a circled tick in success green (completed), a circled cross in
+error red (error). Stroke colour is the only thing `state` changes.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are laying out your own step/progress row and need the
+  product's pending → working → done → failed glyph.
+- **Don't reach for it when:** you want the whole step row (→ `ScInChatList`, which
+  renders this internally), a determinate progress bar (→ `ScProgressBar`), a live
+  "something changed here" dot (→ `ScBeacon`), or a status label
+  (→ `ScBadges`).
+- **Three things that will bite you:**
+  1. `state="default"` draws the ring in `--alias-border-divider` — **deliberately
+     almost invisible**. It reads as "not started", not as "loading".
+  2. The SVG is `aria-hidden`. The glyph conveys nothing to a screen reader unless
+     you label the wrapper yourself.
+  3. `strokeWidth` is fixed at `1.25` **in viewBox units** (viewBox `13.25`), so the
+     rendered stroke is `1.25 × size / 13.25` px — ~1.1px at the 12px default, ~3px at
+     `size={32}`. You cannot keep a hairline stroke while scaling the glyph up.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScThinkingStepIcon } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScThinkingStepIcon state="working" />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `state` | `"default"` \| `"working"` \| `"completed"` \| `"error"` | `"default"` | Selects both the path and the stroke token. The `IcListIconState` type exported from `ScInChatList` is the same union. |
+| `size` | `number` | `12` | Pixels. Applied to the wrapper `<span>` (`width`/`height`) **and** the `<svg>` width/height. |
+| `className` | `string` | – | Inserted between the base class and the state class. |
+| `style` | `React.CSSProperties` | – | Merged **after** `width`/`height`, so `style={{ width: 20 }}` overrides `size` for the span (but not for the svg). |
+| `...props` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | – | `role`, `aria-label`, `title`, `data-*`, `onClick` spread onto the span. `children` is deliberately excluded. |
+
+### What renders in each state
+
+| `state` | Glyph | Stroke token | Animation |
+|---|---|---|---|
+| `default` | hollow circle, r=6 | `--alias-border-divider` (`#242424`) | — |
+| `working` | 8-spoke asterisk | `--alias-text-and-icons-primary` | `rotate` 360° / 1s linear infinite |
+| `completed` | near-full circle + tick | `--alias-text-and-icons-success` (`#00b96b`) | — |
+| `error` | circle + ✕ | `--alias-text-and-icons-error` (`#d11a1a`) | — |
+
+`.stroke { fill: none }` on every path, and `.glyph { overflow: visible }` so the
+1.25 stroke is never clipped at the viewBox edge.
+
+### Recipes
+
+```tsx
+// Map your own status enum onto the glyph
+const glyphState = (s: StepStatus) =>
+  s === "running" ? "working" : s === "done" ? "completed" : s === "failed" ? "error" : "default";
+
+<ScThinkingStepIcon state={glyphState(step.status)} />
+
+// A bespoke step row (what ScInChatList does internally, in a 20×26 gutter)
+<div style={{ display: "flex", alignItems: "flex-start", gap: 8 }}>
+  <span style={{ display: "flex", alignItems: "center", width: 20, height: 26, flexShrink: 0 }}>
+    <ScThinkingStepIcon state="working" />
+  </span>
+  <p>Resolving the taxonomy…</p>
+</div>
+
+// Announced to assistive tech (the svg is aria-hidden, so label the span)
+<ScThinkingStepIcon state="working" role="img" aria-label="In progress" />
+
+// Larger, for a standalone empty/loading state
+<ScThinkingStepIcon state="working" size={24} />
+```
+
+---
+
+## 2. Where to use it
+
+- **Inside `ScInChatList`**, as its `leadingIndicator` — this is where 100% of current
+  usage comes from. `ScInChatList` renders `<ScThinkingStepIcon state={iconState} />`
+  at the default 12px inside a fixed 20×26 gutter, which is what keeps a stack of step
+  titles optically aligned as the glyph swaps.
+- **Your own step/progress rows** in the chat surface, when `ScInChatList`'s layout
+  (single-line truncating title + tool pill) is not what you want.
+- **Anywhere a four-state indeterminate status glyph** fits: an import queue, a deploy
+  log, a pre-flight checklist.
+
+If you are also going to want a title, a description and a tool pill, stop and use
+`ScInChatList` instead of assembling them.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The status is **indeterminate** (no percentage) and has exactly these four outcomes.
+- The glyph sits next to text that already says what the step is — the icon is
+  reinforcement, not the message.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A whole agent step row (glyph + title + description + tool pill) | `ScInChatList` |
+| A "Using <sub-agent>…" chip | `ScSubAgent` |
+| Determinate progress (a percentage, credits used, upload %) | `ScProgressBar` |
+| A small attention dot / "new here" marker in a dashboard | `ScBeacon` |
+| A textual status chip ("Active", "Failed") | `ScBadges` |
+| A checkbox the user toggles | `ScTodoList` (its own 18px circle) or `ScCheckbox` |
+| A button-level loading state | `ScButton`'s `loading` prop |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScBeacon` — a tonal attention dot with its own tone prop | This is a four-state step glyph with fixed semantics |
+| `ScProgressBar` — determinate, has a value | This is indeterminate; `working` spins forever |
+| `ScInChatList` — the row that already contains this glyph | Rendering both nests two glyphs |
+| `ScTodoList`'s circle — an 18px **interactive** checkbox | This glyph is decorative and inert |
+
+---
+
+## 4. Why to use it
+
+- **Four semantic tokens, one component.** `border-divider` / `text-primary` /
+  `text-and-icons-success` / `text-and-icons-error` mean the glyph matches every other
+  status signal in the product and inverts correctly in light mode — the exact thing a
+  hand-rolled `#00b96b` tick fails at.
+- **`prefers-reduced-motion` is already honoured.** The spin animation is disabled
+  under the media query, so you don't ship a vestibular-trigger spinner.
+- **`transform-box: fill-box` + `transform-origin: center`** on the spinner: the
+  asterisk rotates about its own centre rather than the SVG origin, which is the bug
+  every hand-rolled SVG spinner has.
+- **Optically consistent stroke.** One `1.25` stroke across all four glyphs in a shared
+  `13.25` viewBox means the ring, spinner, tick and cross carry identical visual
+  weight — swapping states doesn't make the row "jump".
+- **It is the same glyph `ScInChatList` uses**, so a bespoke row you build will match
+  the transcript rows next to it exactly.
+
+---
+
+## Gotchas
+
+**1. `default` is nearly invisible, on purpose.** `--alias-border-divider` is the
+faintest token in the palette. If you were reaching for "loading", you want
+`"working"`.
+
+```tsx
+// WRONG — a step that is running looks like a step that hasn't started
+<ScThinkingStepIcon />
+
+// RIGHT
+<ScThinkingStepIcon state="working" />
+```
+
+**2. It announces nothing.** The `<svg>` is `aria-hidden="true"` and the span has no
+role. Screen-reader users get the glyph's meaning only from adjacent text — or from a
+label you add.
+
+```tsx
+// RIGHT — when the glyph is the only signal
+<ScThinkingStepIcon state="error" role="img" aria-label="Step failed" />
+```
+
+**3. The stroke scales with `size`, and you cannot control it.** `strokeWidth="1.25"`
+is in viewBox units, so the rendered stroke is `1.25 × size / 13.25` px: ~1.1px at 12,
+~2.3px at 24, ~3px at 32. There is no `strokeWidth` prop, so a large glyph gets a
+proportionally heavy stroke next to UI drawn at a fixed 1.5px.
+
+**4. `style` can desynchronise the span from the svg.** `style` is merged after
+`width`/`height`, so `style={{ width: 24, height: 24 }}` resizes the box but leaves the
+SVG at `size`. Use `size` to resize; use `style` only for margins/positioning.
+
+```tsx
+// WRONG — 24px box containing a 12px glyph
+<ScThinkingStepIcon state="working" style={{ width: 24, height: 24 }} />
+
+// RIGHT
+<ScThinkingStepIcon state="working" size={24} />
+```
+
+**5. `children` is excluded from the props type.** You cannot nest anything inside it —
+by design, it is a leaf.
+
+**6. The colour is not overridable.** There is no `color` prop and the stroke is set by
+a state class, so `style={{ color: … }}` does nothing (the paths use `stroke`, not
+`currentColor`). To recolour, you must beat `.state-*` in specificity — which means you
+probably want a different component.
+
+**7. `completed` is a circle with a deliberate gap.** The tick path exits the ring at the top
+right, so at very small sizes (`size < 10`) the open arc reads as a broken circle.
+Don't go below the 12px default.
+
+**8. Two spaces creep into the class list** when `className` is omitted
+(`base + " " + "" + " " + state`). Harmless, but exact `className` assertions in
+snapshot tests will see it.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+It is composed **inside `ScInChatList`** rather than called directly:
+
+```tsx
+// @streamoid/ui  packages/ui/src/SC-InChatList/ScInChatList.tsx:49
+<ScThinkingStepIcon state={iconState} />
+```
+
+That row component is itself rendered by the chat runtime
+(`stream-agent frontend/src/components/chat/AgentSteps.tsx:448`). If you need the
+glyph directly, the natural home is a bespoke step/progress row in the same chat
+surface.
+
+---
+
+## Related
+
+- `ScInChatList` — the step row that already renders this glyph; prefer it.
+- `ScSubAgent` — the delegation pill in the same steps stack.
+- `ScProgressBar` — determinate progress with a value.
+- `ScBeacon` — the dashboard-side attention dot.
+- `ScTodoList` — its own 18px interactive check circle, not this glyph.

package/dist/docs/ScTodoList.md

@@ -0,0 +1,288 @@
+---
+component: ScTodoList
+package: "@streamoid/ui"
+category: chat-agent
+status: stable
+renders: div
+tags: [chat, agent, todo, checklist, tasks, plan, dynamicform, add, edit, delete]
+related: [ScCheckField, ScCheckbox, ScThinkingStepIcon, ScInChatList, ScMediaSelect]
+do_not_confuse_with: [ScCheckField, ScCheckbox, ScInChatList, ScTableList, ScMenuOptions]
+used_by: [agent]
+---
+
+# ScTodoList
+
+**The agent's task checklist, editable by the user.** A "`n` of `m` completed" header,
+one row per item (18px circle + text + hover-revealed edit/delete), and an always-on
+"add an item" input with a `+` button. Items are yours; the edit buffer is the
+component's.
+
+## TL;DR for agents
+
+- **Reach for it when:** the agent produced a plan or task list and the user must be
+  able to tick, rename, remove and add items — the `todo_list` field of the agent's
+  in-chat DynamicForm.
+- **Don't reach for it when:** the list is read-only agent progress
+  (→ `ScInChatList`, one row per step), it's a form's multi-select
+  (→ `ScCheckField` / `ScCheckbox`), or it's tabular data (→ `ScTableList`).
+- **Four things that will bite you:**
+  1. The **add row always renders** — even with zero items, even with no `onAdd`
+     handler. There is no way to make the list read-only.
+  2. The per-row **edit/delete buttons are `opacity: 0; pointer-events: none` until
+     `:hover`/`:focus-within`** — unreachable on touch devices.
+  3. `onAdd` receives the **untrimmed** string, even though the empty check is done on
+     the trimmed one.
+  4. `items` is fully controlled but the **edit text is internal state** — the
+     component won't re-render an in-progress edit if you change `items` underneath it.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScTodoList } from "@streamoid/ui";
+import type { IScTodoItem } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScTodoList
+  items={todos}                                   // IScTodoItem[]
+  onToggle={(id) => toggle(id)}
+  onAdd={(content) => add(content.trim())}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `items` | `IScTodoItem[]` | `[]` | Controlled. Rendered in array order — there is no sorting and no drag-reorder. |
+| `onToggle` | `(id: string) => void` | – | Fires on the circle button. You flip `status` yourself. |
+| `onEdit` | `(id: string, content: string) => void` | – | Fires on Enter **or blur** of the inline input. Receives the raw buffer, **not trimmed**. |
+| `onDelete` | `(id: string) => void` | – | Fires on the trash button. No confirmation. |
+| `onAdd` | `(content: string) => void` | – | Fires on Enter in the add input or on the `+` button. Receives the **untrimmed** value. |
+| `addPlaceholder` | `string` | `"Add an item"` | The only overridable string in the component. |
+| `className` | `string` | – | Appended after the internal class. |
+
+`IScTodoItem`
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string` | React key **and** the identity passed to every callback. Must be unique and stable. |
+| `content` | `string` | Row text. Wraps (`word-break: break-word`). |
+| `status` | `"pending"` \| `"completed"` | `"completed"` ⇒ filled circle + tick, muted text, `line-through`. Any other value renders as pending. |
+
+⚠️ `IScTodoListProps` does **not** extend `HTMLAttributes` — no `style`, `id`,
+`data-*`, `aria-*` or `onClick` on the root. Wrap it if you need those.
+
+### What renders when
+
+| Region | Condition |
+|---|---|
+| `"n of m completed"` header | `items.length > 0` only |
+| Row edit/delete buttons | only while the row is `:hover` or `:focus-within`, and only when that row is **not** being edited |
+| Inline edit input | while that row's id is the internal `editingId` |
+| Add row (input + `+`) | **always** |
+| `+` button enabled | only when the trimmed add-input value is non-empty |
+
+### Recipes
+
+```tsx
+// The canonical DynamicForm wiring — the form owns the array
+<ScTodoList
+  items={todoItems.map((i) => ({
+    id: i.id,
+    content: i.content,
+    status: i.status === "completed" ? "completed" : "pending",
+  }))}
+  onToggle={(id) => handleTodoToggle(fieldId, id)}
+  onEdit={(id, content) => handleTodoEdit(fieldId, id, content)}
+  onDelete={(id) => handleTodoDelete(fieldId, id)}
+  onAdd={(content) => handleTodoAdd(fieldId, content)}
+  addPlaceholder="Ask for follow-up changes"
+/>
+
+// Reducer-style state, and trimming at the boundary (the component doesn't)
+const [items, setItems] = useState<IScTodoItem[]>([]);
+<ScTodoList
+  items={items}
+  onToggle={(id) =>
+    setItems((xs) => xs.map((x) => x.id === id
+      ? { ...x, status: x.status === "completed" ? "pending" : "completed" }
+      : x))}
+  onEdit={(id, content) => {
+    const next = content.trim();
+    if (!next) return;                                  // reject empty renames yourself
+    setItems((xs) => xs.map((x) => (x.id === id ? { ...x, content: next } : x)));
+  }}
+  onDelete={(id) => setItems((xs) => xs.filter((x) => x.id !== id))}
+  onAdd={(content) => setItems((xs) => [...xs, { id: crypto.randomUUID(), content: content.trim(), status: "pending" }])}
+/>
+
+// Read-only-ish: you still get the add row, so hide it in CSS.
+// The add row is the LAST CHILD OF THE COMPONENT'S OWN ROOT, so you need two levels:
+// .agentPlan > div > div:last-child { display: none }
+<div className="agentPlan"><ScTodoList items={plan} /></div>
+```
+
+---
+
+## 2. Where to use it
+
+- **The agent's in-chat DynamicForm**, `todo_list` field type — the only real consumer.
+  Live at `stream-agent packages/chat-components/src/DynamicForm.tsx`, where the agent
+  proposes a plan and the user edits it before submitting.
+- **A plan-review step in the chat transcript**, under the reasoning steps
+  (`ScInChatList`) that produced it.
+- Any surface where the **user negotiates a short list with the agent**. It is not a
+  general-purpose dashboard task list: there is no persistence, no assignee, no due
+  date, no reordering, no grouping.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The list is **short** (a handful of items), flat, and fully in view.
+- All four mutations — toggle, rename, delete, add — are things the user should be
+  able to do inline.
+- The completion count is useful feedback on its own.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Read-only agent progress, one row per step, with per-row status glyphs | `ScInChatList` |
+| A labelled group of checkboxes in a form (fixed options) | `ScCheckField` |
+| A single checkbox | `ScCheckbox` |
+| Approving/rejecting one suggested line | `ScSelectionList` |
+| Picking media thumbnails | `ScMediaSelect` |
+| Tabular rows with columns and actions | `ScTableList` |
+| A dropdown of actions | `ScMenuOptions` inside `ScPopUpMenu` |
+| Anything needing reorder, nesting, assignees or due dates | build it — this component has none of that |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScCheckField` — a **form field**: label + fixed checkbox options, no add/delete | This is a mutable list with its own add row |
+| `ScInChatList` — read-only step rows with spinner/tick/cross | This has interactive circles and no "working" state |
+| `ScThinkingStepIcon` — the agent's 12px status glyph | The row circle here is a bespoke 18px **button**, not that glyph |
+| A `<ul>`/`<li>` list | It renders nested `div`s — no list semantics for screen readers |
+
+---
+
+## 4. Why to use it
+
+- **Four mutations, one component, no reflow.** The edit/delete buttons keep their
+  layout space at `opacity: 0` and only fade in on hover, so rows never jump width when
+  the pointer enters — the classic hand-rolled bug.
+- **The edit affordance is already correct**: `autoFocus`, Enter to commit, Escape to
+  cancel, blur to commit. Getting blur-vs-Escape ordering right by hand is fiddly (here
+  `cancelEdit` unmounts the input before blur can fire, so Escape genuinely cancels).
+- **Completion is communicated twice** — muted colour *and* strikethrough — so it
+  survives greyscale and colour-blindness.
+- **The check circle is drawn with tokens** (`--alias-fill-base-base` fill,
+  `--alias-text-and-icons-inverse` tick), so the "filled" circle inverts properly in
+  light mode instead of becoming a white dot on white.
+- **The add input matches the DS field skin** (`fill-neutral-neutralplus` → `neutral`
+  on hover/focus, `border-subtle` → `border-default`), so the list sits correctly inside
+  a form built from `ScTextField`/`ScTextArea`.
+
+---
+
+## Gotchas
+
+**1. You cannot hide the add row.** It renders unconditionally, with no `onAdd` needed.
+An agent-owned, read-only plan will still show an editable input and a `+`.
+
+```tsx
+// WRONG — assumes omitting onAdd removes the affordance
+<ScTodoList items={plan} />          // still renders the input + `+` button
+
+// RIGHT — wrap and suppress it, or don't use this component for read-only lists
+<div className="readOnlyPlan"><ScTodoList items={plan} /></div>
+// .readOnlyPlan > div > div:last-child { display: none }
+//         ^ the wrapper   ^ the component root   ^ .addRow
+// (`.readOnlyPlan > div:last-child` would match the component's own root and hide
+//  the whole list — the add row is one level deeper.)
+```
+
+**2. Row actions are hover-only.** `.actions { opacity: 0; pointer-events: none }`
+until `.row:hover` / `.row:focus-within`. On a touch device there is no hover, so
+**edit and delete are unreachable**. Do not use this component on a mobile surface
+without overriding that rule.
+
+**3. `onAdd` and `onEdit` hand you untrimmed strings.** `commitAdd` guards on
+`newValue.trim().length === 0` but then calls `onAdd?.(newValue)` — the raw value.
+Trim at your boundary or you will store `"  fix colours  "`.
+
+**4. Blur commits an edit.** Clicking anywhere else while editing calls
+`onEdit(id, buffer)` — including with an **empty** buffer, which will blank the item if
+you don't guard. Escape is the only way to cancel.
+
+**5. The edit buffer is internal.** `editingId`/`editValue` are `useState` inside the
+component. If a websocket updates `items` mid-edit, the input keeps the stale buffer and
+the next blur overwrites the fresh content. Pause external updates while `onEdit` is
+pending, or key the whole component on a revision id.
+
+**6. `id` must be stable.** It's the React key and the callback identity. Index-based
+ids will misroute toggles the moment an item is deleted.
+
+**7. No confirmation on delete.** The trash button fires `onDelete` immediately. Add
+your own undo if the items matter.
+
+**8. The header only appears when there is at least one item.** An empty list shows
+just the add row — no "0 of 0 completed". Render your own empty state above it if you
+want copy there.
+
+**9. Hardcoded English.** `"{n} of {m} completed"`, and the aria-labels
+`"Mark as completed"` / `"Mark as pending"` / `"Edit item"` / `"Delete item"` /
+`"Add item"`. Only `addPlaceholder` is overridable. Not usable in a localised surface
+without changing the DS.
+
+**10. No root-level props.** `IScTodoListProps` doesn't extend `HTMLAttributes`, so
+`style`, `id`, `data-testid` and `aria-*` are type errors. Wrap the component.
+
+**11. Not a list element.** Rows are `div`s, not `<li>`, and there is no `role="list"`.
+Screen readers get a run of buttons and spans with no count or position.
+
+---
+
+## In the wild
+
+Rendered by the **agent runtime**, not by any of the four dashboards — the live call
+site is the chat DynamicForm's `todo_list` field in the `stream-agent` repo
+(`@streamoid/chat-components`):
+
+```tsx
+// stream-agent  packages/chat-components/src/DynamicForm.tsx:951
+<ScTodoList
+  items={todoItems.map((i) => ({
+    id: i.id,
+    content: i.content,
+    status: i.status === "completed" ? "completed" : "pending",
+  }))}
+  onToggle={(id) => handleTodoToggle(field.id, id)}
+  onEdit={(id, content) => handleTodoEdit(field.id, id, content)}
+  onDelete={(id) => handleTodoDelete(field.id, id)}
+  onAdd={(content) => handleTodoAdd(field.id, content)}
+  addPlaceholder="Ask for follow-up changes"
+/>
+```
+
+---
+
+## Related
+
+- `ScInChatList` — read-only agent step rows; use it for progress, not tasks.
+- `ScCheckField` / `ScCheckbox` — the form-side checkbox vocabulary.
+- `ScSelectionList` — accept/decline one suggested line instead of editing a list.
+- `ScMediaSelect` — the same "pick from what the agent produced" idea, for media.
+- `ScThinkingStepIcon` — the agent's status glyph, not the row circle used here.