@birdapi/velinstyle 0.7.0 → 0.9.0

package/core/highlight/languages/shell.js

@@ -0,0 +1,33 @@
+/** @import { LexerFn } from '../types.js' */
+import { tokenizeWithKeywords } from './_utils.js';
+
+const KEYWORDS = {
+  if: 1,
+  then: 1,
+  else: 1,
+  fi: 1,
+  for: 1,
+  do: 1,
+  done: 1,
+  while: 1,
+  case: 1,
+  esac: 1,
+  function: 1,
+  return: 1,
+  export: 1,
+  local: 1,
+};
+
+const RULES = [
+  { type: 'comment', re: /#[^\n]*/y },
+  { type: 'string', re: /"(?:\\.|[^"\\])*"/y },
+  { type: 'string', re: /'[^']*'/y },
+  { type: 'number', re: /\b\d+\b/y },
+  { type: 'operator', re: /[|&<>]/y },
+  { type: 'punctuation', re: /[();]/y },
+];
+
+/** @type {LexerFn} */
+export default function lexShell(code) {
+  return tokenizeWithKeywords(code, KEYWORDS, RULES);
+}

package/core/highlight/languages/sql.js

@@ -0,0 +1,20 @@
+/** @import { LexerFn } from '../types.js' */
+import { tokenize } from './_utils.js';
+
+const RULES = [
+  { type: 'comment', re: /--[^\n]*/y },
+  { type: 'comment', re: /\/\*[\s\S]*?\*\//y },
+  { type: 'string', re: /'(?:''|[^'])*'/y },
+  { type: 'number', re: /\b\d+(?:\.\d+)?\b/y },
+  {
+    type: 'keyword',
+    re: /\b(?:SELECT|FROM|WHERE|INSERT|INTO|VALUES|UPDATE|SET|DELETE|JOIN|LEFT|RIGHT|INNER|OUTER|ON|AND|OR|NOT|NULL|AS|ORDER|BY|GROUP|HAVING|LIMIT|CREATE|TABLE|INDEX)\b/yi,
+  },
+  { type: 'operator', re: /[=<>!]+|,/y },
+  { type: 'punctuation', re: /[();]/y },
+];
+
+/** @type {LexerFn} */
+export default function lexSql(code) {
+  return tokenize(code, RULES);
+}

package/core/highlight/languages/typescript.js

@@ -0,0 +1,28 @@
+/** @import { LexerFn } from '../types.js' */
+import lexJs from './js.js';
+
+const TS_KEYWORDS = new Set([
+  'type',
+  'interface',
+  'enum',
+  'implements',
+  'declare',
+  'namespace',
+  'readonly',
+  'public',
+  'private',
+  'protected',
+  'abstract',
+  'as',
+  'satisfies',
+  'keyof',
+]);
+
+/** @type {LexerFn} */
+export default function lexTypeScript(code) {
+  return lexJs(code).map((t) =>
+    t.type === 'identifier' && TS_KEYWORDS.has(t.value)
+      ? { type: 'keyword', value: t.value }
+      : t,
+  );
+}

package/core/highlight/observe.js

@@ -0,0 +1,53 @@
+import { highlightElement } from './highlight.js';
+import { observeInView } from '../motion/scheduler.js';
+
+/**
+ * Lazy-highlight code blocks when they enter the viewport.
+ * @param {ParentNode} [root]
+ * @param {object} [options]
+ * @param {string} [options.selector]
+ * @param {boolean} [options.immediate]
+ */
+export function initHighlight(root = document, options = {}) {
+  if (typeof document === 'undefined') return () => {};
+
+  const selector =
+    options.selector ||
+    [
+      'pre[velin-code]',
+      'pre[language]',
+      'pre[data-language]',
+      'pre code[class*="language-"]',
+      'velin-code-block pre',
+      '.velin-doc-example__code pre',
+    ].join(',');
+
+  const nodes = root.querySelectorAll(selector);
+  const teardowns = [];
+
+  const reduced =
+    typeof matchMedia !== 'undefined' &&
+    matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  for (const node of nodes) {
+    const pre = node.tagName === 'PRE' ? node : node.closest('pre');
+    if (!pre || pre.dataset.velinObserve === '1') continue;
+    pre.dataset.velinObserve = '1';
+
+    if (reduced || options.immediate) {
+      void highlightElement(pre);
+      continue;
+    }
+
+    pre.classList.add('velin-syntax-pending');
+    const stop = observeInView(pre, async (el) => {
+      await highlightElement(el);
+    });
+    teardowns.push(stop);
+  }
+
+  return () => teardowns.forEach((fn) => fn());
+}
+
+/** @deprecated alias */
+export const observeCodeBlocks = initHighlight;

