@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/scrub-input.md

@@ -0,0 +1,61 @@
+## What it is
+
+A number field you can drag: type into it, arrow it, click steppers, or scrub horizontally from a grip.
+
+It is the design-tool number input, and it handles the case a plain number field cannot — a **stepped scale** whose legal values are not evenly spaced.
+
+## The contract
+
+```
+@value?, @defaultValue? — null renders empty
+@min?, @max?
+@step?          — one arrow press, one stepper click, and @pixelsPerStep px of
+                  horizontal scrub each move by this much. Default 1
+@pixelsPerStep? — px of pointer travel that buys one step. Default 1, or 6
+                  on a stepped scale
+@steps?         — A STEPPED SCALE: the ordered list of legal values
+@precision?     — decimal places kept on commit. Default 2
+@unit?, @unitPosition? — 'px', '%', '°', 'ms'; prefix or suffix
+@grip?          — short text shown in the grip when there is no unit
+@scrubFrom?     — 'grip' scrubs from the affix only; 'field' makes the
+                  whole control a scrub surface; 'none'. Default 'grip' when
+                  there is a grip (@unit or @grip), otherwise 'field'
+@label?         — accessible name. REQUIRED in practice
+@placeholder?
+@steppers?      — show the up/down stepper pair
+```
+
+**`@steps` is the interesting arg.** Apertures, ISO speeds, type ramps and zoom levels are numeric without being continuous — the gaps between legal values are not uniform, so `@step` cannot describe them. Supply the ordered list and the control becomes a discrete spinbutton: scrub, arrows and steppers travel whole stops, `@min`/`@max` default to the ends of the list, a typed number snaps to the nearest legal value on commit, and the field shows the stop's label — `f/5.6` — while `aria-valuenow` still carries the number.
+
+**`@pixelsPerStep` defaults to 1, and to 6 on a stepped scale**, where one stop per pixel is unusable. Raise it for any control that needs a slower hand.
+
+**A scrub commits once, on release.** Move frames fire `@onInput`; `@onChange` gets the scrubbed value when the pointer lifts, so a controlled `@value` persisted only through `@onChange` still receives the drag. Escape or a `pointercancel` puts the starting value back through `@onInput` and commits nothing, and that Escape goes no further, so an enclosing dialog stays open.
+
+**`@scrubFrom='field'` still lets you select text**, because the field only scrubs while it is not focused.
+
+**`@label` is required in practice**: a bare spinbutton in a panel of twenty is unusable without one.
+
+## Prior art
+
+**figui3's** number input and steppers.
+
+Where Pretui is better: the stepped scale. Every design-tool number input assumes a uniform step, which means an aperture or ISO control has to be a select — losing the scrub — or a slider — losing the exact value. This is both.
+
+Where it is thinner: no expression evaluation (`120/2`), no unit conversion on typing, and no multi-value scrub across a selection.
+
+## Accessibility
+
+- **It is a spinbutton with a name**, and the name is the arg the contract calls required.
+- **On a stepped scale, `aria-valuenow` carries the number while the field shows the label.** A reader hears the value; a viewer sees the stop. Both are true, and neither is a translation of the other.
+- **Arrows, steppers and scrub all move by the same `@step`**, so the three input methods agree — a control where dragging and arrowing disagree is disorienting for anyone switching between them.
+- **Scrub is pointer-only by nature**, which is why arrows and steppers are not optional extras: they are the equal path.
+- **`@steppers` adds visible controls** that are useful well beyond keyboard users — a precise single increment is hard to scrub.
+- **Typed values snap on commit**, not on keystroke, so a reader can type through intermediate states.
+
+## Theming
+
+The control takes the kit's shared input and control tokens; the grip is a affix rather than a separate surface.
+
+There is deliberately no scrub-specific palette — a scrub input in a property panel should be indistinguishable from the other fields until you drag it.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/scrub-input.usage.gts

