siesa-ui-kit 1.0.3 → 1.0.4

package/src/components/NavigationRailTypes/README.md

@@ -0,0 +1,573 @@
+# NavigationRailTypes
+
+Barra de navegación lateral del sistema de diseño Siesa que permite dos modos visuales distintos: **collapsed** (solo iconos) y **expanded** (con labels y búsqueda).
+
+## 📋 Tabla de Contenidos
+
+1. [Descripción](#descripción)
+2. [Características](#características)
+3. [Especificaciones de Diseño](#especificaciones-de-diseño)
+4. [Uso](#uso)
+5. [Props](#props)
+6. [Estados](#estados)
+7. [Ejemplos](#ejemplos)
+8. [Accesibilidad](#accesibilidad)
+9. [Dark Mode](#dark-mode)
+10. [Referencias](#referencias)
+
+---
+
+## Descripción
+
+El componente **NavigationRailTypes** es una barra de navegación lateral responsive que proporciona navegación vertical en aplicaciones de escritorio. Soporta dos modos de visualización que se pueden cambiar dinámicamente mediante el botón de collapse/expand.
+
+### Caso de Uso Principal
+
+- **Navegación principal en aplicaciones desktop**: Menú lateral principal
+- **Aplicaciones con múltiples módulos**: Agrupar opciones de navegación
+- **Dashboard y sistemas administrativos**: Acceso rápido a secciones
+- **Aplicaciones de desktop**: Similar a sidebars en VS Code, Figma, etc.
+
+---
+
+## Características
+
+✅ **Dos modos de visualización:**
+- **Collapsed**: 80px width, solo iconos
+- **Expanded**: 215px width, con labels y búsqueda integrada
+
+✅ **Items de navegación:**
+- Iconos personalizables (16x16px)
+- Labels descriptivos (solo en expanded)
+- Estados: default, hover, active, disabled
+- Badges de notificación (dot rojo o contador)
+
+✅ **Búsqueda integrada:**
+- Solo visible en modo expanded
+- Input con icono de búsqueda
+- Placeholder "Buscar módulo"
+
+✅ **Footer con acciones:**
+- Botón "Recientes" (clock icon)
+- Botón collapse/expand con animación
+- Divisores visuales
+
+✅ **Dark Mode:**
+- Soporte completo para light/dark
+- Colores adaptados automáticamente
+
+✅ **Accesibilidad:**
+- Focus rings adaptativos
+- ARIA labels en botones
+- Navegación por teclado
+
+✅ **Animaciones:**
+- Transición suave al collapse/expand
+- Hover effects en items
+- Rotación del chevron
+
+---
+
+## Especificaciones de Diseño
+
+### Dimensiones
+
+| Propiedad | Collapsed | Expanded |
+|-----------|-----------|----------|
+| **Width** | 80px | 215px |
+| **Height** | 900px | 900px |
+| **Item Height** | Automático | Automático |
+| **Border Radius** | N/A | 8px (items) |
+
+### Espaciado (Spacing)
+
+| Elemento | Padding | Margin | Gap |
+|----------|---------|--------|-----|
+| **Item** (collapsed) | `px-4 py-1` | N/A | `gap-3` |
+| **Item** (expanded) | `px-4 py-2` | N/A | `gap-3` |
+| **Search** (expanded) | `px-3 py-3` | N/A | `gap-2` |
+| **Footer** | `px-3` | N/A | `gap-3` |
+
+### Tipografía
+
+| Elemento | Familia | Tamaño | Peso | Line Height |
+|----------|---------|--------|------|-------------|
+| **Label Item** | SiesaBT | 14px | Regular | 20px |
+| **Button Label** | SiesaBT | 14px | Bold | 20px |
+| **Placeholder** | Inter | 14px | Regular | 20px |
+
+### Colores (Light Mode)
+
+| Elemento | Color | Hex |
+|----------|-------|-----|
+| **Background** | background-primary | #ffffff |
+| **Border** | border-primary | #e4e4e7 |
+| **Text** | content-primary | #18181b |
+| **Icon** | content-secondary | #a1a1aa |
+| **Icon Hover** | content-custom-primary | #0e79fd |
+| **Active Bg** | background-custom-primary | #dbeefe |
+
+### Colores (Dark Mode)
+
+| Elemento | Color | Hex |
+|----------|-------|-----|
+| **Background** | background-primary/dark | #09090b |
+| **Border** | border-primary/dark | #3f3f46 |
+| **Text** | content-primary/dark | #fafafa |
+| **Icon** | content-secondary/dark | #a1a1aa |
+| **Icon Hover** | content-custom-primary/dark | #bfe2fe |
+| **Active Bg** | background-custom-primary/dark | #0e5ab0 |
+
+### Sombras
+
+| Elemento | Sombra |
+|----------|--------|
+| **Search Button** | `shadow-button-inset` |
+| **Search Input** | `shadow-sm` |
+| **Items** | Ninguna |
+
+---
+
+## Uso
+
+### Importación
+
+```tsx
+import { NavigationRailTypes } from '@/components/NavigationRailTypes';
+import type { NavigationRailItem } from '@/components/NavigationRailTypes';
+```
+
+### Instalación de Dependencias
+
+Este componente reutiliza:
+- `Button` - Botones en footer
+- `Input` - Input de búsqueda (input nativo mejorado)
+- `Divider` - Líneas divisoras
+- `DropdownItemCollapsible` - Items en modo expandido
+
+Asegúrate de tener estos componentes instalados.
+
+---
+
+## Props
+
+### NavigationRailTypesProps
+
+```typescript
+interface NavigationRailTypesProps {
+  /**
+   * Si el rail está colapsado (iconos solo) o expandido
+   * @default true
+   */
+  collapsed?: boolean;
+
+  /**
+   * Items de navegación a mostrar
+   * @default []
+   */
+  items?: NavigationRailItem[];
+
+  /**
+   * Si mostrar el botón "Recientes" en footer
+   * @default true
+   */
+  showRecentButton?: boolean;
+
+  /**
+   * Callback cuando collapsed cambia
+   */
+  onCollapsedChange?: (collapsed: boolean) => void;
+
+  /**
+   * Callback cuando se clickea un item
+   */
+  onItemClick?: (index: number, item: NavigationRailItem) => void;
+
+  /**
+   * Classes CSS adicionales
+   */
+  className?: string;
+}
+```
+
+### NavigationRailItem
+
+```typescript
+interface NavigationRailItem {
+  /**
+   * Identificador único
+   */
+  id: string;
+
+  /**
+   * Etiqueta del item
+   */
+  label: string;
+
+  /**
+   * Icono (16x16px recomendado)
+   */
+  icon: ReactNode;
+
+  /**
+   * Si está activo
+   * @default false
+   */
+  active?: boolean;
+
+  /**
+   * Si está deshabilitado
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Callback onClick
+   */
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+
+  /**
+   * URL para navegación
+   */
+  href?: string;
+
+  /**
+   * ARIA label para accesibilidad
+   */
+  ariaLabel?: string;
+
+  /**
+   * Badge de notificación (dot)
+   */
+  badge?: boolean;
+
+  /**
+   * Contador de notificaciones (99+ para >99)
+   */
+  badgeCount?: number;
+
+  /**
+   * Color del badge
+   * @default 'red'
+   */
+  badgeColor?: 'red' | 'blue' | 'green' | 'yellow' | 'orange';
+}
+```
+
+---
+
+## Estados
+
+### Estado Default (No Interactuado)
+
+```
+Collapsed:
+- Icon color: content-secondary (#a1a1aa)
+- Opacity: 100%
+- Cursor: pointer
+
+Expanded:
+- Text color: content-primary (#18181b)
+- Icon color: content-secondary (#a1a1aa)
+- Background: transparent
+- Opacity: 100%
+```
+
+### Estado Hover
+
+```
+Collapsed:
+- Icon color: content-custom-primary (#0e79fd)
+- Opacity: 80%
+- Scale: 1.05
+
+Expanded:
+- Background: background-custom-primary (#dbeefe)
+- Text color: content-custom-primary (#0e79fd)
+- Icon color: content-custom-primary (#0e79fd)
+```
+
+### Estado Active
+
+```
+Collapsed:
+- Icon color: content-custom-primary (#0e79fd)
+- Background: Subtle overlay
+
+Expanded:
+- Background: background-custom-primary (#dbeefe)
+- Text color: content-custom-primary (#0e79fd)
+- Icon color: content-custom-primary (#0e79fd)
+```
+
+### Estado Disabled
+
+```
+Collapsed & Expanded:
+- Opacity: 50%
+- Cursor: not-allowed
+- Pointer events: none
+```
+
+### Estado Focus
+
+```
+Collapsed & Expanded:
+- Ring: 4px solid primary-custom-400 (#60b6fa)
+- Ring offset: 2px background-primary (#ffffff)
+- Outline: none
+```
+
+---
+
+## Ejemplos
+
+### Ejemplo Básico
+
+```tsx
+import { NavigationRailTypes } from '@/components/NavigationRailTypes';
+import { HomeIcon, UsersIcon, SettingsIcon } from '@heroicons/react/outline';
+
+export function AppLayout() {
+  const [collapsed, setCollapsed] = useState(true);
+
+  const navItems = [
+    {
+      id: 'home',
+      label: 'Home',
+      icon: <HomeIcon className="size-4" />,
+      active: true,
+    },
+    {
+      id: 'users',
+      label: 'Users',
+      icon: <UsersIcon className="size-4" />,
+    },
+    {
+      id: 'settings',
+      label: 'Settings',
+      icon: <SettingsIcon className="size-4" />,
+    },
+  ];
+
+  return (
+    <div className="flex h-screen">
+      <NavigationRailTypes
+        collapsed={collapsed}
+        items={navItems}
+        onCollapsedChange={setCollapsed}
+        onItemClick={(index, item) => {
+          console.log('Navigated to:', item.id);
+        }}
+      />
+      <main className="flex-1 overflow-auto">
+        {/* Contenido principal */}
+      </main>
+    </div>
+  );
+}
+```
+
+### Con Badges de Notificación
+
+```tsx
+const navItems = [
+  {
+    id: 'messages',
+    label: 'Messages',
+    icon: <MessageIcon className="size-4" />,
+    badge: true, // Dot rojo simple
+  },
+  {
+    id: 'notifications',
+    label: 'Notifications',
+    icon: <BellIcon className="size-4" />,
+    badgeCount: 12, // Contador numérico
+    badgeColor: 'blue',
+  },
+];
+```
+
+### Con Items Deshabilitados
+
+```tsx
+const navItems = [
+  {
+    id: 'premium',
+    label: 'Premium Features',
+    icon: <StarIcon className="size-4" />,
+    disabled: true, // No clickeable
+  },
+];
+```
+
+### Con Navegación Router
+
+```tsx
+import { useNavigate } from 'react-router-dom';
+
+export function Navigation() {
+  const navigate = useNavigate();
+
+  const navItems = [
+    {
+      id: 'dashboard',
+      label: 'Dashboard',
+      icon: <DashboardIcon className="size-4" />,
+      onClick: () => navigate('/dashboard'),
+    },
+    {
+      id: 'users',
+      label: 'Manage Users',
+      icon: <UsersIcon className="size-4" />,
+      onClick: () => navigate('/users'),
+    },
+  ];
+
+  return (
+    <NavigationRailTypes
+      items={navItems}
+      onItemClick={(_, item) => item.onClick?.({} as any)}
+    />
+  );
+}
+```
+
+---
+
+## Accesibilidad
+
+### Features de Accesibilidad
+
+✅ **Focus Management:**
+- Focus rings visibles (4px) en todos los items
+- Focus visible en botones collapse/expand
+- Orden tab lógico de arriba a abajo
+
+✅ **ARIA Attributes:**
+- `aria-label` en botones sin texto visible (iconOnly)
+- `role="button"` implícito en elementos clickeables
+- `disabled` attribute para items deshabilitados
+
+✅ **Navegación por Teclado:**
+- Tab/Shift+Tab para moverse entre items
+- Enter/Space para activar items
+- Escape para cerrar (si es popover)
+
+✅ **Colores y Contraste:**
+- Ratio de contraste WCAG AA/AAA
+- No depender solo del color para indicar estado
+- Iconos con fallback a text
+
+✅ **Semántica:**
+- Botones semánticos (`<button>`)
+- Labels asociados a inputs
+- Estructura lógica del DOM
+
+---
+
+## Dark Mode
+
+El componente soporta dark mode automáticamente. Los colores se invierten cuando se activa:
+
+```tsx
+<div className="dark">
+  <NavigationRailTypes {...props} />
+</div>
+```
+
+### Colores en Dark Mode
+
+| Light | Dark |
+|-------|------|
+| `#ffffff` bg | `#09090b` bg |
+| `#18181b` text | `#fafafa` text |
+| `#a1a1aa` icon | `#a1a1aa` icon |
+| `#0e79fd` primary | `#bfe2fe` primary |
+| `#e4e4e7` border | `#3f3f46` border |
+
+### Utilidades CSS para Dark Mode
+
+El componente usa clases de dark mode nativas de Tailwind:
+
+```tsx
+// Ejemplos en el código
+className="dark:bg-background-primary"
+className="dark:text-content-primary"
+className="dark:border-border-primary"
+```
+
+---
+
+## Referencias
+
+- **Figma Design**: [NavigationRailTypes Node 6135-36219](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6135-36219&m=dev)
+- **Sistema de Colores**: `docs/colors.md`
+- **Sistema de Tipografía**: `docs/typography.md`
+- **Sistema de Spacing**: `docs/spacing.md`
+- **Sistema de Sombras**: `docs/shadows.md`
+- **Componente Button**: `src/components/Button`
+- **Componente DropdownItemCollapsible**: `src/components/DropdownItemCollapsible`
+- **Componente Input**: `src/components/Input`
+- **Componente Divider**: `src/components/Divider`
+
+---
+
+## Historial de Cambios
+
+### v1.0.0 (Inicial)
+
+- ✨ Componente NavigationRailTypes creado
+- ✨ Soporte para modo collapsed/expanded
+- ✨ Badges de notificación
+- ✨ Búsqueda integrada
+- ✨ Dark mode completo
+- ✨ Historias de Storybook
+- ✨ Documentación completa
+
+---
+
+## Notas de Implementación
+
+### Reutilización de Componentes
+
+Este componente reutiliza:
+
+1. **Button** - Para los botones en footer
+2. **Divider** - Para separadores visuales
+3. **DropdownItemCollapsible** - Para items en modo expandido
+4. **Input** - Mejorado con input nativo para búsqueda
+
+### Consideraciones de Performance
+
+- Los items se renderizan conmigo un array `map()`
+- No hay virtualization aún (500px altura para algunos browsers)
+- Para 100+ items, considerar virtualización
+
+### Compatibilidad
+
+- React 18+
+- Tailwind CSS 3+
+- Navegadores modernos (Chrome, Firefox, Safari, Edge)
+
+---
+
+## FAQ
+
+**P: ¿Puedo personalizar el ancho del rail?**
+R: Actualmente, el ancho está fijo (80px collapsed, 215px expanded). Para personalizar, modifica las clases `w-[80px]` y `w-[215px]` en el componente.
+
+**P: ¿Cómo integro con React Router?**
+R: Usa el callback `onItemClick` para navegar:
+```tsx
+onItemClick={(_, item) => navigate(`/${item.id}`)}
+```
+
+**P: ¿Puedo agregar más iconos?**
+R: Sí, pasa cualquier ReactNode como prop `icon` en los items.
+
+**P: ¿El rail es responsive para mobile?**
+R: No actualmente. Para mobile, considera un dropdown o hamburger menu.
+
+**P: ¿Puedo cambiar los colores?**
+R: Sí, todos los colores usan tokens CSS del sistema. Modifica las clases Tailwind para personalizar.

package/src/components/NavigationRailTypes/icons.tsx

@@ -0,0 +1,76 @@
+import React from 'react';
+// Importamos de 24/outline solo para el ClockIcon
+import { ClockIcon as HeroClockOutline } from '@heroicons/react/24/outline';
+
+// Importamos de 20/solid para los demás
+import {
+  ChevronRightIcon as HeroChevronRight,
+  ChevronLeftIcon as HeroChevronLeft,
+  MagnifyingGlassIcon as HeroSearch,
+  HomeIcon as HeroHome,
+  UsersIcon as HeroUsers,
+  Cog6ToothIcon as HeroSettings,
+} from '@heroicons/react/20/solid';
+
+/**
+ * Props comunes para los iconos
+ */
+interface IconProps {
+  className?: string;
+}
+
+/**
+ * Icono Chevron Right (apunta hacia la derecha)
+ * Usado en el botón de collapse
+ */
+export const ChevronRightIcon: React.FC<IconProps> = ({ className = 'size-5' }) => (
+  <HeroChevronRight className={className} aria-hidden="true" />
+);
+
+/**
+ * Icono Chevron Left (apunta hacia la izquierda)
+ * Usado en el botón de expand
+ */
+export const ChevronLeftIcon: React.FC<IconProps> = ({ className = 'size-5' }) => (
+  <HeroChevronLeft className={className} aria-hidden="true" />
+);
+
+/**
+ * Icono Clock (reloj) - Estilo OUTLINE 24
+ * Usado en el botón "Recientes"
+ */
+export const ClockIcon: React.FC<IconProps> = ({ className = 'size-5' }) => (
+  <HeroClockOutline className={className} aria-hidden="true" />
+);
+
+/**
+ * Icono Magnifying Glass (búsqueda)
+ * Usado en el botón de búsqueda
+ */
+export const MagnifyingGlassIcon: React.FC<IconProps> = ({ className = 'size-5' }) => (
+  <HeroSearch className={className} aria-hidden="true" />
+);
+
+/**
+ * Icono Home
+ * Ejemplo para items de navegación
+ */
+export const HomeIcon: React.FC<IconProps> = ({ className = 'size-5' }) => (
+  <HeroHome className={className} aria-hidden="true" />
+);
+
+/**
+ * Icono Users
+ * Ejemplo para items de navegación
+ */
+export const UsersIcon: React.FC<IconProps> = ({ className = 'size-5' }) => (
+  <HeroUsers className={className} aria-hidden="true" />
+);
+
+/**
+ * Icono Settings
+ * Ejemplo para items de navegación
+ */
+export const SettingsIcon: React.FC<IconProps> = ({ className = 'size-5' }) => (
+  <HeroSettings className={className} aria-hidden="true" />
+);

package/src/components/NavigationRailTypes/index.ts

@@ -0,0 +1,7 @@
+export { NavigationRailTypes } from './NavigationRailTypes';
+export { default } from './NavigationRailTypes';
+export type {
+  NavigationRailTypesProps,
+  NavigationRailItem,
+  NavigationRailCollapsibleItem,
+} from './NavigationRailTypes.types';