@humanspeak/svelte-motion 0.4.7 → 0.4.9

package/dist/utils/inView.js

@@ -1,266 +0,0 @@
-import { animate, inView as motionInView } from 'motion';
-import { readable, writable } from 'svelte/store';
-import { createAttachable } from './attachable.js';
-import {} from './dom.js';
-const CSS_FUNCTION_RE = /\b(var|calc|min|max|clamp|rgb|rgba|hsl|hsla|url)\s*\(/i;
-/**
- * Read an inline CSS-function value (var/calc/url/etc.) for `propName`
- * directly from the element's style declaration. Returns `null` for missing
- * or non-function values so the caller can fall back to `getComputedStyle`.
- *
- * Uses `style.getPropertyValue` so values like `url(data:image/svg+xml;...)`
- * with nested semicolons are preserved intact - the browser has already
- * parsed the declaration, no string scraping required.
- *
- * @param el Element whose inline style is read.
- * @param propName Camel-case JS property name (e.g. `borderColor`).
- * @returns The inline CSS function value, or `null`.
- * @example
- * getInlineCssFunction(node, 'background') // => 'var(--brand)' | null
- */
-const getInlineCssFunction = (el, propName) => {
-    const kebab = propName.replace(/([A-Z])/g, '-$1').toLowerCase();
-    const value = el.style.getPropertyValue(kebab).trim();
-    if (!value)
-        return null;
-    return CSS_FUNCTION_RE.test(value) ? value : null;
-};
-/**
- * Split a whileInView definition into keyframes and an optional nested transition.
- *
- * @param def While-in-view record that may include a nested `transition`.
- * @returns Object with `keyframes` (no `transition`) and optional `transition`.
- * @example
- * // With transition
- * splitInViewDefinition({ opacity: 1, y: 0, transition: { duration: 0.5 } })
- * // => { keyframes: { opacity: 1, y: 0 }, transition: { duration: 0.5 } }
- *
- * @example
- * // Without transition
- * splitInViewDefinition({ opacity: 1, scale: 1 })
- * // => { keyframes: { opacity: 1, scale: 1 }, transition: undefined }
- */
-export const splitInViewDefinition = (def) => {
-    const { transition, ...rest } = (def ?? {});
-    return { keyframes: rest, transition };
-};
-/**
- * Compute the baseline values to restore to when element leaves viewport.
- *
- * Preference order per key: `animate` → `initial` → neutral transform defaults
- * → computed style value if present.
- *
- * @param el Target element.
- * @param opts Source records for baseline computation.
- * @returns Minimal baseline record to restore when element leaves viewport.
- * @example
- * computeInViewBaseline(element, {
- *   initial: { opacity: 0, y: 50 },
- *   animate: { opacity: 1, y: 0 },
- *   whileInView: { opacity: 1, scale: 1.1 }
- * })
- * // => { opacity: 1, scale: 1 } (scale defaults to 1, opacity from animate)
- */
-export const computeInViewBaseline = (el, opts) => {
-    const baseline = {};
-    const initialRecord = (opts.initial ?? {});
-    const animateRecord = (opts.animate ?? {});
-    const whileInViewRecordRaw = (opts.whileInView ?? {});
-    const whileInViewRecord = { ...whileInViewRecordRaw };
-    delete whileInViewRecord.transition;
-    const neutralTransformDefaults = {
-        x: 0,
-        y: 0,
-        translateX: 0,
-        translateY: 0,
-        scale: 1,
-        scaleX: 1,
-        scaleY: 1,
-        rotate: 0,
-        rotateX: 0,
-        rotateY: 0,
-        rotateZ: 0,
-        skewX: 0,
-        skewY: 0,
-        opacity: 1
-    };
-    const cs = getComputedStyle(el);
-    for (const key of Object.keys(whileInViewRecord)) {
-        if (Object.prototype.hasOwnProperty.call(animateRecord, key)) {
-            baseline[key] = animateRecord[key];
-        }
-        else if (Object.prototype.hasOwnProperty.call(initialRecord, key)) {
-            baseline[key] = initialRecord[key];
-        }
-        else if (key in neutralTransformDefaults) {
-            baseline[key] = neutralTransformDefaults[key];
-        }
-        else {
-            const inlineValue = getInlineCssFunction(el, key);
-            if (inlineValue) {
-                baseline[key] = inlineValue;
-            }
-            else if (key in cs) {
-                baseline[key] = cs[key];
-            }
-        }
-    }
-    return baseline;
-};
-/**
- * Attach whileInView interactions to an element via motion's `inView` primitive.
- *
- * On entry, animates to `whileInView` state (using the nested `transition` if
- * provided). On exit, restores the changed keys to a baseline computed from
- * `initial` / `animate` / neutral transform defaults / inline styles.
- *
- * Delegates to motion's `inView` so the IntersectionObserver implementation
- * is shared with the public `useInView` hook.
- *
- * @param el Target element.
- * @param whileInView While-in-view definition.
- * @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(
- *   element,
- *   { opacity: 1, y: 0, transition: { duration: 0.5 } },
- *   { duration: 0.3 },
- *   {
- *     onStart: () => console.log('Entered viewport'),
- *     onEnd: () => console.log('Left viewport')
- *   },
- *   { initial: { opacity: 0, y: 50 } },
- *   { once: true, amount: 0.5 }
- * )
- * // Later: cleanup() to stop observing
- */
-export const attachWhileInView = (el, whileInView, mergedTransition, callbacks, baselineSources, viewport) => {
-    if (!whileInView)
-        return () => { };
-    let latched = false;
-    const stop = motionInView(el, () => {
-        if (latched)
-            return;
-        const inViewBaseline = computeInViewBaseline(el, {
-            initial: baselineSources?.initial,
-            animate: baselineSources?.animate,
-            whileInView
-        });
-        callbacks?.onStart?.();
-        const { keyframes, transition } = splitInViewDefinition(whileInView);
-        const animation = animate(el, keyframes, (transition ?? mergedTransition));
-        animation.finished
-            .then(() => {
-            callbacks?.onAnimationComplete?.(keyframes);
-        })
-            .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?.();
-        };
-    }, {
-        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
- * viewport. Mirrors Framer Motion's `useInView` so the same options
- * (`root`, `margin`, `amount`, `once`, `initial`) work as in React.
- *
- * `target` (and `options.root`) accept either an `HTMLElement` directly or a
- * getter `() => HTMLElement | undefined`. With Svelte's `bind:this`, the
- * element isn't available until after mount, so element resolution is
- * deferred until the first subscriber arrives; if the element isn't ready,
- * the hook polls on `requestAnimationFrame` until it is.
- *
- * SSR-safe: returns a static `readable(initial)` when `window` or
- * `IntersectionObserver` is unavailable.
- *
- * @param target - Element (or getter) to observe.
- * @param options - Optional `UseInViewOptions` (`root`, `margin`, `amount`,
- *   `once`, `initial`).
- * @returns A `Readable<boolean>` that flips to `true` while `target` is in view.
- * @see https://motion.dev/docs/react-use-in-view
- *
- * @example
- * ```svelte
- * <script>
- *   import { useInView } from '@humanspeak/svelte-motion'
- *
- *   let ref
- *   const inView = useInView(() => ref, { once: true })
- *
- *   $effect(() => {
- *     if ($inView) trackImpression()
- *   })
- * </script>
- *
- * <div bind:this={ref}>{$inView ? 'visible' : 'hidden'}</div>
- * ```
- */
-export const useInView = (target, options = {}) => {
-    const initial = options.initial ?? false;
-    if (typeof window === 'undefined' || typeof IntersectionObserver === 'undefined') {
-        return readable(initial);
-    }
-    const store = writable(initial);
-    let current = initial;
-    const update = (next) => {
-        if (next === current)
-            return;
-        current = next;
-        store.set(next);
-    };
-    let latched = false;
-    const attachable = createAttachable({
-        refs: { target, root: options.root },
-        isLatched: () => latched,
-        onAttach: ({ target: el, root }, stop) => motionInView(el, () => {
-            update(true);
-            if (options.once) {
-                // Detach inside the entry callback; motion's inView
-                // handles re-entry safely via observer.unobserve.
-                latched = true;
-                stop();
-                return;
-            }
-            return () => update(false);
-        }, {
-            root: root,
-            // framer-motion types `margin` as a CSS-shorthand template
-            // literal; we expose plain `string` so the public API is
-            // ergonomic and forward-compat with future motion changes.
-            margin: options.margin,
-            amount: options.amount
-        })
-    });
-    return readable(initial, (set) => {
-        const release = attachable.subscribe();
-        const unsub = store.subscribe(set);
-        return () => {
-            unsub();
-            release();
-        };
-    });
-};

package/dist/utils/reducedMotion.d.ts

@@ -1,20 +0,0 @@
-import { type Readable } from 'svelte/store';
-/**
- * Returns a readable store that reflects the user's `prefers-reduced-motion` setting.
- *
- * Defaults to `false` in SSR or when `matchMedia` is unavailable/throws.
- *
- * @returns {Readable<boolean>} `true` when the user prefers reduced motion.
- * @see https://motion.dev/docs/react-reduced-motion
- *
- * @example
- * ```svelte
- * <script>
- *   import { useReducedMotion } from '@humanspeak/svelte-motion'
- *   const reduced = useReducedMotion()
- * </script>
- *
- * <div style:transform={$reduced ? 'none' : 'rotate(45deg)'}>...</div>
- * ```
- */
-export declare const useReducedMotion: () => Readable<boolean>;

package/dist/utils/reducedMotion.js

@@ -1,42 +0,0 @@
-import { readable } from 'svelte/store';
-const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
-const SSR_FALLBACK = readable(false, () => { });
-/**
- * Returns a readable store that reflects the user's `prefers-reduced-motion` setting.
- *
- * Defaults to `false` in SSR or when `matchMedia` is unavailable/throws.
- *
- * @returns {Readable<boolean>} `true` when the user prefers reduced motion.
- * @see https://motion.dev/docs/react-reduced-motion
- *
- * @example
- * ```svelte
- * <script>
- *   import { useReducedMotion } from '@humanspeak/svelte-motion'
- *   const reduced = useReducedMotion()
- * </script>
- *
- * <div style:transform={$reduced ? 'none' : 'rotate(45deg)'}>...</div>
- * ```
- */
-export const useReducedMotion = () => {
-    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
-        return SSR_FALLBACK;
-    }
-    let media;
-    try {
-        media = window.matchMedia(REDUCED_MOTION_QUERY);
-    }
-    catch {
-        return SSR_FALLBACK;
-    }
-    return readable(media.matches, (set) => {
-        const handler = (event) => set(event.matches);
-        if (typeof media.addEventListener === 'function') {
-            media.addEventListener('change', handler);
-            return () => media.removeEventListener('change', handler);
-        }
-        media.addListener(handler);
-        return () => media.removeListener(handler);
-    });
-};

package/dist/utils/reducedMotionConfig.d.ts

@@ -1,39 +0,0 @@
-import { type Readable } from 'svelte/store';
-/**
- * Returns a copy of `keyframes` with transform-related keys removed when
- * `reduced` is `true`. Returns `keyframes` unchanged otherwise.
- *
- * The `transition` key is preserved so per-key transitions still flow through
- * to the animation engine.
- */
-export declare function filterReducedMotionKeyframes<T extends Record<string, unknown> | undefined>(keyframes: T, reduced: boolean): T;
-/**
- * Returns a readable store that reflects the resolved reduced-motion policy
- * for the current component subtree.
- *
- * Resolution combines the nearest `<MotionConfig reducedMotion>` ancestor with
- * the OS-level `prefers-reduced-motion` setting:
- *
- * - `'always'` → always `true`
- * - `'never'` (or no `<MotionConfig>` ancestor) → always `false`
- * - `'user'` → mirrors the OS preference, defaulting to `false` in SSR
- *
- * Use this from inside motion-aware components to decide whether to skip
- * transform animations.
- *
- * @returns {Readable<boolean>} `true` when descendant motion should be reduced.
- * @see https://motion.dev/docs/react-reduced-motion
- *
- * @example
- * ```svelte
- * <script>
- *   import { useReducedMotionConfig } from '@humanspeak/svelte-motion'
- *   const reduced = useReducedMotionConfig()
- * </script>
- *
- * {#if !$reduced}
- *   <motion.div animate={{ x: 100 }} />
- * {/if}
- * ```
- */
-export declare const useReducedMotionConfig: () => Readable<boolean>;

package/dist/utils/reducedMotionConfig.js

@@ -1,92 +0,0 @@
-import { getMotionConfig } from '../components/motionConfig.context.js';
-import { useReducedMotion } from './reducedMotion.js';
-import { derived } from 'svelte/store';
-/**
- * CSS / motion property keys that move or rotate an element via `transform`.
- * When reduced motion is active these keys are stripped from animate keyframes
- * so the element stays in place while non-transform properties (opacity, color,
- * etc.) continue to animate.
- */
-const TRANSFORM_KEYS = new Set([
-    'x',
-    'y',
-    'z',
-    'translate',
-    'translateX',
-    'translateY',
-    'translateZ',
-    'scale',
-    'scaleX',
-    'scaleY',
-    'scaleZ',
-    'rotate',
-    'rotateX',
-    'rotateY',
-    'rotateZ',
-    'skew',
-    'skewX',
-    'skewY',
-    'transform',
-    'transformPerspective',
-    'perspective'
-]);
-/**
- * Returns a copy of `keyframes` with transform-related keys removed when
- * `reduced` is `true`. Returns `keyframes` unchanged otherwise.
- *
- * The `transition` key is preserved so per-key transitions still flow through
- * to the animation engine.
- */
-export function filterReducedMotionKeyframes(keyframes, reduced) {
-    if (!reduced || !keyframes)
-        return keyframes;
-    const out = {};
-    for (const key of Object.keys(keyframes)) {
-        if (!TRANSFORM_KEYS.has(key))
-            out[key] = keyframes[key];
-    }
-    return out;
-}
-/**
- * Returns a readable store that reflects the resolved reduced-motion policy
- * for the current component subtree.
- *
- * Resolution combines the nearest `<MotionConfig reducedMotion>` ancestor with
- * the OS-level `prefers-reduced-motion` setting:
- *
- * - `'always'` → always `true`
- * - `'never'` (or no `<MotionConfig>` ancestor) → always `false`
- * - `'user'` → mirrors the OS preference, defaulting to `false` in SSR
- *
- * Use this from inside motion-aware components to decide whether to skip
- * transform animations.
- *
- * @returns {Readable<boolean>} `true` when descendant motion should be reduced.
- * @see https://motion.dev/docs/react-reduced-motion
- *
- * @example
- * ```svelte
- * <script>
- *   import { useReducedMotionConfig } from '@humanspeak/svelte-motion'
- *   const reduced = useReducedMotionConfig()
- * </script>
- *
- * {#if !$reduced}
- *   <motion.div animate={{ x: 100 }} />
- * {/if}
- * ```
- */
-export const useReducedMotionConfig = () => {
-    const motionConfig = getMotionConfig();
-    // Read motionConfig?.reducedMotion *inside* the derived so dynamic
-    // `<MotionConfig reducedMotion={...}>` updates surface to subscribers —
-    // motionConfig uses property getters, so the value is always fresh.
-    return derived(useReducedMotion(), ($osReduced) => {
-        const policy = motionConfig?.reducedMotion ?? 'never';
-        if (policy === 'always')
-            return true;
-        if (policy === 'never')
-            return false;
-        return $osReduced;
-    });
-};

package/dist/utils/spring.d.ts

@@ -1,51 +0,0 @@
-import { type Readable } from 'svelte/store';
-/**
- * Spring configuration options.
- *
- * This is a minimal subset modeled after Motion's spring transition options.
- * Values are tuned for sensible defaults, not parity.
- *
- * @typedef {Object} SpringOptions
- * @property {number=} stiffness Spring stiffness (higher = snappier). Default 170.
- * @property {number=} damping Spring damping (higher = less oscillation). Default 26.
- * @property {number=} mass Mass of the object. Default 1.
- * @property {number=} restDelta Threshold for absolute position delta to stop. Default 0.01.
- * @property {number=} restSpeed Threshold for velocity magnitude to stop. Default 0.01.
- */
-export type SpringOptions = {
-    stiffness?: number;
-    damping?: number;
-    mass?: number;
-    restDelta?: number;
-    restSpeed?: number;
-};
-/**
- * Function type for updating the spring's target with animation.
- *
- * @param v New target value to animate towards (number or unit string).
- */
-type SetType = (v: number | string) => void;
-/**
- * Function type for immediately setting the spring's value without animation.
- *
- * @param v New value to set instantly (number or unit string).
- */
-type JumpType = (v: number | string) => void;
-/**
- * Creates a spring-animated readable store. The store exposes `set` to
- * animate towards a target, or `jump` to immediately set the value without
- * animation. When constructed with another readable store, the spring
- * automatically follows it.
- *
- * This is SSR-safe: On the server it returns a static store and no timers run.
- *
- * @template T
- * @param {number|string|Readable<number|string>} source Initial value or a source store to follow.
- * @param {SpringOptions=} options Spring configuration.
- * @returns {Readable<number|string> & { set: (v: number|string) => void; jump: (v: number|string) => void; }}
- */
-export declare const useSpring: (source: number | string | Readable<number | string>, options?: SpringOptions) => Readable<number | string> & {
-    set: SetType;
-    jump: JumpType;
-};
-export {};

package/dist/utils/spring.js

@@ -1,157 +0,0 @@
-import { readable, writable } from 'svelte/store';
-/**
- * Parses a number or unit string into numeric value and unit.
- * @param {number|string} v The input value.
- * @returns {UnitValue} Parsed value and unit.
- * @private
- */
-const parseUnit = (v) => {
-    if (typeof v === 'number')
-        return { value: v, unit: '' };
-    const match = String(v).match(/^(-?\d*\.?\d+)(.*)$/);
-    if (!match || !match[1])
-        return { value: 0, unit: '' };
-    const parsed = Number.parseFloat(match[1]);
-    if (!Number.isFinite(parsed))
-        return { value: 0, unit: '' };
-    const unit = match[2] ?? '';
-    return { value: parsed, unit };
-};
-/**
- * Formats a numeric value with a unit.
- * @param {number} n Numeric value.
- * @param {string} unit Unit suffix.
- * @returns {number|string} Number or string with unit.
- * @private
- */
-const formatUnit = (n, unit) => (unit ? `${n}${unit}` : n);
-/**
- * Creates a spring-animated readable store. The store exposes `set` to
- * animate towards a target, or `jump` to immediately set the value without
- * animation. When constructed with another readable store, the spring
- * automatically follows it.
- *
- * This is SSR-safe: On the server it returns a static store and no timers run.
- *
- * @template T
- * @param {number|string|Readable<number|string>} source Initial value or a source store to follow.
- * @param {SpringOptions=} options Spring configuration.
- * @returns {Readable<number|string> & { set: (v: number|string) => void; jump: (v: number|string) => void; }}
- */
-export const useSpring = (source, options = {}) => {
-    if (typeof window === 'undefined') {
-        // Derive best-effort initial value for SSR to avoid hydration mismatch
-        let initial = 0;
-        if (typeof source === 'number' || typeof source === 'string') {
-            initial = source;
-        }
-        else if (source && typeof source === 'object') {
-            const anySource = source;
-            if (typeof anySource.get === 'function') {
-                const v = anySource.get();
-                if (typeof v === 'number' || typeof v === 'string')
-                    initial = v;
-            }
-            else if (typeof anySource.value === 'number' || typeof anySource.value === 'string') {
-                initial = anySource.value;
-            }
-        }
-        const store = readable(initial, () => { });
-        store.set = () => { };
-        store.jump = () => { };
-        return store;
-    }
-    const { stiffness = 170, damping = 26, mass = 1, restDelta = 0.01, restSpeed = 0.01 } = options;
-    const state = {
-        current: parseUnit(typeof source === 'object' ? 0 : source),
-        target: parseUnit(typeof source === 'object' ? 0 : source)
-    };
-    const unit = state.current.unit || state.target.unit;
-    const store = writable(formatUnit(state.current.value, unit));
-    let raf = 0;
-    let lastTime = 0;
-    let velocity = 0;
-    const step = (t) => {
-        if (!lastTime)
-            lastTime = t;
-        // Clamp dt to a safe range to avoid instability across large time gaps
-        const dt = Math.min(0.1, Math.max(0.001, (t - lastTime) / 1000));
-        lastTime = t;
-        const displacement = state.current.value - state.target.value;
-        // Spring force based on Hooke's Law: F = -k x; damping force: -c v
-        const spring = -stiffness * displacement;
-        const damper = -damping * velocity;
-        const accel = (spring + damper) / mass;
-        velocity += accel * dt;
-        state.current.value += velocity * dt;
-        const isNoVelocity = Math.abs(velocity) <= restSpeed;
-        const isNoDisplacement = Math.abs(state.current.value - state.target.value) <= restDelta;
-        const done = isNoVelocity && isNoDisplacement;
-        if (done) {
-            state.current.value = state.target.value;
-            store.set(formatUnit(state.current.value, unit));
-            raf = 0;
-            lastTime = 0;
-            return;
-        }
-        store.set(formatUnit(state.current.value, unit));
-        raf = requestAnimationFrame(step);
-    };
-    const start = () => {
-        if (raf)
-            return;
-        raf = requestAnimationFrame(step);
-    };
-    const api = {
-        set: (v) => {
-            state.target = parseUnit(v);
-            start();
-        },
-        jump: (v) => {
-            state.current = parseUnit(v);
-            state.target = parseUnit(v);
-            velocity = 0;
-            store.set(formatUnit(state.current.value, state.current.unit || state.target.unit));
-        }
-    };
-    // If following another store, subscribe and forward values to set()
-    if (typeof source === 'object' && 'subscribe' in source) {
-        let followSource = true;
-        const unsub = source.subscribe((v) => api.set(v));
-        const wrapped = readable(formatUnit(state.current.value, unit), (set) => {
-            const sub = store.subscribe(set);
-            return () => {
-                sub();
-                unsub();
-                followSource = false;
-                if (raf)
-                    cancelAnimationFrame(raf);
-            };
-        });
-        wrapped.set = (v) => {
-            if (followSource)
-                unsub();
-            followSource = false;
-            api.set(v);
-        };
-        wrapped.jump = (v) => {
-            if (followSource)
-                unsub();
-            followSource = false;
-            api.jump(v);
-        };
-        return wrapped;
-    }
-    // Standard readable wrapping internal writable
-    const wrapped = readable(formatUnit(state.current.value, unit), (set) => {
-        const sub = store.subscribe(set);
-        return () => {
-            sub();
-            if (raf)
-                cancelAnimationFrame(raf);
-        };
-    });
-    wrapped.set = api.set;
-    wrapped.jump = api.jump;
-    return wrapped;
-};