orbital-ds 0.2.0 → 0.4.0

package/scripts/doctor.mjs

@@ -3,14 +3,21 @@
  * orbital-ds doctor — comprueba que el sistema se cumple.
  *
  *   1. CONTRATO: cada tema (themes/*.css) define en :root todos los tokens de
- *      contract.json (y la fuente `--font-sans`). En .dark solo avisa.
- *   2. REPETIDOS: ninguna variable CSS se define dos veces en el mismo bloque.
- *   3. VALORES FIJOS: ningún componente (ui/*.tsx) escribe colores, z-index,
+ *      contract.json y la fuente `--ds-font-sans`. En .dark solo avisa.
+ *   2. REPETIDOS: ninguna variable se define dos veces en el mismo bloque.
+ *   3. SOMBRAS: «sin sombra» es `0 0 #0000`, nunca `none` (una variable con
+ *      `none` invalida todo el box-shadow, anillo de foco incluido).
+ *   4. FUGAS: el tema base (contract.baseTheme) está aplicado siempre; todo tema
+ *      con ámbito debe definir cada `--ds-*` que defina el base, o su valor se
+ *      colaría al cambiar de tema.
+ *   5. VALORES FIJOS: ningún componente (ui/*.tsx) escribe colores, z-index,
  *      duraciones ni sombras a mano; todo sale de tokens.
+ *   6. API PÚBLICA: no desaparece ningún componente ni export respecto a
+ *      components.manifest.json (huella de la última versión). Lo nuevo solo avisa.
  *
  * Uso:
  *   node scripts/doctor.mjs                 # temas y componentes del paquete
- *   node scripts/doctor.mjs --css app.css   # además, un CSS de una app (contrato + repetidos)
+ *   node scripts/doctor.mjs --css app.css   # además, un CSS de una app (repetidos)
  *
  * Sale con código 1 si hay errores (los avisos no fallan).
  */
@@ -26,7 +33,7 @@ const warnings = [];
 const read = (p) => readFileSync(p, 'utf8');
 const stripComments = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '');
 
