@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScBeacon.md

@@ -0,0 +1,244 @@
+---
+component: ScBeacon
+package: "@streamoid/ui"
+category: overlays
+status: stable
+renders: span[aria-hidden="true"] wrapping an inline 20×20 SVG
+tags: [beacon, dot, status-dot, indicator, halo, tone, success, warning, error, neutral]
+related: [ScBadges, ScStoreCard, ScCatalogixStoreTableList, ScRole]
+do_not_confuse_with: [ScBadges, ScProgressBar]
+---
+
+# ScBeacon
+
+**A two-ring status dot.** A 20×20 `<span>` holding an inline SVG: a solid 4px core
+plus a 10px halo of the same colour at 24% opacity, both `currentColor`, tinted by
+one of four `tone`s. It is decoration — `aria-hidden` by default.
+
+## TL;DR for agents
+
+- **Reach for it when:** a row or card needs a colour-coded state marker that sits
+  beside a text label ("● Live", "● Needs attention").
+- **Don't reach for it when:** the marker must carry the words itself
+  (→ `ScBadges`), it's a quantity (→ `ScProgressBar`), or you wanted an animated
+  "new!" nudge — **it does not animate** (see Gotcha 1).
+- **Three things that will bite you:**
+  1. Despite the name, **there is no pulse and no animation anywhere** in
+     `ScBeacon.module.css`. It's a static dot with a halo.
+  2. `tone` defaults to `"neutral"` ⚠️ — a grey status dot that says nothing.
+  3. `aria-hidden="true"` is baked on. Screen readers get nothing, so it must
+     always sit next to real text.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScBeacon } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScBeacon tone="success" />
+```
+
+Practically always paired with a label:
+
+```tsx
+<span style={{ display: "inline-flex", alignItems: "center", gap: 8 }}>
+  <ScBeacon tone="error" />
+  Needs attention
+</span>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `tone` | `"success"` \| `"warning"` \| `"error"` \| `"neutral"` | `"neutral"` | ⚠️ Real default. Sets `color:` on the span; the SVG paints with `currentColor`. **There is no `info`/blue tone** (unlike `ScBadges`). |
+| `className` | `string` | – | Appended only when truthy (this component gets the concatenation right). |
+| `...props` | `HTMLAttributes<HTMLSpanElement>` | – | Spread onto the `<span>` **after** `aria-hidden`, so `style`, `title`, `aria-hidden={false}` + `aria-label`, `data-*` and `onClick` all work. |
+
+`ScBeaconTone` is exported as a standalone type and reused by `ScStoreCard`
+(`tone`) and `ScCatalogixStoreTableList` (`statusTone`).
+
+### Tone → token
+
+| `tone` | Colour |
+|---|---|
+| `success` | `--alias-text-and-icons-success` |
+| `warning` | `--alias-text-and-icons-warning` |
+| `error` | `--alias-text-and-icons-error` |
+| `neutral` | `--alias-text-and-icons-muted` |
+
+### Recipes
+
+```tsx
+// Table status cell — dot + text, one accessible label
+<td>
+  <span style={{ display: "inline-flex", alignItems: "center", gap: 8 }}>
+    <ScBeacon tone={STATUS_TONE[row.status]} />
+    <span>{STATUS_LABEL[row.status]}</span>
+  </span>
+</td>
+
+// Smaller dot — the SVG is width/height 100%, so resizing the span scales it
+<ScBeacon tone="success" style={{ width: 12, height: 12 }} />
+
+// Expose it to assistive tech when there is genuinely no adjacent text
+<ScBeacon tone="error" aria-hidden={false} role="img" aria-label="Feed sync failed" />
+
+// Share the tone type with your own status map
+import type { ScBeaconTone } from "@streamoid/ui";
+const STATUS_TONE: Record<FeedStatus, ScBeaconTone> = {
+  live: "success", syncing: "warning", failed: "error", draft: "neutral",
+};
+```
+
+---
+
+## 2. Where to use it
+
+- **Inside `ScStoreCard`** — the card's footer renders `<ScBeacon tone={tone} />`
+  beside the product count and creation date. That is its main job today.
+- **Table status columns** — `ScCatalogixStoreTableList` takes a `statusTone` of the
+  same `ScBeaconTone` type, though it paints its own dot via a
+  `STATUS_TONE_CLASS` map rather than mounting this component.
+- **Any list where a full `ScBadges` chip is too heavy** — dense tables where one
+  coloured dot plus the plain status word reads better than five coloured boxes.
+
+No host app renders it directly; it reaches the screen through `ScStoreCard`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The state is **already named in adjacent text** and you only need the colour cue.
+- The row is **dense** and a bordered/filled chip would be visual noise.
+- You are building a component that should look like `ScStoreCard`'s footer.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The marker must carry the label itself ("Revoked", "Live") | `ScBadges` |
+| Admin / Member role marker | `ScRole` / `ScRoleMobile` |
+| An `info`/blue state | `ScBadges variant="info"` — this component has no blue tone |
+| A numeric count on an icon (notification badge) | no DS component; build it app-local |
+| Progress or a quantity | `ScProgressBar` |
+| An animated onboarding "new here!" nudge | no DS component — `ScGuide` is the guided-tour callout; this dot does not animate |
+| An interactive filter chip | `ScSelectionPill` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScBadges` — text chip, 5 variants (incl. `info`), 2 skins, no spread | `ScBeacon` — dot only, 4 tones, full HTML spread |
+| `ScProgressBar` — a meter | Not a status marker |
+| An animated attention beacon | The name suggests it; the CSS contains no `@keyframes` |
+
+---
+
+## 4. Why to use it
+
+- **The halo is the point.** A 24%-opacity ring around a solid core makes a small
+  dot legible against both dark and light surfaces without a border — a plain
+  `border-radius: 50%` div disappears on a low-contrast row.
+- **`currentColor` throughout.** Both circles paint from `currentColor`, so the tone
+  is set once on the span and a `color` in your own `className` overrides the whole
+  mark. No fills to keep in sync.
+- **Four semantic tokens, not four hex values.** The tones read the same
+  `--alias-text-and-icons-{success,warning,error,muted}` used by `ScBadges`,
+  `ScMenuOptions` and `ScMappingCard`'s status icons, so a "warning" is one colour
+  product-wide.
+- **`ScBeaconTone` is the shared status vocabulary.** Exporting the type lets store
+  cards, store tables and your own status maps agree on four states instead of each
+  inventing five.
+- **It cannot break a layout.** `inline-flex`, `flex-shrink: 0`, fixed 20×20 — safe
+  in a table cell or a truncating flex row.
+
+---
+
+## Gotchas
+
+**1. It does not pulse.** `ScBeacon.module.css` is 22 lines: a size, a
+`flex-shrink`, and four colour classes. No `@keyframes`, no `animation`, no
+`transition`. If you need the pulsing onboarding nudge the catalog describes, you
+must add the animation yourself via `className`.
+
+**2. `tone` defaults to `"neutral"`.** Forget it and you get a muted grey dot — a
+status indicator communicating no status.
+
+```tsx
+// WRONG — grey dot regardless of state
+<ScBeacon />
+
+// RIGHT
+<ScBeacon tone={row.failed ? "error" : "success"} />
+```
+
+**3. `aria-hidden="true"` is hardcoded.** By design — it's decoration. But it means
+a dot-only status column is invisible to screen readers. Either keep a text label
+beside it, or override: `aria-hidden={false} role="img" aria-label="…"` (the spread
+comes after the attribute, so your override wins).
+
+**4. No `size` prop.** Fixed `1.25rem` (20px). It *does* scale if you set both
+`width` and `height` (the SVG is `100%`/`100%`) — but you must set both, via
+`style` or `className`. Setting only one squashes it.
+
+**5. A `color` you set on the span silently beats `tone`.** The tone class only sets
+`color` on the span, and the SVG paints from `currentColor` — so
+`style={{ color: … }}` (inline, always wins) or a same-specificity `.yourClass
+{ color: … }` that happens to come later in the stylesheet overrides the tone
+entirely. An *inherited* `color` from an ancestor does **not** override it: the tone
+class targets the element directly and beats inheritance. Pick one mechanism.
+
+**6. Four tones only — no `info`.** `ScBadges` has five variants; `ScBeacon` has
+four. If your status map has a blue "info" state you must collapse it to `neutral`
+or use a badge.
+
+**7. It's a `<span>`, so it inherits `font-size`-driven line boxes.** In a text run
+it sits on the baseline and can look vertically off; wrap it in an
+`inline-flex; align-items: center` container with the label rather than relying on
+inline layout.
+
+**8. `onClick` works (via the spread) but there is no cursor, role or focus.** If
+the dot is a control, wrap it in a real button — don't just add a handler to an
+`aria-hidden` span.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+Concretely: it is composed inside the DS, not called from the dashboards —
+
+```tsx
+// npm-components  packages/ui/src/SC-StoreCard/ScStoreCard.tsx:33
+<div className={styles.footer}>
+  <ScBeacon tone={tone} />
+  <span className={styles.products}>{noOfProducts}</span>
+  <span className={styles.date}>{dateCreated}</span>
+</div>
+```
+
+Where it most likely belongs next: the **Catalogix stores table**
+(`ScCatalogixStoreTableList` already accepts a `statusTone: ScBeaconTone` but draws
+its own dot through `STATUS_TONE_CLASS` — mounting `ScBeacon` there would remove the
+duplicate), and any future feed/job status list in Catalogix or Photogenix.
+
+---
+
+## Related
+
+- `ScBadges` — the text-carrying sibling; use it when the state must be named in the chip.
+- `ScStoreCard` — the DS parent that renders a beacon today.
+- `ScCatalogixStoreTableList` — reuses `ScBeaconTone` for its `statusTone` prop.
+- `ScRole` — the dedicated Admin/Member marker.

package/dist/docs/ScBillingHistoryHeader.md

@@ -0,0 +1,210 @@
+---
+component: ScBillingHistoryHeader
+package: "@streamoid/ui"
+category: billing
+status: stable
+renders: div
+tags: [invoice, billing-history, table-header, column-headers, invoices, header-row]
+related: [ScBillingHistoryTableList, ScHeader, ScBillingLogsTableHeader, ScTableHeader]
+do_not_confuse_with: [ScBillingLogsTableHeader, ScTableHeader, ScHeader, ScMobileTopNav]
+used_by: [cxo]
+---
+
+# ScBillingHistoryHeader
+
+**The fixed column-header strip for the invoice-history table.** Four `ScHeader`
+cells — `Invoice` · `Amount` · `Date` · `Action` — on a neutral fill, at the exact
+widths its row sibling `ScBillingHistoryTableList` expects. It takes **no content
+props at all**: the labels are baked in.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are rendering the Billing → *Invoice history* table
+  and are about to stack `ScBillingHistoryTableList` rows under it.
+- **Don't reach for it when:** your columns differ in any way (→ compose `ScHeader`
+  cells yourself), or you need the credit-logs header (→ `ScBillingLogsTableHeader`).
+- **Three things that will bite you:**
+  1. `className` is the **only** prop. The four labels are hardcoded English and
+     cannot be renamed, reordered, removed or extended.
+  2. It is **not sticky**. Wrap it yourself if rows scroll under it.
+  3. `state="none"` is hardcoded on every cell, so there are **no sort arrows** even
+     though `ScHeader` supports `"up"`/`"down"`.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScBillingHistoryHeader, ScBillingHistoryTableList } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScBillingHistoryHeader />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `className` | `string` | – | Appended to the root class. **The only prop.** |
+
+The interface does **not** extend `HTMLAttributes`, and although the component
+destructures `...props`, it never spreads them — so `style`, `onClick`, `id` and
+`data-*` are both a type error *and* a no-op.
+
+### Fixed layout (must match your rows)
+
+| Cell | Label | Width |
+|---|---|---|
+| 1 | `Invoice` | `flex: 1` (`align-items: flex-start`) |
+| 2 | `Amount` | `7.5rem`, `flex-shrink: 0` |
+| 3 | `Date` | `7.5rem`, `flex-shrink: 0` |
+| 4 | `Action` | `10rem`, `flex-shrink: 0` |
+
+Root: `padding: 0.75rem 1rem`, `gap: 1.5rem`, background
+`--alias-fill-neutral-neutral`. `ScBillingHistoryTableList` uses the same gap and
+horizontal padding (with `1.25rem` vertical), which is why the columns line up.
+
+### Recipes
+
+```tsx
+// Sticky header over a scrolling, rounded list (the real CXO/settings pattern)
+<div
+  className="flex-1 min-h-0 w-full relative"
+  style={{
+    backgroundColor: "var(--alias-surface-base)",
+    borderRadius: "var(--radius-3xl)",
+    border: "1px solid var(--alias-border-subtle)",
+    overflowY: "auto",
+  }}
+>
+  <div style={{ position: "sticky", top: 0, zIndex: 1, backgroundColor: "var(--alias-surface-base)" }}>
+    <ScBillingHistoryHeader />
+  </div>
+
+  {invoices.length === 0 && <EmptyRow>No invoices found</EmptyRow>}
+
+  {invoices.map((inv) => (
+    <ScBillingHistoryTableList key={inv._id} invoiceNumber={inv.number} amount={inv.total} date={inv.date} />
+  ))}
+</div>
+```
+
+```tsx
+// Need different columns? Don't fork this component — compose ScHeader.
+<div style={{ display: "flex", gap: "var(--spacing-6xl)", padding: "var(--spacing-xl) var(--spacing-3xl)",
+              background: "var(--alias-fill-neutral-neutral)" }}>
+  <ScHeader text="App" state="none" style={{ flex: 1 }} />
+  <ScHeader text="Credits" state="none" style={{ flexShrink: 0, width: "5rem", justifyContent: "flex-end" }} />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **Billing → Invoice history tab**, immediately above the invoice rows. That is
+  its only surface.
+- Rendered from the shared **`@streamoid/settings`** billing page
+  (`packages/settings/src/billing-content.tsx`, `InvoiceHistoryTable`), which
+  **CXO** mounts through `settings-content.tsx`. The sibling tab ("Usage logs") in
+  that same file **hand-rolls** its header with raw `ScHeader` cells rather than
+  using `ScBillingLogsTableHeader` — see that component's README for why.
+- No mobile twin, and none is needed: the narrow-screen invoice list uses stacked
+  `InvoiceHistoryMobile` cards that carry their own labels. That path is currently
+  wired only in CXO's `src/app/components/mobile-billing-content.tsx:231`, reached
+  from CXO's orphaned local `billing-content.tsx`, so mobile billing is effectively
+  unwired today.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Your columns are exactly `Invoice / Amount / Date / Action`, i.e. you are
+  rendering `ScBillingHistoryTableList` rows.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Credit/usage logs columns (`App`, `Activity`, `Used by`, `Date`, `Credits`) | `ScBillingLogsTableHeader` — but read its README first; production hand-rolls that one |
+| Any other column set, or renamed/localised labels | `ScHeader` cells in your own flex row (see the second recipe) |
+| A sortable header | `ScHeader` with `state="up"` / `"down"` and your own click handling |
+| A page title bar, not a table header | `ScHeader` alone, or your page-header composition |
+| Mobile invoice list | `InvoiceHistoryMobile` (self-labelling cards, no header row) |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScHeader` — the single header **cell** primitive (`text`, `state`, spreads props) | This is a fixed 4-cell **strip** |
+| `ScBillingLogsTableHeader` — the 6-column credit-logs strip | Same shape, different labels and widths; the two are not interchangeable |
+| `ScTableHeader` — the generic list/table header used elsewhere in the library | Not billing-specific and not width-matched to the invoice rows |
+| `ScMobileTopNav` — a mobile screen's top bar | Nothing to do with tables |
+
+---
+
+## 4. Why to use it
+
+- **The widths are the contract.** The `7.5rem / 7.5rem / 10rem` trio and the
+  `1.5rem` gap are duplicated in `ScBillingHistoryTableList`; using both components
+  guarantees alignment, whereas a hand-rolled header drifts the moment either side
+  changes.
+- **Header typography and fill come from tokens** via `ScHeader` and
+  `--alias-fill-neutral-neutral`, so the strip stays legible in light mode.
+- **Zero API surface means zero drift** — every invoice table in the product shows
+  the same four labels in the same order.
+
+---
+
+## Gotchas
+
+**1. There is nothing to configure.** No labels, no widths, no sort state, no
+`style`. If you need any of that, compose `ScHeader` yourself — copying this
+component's flex values is a two-line job.
+
+**2. Not sticky, not rounded.** It renders a plain flex row with a square neutral
+background. The rounded card, the sticky positioning and the top-corner clipping all
+belong to your wrapper.
+
+**3. Extra props are silently dropped.** `({ className, ...props })` destructures a
+rest object that is never used. TypeScript will reject the prop, but if you spread
+a wider object through `as any`, it disappears with no warning.
+
+**4. Missing `className` leaks `"undefined"` into the class list** (root is
+`styles.scBillingHistoryHeader + " " + className`).
+
+**5. No table semantics.** No `<table>`, `<thead>`, `<th>` or `role="columnheader"`
+— screen readers see four unrelated strings, and nothing associates them with the
+row cells beneath.
+
+**6. Alignment is by convention, not by grid.** If you render a custom row under
+this header, you must repeat `gap: 1.5rem`, `padding: … 1rem` and the three fixed
+widths, or the columns will not line up.
+
+---
+
+## In the wild
+
+```tsx
+// npm-components  packages/settings/src/billing-content.tsx:1117
+<div style={{ position: "sticky", top: 0, zIndex: 1, backgroundColor: "var(--alias-surface-base)" }}>
+  <ScBillingHistoryHeader />
+</div>
+```
+
+---
+
+## Related
+
+- `ScBillingHistoryTableList` — the row component this header exists for.
+- `ScHeader` — the cell primitive; use it directly for any other column set.
+- `ScBillingLogsTableHeader` — the credit-logs sibling strip.
+- `InvoiceHistoryMobile` — the stacked mobile alternative to this whole table.

package/dist/docs/ScBillingHistoryTableList.md

@@ -0,0 +1,243 @@
+---
+component: ScBillingHistoryTableList
+package: "@streamoid/ui"
+category: billing
+status: stable
+renders: div
+tags: [invoice, invoice-row, billing-history, table-row, download-invoice, receipt, billing]
+related: [ScBillingHistoryHeader, InvoiceHistoryMobile, ScPairtext, ScBillingLogsTableList, ScTableList]
+do_not_confuse_with: [ScBillingLogsTableList, ScTableList, InvoiceHistoryMobile]
+used_by: [cxo]
+---
+
+# ScBillingHistoryTableList
+
+**One invoice row in the billing-history table.** Invoice number (flexible width,
+ellipsised), amount in success green, date, and a "Download invoice" `ScPairtext`
+with a download icon — width-matched to `ScBillingHistoryHeader` and separated by a
+bottom hairline.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are listing invoices under a `ScBillingHistoryHeader`.
+- **Don't reach for it when:** the row is a credit/usage log entry
+  (→ `ScBillingLogsTableList`), a generic data row (→ `ScTableList`), or the mobile
+  stacked invoice card (→ `InvoiceHistoryMobile`).
+- **Four things that will bite you:**
+  1. `onRowClick` is wired to the root's `onClick` **before** `...props` is spread,
+     so passing your own `onClick` **replaces** `onRowClick` entirely.
+  2. The download cell has **no handler of its own**. Either treat the whole row as
+     the download target, or hit-test the event against the CSS-module class (what
+     production does).
+  3. `amount` is **always success green**. Refunds, failures and zero amounts all
+     render as if they were paid.
+  4. Every value has demo-data default (`"# INV-2800-2026"`, `"₹320.89"`,
+     `"Nov 9th, 2025"`), so a wrong prop name shows plausible fake data instead of
+     failing.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScBillingHistoryHeader, ScBillingHistoryTableList } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScBillingHistoryTableList
+  invoiceNumber="# INV-3F92A0C1"
+  amount="₹4,999.00"
+  date="Nov 9th, 2025"
+  onRowClick={() => downloadInvoice(inv)}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `invoiceNumber` | `string` | `"# INV-2800-2026"` | ⚠️ Real default. `flex: 1`, ellipsised. You supply the `#` prefix. |
+| `amount` | `string` | `"₹320.89"` | ⚠️ Real default. Fixed `7.5rem`. Colour is hardcoded success green. |
+| `date` | `string` | `"Nov 9th, 2025"` | ⚠️ Real default. Fixed `7.5rem`. Pre-formatted by you. |
+| `downloadLabel` | `string` | `"Download invoice"` | ⚠️ Real default. Label of the icon+text action cell (`10rem`). |
+| `onRowClick` | `() => void` | – | Bound to the root `onClick`. **Overridden by an `onClick` you pass** — see Gotcha 1. |
+| `className` | `string` | – | Appended to the root class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root **after** `onClick={onRowClick}`. |
+
+### Layout (matches `ScBillingHistoryHeader`)
+
+| Cell | Width | Styling |
+|---|---|---|
+| `invoiceNumber` | `flex: 1` | primary text, 14px, ellipsis |
+| `amount` | `7.5rem` | **`--alias-text-and-icons-success`**, 16px semibold, ellipsis |
+| `date` | `7.5rem` | primary text, 14px, ellipsis |
+| download `ScPairtext` | `10rem` | `cursor: pointer`, download icon + `downloadLabel` |
+
+Root: `padding: 1.25rem 1rem`, `gap: 1.5rem`, bottom border
+`--alias-border-subtle`. No background of its own — it inherits the wrapper's.
+
+### Recipes
+
+```tsx
+// Whole row is the download target (simplest correct wiring)
+{invoices.map((inv) => (
+  <ScBillingHistoryTableList
+    key={inv._id}
+    invoiceNumber={`# ${inv.transactionId.slice(0, 16).toUpperCase()}`}
+    amount={`${currencySymbol}${(inv.amount / 100).toFixed(2)}`}
+    date={formatDate(inv.createdAt)}
+    downloadLabel="Download invoice"
+    onRowClick={() => handleDownload(inv)}
+  />
+))}
+
+// Only the "Download invoice" cell should act (the production pattern):
+// use onClick + hit-test the pairtext by its emitted CSS-module class.
+const handleRowClick = (e: React.MouseEvent<HTMLDivElement>, inv: Invoice) => {
+  const hit = (e.target as HTMLElement).closest(
+    `.${CSS.escape("ScBillingHistoryTableList_scPairtextInstance")}`,
+  );
+  if (hit) handleDownload(inv);
+};
+
+<ScBillingHistoryTableList
+  invoiceNumber={n}
+  amount={a}
+  date={d}
+  onClick={(e: React.MouseEvent<HTMLDivElement>) => handleRowClick(e, inv)}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **Billing → Invoice history tab**, stacked directly under
+  `ScBillingHistoryHeader` inside a rounded, scrolling surface. Its only surface.
+- Rendered from the shared **`@streamoid/settings`** billing page
+  (`packages/settings/src/billing-content.tsx`, `InvoiceHistoryTable`), which
+  **CXO** mounts through `settings-content.tsx`.
+- The mobile equivalent is `InvoiceHistoryMobile` (stacked card, self-labelling) —
+  currently only wired from CXO's orphaned local mobile billing file.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The row is an **invoice** with exactly the `Invoice / Amount / Date / Download`
+  shape, and you are pairing it with `ScBillingHistoryHeader`.
+- The amount is a **successful charge** (the green is not negotiable).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Credit/usage log entry (App, Activity, Used by, Date, Credits) | `ScBillingLogsTableList` — but read its README; production hand-rolls that table |
+| A generic data row with your own columns | `ScTableList` (or raw divs mirroring the header's widths) |
+| Narrow-screen invoice list | `InvoiceHistoryMobile` |
+| A refunded / failed / pending amount that must not read as green | Hand-roll the row — this component cannot express a non-success amount |
+| A real download link (right-click → Save as, middle-click, keyboard) | Your own `<a href download>` — this row is a `div` with no link semantics |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScBillingLogsTableList` — 6 columns (`app`, `activity`, `usedBy`, `date`, `creditsUsed`, `balance`), credits hardcoded **red** | This one is 4 columns with the amount hardcoded **green** |
+| `InvoiceHistoryMobile` — exported, props `invoiceId` / `date` / `amount` | Not a responsive mode of this row |
+| `ScInvoiceHistoryMobile` (folder `SC-InvoiceHistory-Mobile`) | ⚠️ **Not exported from the package index** — importing it from `@streamoid/ui` fails. Use `InvoiceHistoryMobile`. |
+| `ScTableList` — the generic list row used across the dashboards | Not width-matched to the invoice header |
+
+---
+
+## 4. Why to use it
+
+- **Column widths are the contract.** `flex:1 / 7.5rem / 7.5rem / 10rem` plus a
+  `1.5rem` gap and `1rem` side padding mirror `ScBillingHistoryHeader` exactly, so
+  the header and the rows can't drift apart.
+- **Every cell already truncates.** All three text cells are
+  `nowrap + overflow:hidden + ellipsis`, so a long transaction id degrades instead
+  of breaking the row.
+- **The download affordance is a composed `ScPairtext`**, so the icon size, gap and
+  label typography match every other icon+text pair in the product.
+- **Amount emphasis is tokenised** (`--alias-text-and-icons-success`), so it holds
+  contrast in light mode where a hardcoded `#00b96b` would not.
+
+---
+
+## Gotchas
+
+**1. `onClick` beats `onRowClick`.** The JSX is
+`onClick={onRowClick} {...props}`, so a spread `onClick` overwrites it. Never pass
+both.
+
+```tsx
+// WRONG — onRowClick never fires
+<ScBillingHistoryTableList onRowClick={download} onClick={logClick} />
+
+// RIGHT — pick one; use onClick when you need the event object
+<ScBillingHistoryTableList onClick={(e) => { logClick(); download(); }} />
+```
+
+**2. The download cell has no handler.** `ScPairtext` only gets `cursor: pointer`.
+Clicking it bubbles to the row. To make *only* that cell act, hit-test
+`event.target.closest(".ScBillingHistoryTableList_scPairtextInstance")` — that
+class name is part of the emitted CSS-module output and is what the live billing
+page relies on. It is effectively a private API: if the module class prefix ever
+changes, your hit-test silently stops matching.
+
+**3. Green amounts, always.** `.amount` is `--alias-text-and-icons-success`. There
+is no `variant`/`status` prop, so credits notes and failed charges look paid.
+
+**4. Demo defaults hide typos.** Misspell `invoiceNumber` and the row cheerfully
+shows `"# INV-2800-2026"` / `"₹320.89"` / `"Nov 9th, 2025"`. Check prop names
+against the table when a row looks oddly plausible.
+
+**5. Not a link, not focusable.** It is a `div` with an `onClick` — no `role`, no
+`tabIndex`, no keyboard activation, no browser download semantics. Keyboard users
+cannot download an invoice from this row.
+
+**6. The bottom border is unconditional.** The last row keeps its hairline; if your
+container has its own bottom edge you get a double line. Trim it from the wrapper.
+
+**7. No background.** The row is transparent, so the wrapper owns the surface
+colour — important when you also make the header sticky (the header needs an opaque
+background or rows show through).
+
+**8. Missing `className` leaks `"undefined"` into the class list.**
+
+**9. Trailing spaces in the DOM.** `invoiceNumber`, `amount` and `date` each render
+as `{value}` plus a literal space; trim before exact-match text assertions.
+
+---
+
+## In the wild
+
+```tsx
+// npm-components  packages/settings/src/billing-content.tsx:1138
+<ScBillingHistoryTableList
+  key={inv._id}
+  invoiceNumber={inv.transactionId ? `# ${inv.transactionId.slice(0, 16).toUpperCase()}` : "# INV-UNKNOWN"}
+  amount={inv.amountPaid != null
+    ? `${currencySymbol}${inv.amountPaid.toFixed(2)}`
+    : `${currencySymbol}${(inv.amount / 100).toFixed(2)}`}
+  date={formatDate(inv.createdAt)}
+  downloadLabel="Download invoice"
+  onClick={(e: React.MouseEvent<HTMLDivElement>) => handleRowClick(e, inv)}
+/>
+```
+
+---
+
+## Related
+
+- `ScBillingHistoryHeader` — the header strip whose widths this row mirrors.
+- `InvoiceHistoryMobile` — the stacked mobile card for the same data.
+- `ScBillingLogsTableList` — the credit-logs row sibling.
+- `ScPairtext` — the icon+label pair used for the download cell.