@birdapi/velinstyle 1.2.1 → 1.3.0

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,
+  };
+}

package/core/motion/timeline.js

@@ -0,0 +1,68 @@
+/**
+ * Timeline Engine — Scene → Timeline → Steps (Registry-backed).
+ */
+import { getTimeline } from './registry.js';
+import { markVisible, prefersReducedMotion } from './effects.js';
+
+/**
+ * Run a registered timeline against a root element.
+ * Steps resolve `[data-velin-step="id"]` or `#id` or `[velin-step="id"]`.
+ * @param {string} timelineId
+ * @param {ParentNode} root
+ * @param {{ stepMs?: number, policyDisabled?: boolean }} [opts]
+ * @returns {{ ok: boolean, error?: string, ran: string[] }}
+ */
+export function runTimeline(timelineId, root, opts = {}) {
+  const tl = getTimeline(timelineId);
+  if (!tl) return { ok: false, error: `Unknown timeline "${timelineId}"`, ran: [] };
+  const stepMs = opts.stepMs ?? 120;
+  const ran = [];
+
+  if (opts.policyDisabled || prefersReducedMotion()) {
+    for (const step of tl.steps || []) {
+      const el = resolveStep(root, step);
+      if (el) markVisible(el);
+      ran.push(step);
+    }
+    return { ok: true, ran };
+  }
+
+  let delay = 0;
+  for (const step of tl.steps || []) {
+    const el = resolveStep(root, step);
+    if (!el) continue;
+    const d = delay;
+    delay += stepMs;
+    if (typeof window !== 'undefined' && window.setTimeout) {
+      window.setTimeout(() => markVisible(el), d);
+    } else {
+      markVisible(el);
+    }
+    ran.push(step);
+  }
+  return { ok: true, ran, timeline: tl };
+}
+
+function resolveStep(root, step) {
+  if (!root?.querySelector) return null;
+  return (
+    root.querySelector(`[data-velin-step="${step}"]`)
+    || root.querySelector(`[velin-step="${step}"]`)
+    || root.querySelector(`#${CSS.escape?.(step) || step}`)
+  );
+}
+
+/**
+ * Enhance `[velin-timeline="id"]` roots.
+ */
+export function enhanceTimelines(root) {
+  if (!root?.querySelectorAll) return () => {};
+  const nodes = root.querySelectorAll('[velin-timeline]');
+  const teardowns = [];
+  for (const el of nodes) {
+    const id = el.getAttribute('velin-timeline');
+    const result = runTimeline(id, el);
+    teardowns.push(() => result);
+  }
+  return () => {};
+}

package/core/motion/transitions.js

@@ -0,0 +1,49 @@
+/**
+ * Transition helpers (View Transition + overlay hooks).
+ */
+import { getMotion } from './registry.js';
+
+/**
+ * Run a document view transition if supported.
+ * @param {() => void|Promise<void>} updateCallback
+ * @param {{ name?: string }} [opts]
+ */
+export async function runViewTransition(updateCallback, opts = {}) {
+  const doc = typeof document !== 'undefined' ? document : null;
+  if (!doc) {
+    await updateCallback();
+    return { ok: true, mode: 'direct' };
+  }
+  if (typeof doc.startViewTransition === 'function') {
+    const vt = doc.startViewTransition(async () => {
+      if (opts.name && doc.documentElement) {
+        doc.documentElement.style.viewTransitionName = opts.name;
+      }
+      await updateCallback();
+    });
+    await vt.finished.catch(() => {});
+    return { ok: true, mode: 'view-transition', id: opts.name || null };
+  }
+  await updateCallback();
+  return { ok: true, mode: 'fallback' };
+}
+
+export function getTransitionPreset(id) {
+  return getMotion('transitions', id);
+}
+
+/**
+ * Apply transition class hints for modal/drawer hosts.
+ * @param {HTMLElement} el
+ * @param {'modal-enter'|'drawer-enter'|'cross-fade'} id
+ */
+export function applyTransitionHint(el, id) {
+  if (!el) return;
+  const map = {
+    'modal-enter': 'velin-animate-fade-in',
+    'drawer-enter': 'velin-animate-on-scroll--slide-right',
+    'cross-fade': 'velin-animate-fade-in',
+  };
+  const cls = map[id];
+  if (cls) el.classList.add(cls);
+}

package/core/motion/triggers.js

