siesa-ui-kit 1.0.0 → 1.0.2

package/src/components/NavigationRail/NavigationRail.types.ts

@@ -1,109 +1,109 @@
-import type { ReactNode } from 'react';
-
-/**
- * Props para NavigationRailItem
- */
-export interface NavigationRailItemProps {
-  /**
-   * Icono a mostrar en el item
-   */
-  icon: ReactNode;
-
-  /**
-   * Label del item de navegación
-   */
-  label: string;
-
-  /**
-   * Si el item está seleccionado actualmente
-   * @default false
-   */
-  selected?: boolean;
-
-  /**
-   * Si el item está deshabilitado
-   * @default false
-   */
-  disabled?: boolean;
-
-  /**
-   * Mostrar badge de notificación (dot rojo)
-   * @default false
-   */
-  badge?: boolean;
-
-  /**
-   * Número a mostrar en el badge (reemplaza el dot)
-   */
-  badgeCount?: number;
-
-  /**
-   * Handler para evento click
-   */
-  onClick?: () => void;
-
-  /**
-   * Label para accesibilidad (ARIA)
-   */
-  ariaLabel?: string;
-
-  /**
-   * ID único del item (para navegación)
-   */
-  id?: string;
-}
-
-/**
- * Props del componente NavigationRail
- */
-export interface NavigationRailProps {
-  /**
-   * Items de navegación a mostrar
-   */
-  items: NavigationRailItemProps[];
-
-  /**
-   * Alineación vertical de los items
-   * - `top`: Items alineados arriba (debajo del FAB)
-   * - `center`: Items centrados verticalmente
-   * - `bottom`: Items alineados abajo
-   * @default 'top'
-   */
-  alignment?: 'top' | 'center' | 'bottom';
-
-  /**
-   * Mostrar botón FAB (Floating Action Button) en la parte superior
-   * @default false
-   */
-  showFab?: boolean;
-
-  /**
-   * Icono del botón FAB
-   */
-  fabIcon?: ReactNode;
-
-  /**
-   * Handler para click en el FAB
-   */
-  onFabClick?: () => void;
-
-  /**
-   * Label del FAB para accesibilidad
-   */
-  fabAriaLabel?: string;
-
-  /**
-   * Clases CSS adicionales para el contenedor
-   */
-  className?: string;
-
-  /**
-   * ID del item seleccionado actualmente
-   */
-  selectedId?: string;
-
-  /**
-   * Handler cuando se selecciona un item
-   */
-  onItemSelect?: (id: string) => void;
-}
+import type { ReactNode } from 'react';
+
+/**
+ * Props para NavigationRailItem
+ */
+export interface NavigationRailItemProps {
+  /**
+   * Icono a mostrar en el item
+   */
+  icon: ReactNode;
+
+  /**
+   * Label del item de navegación
+   */
+  label: string;
+
+  /**
+   * Si el item está seleccionado actualmente
+   * @default false
+   */
+  selected?: boolean;
+
+  /**
+   * Si el item está deshabilitado
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Mostrar badge de notificación (dot rojo)
+   * @default false
+   */
+  badge?: boolean;
+
+  /**
+   * Número a mostrar en el badge (reemplaza el dot)
+   */
+  badgeCount?: number;
+
+  /**
+   * Handler para evento click
+   */
+  onClick?: () => void;
+
+  /**
+   * Label para accesibilidad (ARIA)
+   */
+  ariaLabel?: string;
+
+  /**
+   * ID único del item (para navegación)
+   */
+  id?: string;
+}
+
+/**
+ * Props del componente NavigationRail
+ */
+export interface NavigationRailProps {
+  /**
+   * Items de navegación a mostrar
+   */
+  items: NavigationRailItemProps[];
+
+  /**
+   * Alineación vertical de los items
+   * - `top`: Items alineados arriba (debajo del FAB)
+   * - `center`: Items centrados verticalmente
+   * - `bottom`: Items alineados abajo
+   * @default 'top'
+   */
+  alignment?: 'top' | 'center' | 'bottom';
+
+  /**
+   * Mostrar botón FAB (Floating Action Button) en la parte superior
+   * @default false
+   */
+  showFab?: boolean;
+
+  /**
+   * Icono del botón FAB
+   */
+  fabIcon?: ReactNode;
+
+  /**
+   * Handler para click en el FAB
+   */
+  onFabClick?: () => void;
+
+  /**
+   * Label del FAB para accesibilidad
+   */
+  fabAriaLabel?: string;
+
+  /**
+   * Clases CSS adicionales para el contenedor
+   */
+  className?: string;
+
+  /**
+   * ID del item seleccionado actualmente
+   */
+  selectedId?: string;
+
+  /**
+   * Handler cuando se selecciona un item
+   */
+  onItemSelect?: (id: string) => void;
+}

package/src/components/NavigationRail/README.md

@@ -1,224 +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**
+# 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/src/components/NavigationRail/index.ts

@@ -1,2 +1,2 @@
-export { NavigationRail } from './NavigationRail';
-export type { NavigationRailProps, NavigationRailItemProps } from './NavigationRail.types';
+export { NavigationRail } from './NavigationRail';
+export type { NavigationRailProps, NavigationRailItemProps } from './NavigationRail.types';