@streamoid/ui 0.6.17 → 0.6.19

package/dist/docs/ScTabs.md

@@ -0,0 +1,268 @@
+---
+component: ScTabs
+package: "@streamoid/ui"
+category: layout
+status: stable
+renders: div
+tags: [tabs, tab-bar, pills, filter, segmented, n-tabs, view-switch, wrap, compact]
+related: [ScTabComp, ScTabSwitcher, ScTabField, ScSettingsTabComp, ScSelectionPillGroup]
+do_not_confuse_with: [ScTabComp, ScTabSwitcher, ScTabField, ScSettingsTabComp, ScSelectionPill]
+used_by: [catalogix]
+required_props: [tabs]
+---
+
+# ScTabs
+
+**The data-driven N-tab pill bar.** You hand it an array — strings or
+`{ label, value }` — and it renders one rounded pill per entry, calling
+`onClickTab(value)` on click. It is the only tab component in the library that scales
+past five tabs and the only one that takes its tabs as data.
+
+## TL;DR for agents
+
+- **Reach for it when:** you have an arbitrary-length list of views/filters (6, 12,
+  20 tabs) and want them as a wrapping row of pills.
+- **Don't reach for it when:** you have exactly 2–5 tabs in a bordered segmented
+  control (→ `ScTabSwitcher` + `ScTabComp`), an underlined settings strip
+  (→ `ScSettingsTabComp`), or a segmented control inside a form (→ `ScTabField`).
+- **Four things that will bite you:**
+  1. The **active pill's background is `--alias-surface-canvas`** — the page floor
+     colour. On a canvas-coloured background, "active" is invisible. Put it on a card.
+  2. `activeTab` is compared against the **value**, never the label.
+  3. Labels are transformed: `_` → space, and CSS `text-transform: capitalize`.
+     You cannot render a lowercase label.
+  4. **No props are spread.** No `style`, no `id`, no `aria-*`, no `data-*` — and no
+     roles, no keyboard: they're `<div onClick>`s.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScTabs } from "@streamoid/ui";
+import type { ScTab } from "@streamoid/ui";       // only if you type the array yourself
+import "@streamoid/ui/dist/index.css";            // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScTabs tabs={["all", "images", "videos"]} activeTab={tab} onClickTab={setTab} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `tabs` | `ScTab[]` where `ScTab = string \| { label?: string; value?: string }` | — | **Required.** Strings and objects can be mixed. For objects, `label` falls back to `value` and `value` falls back to `label`; both missing → an empty pill with value `""`. |
+| `activeTab` | `string` | – | Matched against each tab's **value**. Controlled — the component keeps no state. |
+| `onClickTab` | `(value: string) => void` | – | Called with the resolved value. Optional; omit and the pills are inert. |
+| `isAutoWidth` | `boolean` | `undefined` (→ full width) | `width: max-content` instead of `width: 100%`. |
+| `allowWrap` | `boolean` | `undefined` | `flex-wrap: wrap` + `row-gap: 8px`. Needed for long tab lists. |
+| `isCompact` | `boolean` | `undefined` | Denser pills: gap 12→8px, padding 6/12→4/10px, font 14→13px. |
+| `className` | `string` | – | Appended last (properly filtered — no stray `"undefined"`). |
+
+### Sizing / density matrix
+
+| Flag | Row | Pill |
+|---|---|---|
+| *(none)* | `width: 100%`, `gap: 12px`, no wrap | `padding: 6px 12px`, `14px/20px` |
+| `isAutoWidth` | `width: max-content` | unchanged |
+| `allowWrap` | wraps, `row-gap: 8px` | unchanged |
+| `isCompact` | `gap: 8px` | `padding: 4px 10px`, `13px/18px` |
+
+### Recipes
+
+```tsx
+// Long filter list above a grid — wrap and go compact
+<ScTabs
+  tabs={TAB_OPTIONS}          // e.g. ["all", "in_progress", "failed", …]
+  activeTab={activeTab}
+  onClickTab={setActiveTab}
+  allowWrap
+  isCompact
+/>
+
+// Object tabs: display text differs from the state value
+<ScTabs
+  tabs={[
+    { label: "In progress", value: "in_progress" },
+    { label: "Failed", value: "error" },
+  ]}
+  activeTab={status}          // must be "in_progress" / "error", NOT the label
+  onClickTab={setStatus}
+/>
+
+// Shrink-wrapped, inside a header row next to other controls
+<div className="flex items-center justify-between">
+  <ScTabs tabs={views} activeTab={view} onClickTab={setView} isAutoWidth />
+  <ScButton text="Export" variant="outline" size="sm" />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **Above a list or grid that it filters** — Catalogix's Assets → Activity panel is
+  the live consumer, via a thin local `Tabs` wrapper that just forwards props.
+- **Panel/section switching** where the set of sections comes from data (a config,
+  an API response, a taxonomy) rather than being hardcoded in JSX.
+- Anywhere the tab count exceeds five: `ScTabSwitcher` physically cannot render a
+  sixth tab.
+
+Catalogix is the only host app using it today.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The tab list is **dynamic** or **long** (data-driven, wrapping).
+- You want a controlled `activeTab` / `onClickTab` pair rather than wiring
+  `active`/`onClick` on every individual tab.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| 2–5 tabs in the bordered "pill container" segmented control | `ScTabSwitcher` with `component`…`component5` slots of `ScTabComp` |
+| One individual tab cell (icon-only or text-only) | `ScTabComp` |
+| A segmented control **inside a form**, with a field label | `ScTabField` |
+| Settings / mobile-settings underline tab strip | `ScSettingsTabComp` |
+| The static settings left-nav card | `ScSettingsNav` (legacy — see its README) |
+| Filter pills whose selected state must be a dark fill + inverse text | `ScSelectionPillGroup` |
+| A taxonomy tree node with a count and chevron | `ScTaxonomyPill` |
+| Non-interactive status chips | `ScBadges` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScTabComp` — a single tab cell whose `active` prop is the **string** `"true"`/`"false"` | `ScTabs` owns the whole row and takes `activeTab` as a value string |
+| `ScTabSwitcher` — a fixed 2–5 slot container with a border and background | `ScTabs` is a borderless, unbounded pill row |
+| `ScSelectionPill` — a real `<button aria-pressed>` | `ScTabs` renders `<div onClick>` with no a11y |
+| `ScSettingsTabComp` — underline tab, `active` is a **boolean** | `ScTabs` pills are filled, not underlined |
+
+### The tab family at a glance
+
+| Component | Shape | Selection API | Root | Spreads DOM props? |
+|---|---|---|---|---|
+| `ScTabs` | N pills, data-driven | `activeTab` + `onClickTab(value)` | `div` > `div` | ❌ |
+| `ScTabComp` | one tab cell | `active="true" \| "false"` (strings) | `div` | ✅ |
+| `ScTabSwitcher` | 2–5 slot container | none — children own it | `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 only tab component that takes data.** Every other tab in the library is a
+  hand-placed slot; this one maps an array, so config-driven screens don't need N
+  hardcoded JSX branches.
+- **`allowWrap` + `isCompact` solve the long-list problem** that `ScTabSwitcher`
+  can't: a 12-tab activity filter fits in two rows without horizontal scroll.
+- **String tabs are tolerated on purpose.** `"in_progress"` renders as
+  "In Progress" without a formatting helper at the call site — which is exactly why
+  Catalogix could drop its own `Tabs` implementation and keep its API.
+- **Token-styled**, so the active pill and the idle border track the theme instead of
+  a hardcoded grey.
+
+---
+
+## Gotchas
+
+**1. The active pill can be invisible.** `.active { background: var(--alias-surface-canvas) }`
+and the idle pill's border is the *same* token. `surface-canvas` is the page floor
+(`#f1f1f1` in light, near-black in dark), so on a canvas-coloured background the
+selected pill has no contrast against its surroundings.
+
+```tsx
+// WRONG — page background is the canvas; "active" reads as nothing
+<main style={{ background: "var(--alias-surface-canvas)" }}>
+  <ScTabs tabs={views} activeTab={view} onClickTab={setView} />
+</main>
+
+// RIGHT — sit it on a raised surface
+<section style={{ background: "var(--alias-surface-base)" }}>
+  <ScTabs tabs={views} activeTab={view} onClickTab={setView} />
+</section>
+```
+
+**2. `activeTab` matches the value, not the label.**
+
+```tsx
+// WRONG — nothing ever looks active
+<ScTabs tabs={[{ label: "In progress", value: "in_progress" }]} activeTab="In progress" />
+
+// RIGHT
+<ScTabs tabs={[{ label: "In progress", value: "in_progress" }]} activeTab="in_progress" />
+```
+
+**3. Your label text is rewritten.** Underscores become spaces
+(`label.replace(/_/g, " ")`) and `text-transform: capitalize` title-cases every word.
+`"api_key"` renders as "Api Key". If you need exact casing (`"API key"`), this
+component cannot give it to you.
+
+**4. Nothing is spread onto the DOM.** `style`, `id`, `data-testid`, `aria-label`,
+`role` are all dropped — the signature only accepts the seven props above.
+Wrap it in your own div for layout and test hooks.
+
+**5. No a11y and no keyboard.** Pills are `<div onClick>`: not focusable, no
+`role="tablist"`/`role="tab"`, no `aria-selected`, no arrow-key navigation. If the
+surface needs to be accessible, supply the roles on a wrapper and consider
+`ScSelectionPillGroup` (real buttons with `aria-pressed`) instead.
+
+**6. It is full width by default.** `width: 100%` — in a flex row it will eat the
+available space and push siblings out. Pass `isAutoWidth` when it shares a row.
+
+**7. Empty/duplicate tabs fail quietly.** `{}` produces a blank pill with value `""`;
+if `activeTab` is `""` (a common "no filter" sentinel) that blank pill renders
+active. Two tabs with the same value both light up. React keys are
+`` `${idx}-${value}` ``, so duplicates don't warn.
+
+**8. `isAutoWidth` / `allowWrap` / `isCompact` are un-defaulted booleans**, so
+`undefined` means "off". There is no way to force full width once `isAutoWidth` is
+`true` other than not passing it.
+
+---
+
+## In the wild
+
+```jsx
+// catalogix/dashboard  app/components/Tabs/index.jsx:10
+<ScTabs
+  tabs={props.tabs}
+  activeTab={props.activeTab}
+  onClickTab={props.onClickTab}
+  isAutoWidth={props.isAutoWidth}
+  allowWrap={props.allowWrap}
+  isCompact={props.isCompact}
+/>
+
+// …consumed at catalogix/dashboard  app/components/Assets/Activity/index.jsx:1209
+<Tabs
+  tabs={TAB_OPTIONS}
+  activeTab={activeTab}
+  allowWrap={true}
+  isCompact={true}
+  onClickTab={setActiveTab}
+/>
+```
+
+---
+
+## Related
+
+- `ScTabComp` — one tab cell; the atom of the 2–5 tab segmented control.
+- `ScTabSwitcher` — the bordered 2–5 slot container for `ScTabComp`s.
+- `ScTabField` — form field wrapping a 2-tab switcher with a label.
+- `ScSettingsTabComp` — the underline tab used by settings strips.
+- `ScSelectionPillGroup` — accessible segmented pills (real buttons) when a11y matters.
+- `ScTaxonomyPill` — hierarchy chips, visually adjacent but structurally unrelated.

