@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScRoleMobile.md

@@ -0,0 +1,199 @@
+---
+component: ScRoleMobile
+package: "@streamoid/ui"
+category: mobile
+status: stable
+renders: div
+tags: [mobile, role, admin, member, badge, chip, permission, label]
+related: [ScRole, ScBadges, ScTableListMobile, ScWorkspaceSwitchMobileV2, ScAccess]
+do_not_confuse_with: [ScRole, ScBadges, ScTaxonomyPill, ScSelectionPill]
+---
+
+# ScRoleMobile
+
+**A fixed 64×32 "Admin" / "Member" chip for mobile rows.** Two hardcoded looks: admin
+= blue info fill with blue text, member = neutral grey fill with grey text. The label
+text is derived from the `role` prop — there is no way to change the words.
+
+## TL;DR for agents
+
+- **Reach for it when:** a mobile list row or card needs the user's role as a chip
+  and the only two roles are admin and member.
+- **Don't reach for it when:** the desktop needs the same chip (→ `ScRole`, which has
+  a `label` prop), the label is anything other than Admin/Member (→ `ScBadges`), or
+  the chip is meant to be tappable/selectable (→ `ScSelectionPill`).
+- **Three things that will bite you:**
+  1. **The label is hardcoded English**, computed as `role === "admin" ? "Admin" : "Member"`.
+     No `label` prop — unlike its desktop twin `ScRole`.
+  2. **`role` is the prop name, so you can never set the ARIA `role` attribute.**
+     The types intersect down to `"admin" | "member"`.
+  3. **Fixed `width: 64px; height: 32px`** — "Member" fits, longer words would not,
+     and it never fills its container.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScRoleMobile } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScRoleMobile role={member.permissions.role === "admin" ? "admin" : "member"} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `role` | `"admin"` \| `"member"` | `"admin"` | ⚠️ Defaults to **admin** — the more privileged value. Drives both the skin and the label text. |
+| `className` | `string` | – | Appended after internal classes. Unguarded concat — see Gotcha 4. |
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` | – | Spread onto the root `div`. Note `role` is consumed by this component, so the ARIA attribute is unavailable. |
+
+### What each value renders
+
+| `role` | Label | Background | Border | Text |
+|---|---|---|---|---|
+| `"admin"` | `Admin` | `--alias-fill-info-soft` | `--alias-border-infoplus` | `--alias-text-and-icons-infocont` |
+| `"member"` | `Member` | `--alias-fill-neutral-neutral` | `--alias-border-default` | `--alias-text-and-icons-tertiary` |
+
+Anything that isn't exactly `"admin"` falls to the member branch for the label, but the
+skin class is `styles["role-" + role]`, so a value outside the union produces an
+**unstyled** chip (no background, a `1px solid` border with no colour).
+
+### Recipes
+
+```tsx
+// Mapping a backend role that has more than two values
+<ScRoleMobile role={m.role === "admin" || m.role === "owner" ? "admin" : "member"} />
+
+// Need "Owner" / "Viewer" / "Billing" wording? This chip cannot do it — use ScBadges
+import { ScBadges } from "@streamoid/ui";
+<ScBadges text="Owner" variant="info" styleVariant="opaque" />
+
+// Announce it to assistive tech — you cannot pass role="…", so use aria-label on
+// the wrapper, or aria-label directly (the prop name collision only blocks `role`)
+<ScRoleMobile role="member" aria-label="Workspace role: Member" />
+```
+
+---
+
+## 2. Where to use it
+
+The role slot of a mobile list row or card — the mobile counterpart of the role column
+in a desktop members table. In practice its job is already done inline by the mobile
+components that need it: `ScTableListMobile`, `ScWorkspaceSettingsMobile` and
+`ScWorkspaceSwitchMobile` each render their **own** role badge rather than composing
+this one, so `ScRoleMobile` is only for rows you assemble yourself.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The role vocabulary really is just admin/member.
+- You are hand-assembling a mobile row and want the same chip metrics as the rest of
+  the mobile family.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Desktop members table / settings row | `ScRole` — same two types, **plus a `label` prop** |
+| Any other word ("Owner", "Viewer", "Pending", "Billing admin") | `ScBadges` (`text` + `variant` + `styleVariant`) |
+| A status chip that must change colour by state | `ScBadges` |
+| A tappable filter/segment chip | `ScSelectionPill` (+ `ScSelectionPillGroup`) |
+| A taxonomy tree node chip | `ScTaxonomyPill` |
+| Per-app access / permission icons | `ScAccess`, or the `accessIcons` / `permissionIcons` props of `ScTableListMobile` |
+| A whole member row (avatar, name, email, role, icons) | `ScTableListMobile` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScRole` — desktop twin. Prop is **`type`**, not `role`, and it has `label` so you can print any word | `ScRoleMobile` has neither |
+| `ScBadges` — the general status chip; any text, several variants | `ScRoleMobile` is two hardcoded words |
+| `ScSelectionPill` — interactive segmented pill with `aria-pressed` | `ScRoleMobile` is a static `div` |
+| The role badge inside `ScWorkspaceSwitchMobile` / `ScWorkspaceSettingsMobile` | Those are **internal** markup with their own metrics (80px wide, `--radius-xl`, always info-blue). This component is not what they use. |
+
+---
+
+## 4. Why to use it
+
+- **The two role skins are already decided** — info-soft/infoplus for admin,
+  neutral/default for member — matching how role is coloured everywhere else in the
+  product, so an admin looks like an admin on every screen.
+- **Fixed metrics mean lists line up.** 64×32 with `--radius-md` keeps the chip column
+  the same width down a list without you setting min-widths.
+- **One prop.** There is genuinely nothing to get wrong except the five gotchas below.
+
+If you need any flexibility at all — different words, more roles, colour by state —
+`ScBadges` is the right primitive and this component is a trap.
+
+---
+
+## Gotchas
+
+**1. The label is hardcoded English.** `"Admin"` / `"Member"` are literals in the
+render body. Do not use this component on a localised surface.
+
+```tsx
+// IMPOSSIBLE — there is no label prop (this is a type error)
+<ScRoleMobile role="admin" label="Administrateur" />
+
+// The desktop twin CAN do it
+<ScRole type="admin" label="Administrateur" />
+```
+
+**2. You cannot set the ARIA `role` attribute.** `role` is destructured as the
+component's own prop, and because the signature is
+`IScRoleMobileProps & React.HTMLAttributes<HTMLDivElement>`, the type narrows to
+`"admin" | "member"`:
+
+```tsx
+// TYPE ERROR — "status" is not assignable to "admin" | "member"
+<ScRoleMobile role="status" />
+
+// Workaround: aria-* still works, or wrap it
+<span role="status"><ScRoleMobile role="member" /></span>
+```
+
+**3. `role` defaults to `"admin"`.** Forgetting the prop grants everyone the
+privileged-looking chip. Always pass it explicitly.
+
+**4. `className` is concatenated unguarded.** Omit it and the root carries a literal
+`undefined` class. Cosmetic, but it breaks exact-class assertions.
+
+**5. An out-of-union `role` renders an unstyled chip.** `styles["role-" + role]` is
+`undefined` for anything else, and the base class sets `border: 1px solid` with no
+colour. TypeScript catches this; plain JS hosts (Catalogix, Photogenix) will not.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+To be precise: it is exported from `@streamoid/ui` but no host app renders it, and it
+is not agent-runtime — it is currently unused. Where it belongs is CXO's mobile teams
+screen; that screen instead passes a plain string to the row component
+(`cxo-dashboard/src/app/components/mobile-teams-content.tsx:311`,
+`role={member.permissions.role === "admin" ? "Admin" : "Member"}` on
+`ScTableListMobile`), which renders its own badge.
+
+---
+
+## Related
+
+- `ScRole` — the desktop twin; prop is `type`, and it accepts a custom `label`.
+- `ScBadges` — reach for this the moment the wording or colour must vary.
+- `ScTableListMobile` — the mobile member row; renders its own role badge.
+- `ScWorkspaceSettingsMobile` / `ScWorkspaceSwitchMobile` — also render their own
+  (always-blue, 80px) role badge rather than this chip.
+- `ScAccess` — per-app access rows, the other half of "what can this user do".

