@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScCheckField.md

@@ -0,0 +1,233 @@
+---
+component: ScCheckField
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div
+tags: [checkbox, field, form, multi-select, permissions, label, checkbox-group, pairtext]
+related: [ScCheckbox, ScPairtext, ScTabField, ScTextField, ScAppField]
+do_not_confuse_with: [ScCheckbox, ScPairtext, ScTabField, ScAppField]
+used_by: [cxo]
+---
+
+# ScCheckField
+
+**A labelled multi-select form field: caption on top, bordered box underneath with
+your checkbox options in a single horizontal row.** Each option is a `ScPairtext`
+(`type="checkbox"`), so the whole label+box pair is one click target. Designed to
+stack with `ScTextField` / `ScTabField` inside a form.
+
+## TL;DR for agents
+
+- **Reach for it when:** a form needs 2 (maybe 3) boolean options under one caption
+  — "Permission: Can Use Credits / Can Invite User".
+- **Don't reach for it when:** you need a bare glyph (→ `ScCheckbox`), one labelled
+  row on its own (→ `ScPairtext`), single-choice (→ `ScTabField`), or app-permission
+  toggles (→ `ScAppField`).
+- **Three things that will bite you:**
+  1. Omit `checkboxes` and you ship **two placeholder rows labelled "Pairtext"** —
+     the fallback is a Figma stub, not an empty state.
+  2. The container is `flex-direction: row` with **no wrapping**. It is a
+     side-by-side pair, not a vertical checklist. Four options squash to unreadable.
+  3. `label` defaults to `"Label"` ⚠️ — forget it and that ships.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScCheckField } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScCheckField
+  label="Permission"
+  checkboxes={[
+    { label: "Can Use Credits", checked: canUseCredits, onChange: setCanUseCredits },
+    { label: "Can Invite User", checked: canInviteUser, onChange: setCanInviteUser },
+  ]}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | `"Label"` | ⚠️ Real default. The muted caption above the box (`--alias-text-and-icons-tertiary`, text-sm). Fixed 1.25rem height — it does not wrap. |
+| `checkboxes` | `{ label: string; checked: boolean; onChange: (checked: boolean) => void }[]` | – | One `ScPairtext` per item, in order, each `flex: 1`. Omit it and you get the placeholder — see Gotcha 1. |
+| `className` | `string` | – | Concatenated onto the outer column wrapper (not the bordered box). |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root: `style`, `onClick`, `id`, `data-*`, `aria-*`. |
+
+There is **no** `disabled`, no `required`, no error/helper text, no `partial` state,
+and no `name` — each item is a plain controlled boolean.
+
+### Recipes
+
+```tsx
+// The CXO idiom: conditional permission field inside a mobile invite form
+{role === "member" && (
+  <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"
+  />
+)}
+
+// Driving it from a permissions object
+<ScCheckField
+  label="Permission"
+  checkboxes={PERMISSIONS.map((p) => ({
+    label: p.label,
+    checked: !!perms[p.key],
+    onChange: (next) => setPerms({ ...perms, [p.key]: next }),
+  }))}
+/>
+
+// More than ~3 options: don't. Stack ScPairtext rows in your own column instead.
+<div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+  {options.map((o) => (
+    <ScPairtext
+      key={o.key}
+      type="checkbox"
+      content={o.label}
+      checked={!!perms[o.key]}
+      onChange={(next) => setPerms({ ...perms, [o.key]: next })}
+    />
+  ))}
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO's mobile teams popups** — the "Permission" field in
+  `mobile-teams-invite-popup` and `mobile-teams-manage-popup`, sitting in a vertical
+  stack between `ScTabField` ("Role") and `ScAppField` ("App permission").
+- Any **short boolean pair inside a form column**, where the caption + bordered box
+  must match the other DS fields' rhythm (`ScTextField`, `ScTabField`, `ScOnlyField`
+  all use the same caption style and `--radius-xl` container).
+
+It composes `ScPairtext` → `ScCheckbox` internally. Nothing else in the DS renders it.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The options are **boolean, few, and belong to one caption**.
+- The value is **staged** — the user confirms with a Save/Invite button afterwards.
+- You want the field to look like every other field in the same form stack.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Just the tickable box, no caption or container | `ScCheckbox` |
+| One labelled option row, laid out by you | `ScPairtext` (`type="checkbox"`) |
+| More than ~3 options, or a vertical checklist | your own column of `ScPairtext` — this field does not wrap |
+| Exactly one of two/three choices, same field look | `ScTabField` |
+| Per-app enable toggles + store pickers (invite flows) | `ScAppField` — it owns that whole block |
+| A setting that applies the moment it's flipped | `ScToggleSwitch` |
+| Text input with a caption | `ScTextField` / `ScOnlyField` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScCheckbox` — the 24px glyph only | `ScCheckField` is caption + container + N rows |
+| `ScPairtext` — a single label+control row (checkbox / radio / icon) | This field *renders* those rows for you |
+| `ScTabField` — same caption + container chrome but **single**-choice, rendered as a segmented switcher | Both are "…Field"; only this one is multi-select |
+| `ScAppField` — the CXO app-permission block (per-app toggles, store lists) | Different domain, not a generic checkbox field |
+
+---
+
+## 4. Why to use it
+
+- **Field rhythm for free.** The caption colour/size, the `--spacing-xs` gap, the
+  `--radius-xl` container and the hairline `--alias-border-divider` border are the
+  same tokens `ScTextField` and `ScTabField` use, so a stack of mixed fields lines
+  up without per-call-site CSS.
+- **The rows are one click target.** `ScPairtext` puts the click on the whole row and
+  sets `cursor: pointer`, so the label text toggles the box — something you don't get
+  by hand, because `ScCheckbox` has no inner `<input>` for a `<label>` to activate.
+- **Even columns.** Each row is `flex: 1 !important`, so two options are always the
+  same width regardless of label length instead of hugging their text.
+- **Theme-correct in one place.** The container background is
+  `--alias-surface-base`, so it stays distinct from the page surface in both themes.
+
+---
+
+## Gotchas
+
+**1. No `checkboxes` → two rows labelled "Pairtext".** The fallback branch renders
+two `ScPairtext`s with only an `icon` prop set — and `type="checkbox"` means the icon
+is never drawn, so you see the default `content` string instead.
+
+```tsx
+// WRONG — renders two unchecked rows reading "Pairtext"
+<ScCheckField label="Permission" />
+
+// RIGHT — always pass checkboxes
+<ScCheckField label="Permission" checkboxes={perms} />
+```
+
+**2. It is a horizontal row, and it does not wrap.** The container is
+`display: flex; flex-direction: row; gap: 1rem` with no `flex-wrap`, and every item
+is `flex: 1`. Two options is the design; three is tight; four is unusable. Long
+labels do not truncate with an ellipsis — they wrap inside their own cell and grow
+the box.
+
+**3. `label` defaults to `"Label"`.** ⚠️ Always set it.
+
+**4. Everything is controlled and per-item.** Each entry supplies its own `checked`
+and `onChange`; the field keeps no state and there is no group-level `onChange`.
+Forget to update your state and the box never moves.
+
+**5. No indeterminate, no disabled.** The item shape is `checked: boolean` only, so
+`ScCheckbox`'s `partial` state is unreachable here, and there is no way to grey out
+a single option. Gate the whole field by conditionally rendering it (that's what CXO
+does with `role === "member"`).
+
+**6. `className` lands on the outer column, not the bordered box.** To restyle the
+box itself you need a descendant selector from your own class; there is no
+`boxClassName`.
+
+**7. Row order is array order, and `key` is the index.** Reordering `checkboxes`
+between renders re-labels existing rows rather than moving them. Keep the array
+stable.
+
+---
+
+## In the wild
+
+```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
+
+- `ScPairtext` — the row this field is made of; use it directly for vertical lists.
+- `ScCheckbox` — the glyph underneath, incl. the `partial` state this field can't reach.
+- `ScTabField` — the single-choice sibling with identical caption/container chrome.
+- `ScTextField` / `ScOnlyField` — the text fields it stacks with.
+- `ScAppField` — the app-permission block that sits below it in CXO's invite forms.

package/dist/docs/ScCheckbox.md

@@ -0,0 +1,272 @@
+---
+component: ScCheckbox
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div
+tags: [checkbox, check, tick, tri-state, indeterminate, partial, select-all, multi-select, boolean, row-selection]
+related: [ScCheckField, ScPairtext, ScRadio, ScToggleSwitch]
+do_not_confuse_with: [ScCheckField, ScPairtext, ScToggleSwitch, ScRadio]
+used_by: [catalogix, photogenix]
+---
+
+# ScCheckbox
+
+**The bare checkbox glyph — a 24×24 box, nothing else.** Renders one of three
+inline SVGs (empty ring / dash / tick) inside a `<div>` that toggles on click. It
+carries **no label**, no native `<input>`, and no internal state.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a tickable box next to content you are laying out
+  yourself — table-row selection, grid-cell selection, a "select all" header.
+- **Don't reach for it when:** you want a labelled row (→ `ScPairtext`), a whole
+  labelled multi-select *field* with a bordered container (→ `ScCheckField`), an
+  instant-apply on/off switch (→ `ScToggleSwitch`), or single-choice (→ `ScRadio`).
+- **Four things that will bite you:**
+  1. `checked` **overrides `state`** — pass `checked` and `state="partial"` becomes
+     unreachable. Indeterminate requires `state="partial"` with `checked` omitted.
+  2. It is **not an `<input>`**. No form value, no keyboard, no `role="checkbox"`,
+     no `aria-checked`. Wrapping it in a `<label>` does nothing.
+  3. It holds **zero internal state**. If you don't move `checked`/`state`, the box
+     never visually changes, even though `onChange` fired.
+  4. `onChange` **and** `onClick` both fire on every click (`onChange` first).
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScCheckbox } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScCheckbox checked={isSelected} onChange={setIsSelected} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `state` | `"default"` \| `"partial"` \| `"selected"` | `"default"` | The tri-state artwork. **Ignored whenever `checked` is not `undefined`.** `"partial"` = the indeterminate dash. |
+| `checked` | `boolean` | – | Controlled boolean. When supplied it wins over `state` and maps to `selected`/`default` only. |
+| `disabled` | `boolean` | `false` | `cursor: not-allowed` + `opacity: 0.5`, and the click handler early-returns. **Does not stop propagation** — see Gotcha 6. |
+| `onChange` | `(checked: boolean) => void` | – | Fires with the *next* value. The handler you normally want. |
+| `onClick` | `MouseEventHandler<HTMLDivElement>` | – | Native click, fires **after** `onChange`. Both run. |
+| `size` | `number \| string` | – | Box size; a number becomes `px`. The SVG fills the box, so the artwork scales proportionally. Default box is `1.5rem` (24px) from CSS. |
+| `style` | `React.CSSProperties` | – | Spread **last**, so it beats `size`, the cursor and the opacity. |
+| `className` | `string` | – | Concatenated between the base and state classes. |
+| `...props` | `Omit<HTMLAttributes<HTMLDivElement>, "onChange">` | – | `id`, `data-*`, `aria-*`, `title` land on the root div. |
+
+### What renders in each state
+
+| Effective state | Artwork | Tokens |
+|---|---|---|
+| `default` | 22.5px rounded square outline, 1.5 stroke | `--alias-border-default` |
+| `partial` | filled square + horizontal dash | fill `--alias-fill-base-base`, dash `--alias-text---icons-inverse` |
+| `selected` | filled square + tick | fill `--alias-fill-base-base`, tick `--alias-text---icons-inverse` |
+
+Effective state is `checked !== undefined ? (checked ? "selected" : "default") : state`.
+
+### Recipes
+
+```tsx
+// Row selection in a table (the Photogenix idiom) — dense 16px box
+<ScCheckbox
+  checked={selectedIds.has(row.id)}
+  onChange={() => toggle(row.id)}
+  style={{ width: 16, height: 16 }}
+/>
+
+// Select-all header with an indeterminate middle state.
+// NOTE: `checked` must be omitted, or "partial" is dropped.
+<ScCheckbox
+  state={allSelected ? "selected" : someSelected ? "partial" : "default"}
+  onChange={() => (allSelected ? clearAll() : selectAll())}
+/>
+
+// Your own labelled row — the label text is NOT clickable for free
+<div
+  style={{ display: "flex", gap: 8, alignItems: "center", cursor: "pointer" }}
+  onClick={() => setAddToAll(!addToAll)}
+>
+  <ScCheckbox checked={addToAll} />
+  <span>Add to all style codes ({styleCodes.length})</span>
+</div>
+
+// Inside a clickable row — stop the cell swallowing/duplicating the click
+<td onClick={(e) => e.stopPropagation()}>
+  <ScCheckbox checked={sel} onChange={onToggle} />
+</td>
+```
+
+---
+
+## 2. Where to use it
+
+- **Table and grid row selection** — Photogenix's batch-detail product rows and
+  admin history view; Catalogix's PLP grid (16px via the local `Checkbox` wrapper).
+- **"Apply to all" options in modals** — Catalogix
+  `app/containers/Assets/AddToProducts` ("Add to all style codes").
+- **Inside the DS itself** — `ScPairtext` with `type="checkbox"` renders one, and
+  `ScCheckField` renders a row of `ScPairtext`s. If you need label + box, go up a
+  level rather than composing this by hand.
+
+Catalogix and Photogenix both wrap it in a local shim (`app/components/Checkbox`,
+Photogenix's test stub) to preserve legacy `partiallyChecked` / `onClick(next)` APIs.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The choice is **boolean and staged** (the user confirms later with a button), or
+  it selects rows for a bulk action.
+- You are laying out the label/row yourself and only want the glyph to be
+  token-correct and theme-correct.
+- You need the **indeterminate** dash — this is the only DS control that has one.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Box **plus** a text label as one clickable row | `ScPairtext` (`type="checkbox"`) |
+| A labelled field: caption + bordered box + several options | `ScCheckField` |
+| On/off that applies **immediately** (a setting) | `ScToggleSwitch` |
+| Exactly one of N | `ScRadio`, or `ScTabField` / `ScSelectionPillGroup` for a segmented look |
+| App-permission rows in an invite flow | `ScAppField` (already composes the toggles) |
+| A real form control that submits with a `<form>` | a native `<input type="checkbox">` — this div never participates in form data |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScCheckField` — the *field*: label + bordered container + N labelled checkboxes | `ScCheckbox` is only the 24px glyph |
+| `ScPairtext` — one label+control row; `type` picks checkbox / radio / icon | `ScCheckbox` has no text at all |
+| `ScToggleSwitch` — 40×24 switch, different semantics (instant apply) | Not a styling variant of this |
+| `ScSelectionList` — in-chat approve/reject row (**agent runtime**) | Unrelated to forms |
+
+---
+
+## 4. Why to use it
+
+- **It themes.** Both host apps replaced baked-dark PNG/SVG `<img>` ticks with this
+  because those did not invert in light mode. The three states are drawn from
+  `--alias-*` tokens, so they resolve in both themes with no conditionals.
+- **`size` actually scales the artwork.** The inner SVG has literal `width="24"`
+  attributes; the CSS forces `width/height: 100%` on it so a shrunk box scales the
+  tick instead of letting a 24px glyph spill out of a 16px frame. Hand-rolling that
+  is exactly the bug the CSS comment documents.
+- **A real indeterminate state**, drawn to the design, without an
+  `input.indeterminate` imperative ref dance.
+- **One glyph everywhere.** Row selection in Photogenix, the Catalogix PLP grid and
+  every `ScPairtext` share one shape, radius and stroke weight.
+
+---
+
+## Gotchas
+
+**1. `checked` beats `state`, and kills `partial`.** The moment `checked` is not
+`undefined` the component ignores `state` entirely.
+
+```tsx
+// WRONG — renders the empty box; "partial" is discarded because `checked` is defined
+<ScCheckbox checked={false} state="partial" />
+
+// RIGHT — omit `checked` when you need the dash
+<ScCheckbox state="partial" onChange={selectAll} />
+```
+
+**2. It's not an `<input>` and has no a11y wiring.** No `role`, no `aria-checked`,
+no `tabIndex`, no keyboard activation, no `name`/`value`, no form participation.
+Add semantics yourself if the surface needs them:
+
+```tsx
+<ScCheckbox
+  checked={sel}
+  onChange={onToggle}
+  role="checkbox"
+  aria-checked={sel}
+  aria-label="Select product"
+  tabIndex={0}
+/>
+```
+
+**3. There is no label, and `<label>` won't help.** Because there is no inner
+`<input>`, wrapping the glyph and some text in a `<label>` gives you *no* click
+target on the text. Put the `onClick` on the wrapper row (see Recipes) or use
+`ScPairtext`.
+
+**4. It is fully controlled with no internal state.** `onChange` firing does not
+change the picture. If your handler doesn't move `checked`/`state`, nothing happens.
+
+**5. `onChange` and `onClick` both fire, `onChange` first.** Don't wire the same
+mutation to both.
+
+```tsx
+// WRONG — toggles twice per click
+<ScCheckbox checked={c} onChange={() => setC(!c)} onClick={() => setC(!c)} />
+
+// RIGHT
+<ScCheckbox checked={c} onChange={setC} />
+```
+
+**6. `disabled` does not stop propagation.** It early-returns before *both*
+`onChange` and your `onClick`, but the DOM click still bubbles — a parent row's
+`onClick` (row navigation, expand) still fires. Stop it yourself if that matters.
+
+**7. `style` wins over `size`, and over `disabled` styling.** `style` is spread
+last, so `style={{ opacity: 1 }}` visually un-dims a disabled box (it stays
+non-interactive). Photogenix sizes via `style={{ width: 16, height: 16 }}`; both
+routes work, don't pass both.
+
+**8. `className` is string-concatenated, not joined.** With `className` unset the
+DOM class list literally contains `undefined`. Harmless in the browser, but it
+shows up in snapshot tests — don't assert on the exact class string.
+
+**9. jsdom tests need a stub.** Importing from the `@streamoid/ui` barrel pulls
+`ScButton`, which touches `CSS.registerProperty` at module load. Both host repos
+`vi.mock("@streamoid/ui")` with a div that surfaces `state` and forwards `onClick`
+(see `catalogix/dashboard app/tests/formControls.test.jsx`).
+
+---
+
+## In the wild
+
+```tsx
+// photogenix_v2  dashboard/client/src/components/studio/batchDetail/BatchDetailProductRow.tsx:225
+<ScCheckbox
+  checked={state.selectedProducts.has(product.id)}
+  onChange={() => state.toggleSelect(product.id)}
+  style={{ width: 16, height: 16 }}
+/>
+```
+
+```jsx
+// catalogix/dashboard  app/components/Checkbox/index.jsx:31   (legacy-API shim)
+<ScCheckbox
+  size={props.size}
+  state={props.partiallyChecked ? "partial" : checked ? "selected" : "default"}
+  style={{
+    ...(props.style || {}),
+    ...(props.disabled ? { opacity: 0.5, cursor: "not-allowed" } : {}),
+  }}
+  onClick={onClickFunc}
+/>
+```
+
+---
+
+## Related
+
+- `ScPairtext` — label + checkbox/radio/icon as one clickable row; the level above this.
+- `ScCheckField` — full labelled multi-select field; composes `ScPairtext`.
+- `ScRadio` — the single-choice sibling glyph (presentational only, no `checked`).
+- `ScToggleSwitch` — instant-apply on/off switch.
+- `ScAppField` — app-permission block; already wires its own controls.