@streamoid/ui 0.6.17 → 0.6.19

package/dist/docs/ScAppSwitchPanel.md

@@ -0,0 +1,286 @@
+---
+component: ScAppSwitchPanel
+also_exports: [ScAppSwitchRow]
+package: "@streamoid/ui"
+category: sidebar
+status: stable
+renders: div
+tags: [app-switcher, switch-app, product-switcher, cross-product, tactix, artifax, photogenix, catalogix, streamoid, wordmark]
+related: [ScSideBarLogoUnit, StreamoidSidebar, ScSidebarSwitchMenu, ScWorkspaceSwitchCard]
+do_not_confuse_with: [ScSidebarSwitchMenu, StreamoidWorkspaceSwitcher, ScWorkspaceSwitchCard, ScAppListingCard, ScAppCard]
+used_by: [cxo, photogenix, catalogix, artifax]
+required_props: [apps]
+---
+
+# ScAppSwitchPanel
+
+**The cross-product "switch app" list — one identical implementation for all four
+apps.** A bare column of 60px rows, each showing the target product's wordmark
+(gray, brightening to white on hover) and a `>` chevron that fades in. It has no
+card, no border and no background: the surrounding sidebar or flyout supplies those.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need the "go to another Streamoid product" list —
+  in `StreamoidSidebar`'s `switchPanel`, or in your own portalled flyout.
+- **Don't reach for it when:** you're switching **workspaces** rather than products
+  (→ `ScWorkspaceSwitchCard` / `StreamoidWorkspaceSwitcher`), you want one row with
+  an icon + description (→ `ScSidebarSwitchMenu`), or you want a product tile in a
+  launcher grid (→ `ScAppListingCard`).
+- **Four things that will bite you:**
+  1. It **re-sorts your array** into a canonical product order. Your ordering is
+     discarded.
+  2. If a product matches an embedded wordmark, `name` **and** `description` are
+     **not rendered at all** — the wordmark replaces them.
+  3. Matching is a **substring** test over `` `${key} ${name}`.toLowerCase() ``. A key
+     containing `"cxo"` or `"streamoid"` gets the Streamoid wordmark.
+  4. It does **not** exclude the current app. That's the host's job.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import {
+  ScAppSwitchPanel,
+  ScAppSwitchRow,
+  type ScAppSwitchItem,
+} from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScAppSwitchPanel
+  apps={[
+    { key: "artifax",    name: "Artifax",    onSelect: () => open(artifaxUrl) },
+    { key: "photogenix", name: "Photogenix", onSelect: () => open(photogenixUrl) },
+  ]}
+/>
+```
+
+### Props — `ScAppSwitchPanel`
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `apps` | `ScAppSwitchItem[]` | — | **Required.** ⚠️ **Re-sorted internally** into canonical order; unknown products keep their relative order and go last. |
+| `className` | `string` | – | On the root column. |
+| `style` | `CSSProperties` | – | Merged **after** the base inline styles, so it can override `paddingBottom`. |
+
+### Props — `ScAppSwitchRow`
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `item` | `ScAppSwitchItem` | — | **Required.** The only prop — no `className`, no `style`. Rarely used directly; the panel renders one per app. |
+
+### `ScAppSwitchItem`
+
+| Field | Type | Notes |
+|---|---|---|
+| `key` | `string` | React key **and** half of the wordmark-matching string. |
+| `name` | `string` | Matching input, and the fallback label. ⚠️ **Not rendered** when a wordmark matches. Always used for the row's `aria-label` (`"Switch to {name}"`). |
+| `description` | `string` | Optional tagline. ⚠️ **Only rendered for products with no embedded wordmark.** |
+| `onSelect` | `() => void` | Row click. |
+
+### Wordmark matching + canonical order
+
+| Order | Matches (substring, case-insensitive, on `key + " " + name`) | Renders |
+|---|---|---|
+| 1 | `tactix` | Tactix wordmark (100×34) |
+| 2 | `artifax`, `design studio` | Artifax wordmark (116×32) |
+| 3 | `photogenix`, `photo studio` | Photogenix wordmark (142×36) |
+| 4 | `catalogix`, `catalog studio` | Catalogix wordmark (94×36) |
+| 5 | `streamoid`, `cxo` | Streamoid wordmark (110×34) |
+| last | anything else | `name` (16px semibold) + `description` (14px tertiary) |
+
+### Recipes
+
+```tsx
+// Inside StreamoidSidebar — the sidebar positions it for both rails
+<StreamoidSidebar
+  switchPanel={apps.length ? <ScAppSwitchPanel apps={apps} /> : undefined}
+  switchPanelOpen={appListOpen}
+  onSwitchPanelClose={() => setAppListOpen(false)}
+  /* … */
+/>
+
+// Mapping a host service catalog, excluding the current app yourself
+const apps: ScAppSwitchItem[] = serviceCatalog
+  .filter((s) => s.key !== CURRENT_APP_KEY)      // the panel will NOT do this
+  .map((s) => ({
+    key: s.key,
+    name: s.name,
+    description: s.desc,                          // only shows for unknown products
+    onSelect: () => window.open(s.pageUrl, "_blank"),
+  }));
+
+<ScAppSwitchPanel apps={apps} />
+
+// In your own portalled flyout (ScArtifaxSidebar has no switchPanel slot).
+// The panel brings its own bottom padding — don't add a second one.
+createPortal(
+  <div style={{ width: 240, background: "var(--alias-surface-base)", border: "1px solid var(--alias-border-default)", borderRadius: "var(--radius-3xl)", overflow: "hidden" }}>
+    <ScAppSwitchPanel apps={apps} />
+  </div>,
+  document.body,
+)
+```
+
+---
+
+## 2. Where to use it
+
+- **`StreamoidSidebar`'s `switchPanel` slot** — CXO, Photogenix and Catalogix all do
+  this. The sidebar renders it as an animated drop-down card when expanded and as a
+  240px right-side flyout when collapsed.
+- **A host-owned portalled flyout** — Artifax, because `ScArtifaxSidebar` has no
+  switch slot and the sidebar body would clip an inline panel.
+- Triggered by `ScSideBarLogoUnit`; it never renders its own trigger.
+- All four apps use it, which is the point: the switcher looks and orders identically
+  everywhere regardless of the order each backend returns.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The user is moving between **Streamoid products** (Tactix / Artifax / Photogenix /
+  Catalogix / Streamoid CXO).
+- You want the canonical order and the embedded brand wordmarks for free.
+- The list lives inside chrome you already own (a sidebar card, a flyout, a popover).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Switching **workspace/tenant**, not product | `ScWorkspaceSwitchCard`, `StreamoidWorkspaceSwitcher`, `ScWorkspaceSwitchMobile` |
+| A single product row with an icon, name **and** description you control | `ScSidebarSwitchMenu` |
+| A product tile in a launcher grid / marketing surface | `ScAppListingCard`, `ScAppCardV3` |
+| Products shown as nav items in the sidebar body | `ScSidebarMenu` via `config.sections` |
+| An arbitrary popover menu of actions | `ScPopUpMenu` + `ScMenuOptions` |
+| You need to render the current app as "selected" | Nothing here supports it — this list is "other apps" only |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSidebarSwitchMenu` — one row, `icon` + `text` + `description`, five `state`s, `variant="collapsed"` | `ScAppSwitchPanel` renders whole rows with **embedded** wordmarks and no state |
+| `StreamoidWorkspaceSwitcher` / `ScWorkspaceSwitchCard` — workspaces (note: there is no `ScWorkspaceSwitcher` export) | This is products |
+| `ScAppCard` / `ScAppCardV3` / `ScAppListingCard` — product **cards** | This is a compact switch list |
+| `ScSideBarLogoUnit` — the trigger row | This is the panel it opens |
+
+---
+
+## 4. Why to use it
+
+- **One canonical order, enforced in the component.** Every backend returns the
+  service catalog in a different order; the panel sorts by a fixed product list so
+  the switcher never reshuffles between apps. The Artifax test suite asserts exactly
+  this ("imposes its own canonical order regardless of the order supplied").
+- **Brand wordmarks that respect the theme.** Each wordmark is drawn as a **CSS mask**
+  (`mask-image` data URI + `background-color`), so its colour is a token —
+  `--alias-text---icons-tertiary` at rest, `-primary` on hover. A plain `<img>` logo
+  would be stuck at one colour and invisible in light mode.
+- **Real `<button type="button">` per row** with `aria-label="Switch to {name}"`, and
+  the wordmark span marked `aria-hidden` so the announcement isn't duplicated.
+- **No chrome, deliberately.** Because it ships no card or border, the identical panel
+  drops into a sidebar drop-down, a 240px collapsed flyout and a portalled overlay
+  without fighting the host's surface.
+- **One place to add a product.** New product ⇒ one entry in the `WORDMARKS` table,
+  and it appears, in the right position, in all four apps.
+
+---
+
+## Gotchas
+
+**1. Your order is discarded.** `ordered = [...apps].sort((a, b) => orderIndex(a) - orderIndex(b))`.
+Sorting the array before passing it is wasted work; you cannot pin a product to the top.
+
+**2. A matched wordmark hides `name` and `description`.** The row renders either the
+mask wordmark **or** the name/description block, never both.
+
+```tsx
+// POINTLESS — "Design generation" is never shown; "artifax" matches the wordmark
+<ScAppSwitchPanel apps={[{ key: "artifax", name: "Artifax", description: "Design generation", onSelect }]} />
+
+// description only surfaces for products with no embedded mark
+<ScAppSwitchPanel apps={[{ key: "insights", name: "Insights", description: "Reporting", onSelect }]} />
+```
+
+**3. Matching is a loose substring test on `key + " " + name`.** `"cxo"` and
+`"streamoid"` both map to the Streamoid wordmark, `"design studio"` maps to Artifax,
+`"photo studio"` to Photogenix, `"catalog studio"` to Catalogix. An internal key like
+`"cxo-insights"` will render the **Streamoid** wordmark, not a text row.
+
+**4. The current app is not excluded.** The source comment is explicit — "The current
+app is expected to be excluded by the host." Forget the filter and the sidebar offers
+to switch to the app you're already in.
+
+**5. Hover is React state, not CSS.** Each row keeps `useState(hover)` and colours
+itself inline. So (a) there is no `:hover` rule to override from the host, and (b)
+the chevron has `opacity: 0` until a real `mouseenter` — it will be missing from
+snapshots and from any screenshot harness that fakes `:hover`.
+
+**6. There's no active/selected/disabled state.** No `selected`, no `disabled`, no
+loading row. Hosts that need a loading state render their own skeleton **instead of**
+the panel (CXO does exactly that).
+
+**7. It brings its own `paddingBottom: var(--spacing-md)`.** Host flyouts note this
+("applies its own bottom padding; don't double it"). Override via `style` if needed.
+
+**8. Row height is a hardcoded 60px** with design-literal padding
+(`15px 12px 12px 16px`). Long text rows do not grow — a two-line
+`name` + `description` at 16px/14px only just fits.
+
+**9. Everything is inline styles; there is no CSS module.** `className` gets you a
+hook on the root only, and inline styles beat your stylesheet — restyle by wrapping,
+not by targeting.
+
+**10. `aria-label` is hardcoded English** (`Switch to {name}`), as is the entire
+wordmark set. Not localisable without changing the DS.
+
+**11. The wordmark assets are not public API.** `STREAMOID`, `ARTIFAX`,
+`PHOTOGENIX`, `CATALOGIX`, `TACTIX` and `WordmarkAsset` live in
+`SC-AppSwitch/wordmarks.ts` but are **not** re-exported from `@streamoid/ui` (only
+`ScAppSwitchPanel`, `ScAppSwitchRow`, `ScAppSwitchItem`,
+`IScAppSwitchPanelProps` are). For a wordmark you can place yourself, use
+`ProductWordmark` from `SC-SideBarLogoUnit` — a different, path-based set.
+
+**12. `mask-image: url("data:image/svg+xml,…")`.** If your app ships a strict CSP,
+`img-src`/`default-src` must allow `data:` or the wordmarks render as blank boxes
+(the coloured background shows through nothing).
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/app-sidebar.tsx:901
+<ScAppSwitchPanel
+  apps={switchApps.map((app) => ({
+    key: app.key,
+    name: app.name,
+    description: app.desc,
+    onSelect: () => openSwitchApp(app.pageUrl),
+  }))}
+/>
+```
+
+Also: `catalogix/dashboard app/containers/LeftMenu/index.jsx:1002` (straight into
+`switchPanel`) and `artifax packages/shared/src/components/DashboardSidebar.tsx:1474`
+(inside the host's portalled `SwitchFlyout`).
+
+---
+
+## Related
+
+- `ScSideBarLogoUnit` — the row that opens this panel.
+- `StreamoidSidebar` — pass this as `switchPanel`; it handles both rails and the backdrop.
+- `ScArtifaxSidebar` — has **no** switch slot; portal the panel yourself.
+- `ScSidebarSwitchMenu` — the older per-row switcher, still used by `ScCatalogixSidebar`.
+- `ScWorkspaceSwitchCard` / `StreamoidWorkspaceSwitcher` — the workspace equivalent.
+- `ProductWordmark` (SC-SideBarLogoUnit) — the other, exported wordmark set.

package/dist/docs/ScAppcardLogos.md

@@ -0,0 +1,226 @@
+---
+component: ScAppcardLogos
+package: "@streamoid/ui"
+category: brand
+status: stable
+renders: span[role="img"]
+tags: [wordmark, logo, brand, product, tactix, artifax, photogenix, catalogix, svg, currentColor]
+related: [ScAppCardForCopilot, ProductWordmark, ProductCollapsedMark, ScStreamoidWordmark, ScStrLogo]
+do_not_confuse_with: [ProductWordmark, ScStreamoidWordmark, ScStreamoidMascot, ScCxoCopilotLogo, ScAppCard]
+used_by: [agent]
+required_props: [product]
+---
+
+# ScAppcardLogos
+
+**One single-colour product wordmark, 14px tall.** Inline SVG for Tactix, Artifax,
+Photogenix or Catalogix, filled with `currentColor` so the parent's text colour
+paints it. Ships the type `AppcardProduct` used by `ScAppCardForCopilot`.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a product's *name as artwork* — inside a card,
+  chip or pill where a hover/theme colour change should recolour the mark for free.
+- **Don't reach for it when:** you want the sidebar-header wordmark
+  (→ `ProductWordmark` / `ProductCollapsedMark`), the Streamoid brand
+  (→ `ScStreamoidWordmark` / `ScStreamoidMascot`), the CXO copilot mark
+  (→ `ScCxoCopilotLogo`), or an app icon plus a typed name (→ `ScAppCard`).
+- **Four things that will bite you:**
+  1. `product` is **required** and the set is exactly four keys — `tactix`,
+     `artifax`, `photogenix`, `catalogix`. **There is no Streamoid or CXO wordmark.**
+  2. Widths differ per product (56 / 54 / 88 / 72 px at a fixed 14px height), so a
+     row of them is **not** visually uniform.
+  3. It sets `role="img"` with **`aria-label={product}` — the raw lowercase key**
+     ("photogenix"), not a display name.
+  4. The SVG is injected with `dangerouslySetInnerHTML`. Safe here (the markup is a
+     compile-time constant), but it means you cannot target inner paths from a
+     parent stylesheet by anything other than element selectors.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScAppcardLogos, type AppcardProduct } from "@streamoid/ui";
+// No CSS import needed for this component — it styles itself inline.
+```
+
+### Minimal usage
+
+```tsx
+<ScAppcardLogos product="catalogix" />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `product` | `AppcardProduct` = `"tactix" \| "artifax" \| "photogenix" \| "catalogix"` | — | **Required.** Selects the wordmark. Also becomes `aria-label` verbatim. |
+| `color` | `string` | – | Sets `color` on the wrapper `<span>`; the SVG paths are `fill="currentColor"`, so this is how you tint the mark. Omit it and the mark inherits the surrounding text colour. |
+| `className` | `string` | – | Applied to the wrapper `<span>` (the usual place to set `height`, `flex-shrink`, or a hover colour). |
+| `style` | `CSSProperties` | – | Merged **after** the built-in `display: inline-flex; align-items: center; color` — so `style` can override `color`, and `style={{ display: "block" }}` works. |
+
+There is no props spread: `onClick`, `data-*`, `aria-hidden` etc. are not accepted.
+
+### Wordmark geometry
+
+| `product` | SVG width | SVG height |
+|---|---|---|
+| `tactix` | 56 | 14 |
+| `artifax` | 54 | 14 |
+| `photogenix` | 88 | 14 |
+| `catalogix` | 72 | 14 |
+
+### Recipes
+
+```tsx
+// Inherit the parent's colour — the idiomatic use. The mark follows a hover
+// transition on the parent for free, because it's currentColor all the way down.
+<button className="text-[var(--alias-text---icons-tertiary)] hover:text-[var(--alias-text---icons-primary)]">
+  <ScAppcardLogos product="photogenix" />
+</button>
+
+// Pin it white on a dark/glassy card (what ScAppCardForCopilot does)
+<ScAppcardLogos product="artifax" color="var(--alias-text---icons-fullwhite, #ffffff)" />
+
+// Scale it: the SVG has width/height attributes, so constrain via CSS, not props
+<ScAppcardLogos product="catalogix" style={{ height: 18 }} className="[&>svg]:h-full [&>svg]:w-auto" />
+
+// Iterate the whole set type-safely
+const PRODUCTS: AppcardProduct[] = ["tactix", "artifax", "photogenix", "catalogix"];
+{PRODUCTS.map((p) => <ScAppcardLogos key={p} product={p} />)}
+```
+
+---
+
+## 2. Where to use it
+
+- **`ScAppCardForCopilot`** renders it as the card's identity, pinned white with a
+  14px height.
+- **The agent's empty chat state** (`stream-agent`) renders it directly inside
+  hand-rolled dashed-border product pills — the wordmark is tertiary by default and
+  goes primary on hover purely via `currentColor`.
+- Any **compact "which product" affordance** on a dark or coloured surface where a
+  wordmark reads better than an icon + label.
+
+Generated from Figma `AppcardLogos` (node `6383:9997`); the SVG strings live in
+`SC-AppcardLogos/sources.ts` and are auto-generated — **do not hand-edit them**.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The mark must **recolour with its context** (hover, theme, inverse surface) and
+  you do not want to ship two PNGs.
+- Space is tight and 14px of wordmark is the whole identity.
+- You need the `AppcardProduct` union to key your own product data.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A sidebar header's product wordmark (expanded state) | `ProductWordmark` |
+| A collapsed sidebar's square product mark | `ProductCollapsedMark` (check `hasCollapsedMark`) |
+| The Streamoid wordmark (98:32) or mascot | `ScStreamoidWordmark` / `ScStreamoidMascot` (SC-Brand) |
+| The plain header Streamoid lockup vs the app-switcher lockup | `ScStreamoidWordmark` (SC-Brand) — those two sizes are distinct, don't conflate |
+| The CXO Copilot logo | `ScCxoCopilotLogo` |
+| The generic Streamoid `S` logo | `ScStrLogo` |
+| An app *icon* (not the name) plus a typed label | `ScAppCard` / `ScAppListingCard` with an `Sicon*` |
+| A whole clickable product card | `ScAppCardForCopilot` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ProductWordmark` — the sidebar wordmark set, sized for the shell header | `ScAppcardLogos` is the 14px *appcard* set; different sizes, different Figma source |
+| `ScStreamoidWordmark` — the company mark | This set has **no** Streamoid entry |
+| `ScAppCard` — icon + name + subtitle row | This is only the name, as vector art |
+
+---
+
+## 4. Why to use it
+
+- **One asset, every colour.** `fill="currentColor"` inline SVG means the mark
+  inherits hover, focus, theme and inverse-surface colours with no second asset and
+  no `filter: invert()` hack.
+- **Inline, not `<img>`** — deliberately, per the source comment: an `<img>` cannot
+  pick up `currentColor`, so the wordmark would need a per-theme file.
+- **No network request, no flash.** The SVG is compiled into the bundle, so the
+  mark is painted on first render (important in the agent's empty state, which is
+  the first thing a user sees).
+- **The `AppcardProduct` union is the single source of truth** for "which products
+  have an appcard wordmark", and it is derived from the wordmark map itself — add a
+  product to `sources.ts` and every consumer's types widen automatically.
+- **`role="img"` + a label** means assistive tech announces a product rather than
+  skipping an unlabelled decorative span.
+
+---
+
+## Gotchas
+
+**1. Only four products exist.** `product="streamoid"` is a type error, and there is
+no CXO mark here.
+
+```tsx
+// WRONG — not in the union
+<ScAppcardLogos product="streamoid" />
+
+// RIGHT
+<ScStreamoidWordmark />
+```
+
+**2. `aria-label` is the raw key.** Screen readers say "photogenix", lowercase. If
+the surrounding control needs a nicer name, label the control itself — you cannot
+override the span's label (no props spread).
+
+**3. Uneven widths.** Photogenix is 88px wide, Artifax 54px. A flex row of the four
+marks will look ragged; add `justify-content` / fixed-width slots if the design
+expects a grid. `ScAppCardForCopilot` inherits this — its `width: fit-content` cards
+come out different widths per product.
+
+**4. `size` does not exist.** Unlike `Sicon*`, there is no size prop. The inner SVG
+carries hardcoded `width`/`height` attributes, so scaling requires CSS on the SVG
+itself (`[&>svg]{height:100%;width:auto}` or similar), not just a height on the span.
+
+**5. `style` beats `color`.** The wrapper's inline style is
+`{ display: "inline-flex", alignItems: "center", color, ...style }` — a `color` inside
+`style` silently wins over the `color` prop. Pick one.
+
+**6. `APPCARD_WORDMARKS` is not exported.** Only `ScAppcardLogos` and the
+`AppcardProduct` type are public. Do not try to import the raw SVG map from
+`@streamoid/ui`; if you need the list of products, iterate a literal array typed as
+`AppcardProduct[]`.
+
+**7. Don't hand-edit `sources.ts`.** It is auto-generated from Figma and its four
+wordmark lines each contain a very large inline SVG string — grep it, never open it
+whole, and regenerate rather than patch.
+
+---
+
+## In the wild
+
+```tsx
+// stream-agent  frontend/src/components/chat/EmptyChat.tsx:228
+<ScAppcardLogos product={p.product} className="shrink-0" />
+```
+
+No host render site found in cxo / photogenix / catalogix / artifax — the call site
+above is the **agent runtime** (`used_by: [agent]`).
+Inside the DS it is composed by `ScAppCardForCopilot`
+(`packages/ui/src/SC-AppCardForCopilot/ScAppCardForCopilot.tsx:36`). If a host
+dashboard ever needs it, the natural home is a product-switcher chip or an
+empty-state "jump to product" row.
+
+---
+
+## Related
+
+- `ScAppCardForCopilot` — the dark glassy card built around this wordmark.
+- `ProductWordmark` / `ProductCollapsedMark` — the sidebar-shell wordmark set.
+- `ScStreamoidWordmark` / `ScStreamoidMascot` — company marks (both live in SC-Brand).
+- `ScCxoCopilotLogo` / `ScStrLogo` — CXO and Streamoid logo marks.
+- `@streamoid/icons` — `Sicon*` product/feature icons, when you want a glyph not a wordmark.