@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScTabComp.md

@@ -0,0 +1,308 @@
+---
+component: ScTabComp
+package: "@streamoid/ui"
+category: layout
+status: stable
+renders: div
+tags: [tab, tab-cell, segmented, icon-tab, toggle, view-switch, theme-switcher]
+related: [ScTabSwitcher, ScTabField, ScTabs, ScSettingsTabComp, ScSelectionPill]
+do_not_confuse_with: [ScTabs, ScTabSwitcher, ScTabField, ScSettingsTabComp, ScSelectionPill]
+used_by: [cxo, photogenix, catalogix, artifax]
+---
+
+# ScTabComp
+
+**One tab cell — icon *or* text, never both.** The atom of the 2–5 way segmented
+control: a rounded, padded div that turns light-filled with inverse text when
+`active="true"`. Almost always rendered into a `ScTabSwitcher` slot, but usable
+standalone (Catalogix's stores grid/list toggle does exactly that).
+
+## TL;DR for agents
+
+- **Reach for it when:** you need one segment of a compact 2–5 way view toggle —
+  theme switcher, grid/list, Active/Pending, Fast/Pro.
+- **Don't reach for it when:** the tab list is data-driven or longer than five
+  (→ `ScTabs`), it's a settings underline strip (→ `ScSettingsTabComp`), or it's a
+  form value (→ `ScTabField`).
+- **Four things that will bite you:**
+  1. `active` is the **string** `"true"` / `"false"`, not a boolean.
+  2. `icon` defaults to `SiconHome` and `text` defaults to `"Tab"` — forget both and
+     you ship a house labelled "Tab".
+  3. `type` is exclusive: `"text-only"` renders no icon, `"icon-only"` renders no
+     text, and **any other value renders an empty tab**.
+  4. Going active recolours only the **text**. Your icon's colour is your job.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScTabComp } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScTabComp text="Active" type="text-only" active="true" onClick={() => setTab("active")} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `text` | `string` | `"Tab"` | ⚠️ Real default. Only rendered when `type="text-only"`. Emitted with a trailing space. |
+| `icon` | `JSX.Element` | `<SiconHome />` (1.25rem) | ⚠️ Real default. Only rendered when `type="icon-only"`. **Not** cloned/recoloured — you control its `color`. |
+| `type` | `"text-only"` \| `"icon-only"` | `"text-only"` | Exclusive. No combined icon+text variant exists. |
+| `active` | `"true"` \| `"false"` | `"false"` | ⚠️ **A string, not a boolean.** Drives the `.active-true` fill + inverse label. |
+| `className` | `string` | – | Appended after the internal classes. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div: `onClick`, `style`, `role`, `aria-*`, `data-*`. This is where selection handling lives. |
+
+### What renders in each combination
+
+| `type` | `active` | Renders |
+|---|---|---|
+| `"text-only"` | `"false"` | muted 14px/400 label, transparent background |
+| `"text-only"` | `"true"` | inverse 14px/**500** label on `--alias-fill-base-basehover` |
+| `"icon-only"` | `"false"` | your `icon` at 1.25rem, transparent background |
+| `"icon-only"` | `"true"` | your `icon` at 1.25rem on `--alias-fill-base-basehover` — **icon colour unchanged** |
+| anything else | any | **an empty div** (see Gotcha 3) |
+
+### Recipes
+
+```tsx
+// Standalone icon toggle with real tab semantics (Catalogix stores view switch)
+<ScTabComp
+  type="icon-only"
+  active={view === "grid" ? "true" : "false"}
+  role="tab"
+  aria-label="Grid view"
+  aria-selected={view === "grid"}
+  icon={
+    <SiconGrid
+      size={20}
+      color={view === "grid"
+        ? "var(--alias-text-and-icons-inverse)"
+        : "var(--alias-text-and-icons-tertiary)"}
+    />
+  }
+  onClick={() => changeView("grid")}
+/>
+
+// Inside ScTabSwitcher — note style={{ flex: 1 }}, it is NOT optional
+<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 }} />
+  }
+/>
+
+// Three-way icon switcher (Photogenix theme picker)
+<ScTabComp
+  type="icon-only"
+  active={theme === "dark" ? "true" : "false"}
+  icon={<SiconDark className="w-5 h-5"
+    color={theme === "dark" ? "var(--alias-text---icons-inverse)" : "var(--alias-text---icons-muted)"} />}
+  onClick={() => setTheme("dark")}
+  style={{ flex: 1 }}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **Inside `ScTabSwitcher`** — the dominant pattern. All four apps do this:
+  CXO teams Active/Pending, Photogenix theme + Fast/Pro + retouch modes, Catalogix
+  PLP views + attribute editor, Artifax sidebar theme switcher.
+- **Inside `ScTabField`** — the DS field wrapper builds a 2-tab switcher out of these
+  for you; pass `tabs` to the field instead of composing.
+- **Inside `ScProfilePopup` / `ScProfileOptions`** — the DS theme switcher rows.
+- **Standalone**, as a bare icon toggle in a page header (Catalogix stores listing).
+
+### Where it does *not* belong
+
+Not in `@streamoid/settings`-owned settings screens with underline tabs — those use
+`ScSettingsTabComp`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The control has **2–5 mutually exclusive** segments, all visible at once.
+- Each segment is a single icon **or** a single short word.
+- You want the "selected = light fill + inverse text" treatment that matches the rest
+  of the product's toggles.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The bordered container around 2–5 of these | `ScTabSwitcher` (don't hand-roll the border/padding) |
+| Icon **and** label in the same tab | nothing in the DS does this — use `ScSelectionPill`, or two elements inside `children`-less layout of your own |
+| 6+ tabs, or tabs from data | `ScTabs` |
+| Settings/mobile-settings underline strip | `ScSettingsTabComp` |
+| A segmented control that is a saved form value | `ScTabField` |
+| Accessible segmented control (real buttons, `aria-pressed`) | `ScSelectionPill` / `ScSelectionPillGroup` |
+| A plain action | `ScButton`; a bare icon action → `ScOnlyIcon` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSettingsTabComp` — underline tab whose `active` is a **boolean** | `ScTabComp`'s `active` is the string `"true"`/`"false"` |
+| `ScTabs` — the whole pill row, driven by `tabs` + `activeTab` | `ScTabComp` is one cell and knows nothing about its siblings |
+| `ScTabSwitcher` — the container | `ScTabComp` is the content |
+| `ScTabField` — label + 2-tab switcher, already composed | Don't rebuild it out of `ScTabComp`s |
+
+### The tab family at a glance
+
+| Component | Shape | Selection API | Root | Spreads DOM props? |
+|---|---|---|---|---|
+| `ScTabComp` | one tab cell | `active="true" \| "false"` (strings) | `div` | ✅ |
+| `ScTabSwitcher` | 2–5 slot container | none — children own it | `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` | ❌ |
+| `ScSelectionPill` | one segmented pill | `selected` (boolean) + `onSelect(value)` | `button[type="button"][aria-pressed]` | ✅ |
+| `ScSelectionPillGroup` | segmented pill row | `value` + `onChange(value)` | `div[role="tablist"]` of `button`s | ✅ |
+
+---
+
+## 4. Why to use it
+
+- **The active skin is a token pair.** `--alias-fill-base-basehover` fill +
+  `--alias-text-and-icons-inverse` label resolves correctly in both themes — the
+  single most common hand-rolled-toggle bug is a selected state that turns
+  white-on-white in light mode.
+- **The type ramp changes with state**, not just the colour: idle is `text-sm-regular`
+  (400), active is `text-sm-medium` (500). Hand-rolled toggles forget the weight
+  change and the control reads flat.
+- **Props are spread**, so `role="tab"` / `aria-selected` / `data-testid` are
+  available — this component can be made accessible, unlike `ScTabs`.
+- **It composes into `ScTabSwitcher`, `ScTabField`, `ScProfilePopup`** — one visual
+  change to the tab cell updates the theme switcher, the teams filter and the PLP
+  toggle at once.
+
+---
+
+## Gotchas
+
+**1. `active` is a string.** `active={true}` is a type error; `active={String(x)}`
+compiles but isn't narrowed. Use a ternary.
+
+```tsx
+// WRONG
+<ScTabComp text="Active" active={tab === "active"} />
+
+// RIGHT
+<ScTabComp text="Active" active={tab === "active" ? "true" : "false"} />
+```
+
+**2. Placeholder defaults.** `icon` is `SiconHome`, `text` is `"Tab"`. `type="icon-only"`
+without an `icon` ships a home glyph; `type="text-only"` without `text` ships "Tab".
+
+**3. An unrecognised `type` renders an empty tab.** The body is two exclusive
+`type === …` checks, so anything outside the union produces a clickable blank.
+
+```tsx
+// WRONG — casts past the type and renders NOTHING inside the tab
+<ScTabComp type={"default" as "icon-only" | "text-only"} icon={<Zap />} text="Fast" />
+
+// RIGHT — pick a side
+<ScTabComp type={showLabels ? "text-only" : "icon-only"} icon={<Zap />} text="Fast" />
+```
+
+(There is a live instance of the wrong form in Photogenix's `QualityToggle.tsx` —
+when labels are enabled, the tab body is empty.)
+
+**4. There is no icon+text variant.** `type` is exclusive; passing both props only
+means one of them is ignored.
+
+**5. Active does not recolour your icon.** The stylesheet only retargets `.tabText`.
+Every host call site switches the icon colour manually — do the same, using
+`--alias-text-and-icons-inverse` when active.
+
+```tsx
+// WRONG — icon stays muted on the light active fill (poor contrast)
+<ScTabComp type="icon-only" active="true" icon={<SiconGrid size={20} />} />
+
+// RIGHT
+<ScTabComp type="icon-only" active="true"
+  icon={<SiconGrid size={20} color="var(--alias-text-and-icons-inverse)" />} />
+```
+
+**6. Inside `ScTabSwitcher` you must pass `style={{ flex: 1 }}`.** The switcher's
+`flex: 1` override lands on the *default* children it creates itself, via a class you
+don't get. A custom child keeps `align-self: stretch; flex-shrink: 0` and sizes to its
+content, so tabs come out unequal widths.
+
+**7. It's a `div` with `cursor: pointer`.** No `role`, no `tabIndex`, no
+`aria-selected`, no Enter/Space handling. Add them yourself (props are spread) if the
+control matters for keyboard users.
+
+**8. `className` is concatenated unguarded** — omit it and the class string contains
+the literal `"undefined"`.
+
+**9. `align-self: stretch` on the root** means it fills its parent's cross axis. In a
+flex-column parent it goes full width; that's usually not what a tab wants.
+
+**10. The label has a trailing space** (`{text} ` in JSX), so
+`textContent === "Active "`.
+
+---
+
+## In the wild
+
+```jsx
+// catalogix/dashboard  app/containers/StoresListing/index.jsx:306
+<ScTabComp
+  type="icon-only"
+  active={view === "grid" ? "true" : "false"}
+  role="tab"
+  aria-label="Grid view"
+  aria-selected={view === "grid"}
+  icon={
+    <SiconGrid
+      size={20}
+      color={view === "grid"
+        ? "var(--alias-text-and-icons-inverse)"
+        : "var(--alias-text-and-icons-tertiary)"}
+    />
+  }
+  onClick={() => changeView("grid")}
+/>
+```
+
+```tsx
+// cxo-dashboard  src/app/components/teams-content.tsx:1174
+<ScTabComp
+  text="Active"
+  type="text-only"
+  active={activeTab === "active" ? "true" : "false"}
+  onClick={() => setActiveTab("active")}
+  style={{ flex: 1 }}
+/>
+```
+
+---
+
+## Related
+
+- `ScTabSwitcher` — the bordered container; pass these in via `component`…`component5`.
+- `ScTabField` — a labelled form field that builds a 2-tab switcher out of these.
+- `ScTabs` — data-driven N-tab pill bar when 5 isn't enough.
+- `ScSettingsTabComp` — underline tab for settings strips (boolean `active`).
+- `ScSelectionPill` / `ScSelectionPillGroup` — accessible segmented alternative.
+- `@streamoid/icons` — the `Sicon*` set; check `packages/icons/ICONS.md` first.

package/dist/docs/ScTabField.md

@@ -0,0 +1,258 @@
+---
+component: ScTabField
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div
+tags: [tab, field, form, segmented, single-select, role-picker, two-choice, switcher]
+related: [ScTabSwitcher, ScTabComp, ScCheckField, ScTextField, ScSelectionPillGroup, ScTabs]
+do_not_confuse_with: [ScTabSwitcher, ScTabComp, ScTabs, ScSettingsTabComp, ScSelectionPillGroup, ScCheckField]
+used_by: [cxo]
+---
+
+# ScTabField
+
+**A labelled single-choice form field rendered as a segmented switcher.** Muted
+caption on top, a bordered `ScTabSwitcher` underneath holding two `ScTabComp` tabs.
+Built for form stacks — "Role: Admin | Member" — not for page navigation.
+
+## TL;DR for agents
+
+- **Reach for it when:** a form needs **exactly two** mutually exclusive values under
+  one caption, and you want it to match the `ScTextField` / `ScCheckField` rhythm.
+- **Don't reach for it when:** you have 3+ options (only two are wired — see
+  Gotcha 2), you're building a page/panel tab bar (→ `ScTabs` / `ScTabSwitcher`), or
+  you need multi-select (→ `ScCheckField`).
+- **Four things that will bite you:**
+  1. **Only `tabs[0]` and `tabs[1]` get wired.** A third entry renders a dead
+     placeholder tab reading **"Tab"**.
+  2. Omit `tabs` entirely and you ship **two placeholder tabs both labelled "Tab"**.
+  3. `label` defaults to `"Label"` ⚠️.
+  4. It does **not** extend `HTMLAttributes` — `style`, `id`, `data-*`, `onClick`
+     are silently unavailable (the rest prop is collected and thrown away).
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScTabField } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScTabField
+  label="Role"
+  tabs={[
+    { label: "Admin", value: "admin" },
+    { label: "Member", value: "member" },
+  ]}
+  activeTab={role}
+  onTabChange={setRole}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | `"Label"` | ⚠️ Real default. Muted caption (`--alias-text-and-icons-tertiary`, text-sm), fixed 1.25rem height — it does not wrap. |
+| `tabs` | `{ label: string; value: string }[]` | – | **Only the first two entries are rendered as live tabs.** `tabs.length` is passed straight through as `ScTabSwitcher`'s `tabCount`. |
+| `activeTab` | `string` | – | Compared against each tab's `value` to set `active`. Controlled — no internal state. |
+| `onTabChange` | `(value: string) => void` | – | Fires with the clicked tab's `value`. |
+| `className` | `string` | – | Concatenated onto the outer column (not the switcher). |
+
+⚠️ `IScTabFieldProps` does **not** extend `React.HTMLAttributes`. The component
+destructures `...props` and never spreads it, so even if you cast around the types
+nothing reaches the DOM. `className` is the only passthrough.
+
+### What renders for each `tabs` length
+
+| `tabs.length` | Result |
+|---|---|
+| `undefined` (prop omitted) | Default `ScTabSwitcher`: **two placeholder `ScTabComp`s labelled "Tab"**, the first `active="true"`, neither clickable |
+| 1 | One live tab + **one placeholder "Tab"** (slot 2 falls back) |
+| 2 | ✅ The intended case: two live tabs |
+| 3–5 | Two live tabs + `(length − 2)` **dead placeholder "Tab"** tabs |
+| >5 | Two live tabs only; `tabCount` is out of range so slots 3–5 don't render |
+
+### Recipes
+
+```tsx
+// The CXO idiom — role picker in a mobile invite form, typed value
+<ScTabField
+  label="Role"
+  tabs={[
+    { label: "Admin", value: "admin" },
+    { label: "Member", value: "member" },
+  ]}
+  activeTab={role}
+  onTabChange={(v) => setRole(v as "admin" | "member")}
+  className="w-full shrink-0"
+/>
+
+// THREE options? Don't use ScTabField. Drive ScTabSwitcher directly:
+<ScTabSwitcher
+  tabCount="3"
+  component={<ScTabComp text="Day"   type="text-only" active={p === "day"   ? "true" : "false"} onClick={() => setP("day")}   style={{ flex: 1 }} />}
+  component2={<ScTabComp text="Week" type="text-only" active={p === "week"  ? "true" : "false"} onClick={() => setP("week")}  style={{ flex: 1 }} />}
+  component3={<ScTabComp text="Month" type="text-only" active={p === "month" ? "true" : "false"} onClick={() => setP("month")} style={{ flex: 1 }} />}
+/>
+
+// …and add the caption yourself if it must look like a field
+<div style={{ display: "flex", flexDirection: "column", gap: 4, width: "100%" }}>
+  <div style={{ color: "var(--alias-text-and-icons-tertiary)", fontSize: "0.875rem" }}>Period</div>
+  <ScTabSwitcher tabCount="3" /* …components… */ />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO's mobile teams popups** — the "Role" field in `mobile-teams-invite-popup`
+  and `mobile-teams-manage-popup`, directly above `ScCheckField` ("Permission") and
+  `ScAppField` ("App permission").
+- Any **two-way choice inside a vertical form stack** where the caption and the
+  bordered container must line up with `ScTextField` / `ScCheckField` /
+  `ScOnlyField`. Those share the caption style, the `--spacing-xs` gap and the
+  `--radius-xl` container.
+
+It composes `ScTabSwitcher` → `ScTabComp`. Nothing else in the DS renders it.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- There are **exactly two** values, both worth showing at once.
+- The value is a **form value** (staged, saved on submit), not a view switch.
+- The control must read as a field: caption above, bordered container below.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| 3–5 options | `ScTabSwitcher` + `ScTabComp` (supply `component3`…`component5`) or `ScSelectionPillGroup` |
+| A full-width in-page tab bar | `ScTabs` |
+| A compact view toggle in a page header (not a form) | `ScTabSwitcher` + `ScTabComp` |
+| The settings-page tab strip | `ScSettingsTabComp` / `ScSettingsNav` |
+| Filter pills over a list | `ScSelectionPillGroup` |
+| Multi-select booleans under one caption | `ScCheckField` |
+| A long list of single choices | `ScRadio` rows, or `ScSelect` |
+| An on/off setting | `ScToggleSwitch` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScTabSwitcher` — the bordered segmented container; takes `component`…`component5` and supports 2–5 tabs | `ScTabField` is that container **plus a caption**, capped at 2 live tabs |
+| `ScTabComp` — one tab inside the switcher (`text-only` / `icon-only`, `active` as a **string**) | `ScTabField` builds these for you |
+| `ScTabs` — the in-page tab bar for navigating panel content | Not a form field |
+| `ScSettingsTabComp` — the settings-page tab strip | Different surface |
+| `ScSelectionPillGroup` — free-standing pills, no caption, no container | Different look, same job for filters |
+| `ScCheckField` — same caption + container chrome, but **multi**-select | Both end in "…Field"; only this one is single-choice |
+
+---
+
+## 4. Why to use it
+
+- **Field rhythm for free.** Caption colour/size, `--spacing-xs` gap, `--radius-xl`
+  container and the `0.03125rem --alias-border-divider` hairline are the same tokens
+  the other DS fields use, so a mixed stack aligns without call-site CSS.
+- **Equal-width tabs.** The field passes `style={{ flex: 1 }}` into each `ScTabComp`
+  it builds, so "Admin" and "Member" are the same width instead of hugging their text.
+  (If you drive `ScTabSwitcher` yourself you must add that `flex: 1` — the switcher's
+  own `flex: 1 !important` class is applied only to its *fallback* tabs, not to
+  components you pass in.)
+- **The `active` plumbing is done.** `ScTabComp`'s `active` is a `"true"`/`"false"`
+  **string** (a Figma-ism that is easy to get wrong by hand); this field derives it
+  from `activeTab === tab.value` for you.
+- **Theme-correct container** — `--alias-surface-base` keeps the switcher distinct
+  from the page in both themes.
+
+---
+
+## Gotchas
+
+**1. No `tabs` → two dead tabs labelled "Tab".** The fallback renders a bare
+`ScTabSwitcher`, whose own fallback is two default `ScTabComp`s (`text = "Tab"`), the
+first hardcoded `active="true"`, with no click handlers.
+
+```tsx
+// WRONG — ships "Label" over two inert tabs reading "Tab"
+<ScTabField />
+
+// RIGHT
+<ScTabField label="Role" tabs={ROLES} activeTab={role} onTabChange={setRole} />
+```
+
+**2. Only the first two tabs are wired.** `tabCount` becomes `String(tabs.length)`,
+so slots 3–5 *render* — but `component3`…`component5` are never supplied, so each
+falls back to a placeholder `ScTabComp` reading **"Tab"** with no `onClick`.
+
+```tsx
+// WRONG — renders: Admin | Member | Tab   (the third is dead)
+<ScTabField label="Role" tabs={[
+  { label: "Admin", value: "admin" },
+  { label: "Member", value: "member" },
+  { label: "Viewer", value: "viewer" },
+]} activeTab={role} onTabChange={setRole} />
+
+// RIGHT — 3+ options: drive ScTabSwitcher directly (see Recipes)
+```
+
+**3. `label` defaults to `"Label"`.** ⚠️
+
+**4. No DOM passthrough at all.** The interface doesn't extend `HTMLAttributes`, and
+the collected `...props` is never spread. No `style`, `id`, `data-testid`, `onClick`,
+`aria-*`. Wrap it in your own div when you need any of those. (`className` does work
+— CXO passes Tailwind classes through it.)
+
+**5. Fully controlled.** No internal state: if `onTabChange` doesn't move
+`activeTab`, the highlight never moves.
+
+**6. `activeTab` with no match = nothing active.** Unlike the no-`tabs` fallback
+(which force-activates the first tab), a mismatched `activeTab` leaves *both* tabs
+inactive. Initialise your state to a real `value`.
+
+**7. `className` lands on the outer column, not the switcher.** There is no
+`switcherClassName`; restyle via a descendant selector from your own class.
+
+**8. `tabs` is keyed positionally.** `tabs[0]`/`tabs[1]` are read by index, so
+reordering the array reorders the meaning of the tabs — fine, but don't rely on
+`value` alone determining position.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/mobile-teams-invite-popup.tsx:137
+<ScTabField
+  label="Role"
+  tabs={[
+    { label: "Admin", value: "admin" },
+    { label: "Member", value: "member" },
+  ]}
+  activeTab={role}
+  onTabChange={(v) => setRole(v as "admin" | "member")}
+  className="w-full shrink-0"
+/>
+```
+
+---
+
+## Related
+
+- `ScTabSwitcher` — the container this wraps; use it directly for 3–5 tabs.
+- `ScTabComp` — one tab; note `active` is the string `"true"`/`"false"`.
+- `ScCheckField` — the multi-select sibling with identical field chrome.
+- `ScTextField` / `ScOnlyField` — the text fields it stacks with.
+- `ScTabs` / `ScSettingsTabComp` — navigation tab bars, not form fields.
+- `ScSelectionPillGroup` — pill-shaped single-choice for filters and views.