@streamoid/ui 0.6.17 → 0.6.19

package/dist/docs/ScMenuOptions.md

@@ -0,0 +1,308 @@
+---
+component: ScMenuOptions
+package: "@streamoid/ui"
+category: overlays
+status: stable
+renders: div
+tags: [menu, menu-item, menu-row, option, kebab, context-menu, sidebar-row, dropdown-item, whats-new]
+related: [ScProfilePopup, ScProfileOptions, ScSidebarMenu, ScButton, ScHDivider]
+do_not_confuse_with: [ScPopUpMenu, ScSidebarMenu, ScProfileOptions, ScTabComp]
+used_by: [cxo, photogenix, artifax]
+---
+
+# ScMenuOptions
+
+**One row of a menu.** Icon + label (+ an optional right-aligned version string),
+with hover fills and a red `error` variant. It renders no overlay, no list and no
+positioning — you stack these rows inside `ScProfilePopup`, a sidebar block, or your
+own anchored container.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a row in a profile flyout, an account/settings
+  menu, or a kebab/overflow menu.
+- **Don't reach for it when:** it's a primary-navigation row in the sidebar rail
+  (→ `ScSidebarMenu`), it's a button (→ `ScButton`), or you wanted the *container*
+  (→ `ScProfilePopup` / `ScModal` / `ScDrawer`).
+- **Five things that will bite you:**
+  1. **Three loud defaults**: `icon` is `SiconTeam`, `text` is `"Menu Option"`,
+     and `version` is the stale literal **`"v2.0.21"`** ⚠️.
+  2. `hover` is the **string** `"true" | "false"`, not a boolean.
+  3. Fixed `width: 12.5rem` (200px) and **no `cursor`** — every real call site
+     passes `style={{ width: "100%", cursor: "pointer" }}`.
+  4. It's a plain `<div>`: no role, no tabIndex, no keyboard activation. All three
+     hosts add those at the call site.
+  5. `version` only renders under `variant="with-v"`, and `variant="error"` only
+     colours the **label**, not your icon.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScMenuOptions } from "@streamoid/ui";
+import { SiconSettings } from "@streamoid/icons";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage — the shape all three hosts ship
+
+```tsx
+<ScMenuOptions
+  icon={<SiconSettings size={24} />}
+  text="Settings"
+  variant="default"
+  style={{ width: "100%", cursor: "pointer" }}
+  role="button"
+  tabIndex={0}
+  onClick={openSettings}
+  onKeyDown={(e) => {
+    if (e.key === "Enter" || e.key === " ") { e.preventDefault(); openSettings(); }
+  }}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `text` | `string` | `"Menu Option"` | ⚠️ Real default. The label. `flex: 1`, `nowrap`, `text-overflow: ellipsis` — and **no `title`**, so long labels truncate with no tooltip. |
+| `icon` | `JSX.Element` | `<SiconTeam />` | ⚠️ Real default — forget it and you ship a "team" glyph. Rendered raw (no clone, no size/colour normalisation). |
+| `variant` | `"default"` \| `"with-v"` \| `"error"` | `"default"` | `with-v` adds the right-aligned `version`; `error` turns the **label** `--alias-text-and-icons-error` and the hover fill `--alias-fill-error-secondary`. |
+| `version` | `string` | `"v2.0.21"` | ⚠️ A stale hardcoded version string. **Only rendered when `variant="with-v"`.** |
+| `hover` | `"true"` \| `"false"` | `"false"` | ⚠️ A **string** union, not a boolean. `"true"` force-renders the hover fill (Figma parity / screenshots). Real `:hover` already works. |
+| `className` | `string` | – | Concatenated unconditionally — see Gotcha 6. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div: `onClick`, `style`, `role`, `tabIndex`, `onKeyDown`, `aria-*`, `data-*`. |
+
+### What renders per variant
+
+| Region | `default` | `with-v` | `error` |
+|---|---|---|---|
+| Icon | `icon` (raw, unstyled) | same | same — **not** recoloured |
+| Label | `--alias-text-and-icons-primary` | same | `--alias-text-and-icons-error` |
+| Right slot | — | `version` in `--alias-text-and-icons-muted`, 12px, right-aligned | — |
+| Hover / `hover="true"` fill | `--alias-fill-neutral-neutralhover` | same | `--alias-fill-error-secondary` |
+
+There is no combination that gives you both a version string and error colouring.
+
+### Recipes
+
+```tsx
+// A menu block: rows + divider + a destructive row
+<div style={{ display: "flex", flexDirection: "column", gap: "var(--spacing-md)" }}>
+  <ScMenuOptions icon={<SiconTeam size={24} />}     text="Teams"        style={ROW} onClick={goTeams} />
+  <ScMenuOptions icon={<SiconBilling size={24} />}  text="Billing"      style={ROW} onClick={goBilling} />
+  <ScMenuOptions icon={<SiconSettings size={24} />} text="All settings" style={ROW} onClick={goSettings} />
+  <ScHDivider />
+  <ScMenuOptions icon={<SiconLogout size={24} />} text="Log out" variant="error" style={ROW} onClick={logout} />
+</div>
+// const ROW = { width: "100%", cursor: "pointer" };
+
+// The "What's new" row — ALWAYS pass version, or you ship "v2.0.21"
+<ScMenuOptions
+  icon={<SiconBolt size={24} />}
+  text="What's new"
+  variant="with-v"
+  version={`v${APP_VERSION}`}
+  style={ROW}
+  onClick={openChangelog}
+/>
+
+// Inside ScProfilePopup's extra-rows slot
+<ScProfilePopup
+  menuContent={<ScMenuOptions icon={<SiconCatalog size={24} />} text="Catalogs" style={ROW} onClick={goCatalogs} />}
+/>
+
+// Recolour the icon to match variant="error" yourself — the component won't
+<ScMenuOptions
+  variant="error"
+  icon={<SiconLogout size={24} color="var(--alias-text-and-icons-error)" />}
+  text="Log out"
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **Profile / account flyouts** — the Teams / Billing / Settings / What's new stack.
+  CXO (`profile-popup.tsx`), Artifax (`DashboardSidebar.tsx`) and Photogenix
+  (`layout/Sidebar.tsx`) all render exactly that quartet.
+- **Kebab / row-overflow menus** — Photogenix's `studio/BatchList.tsx`.
+- **Inside DS composites** — `ScProfilePopup` builds every one of its menu rows from
+  this component (adding `role="button"`, `tabIndex={0}` and an Enter/Space
+  `onKeyDown`), and `ScProfileOptions` does the same.
+- **Sidebar secondary blocks** — the non-navigation rows below the divider.
+
+One of the DS's most widely reached-for parts (the catalog's "universal core"). It
+is *not* used in Catalogix, which has app-local menus.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The row is **one action in a list of actions**, presented in a menu or flyout.
+- You want the hover fill, radius, gap, label truncation and semantic error
+  colouring to match every other menu in the product.
+- You are filling `ScProfilePopup`'s `menuContent` / `preFooterContent` slots.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A primary-navigation row in the sidebar rail (active state, collapsed mode) | `ScSidebarMenu` (or `StreamoidSidebar`'s `config`) |
+| The profile flyout **panel** itself | `ScProfilePopup` (panel body; you position + dismiss) |
+| A whole ready-made profile-options block | `ScProfileOptions` |
+| The overlay/container for your rows | `ScModal` (centered) / `ScDrawer` (edge) |
+| A call-to-action | `ScButton` |
+| A tab / view switch | `ScTabComp` / `ScTabSwitcher` |
+| A key:value display row | `ScPairtext` |
+| A checkbox or radio option row | `ScCheckField` / `ScRadio` |
+| A row in a data table | `ScTableList` / `ScTableHeader` |
+| A contextual help bubble | `ScInfoPopup` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScPopUpMenu` — legacy 242px twin whose label prop is `menu` and which has **no hover styling**; zero call sites | `ScMenuOptions` is the current row |
+| `ScSidebarMenu` — nav row with active/collapsed states, built for the rail | `ScMenuOptions` has no active state and no collapsed mode |
+| `ScProfileOptions` — a composed *block* of these rows | `ScMenuOptions` is one row |
+| `ScProfilePopup` — the panel body | `ScMenuOptions` never positions itself |
+| `ScTabComp` — visually similar icon+label div row, but a *tab* with an `active` prop | Different vocabulary; don't build tabs from menu rows |
+
+---
+
+## 4. Why to use it
+
+- **The hover fills are re-specced tokens, not guesses.** The default hover moved
+  from `neutralToHover` to `--alias-fill-neutral-neutralhover` (Figma node
+  2004:3893) and the error hover is `--alias-fill-error-secondary`. Every app gets
+  that in one place; hand-rolled rows are where light-mode hover contrast breaks.
+- **Error semantics come from tokens.** `variant="error"` reads
+  `--alias-text-and-icons-error`, so "Log out" / "Delete" look identical in CXO,
+  Photogenix and Artifax.
+- **Truncation is already handled.** `flex: 1` + `overflow: hidden` +
+  `text-overflow: ellipsis` + `white-space: nowrap` means a long workspace or
+  catalog name shortens instead of stretching the menu.
+- **The version row is a first-class variant.** "What's new · v1.2.3" is a real
+  product pattern; `with-v` gives you the muted 12px right-aligned slot rather than
+  a hand-aligned span.
+- **It composes into `ScProfilePopup` for free** — same radius, gap and padding, so
+  rows you add via the slots are indistinguishable from the built-in ones.
+
+---
+
+## Gotchas
+
+**1. Three defaults that ship real content.** `text="Menu Option"`,
+`icon=<SiconTeam />`, `version="v2.0.21"`. The last one is the nastiest: a stale
+version number that looks plausible.
+
+```tsx
+// WRONG — renders "What's new    v2.0.21" forever
+<ScMenuOptions text="What's new" variant="with-v" icon={<SiconBolt size={24} />} />
+
+// RIGHT
+<ScMenuOptions text="What's new" variant="with-v" version={`v${APP_VERSION}`} icon={<SiconBolt size={24} />} />
+```
+
+**2. `hover` is a string, not a boolean.**
+
+```tsx
+// WRONG — type error
+<ScMenuOptions text="Teams" hover={true} />
+
+// RIGHT (and only for design parity / screenshots — real :hover already works)
+<ScMenuOptions text="Teams" hover="true" />
+```
+
+**3. Fixed `width: 12.5rem` (200px) and no `cursor`.** Dropped into a flexible
+container it stays 200px, and the pointer never becomes a hand. The universal fix,
+present at every host call site:
+
+```tsx
+<ScMenuOptions … style={{ width: "100%", cursor: "pointer" }} />
+```
+
+**4. It's a `<div>` — no keyboard, no role.** Add them via the spread. Artifax
+factors this into a `buildMenuItemA11yProps(...)` helper; `ScProfilePopup` uses an
+`activateOnKey(handler)` helper. Do the same rather than shipping mouse-only menus.
+
+```tsx
+<ScMenuOptions
+  text="Billing" style={ROW}
+  role="button" tabIndex={0}
+  onClick={goBilling}
+  onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); goBilling(); } }}
+/>
+```
+
+**5. `variant="error"` does not recolour your icon.** The icon is rendered raw —
+no `cloneElement`, no `currentColor` (unlike `ScButton`). A red "Log out" label
+next to a white logout glyph is the default outcome; pass
+`color="var(--alias-text-and-icons-error)"` on the icon yourself.
+
+**6. `className` is concatenated unconditionally.** Omit it and the class attribute
+contains the literal string `undefined`. Cosmetic, but it breaks exact-match
+snapshot assertions.
+
+**7. `version` is silently dropped outside `with-v`,** and `with-v` + `error` is not
+a thing — the variants are mutually exclusive.
+
+**8. Long labels truncate with no tooltip.** There is no `title` attribute. If the
+label can be user data (a workspace or catalog name), wrap it or add `title` via the
+spread — the spread lands on the root, so `title` works there.
+
+**9. It is a row, not a menu.** No overlay, no `open`, no outside-click, no
+positioning, no `role="menu"` grouping. Wrap the stack yourself (`ScProfilePopup`,
+or your own absolutely-positioned container with `role="menu"`).
+
+**10. `icon` size is yours to manage.** The component does not size it. Hosts pass
+either `size={24}` or Tailwind `w-6 h-6` / `h-5 w-5`; mixing sizes in one menu makes
+the labels visibly misalign.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/profile-popup.tsx:298
+<ScMenuOptions
+  icon={<SiconTeam className="w-6 h-6" color={PRIMARY_ICON} />}
+  text="Teams"
+  variant="default"
+  style={{ width: "100%", cursor: "pointer" }}
+  onClick={() => {
+    onClose();
+    navigate(to("/settings/team"));
+  }}
+/>
+```
+
+```tsx
+// artifax  packages/shared/src/components/DashboardSidebar.tsx:952
+<ScMenuOptions
+  icon={<SiconBolt className="h-5 w-5" />}
+  text="What's new"
+  variant="with-v"
+  version={`v${__APP_VERSION__}`}
+  style={{ width: '100%', cursor: 'pointer' }}
+  {...buildMenuItemA11yProps("What's new", onClose)}
+/>
+```
+
+---
+
+## Related
+
+- `ScProfilePopup` — the profile flyout panel; builds its rows from this component and exposes `menuContent` for more.
+- `ScProfileOptions` — an older composed profile-options block, also made of these rows.
+- `ScSidebarMenu` — the primary-nav sibling, with active + collapsed states.
+- `ScPopUpMenu` — **legacy**, no hover styling, no call sites; don't pick it by mistake.
+- `ScHDivider` — the 0.5px rule you put between menu groups.
+- `@streamoid/icons` — check `packages/icons/ICONS.md` before drawing a new glyph.

