siesa-ui-kit 1.0.0 → 1.0.1

package/src/components/NavigationRail/README.md

@@ -1,224 +0,0 @@
-# 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**