@birdapi/velinstyle 0.8.0 → 0.9.0

package/core/highlight/types.js

@@ -0,0 +1,28 @@
+/** @typedef {'keyword'|'identifier'|'string'|'comment'|'number'|'operator'|'punctuation'|'tag'|'attr-name'|'attr-value'|'builtin'|'regex'|'plain'} TokenType */
+
+/**
+ * @typedef {object} Token
+ * @property {TokenType} type
+ * @property {string} value
+ */
+
+/** @type {TokenType[]} */
+export const TOKEN_TYPES = [
+  'keyword',
+  'identifier',
+  'string',
+  'comment',
+  'number',
+  'operator',
+  'punctuation',
+  'tag',
+  'attr-name',
+  'attr-value',
+  'builtin',
+  'regex',
+  'plain',
+];
+
+/**
+ * @typedef {(code: string) => Token[]} LexerFn
+ */

package/core/meta/build.js

@@ -0,0 +1,293 @@
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join, basename } from 'path';
+import {
+  VELIN_META_MIME,
+  VELIN_AGENT_SCHEMA_VERSION,
+  AGENT_CONVENTIONS,
+} from './schema.js';
+import { relativizeDocsPathname } from '../search/docs-url.js';
+
+/**
+ * @param {string} pkgRoot
+ */
+export function readPackageMeta(pkgRoot) {
+  const pkgPath = join(pkgRoot, 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  const exports = Object.keys(pkg.exports || {});
+  return {
+    name: pkg.name,
+    version: pkg.version,
+    homepage: pkg.homepage,
+    repository: typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url,
+    exports,
+  };
+}
+
+const LEGACY_WC_SUFFIX = '-wc';
+
+/**
+ * @param {string} pkgRoot
+ * @returns {{ canonical: string[], legacyAliases: string[], loaderTags: string[] }}
+ */
+export function collectComponentTags(pkgRoot) {
+  const loadersPath = join(pkgRoot, 'components', 'runtime', 'component-loaders.js');
+  if (existsSync(loadersPath)) {
+    const src = readFileSync(loadersPath, 'utf-8');
+    const loaderTags = [...new Set([...src.matchAll(/'((velin-[a-z0-9-]+))':/g)].map((m) => m[1]))].sort();
+    const legacyAliases = loaderTags.filter((t) => t.endsWith(LEGACY_WC_SUFFIX));
+    const canonical = loaderTags.filter((t) => !t.endsWith(LEGACY_WC_SUFFIX));
+    return { canonical, legacyAliases, loaderTags };
+  }
+  const dir = join(pkgRoot, 'components');
+  if (!existsSync(dir)) return { canonical: [], legacyAliases: [], loaderTags: [] };
+  const canonical = readdirSync(dir)
+    .filter((f) => f.startsWith('velin-') && f.endsWith('.js') && !f.includes('runtime'))
+    .map((f) => basename(f, '.js'))
+    .filter((t) => !t.endsWith(LEGACY_WC_SUFFIX))
+    .sort();
+  return { canonical, legacyAliases: [], loaderTags: canonical };
+}
+
+/**
+ * JS helpers shipped under components/ but not registered as custom elements.
+ * @param {string} pkgRoot
+ */
+export function collectHelperModules(pkgRoot) {
+  const helpers = ['velin-flip', 'velin-haptic', 'velin-reveal'];
+  return helpers.filter((name) => existsSync(join(pkgRoot, 'components', `${name}.js`)));
+}
+
+/**
+ * @param {string} html
+ * @param {string} [sourcePath]
+ * @param {string} [pkgRoot]
+ */
+export function buildPageMeta(html, sourcePath = '', pkgRoot = '.') {
+  const components = new Set();
+  const classes = new Set();
+  const attributes = new Set();
+
+  for (const m of html.matchAll(/<(velin-[a-z0-9-]+)/gi)) {
+    components.add(m[1].toLowerCase());
+  }
+  for (const m of html.matchAll(/\b(velin-[a-z0-9-]+)/gi)) {
+    classes.add(m[1].toLowerCase());
+  }
+  for (const m of html.matchAll(/\b(velin-[a-z]+)(?:\s*=|(?=\s|>))/gi)) {
+    const name = m[1].toLowerCase();
+    if (!name.includes('-wc')) attributes.add(name);
+  }
+
+  const intent = sourcePath.includes('components/')
+    ? 'component-doc'
+    : sourcePath.includes('guides/')
+      ? 'guide'
+      : 'page';
+
+  return {
+    version: readPackageMeta(pkgRoot).version || '0.9.0',
+    mime: VELIN_META_MIME,
+    page: {
+      intent,
+      source: sourcePath || undefined,
+    },
+    allowed: {
+      classesPrefix: ['velin-'],
+      components: [...components].sort(),
+      sampleClasses: [...classes].sort().slice(0, 48),
+    },
+    attributes: [...attributes].sort(),
+    a11y: [
+      'Use semantic HTML inside Velin components.',
+      'Provide labels for interactive controls.',
+      'Respect prefers-reduced-motion; Velin motion attributes honor it.',
+    ],
+  };
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.pkgRoot
+ * @param {string} [options.searchIndexPath]
+ * @param {import('./schema.js').VelinAgentBundle} [options.partial]
+ */
+export async function buildAgentBundle(options) {
+  const { pkgRoot } = options;
+  const pkg = readPackageMeta(pkgRoot);
+  const { canonical, legacyAliases, loaderTags } = collectComponentTags(pkgRoot);
+  const helpers = collectHelperModules(pkgRoot);
+
+  let attributes = [];
+  try {
+    const { listRegisteredAttributes } = await import('../attributes/registry.js');
+    attributes = listRegisteredAttributes().sort();
+  } catch {
+    /* registry may need DOM in some environments */
+  }
+
+  let cliCommands = [];
+  try {
+    const { loadCliManifest } = await import('../../cli/docgen/extract-cli.js');
+    cliCommands = loadCliManifest().commands || [];
+  } catch {
+    const manifestPath = join(pkgRoot, 'cli', 'cli-manifest.json');
+    if (existsSync(manifestPath)) {
+      cliCommands = JSON.parse(readFileSync(manifestPath, 'utf-8')).commands || [];
+    }
+  }
+
+  let scannerRuleCount = 0;
+  let a11yContracts = { wcagLevel: 'AAA', components: {} };
+  try {
+    const { SCANNER_RULES } = await import('../../cli/scanner-rules-data.js');
+    scannerRuleCount = SCANNER_RULES.length;
+  } catch {
+    /* optional */
+  }
+  try {
+    const contractsPath = join(pkgRoot, 'core', 'a11y', 'component-contracts.json');
+    if (existsSync(contractsPath)) {
+      a11yContracts = JSON.parse(readFileSync(contractsPath, 'utf-8'));
+    }
+  } catch {
+    /* optional */
+  }
+
+  const searchPath = options.searchIndexPath || join(pkgRoot, 'dist', 'search-index.json');
+  let entryCount;
+  if (existsSync(searchPath)) {
+    try {
+      const idx = JSON.parse(readFileSync(searchPath, 'utf-8'));
+      entryCount = Array.isArray(idx.entries) ? idx.entries.length : undefined;
+    } catch {
+      /* ignore */
+    }
+  }
+
+  const bundle = {
+    schemaVersion: VELIN_AGENT_SCHEMA_VERSION,
+    mime: VELIN_META_MIME,
+    generatedAt: new Date().toISOString(),
+    framework: {
+      name: pkg.name,
+      version: pkg.version,
+      homepage: pkg.homepage,
+      repository: pkg.repository,
+      tagline:
+        'VelinStyle is the WCAG 2.2 AAA CSS framework with native JavaScript runtime and Web Components.',
+    },
+    packageExports: pkg.exports,
+    release: {
+      breaking: [
+        'Canonical tags: velin-tooltip, velin-stepper (legacy *-wc aliases deprecated).',
+        '.velin-mb-* is margin-bottom only; use .velin-my-* for block axis.',
+      ],
+      migration: [
+        'Replace velin-tooltip-wc / velin-stepper-wc with velin-tooltip / velin-stepper.',
+        'Point AI tools at velin-agent.json or docs/llms.txt for framework context.',
+      ],
+    },
+    components: {
+      tags: canonical,
+      count: canonical.length,
+      loaderTags,
+      loaderCount: loaderTags.length,
+      legacyAliases,
+      helpers,
+    },
+    attributes: { names: attributes, count: attributes.length },
+    cli: { commands: cliCommands },
+    tooling: {
+      categories: ['scan', 'prefix', 'scaffold', 'layout', 'perf', 'tokens', 'docs', 'search', 'meta'],
+      scannerRuleCount,
+    },
+    a11y: {
+      wcagLevel: a11yContracts.wcagLevel || 'AAA',
+      modules: 'src/a11y/*.css',
+      matrix: 'docs/generated/a11y/wcag22-aaa-matrix.md',
+      componentContracts: a11yContracts.components,
+      init: "import { initA11y } from '@birdapi/velinstyle/a11y'; initA11y();",
+    },
+    searchIndex: {
+      path: 'dist/search-index.json',
+      entryCount,
+    },
+    documentation: {
+      generated: 'docs/generated/',
+      guides: {
+        velinMeta: 'docs/guides/velin-meta.html',
+        velinSearch: 'docs/guides/velin-search.html',
+        syntaxHighlight: 'docs/guides/syntax-highlight.html',
+        promptScaffolding: 'docs/guides/prompt-scaffolding.html',
+        apiReference: 'docs/guides/api-reference.html',
+      },
+      agentFiles: {
+        json: 'dist/velin-agent.json',
+        llmsTxt: 'dist/llms.txt',
+      },
+    },
+    conventions: AGENT_CONVENTIONS,
+    ...options.partial,
+  };
+
+  return bundle;
+}
+
+/**
+ * @param {object} bundle
+ * @param {string} [baseUrl]
+ */
+export function buildLlmsTxt(bundle, baseUrl = 'https://velinstyle.info') {
+  const tagline =
+    bundle.framework.tagline ||
+    'VelinStyle is the WCAG 2.2 AAA CSS framework with native JavaScript runtime and Web Components.';
+  const lines = [
+    `# VelinStyle ${bundle.framework.version}`,
+    '',
+    `> ${tagline}`,
+    `> Full machine context: ${baseUrl}/dist/velin-agent.json`,
+    `> MIME: ${VELIN_META_MIME}`,
+    '',
+    '## Framework',
+    `- npm: ${bundle.framework.name}`,
+    `- ${tagline}`,
+    `- Components: ${bundle.components.count} canonical Web Components (\`velin-*\`); ${bundle.components.loaderCount ?? bundle.components.count} lazy-loader entries`,
+    `- HTML attributes: ${bundle.attributes.count} \`velin-*\` bridges`,
+    `- CLI: velinstyle (scan, scaffold, docs generate, search index, meta)`,
+    '',
+    '## Conventions',
+    ...bundle.conventions.map((c) => `- ${c}`),
+    '',
+    '## Key guides',
+    `- [Velin-Meta](${baseUrl}/docs/guides/velin-meta.html)`,
+    `- [VelinSearch](${baseUrl}/docs/guides/velin-search.html)`,
+    `- [Syntax highlighting](${baseUrl}/docs/guides/syntax-highlight.html)`,
+    `- [Prompt scaffolding](${baseUrl}/docs/guides/prompt-scaffolding.html)`,
+    `- [API reference (generated)](${baseUrl}/docs/guides/api-reference.html)`,
+    '',
+    '## Generated reference',
+    `- [Components index](${baseUrl}/docs/generated/components/)`,
+    `- [Tokens](${baseUrl}/docs/generated/tokens/)`,
+    `- [Utilities](${baseUrl}/docs/generated/utilities/)`,
+    `- [CLI commands](${baseUrl}/docs/generated/cli/commands.md)`,
+    '',
+    '## Usage for agents',
+    '```',
+    'npx velinstyle meta',
+    'npx velinstyle docs generate',
+    'npx velinstyle search index',
+    '```',
+    '',
+  ];
+  return lines.join('\n');
+}
+
+/**
+ * Serialize page meta for embedding in HTML.
+ * @param {object} meta
+ */
+export function serializePageMetaScript(meta) {
+  return `<script type="${VELIN_META_MIME}" id="velin-meta">\n${JSON.stringify(meta, null, 2)}\n</script>`;
+}
+
+export { relativizeDocsPathname };

package/core/meta/index.js

@@ -0,0 +1,17 @@
+export {
+  VELIN_META_MIME,
+  VELIN_AGENT_SCHEMA_VERSION,
+  DOC_ROOT_SEGMENTS,
+  AGENT_CONVENTIONS,
+} from './schema.js';
+
+export {
+  buildAgentBundle,
+  buildLlmsTxt,
+  buildPageMeta,
+  serializePageMetaScript,
+  readPackageMeta,
+  collectComponentTags,
+  collectHelperModules,
+  relativizeDocsPathname,
+} from './build.js';

package/core/meta/schema.js

@@ -0,0 +1,49 @@
+/** Velin-Meta MIME and JSON shape for agent consumption. */
+
+export const VELIN_META_MIME = 'application/vnd.velinstyle.meta+json';
+
+export const VELIN_AGENT_SCHEMA_VERSION = 1;
+
+/** Top-level doc sections under /docs/ used to fix wrongly prefixed paths. */
+export const DOC_ROOT_SEGMENTS = new Set([
+  'getting-started',
+  'extend',
+  'guides',
+  'utilities',
+  'components',
+  'forms',
+  'layout',
+  'content',
+  'customize',
+  'animations',
+  'about',
+  'helpers',
+  'generated',
+  'migration',
+]);
+
+/**
+ * @typedef {Object} VelinAgentBundle
+ * @property {number} schemaVersion
+ * @property {string} mime
+ * @property {string} generatedAt
+ * @property {{ name: string, version: string, homepage?: string, repository?: string }} framework
+ * @property {string[]} packageExports
+ * @property {{ breaking?: string[], migration?: string[] }} release
+ * @property {{ tags: string[], count: number }} components
+ * @property {{ names: string[], count: number }} attributes
+ * @property {{ commands: object[] }} cli
+ * @property {{ categories: string[], scannerRuleCount: number }} tooling
+ * @property {{ path: string, entryCount?: number }} searchIndex
+ * @property {{ generated: string, guides: Record<string, string> }} documentation
+ * @property {string[]} conventions
+ */
+
+export const AGENT_CONVENTIONS = [
+  'Positioning: VelinStyle is the WCAG 2.2 AAA CSS framework with native JavaScript runtime and Web Components — not a JS-only library or a utility-only CSS kit.',
+  'Use only velin-* utility classes and documented Web Components.',
+  'Prefer data-velin-theme on <html> for theme switching.',
+  'Run velinstyle scan on generated HTML before shipping.',
+  'Do not put secrets, API keys, or raw emails in velin-meta or page meta.',
+  'Resolve doc links against docs root (/docs/), not the current page folder.',
+];

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