@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScReferralCardMobile.md

@@ -0,0 +1,226 @@
+---
+component: ScReferralCardMobile
+package: "@streamoid/ui"
+category: mobile
+status: stable
+renders: div
+tags: [mobile, referral, invite, credits, card, badge, avatar, billing]
+related: [ScReferralTableHeader, ScReferralTableList, ScProfileV2Mobile, ScTableListMobile, ScBadges]
+do_not_confuse_with: [ScReferralTableList, ScTableListMobile, ScProfileV2Mobile, ScBadges]
+---
+
+# ScReferralCardMobile
+
+**One referral, as a mobile card.** A bordered rounded card: 40px avatar + name/email
+with a grey status pill on the right, a divider, then the referral date on the left and
+the credits earned in green on the right.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building the mobile view of a referral programme
+  screen — one card per person referred.
+- **Don't reach for it when:** you're on desktop (→ `ScReferralTableHeader` +
+  `ScReferralTableList`) or the row is a workspace member (→ `ScTableListMobile`).
+- **Four things that will bite you:**
+  1. **It is `width: 349px`, fixed.** Not `100%`. It overflows a 360px phone with any
+     side padding.
+  2. **The status pill is always neutral grey.** "Confirmed" and "Pending" look
+     identical — there is no variant, and it is not `ScBadges`.
+  3. **`credits` is always success-green**, so a clawback still reads as a gain.
+  4. Every text prop has a demo default, including a fake person
+     (`"Chris Hemsworth"` / `"chris@kepler.com"`) and `credits = "+ 500"`.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScReferralCardMobile } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScReferralCardMobile
+  name={r.name}
+  email={r.email}
+  imageUrl={r.avatarUrl}
+  badge={r.status}
+  date={formatDate(r.createdAt)}
+  credits={`+ ${r.points}`}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `name` | `string` | `"Chris Hemsworth"` | ⚠️ Demo default. Also the source of the initials **and** the `<img alt>`. |
+| `email` | `string` | `"chris@kepler.com"` | ⚠️ Demo default. 12px tertiary sub-line. |
+| `imageUrl` | `string` | – | When set, `<img src>` with `object-fit: cover`; otherwise initials. No error fallback. |
+| `badge` | `string` | `"Confirmed"` | ⚠️ Demo default. Free text in a **fixed neutral-grey** pill. Never recolours. |
+| `date` | `string` | `"Nov 9th, 2025"` | ⚠️ Demo default. Pre-formatted string; 14px secondary. |
+| `credits` | `string` | `"+ 500"` | ⚠️ Demo default. 16px/600, hardcoded success green. You supply the `+`/`-`. |
+| `onClick` | `(e: React.MouseEvent) => void` | – | Attached to the card root. **No `role`, `tabIndex` or `cursor: pointer` come with it** — see Gotcha 5. |
+| `className` | `string` | – | Appended after internal classes. Unguarded concat — see Gotcha 4. |
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | – | Spread onto the root `div`. |
+
+### Layout
+
+| Region | Content |
+|---|---|
+| Row 1 | 40px avatar (image or initials) · `name` / `email` column (`flex: 1`, both truncate) · `badge` pill (`flex-shrink: 0`) |
+| Divider | 0.5px `--alias-border-subtle`, full width |
+| Row 2 | `date` (left) · `credits` (right, green) — **both `flex: 1 0 0`**, so they split the row 50/50 |
+
+### Recipes
+
+```tsx
+// Full-width in a mobile list (the card is 349px by default)
+<ScReferralCardMobile
+  name={r.name}
+  email={r.email}
+  badge={r.confirmed ? "Confirmed" : "Pending"}
+  date={formatDate(r.createdAt)}
+  credits={`+ ${r.points.toLocaleString("en-US")}`}
+  className="w-full"
+/>
+
+// The pill can't show state through colour — put the state in the words, or
+// render your own ScBadges beside the card
+import { ScBadges } from "@streamoid/ui";
+<ScBadges text="Pending" variant="warning" styleVariant="opaque" />
+
+// Tappable card — add the semantics yourself
+<ScReferralCardMobile
+  name={r.name}
+  email={r.email}
+  onClick={() => openReferral(r)}
+  role="button"
+  tabIndex={0}
+  className="w-full cursor-pointer"
+/>
+```
+
+---
+
+## 2. Where to use it
+
+The mobile referral-programme screen: a vertical stack of cards, one per person
+referred, where the desktop shows a table (`ScReferralTableHeader` +
+`ScReferralTableList`). Because the card has its own border and radius, stack them with
+a real gap — unlike `InvoiceHistoryMobile`/`UsageHistoryMobile`, which are
+self-dividing rows.
+
+It composes nothing from the DS — the avatar and the badge are hand-rolled, not `ScDp`
+and not `ScBadges`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The viewport is mobile and each referral is a card, not a table row.
+- The status vocabulary is small and doesn't need colour to be legible.
+- Credits earned are always positive.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Desktop referral table | `ScReferralTableHeader` + `ScReferralTableList` (`userName`, `userEmail`, `date`, `status`, `points`) |
+| A workspace member row on mobile (role + access icons + click) | `ScTableListMobile` |
+| Just identity (avatar + name + email), no badge or credits | `ScProfileV2Mobile` |
+| A status chip that must change colour | `ScBadges` |
+| Invoice rows on mobile | `InvoiceHistoryMobile` |
+| Credit-usage rows on mobile | `UsageHistoryMobile` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScReferralTableList` — the desktop row; props are `userName`/`userEmail`/`status`/`points` | This card uses `name`/`email`/`badge`/`credits` for the same data |
+| `ScTableListMobile` — the mobile *member* row, with `onRowClick` and icon groups | Referrals, not team members |
+| `ScProfileV2Mobile` — the same 40px avatar + name/email block, no card chrome | This is that block plus a badge, a divider and a credits row |
+| `ScBadges` — the real status chip | The `badge` here is a plain grey `<div>`; it will not colour by state |
+
+---
+
+## 4. Why to use it
+
+- **The whole referral row in one prop set** — identity, status, date and reward —
+  instead of composing four components and getting the truncation wrong.
+- **Truncation is handled** in both text columns (`flex: 1 0 0; min-width: 0` with
+  ellipsis), so long emails don't push the badge off the card.
+- **Consistent mobile metrics** — 40px avatar, 14/12px type pair, `--radius-3xl` card,
+  12px padding — matching `ScProfileV2Mobile` and `ScTableListMobile`.
+- **Credits colour matches the billing family** (green = credits in), the same
+  convention `InvoiceHistoryMobile` uses.
+
+---
+
+## Gotchas
+
+**1. Fixed `width: 349px`.** The root is not fluid.
+
+```tsx
+// WRONG — 349px inside a 360px phone with 16px side padding = horizontal scroll
+<ScReferralCardMobile name={n} email={e} />
+
+// RIGHT
+<ScReferralCardMobile name={n} email={e} className="w-full" />
+```
+
+**2. The badge never changes colour.** `.badge` is hardcoded
+`--alias-fill-neutral-neutralactive` with primary text.
+
+```tsx
+// MISLEADING — "Pending" and "Confirmed" are visually identical
+<ScReferralCardMobile badge="Pending" />
+```
+
+**3. `credits` is unconditionally green.** No sign handling, no variant. A negative
+value still renders in `--alias-text-and-icons-success`.
+
+**4. `className` is concatenated unguarded.** Omit it and the root carries a literal
+`undefined` class.
+
+**5. `onClick` brings no semantics.** The root is a plain `div` with no `role`, no
+`tabIndex` and no `cursor: pointer` in the CSS. Add all three yourself.
+
+**6. `date` and `credits` split the bottom row 50/50.** Both are `flex: 1 0 0`, so the
+credits figure sits at the midpoint-right, not hugged to the edge. Don't expect a
+right-hugged number.
+
+**7. A broken `imageUrl` shows a broken image, not initials.** The initials branch is
+chosen purely on `imageUrl` being truthy; there is no `onError`.
+
+**8. Initials come only from `name`.** `name.split(" ").map(n => n[0]).join("").toUpperCase().slice(0, 2)`
+— no `initials` prop. An empty `name` gives an empty circle.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+To be precise: it is exported from `@streamoid/ui` but no host app renders it, and it is
+not agent-runtime — it is currently unused. The **desktop** referral screen *is* built:
+`packages/settings/src/settings-content.tsx:1011` renders `ScReferralTableHeader` +
+`ScReferralTableList`. This card is the missing mobile half of that screen, and belongs
+in CXO's mobile settings surface (`cxo-dashboard/src/app/components/mobile-*.tsx`), which
+has no referral tab yet.
+
+---
+
+## Related
+
+- `ScReferralTableHeader` / `ScReferralTableList` — the desktop table for the same data.
+- `ScProfileV2Mobile` — the avatar + name/email block on its own.
+- `ScTableListMobile` — the mobile member row, with `onRowClick` and icon groups.
+- `ScBadges` — use this when the status must be colour-coded.
+- `InvoiceHistoryMobile` / `UsageHistoryMobile` — the other mobile billing list rows.

package/dist/docs/ScReferralTableHeader.md

@@ -0,0 +1,260 @@
+---
+component: ScReferralTableHeader
+package: "@streamoid/ui"
+category: tables
+status: stable
+renders: div
+tags: [table, header, column-headers, referral, referrals, rewards, invite, settings, referral-history]
+related: [ScReferralTableList, ScHeader, ScReferralCardMobile, ScTableHeader, ScBillingHistoryHeader, ScBillingLogsTableHeader, ScCatalogixStoreHeader]
+do_not_confuse_with: [ScTableHeader, ScHeader, ScReferralCardMobile, ScBillingHistoryHeader, ScBillingLogsTableHeader, ScCatalogixStoreHeader]
+---
+
+# ScReferralTableHeader
+
+**The column-header strip of the Referral History table.** A shaded flex row of exactly
+four uppercase muted labels — USER, DATE, STATUS, REWARD — rendered as four internal
+`ScHeader` cells on the widths `ScReferralTableList` uses. It is the *ruler*; the rows
+are the data.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building the Settings → Referral "Referral History"
+  table and need the header above `ScReferralTableList` rows.
+- **Don't reach for it when:** you need the members table header (→ `ScTableHeader`),
+  a single sortable column label (→ `ScHeader`), or the mobile referral surface
+  (→ `ScReferralCardMobile`, which has no header strip).
+- **Four things that will bite you:**
+  1. `className` is the **only** prop. No `type` variant, no label props, no
+     `HTMLAttributes` — the four English labels are baked in.
+  2. **`...props` is destructured but never spread.** `style`, `onClick`, `data-*`,
+     `aria-*` are dropped (and are type errors).
+  3. Unlike `ScTableHeader`, its CSS has **no `flex-shrink: 0` and no
+     `align-self: stretch`** — inside a constrained flex column it can be squashed or
+     fail to fill the width.
+  4. The USER column shows a **descending chevron that is pure decoration**. Nothing
+     is sortable.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScReferralTableHeader, ScReferralTableList } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+There is nothing to configure:
+
+```tsx
+<ScReferralTableHeader />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `className` | `string` | – | Appended after the internal class. The only escape hatch — there is no `style` prop. |
+
+⚠️ `...props` exists in the signature but is **never applied to the DOM**, and
+`IScReferralTableHeaderProps` does not extend `React.HTMLAttributes`, so anything else
+you pass is both a compile error and a no-op.
+
+### The column contract (shared with `ScReferralTableList`)
+
+| Column | Header label | Row prop | Width | Notes |
+|---|---|---|---|---|
+| USER | `"User"` (`state="down"`) | `userName` + `userEmail` → `ScProfile` | `flex: 1` | The only flexible column |
+| DATE | `"Date"` | `date` | `7.5rem` | Row cell truncates, no tooltip |
+| STATUS | `"Status"` | `status` → `ScBadges` | `5rem` | Badge width is forced to `5rem` by the row; long words wrap, they don't truncate |
+| REWARD | `"Reward"` | `points` | `7.5rem` | Row cell is always green |
+
+Both components use `gap: 1.5rem` and `padding-inline: 1rem`. That, plus the widths
+above, is what makes header and rows line up. Change neither via `className` unless you
+change both.
+
+### Recipes
+
+```tsx
+// The whole Referral History table
+<div style={{ display: "flex", flexDirection: "column" }}>
+  <ScReferralTableHeader />
+  {referrals.map((r) => (
+    <ScReferralTableList
+      key={r.id}
+      userName={r.name}
+      userEmail={r.email}
+      date={r.date}
+      status={r.status}
+      points={r.points}
+    />
+  ))}
+</div>
+
+// Sticky + non-shrinking. You cannot pass `style`, so use className.
+<ScReferralTableHeader className={styles.stickyHead} />
+/* .stickyHead {
+     position: sticky; top: 0; z-index: 1;
+     flex-shrink: 0; align-self: stretch;       // the DS CSS omits both — see Gotcha 3
+     background: var(--alias-fill-neutral-neutral);
+   } */
+
+// Or wrap it, which is the pattern the rest of the settings screens use
+<div style={{ position: "sticky", top: 0, zIndex: 1, flexShrink: 0 }}>
+  <ScReferralTableHeader />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **Settings → Referral → "Referral History"**, desktop, directly above a list of
+  `ScReferralTableList` rows. That screen lives in the shared `@streamoid/settings`
+  package (which ships into CXO desktop settings) — and the history block there is
+  currently **commented out**, so nothing renders it today. See "In the wild".
+- The live part of that screen is the referral-link / invite-by-email pair of
+  `ScTextField`s above where this table would sit.
+- Mobile uses `ScReferralCardMobile` instead — stacked cards, **no header strip**.
+- It composes four `ScHeader` cells and a background. Nothing else.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are rendering **referral history** in a desktop table and want the header pinned
+  to the same widths the DS row uses.
+- You want the "shaded header strip over transparent rows" treatment shared by every
+  table in the products.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Members / invites table header (User / Role / Access / Invited by / …) | `ScTableHeader` — it also has a `type="pending"` variant |
+| Billing history header (Invoice / Amount / Date / Action) | `ScBillingHistoryHeader` |
+| Credit & usage logs header (App / Activity / Used by / Date / Credits used / Balance) | `ScBillingLogsTableHeader` |
+| Catalogix stores list header | `ScCatalogixStoreHeader` — the only header in the family whose labels are props |
+| One sortable column label with an asc/desc chevron | `ScHeader` — this strip is four of them, pre-labelled |
+| Renaming a column ("Reward" → "Credits") | Nothing here; the strings are hardcoded. Compose `ScHeader` cells yourself or change the DS |
+| The mobile referral list | `ScReferralCardMobile` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScTableHeader` — the **members** strip: five columns, a `type="default" \| "pending"` prop | `ScReferralTableHeader` has four fixed columns and no variants |
+| `ScHeader` — a **single** column-label cell with `state="up" \| "down" \| "none"` | This is the whole strip |
+| `ScCatalogixStoreHeader` — same shape, but every label is a prop plus `showAssets`/`showCreatedBy` | This one takes no labels at all |
+| `ScReferralCardMobile` — the mobile referral entry | Not a header; and mobile has no header row |
+| `ScReferralTableList` — the *row* sibling | Different component; pair them |
+
+---
+
+## 4. Why to use it
+
+- **It is the alignment contract.** `flex:1 / 7.5rem / 5rem / 7.5rem`, `gap: 1.5rem`,
+  `padding: 0.75rem 1rem` exist in exactly two files — this one and
+  `ScReferralTableList`. Hand-rolling the header is how the table shears apart when
+  someone adds a column.
+- **Two-tone that survives light mode.** The strip paints
+  `--alias-fill-neutral-neutral` while rows stay transparent, so it still reads as a
+  header when the theme flips instead of relying on a grey that collapses to white.
+- **Label typography is already the DS's** `font-size-xs` +
+  `--alias-text-and-icons-muted` + uppercase, matching every other table header in the
+  products.
+- Zero API to get wrong: there is exactly one optional prop.
+
+---
+
+## Gotchas
+
+**1. No label props, no variants.** "User", "Date", "Status" and "Reward" are literal
+strings inside the component. There is no `type` prop, so there is no pending/settled
+variant of this table. Don't use it on a localised surface without changing the DS.
+
+**2. `...props` is destructured and thrown away.** The root div receives only
+`className`.
+
+```tsx
+// WRONG — type error, and even with a cast the style is dropped
+<ScReferralTableHeader style={{ position: "sticky", top: 0 }} />
+
+// RIGHT — className, or your own wrapper
+<div style={{ position: "sticky", top: 0, zIndex: 1 }}>
+  <ScReferralTableHeader />
+</div>
+```
+
+**3. It omits `flex-shrink: 0` and `align-self: stretch`.** `ScTableHeader` and
+`ScTableList` both set them; this pair does not. Inside a constrained
+`flex-direction: column` container (a fixed-height, `overflow-y: auto` panel — exactly
+what a settings screen is) the strip can be compressed toward zero height, and if the
+parent overrides `align-items` it won't span the full width either. Add both via
+`className` when you drop it into a scrolling column.
+
+**4. The USER chevron is decoration.** The first cell is `<ScHeader state="down">`, so
+it renders a double-down arrow that *looks* like "sorted descending". No `onClick`
+reaches any cell and there is no sort prop anywhere.
+
+**5. It is not a table.** No `role="table"`/`row`/`columnheader`, no `<th>`, no
+`scope`, no `aria-sort`. Row cells are not associated with these labels for assistive
+tech.
+
+**6. Not sticky, and it doesn't own the scroll.** Long histories scroll the header
+away. Add `position: sticky; top: 0`, an opaque `background` and a `z-index` (the rows
+are `position: relative`, so without one they paint over it).
+
+**7. `className` lands as the literal string `"undefined"` when omitted** — the class
+list is built by concatenation. Harmless in the browser; breaks exact-string class
+assertions in tests.
+
+**8. Labels are force-uppercased** by `ScHeader`'s `text-transform: uppercase`. Nothing
+you can do about it here, but don't be surprised by the shouty rendering in snapshots.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+More precisely: **the only integration that exists is commented out.** In the shared
+settings package the Referral History block — header plus row loop — sits inside a
+`{/* Referral History section commented out … */}` comment:
+
+```tsx
+// npm-components  packages/settings/src/settings-content.tsx:1011  (inside a commented-out block)
+<ScReferralTableHeader />
+{REFERRALS.map((ref) => (
+  <ScReferralTableList
+    key={ref.id}
+    userEmail={ref.email}
+    date={ref.date}
+    status={ref.status}
+    points={ref.points}
+  />
+))}
+```
+
+Where it belongs: **Settings → Referral**, desktop, under the "Referral History" label
+and above the row loop — uncomment that block (and note that the `REFERRALS` array
+there is local demo data, and `userName` is not passed, which triggers
+`ScReferralTableList` Gotcha 1). CXO reaches this screen through
+`@streamoid/settings`, so no CXO-side change is needed.
+
+---
+
+## Related
+
+- `ScReferralTableList` — the row sibling; the two share one width contract and must be
+  rendered together.
+- `ScHeader` — the single column-label cell this strip is built from; use it to compose
+  a header for a table the DS doesn't cover.
+- `ScReferralCardMobile` — the mobile form of the same data.
+- `ScTableHeader` / `ScCatalogixStoreHeader` / `ScBillingHistoryHeader` /
+  `ScBillingLogsTableHeader` — the other domain-specific header/row pairs, same pattern.