@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScSelection.md

@@ -0,0 +1,256 @@
+---
+component: ScSelection
+package: "@streamoid/ui"
+category: chat-agent
+status: stable
+renders: div
+tags: [chat, agent, radio, option, choice, single-select, inchat, dynamicform]
+related: [ScRadio, ScSelectionList, ScHDivider, ScCheckbox, ScSelectionPill]
+do_not_confuse_with: [ScSelectionPill, ScSelectionPillGroup, ScSelectionList, ScRadio, ScSelect]
+used_by: [agent]
+---
+
+# ScSelection
+
+**One radio option row in an in-chat form.** A 20px `ScRadio` glyph on the left, a
+title and an optional description on the right, and a rounded fill when active. You
+stack them yourself — there is no group component.
+
+## TL;DR for agents
+
+- **Reach for it when:** the agent asks the user to pick **one** of several labelled
+  options inside the chat transcript (the `radio` field type of the agent's
+  DynamicForm).
+- **Don't reach for it when:** you want the dashboard's segmented tab pills
+  (→ `ScSelectionPill` / `ScSelectionPillGroup`, a **completely different family**),
+  a bare radio glyph (→ `ScRadio`), a dropdown (→ `ScSelect`), multi-select
+  (→ `ScCheckbox` / `ScCheckField`), or the approve/reject suggestion row
+  (→ `ScSelectionList`).
+- **Four things that will bite you:**
+  1. `ScSelection` is **not** the singular of `ScSelectionPill`, and
+     `ScSelectionList` is **not** a list of `ScSelection`. Three unrelated things.
+  2. `title` defaults to `"Title"` and `description` to `"Description"`.
+  3. It is a plain `div` — no `role="radio"`, no `tabIndex`, no keyboard, and the
+     inner `ScRadio` is an SVG, not an `<input>`. Screen readers get nothing.
+  4. `onClick` **and** `onSelect` both fire, in that order.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSelection } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScSelection
+  title="Replace the background"
+  description=""
+  value="replace_bg"
+  active={choice === "replace_bg"}
+  onSelect={setChoice}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `title` | `string` | `"Title"` | ⚠️ Real default. Primary label, `text-primary`, 14/20, wraps (`word-break: break-word`). |
+| `description` | `string` | `"Description"` | ⚠️ Real default. Second line, `text-muted`. **Falsy ⇒ not rendered**, so pass `""` to suppress it. |
+| `active` | `boolean` | `false` | Fills the row with `--alias-fill-neutral-neutral` and switches `ScRadio` to `state="selected"`. |
+| `value` | `string` | – | Echoed back to `onSelect`. Omit and you get `onSelect(undefined)`. |
+| `onSelect` | `(value?: string) => void` | – | Fires **after** `onClick`, with `value`. The handler you normally want. |
+| `onClick` | `MouseEventHandler<HTMLDivElement>` | – | Native click on the row, fires **first**. Both run. |
+| `className` | `string` | – | Appended after the internal classes. |
+| `...props` | `Omit<HTMLAttributes<HTMLDivElement>, "onSelect">` | – | `style`, `id`, `data-*`, `aria-*`, `role`, `tabIndex` spread onto the root. |
+
+### Recipes
+
+```tsx
+// The canonical in-chat radio group: you own the state and the dividers
+<div style={{ display: "flex", flexDirection: "column", gap: 4 }}>
+  {options.map((option, idx) => (
+    <React.Fragment key={option.id}>
+      {idx > 0 && <ScHDivider />}
+      <ScSelection
+        value={option.id}
+        active={selected === option.id}
+        onSelect={(v) => setSelected(v as string)}
+        title={option.label}
+        description={option.description ?? ""}   // "" hides the second line
+      />
+    </React.Fragment>
+  ))}
+</div>
+
+// Title-only rows
+<ScSelection title="Square (1:1)" description="" value="1:1" active={ratio === "1:1"} onSelect={setRatio} />
+
+// Patching in the a11y the component doesn't provide
+<div role="radiogroup" aria-label="Aspect ratio">
+  {ratios.map((r) => (
+    <ScSelection
+      key={r}
+      role="radio"
+      tabIndex={0}
+      aria-checked={ratio === r}
+      onKeyDown={(e) => { if (e.key === " " || e.key === "Enter") { e.preventDefault(); setRatio(r); } }}
+      title={r}
+      description=""
+      value={r}
+      active={ratio === r}
+      onSelect={setRatio}
+    />
+  ))}
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **The agent's in-chat DynamicForm**, `radio` field type — the only real consumer.
+  Live at `stream-agent packages/chat-components/src/DynamicForm.tsx`, which stacks
+  them with a `ScHDivider` between each row.
+- Any **chat-surface** "pick one" prompt where each option needs a sentence of
+  explanation and the row should be tappable end-to-end.
+
+It composes `ScRadio` internally (scaled from its native 24px to 20px by a class
+override). Do not nest your own radio inside it.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The choice happens **inside the chat transcript**, not in a dashboard form.
+- Each option benefits from a **description line** under its label.
+- The whole row should be the hit target, with a filled active state.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Segmented tab/filter pills in a dashboard | `ScSelectionPill` + `ScSelectionPillGroup` |
+| Just the radio glyph, in your own row layout | `ScRadio` |
+| A dropdown of many options | `ScSelect` |
+| Multi-select (more than one active) | `ScCheckbox` / `ScCheckField` |
+| A segmented single-choice **field** in a dashboard form | `ScTabField` |
+| Approving/rejecting an agent's *suggested values* | `ScSelectionList` |
+| Picking media thumbnails | `ScMediaSelect` |
+| A generic titled option card outside chat | `ScDefaultCard` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSelectionPill` / `ScSelectionPillGroup` — dashboard segmented pills, real `<button aria-pressed>` | `ScSelection` is an in-chat row with a radio glyph |
+| `ScSelectionList` — a single approve/reject row for a comma-joined suggestion string | Not a list of `ScSelection`; the names lie |
+| `ScRadio` — the 24px glyph alone, `default`/`selected` | `ScSelection` is the glyph plus the labelled row |
+| `ScSelect` — a real dropdown | Unrelated despite the prefix |
+
+The `ScSelection*` (no "Pill") names belong to the **chat/agent runtime**;
+`ScSelectionPill*` belongs to the **dashboards**. This is the single biggest source
+of wrong picks in the library.
+
+---
+
+## 4. Why to use it
+
+- **The active fill is a token, not a grey.** `--alias-fill-neutral-neutral` keeps the
+  selected row visible in light mode, where a hand-rolled `#1a1a1a` inverts to
+  invisible or to a black slab.
+- **The radio glyph is the product's, not the browser's.** A native
+  `<input type="radio">` cannot be styled to match, and the DS glyph already flips
+  its fill between `text-primary` and `text-muted` per theme.
+- **Optical sizing is handled.** `ScRadio` ships at 24px; this row overrides it to
+  20px and forces the SVG to fill the box, so the glyph lines up with a 14/20 title
+  without magic numbers at your call site.
+- **One hit target.** Padding, radius and the 16px gap between glyph and text match
+  the rest of the in-chat family, so a form built from these components measures
+  correctly against `ScInChatMessage` and `ScSelectionList`.
+
+---
+
+## Gotchas
+
+**1. `title` and `description` have real content defaults.**
+
+```tsx
+// WRONG — renders the literal words "Title" and "Description"
+<ScSelection value="a" active />
+
+// RIGHT
+<ScSelection value="a" active title="Use my brand palette" description="" />
+```
+
+**2. `description=""` is how you hide the second line.** `description` is rendered
+`{description && …}` — falsy is dropped, `undefined` falls back to the default
+`"Description"`. So *omitting* it shows text; passing `""` removes it.
+
+**3. `onClick` and `onSelect` both fire, in that order.** Wiring the same setter to
+both runs it twice.
+
+```tsx
+// WRONG — setChoice called twice per click
+<ScSelection value="a" onClick={() => setChoice("a")} onSelect={setChoice} />
+
+// RIGHT
+<ScSelection value="a" onSelect={setChoice} />
+```
+
+**4. `onSelect` yields `undefined` when `value` is unset.** Always pass `value`.
+
+**5. It is fully controlled.** No internal state — omit `active` and no row ever looks
+selected, and nothing enforces that only one row is active. Exclusivity is your job.
+
+**6. No a11y at all.** The root is a `div` with an `onClick`: no `role`, no
+`tabIndex`, no `aria-checked`, and `ScRadio` renders an SVG rather than an input. It
+is keyboard-inoperable out of the box. Add `role="radio"` / `tabIndex` /
+`aria-checked` / `onKeyDown` yourself (see the third recipe), and wrap the stack in
+`role="radiogroup"`.
+
+**7. There is no `disabled`.** `cursor: pointer` is unconditional. To disable a row
+you must dim and block it yourself via `className` (`opacity` + `pointer-events: none`).
+
+**8. There is no group component.** Unlike `ScSelectionPillGroup`, nothing wires
+exclusivity, dividers or keyboard arrow navigation. Map and manage state yourself.
+
+**9. `width: 100%`** — the row always fills its parent. Constrain the parent, not
+the row.
+
+---
+
+## In the wild
+
+Rendered by the **agent runtime**, not by any of the four dashboards — the live call
+site is the chat DynamicForm's `radio` field in the `stream-agent` repo
+(`@streamoid/chat-components`):
+
+```tsx
+// stream-agent  packages/chat-components/src/DynamicForm.tsx:842
+<ScSelection
+  value={option.id}
+  active={((formValues[field.id] as string) || "") === option.id}
+  onSelect={(v) => handleFieldChange(field.id, v as string)}
+  title={option.label}
+  description={option.description ?? ""}
+/>
+```
+
+---
+
+## Related
+
+- `ScRadio` — the glyph this row composes; use it alone for a custom row.
+- `ScHDivider` — what the runtime puts between stacked rows.
+- `ScSelectionList` — the other in-chat "selection" component: approve/reject, not pick-one.
+- `ScSelectionPill` / `ScSelectionPillGroup` — the unrelated dashboard segmented family.
+- `ScSelect` / `ScCheckbox` / `ScCheckField` — dropdown and multi-select alternatives.