@@ -0,0 +1,168 @@
+/**
+ * Motion Trigger Engine — when motion starts (First-Class, Studio-ready).
+ */
+import { observeInView } from './scheduler.js';
+import { markVisible, prefersReducedMotion } from './effects.js';
+import { getTrigger } from './registry.js';
+
+export const TRIGGER_V1 = ['load', 'visible', 'hover', 'focus', 'click', 'scroll'];
+export const TRIGGER_V2 = ['hidden', 'idle', 'media', 'container', 'theme', 'custom'];
+export const ALL_TRIGGERS = [...TRIGGER_V1, ...TRIGGER_V2];
+
+/**
+ * Read trigger id from element (velin-trigger or default).
+ * @param {HTMLElement} el
+ * @param {string} [fallback='visible']
+ */
+export function readTrigger(el, fallback = 'visible') {
+  const raw = (el.getAttribute('velin-trigger') || fallback || 'visible').trim().toLowerCase();
+  return raw || fallback;
+}
+
+/**
+ * Bind a trigger to run `onFire` once (or per event).
+ * @param {HTMLElement} el
+ * @param {string} triggerId
+ * @param {() => void} onFire
+ * @param {{ once?: boolean, reduced?: boolean }} [opts]
+ * @returns {() => void} teardown
+ */
+export function bindTrigger(el, triggerId, onFire, opts = {}) {
+  const once = opts.once !== false;
+  const reduced = opts.reduced ?? prefersReducedMotion();
+  const id = (triggerId || 'visible').toLowerCase();
+  const meta = getTrigger(id);
+
+  if (reduced || el.dataset.velinMotion === 'off') {
+    onFire();
+    return () => {};
+  }
+
+  if (meta?.status === 'planned' && !TRIGGER_V1.includes(id)) {
+    // Planned V2 triggers are not first-class yet: fall back to visible for runtime safety
+    return bindTrigger(el, 'visible', onFire, opts);
+  }
+
+  let fired = false;
+  const fire = () => {
+    if (once && fired) return;
+    fired = true;
+    onFire();
+  };
+
+  if (id === 'load') {
+    fire();
+    return () => {};
+  }
+
+  if (id === 'visible' || id === 'scroll') {
+    return observeInView(el, () => fire());
+  }
+
+  if (id === 'hover') {
+    const enter = () => fire();
+    el.addEventListener('pointerenter', enter);
+    return () => el.removeEventListener('pointerenter', enter);
+  }
+
+  if (id === 'focus') {
+    const onFocus = () => fire();
+    el.addEventListener('focusin', onFocus);
+    return () => el.removeEventListener('focusin', onFocus);
+  }
+
+  if (id === 'click') {
+    const onClick = () => fire();
+    el.addEventListener('click', onClick);
+    return () => el.removeEventListener('click', onClick);
+  }
+
+  if (id === 'hidden') {
+    const stop = observeInView(el, () => {
+      /* enter */
+    });
+    // Fallback: use IntersectionObserver with leave
+    if (typeof IntersectionObserver === 'undefined') return () => {};
+    const io = new IntersectionObserver((entries) => {
+      for (const entry of entries) {
+        if (!entry.isIntersecting) fire();
+      }
+    }, { threshold: 0 });
+    io.observe(el);
+    return () => {
+      stop();
+      io.disconnect();
+    };
+  }
+
+  if (id === 'idle') {
+    const ms = Number(el.getAttribute('velin-trigger-delay') || 3000);
+    const t = setTimeout(fire, ms);
+    return () => clearTimeout(t);
+  }
+
+  if (id === 'media') {
+    const q = el.getAttribute('velin-trigger-media') || '(min-width: 768px)';
+    if (typeof window === 'undefined' || !window.matchMedia) {
+      fire();
+      return () => {};
+    }
+    const mql = window.matchMedia(q);
+    const handler = () => {
+      if (mql.matches) fire();
+    };
+    handler();
+    mql.addEventListener?.('change', handler);
+    return () => mql.removeEventListener?.('change', handler);
+  }
+
+  if (id === 'theme') {
+    const root = el.ownerDocument?.documentElement;
+    if (!root || typeof MutationObserver === 'undefined') {
+      fire();
+      return () => {};
+    }
+    const mo = new MutationObserver(() => fire());
+    mo.observe(root, { attributes: true, attributeFilter: ['data-velin-theme', 'class'] });
+    return () => mo.disconnect();
+  }
+
+  if (id === 'custom') {
+    const evt = el.getAttribute('velin-trigger-event') || 'velin:motion';
+    const handler = () => fire();
+    el.addEventListener(evt, handler);
+    return () => el.removeEventListener(evt, handler);
+  }
+
+  if (id === 'container') {
+    // Approximate with visible until container queries runtime ships
+    return observeInView(el, () => fire());
+  }
+
+  // Unknown → visible
+  return observeInView(el, () => fire());
+}
+
+/**
+ * Apply motion classes then bind trigger to markVisible.
+ * @param {HTMLElement} el
+ * @param {() => void} applyPreset
+ */
+export function armMotionElement(el, applyPreset) {
+  applyPreset();
+  const trigger = readTrigger(el, el.hasAttribute('velin-hover') ? 'hover' : 'visible');
+  if (prefersReducedMotion() || el.dataset.velinMotion === 'off') {
+    markVisible(el);
+    return () => {};
+  }
+  if (trigger === 'hover' || trigger === 'focus') {
+    // CSS hover classes already apply; still mark visible for scroll classes
+    markVisible(el);
+    return () => {};
+  }
+  if (trigger === 'load') {
+    markVisible(el);
+    return () => {};
+  }
+  return bindTrigger(el, trigger, () => markVisible(el));
+}