package/core/highlight/registry.js

@@ -0,0 +1,107 @@
+/** @import { LexerFn } from './types.js' */
+
+/** @type {Map<string, LexerFn>} */
+const languages = new Map();
+
+/** @type {Map<string, Promise<LexerFn>>} */
+const loading = new Map();
+
+const LAZY_LOADERS = {
+  js: () => import('./languages/js.js'),
+  javascript: () => import('./languages/js.js'),
+  ts: () => import('./languages/typescript.js'),
+  typescript: () => import('./languages/typescript.js'),
+  html: () => import('./languages/html.js'),
+  xml: () => import('./languages/html.js'),
+  css: () => import('./languages/css.js'),
+  json: () => import('./languages/json.js'),
+  md: () => import('./languages/markdown.js'),
+  markdown: () => import('./languages/markdown.js'),
+  shell: () => import('./languages/shell.js'),
+  bash: () => import('./languages/shell.js'),
+  sh: () => import('./languages/shell.js'),
+  sql: () => import('./languages/sql.js'),
+  text: () => import('./languages/plain.js'),
+  plain: () => import('./languages/plain.js'),
+  txt: () => import('./languages/plain.js'),
+  markup: () => import('./languages/html.js'),
+  console: () => import('./languages/plain.js'),
+  php: () => import('./languages/php.js'),
+  blade: () => import('./languages/blade.js'),
+};
+
+/** @param {string} name */
+export function normalizeLanguage(name) {
+  const n = (name || '').trim().toLowerCase();
+  if (!n) return '';
+  if (n.startsWith('language-')) return normalizeLanguage(n.slice(9));
+  const map = {
+    javascript: 'js',
+    jsx: 'js',
+    typescript: 'ts',
+    tsx: 'ts',
+    markup: 'html',
+    xml: 'html',
+    svg: 'html',
+    bash: 'shell',
+    sh: 'shell',
+    zsh: 'shell',
+    md: 'markdown',
+    plaintext: 'text',
+    'plain-text': 'text',
+    yml: 'text',
+    yaml: 'text',
+    toml: 'text',
+    ini: 'text',
+    php8: 'php',
+  };
+  return map[n] || n;
+}
+
+/**
+ * @param {string} name
+ * @param {LexerFn} lexerFn
+ */
+export function registerLanguage(name, lexerFn) {
+  languages.set(normalizeLanguage(name), lexerFn);
+}
+
+/**
+ * @param {string} name
+ * @returns {LexerFn|undefined}
+ */
+export function getLanguage(name) {
+  return languages.get(normalizeLanguage(name));
+}
+
+/**
+ * @param {string} name
+ * @returns {Promise<LexerFn|undefined>}
+ */
+export async function lazyLoadLanguage(name) {
+  const key = normalizeLanguage(name);
+  if (!key) return undefined;
+  if (languages.has(key)) return languages.get(key);
+  if (loading.has(key)) return loading.get(key);
+
+  const loader = LAZY_LOADERS[key];
+  if (!loader) return undefined;
+
+  const p = loader().then((mod) => {
+    const fn = mod.default;
+    languages.set(key, fn);
+    loading.delete(key);
+    return fn;
+  });
+  loading.set(key, p);
+  return p;
+}
+
+/** @returns {string[]} */
+export function listLanguages() {
+  return [...new Set([...languages.keys(), ...Object.keys(LAZY_LOADERS)])];
+}
+
+// Eager-register JS for zero-config demos
+import lexJs from './languages/js.js';
+registerLanguage('js', lexJs);

package/core/highlight/render.js

@@ -0,0 +1,35 @@
+/** @import { Token } from './types.js' */
+
+const ESC = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' };
+
+/**
+ * @param {string} s
+ */
+export function escapeHtml(s) {
+  return s.replace(/[&<>"]/g, (c) => ESC[c] || c);
+}
+
+/**
+ * @param {Token[]} tokens
+ * @returns {string}
+ */
+export function renderTokens(tokens) {
+  return tokens
+    .map((t) => {
+      const type = t.type === 'plain' ? '' : t.type;
+      const cls = type ? `velin-token velin-token--${type}` : 'velin-token';
+      return `<span class="${cls}">${escapeHtml(t.value)}</span>`;
+    })
+    .join('');
+}
+
+/**
+ * @param {HTMLElement} codeEl
+ * @param {Token[]} tokens
+ */
+export function applyHighlight(codeEl, tokens) {
+  codeEl.innerHTML = renderTokens(tokens);
+  codeEl.classList.add('velin-syntax-ready');
+  codeEl.closest('pre')?.classList.add('velin-syntax-ready');
+  codeEl.closest('.velin-code-block')?.classList.add('velin-syntax-ready');
+}

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.',
+];