@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScReferralTableList.md

@@ -0,0 +1,293 @@
+---
+component: ScReferralTableList
+package: "@streamoid/ui"
+category: tables
+status: stable
+renders: div
+tags: [table, row, referral, referrals, rewards, invite, points, status, settings, referral-history]
+related: [ScReferralTableHeader, ScProfile, ScBadges, ScReferralCardMobile, ScTableList, ScBillingLogsTableList]
+do_not_confuse_with: [ScTableList, ScReferralTableHeader, ScReferralCardMobile, ScBillingHistoryTableList, ScBillingLogsTableList, ScBadges]
+---
+
+# ScReferralTableList
+
+**One row of the Referral History table.** A `ScProfile` identity cell that flexes, then
+a date, a status `ScBadges` chip and a reward figure — on the widths
+`ScReferralTableHeader` defines. Four columns, five string props, no state.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are rendering Settings → Referral → "Referral History" and
+  have a list of `{ name, email, date, status, points }`.
+- **Don't reach for it when:** you need the members table row (→ `ScTableList` /
+  hand-rolled), the mobile referral entry (→ `ScReferralCardMobile`), or a billing /
+  usage row (→ `ScBillingHistoryTableList`, `ScBillingLogsTableList`).
+- **Four things that will bite you:**
+  1. **Every prop has a placeholder default**, and `userName` has none of its own — omit
+     it and `ScProfile`'s default leaks, so the row reads "Chris Hemsworth".
+  2. The **avatar is always a broken image.** `ScProfile.profileImage` falls back to the
+     relative path `"profile-image0.png"` and this row exposes no way to set it.
+  3. The **status chip is always the same neutral grey.** `ScBadges` is given only
+     `text`, so `variant` stays `"default"` — "Confirmed" is not green and "Pending" is
+     not amber, and there is no prop to change it.
+  4. The **reward is always green** (`--alias-text-and-icons-success`), whatever string
+     you pass — including `"0"` or `"- 500"`.
+
+---
+
+## 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
+
+Pass all five — the defaults are demo data:
+
+```tsx
+<ScReferralTableList
+  userName={r.name}
+  userEmail={r.email}
+  date={r.date}
+  status={r.status}
+  points={r.points}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `userName` | `string` | – (⚠️ **effectively `"Chris Hemsworth"`**) | Passed to `ScProfile` as `name`. It has no default here, so `undefined` falls through to `ScProfile`'s own default. Line 1 of the identity cell; truncates. |
+| `userEmail` | `string` | `"chris@kepler.com"` | ⚠️ Placeholder default. Passed to `ScProfile` as `subText` — line 2 of the identity cell; truncates. |
+| `date` | `string` | `"Nov 9th, 2025"` | ⚠️ Placeholder default. Pre-formatted string; the row does no date formatting. `7.5rem`, truncates, no tooltip. |
+| `status` | `string` | `"Confirmed"` | ⚠️ Placeholder default. Free string → `ScBadges text`. Always the neutral chip — see Gotcha 3. Forced to `5rem` wide. |
+| `points` | `string` | `"+ 500"` | ⚠️ Placeholder default. Reward figure, `text-md-semibold`, **always green**. `7.5rem`, truncates. Include the sign yourself. |
+| `className` | `string` | – | Appended after the internal class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div. Unlike `ScTableList` there is **no internal `onClick`**, so `onClick`, `style`, `aria-*` and `data-*` all work normally. |
+
+### What renders in each column
+
+| Column | Rendered by | Controllable? |
+|---|---|---|
+| USER (`flex: 1`) | `ScProfile name={userName} subText={userEmail}` | ✅ both strings. ❌ avatar — no `profileImage` prop (Gotcha 2). |
+| DATE (`7.5rem`) | plain text cell | ✅ `date` |
+| STATUS (`5rem`) | `ScBadges text={status}` | ✅ the text only. ❌ colour/variant (Gotcha 3). |
+| REWARD (`7.5rem`) | plain text cell | ✅ `points`. ❌ colour — always success green (Gotcha 4). |
+
+### 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={formatDate(r.createdAt)}      // the row does not format dates
+      status={r.status}
+      points={`${r.credits >= 0 ? "+ " : "- "}${Math.abs(r.credits)}`}  // sign is yours
+    />
+  ))}
+</div>
+
+// Clickable row — no onRowClick here, plain onClick works
+<ScReferralTableList
+  userName={r.name}
+  userEmail={r.email}
+  onClick={() => openReferral(r)}
+  style={{ cursor: "pointer" }}
+/>
+
+// Pending referral: pass an empty reward rather than a zero, so it doesn't read as green earnings
+<ScReferralTableList userName={r.name} userEmail={r.email} status="Pending" points="" />
+
+// Non-shrinking inside a scrolling settings column (the CSS omits flex-shrink: 0)
+<ScReferralTableList className={styles.row} />
+/* .row { flex-shrink: 0; align-self: stretch; } */
+```
+
+---
+
+## 2. Where to use it
+
+- **Settings → Referral → "Referral History"**, desktop, stacked under
+  `<ScReferralTableHeader />`. That screen lives in the shared `@streamoid/settings`
+  package (which ships into CXO desktop settings), and the history block there is
+  currently **commented out** — see "In the wild".
+- Mobile uses `ScReferralCardMobile` instead; there is no header strip on mobile.
+- It composes `ScProfile` (identity cell) and `ScBadges` (status chip). Those are the
+  two pieces to reuse if you outgrow the row.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You have referral entries whose only display data is name, email, date, a status word
+  and a reward figure.
+- You want the row to line up with `ScReferralTableHeader` without copying widths.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Members / invites row (Role, Access, Invited by, pending actions) | Your own row under `ScTableHeader`; `ScTableList` only if placeholder content is acceptable |
+| Mobile referral entry | `ScReferralCardMobile` |
+| Invoice row with a download action | `ScBillingHistoryTableList` |
+| Credit & usage log row (App / Activity / Used by / Date / Credits used / Balance) | `ScBillingLogsTableList` |
+| Catalogix stores row | `ScCatalogixStoreTableList` |
+| A **colour-coded** status chip (success / warning / error / info) | `ScBadges` directly, with `variant` and `styleVariant` — this row won't pass them through |
+| A real avatar in the identity cell | `ScProfile` directly, with `profileImage` |
+| A reward that can be negative or neutral | Compose the cell yourself; this one is hardcoded green |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScTableList` — the **members** row: `ScRole` + access icons + `variant="active" \| "pending"` + `hover` + `onRowClick` | `ScReferralTableList` is four columns, no variants, no `onRowClick` (plain `onClick` works) |
+| `ScReferralTableHeader` — the header strip above it | Different component; pair them |
+| `ScReferralCardMobile` — the mobile card for the same data | Not a table row |
+| `ScBadges` — the standalone chip, with real `variant` colours | This row renders one internally and gives it only `text` |
+| `ScBillingHistoryTableList` — also a four-cell settings row, but Invoice / Amount / Date / Download | Different widths; not interchangeable |
+
+Note the naming asymmetry with the members pair: this row has a **`userName`** prop
+(`ScTableList` does not) but **no `onRowClick`** (`ScTableList` does). Don't copy prop
+names between the two.
+
+---
+
+## 4. Why to use it
+
+- **It is the alignment contract's other half.** `flex:1 / 7.5rem / 5rem / 7.5rem`,
+  `gap: 1.5rem`, `padding: 1.25rem 1rem` and the 1px `--alias-border-subtle` bottom rule
+  match `ScReferralTableHeader` exactly. Copy them if you hand-roll.
+- **The identity cell truncates correctly.** `ScProfile` is overridden to `flex: 1;
+  width: unset`, and both its lines ellipsise, so a long email can't push the reward
+  column off-screen.
+- **Everything is tokenised** — the row rule, the badge surface and the success green all
+  come from `--alias-*`, so the row survives the light/dark flip (unlike the mobile
+  family, whose text tokens are misnamed).
+- **Props spread cleanly.** There is no internal `onClick` fighting yours, which is the
+  single biggest trap in `ScTableList`.
+
+---
+
+## Gotchas
+
+**1. `userName` has no default *here*, so `ScProfile`'s default leaks.** Omit it and
+every row is labelled "Chris Hemsworth". (Passing `userName=""` does render an empty
+line — defaults only apply to `undefined`.)
+
+```tsx
+// WRONG — renders "Chris Hemsworth" above every email
+<ScReferralTableList userEmail={r.email} date={r.date} status={r.status} points={r.points} />
+
+// RIGHT
+<ScReferralTableList userName={r.name} userEmail={r.email} date={r.date} status={r.status} points={r.points} />
+```
+
+**2. The avatar is a broken image.** `ScProfile`'s `profileImage` default is the relative
+path `"profile-image0.png"`, resolved against the current route, and this row gives you
+no way to override it — so you get a broken-image glyph (and the `<img>` has no `alt`).
+If the avatar matters, compose the identity cell from `ScProfile` yourself.
+
+**3. The status chip has no colour semantics.** `ScBadges` is rendered as
+`<ScBadges text={status} />`, so `variant` stays `"default"` and `styleVariant` stays
+`"solid"` — every status is the same `--alias-fill-neutral-neutralactive` grey chip with
+primary text. There is no `statusVariant` prop.
+
+```tsx
+// WRONG — expecting a green "Confirmed" / amber "Pending"
+<ScReferralTableList status="Confirmed" />   // renders neutral grey either way
+
+// RIGHT — if the colour is load-bearing, build the cell yourself
+<div style={{ display: "flex", alignItems: "center", gap: "1.5rem", padding: "1.25rem 1rem" }}>
+  <ScProfile name={r.name} subText={r.email} style={{ flex: 1 }} />
+  <div style={{ width: "7.5rem" }}>{r.date}</div>
+  {/* ScBadges takes className only — no style, no props spread — so size it with a class */}
+  <ScBadges text={r.status} variant={r.status === "Confirmed" ? "success" : "warning"}
+            styleVariant="opaque" className={styles.statusCell} />
+  <div style={{ width: "7.5rem" }}>{r.points}</div>
+</div>
+```
+
+**4. The reward is always success green.** `.points` hardcodes
+`--alias-text-and-icons-success`, so `"0"`, `"—"` or `"- 500"` all render as earnings.
+Pass an empty string for "nothing yet" rather than a zero.
+
+**5. All five props default to demo data.** `"chris@kepler.com"`, `"Nov 9th, 2025"`,
+`"Confirmed"`, `"+ 500"` — so a typo'd prop name renders plausible fake data instead of
+failing. Check spelling against the props table.
+
+**6. It formats nothing.** `date` and `points` are printed verbatim; supply the
+formatted string, including the `+`/`-` sign.
+
+**7. It omits `flex-shrink: 0` and `align-self: stretch`.** `ScTableList` sets both; this
+row does not. Inside a constrained `flex-direction: column` container (a fixed-height,
+`overflow-y: auto` settings panel) rows can be compressed toward zero height. Add both
+via `className` when you drop them into a scrolling column.
+
+**8. Every row draws a bottom border, including the last one.** Suppress it on the final
+row via `className` if your container already has a border.
+
+**9. Cells truncate with no tooltip.** DATE and REWARD are fixed-width, `nowrap`,
+`overflow: hidden`, `text-overflow: ellipsis`, with **no `title` attribute**. The status
+badge behaves differently: the row forces it to `width: 5rem`, but `ScBadges` sets no
+`nowrap`, no `overflow: hidden` and no ellipsis — so a long status word **wraps onto a
+second line and grows the chip taller**, rather than truncating. Keep `status` to one
+short word.
+
+**10. Not a table row.** No `role="row"`/`cell`, no `<td>`. Cells are not associated with
+`ScReferralTableHeader`'s labels for assistive tech.
+
+**11. `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.
+
+---
+
+## 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 this row loop — sits inside a
+`{/* Referral History section commented out … */}` comment:
+
+```tsx
+// npm-components  packages/settings/src/settings-content.tsx:1013  (inside a commented-out block)
+<ScReferralTableList
+  key={ref.id}
+  userEmail={ref.email}
+  date={ref.date}
+  status={ref.status}
+  points={ref.points}
+/>
+```
+
+Note that the parked call site omits `userName` — Gotcha 1 — so uncommenting it as-is
+would ship "Chris Hemsworth" on every row, against a local `REFERRALS` demo array.
+
+Where it belongs: **Settings → Referral**, desktop, under `<ScReferralTableHeader />`
+and the "Referral History" label. CXO reaches that screen through `@streamoid/settings`,
+so no CXO-side change is needed.
+
+---
+
+## Related
+
+- `ScReferralTableHeader` — the header strip that defines this row's widths; always
+  render it above.
+- `ScProfile` — the identity cell; use it directly when you need a real avatar.
+- `ScBadges` — the status chip; use it directly when the status needs a colour.
+- `ScReferralCardMobile` — the mobile form of the same data.
+- `ScTableList` / `ScBillingHistoryTableList` / `ScBillingLogsTableList` /
+  `ScCatalogixStoreTableList` — the other domain rows, same header+row pattern.

