@codeplex-sac/layout 0.0.5 → 0.0.7

package/README.md

@@ -1,175 +1,250 @@
 # @codeplex-sac/layout
 
-Este paquete proporciona los cimientos estructurales y de navegación para aplicaciones Codeplex. Envuelve componentes primitivos de MUI y añade patrones de diseño comunes (Dashboards, Paneles, Grillas) con una API declarativa en español.
+El motor de estructura y maquetación definitiva para el ecosistema **Codeplex-SAC**. Este paquete proporciona una base sólida y flexible para construir interfaces modernas, desde rejillas responsivas hasta cascarones de aplicación completos, todo con una API semántica en **Español**.
 
-## 📦 Instalación
+## 🚀 Instalación
 
 ```bash
-pnpm add @mui/material @emotion/react @emotion/styled @codeplex-sac/layout
+bun add @codeplex-sac/layout @mui/material @emotion/react @emotion/styled
 ```
 
 ---
 
-## 🏗️ Estructura y Grilla
-
-Bloques fundamentales para el maquetado de páginas.
-
-### `<CodeplexCaja />` (Box)
-Contenedor genérico ultra-flexible.
-| Propiedad | Descripción |
-| :--- | :--- |
-| `centrado` | `boolean`. Centra contenido vertical y horizontalmente. |
-| `pantallaCompleta` | `boolean`. Ancho y alto de viewport (100vw/vh). |
-| `flexFila` / `flexColumna` | Atajos para dirección Flex. |
-
-### `<CodeplexContenedor />` (Container)
-Contenedor central con anchos máximos responsivos.
-| Propiedad | Descripción |
-| :--- | :--- |
-| `fluido` | `boolean`. Ancho 100% sin máximos. |
-| `paginaCentrada` | `boolean`. Altura 100vh y centro absoluto (ideal Login/404). |
-| `anchoMaximo` | `'xs' | 'sm' | 'md' | 'lg' | 'xl'`. |
-| `deshabilitarMargenes` | Elimina padding horizontal. |
-
-### `<CodeplexCuadricula />` (Grid)
-Sistema de rejilla de 12 columnas (MUI Grid v2).
-| Propiedad | Descripción |
-| :--- | :--- |
-| `contenedor` | Activa el modo contenedor (padre). |
-| `elemento` | Activa el modo ítem (hijo). |
-| `espaciado` | Número (x8px) de separación. |
-| `xs`, `md`, `lg`... | Número de columnas (1-12) u 'auto'. |
-
-### `<CodeplexColumna />` (Div + Tailwind)
-Alternativa ligera a Grid para columnas responsivas simples.
-| Propiedad | Descripción |
-| :--- | :--- |
-| `xs`, `sm`, `md`... | Número de columnas (1-12). Ejemplo: `md={6}` (50%). |
-| `etiqueta` | Tag HTML (default `div`). |
-
-### `<CodeplexFila />`
-Contenedor Flex horizontal con wrap automático y gutters negativos. Útil para agrupar tarjetas o inputs.
-| Propiedad | Descripción |
-| :--- | :--- |
-| `alineacion` | `'start' | 'center' | 'end' | 'stretch'`. |
-| `justificacion` | `'start' | 'center' | 'between' | 'around'`. |
-| `sinMargenes` | Quita los márgenes negativos de corrección. |
-
-### `<CodeplexPila />` (Stack)
-Lista vertical u horizontal de elementos con espaciado uniforme.
-| Propiedad | Descripción |
-| :--- | :--- |
-| `direccion` | `'fila' | 'columna'`. |
-| `espaciado` | Separación entre hijos. |
-| `entre` | `justify-content: space-between`. |
+## 🏗️ Estructura Base (Grid & Flex)
+
+Componentes fundamentales para la distribución y alineación del contenido.
+
+### CodeplexCaja (Box)
+El bloque de construcción más básico. Soporta variantes visuales avanzadas y comportamientos de layout rápidos.
+
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexCaja } from '@codeplex-sac/layout';
+
+export const MiCaja = () => (
+  <CodeplexCaja 
+    variante="vidrio" 
+    relleno={4} 
+    centrado 
+    alFlotar={{ elevar: true }}
+  >
+    Contenido con Glassmorphism
+  </CodeplexCaja>
+);
+```
+
+**Propiedades Destacadas (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `variante` | `Variante` | `'predeterminado'`| `predeterminado`, `bordeado`, `sombreado`, `vidrio`, `gradiente`. |
+| `centrado` | `boolean` | `false` | Centra el contenido en ambos ejes. |
+| `relleno` | `number \| string`| - | Espaciado interno (padding). |
+| `alFlotar` | `object` | - | Opciones de interactividad: `{ elevar, escalar }`. |
+| `validacion`| `Validacion` | - | Feedback visual: `error`, `exito`, `advertencia`, `info`. |
 
 ---
 
-## 🧭 Navegación Principal
-
-Componentes de alto nivel para Layouts de Aplicación (Dashboards, Landings).
-
-### `<CodeplexBarraLateral />` (Sidebar)
-Menú lateral colapsable para dashboards.
-| Propiedad | Tipo | Descripción |
-| :--- | :--- | :--- |
-| `elementos` | `CodeplexElementoMenuLateral[]` | Array de objetos con `id`, `etiqueta`, `icono`, `href`, `hijos`. |
-| `usuario` | `CodeplexInfoUsuario` | Datos del usuario mostrados al pie. |
-| `colapsado` | `boolean` | Estado controlado del colapso. |
-| `alAlternar` | `(c: boolean) => void` | Callback de colapso. |
-
-### `<CodeplexBarraNavegacion />` (Navbar)
-Barra superior para Landing Pages o Apps simples.
-| Propiedad | Descripción |
-| :--- | :--- |
-| `textoLogo` / `srcLogo` | Identidad de marca. |
-| `enlaces` | Array de links simples (`etiqueta`, `href`). |
-| `posicion` | `'fixed' | 'sticky' | 'static'`. |
-| `children` | Slots para acciones extra (derecha). |
-
-### `<CodeplexCabecera />` (Header Dashboard)
-Barra superior para Dashboards, complementa a la Barra Lateral.
-| Propiedad | Descripción |
-| :--- | :--- |
-| `titulo` | Título de la página actual. |
-| `migasPan` | Array `{ etiqueta, href }` para Breadcrumbs. |
-| `mostrarBusqueda` | `boolean`. Muestra input de búsqueda global. |
-| `conteoNotificaciones` | Número para el badge de campana. |
-
-### `<CodeplexPiePagina />` (Footer)
-| Propiedad | Descripción |
-| :--- | :--- |
-| `derechosAutor` | String custom de copyright. |
-| `redesSociales` | Objeto `{ facebook, twitter, github, linkedin }` con URLs. |
+### CodeplexContenedor (Container)
+Centra tu contenido horizontalmente y establece anchos máximos consistentes.
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `fluido` | `boolean` | `false` | Elimina el ancho máximo para ocupar el 100%. |
+| `anchoMaximo`| `string \| false` | `'lg'` | Puntos de ruptura de MUI (xs, sm, md, lg, xl). |
+| `paginaCentrada`| `boolean` | `false` | Altura 100vh y contenido centrado. |
 
 ---
 
-## 🗂️ Contenidos y Paneles
-
-### `<CodeplexAcordeon />`
-Lista de paneles expandibles.
-| Propiedad | Descripción |
-| :--- | :--- |
-| `elementos` | Array `{ titulo, contenido, iconoIzquierda, subtitulo }`. |
-| `multiple` | Permite varios abiertos a la vez. |
-| `variante` | `'simple' | 'bordeado' | 'separado'`. |
-
-### `<CodeplexPanelLateral />` (Drawer)
-Panel deslizante (Off-canvas) para detalles o formularios sin salir de la página.
-| Propiedad | Descripción |
-| :--- | :--- |
-| `abierto` | `boolean`. Controla visibilidad. |
-| `lado` | `'izquierda' | 'derecha'`. |
-| `tamano` | `'sm' | 'md' | 'lg' | 'xl' | 'full'`. |
-| `titulo` / `descripcion` | Cabecera del panel. |
-| `pie` | Slot para botones de acción (Guardar/Cancelar) fijos al fondo. |
+### CodeplexPila (Stack)
+Organiza elementos en una dirección (fila o columna) con espaciado uniforme.
+
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexPila } from '@codeplex-sac/layout';
+
+export const Lista = () => (
+  <CodeplexPila direccion="columna" espaciado={2} divisor>
+    <div>Item 1</div>
+    <div>Item 2</div>
+  </CodeplexPila>
+);
+```
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `direccion` | `string \| obj` | `'columna'` | `fila`, `columna`, `fila-reversa`, `columna-reversa`. |
+| `espaciado` | `number \| string`| `0` | Factor de multiplicación para el gap. |
+| `divisor` | `boolean \| node` | `false` | Agrega una línea o componente entre cada hijo. |
 
 ---
 
