@streamoid/ui 0.6.17 → 0.6.19

package/dist/docs/ScCatalogixInvite.md

@@ -0,0 +1,345 @@
+---
+component: ScCatalogixInvite
+package: "@streamoid/ui"
+category: cards
+status: stable
+renders: div
+tags: [invite, app-access, catalogix, toggle, store-access, permissions, user-management, settings, search, checkbox-list]
+related: [ScArtifaxInvite, ScPhtogenixInvite, ScAppCard, ScToggleSwitch, ScPairtext, ScOnlyField]
+do_not_confuse_with: [ScArtifaxInvite, ScPhtogenixInvite, ScAppCard, ScAppListingCard, ScAccess, ScCatalogixStoreTableList, ScCheckField]
+---
+
+# ScCatalogixInvite
+
+**The Catalogix access row *plus* its store-scoping panel.** Same header as the
+other invite rows — `ScAppCard` + `ScToggleSwitch` — and when the toggle is on it
+reveals a nested panel: "Store access", an *N* Selected count, a search field, and
+a checkbox list of stores. The only member of the invite trio with a sub-scope.
+
+## TL;DR for agents
+
+- **Reach for it when:** you're building the per-app access list in an invite /
+  edit-user flow and the Catalogix row has to pick **which stores** the user can see.
+- **Don't reach for it when:** access is a plain on/off (→ `ScArtifaxInvite`), it's
+  the Photogenix row (→ `ScPhtogenixInvite`), or you want a standalone
+  searchable multi-select that isn't bolted to an app toggle (→ `ScOnlyField` +
+  `ScPairtext`, or `ScCheckField`).
+- **Five things that will bite you:**
+  1. ⚠️ Omit `stores` and you ship **five dummy rows labelled "Pairtext"** — the
+     Figma placeholder. Pass `stores` (even `[]`) always.
+  2. It does **not** filter. `searchValue`/`onSearchChange` are a plain controlled
+     input; *you* filter `stores` before passing them.
+  3. Pass `searchValue` without `onSearchChange` and the search box is read-only.
+  4. The store list has **no max-height and no overflow** — 300 stores means a
+     300-row-tall modal. Cap it yourself.
+  5. ⚠️ Unlike its two siblings it defaults to **OFF** (`active = "false"`) and it
+     draws **no bottom divider**.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScCatalogixInvite } from "@streamoid/ui";
+import { SiconCatalogix } from "@streamoid/icons";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScCatalogixInvite
+  enabled={catalogixOn}
+  onToggle={setCatalogixOn}
+  appIcon={<SiconCatalogix size={24} />}
+  appDescription="Catalog enrichment and feeds"
+  stores={visibleStores}                 // already filtered by your search
+  selectedStores={selectedStoreIds}
+  onStoreToggle={toggleStore}
+  searchValue={storeSearch}
+  onSearchChange={setStoreSearch}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `enabled` | `boolean` | – | The real on/off. Overrides `active` whenever defined. **Use this one.** Also the switch that reveals the store panel. |
+| `active` | `"true"` \| `"false"` | `"false"` | ⚠️ Figma-variant leftover, a *string*. Consulted only when `enabled` is `undefined`. Defaults **off** — the opposite of `ScArtifaxInvite`/`ScPhtogenixInvite`. |
+| `onToggle` | `(active: boolean) => void` | – | Fires with the **next** value. Omit it and the row can never be expanded. |
+| `appName` | `string` | `"Catalogix"` | ⚠️ Real default. Passed to `ScAppCard`. |
+| `appDescription` | `string` | `"Info about catalogix"` | ⚠️ Real default, and it is placeholder copy. |
+| `appIcon` | `JSX.Element` | `<SiconArtifacts />` | ⚠️ The **wrong brand's** icon by default — pass `<SiconCatalogix />`. |
+| `stores` | `{ id: string; name: string }[]` | – | ⚠️ Undefined ≠ empty. Undefined renders 5 placeholder rows; `[]` renders "No stores found". |
+| `selectedStores` | `string[]` | – | Ids that render checked. Also **replaces** `selectedCount` with `` `${selectedStores.length} Selected` ``. |
+| `onStoreToggle` | `(storeId: string) => void` | – | Fires on a store row click. You compute the next selection. |
+| `searchValue` | `string` | – | Value of the search input. Controlled — see Gotcha 3. |
+| `onSearchChange` | `(query: string) => void` | – | Fires on every keystroke. The component does **no** filtering. |
+| `storeAccessTitle` | `string` | `"Store access"` | Panel heading. Truncates with ellipsis (`flex: 1`, `nowrap`). |
+| `selectedCount` | `string` | `"0 Selected"` | Right-hand count. **Ignored whenever `selectedStores` is passed.** |
+| `searchPlaceholder` | `string` | `"Search stores..."` | Placeholder of the search input. |
+| `className` | `string` | – | Appended after internal classes. |
+| `...props` | `Omit<HTMLAttributes<HTMLDivElement>, "onToggle">` | – | Spread onto the root `<div>`. |
+
+### What renders in each state
+
+| Region | `enabled` false | `enabled` true |
+|---|---|---|
+| Header | `ScAppCard` + `ScToggleSwitch` | same |
+| Store-access panel | **not rendered at all** | canvas-base panel, 16px padding, radius 16 |
+| Panel header | — | `storeAccessTitle` + count (`selectedStores.length` if given, else `selectedCount`) |
+| Search | — | `ScOnlyField`, search icon on the **right**, `searchPlaceholder` |
+| List: `stores` non-empty | — | one `ScPairtext type="checkbox"` per store, name left / checkbox right |
+| List: `stores === []` | — | hardcoded "No stores found" |
+| List: `stores` undefined | — | ⚠️ five placeholder `ScPairtext` rows reading **"Pairtext"** |
+
+`storeAccessTitle`, `selectedCount`, `searchPlaceholder`, `stores`,
+`selectedStores`, `searchValue` and their handlers are all inert while the row is
+off — the whole panel is behind `isEnabled &&`.
+
+### Recipes
+
+```tsx
+// The full job: toggle + search + multi-select, with YOU doing the filtering
+const [catalogixOn, setCatalogixOn] = useState(false);
+const [storeSearch, setStoreSearch] = useState("");
+const [selected, setSelected] = useState<string[]>([]);
+
+const visibleStores = useMemo(
+  () =>
+    allStores
+      .map((s) => ({ id: s._id, name: s.name || s._id }))
+      .filter((s) => s.name.toLowerCase().includes(storeSearch.toLowerCase())),
+  [allStores, storeSearch],
+);
+
+<ScCatalogixInvite
+  enabled={catalogixOn}
+  onToggle={(next) => {
+    setCatalogixOn(next);
+    if (!next) setSelected([]);            // clearing on disable is YOUR job
+  }}
+  appIcon={<SiconCatalogix size={24} />}
+  appDescription="Catalog enrichment and feeds"
+  stores={visibleStores}
+  selectedStores={selected}
+  onStoreToggle={(id) =>
+    setSelected((prev) =>
+      prev.includes(id) ? prev.filter((x) => x !== id) : [...prev, id],
+    )
+  }
+  searchValue={storeSearch}
+  onSearchChange={setStoreSearch}
+/>
+
+// Cap the list height — the component never scrolls on its own
+<ScCatalogixInvite
+  /* …as above… */
+  className={styles.invite}
+/>
+```
+
+```css
+/* Target the DS class from your own stylesheet, or wrap and use a descendant
+   selector — the list container is the third child of the panel. */
+.invite [class*="storeListContainer"] { max-height: 240px; overflow-y: auto; }
+```
+
+```tsx
+// Loading state: pass [] (NOT undefined) so you get the empty state, not placeholders
+<ScCatalogixInvite
+  enabled={catalogixOn}
+  onToggle={setCatalogixOn}
+  stores={isLoading ? [] : visibleStores}
+  selectedStores={selected}
+  onStoreToggle={toggleStore}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **The invite-user modal's "App access" section**, as the Catalogix row — normally
+  last, because expanding it makes the modal grow.
+- **The edit-user / manage-access drawer**, pre-populated with the user's current
+  store scope.
+- Any **app-access + resource-scope** pairing with the same shape (app on/off, then
+  "which of these N things").
+
+It composes `ScAppCard`, `ScToggleSwitch`, `ScOnlyField` (search) and `ScPairtext`
+(checkbox rows), with a two-tone nesting: the panel sits on
+`--alias-surface-canvasbase` and the list on `--alias-fill-neutral-neutralplus`, so
+it reads as inset in both themes.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Granting the app is **not** enough — the user also needs a subset of stores.
+- The scope list is short enough to show inline (or you cap the height yourself).
+- You want the row to line up with the other app rows in the same modal.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Access is a plain boolean, no sub-scope | `ScArtifaxInvite` |
+| The Photogenix row | `ScPhtogenixInvite` (prefixed `scAppCardapp*` props) |
+| A searchable multi-select that isn't attached to an app toggle | `ScOnlyField` + `ScPairtext`, or `ScCheckField` |
+| A list of stores as a data table (owner, status, actions) | `ScCatalogixStoreTableList` |
+| Read-only "which apps does this user have" | `ScAccess` |
+| App icon + name + description, no toggle | `ScAppCard` |
+| A launcher/marketing card for the app | `ScAppListingCard` / `ScAppCardV3` |
+| Checkboxes with real form semantics (labels, keyboard) | `ScCheckField` / `ScCheckbox` |
+| Hundreds of options needing virtualisation | build your own list — this one renders every row |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScArtifaxInvite` — header-only row, defaults **ON**, draws a bottom divider | `ScCatalogixInvite` adds the store panel, defaults **OFF**, draws **no** divider |
+| `ScPhtogenixInvite` — header-only row with prefixed props and no DOM prop forwarding | This one uses clean `appName`/`appDescription`/`appIcon` and spreads `...props` |
+| `ScCatalogixStoreTableList` — the store **table** on Catalogix's own screens | This is a compact checkbox picker inside an invite modal |
+| `ScCheckField` — a labelled group of real checkboxes | The rows here are `ScPairtext` divs: no `<input>`, no keyboard |
+| `ScAccess` — three app icons, read-only | Not an editable control |
+
+All three invite components are app-agnostic apart from their default copy and
+icon. Choose by **shape**: no sub-scope → `ScArtifaxInvite`; sub-scope →
+`ScCatalogixInvite`.
+
+---
+
+## 4. Why to use it
+
+- **The disclosure logic is already right.** Toggle on → panel appears; toggle off →
+  the entire panel (and its search state's visual footprint) is gone, in one prop.
+  Hand-rolled versions leak a half-expanded panel or keep a stale search box mounted.
+- **Two-tone inset nesting that survives light mode.** Panel on
+  `surface-canvasbase`, list on `fill-neutral-neutralplus` — two distinct tokens
+  rather than a grey that collapses to white on a light canvas.
+- **Consistent count/heading typography.** Title is `text-sm-regular` primary,
+  count is `text-xs-regular` muted, both ellipsised — the exact spec, and the
+  detail most often missed when this row is rebuilt by hand.
+- **It matches its sibling rows for free**: same 16px padding, same `ScAppCard`
+  flex, same `ScToggleSwitch`.
+- **One place to change.** `@streamoid/settings` currently reimplements this whole
+  panel — local toggle, local search input, local store rows, the same
+  "Search stores..." and "No stores found" strings — in a single ~980-line modal.
+
+---
+
+## Gotchas
+
+**1. `stores` undefined renders five dummy "Pairtext" rows.** The Figma-placeholder
+branch is still in the component, and it renders unchecked checkbox rows whose
+label is `ScPairtext`'s own default (`"Pairtext"`), wired to nothing.
+
+```tsx
+// WRONG — five rows reading "Pairtext" appear the moment the toggle goes on
+<ScCatalogixInvite enabled onToggle={setOn} selectedStores={selected} />
+
+// RIGHT — pass an array, even while loading
+<ScCatalogixInvite enabled onToggle={setOn} stores={stores ?? []} selectedStores={selected} />
+```
+
+**2. It does not filter, sort, or paginate.** `onSearchChange` just reports
+keystrokes; the list renders exactly the `stores` array you pass. Filter upstream.
+
+```tsx
+// WRONG — typing changes nothing on screen
+<ScCatalogixInvite stores={allStores} searchValue={q} onSearchChange={setQ} … />
+
+// RIGHT
+<ScCatalogixInvite
+  stores={allStores.filter((s) => s.name.toLowerCase().includes(q.toLowerCase()))}
+  searchValue={q}
+  onSearchChange={setQ}
+  …
+/>
+```
+
+**3. `searchValue` without `onSearchChange` is a read-only input.** It's forwarded
+straight to a controlled `<input value>`; with no change handler, keystrokes are
+discarded. Pass both, or neither.
+
+**4. The store list never scrolls.** `.storeListContainer` sets no `max-height` and
+no `overflow`, so the panel grows with the data and pushes your modal footer off
+screen. Constrain it from your side (see the Recipes).
+
+**5. It defaults to OFF, and its siblings default to ON.** `active = "false"` here
+vs `"true"` in `ScArtifaxInvite`/`ScPhtogenixInvite`. Always pass `enabled` and
+stop thinking about `active`.
+
+**6. `selectedCount` is dead whenever `selectedStores` is present.** The component
+computes `` `${selectedStores.length} Selected` ``. The `" Selected"` suffix is
+hardcoded English; the only way to change the wording is to omit `selectedStores`
+and drive `selectedCount` yourself — which also loses the checked state.
+
+**7. The default `appIcon` is the Artifax icon.** `SiconArtifacts` is the fallback
+in all three invite components. Pass `<SiconCatalogix />`.
+
+**8. `"No stores found"` is not overridable,** and neither is the placeholder
+branch. Only `storeAccessTitle`, `selectedCount` and `searchPlaceholder` are props.
+Don't use this row in a localised surface without changing the DS first.
+
+**9. The search icon is on the right, and the left one is discarded.** The
+component passes both `tfLeftIcon` and `tfRightIcon` to `ScOnlyField` but never
+sets `tfGroup`, which defaults to `"icon-right"` — so only the right icon renders.
+You cannot move it or replace it.
+
+**10. Store rows are not accessible.** `ScPairtext` renders a `<div onClick>` with
+`cursor: pointer` and an `ScCheckbox` **visual** — no `<input>`, no `role`, no
+`tabIndex`, no label association. Keyboard users cannot select a store. Use
+`ScCheckField` if that matters.
+
+**11. No bottom divider.** Unlike the other two invite rows, `.scCatalogixInvite`
+has no border. Stack it after them and the separator sequence breaks — add your own
+`ScHDivider` or a border via `className`.
+
+**12. Turning the row off does not clear the selection.** `selectedStores` is your
+state; the panel simply unmounts. Reset it in `onToggle` if a disabled app should
+drop its scope.
+
+**13. `styles["active-false"]` doesn't exist.** Only `.active-true` is defined
+(it's what styles the whole panel), so in the OFF state the variant class resolves
+to `undefined` and lands in the class attribute as the literal `"undefined"`, as
+does an omitted `className`. Don't assert on the class list.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+The surface is real but hand-rolled in the shared settings package, which
+reimplements this component end to end:
+
+```tsx
+// @streamoid/settings  packages/settings/src/invite-update-modal.tsx:700
+{/* Catalogix row + store access */}
+// …~200 lines duplicating this component: local ToggleSwitch (line 84),
+// a hand-written search input with placeholder "Search stores..." (line 838),
+// filteredStores mapped to hand-rolled checkbox rows (line 867),
+// and the same "No stores found" empty state (line 901).
+```
+
+That modal — CXO settings → Teams → invite/edit user — is exactly where this
+component belongs; adopting it would delete the duplication.
+
+---
+
+## Related
+
+- `ScArtifaxInvite` — the plain header-only row; the cleanest API of the trio.
+- `ScPhtogenixInvite` — the Photogenix twin; prefixed `scAppCardapp*` props.
+- `ScAppCard` — the icon/name/description block in the header.
+- `ScToggleSwitch` — the switch, standalone.
+- `ScOnlyField` — the search field it renders; note `tfGroup` controls icon sides.
+- `ScPairtext` — the store rows; `type="checkbox"`, `iconPosition="right"`.
+- `ScCheckField` — reach for this when the multi-select needs real form semantics.

package/dist/docs/ScCatalogixSidebar.md

@@ -0,0 +1,337 @@
+---
+component: ScCatalogixSidebar
+package: "@streamoid/ui"
+category: sidebar
+status: legacy
+renders: div
+tags: [sidebar, catalogix, nav, shell, rail, wrapper, stores, ai-training, insights]
+related: [StreamoidSidebar, ScSideBarLogoUnit, ScSidebarSwitchMenu, ScAppSwitchPanel, CreditWarningBanner]
+do_not_confuse_with: [StreamoidSidebar, ScArtifaxSidebar, ScCatalogixInvite, ScCatalogixStoreHeader]
+required_props: [expanded, onToggle]
+---
+
+# ScCatalogixSidebar
+
+**A Catalogix-flavoured preset of `StreamoidSidebar`.** It hardcodes the Catalogix
+wordmark logo unit, a default Stores / AI Training / Insights nav, an inline
+app-switch list built from `ScSidebarSwitchMenu`, and the credit banner — so a caller
+only supplies `expanded` + callbacks.
+
+> **`status: legacy`.** Catalogix's own shell no longer uses it: as of the
+> 2026-07 redesign, `catalogix/dashboard app/containers/LeftMenu/index.jsx:991`
+> composes **`StreamoidSidebar` directly** — it needs `assistantCta` (the "Ask CXO"
+> gradient CTA), `activeItemId`-driven nav and `ScAppSwitchPanel`, none of which this
+> wrapper can express. **For new work, use `StreamoidSidebar`.**
+
+## TL;DR for agents
+
+- **Reach for it when:** essentially never in new code. It is useful mainly as a
+  worked example of how to preset `StreamoidSidebar`.
+- **Don't reach for it when:** you need the assistant CTA, the shared
+  `ScAppSwitchPanel` rows, the collapsed right-side switch flyout, `topItems`,
+  section labels, or a version footer — all unreachable through this wrapper
+  (→ `StreamoidSidebar`).
+- **Three things that will bite you:**
+  1. **There is no `assistantCta` prop.** You cannot render the "Ask CXO" gradient
+     CTA through this component, despite the component catalog implying otherwise.
+  2. `switchApps` rows are `ScSidebarSwitchMenu`, **not** `ScAppSwitchPanel` — a
+     different visual language from every other app's switcher.
+  3. `switchPanel` is only built when `expanded`, so the collapsed rail gets an
+     **inline icon list** instead of `StreamoidSidebar`'s right-side flyout, and no
+     backdrop.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import {
+  ScCatalogixSidebar,
+  type CatalogixNavItem,
+  type CatalogixSwitchApp,
+} from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+Everything except the two state props has a default:
+
+```tsx
+<ScCatalogixSidebar
+  expanded={expanded}
+  onToggle={() => setExpanded((v) => !v)}
+  activeItemId="stores"
+  onItemSelect={(item) => navigate(`/${item.id}`)}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `expanded` | `boolean` | — | **Required.** Forwarded to `StreamoidSidebar`. |
+| `onToggle` | `() => void` | — | **Required.** Also the fallback for the collapsed credit-banner click. |
+| `items` | `CatalogixNavItem[]` | ⚠️ `[Stores, AI Training, Insights]` | Real default: ids `stores` / `ai-training` / `insights`. |
+| `iconMap` | `CatalogixSidebarIconMap` | ⚠️ `SiconBag` / `SiconBrain` / `SiconInsights` | Real default, keyed `stores` / `aiTraining` / `insights`. Replacing `items` without replacing `iconMap` leaves rows **icon-less**. |
+| `activeItemId` | `string` | – | Matching row → `state="active"`; `active` is passed to the icon renderer. |
+| `onItemSelect` | `(item: CatalogixNavItem) => void` | – | No `sectionId` argument (unlike `StreamoidSidebar`). |
+| `switchApps` | `CatalogixSwitchApp[]` | – | `{ id, name, description?, icon?, onClick? }[]`. Omit to disable app switching. |
+| `onLogoClick` | `() => void` | – | Fires **in addition to** the internal open/close of the app list. |
+| `expandedLogo` | `ReactNode` | ⚠️ built-in `ScSideBarLogoUnit product="Catalogix"` | Overriding it **breaks the switcher** — the default node is what carries `onClick={handleSwitch}`. |
+| `collapsedLogo` | `ReactNode` | ⚠️ built-in collapsed Catalogix mark | Same caveat, plus you lose the `hover` highlight while the list is open. |
+| `profile` | `CatalogixSidebarProfile` | – | `{ name, subtitle?, avatar?, onClick? }`. **Required in practice** — see Gotcha 4. |
+| `creditWarning` | `CatalogixSidebarCreditWarning \| null` | – | `{ availableCredits, remainingPct, level?, onBuyCredits, onCollapsedClick? }`. `level` defaults to `"danger"`; `onCollapsedClick` defaults to `onToggle`. |
+| `toggleIcon` | `ReactNode \| ((expanded: boolean) => ReactNode)` | `SiconCollapse` / `SiconExpand`, muted, `size-6` | Real default, and it correctly swaps glyphs per state. |
+| `className` | `string` | – | Forwarded to `StreamoidSidebar`'s outer wrapper. |
+| `style` | `CSSProperties` | – | Forwarded likewise. |
+
+### Types
+
+```ts
+interface CatalogixNavItem { id: string; label: string; iconKey: string }
+interface CatalogixSwitchApp { id: string; name: string; description?: string; icon?: ReactNode; onClick?: () => void }
+interface CatalogixSidebarProfile { name: string; subtitle?: string; avatar?: ReactNode; onClick?: () => void }
+interface CatalogixSidebarCreditWarning {
+  availableCredits: number; remainingPct: number;
+  level?: "warning" | "danger";      // default "danger"
+  onBuyCredits: () => void;
+  onCollapsedClick?: () => void;     // defaults to onToggle
+}
+type CatalogixSidebarIconRenderer = (ctx: { active: boolean; expanded: boolean }) => ReactNode;
+```
+
+### What it hardcodes on `StreamoidSidebar`
+
+Anything in this list is **not reachable** through this wrapper:
+
+| `StreamoidSidebar` prop | Fixed value here |
+|---|---|
+| `config` | `{ sections: [] }` — no `topItems`, no `bottomItems`, no section labels |
+| `iconMap` | `{}` |
+| `showBody` / `bodyContent` | always on / the internal nav + collapsed switch list |
+| `switchPanel` | the `ScSidebarSwitchMenu` rows, **and only when `expanded`** |
+| `switchPanelOpen` / `onSwitchPanelClose` | internal `appListOpen` state |
+| `toggleInProfile` | `true` (so `profile` is mandatory in practice) |
+| `versionText` | `""` |
+| `preFooterContent` | the `CreditWarningBanner` |
+| `assistantCta` | **never passed — no way to set it** |
+| `isMobile`, `hideFooter`, `topItems`, `highlightedItemIds`, `moreIcon`, `onMoreClick` | never passed |
+
+### Recipes
+
+```tsx
+// The full intended wiring
+<ScCatalogixSidebar
+  expanded={expanded}
+  onToggle={() => setExpanded((v) => !v)}
+  activeItemId={currentSection}
+  onItemSelect={(item) => go(item.id)}
+  switchApps={otherProducts.map((p) => ({
+    id: p.id,
+    name: p.name,
+    description: p.desc,
+    icon: <ProductIcon product={p.id} />,
+    onClick: () => open(p.url),
+  }))}
+  onLogoClick={loadServiceCatalog}          // lazy-load the product list
+  profile={{ name, subtitle: workspace, avatar: <ScDp type="initial" initial={initial} size={32} />, onClick: openProfilePopup }}
+  creditWarning={low ? { availableCredits: credits, remainingPct: Math.round(pct), onBuyCredits: goBilling } : null}
+/>
+
+// Custom nav — replace items AND iconMap together
+<ScCatalogixSidebar
+  expanded={expanded}
+  onToggle={toggle}
+  items={[{ id: "feeds", label: "Feeds", iconKey: "feeds" }]}
+  iconMap={{
+    feeds: ({ active }) => (
+      <SiconUpload color={active ? "var(--alias-text---icons-primary)" : "var(--alias-text---icons-tertiary)"} />
+    ),
+  }}
+/>
+
+// What to write instead for anything non-trivial (this is what Catalogix ships):
+<StreamoidSidebar
+  expanded={expanded}
+  onToggle={toggle}
+  config={navConfig}
+  iconMap={iconMap}
+  activeItemId={currentSection}
+  showBody={!insideStore}
+  bodyContent={workspaceServiceBody}
+  switchPanel={apps.length ? <ScAppSwitchPanel apps={apps} /> : undefined}
+  switchPanelOpen={appListOpen}
+  onSwitchPanelClose={() => setAppListOpen(false)}
+  assistantCta={{ label: "Ask CXO", icon: <SiconBolt size={20} color="currentColor" />, active: askOpen, onClick: toggleAsk }}
+  expandedLogo={<ScSideBarLogoUnit wordmark={<ProductWordmark product="Catalogix" />} onClick={() => setAppListOpen((v) => !v)} />}
+  collapsedLogo={<ScSideBarLogoUnit state="collapsed" wordmark={<ProductCollapsedMark product="Catalogix" />} onClick={() => setAppListOpen((v) => !v)} />}
+  profile={profile}
+  toggleInProfile
+  versionText=""
+  toggleIcon={(exp) => <SiconCollapse size={20} style={exp ? undefined : { transform: "rotate(180deg)" }} />}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **Historically:** the Catalogix dashboard shell. **Today: nowhere** — see the
+  status note above.
+- It composes `StreamoidSidebar`, `ScSidebarMenu`, `ScSidebarSwitchMenu`,
+  `ScHDivider`, `ScSideBarLogoUnit` (with the built-in `Catalogix` product mark) and
+  `CreditWarningBanner`.
+- It is **presentational**: it renders chrome and fires callbacks. It fetches
+  nothing, holds no auth/workspace/theme state, and renders no popups — profile
+  menus, workspace modals and routing stay in the host.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are maintaining an existing call site (there are none in the four host repos).
+- You want a compact reference for how to preset `StreamoidSidebar` for one product.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Any new Catalogix sidebar work | `StreamoidSidebar` (what Catalogix actually ships) |
+| You need the "Ask CXO" gradient CTA | `StreamoidSidebar` + `assistantCta` (or `ScAskAgentSlot`) |
+| You want the shared cross-product switcher rows | `ScAppSwitchPanel` inside `StreamoidSidebar`'s `switchPanel` |
+| You want the collapsed switch **flyout** + backdrop | `StreamoidSidebar` (pass `switchPanel` in both rails) |
+| Section labels, top items, bottom items, a version footer | `StreamoidSidebar` |
+| Artifax's shell / collapsible sections | `ScArtifaxSidebar` |
+| One nav row / one switch row | `ScSidebarMenu` / `ScSidebarSwitchMenu` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `StreamoidSidebar` — the component this wraps, and the one Catalogix ships | This wrapper hides two thirds of its props |
+| `ScArtifaxSidebar` — a **standalone** sibling shell, not a wrapper | Different architecture, different prop names |
+| `ScCatalogixInvite` — the Catalogix invite/onboarding card | Not navigation |
+| `ScCatalogixStoreHeader` / `ScCatalogixStoreTableList` — the stores table | Not navigation |
+
+---
+
+## 4. Why to use it
+
+The honest answer: **for the defaults, and nothing else.** What it genuinely gives you:
+
+- **The Catalogix brand marks without importing them** — `product="Catalogix"` resolves
+  both the expanded wordmark and (unusually) a real collapsed square mark.
+- **A correct collapse/expand glyph pair** — `SiconCollapse` when expanded,
+  `SiconExpand` when collapsed, rather than one rotated icon.
+- **A worked example of the `StreamoidSidebar` slot contract** — `showBody` +
+  `bodyContent`, `switchPanel` + `switchPanelOpen` + `onSwitchPanelClose`,
+  `preFooterContent`, `toggleInProfile`, `versionText=""`. Copy the pattern, not
+  the component.
+
+Everything else you get from `StreamoidSidebar` itself, with more control.
+
+---
+
+## Gotchas
+
+**1. No `assistantCta`.** The component catalog describes this wrapper as having an
+"Ask CXO"-style CTA. It does not: `assistantCta` is never forwarded to
+`StreamoidSidebar`, and there is no prop for it. This alone is why Catalogix stopped
+using the wrapper.
+
+**2. Overriding `expandedLogo` / `collapsedLogo` disables the app switcher.** The
+default nodes are the only place `handleSwitch` (which flips the internal
+`appListOpen`) is wired.
+
+```tsx
+// WRONG — switchApps become unreachable
+<ScCatalogixSidebar expandedLogo={<MyLogo />} switchApps={apps} … />
+
+// RIGHT — keep the default logo; use onLogoClick for side effects
+<ScCatalogixSidebar switchApps={apps} onLogoClick={loadCatalog} … />
+```
+
+**3. Collapsed switching behaves differently from every other app.**
+`switchPanelContent` is `undefined` unless `expanded`, so `StreamoidSidebar`'s
+`hasSwitchCard` is false in the collapsed rail: no card, no 240px flyout, no
+backdrop, no `onSwitchPanelClose`. You get an inline column of
+`ScSidebarSwitchMenu variant="collapsed"` icons in the body instead.
+
+**4. `profile` is effectively required.** The wrapper always passes
+`toggleInProfile`, and `StreamoidSidebar` renders that footer branch only inside
+`profile ? … : null`. **Omit `profile` and there is no collapse toggle at all.**
+
+**5. Replacing `items` without `iconMap` yields icon-less rows.** Both props have
+defaults, and they default *independently*; the default `iconMap` only knows
+`stores` / `aiTraining` / `insights`. A missing key resolves to `null`, silently.
+
+**6. Switch rows are hardcoded to `state="default-highlight"`** in the expanded list
+and `state="default"` when collapsed — you cannot mark the current product, and the
+`description` you pass only renders in the expanded rail.
+
+**7. `onLogoClick` does not intercept the toggle.** It fires *in addition to*
+flipping the internal list state, on every click, in both directions — so it's a
+lazy-load hook, not an override.
+
+**8. It inherits every `StreamoidSidebar` gotcha.** Notably: layout depends on
+Tailwind utility classes that `dist/index.css` does **not** ship; the profile row and
+toggle are `div`s with `onClick` (no keyboard access); widths are hardcoded 256/56px;
+the body scrolls, so popovers must be portalled to `document.body`.
+
+**9. It inherits `CreditWarningBanner`'s self-dismissal.** The ✕ sets internal state
+and the banner returns `null` forever, with no callback — remount with a new `key` to
+bring it back. `remainingPct` is printed raw, so round it yourself.
+
+---
+
+## In the wild
+
+_No host render site found — Catalogix's shell composes `StreamoidSidebar` directly._
+
+The nearest thing to a call site is the code that **replaced** it:
+
+```jsx
+// catalogix/dashboard  app/containers/LeftMenu/index.jsx:991
+<StreamoidSidebar
+  expanded={!collapsed}
+  onToggle={handleToggleCollapse}
+  config={navConfig}
+  iconMap={iconMap}
+  activeItemId={currentSection}
+  onItemSelect={handleItemSelect}
+  showBody={!insideStore}
+  bodyContent={workspaceServiceBody}
+  switchPanel={appSwitchItems.length ? <ScAppSwitchPanel apps={appSwitchItems} /> : undefined}
+  assistantCta={{ label: "Ask CXO", icon: <SiconBolt size={20} color="currentColor" />, active: askCxoOpen, onClick: toggleAskCxo }}
+  switchPanelOpen={appListOpen}
+  onSwitchPanelClose={() => setAppListOpen(false)}
+  expandedLogo={
+    <ScSideBarLogoUnit
+      state="expanded"
+      wordmark={<ProductWordmark product="Catalogix" />}
+      onClick={() => setAppListOpen((v) => !v)}
+      switchAriaLabel="Switch app"
+    />
+  }
+  /* … profile, toggleInProfile, versionText="" … */
+/>
+```
+
+If this wrapper is kept, it belongs behind the same wiring: add an `assistantCta`
+pass-through and pass `switchPanel` in both rails.
+
+---
+
+## Related
+
+- `StreamoidSidebar` — the component this presets, and the replacement to use.
+- `ScSideBarLogoUnit` + `ProductWordmark` / `ProductCollapsedMark` — the Catalogix marks it renders by default.
+- `ScAppSwitchPanel` — the shared switcher rows Catalogix now uses instead of `ScSidebarSwitchMenu`.
+- `ScSidebarSwitchMenu` — the row type this wrapper builds its switch list from.
+- `CreditWarningBanner` — what `creditWarning` renders.
+- `ScArtifaxSidebar` — the other app-branded shell (standalone, not a wrapper).