siesa-ui-kit 1.0.0 → 1.0.2

package/src/components/NavigationRailPanel/README.md

@@ -0,0 +1,461 @@
+# NavigationRailPanel
+
+Panel de navegación vertical (rail) que puede contener múltiples secciones de items, búsqueda y encabezados. Se usa típicamente en aplicaciones con navegación compleja que requieren una estructura jerárquica.
+
+## 📋 Tabla de Contenidos
+
+1. [Descripción](#descripción)
+2. [Características](#características)
+3. [Props](#props)
+4. [Estructura](#estructura)
+5. [Ejemplos de Uso](#ejemplos-de-uso)
+6. [Especificaciones de Figma](#especificaciones-de-figma)
+7. [Colores y Dark Mode](#colores-y-dark-mode)
+8. [Espaciado](#espaciado)
+9. [Accesibilidad](#accesibilidad)
+10. [Referencias](#referencias)
+
+---
+
+## Descripción
+
+El componente `NavigationRailPanel` es un contenedor de navegación vertical que organiza elementos en una estructura jerárquica. Está diseñado para uso en aplicaciones complejas que requieren navegación por categorías, búsqueda de items y menús expandibles.
+
+### Casos de Uso
+
+- Aplicaciones con muchas opciones de navegación
+- Paneles de administración con menús colapsables
+- Sistemas de gestión con categorización
+- Aplicaciones POS con categorías de productos
+- Navegación de módulos en aplicaciones empresariales
+
+---
+
+## Características
+
+✅ **Estructura Flexible**
+- Soporte para secciones con encabezados
+- Items simples y colapsables
+- Items anidados con indentación automática
+
+✅ **Búsqueda Integrada**
+- Input de búsqueda con placeholder personalizable
+- Callbacks de cambio de valor
+- Controlable desde el padre
+
+✅ **Encabezado Personalizable**
+- DropdownItemHeading reutilizado
+- Icono, label, descripción y acción
+- Callback para acción
+
+✅ **Dark Mode Completo**
+- Todos los elementos inversos en dark mode
+- Colores adaptativos
+- Accesibilidad mantenida
+
+✅ **Estados Visuales**
+- Hover, focus, active, disabled
+- Transiciones suaves
+- Focus rings adaptativos
+
+✅ **Scroll**
+- El body es scrolleable
+- Encabezado y búsqueda fijos
+- Comportamiento nativo del navegador
+
+✅ **Componentes Reutilizados**
+- `DropdownItemHeading` - Para el encabezado
+- `DropdownItemCollapsible` - Para items colapsables
+- `Input` - Para la búsqueda
+- `Divider` - Para separadores
+
+---
+
+## Props
+
+### NavigationRailPanelProps
+
+```typescript
+interface NavigationRailPanelProps {
+  // Dimensiones
+  height?: number | string;           // Por defecto: 900
+  width?: number | string;            // Por defecto: 248
+
+  // Encabezado
+  showHeading?: boolean;              // Por defecto: true
+  heading?: {
+    label: string;
+    description?: string;
+    showDescription?: boolean;
+    iconName?: string;
+    actionLabel?: string;
+    showAction?: boolean;
+    onActionClick?: () => void;
+  };
+
+  // Búsqueda
+  showSearch?: boolean;               // Por defecto: true
+  search?: {
+    placeholder?: string;             // Por defecto: "Buscar módulo"
+    value?: string;
+    onChange?: (value: string) => void;
+    showLabel?: boolean;              // Por defecto: false
+    showLink?: boolean;               // Por defecto: true
+  };
+
+  // Contenido
+  sections?: NavigationRailPanelSectionProps[];
+  items?: NavigationRailPanelItemProps[];
+
+  // Clases CSS
+  className?: string;
+  panelClassName?: string;
+}
+```
+
+### NavigationRailPanelSectionProps
+
+```typescript
+interface NavigationRailPanelSectionProps {
+  heading?: string;                   // Encabezado de la sección
+  items: NavigationRailPanelItemProps[];
+  showDivider?: boolean;              // Por defecto: true
+  className?: string;
+}
+```
+
+### NavigationRailPanelItemProps
+
+```typescript
+interface NavigationRailPanelItemProps {
+  label: string;                      // Texto del item
+  icon?: ReactNode;                   // Icono opcional
+  isCollapsible?: boolean;            // Por defecto: false
+  children?: DropdownItemCollapsibleChildProps[];
+  defaultOpen?: boolean;              // Por defecto: false
+  disabled?: boolean;                 // Por defecto: false
+  onClick?: (e: React.MouseEvent) => void;
+  onOpenChange?: (open: boolean) => void;
+  className?: string;
+}
+```
+
+---
+
+## Estructura
+
+### Layout Principal
+
+```
+┌─────────────────────────┐
+│   Encabezado (Opcional) │  <- DropdownItemHeading
+├─────────────────────────┤
+│   Búsqueda (Opcional)   │  <- Input
+├─────────────────────────┤
+│   Body (Scrolleable)    │
+│ ┌─────────────────────┐ │
+│ │  Section Heading    │ │
+│ │  Item 1 (Simple)    │ │
+│ │  Item 2 (Collapsible)│
+│ │  ├─ Sub Item 1      │ │
+│ │  └─ Sub Item 2      │ │
+│ │  ---                │ │
+│ │  Section Heading    │ │
+│ │  Item 3             │ │
+│ │  Item 4             │ │
+│ └─────────────────────┘ │
+└─────────────────────────┘
+```
+
+### Especificaciones
+
+| Elemento | Ancho | Altura | Padding | Border Radius |
+|----------|-------|--------|---------|---------------|
+| Panel | 248px | Variable | 12px | 0px |
+| Encabezado | 224px | Auto | 8v, 16h | 8px |
+| Búsqueda | 224px | 40px | 8v, 16h | 6px |
+| Item | 224px | 32px | 8v, 16p | 8px |
+| Section Heading | 224px | Auto | 12t, 4b | 0px |
+
+---
+
+## Ejemplos de Uso
+
+### Ejemplo Simple con Secciones
+
+```tsx
+import { NavigationRailPanel } from '@/components/NavigationRailPanel';
+
+export function Dashboard() {
+  return (
+    <NavigationRailPanel
+      height={900}
+      showHeading={true}
+      heading={{
+        label: 'Settings',
+        description: 'Configure your preferences',
+        iconName: 'cog-6-tooth',
+      }}
+      showSearch={true}
+      sections={[
+        {
+          heading: 'NAVIGATION',
+          items: [
+            { label: 'Dashboard', isCollapsible: false },
+            { label: 'Analytics', isCollapsible: false },
+          ],
+        },
+        {
+          heading: 'MANAGEMENT',
+          items: [
+            {
+              label: 'Users',
+              isCollapsible: true,
+              children: [
+                { label: 'Active Users' },
+                { label: 'Inactive Users' },
+              ],
+            },
+          ],
+        },
+      ]}
+    />
+  );
+}
+```
+
+### Ejemplo sin Encabezado y Búsqueda
+
+```tsx
+<NavigationRailPanel
+  showHeading={false}
+  showSearch={false}
+  items={[
+    { label: 'Dashboard' },
+    { label: 'Users' },
+    { label: 'Settings' },
+  ]}
+/>
+```
+
+### Ejemplo con Callbacks
+
+```tsx
+<NavigationRailPanel
+  heading={{
+    label: 'Menu',
+    actionLabel: 'Clear',
+    showAction: true,
+    onActionClick: () => console.log('Clear clicked'),
+  }}
+  search={{
+    placeholder: 'Search...',
+    onChange: (value) => console.log('Search:', value),
+  }}
+  items={[
+    {
+      label: 'Item 1',
+      onClick: () => console.log('Item 1 clicked'),
+    },
+    {
+      label: 'Category',
+      isCollapsible: true,
+      onOpenChange: (open) => console.log('Toggled:', open),
+      children: [
+        { label: 'Sub Item' },
+      ],
+    },
+  ]}
+/>
+```
+
+### Ejemplo con Items Deshabilitados
+
+```tsx
+<NavigationRailPanel
+  items={[
+    { label: 'Active', disabled: false },
+    { label: 'Disabled', disabled: true },
+    {
+      label: 'Category',
+      isCollapsible: true,
+      disabled: true,
+      children: [
+        { label: 'Sub Item 1' },
+        { label: 'Sub Item 2', disabled: true },
+      ],
+    },
+  ]}
+/>
+```
+
+---
+
+## Especificaciones de Figma
+
+- **Nodo**: 6134-34415
+- **URL**: https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6134-34415
+
+### Dimensiones
+
+- Altura: 900px (variable)
+- Ancho: 248px (estándar)
+- Padding: 12px (todo)
+- Border radius: 0px (panel completo)
+
+### Tipografía
+
+| Elemento | Escala | Font Weight | Size | Line Height |
+|----------|--------|------------|------|------------|
+| Encabezado | Label/Small | 700 (Bold) | 14px | 20px |
+| Descripción | Paragraph/Tiny | 400 | 12px | 16px |
+| Section Heading | Paragraph/Tiny | 400 | 12px | 16px |
+| Item | Paragraph/Small | 400 | 14px | 20px |
+| Acción | Paragraph/XXSmall | 400 | 10px | 12px |
+
+---
+
+## Colores y Dark Mode
+
+### Light Mode
+
+| Elemento | Color | Hex |
+|----------|-------|-----|
+| Background | bg-primary | #ffffff |
+| Border | border-primary | #e4e4e7 |
+| Heading text | content-primary | #18181b |
+| Section heading | content-tertiary | #71717a |
+| Item text | content-primary | #18181b |
+| Icon | content-secondary | #a1a1aa |
+| Hover bg | background-custom-primary | #dbeefe |
+
+### Dark Mode
+
+| Elemento | Color | Hex |
+|----------|-------|-----|
+| Background | dark:bg-zinc-900 | #18181b |
+| Border | dark:border-zinc-800 | #3f3f46 |
+| Heading text | dark:content-primary-dark | #fafafa |
+| Section heading | dark:content-tertiary-dark | #a1a1aa |
+| Item text | dark:content-primary-dark | #fafafa |
+| Icon | dark:content-secondary | #a1a1aa |
+| Hover bg | dark:bg-background-custom-primary-dark | #0e5ab0 |
+
+### Tokens Utilizados
+
+- **Colores**: `content-primary`, `content-secondary`, `content-tertiary`, `bg-primary`, `border-primary`, `background-custom-primary`
+- **Dark Mode**: Se invierten automáticamente con prefijo `dark:`
+- **No hay colores hardcodeados**: Todo usa el sistema de tokens
+
+---
+
+## Espaciado
+
+| Elemento | Valor | Px |
+|----------|-------|-----|
+| Panel padding | 3 | 12px |
+| Item padding (h) | 4 | 16px |
+| Item padding (v) | 2 | 8px |
+| Gap entre items | 0.5 | 2px |
+| Gap entre elemento e icono | 3 | 12px |
+| Section heading pt | 3 | 12px |
+| Section heading pb | 1 | 4px |
+| Divider margin top | 3 | 12px |
+
+---
+
+## Accesibilidad
+
+✅ **Focus Management**
+- Focus rings adaptativos de 4px
+- Offset de 2px en light mode
+- Offset transparente en dark mode
+- Color focus: primary-custom-400 (#60b6fa)
+
+✅ **Keyboard Navigation**
+- Tab para navegar entre items
+- Enter/Space para activar
+- Arrow keys para items colapsables (heredado de DropdownItemCollapsible)
+
+✅ **ARIA**
+- Roles semánticos (button, heading, menuitem)
+- aria-disabled para items deshabilitados
+- aria-expanded para items colapsables
+
+✅ **Colores**
+- Contraste AA/AAA mantenido
+- No depender solo de color para indicar estado
+- Íconos con suficiente contraste
+
+---
+
+## Dark Mode
+
+El componente es **100% compatible con dark mode**:
+
+```tsx
+// El componente detecta automáticamente el tema
+<NavigationRailPanel
+  // Automáticamente invierte colores en dark mode
+  showHeading={true}
+  showSearch={true}
+/>
+```
+
+### Cambios en Dark Mode
+
+1. **Background**: white (#ffffff) → zinc-900 (#18181b)
+2. **Border**: border-primary (#e4e4e7) → border-zinc-800 (#3f3f46)
+3. **Text**: content-primary (#18181b) → content-primary-dark (#fafafa)
+4. **Icon hover**: dbeefe (#dbeefe) → 0e5ab0 (#0e5ab0)
+5. **Focus ring offset**: blanco → zinc-900
+
+---
+
+## Estados Visuales
+
+### Default
+- Sin interacción
+- Colores base
+
+### Hover
+- Background sutil: `background-custom-primary`
+- Cursor pointer
+- Transición suave
+
+### Focus
+- Focus ring de 4px
+- Color: `primary-custom-400`
+- Offset: 2px (light) / transparent (dark)
+
+### Active
+- Item colapsable expandido
+- Indicado por chevron rotado
+
+### Disabled
+- Opacidad: 50%
+- Cursor: not-allowed
+- Sin hover/focus interactivo
+
+---
+
+## Referencias
+
+### Documentación del Sistema
+
+- [@see docs/colors.md](../../../docs/colors.md) - Sistema de colores
+- [@see docs/typography.md](../../../docs/typography.md) - Sistema tipográfico
+- [@see docs/spacing.md](../../../docs/spacing.md) - Sistema de espaciado
+- [@see docs/shadows.md](../../../docs/shadows.md) - Sistema de sombras
+
+### Componentes Relacionados
+
+- [@see ../DropdownItemHeading](../DropdownItemHeading) - Encabezado reutilizado
+- [@see ../DropdownItemCollapsible](../DropdownItemCollapsible) - Items colapsables
+- [@see ../Input](../Input) - Búsqueda
+- [@see ../Divider](../Divider) - Separadores
+
+### Figma
+
+- [NavigationRailPanel en Figma](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6134-34415)
+- [Design System Documentation](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit)

package/src/components/NavigationRailPanel/index.ts

@@ -0,0 +1,6 @@
+export { NavigationRailPanel } from './NavigationRailPanel';
+export type {
+  NavigationRailPanelProps,
+  NavigationRailPanelSectionProps,
+  NavigationRailPanelItemProps,
+} from './NavigationRailPanel.types';