@birdapi/velinstyle 1.0.0 → 1.2.0

package/cli/docgen/extract-components.js

@@ -111,11 +111,61 @@ export function extractComponents(componentsDir) {
   return sortByKey(items, 'tag');
 }
 
+const MINIMAL_EXAMPLES = {
+  'velin-copy': `<velin-copy value="npm i @birdapi/velinstyle" label="Copy"></velin-copy>
+<!-- Shadow button is built-in. Prefer value= or text= (or data-source). Do not use data-velin-copy. -->`,
+  'velin-tooltip': `<velin-tooltip content="Save draft">
+  <button type="button" class="velin-btn">Save</button>
+</velin-tooltip>`,
+  'velin-lightbox': `<velin-lightbox>
+  <a href="photo.jpg"><img src="photo-thumb.jpg" alt="Gallery photo"></a>
+</velin-lightbox>`,
+  'velin-icon': `<!-- Set <meta name="velin-icon-sprite" content="vendor/velinstyle/velin-icons.svg"> once -->
+<velin-icon name="check" size="20" label="Done"></velin-icon>`,
+  'velin-command': `<velin-command>
+  <input slot="input" type="search" class="velin-input" placeholder="Jump to…" aria-label="Command">
+  <button type="button" data-velin-command-item value="home">Home</button>
+  <button type="button" data-velin-command-item value="settings">Settings</button>
+</velin-command>`,
+  'velin-menubar': `<velin-menubar>
+  <button type="button" data-velin-menubar-trigger>File</button>
+  <div data-velin-menubar-panel hidden>
+    <button type="button" role="menuitem">New</button>
+    <button type="button" role="menuitem">Open</button>
+  </div>
+</velin-menubar>`,
+  'velin-form-summary': `<form novalidate>
+  <velin-form-summary></velin-form-summary>
+  <label class="velin-label" for="email">Email</label>
+  <input id="email" class="velin-input" type="email" required>
+  <button type="submit" class="velin-btn velin-btn--primary">Send</button>
+</form>`,
+  'velin-data-table': `<velin-data-table filter-input="#filter" page-size="5" label="Team">
+  <label class="velin-label" for="filter">Filter</label>
+  <input id="filter" class="velin-input" type="search">
+  <table>
+    <caption>Team</caption>
+    <thead><tr><th data-sort="text">Name</th><th data-sort="number">Score</th></tr></thead>
+    <tbody>
+      <tr><td>Ada</td><td data-sort-value="98">98</td></tr>
+      <tr><td>Grace</td><td data-sort-value="95">95</td></tr>
+    </tbody>
+  </table>
+</velin-data-table>`,
+};
+
 export function renderComponent(meta, contracts) {
   let md = banner(meta.file);
   md += heading(1, `<${meta.tag}>`);
   md += `\nSource: \`${meta.file}\`\n\n`;
 
+  const snippet = MINIMAL_EXAMPLES[meta.tag];
+  if (snippet) {
+    md += heading(2, 'Minimal working example');
+    md += 'Copy-paste starter (load CSS + `velinstyle-components` / `bootFromDOM` as needed):\n\n';
+    md += '```html\n' + snippet.trim() + '\n```\n\n';
+  }
+
   if (meta.description) {
     md += heading(2, 'Description');
     md += `${meta.description}\n\n`;
@@ -129,10 +179,19 @@ export function renderComponent(meta, contracts) {
   if (meta.observedAttributes.length) {
     md += table(
       ['Attribute', 'Notes'],
-      meta.observedAttributes.map((a) => [`\`${a}\``, 'Observed — triggers `attributeChangedCallback` when changed']),
+      meta.observedAttributes.map((a) => {
+        const required = contracts?.requiredAttributes?.includes(a) ? ' (required by a11y contract)' : '';
+        return [`\`${a}\``, `Observed — triggers \`attributeChangedCallback\` when changed${required}`];
+      }),
     );
   } else {
-    md += '_No `observedAttributes` declared._\n\n';
+    md += '_No `observedAttributes` declared._ Author-facing configuration may still use slots, properties, or child markup — see **Slots** / **Public API** below.\n\n';
+    if (meta.slots.length) {
+      md += table(
+        ['Author surface', 'Notes'],
+        meta.slots.map((s) => [`slot \`${s}\``, 'Content projection (not an observed attribute)']),
+      );
+    }
   }
 
   md += heading(2, 'Events');

package/cli/docgen/extract-utilities.js

@@ -2,8 +2,11 @@ import { readFileSync, readdirSync, existsSync } from 'fs';
 import { join, basename } from 'path';
 import { banner, heading, table, sortByKey } from './markdown.js';
 
-const CLASS_RULE_RE = /\.(velin-[\w\\\/:-]+)\s*\{([^}]*)\}/g;
-const NESTED_CLASS_RE = /[\s,>+~](\.velin-[\w\\\/:-]+)\s*\{([^}]*)\}/g;
+/**
+ * Match `.velin-*` even when combinators follow before the block
+ * (e.g. `.velin-divide-y > * + * { … }`).
+ */
+const CLASS_RULE_RE = /\.(velin-[\w\\\/:-]+)(?=[^{]*\{)[^{]*\{([^}]*)\}/g;
 
 function truncateCss(body, max = 120) {
   const one = body.replace(/\s+/g, ' ').trim();
@@ -13,17 +16,14 @@ function truncateCss(body, max = 120) {
 
 export function parseUtilityCss(content) {
   const classes = [];
+  const seen = new Set();
   let m;
   const re = new RegExp(CLASS_RULE_RE.source, 'g');
   while ((m = re.exec(content)) !== null) {
-    classes.push({ selector: m[1], output: truncateCss(m[2]) });
-  }
-  const nested = new RegExp(NESTED_CLASS_RE.source, 'g');
-  while ((m = nested.exec(content)) !== null) {
-    const sel = m[1].replace(/^\./, '');
-    if (!classes.some((c) => c.selector === sel)) {
-      classes.push({ selector: sel, output: truncateCss(m[2]) });
-    }
+    const selector = m[1];
+    if (seen.has(selector)) continue;
+    seen.add(selector);
+    classes.push({ selector, output: truncateCss(m[2]) });
   }
   return classes;
 }

package/cli/doctor.js

@@ -0,0 +1,119 @@
+/**
+ * Environment / install health checks for VelinStyle consumers.
+ */
+import { existsSync, readdirSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import { pathToFileURL } from 'url';
+
+/**
+ * @param {{ cwd?: string, pkgRoot?: string }} opts
+ */
+export async function runDoctor(opts = {}) {
+  const cwd = resolve(opts.cwd || process.cwd());
+  const pkgRoot = opts.pkgRoot ? resolve(opts.pkgRoot) : null;
+  const issues = [];
+  const ok = [];
+
+  const checkFile = (label, path, severity = 'error') => {
+    if (existsSync(path) && statSync(path).isFile()) {
+      ok.push(`${label}: ${path}`);
+      return true;
+    }
+    issues.push({ severity, message: `Missing ${label}`, path, fix: `Provide ${label} at ${path}` });
+    return false;
+  };
+
+  const checkDir = (label, path, severity = 'warning') => {
+    if (existsSync(path) && statSync(path).isDirectory()) {
+      ok.push(`${label}: ${path}`);
+      return true;
+    }
+    issues.push({ severity, message: `Missing ${label}`, path, fix: `Create or copy ${label}` });
+    return false;
+  };
+
+  // Consumer project
+  checkFile('velinstyle.config.js', join(cwd, 'velinstyle.config.js'), 'info');
+  const vendorCandidates = [
+    join(cwd, 'vendor', 'velinstyle'),
+    join(cwd, 'public', 'vendor', 'velinstyle'),
+    join(cwd, 'dist'),
+  ];
+  let vendorHit = false;
+  for (const v of vendorCandidates) {
+    if (existsSync(join(v, 'velinstyle.min.css')) || existsSync(join(v, 'velinstyle.css'))) {
+      ok.push(`CSS found under ${v}`);
+      vendorHit = true;
+      const sprite = join(v, 'velin-icons.svg');
+      if (existsSync(sprite)) ok.push(`Icon sprite: ${sprite}`);
+      else issues.push({ severity: 'warning', message: 'Icon sprite not found next to CSS', path: sprite, fix: 'Copy velin-icons.svg or set meta name="velin-icon-sprite"' });
+      const themes = join(v, 'themes');
+      if (existsSync(themes)) ok.push(`Themes: ${themes}`);
+      break;
+    }
+  }
+  if (!vendorHit) {
+    issues.push({
+      severity: 'warning',
+      message: 'No local VelinStyle CSS found (vendor/velinstyle or dist)',
+      fix: 'Copy framework dist/ into vendor/velinstyle or npm i @birdapi/velinstyle',
+    });
+  }
+
+  // Framework package (when doctor runs from monorepo / linked package)
+  if (pkgRoot) {
+    checkFile('Framework CSS (min)', join(pkgRoot, 'dist', 'velinstyle.min.css'));
+    checkFile('Framework components (min)', join(pkgRoot, 'dist', 'velinstyle-components.min.js'));
+    checkFile('Framework icon sprite', join(pkgRoot, 'dist', 'velin-icons.svg'), 'warning');
+    checkDir('Framework themes', join(pkgRoot, 'dist', 'themes'), 'warning');
+  }
+
+  // Windows ESM config smoke
+  const configPath = join(cwd, 'velinstyle.config.js');
+  if (existsSync(configPath)) {
+    try {
+      await import(pathToFileURL(configPath).href);
+      ok.push('Config import via pathToFileURL succeeded (Windows-safe)');
+    } catch (err) {
+      issues.push({
+        severity: 'error',
+        message: `Failed to import velinstyle.config.js: ${err?.message || err}`,
+        fix: 'Ensure the CLI uses pathToFileURL for dynamic imports on Windows',
+      });
+    }
+  }
+
+  if (process.platform === 'win32') {
+    ok.push('Platform: Windows — use pathToFileURL for ESM config; avoid raw d:\\ imports');
+  }
+
+  const errors = issues.filter((i) => i.severity === 'error').length;
+  const warnings = issues.filter((i) => i.severity === 'warning').length;
+
+  return {
+    ok: errors === 0,
+    cwd,
+    summary: { errors, warnings, infos: issues.filter((i) => i.severity === 'info').length, passed: ok.length },
+    okLines: ok,
+    issues,
+  };
+}
+
+export function formatDoctorReport(report) {
+  const lines = [`VelinStyle doctor — ${report.cwd}`, ''];
+  for (const line of report.okLines) lines.push(`  OK  ${line}`);
+  if (report.issues.length) {
+    lines.push('');
+    for (const i of report.issues) {
+      lines.push(`  [${i.severity}] ${i.message}`);
+      if (i.fix) lines.push(`         fix: ${i.fix}`);
+    }
+  }
+  lines.push('');
+  lines.push(
+    report.ok
+      ? `Pass (${report.summary.passed} checks, ${report.summary.warnings} warning(s))`
+      : `Fail (${report.summary.errors} error(s), ${report.summary.warnings} warning(s))`,
+  );
+  return lines.join('\n');
+}