@streamoid/ui 0.6.17 → 0.6.19

package/dist/docs/ScArtifaxInvite.md

@@ -0,0 +1,262 @@
+---
+component: ScArtifaxInvite
+package: "@streamoid/ui"
+category: cards
+status: stable
+renders: div
+tags: [invite, app-access, artifax, toggle, permissions, user-management, settings, onboarding, row]
+related: [ScPhtogenixInvite, ScCatalogixInvite, ScAppCard, ScToggleSwitch, ScAccess]
+do_not_confuse_with: [ScPhtogenixInvite, ScCatalogixInvite, ScAppCard, ScAppListingCard, ScAppCardV3, ScAppCardForCopilot, ScAccess]
+---
+
+# ScArtifaxInvite
+
+**One "does this user get Artifax?" row for the invite / edit-user modal.** An
+`ScAppCard` (icon + app name + description) on the left, an `ScToggleSwitch` on the
+right, a hairline divider underneath. Nothing else — no store scoping, no roles.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building the per-app access list in an invite or
+  edit-user flow and need the **Artifax** row (or any app whose access is a plain
+  on/off with no sub-scope).
+- **Don't reach for it when:** the app needs sub-scoping under the toggle
+  (→ `ScCatalogixInvite`, which adds the store-access panel), it's the Photogenix
+  row (→ `ScPhtogenixInvite`, **different prop names**), or you just want to
+  display an app without a toggle (→ `ScAppCard`).
+- **Four things that will bite you:**
+  1. ⚠️ It defaults to **ON**: `active` defaults to `"true"`. Pass `enabled`
+     explicitly, always.
+  2. ⚠️ Every string defaults to Artifax placeholder copy — `appName="Artifax"`,
+     `appDescription="Info about artifax"`. That description is Figma filler, not
+     product copy.
+  3. `active` is the string `"true"`/`"false"` (a Figma variant), `enabled` is the
+     boolean. `enabled` wins when defined. Use `enabled`.
+  4. It's fully controlled: `onToggle(next)` fires, the component does not change
+     its own state.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScArtifaxInvite } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScArtifaxInvite
+  enabled={artifaxOn}
+  onToggle={setArtifaxOn}
+  appDescription="Design brief and asset workflows"
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `enabled` | `boolean` | – | The real on/off. Overrides `active` whenever it is not `undefined`. **Use this one.** |
+| `active` | `"true"` \| `"false"` | `"true"` | ⚠️ Figma-variant leftover, a *string*. Only consulted when `enabled` is `undefined` — so the row renders **ON** by default. |
+| `onToggle` | `(active: boolean) => void` | – | Fires with the **next** value. No-op if omitted: the toggle then looks live but never changes. |
+| `appName` | `string` | `"Artifax"` | ⚠️ Real default. Passed to `ScAppCard`. |
+| `appDescription` | `string` | `"Info about artifax"` | ⚠️ Real default, and it is placeholder copy. Always set it. |
+| `appIcon` | `JSX.Element` | `<SiconArtifacts />` | ⚠️ Has a default. Correct for Artifax; wrong if you reuse this row for another app. |
+| `className` | `string` | – | Appended after internal classes. |
+| `...props` | `Omit<HTMLAttributes<HTMLDivElement>, "onToggle">` | – | Spread onto the root `<div>` — `onClick`, `style`, `data-*` all work here (unlike `ScPhtogenixInvite`). |
+
+### Recipes
+
+```tsx
+// The standard app-access list: one controlled row per app
+const [access, setAccess] = useState({ artifax: false, photogenix: false });
+
+<ScArtifaxInvite
+  enabled={access.artifax}
+  onToggle={(next) => setAccess((a) => ({ ...a, artifax: next }))}
+  appDescription="Design brief and asset workflows"
+/>
+<ScPhtogenixInvite
+  enabled={access.photogenix}
+  onToggle={(next) => setAccess((a) => ({ ...a, photogenix: next }))}
+  scAppCardappDescription="AI product photography"   // note the prop names
+  scAppCardappIcon={<SiconPhotogenix size={24} />}
+/>
+
+// Reusing the row for a different app (it is app-agnostic apart from its defaults)
+<ScArtifaxInvite
+  appName="Tactix"
+  appDescription="Merch planning and allocation"
+  appIcon={<SiconArtifacts size={24} />}
+  enabled={tactixOn}
+  onToggle={setTactixOn}
+/>
+
+// Mark the last row so you can drop the divider from your side
+<ScArtifaxInvite
+  enabled={artifaxOn}
+  onToggle={setArtifaxOn}
+  className={styles.lastRow}          // .lastRow { border-bottom-width: 0 }
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **The invite-user modal's "App access" section** — a stacked list of app rows,
+  one per product, inside `ScModal`/`ScDrawer`.
+- **The edit-user / manage-access drawer** — same list, pre-populated.
+- **First-run onboarding** ("which products do you want enabled?").
+
+It composes `ScAppCard` (flexed to fill) + `ScToggleSwitch` (`flex-shrink: 0`) and
+draws its own bottom divider, so a vertical stack of these rows needs no
+`ScHDivider` between them.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Access to the app is a **single boolean** with no sub-resource to pick.
+- You want the row to match the Catalogix/Photogenix rows beside it — same
+  padding (`--spacing-3xl`), same divider, same toggle geometry.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The app's access needs a nested resource picker (stores, projects) | `ScCatalogixInvite` |
+| The Photogenix row | `ScPhtogenixInvite` — same layout, **prefixed** prop names |
+| App icon + name + description with **no** toggle | `ScAppCard` |
+| A read-only "which apps does this user have" indicator (icons only) | `ScAccess` |
+| A marketing/launcher card for an app | `ScAppListingCard` / `ScAppCardV3` |
+| The app card inside the copilot/agent surface | `ScAppCardForCopilot` |
+| Just the switch, in your own row | `ScToggleSwitch` |
+| A labelled boolean inside a normal form | `ScCheckField` / `ScCheckbox` |
+| Switching the *current* app | `ScAppSwitchPanel` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScCatalogixInvite` — same header row **plus** a store-access panel that appears when enabled; defaults to **OFF** | `ScArtifaxInvite` is header-only and defaults to **ON** |
+| `ScPhtogenixInvite` — identical markup, but props are `scAppCardappName` / `scAppCardappDescription` / `scAppCardappIcon`, and it **drops** `...props` | `ScArtifaxInvite` uses clean `appName`/`appDescription`/`appIcon` and forwards DOM props |
+| `ScAppCard` — the inner icon/name/description block, no toggle, no divider | This row wraps one |
+| `ScAccess` — up to three app icons in a row, read-only, no labels | Not an editable access control |
+
+The trio is **not** app-locked: nothing but the default strings and the default
+icon ties `ScArtifaxInvite` to Artifax. Pick the one whose *shape* you need
+(plain row vs. row + sub-scope), then override the copy.
+
+---
+
+## 4. Why to use it
+
+- **The row is the design.** 16px padding, 8px gap, a 0.5px
+  `--alias-border-divider` bottom hairline, `ScAppCard` flexed to `1` and the
+  toggle pinned at `flex-shrink: 0` — that's the whole spec, and getting the
+  divider/flex pair wrong is exactly how these lists end up ragged.
+- **The toggle is the shared one.** `ScToggleSwitch` renders the two exact Figma
+  SVG states (on: base fill + inverse knob; off: neutral fill + divider stroke),
+  token-coloured, so it matches every other switch in the product across themes.
+- **`enabled`/`onToggle` is a plain controlled-boolean contract**, which is what
+  an invite form wants: one piece of state per app, submitted together.
+- **One place to change.** `@streamoid/settings` currently hand-rolls this row
+  three times over (with its own local `ToggleSwitch`); adopting these components
+  is how that duplication goes away.
+
+---
+
+## Gotchas
+
+**1. It renders ON unless you say otherwise.** `active = "true"` is the default and
+`enabled` is `undefined` until you pass it.
+
+```tsx
+// WRONG — an invite form that starts with Artifax already granted
+<ScArtifaxInvite onToggle={setArtifaxOn} />
+
+// RIGHT
+<ScArtifaxInvite enabled={artifaxOn} onToggle={setArtifaxOn} />
+```
+
+Note the inconsistency across the trio: `ScArtifaxInvite` and `ScPhtogenixInvite`
+default to `"true"`, `ScCatalogixInvite` defaults to `"false"`.
+
+**2. `active` is a string, not a boolean.** `active={true}` is a type error and
+`active="false"` reads as off — but any `enabled` you pass overrides it. Treat
+`active` as legacy and never mix the two.
+
+```tsx
+// WRONG — mixed sources of truth; `enabled` silently wins
+<ScArtifaxInvite active="false" enabled={artifaxOn} onToggle={setArtifaxOn} />
+
+// RIGHT
+<ScArtifaxInvite enabled={artifaxOn} onToggle={setArtifaxOn} />
+```
+
+**3. `appDescription` defaults to `"Info about artifax"`.** That is Figma filler
+that will ship to users. Same for the `ScAppCard` fallbacks underneath it.
+
+**4. It is stateless.** Omit `onToggle` and the switch is a dead pixel — clicking
+does nothing, because `checked` is recomputed from your props on every render.
+
+**5. You cannot disable the toggle.** `ScToggleSwitch` supports `disabled`, but
+this row never forwards it and exposes no such prop. For a read-only row, render
+`ScAppCard` + your own indicator, or gate the whole section.
+
+**6. Only the switch is clickable.** The root `<div>` gets no handler, `role` or
+keyboard affordance of its own (you can spread your own `onClick` via `...props`,
+but nothing focusable appears); the switch itself is a `div` with `onClick` (not a
+real `<input type="checkbox">`), so there is **no keyboard or screen-reader
+support**. If access control has to be operable by keyboard, wrap or replace it —
+`ScCheckField` gives you real semantics.
+
+**7. `styles["active-true"]` doesn't exist.** The stylesheet only defines
+`.active-false` (which merely thickens the divider from 0.5px to 1px), so in the
+ON state the variant class resolves to `undefined` and lands in the class
+attribute as the literal string `"undefined"` — along with `className` when you
+omit it. Don't write selectors or snapshot assertions against the class list.
+
+**8. Rows carry their own bottom divider.** Stacking these gives you the
+separators for free, but the last row also draws one. Strip it with `className`.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+The surface it models is real but hand-rolled in the shared settings package,
+which reimplements this row (and its own local `ToggleSwitch`) instead of
+importing it:
+
+```tsx
+// @streamoid/settings  packages/settings/src/invite-update-modal.tsx:617
+<ToggleSwitch                      // local component, not ScToggleSwitch
+  active={artifaxOn}
+  onClick={() => { setArtifaxOn(!artifaxOn); markChanged(); }}
+/>
+// …wrapped in hand-written markup that duplicates ScAppCard, including the
+// literal strings "Artifax" and "Info about artifax" (lines ~596-620).
+// The local ToggleSwitch is defined at invite-update-modal.tsx:84.
+```
+
+That modal (rendered by CXO settings → Teams → invite/edit user) is where this
+component belongs.
+
+---
+
+## Related
+
+- `ScPhtogenixInvite` — the Photogenix twin; watch the `scAppCard*` prop prefix.
+- `ScCatalogixInvite` — the same row plus a store-access panel when enabled.
+- `ScAppCard` — the icon/name/description block inside it.
+- `ScToggleSwitch` — the switch on the right, if you need it standalone.
+- `ScAccess` — read-only app-access icon row.

