@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScPagination.md

@@ -0,0 +1,284 @@
+---
+component: ScPagination
+package: "@streamoid/ui"
+category: overlays
+status: stable
+renders: div > div > (SiconRight, input[type=number], SiconRight, span)
+tags: [pagination, pager, page, paging, offset, next, prev, table, list]
+related: [ScTableHeader, ScTableList, ScCatalogixStoreTableList, ScCounter, ScOnlyField]
+do_not_confuse_with: [ScCounter, ScTabs, ScOnlyField]
+used_by: [catalogix]
+required_props: [itemsCount, itemsPerPage, page, setPage, setOffsetValue, onPageChangeAction]
+---
+
+# ScPagination
+
+**The offset-based page stepper for tables.** A right-aligned row of
+`‹ [ 3 ] › of 17`: a numeric input clamped to `[1, maxPage]` between two chevrons,
+plus the derived total. It is fully controlled and it reports an **offset**, not a
+page — a direct port of Catalogix's local `Pagination`, so it wraps as a
+pass-through.
+
+## TL;DR for agents
+
+- **Reach for it when:** you have a server-paged table or list and you already hold
+  `page` + `offset` state and a refetch function.
+- **Don't reach for it when:** you want a numeric stepper in a form
+  (→ `ScCounter`), page-size selection (not provided), or numbered page links
+  (`1 2 3 …` — not this component).
+- **Five things that will bite you:**
+  1. **All six functional props are required.** No defaults, nothing optional
+     except `className`.
+  2. It reports an **offset** via `setOffsetValue((page - 1) * perPage)` *and*
+     separately calls `onPageChangeAction()`. `setPage` alone never refetches.
+  3. `maxPage` is **derived** from `itemsCount / itemsPerPage` — there is no
+     `totalPages` prop.
+  4. Typing commits on **blur**. There is no `keydown` handler, so **Enter does
+     nothing**.
+  5. Clearing the input and blurring commits a **negative offset**
+     (`(Number("") - 1) * perPage`). Guard your fetch.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScPagination } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+const [page, setPage] = useState<number | string>(1);
+const [offset, setOffset] = useState(0);
+
+<ScPagination
+  itemsCount={total}
+  itemsPerPage={PER_PAGE}
+  page={page}
+  setPage={setPage}
+  setOffsetValue={setOffset}
+  onPageChangeAction={() => refetch()}
+/>
+```
+
+### Props
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `itemsCount` | `number` | **yes** | Total rows on the server. `maxPage` is computed from this — `itemsCount % perPage ? floor(itemsCount / perPage) + 1 : itemsCount / perPage`. |
+| `itemsPerPage` | `number \| string` | **yes** | Parsed with `parseInt(String(v), 10) \|\| 1`, so `0`, `""` or `"all"` silently becomes **1**. |
+| `page` | `number \| string` | **yes** | The current page, 1-based. It is a `string` while the user is typing (see Gotcha 5). Renders straight into the input's `value`. |
+| `setPage` | `(page: number \| string) => void` | **yes** | Receives the **raw string** from typing (clamped to `1` / `maxPage` at the bounds) and a **number** from the arrows. |
+| `setOffsetValue` | `(offset: number) => void` | **yes** | The commit channel: `(page - 1) * perPage`. This is what your query should read. |
+| `onPageChangeAction` | `() => void` | **yes** | Called immediately after `setOffsetValue` on every commit. Your refetch. |
+| `className` | `string` | no | Appended after `.scPagination` (only when truthy). |
+
+No `...props` spread — anything else is a type error.
+
+### When each callback fires
+
+| Interaction | `setPage` | `setOffsetValue` | `onPageChangeAction` |
+|---|---|---|---|
+| Typing a digit | ✓ (raw string, clamped at the bounds) | — | — |
+| Blurring the input | — | ✓ `(Number(value) - 1) * perPage` | ✓ |
+| Pressing Enter | — | — | — (no keydown handler) |
+| `‹` at page > 1 | ✓ `p - 1` | ✓ `(p - 2) * perPage` | ✓ |
+| `›` at page < maxPage | ✓ `p + 1` | ✓ `p * perPage` | ✓ |
+| `‹` at page 1 / `›` at maxPage | — | — | — (silent no-op) |
+
+### What it actually renders
+
+```html
+<div class="scPagination {className}">        <!-- width:100%; display:flex; justify-content:flex-end -->
+  <div class="section">                        <!-- overflow:auto; 16px/1.375 --alias-text-and-icons-primary -->
+    <SiconRight size=24 class="leftArrow" />   <!-- the SAME icon, CSS-rotated 180deg -->
+    <span class="page"><input type="number" pattern="\d*" /></span>
+                                               <!-- 60px wide, centered, radius 16px,
+                                                    --alias-surface-canvasbase, spinners removed -->
+    <SiconRight size=24 />
+    <span class="pageCount">of {maxPage}</span>
+  </div>
+</div>
+```
+
+### Recipes
+
+```tsx
+// Offset-driven query — the intended wiring
+const [page, setPage] = useState<number | string>(1);
+const [offset, setOffset] = useState(0);
+const { data, refetch } = useProducts({ limit: PER_PAGE, offset });
+
+<ScPagination
+  itemsCount={data?.total ?? 0}
+  itemsPerPage={PER_PAGE}
+  page={page}
+  setPage={setPage}
+  setOffsetValue={setOffset}
+  onPageChangeAction={refetch}
+/>
+
+// Guard the negative offset an emptied input produces
+setOffsetValue={(o) => setOffset(Math.max(0, o))}
+
+// If your query keys off `offset`, you may not need onPageChangeAction to do work
+onPageChangeAction={() => {}}   // still required — pass a no-op
+
+// Reset to page 1 whenever filters change (the component won't do it for you)
+useEffect(() => { setPage(1); setOffset(0); }, [filters]);
+```
+
+---
+
+## 2. Where to use it
+
+- **Under a paged table** — after `ScTableHeader` + `ScTableList` rows, or
+  `ScCatalogixStoreHeader` + `ScCatalogixStoreTableList`.
+- **Under a paged card/product grid.**
+- **Catalogix** wraps it as `app/components/Pagination`, which adds the outer
+  `margin: 24px 24px 18px 0` and passes every prop straight through. Inside
+  Catalogix, use the wrapper. Catalogix is the only host consumer.
+
+The root is `width: 100%; justify-content: flex-end`, so it right-aligns itself
+inside whatever block you put it in — do not wrap it in your own flex row expecting
+to control alignment.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Paging happens **on the server** and your query takes a `limit` + `offset`.
+- The user needs to **jump** to a page number, not just step one at a time.
+- The list is long enough that page count matters, and you already have the total.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A bounded numeric input in a form (quantity, batch size) | `ScCounter` |
+| A bare number input with no stepper chrome | `ScOnlyField` |
+| Switching between views/sections | `ScTabs` / `ScTabSwitcher` / `ScSelectionPillGroup` |
+| Infinite scroll / "Load more" | no DS component — build it app-local |
+| Numbered page links (`1 2 3 … 17`) | not this component; it's a single input + arrows |
+| Choosing the page size ("20 / 50 / 100 per row") | `ScSelect` beside it; `itemsPerPage` here is read-only input |
+| Client-side paging of an in-memory array | works, but you must derive your slice from the offset yourself |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScCounter` — the −/value/+ stepper with clamp bounds, for forms | `ScPagination` reports an *offset* and calls a refetch |
+| `ScOnlyField` — a plain input | This input is pre-wired with clamping and blur-commit |
+| Catalogix's `app/components/Pagination` — the wrapper that adds the page margin | `ScPagination` is the bare DS part |
+
+---
+
+## 4. Why to use it
+
+- **The clamp and offset arithmetic are in one place.** Typing `999` snaps to
+  `maxPage`, typing `0` snaps to `1`, and the offset is always
+  `(page - 1) * perPage`. Every app that recomputed that inline got the off-by-one
+  wrong at least once.
+- **`maxPage` handles the partial last page.** `itemsCount % perPage ? floor(…) + 1
+  : itemsCount / perPage` — 401 items at 100/page is 5 pages, not 4.
+- **The number input is already de-chromed and tokenised.** Native spinners removed
+  (`-webkit-appearance: none`, `-moz-appearance: textfield`), focus outline removed,
+  60px wide, centred, on `--alias-surface-canvasbase` with primary text — so it
+  reads as a pill, not a form field, in both themes.
+- **Prop-compatible with the Catalogix original,** which is why the migration was a
+  pass-through wrapper rather than a rewrite of every table.
+
+---
+
+## Gotchas
+
+**1. Six required props.** There are no defaults. Omitting any is a type error, and
+`setPage` without `setOffsetValue` + `onPageChangeAction` gives you a pager that
+changes the number and never fetches anything.
+
+**2. It reports an offset, not a page.** Your data layer must take `offset`. If it
+takes `page`, convert: `page = offset / perPage + 1`.
+
+**3. Enter does nothing.** Commit is `onBlur` only — there is no `onKeyDown`. Users
+who type a number and hit Enter see nothing happen until they click away. Consider
+wrapping the input's container with your own Enter handling if that matters, or tell
+users to use the arrows.
+
+**4. Emptying the input commits a negative offset.** `handlePageValue` passes `""`
+straight through to `setPage`, then `commit` computes
+`(Number("") - 1) * perPage === -perPage`. Clamp in your setter:
+`setOffsetValue={(o) => setOffset(Math.max(0, o))}`.
+
+**5. `page` is `number | string` for a reason.** Typing yields the raw string
+(`"12"`), the arrows yield a number. Never do arithmetic on it without `Number()`,
+and type your state as `number | string`.
+
+```tsx
+// WRONG — string concatenation on some renders
+const nextOffset = (page - 1) * PER_PAGE;
+
+// RIGHT
+const nextOffset = (Number(page) - 1) * PER_PAGE;
+```
+
+**6. `itemsPerPage` falls back to 1, silently.** `parseInt(String(v), 10) || 1`, so
+`0`, `undefined`-coerced values or `"all"` make `maxPage === itemsCount`. Never pass
+a sentinel value here.
+
+**7. `itemsCount = 0` gives `maxPage = 0`.** The input clamps typed values to `0`
+and the label reads "of 0". Hide the pager when there are no results.
+
+**8. The arrows have no disabled state.** At page 1 and at `maxPage`, `step()` is a
+no-op but the chevrons keep their `cursor: pointer` and full-contrast colour. Users
+get no signal that they are at an end. There is no prop to change this.
+
+**9. Both arrows are the same icon.** `SiconRight` twice; `.leftArrow` applies
+`transform: rotate(180deg)`. If you override the icon colour or add your own
+transform via `className`, you will flip the wrong one.
+
+**10. Almost no a11y.** The chevrons are bare SVGs with `onClick` — no `<button>`,
+no `role`, no `tabIndex`, no `aria-label`. Keyboard users can only reach the number
+input. The `of {maxPage}` text has no `aria-live`, so a page change is not announced.
+
+**11. Hardcoded English `of {maxPage}`.** No label prop. Do not use in a localised
+surface without changing the DS.
+
+**12. It always spans the full width and right-aligns.** `width: 100%` +
+`justify-content: flex-end` on the root, plus `overflow: auto` on the inner section.
+Positioning is the parent's job via margin (which is exactly what the Catalogix
+wrapper adds).
+
+**13. It does not reset on filter change.** Change a filter and you keep page 7 of a
+now-2-page result set. Reset `page` and `offset` yourself.
+
+---
+
+## In the wild
+
+```jsx
+// catalogix/dashboard  app/components/Pagination/index.jsx:12
+export default function Pagination(props) {
+  return (
+    <div style={{ margin: "24px 24px 18px 0" }}>
+      <ScPagination {...props} />
+    </div>
+  );
+}
+// props = { itemsCount, itemsPerPage, page, setPage, setOffsetValue, onPageChangeAction }
+```
+
+---
+
+## Related
+
+- `ScTableHeader` / `ScTableList` — the table this sits under.
+- `ScCatalogixStoreHeader` / `ScCatalogixStoreTableList` — the Catalogix stores table.
+- `ScCounter` — the form-field stepper, for when you wanted a quantity not a page.
+- `ScOnlyField` — a bare input, if you only need the number box.
+- `ScSelect` — pair it beside the pager for a page-size picker (not built in).

