@humanspeak/svelte-motion 0.5.4 → 0.6.0

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export type { MotionTemplateInput } from './utils/motionTemplate.svelte';
 export { useMotionValue } from './utils/motionValue.svelte';
 export type { MotionValue, RawMotionValue } from './utils/motionValue.svelte';
 export { useMotionValueEvent } from './utils/motionValueEvent';
+export { optimizedAppearDataAttribute, startOptimizedAppearAnimation } from './utils/optimizedAppear';
 export { useReducedMotion } from './utils/reducedMotion.svelte';
 export type { ReducedMotionState } from './utils/reducedMotion.svelte';
 export { useReducedMotionConfig } from './utils/reducedMotionConfig.svelte';

package/dist/index.js

@@ -23,6 +23,7 @@ export { useInView } from './utils/inView.svelte';
 export { useMotionTemplate } from './utils/motionTemplate.svelte';
 export { useMotionValue } from './utils/motionValue.svelte';
 export { useMotionValueEvent } from './utils/motionValueEvent';
+export { optimizedAppearDataAttribute, startOptimizedAppearAnimation } from './utils/optimizedAppear';
 export { useReducedMotion } from './utils/reducedMotion.svelte';
 export { useReducedMotionConfig } from './utils/reducedMotionConfig.svelte';
 export { useScroll } from './utils/scroll.svelte';

package/dist/types.d.ts

