@birdapi/velinstyle 0.7.0 → 0.9.0

package/core/motion/effects.js

@@ -0,0 +1,54 @@
+export const VISIBLE_CLASS = 'velin-in-view';
+
+const EFFECT_MAP = {
+  reveal: ['velin-animate-on-scroll'],
+  fade: ['velin-animate-on-scroll', 'velin-animate-on-scroll--fade'],
+  slide: ['velin-animate-on-scroll', 'velin-animate-on-scroll--slide-up'],
+  'slide-up': ['velin-animate-on-scroll', 'velin-animate-on-scroll--slide-up'],
+  'slide-down': ['velin-animate-on-scroll', 'velin-animate-on-scroll--slide-down'],
+  'slide-left': ['velin-animate-on-scroll', 'velin-animate-on-scroll--slide-left'],
+  'slide-right': ['velin-animate-on-scroll', 'velin-animate-on-scroll--slide-right'],
+  scale: ['velin-animate-on-scroll', 'velin-animate-on-scroll--scale'],
+  parallax: ['velin-parallax'],
+  'parallax-slow': ['velin-parallax', 'velin-parallax--slow'],
+  hover: ['velin-animate-hover'],
+  'hover-lift': ['velin-animate-hover'],
+  flip: ['velin-animate-scale-in'],
+  blur: ['velin-animate-fade-in'],
+};
+
+/**
+ * Apply motion effect classes from velin-* attribute values.
+ * @param {HTMLElement} el
+ * @param {Record<string, string>} attrs keyed by effect name
+ */
+export function applyEffects(el, attrs = {}) {
+  const classes = new Set();
+  for (const [name, value] of Object.entries(attrs)) {
+    if (value === 'false' || value === 'off') continue;
+    const mapped = EFFECT_MAP[name];
+    if (mapped) mapped.forEach((c) => classes.add(c));
+    if (name === 'slide' && value && value !== 'true' && value !== '') {
+      const key = `slide-${value}`;
+      EFFECT_MAP[key]?.forEach((c) => classes.add(c));
+    }
+  }
+  classes.forEach((c) => el.classList.add(c));
+  if (!el.classList.contains('velin-animate-on-scroll') && attrs.reveal !== undefined) {
+    el.classList.add('velin-animate-on-scroll');
+  }
+  return [...classes];
+}
+
+export function markVisible(el) {
+  el.classList.add(VISIBLE_CLASS);
+  el.dataset.velinVisible = 'true';
+}
+
+export function prefersReducedMotion() {
+  return (
+    typeof window !== 'undefined' &&
+    window.matchMedia &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+}

package/core/motion/index.js

@@ -0,0 +1,76 @@
+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';
+
+const MOTION_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.
+ * @param {object} [options]
+ * @param {HTMLElement|Document} [options.root]
+ * @param {string} [options.selector]
+ */
+export function initMotion(options = {}) {
+  const root = options.root || (typeof document !== 'undefined' ? document : null);
+  if (!root) return () => {};
+
+  const selector =
+    options.selector ||
+    [
+      '[velin-reveal]',
+      '[velin-fade]',
+      '[velin-slide]',
+      '[velin-scale]',
+      '[velin-parallax]',
+      '[velin-hover]',
+      '.velin-animate-on-scroll',
+    ].join(',');
+
+  const elements = root.querySelectorAll(selector);
+  const reduced = prefersReducedMotion();
+
+  for (const el of elements) {
+    if (el.dataset.velinMotionInit) continue;
+    el.dataset.velinMotionInit = '1';
+
+    const attrs = {};
+    for (const name of MOTION_ATTRS) {
+      if (el.hasAttribute(name)) attrs[name.replace('velin-', '')] = el.getAttribute(name) || 'true';
+    }
+    applyEffects(el, attrs);
+
+    if (reduced) {
+      markVisible(el);
+      continue;
+    }
+
+    const stop = observeInView(el, (node) => markVisible(node));
+    teardownFns.push(stop);
+  }
+
+  enhanceStagger(root);
+  bindSmoothScroll(root);
+
+  return () => {
+    teardownFns.forEach((fn) => fn());
+    teardownFns = [];
+    disconnectInViewObserver();
+  };
+}
+
+/** @deprecated use initMotion */
+export function initReveal(options = {}) {
+  return initMotion({
+    root: typeof document !== 'undefined' ? document : null,
+    selector: options.selector || '.velin-animate-on-scroll',
+  });
+}
+
+export const velinMotion = { init: initMotion, observe: observeInView, markVisible, VISIBLE_CLASS };
+export { observeInView, disconnectInViewObserver } from './scheduler.js';
+export { applyEffects, markVisible, prefersReducedMotion, VISIBLE_CLASS } from './effects.js';
+export { enhanceStagger, applyStagger } from './stagger.js';
+export { smoothScrollTo, bindSmoothScroll } from './scroll.js';

package/core/motion/scheduler.js

@@ -0,0 +1,72 @@
+const pending = new Set();
+let rafId = 0;
+
+export function scheduleInView(callback) {
+  pending.add(callback);
+  if (!rafId) {
+    rafId = requestAnimationFrame(() => {
+      rafId = 0;
+      const batch = [...pending];
+      pending.clear();
+      batch.forEach((fn) => fn());
+    });
+  }
+}
+
+let sharedObserver = null;
+const observed = new WeakMap();
+
+export function getInViewObserver(options = {}) {
+  if (typeof IntersectionObserver === 'undefined') return null;
+  if (!sharedObserver) {
+    sharedObserver = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (!entry.isIntersecting) continue;
+          const cb = observed.get(entry.target);
+          if (cb) scheduleInView(() => cb(entry.target));
+          const once = entry.target.dataset.velinOnce !== 'false';
+          if (once) sharedObserver.unobserve(entry.target);
+        }
+      },
+      {
+        threshold: options.threshold ?? 0.1,
+        rootMargin: options.rootMargin ?? '0px 0px -40px 0px',
+      },
+    );
+  }
+  return sharedObserver;
+}
+
+export function observeInView(el, onVisible, opts = {}) {
+  const reduced =
+    typeof window !== 'undefined' &&
+    window.matchMedia &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  const motionOff = el.closest('[data-velin-motion="off"]') || el.dataset.velinMotion === 'off';
+
+  if (reduced || motionOff) {
+    scheduleInView(() => onVisible(el, true));
+    return () => {};
+  }
+
+  const io = getInViewObserver(opts);
+  if (!io) {
+    scheduleInView(() => onVisible(el, true));
+    return () => {};
+  }
+
+  observed.set(el, onVisible);
+  io.observe(el);
+  return () => {
+    observed.delete(el);
+    io.unobserve(el);
+  };
+}
+
+export function disconnectInViewObserver() {
+  if (sharedObserver) {
+    sharedObserver.disconnect();
+    sharedObserver = null;
+  }
+}

