@codeplex-sac/navigation 0.0.5 → 0.0.6

package/README.md

@@ -1,155 +1,314 @@
 # @codeplex-sac/navigation
 
-Colección de componentes de navegación diseñada para cubrir todas las necesidades de movimiento dentro de las aplicaciones Codeplex, desde menús simples hasta complejos flujos de pasos.
+Paquete de componentes de navegación avanzados para el ecosistema **Codeplex-SAC**. Ofrece soluciones completas para la gestión de rutas, jerarquías, menús y estructuras de paneles laterales, optimizadas para una experiencia de usuario premium y con una API nativa en **Español**.
 
-## 📦 Instalación
+## 🚀 Instalación
 
 ```bash
-pnpm add @mui/material @emotion/react @emotion/styled @mui/icons-material @codeplex-sac/navigation
+bun add @codeplex-sac/navigation @mui/material @emotion/react @emotion/styled
 ```
 
 ---
 
-## 🧭 Menús y Barras
+## 🏗️ Componentes de Estructura y Flujo
 
-### `<CodeplexCajonLateral />` (Drawer)
-Panel deslizante para menús principales o filtros. Soporta modo "Deslizable" (Swipeable) para móviles.
+### 🗄️ Grupo 1: Contenedores y Pasos
 
-| Propiedad | Tipo | Descripción |
-| :--- | :--- | :--- |
-| `abierto` | `boolean` | Controla la visibilidad. |
-| `anclaje` | `'left' \| 'right'` | Lado de aparición. |
-| `deslizable` | `boolean` | Activa soporte táctil (SwipeableDrawer). |
-| `ancho` | `number \| string` | Ancho del panel (default: 280). |
-| `cabecera` | `ReactNode` | Contenido superior fijo (Logo, Título). |
-| `pie` | `ReactNode` | Contenido inferior fijo. |
+#### CodeplexCajonLateral (Drawer)
+Panel complementario que se desliza desde los bordes de la pantalla. Ideal para menús de navegación móvil o paneles de filtrado.
 
+**Ejemplo de Uso:**
 ```tsx
-<CodeplexCajonLateral 
-    abierto={open} 
-    anclaje="left" 
-    cabecera={<Logo />} 
-    pie={<LogOutButton />}
->
-    <ListaMenu />
-</CodeplexCajonLateral>
+import { CodeplexCajonLateral } from '@codeplex-sac/navigation';
+
+export const MiCajon = ({ abierto, alCerrar }) => (
+  <CodeplexCajonLateral 
+    abierto={abierto} 
+    alCerrar={alCerrar}
+    ancho={320}
+    cabecera={<h2>Menu Principal</h2>}
+    mostrarIconoCierre
+  >
+    {/* Enlaces o navegación aquí */}
+  </CodeplexCajonLateral>
+);
 ```
 
-### `<CodeplexNavegacionInferior />` (Bottom Nav)
-Barra de pestañas inferior, el estándar para apps móviles.
-
-| Propiedad | Descripción |
-| :--- | :--- |
-| `elementos` | Array `{ etiqueta, icono, valor }`. |
-| `fijo` | `boolean`. Fija la barra al fondo de la pantalla (`position: fixed`). |
-| `conPapel` | `boolean`. Añade elevación y fondo (Paper). |
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `abierto` | `boolean` | `false` | Indica si el cajón es visible. |
+| `alCerrar` | `Function` | - | Callback al cerrar (clic fuera, ESC o 'X'). |
+| `ancho` | `number \| string` | `280` | Ancho del panel (en px o %). |
+| `anclaje` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'left'` | Lado por el que aparece el panel. |
+| `cabecera` | `ReactNode` | - | Contenido fijo superior. |
+| `pie` | `ReactNode` | - | Contenido fijo inferior. |
+| `deslizable` | `boolean` | `false` | Permite abrir/cerrar con gestos (touch). |
+| `mostrarIconoCierre` | `boolean` | `false` | Muestra la 'X' en la cabecera. |
 
 ---
 
-## 📍 Ubicación y Flujo
+#### CodeplexPasos (Stepper)
+Guía a los usuarios a través de una serie de pasos consecutivos en un proceso.
+
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexPasos } from '@codeplex-sac/navigation';
+
+const MIS_PASOS = [
+  { etiqueta: 'Identificación', descripcion: 'Datos personales' },
+  { etiqueta: 'Pago', descripcion: 'Método de facturación' },
+  { etiqueta: 'Resumen', opcional: true }
+];
+
+export const Ejemplo = () => (
+  <CodeplexPasos 
+    pasos={MIS_PASOS} 
+    pasoActivo={1} 
+    orientacion="horizontal"
+  />
+);
+```
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `pasos` | `Array<CodeplexPaso>`| - | Lista de objetos con `etiqueta` y `descripcion`. |
+| `pasoActivo` | `number` | - | Índice del paso actual (0-base). |
+| `orientacion`| `'horizontal' \| 'vertical'` | `'horizontal'` | Dirección del flujo. |
+| `etiquetasAlternativas`| `boolean` | `false` | Coloca etiquetas bajo los iconos. |
+| `noLineal` | `boolean` | `false` | Permite navegación libre entre pasos. |
+
+---
 
