@strategicprojects/rpic 0.7.0 → 0.8.0

package/index.js

@@ -63,7 +63,9 @@ function ensure() {
 }
 
 /**
- * Compile pic source into `{ svg, animations, diagnostics, warnings, objects }` (throws on a pic error).
+ * Compile pic source into `{ svg, animations, diagnostics, warnings, objects }`
+ * (throws on a pic error). A top-level `scroll: true` is present when the source
+ * used `animate scroll` — a hint to scrub the timeline on scroll (see `animate`).
  * @param {string} src
  * @param {{circuits?: boolean, texlabels?: boolean}} [opts]
  */
@@ -93,8 +95,8 @@ export function renderSvg(src, opts) {
  * Build a GSAP timeline from a drawing's animation manifest and play it on the
  * SVG inside `root`. Browser-only (needs the DOM and a GSAP instance).
  * @param {Element} root container holding the injected SVG
- * @param {Array<{id:string,effect:string,start:number,duration:number}>} animations
- * @param {*} gsap the GSAP instance
+ * @param {Array<{id:string,effect:string,start:number,duration:number,repeat?:number,yoyo?:boolean,ease?:string,path?:string,color?:string,out?:boolean,from?:string,morph?:string}>} animations
+ * @param {*} gsap the GSAP instance (register MotionPathPlugin for `move`, MorphSVGPlugin for `morph`)
  * @returns the GSAP timeline
  */
 export function animate(root, animations, gsap) {
@@ -106,25 +108,131 @@ export function animate(root, animations, gsap) {
     if (!el) continue;
     switch (a.effect) {
       case 'fade':
-        tl.from(el, { opacity: 0, duration: a.duration, ease: 'power1.out' }, a.start);
+        enterExit(tl, el, withOverrides({ opacity: 0, duration: a.duration, ease: 'power1.out' }, a), a);
         break;
       case 'pop':
-        tl.from(
+        enterExit(
+          tl,
           el,
-          { scale: 0, transformOrigin: '50% 50%', duration: a.duration, ease: 'back.out(1.7)' },
-          a.start
+          withOverrides({ scale: 0, transformOrigin: '50% 50%', duration: a.duration, ease: 'back.out(1.7)' }, a),
+          a
         );
         break;
+      case 'slide':
+        slideIn(tl, el, a);
+        break;
       case 'draw':
         drawOn(el, a, tl);
         break;
+      case 'move':
+        moveAlong(root, el, a, tl);
+        break;
+      case 'morph':
+        morphInto(root, el, a, tl);
+        break;
+      case 'highlight':
+        highlightWith(el, a, tl);
+        break;
       default:
-        tl.from(el, { opacity: 0, duration: a.duration }, a.start);
+        enterExit(tl, el, withOverrides({ opacity: 0, duration: a.duration }, a), a);
     }
   }
   return tl;
 }
 
+// Entrances tween FROM the hidden `vars` to the natural state; `out` reverses
+// it into an exit (TO the hidden state). Shared by fade/pop/slide.
+function enterExit(tl, el, vars, a) {
+  return a.out ? tl.to(el, vars, a.start) : tl.from(el, vars, a.start);
+}
+
+// The `slide` effect: enter (or, with `out`, leave) by translating from a
+// compass direction, offset by the element's own extent so it clears its slot.
+function slideIn(tl, el, a) {
+  let bb = { width: 0, height: 0 };
+  try {
+    bb = el.getBBox();
+  } catch {
+    /* not yet laid out */
+  }
+  const off = {
+    left: { x: -(bb.width * 1.5 || 40) },
+    right: { x: bb.width * 1.5 || 40 },
+    up: { y: -(bb.height * 1.5 || 40) },
+    down: { y: bb.height * 1.5 || 40 },
+  }[a.from || 'left'];
+  enterExit(tl, el, withOverrides({ ...off, opacity: 0, duration: a.duration, ease: 'power2.out' }, a), a);
+}
+
+// Fold the optional GSAP overrides (repeat/yoyo/ease) into a tween's vars.
+// `ease` replaces the effect's default easing; repeat/yoyo loop the tween.
+function withOverrides(vars, a) {
+  if (a.repeat) vars.repeat = a.repeat;
+  if (a.yoyo) vars.yoyo = true;
+  if (a.ease) vars.ease = a.ease;
+  return vars;
+}
+
+// The `highlight` effect: emphasise `el`. With a target colour, tween the
+// stroke of its geometry to that colour; without one, a colour-free scale
+// pulse. It's a one-directional `.to()` — pair with `repeat 1 yoyo` for a
+// flash-and-return, or `repeat -1 yoyo` for a continuous pulse.
+function highlightWith(el, a, tl) {
+  if (a.color) {
+    const shapes = el.querySelectorAll('path, polyline, line, rect, circle, ellipse, polygon');
+    tl.to(shapes, withOverrides({ stroke: a.color, duration: a.duration, ease: 'power1.inOut' }, a), a.start);
+  } else {
+    tl.to(
+      el,
+      withOverrides({ scale: 1.12, transformOrigin: '50% 50%', duration: a.duration, ease: 'power1.inOut' }, a),
+      a.start
+    );
+  }
+}
+
+// The `morph` effect: tween `el`'s outline into the shape of the object
+// `a.morph` references, via GSAP's MorphSVGPlugin. The consumer must have
+// registered it (`gsap.registerPlugin(MorphSVGPlugin)`); without it GSAP
+// no-ops the morphSVG and the shape stays put.
+function morphInto(root, el, a, tl) {
+  if (!a.morph) return;
+  const tsel =
+    typeof CSS !== 'undefined' && CSS.escape ? '#' + CSS.escape(a.morph) : `[id="${a.morph}"]`;
+  const target = root.querySelector(tsel);
+  const sel = 'path, polyline, line, rect, circle, ellipse, polygon';
+  const src = el.querySelector(sel);
+  const dst = target && target.querySelector(sel);
+  if (!src || !dst) return;
+  tl.to(src, withOverrides({ morphSVG: dst, duration: a.duration, ease: 'power1.inOut' }, a), a.start);
+}
+
+// The `move` effect: travel `el` along the geometry of the object `a.path`
+// references, via GSAP's MotionPathPlugin. The consumer must have registered
+// it (`gsap.registerPlugin(MotionPathPlugin)`); without it GSAP no-ops the
+// motionPath and the object simply stays put.
+function moveAlong(root, el, a, tl) {
+  if (!a.path) return;
+  const psel =
+    typeof CSS !== 'undefined' && CSS.escape ? '#' + CSS.escape(a.path) : `[id="${a.path}"]`;
+  const group = root.querySelector(psel);
+  const pathEl = group && group.querySelector('path, polyline, line, polygon');
+  if (!pathEl) return;
+  // `align` maps the path into the traveller's coordinate space; a `move`
+  // tween is a `.to()` (current position → along the path), not a `.from()`.
+  tl.to(
+    el,
+    withOverrides(
+      {
+        motionPath: { path: pathEl, align: pathEl, alignOrigin: [0.5, 0.5], autoRotate: false },
+        duration: a.duration,
+        ease: 'none',
+      },
+      a
+    ),
+    a.start
+  );
+}
+
 function drawOn(group, a, tl) {
   const els = group.querySelectorAll('path, polyline, line, rect, circle, ellipse, polygon');
   els.forEach((el) => {
@@ -146,14 +254,16 @@ function drawOn(group, a, tl) {
       len = 0;
     }
     if (len > 0) {
+      // `out` reverses the trace: the stroke retracts (dashoffset 0 → len).
+      const [begin, end] = a.out ? [0, len] : [len, 0];
       tl.fromTo(
         el,
-        { strokeDasharray: len, strokeDashoffset: len },
-        { strokeDashoffset: 0, duration: a.duration, ease: 'none' },
+        { strokeDasharray: len, strokeDashoffset: begin },
+        withOverrides({ strokeDashoffset: end, duration: a.duration, ease: 'none' }, a),
         a.start
       );
     } else {
-      tl.from(el, { opacity: 0, duration: a.duration }, a.start);
+      enterExit(tl, el, withOverrides({ opacity: 0, duration: a.duration }, a), a);
     }
   });
   const texts = group.querySelectorAll('text');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strategicprojects/rpic",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The pic graphics language compiled to SVG with animation manifests, via WebAssembly. Browser + Node.",
   "type": "module",
   "main": "./index.js",