@astryxdesign/core 0.7.8 → 0.7.9-canary.048476f

package/dist/hooks/useMenuPress.js

@@ -6,7 +6,8 @@
  * @file useMenuPress.ts
  * @input The menu root, its trigger, the enabled-row selector, and callbacks
  *   for opening, highlighting, activating and dismissing
- * @output useMenuPress, the marker attributes, and the activation mark
+ * @output useMenuPress, the marker attributes, the activation mark, and the
+ *   internal useDropdownMenuPress entry with its touch model
  * @position Core hook for DropdownMenu, ContextMenu, DropdownMenuSubMenu,
  *   Selector and MenuBottomSheetActionList. The transition table lives in
  *   menuPressGesture.ts.
@@ -19,13 +20,14 @@
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { currentGesture } from "../Layer/gestureCounter.js";
-import { IDLE_MENU_PRESS, menuPressStep } from "./menuPressGesture.js";
+import { IDLE_MENU_PRESS, menuPressTransition } from "./menuPressGesture.js";
 import { MENU_PRESS_MARKER } from "./menuPressMarker.js";
 import { useLongPressDetector } from "./useLongPress.js";
 import { edgeAutoscroll } from "../utils/edgeAutoscroll.js";
 import { focusForLastInput } from "../utils/focusReturn.js";
 import { useInteractionModalityTrackingFor } from "../utils/interactionModality.js";
 import { LONG_PRESS_DURATION_MS } from "../motion/uikit/longPress.js";
+import { clearMenuPressLit, holdMenuPressPaint, markMenuPressLit, releaseMenuPressPaint } from "../privateAttributes/menuPressLit.stylex.js";
 import { __resetClickGuardForTest, armClickGuard, CLICK_GUARD_WINDOW_MS, withoutClickGuard } from "../utils/clickGuard.js";
 export { MENU_PRESS_MARKER };
 const MENU_PRESS_ROOT_SELECTOR = `[${MENU_PRESS_MARKER}]`;
@@ -124,6 +126,34 @@ function isInMenuTree(element, root) {
   const owner = element.closest(MENU_PRESS_ROOT_SELECTOR);
   return owner != null && getOutermostRoot(owner) === root;
 }
+
+/**
+ * DropdownMenu's options for the press model: everything the public hook
+ * takes, plus its touch model. DropdownMenu reaches the touch model through
+ * its `presentation`, so the public hook has no such option.
+ *
+ * @internal
+ */
+
+/**
+ * What core's own menus get from {@link useDropdownMenuPress}: the public
+ * return. Not exported from the hooks entry point.
+ *
+ * @internal
+ */
+
+/**
+ * Where a pointer is, for a finger's handoff distance. Positions reach the
+ * machine only under `touchModel: 'uikit'`. Without them, it keeps the settle
+ * rule.
+ */
+function handoffPosition(event, hasHandoff) {
+  return hasHandoff ? {
+    x: event.clientX,
+    y: event.clientY
+  } : {};
+}
+
 /**
  * The press model for a menu: the row under the release acts, the highlight
  * follows a held pointer, and a mouse opens the menu on press.
@@ -160,6 +190,26 @@ function isInMenuTree(element, root) {
  * ```
  */
 export function useMenuPress(options) {
+  // The touch model is DropdownMenu's alone; an untyped caller's
+  // `touchModel` does not reach the model.
+  const {
+    touchModel: _touchModel,
+    ...publicOptions
+  } = options;
+  return useDropdownMenuPress({
+    ...publicOptions,
+    touchModel: 'pointer'
+  });
+}
+
+/**
+ * The press model with DropdownMenu's touch model
+ * ({@link DropdownMenuPressOptions.touchModel}). Not exported from the hooks
+ * entry point.
+ *
+ * @internal
+ */
+export function useDropdownMenuPress(options) {
   const optionsRef = useRef(options);
   optionsRef.current = options;
   // The highlight, and the hover focus of the rows in this menu, follow the
@@ -247,8 +297,18 @@ export function useMenuPress(options) {
     autoscroll.stop();
     autoscrollRef.current = null;
   }, [autoscroll]);
