@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScAppCardForCopilot.md

@@ -0,0 +1,230 @@
+---
+component: ScAppCardForCopilot
+package: "@streamoid/ui"
+category: cards
+status: stable
+renders: button[type="button"]
+tags: [card, copilot, agent, glassy, dark, wordmark, product, tagline, arrow, hover]
+related: [ScAppcardLogos, ScAppCardV3, ScAppListingCard, ScBriefCard, ScQuickPrompt]
+do_not_confuse_with: [ScAppCardV3, ScAppCard, ScAppListingCard, ScAppcardLogos]
+# used_by deliberately omitted: nothing renders this yet — see "In the wild".
+required_props: [product]
+---
+
+# ScAppCardForCopilot
+
+**A small, deliberately dark, glassy product card for the copilot surface.** It
+renders a single-colour product wordmark with a right-chevron that fades in on
+hover, and a grey tagline underneath — as a real `<button>` sized to its content.
+
+## TL;DR for agents
+
+- **Reach for it when:** the copilot / agent panel needs a compact "jump to this
+  product" affordance floating over content, identified by a **wordmark** rather
+  than an icon and label.
+- **Don't reach for it when:** you are in a host dashboard grid
+  (→ `ScAppCardV3` for the switcher, `ScAppListingCard` for a landing page), or you
+  only need the wordmark art itself (→ `ScAppcardLogos`).
+- **Four things that will bite you:**
+  1. `subText` defaults to **`"Planning & Buying"`** — Tactix's tagline. Render a
+     Photogenix card without setting it and you mislabel the product.
+  2. The card is **hardcoded `#101010` with `#9e9e9e` text in both themes**. It does
+     not follow the light theme, on purpose. On a light page it will look like a
+     black chip.
+  3. **The prop list is closed**: only `product`, `subText`, `onClick`, `className`,
+     `style`. No `aria-label`, no `data-*`, no `disabled`, no `id` — it does not
+     spread `ButtonHTMLAttributes`.
+  4. `product` is **required** and is a key of the wordmark set —
+     `"tactix" | "artifax" | "photogenix" | "catalogix"`. There is no Streamoid
+     wordmark here.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScAppCardForCopilot } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScAppCardForCopilot product="photogenix" subText="Product imagery" onClick={open} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `product` | `AppcardProduct` = `"tactix" \| "artifax" \| "photogenix" \| "catalogix"` | — | **Required.** Selects the wordmark rendered by `ScAppcardLogos`. Also becomes the wordmark's `aria-label`, i.e. the raw lowercase key. |
+| `subText` | `string` | `"Planning & Buying"` | ⚠️ Real default, and it is **Tactix's** tagline. `12px/18px`, colour hardcoded `#9e9e9e`. |
+| `onClick` | `() => void` | – | No event argument. Fires on click **and** on Enter/Space, because the root is a real `<button>`. |
+| `className` | `string` | – | Appended after the internal class. |
+| `style` | `CSSProperties` | – | Applied to the `<button>`. The only way to override the fixed `width: fit-content`. |
+
+There is **no** props spread — anything not in this table is dropped at compile time.
+
+### Recipes
+
+```tsx
+// A row of product cards in the copilot panel — always set subText per product
+const PRODUCTS = [
+  { product: "tactix",     subText: "Planning & Buying" },
+  { product: "artifax",    subText: "Creative operations" },
+  { product: "photogenix", subText: "Product imagery" },
+  { product: "catalogix",  subText: "Catalog enrichment" },
+] as const;
+
+<div style={{ display: "flex", flexWrap: "wrap", gap: 12 }}>
+  {PRODUCTS.map((p) => (
+    <ScAppCardForCopilot
+      key={p.product}
+      product={p.product}
+      subText={p.subText}
+      onClick={() => openProduct(p.product)}
+    />
+  ))}
+</div>
+
+// Make it fill a column instead of hugging its content
+<ScAppCardForCopilot product="catalogix" subText="Catalog enrichment"
+  style={{ width: "100%" }} onClick={go} />
+```
+
+---
+
+## 2. Where to use it
+
+- **The copilot / agent chat panel** (`stream-agent` → `@streamoid/agent`) — a
+  floating card over the transcript or the empty state. Built from Figma
+  `AppCardForCopilot` (node `6383:9929`).
+- It is intentionally fixed-dark because it "floats over content"; it belongs on a
+  dark-ish or image-backed surface, not inline in a light settings page.
+
+It composes `ScAppcardLogos` for the wordmark and `SiconRight` for the chevron;
+nothing else in the DS renders it.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The product is best identified by its **wordmark** (brand recognition), not by an
+  icon plus a typed name.
+- The surface is the **copilot**, and the card is meant to read as a glassy overlay
+  chip rather than a page card.
+- You want real button semantics (Enter/Space, focus ring, no form submit) for free.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The host app-switcher grid (gradient border, `active` tile) | `ScAppCardV3` |
+| A product tile on a CXO landing page | `ScAppListingCard` |
+| A 200px icon + name + subtitle row beside a toggle | `ScAppCard` |
+| Just the wordmark art, no card | `ScAppcardLogos` |
+| The Streamoid wordmark or mascot | `ScStreamoidWordmark` / `ScStreamoidMascot` (SC-Brand) |
+| A per-app wordmark for a sidebar header | `ProductWordmark` / `ProductCollapsedMark` |
+| An agent quick-prompt card (description only, gradient border) | `ScBriefCard` (via `ScQuickPrompt`) |
+| A card that must follow the light theme | `ScAppCardV3` / `ScDefaultCard` — this one is fixed dark by design |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScAppcardLogos` — the bare wordmark `<span role="img">`, no card, no button | This wraps that wordmark in a dark button with a tagline and hover arrow |
+| `ScAppCardV3` — token-driven, theme-following, icon + typed name + `active` | This is fixed-dark, wordmark-only, with no selected state |
+| `ScAppCard` — chrome-less identity row for settings | Different family entirely |
+
+### Don't confuse the surfaces either
+
+This is the **only** card in the family that lives on the agent surface *and*
+renders a wordmark. If your design shows a typed product name, you want
+`ScAppCardV3` or `ScAppListingCard`.
+
+---
+
+## 4. Why to use it
+
+- **Real button semantics.** Unlike `ScButton` (a `div[role="button"]`) and unlike
+  every other card here (plain `div`s), this is a genuine
+  `<button type="button">`: Enter/Space work, focus-visible works, and it can never
+  accidentally submit a form.
+- **The hover choreography is wired to focus too.** `.card:hover .arrow` *and*
+  `.card:focus-visible .arrow` both reveal the chevron, so keyboard users get the
+  same affordance as mouse users — a detail hand-rolled versions always miss.
+- **Wordmark colouring is solved.** The wordmark is inline SVG on `currentColor`,
+  and the card pins `color: --alias-text---icons-fullwhite`, so the mark is always
+  crisp white on the dark glass without you exporting a second asset.
+- **Figma parity** with `AppCardForCopilot` (`6383:9929`), including the
+  `blur(4px)` glass, the 16px radius and the 12/16px padding pair.
+
+---
+
+## Gotchas
+
+**1. `subText` defaults to Tactix's tagline.** This is the trap of the component.
+
+```tsx
+// WRONG — a Photogenix card labelled "Planning & Buying"
+<ScAppCardForCopilot product="photogenix" onClick={go} />
+
+// RIGHT
+<ScAppCardForCopilot product="photogenix" subText="Product imagery" onClick={go} />
+```
+
+**2. Fixed dark in both themes.** `background: #101010` and `color: #9e9e9e` are
+literals, not tokens. This is deliberate (see the CSS header comment) — do not
+"fix" it by adding tokens without a design decision, and do not use the card on a
+white page expecting it to invert.
+
+**3. No props spread.** You cannot pass `aria-label`, `id`, `data-testid`,
+`disabled`, `type`, `onKeyDown` or `onMouseEnter`. If you need any of them, wrap the
+card or extend the component.
+
+**4. The accessible name is assembled, and partly a slug.** The button has no label
+of its own; its name comes from the wordmark's `aria-label={product}` (the raw
+lowercase key, e.g. `"photogenix"`) plus `subText`. Screen readers therefore
+announce roughly *"photogenix Product imagery, button"*. Acceptable, but if the
+surface has accessibility requirements, prefer wrapping with your own labelled
+control.
+
+**5. `width: fit-content`.** The card hugs its content, so a row of them will have
+uneven widths (the wordmarks are 54–88px wide). Set `style={{ width: "100%" }}` or
+a fixed width if the design wants a uniform row.
+
+**6. The chevron is invisible until hover/focus.** `opacity: 0` by default. In a
+screenshot test without hover simulation you will not see it — that is correct
+behaviour, not a bug.
+
+**7. `product` is a closed union of four keys.** There is no `"streamoid"` and no
+`"cxo"` wordmark in `APPCARD_WORDMARKS`; use `ScStreamoidWordmark` or
+`ScCxoCopilotLogo` for those.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+It is also not yet rendered inside `stream-agent`: that repo's empty state
+hand-rolls dashed-border wordmark pills instead
+(`stream-agent frontend/src/components/chat/EmptyChat.tsx:228` renders
+`<ScAppcardLogos product={p.product} className="shrink-0" />` inside its own
+`<button>`). So `ScAppCardForCopilot` is currently an unused Figma port. It belongs
+in the copilot panel's product row — replacing exactly that hand-rolled pill — or in
+any future agent surface that offers "open this product" cards.
+
+---
+
+## Related
+
+- `ScAppcardLogos` — the wordmark this card renders; use it alone when you don't want the card.
+- `ScAppCardV3` — the host-app switcher tile (theme-following, icon-based).
+- `ScBriefCard` / `ScQuickPrompt` — the other agent-surface card family.
+- `ScStreamoidWordmark` / `ScStreamoidMascot` — Streamoid brand marks (SC-Brand).
+- `ProductWordmark` — the per-product wordmark used in sidebar headers.

