@hiscovega/grisso 1.0.4 → 1.0.6

package/README.md

@@ -1,6 +1,6 @@
 # Grisso
 
-> Librería de utility CSS de Griddo — similar a Tailwind CSS pero con valores basados en CSS custom properties (design tokens).
+> Librería de utility CSS de Griddo con valores basados en CSS custom properties (design tokens).
 
 ## Instalación
 
@@ -10,47 +10,92 @@ npm install @hiscovega/grisso
 
 ## Uso
 
-### Opción A: CSS directo
+### CLI
 
-Importa el CSS pre-compilado directamente. Útil para desarrollo o cuando no usas PostCSS.
+Genera CSS desde la terminal. Forma recomendada de usar Grisso, ideal para scripts de build y CI/CD.
 
-```css
-/* En tu CSS global */
-@import "@hiscovega/grisso";
-```
+```bash
+# CSS completo a stdout
+npx grisso build
+
+# Escribir a archivo
+npx grisso build --output dist/grisso.css
+
+# Con config personalizada
+npx grisso build --config grisso.config.mjs --output dist/grisso.css
+
+# Tree-shaking (solo clases usadas)
+npx grisso build --content "src/**/*.tsx" --content "src/**/*.css" --output dist/grisso.css
 
-O en HTML:
+# Proteger clases del tree-shaking
+npx grisso build --content "src/**/*.tsx" --safelist "^p-" --safelist "^m-" --output dist/grisso.css
 
-```html
-<link rel="stylesheet" href="node_modules/@hiscovega/grisso/dist/grisso.css" />
+# Sin minificar (útil para depuración)
+npx grisso build --no-minify --output dist/grisso.css
+
+# Pipear a otro comando
+npx grisso build | pbcopy
 ```
 
-### Opción B: PostCSS plugin (recomendado — con tree-shaking)
+**Flags de `grisso build`:**
 
-Añade el plugin a tu configuración de PostCSS. El CSS de Grisso se inyecta automáticamente y solo las clases usadas llegan al bundle final.
+| Flag                 | Descripción                                 |
+| -------------------- | ------------------------------------------- |
+| `--config <ruta>`    | Ruta a `grisso.config.mjs`                  |
+| `--content <glob>`   | Globs para tree-shaking (repetible)         |
+| `--safelist <regex>` | Patrones de clases a preservar (repetible)  |
+| `--output <ruta>`    | Archivo de salida (sin `--output` → stdout) |
+| `--no-minify`        | Deshabilitar minificación                   |
+| `--help, -h`         | Ayuda del comando                           |
 
-```js
-// postcss.config.js
-import grisso from "@hiscovega/grisso/plugin";
+Sin `--output`, el CSS va a stdout y los mensajes de estado a stderr, siguiendo la convención Unix.
 
-export default {
-  plugins: [
-    grisso({
-      content: ["./src/**/*.{js,ts,jsx,tsx,css}"],
-    }),
-  ],
-};
+#### `grisso tokens`
+
+Genera un scaffold con todas las CSS custom properties (design tokens) que necesitas definir. Extrae dinámicamente los tokens de la config resuelta.
+
+```bash
+# Scaffold CSS a stdout
+npx grisso tokens
+
+# Escribir a archivo
+npx grisso tokens --output tokens.css
+
+# Con config personalizada (refleja extends/overrides)
+npx grisso tokens --config grisso.config.mjs --output tokens.css
+
+# Config resuelta como JSON
+npx grisso tokens --format json
 ```
 
-Sin `content`, se incluye todo el CSS (útil en desarrollo):
+**Flags de `grisso tokens`:**
 
-```js
-grisso();
+| Flag              | Descripción                                       |
+| ----------------- | ------------------------------------------------- |
+| `--config <ruta>` | Ruta a `grisso.config.mjs`                        |
+| `--format <fmt>`  | Formato de salida: `css` (default) o `json`       |
+| `--output <ruta>` | Archivo de salida (sin `--output` → stdout)       |
+| `--help, -h`      | Ayuda del comando                                 |
+
+El scaffold CSS genera un `:root { }` con todas las properties vacías, agrupadas por sección, listo para rellenar:
+
+```css
+:root {
+	/* ─── Spacing ─── */
+	--spc-4xs: ;
+	--spc-3xs: ;
+	/* ... */
+
+	/* ─── Colors: marca ─── */
+	--brand-1: ;
+	--brand-2: ;
+	/* ... */
+}
 ```
 
-### Opción C: API programática (sin PostCSS)
+### API programática
 
-Usa `buildCSS()` directamente desde Node.js. Genera, purga y optimiza CSS sin depender de PostCSS — ideal para scripts de build, herramientas custom o entornos donde PostCSS no está disponible.
+Usa `buildCSS()` directamente desde Node.js. Genera, purga y optimiza CSS — ideal para scripts de build, herramientas custom o integración con cualquier bundler.
 
 ```js
 import { buildCSS } from "@hiscovega/grisso/build";
