@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/dist/motion/animator.js

@@ -4,7 +4,7 @@
  * @file animator.ts
  * @input An element, target values, and a spring, momentum curves (coast.ts)
  *   or any closed-form curve
- * @output Exports `createMotionAnimator`, a compositor animator for
+ * @output Exports `createMotionEngine`, a compositor animator for
  *   translate, rotate, scale and opacity, and its option, handle and
  *   transition types. It reads presentation values and velocities from the
  *   analytic curves. It retargets with the velocity kept, freezes in place on
@@ -214,10 +214,11 @@ import { themeReducesMotion } from "../privateAttributes/reducedMotion.stylex.js
  * the property's presentation value (`get`) to continue without a jump.
  */
 
+/** How `set` puts values in place. */
+
 /**
- * Options of `createMotionAnimator`.
+ * Options of `createMotionEngine`.
  */
-/** How `set` puts values in place. */
 
 /**
  * One `animate` / `decay` call's animations.
@@ -428,7 +429,7 @@ export function animatorFor(element, options = {}) {
   const key = options.pseudoElement ?? '';
   let animator = byPseudo.get(key);
   if (animator == null) {
-    animator = createMotionAnimator(element, options);
+    animator = createMotionEngine(element, options);
     byPseudo.set(key, animator);
   }
   return animator;
@@ -532,7 +533,7 @@ const REDUCED_TRANSITION = {
  *
  * @example
  * ```
- * const animator = createMotionAnimator(sheet);
+ * const animator = createMotionEngine(sheet);
  * // finger lifts at 1200 px/s heading for the detent at 0 (a component
  * // passes the spring of its motion role):
  * animator.animate({y: 0}, {spring: {response: 0.45, dampingRatio: 0.9}, velocity: {y: 1200}});
@@ -541,7 +542,7 @@ const REDUCED_TRANSITION = {
  * animator.stop(['y']);
  * ```
  */
