@birdapi/velinstyle 1.2.2 → 1.3.0

package/core/motion/index.js

@@ -2,24 +2,62 @@ import { observeInView, disconnectInViewObserver } from './scheduler.js';
 import { applyEffects, markVisible, prefersReducedMotion, VISIBLE_CLASS } from './effects.js';
 import { enhanceStagger } from './stagger.js';
 import { bindSmoothScroll } from './scroll.js';
+import { armMotionElement, readTrigger } from './triggers.js';
+import { applyMotionVars, resolvePolicy, shouldDisableMotion } from './policy.js';
+import { enhanceTimelines } from './timeline.js';
+import { enhanceSequences, Motion } from './composer.js';
+import {
+  loadMotionRegistry,
+  listPresets,
+  listPolicies,
+  catalogSummary,
+  getPreset,
+  resolvePresetId,
+} from './registry.js';
 
-const MOTION_ATTRS = ['velin-reveal', 'velin-fade', 'velin-slide', 'velin-scale', 'velin-parallax', 'velin-hover'];
+const LEGACY_ATTRS = ['velin-reveal', 'velin-fade', 'velin-slide', 'velin-scale', 'velin-parallax', 'velin-hover'];
 
 let teardownFns = [];
 
 /**
- * Initialize motion system: in-view reveals, stagger, smooth scroll anchors.
+ * Create a motion engine bound to an optional policy.
+ * @param {{ policy?: string }} [options]
+ */
+export function createMotionEngine(options = {}) {
+  const policy = resolvePolicy(options.policy || 'safe');
+  return {
+    policy,
+    registry: () => loadMotionRegistry(),
+    catalog: catalogSummary,
+    listPresets,
+    listPolicies,
+    init: (opts = {}) => initMotion({ ...opts, policy: policy.id }),
+    Motion,
+  };
+}
+
+/**
+ * Initialize motion system: unified velin-motion + triggers + legacy attrs.
  * @param {object} [options]
  * @param {HTMLElement|Document} [options.root]
  * @param {string} [options.selector]
+ * @param {string} [options.policy]
  */
 export function initMotion(options = {}) {
   const root = options.root || (typeof document !== 'undefined' ? document : null);
   if (!root) return () => {};
 
+  const policy = resolvePolicy(
+    options.policy
+      || root.documentElement?.getAttribute?.('data-velin-motion-policy')
+      || root.querySelector?.('[data-velin-motion-policy]')?.getAttribute('data-velin-motion-policy')
+      || 'safe',
+  );
+
   const selector =
     options.selector ||
     [
+      '[velin-motion]',
       '[velin-reveal]',
       '[velin-fade]',
       '[velin-slide]',
@@ -30,32 +68,48 @@ export function initMotion(options = {}) {
     ].join(',');
 
   const elements = root.querySelectorAll(selector);
-  const reduced = prefersReducedMotion();
+  const reduced = shouldDisableMotion(policy) || prefersReducedMotion();
 
   for (const el of elements) {
     if (el.dataset.velinMotionInit) continue;
     el.dataset.velinMotionInit = '1';
 
+    applyMotionVars(el, policy);
+
     const attrs = {};
-    for (const name of MOTION_ATTRS) {
+    const motionPreset = el.getAttribute('velin-motion');
+    if (motionPreset) {
+      attrs.motion = motionPreset;
+      const resolved = resolvePresetId(motionPreset);
+      if (resolved?.id) attrs[resolved.id] = 'true';
+    }
+    for (const name of LEGACY_ATTRS) {
       if (el.hasAttribute(name)) attrs[name.replace('velin-', '')] = el.getAttribute(name) || 'true';
     }
     applyEffects(el, attrs);
 
-    if (reduced) {
+    if (reduced || el.dataset.velinMotion === 'off') {
       markVisible(el);
       continue;
     }
 
-    const stop = observeInView(el, (node) => markVisible(node));
+    const stop = armMotionElement(el, () => applyEffects(el, attrs));
     teardownFns.push(stop);
   }
 
   enhanceStagger(root);
   bindSmoothScroll(root);
+  enhanceTimelines(root);
+  enhanceSequences(root);
 
   return () => {
-    teardownFns.forEach((fn) => fn());
+    teardownFns.forEach((fn) => {
+      try {
+        fn();
+      } catch {
+        /* ignore */
+      }
+    });
     teardownFns = [];
     disconnectInViewObserver();
   };
@@ -69,8 +123,57 @@ export function initReveal(options = {}) {
   });
 }
 
-export const velinMotion = { init: initMotion, observe: observeInView, markVisible, VISIBLE_CLASS };
+export const velinMotion = {
+  init: initMotion,
+  observe: observeInView,
+  markVisible,
+  VISIBLE_CLASS,
+  createEngine: createMotionEngine,
+  readTrigger,
+};
+
 export { observeInView, disconnectInViewObserver } from './scheduler.js';
-export { applyEffects, markVisible, prefersReducedMotion, VISIBLE_CLASS } from './effects.js';
+export { applyEffects, markVisible, prefersReducedMotion, VISIBLE_CLASS, EFFECT_MAP } from './effects.js';
 export { enhanceStagger, applyStagger } from './stagger.js';
 export { smoothScrollTo, bindSmoothScroll } from './scroll.js';
+export {
+  loadMotionRegistry,
+  listPresets,
+  listPolicies,
+  listTriggers,
+  listBlueprints,
+  listTimelines,
+  listMotion,
+  getPreset,
+  getPolicy,
+  getTrigger,
+  getTimeline,
+  getBlueprint,
+  catalogSummary,
+  resolvePresetId,
+  NAMESPACES,
+} from './registry.js';
+export {
+  bindTrigger,
+  readTrigger,
+  armMotionElement,
+  TRIGGER_V1,
+  TRIGGER_V2,
+  ALL_TRIGGERS,
+} from './triggers.js';
+export {
+  resolvePolicy,
+  listMotionPolicies,
+  shouldDisableMotion,
+  capDuration,
+  validatePolicy,
+  applyMotionVars,
+} from './policy.js';
+export { scanMotionHtml, doctorMotionHtml, collectMotionElements } from './scan.js';
+export { analyzeMotionHtml } from './analyze.js';
+export { runTimeline, enhanceTimelines } from './timeline.js';
+export { Motion, sequence, fade, slide, wait, rotate, blur, preset, enhanceSequences } from './composer.js';
+export { runViewTransition, applyTransitionHint, getTransitionPreset } from './transitions.js';
+export { emitMotionBlueprint } from './blueprint.js';
+export { optimizeMotionHtml } from './optimize.js';
+export { reviewMotionHtml } from './review.js';

package/core/motion/optimize.js

@@ -0,0 +1,44 @@
+/**
+ * Safe motion optimize — cap durations, strip infinite where safe.
+ * @param {string} html
+ * @param {{ write?: boolean, maxDuration?: number }} [opts]
+ */
+export function optimizeMotionHtml(html, opts = {}) {
+  const max = opts.maxDuration ?? 800;
+  let next = String(html || '');
+  const changes = [];
+
+  next = next.replace(/velin-duration\s*=\s*["'](\d+)["']/gi, (full, n) => {
+    const v = Number(n);
+    if (v > max) {
+      changes.push(`capped duration ${v} → ${max}`);
+      return `velin-duration="${max}"`;
+    }
+    return full;
+  });
+
+  next = next.replace(/velin-delay\s*=\s*["'](\d+)["']/gi, (full, n) => {
+    const v = Number(n);
+    if (v > 500) {
+      changes.push(`capped delay ${v} → 500`);
+      return `velin-delay="500"`;
+    }
+    return full;
+  });
+
+  const beforeInf = next;
+  next = next.replace(/\s*velin-animate[^\s"']*--infinite/gi, (m) => {
+    changes.push(`removed infinite modifier ${m.trim()}`);
+    return '';
+  });
+  if (next !== beforeInf && !changes.some((c) => c.includes('infinite'))) {
+    changes.push('stripped infinite animation classes');
+  }
+
+  return {
+    ok: true,
+    changed: changes.length > 0,
+    changes,
+    html: next,
+  };
+}

package/core/motion/policy.js

@@ -0,0 +1,77 @@
+/**
+ * Motion Policies — Safe / Reduced / Marketing / …
+ */
+import { getPolicy, listPolicies } from './registry.js';
+import { prefersReducedMotion } from './effects.js';
+
+/**
+ * @param {string} [id='safe']
+ */
+export function resolvePolicy(id = 'safe') {
+  return getPolicy(id) || getPolicy('safe');
+}
+
+export function listMotionPolicies() {
+  return listPolicies();
+}
+
+/**
+ * Whether motion should be skipped under policy + user preference.
+ * @param {object|null} policy
+ */
+export function shouldDisableMotion(policy) {
+  if (!policy) return prefersReducedMotion();
+  if (policy.disabled) return true;
+  if (policy.forceReduced && prefersReducedMotion()) return true;
+  if (prefersReducedMotion() && policy.id !== 'marketing') return true;
+  return false;
+}
+
+/**
+ * Cap a duration against policy.
+ * @param {number} ms
+ * @param {object|null} policy
+ */
+export function capDuration(ms, policy) {
+  const max = policy?.maxDurationMs ?? 800;
+  if (policy?.disabled) return 0;
+  return Math.min(Number(ms) || 0, max);
+}
+
+/**
+ * Validate policy id exists.
+ */
+export function validatePolicy(id) {
+  const p = getPolicy(id);
+  if (!p) return { ok: false, error: `Unknown motion policy "${id}"` };
+  return { ok: true, policy: p };
+}
+
+/**
+ * Apply CSS variables for duration/ease from attributes + policy.
+ * @param {HTMLElement} el
+ * @param {object|null} policy
+ */
+export function applyMotionVars(el, policy) {
+  const duration = el.getAttribute('velin-duration');
+  const delay = el.getAttribute('velin-delay');
+  const ease = el.getAttribute('velin-ease');
+  if (duration) {
+    const capped = capDuration(Number(duration), policy);
+    el.style.setProperty('--velin-motion-duration', `${capped}ms`);
+    el.style.animationDuration = `${capped}ms`;
+  }
+  if (delay) el.style.animationDelay = `${Number(delay)}ms`;
+  if (ease) {
+    const map = {
+      spring: 'var(--velin-ease-spring)',
+      bounce: 'var(--velin-ease-bounce)',
+      elastic: 'var(--velin-ease-elastic)',
+      default: 'var(--velin-ease-default)',
+    };
+    el.style.animationTimingFunction = map[ease] || ease;
+  }
+  if (policy?.disabled || shouldDisableMotion(policy)) {
+    el.dataset.velinMotion = 'off';
+  }
+}

package/core/motion/registry.js

@@ -0,0 +1,131 @@
+/**
+ * Velin Motion Registry — all building blocks (Studio-ready source of truth).
+ * Browser-safe: no fs — data imported as JSON module.
+ */
+import data from './data/registry.json' with { type: 'json' };
+
+/** @type {object | null} */
+let cached = data;
+
+const NAMESPACES = [
+  'presets',
+  'timelines',
+  'transitions',
+  'physics',
+  'composers',
+  'triggers',
+  'policies',
+  'blueprints',
+];
+
+/**
+ * @returns {object}
+ */
+export function loadMotionRegistry(override = null) {
+  if (override) {
+    cached = override;
+    return cached;
+  }
+  return cached || data;
+}
+
+export function clearMotionRegistryCache() {
+  cached = data;
+}
+
+export function listNamespaces() {
+  return [...NAMESPACES];
+}
+
+/**
+ * @param {string} namespace
+ * @param {{ status?: string, category?: string, tag?: string }} [filter]
+ */
+export function listMotion(namespace, filter = {}) {
+  const reg = loadMotionRegistry();
+  const key = namespace.endsWith('s') ? namespace : `${namespace}s`;
+  const items = reg[key] || reg[namespace] || [];
+  return items.filter((item) => {
+    if (filter.status && item.status !== filter.status) return false;
+    if (filter.category && item.category !== filter.category) return false;
+    if (filter.tag && !(item.tags || []).includes(filter.tag)) return false;
+    return true;
+  });
+}
+
+export function getMotion(namespace, id) {
+  return listMotion(namespace).find((item) => item.id === id) || null;
+}
+
+export function getPreset(id) {
+  return getMotion('presets', id);
+}
+
+export function getPolicy(id) {
+  return getMotion('policies', id);
+}
+
+export function getTrigger(id) {
+  return getMotion('triggers', id);
+}
+
+export function getTimeline(id) {
+  return getMotion('timelines', id);
+}
+
+export function getBlueprint(id) {
+  return getMotion('blueprints', id);
+}
+
+export function listPresets(filter) {
+  return listMotion('presets', filter);
+}
+
+export function listPolicies(filter) {
+  return listMotion('policies', filter);
+}
+
+export function listTriggers(filter) {
+  return listMotion('triggers', filter);
+}
+
+export function listBlueprints(filter) {
+  return listMotion('blueprints', filter);
+}
+
+export function listTimelines(filter) {
+  return listMotion('timelines', filter);
+}
+
+export function catalogSummary() {
+  const reg = loadMotionRegistry();
+  const counts = {};
+  for (const ns of NAMESPACES) {
+    counts[ns] = (reg[ns] || []).length;
+  }
+  return {
+    schema: reg.schema,
+    version: reg.version,
+    counts,
+    namespaces: NAMESPACES,
+  };
+}
+
+export function exportMotionRegistry() {
+  return structuredClone(loadMotionRegistry());
+}
+
+export function resolvePresetId(id) {
+  if (!id) return null;
+  const direct = getPreset(id);
+  if (direct) return direct;
+  const aliases = {
+    scale: 'zoom',
+    'hover-lift': 'lift',
+    reveal: 'fade',
+  };
+  const mapped = aliases[id];
+  return mapped ? getPreset(mapped) : null;
+}
+
+export { NAMESPACES };

package/core/motion/review.js

@@ -0,0 +1,59 @@
+/**
+ * Review motion markup — counts, delays, reduced-motion, layout-shift, FPS hints.
+ */
+import { analyzeMotionHtml } from './analyze.js';
+import { doctorMotionHtml } from './scan.js';
+
+/**
+ * @param {string} html
+ */
+export function reviewMotionHtml(html) {
+  const analysis = analyzeMotionHtml(html);
+  const doctor = doctorMotionHtml(html);
+  const findings = [...doctor.findings];
+
+  if (analysis.metrics.animations > 40) {
+    findings.push({
+      severity: 'warning',
+      code: 'motion.too-many',
+      message: `${analysis.metrics.animations} motion elements — consider reducing`,
+    });
+  }
+  if (analysis.metrics.averageMs > 600) {
+    findings.push({
+      severity: 'warning',
+      code: 'motion.avg-slow',
+      message: `Average duration ${analysis.metrics.averageMs}ms is high`,
+    });
+  }
+  if (analysis.metrics.layoutShiftRisk === 'HIGH') {
+    findings.push({
+      severity: 'error',
+      code: 'motion.cls-risk',
+      message: 'Layout shift risk HIGH (parallax/infinite combination)',
+    });
+  }
+  if (analysis.metrics.infinite > 0) {
+    findings.push({
+      severity: 'warning',
+      code: 'motion.fps-risk',
+      message: `${analysis.metrics.infinite} infinite animation(s) — FPS risk on low-end devices`,
+    });
+  }
+
+  const errors = findings.filter((f) => f.severity === 'error').length;
+  const warnings = findings.filter((f) => f.severity === 'warning').length;
+  const score = Math.max(0, 100 - errors * 25 - warnings * 8);
+
+  return {
+    ok: errors === 0,
+    gate: errors ? 'fail' : warnings ? 'warn' : 'pass',
+    scores: {
+      motion: score,
+      accessibility: analysis.metrics.reducedMotion === 'PASS' ? 100 : 40,
+      performance: analysis.metrics.layoutShiftRisk === 'LOW' ? 90 : analysis.metrics.layoutShiftRisk === 'MEDIUM' ? 60 : 30,
+    },
+    metrics: analysis.metrics,
+    findings,
+  };
+}

package/core/motion/scan.js

@@ -0,0 +1,150 @@
+/**
+ * Collect motion-related nodes from HTML markup (string or DOM-less regex).
+ */
+const MOTION_ATTR_RE =
+  /\s(?:velin-motion|velin-reveal|velin-fade|velin-slide|velin-scale|velin-parallax|velin-hover|velin-stagger|velin-scroll|velin-trigger|velin-motion-sequence|data-velin-motion|data-velin-reveal-auto)\s*(?:=\s*["']([^"']*)["'])?/gi;
+
+const CLASS_MOTION_RE =
+  /\b(?:velin-animate(?:-[\w-]+)?|velin-parallax|velin-skeleton|velin-in-view)\b/g;
+
+const DURATION_RE = /velin-duration\s*=\s*["'](\d+)["']/gi;
+const INFINITE_RE = /velin-animate[^\s"']*--infinite|animation:\s*[^;]*infinite/gi;
+
+/**
+ * @param {string} html
+ */
+export function collectMotionElements(html) {
+  const text = String(html || '');
+  const elements = [];
+  const seen = new Set();
+
+  for (const m of text.matchAll(/<([a-z0-9-]+)([^>]*)>/gi)) {
+    const tag = m[1];
+    const attrs = m[2] || '';
+    if (!/velin-(?:motion|reveal|fade|slide|scale|parallax|hover|stagger|scroll|trigger)/i.test(attrs)
+      && !/velin-animate|velin-parallax|velin-skeleton/i.test(attrs)) {
+      continue;
+    }
+    const preset = attrs.match(/velin-motion\s*=\s*["']([^"']+)["']/i)?.[1]
+      || (attrs.includes('velin-fade') ? 'fade' : null)
+      || (attrs.includes('velin-reveal') ? 'fade' : null)
+      || (attrs.includes('velin-slide') ? 'slide' : null)
+      || (attrs.includes('velin-scale') ? 'zoom' : null)
+      || (attrs.includes('velin-hover') ? 'lift' : null)
+      || (attrs.includes('velin-parallax') ? 'parallax' : null)
+      || null;
+    const trigger = attrs.match(/velin-trigger\s*=\s*["']([^"']+)["']/i)?.[1] || 'visible';
+    const duration = Number(attrs.match(/velin-duration\s*=\s*["'](\d+)["']/i)?.[1] || 0);
+    const key = `${tag}:${preset}:${trigger}:${attrs.slice(0, 40)}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    elements.push({
+      tag,
+      preset,
+      trigger,
+      duration,
+      hasReducedHint: /prefers-reduced-motion|data-velin-motion\s*=\s*["']off["']/i.test(attrs),
+      infinite: /--infinite|infinite/i.test(attrs),
+      attrs: attrs.trim().slice(0, 120),
+    });
+  }
+
+  const classHits = [...text.matchAll(CLASS_MOTION_RE)].length;
+  return { elements, classHits, rawLength: text.length };
+}
+
+/**
+ * @param {string} html
+ * @param {{ policyId?: string }} [opts]
+ */
+export function scanMotionHtml(html, opts = {}) {
+  const { elements, classHits } = collectMotionElements(html);
+  const presets = new Map();
+  const triggers = new Map();
+  let infinite = 0;
+  let longCount = 0;
+  const findings = [];
+
+  for (const el of elements) {
+    if (el.preset) presets.set(el.preset, (presets.get(el.preset) || 0) + 1);
+    if (el.trigger) triggers.set(el.trigger, (triggers.get(el.trigger) || 0) + 1);
+    if (el.infinite) infinite += 1;
+    if (el.duration > 800) {
+      longCount += 1;
+      findings.push({
+        severity: 'warning',
+        code: 'motion.long-duration',
+        message: `Duration ${el.duration}ms exceeds 800ms soft cap`,
+      });
+    }
+  }
+
+  if (infinite) {
+    findings.push({
+      severity: 'warning',
+      code: 'motion.infinite',
+      message: `${infinite} infinite animation hint(s)`,
+    });
+  }
+
+  const dupPresets = [...presets.entries()].filter(([, n]) => n > 8);
+  for (const [id, n] of dupPresets) {
+    findings.push({
+      severity: 'info',
+      code: 'motion.duplicate-preset',
+      message: `Preset "${id}" used ${n} times`,
+    });
+  }
+
+  return {
+    ok: !findings.some((f) => f.severity === 'error'),
+    summary: {
+      elements: elements.length,
+      classHits,
+      presets: presets.size,
+      triggers: triggers.size,
+      infinite,
+      longCount,
+      policy: opts.policyId || 'safe',
+    },
+    presets: Object.fromEntries(presets),
+    triggers: Object.fromEntries(triggers),
+    findings,
+    elements: elements.slice(0, 100),
+  };
+}
+
+/**
+ * @param {string} html
+ */
+export function doctorMotionHtml(html) {
+  const scan = scanMotionHtml(html);
+  const findings = [...scan.findings];
+
+  if (!/prefers-reduced-motion|data-velin-motion|reduced-motion/i.test(html) && scan.summary.elements > 0) {
+    findings.push({
+      severity: 'warning',
+      code: 'motion.missing-reduced',
+      message: 'No reduced-motion / data-velin-motion=off hints found near motion usage',
+    });
+  }
+
+  const long = scan.elements.filter((e) => e.duration > 1200);
+  for (const el of long) {
+    findings.push({
+      severity: 'error',
+      code: 'motion.excessive-duration',
+      message: `Duration ${el.duration}ms is excessive`,
+    });
+  }
+
+  const errors = findings.filter((f) => f.severity === 'error').length;
+  const warnings = findings.filter((f) => f.severity === 'warning').length;
+
+  return {
+    ok: errors === 0,
+    summary: { ...scan.summary, errors, warnings },
+    findings,
+    scan,
+  };
+}