spark-html-motion 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# spark-html-motion
+
+Declarative **enter / leave transitions** for
+[spark-html](https://github.com/wilkinnovo/spark) — the Spark way: no compiler,
+no virtual DOM, 0 dependencies (~0.5 KB). When an `<template if>` / `<template
+each>` block adds or removes an element, it animates in/out. A leaving element
+is held in the DOM until its exit animation finishes, then removed.
+
+## Install
+
+```sh
+npm install spark-html-motion
+```
+
+## Use
+
+Register once, **before `mount()`**, then opt elements in with a `transition`
+attribute:
+
+```js
+import { mount } from 'spark-html';
+import { motion } from 'spark-html-motion';
+
+motion();
+mount(document.body);
+```
+
+```html
+<template each="t in todos">
+  <li transition="slide">{t.text}</li>
+</template>
+
+<template if="open">
+  <div class="panel" transition="fade">…</div>
+</template>
+```
+
+- `transition="fade | slide | scale"` — or the directive form `transition:fade`.
+- `transition-duration="300"` — milliseconds (per element).
+- `transition-easing="ease-out"` — any CSS easing (per element).
+
+The **initial render is not animated** by default (only later enters/leaves) —
+pass `motion({ appear: true })` if you want the first paint to animate too.
+`prefers-reduced-motion: reduce` is honored automatically (no animation).
+
+## Options & defaults
+
+```js
+motion({
+  preset: 'fade',   // default preset for a bare `transition` attribute
+  duration: 200,    // ms
+  easing: 'ease',
+  appear: false,    // animate the initial mount?
+});
+```
+
+## Custom presets
+
+`presets` is a plain object of `{ in: Keyframe[], out: Keyframe[] }` (standard
+[Web Animations](https://developer.mozilla.org/docs/Web/API/Element/animate)
+keyframes) — add your own:
+
+```js
+import { presets, motion } from 'spark-html-motion';
+presets.zoom = {
+  in: [{ transform: 'scale(0)' }, { transform: 'scale(1)' }],
+  out: [{ transform: 'scale(1)' }, { transform: 'scale(0)' }],
+};
+motion();
+// <li transition="zoom">…</li>
+```
+
+## How it works
+
+Spark core exposes a tiny `lifecycle({ enter, leave })` seam; this package
+registers into it and drives the Web Animations API. Nothing animates unless you
+call `motion()`, and elements without a `transition` attribute are added/removed
+instantly — so the cost is strictly opt-in.
+
+## License
+
+MIT © Wilkin Novo

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "spark-html-motion",
+  "version": "0.1.0",
+  "description": "Declarative enter/leave transitions for spark-html — transition=\"fade|slide|scale\" on if/each blocks, Web Animations API, 0 deps, no compiler.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "homepage": "https://wilkinnovo.github.io/spark",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node test/motion.js"
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wilkinnovo/spark.git",
+    "directory": "packages/spark-html-motion"
+  },
+  "dependencies": {
+    "spark-html": "^0.21.6"
+  },
+  "keywords": [
+    "spark-html",
+    "motion",
+    "transition",
+    "animation",
+    "enter-leave"
+  ],
+  "license": "MIT"
+}

package/src/index.d.ts

@@ -0,0 +1,26 @@
+export interface MotionOptions {
+  /** Default preset when an element uses a bare `transition` attribute. Default: "fade". */
+  preset?: "fade" | "slide" | "scale" | (string & {});
+  /** Default duration in milliseconds. Default: 200. */
+  duration?: number;
+  /** Default easing. Default: "ease". */
+  easing?: string;
+  /** Animate the initial mount too (off by default — only later enters animate). */
+  appear?: boolean;
+}
+
+export interface Preset {
+  in: Keyframe[];
+  out: Keyframe[];
+}
+
+/** Built-in keyframe presets, keyed by name. Mutate to add your own. */
+export const presets: Record<string, Preset>;
+
+/**
+ * Register enter/leave transitions for Spark if/each blocks. Call once before
+ * `mount()`. Opt elements in with `transition="fade|slide|scale"` (or the
+ * directive form `transition:fade`).
+ */
+export function motion(options?: MotionOptions): void;
+export default motion;

package/src/index.js

