@humanspeak/svelte-motion 0.5.2 → 0.5.4

package/dist/components/LazyMotion.svelte

@@ -0,0 +1,70 @@
+<script lang="ts">
+    import { setLazyMotionContext } from './lazyMotion.context'
+    import { domMin } from '../features/domMin'
+    import {
+        isLazyFeatureBundle,
+        normalizeLazyFeatureBundle,
+        type FeatureBundle,
+        type LazyFeatureBundle
+    } from '../features'
+    import { untrack, type Snippet } from 'svelte'
+
+    /**
+     * Props accepted by the LazyMotion component.
+     */
+    type Props = {
+        /** Child content rendered inside the active LazyMotion context. */
+        children?: Snippet
+        /** Eager or async feature bundle used by descendant `m.*` components. */
+        features: FeatureBundle | LazyFeatureBundle
+        /** Enables strict LazyMotion usage checks. Defaults to false. */
+        strict?: boolean
+    }
+
+    let { children, features, strict = false }: Props = $props()
+
+    let loadedFeatures = $state<FeatureBundle>(
+        untrack(() => (isLazyFeatureBundle(features) ? domMin : features))
+    )
+    let isLoaded = $state(untrack(() => !isLazyFeatureBundle(features)))
+
+    setLazyMotionContext({
+        getFeatures: () => loadedFeatures,
+        getIsLoaded: () => isLoaded,
+        get strict() {
+            return strict
+        }
+    })
+
+    let loadId = 0
+
+    $effect(() => {
+        const currentLoadId = ++loadId
+
+        if (!isLazyFeatureBundle(features)) {
+            loadedFeatures = features
+            isLoaded = true
+            return
+        }
+
+        loadedFeatures = domMin
+        isLoaded = false
+        features()
+            .then((bundle) => {
+                if (currentLoadId !== loadId) return
+                loadedFeatures = normalizeLazyFeatureBundle(bundle)
+                isLoaded = true
+            })
+            .catch(() => {
+                if (currentLoadId !== loadId) return
+                loadedFeatures = domMin
+                isLoaded = false
+            })
+
+        return () => {
+            loadId += 1
+        }
+    })
+</script>
+
+{@render children?.()}

package/dist/components/LazyMotion.svelte.d.ts

@@ -0,0 +1,16 @@
+import { type FeatureBundle, type LazyFeatureBundle } from '../features';
+import { type Snippet } from 'svelte';
+/**
+ * Props accepted by the LazyMotion component.
+ */
+type Props = {
+    /** Child content rendered inside the active LazyMotion context. */
+    children?: Snippet;
+    /** Eager or async feature bundle used by descendant `m.*` components. */
+    features: FeatureBundle | LazyFeatureBundle;
+    /** Enables strict LazyMotion usage checks. Defaults to false. */
+    strict?: boolean;
+};
+declare const LazyMotion: import("svelte").Component<Props, {}, "">;
+type LazyMotion = ReturnType<typeof LazyMotion>;
+export default LazyMotion;

package/dist/components/lazyMotion.context.d.ts

@@ -0,0 +1,25 @@
+import type { FeatureBundle } from '../features';
+/**
+ * Context value published by `<LazyMotion>` for descendant motion elements.
+ */
+export type LazyMotionContext = {
+    /** Returns the currently active feature bundle. */
+    getFeatures: () => FeatureBundle;
+    /** Returns whether an async bundle has finished loading. */
+    getIsLoaded: () => boolean;
+    /** Enables Framer Motion-style strict lazy usage checks. */
+    strict: boolean;
+};
+/**
+ * Reads the nearest LazyMotion context.
+ *
+ * @returns The active LazyMotion context, or undefined outside LazyMotion.
+ */
+export declare const getLazyMotionContext: () => LazyMotionContext | undefined;
+/**
+ * Publishes a LazyMotion context for descendant motion elements.
+ *
+ * @param context - LazyMotion context to publish.
+ * @returns The same context value returned by Svelte's setContext.
+ */
+export declare const setLazyMotionContext: (context: LazyMotionContext) => LazyMotionContext;

package/dist/components/lazyMotion.context.js

