@codeplex-sac/navegacion

Componentes de navegación avanzados para el ecosistema Codeplex-SAC. Soluciones completas para rutas, jerarquías, menús y paneles laterales con una API 100% en Español.

Instalación

bun add @codeplex-sac/navegacion @codeplex-sac/tema @mui/material @emotion/react @emotion/styled

[!IMPORTANT] Envuelve la aplicación con CodeplexProveedorTema de @codeplex-sac/tema para que los estilos funcionen correctamente.

Componentes

CodeplexCajonLateral

Panel que se desliza desde los bordes de la pantalla. Ideal para menús de navegación móvil o paneles de filtrado.

Ejemplo:

import { CodeplexCajonLateral } from '@codeplex-sac/navegacion';

export const MiCajon = ({ abierto, alCerrar }) => (
  <CodeplexCajonLateral
    abierto={abierto}
    alCerrar={alCerrar}
    ancho={320}
    cabecera={<h2>Menú Principal</h2>}
    mostrarIconoCierre
  >
    {/* Contenido del cajón */}
  </CodeplexCajonLateral>
);

Props: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | abierto | boolean | false | Controla la visibilidad del cajón. | | alCerrar | () => void | — | Callback al cerrar (clic fuera, Esc o botón X). | | ancho | number \| string | 280 | Ancho del panel (en px o %). | | anclaje | 'izquierda' \| 'derecha' \| 'arriba' \| 'abajo' | 'izquierda' | Lado por el que aparece. | | cabecera | ReactNode | — | Contenido fijo superior. | | pie | ReactNode | — | Contenido fijo inferior. | | deslizable | boolean | false | Permite abrir/cerrar con gestos táctiles. | | mostrarIconoCierre | boolean | false | Muestra botón X en la cabecera. |

CodeplexPasos

Guía a los usuarios a través de una serie de pasos consecutivos.

Ejemplo:

import { CodeplexPasos } from '@codeplex-sac/navegacion';

const pasos = [
  { etiqueta: 'Identificación', descripcion: 'Datos personales' },
  { etiqueta: 'Pago', descripcion: 'Método de facturación' },
  { etiqueta: 'Resumen', opcional: true },
];

export const Ejemplo = () => (
  <CodeplexPasos
    pasos={pasos}
    pasoActivo={1}
    orientacion="horizontal"
  />
);

Props: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | pasos | CodeplexPaso[] | — | Lista con etiqueta, descripcion y opcional. | | pasoActivo | number | — | Índice del paso actual (base 0). | | 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

Organiza contenido en vistas accesibles mediante pestañas.

Ejemplo:

import { CodeplexPestanas } from '@codeplex-sac/navegacion';

const elementos = [
  { etiqueta: 'General', valor: 'general' },
  { etiqueta: 'Seguridad', valor: 'seguridad' },
];

export const Ejemplo = () => (
  <CodeplexPestanas
    elementos={elementos}
    valor="general"
    alCambiar={(_, val) => console.log(val)}
    centrado
  />
);

Props: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | elementos | { etiqueta, valor, icono? }[] | — | Lista de pestañas. | | valor | any | — | Valor de la pestaña activa. | | alCambiar | (e, val) => void | — | Callback al cambiar pestaña. | | centrado | boolean | false | Centra las pestañas. | | posicionIcono | 'arriba' \| 'abajo' \| 'inicio' \| 'fin' | 'arriba' | Posición del icono respecto al texto. |

CodeplexPestanasNavegador

Pestañas tipo navegador ligadas a rutas: abrir, fijar (pin), reordenar arrastrando, cerrar y persistir entre recargas. Se acompaña del hook usarPestanasNavegador que gestiona todo el estado.

Ejemplo:

import { CodeplexPestanasNavegador, usarPestanasNavegador } from '@codeplex-sac/navegacion';

export const Espacio = () => {
  const tabs = usarPestanasNavegador({
    inicial: [
      { id: '/inicio', titulo: 'Inicio', fijada: true },
      { id: '/clientes', titulo: 'Clientes' },
    ],
    persistenciaClave: 'mi-espacio',
  });

  return (
    <CodeplexPestanasNavegador
      pestanas={tabs.pestanas}
      activaId={tabs.activaId}
      alActivar={tabs.activar}
      alCerrar={tabs.cerrar}
      alFijar={tabs.alternarFijar}
      alReordenar={tabs.reordenar}
    />
  );
};

Props de CodeplexPestanasNavegador: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | pestanas | CodeplexPestanaNavegador[] | — | Pestañas abiertas ({ id, titulo, ruta?, icono?, fijada?, cerrable? }). | | activaId | string | — | Id de la pestaña activa. | | alActivar | (id) => void | — | Al seleccionar una pestaña. | | alCerrar | (id) => void | — | Al cerrar (× o clic central). | | alFijar | (id, fijada) => void | — | Al fijar/desfijar. | | alReordenar | (idsOrdenados) => void | — | Nuevo orden tras arrastrar. | | reordenable | boolean | true | Habilita arrastre para reordenar. | | fijables | boolean | true | Habilita el botón de fijar. | | tamano | 'pequeno' \| 'mediano' | 'mediano' | Tamaño de las pestañas. |

Documentación completa: readmes/navegacion/pestanas-navegador.md.

CodeplexMigasPan

Muestra la ubicación actual y permite volver a niveles superiores.

Ejemplo:

import { CodeplexMigasPan } from '@codeplex-sac/navegacion';

