@humanspeak/svelte-motion 0.4.8 → 0.5.0

package/dist/utils/scroll.d.ts

@@ -1,63 +0,0 @@
-import { type Readable } from 'svelte/store';
-import { type ElementOrGetter } from './dom.js';
-/**
- * A scroll offset edge defined as a string (e.g. `"start"`, `"end"`, `"center"`)
- * or a number (0–1 progress). Each offset entry is a pair of `[target, container]`.
- */
-type ScrollOffset = Array<[number | string, number | string]> | string[];
-/**
- * Options accepted by `useScroll`.
- */
-type UseScrollOptions = {
-    /** Scrollable container to track. Defaults to the page. Accepts an element or a getter function. */
-    container?: ElementOrGetter;
-    /** Target element to track position of within the container. Accepts an element or a getter function. */
-    target?: ElementOrGetter;
-    /** Scroll offset configuration for element position tracking. */
-    offset?: ScrollOffset;
-    /** Which axis to use for the single-axis `progress` value supplied to `scroll()`. */
-    axis?: 'x' | 'y';
-};
-/**
- * Return type of `useScroll` — four readable Svelte stores representing
- * scroll position and normalised progress for both axes.
- */
-type UseScrollReturn = {
-    scrollX: Readable<number>;
-    scrollY: Readable<number>;
-    scrollXProgress: Readable<number>;
-    scrollYProgress: Readable<number>;
-};
-/**
- * Creates scroll-linked Svelte stores for building scroll-driven animations
- * such as progress indicators and parallax effects.
- *
- * When the returned stores are used with `opacity` / `transform` CSS properties
- * the animations can be hardware accelerated by the browser.
- *
- * SSR-safe: returns static `readable(0)` stores on the server.
- *
- * `container` and `target` accept either an `HTMLElement` directly or a
- * getter function `() => HTMLElement | undefined`. This is useful with
- * Svelte's `bind:this` where the element isn't available until after mount.
- * When a getter is provided, element resolution is deferred until the
- * first subscriber arrives, and if the element isn't available yet the
- * stores poll on each animation frame until it is.
- *
- * @example
- * ```svelte
- * <script>
- *   import { useScroll, useSpring } from '@humanspeak/svelte-motion'
- *
- *   const { scrollYProgress } = useScroll()
- *   const scaleX = useSpring(scrollYProgress)
- * </script>
- *
- * <div style="transform: scaleX({$scaleX}); transform-origin: left;" />
- * ```
- *
- * @param options Optional scroll tracking configuration.
- * @returns An object with `scrollX`, `scrollY`, `scrollXProgress`, and `scrollYProgress` stores.
- */
-export declare const useScroll: (options?: UseScrollOptions) => UseScrollReturn;
-export {};

package/dist/utils/scroll.js

@@ -1,79 +0,0 @@
-import { scroll } from 'motion';
-import { readable, writable } from 'svelte/store';
-import { createAttachable } from './attachable.js';
-import {} from './dom.js';
-/**
- * Creates scroll-linked Svelte stores for building scroll-driven animations
- * such as progress indicators and parallax effects.
- *
- * When the returned stores are used with `opacity` / `transform` CSS properties
- * the animations can be hardware accelerated by the browser.
- *
- * SSR-safe: returns static `readable(0)` stores on the server.
- *
- * `container` and `target` accept either an `HTMLElement` directly or a
- * getter function `() => HTMLElement | undefined`. This is useful with
- * Svelte's `bind:this` where the element isn't available until after mount.
- * When a getter is provided, element resolution is deferred until the
- * first subscriber arrives, and if the element isn't available yet the
- * stores poll on each animation frame until it is.
- *
- * @example
- * ```svelte
- * <script>
- *   import { useScroll, useSpring } from '@humanspeak/svelte-motion'
- *
- *   const { scrollYProgress } = useScroll()
- *   const scaleX = useSpring(scrollYProgress)
- * </script>
- *
- * <div style="transform: scaleX({$scaleX}); transform-origin: left;" />
- * ```
- *
- * @param options Optional scroll tracking configuration.
- * @returns An object with `scrollX`, `scrollY`, `scrollXProgress`, and `scrollYProgress` stores.
- */
-export const useScroll = (options) => {
-    if (typeof window === 'undefined') {
-        return {
-            scrollX: readable(0),
-            scrollY: readable(0),
-            scrollXProgress: readable(0),
-            scrollYProgress: readable(0)
-        };
-    }
-    const stores = {
-        scrollX: writable(0),
-        scrollY: writable(0),
-        scrollXProgress: writable(0),
-        scrollYProgress: writable(0)
-    };
-    const attachable = createAttachable({
-        refs: { container: options?.container, target: options?.target },
-        onAttach: ({ container, target }) => scroll((_progress, info) => {
-            stores.scrollX.set(info.x.current);
-            stores.scrollY.set(info.y.current);
-            stores.scrollXProgress.set(info.x.progress);
-            stores.scrollYProgress.set(info.y.progress);
-        }, {
-            container,
-            target,
-            offset: options?.offset,
-            axis: options?.axis
-        })
-    });
-    const make = (key) => readable(0, (set) => {
-        const release = attachable.subscribe();
-        const unsub = stores[key].subscribe(set);
-        return () => {
-            unsub();
-            release();
-        };
-    });
-    return {
-        scrollX: make('scrollX'),
-        scrollY: make('scrollY'),
-        scrollXProgress: make('scrollXProgress'),
-        scrollYProgress: make('scrollYProgress')
-    };
-};

