@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScTabSwitcher.md

@@ -0,0 +1,307 @@
+---
+component: ScTabSwitcher
+package: "@streamoid/ui"
+category: layout
+status: stable
+renders: div
+tags: [segmented, tab-switcher, toggle, view-switch, 2-tab, 3-tab, slots, container]
+related: [ScTabComp, ScTabField, ScTabs, ScSettingsTabComp, ScSelectionPillGroup]
+do_not_confuse_with: [ScTabs, ScTabComp, ScTabField, ScSettingsTabComp, ScSelectionPillGroup]
+used_by: [cxo, photogenix, catalogix, artifax]
+---
+
+# ScTabSwitcher
+
+**The bordered shell around a 2–5 way segmented control.** It draws the rounded
+`surface-base` track with a hairline border and 4px padding, then renders whatever you
+put in its `component` … `component5` slots. It holds **no state**: each `ScTabComp`
+child owns its own `active` and `onClick`.
+
+## TL;DR for agents
+
+- **Reach for it when:** you have a compact 2–5 way view toggle and want the standard
+  track: theme switcher, Active/Pending, grid/list, Fast/Pro.
+- **Don't reach for it when:** the tab list is dynamic or longer than five
+  (→ `ScTabs`), it's a settings underline strip (→ `ScSettingsTabComp`), or it's a
+  labelled form field (→ `ScTabField`, which wraps this for you).
+- **Four things that will bite you:**
+  1. **Empty slots are not empty.** A missing `component` renders a *default*
+     `ScTabComp` — a home icon, and the first one is `active="true"`.
+  2. `tabCount` is a **string** (`"2"`…`"5"`) and it **gates** the slots:
+     `component3` is dropped unless `tabCount` is `"3"`+.
+  3. Children you supply need **`style={{ flex: 1 }}`** or the tabs come out unequal.
+  4. `scTabCompicon` / `scTabCompactive` / `scTabComptype` are accepted by the type
+     and **completely ignored** — Figma leftovers.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScTabSwitcher, ScTabComp } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScTabSwitcher
+  tabCount="2"
+  component={
+    <ScTabComp text="Active" type="text-only"
+      active={tab === "active" ? "true" : "false"}
+      onClick={() => setTab("active")} style={{ flex: 1 }} />
+  }
+  component2={
+    <ScTabComp text="Pending" type="text-only"
+      active={tab === "pending" ? "true" : "false"}
+      onClick={() => setTab("pending")} style={{ flex: 1 }} />
+  }
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `tabCount` | `"2"` \| `"3"` \| `"4"` \| `"5"` | `"2"` | ⚠️ A **string**. Controls how many slots render — slots above it are dropped. Applies **no styling** (see Gotcha 5). |
+| `component` | `JSX.Element` | ⚠️ a default `ScTabComp` with `active="true"` and `SiconHome` | Slot 1. Always rendered. |
+| `component2` | `JSX.Element` | ⚠️ a default `ScTabComp` with `SiconHome` | Slot 2. Always rendered. |
+| `component3` | `JSX.Element` | ⚠️ a default `ScTabComp` with `SiconHome` | Slot 3. Rendered only when `tabCount` is `"3"`/`"4"`/`"5"`. |
+| `component4` | `JSX.Element` | ⚠️ a default `ScTabComp` with `SiconHome` | Slot 4. Rendered only when `tabCount` is `"4"`/`"5"`. |
+| `component5` | `JSX.Element` | ⚠️ a default `ScTabComp` with `SiconHome` | Slot 5. Rendered only when `tabCount` is `"5"`. |
+| `scTabCompicon` | `JSX.Element` | – | **Ignored.** Destructured to `_scTabCompicon` and dropped. |
+| `scTabCompactive` | `string` | – | **Ignored.** |
+| `scTabComptype` | `string` | – | **Ignored.** |
+| `className` | `string` | – | Appended after the internal classes. Hosts use it for `w-full`. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the track div: `style`, `role="tablist"`, `aria-label`, `data-*`. |
+
+### What renders for each `tabCount`
+
+| `tabCount` | Slots rendered | Slots silently dropped |
+|---|---|---|
+| `"2"` (default) | `component`, `component2` | 3, 4, 5 |
+| `"3"` | + `component3` | 4, 5 |
+| `"4"` | + `component4` | 5 |
+| `"5"` | all five | — |
+
+### Recipes
+
+```tsx
+// Three icon tabs, full width (Photogenix / Artifax theme switcher)
+<ScTabSwitcher
+  tabCount="3"
+  className="w-full"
+  role="tablist"
+  aria-label="Theme"
+  component={<ScTabComp type="icon-only" style={{ flex: 1 }}
+    active={theme === "system" ? "true" : "false"} onClick={() => setTheme("system")}
+    icon={<SiconSystem className="w-5 h-5"
+      color={theme === "system" ? "var(--alias-text---icons-inverse)" : "var(--alias-text---icons-muted)"} />} />}
+  component2={<ScTabComp type="icon-only" style={{ flex: 1 }}
+    active={theme === "light" ? "true" : "false"} onClick={() => setTheme("light")}
+    icon={<SiconLight className="w-5 h-5"
+      color={theme === "light" ? "var(--alias-text---icons-inverse)" : "var(--alias-text---icons-muted)"} />} />}
+  component3={<ScTabComp type="icon-only" style={{ flex: 1 }}
+    active={theme === "dark" ? "true" : "false"} onClick={() => setTheme("dark")}
+    icon={<SiconDark className="w-5 h-5"
+      color={theme === "dark" ? "var(--alias-text---icons-inverse)" : "var(--alias-text---icons-muted)"} />} />}
+/>
+
+// Shrink-wrapped in a header row (it stretches by default — wrap it)
+<div className="inline-flex">
+  <ScTabSwitcher tabCount="2" component={…} component2={…} />
+</div>
+
+// Driving both slots from one array (do NOT exceed tabCount)
+<ScTabSwitcher
+  tabCount="2"
+  component={renderTab(views[0])}
+  component2={renderTab(views[1])}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **Sidebar footers** — the light/dark/system theme switcher in Photogenix's
+  `Sidebar`, Artifax's `DashboardSidebar`, and the DS's own `ScProfilePopup` /
+  `ScProfileOptions`.
+- **Table/list header rows** — CXO teams & organization (Active/Pending), Catalogix
+  PLP views.
+- **Inspector panels** — Photogenix retouch/reference views, Catalogix's text
+  attribute editor.
+- **Inside `ScTabField`** — the DS field wrapper composes one for you.
+
+All four host apps use it; it's part of the universal core.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The control has **2–5 fixed** segments known at author time.
+- You want the standard bordered track (radius `xl`, 0.5px `border-divider`,
+  `surface-base` fill) instead of hand-rolling it.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| 6+ segments, or segments from data | `ScTabs` |
+| A single tab cell on its own | `ScTabComp` standalone (no track) |
+| A labelled segmented control inside a form | `ScTabField` — it wraps this + two `ScTabComp`s |
+| Settings / mobile-settings underline strip | `ScSettingsTabComp` |
+| Accessible segmented control (real buttons + `aria-pressed`) | `ScSelectionPillGroup` |
+| Pills whose selected state is a dark fill (Catalogix curation look) | `ScSelectionPillGroup` |
+| Two plain actions side by side | two `ScButton`s |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScTabs` — data-driven, unbounded, borderless pill row | `ScTabSwitcher` is a fixed 2–5 slot bordered track |
+| `ScTabField` — already contains a switcher + a field label | Don't nest a switcher inside your own label markup |
+| `ScSelectionPillGroup` — owns the active value and gives you `onChange` | `ScTabSwitcher` owns nothing; each child tracks itself |
+| `ScSettingsTabComp` — underline tabs, no track | different visual family entirely |
+
+### The tab family at a glance
+
+| Component | Shape | Selection API | Root | Spreads DOM props? |
+|---|---|---|---|---|
+| `ScTabSwitcher` | 2–5 slot bordered track | none — children own it | `div` | ✅ |
+| `ScTabComp` | one tab cell | `active="true" \| "false"` (strings) | `div` | ✅ |
+| `ScTabs` | N pills, data-driven | `activeTab` + `onClickTab(value)` | `div` | ❌ |
+| `ScTabField` | field label + 2-tab switcher | `activeTab` + `onTabChange` | `div` | ❌ |
+| `ScSettingsTabComp` | underline tab | `active` (boolean) | `div` | ❌ |
+| `ScSelectionPillGroup` | segmented pills | `value` + `onChange` | `div` of `button`s | ✅ |
+
+---
+
+## 4. Why to use it
+
+- **The track is the part everyone gets wrong.** Radius `--radius-xl`, 0.5px
+  `--alias-border-divider`, `--alias-surface-base` fill, `--spacing-xs` padding,
+  zero gap — five values that must match the theme switcher in four apps.
+- **Slots, not data.** Because each segment is a full element, one segment can carry a
+  tooltip wrapper, a different icon set, or a disabled state without the container
+  needing to know — which is why Photogenix can wrap each tab in its own `Tooltip`.
+- **Stateless by design.** Selection stays in your store; there is no internal state to
+  desync from a URL param or a persisted theme.
+- **`align-self: stretch` + `flex-shrink: 0`** means it fills a sidebar column without
+  width plumbing and won't collapse in a constrained flex parent.
+
+---
+
+## Gotchas
+
+**1. Missing slots render placeholder tabs.** `component`…`component5` each fall back
+to a default `ScTabComp` with `SiconHome`; slot 1's fallback is also `active="true"`.
+
+```tsx
+// WRONG — renders your tab plus a second, home-icon "Tab"
+<ScTabSwitcher tabCount="2" component={<ScTabComp text="Active" style={{ flex: 1 }} />} />
+
+// RIGHT — fill every slot up to tabCount
+<ScTabSwitcher
+  tabCount="2"
+  component={<ScTabComp text="Active" type="text-only" style={{ flex: 1 }} />}
+  component2={<ScTabComp text="Pending" type="text-only" style={{ flex: 1 }} />}
+/>
+```
+
+**2. `tabCount` gates the slots — and it's a string.**
+
+```tsx
+// WRONG — component3 never renders (tabCount defaults to "2")
+<ScTabSwitcher component={a} component2={b} component3={c} />
+
+// ALSO WRONG — numeric literal is a type error
+<ScTabSwitcher tabCount={3} … />
+
+// RIGHT
+<ScTabSwitcher tabCount="3" component={a} component2={b} component3={c} />
+```
+
+**3. Custom children need `style={{ flex: 1 }}`.** The `flex: 1; align-self: unset`
+override is applied through an internal class that only the *default* children get.
+Without it your tabs size to their content and the track looks lopsided. Every host
+call site passes it.
+
+**4. Three props are dead.** `scTabCompicon`, `scTabCompactive`, `scTabComptype` exist
+only so old Figma-generated call sites still typecheck. They are destructured into
+`_`-prefixed locals and never used. Do not try to configure children through them.
+
+**5. `tabCount` applies no CSS.** The component computes
+`styles["tab-count-" + tabCount]`, but the stylesheet defines no `.tab-count-*` rules —
+so the class resolves to `undefined` and lands in the class string as the literal text
+`"undefined"`. `tabCount` is purely a render-count switch.
+
+**6. It stretches.** `align-self: stretch` on the root means a flex-column parent makes
+it full width. Wrap it in an `inline-flex` container when it should shrink-wrap
+(Photogenix's `QualityToggle` does exactly that).
+
+**7. No `role`, no keyboard, no roving tabindex.** The track is a plain div and the
+children are divs. Add `role="tablist"` here and `role="tab"`/`aria-selected` on the
+children if the control needs to be accessible — props are spread on both, so it
+compiles.
+
+**8. `className` is concatenated unguarded**; omitting it puts `"undefined"` in the
+class list.
+
+**9. `ScTabField` only wires slots 1 and 2.** If you pass it three tabs it sets
+`tabCount="3"` but leaves `component3` unset — so the third tab renders as the home-icon
+placeholder. Use `ScTabSwitcher` directly for 3+.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/teams-content.tsx:1171
+<ScTabSwitcher
+  tabCount="2"
+  component={
+    <ScTabComp
+      text="Active"
+      type="text-only"
+      active={activeTab === "active" ? "true" : "false"}
+      onClick={() => setActiveTab("active")}
+      style={{ flex: 1 }}
+    />
+  }
+  component2={
+    <ScTabComp
+      text="Pending"
+      type="text-only"
+      active={activeTab === "pending" ? "true" : "false"}
+      onClick={() => setActiveTab("pending")}
+      style={{ flex: 1 }}
+    />
+  }
+/>
+
+// photogenix_v2  dashboard/client/src/components/layout/Sidebar.tsx:997
+<ScTabSwitcher tabCount="3" className="w-full"
+  component={<ScTabComp icon={<SiconSystem className="w-5 h-5" … />} active={…} type="icon-only" onClick={() => setTheme("system")} style={{ flex: 1 }} />}
+  component2={…}
+  component3={…}
+/>
+```
+
+---
+
+## Related
+
+- `ScTabComp` — the tab cell that goes in the slots; read its README for the
+  `active="true"` string trap.
+- `ScTabField` — labelled form field that composes this with two `ScTabComp`s.
+- `ScTabs` — data-driven N-tab pill bar for 6+ or dynamic tabs.
+- `ScSettingsTabComp` — underline tab strip for settings screens.
+- `ScSelectionPillGroup` — accessible segmented control that owns its value.
+- `ScProfilePopup` / `ScProfileOptions` — DS components that already contain a
+  theme switcher built from this.

package/dist/docs/ScTableHeader.md

@@ -0,0 +1,261 @@
+---
+component: ScTableHeader
+package: "@streamoid/ui"
+category: tables
+status: stable
+renders: div
+tags: [table, header, column-headers, members, team, users, invites, pending, settings]
+related: [ScTableList, ScHeader, ScTableListMobile, ScCatalogixStoreHeader, ScBillingHistoryHeader, ScBillingLogsTableHeader, ScReferralTableHeader]
+do_not_confuse_with: [ScHeader, ScReferralTableHeader, ScCatalogixStoreHeader, ScBillingHistoryHeader, ScBillingLogsTableHeader, ScMobileTopNav, ScTableList]
+used_by: [cxo]
+---
+
+# ScTableHeader
+
+**The column-header strip of the Teams / members table.** A shaded flex row of five
+uppercase muted labels — USER, ROLE, ACCESS, INVITED BY, then either SIGNED ON or
+INVITE ACTION depending on `type` — rendered as five internal `ScHeader` cells on the
+exact widths the member-row markup uses. It is the *ruler*; the rows are the data.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building the Teams / members / pending-invites table
+  and need the header strip above the rows.
+- **Don't reach for it when:** you need a *different* table's header
+  (→ `ScCatalogixStoreHeader`, `ScBillingHistoryHeader`, `ScBillingLogsTableHeader`,
+  `ScReferralTableHeader`), a single sortable column label (→ `ScHeader`), or the
+  mobile members list, which has no header at all (→ `ScTableListMobile`).
+- **Four things that will bite you:**
+  1. **Every column label is hardcoded English.** There is no label prop. `type` is
+     the *only* prop besides `className`.
+  2. **`...props` is destructured but never spread.** `style`, `onClick`, `data-*`,
+     `aria-*` are silently dropped (and are type errors — the interface does not
+     extend `HTMLAttributes`). Wrap it in your own div instead.
+  3. The USER column shows a **descending chevron that is pure decoration** —
+     nothing is sortable, nothing is clickable.
+  4. It is **not a `<table>`**. No `role="table"`, no `columnheader`, no `aria-sort`.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScTableHeader } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScTableHeader />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `type` | `"default"` \| `"pending"` | `"default"` | Picks the fifth column: `default` → `SIGNED ON` (7.5rem), `pending` → `INVITE ACTION` (10rem). Nothing else changes. |
+| `className` | `string` | – | Appended after the internal class. The only escape hatch — there is no `style` prop. |
+
+That is the entire API. ⚠️ `...props` exists in the signature but is **never applied
+to the DOM**, and `IScTableHeaderProps` does not extend `React.HTMLAttributes`, so
+anything else you pass is both a compile error and a no-op.
+
+### What renders in each `type`
+
+| Column | `type="default"` | `type="pending"` | Width |
+|---|---|---|---|
+| USER | ✅ (with a down chevron) | ✅ (with a down chevron) | `flex: 1` |
+| ROLE | ✅ | ✅ | `5rem` |
+| ACCESS | ✅ | ✅ | `11.25rem` |
+| INVITED BY | ✅ | ✅ | `7.5rem` |
+| SIGNED ON | ✅ | — | `7.5rem` |
+| INVITE ACTION | — | ✅ | `10rem` |
+
+### The column contract (shared with the row markup)
+
+`ScTableList` — and every host's hand-rolled equivalent — matches these exactly:
+
+| Column | Header width | Row element | Row width |
+|---|---|---|---|
+| USER | `flex: 1` | `ScProfile` | `flex: 1` |
+| ROLE | `5rem` | `ScRole` | `5rem` (fixed inside `ScRole`) |
+| ACCESS | `11.25rem` | the access-icon group wrapper | `11.25rem` |
+| INVITED BY | `7.5rem` | a truncating text cell | `7.5rem` |
+| SIGNED ON | `7.5rem` | a truncating text cell | `7.5rem` |
+| INVITE ACTION | `10rem` | `ScPendingAction` | `10rem` (fixed inside `ScPendingAction`) |
+
+Both sides 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
+// Tabbed Teams table — the tab decides the fifth column, header and rows together
+<ScTableHeader type={activeTab === "active" ? "default" : "pending"} />
+{members.map((m) => (
+  <ScTableList
+    key={m.id}
+    variant={activeTab}                 // must track the header's `type`
+    userEmail={m.userEmail}
+    invitedBy={m.invitedBy}
+    signedOn={m.signedOn}
+  />
+))}
+// ...or your own row on the widths below — which is what both hosts actually do,
+// because ScTableList hardcodes name/role/access. See SC-tableList/README.md.
+
+// Make it sticky. You cannot pass `style`, so use className (or wrap it).
+<ScTableHeader className={styles.stickyHead} />
+/* .stickyHead { position: sticky; top: 0; z-index: 1; background: var(--alias-surface-base); } */
+
+// The wrapper form — what @streamoid/settings actually does, because `style` is dropped
+// (CXO's own teams-content.tsx renders it unwrapped, so its header scrolls away)
+<div style={{ position: "sticky", top: 0, zIndex: 1, backgroundColor: "var(--alias-surface-base)" }}>
+  <ScTableHeader type="pending" />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **Settings → Teams**, desktop only, on both tabs: Active members (`type="default"`)
+  and Pending invitations (`type="pending"`). This is the reason it exists.
+- Rendered directly by CXO's `teams-content.tsx`, and by the shared
+  `@streamoid/settings` Teams screen that ships into CXO's desktop settings.
+- Nothing else should use it: the column set *is* the workspace-member schema, baked
+  into the JSX with no label props.
+
+It composes five `ScHeader` cells and a background. Nothing else.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are rendering **workspace members or pending invites** 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 |
+|---|---|
+| Catalogix stores list header | `ScCatalogixStoreHeader` (and it takes label props, unlike this) |
+| Billing history table header (Invoice / Amount / Date / Action) | `ScBillingHistoryHeader` |
+| Credit & usage logs header (App / Activity / Used by / Date / Credits used / Balance) | `ScBillingLogsTableHeader` |
+| Referral history header (User / Date / Status / Reward) | `ScReferralTableHeader` |
+| One sortable column label with an asc/desc chevron | `ScHeader` — this strip is five of them, pre-labelled |
+| A genuinely generic N-column table header | Compose `ScHeader` cells yourself; the labels and widths here are hard-wired |
+| The mobile members list | `ScTableListMobile` — the mobile pattern is stacked cards with **no header row** |
+| A page title bar with actions | Neither this nor `ScHeader`; use your page layout + `ScButton` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScHeader` — a **single** column-label cell, `state="up" \| "down" \| "none"`, sort chevron | `ScTableHeader` is the whole strip and hardcodes the five labels |
+| `ScReferralTableHeader` — same shape, **referral** columns, no `type` prop at all | This one is the members table |
+| `ScCatalogixStoreHeader` — same shape but every label is a **prop**, plus `showAssets`/`showCreatedBy` gating | This one has no label props |
+| `ScTableList` — the *row* sibling, not the header | Different component; see its README before using it |
+| `ScMobileTopNav` — the mobile app bar | Unrelated; "header" here means column headers |
+
+---
+
+## 4. Why to use it
+
+- **It is the alignment contract.** The widths (`flex:1`, `5`, `11.25`, `7.5`, then
+  `7.5` or `10` rem), the `1.5rem` gap and the `1rem` inline padding exist in this
+  file and in the row file. Hand-rolling the header is how member tables shear apart
+  when someone adds a column.
+- **The `type` switch is the pending/active difference in one prop** — you don't
+  duplicate a five-column strip per tab.
+- **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.
+
+---
+
+## Gotchas
+
+**1. There are no label props.** "User", "Role", "Access", "Invited by", "Signed On"
+and "Invite action" are literal strings inside the component. Do not use it on a
+localised surface without changing the DS first.
+
+**2. `...props` is destructured and thrown away.** The root div receives only
+`className`. `style`, `onClick`, `id`, `data-*` and `aria-*` never reach the DOM.
+
+```tsx
+// WRONG — type error, and even with a cast the style is dropped
+<ScTableHeader type="pending" style={{ position: "sticky", top: 0 }} />
+
+// RIGHT — className, or your own wrapper
+<div style={{ position: "sticky", top: 0, zIndex: 1 }}>
+  <ScTableHeader type="pending" />
+</div>
+```
+
+**3. 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` is
+passed to any cell and there is no sort prop anywhere. Either wire sorting outside the
+component or expect users to click a dead chevron.
+
+**4. 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. If accessibility matters on the screen, add roles on your own wrapper and rows.
+
+**5. Not sticky, and it doesn't own the scroll.** Long member lists scroll the header
+away. Add `position: sticky; top: 0` **plus** an opaque `background` and a `z-index`
+(the rows are `position: relative`, so without one they paint over it).
+
+**6. `className` lands as the literal string `"undefined"` when omitted.** The class
+list is built by string concatenation (`scTableHeader undefined type-default`).
+Harmless in the browser, but exact-string class assertions in tests will fail.
+
+**7. `type` must be exactly `"default"` or `"pending"`.** The variant class is
+`styles["type-" + type]`; an unknown value yields the class `undefined` and the base
+widths, so you get the four common columns and no fifth one, silently.
+
+**8. `flex-shrink: 0` + `align-self: stretch`.** It expects to be a direct child of a
+`flex-direction: column` container that is at least as wide as
+`flex:1 + 5 + 11.25 + 7.5 + 7.5rem + gaps`. Below that the flexible USER column
+collapses first; the fixed columns never shrink and will overflow the container
+horizontally.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/teams-content.tsx:1225
+<ScTableHeader
+  type={activeTab === "active" ? "default" : "pending"}
+/>
+```
+
+The shared settings package does the same at
+`npm-components packages/settings/src/teams-content.tsx:1149`, there wrapped in a
+`position: sticky` div (Gotcha 5 / Gotcha 2). In both places the rows underneath are a
+local `TeamRow`, **not** `ScTableList` — see `SC-tableList/README.md` for why.
+
+---
+
+## Related
+
+- `ScTableList` — the DS row sibling for this header (read its README first; most of
+  its content is hardcoded and hosts hand-roll the row instead).
+- `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.
+- `ScRole`, `ScAccess`, `ScProfile`, `ScPendingAction` — the per-cell pieces the row
+  side of this contract is made of.
+- `ScTableListMobile` — the mobile members list; stacked cards, no header strip.
+- `ScReferralTableHeader` / `ScBillingHistoryHeader` / `ScBillingLogsTableHeader` /
+  `ScCatalogixStoreHeader` — the other domain-specific header/row pairs, same pattern.