package/dist/docs/ScRole.md

@@ -0,0 +1,226 @@
+---
+component: ScRole
+package: "@streamoid/ui"
+category: profile
+status: stable
+renders: div
+tags: [role, admin, member, permission, pill, badge, team, chip]
+related: [ScRoleMobile, ScBadges, ScAccess, ScTableList, ScWorkspaceSwitchCard]
+do_not_confuse_with: [ScBadges, ScRoleMobile, ScAccess, ScSelectionPill, ScTaxonomyPill]
+used_by: [cxo]
+---
+
+# ScRole
+
+**The admin/member role pill.** A fixed 80 × 40 chip: blue (`fill-info-soft` +
+`border-info` + `text-and-icons-infocont`) for `admin`, neutral grey for `member`.
+Two types, one optional label override, nothing else. It is a **display** chip — it
+is not a picker and it does not select anything.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are showing someone's role in a team table or workspace
+  row and want the standard admin-vs-member colour coding.
+- **Don't reach for it when:** you need an arbitrary status chip (→ `ScBadges`), a
+  per-capability permission row (→ `ScAccess`), a role *picker* (→ `ScSelect` /
+  `ScTabField`), or the mobile chip (→ `ScRoleMobile`).
+- **Four things that will bite you:**
+  1. `type` defaults to **`"admin"`** — the blue one. Forget it and everyone is an
+     admin.
+  2. The box is a **hardcoded 5rem × 2.5rem** (80 × 40) with `justify-content: center`
+     and no `overflow` guard. A `label` longer than ~"Member" overflows the pill.
+  3. `label` is optional and derived from `type` — but only for the two known types.
+  4. Only `"admin"` and `"member"` have styles. Any other string falls through to the
+     base (**admin-blue**) skin.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScRole } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScRole type="member" />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `type` | `"admin"` \| `"member"` | `"admin"` | ⚠️ Real default, and it is the **blue admin** skin. Drives colour **and** the derived label. |
+| `label` | `string` | `type === "admin" ? "Admin" : "Member"` | Visible text. Falls back via `??`, so `label=""` renders an **empty pill** (empty string is not nullish). |
+| `className` | `string` | – | Appended (concatenated unconditionally — a literal `undefined` class when omitted). |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `style`, `onClick`, `title`, `aria-*`, `data-*` spread onto the root div. No button semantics. |
+
+### What each `type` renders
+
+| `type` | Background | Border | Text |
+|---|---|---|---|
+| `"admin"` (base rule) | `--alias-fill-info-soft` | `--alias-border-info` | `--alias-text-and-icons-infocont` |
+| `"member"` | `--alias-fill-neutral-neutral` | `--alias-border-strong` | `--alias-text-and-icons-tertiary` |
+
+Both are `text-xs/regular`, `radius-xl`, 1px border, `0.5rem 0.75rem` padding, and
+the box is fixed at 80 × 40 regardless.
+
+### Recipes
+
+```tsx
+// Team table row (the standard host idiom)
+<ScRole
+  type={member.permissions.role}                 // typed "admin" | "member"
+  label={member.permissions.role === "admin" ? "Admin" : "Member"}
+  className="shrink-0"
+/>
+
+// Normalising an untyped role string from an API
+const role = raw === "admin" ? "admin" : "member";
+<ScRole type={role} />
+
+// Wider pill for a longer label — the 80px is a class rule, so inline style wins
+<ScRole type="member" label="Contributor" style={{ width: "auto", minWidth: "5rem" }} />
+```
+
+---
+
+## 2. Where to use it
+
+- **Team / member tables** — CXO's Teams screen and the shared
+  `@streamoid/settings` Teams + Organization tabs render one per row.
+- **`ScTableList`** composes one internally (with **no props**, so it shows the
+  default "Admin" — see Gotcha 5).
+- **Workspace rows in the switch modal** — `StreamoidWorkspaceSwitcher` renders it
+  with an explicit `style={{ width: 80 }}`.
+
+Its mobile twin `ScRoleMobile` covers the responsive surface.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The value is genuinely the admin/member distinction and you want the product-wide
+  blue/grey coding.
+- The chip sits in a fixed-width table column — the hardcoded 80px is a feature there.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Any other status, count or tag chip | `ScBadges` (`variant` default/success/warning/error/info, `styleVariant` solid/opaque) |
+| Per-capability permission display (read/write per module) | `ScAccess` |
+| **Choosing** a role in a form | `ScSelect`, `ScTabField` or `ScRadio` — this chip has no selected state |
+| A segmented filter the user clicks | `ScSelectionPill` / `ScSelectionPillGroup` |
+| A taxonomy/tree node chip | `ScTaxonomyPill` |
+| The mobile role chip | `ScRoleMobile` |
+| A role line inside an identity row | `ScWorkspace`'s `userRole` (plain tertiary text, no pill) or `ScWorkspaceSwitchCard`'s `role` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScBadges` — free `text` + 5 semantic variants + solid/opaque, width fits content | `ScRole` is role-only with a fixed 80px box |
+| `ScRoleMobile` — the mobile twin; prop is **`role`**, not `type`, and it takes no `label` | different prop names; don't swap blindly |
+| `ScAccess` — permission/capability row | `ScRole` is one summary chip |
+| `ScSelectionPill` — interactive segmented pill with `aria-pressed` | `ScRole` is not interactive |
+
+Note the prop-name trap across the family: **`ScRole` uses `type`**,
+**`ScRoleMobile` uses `role`**, and **`ScWorkspaceSwitchCard` / `ScWorkspaceCard` use
+`role` as a free string**.
+
+---
+
+## 4. Why to use it
+
+- **The two skins are a tokenised pair.** Admin uses the full info triplet
+  (`fill-info-soft` / `border-info` / `text-and-icons-infocont`) and member the
+  neutral triplet, so both stay legible in light and dark. A hand-rolled blue chip is
+  a classic light-mode contrast failure.
+- **Role colour means one thing everywhere.** Admin = info blue across CXO's teams
+  table, the settings package and the workspace modal. (Note `ScWorkspaceSwitchCard`
+  deliberately breaks this: it paints admin **warning-amber** and member info-blue.)
+- **Fixed geometry keeps table columns aligned** without a width prop at every call
+  site.
+- **Label override without losing the skin** — `label` lets you localise or relabel
+  ("Owner") while keeping the admin colours.
+
+---
+
+## Gotchas
+
+**1. `type` defaults to `"admin"`.** The base CSS rule *is* the admin skin, so
+omitting `type` paints a blue "Admin" pill.
+
+```tsx
+// WRONG — everyone is an Admin
+<ScRole />
+
+// RIGHT
+<ScRole type={member.role} />
+```
+
+**2. Unknown `type` values silently render as admin.** `styles["type-" + type]`
+resolves to `undefined` for anything else, leaving only the base rule.
+
+```tsx
+// WRONG — "owner" is a type error; cast past it and you get the blue admin skin
+<ScRole type={"owner" as "admin"} />
+
+// RIGHT — normalise first, relabel with `label`
+<ScRole type="admin" label="Owner" />
+```
+
+**3. The pill is a hardcoded 80 × 40 with no overflow guard.** `.scRole` sets
+`width: 5rem; height: 2.5rem` and `.role` has no `overflow`/`ellipsis`. A long
+`label` spills outside the border. Override `width` inline if you must relabel.
+
+**4. `label=""` renders an empty pill.** The fallback is `label ?? derived`, and `""`
+is not nullish. Pass `undefined` to get the derived label.
+
+**5. `ScTableList` renders `<ScRole />` with no props** — every row of that table
+shows "Admin" until the row component is given a role prop. If you are using
+`ScTableList` for a real member list, this is a DS gap to raise, not something you can
+fix from the call site.
+
+**6. It is a `<div>` with props spread.** `onClick` fires but there is no `role`,
+`tabIndex`, keyboard activation or focus ring. It is not a picker; don't make it one.
+
+**7. Trailing space in the text node** (`{displayLabel} `) — `trim()` before
+asserting.
+
+**8. `className` is concatenated unconditionally** → `class="scRole undefined type-admin"`.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/teams-content.tsx:604
+<ScRole
+  type={member.permissions.role}
+  label={member.permissions.role === "admin" ? "Admin" : "Member"}
+  className="shrink-0"
+/>
+```
+
+The same call exists in the shared settings package
+(`packages/settings/src/teams-content.tsx:588` and
+`packages/settings/src/organization-content.tsx:172`), which is what CXO's desktop
+Settings actually renders.
+
+---
+
+## Related
+
+- `ScRoleMobile` — the mobile twin (prop is `role`, no `label`).
+- `ScBadges` — the general-purpose chip for anything that is not a role.
+- `ScAccess` — per-capability permission row.
+- `ScTableList` / `ScTableHeader` — the team table this chip lives in.
+- `ScWorkspaceSwitchCard` — shows a role too, but as coloured text (admin = amber), not this pill.