@humanspeak/svelte-motion 0.5.3 → 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/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;
+};

package/dist/html/_MotionContainer.svelte

@@ -5,6 +5,8 @@
 
 <script lang="ts">
     import { getMotionConfig } from '../components/motionConfig.context'
+    import { getLazyMotionContext } from '../components/lazyMotion.context'
+    import { domMax } from '../features/domMax'
     import {
         filterReducedMotionKeyframes,
         useReducedMotionConfig
@@ -156,6 +158,11 @@
     let enterAnimationSettled = $state(false)
     let dataPath = $state<number>(-1)
     const motionConfig = $derived(getMotionConfig())
+    const lazyMotion = getLazyMotionContext()
+    const activeFeatures = $derived(lazyMotion?.getFeatures() ?? domMax)
+    const hasGestureFeatures = $derived(!!activeFeatures.gestures)
+    const hasDragFeatures = $derived(!!activeFeatures.drag)
+    const hasLayoutFeatures = $derived(!!activeFeatures.layout)
     const reducedMotionState = useReducedMotionConfig()
     // `.current` is $state-backed inside reducedMotionState; tracking it via
     // $derived makes `reducedMotion` re-evaluate whenever the OS preference
@@ -553,7 +560,8 @@
         // key, empty array) would otherwise add `tabindex=0` for an
         // element that never actually receives a tap gesture — an
         // unintended tab stop. (#349 CR feedback)
-        ...(isNotEmpty(resolvedWhileTap) &&
+        ...(hasGestureFeatures &&
+        isNotEmpty(resolvedWhileTap) &&
         !isNativelyFocusable(tag, rest as Record<string, unknown>) &&
         ((rest as Record<string, unknown>)?.tabindex ??
             (rest as Record<string, unknown>)?.tabIndex ??
@@ -626,7 +634,7 @@
     //   after any non-zero duration settle animation.
     let teardownDrag: (() => void) | null = null
     $effect(() => {
-        if (!(element && isLoaded === 'ready')) return
+        if (!(element && isLoaded === 'ready' && hasDragFeatures)) return
         // Only attach if drag enabled
         if (!dragProp) return
         // Clean up previous
@@ -787,7 +795,7 @@
                 isLoaded
             })
         }
-        if (!element) return
+        if (!element || !hasGestureFeatures) return
         // Defer attachment until the element has settled out of the enter
         // animation phase — matches the gate every other gesture effect
         // in this file uses (drag, whileTap, whileHover, whileFocus,
@@ -1050,7 +1058,7 @@
     // When layout === true we also scale to smoothly interpolate size changes.
     let lastRect: RectLike | null = null
     $effect(() => {
-        if (!(element && layoutProp && isLoaded === 'ready')) return
+        if (!(element && layoutProp && isLoaded === 'ready' && hasLayoutFeatures)) return
 
         // Initialize last rect on first ready frame. We measure through the
         // projection node rather than `measureRect` directly so the rect is
@@ -1105,7 +1113,16 @@
     // Shared layout animation via layoutId.
     // On mount, consume the previous snapshot and FLIP from its position.
     $effect(() => {
-        if (!(element && scopedLayoutId && layoutIdRegistry && isLoaded === 'ready')) return
+        if (
+            !(
+                element &&
+                scopedLayoutId &&
+                layoutIdRegistry &&
+                isLoaded === 'ready' &&
+                hasLayoutFeatures
+            )
+        )
+            return
 
         const prev = layoutIdRegistry.consume(scopedLayoutId)
         if (!prev) return // First appearance, no animation needed
@@ -1123,7 +1140,10 @@
 
     // whileTap handling via motion-dom's press()
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileTap))) return
+        if (
+            !(element && isLoaded === 'ready' && hasGestureFeatures && isNotEmpty(resolvedWhileTap))
+        )
+            return
         return attachWhileTap(
             element!,
             (resolvedWhileTap ?? {}) as Record<string, unknown>,
@@ -1143,7 +1163,15 @@
 
     // whileHover handling, gated to true-hover devices to avoid sticky states on touch
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileHover))) return
+        if (
+            !(
+                element &&
+                isLoaded === 'ready' &&
+                hasGestureFeatures &&
+                isNotEmpty(resolvedWhileHover)
+            )
+        )
+            return
         return attachWhileHover(
             element!,
             (resolvedWhileHover ?? {}) as Record<string, unknown>,
@@ -1158,7 +1186,15 @@
 
     // whileFocus handling for keyboard focus interactions
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileFocus))) return
+        if (
+            !(
+                element &&
+                isLoaded === 'ready' &&
+                hasGestureFeatures &&
+                isNotEmpty(resolvedWhileFocus)
+            )
+        )
+            return
         return attachWhileFocus(
             element!,
             (resolvedWhileFocus ?? {}) as Record<string, unknown>,
@@ -1173,7 +1209,15 @@
 
     // whileInView handling for viewport intersection
     $effect(() => {
-        if (!(element && isLoaded === 'ready' && isNotEmpty(resolvedWhileInView))) return
+        if (
+            !(
+                element &&
+                isLoaded === 'ready' &&
+                hasGestureFeatures &&
+                isNotEmpty(resolvedWhileInView)
+            )
+        )
+            return
         return attachWhileInView(
             element!,
             (resolvedWhileInView ?? {}) as Record<string, unknown>,

package/dist/index.d.ts

@@ -1,7 +1,13 @@
 import AnimatePresence from './components/AnimatePresence.svelte';
 import LayoutGroup from './components/LayoutGroup.svelte';
+import LazyMotion from './components/LazyMotion.svelte';
 import MotionConfig from './components/MotionConfig.svelte';
 import PresenceChild from './components/PresenceChild.svelte';
+export type { FeatureBundle, LazyFeatureBundle } from './features';
+export { domAnimation } from './features/domAnimation';
+export { domMax } from './features/domMax';
+export { domMin } from './features/domMin';
+export { m } from './m';
 export { motion } from './motion';
 export { animate, delay, hover, inView, press, resize, scroll, stagger, transform } from 'motion';
 export { anticipate, backIn, backInOut, backOut, circIn, circInOut, circOut, cubicBezier, easeIn, easeInOut, easeOut } from 'motion';
@@ -42,7 +48,7 @@ export { styleString } from './utils/styleObject.svelte';
 export { useTime } from './utils/time.svelte';
 export { useTransform } from './utils/transform.svelte';
 export type { MultiTransformer, SingleTransformer, TransformOptions, TransformOutputMap, TransformSource } from './utils/transform.svelte';
-export { AnimatePresence, LayoutGroup, MotionConfig, PresenceChild };
+export { AnimatePresence, LayoutGroup, LazyMotion, MotionConfig, PresenceChild };
 export { default as MotionA } from './html/A.svelte';
 export { default as MotionAbbr } from './html/Abbr.svelte';
 export { default as MotionAddress } from './html/Address.svelte';

package/dist/index.js

@@ -1,7 +1,12 @@
 import AnimatePresence from './components/AnimatePresence.svelte';
 import LayoutGroup from './components/LayoutGroup.svelte';
+import LazyMotion from './components/LazyMotion.svelte';
 import MotionConfig from './components/MotionConfig.svelte';
 import PresenceChild from './components/PresenceChild.svelte';
+export { domAnimation } from './features/domAnimation';
+export { domMax } from './features/domMax';
+export { domMin } from './features/domMin';
+export { m } from './m';
 export { motion } from './motion';
 // Re-export core animation functions from motion
 export { animate, delay, hover, inView, press, resize, scroll, stagger, transform } from 'motion';
@@ -31,7 +36,7 @@ export { stringifyStyleObject } from './utils/styleObject';
 export { styleString } from './utils/styleObject.svelte';
 export { useTime } from './utils/time.svelte';
 export { useTransform } from './utils/transform.svelte';
-export { AnimatePresence, LayoutGroup, MotionConfig, PresenceChild };
+export { AnimatePresence, LayoutGroup, LazyMotion, MotionConfig, PresenceChild };
 // Named component exports — tree-shakeable alternative to the `motion` object
 export { default as MotionA } from './html/A.svelte';
 export { default as MotionAbbr } from './html/Abbr.svelte';

package/dist/m.d.ts

@@ -0,0 +1,9 @@
+import type { MotionComponents } from './html/index';
+/**
+ * Lazy motion component namespace used with `<LazyMotion>`.
+ *
+ * The namespace mirrors the default `motion` object API (`m.div`, `m.button`,
+ * `m.svg`, etc.) while reading feature availability from the nearest
+ * LazyMotion provider.
+ */
+export declare const m: MotionComponents;

package/dist/m.js

@@ -0,0 +1,9 @@
+import * as html from './html/index';
+/**
+ * Lazy motion component namespace used with `<LazyMotion>`.
+ *
+ * The namespace mirrors the default `motion` object API (`m.div`, `m.button`,
+ * `m.svg`, etc.) while reading feature availability from the nearest
+ * LazyMotion provider.
+ */
+export const m = Object.fromEntries(Object.entries(html).map(([key, component]) => [key.toLowerCase(), component]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Framer Motion for Svelte 5. Declarative motion.<tag> components with AnimatePresence exit animations, gestures (hover, tap, drag, focus, in-view), variants, FLIP layout animations, shared-layout transitions, spring physics, and scroll-linked motion values. The drop-in Framer Motion alternative for Svelte and SvelteKit.",
   "keywords": [
     "svelte",