@humanspeak/svelte-motion 0.4.1 → 0.4.3

package/dist/html/_MotionContainer.svelte

@@ -87,6 +87,7 @@
         whileHover: whileHoverProp,
         whileFocus: whileFocusProp,
         whileInView: whileInViewProp,
+        viewport: viewportProp,
         whileDrag: whileDragProp,
         onHoverStart: onHoverStartProp,
         onHoverEnd: onHoverEndProp,
@@ -781,7 +782,8 @@
             {
                 initial: (resolvedInitial ?? {}) as Record<string, unknown>,
                 animate: (resolvedAnimate ?? {}) as Record<string, unknown>
-            }
+            },
+            viewportProp
         )
     })
 

package/dist/types.d.ts

@@ -133,6 +133,29 @@ export type MotionWhileDrag = (Record<string, unknown> & {
 export type MotionWhileInView = (Record<string, unknown> & {
     transition?: AnimationOptions;
 }) | DOMKeyframesDefinition | undefined;
+/**
+ * IntersectionObserver configuration for `whileInView`. Mirrors framer-motion's
+ * `viewport` prop. Same shape as `UseInViewOptions` minus `initial` (which is
+ * only meaningful for the hook's pre-mount return value).
+ *
+ * @example
+ * ```svelte
+ * <motion.div
+ *   whileInView={{ opacity: 1, y: 0 }}
+ *   viewport={{ once: true, amount: 0.5 }}
+ * />
+ * ```
+ */
+export type MotionViewport = {
+    /** When `true`, fire only once on first entry. Subsequent re-entries no-op. */
+    once?: boolean;
+    /** Element to use as the IntersectionObserver root. Defaults to the viewport. */
+    root?: Element | Document;
+    /** CSS margin string applied to the root bounding box (e.g. `"100px 0px"`). */
+    margin?: string;
+    /** Fraction (0-1) or `"some"` / `"all"` of the target that must be visible. */
+    amount?: 'some' | 'all' | number;
+};
 /**
  * Animation transition configuration for hover interactions.
  * Overrides the global transition when provided.
@@ -240,6 +263,8 @@ export type MotionProps = {
     whileDrag?: MotionWhileDrag;
     /** In-view interaction animation - animates when element enters viewport */
     whileInView?: MotionWhileInView;
+    /** IntersectionObserver options for `whileInView` (once / root / margin / amount) */
+    viewport?: MotionViewport;
     /** Called right before a main animate transition starts */
     onAnimationStart?: MotionAnimationStart;
     /** Called after a main animate transition completes */

package/dist/utils/inView.d.ts

@@ -1,5 +1,6 @@
 import { type AnimationOptions, type DOMKeyframesDefinition } from 'motion';
 import { type Readable } from 'svelte/store';
+import type { MotionViewport } from '../types.js';
 import { type ElementOrGetter } from './dom.js';
 /**
  * Split a whileInView definition into keyframes and an optional nested transition.
@@ -57,6 +58,7 @@ export declare const computeInViewBaseline: (el: HTMLElement, opts: {
  * @param mergedTransition Root/component merged transition.
  * @param callbacks Optional lifecycle callbacks for in-view start/end and animation completion.
  * @param baselineSources Optional sources used to compute baseline.
+ * @param viewport Optional IntersectionObserver options. `amount` defaults to `0` (any pixel visible).
  * @returns Cleanup function to stop observing.
  * @example
  * const cleanup = attachWhileInView(
@@ -67,7 +69,8 @@ export declare const computeInViewBaseline: (el: HTMLElement, opts: {
  *     onStart: () => console.log('Entered viewport'),
  *     onEnd: () => console.log('Left viewport')
  *   },
- *   { initial: { opacity: 0, y: 50 } }
+ *   { initial: { opacity: 0, y: 50 } },
+ *   { once: true, amount: 0.5 }
  * )
  * // Later: cleanup() to stop observing
  */
@@ -78,7 +81,7 @@ export declare const attachWhileInView: (el: HTMLElement, whileInView: Record<st
 }, baselineSources?: {
     initial?: Record<string, unknown>;
     animate?: Record<string, unknown>;
-}) => (() => void);
+}, viewport?: MotionViewport) => (() => void);
 /**
  * Options accepted by `useInView`.
  */

