@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/CreditWarningBanner.md

@@ -0,0 +1,305 @@
+---
+component: CreditWarningBanner
+package: "@streamoid/ui"
+category: sidebar
+status: stable
+renders: div | button (collapsed)
+tags: [credits, low-credits, warning, banner, danger, buy-credits, sidebar-footer, dismiss]
+related: [StreamoidSidebar, ScArtifaxSidebar, ScCreditsUsageCard, ScPlanCard, ScBadges]
+do_not_confuse_with: [ScCreditsUsageCard, ScGuide, ScBadges, ScInfoPopup]
+used_by: [cxo, photogenix, artifax]
+required_props: [availableCredits, remainingPct, level, onBuyCredits]
+---
+
+# CreditWarningBanner
+
+**The low-credits alert that sits in a sidebar's pre-footer slot.** Expanded: a tinted
+card with a warning triangle, "Low Credits", a dismiss ✕, and the sentence
+"Only *N* credits (*P*%) remaining. **Buy credits** to avoid interruptions."
+Collapsed: a 40×40 tinted square holding just the triangle.
+
+⚠️ **The export is `CreditWarningBanner`, not `ScCreditWarningBanner`.** It is the one
+component in this family without the `Sc` prefix — the component catalog names it
+wrongly. `import { ScCreditWarningBanner }` is `undefined`.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need the "you're nearly out of credits" nudge in a
+  sidebar rail, in either expanded or collapsed form.
+- **Don't reach for it when:** you want the credits **meter** on a billing page
+  (→ `ScCreditsUsageCard`), a generic callout (→ `ScGuide`), or a status chip
+  (→ `ScBadges`).
+- **Four things that will bite you:**
+  1. The export name has **no `Sc` prefix**.
+  2. It owns its own dismiss state: ✕ makes it return `null` **forever**, with no
+     callback and no way to reopen it except remounting with a new `key`.
+  3. `remainingPct` is printed **raw** — no rounding, no clamping. Pass
+     `Math.round(...)` or you ship `(33.33333333333333%)`.
+  4. `expanded` defaults to **`true`**; in a collapsed rail you must pass
+     `expanded={false}` explicitly.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { CreditWarningBanner } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<CreditWarningBanner
+  availableCredits={1200}
+  remainingPct={4}
+  level="danger"
+  onBuyCredits={() => navigate("/settings/billing")}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `availableCredits` | `number` | — | **Required.** Rendered via `.toLocaleString()` — thousands separators come from the browser locale. |
+| `remainingPct` | `number` | — | **Required.** Printed verbatim inside `(…%)`. **Round it yourself.** |
+| `level` | `"warning" \| "danger"` | — | **Required — there is no default.** `warning` = orange tint + `--primitives-warning-400`; `danger` = red tint + `--primitives-error-400`. (Both sidebar wrappers default it to `"danger"`; calling this component directly does not.) |
+| `onBuyCredits` | `() => void` | — | **Required.** The underlined "Buy credits" link, and the collapsed square's fallback click. |
+| `expanded` | `boolean` | `true` | ⚠️ Real default. `false` → the 40×40 icon-only square. |
+| `onCollapsedClick` | `() => void` | `onBuyCredits` | ⚠️ Collapsed square click. Omit it and clicking the square **navigates to billing**; CXO passes the sidebar's `onToggle` so it expands the rail instead. |
+
+### What renders in each state
+
+| Region | `expanded` (default) | `expanded={false}` |
+|---|---|---|
+| Root | `div`, `padding: 16px 8px`, full width | **`button`**, 40×40, `aria-label="Show low credits warning"` |
+| Card | tinted bg + 0.5px tinted border, 12px radius, 12px padding | same tint, `radius-xl` |
+| Header | triangle icon + "Low Credits" (12px/600) + ✕ | — |
+| Body | "Only *N* credits (*P*%) remaining. Buy credits to avoid interruptions." | — |
+| Icon | 16×16 triangle, `strokeWidth` 1.25 | same 16×16 triangle |
+| Dismiss | ✕ button, `aria-label="Dismiss low credits warning"` | **none — cannot be dismissed** |
+
+### Recipes
+
+```tsx
+// The standard host wiring: StreamoidSidebar's pre-footer, both rails
+<StreamoidSidebar
+  expanded={sidebarExpanded}
+  onToggle={onToggle}
+  preFooterContent={
+    creditWarning ? (
+      <CreditWarningBanner
+        availableCredits={creditWarning.availableCredits}
+        remainingPct={creditWarning.remainingPct}
+        level={creditWarning.level}
+        expanded={sidebarExpanded}          // MUST track the rail
+        onBuyCredits={() => navigate("/settings/billing")}
+        onCollapsedClick={onToggle}         // expand the rail, don't jump to billing
+      />
+    ) : undefined
+  }
+  /* … */
+/>
+
+// Deriving the props safely
+const pct = total > 0 ? Math.max(0, Math.min(100, (available / total) * 100)) : 0;
+<CreditWarningBanner
+  availableCredits={available}
+  remainingPct={Math.round(pct)}            // ROUND — the component won't
+  level={pct < 5 ? "danger" : "warning"}
+  onBuyCredits={goBilling}
+  expanded={expanded}
+  onCollapsedClick={onToggle}
+/>
+
+// Bringing it back after the user dismissed it (e.g. credits dropped further)
+<CreditWarningBanner key={`credits-${level}-${bucket}`} … />
+
+// Through a sidebar that owns it for you (level defaults to "danger" there)
+<ScArtifaxSidebar
+  creditWarning={{ availableCredits: 120, remainingPct: 4, onBuyCredits: goBilling }}
+  /* … */
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **`StreamoidSidebar`'s `preFooterContent`** — CXO
+  (`src/app/components/app-sidebar.tsx:986`) does this directly, and is the only
+  **live** host render site. Photogenix has a local `LowCreditsBanner` wrapper that
+  computes the percentage, but it is currently **not rendered**: it is imported by
+  `DashboardContent.tsx` without being used, and the shipped rail hand-rolls its own
+  tinted div in `Sidebar.tsx` instead. Reuse the wrapper rather than the hand-roll.
+- **`ScArtifaxSidebar`'s `creditWarning` prop** (Artifax's live wiring) and
+  **`ScCatalogixSidebar`'s `creditWarning` prop** (that wrapper is `status: legacy`
+  and unused) — both render this component internally, so don't nest a second one.
+- Catalogix's current shell renders no credit banner at all.
+- Its expanded padding (`16px 8px`) assumes it sits inside a 256px rail; the collapsed
+  form assumes a 56px rail.
+- **Not** for page-level billing surfaces — that's `ScCreditsUsageCard` /
+  `ScPlanDetailsCard`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Credits are low enough that the user should act **now**, and the message should
+  follow them across every screen (hence: the sidebar).
+- You want the same alert to survive a rail collapse as a compact square.
+- The only action is "buy credits".
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Credits **remaining / usage meter** on a billing or settings page | `ScCreditsUsageCard` / `ScCreditsUsageCardMobile` |
+| Current-plan summary, upgrade CTA | `ScPlanDetailsCard` / `ScPlanCard` |
+| A generic onboarding/informational callout | `ScGuide` |
+| A non-interactive status or count chip | `ScBadges` |
+| Contextual "?" help | `ScInfoPopup` |
+| A blocking "out of credits" dialog | `ScModal` + `ScButton` |
+| A free-plan upsell CTA in the rail | a plain `ScButton` in `preFooterContent` (what Photogenix does) |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScCreditsUsageCard` — the billing-page meter with usage breakdown | This is a small red/orange sidebar nudge |
+| `ScGuide` — heading + body callout card, tokenised | This one reads `--primitives-*` directly and cannot re-theme |
+| `ScBadges` — a chip | This is a dismissible card with an action |
+| `ScCreditWarningBanner` — **does not exist** | The export is `CreditWarningBanner` |
+
+---
+
+## 4. Why to use it
+
+- **Both rail forms in one component.** The collapsed 40×40 square keeps the exact
+  tint and icon of the expanded card, so the warning never disappears when the user
+  collapses the sidebar.
+- **A consistent severity vocabulary.** `level` maps to the same warning/error hues
+  used everywhere else (`--primitives-warning-400` / `--primitives-error-400`) with
+  matching 8%-alpha fills and 32%-alpha strokes, instead of every app picking its own red.
+- **Correct button semantics for the two actions.** The dismiss ✕, the "Buy credits"
+  link and the collapsed square are all real `<button>`s with `aria-label`s; the
+  triangle is `aria-hidden`.
+- **Locale-aware numbers.** `availableCredits.toLocaleString()` so "1,200" not "1200".
+- **It's what the sidebars already render.** Using it directly keeps a host's
+  hand-rolled banner from drifting away from Artifax's and Catalogix's.
+
+---
+
+## Gotchas
+
+**1. The export has no `Sc` prefix.**
+
+```tsx
+// WRONG — undefined; the catalog's name for it is incorrect
+import { ScCreditWarningBanner } from "@streamoid/ui";
+
+// RIGHT
+import { CreditWarningBanner } from "@streamoid/ui";
+```
+
+**2. Dismissal is internal and permanent.** `const [dismissed, setDismissed] = useState(false)`
+and `if (dismissed) return null`. There is no `onDismiss`, no `dismissed` prop, no
+`persist` option. Once the user clicks ✕ the banner is gone for the lifetime of that
+component instance — even if credits drop to zero.
+
+```tsx
+// If it must be able to come back, change the key
+<CreditWarningBanner key={`credits-${severityBucket}`} … />
+```
+
+**3. `remainingPct` is printed unformatted.** Photogenix's own wrapper computes
+`(availableCredits / totalCredits) * 100` without rounding, which renders as
+`(33.33333333333333%)`. Round (and clamp) at the call site.
+
+**4. `expanded` defaults to `true`.** In a collapsed rail you must thread the rail
+state through, or you get the full 256px-wide card inside a 56px rail.
+
+**5. `onCollapsedClick` falls back to `onBuyCredits`.** Clicking the little square
+then navigates to billing, which is not what a "show me the warning" affordance should
+do. CXO passes the sidebar's `onToggle`, and `ScCatalogixSidebar` defaults its
+`creditWarning.onCollapsedClick` to `onToggle` — but `ScArtifaxSidebar` has **no**
+`onCollapsedClick` field on its `creditWarning` object at all, so in Artifax the
+collapsed square always jumps to billing.
+
+**6. It reads `--primitives-*`, not `--alias-*`.** `--primitives-warning-400` /
+`--primitives-error-400` plus literal `rgba(255,165,0,…)` / `rgba(255,0,0,…)` fills
+and borders. It is the one component in this family that bypasses the semantic token
+layer, so it does **not** re-theme with light mode the way the rest of the DS does.
+
+**7. All copy is hardcoded English.** "Low Credits", "Only {n} credits ({p}%)
+remaining.", "Buy credits", "to avoid interruptions.", plus the
+`"Dismiss low credits warning"` / `"Show low credits warning"` aria-labels. No label
+props — not usable on a localised surface without changing the DS.
+
+**8. `level` is required, with no default.** Rendering it via a sidebar's
+`creditWarning` prop gets you `"danger"` by default; calling the component directly
+does not, and TypeScript will (correctly) reject the omission.
+
+**9. The collapsed form can't be dismissed.** No ✕ in that branch — so a user who
+collapses the rail is stuck with the square until they expand and dismiss.
+
+**10. `toLocaleString()` is locale-dependent.** Server-rendered and client-rendered
+output can differ (hydration warnings) and screenshot tests can vary by CI locale.
+
+**11. It needs Tailwind.** The layout uses `flex`, `shrink-0`, `w-full`, `min-w-0`,
+`flex-1`, `items-center`, `cursor-pointer`, `underline`, `transition-opacity`,
+`hover:opacity-90`. `@streamoid/ui/dist/index.css` does **not** ship those utilities —
+your app must (all four hosts do).
+
+**12. Fixed geometry.** Collapsed square 40×40, icons 16×16, ✕ hit-area 16×16 (small
+for touch), body text a literal `fontSize: 12`.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/app-sidebar.tsx:986  (inside StreamoidSidebar's preFooterContent)
+<CreditWarningBanner
+  availableCredits={creditWarning.availableCredits}
+  remainingPct={creditWarning.remainingPct}
+  level={creditWarning.level}
+  expanded={sidebarExpanded}
+  onBuyCredits={handleBuyCreditsNavigation}
+  onCollapsedClick={onToggle}
+/>
+```
+
+```tsx
+// photogenix_v2  dashboard/client/src/components/layout/LowCreditsBanner.tsx:27
+// (a real wrapper, but currently unrendered — see §2; exercised only by
+//  dashboard/tests/low-credits-banner.vitest.tsx)
+<CreditWarningBanner
+  availableCredits={availableCredits}
+  remainingPct={remainingPct}          // NB: unrounded float — see Gotcha 3
+  level={level}
+  onBuyCredits={onBuyCredits}
+  expanded={expanded}
+  onCollapsedClick={onCollapsedClick}
+/>
+```
+
+Artifax reaches it indirectly, through `ScArtifaxSidebar`'s `creditWarning` prop
+(`artifax packages/shared/src/components/DashboardSidebar.tsx:680`). Catalogix's shell
+renders no banner today.
+
+---
+
+## Related
+
+- `StreamoidSidebar` — pass this as `preFooterContent`, threading `expanded`.
+- `ScArtifaxSidebar` / `ScCatalogixSidebar` — render it for you from `creditWarning`.
+- `ScCreditsUsageCard` — the billing-page credits meter (tokenised, non-dismissible).
+- `ScPlanCard` / `ScPlanDetailsCard` — where "Buy credits" usually lands.
+- `ScGuide` — the tokenised generic callout card.
+- `@streamoid/icons` — `SiconClose` is the dismiss glyph; the warning triangle is an inline SVG in this component.

package/dist/docs/InvoiceHistoryMobile.md

@@ -0,0 +1,222 @@
+---
+component: InvoiceHistoryMobile
+package: "@streamoid/ui"
+category: mobile
+status: stable
+renders: div
+tags: [mobile, billing, invoice, history, row, list-item, amount, cxo]
+related: [UsageHistoryMobile, ScBillingHistoryTableList, ScBillingHistoryHeader, ScInvoiceHistoryMobile]
+do_not_confuse_with: [ScInvoiceHistoryMobile, UsageHistoryMobile, ScBillingHistoryTableList, ScTableListMobile]
+used_by: [cxo]
+---
+
+# InvoiceHistoryMobile
+
+**One invoice row in CXO's mobile billing list.** Invoice id over a date on the left,
+a green amount right-aligned, and a 0.5px bottom border so a stack of them reads as a
+list. Note the export name: **no `Sc` prefix** — it and `UsageHistoryMobile` are the
+only two components in the mobile family without one.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are rendering the "Invoice history" tab of a mobile
+  billing screen, one component per invoice.
+- **Don't reach for it when:** you're on desktop (→ `ScBillingHistoryTableList` +
+  `ScBillingHistoryHeader`) or the row is a credit-usage log (→ `UsageHistoryMobile`).
+- **Four things that will bite you:**
+  1. **The export is `InvoiceHistoryMobile`, not `ScInvoiceHistoryMobile`.** A
+     `ScInvoiceHistoryMobile` *does* exist in the source tree
+     (`src/SC-InvoiceHistory-Mobile/`) but it is **not exported** — see "Don't
+     confuse with".
+  2. **No `onClick`, and no props spread.** `className` is the only escape hatch;
+     you cannot attach a handler, `key`-adjacent `data-*`, `style`, or `aria-*`.
+     Wrap it if the row must be tappable.
+  3. **The amount is always success-green**, including refunds and zero.
+  4. All three text props have demo defaults (`"# INV-2800-2026"`, `"Nov 9th, 2025"`,
+     `"₹320.89"` — a rupee amount).
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { InvoiceHistoryMobile } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+{invoices.map((inv) => (
+  <InvoiceHistoryMobile
+    key={inv.id}
+    invoiceId={`# ${inv.number}`}
+    date={formatDate(inv.createdAt)}
+    amount={`$${inv.amountPaid.toFixed(2)}`}
+  />
+))}
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `invoiceId` | `string` | `"# INV-2800-2026"` | ⚠️ Demo default. 16px primary line. You supply the `#` — the component adds nothing. Truncates with ellipsis. |
+| `date` | `string` | `"Nov 9th, 2025"` | ⚠️ Demo default. 14px tertiary sub-line. Pre-formatted string; no date parsing. |
+| `amount` | `string` | `"₹320.89"` | ⚠️ Demo default **in rupees**. 16px/600, always `--alias-text-and-icons-success` green. You supply the currency symbol. |
+| `className` | `string` | – | Appended after internal classes (safely — uses `className ?? ""`). **The only extra prop it accepts.** |
+
+That is the whole API. There is no `onClick`, no `...props`, no `status`, no icon.
+
+### Recipes
+
+```tsx
+// Make the row tappable — the component itself has no onClick
+<div role="button" tabIndex={0} onClick={() => openInvoice(inv)} className="cursor-pointer">
+  <InvoiceHistoryMobile
+    invoiceId={`# ${inv.number}`}
+    date={formatDate(inv.createdAt)}
+    amount={`$${inv.amountPaid.toFixed(2)}`}
+  />
+</div>
+
+// Empty state — render your own; this component has no zero/empty mode
+{invoices.length === 0
+  ? <p>No invoices found</p>
+  : invoices.map((inv) => <InvoiceHistoryMobile key={inv.id} {...toRow(inv)} />)}
+
+// Stripe amounts arrive in cents
+<InvoiceHistoryMobile
+  invoiceId={`# ${inv.meta?.stripeInvoiceId ?? inv._id}`}
+  date={formatDate(inv.createdAt)}
+  amount={inv.amountPaid != null ? `$${inv.amountPaid.toFixed(2)}` : `$${(inv.amount / 100).toFixed(2)}`}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO mobile billing screen**, inside the "Invoice history" tab of the
+  `ScTabSwitcher`, below `ScPlanDetailsCardMobile` and `ScCreditsUsageCardMobile`.
+- Any narrow scrolling list of "document + date + money" rows.
+
+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.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The viewport is mobile and each invoice is a full-width two-line row.
+- You already have id, date and amount as display strings.
+- The list is read-only, or you own the tap target yourself (wrapper div).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Desktop billing history table | `ScBillingHistoryHeader` + `ScBillingHistoryTableList` |
+| Credit-usage / debit log rows on mobile | `UsageHistoryMobile` |
+| Desktop credit/usage log table | `ScBillingLogsTableHeader` + `ScBillingLogsTableList` |
+| A generic member/user row on mobile | `ScTableListMobile` |
+| Referral rows on mobile | `ScReferralCardMobile` |
+| A row that must be clickable *with* DS-provided semantics | none of these — wrap it, or use `ScTableListMobile` which has `onRowClick` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScInvoiceHistoryMobile` in `src/SC-InvoiceHistory-Mobile/` — an earlier, near-identical copy with `invoiceNumber` instead of `invoiceId`, plus `onClick` and a props spread | It is **not exported** from `index.ts`, its CSS is **not** in `dist/index.css`, and `IScInvoiceHistoryMobileProps` is absent from `dist/index.d.ts`. Importing it will fail. Use `InvoiceHistoryMobile`. |
+| `UsageHistoryMobile` — same chrome, but two rows of two values and a **red** figure | Invoices are green money in; usage is red credits out |
+| `ScBillingHistoryTableList` — the desktop row | Different metrics, header component required |
+
+---
+
+## 4. Why to use it
+
+- **The truncation math is done.** `flex: 1; min-width: 0` on the text column with
+  `ellipsis` on both lines, and `flex-shrink: 0` on the amount, so a long invoice id
+  never pushes the money off-screen — the single thing hand-rolled money rows get wrong.
+- **Self-dividing.** The bottom border is part of the row, so you never end up with a
+  trailing divider or a double line between sections.
+- **Correct tokens.** It uses the real `--alias-text-and-icons-*` names (unlike much
+  of the mobile family), so it genuinely flips light/dark.
+- **Money semantics are consistent** with `UsageHistoryMobile`: green = money/credits
+  in, red = credits out, tertiary grey = context.
+
+---
+
+## Gotchas
+
+**1. The name has no `Sc` prefix.** Autocomplete for `Sc…` will not find it.
+
+```tsx
+// WRONG — not exported
+import { ScInvoiceHistoryMobile } from "@streamoid/ui";
+
+// RIGHT
+import { InvoiceHistoryMobile } from "@streamoid/ui";
+```
+
+**2. No props spread at all.** The signature is
+`({ invoiceId, date, amount, className })` — nothing else reaches the DOM.
+
+```tsx
+// SILENTLY IGNORED — onClick, style and data-* never land anywhere
+<InvoiceHistoryMobile invoiceId="# 1" onClick={open} style={{ opacity: 0.5 }} data-id="1" />
+
+// RIGHT — wrap it
+<div onClick={open} data-id="1"><InvoiceHistoryMobile invoiceId="# 1" /></div>
+```
+
+(In TypeScript the extra props are a compile error; in a plain-JS host they are
+silently dropped.)
+
+**3. The amount is unconditionally green.** `--alias-text-and-icons-success` is
+hardcoded, so refunds, credit notes and `$0.00` all read as positive.
+
+**4. Demo defaults, including a rupee amount.** Rendering it bare gives
+`# INV-2800-2026 / Nov 9th, 2025 / ₹320.89`, which looks like real data.
+
+**5. Nothing is formatted for you.** No currency, no locale grouping, no date parsing,
+no `#` prefix. Three strings in, three strings out.
+
+**6. No status.** Paid / open / void / failed cannot be expressed. If you need it,
+put it in `invoiceId` or `date`, or move to a row component that has a badge.
+
+**7. `align-items: flex-start`** on the root, so the amount aligns to the **top** of
+the row, level with `invoiceId`, not vertically centred.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/mobile-billing-content.tsx:231
+<InvoiceHistoryMobile
+  key={inv._id}
+  invoiceId={`# ${inv.meta?.stripeInvoiceId ?? inv._id}`}
+  date={formatDate(inv.createdAt)}
+  amount={
+    inv.amountPaid != null
+      ? `$${inv.amountPaid.toFixed(2)}`
+      : `$${(inv.amount / 100).toFixed(2)}`
+  }
+/>
+```
+
+---
+
+## Related
+
+- `UsageHistoryMobile` — the sibling row for the "Usage history" tab.
+- `ScInvoiceHistoryMobile` (`src/SC-InvoiceHistory-Mobile/`) — the unexported earlier
+  copy; do not import it.
+- `ScBillingHistoryHeader` / `ScBillingHistoryTableList` — the desktop table.
+- `ScPlanDetailsCardMobile` / `ScCreditsUsageCardMobile` — the cards above the tabs.
+- `ScTabSwitcher` / `ScTabComp` — what toggles invoice vs usage.