@@ -431,8 +431,8 @@ export type MotionProps = {
     style?: string;
     /** CSS classes */
     class?: string;
-    /** Enable FLIP layout animations; "position" limits to translation only */
-    layout?: boolean | 'position';
+    /** Enable FLIP layout animations; string values select the upstream projection animation type. */
+    layout?: boolean | 'position' | 'size' | 'preserve-aspect';
     /**
      * Fires after each `layout`-driven change with the FLIP delta from
      * the element's internal projection node. Mirrors framer-motion's

package/dist/utils/layout.d.ts

@@ -6,11 +6,13 @@ import { type AnimationOptions } from 'motion';
  * immediately after reading the rect.
  *
  * When `scrollContainers` are provided, the returned rect is shifted by the
- * **sum** of each container's `scrollLeft` / `scrollTop`. FLIP deltas
- * computed from two such measures stay correct even when the user scrolls
- * any of the containers between measurements — including a nested
- * `layoutScroll` inside another `layoutScroll`. Mirrors framer-motion's
- * `removeElementScroll`, which walks every ancestor in the path.
+ * **sum** of each container's `scrollLeft` / `scrollTop`. When
+ * `includeViewportScroll` is true, the viewport's `window.scrollX` /
+ * `window.scrollY` is included too. FLIP deltas computed from two such
+ * measures stay correct even when the user scrolls between measurements —
+ * including a nested `layoutScroll` inside another `layoutScroll`. Mirrors
+ * framer-motion's `removeElementScroll`, which walks every ancestor in the
+ * path, plus root scroll compensation from the projection tree.
  *
  * Pass an empty array (or omit) for viewport-relative behaviour.
  *
@@ -27,6 +29,7 @@ import { type AnimationOptions } from 'motion';
  * @param el Element to measure.
  * @param scrollContainers Optional ancestor chain with `layoutScroll` enabled.
  * @param baseTransform Transform string applied during measurement. Defaults to `'none'`.
+ * @param includeViewportScroll Whether to include `window.scrollX/Y` in the returned rect.
  * @returns DOMRect snapshot of the element.
  *
  * @example
@@ -41,7 +44,7 @@ import { type AnimationOptions } from 'motion';
  * const rect = measureRect(node, [innerScroll, outerScroll])
  * ```
  */
-export declare const measureRect: (el: HTMLElement, scrollContainers?: HTMLElement[], baseTransform?: string) => DOMRect;
+export declare const measureRect: (el: HTMLElement, scrollContainers?: HTMLElement[], baseTransform?: string, includeViewportScroll?: boolean) => DOMRect;
 /**
  * Minimal rectangle shape `computeFlipTransforms` reads. A `DOMRect`
  * satisfies it structurally, and so does a projection `Box` converted to

package/dist/utils/layout.js

@@ -1,4 +1,102 @@
 import { animate } from 'motion';
+const layoutSizeAnimationAttribute = 'data-layout-size-animation';
+const px = (value) => `${Math.max(0, value)}px`;
+const isViewportOffscreen = (el) => {
+    if (typeof window === 'undefined')
+        return false;
+    const rect = el.getBoundingClientRect();
+    return (rect.bottom <= 0 ||
+        rect.right <= 0 ||
+        rect.top >= window.innerHeight ||
+        rect.left >= window.innerWidth);
+};
+const runBoxSizeAnimation = (el, transforms, transition) => {
+    const { dx, dy, sx, sy } = transforms;
+    const originalWidth = el.style.width;
+    const originalHeight = el.style.height;
+    const originalTransform = el.style.transform;
+    const originalTransformOrigin = el.style.transformOrigin;
+    const nextRect = el.getBoundingClientRect();
+    const prevWidth = nextRect.width * sx;
+    const prevHeight = nextRect.height * sy;
+    el.setAttribute(layoutSizeAnimationAttribute, 'true');
+    for (const child of el.querySelectorAll('[data-svelte-motion-layout]')) {
+        child.style.transform = '';
+        child.style.transformOrigin = '';
+        if (child.style.willChange === 'transform')
+            child.style.willChange = '';
+    }
+    el.style.width = px(prevWidth);
+    el.style.height = px(prevHeight);
+    const sizedRect = el.getBoundingClientRect();
+    const residualDx = nextRect.left + dx - sizedRect.left;
+    const residualDy = nextRect.top + dy - sizedRect.top;
+    const shouldTranslate = Math.abs(residualDx) > 0.5 || Math.abs(residualDy) > 0.5;
+    const keyframes = {
+        width: [px(prevWidth), px(nextRect.width)],
+        height: [px(prevHeight), px(nextRect.height)]
+    };
+    if (shouldTranslate) {
+        keyframes.x = [residualDx, 0];
+        keyframes.y = [residualDy, 0];
+        el.style.transformOrigin = '0 0';
+        el.style.transform = `translate(${residualDx}px, ${residualDy}px)`;
+    }
+    const animation = animate(el, keyframes, transition);
+    let removeScrollListener;
+    let offscreenRaf = null;
+    let cleanupRan = false;
+    const cleanup = () => {
+        if (cleanupRan)
+            return;
+        cleanupRan = true;
+        removeScrollListener?.();
+        if (offscreenRaf !== null &&
+            typeof window !== 'undefined' &&
+            typeof window.cancelAnimationFrame === 'function') {
+            window.cancelAnimationFrame(offscreenRaf);
+            offscreenRaf = null;
+        }
+        el.style.width = originalWidth;
+        el.style.height = originalHeight;
+        el.style.transformOrigin = originalTransformOrigin;
+        el.style.transform = originalTransform;
+        el.removeAttribute(layoutSizeAnimationAttribute);
+    };
+    if (typeof window !== 'undefined') {
+        const completeIfOffscreen = () => {
+            if (cleanupRan)
+                return;
+            if (isViewportOffscreen(el)) {
+                animation.complete();
+                cleanup();
+            }
+        };
+        const scheduleCompleteIfOffscreen = () => {
+            if (typeof window.requestAnimationFrame !== 'function') {
+                completeIfOffscreen();
+                return;
+            }
+            if (offscreenRaf !== null)
+                return;
+            offscreenRaf = window.requestAnimationFrame(() => {
+                offscreenRaf = null;
+                completeIfOffscreen();
+            });
+        };
+        const handleScroll = () => {
+            completeIfOffscreen();
+            scheduleCompleteIfOffscreen();
+        };
+        window.addEventListener('scroll', handleScroll, { passive: true });
+        removeScrollListener = () => {
+            window.removeEventListener('scroll', handleScroll);
+        };
+        completeIfOffscreen();
+        scheduleCompleteIfOffscreen();
+    }
+    animation.finished?.finally(cleanup);
+};
 /**
  * Measure an element's bounding client rect without current transform.
  *
@@ -6,11 +104,13 @@ import { animate } from 'motion';
  * immediately after reading the rect.
  *
  * When `scrollContainers` are provided, the returned rect is shifted by the
- * **sum** of each container's `scrollLeft` / `scrollTop`. FLIP deltas
- * computed from two such measures stay correct even when the user scrolls
- * any of the containers between measurements — including a nested
- * `layoutScroll` inside another `layoutScroll`. Mirrors framer-motion's
- * `removeElementScroll`, which walks every ancestor in the path.
+ * **sum** of each container's `scrollLeft` / `scrollTop`. When
+ * `includeViewportScroll` is true, the viewport's `window.scrollX` /
+ * `window.scrollY` is included too. FLIP deltas computed from two such
+ * measures stay correct even when the user scrolls between measurements —
+ * including a nested `layoutScroll` inside another `layoutScroll`. Mirrors
+ * framer-motion's `removeElementScroll`, which walks every ancestor in the
+ * path, plus root scroll compensation from the projection tree.
  *
  * Pass an empty array (or omit) for viewport-relative behaviour.
  *
@@ -27,6 +127,7 @@ import { animate } from 'motion';
  * @param el Element to measure.
  * @param scrollContainers Optional ancestor chain with `layoutScroll` enabled.
  * @param baseTransform Transform string applied during measurement. Defaults to `'none'`.
+ * @param includeViewportScroll Whether to include `window.scrollX/Y` in the returned rect.
  * @returns DOMRect snapshot of the element.
  *
  * @example
@@ -41,19 +142,22 @@ import { animate } from 'motion';
  * const rect = measureRect(node, [innerScroll, outerScroll])
  * ```
  */
-export const measureRect = (el, scrollContainers, baseTransform = 'none') => {
+export const measureRect = (el, scrollContainers, baseTransform = 'none', includeViewportScroll = false) => {
     const prev = el.style.transform;
     try {
         el.style.transform = baseTransform;
         const rect = el.getBoundingClientRect();
-        if (!scrollContainers || scrollContainers.length === 0)
-            return rect;
+        let offsetLeft = includeViewportScroll && typeof window !== 'undefined' ? window.scrollX : 0;
+        let offsetTop = includeViewportScroll && typeof window !== 'undefined' ? window.scrollY : 0;
+        if (!scrollContainers || scrollContainers.length === 0) {
+            if (offsetLeft === 0 && offsetTop === 0)
+                return rect;
+            return new DOMRect(rect.left + offsetLeft, rect.top + offsetTop, rect.width, rect.height);
+        }
         // Re-express the rect in the *combined* scroll-container coordinate
         // space so a subsequent scroll on any of them doesn't show up as
         // movement. DOMRect's left/top are read-only, so allocate a fresh
         // one with the summed offsets applied.
-        let offsetLeft = 0;
-        let offsetTop = 0;
         for (const container of scrollContainers) {
             offsetLeft += container.scrollLeft;
             offsetTop += container.scrollTop;
@@ -95,6 +199,13 @@ export const runFlipAnimation = (el, transforms, transition) => {
     const { dx, dy, sx, sy, shouldTranslate, shouldScale } = transforms;
     if (!(shouldTranslate || shouldScale))
         return;
+    const correctionTargets = shouldScale
+        ? Array.from(el.querySelectorAll('[data-svelte-motion-layout]'))
+        : [];
+    if (shouldScale && correctionTargets.length > 0) {
+        runBoxSizeAnimation(el, { dx, dy, sx, sy }, transition);
+        return;
+    }
     const keyframes = {};
     if (shouldTranslate) {
         keyframes.x = [dx, 0];
@@ -140,6 +251,13 @@ export const observeLayoutChanges = (el, onChange) => {
     let pendingRaf = null;
     let releaseTimeout = null;
     const schedule = () => {
+        if (el.closest(`[${layoutSizeAnimationAttribute}]`)) {
+            el.style.transform = '';
+            el.style.transformOrigin = '';
+            if (el.style.willChange === 'transform')
+                el.style.willChange = '';
+            return;
+        }
         if (pendingRaf !== null || releaseTimeout !== null)
             return;
         // Leading-edge: call immediately, then throttle further calls until next frame (or 50ms)
@@ -157,14 +275,23 @@ export const observeLayoutChanges = (el, onChange) => {
     };
     const ro = new ResizeObserver(() => schedule());
     ro.observe(el);
-    const mo = new MutationObserver(() => schedule());
-    mo.observe(el, { attributes: true, attributeFilter: ['class', 'style'] });
+    const attributeObserver = new MutationObserver(() => schedule());
+    attributeObserver.observe(el, {
+        attributes: true,
+        attributeFilter: ['class', 'style', 'data-presence-layout-hold']
+    });
+    const childListObserver = new MutationObserver(() => schedule());
+    childListObserver.observe(el, {
+        childList: true,
+        subtree: true
+    });
     if (el.parentElement) {
-        mo.observe(el.parentElement, { childList: true, subtree: false, attributes: true });
+        childListObserver.observe(el.parentElement, { childList: true, subtree: false });
     }
     return () => {
         ro.disconnect();
-        mo.disconnect();
+        attributeObserver.disconnect();
+        childListObserver.disconnect();
         if (pendingRaf !== null && typeof cancelAnimationFrame === 'function') {
             cancelAnimationFrame(pendingRaf);
             pendingRaf = null;

package/dist/utils/motionDomProjection.d.ts

@@ -0,0 +1,126 @@
+import { type IProjectionNode, type ResolvedValues, type Transition, type VisualElement } from 'motion-dom';
+type ProjectionVisualElement = VisualElement & {
+    latestValues: ResolvedValues;
+    projection?: IProjectionNode<HTMLElement>;
+};
+type LayoutOption = boolean | string | undefined;
+export interface MotionDomProjectionOptions {
+    /** Parent adapter used to connect this node into the upstream projection tree. */
+    parent?: MotionDomProjectionAdapter | null;
+}
+/**
+ * Latest layout-related motion props applied to an upstream projection node.
+ */
+export interface MotionDomProjectionUpdateOptions {
+    /** Enables layout projection and selects the upstream animation type. */
+    layout?: LayoutOption;
+    /** Shared layout id used by upstream projection matching. */
+    layoutId?: string;
+    /** Transition passed to the upstream layout animation builder. */
+    transition?: Transition;
+    /** Inline style props passed through to the visual element. */
+    style?: unknown;
+}
+/**
+ * Svelte lifecycle adapter for motion-dom's upstream projection node system.
+ *
+ * The public Svelte API stays unchanged (`layout`, `layoutId`, `transition`).
+ * This adapter only translates those props into the same `HTMLProjectionNode`
+ * and `HTMLVisualElement` internals Framer Motion uses.
+ */
+export declare class MotionDomProjectionAdapter {
+    readonly visualElement: ProjectionVisualElement;
+    readonly projection: IProjectionNode<HTMLElement>;
+    private element;
+    private layout;
+    private layoutId;
+    private transition;
+    private lastLayout;
+    constructor(options?: MotionDomProjectionOptions);
+    /**
+     * Update projection options from current Svelte props.
+     *
+     * @param options Current layout-related motion props.
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.updateOptions({ layout, layoutId, transition, style })
+     * ```
+     */
+    updateOptions(options: MotionDomProjectionUpdateOptions): void;
+    /**
+     * Mount the upstream projection node to an element and seed its layout.
+     *
+     * @param element Element represented by the current motion component.
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.mount(element)
+     * ```
+     */
+    mount(element: HTMLElement): void;
+    /**
+     * Unmount the upstream projection node and clear its visual-element store.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.unmount()
+     * ```
+     */
+    unmount(): void;
+    /**
+     * Capture the upstream "before" snapshot.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.willUpdate()
+     * ```
+     */
+    willUpdate(): void;
+    /**
+     * Commit an upstream layout update after Svelte has patched the DOM.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.didUpdate()
+     * ```
+     */
+    didUpdate(): void;
+    /**
+     * Seed the current layout without animating.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.seedLayout()
+     * ```
+     */
+    seedLayout(): void;
+    /**
+     * Animate from the last cached layout to the current observed layout.
+     *
+     * This covers layout changes discovered after the mutation by observers.
+     * Svelte runes mode doesn't expose the same component pre/post-update
+     * hooks Framer Motion uses in React, so this adapter reuses upstream
+     * projection while the Svelte component controls the snapshot timing.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.commitObservedLayoutChange()
+     * ```
+     */
+    commitObservedLayoutChange(): void;
+    private refreshCachedLayout;
+}
+export {};

package/dist/utils/motionDomProjection.js

@@ -0,0 +1,212 @@
+import { HTMLProjectionNode, HTMLVisualElement, copyBoxInto, createBox, visualElementStore } from 'motion-dom';
+const createVisualState = () => ({
+    latestValues: {},
+    renderState: {
+        transform: {},
+        transformOrigin: {},
+        style: {},
+        vars: {}
+    }
+});
+const cloneMeasurements = (measurements) => {
+    if (!measurements)
+        return undefined;
+    const measuredBox = createBox();
+    const layoutBox = createBox();
+    copyBoxInto(measuredBox, measurements.measuredBox);
+    copyBoxInto(layoutBox, measurements.layoutBox);
+    return {
+        animationId: measurements.animationId,
+        measuredBox,
+        layoutBox,
+        latestValues: { ...measurements.latestValues },
+        source: measurements.source
+    };
+};
+const animationTypes = new Set([
+    'position',
+    'x',
+    'y',
+    'size',
+    'both',
+    'preserve-aspect'
+]);
+const animationTypeForLayout = (layout) => typeof layout === 'string' && animationTypes.has(layout)
+    ? layout
+    : 'both';
+/**
+ * Svelte lifecycle adapter for motion-dom's upstream projection node system.
+ *
+ * The public Svelte API stays unchanged (`layout`, `layoutId`, `transition`).
+ * This adapter only translates those props into the same `HTMLProjectionNode`
+ * and `HTMLVisualElement` internals Framer Motion uses.
+ */
+export class MotionDomProjectionAdapter {
+    visualElement;
+    projection;
+    element = null;
+    layout;
+    layoutId;
+    transition;
+    lastLayout;
+    constructor(options = {}) {
+        const parent = options.parent ?? null;
+        this.visualElement = new HTMLVisualElement({
+            parent: parent?.visualElement,
+            props: {},
+            presenceContext: null,
+            visualState: createVisualState()
+        }, { allowProjection: true });
+        this.projection = new HTMLProjectionNode(this.visualElement.latestValues, parent?.projection);
+        this.visualElement.projection = this.projection;
+    }
+    /**
+     * Update projection options from current Svelte props.
+     *
+     * @param options Current layout-related motion props.
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.updateOptions({ layout, layoutId, transition, style })
+     * ```
+     */
+    updateOptions(options) {
+        this.layout = options.layout;
+        this.layoutId = options.layoutId;
+        this.transition = options.transition;
+        this.visualElement.update({
+            transition: options.transition,
+            style: options.style
+        }, null);
+        this.projection.setOptions({
+            layout: options.layout,
+            layoutId: options.layoutId,
+            animationType: animationTypeForLayout(options.layout),
+            transition: options.transition,
+            visualElement: this.visualElement
+        });
+    }
+    /**
+     * Mount the upstream projection node to an element and seed its layout.
+     *
+     * @param element Element represented by the current motion component.
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.mount(element)
+     * ```
+     */
+    mount(element) {
+        if (this.element === element)
+            return;
+        if (this.element)
+            this.unmount();
+        this.element = element;
+        this.visualElement.mount(element);
+        this.seedLayout();
+    }
+    /**
+     * Unmount the upstream projection node and clear its visual-element store.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.unmount()
+     * ```
+     */
+    unmount() {
+        if (!this.element)
+            return;
+        const element = this.element;
+        this.projection.scheduleCheckAfterUnmount();
+        this.visualElement.unmount();
+        visualElementStore.delete(element);
+        this.element = null;
+        this.lastLayout = undefined;
+    }
+    /**
+     * Capture the upstream "before" snapshot.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.willUpdate()
+     * ```
+     */
+    willUpdate() {
+        if (!this.element || !this.layoutId)
+            return;
+        this.projection.willUpdate();
+    }
+    /**
+     * Commit an upstream layout update after Svelte has patched the DOM.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.didUpdate()
+     * ```
+     */
+    didUpdate() {
+        if (!this.element || !this.layoutId)
+            return;
+        this.projection.root?.didUpdate();
+        this.refreshCachedLayout();
+    }
+    /**
+     * Seed the current layout without animating.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.seedLayout()
+     * ```
+     */
+    seedLayout() {
+        if (!this.element)
+            return;
+        this.projection.isLayoutDirty = true;
+        this.projection.updateLayout();
+        this.lastLayout = cloneMeasurements(this.projection.layout);
+    }
+    /**
+     * Animate from the last cached layout to the current observed layout.
+     *
+     * This covers layout changes discovered after the mutation by observers.
+     * Svelte runes mode doesn't expose the same component pre/post-update
+     * hooks Framer Motion uses in React, so this adapter reuses upstream
+     * projection while the Svelte component controls the snapshot timing.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.commitObservedLayoutChange()
+     * ```
+     */
+    commitObservedLayoutChange() {
+        if (!this.element || !this.layoutId)
+            return;
+        const snapshot = cloneMeasurements(this.lastLayout);
+        if (!snapshot) {
+            this.seedLayout();
+            return;
+        }
+        this.projection.root?.startUpdate();
+        this.projection.snapshot = snapshot;
+        this.projection.isLayoutDirty = true;
+        this.projection.root?.didUpdate();
+        this.refreshCachedLayout();
+    }
+    refreshCachedLayout() {
+        requestAnimationFrame(() => {
+            this.lastLayout = cloneMeasurements(this.projection.layout);
+        });
+    }
+}