@humanspeak/svelte-motion 0.4.8 → 0.4.9

package/dist/utils/inView.d.ts

@@ -1,136 +0,0 @@
-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.
- *
- * @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 declare const splitInViewDefinition: (def: Record<string, unknown>) => {
-    keyframes: Record<string, unknown>;
-    transition?: AnimationOptions;
-};
-/**
- * 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 declare const computeInViewBaseline: (el: HTMLElement, opts: {
-    initial?: Record<string, unknown>;
-    animate?: Record<string, unknown>;
-    whileInView?: Record<string, unknown>;
-}) => Record<string, unknown>;
-/**
- * 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 declare const attachWhileInView: (el: HTMLElement, whileInView: Record<string, unknown> | undefined, mergedTransition: AnimationOptions, callbacks?: {
-    onStart?: () => void;
-    onEnd?: () => void;
-    onAnimationComplete?: (definition: DOMKeyframesDefinition | undefined) => void;
-}, baselineSources?: {
-    initial?: Record<string, unknown>;
-    animate?: Record<string, unknown>;
-}, viewport?: MotionViewport) => (() => void);
-/**
- * Options accepted by `useInView`.
- */
-export type UseInViewOptions = {
-    /** Element to use as the IntersectionObserver root. Defaults to the viewport. */
-    root?: ElementOrGetter;
-    /** 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;
-    /** When `true`, the store latches to `true` on first entry and never flips back. */
-    once?: boolean;
-    /** Initial value emitted before the first IntersectionObserver callback. */
-    initial?: boolean;
-};
-/**
- * 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 declare const useInView: (target: ElementOrGetter, options?: UseInViewOptions) => Readable<boolean>;

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;
-    });
-};