package/dist/docs/ScTaxonomyPill.md

@@ -0,0 +1,263 @@
+---
+component: ScTaxonomyPill
+package: "@streamoid/ui"
+category: feed-taxonomy
+status: stable
+renders: div
+tags: [taxonomy, hierarchy, tree, node, chip, pill, expand, collapse, chevron, catalogix, ontology]
+related: [ScSelectionPill, ScSelectionPillGroup, ScValueMappingL1, ScBadges, ScDefaultCard]
+do_not_confuse_with: [ScSelectionPill, ScSelectionPillGroup, ScBadges, ScSelection]
+used_by: [catalogix]
+---
+
+# ScTaxonomyPill
+
+**The node chip of a taxonomy tree.** One component with three mutually exclusive
+renders: a labelled node (`pill`), a "N more children" affordance (`expand`, count +
+down chevron), and a "fold this level away" affordance (`collapse`, up chevron only).
+
+## TL;DR for agents
+
+- **Reach for it when:** you're drawing a category/ontology tree and need the node
+  chips and their expand/collapse controls to look like one family.
+- **Don't reach for it when:** you want a segmented single-choice row
+  (→ `ScSelectionPill` / `ScSelectionPillGroup`), a non-interactive status or count
+  chip (→ `ScBadges`), or a flat selectable list row (→ `ScValueMappingL1`).
+- **Four things that will bite you:**
+  1. `label` defaults to **`"All Products"`** and `count` defaults to **`3`**. Both
+     are real Catalogix copy, so a forgotten prop looks like working UI.
+  2. `type` decides which props are read. `expand` ignores `label`; `collapse`
+     ignores both.
+  3. It's a `<div>` with `cursor: pointer` and **no click handling of its own** — no
+     `role`, no `tabIndex`, no `onKeyDown`. The host wraps it.
+  4. `expand` and `collapse` are **two separate renders you choose between**, not a
+     toggle. There is no `expanded` boolean.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScTaxonomyPill } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScTaxonomyPill type="pill" label="Topwear" />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `type` | `"pill"` \| `"expand"` \| `"collapse"` | `"pill"` | Which of the three renders you get. See the matrix below. |
+| `state` | `"default"` \| `"hover"` | `"default"` | Forced visual state. Real `:hover` applies the same skin, so you rarely need this outside screenshots/Figma parity. |
+| `label` | `string` | `"All Products"` | ⚠️ Has a real default. **Only read when `type="pill"`.** Never wraps (`white-space: nowrap`). |
+| `count` | `number \| string` | `3` | ⚠️ Has a real default. **Only read when `type="expand"`.** `string` is allowed, so `"12+"` works. |
+| `className` | `string` | – | Appended after the internal classes. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `onClick`, `role`, `tabIndex`, `aria-*`, `style` all land on the root div. |
+
+### What renders for each `type`
+
+| `type` | Renders | Props read | Props ignored | Inner padding |
+|---|---|---|---|---|
+| `pill` | the `label` in a `text-sm` span | `label` | `count` | `0.5rem 1rem` |
+| `expand` | the `count`, then a `SiconDown` chevron | `count` | `label` | `0.125rem 0.25rem 0.125rem 0.5rem` |
+| `collapse` | a `SiconUp` chevron, nothing else | – | `label`, `count` | `0.25rem` |
+
+Both chevrons are hard-coded and locked to `0.75rem` square with `!important`.
+
+### Recipes
+
+```tsx
+// A node with its expand affordance (the host owns both click targets)
+<div className="node-row">
+  <div role="button" tabIndex={0} onClick={() => selectNode(node)}
+       onKeyDown={(e) => (e.key === "Enter" || e.key === " ") && selectNode(node)}>
+    <ScTaxonomyPill type="pill" label={node.groupName} />
+  </div>
+
+  {node.groups.length > 0 && !isExpanded && (
+    <div role="button" tabIndex={0} aria-label={`Show ${node.groups.length} sub-groups`}
+         onClick={() => expand(node)}>
+      <ScTaxonomyPill type="expand" count={node.groups.length} />
+    </div>
+  )}
+</div>
+
+// The fold-away control, once the level is open
+{isExpanded && (
+  <div role="button" tabIndex={0} aria-label="Collapse level" onClick={() => collapse(node)}>
+    <ScTaxonomyPill type="collapse" />
+  </div>
+)}
+
+// The synthetic root node of an empty taxonomy — the default label IS the copy here
+<ScTaxonomyPill type="pill" label="All Products" />
+
+// Non-numeric count
+<ScTaxonomyPill type="expand" count="99+" />
+```
+
+---
+
+## 2. Where to use it
+
+- **Catalogix taxonomy / ontology trees.** `RecursiveTaxonomyTree` renders all three
+  types: `pill` per node, `expand` on any node with hidden children, `collapse` on the
+  open branch.
+- **The Create-Taxonomy hierarchy page**, where a single `pill` labelled
+  "All Products" stands in as the root before any taxonomy exists.
+- Any future **hierarchy browser** — attribute trees, category maps, folder trees —
+  where nodes are connected by drawn lines and each node needs a compact chip.
+
+It composes nothing and it is never rendered *by* another DS component; hosts place
+it inside their own tree layout (the connector lines, indentation and click targets
+are all host CSS).
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The chips sit in a **hierarchy**: nodes plus per-branch expand/collapse controls.
+- You want the node chip, the count affordance and the fold control to share one
+  radius, one fill and one hover behaviour.
+- The count next to a node means **"children hidden behind this"**, not a status.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Segmented single-choice row (2–5 mutually exclusive views) | `ScSelectionPillGroup` (+ `ScSelectionPill`) |
+| A pill that needs to look **selected** and report it to a screen reader | `ScSelectionPill` — this component has no `selected` state and no `aria-pressed` |
+| Non-interactive status / count badge | `ScBadges` |
+| Flat vertical list of selectable values | `ScValueMappingL1` |
+| "Pick one of these options" card with a title and description | `ScDefaultCard` |
+| A chevron-only disclosure button in a toolbar or form | `ScOnlyIcon` — `type="collapse"` is a tree control, not a generic icon button |
+| An option row in the agent chat transcript | `ScSelection` / `ScSelectionList` (chat runtime, unrelated) |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSelectionPill` — real `<button type="button">`, `aria-pressed`, `selected` skin, `onSelect(value)` | `ScTaxonomyPill` is a `<div>` with no selection concept at all |
+| `ScSelectionPillGroup` — renders and tracks a row of pills for you | This component renders exactly one chip and tracks nothing |
+| `ScBadges` — count/status chip that is *not* clickable | This chip has `cursor: pointer` baked in, so it always looks clickable |
+| `ScSelection` / `ScSelectionList` — chat-runtime option rows | Different family, different surface (stream-agent) |
+
+Both `ScTaxonomyPill` and `ScSelectionPill` default `label` to **`"All Products"`**.
+That shared default is the single easiest way to grab the wrong one and not notice.
+Deciding rule: *pills in a tree* → `ScTaxonomyPill`; *pills in a row that filters
+something* → `ScSelectionPill`.
+
+---
+
+## 4. Why to use it
+
+- **One chip family across three roles.** Node, count and fold controls share
+  `--alias-fill-neutral-neutralactive`, `--alias-border-default` and the same
+  `radius-xl`, so a tree reads as one object instead of three widgets.
+- **The hover token is the DS's neutral hover**
+  (`fill-neutral-neutralhovertoactive`), matching pills, menu rows and list items
+  elsewhere — hand-rolled trees usually invent a different hover grey per screen.
+- **Chevron colour follows the chip.** The icons are rendered with an explicit
+  `color="currentColor"` prop (no `cloneElement`), `.icon` is `color: inherit`, and
+  the chip sets `color` from
+  `--alias-text-and-icons-primary`, so chevrons never drift from the label colour or
+  break in light mode.
+- **`count` accepts a string**, so overflow formatting (`"99+"`) needs no wrapper.
+
+---
+
+## Gotchas
+
+**1. `label` defaults to `"All Products"`, `count` defaults to `3`.** Forget either
+and you ship plausible-looking placeholder data.
+
+```tsx
+// WRONG — renders "All Products"
+<ScTaxonomyPill type="pill" />
+
+// WRONG — renders "3" regardless of the real child count
+<ScTaxonomyPill type="expand" />
+
+// RIGHT
+<ScTaxonomyPill type="pill" label={node.groupName} />
+<ScTaxonomyPill type="expand" count={node.groups.length} />
+```
+
+**2. `type` silently drops the props it doesn't use.** `label` on an `expand` pill and
+either prop on a `collapse` pill are dead code.
+
+```tsx
+// WRONG — the label never renders; you get the count "7" and a chevron
+<ScTaxonomyPill type="expand" label="Topwear" count={7} />
+```
+
+**3. `type="collapse"` has no accessible name at all.** It renders a bare chevron
+`<svg>` — no text, no `aria-label`, no `<title>`. Put `aria-label` on the pill (or on
+your wrapper) or screen readers announce nothing.
+
+**4. It doesn't handle clicks.** `cursor: pointer` is styling only. `onClick` works
+because `...props` is spread onto the div, but you still get no keyboard access —
+add `role="button"`, `tabIndex={0}` and `onKeyDown`. The Catalogix tree wraps each
+pill in its own handler div and calls `e.stopPropagation()` on the expand control so
+the node's own click doesn't also fire.
+
+**5. There is no `expanded` prop.** `expand` and `collapse` are separate renders you
+switch between based on your own state. A single `<ScTaxonomyPill type="expand">` will
+never turn into a collapse control by itself.
+
+**6. No `selected` / `active` state.** Unlike `ScValueMappingL1` (`active`) and
+`ScSelectionPill` (`selected`), `state` is only `default | hover`. "This is the
+current node" styling must come from your `className`.
+
+**7. The chevron size is unoverridable.** The icons render at their own `size={24}`
+default, but `.icon { width: .75rem !important; height: .75rem !important }` clamps
+them to 12px and beats your className too. Don't try to scale it — and there's no
+icon prop, so you can't swap the glyph either.
+
+**8. Giving the root a width won't stretch the content.** The root is
+`display: inline-flex; flex-direction: column; align-items: flex-start`, so the
+padded inner block stays left-hugging inside a wider root. Equal-width pills need
+`min-width` on the *inner* content, which the DS doesn't expose — set `width` on the
+root **and** accept left alignment, or space the tree with the parent's layout.
+
+**9. `label` never wraps.** Long node names extend the chip horizontally and push the
+tree wide; there's no ellipsis and no `title` tooltip (unlike `ScValueMappingL1`).
+Truncate the string before passing it if your tree is width-constrained.
+
+---
+
+## In the wild
+
+```jsx
+// catalogix/dashboard  app/components/TaxonomyComponent/RecursiveTaxonomyTree/index.jsx:193
+<ScTaxonomyPill type="pill" label={node.groupName} />
+```
+
+```jsx
+// catalogix/dashboard  app/components/TaxonomyComponent/RecursiveTaxonomyTree/index.jsx:45
+return <ScTaxonomyPill type="expand" count={childrenCount} />;
+```
+
+```jsx
+// catalogix/dashboard  app/containers/CreateTaxonomy/HierarchyPage/index.jsx:307
+<ScTaxonomyPill type="pill" label="All Products" />
+```
+
+---
+
+## Related
+
+- `ScSelectionPill` / `ScSelectionPillGroup` — the segmented-row pill family; same shared `"All Products"` default label, completely different job.
+- `ScValueMappingL1` — flat selectable list row, when the data is a list rather than a tree.
+- `ScBadges` — when the chip is informational and must not look clickable.
+- `ScDefaultCard` — the "choose a taxonomy" option cards that sit on the screens leading into these trees.
+- `@streamoid/icons` — `SiconDown` / `SiconUp` are the chevrons this component hard-codes; see `packages/icons/ICONS.md`.