@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScTextArea.md

@@ -0,0 +1,259 @@
+---
+component: ScTextArea
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div > (label?) + div > textarea
+tags: [textarea, multiline, description, long-text, form, resize, error-state]
+related: [ScTextField, ScOnlyField, ScSelect, ScCheckField]
+do_not_confuse_with: [ScTextField, ScOnlyField]
+used_by: [catalogix]
+---
+
+# ScTextArea
+
+**The multi-line text field.** Same pill chrome as `ScTextField` — tertiary label
+row, tokenised fill/border, focus ring — wrapped around a vertically resizable
+`<textarea>` that starts at 72 px tall. It is the **only** text field in the
+library with real `error` and `disabled` styling (`ScTextField` and `ScOnlyField`
+accept those `state` values and paint nothing).
+
+## TL;DR for agents
+
+- **Reach for it when:** the user types more than one line — descriptions,
+  product copy, notes, prompts, feedback.
+- **Don't reach for it when:** the value is a single line (→ `ScTextField`), it is
+  a bare search input (→ `ScOnlyField`), or it is a choice (→ `ScSelect`).
+- **Four things that will bite you:**
+  1. `label` renders nothing unless you also pass `labelGroup="label"`.
+  2. `labelGroup="text"` renders the label plus the hardcoded string `"info"` on
+     the right — `info` defaults to that literal word.
+  3. `placeholderFilled` defaults to `"Placeholder"`.
+  4. There are **no icons, no slots and no style escape hatches** — `style` goes
+     to the root wrapper only. `ScTextField`'s `containerStyle`/`inputStyle` do
+     not exist here.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScTextArea } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScTextArea
+  placeholderFilled="E.g.: Info"
+  value={description}
+  onChange={(e) => setDescription(e.target.value)}
+/>
+```
+
+### Props
+
+Extends `React.TextareaHTMLAttributes<HTMLTextAreaElement>`; everything not
+listed below (`value`, `onChange`, `rows`, `maxLength`, `disabled`, `readOnly`,
+`name`) is spread onto the `<textarea>`.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | `""` | Only rendered when `labelGroup` is truthy. A trailing space is appended in the markup. |
+| `labelGroup` | `""` \| `"label"` \| `"text"` | `""` | ⚠️ Gates the label row. `""` → no row. `"label"` → label only. `"text"` → label + `info` on the right. |
+| `info` | `string` | `"info"` | ⚠️ Real default, and it is the literal word "info". Only rendered when `labelGroup="text"`. |
+| `placeholderFilled` | `string` | `"Placeholder"` | ⚠️ Real default. A native `placeholder` prop overrides it (spread later). |
+| `state` | `"default"` \| `"active"` \| `"error"` \| `"disabled"` \| `"filled"` | *derived* | Omit and it derives: `disabled` prop → focused → non-empty `value` → `default`. **All five have real styles here.** |
+| `className` | `string` | – | Appended to the root class list. |
+| `style` | `CSSProperties` | – | Applied to the **root wrapper**, not the textarea or the container. |
+
+#### What each `state` paints
+
+| `state` | Container | Text |
+|---|---|---|
+| `default` | base fill, subtle border | muted |
+| `filled` | raised fill, default border | primary |
+| `active` | raised fill, **strong** 1 px border | primary |
+| `error` | **red 1 px border** (`text-and-icons-error`) | muted |
+| `disabled` | base fill, subtle border | disabled colour, `cursor: not-allowed`, `resize: none` |
+
+### Recipes
+
+```tsx
+// Labelled description field
+<ScTextArea
+  label="Description"
+  labelGroup="label"
+  placeholderFilled="What is this attribute for?"
+  value={description}
+  maxLength={500}
+  onChange={(e) => setDescription(e.target.value)}
+/>
+
+// Validation — this is the one text field where `state="error"` actually shows
+<ScTextArea
+  label="Prompt"
+  labelGroup="label"
+  state={touched && !value ? "error" : undefined}   // undefined ⇒ auto-derive
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+/>
+
+// Grow it with `rows` — it is spread onto the <textarea>, and any value above the
+// stylesheet's min-height (4rem ≈ 3 rows) wins. `style` lands on the ROOT wrapper,
+// so it cannot make the box taller; use `className` if you need to restyle the box.
+<ScTextArea
+  value={body}
+  onChange={(e) => setBody(e.target.value)}
+  rows={8}
+/>
+
+// Read-only / disabled
+<ScTextArea value={generatedCopy} disabled />   {/* derives state="disabled" */}
+```
+
+---
+
+## 2. Where to use it
+
+- **Catalogix product editing** — `ProductsListTableV2/EditTextAttribute` uses it
+  for "Active Content" (long product titles/descriptions).
+- **Catalogix taxonomy modals** — the collapsible "Description" block in
+  `AddHierarchyModal` and `TaxonomyAttributesModal`.
+- Anywhere a form stacks `ScTextField` rows and one of them is long-form: put the
+  `ScTextArea` last in the stack so its resize handle doesn't push siblings.
+
+Catalogix is the only host currently rendering it.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The value is genuinely multi-line, or long enough that a 48 px single-line
+  field would hide most of it.
+- You want a **visible error border** driven by a prop — the other text fields
+  don't have one.
+- You want the user to be able to **drag the field taller** (`resize: vertical`
+  is on by default).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| One line of text with a label, `*`, info popover or helper line | `ScTextField` |
+| Bare/compact input, search box, 40 px or 32 px height | `ScOnlyField` |
+| Choose one of N | `ScSelect` (or `ScTabField` for 2–4 inline) |
+| Rich text / markdown editing | not in the DS — bring your own editor and reuse the tokens |
+| Chat composer | the agent runtime owns the composer, not `@streamoid/ui` |
+| Read-only long text | plain markup with the `--text-text-sm-regular-*` tokens; a disabled textarea reads as broken |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScTextField` — single line, forwards a ref, has `required`/`info`/`desc`/`leftSlot`/`rightSlot` and per-layer style hatches | `ScTextArea` has none of those, but is the only text field whose `error`/`disabled` states paint |
+| `ScOnlyField` — no label at all, `onInputChange(value)` instead of `onChange(event)` | `ScTextArea` uses the native `onChange(event)` |
+| `ScTextField` + `tall` — grows the container around a **single-line input** | that is not a textarea; text still scrolls horizontally |
+
+---
+
+## 4. Why to use it
+
+- **It matches `ScTextField` pixel-for-pixel** on fill, border, radius, label
+  typography and focus ring, so a form mixing the two looks like one form.
+- **A complete state machine.** `error` and `disabled` are implemented (red
+  border; disabled colour + `cursor: not-allowed` + `resize: none`), which is not
+  true of `ScTextField` or `ScOnlyField`.
+- **Auto-derived focus/filled.** You get the "raised when it has content" skin
+  without tracking focus yourself, and your `onFocus`/`onBlur` still fire.
+- **Sensible resize defaults** — `resize: vertical` only, so the user can't drag
+  it wider and break your layout.
+
+---
+
+## Gotchas
+
+**1. `label` alone renders nothing.** The row is gated purely on `labelGroup`.
+
+```tsx
+// WRONG — no label appears
+<ScTextArea label="Description" value={v} onChange={onChange} />
+
+// RIGHT
+<ScTextArea label="Description" labelGroup="label" value={v} onChange={onChange} />
+```
+
+**2. `labelGroup="text"` ships the word "info".** `info` defaults to the literal
+string `"info"`, right-aligned and muted. Pass real copy (a character count, a
+hint) or don't use `"text"`.
+
+```tsx
+// WRONG — renders "info" next to the label
+<ScTextArea label="Description" labelGroup="text" />
+
+// RIGHT
+<ScTextArea label="Description" labelGroup="text" info={`${value.length}/500`} />
+```
+
+**3. `labelGroup="none"` is a type error** even though hosts pass it. `"none"` is
+truthy, so it renders an empty label row that the stylesheet then hides via
+`.label-group-none { display: none }`. It happens to look right — but the
+supported way to hide the label is to **omit `labelGroup` entirely**.
+
+**4. `placeholderFilled` defaults to `"Placeholder"`.** Pass `placeholderFilled=""`
+if you want no placeholder at all (Catalogix's edit-attribute screen does).
+
+**5. No style escape hatches.** `style` is applied to the root wrapper only;
+there is no `containerStyle` or `inputStyle` (those are `ScTextField`-only).
+A `style={{ height }}` on the root does **not** grow the box (the container is a
+`flex-shrink: 0` child with its own `min-height`) — size it with `rows`, or with a
+`className` rule that targets the container/textarea, and note that CSS-module
+specificity may need an attribute selector to win — see `ScTextField`'s "Why"
+section for the host workaround.
+
+**6. No ref, no icons, no slots.** There is no `tfGroup`, no `tfLeftIcon`, no
+`leftSlot`/`rightSlot`, and no forwarded ref. If a spec puts an icon or a
+character counter inside the box, you have to wrap the component yourself.
+
+**7. `rows` fights the stylesheet.** The `<textarea>` carries
+`min-height: 4rem` and the container `min-height: 4.5rem`, so `rows` values below
+about 3 are ignored. Larger values do apply (there is no `height` rule) — see the
+recipe.
+
+**8. Derived `filled` needs a controlled `value`.** The derivation reads
+`props.value`; an uncontrolled textarea with `defaultValue` stays in the
+`default` skin with muted text.
+
+---
+
+## In the wild
+
+```jsx
+// catalogix/dashboard  app/containers/Products/ProductsListTableV2/EditTextAttribute/index.jsx:396
+<ScTextArea
+  key={defaultValue}
+  className={styles["active-textarea"]}
+  placeholderFilled=""
+  value={selectedValue}
+  onChange={(e) => {
+    setSelectedValue(e.target.value);
+    if (optionInView === "similar") {
+      throttle("get_similar_title", getCurrentStoreSimilarTitles);
+    }
+  }}
+/>
+```
+
+---
+
+## Related
+
+- `ScTextField` — the single-line sibling; richer API, weaker state styling.
+- `ScOnlyField` — unlabelled/compact input with `size` variants.
+- `ScSelect` — when the long text is really a choice.
+- `ScCheckField` / `ScTabField` — the other field types you'll stack beside it.

package/dist/docs/ScTextField.md

@@ -0,0 +1,324 @@
+---
+component: ScTextField
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div > (label?) + div > input
+tags: [input, text, textfield, form, label, placeholder, required, helper, desc, info, slot]
+related: [ScOnlyField, ScTextArea, ScSelect, ScFieldButton, ScTabField, ScCheckField, ScFileField, ScInfoPopup]
+do_not_confuse_with: [ScOnlyField, ScTextArea, ScAppField, ScOnlyIcon]
+used_by: [cxo, catalogix, photogenix, artifax]
+---
+
+# ScTextField
+
+**The default single-line text input for every Streamoid form.** Renders a
+tertiary-coloured label row (optional `*`, optional info popover), a 48 px pill
+container holding a borderless `<input>` with up to two icons/slots, and an
+optional helper line underneath. It is the only field in the library that
+forwards a ref to its `<input>`.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a labelled single-line input inside a form,
+  modal or settings panel.
+- **Don't reach for it when:** you want a bare input with no label and size
+  variants (→ `ScOnlyField`), multi-line text (→ `ScTextArea`), or a dropdown
+  (→ `ScSelect`).
+- **Five things that will bite you:**
+  1. `tfGroup` defaults to `"icon-right"` and `tfRightIcon` defaults to a
+     **lightning bolt** — forget both and you ship a ⚡. Pass `tfGroup="none"`.
+  2. `placeholderFilled` defaults to the literal string `"Placeholder"`.
+  3. `onClick` / `onKeyDown` / `aria-*` land on the **`<input>`**, not the root.
+     `className` / `style` land on the **root**. Wrap the field in your own div
+     if you need whole-field click behaviour.
+  4. `state="error"` and `state="disabled"` have **no styles in the stylesheet**.
+     No red border, no grey-out — and worse, they force the input text to the
+     *muted* colour.
+  5. The field container is `overflow: hidden`, so anything absolutely
+     positioned inside `rightSlot` (a menu, a tooltip) gets clipped.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScTextField } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScTextField
+  label="Full Name"
+  labelGroup="label"
+  placeholderFilled="Enter your name"
+  tfGroup="none"
+  value={fullName}
+  onChange={(e) => setFullName(e.target.value)}
+/>
+```
+
+### Props
+
+Extends `React.InputHTMLAttributes<HTMLInputElement>`; everything not listed
+below is spread onto the `<input>`. Ref is forwarded to the `<input>`.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | `""` | Label text. Only rendered when the label row is shown — see `labelGroup`. |
+| `labelGroup` | `""` \| `"label"` \| `"text"` \| `"icon"` | `""` | ⚠️ Gates the whole label row. `""` → no row at all. `"label"` → label only. `"text"` → label + the hardcoded string `"info"` on the right. `"icon"` → label + a bolt icon. |
+| `tfGroup` | `"icon-right"` \| `"icon-left"` \| `"icon-left-right"` \| `"none"` | `"icon-right"` | ⚠️ Which built-in icons render. **`"none"` is what most call sites want.** |
+| `tfRightIcon` | `JSX.Element` | `<SiconBolt />` | ⚠️ Real default. Rendered for `icon-right` / `icon-left-right`. Not size-normalised — pass `size={24}`. |
+| `tfLeftIcon` | `JSX.Element` | `<SiconBolt />` | ⚠️ Real default. Rendered for `icon-left` / `icon-left-right`. |
+| `placeholderFilled` | `string` | `"Placeholder"` | ⚠️ Real default. Overridden by a native `placeholder` prop (spread later). |
+| `state` | `"default"` \| `"active"` \| `"error"` \| `"disabled"` \| `"filled"` | *derived* | Omit it and it is derived: `disabled` → focused → non-empty `value` → `"default"`. Only `active` / `filled` / hover have styles. |
+| `required` | `boolean` | – | Adds a red `*` after the label **and forces the label row to render**. |
+| `info` | `ReactNode` | – | Content for an `ScInfoPopup` beside the label. Also forces the label row to render. |
+| `desc` | `ReactNode` | – | Helper text under the field (12 px, muted). Skipped when `null`/`undefined`/`false`. |
+| `tall` | `boolean` | – | Container becomes `min-height: 5rem`, top-aligned. Still a single-line `<input>`. |
+| `leftSlot` | `ReactNode` | – | Arbitrary adornment before the left icon. |
+| `rightSlot` | `ReactNode` | – | Arbitrary adornment after the right icon. |
+| `className` | `string` | – | Appended to the **root** class list. |
+| `rootClassName` / `rootStyle` | `string` / `CSSProperties` | – | Extra escape hatches on the root. `style` is merged first, then `rootStyle`. |
+| `containerClassName` / `containerStyle` | `string` / `CSSProperties` | – | On the 48 px field container. Use this to change height/radius/padding. |
+| `inputStyle` | `CSSProperties` | – | On the `<input>` itself. |
+| `descClassName` / `descStyle` | `string` / `CSSProperties` | – | On the helper line. |
+
+#### What each `state` actually paints
+
+| `state` | Container | Input text |
+|---|---|---|
+| `default` | base fill, subtle border | muted |
+| `filled` | raised fill, default border | primary |
+| `active` | raised fill, **strong** 1 px border | primary |
+| `error` | **nothing** (no rule exists) | muted |
+| `disabled` | **nothing** (no rule exists) | muted, and `:hover` still lights up |
+
+### Recipes
+
+```tsx
+// Read-only field with a lock — the CXO settings idiom
+<ScTextField
+  label="Email ID"
+  labelGroup="label"
+  value={user?.email ?? ""}
+  state="filled"                                  // NOT "disabled" — see the table
+  tfGroup="icon-right"
+  tfRightIcon={<SiconLock size={24} color="var(--alias-text-and-icons-muted)" />}
+  readOnly
+/>
+
+// Required field with an info popover and a helper line
+<ScTextField
+  label="Store name"
+  labelGroup="label"
+  required
+  info="Shown to shoppers on your storefront."
+  desc="3–40 characters, letters and spaces only."
+  tfGroup="none"
+  value={name}
+  onChange={(e) => setName(e.target.value)}
+/>
+
+// Dropdown trigger: the field is read-only, YOUR wrapper owns the click
+// (onClick on ScTextField would only fire on the inner <input>)
+<div onClick={() => setOpen((v) => !v)} aria-haspopup="listbox" aria-expanded={open}>
+  <ScTextField
+    tfGroup="icon-right"
+    tfRightIcon={<SiconDown size={20} color="var(--alias-text-and-icons-tertiary)" />}
+    value={displayText}
+    placeholder="Select…"
+    readOnly
+    onKeyDown={(e) => {
+      if (e.key === "Enter" || e.key === " ") { e.preventDefault(); setOpen((v) => !v); }
+    }}
+  />
+</div>
+{open && <MyMenu />}   {/* render OUTSIDE the field: the container clips */}
+
+// Overriding DS geometry — use containerStyle, not className
+<ScTextField tfGroup="none" containerStyle={{ height: "2.5rem", borderRadius: "0.75rem" }} />
+```
+
+---
+
+## 2. Where to use it
+
+- **Settings and profile forms** — the `@streamoid/settings` package stacks it for
+  name/email/referral rows; CXO's mobile settings do the same.
+- **Create/rename modals** — Catalogix `CreateStore`, `CreateWorkspace`,
+  `RenameProfile`, the Taxonomy add/edit modals.
+- **As a dropdown trigger** — Catalogix's `DsDropdown` and the settings
+  specialization picker both render a read-only `ScTextField` and own the menu
+  themselves.
+- **Inside `ScModal` / `ScDrawer` / mobile popups**, stacked with `ScTabField`,
+  `ScCheckField` and `ScAppField`, with an `ScButton` footer.
+
+All four host apps use it; it is part of the universal core.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The input needs a **visible label**, a required marker, an info popover or a
+  helper/description line.
+- You need a **ref** to the input (autofocus, imperative select, form libraries) —
+  this is the only field in the library that forwards one.
+- You need **native input props** (`type`, `maxLength`, `name`, `readOnly`,
+  `autoComplete`, `onKeyDown`) passed straight through.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Bare input, no label, and you need 40 px or 32 px height | `ScOnlyField` (`size="medium"` / `"small"`) |
+| Multi-line text (descriptions, prompts) | `ScTextArea` |
+| Choose one of N options from a menu | `ScSelect` |
+| Choose one of 2–4 options shown inline, in a form | `ScTabField` |
+| Boolean options with a shared label | `ScCheckField` |
+| File / image upload | `ScFileField` / `ScImageField` |
+| Per-app permission toggles | `ScAppField` |
+| A small action sitting next to the field ("Attach", "Browse") | `ScFieldButton` |
+| A search box in a toolbar or panel header | `ScOnlyField` with `tfRightIcon={<SiconSearch/>}` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScOnlyField` — no label row *ever*, `size` variants, `onInputChange(value)` instead of `onChange(event)` | `ScTextField` is the labelled, ref-forwarding, native-`onChange` one |
+| `ScAppField` — despite the name, **not** a generic field wrapper; it is a hardcoded three-app permission block | `ScTextField` is the text input |
+| `ScOnlyIcon` — an icon square, nothing to do with fields | `ScOnlyField` is the input; `ScOnlyIcon` is not |
+| `ScTextArea` — multi-line, and the only one of the three with real `error`/`disabled` styling | `ScTextField` ignores those states |
+
+---
+
+## 4. Why to use it
+
+- **The 48 px pill, the radius, the fill/border pairs and the focus ring are all
+  tokens.** Light mode and dark mode both resolve correctly with no conditional
+  in your code.
+- **Focus tracking is free.** The component keeps its own `focused` state and
+  derives `active`/`filled`, and it still calls your `onFocus`/`onBlur`.
+- **Escape hatches at every level** — `rootStyle`, `containerStyle`, `inputStyle`,
+  `descStyle`. You will need them: CSS-module rules beat a plain utility class on
+  ties, which is why hosts carry a
+  `.sc-text-field-full-width[class*="ScTextField_scTextField"]` hack in their
+  global CSS. Prefer `containerStyle` over fighting specificity.
+- **`required` + `info` + `desc` in one component** means the label row, the red
+  asterisk and the popover match across all four apps instead of being
+  re-invented per screen.
+
+---
+
+## Gotchas
+
+**1. The default field has a lightning bolt in it.** `tfGroup="icon-right"` +
+`tfRightIcon={<SiconBolt/>}` are both defaults.
+
+```tsx
+// WRONG — renders a ⚡ inside the field
+<ScTextField label="Name" labelGroup="label" />
+
+// RIGHT
+<ScTextField label="Name" labelGroup="label" tfGroup="none" />
+```
+
+**2. `label` alone renders nothing.** The label row is gated on
+`labelGroup || required || info`. Always pair `label` with `labelGroup="label"`.
+
+```tsx
+// WRONG — the label is dropped
+<ScTextField label="Email ID" tfGroup="none" />
+
+// RIGHT
+<ScTextField label="Email ID" labelGroup="label" tfGroup="none" />
+```
+
+**3. `state="error"` and `state="disabled"` are cosmetically dead.** There is no
+`.state-error` or `.state-disabled` rule in `ScTextField.module.css`. Passing
+either only *suppresses* the derived `filled`/`active` skins, leaving your typed
+value grey. For a genuine error, render your own message via `desc` and colour
+the container with `containerStyle`; for disabled, pass the native `disabled`
+attribute (which the browser greys) — and note the hover skin still fires.
+
+**4. Handlers go to the `<input>`, not the field.** `{...props}` is spread on the
+input, so `onClick` never fires when the user clicks the icon or the padding.
+Wrap the component in your own div for whole-field clicks (both the settings
+specialization picker and Catalogix's `DsDropdown` do exactly this).
+
+**5. `overflow: hidden` on the container clips slot content.** A menu, popover or
+tooltip rendered inside `leftSlot`/`rightSlot` will be cut off. Render it as a
+sibling of `ScTextField` (or portal it to `document.body`).
+
+**6. `labelGroup="text"` renders the hardcoded English word `"info"`.** There is
+no prop for it. `labelGroup="icon"` renders a bolt. Neither is localisable —
+use `info` (the real popover) instead.
+
+**7. A native `placeholder` wins over `placeholderFilled`.** `{...props}` is
+spread after `placeholder={placeholderFilled}`. Both work; don't pass both.
+
+**8. Derived `filled` needs a controlled `value`.** The derivation reads
+`props.value`; with `defaultValue` (uncontrolled) the field stays in the
+`default` skin and the text renders muted. Control the value or pass
+`state="filled"`.
+
+**9. `tall` does not make it multi-line.** It only grows the container to
+`min-height: 5rem` around a single-line `<input>`. For real multi-line use
+`ScTextArea`.
+
+**10. There are no `size` variants.** Height is a fixed `3rem`. If a spec calls
+for a 40 px or 32 px field, use `ScOnlyField` (`size="medium"`/`"small"`) or
+override with `containerStyle`.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/mobile-settings-content.tsx:259
+<ScTextField
+  key="fullName"
+  label="Full Name"
+  labelGroup="label"
+  placeholderFilled="Enter your name"
+  value={fullName}
+  onChange={(e: React.ChangeEvent<HTMLInputElement>) => setFullName(e.target.value)}
+  tfGroup="none"
+  className="w-full"
+/>
+```
+
+```jsx
+// catalogix/dashboard  app/components/DsDropdown/index.jsx:380
+<ScTextField
+  className="sc-text-field-full-width"
+  tfGroup="icon-right"
+  tfRightIcon={<span className={cx(styles["chev"], open && styles["chev-open"])}>
+    <SiconDown size={20} color="var(--alias-text-and-icons-tertiary)" />
+  </span>}
+  rightSlot={rightSlot}
+  state={fieldState}
+  value={displayText}
+  placeholder={placeholder}
+  readOnly
+  aria-haspopup="listbox"
+  aria-expanded={open}
+/>
+```
+
+---
+
+## Related
+
+- `ScOnlyField` — the unlabelled sibling with `size` variants; use for search and dense rows.
+- `ScTextArea` — multi-line, and the only text field with real `error`/`disabled` skins.
+- `ScSelect` — DS-native dropdown when you don't want to hand-roll a trigger.
+- `ScInfoPopup` — what the `info` prop renders; usable standalone.
+- `ScFieldButton` — the 36 px inline action that pairs with a field.
+- `ScTabField` / `ScCheckField` / `ScFileField` / `ScImageField` — the rest of the form vocabulary.