@codeplex-sac/navegacion 0.0.10

package/README.md

@@ -0,0 +1,314 @@
+# @codeplex-sac/navigation
+
+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
+
+```bash
+bun add @codeplex-sac/navigation @mui/material @emotion/react @emotion/styled
+```
+
+---
+
+## 🏗️ Componentes de Estructura y Flujo
+
+### 🗄️ Grupo 1: Contenedores y Pasos
+
+#### 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
+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>
+);
+```
+
+**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. |
+
+---
+
+#### 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. |
+
+---
+
+#### CodeplexPestanas (Tabs)
+Organiza contenido en diferentes vistas accesibles mediante pestañas superiores o integradas.
+
+**Ejemplo de Uso:**
+```tsx
+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
+  />
+);
+```
+
+**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. |
+
+### 🗺️ Grupo 2: Rutas y Jerarquía
+
+#### 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.
+
+**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. |
+
+---
+
+#### CodeplexEnlace (Link)
+Simplifica la creación de vínculos de navegación con estilos consistentes y soporte para polimorfismo.
+
+**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"
+  />
+);
+```
+
+**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). |
+
+---
+
+#### CodeplexPaginacion (Pagination)
+Componente de selección de páginas para listas extensas de datos.
+
+**Ejemplo de Uso:**
+```tsx
+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"
+  />
+);
+```
+
+**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. |
+
+### 🖱️ Grupo 3: Menús y Acciones Flotantes
+
+#### CodeplexMenu
+Muestra una lista de opciones en una superficie temporal anclada a un componente de referencia.
+
+**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ú. |
+
+---
+
+#### CodeplexMarcacionRapida (Speed Dial)
+Botón flotante (FAB) que despliega una ráfaga de acciones relacionadas al interactuar con él.
+
+**Ejemplo de Uso:**
+```tsx
+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"
+  />
+);
+```
+
+**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
+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.

package/index.d.ts

@@ -0,0 +1,11 @@
+export * from './lib/navegacion-inferior/navegacion-inferior';
+export * from './lib/migas-pan/migas-pan';
+export * from './lib/cajon-lateral/cajon-lateral';
+export * from './lib/menu/menu';
+export * from './lib/enlace/enlace';
+export * from './lib/paginacion/paginacion';
+export * from './lib/marcacion-rapida/marcacion-rapida';
+export * from './lib/pasos/pasos';
+export * from './lib/pestanas/pestanas';
+export * from './lib/barra-navegacion/barra-navegacion';
+export * from './lib/panel-lateral/panel-lateral';