@birdapi/velinstyle 0.8.0 → 0.9.0

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

package/core/search/providers.js

@@ -0,0 +1,36 @@
+/** @typedef {() => import('./types.js').SearchEntry[]|Promise<import('./types.js').SearchEntry[]>} SearchProviderFn */
+
+/** @type {Map<string, SearchProviderFn>} */
+const providers = new Map();
+
+/**
+ * Register a custom search content provider (API hook for developers).
+ * @param {string} id
+ * @param {SearchProviderFn} fn
+ */
+export function registerSearchProvider(id, fn) {
+  if (!id || typeof fn !== 'function') {
+    throw new Error('registerSearchProvider(id, fn) requires a non-empty id and function');
+  }
+  providers.set(id, fn);
+}
+
+export function unregisterSearchProvider(id) {
+  providers.delete(id);
+}
+
+export function listSearchProviders() {
+  return [...providers.keys()];
+}
+
+/**
+ * @returns {Promise<import('./types.js').SearchEntry[]>}
+ */
+export async function collectProviderEntries() {
+  const all = [];
+  for (const fn of providers.values()) {
+    const chunk = await fn();
+    if (Array.isArray(chunk)) all.push(...chunk);
+  }
+  return all;
+}

package/core/search/types.js

@@ -0,0 +1,61 @@
+import { sanitizeSearchUrl } from '../../components/sanitize.js';
+
+/** @typedef {'docs'|'components'|'api'|'examples'} SearchCategory */
+
+/**
+ * @typedef {Object} SearchEntry
+ * @property {string} id
+ * @property {string} title
+ * @property {string} [excerpt]
+ * @property {string} url
+ * @property {SearchCategory} category
+ * @property {string[]} [keywords]
+ * @property {number} [weight]
+ */
+
+export const SEARCH_CATEGORIES = /** @type {const} */ (['docs', 'components', 'api', 'examples']);
+
+export const CATEGORY_BOOST = {
+  components: 1.25,
+  api: 1.15,
+  docs: 1,
+  examples: 0.9,
+};
+
+/**
+ * @param {unknown} entry
+ * @returns {SearchEntry|null}
+ */
+export function normalizeEntry(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const e = /** @type {Record<string, unknown>} */ (entry);
+  const id = String(e.id || e.url || e.title || '').trim();
+  const title = String(e.title || '').trim();
+  const url = String(e.url || '').trim();
+  if (!id || !title) return null;
+  const keywords = Array.isArray(e.keywords)
+    ? e.keywords.map((k) => String(k))
+    : typeof e.keywords === 'string'
+      ? e.keywords.split(/\s+/).filter(Boolean)
+      : [];
+  let category = /** @type {SearchCategory} */ (
+    SEARCH_CATEGORIES.includes(/** @type {SearchCategory} */ (e.category))
+      ? e.category
+      : 'docs'
+  );
+  if (!e.category && typeof e.url === 'string') {
+    if (e.url.includes('/components/')) category = 'components';
+    else if (e.url.includes('/cli/') || e.url.includes('/api/')) category = 'api';
+    else if (e.url.includes('samples/') || e.url.includes('examples/')) category = 'examples';
+  }
+  const safeUrl = url ? sanitizeSearchUrl(url) : `#${id}`;
+  return {
+    id,
+    title,
+    excerpt: String(e.excerpt || e.section || '').slice(0, 200),
+    url: safeUrl,
+    category: /** @type {SearchCategory} */ (category),
+    keywords,
+    weight: typeof e.weight === 'number' ? e.weight : 1,
+  };
+}

package/core/search/worker-client.js

@@ -0,0 +1,56 @@
+let _nextId = 0;
+
+/**
+ * @param {string} [workerUrl]
+ */
+export function createSearchWorker(workerUrl) {
+  if (typeof Worker === 'undefined') return null;
+
+  const url =
+    workerUrl ||
+    new URL('./worker.js', import.meta.url).href;
+
+  let worker;
+  try {
+    worker = new Worker(url, { type: 'module' });
+  } catch {
+    return null;
+  }
+
+  /** @type {Map<number, { resolve: Function, reject: Function }>} */
+  const pending = new Map();
+
+  worker.onmessage = (e) => {
+    const { id, ok, result, error } = e.data || {};
+    const p = pending.get(id);
+    if (!p) return;
+    pending.delete(id);
+    if (ok) p.resolve(result);
+    else p.reject(new Error(error || 'Worker error'));
+  };
+
+  worker.onerror = () => {
+    for (const p of pending.values()) p.reject(new Error('Worker failed'));
+    pending.clear();
+  };
+
+  function send(type, payload) {
+    const id = ++_nextId;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject });
+      worker.postMessage({ id, type, payload });
+    });
+  }
+
+  return {
+    setEntries(entries) {
+      return send('setEntries', { entries });
+    },
+    query(query, options) {
+      return send('query', { query, options });
+    },
+    terminate() {
+      worker.terminate();
+    },
+  };
+}

package/core/search/worker.js

@@ -0,0 +1,20 @@
+import { VelinSearchEngine } from './engine.js';
+
+const engine = new VelinSearchEngine();
+
+self.onmessage = (event) => {
+  const { id, type, payload } = event.data || {};
+  try {
+    if (type === 'setEntries') {
+      engine.setEntries(payload.entries || []);
+      self.postMessage({ id, ok: true });
+    } else if (type === 'query') {
+      const result = engine.query(payload.query, payload.options || {});
+      self.postMessage({ id, ok: true, result });
+    } else {
+      self.postMessage({ id, ok: false, error: 'Unknown message type' });
+    }
+  } catch (err) {
+    self.postMessage({ id, ok: false, error: String(err?.message || err) });
+  }
+};

package/dist/chunks/a11y-utils-IRC7LOPF.js

@@ -0,0 +1,16 @@
+import {
+  announce,
+  ensureAriaLabel,
+  getAnnouncer,
+  liveDotLabel,
+  respectReducedMotion,
+  syncExpanded
+} from "./chunk-Z4JYQ2XX.js";
+export {
+  announce,
+  ensureAriaLabel,
+  getAnnouncer,
+  liveDotLabel,
+  respectReducedMotion,
+  syncExpanded
+};