@humanspeak/svelte-motion 0.5.2 → 0.5.4

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/projection.d.ts

@@ -0,0 +1,287 @@
+/**
+ * Local mirrors of `motion-utils`'s `Axis` / `Box` / `AxisDelta` /
+ * `Delta` types. Inlined because `motion-utils` is a runtime-only
+ * transitive dep through `motion-dom` — the runtime helpers
+ * (`calcBoxDelta`, `createDelta`, `isDeltaZero`) are re-exported, but
+ * the type aliases are not. Same approach we use in
+ * `src/lib/components/Reorder/context.ts`.
+ *
+ * Values match upstream byte-for-byte so handoff between our types and
+ * the runtime helpers from motion-dom is implicit.
+ */
+export interface Axis {
+    min: number;
+    max: number;
+}
+export interface Box {
+    x: Axis;
+    y: Axis;
+}
+export interface AxisDelta {
+    translate: number;
+    scale: number;
+    origin: number;
+    originPoint: number;
+}
+export interface Delta {
+    x: AxisDelta;
+    y: AxisDelta;
+}
+/**
+ * Event names the projection node fans out. Mirrors framer-motion's
+ * `LayoutEvents` subset that's actually consumed externally.
+ *
+ * - `willUpdate` — fires inside `willUpdate()`, AFTER the pre-mutation
+ *   snapshot has been captured. Receives the snapshot Box.
+ * - `didUpdate` — fires inside `didUpdate()`, AFTER the post-mutation
+ *   re-measure. Receives the full `LayoutUpdateData` payload (layout,
+ *   snapshot, delta, hasLayoutChanged).
+ * - `measure` — fires every time `measure()` returns a non-null Box.
+ *   Useful for debug overlays and follow-up event consumers.
+ */
+export type ProjectionEventName = 'willUpdate' | 'didUpdate' | 'measure';
+/**
+ * Payload delivered to `didUpdate` listeners.
+ *
+ * `layout` is the post-mutation measurement; `snapshot` is the
+ * pre-mutation one. `delta` is `calcBoxDelta(snapshot, layout)` and is
+ * the value drag-listeners apply via `originPoint += delta.translate`
+ * + `motionValue.set(motionValue.get() + delta.translate)` to keep a
+ * dragged element under the cursor while its slot moves.
+ *
+ * `hasLayoutChanged` is `!isDeltaZero(delta)`. `isDeltaZero` (from
+ * motion-dom) treats an axis as unchanged only when its translate is
+ * within ±0.01px and its scale within ±0.0001 of identity — a tight
+ * floating-point epsilon, NOT a 1px rounding threshold. A genuine
+ * sub-pixel layout shift (say 0.4px) is therefore reported as a change.
+ */
+export interface ProjectionDidUpdateData {
+    layout: Box;
+    snapshot: Box;
+    delta: Delta;
+    hasLayoutChanged: boolean;
+}
+type Listener<E extends ProjectionEventName> = E extends 'didUpdate' ? (data: ProjectionDidUpdateData) => void : E extends 'willUpdate' ? (snapshot: Box) => void : (layout: Box) => void;
+/**
+ * Options passed at `ProjectionNode` construction time. All optional —
+ * a node with no options still works as a leaf measurement target.
+ */
+export interface ProjectionNodeOptions {
+    /**
+     * Parent node in the projection tree. Wire-up is callsite-driven
+     * (the consumer reads `getProjectionParent()` from the Svelte
+     * context system and passes the result here); the node stores it
+     * as `this.parent` and registers self in `parent.children` on
+     * `mount()`.
+     */
+    parent?: ProjectionNode | null;
+    /**
+     * Thunk returning the `layoutScroll` ancestor chain at measure
+     * time. Used as the second argument to `measureRect`, which
+     * shifts the returned rect by the sum of ancestor
+     * `scrollLeft`/`scrollTop` so FLIP deltas stay correct when
+     * scrollable ancestors scroll between two measurements.
+     *
+     * Returning `[]` (or omitting the option entirely) gives
+     * viewport-relative measurements — fine for the common case.
+     */
+    getScrollContainers?: () => HTMLElement[];
+    /**
+     * Thunk returning the element's USER-authored `transform` — the
+     * value `measure()` resets to while reading, so the motion-applied
+     * portion (`initial`/`animate`/FLIP/drag) is stripped but the user's
+     * own transform is preserved.
+     *
+     * Preferred over the mount-time `baseTransform` capture, because at
+     * mount the inline `style.transform` already carries any
+     * transform-type `initial` keyframe (it is serialized inline before
+     * effects run). The consumer therefore sources this from the `style`
+     * prop instead (see `extractTransform`). When omitted, the node
+     * falls back to the mount-captured `baseTransform`.
+     */
+    getBaseTransform?: () => string;
+}
+/**
+ * Per-element node in the projection tree. Created at component setup
+ * time in `_MotionContainer.svelte`, mounted when the element ref
+ * binds, unmounted on cleanup.
+ *
+ * Lifecycle:
+ * 1. `new ProjectionNode({ parent, getScrollContainers })` at setup.
+ * 2. `node.mount(element)` once the element ref binds.
+ * 3. `node.willUpdate()` before any layout-mutating state change (e.g.
+ *    a `values` reassign that reorders DOM children).
+ * 4. State mutates → Svelte commits the DOM update.
+ * 5. `node.didUpdate()` after the DOM update is flushed — fires
+ *    `didUpdate` listeners with the snapshot→current delta.
+ * 6. `node.unmount()` on cleanup.
+ */
+export declare class ProjectionNode {
+    /** The mounted element. `null` until `mount()` runs. */
+    element: HTMLElement | null;
+    /**
+     * Parent node in the projection tree. Captured at construction
+     * from the Svelte context. Set to `null` for root-level motion
+     * elements that have no motion ancestor.
+     */
+    parent: ProjectionNode | null;
+    /**
+     * Descendant nodes registered via `mount()`. Iterated when we
+     * need to broadcast to the subtree (none in this PR; reserved
+     * for follow-up work).
+     */
+    readonly children: Set<ProjectionNode>;
+    /** Most-recent post-mutation measurement, or `null` before first measure. */
+    latestLayout: Box | null;
+    /**
+     * Pre-mutation snapshot captured by `willUpdate`. Cleared by
+     * `didUpdate` after the delta has been computed. Idempotent for
+     * repeat `willUpdate` calls in the same frame — only the first
+     * snapshots; subsequent calls no-op so a parent broadcasting
+     * `willUpdate` to its children doesn't clobber a child's own
+     * earlier snapshot.
+     */
+    snapshot: Box | null;
+    /** Whether `mount()` has been called and `unmount()` has not. */
+    isMounted: boolean;
+    /**
+     * Fallback user-authored base transform, captured from
+     * `element.style.transform` at `mount()` time. Used only when no
+     * `getBaseTransform` thunk was provided (e.g. unit tests that
+     * construct a bare node and set the transform before mounting).
+     *
+     * For real `motion.*` elements the `getBaseTransform` thunk is
+     * preferred: capturing at mount is unsafe because a transform-type
+     * `initial` keyframe is serialized into the inline `style.transform`
+     * BEFORE effects run, so the mount-time value can be a motion
+     * transform rather than the user's. `resolveBaseTransform()` picks
+     * the thunk first.
+     *
+     * `measure()` resets ancestors (and self, via `measureRect`) to this
+     * base rather than to `'none'`, removing the motion-applied portion
+     * while leaving the user-authored part intact — the same distinction
+     * framer-motion draws by only subtracting motion-tracked
+     * `latestValues` in `removeBoxTransforms`.
+     */
+    baseTransform: string;
+    private readonly listeners;
+    private readonly getScrollContainers;
+    private readonly getBaseTransform;
+    constructor(options?: ProjectionNodeOptions);
+    /**
+     * The transform `measure()` resets this node's element to while
+     * reading. Prefers the `getBaseTransform` thunk (the user's authored
+     * `style` transform, motion-independent); falls back to the
+     * mount-captured `baseTransform`. See `getBaseTransform` /
+     * `baseTransform` for why the thunk is the safe source.
+     */
+    private resolveBaseTransform;
+    /**
+     * Register this node with its parent + bind to a DOM element.
+     * Idempotent — calling `mount()` twice on the same element is a
+     * no-op for the registration steps.
+     *
+     * Re-mounting onto a DIFFERENT element swaps the element in place
+     * WITHOUT a full `unmount()`. A full unmount would `children.clear()`,
+     * orphaning still-mounted descendants that registered themselves in
+     * this node's `children` (they keep their `parent` pointer but the
+     * set would never be repopulated). Listeners and children are
+     * therefore preserved across an element swap.
+     *
+     * @param element The DOM element this node represents.
+     */
+    mount(element: HTMLElement): void;
+    /**
+     * Tear down. Detaches from parent, clears children references,
+     * drops all listeners. Safe to call on a never-mounted node and
+     * safe to call twice.
+     */
+    unmount(): void;
+    /**
+     * Read the element's layout box with every ancestor's
+     * motion-applied transform temporarily removed, while preserving
+     * each ancestor's user-authored base transform.
+     *
+     * Mechanism:
+     * 1. Walk `this.parent` chain bottom-up, collecting every
+     *    mounted ancestor node (excludes self — `measureRect`
+     *    handles self's transform internally).
+     * 2. Snapshot each ancestor's current `el.style.transform`.
+     * 3. Set each to its node's resolved base transform (the
+     *    user-authored value, via `resolveBaseTransform`). This strips
+     *    any FLIP/drag/initial transform while keeping the user's static
+     *    one — see `getBaseTransform` / `baseTransform`.
+     * 4. Delegate to `measureRect(self.element, scrollContainers,
+     *    self base)`, which applies self's base transform inside its own
+     *    try/finally and returns the scroll-compensated DOMRect.
+     * 5. Restore ancestor transforms in reverse order inside a
+     *    `finally` block — guarantees restoration even if measure
+     *    throws.
+     * 6. Convert DOMRect → Box and cache as `latestLayout`.
+     *
+     * Returns `null` when `element` is not mounted.
+     */
+    measure(): Box | null;
+    /**
+     * Snapshot the current layout box for use by the next
+     * `didUpdate()`. Caller's contract: invoke this BEFORE the
+     * layout-mutating state change so the snapshot reflects the
+     * pre-mutation position.
+     *
+     * Idempotent within a frame — once a snapshot exists, subsequent
+     * `willUpdate()` calls are no-ops until `didUpdate()` consumes it.
+     * This means a parent that broadcasts `willUpdate` to its
+     * children before its own snapshot is fine: children snapshot
+     * themselves first via their own willUpdate, parent's broadcast
+     * is a no-op.
+     */
+    willUpdate(): void;
+    /**
+     * Re-measure post-mutation, compute the delta against the
+     * snapshot, fire `didUpdate` listeners. No-op when there's no
+     * snapshot (matches upstream — `willUpdate` MUST precede
+     * `didUpdate` for the cycle to fire).
+     *
+     * Always clears the snapshot at the end so the next gesture's
+     * `willUpdate`/`didUpdate` cycle starts fresh.
+     */
+    didUpdate(): void;
+    /**
+     * Observer-driven layout-change commit. Unlike the explicit
+     * `willUpdate()` → mutate → `didUpdate()` cycle (used when a
+     * consumer controls the exact mutation moment, e.g. Reorder.Group
+     * before a `values` reassign), this is for the reactive path where
+     * a layout change has ALREADY happened and we only learn about it
+     * after the fact (the existing `observeLayoutChanges` FLIP loop in
+     * `_MotionContainer`).
+     *
+     * Uses the cached `latestLayout` (the pre-change position from
+     * mount or the previous commit) as the snapshot, re-measures the
+     * post-change position, and fires `didUpdate` with the delta.
+     *
+     * First call after mount just seeds `latestLayout` (no prior
+     * position to diff against) and fires nothing.
+     *
+     * Returns the freshly-measured `Box` (or `null` when unmounted) so
+     * the caller can reuse it — the FLIP loop in `_MotionContainer` uses
+     * this as its `next` rect instead of measuring a second time per
+     * frame.
+     *
+     * The `didUpdate` fan-out is gated on a non-zero delta. The FLIP
+     * animation this commit runs alongside writes its own inverse
+     * `transform` to the element every frame, and those writes re-trigger
+     * the same `observeLayoutChanges` signal that drives this method.
+     * Those re-fires carry no real layout change (the ancestor-stripped
+     * measure is identical to the previous one), so without the
+     * `isDeltaZero` gate every animation frame would fan out a `delta: 0`
+     * event and clobber the genuine delta from the originating change.
+     */
+    commitLayoutChange(): Box | null;
+    /**
+     * Subscribe to a projection event. Returns an unsubscribe
+     * function. Safe to call after `unmount()` (becomes a no-op).
+     */
+    addEventListener<E extends ProjectionEventName>(name: E, cb: Listener<E>): () => void;
+    private notify;
+}
+export {};