@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScStreamoidWordmark.md

@@ -0,0 +1,302 @@
+---
+component: ScStreamoidWordmark
+also_exports: [ScStreamoidMascot, ScCxoCopilotLogo]
+package: "@streamoid/ui"
+category: brand
+status: stable
+renders: span[aria-hidden] (wordmark) · svg[role="img"] (mascot, CXO logo)
+tags: [brand, logo, wordmark, mascot, streamoid, cxo, copilot, mask, svg, gradient, sidebar-header]
+related: [ScSideBarLogoUnit, StreamoidSidebar, ScAppcardLogos, ScAppSwitchPanel, ScStrLogo]
+do_not_confuse_with: [ScStrLogo, ScLogoUnit, ScAppcardLogos, ProductWordmark, ScSideBarLogoUnit, ScCxoCopilotLogo]
+used_by: [cxo]
+---
+
+# ScStreamoidWordmark · ScStreamoidMascot · ScCxoCopilotLogo
+
+**The company's own brand marks, so no host app ships a brand SVG.** Three leaf
+components in one folder: the plain "streamoid" wordmark (110×16, painted as a CSS
+mask so a token colours it), the colourful mascot glyph used in the collapsed
+sidebar (teal→purple gradient, 48×48 viewBox), and the CXO Copilot lockup
+(98×32, red→orange gradient).
+
+## TL;DR for agents
+
+- **Reach for it when:** you need the *Streamoid* wordmark or mascot, or the *CXO
+  Copilot* logo, as a bare mark you position yourself — typically as the
+  `wordmark` node you hand to `ScSideBarLogoUnit`.
+- **Don't reach for it when:** you want a *product* wordmark — Artifax, Photogenix,
+  Catalogix, Tactix (→ `ScAppcardLogos`, or `ProductWordmark` inside
+  `ScSideBarLogoUnit`); you want the whole clickable sidebar header row
+  (→ `ScSideBarLogoUnit`); or you want the old 626×60 wordmark+mascot lockup
+  (→ `ScStrLogo`, legacy).
+- **Four things that will bite you:**
+  1. `width`/`height` (and `size`) set the **box**, not the mark's scale. The art
+     scales to *fit* the box, so `width={220}` with the default `height={16}`
+     renders the same 110×16 mark, left-aligned in a 220px box. Scale both.
+  2. `ScStreamoidMascot`'s art spans only 15 of its 48 vertical viewBox units (and
+     40 of 48 horizontally), so `size={40}` paints a mark roughly 33×12.5px. It
+     looks much smaller than the number.
+  3. The wordmark is `aria-hidden` and contributes **no accessible name**. The
+     mascot and CXO logo carry hardcoded English `aria-label`s you cannot change.
+  4. None of them take `onClick`, children, or `...HTMLAttributes`. Only
+     `className` + `style` (+ `color`/`width`/`height`/`size`).
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import {
+  ScStreamoidWordmark,
+  ScStreamoidMascot,
+  ScCxoCopilotLogo,
+} from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScStreamoidWordmark />          {/* 110×16, primary-text colour */}
+<ScStreamoidMascot />            {/* 40×40 box */}
+<ScCxoCopilotLogo />             {/* 98×32 */}
+```
+
+### Props — `ScStreamoidWordmark`
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `width` | `number` | `110` | Box width in **px** (number only — `"100%"` is a type error). Native width. |
+| `height` | `number` | `16` | Box height in px. The mask is `contain` + `left center`, so extra height is padding, not scale. |
+| `color` | `string` | `"var(--alias-text---icons-primary, #f5f5f5)"` | Any solid CSS colour — it becomes `background-color` behind the mask. Gradients don't work (Gotcha 3). |
+| `className` | `string` | – | Set on the `<span>`. |
+| `style` | `CSSProperties` | – | Spread **last**, so it overrides the inline width/height/mask. |
+
+### Props — `ScStreamoidMascot`
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `size` | `number` | `40` | Square box in px (`viewBox="0 0 48 48"`). ⚠️ The art occupies ~40×15 of those 48 units — see Gotcha 2. |
+| `className` | `string` | – | Set on the `<svg>`. |
+| `style` | `CSSProperties` | – | Set on the `<svg>`. Does not override `width`/`height` attributes. |
+
+No `color` prop: the gradient (`#50DCDE` → `#7850DE`) is intrinsic to the mark —
+but only **two** of the mascot's three arcs carry it. The **right-hand arc** (the
+one with the "eye" dot cut out of it) is a separate path filled with
+`--alias-text---icons-primary`, so roughly a third of the mark is token-coloured
+and flips with the theme while the rest stays teal→purple.
+
+### Props — `ScCxoCopilotLogo`
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `width` | `number` | `98` | Box width in px. |
+| `height` | `number` | `32` | Box height in px. ⚠️ The JSDoc says height scales with the 98:32 ratio — **it does not**. Pass both (Gotcha 1). |
+| `className` | `string` | – | Set on the `<svg>`. |
+| `style` | `CSSProperties` | – | Set on the `<svg>`. |
+
+No `color` prop: the red→orange gradient (`#D91536` → `#EE5E3A`) is the brand.
+
+### Recipes
+
+```tsx
+// The standard job: feed the sidebar header's wordmark slot (expanded + collapsed)
+<ScSideBarLogoUnit
+  wordmark={<ScStreamoidWordmark width={110} height={16} />}
+  onClick={onToggle}
+  switchAriaLabel="Switch product"
+/>
+<ScSideBarLogoUnit
+  state="collapsed"
+  wordmark={<ScStreamoidMascot size={40} />}
+  onClick={onToggle}
+/>
+
+// A bigger wordmark on an auth / splash screen — scale BOTH axes (110:16 = 6.875)
+<ScStreamoidWordmark width={220} height={32} />
+
+// Recolour the wordmark for a coloured banner
+<ScStreamoidWordmark color="var(--alias-text---icons-inverse)" />
+
+// The CXO Copilot lockup, doubled — pass both dimensions
+<ScCxoCopilotLogo width={196} height={64} />
+
+// Give the mark an accessible name when it IS the page's identity
+<h1 style={{ margin: 0 }}>
+  <span className="sr-only">Streamoid</span>
+  <ScStreamoidWordmark width={165} height={24} />
+</h1>
+```
+
+---
+
+## 2. Where to use it
+
+- **Sidebar header** — the near-universal use. `ScStreamoidWordmark` goes into
+  `ScSideBarLogoUnit`'s `wordmark` slot when expanded; `ScStreamoidMascot` when
+  collapsed. `StreamoidSidebar` renders that unit for you.
+- **Auth / splash / empty-state screens** — the wordmark at 1.5–2× scale.
+- **CXO copilot surfaces** — `ScCxoCopilotLogo` on the agent panel header, the
+  copilot marketing/first-run surface, or anywhere the *Copilot* product (not the
+  company) is being named.
+
+CXO is the live consumer (`app-sidebar.tsx`). Photogenix/Catalogix/Artifax show
+their **own** product wordmark in that slot via `ScSideBarLogoUnit`'s `product`
+prop, which is why they don't import these.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The mark you need is **Streamoid the company** (wordmark or mascot) or **CXO
+  Copilot** — not one of the four products.
+- You want to position/scale the mark yourself, inside your own layout or a slot.
+- You need it to survive a theme flip: the wordmark is a token-coloured mask, so
+  it never becomes white-on-white in light mode the way an exported PNG/`<img>` does.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A **product** wordmark (Artifax / Photogenix / Catalogix / Tactix) | `ScAppcardLogos` (14px, `currentColor`) or `ScSideBarLogoUnit product="…"` |
+| The whole sidebar header row (mark + switch pill + click target) | `ScSideBarLogoUnit` |
+| The app-switch list of products | `ScAppSwitchPanel` |
+| The old 626×60 "wordmark + mascot" corporate lockup | `ScStrLogo` — legacy, don't start there |
+| The pre-`StreamoidSidebar` logo box | `ScLogoUnit` — legacy |
+| An app icon + name + description row | `ScAppCard` |
+| A clickable logo | wrap it in your own `<button>`, or use `ScSideBarLogoUnit` — these are inert `span`/`svg` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScStrLogo` — one 626×60 SVG containing the wordmark **and** the mascot together | `ScStreamoidWordmark` is 110×16 and has **no** mascot; `ScStreamoidMascot` is the mascot **alone** |
+| `ScLogoUnit` — a padded 240px sidebar box that renders `ScStrLogo` inside | Legacy; superseded by `ScSideBarLogoUnit` |
+| `ScAppcardLogos` — per-**product** wordmarks; has **no** Streamoid entry | These are the Streamoid/CXO marks |
+| `ProductWordmark` / `ProductCollapsedMark` (SC-SideBarLogoUnit) — per-product marks for the sidebar slot | Same slot, different brand |
+| `ScCxoCopilotLogo` — the **CXO Copilot** product lockup | Not a Streamoid company mark; different gradient, different aspect (98:32) |
+
+Note the aspect ratios, because neighbouring docs get this wrong: the Streamoid
+wordmark is **110×16**; **98×32** is `ScCxoCopilotLogo`.
+
+---
+
+## 4. Why to use it
+
+- **Zero brand assets in host repos.** Every consumer used to carry its own
+  hand-exported SVG component (CXO still has two dead ones under
+  `src/app/components/strLogo/`). One import replaces them, and a brand refresh
+  ships from one place.
+- **The wordmark is theme-correct by construction.** It's rendered as a CSS
+  `mask-image` with `background-color` from `--alias-text---icons-primary`, so it
+  is *the same colour as your text* in both themes and can brighten on hover. A
+  raw white `<img>` stays white and disappears on a light canvas — this is the
+  exact bug the mask design exists to prevent.
+- **Gradient marks stay gradient.** Mascot and CXO logo are inline multi-colour
+  SVGs (not masks) precisely so their gradients survive (the mascot deliberately
+  mixes the gradient with one token-filled arc); each one mints a
+  **unique gradient id per instance** with `useId()`, so N of them on a page don't
+  collide the way a copy-pasted SVG does.
+- **Correct geometry, once.** The 110×16 plain wordmark is deliberately a
+  *different* asset from the 110×34 app-switcher lockup (wordmark + descriptor,
+  22 paths, in `SC-AppSwitch/wordmarks.ts`). Picking the file yourself is how you
+  end up with the descriptor showing in a sidebar.
+
+---
+
+## Gotchas
+
+**1. Size props size the *box*; the art scales to fit.** The wordmark's mask is
+`mask-size: contain`, and both SVGs use the default `preserveAspectRatio`. Passing
+one dimension letterboxes the mark instead of growing it.
+
+```tsx
+// WRONG — still paints a 110×16 mark, now sitting in a 220px-wide box
+<ScStreamoidWordmark width={220} />
+
+// WRONG — still paints 98×32, letterboxed inside 196×32
+<ScCxoCopilotLogo width={196} />
+
+// RIGHT — scale both axes on the native ratio (110:16, 98:32)
+<ScStreamoidWordmark width={220} height={32} />
+<ScCxoCopilotLogo width={196} height={64} />
+```
+
+**2. The mascot is smaller than `size` implies.** Its artwork spans about 40×15
+units of a 48×48 viewBox, so `size={40}` yields ~33×12.5px of visible mark with
+~14px of empty space above it. That padding is deliberate (it centres the glyph in
+a 40px collapsed-sidebar slot) — don't "fix" it by inflating `size` unless you
+also expect the slot to grow.
+
+**3. `color` on the wordmark is a `background-color`, not a fill.** Solid colours
+and `currentColor` work; `linear-gradient(...)` silently paints nothing because a
+gradient is a `background-image`. The wordmark is single-colour by design.
+
+**4. The wordmark is `aria-hidden`.** It contributes no accessible name. If it is
+the only identity on the surface, label the wrapper yourself.
+(`ScSideBarLogoUnit` already labels its row — default `"Switch product"`.)
+
+**5. The mascot/CXO `aria-label`s are hardcoded English** (`"Streamoid"`,
+`"CXO Copilot"`) with no prop to override. Fine for brand names; a blocker if a
+surface must be fully localised.
+
+**6. No event props, no children.** These interfaces are exactly
+`{ width|height|size?, color?, className?, style? }` — they do **not** extend
+`HTMLAttributes`. `onClick`, `id`, `data-*`, `role` are type errors.
+
+```tsx
+// WRONG — onClick is not in the props type and nothing is spread
+<ScStreamoidMascot size={40} onClick={goHome} />
+
+// RIGHT
+<button type="button" onClick={goHome} aria-label="Home">
+  <ScStreamoidMascot size={40} />
+</button>
+```
+
+**7. `style` wins over the component's own inline styles on the wordmark** (it is
+spread last). Handy for `marginLeft`, dangerous if you set `background` — that
+kills the mask fill and the mark vanishes.
+
+**8. `STREAMOID_WORDMARK` (the data-URI asset in `streamoid-wordmark.ts`) is
+not public.** It is not re-exported from the package entry point. Don't try to
+import the raw URI; render the component.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/app-sidebar.tsx:76
+<ScSideBarLogoUnit
+  wordmark={<ScStreamoidWordmark width={110} height={16} />}
+  onClick={onClick}
+  switchAriaLabel="Switch product"
+  style={{ paddingBottom: 0 }}
+/>
+
+// cxo-dashboard  src/app/components/app-sidebar.tsx:100
+<ScSideBarLogoUnit
+  state="collapsed"
+  wordmark={<ScStreamoidMascot size={40} />}
+  onClick={onClick}
+  hover={open ? true : undefined}
+/>
+```
+
+`ScCxoCopilotLogo` has no host render site yet — it is the CXO-only copilot
+lockup, and CXO currently renders the company wordmark in its shell.
+
+---
+
+## Related
+
+- `ScSideBarLogoUnit` — the sidebar header row these marks are usually passed into.
+- `StreamoidSidebar` — renders that unit as part of the app shell.
+- `ScAppcardLogos` — the per-product wordmark set (no Streamoid entry).
+- `ScAppSwitchPanel` — the product-switch list below the logo.
+- `ScStrLogo` / `ScLogoUnit` — the legacy 626×60 lockup and its container.