@@ -61,11 +106,12 @@ const css = await buildCSS();
 
 **Opciones de `buildCSS()`:**
 
-| Opción | Tipo | Default | Descripción |
-|---|---|---|---|
-| `config` | `string` | — | Ruta a `grisso.config.mjs` personalizado |
-| `content` | `string[]` | — | Globs de archivos a escanear para tree-shaking |
-| `minify` | `boolean` | `true` | Minificar el CSS de salida |
+| Opción     | Tipo                   | Default | Descripción                                                      |
+| ---------- | ---------------------- | ------- | ---------------------------------------------------------------- |
+| `config`   | `string`               | —       | Ruta a `grisso.config.mjs` personalizado                         |
+| `content`  | `string[]`             | —       | Globs de archivos a escanear para tree-shaking                   |
+| `safelist` | `(string \| RegExp)[]` | —       | Patrones de clases a preservar (se mergea con `config.safelist`) |
+| `minify`   | `boolean`              | `true`  | Minificar el CSS de salida                                       |
 
 Sin `content`, se incluye todo el CSS. Con `content`, se eliminan las clases no usadas via PurgeCSS.
 
@@ -131,6 +177,30 @@ export default {
 };
 ```
 
+#### `extractTokens()` — scaffold de tokens
+
+Usa `extractTokens()` para generar programáticamente el scaffold de custom properties (o JSON) desde la config resuelta.
+
+```js
+import { extractTokens } from "@hiscovega/grisso/tokens";
+
+// Scaffold CSS con todas las custom properties
+const css = await extractTokens();
+
+// JSON con los token maps resueltos
+const json = await extractTokens({
+  format: "json",
+  config: "./grisso.config.mjs",
+});
+```
+
+**Opciones de `extractTokens()`:**
+
+| Opción   | Tipo             | Default | Descripción                               |
+| -------- | ---------------- | ------- | ----------------------------------------- |
+| `config` | `string`         | —       | Ruta a `grisso.config.mjs` personalizado  |
+| `format` | `"css" \| "json"` | `"css"` | Formato de salida                         |
+
 **Servidor de desarrollo** — generar CSS on-the-fly:
 
 ```js
