@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScBillingLogsTableHeader.md

@@ -0,0 +1,212 @@
+---
+component: ScBillingLogsTableHeader
+package: "@streamoid/ui"
+category: billing
+status: legacy
+renders: div
+tags: [credit-logs, usage-logs, table-header, column-headers, billing, credits, balance]
+related: [ScBillingLogsTableList, ScHeader, ScBillingHistoryHeader]
+do_not_confuse_with: [ScBillingHistoryHeader, ScHeader, ScTableHeader]
+---
+
+# ScBillingLogsTableHeader
+
+**The fixed 6-column header strip for the credit/usage-logs table:** `App` ·
+`Activity` · `Used by` · `Date` · `Credits used` · `Balance`. Six `ScHeader` cells
+on a neutral fill, width-matched to `ScBillingLogsTableList`. No content props at
+all — every label is baked in.
+
+> **Legacy.** Nothing renders this today. The live Billing → *Usage logs* tab in
+> `@streamoid/settings` **hand-rolls** its header from raw `ScHeader` cells because
+> this strip's column set no longer matches the API (see §3). It is not
+> `@deprecated` in source and still exports fine — but if you reach for it you are
+> almost certainly reproducing a layout the product has moved off.
+
+## TL;DR for agents
+
+- **Reach for it when:** you genuinely want the original six columns *including*
+  a per-row running `Balance`, and you are pairing it with
+  `ScBillingLogsTableList`.
+- **Don't reach for it when:** your log rows have no running balance, or the credits
+  figure needs a sign and two colours — that is the live shape, and it is built from
+  `ScHeader` cells directly (§3 has the recipe).
+- **Three things that will bite you:**
+  1. `className` is the **only** prop; the six labels are hardcoded English.
+  2. Its `Credits used` cell is `7.5rem` **left-aligned**; the live table renamed it
+     to `Credits` at `5rem` **right-aligned**. Mixing the two misaligns the column.
+  3. Not sticky, not rounded — your wrapper owns that.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScBillingLogsTableHeader, ScBillingLogsTableList } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScBillingLogsTableHeader />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `className` | `string` | – | Appended to the root class. **The only prop.** |
+
+The interface does **not** extend `HTMLAttributes`, and the destructured `...props`
+is never spread — `style`, `onClick`, `id` and `data-*` are both a type error and a
+no-op.
+
+### Fixed layout (must match your rows)
+
+| Cell | Label | Width |
+|---|---|---|
+| 1 | `App` | `flex: 1` |
+| 2 | `Activity` | `flex: 1` |
+| 3 | `Used by` | `7.5rem`, `flex-shrink: 0` |
+| 4 | `Date` | `7.5rem`, `flex-shrink: 0` |
+| 5 | `Credits used` | `7.5rem`, `flex-shrink: 0` |
+| 6 | `Balance` | `7.5rem`, `flex-shrink: 0` |
+
+Root: `padding: 0.75rem 1rem`, `gap: 1.5rem`, background
+`--alias-fill-neutral-neutral` — identical to `ScBillingHistoryHeader`'s root, so
+the two header strips are visually interchangeable even though their columns are not.
+
+### Recipes
+
+```tsx
+// Original 6-column shape, sticky over a scrolling rounded surface
+<div className="w-full relative" style={{ backgroundColor: "var(--alias-surface-base)", borderRadius: "var(--radius-3xl)", overflow: "clip" }}>
+  <ScBillingLogsTableHeader />
+  {logs.length === 0 && <EmptyRow>No usage logs found</EmptyRow>}
+  {logs.map((log) => (
+    <ScBillingLogsTableList
+      key={log._id}
+      app={log.service?.serviceGroupName || "—"}
+      activity={log.meta?.info || "Credit usage"}
+      usedBy={userMap[log.triggeredByUserId] || "System"}
+      date={formatDate(log.createdAt)}
+      creditsUsed={String(log.amount)}
+      balance={formatCredits(log.runningBalance)}
+    />
+  ))}
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **Billing → Usage logs tab.** That is the surface it was designed for.
+- **No live render site.** The only call in any repo is
+  `cxo-dashboard/src/app/components/billing-content.tsx:1670`, and nothing imports
+  `BillingContent` from that file — it is orphaned. The live page is
+  `packages/settings/src/billing-content.tsx` (`UsageLogsTable`), which builds its
+  own header.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You have a per-row **running balance** to show and want the six-column shape
+  exactly as designed.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Log rows without a running balance, and/or signed ±credits in green/red | `ScHeader` cells in your own flex row — this is what the live page does |
+| Invoice columns (`Invoice`, `Amount`, `Date`, `Action`) | `ScBillingHistoryHeader` + `ScBillingHistoryTableList` |
+| Renamed or localised labels, or a different column count | `ScHeader` — it is a two-prop primitive; the strip is 20 lines of flex |
+| A sortable header | `ScHeader` with `state="up"` / `"down"` and your own handler |
+
+The live replacement, verbatim in shape:
+
+```tsx
+// 5 columns: Balance dropped, "Credits used" → "Credits" (5rem, right-aligned)
+<div style={{ position: "sticky", top: 0, zIndex: 1,
+              background: "var(--alias-fill-neutral-neutral, #1a1a1a)",
+              padding: "var(--spacing-xl, 0.75rem) var(--spacing-3xl, 1rem)",
+              display: "flex", gap: "var(--spacing-6xl, 1.5rem)", alignItems: "center" }}>
+  <ScHeader text="App"      state="none" style={{ flex: 1, alignItems: "flex-start", gap: "0.25rem" }} />
+  <ScHeader text="Activity" state="none" style={{ flex: 1, alignItems: "flex-start", gap: "0.25rem" }} />
+  <ScHeader text="Used by"  state="none" style={{ flexShrink: 0, width: "7.5rem" }} />
+  <ScHeader text="Date"     state="none" style={{ flexShrink: 0, width: "7.5rem" }} />
+  <ScHeader text="Credits"  state="none" style={{ flexShrink: 0, width: "5rem", justifyContent: "flex-end" }} />
+</div>
+```
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScBillingHistoryHeader` — 4 columns (`Invoice`, `Amount`, `Date`, `Action`), still live | Same background, padding and gap; different labels and widths. Swapping them silently misaligns your rows. |
+| `ScHeader` — the single header **cell** (`text`, `state`, spreads props) | This is a fixed 6-cell strip |
+| `ScTableHeader` — the generic library table header | Not billing-specific, not width-matched to the logs rows |
+
+---
+
+## 4. Why to use it
+
+- **Width parity with `ScBillingLogsTableList`** is the only real value: the
+  `flex:1 / flex:1 / 7.5rem × 4` pattern and the `1.5rem` gap are duplicated in the
+  row component, so using both guarantees alignment.
+- **Token-driven header fill and typography** via `ScHeader`, so the strip survives
+  light mode.
+
+If you are not using `ScBillingLogsTableList`, this component buys you almost
+nothing over five lines of `ScHeader` cells — and costs you six hardcoded labels.
+
+---
+
+## Gotchas
+
+**1. Zero configuration.** No labels, no widths, no sort state, no `style`. Any
+change to the column set means dropping the component.
+
+**2. `state="none"` on every cell** — no sort arrows, ever, even though `ScHeader`
+supports them.
+
+**3. Extra props vanish.** `({ className, ...props })` never spreads the rest
+object; TypeScript rejects the prop, and an `as any` spread disappears silently.
+
+**4. Not sticky, not rounded, square corners.** Wrap it to pin it, and give the
+wrapper the radius + `overflow: clip`.
+
+**5. Missing `className` leaks `"undefined"` into the class list.**
+
+**6. No table semantics** — no `<thead>`/`<th>`/`role="columnheader"`, nothing tying
+these labels to the row cells below.
+
+**7. It looks identical to `ScBillingHistoryHeader` at a glance.** Same fill, same
+padding, same gap. In review, check the labels, not the shape.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/billing-content.tsx:1670
+<ScBillingLogsTableHeader />
+```
+
+⚠️ That call site is **orphaned** — nothing imports `BillingContent` from that
+file. There is no live render site for this component in any host app.
+
+---
+
+## Related
+
+- `ScBillingLogsTableList` — the row component this header exists for (same legacy
+  status, same reasons).
+- `ScHeader` — the cell primitive; the live usage-logs table is built from it.
+- `ScBillingHistoryHeader` / `ScBillingHistoryTableList` — the still-live
+  invoice-table pair.

package/dist/docs/ScBillingLogsTableList.md

@@ -0,0 +1,251 @@
+---
+component: ScBillingLogsTableList
+package: "@streamoid/ui"
+category: billing
+status: legacy
+renders: div
+tags: [credit-logs, usage-logs, table-row, credits-used, balance, billing, audit]
+related: [ScBillingLogsTableHeader, ScBillingHistoryTableList, ScHeader, ScTableList]
+do_not_confuse_with: [ScBillingHistoryTableList, ScTableList, ScBillingLogsTableHeader]
+---
+
+# ScBillingLogsTableList
+
+**One credit-consumption row in the usage-logs table.** Six cells: app, activity,
+who triggered it, date, credits used (hardcoded **error red**, semibold) and the
+running balance — width-matched to `ScBillingLogsTableHeader`, separated by a bottom
+hairline.
+
+> **Legacy.** Nothing renders this today. The live Billing → *Usage logs* tab in
+> `@streamoid/settings` hand-rolls its rows because this component cannot express
+> what the API returns: there is **no per-row running balance**, and credit
+> movements need a **sign and two colours** (`-50` red for a deduction, `+50` green
+> for a return/top-up). It is not `@deprecated` in source and still exports fine —
+> but reaching for it means reproducing a shape the product has moved off.
+
+## TL;DR for agents
+
+- **Reach for it when:** you have logs with a genuine per-row running balance and
+  every row is a deduction.
+- **Don't reach for it when:** rows can add credits back, or you have no balance
+  column — hand-roll the row (§3 has the live pattern) or extend the DS.
+- **Four things that will bite you:**
+  1. `creditsUsed` is **always red** and unsigned. A returned/added credit reads as
+     a charge.
+  2. `balance` is required by the layout but absent from the credits API — passing
+     the row `amount` again (as the orphaned CXO call site does) is misleading data.
+  3. All six values have demo defaults (`"Artifax"`, `"Rohan"`, `"84,902"`…), so a
+     misspelled prop shows plausible fake data.
+  4. Column widths are duplicated by hand in `ScBillingLogsTableHeader` — use both
+     or neither.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScBillingLogsTableHeader, ScBillingLogsTableList } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScBillingLogsTableList
+  app="Photogenix"
+  activity="Image generation"
+  usedBy="Rohan"
+  date="Nov 9th, 2025"
+  creditsUsed="50"
+  balance="84,902"
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `app` | `string` | `"Artifax"` | ⚠️ Real default. `flex: 1`, 14px, ellipsised. |
+| `activity` | `string` | `"Artifax Generation"` | ⚠️ Real default. `flex: 1`, 14px, ellipsised. |
+| `usedBy` | `string` | `"Rohan"` | ⚠️ Real default. `7.5rem`. Pass `"System"` for machine-triggered rows. |
+| `date` | `string` | `"Nov 9th, 2025"` | ⚠️ Real default. `7.5rem`. Pre-formatted by you. |
+| `creditsUsed` | `string` | `"50"` | ⚠️ Real default. `7.5rem`, 16px semibold, **`--alias-text-and-icons-error` (red), always**. |
+| `balance` | `string` | `"84,902"` | ⚠️ Real default. `7.5rem`, 16px semibold, primary text. |
+| `className` | `string` | – | Appended to the root class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root (`onClick`, `style`, `data-*` all work — unlike the header). |
+
+Root: `padding: 1.25rem 1rem`, `gap: 1.5rem`, bottom border
+`--alias-border-subtle`, no background of its own. Every cell is
+`nowrap + overflow:hidden + ellipsis`.
+
+### Recipes
+
+```tsx
+// The full legacy table, if you do have a running balance
+<div className="w-full relative" style={{ backgroundColor: "var(--alias-surface-base)", borderRadius: "var(--radius-3xl)", overflow: "clip" }}>
+  <ScBillingLogsTableHeader />
+  {logs.map((log) => (
+    <ScBillingLogsTableList
+      key={log._id}
+      app={log.service?.serviceGroupName || "—"}
+      activity={log.meta?.info || "Credit usage"}
+      usedBy={log.triggeredByUserId ? userMap[log.triggeredByUserId] || "Unknown" : "System"}
+      date={formatDate(log.createdAt)}
+      creditsUsed={String(log.amount)}
+      balance={formatCredits(log.runningBalance)}
+    />
+  ))}
+</div>
+
+// Rows are clickable if you need them to be (props are spread, unlike the header)
+<ScBillingLogsTableList app={app} activity={activity} onClick={() => openLog(log)} />
+```
+
+---
+
+## 2. Where to use it
+
+- **Billing → Usage logs tab**, stacked under `ScBillingLogsTableHeader`. That is
+  the surface it was designed for.
+- **No live render site.** The only call in any repo is
+  `cxo-dashboard/src/app/components/billing-content.tsx:1697`, inside a file whose
+  `BillingContent` export nothing imports. The live page is
+  `packages/settings/src/billing-content.tsx` (`UsageLogsTable`), which renders raw
+  divs instead.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Every row is a **deduction** (red, unsigned reads correctly), **and**
+- you have a real **running balance** per row, **and**
+- you are pairing it with `ScBillingLogsTableHeader`.
+
+If any of those is false, don't.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Credit movements that can be positive (returns, top-ups) | Hand-roll the row — see the live pattern below — or add a `tone`/`sign` prop to the DS first |
+| No per-row balance from the API | Hand-roll a 5-column row; `balance` has no "hide" option |
+| Invoice rows (`Invoice`, `Amount`, `Date`, `Download`) | `ScBillingHistoryTableList` + `ScBillingHistoryHeader` |
+| A generic dashboard list row | `ScTableList` |
+| Narrow screens | Nothing exists; the mobile billing surface has no usage-logs list |
+
+The live replacement, in shape:
+
+```tsx
+// 5 cells; credits signed and two-tone, 5rem, right-aligned
+const isPositive = log.type === "return" || log.type === "add";
+<div style={{ display: "flex", gap: "var(--spacing-6xl, 1.5rem)", alignItems: "center",
+              padding: "var(--spacing-5xl, 1.25rem) var(--spacing-3xl, 1rem)",
+              borderBottom: "0.0625rem solid var(--alias-border-subtle, #242424)" }}>
+  <div style={{ ...cell, flex: 1 }}>{app}</div>
+  <div style={{ ...cell, flex: 1 }}>{log.type === "return" ? "Returned Credits" : log.meta?.info || "Credit usage"}</div>
+  <div style={{ ...cell, width: "7.5rem" }}>{userName}</div>
+  <div style={{ ...cell, width: "7.5rem" }}>{formatDate(log.createdAt)}</div>
+  <div style={{ width: "5rem", textAlign: "right", fontWeight: 600,
+                color: isPositive ? "var(--alias-text---icons-success)" : "var(--alias-text---icons-error)" }}>
+    {`${isPositive ? "+" : "-"}${log.amount}`}
+  </div>
+</div>
+```
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScBillingHistoryTableList` — 4 columns, amount hardcoded **green**, has an `onRowClick` + download cell | This row is 6 columns with credits hardcoded **red** and no action cell |
+| `ScBillingLogsTableHeader` — the matching header strip (`className` only) | The header ignores extra props; this row spreads them |
+| `ScTableList` — the generic dashboard row | Not width-matched to the logs header |
+
+---
+
+## 4. Why to use it
+
+- **Width parity with `ScBillingLogsTableHeader`** (`flex:1 / flex:1 / 7.5rem × 4`,
+  `1.5rem` gap, `1rem` side padding) — the one thing you'd otherwise have to keep in
+  sync by hand.
+- **Every cell truncates**, so a long activity string or app name degrades to an
+  ellipsis instead of breaking the row.
+- **Emphasis via tokens** (`--alias-text-and-icons-error` for credits, primary for
+  balance), which hold contrast in light mode.
+
+That is the whole value. It is a layout-only row; all formatting, sign logic and
+colour semantics are yours — and two of those it actively gets in the way of.
+
+---
+
+## Gotchas
+
+**1. Credits are always red and never signed.** There is no `tone`, `variant`,
+`sign` or `type` prop. A returned credit renders exactly like a charge.
+
+```tsx
+// MISLEADING — a +50 refund painted red, unsigned
+<ScBillingLogsTableList activity="Returned Credits" creditsUsed="50" />
+
+// Only honest option today: hand-roll the row (see §3)
+```
+
+**2. `balance` cannot be hidden.** Omit it and you get the demo default
+`"84,902"`; pass `""` and the column is an empty 7.5rem gap. There is no 5-column
+mode.
+
+**3. Demo defaults hide typos.** Misspell `usedBy` and the row shows `"Rohan"`. If a
+usage log looks suspiciously like sample data, check your prop names.
+
+**4. Header/row alignment is by convention.** If you swap in a custom header you
+must reproduce `gap: 1.5rem`, `padding: … 1rem` and the exact widths, or the columns
+drift.
+
+**5. The bottom border is unconditional** — the last row keeps its hairline; trim it
+from the wrapper if your container already has an edge.
+
+**6. No background.** The row is transparent; the wrapper owns the surface colour,
+which matters if you make the header sticky (it needs an opaque background).
+
+**7. Missing `className` leaks `"undefined"` into the class list.**
+
+**8. Trailing spaces in the DOM.** All six values render as `{value}` plus a literal
+space; trim before exact-match text assertions.
+
+**9. No row semantics.** Divs only — no `role="row"`/`"cell"`, no focus handling. If
+you attach `onClick`, add your own keyboard affordance.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/billing-content.tsx:1697
+<ScBillingLogsTableList
+  key={log._id}
+  app={app}
+  activity={activity}
+  usedBy={userName}
+  date={formatDate(log.createdAt)}
+  creditsUsed={log.amount.toString()}
+  balance={formatCredits(runningBalance)}   // note: runningBalance = log.amount here
+/>
+```
+
+⚠️ That call site is **orphaned** — nothing imports `BillingContent` from that file
+— and it illustrates the balance problem: `runningBalance` is just `log.amount`
+again, because the API has no per-row balance. There is no live render site for this
+component in any host app.
+
+---
+
+## Related
+
+- `ScBillingLogsTableHeader` — the matching header strip (same legacy status).
+- `ScBillingHistoryTableList` / `ScBillingHistoryHeader` — the still-live invoice
+  pair.
+- `ScHeader` — what the live usage-logs table uses for its header cells.
+- `ScCreditsUsageCard` — the aggregate credits meter on the same billing page.