@@ -0,0 +1,275 @@
+// Pretui — ScrubInput usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { ScrubInput } from './scrub-input';
+import type { ScaleStops } from '../internal/design-tools';
+import { APERTURES } from '../demo-design-tools';
+
+// ── ScrubInput ───────────────────────────────────────────────────────────
+const SCRUB_FROM = ['grip', 'field', 'none'];
+
+const UNIT_POSITIONS = ['suffix', 'prefix'];
+
+class ScrubInputUsage extends Component {
+  scrubFromOptions = SCRUB_FROM;
+  unitPositionOptions = UNIT_POSITIONS;
+
+  @tracked value: number | null = 24;
+  @tracked committed: number | null = 24;
+  @tracked step = 1;
+  @tracked pixelsPerStep = 1;
+  @tracked precision = 2;
+  @tracked unit = 'px';
+  @tracked unitPosition = 'suffix';
+  @tracked scrubFrom = 'grip';
+  @tracked steppers = true;
+  @tracked mixed = false;
+  @tracked disabled = false;
+  @tracked labelText = 'Corner radius';
+  @tracked min: number | null = 0;
+  @tracked max: number | null = 200;
+  @tracked stepped = false;
+
+  setStepped = (v: boolean) => {
+    this.stepped = v;
+    // Swap the whole configuration together, so the knob shows the control
+    // in the two shapes a caller actually uses it in rather than a hybrid
+    // neither of them would ship.
+    if (v) {
+      this.value = 2.8;
+      this.committed = 2.8;
+      this.labelText = 'Aperture';
+      this.unit = '';
+      this.min = null;
+      this.max = null;
+      this.precision = 2;
+    } else {
+      this.value = 24;
+      this.committed = 24;
+      this.labelText = 'Corner radius';
+      this.unit = 'px';
+      this.min = 0;
+      this.max = 200;
+    }
+  };
+  get steps(): ScaleStops | undefined {
+    return this.stepped ? APERTURES : undefined;
+  }
+
+  setValue = (v: number | null) => (this.value = v);
+  commit = (v: number | null) => (this.committed = v);
+  setStep = (v: number) => (this.step = v);
+  setPixels = (v: number) => (this.pixelsPerStep = v);
+  setPrecision = (v: number) => (this.precision = v);
+  setUnit = (v: string) => (this.unit = v);
+  setUnitPosition = (v: string) => (this.unitPosition = v);
+  setScrubFrom = (v: string) => (this.scrubFrom = v);
+  setSteppers = (v: boolean) => (this.steppers = v);
+  setMixed = (v: boolean) => (this.mixed = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setLabel = (v: string) => (this.labelText = v);
+  setMin = (v: number) => (this.min = v);
+  setMax = (v: number) => (this.max = v);
+
+  get unitPositionVal() {
+    return this.unitPosition as 'prefix' | 'suffix';
+  }
+  get scrubFromVal() {
+    return this.scrubFrom as 'grip' | 'field' | 'none';
+  }
+  get minVal() {
+    return this.min === null ? undefined : this.min;
+  }
+  get maxVal() {
+    return this.max === null ? undefined : this.max;
+  }
+  get usage() {
+    let bits = ["@label='" + this.labelText + "'", '@value={{this.value}}'];
+    if (this.stepped) {
+      bits.push('@steps={{APERTURES}}');
+    }
+    if (this.unit) {
+      bits.push("@unit='" + this.unit + "'");
+    }
+    if (this.steppers) {
+      bits.push('@steppers={{true}}');
+    }
+    if (this.scrubFrom !== 'grip') {
+      bits.push("@scrubFrom='" + this.scrubFrom + "'");
+    }
+    bits.push('@onChange={{this.commit}}');
+    return '<ScrubInput ' + bits.join(' ') + ' />';
+  }
+  <template>
+    <FreestyleUsage
+      @name='ScrubInput'
+      @description='The numeric field a design tool lives on: drag the unit grip horizontally to change the value, or type into it. Shift coarsens ×10, Alt/⌘ refines ×0.1, and the same multipliers drive the arrow keys. PageUp/PageDown coarse-step, Home/End jump to min/max, Escape abandons a half-typed value. Ported from figui3 fig-input-number + fig-steppers. Turn on “stepped” to see the same control over a DISCRETE scale — the f-stop ladder, where the legal values are an ordered non-uniform list and the gesture travels whole stops.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-scrub-demo'>
+          <ScrubInput
+            @label={{this.labelText}}
+            @value={{this.value}}
+            @steps={{this.steps}}
+            @min={{this.minVal}}
+            @max={{this.maxVal}}
+            @step={{this.step}}
+            @pixelsPerStep={{this.pixelsPerStep}}
+            @precision={{this.precision}}
+            @unit={{this.unit}}
+            @unitPosition={{this.unitPositionVal}}
+            @scrubFrom={{this.scrubFromVal}}
+            @steppers={{this.steppers}}
+            @mixed={{this.mixed}}
+            @disabled={{this.disabled}}
+            @onInput={{this.setValue}}
+            @onChange={{this.commit}}
+          />
+          <p class='pretui-demo-readout' data-test-scrub-readout>
+            live = {{this.value}} · committed = {{this.committed}}
+          </p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='value'
+          @value={{this.value}}
+          @description='Controlled value. Omit and seed @defaultValue for uncontrolled use (kit contract: args.value ?? internal).'
+          @onInput={{this.setValue}}
+        />
+        <Args.Bool
+          @name='steps'
+          @defaultValue={{false}}
+          @value={{this.stepped}}
+          @description='A STEPPED SCALE — the ordered list of legal values, as numbers or {value,label} pairs. Numeric does not mean continuous: apertures, ISO speeds and type ramps have non-uniform gaps that @step cannot describe. With @steps the gesture addresses the scale by INDEX (a scrub, an arrow and a stepper each travel whole stops), @min/@max default to the ends of the list, a typed number snaps to the nearest legal value on commit, and the field shows the stop’s label while aria-valuenow keeps the number. The knob here swaps in the thirteen-stop aperture ladder.'
+          @onInput={{this.setStepped}}
+        />
+        <Args.Number
+          @name='min'
+          @value={{this.min}}
+          @description='Lower bound. Also the target of the Home key — without a min, Home is inert rather than wrong.'
+          @onInput={{this.setMin}}
+        />
+        <Args.Number
+          @name='max'
+          @value={{this.max}}
+          @description='Upper bound, and the End key target.'
+          @onInput={{this.setMax}}
+        />
+        <Args.Number
+          @name='step'
+          @defaultValue={{1}}
+          @value={{this.step}}
+          @description='One arrow press, one stepper click, and one pixelsPerStep of scrub each move the value this far.'
+          @onInput={{this.setStep}}
+        />
+        <Args.Number
+          @name='pixelsPerStep'
+          @defaultValue={{1}}
+          @value={{this.pixelsPerStep}}
+          @min={{1}}
+          @max={{20}}
+          @description='Pixels of pointer travel that buy one step. figui3 hardcodes 1; raise it for a control that needs a slower hand.'
+          @onInput={{this.setPixels}}
+        />
+        <Args.Number
+          @name='precision'
+          @defaultValue={{2}}
+          @value={{this.precision}}
+          @min={{0}}
+          @max={{6}}
+          @description='Decimal places kept on commit. Rounding runs through roundTo (×10ⁿ integer round), not toFixed, so a long drag cannot accumulate drift.'
+          @onInput={{this.setPrecision}}
+        />
+        <Args.String
+          @name='unit'
+          @value={{this.unit}}
+          @description="Unit rendered in the grip and folded into aria-valuetext: 'px', '%', '°', 'ms'."
+          @onInput={{this.setUnit}}
+        />
+        <Args.String
+          @name='unitPosition'
+          @defaultValue='suffix'
+          @value={{this.unitPosition}}
+          @options={{this.unitPositionOptions}}
+          @description='Which side the grip sits on.'
+          @onInput={{this.setUnitPosition}}
+        />
+        <Args.String
+          @name='scrubFrom'
+          @defaultValue='grip'
+          @value={{this.scrubFrom}}
+          @options={{this.scrubFromOptions}}
+          @description="'grip' scrubs from the unit affix only (discoverable, and leaves text selection alone); 'field' makes the whole control a scrub surface; 'none' is a plain spinbutton."
+          @onInput={{this.setScrubFrom}}
+        />
+        <Args.Bool
+          @name='steppers'
+          @defaultValue={{false}}
+          @value={{this.steppers}}
+          @description='The up/down pair — figui3 fig-steppers, folded in as an arg rather than shipped as a second component.'
+          @onInput={{this.setSteppers}}
+        />
+        <Args.Bool
+          @name='mixed'
+          @defaultValue={{false}}
+          @value={{this.mixed}}
+          @description='Multi-selection with differing values. Rendered as the WORD “Mixed” in the placeholder and in aria-valuetext — never colour alone.'
+          @onInput={{this.setMixed}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @description='readonly + aria-disabled rather than the disabled attribute, so the row stays keyboard-reachable and still announces its value.'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String
+          @name='label'
+          @value={{this.labelText}}
+          @description='Accessible name. A panel of twenty unnamed spinbuttons is unusable, so this is required in practice.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='grip'
+          @description='Grip text when there is no unit — the scrub affordance needs something to grab.'
+        />
+        <Args.String
+          @name='controlId'
+          @description='id placed on the inner input, so a PropertyRow label can point at it.'
+        />
+        <Args.String
+          @name='describedBy'
+          @description='id of a description element (PropertyRow yields one).'
+        />
+        <Args.Action
+          @name='onInput'
+          @description='Continuous — every scrub frame and every keystroke.'
+        />
+        <Args.Action
+          @name='onChange'
+          @description='Committed — blur, Enter, scrub release, stepper click. This is the one to persist.'
+        />
+        <Args.Yield @description='The grip block replaces the grip content with an axis glyph or icon.' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-scrub-demo {
+        max-width: 220px;
+      }
+      .pretui-demo-readout {
+        margin: 8px 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+        font-variant-numeric: tabular-nums;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SCRUB_INPUT: Record<string, unknown> = {
+  ScrubInput: ScrubInputUsage,
+};

package/bundled-realms/pretui/components/search-input.gts

@@ -0,0 +1,141 @@
+// Pretui — SearchInput: a search field with a clear button.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { htmlSafe } from '@ember/template';
+import { BoxelInput } from '@cardstack/boxel-ui/components';
+import { emit, firstDefined } from '../pretui-primitives';
+import type { ControlAliasArgs } from '../pretui-primitives';
+
+// BoxelInput @type='search' — boxel's search dress (leading magnifier
+// icon) re-pointed at the Pretui field tokens via its --boxel-input-
+// search-* knobs — plus the clear button boxel-ui doesn't ship: an overlay
+// ✕ appears once the field holds text and resets it through @onInput('').
+// Wave-0 adaptation (documented): no debounce knob — realm code takes no
+// timers; debounce belongs to the consumer's data layer.
+
+const SEARCH_METRICS = htmlSafe(
+  'font: inherit; letter-spacing: inherit; line-height: 18px; padding-block: 4px; border-radius: var(--radius); padding-right: 28px;',
+);
+
+export interface SearchInputSignature {
+  Args: ControlAliasArgs & {
+    value?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    controlId?: string;
+    /** show the clear button once the field holds text — true by default */
+    clearable?: boolean;
+    onInput?: (value: string) => void;
+  };
+  Element: HTMLDivElement;
+}
+
+export class SearchInput extends Component<SearchInputSignature> {
+  @tracked internal = this.args.value ?? '';
+
+  get current() {
+    return this.args.value ?? this.internal;
+  }
+  get showClear() {
+    return (
+      (this.args.clearable ?? true) && this.current !== '' && !this.disabled
+    );
+  }
+  get disabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled);
+  }
+  private notify(value: string) {
+    emit(
+      [this.args.onInput, this.args.onChange, this.args.onValueChange],
+      value,
+    );
+  }
+  handleInput = (value: string) => {
+    this.internal = value;
+    this.notify(value);
+  };
+  clear = (_e: Event) => {
+    this.internal = '';
+    this.notify('');
+  };
+  <template>
+    <div
+      class='pretui-boxelwrap'
+      data-filled={{if this.showClear 'true'}}
+      data-test-pretui-search-input
+      ...attributes
+    >
+      <BoxelInput
+        @type='search'
+        @value={{this.current}}
+        @placeholder={{@placeholder}}
+        @disabled={{this.disabled}}
+        @onInput={{this.handleInput}}
+        id={{@controlId}}
+        style={{SEARCH_METRICS}}
+      />
+      {{#if this.showClear}}
+        <button
+          type='button'
+          class='pretui-searchclear'
+          aria-label='Clear search'
+          {{on 'click' this.clear}}
+        >
+          <svg width='12' height='12' viewBox='0 0 12 12' aria-hidden='true'><path
+              d='M3 3l6 6M9 3l-6 6'
+              fill='none'
+              stroke='currentColor'
+              stroke-width='1.5'
+              stroke-linecap='round'
+            /></svg>
+        </button>
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        /* EmailInput channel + boxel's search-specific knobs: the dark host
+           pill re-dresses as the Pretui field face, magnifier in quiet ink. */
+        .pretui-boxelwrap {
+          position: relative;
+          width: 100%;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          --background: var(--field, var(--boxel-light));
+          --border: var(--input);
+          --ring: var(--primary);
+          --muted-foreground: var(--ink-3, var(--boxel-400));
+          --boxel-input-search-background-color: var(--field, var(--boxel-light));
+          --boxel-input-search-color: var(--foreground);
+          --boxel-input-search-icon-color: var(--ink-3, var(--boxel-400));
+          --boxel-icon-sm: 14px;
+          --boxel-sp-xxl: 30px;
+          --boxel-form-control-height: var(--control-h, 28px);
+          --boxel-input-height: var(--control-h, 28px);
+          --boxel-form-control-border-radius: var(--radius);
+          --boxel-sp-xs: 5px;
+          --boxel-sp-sm: 9px;
+        }
+        .pretui-searchclear {
+          position: absolute;
+          top: calc((var(--control-h, 28px) - 20px) / 2);
+          right: 5px;
+          display: grid;
+          place-items: center;
+          width: 20px;
+          height: 20px;
+          border: 0;
+          padding: 0;
+          border-radius: 6px;
+          background: none;
+          color: var(--muted-foreground);
+          cursor: pointer;
+        }
+        .pretui-searchclear:hover {
+          background: var(--hover, var(--boxel-100));
+          color: var(--foreground);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/search-input.md

@@ -0,0 +1,56 @@
+## What it is
+
+A text field for filtering or querying, with a clear button that appears once it holds text. Use it above a **DataGrid**, a **FilterList**, or any list a user narrows by typing. If the field selects a _value_ from a list rather than filtering one, use **Combobox** or **Lookup**. If it filters by category rather than by text, **FilterChips**.
+
+## The contract
+
+```
+@value?, @placeholder?, @disabled?, @controlId?
+@clearable? (default true)
+@onInput?(value: string)
+```
+
+**The clear button appears only when there is text and the field is enabled** (`showClear` is `clearable && current !== '' && !disabled`), so an empty search field has no dead affordance.
+
+**The internal value tracks even when controlled.** `@tracked internal = @value ?? ''`, and `handleInput` writes `internal` _and_ calls `@onInput` unconditionally — unlike the rest of the kit, which only writes internal state when the component is uncontrolled. That means a controlled SearchInput briefly holds two copies of the value. In practice it works because the field re-renders from `@value`, but it is a deviation from the kit-wide hybrid idiom and worth knowing if you see a stale clear button.
+
+`clear` sets the internal value to `''` **and** calls `@onInput('')`, so a controlled parent is told about the clear rather than having to notice it.
+
+There is no debounce. `@onInput` fires per keystroke, and throttling is the caller's job — which is right for a component that cannot know whether the filter is a synchronous array filter or a network round trip.
+
+## Prior art
+
+**React Aria `useSearchField`** is the reference: `type` defaults to `'search'`, **Escape clears the field and fires `onClear`**, and the clear button gets a localized `aria-label` of "Clear search" and is explicitly not a submit button. **Web Awesome** has no search field — `wa-input type="search"` with `with-clear`. **shadcn** has none.
+
+Where Pretui matches the field: the conditional clear button, and `@onInput` receiving the string.
+
+Where it is behind React Aria, and the first one is the notable gap:
+
+- **No Escape-to-clear.** This is the search field's one keyboard convention, it costs a `keydown` handler, and every serious implementation has it. Its absence means a keyboard user must Tab to the clear button or select-all-delete.
+- **No `onClear` distinct from `onInput('')`.** A caller cannot tell "the user cleared" from "the user deleted the last character", which matters if clearing should also reset filters or close a results panel.
+- **No search icon.** Every reference implementation has a leading magnifier; here the field is visually indistinguishable from a plain **Input** until you type. That is the clearest visual gap.
+- **No result-count announcement hook** (see below).
+
+## Accessibility
+
+No APG pattern. The convention is `<input type="search">` inside a `role="search"` landmark (or a `<form role="search">`), with a labelled clear button and a live region for result counts.
+
+Gaps, in order:
+
+- **Result counts are not announced, and nothing here provides a hook.** This is the most important accessibility fact about any search field: a sighted user sees the list shrink, a screen-reader user gets silence. The fix is a `role="status"` region containing "24 results" — and **it must exist in the DOM before the count changes**, which is the usual live-region requirement. That region belongs to the caller, and this component neither provides nor prompts for one.
+- **No Escape-to-clear** (above) is an accessibility gap as much as a usability one — it is the expected keyboard affordance.
+- **The clear button's accessible name and tab position need checking.** It must be labelled ("Clear search"), must be `type="button"` so it never submits an enclosing form, and — arguably — should be reachable, unlike a password reveal toggle, since clearing is a real action.
+- **Clearing announces nothing.** After pressing clear, focus should generally return to the field, and the empty state should be discoverable. Verify where focus lands.
+- **No `role="search"` landmark.** The component does not wrap itself in one and there is no arg for it, so a page's search is not findable by landmark navigation unless the caller adds it.
+- **No accessible name of its own.** Outside **Field**/**FormField** and without an explicit `aria-label`, the field is unnamed — and search fields are the most likely control in any kit to be shipped with only a placeholder, which is not a label.
+- **`@disabled` uses the native attribute**, removing the field from the tab order — and also hides the clear button, which is correct.
+
+## Theming
+
+Consumed: `--field`, `--input`, `--primary` (focus ring via `--ring`), `--ink-3` (placeholder), `--control-h`, `--radius`, `--text-ui-md`, `--text-ui-sm`, `--text-ui-xs`, `--track-ui`, plus **IconButton**'s tokens for the clear affordance.
+
+Forwarded into boxel-ui through the `--boxel-*` channel, matching **Input**'s metrics exactly.
+
+`data-filled` is reflected on the wrapper when the clear button is showing, so a stylesheet can dress the filled state — a stronger hairline, a changed placeholder treatment — which is the only hook available for signaling "this search is active" without adding markup. Worth using, since the clear button alone is a small signal at 28px.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/search-input.usage.gts

@@ -0,0 +1,91 @@
+// Pretui — SearchInput usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { SearchInput } from './search-input';
+
+// ── SearchInput — typed-input split, fresh page ──────────────────────────
+// Type-specific knob: clearable (the ✕ button). Wave-0 adaptation on
+// record: no debounce knob — realm code takes no timers; debounce belongs
+// to the consumer's data layer.
+class SearchInputUsage extends Component {
+  @tracked value = '';
+  @tracked placeholder = 'Search components…';
+  @tracked clearable = true;
+  @tracked disabled = false;
+  setValue = (v: string) => (this.value = v);
+  setPlaceholder = (v: string) => (this.placeholder = v);
+  setClearable = (v: boolean) => (this.clearable = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  get usage() {
+    let bits = [`@value='${this.value}'`];
+    if (this.placeholder) bits.push(`@placeholder='${this.placeholder}'`);
+    if (!this.clearable) bits.push('@clearable={{false}}');
+    bits.push('@onInput={{this.setValue}}');
+    return `<SearchInput ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='SearchInput'
+      @description="Search field riding boxel-ui BoxelInput (@type=search) — the leading magnifier re-dressed in Pretui field tokens — plus the clear button boxel-ui doesn't ship: a ✕ appears once the field holds text and resets it through @onInput('')."
+      @source={{this.usage}}
+    >
+      <:example>
+        <SearchInput
+          @value={{this.value}}
+          @placeholder={{this.placeholder}}
+          @clearable={{this.clearable}}
+          @disabled={{this.disabled}}
+          @onInput={{this.setValue}}
+        />
+        <p class='pretui-demo-readout' data-test-search-readout>
+          value = “{{this.value}}”
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.Bool
+          @name='clearable'
+          @defaultValue={{true}}
+          @value={{this.clearable}}
+          @description='Show the ✕ clear button while the field holds text.'
+          @onInput={{this.setClearable}}
+        />
+        <Args.String
+          @name='value'
+          @value={{this.value}}
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='placeholder'
+          @value={{this.placeholder}}
+          @onInput={{this.setPlaceholder}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String
+          @name='controlId'
+          @description="The input's id for label wiring — supplied by a wrapping Field's yielded controlId."
+        />
+        <Args.Action
+          @name='onInput'
+          @description="Receives the changed value as a string; the clear button sends ''."
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-demo-readout {
+        margin: 8px 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SEARCH_INPUT: Record<string, unknown> = {
+  SearchInput: SearchInputUsage,
+};