siesa-ui-kit 1.0.3 → 1.0.5

package/src/components/NavigationRail/README.md

@@ -0,0 +1,224 @@
+# NavigationRail
+
+Componente de navegación vertical (rail) para aplicaciones del sistema de diseño Siesa.
+
+## Descripción
+
+El NavigationRail proporciona acceso rápido a destinos principales de la aplicación mediante iconos y labels opcionales. Es ideal para aplicaciones de escritorio y tablets donde se requiere navegación persistente sin ocupar mucho espacio horizontal.
+
+**Figma:** [Siesa UI Kit - Navigation Rail](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4294-22925&m=dev)
+
+## Características
+
+- ✅ **Ancho fijo de 80px** para navegación compacta y consistente
+- ✅ **Soporte para FAB** (Floating Action Button) en la parte superior
+- ✅ **Estados completos**: normal, hover, selected, disabled
+- ✅ **Badges de notificación** con contador opcional
+- ✅ **Alineación flexible**: top, center, bottom
+- ✅ **Dark mode completo** en todos los estados
+- ✅ **Accesibilidad**: ARIA labels, navegación por teclado
+- ✅ **Tipografía Label XXSmall** (10px Bold) según sistema de diseño
+
+## Instalación
+
+```tsx
+import { NavigationRail } from '@/components/NavigationRail';
+import type { NavigationRailProps, NavigationRailItemProps } from '@/components/NavigationRail';
+```
+
+## Uso Básico
+
+```tsx
+import { NavigationRail } from '@/components/NavigationRail';
+import { HomeIcon, SearchIcon, BellIcon, UserIcon } from '@/icons';
+
+function App() {
+  const [selectedId, setSelectedId] = useState('home');
+
+  return (
+    <NavigationRail
+      items={[
+        { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+        { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+        { id: 'notifications', icon: <BellIcon />, label: 'Notificaciones', badgeCount: 5 },
+        { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+      ]}
+      selectedId={selectedId}
+      onItemSelect={setSelectedId}
+      alignment="top"
+    />
+  );
+}
+```
+
+## Ejemplos
+
+### Con Botón FAB
+
+```tsx
+<NavigationRail
+  showFab
+  fabIcon={<PlusIcon />}
+  onFabClick={() => console.log('Create new')}
+  fabAriaLabel="Crear nuevo"
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio', selected: true },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+  ]}
+/>
+```
+
+### Con Badges de Notificación
+
+```tsx
+<NavigationRail
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    // Badge dot simple
+    { id: 'notifications', icon: <BellIcon />, label: 'Notificaciones', badge: true },
+    // Badge con contador
+    { id: 'messages', icon: <MessageIcon />, label: 'Mensajes', badgeCount: 12 },
+  ]}
+/>
+```
+
+### Alineación de Items
+
+```tsx
+// Items en la parte superior (default)
+<NavigationRail items={items} alignment="top" />
+
+// Items centrados verticalmente
+<NavigationRail items={items} alignment="center" />
+
+// Items en la parte inferior
+<NavigationRail items={items} alignment="bottom" />
+```
+
+### Estados de Items
+
+```tsx
+<NavigationRail
+  items={[
+    // Item normal
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    // Item seleccionado
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar', selected: true },
+    // Item deshabilitado
+    { id: 'settings', icon: <SettingsIcon />, label: 'Configuración', disabled: true },
+  ]}
+/>
+```
+
+## Props
+
+### NavigationRailProps
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `items` | `NavigationRailItemProps[]` | - | **Requerido.** Array de items de navegación |
+| `alignment` | `'top' \| 'center' \| 'bottom'` | `'top'` | Alineación vertical de los items |
+| `showFab` | `boolean` | `false` | Mostrar botón FAB en la parte superior |
+| `fabIcon` | `ReactNode` | - | Icono del botón FAB |
+| `onFabClick` | `() => void` | - | Handler para click en el FAB |
+| `fabAriaLabel` | `string` | `'Crear nuevo'` | Label del FAB para accesibilidad |
+| `className` | `string` | `''` | Clases CSS adicionales |
+| `selectedId` | `string` | - | ID del item seleccionado actualmente |
+| `onItemSelect` | `(id: string) => void` | - | Handler cuando se selecciona un item |
+
+### NavigationRailItemProps
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `icon` | `ReactNode` | - | **Requerido.** Icono a mostrar (16x16px) |
+| `label` | `string` | - | **Requerido.** Label del item |
+| `id` | `string` | - | ID único del item (recomendado para navegación) |
+| `selected` | `boolean` | `false` | Si el item está seleccionado |
+| `disabled` | `boolean` | `false` | Si el item está deshabilitado |
+| `badge` | `boolean` | `false` | Mostrar badge dot de notificación |
+| `badgeCount` | `number` | - | Número a mostrar en el badge (reemplaza el dot) |
+| `onClick` | `() => void` | - | Handler para click individual del item |
+| `ariaLabel` | `string` | - | Label ARIA (usa `label` si no se proporciona) |
+
+## Mejores Prácticas
+
+### ✅ Hacer
+
+- **Usar entre 3-7 items**: Óptimo para navegación principal sin scroll
+- **Iconos de 16x16px**: Tamaño estándar para máxima claridad
+- **Labels descriptivos**: Usar nombres cortos y claros (1-2 palabras)
+- **Indicar item activo**: Siempre mantener un item selected
+- **FAB para acción principal**: Usar para "Crear", "Nuevo", etc.
+- **Badges para notificaciones**: Actualizar en tiempo real
+- **IDs únicos**: Facilita el manejo de estado y navegación
+
+### ❌ Evitar
+
+- **Demasiados items**: Más de 7 items requiere scroll, considera otro patrón
+- **Labels largos**: Más de 12 caracteres pueden truncarse
+- **Iconos inconsistentes**: Usar mismo estilo visual en todos los iconos
+- **Sin item seleccionado**: Siempre debe haber uno selected
+- **Múltiples badges rojos**: Limitar uso para evitar fatiga visual
+
+## Especificaciones de Diseño
+
+### Dimensiones
+- **Ancho del rail**: 80px (w-20)
+- **Ancho del item**: 56px (w-14)
+- **Gap entre items**: 12px (gap-3)
+- **Gap FAB a items**: 40px (gap-10)
+- **Padding vertical**: 8px arriba, 40px abajo
+
+### Tipografía
+- **Label**: 10px Bold (Label XXSmall)
+- **Line height**: 12px (leading-3)
+
+### Colores
+
+#### Light Mode
+- **Default icon**: `content-primary` (#18181b)
+- **Hover bg**: `primary-custom-100` (#dbeefe)
+- **Hover icon**: `primary-custom-600` (#0e79fd)
+- **Selected bg**: `primary-custom-100` (#dbeefe)
+- **Selected icon**: `primary-custom-600` (#0e79fd)
+- **Badge**: `red-700` (#b91c1c)
+
+#### Dark Mode
+- **Default icon**: `dark-content-primary`
+- **Hover bg**: `primary-custom-100/20`
+- **Selected bg**: `primary-custom-100/20`
+- **Badge**: `red-700` (#b91c1c)
+
+### Estados Interactivos
+- **Hover**: Background azul suave, icon cambia a primary
+- **Selected**: Background azul con overlay, icon primary permanente
+- **Disabled**: Opacity 50%, cursor not-allowed, sin interacción
+- **Focus**: Ring 2px con primary-custom-400 en light, dark-border-custom en dark
+
+## Accesibilidad
+
+- ✅ **Roles ARIA**: `<nav>` con `aria-label="Navegación principal"`
+- ✅ **aria-current**: Items seleccionados tienen `aria-current="page"`
+- ✅ **aria-label**: Todos los items tienen labels descriptivos
+- ✅ **Navegación por teclado**: Tab para navegar, Enter/Space para activar
+- ✅ **Focus visible**: Anillos de enfoque claros y adaptativos
+- ✅ **Screen reader**: Badges anuncian cantidad de notificaciones
+- ✅ **Estados semánticos**: Disabled con `disabled` attribute y `aria-disabled`
+
+## Referencias
+
+- 📘 [Sistema de Colores](../../../docs/colors.md)
+- 📘 [Sistema Tipográfico](../../../docs/typography.md)
+- 📘 [Sistema de Espaciado](../../../docs/spacing.md)
+- 📘 [Sistema de Sombras](../../../docs/shadows.md)
+- 🎨 [Figma: Navigation Rail](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4294-22925&m=dev)
+
+## Componentes Relacionados
+
+- **Button**: Usado para el FAB button
+- **Badge**: Sistema de notificaciones similar
+- **Navbar**: Alternativa para navegación horizontal
+
+---
+
+**Implementado con ❤️ siguiendo Siesa UI Kit Design System**

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

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