package/dist/utils/time.d.ts

@@ -1,14 +0,0 @@
-import { type Readable } from 'svelte/store';
-/**
- * Returns a time store that ticks once per animation frame.
- *
- * - Without an `id`, returns a fresh timeline per call.
- * - With an `id`, callers sharing the same id receive the same store/timeline,
- *   ensuring synchronized reads across components.
- * - SSR-safe: Returns a static 0-valued store when `window` is unavailable.
- *
- * @param {string=} id Optional timeline identifier for sharing across calls.
- * @returns {Readable<number>} A readable store of elapsed milliseconds.
- * @see https://motion.dev/docs/react-use-time?platform=react
- */
-export declare const useTime: (id?: string) => Readable<number>;

package/dist/utils/time.js

@@ -1,68 +0,0 @@
-import { readable } from 'svelte/store';
-const SSR_ZERO = readable(0, () => { });
-const sharedStores = new Map();
-// Clear shared timelines on HMR dispose to avoid stale entries across hot reloads
-if (import.meta &&
-    import.meta.hot) {
-    ;
-    import.meta.hot.dispose(() => {
-        sharedStores.clear();
-    });
-}
-/**
- * Creates a new time store that updates once per animation frame.
- *
- * The store value represents elapsed milliseconds since the store was created.
- * In SSR environments (no `window`), a static 0-valued store is returned.
- *
- * @returns {Readable<number>} A readable store of elapsed milliseconds.
- * @see https://motion.dev/docs/react-use-time?platform=react
- * @private
- */
-const createTimeStore = () => {
-    if (typeof window === 'undefined')
-        return SSR_ZERO;
-    return readable(0, (set) => {
-        const start = performance.now();
-        let raf = 0;
-        /* c8 ignore start */
-        const loop = (t) => {
-            set(t - start);
-            raf = requestAnimationFrame(loop);
-        };
-        /* c8 ignore stop */
-        raf = requestAnimationFrame(loop);
-        return () => cancelAnimationFrame(raf);
-    });
-};
-/**
- * Returns a time store that ticks once per animation frame.
- *
- * - Without an `id`, returns a fresh timeline per call.
- * - With an `id`, callers sharing the same id receive the same store/timeline,
- *   ensuring synchronized reads across components.
- * - SSR-safe: Returns a static 0-valued store when `window` is unavailable.
- *
- * @param {string=} id Optional timeline identifier for sharing across calls.
- * @returns {Readable<number>} A readable store of elapsed milliseconds.
- * @see https://motion.dev/docs/react-use-time?platform=react
- */
-export const useTime = (id) => {
-    if (!id)
-        return createTimeStore();
-    if (typeof window === 'undefined')
-        return SSR_ZERO;
-    const existing = sharedStores.get(id);
-    if (existing)
-        return existing;
-    const base = createTimeStore();
-    const store = readable(0, (set) => {
-        const unsub = base.subscribe(set);
-        return () => {
-            unsub();
-            sharedStores.delete(id);
-        };
-    });
-    sharedStores.set(id, store);
-    return store;
-};

package/dist/utils/transform.d.ts

