@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScSelectionPill.md

@@ -0,0 +1,240 @@
+---
+component: ScSelectionPill
+package: "@streamoid/ui"
+category: selection
+status: stable
+renders: button[type="button"][aria-pressed]
+tags: [pill, segmented, tab, filter, chip, toggle, single-select]
+related: [ScSelectionPillGroup, ScTabs, ScTabSwitcher, ScTaxonomyPill, ScBadges]
+do_not_confuse_with: [ScSelection, ScTaxonomyPill, ScBadges, ScTabComp]
+used_by: [catalogix]
+---
+
+# ScSelectionPill
+
+**One pill in a segmented single-choice row.** Selected renders as a dark fill with
+inverse text. Almost always used through `ScSelectionPillGroup`, which owns the
+active value for you.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a segmented control — 2–5 mutually exclusive
+  views or filters shown as pills, all visible at once.
+- **Don't reach for it when:** you want the in-chat radio row (→ `ScSelection`,
+  a completely different component), a taxonomy tree node (→ `ScTaxonomyPill`),
+  or a non-interactive status chip (→ `ScBadges`).
+- **Two things that will bite you:**
+  1. `ScSelection` is **not** the singular of `ScSelectionPill`. Different family,
+     different surface. See "Don't confuse with".
+  2. This pill is stateless. It renders `selected` — it does not track it. Use
+     `ScSelectionPillGroup` unless you're deliberately owning the state yourself.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSelectionPill, ScSelectionPillGroup } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+Prefer the group — it wires selection for you:
+
+```tsx
+<ScSelectionPillGroup
+  options={[
+    { label: "Attributes", value: "attributes" },
+    { label: "Pose Type", value: "pose_types" },
+  ]}
+  value={activeTab}
+  onChange={setActiveTab}
+/>
+```
+
+A single pill, if you own the state:
+
+```tsx
+<ScSelectionPill
+  label="All Products"
+  value="all"
+  selected={filter === "all"}
+  onSelect={setFilter}
+/>
+```
+
+### Props
+
+`ScSelectionPill`
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | `"All Products"` | Pill text. ⚠️ Has a real default — always set it. |
+| `selected` | `boolean` | `false` | Dark fill + inverse text. Also surfaced as `aria-pressed`. |
+| `value` | `string` | – | Passed back to `onSelect`. Omit and you get `onSelect(undefined)`. |
+| `onSelect` | `(value?: string) => void` | – | Fires **after** `onClick`, with `value`. The handler you normally want. |
+| `onClick` | `MouseEventHandler` | – | Native click, fires **first**. Both run — see Gotcha 2. |
+| `className` | `string` | – | Appended after internal classes. |
+| `...props` | `ButtonHTMLAttributes<HTMLButtonElement>` (minus `onSelect`) | – | Spread onto the `<button>`. |
+
+`ScSelectionPillGroup`
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `options` | `{ label: string; value: string }[]` | – | Rendered in order. |
+| `value` | `string` | – | Value of the active pill. Controlled — you must supply it. |
+| `onChange` | `(value: string) => void` | – | Fires with the clicked pill's value. |
+| `className` | `string` | – | Appended after internal classes. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` (minus `onChange`) | – | Spread onto the row. |
+
+### Recipes
+
+```tsx
+// Counts in labels — build the string, the pill takes plain text
+<ScSelectionPillGroup
+  options={[
+    { label: `Attributes (${selected.length})`, value: "attributes" },
+    { label: "Pose Type", value: "pose_types" },
+  ]}
+  value={activeTab}
+  onChange={setActiveTab}
+/>
+
+// Owning state yourself over a dynamic list
+<div style={{ display: "flex", gap: 8 }}>
+  {stores.map((s) => (
+    <ScSelectionPill
+      key={s.id}
+      label={s.name}
+      value={s.id}
+      selected={s.id === activeStoreId}
+      onSelect={setActiveStoreId}
+    />
+  ))}
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **Above a list or grid that it filters** — the Catalogix Curation screen puts a
+  group directly over the attribute list it scopes.
+- **Section headers inside a panel** — switching what the panel body shows without
+  navigating.
+- **Inside `ScDrawer` / `ScModal`** — segmenting a form or picker into 2–3 views.
+
+Catalogix is the current consumer (Curation V2). Nothing outside the segmented-row
+pattern should reach for it.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The choices are **mutually exclusive** and **few** (2–5), and showing all of
+  them at once is useful context.
+- The switch changes **what is displayed**, not what is saved.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Full-width in-page tab bar, possibly wrapping/compact | `ScTabs` |
+| Compact 2–3 way view toggle in a page header | `ScTabSwitcher` (+ `ScTabComp`) |
+| Settings-page tab strip | `ScSettingsTabComp` / `ScSettingsNav` |
+| Segmented single-choice **inside a form** (a saved value) | `ScTabField` |
+| A node in a taxonomy/hierarchy tree, with expand/collapse counts | `ScTaxonomyPill` |
+| Non-interactive status/count chip | `ScBadges` |
+| Multi-select (more than one active) | `ScCheckbox` / `ScCheckField` — this pill is single-select by design |
+| An option row in the agent chat transcript | `ScSelection` / `ScSelectionList` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSelection` — in-chat radio row with title + description, agent runtime | `ScSelectionPill` is a host-app segmented tab |
+| `ScSelectionList` — in-chat approve/reject toggle row | Also agent runtime, unrelated to pills |
+| `ScTaxonomyPill` — tree node with `expand`/`collapse` types and a child count | Visually similar, structurally different |
+
+The `ScSelection*` (no "Pill") family belongs to the **chat/agent runtime**
+vocabulary. `ScSelectionPill*` belongs to the **dashboards**. The names are the
+single biggest source of wrong picks in this library.
+
+---
+
+## 4. Why to use it
+
+- **The selected skin is a token pair, not a colour.** Dark fill + inverse text
+  resolves correctly in both themes; a hand-rolled pill typically inverts wrongly
+  in light mode.
+- **Real button semantics.** Unlike `ScButton`, this renders an actual
+  `<button type="button">` with `aria-pressed` tracking `selected`, so screen
+  readers announce the toggle state and it can't accidentally submit a form.
+- **The group removes the boilerplate** you'd otherwise repeat at every call site
+  (map, compare, set) and guarantees exactly one active pill.
+- **Consistent with the rest of the segmented vocabulary** — pill radius, gap and
+  padding match `ScTabs` and `ScTaxonomyPill`.
+
+---
+
+## Gotchas
+
+**1. `label` defaults to `"All Products"`.** Forget it and you ship Catalogix copy.
+
+```tsx
+// WRONG — renders "All Products"
+<ScSelectionPill value="pose" selected />
+
+// RIGHT
+<ScSelectionPill label="Pose Type" value="pose" selected />
+```
+
+**2. `onClick` and `onSelect` both fire, in that order.** Don't wire the same
+handler to both or it runs twice.
+
+```tsx
+// WRONG — setFilter called twice per click
+<ScSelectionPill onClick={() => setFilter("all")} onSelect={setFilter} value="all" />
+
+// RIGHT — pick one; onSelect is the idiomatic choice
+<ScSelectionPill onSelect={setFilter} value="all" />
+```
+
+**3. It's controlled, always.** Neither the pill nor the group keeps internal
+state. If you don't pass `selected` / `value`, nothing ever looks active.
+
+**4. `onSelect` yields `undefined` when `value` is unset.** Always pass `value`
+alongside `onSelect`.
+
+**5. The group is not a `<fieldset>`/radiogroup.** It's a div of `aria-pressed`
+buttons. For a genuine form radio group, use `ScRadio` or `ScTabField`.
+
+---
+
+## In the wild
+
+```tsx
+// catalogix/dashboard  app/containers/StoreSettingsV2/CurationV2/index.jsx:368
+<ScSelectionPillGroup
+  options={[
+    { label: `Attributes (${selectedAttributeValues.length})`, value: "attributes" },
+    { label: "Pose Type", value: "pose_types" },
+  ]}
+  value={activeTab}
+  onChange={(tab) => setActiveTab(tab)}
+/>
+```
+
+---
+
+## Related
+
+- `ScSelectionPillGroup` — the controlled wrapper; use this by default.
+- `ScTabs` / `ScTabSwitcher` / `ScTabComp` — the tab-bar vocabulary.
+- `ScTaxonomyPill` — hierarchy node chip with expand/collapse.
+- `ScSelection` / `ScSelectionList` — the unrelated in-chat selection family.

package/dist/docs/ScSelectionPillGroup.md

@@ -0,0 +1,302 @@
+---
+component: ScSelectionPillGroup
+package: "@streamoid/ui"
+category: feed-taxonomy
+status: stable
+renders: div[role="tablist"]
+tags: [segmented, pills, tabs, tablist, filter, single-select, controlled, group, catalogix]
+related: [ScSelectionPill, ScTabs, ScTabSwitcher, ScTabField, ScTaxonomyPill]
+do_not_confuse_with: [ScSelection, ScSelectionList, ScTabs, ScTabSwitcher, ScSettingsTabComp]
+used_by: [catalogix]
+---
+
+# ScSelectionPillGroup
+
+**The controlled wrapper around a row of `ScSelectionPill`s.** You hand it
+`options`, the current `value` and `onChange`; it renders one pill per option, marks
+exactly one selected, and wires the click. The root is a
+`div[role="tablist"]` with `flex-wrap: wrap` and a `0.5rem` gap.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a segmented control — 2–5 mutually exclusive views
+  or filters, all visible at once — and you don't want to hand-roll the
+  map/compare/set boilerplate.
+- **Don't reach for it when:** you want the in-chat option rows (→ `ScSelection` /
+  `ScSelectionList`, a different family in a different package's surface), a
+  full-width page tab bar (→ `ScTabs`), a settings tab strip
+  (→ `ScSettingsTabComp`), a saved form value (→ `ScTabField`), or taxonomy tree
+  chips (→ `ScTaxonomyPill`).
+- **Four things that will bite you:**
+  1. Fully **controlled**. No internal state — if `value` doesn't match an option's
+     `value` exactly, nothing looks selected.
+  2. Options are **label + value only**. No icons, no counts-as-badges, no per-option
+     `disabled`. Bake counts into the label string.
+  3. It claims `role="tablist"` / `role="tab"` but wires **no `aria-controls`, no
+     tabpanel and no arrow-key navigation** — an incomplete ARIA tabs pattern.
+  4. Duplicate `option.value`s break it twice over: duplicate React keys *and* every
+     matching pill renders selected.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSelectionPillGroup } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+`ScSelectionPill` is imported internally — you don't need it unless you're building
+something the group can't express (see Gotcha 3).
+
+### Minimal usage
+
+```tsx
+<ScSelectionPillGroup
+  options={[
+    { label: "Attributes", value: "attributes" },
+    { label: "Pose Type", value: "pose_types" },
+  ]}
+  value={activeTab}
+  onChange={setActiveTab}
+/>
+```
+
+### Props
+
+`ScSelectionPillGroup`
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `options` | `IScSelectionPillOption[]` | `[]` | Rendered in source order. Defaults to empty → an empty (but still `width: 100%`) row. |
+| `value` | `string` | – | `value` of the selected pill. Compared with `===`, so it is case- and whitespace-sensitive. |
+| `onChange` | `(value: string) => void` | – | Fires with the clicked option's `value`. Coerced: an option with no `value` yields `""`. |
+| `className` | `string` | – | Appended after the internal class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` **minus `onChange`** | – | Spread onto the root **after** `role="tablist"`, so `role`/`aria-*` are overridable. |
+
+`IScSelectionPillOption`
+
+| Field | Type | Notes |
+|---|---|---|
+| `label` | `string` | **Required.** Plain text — no `ReactNode`, so no icons or markup. |
+| `value` | `string` | **Required.** Also used as the React `key`. Must be unique. |
+
+### What the group sets on each pill
+
+| Attribute | Value | Note |
+|---|---|---|
+| `label` | `option.label` | |
+| `value` | `option.value` | |
+| `selected` | `option.value === value` | drives the pill's `aria-pressed` too |
+| `role` | `"tab"` | |
+| `aria-selected` | `option.value === value` | |
+| `onSelect` | `(v) => onChange?.(v ?? "")` | |
+
+So each pill carries **both** `aria-pressed` and `aria-selected`. See Gotcha 4.
+
+### Recipes
+
+```tsx
+// Counts belong in the label string — there is no count/badge slot
+<ScSelectionPillGroup
+  options={[
+    { label: `Attributes (${selectedAttributeValues.length})`, value: "attributes" },
+    { label: "Pose Type", value: "pose_types" },
+  ]}
+  value={activeTab}
+  onChange={(tab) => setActiveTab(tab)}
+/>
+
+// Derived from data — guarantee unique values
+<ScSelectionPillGroup
+  options={channels.map((c) => ({ label: c.name, value: c.id }))}
+  value={activeChannelId}
+  onChange={setActiveChannelId}
+/>
+
+// If it isn't really a tab strip, drop the tablist role rather than shipping a
+// half-implemented ARIA tabs pattern
+<ScSelectionPillGroup
+  role="group"
+  aria-label="Filter products"
+  options={filters}
+  value={filter}
+  onChange={setFilter}
+/>
+
+// Completing the ARIA contract instead (only worth it for a real tab strip)
+<>
+  <ScSelectionPillGroup aria-label="Curation views" options={views} value={view} onChange={setView} />
+  <div role="tabpanel" aria-label={activeViewLabel}>{body}</div>
+</>
+```
+
+---
+
+## 2. Where to use it
+
+- **Directly above the list or grid it scopes.** Catalogix Curation V2 puts a group
+  in `.select-heading`, over the `ScValueMappingL1` list of attribute values, with a
+  rule between them. Switching the pill swaps the whole panel body (attribute values
+  ↔ a pose-type multi-select).
+- **Section headers inside a panel** — changing what the panel body shows without
+  navigating.
+- **Inside `ScDrawer` / `ScModal`** to split a form or picker into 2–3 views.
+
+The root is `width: 100%` and `flex-wrap: wrap`, so it fills its column and wraps to
+a second line rather than scrolling. Put it in a container that is already the width
+you want.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Choices are **mutually exclusive** and **few** (2–5), and showing all of them at
+  once is useful context.
+- The switch changes **what is displayed**, not what is saved.
+- You already hold the active value in state (URL param, reducer, `useState`).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Full-width in-page tab bar with underline/active rail | `ScTabs` |
+| Compact 2–3 way view toggle in a page header | `ScTabSwitcher` (+ `ScTabComp`) |
+| Settings-page tab strip / left nav | `ScSettingsTabComp` / `ScSettingsNav` |
+| Segmented single-choice **inside a form**, whose value is saved | `ScTabField` |
+| One pill whose state you own yourself, or a pill that must be `disabled` | `ScSelectionPill` directly |
+| Multi-select (more than one active at a time) | `ScCheckField` / `ScCheckbox` — this group is single-select by construction |
+| Taxonomy tree node chips with counts and expand/collapse | `ScTaxonomyPill` |
+| Non-interactive status/count chips | `ScBadges` |
+| Option rows in the agent chat transcript | `ScSelection` / `ScSelectionList` (chat runtime) |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSelection` — in-chat radio row with title + description; **chat/agent runtime** (stream-agent / `@streamoid/agent`), not the dashboards | `ScSelectionPillGroup` is a host-app segmented row |
+| `ScSelectionList` — in-chat approve/reject toggle row; also chat runtime | Unrelated to pills despite the name |
+| `ScTabs` — tab bar with tab chrome | This is a pill row; the two are not interchangeable skins of one control |
+| `ScTaxonomyPill` — visually similar chip, but a tree node with `expand`/`collapse` types and no selected state | Different family; note both `ScSelectionPill` and `ScTaxonomyPill` default `label` to `"All Products"` |
+| `ScSelectionPill` — the leaf this group renders | Import the group unless you need per-pill control |
+
+`ScSelection*` (no "Pill") is **chat runtime**. `ScSelectionPill*` is **dashboards**.
+This naming collision is the single biggest source of wrong picks in the library.
+
+---
+
+## 4. Why to use it
+
+- **It removes the boilerplate you'd otherwise repeat at every call site** — the map,
+  the `===` compare, the setter — and guarantees exactly one pill is selected.
+- **Real `<button>` semantics per pill.** Unlike `ScButton` (a `div[role="button"]`),
+  each pill is a native `<button type="button">`, so Enter/Space work for free and it
+  can't accidentally submit a surrounding form.
+- **The selected skin is a token pair, not a colour.**
+  `--alias-fill-base-basehover` fill + `--alias-text-and-icons-inverse` text, so the
+  selected pill stays high-contrast in both themes. Hand-rolled pills are a classic
+  light-mode inversion bug.
+- **Keyboard focus is already right.** The pill kills the mouse-click outline but
+  keeps a `:focus-visible` ring on `--alias-border-focus`.
+- **Consistent metrics in one place.** The pill's `0.5rem 1rem` padding and
+  `radius-3xl` and the group's `0.5rem` gap live in two CSS modules, so every
+  segmented row in a host looks identical. (They are *not* shared with the other
+  pill-ish components: `ScTaxonomyPill` uses `radius-xl` and `ScTabs` a `100px`
+  radius with a `12px` gap — don't mix them in one row expecting parity.)
+
+---
+
+## Gotchas
+
+**1. It is controlled, always.** No internal state. A `value` that doesn't `===` an
+option's `value` leaves every pill unselected — and the very first render is the
+usual victim.
+
+```tsx
+// WRONG — nothing is selected; "Attributes" !== "attributes"
+<ScSelectionPillGroup options={opts} value="Attributes" onChange={setTab} />
+
+// RIGHT — seed state from an option's value
+const [tab, setTab] = useState(opts[0].value);
+<ScSelectionPillGroup options={opts} value={tab} onChange={setTab} />
+```
+
+**2. `options` defaults to `[]`.** A typo'd prop name renders an empty div that still
+occupies a `width: 100%` flex line — it looks like a layout gap, not an error.
+
+**3. Options are label + value only.** `label` is `string`, not `ReactNode`, and
+there is no `disabled`, `icon` or `count` field. Counts go into the string
+(`` `Attributes (${n})` ``). Anything else means dropping to `ScSelectionPill`
+directly — which, being a real `<button>`, does accept the native `disabled`
+attribute the group can't pass through.
+
+**4. The ARIA tabs pattern is incomplete.** The group sets `role="tablist"`, each
+pill gets `role="tab"` + `aria-selected`, and the pill itself also sets
+`aria-pressed` — so every pill announces two different selection states. There is no
+`aria-controls`, no `id`/`tabpanel` pairing, and no arrow-key roving tabindex (Tab
+steps through every pill). Either finish the contract or override the role:
+
+```tsx
+// RIGHT when it's just a filter row, not a tab strip
+<ScSelectionPillGroup role="group" aria-label="Filter" options={opts} value={v} onChange={setV} />
+```
+
+`role` is applied **before** `...props`, so your override wins. Same for `aria-*`.
+
+**5. `option.value` is the React key.** Duplicates give you a key warning *and*
+multiple pills rendering selected at once, because selection is `value ===` and not
+an index compare.
+
+**6. `onChange` never receives `undefined`.** The group does `onChange?.(v ?? "")`.
+In a JS host (Catalogix is `.jsx`) an option built without a `value` therefore fires
+`onChange("")` rather than throwing — a silent "nothing selected" loop.
+
+**7. "Selected = dark fill" is the light-theme description.** The token pair is
+`--alias-fill-base-basehover` + `--alias-text-and-icons-inverse`, which in the
+**dark** theme paints a *light grey* pill with dark text. That's correct and
+intentional (maximum contrast against a dark canvas) — just don't read the JSDoc
+literally and "fix" it.
+
+**8. The group has no `disabled` and no busy state.** Clicks always fire. If a view
+is loading, gate it in your `onChange` handler.
+
+**9. It wraps, it doesn't scroll.** `flex-wrap: wrap` on a `width: 100%` root, so
+7 long labels silently become two rows and shift the layout below. Keep option counts
+low, or shorten labels.
+
+---
+
+## In the wild
+
+```jsx
+// catalogix/dashboard  app/containers/StoreSettingsV2/CurationV2/index.jsx:368
+<ScSelectionPillGroup
+  options={[
+    {
+      label: `Attributes (${selectedAttributeValues.length})`,
+      value: "attributes",
+    },
+    { label: "Pose Type", value: "pose_types" },
+  ]}
+  value={activeTab}
+  onChange={(tab) => setActiveTab(tab)}
+/>
+```
+
+The same screen renders the `ScValueMappingL1` list underneath it — the pill group
+picks the mode, the value rows are the list body.
+
+---
+
+## Related
+
+- `ScSelectionPill` — the leaf; use it directly only when you need per-pill control (`disabled`, custom ordering, your own container).
+- `ScTabs` / `ScTabSwitcher` / `ScTabComp` / `ScSettingsTabComp` — the tab-bar vocabulary; pick by surface, not by looks.
+- `ScTabField` — segmented single-choice that is a *form value*.
+- `ScValueMappingL1` — the list this group usually sits above in Catalogix Curation.
+- `ScTaxonomyPill` — the tree-node chip family; shares the `"All Products"` default label trap.
+- `ScSelection` / `ScSelectionList` — the unrelated chat-runtime selection family.