@nitesh-tyagi/vectorflow 1.0.0

package/src/player.js

@@ -0,0 +1,246 @@
+/**
+ * VectorFlow — Player
+ * Animation playback using anime.js, with cancel/interrupt support.
+ */
+
+import anime from 'animejs/lib/anime.es.js';
+import { readSnapshot, lerpColor, parseTransform, buildTransform, lerp } from './utils.js';
+
+/**
+ * Animate a single step: transition all live parts to target state.
+ * Returns a Promise that resolves when the animation completes.
+ *
+ * @param {Map<string, Element>} liveParts — partName → live element
+ * @param {Map<string, object>} targetSnapshots — partName → snapshot for target state
+ * @param {number} ms — animation duration
+ * @param {AbortSignal} signal — for cancellation
+ * @returns {Promise<void>}
+ */
+export function playStep(liveParts, targetSnapshots, ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException('Aborted', 'AbortError'));
+      return;
+    }
+
+    const animations = [];
+    let completedCount = 0;
+    const totalParts = liveParts.size;
+
+    if (totalParts === 0) {
+      resolve();
+      return;
+    }
+
+    for (const [partName, liveEl] of liveParts) {
+      const targetSnap = targetSnapshots.get(partName);
+      if (!targetSnap) continue;
+
+      // Read current snapshot from the live element
+      const currentSnap = readSnapshot(liveEl);
+
+      // Build anime.js animation targets
+      const animeConfig = {
+        targets: liveEl,
+        duration: ms,
+        easing: 'linear',
+        complete: () => {
+          completedCount++;
+          if (completedCount >= totalParts) {
+            resolve();
+          }
+        },
+      };
+
+      // Animate numeric attributes
+      for (const [attr, targetVal] of Object.entries(targetSnap.numericAttrs)) {
+        const currentVal = currentSnap.numericAttrs[attr] ?? targetVal;
+        if (currentVal !== targetVal) {
+          animeConfig[attr] = targetVal;
+        }
+      }
+
+      // Animate colors using update callback
+      const colorAnimations = [];
+      for (const [prop, targetColor] of Object.entries(targetSnap.colors)) {
+        const currentColor = currentSnap.colors[prop];
+        if (currentColor && currentColor !== targetColor) {
+          colorAnimations.push({ prop, from: currentColor, to: targetColor });
+        } else if (!currentColor && targetColor) {
+          // Set directly if no current
+          liveEl.style.setProperty(prop, targetColor);
+        }
+      }
+
+      // Animate transform
+      let transformAnim = null;
+      if (targetSnap.transform || currentSnap.transform) {
+        const fromT = parseTransform(currentSnap.transform);
+        const toT = parseTransform(targetSnap.transform);
+        if (JSON.stringify(fromT) !== JSON.stringify(toT)) {
+          transformAnim = { from: fromT, to: toT };
+        }
+      }
+
+      // If we have color or transform animations, use the update callback
+      if (colorAnimations.length > 0 || transformAnim) {
+        const progressObj = { t: 0 };
+        const colorTransformAnim = anime({
+          targets: progressObj,
+          t: 1,
+          duration: ms,
+          easing: 'linear',
+          update: () => {
+            const t = progressObj.t;
+            // Colors
+            for (const { prop, from, to } of colorAnimations) {
+              const interpolated = lerpColor(from, to, t);
+              liveEl.style.setProperty(prop, interpolated);
+            }
+            // Transform
+            if (transformAnim) {
+              const { from, to } = transformAnim;
+              const interpolated = {
+                translateX: lerp(from.translateX, to.translateX, t),
+                translateY: lerp(from.translateY, to.translateY, t),
+                scaleX: lerp(from.scaleX, to.scaleX, t),
+                scaleY: lerp(from.scaleY, to.scaleY, t),
+                rotate: lerp(from.rotate, to.rotate, t),
+              };
+              const transformStr = buildTransform(interpolated);
+              if (transformStr) {
+                liveEl.setAttribute('transform', transformStr);
+              } else {
+                liveEl.removeAttribute('transform');
+              }
+            }
+          },
+        });
+        animations.push(colorTransformAnim);
+      }
+
+      // Create the main numeric attributes animation
+      const hasNumericChanges = Object.keys(animeConfig).some(
+        k => !['targets', 'duration', 'easing', 'complete'].includes(k)
+      );
+
+      if (hasNumericChanges) {
+        const anim = anime(animeConfig);
+        animations.push(anim);
+      } else {
+        // If no numeric changes, still count this part as complete
+        animeConfig.complete();
+      }
+    }
+
+    // Handle abort
+    const onAbort = () => {
+      for (const anim of animations) {
+        anime.remove(anim.targets || anim);
+        if (anim.pause) anim.pause();
+      }
+      reject(new DOMException('Aborted', 'AbortError'));
+    };
+
+    if (signal) {
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+  });
+}
+
+/**
+ * Play a sequence of steps.
+ *
+ * @param {Array<{state: string, ms: number}>} steps
+ * @param {Map<string, Element>} liveParts
+ * @param {Map<string, Map<string, object>>} stateSnapshots — stateName → partName → snapshot
+ * @param {AbortSignal} signal
+ * @param {function(string)} onStateChange — callback when a step completes
+ * @returns {Promise<string>} — resolves with the final state
+ */
+export async function playSteps(steps, liveParts, stateSnapshots, signal, onStateChange) {
+  let lastState = null;
+
+  for (const step of steps) {
+    if (signal?.aborted) {
+      throw new DOMException('Aborted', 'AbortError');
+    }
+
+    const targetSnapshots = stateSnapshots.get(step.state);
+    if (!targetSnapshots) {
+      throw new Error(`VectorFlow: No snapshots for state "${step.state}"`);
+    }
+
+    await playStep(liveParts, targetSnapshots, step.ms, signal);
+    lastState = step.state;
+
+    if (onStateChange) {
+      onStateChange(step.state);
+    }
+  }
+
+  return lastState;
+}
+
+/**
+ * Run a full action (sequence or loop).
+ *
+ * @param {object} action — normalized action object
+ * @param {string} currentState
+ * @param {object} routes
+ * @param {number} jsonMs
+ * @param {Set<string>} validStates
+ * @param {Map<string, Element>} liveParts
+ * @param {Map<string, Map<string, object>>} stateSnapshots
+ * @param {AbortSignal} signal
+ * @param {function(string)} onStateChange
+ * @param {object} expandFns — { expandSequence, expandDirect } from engine
+ * @returns {Promise<string>} — final state
+ */
+export async function runAction(
+  action, currentState, routes, jsonMs, validStates,
+  liveParts, stateSnapshots, signal, onStateChange, expandFns
+) {
+  const { expandSequence, expandDirect } = expandFns;
+
+  if (action.type === 'loop') {
+    const count = action.count || 99999;
+    let current = currentState;
+
+    for (let i = 0; i < count; i++) {
+      if (signal?.aborted) {
+        throw new DOMException('Aborted', 'AbortError');
+      }
+
+      let result;
+      if (action.mode === 'direct') {
+        result = expandDirect(action.order, current, routes, action.ms, jsonMs, validStates);
+      } else {
+        result = expandSequence(action.order, current, routes, action.ms, jsonMs, validStates);
+      }
+
+      if (result.steps.length > 0) {
+        const finalState = await playSteps(
+          result.steps, liveParts, stateSnapshots, signal, onStateChange
+        );
+        current = finalState || current;
+      }
+    }
+
+    return current;
+  } else {
+    // sequence (default)
+    const result = expandSequence(
+      action.order, currentState, routes, action.ms, jsonMs, validStates
+    );
+
+    if (result.steps.length > 0) {
+      const finalState = await playSteps(
+        result.steps, liveParts, stateSnapshots, signal, onStateChange
+      );
+      return finalState || currentState;
+    }
+
+    return currentState;
+  }
+}

