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

package/bundled-realms/pretui/components/dueling-picklist.md

@@ -0,0 +1,67 @@
+## What it is
+
+Two side-by-side lists — Available and Selected — with move buttons between them and an optional reorder column. Use it when the selection is a **set whose order matters** and the whole option list is small enough to show at once: report columns, workflow stages, a permission set. If order does not matter, **MultiSelect** or **Picker** is far less UI. If the list is long or fetched, **Lookup**. If it is a short single choice, **Select**.
+
+## The contract
+
+```
+@options: PickerRecord[]   — every record in play; the two lists derive from this + @value
+@value? / @defaultValue?   — an ORDERED list of ids
+@label?, @availableLabel?, @selectedLabel?
+@reorder? (default true), @disabled?, @required?, @rows? (default 7)
+@onValueChange?(ids: string[])
+<:option as |record, { selected, side }|>
+```
+
+**"Order is the payload."** `@value` is an ordered array of ids, and reordering fires `@onValueChange` exactly as moving does. That is the reason this component exists rather than being a **MultiSelect** — a set of ids in arbitrary order is what MultiSelect gives you; an ordered list is a different value type, and the UI is the honest expression of it.
+
+**The two lists are derived, not stored.** There is one `@options` array and one `@value`; Available is `options - value` and Selected is `value` in order. So the component can never get into a state where a record is in both lists or in neither.
+
+**`PickerRecord.locked` means a record cannot be transferred out of its list** — the field exists on the shared record type specifically for this component, and it is how you express "this column is mandatory" without removing it from view.
+
+`@rows` (default 7) sets the visible height before each list scrolls.
+
+## Prior art
+
+**SLDS's `dueling-picklist`** is the direct ancestor and the canonical implementation — two listboxes, four move buttons, up/down reorder, and a documented ARIA contract. **React Spectrum**, **Radix**, **Web Awesome** and **shadcn** all ship nothing here; the pattern belongs to enterprise UI and modern kits have skipped it.
+
+So the comparison is against SLDS, and the interesting question is whether the pattern earns its space. The honest answer: it earns it **only** when order matters. For an unordered set, a multi-select with chips is one control instead of two lists and four buttons, and every usability comparison favours it.
+
+Where Pretui improves on SLDS:
+
+- **Records are the shared `PickerRecord` value**, so a dueling list, a **Lookup** result and a **RecordPill** all render through the same **RecordFace** primitive and look identical.
+- **`locked` as a record property** rather than a separate disabled-ids array — the constraint travels with the data.
+- **The derived-lists model** (above); SLDS leaves both lists to the caller.
+
+Where it is behind SLDS: no drag-and-drop between lists (SLDS supports it), no multi-select-then-move-many in some implementations, and no search/filter over the Available list — which for anything past thirty options is what you actually want, and is the point at which you should switch to **Lookup**.
+
+## Accessibility
+
+Governing pattern: **two multi-select listboxes** (`role="listbox"` with `aria-multiselectable`, `role="option"` with `aria-selected`) plus a labelled group, which is what the source documents.
+
+The move buttons are the crux, and SLDS's contract is the one to hold this to:
+
+- **Each list needs its own accessible name** (`@availableLabel`/`@selectedLabel`), and the whole control needs a group name (`@label`) — all three are exposed, which is right.
+- **Each move button names its direction and target**: "Move selection to Selected", "Move all to Available", not "→".
+- **Every move must be announced.** "Region added to Selected, position 3 of 5" — without it, a keyboard user presses a button and has no idea whether anything happened, because focus stays on the button while both lists change behind them. **Lookup** in this same file has a well-designed polite live region; this component should have the same, and whether it does is the first thing to check.
+- **Focus after a move** should follow the moved item or stay predictably on the button; an unmanaged move leaves focus on a button whose enabled state may have just changed.
+- **Reorder buttons need the same treatment** — "Move up" must announce the new position, or the reorder column is unusable without sight.
+- **WCAG 2.5.7 Dragging Movements** does not apply (there is no drag), which is one place the button-based design is _more_ accessible than SLDS's drag-enabled version.
+- **`locked` records must announce as such** — a record that cannot be moved should carry `aria-disabled` and, ideally, a reason.
+- **`@required` adds "(required)" to the legend's accessible name**; the asterisk beside it is `aria-hidden`, as in **FormField**.
+- Two scrolling listboxes at `@rows={{7}}` need keyboard scrolling, which listbox arrow navigation provides.
+
+## Theming
+
+**RecordFace**'s row tokens throughout, plus `--card`/`--inset` for the two list surfaces, `--border` for their edges, `--pretui-selected` and `--hover` for option states, **Button** or **IconButton** tokens for the move and reorder controls, and **Label**'s legend voice.
+
+The option rows carry a `prefers-reduced-motion` branch (their transition is disabled), which is a good sign for a control with this much state change.
+
+A theme must keep the two list surfaces visually equal — if Available and Selected read at different weights, the control implies a hierarchy that is not there. And `--pretui-selected` must be distinguishable from `--hover` within a list, since a user pointing at one row while another is selected is the normal state of this control.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Ant `Transfer`. **Transfer** is this component under that name. Accept `dataSource` /
+`targetKeys` / `onChange` as aliases if it helps agents.