-### `<CodeplexMigasPan />` (Breadcrumbs)
-Muestra la ruta actual. Añade automáticamente un icono de "Inicio" si se define `rutaInicio`.
+#### CodeplexPestanas (Tabs)
+Organiza contenido en diferentes vistas accesibles mediante pestañas superiores o integradas.
 
+**Ejemplo de Uso:**
 ```tsx
-<CodeplexMigasPan 
-    rutaInicio="/"
-    elementos={[
-        { etiqueta: 'Configuración', href: '/settings' },
-        { etiqueta: 'Perfil', href: '/settings/profile' }, // Último activo
-    ]} 
-/>
+import { CodeplexPestanas } from '@codeplex-sac/navigation';
+
+const ITEMS = [
+  { etiqueta: 'General', valor: 'v1' },
+  { etiqueta: 'Seguridad', valor: 'v2', icono: <LockIcon /> }
+];
+
+export const MiSeccion = () => (
+  <CodeplexPestanas 
+    elementos={ITEMS} 
+    valor="v1" 
+    alCambiar={(_, val) => console.log(val)}
+    centrado
+  />
+);
 ```
 
-### `<CodeplexPasos />` (Stepper)
-Ideal para wizards o formularios largos.
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `elementos` | `Array<Item>` | - | Lista con `etiqueta`, `valor` e `icono`. |
+| `valor` | `any` | - | Valor de la pestaña seleccionada. |
+| `alCambiar` | `Function` | - | Evento al seleccionar una pestaña. |
+| `centrado` | `boolean` | `false` | Centra las pestañas horizontalmente. |
+| `posicionIcono`| `'top' \| 'bottom' \| 'start' \| 'end'` | `'top'` | Posición del icono respecto al texto. |
 
-| Propiedad | Descripción |
-| :--- | :--- |
-| `pasos` | Array `{ etiqueta, leyenda, opcional, error, completado }`. |
-| `pasoActivo` | Índice del paso actual (0-based). |
-| `noLineal` | `boolean`. Permite saltar entre pasos haciendo clic. |
-| `etiquetaAlternativa` | `boolean`. Pone los textos debajo de los círculos. |
+### 🗺️ Grupo 2: Rutas y Jerarquía
 
-### `<CodeplexPaginacion />`
-Navegación entre páginas de datos.
+#### CodeplexMigasPan (Breadcrumbs)
+Ayuda a los usuarios a visualizar su ubicación actual y volver a niveles superiores en la jerarquía de la aplicación.
 
-| Propiedad | Descripción |
-| :--- | :--- |
-| `total` | Número total de páginas (`count`). |
-| `pagina` | Página actual. |
-| `centrado` | `boolean`. Centra horizontalmente el paginador. |
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexMigasPan } from '@codeplex-sac/navigation';
+
+const RUTA = [
+  { etiqueta: 'Artículos', href: '/blog' },
+  { etiqueta: 'Tecnología', href: '/blog/tech' },
+  { etiqueta: 'Componentes UI' } // Último elemento sin link
+];
+
+export const Navegacion = () => (
+  <CodeplexMigasPan 
+    elementos={RUTA} 
+    rutaInicio="/" 
+    colorActivo="primary.main"
+  />
+);
+```
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `elementos` | `Array<Miga>` | - | Lista con `etiqueta`, `href` e `icono`. |
+| `rutaInicio`| `string` | - | Activa botón "Inicio" redirigiendo a esta ruta. |
+| `colorActivo`| `string` | `'text.primary'`| Color del texto del último elemento. |
+| `separador` | `ReactNode` | `NavigateNext` | Icono o carácter divisor entre elementos. |
 
 ---
 
-## 🔗 Interacción
+#### CodeplexEnlace (Link)
+Simplifica la creación de vínculos de navegación con estilos consistentes y soporte para polimorfismo.
 
-### `<CodeplexPestanas />` (Tabs)
-Organización de contenido en pestañas.
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexEnlace } from '@codeplex-sac/navigation';
+
+export const MiEnlace = () => (
+  <CodeplexEnlace 
+    hijos="Ver documentación" 
+    href="https://google.com" 
+    subrayado="hover"
+    target="_blank"
+  />
+);
+```
 
