orbital-ds 0.1.1 → 0.3.0

package/package.json

@@ -1,95 +1,138 @@
-{
-  "name": "orbital-ds",
-  "version": "0.1.1",
-  "description": "Sistema de diseño genérico: estructura común (tokens semánticos, capa base) + temas intercambiables + primitivos sobre Base UI y Tailwind v4.",
-  "keywords": [
-    "design-system",
-    "design-tokens",
-    "theme",
-    "tailwindcss",
-    "base-ui",
-    "shadcn",
-    "react"
-  ],
-  "license": "MIT",
-  "type": "module",
-  "sideEffects": [
-    "*.css"
-  ],
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "exports": {
-    "./styles.css": "./dist/styles.css",
-    "./themes/*.css": "./dist/themes/*.css",
-    "./ui/*": {
-      "types": "./dist/ui/*.d.ts",
-      "import": "./dist/ui/*.js"
-    },
-    "./lib/*": {
-      "types": "./dist/lib/*.d.ts",
-      "import": "./dist/lib/*.js"
-    },
-    "./hooks/*": {
-      "types": "./dist/hooks/*.d.ts",
-      "import": "./dist/hooks/*.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "scripts": {
-    "build": "tsup && node scripts/copy-css.mjs",
-    "dev": "tsup --watch --onSuccess \"node scripts/copy-css.mjs\"",
-    "typecheck": "tsc --noEmit",
-    "verify": "pnpm typecheck && pnpm build"
-  },
-  "peerDependencies": {
-    "@base-ui/react": ">=1.7",
-    "class-variance-authority": ">=0.7",
-    "clsx": ">=2",
-    "lucide-react": ">=0.400",
-    "react": ">=19",
-    "react-dom": ">=19",
-    "tailwind-merge": ">=3",
-    "tailwindcss": ">=4.1",
-    "tw-animate-css": ">=1.3",
-    "next-themes": ">=0.4",
-    "recharts": ">=3",
-    "sonner": ">=2"
-  },
-  "peerDependenciesMeta": {
-    "next-themes": {
-      "optional": true
-    },
-    "recharts": {
-      "optional": true
-    },
-    "sonner": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@base-ui/react": "^1.7.0",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "lucide-react": "^0.577.0",
-    "next-themes": "^0.4.6",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "recharts": "3.8.0",
-    "sonner": "^2.0.8",
-    "tailwind-merge": "^3.0.2",
-    "tailwindcss": "^4.1.18",
-    "tsup": "^8.5.0",
-    "tw-animate-css": "^1.3.6",
-    "typescript": "^5.9.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
-  }
-}
+{
+  "name": "orbital-ds",
+  "version": "0.3.0",
+  "description": "Sistema de diseño genérico: estructura común + temas con personalidad (qratia, zyro) + ~60 componentes sobre Base UI y Tailwind v4, con contrato verificable y legible por agentes.",
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "theme",
+    "tailwindcss",
+    "base-ui",
+    "shadcn",
+    "react"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "dist",
+    "scripts/doctor.mjs",
+    "scripts/manifest.mjs",
+    "contract.json",
+    "components.manifest.json",
+    "docs",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./styles.css": "./dist/styles.css",
+    "./themes/*.css": "./dist/themes/*.css",
+    "./ui/*": {
+      "types": "./dist/ui/*.d.ts",
+      "import": "./dist/ui/*.js"
+    },
+    "./lib/*": {
+      "types": "./dist/lib/*.d.ts",
+      "import": "./dist/lib/*.js"
+    },
+    "./hooks/*": {
+      "types": "./dist/hooks/*.d.ts",
+      "import": "./dist/hooks/*.js"
+    },
+    "./package.json": "./package.json",
+    "./contract.json": "./contract.json",
+    "./components.manifest.json": "./components.manifest.json"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/build-css.mjs",
+    "dev": "tsup --watch --onSuccess \"node scripts/copy-css.mjs\"",
+    "typecheck": "tsc --noEmit",
+    "verify": "pnpm check:ds && pnpm typecheck && pnpm build",
+    "manifest": "node scripts/manifest.mjs",
+    "check:ds": "node scripts/doctor.mjs"
+  },
+  "peerDependencies": {
+    "@base-ui/react": ">=1.9",
+    "class-variance-authority": ">=0.7",
+    "clsx": ">=2",
+    "lucide-react": ">=0.400",
+    "react": ">=19",
+    "react-dom": ">=19",
+    "tailwind-merge": ">=3",
+    "tailwindcss": ">=4.1",
+    "tw-animate-css": ">=1.3",
+    "next-themes": ">=0.4",
+    "recharts": ">=3",
+    "sonner": ">=2",
+    "@shadcn/react": ">=0.3",
+    "cmdk": ">=1.1",
+    "date-fns": ">=4",
+    "embla-carousel-react": ">=8.6",
+    "input-otp": ">=1.5",
+    "react-day-picker": ">=10",
+    "react-resizable-panels": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "next-themes": {
+      "optional": true
+    },
+    "recharts": {
+      "optional": true
+    },
+    "sonner": {
+      "optional": true
+    },
+    "@shadcn/react": {
+      "optional": true
+    },
+    "cmdk": {
+      "optional": true
+    },
+    "date-fns": {
+      "optional": true
+    },
+    "embla-carousel-react": {
+      "optional": true
+    },
+    "input-otp": {
+      "optional": true
+    },
+    "react-day-picker": {
+      "optional": true
+    },
+    "react-resizable-panels": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@base-ui/react": "^1.9.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.577.0",
+    "next-themes": "^0.4.6",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "recharts": "3.8.0",
+    "sonner": "^2.0.8",
+    "tailwind-merge": "^3.0.2",
+    "tailwindcss": "^4.1.18",
+    "tsup": "^8.5.0",
+    "tw-animate-css": "^1.3.6",
+    "typescript": "^5.9.0",
+    "@shadcn/react": "^0.3.1",
+    "cmdk": "^1.1.1",
+    "date-fns": "^4.4.0",
+    "embla-carousel-react": "^8.6.0",
+    "input-otp": "^1.5.0",
+    "react-day-picker": "^10.0.2",
+    "react-resizable-panels": "^4.14.4"
+  },
+  "bin": {
+    "orbital-ds-doctor": "./scripts/doctor.mjs"
+  }
+}

