siesa-ui-kit 1.0.2 → 1.0.3

package/src/components/NavigationRailPanel/README.md

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

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