@@ -0,0 +1,19 @@
+import { getContext, setContext } from 'svelte';
+const key = Symbol('lazyMotion');
+/**
+ * Reads the nearest LazyMotion context.
+ *
+ * @returns The active LazyMotion context, or undefined outside LazyMotion.
+ */
+export const getLazyMotionContext = () => {
+    return getContext(key);
+};
+/**
+ * Publishes a LazyMotion context for descendant motion elements.
+ *
+ * @param context - LazyMotion context to publish.
+ * @returns The same context value returned by Svelte's setContext.
+ */
+export const setLazyMotionContext = (context) => {
+    return setContext(key, context);
+};

package/dist/components/projection.context.d.ts

@@ -0,0 +1,22 @@
+import type { ProjectionNode } from '../utils/projection';
+/**
+ * Publish a `ProjectionNode` as the projection parent for descendant
+ * motion components.
+ *
+ * @param node The current component's ProjectionNode, or `null` to
+ *   explicitly clear (rarely needed — Svelte context auto-clears on
+ *   component unmount).
+ */
+export declare const setProjectionParent: (node: ProjectionNode | null) => void;
+/**
+ * Read the ancestor `ProjectionNode` published by the nearest motion
+ * ancestor. Returns `null` when this component is at the root of the
+ * projection tree (or when no motion ancestor exists).
+ *
+ * Must be called BEFORE the current component publishes its own node
+ * via `setProjectionParent` — see the order-of-operations note in this
+ * file's header.
+ *
+ * @returns The parent ProjectionNode, or `null`.
+ */
+export declare const getProjectionParent: () => ProjectionNode | null;

package/dist/components/projection.context.js

@@ -0,0 +1,56 @@
+import { getContext, setContext } from 'svelte';
+/**
+ * Svelte context plumbing for the projection tree.
+ *
+ * Every `motion.*` element creates a `ProjectionNode` at setup time and
+ * publishes it via `setProjectionParent(node)` so descendant motion
+ * elements can pick it up via `getProjectionParent()` and wire themselves
+ * as `node.parent` + register in `node.parent.children`. The tree shape
+ * mirrors the Svelte component tree exactly because Svelte's
+ * `setContext` propagates down through descendants in component-init
+ * order.
+ *
+ * This is the closest analog we have to framer-motion's depth-sorted
+ * FlatTree (`projection/node/create-projection-node.ts`), but without
+ * the global `root` registry — parent/child pointers are sufficient
+ * for the workflows this PR enables (drag↔swap origin compensation,
+ * ancestor-zeroing measure). A global root would only be needed once we
+ * port shared-element `layoutId` morphing onto projection nodes; the
+ * current `layoutId.ts` registry continues to handle that case
+ * independently.
+ *
+ * Order of operations inside a single `motion.*` component (CRITICAL):
+ * 1. Read parent via `getProjectionParent()` BEFORE creating own node.
+ * 2. Construct own node, set `node.parent = parent`.
+ * 3. Publish own node via `setProjectionParent(node)`.
+ * If steps 1 and 3 are reversed, the component sees ITS OWN node as
+ * the parent (because `setContext` shadows from the call site down)
+ * and the tree collapses to a chain of self-references. Same trap
+ * `layoutScroll.context.ts` documents — don't repeat it.
+ */
+const PROJECTION_CONTEXT_KEY = Symbol('svelte-motion:projection-parent');
+/**
+ * Publish a `ProjectionNode` as the projection parent for descendant
+ * motion components.
+ *
+ * @param node The current component's ProjectionNode, or `null` to
+ *   explicitly clear (rarely needed — Svelte context auto-clears on
+ *   component unmount).
+ */
+export const setProjectionParent = (node) => {
+    setContext(PROJECTION_CONTEXT_KEY, node);
+};
+/**
+ * Read the ancestor `ProjectionNode` published by the nearest motion
+ * ancestor. Returns `null` when this component is at the root of the
+ * projection tree (or when no motion ancestor exists).
+ *
+ * Must be called BEFORE the current component publishes its own node
+ * via `setProjectionParent` — see the order-of-operations note in this
+ * file's header.
+ *
+ * @returns The parent ProjectionNode, or `null`.
+ */
+export const getProjectionParent = () => {
+    return getContext(PROJECTION_CONTEXT_KEY) ?? null;
+};