@@ -1,74 +0,0 @@
-export type TransformValues = Partial<{
-    x: number;
-    y: number;
-    scale: number;
-    scaleX: number;
-    scaleY: number;
-    rotate: number;
-}>;
-/**
- * Build a CSS transform string from numeric values (no matrices).
- *
- * @param values Partial map of translate/scale/rotate values.
- * @returns A space-separated CSS `transform` string, or `""` when all values are defaults.
- */
-export declare const buildTransform: (values: TransformValues) => string;
-/**
- * Lightweight safety check for transform magnitudes and NaN values.
- *
- * @param values Transform values to validate.
- * @param opts Optional configuration; `maxScale` caps allowable absolute scale (default 8).
- * @returns `true` if all scale values are finite and within bounds.
- */
-export declare const isSafeTransform: (values: TransformValues, opts?: {
-    maxScale?: number;
-}) => boolean;
-/**
- * Extract the uniform scale factor from a CSS `matrix()` string.
- *
- * @param matrix A CSS `matrix(...)` value, `"none"`, `null`, or `undefined`.
- * @returns The `a` component of the matrix (uniform scale), or `null` if unparseable.
- */
-export declare const parseMatrixScale: (matrix: string | null | undefined) => number | null;
-import { type Readable } from 'svelte/store';
-/**
- * Options for range-mapping transform.
- *
- * - clamp: If true, clamps the input to the active segment bounds.
- * - ease: A single easing function or one per segment to shape interpolation.
- * - mixer: Custom mixer factory to interpolate non-numeric outputs.
- *
- * @see https://motion.dev/docs/react-use-transform?platform=react
- */
-export type TransformOptions = {
-    clamp?: boolean;
-    ease?: ((t: number) => number) | Array<(t: number) => number>;
-    mixer?: (from: unknown, to: unknown) => (t: number) => unknown;
-};
-/**
- * Clamps a numeric value between two bounds, irrespective of their order.
- *
- * @param val Current value.
- * @param a First bound.
- * @param b Second bound.
- * @returns Value clamped to [min(a,b), max(a,b)].
- */
-export declare const clampBidirectional: (val: number, a: number, b: number) => number;
-/**
- * Creates a derived Svelte store that transforms values.
- *
- * Two supported forms (API parity with Motion's useTransform):
- * - Mapping form: Map a numeric source across input/output ranges.
- *   Example: `useTransform(src, [0, 100], [0, 1], { clamp: true })`
- * - Function form: Recompute from a function based on dependency stores.
- *   Example: `useTransform(() => compute(), [depA, depB])`
- *
- * @template T
- * @param {Readable<number>|(() => T)} sourceOrCompute Numeric source store (mapping form), or compute function (function form).
- * @param {number[]|Readable<unknown>[]} inputOrDeps Input stops (mapping) or dependency stores (function form).
- * @param {T[]=} output Output stops (mapping form only). Must match input length.
- * @param {TransformOptions=} options Mapping options (mapping form only).
- * @returns {Readable<T>} A derived Svelte readable store.
- * @see https://motion.dev/docs/react-use-transform?platform=react
- */
-export declare const useTransform: <T = number>(sourceOrCompute: Readable<number> | (() => T), inputOrDeps: number[] | Readable<unknown>[], output?: T[], options?: TransformOptions) => Readable<T>;

package/dist/utils/transform.js