package/dist/docs/ScMobileBottomAction.md

@@ -0,0 +1,252 @@
+---
+component: ScMobileBottomAction
+package: "@streamoid/ui"
+category: mobile
+status: stable
+renders: div
+tags: [mobile, bottom, footer, action-bar, cta, save, cancel, sticky, buttons]
+related: [ScMobileTopNav, ScButton, ScModal, ScDrawer]
+do_not_confuse_with: [ScButton, ScMobileTopNav, ScFieldButton, ScOnlyIcon]
+---
+
+# ScMobileBottomAction
+
+**The mobile screen's bottom action bar.** A bordered strip over
+`--alias-surface-canvas` holding one full-width primary button, or two 50/50 buttons
+(outline + primary) when `secondaryText` is set. The buttons are **real `<button>`
+elements** written from scratch — this component does **not** use `ScButton`.
+
+## TL;DR for agents
+
+- **Reach for it when:** a mobile screen or sheet ends in a committed action —
+  Save / Cancel, Continue, Delete.
+- **Don't reach for it when:** you need one button anywhere else (→ `ScButton`), an
+  icon+label CTA (→ `ScButton` with `styleVariant`), or the top bar
+  (→ `ScMobileTopNav`).
+- **Five things that will bite you:**
+  1. **These are native `<button>`s with no `type` attribute**, so inside a `<form>`
+     they default to `type="submit"` and will submit it.
+  2. **It is not `ScButton`.** No `variant`, no `loading`, no `icon`, no `size` — and
+     the primary's fill/text tokens differ from `ScButton`'s.
+  3. **The two labels have different font sizes** — primary 14px, secondary 16px.
+     That is what the CSS says; it is not a typo you can fix from outside.
+  4. **`text` defaults to `"Save Changes"`.**
+  5. **It is not sticky.** You position it.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScMobileBottomAction } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScMobileBottomAction text="Save changes" onClick={save} disabled={!isDirty} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `text` | `string` | `"Save Changes"` | ⚠️ Primary button label. Hardcoded English default. |
+| `disabled` | `boolean` | `false` | Sets the native `disabled` attribute **and** `opacity: 0.5` + `cursor: not-allowed`. Genuinely blocks clicks (unlike `ScButton`'s `loading`). |
+| `onClick` | `(e: React.MouseEvent) => void` | – | On the primary button. Does **not** land on the root. |
+| `secondaryText` | `string` | – | **Presence of this prop switches to the 2-button layout.** Renders the outline button, to the **left** of the primary. |
+| `secondaryDisabled` | `boolean` | `false` | Same treatment as `disabled`, for the outline button. |
+| `onSecondaryClick` | `(e: React.MouseEvent) => void` | – | On the outline button. |
+| `className` | `string` | – | Appended after internal classes. Unguarded concat — see Gotcha 6. |
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | – | Spread onto the root strip, **not** the buttons. |
+
+### What renders
+
+| `secondaryText` | Layout | Root gap |
+|---|---|---|
+| unset | one primary button, `flex: 1 0 0` (full width) | `0` |
+| set | outline button (left) + primary button (right), both `flex: 1 0 0` → 50/50 | `16px` |
+
+Both buttons are 40px tall, `--medium-5` (12px) radius, `8px 16px` padding. Primary =
+`--alias-fill-base-base` fill with `--alias-text-and-icons-inverse` text. Outline =
+transparent with a 1.25px `--alias-border-default` border and
+`--alias-text-and-icons-primary` text.
+
+### Recipes
+
+```tsx
+// One action
+<ScMobileBottomAction text="Continue" onClick={next} disabled={!canProceed} />
+
+// Two actions — secondary is the outline one, and sits on the LEFT
+<ScMobileBottomAction
+  text="Save changes"
+  onClick={save}
+  disabled={!isDirty || saving}
+  secondaryText="Cancel"
+  onSecondaryClick={close}
+  secondaryDisabled={saving}
+/>
+
+// Make it a sticky footer of a full-height mobile screen — the component does not do this
+<div className="flex flex-col h-full">
+  <ScMobileTopNav type="inApp" heading="Settings" menuIcon={<SiconMenu size={24} />} />
+  <div className="flex-1 overflow-y-auto">{body}</div>
+  <div className="shrink-0">
+    <ScMobileBottomAction text="Save changes" onClick={save} />
+  </div>
+</div>
+
+// Inside a <form>: give the buttons no chance to submit — put the bar outside the form,
+// or don't use a form at all (CXO wires plain onClick handlers).
+```
+
+---
+
+## 2. Where to use it
+
+The last child of a mobile screen or bottom sheet, below the scrolling body. The intended
+mobile shell is:
+
+```
+ScMobileTopNav          ← 56px, shrink-0
+<scrolling body>        ← flex-1, overflow-y auto
+ScMobileBottomAction    ← shrink-0
+```
+
+It also fits the footer of a mobile-width `ScDrawer` / `ScModal`, where the desktop would
+use a pair of `ScButton`s.
+
+It composes nothing from the DS.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The action is the **commitment point** of a whole mobile screen, not an inline control.
+- There are exactly one or two actions, and they should each take half the width.
+- You want the footer's border, canvas fill and 16/16/20px padding to match the rest of
+  the mobile surface.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Any single button, anywhere in a page body | `ScButton` |
+| A CTA that needs an icon, a spinner, or a colour role (`error`, `outline`, `mono`) | `ScButton` — this bar has none of those |
+| Three or more actions | `ScButton`s in your own row, or a `ScPopUpMenu` |
+| A button that sits inline with a form field | `ScFieldButton` |
+| A bare icon affordance | `ScOnlyIcon` |
+| The mobile top bar | `ScMobileTopNav` |
+| A destructive confirm | `ScModal` + `ScButton variant="error"` — this bar cannot render red |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScButton` — the real button primitive: `variant`, `type`, `size`, `loading`, `icon`, `styleVariant`, `state` | `ScMobileBottomAction` re-implements two buttons in CSS and exposes only text + disabled |
+| `ScButton state="disabled"` — a `div` with `pointer-events: none` | This bar's `disabled` is the **native** attribute on a real `<button>`, so it is properly announced and unclickable |
+| `ScMobileTopNav` — the top bar, icon slots | Same family, opposite end |
+
+A note on consistency: because this bar does **not** compose `ScButton`, its primary
+button's fill (`--alias-fill-base-base`) and radius (`--medium-5`) are its own. If you put
+an `ScButton` next to it, expect a small mismatch — CXO's mobile billing screen sidesteps
+this by hand-rolling the footer strip and putting a real `ScButton` inside it.
+
+---
+
+## 4. Why to use it
+
+- **Real `<button>` semantics.** Unlike `ScButton` (which is a `div role="button"`), both
+  buttons here are native, so `disabled` is genuinely announced and genuinely
+  unclickable, and Enter/Space work without extra wiring. That is the one place this
+  component is *better* than the primitive.
+- **The 1-vs-2 layout switch is one prop.** Adding `secondaryText` flips the root to
+  `gap: 16px` and inserts the outline button in the correct (left) position — no
+  conditional JSX at the call site.
+- **Correct footer chrome**: `--alias-surface-canvas` fill, 0.5px
+  `--alias-border-divider` top rule, and asymmetric `16px 16px 20px` padding so the bar
+  clears a phone's home indicator.
+- **Both buttons are `flex: 1 0 0; min-width: 0`,** so they always split the bar evenly.
+  (Note `flex-shrink: 0` plus `white-space: nowrap` labels: a very long label grows the
+  button past its share rather than ellipsising, so keep labels short.)
+
+---
+
+## Gotchas
+
+**1. The buttons have no `type` attribute, so inside a form they submit it.** A
+`<button>` without `type` defaults to `type="submit"`.
+
+```tsx
+// WRONG — tapping "Cancel" submits the form
+<form onSubmit={save}>
+  {fields}
+  <ScMobileBottomAction text="Save" onClick={save} secondaryText="Cancel" onSecondaryClick={close} />
+</form>
+
+// RIGHT — keep the bar outside the form, and drive it with onClick
+<form onSubmit={(e) => e.preventDefault()}>{fields}</form>
+<ScMobileBottomAction text="Save" onClick={save} secondaryText="Cancel" onSecondaryClick={close} />
+```
+
+**2. It is not `ScButton`.** There is no `variant`, `type`, `size`, `loading`,
+`styleVariant`, `icon` or `state`. You cannot make either button red, and you cannot show
+a spinner — track your own saving state and use `disabled`.
+
+**3. The two labels are different sizes.** `.buttonText` is
+`--font-size-font-size-sm` (14px) and `.outlineButtonText` is
+`--font-size-font-size-md` (16px). In the 2-button layout the *secondary* label is the
+bigger one. Nothing at the call site can change that.
+
+**4. `secondaryText` is the layout switch, not a style flag.** An empty string is falsy,
+so `secondaryText=""` silently gives you the 1-button layout.
+
+**5. `text` defaults to `"Save Changes"`.** Forget the prop and you ship that label on a
+"Delete account" screen.
+
+**6. `className` is concatenated unguarded.** Omit it and the root carries a literal
+`undefined` class. Also note `className` lands on the **root strip**, so you cannot
+restyle the buttons through it without descendant selectors.
+
+**7. Not sticky, not fixed, no `z-index`.** It is a static `width: 100%` strip. Wrap it
+yourself (`position: sticky; bottom: 0`, or a `shrink-0` child of a
+`flex-col h-full` screen).
+
+**8. `onClick` goes to the primary button, not the root.** Unlike most components in this
+family, `...props` on the root and `onClick` are separate — so `onClick` can never make
+the whole bar clickable.
+
+**9. `--medium-5` is not a real token.** The radius resolves via its `12px` fallback
+everywhere; `--radius-xl` is the token the rest of the library uses for the same value.
+
+---
+
+## 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 the same strip
+and put a real `ScButton` inside it — see
+`cxo-dashboard/src/app/components/mobile-billing-content.tsx:275`, which builds a
+`shrink-0` div with `backgroundColor: T.canvas`, a `0.5px` top border and
+`16px 16px 20px` padding (exactly this component's CSS) around an
+`ScButton variant="tertiary" styleVariant="icon-left"`. That call site is both where this
+component belongs and the reason it was skipped: the screen needed an icon in the button,
+which this bar cannot render.
+
+---
+
+## Related
+
+- `ScMobileTopNav` — the other half of the mobile shell.
+- `ScButton` — the real button primitive; reach for it whenever you need an icon, a
+  spinner, or a colour role.
+- `ScModal` / `ScDrawer` — the overlays whose mobile footers this bar suits.
+- `ScFieldButton` / `ScOnlyIcon` — the other action shapes in the library.