@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScValueMappingL1.md

@@ -0,0 +1,256 @@
+---
+component: ScValueMappingL1
+package: "@streamoid/ui"
+category: feed-taxonomy
+status: stable
+renders: div
+tags: [value-mapping, curation, attribute-value, list-row, selectable-row, updated-dot, catalogix, map-values]
+related: [ScMappingCard, ScSelectionPillGroup, ScTaxonomyPill, ScDefaultCard]
+do_not_confuse_with: [ScMappingCard, ScSelectionPill, ScDefaultCard, ScTableList]
+used_by: [catalogix]
+---
+
+# ScValueMappingL1
+
+**One selectable row in a value-mapping / curation list.** A full-width rounded box
+containing a single truncating label, three visual states (`default` / `hover` /
+`active`), and an optional blue "this value was edited" dot on the right.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a vertical list of *values* (attribute values,
+  categories, enum members) where exactly one is the current selection and some
+  carry an "updated" marker.
+- **Don't reach for it when:** you're mapping *columns* to attributes with a
+  confirm/ignore lifecycle (→ `ScMappingCard`), you want a horizontal segmented
+  switch (→ `ScSelectionPillGroup`), or you need a multi-column data row
+  (→ `ScTableList` / `ScCatalogixStoreTableList`).
+- **Three things that will bite you:**
+  1. `label` defaults to **`"Title"`** — forget it and every row says "Title".
+  2. It's a plain `<div>`. `onClick` works because it's spread, but there is **no
+     `role`, no `tabIndex`, no keyboard handler**. You add those.
+  3. `state` is a *skin*, not selection state. Nothing is tracked; you compute
+     `"active"` yourself.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScValueMappingL1 } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScValueMappingL1 label="Red" onClick={() => setSelected("Red")} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | `"Title"` | ⚠️ Has a real default. The whole content of the row. Truncates with ellipsis and gets a native `title` tooltip with the same text. |
+| `state` | `"default"` \| `"hover"` \| `"active"` | `"default"` | Forced visual state. `"active"` = "this is the currently selected row". Real `:hover` also applies the hover skin. |
+| `updated` | `boolean` | `false` | Renders the trailing blue dot **and** adds `padding-right: 0.5rem` to the row. The dot is `aria-hidden`. |
+| `className` | `string` | – | Appended after the internal classes, so it wins on equal specificity. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `onClick`, `role`, `tabIndex`, `onKeyDown`, `style`, `data-*` all land on the root div. |
+
+### What renders in each state
+
+| `state` | Background token | Border token |
+|---|---|---|
+| `default` | `--alias-surface-base` | `--alias-border-subtle` |
+| `hover` (or real `:hover`) | `--alias-surface-basesubtle` | `--alias-border-default` |
+| `active` | `--alias-surface-raisedoverlay` | `--alias-border-default` |
+
+`active` wins over real `:hover` (its rule is last), so hovering the selected row
+does not flicker back to the hover skin.
+
+### Recipes
+
+```tsx
+// The standard list: one active row, some rows flagged as edited
+<div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+  {attributeValues.map((attr) => (
+    <ScValueMappingL1
+      key={attr}
+      label={attr}
+      state={attr === selectedValue ? "active" : "default"}
+      updated={isEdited(attr)}
+      onClick={() => setSelectedValue(attr)}
+    />
+  ))}
+</div>
+
+// Make it actually keyboard-operable (the DS does not do this for you)
+<ScValueMappingL1
+  label={attr}
+  state={attr === selectedValue ? "active" : "default"}
+  role="option"
+  aria-selected={attr === selectedValue}
+  tabIndex={0}
+  onClick={() => setSelectedValue(attr)}
+  onKeyDown={(e) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      setSelectedValue(attr);
+    }
+  }}
+/>
+
+// Give the "updated" dot a meaning screen readers can reach
+<ScValueMappingL1 label={attr} updated aria-label={`${attr} (edited)`} />
+```
+
+---
+
+## 2. Where to use it
+
+- **Catalogix Curation V2 → the attribute-values column.** The left panel lists every
+  value of the selected attribute; clicking one loads its curation rules in the right
+  panel. This is the component's only production surface today.
+- Any **master/detail list of values** on the feed side: map-values screens,
+  synonym lists, enum pickers — a narrow scrolling column of single-line rows next to
+  a detail pane.
+- It composes *nothing*. It expects to be stacked directly inside a scrolling flex
+  column that supplies the gap.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The list items are **single strings** with no secondary line, no icon, no counts.
+- Exactly **one** row is "current", and the selection drives a neighbouring panel.
+- Some rows need a **subtle "changed since last save" marker** that doesn't steal
+  attention (the blue info dot).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Mapping a feed **column** to target attributes, with Ignore/Confirm/Edit | `ScMappingCard` |
+| Horizontal segmented switch between 2–5 views | `ScSelectionPillGroup` |
+| A node in a taxonomy tree, with child counts and expand/collapse | `ScTaxonomyPill` |
+| Title + description "pick one of these options" card | `ScDefaultCard` |
+| A row with several aligned columns | `ScTableList`, or `ScCatalogixStoreHeader` + `ScCatalogixStoreTableList` |
+| Multi-select over the list | `ScCheckField` / `ScCheckbox` rows — this row has no checkbox and no multi-select affordance |
+| A real form control whose value gets saved | `ScRadio` / `ScTabField` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScMappingCard` — column-level card with a `default`/`confirmed`/`ignored` lifecycle, a `targets` slot and an action footer | `ScValueMappingL1` is a single value row with a forced skin and nothing else |
+| `ScSelectionPill` — a *horizontal* pill in a segmented row, real `<button>`, `aria-pressed` | This is a *vertical* full-width row, a `<div>`, no aria |
+| `ScDefaultCard` — generic option card (`title` + optional `description`) | No description line here, and it has an `active` state that `ScDefaultCard` lacks |
+
+Both `ScValueMappingL1` and `ScDefaultCard` take a `state` prop with a `"hover"`
+member; only `ScValueMappingL1` has `"active"`. If you need a persistent
+"selected" look, that's the deciding factor.
+
+---
+
+## 4. Why to use it
+
+- **The three-state token ladder is already correct.** `surface-base` →
+  `surface-basesubtle` → `surface-raisedoverlay` stay visually distinct in both
+  themes. Hand-rolled selection rows almost always reach for a hard-coded grey that
+  collapses to white in light mode and loses the "selected" read entirely.
+- **Truncation with a tooltip, for free.** Long attribute values ellipsise and get a
+  `title` fallback, so a 200-character value can't blow out the column width.
+- **The "updated" dot is a token, not a colour.** It uses
+  `--alias-text-and-icons-infocont`, matching every other "changed / info" marker
+  in the product.
+- **One row height everywhere.** `0.75rem` padding on a `text-sm` line, so the
+  Curation list and any future value list line up without per-screen CSS.
+
+---
+
+## Gotchas
+
+**1. `label` defaults to `"Title"`.** There is no required prop, so a typo'd prop
+name renders a list of "Title".
+
+```tsx
+// WRONG — renders "Title" (typo'd prop is silently ignored)
+<ScValueMappingL1 lable={attr} />
+
+// RIGHT
+<ScValueMappingL1 label={attr} />
+```
+
+**2. No button semantics.** The root is a `<div>` with `cursor: pointer` and nothing
+else — no `role`, no `tabIndex`, no `onKeyDown`, no `aria-selected`. A mouse user
+sees an affordance a keyboard user cannot reach. Pass them yourself (see Recipes).
+
+**3. `state` does not track anything.** It is a forced skin. There is no `selected`
+prop and no internal state; if you never compute `"active"`, nothing ever looks
+selected.
+
+```tsx
+// WRONG — nothing looks selected, ever
+{values.map((v) => <ScValueMappingL1 key={v} label={v} onClick={() => pick(v)} />)}
+
+// RIGHT
+{values.map((v) => (
+  <ScValueMappingL1 key={v} label={v} state={v === picked ? "active" : "default"} onClick={() => pick(v)} />
+))}
+```
+
+**4. `state="hover"` is for design parity, not interaction.** Real `:hover` already
+works. Wiring `onMouseEnter` to flip `state` just fights the CSS.
+
+**5. The row supplies no vertical gap.** No margin, no `:not(:last-child)` rule.
+Stacked rows touch unless the parent sets `gap` (Catalogix uses `12px`).
+
+**6. It has `width: 100%` but no `flex-shrink: 0`.** Inside a **height-capped** flex
+column the rows compress toward zero height and the list looks empty. Put them in a
+scrolling wrapper instead of a fixed-height column:
+
+```css
+/* RIGHT — the host pattern */
+.list-scroll { overflow-y: auto; }
+.list        { display: flex; flex-direction: column; gap: 12px; }
+```
+
+**7. The `updated` dot carries no accessible name.** It's `aria-hidden` decoration
+occupying `1.5rem`. If "edited" is information the user needs, put it in
+`aria-label` or a visible legend.
+
+**8. `updated` changes the row's inner metrics.** It adds `padding-right: 0.5rem`
+plus a `1.5rem` dot slot, so an updated row has a narrower label area than its
+neighbours. Expected, but it means truncation points differ down the list.
+
+---
+
+## In the wild
+
+```jsx
+// catalogix/dashboard  app/containers/StoreSettingsV2/CurationV2/index.jsx:394
+<ScValueMappingL1
+  key={idx}
+  label={attr}
+  state={attr === selectedAttribute ? "active" : "default"}
+  updated={isAttrUpdated(attr)}
+  onClick={() => setSelectedAttribute(attr)}
+/>
+```
+
+Rendered inside `.smp-values { overflow-y: auto }` → `.block { display: flex;
+flex-direction: column; gap: 12px }` — i.e. the host supplies both the scroll
+container and the gap (see Gotchas 5 and 6).
+
+---
+
+## Related
+
+- `ScMappingCard` — the column-level sibling on the feed Map-Attributes screen; has the confirm/ignore state machine this row deliberately lacks.
+- `ScSelectionPillGroup` — the horizontal segmented switch that usually sits *above* a `ScValueMappingL1` list (Curation V2 has both).
+- `ScTaxonomyPill` — hierarchy node chip for tree layouts rather than flat lists.
+- `ScDefaultCard` — reach for it when the row needs a description line and no `active` state.

package/dist/docs/ScVersion.md

@@ -0,0 +1,251 @@
+---
+component: ScVersion
+package: "@streamoid/ui"
+category: sidebar
+status: legacy
+renders: div
+tags: [sidebar, version, footer, version-stamp, collapse-toggle, legacy, build-number]
+related: [StreamoidSidebar, ScSidebarIcons, ScSidebar, ScMenuOptions]
+do_not_confuse_with: [StreamoidSidebar, ScSidebarIcons, ScMenuOptions, ScBadges]
+---
+
+# ScVersion
+
+**Legacy. Superseded by `StreamoidSidebar`'s `versionText` prop.** The old rail's bottom
+footer: a version string plus a collapse chevron. The chevron is **decorative** (it goes
+through `ScSidebarIcons`, which drops all props), and the version defaults to the
+hardcoded string `"v2.1.2"`.
+
+## TL;DR for agents
+
+- **Reach for it when:** never. `StreamoidSidebar` renders its own version footer
+  inline from `versionText`.
+- **Reach for this instead:** `StreamoidSidebar` with `versionText="v2.1.2"` — or
+  `toggleInProfile` if you want the collapse control beside the profile row and no
+  version footer at all.
+- **Four things that will bite you:**
+  1. ⚠️ `version` defaults to `"v2.1.2"`. Forget it and you ship a stale build number.
+  2. `component` and `scSidebarIconsinstance` are **only read in the `collapsed`
+     branch**. In `expanded` the component builds its own `SiconCollapse` and ignores
+     both props.
+  3. The chevron in `expanded` is hardcoded to `state="hover"` — permanently
+     hover-skinned.
+  4. Nothing inside is clickable. Wire `onClick` on the root (that prop *is* spread) and
+     accept that the whole footer becomes the hit area.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScVersion } from "@streamoid/ui";
+import { SiconCollapse } from "@streamoid/icons";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScVersion state="expanded" version={`v${appVersion}`} onClick={toggleSidebar} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `version` | `string` | `"v2.1.2"` | ⚠️ Has a real default — a specific stale version string. Rendered with a **trailing space** (`{version}&nbsp;`). Single line, ellipsised. |
+| `state` | `"expanded"` \| `"collapsed"` | `"expanded"` | Changes both the layout direction and which icon branch runs. See the table below. |
+| `scSidebarIconsinstance` | `JSX.Element` | – | ⚠️ Note the lower-case `i` in `…instance`. The icon handed to the internal `ScSidebarIcons`. **`collapsed` only** — falls back to `<SiconCollapse />`. |
+| `component` | `JSX.Element` | – | Replaces the whole icon slot (wins over `scSidebarIconsinstance`). **`collapsed` only.** |
+| `className` | `string` | – | Concatenated onto the root. ⚠️ Unguarded — omitting it puts a literal `undefined` in the class list. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | **Is** spread onto the root, so `onClick`, `style`, `aria-*`, `data-*` work — on the whole row, not on the chevron. |
+
+### What renders in each state
+
+| | `expanded` | `collapsed` |
+|---|---|---|
+| Direction | `row`, 4 px gap, padding `4px 4px 4px 16px` | `column`, 12 px gap, padding `16px 8px`, fixed `width: 3.5rem` |
+| Order | `version` (flex: 1) → chevron | chevron → `version` |
+| Icon source | **hardcoded** `<SiconCollapse />` inside `ScSidebarIcons state="hover"`. `component` and `scSidebarIconsinstance` are **ignored**. | `component` ?? `ScSidebarIcons instance={scSidebarIconsinstance ?? <SiconCollapse />}` |
+| Type ramp | `text-sm-regular`, left-aligned | `text-xs-regular`, centred |
+| Colour | `--alias-text-and-icons-muted` | same |
+
+### Recipes
+
+```tsx
+// Collapsed footer with your own icon (the only state where the icon props work)
+<ScVersion
+  state="collapsed"
+  version={`v${appVersion}`}
+  scSidebarIconsinstance={<SiconCollapse size={20} />}
+  onClick={toggleSidebar}
+/>
+
+// Collapsed footer, replacing the entire icon slot
+<ScVersion
+  state="collapsed"
+  version={`v${appVersion}`}
+  component={<MyOwnToggleButton onClick={toggleSidebar} />}
+/>
+```
+
+The replacement, which is what you should actually write:
+
+```tsx
+// Version footer + a working collapse toggle, rendered by the shell
+<StreamoidSidebar
+  expanded={expanded}
+  onToggle={() => setExpanded((v) => !v)}
+  config={config}
+  iconMap={iconMap}
+  versionText={`v${appVersion}`}                                    // default is "v1.0.0"
+  toggleIcon={(isExpanded) => <SiconCollapse size={20} />}
+/>
+
+// Or: no version footer at all — profile row + a separate collapse button beside it
+<StreamoidSidebar … versionText={undefined} toggleInProfile />
+```
+
+---
+
+## 2. Where to use it
+
+Nowhere. Its only render site is the legacy `ScSidebar`
+(`src/SC-Sidebar/ScSidebar.tsx:140` collapsed, `:248` expanded), which is itself unused.
+
+`StreamoidSidebar` renders the version footer **inline** — it does not compose
+`ScVersion` — from `versionText` (default `"v1.0.0"`), and owns the collapse toggle via
+`onToggle` / `toggleIcon` / `toggleInProfile`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Never.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A version stamp in a real sidebar footer | `StreamoidSidebar`'s `versionText` |
+| A working collapse/expand control | `StreamoidSidebar`'s `onToggle` + `toggleIcon`, or `toggleInProfile` |
+| A version line inside a profile/settings popup menu row | `ScMenuOptions` (`variant="with-v"`, `version` prop) |
+| A version pill/chip somewhere in the UI | `ScBadges` (`text`, `variant`, `styleVariant`) |
+| Any clickable icon | `ScButton styleVariant="icon-only"` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `StreamoidSidebar`'s `versionText` — the current, working footer | `ScVersion` is the standalone legacy footer |
+| `ScMenuOptions` with `variant="with-v"` — a **popup menu row** that also shows a version | not a sidebar footer |
+| `ScBadges` — a small status/count chip | `ScVersion` is a full-width footer row |
+| `ScSidebarIcons` — the inert icon box this component wraps | also legacy |
+
+---
+
+## 4. Why to use it
+
+You wouldn't. What it still encodes correctly:
+
+- The version stamp is `--alias-text-and-icons-muted` — the dimmest text token, so a
+  build number never competes with nav labels.
+- Expanded uses `text-sm` left-aligned with the chevron pushed right by `flex: 1`;
+  collapsed drops to `text-xs`, centres, and stacks the chevron above the string. Both
+  are the correct Figma treatments.
+- `text-overflow: ellipsis` on the version, so a long build hash truncates rather than
+  widening the rail.
+
+What you lose: a working toggle, and any way to change the icon in the expanded state.
+
+---
+
+## Gotchas
+
+**1. `version` defaults to `"v2.1.2"`.** Not a placeholder like "Version" — an actual
+version number that will look plausible and be wrong.
+
+```tsx
+// WRONG — ships "v2.1.2"
+<ScVersion state="expanded" />
+
+// RIGHT
+<ScVersion state="expanded" version={`v${appVersion}`} />
+```
+
+**2. `component` and `scSidebarIconsinstance` are ignored when expanded.** The expanded
+branch constructs its own `<ScSidebarIcons instance={<SiconCollapse />} state="hover" />`
+and never consults either prop. The legacy `ScSidebar` passes both anyway — don't take
+that call site as an example.
+
+```tsx
+// WRONG — your icon never appears
+<ScVersion state="expanded" scSidebarIconsinstance={<SiconUp />} />
+
+// RIGHT — the icon props only work collapsed
+<ScVersion state="collapsed" scSidebarIconsinstance={<SiconUp />} />
+```
+
+**3. The chevron is not a button.** It renders through `ScSidebarIcons`, which
+destructures `...props` and never spreads it, so there is no way to attach a handler to
+the icon. `ScVersion`'s own `...props` *is* spread on the root, so an `onClick` there
+makes the **whole footer row** the hit area — including the version text.
+
+**4. `state="hover"` is baked into the expanded chevron.** It permanently renders the
+hover background. There is no prop to turn it off.
+
+**5. The prop name is `scSidebarIconsinstance`.** Lower-case `i` on `instance`, mixed
+into a camel-cased component name. It's a Figma-export artifact and an easy typo — and
+a typo is silent, because every prop is optional.
+
+**6. Fixed `width: 3.5rem` when collapsed.** 56 px, wider than the 40 px collapsed nav
+squares and the 48 px collapsed profile box, so the footer sets the rail's minimum
+width.
+
+**7. `version` renders with a trailing space.** The JSX is `{version} ` — visible in DOM
+snapshots and in text assertions.
+
+**8. `className` produces a literal `undefined` class when omitted.**
+`styles.scVersion + " " + className + " " + variantsClassName`.
+
+**9. No `role`, `tabIndex` or keyboard handling.** If you make the row clickable via
+`onClick`, supply those yourself through `...props`.
+
+---
+
+## 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:140
+<ScVersion
+  state="collapsed"
+  scSidebarIconsinstance={
+    <SiconCollapse className={styles.siconCollapseInstance} />
+  }
+  className={styles.scVersionInstance}
+/>
+```
+
+Where it *would* belong — the rail's bottom footer — is now rendered inline by
+`StreamoidSidebar` from `versionText`
+(`packages/ui/src/SC-Sidebar-new/streamoid-sidebar.tsx:787`), which every host drives
+(e.g. `cxo-dashboard src/app/components/app-sidebar.tsx`).
+
+---
+
+## Related
+
+- `StreamoidSidebar` — **the replacement.** `versionText` for the stamp, `onToggle` /
+  `toggleIcon` / `toggleInProfile` for the collapse control.
+- `ScSidebarIcons` — the inert icon box this composes; also legacy.
+- `ScMenuOptions` — popup menu row with a `version` slot (`variant="with-v"`).
+- `ScSidebar` / `ScLogoUnit` / `ScSidebarProfile` — the rest of this legacy sidebar
+  family.