@birdapi/velinstyle 1.2.1 → 1.3.0

package/core/attributes/registry.js

@@ -240,7 +240,7 @@ function registerBuiltins() {
     },
   });
 
-  for (const motion of ['velin-reveal', 'velin-fade', 'velin-slide', 'velin-scale', 'velin-parallax', 'velin-hover', 'velin-stagger', 'velin-scroll']) {
+  for (const motion of ['velin-motion', 'velin-trigger', 'velin-duration', 'velin-delay', 'velin-ease', 'velin-timeline', 'velin-motion-sequence', 'velin-reveal', 'velin-fade', 'velin-slide', 'velin-scale', 'velin-parallax', 'velin-hover', 'velin-stagger', 'velin-scroll']) {
     registerAttribute(motion, { enhance() {} });
   }
 }

package/core/meta/knowledge/components.json

@@ -201,7 +201,7 @@
       "density": ["default"],
       "themeSupport": ["light", "dark"],
       "motion": { "reducedMotionSafe": true },
-      "examples": ["<velin-modal><h2 slot=\"title\">…</h2></velin-modal>"],
+      "examples": ["<velin-modal title=\"Confirm\"></velin-modal>", "<velin-modal><h2 slot=\"title\">…</h2></velin-modal>"],
       "promptKeywords": ["modal", "dialog overlay", "popup"],
       "designIntelligence": {
         "visualWeight": 5,
@@ -491,7 +491,7 @@
       "density": ["default", "compact"],
       "themeSupport": ["light", "dark"],
       "motion": { "reducedMotionSafe": true },
-      "examples": ["<velin-drawer></velin-drawer>"],
+      "examples": ["<velin-drawer title=\"Filters\"></velin-drawer>", "<velin-drawer><span slot=\"title\">Filters</span></velin-drawer>"],
       "promptKeywords": ["drawer", "side panel", "sidebar overlay"],
       "designIntelligence": {
         "visualWeight": 4,
@@ -528,7 +528,7 @@
       "density": ["default", "compact"],
       "themeSupport": ["light", "dark"],
       "motion": { "reducedMotionSafe": true },
-      "examples": ["<velin-sheet></velin-sheet>"],
+      "examples": ["<velin-sheet title=\"Actions\"></velin-sheet>", "<velin-sheet><span slot=\"title\">Actions</span></velin-sheet>"],
       "promptKeywords": ["sheet", "bottom sheet", "action sheet"],
       "designIntelligence": {
         "visualWeight": 4,
@@ -617,6 +617,78 @@
         "commonMistakes": ["toasts for persistent form errors"],
         "bestPractices": ["auto-dismiss with pause on focus/hover"]
       }
+    },
+    {
+      "id": "velin-otp-input",
+      "kind": "web-component",
+      "tag": "velin-otp-input",
+      "category": "forms",
+      "subcategory": "otp",
+      "purpose": "Segmented one-time-password / PIN digit entry with paste and keyboard support.",
+      "family": "forms",
+      "maturity": "core",
+      "recommendedPages": ["auth", "saas"],
+      "recommendedSections": [],
+      "compatibleWith": ["css-button", "velin-form-summary", "velin-secure-field"],
+      "incompatibleWith": [],
+      "accessibility": { "role": "group", "notes": "Per-digit labels; autocomplete one-time-code" },
+      "seo": { "impact": "none" },
+      "performance": { "cost": "lazy-ok" },
+      "variants": [],
+      "density": ["default"],
+      "themeSupport": ["light", "dark"],
+      "motion": { "reducedMotionSafe": true },
+      "examples": ["<velin-otp-input length=\"6\"></velin-otp-input>"],
+      "promptKeywords": ["otp", "2fa", "pin", "one-time password"],
+      "api": { "events": ["velin-change", "velin-complete"], "attributes": ["length", "value", "disabled", "name"] }
+    },
+    {
+      "id": "velin-password-strength",
+      "kind": "web-component",
+      "tag": "velin-password-strength",
+      "category": "forms",
+      "subcategory": "password",
+      "purpose": "Heuristic password strength meter linked to an input via for= or value.",
+      "family": "forms",
+      "maturity": "core",
+      "recommendedPages": ["auth", "saas"],
+      "recommendedSections": [],
+      "compatibleWith": ["css-input", "velin-secure-field", "velin-form-summary"],
+      "incompatibleWith": [],
+      "accessibility": { "role": "progressbar", "notes": "aria-live polite label" },
+      "seo": { "impact": "none" },
+      "performance": { "cost": "lazy-ok" },
+      "variants": [],
+      "density": ["default"],
+      "themeSupport": ["light", "dark"],
+      "motion": { "reducedMotionSafe": true },
+      "examples": ["<input id=\"pw\" type=\"password\"><velin-password-strength for=\"pw\"></velin-password-strength>"],
+      "promptKeywords": ["password strength", "meter", "signup"],
+      "api": { "events": ["velin-strength"], "attributes": ["for", "value", "label"] }
+    },
+    {
+      "id": "velin-empty-state",
+      "kind": "web-component",
+      "tag": "velin-empty-state",
+      "category": "feedback",
+      "subcategory": "empty",
+      "purpose": "Consistent empty / zero-data surface with illustration, title, description, and actions slots.",
+      "family": "feedback",
+      "maturity": "core",
+      "recommendedPages": ["dashboard", "saas", "shop", "docs"],
+      "recommendedSections": [],
+      "compatibleWith": ["css-button", "velin-icon"],
+      "incompatibleWith": [],
+      "accessibility": { "role": "status" },
+      "seo": { "impact": "none" },
+      "performance": { "cost": "lazy-ok" },
+      "variants": [],
+      "density": ["default"],
+      "themeSupport": ["light", "dark"],
+      "motion": { "reducedMotionSafe": true },
+      "examples": ["<velin-empty-state heading=\"No items yet\" description=\"Create your first entry.\"><button slot=\"actions\" class=\"velin-btn velin-btn--primary\">Create</button></velin-empty-state>"],
+      "promptKeywords": ["empty state", "no results", "zero data"],
+      "api": { "attributes": ["heading", "description"], "slots": ["illustration", "title", "description", "actions"] }
     }
   ]
 }

