@codeplex-sac/layout 0.0.4 → 0.0.6

package/README.md

@@ -1,7 +1,250 @@
-# layout
+# @codeplex-sac/layout
 
-This library was generated with [Nx](https://nx.dev).
+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**.
 
-## Running unit tests
+## 🚀 Instalación
 
-Run `nx test layout` to execute the unit tests via [Vitest](https://vitest.dev/).
+```bash
+bun add @codeplex-sac/layout @mui/material @emotion/react @emotion/styled
+```
+
+---
+
+## 🏗️ 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`. |
+
+---
+
+### 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. |
+
+---
+
+### 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. |
+
+---
+
+### CodeplexCuadricula (Grid)
+Sistema de rejilla basado en 12 columnas, ideal para diseños complejos y responsivos.
+
+**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 }`. |
+
+---
+
+### CodeplexFila y CodeplexColumna
+Utilidades ligeras basadas en Tailwind CSS para maquetación rápida y flexible.
+
+**Ejemplo de Uso:**
+```tsx
+<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';