@hiscovega/grisso 1.0.3 → 1.0.5

package/README.md

@@ -5,67 +5,71 @@
 ## Instalación
 
 ```bash
-npm install @griddo/grisso
+npm install @hiscovega/grisso
 ```
 
 ## Uso
 
 ### Opción A: CSS directo
 
-Importa el CSS pre-compilado directamente. Útil para desarrollo o cuando no usas PostCSS.
+Importa el CSS pre-compilado directamente. Útil para desarrollo.
 
 ```css
 /* En tu CSS global */
-@import "@griddo/grisso";
+@import "@hiscovega/grisso";
 ```
 
 O en HTML:
 
 ```html
-<link rel="stylesheet" href="node_modules/@griddo/grisso/dist/grisso.css" />
+<link rel="stylesheet" href="node_modules/@hiscovega/grisso/dist/grisso.css" />
 ```
 
-### Opción B: PostCSS plugin (recomendado — con tree-shaking)
+### Opción B: CLI
 
-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.
+Genera CSS desde la terminal. Ideal para scripts de build y CI/CD.
 
-```js
-// postcss.config.js
-import grisso from "@griddo/grisso/plugin";
+```bash
+# CSS completo a stdout
+npx grisso build
 
-export default {
-  plugins: [
-    grisso({
-      content: ["./src/**/*.{js,ts,jsx,tsx,css}"],
-    }),
-  ],
-};
-```
+# Escribir a archivo
+npx grisso build --output dist/grisso.css
 
-Sin `content`, se incluye todo el CSS (útil en desarrollo):
+# Con config personalizada
+npx grisso build --config grisso.config.mjs --output dist/grisso.css
 
-```js
-grisso();
+# Tree-shaking (solo clases usadas)
+npx grisso build --content "src/**/*.tsx" --content "src/**/*.css" --output 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 C: API programática (sin PostCSS)
+**Flags de `grisso build`:**
 
-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.
+| 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 |
+
+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
+
+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 "@griddo/grisso/build";
+import { buildCSS } from "@hiscovega/grisso/build";
 
 // Build completo (todo el CSS, minificado)
 const css = await buildCSS();
-
-// Build con tree-shaking
-const css = await buildCSS({
-  content: ["./src/**/*.{js,ts,jsx,tsx,css}"],
-  config: "./grisso.config.mjs",
-});
-
-// Build sin minificar
-const css = await buildCSS({ minify: false });
 ```
 
 **Opciones de `buildCSS()`:**
@@ -78,6 +82,83 @@ const css = await buildCSS({ minify: false });
 
 Sin `content`, se incluye todo el CSS. Con `content`, se eliminan las clases no usadas via PurgeCSS.
 
+#### Ejemplos
+
+**Tree-shaking** — solo las clases que usa tu proyecto:
+
+```js
+const css = await buildCSS({
+  content: ["./src/**/*.{js,ts,jsx,tsx}", "./src/**/*.css"],
+});
+```
+
+**Config personalizada + tree-shaking:**
+
+```js
+const css = await buildCSS({
+  config: "./grisso.config.mjs",
+  content: ["./src/**/*.{js,ts,jsx,tsx,css}"],
+});
+```
+
+**CSS sin minificar** (útil para depuración):
+
+```js
+const css = await buildCSS({ minify: false });
+```
+
+**Script de build** — genera un archivo CSS para producción:
+
+```js
+// scripts/build-css.mjs
+import { writeFileSync } from "node:fs";
+import { buildCSS } from "@hiscovega/grisso/build";
+
+const css = await buildCSS({
+  content: ["./src/**/*.{jsx,tsx,css}"],
+  config: "./grisso.config.mjs",
+});
+
+writeFileSync("./dist/styles.css", css);
+console.log(`CSS generado: ${css.length} bytes`);
+```
+
+**Integración con Vite** (plugin custom):
+
+```js
+// vite.config.js
+import { buildCSS } from "@hiscovega/grisso/build";
+
+export default {
+  plugins: [
+    {
+      name: "grisso",
+      async buildStart() {
+        const css = await buildCSS({
+          content: ["./src/**/*.{jsx,tsx,css}"],
+        });
+        this.emitFile({ type: "asset", fileName: "grisso.css", source: css });
+      },
+    },
+  ],
+};
+```
+
+**Servidor de desarrollo** — generar CSS on-the-fly:
+
+```js
+// Ejemplo con Express
+import express from "express";
+import { buildCSS } from "@hiscovega/grisso/build";
+
+const app = express();
+
+app.get("/grisso.css", async (req, res) => {
+  const css = await buildCSS({ minify: false });
+  res.type("text/css").send(css);
+});
+```
+
 ## 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:
@@ -104,25 +185,16 @@ export default {
 };
 ```
 
-Pasa la ruta al plugin:
+Si no se pasa `config` a `buildCSS()`, busca automáticamente `grisso.config.mjs` en el directorio de trabajo. Si no existe, usa los defaults.
 
-```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.
-
-Los defaults se pueden consultar importando `@griddo/grisso/config`.
+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:
 
 ```bash
-cp node_modules/@griddo/grisso/tokens-example.css src/tokens.css
+cp node_modules/@hiscovega/grisso/tokens-example.css src/tokens.css
 ```
 
 ```css
@@ -140,7 +212,7 @@ Importa los tokens antes que Grisso en tu CSS global:
 
 ```css
 @import "./tokens.css";
-@import "@griddo/grisso"; /* o via plugin de PostCSS */
+@import "@hiscovega/grisso";
 ```
 
 ## Clases disponibles
@@ -151,7 +223,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)
 
@@ -164,22 +236,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
@@ -187,27 +259,20 @@ npm run test:watch  # Tests en modo watch
 npm run playground  # Build + tree-shake + abre playground/index.html
 ```
 
-### Build script
-
-El script de build acepta flags opcionales:
+### CLI
 
-```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 [Opción B: CLI](#opción-b-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