# Guides

How-tos that go beyond the reference. Each builds on the
[Concepts](./concepts.md) — especially the [control vs field
split](./concepts.md#control-vs-field--the-key-distinction).

**Using the library:**

- [Composing a section body](#composing-a-section-body)
- [Custom content and custom CSS](#custom-content-and-custom-css)
- [Reactive values and change events](#reactive-values-and-change-events)
- [Choosing a button](#choosing-a-button)
- [A toolbar with a fluid search](#a-toolbar-with-a-fluid-search)
- [Designing dock sections](#designing-dock-sections)
- [App-wide shortcuts and saved state](#app-wide-shortcuts-and-saved-state)

**Extending it:**

- [Building a custom control](#building-a-custom-control)
- [Building a custom field](#building-a-custom-field)
- [Validation & tooltips](#validation--tooltips)
- [Building a custom search or filter control](#building-a-custom-search-or-filter-control)
- [Deep-linking to a field](#deep-linking-to-a-field)

---

## Composing a section body

A `Section` body has padding and nothing else. It doesn't arrange what you put in it,
which is what makes custom content possible. So the structure is yours to choose:

| You're adding | Use | Why |
|---|---|---|
| One field | The field on its own | Nothing to stack |
| Several fields | `FieldGroup` | Rows have no gap of their own; the group provides it |
| A titled block of fields | `Fieldset` | A group with a heading |
| A block that collapses | A nested `Section` | |
| A value only the app changes | `ReadoutField` | A caption and selectable text, with no input to imply it's editable |
| A sentence or two | `Label layout="expanded"` | A compact `Label` truncates to one line |
| A warning or status message | `Label level="warn"` | Same row, colored by severity |
| Richer prose, a table, a tree | Your own markup | See [Custom content and custom CSS](#custom-content-and-custom-css) |

**Every `*Field` and `Label` is a row, and a row has no margin.** Rows placed directly in
a section or modal body touch, with no error or warning, and it only looks slightly
wrong. So wrap any stack of two or more:

```tsx
<Section title="Camera">
  <FieldGroup>
    <SliderField name="FOV" {...bind('fov')} min={20} max={120} />
    <NumberField name="Near" {...bind('near')} />
    <BooleanField name="Orthographic" {...bind('ortho')} />
    <ReadoutField name="Aspect" value={aspect} />
  </FieldGroup>
</Section>
```

A group's direct children are its rows. A wrapper around one row is fine, but a wrapper
around several takes them out of the group's gap.

Bare content is deliberately supported, so a section holding a table or a canvas needs no
group. The rule is about stacks of rows, not about sections.

### Read-only or readout?

Both show a value a user can't change right now, and the difference is whether they ever
could. A field that's editable in some states uses `readonly` on its normal field, so it
keeps its shape when it locks. A value that only the app ever changes, like a resolved
path or a frame count, uses `ReadoutField`, which can also be selected and copied.

### Spacing between blocks

Spacing between two blocks in a body, like a `FieldGroup` and the buttons after it, is
yours. The library adds none, so that bare content stays free of surprises. A margin on
your own class is the intended answer, not a workaround:

```tsx
<FieldGroup>…</FieldGroup>
<div class="my-actions">
  <ButtonGroupControl
    justify="end"
    options={[
      { id: 'apply', label: 'Apply', onClick: apply },
      { id: 'revert', label: 'Revert', onClick: revert },
    ]}
  />
</div>
```

```css
.my-actions { margin-top: 8px; }
```

### Modal bodies and footers

A modal is one dismissable `Section`, so all of the above applies to its body. For a
footer with a primary action and a quieter one, set `variant` on the quieter option:

```tsx
<ButtonGroupControl
  justify="end"
  options={[
    { id: 'cancel', label: 'Cancel', variant: 'ghost', onClick: cancel },
    { id: 'save', label: 'Save', onClick: save },
  ]}
/>
```

Use `kind: 'static'` for non-button content such as a readout.

To widen a content-heavy modal, pass a class: `stageModal.open(content, { class: 'my-wide-modal' })`.

---

## Custom content and custom CSS

Everything inside `.stage-root` gets the tier's font size and the consumer's font family.
Beyond that, custom markup gets no library styling, so read the tokens rather than
repeating their values. A theme override then reaches your markup as well.

```css
.my-tree-row {
  padding: 2px 6px;
  color: var(--stage-color-text);
  border-radius: var(--stage-border-radius);
}
.my-tree-row:hover { background: var(--stage-color-control-hover-bg); }
.my-tree-row.selected {
  background: color-mix(in srgb, var(--stage-color-accent) 25%, var(--stage-color-panel-bg));
}
```

| You want | Token |
|---|---|
| Text | `--stage-color-text` |
| Disabled text | `--stage-color-text-disabled` |
| Hover fill | `--stage-color-control-hover-bg` |
| Borders | `--stage-color-border`, `--stage-color-border-strong` |
| Accent | `--stage-color-accent` |
| Text size, row height | `--stage-font-size`, `--stage-control-height` |
| Layering a custom popover | `--stage-z-popover` |

- **Skip `var()` fallbacks.** Every token is always defined inside `.stage-root`, so a
  fallback does nothing except hide a misspelled or invented name.
- **`--stage-color-text-muted` doesn't dim by default.** It equals `--stage-color-text`
  until a theme overrides it. Use `-text-disabled`, or mix your own, when you need a
  dimmer tone.
- **Keyboard access is yours.** A `<div onClick>` has no focus stop. Use a real `<button>`,
  or add `tabindex` and key handling.
- **To adjust one section's body padding,** give it a class (`Section` and `SectionDef`
  both take `class`) and set `--stage-section-body-pad` there.

Consumers can override anything, and [Theming](./theming.md#which-classes-are-stable) lists
which classes won't change without notice. If you find yourself selecting an internal
class because there's no other way to do something, that's a missing feature, so please
ask for it.

---

## Reactive values and change events

**Buttons in an option array can read signals inline.** Options render by position, so a
new array updates the existing buttons, and keyboard focus stays where it was:

```tsx
<ButtonGroupField
  name="Playback"
  options={[{ id: 'play', label: playing() ? 'Pause' : 'Play', onClick: toggle }]}
/>
```

**`SelectField` options should be memoized when derived,** because a rebuilt list is a real
change for a dropdown: `options={folders()}` with `const folders = createMemo(() => …)`.

**When `onChange` fires:**

| Field | Fires |
|---|---|
| `TextField`, `TextareaField` | On every keystroke |
| `NumberField` | While typing, and again on blur if `min`/`max` clamp the value |
| `SliderField` | Throughout a drag |
| Everything else | When the user commits a choice |

No field fires `onChange` on mount or when your code changes its value, so `onChange` always
means a person did something.

So a text field wired straight to a save writes once per character. Keep a draft and
commit it when the user is done:

```tsx
const [draft, setDraft] = createSignal(name());
<div
  onFocusOut={() => rename(draft())}
  onKeyDown={(e) => { if (e.key === 'Enter') rename(draft()); }}
>
  <TextField name="Name" value={draft} onChange={setDraft} />
</div>
```

`NumberField` can pass through an out-of-range or fractional value while someone is
typing, since clamping waits for blur and `step` doesn't round. Validate before acting on
it if a bad value would do harm.

---

## Choosing a button

| You want | Use |
|---|---|
| Run a command | `ActionButton`, or `IconButton` for an icon alone |
| Switch something on and off | `ToggleButton`, or `IconToggle` |
| Pick exactly one of a few | `ButtonGroupField` with `value` |
| Pick one or none, or several | `IconToggleField` |
| Pick from many | `SelectField` |

- **Show state with `active`, not by swapping `variant`.** `active` also sets `aria-pressed`.
- **`primary` is the main action, `ghost` the quieter one beside it,** as with Save and
  Discard. Equal-weight actions can all be `primary`.
- **Pass `icon` the component,** as in `icon={Copy}`, rather than a thunk.
- **`size="sm"` on an icon button doesn't change its size today.** Change size with the
  `size` prop on a container or a `.stage-size-*` class.
- **If a row of buttons squeezes its caption,** use `layout="expanded"` on the
  `ButtonGroupField` so the buttons get their own row.

---

## A toolbar with a fluid search

`FieldBar grow` lets a field stretch with the bar. `--stage-bar-value-width` caps it, and
any spare room lands after the last item:

```tsx
<Toolbar
  left={
    <FieldBar grow style={{ '--stage-bar-value-width': '24rem' }}>
      <SearchField name="Model" layout="bar" search={search} value={label} onChange={pick} />
      <ActionButton label="Browse" onClick={browse} />
    </FieldBar>
  }
/>
```

For no cap at all, use `--stage-bar-value-width: none`.

Put the cluster directly in `left` or `right`, set the width on the cluster itself, and
keep fields as its direct children. A wrapper breaks the stretch.

A `Toolbar` centers its middle anchor, so when `center` has content, `left` and `right`
each get at most half the bar. Leave `center` empty and they share the whole bar.

---

## Designing dock sections

A section in a `DockZone` can move between docks, and that shapes how you write it.

**`render` runs again every time the section moves,** so anything created inside it is
lost on a move. Keep state that must survive outside `render`:

```tsx
function createCameraSection(viewer: Viewer): SectionDef {
  // Lives as long as the section definition, not as long as one placement.
  const [fov, setFov] = createSignal(60);
  return {
    title: 'Camera',
    dock: 'controls',
    render: () => <SliderField name="FOV" value={fov} onChange={setFov} min={20} max={120} />,
  };
}
```

**A section's `title` updates through a getter,** since the definition is a plain object:

```tsx
{ get title() { return `Variants (${variants().length})`; }, dock: 'info', render: … }
```

**Several independent viewports can each have their own layout,** when their sections drive
one viewport and shouldn't cross to another. Give each its own `createSectionLayout`,
`SectionLayoutProvider` and `StageFloatHost`. A drag only sees its own layout's docks, so a
section released over another viewport's dock floats instead of crossing. Keep one layout
for the whole app when sections should be free to move anywhere.

---

## App-wide shortcuts and saved state

**A window-level key handler has to step aside for library controls.** Checking for
`INPUT` and `SELECT` isn't enough, since `SelectField` is a `button` with a portaled list:

```ts
function shouldIgnoreShortcut(e: KeyboardEvent): boolean {
  if (stageModal.isOpen()) return true;
  return (
    e.target instanceof Element &&
    e.target.closest(
      'input, textarea, button, [contenteditable], [role="listbox"], .stage-field-control',
    ) !== null
  );
}
```

Don't identify fields by `aria-label`, since it comes from the caption and changes with it.

**Saved state lives under `stage-` keys in `localStorage`:** `stage-panel:`, `stage-section:`
and `stage-layout:`. That prefix is reserved for the library. To restore the arrangement,
call [`layout.reset()`](./dnd.md#resetting-the-layout). To clear everything, remove keys with
those prefixes.

---

## Building a custom control

A **control** is the bare widget. To fit the library, honour the control
contract so it themes and validates like the built-ins:

- Take a `value: () => V` accessor and an `onChange: (next: V) => void`.
- Take `readonly?: () => boolean`, an `aria-label`, and the validation props
  (`level` + the three focus/hover handlers) by extending `ControlValidationProps`.
- Render only the widget, using `stage-*` classes so it inherits the theme.

```tsx
import { type ControlValidationProps } from '@dolphinspired/solid-stage';
import { type JSX } from 'solid-js';

interface StarRatingControlProps extends ControlValidationProps {
  value: () => number;
  onChange: (next: number) => void;
  max?: number;
  readonly?: () => boolean;
  'aria-label'?: string;
}

export function StarRatingControl(props: StarRatingControlProps): JSX.Element {
  const max = () => props.max ?? 5;
  const locked = () => props.readonly?.() ?? false;
  return (
    <div
      class="stage-input star-rating"
      role="slider"
      aria-label={props['aria-label']}
      aria-valuenow={props.value()}
      data-stage-level={props.level}            // border recolour on error/warn
      onFocusIn={props.onFocusIn}               // validation tooltip wiring
      onFocusOut={props.onFocusOut}
      onPointerEnter={props.onPointerEnter}
      tabindex={locked() ? -1 : 0}
    >
      {Array.from({ length: max() }, (_, i) => (
        <button
          type="button"
          disabled={locked()}
          aria-pressed={props.value() > i}
          onClick={() => props.onChange(i + 1)}
        >★</button>
      ))}
    </div>
  );
}
```

Key contract points:

- **`data-stage-level={props.level}`** on the root gives you the error/warn border
  recolour the built-ins use.
- **Spread the three handlers** (`onFocusIn` / `onFocusOut` / `onPointerEnter`) onto
  the focusable root so validation tooltips appear on focus/hover.
- **Respect `readonly`** — drop out of the tab order (`tabindex={-1}`) and disable
  interaction, and dim with *colour* not opacity.

That control is now usable on its own (a toolbar, a custom layout). To give it a
captioned row, wrap it in a field.

## Building a custom field

A **field** composes your control with the `Field` layout primitive and
`createFieldValidation`. The pattern is identical for every built-in — here's the
whole of `SliderField`, adapted:

```tsx
import {
  Field, createFieldValidation,
  type FieldValidationProps, type FieldInfoProps, type FieldLayout,
} from '@dolphinspired/solid-stage';
import { StarRatingControl } from './StarRatingControl';

interface StarRatingFieldProps extends FieldValidationProps<number>, FieldInfoProps {
  name: string;
  id?: string;
  value: () => number;
  onChange: (next: number) => void;
  max?: number;
  layout?: FieldLayout;
  readonly?: () => boolean;
  description?: string;
}

export function StarRatingField(props: StarRatingFieldProps) {
  const v = createFieldValidation<number>({
    value: () => props.value(),
    name: () => props.name,
    validate: props.validate,
  });
  return (
    <Field
      name={props.name}
      id={props.id}
      value={props.value}
      layout={props.layout}
      fieldType="star-rating"          // → .stage-field-star-rating
      description={props.description}
      info={props.info}
      IconComponent={props.IconComponent}
    >
      {(value) => (
        <StarRatingControl
          value={value}
          onChange={props.onChange}
          max={props.max}
          readonly={props.readonly}
          aria-label={props.name}
          level={v.borderLevel()}        // error/warn → control border
          {...v.controlHandlers}         // focus/hover tooltip handlers
        />
      )}
    </Field>
  );
}
```

What's happening:

- **`createFieldValidation`** computes the reactive validation result and gives you
  `v.borderLevel()` (the `error`/`warn` cue) and `v.controlHandlers` (the
  focus/hover wiring). Thread both into the control.
- **`Field`** renders the caption row, the optional `description` line, and the info
  bubble (`info`). Its `children` is a **render-prop receiving the value
  accessor** — pass *that* to your control (not `props.value`), the un-keyed
  `<Show>` convention so the control mounts once.
- `extends FieldValidationProps<V>, FieldInfoProps` pulls in `validate`, `info`, and
  `IconComponent` for free.

Your field now drops into a `Section` like any built-in, with `bind`, validation,
info, and theming all working.

## Validation & tooltips

Every value field takes a `validate` callback. Return `null` for valid, or a
`ValidationResult` `{ level, content }` to flag it:

```tsx
import { type ValidationResult } from '@dolphinspired/solid-stage';

const validateLevel = (n: number): ValidationResult | null =>
  n < 0 ? { level: 'error', content: 'must be ≥ 0' } : null;

<NumberField name="Level" {...bind('level')} validate={validateLevel} />
```

- **`level`** is `'error' | 'warn' | 'success' | 'info'`. Only `error` and `warn`
  recolour the control's border; all four tint the tooltip bubble.
- **`content`** is a string or JSX, shown in the tooltip on focus/hover.

Text fields also have built-in helper validators that run *before* `validate`:
`minLength`, `maxLength`, `pattern` (first failure wins).

```tsx
<TextField name="Slug" {...bind('slug')} pattern={/^[a-z0-9-]+$/} maxLength={40} />
```

Validation never traps the user: a `validate` that throws is logged and treated as
valid. The cue is the border recolour plus the tooltip — there's no inline error
line.

If you build a custom field, `createFieldValidation` is the same machinery the
built-ins use; see [above](#building-a-custom-field).

## Building a custom search or filter control

`SearchField` is the standard async combobox. If you need a different interaction —
the classic **filter** model where the query stays in the input, the selection is
shown separately, and a sibling category `<select>` narrows results — compose it
from the **exported search pipeline** rather than re-deriving the debounce /
cancellation / stepping machinery.

```tsx
import {
  createSearchSource, stepThrough, SelectControl, createFieldValidation,
  type SearchFn, type SearchItem,
} from '@dolphinspired/solid-stage';
import { createSignal } from 'solid-js';

function CreatureFilter(props: { search: SearchFn<Creature> }) {
  const [query, setQuery] = createSignal('');
  const [kind, setKind] = createSignal('all');

  // The pipeline: debounce + monotonic token + AbortController, all handled.
  const source = createSearchSource<Creature>({ search: props.search });

  // Re-run when the query or the sibling filter changes:
  const onQuery = (q: string) => { setQuery(q); source.schedule(q, kind()); };
  const onKind  = (k: string) => { setKind(k);  source.schedule(query(), k); };

  return (
    <div>
      <input value={query()} onInput={(e) => onQuery(e.currentTarget.value)} />
      <SelectControl value={kind} onChange={onKind} options={['all', 'beast', 'undead']} aria-label="Kind" />

      {source.loading() && <span>Searching…</span>}
      <ul>
        {source.results()?.items.map((item) => <li>{item.label}</li>)}
      </ul>
    </div>
  );
}
```

`createSearchSource(opts)` returns:

| Member | Type | Notes |
|---|---|---|
| `results` | `() => SearchResult \| null` | The latest results (reactive). |
| `loading` | `() => boolean` | |
| `schedule(query, filter?)` | | Run a (debounced) search; `filter` reaches your `search` fn as `ctx.filter`. |
| `reset()` / `cancel()` | | Clear / abort in-flight. |

Your `SearchFn` receives `ctx.filter` (the sibling value) and `ctx.signal` (honour
it to cancel). For ◀▶ stepping through results, `stepThrough(list, currentId, dir)`
gives you the wrap math.

This is exactly how the library's own `SearchControl` is built, and why a
standalone `FilterControl` isn't shipped — it's fully composable from these pieces.

## Deep-linking to a field

Give a field an `id`, then focus it from anywhere with `focusField(id)` — a toast
action, a "jump to setting" button, another panel. It returns whether it found a
target.

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

<TextField id="project-name" name="Name" {...bind('name')} />

// elsewhere — a button, a toast, a different panel:
<ActionButton label="Rename" onClick={() => focusField('project-name')} />
```

What it handles for you:

- Focuses the field's **primary control** (skipping mouse-only chrome like a colour
  swatch or number steppers).
- **Scrolls the field into view** — deep-linking to a field in another scrollable
  panel scrolls that panel to it.
- **Expands collapsed sections and panels first** — a collapsed `Section` or `Panel`
  keeps its body mounted (just hidden), so `focusField` walks up expanding any collapsed ancestor
  sections, then focuses. It works even for a section never opened since load.

Wire it into a toast for a "go fix this" affordance:

```tsx
stageToast.push({
  level: 'warn',
  message: () => <span>Name is required. <a onClick={() => focusField('project-name')}>Fix</a></span>,
  autoDismissMs: null,
});
```