motionary 0.0.0-stage → 6.2.0

package/dist/components/fx-gpu.d.ts

@@ -0,0 +1,63 @@
+type MotionSensitivity = 'full' | 'gentle' | 'minimal' | 'static';
+type Cleanup = () => void;
+
+/**
+ * 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];
+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>;
+}
+
+/**
+ * 6.2 — GPU effect pack (`motionary/components/fx-gpu`), registered through
+ * `registerEffect()`:
+ *
+ * - WebGL2 shaders with a Canvas 2D fallback (kind `background`): `fluid`
+ *   (domain-warped fluid that swirls around the pointer), `smoke`, `fire`,
+ *   `ink` (ink blooming in water), `fireflies`.
+ * - Canvas 2D particles (kind `background`): `sakura` (falling cherry
+ *   petals), `leaves` (tumbling autumn leaves).
+ * - `splash` (kind `click`): droplets + a ring burst from the pointer.
+ *
+ * Every background renders only while visible, lowers its resolution when
+ * frames are slow, and draws one static frame under reduced motion.
+ */
+
+declare const GPU_FX: EffectDefinition[];
+/** Register the 6.2 GPU pack (idempotent). */
+declare function registerGpuEffects(): void;
+
+export { GPU_FX, registerGpuEffects };

package/dist/components/fx-gpu.js

@@ -0,0 +1,5 @@
+import '../chunks/registry-CKNLQpwd.js';
+import '../chunks/generative-D2YyhaeO.js';
+export { G as GPU_FX, r as registerGpuEffects } from '../chunks/gpu-Bu7qwugO.js';
+import '../chunks/base-C_3cAoRz.js';
+//# sourceMappingURL=fx-gpu.js.map

package/dist/components/fx-gpu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx-gpu.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}

package/dist/components/fx.cjs

@@ -0,0 +1,169 @@
+'use strict';
+
+var base = require('../chunks/base-BaQV-2ha.cjs');
+var registry = require('../chunks/registry-DehBVRDV.cjs');
+var core = require('../chunks/core-BGAyaY6L.cjs');
+var fx = require('../chunks/fx-lBGVtQO1.cjs');
+require('./tokens.cjs');
+
+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 registry.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(registry.bindEffect(this.target, name, { ...this.opts(), trigger: registry.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 `x` / `y`, 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(o.x ?? e?.clientX ?? r.left + r.width / 2, o.y ?? 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];
+
+/**
+ * motionary/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: `motionary/components/effects`.
+ */
+/** Register the built-in effects (idempotent; `defineFxComponents()` calls it). */
+function registerBuiltinEffects() {
+    registry.registerEffects(BUILTIN_EFFECTS);
+}
+/** Register every component of this category under its default tag (+ the built-in effects). */
+function defineFxComponents() {
+    registerBuiltinEffects();
+    defineFx();
+}
+
+exports.EFFECT_KINDS = registry.EFFECT_KINDS;
+exports.EFFECT_TRIGGERS = registry.EFFECT_TRIGGERS;
+exports.bindEffect = registry.bindEffect;
+exports.getEffect = registry.getEffect;
+exports.hasEffect = registry.hasEffect;
+exports.listEffects = registry.listEffects;
+exports.playEffect = registry.playEffect;
+exports.registerEffect = registry.registerEffect;
+exports.registerEffects = registry.registerEffects;
+exports.BUILTIN_EFFECTS = BUILTIN_EFFECTS;
+exports.defineFx = defineFx;
+exports.defineFxComponents = defineFxComponents;
+exports.registerBuiltinEffects = registerBuiltinEffects;
+//# sourceMappingURL=fx.cjs.map

package/dist/components/fx.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx.cjs","sources":["../../src/components/fx/fx-el.ts","../../src/components/fx/builtins.ts","../../src/components/fx/index.ts"],"sourcesContent":["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 `x` / `y`, 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(o.x ?? e?.clientX ?? r.left + r.width / 2, o.y ?? 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 * motionary/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: `motionary/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":["defineElement","playEffect","bindEffect","EFFECT_TRIGGERS","TIMELINE_PRESETS","burst","confetti","shake","registerEffects"],"mappings":"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"}

package/dist/components/fx.css

@@ -0,0 +1,3 @@
+/* motionary/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[];
+
+/**
+ * motionary/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: `motionary/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[];
+
+/**
+ * motionary/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: `motionary/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 };