@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScSidebarIcons.md

@@ -0,0 +1,232 @@
+---
+component: ScSidebarIcons
+package: "@streamoid/ui"
+category: sidebar
+status: legacy
+renders: div
+tags: [sidebar, icon, icon-button, hover, footer, collapse-toggle, legacy, wrapper]
+related: [ScButton, ScVersion, StreamoidSidebar, ScSidebarMenu, ScOnlyIcon]
+do_not_confuse_with: [ScOnlyIcon, ScSidebarMenu, ScAppcardLogos, ScButton]
+---
+
+# ScSidebarIcons
+
+**Legacy. A 8 px-padded, `radius-3xl` box around one icon, with a hover background —
+and nothing else.** It drops every prop except `instance`, `state` and `className`, so
+it cannot be clicked, focused or labelled. Superseded by
+`ScButton styleVariant="icon-only"` for a real icon affordance, and by
+`StreamoidSidebar`'s built-in collapse toggle for its original job.
+
+## TL;DR for agents
+
+- **Reach for it when:** never. It has no click path.
+- **Reach for this instead:** `ScButton styleVariant="icon-only" icon={…}` (a real,
+  keyboard-accessible icon affordance), or `StreamoidSidebar`'s `toggleIcon` /
+  `toggleInProfile` for the rail's collapse control. Note `ScOnlyIcon` is **not** a
+  general-purpose alternative — it hardcodes `SiconSettings` and has no `icon` prop.
+- **Three things that will bite you:**
+  1. ⚠️ **`...props` is destructured and never spread.** `onClick`, `aria-label`,
+     `data-*` are silently dropped. The interface doesn't even extend
+     `HTMLAttributes`, so TypeScript rejects `onClick` before you get that far.
+  2. `instance` defaults to `<SiconSupport />`. Forget it and you ship a headset icon.
+  3. It has a hover background but no `cursor: pointer`, no `role`, no `tabIndex`. It
+     looks like a button and is inert.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSidebarIcons, ScButton, StreamoidSidebar } from "@streamoid/ui";
+import { SiconCollapse, SiconSupport } from "@streamoid/icons";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+// The entire useful API. Note: no onClick — see Gotcha 1.
+<ScSidebarIcons instance={<SiconCollapse />} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `instance` | `JSX.Element` | `<SiconSupport />` | ⚠️ Has a real default. The single child; rendered verbatim (no `cloneElement`, no size or colour normalisation). |
+| `state` | `"default"` \| `"hover"` | `"default"` | `"hover"` force-renders the `fill-neutral-neutral` background. Real `:hover` already does the same. |
+| `className` | `string` | – | Concatenated onto the root. ⚠️ Unguarded — omitting it puts a literal `undefined` in the class list. |
+| `...props` | – | – | ⚠️ **Destructured and discarded.** `IScSidebarIconsProps` does **not** extend `React.HTMLAttributes`, so there is no supported way to attach a handler or an aria attribute. |
+
+The whole component is: `<div className="…">{instance}</div>` plus one hover rule.
+
+### Recipes
+
+```tsx
+// You want a clickable icon → use ScButton in icon-only mode
+<ScButton
+  styleVariant="icon-only"
+  icon={<SiconCollapse size={20} />}
+  variant="mono"
+  type="tertiary"
+  size="md"
+  onClick={toggleSidebar}
+  aria-label="Collapse sidebar"
+/>
+
+// You want the rail's collapse control → StreamoidSidebar already renders it
+<StreamoidSidebar
+  expanded={expanded}
+  onToggle={() => setExpanded((v) => !v)}
+  config={config}
+  iconMap={iconMap}
+  toggleIcon={(isExpanded) => <SiconCollapse style={{ transform: isExpanded ? undefined : "rotate(180deg)" }} />}
+/>
+
+// You genuinely only want a padded, hover-tinted icon box (decorative)
+<ScSidebarIcons instance={<SiconSupport />} />
+```
+
+---
+
+## 2. Where to use it
+
+Nowhere. It has exactly two composition sites, both inside the design system and both
+in the legacy family:
+
+- `src/SC-version/ScVersion.tsx:34` and `:49` — the collapse chevron in the old rail's
+  version footer.
+- `src/SC-Sidebar/ScSidebar.tsx:250` — passed into `ScVersion`'s `component` slot.
+
+The current rail's collapse control lives inside `StreamoidSidebar` (driven by
+`onToggle` / `toggleIcon` / `toggleInProfile`) and is a real interactive element.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Never in new code. If you catch yourself wanting it, you want a clickable icon.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A clickable bare icon affordance, any icon | `ScButton styleVariant="icon-only" icon={…}` |
+| Specifically a settings-cog affordance | `ScOnlyIcon` — but be aware its icon is hardcoded to `SiconSettings` |
+| The sidebar collapse/expand toggle | `StreamoidSidebar`'s `onToggle` + `toggleIcon` (or `toggleInProfile`) |
+| An icon + label nav row in a rail | `ScSidebarMenu` |
+| A trailing kebab on a nav row | `ScSidebarMenu`'s `moreIcon` + `onMoreClick` |
+| A product/app logo mark | `ScAppcardLogos` / `ScSideBarLogoUnit` / `ScStreamoidMascot` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScOnlyIcon` — spreads its props (so `onClick` works) but hardcodes `SiconSettings` and exposes no `icon` prop | `ScSidebarIcons` takes any icon but is completely inert. Neither is a good general choice — use `ScButton styleVariant="icon-only"`. |
+| `ScSidebarMenu` — the nav **row** (icon + label, five states) | this is just the icon chrome |
+| `ScAppcardLogos` — branded product marks | this holds any icon, unstyled |
+
+Note the plural: the folder is `SC-sidebar icons` and the export is `ScSidebarIcons`,
+but it renders **one** icon. There is no multi-icon component behind that name.
+
+---
+
+## 4. Why to use it
+
+You wouldn't. What it still encodes correctly:
+
+- The rail's icon-slot geometry: `spacing-md` (8 px) padding, `radius-3xl` corners, so
+  a footer icon lines up with the 40 px collapsed nav squares above it.
+- The hover fill token is `--alias-fill-neutral-neutral` — the same one
+  `ScSidebarMenu`, `ScSidebarSwitchMenu` and `ScSidebarProfile` use, so hovers across
+  the rail match.
+
+`ScButton styleVariant="icon-only"` gives you comparable geometry *plus* a click path,
+keyboard handling and `aria-disabled` wiring.
+
+---
+
+## Gotchas
+
+**1. Props are silently dropped.** The component destructures `...props` and then never
+uses it. The root div receives only `className`.
+
+```tsx
+// WRONG — will not compile (no onClick on IScSidebarIconsProps) and would be
+// dropped even if it did
+<ScSidebarIcons instance={<SiconCollapse />} onClick={toggleSidebar} />
+
+// RIGHT
+<ScButton
+  styleVariant="icon-only"
+  icon={<SiconCollapse size={20} />}
+  variant="mono"
+  type="tertiary"
+  size="md"
+  onClick={toggleSidebar}
+  aria-label="Collapse sidebar"
+/>
+
+// WORKAROUND if you must keep this component: wrap it
+<div role="button" tabIndex={0} onClick={toggleSidebar} aria-label="Collapse sidebar">
+  <ScSidebarIcons instance={<SiconCollapse />} />
+</div>
+```
+
+**2. `instance` defaults to `<SiconSupport />`.** A live-support headset appears if you
+forget it, or typo the prop name (it's `instance`, not `icon`).
+
+**3. Interactive-looking, non-interactive.** There is a `:hover` background rule but no
+`cursor: pointer`, no `role`, no `tabIndex`. Users will try to click it.
+
+**4. No icon normalisation.** Unlike `ScButton`, your icon is rendered as-is — no
+`cloneElement`, no `currentColor`, no `strokeWidth`. Set the icon's own `size` and
+`color`, and size the box by wrapping or overriding via `className`.
+
+**5. `className` produces a literal `undefined` class when omitted.**
+`styles.scSidebarIcons + " " + className + " " + variantsClassName`.
+
+**6. `state="hover"` is design parity only** — and `ScVersion`'s expanded branch passes
+`state="hover"` unconditionally, so the old rail's collapse chevron is permanently
+hover-skinned. Don't copy that.
+
+**7. No intrinsic size.** The box is content-sized: `display: flex` + 8 px padding
+around whatever `instance` measures. Two `ScSidebarIcons` with differently-sized icons
+will be different sizes.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+Composed only inside the legacy family:
+
+```tsx
+// npm-components  packages/ui/src/SC-version/ScVersion.tsx:49
+<ScSidebarIcons
+  instance={<SiconCollapse className={styles.siconCollapseInstance} />}
+  state="hover"
+  className={styles.scSidebarIconsInstance}
+/>
+```
+
+Where it *would* belong — an icon affordance in a sidebar footer — is now
+`ScButton styleVariant="icon-only"`, or the collapse button `StreamoidSidebar` renders
+itself.
+
+---
+
+## Related
+
+- `ScButton` (`styleVariant="icon-only"`) — the clickable replacement. Use this.
+- `ScOnlyIcon` — spreads props but hardcodes `SiconSettings`; only for a settings cog.
+- `StreamoidSidebar` — owns the collapse toggle via `onToggle` / `toggleIcon`.
+- `ScVersion` — the legacy footer that composes this; also legacy.
+- `ScSidebarMenu` — the current, stable rail row.
+- `@streamoid/icons` — every `Sicon*`; check `packages/icons/ICONS.md` before drawing
+  a new one.

package/dist/docs/ScSidebarMenu.md

@@ -0,0 +1,283 @@
+---
+component: ScSidebarMenu
+package: "@streamoid/ui"
+category: sidebar
+status: stable
+renders: div
+tags: [sidebar, nav, menu-item, nav-row, rail, collapsed, active, more-icon, kebab]
+related: [StreamoidSidebar, ScSidebarSwitchMenu, ScSettingsNav, ScMenuOptions, ScSideBarLogoUnit]
+do_not_confuse_with: [ScSidebarSwitchMenu, ScSidebar, ScMenuOptions, ScSettingsTabComp]
+used_by: [cxo, photogenix, catalogix, artifax]
+---
+
+# ScSidebarMenu
+
+**One nav row in a sidebar rail.** Icon + label + an optional hover-only kebab, as a
+40 px-high pill that has an `active` skin, two "sort of active" skins, and a
+40 × 40 collapsed square. This is the only piece of the old à-la-carte sidebar family
+that is still current — every desktop sidebar in the product is built out of it.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are laying out sidebar nav rows yourself, or building a
+  vertical nav that isn't the app rail (e.g. a settings nav, a panel's section list).
+- **Don't reach for it when:** you want a whole app sidebar — use `StreamoidSidebar`
+  (it renders these rows for you from `config` + `iconMap`), or the branded
+  `ScCatalogixSidebar` / `ScArtifaxSidebar`. Don't reach for `ScSidebar` (legacy,
+  hardcoded).
+- **Four things that will bite you:**
+  1. It's a plain `<div>` with `cursor: pointer` — **no `role`, no `tabIndex`, no key
+     handling**. Keyboard and screen-reader users get nothing unless you wrap it.
+  2. `variant="collapsed"` **drops the label entirely** and adds no `title`. There is
+     no built-in tooltip — hosts add their own.
+  3. `icon` defaults to `<SiconHome />`. Forget it and you ship a house.
+  4. `moreIcon` is `display: none` until `:hover`. It is unreachable on touch.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSidebarMenu } from "@streamoid/ui";
+import { SiconDot } from "@streamoid/icons";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScSidebarMenu
+  icon={<SiconDot size={24} />}
+  text="Insights"
+  state={isActive ? "active" : "default"}
+  variant={expanded ? "expanded" : "collapsed"}
+  onClick={() => go("insights")}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `icon` | `JSX.Element` | `<SiconHome />` | ⚠️ Has a real default. Always rendered, in both variants. Clamped to 20 × 20 by CSS (`.scSidebarMenu > :first-child`) whatever size you pass the icon. |
+| `text` | `string` | `"Menu Item"` | ⚠️ Has a real default. **Only rendered when `variant="expanded"`.** Single line, `text-overflow: ellipsis`. |
+| `state` | `"default"` \| `"active"` \| `"hover"` \| `"default-highlight"` \| `"default-active"` | `"default"` | See the state table below. |
+| `variant` | `"expanded"` \| `"collapsed"` | `"expanded"` | `collapsed` = fixed 40 × 40 square, icon centred, label and kebab omitted. |
+| `moreIcon` | `ReactNode` | – | Trailing kebab/overflow affordance. **`expanded` only**, and hidden until the row is hovered. |
+| `onMoreClick` | `(e: React.MouseEvent) => void` | – | Fires from the `moreIcon` wrapper; the wrapper calls `stopPropagation()` first, so the row's `onClick` does **not** also fire. |
+| `className` | `string` | – | Appended after the internal class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div — this is how `onClick`, `style`, `aria-*`, `data-*`, `key` reach the DOM. |
+
+### What each `state` renders
+
+| `state` | Background | Label colour | Used for |
+|---|---|---|---|
+| `default` | none (hover → `fill-neutral-neutral`) | tertiary | an ordinary row |
+| `active` | `fill-neutral-neutralselected` | primary | the currently open item |
+| `hover` | `fill-neutral-neutral` (forced) | tertiary | Figma parity / screenshots. Also force-reveals `moreIcon`. |
+| `default-highlight` | none | primary | "has unread / needs attention" — brighter text, no fill |
+| `default-active` | `surface-canvas` + a 0.5 px inset ring | primary | this section is the active one but the real selection is a child item |
+
+### Recipes
+
+```tsx
+// The standard host loop — expanded/collapsed off one boolean
+{items.map((item) => (
+  <ScSidebarMenu
+    key={item.id}
+    icon={iconMap[item.iconKey]}
+    text={expanded ? item.label : undefined}   // collapsed hides it anyway
+    state={item.id === activeId ? "active" : "default"}
+    variant={expanded ? "expanded" : "collapsed"}
+    onClick={() => onItemSelect(item)}
+  />
+))}
+
+// A row with an overflow menu (rename / delete on a chat thread)
+<ScSidebarMenu
+  icon={<SiconDot size={24} />}
+  text={conversation.title}
+  state={unread ? "default-highlight" : "default"}
+  variant="expanded"
+  moreIcon={<SiconMore size={20} color="var(--alias-text---icons-tertiary)" />}
+  onMoreClick={() => setMenuOpenFor(conversation.id)}
+/>
+
+// Collapsed rail + your own tooltip (the component supplies none)
+<Tooltip.Root delayDuration={120}>
+  <Tooltip.Trigger asChild>
+    <div style={{ display: "inline-flex" }}>
+      <ScSidebarMenu icon={<SiconBilling />} variant="collapsed" onClick={goBilling} />
+    </div>
+  </Tooltip.Trigger>
+  <Tooltip.Content side="right">Billing</Tooltip.Content>
+</Tooltip.Root>
+```
+
+---
+
+## 2. Where to use it
+
+- **Inside `StreamoidSidebar`** — it already renders one per `config` item and per
+  `topItems` entry; you normally never call it directly there. `ScCatalogixSidebar`
+  and `ScArtifaxSidebar` do the same.
+- **Ad-hoc nav lists a host owns** — CXO's recents/chat list and Catalogix's
+  workspace-service list are rendered by the host as `bodyContent` and pass
+  `ScSidebarMenu` rows through.
+- **`ScSettingsNav`** composes three of them (Profile / Workspace / Referral).
+- **Any vertical nav that should match the rail** — a panel's section list, a drawer's
+  navigation column.
+
+Direct host call sites exist in CXO, Catalogix and Photogenix. Artifax gets it
+indirectly through `ScArtifaxSidebar`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You need a **single nav row** and you are composing the rail yourself.
+- You want the expanded/collapsed geometry, the five state skins and the hover-kebab
+  behaviour to match the shared sidebar exactly.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| You want the whole sidebar (logo, sections, profile, collapse toggle, app switcher) | `StreamoidSidebar` |
+| The whole sidebar, pre-branded for Catalogix / Artifax | `ScCatalogixSidebar` / `ScArtifaxSidebar` |
+| A row that also needs a **secondary description line** (app-switch list) | `ScSidebarSwitchMenu` |
+| A row inside a floating popup/dropdown menu | `ScMenuOptions` |
+| A horizontal tab strip | `ScTabs` / `ScTabSwitcher` / `ScSettingsTabComp` |
+| The sidebar's logo/product-switch header row | `ScSideBarLogoUnit` |
+| A mobile navigation surface | `ScMobileTopNav` / `ScMobileBottomAction` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSidebarSwitchMenu` — same row shape but with `text` **and** `description`, square hover fill, used for the app-switch list | `ScSidebarMenu` is one line only |
+| `ScSidebar` — the **legacy** whole-sidebar mock with hardcoded nav | This is the row primitive, and it is current |
+| `ScMenuOptions` — a popup menu row (has `version` and `error` variants) | Different surface entirely |
+| `StreamoidSidebar` — the current shell that renders these rows | Reach for the shell first |
+
+---
+
+## 4. Why to use it
+
+- **The five states are the product's whole nav vocabulary.** `active`,
+  `default-highlight` (unread) and `default-active` (section active, child selected)
+  are three genuinely different visual answers that hosts got wrong by hand; they are
+  one prop here.
+- **Expanded ↔ collapsed geometry is already right.** Collapsed is a fixed 40 × 40
+  square with the icon optically centred, and the icon is clamped to 20 px regardless
+  of the `size` you pass — so a rail of mixed icons never jitters.
+- **Token-driven.** Fills come from `--alias-fill-neutral-*`, text from
+  `--alias-text-and-icons-*`, so light mode works with no conditionals.
+- **One place to change.** `StreamoidSidebar`, `ScCatalogixSidebar`,
+  `ScArtifaxSidebar` and `ScSettingsNav` all render this row, so a shape change lands
+  in every app's nav at once.
+
+---
+
+## Gotchas
+
+**1. No a11y wiring at all.** The root is `<div className=… onClick=…>` — no
+`role="button"`, no `tabIndex`, no `onKeyDown`, no `aria-current`. It is not
+reachable by keyboard.
+
+```tsx
+// WRONG — mouse-only nav
+<ScSidebarMenu text="Billing" onClick={goBilling} />
+
+// RIGHT — supply the semantics yourself until the DS does
+<ScSidebarMenu
+  text="Billing"
+  onClick={goBilling}
+  role="link"
+  tabIndex={0}
+  aria-current={isActive ? "page" : undefined}
+  onKeyDown={(e) => (e.key === "Enter" || e.key === " ") && goBilling()}
+/>
+```
+
+**2. Collapsed rows have no label and no tooltip.** `variant="collapsed"` renders the
+icon only; there is no `title` attribute. Every host wraps it in its own tooltip
+(CXO uses Radix). Do the same or your collapsed rail is unlabelled.
+
+**3. `icon` defaults to `<SiconHome />` and `text` to `"Menu Item"`.** Both are real
+defaults — a mistyped prop name gives you a house labelled "Menu Item" rather than an
+error. Note that hosts idiomatically pass `text={expanded ? label : undefined}`, which
+*does* fall back to `"Menu Item"` — harmless only because collapsed never renders it.
+
+**4. There is no "no icon" row.** `icon` is typed `JSX.Element`, and omitting it (or
+passing `undefined`) falls back to `<SiconHome />` — there is no supported way to
+render a label-only row. If you force a falsy icon past the type, the label becomes the
+first child and the clamp rule `.scSidebarMenu > :first-child { width: 1.25rem;
+height: 1.25rem }` applies to your text instead.
+
+**5. `moreIcon` is hover-only.** `.moreIconWrapper` is `display: none` and only
+becomes `flex` on `:hover` (or `state="hover"`). There is no focus-visible reveal, so
+it cannot be reached by keyboard or on a touch device.
+
+**6. `onMoreClick` swallows the row click.** The wrapper calls `stopPropagation()`, so
+clicking the kebab does not also fire the row's `onClick`. That's usually what you
+want — just don't wire the same handler to both.
+
+**7. `moreIcon` is ignored when collapsed.** It lives inside the
+`variant === "expanded"` branch. So does `text`.
+
+**8. `className` is concatenated unguarded.** When you omit `className` the rendered
+class list literally contains `undefined`
+(`ScSidebarMenu_scSidebarMenu undefined ScSidebarMenu_state-default …`). Harmless in
+the browser, but it will show up in DOM snapshots and class-name assertions.
+
+**9. Your icon's colour is *not* normalised.** Unlike `ScButton`, this component does
+not `cloneElement` your icon — it renders it as-is. Only the label colour tracks
+`state`; you must colour the icon yourself (every host does:
+`color={active ? "var(--alias-text---icons-primary)" : "var(--alias-text---icons-muted)"}`).
+
+**10. `state="hover"` is for design parity.** Real `:hover` already works. Don't wire
+it to mouse handlers.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/app-sidebar.tsx:773
+<ScSidebarMenu
+  icon={<SiconDot size={24} color={iconColor} />}
+  text={conversation.title}
+  state={menuState}
+  variant="expanded"
+  onClick={() => handleOpenConversation(conversation.id)}
+  moreIcon={
+    <SiconMore size={20} color="var(--alias-text---icons-tertiary)" />
+  }
+  onMoreClick={() =>
+    setMenuOpenFor(menuOpenFor === conversation.id ? null : conversation.id)
+  }
+/>
+```
+
+Also: `catalogix/dashboard app/containers/LeftMenu/index.jsx:815`,
+`photogenix_v2/dashboard/client/src/components/layout/Sidebar.tsx:840`,
+and internally at
+`packages/ui/src/SC-Sidebar-new/streamoid-sidebar.tsx:173`.
+
+---
+
+## Related
+
+- `StreamoidSidebar` (`SC-Sidebar-new`) — the current shell; renders these rows from
+  `config` + `iconMap`. Start here.
+- `ScSidebarSwitchMenu` — two-line sibling for the app-switch list.
+- `ScSideBarLogoUnit` — the rail's logo + product-switch header row.
+- `ScSettingsNav` — a small stack of three of these rows.
+- `ScSidebar` / `ScLogoUnit` / `ScSidebarProfile` / `ScSidebarIcons` / `ScVersion` —
+  the **legacy** parts of this family; all superseded by `StreamoidSidebar`.
+- `ScMenuOptions` — the popup-menu row, not a rail row.