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

package/src/motion/README.md

@@ -69,7 +69,7 @@ the timings that decide who gets a touch are not roles.
 ## Animator
 
 ```
-import {createMotionAnimator} from '../motion/animator';
+import {createMotionEngine} from '../motion/animator';
 import {coast} from '../motion/coast';
 import {solveSpringTowardRamp, toSpring} from '../motion/spring';
 import {resolveMotion} from '../motion/resolveMotion';
@@ -78,7 +78,7 @@ import {registerSpringsTable, springs} from '../motion/uikit';
 // Once, so the springs are registered as their roles:
 registerSpringsTable();
 
-const animator = createMotionAnimator(sheet);
+const animator = createMotionEngine(sheet);
 // The animator plays a motion role (spec:AST-094 FR4), its table value, as the
 // per-role tables stay internal (DEC-15); math on a spring reads the role with
 // resolveMotion.
@@ -175,7 +175,7 @@ await handle.finished; // true if it ran to the end, false if interrupted
 - `animatorFor(element)` returns the one animator for an element, so code
   that animates it from several places (a swipe on x, a removal on y)
   composes in one `translate` track.
-- `createMotionAnimator(dialog, {pseudoElement: '::backdrop'})` drives a
+- `createMotionEngine(dialog, {pseudoElement: '::backdrop'})` drives a
   pseudo-element; with no inline style to hold it, a static filling animation
   holds its end value until the next animation replaces it, while the
   pseudo-element exists. A dialog's `::backdrop` is made again each time the

package/src/motion/animator.ts

@@ -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
@@ -299,9 +299,6 @@ export interface MotionCurve {
   readonly isTransition?: boolean;
 }
 
-/**
- * Options of `createMotionAnimator`.
- */
 /** How `set` puts values in place. */
 export interface SetOptions {
   /**
@@ -317,6 +314,9 @@ export interface SetOptions {
   promote?: boolean;
 }
 
+/**
+ * Options of `createMotionEngine`.
+ */
 export interface AnimatorOptions {
   /**
    * Animates a pseudo-element of the element instead (`'::backdrop'` of a
@@ -811,7 +811,7 @@ export function animatorFor(
   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;
@@ -928,7 +928,7 @@ const REDUCED_TRANSITION: SpringTransition = {
  *
  * @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}});
@@ -937,7 +937,7 @@ const REDUCED_TRANSITION: SpringTransition = {
  * animator.stop(['y']);
  * ```
  */
