@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScOnlyField.md

@@ -0,0 +1,302 @@
+---
+component: ScOnlyField
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div > div > input
+tags: [input, search, searchbox, bare-input, unlabelled, compact, size, sidebar-search, filter]
+related: [ScTextField, ScTextArea, ScSelect, ScOnlyIcon, ScFieldButton]
+do_not_confuse_with: [ScOnlyIcon, ScTextField, ScAppField]
+used_by: [cxo, catalogix, photogenix, artifax]
+---
+
+# ScOnlyField
+
+**A bare input in a pill — no label, ever.** One rounded container, an optional
+icon on either side, and a borderless `<input>` inside. Unlike `ScTextField` it
+has three heights (`48 / 40 / 32 px`) and reports changes as a plain string via
+`onInputChange`. This is the component behind almost every search box in the
+product.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a search box, a filter input, or a compact
+  input inside a toolbar, sidebar or modal row — with no label above it.
+- **Don't reach for it when:** the field needs a label, a `*`, a helper line or a
+  ref (→ `ScTextField`), or it is multi-line (→ `ScTextArea`).
+- **Five things that will bite you:**
+  1. `tfGroup` defaults to `"icon-right"` and `tfRightIcon` defaults to a
+     **lightning bolt**. Pass `tfGroup="none"` or supply a real icon.
+  2. `labelGroup` is **vestigial** — this component renders no label element at
+     all. There is no `label` prop either.
+  3. `state="active"`, `state="error"` and `state="disabled"` paint **nothing**.
+     Only `filled` (and `:hover`) have styles; the focus rule in the stylesheet
+     is misspelled `state-ative-focused` and is unreachable.
+  4. It's fully controlled but has **no `onChange`** — use `onInputChange(value)`.
+     Passing `inputProps.onChange` silently replaces it.
+  5. `inputProps.style` **replaces** the component's inline input styles, which
+     brings back the browser's default input border and background.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScOnlyField } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScOnlyField
+  tfGroup="icon-right"
+  tfRightIcon={<SiconSearch />}
+  placeholderFilled="Search…"
+  value={query}
+  onInputChange={setQuery}
+/>
+```
+
+### Props
+
+Extends `React.HTMLAttributes<HTMLDivElement>`; unlisted props (`style`,
+`onClick`, `data-*`, `id`) are spread onto the **root div**.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `value` | `string` | – | Controlled value. No internal state — without `onInputChange` typing does nothing. |
+| `onInputChange` | `(value: string) => void` | – | Receives the **string**, not an event. The only change hook. |
+| `size` | `"default"` \| `"medium"` \| `"small"` | `"default"` | 48 px / 40 px / 32 px tall; radius `3xl`/`xl`/`lg`; icon box 24/20/16 px. |
+| `tfGroup` | `"icon-right"` \| `"icon-left"` \| `"icon-left-right"` \| `"none"` | `"icon-right"` | ⚠️ Which icons render. `"none"` for a plain input. |
+| `tfRightIcon` | `JSX.Element` | `<SiconBolt />` | ⚠️ Real default. Force-sized by CSS to the `size` icon box. |
+| `tfLeftIcon` | `JSX.Element` | `<SiconBolt />` | ⚠️ Real default. Same sizing. |
+| `placeholderFilled` | `string` | `"Placeholder"` | ⚠️ Real default. Overridable via `inputProps.placeholder`. |
+| `state` | `"default"` \| `"active"` \| `"error"` \| `"disabled"` \| `"filled"` | `"default"` | Only `"filled"` changes anything (raised fill). See Gotcha 3. |
+| `labelGroup` | `"none"` \| `"label"` \| `"text"` \| `"icon"` | `"none"` | ⚠️ **Dead prop** — no label is ever rendered. |
+| `inputProps` | `React.InputHTMLAttributes<HTMLInputElement>` | – | Spread onto the `<input>` **after** the component's own attributes, so it can override `onChange`, `placeholder` and `style`. Use it for `autoFocus`, `maxLength`, `onKeyDown`, `readOnly`. |
+| `className` | `string` | – | Appended to the root class list. |
+
+#### What each `state` actually paints
+
+| `state` | Effect |
+|---|---|
+| `default` | base fill (`fill-neutral-neutralplus`); in light mode a 0.5 px subtle border |
+| `filled` | raised fill (`fill-neutral-neutral`); light mode border → `border-default` |
+| `active` | **nothing** — the stylesheet rule is typo'd `state-ative-focused` |
+| `error` | **nothing** — no rule exists |
+| `disabled` | **nothing** — no rule exists, and the input stays editable |
+| `:hover` | same as `filled` (real CSS hover, always live) |
+
+### Recipes
+
+```tsx
+// Toolbar / panel search — the CXO app-switcher idiom
+<ScOnlyField
+  tfGroup="icon-right"
+  size="medium"
+  tfRightIcon={<SiconSearch className="w-6 h-6" color="var(--alias-text-and-icons-primary)" />}
+  placeholderFilled="Search..."
+  value={searchQuery}
+  onInputChange={setSearchQuery}
+  style={{ width: 256 }}          // style lands on the ROOT (root is width:100%)
+/>
+
+// Repeated option rows with a trailing delete — the Catalogix taxonomy idiom
+<ScOnlyField
+  value={option.value}
+  placeholderFilled="Option 1"
+  state={hasValue ? "filled" : "default"}
+  tfGroup={hasValue ? "icon-right" : "none"}
+  tfRightIcon={
+    <SiconDelete
+      size={24}
+      color="var(--alias-text-and-icons-error)"
+      style={{ cursor: "pointer" }}
+      onClick={removeOption}
+    />
+  }
+  onInputChange={(val) => updateOption(idx, val)}
+  inputProps={{ autoFocus: shouldFocus, onKeyDown: onEnterAddRow }}
+/>
+
+// Dense 32 px input inside a table row
+<ScOnlyField size="small" tfGroup="none" value={v} onInputChange={setV} />
+
+// Truly disabled — the `state` prop won't do it
+<ScOnlyField tfGroup="none" value={v} inputProps={{ disabled: true }} />
+```
+
+---
+
+## 2. Where to use it
+
+- **Sidebar / workspace-listing search** — Photogenix `Sidebar.tsx`, Artifax
+  `DashboardSidebar.tsx`, Catalogix `LeftMenu/WorkspaceListing`.
+- **App-switcher and panel headers** — CXO `app-switcher.tsx` (256 px, medium).
+- **Store / member filters** — CXO `teams-content.tsx`, the
+  `@streamoid/settings` teams and organization screens.
+- **Repeatable value rows in modals** — Catalogix taxonomy "Options" lists,
+  where each row is an `ScOnlyField` with a trailing red delete icon.
+- **Composed inside other DS components** — `ScCatalogixInvite` renders one as
+  its store-search box.
+
+All four host apps use it; it is part of the universal core.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- There is **no label** — the surrounding heading or icon already says what the
+  input is for.
+- You need a **40 px or 32 px** field; `ScTextField` is fixed at 48 px.
+- The value is a plain string in local state and you want the terser
+  `onInputChange` signature.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The field needs a label, a `*`, an info popover or helper text | `ScTextField` |
+| You need a `ref` on the input, or full native `onChange`/form props | `ScTextField` (it forwards a ref) |
+| Multi-line input | `ScTextArea` |
+| Pick from a list | `ScSelect` |
+| A visible error state on the field | `ScTextField` + `desc`, or `ScTextArea` (which has a real `state="error"`) |
+| An icon-only button (no text entry) | `ScButton` with `styleVariant="icon-only"` |
+| A non-editable icon/control + label row | `ScPairtext` (one text line, no input — **not** a label:value pair) |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScOnlyIcon` — a 40 px icon square with a hover background, **not an input** | `ScOnlyField` is a text input. The names are one character apart. |
+| `ScTextField` — labelled, ref-forwarding, native `onChange`, 48 px only | `ScOnlyField` is unlabelled, no ref, `onInputChange`, three sizes |
+| `ScAppField` — a hardcoded three-app permission block, not a generic field | neither of these |
+
+---
+
+## 4. Why to use it
+
+- **Three sizes that match the spec.** Height, padding, radius *and* icon box all
+  step together (48/40/32 → 24/20/16 icons). Hand-rolled search boxes get the
+  icon size wrong almost every time.
+- **Icons are force-sized.** `.iconWrapper > *` sets `width/height: 100%`, so any
+  `Sicon*` you pass lands at exactly the right box size regardless of its own
+  `size` prop.
+- **Light mode is explicitly handled.** The neutral fills are near-white in the
+  light theme, so `[data-theme="Light"]` adds a persistent 0.5 px border across
+  all states — which also removes the 1 px layout shift on focus.
+- **The placeholder uses the muted token** via `::placeholder`, so it can't drift
+  from the rest of the product.
+
+---
+
+## Gotchas
+
+**1. The default field contains a lightning bolt.**
+
+```tsx
+// WRONG — renders a ⚡ on the right
+<ScOnlyField value={q} onInputChange={setQ} />
+
+// RIGHT
+<ScOnlyField tfGroup="none" value={q} onInputChange={setQ} />
+```
+
+**2. There is no label and no `label` prop.** `labelGroup` is accepted and
+ignored — the component's JSX has no label element. If you need one, either use
+`ScTextField` or render your own text above it.
+
+**3. Only `filled` is a real state.** `active` is misspelled in the stylesheet
+(`state-ative-focused`), and `error`/`disabled` have no rules at all. So:
+
+```tsx
+// WRONG — looks identical to default, and is still editable
+<ScOnlyField state="disabled" value={v} />
+
+// RIGHT
+<ScOnlyField tfGroup="none" value={v} inputProps={{ disabled: true }} />
+```
+
+For an error, put the red on the icon or draw the border yourself via a
+`className` on the root — the component gives you nothing.
+
+**4. `inputProps` overrides the component's own input wiring.** It is spread
+last, so `inputProps.onChange` replaces the internal handler and `onInputChange`
+stops firing.
+
+```tsx
+// WRONG — onInputChange never fires
+<ScOnlyField value={v} onInputChange={setV} inputProps={{ onChange: log }} />
+
+// RIGHT — keep one owner of the change
+<ScOnlyField value={v} inputProps={{ onChange: (e) => { setV(e.target.value); log(e); } }} />
+```
+
+**5. `inputProps.style` wipes the transparent-input styling.** The `<input>`
+carries inline `background: transparent; border: none; outline: none; font:
+inherit; color: primary; width: 100%; padding: 0`. Passing `style` replaces the
+whole object, so the native grey box comes back. Pass only the properties you
+need *plus* those, or style via `className` on the root instead.
+
+**6. No ref is forwarded.** For autofocus use `inputProps={{ autoFocus: true }}`
+(Catalogix does). If you genuinely need a DOM handle, use `ScTextField`.
+
+**7. `style` lands on the root, not the input.** The root is `width: 100%`, so
+`style={{ width: 256 }}` is the right way to make it narrower.
+
+**8. Typing does nothing without `onInputChange`.** `value` is passed straight to
+a controlled input. This looks like a broken field, not a read-only one — if you
+want read-only, say `inputProps={{ readOnly: true }}`.
+
+**9. The class attribute contains the literal `undefined`** when `className` is
+omitted (raw string concatenation) and for state/group names with no matching
+rule. Harmless, but don't write CSS or tests that depend on the class list.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/app-switcher.tsx:246
+<ScOnlyField
+  tfGroup="icon-right"
+  size="medium"
+  tfRightIcon={<SiconSearch className="w-6 h-6" color={PRIMARY_ICON} />}
+  placeholderFilled="Search..."
+  value={searchQuery}
+  onInputChange={setSearchQuery}
+  style={{ width: 256 }}
+/>
+```
+
+```jsx
+// catalogix/dashboard  app/components/TaxonomyComponent/AddHierarchyModal/AddHierarchyContent.jsx:379
+<ScOnlyField
+  key={indx}
+  value={option.value}
+  placeholderFilled="Option 1"
+  state={option.error ? "error" : hasValue ? "filled" : "default"}
+  tfGroup={hasValue ? "icon-right" : "none"}
+  tfRightIcon={<SiconDelete size={24} color="var(--alias-text-and-icons-error)" onClick={removeOption} />}
+  onInputChange={(val) => { /* writes optionValues[indx].value, clears the error */ }}
+  inputProps={{ autoFocus: changeFocus, /* … */ }}
+/>
+```
+
+*(Note: that call site's `state="error"` renders no error styling — see Gotcha 3.)*
+
+---
+
+## Related
+
+- `ScTextField` — use it the moment you need a label, a ref, or helper text.
+- `ScTextArea` — multi-line sibling with real `error`/`disabled` skins.
+- `ScSelect` — dropdown instead of free text.
+- `ScOnlyIcon` — the confusable namesake; an icon square, not an input.
+- `ScFieldButton` — the compact action that sits beside a field.
+- `@streamoid/icons` — `SiconSearch`, `SiconDelete`, `SiconClose`; see `packages/icons/ICONS.md`.

package/dist/docs/ScOnlyIcon.md

@@ -0,0 +1,213 @@
+---
+component: ScOnlyIcon
+package: "@streamoid/ui"
+category: actions
+status: legacy
+renders: div
+tags: [icon-button, icon-only, settings-icon, square, hover, affordance, orphan]
+related: [ScButton, ScFieldButton, ScSidebarIcons, ScMenuOptions]
+do_not_confuse_with: [ScOnlyField, ScButton, ScFieldButton, ScSidebarIcons]
+---
+
+# ScOnlyIcon
+
+**A 40 × 40 hover square that always renders the settings gear.** That is the
+whole component: a `div` with 8 px padding, a 16 px radius, a hover background,
+and a hardcoded `<SiconSettings />` inside. **There is no `icon` prop.**
+
+> **Use `ScButton` with `styleVariant="icon-only"` instead.** `ScOnlyIcon` is a
+> Figma-generated stub with no consumers anywhere — not in the four host
+> dashboards, and not inside `@streamoid/ui` itself. It cannot render any icon
+> other than the gear, has no keyboard or `aria` semantics, and has no disabled
+> state.
+
+## TL;DR for agents
+
+- **Reach for it when:** essentially never. The only honest use is a bare
+  settings-gear affordance where you also don't need keyboard access.
+- **Don't reach for it when:** you need *any* other icon, a11y, a disabled state,
+  variants or sizes → `ScButton` (`styleVariant="icon-only"`).
+- **Three things that will bite you:**
+  1. `icon` **does not exist**. Passing one is a type error and would be ignored.
+  2. `variant` accepts only `"default"` and maps to a class that isn't in the
+     stylesheet, so it does nothing.
+  3. It is a `<div>` — no `role`, no `tabIndex`, no Enter/Space, no focus ring.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScOnlyIcon } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScOnlyIcon onClick={openSettings} />
+```
+
+### Props
+
+Extends `React.HTMLAttributes<HTMLDivElement>`; unlisted props (`onClick`,
+`style`, `title`, `aria-*`, `data-*`) are spread onto the root div.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `variant` | `"default"` | `"default"` | Dead prop — resolves to a class (`variant-default`) that the stylesheet does not define. |
+| `className` | `string` | – | Appended to the root class list. The only real styling hook. |
+
+There is **no** `icon`, `size`, `state`, `disabled`, `active` or `label` prop.
+
+#### What actually renders
+
+| Part | Value |
+|---|---|
+| Root | `div`, `padding: 0.5rem`, `border-radius: var(--radius-3xl, 1rem)`, flex row |
+| Icon | `<SiconSettings />` at its default `size={24}`, `stroke: currentColor` |
+| Total box | **40 × 40 px** — derived (24 px icon + 2 × 8 px padding); the stylesheet sets no `width`/`height` |
+| Hover | background `--alias-fill-neutral-neutralhover` |
+| Icon colour | inherited `currentColor` from the parent — set `color` on an ancestor to change it |
+
+### Recipes
+
+```tsx
+// The only sane call: a gear that opens settings, with semantics bolted on
+<ScOnlyIcon
+  role="button"
+  tabIndex={0}
+  aria-label="Settings"
+  onClick={openSettings}
+  onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") openSettings(); }}
+/>
+
+// Recolour the gear (it inherits currentColor)
+<span style={{ color: "var(--alias-text-and-icons-tertiary)" }}>
+  <ScOnlyIcon onClick={openSettings} />
+</span>
+
+// What you almost certainly want instead
+<ScButton
+  styleVariant="icon-only"
+  icon={<SiconSettings size={24} />}
+  variant="mono"
+  type="tertiary"
+  size="md"
+  aria-label="Settings"
+  onClick={openSettings}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+Nowhere, currently. Grepping CXO, Catalogix, Photogenix and Artifax — and
+`packages/ui/src` itself — finds no render site. Its intended home was clearly a
+toolbar or panel-header gear.
+
+The surfaces that *look* like its job are already served by other components:
+
+| Surface | What actually renders there |
+|---|---|
+| Sidebar rail icons | `ScSidebarIcons` / `StreamoidSidebar` |
+| Header / toolbar icon actions | `ScButton styleVariant="icon-only"` |
+| Composer toolbar actions | `ScFieldButton type="only-icon"` |
+| Row overflow menus | `ScPopUpMenu` + `ScMenuOptions` |
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You want a bare gear icon with the DS hover square and you are fine adding
+  `role`/`tabIndex`/`aria-label` yourself.
+
+That is the complete list.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Any icon other than the settings gear | `ScButton styleVariant="icon-only"` with `icon={…}` |
+| The icon button needs keyboard access, a focus ring, `aria-disabled` | `ScButton` |
+| A disabled/loading state | `ScButton` (`state="disabled"`, `loading`) |
+| A compact icon affordance inside a composer or beside a field | `ScFieldButton type="only-icon"` (which *does* take an `icon`) |
+| A sidebar rail icon with active state | `ScSidebarIcons` / `StreamoidSidebar` |
+| An icon that opens a menu | `ScPopUpMenu` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| **`ScOnlyField`** — a text **input** in a pill. One character apart from this name and a completely different component. | `ScOnlyIcon` renders no input |
+| `ScFieldButton` with `type="only-icon"` — a 36 px chip that accepts **your** icon | `ScOnlyIcon`'s icon is hardcoded |
+| `ScButton` with `styleVariant="icon-only"` — the supported icon button | `ScOnlyIcon` has no variants, states or semantics |
+
+---
+
+## 4. Why to use it
+
+Honestly: there is little reason. What it does give you is the 8 px / 16 px-radius
+hover square that matches other icon affordances, in ~20 lines with no variant
+logic. Everything else — icon choice, colour normalisation, keyboard access,
+disabled handling, Figma variant parity — you get from `ScButton` and not from
+here.
+
+If you keep it, keep it for the gear only, and add the semantics yourself.
+
+---
+
+## Gotchas
+
+**1. You cannot change the icon.**
+
+```tsx
+// WRONG — type error, and there is no code path that would render it
+<ScOnlyIcon icon={<SiconClose />} />
+
+// RIGHT
+<ScButton styleVariant="icon-only" icon={<SiconClose size={24} />} aria-label="Close" />
+```
+
+**2. `variant` does nothing.** The component computes `styles["variant-default"]`,
+which is not defined in `ScOnlyIcon.module.css`, so the literal string `undefined`
+lands in the class attribute (raw concatenation also adds `undefined` when
+`className` is omitted). Don't write CSS or tests against this class list.
+
+**3. `.hover-true` is unreachable.** The stylesheet has a forced-hover class for
+Figma parity, but no prop sets it. Only real `:hover` works — you cannot
+screenshot the hover state via props the way `ScButton state="hover"` allows.
+
+**4. No semantics at all.** `div` with a spread `onClick`. Add
+`role="button" tabIndex={0} aria-label="…"` and an `onKeyDown`, or use `ScButton`.
+
+**5. No size control.** There is no `size` prop: the box is whatever the icon plus
+`0.5rem` of padding comes to — 40 × 40 today, because the stylesheet gives
+`.siconSettingsInstance` no sizing rule and `Sicon*` defaults to `size={24}`. The
+CSS itself declares no `width`/`height`, so the only lever is a `className` on the
+root plus a descendant rule.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+To be precise: not used by the agent runtime either — this one is a genuine
+orphan. If a gear affordance is needed, it belongs in a header/toolbar row beside
+an `ScHeader`, and should be built with `ScButton styleVariant="icon-only"`.
+
+---
+
+## Related
+
+- `ScButton` — `styleVariant="icon-only"`; the supported way to render an icon button.
+- `ScFieldButton` — `type="only-icon"`; compact 36 px chip that accepts your icon.
+- `ScOnlyField` — the near-identical *name* that is actually a text input.
+- `ScSidebarIcons` / `StreamoidSidebar` — sidebar rail icons with active states.
+- `@streamoid/icons` — `SiconSettings` and every other icon; see `packages/icons/ICONS.md`.