package/dist/docs/ScSelectionList.md

@@ -0,0 +1,272 @@
+---
+component: ScSelectionList
+package: "@streamoid/ui"
+category: chat-agent
+status: stable
+renders: div
+tags: [chat, agent, approve, reject, suggestion, toggle, inchat, review, accept]
+related: [ScSelection, ScInChatList, ScMediaApproval, ScTodoList]
+do_not_confuse_with: [ScSelection, ScSelectionPill, ScSelectionPillGroup, ScTodoList, ScMediaApproval]
+---
+
+# ScSelectionList
+
+**One approve-or-reject row for a suggestion the agent made.** Two 20px circular
+toggles (✓ and ✕) on the left, then a label and the suggested values in a rounded
+pill: `"Suggested Colours: "` + `"Pink, Green, Red, Blue"`. Approving fills the tick;
+rejecting fills the cross red and strikes the text through.
+
+## TL;DR for agents
+
+- **Reach for it when:** the agent proposes a value (or a comma-joined set of values)
+  and the user must accept or decline **that one line**.
+- **Don't reach for it when:** the user picks one of several options
+  (→ `ScSelection`), the suggestion is media (→ `ScMediaApproval` / `ScMediaSelect`),
+  the items are an editable checklist (→ `ScTodoList`), or you want dashboard
+  segmented pills (→ `ScSelectionPill`, unrelated family).
+- **Four things that will bite you:**
+  1. It is **not a list**. One row, one label, one values string. `optionValues` is a
+     `string`, not `string[]` — you join it yourself.
+  2. Both text spans are `white-space: nowrap` with `flex-shrink: 0`, so a long
+     values string **overflows** rather than wrapping.
+  3. Every default is Catalogix demo copy: `label = "Suggested Colours: "`,
+     `optionValues = "Pink, Green, Red, Blue"`.
+  4. Fully controlled and **toggle-aware**: clicking the already-active toggle emits
+     `onChange("default")` — a revoke, not a no-op.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSelectionList } from "@streamoid/ui";
+import type { SelectionListState } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+const [state, setState] = useState<SelectionListState>("default");
+
+<ScSelectionList
+  label="Suggested colours: "
+  optionValues={colours.join(", ")}
+  state={state}
+  onChange={setState}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `state` | `SelectionListState` = `"default"` \| `"approved"` \| `"rejected"` | `"default"` | The whole visual state machine. Controlled — the component keeps no state. |
+| `label` | `string` | `"Suggested Colours: "` | ⚠️ Real default, note the **trailing space** (there is no separator styling — the space is the separator). `nowrap`. |
+| `optionValues` | `string` | `"Pink, Green, Red, Blue"` | ⚠️ Real default. A **single string**, rendered in one pill. Join arrays yourself. `nowrap`. |
+| `onChange` | `(next: SelectionListState) => void` | – | Fires on **every** toggle click with the next state, including the revoke back to `"default"`. This is the handler to drive state with. |
+| `onApprove` | `() => void` | – | Fires **only** on the positive transition into `"approved"` — not on revoke. |
+| `onReject` | `() => void` | – | Fires **only** on the positive transition into `"rejected"` — not on revoke. |
+| `disabled` | `boolean` | `false` | `opacity: 0.5` + `pointer-events: none` on the root, plus `disabled` on both buttons. |
+| `className` | `string` | – | Appended to the root's class list (before the `state-*` class in the attribute — see Gotcha 10 for why that does *not* help you override). |
+| `...props` | `Omit<HTMLAttributes<HTMLDivElement>, "onChange">` | – | `style`, `id`, `data-*`, `aria-*` spread onto the root. |
+
+### What renders in each state
+
+| Region | `default` | `approved` | `rejected` |
+|---|---|---|---|
+| ✓ toggle | outlined, disabled-grey glyph | filled `text-primary`, inverse glyph | outlined, `opacity: 0.3` |
+| ✕ toggle | outlined, disabled-grey glyph | outlined, `opacity: 0.3` | filled `fill-error-solidhover`, inverse glyph |
+| Label + pill | normal | normal | `opacity: 0.5` + `line-through` |
+| ✓ `aria-label` | `"Approve"` | `"Revoke approval"` | `"Approve"` |
+| ✕ `aria-label` | `"Reject"` | `"Reject"` | `"Revoke rejection"` |
+
+### Recipes
+
+```tsx
+// Drive state from onChange, and fire side effects from onApprove/onReject
+<ScSelectionList
+  label="Suggested colours: "
+  optionValues={suggestion.values.join(", ")}
+  state={decisions[suggestion.id] ?? "default"}
+  onChange={(next) => setDecisions((d) => ({ ...d, [suggestion.id]: next }))}
+  onApprove={() => track("suggestion_approved", suggestion.id)}
+  onReject={() => track("suggestion_rejected", suggestion.id)}
+/>
+
+// A stack of suggestions — you own the stack, the component owns one row
+<div style={{ display: "flex", flexDirection: "column", gap: 4 }}>
+  {suggestions.map((s) => (
+    <ScSelectionList
+      key={s.id}
+      label={`${s.attribute}: `}
+      optionValues={s.values.join(", ")}
+      state={decisions[s.id] ?? "default"}
+      onChange={(next) => decide(s.id, next)}
+    />
+  ))}
+</div>
+
+// Locked while the decision is in flight
+<ScSelectionList
+  label="Suggested colours: "
+  optionValues={values.join(", ")}
+  state={state}
+  onChange={setState}
+  disabled={isSubmitting}
+/>
+
+// Long value sets: cap the string yourself — the pill will not wrap
+<ScSelectionList
+  label="Suggested colours: "
+  optionValues={values.slice(0, 4).join(", ") + (values.length > 4 ? ` +${values.length - 4}` : "")}
+  state={state}
+  onChange={setState}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **The agent chat transcript**, under an assistant turn that proposes attribute
+  values, tags, colours or any other short enumerable the user should sign off on —
+  one row per proposal.
+- Alongside `ScInChatList` (the reasoning steps that produced the suggestion) and
+  `ScInChatMessage` (the surrounding prose). It shares their `max-width: 600px`
+  measure, so a mixed stack aligns.
+
+It composes nothing — the ✓ and ✕ are inline SVG paths, not `@streamoid/icons`.
+
+> **Status note:** this component has **no render site anywhere yet** — not in the
+> four dashboards and not in the current agent runtime. It is a built-but-unwired
+> Figma part from the "InChat Default comps" set. Treat the API as unproven.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The unit of decision is **one line of proposed values**, and the two outcomes are
+  accept / decline.
+- The user should be able to **change their mind** — re-clicking the active toggle
+  clears the decision.
+- The rejected state should stay visible (struck through) rather than disappearing.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The user picks **one** of several labelled options | `ScSelection` |
+| The user picks **several** items from a set | `ScCheckbox` / `ScCheckField`, or `ScMediaSelect` for thumbnails |
+| The suggestion is an image or video needing feedback text | `ScMediaApproval` |
+| An editable checklist of tasks | `ScTodoList` |
+| Segmented tabs/filters in a dashboard | `ScSelectionPill` + `ScSelectionPillGroup` |
+| A confirm/cancel pair of real buttons | two `ScButton`s (`variant="mono"` / `variant="error"`) |
+| A whole mapping row with confirm/ignore and a footer | `ScMappingCard` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSelection` — an in-chat **radio option** row (pick one of N) | This is an accept/decline row for **one** suggestion |
+| `ScSelectionPill` / `ScSelectionPillGroup` — dashboard segmented pills | Unrelated family, unrelated surface |
+| A component that takes an array of options | `optionValues` is one `string` in one pill |
+| `ScTodoList` — per-item checkboxes the user toggles | This has no per-value toggles; the whole line is one decision |
+
+---
+
+## 4. Why to use it
+
+- **Real button semantics for the toggles.** Both are `<button type="button">` with
+  `aria-pressed` tracking `state` and an `aria-label` that flips to
+  `"Revoke approval"` / `"Revoke rejection"` — so the revoke affordance is announced,
+  which a pair of clickable divs would never do.
+- **The approved fill is deliberately `text-primary`, not white.** Paired with an
+  `text-and-icons-inverse` glyph, the tick stays legible in **both** themes; a fixed
+  `#fff` circle would vanish on a light background.
+- **Rejected is communicated three ways** — red fill, 50% content opacity, and
+  strikethrough — so the decision survives colour-blindness and greyscale printing.
+- **The revoke transition is already modelled.** `onChange` gets the next state,
+  `onApprove`/`onReject` only fire on the positive edge, so you can wire analytics
+  and mutations without writing the "was it already approved?" branch yourself.
+
+---
+
+## Gotchas
+
+**1. `optionValues` is a `string`, not an array.**
+
+```tsx
+// WRONG — type error, and would render "PinkGreenRed" if it slipped through as any
+<ScSelectionList optionValues={["Pink", "Green", "Red"]} />
+
+// RIGHT
+<ScSelectionList optionValues={["Pink", "Green", "Red"].join(", ")} />
+```
+
+**2. Nothing wraps.** `.label` and `.valuesText` are both `white-space: nowrap`, and
+`.valuesPill` is `flex-shrink: 0`. A long values string overflows the row's 600px
+measure and can push a chat transcript into horizontal scroll. Truncate or summarise
+before passing it (see the fourth recipe).
+
+**3. Every default is demo copy.** Omit `label`/`optionValues` and you ship
+`"Suggested Colours: Pink, Green, Red, Blue"`.
+
+**4. `label` needs its own trailing separator.** There is no gap styling between the
+label text and the pill beyond an 8px flex gap; the default value ends in a space and
+a colon is part of the string. Format the whole label yourself.
+
+**5. Clicking the active toggle revokes.** This is by design but surprising.
+
+```tsx
+// WRONG — assumes onChange only ever moves forward
+onChange={(next) => submitDecision(next)}   // fires submitDecision("default") on revoke
+
+// RIGHT — treat "default" as "cleared"
+onChange={(next) => (next === "default" ? clearDecision() : submitDecision(next))}
+```
+
+**6. `onApprove` / `onReject` never fire on revoke.** If you only wire those two, a
+revoke is silent — you will lose the state change. Always wire `onChange`.
+
+**7. It keeps no state.** Omit `state` and both toggles stay outlined forever no
+matter how many times the user clicks.
+
+**8. `disabled` sets `pointer-events: none` on the root.** Tooltips, `title`
+attributes and hover affordances anywhere inside the row stop working while disabled —
+put any "why is this disabled?" hint on a wrapping element.
+
+**9. There is no per-value interaction.** The values pill is inert text; the user
+cannot drop one colour from the set. If they need to, this is the wrong component
+(→ `ScCheckField` or `ScMediaSelect`).
+
+**10. The state skins are two-class selectors, so a plain `className` loses.** Every
+state rule is written `.scSelectionList.state-rejected …` (specificity 0-2-0); your
+single custom class is 0-1-0 and will not win no matter where it sits in the class
+attribute. Raise your own specificity (`.mine.mine`) or use `style` if you must
+override the state skin.
+
+---
+
+## In the wild
+
+_No host render site found — and none in the agent runtime either._
+
+It belongs in the chat
+transcript beside `ScInChatList` / `ScInChatMessage` in the `stream-agent` repo
+(`@streamoid/chat-components`), most naturally as a new DynamicForm field type for
+"agent proposes values, user signs off" — the sibling of the existing
+`media_approval` field that renders `ScMediaApproval`.
+
+---
+
+## Related
+
+- `ScSelection` — the other in-chat "selection" component: pick one of N options.
+- `ScMediaApproval` — the same accept-with-feedback idea for generated images/video.
+- `ScTodoList` — when the user must edit the items, not just accept them.
+- `ScInChatList` / `ScInChatMessage` — the transcript rows this sits between.