-## 🖼️ Multimedia
+### CodeplexCuadricula (Grid)
+Sistema de rejilla basado en 12 columnas, ideal para diseños complejos y responsivos.
 
-### `<CodeplexListaImagenes />`
-Mosaico de imágenes (Masonry o Grid estándar).
-*   **Subcomponentes**: `CodeplexElementoListaImagenes`, `CodeplexBarraElementoListaImagenes`.
-*   Propiedades espejo de MUI ImageList (`columnas`, `altoFila`, `variante`).
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `contenedor` | `boolean` | `false` | Define el componente como contenedor Grid. |
+| `elemento` | `boolean` | `false` | Define el componente como item Grid. |
+| `espaciado` | `number` | - | Espacio entre columnas (Padding). |
+| `tamano` | `number \| object`| - | Número de columnas (1-12) o breakpoints `{ xs, md }`. |
 
 ---
 
-### 💡 Ejemplo: Layout de Dashboard Completo
+### CodeplexFila y CodeplexColumna
+Utilidades ligeras basadas en Tailwind CSS para maquetación rápida y flexible.
 
+**Ejemplo de Uso:**
 ```tsx
-import { 
-  CodeplexCaja, 
-  CodeplexBarraLateral, 
-  CodeplexCabecera 
-} from '@codeplex-sac/layout';
-
-export const DashboardLayout = ({ children }) => {
-  const [colapsado, setColapsado] = useState(false);
-
-  return (
-    <CodeplexCaja flexFila pantallaCompleta>
-        {/* 1. Menú Lateral */}
-        <CodeplexBarraLateral 
-            colapsado={colapsado} 
-            alAlternar={setColapsado}
-            elementos={MENU_ITEMS}
-        />
-
-        {/* 2. Área Principal */}
-        <CodeplexCaja flexColumna sx={{ flex: 1, overflow: 'hidden' }}>
-            {/* Header */}
-            <CodeplexCabecera 
-                titulo="Inicio" 
-                barraLateralColapsada={colapsado}
-            />
-            
-            {/* Contenido con Scroll */}
-            <main className="flex-1 overflow-auto p-4 bg-gray-50 dark:bg-gray-900">
-                {children}
-            </main>
-        </CodeplexCaja>
-    </CodeplexCaja>
-  );
-};
+<CodeplexFila justificacion="between" alineacion="center">
+  <CodeplexColumna md={6}>Contenido Izquierdo</CodeplexColumna>
+  <CodeplexColumna md={6}>Contenido Derecho</CodeplexColumna>
+</CodeplexFila>
 ```
