@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScTableList.md

@@ -0,0 +1,301 @@
+---
+component: ScTableList
+package: "@streamoid/ui"
+category: tables
+status: stable
+renders: div
+tags: [table, row, members, team, users, invites, pending, settings, teams-row]
+related: [ScTableHeader, ScProfile, ScRole, ScAccess, ScPendingAction, ScTableListMobile, ScCatalogixStoreTableList]
+do_not_confuse_with: [ScTableHeader, ScTableListMobile, ScReferralTableList, ScBillingLogsTableList, ScBillingHistoryTableList, ScCatalogixStoreTableList]
+---
+
+# ScTableList
+
+**One row of the Teams / members table — the Figma export, largely un-parameterised.**
+It renders `ScProfile` + `ScRole` + two `ScAccess` icon groups + an "invited by" cell,
+then either a date (`variant="active"`) or `ScPendingAction` (`variant="pending"`), on
+the widths `ScTableHeader` defines.
+
+## TL;DR for agents
+
+- **Reach for it when:** you want a quick, visually correct members-table row and the
+  *only* real data you need to show is the user's **email**, who **invited** them, and
+  the **signed-on date**.
+- **Don't reach for it when:** you need to show the member's real **name**, real
+  **role**, real **avatar**, real **app access**, or wire the pending Cancel/Resend
+  buttons. None of that is reachable through props. Compose the row yourself from
+  `ScProfile` + `ScRole` + `ScAccess` + `ScPendingAction` under a `ScTableHeader` —
+  which is exactly what CXO and `@streamoid/settings` both do.
+- **Five things that will bite you:**
+  1. The display **name is always "Chris Hemsworth"**. `ScProfile` is rendered with
+     only `subText`, so its `name` default leaks into production.
+  2. The **role chip is always the blue "Admin"**. `ScRole` is rendered with no props.
+  3. The **access icons are hardcoded** — Artifax + Photogenix + Catalogix, then
+     User-add + Coins — regardless of the member's actual permissions.
+  4. `ScPendingAction`'s Cancel/Resend buttons have **no callbacks at all**; the row
+     exposes none either.
+  5. `{...props}` is spread **after** the internal `onClick`, so passing your own
+     `onClick` silently disables `onRowClick`.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScTableHeader, ScTableList } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+Every prop has a placeholder default, so the bare call renders — with demo data:
+
+```tsx
+<ScTableList
+  userEmail={member.userEmail}
+  invitedBy={member.invitedBy}
+  signedOn={member.signedOn}
+  variant="active"
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `userEmail` | `string` | `"chris@kepler.com"` | ⚠️ Placeholder default. Passed to `ScProfile` as `subText` — the **second** line of the profile cell. |
+| `invitedBy` | `string` | `"Rohan"` | ⚠️ Placeholder default. The INVITED BY cell (7.5rem, truncated, no tooltip). Also doubles as the `rowId` handed to `onRowClick` — see Gotcha 6. |
+| `signedOn` | `string` | `"Nov 9th, 2025"` | ⚠️ Placeholder default. Pre-formatted string; the row does no date formatting. **`variant="active"` only.** |
+| `variant` | `"active"` \| `"pending"` | `"active"` | Picks the fifth column: `active` → the `signedOn` date cell; `pending` → `ScPendingAction`. |
+| `hover` | `"false"` \| `"true"` | `"false"` | ⚠️ A **string** union, not a boolean. `"true"` force-paints the hover background (Figma parity / screenshots). Real `:hover` already works without it. |
+| `className` | `string` | – | Appended after the internal class. |
+| `onRowClick` | `(rowId: string, event: React.MouseEvent) => void` | – | Fires on the whole row. `rowId` is **`invitedBy`**, not an id. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div **after** `onClick` — so a passed `onClick` wins over `onRowClick`. |
+
+### What renders in each column — and what you can control
+
+| Column | Rendered by | Controllable? |
+|---|---|---|
+| USER (`flex: 1`) | `ScProfile subText={userEmail}` | ⚠️ **email only.** `name` falls back to `"Chris Hemsworth"`; `profileImage` falls back to the relative path `"profile-image0.png"` → a broken image in every host. |
+| ROLE (`5rem`) | `ScRole` with **no props** | ❌ Always the blue `Admin` chip. |
+| ACCESS (`11.25rem`) | two `ScAccess` groups | ❌ Group 1 = Artifax + Photogenix + Catalogix; group 2 = User-add + Coins. Always all five. |
+| INVITED BY (`7.5rem`) | plain text cell | ✅ `invitedBy` |
+| SIGNED ON (`7.5rem`, `variant="active"`) | plain text cell | ✅ `signedOn` |
+| INVITE ACTION (`10rem`, `variant="pending"`) | `ScPendingAction` | ❌ Renders "Cancel" + divider + "Resend" with **no handlers**. |
+
+### Recipes
+
+```tsx
+// The full table, as far as this component can take you
+<div style={{ display: "flex", flexDirection: "column" }}>
+  <ScTableHeader type={tab === "active" ? "default" : "pending"} />
+  {members.map((m) => (
+    <ScTableList
+      key={m.id}
+      variant={tab}
+      userEmail={m.userEmail}
+      invitedBy={m.invitedBy}
+      signedOn={m.signedOn}
+      onRowClick={() => openMember(m)}   // ignore the rowId arg; close over `m` instead
+    />
+  ))}
+</div>
+
+// Row click — use onRowClick, never onClick (see Gotcha 5)
+<ScTableList userEmail={m.userEmail} onRowClick={(_rowId, e) => { e.stopPropagation(); edit(m); }} />
+
+// What you should actually build when the data is real: the same contract, your own row.
+// Widths and gap must match ScTableHeader exactly: flex:1 / 5rem / 11.25rem / 7.5rem / 7.5rem|10rem,
+// gap 1.5rem, padding-inline 1rem.
+<div style={{ display: "flex", alignItems: "center", gap: "1.5rem", padding: "1.25rem 1rem" }}>
+  <div style={{ flex: 1, minWidth: 0 }}>{/* your avatar + name/email stack */}</div>
+  <ScRole type={m.role === "admin" ? "admin" : "member"} />   {/* type is "admin" | "member" only */}
+  {/* your permission-driven access icons, 11.25rem */}
+  <div style={{ width: "7.5rem" }}>{m.invitedBy}</div>
+  {tab === "active" ? <div style={{ width: "7.5rem" }}>{m.signedOn}</div> : <ScPendingAction /* see Gotcha 4 */ />}
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **Settings → Teams**, desktop, under a `ScTableHeader` — Active members and Pending
+  invitations. That is the only surface it was drawn for.
+- It composes `ScProfile`, `ScRole`, `ScAccess` ×2 and `ScPendingAction`. Those four are
+  the pieces to reuse when you outgrow the row (which happens as soon as the member's
+  name or role is real data).
+- The mobile equivalent of this screen is `ScTableListMobile` — a stacked card, no
+  shared width contract, and fully parameterised.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are prototyping or screenshotting the Teams table and want pixel-correct
+  chrome with zero wiring.
+- Your row genuinely only needs email + invited-by + date, and the Admin chip and the
+  five access icons happen to be right.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Real member data — name, role, avatar, per-app access | Your own row composed from `ScProfile` + `ScRole` + `ScAccess` + `ScPendingAction`, under `ScTableHeader`. See the third recipe. |
+| Working Cancel / Resend on a pending invite | `ScPendingAction` rendered directly, with the click hit-test described in Gotcha 4 |
+| Mobile members list | `ScTableListMobile` |
+| Referral history row (User / Date / Status / Reward) | `ScReferralTableList` |
+| Credit & usage log row | `ScBillingLogsTableList` |
+| Invoice row with a download action | `ScBillingHistoryTableList` |
+| Catalogix stores row | `ScCatalogixStoreTableList` |
+| Just the role chip, or just the access icons | `ScRole` / `ScAccess` on their own |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScTableHeader` — the header strip; takes `type`, not row data | `ScTableList` is one row |
+| `ScTableListMobile` — the members row for mobile: `name`, `email`, `imageUrl`, `role`, `accessIcons[]`, `permissionIcons[]` all real props | This desktop row hardcodes all of those |
+| `ScCatalogixStoreTableList` — the stores row, fully prop-driven, with `showAssets`/`showCreatedBy` gating | Different table, different schema |
+| `ScReferralTableList` — looks similar (a `ScProfile` + text cells) but its columns are Date / Status / Reward | Not interchangeable; the widths differ |
+
+---
+
+## 4. Why to use it
+
+- **It is the alignment contract's other half.** Its widths (`flex:1`, `5rem` from
+  `ScRole`, `11.25rem`, `7.5rem`, `7.5rem`/`10rem` from `ScPendingAction`), its
+  `1.5rem` gap and its `1rem` inline padding are the same numbers `ScTableHeader`
+  uses. Copy them if you hand-roll.
+- **The hover skin and the row rule are tokenised** — `--alias-fill-neutral-neutralplus`
+  on hover, `--alias-border-subtle` for the 1px bottom rule — so both survive the
+  light/dark flip.
+- **The two-column-collapse behaviour is already right:** the profile cell flexes and
+  truncates with an ellipsis while every other cell holds its width.
+- Honest caveat: beyond the chrome and those numbers, the value here is low. Read
+  Gotchas 1–4 before choosing it over composing the four child components yourself.
+
+---
+
+## Gotchas
+
+**1. The member's name is a hardcoded demo string.** `ScProfile` is rendered with only
+`subText={userEmail}`, so `ScProfile`'s own `name` default — `"Chris Hemsworth"` —
+renders on every row. There is no `userName` prop (`ScReferralTableList`, confusingly,
+*does* have one).
+
+```tsx
+// WRONG — you will ship "Chris Hemsworth" above every email
+<ScTableList userEmail={m.userEmail} />
+
+// RIGHT — compose the profile cell yourself
+<ScProfile name={m.name} subText={m.userEmail} profileImage={m.avatarUrl} style={{ flex: 1 }} />
+```
+
+**2. The avatar is a broken image.** `ScProfile`'s `profileImage` default is the
+relative path `"profile-image0.png"`, resolved against the current route, and the row
+gives you no way to override it. You get a broken-image glyph (and the `<img>` has no
+`alt`).
+
+**3. The role chip and the access icons are decoration.** `ScRole` gets no props →
+always the blue `Admin` chip, even for members. `ScAccess` gets a fixed icon set →
+Artifax, Photogenix, Catalogix, then User-add and Coins, for everyone. A row will
+happily claim a read-only member is an admin with access to all three apps.
+
+**4. `ScPendingAction` has no per-button callbacks.** Its own props are `className` plus
+the usual `React.HTMLAttributes<HTMLDivElement>` spread — there is no `onCancel` /
+`onResend`, and the two `ScButton`s inside are constructed internally with no `onClick`.
+So `variant="pending"` renders a Cancel and a Resend button that do nothing, and the row
+offers no `onCancel`/`onResend`. The working pattern (used by both hosts) is to render
+`ScPendingAction` yourself and hit-test the click against its first/last child:
+
+```tsx
+<ScPendingAction
+  onClick={(event) => {
+    event.stopPropagation();
+    const root = event.currentTarget as HTMLElement;
+    const target = event.target as HTMLElement;
+    const cancel = root.children.item(0) as HTMLElement | null;
+    const resend = root.children.item(root.children.length - 1) as HTMLElement | null;
+    if (cancel?.contains(target)) return onCancelInvite();
+    if (resend?.contains(target)) return onResendInvite();
+  }}
+/>
+```
+
+**5. Your `onClick` kills `onRowClick`.** The root is
+`<div onClick={…onRowClick…} {...props}>` — the spread comes last, so a passed
+`onClick` overwrites the internal handler.
+
+```tsx
+// WRONG — onRowClick never fires
+<ScTableList onClick={handle} onRowClick={handleRow} />
+
+// RIGHT — pick one
+<ScTableList onRowClick={handleRow} />
+```
+
+**6. `onRowClick`'s first argument is `invitedBy`, not an id.** Signature is
+`(rowId: string, event) => void` and the row calls `onRowClick(invitedBy, e)`. Ignore
+the argument and close over your own record.
+
+**7. `hover` is `"true"` / `"false"` as strings.** `hover={true}` is a type error;
+`hover="true"` force-paints the hover background permanently. Only use it for design
+parity — real `:hover` is already wired in CSS.
+
+**8. Placeholder defaults everywhere.** `invitedBy`, `signedOn` and `userEmail` all
+default to demo values, so a typo'd prop name renders plausible-looking fake data
+instead of failing. Check spelling against the props table.
+
+**9. Not a table row.** No `role="row"`/`cell`, no `<td>`. The cells are not associated
+with `ScTableHeader`'s labels for assistive tech.
+
+**10. 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.
+
+**11. Cells truncate with no tooltip.** INVITED BY and SIGNED ON are fixed-width,
+`nowrap`, `overflow: hidden`, `text-overflow: ellipsis`, and there is **no `title`
+attribute**. A long inviter name just disappears.
+
+**12. `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: **no consumer renders it, and that is deliberate.** Both Teams screens
+render `ScTableHeader` and then a *local* row, because of Gotchas 1–4:
+
+- `cxo-dashboard src/app/components/teams-content.tsx:530` — `function TeamRow(...)`,
+  which reuses `ScRole` (with real `type`/`label`), `ScPendingAction` (with the
+  hit-test from Gotcha 4) and a hand-built profile cell, on this component's widths.
+- `npm-components packages/settings/src/teams-content.tsx:514` — the same `TeamRow`,
+  in the shared settings package that ships into CXO desktop settings.
+
+Where it *belongs*: Settings → Teams, desktop, directly under
+`<ScTableHeader type="default" | "pending" />` — once `userName`, `profileImage`,
+`role`, an access-icons prop and `onCancelInvite`/`onResendInvite` are added to the DS,
+at which point both `TeamRow` copies can be deleted.
+
+---
+
+## Related
+
+- `ScTableHeader` — the header strip that defines this row's widths; always render it above.
+- `ScProfile` — the USER cell; pass `name` **and** `subText` **and** `profileImage` yourself.
+- `ScRole` — the role chip; `type="admin" | "member"` plus an optional `label` override
+  (fixed `5rem × 2.5rem`, which is where this row's ROLE width comes from).
+- `ScAccess` — one access-icon group; `component` / `component2` / `component3` +
+  `visibleSiconCatalogix` let you drive it from real permissions.
+- `ScPendingAction` — the Cancel/Resend pair (no per-button callbacks; see Gotcha 4).
+- `ScTableListMobile` — the mobile twin, and the fully prop-driven one.
+- `ScReferralTableList` / `ScBillingLogsTableList` / `ScBillingHistoryTableList` /
+  `ScCatalogixStoreTableList` — the other domain rows, same header+row pattern.

package/dist/docs/ScTableListMobile.md

@@ -0,0 +1,282 @@
+---
+component: ScTableListMobile
+package: "@streamoid/ui"
+category: mobile
+status: stable
+renders: div
+tags: [table, row, mobile, members, team, users, invites, teams, responsive, card]
+related: [ScTableList, ScTableHeader, ScProfileV2Mobile, ScRoleMobile, ScRole, ScAccess, ScMobileBottomAction]
+do_not_confuse_with: [ScTableList, ScTableHeader, ScReferralCardMobile, ScProfileV2Mobile, ScRoleMobile, ScRole]
+used_by: [cxo]
+---
+
+# ScTableListMobile
+
+**The members row for narrow screens — a two-line stacked card, not a table row.**
+Line 1 is name + email on the left with a 40px avatar (or initials) on the **right**;
+line 2 is a role badge on the left and up to two pill-shaped icon groups on the right.
+Unlike its desktop twin `ScTableList`, everything it shows is a real prop.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are rendering the Teams / members list on CXO mobile, or
+  a single member's summary card in a mobile drawer or popup.
+- **Don't reach for it when:** you're on desktop (→ `ScTableHeader` + your own row, see
+  `SC-tableList/README.md`), or you want the referral card (→ `ScReferralCardMobile`).
+- **Three things that will bite you:**
+  1. `name`, `email` and `role` all have **placeholder defaults** — forget one and you
+     ship "Chris Hemsworth / chris@kepler.com / Admin".
+  2. The role badge is a **fixed 64×32px blue info chip with no variants**. "Member"
+     is as blue as "Admin", and anything longer than ~7 characters overflows it.
+  3. `{...props}` is spread **after** `onClick={onRowClick}`, so passing your own
+     `onClick` silently replaces `onRowClick`. There is also **no `cursor: pointer`**
+     and no hover/press state — a tappable row looks inert.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScTableListMobile } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScTableListMobile
+  name={member.name}
+  email={member.userEmail}
+  role={member.permissions.role === "admin" ? "Admin" : "Member"}
+  onRowClick={() => openMember(member)}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `name` | `string` | `"Chris Hemsworth"` | ⚠️ Placeholder default. Line 1, medium 14px, truncates. Also the source of the initials fallback and the `<img alt>`. |
+| `email` | `string` | `"chris@kepler.com"` | ⚠️ Placeholder default. Line 2, regular 12px tertiary, truncates. |
+| `imageUrl` | `string` | – | Avatar `src`. When omitted, a 40px circle of **initials derived from `name`** is drawn instead (first letter of each space-separated word, uppercased, first 2 chars). |
+| `role` | `string` | `"Admin"` | ⚠️ Placeholder default. Free string, rendered in a fixed 64×32px blue info badge. **No variants** — see Gotcha 2. |
+| `accessIcons` | `JSX.Element[]` | – | First icon pill (app access). Each element is wrapped in a 20×20 span. The whole pill is **omitted when the array is empty or undefined**. |
+| `permissionIcons` | `JSX.Element[]` | – | Second icon pill (capabilities, e.g. invite / credits). Same rules. |
+| `onRowClick` | `(e: React.MouseEvent) => void` | – | Wired to the root's `onClick`. Takes the event only — no id (unlike `ScTableList`, which passes `invitedBy`). |
+| `className` | `string` | – | Appended after the internal class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div **after** `onClick` — a passed `onClick` wins over `onRowClick`. |
+
+### Layout at a glance
+
+| Region | Contents | Notes |
+|---|---|---|
+| `profileRow` | `name` / `email` stack (`flex: 1`, truncating) → avatar | ⚠️ Avatar is on the **right**. `ScProfile` (desktop) puts it on the left. |
+| avatar | `<img src={imageUrl} alt={name}>` **or** an initials circle | 40×40, `border-radius: full`, `object-fit: cover`, `overflow: hidden` |
+| `detailsRow` | role badge ← `space-between` → icon pills | Badge fixed 64×32; pills are `--alias-fill-neutral-neutral` at `radius-lg` |
+| root | `width: 100%`, `padding: 20px 16px`, `border-bottom: 0.5px` | Bottom rule on every card, including the last |
+
+### Recipes
+
+```tsx
+// The mobile members list — icons built from real permissions
+{members.map((m) => (
+  <ScTableListMobile
+    key={m.id}
+    name={m.name || m.userEmail.split("@")[0]}
+    email={m.userEmail}
+    role={m.permissions.role === "admin" ? "Admin" : "Member"}
+    accessIcons={[
+      ...(m.permissions.artifax    ? [<SiconArtifacts  key="a"  size={20} />] : []),
+      ...(m.permissions.photogenix ? [<SiconPhotogenix key="p"  size={20} />] : []),
+      ...(m.permissions.catalogix  ? [<SiconCatalogix  key="c"  size={20} />] : []),
+    ]}
+    permissionIcons={[
+      ...(m.permissions.canInviteUser ? [<SiconUserAdd key="u"  size={20} />] : []),
+      ...(m.permissions.canUseCredits ? [<SiconCoins   key="cr" size={20} />] : []),
+    ]}
+    onRowClick={() => handleMemberClick(m)}
+    className="w-full"
+  />
+))}
+
+// One member as the header of a detail drawer — non-interactive, custom rule
+<ScTableListMobile
+  name={member.name}
+  email={member.userEmail}
+  role="Member"
+  style={{ borderBottom: "0.5px solid var(--alias-border-subtle)", paddingBottom: "20px" }}
+/>
+
+// Give a tappable card an affordance — the DS supplies none
+<ScTableListMobile name={m.name} email={m.userEmail} onRowClick={open} className="cursor-pointer" />
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO mobile → Settings → Teams**, in both the members list and the pending-invites
+  list. There is **no mobile header strip** — the label/value pairing that
+  `ScTableHeader` provides on desktop is replaced by the card's own two-line layout.
+- **CXO mobile → pending-invite detail popup**, rendered once at the top as the
+  member summary, with `style` overriding the bottom rule.
+- It composes nothing from the DS — plain divs, an `<img>` and your icons. It does
+  **not** use `ScProfile`, `ScRole`, `ScAccess`, `ScProfileV2Mobile` or `ScRoleMobile`,
+  even though the last two are near-identical to the regions it inlines. That
+  duplication is why its role badge doesn't distinguish admin from member.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The viewport is narrow and a five-column table would be unusable.
+- You have real member data (name, email, role, permissions) — this component, unlike
+  `ScTableList`, actually accepts all of it.
+- You want the member summary card in a mobile drawer/popup to look identical to the
+  rows in the list behind it.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Desktop members table | `ScTableHeader` + your own row (see `SC-tableList/README.md`); `ScTableList` only if placeholder content is acceptable |
+| Referral entry on mobile | `ScReferralCardMobile` |
+| Just an avatar + name/email pair on mobile | `ScProfileV2Mobile` — same layout as this card's line 1, plus `dpPosition="left" \| "right"` |
+| A role chip that distinguishes admin from member | `ScRoleMobile` (`role="admin" \| "member"`, identical 64×32 box) on mobile, `ScRole` on desktop. This card's inline badge does not |
+| Sticky bottom "Invite user" action on the same screen | `ScMobileBottomAction` |
+| Referral / billing / stores rows | `ScReferralTableList`, `ScBillingLogsTableList`, `ScBillingHistoryTableList`, `ScCatalogixStoreTableList` (all desktop) |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScTableList` — the desktop members row. Hardcodes name, avatar, role and access icons; has `variant="active" \| "pending"` and `hover` | `ScTableListMobile` parameterises all of that but has **no** `variant` and no pending-action buttons |
+| `ScTableHeader` — the desktop column-header strip | Mobile has no header; don't try to pair one with these cards |
+| `ScReferralCardMobile` — the mobile card for the *referral* table | Different data, different layout |
+| `ScRoleMobile` — the standalone mobile role chip, `role="admin" \| "member"`, same 64×32 box | This card draws an equivalent badge inline and ignores `ScRoleMobile` entirely, so it has no member skin |
+| `ScProfileV2Mobile` — the same name/email/avatar block as line 1, but with `dpPosition` | This card's avatar is fixed to the **right**; `ScProfile` (desktop) puts it on the left |
+
+---
+
+## 4. Why to use it
+
+- **It is the only members row in the DS you can actually drive with data.** Name,
+  email, avatar, role and both icon groups are props; the desktop `ScTableList`
+  hardcodes every one of them.
+- **The truncation is already correct.** The name/email stack is `flex: 1; min-width: 0`
+  with `overflow: hidden; text-overflow: ellipsis`, so long emails ellipsise instead of
+  pushing the avatar off-screen — the single most common hand-rolled mobile row bug.
+- **Initials fallback for free.** No avatar URL still yields a filled circle rather
+  than a broken `<img>` (which is exactly what `ScTableList` ships).
+- **Empty icon pills disappear.** A member with no app access renders no pill at all,
+  instead of an empty grey rectangle.
+
+---
+
+## Gotchas
+
+**1. `name`, `email` and `role` default to demo values.** A typo'd prop name renders
+plausible fake data instead of failing.
+
+```tsx
+// WRONG — renders "Chris Hemsworth / chris@kepler.com / Admin"
+<ScTableListMobile userName={m.name} userEmail={m.userEmail} />
+
+// RIGHT
+<ScTableListMobile name={m.name} email={m.userEmail} role="Member" />
+```
+
+**2. The role badge has no variants and a fixed 64px width.** It is always the blue
+info skin (`fill-info-soft` / `border-infoplus`), so "Member", "Viewer" and "Admin" are
+visually identical. The text is `white-space: nowrap` inside a `width: 64px` flex box
+with no `overflow: hidden`, so anything longer than ~7 characters spills outside the
+badge outline. Keep `role` to one short word, or use `ScRole` in your own row.
+
+**3. Your `onClick` replaces `onRowClick`.** The root is
+`<div onClick={onRowClick} {...props}>` — the spread wins.
+
+```tsx
+// WRONG — onRowClick never fires
+<ScTableListMobile onClick={handle} onRowClick={handleRow} />
+
+// RIGHT
+<ScTableListMobile onRowClick={handleRow} />
+```
+
+**4. No tap affordance and no hover/active state.** No `cursor: pointer`, no
+`role="button"`, no `tabIndex`, no background change. Add `cursor-pointer` (and, if the
+row is a real control, `role="button"` + `tabIndex={0}` via `...props`) yourself.
+
+**5. Initials come from `name` only, and only the first two words.**
+`name.split(" ").map(n => n[0]).join("").toUpperCase().slice(0, 2)`. An email-derived
+name like `"chris.hemsworth"` yields `"C"`; `name=""` yields an empty circle. Pass
+`imageUrl` whenever you have one.
+
+**6. Icon arrays must already be sized.** Each element is wrapped in a 20×20 span but
+is **not** cloned or resized — pass `size={20}` (and a colour, since the card sets none
+on the pill contents) on every `Sicon*`.
+
+**7. Empty vs undefined matters.** `accessIcons={[]}` and `accessIcons={undefined}`
+both remove the pill entirely; there is no placeholder. Build the array with spreads
+(see the recipe) rather than pushing `null`s — a `null` element still renders an empty
+20×20 span.
+
+**8. Every card draws a 0.5px bottom border, including the last.** Override via
+`className`/`style` if your container already has one.
+
+**9. Hardcoded px, not rem.** Font sizes 14/12, avatar 40, badge 64×32 and icon 20 are
+literal pixels (some behind token fallbacks). It does not respond to root font scaling
+the way the desktop `rem`-based rows do.
+
+**10. `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
+
+```tsx
+// cxo-dashboard  src/app/components/mobile-teams-content.tsx:307
+<ScTableListMobile
+  key={member.id}
+  name={member.name || member.userEmail.split("@")[0]}
+  email={member.userEmail}
+  role={member.permissions.role === "admin" ? "Admin" : "Member"}
+  accessIcons={[
+    ...(member.permissions.artifax ? [<SiconArtifacts key="a" size={20} color={T.primary} />] : []),
+    ...(member.permissions.photogenix ? [<SiconPhotogenix key="p" size={20} color={T.primary} />] : []),
+    ...(member.permissions.catalogix ? [<SiconCatalogix key="c" size={20} color={T.primary} />] : []),
+  ]}
+  permissionIcons={[
+    ...(member.permissions.canInviteUser ? [<SiconUserAdd key="u" size={20} color={T.primary} />] : []),
+    ...(member.permissions.canUseCredits ? [<SiconCoins key="cr" size={20} color={T.primary} />] : []),
+  ]}
+  onRowClick={() => handleMemberClick(member)}
+  className="w-full"
+/>
+```
+
+Also rendered once as a detail-popup header at
+`cxo-dashboard src/app/components/mobile-teams-pending-popup.tsx:131`, there with no
+`onRowClick` and a `style` that replaces the bottom rule.
+
+---
+
+## Related
+
+- `ScTableList` — the desktop twin; read its README before choosing it (most of its
+  content is hardcoded).
+- `ScTableHeader` — the desktop column strip; deliberately absent on mobile.
+- `ScRoleMobile` — the mobile role chip with real admin/member variants; use it if the
+  badge here is too blunt. `ScRole` is its desktop equivalent.
+- `ScAccess` — the desktop icon-group equivalent of `accessIcons` / `permissionIcons`.
+- `ScProfileV2Mobile` — the name/email/avatar block on its own, with `dpPosition`;
+  `ScProfile` for the desktop, avatar-left form.
+- `ScMobileBottomAction` — the sticky footer action that usually sits below this list.
+- `@streamoid/icons` — `SiconArtifacts`, `SiconPhotogenix`, `SiconCatalogix`,
+  `SiconUserAdd`, `SiconCoins` are the icons these pills carry; see `packages/icons/ICONS.md`.