package/bundled-realms/pretui/components/dueling-picklist.usage.gts

@@ -0,0 +1,182 @@
+// Pretui — DuelingPicklist usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import {
+  PLACES,
+  TEAS,
+  pick,
+  seedFrom,
+} from '../examples';
+import { DuelingPicklist } from './dueling-picklist';
+import type { PickerRecord } from '../internal/forms-picker';
+
+// ── DuelingPicklist ← slds dueling-picklist/ ─────────────────────────────
+const LOTS: PickerRecord[] = TEAS.slice(0, 9).map((name, i) => ({
+  id: `a0X00000${String(i + 31).padStart(2, '0')}`,
+  label: name,
+  meta: `${pick(seedFrom(name), i, PLACES)} · lot ${1200 + i * 37}`,
+  // the house control tea anchors every flight and cannot leave it
+  locked: i === 2,
+}));
+
+const LOT_IDS = LOTS.map((r) => r.id);
+
+// Dropped SLDS surface: native HTML5 `draggable` on the options (pointer-only,
+// no keyboard equivalent, and a rotate(3deg) grabbed transform that ignores
+// reduced motion), the modal Space-to-grab reorder mode (replaced by modeless
+// Alt+Arrow), and the `dataSet`/snapshot prop shape, whose per-option
+// tabIndex/isSelected/isGrabbed flags were authored by hand because nothing
+// upstream computed them.
+class DuelingPicklistUsage extends Component {
+  lots = LOTS;
+  lotIds = LOT_IDS;
+  @tracked value: string[] = [
+    LOTS[1]?.id as string,
+    LOTS[2]?.id as string,
+    LOTS[5]?.id as string,
+  ];
+  @tracked availableLabel = 'Cellar lots';
+  @tracked selectedLabel = 'Flight order';
+  @tracked rows: number | null = 6;
+  @tracked reorder = true;
+  @tracked disabled = false;
+  @tracked required = true;
+
+  setValue = (ids: string[]) => (this.value = ids);
+  setAvailableLabel = (v: string) => (this.availableLabel = v);
+  setSelectedLabel = (v: string) => (this.selectedLabel = v);
+  setRows = (v: number | null) => (this.rows = v);
+  setReorder = (v: boolean) => (this.reorder = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setRequired = (v: boolean) => (this.required = v);
+
+  get rowCount() {
+    return this.rows ?? 6;
+  }
+  get usage() {
+    let bits = [
+      '@options={{this.lots}}',
+      '@value={{this.value}}',
+      "@label='Cupping flight'",
+      `@availableLabel='${this.availableLabel}'`,
+      `@selectedLabel='${this.selectedLabel}'`,
+      `@rows={{${this.rowCount}}}`,
+    ];
+    if (!this.reorder) {
+      bits.push('@reorder={{false}}');
+    }
+    if (this.required) {
+      bits.push('@required={{true}}');
+    }
+    if (this.disabled) {
+      bits.push('@disabled={{true}}');
+    }
+    bits.push('@onValueChange={{this.setValue}}');
+    return `<DuelingPicklist ${bits.join('\n  ')}\n/>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='DuelingPicklist'
+      @description='The two-column transfer control: an available list, a selected list, move and move-all buttons in both directions, and up/down reorder on the selected side. Reach for it when a field is a SET whose ORDER is part of the answer — a cupping flight tasted light to dark, report columns, an approval chain — and when the user needs to see what is NOT chosen as clearly as what is. Both lists are multi-select listboxes with roving tabindex: arrows move the active option, Space toggles, Shift extends, Ctrl/Cmd+A selects all, Ctrl/Cmd plus left/right transfers between lists, and Alt plus up/down reorders. Every move is announced ("Gyokuro and Silver Needle: moved to Flight order.") and focus follows the moved records into the destination list rather than falling to the body. Records marked locked cannot be transferred out. Honest limits: no drag-and-drop (the keyboard and button paths are the complete ones), no grouping or search inside either list, and no virtualization — past a few hundred options, filter before you hand them over.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <DuelingPicklist
+          @options={{this.lots}}
+          @value={{this.value}}
+          @label='Cupping flight'
+          @availableLabel={{this.availableLabel}}
+          @selectedLabel={{this.selectedLabel}}
+          @rows={{this.rowCount}}
+          @reorder={{this.reorder}}
+          @required={{this.required}}
+          @disabled={{this.disabled}}
+          @onValueChange={{this.setValue}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='options'
+          @required={{true}}
+          @description='Every record in play: {id, label, meta?, icon?, locked?}. The two lists are derived from this plus @value — you never hand over two arrays that can drift apart.'
+          @value={{this.lots}}
+        />
+        <Args.Array
+          @name='value'
+          @description='Controlled selection as an ORDERED list of ids. The order IS the payload — that is the whole reason this control exists rather than a MultiSelect.'
+          @value={{this.value}}
+          @onInput={{this.setValue}}
+        />
+        <Args.Base
+          @name='defaultValue'
+          @type='String[]'
+          @description='Uncontrolled initial selection. Ignored once @value is supplied.'
+        />
+        <Args.Base
+          @name='label'
+          @type='String'
+          @defaultValue='Select options'
+          @description='Visible legend, and the accessible name of the whole role=group.'
+        />
+        <Args.String
+          @name='availableLabel'
+          @value={{this.availableLabel}}
+          @defaultValue='Available'
+          @description='Heading over the left list. Also the noun in every "moved to …" announcement and in the move buttons’ accessible names.'
+          @onInput={{this.setAvailableLabel}}
+        />
+        <Args.String
+          @name='selectedLabel'
+          @value={{this.selectedLabel}}
+          @defaultValue='Selected'
+          @description='Heading over the right list, same double duty as availableLabel.'
+          @onInput={{this.setSelectedLabel}}
+        />
+        <Args.Number
+          @name='rows'
+          @value={{this.rows}}
+          @min={{3}}
+          @max={{12}}
+          @defaultValue={{7}}
+          @description='Visible rows per list before it scrolls.'
+          @onInput={{this.setRows}}
+        />
+        <Args.Bool
+          @name='reorder'
+          @defaultValue={{true}}
+          @description='Show the up/down reorder column and enable Alt+Arrow reordering. Turn it off when the selection is a set, not a sequence.'
+          @value={{this.reorder}}
+          @onInput={{this.setReorder}}
+        />
+        <Args.Bool
+          @name='required'
+          @defaultValue={{false}}
+          @description='Renders the required marker beside the legend. It marks; it never validates.'
+          @value={{this.required}}
+          @onInput={{this.setRequired}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @description='Blocks every move and dims both lists.'
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description='Fires with the full ordered id list after every transfer or reorder.'
+        />
+        <Args.Yield
+          @name=':option'
+          @description='Replaces the option row in BOTH lists. Yields (record, {selected, side}). Defaults to a RecordFace.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_DUELING_PICKLIST: Record<string, unknown> = {
+  DuelingPicklist: DuelingPicklistUsage,
+};

package/bundled-realms/pretui/components/dynamic-island.gts

@@ -0,0 +1,264 @@
+// Pretui — DynamicIsland: a pill that morphs between idle, compact and expanded views.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { guidFor } from '@ember/object/internals';
+
+// ── DynamicIsland ────────────────────────────────────────────────────────
+
+export type IslandView = 'idle' | 'compact' | 'expanded';
+
+export interface DynamicIslandSignature {
+  Args: {
+    /** Controlled view. Omit for uncontrolled. */
+    view?: IslandView;
+    /** Initial view for the uncontrolled case. Default `compact`. */
+    defaultView?: IslandView;
+    /** Fires with the next view on every change. */
+    onViewChange?: (view: IslandView) => void;
+    /** Accessible name for the capsule. */
+    label?: string;
+    /** Let the reader toggle compact ⇄ expanded. Default true. Turn it off
+     * for a purely host-driven status capsule. */
+    expandable?: boolean;
+  };
+  Blocks: {
+    /** The resting sliver — a dot, a bar, a single glyph. */
+    idle: [];
+    /** The one-line state: what is happening, right now. */
+    compact: [];
+    /** The detail: controls, progress, a description. */
+    expanded: [];
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * A status capsule that morphs between three views.
+ *
+ * ```hbs
+ * <DynamicIsland @label='Indexing status' @view={{this.view}}>
+ *   <:idle><span class='dot'></span></:idle>
+ *   <:compact>Indexing 42 cards…</:compact>
+ *   <:expanded><Progress @value={{this.done}} /></:expanded>
+ * </DynamicIsland>
+ * ```
+ *
+ * The motion is the point and it is legitimate under Law 5: the capsule
+ * growing is what tells the reader that the SAME object gained detail,
+ * rather than a second, unrelated surface appearing. Nothing animates while
+ * the view is unchanged.
+ *
+ * Better than the inspiration (cult-ui's dynamic-island): upstream drives
+ * the whole thing with a spring engine and a `setTimeout` state machine that
+ * advances itself — which is decoration, not state, and is forbidden in this
+ * realm besides. Here the view is DATA: controlled by the host or toggled by
+ * the reader, never by a clock. The geometry is a set of `--pretui-island-*`
+ * tokens rather than hard-coded pixels, the capsule carries `role='status'`
+ * so a state change is announced without stealing focus, and the toggle is a
+ * real named button rather than a click handler on a div.
+ */
+export class DynamicIsland extends Component<DynamicIslandSignature> {
+  @tracked private internalView: IslandView | undefined = undefined;
+
+  private bodyId = guidFor(this) + '-island-body';
+
+  get view(): IslandView {
+    return (
+      this.args.view ?? this.internalView ?? this.args.defaultView ?? 'compact'
+    );
+  }
+
+  get expandable(): boolean {
+    return this.args.expandable ?? true;
+  }
+
+  get isExpanded(): boolean {
+    return this.view === 'expanded';
+  }
+
+  get isIdle(): boolean {
+    return this.view === 'idle';
+  }
+
+  get toggleLabel(): string {
+    return this.isExpanded ? 'Collapse details' : 'Expand details';
+  }
+
+  toggle = () => {
+    let next: IslandView = this.isExpanded ? 'compact' : 'expanded';
+    if (this.args.view === undefined) {
+      this.internalView = next;
+    }
+    this.args.onViewChange?.(next);
+  };
+
+  <template>
+    <div class='pretui-island' data-test-pretui-dynamic-island ...attributes>
+      <div
+        class='pretui-island-capsule'
+        data-view={{this.view}}
+        role='status'
+        aria-label={{@label}}
+        id={{this.bodyId}}
+        data-test-pretui-island-capsule
+      >
+        {{! Exactly one view is rendered at a time — which is what makes
+            @starting-style fire on the incoming one, and what stops the
+            capsule from being sized by the largest block it was given. }}
+        <div class='pretui-island-body'>
+          {{#if this.isExpanded}}
+            <div class='pretui-island-view' data-view='expanded'>
+              {{yield to='expanded'}}
+            </div>
+          {{else if this.isIdle}}
+            <div class='pretui-island-view' data-view='idle'>
+              {{yield to='idle'}}
+            </div>
+          {{else}}
+            <div class='pretui-island-view' data-view='compact'>
+              {{yield to='compact'}}
+            </div>
+          {{/if}}
+        </div>
+
+        {{#if this.expandable}}
+          {{! A named button rather than a click handler on the capsule: the
+              capsule's own content is live status text, and folding that
+              into a button's accessible name would make the name change
+              every time the status did. Collapsed, the button covers the
+              capsule (the island idiom — tap anywhere); expanded, it
+              shrinks to a corner so the detail view keeps its own pointer
+              events. }}
+          <button
+            type='button'
+            class='pretui-island-toggle'
+            aria-expanded={{if this.isExpanded 'true' 'false'}}
+            aria-controls={{this.bodyId}}
+            aria-label={{this.toggleLabel}}
+            data-test-pretui-island-toggle
+            {{on 'click' this.toggle}}
+          ><span class='pretui-island-caret' aria-hidden='true'></span></button>
+        {{/if}}
+      </div>
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-island {
+          display: flex;
+          justify-content: center;
+          font-family: var(--font-sans);
+        }
+        .pretui-island-capsule {
+          position: relative;
+          display: grid;
+          overflow: hidden;
+          color: var(--pretui-island-ink, var(--card));
+          background: var(--pretui-island-ground, var(--foreground));
+          box-shadow: var(--pretui-shadow-raised, 0 2px 10px rgb(0 0 0 / 0.22));
+          inline-size: var(--pretui-island-width, 260px);
+          block-size: var(--pretui-island-height, 44px);
+          border-radius: var(--pretui-island-radius, 22px);
+          /* THE morph. Three properties, one transition, and the reader reads
+             it as one object changing rather than three surfaces swapping. */
+          transition: inline-size 340ms cubic-bezier(0.23, 1, 0.32, 1),
+            block-size 340ms cubic-bezier(0.23, 1, 0.32, 1),
+            border-radius 340ms cubic-bezier(0.23, 1, 0.32, 1);
+        }
+        .pretui-island-capsule[data-view='idle'] {
+          inline-size: var(--pretui-island-idle-width, 96px);
+          block-size: var(--pretui-island-idle-height, 26px);
+          border-radius: var(--pretui-island-idle-radius, 13px);
+        }
+        .pretui-island-capsule[data-view='expanded'] {
+          inline-size: var(--pretui-island-expanded-width, 340px);
+          block-size: var(--pretui-island-expanded-height, 156px);
+          border-radius: var(--pretui-island-expanded-radius, 26px);
+        }
+        .pretui-island-body {
+          display: grid;
+          align-items: center;
+          min-inline-size: 0;
+          block-size: 100%;
+          padding-inline: var(--space-5, 14px);
+          padding-block: var(--space-3, 8px);
+          font-size: var(--text-ui-md, 12.5px);
+        }
+        .pretui-island-capsule[data-view='idle'] .pretui-island-body {
+          padding-inline: var(--space-3, 8px);
+          padding-block: 0;
+          justify-items: center;
+        }
+        .pretui-island-view {
+          min-inline-size: 0;
+          opacity: 1;
+          /* The incoming view fades up as the box grows. @starting-style is
+             what gives an ENTERING element something to animate from without
+             a JS frame — verified to survive the scoped-CSS transpile. */
+          transition: opacity 220ms ease-out;
+        }
+        @starting-style {
+          .pretui-island-view {
+            opacity: 0;
+          }
+        }
+        .pretui-island-view[data-view='expanded'] {
+          align-self: start;
+          inline-size: 100%;
+        }
+        .pretui-island-toggle {
+          position: absolute;
+          inset: 0;
+          border: 0;
+          padding: 0;
+          background: transparent;
+          color: inherit;
+          cursor: pointer;
+          display: grid;
+          place-items: end center;
+          padding-block-end: 6px;
+        }
+        .pretui-island-capsule[data-view='expanded'] .pretui-island-toggle {
+          inset: auto 6px 6px auto;
+          inline-size: 30px;
+          block-size: 30px;
+          border-radius: 999px;
+          place-items: center;
+          padding: 0;
+          background: color-mix(in oklch, var(--card) 16%, transparent);
+        }
+        @media (any-pointer: coarse) {
+          .pretui-island-capsule[data-view='expanded'] .pretui-island-toggle {
+            inline-size: 44px;
+            block-size: 44px;
+          }
+        }
+        .pretui-island-toggle:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: -3px;
+          border-radius: inherit;
+        }
+        .pretui-island-caret {
+          inline-size: 7px;
+          block-size: 7px;
+          border-inline-end: 1.5px solid currentColor;
+          border-block-end: 1.5px solid currentColor;
+          transform: rotate(45deg);
+          opacity: 0.7;
+          transition: transform 340ms cubic-bezier(0.23, 1, 0.32, 1);
+        }
+        .pretui-island-capsule[data-view='expanded'] .pretui-island-caret {
+          transform: rotate(-135deg);
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-island-capsule,
+          .pretui-island-view,
+          .pretui-island-caret {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/dynamic-island.md

@@ -0,0 +1,45 @@
+## What it is
+
+A capsule that changes size with what it has to say: a resting sliver, a one-line state, and an expanded detail view.
+
+## The contract
+
+```
+@view?, @defaultView?, @onViewChange? — controlled / uncontrolled view.
+              Default 'compact'
+@label?       — accessible name for the capsule
+@expandable?  — let the reader toggle compact ⇄ expanded. Default true.
+                Turn it off for a purely host-driven status capsule
+
+<:idle>    the resting sliver — a dot, a bar, a single glyph
+<:compact> the one-line state: what is happening, right now
+<:expanded> the detail: controls, progress, a description
+```
+
+**Three blocks, three sizes, one element.** The capsule morphs between them rather than swapping components, which is what makes the transition read as one object changing rather than as three things replacing each other.
+
+**`@expandable={{false}}` makes it host-driven only.** A status capsule that the reader cannot open is a legitimate thing — the arg exists so that is expressible rather than being achieved by omitting a handler.
+
+## Prior art
+
+Apple's Dynamic Island.
+
+Where Pretui is better: it is a contract with three blocks rather than an effect. The upstream is a platform affordance; this is the same idea made composable, with the view as controllable state so a host can drive it from what is actually happening.
+
+Where it is thinner: no multi-activity stacking — one capsule, one state — no gesture model beyond the toggle, and no priority or queueing when two things want the island at once.
+
+## Accessibility
+
+- **The capsule is named**, which is essential for something that changes shape: without a stable name, a screen-reader user encounters what appears to be a different element each time.
+- **`@expandable` decides whether there is a control at all.** When false, the capsule is a live status region and nothing more; when true, it is a disclosure.
+- **A capsule that changes content without announcing it is a silent status.** Whether the view change is announced is the host's decision through what it puts in the blocks — the component supplies no live region of its own.
+- **The idle sliver is often a single glyph**, which needs to be `aria-hidden` with the meaning carried elsewhere, or it announces as an unnamed graphic.
+- **Motion is central to this component's identity**, so reduced motion should land it on the target size without the morph.
+
+## Theming
+
+The capsule takes the kit's elevation and surface tokens, with the morph riding the shared duration and easing.
+
+Using the shared motion tokens is what keeps the island feeling like the same product as every other transition — an island with its own curve is the one element that moves differently from everything around it.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.