motionary 0.0.0-stage → 6.2.0

package/dist/index.d.ts

@@ -0,0 +1,425 @@
+/**
+ * motionary - Core Type Definitions
+ * A lightweight, high-performance scroll animation library
+ */
+/** The 33 core presets (always available in `PRESETS`). */
+type CorePreset = 'fade-in' | 'fade-in-up' | 'fade-in-down' | 'fade-in-left' | 'fade-in-right' | 'zoom-in' | 'zoom-out' | 'flip-x' | 'flip-y' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right' | 'bounce' | 'rotate-in' | 'blur-in' | 'skew-in' | 'scale-x' | 'scale-y' | 'shimmer' | 'pulse' | 'swing' | 'scale-up' | 'blur-in-up' | 'flip-up' | 'flip-down' | 'rotate-left' | 'rotate-right' | 'clip-up' | 'clip-down' | 'clip-left' | 'clip-right' | 'clip-circle';
+/**
+ * Every built-in preset name: the core set plus the 6.1 extended set, which is
+ * available once `motionary/presets/extended` is loaded (or after
+ * `registerPresets(EXTENDED_PRESETS)`).
+ */
+type AnimationPreset = CorePreset | ExtendedPreset;
+/**
+ * How `onProgress` / `progressVar` progress is measured.
+ * - `'ratio'` (default): the element's visible ratio (IntersectionObserver `intersectionRatio`).
+ * - `'scroll'`: true scroll progress, 0 when the element's top touches the bottom of the
+ *   viewport and 1 when its bottom leaves the top. Works for elements taller than the screen.
+ */
+type ProgressMode = 'ratio' | 'scroll';
+/**
+ * Which engine runs the entrance animation.
+ * - `'js'`: IntersectionObserver triggers a time-based Web Animation.
+ * - `'css'`: the preset runs on the browser's native scroll-driven timeline
+ *   (`animation-timeline: view()`), so its progress follows the scroll position
+ *   off the main thread. Falls back to `'js'` where unsupported.
+ * - `'auto'` (default since 2.0): native when supported, JS otherwise — and JS
+ *   whenever the element sets `duration`, `delay`, `offset` or `stagger` itself,
+ *   since those only mean something for a time-based animation.
+ */
+type ScrollEngine = 'auto' | 'js' | 'css';
+/** The 6.1 extended presets (`motionary/presets/extended`). */
+type ExtendedPreset = 'fade-in-up-sm' | 'fade-in-down-sm' | 'fade-in-left-sm' | 'fade-in-right-sm' | 'fade-in-up-lg' | 'fade-in-down-lg' | 'fade-in-left-lg' | 'fade-in-right-lg' | 'fade-in-up-left' | 'fade-in-up-right' | 'fade-in-down-left' | 'fade-in-down-right' | 'fade-in-scale' | 'fade-in-half' | 'zoom-in-up' | 'zoom-in-down' | 'zoom-in-left' | 'zoom-in-right' | 'zoom-out-up' | 'zoom-out-down' | 'zoom-out-left' | 'zoom-out-right' | 'zoom-in-big' | 'zoom-out-big' | 'zoom-bounce' | 'zoom-in-rotate' | 'scale-x-left' | 'scale-x-right' | 'scale-y-top' | 'scale-y-bottom' | 'stretch-x' | 'stretch-y' | 'flip-x-reverse' | 'flip-y-reverse' | 'flip-y-full' | 'flip-diagonal' | 'flip-diagonal-reverse' | 'flip-left' | 'flip-right' | 'unfold-down' | 'unfold-up' | 'door-open-left' | 'door-open-right' | 'fold-in' | 'flip-x-bounce' | 'flip-y-bounce' | 'swing-in-top' | 'swing-in-bottom' | 'swing-in-left' | 'swing-in-right' | 'slide-up-spring' | 'slide-down-spring' | 'slide-left-spring' | 'slide-right-spring' | 'slide-up-sm' | 'slide-down-sm' | 'back-in-up' | 'back-in-down' | 'back-in-left' | 'back-in-right' | 'light-speed-in-left' | 'light-speed-in-right' | 'rise-in' | 'sink-in' | 'float-in-up' | 'float-in-down' | 'roll-in-left' | 'roll-in-right' | 'spiral-in' | 'spiral-in-reverse' | 'spin-in' | 'rotate-in-up-left' | 'rotate-in-up-right' | 'rotate-in-down-left' | 'rotate-in-down-right' | 'skew-in-left' | 'skew-in-y' | 'shear-in' | 'shear-in-reverse' | 'twist-in' | 'tilt-in-left' | 'tilt-in-right' | 'blur-in-down' | 'blur-in-left' | 'blur-in-right' | 'blur-in-strong' | 'blur-in-zoom' | 'blur-in-scale' | 'blur-in-x' | 'mask-up' | 'mask-down' | 'mask-left' | 'mask-right' | 'blur-mask-up' | 'clip-circle-top' | 'clip-circle-bottom' | 'clip-circle-left' | 'clip-circle-right' | 'clip-circle-corner' | 'clip-ellipse' | 'clip-diamond' | 'clip-split-x' | 'clip-split-y' | 'clip-box' | 'clip-pill' | 'clip-blinds' | 'clip-blinds-x' | 'clip-diagonal' | 'clip-diagonal-reverse' | 'clip-slant-right' | 'clip-slant-left' | 'bounce-in' | 'bounce-in-up' | 'bounce-in-down' | 'bounce-in-left' | 'bounce-in-right' | 'elastic-in' | 'elastic-in-x' | 'rubber-in' | 'jello-in' | 'wobble-in' | 'tada-in' | 'heartbeat-in' | 'drop-in' | 'pop-in' | 'squash-in' | 'shake-in' | 'swing-in' | 'brightness-in' | 'darken-in' | 'color-in' | 'saturate-in' | 'hue-in' | 'sepia-in' | 'invert-in' | 'contrast-in' | 'exposure-in' | 'vintage-in' | 'blur-bright-in' | 'shadow-lift' | 'neon-glow-in' | 'glow-in' | 'perspective-in-up' | 'perspective-in-down' | 'perspective-in-left' | 'perspective-in-right' | 'depth-push' | 'depth-pull' | 'depth-in-up' | 'swoop-in-left' | 'swoop-in-right' | 'card-tilt-in' | 'glitch-in' | 'glitch-in-color' | 'typewriter' | 'typewriter-lines' | 'hinge-in' | 'flicker-in' | 'scan-in' | 'materialize' | 'teleport-in' | 'stagger-fade-up' | 'stagger-pop' | 'stagger-rise' | 'stagger-slide' | 'stagger-flip' | 'stagger-blur' | 'stagger-zoom' | 'stagger-drop' | 'scrub-parallax-up' | 'scrub-parallax-down' | 'scrub-rotate' | 'scrub-spin' | 'scrub-scale' | 'scrub-shrink' | 'scrub-pan-left' | 'scrub-pan-right' | 'scrub-tilt' | 'scrub-fade-through' | 'scrub-blur-through' | 'scrub-reveal-x';
+/** Easing function types */
+type EasingType = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'spring' | 'soft-spring' | 'heavy-bounce' | [number, number, number, number] | ((t: number) => number) | string;
+/** Keyframe definition for custom animations */
+interface AnimationKeyframe {
+    [property: string]: string | number;
+}
+/** One intermediate keyframe of a preset: `offset` is 0 < offset < 1. */
+interface AnimationFrame extends AnimationKeyframe {
+    offset: number;
+}
+/** Custom animation definition */
+interface CustomAnimation {
+    from: AnimationKeyframe;
+    to: AnimationKeyframe;
+    /** Optional intermediate keyframes (overshoot, bounce, …), played between `from` and `to`. */
+    frames?: AnimationFrame[];
+}
+/** The keyframes of a preset (`PRESETS[name]`). */
+type PresetKeyframes = CustomAnimation;
+/** Per-element animation options */
+interface AnimateOptions {
+    /** Animation preset name, array of presets, or custom animation object */
+    animation?: AnimationPreset | AnimationPreset[] | CustomAnimation;
+    /** Duration in milliseconds (default: 600) */
+    duration?: number;
+    /** Delay in milliseconds (default: 0) */
+    delay?: number;
+    /** Easing function (default: 'ease') */
+    easing?: EasingType;
+    /** Intersection threshold 0-1 (default: 0.1) */
+    threshold?: number | number[];
+    /** Root margin for IntersectionObserver (default: '0px') */
+    rootMargin?: string;
+    /** Whether to replay animation each time element enters viewport (default: false) */
+    repeat?: boolean;
+    /** Whether to trigger animation only once (default: true if repeat is false) */
+    once?: boolean;
+    /** Offset in pixels from the viewport edge to trigger animation (default: 0) */
+    offset?: number;
+    /** Stagger delay for child elements in ms (default: 0) */
+    stagger?: number;
+    /** Callback fired when animation starts */
+    onStart?: (element: Element) => void;
+    /** Callback fired when animation completes */
+    onComplete?: (element: Element) => void;
+    /** Callback fired when element enters viewport */
+    onEnter?: (element: Element) => void;
+    /** Callback fired when element leaves viewport */
+    onLeave?: (element: Element) => void;
+    /** Callback fired with scroll progress (0 to 1) */
+    onProgress?: (element: Element, progress: number) => void;
+    /** How progress for `onProgress`/`progressVar` is measured (default: 'ratio') */
+    progressMode?: ProgressMode;
+    /**
+     * Name of a CSS custom property (e.g. `'--sa-progress'`) that receives the
+     * element's progress (0 to 1, same value as `onProgress`) as an inline
+     * style, for scroll-driven effects written in plain CSS. Off by default.
+     */
+    progressVar?: string;
+    /**
+     * Animation engine (default: `'auto'`, see `ScrollEngine`). With the native
+     * engine the animation is linked to scroll position: `duration`, `delay`,
+     * `threshold`, `offset` and `stagger` do not apply; `viewRange` does.
+     */
+    engine?: ScrollEngine;
+    /**
+     * Native engine only: the view-timeline range the entrance animation spans,
+     * as `[rangeStart, rangeEnd]` (default: `['entry 0%', 'entry 100%']`).
+     */
+    viewRange?: [string, string];
+    /**
+     * Animate out when the element leaves the viewport, and back in when it
+     * re-enters (implies `repeat: true` unless `repeat` is set).
+     * - `true`: play the entrance animation in reverse.
+     * - a preset / presets / `{ from, to }`: play that animation in reverse
+     *   (e.g. `exit: 'fade-in-down'` leaves upwards).
+     * Skipped under reduced motion. (default: `false`)
+     */
+    exit?: boolean | AnimationPreset | AnimationPreset[] | CustomAnimation;
+}
+/** Global configuration for ScrollAnimate instance */
+interface ScrollAnimateConfig {
+    /** Default animation preset (default: 'fade-in-up') */
+    defaultAnimation?: AnimationPreset | AnimationPreset[] | CustomAnimation;
+    /** Default duration in ms (default: 600) */
+    defaultDuration?: number;
+    /** Default delay in ms (default: 0) */
+    defaultDelay?: number;
+    /** Default easing (default: 'ease') */
+    defaultEasing?: EasingType;
+    /** Default threshold (default: 0.1) */
+    defaultThreshold?: number | number[];
+    /** Default root margin (default: '0px') */
+    defaultRootMargin?: string;
+    /** Whether animations replay by default (default: false) */
+    defaultRepeat?: boolean;
+    /** Default once setting (default: true) */
+    defaultOnce?: boolean;
+    /** Default offset in pixels (default: 0) */
+    defaultOffset?: number;
+    /** CSS class added before animation (default: 'sa-hidden') */
+    hiddenClass?: string;
+    /** CSS class added when element is visible (default: 'sa-visible') */
+    visibleClass?: string;
+    /** Whether to use CSS class-based animation instead of Web Animations API */
+    useClassNames?: boolean;
+    /** Disable all animations (useful for reduced-motion preference) */
+    disabled?: boolean;
+    /** Custom IntersectionObserver root element */
+    root?: Element | null;
+    /**
+     * Drop `once` elements from the registry as soon as their entrance animation
+     * has been triggered (unless they still need onProgress/progressVar), so they can
+     * be garbage-collected. They are remembered in a WeakSet, so `init()`/`observe()`
+     * never re-hide or replay them. (default: true)
+     */
+    autoUnregister?: boolean;
+    /** Default animation engine (default: `'auto'`; `'js'` restores the 1.x behaviour) */
+    defaultEngine?: ScrollEngine;
+}
+/** Registered element entry */
+interface AnimatedElement {
+    element: Element;
+    options: Required<AnimateOptions>;
+    observer: IntersectionObserver;
+    animated: boolean;
+    progressObserver?: IntersectionObserver;
+    /** Engine actually used for this element (`'css'` = native scroll-driven timeline) */
+    engine?: 'js' | 'css';
+}
+/** ScrollAnimate public API */
+interface ScrollAnimateInstance {
+    /** Observe a single element or CSS selector */
+    observe(target: string | Element | NodeList | Element[], options?: AnimateOptions): void;
+    /** Stop observing a single element or CSS selector */
+    unobserve(target: string | Element | NodeList | Element[]): void;
+    /** Observe all elements matching the data-sa attribute */
+    init(rootElement?: Element | Document): void;
+    /**
+     * Like `init()`, then keep watching `rootElement` (default: `document`) with a
+     * MutationObserver: `[data-sa]` elements added later (or that gain the
+     * attribute) are observed automatically, and removed ones are released.
+     * Returns a function that stops watching. `destroy()` stops every watcher.
+     * SSR-safe: a no-op without a DOM / MutationObserver.
+     */
+    watch(rootElement?: Element | Document): () => void;
+    /** Destroy the instance and clean up all observers */
+    destroy(): void;
+    /** Refresh all observers (useful after DOM changes) */
+    refresh(): void;
+    /** Manually trigger animation on an element */
+    animate(target: string | Element, options?: AnimateOptions): void;
+    /** Get all currently observed elements */
+    getObservedElements(): AnimatedElement[];
+    /** Update global configuration */
+    configure(config: Partial<ScrollAnimateConfig>): void;
+}
+
+/**
+ * motionary - Core Implementation
+ * Uses IntersectionObserver + Web Animations API for zero-dependency,
+ * high-performance scroll-triggered animations.
+ */
+
+/**
+ * Whether the browser can run presets on a native scroll-driven timeline:
+ * `CSS.supports('animation-timeline: view()')` plus the `ViewTimeline`
+ * constructor used to attach it from JavaScript. Cached. SSR-safe.
+ */
+declare function supportsScrollTimeline(): boolean;
+/**
+ * True scroll progress of `el` through the viewport (or `root`): 0 when its top
+ * edge reaches the bottom of the viewport, 1 when its bottom edge passes the top.
+ * Works for elements taller than the viewport. Returns 0 without a DOM.
+ */
+declare function getScrollProgress(el: Element, root?: Element | null): number;
+declare function createScrollAnimate(userConfig?: ScrollAnimateConfig): ScrollAnimateInstance;
+
+/**
+ * motionary - Staggered children
+ * Reveal a container's children one after another when the container scrolls
+ * into view, optionally also animating children that are added later.
+ */
+
+interface StaggerOptions extends AnimateOptions {
+    /** Delay between consecutive children in ms (default: 80) */
+    stagger?: number;
+    /**
+     * Watch the container with a MutationObserver and animate children added
+     * later (e.g. infinite lists). Children added after the container was
+     * revealed animate when they scroll into view, staggered per batch.
+     * (default: false)
+     */
+    observeChildren?: boolean;
+}
+/**
+ * Animate the children of `container` with a stagger once it enters the
+ * viewport. Returns a cleanup function. SSR-safe (no-op without a DOM).
+ *
+ * @example
+ * const stop = staggerChildren(document.querySelector('ul'), { stagger: 60, observeChildren: true });
+ */
+declare function staggerChildren(container: Element | null | undefined, options?: StaggerOptions, instance?: ScrollAnimateInstance): () => void;
+
+/**
+ * Where a step starts on a timeline:
+ * - a number: absolute time in ms
+ * - `'>'` (default): when the previous step ends · `'<'`: when it starts
+ * - `'+=200'` / `'-=200'`: after / overlapping the previous end
+ * - `'<+=100'`: 100ms after the previous step's start
+ * - `'intro'` / `'intro+=150'`: at (or relative to) a label
+ */
+type TimelinePosition = number | string;
+interface TimelineStepOptions {
+    /** Duration in ms or a motion token name (`'fast'`, `'slow'`…; 4.2). Default: timeline default, 600. */
+    duration?: number | string;
+    /** CSS easing or a motion token name (`'emphasized'`, `'spring'`…; 4.2). Default `cubic-bezier(0.22, 1, 0.36, 1)`. */
+    easing?: string;
+    /** Start position, see `TimelinePosition`. */
+    at?: TimelinePosition;
+    /** ms between targets when the selector matches several elements. */
+    stagger?: number;
+}
+interface TimelineOptions {
+    /** Defaults for every step. */
+    defaults?: Pick<TimelineStepOptions, 'duration' | 'easing' | 'stagger'>;
+    /** Playback rate (1 = normal). */
+    speed?: number;
+    /** Called after `play()` reaches the end (or the start when reversed). */
+    onComplete?: () => void;
+    /** Called on every frame with progress 0–1. */
+    onUpdate?: (progress: number) => void;
+}
+interface ScrubOptions {
+    /** Scroll offset (px) before the source's top reaches the viewport bottom where progress starts (JS engine only). */
+    offset?: number;
+    /** Smoothing 0–1 (0 = immediate, default 0). Smoothing needs the JS engine. */
+    smooth?: number;
+    /**
+     * 4.1: which progress source drives the timeline.
+     * - `'view'` (default): `source` moving through the viewport (CSS `ViewTimeline`, range `cover`).
+     * - `'scroll'`: the scroll position of `source` itself (a scroll container; CSS `ScrollTimeline`).
+     */
+    source?: 'view' | 'scroll';
+    /** 4.1: `'auto'` (default) uses the browser's native scroll-driven animations when available, `'js'` forces the fallback. */
+    engine?: 'auto' | 'native' | 'js';
+    /** 4.1: scroll axis, `'block'` (default) · `'inline'` · `'x'` · `'y'`. */
+    axis?: 'block' | 'inline' | 'x' | 'y';
+}
+/** The function `scrub()` returns: call it to stop. `native` tells which engine runs it. */
+interface ScrubHandle {
+    (): void;
+    /** `true` when the browser's ScrollTimeline / ViewTimeline drives it (compositor, no JS per frame). */
+    readonly native: boolean;
+}
+/** 4.1: whether `scrub()` can use native ScrollTimeline / ViewTimeline here. */
+declare function supportsNativeScrub(source?: 'view' | 'scroll'): boolean;
+interface Timeline {
+    /** Total length in ms. */
+    readonly duration: number;
+    /** Label positions in ms. */
+    readonly labels: Readonly<Record<string, number>>;
+    /** Current playhead in ms. */
+    readonly time: number;
+    /** Add a step: animate `target` with keyframes or a preset name (`fade-up`, `scale`…). */
+    to(target: string | Element | Element[] | NodeList, frames: Keyframe[] | string, options?: TimelineStepOptions): Timeline;
+    /** Name a position (default: the current end). */
+    label(name: string, at?: TimelinePosition): Timeline;
+    /** Run `fn` when the playhead passes `at`. */
+    call(fn: () => void, at?: TimelinePosition): Timeline;
+    /** Play forwards from the playhead (from 0 when at the end). Resolves at the end. */
+    play(from?: TimelinePosition): Promise<void>;
+    /** Play backwards to 0. */
+    reverse(): Promise<void>;
+    pause(): Timeline;
+    /** Jump to a time (ms) or label. */
+    seek(to: TimelinePosition): Timeline;
+    /** Get or set progress 0–1. */
+    progress(p?: number): number;
+    /**
+     * Tie progress to scroll: `source` moving through the viewport (or, with
+     * `{ source: 'scroll' }`, a scroll container's own position). Runs on native
+     * ScrollTimeline / ViewTimeline when available (and no `smooth`, `offset`,
+     * `call()` cues or `onUpdate` need JS), else on a rAF-throttled listener.
+     * Returns a stop function with a `native` flag.
+     */
+    scrub(source: Element, options?: ScrubOptions): ScrubHandle;
+    /** Stop and drop every animation (elements keep their last frame). */
+    cancel(): void;
+}
+/** Keyframe presets usable by name in `to()` and `data-tl`. */
+declare const TIMELINE_PRESETS: Record<string, Keyframe[]>;
+/** Resolve a position against the previous step and labels (pure). */
+declare function resolvePosition(pos: TimelinePosition | undefined, end: number, prevStart: number, labels?: Record<string, number>): number;
+/**
+ * Choreograph animations on one clock: chain, overlap, label, seek, reverse and
+ * scrub them with scroll. Built on WAAPI (paused animations driven by one
+ * playhead); without WAAPI or under reduced motion it jumps to the end state.
+ *
+ * @example
+ * const tl = timeline({ defaults: { duration: 500 } })
+ *   .to('.title', 'fade-up')
+ *   .label('cards')
+ *   .to('.card', 'scale', { stagger: 80, at: '-=200' })
+ *   .to('.cta', [{ opacity: 0 }, { opacity: 1 }], { at: 'cards+=400' });
+ * tl.play();             // or tl.scrub(document.querySelector('.hero'))
+ */
+declare function timeline(options?: TimelineOptions): Timeline;
+
+/**
+ * motionary - parallax() helper
+ *
+ * Moves elements at a different speed than the page while they cross the
+ * viewport. Built on the same scroll progress as `progressVar` (0 when the
+ * element's top enters at the bottom, 1 when its bottom leaves at the top):
+ * the progress is written to a CSS custom property (default `--sa-parallax`)
+ * and the offset is applied with the individual `translate` property, so it
+ * composes with entrance animations and other `transform`s.
+ */
+interface ParallaxHelperOptions {
+    /**
+     * Total distance the element shifts while it crosses the viewport, as a
+     * fraction of the viewport size (`0.2` = 20vh on the y axis). Positive values
+     * lag behind the scroll (background-like), negative values move ahead of it
+     * (foreground-like). (default: `0.2`)
+     */
+    speed?: number;
+    /** `'y'` (default) or `'x'` (horizontal drift, in `vw`) */
+    axis?: 'x' | 'y';
+    /** CSS custom property receiving the progress (default: `'--sa-parallax'`) */
+    progressVar?: string;
+    /** Scroll container (default: the viewport) */
+    root?: Element | null;
+    /**
+     * Under `prefers-reduced-motion: reduce` no offset is applied (the progress
+     * variable is still written). Set to `false` to move anyway. (default: `true`)
+     */
+    respectReducedMotion?: boolean;
+}
+/**
+ * Apply a scroll parallax to `target` (selector, Element, NodeList or array).
+ * Returns a function that stops it and removes the inline styles it set.
+ * SSR-safe (no-op without a DOM / IntersectionObserver).
+ *
+ * @example
+ * const stop = parallax('.hero-bg', { speed: 0.3 });
+ * parallax('.badge', { speed: -0.15, axis: 'x' });
+ */
+declare function parallax(target: string | Element | NodeList | Element[], options?: ParallaxHelperOptions): () => void;
+
+/**
+ * motionary - Animation Presets
+ * Defines keyframes for all built-in animation presets
+ */
+
+type KeyframeMap = PresetKeyframes;
+/**
+ * Every registered preset: the 33 core presets, plus the 6.1 extended set once
+ * `motionary/presets/extended` is loaded, plus your own.
+ */
+declare const PRESETS: Record<CorePreset, KeyframeMap> & Partial<Record<ExtendedPreset, KeyframeMap>>;
+/**
+ * Add (or replace) presets by name: `registerPresets({ 'my-pop': { from, to, frames? } })`.
+ * They work everywhere a preset name does (`animation`, `exit`, `data-sa-animation`,
+ * `<scroll-animate>`, `<usa-reveal effect>`).
+ */
+declare function registerPresets(presets: Record<string, PresetKeyframes>): void;
+/** The same keyframes played backwards (exit animations). */
+declare function reversePreset(p: KeyframeMap): KeyframeMap;
+declare function resolvePreset(animation: AnimationPreset | AnimationPreset[] | CustomAnimation): KeyframeMap;
+/** Easing to CSS cubic-bezier mapping */
+declare const EASING_MAP: Record<string, string>;
+declare function resolveEasing(easing: EasingType): string;
+
+/**
+ * Default singleton instance of ScrollAnimate.
+ * Ready to use out of the box with sensible defaults.
+ *
+ * @example
+ * ```js
+ * import ScrollAnimate from 'motionary';
+ *
+ * // Auto-initialize all elements with data-sa attribute
+ * ScrollAnimate.init();
+ *
+ * // Or manually observe elements
+ * ScrollAnimate.observe('.my-element', { animation: 'fade-in-up' });
+ * ```
+ */
+declare const ScrollAnimate: ScrollAnimateInstance;
+
+export { EASING_MAP, PRESETS, TIMELINE_PRESETS, createScrollAnimate, ScrollAnimate as default, getScrollProgress, parallax, registerPresets, resolveEasing, resolvePosition, resolvePreset, reversePreset, staggerChildren, supportsNativeScrub, supportsScrollTimeline, timeline };
+export type { AnimateOptions, AnimatedElement, AnimationFrame, AnimationKeyframe, AnimationPreset, CorePreset, CustomAnimation, EasingType, ExtendedPreset, ParallaxHelperOptions, PresetKeyframes, ProgressMode, ScrollAnimateConfig, ScrollAnimateInstance, ScrollEngine, ScrubHandle, ScrubOptions, StaggerOptions, Timeline, TimelineOptions, TimelinePosition, TimelineStepOptions };