package/dist/docs/ScSelect.md

@@ -0,0 +1,270 @@
+---
+component: ScSelect
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div > button[aria-haspopup="listbox"] + div[role="listbox"]
+tags: [select, dropdown, picker, listbox, options, combobox, choice]
+related: [ScTextField, ScTabField, ScPopUpMenu, ScMenuOptions, ScMappingCard, ScSelectionPillGroup]
+do_not_confuse_with: [ScSelection, ScSelectionList, ScSelectionPill, ScSelectionPillGroup, ScPopUpMenu, ScMenuOptions]
+---
+
+# ScSelect
+
+**The DS-native dropdown.** A 48 px field-shaped `<button>` showing the selected
+label (or a placeholder) plus a chevron that rotates when open, and an
+absolutely-positioned `role="listbox"` panel of options — each option optionally
+carrying a second description line. It owns its own open/closed state and closes
+on an outside `mousedown`.
+
+## TL;DR for agents
+
+- **Reach for it when:** the user picks **one** value from a list that is too long
+  or too wordy for inline pills, and you want DS chrome without wiring a trigger
+  yourself.
+- **Don't reach for it when:** the menu must escape a clipping parent (it is
+  **not portalled**), you need multi-select/search/async options, or the "menu" is
+  really a list of *actions* (→ `ScPopUpMenu` + `ScMenuOptions`).
+- **Five things that will bite you:**
+  1. Options are keyed by **`id`**, not `value` — `{ id, label, description? }`.
+  2. `placeholder` defaults to the literal `"Select an option..."`.
+  3. `label` renders **only** when you also pass `labelGroup="label"`.
+  4. The menu is `position: absolute; z-index: 20` inside the component. Any
+     ancestor with `overflow: hidden` clips it — including `ScMappingCard` and
+     `ScTextField`'s own field container.
+  5. **No keyboard support in the list.** The trigger is a real button, but the
+     options are `div`s: no arrow keys, no Enter-to-select, no Escape-to-close,
+     no focus management.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSelect } from "@streamoid/ui";
+import type { IScSelectOption } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScSelect
+  options={[
+    { id: "admin", label: "Admin" },
+    { id: "member", label: "Member" },
+  ]}
+  value={role}
+  onChange={setRole}
+/>
+```
+
+### Props
+
+`ScSelect` does **not** extend `HTMLAttributes` and does **not** spread extra
+props. `className` is the only escape hatch — no `style`, `id`, `data-*`,
+`onBlur`, `name` or `required`.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `options` | `IScSelectOption[]` | `[]` | ⚠️ Empty default: with no options the panel opens blank. |
+| `value` | `string` | – | Matched against `option.id`. Controlled — no internal value state. |
+| `onChange` | `(id: string) => void` | – | Called with the option **`id`**, then the menu closes. |
+| `placeholder` | `string` | `"Select an option..."` | ⚠️ Real default, hardcoded English. |
+| `label` | `string` | – | Rendered only when `labelGroup === "label"` **and** `label` is truthy. |
+| `labelGroup` | `""` \| `"label"` | `""` | Gates the label row. |
+| `disabled` | `boolean` | `false` | Disables the native button, blocks toggling, greys text + chevron. |
+| `className` | `string` | – | Appended to the root class list. |
+
+`IScSelectOption`
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string` | **Required.** The value passed to `onChange`; also the React key. |
+| `label` | `string` | **Required.** Trigger text and option title. |
+| `description` | `string` | Optional 12 px muted second line inside the option row. |
+
+#### Derived visual state (you cannot set it)
+
+| Condition | State | Trigger skin |
+|---|---|---|
+| `disabled` | `disabled` | base fill, subtle border, `not-allowed`, disabled text |
+| menu open | `active` | raised fill, **strong** border |
+| a matching option | `filled` | raised fill, default border |
+| otherwise | `default` | base fill, subtle border, muted placeholder text |
+
+### Recipes
+
+```tsx
+// Labelled, with descriptions
+<ScSelect
+  label="Role"
+  labelGroup="label"
+  options={[
+    { id: "admin",  label: "Admin",  description: "Full access, can invite users" },
+    { id: "member", label: "Member", description: "Scoped access you configure" },
+  ]}
+  value={role}
+  onChange={setRole}
+/>
+
+// Mapping API objects — remember `id`, not `value`
+<ScSelect
+  options={attributes.map((a) => ({ id: a.code, label: a.displayName }))}
+  value={target}
+  onChange={setTarget}
+/>
+
+// Width/margins: className only (there is no `style` prop)
+<ScSelect className="my-select" options={opts} value={v} onChange={setV} />
+```
+
+---
+
+## 2. Where to use it
+
+- **Simple settings and form dropdowns** where the option list is static and
+  short (roles, units, sort orders, statuses).
+- **Inside `ScModal` / `ScDrawer`** — but check the container: the menu is not
+  portalled, so a scrolling modal body will clip or scroll it away.
+
+The hosts currently solve dropdowns two other ways, which is why this component
+has no host render site yet:
+
+| Host | What it does instead |
+|---|---|
+| Catalogix | `app/components/DsDropdown` — a read-only `ScTextField` as the trigger with a hand-rolled, host-owned menu; plus `react-select` (portalled) for feed mapping |
+| `@streamoid/settings` | wraps `ScTextField` in a clickable div for the specialization picker |
+
+`ScSelect` is the intended replacement for those wrappers whenever the menu does
+**not** need to escape a clipping ancestor.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- One value, from **5–30** static options, where pills/tabs would not fit.
+- Options benefit from a **second description line** (`description`).
+- You want the trigger to look identical to `ScTextField` (same 48 px pill, same
+  fill/border tokens, same focus skin) with none of the wrapper work.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| 2–4 mutually exclusive choices in a form, all visible | `ScTabField` |
+| 2–5 filters/views over a list | `ScSelectionPillGroup` |
+| A list of **actions** (Rename, Duplicate, Delete) | `ScPopUpMenu` + `ScMenuOptions` |
+| Multi-select, type-ahead search, async/paged options, grouped options | not in the DS — use the host's `react-select` (portalled) or build it |
+| The menu must escape `overflow: hidden` (e.g. inside `ScMappingCard`'s `targets` slot) | a portalled select of your own — `ScSelect` will be clipped |
+| Native form participation (`name`, `required`, uncontrolled submit) | a real `<select>`, styled with the tokens |
+| Free text with an optional suggestion list | `ScTextField` + your own list |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSelection` — an in-chat radio row (title + description) in the **agent runtime** | `ScSelect` is a host-app dropdown |
+| `ScSelectionList` — an in-chat approve/reject list, also agent runtime | unrelated |
+| `ScSelectionPill` / `ScSelectionPillGroup` — a segmented pill row in the dashboards | `ScSelect` is a collapsed menu |
+| `ScPopUpMenu` / `ScMenuOptions` — an action menu hung off an icon | `ScSelect` sets a **value** |
+
+The `ScSelect` / `ScSelection*` name collision is one of the top sources of wrong
+picks in this library: **`ScSelect` = dropdown (dashboards)**,
+**`ScSelection*` = chat transcript UI (agent runtime)**.
+
+---
+
+## 4. Why to use it
+
+- **The trigger already matches the field vocabulary** — `fill-neutral-neutralplus`
+  → `neutral` on hover/filled, `border-subtle` → `border-strong` when open, the
+  same `radius-3xl` and 48 px height as `ScTextField`. A hand-rolled trigger drifts
+  immediately.
+- **Correct listbox semantics on the parts that matter**: `aria-haspopup="listbox"`,
+  `aria-expanded` on a real `<button type="button">`, `role="listbox"` on the panel
+  and `role="option"` + `aria-selected` on each row.
+- **Outside-click closing is already handled** (a `mousedown` listener registered
+  only while open, and cleaned up on close) — the single most commonly forgotten
+  piece of a hand-rolled dropdown.
+- **Descriptions in options** are tokenised (12 px muted) so a two-line option row
+  looks the same everywhere.
+
+---
+
+## Gotchas
+
+**1. Options use `id`, not `value`.** Nearly every other list-shaped DS prop in
+this library (`ScTabField.tabs`, `ScSelectionPillGroup.options`) uses
+`{ label, value }`. This one is `{ id, label, description? }`.
+
+```tsx
+// WRONG — never matches; the trigger shows the placeholder forever
+<ScSelect options={[{ value: "admin", label: "Admin" }]} value="admin" />
+
+// RIGHT
+<ScSelect options={[{ id: "admin", label: "Admin" }]} value="admin" onChange={setRole} />
+```
+
+**2. The menu is not portalled.** It is `position: absolute; top: 100%;
+z-index: 20` inside `.selectArea`. Any ancestor with `overflow: hidden` clips it —
+notably `ScMappingCard` (whose README warns about exactly this) and
+`ScTextField`'s field container. Lift the select out, or use a portalled select.
+
+**3. `label` alone renders nothing.**
+
+```tsx
+// WRONG — the label is dropped
+<ScSelect label="Role" options={opts} value={v} onChange={setV} />
+
+// RIGHT
+<ScSelect label="Role" labelGroup="label" options={opts} value={v} onChange={setV} />
+```
+
+**4. No keyboard navigation inside the list.** Options are `div`s with `onClick`.
+Keyboard and screen-reader users can open the button but cannot reach the options.
+Don't use it as the only path to a critical setting until this is fixed in the DS.
+
+**5. There is no `style` prop and no prop spreading.** `className` is the whole
+API surface for layout. You cannot attach `data-testid`, `id`, `onBlur` or
+`aria-label` to the root.
+
+**6. The chevron is a hardcoded inline SVG,** not an `Sicon*`, and there is no
+left-icon or adornment slot on the trigger. If the spec puts an avatar, a colour
+swatch or a custom caret in the closed state, you cannot express it here — use the
+`ScTextField`-as-trigger pattern instead.
+
+**7. Fonts are hardcoded `Inter, sans-serif`** in this stylesheet rather than
+`--text-text-sm-regular-font-family` like the other fields. Sizes/colours are
+tokenised; the family is not. Harmless today, a drift risk if the body font
+changes.
+
+**8. Open state is internal.** There is no `open`/`onOpenChange` prop, so you
+cannot open it programmatically or coordinate it with another popover.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+Most likely home: the Catalogix feed **Map-Attributes** target rows
+(`ScMappingCard`'s `targets` slot) and simple settings dropdowns — but note
+Gotcha 2, since `ScMappingCard` sets `overflow: hidden`. Today Catalogix uses
+`app/components/DsDropdown` (an `ScTextField` trigger with its own menu) and
+`react-select` for the portalled cases.
+
+---
+
+## Related
+
+- `ScTextField` — what the trigger is modelled on; also the current host pattern
+  for hand-rolled dropdowns.
+- `ScTabField` — a segmented field when there are only 2–4 options.
+- `ScPopUpMenu` / `ScMenuOptions` — action menus, not value pickers.
+- `ScSelectionPillGroup` — visible segmented filters over a list.
+- `ScSelection` / `ScSelectionList` — the unrelated in-chat family (agent runtime).