package/core/motion/analyze.js

@@ -0,0 +1,38 @@
+import { scanMotionHtml, doctorMotionHtml, collectMotionElements } from './scan.js';
+
+/**
+ * Aggregate metrics for `velinstyle motion analyze`.
+ * @param {string} html
+ */
+export function analyzeMotionHtml(html) {
+  const { elements } = collectMotionElements(html);
+  const scan = scanMotionHtml(html);
+  const durations = elements.map((e) => e.duration).filter((d) => d > 0);
+  const sum = durations.reduce((a, b) => a + b, 0);
+  const avg = durations.length ? Math.round(sum / durations.length) : 0;
+  const longest = durations.length ? Math.max(...durations) : 0;
+  const doctor = doctorMotionHtml(html);
+  const reducedPass = !doctor.findings.some((f) => f.code === 'motion.missing-reduced' || f.code === 'motion.excessive-duration');
+
+  let layoutShiftRisk = 'LOW';
+  if (elements.some((e) => e.preset === 'parallax') || scan.summary.infinite > 2) layoutShiftRisk = 'MEDIUM';
+  if (scan.summary.infinite > 5 || longest > 2000) layoutShiftRisk = 'HIGH';
+
+  return {
+    ok: doctor.ok,
+    metrics: {
+      animations: elements.length || scan.summary.classHits,
+      durationMs: sum,
+      durationLabel: `${(sum / 1000).toFixed(1)} s`,
+      averageMs: avg,
+      longestMs: longest,
+      reducedMotion: reducedPass ? 'PASS' : 'FAIL',
+      infinite: scan.summary.infinite,
+      layoutShiftRisk,
+    },
+    summary: scan.summary,
+    findings: doctor.findings,
+  };
+}
+
+export { doctorMotionHtml, scanMotionHtml };

package/core/motion/blueprint.js

@@ -0,0 +1,51 @@
+/**
+ * Emit motion blueprint HTML snippets from registry.
+ */
+import { getBlueprint, getPreset, getTimeline, getPolicy } from './registry.js';
+
+/**
+ * @param {string} kind
+ * @returns {{ ok: boolean, html?: string, error?: string, blueprint?: object }}
+ */
+export function emitMotionBlueprint(kind) {
+  const bp = getBlueprint(kind);
+  if (!bp) {
+    return {
+      ok: false,
+      error: `Unknown motion blueprint "${kind}". Use: landing|dashboard|pricing|portfolio|shop|forum|docs|blog|crm|login`,
+    };
+  }
+  const policy = getPolicy(bp.policy || 'safe');
+  const timeline = bp.timeline ? getTimeline(bp.timeline) : null;
+  const presetBlocks = (bp.presets || [])
+    .map((id) => {
+      const p = getPreset(id);
+      return `  <!-- preset: ${id}${p ? ` — ${p.title}` : ''} -->
+  <div velin-motion="${id === 'heroReveal' ? 'fade' : id}" velin-trigger="visible" class="velin-mb-4">
+    <p class="velin-text-muted">${p?.title || id}</p>
+  </div>`;
+    })
+    .join('\n');
+
+  const timelineBlock = timeline
+    ? `
+<section velin-timeline="${timeline.id}" class="velin-stack velin-gap-3" aria-label="${timeline.title}">
+  ${(timeline.steps || [])
+    .map(
+      (step, i) =>
+        `  <div data-velin-step="${step}" velin-motion="fade" velin-trigger="load" velin-delay="${i * 100}">${step}</div>`,
+    )
+    .join('\n')}
+</section>`
+    : '';
+
+  const html = `<!-- Velin Motion blueprint: ${bp.id} · policy ${policy?.id || 'safe'} -->
+<!-- ${bp.description} -->
+<div data-velin-motion-policy="${policy?.id || 'safe'}" data-velin-reveal-auto>
+${presetBlocks}
+${timelineBlock}
+</div>
+`;
+
+  return { ok: true, html, blueprint: bp };
+}