-| Propiedad | Descripción |
-| :--- | :--- |
-| `elementos` | Array `{ etiqueta, valor, icono, disabled }`. |
-| `valor` | Valor de la pestaña activa. |
-| `centrado` | `boolean`. Centra las pestañas en el contenedor. |
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `hijos` | `ReactNode` | - | Contenido del enlace (texto/iconos). |
+| `href` | `string` | - | Dirección de destino. |
+| `subrayado` | `'none' \| 'hover' \| 'always'` | `'hover'` | Controla la visualización del subrayado. |
+| `componente` | `ElementType`| `'a'` | Etiqueta base (útil para `Link` de React Router). |
 
-### `<CodeplexEnlace />` (Link)
-Enlace estilizado estándar.
+---
 
-| Propiedad | Descripción |
-| :--- | :--- |
-| `subrayado` | `'none' \| 'hover' \| 'always'`. |
-| `componente` | Permite cambiar el nodo raíz (útil para `react-router-dom Link`). |
+#### CodeplexPaginacion (Pagination)
+Componente de selección de páginas para listas extensas de datos.
 
+**Ejemplo de Uso:**
 ```tsx
-<CodeplexEnlace componente={RouterLink} to="/home">
-    Ir al Inicio
-</CodeplexEnlace>
+import { CodeplexPaginacion } from '@codeplex-sac/navigation';
+
+export const Listado = () => (
+  <CodeplexPaginacion 
+    total={25} 
+    pagina={1} 
+    alCambiar={(e, p) => console.log('Nueva página:', p)}
+    centrado
+    color="primary"
+  />
+);
 ```
 
-### `<CodeplexMarcacionRapida />` (Speed Dial)
-Botón flotante (FAB) que despliega acciones secundarias.
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `total` | `number` | - | Número total de páginas. |
+| `pagina` | `number` | - | Página actual seleccionada. |
+| `alCambiar` | `Function` | - | Evento disparado al seleccionar otra página. |
+| `centrado` | `boolean` | `false` | Centra el componente en su contenedor. |
+| `variante` | `'outlined' \| 'text'` | `'text'`| Estilo visual de los botones. |
 
-| Propiedad | Descripción |
-| :--- | :--- |
-| `acciones` | Array `{ icono, tituloTooltip, alHacerClick }`. |
-| `direction` | Dirección de apertura (`up`, `down`, `left`, `right`). |
+### 🖱️ Grupo 3: Menús y Acciones Flotantes
 
-### `<CodeplexMenu />`
-Menú emergente estándar (Dropdown).
+#### CodeplexMenu
+Muestra una lista de opciones en una superficie temporal anclada a un componente de referencia.
 
-| Propiedad | Descripción |
-| :--- | :--- |
-| `elementos` | Array `{ etiqueta, icono, alHacerClick }`. |
-| `elementoAnclaje` | Elemento HTML al que se pega el menú. |
+**Ejemplo de Uso:**
+```tsx
+import { CodeplexMenu, CodeplexBoton } from '@codeplex-sac/ui';
+
+export const Ejemplo = () => {
+  const [ancla, setAncla] = useState(null);
+  const ACCIONES = [
+    { etiqueta: 'Editar', icono: <EditIcon />, alHacerClick: () => alert('Editando...') },
+    { etiqueta: 'Eliminar', icono: <DeleteIcon />, sx: { color: 'error.main' } }
+  ];
+
+  return (
+    <>
+      <CodeplexBoton texto="Opciones" alHacerClick={(e) => setAncla(e.currentTarget)} />
+      <CodeplexMenu 
+        abierto={Boolean(ancla)} 
+        elementoAnclaje={ancla} 
+        alCerrar={() => setAncla(null)}
+        elementos={ACCIONES}
+      />
+    </>
+  );
+};
+```
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `abierto` | `boolean` | - | Controla la visibilidad del menú. |
+| `elementoAnclaje`| `HTMLElement` | - | Elemento que sirve de referencia para la posición. |
+| `elementos` | `Array<Item>` | - | Lista de opciones con `etiqueta`, `icono` y callback. |
+| `alCerrar` | `Function` | - | Evento disparado al cerrar el menú. |
 
 ---
 
