@humanspeak/svelte-motion 0.5.1 → 0.5.3

package/dist/utils/drag.d.ts

@@ -66,24 +66,55 @@ export declare const resolveConstraints: (el: HTMLElement | null, constraints: D
  */
 export declare const applyElastic: (value: number, min: number, max: number, elastic: number) => number;
 /**
- * Attach a drag gesture to an element.
+ * Cleanup handle returned by {@link attachDrag}. Invoke it to detach the
+ * gesture's pointer/resize listeners. It does NOT cancel an in-flight
+ * momentum/settle animation — matching framer-motion, whose drag teardown
+ * removes listeners only and deliberately lets motion continue across an
+ * unmount/remount (e.g. reorder reconciliation); the animation is cleaned
+ * up by the element/motion-value lifecycle.
  *
- * Captures the pointer, updates x/y transforms with axis and optional direction lock,
- * applies elastic overflow against constraints, emits lifecycle callbacks with DragInfo,
- * and runs a momentum animation on release when enabled.
+ * The handle also carries `adjustOrigin(dx, dy)`, which shifts the LIVE
+ * gesture's origin + visual offset by a layout-shift delta mid-drag — used
+ * for projection-driven cursor pinning when a layout slot moves under the
+ * dragged element (#379 / #310). It is a no-op when not currently dragging
+ * and compensates on both axes (mirroring upstream's per-axis `eachAxis`
+ * compensation).
  */
+export type AttachDragCleanup = (() => void) & {
+    adjustOrigin: (dx: number, dy: number) => void;
+};
 /**
- * Attach a drag gesture to an HTMLElement.
+ * Attach a drag gesture to an element.
+ *
+ * Captures the pointer and updates x/y transforms with axis and optional
+ * direction lock, applies elastic overflow against constraints, emits
+ * lifecycle callbacks with `DragInfo`, and runs a momentum animation on
+ * release when enabled.
  *
  * Lifecycle:
  * - pointerdown → capture pointer, snapshot origin, start velocity history, enter whileDrag
  * - pointermove → compute deltas, direction lock, apply constraints + elastic, write x/y
  * - pointerup/cancel → either run momentum decay to a target or settle/clamp instantly
  *
- * Important invariants:
- * - `applied` tracks the currently applied transform (x/y). Always keep it in sync when
- *   writing transforms or finishing animations so a second drag starts from the right origin.
- * - If you see a "jump" at the start of a second drag, it usually means `applied` wasn't
- *   updated after a non-0-duration settle animation.
+ * Invariant: `applied` tracks the currently applied x/y transform — it
+ * must stay in sync when writing transforms or finishing animations, or a
+ * second drag "jumps" from a stale origin (commonly a missed update after
+ * a non-zero-duration settle animation).
+ *
+ * @param el The element to make draggable.
+ * @param opts Drag options — `axis`, `constraints`, `elastic`,
+ *   `momentum`, `whileDrag`, and the `onDrag*` lifecycle callbacks.
+ * @returns A callable cleanup handle ({@link AttachDragCleanup}): call it
+ *   to detach the gesture's listeners (in-flight momentum is not
+ *   cancelled — see the type docs), or call its `adjustOrigin(dx, dy)` to
+ *   reposition the live gesture mid-drag.
+ * @example
+ * ```ts
+ * const cleanup = attachDrag(el, { axis: 'x', momentum: true })
+ * // …when a layout swap shifts the slot under the cursor mid-drag:
+ * cleanup.adjustOrigin(10, -5)
+ * // on teardown:
+ * cleanup()
+ * ```
  */
-export declare const attachDrag: (el: HTMLElement, opts: AttachDragOptions) => (() => void);
+export declare const attachDrag: (el: HTMLElement, opts: AttachDragOptions) => AttachDragCleanup;

package/dist/utils/drag.js

@@ -137,23 +137,36 @@ const computeReleaseVelocity = (history, nowMs) => {
 /**
  * Attach a drag gesture to an element.
  *
- * Captures the pointer, updates x/y transforms with axis and optional direction lock,
- * applies elastic overflow against constraints, emits lifecycle callbacks with DragInfo,
- * and runs a momentum animation on release when enabled.
- */
-/**
- * Attach a drag gesture to an HTMLElement.
+ * Captures the pointer and updates x/y transforms with axis and optional
+ * direction lock, applies elastic overflow against constraints, emits
+ * lifecycle callbacks with `DragInfo`, and runs a momentum animation on
+ * release when enabled.
  *
  * Lifecycle:
  * - pointerdown → capture pointer, snapshot origin, start velocity history, enter whileDrag
  * - pointermove → compute deltas, direction lock, apply constraints + elastic, write x/y
  * - pointerup/cancel → either run momentum decay to a target or settle/clamp instantly
  *
- * Important invariants:
- * - `applied` tracks the currently applied transform (x/y). Always keep it in sync when
- *   writing transforms or finishing animations so a second drag starts from the right origin.
- * - If you see a "jump" at the start of a second drag, it usually means `applied` wasn't
- *   updated after a non-0-duration settle animation.
+ * Invariant: `applied` tracks the currently applied x/y transform — it
+ * must stay in sync when writing transforms or finishing animations, or a
+ * second drag "jumps" from a stale origin (commonly a missed update after
+ * a non-zero-duration settle animation).
+ *
+ * @param el The element to make draggable.
+ * @param opts Drag options — `axis`, `constraints`, `elastic`,
+ *   `momentum`, `whileDrag`, and the `onDrag*` lifecycle callbacks.
+ * @returns A callable cleanup handle ({@link AttachDragCleanup}): call it
+ *   to detach the gesture's listeners (in-flight momentum is not
+ *   cancelled — see the type docs), or call its `adjustOrigin(dx, dy)` to
+ *   reposition the live gesture mid-drag.
+ * @example
+ * ```ts
+ * const cleanup = attachDrag(el, { axis: 'x', momentum: true })
+ * // …when a layout swap shifts the slot under the cursor mid-drag:
+ * cleanup.adjustOrigin(10, -5)
+ * // on teardown:
+ * cleanup()
+ * ```
  */
 export const attachDrag = (el, opts) => {
     const EL_ID = el.getAttribute('data-testid') || el.id || el.tagName;
@@ -249,6 +262,83 @@ export const attachDrag = (el, opts) => {
             }
         }
     };
+    /**
+     * Write absolute element-space translation by mutating
+     * `el.style.transform` DIRECTLY — no `animate()`, no epsilon skip,
+     * no Playwright retry. The translate channel is rewritten while any
+     * non-translate transform the element already carries (e.g. a
+     * `whileDrag` scale) is preserved as a suffix.
+     *
+     * Why this exists separately from `setXY`: routing through
+     * `animate(el, _, { duration: 0 })` defers the write to Motion's
+     * scheduler, costing ~1 frame before the new position paints. For
+     * the projection-driven origin compensation (where a layout swap
+     * must keep the dragged element under the cursor in the SAME frame
+     * the swap commits), that frame of lag manifests as a visible
+     * wobble. This path lands synchronously. See #379 / the
+     * `adjustOrigin` hook below.
+     */
+    const setXYImmediate = (x, y) => {
+        const parts = [];
+        if (axis === true || axis === 'x')
+            parts.push(`translateX(${x}px)`);
+        if (axis === true || axis === 'y')
+            parts.push(`translateY(${y}px)`);
+        // Strip existing translate channels, keep the rest (scale/rotate/etc.).
+        const nonTranslate = el.style.transform.replace(/translate[XYZ3d]*\([^)]*\)/g, '').trim();
+        el.style.transform = [...parts, nonTranslate].filter(Boolean).join(' ');
+        if (axis === true || axis === 'x')
+            applied.x = x;
+        if (axis === true || axis === 'y')
+            applied.y = y;
+    };
+    /**
+     * Adjust the drag origin + visual offset by a layout-shift delta,
+     * mid-gesture, keeping the dragged element pinned under the cursor
+     * while its underlying layout slot moves.
+     *
+     * Direct port of framer-motion's projection `didUpdate` handler in
+     * `VisualElementDragControls.ts:742-758`:
+     *
+     * ```ts
+     * this.originPoint[axis] += delta[axis].translate
+     * motionValue.set(motionValue.get() + delta[axis].translate)
+     * ```
+     *
+     * We do the same two-write dance: shift `origin` (the gesture's
+     * reference zero) AND the applied visual transform by the same
+     * delta, so `lastPoint - startPoint + origin` continues to resolve
+     * to the correct on-screen position after the layout slot moved.
+     * Uses `setXYImmediate` so the compensation is visible the same
+     * frame as the layout change.
+     *
+     * Not wired to any projection node in this PR — exposed on the
+     * `attachDrag` return handle for the Reorder PR (#310) to call from
+     * its `ProjectionNode.didUpdate` listener.
+     *
+     * @param dx Layout delta on the x axis (px).
+     * @param dy Layout delta on the y axis (px).
+     */
+    const adjustOrigin = (dx, dy) => {
+        if (!dragging)
+            return;
+        // Compensate the origin on BOTH axes unconditionally — upstream's
+        // didUpdate handler applies the delta per-axis via `eachAxis`
+        // regardless of the drag axis or direction lock, because a layout
+        // slot can shift on either axis.
+        origin.x += dx;
+        origin.y += dy;
+        // The VISUAL write is `setXYImmediate`, which only writes the axis
+        // this drag manages (`opts.axis`). For the dragged axis that pins
+        // the element same-frame; the cross-axis case (e.g. drag="x" + a
+        // y-shift) only updates `origin`, not the transform. Fully
+        // rendering cross-axis compensation needs to route through the
+        // Motion value the move path uses (a direct write here would be
+        // wiped by the next `setXY`), so it's finalized when this hook is
+        // wired in #310. The common Reorder case (drag axis === the shift
+        // axis) is fully compensated today.
+        setXYImmediate(applied.x + dx, applied.y + dy);
+    };
     const startWhileDrag = () => {
         if (!opts.whileDrag)
             return;
@@ -758,7 +848,7 @@ export const attachDrag = (el, opts) => {
     }
     el.addEventListener('pointerdown', onPointerDown);
     pwLog('[drag] pointerdown listener attached', { el: EL_ID });
-    return () => {
+    const teardown = () => {
         pwLog('[drag] detach', { el: EL_ID });
         el.removeEventListener('pointerdown', onPointerDown);
         el.removeEventListener('pointermove', onPointerMove);
@@ -768,4 +858,5 @@ export const attachDrag = (el, opts) => {
         window.removeEventListener('pointerup', onPointerUp);
         window.removeEventListener('pointercancel', onPointerCancel);
     };
+    return Object.assign(teardown, { adjustOrigin });
 };

package/dist/utils/layout.d.ts

@@ -14,8 +14,19 @@ import { type AnimationOptions } from 'motion';
  *
  * Pass an empty array (or omit) for viewport-relative behaviour.
  *
+ * `baseTransform` is the value the element's `transform` is set to while
+ * measuring (default `'none'`, i.e. all transforms removed). The
+ * projection system passes the element's mount-time transform here so
+ * that a user-authored static `transform` is preserved in the
+ * measurement while only the motion-applied portion (written after
+ * mount) is removed — mirroring framer-motion's `removeBoxTransforms`,
+ * which only subtracts motion-tracked `latestValues` and leaves
+ * user-authored transforms intact. Existing FLIP callers omit it and
+ * get the original strip-everything behaviour.
+ *
  * @param el Element to measure.
  * @param scrollContainers Optional ancestor chain with `layoutScroll` enabled.
+ * @param baseTransform Transform string applied during measurement. Defaults to `'none'`.
  * @returns DOMRect snapshot of the element.
  *
  * @example
@@ -30,7 +41,20 @@ import { type AnimationOptions } from 'motion';
  * const rect = measureRect(node, [innerScroll, outerScroll])
  * ```
  */
-export declare const measureRect: (el: HTMLElement, scrollContainers?: HTMLElement[]) => DOMRect;
+export declare const measureRect: (el: HTMLElement, scrollContainers?: HTMLElement[], baseTransform?: string) => DOMRect;
+/**
+ * Minimal rectangle shape `computeFlipTransforms` reads. A `DOMRect`
+ * satisfies it structurally, and so does a projection `Box` converted to
+ * `{ left, top, width, height }`. Declared here (rather than importing
+ * the projection `Box`) so `layout.ts` stays free of a circular
+ * dependency on `projection.ts`, which imports `measureRect` from here.
+ */
+export interface RectLike {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
 /**
  * Compute FLIP transform deltas between two rects.
  *
@@ -39,7 +63,7 @@ export declare const measureRect: (el: HTMLElement, scrollContainers?: HTMLEleme
  * @param mode `true` for translate+scale, `'position'` for translate only.
  * @return Deltas and flags indicating which transforms to apply.
  */
-export declare const computeFlipTransforms: (prev: DOMRect, next: DOMRect, mode: boolean | "position") => {
+export declare const computeFlipTransforms: (prev: RectLike, next: RectLike, mode: boolean | "position") => {
     dx: number;
     dy: number;
     sx: number;

package/dist/utils/layout.js

@@ -14,8 +14,19 @@ import { animate } from 'motion';
  *
  * Pass an empty array (or omit) for viewport-relative behaviour.
  *
+ * `baseTransform` is the value the element's `transform` is set to while
+ * measuring (default `'none'`, i.e. all transforms removed). The
+ * projection system passes the element's mount-time transform here so
+ * that a user-authored static `transform` is preserved in the
+ * measurement while only the motion-applied portion (written after
+ * mount) is removed — mirroring framer-motion's `removeBoxTransforms`,
+ * which only subtracts motion-tracked `latestValues` and leaves
+ * user-authored transforms intact. Existing FLIP callers omit it and
+ * get the original strip-everything behaviour.
+ *
  * @param el Element to measure.
  * @param scrollContainers Optional ancestor chain with `layoutScroll` enabled.
+ * @param baseTransform Transform string applied during measurement. Defaults to `'none'`.
  * @returns DOMRect snapshot of the element.
  *
  * @example
@@ -30,10 +41,10 @@ import { animate } from 'motion';
  * const rect = measureRect(node, [innerScroll, outerScroll])
  * ```
  */
-export const measureRect = (el, scrollContainers) => {
+export const measureRect = (el, scrollContainers, baseTransform = 'none') => {
     const prev = el.style.transform;
     try {
-        el.style.transform = 'none';
+        el.style.transform = baseTransform;
         const rect = el.getBoundingClientRect();
         if (!scrollContainers || scrollContainers.length === 0)
             return rect;

package/dist/utils/pan.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Pan gesture session.
+ *
+ * Direct port of framer-motion's `PanSession`
+ * (`packages/framer-motion/src/gestures/pan/PanSession.ts`) and `PanGesture`
+ * (`packages/framer-motion/src/gestures/pan/index.ts`). Pan is the
+ * primitive that powers swipe-to-dismiss drawers, swipe-to-delete rows,
+ * carousels, and any gesture that tracks pointer offset/velocity without
+ * the constraint/momentum/snap-to-origin baggage of `drag`.
+ *
+ * Critical design notes (mirrors upstream):
+ *
+ * - `pointermove`, `pointerup`, `pointercancel` subscribe on the
+ *   `contextWindow` (defaults to `window`), NOT the source element. This
+ *   keeps the gesture alive even when the pointer leaves the element's
+ *   bounds during a fast swipe — the original element is only used for
+ *   the initial `pointerdown` and for scroll-compensation tracking.
+ *
+ * - `distanceThreshold` (default `3`px) gates the `onStart` callback so
+ *   a steady press without movement doesn't fire a pan. `onSessionStart`
+ *   fires immediately on pointerdown for setup work.
+ *
+ * - Per-frame throttling via `frame.update(updatePoint, true)` so a flood
+ *   of pointermove events doesn't run handlers more than once per render
+ *   frame. On top of that, individual handlers are routed onto motion-dom's
+ *   step lanes (see `wrapUpdate` / `wrapPostRender` above):
+ *   `onSessionStart` / `onStart` / `onMove` land on `update`,
+ *   `onEnd` / `onSessionEnd` on `postRender`. Matches upstream's
+ *   `asyncHandler` + `frame.postRender` split byte-for-byte.
+ *
+ * - `getPanInfo` returns `{ point, delta, offset, velocity }` — identical
+ *   shape to motion-dom's `DragInfo` / framer-motion's `PanInfo`.
+ *
+ * - Velocity uses a 100ms history window with the "skip the pointer-down
+ *   origin if it's too stale" tweak upstream added for hold-then-flick
+ *   gestures.
+ */
+import type { DragInfo } from '../types';
+export interface PanHandlers {
+    /** Fires on `pointerdown` regardless of whether movement follows. */
+    onSessionStart?: (event: PointerEvent, info: DragInfo) => void;
+    /** Fires the first time pointer offset crosses `distanceThreshold`. */
+    onStart?: (event: PointerEvent, info: DragInfo) => void;
+    /** Fires on every per-frame-throttled pointermove past threshold. */
+    onMove?: (event: PointerEvent, info: DragInfo) => void;
+    /** Fires on `pointerup` / `pointercancel` if `onStart` ever fired. */
+    onEnd?: (event: PointerEvent, info: DragInfo) => void;
+    /** Fires on `pointerup` / `pointercancel` always (paired with `onSessionStart`). */
+    onSessionEnd?: (event: PointerEvent, info: DragInfo) => void;
+}
+export interface AttachPanOptions {
+    /**
+     * Movement distance (in pixels) required before `onStart`/`onMove`
+     * fire. Default `3` — same as framer-motion. A steady press with
+     * sub-threshold drift is reported via `onSessionStart` / `onSessionEnd`
+     * only.
+     */
+    distanceThreshold?: number;
+    /**
+     * Window to attach the move/up/cancel listeners to. Defaults to the
+     * source element's owner window. Override for iframe / shadow-root
+     * scenarios.
+     */
+    contextWindow?: Window | null;
+}
+/**
+ * Cleanup function returned by `attachPan`. Carries an `update` method
+ * that hot-swaps the live handler set without tearing down the active
+ * `PanSession` — call this when a consumer's `onPan` reference changes
+ * mid-gesture (the canonical Svelte 5 pattern of inline arrow handlers
+ * passes a fresh closure every render). Without this, the host
+ * `$effect` would have to teardown + re-attach and the user's in-flight
+ * pan would silently die.
+ */
+export type AttachPanCleanup = (() => void) & {
+    update: (next: PanHandlers) => void;
+};
+/**
+ * Attach a pan gesture session to `el`. Returns a cleanup function that
+ * tears down the pointerdown listener and ends any in-flight session,
+ * with a `.update(next)` method for hot-swapping handlers mid-gesture.
+ *
+ * Internally a fresh `PanSession` spawns on each pointerdown — the
+ * outer attachment just keeps the pointerdown listener alive across the
+ * element's lifetime.
+ *
+ * SSR-safe: returns a no-op cleanup if `window` is undefined. The Svelte
+ * `$effect` consumer never fires on the server anyway, but defending the
+ * boundary lets the module load cleanly in node-only test runners.
+ *
+ * Lifecycle guarantee: when the returned cleanup runs mid-gesture, the
+ * session synthesizes `onEnd` + `onSessionEnd` against the raw handlers
+ * BEFORE removing listeners (see `PanSession.dispatchTerminal`). Hosts
+ * (e.g. `_MotionContainer`'s pan `$effect`) can put their `whilePan`
+ * revert logic inside the user-supplied `onEnd` and rely on it firing
+ * exactly once per gesture — whether the user released or the host
+ * forced teardown.
+ *
+ * @param el Target element to bind `pointerdown` on. Move/up/cancel
+ *   events are listened for on the element's owning window so a fast
+ *   swipe past the element's bounds keeps the gesture alive.
+ * @param handlers Pan lifecycle handlers. Any subset of
+ *   `onSessionStart` (fires on pointerdown), `onStart` (fires the first
+ *   time the cumulative offset crosses `distanceThreshold`), `onMove`
+ *   (per-frame-throttled on every pointermove past threshold), `onEnd`
+ *   (fires on pointerup/cancel if `onStart` ever fired), `onSessionEnd`
+ *   (fires on every pointerup/cancel where a pointermove occurred).
+ * @param options Per-session config. `distanceThreshold` (default 3px)
+ *   gates the start callback; `contextWindow` overrides the owning
+ *   window (use for shadow-root / iframe scenarios).
+ * @returns A cleanup function with an attached `.update(next)` method.
+ *   Calling the cleanup ends the session + removes the pointerdown
+ *   listener. Calling `.update(next)` swaps handlers in place on the
+ *   live session without rebuilding it — the canonical Svelte pattern
+ *   for inline arrow handlers that change identity each render.
+ *
+ * @example
+ * ```ts
+ * const cleanup = attachPan(node, {
+ *   onStart: (_event, info) => console.log('start', info.offset),
+ *   onMove: (_event, info) => x.set(info.offset.x),
+ *   onEnd: (_event, info) => {
+ *     if (Math.abs(info.velocity.x) > 600) commit()
+ *     else animate(x, 0, { type: 'spring' })
+ *   }
+ * })
+ *
+ * // Later, swap handlers without ending the live gesture:
+ * cleanup.update({ onMove: (_e, info) => x.set(info.offset.x * 2) })
+ *
+ * // On unmount:
+ * cleanup()
+ * ```
+ */
+export declare const attachPan: (el: HTMLElement, handlers: PanHandlers, options?: AttachPanOptions) => AttachPanCleanup;