package/dist/docs/ScArtifaxSidebar.md

@@ -0,0 +1,330 @@
+---
+component: ScArtifaxSidebar
+package: "@streamoid/ui"
+category: sidebar
+status: stable
+renders: div
+tags: [sidebar, artifax, nav, shell, rail, collapsible-sections, accordion, collapse]
+related: [StreamoidSidebar, ScSideBarLogoUnit, ScAppSwitchPanel, ScSidebarMenu, ScAskAgentButton, CreditWarningBanner]
+do_not_confuse_with: [StreamoidSidebar, ScCatalogixSidebar, ScArtifaxInvite, ScSidebar]
+used_by: [artifax]
+required_props: [expanded, onToggle, sections]
+---
+
+# ScArtifaxSidebar
+
+**The Artifax app shell's sidebar — the one shell with collapsible, labelled nav
+sections.** Same silhouette as `StreamoidSidebar` (256px rounded card / 56px rail,
+logo slot, credit banner, gradient assistant CTA, profile + inline collapse toggle),
+but the nav is an accordion of uppercase-labelled sections, and it has **no
+`switchPanel` slot** — the app switcher is the host's job.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are working on the Artifax (or Tactix) shell, or you
+  need a sidebar whose sections the user can collapse.
+- **Don't reach for it when:** you are in CXO / Photogenix / Catalogix
+  (→ `StreamoidSidebar`), or you need the built-in app-switch overlay
+  (`StreamoidSidebar`'s `switchPanel` — this component has none).
+- **Four things that will bite you:**
+  1. Uncontrolled open-state is captured **once, at mount**. Sections that arrive
+     later (async nav) render **closed**.
+  2. Passing `openSections={{}}` switches it to controlled mode with **everything
+     closed** — `isControlled = !!openSections`, and `{}` is truthy.
+  3. A missing `iconMap` entry renders a **dashed-circle placeholder**, not nothing.
+  4. `.footerToggle > *` forces your toggle icon to **24×24 via CSS** — the `size`
+     prop on your `Sicon*` is overridden.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import {
+  ScArtifaxSidebar,
+  type ArtifaxSection,
+  type ArtifaxSidebarIconMap,
+  type ArtifaxSidebarAssistantCta,
+} from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScArtifaxSidebar
+  expanded={!collapsed}
+  onToggle={() => setCollapsed((v) => !v)}
+  sections={[
+    { id: "work", label: "Workspace", items: [{ id: "projects", label: "Projects", iconKey: "folder" }] },
+  ]}
+  iconMap={{ folder: <SiconFolder /> }}
+  activeItemId="projects"
+  onItemSelect={(item) => navigate(`/${item.id}`)}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `expanded` | `boolean` | — | **Required.** `true` → 256px card inside a 16px padded wrapper; `false` → 56px rail with a right border. Separate render branches. |
+| `onToggle` | `() => void` | — | **Required.** Fired by the footer toggle. |
+| `sections` | `ArtifaxSection[]` | — | **Required.** `{ id, label?, collapsible?, defaultOpen?, items }[]`. A `ScHDivider` is drawn before every section except the first. |
+| `iconMap` | `ArtifaxSidebarIconMap` | – | `Record<iconKey, ReactNode \| ({item, active, expanded}) => ReactNode>`. ⚠️ Missing key → dashed-circle placeholder icon. |
+| `activeItemId` | `string` | – | Matching row gets `state="active"`; `active` is also passed to your icon renderer. |
+| `onItemSelect` | `(item: ArtifaxMenuItem, sectionId: string) => void` | – | Fired on row click. |
+| `expandedLogo` | `ReactNode` | – | Slot. Omit → **no logo at all** (there is no built-in default). |
+| `collapsedLogo` | `ReactNode` | – | Slot, in a fixed 48×48 box. |
+| `creditWarning` | `ArtifaxSidebarCreditWarning \| null` | – | `{ availableCredits, remainingPct, level?, onBuyCredits }`. `level` defaults to **`"danger"`** here. Renders `CreditWarningBanner`. |
+| `assistantCta` | `ArtifaxSidebarAssistantCta \| null` | – | Alias of `AssistantCta`. Renders `ScAskAgentSlot` — the gradient "Ask CXO" pill / collapsed square. |
+| `profile` | `ArtifaxSidebarProfile` | – | `{ name, subtitle?, avatar?, onClick? }`. Omit and an `aria-hidden` spacer keeps the toggle right-aligned. |
+| `toggleIcon` | `ReactNode \| ((expanded: boolean) => ReactNode)` | `<SiconCollapse />` | ⚠️ **Has a real default** (unlike `StreamoidSidebar`). It does **not** rotate when collapsed — do that yourself. |
+| `openSections` | `Record<string, boolean>` | – | Presence switches to **controlled** accordion mode. |
+| `onSectionToggle` | `(sectionId: string, open: boolean) => void` | – | Fires in **both** modes (uncontrolled too). |
+| `className` | `string` | – | On the outer wrapper — Artifax uses it to scope per-app CSS. |
+| `style` | `CSSProperties` | – | On the outer wrapper. |
+
+### Types
+
+```ts
+interface ArtifaxMenuItem { id: string; label: string; iconKey: string }
+interface ArtifaxSection {
+  id: string;
+  label?: string;          // no label → no header, section is always open
+  collapsible?: boolean;   // false → header renders but is disabled, always open
+  defaultOpen?: boolean;   // read ONCE, at mount. Defaults to true.
+  items: ArtifaxMenuItem[];
+}
+interface ArtifaxSidebarCreditWarning { availableCredits: number; remainingPct: number; level?: "warning" | "danger"; onBuyCredits: () => void }
+type ArtifaxSidebarAssistantCta = AssistantCta; // { label, icon?, active?, ariaLabel?, onClick }
+```
+
+### What renders in each rail
+
+| Region | expanded | collapsed |
+|---|---|---|
+| Container | 256px, 16px radius, 1px `border-subtle` overlay, inside a 16px padded wrapper | 56px wide, `border-right` only, no wrapper padding |
+| Logo | `expandedLogo`, 8px padding, full width | `collapsedLogo` in a 48×48 centred box |
+| Section header | uppercase 10px/1px-tracked label + `SiconUp`/`SiconDown` chevron | **not rendered** |
+| Items | `ScSidebarMenu variant="expanded"` with `text` | `variant="collapsed"`, `text` omitted |
+| Collapsibility | honoured | **ignored** — all items always render |
+| Credit banner | `CreditWarningBanner expanded` | `CreditWarningBanner expanded={false}` (40×40 square) |
+| Assistant CTA | `ScAskAgentSlot` pill | `ScAskAgentSlot collapsed` square |
+| Footer | profile (flex-1, hover bg) + toggle, `aria-label="Collapse sidebar"` | avatar above toggle, `aria-label="Expand sidebar"` |
+
+### Recipes
+
+```tsx
+// Controlled accordion — persist which sections are open
+const [openSections, setOpenSections] = useState<Record<string, boolean>>({ work: true, recent: false });
+
+<ScArtifaxSidebar
+  expanded={!collapsed}
+  onToggle={() => setCollapsed((v) => !v)}
+  sections={sections}
+  openSections={openSections}
+  onSectionToggle={(id, open) => setOpenSections((p) => ({ ...p, [id]: open }))}
+  iconMap={iconMap}
+/>
+
+// Icon renderer that tracks the active row
+<ScArtifaxSidebar
+  /* … */
+  iconMap={{
+    folder: ({ active }) => (
+      <SiconFolder color={active ? "var(--alias-text---icons-primary)" : "var(--alias-text---icons-tertiary)"} />
+    ),
+  }}
+/>
+
+// Gradient assistant CTA + low credits, plus a collapsed-aware toggle glyph
+<ScArtifaxSidebar
+  /* … */
+  assistantCta={{ label: "Ask CXO", icon: <SiconBolt className="h-5 w-5" />, active: assistantOpen, onClick: toggleAssistant }}
+  creditWarning={{ availableCredits: 120, remainingPct: 4, onBuyCredits: goBilling }}
+  toggleIcon={(expanded) => <SiconCollapse className={expanded ? "" : "rotate-180"} />}
+/>
+
+// The app switcher — this component has no slot for it, so portal your own
+<>
+  <ScArtifaxSidebar expandedLogo={<div ref={anchorRef}><ScSideBarLogoUnit wordmark={wm} onClick={() => setOpen(v => !v)} /></div>} … />
+  {open ? createPortal(<Flyout anchorRef={anchorRef}><ScAppSwitchPanel apps={apps} /></Flyout>, document.body) : null}
+</>
+```
+
+---
+
+## 2. Where to use it
+
+- **The Artifax dashboard shell** — `packages/shared/src/components/DashboardSidebar.tsx`,
+  shared by the Artifax and Tactix front-ends. That file is the reference wiring for
+  everything this component deliberately leaves out (app switcher, profile menu,
+  workspace modal).
+- It composes internally: `ScSidebarMenu`, `ScHDivider`, `CreditWarningBanner`,
+  `ScAskAgentSlot`, and `SiconCollapse`/`SiconUp`/`SiconDown`.
+- You supply into its slots: `ScSideBarLogoUnit` (both logo slots), `ScDp`
+  (`profile.avatar`).
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are in the Artifax/Tactix shell.
+- The nav has **several labelled groups** the user should be able to collapse —
+  `StreamoidSidebar` has section labels but no accordion.
+- You want the credit banner and assistant CTA wired by prop rather than by slot.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| CXO / Photogenix / Catalogix sidebar | `StreamoidSidebar` |
+| You need the built-in app-switch overlay + backdrop | `StreamoidSidebar` (`switchPanel` / `switchPanelOpen`) |
+| You want a free-form nav body instead of `sections` | `StreamoidSidebar` (`showBody` + `bodyContent`) |
+| One nav row | `ScSidebarMenu` |
+| The product-switch list | `ScAppSwitchPanel` (portal it yourself here) |
+| Artifax's invite/onboarding card | `ScArtifaxInvite` — unrelated component |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `StreamoidSidebar` — the shared shell; different prop names (`config`, `topItems`, `switchPanel`, `versionText`) | `ScArtifaxSidebar` is a **sibling**, not a wrapper |
+| `ScCatalogixSidebar` — *is* a wrapper of `StreamoidSidebar` | This one is standalone |
+| `ScArtifaxInvite` — the Artifax invite card | Nothing to do with navigation |
+| `ScSidebar` — legacy shell | Superseded |
+
+---
+
+## 4. Why to use it
+
+- **The accordion is already correct in both modes.** Controlled and uncontrolled,
+  `collapsible: false` headers that render but don't toggle, label-less sections that
+  are permanently open — three branches you'd otherwise re-derive.
+- **Both rails are real designs, not a CSS `width` change.** The collapsed rail
+  drops labels and section headers, centres everything, and stacks avatar-over-toggle;
+  the expanded one puts the toggle inline in the profile row.
+- **CSS-module scoped, token-only.** `--alias-surface-base`, `--alias-border-subtle`,
+  `--alias-fill-neutral-neutral` hovers, `--alias-text-and-icons-*` — light mode is free.
+- **Real `<button>`s throughout.** Section headers, profile, toggle and the assistant
+  CTA are all native `<button type="button">`s — unlike `StreamoidSidebar`, whose
+  profile row and toggle are `div`s with `onClick`. (`aria-label` is set on the
+  footer toggle — `"Collapse sidebar"` / `"Expand sidebar"` — and on the collapsed
+  profile button; the section header and the expanded profile are labelled by their
+  own text.)
+- **One assistant CTA implementation.** `assistantCta` renders the shared
+  `SC-AskAgentButton`, so the Artifax pill and the CXO/Catalogix pill cannot drift.
+
+---
+
+## Gotchas
+
+**1. Uncontrolled open-state is frozen at mount.** The internal map is built in a
+`useState` initialiser from `defaultOpen ?? true`. A section added later has no key,
+`!!internalOpen[id]` is `false`, and it renders **closed** — the classic
+"sections load from the API and are all collapsed" bug.
+
+```tsx
+// WRONG — sections arrive after mount, all render closed
+<ScArtifaxSidebar sections={sectionsFromApi} … />
+
+// RIGHT — either don't mount until loaded…
+{sectionsFromApi.length ? <ScArtifaxSidebar sections={sectionsFromApi} … /> : <Skeleton />}
+// …or drive it controlled
+<ScArtifaxSidebar sections={sectionsFromApi} openSections={open} onSectionToggle={set} … />
+```
+
+**2. `openSections={{}}` means "controlled, all closed".** The mode switch is
+`isControlled = !!openSections`, and `{}` is truthy. Never pass an empty object as a
+placeholder.
+
+**3. A missing `iconMap` key renders a dashed circle.** `resolveIcon` falls back to
+`ArtifaxPlaceholderIcon` (a 20px box with a 10px dashed-border `::before`). It looks
+like a deliberate design, so typo'd `iconKey`s survive review.
+
+**4. CSS overrides your toggle icon's size.** `.footerToggle > * { width: 1.5rem; height: 1.5rem }`
+wins over an svg's `width`/`height` attributes. `<SiconCollapse size={16} />` still
+renders 24px. Use a wrapper with an inline style if you truly need another size.
+
+**5. `toggleIcon` doesn't rotate itself.** The default is a bare `<SiconCollapse />`
+in both states. Artifax passes `(expanded) => <SiconCollapse className={expanded ? "" : "rotate-180"} />`.
+
+**6. The scroll body clips popovers.** `.body` is `overflow-y: auto; overflow-x: hidden`.
+Anything you open from the logo slot, a nav row or the profile row must be portalled
+to `document.body` — which is exactly why the Artifax host renders `SwitchFlyout` and
+`ProfileMenu` as portals.
+
+**7. There is no app-switcher slot.** No `switchPanel`, no `switchPanelOpen`, no
+backdrop. Clicking `ScSideBarLogoUnit` in the logo slot only calls your handler; you
+own the panel, its position and its outside-click.
+
+**8. Collapsed ignores `collapsible` / `label` / `defaultOpen` entirely.** Every
+item of every section renders. A section the user collapsed reappears when they
+collapse the rail.
+
+**9. `creditWarning.onCollapsedClick` doesn't exist here.** The collapsed 40×40
+square falls back to `onBuyCredits`, so collapsing the rail turns the banner into a
+"go to billing" button. (`StreamoidSidebar` + `CreditWarningBanner` directly *do*
+support `onCollapsedClick`.) The banner also dismisses itself permanently on ✕ with
+no callback — see `CreditWarningBanner`'s own README.
+
+**10. Hardcoded English.** `"Collapse sidebar"` / `"Expand sidebar"` aria-labels, and
+section labels are force-uppercased via `text-transform` (so `label` should be
+written in sentence case, not shouted).
+
+**11. No logo default.** Omit `expandedLogo`/`collapsedLogo` and the slot simply
+isn't rendered — no fallback wordmark.
+
+**12. Widths are hardcoded** — `16rem` expanded, `3.5rem` collapsed, 48×48 collapsed
+logo box, 32×32 avatar. Not overridable by props.
+
+---
+
+## In the wild
+
+```tsx
+// artifax  packages/shared/src/components/DashboardSidebar.tsx:641
+<ScArtifaxSidebar
+  className={nav.rootClassName}
+  expanded={!collapsed}
+  onToggle={() => setCollapsed((v) => !v)}
+  sections={nav.sections}
+  iconMap={nav.iconMap}
+  activeItemId={activeItemId}
+  onItemSelect={handleItemSelect}
+  expandedLogo={
+    <div ref={expandedSwitchRef} className="flex w-full flex-col">
+      <ScSideBarLogoUnit state="expanded" wordmark={nav.wordmark} onClick={() => setAppListOpen((v) => !v)} switchAriaLabel="Switch product" />
+    </div>
+  }
+  collapsedLogo={
+    <div ref={collapsedLogoRef} className="flex w-full flex-col items-center">
+      <ScSideBarLogoUnit state="collapsed" wordmark={nav.mark} onClick={() => setAppListOpen((v) => !v)} switchAriaLabel="Switch product" />
+    </div>
+  }
+  creditWarning={creditWarning}
+  assistantCta={
+    onToggleAssistant
+      ? { label: ASK_CXO_LABEL, icon: <SiconBolt className="h-5 w-5" />, active: assistantOpen, onClick: onToggleAssistant }
+      : undefined
+  }
+  profile={{ name: userName, subtitle: workspaceName, avatar: <ScDp type="initial" variant="profile" initial={userInitial} size={32} />, onClick: () => setProfileMenuOpen((v) => !v) }}
+  toggleIcon={(expanded) => <SiconCollapse className={expanded ? "" : "rotate-180"} />}
+/>
+```
+
+---
+
+## Related
+
+- `StreamoidSidebar` — the shell every other desktop app uses; has `switchPanel`, `bodyContent`, `versionText`.
+- `ScSideBarLogoUnit` — what goes in the two logo slots.
+- `ScAppSwitchPanel` — the product-switch list you must portal yourself here.
+- `ScAskAgentButton` / `ScAskAgentSlot` — what `assistantCta` renders.
+- `CreditWarningBanner` — what `creditWarning` renders (read its gotchas: self-dismiss, raw `remainingPct`).
+- `ScSidebarMenu` — the nav row rendered per item.