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

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

@@ -0,0 +1,436 @@
+// Pretui — Tour: an in-product walkthrough — one card per step, anchored to the real control it explains.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { guidFor } from '@ember/object/internals';
+// type-only gap: 'ember-modifier' resolves at realm runtime; glint cannot see
+// it here (accepted parse baseline, same as toaster.gts / focus.gts)
+import { modifier } from 'ember-modifier';
+import { Button } from './button';
+import { listenDocumentCapture } from '../focus';
+import { anchorTo } from '../internal/overlay';
+import type { PopupPlacement } from '../internal/overlay';
+
+export type TourPlacement = 'bottom' | 'top' | 'start' | 'end';
+
+export interface TourStep {
+  id: string;
+  title: string;
+  body: string;
+  /** A CSS selector for the control this step explains. Without it the card is centred. */
+  target?: string;
+  placement?: TourPlacement;
+}
+
+export interface TourSignature {
+  Args: {
+    steps: TourStep[];
+    /** Controlled visibility. Omit for uncontrolled (starts closed unless @defaultOpen). */
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Controlled step index. Omit for uncontrolled. */
+    index?: number;
+    onIndexChange?: (index: number) => void;
+    /** Fired by Done on the last step. */
+    onFinish?: () => void;
+    /** Fired by Skip, the close button or Escape. */
+    onSkip?: () => void;
+    /** Dim everything but the target and block pointer input to the rest of the page (default false). */
+    modal?: boolean;
+    /** Labels (defaults 'Back', 'Next', 'Done', 'Skip tour'). */
+    backLabel?: string;
+    nextLabel?: string;
+    doneLabel?: string;
+    skipLabel?: string;
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * Onboarding is a first-run scene; Tour is attached to the live UI: step N
+ * of M, a ring around the real control, Back / Next / Done and Skip.
+ *
+ * The card is a non-modal `role="dialog"` labelled by the step title and
+ * described by its body, so the page stays usable: Escape skips the tour
+ * only when focus is in the card, and every other control keeps its own
+ * Escape. `@modal` adds a scrim around the target that blocks the pointer
+ * elsewhere (and takes Escape page-wide). Each step moves focus to its
+ * primary button, and however the tour closes, focus returns to wherever it
+ * was when it opened. The card is placed by the kit's `anchorTo`, which
+ * flips and shifts to stay clear of the target; the target is scrolled into
+ * view (nearest, never the whole page). The ring is decoration, ignores the
+ * pointer and never covers the control — the step text carries the meaning
+ * (Law 6).
+ */
+export class Tour extends Component<TourSignature> {
+  private guid = guidFor(this);
+  @tracked private internalOpen = this.args.defaultOpen ?? false;
+  @tracked private internalIndex = 0;
+
+  get open(): boolean {
+    return (this.args.open ?? this.internalOpen) && this.count > 0;
+  }
+  get count(): number {
+    return this.args.steps?.length ?? 0;
+  }
+  get index(): number {
+    let raw = this.args.index ?? this.internalIndex;
+    return Math.min(Math.max(0, raw), Math.max(0, this.count - 1));
+  }
+  get step(): TourStep | undefined {
+    return this.args.steps?.[this.index];
+  }
+  get isFirst(): boolean {
+    return this.index === 0;
+  }
+  get isLast(): boolean {
+    return this.index >= this.count - 1;
+  }
+  get progress(): string {
+    return `Step ${this.index + 1} of ${this.count}`;
+  }
+  get titleId(): string {
+    return this.guid + '-title';
+  }
+  get bodyId(): string {
+    return this.guid + '-body';
+  }
+
+  private setIndex(next: number) {
+    if (this.args.index === undefined) {
+      this.internalIndex = next;
+    }
+    this.args.onIndexChange?.(next);
+  }
+  private setOpen(next: boolean) {
+    if (this.args.open === undefined) {
+      this.internalOpen = next;
+    }
+    this.args.onOpenChange?.(next);
+  }
+
+  /** the tour's own close sends an uncontrolled index back to the start */
+  private end() {
+    if (this.args.index === undefined) {
+      this.internalIndex = 0;
+    }
+    this.setOpen(false);
+  }
+
+  next = () => {
+    if (this.isLast) {
+      this.args.onFinish?.();
+      this.end();
+      return;
+    }
+    this.setIndex(this.index + 1);
+  };
+  back = () => {
+    if (!this.isFirst) {
+      this.setIndex(this.index - 1);
+    }
+  };
+  skip = () => {
+    this.args.onSkip?.();
+    this.end();
+  };
+  onKey = (event: Event) => {
+    let ev = event as KeyboardEvent;
+    // non-modal: Escape belongs to whatever has focus unless that is the card
+    let card = document.getElementById(this.cardId);
+    let target = ev.target as Node | null;
+    let inCard = Boolean(card && target && card.contains(target));
+    if (ev.key === 'Escape' && this.open && (this.args.modal || inCard)) {
+      ev.preventDefault();
+      ev.stopPropagation();
+      this.skip();
+    }
+  };
+
+  /** Records where focus was on every open, and gives it back on every
+   * close — Skip, Done, Escape or a controlled `@open={{false}}` alike. */
+  remember = modifier((el: HTMLElement) => {
+    let active = document.activeElement as HTMLElement | null;
+    let back = active && active !== document.body ? active : null;
+    let root = el.parentElement;
+    return () => {
+      let now = document.activeElement;
+      if (back && (!now || now === document.body || (root && root.contains(now)))) {
+        back.focus?.();
+      }
+    };
+  });
+
+  /** The step's target, or null when it has none or its selector is not valid. */
+  get targetEl(): HTMLElement | null {
+    let selector = this.step?.target;
+    if (!selector) {
+      return null;
+    }
+    try {
+      return document.querySelector<HTMLElement>(selector);
+    } catch {
+      return null;
+    }
+  }
+  get modal(): boolean {
+    return this.args.modal ?? false;
+  }
+  /** anchorTo takes undefined, not null, for no anchor. */
+  get anchorEl(): HTMLElement | undefined {
+    return this.targetEl ?? undefined;
+  }
+  get anchored(): boolean {
+    return this.targetEl !== null;
+  }
+  get cardId(): string {
+    return this.guid + '-card';
+  }
+  /** anchorTo's physical placement for the step's logical one. */
+  get popupPlacement(): PopupPlacement {
+    let rtl = document.documentElement.dir === 'rtl';
+    let p = this.placement;
+    if (p === 'start') {
+      return rtl ? 'right' : 'left';
+    }
+    if (p === 'end') {
+      return rtl ? 'left' : 'right';
+    }
+    return p;
+  }
+
+  /** Draws the ring, and under @modal the scrim around the target, and follows the target. */
+  outline = modifier((layer: HTMLElement, [target, modal]: [HTMLElement | null, boolean]) => {
+    target?.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
+    // a centred step must not keep the last anchored step's inline position
+    let card = layer.querySelector<HTMLElement>('.pretui-tour-card');
+    if (!target && card) {
+      card.style.top = '';
+      card.style.left = '';
+    }
+    let ring = layer.querySelector<HTMLElement>('.pretui-tour-ring');
+    let scrims = Array.from(layer.querySelectorAll<HTMLElement>('.pretui-tour-scrim'));
+    let update = () => {
+      let rect = target?.getBoundingClientRect() ?? null;
+      if (ring) {
+        ring.style.display = rect ? '' : 'none';
+        if (rect) {
+          Object.assign(ring.style, {
+            top: `${rect.top - 4}px`,
+            left: `${rect.left - 4}px`,
+            width: `${rect.width + 8}px`,
+            height: `${rect.height + 8}px`,
+          });
+        }
+      }
+      if (!modal) {
+        return;
+      }
+      // four real rects around the target: they catch the pointer, and the
+      // target in the middle stays pressable
+      let vw = document.documentElement.clientWidth;
+      let vh = document.documentElement.clientHeight;
+      let hole = rect ?? new DOMRect(vw / 2, vh / 2, 0, 0);
+      let boxes = [
+        { top: 0, left: 0, width: vw, height: Math.max(0, hole.top - 4) },
+        { top: hole.bottom + 4, left: 0, width: vw, height: Math.max(0, vh - hole.bottom - 4) },
+        { top: hole.top - 4, left: 0, width: Math.max(0, hole.left - 4), height: hole.height + 8 },
+        { top: hole.top - 4, left: hole.right + 4, width: Math.max(0, vw - hole.right - 4), height: hole.height + 8 },
+      ];
+      scrims.forEach((scrim, i) => {
+        let b = boxes[i] as { top: number; left: number; width: number; height: number };
+        Object.assign(scrim.style, { top: `${b.top}px`, left: `${b.left}px`, width: `${b.width}px`, height: `${b.height}px` });
+      });
+    };
+    update();
+    window.addEventListener('resize', update);
+    window.addEventListener('scroll', update, true);
+    return () => {
+      window.removeEventListener('resize', update);
+      window.removeEventListener('scroll', update, true);
+    };
+  });
+
+  /** Moves focus back to the primary button whenever the step changes. */
+  refocus = modifier((button: HTMLElement, [index]: [number]) => {
+    void index;
+    button.focus();
+  });
+
+  get placement(): TourPlacement {
+    let p = this.step?.placement;
+    return p === 'top' || p === 'start' || p === 'end' ? p : 'bottom';
+  }
+
+  <template>
+    {{#if this.open}}
+      <div class='pretui-tour' data-modal={{if @modal 'true' 'false'}} data-test-pretui-tour {{this.outline this.targetEl this.modal}} ...attributes>
+        {{#if @modal}}
+          <div class='pretui-tour-scrim' aria-hidden='true' data-test-pretui-tour-scrim></div>
+          <div class='pretui-tour-scrim' aria-hidden='true'></div>
+          <div class='pretui-tour-scrim' aria-hidden='true'></div>
+          <div class='pretui-tour-scrim' aria-hidden='true'></div>
+        {{/if}}
+        <div class='pretui-tour-ring' aria-hidden='true' data-test-pretui-tour-ring></div>
+        <span class='pretui-tour-watch' {{listenDocumentCapture 'keydown' this.onKey}} {{this.remember}}></span>
+        <div
+          id={{this.cardId}}
+          class='pretui-tour-card'
+          role='dialog'
+          aria-labelledby={{this.titleId}}
+          aria-describedby={{this.bodyId}}
+          data-anchored={{if this.anchored 'true' 'false'}}
+          data-test-pretui-tour-card
+          {{anchorTo this.anchorEl this.popupPlacement 10 false}}
+        >
+          <div class='pretui-tour-head'>
+            <span class='pretui-tour-progress' data-test-pretui-tour-progress>{{this.progress}}</span>
+            <button
+              type='button'
+              class='pretui-tour-close'
+              aria-label={{if @skipLabel @skipLabel 'Skip tour'}}
+              data-test-pretui-tour-close
+              {{on 'click' this.skip}}
+            >
+              <svg width='10' height='10' viewBox='0 0 12 12' aria-hidden='true'><path
+                  d='M2 2l8 8M10 2l-8 8'
+                  fill='none'
+                  stroke='currentColor'
+                  stroke-width='1.6'
+                  stroke-linecap='round'
+                /></svg>
+            </button>
+          </div>
+          <h2 id={{this.titleId}} class='pretui-tour-title' data-test-pretui-tour-title>{{this.step.title}}</h2>
+          <p id={{this.bodyId}} class='pretui-tour-body' data-test-pretui-tour-body>{{this.step.body}}</p>
+          <div class='pretui-tour-actions'>
+            <button type='button' class='pretui-tour-skip' data-test-pretui-tour-skip {{on 'click' this.skip}}>{{if @skipLabel @skipLabel 'Skip tour'}}</button>
+            <span class='pretui-tour-nav'>
+              {{#unless this.isFirst}}
+                <Button @appearance='outlined' @size='s' data-test-pretui-tour-back {{on 'click' this.back}}>{{if @backLabel @backLabel 'Back'}}</Button>
+              {{/unless}}
+              <Button
+                @appearance='accent'
+                @size='s'
+                data-test-pretui-tour-next
+                {{this.refocus this.index}}
+                {{on 'click' this.next}}
+              >{{#if this.isLast}}{{if @doneLabel @doneLabel 'Done'}}{{else}}{{if @nextLabel @nextLabel 'Next'}}{{/if}}</Button>
+            </span>
+          </div>
+        </div>
+      </div>
+    {{/if}}
+    <style scoped>
+      @layer PretComponent {
+        .pretui-tour-ring {
+          position: fixed;
+          z-index: var(--pretui-z-overlay, 70);
+          border-radius: var(--radius-control, 6px);
+          box-shadow: 0 0 0 2px var(--pretui-tour-ring, var(--primary));
+          pointer-events: none;
+          transition: top var(--pretui-dur-snap, 160ms) var(--pretui-ease-snap, ease-out),
+            left var(--pretui-dur-snap, 160ms) var(--pretui-ease-snap, ease-out),
+            width var(--pretui-dur-snap, 160ms) var(--pretui-ease-snap, ease-out),
+            height var(--pretui-dur-snap, 160ms) var(--pretui-ease-snap, ease-out);
+        }
+        .pretui-tour-scrim {
+          position: fixed;
+          z-index: var(--pretui-z-overlay, 70);
+          background: var(--pretui-overlay-scrim, rgb(0 0 0 / 0.45));
+        }
+        .pretui-tour-card[data-anchored='false'] {
+          inset-block-start: 50%;
+          inset-inline-start: 50%;
+          translate: -50% -50%;
+        }
+        .pretui-tour-card {
+          position: fixed;
+          z-index: var(--pretui-z-overlay, 70);
+          box-sizing: border-box;
+          inline-size: min(20rem, calc(100vw - 16px));
+          padding: var(--space-4, 0.6875rem);
+          border-radius: var(--radius-surface, 10px);
+          background: var(--popover);
+          color: var(--popover-foreground);
+          box-shadow: var(--pretui-shadow-overlay, 0 0 0 1px var(--border), 0 12px 32px rgb(16 24 40 / 0.18));
+          font-family: var(--font-sans);
+          font-size: var(--text-ui-md, 0.78rem);
+        }
+        .pretui-tour-head {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+        }
+        .pretui-tour-progress {
+          color: var(--muted-foreground);
+          font-size: var(--text-ui-xs, 0.66rem);
+          font-variant-numeric: tabular-nums;
+          letter-spacing: var(--track-eyebrow, 0.04em);
+          text-transform: uppercase;
+        }
+        .pretui-tour-close {
+          display: grid;
+          place-items: center;
+          inline-size: 1.5rem;
+          block-size: 1.5rem;
+          border: 0;
+          border-radius: var(--radius-control, 6px);
+          background: transparent;
+          color: var(--muted-foreground);
+          cursor: pointer;
+        }
+        .pretui-tour-close:hover {
+          color: var(--foreground);
+          background: var(--hover, color-mix(in oklch, currentColor 10%, transparent));
+        }
+        .pretui-tour-title {
+          margin: var(--space-2, 0.375rem) 0 0;
+          font-family: var(--font-serif);
+          font-size: var(--text-heading, 1.1875rem);
+          font-weight: var(--weight-heading, 500);
+        }
+        .pretui-tour-body {
+          margin: var(--space-2, 0.375rem) 0 0;
+          color: var(--muted-foreground);
+          line-height: var(--leading-body, 1.5);
+        }
+        .pretui-tour-actions {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          gap: var(--space-2, 0.375rem);
+          margin-block-start: var(--space-4, 0.6875rem);
+        }
+        .pretui-tour-nav {
+          display: flex;
+          gap: var(--space-2, 0.375rem);
+        }
+        .pretui-tour-skip {
+          padding: 0.25rem;
+          border: 0;
+          background: transparent;
+          color: var(--muted-foreground);
+          font: inherit;
+          text-decoration: underline;
+          text-underline-offset: 0.18em;
+          cursor: pointer;
+        }
+        .pretui-tour-close:focus-visible,
+        .pretui-tour-skip:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 1px;
+        }
+        .pretui-tour-watch {
+          display: none;
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-tour-ring {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,62 @@
+## What it is
+
+**An in-product walkthrough** attached to the live interface: one card per step, anchored to the real control it explains, with a ring around that control. Step N of M, Back, Next, Done, and Skip.
+
+Reach for a neighbour when the job is different:
+
+- **Onboarding** is a first-run scene of its own.
+- **Tooltip** is one hint on one control.
+- **Popover** is one panel on demand.
+
+## The contract
+
+```
+@steps ({ id, title, body, target?, placement? }[])
+@open?, @defaultOpen?, @onOpenChange?
+@index?, @onIndexChange?, @onFinish?, @onSkip?
+@modal? (default false)
+@backLabel?, @nextLabel?, @doneLabel?, @skipLabel?
+Element: HTMLDivElement
+```
+
+**Anchoring.** A step's `target` is a CSS selector for the control it explains. The target is scrolled into view (nearest, never the whole page). The card is placed by the kit's `anchorTo` on its `placement` side (`bottom` by default, then `top`, `start` or `end`, logical in RTL). It flips to the other side when there is no room, so it never covers the target, and it follows the target on scroll and resize. A step with no target, or with a selector that isn't valid, is centred. A ring is drawn around the target and never covers it.
+
+**Moving.** Next advances, Back returns, and on the last step Next becomes Done, which calls `@onFinish` and closes. Skip, the close button and Escape call `@onSkip` and close. Escape counts only while focus is in the card, so any other control on the page keeps its own Escape. The step can be controlled with `@index` and `@onIndexChange`, and visibility with `@open` and `@onOpenChange`. When Done, Skip, the close button or Escape closes the tour, an uncontrolled step goes back to the first one, so reopening starts over. Closing it through `@open` keeps the place.
+
+**Modal only on request.** By default the page stays usable around the card. `@modal` adds a scrim around the target, drawn as four rects that catch the pointer, so the rest of the page can't be clicked while the target stays pressable. Under `@modal`, Escape skips the tour from anywhere. The page is not made inert for the keyboard, so the dialog is never marked `aria-modal`.
+
+## Prior art
+
+**Ant `Tour`** takes `steps` (`title`, `description`, `target`, `placement`, `cover`), `open`, `current`, `onChange`, `onClose`, `onFinish`, `mask` and `type`. **React Joyride** takes `steps`, `run`, `stepIndex`, `callback` and `spotlightClicks`. **Shepherd.js** and **Driver.js** are the framework-free libraries. **Mantine** has none.
+
+Where Pretui is better: **focus is handled.** Next takes focus on every step, and closing returns focus to where it was before the tour. Joyride and Driver.js leave focus on the page behind. **Non-modal by default**, so the reader can try the control the step describes. **It is a labelled dialog**, titled and described by the step.
+
+Where it is thinner: **no arrow pointing at the target**, **no per-step custom content** beyond title and body, **no beacon mode** (Joyride's pulsing hotspots), and **no persistence** of whether the tour was seen. Store that yourself from `@onFinish` and `@onSkip`.
+
+## Accessibility
+
+APG **Dialog**, non-modal by default.
+
+- **The card is `role="dialog"`**, labelled by the step title (`aria-labelledby`) and described by its body (`aria-describedby`). It carries no `aria-modal`, because the page is never inert. The tests assert all three.
+- **Focus.** Next (or Done) takes focus when the tour opens and on every step, so the reader can press Enter through it. However the tour closes (Skip, Done, Escape or a controlled `@open={{false}}`), focus returns to the element that had it when that open began. The tests assert each, including a second open returning to its own opener.
+- **Escape skips while focus is in the card**, and another control's Escape stays its own. The tests assert both. **The close button is named** after the skip label.
+- **The ring and scrim are decoration**, `aria-hidden`. The step text carries the meaning (Law 6). The ring outlines the target and never hides it.
+- **Progress is text**, "Step 2 of 5".
+
+## Theming
+
+`--pretui-tour-ring` (default `--primary`), `--pretui-overlay-scrim` (the `@modal` scrim), `--pretui-z-overlay` (the card and ring), `--popover`, `--popover-foreground`, `--pretui-shadow-overlay`, `--radius-surface`, `--radius-control`, `--border`, `--hover`, `--ring`, `--muted-foreground`, `--foreground`, `--font-sans`, `--font-serif` (the title), `--text-heading`, `--weight-heading`, `--text-ui-md`, `--text-ui-xs`, `--track-eyebrow`, `--leading-body`, `--space-2`, `--space-4`, and `--pretui-dur-snap` / `--pretui-ease-snap` (the ring moving between steps).
+
+The card is 20rem wide at most. The ring's move is dropped under reduced motion.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                              | Give them                                    |
+| ---------------------------------------- | -------------------------------------------- |
+| Ant `<Tour steps open current onChange>` | `<Tour @steps @open @index @onIndexChange>`  |
+| Ant `mask`                               | `@modal={{true}}`                            |
+| Ant step `target: () => ref.current`     | step `target: '.css-selector'`               |
+| Joyride `run` / `stepIndex` / `callback` | `@open` / `@index` / `@onFinish` + `@onSkip` |
+| Driver.js `driver().drive()`             | `<Tour @defaultOpen={{true}}>`               |

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

@@ -0,0 +1,70 @@
+// Pretui — Tour usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Tour } from './tour';
+import type { TourStep } from './tour';
+import { Button } from './button';
+import { Input } from './input';
+
+const STEPS: TourStep[] = [
+  { id: 'search', title: 'Find a lot', body: 'Search by farm, region or process.', target: '.tr-demo-search' },
+  { id: 'roast', title: 'Start a roast', body: 'Pick a profile, then press Start. The curve records itself.', target: '.tr-demo-start', placement: 'top' },
+  { id: 'done', title: 'You are set', body: 'Replay this tour any time from Help.' },
+];
+
+export class TourUsage extends Component {
+  steps = STEPS;
+  @tracked open = false;
+  @tracked modal = false;
+  show = () => (this.open = true);
+  setOpen = (v: boolean) => (this.open = v);
+  setModal = (v: boolean) => (this.modal = v);
+  get usage() {
+    return "<Tour @steps={{this.steps}} @open={{this.touring}} @onOpenChange={{this.setTouring}} />";
+  }
+  <template>
+    <FreestyleUsage
+      @name='Tour'
+      @description='An in-product walkthrough: one card per step, anchored to the real control it explains, with a ring around it. The card is a non-modal dialog; Next takes focus each step, Escape skips, and focus returns to where it was. Onboarding is a first-run scene; Tour is attached to the live UI.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='tr-demo'>
+          <Input class='tr-demo-search' aria-label='Search lots' @placeholder='Search lots' />
+          <Button class='tr-demo-start' @appearance='accent'>Start roast</Button>
+          <Button @appearance='outlined' {{on 'click' this.show}}>Take the tour</Button>
+        </div>
+        <Tour @steps={{this.steps}} @open={{this.open}} @onOpenChange={{this.setOpen}} @modal={{this.modal}} />
+      </:example>
+      <:api as |Args|>
+        <Args.Object @name='steps' @required={{true}} @description='{ id, title, body, target?, placement? }[]; target is a CSS selector.' />
+        <Args.Bool @name='open' @description='Controlled; defaultOpen seeds the uncontrolled form.' />
+        <Args.Action @name='onOpenChange' />
+        <Args.Number @name='index' @description='Controlled step index.' />
+        <Args.Action @name='onIndexChange' />
+        <Args.Action @name='onFinish' @description='Done on the last step.' />
+        <Args.Action @name='onSkip' @description='Skip, the close button or Escape.' />
+        <Args.Bool @name='modal' @value={{this.modal}} @defaultValue={{false}} @onInput={{this.setModal}} @description='Dim everything but the target.' />
+        <Args.String @name='nextLabel' @defaultValue='Next' />
+        <Args.String @name='backLabel' @defaultValue='Back' />
+        <Args.String @name='doneLabel' @defaultValue='Done' />
+        <Args.String @name='skipLabel' @defaultValue='Skip tour' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .tr-demo {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: var(--space-3, 0.5rem);
+        padding: var(--space-6, 1.25rem) var(--space-4, 0.6875rem);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TOUR: Record<string, unknown> = {
+  Tour: TourUsage,
+};

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

@@ -0,0 +1,2 @@
+// Pretui — Transfer: The Ant name for DuelingPicklist.
+export { DuelingPicklist as Transfer } from './dueling-picklist';

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

@@ -0,0 +1,39 @@
+## What it is
+
+**Transfer** is **DuelingPicklist** under the name Ant Design uses. The export is the same class; nothing is re-implemented. Import it when a port or an agent already speaks Ant's vocabulary — two lists, move buttons, `targetKeys` — and wants the first guess to resolve. The depth lives in the **DuelingPicklist** writeup: this page only says what the name maps to.
+
+## The contract
+
+```
+@options            — every record in play: {id, label, meta?, icon?, locked?}
+@value? / @defaultValue?   — the selected list as an ORDERED id list
+@label? @availableLabel? @selectedLabel?
+@reorder? @disabled? @required? @rows?
+@onValueChange?     — the full ordered id list after every move
+<:option as |record state|>
+```
+
+Identical to DuelingPicklist. The one rule worth restating under this name: **the order of `@value` is the payload**, which is where Ant's `targetKeys` set and this control part ways.
+
+## Prior art
+
+**Ant `Transfer`** takes a flat `dataSource` plus `targetKeys`, renders the same row on both sides, and adds what DuelingPicklist does not have: a search box per list, `oneWay` (a single direction with a per-row remove), pagination inside each list, and a `render` prop for the row. DuelingPicklist has none of those and instead has the SLDS half Ant lacks — the up/down **reorder column**, `locked` records that cannot leave, a polite live region that announces every move, and focus that follows the moved records into the destination list. Ant announces nothing and leaves focus on the button. Neither drags.
+
+## Accessibility
+
+Two multi-select listboxes (`role="listbox"` with `aria-multiselectable`, `role="option"` with `aria-selected`) inside a labelled group. Each list has its own accessible name from `@availableLabel` / `@selectedLabel`, the group's from `@label`, and every move is announced with the destination noun. Arrows move, Space toggles, Shift extends, Ctrl/Cmd+A selects all, Ctrl/Cmd plus left/right transfers, Alt plus up/down reorders. Locked records carry `aria-disabled`. There is no drag path, so WCAG 2.5.7 does not arise.
+
+## Theming
+
+**RecordFace**'s row tokens, `--card` / `--inset` for the two list surfaces, `--border` for their edges, `--pretui-selected` and `--hover` for option states, and **Button** / **IconButton** tokens for the move and reorder controls. A theme must keep the two surfaces visually equal and `--pretui-selected` distinguishable from `--hover` within one list.
+
+## React ecosystem
+
+| Ant Transfer                              | Pretui Transfer                            |
+| ----------------------------------------- | ------------------------------------------ |
+| `dataSource`                              | `@options`                                 |
+| `targetKeys` / `onChange(nextTargetKeys)` | `@value` / `@onValueChange` — order kept   |
+| `titles=[left, right]`                    | `@availableLabel` / `@selectedLabel`       |
+| `render`                                  | `<:option>`                                |
+| `oneWay`                                  | not supported; both directions always show |
+| `showSearch` / `pagination`               | not supported; filter before handing over  |

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

@@ -0,0 +1,52 @@
+// Pretui — Transfer usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Transfer } from './transfer';
+import type { PickerRecord } from '../internal/forms-picker';
+
+const COLUMNS: PickerRecord[] = [
+  { id: 'lot', label: 'Lot', meta: 'a0X…' },
+  { id: 'tea', label: 'Tea', meta: 'name' },
+  { id: 'origin', label: 'Origin', meta: 'estate · region' },
+  { id: 'harvest', label: 'Harvest', meta: 'date' },
+  { id: 'chests', label: 'Chests', meta: 'count' },
+  { id: 'grade', label: 'Grade', meta: 'cupping score' },
+];
+
+class TransferUsage extends Component {
+  columns = COLUMNS;
+  @tracked value: string[] = ['lot', 'tea', 'chests'];
+  setValue = (ids: string[]) => (this.value = ids);
+
+  <template>
+    <FreestyleUsage
+      @name='Transfer'
+      @description='DuelingPicklist under the Ant name: two lists with move buttons, where the order of the right-hand list is the value. Import it when a port already says Transfer; the component and its writeup are DuelingPicklist.'
+      @source="<Transfer @options={{this.columns}} @value={{this.value}} @label='Report columns' @onValueChange={{this.setValue}} />"
+    >
+      <:example>
+        <Transfer
+          @options={{this.columns}}
+          @value={{this.value}}
+          @label='Report columns'
+          @availableLabel='Hidden'
+          @selectedLabel='Shown, in order'
+          @rows={{6}}
+          @onValueChange={{this.setValue}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Object @name='options' @required={{true}} @value={{this.columns}} @description='Every record: {id, label, meta?, icon?, locked?}. Both lists derive from this plus @value.' />
+        <Args.Array @name='value' @value={{this.value}} @onInput={{this.setValue}} @description='Ordered ids of the selected list. Ant targetKeys, with order kept.' />
+        <Args.Base @name='availableLabel / selectedLabel' @type='String' @description='Headings over the two lists; Ant titles.' />
+        <Args.Bool @name='reorder' @defaultValue={{true}} @description='The up/down column on the selected side.' />
+        <Args.Action @name='onValueChange' @description='Fires with the full ordered id list after every move.' />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_TRANSFER: Record<string, unknown> = {
+  Transfer: TransferUsage,
+};