package/dist/index.js

@@ -0,0 +1,131 @@
+import { b as resolveTargets, h as hasDOM, s as supportsObserver, g as getScrollProgress, d as prefersReducedMotion, c as createScrollAnimate } from './chunks/core-D7cVumUu.js';
+export { e as supportsScrollTimeline } from './chunks/core-D7cVumUu.js';
+export { s as staggerChildren } from './chunks/stagger-DtMKo2SK.js';
+export { T as TIMELINE_PRESETS, r as resolvePosition, s as supportsNativeScrub, t as timeline } from './chunks/core-VEBw36QK.js';
+export { E as EASING_MAP, P as PRESETS, c as registerPresets, a as resolveEasing, r as resolvePreset, b as reversePreset } from './chunks/presets-BYBVJVeP.js';
+import './chunks/base-C_3cAoRz.js';
+import './components/tokens.js';
+
+/**
+ * motionary - parallax() helper
+ *
+ * Moves elements at a different speed than the page while they cross the
+ * viewport. Built on the same scroll progress as `progressVar` (0 when the
+ * element's top enters at the bottom, 1 when its bottom leaves at the top):
+ * the progress is written to a CSS custom property (default `--sa-parallax`)
+ * and the offset is applied with the individual `translate` property, so it
+ * composes with entrance animations and other `transform`s.
+ */
+const PASSIVE = { passive: true };
+/**
+ * Apply a scroll parallax to `target` (selector, Element, NodeList or array).
+ * Returns a function that stops it and removes the inline styles it set.
+ * SSR-safe (no-op without a DOM / IntersectionObserver).
+ *
+ * @example
+ * const stop = parallax('.hero-bg', { speed: 0.3 });
+ * parallax('.badge', { speed: -0.15, axis: 'x' });
+ */
+function parallax(target, options = {}) {
+    const els = resolveTargets(target);
+    if (!els.length || !hasDOM() || !supportsObserver())
+        return () => undefined;
+    const { speed = 0.2, axis = 'y', root = null, respectReducedMotion = true } = options;
+    const name = options.progressVar ? (options.progressVar.startsWith('--') ? options.progressVar : `--${options.progressVar}`) : '--sa-parallax';
+    const unit = axis === 'x' ? 'vw' : 'vh';
+    const visible = new Set();
+    let frame = 0;
+    let listening = false;
+    const scroller = root || window;
+    const apply = (el) => {
+        const style = el.style;
+        if (!style)
+            return;
+        const p = getScrollProgress(el, root);
+        style.setProperty(name, String(+p.toFixed(4)));
+        if (respectReducedMotion && prefersReducedMotion()) {
+            style.removeProperty('translate');
+            return;
+        }
+        const offset = `${+((p - 0.5) * speed * 100).toFixed(3)}${unit}`;
+        style.setProperty('translate', axis === 'x' ? `${offset} 0px` : `0px ${offset}`);
+    };
+    const update = () => {
+        frame = 0;
+        visible.forEach(apply);
+    };
+    const schedule = () => {
+        if (!frame)
+            frame = requestAnimationFrame(update);
+    };
+    const listen = (on) => {
+        if (on === listening)
+            return;
+        listening = on;
+        const method = on ? 'addEventListener' : 'removeEventListener';
+        scroller[method]('scroll', schedule, PASSIVE);
+        window[method]('resize', schedule, PASSIVE);
+        if (!on && frame) {
+            cancelAnimationFrame(frame);
+            frame = 0;
+        }
+    };
+    const io = new IntersectionObserver((entries) => {
+        entries.forEach((entry) => {
+            if (entry.isIntersecting)
+                visible.add(entry.target);
+            else
+                visible.delete(entry.target);
+            apply(entry.target); // report the edges even on fast scrolls
+        });
+        listen(visible.size > 0);
+    }, { threshold: 0, root });
+    els.forEach((el) => {
+        apply(el); // no jump before the first observer callback
+        io.observe(el);
+    });
+    return () => {
+        io.disconnect();
+        listen(false);
+        visible.clear();
+        els.forEach((el) => {
+            const style = el.style;
+            if (!style)
+                return;
+            style.removeProperty('translate');
+            style.removeProperty(name);
+        });
+    };
+}
+
+/**
+ * motionary
+ *
+ * A lightweight, dependency-free scroll animation library for modern web
+ * applications. Built with TypeScript, powered by IntersectionObserver and
+ * the Web Animations API (or the native scroll-driven timeline). Safe to
+ * import during SSR. Framework integrations live in the subpath entries:
+ * `motionary/react`, `/vue`, `/svelte`, `/solid`, `/element`.
+ *
+ * @license MIT
+ * @see https://github.com/HarrisonCN/motionary
+ */
+/**
+ * Default singleton instance of ScrollAnimate.
+ * Ready to use out of the box with sensible defaults.
+ *
+ * @example
+ * ```js
+ * import ScrollAnimate from 'motionary';
+ *
+ * // Auto-initialize all elements with data-sa attribute
+ * ScrollAnimate.init();
+ *
+ * // Or manually observe elements
+ * ScrollAnimate.observe('.my-element', { animation: 'fade-in-up' });
+ * ```
+ */
+const ScrollAnimate = /* @__PURE__ */ createScrollAnimate();
+
+export { createScrollAnimate, ScrollAnimate as default, getScrollProgress, parallax };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/parallax.ts","../src/index.ts"],"sourcesContent":["/**\n * motionary - parallax() helper\n *\n * Moves elements at a different speed than the page while they cross the\n * viewport. Built on the same scroll progress as `progressVar` (0 when the\n * element's top enters at the bottom, 1 when its bottom leaves at the top):\n * the progress is written to a CSS custom property (default `--sa-parallax`)\n * and the offset is applied with the individual `translate` property, so it\n * composes with entrance animations and other `transform`s.\n */\n\nimport { getScrollProgress, hasDOM, prefersReducedMotion, resolveTargets, supportsObserver } from './core';\n\nexport interface ParallaxHelperOptions {\n  /**\n   * Total distance the element shifts while it crosses the viewport, as a\n   * fraction of the viewport size (`0.2` = 20vh on the y axis). Positive values\n   * lag behind the scroll (background-like), negative values move ahead of it\n   * (foreground-like). (default: `0.2`)\n   */\n  speed?: number;\n  /** `'y'` (default) or `'x'` (horizontal drift, in `vw`) */\n  axis?: 'x' | 'y';\n  /** CSS custom property receiving the progress (default: `'--sa-parallax'`) */\n  progressVar?: string;\n  /** Scroll container (default: the viewport) */\n  root?: Element | null;\n  /**\n   * Under `prefers-reduced-motion: reduce` no offset is applied (the progress\n   * variable is still written). Set to `false` to move anyway. (default: `true`)\n   */\n  respectReducedMotion?: boolean;\n}\n\nconst PASSIVE: AddEventListenerOptions = { passive: true };\n\n/**\n * Apply a scroll parallax to `target` (selector, Element, NodeList or array).\n * Returns a function that stops it and removes the inline styles it set.\n * SSR-safe (no-op without a DOM / IntersectionObserver).\n *\n * @example\n * const stop = parallax('.hero-bg', { speed: 0.3 });\n * parallax('.badge', { speed: -0.15, axis: 'x' });\n */\nexport function parallax(\n  target: string | Element | NodeList | Element[],\n  options: ParallaxHelperOptions = {}\n): () => void {\n  const els = resolveTargets(target);\n  if (!els.length || !hasDOM() || !supportsObserver()) return () => undefined;\n  const { speed = 0.2, axis = 'y', root = null, respectReducedMotion = true } = options;\n  const name = options.progressVar ? (options.progressVar.startsWith('--') ? options.progressVar : `--${options.progressVar}`) : '--sa-parallax';\n  const unit = axis === 'x' ? 'vw' : 'vh';\n  const visible = new Set<Element>();\n  let frame = 0;\n  let listening = false;\n  const scroller: EventTarget = root || window;\n\n  const apply = (el: Element) => {\n    const style = (el as HTMLElement).style;\n    if (!style) return;\n    const p = getScrollProgress(el, root);\n    style.setProperty(name, String(+p.toFixed(4)));\n    if (respectReducedMotion && prefersReducedMotion()) {\n      style.removeProperty('translate');\n      return;\n    }\n    const offset = `${+((p - 0.5) * speed * 100).toFixed(3)}${unit}`;\n    style.setProperty('translate', axis === 'x' ? `${offset} 0px` : `0px ${offset}`);\n  };\n\n  const update = () => {\n    frame = 0;\n    visible.forEach(apply);\n  };\n  const schedule = () => {\n    if (!frame) frame = requestAnimationFrame(update);\n  };\n  const listen = (on: boolean) => {\n    if (on === listening) return;\n    listening = on;\n    const method = on ? 'addEventListener' : 'removeEventListener';\n    scroller[method]('scroll', schedule, PASSIVE);\n    window[method]('resize', schedule, PASSIVE);\n    if (!on && frame) {\n      cancelAnimationFrame(frame);\n      frame = 0;\n    }\n  };\n\n  const io = new IntersectionObserver(\n    (entries) => {\n      entries.forEach((entry) => {\n        if (entry.isIntersecting) visible.add(entry.target);\n        else visible.delete(entry.target);\n        apply(entry.target); // report the edges even on fast scrolls\n      });\n      listen(visible.size > 0);\n    },\n    { threshold: 0, root }\n  );\n  els.forEach((el) => {\n    apply(el); // no jump before the first observer callback\n    io.observe(el);\n  });\n\n  return () => {\n    io.disconnect();\n    listen(false);\n    visible.clear();\n    els.forEach((el) => {\n      const style = (el as HTMLElement).style;\n      if (!style) return;\n      style.removeProperty('translate');\n      style.removeProperty(name);\n    });\n  };\n}\n","/**\n * motionary\n *\n * A lightweight, dependency-free scroll animation library for modern web\n * applications. Built with TypeScript, powered by IntersectionObserver and\n * the Web Animations API (or the native scroll-driven timeline). Safe to\n * import during SSR. Framework integrations live in the subpath entries:\n * `motionary/react`, `/vue`, `/svelte`, `/solid`, `/element`.\n *\n * @license MIT\n * @see https://github.com/HarrisonCN/motionary\n */\n\nexport { createScrollAnimate, getScrollProgress, supportsScrollTimeline } from './core';\nexport { staggerChildren } from './stagger';\nexport { timeline, resolvePosition, TIMELINE_PRESETS, supportsNativeScrub } from './components/timeline/core';\nexport { parallax } from './parallax';\nexport { PRESETS, registerPresets, reversePreset, resolvePreset, resolveEasing, EASING_MAP } from './presets';\nexport type {\n  AnimationPreset,\n  CorePreset,\n  ExtendedPreset,\n  PresetKeyframes,\n  AnimationFrame,\n  EasingType,\n  AnimationKeyframe,\n  CustomAnimation,\n  ProgressMode,\n  ScrollEngine,\n  AnimateOptions,\n  ScrollAnimateConfig,\n  AnimatedElement,\n  ScrollAnimateInstance,\n} from './types';\nexport type { StaggerOptions } from './stagger';\nexport type { ParallaxHelperOptions } from './parallax';\nexport type { Timeline, TimelineOptions, TimelineStepOptions, TimelinePosition, ScrubOptions, ScrubHandle } from './components/timeline/core';\n\n// Default export: a ready-to-use singleton instance\nimport { createScrollAnimate } from './core';\n\n/**\n * Default singleton instance of ScrollAnimate.\n * Ready to use out of the box with sensible defaults.\n *\n * @example\n * ```js\n * import ScrollAnimate from 'motionary';\n *\n * // Auto-initialize all elements with data-sa attribute\n * ScrollAnimate.init();\n *\n * // Or manually observe elements\n * ScrollAnimate.observe('.my-element', { animation: 'fade-in-up' });\n * ```\n */\nconst ScrollAnimate = /* @__PURE__ */ createScrollAnimate();\nexport default ScrollAnimate;\n"],"names":[],"mappings":"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"}