package/dist/docs/ScSubAgent.md

@@ -0,0 +1,226 @@
+---
+component: ScSubAgent
+also_exports: [formatSubAgentLabel]
+package: "@streamoid/ui"
+category: chat-agent
+status: stable
+renders: div
+tags: [chat, agent, sub-agent, delegation, pill, badge, using, tool, inchat]
+related: [ScInChatList, ScThinkingStepIcon, ScInChatMessage, ScBadges]
+do_not_confuse_with: [ScInChatList, ScBadges, ScTaxonomyPill, ScSelectionPill]
+used_by: [agent]
+---
+
+# ScSubAgent
+
+**The "Using Research Agent…" pill.** A single `fit-content` rounded chip with 12/18
+primary text on a neutral fill, marking the moment the main agent handed work to a
+sub-agent. Ships a `formatSubAgentLabel` helper that builds the label from a raw
+agent name.
+
+## TL;DR for agents
+
+- **Reach for it when:** a step in the transcript **is** a delegation — the agent
+  invoked a named sub-agent and you want to say so in one chip.
+- **Don't reach for it when:** the step has a title, a status glyph and a
+  tool name (→ `ScInChatList`, whose `showTool`/`toolUsing` renders the *same*
+  pill inside a full step row), or you want a status/count chip in a dashboard
+  (→ `ScBadges`).
+- **Three things that will bite you:**
+  1. `text` **bypasses formatting entirely**. If you pass `text`, you own the whole
+     string, including the "Using …" prefix and the ellipsis.
+  2. Pass neither `text` nor `agentName` and you get the literal
+     `"Using sub-agent..."`.
+  3. `white-space: nowrap` + `width: fit-content` — a long agent name **overflows**
+     its container instead of wrapping or truncating.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSubAgent, formatSubAgentLabel } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScSubAgent agentName="research agent" />   {/* → "Using Research Agent..." */}
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `text` | `string` | – | The label, **verbatim**. Wins over `agentName`; no prefix, no title-casing, no ellipsis added. |
+| `agentName` | `string` | – | Run through `formatSubAgentLabel` → `` `Using ${TitleCased}...` ``. Only used when `text` is `undefined`. |
+| `className` | `string` | – | Appended after the internal class (falsy values filtered). |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `onClick`, `style`, `title`, `data-*`, `aria-*` spread onto the root. |
+
+Resolution is exactly `const label = text ?? formatSubAgentLabel(agentName)` — note
+`??`, so `text=""` renders an **empty pill**, it does not fall through to `agentName`.
+
+### `formatSubAgentLabel(agentName?: string): string`
+
+Exported alongside the component, so you can compute the same label for a tooltip,
+an `aria-label`, or a log line.
+
+| Input | Output |
+|---|---|
+| `undefined` / `""` / `"   "` | `"Using sub-agent..."` |
+| `"research"` | `"Using Research..."` |
+| `"research agent"` | `"Using Research Agent..."` |
+| `"catalog-mapper"` | `"Using Catalog-Mapper..."` (`\b` matches after the hyphen) |
+| `"SEO agent"` | `"Using SEO Agent..."` (already-capitalised letters are untouched) |
+| `"  feed agent  "` | `"Using Feed Agent..."` (trimmed) |
+
+It uppercases the first character of **every word** via
+`replace(/\b\w/g, c => c.toUpperCase())`; it never lowercases anything.
+
+### Recipes
+
+```tsx
+// The runtime idiom: the step stream already carries a formatted label
+{step.kind === "subAgent" ? <ScSubAgent text={step.label} /> : <ScInChatList … />}
+
+// From a raw name off the wire
+<ScSubAgent agentName={event.sub_agent} />
+
+// Keep the pill and a tooltip in sync using the exported helper
+<ScSubAgent agentName={name} title={formatSubAgentLabel(name)} />
+
+// Long names: cap it yourself — the pill will not wrap or ellipsise
+<ScSubAgent text={`Using ${name.length > 28 ? name.slice(0, 27) + "…" : name}...`} />
+```
+
+---
+
+## 2. Where to use it
+
+- **The agent chat transcript's steps block**, as one entry in the same stack as
+  `ScInChatList`. In the live runtime
+  (`stream-agent frontend/src/components/chat/AgentSteps.tsx`) the step stream is
+  discriminated on `step.kind`: `"subAgent"` renders this pill, `"plan"` renders a
+  plan card, everything else renders a `ScInChatList` row.
+- It carries **no leading indicator gutter**, so a stack of `ScInChatList` rows with
+  a `ScSubAgent` among them is intentionally ragged on the left — the pill reads as a
+  marker, not as another step.
+
+Its skin is byte-for-byte the same as `ScInChatList`'s internal tool pill
+(`--alias-fill-neutral-neutraltohover`, `--radius-md`, 4/8 padding, 12/18 primary
+text). That is deliberate: same meaning, two placements.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The transcript entry's whole content is "work moved to <named agent>".
+- You want the delegation to read as a **chip**, visually subordinate to the
+  surrounding step rows and message bubbles.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A step with a title, status glyph and optional description | `ScInChatList` |
+| A tool pill attached **to** such a step | `ScInChatList` with `showTool` + `toolUsing` |
+| Only the status glyph (spinner / tick / cross) | `ScThinkingStepIcon` |
+| A status or count chip in a dashboard table/header | `ScBadges` |
+| A taxonomy tree node chip | `ScTaxonomyPill` |
+| A clickable segmented filter chip | `ScSelectionPill` |
+| Prose from the agent | `ScInChatMessage` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScInChatList` — the full step row; its tool pill looks identical | `ScSubAgent` is that pill standing alone, with no title, glyph or gutter |
+| `ScBadges` — dashboard status chip with semantic colours | This pill has one neutral skin and no tone/variant prop |
+| A pill with an icon | There is no icon slot; it is text only |
+
+---
+
+## 4. Why to use it
+
+- **One skin, two placements.** Because it reuses `ScInChatList`'s tool-pill tokens,
+  "the agent used a tool" and "the agent used a sub-agent" look like the same class of
+  event no matter which component drew them.
+- **The label rule lives in the DS, not in five call sites.** `formatSubAgentLabel`
+  makes "Using X…" phrasing, title-casing and the empty-name fallback a single
+  decision — and it is exported, so tooltips and aria labels can't drift from the
+  visible text.
+- **Theme-safe on a chat surface.** `--alias-fill-neutral-neutraltohover` on
+  `--alias-text-and-icons-primary` keeps the chip readable against both the dark
+  canvas and the light-mode surface, where a hardcoded `#1f1f1f` chip would go black.
+- **`fit-content` + `nowrap`** means the chip is exactly as wide as its text, so a
+  column of them stays visually ragged-right the way the design intends, instead of
+  stretching to the transcript's 600px measure.
+
+---
+
+## Gotchas
+
+**1. `text` skips the formatter completely.**
+
+```tsx
+// WRONG — renders the bare name, no "Using", no ellipsis
+<ScSubAgent text="research agent" />
+
+// RIGHT — either let agentName do the work…
+<ScSubAgent agentName="research agent" />
+// …or pass a label that is already complete
+<ScSubAgent text={formatSubAgentLabel("research agent")} />
+```
+
+**2. No props at all ⇒ `"Using sub-agent..."`.** A real, shippable default. Also
+reached when `agentName` is `""` or whitespace.
+
+**3. `text=""` renders an empty pill.** The fallback is `??`, not `||`, so an empty
+string is a valid label and you get a blank chip that is just its 8px-per-side
+padding wide. Guard upstream.
+
+**4. It never wraps or truncates.** `.label` is `white-space: nowrap` and
+`flex-shrink: 0` on a `fit-content` root, so a 60-character agent name pushes past
+its parent (and past `ScInChatList`'s 600px measure if they share a column). Cap the
+string yourself.
+
+**5. Title-casing is naive.** `\b\w` fires after every non-word character:
+`"catalog-mapper"` → `"Catalog-Mapper"`, `"v2 agent"` → `"V2 Agent"`. It also never
+lowercases, so `"RESEARCH"` stays `"RESEARCH"`. If the display name matters, pass
+`text`.
+
+**6. It is not a button.** A `div` with no `role`/`tabIndex`. `onClick` passes through
+via `HTMLAttributes`, but you get no keyboard, no focus ring and no affordance — add
+them yourself if the pill is meant to expand a sub-transcript.
+
+**7. It has no status.** Unlike `ScInChatList` there is no `iconState`; a sub-agent
+that failed looks identical to one that succeeded. If the delegation needs a state,
+render a `ScInChatList` row instead and put the pill content in `toolUsing`.
+
+---
+
+## 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:443
+<ScSubAgent text={step.label} />
+```
+
+---
+
+## Related
+
+- `ScInChatList` — the full step row; use its `showTool`/`toolUsing` for a tool pill
+  attached to a step.
+- `ScThinkingStepIcon` — the status glyph, when you need state rather than a name.
+- `ScInChatMessage` — the message bubbles the steps block sits between.
+- `ScBadges` — the dashboard-side chip vocabulary, with semantic tones.