@streamoid/ui 0.6.17 → 0.6.19

package/dist/docs/ScMobileTopNav.md

@@ -0,0 +1,279 @@
+---
+component: ScMobileTopNav
+package: "@streamoid/ui"
+category: mobile
+status: stable
+renders: div
+tags: [mobile, nav, topbar, header, appbar, menu, search, chat, heading]
+related: [ScMobileBottomAction, ScHeader, ScTableHeader, ScSideBarLogoUnit, ScOnlyField]
+do_not_confuse_with: [ScHeader, ScTableHeader, ScSideBarLogoUnit, ScMobileBottomAction, ScTabSwitcher]
+---
+
+# ScMobileTopNav
+
+**The mobile app bar, in three layouts.** A flex row over
+`--alias-surface-canvas`, 56px tall because its 56×56 icon slots make it so (the root
+itself sets no `height`), with three `type`s: `home` (menu icon only, no border), `chat`
+(menu · chat title · more, bordered), and `inApp` (menu · centred heading · optional
+search icon, bordered) — where `inApp` can flip into a full-width search field.
+
+## TL;DR for agents
+
+- **Reach for it when:** a mobile screen needs the standard top bar — hamburger on the
+  left, a title, and an optional search or overflow affordance on the right.
+- **Don't reach for it when:** you need a desktop page header (→ `ScHeader`), a table's
+  column header (→ `ScTableHeader`), a sidebar logo row (→ `ScSideBarLogoUnit`), or the
+  sticky footer action bar (→ `ScMobileBottomAction`).
+- **Five things that will bite you:**
+  1. **No icons are supplied.** `menuIcon`, `searchIconElement`, `closeIcon` and
+     `moreIcon` all fall back to an **invisible** 24×24 placeholder div. Render it bare
+     and you get an empty bar.
+  2. **`search={true}` with `searchIcon={false}` renders nothing at all.** Both flags
+     must be true for the search layout, and the non-search layout is gated on
+     `!search` — so that combination falls through every branch. See Gotcha 2.
+  3. **The icon hit areas are `div`s with `onClick`** — no `role`, no `tabIndex`, no
+     `aria-label`. Keyboard users cannot reach them.
+  4. **It is not sticky or fixed.** You position it.
+  5. `heading` defaults to `"Heading"` and `chatTitle` to
+     `"Chat title comes here..."`.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScMobileTopNav } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+import { SiconMenu } from "@streamoid/icons";
+
+<ScMobileTopNav type="home" menuIcon={<SiconMenu size={24} />} onMenuClick={openDrawer} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `type` | `"home"` \| `"chat"` \| `"inApp"` | `"home"` | The layout. `chat` and `inApp` add a bottom border **and** a 16px gap; `home` has neither. |
+| `searchIcon` | `boolean` | `false` | `inApp` only. `false` → the trailing slot still renders but is `opacity: 0; pointer-events: none` (keeps the heading centred). |
+| `search` | `boolean` | `false` | `inApp` only, **and only with `searchIcon`** — flips the bar into search-field mode. See Gotcha 2. |
+| `heading` | `string` | `"Heading"` | ⚠️ `inApp` only. Centred, 16px secondary. **Does not truncate** — see Gotcha 7. |
+| `chatTitle` | `string` | `"Chat title comes here..."` | ⚠️ `chat` only. Left-aligned, truncates with ellipsis. |
+| `searchPlaceholder` | `string` | `"Search..."` | ⚠️ Hardcoded English default. |
+| `searchValue` | `string` | – | Passed straight to `<input value>`. Omit → uncontrolled; pass it → you **must** wire `onSearchChange` or the field freezes. |
+| `menuIcon` | `JSX.Element` | – | ⚠️ No default; falls back to an invisible 24×24 div. `home`, `chat`, `inApp` (non-search). |
+| `searchIconElement` | `JSX.Element` | – | ⚠️ No default. The magnifier — in the trailing slot for `inApp`, and **leading the field** in search mode. |
+| `closeIcon` | `JSX.Element` | – | ⚠️ No default. Search mode only, trailing. |
+| `moreIcon` | `JSX.Element` | – | ⚠️ No default. `chat` only, trailing. |
+| `onMenuClick` | `(e: React.MouseEvent) => void` | – | On the leading 56×56 slot. |
+| `onSearchClick` | `(e: React.MouseEvent) => void` | – | On the trailing magnifier (`inApp`) **and** on the leading magnifier inside search mode. |
+| `onCloseClick` | `(e: React.MouseEvent) => void` | – | Search mode's trailing slot. |
+| `onMoreClick` | `(e: React.MouseEvent) => void` | – | `chat` mode's trailing slot. |
+| `onSearchChange` | `(value: string) => void` | – | Receives `e.target.value` — the string, not the event. |
+| `className` | `string` | – | Appended after internal classes. Unguarded concat — see Gotcha 8. |
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | – | Spread onto the root `div`. |
+
+### What renders in each state
+
+| `type` | `searchIcon` | `search` | Layout | Border |
+|---|---|---|---|---|
+| `home` | — | — | `menuIcon` only, left-aligned | no |
+| `chat` | — | — | `menuIcon` · `chatTitle` (grows, truncates) · `moreIcon` | yes |
+| `inApp` | `false` | `false` | `menuIcon` · `heading` (centred) · **invisible** 56px spacer | yes |
+| `inApp` | `true` | `false` | `menuIcon` · `heading` (centred) · `searchIconElement` | yes |
+| `inApp` | `true` | `true` | `searchIconElement` + text input (grows) · `closeIcon` — **no menu, no heading** | yes |
+| `inApp` | `false` | `true` | ⚠️ **nothing renders** — an empty 0-height bar. See Gotcha 2. |
+
+### Recipes
+
+```tsx
+import { SiconMenu, SiconSearch, SiconClose, SiconMore } from "@streamoid/icons";
+
+// A searchable in-app screen — the full state machine
+const [searching, setSearching] = useState(false);
+const [q, setQ] = useState("");
+
+<ScMobileTopNav
+  type="inApp"
+  heading="Team"
+  searchIcon                       // must stay true in BOTH states
+  search={searching}
+  menuIcon={<SiconMenu size={24} />}
+  searchIconElement={<SiconSearch size={24} />}
+  closeIcon={<SiconClose size={24} />}
+  searchValue={q}
+  searchPlaceholder="Search members…"
+  onMenuClick={openDrawer}
+  onSearchClick={() => setSearching(true)}
+  onCloseClick={() => { setSearching(false); setQ(""); }}
+  onSearchChange={setQ}
+/>
+
+// A chat screen
+<ScMobileTopNav
+  type="chat"
+  chatTitle={thread.title}
+  menuIcon={<SiconMenu size={24} />}
+  moreIcon={<SiconMore size={24} />}
+  onMenuClick={openDrawer}
+  onMoreClick={openThreadMenu}
+/>
+
+// Make it stick to the top of a scrolling screen — the component does not
+<div style={{ position: "sticky", top: 0, zIndex: 10 }}>
+  <ScMobileTopNav type="home" menuIcon={<SiconMenu size={24} />} onMenuClick={openDrawer} />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+The first child of every mobile screen — above the scrolling body and above
+`ScMobileBottomAction`. The intended mobile shell is:
+
+```
+ScMobileTopNav          ← 56px, shrink-0
+<scrolling body>        ← flex-1, overflow-y auto
+ScMobileBottomAction    ← shrink-0, sticky footer
+```
+
+It composes nothing from the DS — icons are slots, and the search field is a bare
+`<input>`, not `ScOnlyField`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The screen is a mobile route with a drawer/hamburger and a title.
+- You want the 56px hit areas, the border-on-scroll-surfaces rule and the
+  centred-heading spacer logic without rebuilding them.
+- The screen has an in-place search that replaces the bar (the `inApp` + `search` flow).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Desktop page/section header with a title | `ScHeader` (`text`, `state: up/down/none`) |
+| A table's column header row | `ScTableHeader` / `ScBillingHistoryHeader` / `ScReferralTableHeader` |
+| The sidebar's logo + app-switcher row | `ScSideBarLogoUnit` |
+| Mobile sticky footer with 1–2 buttons | `ScMobileBottomAction` |
+| Switching between views inside a screen | `ScTabSwitcher` + `ScTabComp`, below the nav |
+| A styled search input anywhere else | `ScOnlyField` / `ScTextField` |
+| The desktop app shell | `StreamoidSidebar` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScHeader` — desktop title bar with a sort/collapse `state` | `ScMobileTopNav` is the mobile app bar with icon slots |
+| `ScTableHeader` — a table's column labels | Not navigation |
+| `ScSideBarLogoUnit` — logo + chevron, `expanded`/`collapsed` | Sidebar chrome, not a top bar |
+| `ScMobileBottomAction` — the *bottom* bar, buttons not icons | Same family, opposite end of the screen |
+
+---
+
+## 4. Why to use it
+
+- **The centred-heading trick is already right.** In `inApp` with `searchIcon={false}`
+  the trailing 56px slot still renders, hidden — that invisible spacer is what keeps
+  `heading` optically centred. Hand-rolled bars centre the title with the icon on one
+  side and it drifts.
+- **56×56 hit areas** meet the touch-target minimum on every slot, consistently.
+- **The border rule is encoded**: `home` (which sits on a hero/canvas) gets no divider;
+  `chat` and `inApp` (which sit above content) get a 0.5px `--alias-border-subtle` line
+  and a 16px gap.
+- **Search is a layout swap, not an overlay**, so you don't manage a second component's
+  z-index and mount lifecycle — one `search` boolean.
+- **Icon slots keep app iconography out of the DS**, so CXO, Catalogix and Photogenix can
+  each pass their own `Sicon*` set.
+
+---
+
+## Gotchas
+
+**1. No icons are provided.** Every icon prop falls back to
+`<div className={styles.iconPlaceholder} />` — a transparent 24×24 box. So the bar
+renders, occupies 56px, responds to clicks, and shows **nothing**.
+
+```tsx
+// WRONG — an empty bar with an invisible tap target
+<ScMobileTopNav type="home" onMenuClick={openDrawer} />
+
+// RIGHT
+<ScMobileTopNav type="home" menuIcon={<SiconMenu size={24} />} onMenuClick={openDrawer} />
+```
+
+**2. `search` without `searchIcon` renders an empty bar.** The two branches are
+`type === "inApp" && searchIcon && search` and `type === "inApp" && !search`. With
+`searchIcon={false}, search={true}` neither matches.
+
+```tsx
+// WRONG — renders an empty div; nothing at all inside the nav
+<ScMobileTopNav type="inApp" search heading="Team" />
+
+// RIGHT — keep searchIcon true in both states and toggle only `search`
+<ScMobileTopNav type="inApp" searchIcon search={searching} heading="Team" />
+```
+
+**3. The icon slots are not accessible.** They are `div`s with `onClick` and
+`cursor: pointer` — no `role="button"`, no `tabIndex`, no `aria-label`. Screen-reader and
+keyboard users get nothing. There is no prop to fix this from outside; if the surface must
+be accessible, pass an interactive element *as* the icon (e.g. a `<button aria-label="Menu">`
+wrapping your `Sicon`), or fix the DS.
+
+**4. The search `<input>` has no label.** Only `placeholder`. Add
+`aria-label` support in the DS, or accept the gap.
+
+**5. `searchValue` makes the input controlled.** Pass it without `onSearchChange` and the
+field is frozen. `onSearchChange` receives the **string**, not the event.
+
+**6. No submit.** There is no `<form>` and no Enter handling — wire debounced filtering
+off `onSearchChange`, or add a `onKeyDown` via… you can't; `...props` goes to the root, not
+the input. Filter as-you-type.
+
+**7. `heading` does not truncate.** `.heading` has `flex: 1 0 0; min-width: 0` and
+`text-align: center` but **no** `overflow`/`ellipsis` (unlike `.chatTitle`, which has
+all three). A long heading wraps to two lines and breaks the 56px height.
+
+**8. `className` is concatenated unguarded.** Omit it and the root carries a literal
+`undefined` class.
+
+**9. Not sticky, not fixed.** The root is a static `width: 100%` flex row over
+`--alias-surface-canvas`. Wrap it yourself for sticky behaviour, and remember it has no
+`z-index` of its own.
+
+**10. In search mode the menu icon disappears.** There is no hamburger and no heading —
+only the magnifier, the field, and close. If your drawer must stay reachable while
+searching, this layout is wrong for you.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+To be precise: it is exported from `@streamoid/ui` but no host app renders it, and it is
+not agent-runtime — it is currently unused. CXO's mobile screens hand-roll exactly this
+layout instead: `cxo-dashboard/src/app/components/mobile-teams-content.tsx` builds the
+same bar from `SiconMenu` / `SiconSearch` / `SiconClose` in 56×56 `div`s (see the icon
+uses at lines 174, 201, 211 and 240). Those screens are where this component belongs.
+
+---
+
+## Related
+
+- `ScMobileBottomAction` — the other half of the mobile shell (sticky footer buttons).
+- `ScHeader` — the desktop page-header equivalent.
+- `ScSideBarLogoUnit` / `StreamoidSidebar` — the desktop shell's chrome.
+- `ScTabSwitcher` / `ScTabComp` — what usually sits directly below this bar.
+- `@streamoid/icons` — `SiconMenu`, `SiconSearch`, `SiconClose`, `SiconMore`; see
+  `packages/icons/ICONS.md`.