package/core/motion/scroll.js

@@ -0,0 +1,32 @@
+export function smoothScrollTo(target, options = {}) {
+  const reduced =
+    typeof window !== 'undefined' &&
+    window.matchMedia &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  const el = typeof target === 'string' ? document.querySelector(target) : target;
+  if (!el) return;
+  el.scrollIntoView({
+    behavior: reduced || options.instant ? 'auto' : 'smooth',
+    block: options.block || 'start',
+    inline: options.inline || 'nearest',
+  });
+  if (el.tabIndex < 0 && !el.hasAttribute('tabindex')) {
+    el.setAttribute('tabindex', '-1');
+  }
+  el.focus({ preventScroll: true });
+}
+
+export function bindSmoothScroll(root = document) {
+  root.querySelectorAll('[velin-scroll]').forEach((link) => {
+    if (link.dataset.velinScrollBound) return;
+    link.dataset.velinScrollBound = '1';
+    link.addEventListener('click', (e) => {
+      const href = link.getAttribute('href');
+      if (!href || !href.startsWith('#')) return;
+      const target = document.querySelector(href);
+      if (!target) return;
+      e.preventDefault();
+      smoothScrollTo(target);
+    });
+  });
+}

package/core/motion/stagger.js

@@ -0,0 +1,24 @@
+const STAGGER_ATTR = 'velin-stagger';
+
+/**
+ * Apply stagger delay to direct children.
+ * @param {HTMLElement} listEl
+ * @param {string} [value] base delay ms or multiplier
+ */
+export function applyStagger(listEl, value = 'true') {
+  const base = value === 'true' || value === '' ? 60 : parseInt(value, 10) || 60;
+  const children = [...listEl.children];
+  children.forEach((child, i) => {
+    child.style.setProperty('--velin-stagger-delay', `${i * base}ms`);
+    child.classList.add('velin-stagger-item');
+  });
+  listEl.classList.add('velin-stagger');
+}
+
+export function enhanceStagger(root = document) {
+  root.querySelectorAll(`[${STAGGER_ATTR}]`).forEach((el) => {
+    if (el.dataset.velinStaggerDone) return;
+    el.dataset.velinStaggerDone = '1';
+    applyStagger(el, el.getAttribute(STAGGER_ATTR) || 'true');
+  });
+}

package/core/search/docs-url.js

