@cardstack/boxel-cli 0.12.0 → 0.13.0-unstable.0

package/bundled-types/choreo/test-support/index.ts

@@ -90,37 +90,16 @@ export function orphanCount(root: HTMLElement = testRoot()): number {
 }
 
 /**
- * The first LIVE match for `selector` — the copy that is still part of the
- * rendered tree, never a leaver parked in a region's orphan layer.
- *
- * Mid-crossing an identity exists twice: the arriving element in the live
- * tree, and the departing skin the region locked into `[data-choreo-orphans]`
- * so it can be flown and faded. That layer is the region's FIRST child, so a
- * bare `querySelector` answers with the ghost — an element whose component
- * has already been torn down, whose listeners are gone, and whose box is
- * where the OLD scene stood. Clicking it does nothing; measuring it measures
- * the past. Neither failure names itself.
- *
- * So any assertion or interaction a test performs while a crossing may be
- * aloft should come through here. A raised sprite (`c.Raise`) is deliberately
- * still live: it is the real element on a different layer, not a copy.
+ * `live()` / `liveAll()`: queries that skip memories. Mid-crossing an identity
+ * exists twice: the arriving element in the live tree, and the departing one
+ * the region keeps as a memory in its orphan layer so it can be flown and
+ * faded. The memory's test hooks carry a suffix (`data-test-title-memory`),
+ * but a class or role selector matches both, and the orphan layer is the
+ * region's FIRST child, so a bare `querySelector` answers with the memory. A
+ * raised sprite (`c.Raise`) is deliberately still live: it is the real element
+ * on a different layer, not a memory.
  */
-export function live<E extends Element = HTMLElement>(
-  selector: string,
-  root: ParentNode = testRoot(),
-): E | null {
-  return liveAll<E>(selector, root)[0] ?? null;
-}
-
-/** every live match for `selector`, in document order — see `live()` */
-export function liveAll<E extends Element = HTMLElement>(
-  selector: string,
-  root: ParentNode = testRoot(),
-): E[] {
-  return [...root.querySelectorAll<E>(selector)].filter(
-    (el) => !el.closest('[data-choreo-orphans]'),
-  );
-}
+export { live, liveAll } from 'glimmer-motion/test-support';
 
 /**
  * Elements still wearing a transform that nothing is animating.

package/bundled-types/glimmer-motion/index.ts

@@ -2,9 +2,9 @@
  * glimmer-motion — Motion's React glue re-done for Glimmer, on the unchanged motion-dom engine.
  * Deep imports (`glimmer-motion/motion`, `glimmer-motion/presence`, …) are the same modules.
  *
- * `registerBusyProbe` and the participant-host API are the seams a layer built
- * on top (such as `@cardstack/choreo`) uses to take part in settling and in
- * motion elements' lifecycles.
+ * `registerBusyProbe`, the participant-host API and memories are the seams a
+ * layer built on top (such as `@cardstack/choreo`) uses to take part in
+ * settling, in motion elements' lifecycles, and in keeping leavers on screen.
  */
 export { type BusyProbe, registerBusyProbe } from './activity.ts';
 export { createDragControls, DragControls } from './gestures/drag-controls.ts';
@@ -38,6 +38,14 @@ export {
   RENDER_DETECTOR_ATTRIBUTE,
   snapshotOnRender,
 } from './layout-group.gts';
+export type { ScrollPosition, Shown, ShownAnimation } from './memory.ts';
+export {
+  keepAsMemory,
+  MEMORY_ATTRIBUTE,
+  MEMORY_HOOK_SUFFIX,
+  readAnimations,
+  trackScrolls,
+} from './memory.ts';
 export type { MotionEl, MotionProps } from './motion.ts';
 export { default as motion, MotionModifier } from './motion.ts';
 export type { MotionConfigContext } from './motion-config.gts';

package/bundled-types/glimmer-motion/memory.ts

