responsive-system 1.0.0

package/ARCHITECTURE.md

@@ -0,0 +1,195 @@
+# 🏗️ Arquitectura del Sistema
+
+## 📦 Sistema Core vs Ejemplos
+
+### ✅ **SISTEMA CORE (Independiente)**
+
+Estos archivos conforman el **sistema responsivo reutilizable**. Puedes eliminar las páginas de ejemplo y el sistema seguirá funcionando.
+
+#### **Plugin**
+```
+src/plugin/
+└── responsiveScalePlugin.js    # ✅ Plugin de Tailwind
+```
+
+#### **Providers**
+```
+src/providers/
+├── index.ts                    # ✅ Barrel exports
+├── ResponsiveProvider.tsx      # ✅ Provider base
+└── ResponsiveLayoutProvider.tsx # ✅ Provider con layouts
+```
+
+#### **Hooks**
+```
+src/hooks/
+├── index.ts                    # ✅ Barrel exports
+├── useResponsive.ts            # ✅ Hook responsivo
+├── useResponsiveLayout.ts      # ✅ Hook unificado
+└── useLayout.ts                # ✅ Hook de layout
+```
+
+#### **Layouts**
+```
+src/layouts/
+├── index.ts                    # ✅ Barrel exports
+├── MainLayout.tsx              # ✅ Layout principal
+├── DefaultLayout.tsx           # ✅ Layout por defecto
+├── SidebarLayout.tsx           # ✅ Layout con sidebar
+├── DashboardLayout.tsx         # ✅ Layout dashboard
+└── MinimalLayout.tsx           # ✅ Layout mínimo
+```
+
+#### **Componentes de Layout**
+```
+src/components/layout/
+├── index.ts                    # ✅ Barrel exports
+├── Navigation.tsx              # ✅ Navegación
+├── Sidebar.tsx                 # ✅ Sidebar
+├── Header.tsx                  # ✅ Header
+└── Footer.tsx                  # ✅ Footer
+```
+
+#### **Context**
+```
+src/context/
+├── index.ts                    # ✅ Barrel exports
+├── ResponsiveLayoutContext.tsx # ✅ Context principal
+├── SidebarContext.tsx          # ✅ Context del sidebar
+└── NavigationContext.tsx       # ✅ Context de navegación
+```
+
+#### **Tipos**
+```
+src/types/
+└── responsive.ts               # ✅ Tipos TypeScript
+```
+
+#### **Constantes**
+```
+src/constants/
+└── breakpoints.ts              # ✅ Configuración de breakpoints
+```
+
+#### **Configuración**
+```
+src/config/
+└── layout.ts                   # ✅ Configuración de layouts
+```
+
+#### **Componentes Auxiliares**
+```
+src/components/
+└── LayoutSwitcher.tsx          # ✅ Selector de layouts
+```
+
+#### **Export Principal**
+```
+src/index.ts                    # ✅ Exportaciones del sistema
+```
+
+---
+
+### 🎨 **EJEMPLOS (Eliminables)**
+
+Estos archivos son **solo para demostración**. Puedes eliminarlos sin afectar el sistema core.
+
+#### **Páginas de Ejemplo**
+```
+src/pages/
+└── ResponsiveTestPage.tsx      # ❌ Ejemplo - Suite de tests
+```
+
+#### **Componentes de Ejemplo**
+```
+src/components/
+└── ResponsiveDemo.tsx          # ❌ Ejemplo - Demo visual
+```
+
+#### **App de Ejemplo**
+```
+src/App.tsx                     # ❌ Ejemplo - Aplicación de prueba
+src/main.tsx                    # ❌ Ejemplo - Entry point
+```
+
+---
+
+### **Paso 1: Actualizar `src/index.ts`**
+```typescript
+// Eliminar estas líneas:
+export { default as ResponsiveTestPage } from './pages/ResponsiveTestPage'
+export { default as ResponsiveDemo } from './components/ResponsiveDemo'
+```
+
+### **Paso 2: Listo ✅**
+El sistema core sigue funcionando perfectamente. Ahora puedes:
+- Instalar el sistema en tu proyecto
+- Importar solo lo que necesites: `import { ResponsiveLayoutProvider, MainLayout } from './index'`
+- Usar el plugin en `tailwind.config.js`
+
+---
+
+## 📖 Uso en Tu Proyecto
+
+### **1. Instalar el Sistema**
+```bash
+# Copiar la carpeta src/ a tu proyecto
+# O publicar como paquete npm
+```
+
+### **2. Configurar Tailwind**
+```js
+// tailwind.config.js
+import responsiveScalePlugin from './src/plugin/responsiveScalePlugin.js'
+
+export default {
+  plugins: [responsiveScalePlugin({ /* config */ })]
+}
+```
+
+### **3. Crear Tu App**
+```tsx
+// TuApp.tsx
+import { ResponsiveLayoutProvider, MainLayout } from './index'
+
+function TuApp() {
+  return (
+    <ResponsiveLayoutProvider defaultLayout="default">
+      <MainLayout>
+        <TuContenido />
+      </MainLayout>
+    </ResponsiveLayoutProvider>
+  )
+}
+```
+
+### **4. Si Necesitas Navegación**
+```tsx
+import { NavigationProvider, useNavigation } from './index'
+
+function TuApp() {
+  return (
+    <NavigationProvider defaultPage="home">
+      <ResponsiveLayoutProvider defaultLayout="default">
+        <MainLayout>
+          <TuContenido />
+        </MainLayout>
+      </ResponsiveLayoutProvider>
+    </NavigationProvider>
+  )
+}
+```
+
+---
+
+## 🎯 Resumen
+
+| Tipo | Archivos | ¿Eliminable? | Función |
+|------|----------|--------------|---------|
+| **Sistema Core** | 30+ archivos | ❌ NO | Sistema responsivo + layouts |
+| **Ejemplos** | 4 archivos | ✅ SÍ | Demostración y pruebas |
+
+**✅ El sistema es 100% independiente de los ejemplos**
+**✅ Puedes eliminar `App.tsx`, `ResponsiveDemo.tsx`, `ResponsiveTestPage.tsx` sin problemas**
+
+

