@humanspeak/svelte-motion 0.5.4 → 0.6.1

package/dist/utils/motionDomProjection.d.ts

@@ -0,0 +1,155 @@
+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;
+    /** Tracks scroll on this element for descendant layout projection. */
+    layoutScroll?: boolean;
+    /** 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 {
+    private static adapters;
+    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;
+    /**
+     * Finish any active upstream layout animation in this subtree.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.finishAnimation()
+     * ```
+     */
+    finishAnimation(): void;
+    /**
+     * Check whether this projection subtree has an active layout animation.
+     *
+     * @returns `true` when this projection subtree is currently animating.
+     *
+     * @example
+     * ```ts
+     * if (adapter.isAnimating()) adapter.finishAnimation()
+     * ```
+     */
+    isAnimating(): boolean;
+    private seedCachedSnapshotsForSubtree;
+    private finishAnimationForSubtree;
+    private isAnimatingSubtree;
+    private updatePathScroll;
+    private refreshCachedLayout;
+}
+export {};

package/dist/utils/motionDomProjection.js

@@ -0,0 +1,279 @@
+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 {
+    static adapters = new WeakMap();
+    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;
+        MotionDomProjectionAdapter.adapters.set(this.projection, this);
+    }
+    /**
+     * 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,
+            layoutScroll: options.layoutScroll,
+            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;
+        MotionDomProjectionAdapter.adapters.set(this.projection, this);
+        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);
+        MotionDomProjectionAdapter.adapters.delete(this.projection);
+        this.element = null;
+        this.lastLayout = undefined;
+    }
+    /**
+     * Capture the upstream "before" snapshot.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.willUpdate()
+     * ```
+     */
+    willUpdate() {
+        if (!this.element || !this.layout)
+            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.layout)
+            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.updatePathScroll();
+        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.layout)
+            return;
+        if (!this.lastLayout) {
+            this.seedLayout();
+            return;
+        }
+        this.projection.root?.startUpdate();
+        this.seedCachedSnapshotsForSubtree(this.projection);
+        this.projection.root?.didUpdate();
+        this.refreshCachedLayout();
+    }
+    /**
+     * Finish any active upstream layout animation in this subtree.
+     *
+     * @returns Nothing.
+     *
+     * @example
+     * ```ts
+     * adapter.finishAnimation()
+     * ```
+     */
+    finishAnimation() {
+        if (!this.element || !this.layout)
+            return;
+        this.finishAnimationForSubtree(this.projection);
+        this.seedLayout();
+    }
+    /**
+     * Check whether this projection subtree has an active layout animation.
+     *
+     * @returns `true` when this projection subtree is currently animating.
+     *
+     * @example
+     * ```ts
+     * if (adapter.isAnimating()) adapter.finishAnimation()
+     * ```
+     */
+    isAnimating() {
+        return this.isAnimatingSubtree(this.projection);
+    }
+    seedCachedSnapshotsForSubtree(projection) {
+        const adapter = MotionDomProjectionAdapter.adapters.get(projection);
+        const snapshot = cloneMeasurements(adapter?.lastLayout);
+        if (snapshot && projection.options.layout) {
+            projection.snapshot = snapshot;
+            projection.isLayoutDirty = true;
+        }
+        for (const child of projection.children) {
+            this.seedCachedSnapshotsForSubtree(child);
+        }
+    }
+    finishAnimationForSubtree(projection) {
+        projection.finishAnimation();
+        projection.targetDelta = projection.relativeTarget = projection.target = undefined;
+        projection.isProjectionDirty = true;
+        projection.scheduleRender();
+        for (const child of projection.children) {
+            this.finishAnimationForSubtree(child);
+        }
+    }
+    isAnimatingSubtree(projection) {
+        if (projection.currentAnimation)
+            return true;
+        for (const child of projection.children) {
+            if (this.isAnimatingSubtree(child))
+                return true;
+        }
+        return false;
+    }
+    updatePathScroll() {
+        for (const node of this.projection.path) {
+            node.updateScroll();
+        }
+    }
+    refreshCachedLayout() {
+        requestAnimationFrame(() => {
+            this.lastLayout = cloneMeasurements(this.projection.layout);
+        });
+    }
+}

package/dist/utils/optimizedAppear.d.ts