@@ -0,0 +1,135 @@
+// spark-html-motion — declarative enter/leave transitions for Spark, the Spark
+// way: no compiler, no virtual DOM. It plugs into the core's lifecycle seam
+// (`lifecycle()` from spark-html) and animates nodes that if/each blocks add or
+// remove. Animation is the Web Animations API (0 deps); a leaving node is held
+// in the DOM until its exit animation finishes, then removed.
+//
+//   import { mount } from 'spark-html';
+//   import { motion } from 'spark-html-motion';
+//   motion();           // register once, before mount()
+//   mount(document.body);
+//
+//   <template each="t in todos">
+//     <li transition="slide">{t.text}</li>     <!-- or transition:fade -->
+//   </template>
+//
+// Opt in per element with `transition="fade|slide|scale"` (or the directive
+// form `transition:fade`). Tune with `transition-duration="300"` (ms) and
+// `transition-easing="ease-out"`. Honors prefers-reduced-motion.
+
+import { lifecycle } from 'spark-html';
+
+export const presets = {
+  fade: {
+    in: [{ opacity: 0 }, { opacity: 1 }],
+    out: [{ opacity: 1 }, { opacity: 0 }],
+  },
+  slide: {
+    in: [
+      { opacity: 0, transform: 'translateY(8px)' },
+      { opacity: 1, transform: 'translateY(0)' },
+    ],
+    out: [
+      { opacity: 1, transform: 'translateY(0)' },
+      { opacity: 0, transform: 'translateY(8px)' },
+    ],
+  },
+  scale: {
+    in: [
+      { opacity: 0, transform: 'scale(.96)' },
+      { opacity: 1, transform: 'scale(1)' },
+    ],
+    out: [
+      { opacity: 1, transform: 'scale(1)' },
+      { opacity: 0, transform: 'scale(.96)' },
+    ],
+  },
+};
+
+const prefersReduced = () =>
+  typeof matchMedia === 'function' &&
+  matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+// Resolve an element's transition config from its attributes, or null to skip.
+function configFor(node, defaults) {
+  if (!node || node.nodeType !== 1 || !node.getAttribute) return null;
+  let name = node.getAttribute('transition');
+  if (name == null && node.attributes) {
+    for (const a of node.attributes) {
+      if (a.name && a.name.indexOf('transition:') === 0) {
+        name = a.name.slice('transition:'.length);
+        break;
+      }
+    }
+  }
+  if (name == null) return null; // not opted in
+  name = (name && name.trim()) || defaults.preset;
+  const keyframes = presets[name] || presets[defaults.preset];
+  const dAttr = node.getAttribute('transition-duration');
+  const d = dAttr != null && dAttr !== '' ? Number(dAttr) : NaN;
+  const duration = Number.isFinite(d) && d >= 0 ? d : defaults.duration;
+  const easing = node.getAttribute('transition-easing') || defaults.easing;
+  return { keyframes, duration, easing };
+}
+
+export function motion(options = {}) {
+  const defaults = {
+    preset: options.preset || 'fade',
+    duration: options.duration != null ? options.duration : 200,
+    easing: options.easing || 'ease',
+  };
+
+  // Don't animate the initial mount unless asked — only later enters. The first
+  // render runs synchronously inside mount(); flip `ready` on a later frame.
+  let ready = !!options.appear;
+  if (!ready && typeof requestAnimationFrame === 'function') {
+    requestAnimationFrame(() =>
+      requestAnimationFrame(() => {
+        ready = true;
+      }),
+    );
+  }
+
+  const canAnimate = (node) =>
+    typeof node.animate === 'function' && !prefersReduced();
+
+  lifecycle({
+    enter(node) {
+      if (!ready) return;
+      const cfg = configFor(node, defaults);
+      if (!cfg || !canAnimate(node)) return;
+      node.animate(cfg.keyframes.in, {
+        duration: cfg.duration,
+        easing: cfg.easing,
+      });
+    },
+    leave(node, remove) {
+      const cfg = configFor(node, defaults);
+      if (!cfg || !canAnimate(node)) {
+        remove();
+        return;
+      }
+      const anim = node.animate(cfg.keyframes.out, {
+        duration: cfg.duration,
+        easing: cfg.easing,
+        fill: 'forwards', // hold the faded-out frame until we detach
+      });
+      let done = false;
+      const finish = () => {
+        if (done) return;
+        done = true;
+        remove();
+      };
+      if (anim && anim.finished && typeof anim.finished.then === 'function') {
+        anim.finished.then(finish, finish);
+      } else if (anim && typeof anim.addEventListener === 'function') {
+        anim.addEventListener('finish', finish);
+        anim.addEventListener('cancel', finish);
+      } else {
+        finish();
+      }
+    },
+  });
+}
+
+export default motion;