@astryxdesign/core 0.7.8 → 0.7.9-canary.0a64fdb

package/src/hooks/usePressFeedback.doc.mjs

@@ -20,12 +20,12 @@ export const docs = {
       name: 'pressableProps',
       type: "{'data-astryx-pressable': ''}",
       description:
-        "The marker attribute to spread on the element that paints the press. Compose one of `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 — and it paints the pressed token at the press's strength on the first frame of a believed press and fades it over the release, keeping `:active` for a mouse on a desktop. On a phone or tablet, where the stylesheet drops `:active`, the controller also paints a mouse, trackpad or Space-key press: at once, held while the button or key is down, faded at the release. A press is themed through `--color-overlay-pressed`.",
+        "The marker attribute to spread on the element that paints the press. Compose one of `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 — and it paints the pressed token on the first frame of a press and fades it over the release, keeping `:active` for a mouse on a desktop. On a phone or tablet, where the stylesheet drops `:active`, the controller also paints a mouse, trackpad or Space-key press: at once, held while the button or key is down, faded at the release. A press is themed through `--color-overlay-pressed`.",
     },
   ],
   usage: {
     description:
-      'The touch press model every Astryx pressable uses, for a local component that paints its own press. Under a finger, CSS `:active` paints on the touch itself and can outlive the start of a scroll; the press model instead waits 150 ms before believing a press, cancels it the moment the finger travels 10 px or a scroll claims the gesture, never brings it back inside that gesture, answers a quick tap at the lift, and fades the release over 200 ms — the clocks a native list uses. One document-level controller does this for every marked element (installed by the first pressable to mount, removed by the last to unmount), so calling the hook adds no listener or state to your element. On a desktop a mouse press is still your `:active` rule: keep it, and drop it under `@media (pointer: coarse)` the way the built-in components do. That query reads the primary pointer, so on a phone or tablet it also drops `:active` for a connected mouse, trackpad or keyboard; the controller paints those presses there (at once, faded at the release), so nothing goes unanswered.',
+      'The touch press model every Astryx pressable uses, for a local component that paints its own press. Under a finger, CSS `:active` paints on the touch itself and can outlive the start of a scroll; the press model instead tracks the touch the way UIKit tracks a control: it highlights as the finger lands (after the content-touch delay inside a scroller, where a flick paints nothing), a quick tap answers at the lift, and a scroll that takes the touch cancels it with no fade. One document-level controller does this for every marked element (installed by the first pressable to mount, removed by the last to unmount), so calling the hook adds no listener or state to your element. On a desktop a mouse press is still your `:active` rule: keep it, and drop it under `@media (pointer: coarse)` the way the built-in components do. That query reads the primary pointer, so on a phone or tablet it also drops `:active` for a connected mouse, trackpad or keyboard; the controller paints those presses there (at once, faded at the release), so nothing goes unanswered.',
     bestPractices: [
       {
         guidance: true,
@@ -58,7 +58,7 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Marks an element as a pressable surface of the touch press model (150 ms onset, 10 px slop, cancel on scroll, tap answers at lift, 200 ms fade) and installs the shared document controller; on a coarse primary pointer it also paints mouse, trackpad and Space-key presses at once. Returns the data-astryx-pressable marker to spread; compose one of interactionOverlayStyles on the same element to paint.',
+    'Marks an element as a pressable surface of the touch press model, tracked like a UIKit control (highlight as the finger lands, 150 ms inside a scroller, fade at the lift), and installs the shared document controller; on a coarse primary pointer it also paints mouse, trackpad and Space-key presses at once. Returns the data-astryx-pressable marker to spread; compose one of interactionOverlayStyles on the same element to paint.',
   paramDescriptions: {},
   returnDescriptions: {
     pressableProps:

package/src/hooks/usePressFeedback.ts

@@ -26,11 +26,11 @@ import {installPressFeedback, pressableProps} from '../utils/pressFeedback';
  * `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
@@ -46,7 +46,7 @@ import {installPressFeedback, pressableProps} from '../utils/pressFeedback';
  * @example
  * ```
  * const pressable = usePressFeedback();
- * return <div role="button" {...pressable} {...stylex.props(styles.row)} />;
+ * return <button {...pressable} {...stylex.props(styles.button)} />;
  * ```
  */
 export function usePressFeedback(): typeof pressableProps {

package/src/hooks/useScrollRegionProps.ts

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useScrollRegionProps.ts
+ * @input Whether a region may scroll, and the caller's role and label
+ * @output useScrollRegionProps: a ref for the region, and the role and
+ *   accessible name that the region carries while its content overflows
+ * @position Internal hook for LayoutContent, LayoutPanel and StackItem.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useScrollRegionProps.test.tsx
+ * - /packages/core/src/AppShell/observeMainOverflow.ts
+ */
+
+import {useCallback, useState, type AriaRole, type RefCallback} from 'react';
+import {
+  registerEnglishFallback,
+  useComponentTranslator,
+} from '../i18n/useComponentTranslator';
+import english from '../i18n/generated-english/hooks/useScrollRegionProps.generated';
+import {observeMainOverflow} from '../AppShell/observeMainOverflow';
+
+registerEnglishFallback(english);
+
+export interface ScrollRegionOptions {
+  /** Whether the region may scroll at all (`overflow: auto`). */
+  isScrollable: boolean;
+  /** The caller's role. It always wins, and takes no default name. */
+  role?: AriaRole;
+  /** The caller's accessible name. It always wins. */
+  label?: string;
+}
+
+export interface ScrollRegionProps {
+  ref: RefCallback<HTMLElement>;
+  role: AriaRole | undefined;
+  'aria-label': string | undefined;
+}
+
+/**
+ * The region's ref, role and accessible name. While the region may scroll
+ * and its content overflows, it is a group named by the caller's `label`, or
+ * by the translated "Content". A caller's `role` is kept with only the
+ * caller's `label`: a single main landmark relies on its role alone. When
+ * the region does not scroll, the caller's own `role` and `label` pass
+ * through unchanged.
+ */
+export function useScrollRegionProps({
+  isScrollable,
+  role,
+  label,
+}: ScrollRegionOptions): ScrollRegionProps {
+  const t = useComponentTranslator();
+  const [overflows, setOverflows] = useState(false);
+  // A caller's role takes no default name, so its region is not observed.
+  const hasRole = role != null;
+  const ref = useCallback(
+    (element: HTMLElement | null) => {
+      if (element == null || !isScrollable || hasRole) {
+        setOverflows(false);
+        return undefined;
+      }
+      return observeMainOverflow(element, setOverflows);
+    },
+    [hasRole, isScrollable],
+  );
+  const isGroup = !hasRole && isScrollable && overflows;
+  return {
+    ref,
+    role: role ?? (isGroup ? 'group' : undefined),
+    'aria-label':
+      label ?? (isGroup ? t('@astryx.scrollRegion.label') : undefined),
+  };
+}

package/src/i18n/generated-english/hooks/useScrollRegionProps.generated.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @generated by scripts/generate-i18n-runtime.mjs from packages/core/locales/en.json,
+ * holding the English for the catalog keys named in packages/core/src/hooks/useScrollRegionProps.ts.
+ * Do not edit by hand. Run `pnpm generate:i18n-runtime` instead.
+ */
+
+const english: Readonly<Record<string, string>> = {
+  "@astryx.scrollRegion.label": "Content"
+};
+
+export default english;

package/src/i18n/generated-locales/en.generated.ts

@@ -375,6 +375,7 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.banner.expand': 'Expand',
   '@astryx.button.loading': 'Loading',
   '@astryx.spinner.loading': 'Loading',
+  '@astryx.scrollRegion.label': 'Content',
   '@astryx.chatComposerDrawer.expand': 'Expand {label}',
   '@astryx.chatComposerDrawer.collapse': 'Collapse {label}',
   '@astryx.chatDictationButton.startDictation': 'Start dictation',

package/src/i18n/generated-locales/pseudo.generated.ts

@@ -383,6 +383,7 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.banner.expand': '⟦Éẋþàñð⟧',
   '@astryx.button.loading': '⟦Łóàðíñĝ⟧',
   '@astryx.spinner.loading': '⟦Łóàðíñĝ⟧',
+  '@astryx.scrollRegion.label': '⟦Çóñţéñţ⟧',
   '@astryx.chatComposerDrawer.expand': '⟦Éẋþàñð {label}⟧',
   '@astryx.chatComposerDrawer.collapse': '⟦Çółłàþšé {label}⟧',
   '@astryx.chatDictationButton.startDictation': '⟦Šţàřţ ðíçţàţíóñ⟧',

package/src/motion/MEASUREMENTS.md

@@ -314,3 +314,14 @@ scroll view coasts with 0.25 × the pan's velocity plus 0.75 × its value one
 event earlier (four HID releases; `velocity.scrollReleaseWeight`, which a
 pan's `scrollVelocity()` reads). On UIKit, Reduce Motion with Prefer Cross-Fade changes
 nothing on a picker; the Wheel follows design:reduced-motion instead.
+
+## Menus (UIMenu)
+
+Probe: the UIKit lab host app with a UIButton whose `UIMenu` is its primary
+action (`showsMenuAsPrimaryAction`), three to twelve items, on a plain view
+and inside a UIScrollView; the gesture-state, presentation-modifier,
+display-link and feedback hooks; real HID touches.
+
+| ID    | Scene                  | Gesture                                                                                                                                                 | Extract                                                                                                                                 | Method |
+| ----- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| M-MN2 | button on a plain view | hold until the menu is open, then lift still; move 8 pt down, 8 pt right, 12 pt down, (7, 7), (8, 8) and lift; move 6 pt before the open and 6 pt after | row picked or not; handoff and list-selection recognizer states; highlighted row per frame: threshold, metric, where it is counted from | C      |

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,