@@ -0,0 +1,141 @@
+import { type AnimationOptions } from 'motion';
+import { optimizedAppearDataAttribute } from 'motion-dom';
+type AppearValueName = 'opacity' | 'transform';
+type OptimizedAppearEntry = {
+    name: AppearValueName;
+    keyframes: [string | number, string | number];
+    options: KeyframeAnimationOptions;
+};
+type AppearStoreEntry = {
+    animation: Animation;
+    startTime: number | null;
+};
+type SvelteMotionAppearStore = {
+    animations: Map<string, AppearStoreEntry>;
+    complete: Map<string, boolean>;
+    started: Array<{
+        id: string;
+        name: string;
+    }>;
+    readyAnimation?: Animation;
+    startFrameTime?: number;
+};
+declare global {
+    interface Window {
+        __SvelteMotionAppear?: SvelteMotionAppearStore;
+    }
+}
+/**
+ * Build serialisable optimized-appear animation entries from an initial and
+ * animate pair.
+ *
+ * @param initial Initial keyframes reflected into SSR markup.
+ * @param animate Target keyframes for the enter animation.
+ * @param transition Motion transition options.
+ * @returns Appear entries for WAAPI-supported opacity and transform values.
+ *
+ * @example
+ * ```ts
+ * const entries = createOptimizedAppearData(
+ *     { opacity: 0, scale: 0.8 },
+ *     { opacity: 1, scale: 1 },
+ *     { duration: 0.6, ease: [0.16, 1, 0.3, 1] }
+ * )
+ * ```
+ */
+export declare const createOptimizedAppearData: (initial: Record<string, unknown> | null | undefined, animate: Record<string, unknown> | null | undefined, transition?: AnimationOptions) => OptimizedAppearEntry[];
+/**
+ * Create the inline SSR bootstrap that starts appear animations before Svelte
+ * hydrates the component tree.
+ *
+ * @param appearId Stable optimized-appear id attached to the motion element.
+ * @param entries WAAPI animation entries to start.
+ * @returns A script tag string, or an empty string when no entries exist.
+ *
+ * @example
+ * ```ts
+ * const script = createOptimizedAppearScript('appear-1', [
+ *     { name: 'opacity', keyframes: [0, 1], options: { duration: 300, fill: 'both' } }
+ * ])
+ * ```
+ */
+export declare const createOptimizedAppearScript: (appearId: string | undefined, entries: OptimizedAppearEntry[]) => string;
+/**
+ * Start an optimized appear animation imperatively.
+ *
+ * Mirrors Framer Motion's `startOptimizedAppearAnimation`: if Motion has
+ * already mounted, this intentionally does nothing.
+ *
+ * @param element Element carrying `data-framer-appear-id`.
+ * @param name CSS property to animate.
+ * @param keyframes WAAPI keyframes for the property.
+ * @param options Motion animation options.
+ * @param onReady Optional callback receiving the started animation.
+ * @returns Nothing.
+ *
+ * @example
+ * ```ts
+ * const element = document.querySelector('[data-framer-appear-id]')
+ * if (element instanceof HTMLElement) {
+ *     startOptimizedAppearAnimation(element, 'opacity', [0, 1], { duration: 0.3 })
+ * }
+ * ```
+ */
+export declare const startOptimizedAppearAnimation: (element: HTMLElement, name: AppearValueName, keyframes: string[] | number[], options: AnimationOptions, onReady?: (animation: Animation) => void) => void;
+/**
+ * Commit and cancel optimized appear animations for an element.
+ *
+ * @param elementId Optimized appear id.
+ * @returns `true` when at least one optimized animation was handed off.
+ *
+ * @example
+ * ```ts
+ * const wasHandedOff = handoffOptimizedAppearAnimation('appear-1')
+ * if (wasHandedOff) {
+ *     console.log('Animation handed off to runtime')
+ * }
+ * ```
+ */
+export declare const handoffOptimizedAppearAnimation: (elementId: string | undefined) => boolean;
+/**
+ * Let active optimized appear animations finish before handing their final
+ * styles back to Svelte Motion.
+ *
+ * @param elementId Optimized appear id.
+ * @returns Whether at least one optimized animation was adopted.
+ *
+ * @example
+ * ```ts
+ * const wasAdopted = await finishOptimizedAppearAnimation('appear-1')
+ * if (wasAdopted) {
+ *     console.log('Animation finished and adopted')
+ * }
+ * ```
+ */
+export declare const finishOptimizedAppearAnimation: (elementId: string | undefined) => Promise<boolean>;
+/**
+ * Check whether an optimized appear animation is active for an element.
+ *
+ * @param elementId Optimized appear id.
+ * @returns Whether any optimized appear animation is currently registered.
+ *
+ * @example
+ * ```ts
+ * if (hasOptimizedAppearAnimation('appear-1')) {
+ *     console.log('Animation is active')
+ * }
+ * ```
+ */
+export declare const hasOptimizedAppearAnimation: (elementId: string | undefined) => boolean;
+/**
+ * Mark Motion as mounted so late optimized-appear starters no-op.
+ *
+ * @returns Nothing.
+ *
+ * @example
+ * ```ts
+ * markMotionMounted()
+ * ```
+ */
+export declare const markMotionMounted: () => void;
+export { optimizedAppearDataAttribute };