-## 🎨 Patrones Comunes
+#### CodeplexMarcacionRapida (Speed Dial)
+Botón flotante (FAB) que despliega una ráfaga de acciones relacionadas al interactuar con él.
 
-### Navegación Móvil Fija
-Para crear una app móvil con barra inferior fija:
+**Ejemplo de Uso:**
 ```tsx
-<CodeplexNavegacionInferior
-    fijo
-    valor={pestana}
-    alCambiar={(_, v) => setPestana(v)}
-    elementos={[
-        { label: 'Inicio', valor: 'home', icon: <HomeIcon /> },
-        { label: 'Perfil', valor: 'profile', icon: <PersonIcon /> }
-    ]}
-/>
+import { CodeplexMarcacionRapida } from '@codeplex-sac/navigation';
+
+const ACCIONES = [
+  { icono: <SaveIcon />, tituloTooltip: 'Guardar', alHacerClick: () => save() },
+  { icono: <PrintIcon />, tituloTooltip: 'Imprimir' }
+];
+
+export const MiApp = () => (
+  <CodeplexMarcacionRapida 
+    etiquetaAria="Acciones de archivo"
+    icono={<EditIcon />} 
+    acciones={ACCIONES}
+    direction="up"
+  />
+);
 ```
 
-### Wizard de Registro
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `acciones` | `Array<Accion>`| - | Lista de botones internos con `icono` y `tituloTooltip`. |
+| `etiquetaAria` | `string` | - | Texto de accesibilidad (obligatorio). |
+| `icono` | `ReactNode` | - | Icono del botón principal. |
+| `direction` | `string` | `'up'` | Dirección de despliegue (up, down, left, right). |
+
+---
+
+#### CodeplexNavegacionInferior (Bottom Navigation)
+Navegación principal fija en la base de la pantalla, optimizada para aplicaciones móviles.
+
+**Ejemplo de Uso:**
 ```tsx
-<CodeplexPasos
-    pasoActivo={paso}
-    etiquetaAlternativa
-    pasos={[
-        { etiqueta: 'Cuenta', leyenda: 'Datos de acceso' },
-        { etiqueta: 'Perfil', opcional: true },
-        { etiqueta: 'Confirmación' }
-    ]}
-/>
+import { CodeplexNavegacionInferior } from '@codeplex-sac/navigation';
+
+const NAV_ITEMS = [
+  { etiqueta: 'Inicio', valor: 'inicio', icono: <HomeIcon /> },
+  { etiqueta: 'Favoritos', valor: 'favs', icono: <FavoriteIcon /> },
+  { etiqueta: 'Perfil', valor: 'perfil', icono: <PersonIcon /> }
+];
+
+export const AppMovil = () => (
+  <CodeplexNavegacionInferior 
+    elementos={NAV_ITEMS} 
+    valor="inicio" 
+    fijo
+    conPapel
+  />
+);
 ```
+
+**Propiedades (Props):**
+| Propiedad | Tipo | Por Defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `elementos` | `Array<Item>` | - | Lista de pestañas con `etiqueta`, `icono` y `valor`. |
+| `valor` | `any` | - | Valor del elemento activo. |
+| `fijo` | `boolean` | `false` | Ancla la barra al final de la ventana (fixed). |
+| `conPapel`| `boolean` | `true` | Aplica sombra y elevación estilo Material Design. |
+
+---
+
+## 🎨 Integración y Diseño
+
+Todos los componentes de `@codeplex-sac/navigation` están diseñados para heredar automáticamente la identidad visual definida en `@codeplex-sac/theme`, respetando los modos claro/oscuro y utilizando la tipografía **Poppins**.
+
+## 📄 Licencia
+
+Este proyecto es propiedad privada de **Codeplex SAC**. Todos los derechos reservados.