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

package/bundled-realms/pretui/components/sliding-highlight.gts

@@ -0,0 +1,249 @@
+// Pretui — SlidingHighlight: the traveling selection indicator and the modifier that measures it.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { modifier } from 'ember-modifier';
+import { cssNumber } from '../pretui-css';
+import { seconds } from '../internal/motion-core';
+
+// ── slidingHighlight (modifier) + SlidingHighlight (indicator) ───────────
+// Law 5's second canonical mechanism: ONE absolutely-positioned indicator
+// whose translate/width follow the active item's offsetLeft/offsetWidth with
+// a transition, so the selection TRAVELS instead of cross-fading. The
+// travel is what encodes "selection moved from there to here" — the reader
+// would otherwise have to infer it.
+//
+// This is deliberately split in two so adoption by an existing control is a
+// five-line diff and no component has to hand its DOM over:
+//   {{slidingHighlight}}   on the item container — measures, writes custom
+//                          properties, and nothing else
+//   <SlidingHighlight />   inside it — the indicator that reads them
+// Custom properties inherit across scoped-CSS boundaries, which is precisely
+// why the geometry travels as custom properties rather than as classes.
+//
+// Better than the inspiration (radix/headlessui indicators and the
+// react-bits animated tabs): the container does not have to declare which
+// item is active. A MutationObserver watches data-state / aria-selected /
+// aria-current, so the modifier takes no arguments in the common case and
+// stays correct when selection is driven by anything at all — including the
+// browser, via :checked-driven attributes. Upstream indicators need the
+// active index threaded through props and a useEffect to re-measure.
+//
+// Also handled, which upstream typically is not:
+//   - the first-paint slide from (0,0) is suppressed without a timer, by
+//     writing a 0s duration into the SAME style mutation as the first
+//     geometry (transitions read the after-change style, so nothing runs)
+//   - a ResizeObserver keeps the geometry honest through font loading and
+//     container resize
+//   - reduced motion parks the indicator on the active item instantly — the
+//     END state, never a frozen midpoint
+const ACTIVE_SELECTOR =
+  '[data-state="active"], [aria-selected="true"], [aria-current="true"], [aria-current="page"]';
+
+/**
+ * Measures the active descendant of the element it is installed on and
+ * publishes `--pretui-highlight-x/y/w/h/on` for a `<SlidingHighlight />`
+ * rendered inside. Takes no arguments in the common case; pass a custom
+ * active-item selector when the container also holds selectable content that
+ * the default selector would reach — `':scope > [aria-selected=\"true\"]'`
+ * confines it to direct children.
+ */
+export const slidingHighlight = modifier(
+  (el: HTMLElement, [selector]: [(string | undefined)?]) => {
+    let sel = selector ?? ACTIVE_SELECTOR;
+    // The indicator is absolutely positioned; give it a containing block if
+    // the container has not already claimed one.
+    if (getComputedStyle(el).position === 'static') {
+      el.style.position = 'relative';
+    }
+    let first = true;
+    let watched: HTMLElement | null = null;
+    let resize: ResizeObserver | null = null;
+    let measure = () => {
+      let active = el.querySelector<HTMLElement>(sel);
+      if (!active) {
+        el.style.setProperty('--pretui-highlight-on', '0');
+        return;
+      }
+      let x: number;
+      let y: number;
+      let w: number;
+      let h: number;
+      if (active.offsetParent === el) {
+        x = active.offsetLeft;
+        y = active.offsetTop;
+        w = active.offsetWidth;
+        h = active.offsetHeight;
+      } else {
+        let a = active.getBoundingClientRect();
+        let c = el.getBoundingClientRect();
+        x = a.left - c.left + el.scrollLeft;
+        y = a.top - c.top + el.scrollTop;
+        w = a.width;
+        h = a.height;
+      }
+      if (watched !== active) {
+        if (resize && watched) resize.unobserve(watched);
+        if (resize) resize.observe(active);
+        watched = active;
+      }
+      let style = el.style;
+      style.setProperty('--pretui-highlight-x', `${x.toFixed(2)}px`);
+      style.setProperty('--pretui-highlight-y', `${y.toFixed(2)}px`);
+      style.setProperty('--pretui-highlight-w', `${w.toFixed(2)}px`);
+      style.setProperty('--pretui-highlight-h', `${h.toFixed(2)}px`);
+      style.setProperty('--pretui-highlight-on', '1');
+      // First measurement lands with a 0s duration in the same mutation, so
+      // the indicator appears in place instead of sliding in from the
+      // origin. Clearing the property afterwards restores the real duration.
+      style.setProperty('--pretui-highlight-init', first ? '0s' : '');
+      first = false;
+    };
+    if (typeof ResizeObserver !== 'undefined') {
+      resize = new ResizeObserver(() => measure());
+    }
+    measure();
+    resize?.observe(el);
+    let mutation =
+      typeof MutationObserver === 'undefined'
+        ? null
+        : new MutationObserver(() => measure());
+    // 'style' is deliberately absent from the filter: the modifier writes to
+    // el.style itself, and watching it would feed back into this observer.
+    mutation?.observe(el, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: ['data-state', 'aria-selected', 'aria-current'],
+    });
+    return () => {
+      resize?.disconnect();
+      mutation?.disconnect();
+    };
+  },
+);
+
+export interface SlidingHighlightSignature {
+  Args: {
+    /** pill (default, a raised card face) | underline | soft (accent tint) | outline */
+    variant?: 'pill' | 'underline' | 'soft' | 'outline';
+    /** travel duration in seconds */
+    duration?: number;
+    /** bar thickness in px — the underline variant only */
+    thickness?: number;
+    /** corner radius in px; defaults to the control radius, or 1px under underline */
+    radius?: number;
+  };
+  Blocks: { default: [] };
+  Element: HTMLSpanElement;
+}
+
+/**
+ * The traveling indicator. Render it inside a container carrying
+ * `{{slidingHighlight}}`; it needs no arguments to work. Its block is a slot
+ * for callers who want to paint the indicator themselves (a gradient, a
+ * texture) while keeping the travel.
+ */
+export class SlidingHighlight extends Component<SlidingHighlightSignature> {
+  get variant(): string {
+    return this.args.variant ?? 'pill';
+  }
+  get style(): ReturnType<typeof htmlSafe> {
+    let bits: string[] = [];
+    if (this.args.duration !== undefined) {
+      bits.push(
+        `--pretui-highlight-duration: ${seconds(this.args.duration, 0.18)}`,
+      );
+    }
+    {
+      let n = cssNumber(this.args.thickness, 0, 1000);
+      if (n !== undefined) {
+        bits.push(`--pretui-highlight-thickness: ${n}px`);
+      }
+    }
+    {
+      let n = cssNumber(this.args.radius, 0, 1000);
+      if (n !== undefined) {
+        bits.push(`--pretui-highlight-radius: ${n}px`);
+      }
+    }
+    return htmlSafe(bits.join('; '));
+  }
+  <template>
+    <span
+      class='pretui-highlight'
+      data-variant={{this.variant}}
+      style={{this.style}}
+      aria-hidden='true'
+      data-test-pretui-sliding-highlight
+      ...attributes
+    >{{yield}}</span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-highlight {
+          position: absolute;
+          inset-block-start: 0;
+          inset-inline-start: 0;
+          width: var(--pretui-highlight-w, 0px);
+          height: var(--pretui-highlight-h, 0px);
+          transform: translate(
+            var(--pretui-highlight-x, 0px),
+            var(--pretui-highlight-y, 0px)
+          );
+          opacity: var(--pretui-highlight-on, 0);
+          border-radius: var(--pretui-highlight-radius, var(--radius));
+          pointer-events: none;
+          z-index: 0;
+          transition-property: transform, width, height, opacity;
+          /* --init is present only for the first measurement (see the
+             modifier); the chain then falls through to the caller's duration */
+          transition-duration: var(
+            --pretui-highlight-init,
+            var(--pretui-highlight-duration, 180ms)
+          );
+          transition-timing-function: var(
+            --pretui-highlight-ease,
+            cubic-bezier(0.23, 1, 0.32, 1)
+          );
+        }
+        /* a strong edge, so the pill reads even when its track blends into
+           the surface behind it */
+        .pretui-highlight[data-variant='pill'] {
+          background-color: var(--card);
+          box-shadow:
+            0 0 0 1px var(--border-strong),
+            var(--shadow-sm);
+        }
+        .pretui-highlight[data-variant='soft'] {
+          background-color: color-mix(
+            in oklch,
+            var(--primary) 14%,
+            var(--card)
+          );
+        }
+        /* a line is drawn in the -ink, which holds 3:1 on the surface; the
+           --primary fill does not */
+        .pretui-highlight[data-variant='outline'] {
+          box-shadow: 0 0 0 1px var(--primary-ink);
+        }
+        .pretui-highlight[data-variant='underline'] {
+          height: var(--pretui-highlight-thickness, 2px);
+          border-radius: var(--pretui-highlight-radius, 1px);
+          background-color: var(--primary-ink);
+          /* ride the bottom edge of the active item's box */
+          transform: translate(
+            var(--pretui-highlight-x, 0px),
+            calc(
+              var(--pretui-highlight-y, 0px) + var(--pretui-highlight-h, 0px) -
+                var(--pretui-highlight-thickness, 2px)
+            )
+          );
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-highlight {
+            transition-property: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/sliding-highlight.md

@@ -0,0 +1,58 @@
+## What it is
+
+The traveling selection indicator: one element that moves and resizes to sit under whichever item is active. **Law 5's second canonical mechanism**, and it is shared — **Tabs** and **SegmentedControl** both use this exact component rather than each painting their own active state. Use it whenever a set of peers has one active member and the selection should _travel_ rather than cross-fade. If the active state is a static fill, plain CSS is enough.
+
+## The contract
+
+```
+{{slidingHighlight}}          — modifier on the container
+<SlidingHighlight />          — the indicator, rendered inside
+@variant? 'pill' | 'underline' | 'soft' | 'outline'   (default 'pill')
+@duration? (s), @thickness? (px, underline only), @radius? (px)
+<:default>   — paint the indicator yourself while keeping the travel
+```
+
+**Two parts, and the split is the design.** The modifier measures; the component paints. The modifier publishes `--pretui-highlight-x/y/w/h/on` on the container, and the indicator is an absolutely-positioned element that reads them. So the measuring code exists **once** for the whole kit, and any component that wants a traveling indicator adds a modifier and an element rather than a measurement implementation.
+
+**It needs no arguments to work.** The default selector finds the active descendant; pass a custom one (`':scope > [aria-selected="true"]'`) when the container also holds selectable content the default would reach.
+
+**The modifier claims a containing block if the container has not.** If the container computes to `position: static` it sets `position: relative` — so a caller cannot forget the one CSS prerequisite.
+
+`--pretui-highlight-on` goes to `0` when there is no active item, so the indicator disappears rather than parking at the last position.
+
+The block slot exists for callers who want to paint the indicator themselves — a gradient, a texture — while keeping the travel.
+
+## Prior art
+
+Every kit paints this differently, and almost all of them cross-fade. **Radix `Tabs`** leaves the indicator to CSS on the active trigger. **Web Awesome `wa-tab-group`** does the same. **shadcn** styles the active tab's background. In all three, getting an indicator that _travels_ means writing measurement code yourself, per component.
+
+The nearest real prior art is **Framer's `layoutId`** (shared-layout animation), which achieves the travel through FLIP measurement in a JS animation engine on every frame.
+
+Pretui's improvement is structural rather than visual: **one measured implementation, adopted rather than copied.** The source records the reasoning when **SegmentedControl** took it up — adopting the shared primitive rather than keeping a local copy means the measuring code, the first-paint suppression and the reduced-motion fallback live in exactly one place. And the modifier reads the same `data-state='active'` the styling already used, so no component had to hand over its DOM or thread an active index through.
+
+The measurement is a `ResizeObserver` plus offset reads, not a RAF loop — so it costs nothing between changes, unlike the Framer approach.
+
+Where a second copy still exists: **TableOfContents** has a local vertical implementation of the same idea, with a note that it should be replaced by this component once both are on the realm. Two implementations of a "one implementation" primitive is worth closing.
+
+## Accessibility
+
+**No roles, no states, no keyboard — and that is correct.** The indicator is decoration; the selection it tracks is expressed by whatever the container marks as active (`aria-selected` on a tab, `aria-checked` on a radio, `data-state` on a segment).
+
+The important consequence, and it is a real one: **this component makes selection _look_ well-communicated while contributing nothing to how it is _announced_.** Each consumer exposes the selection itself: **Tabs** with `aria-selected`, **SegmentedControl** with native checked radios. A new consumer must do the same; the pill alone is invisible to assistive tech.
+
+Other notes:
+
+- **First-paint suppression** exists (the `first` flag), so the indicator does not animate from `0,0` on mount — it appears in place. Without that, every tab strip would slide in from the top-left corner on load.
+- **Reduced motion** sets `transition-property: none`, so the indicator moves to its new place instantly instead of disappearing. The guard lives here so consumers don't roll their own.
+- **`--pretui-highlight-on: 0`** hides the indicator when nothing is active, so an empty state does not leave a stray bar.
+- The indicator is absolutely positioned inside the container and does not affect layout, so it cannot push content or trap focus.
+
+## Theming
+
+`--pretui-highlight-duration` (default 0.18s), `--pretui-highlight-ease` (default `cubic-bezier(0.23, 1, 0.32, 1)`), `--pretui-highlight-thickness`, `--pretui-highlight-radius` (defaults to the control radius, or 1px under `underline`), plus the four variants: `pill` is a `--card` face with a 1px `--border-strong` edge and `--shadow-sm`, `soft` a `--primary` tint over `--card`, `outline` a 1px `--primary-ink` line, `underline` a `--primary-ink` bar. Lines use the `-ink` because the `--primary` fill misses 3:1 as a line.
+
+The published measurement properties (`--pretui-highlight-x/y/w/h/on`) are read-only outputs; a theme or caller should not set them.
+
+Because `pill` is a card face, it depends on `--card`, its `--border-strong` edge and `--shadow-sm` reading distinctly against whatever rail it sits on. A theme that makes the rail and the card the same color leaves the pill visible only by its edge and shadow.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/sliding-highlight.usage.gts

@@ -0,0 +1,184 @@
+// Pretui — SlidingHighlight usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { array, fn } from '@ember/helper';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { TASKS } from '../examples';
+import { SlidingHighlight, slidingHighlight } from './sliding-highlight';
+
+// ── SlidingHighlight — fresh page (no upstream knob rig) ─────────────────
+class SlidingHighlightUsage extends Component {
+  @tracked variant: 'pill' | 'underline' | 'soft' | 'outline' = 'pill';
+  @tracked duration = 0.18;
+  @tracked thickness = 2;
+  @tracked active = TASKS[0] as string;
+  setVariant = (v: string) =>
+    (this.variant = v as 'pill' | 'underline' | 'soft' | 'outline');
+  setDuration = (v: number | null) => (this.duration = v ?? 0.18);
+  setThickness = (v: number | null) => (this.thickness = v ?? 2);
+  select = (value: string) => (this.active = value);
+  isActive = (value: string) => this.active === value;
+  get options(): string[] {
+    return ['Booking', 'Cupping', 'Curing', 'Customs'];
+  }
+  get usage() {
+    return [
+      `<div role='tablist' {{slidingHighlight}}>`,
+      `  <SlidingHighlight @variant='${this.variant}' @duration={{${this.duration}}} />`,
+      `  {{#each this.options as |o|}}`,
+      `    <button role='tab' aria-selected={{...}}>{{o}}</button>`,
+      `  {{/each}}`,
+      `</div>`,
+    ].join('\n');
+  }
+  <template>
+    <FreestyleUsage
+      @name='SlidingHighlight'
+      @description="Law 5's travelling selection indicator: one absolutely-positioned element whose translate and size follow the active item, so the selection travels instead of cross-fading — the reader sees where it came from. It ships as two halves so any existing control can adopt it without surrendering its DOM: the slidingHighlight modifier on the item container measures and publishes --pretui-highlight-x/y/w/h, and <SlidingHighlight /> inside reads them. The modifier needs no arguments — a MutationObserver watches data-state / aria-selected / aria-current, so it stays correct whoever drives the selection. The first paint lands in place rather than sliding in from the corner, and reduced motion parks it on the active item instantly."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='sh-stage'>
+          <div class='sh-tabs' role='tablist' {{slidingHighlight}}>
+            <SlidingHighlight
+              @variant={{this.variant}}
+              @duration={{this.duration}}
+              @thickness={{this.thickness}}
+            />
+            {{#each this.options as |option|}}
+              <button
+                type='button'
+                role='tab'
+                class='sh-tab'
+                aria-selected={{if (this.isActive option) 'true' 'false'}}
+                {{on 'click' (fn this.select option)}}
+              >{{option}}</button>
+            {{/each}}
+          </div>
+          <p class='sh-note'>Selected stage:
+            <strong>{{this.active}}</strong></p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='variant'
+          @defaultValue='pill'
+          @value={{this.variant}}
+          @options={{array 'pill' 'underline' 'soft' 'outline'}}
+          @description='pill is a raised card face behind the label (SegmentedControl); underline is a bar riding the bottom edge of the item box (Tabs); soft is an accent tint; outline is a ring only.'
+          @onInput={{this.setVariant}}
+        />
+        <Args.Number
+          @name='duration'
+          @defaultValue={{0.18}}
+          @value={{this.duration}}
+          @min={{0.05}}
+          @max={{1}}
+          @step={{0.02}}
+          @description='Travel duration in seconds. Defaults to the kit-wide --pretui-dur-snap.'
+          @onInput={{this.setDuration}}
+        />
+        <Args.Number
+          @name='thickness'
+          @defaultValue={{2}}
+          @value={{this.thickness}}
+          @min={{1}}
+          @max={{8}}
+          @step={{1}}
+          @description='Bar thickness in px — the underline variant only.'
+          @onInput={{this.setThickness}}
+        />
+        <Args.Base
+          @name='radius'
+          @type='Number'
+          @defaultValue='var(--radius)'
+          @description='Corner radius in px. Left unset it follows the control radius, or 1px under the underline variant. Documented rather than knob-driven — the preset radii are the intended path.'
+        />
+        <Args.Yield
+          @name='default'
+          @description='Optional slot for painting the indicator yourself — a gradient, a texture — while keeping the travel. Empty by default.'
+        />
+        <Args.Action
+          @name='slidingHighlight (modifier)'
+          @description="Install on the item container. Optional first positional argument is a custom active-item selector; the default matches [data-state='active'], [aria-selected='true'] and [aria-current]. The container is given position: relative if it is still static. ResizeObserver and MutationObserver both disconnect on teardown."
+        />
+        <Args.Base
+          @name='--pretui-highlight-duration'
+          @type='CSS'
+          @defaultValue='var(--pretui-dur-snap, 180ms)'
+          @description='Travel duration; @duration sets it.'
+        />
+        <Args.Base
+          @name='--pretui-highlight-ease'
+          @type='CSS'
+          @defaultValue='var(--pretui-ease-snap)'
+          @description='Travel easing.'
+        />
+        <Args.Base
+          @name='--pretui-highlight-thickness'
+          @type='CSS'
+          @defaultValue='2px'
+          @description='Underline bar thickness; @thickness sets it.'
+        />
+        <Args.Base
+          @name='--pretui-highlight-radius'
+          @type='CSS'
+          @defaultValue='var(--radius)'
+          @description='Indicator corner radius.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .sh-stage {
+        display: grid;
+        gap: var(--space-4, 11px);
+        justify-items: start;
+      }
+      .sh-tabs {
+        position: relative;
+        display: inline-flex;
+        gap: 2px;
+        padding: 2px;
+        border-radius: calc(var(--radius) + 2px);
+        background: var(--muted);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+      }
+      .sh-tab {
+        position: relative;
+        z-index: 1;
+        height: 26px;
+        padding: 0 12px;
+        border: 0;
+        background: none;
+        border-radius: var(--radius);
+        font-family: inherit;
+        font-size: var(--text-ui, 12px);
+        font-weight: 500;
+        color: var(--muted-foreground);
+        cursor: pointer;
+        transition: color var(--pretui-dur-snap, 180ms)
+          var(--pretui-ease-snap, ease);
+      }
+      .sh-tab[aria-selected='true'] {
+        color: var(--foreground);
+      }
+      .sh-tab:focus-visible {
+        outline: 2px solid var(--ring);
+        outline-offset: 1px;
+      }
+      .sh-note {
+        margin: 0;
+        font-size: var(--text-ui, 12px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SLIDING_HIGHLIGHT: Record<string, unknown> = {
+  SlidingHighlight: SlidingHighlightUsage,
+};

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

@@ -0,0 +1,2 @@
+// Pretui — Snackbar: The MUI name for Toast.
+export { Toast as Snackbar } from './toast';

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

@@ -0,0 +1,34 @@
+## What it is
+
+**Snackbar** is **Toast** under the name MUI uses: the brief status card alone, with no position, clock or live region of its own. The export is the same component. MUI's `Snackbar` is a card _and_ a host in one; Pretui splits those, so the host that stacks, ages and dismisses — MUI's `open` / `autoHideDuration` / `anchorOrigin` — is **Toaster** (**Sonner** is its shadcn name). The **Toast** writeup carries the depth.
+
+## The contract
+
+```
+@title
+@message? / @description?   — the second line; description is the Sonner spelling
+<:icon> <:action>
+```
+
+Identical to Toast. Lifetime, placement and tone are not args here: they live on the item you `show()` into a Toaster.
+
+## Prior art
+
+**MUI `Snackbar`** owns `open`, `autoHideDuration`, `onClose`, `anchorOrigin` and `TransitionComponent`, and usually wraps an `Alert` for severity. Toast owns none of that: it is a title, a message and two slots, sized and shadowed to read as "floating above". The split is the point — one host implements the clock, the roles and the focus handling once, and the card stays ordinary content.
+
+## Accessibility
+
+Governing pattern: APG **Alert**. Toast hardcodes `role="status"` on the card and is its own live region, created with its content already in it, so a card that mounts complete is announced unreliably; there is no close control and no Escape handling. Render it inside a host that owns the region, the politeness and the dismiss, and pass `role={{null}}` so the card isn't a second region. **Toaster** owns all three but draws its own item, so it is the alternative to Snackbar, not a place to put one.
+
+## Theming
+
+Same as **Toast**; see its Theming.
+
+## React ecosystem
+
+| MUI Snackbar                            | Pretui                                                      |
+| --------------------------------------- | ----------------------------------------------------------- |
+| `message` / `action`                    | `@title` / `@message` / `<:action>`                         |
+| `open` / `autoHideDuration` / `onClose` | **Toaster** — `show()` returns an id, `duration` in seconds |
+| `anchorOrigin`                          | **Toaster** `@placement`                                    |
+| `severity` (via Alert)                  | `tone` on the item shown into Toaster                       |

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

@@ -0,0 +1,31 @@
+// Pretui — Snackbar usage page.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { FreestyleUsage } from './freestyle-usage';
+import CheckIcon from '@cardstack/boxel-icons/check';
+import { Button } from './button';
+import { Snackbar } from './snackbar';
+
+const SnackbarUsage: TemplateOnlyComponent = <template>
+  <FreestyleUsage
+    @name='Snackbar'
+    @description='Toast under the MUI name: the brief status card alone, with no position, clock or live region of its own. Import it when a port already says Snackbar; the component and its writeup are Toast, and the host that stacks and ages them is Toaster.'
+    @source="<Snackbar @title='Lot saved' @message='B-103 is ready for review'>…</Snackbar>"
+  >
+    <:example>
+      <Snackbar @title='Lot saved' @message='B-103 is ready for review'>
+        <:icon><CheckIcon width='14' height='14' aria-hidden='true' /></:icon>
+        <:action><Button @tone='neutral' @appearance='plain'>Review</Button></:action>
+      </Snackbar>
+    </:example>
+    <:api as |Args|>
+      <Args.String @name='title' @value='Lot saved' />
+      <Args.String @name='message' @value='B-103 is ready for review' @description='The second line; description is the Sonner spelling of the same arg.' />
+      <Args.Yield @name='icon' />
+      <Args.Yield @name='action' />
+    </:api>
+  </FreestyleUsage>
+</template>;
+
+export const DEMOS_SNACKBAR: Record<string, unknown> = {
+  Snackbar: SnackbarUsage,
+};

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

@@ -0,0 +1,2 @@
+// Pretui — Sonner: Toaster under the name other kits use.
+export { Toaster as Sonner } from './toaster';

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

@@ -0,0 +1,42 @@
+## What it is
+
+**Sonner** is **Toaster** under the shadcn name (`emilkowalski/sonner`): the positioned region that stacks, ages and dismisses toasts pushed into a **ToastStore**. The export is the same class. Import it when a port already says Sonner; the **Toaster** writeup carries the depth. The presentation-only card is **Toast** (**Snackbar** is its MUI name) and is not what this host renders — the host draws its own item so the clock, roles and controls are one implementation.
+
+## The contract
+
+```
+@store?                         — a ToastStore; the imperative half
+@toasts? + @onDismiss?          — the controlled alternative; wins over @store
+@placement? / @position?        — where the stack sits (default bottom-end)
+@limit? @duration?              — cap (default 4) and default seconds (default 5)
+@pauseOnHover? @pauseOnFocus? @pauseWhenHidden?
+@label? @dismissLabel? @hotkey?
+<:toast as |item|>              — draw the body yourself; the chrome stays
+```
+
+Identical to Toaster. `duration` is in seconds, and `0` makes a toast sticky.
+
+## Prior art
+
+**Sonner** exposes `toast()` as a module singleton with `toast.success` / `.error` / `.promise`, a `position`, `visibleToasts`, `closeButton`, `richColors` and `expand`. Toaster puts the imperative API on a store you instantiate — module-scope state in a realm is evaluated by the indexer and shared by every importer — and replaces `toast.promise` with `show({ id, … })` called again, which swaps a toast in place. Its cap is a real queue whose clocks have not started; Sonner keeps every toast alive behind the cap, so the ones never seen expire unseen. F6 moves focus into the region, which Sonner does not offer.
+
+## Accessibility
+
+A named landmark (`<section role='region' aria-label='Notifications' tabindex='-1'>`). Each toast carries `role='alert'` with `aria-live='assertive'` for `warning` and `danger`, `role='status'` with `aria-live='polite'` otherwise, `aria-atomic='true'` on both. F6 moves focus to the newest toast and back; dismissal hands focus to a neighbour or to where it came from, never the body; the clock pauses on hover and on focus. The life bar is `aria-hidden` and is exempt from reduced motion because stopping it would stop the dismissal. WCAG 2.2.1 is the caller's: give anything with an action a longer `duration`, or `0`.
+
+## Theming
+
+`--popover` and `--popover-foreground`, `--pretui-shadow-raised`, `--border`, `--radius-surface`, `--font-sans`, `--text-ui-md` and `--text-ui-sm`, `--muted-foreground`, `--foreground`, `--hover`, `--ring`, `--radius-control`, `--space-3` / `--space-4`. The tone stripe and life bar share `--pretui-toast-tone` per severity (`--pretui-info`, `--success`, `--warning`, `--destructive`, `--muted-foreground` for neutral). Host knobs: `--pretui-z-toast`, `--pretui-toaster-width`; entrance motion is `--pretui-dur-enter` / `--pretui-ease-enter`.
+
+## React ecosystem
+
+| Sonner | Pretui Sonner |
+| --- | --- |
+| `<Toaster position='bottom-right' />` | `<Sonner @store={{this.toasts}} @position='bottom-right' />` — mapped to `bottom-end` |
+| `toast('Saved')` | `this.toasts.show({ title: 'Saved' })` |
+| `toast.success(…)` / `.error(…)` | `show({ …, tone: 'success' })` / `tone: 'danger'` |
+| `toast.promise(p, {…})` | `show` returns an id; `show({ id, … })` again replaces in place |
+| `duration: 4000` | `duration: 4` — seconds |
+| `visibleToasts` | `@limit` — the rest queue unstarted |
+| `closeButton` | on by default; `dismissible: false` per toast |
+| `pauseWhenPageIsHidden` | `@pauseWhenHidden` |

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

@@ -0,0 +1,43 @@
+// Pretui — Sonner usage page.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Sonner } from './sonner';
+import { ToastStore } from './toaster';
+
+class SonnerUsage extends Component {
+  toasts = new ToastStore();
+
+  show = () =>
+    this.toasts.show({
+      title: 'Lot 4417 published',
+      message: 'Visible to the desk in a moment.',
+      tone: 'success',
+    });
+
+  <template>
+    <FreestyleUsage
+      @name='Sonner'
+      @description='Toaster under the shadcn name: the positioned region that stacks, ages and dismisses toasts pushed into a ToastStore. Import it when a port already says Sonner; the component and its writeup are Toaster.'
+      @source='<Sonner @store={{this.toasts}} @placement="bottom-end" />'
+    >
+      <:example>
+        <Button @tone='primary' @appearance='accent' {{on 'click' this.show}}>
+          Show a toast
+        </Button>
+        <Sonner @store={{this.toasts}} @placement='bottom-end' @limit={{3}} />
+      </:example>
+      <:api as |Args|>
+        <Args.Base @name='store' @description='A ToastStore: show({title, message, tone, duration}) returns an id; dismiss(id) and clear() do what they say.' @hideControls={{true}} />
+        <Args.String @name='placement' @defaultValue='bottom-end' @description='Where the stack sits. The Sonner position spellings (bottom-right, top-left, …) are accepted through position.' />
+        <Args.Number @name='limit' @defaultValue={{4}} @description='How many render at once; the rest queue with their clock unstarted.' />
+        <Args.Number @name='duration' @defaultValue={{5}} @description='Default seconds per toast. Seconds, not milliseconds.' />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_SONNER: Record<string, unknown> = {
+  Sonner: SonnerUsage,
+};