@hiscovega/grisso 1.0.5 → 1.0.7

package/README.md

@@ -1,6 +1,9 @@
 # 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 variantes responsive y de estado, basada en CSS custom properties (design tokens).
+
+> [!WARNING]
+> En la versión estable 2.0, el paquete se moverá a `@griddo/grisso`. El nombre actual `@hiscovega/grisso` dejará de recibir actualizaciones a partir de ese momento.
 
 ## Instalación
 
@@ -10,24 +13,9 @@ npm install @hiscovega/grisso
 
 ## Uso
 
-### Opción A: CSS directo
-
-Importa el CSS pre-compilado directamente. Útil para desarrollo.
-
-```css
-/* En tu CSS global */
-@import "@hiscovega/grisso";
-```
-
-O en HTML:
-
-```html
-<link rel="stylesheet" href="node_modules/@hiscovega/grisso/dist/grisso.css" />
-```
-
-### Opción B: CLI
+### CLI
 
-Genera CSS desde la terminal. Ideal para scripts de build y CI/CD.
+Genera CSS desde la terminal. Forma recomendada de usar Grisso, ideal para scripts de build y CI/CD.
 
 ```bash
 # CSS completo a stdout
@@ -42,6 +30,9 @@ 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
 
+# Proteger clases del tree-shaking
+npx grisso build --content "src/**/*.tsx" --safelist "^p-" --safelist "^m-" --output dist/grisso.css
+
 # Sin minificar (útil para depuración)
 npx grisso build --no-minify --output dist/grisso.css
 
@@ -51,17 +42,61 @@ npx grisso build | pbcopy
 
 **Flags de `grisso build`:**
 
-| Flag | Descripción |
-|---|---|
-| `--config <ruta>` | Ruta a `grisso.config.mjs` |
-| `--content <glob>` | Globs para tree-shaking (repetible) |
-| `--output <ruta>` | Archivo de salida (sin `--output` → stdout) |
-| `--no-minify` | Deshabilitar minificación |
-| `--help, -h` | Ayuda del comando |
+| 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                           |
 
 Sin `--output`, el CSS va a stdout y los mensajes de estado a stderr, siguiendo la convención Unix.
 
-### Opción C: API programática
+#### `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
+```
+
+**Flags de `grisso tokens`:**
+
+| 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: ;
+	/* ... */
+}
+```
+
+### API programática
 
 Usa `buildCSS()` directamente desde Node.js. Genera, purga y optimiza CSS — ideal para scripts de build, herramientas custom o integración con cualquier bundler.
 
@@ -74,11 +109,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.
 
@@ -144,6 +180,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
@@ -161,7 +221,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
@@ -173,7 +233,14 @@ export default {
     lg: "24px",
   },
 
-  // `extend` MERGEA con los defaults
+  // States: reemplaza los 5 defaults (hover, focus, focus-visible, active, disabled)
+  // Solo genera variantes para los estados listados
+  states: {
+    hover: ":hover",
+    focus: ":focus",
+  },
+
+  // `extend` MERGEA con los defaults (arrays se concatenan)
   extend: {
     foregroundColors: {
       5: "var(--text-5)",
@@ -181,17 +248,30 @@ export default {
     shadows: {
       "2xl": "var(--box-shadow-2xl)",
     },
+    // Se concatena con el default []
+    safelist: [/^p-/],
   },
 };
 ```
 
+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`.
+
+Los `states` controlan qué variantes de estado se generan. Cada entrada es `nombre: pseudo-clase`. Top-level reemplaza completamente; `extend.states` mergea con 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
@@ -220,10 +300,10 @@ Importa los tokens antes que Grisso en tu CSS global:
 ### Nomenclatura
 
 ```
-{breakpoint}-{propiedad}-{escala}
+{breakpoint}-{state}-{propiedad}-{escala}
 ```
 
-Ejemplos: `flex`, `tablet-flex`, `p-md`, `desktop-mt-lg`, `text-center`, `w-1/2`, `z-10`, `tracking-tight`
+Ejemplos: `flex`, `tablet-flex`, `p-md`, `hover-bg-1`, `focus-border-1`, `tablet-hover-p-sm`, `desktop-mt-lg`, `w-1/2`
 
 ### Breakpoints (mobile-first)
 
@@ -234,24 +314,40 @@ Ejemplos: `flex`, `tablet-flex`, `p-md`, `desktop-mt-lg`, `text-center`, `w-1/2`
 | `desktop-`      | 1024px+ |
 | `ultrawide-`    | 1680px+ |
 
+### State variants
+
+Todas las utilidades generan variantes de estado automáticamente. El tree-shaking elimina las no usadas.
+
+| Prefijo            | Pseudo-clase     |
+| ------------------ | ---------------- |
+| `hover-`           | `:hover`         |
+| `focus-`           | `:focus`         |
+| `focus-visible-`   | `:focus-visible` |
+| `active-`          | `:active`        |
+| `disabled-`        | `:disabled`      |
+
+Se combinan con breakpoints: `tablet-hover-bg-1`, `desktop-focus-p-sm`.
+
+Orden del cascade: base → state → responsive → responsive+state.
+
 ### Categorías
 
-| Categoría      | Ejemplos                                                                      |
-| -------------- | ----------------------------------------------------------------------------- |
+| 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`                                                            |
+| **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 (~154 KB)
+npm run build       # Compila TS + genera dist/grisso.css (~800 KB)
 npm run typecheck   # Type-check sin emitir (tsc --noEmit)
 npm run lint        # Lint con Biome
 npm test            # Tests con Vitest
@@ -261,9 +357,9 @@ npm run playground  # Build + tree-shake + abre playground/index.html
 
 ### CLI
 
-El CLI se usa internamente y está disponible para consumidores via `npx grisso build`. Ver [Opción B: CLI](#opción-b-cli) para detalles completos.
+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 (~154 KB → ~4 KB en el playground).
+Con `--content`, se usa PurgeCSS para eliminar clases no usadas (~800 KB → ~4 KB en el playground).
 
 ## Desarrollo: Añadir nuevas utilities
 
@@ -275,11 +371,11 @@ Con `--content`, se usa PurgeCSS para eliminar clases no usadas (~154 KB → ~4
 // src/partials/layout.ts
 import { simpleClass, complexClass } from "../generators.js";
 
-// Clase simple — genera .flex + variantes responsive
-simpleClass("flex", "display", "flex", breakpoints);
+// Clase simple — genera .flex + variantes de estado y responsive
+simpleClass("flex", "display", "flex", breakpoints, states);
 
-// Clase basada en tokens — genera .p-xs, .p-sm, etc. + variantes responsive
-complexClass("p-", "padding", spacing, breakpoints);
+// Clase basada en tokens — genera .p-xs, .hover-p-xs:hover, .tablet-p-xs, etc.
+complexClass("p-", "padding", spacing, breakpoints, states);
 ```
 
 ## Publicación (release)