@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScBriefCard.md

@@ -0,0 +1,255 @@
+---
+component: ScBriefCard
+package: "@streamoid/ui"
+category: chat-agent
+status: stable
+renders: div
+tags: [card, brief, quick-prompt, suggestion, agent, copilot, chat, gradient-border, glow, active]
+related: [ScAppCardV3, ScQuickPrompt, ScInChatMessage, ScSelection, ScAppCardForCopilot]
+do_not_confuse_with: [ScQuickPrompt, ScAppCardV3, ScDefaultCard, ScAppCardForCopilot]
+used_by: [agent]
+---
+
+# ScBriefCard
+
+**A single suggested-prompt card in the agent's empty chat state.** One centred
+paragraph of text, nothing else — wrapped in the same 1px gradient-border shell as
+`ScAppCardV3`, with the coral corner glow blooming on hover.
+
+**This is a chat/agent-runtime component** (`stream-agent` / `@streamoid/agent`), not
+a host-dashboard one. Its absence from CXO, Photogenix, Catalogix and Artifax is
+expected, not a bug.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building the agent's suggested-prompt / "brief"
+  grid and each card is a single sentence the user can click to send.
+- **Don't reach for it when:** you want the DS's older three-line prompt chip with an
+  app name and a bolt icon (→ `ScQuickPrompt`, which is what **CXO's** landing page
+  uses), a product tile with a name and icon (→ `ScAppCardV3`), or a titled option
+  card in a dashboard (→ `ScDefaultCard`).
+- **Four things that will bite you:**
+  1. **There is only `description`** — no title, no icon, no author, no label. The
+     card is one paragraph.
+  2. `description` defaults to `"Centralized product and asset management for every
+     storefront"` — copy borrowed from the app cards, which makes no sense as a brief.
+  3. `active` sets `--alias-surface-raised`, which is **`#ffffff` in light mode, the
+     same as the default surface** — the active state is invisible in light mode.
+  4. No `role`/`tabIndex`/key handling, but `cursor: pointer` is baked in. The agent's
+     own `QuickPrompt` wrapper adds `role="button" tabIndex={0} aria-label onKeyDown`;
+     copy that.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScBriefCard } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScBriefCard description="Summarise last week's sell-through by category." />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `description` | `string` | `"Centralized product and asset management for every storefront"` | ⚠️ Real default, and it is app-card copy — always set it. `text-xs-regular`, **primary** colour (not tertiary — brighter than `ScAppCardV3`'s description), centred, `word-break: break-word`, no clamp. |
+| `active` | `boolean` | `false` | Swaps the inner background to `--alias-surface-raised`. See Gotcha 3 — a no-op in light mode. |
+| `className` | `string` | – | Applied to the **outer** `.cardBorder` wrapper, not the inner card. |
+| `style` | `CSSProperties` | – | Applied to the outer wrapper. Where you set `width` / `height`. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the outer wrapper (`onClick`, `role`, `tabIndex`, `aria-label`, `onKeyDown`, `data-*`). |
+
+### What the DOM looks like
+
+```
+div.cardBorder            ← className, style, {...props}; the 1px gradient "border"
+└─ div.scBriefCard        ← surface, 20px padding, overflow:clip, height:100%, centred
+   ├─ div.glow            ← decorative, pointer-events:none
+   ├─ div.glowHover       ← coral radial bloom, opacity 0 → 1 on wrapper :hover
+   └─ div.body → p.description
+```
+
+Identical shell to `ScAppCardV3`; only the body differs (centred single paragraph,
+20px padding instead of 16px).
+
+### Recipes
+
+```tsx
+// The agent idiom (stream-agent's QuickPrompt wrapper) — accessible + focus ring
+<ScBriefCard
+  role="button"
+  tabIndex={0}
+  aria-label={title}
+  description={description || title}
+  className="h-full cursor-pointer outline-none focus-visible:ring-2 focus-visible:ring-[var(--alias-border-focus)]"
+  onClick={() => onClick?.(promptValue)}
+  onKeyDown={(e) => {
+    if (e.key === "Enter" || e.key === " ") { e.preventDefault(); onClick?.(promptValue); }
+  }}
+/>
+
+// An equal-height grid of briefs
+<div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fit, minmax(180px, 1fr))", gap: 12 }}>
+  {briefs.map((b) => (
+    <ScBriefCard key={b.id} description={b.text} style={{ height: "100%" }}
+      role="button" tabIndex={0} onClick={() => send(b.text)} />
+  ))}
+</div>
+
+// Marking the brief that's currently running — add a light-mode-safe cue too
+<ScBriefCard description={b.text} active={b.id === runningId} aria-current={b.id === runningId ? "true" : undefined} />
+```
+
+---
+
+## 2. Where to use it
+
+- **The agent chat's empty state / suggested-prompt grid.** `stream-agent`'s local
+  `QuickPrompt` component is a thin wrapper around this card: it takes
+  `title`/`value`/`description`, falls back to `description || title`, and adds the
+  button semantics and focus ring.
+- Any **agent surface offering short one-line actions** where the text *is* the whole
+  card.
+
+Note what the wrapper reveals: `QuickPrompt`'s `icon` prop is accepted purely for
+call-site compatibility and thrown away, because **the Figma brief card has no
+icon**. Don't try to add one.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The card content is **one sentence**, and clicking it sends that sentence.
+- You are inside the agent/copilot runtime and want the coral gradient-border
+  language shared with `ScAppCardV3`.
+- Cards sit in an equal-height grid where the shell's `height: 100%` helps.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The DS prompt chip with app name + bolt icon + heading + description (CXO home) | `ScQuickPrompt` |
+| A product tile with a name and an icon pill | `ScAppCardV3` |
+| A dark glassy product **wordmark** card on the copilot surface | `ScAppCardForCopilot` |
+| A titled "choose an option" card in a dashboard | `ScDefaultCard` |
+| An in-chat message bubble | `ScInChatMessage` (inside `ScInChatList`) |
+| An in-chat radio row with title + description | `ScSelection` / `ScSelectionList` |
+| A pending action awaiting confirmation | `ScPendingAction` |
+| A segmented filter row in a dashboard | `ScSelectionPill` / `ScSelectionPillGroup` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScQuickPrompt` — `appName` + `heading` + `description` + a `SiconBolt` chip; **rendered by CXO's landing page** | `ScBriefCard` is description-only and lives in the agent runtime |
+| `ScAppCardV3` — same shell, but `appName` + `description` + icon pill, description in *tertiary* | This card is one *primary*-coloured paragraph, centred |
+| `ScDefaultCard` — plain subtle border, centred title + hint, `state="hover"` prop | No gradient border, no glow, no `active` |
+| `ScAppCardForCopilot` — real `<button>`, fixed dark, wordmark | This is a `div` and follows the theme |
+
+The naming trap: **the agent's `QuickPrompt` renders `ScBriefCard`, while the DS's
+`ScQuickPrompt` is a different, older card that CXO uses.** Two components, similar
+names, opposite surfaces.
+
+---
+
+## 4. Why to use it
+
+- **Shell parity with `ScAppCardV3` for free.** The gradient border (1px-padded
+  wrapper + `calc(radius - 1px)` inner card) and the two-layer glow are the same CSS,
+  so briefs and app cards read as one family. Fixing one shell fixes both.
+- **The glow never eats clicks.** Both glow layers are `pointer-events: none`, and
+  `overflow: clip` keeps them inside the rounded corners.
+- **Primary-coloured body text.** A brief is the *content*, not a caption, so the
+  paragraph uses `--alias-text-and-icons-primary` — the reason this card is not just
+  `ScAppCardV3` with the name removed.
+- **`word-break: break-word` + no clamp** means a long prompt grows the card instead
+  of clipping, which is what you want when the text is the clickable payload.
+- **`height: 100%`** on the inner card keeps a grid of briefs even without measuring.
+
+---
+
+## Gotchas
+
+**1. The default copy is wrong for this card.** `description` defaults to the app-card
+sentence about storefront asset management.
+
+```tsx
+// WRONG — renders "Centralized product and asset management for every storefront"
+<ScBriefCard onClick={send} />
+
+// RIGHT
+<ScBriefCard description="Show me the top 10 SKUs by margin this month." onClick={send} />
+```
+
+**2. There is no title and no icon.** Only `description`. If your data has a short
+title and a longer body, pick one — the agent wrapper resolves this as
+`description || title`.
+
+**3. `active` is invisible in light mode.** `--alias-surface-raised` and
+`--alias-surface-base` both resolve to `#ffffff` in the light theme. Pair `active`
+with `aria-current` and a visual cue that survives (border, ring, badge).
+
+**4. Not keyboard accessible on its own.** `cursor: pointer` is baked in but there is
+no `role`, `tabIndex` or key handling — and no focus ring. Add all of them, as
+`QuickPrompt` does, or keyboard users cannot trigger the prompt at all.
+
+**5. `className`, `style` and `onClick` go to the wrapper, not the inner card.** A
+class that tries to override `padding` or `background` will not apply to the padded
+surface; target `> div`, or restyle via tokens.
+
+**6. The accent colours are hardcoded.** The border gradient ends at `#EE5E3A`; the
+glow is a stack of `rgba(200,60,20,…)` stops. Identical in dark and light, with no
+brand override.
+
+**7. `backdrop-filter: blur(4px)` on the inner card** creates a containing block for
+`position: fixed` descendants. Portal any popover to `document.body`.
+
+**8. Grid alignment needs the wrapper stretched.** `height: 100%` is on the inner card
+only; in a flex row (or with `align-items: start`) pass `style={{ height: "100%" }}` —
+or a `h-full` class, which is what the agent wrapper does.
+
+---
+
+## In the wild
+
+```tsx
+// stream-agent  frontend/src/components/chat/QuickPrompt.tsx:31
+<ScBriefCard
+  role="button"
+  tabIndex={0}
+  aria-label={title}
+  description={cardDescription}
+  className={[
+    'h-full cursor-pointer outline-none transition-transform',
+    'focus-visible:ring-2 focus-visible:ring-[var(--alias-border-focus)]',
+    'focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--alias-surface-base)]',
+    className,
+  ].join(' ')}
+  onClick={() => onClick?.(promptValue)}
+  onKeyDown={handleKeyDown}
+/>
+```
+
+_No host render site found — used by the agent runtime / composed internally._
+That is correct and expected: this card belongs to the chat runtime. The nearest
+host-dashboard equivalent is `ScQuickPrompt`, rendered by
+`cxo-dashboard src/app/components/landing-content.tsx:380`.
+
+---
+
+## Related
+
+- `ScQuickPrompt` — the DS's other prompt card (app name + bolt + heading); used by CXO's home.
+- `ScAppCardV3` — the same gradient-border shell with a name row and icon pill.
+- `ScAppCardForCopilot` — the other agent-surface card, wordmark-based and fixed dark.
+- `ScInChatList` / `ScInChatMessage` — the transcript components these briefs sit above.
+- `ScSelection` / `ScSelectionList` / `ScPendingAction` — the rest of the in-chat vocabulary.

package/dist/docs/ScButton.md

@@ -0,0 +1,251 @@
+---
+component: ScButton
+package: "@streamoid/ui"
+category: actions
+status: stable
+renders: div[role="button"]
+tags: [button, cta, submit, action, click, icon-button, primary, danger]
+related: [ScFieldButton, ScOnlyIcon, ScMobileBottomAction, ScAskAgentButton]
+do_not_confuse_with: [ScFieldButton, ScOnlyIcon, ScPopUpMenu]
+used_by: [cxo, photogenix, catalogix, artifax]
+---
+
+# ScButton
+
+**The one button primitive.** Every call-to-action across all four Streamoid apps
+goes through this component — Photogenix alone renders it 373 times.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need any clickable action with a label, an icon, or both.
+- **Don't reach for it when:** the action sits inline with a form field (→ `ScFieldButton`),
+  it's a bare icon affordance in a toolbar (→ `ScOnlyIcon`), or it's a mobile
+  screen's sticky footer action (→ `ScMobileBottomAction`).
+- **Three things that will bite you:**
+  1. It renders a `<div role="button">`, **not** a `<button>`. No native form submit.
+  2. `type` is a **style** prop, not the HTML button type. `type="submit"` does nothing.
+  3. There is **no `disabled` prop** — disable with `state="disabled"`.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScButton } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScButton text="Save changes" variant="mono" size="md" onClick={handleSave} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `text` | `string` | `"Button"` | The label. **Ignored when `children` is passed.** |
+| `children` | `ReactNode` | – | Overrides `text` **and suppresses the icon entirely**. |
+| `icon` | `JSX.Element` | `<SiconHome />` | ⚠️ Has a real default. Only rendered when `styleVariant` is `icon-left` / `icon-right` / `icon-only`. |
+| `styleVariant` | `"default"` \| `"icon-right"` \| `"icon-left"` \| `"icon-only"` | `"default"` | Whether and where the icon renders. `"default"` = label only. |
+| `variant` | `"primary"` \| `"secondary"` \| `"tertiary"` \| `"outline"` \| `"error"` \| `"mono"` | `"primary"` | Colour role. `mono` = black/white, flips with the theme. `error` = destructive. |
+| `type` | `"primary"` \| `"secondary"` \| `"tertiary"` | `"primary"` | A **second style axis** multiplied with `variant` (emphasis within the role). **Not** the HTML `type` attribute. |
+| `size` | `"lg"` \| `"md"` \| `"sm"` | `"lg"` | Also drives the icon stroke width (1.25 for `sm`, 1.5 otherwise). |
+| `state` | `"default"` \| `"hover"` \| `"disabled"` | `"default"` | `"disabled"` → `pointer-events: none`, `cursor: not-allowed`, `tabIndex={-1}`, `aria-disabled`. `"hover"` force-renders hover styling (Figma parity / screenshots). |
+| `loading` | `boolean` | `false` | Swaps all content for a spinner. **Does not disable the button** — see Gotcha 5. |
+| `className` | `string` | – | Appended after the internal classes, so it wins on equal specificity. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `onClick`, `style`, `aria-*`, `data-*` are spread onto the root div. |
+
+### Recipes
+
+```tsx
+// Primary CTA, disabled until the form is valid  (the standard host idiom)
+<ScButton
+  text="Invite user"
+  variant="primary"
+  size="md"
+  state={isSubmitDisabled ? "disabled" : "default"}
+  onClick={handleInvite}
+/>
+
+// Destructive action
+<ScButton text="Remove user" variant="error" size="md" onClick={onRemove} />
+
+// Async submit — spinner AND blocked input
+<ScButton
+  text="Publishing…"
+  variant="mono"
+  loading={isSaving}
+  state={isSaving ? "disabled" : "default"}
+  onClick={handlePublish}
+/>
+
+// Icon + label
+<ScButton
+  text="Add store"
+  styleVariant="icon-left"
+  icon={<SiconPlus size={20} />}
+  variant="outline"
+  size="md"
+/>
+
+// Icon only
+<ScButton
+  styleVariant="icon-only"
+  icon={<SiconLogout size={24} />}
+  variant="error"
+  type="tertiary"
+  size="md"
+  aria-label="Log out"
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **Modal and drawer footers** — the confirm/cancel pair (`ScModal`, `ScDrawer`).
+- **Form submits** — at the end of `ScTextField` / `ScAppField` stacks.
+- **Card CTAs** — inside `ScPlanCard`, `ScCreditsUsageCard`, `ScWorkspaceCard`
+  (several of these already render one internally; pass their `buttonText` /
+  `onUpgrade` props rather than nesting your own).
+- **Sidebar footers and banners** — `ScCreditWarningBanner`'s "Buy credits".
+- **Page headers** — the primary action beside a `ScHeader`.
+
+All four host apps use it. CXO wraps it in a local `app/components/Button` shim
+that maps legacy names (`primary`→`mono`, `danger`→`error`, `transparent`→`outline`)
+so old call sites keep working.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The element performs an **action** (mutates state, submits, opens, deletes).
+- You want the label, icon sizing, spinner, focus ring, and theme behaviour to
+  match every other button in the product without thinking about it.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Action sitting inline with a form field ("Browse", "Apply") | `ScFieldButton` — matches field height and border |
+| Bare square icon affordance in a toolbar | `ScOnlyIcon` |
+| Mobile screen's sticky bottom action bar (1 or 2 buttons) | `ScMobileBottomAction` |
+| Navigation to another route/URL | a real `<a>` / your router's `<Link>` — this is a `div`, so it gets no link semantics, no middle-click, no "open in new tab" |
+| Opening a menu of choices | `ScPopUpMenu` + `ScMenuOptions` |
+| The gradient "Ask CXO" assistant CTA in a sidebar | `ScAskAgentButton` / `ScAskAgentSlot` |
+| A row in a segmented/tabbed control | `ScSelectionPill` / `ScTabs` / `ScTabSwitcher` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| HTML `type="submit"` behaviour | `type` here is a style axis. Wire `onClick` instead. |
+| `variant="primary"` in Catalogix | The orange gradient is **retired** there — use `mono` or `outline`. |
+
+---
+
+## 4. Why to use it
+
+- **Theme correctness for free.** Styled entirely off `--alias-*` tokens, so it
+  flips between dark and light without a single conditional in your code. Hand-rolled
+  buttons are the most common source of light-mode contrast bugs.
+- **Icon normalisation.** Your icon is cloned with `color="currentColor"` and a
+  size-matched `strokeWidth`, so icon and label always share a colour and optical weight.
+- **Keyboard access already handled.** Enter and Space invoke `onClick`; `tabIndex`
+  and `aria-disabled` track `state`. A hand-rolled `<div onClick>` gives you none of that.
+- **Figma parity.** `variant` × `type` × `size` × `state` maps 1:1 onto the design
+  library, so a spec can be implemented by reading prop names off the design.
+- **One place to change.** A tweak to the button shape ships to 400+ call sites at once.
+
+---
+
+## Gotchas
+
+**1. It is not a native `<button>`.** It renders `<div role="button" tabIndex={0}>`.
+It will never submit a form.
+
+```tsx
+// WRONG — no form submission happens
+<form onSubmit={save}><ScButton text="Save" type="submit" /></form>
+
+// RIGHT
+<form onSubmit={save}><ScButton text="Save" onClick={save} /></form>
+```
+
+**2. `type` is not the HTML type.** `type="primary" | "secondary" | "tertiary"` is a
+style axis that combines with `variant`. Passing `"submit"` is a type error and has
+no runtime effect.
+
+**3. `icon` defaults to a home icon.** If you set an icon `styleVariant` and forget
+`icon`, you ship a house.
+
+```tsx
+// WRONG — renders SiconHome
+<ScButton text="Delete" styleVariant="icon-left" />
+
+// RIGHT
+<ScButton text="Delete" styleVariant="icon-left" icon={<SiconDelete size={20} />} />
+```
+
+**4. `children` silently drops the icon.** The icon only renders on the `text` path.
+
+```tsx
+// WRONG — icon never appears
+<ScButton styleVariant="icon-left" icon={<SiconPlus />}>Add</ScButton>
+
+// RIGHT
+<ScButton styleVariant="icon-left" icon={<SiconPlus />} text="Add" />
+```
+
+**5. `loading` does not disable.** The spinner shows but clicks still fire — a
+double-submit waiting to happen. Pair it with `state="disabled"`.
+
+**6. Your icon's `color` prop is overwritten.** The component clones the icon with
+`color="currentColor"` so it inherits the button's text colour. Setting a colour on
+the icon is dead code — control it via `variant` instead.
+
+```tsx
+// POINTLESS — color is overwritten by cloneElement
+<ScButton styleVariant="icon-only" icon={<SiconLogout color="var(--alias-text---icons-error)" />} />
+
+// RIGHT — the variant colours both label and icon
+<ScButton styleVariant="icon-only" icon={<SiconLogout />} variant="error" type="tertiary" />
+```
+
+**7. `variant="primary"` + `type="primary"` is non-deterministic.** That combination
+generates a canvas noise texture at runtime using `Math.random()`, and needs a DOM.
+Avoid it in snapshot tests, and expect nothing painted during SSR.
+
+**8. `state="hover"` is for design parity, not interaction.** It force-renders the
+hover skin. Never wire it to your own mouse handlers — real `:hover` already works.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/invite-update-modal.tsx:927
+<ScButton
+  text="Remove user"
+  variant="error"
+  size="md"
+  state={canRemove ? "default" : "disabled"}
+  onClick={canRemove ? onRemove : undefined}
+/>
+```
+
+---
+
+## Related
+
+- `ScFieldButton` — field-height sibling for form-adjacent actions.
+- `ScOnlyIcon` — icon-only affordance without button chrome.
+- `ScMobileBottomAction` — mobile sticky footer, composes 1–2 buttons.
+- `ScAskAgentButton` / `ScAskAgentSlot` — the gradient assistant CTA.
+- `@streamoid/icons` — every `Sicon*`; check `packages/icons/ICONS.md` before drawing a new one.