siesa-ui-kit 1.0.1 → 1.0.2

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,141 @@
+import React from 'react';
+
+/**
+ * Icono Chevron Right (apunta hacia la derecha)
+ * Usado en el botón de collapse
+ * Tamaño recomendado: 16x16px
+ */
+export const ChevronRightIcon: React.FC<{ className?: string }> = ({ className = 'size-4' }) => (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    className={className}
+  >
+    <polyline points="9 18 15 12 9 6"></polyline>
+  </svg>
+);
+
+/**
+ * Icono Chevron Left (apunta hacia la izquierda)
+ * Usado en el botón de expand
+ * Tamaño recomendado: 16x16px
+ */
+export const ChevronLeftIcon: React.FC<{ className?: string }> = ({ className = 'size-4' }) => (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    className={className}
+  >
+    <polyline points="15 18 9 12 15 6"></polyline>
+  </svg>
+);
+
+/**
+ * Icono Clock (reloj)
+ * Usado en el botón "Recientes"
+ * Tamaño recomendado: 16x16px
+ */
+export const ClockIcon: React.FC<{ className?: string }> = ({ className = 'size-4' }) => (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    className={className}
+  >
+    <circle cx="12" cy="12" r="10"></circle>
+    <polyline points="12 6 12 12 16 14"></polyline>
+  </svg>
+);
+
+/**
+ * Icono Magnifying Glass (búsqueda)
+ * Usado en el botón de búsqueda
+ * Tamaño recomendado: 16x16px
+ */
+export const MagnifyingGlassIcon: React.FC<{ className?: string }> = ({ className = 'size-4' }) => (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    className={className}
+  >
+    <circle cx="11" cy="11" r="8"></circle>
+    <path d="m21 21-4.35-4.35"></path>
+  </svg>
+);
+
+/**
+ * Icono Home
+ * Ejemplo para items de navegación
+ * Tamaño recomendado: 16x16px
+ */
+export const HomeIcon: React.FC<{ className?: string }> = ({ className = 'size-4' }) => (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    className={className}
+  >
+    <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"></path>
+    <polyline points="9 22 9 12 15 12 15 22"></polyline>
+  </svg>
+);
+
+/**
+ * Icono Users
+ * Ejemplo para items de navegación
+ * Tamaño recomendado: 16x16px
+ */
+export const UsersIcon: React.FC<{ className?: string }> = ({ className = 'size-4' }) => (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    className={className}
+  >
+    <path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"></path>
+    <circle cx="9" cy="7" r="4"></circle>
+    <path d="M23 21v-2a4 4 0 0 0-3-3.87"></path>
+    <path d="M16 3.13a4 4 0 0 1 0 7.75"></path>
+  </svg>
+);
+
+/**
+ * Icono Settings
+ * Ejemplo para items de navegación
+ * Tamaño recomendado: 16x16px
+ */
+export const SettingsIcon: React.FC<{ className?: string }> = ({ className = 'size-4' }) => (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    className={className}
+  >
+    <circle cx="12" cy="12" r="3"></circle>
+    <path d="M12 1v6m0 6v6M4.22 4.22l4.24 4.24m3.08 3.08l4.24 4.24M1 12h6m6 0h6m-2.78-7.78l-4.24 4.24m-3.08 3.08l-4.24 4.24"></path>
+  </svg>
+);

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';