@@ -0,0 +1,302 @@
+/**
+ * A memory: an element that has left, kept on screen for as long as its exit
+ * plays. `<Presence @mode="snapshot">` keeps a copy of its leaver as one, and
+ * a layer that parks removed elements itself (Choreo's orphan layer) keeps
+ * each element it parks as one, so a leaver looks and behaves the same
+ * whichever layer let it go.
+ *
+ * A memory shows the frame its element last showed, and nothing in it acts:
+ *
+ * - Its CSS animations hold still. An element put back in the document
+ *   restarts every stylesheet animation on it, so an entrance that had
+ *   finished would play again while the element leaves. Each animation the
+ *   element was showing pauses at the time it had reached, and any other (one
+ *   that had finished, or one the re-insertion started) jumps to its end.
+ *   Animations on a scroll timeline follow the restored scroll offsets. The
+ *   engine's own animations are not stylesheet animations, and are left
+ *   alone.
+ * - Its scroll offsets are restored: an element taken out of the document
+ *   loses them.
+ * - Its backdrop filters are off. A backdrop filter re-samples whatever is
+ *   behind it on every frame, at full price inside a moving, fading element,
+ *   and what is behind a memory is the scene that replaced it.
+ * - It is composited as one texture (`will-change: transform, opacity`).
+ *   That also makes it a stacking context, and the containing block of every
+ *   positioned descendant, `position: fixed` included: a descendant that was
+ *   placed against a box outside the element is placed against the memory.
+ * - It is inert and hidden from assistive technology.
+ * - Its HTML elements carry no ids, `autofocus` or form-control names. A
+ *   duplicate id that comes first in the document is what `getElementById`
+ *   and `<label for>` find, and a checked radio button joining the document
+ *   unchecks the live one in its group. Its SVG elements keep their ids,
+ *   which its own fills, clips, masks and `<use>` references resolve through.
+ *   A reference resolves to the first element in the document with its id,
+ *   so while a memory comes before its replacement (as one in Choreo's orphan
+ *   layer, its region's first child, does), the replacement's `url(#id)` and
+ *   `<use>` references resolve to the memory's definitions. Definitions that
+ *   change as their element is replaced need an id per version. Its iframes
+ *   are blank, and its media neither plays nor loads.
+ * - Its test hooks carry a suffix: `data-test-title` becomes
+ *   `data-test-title-memory`, with its value. A test's selector finds only the
+ *   live element, which is what replaced the leaver or nothing, and a test that
+ *   means the leaver names it with the suffix. `live()` and `liveAll()` in
+ *   `glimmer-motion/test-support` skip memories for every other selector.
+ * - Its classes and its other attributes stay, so it looks as its element
+ *   did wherever its styles are keyed on them. A rule keyed on an id
+ *   (`#panel`, `:target`) no longer reaches it, so an element that may leave
+ *   is styled by class. A memory put back in its parent (a
+ *   `<Presence @mode="snapshot">` copy) therefore still matches structural
+ *   selectors that read the live scene: `:has()`, `+`, `~`, `:nth-child()`,
+ *   `:empty`. A rule that should see only live content excludes it, as in
+ *   `:has(.menu:not([data-motion-memory], [data-motion-memory] *))`.
+ *
+ * Custom elements in a memory are connected again, and run their
+ * `connectedCallback`.
+ */
+
+/** the attribute every memory carries */
+export const MEMORY_ATTRIBUTE = 'data-motion-memory';
+
+/** what a memory's `data-test-*` hooks are renamed with */
+export const MEMORY_HOOK_SUFFIX = '-memory';
+
+export interface ScrollPosition {
+  left: number;
+  top: number;
+}
+
+/** a CSS animation on the document timeline that an element was showing */
+export interface ShownAnimation {
+  finished: boolean;
+  /** its `animation-name` */
+  name: string;
+  /** the pseudo-element it runs on, or null for the element itself */
+  pseudoElement: string | null;
+  /** its current time, in milliseconds */
+  time: number;
+}
+
+/** what a subtree showed before the render that removed it, for its memory to show */
+export interface Shown {
+  /** the CSS animations each element was showing */
+  animations: { get(el: Element): readonly ShownAnimation[] | undefined };
+  /** each element's scroll offset */
+  scrolls: { get(el: Element): ScrollPosition | undefined };
+}
+
+/** form controls whose name would join a live radio group or form submission */
+const NAMED_CONTROLS =
+  'input, select, textarea, button, fieldset, output, object, form, iframe';
+
+/** the element and every element inside it, in document order */
+export function elementsOf(root: Element): Element[] {
+  return [root, ...root.querySelectorAll('*')];
+}
+
+/** a stylesheet animation on the document timeline: a scroll-driven one follows its scroller instead */
+function onDocumentTimeline(animation: Animation): animation is CSSAnimation {
+  return (
+    animation instanceof CSSAnimation &&
+    animation.timeline === document.timeline
+  );
+}
+
+/**
+ * The CSS animations on the document timeline that `root` and the elements
+ * inside it are showing, by the element each runs on. Read it while `root` is
+ * still in the document: a removed element has none.
+ */
+export function readAnimations(root: Element): Map<Element, ShownAnimation[]> {
+  const shown = new Map<Element, ShownAnimation[]>();
+  for (const animation of root.getAnimations({ subtree: true })) {
+    const effect = animation.effect;
+    if (
+      !onDocumentTimeline(animation) ||
+      !(effect instanceof KeyframeEffect) ||
+      !effect.target
+    ) {
+      continue;
+    }
+    const list = shown.get(effect.target) ?? [];
+    list.push({
+      finished: animation.playState === 'finished',
+      name: animation.animationName,
+      pseudoElement: effect.pseudoElement,
+      time: Number(animation.currentTime ?? 0),
+    });
+    shown.set(effect.target, list);
+  }
+  return shown;
+}
+
+/** the scroll offsets of `root` and of every element inside it that is scrolled */
+export function readScrolls(root: Element): Map<Element, ScrollPosition> {
+  const scrolls = new Map<Element, ScrollPosition>();
+  for (const el of elementsOf(root)) {
+    if (el.scrollTop || el.scrollLeft) {
+      scrolls.set(el, { top: el.scrollTop, left: el.scrollLeft });
+    }
+  }
+  return scrolls;
+}
+
+/** what `root` shows now. Read it while `root` is still in the document. */
+export function readShown(root: Element): Shown {
+  return { animations: readAnimations(root), scrolls: readScrolls(root) };
+}
+
+/** what `original` showed, moved onto the matching elements of `copy`, a deep clone of it */
+export function shownOnCopy(
+  shown: Shown,
+  original: Element,
+  copy: Element,
+): Shown {
+  const from = elementsOf(original);
+  const to = elementsOf(copy);
+  const animations = new Map<Element, readonly ShownAnimation[]>();
+  const scrolls = new Map<Element, ScrollPosition>();
+  from.forEach((el, i) => {
+    const counterpart = to[i];
+    if (!counterpart) {
+      return;
+    }
+    const animation = shown.animations.get(el);
+    if (animation) {
+      animations.set(counterpart, animation);
+    }
+    const scroll = shown.scrolls.get(el);
+    if (scroll) {
+      scrolls.set(counterpart, scroll);
+    }
+  });
+  return { animations, scrolls };
+}
+
+/**
+ * Records the scroll offset of every element inside `root` as it scrolls. For
+ * a layer that learns which elements left only after the render that removed
+ * them, by when their offsets are gone.
+ */
+export function trackScrolls(root: Element): {
+  scrolls: Shown['scrolls'];
+  stop(): void;
+} {
+  const scrolls = new WeakMap<Element, ScrollPosition>();
+  const record = (event: Event) => {
+    const el = event.target;
+    if (el instanceof Element) {
+      scrolls.set(el, { top: el.scrollTop, left: el.scrollLeft });
+    }
+  };
+  // scroll events do not bubble, but they do pass ancestors while capturing
+  root.addEventListener('scroll', record, { capture: true, passive: true });
+  return {
+    scrolls,
+    stop: () => root.removeEventListener('scroll', record, { capture: true }),
+  };
+}
+
+let memoryStyle: HTMLStyleElement | undefined;
+
+function ensureMemoryStyle() {
+  if (memoryStyle?.isConnected) {
+    return;
+  }
+  const m = `[${MEMORY_ATTRIBUTE}]`;
+  memoryStyle = document.createElement('style');
+  memoryStyle.setAttribute('data-motion-memory-style', '');
+  memoryStyle.textContent =
+    `${m},${m}::before,${m}::after,${m} *,${m} *::before,${m} *::after` +
+    '{backdrop-filter:none!important;-webkit-backdrop-filter:none!important}';
+  document.head.appendChild(memoryStyle);
+}
+
+/** nothing in a memory can be found by id or test hook, submitted, focused, loaded or played */
+function neutralize(el: Element) {
+  for (const name of el.getAttributeNames()) {
+    if (name === 'data-test' || name.startsWith('data-test-')) {
+      el.setAttribute(`${name}${MEMORY_HOOK_SUFFIX}`, el.getAttribute(name)!);
+      el.removeAttribute(name);
+    }
+  }
+  if (!(el instanceof SVGElement)) {
+    el.removeAttribute('id');
+  }
+  el.removeAttribute('autofocus');
+  if (el.matches(NAMED_CONTROLS)) {
+    el.removeAttribute('name');
+  }
+  if (el instanceof HTMLIFrameElement) {
+    el.removeAttribute('srcdoc');
+    el.src = 'about:blank';
+  } else if (el instanceof HTMLMediaElement) {
+    el.removeAttribute('autoplay');
+    el.preload = 'none';
+  }
+}
+
+/** each stylesheet animation pauses where it was shown, or jumps to its end */
+function holdAnimations(root: Element, shown: Shown['animations']) {
+  for (const animation of root.getAnimations({ subtree: true })) {
+    const effect = animation.effect;
+    if (!onDocumentTimeline(animation) || !(effect instanceof KeyframeEffect)) {
+      continue;
+    }
+    const was = effect.target
+      ? shown
+          .get(effect.target)
+          ?.find(
+            (a) =>
+              a.name === animation.animationName &&
+              a.pseudoElement === effect.pseudoElement,
+          )
+      : undefined;
+    try {
+      if (was && !was.finished) {
+        animation.pause();
+        animation.currentTime = was.time;
+      } else {
+        animation.finish();
+      }
+    } catch {
+      // an endless animation has no end to jump to
+      animation.cancel();
+    }
+  }
+}
+
+/**
+ * Makes `root` a memory of what `shown` describes, and puts it back in the
+ * document with `insert`. Ids, form-control names and test hooks are changed
+ * before `insert` runs, so none of them joins the document even for a moment;
+ * scroll offsets and animations are restored after it, in the same task, so
+ * no frame shows them reset. Whatever is already in a memory (a leaver lifted
+ * out of one that left with it, a copy still fading inside a leaver) is put
+ * back and restored, and not changed twice.
+ */
+export function keepAsMemory(
+  root: HTMLElement | SVGElement,
+  shown: Shown,
+  insert: () => void,
+) {
+  ensureMemoryStyle();
+  const elements = elementsOf(root);
+  for (const el of elements) {
+    if (!el.closest(`[${MEMORY_ATTRIBUTE}]`)) {
+      neutralize(el);
+    }
+  }
+  root.setAttribute(MEMORY_ATTRIBUTE, '');
+  root.setAttribute('inert', '');
+  root.setAttribute('aria-hidden', 'true');
+  root.style.willChange = 'transform, opacity';
+  insert();
+  for (const el of elements) {
+    const scroll = shown.scrolls.get(el);
+    if (scroll) {
+      el.scrollTop = scroll.top;
+      el.scrollLeft = scroll.left;
+    }
+  }
+  holdAnimations(root, shown.animations);
+}

