@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScQuickPrompt.md

@@ -0,0 +1,277 @@
+---
+component: ScQuickPrompt
+package: "@streamoid/ui"
+category: chat-agent
+status: stable
+renders: div
+tags: [chat, prompt, suggestion, starter, empty-state, copilot, card, bolt]
+related: [ScAppCardForCopilot, ScBriefCard, ScDefaultCard, ScAskAgentButton, ScInChatMessage]
+do_not_confuse_with: [ScBriefCard, ScDefaultCard, ScAppCardForCopilot, ScAppListingCard]
+used_by: [cxo, photogenix]
+---
+
+# ScQuickPrompt
+
+**A suggested-prompt card for an empty chat.** A bolt tile and a pill with the target
+app's name across the top, then a medium heading and a muted description — the thing
+a user clicks to seed the conversation. Bordered card on the canvas surface.
+
+## TL;DR for agents
+
+- **Reach for it when:** you're building the chat/copilot empty state and want a row
+  or grid of 2–4 clickable starter prompts.
+- **Don't reach for it when:** you want an app tile in the copilot app switcher
+  (→ `ScAppCardForCopilot`), a saved-brief card (→ `ScBriefCard`), a generic titled
+  option card (→ `ScDefaultCard`), or the gradient "Ask CXO" CTA
+  (→ `ScAskAgentButton`).
+- **Three things that will bite you:**
+  1. It has a **hardcoded `width: 15.333125rem`** (245px). In a flex row or grid you
+     must override it (`!w-auto min-w-0 flex-1`) or every card stays 245px wide.
+  2. Every prop has a **real Photogenix default** — omit them and you ship
+     "Photogenix / Swap Model and Background / Replace the current model and…".
+  3. It is **not a button**: a plain `div`, no `cursor: pointer`, no `role`, no
+     `tabIndex`, no keyboard. `onClick` only works because `HTMLAttributes` are spread.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScQuickPrompt } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScQuickPrompt
+  appName="Photogenix"
+  heading="Swap Background"
+  description="Change the background of this image to a minimalist studio"
+  onClick={() => sendPrompt("Change the background of this image to a minimalist studio")}
+  style={{ cursor: "pointer" }}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `appName` | `string` | `"Photogenix"` | ⚠️ Real default. Rendered in the top-right outlined pill, `text-tertiary` 12/18. A trailing space is appended by the component. |
+| `heading` | `string` | `"Swap Model and Background"` | ⚠️ Real default. `text-secondary`, 16/24 medium. Wraps freely — no truncation. |
+| `description` | `string` | `"Replace the current model and background with new ones that match my brand's aesthetic and tone."` | ⚠️ Real default. `text-muted`, 14/20. No line clamp — long strings make the card taller. |
+| `className` | `string` | – | Appended after the internal class. **Always concatenated**, so omitting it puts a literal `undefined` class on the root (harmless, but visible in the DOM). |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `onClick`, `style`, `role`, `tabIndex`, `onKeyDown`, `data-*`, `aria-*` spread onto the root. **This is the only way to make it interactive.** |
+
+There is **no `icon` prop** — the tile always renders `SiconBolt`. There is no
+`prompt`/`value` prop either: the text you send is your own concern, and is usually
+not the same string as `description`.
+
+### Recipes
+
+```tsx
+// A responsive grid of starters (Photogenix's copilot empty state)
+const suggestions = [
+  { heading: "Swap Background", description: "Change the background of this image to a minimalist studio", prompt: "Change the background of this image to a minimalist studio" },
+  { heading: "Generate Video",  description: "Create a cinematic product video with pan-up motion",        prompt: "Create a cinematic product video with pan-up motion" },
+];
+
+<div className="grid grid-cols-1 md:grid-cols-2 gap-3 w-full">
+  {suggestions.map((item, i) => (
+    <ScQuickPrompt
+      key={i}
+      appName="Photogenix"
+      heading={item.heading}
+      description={item.description}
+      onClick={() => onSelect(item.prompt)}
+      style={{ cursor: "pointer" }}
+    />
+  ))}
+</div>
+
+// An equal-width flex row — the fixed 245px width MUST be overridden
+<div style={{ display: "flex", gap: "var(--spacing-8xl)", width: "100%" }}>
+  {prompts.map((p) => (
+    <ScQuickPrompt key={p.id} {...p} className="flex-1 !w-auto min-w-0" />
+  ))}
+</div>
+
+// Keyboard-operable (the component gives you none of this)
+<ScQuickPrompt
+  appName="Catalogix"
+  heading="Map my feed"
+  description="Map the columns of my latest feed to the taxonomy"
+  role="button"
+  tabIndex={0}
+  aria-label="Quick prompt: Map my feed"
+  style={{ cursor: "pointer" }}
+  onClick={send}
+  onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); send(); } }}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **The chat/copilot empty state** — a row or 2×2 grid of starters shown before the
+  first turn. Photogenix renders exactly this in
+  `dashboard/client/src/components/copilot/CopilotSuggestions.tsx`.
+- **The CXO landing/home hero**, as a row of three cards under the composer — the one
+  member of the chat family that genuinely lives in a host dashboard.
+- Any **"what can this app do?"** affordance where the `appName` pill is meaningful
+  because the prompt is routed to a specific product.
+
+Unlike the rest of the `chat-agent` family, this one is host-facing: CXO and
+Photogenix both render it directly.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The card's job is to **send a prompt**, and naming the destination app adds
+  information.
+- You want the heading/description type scale and the bordered canvas card that
+  matches the composer above it.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A tile that **launches an app** from the copilot switcher | `ScAppCardForCopilot` |
+| A tile in the app listing / marketing grid | `ScAppListingCard` / `ScAppCard` / `ScAppCardV3` |
+| A saved brief or previous conversation | `ScBriefCard` |
+| A generic pick-one option card (no app attribution) | `ScDefaultCard` |
+| The gradient "Ask CXO" assistant CTA in a sidebar | `ScAskAgentButton` / `ScAskAgentSlot` |
+| A short filter/segment choice | `ScSelectionPill` |
+| An actual message in the transcript | `ScInChatMessage` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScBriefCard` — a *saved* brief with its own metadata | This is a *suggested* prompt with no persistence |
+| `ScAppCardForCopilot` — app identity + logo, launches the app | This shows a bolt + app *name pill*, and sends text |
+| `ScDefaultCard` — title/description card with no app pill and no fixed width | This one is 245px wide and app-attributed |
+| A component that owns the prompt string | It renders three strings; the prompt you send is separate |
+
+---
+
+## 4. Why to use it
+
+- **The three-level type ramp is pre-set** (12/18 tertiary app pill → 16/24 medium
+  secondary heading → 14/20 muted description). Getting that hierarchy right by hand
+  is the difference between a starter card that scans and one that reads as a wall.
+- **Canvas-on-canvas correctness.** The card sits on `--alias-surface-canvas` with a
+  `--alias-border-divider` hairline, so it stays distinguishable from the page in
+  light mode instead of turning into a white box on white.
+- **Consistent across two products.** CXO home and the Photogenix copilot render the
+  same component, so a change to the starter-card shape lands in both.
+- **The bolt tile is the product's "quick action" mark**, already sized and boxed at
+  8px padding on `--alias-fill-neutral-neutral`.
+
+---
+
+## Gotchas
+
+**1. The width is hardcoded to 245px.** `width: 15.333125rem` on the root.
+
+```tsx
+// WRONG — three 245px cards with a gap, not a full-width row
+<div className="flex gap-4 w-full">
+  {prompts.map((p) => <ScQuickPrompt key={p.id} {...p} />)}
+</div>
+
+// RIGHT — override the width and allow shrinking
+<div className="flex gap-4 w-full">
+  {prompts.map((p) => <ScQuickPrompt key={p.id} {...p} className="flex-1 !w-auto min-w-0" />)}
+</div>
+```
+
+Note the `!` — `className` is appended to the component's own class, but both are single
+class selectors, so specificity ties and the winner is whichever rule comes later in the
+stylesheet. `@streamoid/ui/dist/index.css` is typically imported before your utility CSS,
+but don't rely on that: use `!w-auto` (or `style={{ width: "auto" }}`) so the override is
+unambiguous.
+
+**2. It is not interactive.** No `cursor: pointer`, no `role="button"`, no `tabIndex`,
+no key handling. A card that looks clickable but isn't is the most common bug here.
+
+```tsx
+// WRONG — clickable to a mouse, invisible to a keyboard, no affordance
+<ScQuickPrompt heading="Map my feed" description="…" onClick={send} />
+
+// RIGHT
+<ScQuickPrompt
+  heading="Map my feed" description="…"
+  role="button" tabIndex={0} style={{ cursor: "pointer" }}
+  onClick={send}
+  onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); send(); } }}
+/>
+```
+
+**3. All three text props default to Photogenix demo copy.** Omitting `appName` on a
+Catalogix surface ships the word "Photogenix".
+
+**4. `description` has no clamp.** Cards in a row will have different heights if the
+descriptions differ in length; the row does not equalise them. Cap the string, or set
+`-webkit-line-clamp` via `className`.
+
+**5. There is no icon prop.** `SiconBolt` is hardcoded. If a spec asks for a
+per-prompt icon, this component cannot do it — extend the DS rather than overlaying
+one.
+
+**6. Omitting `className` puts a literal `undefined` class on the root.** The class
+list is built with plain string concatenation (`styles.scQuickPrompt + " " + className`),
+unlike most components which filter falsy values. Cosmetic, but it will show up in
+snapshot tests — pass `className=""` if a test diff matters.
+
+**7. `appName`, `heading` and `description` each render with a trailing space** in the
+JSX (`{appName} `). Harmless for layout, but `toHaveTextContent("Photogenix")` style
+assertions on exact strings need trimming.
+
+**8. The card has no selected/active state.** If a starter should stay highlighted
+after being clicked, you need your own `className` skin.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/landing-content.tsx:380
+<ScQuickPrompt
+  appName="Photogenix"
+  heading="Swap Model and Background"
+  description="Replace the current model and background with new ones that match my brand's aesthetic and tone."
+  className="flex-1 !w-auto min-w-0"
+  style={{
+    color: "var(--alias-text---icons-primary)",
+  }}
+/>
+```
+
+```tsx
+// photogenix_v2  dashboard/client/src/components/copilot/CopilotSuggestions.tsx:24
+<ScQuickPrompt
+  key={i}
+  appName="Photogenix"
+  heading={item.heading}
+  description={item.description}
+  onClick={() => onSelect(item.prompt)}
+  style={{ cursor: 'pointer' }}
+/>
+```
+
+---
+
+## Related
+
+- `ScAppCardForCopilot` — the app-launcher tile in the copilot switcher.
+- `ScBriefCard` — a saved brief/conversation card in the chat surface.
+- `ScDefaultCard` — generic titled option card, no app attribution, no fixed width.
+- `ScAskAgentButton` — the gradient assistant CTA that opens the chat in the first place.
+- `ScInChatMessage` — what the transcript renders once a starter has been sent.

package/dist/docs/ScRadio.md

@@ -0,0 +1,228 @@
+---
+component: ScRadio
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div
+tags: [radio, radio-button, single-select, option, choice, presentational]
+related: [ScPairtext, ScCheckbox, ScTabField, ScSelectionPillGroup, ScSelection]
+do_not_confuse_with: [ScCheckbox, ScPairtext, ScSelection, ScSelectionPill, ScTabField]
+used_by: [catalogix]
+---
+
+# ScRadio
+
+**The bare radio glyph — a 24×24 ring, and a dot when selected.** It is
+**purely presentational**: there is no `checked`, no `onChange`, no `value`, no
+`name`, and no group component. You pass `state` and wire the click yourself.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building a single-choice option list and laying out
+  the rows (label, description, disabled styling) yourself.
+- **Don't reach for it when:** you want a labelled row for free (→ `ScPairtext`
+  with `type="radio"`), a segmented single-choice *field* (→ `ScTabField`), pills
+  (→ `ScSelectionPillGroup`), or the in-chat option list (→ `ScSelection`, agent
+  runtime).
+- **Three things that will bite you:**
+  1. **There is no `onChange` and no `checked`.** Only `state`. Put your `onClick`
+     on the radio or (better) on the whole row.
+  2. **No group.** There is no `ScRadioGroup` — mutual exclusion is entirely yours.
+  3. **No `disabled` prop.** Gate your own handler and dim it with your own class.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScRadio } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScRadio
+  state={mode === "one-time" ? "selected" : "default"}
+  onClick={() => setMode("one-time")}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `state` | `"default"` \| `"selected"` | `"default"` | The **only** state axis. `selected` adds the centre dot and brightens the ring. |
+| `className` | `string` | – | Concatenated between the base and state classes. Also how you resize it (see Gotcha 6). |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `onClick`, `style`, `id`, `role`, `aria-*`, `data-*` spread onto the root div. **`onClick` comes from here — it is not a declared prop.** |
+
+### What renders in each state
+
+| `state` | Ring | Dot | Tokens |
+|---|---|---|---|
+| `default` | muted 1.5px ring | — | `--alias-text-and-icons-muted` |
+| `selected` | bright ring | 6px radius filled circle | `--alias-text-and-icons-primary` (both) |
+
+### Recipes
+
+```tsx
+// The Catalogix idiom: click target is the whole row, radio is decoration
+{OPTIONS.map((o) => (
+  <div
+    key={o.value}
+    style={{ display: "flex", gap: 8, alignItems: "center", cursor: "pointer" }}
+    onClick={() => setValue(o.value)}
+  >
+    <ScRadio state={value === o.value ? "selected" : "default"} />
+    <span>{o.label}</span>
+  </div>
+))}
+
+// "Disabled" option — gate the handler, dim it yourself
+<div className={cx(styles.option, isLocked && styles.disabledOption)}>
+  <ScRadio
+    state={value === "one-time" ? "selected" : "default"}
+    onClick={() => !isLocked && setValue("one-time")}
+  />
+  <span>One Time</span>
+</div>
+
+// Want the label for free instead? Go one level up.
+<ScPairtext type="radio" content="One Time" checked={value === "one-time"}
+            onChange={() => setValue("one-time")} />
+
+// Dense contexts: size it from the outside — the SVG fills the box
+<ScRadio state="selected" style={{ width: 16, height: 16 }} />
+```
+
+---
+
+## 2. Where to use it
+
+- **Catalogix option lists** — `AddNewSyncRule` (One Time / Recurring),
+  `Assets/AddAssets` (upload-mode options), `FeedMapping/SelectHeaderRow` (pick which
+  preview row is the header). Seven call sites, all the same pattern: a row div owns
+  the click, the radio just reflects state.
+- **Inside the DS** — `ScPairtext` (`type="radio"`) and `ScSelection` (the in-chat
+  option row, **agent runtime**) both render one.
+- **Table cells** where one row must be picked (`SelectHeaderRow`).
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The choices are **mutually exclusive** and shown as a vertical list with labels or
+  descriptions you control.
+- You already own the selection state and just need the correct glyph.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Ring **plus** a text label as one click target | `ScPairtext` (`type="radio"`) |
+| A labelled single-choice **field** in a form stack | `ScTabField` (caption + segmented switcher) |
+| 2–5 mutually exclusive views shown as pills | `ScSelectionPillGroup` |
+| A page/panel tab bar | `ScTabs` / `ScTabSwitcher` + `ScTabComp` |
+| Multi-select (more than one active) | `ScCheckbox` / `ScCheckField` |
+| An option row in the **agent chat transcript** | `ScSelection` / `ScSelectionList` (chat runtime) |
+| A real form radio that posts with a `<form>` | native `<input type="radio" name=…>` — this div has no name/value |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScCheckbox` — has `checked` + `onChange` + a `partial` state | `ScRadio` has **none** of those; it is `state`-only |
+| `ScSelection` — the in-chat radio *row* with title + description (**agent runtime**) | `ScRadio` is a host-app glyph |
+| `ScSelectionPill` — segmented tab pill, single-select but a completely different shape | Not a radio |
+| `ScPairtext` — the labelled row that wraps this | This is only the ring |
+
+Note the asymmetry with its sibling: `ScCheckbox` grew `checked`/`onChange`/`disabled`
+props, `ScRadio` did not. Don't assume they share an API.
+
+---
+
+## 4. Why to use it
+
+- **Theme-correct ring and dot.** The two states are one SVG path plus a circle,
+  filled from `--alias-text-and-icons-muted` / `-primary`, so the unselected ring
+  stays visible against both the dark and light surfaces. Hand-drawn `border-radius`
+  radios routinely disappear in light mode.
+- **It scales cleanly.** The CSS forces the SVG to `100%/100%` with `aspect-ratio: 1`,
+  so overriding width/height shrinks the ring *and* the dot proportionally — the
+  literal `width="24"` attributes on the SVG would otherwise spill.
+- **Zero API surface to get wrong.** One prop. The selection logic lives in your
+  reducer where it belongs, and no two call sites can disagree about the glyph.
+
+---
+
+## Gotchas
+
+**1. No `onChange`, no `checked`.** They exist on `ScCheckbox`, not here. `checked`
+is a type error — but **`onChange` compiles and silently never fires**, because
+`HTMLAttributes` declares `onChange` for every div and nothing in `ScRadio` ever
+calls it. Use `state` + `onClick`.
+
+```tsx
+// WRONG — compiles, renders, and does nothing on click
+<ScRadio state="default" onChange={() => setValue("a")} />
+
+// RIGHT
+<ScRadio state={value === "a" ? "selected" : "default"} onClick={() => setValue("a")} />
+```
+
+**2. It is not an `<input type="radio">`.** No `name`, no `value`, no form
+participation, no `role="radio"`, no `aria-checked`, no `tabIndex`, no arrow-key
+roving between options. If the surface needs a11y, add it:
+
+```tsx
+<div role="radiogroup" aria-label="Schedule">
+  <ScRadio role="radio" aria-checked={v === "one-time"} tabIndex={0}
+           state={v === "one-time" ? "selected" : "default"}
+           onClick={() => setV("one-time")} />
+</div>
+```
+
+**3. `cursor: pointer` is always on** — even with no `onClick` and even when your row
+treats the option as locked. The CSS sets it unconditionally, so a "disabled" option
+still looks clickable unless you override the cursor yourself.
+
+**4. No `disabled`.** Guard inside your handler *and* dim with your own class; that's
+what `AddNewSyncRule` does (`!isOneTimeDisabled && …` plus a `disabled-option` class).
+
+**5. Click the label? Nothing happens.** Same trap as `ScCheckbox`: no inner input,
+so `<label>` gives you no free hit area. Put `onClick` on the row wrapper.
+
+**6. Resize from the outside only.** There is no `size` prop (unlike `ScCheckbox`).
+Use `style={{ width, height }}` or a `className` — the SVG will follow.
+
+**7. `className` is string-concatenated.** With `className` unset the DOM class list
+contains a literal `undefined`. Don't assert on the class string in snapshots.
+
+---
+
+## In the wild
+
+```jsx
+// catalogix/dashboard  app/components/AddNewSyncRule/index.jsx:403
+<ScRadio
+  state={syncData.scheduleType === "one-time" ? "selected" : "default"}
+  onClick={() =>
+    !isOneTimeDisabled &&
+    setSyncData({ ...syncData, scheduleType: "one-time" })
+  }
+/>
+```
+
+---
+
+## Related
+
+- `ScPairtext` — label + radio (or checkbox, or icon) as one clickable row.
+- `ScCheckbox` — the multi-select sibling; note its richer API (`checked`, `onChange`, `partial`).
+- `ScTabField` — labelled single-choice field for form stacks.
+- `ScSelectionPillGroup` — segmented single-choice for filters/views.
+- `ScSelection` / `ScSelectionList` — the in-chat option family (**agent runtime**, not dashboards).