package/dist/features/domAnimation.d.ts

@@ -0,0 +1,6 @@
+import type { FeatureBundle } from './index';
+/**
+ * DOM animation feature bundle: animations plus hover, tap, focus, pan,
+ * and in-view gestures.
+ */
+export declare const domAnimation: FeatureBundle;

package/dist/features/domAnimation.js

@@ -0,0 +1,8 @@
+/**
+ * DOM animation feature bundle: animations plus hover, tap, focus, pan,
+ * and in-view gestures.
+ */
+export const domAnimation = {
+    animations: true,
+    gestures: true
+};

package/dist/features/domMax.d.ts

@@ -0,0 +1,5 @@
+import type { FeatureBundle } from './index';
+/**
+ * Full DOM feature bundle: animations, gestures, drag, and layout features.
+ */
+export declare const domMax: FeatureBundle;

package/dist/features/domMax.js

@@ -0,0 +1,9 @@
+import { domAnimation } from './domAnimation';
+/**
+ * Full DOM feature bundle: animations, gestures, drag, and layout features.
+ */
+export const domMax = {
+    ...domAnimation,
+    drag: true,
+    layout: true
+};

package/dist/features/domMin.d.ts

@@ -0,0 +1,5 @@
+import type { FeatureBundle } from './index';
+/**
+ * Minimal DOM feature bundle: mount/update animations only.
+ */
+export declare const domMin: FeatureBundle;

package/dist/features/domMin.js

@@ -0,0 +1,6 @@
+/**
+ * Minimal DOM feature bundle: mount/update animations only.
+ */
+export const domMin = {
+    animations: true
+};

package/dist/features/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Runtime capabilities made available to motion components inside a
+ * `<LazyMotion>` subtree.
+ */
+export type FeatureBundle = {
+    /** Enables initial/animate/exit animation behavior. */
+    animations: true;
+    /** Enables hover, tap, focus, pan, and in-view gesture behavior. */
+    gestures?: true;
+    /** Enables drag gesture behavior. */
+    drag?: true;
+    /** Enables layout and shared-layout animation behavior. */
+    layout?: true;
+};
+/**
+ * Function form accepted by `<LazyMotion features>`.
+ *
+ * The function resolves to a feature bundle directly or to a module-like
+ * object with the bundle as its default export.
+ */
+export type LazyFeatureBundle = () => Promise<FeatureBundle | {
+    default: FeatureBundle;
+}>;
+/**
+ * Returns whether a LazyMotion `features` value is an async loader.
+ *
+ * @param features - Feature bundle or loader passed to `<LazyMotion>`.
+ * @returns True when the features value should be invoked asynchronously.
+ */
+export declare const isLazyFeatureBundle: (features: FeatureBundle | LazyFeatureBundle) => features is LazyFeatureBundle;
+/**
+ * Normalizes an asynchronously loaded feature bundle.
+ *
+ * @param loaded - Resolved bundle or default-export module wrapper.
+ * @returns The concrete feature bundle.
+ */
+export declare const normalizeLazyFeatureBundle: (loaded: FeatureBundle | {
+    default: FeatureBundle;
+}) => FeatureBundle;

package/dist/features/index.js

@@ -0,0 +1,18 @@
+/**
+ * Returns whether a LazyMotion `features` value is an async loader.
+ *
+ * @param features - Feature bundle or loader passed to `<LazyMotion>`.
+ * @returns True when the features value should be invoked asynchronously.
+ */
+export const isLazyFeatureBundle = (features) => typeof features === 'function';
+/**
+ * Normalizes an asynchronously loaded feature bundle.
+ *
+ * @param loaded - Resolved bundle or default-export module wrapper.
+ * @returns The concrete feature bundle.
+ */
+export const normalizeLazyFeatureBundle = (loaded) => {
+    if ('default' in loaded)
+        return loaded.default;
+    return loaded;
+};