@streamoid/ui 0.6.17 → 0.6.19

package/dist/docs/ScInfoPopup.md

@@ -0,0 +1,248 @@
+---
+component: ScInfoPopup
+package: "@streamoid/ui"
+category: overlays
+status: stable
+renders: div (inline-block wrapper) > span[role="button"] trigger + absolutely-positioned div bubble (no portal)
+tags: [info, popover, tooltip, help, hint, question-mark, popup, contextual]
+related: [ScTextField, ScModal, ScGuide, ScBadges]
+do_not_confuse_with: [ScModal, ScPopUpMenu, ScProfilePopup, ScGuide]
+used_by: [catalogix]
+---
+
+# ScInfoPopup
+
+**The little ⓘ that opens a help bubble.** A self-contained 18px info glyph that,
+on click, reveals a small absolutely-positioned card (max 300 × 100px, scrollable)
+with a ✕ in the corner. It owns its own open state and its own outside-click
+dismissal — you pass only `content`.
+
+## TL;DR for agents
+
+- **Reach for it when:** a label or a table header needs a short explanation, and
+  you want the standard ⓘ affordance next to it.
+- **Don't reach for it when:** you're labelling a form field that is already a
+  `ScTextField` (it has an `info` prop that renders this for you), you need a
+  hover tooltip, you need a menu (→ `ScMenuOptions`), or the content is long
+  enough to need a dialog (→ `ScModal`).
+- **Four things that will bite you:**
+  1. **It is not portalled.** The bubble is `position: absolute` with
+     `z-index: 2`, so any ancestor with `overflow: hidden` clips it — that
+     includes `ScDrawer`, `ScMappingCard` and most cards.
+  2. **No positioning logic.** Hardcoded `top: 18px; right: 0; translateX(50%)` —
+     it always hangs half-way off to the right and is cut by the viewport edge.
+  3. **Keyboard users can focus the trigger but cannot open it.** `tabIndex={0}` +
+     `role="button"` with an `onClick` only — no `onKeyDown`.
+  4. **You cannot control it.** No `open` / `onOpenChange` / `defaultOpen`, no
+     `trigger` slot, no `icon` prop. The glyph is a hardcoded inline SVG.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScInfoPopup } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScInfoPopup content="Only rows that passed validation are exported." />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `content` | `ReactNode` | – | The bubble body. Rendered inside a `<span>`, so block-level children are technically invalid HTML — keep it to text / inline nodes. |
+| `className` | `string` | – | On the **outer wrapper** (the `inline-block` that contains the trigger *and* the bubble), appended after `.scInfoPopup`. There is no way to class the bubble itself. |
+
+That's the whole API. No `...props` spread — anything else is a type error.
+
+### What it actually renders
+
+```html
+<div class="scInfoPopup {className}">             <!-- position:relative; display:inline-block -->
+  <span class="infoIcon" role="button" tabindex="0" aria-label="More info">
+    <svg width="18" height="18">…</svg>           <!-- hardcoded ⓘ, --alias-text-and-icons-tertiary -->
+  </span>
+  <!-- only when open: -->
+  <div class="content">                            <!-- position:absolute; top:18px; right:0;
+                                                        translateX(50%); max-width:300px;
+                                                        z-index:2; radius 6px; padding 8px;
+                                                        background --alias-surface-base -->
+    <div class="closeIconContainer"><SiconClose size={18} /></div>
+    <span class="contentText">{content}</span>     <!-- 12px; max-height:100px; overflow-y:auto -->
+  </div>
+</div>
+```
+
+⚠️ The root is a **`<div>`**, not a span — dropping one inside a `<p>` or another
+inline-only element is invalid nesting even though the wrapper is `inline-block`.
+
+### Recipes
+
+```tsx
+// On a form field — DON'T nest your own; ScTextField already composes one
+<ScTextField label="Feed URL" required info="We poll this URL every 6 hours." />
+
+// Beside a table column header
+<div style={{ display: "flex", alignItems: "center" }}>
+  <span>Match rate</span>
+  <ScInfoPopup content="Share of feed rows that matched an existing product." />
+</div>
+
+// Rich (inline) content
+<ScInfoPopup content={<>Supported: <code>CSV</code>, <code>TSV</code>, <code>XLSX</code>.</>} />
+
+// Neutralise the baked-in 12px side margins when it must sit tight to a label
+<ScInfoPopup className="tight" content="…" />
+// .tight > span:first-child { margin: 0; }   /* .infoIcon has margin: 0 12px */
+```
+
+---
+
+## 2. Where to use it
+
+- **Form field labels** — but via `ScTextField`'s `info` prop, which renders this
+  component at `ScTextField.tsx:106`. That is by far the highest-traffic path.
+- **Table / list column headers** where the metric needs a definition.
+- **Settings rows** explaining what a toggle actually does.
+- **Catalogix** wraps it as `app/components/InfoPopup`, a pass-through that
+  preserves the old `content`-only API.
+
+Catalogix is the only direct host consumer. CXO/Photogenix/Artifax get it
+indirectly through `ScTextField`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The explanation is **one or two short sentences** and genuinely optional.
+- The trigger belongs **inline next to a label**, not as a separate control.
+- You want the standard glyph, bubble surface and dismissal without wiring state.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Explaining a `ScTextField` label | `ScTextField`'s own `info` prop (it renders this for you) |
+| A hover tooltip on an icon button | plain `title` attribute, or your app's tooltip — this is click-to-open |
+| Content longer than ~2 sentences, or with actions/links to click | `ScModal` |
+| A step-by-step onboarding callout with Skip / Next | `ScGuide` |
+| A menu of actions | `ScMenuOptions` rows in your own positioned container |
+| A status/validation message under a field | `ScTextField`'s helper/error text |
+| A dismissible warning banner | `CreditWarningBanner` (exported without the `Sc` prefix), or your app's banner |
+| A popover you need to open/close programmatically | roll your own — this component does not expose its state |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScModal` — portalled, scrimmed, blocking, caller-controlled | `ScInfoPopup` is inline, unportalled, self-controlled |
+| `ScPopUpMenu` / `ScMenuOptions` — a *menu row*, no popover at all | `ScInfoPopup` is the only component here that actually pops something up |
+| `ScProfilePopup` — a large profile *panel body* you position yourself | `ScInfoPopup` positions itself (badly) and owns its own state |
+| `ScGuide` — heading + body + Skip/Next, for guided tours | `ScInfoPopup` has no actions |
+
+---
+
+## 4. Why to use it
+
+- **Zero wiring.** Open state, the outside-click listener (added/removed with
+  `open`) and the ✕ are all internal. There is no app-level `OutsideClick`
+  dependency, so it works identically in all four hosts.
+- **The glyph is theme-aware and consistent.** The trigger circle, stroke and dot
+  are drawn with `--alias-text-and-icons-tertiary`, so the ⓘ has the same weight
+  and colour as every other tertiary icon in the product — the usual hand-rolled
+  version is a hardcoded grey that disappears in light mode.
+- **The bubble is already token-correct** — `--alias-surface-base` on a soft shadow
+  with `--alias-text-and-icons-primary` copy at 12px.
+- **Overflow is bounded.** `max-width: 300px` + `max-height: 100px; overflow-y: auto`
+  means an over-long help string degrades into a small scroller instead of blowing
+  out your layout.
+
+---
+
+## Gotchas
+
+**1. It is not portalled — clipping is the number-one failure.** The bubble lives
+inside the trigger's `position: relative` wrapper. Any ancestor with
+`overflow: hidden` cuts it off: `ScDrawer` (twice over), `ScMappingCard`,
+`ScProgressBar`, most cards, and any `text-overflow: ellipsis` row.
+
+```tsx
+// WRONG — bubble is clipped by the drawer's overflow:hidden
+<ScDrawer><ScInfoPopup content="…" /></ScDrawer>
+
+// RIGHT — put the ⓘ outside the clipping container, or use ScModal for the explanation
+```
+
+**2. `z-index: 2` only.** Anything with a higher z-index inside the same stacking
+context paints over the bubble. There is no prop to raise it; you'd have to
+override `.content` from an ancestor selector.
+
+**3. Placement is hardcoded and has no collision handling.**
+`top: 18px; right: 0; transform: translateX(50%)` means the bubble is *centred on
+the trigger's right edge* — half of it hangs to the right of the icon. Placed near
+the right edge of the screen (or of a narrow card), it is cut off. There is no
+`side` / `align` / flip prop.
+
+**4. Keyboard cannot open it.** The trigger is a `<span role="button" tabIndex={0}>`
+with `onClick` and **no `onKeyDown`** — Tab focuses it, Enter and Space do nothing.
+The ✕ is a bare `<div onClick>` with no role or tabIndex at all. If your surface
+must be keyboard-accessible, don't hide required information here.
+
+**5. `aria-label="More info"` is hardcoded English,** as is nothing else — but there
+is no label prop, so it cannot be localised without changing the DS.
+
+**6. The trigger carries `margin: 0 12px`.** You get 12px of horizontal space on
+both sides whether you want it or not; a `gap` on your flex parent stacks on top of
+it. Neutralise via `className` if you need it flush.
+
+**7. It is click-to-open, not hover.** Users expecting a tooltip will not discover
+it. Also: opening `stopPropagation()`s the click, so a click on the ⓘ never reaches
+a clickable parent row — usually what you want, occasionally surprising.
+
+**8. Dismissal is on `mousedown`, and re-clicking the ⓘ does not toggle.** The
+trigger only ever calls `setOpen(true)`; the outside-click listener closes it. A
+second click on the icon lands *inside* the wrapper, so it stays open. Close via
+the ✕ or by clicking elsewhere.
+
+**9. `className` styles the wrapper, not the bubble.** There is no
+`contentClassName`. To restyle the bubble you must write a descendant selector from
+your own class.
+
+**10. `content` renders inside a `<span>`.** Passing a `<div>`/`<p>`/list produces
+invalid nesting (it usually still renders, but don't rely on it). Keep it inline.
+
+---
+
+## In the wild
+
+```jsx
+// catalogix/dashboard  app/components/InfoPopup/index.jsx:9
+export default function InfoPopup({ content }) {
+  return <ScInfoPopup content={content} />;
+}
+```
+
+And composed inside the DS itself:
+
+```tsx
+// npm-components  packages/ui/src/SC-textField/ScTextField.tsx:106
+{info != null && <ScInfoPopup content={info} />}
+```
+
+---
+
+## Related
+
+- `ScTextField` — pass `info` and it renders this popup beside the label; the preferred path.
+- `ScModal` — for explanations too long or too interactive for a bubble.
+- `ScGuide` — guided-tour callout with Skip / step / Next.
+- `ScMenuOptions` — if what you actually wanted was a menu, not help text.

package/dist/docs/ScIntialProfileCover.md

@@ -0,0 +1,233 @@
+---
+component: ScIntialProfileCover
+package: "@streamoid/ui"
+category: profile
+status: stable
+renders: div
+tags: [initials, avatar, workspace-tile, placeholder, cover, misspelled-prop, intial]
+related: [ScDp, ScWorkspaceCard, ScProfile, ScWorkspaceSwitchCard]
+do_not_confuse_with: [ScDp, ScProfileImageUpdate, ScProfile, ScBadges]
+---
+
+# ScIntialProfileCover
+
+**An initials tile — 60px rounded square, no image path at all.** One grey box
+(`fill-neutral-neutralselected`, `radius-3xl`) with centred initials. Note the
+misspellings: the component is `ScIntialProfileCover` and its prop is **`intial`**.
+Both are load-bearing — you must reproduce them to compile.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need the workspace/profile *initials block* from the
+  Figma workspace rows and you know you will never have an image.
+- **Don't reach for it when:** an image might exist (→ `ScDp`, which has an
+  `onError` → initials fallback), or you need any interactivity or `aria` (this
+  component forwards **nothing**).
+- **Four things that will bite you:**
+  1. The prop is **`intial`** (sic), not `initial`. `initial="AC"` is a type error;
+     the tile silently shows the `"WS"` default if you cast around it.
+  2. It has **no image support**. Not `imageUrl`, not `children`.
+  3. It accepts **only** `intial`, `size`, `className`. No `style`, no `onClick`, no
+     `data-*`, no `aria-*` — `IScIntialProfileCoverProps` does not extend
+     `HTMLAttributes`.
+  4. The initials text is a fixed `1rem`; `size` does not scale it, and the box
+     clips (`overflow: hidden` on `.initials`).
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScIntialProfileCover } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScIntialProfileCover intial="AC" />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `intial` | `string` | `"WS"` | ⚠️ **Misspelled prop name** and ⚠️ a real default. Rendered with a literal trailing space (`{intial} `). |
+| `size` | `number` | – | px. When set, applies `width`/`height` **and zeroes the 1rem padding**. Unset → the CSS default of `3.75rem` (60px) **with** 1rem padding. |
+| `className` | `string` | – | Appended (concatenated unconditionally — a literal `undefined` class when omitted). |
+
+That is the entire API — three props, and no spread.
+
+### What `size` changes
+
+| `size` | Box | Padding | Notes |
+|---|---|---|---|
+| unset | `3.75rem` × `3.75rem` from CSS | `var(--spacing-3xl)` = 1rem | the Figma default block |
+| set | `{size}px` inline | `0` | inline `style` on the root; the CSS class rule is overridden |
+
+### Recipes
+
+```tsx
+// Workspace row tile, initials derived from the name
+<ScIntialProfileCover
+  intial={ws.initials || ws.name.split(/\s+/).slice(0, 2).map((w) => w[0]?.toUpperCase() ?? "").join("") || "WS"}
+  className="shrink-0"
+/>
+
+// Smaller tile — remember one character only, the font does not scale
+<ScIntialProfileCover intial="A" size={32} />
+
+// Needs a click, an image fallback, or an aria label? use ScDp instead
+<button type="button" onClick={open} aria-label={`Open ${ws.name}`}>
+  <ScDp type={ws.imageUrl ? "image" : "initial"} variant="workspace" initial="AC" imageUrl={ws.imageUrl} size={60} />
+</button>
+```
+
+---
+
+## 2. Where to use it
+
+Composed inside two DS components, not usually placed directly:
+
+| Parent | Role |
+|---|---|
+| `ScWorkspaceCard` | the workspace tile at the head of the card |
+| `StreamoidWorkspaceSwitcher` | the tile on each workspace row in the switch modal |
+
+Everything newer reaches for `ScDp` instead — `ScWorkspaceSwitchCard`,
+`ScWorkspaceSwitchMobileV2` and the sidebar shells all use `ScDp variant="workspace"`.
+Treat `ScIntialProfileCover` as the older, image-less spelling of the same idea.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are inside `ScWorkspaceCard` / `StreamoidWorkspaceSwitcher` territory and want
+  to match those tiles exactly (60px, `radius-3xl`).
+- The entity provably has no avatar (a brand-new workspace, a placeholder row).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| An avatar that may have an image | `ScDp` (`type="image"` + `imageUrl`, with initials fallback) |
+| A person avatar (circle) | `ScDp` with `variant="profile"` |
+| Clickable / focusable / labelled tile | `ScDp` wrapped in a `<button>` — this component forwards nothing |
+| Avatar upload / delete | `ScProfileImageUpdate` |
+| Avatar + name + subtext row | `ScProfile` |
+| A whole workspace row | `ScWorkspaceSwitchCard` |
+| A small text chip / count | `ScBadges` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScDp` — `initial` (spelled correctly), `variant`, `imageUrl`, `size` default 60, error fallback, accepts `style` | `ScIntialProfileCover` is initials-only with the misspelled `intial` |
+| `ScProfileImageUpdate` — editable avatar | this is display-only |
+| `ScProfile` — identity **row** | this is one tile |
+
+`ScDp` vs `ScIntialProfileCover` is the mis-pick to watch: they look identical at
+60px in the workspace variant. **If an image could ever exist, it is `ScDp`.**
+
+---
+
+## 4. Why to use it
+
+- **It is the exact Figma block** used by the workspace card and switch modal:
+  60 × 60, `radius-3xl` (1rem), `fill-neutral-neutralselected`, `text-md/medium`
+  centred. Re-deriving those four values by hand is how tile sizes drift between the
+  card and the modal.
+- **Token-driven**, so the grey and the text flip with the theme.
+- **Genuinely tiny** — if you know there is no image, it is a smaller commitment than
+  `ScDp`'s image/error state machine.
+
+Honestly though: `ScDp` gives you all of this plus the image path, accepts `style`,
+and is the one the newer components use. Prefer it in new code unless you are
+matching an existing `ScIntialProfileCover` tile.
+
+---
+
+## Gotchas
+
+**1. The prop is `intial`, not `initial`.**
+
+```tsx
+// WRONG — type error (and if you cast past it, you get "WS")
+<ScIntialProfileCover initial="AC" />
+
+// RIGHT
+<ScIntialProfileCover intial="AC" />
+```
+
+The component name is misspelled too (`ScIntialProfileCover`). Both are the published
+API — fixing them is a breaking change, so don't "correct" them locally.
+
+**2. `intial` defaults to `"WS"`.** Forget it and every tile reads "WS".
+
+**3. No `style` prop, no spread.** `IScIntialProfileCoverProps` is exactly
+`{ intial?, size?, className? }`. `onClick`, `title`, `aria-label`, `data-testid` and
+`style` are all rejected by TypeScript. Style it through `className`, and wrap it for
+interaction.
+
+```tsx
+// WRONG — type error; also no keyboard access even if it compiled
+<ScIntialProfileCover intial="AC" onClick={open} />
+
+// RIGHT
+<button type="button" onClick={open} aria-label="Acme workspace">
+  <ScIntialProfileCover intial="AC" />
+</button>
+```
+
+**4. `size` also zeroes the padding.** The two configurations are not just different
+sizes: unset gives `60px + 1rem padding`, set gives `{size}px + 0 padding`. The
+initials therefore sit closer to the edge at custom sizes.
+
+**5. Long initials clip, and the font never scales.** `.initials` is
+`font-size-md` (1rem) with `overflow: hidden` + `text-overflow: ellipsis`. Three
+letters, or two letters at `size={24}`, get cut.
+
+**6. It is a rounded square, never a circle.** `radius-3xl` (1rem) is baked in. For a
+person avatar you want `ScDp variant="profile"`, or override `border-radius` via
+`className`.
+
+**7. `className` is concatenated unconditionally** → `class="scIntialProfileCover undefined"`
+when omitted.
+
+**8. Trailing space in the text node** (`{intial} `) — `trim()` before asserting in
+tests.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+Composed at `src/SC-workspaceCard/ScWorkspaceCard.tsx:35` and
+`src/SC-WorkspaceSwitcher/streamoid-workspace-switcher.tsx:101`:
+
+```tsx
+// packages/ui  src/SC-WorkspaceSwitcher/streamoid-workspace-switcher.tsx:101
+<ScIntialProfileCover
+  intial={workspace.initials || deriveInitials(workspace.name)}
+  className="shrink-0"
+/>
+```
+
+Host apps that need a workspace tile use `ScDp` instead (e.g. artifax
+`packages/shared/src/components/DashboardSidebar.tsx:698`). If a host ever needs this
+tile directly it belongs on a workspace-creation or empty-state screen, where no
+avatar can exist yet.
+
+---
+
+## Related
+
+- `ScDp` — the avatar with an image path and an error fallback; prefer it in new code.
+- `ScWorkspaceCard` — renders this tile plus name/role/owner and a CTA.
+- `StreamoidWorkspaceSwitcher` — the switch modal whose rows use this tile.
+- `ScProfileImageUpdate` — the editable avatar.

