npm - @duboseweb/motus - Versions diffs - 1.0.0 - Mend

@duboseweb/motus 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/CUSTOMIZATION.md +150 -0
package/LICENSE +21 -0
package/README.md +355 -0
package/dist/css/core.css +1 -0
package/dist/css/fade.css +1 -0
package/dist/css/flip.css +1 -0
package/dist/css/motus.css +1 -0
package/dist/css/slide.css +1 -0
package/dist/css/zoom.css +1 -0
package/dist/motus.cjs +800 -0
package/dist/motus.d.cts +102 -0
package/dist/motus.d.ts +102 -0
package/dist/motus.js +791 -0
package/dist/motus.umd.js +2 -0
package/package.json +115 -0
package/scss/animations/fade.scss +60 -0
package/scss/animations/flip.scss +42 -0
package/scss/animations/slide.scss +34 -0
package/scss/animations/zoom.scss +58 -0
package/scss/config.scss +3 -0
package/scss/core.scss +18 -0
package/scss/motus.scss +8 -0

package/dist/motus.js ADDED Viewed

@@ -0,0 +1,791 @@
+/*! dwg-motus | MIT License | https://github.com/dubose-web/dwg-motus */
+/**
+ * Every literal string the library writes to or reads from the DOM.
+ *
+ * Single source of truth so the attribute/class/event prefix can never end up
+ * half-renamed across modules.
+ */
+/** Attribute that marks an element for animation: `data-motus="fade-up"`. */
+const ATTR = 'data-motus';
+/** Attribute on `<html>` that disables the library in both CSS and JS. Set by the consumer. */
+const DISABLED_ATTR = 'data-motus-disabled';
+/**
+ * Attribute on `<html>` that the library sets on itself when it is not running
+ * — disabled by option, unsupported browser, or torn down.
+ *
+ * Deliberately separate from `DISABLED_ATTR`: the CSS hides `[data-motus]`
+ * elements until they animate, so something has to tell it to reveal them when
+ * no JS will ever arrive to do it. Reusing `DISABLED_ATTR` would be read back
+ * by `isDisabled()` on the next `init()` and wedge the library off for good.
+ */
+const INACTIVE_ATTR = 'data-motus-inactive';
+/** Builds a per-option attribute name, e.g. `attr('delay')` -> `data-motus-delay`. */
+const attr = (key) => `${ATTR}-${key}`;
+const CLASS_READY = 'motus-ready';
+const VAR_DURATION = '--motus-duration';
+const VAR_DELAY = '--motus-delay';
+const VAR_EASING = '--motus-easing';
+const EVENT_IN = 'motus:in';
+const EVENT_OUT = 'motus:out';
+/** Prefix for every console warning the library emits. */
+const LOG_PREFIX = '[dwg-motus]';
+/**
+ * Bootstrap 5's scale, so the tier names mean what they mean everywhere else.
+ * `xs` is implicit at 0 and is deliberately not a valid `disable` target —
+ * "disable below 0px" would never match.
+ */
+const BREAKPOINTS = Object.freeze({
+    sm: 576,
+    md: 768,
+    lg: 992,
+    xl: 1200,
+    xxl: 1400,
+});
+const BREAKPOINT_NAMES = ['sm', 'md', 'lg', 'xl', 'xxl'];
+/**
+ * Frozen so a stray `Object.assign(DEFAULTS, settings)` can never poison
+ * subsequent `init()` calls. Always merge into a fresh object.
+ */
+const DEFAULTS = Object.freeze({
+    offset: 120,
+    delay: 0,
+    easing: 'ease',
+    duration: 400,
+    disable: 'lg',
+    breakpoints: BREAKPOINTS,
+    once: false,
+    mirror: false,
+    anchorPlacement: 'top-bottom',
+    startEvent: 'DOMContentLoaded',
+    animatedClassName: 'motus-animate',
+    initClassName: 'motus-init',
+    useClassNames: false,
+    disableMutationObserver: false,
+    debounceDelay: 50,
+});
+const ANCHOR_PLACEMENTS = [
+    'top-bottom',
+    'top-center',
+    'top-top',
+    'center-bottom',
+    'center-center',
+    'center-top',
+    'bottom-bottom',
+    'bottom-center',
+    'bottom-top',
+];
+/** The legacy device-class keywords. Touch-based, exclusive, not configurable. */
+const DISABLE_KEYWORDS = ['phone', 'tablet', 'mobile'];
+const DEBOUNCE_MIN = 16;
+const DEBOUNCE_MAX = 500;
+/** Trailing-edge debounce. Inlined to keep the package dependency-free. */
+function debounce(fn, wait) {
+    let timeout;
+    return (...args) => {
+        clearTimeout(timeout);
+        timeout = setTimeout(() => fn(...args), wait);
+    };
+}
+/**
+ * Viewport and device detection via `matchMedia` — no user-agent sniffing.
+ *
+ * `below()` is the width-based path behind the `disable` tier names. The
+ * `phone` / `mobile` / `tablet` trio is the older device-class path:
+ * `pointer: coarse` plus `hover: none` is the standard signal for a touch
+ * device, and the width cut-off is what separates a phone from a tablet.
+ */
+const below = (width) =>
+/**
+ * `- 0.02` rather than `- 1`: a max-width derived from a min-width
+ * breakpoint must not leave a dead zone on fractional viewport widths,
+ * which a 991.5px window would otherwise land in.
+ */
+matchMedia(`(max-width: ${width - 0.02}px)`).matches;
+const phone = () => matchMedia('(pointer: coarse) and (hover: none) and (max-width: 767px)').matches;
+const mobile = () => matchMedia('(pointer: coarse) and (hover: none)').matches;
+const tablet = () => mobile() && !phone();
+/**
+ * The CSS-native keywords (`ease`, `linear`, `ease-in`, `ease-out`,
+ * `ease-in-out`) are deliberately absent — the fallthrough returns them
+ * unchanged, and that same fallthrough is what lets a raw `cubic-bezier(...)`
+ * value through untouched.
+ */
+const EASING_MAP = {
+    'ease-in-back': 'cubic-bezier(.6, -.28, .735, .045)',
+    'ease-out-back': 'cubic-bezier(.175, .885, .32, 1.275)',
+    'ease-in-out-back': 'cubic-bezier(.68, -.55, .265, 1.55)',
+    'ease-in-sine': 'cubic-bezier(.47, 0, .745, .715)',
+    'ease-out-sine': 'cubic-bezier(.39, .575, .565, 1)',
+    'ease-in-out-sine': 'cubic-bezier(.445, .05, .55, .95)',
+    'ease-in-quad': 'cubic-bezier(.55, .085, .68, .53)',
+    'ease-out-quad': 'cubic-bezier(.25, .46, .45, .94)',
+    'ease-in-out-quad': 'cubic-bezier(.455, .03, .515, .955)',
+    'ease-in-cubic': 'cubic-bezier(.55, .055, .675, .19)',
+    'ease-out-cubic': 'cubic-bezier(.215, .61, .355, 1)',
+    'ease-in-out-cubic': 'cubic-bezier(.645, .045, .355, 1)',
+    'ease-in-quart': 'cubic-bezier(.895, .03, .685, .22)',
+    'ease-out-quart': 'cubic-bezier(.165, .84, .44, 1)',
+    'ease-in-out-quart': 'cubic-bezier(.77, 0, .175, 1)',
+};
+const resolveEasing = (name) => { var _a; return (_a = EASING_MAP[name]) !== null && _a !== void 0 ? _a : name; };
+const addClasses = (node, classes) => {
+    for (const className of classes)
+        node.classList.add(className);
+};
+const removeClasses = (node, classes) => {
+    for (const className of classes)
+        node.classList.remove(className);
+};
+/**
+ * Dispatches on `document`. The `:<id>` variant fires *in addition to* the base
+ * event, never instead of it.
+ */
+const fireEvent = (eventName, node, id) => {
+    const detail = { node };
+    document.dispatchEvent(new CustomEvent(eventName, { detail }));
+    if (id) {
+        document.dispatchEvent(new CustomEvent(`${eventName}:${id}`, { detail }));
+    }
+};
+/** The three custom properties this library owns, global and per element alike. */
+const VARS = [VAR_DURATION, VAR_DELAY, VAR_EASING];
+const clearVars = (target) => {
+    if (!target)
+        return;
+    for (const name of VARS)
+        target.style.removeProperty(name);
+};
+/** Global duration/delay/easing, read by the core stylesheet. */
+const setGlobalVars = (options) => {
+    const { body } = document;
+    if (!body)
+        return;
+    body.style.setProperty(VAR_DURATION, `${options.duration}ms`);
+    body.style.setProperty(VAR_DELAY, `${options.delay}ms`);
+    body.style.setProperty(VAR_EASING, resolveEasing(options.easing));
+};
+// `document.body` is null before the parser reaches it; the element variant
+// always has a node.
+const clearGlobalVars = () => clearVars(document.body);
+const clearElementVars = (el) => clearVars(el);
+/**
+ * Per-element overrides. Only written when the attribute is actually present —
+ * note `"0"` is a truthy string, so `data-motus-duration="0"` correctly yields
+ * `--motus-duration: 0ms`.
+ */
+const setElementVars = (el, values) => {
+    if (values.duration)
+        el.style.setProperty(VAR_DURATION, `${values.duration}ms`);
+    if (values.delay)
+        el.style.setProperty(VAR_DELAY, `${values.delay}ms`);
+    if (values.easing)
+        el.style.setProperty(VAR_EASING, resolveEasing(values.easing));
+};
+/**
+ * True when the browser supports IntersectionObserver natively.
+ *
+ * Checks the constructor type rather than `'IntersectionObserver' in window`,
+ * because a stubbed-but-undefined global would otherwise pass the `in` test and
+ * then throw on construction.
+ */
+const isSupported = () => {
+    if (typeof window === 'undefined')
+        return false;
+    if (typeof window.IntersectionObserver !== 'function')
+        return false;
+    if (typeof window.IntersectionObserverEntry !== 'function')
+        return false;
+    return 'intersectionRatio' in window.IntersectionObserverEntry.prototype;
+};
+/**
+ * Per-node "has this already animated in" state, needed because every
+ * `rebuild()` — `refresh()`, a height-changing resize, a MutationObserver
+ * batch — throws the configs away and then calls `activate()`, which replays
+ * the observers' initial records. A config that starts at `false` re-fires
+ * `motus:in` for everything already on screen.
+ *
+ * The animated class on the element is the primary source, because that class
+ * is what the stylesheet keys on: if the remembered state and the DOM ever
+ * disagree, the DOM is the one that decides whether the user sees anything.
+ * This map is only the fallback for `animatedClassName: false`, where no
+ * marker is written and there is nothing to read back.
+ *
+ * Keyed by `node`, not `observeTarget`: several configs can share one
+ * `observeTarget` (`data-motus-anchor`), but `buildConfigs` emits exactly one
+ * config per element, so `node` is unique.
+ *
+ * A WeakMap cannot be cleared, so the reset rebinds a fresh one. That is why
+ * callers go through these functions rather than importing the map.
+ */
+let animated = new WeakMap();
+const setAnimated = (node, value) => {
+    animated.set(node, value);
+};
+/**
+ * Resolves the starting `animated` for a rebuilt config.
+ *
+ * Reads the class whenever there is one to read. A remembered `true` with the
+ * class gone — a framework re-render resetting `className`, a consumer
+ * stripping it — would otherwise leave the element hidden for good, since the
+ * CSS keeps every `[data-motus]` element invisible until it animates.
+ */
+const seedAnimated = (node, animatedClassName) => animatedClassName ? node.classList.contains(animatedClassName) : animated.get(node) === true;
+/** Called from `disable()`, which strips the animated class from every element. */
+const resetAnimatedState = () => {
+    animated = new WeakMap();
+};
+function getInlineOption(el, key, fallback) {
+    const value = el.getAttribute(attr(key));
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return value !== null && value !== void 0 ? value : fallback;
+}
+/**
+ * Reads an inline option that is only meaningful as a string. `getInlineOption`
+ * coerces `"true"`/`"false"` to booleans, which none of these callers want.
+ */
+const getInlineString = (node, key) => {
+    const value = getInlineOption(node, key);
+    return typeof value === 'string' ? value : undefined;
+};
+/**
+ * Resolves the anchor element for `data-motus-anchor`.
+ *
+ * An invalid CSS selector makes `querySelector` throw, which would otherwise
+ * take down the whole refresh; fall back to the node itself.
+ *
+ * `resolved` memoises the lookup for the duration of one `buildConfigs` pass,
+ * so a page where 50 elements share an anchor runs one query per rebuild
+ * rather than 50. It also means a bad selector warns once, not once per node.
+ */
+const resolveAnchor = (node, resolved) => {
+    var _a;
+    const selector = getInlineString(node, 'anchor');
+    if (!selector)
+        return node;
+    if (resolved.has(selector))
+        return (_a = resolved.get(selector)) !== null && _a !== void 0 ? _a : node;
+    let target = null;
+    try {
+        target = document.querySelector(selector);
+    }
+    catch (_b) {
+        console.warn(`${LOG_PREFIX} Invalid data-motus-anchor selector: ${selector}`);
+    }
+    resolved.set(selector, target);
+    return target !== null && target !== void 0 ? target : node;
+};
+/**
+ * Builds the resolved per-element settings, and performs the only DOM writes
+ * that happen at setup time: the init class and the per-element CSS variables.
+ */
+const buildConfigs = (elements, options) => {
+    const anchors = new Map();
+    // Shared, because with the default `useClassNames: false` every element ends
+    // up with the same list. An empty array is what makes
+    // `animatedClassName: false` skip the class entirely.
+    const baseClassNames = options.animatedClassName ? [options.animatedClassName] : [];
+    return elements.map((node) => {
+        var _a, _b;
+        const mirror = Boolean(getInlineOption(node, 'mirror', options.mirror));
+        const once = Boolean(getInlineOption(node, 'once', options.once));
+        const id = (_a = getInlineString(node, 'id')) !== null && _a !== void 0 ? _a : null;
+        const anchorPlacement = ((_b = getInlineString(node, 'anchor-placement')) !== null && _b !== void 0 ? _b : options.anchorPlacement);
+        // A non-numeric offset would otherwise poison the observer pool key
+        // (`"top-bottom-NaN"`) and every comparison in activate().
+        const rawOffset = Number(getInlineOption(node, 'offset', options.offset));
+        const offset = Number.isFinite(rawOffset) ? rawOffset : options.offset;
+        setElementVars(node, {
+            duration: getInlineString(node, 'duration'),
+            delay: getInlineString(node, 'delay'),
+            easing: getInlineString(node, 'easing'),
+        });
+        if (options.initClassName) {
+            node.classList.add(options.initClassName);
+        }
+        // `useClassNames` also applies the data-motus value itself, which is how
+        // the Animate.css integration works.
+        const custom = options.useClassNames ? node.getAttribute(ATTR) : null;
+        const animatedClassNames = custom
+            ? baseClassNames.concat(custom.split(' ').filter((name) => name !== ''))
+            : baseClassNames;
+        return {
+            node,
+            observeTarget: resolveAnchor(node, anchors),
+            mirror,
+            once,
+            id,
+            animatedClassNames,
+            // Seeded, not reset: rebuild() calls activate() as soon as the page is
+            // ready, which replays an "intersecting" record for everything on screen.
+            // A fresh `false` here makes that replay re-fire `motus:in`.
+            animated: seedAnimated(node, options.animatedClassName),
+            anchorPlacement,
+            offset,
+        };
+    });
+};
+/**
+ * Translates an anchor placement into an IntersectionObserver `rootMargin`.
+ *
+ * Pure and exported so the arithmetic can be unit-tested without a DOM.
+ */
+const getRootMargin = (anchorPlacement, offset, windowHeight = window.innerHeight) => {
+    switch (anchorPlacement) {
+        case 'top-center':
+        case 'center-center':
+        case 'bottom-center': {
+            // Clamped to at least 1px: a margin that collapses the root to zero
+            // height would never intersect anything.
+            const centerMargin = Math.max(Math.round(windowHeight / 2) - offset, 1);
+            return `${-centerMargin}px 0px ${-centerMargin}px 0px`;
+        }
+        case 'top-top':
+        case 'center-top':
+        case 'bottom-top': {
+            const topExpand = Math.max(offset, 1);
+            return `${topExpand}px 0px ${-(windowHeight - offset)}px 0px`;
+        }
+        case 'top-bottom':
+        case 'center-bottom':
+        case 'bottom-bottom':
+        default:
+            return `0px 0px ${-offset}px 0px`;
+    }
+};
+/**
+ * `center-*` placements wait until the element is half visible. The `bottom-*`
+ * placements stay at 0 because `rootMargin` already compensates for element
+ * height.
+ */
+const getThreshold = (anchorPlacement) => {
+    switch (anchorPlacement) {
+        case 'center-bottom':
+        case 'center-center':
+        case 'center-top':
+            return 0.5;
+        default:
+            return 0;
+    }
+};
+/**
+ * Creates the IntersectionObservers for a set of resolved configs.
+ *
+ * Observers are pooled by `anchorPlacement` + `offset`, because those two
+ * values are the only inputs to `rootMargin` and `threshold`. A page with 200
+ * elements sharing one configuration gets one observer, not 200.
+ */
+const createObserver = (configs,
+/**
+ * Passed in by `rebuild()`, which has already read it. Every pool would
+ * otherwise re-read `window.innerHeight` through `getRootMargin`'s default.
+ */
+windowHeight = window.innerHeight) => {
+    /**
+     * IntersectionObserver fires its first callback immediately on `observe()`,
+     * before the stylesheet's `motus-ready` gate is in place. Holding callbacks
+     * back until `activate()` is what stops above-the-fold elements from jumping
+     * straight to their final state with no visible transition.
+     */
+    let activated = false;
+    const pools = new Map();
+    const handleEntry = (entry, pool) => {
+        const targets = pool.targets.get(entry.target);
+        if (!targets)
+            return;
+        for (const config of targets) {
+            if (entry.isIntersecting) {
+                if (!config.animated) {
+                    addClasses(config.node, config.animatedClassNames);
+                    fireEvent(EVENT_IN, config.node, config.id);
+                    config.animated = true;
+                    setAnimated(config.node, true);
+                }
+            }
+            else if (config.animated && config.mirror && !config.once) {
+                removeClasses(config.node, config.animatedClassNames);
+                fireEvent(EVENT_OUT, config.node, config.id);
+                config.animated = false;
+                setAnimated(config.node, false);
+            }
+        }
+        // Only stop observing once *every* config on this target is finished —
+        // with a shared anchor, unobserving on the first one strands the rest.
+        if (targets.every((config) => config.once && config.animated)) {
+            pool.observer.unobserve(entry.target);
+        }
+    };
+    for (const config of configs) {
+        // A finished `once` config can only produce callbacks it would ignore.
+        // Skipping before pooling leaves the unobserve rule intact — the config
+        // simply never enters the target Map.
+        if (config.once && config.animated)
+            continue;
+        const key = `${config.anchorPlacement}-${config.offset}`;
+        let pool = pools.get(key);
+        if (!pool) {
+            const targets = new Map();
+            const observer = new IntersectionObserver((entries) => {
+                if (!activated) {
+                    pool.buffered.push(...entries);
+                    return;
+                }
+                for (const entry of entries)
+                    handleEntry(entry, pool);
+            }, {
+                rootMargin: getRootMargin(config.anchorPlacement, config.offset, windowHeight),
+                threshold: getThreshold(config.anchorPlacement),
+            });
+            pool = { observer, targets, buffered: [] };
+            pools.set(key, pool);
+        }
+        const existing = pool.targets.get(config.observeTarget);
+        if (existing) {
+            existing.push(config);
+        }
+        else {
+            pool.targets.set(config.observeTarget, [config]);
+            pool.observer.observe(config.observeTarget);
+        }
+    }
+    return {
+        disconnect: () => {
+            for (const pool of pools.values())
+                pool.observer.disconnect();
+            pools.clear();
+        },
+        /**
+         * Opens the gate and settles whatever the observers already know.
+         *
+         * Replays the entries that arrived while gated, plus any the browser has
+         * computed but not yet dispatched. That is what makes an element which was
+         * already on screen at init animate, without re-deriving the trigger
+         * geometry by hand: every decision here comes from the browser, using each
+         * pool's own rootMargin and threshold.
+         *
+         * Entries are processed oldest-first so the final state reflects the most
+         * recent observation.
+         */
+        activate: () => {
+            activated = true;
+            for (const pool of pools.values()) {
+                const entries = pool.buffered.concat(pool.observer.takeRecords());
+                pool.buffered.length = 0;
+                for (const entry of entries)
+                    handleEntry(entry, pool);
+            }
+        },
+    };
+};
+/**
+ * Iterates the live NodeList directly rather than spreading it into an array.
+ * This runs for every mutation record of every DOM change anywhere on the
+ * page, most of which have nothing to do with motus, so the allocation is not
+ * worth it.
+ */
+const containsMotusNode = (nodes) => {
+    for (const node of nodes) {
+        if (node.nodeType !== Node.ELEMENT_NODE)
+            continue;
+        const el = node;
+        if (el.hasAttribute(ATTR) || el.querySelector(`[${ATTR}]`))
+            return true;
+    }
+    return false;
+};
+/**
+ * Watches the document for dynamically added `[data-motus]` elements.
+ *
+ * Only `addedNodes` are considered. Reacting to removals causes a rebuild storm
+ * on SPA teardown for no benefit.
+ *
+ * Callbacks are batched into a single frame: framework hydration that appends
+ * 200 elements should rebuild the observers once, not 200 times.
+ */
+const watch = (callback) => {
+    let scheduled = false;
+    const observer = new MutationObserver((mutations) => {
+        if (scheduled)
+            return;
+        const hasNewElements = mutations.some((mutation) => containsMotusNode(mutation.addedNodes));
+        if (!hasNewElements)
+            return;
+        scheduled = true;
+        requestAnimationFrame(() => {
+            scheduled = false;
+            callback();
+        });
+    });
+    observer.observe(document.documentElement, { childList: true, subtree: true });
+    return observer;
+};
+/** Tier names first — they are the documented path; the device keywords are legacy. */
+const DISABLE_VALUES = [...BREAKPOINT_NAMES, ...DISABLE_KEYWORDS];
+const isNonNegativeNumber = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+/**
+ * Merges user settings over the defaults, clamps what needs clamping, and
+ * reports every problem in a single grouped warning so one typo does not
+ * produce a wall of console noise.
+ */
+const normalizeOptions = (settings = {}) => {
+    const problems = [];
+    for (const key of Object.keys(settings)) {
+        if (!(key in DEFAULTS)) {
+            problems.push(`Unknown option "${key}".`);
+        }
+    }
+    const options = Object.assign({}, DEFAULTS, settings);
+    for (const key of ['duration', 'delay', 'offset']) {
+        if (!isNonNegativeNumber(options[key])) {
+            problems.push(`"${key}" must be a non-negative number, received ${String(options[key])}. Using ${DEFAULTS[key]}.`);
+            options[key] = DEFAULTS[key];
+        }
+    }
+    if (!ANCHOR_PLACEMENTS.includes(options.anchorPlacement)) {
+        problems.push(`"anchorPlacement" must be one of ${ANCHOR_PLACEMENTS.join(', ')}. Using ${DEFAULTS.anchorPlacement}.`);
+        options.anchorPlacement = DEFAULTS.anchorPlacement;
+    }
+    if (typeof options.disable === 'string' && !DISABLE_VALUES.includes(options.disable)) {
+        problems.push(`"disable" must be a boolean, a function, or one of ${DISABLE_VALUES.join(', ')}. Using ${String(DEFAULTS.disable)}.`);
+        // Falls back to the default, not to `false` — a typo'd tier name must not
+        // silently re-enable animations on every viewport.
+        options.disable = DEFAULTS.disable;
+    }
+    /**
+     * `Object.assign` above copied the frozen default map by reference, so a
+     * partial override would otherwise drop the tiers it did not mention.
+     * Re-merge into a fresh object; `DEFAULTS.breakpoints` is never the target.
+     */
+    options.breakpoints = Object.assign({}, DEFAULTS.breakpoints, settings.breakpoints);
+    for (const name of BREAKPOINT_NAMES) {
+        const width = options.breakpoints[name];
+        if (typeof width !== 'number' || !Number.isFinite(width) || width <= 0) {
+            problems.push(`"breakpoints.${name}" must be a positive number, received ${String(width)}. Using ${DEFAULTS.breakpoints[name]}.`);
+            options.breakpoints[name] = DEFAULTS.breakpoints[name];
+        }
+    }
+    if (typeof options.startEvent !== 'string' || options.startEvent === '') {
+        problems.push(`"startEvent" must be a non-empty string. Using ${DEFAULTS.startEvent}.`);
+        options.startEvent = DEFAULTS.startEvent;
+    }
+    const requested = options.debounceDelay;
+    const clamped = Number.isFinite(requested)
+        ? Math.min(DEBOUNCE_MAX, Math.max(DEBOUNCE_MIN, requested))
+        : DEFAULTS.debounceDelay;
+    if (clamped !== requested) {
+        problems.push(`"debounceDelay" clamped from ${String(requested)} to ${clamped} (allowed range ${DEBOUNCE_MIN}–${DEBOUNCE_MAX}ms).`);
+    }
+    options.debounceDelay = clamped;
+    if (problems.length > 0) {
+        console.warn(`${LOG_PREFIX} Invalid options:\n  - ${problems.join('\n  - ')}`);
+    }
+    return options;
+};
+let elements = [];
+let observers = null;
+let mutationObs = null;
+let listeners = [];
+let initialized = false;
+let lastWindowHeight = null;
+let options = Object.assign({}, DEFAULTS);
+/** Every listener goes through here so `destroy()` can remove all of them. */
+const listen = (target, event, fn) => {
+    target.addEventListener(event, fn);
+    listeners.push({ target, event, fn });
+};
+const collectElements = () => [
+    ...document.querySelectorAll(`[${ATTR}]`),
+];
+/**
+ * Takes the whole options object rather than just `disable`, because a tier
+ * name is meaningless without the breakpoint map it indexes into.
+ */
+const isDisabled = (opts) => {
+    const { disable } = opts;
+    return (document.documentElement.hasAttribute(DISABLED_ATTR) ||
+        disable === true ||
+        // A tier name means *below* that tier, so `'lg'` covers everything narrower.
+        (typeof disable === 'string' &&
+            disable in opts.breakpoints &&
+            below(opts.breakpoints[disable])) ||
+        (disable === 'mobile' && mobile()) ||
+        (disable === 'phone' && phone()) ||
+        (disable === 'tablet' && tablet()) ||
+        (typeof disable === 'function' && disable() === true));
+};
+/**
+ * Rebuilds the observers from the current DOM.
+ *
+ * Unconditional by design — the width-only-resize optimisation lives in
+ * `handleResize()`, not here, so that dynamically added content is always
+ * picked up even though the viewport has not changed size.
+ */
+const rebuild = () => {
+    if (!initialized)
+        return;
+    lastWindowHeight = window.innerHeight;
+    elements = collectElements();
+    observers === null || observers === void 0 ? void 0 : observers.disconnect();
+    observers = createObserver(buildConfigs(elements, options), lastWindowHeight);
+    if (document.body.classList.contains(CLASS_READY)) {
+        // Already painted once — the new observers just need un-gating.
+        observers === null || observers === void 0 ? void 0 : observers.activate();
+        return;
+    }
+    /**
+     * Two frames, not one. The first frame must paint the elements in their
+     * initial hidden state; only then does `motus-ready` enable transitions and
+     * `activate()` add the animate class. Collapsing this makes every
+     * above-the-fold element snap to its final position with no animation.
+     */
+    requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+            document.body.classList.add(CLASS_READY);
+            observers === null || observers === void 0 ? void 0 : observers.activate();
+        });
+    });
+};
+/** First run: flips the initialised flag, then builds. */
+const start = () => {
+    initialized = true;
+    rebuild();
+};
+/**
+ * `rootMargin` is vertical-only, so a width-only resize needs no rebuild.
+ * Mobile browsers fire `resize` on every URL-bar show/hide, which would
+ * otherwise tear down and recreate every observer mid-scroll.
+ */
+const handleResize = () => {
+    if (!initialized)
+        return;
+    if (lastWindowHeight === window.innerHeight)
+        return;
+    rebuild();
+};
+const refresh = () => rebuild();
+const refreshHard = () => {
+    if (isDisabled(options)) {
+        disable();
+        return;
+    }
+    /**
+     * Coming back from disabled is not a rebuild. When `init()` bailed at the
+     * gate it returned before setting `initialized`, installing the mutation
+     * observer or binding any listener, so `rebuild()` would no-op here. Re-run
+     * `init()` with the options already in hand — they are normalised, so the
+     * second pass revalidates cleanly and warns about nothing.
+     */
+    if (!initialized) {
+        init(options);
+        return;
+    }
+    document.documentElement.removeAttribute(INACTIVE_ATTR);
+    rebuild();
+};
+/**
+ * Tears down observers and removes the classes and custom properties this
+ * library added. Deliberately leaves `data-motus*` attributes alone so the
+ * markup survives and `init()` works again afterwards.
+ */
+const disable = () => {
+    var _a;
+    // The CSS hides every [data-motus] element until it animates. With the
+    // library off, nothing will ever add that class, so this attribute is what
+    // stops the page from rendering blank.
+    document.documentElement.setAttribute(INACTIVE_ATTR, '');
+    mutationObs === null || mutationObs === void 0 ? void 0 : mutationObs.disconnect();
+    mutationObs = null;
+    observers === null || observers === void 0 ? void 0 : observers.disconnect();
+    observers = null;
+    (_a = document.body) === null || _a === void 0 ? void 0 : _a.classList.remove(CLASS_READY);
+    for (const el of elements) {
+        clearElementVars(el);
+        if (options.initClassName)
+            el.classList.remove(options.initClassName);
+        if (options.animatedClassName)
+            el.classList.remove(options.animatedClassName);
+    }
+    // The classes are gone, so the remembered state is now a lie. Reset here
+    // rather than in destroy() so the disable -> refreshHard() round trip
+    // re-animates. destroy() calls disable() first, so it inherits this.
+    resetAnimatedState();
+};
+/**
+ * Full teardown. Note `options` is intentionally left in place — `disable()`
+ * needs the last-used class names to remove them.
+ */
+const destroy = () => {
+    disable();
+    for (const { target, event, fn } of listeners) {
+        target.removeEventListener(event, fn);
+    }
+    listeners = [];
+    clearGlobalVars();
+    elements = [];
+    initialized = false;
+    lastWindowHeight = null;
+};
+const init = (settings) => {
+    // Repeated init() is common in SPA route handlers; without this, every call
+    // leaks another set of listeners and observers.
+    if (initialized)
+        destroy();
+    options = normalizeOptions(settings);
+    // Cleared before the gate below can set it again, so re-initialising with
+    // different options is not permanently poisoned by the last run.
+    document.documentElement.removeAttribute(INACTIVE_ATTR);
+    if (!isSupported()) {
+        console.warn(`${LOG_PREFIX} IntersectionObserver is not supported in this browser; animations are disabled.`);
+        document.documentElement.setAttribute(INACTIVE_ATTR, '');
+        return undefined;
+    }
+    elements = collectElements();
+    // Checked before the MutationObserver is installed: on a disabled page there
+    // is no reason for every DOM mutation to run the disable path again.
+    if (isDisabled(options)) {
+        disable();
+        return undefined;
+    }
+    if (!options.disableMutationObserver) {
+        mutationObs = watch(refreshHard);
+    }
+    setGlobalVars(options);
+    if (options.startEvent === 'DOMContentLoaded' || options.startEvent === 'load') {
+        listen(window, 'load', () => {
+            // Guarded so the first run does not happen twice when DOMContentLoaded
+            // already fired.
+            if (!initialized)
+                start();
+        });
+    }
+    else {
+        listen(document, options.startEvent, () => start());
+    }
+    if (options.startEvent === 'DOMContentLoaded' &&
+        (document.readyState === 'complete' || document.readyState === 'interactive')) {
+        start();
+    }
+    listen(window, 'resize', debounce(handleResize, options.debounceDelay));
+    return elements;
+};
+/** Frozen so consuming code cannot monkey-patch the API. */
+const Motus = Object.freeze({ init, refresh, refreshHard, destroy });
+export { DEFAULTS, Motus as default, destroy, init, refresh, refreshHard };