@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScInChatList.md

@@ -0,0 +1,277 @@
+---
+component: ScInChatList
+package: "@streamoid/ui"
+category: chat-agent
+status: stable
+renders: div
+tags: [chat, agent, thinking, reasoning, step, tool, transcript, progress, inchat]
+related: [ScThinkingStepIcon, ScSubAgent, ScInChatMessage, ScTodoList]
+do_not_confuse_with: [ScSubAgent, ScInChatMessage, ScTableList, ScMenuOptions]
+used_by: [agent]
+---
+
+# ScInChatList
+
+**One reasoning step in the agent transcript — not a list.** A leading status glyph,
+a single-line truncating title, an optional expandable description, and an optional
+"Using <tool>…" pill. You render one per step and stack them yourself.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are rendering the agent's thinking/tool steps in a chat
+  transcript, one row per step, each with a pending/working/done/error status.
+- **Don't reach for it when:** you want a user or assistant message bubble
+  (→ `ScInChatMessage`), a standalone "Using X…" delegation pill
+  (→ `ScSubAgent`), the agent's task checklist (→ `ScTodoList`), or just the status
+  glyph on its own (→ `ScThinkingStepIcon`).
+- **Four things that will bite you:**
+  1. Despite the name it renders **one row**. There is no `items` prop.
+  2. `showTool` defaults to **`true`** and `toolUsing` defaults to
+     **`"Using Catalogix..."`** — a bare `<ScInChatList />` ships Catalogix copy.
+  3. `title` defaults to a **marketing sentence**
+     (`"Infrastructure that helps modern brands scale"`).
+  4. It does **not** extend `HTMLAttributes`. Only `className` and `style` get
+     through — no `id`, no `onClick`, no `data-*`, no `aria-*`.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScInChatList } from "@streamoid/ui";
+import type { IcListIconState, DescriptionVisibility } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScInChatList title="Reading the product feed" iconState="working" showTool={false} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `title` | `string` | `"Infrastructure that helps modern brands scale"` | ⚠️ Real, very wrong default. Single line only — `nowrap` + ellipsis at 560px. |
+| `description` | `string` | `"Description"` | ⚠️ Real default. Only rendered when `descriptionVisibility === "visible"`. |
+| `descriptionVisibility` | `"no"` \| `"hidden"` \| `"visible"` | `"no"` | `"no"` = no chevron, no description. `"hidden"` = chevron, collapsed. `"visible"` = chevron, expanded. |
+| `leadingIndicator` | `boolean` | `true` | Renders a `ScThinkingStepIcon` in a fixed 20×26 gutter. `false` removes the gutter entirely (rows lose their left alignment). |
+| `iconState` | `IcListIconState` = `"default"` \| `"working"` \| `"completed"` \| `"error"` | `"default"` | Forwarded straight to `ScThinkingStepIcon`. `"working"` spins. |
+| `showSteps` | `boolean` | `false` | Shows the `stepCount` line above the title. |
+| `stepCount` | `string` | `"Step 01:"` | ⚠️ Real default, hardcoded English. You format the number yourself. |
+| `showTool` | `boolean` | `true` | ⚠️ Defaults **on**. Shows the tool pill under the title. |
+| `toolUsing` | `string` | `"Using Catalogix..."` | ⚠️ Real default. Passing `undefined` falls back to it — gate with `showTool`, don't pass `undefined`. |
+| `onToggle` | `() => void` | – | Fires on a click anywhere in the title row. Only wired when `descriptionVisibility` is `"hidden"` or `"visible"`. |
+| `className` | `string` | – | Appended after the internal class. |
+| `style` | `React.CSSProperties` | – | Applied to the root. |
+
+### What renders in each `descriptionVisibility`
+
+| Region | `"no"` | `"hidden"` | `"visible"` |
+|---|---|---|---|
+| Chevron | — | ▾ `SiconDown` | ▴ `SiconUp` |
+| Title row click | inert (`cursor: default`) | calls `onToggle` | calls `onToggle` |
+| `description` | not rendered | not rendered | rendered with a dot bullet |
+
+### Recipes
+
+```tsx
+// The canonical transcript: you own the array, the component owns one row
+{steps.map((step, i) => (
+  <ScInChatList
+    key={step.id ?? i}
+    title={step.message}
+    iconState={step.status}                    // "default" | "working" | "completed" | "error"
+    showSteps={false}
+    descriptionVisibility={step.description ? "visible" : "no"}
+    description={step.description}
+    showTool={!!step.toolName}                 // gate the pill…
+    toolUsing={`Using ${step.toolName}...`}    // …and format it yourself
+    leadingIndicator
+  />
+))}
+
+// A collapsible step the user can expand
+const [open, setOpen] = useState(false);
+<ScInChatList
+  title="Resolved 412 SKUs against the taxonomy"
+  description={longExplanation}
+  descriptionVisibility={open ? "visible" : "hidden"}
+  onToggle={() => setOpen((v) => !v)}
+  iconState="completed"
+  showTool={false}
+/>
+
+// Numbered steps
+<ScInChatList showSteps stepCount={`Step ${String(i + 1).padStart(2, "0")}:`} title={s.message} showTool={false} />
+
+// The trailing "still working" row while the last step is done
+<ScInChatList title="Planning next steps" iconState="working" descriptionVisibility="no" showTool={false} />
+```
+
+---
+
+## 2. Where to use it
+
+- **The agent chat transcript**, in the reasoning/steps block that sits above the
+  assistant's answer. In the live runtime this is
+  `stream-agent frontend/src/components/chat/AgentSteps.tsx`, which maps the step
+  stream onto one `ScInChatList` per step and interleaves `ScSubAgent` pills and
+  plan cards.
+- Anywhere else you have a **stream of short status lines with per-line state** —
+  a long-running import, a deploy log — as long as one line per row is what you want.
+
+It composes `ScThinkingStepIcon` internally (leading indicator) and nothing else.
+Its tool pill is visually identical to `ScSubAgent`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Each row has **its own lifecycle** (pending → working → completed | error) and you
+  want the spinner/tick/cross to be tokenised and consistent.
+- The row's detail is **secondary** and should be collapsible behind a chevron.
+- The row optionally names a **tool** the agent invoked.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A user or assistant chat bubble | `ScInChatMessage` |
+| A standalone "Using <sub-agent>…" pill with no step row around it | `ScSubAgent` |
+| The agent's editable task checklist (toggle/add/delete) | `ScTodoList` |
+| Just the status glyph, e.g. in your own layout | `ScThinkingStepIcon` |
+| A dashboard data row | `ScTableList` |
+| A dropdown menu of options | `ScMenuOptions` inside `ScPopUpMenu` |
+| A multi-line, wrapping paragraph of agent prose | `ScInChatMessage` — this title is `nowrap` and truncates |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSubAgent` — the bare "Using X…" pill; a step that *is* a delegation | `ScInChatList` is the step row that can *contain* such a pill |
+| `ScTodoList` — a checklist the **user** mutates | This is a read-only step log |
+| A component that takes a list | It takes **one** step; "List" in the name means "list row" |
+
+---
+
+## 4. Why to use it
+
+- **The status vocabulary is already tokenised.** Pending grey, working white spinner,
+  success green, error red all come from `--alias-*` tokens via
+  `ScThinkingStepIcon`, so a transcript reads identically in dark and light mode.
+- **The 20×26 indicator gutter is fixed**, so a stack of rows keeps its titles
+  optically aligned regardless of glyph state — the thing hand-rolled step lists
+  always get wrong when the spinner swaps in.
+- **`prefers-reduced-motion` is honoured** for the working spinner, for free.
+- **Truncation is decided once.** Titles are single-line with an ellipsis at 560px,
+  so a runaway tool message can never reflow the transcript.
+
+---
+
+## Gotchas
+
+**1. It renders one row, not a list.** You map.
+
+```tsx
+// WRONG — there is no items prop; this renders one default row
+<ScInChatList items={steps} />
+
+// RIGHT
+{steps.map((s) => <ScInChatList key={s.id} title={s.message} showTool={false} />)}
+```
+
+**2. The tool pill is on by default, and its default text says "Using Catalogix...".**
+
+```tsx
+// WRONG — renders a "Using Catalogix..." pill under your title
+<ScInChatList title="Fetching orders" />
+
+// RIGHT
+<ScInChatList title="Fetching orders" showTool={false} />
+```
+
+**3. `toolUsing={undefined}` does not hide the pill** — `undefined` triggers the
+default. Gate with `showTool`.
+
+```tsx
+// WRONG — still shows "Using Catalogix..." when toolName is empty
+<ScInChatList title={s.message} toolUsing={s.toolName ? `Using ${s.toolName}...` : undefined} />
+
+// RIGHT
+<ScInChatList
+  title={s.message}
+  showTool={!!s.toolName}
+  toolUsing={s.toolName ? `Using ${s.toolName}...` : undefined}
+/>
+```
+
+**4. `title` and `description` have real content defaults.** Omit `title` and you
+ship `"Infrastructure that helps modern brands scale"`; omit `description` while
+expanded and you ship the literal word `"Description"`.
+
+**5. `description` is dropped unless `descriptionVisibility === "visible"`.**
+`"hidden"` gives you the chevron but no text — that is the collapsed half of the
+pair, and you must flip the prop in `onToggle`. There is no internal state.
+
+**6. The title never wraps.** `.title` is `white-space: nowrap; overflow: hidden;
+text-overflow: ellipsis; max-width: 560px`. Long tool output silently truncates —
+put the long form in `description`, not `title`.
+
+**7. The expander is not keyboard accessible.** The clickable title row is a plain
+`div` with an `onClick` — no `role`, no `tabIndex`, no `aria-expanded`. If you need
+keyboard access to the description, don't hide it behind the chevron.
+
+**8. Only `className` and `style` pass through.** `IScInChatListProps` does **not**
+extend `HTMLAttributes`, unlike most of the library.
+
+```tsx
+// WRONG — type error; none of these reach the DOM
+<ScInChatList title="x" id="step-1" data-testid="step" onClick={select} />
+
+// RIGHT — wrap it
+<div id="step-1" data-testid="step" onClick={select}><ScInChatList title="x" /></div>
+```
+
+**9. `leadingIndicator={false}` removes the gutter, not just the glyph.** The row's
+content shifts 28px left, so mixing indicator-less rows into a stack breaks
+alignment. Use `iconState="default"` (a faint hollow ring) if you want an empty slot.
+
+**10. The root is capped at `max-width: 600px`.** In a wider panel the rows will not
+fill the column; override with `className` if that matters.
+
+---
+
+## In the wild
+
+Rendered by the **agent runtime**, not by any of the four dashboards — the live call
+site is the chat transcript's steps block in the `stream-agent` repo (the copilot
+widget):
+
+```tsx
+// stream-agent  frontend/src/components/chat/AgentSteps.tsx:448
+<ScInChatList
+  title={step.message}
+  iconState={mapIconState(step.status)}
+  showSteps={false}
+  descriptionVisibility={step.description ? 'visible' : 'no'}
+  description={step.description}
+  showTool={!!step.toolName}
+  toolUsing={step.toolName ? `Using ${step.toolName}...` : undefined}
+  leadingIndicator
+/>
+```
+
+---
+
+## Related
+
+- `ScThinkingStepIcon` — the leading glyph; use it alone for a bespoke row layout.
+- `ScSubAgent` — the standalone "Using X…" pill for delegation steps.
+- `ScInChatMessage` — the message bubble the steps block sits above.
+- `ScTodoList` — the interactive checklist, when the user owns the items.

package/dist/docs/ScInChatMessage.md

@@ -0,0 +1,205 @@
+---
+component: ScInChatMessage
+package: "@streamoid/ui"
+category: chat-agent
+status: stable
+renders: div
+tags: [chat, message, bubble, transcript, agent, user, input, output, inchat]
+related: [ScInChatList, ScSubAgent, ScQuickPrompt, ScBriefCard]
+do_not_confuse_with: [ScInChatList, ScInfoPopup, ScBriefCard]
+used_by: [agent]
+---
+
+# ScInChatMessage
+
+**A single chat bubble.** One rounded, padded block of 16/24 text: `type="input"` is
+the user's bubble (raised fill, squared bottom-right corner), `type="output"` is the
+agent's (base surface, 1px divider border, fully rounded).
+
+## TL;DR for agents
+
+- **Reach for it when:** you need the bubble chrome for one turn of a chat transcript.
+- **Don't reach for it when:** you're rendering the agent's reasoning steps
+  (→ `ScInChatList`), a "Using X…" pill (→ `ScSubAgent`), a suggested prompt card
+  (→ `ScQuickPrompt`), or **any markdown / block content** — see Gotcha 1.
+- **Three things that will bite you:**
+  1. Children are rendered **inside a `<p>`**. Block elements (markdown, `<div>`,
+     lists, code blocks) are invalid there and React will warn / the browser will
+     re-parent them.
+  2. `type` defaults to **`"input"`** — the *user* bubble. Agent turns need
+     `type="output"` explicitly.
+  3. No avatar, no timestamp, no author, no markdown, no streaming cursor. It is
+     purely the bubble.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScInChatMessage } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScInChatMessage type="input" text={userMessage} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `type` | `"input"` \| `"output"` | `"input"` | ⚠️ Defaults to the **user** bubble. `input` = raised fill, bottom-right corner squared to 4px. `output` = base surface + divider border, all corners 18px. |
+| `text` | `string` | – | The bubble text. Rendered only when `children` is not supplied. Omit both and you get an empty `<p>` with full padding (a visible empty bubble). |
+| `children` | `ReactNode` | – | Wins over `text` (`children ?? text`). **Goes inside a `<p>`** — inline content only. |
+| `id` | `string` | – | On the root div. Useful for scroll-to-message anchors. |
+| `className` | `string` | – | Appended after the internal classes. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `onClick`, `style`, `data-*`, `aria-*` spread onto the root. |
+
+### Recipes
+
+```tsx
+// The two turns
+<ScInChatMessage type="input"  text={turn.userText} />
+<ScInChatMessage type="output" text={turn.assistantText} />
+
+// Scroll anchor for "jump to this message"
+<ScInChatMessage id={`msg-${turn.id}`} type="input" text={turn.userText} />
+
+// Inline emphasis is fine — it stays inside the <p>
+<ScInChatMessage type="output">
+  Mapped <strong>412</strong> SKUs. <em>3 need review.</em>
+</ScInChatMessage>
+
+// Markdown / block content: use the bubble's tokens, not the bubble
+// (this is what the real runtime does for assistant turns)
+<div className="chat-output-bubble">
+  <ReactMarkdown remarkPlugins={[remarkGfm]}>{md}</ReactMarkdown>
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **The agent chat transcript**, one per turn. In the live runtime
+  (`stream-agent frontend/src/components/chat/MessageBlocks.tsx`) only the
+  **user** turn uses it — assistant turns need markdown, lists and code blocks, so
+  they are rendered with a bespoke container (see Gotcha 1).
+- Attachments/thumbnails for a user turn are rendered **above** it as siblings, not
+  as children.
+- The reasoning steps (`ScInChatList`, `ScSubAgent`) sit between the input bubble and
+  the output block.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You need the exact product bubble geometry and surface tokens for a **plain-text**
+  turn.
+- The content is one paragraph of prose or a short inline-formatted string.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Agent reasoning / tool steps | `ScInChatList` |
+| "Using <sub-agent>…" pill | `ScSubAgent` |
+| Suggested starter prompts | `ScQuickPrompt` |
+| A saved brief / conversation summary card | `ScBriefCard` |
+| Markdown, code blocks, tables, lists | your own container — a `<p>` can't hold them |
+| A hint/help popover in a dashboard | `ScInfoPopup` |
+| A persistent warning strip in a page or sidebar | `CreditWarningBanner` (exported without the `Sc` prefix) |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScInChatList` — a *step* row with a status glyph and tool pill | This is a message bubble with no status |
+| A bubble that renders markdown | This renders a raw string inside a `<p>` |
+| `type` as an author name | It is the surface variant only; there is no author/avatar concept |
+
+---
+
+## 4. Why to use it
+
+- **The asymmetric corner is the product's signature.** `input` squares its
+  bottom-right corner to `--radius-xs` while keeping 18px elsewhere; getting that
+  wrong is the fastest way to make a chat look off-brand.
+- **Both surfaces are token pairs.** `--alias-surface-subtleraised` vs
+  `--alias-surface-base` + `--alias-border-divider` keep the user and agent bubbles
+  distinguishable in light mode, where a hand-rolled "slightly grey" bubble collapses
+  into the page.
+- **`word-break: break-word`** is already set, so pasted URLs and long IDs cannot
+  blow out the transcript width.
+- **`max-width: 600px`** matches every other chat primitive in the family
+  (`ScInChatList`, `ScSelectionList`), so a transcript has one measure.
+
+---
+
+## Gotchas
+
+**1. Children live inside a `<p>`.** The component always renders
+`<p className={styles.text}>{children ?? text}</p>`.
+
+```tsx
+// WRONG — <div>/<ul>/markdown inside <p>: React warns, the DOM re-parents,
+// and your padding/radius end up on the wrong box
+<ScInChatMessage type="output">
+  <ReactMarkdown>{md}</ReactMarkdown>
+</ScInChatMessage>
+
+// RIGHT — plain text through the bubble…
+<ScInChatMessage type="output" text={plainText} />
+
+// …or your own container for block content
+<div className="my-output-bubble"><ReactMarkdown>{md}</ReactMarkdown></div>
+```
+
+**2. `type` defaults to `"input"`.** Forget it on an assistant turn and the agent's
+reply is styled as if the user said it.
+
+**3. `text` has no default.** `<ScInChatMessage />` renders a fully padded, bordered,
+**empty** bubble rather than nothing. Guard on empty content yourself.
+
+**4. `children` silently wins over `text`.** Passing both is not an error; `text` is
+just ignored.
+
+**5. There is no author, avatar, timestamp or "typing" state.** Anything a real
+transcript needs beyond the bubble is your composition problem — put it in sibling
+elements, not children.
+
+**6. Streaming text reflows the whole bubble.** The bubble is `max-width: 600px` with
+no min-height, so a token-by-token stream grows it line by line. If you need a stable
+box during streaming, set a `min-height` via `className`.
+
+**7. The font size is fixed at 16/24.** There is no `size` prop; `className` overrides
+have to target the inner `<p>`, which is a CSS-module class you don't own. Prefer
+wrapping in a container with your own text element if you need a different scale.
+
+---
+
+## In the wild
+
+Rendered by the **agent runtime**, not by any of the four dashboards — the live call
+site is the chat transcript's message block in the `stream-agent` repo (the copilot
+widget):
+
+```tsx
+// stream-agent  frontend/src/components/chat/MessageBlocks.tsx:291
+<ScInChatMessage type="input" text={content} />
+```
+
+---
+
+## Related
+
+- `ScInChatList` — the reasoning-step row that sits between the two bubbles.
+- `ScSubAgent` — the "Using X…" delegation pill.
+- `ScQuickPrompt` — the suggested-prompt card shown in an empty transcript.
+- `ScBriefCard` — a saved-brief card in the chat surface.