@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScSettingsNav.md

@@ -0,0 +1,212 @@
+---
+component: ScSettingsNav
+package: "@streamoid/ui"
+category: layout
+status: legacy
+renders: div
+tags: [settings, nav, left-nav, sidebar, profile, workspace, referral, static, figma-dump]
+related: [ScSidebarMenu, ScSettingsTabComp, StreamoidSidebar, ScProfileSettingsComp]
+do_not_confuse_with: [ScSettingsTabComp, ScSidebarMenu, ScSidebar, StreamoidSidebar, ScProfileSettingsComp]
+---
+
+# ScSettingsNav
+
+**A hardcoded 256×290px settings left-nav card — Profile / Workspace / Referral, with
+Profile permanently active and nothing clickable.** It takes no props other than
+`className`. Treat it as a Figma snapshot, not a component: there is no way to change
+the items, the active row, or to attach a handler.
+
+> **status: legacy.** No host app renders it, and it cannot be configured. For a real
+> settings nav, compose `ScSidebarMenu` rows yourself, or use `ScSettingsTabComp` for a
+> horizontal tab strip.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a static visual placeholder of the settings nav
+  (a design mock, a screenshot, a Figma-parity check).
+- **Don't reach for it when:** you are building a working settings screen. It has no
+  `items`, no `activeItem`, no `onSelect`. → compose `ScSidebarMenu`, or use
+  `ScSettingsTabComp` / `StreamoidSidebar`.
+- **Three things that will bite you:**
+  1. The three labels — **"Profile", "Workspace", "Referral"** — are baked into the
+     source. No prop, no children, no localisation.
+  2. **"Profile" is always `state="active"`.** Navigation cannot be reflected.
+  3. **Nothing has an `onClick`.** The card is inert; clicks fall through to the parent.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSettingsNav } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScSettingsNav />
+```
+
+That is also the maximal usage.
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `className` | `string` | – | Appended after the internal class. Your only lever — use it to override the fixed `16rem × 18.125rem` box. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div. `onClick` here fires for the whole card, not per row — you cannot tell which item was hit. |
+
+There are **no** item, label, icon, active or handler props.
+
+### What it renders, verbatim
+
+| Row | Icon | `state` |
+|---|---|---|
+| `"Profile"` | `SiconTeam` | `"active"` |
+| `"Workspace"` | `SiconWorkspace` | `"default"` |
+| `"Referral"` | `SiconReferral` | `"default"` |
+
+Container: `--alias-surface-base` fill, `--radius-3xl` corners, 1px
+`--alias-border-subtle` border, `--spacing-md` padding, **fixed `width: 16rem` and
+`height: 18.125rem`**.
+
+### What to write instead
+
+```tsx
+// A working settings nav — the same look, with real behaviour
+const ITEMS = [
+  { id: "profile",   label: "Profile",   icon: <SiconTeam /> },
+  { id: "workspace", label: "Workspace", icon: <SiconWorkspace /> },
+  { id: "referral",  label: "Referral",  icon: <SiconReferral /> },
+];
+
+<div className={styles.navCard}>            {/* your own surface/border/radius */}
+  {ITEMS.map((it) => (
+    <ScSidebarMenu
+      key={it.id}
+      icon={it.icon}
+      text={it.label}
+      state={active === it.id ? "active" : "default"}
+      onClick={() => setActive(it.id)}
+    />
+  ))}
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+Nowhere in production today. Grepping CXO, Photogenix, Catalogix, Artifax and
+`@streamoid/settings` finds zero render sites.
+
+Where the *pattern* lives instead:
+
+- **Desktop settings navigation** is handled by `@streamoid/settings`, which uses
+  `ScTabComp`-based switchers and its own layout rather than a nav card.
+- **Mobile settings** uses a horizontal `ScSettingsTabComp` strip
+  (`cxo-dashboard src/app/components/mobile-settings-content.tsx`).
+- **App-level navigation** is `StreamoidSidebar` (config-driven `topItems` / `sections`).
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You need a pixel-parity static mock of the settings nav card and nothing more.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A functioning settings left-nav | your own container + `ScSidebarMenu` rows (see the snippet above) |
+| A horizontal settings tab strip | `ScSettingsTabComp` |
+| The app's primary navigation | `StreamoidSidebar` (config-driven; also `ScCatalogixSidebar` / `ScArtifaxSidebar`) |
+| One nav row | `ScSidebarMenu` |
+| The profile-settings screen scaffold | `ScProfileSettingsComp` |
+| A compact 2–5 way view toggle | `ScTabSwitcher` + `ScTabComp` |
+| A data-driven tab bar | `ScTabs` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSettingsTabComp` — a **single horizontal underline tab** with `tabName`/`active`/`onClick` | `ScSettingsNav` is a vertical card with no API |
+| `ScSidebarMenu` — the configurable nav row this card is built from | Use the row, not the card |
+| `ScSidebar` / `ScSidebarIcons` / `ScSidebarProfile` — the other pre-`StreamoidSidebar` parts | Same era, same problem: superseded |
+| `ScProfileSettingsComp` — the profile-settings content scaffold | Different surface |
+
+---
+
+## 4. Why to use it
+
+Honestly: don't. The only thing you'd get is Figma parity for a static screenshot.
+
+What you *lose* by using it: any ability to route, to reflect the current section, to
+add or remove items, to localise labels, or to fit a container (it is a fixed
+256×290px box). Everything valuable in it — the token fill, the border, the row
+treatment — is available directly from `ScSidebarMenu` plus four CSS declarations.
+
+---
+
+## Gotchas
+
+**1. Hardcoded English labels.** "Profile", "Workspace", "Referral" are string
+literals in the render body. No `items` prop exists.
+
+**2. "Profile" is always the active row.** `state="active"` is hardcoded on the first
+`ScSidebarMenu`, so the card contradicts your actual route the moment the user
+navigates.
+
+**3. No handlers anywhere.** Rows don't take `onClick` here. An `onClick` on the root
+tells you the card was clicked, not which row.
+
+```tsx
+// WRONG — there is no way to know which item was clicked
+<ScSettingsNav onClick={(e) => route(e.target)} />
+
+// RIGHT — build the list yourself
+{items.map((it) => <ScSidebarMenu key={it.id} text={it.label} onClick={() => route(it.id)} />)}
+```
+
+**4. Fixed size.** `width: 16rem; height: 18.125rem` — the card keeps its 290px height
+with three rows and will not grow for a fourth (you can't add one anyway). Override via
+`className` if you must embed it.
+
+**5. `className` is concatenated unguarded** → `class="scSettingsNav undefined"` when
+omitted.
+
+**6. `--alias-border-subtle` at 1px, not the 0.5px divider.** If you place it beside
+cards that use `--alias-shadow-*` elevation, its border reads heavier than its
+neighbours in light mode.
+
+**7. Not deprecated in source, but unused everywhere.** Nothing warns you at build
+time. Its `status: legacy` here is the only signal — don't take its presence in
+`index.ts` as an endorsement.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+Neither is true, strictly: it has **no** consumer at all — not the four dashboards, not
+`@streamoid/settings`, not another DS component. If a settings nav card is needed
+again, it most likely belongs in `@streamoid/settings` beside the settings/billing
+screens, rebuilt with an `items` + `activeId` + `onSelect` API on top of
+`ScSidebarMenu`.
+
+---
+
+## Related
+
+- `ScSidebarMenu` — the configurable nav row; the right building block.
+- `ScSettingsTabComp` — the horizontal settings tab actually used by CXO.
+- `StreamoidSidebar` — the current shared, config-driven app shell nav.
+- `ScProfileSettingsComp` / `ScProfileOptions` — profile-side settings scaffolding.
+- `ScSidebar`, `ScSidebarIcons`, `ScSidebarProfile`, `ScSidebarSwitchMenu`,
+  `ScLogoUnit` — the other superseded pre-`StreamoidSidebar` parts.

package/dist/docs/ScSettingsTabComp.md

@@ -0,0 +1,260 @@
+---
+component: ScSettingsTabComp
+package: "@streamoid/ui"
+category: layout
+status: stable
+renders: div
+tags: [tab, underline-tab, settings, tab-strip, mobile-settings, modal-tabs, section-switch]
+related: [ScTabComp, ScTabSwitcher, ScTabs, ScTabField, ScSettingsNav]
+do_not_confuse_with: [ScTabComp, ScTabSwitcher, ScTabs, ScSettingsNav, ScSelectionPill]
+used_by: [cxo, catalogix]
+---
+
+# ScSettingsTabComp
+
+**One underlined tab in a horizontal strip.** 56px tall, 12px padding, muted 16px
+label; when `active` it turns primary-coloured and grows a 1.25px underline. This is
+the settings/modal tab vocabulary — flat and underlined — as opposed to the filled
+`ScTabComp` pill inside a `ScTabSwitcher` track.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a settings-style tab strip — Profile / Workspace,
+  or a modal's section tabs — where the active tab is marked by an underline.
+- **Don't reach for it when:** you want the bordered filled segmented control
+  (→ `ScTabSwitcher` + `ScTabComp`), a data-driven pill bar (→ `ScTabs`), or a form
+  field (→ `ScTabField`).
+- **Four things that will bite you:**
+  1. `active` is a **real boolean** here — the exact opposite of `ScTabComp`, whose
+     `active` is the string `"true"`/`"false"`.
+  2. **No props are spread.** No `style`, no `role`, no `aria-selected`, no
+     `data-testid`, no `id`. Only `tabName`, `active`, `onClick`, `className`.
+  3. It draws **only its own underline**. The strip's baseline border is the parent's job.
+  4. `tabName` defaults to `"Tab"`, and the 3.5rem height is fixed.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSettingsTabComp } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScSettingsTabComp tabName="Profile" active={tab === "profile"} onClick={() => setTab("profile")} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `tabName` | `string` | `"Tab"` | ⚠️ Real default. Rendered in a `<span>`, `white-space: nowrap`, no truncation. |
+| `active` | `boolean` | `false` | **Boolean** (unlike `ScTabComp`). Adds the underline and switches the label to `--alias-text-and-icons-primary`. |
+| `onClick` | `() => void` | – | No event argument — the handler takes no parameters. |
+| `className` | `string` | – | Appended last (guarded with `?? ""`, so no stray `"undefined"`). Your only styling lever. |
+
+Everything else is unavailable: the component destructures exactly these four props and
+spreads nothing.
+
+### What renders in each state
+
+| `active` | Label colour | Underline |
+|---|---|---|
+| `false` | `--alias-text-and-icons-muted` | none |
+| `true` | `--alias-text-and-icons-primary` | `border-bottom: 1.25px solid --alias-text-and-icons-primary` |
+
+Box in both states: `height: 3.5rem`, `padding: var(--spacing-xl)` (0.75rem),
+`flex-shrink: 0`, `cursor: pointer`, centred content, 16px/1.5rem label.
+
+### Recipes
+
+```tsx
+// The strip: the PARENT draws the baseline, the tab draws only its own underline
+<div
+  className="flex shrink-0"
+  style={{
+    borderBottom: "0.5px solid var(--alias-border-divider)",
+    padding: "0 var(--spacing-md)",
+    gap: "var(--spacing-md)",
+  }}
+>
+  <ScSettingsTabComp tabName="Profile"   active={tab === "profile"}   onClick={() => setTab("profile")} />
+  <ScSettingsTabComp tabName="Workspace" active={tab === "workspace"} onClick={() => setTab("workspace")} />
+</div>
+
+// From data
+{sections.map((s) => (
+  <ScSettingsTabComp
+    key={s.value}
+    tabName={s.label}
+    active={activeTab === s.value}
+    onClick={() => onClickTab(s.value)}
+  />
+))}
+
+// Need aria/roles or a test hook? wrap it — they can't be passed through
+<div role="tab" aria-selected={isActive} data-testid={`tab-${id}`}>
+  <ScSettingsTabComp tabName={label} active={isActive} onClick={select} />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO mobile settings** — the Profile / Workspace strip at the top of
+  `mobile-settings-content`.
+- **Catalogix modals** — the folder-tab strip inside the shared `Modal` component
+  (which reverses the array to preserve the legacy `row-reverse` order).
+- Any **section switcher above a scrolling content pane** where an underline reads
+  better than a filled pill: settings, detail screens, modal sections.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The tabs sit **directly above the content they switch**, with a baseline rule.
+- Labels are words (not icons) and the underline treatment matches the surface.
+- You are matching the existing settings / modal look.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Compact filled segmented control, 2–5 ways | `ScTabSwitcher` + `ScTabComp` |
+| Icon-only tabs | `ScTabComp` (`type="icon-only"`) — this component has no icon support |
+| Long or dynamic tab lists that must wrap | `ScTabs` (`allowWrap`, `isCompact`) |
+| A segmented control that is a **saved form value** | `ScTabField` |
+| Dark-fill selection pills (Catalogix curation) | `ScSelectionPillGroup` |
+| A vertical settings nav | your own `ScSidebarMenu` list (**not** `ScSettingsNav` — see its README) |
+| Something that needs `role="tab"` on the element itself | wrap this, or use `ScSelectionPill` (a real `<button>`) |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScTabComp` — filled pill for a `ScTabSwitcher`; `active` is the **string** `"true"`/`"false"`; spreads DOM props | `ScSettingsTabComp` is an underline tab; `active` is a **boolean**; spreads nothing |
+| `ScSettingsNav` — the static vertical settings nav card (legacy, no API) | This is one horizontal tab |
+| `ScTabs` — the whole row from data | This is one tab; you map them yourself |
+| `ScTabField` — label + switcher, for forms | Different surface and API |
+
+### The tab family at a glance
+
+| Component | Shape | Selection API | Root | Spreads DOM props? |
+|---|---|---|---|---|
+| `ScSettingsTabComp` | underline tab | `active` (**boolean**) + `onClick()` | `div` | ❌ |
+| `ScTabComp` | filled pill cell | `active="true" \| "false"` (**strings**) | `div` | ✅ |
+| `ScTabSwitcher` | 2–5 slot bordered track | none — children own it | `div` | ✅ |
+| `ScTabs` | N pills, data-driven | `activeTab` + `onClickTab(value)` | `div` | ❌ |
+| `ScTabField` | field label + 2-tab switcher | `activeTab` + `onTabChange` | `div` | ❌ |
+| `ScSelectionPill` | one segmented pill | `selected` (**boolean**) + `onSelect(value)` | `button[type="button"][aria-pressed]` | ✅ |
+| `ScSelectionPillGroup` | segmented pill row | `value` + `onChange(value)` | `div[role="tablist"]` of `button`s | ✅ |
+
+---
+
+## 4. Why to use it
+
+- **The active marker is a token, not a colour.** Label and underline both use
+  `--alias-text-and-icons-primary`, so the strip inverts correctly between themes —
+  a hand-rolled `border-bottom: 1.25px solid #f5f5f5` disappears on the light canvas.
+- **1.25px is a real design value**, not a rounding of 1px. Getting it wrong is the
+  most visible way a hand-built tab strip looks "off" next to a DS one.
+- **The 56px row height is shared** with the mobile settings header rhythm, so tabs
+  line up with adjacent chrome without magic numbers at the call site.
+- **Tiny surface area** — four props, no state — which is why both CXO and Catalogix
+  could drop their own tab-strip implementations and keep their existing APIs.
+
+---
+
+## Gotchas
+
+**1. `active` is a boolean — the inverse of `ScTabComp`.** Switching between the two
+components is the most common mistake in this family.
+
+```tsx
+// WRONG — TS error: Type 'string' is not assignable to type 'boolean | undefined'
+<ScSettingsTabComp tabName="Profile" active={tab === "profile" ? "true" : "false"} />
+
+// RIGHT
+<ScSettingsTabComp tabName="Profile" active={tab === "profile"} />
+```
+
+The variant class is built by concatenation (`styles["active-" + active]`), so in a
+plain-JS host (Catalogix) the string form happens to resolve to the same class and the
+mistake never surfaces at runtime — it only fails to typecheck. Don't rely on that.
+
+**2. Nothing is spread onto the DOM.** `style`, `role`, `aria-selected`, `id`,
+`data-*` are silently unavailable — they are not in the props type at all.
+
+```tsx
+// WRONG — TS error; and there is no runtime pass-through either
+<ScSettingsTabComp tabName="Profile" active role="tab" style={{ flex: 1 }} />
+
+// RIGHT — wrap it, or use className
+<div role="tab" aria-selected style={{ flex: 1 }}>
+  <ScSettingsTabComp tabName="Profile" active className={styles.tab} />
+</div>
+```
+
+**3. The strip's baseline border is yours.** The tab only paints its own 1.25px
+underline; without a container `border-bottom` the inactive tabs float over nothing.
+CXO's strip sets `borderBottom: 0.5px solid <divider>` on the flex row.
+
+**4. Fixed 3.5rem height.** No `size` prop. Override with a `className` if you need a
+denser strip — and expect the underline to move with it.
+
+**5. `tabName` defaults to `"Tab"`.** Forget the prop and you ship the placeholder.
+
+**6. No icon support.** There is no `icon` prop and no slot; `tabName` is a `string`,
+not a `ReactNode`, so you cannot pass an element.
+
+**7. No truncation.** `white-space: nowrap` with no `max-width`, no ellipsis, no
+`title`. Long labels widen the strip and force horizontal overflow on mobile.
+
+**8. `div` + `onClick`: no keyboard, no focus ring.** Not focusable, no Enter/Space,
+no `aria-selected`. For an accessible strip, wrap each tab (see recipe) or use
+`ScSelectionPillGroup`.
+
+**9. `onClick` receives no event.** The signature is `() => void`, so you cannot
+`stopPropagation` or read the target. Do that in a wrapper.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/mobile-settings-content.tsx:233
+<ScSettingsTabComp
+  tabName="Profile"
+  active={activeTab === "profile"}
+  onClick={() => setActiveTab("profile")}
+/>
+```
+
+```jsx
+// catalogix/dashboard  app/components/Modal/index.jsx:354
+<ScSettingsTabComp
+  key={`${idx}-${value}`}
+  tabName={formatTabLabel(label)}
+  active={props.activeTab == value}
+  onClick={() => props.onClickTab(value)}
+/>
+```
+
+---
+
+## Related
+
+- `ScTabComp` — the filled pill cell; note the string `active` prop.
+- `ScTabSwitcher` — bordered 2–5 slot track for `ScTabComp`s.
+- `ScTabs` — data-driven wrapping pill bar.
+- `ScTabField` — labelled form field wrapping a 2-tab switcher.
+- `ScSettingsNav` — **legacy** static vertical settings nav card; don't use it.
+- `ScSelectionPillGroup` — accessible segmented control (real buttons).