siesa-ui-kit 1.0.3 → 1.0.5

package/src/components/NavigationBar/NavigationBar.types.ts

@@ -0,0 +1,74 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Interfaz para un ítem individual del Navigation Bar
+ */
+export interface NavigationBarItem {
+  /**
+   * Identificador único del ítem
+   */
+  id: string;
+
+  /**
+   * Icono del ítem (componente React)
+   */
+  icon: ReactNode;
+
+  /**
+   * Label del ítem (texto debajo del icono)
+   */
+  label: string;
+
+  /**
+   * Si el ítem está activo
+   * @default false
+   */
+  active?: boolean;
+
+  /**
+   * Si el ítem está deshabilitado
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Función onClick del ítem
+   */
+  onClick?: (id: string) => void;
+
+  /**
+   * Etiqueta accesible para lectores de pantalla
+   */
+  ariaLabel?: string;
+}
+
+/**
+ * Props del componente NavigationBar
+ */
+export interface NavigationBarProps {
+  /**
+   * Lista de ítems del navigation bar (máximo 5 ítems recomendado)
+   */
+  items: NavigationBarItem[];
+
+  /**
+   * ID del ítem actualmente activo
+   */
+  activeItemId?: string;
+
+  /**
+   * Función que se ejecuta cuando se hace click en un ítem
+   */
+  onItemClick?: (id: string) => void;
+
+  /**
+   * Clases CSS adicionales para el contenedor
+   */
+  className?: string;
+
+  /**
+   * Etiqueta accesible para el navigation bar
+   * @default 'Navigation Bar'
+   */
+  ariaLabel?: string;
+}

package/src/components/NavigationBar/README.md