package/dist/docs/ScPairtext.md

@@ -0,0 +1,287 @@
+---
+component: ScPairtext
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div
+tags: [icon-text, label-row, checkbox-row, radio-row, option-row, meta-row, atom]
+related: [ScCheckField, ScCheckbox, ScRadio, ScBadges, ScCatalogixInvite, ScWorkspaceCard]
+do_not_confuse_with: [ScCheckField, ScCheckbox, ScRadio, ScSelection, ScSelectionPill, ScMenuOptions]
+---
+
+# ScPairtext
+
+**One row: a leading (or trailing) icon / checkbox / radio, paired with a single
+line of text.** It is the atom the DS uses for option rows and icon-and-label meta
+rows — `ScCheckField`, `ScCatalogixInvite`'s store list, `ScWorkspaceCard`,
+`ScPlanDetailsCard`, `ScCreditsUsageCard` and `ScBillingHistoryTableList` are all
+built from it.
+
+Despite the name it is **not** a key→value pair: there is exactly one text string.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are composing a DS component and need the standard
+  "control + label" or "icon + label" row, and you want it to line up with the
+  rest of the library.
+- **Don't reach for it when:** you are building a form in a host app — use
+  `ScCheckField` (label + checkbox list) or `ScCheckbox`/`ScRadio` directly, both
+  of which have real props and a11y.
+- **Five things that will bite you:**
+  1. `content` defaults to the literal string `"Pairtext"`. Forget it and that
+     word ships (it does today, in `ScCheckField`'s and `ScCatalogixInvite`'s
+     placeholder rows).
+  2. `icon` is only rendered when `type="icon"`. With `radio`/`checkbox` it is
+     silently ignored.
+  3. The root **always** has `cursor: pointer` and **always** calls
+     `onChange(!checked)` on click — even for a read-only `type="icon"` display row.
+  4. Extra props are **dropped**. No `style`, no `id`, no `data-*`, no `aria-*`,
+     no `onClick`, no `onMouseEnter` — `className` is the entire escape hatch.
+  5. No a11y. It is a `div` with an `onClick`; there is no `role="checkbox"`,
+     no `aria-checked`, no `tabIndex`, no keyboard.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScPairtext } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+// icon + label (display)
+<ScPairtext icon={<SiconTeam />} content="12 members" />
+
+// checkbox + label (interactive)
+<ScPairtext type="checkbox" content="Can use credits" checked={canUse} onChange={setCanUse} />
+```
+
+### Props
+
+`ScPairtext` does **not** extend `HTMLAttributes` and does **not** spread extra
+props onto the root.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `content` | `string` | `"Pairtext"` | ⚠️ Real default. The single text line. `flex: 1`, so it fills the row. Wraps — it does not truncate. |
+| `icon` | `JSX.Element` | `<SiconHome />` | ⚠️ Real default. **Only rendered when `type="icon"`.** Not size-normalised or recoloured. |
+| `iconPosition` | `"left"` \| `"right"` | `"left"` | Which side the icon/control sits on. `"left"` → control then text; `"right"` → text then control. |
+| `type` | `"icon"` \| `"radio"` \| `"checkbox"` | `"icon"` | What the leading/trailing element is. `radio` renders `ScRadio`, `checkbox` renders `ScCheckbox`. |
+| `checked` | `boolean` | – | Drives the control's `state` (`checked ? "selected" : "default"`) and is forwarded to `ScCheckbox`. |
+| `onChange` | `(checked: boolean) => void` | – | Called with `!checked` on **any** click on the row. |
+| `className` | `string` | – | Appended to the root class list. The only styling hook. |
+
+#### What renders for each `type`
+
+| `type` | Leading/trailing element | `icon` used? | `checked` used? |
+|---|---|---|---|
+| `"icon"` | your `icon` (or the default home icon) | yes | only to compute a state nothing renders |
+| `"radio"` | `ScRadio state={checked ? "selected" : "default"}` | **no** | yes (visual only) |
+| `"checkbox"` | `ScCheckbox state={…} checked={checked}` | **no** | yes |
+
+### Recipes
+
+```tsx
+// Meta row inside a card: icon + value (the ScWorkspaceCard idiom)
+<ScPairtext icon={<SiconCrown />} content={ownerEmail} />
+
+// Checkbox option row with the box on the RIGHT (the store-access idiom)
+<ScPairtext
+  type="checkbox"
+  iconPosition="right"
+  content={store.name}
+  checked={selectedStores.includes(store.id)}
+  onChange={() => toggleStore(store.id)}
+/>
+
+// A radio group — YOU own exclusivity; ScPairtext has no name/group concept
+{plans.map((p) => (
+  <ScPairtext
+    key={p.id}
+    type="radio"
+    content={p.label}
+    checked={p.id === selectedPlan}
+    onChange={() => setSelectedPlan(p.id)}   // never rely on the boolean argument
+  />
+))}
+
+// In a host app, prefer the field wrapper over hand-stacking rows
+<ScCheckField
+  label="Permission"
+  checkboxes={[
+    { label: "Can Use Credits", checked: canUseCredits, onChange: setCanUseCredits },
+    { label: "Can Invite User", checked: canInviteUser, onChange: setCanInviteUser },
+  ]}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+Inside other components. Current internal render sites in `@streamoid/ui`:
+
+| Parent | How it is used |
+|---|---|
+| `ScCheckField` | one `type="checkbox"` row per entry in `checkboxes` |
+| `ScCatalogixInvite` | the store-access list (`type="checkbox"`, `iconPosition="right"`) |
+| `ScWorkspaceCard` | two `type="icon"` meta rows (member count, owner email) |
+| `StreamoidWorkspaceSwitcher` (`SC-WorkspaceSwitcher`) | a workspace row |
+| `ScPlanDetailsCard` | the plan header row (billing icon + plan label) |
+| `ScCreditsUsageCard` | the credits header row |
+| `ScBillingHistoryTableList` | the "download invoice" cell (download icon + label) |
+
+In a host app, reach for it only when you are building a **new composite** that
+must line up with those. For plain forms, `ScCheckField` already wraps it.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are authoring a DS component and need the canonical icon/control + label
+  row with the library's 8 px gap and 14 px primary text.
+- You need a **checkbox or radio on the right** of its label —
+  `iconPosition="right"` is the cheapest way to get that alignment (the text is
+  `flex: 1`, so the control is pushed to the far edge).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A labelled group of checkboxes in a form | `ScCheckField` |
+| One checkbox, with `disabled` / `partial` / a custom size | `ScCheckbox` (it has `disabled`, `size`, `state="partial"`, `style`, `onClick`) |
+| A radio in a real group | `ScRadio`, with exclusivity managed by you |
+| A read-only status chip | `ScBadges` |
+| A row in a dropdown/popup menu | `ScMenuOptions` |
+| A segmented filter row | `ScSelectionPill` / `ScSelectionPillGroup` |
+| An option row in the agent chat transcript | `ScSelection` / `ScSelectionList` (agent runtime) |
+| A true key→value row (label left, value right) | not this — build it, or use `ScTableList` for tabular data |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScCheckField` — label + a list of checkbox rows, with real props | `ScPairtext` is one row and has no label above it |
+| `ScCheckbox` / `ScRadio` — the controls themselves, with `disabled`, `size`, `style` | `ScPairtext` wraps them and hides most of their API |
+| A key→value display (older docs call this "paired text") | there is only **one** text prop, `content` |
+| `ScSelection` — in-chat radio row with title *and* description (agent runtime) | `ScPairtext` is a dashboard/composite atom |
+| `ScMenuOptions` — icon + label row built for menus | different padding, hover and click contract |
+
+---
+
+## 4. Why to use it
+
+- **It is what the rest of the library uses**, so a new composite built from it
+  inherits exactly the same 8 px gap, 14 px `text-and-icons-primary` label and
+  vertical centring as the workspace, plan and billing cards.
+- **`flex: 1` on the text** gives you right-aligned controls for free without a
+  `justify-content: space-between` wrapper, and `min-width: 0` means long values
+  don't blow the row's width out.
+- **The control's visual state is derived** from `checked`, so a row can't show a
+  ticked box with `checked={false}`.
+- **`flex-shrink: 0` on the nested control** is already set, which is the exact
+  rule that goes missing when these rows are hand-rolled inside a constrained
+  flex column.
+
+---
+
+## Gotchas
+
+**1. `content` defaults to `"Pairtext"`.** This is live in the product today:
+`ScCheckField` with no `checkboxes` and `ScCatalogixInvite` with no `stores` both
+render placeholder rows reading "Pairtext".
+
+```tsx
+// WRONG — renders the word "Pairtext"
+<ScPairtext type="checkbox" checked={v} onChange={setV} />
+
+// RIGHT
+<ScPairtext type="checkbox" content="Can invite users" checked={v} onChange={setV} />
+```
+
+**2. `icon` is ignored unless `type="icon"`.** Passing both an `icon` and
+`type="checkbox"` renders only the checkbox — a mistake that exists in the DS's
+own placeholder branches.
+
+**3. Everything is clickable, always.** The root carries inline
+`cursor: pointer` and an `onClick` that fires `onChange?.(!checked)` regardless of
+`type`. A `type="icon"` display row therefore *looks* interactive. There is no
+`disabled` and no way to turn the handler off — omitting `onChange` leaves the
+pointer cursor.
+
+**4. `onChange` receives `!checked`, which lies when `checked` is undefined.**
+`!undefined === true`, so an uncontrolled row reports `true` on every click.
+
+```tsx
+// WRONG — always logs true, even on the "second" click
+<ScPairtext type="checkbox" content="Beta" onChange={(v) => save(v)} />
+
+// RIGHT — control it, or ignore the argument
+<ScPairtext type="checkbox" content="Beta" checked={beta} onChange={setBeta} />
+```
+
+**5. Extra props are silently dropped.** The component destructures `...props` and
+never spreads it, and the interface doesn't extend `HTMLAttributes`. So there is
+no `style`, `id`, `data-testid`, `title`, `aria-label`, `onClick`, `onMouseEnter`
+or `key`-adjacent escape hatch — only `className`. If you need any of those, wrap
+it in your own element or use `ScCheckbox`/`ScRadio` directly (both accept
+`style` and spread props).
+
+**6. No accessibility.** No `role`, no `aria-checked`, no `tabIndex`, no
+Enter/Space. For a genuinely accessible option list, wrap `ScCheckbox` yourself
+with a real `<label>`.
+
+**7. `radio` has no group semantics.** `ScRadio` receives only a visual `state`;
+there is no `name`, so nothing stops every row in your list from looking selected.
+You own exclusivity.
+
+**8. Long text wraps, it doesn't truncate.** `.content` sets `flex: 1;
+min-width: 0` but no `overflow`/`text-overflow`/`white-space`. A long store name
+will grow the row's height. Truncate upstream or add a `className` rule.
+
+**9. Your icon is not resized or recoloured.** Unlike `ScButton`, there is no
+`cloneElement`; `Sicon*` defaults to `size={24}`, which is often too big for a
+dense row. Pass `size` and `color` explicitly.
+
+**10. The row gap uses a non-standard token,** `var(--gp8, 0.5rem)` rather than
+`--spacing-md`. A known outlier; don't copy it into new components.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+Composed internally is the accurate story here: it is rendered by seven other
+`@streamoid/ui` components (see §2) and never called directly from CXO,
+Catalogix, Photogenix or Artifax. Where a host *needs* this shape, the supported
+entry point is `ScCheckField`:
+
+```tsx
+// cxo-dashboard  src/app/components/mobile-teams-invite-popup.tsx:150
+<ScCheckField
+  label="Permission"
+  checkboxes={[
+    { label: "Can Use Credits", checked: canUseCredits, onChange: setCanUseCredits },
+    { label: "Can Invite User", checked: canInviteUser, onChange: setCanInviteUser },
+  ]}
+  className="w-full shrink-0"
+/>
+```
+
+---
+
+## Related
+
+- `ScCheckField` — the host-facing wrapper: label + a list of `ScPairtext` checkbox rows.
+- `ScCheckbox` / `ScRadio` — the controls, with the full API (`disabled`, `size`, `style`).
+- `ScCatalogixInvite` / `ScWorkspaceCard` / `ScPlanDetailsCard` — composites that render it.
+- `ScBadges` — for non-interactive status text instead of a fake-clickable row.
+- `ScMenuOptions` — the icon + label row for menus.