package/dist/utils/inView.js

@@ -122,6 +122,7 @@ export const computeInViewBaseline = (el, opts) => {
  * @param mergedTransition Root/component merged transition.
  * @param callbacks Optional lifecycle callbacks for in-view start/end and animation completion.
  * @param baselineSources Optional sources used to compute baseline.
+ * @param viewport Optional IntersectionObserver options. `amount` defaults to `0` (any pixel visible).
  * @returns Cleanup function to stop observing.
  * @example
  * const cleanup = attachWhileInView(
@@ -132,14 +133,18 @@ export const computeInViewBaseline = (el, opts) => {
  *     onStart: () => console.log('Entered viewport'),
  *     onEnd: () => console.log('Left viewport')
  *   },
- *   { initial: { opacity: 0, y: 50 } }
+ *   { initial: { opacity: 0, y: 50 } },
+ *   { once: true, amount: 0.5 }
  * )
  * // Later: cleanup() to stop observing
  */
-export const attachWhileInView = (el, whileInView, mergedTransition, callbacks, baselineSources) => {
+export const attachWhileInView = (el, whileInView, mergedTransition, callbacks, baselineSources, viewport) => {
     if (!whileInView)
         return () => { };
-    return motionInView(el, () => {
+    let latched = false;
+    const stop = motionInView(el, () => {
+        if (latched)
+            return;
         const inViewBaseline = computeInViewBaseline(el, {
             initial: baselineSources?.initial,
             animate: baselineSources?.animate,
@@ -155,13 +160,28 @@ export const attachWhileInView = (el, whileInView, mergedTransition, callbacks,
             .catch(() => {
             /* animation cancelled — skip completion callback */
         });
+        if (viewport?.once) {
+            // Latch on first entry. Don't return an exit handler so the
+            // element holds its in-view state and we never animate back.
+            // Stop observing entirely after the entry handler returns.
+            latched = true;
+            queueMicrotask(stop);
+            return;
+        }
         return () => {
             if (Object.keys(inViewBaseline).length > 0) {
                 animate(el, inViewBaseline, mergedTransition);
             }
             callbacks?.onEnd?.();
         };
-    }, { amount: 0 });
+    }, {
+        root: viewport?.root,
+        // framer-motion types `margin` as a CSS-shorthand template literal;
+        // we expose plain `string` so consumers can pass any computed value.
+        margin: viewport?.margin,
+        amount: viewport?.amount ?? 0
+    });
+    return stop;
 };
 /**
  * Returns a Svelte readable store that tracks whether `target` is in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-motion",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "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",
@@ -95,8 +95,8 @@
   },
   "dependencies": {
     "acorn": "^8.16.0",
-    "motion": "^12.38.0",
-    "motion-dom": "^12.38.0"
+    "motion": "^12.39.0",
+    "motion-dom": "^12.39.0"
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
@@ -114,7 +114,7 @@
     "@tailwindcss/vite": "^4.3.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.3.1",
-    "@types/node": "^25.8.0",
+    "@types/node": "^25.9.0",
     "@vitest/coverage-v8": "^4.1.6",
     "eslint": "^10.4.0",
     "eslint-config-prettier": "10.1.8",
@@ -142,7 +142,7 @@
     "tailwind-variants": "^3.2.2",
     "tailwindcss": "^4.3.0",
     "tailwindcss-animate": "^1.0.7",
-    "tsx": "^4.22.0",
+    "tsx": "^4.22.2",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.3",
     "vite": "^8.0.13",