@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScStoreCard.md

@@ -0,0 +1,252 @@
+---
+component: ScStoreCard
+package: "@streamoid/ui"
+category: cards
+status: stable
+renders: div
+tags: [card, store, tile, listing, grid, beacon, status, products, catalogix]
+related: [ScBeacon, ScHDivider, ScCatalogixStoreHeader, ScCatalogixStoreTableList, ScDefaultCard]
+do_not_confuse_with: [ScCatalogixStoreTableList, ScDefaultCard, ScAppListingCard, ScWorkspaceCard]
+used_by: [catalogix]
+---
+
+# ScStoreCard
+
+**One store in the Catalogix stores grid.** A two-line-clamped store name on top, a
+hairline divider, then a footer row: status beacon, product count on the left, and
+the creation date pushed right. Scales up 1% on hover.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are rendering the **grid** view of a stores listing and
+  each tile is name + status + counts + date.
+- **Don't reach for it when:** you are rendering the **list** view of the same data
+  (→ `ScCatalogixStoreHeader` + `ScCatalogixStoreTableList`), or the card is a
+  generic "choose an option" box (→ `ScDefaultCard`).
+- **Four things that will bite you:**
+  1. Every content prop has a real default — a bare `<ScStoreCard />` renders
+     `"Store Name"`, `"1490 Products"`, `"24th Jan 2026"`.
+  2. `noOfProducts` and `dateCreated` are **pre-formatted strings**, including the
+     word "Products" and the date format. The card does no formatting.
+  3. The name block has a **fixed `height: 3.5rem`** with a 2-line clamp, so short
+     names still reserve two lines (good for grid alignment, surprising in a
+     one-off).
+  4. The CSS styles `:focus-visible` but the component sets **no `tabIndex`** — you
+     must add `role="button" tabIndex={0} onKeyDown` for that styling to ever fire.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScStoreCard } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScStoreCard
+  storeName="SS26 Womenswear"
+  noOfProducts="1490 Products"
+  dateCreated="24th Jan 2026"
+  tone="success"
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `storeName` | `string` | `"Store Name"` | ⚠️ Real default. `lead-text-xs-regular`, clamped to 2 lines in a fixed 3.5rem block, and wired to a native `title` tooltip so the clipped text is still readable on hover. |
+| `noOfProducts` | `string` | `"1490 Products"` | ⚠️ Real default, **including the unit word**. Left-aligned, `flex: 1`, single-line ellipsised. |
+| `dateCreated` | `string` | `"24th Jan 2026"` | ⚠️ Real default. Right-aligned, `flex-shrink: 0`, single-line ellipsised. |
+| `tone` | `ScBeaconTone` = `"success" \| "warning" \| "error" \| "neutral"` | `"neutral"` | Colour of the 20px `ScBeacon` dot in the footer. `neutral` = muted grey. |
+| `className` | `string` | – | Appended after the internal class (guarded — no stray `undefined` class). |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `onClick`, `role`, `tabIndex`, `onKeyDown`, `style`, `aria-*`, `data-*` land on the root div. |
+
+### Tone semantics
+
+| `tone` | Beacon colour token | Typical meaning in a stores grid |
+|---|---|---|
+| `success` | `--alias-text-and-icons-success` | Store live / feed healthy |
+| `warning` | `--alias-text-and-icons-warning` | Processing / partial |
+| `error` | `--alias-text-and-icons-error` | Failed / status fetch failed |
+| `neutral` | `--alias-text-and-icons-muted` | Unknown / not yet reported (the default) |
+
+### Recipes
+
+```tsx
+// The Catalogix idiom — grid view, fully keyboard reachable
+<div className="stores-grid">
+  {stores.map((store) => {
+    const meta = getStoreMeta(store);           // derives label strings + tone
+    return (
+      <ScStoreCard
+        key={store._id}
+        storeName={store.name}
+        noOfProducts={meta.productCountLabel}   // e.g. "1490 Products" / "—"
+        dateCreated={meta.dateLabel}
+        tone={meta.tone}
+        role="button"
+        tabIndex={0}
+        onClick={() => openStore(store)}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") { e.preventDefault(); openStore(store); }
+        }}
+      />
+    );
+  })}
+</div>
+
+// Loading / failed metadata — the card takes whatever string you give it
+<ScStoreCard storeName={store.name} noOfProducts="Loading…" dateCreated="—" tone="neutral" />
+```
+
+---
+
+## 2. Where to use it
+
+- **Catalogix `StoresListing`, grid view.** The same screen's list view swaps to
+  `ScCatalogixStoreHeader` + `ScCatalogixStoreTableList` from the same `getStoreMeta`
+  data — keep the two branches fed identically.
+- Any future **"collection of containers" grid** (stores, catalogues, feeds) where a
+  tile is a name plus two metrics and a status dot.
+
+It composes `ScBeacon` (the status dot) and `ScHDivider` (the hairline between name
+and footer) from the DS; everything else is its own CSS.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The user is **choosing which store to open**, and the tile's job is identity plus
+  at-a-glance health.
+- You are in a grid and want **uniform tile heights** without measuring — the fixed
+  name block gives you that for free.
+- The status is a single dot, not a labelled chip.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The list/table view of the same stores | `ScCatalogixStoreHeader` + `ScCatalogixStoreTableList` |
+| A generic table row | `ScTableHeader` + `ScTableList` (`ScTableListMobile` on mobile) |
+| A generic "pick one option" card | `ScDefaultCard` |
+| A product/app tile with an icon chip | `ScAppListingCard` |
+| A workspace, not a store | `ScWorkspaceSwitchCard` / `StreamoidWorkspaceSwitcher` |
+| A labelled status chip rather than a dot | `ScBadges` |
+| The status dot alone, in your own layout | `ScBeacon` |
+| A feed source→target mapping row | `ScMappingCard` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScCatalogixStoreTableList` — the row form of a store, with the header component | `ScStoreCard` is the grid form; same data, different view |
+| `ScDefaultCard` — centred title + hint, no footer, no divider, no beacon | This card has a name block, divider and metrics footer |
+| `ScWorkspaceCard` — workspace identity with badges and buttons | Different entity, different (legacy) component |
+| `ScAppListingCard` — icon + title + description product tile | No icon here; the beacon is the only glyph |
+
+---
+
+## 4. Why to use it
+
+- **Grid alignment without measuring.** The `height: 3.5rem` + `-webkit-line-clamp: 2`
+  name block means every tile is the same height regardless of name length — the
+  usual reason hand-rolled store grids look ragged.
+- **The clipped name still has a tooltip.** `title={storeName}` is wired internally,
+  so a two-line-clamped name is recoverable on hover. Easy to forget by hand.
+- **Status colour comes from `ScBeacon`**, i.e. from
+  `--alias-text-and-icons-success/warning/error/muted` — the same four colours every
+  other status in the product uses, and `aria-hidden` so it does not pollute the
+  accessible name.
+- **Hover survives light mode.** Background (`base` → `basesubtle`), border
+  (`subtle` → `default`) *and* `transform: scale(1.01)` all change together; because
+  light mode collapses the surfaces to white, the border and the scale are what keep
+  the hover legible.
+- **`overflow: hidden` + 1.125rem radius** means the divider and footer can never
+  poke past the rounded corners.
+
+---
+
+## Gotchas
+
+**1. Placeholder defaults are real content.** `"Store Name"`, `"1490 Products"` and
+`"24th Jan 2026"` will ship if you forget a prop — and `"1490 Products"` looks
+plausible enough to survive review.
+
+**2. You format, the card renders.** `noOfProducts` includes the unit; `dateCreated`
+includes the date format. There is no number or date formatting inside.
+
+```tsx
+// WRONG — renders the bare number with no unit
+<ScStoreCard storeName={s.name} noOfProducts={String(s.count)} />
+
+// RIGHT
+<ScStoreCard storeName={s.name} noOfProducts={`${s.count} Products`} />
+```
+
+**3. `overflow: hidden` on the root clips popovers.** A kebab menu or tooltip opened
+from inside the card gets cut off. Portal it to `document.body` with an explicit
+z-index, or place the trigger outside the card.
+
+**4. `:focus-visible` styling is dead until you add `tabIndex`.** The CSS defines a
+focus-visible skin (same as hover, outline removed), but the component ships no
+`tabIndex` and no key handling. Add `role="button" tabIndex={0} onKeyDown` — the
+Catalogix call site does exactly this.
+
+**5. `cursor: pointer` is unconditional.** A read-only card still looks clickable.
+Override with `style={{ cursor: "default" }}` when there is no `onClick`.
+
+**6. `transform: scale(1.01)` on hover.** Small, but it does lift the tile over its
+neighbours with no `z-index` management. Keep grid gaps ≥ 12px.
+
+**7. The name block reserves two lines even for one-word names.** Correct in a grid,
+odd if you render a single card in a sidebar. There is no prop to collapse it.
+
+**8. `tone` defaults to `neutral`, not `success`.** A store whose status you have not
+fetched yet shows a grey dot — which is right, but means "no tone passed" reads as
+"unknown", not "healthy".
+
+**9. The beacon is `aria-hidden`.** Screen readers get name + counts + date only. If
+status matters for accessibility, add an `aria-label` on the card or a visually
+hidden status string.
+
+---
+
+## In the wild
+
+```tsx
+// catalogix/dashboard  app/containers/StoresListing/index.jsx:354
+<ScStoreCard
+  key={store._id}
+  storeName={store.name}
+  noOfProducts={meta.productCountLabel}
+  dateCreated={meta.dateLabel}
+  tone={meta.tone}
+  role="button"
+  tabIndex={0}
+  onClick={() => openStore(store)}
+  onKeyDown={(e) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      openStore(store);
+    }
+  }}
+/>
+```
+
+---
+
+## Related
+
+- `ScBeacon` — the status dot this card renders; use it standalone in your own rows.
+- `ScHDivider` — the hairline between name and footer.
+- `ScCatalogixStoreHeader` / `ScCatalogixStoreTableList` — the list-view twin of this card.
+- `ScDefaultCard` — generic option card when there is no store metadata.
+- `ScBadges` — a labelled status chip when a dot is not enough.

package/dist/docs/ScStrLogo.md

@@ -0,0 +1,253 @@
+---
+component: ScStrLogo
+package: "@streamoid/ui"
+category: brand
+status: legacy
+renders: svg
+tags: [logo, wordmark, streamoid, mascot, lockup, brand, legacy, 626x60]
+related: [ScStreamoidWordmark, ScStreamoidMascot, ScSideBarLogoUnit, ScLogoUnit, ScAppcardLogos]
+do_not_confuse_with: [ScStreamoidWordmark, ScStreamoidMascot, ScLogoUnit, ScSideBarLogoUnit, ScAppcardLogos]
+---
+
+# ScStrLogo
+
+**The legacy Streamoid corporate lockup: the "streamoid" wordmark *and* the mascot
+in one 626×60 SVG.** One inert `<svg>` with hardcoded `width="626" height="60"`;
+the letterforms are painted with a text token, and the mascot half mixes a fixed
+teal→purple gradient (two arcs) with a third arc painted in that same text token.
+
+> **Legacy.** For new work use `ScStreamoidWordmark` (110×16 wordmark) and
+> `ScStreamoidMascot` (the glyph alone), passed into `ScSideBarLogoUnit`. Its only
+> in-library consumer is `ScLogoUnit`, which is itself superseded by
+> `ScSideBarLogoUnit` / `StreamoidSidebar`. It is not marked `@deprecated` in the
+> source, so it still compiles and ships — it simply isn't the current path.
+
+## TL;DR for agents
+
+- **Reach for it when:** you specifically need the **combined** wordmark + mascot
+  lockup at large size (a splash / auth / print-ish surface), and you are willing
+  to size it yourself. That combination exists nowhere else in the library.
+- **Don't reach for it when:** you're filling a sidebar header (→
+  `ScSideBarLogoUnit` with `ScStreamoidWordmark` / `ScStreamoidMascot`), you want
+  just the wordmark (→ `ScStreamoidWordmark`), or just the mascot (→
+  `ScStreamoidMascot`).
+- **Four things that will bite you:**
+  1. It renders **626px wide** by default and will blow out any normal container.
+     There is no size prop — you must override width/height via `className`.
+  2. `type="logo-only"` does **not** hide the wordmark. It just shrinks the whole
+     lockup into a 163px box.
+  3. Every prop except `type` and `className` is dropped — `...props` is
+     destructured and never spread, and the interface doesn't extend
+     `HTMLAttributes`.
+  4. The gradient `id` is **hardcoded**, so two instances on a page produce
+     duplicate DOM ids.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScStrLogo } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+// Renders at 626×60 — almost always too big. Size it with a class.
+<ScStrLogo className="myLogo" />
+```
+
+```css
+/* your stylesheet — the only way to size it */
+.myLogo { width: 167px; height: 16px; }
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `type` | `"default"` \| `"logo-only"` | `"default"` | Adds `.type-default` / `.type-logo-only`. ⚠️ `logo-only` only constrains the box to `163×60` + `aspect-ratio: 163/60` — it does **not** clip to the mascot (Gotcha 2). |
+| `className` | `string` | – | Concatenated after the internal classes. **The only way to change its size.** |
+| `...props` | — | – | ⚠️ Destructured but **never spread**. `onClick`, `style`, `id`, `aria-*` are also type errors — the props interface does not extend `React.SVGProps`/`HTMLAttributes`. |
+
+### What each `type` actually does
+
+| `type` | CSS applied | Rendered result |
+|---|---|---|
+| `"default"` | `height: 3.75rem` (60px); width comes from the SVG's own `width="626"` | Full lockup, 626×60 |
+| `"logo-only"` | `height: 3.75rem`, `width: 10.1875rem` (163px), `aspect-ratio: 163/60` | The **same** full lockup, uniformly scaled down to ~163×15.6 and vertically centred in a 60px box |
+
+### Recipes
+
+```tsx
+// Splash / auth screen — one clear legitimate use, sized by a wrapper class
+<div className="authBrand">
+  <ScStrLogo />
+</div>
+```
+
+```css
+.authBrand :global(svg) { width: 313px; height: 30px; } /* keep 626:60 */
+```
+
+```tsx
+// What you almost certainly want instead
+<ScStreamoidWordmark width={165} height={24} />   {/* wordmark only  */}
+<ScStreamoidMascot size={40} />                   {/* mascot only    */}
+```
+
+---
+
+## 2. Where to use it
+
+- **Historically:** inside `ScLogoUnit`, which wrapped it in a 240px padded sidebar
+  box and forced it down to `167×16` (expanded) or `32×12` (collapsed) with
+  `!important` width/height overrides. That pair was the pre-`StreamoidSidebar`
+  sidebar header.
+- **Today:** nothing renders it in any host app. The sidebar header is
+  `ScSideBarLogoUnit`; large-format brand surfaces are better served by
+  `ScStreamoidWordmark` at an explicit size.
+
+Photogenix evaluated `ScLogoUnit`/`ScStrLogo` during its DS migration and
+deliberately rejected them — the corporate lockup would have erased the *product*
+wordmark that distinguishes each app (`dashboard/docs/archive/Migration-leftout.md`).
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You genuinely need **wordmark + mascot together** as a single mark, at a size
+  where both are legible (≥ ~200px wide), and you can supply the sizing CSS.
+- You are maintaining an existing `ScLogoUnit` call site and don't want to migrate
+  it yet.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Sidebar header, expanded | `ScSideBarLogoUnit` + `ScStreamoidWordmark` |
+| Sidebar header, collapsed | `ScSideBarLogoUnit state="collapsed"` + `ScStreamoidMascot` |
+| Wordmark on its own, any size, theme-correct | `ScStreamoidWordmark` (`width`/`height`/`color` props) |
+| Mascot glyph on its own | `ScStreamoidMascot` (`size` prop) |
+| A **product** wordmark (Artifax / Photogenix / Catalogix / Tactix) | `ScAppcardLogos` or `ScSideBarLogoUnit product="…"` |
+| The CXO Copilot lockup | `ScCxoCopilotLogo` |
+| A clickable logo | `ScSideBarLogoUnit`, or your own `<button>` wrapper — this svg takes no handlers |
+| Anything that must be recoloured per surface | `ScStreamoidWordmark` (`color` prop) — `ScStrLogo` has no colour prop |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScStreamoidWordmark` — 110×16 plain wordmark, mask-painted by a token, `width`/`height`/`color` props | `ScStrLogo` is the 626×60 wordmark **+ mascot**, unsizeable by prop |
+| `ScStreamoidMascot` — the mascot alone, `size` prop, unique gradient id per instance | `ScStrLogo` always includes the wordmark and reuses one hardcoded gradient id |
+| `ScLogoUnit` — the padded 240px **container** that renders `ScStrLogo` | Also legacy; the current container is `ScSideBarLogoUnit` (capital **B**) |
+| `ScSideBarLogoUnit` — the current interactive sidebar header row | `ScStrLogo` is an inert mark |
+| `ScAppcardLogos` — per-product wordmarks | Contains no Streamoid entry |
+
+---
+
+## 4. Why to use it
+
+Honestly: mostly for continuity. What it does give you:
+
+- **The only combined lockup in the library** — wordmark and mascot in one mark,
+  in the correct relative proportions.
+- **Theme-aware letterforms.** The ten letterform paths are filled with
+  `--alias-text-and-icons-primary` (an alias of `--alias-text---icons-primary`),
+  so the wordmark half flips with the theme instead of staying #F5F5F5. Of the
+  mascot's three arcs, only two carry the brand gradient (`paint0_linear_19_1153`);
+  the right-hand arc is filled with that same text token — an eleventh token-filled
+  path — so part of the glyph flips with the theme too.
+- **No asset shipping.** Same argument as the rest of SC-Brand: hosts carry no
+  brand SVGs. (CXO still has two hand-exported copies at
+  `src/app/components/strLogo/` that nothing imports — that's the mess this exists
+  to end.)
+
+What you *don't* get, and why `ScStreamoidWordmark` superseded it: no size props,
+no colour prop, no per-instance gradient id, no a11y wiring, no event props.
+
+---
+
+## Gotchas
+
+**1. It is 626px wide until you say otherwise.** The `<svg>` carries
+`width="626" height="60"`, and the CSS sets only `height: 3.75rem`. Dropping it
+into a sidebar or card will overflow.
+
+```tsx
+// WRONG — 626px wide inside a 240px rail
+<ScStrLogo />
+
+// RIGHT — constrain it, keeping the 626:60 ratio
+<ScStrLogo className={styles.brand} />   /* .brand { width: 167px; height: 16px } */
+```
+
+**2. `type="logo-only"` is a misnomer.** It applies `width: 163px` +
+`aspect-ratio: 163/60`; the SVG's default `preserveAspectRatio` then scales the
+*entire* 626-unit viewBox down to fit that width (≈163×15.6, vertically centred).
+The wordmark is still there, just tiny. For the mascot alone use
+`ScStreamoidMascot`.
+
+**3. All other props are silently dropped.**
+
+```tsx
+// WRONG — both are type errors, and even with a cast nothing is spread onto the svg
+<ScStrLogo onClick={goHome} style={{ width: 200 }} />
+
+// RIGHT
+<button type="button" onClick={goHome} aria-label="Home" className={styles.brandBtn}>
+  <ScStrLogo />
+</button>
+```
+
+**4. The gradient id is hardcoded** (`paint0_linear_19_1153`). Render two
+`ScStrLogo`s and the document contains two elements with the same `id`; every
+instance resolves `url(#paint0_linear_19_1153)` to the *first* one, so unmounting
+that first instance can strip the gradient from the rest. `ScStreamoidMascot` and
+`ScCxoCopilotLogo` avoid this with `useId()`.
+
+**5. Omitting `className` puts the literal string `undefined` in the class
+attribute.** `className={styles.scStrLogo + " " + className + " " + variantsClassName}`
+is unguarded, so you get `class="ScStrLogo_scStrLogo undefined ScStrLogo_type-default"`.
+Harmless visually, but don't write selectors or tests against the class list.
+
+**6. No `role`, no `aria-label`, no `<title>`, and not `aria-hidden`.** It is
+neither properly labelled nor properly hidden. Add `aria-hidden` on a wrapper if
+it's decorative, or label the wrapper if it carries meaning.
+
+**7. `.vector` in the stylesheet is dead code.** The CSS defines
+`.type-default .vector` / `.type-logo-only .vector`, but the component never
+renders an element with that class. Don't try to target it.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+Composed internally by the legacy `ScLogoUnit`:
+
+```tsx
+// @streamoid/ui  packages/ui/src/SC-Logo unit/ScLogoUnit.tsx:20
+<ScStrLogo type="default" className={styles.scStrLogoInstance} />
+// .scStrLogoInstance forces width: 10.4375rem !important; height: 1rem !important
+```
+
+Where it would belong if revived: a full-bleed brand surface (sign-in, splash,
+error page) at ≥200px wide. Every sidebar/header slot in every host app is now
+`ScSideBarLogoUnit` + `ScStreamoidWordmark`/`ScStreamoidMascot`.
+
+---
+
+## Related
+
+- `ScStreamoidWordmark` — the current wordmark; `width`/`height`/`color` props, token-masked.
+- `ScStreamoidMascot` — the mascot alone; unique gradient id per instance.
+- `ScSideBarLogoUnit` — the current sidebar header row (takes a `wordmark` node).
+- `ScLogoUnit` — the legacy container that renders this; superseded by `ScSideBarLogoUnit`.
+- `ScAppcardLogos` — per-product wordmarks, when you want the app's name not the company's.