@@ -1,211 +0,0 @@
-// Utilities for building and validating transform strings
-const DEFAULTS = {
-    x: 0,
-    y: 0,
-    scale: 1,
-    scaleX: 1,
-    scaleY: 1,
-    rotate: 0
-};
-/**
- * Build a CSS transform string from numeric values (no matrices).
- *
- * @param values Partial map of translate/scale/rotate values.
- * @returns A space-separated CSS `transform` string, or `""` when all values are defaults.
- */
-export const buildTransform = (values) => {
-    const v = { ...DEFAULTS, ...values };
-    // If explicit per-axis scales provided, use them; otherwise use uniform scale
-    const useAxes = values.scaleX !== undefined || values.scaleY !== undefined;
-    const parts = [];
-    // Translate first for readability; rely on browser to optimize
-    if (v.x !== 0 || v.y !== 0)
-        parts.push(`translate(${round(v.x)}px, ${round(v.y)}px)`);
-    if (v.rotate !== 0)
-        parts.push(`rotate(${round(v.rotate)}deg)`);
-    if (useAxes) {
-        parts.push(`scaleX(${round(v.scaleX)})`);
-        parts.push(`scaleY(${round(v.scaleY)})`);
-    }
-    else if (v.scale !== 1) {
-        parts.push(`scale(${round(v.scale)})`);
-    }
-    return parts.join(' ').trim();
-};
-/**
- * Lightweight safety check for transform magnitudes and NaN values.
- *
- * @param values Transform values to validate.
- * @param opts Optional configuration; `maxScale` caps allowable absolute scale (default 8).
- * @returns `true` if all scale values are finite and within bounds.
- */
-export const isSafeTransform = (values, opts) => {
-    const maxScale = opts?.maxScale ?? 8;
-    const entries = [
-        ['scale', values.scale],
-        ['scaleX', values.scaleX],
-        ['scaleY', values.scaleY]
-    ];
-    for (const [, val] of entries) {
-        if (val === undefined)
-            continue;
-        if (!Number.isFinite(val))
-            return false;
-        if (Math.abs(val) > maxScale)
-            return false;
-    }
-    return true;
-};
-/**
- * Extract the uniform scale factor from a CSS `matrix()` string.
- *
- * @param matrix A CSS `matrix(...)` value, `"none"`, `null`, or `undefined`.
- * @returns The `a` component of the matrix (uniform scale), or `null` if unparseable.
- */
-export const parseMatrixScale = (matrix) => {
-    if (!matrix || matrix === 'none')
-        return null;
-    const m = matrix.match(/matrix\(([^)]+)\)/);
-    if (!m)
-        return null;
-    const [a] = m[1].split(',').map((s) => parseFloat(s.trim()));
-    return Number.isFinite(a) ? a : null;
-};
-/**
- * Round a number to six decimal places to avoid excessive precision in CSS strings.
- *
- * @param n The number to round.
- * @returns The rounded value.
- */
-const round = (n) => {
-    return Math.round(n * 1e6) / 1e6;
-};
-import { derived, readable } from 'svelte/store';
-/**
- * Creates a linear mixer function for numeric values.
- *
- * @param from Starting numeric value.
- * @param to Ending numeric value.
- * @returns Function that linearly interpolates between from→to for progress t∈[0,1].
- * @private
- */
-const linearMix = (from, to) => (t) => from + (to - from) * t;
-/**
- * Clamps a numeric value between two bounds, irrespective of their order.
- *
- * @param val Current value.
- * @param a First bound.
- * @param b Second bound.
- * @returns Value clamped to [min(a,b), max(a,b)].
- */
-export const clampBidirectional = (val, a, b) => {
-    const lower = a < b ? a : b;
-    const upper = a < b ? b : a;
-    return Math.min(Math.max(val, lower), upper);
-};
-/**
- * Finds the segment index i such that x lies between input[i] and input[i+1].
- * Handles both ascending and descending input ranges.
- *
- * @param input Monotonic list of input stops.
- * @param x Current input value.
- * @returns Segment index in range [0, input.length - 2].
- * @private
- */
-const findSegment = (input, x) => {
-    if (input.length < 2)
-        return 0;
-    const first = input[0];
-    const second = input[1];
-    const ascending = second > first;
-    if (ascending) {
-        if (x <= first)
-            return 0;
-        for (let i = 1; i < input.length; i++) {
-            const curr = input[i];
-            if (x <= curr)
-                return i - 1;
-        }
-        return input.length - 2;
-    }
-    else {
-        if (x >= first)
-            return 0;
-        for (let i = 1; i < input.length; i++) {
-            const curr = input[i];
-            if (x >= curr)
-                return i - 1;
-        }
-        return input.length - 2;
-    }
-};
-/**
- * Creates a derived Svelte store that transforms values.
- *
- * Two supported forms (API parity with Motion's useTransform):
- * - Mapping form: Map a numeric source across input/output ranges.
- *   Example: `useTransform(src, [0, 100], [0, 1], { clamp: true })`
- * - Function form: Recompute from a function based on dependency stores.
- *   Example: `useTransform(() => compute(), [depA, depB])`
- *
- * @template T
- * @param {Readable<number>|(() => T)} sourceOrCompute Numeric source store (mapping form), or compute function (function form).
- * @param {number[]|Readable<unknown>[]} inputOrDeps Input stops (mapping) or dependency stores (function form).
- * @param {T[]=} output Output stops (mapping form only). Must match input length.
- * @param {TransformOptions=} options Mapping options (mapping form only).
- * @returns {Readable<T>} A derived Svelte readable store.
- * @see https://motion.dev/docs/react-use-transform?platform=react
- */
-export const useTransform = (sourceOrCompute, inputOrDeps, output, options = {}) => {
-    // Function form: (compute, deps)
-    if (typeof sourceOrCompute === 'function') {
-        const compute = sourceOrCompute;
-        const deps = inputOrDeps;
-        if (!deps || deps.length === 0)
-            return readable(compute());
-        return derived(deps, () => compute());
-    }
-    // Mapping form: (source, input, output, options)
-    const source = sourceOrCompute;
-    const input = inputOrDeps;
-    const out = (output ?? []);
-    const { clamp = true, ease, mixer } = options;
-    if (input.length !== out.length) {
-        throw new Error(`useTransform: input and output arrays must be the same length (input: ${input.length}, output: ${out.length})`);
-    }
-    const easings = Array.isArray(ease)
-        ? ease
-        : ease
-            ? new Array(Math.max(0, out.length - 1)).fill(ease)
-            : [];
-    return derived(source, (x) => {
-        if (input.length === 0)
-            return out[0];
-        if (input.length === 1)
-            return out[0];
-        const seg = findSegment(input, x);
-        const i0 = input[seg];
-        const i1 = input[seg + 1];
-        const o0 = out[seg];
-        const o1 = out[seg + 1];
-        // Runtime validation to avoid non-null assertions
-        if (i0 === undefined || i1 === undefined || o0 === undefined || o1 === undefined) {
-            console.warn('useTransform: Invalid segment bounds', {
-                seg,
-                inputLength: input.length,
-                outputLength: out.length
-            });
-            return out[0];
-        }
-        const localClamp = clamp ? clampBidirectional : (val) => val;
-        const progress = i0 === i1 ? 0 : (localClamp(x, i0, i1) - i0) / (i1 - i0);
-        const e = easings[seg];
-        const p = e ? e(progress) : progress;
-        const mix = mixer
-            ? mixer(o0, o1)
-            : typeof o0 === 'number' && typeof o1 === 'number'
-                ? linearMix(o0, o1)
-                : (_t) => (p < 0.5 ? o0 : o1); // trunk-ignore(eslint/@typescript-eslint/no-unused-vars)
-        return mix(p);
-    });
-};

