@streamoid/ui 0.6.17 → 0.6.19

package/dist/docs/StreamoidSidebar.md

@@ -0,0 +1,413 @@
+---
+component: StreamoidSidebar
+package: "@streamoid/ui"
+category: sidebar
+status: stable
+renders: div
+tags: [sidebar, nav, shell, rail, collapse, expand, app-shell, switcher, primary-navigation]
+related: [ScSideBarLogoUnit, ScAppSwitchPanel, ScSidebarMenu, ScAskAgentButton, CreditWarningBanner, ScArtifaxSidebar]
+do_not_confuse_with: [ScSidebar, ScArtifaxSidebar, ScCatalogixSidebar, ScSidebarMenu, ScLogoUnit]
+used_by: [cxo, photogenix, catalogix]
+required_props: [expanded, onToggle, config, iconMap]
+also_exports: [ScSidebarResizeHandle, advanceSidebarResizeGesture, SIDEBAR_RESIZE_THRESHOLD_PX]
+---
+
+# StreamoidSidebar
+
+**The current shared sidebar shell for every desktop Streamoid app.** It renders the
+rounded 256px rail (or the 56px collapsed rail), a logo slot, the nav, an optional
+gradient assistant CTA, a pre-footer slot, the profile row and the collapse toggle —
+plus the app-switch panel as an *overlay* so opening it never pushes the nav down.
+
+Note the name: it is **not** `Sc`-prefixed. `ScSidebar` is a different, legacy component.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building (or fixing) a desktop app's primary
+  left navigation and you want the same chrome CXO, Photogenix and Catalogix use.
+- **Don't reach for it when:** you are in Artifax (→ `ScArtifaxSidebar`, which owns
+  collapsible sections), you want one nav row (→ `ScSidebarMenu`), or you want the
+  product-switch list itself (→ `ScAppSwitchPanel`).
+- **Five things that will bite you:**
+  1. `versionText` defaults to **`"v1.0.0"`** — a fake version string. Every host
+     passes `versionText=""`.
+  2. `bodyContent` is **ignored unless `showBody` is `true`**, and when it renders
+     it **replaces** `config.sections` entirely.
+  3. `toggleInProfile` puts the collapse toggle inside the profile row — so with
+     `toggleInProfile` and **no `profile`, there is no toggle at all**.
+  4. `config` and `iconMap` are **required** even when you drive the whole nav
+     through `bodyContent`. Pass `{ sections: [] }` and `{}`.
+  5. Layout comes from **Tailwind utility class names** (`flex`, `shrink-0`,
+     `truncate`, `min-w-0`, `overflow-y-auto`). `dist/index.css` does **not** ship
+     them — your app must have Tailwind (all three hosts do).
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import {
+  StreamoidSidebar,
+  type SidebarConfig,
+  type SidebarIconMap,
+} from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+const config: SidebarConfig = {
+  sections: [{ id: "main", label: "Manage", items: [{ id: "stores", label: "Stores", iconKey: "bag" }] }],
+};
+const iconMap: SidebarIconMap = { bag: <SiconBag /> };
+
+<StreamoidSidebar
+  expanded={expanded}
+  onToggle={() => setExpanded((v) => !v)}
+  config={config}
+  iconMap={iconMap}
+  activeItemId="stores"
+  onItemSelect={(item) => navigate(`/${item.id}`)}
+  versionText=""                       // else you ship "v1.0.0"
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `expanded` | `boolean` | — | **Required.** You own the state. `true` → 256px rounded card; `false` → 56px rail. Two completely different render branches. |
+| `onToggle` | `() => void` | — | **Required.** Fired by the collapse toggle (and the mobile close icon). |
+| `resizable` | `boolean` | `false` | Shows the shared 12px right-edge resize handle on desktop. The rail still has only expanded and collapsed widths. |
+| `onExpandedChange` | `(expanded: boolean) => void` | – | Controlled resize callback. One drag may call it more than once as the pointer reverses; omit it to fall back to `onToggle`. |
+| `config` | `SidebarConfig` | — | **Required.** `{ topItem?, sections, bottomItems? }`. Pass `{ sections: [] }` if you drive nav via `bodyContent`. |
+| `iconMap` | `SidebarIconMap` | — | **Required.** `Record<iconKey, ReactNode \| ({item, active, expanded}) => ReactNode>`. A missing key renders **no icon**, silently. |
+| `activeItemId` | `string` | – | Matching item gets `state="active"`. |
+| `highlightedItemIds` | `Set<string>` | – | Items get `state="default-highlight"`. ⚠️ Only honoured for `topItems` in the **expanded** rail — see Gotcha 8. |
+| `onItemSelect` | `(item, sectionId?) => void` | – | `sectionId` is `"top"`, `"bottom"`, or the section's `id`. |
+| `moreIcon` | `ReactNode` | – | Trailing "…" affordance on a row. ⚠️ Expanded rail passes it to **top items only**. |
+| `onMoreClick` | `(item, sectionId?) => void` | – | Same restriction as `moreIcon`. |
+| `topItems` | `SidebarMenuItemConfig[]` | – | Stacked items above the first divider. **Supersedes `config.topItem`.** |
+| `topItemStates` | `Record<string, "default" \| "active" \| "hover" \| "default-highlight" \| "default-active">` | – | Per-id override; wins over `activeItemId` / `highlightedItemIds`. Top items only. |
+| `expandedLogo` | `ReactNode` | – | Slot. Normally a `ScSideBarLogoUnit state="expanded"`. |
+| `collapsedLogo` | `ReactNode` | – | Slot. Normally a `ScSideBarLogoUnit state="collapsed"`. |
+| `profile` | `SidebarProfileConfig` | – | `{ name, subtitle?, avatar?, onClick? }`. Footer row (expanded) / avatar only (collapsed). |
+| `versionText` | `string` | `"v1.0.0"` | ⚠️ **Real default.** Pass `""` to hide (all hosts do). Empty string still renders the footer wrapper + toggle. |
+| `toggleIcon` | `ReactNode \| ((expanded: boolean) => ReactNode)` | – | No default glyph — omit it and the toggle is an **invisible click target**. |
+| `toggleInProfile` | `boolean` | `false` | Footer = profile (flex-1) + a separate toggle button beside it, no version line. Expanded only. Requires `profile`. |
+| `hideFooter` | `boolean` | `false` | Hides the version/toggle footer. ⚠️ Asymmetric with `isMobile` — see Gotcha 6. |
+| `assistantCta` | `AssistantCta \| null` | – | Renders `ScAskAgentSlot` (the gradient "Ask CXO" pill / collapsed square) above `preFooterContent`. |
+| `preFooterContent` | `ReactNode` | – | Slot between the nav and the bottom items — where `CreditWarningBanner` goes. |
+| `bodyContent` | `ReactNode` | – | Slot replacing the whole sections area. **Only rendered when `showBody`.** |
+| `showBody` | `boolean` | `false` | ⚠️ Gate for `bodyContent`. `false` → your body is dropped and `config.sections` renders instead. |
+| `switchPanel` | `ReactNode` | – | The app-switch list (normally `ScAppSwitchPanel`). Mounted whenever supplied **and `!isMobile`**, so open/close can animate. |
+| `switchPanelOpen` | `boolean` | `false` | Drives the open styling, the backdrop and `pointer-events`. |
+| `onSwitchPanelClose` | `() => void` | – | Fired by the dim backdrop (expanded) / the fixed click-catcher (collapsed). |
+| `isMobile` | `boolean` | `false` | Moves the toggle into the logo row, forces `hideFooter` in the expanded branch, and **disables `switchPanel` entirely**. |
+| `className` | `string` | – | Appended on the **outer** wrapper, not the card. |
+| `style` | `CSSProperties` | – | Merged **after** the wrapper's padding in the expanded branch, so `style={{ padding: 0 }}` wins. |
+
+### Types
+
+```ts
+interface SidebarMenuItemConfig { id: string; label?: string; iconKey: string }
+interface SidebarSectionConfig  { id: string; label?: string; items: SidebarMenuItemConfig[] }
+interface SidebarConfig         { topItem?: SidebarMenuItemConfig; sections: SidebarSectionConfig[]; bottomItems?: SidebarMenuItemConfig[] }
+interface SidebarProfileConfig  { name: string; subtitle?: string; avatar?: ReactNode; onClick?: () => void }
+type SidebarIconRenderer = (ctx: { item: SidebarMenuItemConfig; active: boolean; expanded: boolean }) => ReactNode;
+type SidebarIconMap = Record<string, ReactNode | SidebarIconRenderer>;
+```
+
+### What renders in each rail
+
+| Region | `expanded` | `expanded` + `isMobile` | collapsed |
+|---|---|---|---|
+| Outer | 16px padding wrapper → 256px card, 16px radius, 1px subtle border overlay | same | no padding, 56px-ish rail, right border only |
+| Logo row | `expandedLogo` (+ toggle only when `isMobile`) | + close/toggle icon on the right | `collapsedLogo` |
+| Top items | `topItems ?? config.topItem`, wrapped in two dividers | same | same, tighter gaps |
+| Body | `showBody ? bodyContent : config.sections` (labels shown) | same | `showBody ? bodyContent : config.sections` (**labels dropped**) |
+| Assistant CTA | `ScAskAgentSlot` pill | pill | `ScAskAgentSlot collapsed` square |
+| Pre-footer | `preFooterContent` | same | same |
+| Bottom items | `config.bottomItems` | same | same |
+| Footer | profile + (toggle inline, or version + toggle) | footer hidden (`isMobile`) | avatar, then toggle + `versionText` (56px wide) |
+| Switch panel | animated drop-down inside a bordered card + 90% backdrop dim | **not rendered** | 240px flyout at `left: calc(100% + 8px)`, fixed transparent click-catcher |
+
+### Recipes
+
+```tsx
+// The idiomatic host wiring (what CXO, Photogenix and Catalogix all do):
+// nav rendered through bodyContent, empty config, no version, toggle in profile.
+<StreamoidSidebar
+  expanded={!collapsed}
+  onToggle={() => setCollapsed((v) => !v)}
+  config={{ sections: [] }}
+  iconMap={{}}
+  showBody
+  bodyContent={<MyNav collapsed={collapsed} />}
+  expandedLogo={<ScSideBarLogoUnit wordmark={<MyWordmark />} onClick={toggleAppList} />}
+  collapsedLogo={<ScSideBarLogoUnit state="collapsed" wordmark={<MyMark />} onClick={toggleAppList} hover={appListOpen ? true : undefined} />}
+  switchPanel={apps.length ? <ScAppSwitchPanel apps={apps} /> : undefined}
+  switchPanelOpen={appListOpen}
+  onSwitchPanelClose={() => setAppListOpen(false)}
+  profile={{ name, subtitle: workspace, avatar: <ScDp type="initial" initial={initial} size={32} />, onClick: openProfile }}
+  versionText=""
+  toggleInProfile
+  toggleIcon={(exp) => <SiconCollapse size={20} style={exp ? undefined : { transform: "rotate(180deg)" }} />}
+/>
+
+// Config-driven nav (the JSON path — see sidebar-config.example.json)
+<StreamoidSidebar
+  expanded={expanded}
+  onToggle={toggle}
+  config={sidebarConfigJson as SidebarConfig}
+  iconMap={{ plus: <SiconPlus />, dot: ({ active }) => <Dot on={active} /> }}
+  activeItemId={activeId}
+  onItemSelect={(item, sectionId) => route(sectionId, item.id)}
+  versionText=""
+/>
+
+// Gradient assistant CTA + low-credits banner in the pre-footer
+<StreamoidSidebar
+  /* … */
+  assistantCta={{ label: "Ask CXO", icon: <SiconBolt size={20} color="currentColor" />, active: askOpen, onClick: toggleAsk }}
+  preFooterContent={
+    lowCredits ? (
+      <CreditWarningBanner
+        availableCredits={credits}
+        remainingPct={Math.round(pct)}
+        level="danger"
+        expanded={expanded}
+        onBuyCredits={goBilling}
+        onCollapsedClick={onToggle}
+      />
+    ) : undefined
+  }
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **The primary left navigation of every desktop app.** CXO
+  (`src/app/components/app-sidebar.tsx`), Photogenix
+  (`dashboard/client/src/components/layout/Sidebar.tsx`) and Catalogix
+  (`app/containers/LeftMenu/index.jsx`) each render exactly one, at the root of
+  their app shell.
+- It composes, or expects you to compose into its slots:
+  `ScSideBarLogoUnit` (logo slots), `ScAppSwitchPanel` (`switchPanel`),
+  `ScSidebarMenu` (rendered internally from `config`, or by you inside
+  `bodyContent`), `ScAskAgentSlot` (from `assistantCta`),
+  `CreditWarningBanner` (`preFooterContent`), `ScDp` (`profile.avatar`).
+- `ScCatalogixSidebar` is a thin wrapper around it. Artifax deliberately does
+  **not** use it (`ScArtifaxSidebar` instead).
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You need the shared app-shell rail: 256/56px, rounded card, dividers, profile
+  footer, collapse toggle, animated app-switch overlay.
+- You want the app switcher to behave identically everywhere — as an overlay,
+  never pushing the nav down.
+- Your nav is either a plain data structure (`config`) *or* app-specific enough
+  that you'd rather render it yourself (`bodyContent`) while keeping the chrome.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Artifax's sidebar (collapsible labelled sections, no `switchPanel`) | `ScArtifaxSidebar` |
+| Catalogix with default Stores/AI-Training/Insights nav | `ScCatalogixSidebar` (a wrapper — but Catalogix now composes `StreamoidSidebar` directly) |
+| One nav row | `ScSidebarMenu` |
+| One product-switch row (icon + name + description) | `ScSidebarSwitchMenu` |
+| The product-switch list itself | `ScAppSwitchPanel` |
+| The logo + switch chevron row | `ScSideBarLogoUnit` |
+| Mobile top bar / bottom action bar | `ScMobileTopNav` / `ScMobileBottomAction` |
+| A settings-page left nav | `ScSettingsNav` / `ScSettingsTabComp` |
+| The workspace switcher | `ScWorkspaceSwitchCard` / `StreamoidWorkspaceSwitcher` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSidebar` — a legacy, pre-`StreamoidSidebar` shell with only `state` + `onToggle` | `StreamoidSidebar` is the current one |
+| `ScSidebarMenu` — one row | This is the whole rail |
+| `ScLogoUnit` — legacy logo part | Use `ScSideBarLogoUnit` |
+| `ScSidebarProfile` / `ScSidebarSwitchMenu` — à-la-carte legacy parts | This renders the profile row itself |
+| `ScArtifaxSidebar` — sibling shell, **not** a wrapper of this one | Different props (`sections`, `openSections`), no `switchPanel` |
+| `ScCatalogixSidebar` — **is** a wrapper of this one | Hides most props behind Catalogix defaults |
+
+---
+
+## 4. Why to use it
+
+- **The two rails are already correct.** Expanded and collapsed are separate
+  render branches with different padding, gaps, divider rules and footer layout.
+  Reimplementing that from a design spec is a day of pixel-chasing.
+- **The switch-panel overlay is the hard part, and it's done.** Expanded, it
+  animates via `grid-template-rows: 0fr → 1fr` inside an absolutely-positioned
+  card so it floats instead of pushing the nav down; the rest of the rail dims to
+  90%. Collapsed, it becomes a 240px flyout with a fixed transparent click-catcher.
+  Both stay mounted so *closing* animates too.
+- **Slot design, not a fork.** Every app has a different nav; `bodyContent`,
+  `preFooterContent`, `switchPanel` and the logo slots let you keep the chrome and
+  own the content, which is why all three apps converged on one component.
+- **Token-only surfaces.** `--alias-surface-base`, `--alias-border-subtle`,
+  `--alias-fill-neutral-neutral` for hover — it flips to light mode with no
+  conditionals in your code.
+- **Layout-stable toggling.** The switch card uses `inset box-shadow` rather than
+  `border` so opening it can't shift a single pixel of the card below.
+
+---
+
+## Gotchas
+
+**1. `versionText` defaults to `"v1.0.0"`.** A hardcoded fake version in your
+production nav. Every host passes `""`.
+
+```tsx
+// WRONG — ships "v1.0.0"
+<StreamoidSidebar expanded onToggle={t} config={c} iconMap={m} />
+
+// RIGHT
+<StreamoidSidebar expanded onToggle={t} config={c} iconMap={m} versionText="" />
+```
+
+**2. `bodyContent` needs `showBody`, and then it replaces `config.sections`.**
+
+```tsx
+// WRONG — body silently dropped, empty sections render instead
+<StreamoidSidebar config={{ sections: [] }} bodyContent={<MyNav />} … />
+
+// RIGHT
+<StreamoidSidebar config={{ sections: [] }} showBody bodyContent={<MyNav />} … />
+```
+
+**3. `toggleInProfile` without `profile` removes the toggle entirely.** The
+expanded footer is either *(profile + inline toggle)* or *(version + toggle)*;
+`toggleInProfile` selects the first branch, and that branch only renders inside
+`profile ? … : null`. No profile → no collapse affordance at all.
+
+**4. There is no default `toggleIcon`.** `resolveToggleIcon` returns `null` when
+`toggleIcon` is omitted, so the toggle becomes an invisible (but clickable) box.
+Always pass a glyph, and rotate it yourself for the collapsed state.
+
+**5. The logo → nav divider is only drawn on the `topItems` path.** With no
+`topItems`/`config.topItem` and `showBody`, nothing separates the logo from your
+body — which is why all three hosts emit their own `<ScHDivider />` as the first
+child of `bodyContent`.
+
+**6. `hideFooter` and `isMobile` are asymmetric.** Expanded uses
+`hideFooter || isMobile`; the **collapsed** branch checks `hideFooter` only. A
+collapsed mobile rail still renders the version/toggle footer.
+
+**7. `switchPanel` is dead when `isMobile`.** `hasSwitchCard = !!(switchPanel && !isMobile)`
+— so on mobile the logo row's own toggle is your only affordance, and
+`onSwitchPanelClose` never fires.
+
+**8. `moreIcon` / `onMoreClick` / `highlightedItemIds` are dropped for section and
+bottom items in the *expanded* rail.** They are only forwarded to `topItems` there,
+while the collapsed rail forwards them everywhere. A "…" menu that appears when
+collapsed and vanishes when expanded is this, not your code.
+
+```tsx
+// Expanded sections get no more-menu. Render your rows yourself if you need one:
+<StreamoidSidebar showBody bodyContent={
+  items.map((i) => <ScSidebarMenu key={i.id} text={i.label} moreIcon={<SiconMore />} onMoreClick={…} />)
+} … />
+```
+
+**9. Section labels only exist in the expanded rail.** `SectionHeader` isn't
+rendered in the collapsed branch — don't put meaning-bearing text there only.
+
+**10. The profile row and the collapse toggle are `div`s with `onClick`.** No
+`<button>`, no `tabIndex`, no keyboard access, and hover is wired through
+`onMouseEnter`/`onMouseLeave` writing inline styles. The root is a plain `div` with
+no `<nav>`/`aria-label`; wrap it yourself:
+
+```tsx
+<nav aria-label="Main navigation"><StreamoidSidebar … /></nav>
+```
+
+**11. Widths are hardcoded.** Expanded card `width: 256`, inside a
+`var(--spacing-3xl)` padded wrapper (≈288px footprint); the collapsed footer block
+is `width: 56`. Not responsive, not overridable via props — hosts measure these
+constants themselves.
+
+The optional resize edge is a two-state gesture, not a free-width splitter.
+After either state change it re-anchors at the crossing point, so the user can
+collapse and expand again in the same uninterrupted drag. Hosts should pass a
+controlled setter: `onExpandedChange={setExpanded}`. In the collapsed state,
+the 12px hit target straddles the rail boundary and its blue line renders just
+outside the rail; expanded positioning remains on the wrapper's outside edge.
+
+**12. Tailwind utilities are a hard requirement.** The component's structure is
+`className="flex flex-col flex-1 min-h-0 overflow-y-auto shrink-0 truncate …"` with
+inline styles only for colours/spacing. `dist/index.css` ships the
+`.text-text-*` typography classes but **none** of those utilities, and no
+`.sidebar-scroll` rule either (that class is a hook for the host to style the
+scrollbar). Without Tailwind the rail collapses and labels stop truncating.
+
+**13. The collapsed flyout is `position: absolute` inside the rail.** Any host
+ancestor with `overflow: hidden` will clip it. Hosts that can't guarantee that
+(Artifax) portal their own flyout to `document.body` instead.
+
+**14. `iconMap` misses fail silently.** A wrong `iconKey` yields `null` — in the
+collapsed rail that is a blank, still-clickable row.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/app-sidebar.tsx:965
+<StreamoidSidebar
+  expanded={sidebarExpanded}
+  onToggle={onToggle}
+  isMobile={isMobile}
+  showBody={showCopilotPanel}
+  config={isMobile ? MOBILE_SIDEBAR_CONFIG : BASE_SIDEBAR_CONFIG}
+  iconMap={iconMap}
+  onItemSelect={onItemSelect}
+  expandedLogo={<ExpandedLogo onClick={toggleAppList} />}
+  collapsedLogo={
+    <div style={{ paddingBottom: "var(--spacing-md)" }}>
+      <CollapsedLogo onClick={toggleAppList} open={appListOpen} />
+    </div>
+  }
+  bodyContent={sidebarContent}
+  switchPanel={switchPanelContent}
+  switchPanelOpen={appListOpen}
+  onSwitchPanelClose={() => setAppListOpen(false)}
+  preFooterContent={creditWarning ? <CreditWarningBanner … /> : undefined}
+  profile={{ name: displayName, subtitle: displayWorkspace, avatar: <ProfileAvatar … />, onClick: … }}
+  versionText=""
+  toggleInProfile
+  toggleIcon={(exp) => <SiconCollapse className="size-5" style={exp ? undefined : { transform: "rotate(180deg)" }} />}
+/>
+```
+
+Also: `catalogix/dashboard app/containers/LeftMenu/index.jsx:991` (adds
+`assistantCta` + `activeItemId`), and
+`photogenix_v2 dashboard/client/src/components/layout/Sidebar.tsx:854`
+(`preFooterContent` carries an upgrade CTA + low-credits node).
+
+---
+
+## Related
+
+- `ScSideBarLogoUnit` — what goes in `expandedLogo` / `collapsedLogo`.
+- `ScAppSwitchPanel` — what goes in `switchPanel`.
+- `ScSidebarMenu` — the row this renders from `config`; render it yourself inside `bodyContent`.
+- `ScAskAgentButton` / `ScAskAgentSlot` — what `assistantCta` renders.
+- `CreditWarningBanner` — the usual `preFooterContent`.
+- `ScArtifaxSidebar` — the sibling shell used by Artifax.
+- `ScCatalogixSidebar` — a Catalogix-flavoured wrapper of this component.
+- `ScSidebar` / `ScLogoUnit` / `ScSidebarProfile` / `ScSidebarSwitchMenu` — legacy parts this replaced.
+- `sidebar-config.example.json` (this folder) — a complete `SidebarConfig` to copy.