+  const litRowRef = useRef(null);
+  const heldMenuRef = useRef(null);
   const endGesture = useCallback(() => {
     longPressApiRef.current?.cancel();
+    if (litRowRef.current != null) {
+      clearMenuPressLit(litRowRef.current);
+      litRowRef.current = null;
+    }
+    if (heldMenuRef.current != null) {
+      releaseMenuPressPaint(heldMenuRef.current);
+      heldMenuRef.current = null;
+    }
     touchMovePreventerRef.current?.();
     touchMovePreventerRef.current = null;
     stopAutoscroll();
@@ -259,10 +319,36 @@ export function useMenuPress(options) {
     gestureRef.current = IDLE_MENU_PRESS;
   }, [stopAutoscroll]);
   const highlight = useCallback(row => {
+    // A held finger or pen marks the row it lights, for the row's pressed
+    // paint. A held mouse keeps the hover tint, as on a desktop.
+    const gesture = gestureRef.current;
+    const isHeld = gesture.phase !== 'idle' && gesture.pointerType !== 'mouse';
+    const lit = isHeld ? row : null;
+    if (litRowRef.current !== lit) {
+      if (litRowRef.current != null) {
+        clearMenuPressLit(litRowRef.current);
+      }
+      litRowRef.current = lit;
+      if (lit != null) {
+        markMenuPressLit(lit);
+      }
+    }
     const {
       onHighlight,
       menuRef
     } = optionsRef.current;
+    // The row the press began on stays :active where a pointer hovers, so
+    // the menu holds every row but the lit one off that paint.
+    const held = isHeld ? menuRef.current : null;
+    if (heldMenuRef.current !== held) {
+      if (heldMenuRef.current != null) {
+        releaseMenuPressPaint(heldMenuRef.current);
+      }
+      heldMenuRef.current = held;
+      if (held != null) {
+        holdMenuPressPaint(held);
+      }
+    }
     if (onHighlight != null) {
       onHighlight(row);
       return;
@@ -369,7 +455,7 @@ export function useMenuPress(options) {
     }
   }, [activate, endGesture, getDocument, highlight]);
   const step = useCallback((event, native) => {
-    const result = menuPressStep(gestureRef.current, event);
+    const result = menuPressTransition(gestureRef.current, event);
     gestureRef.current = result.gesture;
     applyEffect(result.effect, result.gesture, native);
   }, [applyEffect]);
@@ -466,7 +552,8 @@ export function useMenuPress(options) {
         type: 'move',
         row: point.row,
         isInMenu: point.isInMenu,
-        time: Date.now()
+        time: Date.now(),
+        ...handoffPosition(event, optionsRef.current.touchModel === 'uikit')
       }, event);
       updateAutoscroll(event);
     };
