@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScLogoUnit.md

@@ -0,0 +1,232 @@
+---
+component: ScLogoUnit
+package: "@streamoid/ui"
+category: sidebar
+status: legacy
+renders: div
+tags: [sidebar, logo, wordmark, header, brand, streamoid, legacy, logo-unit]
+related: [ScSideBarLogoUnit, ScStrLogo, ScStreamoidWordmark, ScStreamoidMascot, StreamoidSidebar]
+do_not_confuse_with: [ScSideBarLogoUnit, ScStrLogo, ScStreamoidWordmark, ScStreamoidMascot, ScCxoCopilotLogo, ScAppcardLogos]
+---
+
+# ScLogoUnit
+
+**Legacy. Superseded by `ScSideBarLogoUnit`.** A fixed-width 240 px padded box holding
+the full Streamoid wordmark (`ScStrLogo`). No product branding, no click target, no
+app-switcher chevron — and its "collapsed" state squeezes the *whole wordmark* into a
+32 × 12 px sliver instead of showing a product mark.
+
+## TL;DR for agents
+
+- **Reach for it when:** never. It cannot be clicked and cannot show a product.
+- **Reach for this instead:** `ScSideBarLogoUnit` (product wordmark + switcher chevron
+  + `onClick` + `hover`/`disabled` + a11y label), which is what every current sidebar
+  passes into `StreamoidSidebar`'s `expandedLogo` / `collapsedLogo` slots.
+- **Three things that will bite you:**
+  1. ⚠️ **`...props` is destructured and never spread.** No `onClick`, no `style`, no
+     `data-*`. The interface doesn't extend `HTMLAttributes` either.
+  2. Hardcoded `width: 15rem` (240 px) when expanded. It does not adapt to its rail.
+  3. `state="collapsed"` still renders the **full "Streamoid" wordmark**, scaled to
+     32 × 12 px. It is not a logo mark — it is an unreadable smear.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScLogoUnit } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+// This is the whole API.
+<ScLogoUnit state="expanded" />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `state` | `"expanded"` \| `"collapsed"` | `"expanded"` | `expanded` = 240 px wide, 16 px padding, wordmark at 167 × 16. `collapsed` = 48 × 48 box, 8 px padding, wordmark at 32 × 12. |
+| `className` | `string` | – | Concatenated onto the root. ⚠️ Unguarded — omitting it puts a literal `undefined` in the class list. |
+| `...props` | – | – | ⚠️ **Destructured and discarded.** `IScLogoUnitProps` does **not** extend `React.HTMLAttributes`, so there is no supported way to attach `onClick`, `style` or `aria-*`. |
+
+The child is a hardcoded `<ScStrLogo type="default" />` — the Streamoid wordmark SVG.
+There is no `product`, `wordmark` or `children` prop.
+
+### What renders in each state
+
+| | `expanded` | `collapsed` |
+|---|---|---|
+| Box | `width: 15rem` (240 px), 16 px padding | 48 × 48, 8 px padding, contents centred |
+| Wordmark | `ScStrLogo` at 167 × 16 (`aspect-ratio: 167/16`) | the **same** wordmark at 32 × 12 (`aspect-ratio: 32/12`) |
+| Colour | the SVG paths are filled with `--alias-text-and-icons-primary`, so it flips with the theme | same |
+
+### Recipes
+
+None. Here is the replacement:
+
+```tsx
+// Expanded rail header: product wordmark + app-switcher chevron, one click target
+<ScSideBarLogoUnit
+  product="CXO"                        // "CXO" | "Catalogix" | "Artifax" | "Photogenix" | "Tactix"
+  onClick={() => setAppListOpen((v) => !v)}
+  switchAriaLabel="Switch product"
+/>
+
+// Collapsed rail header: the square product icon
+<ScSideBarLogoUnit
+  state="collapsed"
+  product="CXO"
+  onClick={() => setAppListOpen((v) => !v)}
+/>
+
+// Wired into the current shell
+<StreamoidSidebar
+  expanded={expanded}
+  onToggle={() => setExpanded((v) => !v)}
+  config={config}
+  iconMap={iconMap}
+  expandedLogo={<ScSideBarLogoUnit product="CXO" onClick={openSwitcher} />}
+  collapsedLogo={<ScSideBarLogoUnit state="collapsed" product="CXO" onClick={openSwitcher} />}
+  switchPanel={<ScAppSwitchPanel apps={apps} />}
+  switchPanelOpen={appListOpen}
+  onSwitchPanelClose={() => setAppListOpen(false)}
+/>
+
+// If you only want the Streamoid mark itself, skip the wrapper entirely
+<ScStreamoidWordmark width={110} height={16} />
+<ScStreamoidMascot size={24} />
+```
+
+---
+
+## 2. Where to use it
+
+Nowhere. Its only render site is the legacy `ScSidebar`
+(`src/SC-Sidebar/ScSidebar.tsx:37` collapsed, `:154` expanded), which is itself unused.
+
+The current rail header is `ScSideBarLogoUnit`, passed into `StreamoidSidebar`'s
+`expandedLogo` / `collapsedLogo`. CXO, Photogenix, Catalogix and Artifax all do this.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Never.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The sidebar's logo + product-switch header row | `ScSideBarLogoUnit` |
+| The whole rail, with the logo slotted in | `StreamoidSidebar` (`expandedLogo` / `collapsedLogo`) |
+| Just the Streamoid wordmark, sized by you | `ScStreamoidWordmark` (`width`, `height`, `color`) |
+| Just the Streamoid mascot/monogram | `ScStreamoidMascot` (`size`) |
+| The raw legacy wordmark SVG | `ScStrLogo` (`type: "default" \| "logo-only"`) |
+| A product wordmark in a page header | `ProductWordmark` / `ProductCollapsedMark` |
+| A product logo inside an app card | `ScAppcardLogos` |
+| The CXO Copilot lockup | `ScCxoCopilotLogo` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSideBarLogoUnit` — the current header row: `product`/`wordmark`, `onClick`, `onSwitchClick`, `switchAriaLabel`, `hideSwitch`, `hover`, `disabled` | `ScLogoUnit` has `state` and `className`, full stop |
+| `ScStreamoidWordmark` — the current brand wordmark component (110 × 16 header size) | `ScLogoUnit` embeds the older `ScStrLogo` SVG |
+| `ScStreamoidMascot` — the square monogram, which is what a *collapsed* rail actually wants | `ScLogoUnit state="collapsed"` shows a 32 px-wide full wordmark |
+| `ScStrLogo` — the bare SVG with no padding box | `ScLogoUnit` is `ScStrLogo` + a 240 px box |
+
+The names are one word apart: **`ScLogoUnit`** (legacy, Streamoid-only, inert) vs
+**`ScSideBarLogoUnit`** (current, per-product, clickable). Autocomplete will offer both.
+
+---
+
+## 4. Why to use it
+
+You wouldn't. What it still gets right:
+
+- The wordmark SVG's paths are filled with `var(--alias-text-and-icons-primary)`, so
+  the logo inverts correctly between dark and light mode with no conditional.
+- `aspect-ratio` is pinned in both states, so the mark never distorts when the box
+  is squeezed.
+
+What you lose versus `ScSideBarLogoUnit`: the product wordmark, the switcher chevron,
+the single unified click target, hover/disabled states, and the `switchAriaLabel`
+accessible name.
+
+---
+
+## Gotchas
+
+**1. It is completely inert.** `...props` is destructured out and never spread onto the
+root `<div>`, and the props interface doesn't extend `HTMLAttributes`. You cannot make
+it clickable, cannot pass `style`, cannot pass `aria-*`.
+
+```tsx
+// WRONG — does not compile, and would be dropped anyway
+<ScLogoUnit onClick={openAppSwitcher} />
+
+// RIGHT
+<ScSideBarLogoUnit product="CXO" onClick={openAppSwitcher} />
+```
+
+**2. Hardcoded 240 px width.** `.scLogoUnit { width: 15rem }` in the expanded state.
+`StreamoidSidebar`'s expanded rail is 16 rem wide with 8 px padding, so this box
+overflows it. And since `style` is dropped (Gotcha 1) you can only fix it with a
+`className` override.
+
+**3. "Collapsed" is not a logo mark.** It renders the same full wordmark at
+`width: 2rem; height: 0.75rem`. Every current rail shows a square product icon there
+instead — `ScSideBarLogoUnit state="collapsed"`, or `ScStreamoidMascot`.
+
+**4. Streamoid-only.** `ScStrLogo type="default"` is hardcoded. There is no way to show
+CXO, Catalogix, Artifax, Photogenix or Tactix branding.
+
+**5. `className` produces a literal `undefined` class when omitted.**
+`styles.scLogoUnit + " " + className + " " + variantsClassName`.
+
+**6. Padding, not gap, does the spacing.** Expanded uses 16 px padding on all four
+sides; collapsed drops to 8 px and centres. If you nest it in a rail that also pads,
+the logo drifts out of alignment with the nav rows below it.
+
+**7. Don't pass the app switcher next to it.** The whole reason
+`StreamoidSidebar` grew `switchPanel` / `switchPanelOpen` is that rendering an app list
+inline beside the logo pushes the nav down. Use the overlay slot.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+Composed only inside the legacy sidebar:
+
+```tsx
+// npm-components  packages/ui/src/SC-Sidebar/ScSidebar.tsx:154
+<ScLogoUnit className={styles.scLogoUnitInstance}></ScLogoUnit>
+```
+
+Where it *would* belong — the rail header — is now `ScSideBarLogoUnit`, passed into
+`StreamoidSidebar`'s `expandedLogo` / `collapsedLogo` (see
+`cxo-dashboard src/app/components/app-sidebar.tsx`).
+
+---
+
+## Related
+
+- `ScSideBarLogoUnit` — **the replacement.** Product wordmark + switcher, clickable.
+- `StreamoidSidebar` — the shell with `expandedLogo` / `collapsedLogo` slots.
+- `ScStreamoidWordmark` / `ScStreamoidMascot` (`SC-Brand`) — the current brand marks.
+  The plain header wordmark (110 × 16) and the app-switcher lockup are different
+  things; don't conflate them.
+- `ScStrLogo` — the raw legacy wordmark SVG this component wraps.
+- `ScAppcardLogos` / `ProductWordmark` / `ScCxoCopilotLogo` — other branded marks.
+- `ScSidebar` / `ScSidebarProfile` / `ScSidebarIcons` / `ScVersion` — the rest of this
+  legacy sidebar family.

package/dist/docs/ScMappingCard.md

@@ -0,0 +1,241 @@
+---
+component: ScMappingCard
+package: "@streamoid/ui"
+category: feed-taxonomy
+status: stable
+renders: div
+tags: [feed, mapping, map-attributes, column, source-target, catalogix, slot]
+related: [ScValueMappingL1, ScDefaultCard, ScSelect, ScTaxonomyPill]
+do_not_confuse_with: [ScValueMappingL1, ScDefaultCard, ScTableList]
+used_by: [catalogix]
+required_props: [columnName]
+---
+
+# ScMappingCard
+
+**One row of the Catalogix feed Map-Attributes screen.** A source feed column on the
+left, the target attribute(s) it maps to on the right, and the confirm/ignore
+actions for that pairing — as a single card with three mutually exclusive states.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building a source→target mapping review list where
+  each row can be confirmed, ignored, or is still pending.
+- **Don't reach for it when:** you are mapping *values* rather than *columns*
+  (→ `ScValueMappingL1`), or you just need a generic titled option card
+  (→ `ScDefaultCard`).
+- **Three things that will bite you:**
+  1. `status` gates almost every other prop. In `confirmed`/`ignored`, the `targets`
+     slot, `sampleRows`, `warning` and `validityText` are **not rendered at all**.
+  2. `targets` is a **slot** — you render your own dropdowns into it. The card
+     supplies no select control.
+  3. The card sets `overflow: hidden`. Dropdowns opened inside the slot **must be
+     portalled to `<body>`** or they get clipped.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScMappingCard } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScMappingCard
+  columnName="STYLE ID"
+  status="default"
+  targets={<MyTargetSelect value={target} onChange={setTarget} />}
+  onIgnore={() => ignore(col)}
+  onConfirm={() => confirm(col)}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `columnName` | `string` | — | **Required.** Source feed-column name, e.g. `"STYLE ID"`. Truncates with a `title` tooltip. |
+| `status` | `"default"` \| `"confirmed"` \| `"ignored"` | `"default"` | The state machine. Gates every region below. |
+| `badge` | `string` | – | Single letter for the narrow left gutter, e.g. `"A"`. Gutter is omitted entirely when unset. `aria-hidden`. |
+| `sampleRows` | `string[]` | `[]` | Sample-value preview lines under the column name. **`default` status only.** |
+| `targets` | `ReactNode` | – | **SLOT** for your target dropdown rows. **`default` status only.** |
+| `confirmedTargets` | `string[]` | `[]` | Mapped target names as read-only boxes with connector arrows. **`confirmed` status only.** |
+| `validityText` | `string` | – | Data-quality line, e.g. `"50% of rows … (200 out of 400)"`. **`default` status only.** |
+| `warning` | `ReactNode` | – | Link-warning message with an error icon. **`default` status only.** |
+| `canConfirm` | `boolean` | `false` | Shows "Confirm Mapping". Gate on "at least one target chosen". **`default` status only.** |
+| `onAddColumn` | `() => void` | – | The `+` in the source card header ("map this column to another target too"). **`default` status only.** |
+| `onIgnore` | `() => void` | – | "Ignore Column". **`default` status only.** |
+| `onConfirm` | `() => void` | – | "Confirm Mapping". Only reachable when `canConfirm`. |
+| `onEdit` | `() => void` | – | "Edit". **`confirmed` and `ignored` status only** — reopens the pairing. |
+| `className` | `string` | – | Appended after internal classes. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the card root. |
+
+### What renders in each status
+
+| Region | `default` | `confirmed` | `ignored` |
+|---|---|---|---|
+| Source | expanded card: name + `+` button + `sampleRows` | collapsed: name only | collapsed: name only |
+| Target | your `targets` slot | `confirmedTargets` as read-only boxes | a single `-` box |
+| Warning | `warning` if set | — | — |
+| Actions | "Ignore Column" + "Confirm Mapping" (if `canConfirm`) + `validityText` | ✓ "Column Confirmed" + "Edit" | ✕ "Column Ignored" + "Edit" |
+
+### Recipes
+
+```tsx
+// Driving the full list from mapping state
+{mappings.map((m, i) => (
+  <ScMappingCard
+    key={m.feedCol}
+    badge={m.headerLetter}
+    columnName={m.feedCol}
+    sampleRows={m.rows?.slice(0, 2).map((r) => r || "-")}
+    status={m.status}                          // "default" | "confirmed" | "ignored"
+    targets={<TargetRows mapping={m} />}       // your selects go here
+    confirmedTargets={[...m.mappedCols, ...m.customCols]}
+    validityText={m.validityText}
+    warning={m.warning?.msg}
+    canConfirm={[...m.mappedCols, ...m.customCols].length > 0}
+    onAddColumn={() => showExtraTarget(i)}
+    onIgnore={() => act(i, "ignore")}
+    onConfirm={() => act(i, "confirm")}
+    onEdit={() => act(i, "edit")}
+  />
+))}
+
+// The dropdown inside `targets` MUST portal out of the card
+<Select
+  menuPortalTarget={document.body}
+  styles={{ menuPortal: (b) => ({ ...b, zIndex: 9999 }) }}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **The Catalogix feed Map-Attributes screen** — one card per source column, stacked
+  in a scrolling list. This is its reason for existing.
+- Any future **schema/import mapping review** flow with the same
+  source→target→confirm shape.
+
+Currently rendered from `catalogix/dashboard app/components/FeedMapping/MapSingleAttribute`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are reviewing a **column-to-attribute** pairing, one card per source column.
+- Each row needs a **three-way lifecycle** (pending → confirmed | ignored) that the
+  user can reopen.
+- The target control is **product-specific** and you want to supply it yourself
+  while inheriting the card's layout, states and actions.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Mapping individual **values** within an attribute (Map-Values / curation) | `ScValueMappingL1` |
+| A generic pick-one-option card (title + description) | `ScDefaultCard` |
+| A flat data row in a table | `ScTableList` / `ScCatalogixStoreTableList` |
+| The target dropdown itself | `ScSelect`, or your app's select — this card only provides the slot |
+| A taxonomy tree node | `ScTaxonomyPill` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScValueMappingL1` — a single value-mapping row with `default`/`hover`/`active` + an "updated" dot | `ScMappingCard` is the column-level card with its own action footer |
+| `ScDefaultCard` — generic option card, no states, no actions | This card carries a mapping lifecycle |
+
+---
+
+## 4. Why to use it
+
+- **The state machine is already correct.** Three statuses × four regions is a lot
+  of conditional rendering to get wrong; the card collapses the source, swaps the
+  target region, and switches the footer to a status label in one prop.
+- **Slot design keeps product logic out of the DS.** Feed target dropdowns need
+  app-specific data, search and portalling, so `targets` stays a slot — you get the
+  chrome without the DS needing to know about your data layer.
+- **Two-tone surfaces that survive light mode.** The source card and card body use
+  two distinct tokens (`fill-neutral-*` body / raised source) that stay visually
+  separate in both themes, instead of relying on a grey that collapses to white.
+- **Status semantics are tokenised** — the ✓/✕ and their colours come from
+  `--alias-text-and-icons-success` / `-error`, so they match every other status in
+  the product.
+
+---
+
+## Gotchas
+
+**1. `status` silently drops props.** Passing `targets` while `status="confirmed"`
+renders nothing — a very common "my dropdowns disappeared" bug.
+
+```tsx
+// WRONG — targets ignored; confirmed status renders confirmedTargets instead
+<ScMappingCard columnName="COLOR" status="confirmed" targets={<MySelect />} />
+
+// RIGHT
+<ScMappingCard columnName="COLOR" status="confirmed" confirmedTargets={["color"]} onEdit={reopen} />
+```
+
+**2. Dropdowns get clipped.** The card root is `overflow: hidden`. Any menu opened
+from inside `targets` must be portalled to `document.body` with an explicit z-index.
+
+**3. `canConfirm` defaults to `false`.** Forget it and "Confirm Mapping" never
+appears, no matter how many targets are selected.
+
+**4. Button labels are hardcoded English.** "Ignore Column", "Confirm Mapping",
+"Edit", "Column Confirmed", "Column Ignored" and the `"Add column"` aria-label are
+baked into the component. There is no label prop — do not use this card in a
+localised surface without changing the DS first.
+
+**5. `columnName` is the only required prop.** Everything else is optional, so a
+typo'd prop name fails silently rather than erroring. Check spelling against the
+table above.
+
+**6. `onEdit` is unreachable in `default` status,** and `onIgnore`/`onConfirm`/
+`onAddColumn` are unreachable in the other two. Wire all of them; the card decides
+which are live.
+
+**7. `badge` is `aria-hidden`.** It is decoration, not information — don't put
+anything meaning-bearing there.
+
+---
+
+## In the wild
+
+```tsx
+// catalogix/dashboard  app/components/FeedMapping/MapSingleAttribute/index.jsx:302
+<ScMappingCard
+  badge={headerColumnName}
+  columnName={feedCol}
+  sampleRows={rows?.slice(0, 2).map((rowItem) => rowItem || "-")}
+  status={status}
+  targets={targets}
+  confirmedTargets={[...mappedCols, ...customCols]}
+  validityText={validityText}
+  warning={warningInfo ? warningInfo.msg : undefined}
+  canConfirm={[...mappedCols, ...customCols].length > 0}
+  onAddColumn={() => setShowAdditionalMappingOption(true)}
+  onIgnore={() => handleActionForMapAttribute(mappingItemIdx, "ignore")}
+  onConfirm={() => handleActionForMapAttribute(mappingItemIdx, "confirm")}
+  onEdit={() => handleActionForMapAttribute(mappingItemIdx, "edit")}
+/>
+```
+
+---
+
+## Related
+
+- `ScValueMappingL1` — the value-level sibling (Map-Values / curation rows).
+- `ScDefaultCard` — generic option card when you don't need the lifecycle.
+- `ScSelect` — a DS select you can render into the `targets` slot.
+- `ScTaxonomyPill` — taxonomy nodes on adjacent Catalogix screens.