@@ -0,0 +1,469 @@
+# NavigationBar
+
+Barra de navegación inferior (Bottom Navigation Bar) para aplicaciones móviles del sistema de diseño Siesa UI Kit.
+
+## 📋 Descripción
+
+El **NavigationBar** es un componente de navegación diseñado específicamente para aplicaciones móviles. Permite al usuario navegar entre 3-5 vistas principales de la aplicación mediante una barra fija en la parte inferior de la pantalla.
+
+## 🔄 Navegación Responsive
+
+**El NavigationRail se convierte en NavigationBar cuando es responsive.**
+
+Esta es una práctica recomendada de UX para optimizar el espacio en diferentes dispositivos:
+- **Desktop/Tablet (≥768px)**: Usar **NavigationRail** (navegación lateral vertical)
+- **Mobile (<768px)**: Usar **NavigationBar** (navegación inferior horizontal)
+
+El patrón responsive permite aprovechar mejor el espacio disponible: en desktop se usa el espacio lateral, mientras que en móvil se usa el espacio inferior para mantener el contenido principal en el centro de la pantalla.
+
+## 🎨 Características
+
+- ✅ Soporte para 3-5 ítems de navegación (recomendado)
+- ✅ Cada ítem incluye icono + label
+- ✅ Indicador visual de ítem activo (fondo azul claro)
+- ✅ Estados: active, hover, disabled
+- ✅ Dark mode completo
+- ✅ Accesibilidad con ARIA labels
+- ✅ TypeScript con types estrictos
+- ✅ Iconos de 16x16px según especificaciones de Figma
+- ✅ Tipografía Label XXSmall (10px Bold)
+
+## 📦 Instalación
+
+```tsx
+import { NavigationBar } from '@/components/NavigationBar';
+import type { NavigationBarItem } from '@/components/NavigationBar';
+```
+
+## 🚀 Uso Básico
+
+### Ejemplo Simple
+
+```tsx
+import { NavigationBar } from '@/components/NavigationBar';
+import { HomeIcon, SearchIcon, ProfileIcon } from '@/icons';
+
+const items = [
+  { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
+  { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+  { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+];
+
+function App() {
+  return <NavigationBar items={items} activeItemId="home" />;
+}
+```
+
+### Ejemplo con Estado Controlado
+
+```tsx
+import { useState } from 'react';
+import { NavigationBar } from '@/components/NavigationBar';
+import { HomeIcon, SearchIcon, HeartIcon, ProfileIcon } from '@/icons';
+
+function App() {
+  const [activeTab, setActiveTab] = useState('home');
+
+  const items = [
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ];
+
+  return (
+    <NavigationBar
+      items={items}
+      activeItemId={activeTab}
+      onItemClick={(id) => setActiveTab(id)}
+    />
+  );
+}
+```
+
+### Ejemplo con Ítem Deshabilitado
+
+```tsx
+const items = [
+  { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+  { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+  {
+    id: 'favorites',
+    icon: <HeartIcon />,
+    label: 'Favoritos',
+    disabled: true, // Ítem deshabilitado
+  },
+  { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+];
+
+<NavigationBar items={items} activeItemId="home" />;
+```
+
+## 📐 Props
+
+### NavigationBarProps
+
+| Prop           | Tipo                       | Default               | Descripción                                          |
+| -------------- | -------------------------- | --------------------- | ---------------------------------------------------- |
+| `items`        | `NavigationBarItem[]`      | **Required**          | Lista de ítems del navigation bar (máximo 5)         |
+| `activeItemId` | `string`                   | `undefined`           | ID del ítem actualmente activo                       |
+| `onItemClick`  | `(id: string) => void`     | `undefined`           | Función que se ejecuta cuando se hace click en ítem  |
+| `className`    | `string`                   | `''`                  | Clases CSS adicionales para el contenedor            |
+| `ariaLabel`    | `string`                   | `'Navegación Principal'` | Etiqueta accesible para el navigation bar            |
+
+### NavigationBarItem
+
+| Prop        | Tipo                    | Default     | Descripción                              |
+| ----------- | ----------------------- | ----------- | ---------------------------------------- |
+| `id`        | `string`                | **Required** | Identificador único del ítem             |
+| `icon`      | `ReactNode`             | **Required** | Icono del ítem (componente React)        |
+| `label`     | `string`                | **Required** | Label del ítem (texto debajo del icono)  |
+| `active`    | `boolean`               | `false`     | Si el ítem está activo                   |
+| `disabled`  | `boolean`               | `false`     | Si el ítem está deshabilitado            |
+| `onClick`   | `(id: string) => void`  | `undefined` | Función onClick del ítem individual      |
+| `ariaLabel` | `string`                | `undefined` | Etiqueta accesible para el ítem          |
+
+## 🎨 Variantes
+
+### Por Cantidad de Ítems
+
+#### 3 Ítems (Mínimo Recomendado)
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ]}
+  activeItemId="home"
+/>
+```
+
+**Uso:** Aplicaciones simples con pocas secciones principales.
+
+#### 4 Ítems (Óptimo)
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ]}
+  activeItemId="home"
+/>
+```
+
+**Uso:** Balance perfecto entre funcionalidad y usabilidad.
+
+#### 5 Ítems (Máximo Recomendado)
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
+    { id: 'notifications', icon: <BellIcon />, label: 'Alertas' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ]}
+  activeItemId="home"
+/>
+```
+
+**Uso:** Máximo de ítems para mantener buena experiencia de usuario.
+
+## 🎯 Estados
+
+### Estado Normal
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ]}
+  activeItemId="home"
+/>
+```
+
+El ítem activo muestra un fondo azul claro en light mode o azul oscuro transparente en dark mode.
+
+### Estado Hover
+
+Los ítems inactivos muestran un overlay ligero al pasar el mouse sobre ellos.
+
+### Estado Disabled
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar', disabled: true },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ]}
+  activeItemId="home"
+/>
+```
+
+Los ítems deshabilitados tienen opacidad reducida y no responden a clicks.
+
+## 📱 Uso Responsive
+
+El NavigationBar está diseñado específicamente para **móviles**. En desktop, debes usar **NavigationRail** (navegación lateral).
+
+### Patrón Responsive: NavigationRail → NavigationBar
+
+**Implementación recomendada para aplicaciones responsive:**
+
+```tsx
+import { NavigationBar } from '@/components/NavigationBar';
+import { NavigationRail } from '@/components/NavigationRail';
+
+function ResponsiveApp() {
+  const [activeTab, setActiveTab] = useState('home');
+
+  const navItems = [
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
+    { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+  ];
+
+  return (
+    <div className="min-h-screen">
+      {/* NavigationRail para desktop/tablet (≥768px) */}
+      <div className="hidden md:block">
+        <NavigationRail
+          items={navItems}
+          activeItemId={activeTab}
+          onItemClick={setActiveTab}
+        />
+      </div>
+
+      {/* Contenido principal */}
+      <main className="md:ml-20 pb-20 md:pb-0">
+        {/* Tu contenido aquí */}
+      </main>
+
+      {/* NavigationBar para móvil (<768px) */}
+      <div className="md:hidden fixed bottom-0 left-0 right-0 z-50">
+        <NavigationBar
+          items={navItems}
+          activeItemId={activeTab}
+          onItemClick={setActiveTab}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Fijar en la Parte Inferior (Solo Móvil)
+
+```tsx
+import { NavigationBar } from '@/components/NavigationBar';
+
+function MobileApp() {
+  return (
+    <div className="min-h-screen flex flex-col">
+      {/* Contenido principal */}
+      <main className="flex-1 pb-20">{/* Tu contenido aquí */}</main>
+
+      {/* Navigation Bar fijo en bottom */}
+      <div className="fixed bottom-0 left-0 right-0 z-50">
+        <NavigationBar items={items} activeItemId={activeTab} />
+      </div>
+    </div>
+  );
+}
+```
+
+### Breakpoints Recomendados
+
+```tsx
+// Tailwind breakpoints para la conversión
+// mobile    : <768px  → NavigationBar (inferior)
+// tablet+   : ≥768px  → NavigationRail (lateral)
+
+<div className="md:hidden">      {/* Solo móvil */}
+  <NavigationBar />
+</div>
+
+<div className="hidden md:block"> {/* Tablet y desktop */}
+  <NavigationRail />
+</div>
+```
+
+## 🌓 Dark Mode
+
+El componente soporta dark mode completo automáticamente usando la estrategia `class` de Tailwind CSS.
+
+```tsx
+// El componente detecta automáticamente el modo oscuro
+<NavigationBar items={items} activeItemId="home" />
+```
+
+### Colores en Dark Mode
+
+| Elemento              | Light Mode                 | Dark Mode                           |
+| --------------------- | -------------------------- | ----------------------------------- |
+| Fondo principal       | `bg-bg-primary` (#ffffff)  | `dark:bg-dark-bg-primary` (#18181b) |
+| Icono activo (fondo)  | `bg-primary-custom-100`    | `dark:bg-primary-custom-100/20`     |
+| Icono/texto           | `text-content-primary`     | `dark:text-dark-content-primary`    |
+| Hover (inactivo)      | `hover:bg-hover-overlay`   | `dark:hover:bg-hover-overlay-dark`  |
+
+## ♿ Accesibilidad
+
+### ARIA Labels
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio', ariaLabel: 'Ir a Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar', ariaLabel: 'Buscar contenido' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil', ariaLabel: 'Ver mi perfil' },
+  ]}
+  ariaLabel="Navegación Principal de la Aplicación"
+  activeItemId="home"
+/>
+```
+
+### Atributos ARIA Automáticos
+
+- `role="navigation"`: Identifica el componente como navegación
+- `aria-label`: Descripción del navigation bar completo
+- `aria-current="page"`: Marca el ítem activo
+- `aria-label` en cada ítem: Descripción de la acción del ítem
+
+## 💡 Mejores Prácticas
+
+### ✅ Hacer
+
+1. **Usar entre 3-5 ítems** para mejor usabilidad
+2. **Iconos simples y reconocibles** de 16x16px
+3. **Labels cortos** (máximo 10 caracteres)
+4. **Primer ítem como "Inicio"** o vista principal
+5. **Fijar en bottom** con `position: fixed`
+6. **Considerar safe-area-inset-bottom** en dispositivos con notch
+
+```tsx
+// ✅ CORRECTO
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ]}
+  activeItemId="home"
+/>
+```
+
+### ❌ Evitar
+
+1. **NO usar más de 5 ítems**
+2. **NO usar labels largos** ("Configuración Avanzada" → "Ajustes")
+3. **NO usar en desktop** (usar sidebar o tabs)
+4. **NO cambiar orden de ítems** dinámicamente
+5. **NO omitir el indicador de ítem activo**
+
+```tsx
+// ❌ INCORRECTO - Demasiados ítems
+<NavigationBar
+  items={[
+    { id: '1', icon: <Icon1 />, label: 'Item 1' },
+    { id: '2', icon: <Icon2 />, label: 'Item 2' },
+    { id: '3', icon: <Icon3 />, label: 'Item 3' },
+    { id: '4', icon: <Icon4 />, label: 'Item 4' },
+    { id: '5', icon: <Icon5 />, label: 'Item 5' },
+    { id: '6', icon: <Icon6 />, label: 'Item 6' }, // ❌ Demasiados
+    { id: '7', icon: <Icon7 />, label: 'Item 7' }, // ❌ Demasiados
+  ]}
+/>
+```
+
+## 🎨 Especificaciones de Diseño
+
+### Tipografía
+
+- **Label**: 10px Bold (Label XXSmall según `docs/typography.md`)
+- **Line Height**: 12px
+- **Font Family**: SiesaBT Bold
+
+### Espaciado
+
+- **Padding contenedor**: 16px (`p-4`)
+- **Gap entre ítems**: 8px (`gap-2`)
+- **Gap icono-label**: 4px (`gap-1`)
+- **Padding icon-container**: 16px horizontal, 4px vertical (`px-4 py-1`)
+
+### Iconos
+
+- **Tamaño**: 16x16px (`w-4 h-4`)
+- **Formato**: SVG con `stroke="currentColor"`
+- **Estilo**: Outline (no fill)
+
+### Colores
+
+- **Fondo activo (light)**: `#dbeefe` (`bg-primary-custom-100`)
+- **Fondo activo (dark)**: `rgba(219, 238, 254, 0.2)` (`dark:bg-primary-custom-100/20`)
+- **Texto/Icono**: Token `content-primary` / `dark-content-primary`
+
+## 🔗 Ver También
+
+- [Figma - NavigationBar](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4348-22539)
+- [Documentación de Colores](../../docs/colors.md)
+- [Documentación de Tipografía](../../docs/typography.md)
+- [Documentación de Espaciado](../../docs/spacing.md)
+- [NavigationRail](../NavigationRail) - Componente similar para desktop
+
+## 📚 Ejemplos de Casos de Uso
+
+### E-commerce App
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'cart', icon: <CartIcon />, label: 'Carrito' },
+    { id: 'profile', icon: <UserIcon />, label: 'Cuenta' },
+  ]}
+/>
+```
+
+### Social Media App
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Explorar' },
+    { id: 'notifications', icon: <BellIcon />, label: 'Alertas' },
+    { id: 'favorites', icon: <HeartIcon />, label: 'Guardados' },
+    { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+  ]}
+/>
+```
+
+### Banking App
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'payments', icon: <PaymentIcon />, label: 'Pagos' },
+    { id: 'cards', icon: <CardIcon />, label: 'Tarjetas' },
+    { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+  ]}
+/>
+```
+
+---
+
+**Versión**: 1.0.0
+**Última actualización**: 2025-11-20
+**Mantenido por**: Equipo Siesa UI Kit

package/{dist/components/NavigationBar/index.d.ts → src/components/NavigationBar/index.ts}

@@ -1,3 +1,2 @@
-export { NavigationBar } from './NavigationBar';
-export type { NavigationBarProps, NavigationBarItem } from './NavigationBar.types';
-//# sourceMappingURL=index.d.ts.map
+export { NavigationBar } from './NavigationBar';
+export type { NavigationBarProps, NavigationBarItem } from './NavigationBar.types';