package/INSTALLATION.md

@@ -0,0 +1,403 @@
+# 📦 Instalación en Proyecto Existente
+
+## ¿Es invasivo este sistema?
+
+**RESPUESTA CORTA: NO, es completamente modular y no invasivo.**
+
+El sistema se divide en **2 partes independientes**:
+
+1. **Sistema de Auto-Scaling** (Plugin de Tailwind) - ⚠️ Requiere configuración
+2. **Sistema de Layouts** (Componentes React) - ✅ Completamente opcional
+
+---
+
+## 🎯 Nivel de Invasividad
+
+### ✅ **BAJO IMPACTO** - Solo Auto-Scaling
+
+Si **solo quieres el auto-scaling** (sin layouts):
+
+**Archivos a copiar:** `1 archivo`
+```
+src/plugin/responsiveScalePlugin.js
+```
+
+**Archivos a modificar:** `1 archivo`
+```
+tailwind.config.js  (agregar plugin)
+```
+
+**¿Rompe código existente?** **NO**
+- El plugin solo agrega CSS variables nuevas
+- No modifica clases existentes de Tailwind
+- Tu código actual sigue funcionando igual
+
+---
+
+### ⚠️ **MEDIO IMPACTO** - Con Providers
+
+Si quieres usar **hooks** (`useResponsive`, etc.):
+
+**Archivos a copiar:** `~10 archivos`
+```
+src/plugin/responsiveScalePlugin.js
+src/providers/ResponsiveProvider.tsx
+src/hooks/useResponsive.ts
+src/constants/breakpoints.ts
+src/types/responsive.ts
+```
+
+**Archivos a modificar:** `2 archivos`
+```
+tailwind.config.js  (agregar plugin)
+App.tsx            (envolver con provider)
+```
+
+**¿Rompe código existente?** **NO**
+- Solo necesitas agregar `<ResponsiveProvider>` en tu App
+- No afecta componentes existentes
+- Puedes usar solo en componentes nuevos
+
+---
+
+### 🔧 **ALTO IMPACTO** - Sistema Completo + Layouts
+
+Si quieres **todo el sistema** (auto-scaling + layouts + hooks):
+
+**Archivos a copiar:** `~30 archivos`
+
+**Archivos a modificar:** `2-3 archivos`
+```
+tailwind.config.js
+App.tsx
+package.json (si faltan dependencias)
+```
+
+**¿Rompe código existente?** **DEPENDE**
+- Si usas `MainLayout`, necesitas adaptar tu estructura
+- Tus componentes existentes **NO se rompen**
+- Puedes migrar progresivamente
+
+---
+
+## 📋 Guía de Instalación Paso a Paso
+
+### **OPCIÓN 1: Solo Auto-Scaling** ⭐ **RECOMENDADA PARA EMPEZAR**
+
+#### 1. Copiar el plugin
+```bash
+# Crear carpeta
+mkdir -p src/plugin
+
+# Copiar archivo
+cp responsiveScalePlugin.js src/plugin/
+```
+
+#### 2. Modificar `tailwind.config.js`
+```js
+import responsiveScalePlugin from './src/plugin/responsiveScalePlugin.js'
+
+export default {
+  content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
+  theme: {
+    extend: {
+      screens: {
+        'xs': '475px',
+        'sm': '640px',
+        'md': '768px',
+        'lg': '1024px',
+        'xl': '1280px',
+        '2xl': '1536px',
+        '3xl': '1920px',  // 👈 Nuevo
+        '4xl': '2560px',  // 👈 Nuevo
+        '5xl': '3840px',  // 👈 Nuevo (4K)
+      }
+    },
+  },
+  plugins: [
+    responsiveScalePlugin({
+      scaleProperties: {
+        typography: true,      // font-size se escala
+        spacing: true,         // padding, margin, gap se escalan
+        lineHeight: true,      // line-height se escala
+        letterSpacing: true,   // letter-spacing se escala
+        shadows: true,         // box-shadow se escala
+        borderWidth: false,    // border-width NO se escala (puede romper)
+        sizing: false,         // width, height NO se escalan (puede romper)
+        borderRadius: false    // rounded-* NO se escala (mantener fijo)
+      },
+      scales: {
+        xs: 1.0,
+        sm: 1.0,
+        md: 1.0,
+        lg: 1.0,
+        xl: 1.0,
+        '2xl': 1.05,  // +5% en 1536px
+        '3xl': 1.15,  // +15% en 1920px (Full HD)
+        '4xl': 1.25,  // +25% en 2560px (2K)
+        '5xl': 1.35   // +35% en 3840px (4K)
+      },
+      breakpoints: {
+        xs: '475px',
+        sm: '640px',
+        md: '768px',
+        lg: '1024px',
+        xl: '1280px',
+        '2xl': '1536px',
+        '3xl': '1920px',
+        '4xl': '2560px',
+        '5xl': '3840px'
+      }
+    })
+  ],
+}
+```
+
+#### 3. ¡Listo! 🎉
+
+**Ya funciona.** Ahora puedes usar:
+
+```tsx
+// Componente existente
+function MyButton() {
+  return (
+    <button className="px-4 py-2 text-base">
+      Click me
+    </button>
+  )
+}
+
+// En móvil: px-4 = 16px
+// En 4K:    px-4 = 21.6px (escalado automáticamente)
+```
+
+**✅ Ventajas:**
+- Cero cambios en tu código
+- Compatible con cualquier proyecto Tailwind
+- No rompe nada existente
+- Puedes ajustar `scales` a tu gusto
+
+**❌ Limitaciones:**
+- No tienes acceso a hooks (`useResponsive`, `isMobile`, etc.)
+- No puedes detectar breakpoints en JavaScript
+
+---
+
+### **OPCIÓN 2: Con Hooks** (Detección de Breakpoints)
+
+Si necesitas **detectar breakpoints en JavaScript** (ej: `isMobile`, `isTablet`):
+
+#### 1. Instalar OPCIÓN 1 primero
+
+#### 2. Copiar archivos adicionales
+```bash
+mkdir -p src/providers src/hooks src/constants src/types
+
+# Copiar archivos core
+cp ResponsiveProvider.tsx src/providers/
+cp useResponsive.ts src/hooks/
+cp breakpoints.ts src/constants/
+cp responsive.ts src/types/
+```
+
+#### 3. Envolver tu App
+```tsx
+// App.tsx (ANTES)
+function App() {
+  return <YourExistingApp />
+}
+
+// App.tsx (DESPUÉS)
+import { ResponsiveProvider } from './providers/ResponsiveProvider'
+
+function App() {
+  return (
+    <ResponsiveProvider>
+      <YourExistingApp />
+    </ResponsiveProvider>
+  )
+}
+```
+
+#### 4. Usar en componentes
+```tsx
+import { useResponsive } from './hooks/useResponsive'
+
+function MyComponent() {
+  const { isMobile, isTablet, currentBreakpoint } = useResponsive()
+
+  return (
+    <div>
+      {isMobile && <MobileMenu />}
+      {isTablet && <TabletView />}
+      <p>Breakpoint actual: {currentBreakpoint}</p>
+    </div>
+  )
+}
+```
+
+**✅ Ventajas adicionales:**
+- Detección de breakpoints en JS
+- Helpers booleanos (isMobile, isTablet, etc.)
+- Condicionales responsive sin CSS
+
+**⚠️ Consideración:**
+- Agrega 1 provider a tu App
+- Agrega ~50KB al bundle (hooks + context)
+
+---
+
+### **OPCIÓN 3: Sistema Completo** (Con Layouts)
+
+Si quieres **layouts preconfigurados** (tipo Ant Design):
+
+#### 1. Instalar OPCIÓN 2 primero
+
+#### 2. Copiar carpetas adicionales
+```bash
+mkdir -p src/layouts src/components/layout src/context
+
+# Copiar todo el sistema de layouts
+cp -r layouts/* src/layouts/
+cp -r components/layout/* src/components/layout/
+cp -r context/* src/context/
+cp ResponsiveLayoutProvider.tsx src/providers/
+cp useResponsiveLayout.ts src/hooks/
+cp useLayout.ts src/hooks/
+```
+
+#### 3. Modificar App.tsx
+```tsx
+// App.tsx
+import { ResponsiveLayoutProvider, MainLayout } from './index'
+
+function App() {
+  return (
+    <ResponsiveLayoutProvider defaultLayout="default">
+      <MainLayout>
+        <YourExistingApp />
+      </MainLayout>
+    </ResponsiveLayoutProvider>
+  )
+}
+```
+
+#### 4. Usar layouts
+```tsx
+import { useResponsiveLayout } from './hooks'
+
+function MyPage() {
+  const { layout } = useResponsiveLayout()
+
+  return (
+    <div>
+      <h1>Mi Página</h1>
+      <p>Layout actual: {layout.current}</p>
+      
+      <button onClick={() => layout.setLayout('sidebar')}>
+        Cambiar a Sidebar
+      </button>
+    </div>
+  )
+}
+```
+
+**✅ Ventajas adicionales:**
+- Layouts listos para usar (Default, Sidebar, Dashboard, Minimal)
+- Navbar, Sidebar, Footer incluidos
+- Cambio dinámico de layout
+
+**⚠️ Consideraciones:**
+- Sistema más complejo (~30 archivos)
+- Puede requerir adaptar tu estructura actual
+- Si ya tienes un layout, puede generar conflictos
+
+---
+
+## 🔍 Comparación de Opciones
+
+| Característica | Solo Plugin | Con Hooks | Completo |
+|---|---|---|---|
+| **Archivos a copiar** | 1 | ~8 | ~30 |
+| **Archivos a modificar** | 1 | 2 | 2-3 |
+| **Auto-scaling CSS** | ✅ | ✅ | ✅ |
+| **Detección de breakpoints** | ❌ | ✅ | ✅ |
+| **Helpers booleanos** | ❌ | ✅ | ✅ |
+| **Layouts preconfigurados** | ❌ | ❌ | ✅ |
+| **Cambio dinámico de layout** | ❌ | ❌ | ✅ |
+| **Invasividad** | ⬇️ Baja | ⬇️ Media | ⬆️ Alta |
+| **Bundle size** | +5KB | +50KB | +150KB |
+
+---
+
+## ⚡ Recomendación
+
+### Para un **proyecto nuevo**:
+👉 **OPCIÓN 3** (Sistema completo) - Aprovecha todo
+
+### Para un **proyecto existente pequeño**:
+👉 **OPCIÓN 2** (Con hooks) - Buen balance
+
+### Para un **proyecto existente grande/complejo**:
+👉 **OPCIÓN 1** (Solo plugin) - Mínima invasión
+
+---
+
+## 🚨 ¿Puede romper algo?
+
+### **NO romperá:**
+- ✅ Componentes existentes
+- ✅ Estilos actuales de Tailwind
+- ✅ Otras librerías CSS
+- ✅ Funcionalidad de la app
+
+### **PUEDE conflictuar con:**
+- ⚠️ Otros plugins de Tailwind que modifiquen las mismas propiedades
+- ⚠️ Sistemas de layout existentes (si usas OPCIÓN 3)
+- ⚠️ CSS custom que dependa de valores fijos de Tailwind
+
+---
+
+## 🧪 Modo de Prueba
+
+**Recomendación:** Prueba primero en una **rama separada**
+
+```bash
+# Crear rama de prueba
+git checkout -b test-responsive-system
+
+# Instalar OPCIÓN 1
+# ... copiar archivo y modificar config
+
+# Probar en desarrollo
+npm run dev
+
+# Si funciona bien, mergear
+git checkout main
+git merge test-responsive-system
+```
+
+---
+
+## 📞 Soporte
+
+Si encuentras problemas:
+
+1. Verifica que Tailwind CSS v4+ esté instalado
+2. Revisa que el plugin se esté importando correctamente
+3. Verifica que los breakpoints coincidan en `theme.extend.screens` y en el plugin
+4. Abre un issue en GitHub
+
+---
+
+## 🎯 Conclusión
+
+**El sistema NO es invasivo** si usas solo el plugin (OPCIÓN 1).
+
+**Es progresivamente más invasivo** si agregas hooks y layouts, pero siempre:
+- ✅ Sin romper código existente
+- ✅ Modular (usa solo lo que necesites)
+- ✅ Fácil de remover si no te gusta
+
+**Empieza con OPCIÓN 1, y escala según necesites.** 🚀
+