package/dist/docs/ScInvoiceHistoryMobile.md

@@ -0,0 +1,187 @@
+---
+component: ScInvoiceHistoryMobile
+exported: false
+package: "@streamoid/ui"
+category: mobile
+status: deprecated
+renders: div
+tags: [mobile, billing, invoice, history, row, unexported, dead-code, superseded]
+related: [InvoiceHistoryMobile, ScUsageHistoryMobile, ScBillingHistoryTableList]
+do_not_confuse_with: [InvoiceHistoryMobile, ScUsageHistoryMobile, UsageHistoryMobile]
+---
+
+# ScInvoiceHistoryMobile
+
+**Do not use — this component is not shipped.** It is an earlier copy of the mobile
+invoice row that never made it into the public surface: it is absent from
+`src/index.ts`, so its JS is not in `dist/index.js`, its class names are not in
+`dist/index.css`, and `IScInvoiceHistoryMobileProps` is not in `dist/index.d.ts`.
+The shipped component is **`InvoiceHistoryMobile`** (no `Sc` prefix) in
+`src/SC-InvoiceHistoryMobile/`.
+
+## TL;DR for agents
+
+- **Reach for it when:** never. Use `InvoiceHistoryMobile` instead.
+- **Don't reach for it when:** always — importing `ScInvoiceHistoryMobile` from
+  `@streamoid/ui` throws/undefined at runtime and fails to type-check.
+- **Two things that will bite you:**
+  1. **It is not exported.** Neither the component nor its CSS reaches `dist/`.
+     Verified: `grep -c scInvoiceHistoryMobile dist/index.css` → `0`.
+  2. **The prop names differ from the shipped twin.** Here the id prop is
+     `invoiceNumber`; in `InvoiceHistoryMobile` it is `invoiceId`.
+
+---
+
+## 1. How to use it
+
+You don't. Import the shipped sibling:
+
+### Import
+
+```tsx
+// The component that actually ships:
+import { InvoiceHistoryMobile } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+
+// NOT THIS — `ScInvoiceHistoryMobile` is not an export of @streamoid/ui
+```
+
+### Minimal usage
+
+```tsx
+<InvoiceHistoryMobile
+  invoiceId={`# ${inv.number}`}
+  date={formatDate(inv.createdAt)}
+  amount={`$${inv.amountPaid.toFixed(2)}`}
+/>
+```
+
+### Props
+
+Documented only so you can recognise the difference when migrating a call site.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `invoiceNumber` | `string` | `"# INV-2800-2026"` | ⚠️ Demo default. **Renamed to `invoiceId`** in the shipped twin. |
+| `date` | `string` | `"Nov 9th, 2025"` | ⚠️ Demo default. Same name in the shipped twin. |
+| `amount` | `string` | `"₹320.89"` | ⚠️ Demo default in rupees. Same name in the shipped twin. Always success-green. |
+| `onClick` | `(e: React.MouseEvent) => void` | – | **Only exists here.** The shipped twin has no click handler. |
+| `className` | `string` | – | Unguarded concat — renders a literal `undefined` class when omitted. |
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | – | **Only exists here.** The shipped twin accepts no extra props. |
+
+### Mapping between the two
+
+| This (unexported) | Shipped `InvoiceHistoryMobile` |
+|---|---|
+| `invoiceNumber` | `invoiceId` |
+| `date` | `date` |
+| `amount` | `amount` |
+| `onClick` | *(none — wrap the row in your own clickable `div`)* |
+| `...props` spread | *(none — `className` only)* |
+| `className` (unguarded) | `className` (guarded with `?? ""`) |
+
+Styling is otherwise equivalent: 16px padding, 12px gap, 0.5px bottom divider, a
+truncating text column (`flex: 1 0 0` here, `flex: 1` in the shipped twin) and a
+`flex-shrink: 0` green amount.
+
+### Recipes
+
+```tsx
+// Migrating an old call site
+// BEFORE (would not have compiled against the published package anyway)
+// <ScInvoiceHistoryMobile invoiceNumber={id} date={d} amount={a} onClick={open} />
+
+// AFTER
+<div onClick={open} className="cursor-pointer">
+  <InvoiceHistoryMobile invoiceId={id} date={d} amount={a} />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+Nowhere. The surface it was drawn for — the "Invoice history" tab of CXO's mobile
+billing screen — is served by `InvoiceHistoryMobile`
+(`cxo-dashboard/src/app/components/mobile-billing-content.tsx:231`).
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+Never. Treat this folder as source to delete, or as the place to land the fix if the
+team decides the shipped row should regain `onClick` and a props spread (which are the
+two capabilities this copy has and the shipped one lacks).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A mobile invoice row | `InvoiceHistoryMobile` (`src/SC-InvoiceHistoryMobile/`) |
+| A mobile credit-usage row | `UsageHistoryMobile` (`src/SC-UsageHistoryMobile/`) |
+| Desktop invoice table | `ScBillingHistoryHeader` + `ScBillingHistoryTableList` |
+| A clickable mobile row with DS-provided semantics | `ScTableListMobile` (`onRowClick`) |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `InvoiceHistoryMobile` — the exported row, prop `invoiceId`, no `onClick` | This one is unexported and uses `invoiceNumber` |
+| `ScUsageHistoryMobile` — the *other* unexported duplicate, for usage rows | Same situation, different data |
+| `UsageHistoryMobile` — the exported usage row | Different data (red credits, four fields) |
+
+The library contains **two** of these unexported `Sc*`-prefixed duplicates —
+`ScInvoiceHistoryMobile` and `ScUsageHistoryMobile` — while the exported pair
+(`InvoiceHistoryMobile`, `UsageHistoryMobile`) are the only two components in the
+**mobile** family without the `Sc` prefix. (Other un-prefixed exports exist in the
+package — `CreditWarningBanner`, `StreamoidSidebar` — but none are mobile.) That
+inversion is the single easiest naming mistake to make in this family.
+
+---
+
+## 4. Why to use it
+
+There is no reason to. What the shipped twin gives you that this does not: it is
+actually in the bundle. What this gives you that the shipped twin does not: `onClick`
+and a props spread — capabilities you can reproduce today with a wrapper `div`.
+
+---
+
+## Gotchas
+
+**1. It is not importable.** `src/index.ts` exports
+`./SC-InvoiceHistoryMobile/InvoiceHistoryMobile` and nothing from
+`./SC-InvoiceHistory-Mobile/`. The two folder names differ only by a hyphen.
+
+**2. Its CSS is not in the shipped stylesheet.** Because nothing imports the module,
+esbuild never sees `ScInvoiceHistoryMobile.module.css`. Even if you deep-imported the
+`.tsx` from source, in a consumer repo the row would render **unstyled**.
+
+**3. `invoiceNumber` vs `invoiceId`.** Copying an old snippet across produces an
+undefined-prop that silently falls back to the demo default `"# INV-2800-2026"`.
+
+**4. `className` is concatenated unguarded** here (`+ " " + className`), so it emits a
+literal `undefined` class — one of the small differences from the shipped twin, which
+guards with `?? ""`.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+To be precise: it cannot have one — it is not exported, so no host *could* render it.
+It is not agent-runtime either; it is dead source. The surface it was drawn for uses
+the exported twin at
+`cxo-dashboard/src/app/components/mobile-billing-content.tsx:231`.
+
+---
+
+## Related
+
+- `InvoiceHistoryMobile` — **use this**; the shipped mobile invoice row.
+- `UsageHistoryMobile` — the shipped mobile usage row.
+- `ScUsageHistoryMobile` — the other unexported duplicate, same story.
+- `ScBillingHistoryHeader` / `ScBillingHistoryTableList` — the desktop table.