@strategicprojects/rpic 0.9.0 → 0.10.0

package/index.d.ts

@@ -2,7 +2,7 @@
 
 export interface Anim {
   id: string;
-  /** "fade" | "pop" | "draw" | "slide" | "move" | "highlight" | "morph" */
+  /** "fade" | "pop" | "draw" | "slide" | "move" | "highlight" | "morph" | "type" | "scramble" | "wiggle" */
   effect: string;
   /** absolute start time in seconds */
   start: number;
@@ -23,6 +23,16 @@ export interface Anim {
   from?: string;
   /** id of the shape a `morph` tweens into. Present only for `morph`. */
   morph?: string;
+  /** `type` reveal granularity: "word" splits by word, absent means by char. */
+  unit?: string;
+  /** custom scramble charset for `scramble` (`by "…"`). Present only when set. */
+  chars?: string;
+  /** oscillation count for `wiggle` (`wiggles <n>`). Present only when set. */
+  wiggles?: number;
+  /** `draw` reveal start as a stroke fraction (`from 40%` → 0.4). Present only when set. */
+  drawFrom?: number;
+  /** `draw` reveal end as a stroke fraction (`to 60%` → 0.6). Present only when set. */
+  drawTo?: number;
 }
 
 export interface Diagnostic {
@@ -59,9 +69,23 @@ export interface ObjectGeometry {
   file?: string;
 }
 
+export interface Interaction {
+  id: string;
+  /** currently always "drag" */
+  kind: string;
+  /** throw with momentum (needs InertiaPlugin). Present only when set. */
+  inertia?: boolean;
+  /** id of the shape whose box constrains dragging. Present only when set. */
+  bounds?: string;
+  /** axis lock: "x" | "y". Present only when set (absent = free drag). */
+  axis?: string;
+}
+
 export interface Bundle {
   svg: string;
   animations: Anim[];
+  /** `draggable` targets for the host to wire GSAP Draggable. Present only when non-empty. */
+  interactions?: Interaction[];
   /** lines emitted by pic `print` statements */
   diagnostics: string[];
   /** non-fatal compiler warnings for accepted but suspicious input */
@@ -126,3 +150,11 @@ export function renderSvg(src: string, opts?: CompileOptions): string;
  * `root`. Browser-only.
  */
 export function animate(root: Element, animations: Anim[], gsap: unknown): unknown;
+
+/**
+ * Make objects draggable from the `interactions` manifest (the `draggable`
+ * directive). Pass GSAP's `Draggable` class (register it — and `InertiaPlugin`
+ * if any interaction uses `inertia`). Returns the created Draggable instances.
+ * Browser-only.
+ */
+export function interactive(root: Element, interactions: Interaction[], Draggable: unknown): unknown[];

package/index.js

@@ -138,6 +138,15 @@ export function animate(root, animations, gsap) {
       case 'highlight':
         highlightWith(el, a, tl);
         break;
+      case 'type':
+        typeReveal(el, a, tl);
+        break;
+      case 'scramble':
+        scrambleReveal(el, a, tl);
+        break;
+      case 'wiggle':
+        wiggleShake(el, a, tl);
+        break;
       default:
         enterExit(tl, el, withOverrides({ opacity: 0, duration: a.duration }, a), a);
     }
@@ -145,6 +154,36 @@ export function animate(root, animations, gsap) {
   return tl;
 }
 
+/**
+ * Make objects draggable from the compile bundle's `interactions` array (the
+ * `draggable` directive). Pass GSAP's `Draggable` class (import it and
+ * `registerPlugin(Draggable)` — and `InertiaPlugin` if any interaction uses
+ * `inertia`). Returns the created Draggable instances.
+ * @param {Element} root
+ * @param {Array<{id:string,kind:string,inertia?:boolean,bounds?:string,axis?:string}>} interactions
+ * @param {*} Draggable
+ * @returns {Array}
+ */
+export function interactive(root, interactions, Draggable) {
+  if (!Draggable || !interactions || !interactions.length) return [];
+  const pick = (id) =>
+    root.querySelector(
+      typeof CSS !== 'undefined' && CSS.escape ? '#' + CSS.escape(id) : `[id="${id}"]`
+    );
+  const out = [];
+  for (const it of interactions) {
+    const el = pick(it.id);
+    if (!el) continue;
+    const vars = { type: it.axis || 'x,y', inertia: !!it.inertia };
+    if (it.bounds) {
+      const b = pick(it.bounds);
+      if (b) vars.bounds = b;
+    }
+    out.push(...Draggable.create(el, vars));
+  }
+  return out;
+}
+
 // 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) {
@@ -169,6 +208,49 @@ function slideIn(tl, el, a) {
   enterExit(tl, el, withOverrides({ ...off, opacity: 0, duration: a.duration, ease: 'power2.out' }, a), a);
 }
 
+// The `type` effect: reveal a label a glyph (or word) at a time — a
+// typewriter. The emitter split the label into `.rpic-ch` tspans; stagger
+// their opacity so the whole reveal spans the effect's duration (each unit
+// fades over one stagger step, the last finishing at `duration`). `out`
+// reverses it into a staggered fade-out.
+function typeReveal(el, a, tl) {
+  const units = el.querySelectorAll('.rpic-ch');
+  if (!units.length) return;
+  const step = a.duration / units.length;
+  const vars = withOverrides({ opacity: 0, duration: step, stagger: step, ease: 'none' }, a);
+  return a.out ? tl.to(units, vars, a.start) : tl.from(units, vars, a.start);
+}
+
+// The `scramble` effect: the label's glyphs cycle through random characters and
+// resolve to the real text — a decode reveal. Needs GSAP's ScrambleTextPlugin
+// registered. `{original}` tells the plugin to scramble the element's existing
+// text, so no capture is needed; `out` scrambles it away to nothing.
+function scrambleReveal(el, a, tl) {
+  const text = el.querySelector('text');
+  if (!text) return;
+  const chars = a.chars || 'upperCase';
+  const target = a.out ? '' : '{original}';
+  const vars = withOverrides(
+    { duration: a.duration, scrambleText: { text: target, chars, speed: 1 }, ease: 'none' },
+    a
+  );
+  return tl.to(text, vars, a.start);
+}
+
+// The `wiggle` effect: a quick oscillating shake that returns to rest, to draw
+// the eye to an object without moving it. Uses GSAP's CustomWiggle ease via its
+// string syntax `wiggle(n)` (register CustomWiggle first); the tween rotates
+// about the element's own centre and the ease settles it back to 0. An explicit
+// `ease` overrides the wiggle.
+function wiggleShake(el, a, tl) {
+  const n = a.wiggles || 6;
+  const vars = withOverrides(
+    { rotation: 8, transformOrigin: '50% 50%', duration: a.duration, ease: `wiggle(${n})` },
+    a
+  );
+  return tl.fromTo(el, { rotation: 0 }, vars, a.start);
+}
+
 // 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) {
@@ -317,12 +399,19 @@ function moveAlong(root, el, a, tl) {
 }
 
 function drawOn(group, a, tl) {
+  // `draw from 40% to 60%` reveals only a sub-segment; absent ends default to
+  // 0 and 1. A range switches the trace to a dash-window animation (no plugin).
+  const rangeStart = a.drawFrom != null ? a.drawFrom : 0;
+  const rangeEnd = a.drawTo != null ? a.drawTo : 1;
+  const hasRange = a.drawFrom != null || a.drawTo != null;
   const els = group.querySelectorAll('path, polyline, line, rect, circle, ellipse, polygon');
   els.forEach((el) => {
     // Filled, unstroked elements (arrowheads) can't be dash-traced — pop
-    // them in as the shaft reaches the tip instead.
+    // them in as the shaft reaches the tip instead. A partial draw that stops
+    // short of the end never reaches the tip, so leave the arrowhead hidden.
     const fill = el.getAttribute('fill');
     if (el.getAttribute('stroke-width') === '0' || (fill && fill !== 'none' && !el.getAttribute('stroke'))) {
+      if (hasRange && rangeEnd < 1) return;
       tl.from(
         el,
         { opacity: 0, scale: 0, transformOrigin: '50% 50%', duration: Math.min(0.2, a.duration * 0.4), ease: 'back.out(1.7)' },
@@ -336,7 +425,22 @@ function drawOn(group, a, tl) {
     } catch {
       len = 0;
     }
-    if (len > 0) {
+    if (len > 0 && hasRange) {
+      // Reveal only [p0,p1] of the stroke by growing a dash window: a leading
+      // gap of p0, then a dash that stretches from 0 to (p1-p0). `out` retracts
+      // it back to nothing. dasharray `[0, p0, w, len]` shows exactly [p0,p0+w].
+      const p0 = rangeStart * len;
+      const p1 = rangeEnd * len;
+      const [w0, w1] = a.out ? [p1 - p0, 0] : [0, p1 - p0];
+      const set = (w) => el.setAttribute('stroke-dasharray', `0 ${p0} ${Math.max(0, w)} ${len}`);
+      set(w0);
+      const proxy = { w: w0 };
+      tl.to(
+        proxy,
+        withOverrides({ w: w1, duration: a.duration, ease: 'none', onUpdate: () => set(proxy.w) }, a),
+        a.start
+      );
+    } else if (len > 0) {
       // `out` reverses the trace: the stroke retracts (dashoffset 0 → len).
       const [begin, end] = a.out ? [0, len] : [len, 0];
       tl.fromTo(

package/package.json

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