@@ -480,7 +567,8 @@ export function useMenuPress(options) {
         row: point.row,
         isInMenu: point.isInMenu,
         isOnTrigger: point.isOnTrigger,
-        time: Date.now()
+        time: Date.now(),
+        ...handoffPosition(event, optionsRef.current.touchModel === 'uikit')
       }, event);
     };
     const onCancel = event => {

package/dist/hooks/usePressFeedback.d.ts

@@ -7,11 +7,11 @@ import { pressableProps } from '../utils/pressFeedback.js';
  * `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same
  * element: `backgroundColor` or `backgroundImage` for a surface whose hover
  * and press are the system's overlays, `pressedBackgroundColor` for one
- * whose hover is its own. The controller writes its attribute on the element
- * while a touch press is believed (after the onset delay, cancelled by travel
- * or by a scroll) and for the release, and the composed style paints the
- * pressed token at the press's strength on the first frame and fades it over
- * the release, keeping `:active` for a mouse on a desktop. On a phone or
+ * whose hover is its own. Under a finger the controller tracks the press the
+ * way UIKit tracks a control and writes its
+ * attribute on the element while the press is held and for the release; the
+ * composed style paints the pressed token on the first frame and fades it
+ * over the release, keeping `:active` for a mouse on a desktop. On a phone or
  * tablet the stylesheet drops `:active` for every press, so the controller
  * also paints a mouse, trackpad or Space-key press there, at once. A press is
  * themed through `--color-overlay-pressed`, which the hold, the flash and the
@@ -27,7 +27,7 @@ import { pressableProps } from '../utils/pressFeedback.js';
  * @example
  * ```
  * const pressable = usePressFeedback();
- * return <div role="button" {...pressable} {...stylex.props(styles.row)} />;
+ * return <button {...pressable} {...stylex.props(styles.button)} />;
  * ```
  */
 export declare function usePressFeedback(): typeof pressableProps;

package/dist/hooks/usePressFeedback.js

@@ -25,11 +25,11 @@ import { installPressFeedback, pressableProps } from "../utils/pressFeedback.js"
  * `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same
  * element: `backgroundColor` or `backgroundImage` for a surface whose hover
  * and press are the system's overlays, `pressedBackgroundColor` for one
- * whose hover is its own. The controller writes its attribute on the element
- * while a touch press is believed (after the onset delay, cancelled by travel
- * or by a scroll) and for the release, and the composed style paints the
- * pressed token at the press's strength on the first frame and fades it over
- * the release, keeping `:active` for a mouse on a desktop. On a phone or
+ * whose hover is its own. Under a finger the controller tracks the press the
+ * way UIKit tracks a control and writes its
+ * attribute on the element while the press is held and for the release; the
+ * composed style paints the pressed token on the first frame and fades it
+ * over the release, keeping `:active` for a mouse on a desktop. On a phone or
  * tablet the stylesheet drops `:active` for every press, so the controller
  * also paints a mouse, trackpad or Space-key press there, at once. A press is
  * themed through `--color-overlay-pressed`, which the hold, the flash and the
@@ -45,7 +45,7 @@ import { installPressFeedback, pressableProps } from "../utils/pressFeedback.js"
  * @example
  * ```
  * const pressable = usePressFeedback();
- * return <div role="button" {...pressable} {...stylex.props(styles.row)} />;
+ * return <button {...pressable} {...stylex.props(styles.button)} />;
  * ```
  */
 export function usePressFeedback() {

package/dist/motion/carryAnimations.d.ts

@@ -0,0 +1,58 @@
+type Writable = Record<string, unknown>;
+/** One animation's state, read before the browser starts it afresh. */
+export interface SavedAnimation {
+    animation: Animation;
+    name: string;
+    target: Element | null;
+    pseudoElement: string | null;
+    values: Writable;
+    effectValues: Writable;
+    timing: EffectTiming | null;
+    keyframes: ComputedKeyframe[] | null;
+    playState: AnimationPlayState;
+    replaceState: AnimationReplaceState;
+}
+/**
+ * Reads one animation's state generically, from what the platform exposes.
+ * That is every accessor with a setter on the animation's and its effect's
+ * prototype chains, every field of the effect's timing, and its keyframes. Only values
+ * that differ from the recreated animation's are written back, so a value the
+ * stylesheet controls stays under its control. A few members are not plain
+ * state and are written in their own step (`ORDERED`). The Animation and
+ * effect objects themselves cannot be carried over: the old ones keep their
+ * listeners and promises.
+ */
+export declare function saveAnimation(animation: Animation): SavedAnimation;
+/**
+ * Puts each state `saved` holds on the CSS animations and transitions of
+ * `root` and its subtree that are not among `survivors`. Each CSS animation
+ * the browser started afresh takes the state of the one it replaces. It is
+ * matched by element, pseudo-element and name, in order, and then by name
+ * alone (an effect script moved to another element or pseudo-element). Each
+ * transition whose animation no longer runs resumes as a script animation in
+ * its state. One started afresh that replaces none is finished: an entrance
+ * that had played and been dropped, or a transition from `@starting-style`.
+ * Script animations are left as they are.
+ */
+export declare function restoreAnimations(root: Element, saved: ReadonlyArray<SavedAnimation>, survivors: ReadonlySet<Animation>): void;
+/** The CSS animations and transitions `saveAnimations` read. */
+export type SavedAnimations = ReadonlyArray<SavedAnimation>;
+/**
+ * Reads the state of every CSS animation and transition of `root` and its
+ * subtree, for `carryAnimations` to give a copy of it.
+ */
+export declare function saveAnimations(root: Element): SavedAnimations;
+/**
+ * Carries on in `copy`, a clone of the root `saved` was read from, now laid
+ * out, the CSS animations and transitions its element ran. A clone starts
+ * each CSS animation again and runs no transition but a `@starting-style`
+ * one. So each CSS animation the clone started takes the state of its
+ * element's, and each transition runs on as a script animation. One the
+ * clone started that its element no longer ran is finished: an entrance that
+ * had played, or a `@starting-style` transition. `copyOf` maps each element
+ * of the cloned subtree to its copy. The element's own animations keep
+ * running, so the copy's take no id or event handler.
+ */
+export declare function carryAnimations(saved: SavedAnimations, copy: Element, copyOf: (element: Element) => Element | null): void;
+export {};
+//# sourceMappingURL=carryAnimations.d.ts.map

package/dist/motion/carryAnimations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carryAnimations.d.ts","sourceRoot":"","sources":["../../src/motion/carryAnimations.ts"],"names":[],"mappings":"AA+BA,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAsDxC,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,QAAQ,CAAC;IACjB,YAAY,EAAE,QAAQ,CAAC;IACvB,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IACrC,SAAS,EAAE,kBAAkB,CAAC;IAC9B,YAAY,EAAE,qBAAqB,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,cAAc,CAyBlE;AAsJD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,aAAa,CAAC,cAAc,CAAC,EACpC,SAAS,EAAE,WAAW,CAAC,SAAS,CAAC,GAChC,IAAI,CA8CN;AAED,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,CAQ7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAG,IAAI,GAC3C,IAAI,CASN"}

package/dist/motion/carryAnimations.js

@@ -0,0 +1,305 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file carryAnimations.ts
+ * @input The CSS animations and transitions of an element and its subtree,
+ *   read before the browser starts them afresh
+ * @output Exports `saveAnimations` and `carryAnimations`, which carry them on
+ *   in a clone of the element. Also `saveAnimation` and `restoreAnimations`,
+ *   which put them back after a display reset
+ * @position Motion foundation; the transient copy (transientCopy.ts) and the
+ *   layer runtime's re-placement (Layer/preserveAnimations.ts) use it
+ */
+
+/**
+ * Animation members written in a fixed order rather than generically: the
+ * timeline before the range that is measured on it, the rate before the
+ * time, and the start time (or, for a paused animation, the current time)
+ * last, once the play state is set. `effect` is not
+ * replaced, because a CSS animation whose effect script replaces leaves the
+ * stylesheet's control; its state is copied onto the new effect instead.
+ */
+const ORDERED = new Set(['effect', 'timeline', 'rangeStart', 'rangeEnd', 'playbackRate', 'startTime', 'currentTime']);
+/** Every accessor with a setter on `object`'s prototype chain. */
+function writableAccessors(object) {
+  const names = new Set();
+  for (let proto = Object.getPrototypeOf(object); proto != null && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+    for (const [name, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(proto))) {
+      if (descriptor.set != null) {
+        names.add(name);
+      }
+    }
+  }
+  return [...names];
+}
+
+/**
+ * A textual form of a value that is compared by content rather than by
+ * identity: a CSS numeric value (as in a timeline range offset) through its
+ * serialization, a plain object (a range) through its members. Anything else
+ * is compared by identity (`null`).
+ */
+function contentOf(value) {
+  if (typeof CSSNumericValue !== 'undefined' && value instanceof CSSNumericValue) {
+    return value.toString();
+  }
+  if (value != null && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+    return Object.entries(value).map(([key, inner]) => `${key}:${contentOf(inner) ?? String(inner)}`).join(';');
+  }
+  return null;
+}
+function differs(a, b) {
+  if (a === b) {
+    return false;
+  }
+  const textA = contentOf(a);
+  return textA == null || textA !== contentOf(b);
+}
+
+/** One animation's state, read before the browser starts it afresh. */
+
+/**
+ * Reads one animation's state generically, from what the platform exposes.
+ * That is every accessor with a setter on the animation's and its effect's
+ * prototype chains, every field of the effect's timing, and its keyframes. Only values
+ * that differ from the recreated animation's are written back, so a value the
+ * stylesheet controls stays under its control. A few members are not plain
+ * state and are written in their own step (`ORDERED`). The Animation and
+ * effect objects themselves cannot be carried over: the old ones keep their
+ * listeners and promises.
+ */
+export function saveAnimation(animation) {
+  const effect = animation.effect;
+  const values = {};
+  for (const name of writableAccessors(animation)) {
+    values[name] = animation[name];
+  }
+  const effectValues = {};
+  if (effect != null) {
+    for (const name of writableAccessors(effect)) {
+      effectValues[name] = effect[name];
+    }
+  }
+  return {
+    animation,
+    name: animation.animationName ?? '',
+    target: effect?.target ?? null,
+    pseudoElement: effect?.pseudoElement ?? null,
+    values,
+    effectValues,
+    timing: effect?.getTiming() ?? null,
+    keyframes: effect?.getKeyframes() ?? null,
+    playState: animation.playState,
+    replaceState: animation.replaceState
+  };
+}
+function write(object, name, value) {
+  object[name] = value;
+}
+
+/** Give `next` the effect state `saved` had: every writable member. */
+function restoreEffect(next, saved) {
+  for (const name of writableAccessors(next)) {
+    if (name in saved.effectValues && differs(saved.effectValues[name], next[name])) {
+      write(next, name, saved.effectValues[name]);
+    }
+  }
+  if (saved.timing != null) {
+    const timing = next.getTiming();
+    const changed = {};
+    for (const [field, value] of Object.entries(saved.timing)) {
+      if (differs(value, timing[field])) {
+        changed[field] = value;
+      }
+    }
+    if (Object.keys(changed).length > 0) {
+      next.updateTiming(changed);
+    }
+  }
+  if (saved.keyframes != null && JSON.stringify(saved.keyframes) !== JSON.stringify(next.getKeyframes())) {
+    next.setKeyframes(saved.keyframes);
+  }
+}
+
+/** Give `next` the state `saved` had, member by member. */
+function restore(next, saved) {
+  const effect = next.effect;
+  if (effect != null) {
+    restoreEffect(effect, saved);
+  }
+  const current = next;
+  for (const name of ['timeline', 'rangeStart', 'rangeEnd']) {
+    if (name in saved.values && differs(saved.values[name], current[name])) {
+      write(next, name, saved.values[name]);
+    }
+  }
+  for (const name of writableAccessors(next)) {
+    if (!ORDERED.has(name) && name in saved.values && differs(saved.values[name], current[name])) {
+      write(next, name, saved.values[name]);
+    }
+  }
+  if (saved.replaceState === 'persisted' && next.replaceState !== 'persisted') {
+    next.persist();
+  }
+  const rate = saved.values.playbackRate;
+  if (typeof rate === 'number' && rate !== next.playbackRate) {
+    next.playbackRate = rate;
+  }
+  if (saved.playState === 'paused' && next.playState !== 'paused') {
+    next.pause();
+  } else if (saved.playState !== 'paused' && next.playState === 'paused') {
+    next.play();
+  }
+  // A running animation is anchored to its timeline by its start time, which
+  // carries its current time on exactly. A paused one has none and keeps its
+  // current time. A finished one holds its end: finishing it again holds the
+  // same time, though its start time is then counted from now, since script
+  // cannot set a start time and a held time together.
+  const start = saved.values.startTime;
+  const time = saved.values.currentTime;
+  if (saved.playState === 'finished') {
+    next.finish();
+  } else if (start != null) {
+    next.startTime = start;
+  } else if (time != null) {
+    next.currentTime = time;
+  }
+}
+
+/** Resume a cancelled CSS transition with a script animation in its state. */
+function resumeTransition(saved) {
+  if (saved.target == null || saved.keyframes == null) {
+    return;
+  }
+  const replacement = saved.target.animate(saved.keyframes, {
+    pseudoElement: saved.pseudoElement ?? undefined
+  });
+  restore(replacement, saved);
+}
+function isTransition(animation) {
+  return typeof CSSTransition !== 'undefined' && animation instanceof CSSTransition;
+}
+function isCssAnimation(animation) {
+  return typeof CSSAnimation !== 'undefined' && animation instanceof CSSAnimation;
+}
+
+/**
+ * Finishes an animation that ends: an infinite one cannot be finished, and is
+ * left as it runs.
+ */
+function finishIfItEnds(animation) {
+  const end = animation.effect?.getComputedTiming().endTime;
+  if (end != null && Number.isFinite(Number(end)) && animation.playbackRate !== 0) {
+    animation.finish();
+  }
+}
+
+/** The members a copy's animation does not take: its element's keep them. */
+const IDENTITY_MEMBERS = new Set(['id', 'onfinish', 'oncancel', 'onremove']);
+
+/**
+ * `saved` for an animation that carries on on the copy of its element:
+ * aimed at the copy, without the element's id and event handlers.
+ */
+function retarget(saved, copyOf) {
+  const target = saved.target == null ? null : copyOf(saved.target);
+  if (target == null) {
+    return null;
+  }
+  const values = Object.fromEntries(Object.entries(saved.values).filter(([name]) => !IDENTITY_MEMBERS.has(name)));
+  const effectValues = {
+    ...saved.effectValues
+  };
+  if ('target' in effectValues) {
+    effectValues.target = target;
+  }
+  return {
+    ...saved,
+    target,
+    values,
+    effectValues
+  };
+}
+
+/**
+ * Puts each state `saved` holds on the CSS animations and transitions of
+ * `root` and its subtree that are not among `survivors`. Each CSS animation
+ * the browser started afresh takes the state of the one it replaces. It is
+ * matched by element, pseudo-element and name, in order, and then by name
+ * alone (an effect script moved to another element or pseudo-element). Each
+ * transition whose animation no longer runs resumes as a script animation in
+ * its state. One started afresh that replaces none is finished: an entrance
+ * that had played and been dropped, or a transition from `@starting-style`.
+ * Script animations are left as they are.
+ */
+export function restoreAnimations(root, saved, survivors) {
+  const after = root.getAnimations({
+    subtree: true
+  });
+  const current = new Set(after);
+  const cancelled = [];
+  for (const state of saved) {
+    if (current.has(state.animation)) {
+      continue;
+    }
+    if (isTransition(state.animation)) {
+      resumeTransition(state);
+    } else {
+      cancelled.push(state);
+    }
+  }
+  const recreated = after.filter(animation => (isCssAnimation(animation) || isTransition(animation)) && !survivors.has(animation));
+  const unmatched = [];
+  for (const animation of recreated) {
+    const effect = animation.effect;
+    const name = animation.animationName ?? '';
+    const index = cancelled.findIndex(state => state.name === name && state.target === (effect?.target ?? null) && state.pseudoElement === (effect?.pseudoElement ?? null));
+    if (index === -1) {
+      unmatched.push(animation);
+    } else {
+      restore(animation, cancelled.splice(index, 1)[0]);
+    }
+  }
+  for (const animation of unmatched) {
+    const name = animation.animationName ?? '';
+    const index = cancelled.findIndex(state => state.name === name);
+    if (index === -1) {
+      finishIfItEnds(animation);
+    } else {
+      restore(animation, cancelled.splice(index, 1)[0]);
+    }
+  }
+}
+
+/** The CSS animations and transitions `saveAnimations` read. */
+
+/**
+ * Reads the state of every CSS animation and transition of `root` and its
+ * subtree, for `carryAnimations` to give a copy of it.
+ */
+export function saveAnimations(root) {
+  if (typeof root.getAnimations !== 'function') {
+    return [];
+  }
+  return root.getAnimations({
+    subtree: true
+  }).filter(animation => isCssAnimation(animation) || isTransition(animation)).map(saveAnimation);
+}
+
+/**
+ * Carries on in `copy`, a clone of the root `saved` was read from, now laid
+ * out, the CSS animations and transitions its element ran. A clone starts
+ * each CSS animation again and runs no transition but a `@starting-style`
+ * one. So each CSS animation the clone started takes the state of its
+ * element's, and each transition runs on as a script animation. One the
+ * clone started that its element no longer ran is finished: an entrance that
+ * had played, or a `@starting-style` transition. `copyOf` maps each element
+ * of the cloned subtree to its copy. The element's own animations keep
+ * running, so the copy's take no id or event handler.
+ */
+export function carryAnimations(saved, copy, copyOf) {
+  if (typeof copy.getAnimations !== 'function') {
+    return;
+  }
+  restoreAnimations(copy, saved.flatMap(state => retarget(state, copyOf) ?? []), new Set());
+}

package/dist/motion/transientCopy.d.ts

@@ -4,7 +4,8 @@ export declare function isCopyable(element: Element): boolean;
  * A copy that takes no part: no ids or test ids, no form or radio group (a
  * copied checked radio would uncheck the live one), no label for a live
  * control, and copied frames and media load nothing. Scrolled descendants
- * keep their offsets once the copy is laid out (`placeOver`).
+ * keep their offsets. The CSS animations and transitions running in it carry
+ * on from where they were, once the copy is laid out (`placeOver`).
  */
 export declare function inertCopy(element: HTMLElement): HTMLElement | null;
 /** The background `element` shows: its own, or the nearest ancestor's. */
@@ -12,7 +13,8 @@ export declare function paintedBackground(element: Element): string;
 /**
  * Lay `element` over `rect` (viewport coordinates), absolutely, as the last
  * child of `host`, wherever its containing block is: no ancestor's position
- * changes.
+ * changes. A copy's scrolled descendants then restore their offsets, and the
+ * CSS animations and transitions its element ran carry on in it.
  */
 export declare function placeOver(element: HTMLElement, host: Element, rect: DOMRect): void;
 /**

package/dist/motion/transientCopy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transientCopy.d.ts","sourceRoot":"","sources":["../../src/motion/transientCopy.ts"],"names":[],"mappings":"AAiCA,iDAAiD;AACjD,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEpD;AAqHD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CA0ClE;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAQ1D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,OAAO,GACZ,IAAI,CAwDN;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG;IACrD,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,IAAI,CA8CP;AAID;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,EAAE,CA6BrD"}
+{"version":3,"file":"transientCopy.d.ts","sourceRoot":"","sources":["../../src/motion/transientCopy.ts"],"names":[],"mappings":"AA0CA,iDAAiD;AACjD,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEpD;AA+HD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CA8ClE;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAQ1D;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,OAAO,GACZ,IAAI,CAiEN;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG;IACrD,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,IAAI,CAoDP;AAID;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,EAAE,CA6BrD"}