@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScSideBarLogoUnit.md

@@ -0,0 +1,340 @@
+---
+component: ScSideBarLogoUnit
+also_exports: [ProductWordmark, ProductCollapsedMark, hasCollapsedMark]
+package: "@streamoid/ui"
+category: sidebar
+status: stable
+renders: div > button[type="button"]
+tags: [logo, wordmark, sidebar-header, app-switcher, switch-product, chevron, brand, product-mark]
+related: [StreamoidSidebar, ScArtifaxSidebar, ScAppSwitchPanel, ScStreamoidWordmark, ScStreamoidMascot]
+do_not_confuse_with: [ScLogoUnit, ScStreamoidWordmark, ScStreamoidMascot, ScStrLogo, ScAppcardLogos, ScCxoCopilotLogo]
+used_by: [cxo, photogenix, catalogix, artifax]
+---
+
+# ScSideBarLogoUnit
+
+**The row at the top of every sidebar: the product wordmark plus the
+double-arrow "switch product" pill, as one click target.** Expanded it is a 64px-tall
+full-width row; collapsed it is a square product icon stacked above the same pill.
+Clicking anywhere on it fires your handler — which is always "open the app switcher".
+
+The folder also exports the branded marks it uses: `ProductWordmark`,
+`ProductCollapsedMark` and `hasCollapsedMark`.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are filling `StreamoidSidebar`/`ScArtifaxSidebar`'s
+  `expandedLogo` / `collapsedLogo` slots.
+- **Don't reach for it when:** you want a bare Streamoid wordmark in a page header
+  (→ `ScStreamoidWordmark`), the app-switch list itself (→ `ScAppSwitchPanel`), or
+  the pre-`StreamoidSidebar` logo part (→ `ScLogoUnit`, legacy).
+- **Four things that will bite you:**
+  1. `onClick` **and** `onSwitchClick` both fire on a single click. Wire exactly one,
+     or a functional `setState` toggle cancels itself out.
+  2. `wordmark` overrides `product` in **both** states — pass a *different* node per
+     state, not one node for both.
+  3. `product="CXO" | "Artifax" | "Photogenix"` with `state="collapsed"` renders
+     **nothing**. Only `Catalogix` and `Tactix` have collapsed marks.
+  4. The wrapper adds `padding-bottom: var(--spacing-md)` in the expanded state;
+     hosts kill it with `style={{ paddingBottom: 0 }}`.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import {
+  ScSideBarLogoUnit,
+  ProductWordmark,
+  ProductCollapsedMark,
+  hasCollapsedMark,
+  type SidebarProduct,
+} from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+// Built-in branded mark
+<ScSideBarLogoUnit product="Catalogix" onClick={() => setAppListOpen((v) => !v)} />
+
+// Your own art (the common case — most products pass their own logo component)
+<ScSideBarLogoUnit
+  wordmark={<ScStreamoidWordmark width={110} height={16} />}
+  onClick={() => setAppListOpen((v) => !v)}
+/>
+```
+
+### Props — `ScSideBarLogoUnit`
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `state` | `"expanded"` \| `"collapsed"` | `"expanded"` | Two different render branches, not a width change. |
+| `wordmark` | `ReactNode` | – | The mark to render. **Overrides `product` in both states.** Expanded: the stacked wordmark; collapsed: the square icon. |
+| `product` | `SidebarProduct` | – | Built-in branded mark. The five real keys are `"CXO"`, `"Catalogix"`, `"Artifax"`, `"Photogenix"`, `"Tactix"`. ⚠️ **`SidebarProduct` is not a literal union** — it is `keyof typeof WORDMARKS` over a `Record<string, Wordmark>`, so it widens to `string` and a typo compiles. Only used when `wordmark` is unset. |
+| `onClick` | `() => void` | – | Whole-row click. |
+| `onSwitchClick` | `() => void` | – | Back-compat alias. ⚠️ **Fires *alongside* `onClick`**, not instead of it. |
+| `switchAriaLabel` | `string` | ⚠️ `"Switch product"` | The button's `aria-label`, only applied when interactive. Hardcoded English default. |
+| `hideSwitch` | `boolean` | `false` | Drops the double-arrow pill. The design always shows it. |
+| `hover` | `boolean \| undefined` | `undefined` | `undefined` → CSS `:hover` drives it. `true` → force the hover background on (use while the switch panel is open). `false` → suppress the row background via an inline style. |
+| `disabled` | `boolean` | `false` | Sets the native `disabled` on the button and makes it non-interactive. |
+| `className` | `string` | – | Appended on the **outer wrapper**, not the button. |
+| `style` | `CSSProperties` | – | On the outer wrapper. |
+
+**Interactivity rule:** `interactive = !disabled && (!!onClick || !!onSwitchClick)`.
+With no handler you get a focusable `<button>` with `aria-disabled="true"`, no
+`aria-label` and no click — still visually hoverable.
+
+### Props — `ProductWordmark` / `ProductCollapsedMark`
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `product` | `SidebarProduct` | — | **Required.** Unknown product → returns `null`. |
+| `style` | `CSSProperties` | – | Merged over the base style (`display: block`, `color: var(--alias-text---icons-primary)`). |
+
+Both render an `<svg role="img" aria-label={product}>` whose paths are
+`fill="currentColor"`, so the mark follows the surrounding text colour and is
+theme-aware.
+
+| product | `ProductWordmark` (h × w) | `ProductCollapsedMark` |
+|---|---|---|
+| `CXO` | 32 × 56 | — (returns `null`) |
+| `Catalogix` | 32 × 117 | 40 × 40 |
+| `Artifax` | 32 × 90 | — (`null`) |
+| `Photogenix` | 32 × 144 | — (`null`) |
+| `Tactix` | 32 × 80 | 40 × 40 |
+
+`hasCollapsedMark(product: SidebarProduct): boolean` — check before relying on
+`ProductCollapsedMark` / `state="collapsed"` + `product`.
+
+### Recipes
+
+```tsx
+// The standard pair, driven from one bit of host state (CXO / Photogenix / Artifax)
+const [appListOpen, setAppListOpen] = useState(false);
+const toggle = () => setAppListOpen((v) => !v);
+
+<StreamoidSidebar
+  expandedLogo={
+    <ScSideBarLogoUnit
+      wordmark={<ScStreamoidWordmark width={110} height={16} />}
+      onClick={toggle}
+      switchAriaLabel="Switch product"
+      style={{ paddingBottom: 0 }}      // sits flush with the divider below
+    />
+  }
+  collapsedLogo={
+    <ScSideBarLogoUnit
+      state="collapsed"
+      wordmark={<ScStreamoidMascot size={40} />}
+      onClick={toggle}
+      hover={appListOpen ? true : undefined}   // stay lit while the panel is open
+    />
+  }
+  /* … */
+/>
+
+// Built-in marks, guarding the collapsed one
+<ScSideBarLogoUnit
+  state="collapsed"
+  {...(hasCollapsedMark(product)
+    ? { product }
+    : { wordmark: <MyOwnSquareMark /> })}
+  onClick={toggle}
+/>
+
+// Using the marks standalone (e.g. Catalogix passes them in explicitly)
+<ScSideBarLogoUnit state="expanded"  wordmark={<ProductWordmark product="Catalogix" />}      onClick={toggle} />
+<ScSideBarLogoUnit state="collapsed" wordmark={<ProductCollapsedMark product="Catalogix" />} onClick={toggle} />
+
+// Non-interactive brand row (no switcher in this app)
+<ScSideBarLogoUnit product="Photogenix" hideSwitch />
+```
+
+---
+
+## 2. Where to use it
+
+- **`expandedLogo` / `collapsedLogo` of `StreamoidSidebar`** — CXO, Photogenix and
+  Catalogix all do exactly this.
+- **`expandedLogo` / `collapsedLogo` of `ScArtifaxSidebar`** — same, wrapped in a
+  `ref`'d div so the host's portalled switch flyout can anchor to it.
+- It is the **trigger** for `ScAppSwitchPanel`: this component renders the affordance,
+  `ScAppSwitchPanel` renders the list, and the sidebar (or the host) positions it.
+- All four apps use it. It is part of the "universal core".
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- A sidebar needs its product identity **plus** an app-switch affordance in one row.
+- You want the hover choreography (row → `fill-neutral-neutral`, pill →
+  `fill-neutral-neutralplus`) to match the nav rows below it.
+- You need the expanded and collapsed brand treatments to stay in sync.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A Streamoid wordmark in a page header / auth screen | `ScStreamoidWordmark` (110×16 plain) or `ScStreamoidBrand` |
+| The mascot / collapsed Streamoid glyph on its own | `ScStreamoidMascot` |
+| Product art inside an app card | `ScAppcardLogos` |
+| The CXO Copilot lockup | `ScCxoCopilotLogo` |
+| The list of other products | `ScAppSwitchPanel` |
+| One switchable product row (icon + name + description) | `ScSidebarSwitchMenu` |
+| The pre-`StreamoidSidebar` logo part | `ScLogoUnit` — legacy, don't start there |
+| A workspace (not product) switcher | `ScWorkspaceSwitchCard` / `StreamoidWorkspaceSwitcher` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScLogoUnit` — legacy sidebar logo part, props are only `state` + `className` | `ScSideBarLogoUnit` is the current one (note the capital **B**) |
+| `ScStreamoidWordmark` — the plain 110×16 header wordmark | This is a whole interactive row with a switch pill |
+| `ScStreamoidMascot` — the square glyph you'd *pass in* as `wordmark` | Not a replacement for this row |
+| `ScAppSwitchPanel` — the panel this row opens | Different component, different folder |
+| `ProductWordmark` (this folder, `currentColor` SVG paths, 32px tall) vs the `SC-AppSwitch` wordmark assets (CSS-mask data URIs) | Two separate wordmark sets that are **not** interchangeable |
+
+---
+
+## 4. Why to use it
+
+- **One click target, correctly.** The design merged the wordmark and the switch
+  chevron into a single row; the pill inside is decorative (`<span>`, not a nested
+  button), so there is exactly one focus stop and no nested-interactive a11y bug.
+- **Real `<button type="button">`** with `aria-label`, `disabled` and `aria-disabled`
+  wired — unlike `StreamoidSidebar`'s own profile row, which is a `div`.
+- **Two-tone hover that survives light mode.** The row goes to
+  `--alias-fill-neutral-neutral` while the pill goes one step darker to
+  `--alias-fill-neutral-neutralplus`, so the pill stays visible against the new row
+  background in both themes. Getting this wrong is the classic "the chevron
+  disappears on hover in light mode" bug.
+- **The `hover` prop exists for a real reason.** While the app-switch panel is open
+  the row must *stay* lit even though the pointer has moved into the panel.
+  `hover={true}` does that without you touching CSS.
+- **`hover={false}`** lets you keep clicks but suppress the highlight (e.g. a
+  screenshot or a walkthrough overlay).
+- **Branded marks are tokenised, not baked.** `ProductWordmark` paths use
+  `currentColor` over `--alias-text---icons-primary`, so the wordmark inverts with
+  the theme instead of shipping two PNGs.
+
+---
+
+## Gotchas
+
+**1. `onClick` and `onSwitchClick` both fire, in that order.** `handleClick` calls
+both. CXO's source carries an explicit comment about this: a double-fire cancels a
+functional `setState` toggle out, so the panel never opens.
+
+```tsx
+// WRONG — toggles twice, net zero
+<ScSideBarLogoUnit onClick={toggle} onSwitchClick={toggle} />
+
+// RIGHT — pick one; onClick is the idiomatic choice
+<ScSideBarLogoUnit onClick={toggle} />
+```
+
+**2. `wordmark` wins over `product` in *both* states.** The same node is used for the
+expanded wordmark and the collapsed square, so reusing one node gives you a 117px-wide
+wordmark inside a 56px rail. Always pass state-specific art.
+
+```tsx
+// WRONG — the wide wordmark overflows the collapsed rail
+<ScSideBarLogoUnit state="collapsed" wordmark={<ProductWordmark product="Catalogix" />} />
+
+// RIGHT
+<ScSideBarLogoUnit state="collapsed" wordmark={<ProductCollapsedMark product="Catalogix" />} />
+```
+
+**3. Most products have no collapsed mark, and a typo'd `product` is not a type
+error.** `COLLAPSED_MARKS` contains only `Catalogix` and `Tactix`.
+`ProductCollapsedMark` returns `null` for the rest, so
+`<ScSideBarLogoUnit state="collapsed" product="CXO" />` renders an empty (but still
+clickable) button with just the pill. And because `SidebarProduct` resolves to
+`string` (the tables are typed `Record<string, …>`), `product="catalogix"`
+(lowercase) also compiles and renders nothing — the lookup is case-sensitive.
+Guard with `hasCollapsedMark(product)`.
+
+**4. The expanded wrapper has bottom padding you probably don't want.**
+`.scSideBarLogoUnit { padding-bottom: var(--spacing-md) }`. CXO and Catalogix both
+pass `style={{ paddingBottom: 0 }}` so the row sits flush against the switch card's
+divider.
+
+**5. Fixed geometry.** The expanded row is `height: 4rem` (64px) with asymmetric
+padding (16px left, 12px right), and the wordmark slot is a fixed `2rem` tall
+`inline-flex`. Nothing is `overflow: hidden`, so an over-tall logo visually overlaps
+the neighbouring content rather than being clipped. Keep marks ≤32px tall.
+
+**6. `hover={false}` doesn't stop the *pill* from reacting.** The inline
+`backgroundColor: transparent` applies to the row only; the CSS rule
+`.row:hover .switch` still swaps the pill to `neutralplus` on real mouse hover.
+
+**7. `className` lands on the wrapper `div`, not the button.** Styling `.row`
+requires a descendant selector (Photogenix does this with `.ph-sidebar-logo`).
+
+**8. The accessible name can double up.** `ProductWordmark` renders
+`<svg role="img" aria-label={product}>` *inside* a button that carries
+`aria-label={switchAriaLabel}`. The button's label wins, but if you pass your own
+`wordmark` with its own text, check what a screen reader actually announces.
+
+**9. `switchAriaLabel` disappears when non-interactive.** With no `onClick` /
+`onSwitchClick`, `aria-label` is `undefined` and `aria-disabled="true"` — but the
+`<button>` is still in the tab order unless you also pass `disabled`.
+
+**10. `hideSwitch` is a design deviation, not a mode.** The comment in the source is
+explicit: "rare; the design always shows it".
+
+**11. The two wordmark systems are different.** This folder's `wordmarks.tsx` holds
+inline SVG **path** data (`currentColor`, theme-tinted). `SC-AppSwitch/wordmarks.ts`
+holds base64/URI-encoded SVGs used as **CSS masks**, and those are **not exported**
+from the package. Don't try to import `CATALOGIX` / `ARTIFAX` etc. from
+`@streamoid/ui`.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/app-sidebar.tsx:75
+<ScSideBarLogoUnit
+  wordmark={<ScStreamoidWordmark width={110} height={16} />}
+  // ScSideBarLogoUnit fires both onClick and onSwitchClick on a single
+  // click, so wire the toggle through exactly one prop to avoid a
+  // double-fire that cancels a functional setState toggle out.
+  onClick={onClick}
+  switchAriaLabel="Switch product"
+  // Drop the unit's bottom padding so it sits flush with the switch card's
+  // divider / the divider below it.
+  style={{ paddingBottom: 0 }}
+/>
+```
+
+```jsx
+// catalogix/dashboard  app/containers/LeftMenu/index.jsx:1031  (collapsed, built-in mark)
+<ScSideBarLogoUnit
+  state="collapsed"
+  wordmark={<ProductCollapsedMark product="Catalogix" />}
+  onClick={() => setAppListOpen((v) => !v)}
+  switchAriaLabel="Switch app"
+/>
+```
+
+Also: `photogenix_v2 dashboard/client/src/components/layout/Sidebar.tsx:745`
+(one helper returning both states, `hover={appListOpen ? true : undefined}`) and
+`artifax packages/shared/src/components/DashboardSidebar.tsx:660`.
+
+---
+
+## Related
+
+- `StreamoidSidebar` / `ScArtifaxSidebar` — the two slots this fills.
+- `ScAppSwitchPanel` — the list this row opens.
+- `ScStreamoidWordmark` / `ScStreamoidMascot` (SC-Brand) — the nodes CXO passes as `wordmark`.
+- `ScSidebarSwitchMenu` — a single switchable-product row (the older switcher vocabulary).
+- `ScLogoUnit` — the legacy predecessor; don't start new work there.
+- `@streamoid/icons` — `SiconDoubleArrow` is the pill glyph, rendered at 16px, strokeWidth 1.5.

package/dist/docs/ScSidebar.md

@@ -0,0 +1,243 @@
+---
+component: ScSidebar
+package: "@streamoid/ui"
+category: sidebar
+status: legacy
+renders: div
+tags: [sidebar, rail, nav, legacy, deprecated, figma-export, expanded, collapsed, shell]
+related: [StreamoidSidebar, ScCatalogixSidebar, ScArtifaxSidebar, ScSidebarMenu, ScSideBarLogoUnit]
+do_not_confuse_with: [StreamoidSidebar, ScSidebarMenu, ScCatalogixSidebar, ScArtifaxSidebar, ScMobileTopNav]
+---
+
+# ScSidebar
+
+**Legacy. Superseded by `StreamoidSidebar` (`src/SC-Sidebar-new`). Do not use it in new
+code.** It is a verbatim Figma export of the original CXO rail: every nav label,
+section header, chat title and icon is **hardcoded in the JSX**. It accepts no items,
+no config, no handlers — the only prop that changes anything is `state`.
+
+## TL;DR for agents
+
+- **Reach for it when:** never, in product code. It exists so old imports keep
+  resolving, and as a pixel reference for the original design.
+- **Reach for this instead:** `StreamoidSidebar` (data-driven: `config` + `iconMap` +
+  `topItems` + `profile` + `switchPanel`), or the branded `ScCatalogixSidebar` /
+  `ScArtifaxSidebar`.
+- **Four things that will bite you:**
+  1. The nav is **hardcoded**: "New chat", "Apps / Artifax / Photogenix / Catalogix",
+     "Management / Teams / Billing", "Recents / Chat 1 / Chat 2 / Chat 3 / View all",
+     "Live support". "Artifax" is always the active row. There is no items prop.
+  2. `onToggle` is typed and accepted but **never called**. Dead prop.
+  3. `...props` is destructured and then **never spread** — `onClick`, `style`,
+     `id`, `data-*` are all silently dropped.
+  4. The root has a hardcoded `height: 62.5rem` (1000 px). It does not fill its parent.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSidebar } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+// Everything inside is fixed. This is the entire API surface.
+<ScSidebar state="expanded" />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `state` | `"expanded"` \| `"collapsed"` | `"expanded"` | The only functional prop. Picks between two completely separate hardcoded trees. |
+| `className` | `string` | – | Concatenated onto the root. ⚠️ Unguarded — omitting it puts a literal `undefined` in the class list. |
+| `onToggle` | `(state: "expanded" \| "collapsed") => void` | – | ⚠️ **Never invoked.** Declared, destructured, discarded. Nothing in the component calls it. |
+| `...props` | `Omit<HTMLAttributes<HTMLDivElement>, "onToggle">` | – | ⚠️ **Not spread onto the root.** Typed as accepted, then dropped on the floor. |
+
+### What renders in each state
+
+| Region | `expanded` (16 rem card) | `collapsed` (icon rail) |
+|---|---|---|
+| Header | `ScLogoUnit` (full Streamoid wordmark, 240 px wide) | `ScLogoUnit state="collapsed"` (wordmark squeezed to 32 × 12) |
+| Top item | "New chat" + `SiconPlus` | same, icon-only |
+| Section 1 | header "Apps " + Artifax (**active**) / Photogenix / Catalogix | same three icons, no header, `ScHDivider` above |
+| Section 2 | header "Management " + Teams / Billing | same two icons |
+| Section 3 | header "Recents " + Chat 1 / Chat 2 / Chat 3 / "View all" | same four icons |
+| Pre-footer | "Live support" + `SiconSupport` | same, icon-only |
+| Profile | `ScSidebarProfile` → renders `ScProfile` with **no props** → "Chris Hemsworth / Kepler workspace" and a broken `profile-image0.png` | same, in a 3 rem box |
+| Footer | `ScVersion` → "v2.1.2" + a non-clickable collapse chevron | `ScVersion state="collapsed"` |
+
+### Recipes
+
+There are none. There is nothing to configure. If you are here because you need a
+sidebar, this is the replacement:
+
+```tsx
+import { StreamoidSidebar, type SidebarConfig, type SidebarIconMap } from "@streamoid/ui";
+
+<StreamoidSidebar
+  expanded={expanded}
+  onToggle={() => setExpanded((v) => !v)}
+  config={sidebarConfig}                    // sections + items, JSON-shaped
+  iconMap={iconMap}                         // iconKey -> node/renderer
+  topItems={[{ id: "new-chat", label: "New chat", iconKey: "plus" }]}
+  activeItemId={activeId}
+  onItemSelect={(item) => go(item.id)}
+  expandedLogo={<ScSideBarLogoUnit product="CXO" onClick={openSwitcher} />}
+  collapsedLogo={<ScSideBarLogoUnit state="collapsed" product="CXO" onClick={openSwitcher} />}
+  profile={{ name, subtitle, avatar: <img src={photoUrl} alt="" />, onClick: openProfilePopup }}
+  versionText="v2.1.2"
+  switchPanel={<ScAppSwitchPanel apps={apps} />}
+  switchPanelOpen={appListOpen}
+  onSwitchPanelClose={() => setAppListOpen(false)}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+Nowhere in production. Its only remaining value:
+
+- **Design reference** — a single file that shows the original rail's spacing, divider
+  placement and section rhythm.
+- **Import compatibility** — it is still exported from `src/index.ts`, so old code that
+  imports the name still compiles.
+
+Every desktop app has converged on `StreamoidSidebar` + `ScAppSwitchPanel`: CXO
+(`src/app/components/app-sidebar.tsx:965`), Photogenix
+(`dashboard/client/src/components/layout/Sidebar.tsx:855`), Catalogix
+(`app/containers/LeftMenu/index.jsx:991` — directly on `StreamoidSidebar`, *not*
+via `ScCatalogixSidebar`), Artifax
+(`packages/shared/src/components/DashboardSidebar.tsx:641`, via `ScArtifaxSidebar`).
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Never. If you think you have a case, you want `StreamoidSidebar`.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Any real app sidebar | `StreamoidSidebar` (`SC-Sidebar-new`) |
+| A Catalogix-branded sidebar with its default nav + credit card | `ScCatalogixSidebar` |
+| An Artifax-branded sidebar | `ScArtifaxSidebar` |
+| Just one nav row, composing the rail yourself | `ScSidebarMenu` |
+| The logo + product-switch header row | `ScSideBarLogoUnit` |
+| The app-switch list | `ScAppSwitchPanel` (+ `ScSidebarSwitchMenu` rows) |
+| A mobile navigation surface | `ScMobileTopNav` / `ScMobileBottomAction` |
+| A settings-page vertical nav | `ScSettingsNav` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `StreamoidSidebar` — the current, data-driven shell, exported from the same package | `ScSidebar` is the frozen predecessor with the same-ish name |
+| `ScSidebarMenu` — one nav row, **stable and current** | `ScSidebar` is the whole legacy rail |
+| `ScCatalogixSidebar` / `ScArtifaxSidebar` — branded shells built on `StreamoidSidebar` | not built on this |
+
+Name collision warning: `ScSidebar` and `StreamoidSidebar` differ by one word and live
+in the same barrel export. Autocomplete will offer you the wrong one.
+
+---
+
+## 4. Why to use it
+
+You wouldn't. For completeness, what you *lose* by using it instead of
+`StreamoidSidebar`: any nav data, active-item tracking, unread highlighting,
+collapse/expand behaviour, the app-switch overlay, the assistant CTA, a real profile
+row, the credit-warning slot, `bodyContent`, mobile behaviour, and every callback.
+
+What it does still demonstrate correctly (expanded state): the `surface-base` card,
+its `border-subtle` 1 px border, `radius-3xl` corners, `spacing-md` gutters, the
+divider positions, and the 50 %-opacity `text-xs` section headers. (Collapsed draws no
+card — just a 1 px `border-subtle` right edge.)
+
+---
+
+## Gotchas
+
+**1. `onToggle` does nothing.** It type-checks, so this looks like it works:
+
+```tsx
+// WRONG — the callback is never called; the sidebar cannot collapse itself
+const [state, setState] = useState<"expanded" | "collapsed">("expanded");
+<ScSidebar state={state} onToggle={setState} />
+
+// RIGHT — the shell that actually reports toggles
+<StreamoidSidebar expanded={expanded} onToggle={() => setExpanded((v) => !v)} … />
+```
+
+**2. `...props` never reaches the DOM.** The root `<div>` receives only `className`.
+So `onClick`, `style`, `id`, `ref`-adjacent attributes and `data-*` are dropped. You
+cannot even size it from the outside via `style`.
+
+**3. Hardcoded 1000 px height.** `.scSidebar { height: 62.5rem }`. In a real layout it
+either overflows the viewport or leaves a gap; and since `style` is dropped (Gotcha 2)
+you can only fix it with a `className` override.
+
+**4. `className` produces a literal `undefined` class when omitted.**
+`styles.scSidebar + " " + className + " " + variantsClassName`.
+
+**5. It ships placeholder identity.** `ScSidebarProfile` is rendered with no props, so
+the footer says **"Chris Hemsworth" / "Kepler workspace"** with a broken
+`profile-image0.png`, and `ScVersion` prints **"v2.1.2"**. There is no way to pass real
+values through.
+
+**6. Every label is English and baked in.** No `labels`/`items`/`config` prop exists.
+Localising or renaming a single nav item means editing the DS.
+
+**7. "Artifax" is always `state="active"`.** Both trees hardcode it. No prop changes
+the selection.
+
+**8. The collapsed tree fights its own children.** `.scSidebar.state-collapsed
+.scSidebarMenuInstance` unsets `display`, `padding`, `flex-direction`, `gap`,
+`align-items`, `height` and `position` on the nested `ScSidebarMenu` — a Figma-export
+artifact. Any change to `ScSidebarMenu`'s own CSS can break the collapsed rail here in
+ways it won't break anywhere else.
+
+**9. The collapse chevron is decorative.** It goes through `ScVersion` →
+`ScSidebarIcons`, and `ScSidebarIcons` does not spread props, so nothing is clickable.
+
+**10. Two different `ScSidebarIcons` shapes.** `expanded` passes `component={<ScSidebarIcons …/>}`
+*and* `scSidebarIconsinstance`, while `collapsed` passes only
+`scSidebarIconsinstance` — and `ScVersion` ignores **both** in its expanded branch.
+Don't take this call site as a usage example for `ScVersion`.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+More precisely: **no render site at all.** Nothing in `@streamoid/ui`, CXO, Catalogix,
+Photogenix or Artifax renders `ScSidebar`; it is exported and unused
+(`packages/ui/src/index.ts:35`). Where it *would* belong — the desktop app rail — is
+now occupied by:
+
+```tsx
+// cxo-dashboard  src/app/components/app-sidebar.tsx:965  (the real rail)
+<StreamoidSidebar expanded={sidebarExpanded} onToggle={onToggle} config={…} iconMap={iconMap} … />
+```
+
+---
+
+## Related
+
+- `StreamoidSidebar` (`SC-Sidebar-new`) — **the replacement.** Read
+  `src/SC-Sidebar-new/README.md`.
+- `ScCatalogixSidebar` / `ScArtifaxSidebar` — branded shells over `StreamoidSidebar`.
+- `ScSidebarMenu` — the one part of this old family that is still current.
+- `ScSideBarLogoUnit` — replaces `ScLogoUnit` for the header row.
+- `ScAppSwitchPanel` — replaces the inline app list.
+- `ScLogoUnit` / `ScSidebarProfile` / `ScSidebarIcons` / `ScVersion` — the other
+  legacy parts this file composes; all superseded.