package/core/motion/composer.js

@@ -0,0 +1,114 @@
+/**
+ * Motion Composer — sequence API (Studio-ready).
+ */
+import { prefersReducedMotion, markVisible } from './effects.js';
+import { resolvePresetId } from './registry.js';
+import { applyEffects } from './effects.js';
+
+/**
+ * @typedef {{ type: 'fade'|'slide'|'wait'|'rotate'|'blur'|'preset', preset?: string, ms?: number, value?: string }} MotionStep
+ */
+
+export function fade(ms = 400) {
+  return { type: 'fade', ms };
+}
+
+export function slide(ms = 500, value = 'up') {
+  return { type: 'slide', ms, value };
+}
+
+export function wait(ms = 200) {
+  return { type: 'wait', ms };
+}
+
+export function rotate(ms = 400) {
+  return { type: 'rotate', ms };
+}
+
+export function blur(ms = 400) {
+  return { type: 'blur', ms };
+}
+
+export function preset(id, ms) {
+  return { type: 'preset', preset: id, ms };
+}
+
+/**
+ * @param {MotionStep[]} steps
+ * @param {{ root?: HTMLElement, target?: HTMLElement }} [ctx]
+ */
+export async function sequence(steps = [], ctx = {}) {
+  const target = ctx.target || ctx.root;
+  const reduced = prefersReducedMotion();
+  const ran = [];
+
+  for (const step of steps) {
+    if (step.type === 'wait') {
+      if (!reduced && step.ms) await delay(step.ms);
+      ran.push(step);
+      continue;
+    }
+    if (target && typeof target.classList?.add === 'function') {
+      if (step.type === 'preset' && step.preset) {
+        const p = resolvePresetId(step.preset);
+        if (p?.cssClass) target.classList.add(...String(p.cssClass).split(/\s+/));
+        applyEffects(target, { [step.preset]: 'true' });
+      } else if (step.type === 'fade') {
+        applyEffects(target, { fade: 'true' });
+      } else if (step.type === 'slide') {
+        applyEffects(target, { slide: step.value || 'up' });
+      } else if (step.type === 'blur') {
+        applyEffects(target, { blur: 'true' });
+      } else if (step.type === 'rotate') {
+        applyEffects(target, { flip: 'true' });
+      }
+      markVisible(target);
+    }
+    if (!reduced && step.ms) await delay(step.ms);
+    ran.push(step);
+  }
+  return { ok: true, ran };
+}
+
+function delay(ms) {
+  return new Promise((resolve) => {
+    if (typeof setTimeout === 'undefined') return resolve();
+    setTimeout(resolve, ms);
+  });
+}
+
+/**
+ * Declarative `<section velin-motion-sequence>` — children play in order.
+ */
+export function enhanceSequences(root) {
+  if (!root?.querySelectorAll) return () => {};
+  const nodes = [...root.querySelectorAll('[velin-motion-sequence]')];
+  for (const section of nodes) {
+    const children = [...section.children];
+    let i = 0;
+    const stepMs = Number(section.getAttribute('velin-sequence-gap') || 120);
+    for (const child of children) {
+      child.classList.add('velin-animate-on-scroll', 'velin-animate-on-scroll--fade');
+      if (prefersReducedMotion()) {
+        markVisible(child);
+      } else if (typeof setTimeout !== 'undefined') {
+        const delayMs = i * stepMs;
+        setTimeout(() => markVisible(child), delayMs);
+      } else {
+        markVisible(child);
+      }
+      i += 1;
+    }
+  }
+  return () => {};
+}
+
+export const Motion = {
+  sequence,
+  fade,
+  slide,
+  wait,
+  rotate,
+  blur,
+  preset,
+};