@@ -0,0 +1,96 @@
+const DOCS_MOUNT = '/docs/';
+
+const DOC_ROOT_SEGMENTS = new Set([
+  'getting-started',
+  'extend',
+  'guides',
+  'utilities',
+  'components',
+  'forms',
+  'layout',
+  'content',
+  'customize',
+  'animations',
+  'about',
+  'helpers',
+  'generated',
+  'migration',
+]);
+
+/**
+ * Docs root URL (…/docs/) — stable even when <base> mis-resolves the script under …/components/assets/.
+ */
+export function getDocsBaseUrl() {
+  if (typeof document === 'undefined') {
+    return 'https://example.invalid/docs/';
+  }
+
+  const script = document.querySelector('script[src*="doc-search"]');
+  if (script?.src) {
+    const u = new URL(script.src);
+    const i = u.pathname.indexOf(DOCS_MOUNT);
+    if (i !== -1) {
+      return u.origin + u.pathname.slice(0, i + DOCS_MOUNT.length);
+    }
+  }
+
+  const path = window.location.pathname.replace(/\\/g, '/');
+  const idx = path.indexOf(DOCS_MOUNT);
+  if (idx >= 0) {
+    return new URL(path.slice(0, idx + DOCS_MOUNT.length), window.location.origin).href;
+  }
+
+  return new URL('./', window.location.href).href;
+}
+
+function splitUrlHash(url) {
+  const i = url.indexOf('#');
+  if (i === -1) return { path: url, hash: '' };
+  return { path: url.slice(0, i), hash: url.slice(i) };
+}
+
+/** Strip a mistaken current-section prefix (e.g. components/getting-started/…). */
+export function relativizeDocsPathname(pathname) {
+  const docsIdx = pathname.indexOf(DOCS_MOUNT);
+  if (docsIdx < 0) return null;
+  const rest = pathname.slice(docsIdx + DOCS_MOUNT.length);
+  const parts = rest.split('/').filter(Boolean);
+  if (
+    parts.length >= 2 &&
+    DOC_ROOT_SEGMENTS.has(parts[0]) &&
+    DOC_ROOT_SEGMENTS.has(parts[1]) &&
+    parts[0] !== parts[1]
+  ) {
+    return parts.slice(1).join('/');
+  }
+  return rest;
+}
+
+/**
+ * Resolve a search-index URL to a full navigable URL under the docs root.
+ * @param {string} url
+ */
+export function resolveDocsSearchUrl(url) {
+  if (!url || url === '#') return '';
+  if (typeof window === 'undefined') return url;
+
+  const { path, hash } = splitUrlHash(url);
+  if (!path) return hash || '';
+
+  let rel = path;
+  if (/^https?:\/\//i.test(path)) {
+    try {
+      const fixed = relativizeDocsPathname(new URL(path).pathname);
+      rel = fixed ?? path;
+    } catch {
+      return '';
+    }
+  }
+
+  try {
+    const target = new URL(rel || '', getDocsBaseUrl());
+    return target.href + (hash && !target.href.includes('#') ? hash : '');
+  } catch {
+    return '';
+  }
+}

package/core/search/engine.js