package/bundled-types/glimmer-motion/node.ts

@@ -37,6 +37,7 @@ import {
   SVGVisualElement,
   visualElementStore,
 } from 'motion-dom';
+import { MotionGlobalConfig } from 'motion-utils';
 
 import { registerBusyProbe } from './activity.ts';
 import { initFeatures } from './features.ts';
@@ -65,6 +66,19 @@ import { postRender } from './scheduler.ts';
 import { motionSpeed, onMotionSpeed, slowed } from './speed.ts';
 import { styleValue } from './unitless.ts';
 
+/**
+ * The values motion-dom can hand to the browser to play (its
+ * `acceleratedValues`), each with the property its computed style shows it
+ * under. While the browser plays one, its motion value does not follow frame
+ * by frame.
+ */
+const BROWSER_PLAYED: Record<string, string> = {
+  opacity: 'opacity',
+  clipPath: 'clip-path',
+  filter: 'filter',
+  transform: 'transform',
+};
+
 /** motion-dom's own `defaultLayoutTransition`, which it does not export */
 const DEFAULT_LAYOUT_TRANSITION = {
   duration: 0.45,
@@ -272,7 +286,7 @@ const pendingPops: { apply: () => void }[] = [];
 let popFlushBooked = false;
 
 /** where a popLayout leaver is sitting, and the box it has to be pinned inside */
-interface PopSeat {
+export interface PopSeat {
   h: number;
   isRTL: boolean;
   left: number;
@@ -282,7 +296,29 @@ interface PopSeat {
   w: number;
 }
 
-function seatOf(el: MotionEl): PopSeat | undefined {
+/**
+ * The two insets that pin a box lifted out of flow to its seat: one inline,
+ * from the side `anchorX` names (mirrored in right-to-left text), and one
+ * block, from the side `anchorY` names.
+ */
+export function seatInsets(
+  seat: PopSeat,
+  anchorX: 'left' | 'right',
+  anchorY: 'top' | 'bottom',
+): {
+  block: ['top' | 'bottom', number];
+  inline: ['left' | 'right', number];
+} {
+  const { w, h, top, left, parentWidth, parentHeight, isRTL } = seat;
+  const fromLeft = (anchorX === 'left') !== isRTL;
+  return {
+    inline: fromLeft ? ['left', left] : ['right', parentWidth - w - left],
+    block:
+      anchorY === 'bottom' ? ['bottom', parentHeight - h - top] : ['top', top],
+  };
+}
+
+export function seatOf(el: MotionEl): PopSeat | undefined {
   const parent = (el as HTMLElement).offsetParent as HTMLElement | null;
   const cs = getComputedStyle(el);
   const w = parseFloat(cs.width),
@@ -618,6 +654,8 @@ export class MotionNode implements MotionParticipant, PopMeasurable {
   private popStyle?: HTMLStyleElement;
   /** the seat measured before the render that removed this element */
   private popSeat?: PopSeat;
+  /** snapshot: the seat this element had in the last frame (see recordSeat) */
+  private shownSeat?: PopSeat;
   private unregisterPop?: () => void;
   /** participant identity: a participant host above selects this element by these */
   id: string | null = null;
@@ -1326,6 +1364,87 @@ export class MotionNode implements MotionParticipant, PopMeasurable {
     }
   }
 
+  /**
+   * `<Presence @mode="snapshot">`: reads the seat this element has now, for
+   * the copy of it to be pinned to if it leaves. <Presence> calls this in each
+   * frame that follows a render, and whenever this element or the box it is
+   * pinned inside resizes. That covers the moves a render or a resize makes;
+   * a move that is neither, such as a transition on a sibling's width that
+   * shifts this element without resizing either box, leaves the seat where it
+   * was. Returns the elements the seat depends on, for <Presence> to watch
+   * for resizes.
+   */
+  recordSeat(): Element[] {
+    const el = this.element;
+    if (this.destroyed || !el?.isConnected) {
+      return [];
+    }
+    this.shownSeat = seatOf(el);
+    const parent = (el as HTMLElement).offsetParent;
+    return parent ? [el, parent] : [el];
+  }
+
+  /**
+   * `<Presence @mode="snapshot">`: what a static copy of this element needs to
+   * play the exit this element would have played. <Presence> reads it from
+   * its diff, before the render that removes the element.
+   *
+   * `seat` is the one recorded before this render (see recordSeat). By the
+   * time the diff runs, content earlier in the template has already been
+   * patched for this render, and may have moved the element somewhere no
+   * frame showed it.
+   *
+   * The copy starts from every value this element shows now. The browser
+   * plays some of them (opacity, clip-path, filter, a whole transform), and a
+   * motion value does not follow those frame by frame, so those are read from
+   * the computed style. The copy inherits nothing from the variant tree: the
+   * tree it would inherit from has already moved on.
+   *
+   * Undefined when there is no exit to play: the element declares no `exit`
+   * of its own, has not mounted, or animations are skipped.
+   */
+  exitForCopy():
+    | { element: MotionEl; props: MotionProps; seat: PopSeat | undefined }
+    | undefined {
+    const { element, ve, latest } = this;
+    if (this.destroyed || !element?.isConnected || !ve?.current || !latest) {
+      return undefined;
+    }
+    const props = latest.props as MotionProps;
+    if (
+      props.exit === undefined ||
+      this.config.skipAnimations ||
+      MotionGlobalConfig.skipAnimations ||
+      MotionGlobalConfig.instantAnimations
+    ) {
+      return undefined;
+    }
+    const computed = getComputedStyle(element);
+    const initial: Record<string, string | number> = {};
+    ve.values.forEach((value, key) => {
+      const css = BROWSER_PLAYED[key];
+      if (css) {
+        const shown = computed.getPropertyValue(css);
+        initial[key] = key === 'opacity' ? parseFloat(shown) : shown;
+      } else {
+        initial[key] = value.get() as string | number;
+      }
+    });
+    return {
+      element,
+      seat: this.shownSeat,
+      props: {
+        initial,
+        exit: props.exit,
+        variants: props.variants,
+        transition: props.transition,
+        custom: props.custom,
+        transformTemplate: props.transformTemplate,
+        inherit: false,
+      },
+    };
+  }
+
   /** popLayout: a leaving element is lifted out of flow at its last box so siblings can close up */
   private pop(el: MotionEl, isPresent: boolean, handle: PresenceHandle) {
     if (isPresent) {
@@ -1342,18 +1461,10 @@ export class MotionNode implements MotionParticipant, PopMeasurable {
     if (!seat) {
       return;
     }
-    const { w, h, top, left, parentWidth, parentHeight, isRTL } = seat;
-    const right = parentWidth - w - left,
-      bottom = parentHeight - h - top;
-    const x =
-      handle.anchorX === 'left'
-        ? isRTL
-          ? `right:${right}`
-          : `left:${left}`
-        : isRTL
-          ? `left:${left}`
-          : `right:${right}`;
-    const y = handle.anchorY === 'bottom' ? `bottom:${bottom}` : `top:${top}`;
+    const { w, h } = seat;
+    const { inline, block } = seatInsets(seat, handle.anchorX, handle.anchorY);
+    const x = `${inline[0]}:${inline[1]}`;
+    const y = `${block[0]}:${block[1]}`;
     const id = `pop-${Math.random().toString(36).slice(2, 8)}`;
     el.dataset['motionPopId'] = id;
     // measured above against the layout as it stands; the lift itself waits

package/bundled-types/glimmer-motion/presence-types.ts

@@ -1,12 +1,20 @@
 import type { PresenceContextProps } from 'motion-dom';
 
+import type { MotionEl, MotionProps, PopSeat } from './node.ts';
+
 /**
- * A direct child of a popLayout <Presence>, which has to be measured before
- * the render that removes it. React's PopChildMeasure does this in
- * getSnapshotBeforeUpdate; see MotionNode.measureForPop.
+ * A direct child of a <Presence>, which has to be read before the render
+ * that removes it: popLayout measures its seat (React's PopChildMeasure does
+ * this in getSnapshotBeforeUpdate; see MotionNode.measureForPop), and
+ * snapshot copies it (see MotionNode.exitForCopy), pinning the copy to the
+ * seat recorded before that render (see MotionNode.recordSeat).
  */
 export interface PopMeasurable {
+  exitForCopy():
+    | { element: MotionEl; props: MotionProps; seat: PopSeat | undefined }
+    | undefined;
   measureForPop(): void;
+  recordSeat(): Element[];
 }
 
 /** what one item inside <Presence> hands to its {{motion}} element */
@@ -16,8 +24,8 @@ export interface PresenceHandle {
   readonly context: PresenceContextProps;
   readonly isPresent: boolean;
   readonly key: string;
-  readonly mode: 'sync' | 'wait' | 'popLayout';
-  /** popLayout: the direct child asks to be measured while it is still in flow */
+  readonly mode: 'sync' | 'wait' | 'popLayout' | 'snapshot';
+  /** popLayout and snapshot: the direct child asks to be read while it is still in flow */
   popCandidate(node: PopMeasurable): () => void;
   /** motion elements that inherit this presence (React: PresenceContext consumers) ask to be refreshed when it flips */
   subscribe(refresh: () => void): () => void;