-export function createMotionAnimator(element, options = {}) {
+export function createMotionEngine(element, options = {}) {
   const now = options.now ?? defaultNow;
   const frameSource = options.requestFrame ?? (typeof requestAnimationFrame === 'function' ? callback => {
     requestAnimationFrame(() => callback());

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"}

package/dist/motion/transientCopy.js

@@ -15,9 +15,12 @@
  * technology, carries no ids or test ids, joins no form or radio group (a
  * copied checked radio would uncheck the live one), and its frames and media
  * load nothing. Laying it out changes no ancestor's position, and a scaled
- * host draws it at the old size. Laid in a host outside the element's own
- * ancestors, it keeps what it inherited from them: its inherited properties
- * and custom properties that differ from the host's are written on it.
+ * host draws it at the old size. A clone restarts each CSS animation and runs
+ * no transition but a `@starting-style` one; the copy carries on its
+ * element's from where they were.
+ * Laid in a host outside the element's own ancestors, it keeps what it
+ * inherited from them: its inherited properties and custom properties that
+ * differ from the host's are written on it.
  * Limits: a rule keyed on a removed `id`, or matched through an ancestor
  * between the host and the element (`.collapsed .label`), does not style the
  * copy as it styled the element; and content holding a canvas whose pixels read back
@@ -28,6 +31,8 @@
  * SYNC: When modified, update /packages/core/src/motion/animatedLayout.ts
  */
 
+import { carryAnimations, saveAnimations } from "./carryAnimations.js";
+
 /** Above this many elements, old content is not copied: the new one enters. */
 const MAX_COPIED_ELEMENTS = 1500;
 
@@ -115,11 +120,19 @@ function readInherited(element) {
 /** Scroll offsets a copy restores once laid out (a clone carries none). */
 const scrollOffsets = new WeakMap();
 
+/**
+ * The CSS animations and transitions a copy's element ran, and the copy of
+ * each element in the copied subtree. The copy carries them on once laid out
+ * (`placeOver`).
+ */
+const carriedMotion = new WeakMap();
+
 /**
  * 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 function inertCopy(element) {
   const copy = element.cloneNode(true);
@@ -133,6 +146,10 @@ export function inertCopy(element) {
   });
   scrollOffsets.set(copy, offsets);
   inheritedValues.set(copy, readInherited(element));
+  carriedMotion.set(copy, {
+    saved: saveAnimations(element),
+    copyOf: new Map(sourceNodes.map((node, index) => [node, copyNodes[index]]))
+  });
   for (const node of copyNodes) {
     for (const name of ['id', 'data-testid', 'name', 'form', 'for', 'autofocus']) {
       node.removeAttribute(name);
@@ -170,7 +187,8 @@ export function paintedBackground(element) {
 /**
  * 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 function placeOver(element, host, rect) {
   Object.assign(element.style, {
@@ -221,6 +239,11 @@ export function placeOver(element, host, rect) {
       node.scrollLeft = left;
     }
   }
+  const carried = carriedMotion.get(element);
+  if (carried != null) {
+    carriedMotion.delete(element);
+    carryAnimations(carried.saved, element, node => carried.copyOf.get(node) ?? null);
+  }
 }
 
 /**
@@ -264,6 +287,12 @@ export function visiblePartCopy(element) {
   if (values != null) {
     inheritedValues.set(holder, values);
   }
+  // The content's CSS motion carries on when the holder is laid out.
+  const carried = carriedMotion.get(content);
+  if (carried != null) {
+    carriedMotion.set(holder, carried);
+    carriedMotion.delete(content);
+  }
   const box = element.getBoundingClientRect();
   return {
     copy: holder,

package/dist/motion/uikit/gestures.d.ts

@@ -253,6 +253,29 @@ export declare const UIKIT_PRESS: {
         readonly unit: "ms";
     };
 };
+/**
+ * UIMenu presented by a button whose menu is its primary action: how far the
+ * finger that opened it travels before it picks. DropdownMenu's press model
+ * reads a copy in `hooks/menuPressValues.ts`.
+ */
+export declare const UIKIT_MENU_PRESS: {
+    /**
+     * After the menu opens under a still-held finger, the finger travels this
+     * far before it starts picking. The distance is a straight line from the
+     * first sample the menu receives after it opened. Until then nothing is
+     * lit, and lifting acts on nothing.
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, gesture-state hook, steps 150 ms apart, Oct 23 2026
+     *   (M-MN2): with the menu open under a held finger and a 1 pt first step,
+     *   moves of (0, 9) and (7, 7) picked nothing; (0, 10), (0, 11), (10, 0),
+     *   (9, 9) and (10, 10) picked; a 9 pt step followed by 3 pt more picked
+     *   nothing
+     */
+    readonly handoff: {
+        readonly value: 10;
+        readonly unit: "px";
+    };
+};
 export declare const UIKIT_VELOCITY: {
     /**
      * UIPanGestureRecognizer.velocity(in:) is this times the newest event's
@@ -567,6 +590,24 @@ export declare const UIKIT_GESTURES: {
             readonly unit: "ms";
         };
     };
+    readonly menuPress: {
+        /**
+         * After the menu opens under a still-held finger, the finger travels this
+         * far before it starts picking. The distance is a straight line from the
+         * first sample the menu receives after it opened. Until then nothing is
+         * lit, and lifting acts on nothing.
+         * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+         *   iPhone 17 Pro, gesture-state hook, steps 150 ms apart, Oct 23 2026
+         *   (M-MN2): with the menu open under a held finger and a 1 pt first step,
+         *   moves of (0, 9) and (7, 7) picked nothing; (0, 10), (0, 11), (10, 0),
+         *   (9, 9) and (10, 10) picked; a 9 pt step followed by 3 pt more picked
+         *   nothing
+         */
+        readonly handoff: {
+            readonly value: 10;
+            readonly unit: "px";
+        };
+    };
     readonly velocity: {
         /**
          * UIPanGestureRecognizer.velocity(in:) is this times the newest event's

package/dist/motion/uikit/gestures.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gestures.d.ts","sourceRoot":"","sources":["../../../src/motion/uikit/gestures.ts"],"names":[],"mappings":"AAgDA,MAAM,MAAM,mBAAmB,GAC7B,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,MAAM;IACzC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;CACpC;AAED,eAAO,MAAM,SAAS;IACpB;;;;;;;OAOG;;;;;IAEH;;;;;OAKG;;;;;IAEH;;;;;;OAMG;;;;;IAEH;;;;;OAKG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,gBAAgB;IAC3B;;;;;;OAMG;;;;;IAEH;;;;;;OAMG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,SAAS;IACpB;;;;;;;;;;OAUG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,WAAW;IACtB;;;;;OAKG;;;;;IAEH;;;;;OAKG;;;;;IAEH;;;;;OAKG;;;;;IAEH;;;;;;OAMG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,WAAW;IACtB;;;;;;;OAOG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,cAAc;IACzB;;;;;;OAMG;;;;;CAG+C,CAAC;AAErD,eAAO,MAAM,qBAAqB;IAChC;;;;;;OAMG;;;;;IAEH;;;;OAIG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,aAAa;IACxB;;;;;;;OAOG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,WAAW;IACtB;;;;;OAKG;;;;;IAEH;;;;;OAKG;;;;;IAEH;;;;;;OAMG;;;;;IAEH;;;;;OAKG;;;;;IAEH;;;;;;OAMG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,cAAc;IACzB;;;;;;;;;;;;OAYG;;;;;IAEH;;;;;;;;OAQG;;;;;IAEH;;;;;;;OAOG;;;;;CAE+C,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,WAAW;IACtB;;;;OAIG;;;;;CAE+C,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;QAzPzB;;;;;;;WAOG;;;;;QAEH;;;;;WAKG;;;;;QAEH;;;;;;WAMG;;;;;QAEH;;;;;WAKG;;;;;;;QAKH;;;;;;WAMG;;;;;QAEH;;;;;;WAMG;;;;;;;QAKH;;;;;;;;;;WAUG;;;;;;;QAKH;;;;;WAKG;;;;;QAEH;;;;;WAKG;;;;;QAEH;;;;;WAKG;;;;;QAEH;;;;;;WAMG;;;;;;;QAKH;;;;;;;WAOG;;;;;;;QAKH;;;;;;WAMG;;;;;;;QAMH;;;;;;WAMG;;;;;QAEH;;;;WAIG;;;;;;;QAKH;;;;;;;WAOG;;;;;;;QAKH;;;;;WAKG;;;;;QAEH;;;;;WAKG;;;;;QAEH;;;;;;WAMG;;;;;QAEH;;;;;WAKG;;;;;QAEH;;;;;;WAMG;;;;;;;QAKH;;;;;;;;;;;;WAYG;;;;;QAEH;;;;;;;;WAQG;;;;;QAEH;;;;;;;WAOG;;;;;;CAoCK,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,sKAUxB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAC5C,kBAAkB,EAClB,eAAe,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAWvC,CAAC"}
+{"version":3,"file":"gestures.d.ts","sourceRoot":"","sources":["../../../src/motion/uikit/gestures.ts"],"names":[],"mappings":"AAgDA,MAAM,MAAM,mBAAmB,GAC7B,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,MAAM;IACzC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;CACpC;AAED,eAAO,MAAM,SAAS;IACpB;;;;;;;OAOG;;;;;IAEH;;;;;OAKG;;;;;IAEH;;;;;;OAMG;;;;;IAEH;;;;;OAKG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,gBAAgB;IAC3B;;;;;;OAMG;;;;;IAEH;;;;;;OAMG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,SAAS;IACpB;;;;;;;;;;OAUG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,WAAW;IACtB;;;;;OAKG;;;;;IAEH;;;;;OAKG;;;;;IAEH;;;;;OAKG;;;;;IAEH;;;;;;OAMG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,WAAW;IACtB;;;;;;;OAOG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,cAAc;IACzB;;;;;;OAMG;;;;;CAG+C,CAAC;AAErD,eAAO,MAAM,qBAAqB;IAChC;;;;;;OAMG;;;;;IAEH;;;;OAIG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,aAAa;IACxB;;;;;;;OAOG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,WAAW;IACtB;;;;;OAKG;;;;;IAEH;;;;;OAKG;;;;;IAEH;;;;;;OAMG;;;;;IAEH;;;;;OAKG;;;;;IAEH;;;;;;OAMG;;;;;CAE+C,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;;;;;;;;;OAWG;;;;;CAE+C,CAAC;AAErD,eAAO,MAAM,cAAc;IACzB;;;;;;;;;;;;OAYG;;;;;IAEH;;;;;;;;OAQG;;;;;IAEH;;;;;;;OAOG;;;;;CAE+C,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,WAAW;IACtB;;;;OAIG;;;;;CAE+C,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;QA9QzB;;;;;;;WAOG;;;;;QAEH;;;;;WAKG;;;;;QAEH;;;;;;WAMG;;;;;QAEH;;;;;WAKG;;;;;;;QAKH;;;;;;WAMG;;;;;QAEH;;;;;;WAMG;;;;;;;QAKH;;;;;;;;;;WAUG;;;;;;;QAKH;;;;;WAKG;;;;;QAEH;;;;;WAKG;;;;;QAEH;;;;;WAKG;;;;;QAEH;;;;;;WAMG;;;;;;;QAKH;;;;;;;WAOG;;;;;;;QAKH;;;;;;WAMG;;;;;;;QAMH;;;;;;WAMG;;;;;QAEH;;;;WAIG;;;;;;;QAKH;;;;;;;WAOG;;;;;;;QAKH;;;;;WAKG;;;;;QAEH;;;;;WAKG;;;;;QAEH;;;;;;WAMG;;;;;QAEH;;;;;WAKG;;;;;QAEH;;;;;;WAMG;;;;;;;QAUH;;;;;;;;;;;WAWG;;;;;;;QAKH;;;;;;;;;;;;WAYG;;;;;QAEH;;;;;;;;WAQG;;;;;QAEH;;;;;;;WAOG;;;;;;CAqCK,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,sKAUxB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAC5C,kBAAkB,EAClB,eAAe,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAWvC,CAAC"}

package/dist/motion/uikit/gestures.js

@@ -295,6 +295,30 @@ export const UIKIT_PRESS = {
     unit: 'ms'
   }
 };
+
+/**
+ * UIMenu presented by a button whose menu is its primary action: how far the
+ * finger that opened it travels before it picks. DropdownMenu's press model
+ * reads a copy in `hooks/menuPressValues.ts`.
+ */
+export const UIKIT_MENU_PRESS = {
+  /**
+   * After the menu opens under a still-held finger, the finger travels this
+   * far before it starts picking. The distance is a straight line from the
+   * first sample the menu receives after it opened. Until then nothing is
+   * lit, and lifting acts on nothing.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, gesture-state hook, steps 150 ms apart, Oct 23 2026
+   *   (M-MN2): with the menu open under a held finger and a 1 pt first step,
+   *   moves of (0, 9) and (7, 7) picked nothing; (0, 10), (0, 11), (10, 0),
+   *   (9, 9) and (10, 10) picked; a 9 pt step followed by 3 pt more picked
+   *   nothing
+   */
+  handoff: {
+    value: 10,
+    unit: 'px'
+  }
+};
 export const UIKIT_VELOCITY = {
   /**
    * UIPanGestureRecognizer.velocity(in:) is this times the newest event's
@@ -374,6 +398,7 @@ export const UIKIT_GESTURES = {
   screenEdgePan: UIKIT_SCREEN_EDGE_PAN,
   control: UIKIT_CONTROL,
   press: UIKIT_PRESS,
+  menuPress: UIKIT_MENU_PRESS,
   velocity: UIKIT_VELOCITY
 };
 

package/dist/motion/uikit/index.d.ts

@@ -17,7 +17,7 @@
  * SYNC: When a domain file is added, re-export it here and list it in
  * /packages/core/src/motion/README.md.
  */
-export { HAPTIC_FEEDBACK_KINDS, HAPTIC_VIBRATION_PATTERNS, UIKIT_CLICK, UIKIT_CONTROL, UIKIT_GESTURES, UIKIT_LONG_PRESS, UIKIT_PAN, UIKIT_PINCH, UIKIT_PRESS, UIKIT_ROTATION, UIKIT_SCREEN_EDGE_PAN, UIKIT_SWIPE, UIKIT_TAP, UIKIT_VELOCITY, type GestureConstant, type GestureConstantUnit, type HapticFeedbackKind, } from './gestures.js';
+export { HAPTIC_FEEDBACK_KINDS, HAPTIC_VIBRATION_PATTERNS, UIKIT_CLICK, UIKIT_CONTROL, UIKIT_GESTURES, UIKIT_LONG_PRESS, UIKIT_MENU_PRESS, UIKIT_PAN, UIKIT_PINCH, UIKIT_PRESS, UIKIT_ROTATION, UIKIT_SCREEN_EDGE_PAN, UIKIT_SWIPE, UIKIT_TAP, UIKIT_VELOCITY, type GestureConstant, type GestureConstantUnit, type HapticFeedbackKind, } from './gestures.js';
 export { datePicker } from './datePicker.js';
 export { navigation, registerNavigationTable } from './navigation.js';
 export { picker } from './picker.js';

package/dist/motion/uikit/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/motion/uikit/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,WAAW,EACX,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,SAAS,EACT,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AACxC,OAAO,EAAC,UAAU,EAAE,uBAAuB,EAAC,MAAM,cAAc,CAAC;AACjE,OAAO,EAAC,MAAM,EAAC,MAAM,UAAU,CAAC;AAChC,OAAO,EAAC,WAAW,EAAE,wBAAwB,EAAC,MAAM,eAAe,CAAC;AACpE,OAAO,EAAC,mBAAmB,EAAE,MAAM,EAAC,MAAM,UAAU,CAAC;AACrD,OAAO,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAC,MAAM,EAAC,MAAM,UAAU,CAAC;AAChC,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACb,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,EACf,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,0BAA0B,EAC1B,8BAA8B,EAC9B,wCAAwC,EACxC,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,yBAAyB,EACzB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,OAAO,GACR,MAAM,WAAW,CAAC;AACnB,OAAO,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AACvC,OAAO,EAAC,mBAAmB,EAAE,MAAM,EAAC,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/motion/uikit/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACT,WAAW,EACX,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,SAAS,EACT,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AACxC,OAAO,EAAC,UAAU,EAAE,uBAAuB,EAAC,MAAM,cAAc,CAAC;AACjE,OAAO,EAAC,MAAM,EAAC,MAAM,UAAU,CAAC;AAChC,OAAO,EAAC,WAAW,EAAE,wBAAwB,EAAC,MAAM,eAAe,CAAC;AACpE,OAAO,EAAC,mBAAmB,EAAE,MAAM,EAAC,MAAM,UAAU,CAAC;AACrD,OAAO,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAC,MAAM,EAAC,MAAM,UAAU,CAAC;AAChC,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACb,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,EACf,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,0BAA0B,EAC1B,8BAA8B,EAC9B,wCAAwC,EACxC,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,yBAAyB,EACzB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,OAAO,GACR,MAAM,WAAW,CAAC;AACnB,OAAO,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AACvC,OAAO,EAAC,mBAAmB,EAAE,MAAM,EAAC,MAAM,UAAU,CAAC"}