@@ -0,0 +1,139 @@
+import { CATEGORY_BOOST, normalizeEntry } from './types.js';
+
+/**
+ * Lightweight fuzzy/substring search engine (no external deps).
+ */
+export class VelinSearchEngine {
+  constructor() {
+    /** @type {import('./types.js').SearchEntry[]} */
+    this._entries = [];
+  }
+
+  /** @param {import('./types.js').SearchEntry[]} entries */
+  setEntries(entries) {
+    this._entries = entries.map((e) => normalizeEntry(e)).filter(Boolean);
+  }
+
+  /** @param {import('./types.js').SearchEntry[]} entries */
+  addEntries(entries) {
+    const next = entries.map((e) => normalizeEntry(e)).filter(Boolean);
+    const ids = new Set(this._entries.map((e) => e.id));
+    for (const e of next) {
+      if (!ids.has(e.id)) {
+        this._entries.push(e);
+        ids.add(e.id);
+      }
+    }
+  }
+
+  /**
+   * @param {string} query
+   * @param {object} [opts]
+   * @param {number} [opts.limit]
+   * @param {number} [opts.minChars]
+   * @param {number} [opts.fuzzy] 0–1 threshold for typo tolerance
+   * @param {import('./types.js').SearchCategory[]} [opts.categories]
+   */
+  query(query, opts = {}) {
+    const q = String(query || '').trim().toLowerCase();
+    const minChars = opts.minChars ?? 2;
+    const limit = opts.limit ?? 12;
+    const fuzzy = opts.fuzzy ?? 0.2;
+    const categories = opts.categories;
+
+    if (q.length < minChars) {
+      return { results: [], groups: {} };
+    }
+
+    const scored = [];
+    for (const entry of this._entries) {
+      if (categories && categories.length && !categories.includes(entry.category)) continue;
+      const s = scoreEntry(entry, q, fuzzy);
+      if (s > 0) scored.push({ entry, score: s });
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    const results = scored.slice(0, limit).map((x) => ({ ...x.entry, _score: x.score }));
+
+    /** @type {Record<string, typeof results>} */
+    const groups = {};
+    for (const r of results) {
+      if (!groups[r.category]) groups[r.category] = [];
+      groups[r.category].push(r);
+    }
+
+    return { results, groups };
+  }
+}
+
+/**
+ * @param {import('./types.js').SearchEntry} entry
+ * @param {string} q
+ * @param {number} fuzzy
+ */
+function scoreEntry(entry, q, fuzzy) {
+  const title = entry.title.toLowerCase();
+  const excerpt = (entry.excerpt || '').toLowerCase();
+  const keywords = (entry.keywords || []).join(' ').toLowerCase();
+  const boost = (CATEGORY_BOOST[entry.category] || 1) * (entry.weight || 1);
+
+  let score = 0;
+
+  if (title === q) score = 100;
+  else if (title.startsWith(q)) score = 70;
+  else if (title.includes(q)) score = 50;
+  else if (keywords.includes(q)) score = 35;
+  else if (excerpt.includes(q)) score = 25;
+  else if (fuzzy > 0 && fuzzyMatch(title, q, fuzzy)) score = 40;
+  else if (fuzzy > 0 && fuzzyMatch(keywords, q, fuzzy)) score = 28;
+  else if (fuzzy > 0 && fuzzyMatch(excerpt, q, fuzzy)) score = 18;
+  else if (subsequenceMatch(title, q)) score = 22;
+  else if (fuzzy > 0) {
+    for (const word of title.split(/[^a-z0-9]+/)) {
+      if (word.length >= 3 && fuzzyMatch(word, q, fuzzy)) {
+        score = 32;
+        break;
+      }
+    }
+  }
+
+  return score > 0 ? score * boost : 0;
+}
+
+function subsequenceMatch(haystack, needle) {
+  let j = 0;
+  for (let i = 0; i < haystack.length && j < needle.length; i++) {
+    if (haystack[i] === needle[j]) j++;
+  }
+  return j === needle.length;
+}
+
+/** Allow ~1 edit per 4 chars when fuzzy threshold met */
+function fuzzyMatch(text, query, threshold) {
+  if (!text || !query) return false;
+  if (text.includes(query)) return true;
+  if (subsequenceMatch(text, query)) return true;
+  const maxDist = Math.max(1, Math.floor(query.length * threshold * 2));
+  return levenshtein(text.slice(0, Math.min(text.length, query.length + 8)), query) <= maxDist;
+}
+
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  const dp = new Uint16Array((n + 1) * (m + 1));
+  for (let j = 0; j <= n; j++) dp[j] = j;
+  for (let i = 1; i <= m; i++) {
+    dp[i * (n + 1)] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i * (n + 1) + j] = Math.min(
+        dp[(i - 1) * (n + 1) + j] + 1,
+        dp[i * (n + 1) + (j - 1)] + 1,
+        dp[(i - 1) * (n + 1) + (j - 1)] + cost,
+      );
+    }
+  }
+  return dp[m * (n + 1) + n];
+}

package/core/search/highlight.js