const ruta = [
  { etiqueta: 'Artículos', href: '/blog' },
  { etiqueta: 'Tecnología', href: '/blog/tech' },
  { etiqueta: 'Componentes UI' },
];

export const Ejemplo = () => (
  <CodeplexMigasPan
    elementos={ruta}
    rutaInicio="/"
    colorActivo="primario.main"
  />
);

Props: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | elementos | { etiqueta, href?, icono? }[] | — | Elementos de la ruta. | | rutaInicio | string | — | Activa botón "Inicio" con esta ruta. | | colorActivo | string | 'texto.primario' | Color del último elemento (hoja). | | separador | ReactNode | NavigateNext | Divisor entre elementos. |

CodeplexEnlace

Vínculo de navegación con estilos consistentes y soporte para React Router.

Ejemplo:

import { CodeplexEnlace } from '@codeplex-sac/navegacion';

export const Ejemplo = () => (
  <CodeplexEnlace
    href="/documentacion"
    subrayado="hover"
    target="_blank"
  >
    Ver documentación
  </CodeplexEnlace>
);

Props: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | href | string | — | URL de destino. | | subrayado | 'ninguno' \| 'hover' \| 'siempre' | 'hover' | Visibilidad del subrayado. | | componente | ElementType | 'a' | Etiqueta base (útil para Link de React Router). | | children | ReactNode | — | Contenido del enlace. |

CodeplexPaginacion

Selector de páginas para listas extensas de datos.

Ejemplo:

import { CodeplexPaginacion } from '@codeplex-sac/navegacion';

export const Ejemplo = () => (
  <CodeplexPaginacion
    total={25}
    pagina={1}
    alCambiar={(_, p) => console.log('Página:', p)}
    centrado
    color="primario"
  />
);

Props: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | total | number | — | Número total de páginas. | | pagina | number | — | Página activa. | | alCambiar | (e, pagina: number) => void | — | Callback al cambiar de página. | | centrado | boolean | false | Centra el componente. | | color | 'primario' \| 'secundario' \| 'estandar' | 'estandar' | Color de los botones activos. | | variante | 'contorno' \| 'texto' | 'texto' | Estilo visual de los botones. |

CodeplexMenu

Lista de opciones en superficie temporal anclada a un elemento de referencia.

Ejemplo:

import { CodeplexMenu } from '@codeplex-sac/navegacion';
import { CodeplexBoton } from '@codeplex-sac/ui';
import { useState } from 'react';

export const Ejemplo = () => {
  const [ancla, setAncla] = useState(null);
  const acciones = [
    { etiqueta: 'Editar', alHacerClick: () => {} },
    { etiqueta: 'Eliminar', alHacerClick: () => {} },
  ];

  return (
    <>
      <CodeplexBoton texto="Opciones" alHacerClick={(e) => setAncla(e.currentTarget)} />
      <CodeplexMenu
        abierto={Boolean(ancla)}
        elementoAnclaje={ancla}
        alCerrar={() => setAncla(null)}
        elementos={acciones}
      />
    </>
  );
};

Props: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | abierto | boolean | — | Controla la visibilidad. | | elementoAnclaje | HTMLElement \| null | — | Elemento de referencia para posicionarse. | | elementos | { etiqueta, icono?, alHacerClick? }[] | — | Opciones del menú. | | alCerrar | () => void | — | Callback al cerrar el menú. |

CodeplexMarcacionRapida

Botón flotante (FAB) que despliega acciones relacionadas.

Ejemplo:

import { CodeplexMarcacionRapida } from '@codeplex-sac/navegacion';

const acciones = [
  { icono: <GuardarIcono />, tituloTooltip: 'Guardar', alHacerClick: () => {} },
  { icono: <ImprimirIcono />, tituloTooltip: 'Imprimir' },
];

export const Ejemplo = () => (
  <CodeplexMarcacionRapida
    etiquetaAria="Acciones de archivo"
    icono={<EditarIcono />}
    acciones={acciones}
    direccion="arriba"
  />
);

Props: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | acciones | { icono, tituloTooltip, alHacerClick? }[] | — | Botones internos. | | etiquetaAria | string | — | Texto de accesibilidad (obligatorio). | | icono | ReactNode | — | Icono del botón principal. | | direccion | 'arriba' \| 'abajo' \| 'izquierda' \| 'derecha' | 'arriba' | Dirección de despliegue. |

CodeplexNavegacionInferior

Barra de navegación fija al pie de pantalla, optimizada para móvil.

Ejemplo:

import { CodeplexNavegacionInferior } from '@codeplex-sac/navegacion';

const elementos = [
  { etiqueta: 'Inicio', valor: 'inicio', icono: <InicioIcono /> },
  { etiqueta: 'Favoritos', valor: 'favs', icono: <FavIcono /> },
  { etiqueta: 'Perfil', valor: 'perfil', icono: <PerfilIcono /> },
];

export const Ejemplo = () => (
  <CodeplexNavegacionInferior
    elementos={elementos}
    valor="inicio"
    alCambiar={(_, val) => console.log(val)}
    fijo
  />
);

Props: | Propiedad | Tipo | Por defecto | Descripción | | :--- | :--- | :--- | :--- | | elementos | { etiqueta, valor, icono }[] | — | Pestañas de navegación. | | valor | any | — | Valor del elemento activo. | | alCambiar | (e, val) => void | — | Callback al cambiar elemento. | | fijo | boolean | false | Ancla la barra al pie de la ventana. | | conPapel | boolean | true | Aplica sombra y elevación. |

Licencia

Propiedad privada de Codeplex SAC. Todos los derechos reservados.