@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/StreamoidWorkspaceSwitcher.md

@@ -0,0 +1,307 @@
+---
+component: StreamoidWorkspaceSwitcher
+package: "@streamoid/ui"
+category: overlays
+status: legacy
+renders: div
+tags: [workspace-switcher, switch-workspace, modal, overlay, tenant, workspace-list, tailwind]
+related: [ScWorkspaceSwitchCard, ScIntialProfileCover, ScRole, ScPairtext, ScProfilePopup]
+do_not_confuse_with: [ScWorkspaceSwitchCard, ScWorkspaceCard, ScWorkspace, ScWorkspaceSwitchMobileV2, ScModal]
+required_props: [open, onClose, workspaces, onSwitchWorkspace]
+---
+
+# StreamoidWorkspaceSwitcher
+
+**The DS's prebuilt "switch workspace" modal — and the one component in this family
+that needs Tailwind in the host.** A 1000×60vh centred dialog with a title bar, a
+close icon, a scrolling list of workspace rows (initials tile, name, role pill, user
+count, owner, and a Switch / Current button), Escape-to-close and backdrop-click
+dismissal. Note the export is **`StreamoidWorkspaceSwitcher`** — no `Sc` prefix.
+
+## TL;DR for agents
+
+- **Reach for it when:** your host already runs Tailwind and you want the whole
+  switch-workspace modal without building the shell.
+- **Don't reach for it when:** you want the row only (→ `ScWorkspaceSwitchCard`, what
+  all four apps actually use), your host has no Tailwind, or you need the current/other
+  grouping and a search box (this component has neither).
+- **Four things that will bite you:**
+  1. Its layout is written in **Tailwind utility classes** (`fixed inset-0 z-50`,
+     `flex`, `truncate`, `size-full`, `min-w-0`, `overflow-y-auto`) that
+     `@streamoid/ui/dist/index.css` **does not ship**. Without Tailwind in the host
+     the modal does not overlay, does not scroll and does not centre.
+  2. **No host app uses it.** CXO, Catalogix, Photogenix and Artifax each hand-roll
+     the modal around `ScWorkspaceSwitchCard` instead.
+  3. It returns `null` when `open` is false — it does **not** render a hidden panel,
+     and it does not portal, so it inherits your stacking context.
+  4. It has no `className` and no style escape hatch. Every dimension (1000px cap,
+     60vh height, the 80/120/200px column widths) is hardcoded inline.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import {
+  StreamoidWorkspaceSwitcher,
+  type WorkspaceSwitcherItem,
+  type WorkspaceSwitcherConfig,
+} from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root — plus Tailwind, see Gotcha 1
+```
+
+> The previous version of this file said `@streamoid/workspace`. **That package does
+> not exist** — this component ships in `@streamoid/ui`.
+
+### Minimal usage
+
+```tsx
+<StreamoidWorkspaceSwitcher
+  open={open}
+  onClose={() => setOpen(false)}
+  workspaces={workspaces}
+  onSwitchWorkspace={(ws) => void switchTo(ws.id)}
+/>
+```
+
+### Props
+
+`StreamoidWorkspaceSwitcherProps`
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `open` | `boolean` | — | **Required.** `false` → returns `null` (nothing mounted). |
+| `onClose` | `() => void` | — | **Required.** Called by the close icon, a backdrop click (only when the click target *is* the backdrop), and Escape. |
+| `workspaces` | `WorkspaceSwitcherItem[]` | — | **Required.** Rendered in array order — no grouping, no sorting, no search. |
+| `onSwitchWorkspace` | `(ws: WorkspaceSwitcherItem) => void \| Promise<void>` | — | **Required.** Fires only for rows where `isCurrent` is falsy; a current row closes the modal instead. |
+| `loading` | `boolean` | `false` | Shows `config.loadingText` **only while `workspaces` is also empty**. No spinner, no skeleton. |
+| `config` | `WorkspaceSwitcherConfig` | – | The four label strings. |
+
+`WorkspaceSwitcherItem`
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string` | Required; used as the React `key`. |
+| `name` | `string` | Required. Clamped to **2 lines** (`-webkit-line-clamp: 2`). |
+| `initials` | `string?` | Falls back to first letters of the first two words, else `"WS"`. |
+| `role` | `"admin" \| "member" \| string` | Normalised: **only the exact lowercase `"admin"` is admin**; everything else is member. |
+| `userCount` | `string?` | Free text — you format it (`"12 Users"`). Renders `"–"` when absent. |
+| `ownerEmail` | `string?` | Renders `"–"` when absent. |
+| `isCurrent` | `boolean?` | Swaps the trailing button to a disabled "Current workspace" at `opacity: 0.5`. |
+
+`WorkspaceSwitcherConfig`
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `title` | `string?` | `"Switch workspace"` | Dialog title. |
+| `loadingText` | `string?` | `"Loading workspaces…"` | Shown only when `loading && workspaces.length === 0`. |
+| `currentWorkspaceText` | `string?` | `"Current workspace"` | Disabled button label on the current row. |
+| `switchWorkspaceText` | `string?` | `"Switch workspace"` | Button label on every other row. |
+
+### What each row renders
+
+| Slot | Content | Width |
+|---|---|---|
+| Tile | `ScIntialProfileCover` — **initials only, no image support** | 60px (its default) |
+| Name | 2-line clamp | flex |
+| Role | `ScRole type={admin\|member}` | forced `80px` inline |
+| Users | `ScPairtext` with `SiconTeam` | `120px` inline |
+| Owner | `SiconCrown` + truncated email | `200px` inline |
+| Action | `ScButton` — `secondary` + `icon-left` switch, or `outline` + `state="disabled"` | `200px` inline |
+
+### Recipes
+
+```tsx
+// Driving it from your workspace store
+<StreamoidWorkspaceSwitcher
+  open={switcherOpen}
+  onClose={() => setSwitcherOpen(false)}
+  loading={wsLoading}
+  workspaces={workspaces.map((w) => ({
+    id: w.id,
+    name: w.name,
+    initials: w.initials,
+    role: w.role === "admin" ? "admin" : "member",   // exact lowercase, see Gotcha 5
+    userCount: `${w.memberCount} Users`,             // you format the string
+    ownerEmail: w.ownerEmail,
+    isCurrent: w.id === currentWorkspaceId,
+  }))}
+  onSwitchWorkspace={async (ws) => { await switchTo(ws.id); setSwitcherOpen(false); }}
+  config={{ title: "Switch workspace", switchWorkspaceText: "Switch" }}
+/>
+
+// Opened from the profile menu
+<ScProfilePopup /* … */ onSwitchWorkspace={() => setSwitcherOpen(true)} />
+
+// What the hosts do instead: own the shell, use the row
+<ScModal open={open} onClose={close}>
+  {others.map((ws) => (
+    <ScWorkspaceSwitchCard key={ws.id} wsName={ws.name} role={ws.role} plan={ws.plan}
+      ownerId={ws.ownerEmail} type="otherWS" onSwitch={() => void switchTo(ws)} />
+  ))}
+</ScModal>
+```
+
+A JSON shape for the labels + rows is checked in beside the source at
+`src/SC-WorkspaceSwitcher/workspace-switcher.example.json`.
+
+---
+
+## 2. Where to use it
+
+Intended for any desktop shell's "Switch workspace" flow, opened from
+`ScProfilePopup`'s `onSwitchWorkspace` or a sidebar workspace row.
+
+In practice **all four hosts built their own modal** and reused only the row:
+
+| App | Their shell |
+|---|---|
+| CXO | `src/app/components/app-workspace-switcher.tsx` (+ search + current/other sections) |
+| Catalogix | `app/containers/LeftMenu/WorkspaceListing/index.jsx` |
+| Photogenix | `dashboard/client/src/components/layout/Sidebar.tsx` |
+| Artifax | `packages/shared/src/components/DashboardSidebar.tsx` (also fetches plans per row) |
+
+They did that because they needed search, current/other grouping, a plan column and
+per-row settings/leave actions — none of which this component offers.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The host already ships Tailwind **and** a flat, unsearchable list of workspaces is
+  genuinely enough.
+- You want Escape + backdrop dismissal handed to you.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Anything in a non-Tailwind host | `ScWorkspaceSwitchCard` inside `ScModal` / `ScDrawer` |
+| You need search, grouping, or a plan column | `ScWorkspaceSwitchCard` in your own shell (what all four apps do) |
+| You need per-row settings / leave actions | `ScWorkspaceSwitchCard`'s `onSettings` / `onLeave` |
+| Workspace rows with avatars (not just initials) | `ScWorkspaceSwitchCard` (`imageUrl` → `ScDp`) |
+| Mobile | `ScWorkspaceSwitchMobileV2` |
+| A generic modal shell you fill yourself | `ScModal` |
+| A workspace card with a user count and a CTA | `ScWorkspaceCard` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScWorkspaceSwitchCard` — **one row**, `wsName`/`role`/`plan`/`ownerId`, hover actions, avatar support | `StreamoidWorkspaceSwitcher` is the whole modal, initials only, no plan |
+| `ScWorkspace` — the bare identity line (not exported) | this is a dialog |
+| `ScWorkspaceCard` — card + persistent CTA | this lists many |
+| `ScModal` — the DS modal primitive | this is a purpose-built dialog with no children slot |
+| `ScProfilePopup` — the profile menu that *opens* this | different panel |
+
+Naming: this is the only workspace component **without** the `Sc` prefix — the sibling
+of `StreamoidSidebar` in that respect. `ScWorkspaceSwitcher` does not exist.
+
+---
+
+## 4. Why to use it
+
+What it does give you, if the Tailwind precondition holds:
+
+- **Dismissal wired three ways** — the close icon, Escape (a `keydown` listener added
+  only while `open`, and cleaned up), and a backdrop click that correctly checks
+  `e.target === e.currentTarget` so clicks inside the dialog don't close it.
+- **`isCurrent` handled** — the current row's button becomes a disabled
+  "Current workspace", and clicking its switch path closes the modal instead of firing
+  `onSwitchWorkspace`.
+- **Async-aware** — `onSwitchWorkspace` may return a promise; the component `void`s it
+  rather than assuming sync.
+- **Composed from real DS parts** — `ScIntialProfileCover`, `ScRole`, `ScPairtext`,
+  `ScVDivider`, `ScButton` — so the row internals stay on-token.
+- **Initials derivation and role normalisation** are built in.
+
+What it costs: a Tailwind dependency, no style hooks, no search/grouping, and a
+divergence from the row every host already renders. That is why it is marked
+**legacy** here — not because it is broken, but because the ecosystem chose
+`ScWorkspaceSwitchCard` + a host shell.
+
+---
+
+## Gotchas
+
+**1. It needs Tailwind, and the DS does not ship it.** The overlay, centring,
+scrolling and truncation are Tailwind utilities (`fixed inset-0 z-50 flex items-center
+justify-center`, `flex-1 min-h-0 overflow-y-auto`, `truncate`, `size-full`, `w-6 h-6`,
+`shrink-0`). None of those class names exist in `@streamoid/ui/dist/index.css`. In a
+plain-CSS host the "modal" renders as an inline block in the document flow.
+
+```tsx
+// WRONG in a non-Tailwind host — renders unstyled, in flow, with no overlay
+<StreamoidWorkspaceSwitcher open workspaces={list} onClose={close} onSwitchWorkspace={go} />
+
+// RIGHT — build the shell with tokens/ScModal and reuse the row
+<ScModal open={open} onClose={close}>
+  {list.map((ws) => <ScWorkspaceSwitchCard key={ws.id} wsName={ws.name} type="otherWS" onSwitch={() => go(ws)} /* … */ />)}
+</ScModal>
+```
+
+**2. No `className`, no `style`, no spread.** `StreamoidWorkspaceSwitcherProps` has
+exactly six keys. Width (`min(1000px, 90vw)`), height (`60vh`) and the 80/120/200px
+column widths are inline literals you cannot reach.
+
+**3. It does not portal.** The `fixed` root is rendered where you mount it, so it
+inherits ancestor `transform` / `filter` / `contain` — any of which turn `fixed` into
+"relative to that ancestor" and break the overlay. Mount it near the app root.
+
+**4. `loading` only shows while the list is empty.** `loading && workspaces.length === 0`
+is the condition, and the fallback is a single line of text — no spinner, and no
+indication during a refresh of an already-populated list.
+
+**5. Role matching is exact-lowercase.** `normalizeRole` is
+`role === "admin" ? "admin" : "member"` — `"Admin"`, `"ADMIN"` and `"owner"` all render
+the grey **Member** pill. Lowercase before you pass it. (This differs from
+`ScWorkspaceSwitchCard`, which lowercases for you.)
+
+**6. `userCount` is a formatted string, not a number.** Pass `"12 Users"`; a bare
+number renders as bare digits with no unit.
+
+**7. Initials only — no avatars.** The tile is `ScIntialProfileCover`, which has no
+image support at all. `ScWorkspaceSwitchCard` uses `ScDp` and accepts `imageUrl`.
+
+**8. `name` is clamped to two lines, not ellipsised to one.** Row height varies with
+name length.
+
+**9. The dialog has no ARIA.** No `role="dialog"`, no `aria-modal`, no `aria-labelledby`,
+no focus trap and no focus restore on close. Escape works; nothing else about it is
+accessible. Wrap it or use `ScModal` if that matters.
+
+**10. Nothing in the rows is keyboard-reachable except the buttons.** The close "icon"
+is a `<div onClick>` with `cursor: pointer` — not a button, not focusable, no
+`aria-label`.
+
+**11. `config` is all-or-nothing per field, and there is no `emptyText`.** An empty
+`workspaces` array with `loading={false}` renders a blank scroll area.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+No app imports it (the only hits outside the package are Vite's prebundled dep cache,
+`artifax/frontend-react/.vite/deps/@streamoid_ui.js`, which is build output, not a
+render site). The surface it belongs on is the workspace-switch modal each host builds
+by hand — e.g. `cxo-dashboard src/app/components/app-workspace-switcher.tsx:408` or
+`catalogix/dashboard app/containers/LeftMenu/WorkspaceListing/index.jsx:371`, both of
+which render `ScWorkspaceSwitchCard` rows inside their own shell. Adopting this
+component would mean adding search + current/other grouping + a plan column to it
+first.
+
+---
+
+## Related
+
+- `ScWorkspaceSwitchCard` — **the row all four hosts actually use**; richer than the row here.
+- `ScModal` / `ScDrawer` — the shells to build your own switcher in.
+- `ScIntialProfileCover` / `ScRole` / `ScPairtext` / `ScButton` — the parts each row composes.
+- `ScProfilePopup` — `onSwitchWorkspace` is the trigger for this flow.
+- `ScWorkspaceSwitchMobileV2` — the mobile surface.

package/dist/docs/UsageHistoryMobile.md

@@ -0,0 +1,235 @@
+---
+component: UsageHistoryMobile
+package: "@streamoid/ui"
+category: mobile
+status: stable
+renders: div
+tags: [mobile, billing, usage, credits, log, history, row, list-item, cxo]
+related: [InvoiceHistoryMobile, ScBillingLogsTableList, ScBillingLogsTableHeader, ScUsageHistoryMobile]
+do_not_confuse_with: [ScUsageHistoryMobile, InvoiceHistoryMobile, ScBillingLogsTableList, ScCreditsUsageCardMobile]
+used_by: [cxo]
+---
+
+# UsageHistoryMobile
+
+**One credit-usage log row in CXO's mobile billing list.** Two rows inside one row:
+service name + a **red** credit figure on top, then `user · date` + a running balance
+underneath, with a 0.5px bottom border. Note the export name: **no `Sc` prefix**.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are rendering the "Usage history" tab of a mobile billing
+  screen, one component per credit-debit log entry.
+- **Don't reach for it when:** you're on desktop (→ `ScBillingLogsTableHeader` +
+  `ScBillingLogsTableList`), the row is an invoice (→ `InvoiceHistoryMobile`), or you
+  want the aggregate credits meter (→ `ScCreditsUsageCardMobile`).
+- **Four things that will bite you:**
+  1. **The export is `UsageHistoryMobile`, not `ScUsageHistoryMobile`.** A
+     `ScUsageHistoryMobile` exists in the source tree
+     (`src/SC-UsageHistory-Mobile/`) but is **not exported**.
+  2. **No `onClick`, and no props spread.** `className` is the only extra prop.
+  3. **`credits` is always red** and **`balance` always tertiary grey** — a credit
+     *refund* still renders as a debit.
+  4. All five text props have demo defaults (`"Artifax Generation"`, `"50"`,
+     `"Rohan"`, `"Nov 9th, 2025"`, `"84,902"`).
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { UsageHistoryMobile } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+{logs.map((log) => (
+  <UsageHistoryMobile
+    key={log.id}
+    serviceName={log.serviceName}
+    credits={log.amount.toLocaleString("en-US")}
+    userName={log.userName}
+    date={formatDate(log.createdAt)}
+    balance={log.balanceAfter.toLocaleString("en-US")}
+  />
+))}
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `serviceName` | `string` | `"Artifax Generation"` | ⚠️ Demo default. 14px primary, top-left, `flex: 1` + ellipsis. |
+| `credits` | `string` | `"50"` | ⚠️ Demo default. 16px/600 top-right, hardcoded `--alias-text-and-icons-error` **red**. You supply any sign/prefix. |
+| `userName` | `string` | `"Rohan"` | ⚠️ Demo default. Bottom-left, before a 12px vertical divider. |
+| `date` | `string` | `"Nov 9th, 2025"` | ⚠️ Demo default. Bottom-left, after the divider. Pre-formatted string. |
+| `balance` | `string` | `"84,902"` | ⚠️ Demo default. Bottom-right, tertiary grey — the balance **after** this entry. |
+| `className` | `string` | – | Appended after internal classes (safely — uses `className ?? ""`). **The only extra prop it accepts.** |
+
+That is the whole API. No `onClick`, no `...props`, no icon, no status.
+
+### Layout
+
+| | left | right |
+|---|---|---|
+| **row 1** | `serviceName` (14px primary, truncates) | `credits` (16px/600 **red**) |
+| **row 2** | `userName` │ `date` (14px tertiary, 9px gap, 0.5px vertical rule) | `balance` (14px tertiary) |
+
+Row 2's left group is `flex: 1; min-width: 0`, but `userName` and `date` are each
+`flex-shrink: 0`, so a very long user name pushes the date out rather than truncating
+itself.
+
+### Recipes
+
+```tsx
+// Make the row tappable — the component has no onClick
+<div role="button" tabIndex={0} onClick={() => openLog(log)} className="cursor-pointer">
+  <UsageHistoryMobile
+    serviceName={log.service?.serviceGroupName ?? "—"}
+    credits={log.amount.toLocaleString("en-US")}
+    userName={userMap[log.triggeredByUserId] ?? "User"}
+    date={formatDate(log.createdAt)}
+    balance={log.balanceAfter.toLocaleString("en-US")}
+  />
+</div>
+
+// System-triggered entries have no user — show an em dash, not "undefined"
+<UsageHistoryMobile
+  serviceName={log.service?.serviceGroupName ?? log.meta?.info ?? "—"}
+  credits={log.amount.toLocaleString("en-US")}
+  userName={log.triggeredByUserId ? (userMap[log.triggeredByUserId] ?? "User") : "—"}
+  date={formatDate(log.createdAt)}
+  balance={formatCredits(log.balanceAfter)}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO mobile billing screen**, inside the "Usage history" tab of the
+  `ScTabSwitcher`, below `ScPlanDetailsCardMobile` and `ScCreditsUsageCardMobile`.
+- Any narrow scrolling ledger of "what was spent, by whom, when, balance after".
+
+The row draws its own bottom border, so stack them with no gap and no dividers of your
+own. It composes nothing from the DS (the vertical rule is a 0.5px `border-left` div,
+not `ScVDivider`).
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The viewport is mobile and each log entry needs four facts plus a service name.
+- You already have every value as a display string.
+- The list is read-only, or you own the tap target yourself.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Desktop credit/usage log table | `ScBillingLogsTableHeader` + `ScBillingLogsTableList` |
+| Mobile invoice rows (money in, green) | `InvoiceHistoryMobile` |
+| Desktop invoice table | `ScBillingHistoryHeader` + `ScBillingHistoryTableList` |
+| The credits meter / "buy credits" summary | `ScCreditsUsageCardMobile` |
+| A generic member row on mobile | `ScTableListMobile` |
+| A row that must be clickable with DS semantics | `ScTableListMobile` (`onRowClick`) |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScUsageHistoryMobile` in `src/SC-UsageHistory-Mobile/` — a near-identical copy with `title`/`usageCount`/`totalCount` instead of `serviceName`/`credits`/`balance`, plus `onClick` | It is **not exported** from `index.ts`, its CSS is **not** in `dist/index.css`. Importing it will fail. |
+| `InvoiceHistoryMobile` — same chrome, one text column, **green** amount | Usage is red credits out; invoices are green money in |
+| `ScCreditsUsageCardMobile` — the aggregate card at the top of the screen | This is a single ledger line |
+| `ScBillingLogsTableList` — the desktop row | Different metrics; needs a header component |
+
+---
+
+## 4. Why to use it
+
+- **Four values in a 2×2 grid without a table.** The nested flex rows with
+  `min-width: 0` and per-cell `flex-shrink` are exactly what hand-rolled mobile
+  ledgers get wrong — the money never wraps and never gets pushed off-screen.
+- **Colour semantics match the invoice row.** Red `--alias-text-and-icons-error` for
+  credits out, green for money in, tertiary grey for context — one consistent reading
+  across both tabs.
+- **Correct tokens.** It uses the real `--alias-text-and-icons-*` names (unlike much of
+  the mobile family), so it genuinely flips light/dark.
+- **Self-dividing**, so no trailing rule at the end of the list.
+
+---
+
+## Gotchas
+
+**1. The name has no `Sc` prefix.** Autocomplete for `Sc…` will not find it.
+
+```tsx
+// WRONG — not exported
+import { ScUsageHistoryMobile } from "@streamoid/ui";
+
+// RIGHT
+import { UsageHistoryMobile } from "@streamoid/ui";
+```
+
+**2. No props spread at all.** The signature is
+`({ serviceName, credits, userName, date, balance, className })`.
+
+```tsx
+// SILENTLY IGNORED — none of these reach the DOM
+<UsageHistoryMobile serviceName="X" onClick={open} style={{ opacity: 0.5 }} data-id="1" />
+
+// RIGHT — wrap it
+<div onClick={open} data-id="1"><UsageHistoryMobile serviceName="X" /></div>
+```
+
+**3. `credits` is unconditionally red.** There is no sign handling and no variant, so a
+credit grant or refund still reads as a debit. If you need both directions, prefix the
+string (`"+ 500"`) and accept the colour, or use a different row.
+
+**4. `balance` is not computed.** The component does no arithmetic — it is whatever
+string you pass. Passing the same value for `credits` and `balance` renders a
+plausible-looking but wrong ledger, so derive the running balance from your data.
+
+**5. Demo defaults on all five props.** Bare, it renders
+`Artifax Generation / 50 / Rohan · Nov 9th, 2025 / 84,902` — indistinguishable from
+real data in a screenshot.
+
+**6. `userName` and `date` don't truncate, they shove.** Both are `flex-shrink: 0`.
+A long user name pushes the date out of the visible row instead of ellipsising. Cap
+long names yourself.
+
+**7. The vertical rule between user and date is unconditional.** With
+`userName=""` you get a leading rule. Pass `"—"` rather than an empty string.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/mobile-billing-content.tsx:254
+<UsageHistoryMobile
+  key={log._id}
+  serviceName={log.service?.serviceGroupName ?? log.meta?.info ?? "—"}
+  credits={log.amount.toLocaleString("en-US")}
+  userName={log.triggeredByUserId ? (userMap[log.triggeredByUserId] ?? "User") : "—"}
+  date={formatDate(log.createdAt)}
+  balance={formatCredits(log.amount)}
+/>
+```
+
+---
+
+## Related
+
+- `InvoiceHistoryMobile` — the sibling row for the "Invoice history" tab.
+- `ScUsageHistoryMobile` (`src/SC-UsageHistory-Mobile/`) — the unexported earlier copy;
+  do not import it.
+- `ScBillingLogsTableHeader` / `ScBillingLogsTableList` — the desktop table.
+- `ScCreditsUsageCardMobile` — the aggregate meter above the tabs.
+- `ScTabSwitcher` / `ScTabComp` — what toggles invoice vs usage.