-export function createMotionAnimator(
+export function createMotionEngine(
   element: HTMLElement | null,
   options: AnimatorOptions = {},
 ): Animator {

package/src/motion/carryAnimations.ts

@@ -0,0 +1,389 @@
+// 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',
+]);
+
+type Writable = Record<string, unknown>;
+
+/** Every accessor with a setter on `object`'s prototype chain. */
+function writableAccessors(object: object): string[] {
+  const names = new Set<string>();
+  for (
+    let proto: object | null = 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: unknown): string | null {
+  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: unknown, b: unknown): boolean {
+  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. */
+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 function saveAnimation(animation: Animation): SavedAnimation {
+  const effect = animation.effect as KeyframeEffect | null;
+  const values: Writable = {};
+  for (const name of writableAccessors(animation)) {
+    values[name] = (animation as unknown as Writable)[name];
+  }
+  const effectValues: Writable = {};
+  if (effect != null) {
+    for (const name of writableAccessors(effect)) {
+      effectValues[name] = (effect as unknown as Writable)[name];
+    }
+  }
+  return {
+    animation,
+    name:
+      (animation as Animation & {animationName?: string}).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: object, name: string, value: unknown): void {
+  (object as Writable)[name] = value;
+}
+
+/** Give `next` the effect state `saved` had: every writable member. */
+function restoreEffect(next: KeyframeEffect, saved: SavedAnimation): void {
+  for (const name of writableAccessors(next)) {
+    if (
+      name in saved.effectValues &&
+      differs(saved.effectValues[name], (next as unknown as Writable)[name])
+    ) {
+      write(next, name, saved.effectValues[name]);
+    }
+  }
+  if (saved.timing != null) {
+    const timing = next.getTiming() as unknown as Writable;
+    const changed: Writable = {};
+    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: Animation, saved: SavedAnimation): void {
+  const effect = next.effect as KeyframeEffect | null;
+  if (effect != null) {
+    restoreEffect(effect, saved);
+  }
+  const current = next as unknown as Writable;
+  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 as CSSNumberish | null | undefined;
+  const time = saved.values.currentTime as CSSNumberish | null | undefined;
+  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: SavedAnimation): void {
+  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: Animation): boolean {
+  return (
+    typeof CSSTransition !== 'undefined' && animation instanceof CSSTransition
+  );
+}
+
+function isCssAnimation(animation: Animation): animation is CSSAnimation {
+  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: Animation): void {
+  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: SavedAnimation,
+  copyOf: (element: Element) => Element | null,
+): SavedAnimation | null {
+  const target = saved.target == null ? null : copyOf(saved.target);
+  if (target == null) {
+    return null;
+  }
+  const values: Writable = Object.fromEntries(
+    Object.entries(saved.values).filter(
+      ([name]) => !IDENTITY_MEMBERS.has(name),
+    ),
+  );
+  const effectValues: Writable = {...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: Element,
+  saved: ReadonlyArray<SavedAnimation>,
+  survivors: ReadonlySet<Animation>,
+): void {
+  const after = root.getAnimations({subtree: true});
+  const current = new Set(after);
+  const cancelled: SavedAnimation[] = [];
+  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: Animation[] = [];
+  for (const animation of recreated) {
+    const effect = animation.effect as KeyframeEffect | null;
+    const name =
+      (animation as Animation & {animationName?: string}).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 as Animation & {animationName?: string}).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. */
+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 function saveAnimations(root: Element): SavedAnimations {
+  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: SavedAnimations,
+  copy: Element,
+  copyOf: (element: Element) => Element | null,
+): void {
+  if (typeof copy.getAnimations !== 'function') {
+    return;
+  }
+  restoreAnimations(
+    copy,
+    saved.flatMap(state => retarget(state, copyOf) ?? []),
+    new Set(),
+  );
+}

package/src/motion/transientCopy.ts

@@ -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,12 @@
  * SYNC: When modified, update /packages/core/src/motion/animatedLayout.ts
  */
 
+import {
+  carryAnimations,
+  saveAnimations,
+  type SavedAnimations,
+} from './carryAnimations';
+
 /** Above this many elements, old content is not copied: the new one enters. */
 const MAX_COPIED_ELEMENTS = 1500;
 
@@ -151,11 +160,22 @@ const scrollOffsets = new WeakMap<
   ReadonlyArray<readonly [Element, number, number]>
 >();
 
+/**
+ * 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<
+  HTMLElement,
+  {saved: SavedAnimations; copyOf: ReadonlyMap<Element, Element>}
+>();
+
 /**
  * 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: HTMLElement): HTMLElement | null {
   const copy = element.cloneNode(true) as HTMLElement;
@@ -169,6 +189,10 @@ export function inertCopy(element: HTMLElement): HTMLElement | null {
   });
   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',
@@ -215,7 +239,8 @@ export 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 function placeOver(
   element: HTMLElement,
@@ -277,6 +302,15 @@ export function placeOver(
       node.scrollLeft = left;
     }
   }
+  const carried = carriedMotion.get(element);
+  if (carried != null) {
+    carriedMotion.delete(element);
+    carryAnimations(
+      carried.saved,
+      element,
+      node => carried.copyOf.get(node) ?? null,
+    );
+  }
 }
 
 /**
@@ -323,6 +357,12 @@ export function visiblePartCopy(element: HTMLElement): {
   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/src/motion/uikit/gestures.ts

@@ -251,6 +251,27 @@ export const UIKIT_PRESS = {
   momentumMemory: {value: 3000, unit: 'ms'},
 } as const satisfies Record<string, GestureConstant>;
 
+/**
+ * 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'},
+} as const satisfies Record<string, GestureConstant>;
+
 export const UIKIT_VELOCITY = {
   /**
    * UIPanGestureRecognizer.velocity(in:) is this times the newest event's
@@ -318,6 +339,7 @@ export const UIKIT_GESTURES = {
   screenEdgePan: UIKIT_SCREEN_EDGE_PAN,
   control: UIKIT_CONTROL,
   press: UIKIT_PRESS,
+  menuPress: UIKIT_MENU_PRESS,
   velocity: UIKIT_VELOCITY,
 } as const;
 

package/src/motion/uikit/index.ts

@@ -27,6 +27,7 @@ export {
   UIKIT_CONTROL,
   UIKIT_GESTURES,
   UIKIT_LONG_PRESS,
+  UIKIT_MENU_PRESS,
   UIKIT_PAN,
   UIKIT_PINCH,
   UIKIT_PRESS,

package/src/motion/uikit/timing.ts

@@ -50,17 +50,19 @@ export const press = {
    */
   flashMs: 100,
   /**
-   * Highlight fade after release: UIKit's deselect cross-fade.
+   * Highlight fade after release: UIKit's deselect cross-fade. Reference
+   * only, not played: a press release plays the theme's exit motion tokens
+   * (`--duration-exit`, `--ease-exit`).
    * @source measured: Settings and Contacts, iOS 26.2, simulator driven
-   *   with real HID touches at 60 fps (PRESS_FADE_MS / pressConsts.releaseMs,
+   *   with real HID touches at 60 fps (touch press model,
    *   packages/core/src/utils/pressGesture.ts, 2026-10-06)
    */
   highlightOutMs: 200,
   /**
    * The highlight fade's curve after release: an ease-out that spends the
-   * whole clock fading (strength about 0.2 at the midpoint).
-   * @source GUESS — the release curve the touch press model ships with
-   *   (`RELEASE_EASE`, packages/core/src/utils/interactionOverlay.stylex.ts),
+   * whole clock fading (strength about 0.2 at the midpoint). Reference only,
+   * not played: a press release plays the theme's `--ease-exit`.
+   * @source GUESS — the release curve the touch press model shipped with,
    *   chosen to read as UIKit's deselect cross-fade, not read from UIKit
    * @measure M-PR1
    */