# Controls & fields

Every form widget. Read [Concepts → Control vs Field](./concepts.md#control-vs-field--the-key-distinction)
first if you haven't — it explains the two tiers. In short:

- **`*Field`** = captioned form row (label + control + description/info/validation).
  Put these in a `Section`.
- **`*Control`** = the bare widget. Place it yourself (toolbar, custom layout).

Remember the convention: **`value` is an accessor** (`() => V`), `onChange` is
`(next: V) => void`. With [`createEditorStore`](./state.md), `{...bind('path')}`
fills both in.

---

## Shared props

### Every `*Field` accepts

| Prop | Type | Notes |
|---|---|---|
| `name` | `string` | The caption. `""` renders no label, and the value spans the row. Pass `aria-label` then, since no caption names the control. |
| `value` | `() => V` | Value accessor. |
| `onChange` | `(next: V) => void` | Fires only for a user's edit, never on mount or when your code changes `value`. See [when it fires](./guides.md#reactive-values-and-change-events). |
| `readonly?` | `() => boolean` | Locks the field (see [Readonly](#readonly)). |
| `layout?` | `'compact' \| 'expanded'` | Row layout (see [Layout](#layout-compact-vs-expanded)). Some fields pin one. |
| `description?` | `string` | A muted help line under the control. |
| `info?` | `string \| (() => string)` | Shows an info `(i)` bubble beside the caption. |
| `id?` | `string` | Deep-link handle for [`focusField(id)`](./guides.md#deep-linking-to-a-field). |
| `validate?` | `(v: V) => ValidationResult \| null` | See [validation](./guides.md#validation--tooltips). |

Text-based fields (`TextField`, `TextareaField`) also take `minLength?`,
`maxLength?`, `pattern?: RegExp` (built-in validation helpers).

### Every `*Control` accepts

| Prop | Type | Notes |
|---|---|---|
| `value` | `() => V` | Value accessor. |
| `onChange` | `(next: V) => void` | Commit handler. |
| `readonly?` | `() => boolean` | Locks the control. |
| `aria-label?` | `string` | Accessible name (a field forwards its caption here). |
| `level?` | `'error' \| 'warn'` | Recolours the border (validation cue). |
| `onFocusIn?` / `onFocusOut?` / `onPointerEnter?` | event handlers | Validation/tooltip wiring; spread `{...v.controlHandlers}` from `createFieldValidation`. |

A control renders **only the widget** — no caption, no row. It emits the same CSS
classes the field uses, so theming is shared.

### Text inputs also accept

The five text-input fields/controls (`Text`, `Number`, `Textarea`, `Color`,
`Search`) take:

| Prop | Type | Notes |
|---|---|---|
| `touchSizing?` | `boolean` | On touch devices, render the input at 16px so focusing it doesn't trigger iOS Safari's zoom (it zooms any focused input under 16px). Default `true`. Set `false` to opt out — the input keeps its tier font and may zoom. Font-only: the row height and other controls are unaffected, and it has no effect on non-touch devices or the `small` tier (see [Theming](./theming.md#size-tiers)). |

All five also opt out of browser text assistance: no spellcheck, autocorrect,
auto-capitalization or autofill. Editor values are names, ids, paths and code,
not prose, so these only get in the way (and on mobile, autocorrect rewrites the
value as you type). This is fixed, not a prop.

The single-line inputs (`Text`, `Number`, `Color`, `Search`) treat Enter as
"done", never a newline. The on-screen key reads **Done** (**Go** for Search).
When the edit started from a touch or pen press, Enter releases focus, which
closes the on-screen keyboard. With a mouse or keyboard, Text and Number keep
focus on Enter, so Tab carries on as usual. Color always releases focus on Enter,
since Enter also closes its picker. Textarea keeps Enter as a newline.

---

## Value fields & controls

### Text — `TextField` / `TextControl`

Single-line text input.

```tsx
<TextField name="Project name" value={name} onChange={setName} placeholder="Untitled" />
```

| Extra prop | Type | Notes |
|---|---|---|
| `placeholder?` | `string` | |
| `minLength?` / `maxLength?` | `number` | Built-in validation. |
| `pattern?` | `RegExp` | Built-in validation. |
| `actions?` | `InputAction[]` | Buttons attached to the input's right edge (see below). |

**Attached action buttons (`actions`).** Seam a row of buttons flush to the
input's right edge — a copy / apply / reset action. Each `InputAction` is an icon
*or* a text `label`, with a `title` (shown as a tooltip on hover and keyboard focus, and used as its
`aria-label`), an `onClick`, and an optional reactive `disabled`. They're real `<button>`s, so they're
tab-reachable by default. (This is the same primitive the `SearchField` ◀▶ stepper
is built on.)

```tsx
import { Copy } from '@dolphinspired/solid-stage/icons';

<TextField
  name="API key" value={key} onChange={setKey}
  actions={[
    { icon: Copy, title: 'Copy', onClick: () => navigator.clipboard.writeText(key()) },
    { label: 'Apply', onClick: apply, disabled: () => key() === '' },
  ]}
/>
```

A readonly field does **not** auto-disable its actions (you can still copy a
readonly value) — set each action's own `disabled`.

### Number — `NumberField` / `NumberControl`

Numeric input with increment/decrement steppers (replacing the OS spinner).

```tsx
<NumberField name="Level" value={level} onChange={setLevel} min={1} max={99} step={1} />
```

| Extra prop | Type | Notes |
|---|---|---|
| `min?` / `max?` / `step?` | `number` | Clamps (Kobalte number-field). |
| `steppers?` | `boolean` | Show the up/down steppers. Default `true`; always hidden when readonly. |

`value` is a `number` and `onChange` a `number` — the Kobalte raw-value plumbing
is internal.

### Textarea — `TextareaField` / `TextareaControl`

Multi-line text. **Expanded layout only** (it's tall by design). Regular text by
default; set `monospace` for code / JSON / shader source. Keyboard-focus puts the
caret at the start; pointer-focus keeps where you clicked.

```tsx
<TextareaField name="Notes" value={notes} onChange={setNotes} minHeight={64} maxHeight={240} />
<TextareaField name="Shader" value={src} onChange={setSrc} monospace />
```

| Extra prop | Type | Notes |
|---|---|---|
| `placeholder?` | `string` | |
| `minHeight?` / `maxHeight?` | `number` (px) | Sizes the box. |
| `monospace?` | `boolean` | Monospace font for code. Default off (regular text). |
| `minLength?` / `maxLength?` / `pattern?` | | Built-in validation. |

### Color — `ColorField` / `ColorControl`

A hex input + swatch that opens a colour-area + hue (+ optional alpha) popover.
**Compact layout only.**

> The value is a hex string **without** the leading `#`, **UPPERCASE** —
> `'8A8A8A'`, and 8 digits (`RRGGBBAA`) when `alpha` is on. (The input boxes
> display a leading `#`; it's presentation only, never part of the stored value.)

```tsx
<ColorField name="Tint" value={tint} onChange={setTint} alpha />
```

| Extra prop | Type | Notes |
|---|---|---|
| `alpha?` | `boolean` | Adds the opacity slider; value becomes 8-digit. Default `false`. |

There is **one** hex box, in the field itself — it displays `#` + uppercase hex,
accepts regex-limited typing, resolves the colour live on every keystroke, and
normalizes on blur. The swatch opens the picker popover (colour area + hue + optional
alpha); the picker and the hex box edit the same value, so the box stays usable
while the popover is open. The popover **stays open until you interact outside both
the field and the picker** (click elsewhere, or Tab to another field); **Enter or
Escape in the hex box** also closes it. It carries a border-matched arrow pointing
at the field.

The popover opens **beside** the field (right, flipping left) in a panel/module, but
**below/above** in a horizontal bar (`FieldBar` / toolbar) — it reads the field
layout. The hex box is the field's only tab stop; the swatch is mouse-only.

### Boolean — `BooleanField` / `BooleanControl`

A switch (default) or checkbox.

```tsx
<BooleanField name="Snap to grid" value={snap} onChange={setSnap} />
<BooleanField name="Visible" value={vis} onChange={setVis} variant="checkbox" />
```

| Extra prop | Type | Notes |
|---|---|---|
| `variant?` | `'toggle' \| 'checkbox'` | Default `'toggle'` (sliding switch). |
| `aria-label?` | `string` | Names a field with `name=""`. The glyph then sits at the start of the row. |

> **Note:** `BooleanField` does *not* wrap `BooleanControl` — clicking the label to
> toggle requires the caption inside the Kobalte root, so the field wires its own
> caption. The control is a parallel bare widget. This is the one pair that
> doesn't follow the generic compose-a-control contract.

### Slider — `SliderField` / `SliderControl`

A track + thumb with a live value readout.

```tsx
<SliderField name="Opacity" value={op} onChange={setOp} min={0} max={1} step={0.01}
  format={(v) => `${Math.round(v * 100)}%`} sampleText="100%" />
```

| Extra prop | Type | Notes |
|---|---|---|
| `min` / `max` | `number` | **Required.** |
| `step?` | `number` | |
| `format?` | `(v: number) => string` | Format the readout text. |
| `sampleText?` | `string` | Widest value the readout will show (e.g. `"100.0%"`). The right-anchored readout reserves exactly that text's rendered width so the bar never shifts as digits change. Without it, a 3ch default is reserved — set this whenever your formatted value can exceed ~3 chars. |

### Select — `SelectField` / `SelectControl`

A dropdown over a fixed list of string options.

```tsx
<SelectField
  name="Mode"
  value={mode}
  onChange={setMode}
  options={['walk', 'run', 'idle']}
  optionLabels={{ walk: 'Walking', run: 'Running', idle: 'Idle' }}
/>
```

| Extra prop | Type | Notes |
|---|---|---|
| `options` | `ReadonlyArray<V>` | **Required.** `V extends string`. |
| `optionLabels?` | `Record<string, string>` | Display label per option value. |
| `renderOption?` | `(value: V) => JSX.Element` | Rich per-option content (icon, swatch, preview) on the list **and** the trigger. |
| `overflow?` | `'fit' \| 'wrap'` | How options wider than the trigger behave. Default `'fit'`. |
| `maxWidth?` | `number` | Width cap (px) for `overflow="fit"`. Defaults to the `--stage-select-content-max-width` token (400). |
| `actions?` | `SelectFieldAction[]` | Icon buttons flush-right of the trigger (see below). |
| `disabled?` | `() => boolean` | |
| `align?` | `FieldAlign` | Value-cell alignment (field only). |

`readonly` maps to `disabled` (a `<select>` has no readonly state).

**Attached actions (`actions`).** Each `SelectFieldAction` is
`{ icon, title, onClick, active?, disabled?, border?, tone? }` — an icon button
flush-right of the trigger (e.g. a prev/next stepper). `border` frames it to
match other bordered icon buttons (`IconButton.border`, `ButtonGroup`
`buttonBorder`); `tone` (`'accent' | 'danger' | 'warning'`) sets the active
fill. Both are **per-action** (default off), so a mixed row stays expressible.

**Long options.** By default (`overflow="fit"`) the dropdown grows to fit its
longest option — expanding in the reading direction and sliding back toward the
page when it nears the viewport edge — up to `maxWidth` (the
`--stage-select-content-max-width` token, 400px), past which option text wraps.
The trigger itself always ellipsis-truncates. Pass `overflow="wrap"` to pin the
list to the trigger width and wrap long option text instead.

```tsx
<SelectField name="Mode" value={mode} onChange={setMode} options={modes} />            {/* fit (default) */}
<SelectField name="Mode" value={mode} onChange={setMode} options={modes} overflow="wrap" />
<SelectField name="Mode" value={mode} onChange={setMode} options={modes} maxWidth={240} /> {/* fit, narrower cap */}
```

For rich options — an icon, a swatch, a font sample — pass `renderOption`. It
replaces the plain label on both the list rows and the selected-value trigger;
typeahead and accessibility still use the text label (so keyboard search keeps
working). Keep `optionLabels` set when the value isn't human-readable on its own.

```tsx
<SelectField
  name="Font"
  value={font}
  onChange={setFont}
  options={fonts}
  renderOption={(f) => <span style={{ 'font-family': f }}>Aa — {f}</span>}
/>
```

> ⚠️ `options` (and `optionLabels`) must be a **stable** value or wrapped in
> `createMemo` — never a bare getter that reads a store/signal on every access.
> The library memoizes internally, but a store-reading `options` getter is still
> a smell. Create a memo and pass its value: `options={folders()}`.

### Search — `SearchField` / `SearchControl`

An async combobox: type a query, the library calls your `search` fn, you pick a
result. The primitive owns *all* the dropdown chrome (loading, recents, empty,
"showing N of M"). You supply the data.

```tsx
const search: SearchFn<Monster> = async (query, ctx) => {
  const items = await api.search(query, { signal: ctx.signal });
  return {
    items: items.map((m) => ({ id: m.id, label: m.name, description: m.kind, payload: m })),
    total: items.length,
  };
};

<SearchField
  name="Monster"
  value={picked}                 // committed label string
  onChange={(item) => setPicked(item.label)}   // item: SearchItem<Monster>
  search={search}
  recentsKey="monster-search"    // opt into persisted recents
/>
```

The data types (also exported):

```ts
interface SearchItem<P = unknown> {
  id: string;
  label: string;
  description?: string;
  badge?: string;
  payload: P;          // your raw object, handed back in onChange
}
interface SearchResult<P> { items: ReadonlyArray<SearchItem<P>>; total?: number; }
interface SearchContext { signal: AbortSignal; name: string; filter?: string; }
type SearchFn<P> = (query: string, ctx: SearchContext) => Promise<SearchResult<P>>;
```

Key props (full list in the type):

| Prop | Type | Notes |
|---|---|---|
| `value` | `() => string` | The committed label. |
| `onChange` | `(item: SearchItem<P>) => void` | Fires on pick (carries your `payload`). |
| `search` | `SearchFn<P>` | Your async data fn. Honour `ctx.signal`. |
| `minQueryLength?` | `number` | Default `1`. |
| `debounceMs?` | `number` | Default `150`. |
| `allowEmpty?` | `boolean` | Empty-on-blur clears (fires `onClear`) instead of reverting. |
| `onClear?` | `() => void` | Consumer commits the empty value. |
| `recentsKey?` | `string` | Persist recents under this key. |
| `maxRecents?` | `number` | Default `8`. |
| `reconcileRecent?` | `(item) => SearchItem \| null` | Validate/refresh each stored recent before display. |
| `stepItems?` | `() => ReadonlyArray<SearchItem<P>>` | Adds ◀▶ to step the selection through this list. |
| `itemRender?` | `(item) => JSX.Element` | Override the result row. |
| `valueRender?` | `() => JSX.Element` | Rich committed value painted over the input **at rest** (hidden while editing). Omit for plain text. |
| `recentsHeader?` / `resultsHeader?` / `emptyLabel?` / `recentsFooter?` / `resultsFooter?` … | text or JSX | Override dropdown chrome. |

**Rich committed value (`valueRender`).** By default the resting field shows the
plain label text. Pass `valueRender` to paint rich content over it instead — a
badge pill beside the name, say — so the bar matches your `itemRender` rows
(`SelectField`'s `renderOption` does the same for a fixed-options trigger). It's
**consumer-driven** (you read your own signals), so it also covers a value seeded
from persistence with no pick — derive the display from the committed name:

```tsx
<SearchField
  value={picked}
  itemRender={(m) => <><Pill>{m.payload.dex}</Pill> {m.label}</>}   // dropdown rows
  valueRender={() => { const m = currentItem(); return m ? <><Pill>{m.payload.dex}</Pill> {m.label}</> : <></>; }}
  search={search}
/>
```

The overlay is `aria-hidden` / `pointer-events:none`; the real `<input>` stays the
accessible value and sole tab stop. It hides the instant you focus to edit and
returns on blur/pick. (Plain text is just this slot's default — there's one input
structure either way.)

**On touch devices.** The on-screen keyboard's Enter key reads **Go**, and Enter
picks the highlighted result. With a mouse or keyboard, a pick leaves the input
focused, resting on the selection, so Tab carries on from there. When the session
started from a touch or pen press, a pick (tap or Enter) blurs the input instead,
which closes the on-screen keyboard. So does Enter with nothing to pick.

> Need the *filter* interaction instead (query stays in the input, selection shown
> separately, a sibling category filter)? That's not a built-in — compose it from
> the exported search pipeline. See [Guides → custom search](./guides.md#building-a-custom-search-or-filter-control).

---

## Buttons

These are **actions, not values**, so they don't follow the `*Control`/`*Field`
split (the one exception is `ButtonGroupControl`, which has a field partner).
Icon buttons take an `IconComponent` — see [Icons](./icons.md).

### `IconButton`

A square icon button.

```tsx
import { Copy } from '@dolphinspired/solid-stage/icons';
<IconButton icon={Copy} title="Copy" onClick={copy} />
```

| Prop | Type | Notes |
|---|---|---|
| `icon` | `IconComponent` | |
| `onClick` | `() => void` | |
| `title?` | `string` | What the button does: shown as a library tooltip on hover and keyboard focus, and used as its `aria-label` (required for icon-only a11y). The library emits no native `title`. |
| `active?` | `() => boolean` | Pressed/active state (`aria-pressed` when supplied). |
| `disabled?` | `() => boolean` | |
| `tone?` | `'accent' \| 'danger' \| 'warning'` | |
| `border?` | `boolean` | |
| `subtle?` | `boolean` | Muted glyph for secondary/meta actions. |
| `untoggles?` | `boolean` | The button turns *off* when clicked while active (a toggle, not a radio), so an **active** button keeps lighting up on hover. Default `false` (a radio-style active button does nothing on re-click, so it stays put). Set for you by `IconToggle` / `IconToggleField`; leave off for `ButtonGroupControl` options. |
| `tabbable?` | `boolean` | `false` = mouse-only (out of tab order). |
| `debounce?` | `boolean \| number` | Debounce clicks. |

### `IconToggle`

A two-state icon button (controlled or uncontrolled).

| Prop | Type | Notes |
|---|---|---|
| `icon` | `IconComponent` | |
| `value?` | `() => boolean` | Controlled pressed state. |
| `defaultPressed?` | `boolean` | Uncontrolled seed. |
| `onChange?` | `(next: boolean) => void` | |
| `title?`, `disabled?`, `tone?`, `border?`, `debounce?`, `tabbable?` | | As `IconButton`. |

### `ActionButton`

A text button (with optional leading/trailing icon).

```tsx
<ActionButton label="Export" icon={FloppyDisk} onClick={save} variant="primary" />
```

| Prop | Type | Notes |
|---|---|---|
| `label` | `string` | |
| `onClick` | `() => void` | |
| `variant?` | `'primary' \| 'ghost' \| 'tool'` | Default `'primary'` — a filled well. `'ghost'` is a **borderless text button** (no frame, no rest fill; the hover reveals a fill) for secondary/tertiary actions like a Reset beside a Save. `'tool'` is a left-aligned toolbar button. |
| `icon?` | `IconComponent` | Leading icon (an icon component — see [Icons](./icons.md)). |
| `trailing?` | `() => JSX.Element` | Trailing slot (arbitrary content, e.g. a dirty-dot badge). |
| `active?` | `() => boolean` | Marks a selected or on state: an accent fill plus `aria-pressed`. Use this rather than swapping `variant`. |
| `disabled?` | `() => boolean` | |
| `fill?` | `boolean` | Stretch to container width. |

### `ToggleButton`

A labelled on/off button.

```tsx
<ToggleButton value={shown} onChange={setShown} labelOn="Shown" labelOff="Hidden" />
```

### `ButtonGroupControl` / `ButtonGroupField`

A segmented row of buttons (one logical group). `value` highlights the active id.

```tsx
<ButtonGroupControl
  value={() => tool()}
  options={[
    { id: 'move', icon: Crosshair, title: 'Move', onClick: () => setTool('move') },
    { id: 'rotate', label: 'Rotate', onClick: () => setTool('rotate') },
    { kind: 'static', render: () => <span>·</span> },   // non-button slot
  ]}
  justify="fill"
/>
```

| Prop | Type | Notes |
|---|---|---|
| `options` | `ButtonGroupOption<V>[]` | Each is a button `{ id, icon?, label?, title?, variant?, onClick, disabled? }` or `{ kind: 'static', render }`. |
| `value?` | `() => V \| null` | The active id (highlights it). |
| `direction?` | `'horizontal' \| 'vertical'` | |
| `justify?` | `'start' \| 'center' \| 'end' \| 'fill'` | Self-alignment when spanning its container; `fill` shares width across buttons. |
| `buttonSize?` / `buttonVariant?` | | Label options default to `primary` (same as a standalone `ActionButton` — a group is just normal buttons). Pass `buttonVariant="ghost"` to de-emphasize the group, or set `variant` on one label option to override it. |
| `buttonBorder?` | `boolean` | Frame **icon-only** options with a border + subtle background so an icon group reads as framed like a labelled one. Default `false`. |
| `buttonTone?` | `'accent' \| 'danger' \| 'warning'` | Tone palette for icon-only options. |

`ButtonGroupField` is the captioned wrapper — same props plus `name`, `align`,
`layout`, `description`, `info`. In a field row the button group sizes to its content and anchors
at the right of the value cell; the caption (left) truncates with an ellipsis to
make room (so buttons never overflow past the field). Use `layout="expanded"` to
give the buttons their own row instead.

### `IconButtonField` / `IconToggleField`

A **field row** holding a *set* of icon buttons / toggles (e.g. an alignment row).

```tsx
<IconButtonField
  name="Actions"
  items={[
    { icon: Copy, title: 'Copy', onClick: copy },
    { icon: Trash, title: 'Delete', onClick: del },
  ]}
/>

<IconToggleField
  name="Channels"
  multiple
  value={() => active()}
  onChange={setActive}
  items={[
    { id: 'r', icon: () => <span>R</span>, title: 'Red' },
    { id: 'g', icon: () => <span>G</span>, title: 'Green' },
  ]}
/>
```

A set of more than four buttons auto-switches to the expanded (wrapping) layout.

---

## Display & layout helpers

### `Label`

Static, display-only text (a section blurb, a status line, a bar app title). No
value, untouched by `bind`. Drive it with a reactive `text`.

```tsx
<Label text={() => `${count()} items`} />
<Label text="Read the docs" layout="bar" />
<Label text="3 tiles will be deleted first." layout="expanded" level="warn" />
// Inline rich content (e.g. a link) via a thunk:
<Label text={() => <>See <a href="/docs">docs</a></>} />
```

| Prop | Type | Notes |
|---|---|---|
| `text` | `string \| (() => JSX.Element)` | The content. Both forms are reactive — a string read (`text={desc()}`) or a thunk reading a signal (`text={() => statsLine(stats())}`) both re-render on change. A thunk also carries light inline rich content (chiefly a link). |
| `align?` | `'left' \| 'center' \| 'right'` | Compact/expanded only. |
| `level?` | `'info' \| 'success' \| 'warn' \| 'error'` | Colors the text as a status message, from `--stage-color-<level>`. Color alone can't carry the meaning, so word the message to say it too. |
| `layout?` | `'compact' \| 'expanded' \| 'bar'` | |
| `size?` | `'small' \| 'normal' \| 'large'` | |
| `class?` | `string` | Style hook (italic/bold/colour). |

It's a caption, not a rich-text surface — keep content to inline accents.

A compact `Label` stays on one line and truncates, so give a sentence
`layout="expanded"` to let it wrap. A `Label` is a row with no margin of its own, so
stack several in a `FieldGroup`.

### `ReadoutField`

A caption and a value that only the app changes, such as a resolved path, a frame count
or a status. A user can select and copy it, but it has no input frame, `onChange` or focus
stop. For a field that's editable in other states, use `readonly` on the normal field.

```tsx
<ReadoutField name="Source" value={() => model().path} />
<ReadoutField name="Notes" layout="expanded" value={notes} />
```

| Prop | Type | Notes |
|---|---|---|
| `name` | `string` | The caption. |
| `value` | `() => string \| number` | Digits keep an even width, so a changing number doesn't shift. |
| `layout?` | `'compact' \| 'expanded' \| 'bar'` | Compact truncates a long value; expanded wraps it on its own row. Adopts `bar` in a `FieldBar`. |
| `description?`, `info?` | | As on other fields. |

### `Field`

The base layout primitive every `*Field` builds on. You only touch this when
[building a custom field](./guides.md#building-a-custom-field). It renders the
caption + row skeleton and a render-prop that receives the value accessor.

### `FieldGroup`

Groups fields with consistent vertical rhythm. Wrap a section's fields:

```tsx
<Section title="Transform">
  <FieldGroup>
    <NumberField name="X" {...bind('x')} />
    <NumberField name="Y" {...bind('y')} />
  </FieldGroup>
</Section>
```

### `Fieldset`

A labeled, **value-less** group of fields — the gap between `FieldGroup` (stacks
rows, no heading) and `Section` (a full collapsible panel with its own persist
key). It renders the expanded-field heading (caption + trailing rule) over a
stacked `FieldGroup` body, for grouping related controls under one inline heading.

```tsx
<Fieldset label="Effects" description="Post-processing toggles.">
  <BooleanField name="Bloom" {...bind('bloom')} />
  <BooleanField name="Shadows" {...bind('shadows')} />
  <BooleanField name="Eye shine" {...bind('eyeShine')} />
</Fieldset>
```

| Prop | Type | Notes |
|---|---|---|
| `label` | `string` | Inline heading (the legend) naming the group. |
| `description?` | `string` | Optional blurb under the heading. |

**Display-only / structural** — no `value`/`onChange`/`bind` (like `Label`); the
child fields own their state. Rendered as `role="group"` named by the caption via
`aria-labelledby` (not a native `<fieldset>`/`<legend>`, which fight the
caption+rule layout). Flat and non-collapsible by design — reach for `Section`
when you need collapse or a persisted panel. Conditional members (show a toggle
only in some mode) and nested controls (a slider under its toggle) are the
consumer's own `<Show>`, not a `Fieldset` feature.

### `FieldBar`

Lays fields out **horizontally** for a bar/toolbar context (sets the `bar` layout
on its children automatically). Optional `separator` between items.

```tsx
<FieldBar separator="·">
  <SelectControl ... />
  <BooleanControl ... />
</FieldBar>
```

| Prop | Type | Notes |
|---|---|---|
| `separator?` | `string` | Glyph between items (default `·`; `''` omits). |
| `grow?` | `boolean` | Fluid mode (default off). |
| `class?` / `style?` | `string` / `JSX.CSSProperties` | Applied to the cluster element — the natural place to set the `--stage-bar-value-width` cap (see below). |

Bar fields are **fixed-width** by default (`--stage-bar-value-width`, 110px). Pass
`grow` for a **fluid** cluster: it stretches into its `Toolbar` anchor and its
field children grow to fill it, then **shrink** when the bar is cramped instead of
overflowing. In fluid mode the two width tokens become **bounds**: a field's
width is `clamp(--stage-bar-value-min-width, available, --stage-bar-value-width)`
— it grows up to the cap (`--stage-bar-value-width`) and shrinks down to the floor
(`--stage-bar-value-min-width`, 96px). The floor keeps the input usable and stops
its attached buttons (a `SearchField` stepper, `TextField` actions) from being
squeezed out of their box and overlapping the inline label. Non-field siblings
(e.g. an `ActionButton`) stay content-sized. Use it for a search/filter field that
should fill a toolbar yet degrade gracefully on narrow panes — set the cap with
`class`/`style` **on the cluster itself** (an extra wrapper element would break
the flex grow chain):

```tsx
<FieldBar grow style={{ '--stage-bar-value-width': '24rem' }}>
  <SearchField name="Model" layout="bar" … />
  <ActionButton label="Browse" onClick={…} />  {/* stays content-sized */}
</FieldBar>
```

Spare room beyond the cap lands after the last item. Use
`--stage-bar-value-width: none` to remove the cap.

The stretch relies on a definite-width anchor, so `grow` is meaningful in the
`1fr` `left` / `right` `Toolbar` cells (not the content-sized `center` cell).

### `InfoIcon`

The `(i)` info bubble used by fields' `info` prop. Rendered automatically when a
field has `info` set; exported for custom use.

---

## Readonly

Every value field/control takes `readonly?: () => boolean`. It maps to the native
`readonly` attribute where one exists (text/number/textarea, the colour hex box)
and to `disabled` otherwise (select/boolean/slider, the colour swatch).

Readonly is shown with **solid colours** (lighter fill, muted text, softer
border) — never opacity — and the control drops out of the tab order.

```tsx
<TextField name="Id" value={id} onChange={setId} readonly={() => true} />
```

## Layout: compact vs expanded

Each field row is either:

- **`compact`** (default) — label and value share one row.
- **`expanded`** — label on its own row (with a trailing rule), value full-width
  below it.

Set `layout="expanded"` per field. Some fields pin one: `BooleanField` and
`ColorField` are compact-only; `TextareaField` is expanded-only.