package/dist/docs/ScModal.md

@@ -0,0 +1,291 @@
+---
+component: ScModal
+package: "@streamoid/ui"
+category: overlays
+status: stable
+renders: div (portalled to document.body)
+tags: [modal, dialog, overlay, scrim, backdrop, portal, centered, blocking, escape]
+related: [ScDrawer, ScInfoPopup, ScProfilePopup, ScGuide, ScButton]
+do_not_confuse_with: [ScDrawer, ScInfoPopup, ScProfilePopup]
+used_by: [catalogix]
+---
+
+# ScModal
+
+**The centered blocking-dialog shell.** A fixed full-screen scrim portalled to
+`<body>` with one padded, rounded content box centered inside it. It supplies the
+scrim, the portal, backdrop-click close and Escape close — and *nothing else*: no
+header, no footer, no close button, no width. Your dialog is `children`.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a centered dialog that blocks the page — confirm,
+  create/edit form, image preview, invite flow.
+- **Don't reach for it when:** the panel should slide in from the screen edge
+  (→ `ScDrawer`), it's a small contextual "?" bubble (→ `ScInfoPopup`), or it's the
+  profile/account flyout (→ `ScProfilePopup`, which is a positioned panel with no
+  overlay of its own).
+- **Four things that will bite you:**
+  1. `open` defaults to **`true`**. Mounting it shows it.
+  2. `className` / `style` land on the **backdrop**. The panel is
+     `contentClassName` / `contentStyle`. This is the reverse of most modal APIs.
+  3. There is **no `role="dialog"`, no `aria-modal`, no focus trap and no
+     body-scroll lock**, and no prop to add them — you must render your own
+     `role="dialog"` wrapper as the child.
+  4. The content box has **no width and no max-height**. Tall content runs off the
+     viewport with nothing to scroll. Set both in `contentStyle`.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScModal } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+The idiomatic host pattern is conditional mounting — don't bother with `open`:
+
+```tsx
+{isOpen && (
+  <ScModal onClose={() => setIsOpen(false)}>
+    <h2>Delete store?</h2>
+    <ScButton text="Delete" variant="error" size="md" onClick={confirmDelete} />
+  </ScModal>
+)}
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `children` | `ReactNode` | – | Your whole dialog. The component adds no chrome. |
+| `open` | `boolean` | `true` | ⚠️ Defaults to open. `false` returns `null` (unmounts, no CSS transition). |
+| `onClose` | `() => void` | – | Called by backdrop mousedown and by Escape. Optional — omit it and the modal cannot be dismissed. |
+| `closeOnBackdrop` | `boolean` | `true` | Backdrop **mousedown** (not click) fires `onClose`, and only when the event target *is* the backdrop. |
+| `closeOnEsc` | `boolean` | `true` | Document-level `keydown` listener, active only while `open`. |
+| `className` | `string` | – | **On the backdrop**, appended after `styles.backdrop`. |
+| `style` | `CSSProperties` | – | **On the backdrop.** Use it to change the scrim or the z-index. |
+| `contentClassName` | `string` | – | On the centered panel. |
+| `contentStyle` | `CSSProperties` | – | On the centered panel. **This is where width / max-height / padding go.** |
+
+There is no `...props` spread — anything not in this table is a type error and has
+no runtime effect.
+
+### What it actually renders
+
+```html
+<!-- portalled into document.body -->
+<div class="backdrop {className}" style={style}>      <!-- position:fixed, inset 0, z-index:999,
+                                                            padding-left: var(--leftMenuWidth, 0),
+                                                            background: rgba(16,16,16,0.7) -->
+  <div class="content {contentClassName}" style={contentStyle}>   <!-- padding:24px; radius:16px;
+                                                                       background: --alias-surface-base -->
+    {children}
+  </div>
+</div>
+```
+
+### Recipes
+
+```tsx
+// Sized, scrollable dialog with real dialog semantics
+{isOpen && (
+  <ScModal
+    onClose={close}
+    contentStyle={{ width: 560, maxWidth: "calc(100vw - 48px)", maxHeight: "80vh", overflow: "auto" }}
+  >
+    <div role="dialog" aria-modal="true" aria-labelledby="invite-title">
+      <h2 id="invite-title">Invite a teammate</h2>
+      {/* … */}
+    </div>
+  </ScModal>
+)}
+
+// A form dialog that must NOT discard typed input on Escape (the Catalogix idiom)
+<ScModal onClose={close} closeOnEsc={false}>
+  <QuickInviteForm />
+</ScModal>
+
+// Edge-to-edge content (image preview, embedded canvas) — kill the 24px padding
+<ScModal onClose={close} contentStyle={{ padding: 0, borderRadius: 12, overflow: "hidden" }}>
+  <img src={url} style={{ display: "block", maxWidth: "90vw", maxHeight: "90vh" }} />
+</ScModal>
+
+// Lock body scroll yourself — the modal does not
+useEffect(() => {
+  if (!isOpen) return;
+  const prev = document.body.style.overflow;
+  document.body.style.overflow = "hidden";
+  return () => { document.body.style.overflow = prev; };
+}, [isOpen]);
+```
+
+---
+
+## 2. Where to use it
+
+- **Confirm / destructive-action dialogs** — the "are you sure?" pair with
+  `ScButton variant="error"`.
+- **Create / edit forms** that are short enough not to want a drawer.
+- **Media preview** overlays (pass `contentStyle={{ padding: 0 }}`).
+- **Invite and quick-action flows** — Catalogix's `QuickInviteModal` goes through
+  its local `CenterModal` wrapper, which is a pass-through to this component.
+
+Catalogix is the only host consumer today, via
+`app/components/CenterModal` (its historical `ConterModal` spelling still works —
+the default export is bound by position). CXO and Photogenix use app-local modal
+shells; if you touch either, this is what they should converge on.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The task is **modal**: the user must finish or cancel before continuing.
+- You want the scrim colour, the portal escape-hatch and the dismissal wiring to
+  match every other dialog in the product.
+- Your dialog needs to **escape a transformed / `overflow: hidden` ancestor** — the
+  portal to `<body>` is the main reason to use this over a locally-positioned div.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Panel slides in from the right/left edge, full height | `ScDrawer` |
+| Small contextual help bubble anchored to an "?" icon | `ScInfoPopup` |
+| Profile / account flyout anchored to the sidebar footer | `ScProfilePopup` (panel body only — you position it) |
+| Cross-product app switcher overlay | `ScAppSwitchPanel` via `StreamoidSidebar`'s `switchPanel` / `switchPanelOpen` |
+| Kebab / context menu of actions | `ScMenuOptions` rows inside your own positioned container |
+| Onboarding step callout with Skip / Next | `ScGuide` |
+| Non-blocking toast / inline banner | `CreditWarningBanner` (exported without the `Sc` prefix), or your app's toast |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScDrawer` — same portal + Escape contract, but edge-anchored, 512px wide, and **no backdrop by default** | `ScModal` always has a scrim |
+| `ScProfilePopup` — a *panel body*, renders no overlay and owns no open state | `ScModal` is the overlay |
+| Catalogix's local `Modal` (`app/components/Modal`) — a much larger legacy shell with pagers/tabs/blur | `CenterModal` is the thin `ScModal` wrapper |
+
+---
+
+## 4. Why to use it
+
+- **Portalling is already correct.** `createPortal(…, document.body)` means the
+  dialog is genuinely viewport-fixed even when rendered from inside a transformed,
+  `overflow: hidden` or `z-index`-trapped subtree. This is the single most common
+  hand-rolled-modal bug.
+- **The scrim is the *fixed* scrim.** It is a deliberate neutral
+  `rgba(16, 16, 16, 0.7)` — the legacy navy `rgba(11, 8, 30, 0.5)` cast a blue tint
+  over everything behind the dialog. Rolling your own reintroduces that.
+- **Dismissal is wired once.** Escape is a document listener that is added and
+  removed with `open`, and backdrop close checks `e.target === e.currentTarget` so
+  a mousedown inside your content never closes the dialog.
+- **SSR-safe.** Returns `null` when `typeof document === "undefined"` instead of
+  throwing in `createPortal`.
+- **One place to change.** Scrim opacity, panel radius and the left-nav inset are
+  one edit for every dialog in the app.
+
+---
+
+## Gotchas
+
+**1. `open` defaults to `true`.** A mounted `ScModal` with no props is a visible
+modal. Either mount it conditionally or always pass `open`.
+
+```tsx
+// WRONG — permanently open
+<ScModal onClose={close}>…</ScModal>   // rendered unconditionally
+
+// RIGHT — either of these
+{isOpen && <ScModal onClose={close}>…</ScModal>}
+<ScModal open={isOpen} onClose={close}>…</ScModal>
+```
+
+**2. `className` / `style` are the *backdrop*, not the panel.** Sizing the dialog
+with `style` silently resizes the scrim instead.
+
+```tsx
+// WRONG — sets width on the full-screen scrim; the panel stays content-sized
+<ScModal style={{ width: 560 }}>…</ScModal>
+
+// RIGHT
+<ScModal contentStyle={{ width: 560 }}>…</ScModal>
+```
+
+**3. No dialog a11y at all.** No `role="dialog"`, no `aria-modal`, no focus trap,
+no focus restore, no `aria-labelledby`, no body-scroll lock. And because there is
+no props spread, you cannot pass aria onto the panel — wrap your children:
+
+```tsx
+<ScModal onClose={close}>
+  <div role="dialog" aria-modal="true" aria-labelledby="t">
+    <h2 id="t">Title</h2>
+  </div>
+</ScModal>
+```
+
+**4. Tall content overflows the viewport with no scrollbar.** The panel has
+`padding: 24px` and a radius and *no* size constraints. Always set
+`maxHeight` + `overflow: auto` in `contentStyle` for anything list-shaped.
+
+**5. Backdrop close is on `mousedown`, not `click`.** Two consequences: a
+text-selection drag that ends on the backdrop still closes; and the modal
+disappears before any underlying `click` handler would fire. Set
+`closeOnBackdrop={false}` for dialogs with drag interactions inside.
+
+**6. `padding-left: var(--leftMenuWidth, 0)` is a Catalogix contract.** The scrim
+insets itself by that variable so the dialog centers in the content area rather
+than the whole window. Catalogix defines it; **CXO, Photogenix and Artifax do
+not**, so it falls back to `0` and the scrim covers the sidebar too. Define
+`--leftMenuWidth` on your app root if you want the inset.
+
+**7. The scrim is intentionally not theme-flipped.** It's a hardcoded dark
+`rgba(16, 16, 16, 0.7)`, because a scrim is dark in both light and dark mode.
+Don't "fix" it with a light-mode override.
+
+**8. `z-index: 999` is hardcoded** — there is no `zIndex` prop (unlike `ScDrawer`).
+To stack something above a modal, either give that thing a higher z-index or
+raise this one via `style={{ zIndex: … }}`. A drawer over a modal is exactly what
+`ScDrawer`'s `zIndex` prop exists for.
+
+**9. `onClose` is optional.** Omit it and neither Escape nor the backdrop does
+anything — you have built an undismissable modal with no close button.
+
+**10. No enter/exit animation.** `open={false}` unmounts immediately. If you need
+a fade, animate inside `children`.
+
+---
+
+## In the wild
+
+```jsx
+// catalogix/dashboard  app/components/CenterModal/index.jsx:12
+<ScModal
+  onClose={props.onClose}
+  className={props.className}
+  style={props.style}
+  contentStyle={props.contentStyle}
+  // Legacy ConterModal closed only on outside/backdrop click, never on Escape.
+  // Opt out to preserve parity (QuickInviteModal must not discard a typed email).
+  closeOnEsc={false}
+>
+  {props.children}
+</ScModal>
+```
+
+---
+
+## Related
+
+- `ScDrawer` — the edge-anchored sibling; same portal/Escape contract, opt-in backdrop, `zIndex` prop.
+- `ScInfoPopup` — the tiny non-blocking contextual popover.
+- `ScProfilePopup` — panel body for the profile flyout; you own the overlay and placement.
+- `ScGuide` — onboarding callout card (Skip / step / Next), not a dialog shell.
+- `ScButton` — the confirm/cancel pair inside the footer you build.