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

package/bundled-realms/pretui/components/lookup.md

@@ -0,0 +1,59 @@
+## What it is
+
+A record search field: type, results arrive from wherever you fetch them, pick one or several, selected records show as removable **RecordPill**s. Use it for any relationship — an account, an owner, a linked card. If the options are a short static list, **Select** or **MultiSelect**. If the user may type a value that is not a record, **Combobox**. If the whole set is small enough to show at once and order matters, **DuelingPicklist**.
+
+## The contract
+
+```
+@records: PickerRecord[]   — already filtered/sorted by YOU
+@selected? / @defaultSelected?, @multiple?, @loading?, @disabled?, @invalid?
+@label?, @placeholder?, @recordNoun?
+@onSearch?(query), @onSelectionChange?(records), @onOpenChange?(open)
+<:option as |record, { selected, term }|>
+```
+
+**`@onSearch` fires on every keystroke and you debounce and fetch, not the component.** That is the load-bearing decision: a realm component owns no timers, so a built-in debounce is impossible — and the honest consequence is that the async boundary is explicit rather than hidden. `@records` is whatever you last returned.
+
+**`PickerRecord` is a plain value, not a `CardDef` or `FieldDef` instance** — `{ id, label, meta?, icon?, search?, locked? }`. The source records the reason: a picker must be usable before a schema exists. Salesforce shapes map straight on (`id` ← the 18-char record id, `label` ← Name, `meta` ← the "Account • San Francisco" second line).
+
+**`search` is the field that stops a real bug.** The dropdown runs a _local_ filter over `label meta id`; when the server matched on something the visible text does not contain — a synonym, an account number, a fuzzy hit — that local pass would hide the row the server just returned. Setting `search` on the record keeps it.
+
+**Single-select is an array of length 0 or 1.** One shape for both modes.
+
+## Prior art
+
+**SLDS's lookup** is the direct ancestor — the entity option row, the pill for the selection, the "Account • location" meta line. **React Spectrum** has no lookup; `ComboBox` with async `items` is the nearest. **Web Awesome** has none. **Radix** has none; shadcn's recipe is Command inside a Popover.
+
+The combobox behaviour is **ember-power-select's**, and the source is explicit about why: roles, `aria-autocomplete="list"`, `aria-activedescendant` tracking, `role="listbox"`/`option`, DOM focus staying in the input, arrow navigation and scroll-into-view are all supplied whole rather than reimplemented.
+
+Where Pretui adds real value over both:
+
+- **A `role="status" aria-live="polite"` region announcing selections, removals and "Searching…".** That is the thing async record pickers universally omit, and it is what makes this component genuinely usable without sight. `@recordNoun` exists to make the announcements read naturally.
+- **`@loading` spins the trigger affix _and_ announces**, so the async state is not color-and-motion only.
+- **`RecordFace` is exported as its own primitive**, so a listbox option, a selection pill and a dueling-list row render records identically.
+
+One documented gap the source itself flags: **EntityDisplay was the natural composition and could not be used**, because its `@title` is a string with no title block, so the matched search term could not carry a `<mark>`. That is a real API limitation in EntityDisplay worth fixing.
+
+## Accessibility
+
+Governing pattern: APG **Combobox with listbox popup**. This is the best-served component in the kit on announcements.
+
+Present: `role="combobox"` with `aria-expanded`, `aria-controls`, `aria-autocomplete="list"` and `aria-activedescendant`; `role="listbox"` with `role="option"` rows; DOM focus staying in the input; `aria-invalid` from `@invalid`; individually-named remove buttons on the pills; and the polite live region.
+
+**The live region is designed rather than sprinkled**, which is worth reading as a model: it announces only what power-select does not already speak, so results are not double-spoken, and it is in the DOM from first render rather than being mounted with its content — which is the failure mode **Alert**, **Toast**, **Spinner** and **LoadingState** all have in this kit.
+
+Gaps:
+
+- **`@label` is optional** and is the combobox's accessible name. Without it the field is unnamed; there is no `@controlId`, so **Field**/**FormField** cannot wire a `<label for>` either.
+- **The result count is announced but the results themselves are not enumerated** — a user must arrow through to discover them, which is correct behaviour but means an empty result set needs its own clear announcement. That announcement comes from power-select's own `role="status"` region, which also says "No results found" for an empty set.
+- **`@invalid` sets `aria-invalid` but carries no message.** Issues render in the field wrapper, so a bare Lookup outside a **FormField** shows an error dress that announces nothing.
+- **The pills are inside the control**, so a selection of eight records adds eight tab stops before anything after the field.
+- **Debouncing is yours, and so is the announcement cadence.** A caller who fires `@onSearch` per keystroke with no debounce will produce a live region that re-announces a changing count continuously.
+
+## Theming
+
+Trigger and input: `--field`, `--input`, `--primary` (via `--ring`), `--ink-3`, `--control-h`, `--radius`, `--text-ui-md`. Dropdown: `--popover`, `--hover`, `--pretui-shadow-overlay`. Rows: **RecordFace**'s tokens plus the `<mark>` highlight dress. Pills: **RecordPill**'s. Invalid: `--destructive` through the **Field** token channel.
+
+The `<mark>` on the matched term is the one thing to check per theme: it must be legible against both the resting and highlighted row backgrounds, and since **RecordFace** tints it with `--primary` at 22%, a theme with a pale `--primary` produces a highlight that is barely visible.
+
+The rules for the lookup's own elements sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector. The `:deep()` rules that restyle BoxelMultiSelect's power-select markup stay unlayered, because its own rules are unlayered and would beat them from inside a layer.