package/dist/docs/ScAppCardV3.md

@@ -0,0 +1,273 @@
+---
+component: ScAppCardV3
+package: "@streamoid/ui"
+category: cards
+status: stable
+renders: div
+tags: [card, tile, app, product, app-switcher, gradient-border, glow, active, v3]
+related: [ScBriefCard, ScAppListingCard, ScAppCard, ScAppSwitchPanel, ScAppCardForCopilot]
+do_not_confuse_with: [ScAppCard, ScAppListingCard, ScBriefCard, ScAppCardForCopilot]
+used_by: [cxo]
+---
+
+# ScAppCardV3
+
+**The app-switcher tile: name on the left, glass icon pill on the right, one
+description line under both.** Wrapped in a 1px gradient-border shell that warms to
+coral on hover, with a coral radial glow blooming from the bottom-right corner.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building the cross-product app-switcher grid
+  (or any dense grid of equal-height product tiles) and want the coral
+  gradient-border + glow treatment.
+- **Don't reach for it when:** you want the roomy landing-page product tile
+  (→ `ScAppListingCard`), a description-only card in the same shell
+  (→ `ScBriefCard`), a 200px identity row (→ `ScAppCard`), or the dark glassy
+  wordmark card (→ `ScAppCardForCopilot`).
+- **Four things that will bite you:**
+  1. `active` sets the inner background to `--alias-surface-raised`, which is
+     **`#ffffff` in light mode — the same as the default surface.** The active
+     state is effectively invisible in light mode.
+  2. Your `appIcon` is force-sized to **20×20** (`.iconPillIcon > * { width:100%;
+     height:100% }`), so the icon's own `size` prop is overridden.
+  3. `{...props}` (including `onClick`) lands on the **outer** `.cardBorder`
+     wrapper — but there is no `role`/`tabIndex`/key handling, so it is not
+     keyboard reachable until you add them.
+  4. The inner card is `height: 100%`; the **wrapper** has no height, so in a grid
+     you must stretch the wrapper (`height: 100%` or `align-items: stretch`) for
+     tiles to line up.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScAppCardV3 } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScAppCardV3
+  appName="Stores"
+  description="Centralized product and asset management for every storefront"
+  appIcon={<SiconStores />}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `appIcon` | `ReactNode` | `<SiconCart />` | ⚠️ Real default — a cart. Rendered inside the glass pill and **force-sized to 20×20** by CSS. |
+| `appName` | `string` | `"Stores"` | ⚠️ Real default. `text-md-medium`, primary, `flex: 1`, `overflow: hidden; text-overflow: ellipsis` — but **no `white-space: nowrap`**, so multi-word names still wrap rather than ellipsise. |
+| `description` | `string` | `"Centralized product and asset management for every storefront"` | ⚠️ Real default. `text-xs-regular`, tertiary, no clamp — long copy grows the tile. |
+| `active` | `boolean` | `false` | Swaps the inner background to `--alias-surface-raised`. See Gotcha 1 — 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. This is where you set `width` / `height` / `cursor`. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the outer wrapper (`onClick`, `role`, `tabIndex`, `onKeyDown`, `aria-*`, `data-*`). |
+
+### What the DOM looks like
+
+```
+div.cardBorder            ← className, style, {...props}, the 1px gradient "border"
+└─ div.scAppCardV3        ← surface, radius, padding, overflow:clip, height:100%
+   ├─ div.glow            ← decorative, pointer-events:none
+   ├─ div.glowHover       ← coral radial bloom, opacity 0 → 1 on wrapper :hover
+   └─ div.header
+      ├─ div.iconRow → p.appName + div.iconPill(bg/icon/shadow)
+      └─ p.description
+```
+
+### Recipes
+
+```tsx
+// The CXO app-switcher grid (5-up), clickable + keyboard reachable
+<div style={{ display: "grid", gridTemplateColumns: "repeat(5, minmax(0, 1fr))", gap: 16 }}>
+  {group.cards.map((card) => (
+    <ScAppCardV3
+      key={card.id}
+      appName={card.title}
+      description={card.desc}
+      appIcon={card.icon}
+      role="button"
+      tabIndex={0}
+      style={{ width: "100%", height: "100%", cursor: card.pageUrl ? "pointer" : "default" }}
+      onClick={() => handleCardClick(card.pageUrl)}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") { e.preventDefault(); handleCardClick(card.pageUrl); }
+      }}
+    />
+  ))}
+</div>
+
+// Marking the current app — pair `active` with something that survives light mode
+<ScAppCardV3
+  appName={app.title}
+  description={app.desc}
+  appIcon={app.icon}
+  active={app.id === currentAppId}
+  aria-current={app.id === currentAppId ? "true" : undefined}
+  style={{ width: "100%", height: "100%" }}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO's app switcher** — the desktop overlay (`app-switcher.tsx`, a 5-column grid)
+  and the mobile sheet (`mobile-app-switcher.tsx`, 2 columns). These are its only
+  render sites.
+- Any **grid of product/feature entry points** that wants the coral gradient-border
+  treatment rather than the scale-up hover of `ScAppListingCard`.
+- Photogenix's internal component-library catalogue lists it as a subcomponent of
+  its templates section, i.e. it is on that team's radar but not yet rendered.
+
+Its shell (gradient border + glow) is shared verbatim with `ScBriefCard`. CXO's
+`specialization-picker-modal.tsx` **ports that CSS by hand** rather than using the
+component — if you are touching the shell, that copy needs updating too.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Tiles are **dense and equal-height** (a switcher grid, a feature picker) and the
+  description is one short line.
+- You want the **coral gradient border + corner glow** hover language.
+- You need a **selected/current** tile in the grid (`active`) — and you are on dark
+  mode, or you add your own light-mode affordance.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A roomy landing-page product tile (24px padding, scale-up hover) | `ScAppListingCard` |
+| The same shell but description-only, centred (agent quick prompts) | `ScBriefCard` |
+| A 200px icon+name+subtitle identity row beside a control | `ScAppCard` |
+| A dark glassy card showing a product **wordmark** with a hover arrow | `ScAppCardForCopilot` |
+| The whole app-switcher flyout, already assembled | `ScAppSwitchPanel` (pass it to `StreamoidSidebar`'s `switchPanel`) |
+| "Choose one of these options" in a modal | `ScDefaultCard` |
+| A store tile | `ScStoreCard` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScBriefCard` — identical shell, but only `description` (centred), no name, no icon | `ScAppCardV3` always renders a name row and an icon pill |
+| `ScAppListingCard` — bigger tile, `title`/`descrp`, scale(1.03) hover, no gradient border | This tile is compact with a gradient border |
+| `ScAppCard` — the v1 of the name; a 200px chrome-less row | "V3" does **not** mean `ScAppCard` is deprecated; they are different shapes |
+| `ScAppSwitchPanel` — the whole switcher card/overlay | This is one tile inside such a grid |
+
+Prop-name cheat sheet: this card uses `appName` + **`description`**;
+`ScAppCard` uses `appName` + `appDescription`; `ScAppListingCard` uses `title` +
+`descrp`.
+
+---
+
+## 4. Why to use it
+
+- **The gradient border actually works.** A CSS gradient cannot be a `border` and
+  keep `border-radius`; the component solves it with a 1px-padded wrapper whose
+  background is the gradient and an inner card at `calc(radius - 1px)`. Getting
+  that right by hand is the usual source of hairline seams and clipped corners.
+- **The glow is two layers with a real transition** (`glow` fading out while
+  `glowHover` fades in over 600ms) and both are `pointer-events: none`, so the
+  bloom never eats your clicks.
+- **The glass icon pill is three stacked layers** — translucent black at
+  `blur(40px)`, an inset shadow, then the icon — and the icon is normalised to
+  20×20 so a grid of mixed icon sources still looks uniform.
+- **`overflow: clip` on the inner card** keeps the glow and the pill inside the
+  rounded corners without clipping the wrapper's gradient ring.
+- **One shell, two components.** Fixing the shell here fixes `ScBriefCard` too.
+
+---
+
+## Gotchas
+
+**1. `active` is invisible in light mode.** It sets `--alias-surface-raised`, and in
+the light theme `surface-base`, `surface-basesubtle` and `surface-raised` all
+resolve to `#ffffff`. Add your own marker (border, `aria-current`, a badge) if the
+selected tile must read in both themes.
+
+**2. Your icon's `size` is overridden.** `.iconPillIcon` is 20×20 and forces
+`width/height: 100%` on its direct child.
+
+```tsx
+// POINTLESS — the CSS forces 20×20 regardless
+<ScAppCardV3 appIcon={<SiconStores size={32} />} />
+
+// RIGHT — let the pill size it
+<ScAppCardV3 appIcon={<SiconStores />} />
+```
+
+**3. The default icon is a cart.** Pass `appIcon={maybeUndefined}` and you re-trigger
+the default. Decide explicitly with `?? <SiconX />`.
+
+**4. Not keyboard accessible out of the box.** `cursor: pointer` is baked into the
+inner card, so it looks clickable, but there is no `role`, `tabIndex` or key
+handling. Add all three alongside `onClick` (neither CXO switcher currently does —
+that is a known gap, not a pattern to copy).
+
+**5. `className`/`style`/`onClick` go to the wrapper, not the card.** If you write a
+`className` that expects to sit on the padded surface (e.g. overriding `padding` or
+`background`), it will not apply — target `> div` from your class, or restyle via
+tokens.
+
+**6. Grid alignment needs the wrapper stretched.** `height: 100%` is on the inner
+card only. In a CSS grid the wrapper is stretched by default (`align-items:
+stretch`), which is why both CXO call sites get away with passing only
+`style={{ width: "100%" }}`. In a flex row, or with `align-items: start`, you must
+also pass `style={{ height: "100%" }}`.
+
+**7. `appName` ellipsis is half-configured.** It has `overflow: hidden` and
+`text-overflow: ellipsis` but no `white-space: nowrap`, so a two-word name wraps to
+a second line and shifts the description down instead of showing an ellipsis. Keep
+names short, or clamp them yourself.
+
+**8. The hover accents are hardcoded, not tokens.** The border gradient ends at
+`#EE5E3A` and the glow is a stack of `rgba(200,60,20,…)` stops. Identical in dark
+and light; no brand override hook.
+
+**9. `backdrop-filter: blur(4px)` on the inner card** creates a containing block for
+fixed-position descendants. Do not render a `position: fixed` popover from inside
+the tile — portal it to `document.body`.
+
+**10. There is no `onClick` in the interface** — it arrives via
+`HTMLAttributes<HTMLDivElement>`. Do not look for a documented handler prop; the
+same is true of `role`, `tabIndex` and `aria-*`.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/app-switcher.tsx:366
+<ScAppCardV3
+  key={card.id}
+  appName={card.title}
+  description={card.desc}
+  appIcon={card.icon}
+  style={{ width: "100%", cursor: card.pageUrl ? "pointer" : "default" }}
+  onClick={() => handleCardClick(card.pageUrl)}
+/>
+```
+
+The mobile sheet renders the same call in a 2-column grid at
+`src/app/components/mobile-app-switcher.tsx:327`.
+
+---
+
+## Related
+
+- `ScBriefCard` — the same gradient-border shell, description-only (agent runtime).
+- `ScAppListingCard` — the larger landing-page product tile.
+- `ScAppCard` — the 200px chrome-less identity row (not an older version of this).
+- `ScAppCardForCopilot` — dark glassy wordmark card; a real `<button>`.
+- `ScAppSwitchPanel` — the assembled app-switcher overlay this tile belongs in.