@@ -0,0 +1,48 @@
+/**
+ * Escape HTML and wrap query matches in <mark class="velin-search-hit">.
+ * @param {string} text
+ * @param {string} query
+ * @returns {string}
+ */
+export function highlightHtml(text, query) {
+  const raw = String(text || '');
+  const q = String(query || '').trim();
+  if (!q || q.length < 2) return escapeHtml(raw);
+  const lower = raw.toLowerCase();
+  const ql = q.toLowerCase();
+  let start = lower.indexOf(ql);
+  let len = q.length;
+  if (start === -1) {
+    start = fuzzySubsequenceIndex(lower, ql);
+    if (start === -1) return escapeHtml(raw);
+    len = Math.min(q.length, raw.length - start);
+  }
+  return (
+    escapeHtml(raw.slice(0, start)) +
+    '<mark class="velin-search-hit">' +
+    escapeHtml(raw.slice(start, start + len)) +
+    '</mark>' +
+    escapeHtml(raw.slice(start + len))
+  );
+}
+
+function escapeHtml(s) {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/** @returns {number} start index of subsequence or -1 */
+function fuzzySubsequenceIndex(haystack, needle) {
+  let j = 0;
+  let start = -1;
+  for (let i = 0; i < haystack.length && j < needle.length; i++) {
+    if (haystack[i] === needle[j]) {
+      if (j === 0) start = i;
+      j++;
+    }
+  }
+  return j === needle.length ? start : -1;
+}

package/core/search/index.js

@@ -0,0 +1,126 @@
+import { VelinSearchEngine } from './engine.js';
+import { collectProviderEntries } from './providers.js';
+import { normalizeEntry, SEARCH_CATEGORIES } from './types.js';
+
+export { VelinSearchEngine } from './engine.js';
+export { highlightHtml } from './highlight.js';
+export { registerSearchProvider, unregisterSearchProvider, listSearchProviders } from './providers.js';
+export { SEARCH_CATEGORIES, CATEGORY_BOOST, normalizeEntry } from './types.js';
+export { getDocsBaseUrl, resolveDocsSearchUrl, relativizeDocsPathname } from './docs-url.js';
+
+const defaultEngine = new VelinSearchEngine();
+let indexLoaded = false;
+
+/**
+ * @param {import('./types.js').SearchEntry[]|{ entries?: import('./types.js').SearchEntry[] }} data
+ */
+function parseIndexPayload(data) {
+  if (Array.isArray(data)) return data;
+  if (data && Array.isArray(data.entries)) return data.entries;
+  return [];
+}
+
+/**
+ * Singleton search API.
+ */
+export const velinSearch = {
+  engine: defaultEngine,
+
+  /**
+   * Load JSON index from URL (offline after fetch) or pass entries directly.
+   * @param {string|import('./types.js').SearchEntry[]} source
+   */
+  async loadIndex(source) {
+    let entries = [];
+    if (typeof source === 'string') {
+      const res = await fetch(source);
+      if (!res.ok) throw new Error(`Failed to load search index: ${res.status}`);
+      entries = parseIndexPayload(await res.json());
+    } else if (Array.isArray(source)) {
+      entries = source;
+    }
+    defaultEngine.setEntries(entries);
+    const providerEntries = await collectProviderEntries();
+    if (providerEntries.length) defaultEngine.addEntries(providerEntries);
+    indexLoaded = true;
+    return entries.length;
+  },
+
+  /**
+   * Merge entries without replacing the full index.
+   * @param {import('./types.js').SearchEntry[]} entries
+   */
+  addEntries(entries) {
+    defaultEngine.addEntries(entries);
+  },
+
+  /**
+   * Refresh entries from registered providers.
+   */
+  async refreshProviders() {
+    const providerEntries = await collectProviderEntries();
+    if (providerEntries.length) defaultEngine.addEntries(providerEntries);
+    return providerEntries.length;
+  },
+
+  /**
+   * @param {string} query
+   * @param {object} [options]
+   */
+  async query(query, options = {}) {
+    if (!indexLoaded && defaultEngine._entries.length === 0) {
+      await this.refreshProviders();
+    }
+    return defaultEngine.query(query, options);
+  },
+
+  isReady() {
+    return indexLoaded || defaultEngine._entries.length > 0;
+  },
+};
+
+/**
+ * Create an isolated search instance (for multiple widgets).
+ */
+/**
+ * @param {{ worker?: boolean, workerUrl?: string }} [config]
+ */
+export function createSearch(config = {}) {
+  const engine = new VelinSearchEngine();
+  const wantWorker = config.worker === true;
+  let workerClient = null;
+
+  async function getWorker() {
+    if (!wantWorker || workerClient) return workerClient;
+    if (typeof Worker === 'undefined') return null;
+    const { createSearchWorker } = await import('./worker-client.js');
+    workerClient = createSearchWorker(config.workerUrl);
+    return workerClient;
+  }
+
+  return {
+    engine,
+    async loadIndex(source) {
+      let entries = [];
+      if (typeof source === 'string') {
+        const res = await fetch(source);
+        entries = parseIndexPayload(await res.json());
+      } else if (Array.isArray(source)) {
+        entries = source;
+      }
+      engine.setEntries(entries);
+      const w = await getWorker();
+      if (w) await w.setEntries(engine._entries);
+      return entries.length;
+    },
+    async query(q, opts) {
+      const w = await getWorker();
+      if (w) return w.query(q, opts);
+      return engine.query(q, opts);
+    },
+    addEntries(entries) {
+      engine.addEntries(entries);
+      void getWorker().then((w) => w?.setEntries(engine._entries));
+    },
+  };
+}