package/bundled-realms/pretui/components/lookup.usage.gts

@@ -0,0 +1,235 @@
+// Pretui — Lookup usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import {
+  PEOPLE,
+  SUPPLIERS,
+  pick,
+  seedFrom,
+} from '../examples';
+import { Lookup } from './lookup';
+import type { PickerRecord } from '../internal/forms-picker';
+import { ACCOUNTS } from '../internal/forms-picker-fixtures';
+
+// ── Lookup ← slds lookups/ + combobox/ ───────────────────────────────────
+const CONTACTS: PickerRecord[] = PEOPLE.slice(0, 10).map((name, i) => ({
+  id: `003R0000${String(i + 21).padStart(2, '0')}`,
+  label: name,
+  meta: `Contact • ${pick(seedFrom(name), i, SUPPLIERS)}`,
+  icon: 'user',
+}));
+
+// Dropped SLDS surface (also named in the component's own header): the
+// `selectOnly` faux-input single-select, the object-switcher addon and
+// advanced-search modal, the `+6 more` selection-group toggle, and every
+// `isOpen`/`hasFocus`/`hasInteractions` prop that existed only to freeze the
+// React examples into static snapshots.
+class LookupUsage extends Component {
+  @tracked objectType = 'Accounts';
+  @tracked query = '';
+  @tracked selected: PickerRecord[] = [ACCOUNTS[0] as PickerRecord];
+  @tracked multiple = false;
+  @tracked loading = false;
+  @tracked disabled = false;
+  @tracked placeholder = 'Search accounts…';
+
+  objectTypes = ['Accounts', 'Contacts'];
+
+  get pool(): PickerRecord[] {
+    return this.objectType === 'Contacts' ? CONTACTS : ACCOUNTS;
+  }
+  /**
+   * The CALLER owns search. In a real card this is a `searchCards` query
+   * behind a debounce; here it is a synchronous filter over the bank so the
+   * workbench needs no network and no timers.
+   */
+  get results(): PickerRecord[] {
+    let term = this.query.trim().toLowerCase();
+    let base = this.pool;
+    let hits = term
+      ? base.filter(
+          (r) =>
+            r.label.toLowerCase().includes(term) ||
+            (r.meta ?? '').toLowerCase().includes(term),
+        )
+      : base;
+    return hits.slice(0, 6);
+  }
+  get selectedIds(): string[] {
+    return this.selected.map((r) => r.id);
+  }
+  get recordNoun() {
+    return this.objectType === 'Contacts' ? 'contact' : 'account';
+  }
+  get label() {
+    return this.objectType === 'Contacts' ? 'Search Contacts' : 'Search Accounts';
+  }
+
+  setObjectType = (v: string) => {
+    this.objectType = v;
+    this.selected = [];
+    this.query = '';
+    this.placeholder = `Search ${v.toLowerCase()}…`;
+  };
+  setQuery = (v: string) => (this.query = v);
+  setSelected = (records: PickerRecord[]) => (this.selected = records);
+  setMultiple = (v: boolean) => {
+    this.multiple = v;
+    if (!v) {
+      this.selected = this.selected.slice(0, 1);
+    }
+  };
+  setLoading = (v: boolean) => (this.loading = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setPlaceholder = (v: string) => (this.placeholder = v);
+  setSelectedIds = (ids: string[]) => {
+    this.selected = ids
+      .map((id) => this.pool.find((r) => r.id === id))
+      .filter((r): r is PickerRecord => Boolean(r));
+  };
+
+  get usage() {
+    let bits = [
+      '@records={{this.results}}',
+      '@selected={{this.selected}}',
+      `@label='${this.label}'`,
+      `@recordNoun='${this.recordNoun}'`,
+    ];
+    if (this.multiple) {
+      bits.push('@multiple={{true}}');
+    }
+    if (this.loading) {
+      bits.push('@loading={{true}}');
+    }
+    if (this.disabled) {
+      bits.push('@disabled={{true}}');
+    }
+    if (this.placeholder) {
+      bits.push(`@placeholder='${this.placeholder}'`);
+    }
+    bits.push('@onSearch={{this.search}}');
+    bits.push('@onSelectionChange={{this.setSelected}}');
+    return `<Lookup ${bits.join('\n  ')}\n/>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Lookup'
+      @description='The record-reference control — a Salesforce lookup field. Type to search, review a results listbox with per-record chrome (icon, primary label, secondary meta line, matched-term highlight), and commit the pick as a removable pill. Reach for it whenever a value points at another record rather than being typed: Account on an Opportunity, Reports To on a Contact, Supplier on a purchase order. The dropdown ENGINE is ember-power-select, reached through boxel-ui BoxelMultiSelect and rendered in place so Pretui tokens reach it — so outside-click dismissal, Escape, focus return, arrow/Enter keyboard, the aria-activedescendant wiring and the result-count live region are all the engine’s, not ours. It owns NO fetching: you supply @records and @loading and debounce inside @onSearch (realm law forbids timers in components). Honest limits: the search text belongs to the engine, so there is no @query arg to control it; filtering is LOCAL over the records you supply, matched against record.search (label + meta + id by default) — put anything a fuzzy server match found into record.search or it will be filtered back out; the listbox reports aria-multiselectable even in single-select; and issue rendering belongs to the surrounding form field, not here.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Lookup
+          @records={{this.results}}
+          @selected={{this.selected}}
+          @multiple={{this.multiple}}
+          @loading={{this.loading}}
+          @disabled={{this.disabled}}
+          @label={{this.label}}
+          @recordNoun={{this.recordNoun}}
+          @placeholder={{this.placeholder}}
+          @onSearch={{this.setQuery}}
+          @onSelectionChange={{this.setSelected}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='objectType'
+          @value={{this.objectType}}
+          @options={{this.objectTypes}}
+          @description='DEMO KNOB, not a Lookup arg — swaps the record bank between Accounts and Contacts so you can see the icon/meta channel change.'
+          @onInput={{this.setObjectType}}
+        />
+        <Args.Object
+          @name='records'
+          @required={{true}}
+          @description='Result records to render, already filtered and sorted by the caller: {id, label, meta?, icon?}. Plain values, never card instances.'
+          @value={{this.results}}
+        />
+        <Args.Array
+          @name='selected'
+          @description='Controlled selection, as records (not ids) so a pill can render after the results list has moved on. Single-select is simply an array of 0 or 1. Edit as comma-separated ids.'
+          @value={{this.selectedIds}}
+          @onInput={{this.setSelectedIds}}
+        />
+        <Args.String
+          @name='(search text)'
+          @value={{this.query}}
+          @description='READ-ONLY, and not an arg. ember-power-select owns the search text; there is no supported way to push a value back in, so @query / @defaultQuery were removed in the engine swap. This row mirrors what @onSearch last reported. Type in the example to watch it move.'
+          @onInput={{this.setQuery}}
+        />
+        <Args.Bool
+          @name='multiple'
+          @defaultValue={{false}}
+          @description='Allow more than one record. Single-select replaces on each pick instead of forcing a clear first.'
+          @value={{this.multiple}}
+          @onInput={{this.setMultiple}}
+        />
+        <Args.Bool
+          @name='loading'
+          @defaultValue={{false}}
+          @description='Async search in flight — spins the trigger affix and announces “Searching…”. Keep the previous @records in place while it is true; the engine shows its own “No results found” row for an empty list and cannot be told to wait.'
+          @value={{this.loading}}
+          @onInput={{this.setLoading}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @description='Blocks every interaction.'
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String
+          @name='placeholder'
+          @value={{this.placeholder}}
+          @description='Input placeholder.'
+          @defaultValue='Search…'
+          @onInput={{this.setPlaceholder}}
+        />
+        <Args.Base
+          @name='defaultSelected'
+          @type='PickerRecord[]'
+          @description='Uncontrolled initial selection. Ignored once @selected is supplied.'
+        />
+        <Args.Bool
+          @name='invalid'
+          @defaultValue={{false}}
+          @description='Error dress plus aria-invalid. The message itself belongs to the surrounding form field — this control never validates.'
+        />
+        <Args.Base
+          @name='label'
+          @type='String'
+          @defaultValue='Search {recordNoun}s'
+          @description='Accessible name for the combobox input — passed to the engine as @ariaLabel. This is the only naming channel: BoxelMultiSelect does not forward aria-labelledby or aria-describedby, so @labelledBy / @describedBy were removed in the engine swap.'
+        />
+        <Args.Base
+          @name='recordNoun'
+          @type='String'
+          @defaultValue='record'
+          @description="Noun used in the listbox name and every announcement — 'account', 'contact', 'lot'."
+        />
+        <Args.Action
+          @name='onSearch'
+          @description='Fires on every keystroke with the current query. Debounce and fetch HERE — the component owns no timers and no fetching.'
+        />
+        <Args.Action
+          @name='onSelectionChange'
+          @description='Fires with the FULL selection (PickerRecord[]) after every pick or remove.'
+        />
+        <Args.Action
+          @name='onOpenChange'
+          @description='Fires with true/false when the results panel opens or closes.'
+        />
+        <Args.Yield
+          @name=':option'
+          @description='Replaces the default result row. Yields (record, {selected, term}) — the default row is a RecordFace with the matched term marked. :empty and :footer were removed in the engine swap: power-select owns the no-results row, and @afterOptionsComponent takes a component, not a block.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_LOOKUP: Record<string, unknown> = {
+  Lookup: LookupUsage,
+};

package/bundled-realms/pretui/components/magnetic.gts

@@ -0,0 +1,158 @@
+// Pretui — Magnetic: content that leans toward the pointer as it approaches.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+// Caller-supplied hues are strings and must clear the kit-wide allowlist
+// before they reach an inline style — see pretui-css.gts.
+import { cssDeclaration, cssNumber } from '../pretui-css';
+import { pointerField } from '../internal/motion-pointer';
+
+// ── Magnetic ─────────────────────────────────────────────────────────────
+// TRANSCRIBED from motion-primitives magnetic.tsx and react-bits
+// Magnet/MagnetLines.
+//
+// Upstream engine: a document-level mousemove handler measures the
+// element every event, computes distance, scales by (1 - d/range), and
+// pushes the result through useSpring (stiffness 26.7 / damping 4.1 /
+// mass 0.2 — deliberately underdamped, so the element wobbles). Range is
+// an invisible number: nothing on screen tells the reader where the pull
+// starts, and a still frame of the component is just… the button.
+//
+// This version: the range is REAL LAYOUT. The wrapper reserves it as
+// padding, so the reach zone is a box the pointer actually enters — which
+// means one pointermove listener on the wrapper replaces the global one,
+// and the zone can be DRAWN. That drawn halo is the resting state and the
+// encoding both: it is a picture of the control's true (enlarged) hit
+// area, and it brightens with --pretui-pd as the pointer closes in, so
+// affinity is legible before anything moves. Lean is
+// --pretui-dx/dy × @intensity on a `translate` transition. Differences
+// from the spring: critically damped — it eases home and stops, no
+// wobble, no stiffness/damping/mass surface. Dropped from upstream:
+// `actionArea: 'self' | 'parent' | 'global'` (the padded zone IS the
+// action area; a global magnet that reacts from across the page is the
+// behavior that most reliably reads as a bug) and `springOptions`.
+//
+// Touch: coarse pointers get the halo but no lean — pulling an element
+// out from under a fingertip is only ever a miss. Keyboard: focusing the
+// wrapped control lights the halo to full via focusin, so the reach
+// affordance appears on the keyboard path too (upstream: nothing).
+export interface MagneticSignature {
+  Args: {
+    /** reach in px, reserved as real padding around the control — this is
+     * the extra hit area the halo draws. Default 56 */
+    range?: number;
+    /** how far the control leans toward the pointer, as a fraction of the
+     * falloff-scaled offset, 0–1 — default 0.35 */
+    intensity?: number;
+    /** draw the reach zone (the resting state) — default true. Turning it
+     * off makes the component invisible in a still frame; do it only when
+     * a neighbouring affordance already shows the target */
+    halo?: boolean;
+    /** any CSS color for the halo — defaults to the --primary token */
+    hue?: string;
+  };
+  Blocks: {
+    /** the control being magnetized — keeps all of its own events */
+    default: [];
+  };
+  Element: HTMLDivElement;
+}
+
+export class Magnetic extends Component<MagneticSignature> {
+  get showHalo(): boolean {
+    return this.args.halo ?? true;
+  }
+  get rootStyle(): ReturnType<typeof htmlSafe> {
+    let bits: string[] = [];
+    {
+      let n = cssNumber(this.args.range, 0, 10000);
+      if (n !== undefined) {
+        bits.push(`--pretui-magnetic-range: ${n}px`);
+      }
+    }
+    {
+      let n = cssNumber(this.args.intensity, -100, 100);
+      if (n !== undefined) {
+        bits.push(`--pretui-magnetic-intensity: ${n}`);
+      }
+    }
+    let hue = cssDeclaration('--pretui-magnetic-hue', this.args.hue);
+    if (hue) bits.push(hue);
+    return htmlSafe(bits.join('; '));
+  }
+  <template>
+    <div
+      class='pretui-magnetic'
+      style={{this.rootStyle}}
+      data-test-pretui-magnetic
+      {{pointerField 0 true 0.5 0.5}}
+      ...attributes
+    >
+      {{#if this.showHalo}}
+        <span class='pretui-magnetic-halo' aria-hidden='true'></span>
+      {{/if}}
+      <span class='pretui-magnetic-lean'>{{yield}}</span>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-magnetic {
+          position: relative;
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          padding: var(--pretui-magnetic-range, 56px);
+        }
+        .pretui-magnetic-halo {
+          position: absolute;
+          inset: 0;
+          pointer-events: none;
+          border-radius: var(--pretui-magnetic-halo-radius, 999px);
+          background: radial-gradient(
+            circle at center,
+            color-mix(
+                in oklch,
+                var(--pretui-magnetic-hue, var(--primary)) 16%,
+                transparent
+              )
+              0%,
+            color-mix(
+                in oklch,
+                var(--pretui-magnetic-hue, var(--primary)) 5%,
+                transparent
+              )
+              48%,
+            transparent 72%
+          );
+          box-shadow: 0 0 0 1px
+            color-mix(in oklch, var(--border) 70%, transparent);
+          opacity: calc(0.34 + 0.66 * var(--pretui-pd, 0));
+          transition: opacity 180ms ease-out;
+        }
+        .pretui-magnetic-lean {
+          display: inline-flex;
+          translate: calc(
+              var(--pretui-dx, 0px) * var(--pretui-magnetic-intensity, 0.35)
+            )
+            calc(var(--pretui-dy, 0px) * var(--pretui-magnetic-intensity, 0.35));
+          transition: translate 260ms cubic-bezier(0.22, 1, 0.36, 1);
+          will-change: translate;
+        }
+        /* a finger is already ON the target — never pull the control out
+           from under it; the halo still reports the reach */
+        .pretui-magnetic[data-pretui-pointer='coarse'] .pretui-magnetic-lean {
+          translate: 0 0;
+        }
+        /* end state under reduced motion: control centred, halo still
+           reporting affinity — the information survives, the travel does not */
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-magnetic-lean {
+            translate: 0 0;
+            transition: none;
+          }
+          .pretui-magnetic-halo {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/magnetic.md

@@ -0,0 +1,48 @@
+## What it is
+
+A control that leans toward an approaching pointer, wrapped in a halo that *shows* where the pull starts.
+
+The halo is the point. Upstream magnetics attach a document-level pointer listener and spring the element within an invisible pixel range — nothing on screen says where the attraction begins, and a still frame is just a button. Here the range is real layout: the wrapper reserves it as padding, so one local listener replaces the global one **and** the reach zone can be drawn.
+
+## The contract
+
+```
+@range?     — reach in px, reserved as real padding around the control. Default 56
+@intensity? — how far the control leans, as a fraction of the falloff-scaled offset, 0–1. Default 0.35
+@halo?      — draw the reach zone. Default true
+@hue?       — any CSS colour for the halo; defaults to --primary
+
+<:default> — the control being magnetized; keeps all of its own events
+```
+
+**`@range` is layout, not a threshold.** It becomes padding on the wrapper, which is what makes a local `pointermove` sufficient — the pointer is genuinely inside the element before anything happens, so no document listener is needed.
+
+**The halo is the resting state.** It is a picture of the control's true, enlarged hit area, and it brightens with proximity, so affinity is legible before anything moves. Turning it off makes the component invisible in a still frame — do that only when a neighbouring affordance already shows the target.
+
+**Touch gets the halo but no lean.** Pulling a control out from under a fingertip is hostile.
+
+**The wrapped control keeps all of its own events.** This wraps rather than replaces — the button inside is still the button.
+
+## Prior art
+
+**motion-primitives' Magnetic** and **react-bits' Magnet/MagnetLines**.
+
+Where Pretui is better: **the reach is visible and the listener is local.** Both upstreams need a document-level `mousemove` precisely because their range is imaginary; making it real padding removes that need and makes the behaviour explicable. The lean is also falloff-scaled rather than linear, so the pull grows as you approach instead of snapping on at the boundary.
+
+Where it is thinner: no spring physics — the return is an eased transition rather than momentum — no axis constraint, and no `MagnetLines` field-grid variant, which is RAF-bound upstream and out of reach here.
+
+## Accessibility
+
+- **The halo is `aria-hidden`.** It is decoration over a control that carries its own semantics.
+- **This component adds no interaction, so it adds no keyboard surface.** The wrapped control is reached and operated exactly as it would be unwrapped — which also means the lean is invisible to anyone navigating by keyboard.
+- **The reserved range is real hit area**, which is a genuine motor-accessibility gain: the target is larger than it looks, in the direction the pointer is coming from. That is the one part of this component that helps rather than decorates.
+- **Reduced motion should stop the lean**; the halo, being the resting state, is what remains.
+- **Nothing is conveyed by the lean alone.** It is affinity, not state.
+
+## Theming
+
+`--pretui-magnetic-range` (from `@range`), `--pretui-magnetic-intensity` (from `@intensity`), `--pretui-magnetic-hue` (from `@hue`, defaulting to `--primary`), `--pretui-magnetic-halo-radius`, plus the shared pointer channel `--pretui-px` / `--pretui-py` / `--pretui-nx` / `--pretui-ny` / `--pretui-dx` / `--pretui-dy` that every component in this module writes.
+
+That shared channel is why the pointer components compose: a **Spotlight** and a **Magnetic** in the same surface read the same pointer position from the same custom properties rather than each installing its own listener.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/magnetic.usage.gts

@@ -0,0 +1,125 @@
+// Pretui — Magnetic usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Magnetic } from './magnetic';
+import {
+  SUPPLIERS,
+  pick,
+  seedFrom,
+} from '../examples';
+
+// ── Magnetic ─────────────────────────────────────────────────────────────
+class MagneticUsage extends Component {
+  @tracked range = 56;
+  @tracked intensity = 0.35;
+  @tracked halo = true;
+  @tracked hue = '';
+  setRange = (v: number | null) => (this.range = v ?? 56);
+  setIntensity = (v: number | null) => (this.intensity = v ?? 0.35);
+  setHalo = (v: boolean) => (this.halo = v);
+  setHue = (v: string) => (this.hue = v);
+  get supplier() {
+    return pick(seedFrom('magnetic'), 0, SUPPLIERS);
+  }
+  get usage() {
+    let bits = [
+      `@range={{${this.range}}}`,
+      `@intensity={{${this.intensity}}}`,
+    ];
+    if (!this.halo) bits.push('@halo={{false}}');
+    if (this.hue) bits.push(`@hue='${this.hue}'`);
+    return `<Magnetic ${bits.join(' ')}>\n  <Button>Confirm booking</Button>\n</Magnetic>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Magnetic'
+      @description='A control that leans toward an approaching pointer. Upstream (motion-primitives Magnetic, react-bits Magnet) attaches a document-level mousemove and springs the element by an invisible px range — nothing on screen says where the pull starts, and a still frame is just the button. Here the range is real layout: the wrapper reserves it as padding, so one local listener replaces the global one AND the reach zone can be drawn. That halo is both the resting state and the Law 5 encoding — it is a picture of the control’s true enlarged hit area, and it brightens with proximity, so affinity is legible before anything moves. Touch gets the halo but no lean (pulling a control out from under a fingertip is only ever a miss); focusing the control lights the halo to full. Dropped from upstream: actionArea (self/parent/global) and springOptions — the padded zone IS the action area, and a CSS transition is critically damped, so there is no wobble to tune. Honest limit: the range occupies real layout space, so a magnetic control needs room around it.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='mag-stage'>
+          <Magnetic
+            @range={{this.range}}
+            @intensity={{this.intensity}}
+            @halo={{this.halo}}
+            @hue={{this.hue}}
+          >
+            <Button @size='m'>Confirm booking</Button>
+          </Magnetic>
+          <p class='mag-note'>{{this.supplier}}
+            · spring allocation closes Friday</p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='range'
+          @defaultValue={{56}}
+          @value={{this.range}}
+          @min={{0}}
+          @max={{140}}
+          @step={{4}}
+          @description='Reach in px, reserved as real padding around the control. This is the extra hit area the halo draws.'
+          @onInput={{this.setRange}}
+        />
+        <Args.Number
+          @name='intensity'
+          @defaultValue={{0.35}}
+          @value={{this.intensity}}
+          @min={{0}}
+          @max={{1}}
+          @step={{0.05}}
+          @description='How far the control leans, as a fraction of the falloff-scaled pointer offset. Above ~0.6 the control outruns the pointer and reads as slippery.'
+          @onInput={{this.setIntensity}}
+        />
+        <Args.Bool
+          @name='halo'
+          @defaultValue={{true}}
+          @value={{this.halo}}
+          @description='Draw the reach zone. Turning it off makes the component invisible in a still frame (the exact failure Law 8 names) — do it only when a neighbouring affordance already shows the target.'
+          @onInput={{this.setHalo}}
+        />
+        <Args.String
+          @name='hue'
+          @value={{this.hue}}
+          @description='Any CSS color for the halo. Empty falls back to the --primary token.'
+          @onInput={{this.setHue}}
+        />
+        <Args.Yield
+          @name='default'
+          @description='The magnetized control. It keeps all of its own events — the halo is pointer-events: none and aria-hidden, and nothing is layered over the control.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-magnetic-halo-radius'
+          @type='length'
+          @description='Corner radius of the reach halo — default 999px (a pill). Set it to match a rectangular control.'
+        />
+        <Css.Basic
+          @name='pretui-magnetic-range'
+          @type='length'
+          @description='Same channel @range writes to, for setting the reach from a stylesheet.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .mag-stage {
+        display: grid;
+        justify-items: center;
+        gap: 4px;
+        padding: 8px;
+      }
+      .mag-note {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_MAGNETIC: Record<string, unknown> = {
+  Magnetic: MagneticUsage,
+};