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

package/bundled-realms/pretui/components/morphing-dialog.gts

@@ -0,0 +1,173 @@
+// Pretui — MorphingDialog: a Dialog that grows out of its trigger.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { modifier } from 'ember-modifier';
+import { Dialog } from './dialog';
+import { morphFrom } from '../internal/structure-morph';
+
+// ── MorphingDialog ───────────────────────────────────────────────────────
+
+export interface MorphingDialogSignature {
+  Args: {
+    /** Accessible name for the dialog, and its visible title when no
+     * `<:title>` block is given. */
+    label: string;
+    /** Controlled open state. Omit for uncontrolled. */
+    open?: boolean;
+    /** Fires with the next open state on every change. */
+    onOpenChange?: (open: boolean) => void;
+    /** Dialog width preset, forwarded to `Dialog`. Default `m`. */
+    size?: 's' | 'm' | 'l';
+    /** Allow Escape and backdrop dismissal. Default true. */
+    dismissible?: boolean;
+  };
+  Blocks: {
+    /** The resting card. It becomes the trigger, and its rectangle is what
+     * the dialog grows out of. */
+    trigger: [];
+    /** Visible dialog title. Falls back to `@label`. */
+    title: [];
+    /** Dialog body. */
+    default: [];
+    /** Actions row, rendered under a hairline at the foot of the body. */
+    actions: [];
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * A card that grows into its own modal dialog.
+ *
+ * ```hbs
+ * <MorphingDialog @label='Lot B-114'>
+ *   <:trigger><LotCard @lot={{this.lot}} /></:trigger>
+ *   <:default><LotDetail @lot={{this.lot}} /></:default>
+ *   <:actions><Button>Close</Button></:actions>
+ * </MorphingDialog>
+ * ```
+ *
+ * WRAPS `Dialog`, so every hard part is the platform's and none of it is
+ * re-implemented here: `showModal()` gives the focus trap, Escape, the top
+ * layer, the `::backdrop`, and — the one every hand-rolled modal forgets —
+ * focus RETURN to the trigger on close. The only thing this component adds
+ * is the morph, and it adds it through the shared `morphFrom` primitive.
+ *
+ * Better than the inspiration (motion-primitives' MorphingDialog): upstream
+ * builds the modal out of divs with a framer-motion layout animation, so it
+ * ships its own focus trap, its own Escape handling, its own scroll lock and
+ * a runtime — and it puts the trigger's content inside a clickable div
+ * rather than a button. Here the trigger is a real `<button>` with
+ * `aria-haspopup='dialog'` and `aria-expanded`, the modal is a native
+ * `<dialog>`, and the whole morph is one WAAPI call with no engine at all.
+ */
+export class MorphingDialog extends Component<MorphingDialogSignature> {
+  @tracked private internalOpen = false;
+  @tracked private origin: DOMRect | undefined = undefined;
+  private triggerEl?: HTMLElement;
+
+  captureTrigger = modifier((element: HTMLElement) => {
+    this.triggerEl = element;
+  });
+
+  get open(): boolean {
+    return this.args.open ?? this.internalOpen;
+  }
+
+  /** `undefined` while closed, so the modifier tears the animation down on
+   * close instead of replaying it. */
+  get morphOrigin(): DOMRect | undefined {
+    return this.open ? this.origin : undefined;
+  }
+
+  openDialog = () => {
+    // Measured at CLICK time, which is the last moment the trigger is
+    // guaranteed to be where the reader saw it.
+    this.origin = this.triggerEl?.getBoundingClientRect();
+    if (this.args.open === undefined) {
+      this.internalOpen = true;
+    }
+    this.args.onOpenChange?.(true);
+  };
+
+  closeDialog = () => {
+    if (this.args.open === undefined) {
+      this.internalOpen = false;
+    }
+    this.args.onOpenChange?.(false);
+  };
+
+  <template>
+    <div class='pretui-morph-dialog' data-test-pretui-morphing-dialog ...attributes>
+      <button
+        type='button'
+        class='pretui-morph-trigger'
+        aria-haspopup='dialog'
+        aria-expanded={{if this.open 'true' 'false'}}
+        data-test-pretui-morphing-dialog-trigger
+        {{this.captureTrigger}}
+        {{on 'click' this.openDialog}}
+      >
+        {{yield to='trigger'}}
+      </button>
+
+      <Dialog
+        @open={{this.open}}
+        @onClose={{this.closeDialog}}
+        @label={{@label}}
+        @size={{@size}}
+        @dismissible={{@dismissible}}
+        {{morphFrom this.morphOrigin}}
+      >
+        <:title>
+          {{#if (has-block 'title')}}
+            {{yield to='title'}}
+          {{else}}
+            {{@label}}
+          {{/if}}
+        </:title>
+        <:default>
+          <div class='pretui-morph-body'>{{yield}}</div>
+          {{#if (has-block 'actions')}}
+            <div class='pretui-morph-actions'>{{yield to='actions'}}</div>
+          {{/if}}
+        </:default>
+      </Dialog>
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-morph-dialog {
+          display: contents;
+        }
+        .pretui-morph-trigger {
+          display: block;
+          inline-size: 100%;
+          padding: 0;
+          border: 0;
+          background: transparent;
+          color: inherit;
+          font: inherit;
+          text-align: start;
+          cursor: pointer;
+          border-radius: var(--radius-surface, 10px);
+        }
+        .pretui-morph-trigger:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-morph-body {
+          color: var(--foreground);
+        }
+        .pretui-morph-actions {
+          display: flex;
+          justify-content: flex-end;
+          gap: var(--space-3, 8px);
+          margin-block-start: var(--space-4, 11px);
+          padding-block-start: var(--space-4, 11px);
+          border-block-start: 1px solid var(--border);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/morphing-dialog.md

@@ -0,0 +1,46 @@
+## What it is
+
+A card that grows into a dialog: the resting card is the trigger, and its rectangle is what the dialog expands out of.
+
+## The contract
+
+```
+@label (required) — accessible name, and the visible title when no <:title> is given
+@open?, @onOpenChange? — controlled / uncontrolled
+@size?        — dialog width preset, forwarded to Dialog. Default 'm'
+@dismissible? — allow Escape and backdrop dismissal. Default true
+
+<:trigger> the resting card; it becomes the trigger and the growth origin
+<:title>   visible dialog title; falls back to @label
+<:default> dialog body
+```
+
+**The trigger's rectangle is the origin of the growth**, which is the whole effect: the dialog appears to be the card, larger, rather than a panel arriving over it.
+
+**It forwards to the kit's Dialog**, so the focus trap, Escape handling and backdrop are that component's rather than being re-implemented around an animation.
+
+**`@label` does double duty** — the accessible name always, and the visible title when `<:title>` is absent — so a dialog is never nameless.
+
+## Prior art
+
+The morphing-card-to-dialog effect in motion libraries.
+
+Where Pretui is better: it is a real dialog underneath. The upstream implementations animate a div into position and leave focus management, Escape and the backdrop to the integrator, which in practice means a beautiful modal you cannot close with the keyboard.
+
+Where it is thinner: no shared-element transition across routes, no drag-to-dismiss, and the morph is size and position only — content does not cross-fade between the two states.
+
+## Accessibility
+
+- **The dialog is the kit's Dialog**, which brings the focus trap, Escape, and focus return to the trigger.
+- **The trigger is a real control**, so opening is a keyboard action rather than a click on a card.
+- **`@label` guarantees a name**, and a dialog without one is announced as an unnamed modal.
+- **`@dismissible={{false}}` removes Escape and backdrop dismissal**, which should only be used when the dialog's own content provides an unmissable way out.
+- **The morph is decoration over a state change that is already announced.** Reduced motion should land on the open dialog, which costs nothing because the dialog is the end state.
+
+## Theming
+
+Everything comes from **Dialog** and the kit's shared motion tokens; the morph uses the shared duration and easing.
+
+There is no morph-specific palette, so a morphing dialog and an ordinary one are the same surface arriving two ways.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/morphing-dialog.usage.gts

@@ -0,0 +1,168 @@
+// Pretui — MorphingDialog usage page.
+import Component from '@glimmer/component';
+import {
+  PLACES,
+  TEAS,
+  seedFrom,
+  take,
+} from '../examples';
+import { FreestyleUsage } from './freestyle-usage';
+import { MorphingDialog } from './morphing-dialog';
+
+// ── MorphingDialog ───────────────────────────────────────────────────────
+const MORPH_SEED = seedFrom('pretui-morph-demo');
+
+const DEMO_TEAS = take(MORPH_SEED, 0, 3, TEAS);
+
+interface DemoLot {
+  id: string;
+  tea: string;
+  place: string;
+  chests: number;
+}
+
+const DIALOG_LOTS: DemoLot[] = DEMO_TEAS.map((tea, i) => ({
+  id: 'B-' + (204 + i),
+  tea,
+  place: PLACES[(seedFrom('morph#' + tea) + i) % PLACES.length] as string,
+  chests: 30 + (seedFrom('chests#' + tea) % 210),
+}));
+
+export class MorphingDialogUsage extends Component {
+  lots = DIALOG_LOTS;
+
+  get usage(): string {
+    return [
+      "<MorphingDialog @label='Lot B-204'>",
+      '  <:trigger><LotCard @lot={{this.lot}} /></:trigger>',
+      '  <:default><LotDetail @lot={{this.lot}} /></:default>',
+      '  <:actions>…</:actions>',
+      '</MorphingDialog>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='MorphingDialog'
+      @description='A card that grows into its own modal dialog. Open any of the three cards and watch which one it came from — with six tiles on a page that is information the reader would otherwise have to reconstruct, which is exactly what Law 5 licenses motion for. It WRAPS Dialog, so the focus trap, Escape, the top layer, the backdrop and focus RETURN to the trigger are all the native <dialog> element’s rather than a re-implementation.'
+      @source={{this.usage}}
+      @viewportMode='wide'
+    >
+      <:example>
+        <div class='md-grid'>
+          {{#each this.lots key='id' as |lot|}}
+            <MorphingDialog @label={{lot.tea}} @size='m'>
+              <:trigger>
+                <article class='md-card'>
+                  <p class='md-id'>{{lot.id}}</p>
+                  <h4 class='md-tea'>{{lot.tea}}</h4>
+                  <p class='md-meta'>{{lot.place}}</p>
+                </article>
+              </:trigger>
+              <:title>{{lot.tea}}</:title>
+              <:default>
+                <p class='md-body'>Lot
+                  {{lot.id}}
+                  landed at
+                  {{lot.place}}:
+                  {{lot.chests}}
+                  chests, cleared and bonded. The dialog grew out of the card
+                  you clicked, so the connection between the two never has to
+                  be inferred.</p>
+                <p class='md-body'>Escape closes it, the backdrop closes it,
+                  and focus goes back to the card either way — all of that is
+                  the platform’s, not this component’s.</p>
+              </:default>
+              <:actions>
+                <span class='md-hint'>Press Escape to close</span>
+              </:actions>
+            </MorphingDialog>
+          {{/each}}
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='label'
+          @description='Accessible name for the dialog, and its visible title when no <:title> block is given.'
+        />
+        <Args.Bool
+          @name='open'
+          @description='Controlled open state. Omit for uncontrolled.'
+        />
+        <Args.Action
+          @name='onOpenChange'
+          @description='Fires with the next open state on every change, including a platform dismissal (Escape or backdrop).'
+        />
+        <Args.String
+          @name='size'
+          @description='Dialog width preset, forwarded to Dialog: s, m (default) or l.'
+        />
+        <Args.Bool
+          @name='dismissible'
+          @description='Allow Escape and backdrop dismissal.'
+          @defaultValue={{true}}
+        />
+        <Args.Yield
+          @name='trigger'
+          @description='The resting card. It becomes a real <button> with aria-haspopup="dialog", and its rectangle is what the dialog grows out of.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='actions'
+          @description='Actions row, rendered under a hairline at the foot of the body.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+
+    <style scoped>
+      .md-grid {
+        display: grid;
+        grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));
+        gap: var(--space-4, 11px);
+      }
+      .md-card {
+        display: grid;
+        gap: 2px;
+        padding: var(--space-5, 14px);
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        box-shadow: var(
+          --pretui-shadow-card,
+          0 0 0 1px var(--border),
+          0 1px 2px rgb(0 0 0 / 0.2)
+        );
+        text-align: start;
+      }
+      .md-id {
+        margin: 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        letter-spacing: var(--track-eyebrow, 0.08em);
+        color: var(--muted-foreground);
+      }
+      .md-tea {
+        margin: 0;
+        font-size: var(--text-ui-lg, 14px);
+        font-weight: var(--weight-strong, 600);
+      }
+      .md-meta {
+        margin: 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .md-body {
+        margin: 0 0 var(--space-3, 8px);
+        max-inline-size: 62ch;
+      }
+      .md-hint {
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_MORPHING_DIALOG: Record<string, unknown> = {
+  MorphingDialog: MorphingDialogUsage,
+};

package/bundled-realms/pretui/components/morphing-popover.gts

@@ -0,0 +1,245 @@
+// Pretui — MorphingPopover: a Popup that grows out of its trigger.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { guidFor } from '@ember/object/internals';
+import { modifier } from 'ember-modifier';
+import { listenDocument, listenDocumentCapture } from '../focus';
+import { Popup } from './popup';
+import type { PopupPlacement } from '../internal/overlay';
+import { morphFrom } from '../internal/structure-morph';
+
+// ── MorphingPopover ──────────────────────────────────────────────────────
+
+export interface MorphingPopoverSignature {
+  Args: {
+    /** Accessible name for the panel. */
+    label: string;
+    /** Controlled open state. Omit for uncontrolled. */
+    open?: boolean;
+    /** Fires with the next open state on every change. */
+    onOpenChange?: (open: boolean) => void;
+    /** Where the panel sits relative to the trigger. Default
+     * `bottom-start`; `anchorTo` flips and shifts it to stay on screen. */
+    placement?: PopupPlacement;
+    /** Gap between trigger and panel in px. Default 8. */
+    distance?: number;
+    /** Match the panel's minimum width to the trigger's. Default false. */
+    matchWidth?: boolean;
+  };
+  Blocks: {
+    /** The trigger's face. */
+    trigger: [];
+    /** The panel contents. Receives a `close` action so a control inside
+     * the panel can dismiss it without the caller tracking state. */
+    default: [close: () => void];
+  };
+  Element: HTMLSpanElement;
+}
+
+/**
+ * A trigger that grows into its own anchored panel.
+ *
+ * ```hbs
+ * <MorphingPopover @label='Filters'>
+ *   <:trigger>Filters</:trigger>
+ *   <:default as |close|><FilterSet @onDone={{close}} /></:default>
+ * </MorphingPopover>
+ * ```
+ *
+ * WRAPS `Popup`, so placement, flipping, shifting and the scroll/resize
+ * re-placement are `anchorTo`'s rather than a second copy. Added here: the
+ * morph out of the trigger's rectangle (`morphFrom`), Escape in the CAPTURE
+ * phase so a host that also listens for Escape cannot make one keypress mean
+ * two things, outside-pointer dismissal, focus into the panel on open, and
+ * focus back to the trigger on close.
+ *
+ * Better than the inspiration (motion-primitives' MorphingPopover): upstream
+ * ships the morph and nothing else — no placement logic (it is absolutely
+ * positioned and will happily render off-screen), no Escape, no outside
+ * click, no focus management, and a `div` trigger. Here the trigger is a
+ * `<button>` with `aria-haspopup` and `aria-expanded`, the panel is a
+ * `role='dialog'` with a name, and every dismissal path returns focus.
+ */
+export class MorphingPopover extends Component<MorphingPopoverSignature> {
+  @tracked private internalOpen = false;
+  @tracked private origin: DOMRect | undefined = undefined;
+  private triggerEl?: HTMLElement;
+
+  private panelId = guidFor(this) + '-morph-popover';
+
+  captureTrigger = modifier((element: HTMLElement) => {
+    this.triggerEl = element;
+  });
+
+  /** Focus moves INTO the panel on open — an overlay whose content the
+   * keyboard cannot reach is not an overlay, it is a decoration. */
+  focusPanel = modifier((element: HTMLElement) => {
+    element.focus();
+  });
+
+  get open(): boolean {
+    return this.args.open ?? this.internalOpen;
+  }
+
+  get morphOrigin(): DOMRect | undefined {
+    return this.open ? this.origin : undefined;
+  }
+
+  get distance(): number {
+    return this.args.distance ?? 8;
+  }
+
+  private setOpen(next: boolean): void {
+    if (this.args.open === undefined) {
+      this.internalOpen = next;
+    }
+    this.args.onOpenChange?.(next);
+  }
+
+  toggle = () => {
+    if (this.open) {
+      this.close();
+      return;
+    }
+    this.origin = this.triggerEl?.getBoundingClientRect();
+    this.setOpen(true);
+  };
+
+  close = () => {
+    if (!this.open) {
+      return;
+    }
+    this.setOpen(false);
+    // Focus RETURN. The native <dialog> gives this for free; an anchored
+    // panel has to do it, and almost none of them do.
+    this.triggerEl?.focus();
+  };
+
+  onDocumentKeydown = (event: Event) => {
+    if (!this.open) {
+      return;
+    }
+    let key = (event as KeyboardEvent).key;
+    if (key === 'Escape') {
+      event.stopPropagation();
+      event.preventDefault();
+      this.close();
+    }
+  };
+
+  onDocumentPointerdown = (event: Event) => {
+    if (!this.open) {
+      return;
+    }
+    let target = event.target as Node | null;
+    if (!target) {
+      return;
+    }
+    if (this.triggerEl?.contains(target)) {
+      return;
+    }
+    let panel = document.getElementById(this.panelId);
+    if (panel?.contains(target)) {
+      return;
+    }
+    this.setOpen(false);
+  };
+
+  <template>
+    <Popup
+      @open={{this.open}}
+      @placement={{@placement}}
+      @distance={{this.distance}}
+      @matchWidth={{@matchWidth}}
+      data-test-pretui-morphing-popover
+      ...attributes
+    >
+      <:anchor>
+        <button
+          type='button'
+          class='pretui-morph-pop-trigger'
+          aria-haspopup='dialog'
+          aria-expanded={{if this.open 'true' 'false'}}
+          aria-controls={{if this.open this.panelId}}
+          data-test-pretui-morphing-popover-trigger
+          {{this.captureTrigger}}
+          {{on 'click' this.toggle}}
+        >
+          {{yield to='trigger'}}
+        </button>
+      </:anchor>
+      <:default>
+        <div
+          class='pretui-morph-pop-panel'
+          id={{this.panelId}}
+          role='dialog'
+          aria-label={{@label}}
+          tabindex='-1'
+          data-test-pretui-morphing-popover-panel
+          {{this.focusPanel}}
+          {{morphFrom this.morphOrigin}}
+          {{listenDocumentCapture 'keydown' this.onDocumentKeydown}}
+          {{listenDocument 'pointerdown' this.onDocumentPointerdown true}}
+        >
+          {{yield this.close}}
+        </div>
+      </:default>
+    </Popup>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-morph-pop-trigger {
+          display: inline-flex;
+          align-items: center;
+          gap: var(--space-2, 6px);
+          padding: 6px 11px;
+          min-block-size: 30px;
+          border: 0;
+          border-radius: var(--radius-control, 7px);
+          background: var(--card);
+          color: var(--foreground);
+          box-shadow: var(
+            --pretui-shadow-control,
+            0 0 0 1px var(--border),
+            0 1px 2px rgb(0 0 0 / 0.3)
+          );
+          font: inherit;
+          font-size: var(--text-ui-md, 12.5px);
+          cursor: pointer;
+        }
+        @media (any-pointer: coarse) {
+          .pretui-morph-pop-trigger {
+            min-block-size: 44px;
+          }
+        }
+        .pretui-morph-pop-trigger:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-morph-pop-panel {
+          min-inline-size: var(--pretui-morph-popover-width, 240px);
+          max-inline-size: min(92vw, 420px);
+          padding: var(--space-4, 11px);
+          border-radius: var(--radius-surface, 10px);
+          background: var(--card);
+          color: var(--foreground);
+          box-shadow: var(
+            --pretui-shadow-overlay,
+            0 0 0 1px var(--border),
+            0 8px 28px rgb(0 0 0 / 0.34)
+          );
+          font-family: var(--font-sans);
+          font-size: var(--text-ui-md, 12.5px);
+          /* Transform origin follows the anchor edge so the morph reads as
+             growth out of the trigger rather than a slide from nowhere. */
+          transform-origin: top left;
+        }
+        .pretui-morph-pop-panel:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/morphing-popover.md

@@ -0,0 +1,47 @@
+## What it is
+
+A trigger that grows into a popover: the panel expands out of the control that opened it.
+
+## The contract
+
+```
+@label (required) — accessible name for the panel
+@open?, @onOpenChange? — controlled / uncontrolled
+@placement?   — where the panel sits relative to the trigger. Default 'bottom-start';
+                it flips and shifts to stay on screen
+@distance?    — gap between trigger and panel in px. Default 8
+@matchWidth?  — match the panel's minimum width to the trigger's. Default false
+
+<:trigger> the trigger's face
+<:default> the panel contents; receives a `close` action
+```
+
+**The panel block receives `close`**, so a control inside the panel can dismiss it without the caller tracking state. That is the arg that stops every consumer from wiring up an `@open` just to close from the inside.
+
+**Placement flips and shifts to stay on screen**, so `@placement` is a preference rather than an instruction.
+
+**`@matchWidth` is off by default**, because a popover as narrow as a small trigger is usually wrong — the arg exists for the select-like case where matching is right.
+
+## Prior art
+
+The morphing-popover effect in motion libraries, over the kit's own anchoring.
+
+Where Pretui is better: real anchoring with flip and shift, and a close action yielded into the panel. The upstreams animate a positioned div and leave both to the caller.
+
+Where it is thinner: no arrow or tail pointing at the trigger, no nested popovers, and no hover-open mode — this opens on activation only.
+
+## Accessibility
+
+- **The panel is named** through `@label`, which is what a screen reader announces on open.
+- **`close` being yielded is an accessibility affordance as much as a convenience**: a panel whose only dismissal is Escape or an outside click is harder to leave deliberately.
+- **The trigger is a real control** and focus returns to it on close.
+- **Flip and shift keep the panel on screen**, which matters for every input method equally — an off-screen panel is unreachable, not merely ugly.
+- **The morph is decoration over an already-announced state change**; reduced motion lands on the open panel.
+
+## Theming
+
+The panel takes the kit's overlay tokens and the morph the shared motion tokens.
+
+`@distance` is a caller value rather than a token because the right gap depends on the trigger, not on the theme.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.