package/dist/utils/velocity.d.ts

@@ -1,15 +0,0 @@
-import { type Readable } from 'svelte/store';
-/**
- * Creates a readable store that tracks the velocity of a source store's value.
- *
- * Uses `motionValue` from motion-dom for built-in velocity tracking with
- * timestamps. Polls velocity via `requestAnimationFrame` and settles to 0
- * when movement stops.
- *
- * SSR-safe: returns a static `readable(0)` on the server.
- *
- * @param source A readable store of numeric or unit-string values.
- * @returns A readable store of the current velocity in units/second.
- * @see https://motion.dev/docs/react-use-velocity
- */
-export declare const useVelocity: (source: Readable<number | string>) => Readable<number>;

package/dist/utils/velocity.js

@@ -1,62 +0,0 @@
-import { motionValue } from 'motion-dom';
-import { readable, writable } from 'svelte/store';
-/**
- * Parses a numeric value from a number or unit string (e.g. "100px" → 100).
- */
-const parseNumeric = (v) => {
-    if (typeof v === 'number')
-        return v;
-    const parsed = Number.parseFloat(String(v));
-    return Number.isFinite(parsed) ? parsed : 0;
-};
-/**
- * Creates a readable store that tracks the velocity of a source store's value.
- *
- * Uses `motionValue` from motion-dom for built-in velocity tracking with
- * timestamps. Polls velocity via `requestAnimationFrame` and settles to 0
- * when movement stops.
- *
- * SSR-safe: returns a static `readable(0)` on the server.
- *
- * @param source A readable store of numeric or unit-string values.
- * @returns A readable store of the current velocity in units/second.
- * @see https://motion.dev/docs/react-use-velocity
- */
-export const useVelocity = (source) => {
-    if (typeof window === 'undefined')
-        return readable(0, () => { });
-    const mv = motionValue(0);
-    const store = writable(0);
-    let raf = 0;
-    let settled = true;
-    const poll = () => {
-        const v = mv.getVelocity();
-        store.set(v);
-        if (Math.abs(v) < 0.001) {
-            settled = true;
-            store.set(0);
-            raf = 0;
-            return;
-        }
-        raf = requestAnimationFrame(poll);
-    };
-    const startPolling = () => {
-        if (!settled)
-            return;
-        settled = false;
-        raf = requestAnimationFrame(poll);
-    };
-    return readable(0, (set) => {
-        const unsubStore = store.subscribe(set);
-        const unsubSource = source.subscribe((v) => {
-            mv.set(parseNumeric(v));
-            startPolling();
-        });
-        return () => {
-            unsubStore();
-            unsubSource();
-            if (raf)
-                cancelAnimationFrame(raf);
-        };
-    });
-};