use-scroll-animate 4.9.0 → 5.1.0

package/dist/components/fx.cjs

@@ -0,0 +1,289 @@
+'use strict';
+
+var base = require('../chunks/base-B5i8qQPR.cjs');
+var core = require('../chunks/core-BDcszY4L.cjs');
+var fx = require('../chunks/fx-B8hk1Fby.cjs');
+require('./tokens.cjs');
+
+/**
+ * 5.0 — unified plugin-style effect registration. Every effect (built-in or
+ * yours) is a plain object registered once and played the same way:
+ * `playEffect(el, name)`, `bindEffect(el, name, { trigger })` or
+ * `<usa-fx effect="name" trigger="click">`. Effects get a context that
+ * already applies reduced motion, motion sensitivity, intensity and the
+ * animation budget.
+ */
+const EFFECT_KINDS = ['enter', 'exit', 'attention', 'click', 'hover', 'card', 'loop', 'page', 'background', 'text', 'cursor', 'scroll'];
+const EFFECT_TRIGGERS = ['click', 'hover', 'enter', 'load', 'loop', 'manual'];
+const registry = new Map();
+/** Register an effect (throws on a duplicate name unless `override`). Returns an unregister function. */
+function registerEffect(def, opts = {}) {
+    if (!/^[a-z][a-z0-9-]*$/.test(def.name))
+        throw new Error(`[use-scroll-animate] invalid effect name "${def.name}"`);
+    if (!EFFECT_KINDS.includes(def.kind))
+        throw new Error(`[use-scroll-animate] unknown effect kind "${def.kind}"`);
+    if (registry.has(def.name) && !opts.override)
+        throw new Error(`[use-scroll-animate] effect "${def.name}" is already registered`);
+    registry.set(def.name, def);
+    return () => {
+        if (registry.get(def.name) === def)
+            registry.delete(def.name);
+    };
+}
+/** Register several effects at once (already-registered names are skipped). */
+function registerEffects(defs) {
+    for (const d of defs)
+        if (!registry.has(d.name))
+            registerEffect(d);
+}
+const getEffect = (name) => registry.get(name);
+const hasEffect = (name) => registry.has(name);
+/** Registered effects (optionally of one kind), sorted by name. */
+function listEffects(kind) {
+    return Array.from(registry.values())
+        .filter((d) => !kind || d.kind === kind)
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+const SKIP_BY_DEFAULT = ['loop', 'background', 'cursor'];
+function context(event) {
+    const cleanups = [];
+    return {
+        reduced: base.prefersReducedMotion(),
+        sensitivity: base.getMotionSensitivity(),
+        event,
+        animate: base.animateWithMotion,
+        onCleanup: (fn) => cleanups.push(fn),
+        cleanups,
+    };
+}
+/**
+ * Play a registered effect once on `el`. Resolves when it finishes (or
+ * immediately for fire-and-forget effects). Unknown names reject.
+ */
+async function playEffect(el, name, options = {}, event) {
+    const def = registry.get(name);
+    if (!def)
+        throw new Error(`[use-scroll-animate] unknown effect "${name}" — registered: ${Array.from(registry.keys()).join(', ')}`);
+    const ctx = context(event);
+    if (ctx.reduced && (def.reduced ?? (SKIP_BY_DEFAULT.includes(def.kind) ? 'skip' : 'run')) === 'skip')
+        return;
+    const out = def.run(el, { ...(def.defaults || {}), ...options }, ctx);
+    if (out && typeof out.finished?.then === 'function')
+        await out.finished.catch(() => undefined);
+    else if (out && typeof out.then === 'function')
+        await out;
+}
+/**
+ * Bind an effect to a trigger on `el`: `click`, `hover` (pointerenter / focus),
+ * `enter` (scrolls into view; `once` by default), `load` (now), `loop`
+ * (starts now, cleanup stops it) or `manual` (nothing). Returns an unbind.
+ */
+function bindEffect(el, name, options = {}) {
+    const { trigger = 'click', once, ...opts } = options;
+    const def = registry.get(name);
+    if (!def)
+        throw new Error(`[use-scroll-animate] unknown effect "${name}"`);
+    const offs = [];
+    let current = null;
+    const fire = (e) => {
+        const ctx = context(e);
+        if (ctx.reduced && (def.reduced ?? (SKIP_BY_DEFAULT.includes(def.kind) ? 'skip' : 'run')) === 'skip')
+            return;
+        // A persistent effect (returns a cleanup) replaces its previous run instead of stacking.
+        current?.();
+        current = null;
+        const out = def.run(el, { ...(def.defaults || {}), ...opts }, ctx);
+        const stops = [...ctx.cleanups, ...(typeof out === 'function' ? [out] : [])];
+        if (stops.length)
+            current = () => stops.splice(0).forEach((f) => f());
+    };
+    offs.push(() => {
+        current?.();
+        current = null;
+    });
+    const on = (type, opt) => {
+        el.addEventListener(type, fire, opt);
+        offs.push(() => el.removeEventListener(type, fire, opt));
+    };
+    if (trigger === 'click')
+        on('click', { once: !!once });
+    else if (trigger === 'hover')
+        (on('pointerenter'), on('focusin'));
+    else if (trigger === 'load' || trigger === 'loop')
+        fire();
+    else if (trigger === 'enter' && typeof IntersectionObserver !== 'undefined') {
+        const io = new IntersectionObserver((entries) => {
+            for (const en of entries)
+                if (en.isIntersecting) {
+                    fire();
+                    if (once !== false)
+                        io.disconnect();
+                }
+        }, { threshold: 0.15 });
+        io.observe(el);
+        offs.push(() => io.disconnect());
+    }
+    return () => offs.splice(0).reverse().forEach((f) => f());
+}
+
+function defineFx(tag = 'usa-fx') {
+    return base.defineElement(tag, (Base) => class UsaFx extends Base {
+        static get observedAttributes() {
+            return ['effect', 'trigger', 'options'];
+        }
+        get target() {
+            return this.flag('self') ? this : (this.firstElementChild || this);
+        }
+        opts() {
+            try {
+                return JSON.parse(this.str('options', '{}')) || {};
+            }
+            catch {
+                return {};
+            }
+        }
+        play() {
+            return playEffect(this.target, this.str('effect', 'pop'), this.opts()).catch(() => undefined);
+        }
+        mount() {
+            if (!this.style.display)
+                this.style.display = 'inline-block';
+            const name = this.str('effect', 'pop');
+            const t = this.str('trigger', 'click');
+            try {
+                this.onCleanup(bindEffect(this.target, name, { ...this.opts(), trigger: EFFECT_TRIGGERS.includes(t) ? t : 'click', once: this.flag('once') }));
+                this.removeAttribute('data-unknown');
+            }
+            catch {
+                this.setAttribute('data-unknown', name); // not registered (yet)
+            }
+        }
+    });
+}
+
+/**
+ * 5.0 built-in effects, all registered through `registerEffect()`:
+ * every timeline preset as an `enter` effect, attention seekers, and the
+ * click effects (burst, confetti, shake, ripple).
+ */
+const enter = Object.entries(core.TIMELINE_PRESETS).map(([name, frames]) => ({
+    name,
+    kind: 'enter',
+    description: `Entrance: ${name} (same keyframes as the timeline preset).`,
+    defaults: { duration: 600, delay: 0, easing: 'cubic-bezier(0.22, 1, 0.36, 1)' },
+    run: (el, o, ctx) => ctx.animate(el, ctx.reduced ? [{ opacity: 0 }, { opacity: 1 }] : frames, { duration: o.duration, delay: o.delay, easing: o.easing, fill: 'backwards' }),
+}));
+const A = (name, description, frames, duration = 700, easing = 'ease-in-out') => ({
+    name,
+    kind: 'attention',
+    description,
+    defaults: { duration, iterations: 1 },
+    run: (el, o, ctx) => (ctx.reduced ? ctx.animate(el, [{ opacity: 1 }, { opacity: 0.6 }, { opacity: 1 }], { duration: 400 }) : ctx.animate(el, frames, { duration: o.duration, easing, iterations: o.iterations })),
+});
+const attention = [
+    A('pulse', 'Gentle scale pulse.', [{ transform: 'scale(1)' }, { transform: 'scale(1.08)' }, { transform: 'scale(1)' }], 600),
+    A('pop', 'Quick overshoot pop.', [{ transform: 'scale(1)' }, { transform: 'scale(1.18)', offset: 0.4 }, { transform: 'scale(0.96)', offset: 0.7 }, { transform: 'scale(1)' }], 450, 'cubic-bezier(0.34, 1.56, 0.64, 1)'),
+    A('jelly', 'Rubbery squash-and-stretch.', [{ transform: 'scale(1,1)' }, { transform: 'scale(1.25,0.75)', offset: 0.3 }, { transform: 'scale(0.75,1.25)', offset: 0.4 }, { transform: 'scale(1.15,0.85)', offset: 0.5 }, { transform: 'scale(0.95,1.05)', offset: 0.65 }, { transform: 'scale(1.05,0.95)', offset: 0.75 }, { transform: 'scale(1,1)' }], 900),
+    A('wiggle', 'Playful rotate wiggle.', [{ transform: 'rotate(0)' }, { transform: 'rotate(-8deg)', offset: 0.2 }, { transform: 'rotate(7deg)', offset: 0.4 }, { transform: 'rotate(-5deg)', offset: 0.6 }, { transform: 'rotate(3deg)', offset: 0.8 }, { transform: 'rotate(0)' }], 650),
+    A('heartbeat', 'Double-beat heart pulse.', [{ transform: 'scale(1)' }, { transform: 'scale(1.2)', offset: 0.14 }, { transform: 'scale(1)', offset: 0.28 }, { transform: 'scale(1.2)', offset: 0.42 }, { transform: 'scale(1)', offset: 0.7 }], 1100),
+    A('bounce', 'Hop up and settle with a squash.', [{ transform: 'translateY(0) scale(1,1)' }, { transform: 'translateY(-22px) scale(0.95,1.05)', offset: 0.35 }, { transform: 'translateY(0) scale(1.08,0.92)', offset: 0.6 }, { transform: 'translateY(-6px) scale(1,1)', offset: 0.8 }, { transform: 'translateY(0) scale(1,1)' }], 800),
+    A('flash', 'Two soft flashes (well under 3 per second).', [{ opacity: 1 }, { opacity: 0.25, offset: 0.25 }, { opacity: 1, offset: 0.5 }, { opacity: 0.25, offset: 0.75 }, { opacity: 1 }], 1400),
+    A('tada', 'Scale + shake celebration.', [{ transform: 'scale(1) rotate(0)' }, { transform: 'scale(0.9) rotate(-3deg)', offset: 0.1 }, { transform: 'scale(1.1) rotate(3deg)', offset: 0.3 }, { transform: 'scale(1.1) rotate(-3deg)', offset: 0.5 }, { transform: 'scale(1.1) rotate(3deg)', offset: 0.7 }, { transform: 'scale(1) rotate(0)' }], 1000),
+];
+const click = [
+    {
+        name: 'burst',
+        kind: 'click',
+        description: 'Particle burst from the click point (or the element center).',
+        defaults: { count: 12 },
+        run: (el, o, ctx) => {
+            if (ctx.reduced)
+                return;
+            const r = el.getBoundingClientRect();
+            const e = ctx.event;
+            fx.burst(e?.clientX ?? r.left + r.width / 2, e?.clientY ?? r.top + r.height / 2, o);
+        },
+    },
+    {
+        name: 'confetti',
+        kind: 'click',
+        description: 'Confetti cannon from the element.',
+        defaults: { count: 80 },
+        run: (el, o, ctx) => {
+            if (ctx.reduced)
+                return;
+            const r = el.getBoundingClientRect();
+            fx.confetti({ x: r.left + r.width / 2, y: r.top + r.height / 2, ...o });
+        },
+    },
+    {
+        name: 'shake',
+        kind: 'attention',
+        description: 'Horizontal "no" shake (errors, wrong password).',
+        defaults: { intensity: 8, duration: 480 },
+        run: (el, o, ctx) => (ctx.reduced ? ctx.animate(el, [{ opacity: 1 }, { opacity: 0.5 }, { opacity: 1 }], { duration: 300 }) : fx.shake(el, o.intensity, o.duration)),
+    },
+    {
+        name: 'ripple',
+        kind: 'click',
+        description: 'Material-style ink ripple from the pointer.',
+        defaults: { color: 'currentColor', duration: 600 },
+        run: (el, o, ctx) => {
+            var _a;
+            if (ctx.reduced)
+                return;
+            const r = el.getBoundingClientRect();
+            const e = ctx.event;
+            const d = Math.hypot(r.width, r.height) * 2;
+            const dot = document.createElement('span');
+            dot.setAttribute('aria-hidden', 'true');
+            Object.assign(dot.style, { position: 'absolute', left: `${(e?.clientX ?? r.left + r.width / 2) - r.left - d / 2}px`, top: `${(e?.clientY ?? r.top + r.height / 2) - r.top - d / 2}px`, width: `${d}px`, height: `${d}px`, borderRadius: '50%', background: o.color, opacity: '0.25', pointerEvents: 'none' });
+            if (getComputedStyle(el).position === 'static')
+                el.style.position = 'relative';
+            (_a = el.style).overflow || (_a.overflow = 'hidden');
+            el.appendChild(dot);
+            const a = ctx.animate(dot, [{ transform: 'scale(0)', opacity: 0.3 }, { transform: 'scale(1)', opacity: 0 }], { duration: o.duration, easing: 'ease-out' });
+            const done = () => dot.remove();
+            if (a)
+                a.finished.then(done, done);
+            else
+                done();
+            return a;
+        },
+    },
+];
+/** Every built-in 5.0 effect definition. */
+const BUILTIN_EFFECTS = [...enter, ...attention, ...click];
+
+/**
+ * use-scroll-animate/components/fx — unified plugin-style effects (5.0).
+ * `registerEffect({ name, kind, run })`, `playEffect(el, name)`,
+ * `bindEffect(el, name, { trigger })`, `<usa-fx effect trigger>`. Built-ins:
+ * every timeline preset (`enter`), `pulse` · `pop` · `jelly` · `wiggle` ·
+ * `heartbeat` · `bounce` · `flash` · `tada` · `shake` (attention),
+ * `burst` · `confetti` · `ripple` (click). More packs: `use-scroll-animate/components/effects`.
+ */
+/** Register the built-in effects (idempotent; `defineFxComponents()` calls it). */
+function registerBuiltinEffects() {
+    registerEffects(BUILTIN_EFFECTS);
+}
+/** Register every component of this category under its default tag (+ the built-in effects). */
+function defineFxComponents() {
+    registerBuiltinEffects();
+    defineFx();
+}
+
+exports.BUILTIN_EFFECTS = BUILTIN_EFFECTS;
+exports.EFFECT_KINDS = EFFECT_KINDS;
+exports.EFFECT_TRIGGERS = EFFECT_TRIGGERS;
+exports.bindEffect = bindEffect;
+exports.defineFx = defineFx;
+exports.defineFxComponents = defineFxComponents;
+exports.getEffect = getEffect;
+exports.hasEffect = hasEffect;
+exports.listEffects = listEffects;
+exports.playEffect = playEffect;
+exports.registerBuiltinEffects = registerBuiltinEffects;
+exports.registerEffect = registerEffect;
+exports.registerEffects = registerEffects;
+//# sourceMappingURL=fx.cjs.map

package/dist/components/fx.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx.cjs","sources":["../../src/components/fx/registry.ts","../../src/components/fx/fx-el.ts","../../src/components/fx/builtins.ts","../../src/components/fx/index.ts"],"sourcesContent":["/**\n * 5.0 — unified plugin-style effect registration. Every effect (built-in or\n * yours) is a plain object registered once and played the same way:\n * `playEffect(el, name)`, `bindEffect(el, name, { trigger })` or\n * `<usa-fx effect=\"name\" trigger=\"click\">`. Effects get a context that\n * already applies reduced motion, motion sensitivity, intensity and the\n * animation budget.\n */\nimport { animateWithMotion, prefersReducedMotion, getMotionSensitivity, type MotionSensitivity, type Cleanup } from '../base';\n\nexport const EFFECT_KINDS = ['enter', 'exit', 'attention', 'click', 'hover', 'card', 'loop', 'page', 'background', 'text', 'cursor', 'scroll'] as const;\nexport type EffectKind = (typeof EFFECT_KINDS)[number];\n\nexport const EFFECT_TRIGGERS = ['click', 'hover', 'enter', 'load', 'loop', 'manual'] as const;\nexport type EffectTrigger = (typeof EFFECT_TRIGGERS)[number];\n\nexport interface EffectContext {\n  /** Reduced motion applies (OS setting, `minimal` / `static` sensitivity). */\n  readonly reduced: boolean;\n  readonly sensitivity: MotionSensitivity;\n  /** The triggering event (pointer position for click effects), if any. */\n  readonly event?: Event;\n  /** `el.animate()` with the library's motion rules (may return `null`). */\n  animate(el: Element, keyframes: Keyframe[], options: KeyframeAnimationOptions): Animation | null;\n  /** Register teardown for long-running effects (loops, listeners). */\n  onCleanup(fn: Cleanup): void;\n}\n\nexport interface EffectDefinition<O extends Record<string, unknown> = Record<string, any>> {\n  /** Unique, kebab-case. */\n  name: string;\n  kind: EffectKind;\n  /** One line for docs and the gallery. */\n  description?: string;\n  /** Option defaults (merged under the caller's options). */\n  defaults?: Partial<O>;\n  /**\n   * Under reduced motion: `'skip'` (do nothing — default for loop, background\n   * and cursor effects) or `'run'` (run with `ctx.reduced === true`, the\n   * effect degrades itself — default for everything else).\n   */\n  reduced?: 'skip' | 'run';\n  /** Play the effect. Return an Animation / Promise to be awaited, or a cleanup. */\n  run(el: HTMLElement, options: O, ctx: EffectContext): void | Cleanup | Animation | null | Promise<unknown>;\n}\n\nconst registry = new Map<string, EffectDefinition>();\n\n/** Register an effect (throws on a duplicate name unless `override`). Returns an unregister function. */\nexport function registerEffect<O extends Record<string, unknown>>(def: EffectDefinition<O>, opts: { override?: boolean } = {}): () => void {\n  if (!/^[a-z][a-z0-9-]*$/.test(def.name)) throw new Error(`[use-scroll-animate] invalid effect name \"${def.name}\"`);\n  if (!EFFECT_KINDS.includes(def.kind)) throw new Error(`[use-scroll-animate] unknown effect kind \"${def.kind}\"`);\n  if (registry.has(def.name) && !opts.override) throw new Error(`[use-scroll-animate] effect \"${def.name}\" is already registered`);\n  registry.set(def.name, def as unknown as EffectDefinition);\n  return () => {\n    if (registry.get(def.name) === (def as unknown)) registry.delete(def.name);\n  };\n}\n\n/** Register several effects at once (already-registered names are skipped). */\nexport function registerEffects(defs: EffectDefinition<any>[]): void {\n  for (const d of defs) if (!registry.has(d.name)) registerEffect(d);\n}\n\nexport const getEffect = (name: string): EffectDefinition | undefined => registry.get(name);\nexport const hasEffect = (name: string): boolean => registry.has(name);\n/** Registered effects (optionally of one kind), sorted by name. */\nexport function listEffects(kind?: EffectKind): EffectDefinition[] {\n  return Array.from(registry.values())\n    .filter((d) => !kind || d.kind === kind)\n    .sort((a, b) => a.name.localeCompare(b.name));\n}\n\nconst SKIP_BY_DEFAULT: EffectKind[] = ['loop', 'background', 'cursor'];\n\nfunction context(event?: Event): EffectContext & { cleanups: Cleanup[] } {\n  const cleanups: Cleanup[] = [];\n  return {\n    reduced: prefersReducedMotion(),\n    sensitivity: getMotionSensitivity(),\n    event,\n    animate: animateWithMotion,\n    onCleanup: (fn) => cleanups.push(fn),\n    cleanups,\n  };\n}\n\n/**\n * Play a registered effect once on `el`. Resolves when it finishes (or\n * immediately for fire-and-forget effects). Unknown names reject.\n */\nexport async function playEffect(el: HTMLElement, name: string, options: Record<string, unknown> = {}, event?: Event): Promise<void> {\n  const def = registry.get(name);\n  if (!def) throw new Error(`[use-scroll-animate] unknown effect \"${name}\" — registered: ${Array.from(registry.keys()).join(', ')}`);\n  const ctx = context(event);\n  if (ctx.reduced && (def.reduced ?? (SKIP_BY_DEFAULT.includes(def.kind) ? 'skip' : 'run')) === 'skip') return;\n  const out = def.run(el, { ...(def.defaults || {}), ...options }, ctx);\n  if (out && typeof (out as Animation).finished?.then === 'function') await (out as Animation).finished.catch(() => undefined);\n  else if (out && typeof (out as Promise<unknown>).then === 'function') await out;\n}\n\n/**\n * Bind an effect to a trigger on `el`: `click`, `hover` (pointerenter / focus),\n * `enter` (scrolls into view; `once` by default), `load` (now), `loop`\n * (starts now, cleanup stops it) or `manual` (nothing). Returns an unbind.\n */\nexport function bindEffect(el: HTMLElement, name: string, options: Record<string, unknown> & { trigger?: EffectTrigger; once?: boolean } = {}): Cleanup {\n  const { trigger = 'click', once, ...opts } = options;\n  const def = registry.get(name);\n  if (!def) throw new Error(`[use-scroll-animate] unknown effect \"${name}\"`);\n  const offs: Cleanup[] = [];\n  let current: Cleanup | null = null;\n  const fire = (e?: Event) => {\n    const ctx = context(e);\n    if (ctx.reduced && (def.reduced ?? (SKIP_BY_DEFAULT.includes(def.kind) ? 'skip' : 'run')) === 'skip') return;\n    // A persistent effect (returns a cleanup) replaces its previous run instead of stacking.\n    current?.();\n    current = null;\n    const out = def.run(el, { ...(def.defaults || {}), ...opts }, ctx);\n    const stops = [...ctx.cleanups, ...(typeof out === 'function' ? [out as Cleanup] : [])];\n    if (stops.length) current = () => stops.splice(0).forEach((f) => f());\n  };\n  offs.push(() => {\n    current?.();\n    current = null;\n  });\n  const on = (type: string, opt?: AddEventListenerOptions) => {\n    el.addEventListener(type, fire, opt);\n    offs.push(() => el.removeEventListener(type, fire, opt));\n  };\n  if (trigger === 'click') on('click', { once: !!once });\n  else if (trigger === 'hover') (on('pointerenter'), on('focusin'));\n  else if (trigger === 'load' || trigger === 'loop') fire();\n  else if (trigger === 'enter' && typeof IntersectionObserver !== 'undefined') {\n    const io = new IntersectionObserver((entries) => {\n      for (const en of entries)\n        if (en.isIntersecting) {\n          fire();\n          if (once !== false) io.disconnect();\n        }\n    }, { threshold: 0.15 });\n    io.observe(el);\n    offs.push(() => io.disconnect());\n  }\n  return () => offs.splice(0).reverse().forEach((f) => f());\n}\n","import { defineElement, type UsaElement } from '../base';\nimport { bindEffect, playEffect, EFFECT_TRIGGERS, type EffectTrigger } from './registry';\n\n/**\n * `<usa-fx effect=\"pop\" trigger=\"click\">` — plays any registered effect\n * (`registerEffect()`) on its first element child (or itself with `self`).\n * `trigger`: `click` (default) · `hover` · `enter` · `load` · `loop` · `manual`;\n * `options` (JSON) is passed to the effect; `once`. Method `play()`.\n */\nexport interface UsaFxElement extends UsaElement {\n  readonly target: HTMLElement;\n  play(): Promise<void>;\n}\n\nexport function defineFx(tag = 'usa-fx'): CustomElementConstructor | undefined {\n  return defineElement(tag, (Base) =>\n    class UsaFx extends Base {\n      static get observedAttributes(): string[] {\n        return ['effect', 'trigger', 'options'];\n      }\n      get target(): HTMLElement {\n        return this.flag('self') ? this : ((this.firstElementChild as HTMLElement) || this);\n      }\n      private opts(): Record<string, unknown> {\n        try {\n          return JSON.parse(this.str('options', '{}')) || {};\n        } catch {\n          return {};\n        }\n      }\n      play(): Promise<void> {\n        return playEffect(this.target, this.str('effect', 'pop'), this.opts()).catch(() => undefined);\n      }\n      mount(): void {\n        if (!this.style.display) this.style.display = 'inline-block';\n        const name = this.str('effect', 'pop');\n        const t = this.str('trigger', 'click') as EffectTrigger;\n        try {\n          this.onCleanup(bindEffect(this.target, name, { ...this.opts(), trigger: EFFECT_TRIGGERS.includes(t) ? t : 'click', once: this.flag('once') }));\n          this.removeAttribute('data-unknown');\n        } catch {\n          this.setAttribute('data-unknown', name); // not registered (yet)\n        }\n      }\n    }\n  );\n}\n","/**\n * 5.0 built-in effects, all registered through `registerEffect()`:\n * every timeline preset as an `enter` effect, attention seekers, and the\n * click effects (burst, confetti, shake, ripple).\n */\nimport { TIMELINE_PRESETS } from '../timeline/core';\nimport { burst, confetti, shake } from '../click/fx';\nimport type { EffectDefinition } from './registry';\n\nconst enter: EffectDefinition[] = Object.entries(TIMELINE_PRESETS).map(([name, frames]) => ({\n  name,\n  kind: 'enter' as const,\n  description: `Entrance: ${name} (same keyframes as the timeline preset).`,\n  defaults: { duration: 600, delay: 0, easing: 'cubic-bezier(0.22, 1, 0.36, 1)' },\n  run: (el: HTMLElement, o: any, ctx) => ctx.animate(el, ctx.reduced ? [{ opacity: 0 }, { opacity: 1 }] : frames, { duration: o.duration, delay: o.delay, easing: o.easing, fill: 'backwards' }),\n}));\n\nconst A = (name: string, description: string, frames: Keyframe[], duration = 700, easing = 'ease-in-out'): EffectDefinition => ({\n  name,\n  kind: 'attention',\n  description,\n  defaults: { duration, iterations: 1 },\n  run: (el, o: any, ctx) => (ctx.reduced ? ctx.animate(el, [{ opacity: 1 }, { opacity: 0.6 }, { opacity: 1 }], { duration: 400 }) : ctx.animate(el, frames, { duration: o.duration, easing, iterations: o.iterations })),\n});\n\nconst attention: EffectDefinition[] = [\n  A('pulse', 'Gentle scale pulse.', [{ transform: 'scale(1)' }, { transform: 'scale(1.08)' }, { transform: 'scale(1)' }], 600),\n  A('pop', 'Quick overshoot pop.', [{ transform: 'scale(1)' }, { transform: 'scale(1.18)', offset: 0.4 }, { transform: 'scale(0.96)', offset: 0.7 }, { transform: 'scale(1)' }], 450, 'cubic-bezier(0.34, 1.56, 0.64, 1)'),\n  A('jelly', 'Rubbery squash-and-stretch.', [{ transform: 'scale(1,1)' }, { transform: 'scale(1.25,0.75)', offset: 0.3 }, { transform: 'scale(0.75,1.25)', offset: 0.4 }, { transform: 'scale(1.15,0.85)', offset: 0.5 }, { transform: 'scale(0.95,1.05)', offset: 0.65 }, { transform: 'scale(1.05,0.95)', offset: 0.75 }, { transform: 'scale(1,1)' }], 900),\n  A('wiggle', 'Playful rotate wiggle.', [{ transform: 'rotate(0)' }, { transform: 'rotate(-8deg)', offset: 0.2 }, { transform: 'rotate(7deg)', offset: 0.4 }, { transform: 'rotate(-5deg)', offset: 0.6 }, { transform: 'rotate(3deg)', offset: 0.8 }, { transform: 'rotate(0)' }], 650),\n  A('heartbeat', 'Double-beat heart pulse.', [{ transform: 'scale(1)' }, { transform: 'scale(1.2)', offset: 0.14 }, { transform: 'scale(1)', offset: 0.28 }, { transform: 'scale(1.2)', offset: 0.42 }, { transform: 'scale(1)', offset: 0.7 }], 1100),\n  A('bounce', 'Hop up and settle with a squash.', [{ transform: 'translateY(0) scale(1,1)' }, { transform: 'translateY(-22px) scale(0.95,1.05)', offset: 0.35 }, { transform: 'translateY(0) scale(1.08,0.92)', offset: 0.6 }, { transform: 'translateY(-6px) scale(1,1)', offset: 0.8 }, { transform: 'translateY(0) scale(1,1)' }], 800),\n  A('flash', 'Two soft flashes (well under 3 per second).', [{ opacity: 1 }, { opacity: 0.25, offset: 0.25 }, { opacity: 1, offset: 0.5 }, { opacity: 0.25, offset: 0.75 }, { opacity: 1 }], 1400),\n  A('tada', 'Scale + shake celebration.', [{ transform: 'scale(1) rotate(0)' }, { transform: 'scale(0.9) rotate(-3deg)', offset: 0.1 }, { transform: 'scale(1.1) rotate(3deg)', offset: 0.3 }, { transform: 'scale(1.1) rotate(-3deg)', offset: 0.5 }, { transform: 'scale(1.1) rotate(3deg)', offset: 0.7 }, { transform: 'scale(1) rotate(0)' }], 1000),\n];\n\nconst click: EffectDefinition[] = [\n  {\n    name: 'burst',\n    kind: 'click',\n    description: 'Particle burst from the click point (or the element center).',\n    defaults: { count: 12 },\n    run: (el, o: any, ctx) => {\n      if (ctx.reduced) return;\n      const r = el.getBoundingClientRect();\n      const e = ctx.event as PointerEvent | undefined;\n      burst(e?.clientX ?? r.left + r.width / 2, e?.clientY ?? r.top + r.height / 2, o);\n    },\n  },\n  {\n    name: 'confetti',\n    kind: 'click',\n    description: 'Confetti cannon from the element.',\n    defaults: { count: 80 },\n    run: (el, o: any, ctx) => {\n      if (ctx.reduced) return;\n      const r = el.getBoundingClientRect();\n      confetti({ x: r.left + r.width / 2, y: r.top + r.height / 2, ...o });\n    },\n  },\n  {\n    name: 'shake',\n    kind: 'attention',\n    description: 'Horizontal \"no\" shake (errors, wrong password).',\n    defaults: { intensity: 8, duration: 480 },\n    run: (el, o: any, ctx) => (ctx.reduced ? ctx.animate(el, [{ opacity: 1 }, { opacity: 0.5 }, { opacity: 1 }], { duration: 300 }) : shake(el, o.intensity, o.duration)),\n  },\n  {\n    name: 'ripple',\n    kind: 'click',\n    description: 'Material-style ink ripple from the pointer.',\n    defaults: { color: 'currentColor', duration: 600 },\n    run: (el, o: any, ctx) => {\n      if (ctx.reduced) return;\n      const r = el.getBoundingClientRect();\n      const e = ctx.event as PointerEvent | undefined;\n      const d = Math.hypot(r.width, r.height) * 2;\n      const dot = document.createElement('span');\n      dot.setAttribute('aria-hidden', 'true');\n      Object.assign(dot.style, { position: 'absolute', left: `${(e?.clientX ?? r.left + r.width / 2) - r.left - d / 2}px`, top: `${(e?.clientY ?? r.top + r.height / 2) - r.top - d / 2}px`, width: `${d}px`, height: `${d}px`, borderRadius: '50%', background: o.color, opacity: '0.25', pointerEvents: 'none' });\n      if (getComputedStyle(el).position === 'static') el.style.position = 'relative';\n      el.style.overflow ||= 'hidden';\n      el.appendChild(dot);\n      const a = ctx.animate(dot, [{ transform: 'scale(0)', opacity: 0.3 }, { transform: 'scale(1)', opacity: 0 }], { duration: o.duration, easing: 'ease-out' });\n      const done = () => dot.remove();\n      if (a) a.finished.then(done, done);\n      else done();\n      return a;\n    },\n  },\n];\n\n/** Every built-in 5.0 effect definition. */\nexport const BUILTIN_EFFECTS: EffectDefinition[] = [...enter, ...attention, ...click];\n","/**\n * use-scroll-animate/components/fx — unified plugin-style effects (5.0).\n * `registerEffect({ name, kind, run })`, `playEffect(el, name)`,\n * `bindEffect(el, name, { trigger })`, `<usa-fx effect trigger>`. Built-ins:\n * every timeline preset (`enter`), `pulse` · `pop` · `jelly` · `wiggle` ·\n * `heartbeat` · `bounce` · `flash` · `tada` · `shake` (attention),\n * `burst` · `confetti` · `ripple` (click). More packs: `use-scroll-animate/components/effects`.\n */\nimport { defineFx, type UsaFxElement } from './fx-el';\nimport { registerEffects } from './registry';\nimport { BUILTIN_EFFECTS } from './builtins';\n\nexport { defineFx };\nexport { registerEffect, registerEffects, playEffect, bindEffect, getEffect, hasEffect, listEffects, EFFECT_KINDS, EFFECT_TRIGGERS } from './registry';\nexport type { EffectDefinition, EffectContext, EffectKind, EffectTrigger } from './registry';\nexport { BUILTIN_EFFECTS };\nexport type { UsaFxElement };\n\n/** Register the built-in effects (idempotent; `defineFxComponents()` calls it). */\nexport function registerBuiltinEffects(): void {\n  registerEffects(BUILTIN_EFFECTS);\n}\n\n/** Register every component of this category under its default tag (+ the built-in effects). */\nexport function defineFxComponents(): void {\n  registerBuiltinEffects();\n  defineFx();\n}\n\ndeclare global {\n  interface HTMLElementTagNameMap {\n    'usa-fx': UsaFxElement;\n  }\n}\n"],"names":["prefersReducedMotion","getMotionSensitivity","animateWithMotion","defineElement","TIMELINE_PRESETS","burst","confetti","shake"],"mappings":"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"}

package/dist/components/fx.css

@@ -0,0 +1,3 @@
+/* use-scroll-animate/components/fx */
+.usa-sr{position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;border:0}
+

package/dist/components/fx.d.cts

@@ -0,0 +1,114 @@
+type MotionSensitivity = 'full' | 'gentle' | 'minimal' | 'static';
+type Cleanup = () => void;
+/**
+ * Members shared by every `<usa-*>` element. Attribute helpers, a cleanup
+ * bag that is emptied on disconnect, and motion helpers that degrade to the
+ * final state without WAAPI or under reduced motion.
+ */
+interface UsaElement extends HTMLElement {
+    /** `true` while reduced motion applies to this element. */
+    readonly reduced: boolean;
+}
+
+/**
+ * `<usa-fx effect="pop" trigger="click">` — plays any registered effect
+ * (`registerEffect()`) on its first element child (or itself with `self`).
+ * `trigger`: `click` (default) · `hover` · `enter` · `load` · `loop` · `manual`;
+ * `options` (JSON) is passed to the effect; `once`. Method `play()`.
+ */
+interface UsaFxElement extends UsaElement {
+    readonly target: HTMLElement;
+    play(): Promise<void>;
+}
+declare function defineFx(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * 5.0 — unified plugin-style effect registration. Every effect (built-in or
+ * yours) is a plain object registered once and played the same way:
+ * `playEffect(el, name)`, `bindEffect(el, name, { trigger })` or
+ * `<usa-fx effect="name" trigger="click">`. Effects get a context that
+ * already applies reduced motion, motion sensitivity, intensity and the
+ * animation budget.
+ */
+
+declare const EFFECT_KINDS: readonly ["enter", "exit", "attention", "click", "hover", "card", "loop", "page", "background", "text", "cursor", "scroll"];
+type EffectKind = (typeof EFFECT_KINDS)[number];
+declare const EFFECT_TRIGGERS: readonly ["click", "hover", "enter", "load", "loop", "manual"];
+type EffectTrigger = (typeof EFFECT_TRIGGERS)[number];
+interface EffectContext {
+    /** Reduced motion applies (OS setting, `minimal` / `static` sensitivity). */
+    readonly reduced: boolean;
+    readonly sensitivity: MotionSensitivity;
+    /** The triggering event (pointer position for click effects), if any. */
+    readonly event?: Event;
+    /** `el.animate()` with the library's motion rules (may return `null`). */
+    animate(el: Element, keyframes: Keyframe[], options: KeyframeAnimationOptions): Animation | null;
+    /** Register teardown for long-running effects (loops, listeners). */
+    onCleanup(fn: Cleanup): void;
+}
+interface EffectDefinition<O extends Record<string, unknown> = Record<string, any>> {
+    /** Unique, kebab-case. */
+    name: string;
+    kind: EffectKind;
+    /** One line for docs and the gallery. */
+    description?: string;
+    /** Option defaults (merged under the caller's options). */
+    defaults?: Partial<O>;
+    /**
+     * Under reduced motion: `'skip'` (do nothing — default for loop, background
+     * and cursor effects) or `'run'` (run with `ctx.reduced === true`, the
+     * effect degrades itself — default for everything else).
+     */
+    reduced?: 'skip' | 'run';
+    /** Play the effect. Return an Animation / Promise to be awaited, or a cleanup. */
+    run(el: HTMLElement, options: O, ctx: EffectContext): void | Cleanup | Animation | null | Promise<unknown>;
+}
+/** Register an effect (throws on a duplicate name unless `override`). Returns an unregister function. */
+declare function registerEffect<O extends Record<string, unknown>>(def: EffectDefinition<O>, opts?: {
+    override?: boolean;
+}): () => void;
+/** Register several effects at once (already-registered names are skipped). */
+declare function registerEffects(defs: EffectDefinition<any>[]): void;
+declare const getEffect: (name: string) => EffectDefinition | undefined;
+declare const hasEffect: (name: string) => boolean;
+/** Registered effects (optionally of one kind), sorted by name. */
+declare function listEffects(kind?: EffectKind): EffectDefinition[];
+/**
+ * Play a registered effect once on `el`. Resolves when it finishes (or
+ * immediately for fire-and-forget effects). Unknown names reject.
+ */
+declare function playEffect(el: HTMLElement, name: string, options?: Record<string, unknown>, event?: Event): Promise<void>;
+/**
+ * Bind an effect to a trigger on `el`: `click`, `hover` (pointerenter / focus),
+ * `enter` (scrolls into view; `once` by default), `load` (now), `loop`
+ * (starts now, cleanup stops it) or `manual` (nothing). Returns an unbind.
+ */
+declare function bindEffect(el: HTMLElement, name: string, options?: Record<string, unknown> & {
+    trigger?: EffectTrigger;
+    once?: boolean;
+}): Cleanup;
+
+/** Every built-in 5.0 effect definition. */
+declare const BUILTIN_EFFECTS: EffectDefinition[];
+
+/**
+ * use-scroll-animate/components/fx — unified plugin-style effects (5.0).
+ * `registerEffect({ name, kind, run })`, `playEffect(el, name)`,
+ * `bindEffect(el, name, { trigger })`, `<usa-fx effect trigger>`. Built-ins:
+ * every timeline preset (`enter`), `pulse` · `pop` · `jelly` · `wiggle` ·
+ * `heartbeat` · `bounce` · `flash` · `tada` · `shake` (attention),
+ * `burst` · `confetti` · `ripple` (click). More packs: `use-scroll-animate/components/effects`.
+ */
+
+/** Register the built-in effects (idempotent; `defineFxComponents()` calls it). */
+declare function registerBuiltinEffects(): void;
+/** Register every component of this category under its default tag (+ the built-in effects). */
+declare function defineFxComponents(): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'usa-fx': UsaFxElement;
+    }
+}
+
+export { BUILTIN_EFFECTS, EFFECT_KINDS, EFFECT_TRIGGERS, bindEffect, defineFx, defineFxComponents, getEffect, hasEffect, listEffects, playEffect, registerBuiltinEffects, registerEffect, registerEffects };
+export type { EffectContext, EffectDefinition, EffectKind, EffectTrigger, UsaFxElement };

package/dist/components/fx.d.ts

@@ -0,0 +1,114 @@
+type MotionSensitivity = 'full' | 'gentle' | 'minimal' | 'static';
+type Cleanup = () => void;
+/**
+ * Members shared by every `<usa-*>` element. Attribute helpers, a cleanup
+ * bag that is emptied on disconnect, and motion helpers that degrade to the
+ * final state without WAAPI or under reduced motion.
+ */
+interface UsaElement extends HTMLElement {
+    /** `true` while reduced motion applies to this element. */
+    readonly reduced: boolean;
+}
+
+/**
+ * `<usa-fx effect="pop" trigger="click">` — plays any registered effect
+ * (`registerEffect()`) on its first element child (or itself with `self`).
+ * `trigger`: `click` (default) · `hover` · `enter` · `load` · `loop` · `manual`;
+ * `options` (JSON) is passed to the effect; `once`. Method `play()`.
+ */
+interface UsaFxElement extends UsaElement {
+    readonly target: HTMLElement;
+    play(): Promise<void>;
+}
+declare function defineFx(tag?: string): CustomElementConstructor | undefined;
+
+/**
+ * 5.0 — unified plugin-style effect registration. Every effect (built-in or
+ * yours) is a plain object registered once and played the same way:
+ * `playEffect(el, name)`, `bindEffect(el, name, { trigger })` or
+ * `<usa-fx effect="name" trigger="click">`. Effects get a context that
+ * already applies reduced motion, motion sensitivity, intensity and the
+ * animation budget.
+ */
+
+declare const EFFECT_KINDS: readonly ["enter", "exit", "attention", "click", "hover", "card", "loop", "page", "background", "text", "cursor", "scroll"];
+type EffectKind = (typeof EFFECT_KINDS)[number];
+declare const EFFECT_TRIGGERS: readonly ["click", "hover", "enter", "load", "loop", "manual"];
+type EffectTrigger = (typeof EFFECT_TRIGGERS)[number];
+interface EffectContext {
+    /** Reduced motion applies (OS setting, `minimal` / `static` sensitivity). */
+    readonly reduced: boolean;
+    readonly sensitivity: MotionSensitivity;
+    /** The triggering event (pointer position for click effects), if any. */
+    readonly event?: Event;
+    /** `el.animate()` with the library's motion rules (may return `null`). */
+    animate(el: Element, keyframes: Keyframe[], options: KeyframeAnimationOptions): Animation | null;
+    /** Register teardown for long-running effects (loops, listeners). */
+    onCleanup(fn: Cleanup): void;
+}
+interface EffectDefinition<O extends Record<string, unknown> = Record<string, any>> {
+    /** Unique, kebab-case. */
+    name: string;
+    kind: EffectKind;
+    /** One line for docs and the gallery. */
+    description?: string;
+    /** Option defaults (merged under the caller's options). */
+    defaults?: Partial<O>;
+    /**
+     * Under reduced motion: `'skip'` (do nothing — default for loop, background
+     * and cursor effects) or `'run'` (run with `ctx.reduced === true`, the
+     * effect degrades itself — default for everything else).
+     */
+    reduced?: 'skip' | 'run';
+    /** Play the effect. Return an Animation / Promise to be awaited, or a cleanup. */
+    run(el: HTMLElement, options: O, ctx: EffectContext): void | Cleanup | Animation | null | Promise<unknown>;
+}
+/** Register an effect (throws on a duplicate name unless `override`). Returns an unregister function. */
+declare function registerEffect<O extends Record<string, unknown>>(def: EffectDefinition<O>, opts?: {
+    override?: boolean;
+}): () => void;
+/** Register several effects at once (already-registered names are skipped). */
+declare function registerEffects(defs: EffectDefinition<any>[]): void;
+declare const getEffect: (name: string) => EffectDefinition | undefined;
+declare const hasEffect: (name: string) => boolean;
+/** Registered effects (optionally of one kind), sorted by name. */
+declare function listEffects(kind?: EffectKind): EffectDefinition[];
+/**
+ * Play a registered effect once on `el`. Resolves when it finishes (or
+ * immediately for fire-and-forget effects). Unknown names reject.
+ */
+declare function playEffect(el: HTMLElement, name: string, options?: Record<string, unknown>, event?: Event): Promise<void>;
+/**
+ * Bind an effect to a trigger on `el`: `click`, `hover` (pointerenter / focus),
+ * `enter` (scrolls into view; `once` by default), `load` (now), `loop`
+ * (starts now, cleanup stops it) or `manual` (nothing). Returns an unbind.
+ */
+declare function bindEffect(el: HTMLElement, name: string, options?: Record<string, unknown> & {
+    trigger?: EffectTrigger;
+    once?: boolean;
+}): Cleanup;
+
+/** Every built-in 5.0 effect definition. */
+declare const BUILTIN_EFFECTS: EffectDefinition[];
+
+/**
+ * use-scroll-animate/components/fx — unified plugin-style effects (5.0).
+ * `registerEffect({ name, kind, run })`, `playEffect(el, name)`,
+ * `bindEffect(el, name, { trigger })`, `<usa-fx effect trigger>`. Built-ins:
+ * every timeline preset (`enter`), `pulse` · `pop` · `jelly` · `wiggle` ·
+ * `heartbeat` · `bounce` · `flash` · `tada` · `shake` (attention),
+ * `burst` · `confetti` · `ripple` (click). More packs: `use-scroll-animate/components/effects`.
+ */
+
+/** Register the built-in effects (idempotent; `defineFxComponents()` calls it). */
+declare function registerBuiltinEffects(): void;
+/** Register every component of this category under its default tag (+ the built-in effects). */
+declare function defineFxComponents(): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'usa-fx': UsaFxElement;
+    }
+}
+
+export { BUILTIN_EFFECTS, EFFECT_KINDS, EFFECT_TRIGGERS, bindEffect, defineFx, defineFxComponents, getEffect, hasEffect, listEffects, playEffect, registerBuiltinEffects, registerEffect, registerEffects };
+export type { EffectContext, EffectDefinition, EffectKind, EffectTrigger, UsaFxElement };