holygrail5 1.0.2 → 1.0.3

package/README.md

@@ -1,47 +1,55 @@
 # HolyGrail5
 
+[![npm version](https://img.shields.io/npm/v/holygrail5.svg)](https://www.npmjs.com/package/holygrail5)
+[![npm downloads](https://img.shields.io/npm/dm/holygrail5.svg)](https://www.npmjs.com/package/holygrail5)
+
 Framework CSS generator con Node.js que genera CSS optimizado con variables CSS compartidas desde un archivo JSON de configuración.
 
-## ⚖️ En resumen
+## 📦 Instalación
 
-| Aspecto                  | Solo Tailwind                                                                 | Híbrido                              |
-|--------------------------|-------------------------------------------------------------------------------|---------------------------------------------------------------------|
-| Velocidad de desarrollo  | 🔥 Muy alta                                                                   | 🔥 Alta                                                            |
-| Consistencia visual      | ⚠️ Difícil mantener si hay muchas utilidades                                 | ✅ Mantienes branding y coherencia                                  |
-| Escalabilidad            | ⚠️ Costoso en proyectos grandes                                               | ✅ Fácil de mantener                                                |
-| Curva de aprendizaje     | Media                                                                         | Baja si ya vienes de BEM/SCSS                                      |
-| Control sobre design system   | ❌ Limitado                                                            | ✅ Total                                                           |
-| Performance CSS final    | ✅ Muy buena                                                                   | ✅ Muy buena                                                       |
+```bash
+# Instalación global
+npm install -g holygrail5
 
+# Instalación local
+npm install holygrail5
+```
 
+## 🚀 Inicio Rápido
 
-## ✨ Características
+```bash
+# 1. Generar CSS y HTML
+npx holygrail5
+
+# 2. Ver la guía interactiva
+npm run serve
+# Abre http://localhost:3000/index.html
+```
+
+## ✨ Características Principales
 
 - 🎨 **CSS optimizado** con variables CSS compartidas (mínimas y eficientes)
 - 📱 **Soporte responsive** con breakpoints personalizables (mobile/desktop)
 - 🔧 **Configuración simple** mediante JSON
 - 📊 **Guía HTML interactiva** generada automáticamente con detección de cambios
-- 🎯 **Variables compartidas** basadas en valores únicos
-- 🔄 **Conversión automática** de px a rem
-- 🛠️ **Helpers de spacing** (padding y margin) estilo Tailwind con propiedades lógicas (RTL)
+- 🛠️ **Helpers de spacing** estilo Tailwind con propiedades lógicas (RTL)
 - 🎨 **Sistema de colores** con variables CSS
 - 📐 **Helpers de layout** (display, flexbox, alignment, gap)
 - 👀 **Modo watch** para desarrollo con regeneración automática
-- ✅ **Validación robusta** de configuración
-- 🧪 **Suite de tests** incluida
 - 🔍 **Gestión de variables CSS** con historial persistente
 
-## 📦 Instalación
+## ⚖️ ¿Por qué HolyGrail5?
 
-```bash
-# Instalación global
-npm install -g holygrail5
-
-# Instalación local
-npm install holygrail5
-```
+| Aspecto                  | Solo Tailwind                                                                 | HolyGrail5 (Híbrido)                              |
+|--------------------------|-------------------------------------------------------------------------------|---------------------------------------------------------------------|
+| Velocidad de desarrollo  | 🔥 Muy alta                                                                   | 🔥 Alta                                                            |
+| Consistencia visual      | ⚠️ Difícil mantener si hay muchas utilidades                                 | ✅ Mantienes branding y coherencia                                  |
+| Escalabilidad            | ⚠️ Costoso en proyectos grandes                                               | ✅ Fácil de mantener                                                |
+| Curva de aprendizaje     | Media                                                                         | Baja si ya vienes de BEM/SCSS                                      |
+| Control sobre design system   | ❌ Limitado                                                            | ✅ Total                                                           |
+| Performance CSS final    | ✅ Muy buena                                                                   | ✅ Muy buena                                                       |
 
-## 🚀 Uso
+## 📖 Uso
 
 ### CLI
 
@@ -65,7 +73,7 @@ const css = generateCSS(config);
 const html = generateHTML(config);
 ```
 
-### Desarrollo
+### Scripts de Desarrollo
 
 ```bash
 # Modo watch (regenera automáticamente al cambiar config.json)
@@ -81,7 +89,7 @@ npm run serve
 npm run start
 ```
 
-**Nota:** El servidor sirve desde `dist/` como raíz, así que la URL será `http://localhost:3000/index.html` (sin mostrar "dist" en la URL).
+> **Nota:** El servidor sirve desde `dist/` como raíz, así que la URL será `http://localhost:3000/index.html` (sin mostrar "dist" en la URL).
 
 ## ⚙️ Configuración
 
@@ -105,8 +113,7 @@ npm run start
     "4": "4px",
     "8": "8px",
     "16": "16px",
-    "24": "24px",
-    "32": "32px"
+    "24": "24px"
   },
   "spacingImportant": ["0"],
   "colors": {
@@ -121,17 +128,7 @@ npm run start
       "class": "d",
       "responsive": true,
       "description": "Tipo de caja de renderizado",
-      "values": ["contents", "inline", "inline-block", "block", "flex", "inline-flex", "none"]
-    },
-    "flex-direction": {
-      "property": "flex-direction",
-      "class": "flex",
-      "responsive": true,
-      "description": "Dirección del eje principal",
-      "values": {
-        "row": "row",
-        "column": "column"
-      }
+      "values": ["flex", "block", "none"]
     }
   },
   "classes": {
@@ -153,7 +150,7 @@ npm run start
 }
 ```
 
-### Propiedades globales
+### Propiedades Globales
 
 | Propiedad | Tipo | Default | Descripción |
 |-----------|------|---------|-------------|
@@ -168,7 +165,7 @@ npm run start
 | `helpers` | object | - | Helpers de layout (display, flexbox, etc.) |
 | `classes` | object | **Requerido** | Clases CSS de tipografía a generar |
 
-### Propiedades de clases
+### Propiedades de Clases
 
 **Base (aplicadas a todos los breakpoints):**
 
@@ -178,62 +175,10 @@ npm run start
 - `textTransform`: Transformación (none, uppercase, lowercase)
 
 **Responsive (por breakpoint):**
+
 - `mobile`: `{ fontSize: "18px", lineHeight: "1.2" }`
 - `desktop`: `{ fontSize: "24px", lineHeight: "1.5" }`
 
-## 📄 Salida
-
-### `dist/output.css`
-
-CSS generado con estructura organizada:
-
-1. **Reset CSS Mínimo** - Normalización básica
-2. **Variables CSS Compartidas** (`:root`) - Variables para:
-
-   - Font families
-   - Font sizes
-   - Line heights
-   - Font weights
-   - Letter spacing
-   - Text transform
-   - Spacing values
-   - Colors
-3. **Helpers de Spacing (Mobile)** - Padding y margin con propiedades lógicas
-4. **Helpers de Spacing (Desktop)** - Versiones `md:` con media queries
-5. **Layout Helpers** - Display, flexbox, alignment, gap
-6. **Tipografías (Mobile)** - Clases responsive para mobile
-7. **Tipografías (Desktop)** - Clases responsive para desktop
-   - Font families
-   - Font sizes
-   - Line heights
-   - Font weights
-   - Letter spacing
-   - Text transform
-   - Spacing values
-   - Colors
-3. **Helpers de Spacing (Mobile)** - Padding y margin con propiedades lógicas
-4. **Helpers de Spacing (Desktop)** - Versiones `md:` con media queries
-5. **Layout Helpers** - Display, flexbox, alignment, gap
-6. **Tipografías (Mobile)** - Clases responsive para mobile
-7. **Tipografías (Desktop)** - Clases responsive para desktop
-
-### `dist/index.html`
-
-Guía HTML interactiva generada en la carpeta `dist/` con:
-
-- 🎨 **Sección de Colores** - Grid visual con preview de colores
-- 🔤 **Font Families** - Tabla con preview de fuentes
-- 📝 **Clases de Tipografía** - Tabla completa con preview y valores responsive
-- 🔗 **Variables CSS Compartidas** - Todas las variables generadas
-- 📏 **Helpers de Spacing** - Tabla con clases y variables
-- 📐 **Helpers de Layout** - Tabla con clases base y responsive (`md:`)
-- 📱 **Breakpoints** - Configuración de breakpoints
-- 🔍 **Búsqueda en tiempo real** - Filtra y resalta contenido
-- 🎯 **Detección de cambios** - Valores modificados se resaltan en verde
-- 📌 **Header sticky** - Navegación siempre visible
-- 📋 **Menú lateral** - Navegación rápida entre secciones
-- 📊 **Metadata** - Último commit y versión del package
-
 ## 🎯 Helpers de Spacing
 
 Genera clases estilo Tailwind para padding y margin con **propiedades lógicas** para soporte RTL automático:
@@ -335,40 +280,64 @@ Genera helpers para display, flexbox, alignment y gap:
 }
 ```
 
+## 📄 Archivos Generados
+
+### `dist/output.css`
+
+CSS generado con estructura organizada:
+
+1. **Reset CSS Mínimo** - Normalización básica
+2. **Variables CSS Compartidas** (`:root`) - Variables para:
+   - Font families, font sizes, line heights
+   - Font weights, letter spacing, text transform
+   - Spacing values, colors
+3. **Helpers de Spacing (Mobile)** - Padding y margin con propiedades lógicas
+4. **Helpers de Spacing (Desktop)** - Versiones `md:` con media queries
+5. **Layout Helpers** - Display, flexbox, alignment, gap
+6. **Tipografías (Mobile)** - Clases responsive para mobile
+7. **Tipografías (Desktop)** - Clases responsive para desktop
+
+### `dist/index.html`
+
+Guía HTML interactiva generada automáticamente con:
+
+- 🎨 **Grid de colores** - Visualización de la paleta de colores con preview
+- 🔤 **Font Families** - Tabla con preview de fuentes
+- 📝 **Clases de Tipografía** - Tabla completa con preview y valores responsive
+- 🔗 **Variables CSS Compartidas** - Todas las variables generadas
+- 📏 **Helpers de Spacing** - Tabla con clases y variables
+- 📐 **Helpers de Layout** - Tabla con clases base y responsive (`md:`)
+- 📱 **Breakpoints** - Configuración de breakpoints
+- 🔍 **Búsqueda en tiempo real** - Filtra y resalta contenido
+- 🎯 **Detección de cambios** - Valores modificados se resaltan en verde
+- 📌 **Header sticky** - Navegación siempre visible
+- 📋 **Menú lateral** - Navegación rápida con scroll suave
+- 📊 **Metadata** - Último commit y versión del package
+
 ## 🔍 Gestión de Variables CSS
 
 El generador mantiene un historial de todas las variables CSS generadas en `.data/.historical-variables.json` para que nunca se eliminen automáticamente, incluso si se borran las clases que las usaban.
 
-### Comandos disponibles
+### Comandos Disponibles
 
 ```bash
 # Listar variables no usadas
 npm run vars:list
-# o
-node src/cli-variables.js list
 
 # Ver reporte completo de variables
 npm run vars:report
-# o
-node src/cli-variables.js report
 
 # Eliminar una variable específica del historial
 npm run vars:remove -- --hg-typo-font-size-18
-# o
-node src/cli-variables.js remove --hg-typo-font-size-18
 
 # Eliminar todas las variables no usadas del historial
 npm run vars:remove-all-unused
-# o
-node src/cli-variables.js remove-all-unused
 
 # Mostrar todas las variables históricas almacenadas
 npm run vars:show-all
-# o
-node src/cli-variables.js show-all
 ```
 
-### Ejemplo de uso
+### Ejemplo de Uso
 
 ```bash
 # 1. Generar CSS
@@ -384,7 +353,7 @@ npm run vars:remove-all-unused
 npm run generate
 ```
 
-### Opciones avanzadas
+### Opciones Avanzadas
 
 ```bash
 # Especificar ruta personalizada del CSS
@@ -410,38 +379,43 @@ node src/cli-variables.js list --history=./.data/.custom-variables.json
 | `npm run vars:remove-all-unused` | Elimina todas las variables no usadas |
 | `npm run vars:show-all` | Muestra todas las variables históricas |
 
-## 🏗️ Estructura del proyecto
+## 🔑 Características Técnicas
 
-```
-holygrail5/
-├── generator.js              # Orquestador principal
-├── config.json               # Configuración del proyecto
-├── package.json              # Dependencias y scripts
-├── README.md                 # Este archivo
-├── .data/                    # Archivos de estado (gitignored)
-│   ├── .previous-values.json      # Valores previos para detección de cambios
-│   └── .historical-variables.json # Historial de variables CSS
-├── dist/                     # Archivos generados (gitignored)
-│   ├── output.css           # CSS generado
-│   └── index.html           # Guía HTML interactiva
-├── src/
-│   ├── config.js            # Carga y validación de configuración
-│   ├── parser.js            # Generación de CSS desde JSON
-│   ├── guide.js             # Generación de guía HTML interactiva
-│   ├── utils.js             # Utilidades compartidas (px→rem, etc.)
-│   ├── variables-manager.js # Gestión de variables CSS históricas
-│   ├── cli-variables.js     # CLI para gestión de variables
-│   ├── watch.js             # Modo watch para desarrollo
-│   └── dev.js               # Script de desarrollo (watch + servidor)
-└── tests/
-    ├── run-all.js           # Ejecutor de todos los tests
-    ├── config.test.js       # Tests de configuración
-    ├── parser.test.js       # Tests del parseador
-    ├── guide.test.js        # Tests de la guía HTML
-    └── utils.test.js        # Tests de utilidades
-```
+### Variables Compartidas
+
+Las variables se generan basándose en **valores únicos**, no en clases:
 
-## 🎨 Ejemplo de CSS generado
+- Múltiples clases con `fontWeight: "900"` → una sola variable `--hg-typo-font-weight-900`
+- Optimiza el CSS eliminando duplicados
+- Historial persistente en `.data/.historical-variables.json`
+
+### Conversión px → rem
+
+- `fontSize` en JSON: `"18px"` → CSS: `1.125rem` (usando `baseFontSize: 16`)
+- Nombre de variable mantiene el valor original: `--hg-typo-font-size-18`
+- Conversión automática para todos los valores en píxeles
+
+### Nombres de Variables
+
+Patrón: `--{prefix}-{category}-{propiedad}-{valor}`
+
+Ejemplos:
+
+- `--hg-typo-font-family-primary`
+- `--hg-typo-font-size-18`
+- `--hg-spacing-4`
+- `--hg-color-white`
+
+### Propiedades Lógicas (RTL)
+
+Los helpers de spacing usan propiedades lógicas para soporte RTL automático:
+
+- `pr-4` → `padding-inline-end` (no `padding-right`)
+- `pl-4` → `padding-inline-start` (no `padding-left`)
+- `mr-8` → `margin-inline-end` (no `margin-right`)
+- `ml-8` → `margin-inline-start` (no `margin-left`)
+
+## 🎨 Ejemplo de CSS Generado
 
 ```css
 /* Reset CSS Mínimo */
@@ -503,66 +477,38 @@ html {
 }
 ```
 
-## 🔑 Características técnicas
+## 🏗️ Estructura del Proyecto
 
-#### Variables compartidas
-
-Las variables se generan basándose en **valores únicos**, no en clases:
-
-- Múltiples clases con `fontWeight: "900"` → una sola variable `--hg-typo-font-weight-900`
-- Optimiza el CSS eliminando duplicados
-- Historial persistente en `.data/.historical-variables.json`
-
-#### Conversión px → rem
-
-- `fontSize` en JSON: `"18px"` → CSS: `1.125rem` (usando `baseFontSize: 16`)
-- Nombre de variable mantiene el valor original: `--hg-typo-font-size-18`
-- Conversión automática para todos los valores en píxeles
-
-#### Nombres de variables
-
-Patrón: `--{prefix}-{category}-{propiedad}-{valor}`
-
-Ejemplos:
-
-- `--hg-typo-font-family-primary`
-- `--hg-typo-font-size-18`
-- `--hg-spacing-4`
-- `--hg-color-white`
-
-#### Propiedades lógicas (RTL)
-
-Los helpers de spacing usan propiedades lógicas para soporte RTL automático:
-
-- `pr-4` → `padding-inline-end` (no `padding-right`)
-- `pl-4` → `padding-inline-start` (no `padding-left`)
-- `mr-8` → `margin-inline-end` (no `margin-right`)
-- `ml-8` → `margin-inline-start` (no `margin-left`)
-
-## 📊 Guía HTML Interactiva
-
-La guía HTML generada en `dist/index.html` incluye:
-
-#### Características
-
-- 🎨 **Grid de colores** - Visualización de la paleta de colores con preview
-- 🔤 **Font Families** - Tabla con preview de fuentes
-- 📝 **Tipografía** - Tabla completa con preview y valores mobile/desktop
-- 🔗 **Variables CSS** - Todas las variables generadas con valores
-- 📏 **Helpers de Spacing** - Clases y variables de padding/margin
-- 📐 **Helpers de Layout** - Display, flexbox, alignment, gap
-- 📱 **Breakpoints** - Configuración de breakpoints
-
-#### Funcionalidades interactivas
-
-- 🔍 **Búsqueda en tiempo real** - Filtra y resalta contenido en todas las tablas
-- 🎯 **Detección de cambios** - Valores modificados se resaltan en verde
-- 📌 **Header sticky** - Navegación y búsqueda siempre visibles
-- 📋 **Menú lateral** - Navegación rápida con scroll suave
-- 📊 **Metadata** - Último commit de Git y versión del package
-- 🔄 **Cache busting** - Timestamp en CSS para forzar recarga
+```
+holygrail5/
+├── generator.js              # Orquestador principal
+├── config.json               # Configuración del proyecto
+├── package.json              # Dependencias y scripts
+├── README.md                 # Este archivo
+├── .data/                    # Archivos de estado (gitignored)
+│   ├── .previous-values.json      # Valores previos para detección de cambios
+│   └── .historical-variables.json # Historial de variables CSS
+├── dist/                     # Archivos generados (gitignored)
+│   ├── output.css           # CSS generado
+│   └── index.html           # Guía HTML interactiva
+├── src/
+│   ├── config.js            # Carga y validación de configuración
+│   ├── parser.js            # Generación de CSS desde JSON
+│   ├── guide.js             # Generación de guía HTML interactiva
+│   ├── utils.js             # Utilidades compartidas (px→rem, etc.)
+│   ├── variables-manager.js # Gestión de variables CSS históricas
+│   ├── cli-variables.js     # CLI para gestión de variables
+│   ├── watch.js             # Modo watch para desarrollo
+│   └── dev.js               # Script de desarrollo (watch + servidor)
+└── tests/
+    ├── run-all.js           # Ejecutor de todos los tests
+    ├── config.test.js       # Tests de configuración
+    ├── parser.test.js       # Tests del parseador
+    ├── guide.test.js        # Tests de la guía HTML
+    └── utils.test.js        # Tests de utilidades
+```
 
-## 🐛 Solución de problemas
+## 🐛 Solución de Problemas
 
 **Error: "Archivo de configuración no encontrado"**
 
@@ -595,14 +541,17 @@ Para desplegar en GitHub Pages, puedes:
 2. O crear un workflow de GitHub Actions que genere los archivos en `docs/` automáticamente
 
 **Opción 1 - Usar dist/ directamente:**
+
 - En Settings → Pages, selecciona la rama y carpeta `dist/`
 
 **Opción 2 - Workflow automático:**
+
 - Crea `.github/workflows/deploy.yml` que ejecute `npm run generate` y copie archivos a `docs/`
 
 ## 📚 Recursos
 
 - **Repositorio**: [GitHub](https://github.com/holygrailcss/holygrail5.git)
+- **npm**: [holygrail5](https://www.npmjs.com/package/holygrail5)
 - **Licencia**: MIT
 - **Node.js**: Requiere >=12.0.0
 
@@ -617,6 +566,7 @@ Para desplegar en GitHub Pages, puedes:
 ## 📝 Changelog
 
 ### v1.0.2
+
 - ✅ Sistema de colores con variables CSS
 - ✅ Helpers de layout (display, flexbox, alignment, gap)
 - ✅ Propiedades lógicas para soporte RTL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holygrail5",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Framework CSS generator con Node.js - Genera CSS optimizado con variables CSS desde un archivo JSON de configuración",
   "main": "generator.js",
   "bin": {

package/src/guide.js

@@ -1146,6 +1146,7 @@ function generateHTML(configData, previousValuesPath = null) {
       background: white;
       border-right: 1px solid #e0e0e0;
       padding: 2rem 0;
+      padding-bottom: 120px;
       overflow-y: auto;
       z-index: 100;
       box-shadow: 2px 0 8px rgba(0,0,0,0.05);
@@ -1167,6 +1168,28 @@ function generateHTML(configData, previousValuesPath = null) {
     .sidebar-nav {
       padding: 0 1rem;
     }
+
+    .sidebar-footer {
+      position: absolute;
+      bottom: 0;
+      left: 0;
+      right: 0;
+      padding: 1rem 1.5rem .5rem 1.5rem;
+      border-top: 1px solid #e0e0e0;
+      background: white;
+    }
+
+    .sidebar-badges {
+      display: flex;
+      flex-direction: column;
+      gap: 0.5rem;
+      align-items: flex-start;
+    }
+
+    .sidebar-badges img {
+      height: 20px;
+      width: auto;
+    }
     
     .menu-item {
       display: block;
@@ -1315,6 +1338,15 @@ function generateHTML(configData, previousValuesPath = null) {
     <nav class="sidebar-nav">
       ${menuHTML}
     </nav>
+    
+    <div class="sidebar-footer">
+      <div class="sidebar-badges">
+        <a href="https://www.npmjs.com/package/holygrail5" target="_blank" rel="noopener noreferrer">
+          <img src="https://img.shields.io/npm/v/holygrail5.svg" alt="npm version" />
+        </a>
+
+      </div>
+    </div>
   </aside>
   
   <main class="main-content">