@n-uf/motion 26.11.4 → 26.11.6

package/dist/gestures.d.ts

@@ -464,4 +464,248 @@ interface DwellMachineOptions {
 /** A dwell machine on a clock: the dwell timer is armed for you. */
 declare function createDwellMachine<K = string, P = unknown>(options: DwellMachineOptions): Machine<DwellState<K, P>, DwellInput<K, P>>;
 
-export { type CancelReason, type CoalescerOptions, DWELL_DEFAULTS, DWELL_IDLE, type Deadline, type DwellConfig, type DwellInput, type DwellMachineOptions, type DwellState, type FrameCoalescer, type InputGesture, type InputGestureType, type Machine, type MachineOptions, type ModifierDrag, type ModifierKey, type Modifiers, NO_MODIFIERS, type Platform, type PointerKind, RECOGNIZER_DEFAULTS, type RawInputEvent, type RawPointerEvent, type RawPointerType, type RawSafariGestureEvent, type RawWheelEvent, type Recognizer, type RecognizerOptions, type RecognizerTimers, type SurfacePointer, WHEEL_DEFAULTS, WHEEL_PAN_DEFAULTS, type WheelIntent, type WheelOptions, type WheelPanOptions, classifyWheel, createDwellMachine, createFrameCoalescer, createMachine, createRecognizer, dampWheelPan, defaultDragModifier, dwellDeadline, dwellReducer, isHeld, modHeld, platformButton, resolveDragModifier, toModifiers, wheelDeltaPx };
+/**
+ * A touch press on something draggable that sits in a scrolling page: is it a drag, or a scroll?
+ *
+ * ```text
+ * idle ──press──► pressed ──move: mostly along the scroll direction, ≥ scrollEscape──► scrolled (never lifts)
+ *                    │ ──move: mostly across it, ≥ lift px────────────────────────────► lifted
+ *                    │ ──tick: held still holdMs─────────────────────────────────────► lifted (where it was pressed)
+ *                    └ ──move: along it short of the escape, or across it below lift px: stays pressed
+ * any ──release──► idle
+ * ```
+ *
+ * Before the hold has elapsed, a finger that travels mostly along the page's scroll direction is a scroll: the touch
+ * goes back to the page and stays a scroll until it is released; short of the escape it waits, never lifting.
+ * Travel past the lift distance mostly across the scroll direction is a deliberate drag. Once the hold has elapsed
+ * the press lifts where it is. `scrolled` and `lifted`
+ * hold until `release`.
+ */
+/** Tunables of the touch press. */
+interface TouchPressConfig {
+    /** px of travel that lifts a press that is not a scroll. Default 6. */
+    readonly lift: number;
+    /** px of travel along the scroll direction that makes the press a scroll. Default 10. */
+    readonly scrollEscape: number;
+    /** The page's scroll direction: `"y"` (a vertical page, the default) or `"x"`. */
+    readonly scroll: "x" | "y";
+    /** ms a still finger holds before the press lifts where it is. Default 220. */
+    readonly holdMs: number;
+}
+/** Defaults of {@link TouchPressConfig}. */
+declare const TOUCH_PRESS_DEFAULTS: TouchPressConfig;
+/** The touch press's state. `from` is where the finger went down, `at` where it lifted. */
+type TouchPressState = {
+    readonly phase: "idle";
+} | {
+    readonly phase: "pressed";
+    readonly from: Point;
+    readonly since: number;
+} | {
+    readonly phase: "lifted";
+    readonly from: Point;
+    readonly at: Point;
+} | {
+    readonly phase: "scrolled";
+    readonly from: Point;
+};
+/** Events of the touch press. `t` is the clock time in ms. */
+type TouchPressInput = {
+    readonly type: "press";
+    readonly t: number;
+    readonly point: Point;
+} | {
+    readonly type: "move";
+    readonly point: Point;
+} | {
+    readonly type: "tick";
+    readonly t: number;
+} | {
+    readonly type: "release";
+};
+/** The idle state (the same object every time). */
+declare const TOUCH_PRESS_IDLE: TouchPressState;
+/** The touch press's pure transition function. */
+declare function touchPressReducer(state: TouchPressState, event: TouchPressInput, config?: TouchPressConfig): TouchPressState;
+/** When a pressed state lifts by holding, as a timer event; `null` outside `pressed`. */
+declare function touchPressDeadline(state: TouchPressState, config?: TouchPressConfig): Deadline<TouchPressInput> | null;
+/** Options of {@link createTouchPress}. */
+interface TouchPressOptions {
+    readonly clock: TimerSource;
+    readonly config?: Partial<TouchPressConfig>;
+}
+/** A touch press on a clock: the hold timer is armed for you. */
+declare function createTouchPress(options: TouchPressOptions): Machine<TouchPressState, TouchPressInput>;
+
+/**
+ * A paged swipe: a trackpad's two-finger scroll or a finger swipes from one page to the previous or the next, the
+ * pages following it, and commits or snaps back when it ends.
+ *
+ * ```text
+ * idle ──wheel / touch-move (arming rules pass)──► armed ──travel ≥ thresholdPx──► tracking
+ *   ▲                                               │                                │
+ *   │                                   rule breach / idle / end                 gesture end
+ *   │                                               ▼                                ▼
+ *   └──────── lockoutMs elapsed ◄── lockout ◄── settled (commit) ◄───────────── settling
+ *   └──────────────────────────────────────── settled (cancel) ◄───────────────────┤
+ *   └──────────────────────────────────────── cancel (transition stopped) ◄────────┘
+ * ```
+ *
+ * - **Arming:** nothing else owns the pointer (`blocked`), the movement runs mostly along the swipe (more than twice
+ *   the cross movement), no Ctrl (a pinch), the configured modifier is held, nothing under the pointer can still
+ *   scroll that way (`canScrollFurther`), and there is a page on that side (or `wrap`). A wheel run that breaks a
+ *   rule belongs to scrolling until the wheel has been idle `idleMs`.
+ * - **Tracking:** `progress` is the travel over the page size, −1 to 1, held at 0 towards a side with no page.
+ * - **Ending:** a touch ends when the finger lifts, a wheel run after `idleMs` without samples. It commits when
+ *   `|progress| ≥ commitFraction`, or the peak speed towards the target reached `commitVelocity` (the peak starts
+ *   over when the travel crosses zero, so a fast fling out and a pull back does not commit the way back).
+ * - **Settling** lasts as long as the host's page transition; the host sends `settled` when it is done (or `cancel`,
+ *   which goes straight back to idle, when it stops the transition). After a commit, `lockout` swallows the
+ *   trackpad's momentum for `lockoutMs`, and the run stays claimed after it.
+ *
+ * Pure and timer-free: {@link pagedSwipeDeadline} says when the next `tick` is due ({@link createPagedSwipe} arms it).
+ * Signs: a wheel delta > 0 along the swipe heads to `next`; a finger moving towards smaller x (or y) heads to `next`.
+ */
+/** Which side of the current page a swipe heads to. */
+type SwipeSide = "prev" | "next";
+/** Tunables of the paged swipe. */
+interface PagedSwipeConfig {
+    /** px of travel before an armed swipe tracks. Default 24. */
+    readonly thresholdPx: number;
+    /** The share of the page size that commits at the end. Default 0.35. */
+    readonly commitFraction: number;
+    /** px/ms: a peak speed towards the target that commits at the end. Default 0.6. */
+    readonly commitVelocity: number;
+    /** ms without a wheel sample that ends a wheel run. Default 120. */
+    readonly idleMs: number;
+    /** ms after a commit during which wheel samples are swallowed (momentum). Default 350. */
+    readonly lockoutMs: number;
+    /** Past the last page comes the first, and back. Default false. */
+    readonly wrap: boolean;
+    /** The page size in px when no sample or context gives one. Default 800. */
+    readonly size: number;
+    /** A modifier the wheel needs held to swipe (`null`: none). Touch never needs one. Default null. */
+    readonly modifier: ModifierKey | null;
+    /** The swipe's direction: `"x"` (the default) or `"y"`. */
+    readonly along: "x" | "y";
+}
+/** Defaults of {@link PagedSwipeConfig}. */
+declare const PAGED_SWIPE_DEFAULTS: PagedSwipeConfig;
+/** What the host knows about the pages now. */
+interface PagedSwipeContext {
+    readonly hasPrev: boolean;
+    readonly hasNext: boolean;
+    /** The page size in px, or null (the config's). */
+    readonly size: number | null;
+    /** Something else owns the pointer (a drag): nothing arms, and a swipe in progress gives way. */
+    readonly blocked: boolean;
+}
+/** The context before the host has said anything. */
+declare const PAGED_SWIPE_EMPTY_CONTEXT: PagedSwipeContext;
+type Input = "wheel" | "touch";
+interface Base {
+    readonly context: PagedSwipeContext;
+    /** −1 to 1; negative towards `prev`. */
+    readonly progress: number;
+    readonly target: SwipeSide | null;
+}
+/** The paged swipe's state. Every phase has a way back to `idle`. */
+type PagedSwipeState = (Base & {
+    readonly phase: "idle";
+    /** The last wheel sample of the current run (null: none, or the run went idle). */
+    readonly lastWheel: number | null;
+    /** This wheel run broke the arming rules (or committed): it cannot arm until the wheel is idle `idleMs`. */
+    readonly claimed: boolean;
+}) | (Base & {
+    readonly phase: "armed";
+    readonly input: Input;
+    /** Where the finger went down (touch). */
+    readonly origin: {
+        readonly x: number;
+        readonly y: number;
+    };
+    /** Wheel travel along the swipe and across it so far. */
+    readonly travel: number;
+    readonly cross: number;
+    readonly last: number;
+}) | (Base & {
+    readonly phase: "tracking";
+    readonly input: Input;
+    readonly origin: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly travel: number;
+    readonly last: number;
+    /** The highest speed (px/ms) towards the current target. */
+    readonly peak: number;
+}) | (Base & {
+    readonly phase: "settling";
+    readonly input: Input;
+    readonly outcome: "commit" | "cancel";
+    readonly ended: number;
+    readonly lastWheel: number;
+}) | (Base & {
+    readonly phase: "lockout";
+    readonly until: number;
+    readonly lastWheel: number;
+});
+/** Events of the paged swipe. `t` is the clock time in ms. */
+type PagedSwipeInput = {
+    readonly type: "wheel";
+    readonly dx: number;
+    readonly dy: number;
+    readonly t: number;
+    readonly modifiers: Modifiers;
+    /** Something under the pointer can still scroll that way: no arming. */
+    readonly canScrollFurther?: boolean;
+    readonly size?: number;
+} | {
+    readonly type: "touch-start";
+    readonly x: number;
+    readonly y: number;
+    readonly t: number;
+    readonly size?: number;
+} | {
+    readonly type: "touch-move";
+    readonly x: number;
+    readonly y: number;
+    readonly t: number;
+    readonly canScrollFurther?: boolean;
+    readonly size?: number;
+} | {
+    readonly type: "touch-end";
+    readonly t: number;
+} | {
+    readonly type: "tick";
+    readonly t: number;
+} | {
+    readonly type: "settled";
+} | {
+    readonly type: "cancel";
+} | {
+    readonly type: "block";
+    readonly on: boolean;
+} | {
+    readonly type: "context";
+    readonly hasPrev: boolean;
+    readonly hasNext: boolean;
+    readonly size?: number;
+};
+/** The idle state with no context. */
+declare const PAGED_SWIPE_IDLE: PagedSwipeState;
+/** Travel to progress: over the page size, −1 to 1, 0 towards a side with no page (unless `wrap`). */
+declare function swipeProgress(travel: number, size: number, c: PagedSwipeContext, wrap: boolean): number;
+/** The paged swipe's pure transition function. Unmatched pairs return the state unchanged. */
+declare function pagedSwipeReducer(state: PagedSwipeState, event: PagedSwipeInput, config?: PagedSwipeConfig): PagedSwipeState;
+/** When the next `tick` is due: a wheel run's idle end, or the end of the lockout; `null` when none is. */
+declare function pagedSwipeDeadline(state: PagedSwipeState, config?: PagedSwipeConfig): Deadline<PagedSwipeInput> | null;
+/** Options of {@link createPagedSwipe}. */
+interface PagedSwipeOptions {
+    readonly clock: TimerSource;
+    readonly config?: Partial<PagedSwipeConfig>;
+}
+/** A paged swipe on a clock: the idle and lockout timers are armed for you. */
+declare function createPagedSwipe(options: PagedSwipeOptions): Machine<PagedSwipeState, PagedSwipeInput>;
+
+export { type CancelReason, type CoalescerOptions, DWELL_DEFAULTS, DWELL_IDLE, type Deadline, type DwellConfig, type DwellInput, type DwellMachineOptions, type DwellState, type FrameCoalescer, type InputGesture, type InputGestureType, type Machine, type MachineOptions, type ModifierDrag, type ModifierKey, type Modifiers, NO_MODIFIERS, PAGED_SWIPE_DEFAULTS, PAGED_SWIPE_EMPTY_CONTEXT, PAGED_SWIPE_IDLE, type PagedSwipeConfig, type PagedSwipeContext, type PagedSwipeInput, type PagedSwipeOptions, type PagedSwipeState, type Platform, type PointerKind, RECOGNIZER_DEFAULTS, type RawInputEvent, type RawPointerEvent, type RawPointerType, type RawSafariGestureEvent, type RawWheelEvent, type Recognizer, type RecognizerOptions, type RecognizerTimers, type SurfacePointer, type SwipeSide, TOUCH_PRESS_DEFAULTS, TOUCH_PRESS_IDLE, type TouchPressConfig, type TouchPressInput, type TouchPressOptions, type TouchPressState, WHEEL_DEFAULTS, WHEEL_PAN_DEFAULTS, type WheelIntent, type WheelOptions, type WheelPanOptions, classifyWheel, createDwellMachine, createFrameCoalescer, createMachine, createPagedSwipe, createRecognizer, createTouchPress, dampWheelPan, defaultDragModifier, dwellDeadline, dwellReducer, isHeld, modHeld, pagedSwipeDeadline, pagedSwipeReducer, platformButton, resolveDragModifier, swipeProgress, toModifiers, touchPressDeadline, touchPressReducer, wheelDeltaPx };

package/dist/gestures.js

@@ -2,47 +2,71 @@ import {
   DWELL_DEFAULTS,
   DWELL_IDLE,
   NO_MODIFIERS,
+  PAGED_SWIPE_DEFAULTS,
+  PAGED_SWIPE_EMPTY_CONTEXT,
+  PAGED_SWIPE_IDLE,
   RECOGNIZER_DEFAULTS,
+  TOUCH_PRESS_DEFAULTS,
+  TOUCH_PRESS_IDLE,
   WHEEL_DEFAULTS,
   WHEEL_PAN_DEFAULTS,
   classifyWheel,
   createDwellMachine,
   createFrameCoalescer,
   createMachine,
+  createPagedSwipe,
   createRecognizer,
+  createTouchPress,
   dampWheelPan,
   defaultDragModifier,
   dwellDeadline,
   dwellReducer,
   isHeld,
   modHeld,
+  pagedSwipeDeadline,
+  pagedSwipeReducer,
   platformButton,
   resolveDragModifier,
+  swipeProgress,
   toModifiers,
+  touchPressDeadline,
+  touchPressReducer,
   wheelDeltaPx
-} from "./chunk-C4M62FUT.js";
+} from "./chunk-KVFX5V4Y.js";
 import "./chunk-OOKRBVMB.js";
 export {
   DWELL_DEFAULTS,
   DWELL_IDLE,
   NO_MODIFIERS,
+  PAGED_SWIPE_DEFAULTS,
+  PAGED_SWIPE_EMPTY_CONTEXT,
+  PAGED_SWIPE_IDLE,
   RECOGNIZER_DEFAULTS,
+  TOUCH_PRESS_DEFAULTS,
+  TOUCH_PRESS_IDLE,
   WHEEL_DEFAULTS,
   WHEEL_PAN_DEFAULTS,
   classifyWheel,
   createDwellMachine,
   createFrameCoalescer,
   createMachine,
+  createPagedSwipe,
   createRecognizer,
+  createTouchPress,
   dampWheelPan,
   defaultDragModifier,
   dwellDeadline,
   dwellReducer,
   isHeld,
   modHeld,
+  pagedSwipeDeadline,
+  pagedSwipeReducer,
   platformButton,
   resolveDragModifier,
+  swipeProgress,
   toModifiers,
+  touchPressDeadline,
+  touchPressReducer,
   wheelDeltaPx
 };
 //# sourceMappingURL=gestures.js.map