-/** Devuelve el cuerpo de cada bloque `selector { ... }` (respeta llaves anidadas). */
+/** Cuerpo de cada bloque `selector { ... }` (respeta llaves anidadas). */
 function blocks(css, selectorRe) {
   const out = [];
   const re = new RegExp(selectorRe.source + '\\s*\\{', 'g');
@@ -46,25 +53,52 @@ function blocks(css, selectorRe) {
   return out;
 }
 
-const definedVars = (body) => [...body.matchAll(/(^|[;{\s])(--[a-z0-9-]+)\s*:/gi)].map((m) => m[2]);
+/** Declaraciones `--x: valor;` del nivel superior de un bloque (no las anidadas). */
+function declarations(body) {
+  let depth = 0;
+  let top = '';
+  for (const ch of body) {
+    if (ch === '{') depth++;
+    else if (ch === '}') depth--;
+    else if (depth === 0) top += ch;
+  }
+  return [...top.matchAll(/(^|[;\s])(--[a-z0-9-]+)\s*:\s*([^;]*);?/gi)].map((m) => ({ name: m[2], value: m[3].trim() }));
+}
+
+/** Variables --ds-* que la estructura del paquete define (las que una app puede usar). */
+function knownDsVars() {
+  const f = existsSync(join(ROOT, 'src/styles.css')) ? join(ROOT, 'src/styles.css') : join(ROOT, 'dist/styles.css');
+  return new Set([...read(f).matchAll(/(--ds-[a-z0-9-]+)\s*:/g)].map((m) => m[1]));
+}
+
+// El grupo de marca debe ser coherente con el contrato: cada variable, o es del contrato, o es --ds-*.
+for (const t of contract.brand?.tokens ?? []) {
+  const inContract =
+    contract.root.includes(t.name) ||
+    contract.fonts.includes(t.name) ||
+    (t.name.startsWith('ds-') && knownDsVars().has(`--${t.name}`));
+  if (!inContract) errors.push(`contrato: la variable de marca --${t.name} ni es del contrato ni la define la estructura`);
+}
 
-function checkTheme(file, label) {
+const themeInfo = {}; // nombre → { rootVars:Set, darkVars:Set }
+
+function checkTheme(file, name) {
+  const label = `tema ${name}`;
   const css = stripComments(read(file));
   const roots = blocks(css, /(?:^|[\s}])\:root/);
   const darks = blocks(css, /(?:^|[\s}])\.dark/);
-  const themeBlocks = blocks(css, /@theme\s+inline/);
 
-  const rootVars = new Set(roots.flatMap(definedVars));
-  const themeVars = new Set(themeBlocks.flatMap(definedVars));
-  const darkVars = new Set(darks.flatMap(definedVars));
+  const rootDecl = roots.flatMap(declarations);
+  const darkDecl = darks.flatMap(declarations);
+  const rootVars = new Set(rootDecl.map((d) => d.name));
+  const darkVars = new Set(darkDecl.map((d) => d.name));
+  themeInfo[name] = { rootVars, darkVars };
 
   for (const t of contract.root) {
     if (!rootVars.has(`--${t}`)) errors.push(`${label}: falta el token obligatorio --${t} en :root`);
   }
   for (const f of contract.fonts) {
-    if (!rootVars.has(`--${f}`) && !themeVars.has(`--${f}`)) {
-      errors.push(`${label}: falta la fuente --${f} (en :root o @theme)`);
-    }
+    if (!rootVars.has(`--${f}`)) errors.push(`${label}: falta la fuente --${f} en :root`);
   }
   if (darks.length) {
     for (const t of contract.dark.avisar_si_falta) {
@@ -74,38 +108,65 @@ function checkTheme(file, label) {
     warnings.push(`${label}: no define piel .dark`);
   }
 
-  // Repetidos dentro de un mismo bloque
-  for (const [name, list] of [['@theme', themeBlocks], [':root', roots], ['.dark', darks]]) {
+  // Repetidos (solo declaraciones del nivel superior de cada bloque)
+  for (const [kind, list] of [[':root', roots], ['.dark', darks]]) {
     list.forEach((body, idx) => {
       const seen = new Map();
-      for (const v of definedVars(body)) seen.set(v, (seen.get(v) ?? 0) + 1);
+      for (const d of declarations(body)) seen.set(d.name, (seen.get(d.name) ?? 0) + 1);
       for (const [v, n] of seen) {
-        if (n > 1) errors.push(`${label}: ${v} definido ${n} veces en el mismo bloque ${name} (#${idx + 1})`);
+        if (n > 1) errors.push(`${label}: ${v} definido ${n} veces en el mismo bloque ${kind} (#${idx + 1})`);
       }
     });
   }
+
+  // Sombras: `none` invalida el box-shadow
+  for (const d of [...rootDecl, ...darkDecl]) {
+    if (/^--ds-(?:shadow|sidebar-shadow)/.test(d.name) && /^none$/i.test(d.value)) {
+      errors.push(`${label}: ${d.name}: none — usa «0 0 #0000» (none invalida todo el box-shadow)`);
+    }
+  }
 }
 
-// 1+2) temas del paquete
+// 1+2+3) temas
 const themesDir = join(ROOT, existsSync(join(ROOT, 'src/themes')) ? 'src/themes' : 'dist/themes');
-for (const f of readdirSync(themesDir).filter((n) => n.endsWith('.css'))) {
-  checkTheme(join(themesDir, f), `tema ${f}`);
+const themeFiles = readdirSync(themesDir).filter(
+  (n) => n.endsWith('.css') && !n.endsWith('.fonts.css') && !n.endsWith('.scoped.css'),
+);
+for (const f of themeFiles) checkTheme(join(themesDir, f), f.replace(/\.css$/, ''));
+
+// 4) fugas desde el tema base
+const base = contract.baseTheme;
+if (base && themeInfo[base]) {
+  const baseDs = [...themeInfo[base].rootVars].filter((v) => v.startsWith('--ds-'));
+  for (const [name, info] of Object.entries(themeInfo)) {
+    if (name === base) continue;
+    for (const v of baseDs) {
+      if (!info.rootVars.has(v)) {
+        errors.push(`tema ${name}: no define ${v}, que sí define el tema base «${base}» — su valor se colaría al cambiar de tema`);
+      }
+    }
+  }
 }
 
 // CSS de una app (opcional)
 const cssArgIdx = process.argv.indexOf('--css');
 if (cssArgIdx > -1 && process.argv[cssArgIdx + 1]) {
-  const f = resolve(process.argv[cssArgIdx + 1]);
-  const css = stripComments(read(f));
-  const roots = blocks(css, /(?:^|[\s}])\:root/);
-  roots.forEach((body, idx) => {
+  const css = stripComments(read(resolve(process.argv[cssArgIdx + 1])));
+  blocks(css, /(?:^|[\s}])\:root/).forEach((body, idx) => {
     const seen = new Map();
-    for (const v of definedVars(body)) seen.set(v, (seen.get(v) ?? 0) + 1);
+    for (const d of declarations(body)) seen.set(d.name, (seen.get(d.name) ?? 0) + 1);
     for (const [v, n] of seen) if (n > 1) errors.push(`app css: ${v} definido ${n} veces en :root (#${idx + 1})`);
+    // Una variable --ds-* que el paquete ya no tiene: la marca la ignoraría en silencio.
+    const known = knownDsVars();
+    for (const d of declarations(body)) {
+      if (d.name.startsWith('--ds-') && !known.has(d.name)) {
+        errors.push(`app css: ${d.name} no existe en orbital-ds (¿renombrada o retirada? mira docs/CONTRACT.md)`);
+      }
+    }
   });
 }
 
-// 3) valores fijos en componentes
+// 5) valores fijos en componentes
 const NO_HARDCODE = [
   { re: /#[0-9a-fA-F]{3,8}\b/g, why: 'color hexadecimal', skip: ['chart.tsx'] },
   { re: /\b(?:rgb|rgba|hsl|hsla|oklch)\((?!from_)/g, why: 'color literal' },
@@ -133,10 +194,31 @@ if (existsSync(uiDir)) {
   }
 }
 
+// 6) API pública frente a la huella commiteada
+const manifestPath = join(ROOT, 'components.manifest.json');
+if (existsSync(manifestPath) && existsSync(uiDir)) {
+  const { buildManifest } = await import('./manifest.mjs');
+  const before = JSON.parse(read(manifestPath)).components;
+  const now = buildManifest().components;
+  for (const [name, comp] of Object.entries(before)) {
+    if (!now[name]) {
+      errors.push(`API pública: desaparece el componente «${name}» (¿versión mayor? regenera con pnpm manifest)`);
+      continue;
+    }
+    for (const e of comp.exports) {
+      if (!now[name].exports.includes(e)) {
+        errors.push(`API pública: «${name}» ya no exporta ${e} (¿versión mayor? regenera con pnpm manifest)`);
+      }
+    }
+  }
+  const added = Object.keys(now).filter((n) => !before[n]);
+  if (added.length) warnings.push(`API pública: componentes nuevos sin registrar en el manifiesto (${added.join(', ')}); ejecuta pnpm manifest`);
+}
+
 for (const w of warnings) console.log(`AVISO  ${w}`);
 for (const e of errors) console.log(`ERROR  ${e}`);
 if (errors.length) {
   console.log(`\ndoctor: ${errors.length} error(es), ${warnings.length} aviso(s)`);
   process.exit(1);
 }
-console.log(`doctor: contrato, repetidos y valores fijos correctos (${warnings.length} aviso(s)).`);
+console.log(`doctor: contrato, repetidos, sombras, fugas, valores fijos y API pública correctos (${warnings.length} aviso(s)).`);

package/scripts/init.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * orbital-ds-init — crea el fichero de MARCA de una app.
+ *
+ *   pnpm exec orbital-ds-init            # crea src/brand.css si no existe
+ *   pnpm exec orbital-ds-init --out app/brand.css
+ *
+ * NUNCA sobrescribe un fichero existente. Ese fichero es de la app: ninguna
+ * actualización de orbital-ds lo toca, y se importa DESPUÉS del tema para que gane.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const contract = JSON.parse(readFileSync(resolve(ROOT, 'contract.json'), 'utf8'));
+
+const outIdx = process.argv.indexOf('--out');
+const out = resolve(outIdx > -1 && process.argv[outIdx + 1] ? process.argv[outIdx + 1] : 'src/brand.css');
+
+if (existsSync(out)) {
+  console.log(`Ya existe ${out}: no se toca (es de tu app).`);
+  process.exit(0);
+}
+
+const lines = contract.brand.tokens.map(
+  (t) => `  /* --${t.name}: ${t.example}; */  /* ${t.about} */`,
+);
+
+const css = `/*
+ * MARCA de la app — fichero TUYO.
+ *
+ * Ninguna actualización de orbital-ds lo toca. Se importa DESPUÉS del tema, así que
+ * lo que pongas aquí gana. Si no defines nada, se aplica el valor estándar del tema.
+ *
+ * Estas variables son el grupo estable de «lo que una marca suele cambiar»: renombrar
+ * o quitar una de ellas es una versión MAYOR de orbital-ds, con aviso previo.
+ * Descomenta solo lo que necesites y cambia el valor.
+ *
+ * Cambia el color principal TODO junto: primary, ring, link, brand, sidebar-primary y
+ * chart-1 deben ir a la par (y comprueba el contraste del texto sobre ellos).
+ */
+:root {
+${lines.join('\n')}
+}
+
+/* Piel oscura: solo si tu marca necesita valores distintos en oscuro. */
+.dark {
+  /* --primary: ...; */
+}
+`;
+
+mkdirSync(dirname(out), { recursive: true });
+writeFileSync(out, css);
+console.log(`Creado ${out}.\n\nImpórtalo DESPUÉS del tema, en el CSS de tu app:\n\n  @import 'orbital-ds/themes/<tema>.css';\n  @import './brand.css';\n`);

package/scripts/manifest.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * Manifiesto de componentes de orbital-ds (`components.manifest.json`).
+ *
+ * Lo leen los agentes de IA (qué hay, cómo se importa, qué `data-slot` expone,
+ * qué dependencias opcionales pide) y `pnpm check:ds` lo usa como HUELLA de la API
+ * pública: si desaparece un componente o un export respecto al manifiesto
+ * commiteado, doctor falla salvo que se haga una versión mayor.
+ *
+ *   node scripts/manifest.mjs        # regenera components.manifest.json
+ */
+import { readFileSync, readdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const UI = join(ROOT, 'src/ui');
+
+// Dependencias que SIEMPRE están (peers obligatorios): no se listan como opcionales.
+const REQUIRED = new Set([
+  'react', 'react-dom', 'class-variance-authority', 'clsx', 'tailwind-merge', 'lucide-react',
+]);
+
+function parseExports(src) {
+  const names = new Set();
+  for (const m of src.matchAll(/export\s*\{([^}]*)\}/g)) {
+    for (const part of m[1].split(',')) {
+      const n = part.trim().split(/\s+as\s+/i).pop()?.trim();
+      if (n) names.add(n);
+    }
+  }
+  for (const m of src.matchAll(/export\s+(?:async\s+)?(?:function|const|class)\s+([A-Za-z0-9_]+)/g)) names.add(m[1]);
+  return [...names].sort();
+}
+
+function parseSlots(src) {
+  return [...new Set([...src.matchAll(/data-slot="([a-z0-9-]+)"/g)].map((m) => m[1]))].sort();
+}
+
+function parseOptionalPeers(src) {
+  const peers = new Set();
+  for (const m of src.matchAll(/from\s+"([^"]+)"/g)) {
+    const spec = m[1];
+    if (spec.startsWith('.')) continue;
+    const pkg = spec.startsWith('@') ? spec.split('/').slice(0, 2).join('/') : spec.split('/')[0];
+    if (pkg === '@base-ui/react' || REQUIRED.has(pkg)) continue;
+    peers.add(pkg);
+  }
+  return [...peers].sort();
+}
+
+export function buildManifest() {
+  const components = {};
+  for (const f of readdirSync(UI).filter((n) => n.endsWith('.tsx')).sort()) {
+    const src = readFileSync(join(UI, f), 'utf8');
+    const name = f.replace(/\.tsx$/, '');
+    components[name] = {
+      import: `orbital-ds/ui/${name}`,
+      exports: parseExports(src),
+      slots: parseSlots(src),
+      optionalPeers: parseOptionalPeers(src),
+    };
+  }
+  const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'));
+  return {
+    package: pkg.name,
+    version: pkg.version,
+    engine: '@base-ui/react',
+    docs: ['README.md', 'docs/CONTRACT.md', 'AGENTS.md', 'contract.json'],
+    components,
+  };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const out = join(ROOT, 'components.manifest.json');
+  const manifest = buildManifest();
+  writeFileSync(out, JSON.stringify(manifest, null, 2) + '\n');
+  console.log(`manifest: ${Object.keys(manifest.components).length} componentes → components.manifest.json`);
+}