package/scripts/doctor.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * 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 `--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 (repetidos)
+ *
+ * Sale con código 1 si hay errores (los avisos no fallan).
+ */
+import { readFileSync, readdirSync, 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 contract = JSON.parse(readFileSync(join(ROOT, 'contract.json'), 'utf8'));
+
+const errors = [];
+const warnings = [];
+const read = (p) => readFileSync(p, 'utf8');
+const stripComments = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '');
+
+/** Cuerpo de cada bloque `selector { ... }` (respeta llaves anidadas). */
+function blocks(css, selectorRe) {
+  const out = [];
+  const re = new RegExp(selectorRe.source + '\\s*\\{', 'g');
+  let m;
+  while ((m = re.exec(css))) {
+    let depth = 1;
+    let i = re.lastIndex;
+    const start = i;
+    while (i < css.length && depth > 0) {
+      if (css[i] === '{') depth++;
+      else if (css[i] === '}') depth--;
+      i++;
+    }
+    out.push(css.slice(start, i - 1));
+    re.lastIndex = i;
+  }
+  return out;
+}
+
+/** 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() }));
+}
+
+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 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}`)) errors.push(`${label}: falta la fuente --${f} en :root`);
+  }
+  if (darks.length) {
+    for (const t of contract.dark.avisar_si_falta) {
+      if (!darkVars.has(`--${t}`)) warnings.push(`${label}: .dark no redefine --${t} (hereda el valor claro)`);
+    }
+  } else {
+    warnings.push(`${label}: no define piel .dark`);
+  }
+
+  // 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 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 ${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+3) temas
+const themesDir = join(ROOT, existsSync(join(ROOT, 'src/themes')) ? 'src/themes' : 'dist/themes');
+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 css = stripComments(read(resolve(process.argv[cssArgIdx + 1])));
+  blocks(css, /(?:^|[\s}])\:root/).forEach((body, idx) => {
+    const seen = new Map();
+    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})`);
+  });
+}
+
+// 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' },
+  { re: /(?<![\w-])z-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'z-index numérico (usa --ds-z-*)' },
+  { re: /(?<![\w-])duration-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'duración fija (usa --ds-motion-*)' },
+  { re: /(?<![\w-])(?:bg|text|border)-(?:black|white)(?:\/\d+)?(?![\w-])/g, why: 'color fijo (usa un token de color)' },
+  { re: /(?<![\w-])shadow-(?:xs|sm|md|lg|xl|2xl)(?![\w-])/g, why: 'sombra de la escala Tailwind (usa shadow-card/control/raised/overlay/popover)' },
+  { re: /(?<![\w-])text-\[\d+px\]/g, why: 'tamaño de texto arbitrario (usa la escala estándar)' },
+  { re: /(?<![\w-])rounded-(?:3xl|4xl)(?![\w-])/g, why: 'radio fuera de la rampa (usa rounded-control/overlay o la rampa sm…2xl)' },
+  { re: /(?<![\w-])(?:bg|text|border|ring|fill|stroke)-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone)-\d{2,3}(?![\w-])/g, why: 'color de la paleta Tailwind (usa tokens del tema)' },
+];
+
+const uiDir = join(ROOT, 'src/ui');
+if (existsSync(uiDir)) {
+  for (const f of readdirSync(uiDir).filter((n) => n.endsWith('.tsx'))) {
+    const lines = read(join(uiDir, f)).split(/\r?\n/);
+    lines.forEach((line, i) => {
+      const code = line.replace(/\/\/.*$/, '');
+      for (const rule of NO_HARDCODE) {
+        if (rule.skip?.includes(f)) continue;
+        const hits = code.match(rule.re);
+        if (hits) errors.push(`ui/${f}:${i + 1}: ${rule.why} → ${[...new Set(hits)].join(', ')}`);
+      }
+    });
+  }
+}
+
+// 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, sombras, fugas, valores fijos y API pública correctos (${warnings.length} aviso(s)).`);

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