+
+---
+
+## 🏛️ Cascarón de Aplicación (Shell)
+
+Componentes diseñados para construir la estructura de alto nivel de aplicaciones corporativas.
+
+### CodeplexEsqueleto (Standard Scaffold)
+Combina Cabecera, Barra Lateral y Pie de Página en una estructura unificada y lista para usar.
+
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexEsqueleto } from '@codeplex-sac/layout';
+
+const MENU = [
+  { id: '1', etiqueta: 'Dashboard', icono: <DashboardIcon />, activo: true },
+  { id: '2', etiqueta: 'Usuarios', icono: <PeopleIcon /> }
+];
+
+export const MiPantalla = () => (
+  <CodeplexEsqueleto menu={MENU} titulo="Admin Panel">
+    Contenido principal de la página
+  </CodeplexEsqueleto>
+);
+```
+
+---
+
+### CodeplexCabecera (Header)
+Barra superior fija con soporte para migas de pan (breadcrumbs), búsqueda y perfil de usuario.
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `titulo` | `string` | - | Título principal (si no hay migas de pan). |
+| `migasPan` | `Array<Item>` | - | Lista de niveles con `etiqueta`, `href` y callback. |
+| `usuario` | `object` | - | `{ nombre, rol, avatar }`. |
+| `conteoNotificaciones`| `number`| `0` | Badge sobre el icono de campana. |
+| `alBuscar` | `function` | - | Callback que recibe el texto de búsqueda. |
+
+---
+
+### CodeplexBarraNavegacion (Navbar)
+Barra de navegación horizontal con soporte para logo, enlaces responsivos y perfil de usuario.
+
+**Ejemplo de Uso:**
+```tsx
+<CodeplexBarraNavegacion 
+  textoLogo="Codeplex"
+  enlaces={[
+    { id: '1', etiqueta: 'Inicio', activo: true },
+    { id: '2', etiqueta: 'Servicios', href: '/servicios' }
+  ]}
+  posicion="sticky"
+/>
+```
+
+---
+
+### CodeplexBarraLateral (Sidebar)
+Navegación vertical avanzada con soporte para submenús, colapsado manual y modo móvil automático.
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `elementos` | `Array<Item>` | - | Árbol de navegación con `etiqueta`, `icono`, `hijos`. |
+| `colapsado` | `boolean` | `false` | Estado contraído del sidebar (solo iconos). |
+| `ancho` | `number` | `260` | Ancho del panel expandido. |
+| `alAlternar` | `function` | - | Callback ejecutado al expandir/colapsar. |
+
+---
+
+### CodeplexPanelLateral (Side Panel / Drawer)
+Panel deslizante para flujos secundarios, disponible en ambos lados y múltiples tamaños.
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `abierto` | `boolean` | - | Controla la visibilidad. |
+| `lado` | `string` | `'derecha'` | `'izquierda'` o `'derecha'`. |
+| `tamano` | `string` | `'md'` | `'sm'`, `'md'`, `'lg'`, `'xl'`, `'full'`. |
+| `pie` | `ReactNode` | - | Contenido fijo al final del panel. |
+
+---
+
+### CodeplexPiePagina (Footer)
+Pie de página consistente con soporte para enlaces legales y redes sociales.
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `derechosAutor`| `string` | - | Texto de copyright personalizado. |
+| `enlaces` | `Array` | - | Lista de enlaces legales `{ etiqueta, href }`. |
+| `redesSociales`| `object` | - | `{ facebook, twitter, github, linkedin }`. |
+
+---
+
+## 📦 Contenedores de Contenido
+
+### CodeplexAcordeon
+Organiza información en paneles colapsables con animaciones fluidas y múltiples variantes.
+
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexAcordeon } from '@codeplex-sac/layout';
+
+const DATOS = [
+  { id: '1', titulo: 'Sección 1', contenido: 'Detalle 1', iconoIzquierda: <InfoIcon /> },
+  { id: '2', titulo: 'Sección 2', contenido: 'Detalle 2' }
+];
+
+export const Faq = () => (
+  <CodeplexAcordeon elementos={DATOS} variante="separado" multiple />
+);
+```
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `elementos` | `Array<Item>` | - | Lista de paneles con `id`, `titulo`, `contenido`. |
+| `variante` | `string` | `'simple'` | `'simple'`, `'bordeado'`, `'separado'`. |
+| `multiple` | `boolean` | `false` | Permite abrir varios paneles a la vez. |
+| `alCambiar` | `function` | - | Callback con los IDs de los items abiertos. |
+
+---
+
+### CodeplexListaImagenes (Image List)
+Distribuye una colección de imágenes en rejillas optimizadas (estándar, mosaico o mampostería).
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `variante` | `string` | `'estandar'`| `estandar`, `mosaico`, `mamposteria`, `tejido`. |
+| `columnas` | `number` | `2` | Número de columnas en la rejilla. |
+| `espacio` | `number` | `4` | Espacio entre imágenes (px). |
+
+---
+
+## 🎨 Diseño y Consistencia
+
+Todos los componentes de `@codeplex-sac/layout` están construidos sobre los cimientos de `@codeplex-sac/theme`. Utilizan tokens de espaciado, elevaciones y colores corporativos para garantizar que la maquetación de tus aplicaciones sea impecable y profesional por defecto.
+
+## 📄 Licencia
+
+Este proyecto es propiedad privada de **Codeplex SAC**. Todos los derechos reservados.

package/index.d.ts

@@ -11,3 +11,4 @@ export * from './lib/caja/caja';
 export * from './lib/cuadricula/cuadricula';
 export * from './lib/pila/pila';
 export * from './lib/lista-imagenes/lista-imagenes';
+export * from './lib/esqueleto/esqueleto';