@@ -148,7 +218,7 @@ app.get("/grisso.css", async (req, res) => {
 
 ## Configuración personalizada
 
-Crea un `grisso.config.mjs` en la raíz de tu proyecto para extender o reemplazar los tokens por defecto. Sigue el patrón de Tailwind v3:
+Crea un `grisso.config.mjs` en la raíz de tu proyecto para extender o reemplazar los tokens por defecto.
 
 ```js
 // grisso.config.mjs
@@ -160,7 +230,7 @@ export default {
     lg: "24px",
   },
 
-  // `extend` MERGEA con los defaults
+  // `extend` MERGEA con los defaults (arrays se concatenan)
   extend: {
     foregroundColors: {
       5: "var(--text-5)",
@@ -168,26 +238,28 @@ export default {
     shadows: {
       "2xl": "var(--box-shadow-2xl)",
     },
+    // Se concatena con el default []
+    safelist: [/^p-/],
   },
 };
 ```
 
-Pasa la ruta al plugin:
+La `safelist` controla qué clases se protegen del tree-shaking. Por defecto está vacía. En top-level reemplaza, en `extend` se concatena. Acepta `RegExp` y `string`.
 
-```js
-grisso({
-  content: ["./src/**/*.{js,ts,jsx,tsx,css}"],
-  config: "./grisso.config.mjs",
-});
-```
-
-Si no se pasa `config`, el plugin busca automáticamente `grisso.config.mjs` en el directorio de trabajo. Si no existe, usa los defaults.
+Si no se pasa `config` a `buildCSS()`, busca automáticamente `grisso.config.mjs` en el directorio de trabajo. Si no existe, usa los defaults.
 
 Los defaults se pueden consultar importando `@hiscovega/grisso/config`.
 
 ## Design Tokens (CSS custom properties)
 
-Grisso usa CSS custom properties para todos los valores. Copia `tokens-example.css` y adapta los valores a tu design system:
+Grisso usa CSS custom properties para todos los valores. Genera un scaffold con todas las properties que necesitas definir:
+
+```bash
+# Genera scaffold dinámico desde tu config resuelta
+npx grisso tokens --output src/tokens.css
+```
+
+Alternativamente, copia el ejemplo estático:
 
 ```bash
 cp node_modules/@hiscovega/grisso/tokens-example.css src/tokens.css
@@ -208,7 +280,7 @@ Importa los tokens antes que Grisso en tu CSS global:
 
 ```css
 @import "./tokens.css";
-@import "@hiscovega/grisso"; /* o via plugin de PostCSS */
+@import "@hiscovega/grisso";
 ```
 
 ## Clases disponibles
@@ -219,7 +291,7 @@ Importa los tokens antes que Grisso en tu CSS global:
 {breakpoint}-{propiedad}-{escala}
 ```
 
-Ejemplos: `flex`, `tablet-flex`, `p-md`, `desktop-mt-lg`, `text-center`
+Ejemplos: `flex`, `tablet-flex`, `p-md`, `desktop-mt-lg`, `text-center`, `w-1/2`, `z-10`, `tracking-tight`
 
 ### Breakpoints (mobile-first)
 
@@ -232,22 +304,22 @@ Ejemplos: `flex`, `tablet-flex`, `p-md`, `desktop-mt-lg`, `text-center`
 
 ### Categorías
 
-| Categoría      | Ejemplos                                                             |
-| -------------- | -------------------------------------------------------------------- |
-| **Layout**     | `flex`, `block`, `hidden`, `relative`, `absolute`, `overflow-hidden` |
-| **Flex/Grid**  | `flex-col`, `flex-wrap`, `items-center`, `justify-between`, `gap-md` |
-| **Spacing**    | `p-sm`, `pt-lg`, `mx-auto`, `mt-xs`, `mb-md`                         |
-| **Sizing**     | `w-full`, `h-full`, `w-1`, `max-w-full`                              |
-| **Tipografía** | `text-1`, `text-center`, `font-bold`, `leading-tight`                |
-| **Fondos**     | `bg-1`, `bg-ui`, `bg-cover`, `bg-center`                             |
-| **Bordes**     | `border-sm`, `divide-x`, `outline-none`                              |
-| **Efectos**    | `shadow-md`, `opacity-3`, `overlay-2`                                |
-| **Iconos**     | `icon-1`, `icon-3`                                                   |
+| Categoría      | Ejemplos                                                                                              |
+| -------------- | ----------------------------------------------------------------------------------------------------- |
+| **Layout**     | `flex`, `block`, `hidden`, `relative`, `absolute`, `overflow-hidden`, `inset-0`, `inset-x-sm`, `z-10` |
+| **Flex/Grid**  | `flex-col`, `flex-wrap`, `items-center`, `justify-between`, `gap-md`                                  |
+| **Spacing**    | `p-sm`, `pt-lg`, `mx-auto`, `mt-xs`, `mb-md`                                                          |
+| **Sizing**     | `w-full`, `h-full`, `w-1/2`, `w-2/3`, `h-1/4`, `max-w-full`                                           |
+| **Tipografía** | `text-1`, `text-center`, `font-bold`, `font-light`, `leading-snug`, `tracking-tight`                  |
+| **Fondos**     | `bg-1`, `bg-ui`, `bg-cover`, `bg-center`                                                              |
+| **Bordes**     | `border-sm`, `border-1`, `border-t-sm`, `divide-x`, `outline-none`                                    |
+| **Efectos**    | `shadow-md`, `opacity-3`, `overlay-2`                                                                 |
+| **Iconos**     | `icon-1`, `icon-3`                                                                                    |
 
 ## Build
 
 ```bash
-npm run build       # Compila TS + genera dist/grisso.css (~156 KB)
+npm run build       # Compila TS + genera dist/grisso.css (~154 KB)
 npm run typecheck   # Type-check sin emitir (tsc --noEmit)
 npm run lint        # Lint con Biome
 npm test            # Tests con Vitest
@@ -255,27 +327,20 @@ npm run test:watch  # Tests en modo watch
 npm run playground  # Build + tree-shake + abre playground/index.html
 ```
 
-### Build script
+### CLI
 
-El script de build acepta flags opcionales:
-
-```bash
-node scripts/build.js                                                  # Full build → dist/grisso.css
-node scripts/build.js --config grisso.config.mjs                       # Con config personalizada
-node scripts/build.js --content "src/**/*.html" --output out.css       # Tree-shaken
-node scripts/build.js --config conf.mjs --content "src/**" --output x  # Todo junto
-```
+El CLI se usa internamente y está disponible para consumidores via `npx grisso build`. Ver [CLI](#cli) para detalles completos.
 
-Con `--content`, se usa PurgeCSS para eliminar clases no usadas (156 KB → ~4 KB en el playground).
+Con `--content`, se usa PurgeCSS para eliminar clases no usadas (~154 KB → ~4 KB en el playground).
 
 ## Desarrollo: Añadir nuevas utilities
 
-1. Edita el partial correspondiente en `src/js/partials/{category}.ts`
+1. Edita el partial correspondiente en `src/partials/{category}.ts`
 2. Usa `simpleClass`, `complexClass` o `customClass` con los tokens del config
 3. Ejecuta `npm run build`
 
 ```ts
-// src/js/partials/layout.ts
+// src/partials/layout.ts
 import { simpleClass, complexClass } from "../generators.js";
 
 // Clase simple — genera .flex + variantes responsive