package/dist/index.d.ts

@@ -4,5 +4,5 @@ export { F as FrameInfo, a as FrameLoop, b as FrameLoopOptions, c as FrameStats,
 export { EffectCleanup, EffectOptions, Equals, ReadonlySignal, Signal, SignalOptions, batch, computed, effect, isSignal, signal, untracked } from './signals.js';
 export { Animator, AnimatorValue, Easing, MotionOptions, MotionValue, SETTLE_DEFAULTS, SETTLE_TEMPO, SPRING_DEFAULTS, SetOptions, Settle, SettleConfig, Spring, SpringConfig, SpringParams, SpringState, Tween, TweenConfig, createSettle, createSpring, createTween, cubicBezier, ease, easeIn, easeInOut, easeInOutCubic, easeOut, easeOutCubic, linear, motionValue, resolveSpring, settleValue, springStep, springValue, tweenValue } from './values.js';
 export { P as PopIn, R as RevealFrame, p as popIn, r as reveal } from './reveal-my7U6UyE.js';
-export { CancelReason, CoalescerOptions, DWELL_DEFAULTS, DWELL_IDLE, Deadline, DwellConfig, DwellInput, DwellMachineOptions, DwellState, FrameCoalescer, InputGesture, InputGestureType, Machine, MachineOptions, ModifierDrag, ModifierKey, Modifiers, NO_MODIFIERS, Platform, PointerKind, RECOGNIZER_DEFAULTS, RawInputEvent, RawPointerEvent, RawPointerType, RawSafariGestureEvent, RawWheelEvent, Recognizer, RecognizerOptions, RecognizerTimers, SurfacePointer, WHEEL_DEFAULTS, WHEEL_PAN_DEFAULTS, WheelIntent, WheelOptions, WheelPanOptions, classifyWheel, createDwellMachine, createFrameCoalescer, createMachine, createRecognizer, dampWheelPan, defaultDragModifier, dwellDeadline, dwellReducer, isHeld, modHeld, platformButton, resolveDragModifier, toModifiers, wheelDeltaPx } from './gestures.js';
+export { CancelReason, CoalescerOptions, DWELL_DEFAULTS, DWELL_IDLE, Deadline, DwellConfig, DwellInput, DwellMachineOptions, DwellState, FrameCoalescer, InputGesture, InputGestureType, Machine, MachineOptions, ModifierDrag, ModifierKey, Modifiers, NO_MODIFIERS, PAGED_SWIPE_DEFAULTS, PAGED_SWIPE_EMPTY_CONTEXT, PAGED_SWIPE_IDLE, PagedSwipeConfig, PagedSwipeContext, PagedSwipeInput, PagedSwipeOptions, PagedSwipeState, Platform, PointerKind, RECOGNIZER_DEFAULTS, RawInputEvent, RawPointerEvent, RawPointerType, RawSafariGestureEvent, RawWheelEvent, Recognizer, RecognizerOptions, RecognizerTimers, SurfacePointer, SwipeSide, TOUCH_PRESS_DEFAULTS, TOUCH_PRESS_IDLE, TouchPressConfig, TouchPressInput, TouchPressOptions, TouchPressState, WHEEL_DEFAULTS, WHEEL_PAN_DEFAULTS, WheelIntent, WheelOptions, WheelPanOptions, classifyWheel, createDwellMachine, createFrameCoalescer, createMachine, createPagedSwipe, createRecognizer, createTouchPress, dampWheelPan, defaultDragModifier, dwellDeadline, dwellReducer, isHeld, modHeld, pagedSwipeDeadline, pagedSwipeReducer, platformButton, resolveDragModifier, swipeProgress, toModifiers, touchPressDeadline, touchPressReducer, wheelDeltaPx } from './gestures.js';
 export { A as Animatable, P as Point, R as Rect, V as Vector, W as Widen, s as shapeEquals } from './shapes-EbQlwbCu.js';

package/dist/index.js

@@ -27,25 +27,37 @@ import {
   DWELL_DEFAULTS,
   DWELL_IDLE,
   NO_MODIFIERS,
+  PAGED_SWIPE_DEFAULTS,
+  PAGED_SWIPE_EMPTY_CONTEXT,
+  PAGED_SWIPE_IDLE,
   RECOGNIZER_DEFAULTS,
+  TOUCH_PRESS_DEFAULTS,
+  TOUCH_PRESS_IDLE,
   WHEEL_DEFAULTS,
   WHEEL_PAN_DEFAULTS,
   classifyWheel,
   createDwellMachine,
   createFrameCoalescer,
   createMachine,
+  createPagedSwipe,
   createRecognizer,
+  createTouchPress,
   dampWheelPan,
   defaultDragModifier,
   dwellDeadline,
   dwellReducer,
   isHeld,
   modHeld,
+  pagedSwipeDeadline,
+  pagedSwipeReducer,
   platformButton,
   resolveDragModifier,
+  swipeProgress,
   toModifiers,
+  touchPressDeadline,
+  touchPressReducer,
   wheelDeltaPx
-} from "./chunk-C4M62FUT.js";
+} from "./chunk-KVFX5V4Y.js";
 import {
   batch,
   computed,
@@ -66,11 +78,16 @@ export {
   DWELL_DEFAULTS,
   DWELL_IDLE,
   NO_MODIFIERS,
+  PAGED_SWIPE_DEFAULTS,
+  PAGED_SWIPE_EMPTY_CONTEXT,
+  PAGED_SWIPE_IDLE,
   PHASES,
   RECOGNIZER_DEFAULTS,
   SETTLE_DEFAULTS,
   SETTLE_TEMPO,
   SPRING_DEFAULTS,
+  TOUCH_PRESS_DEFAULTS,
+  TOUCH_PRESS_IDLE,
   WHEEL_DEFAULTS,
   WHEEL_PAN_DEFAULTS,
   batch,
@@ -81,9 +98,11 @@ export {
   createFrameCoalescer,
   createFrameLoop,
   createMachine,
+  createPagedSwipe,
   createRecognizer,
   createSettle,
   createSpring,
+  createTouchPress,
   createTween,
   cubicBezier,
   dampWheelPan,
@@ -102,6 +121,8 @@ export {
   linear,
   modHeld,
   motionValue,
+  pagedSwipeDeadline,
+  pagedSwipeReducer,
   platformButton,
   popIn,
   resolveDragModifier,
@@ -112,7 +133,10 @@ export {
   signal,
   springStep,
   springValue,
+  swipeProgress,
   toModifiers,
+  touchPressDeadline,
+  touchPressReducer,
   tweenValue,
   untracked,
   wheelDeltaPx

package/dist/layout.d.ts

@@ -58,6 +58,14 @@ interface LayoutItem {
     readonly shownSettled: boolean;
     /** Settle to `to` from where it is drawn; lays the content out at `to` and redraws at once. */
     moveTo(to: Rect): void;
+    /**
+     * Settle to `to` from where it is drawn, like {@link LayoutItem.moveTo}, but keep the content laid out in its box
+     * while `to` is the box's size: for chasing a moving point (a pointer), which would otherwise lay the content out
+     * again on every frame. A new size lays it out at `to`, as `moveTo` does. Optional, so an item from before it (or
+     * a test double) still works where it is used: {@link holdItem} falls back to `moveTo`. `createLayoutMotion`'s
+     * items always have it.
+     */
+    retarget?(to: Rect): void;
     /** Be at `to` now, at rest: no glide. */
     jumpTo(to: Rect): void;
     /** Drawn at `from` now, then settle to `to` (a FLIP's invert and play: `from` in the item's own coordinates). */
@@ -73,6 +81,11 @@ interface LayoutItem {
 }
 /** A task the layout motion runs on every frame before it steps the items; true keeps the frames coming. */
 type LayoutTask = (frame: FrameInfo) => boolean | void;
+/** One item's frame in a batch ({@link LayoutMotionOptions.onDraw}). */
+interface DrawEntry {
+    readonly id: string;
+    readonly frame: DrawFrame;
+}
 interface LayoutMotionOptions {
     /** The frame loop every item steps on (one loop for all of them). */
     readonly loop: FrameLoop;
@@ -82,6 +95,20 @@ interface LayoutMotionOptions {
     readonly phase?: Phase;
     /** Where an appearing item grows from, as a share of its size ({@link popIn}'s `from`); default 0.87. */
     readonly popFrom?: number;
+    /**
+     * Reduced motion: read on every new target and every show or hide. While true an item is placed on its new
+     * target at once (no glide) and appears or disappears at once (no fade). A boolean, or the host's query (such as
+     * the reduced-motion media query). Default false.
+     */
+    readonly reducedMotion?: boolean | (() => boolean);
+    /**
+     * Batched drawing: every item that changed is drawn in one pass per frame, after the items step: each one's
+     * drawable, then this, once, with all of their frames. Changes made between frames (a new target, a hold) are
+     * drawn on the next frame, or now by {@link LayoutMotion.flush}. Without it, each item is drawn as it changes.
+     */
+    readonly onDraw?: (batch: readonly DrawEntry[]) => void;
+    /** Called when frames start running (true) and when they stop (false), once per change. */
+    readonly onActiveChange?: (active: boolean) => void;
 }
 /**
  * Layout motion: items with an id and a target rect, each settled to its place on one shared frame loop.
@@ -100,6 +127,14 @@ interface LayoutMotion {
     get(id: string): LayoutItem | undefined;
     /** Stop moving an item (its drawable is not touched again). */
     remove(id: string): void;
+    /** Remove every item whose id is not in `ids` (the ones that left the layout). */
+    retain(ids: Iterable<string>): void;
+    /**
+     * With {@link LayoutMotionOptions.onDraw}: draw the items changed since the last frame now, outside the loop. A
+     * host calls it right after it commits a new layout, so the next paint shows every item where it is drawn, not a
+     * frame at its new box. Without batching each item is already drawn as it changes, and it does nothing.
+     */
+    flush(): void;
     readonly items: ReadonlyMap<string, LayoutItem>;
     /** Run `task` on every frame, before the items step; returns how to stop it. */
     task(task: LayoutTask): () => void;
@@ -255,4 +290,4 @@ declare function drawBox(nodes: BoxNodes, frame: DrawFrame): void;
 /** A {@link Drawable} for DOM nodes: {@link layOutBox} on a new box, {@link drawBox} on every frame. */
 declare function domDrawable(nodes: BoxNodes): Drawable;
 
-export { type BoxNodes, type DrawFrame, type Drawable, type FlipEntry, type HeldDrag, type LayoutItem, type LayoutMotion, type LayoutMotionOptions, type LayoutTask, type Measurable, type RectLike, type StyleLike, type Styled, createLayoutMotion, domDrawable, drawBox, flip, holdItem, layOutBox, rectOf };
+export { type BoxNodes, type DrawEntry, type DrawFrame, type Drawable, type FlipEntry, type HeldDrag, type LayoutItem, type LayoutMotion, type LayoutMotionOptions, type LayoutTask, type Measurable, type RectLike, type StyleLike, type Styled, createLayoutMotion, domDrawable, drawBox, flip, holdItem, layOutBox, rectOf };

package/dist/layout.js

@@ -23,19 +23,45 @@ function createLayoutMotion(options) {
   let waiters = [];
   let stop = null;
   let woken = false;
+  let ticking = false;
+  let active = false;
+  const reduced = () => typeof options.reducedMotion === "function" ? options.reducedMotion() : options.reducedMotion === true;
+  const { onDraw, onActiveChange } = options;
+  const drawers = /* @__PURE__ */ new Map();
+  const dirty = /* @__PURE__ */ new Set();
+  const setActive = (on) => {
+    if (on === active) return;
+    active = on;
+    onActiveChange?.(on);
+  };
   const wake = () => {
     woken = true;
     if (stop) return;
     stop = loop.repeat(phase, tick);
+    setActive(true);
   };
+  function writeBatch() {
+    if (!onDraw || dirty.size === 0) return;
+    const batch = [];
+    for (const id of dirty) {
+      const entry = drawers.get(id)?.();
+      if (entry) batch.push(entry);
+    }
+    dirty.clear();
+    if (batch.length > 0) onDraw(batch);
+  }
   function tick(frame) {
     let moving = woken;
     woken = false;
+    ticking = true;
     for (const task of [...tasks]) if (task(frame)) moving = true;
     for (const step of [...steps.values()]) if (step(frame.delta)) moving = true;
+    writeBatch();
+    ticking = false;
     for (const listener of [...frames]) listener(frame);
     if (moving || woken) return true;
     stop = null;
+    setActive(false);
     const resolve = waiters;
     waiters = [];
     for (const r of resolve) r();
@@ -51,11 +77,33 @@ function createLayoutMotion(options) {
       const drawn = rect.value;
       return { drawn, box, reveal: reveal(drawn, box), pop: popIn(pop.value, popFrom), shown: pop.value, gone: pop.settled && pop.value === 0 };
     };
-    const draw = () => drawable.draw(frameOf());
+    const drawNow = () => {
+      const frame = frameOf();
+      drawable.draw(frame);
+      return { id, frame };
+    };
+    const draw = () => {
+      if (!onDraw) {
+        drawNow();
+        return;
+      }
+      dirty.add(id);
+      if (!ticking) wake();
+    };
     const layOut = (to) => {
       box = copy(to);
       drawable.layOut(box);
     };
+    const aim = (to) => {
+      if (reduced()) {
+        rect.jumpTo(copy(to));
+        draw();
+        return;
+      }
+      rect.setTarget(copy(to));
+      wake();
+    };
+    let moved = false;
     const tempo = () => {
       rect.configure({ omega });
       pop.configure({ omega });
@@ -88,8 +136,15 @@ function createLayoutMotion(options) {
         layOut(to);
         draw();
         if (same(rect.target, to)) return;
-        rect.setTarget(copy(to));
-        wake();
+        aim(to);
+      },
+      retarget(to) {
+        if (to.width !== box.width || to.height !== box.height) {
+          item.moveTo(to);
+          return;
+        }
+        if (same(rect.target, to)) return;
+        aim(to);
       },
       jumpTo(to) {
         layOut(to);
@@ -100,8 +155,7 @@ function createLayoutMotion(options) {
         rect.jumpTo(copy(from));
         layOut(to);
         draw();
-        rect.setTarget(copy(to));
-        wake();
+        aim(to);
       },
       hold(r) {
         rect.hold(copy(r));
@@ -109,7 +163,7 @@ function createLayoutMotion(options) {
       },
       show(on, o = {}) {
         const want = on ? 1 : 0;
-        if (o.now) pop.jumpTo(want);
+        if (o.now || reduced()) pop.jumpTo(want);
         else if (pop.target !== want) {
           pop.setTarget(want);
           wake();
@@ -118,6 +172,7 @@ function createLayoutMotion(options) {
       },
       redraw: draw
     };
+    drawers.set(id, drawNow);
     drawable.layOut(box);
     draw();
     items.set(id, item);
@@ -125,21 +180,32 @@ function createLayoutMotion(options) {
     steps.set(id, (dt) => {
       const a = rect.step(dt);
       const b = pop.step(dt);
-      draw();
+      if (!onDraw || a || b || moved) draw();
+      moved = a || b;
       return a || b;
     });
-    removers.set(id, () => tempos.delete(tempo));
+    removers.set(id, () => {
+      tempos.delete(tempo);
+      drawers.delete(id);
+      dirty.delete(id);
+    });
     return item;
   }
+  function remove(id) {
+    items.delete(id);
+    steps.delete(id);
+    removers.get(id)?.();
+    removers.delete(id);
+  }
   return {
     add,
     get: (id) => items.get(id),
-    remove(id) {
-      items.delete(id);
-      steps.delete(id);
-      removers.get(id)?.();
-      removers.delete(id);
+    remove,
+    retain(ids) {
+      const keep = new Set(ids);
+      for (const id of [...items.keys()]) if (!keep.has(id)) remove(id);
     },
+    flush: writeBatch,
     items,
     task(task) {
       tasks.add(task);
@@ -166,8 +232,11 @@ function createLayoutMotion(options) {
     dispose() {
       stop?.();
       stop = null;
+      setActive(false);
       items.clear();
       steps.clear();
+      drawers.clear();
+      dirty.clear();
       tasks.clear();
       frames.clear();
       idles.clear();
@@ -206,7 +275,8 @@ function holdItem(item, grab) {
   const follow = () => {
     const goal = heldRect();
     if (!returning || !goal) return false;
-    item.moveTo(goal);
+    if (item.retarget) item.retarget(goal);
+    else item.moveTo(goal);
     const d = item.drawn;
     if (Math.max(Math.abs(d.x - goal.x), Math.abs(d.y - goal.y), Math.abs(d.width - goal.width), Math.abs(d.height - goal.height)) >= CAUGHT) return false;
     returning = false;