package/src/utils.js

@@ -0,0 +1,221 @@
+/**
+ * VectorFlow — Utility helpers
+ * Color parsing, attribute reading, interpolation helpers.
+ */
+
+/**
+ * Parse a hex color string to { r, g, b } (0-255).
+ * Supports #RGB, #RRGGBB.
+ */
+export function hexToRgb(hex) {
+  if (!hex || hex === 'none') return null;
+  hex = hex.trim().replace('#', '');
+  if (hex.length === 3) {
+    hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+  }
+  const num = parseInt(hex, 16);
+  if (isNaN(num)) return null;
+  return {
+    r: (num >> 16) & 255,
+    g: (num >> 8) & 255,
+    b: num & 255,
+  };
+}
+
+/**
+ * Convert { r, g, b } back to a hex string.
+ */
+export function rgbToHex({ r, g, b }) {
+  const toHex = (n) => Math.round(Math.max(0, Math.min(255, n)))
+    .toString(16)
+    .padStart(2, '0');
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+/**
+ * Linearly interpolate between two numbers.
+ */
+export function lerp(a, b, t) {
+  return a + (b - a) * t;
+}
+
+/**
+ * Linearly interpolate between two colors (hex strings).
+ * Returns a hex string.
+ */
+export function lerpColor(colorA, colorB, t) {
+  const a = hexToRgb(colorA);
+  const b = hexToRgb(colorB);
+  if (!a || !b) return colorB || colorA || '#000000';
+  return rgbToHex({
+    r: lerp(a.r, b.r, t),
+    g: lerp(a.g, b.g, t),
+    b: lerp(a.b, b.b, t),
+  });
+}
+
+/**
+ * Numeric SVG attributes we want to interpolate.
+ */
+export const NUMERIC_ATTRS = ['x', 'y', 'width', 'height', 'rx', 'ry', 'cx', 'cy', 'r', 'opacity'];
+
+/**
+ * Style properties that may contain colors.
+ */
+export const COLOR_PROPS = ['fill', 'stroke'];
+
+/**
+ * Read a numeric attribute from an SVG element.
+ * Falls back to computed style, then to defaultVal.
+ */
+export function readNumericAttr(el, attr, defaultVal = 0) {
+  // Try direct attribute first
+  const raw = el.getAttribute(attr);
+  if (raw !== null && raw !== '') {
+    const val = parseFloat(raw);
+    if (!isNaN(val)) return val;
+  }
+  return defaultVal;
+}
+
+/**
+ * Read a color property from an SVG element.
+ * Checks inline style first, then attribute, then computed style.
+ * Returns a hex color string or null.
+ */
+export function readColorProp(el, prop) {
+  // 1. Inline style
+  const styleVal = el.style.getPropertyValue(prop);
+  if (styleVal && styleVal !== 'none') {
+    return normalizeColor(styleVal);
+  }
+  // 2. Direct attribute
+  const attrVal = el.getAttribute(prop);
+  if (attrVal && attrVal !== 'none') {
+    return normalizeColor(attrVal);
+  }
+  // 3. Computed style
+  const computed = window.getComputedStyle(el).getPropertyValue(prop);
+  if (computed && computed !== 'none') {
+    return normalizeColor(computed);
+  }
+  return null;
+}
+
+/**
+ * Normalize a color value to hex. Handles:
+ * - hex: #fff, #ff0000
+ * - rgb(...): rgb(255, 0, 0)
+ */
+export function normalizeColor(val) {
+  if (!val || val === 'none') return null;
+  val = val.trim();
+
+  // Already hex
+  if (val.startsWith('#')) return val;
+
+  // rgb(r, g, b) or rgb(r,g,b)
+  const match = val.match(/^rgb\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)/i);
+  if (match) {
+    return rgbToHex({
+      r: parseInt(match[1], 10),
+      g: parseInt(match[2], 10),
+      b: parseInt(match[3], 10),
+    });
+  }
+
+  // Named colors — use a canvas trick
+  if (typeof document !== 'undefined') {
+    const ctx = document.createElement('canvas').getContext('2d');
+    ctx.fillStyle = val;
+    const resolved = ctx.fillStyle; // returns hex
+    if (resolved.startsWith('#')) return resolved;
+  }
+
+  return val;
+}
+
+/**
+ * Read all animatable snapshot from an SVG element.
+ * Returns { numericAttrs: {attr: value}, colors: {prop: hexString}, transform: string|null }
+ */
+export function readSnapshot(el) {
+  const snapshot = {
+    numericAttrs: {},
+    colors: {},
+    transform: null,
+  };
+
+  // Numeric attributes
+  for (const attr of NUMERIC_ATTRS) {
+    const raw = el.getAttribute(attr);
+    if (raw !== null && raw !== '') {
+      const val = parseFloat(raw);
+      if (!isNaN(val)) {
+        snapshot.numericAttrs[attr] = val;
+      }
+    }
+  }
+
+  // Colors
+  for (const prop of COLOR_PROPS) {
+    const color = readColorProp(el, prop);
+    if (color) {
+      snapshot.colors[prop] = color;
+    }
+  }
+
+  // Transform
+  const transform = el.getAttribute('transform');
+  if (transform) {
+    snapshot.transform = transform;
+  }
+
+  return snapshot;
+}
+
+/**
+ * Parse a simple SVG transform string into components.
+ * Only handles translate, scale, rotate as simple cases.
+ * Returns an object like { translateX, translateY, scaleX, scaleY, rotate }.
+ */
+export function parseTransform(transformStr) {
+  const result = { translateX: 0, translateY: 0, scaleX: 1, scaleY: 1, rotate: 0 };
+  if (!transformStr) return result;
+
+  const translateMatch = transformStr.match(/translate\(\s*([-\d.]+)\s*[,\s]\s*([-\d.]+)\s*\)/);
+  if (translateMatch) {
+    result.translateX = parseFloat(translateMatch[1]);
+    result.translateY = parseFloat(translateMatch[2]);
+  }
+
+  const scaleMatch = transformStr.match(/scale\(\s*([-\d.]+)(?:\s*[,\s]\s*([-\d.]+))?\s*\)/);
+  if (scaleMatch) {
+    result.scaleX = parseFloat(scaleMatch[1]);
+    result.scaleY = scaleMatch[2] !== undefined ? parseFloat(scaleMatch[2]) : result.scaleX;
+  }
+
+  const rotateMatch = transformStr.match(/rotate\(\s*([-\d.]+)/);
+  if (rotateMatch) {
+    result.rotate = parseFloat(rotateMatch[1]);
+  }
+
+  return result;
+}
+
+/**
+ * Build a transform string from parsed components.
+ */
+export function buildTransform({ translateX, translateY, scaleX, scaleY, rotate }) {
+  const parts = [];
+  if (translateX !== 0 || translateY !== 0) {
+    parts.push(`translate(${translateX},${translateY})`);
+  }
+  if (rotate !== 0) {
+    parts.push(`rotate(${rotate})`);
+  }
+  if (scaleX !== 1 || scaleY !== 1) {
+    parts.push(`scale(${scaleX},${scaleY})`);
+  }
+  return parts.length > 0 ? parts.join(' ') : null;
+}