siesa-ui-kit 1.0.2 → 1.0.4

package/src/components/NavigationRailCommercial/NavigationRailCommercial.tsx

@@ -0,0 +1,301 @@
+import React, { useState } from 'react';
+import type {
+  NavigationRailCommercialProps,
+  NavigationRailCommercialMenuItem,
+} from './NavigationRailCommercial.types';
+import { NavigationRailTypes } from '../NavigationRailTypes/NavigationRailTypes';
+import { NavigationRailPanel } from '../NavigationRailPanel/NavigationRailPanel';
+import { MagnifyingGlassIcon } from './icons';
+
+/**
+ * NavigationRailCommercial del sistema de diseño Siesa
+ *
+ * Componente de navegación lateral especializado para aplicaciones comerciales
+ * que combina NavigationRailTypes y NavigationRailPanel para crear una experiencia
+ * de navegación completa con múltiples estados:
+ *
+ * - **Collapsed**: Barra compacta de 80px con solo iconos
+ * - **Expanded**: Barra expandida de 215px con labels
+ * - **Hover**: Panel lateral con submenú del item (se muestra al hacer hover)
+ * - **Searcher**: Panel lateral con búsqueda y recientes
+ *
+ * **Características:**
+ * - Reutiliza NavigationRailTypes para la barra lateral principal
+ * - Reutiliza NavigationRailPanel para los paneles de hover y búsqueda
+ * - Gestión de estado integrada (collapsed, expanded, hover, searcher)
+ * - Dark mode completo en todos los elementos
+ * - Focus rings adaptativos
+ * - Transiciones suaves entre estados
+ *
+ * **Especificaciones de Figma:**
+ * - NavigationRailTypes: 80px (collapsed) / 215px (expanded)
+ * - NavigationRailPanel: 248px width, altura variable
+ * - Posición panel: left 80px desde el rail
+ * - Transiciones: 300ms ease-in-out
+ *
+ * **Estructura:**
+ * ```
+ * ┌────────────────────────────────────┐
+ * │  NavigationRailCommercial          │
+ * │  ┌──────────┬─────────────────┐   │
+ * │  │  Rail    │  Panel          │   │
+ * │  │  Types   │  (hover/search) │   │
+ * │  │  (base)  │  (opcional)     │   │
+ * │  └──────────┴─────────────────┘   │
+ * └────────────────────────────────────┘
+ * ```
+ *
+ * **Estados de Items:**
+ * - `default`: Sin interacción
+ * - `hover`: Muestra panel con submenú (si tiene children)
+ * - `active`: Item seleccionado, fondo custom-primary
+ * - `disabled`: Opacity 50%, sin interacción
+ *
+ * **Colores (Light Mode):**
+ * - Background rail: #ffffff (bg-primary)
+ * - Background panel: #ffffff (bg-primary)
+ * - Borders: #e4e4e7 (border-primary)
+ * - Text: #18181b (content-primary)
+ * - Icons: #a1a1aa (content-secondary)
+ * - Search button: #0e79fd (primary-custom-600)
+ *
+ * **Colores (Dark Mode):**
+ * - Background rail: #18181b (dark-bg-primary)
+ * - Background panel: #18181b (dark-bg-primary)
+ * - Borders: #71717a (dark-border-primary)
+ * - Text: #f4f4f5 (dark-content-primary)
+ * - Icons: #a1a1aa (content-secondary)
+ *
+ * **Tipografía:**
+ * - Items: Paragraph/Small (14px Regular, line-height 20px)
+ * - Panel heading: Label/Small (14px Bold)
+ * - Section headings: Paragraph/Tiny (12px Regular)
+ *
+ * **Implementación de Estados:**
+ * - `collapsed` + hover en item → state='hover' + muestra panel
+ * - `collapsed` + click en search → state='searcher' + muestra panel búsqueda
+ * - `expanded` → NavigationRailTypes expandido con Input integrado
+ * - Click en "Colapsar" → vuelve a collapsed
+ *
+ * @see docs/colors.md - Sistema de colores
+ * @see docs/typography.md - Sistema tipográfico
+ * @see docs/spacing.md - Sistema de espaciado
+ * @see ../NavigationRailTypes - Componente reutilizado para barra lateral
+ * @see ../NavigationRailPanel - Componente reutilizado para paneles
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6146-34487
+ *
+ * @example
+ * ```tsx
+ * // Uso básico en modo collapsed
+ * const items = [
+ *   {
+ *     id: 'admin',
+ *     label: 'Administración',
+ *     icon: <Cog6ToothIcon />,
+ *     isCollapsible: true,
+ *     children: [
+ *       { id: 'users', label: 'Usuarios' },
+ *       { id: 'roles', label: 'Roles' },
+ *     ],
+ *   },
+ *   {
+ *     id: 'sales',
+ *     label: 'Ventas',
+ *     icon: <ShoppingCartIcon />,
+ *   },
+ * ];
+ *
+ * <NavigationRailCommercial
+ *   state="collapsed"
+ *   items={items}
+ *   onItemClick={(item) => console.log('Clicked:', item.label)}
+ *   onItemHover={(item) => console.log('Hover:', item.label)}
+ * />
+ *
+ * // Uso con control de estado externo
+ * const [state, setState] = useState('collapsed');
+ *
+ * <NavigationRailCommercial
+ *   state={state}
+ *   items={items}
+ *   onStateChange={setState}
+ * />
+ * ```
+ *
+ * @see NavigationRailCommercial.types.ts - Props e interfaces
+ */
+export const NavigationRailCommercial = React.forwardRef<
+  HTMLDivElement,
+  NavigationRailCommercialProps
+>(
+  (
+    {
+      state = 'collapsed',
+      items = [],
+      onStateChange,
+      onItemClick,
+      onItemHover,
+      labels = {},
+      className,
+      showSearchButton = true,
+    },
+    ref
+  ) => {
+    // Estado local para controlar el panel
+    const [showPanel, setShowPanel] = useState(false);
+    const [panelType, setPanelType] = useState<'hover' | 'searcher'>('hover');
+    const [hoveredItem, setHoveredItem] = useState<NavigationRailCommercialMenuItem | null>(null);
+
+    // Labels con valores por defecto
+    const finalLabels = {
+      searchPlaceholder: labels.searchPlaceholder ?? 'Buscar módulo',
+      collapseButton: labels.collapseButton ?? 'Colapsar',
+      recentSection: labels.recentSection ?? 'Recientes',
+      frequentSection: labels.frequentSection ?? 'Opciones frecuentes',
+    };
+
+    // Controlar el estado collapsed/expanded
+    const isCollapsed = state === 'collapsed' || state === 'hover' || state === 'searcher';
+
+    // Manejar cambio de estado collapsed/expanded
+    const handleCollapsedChange = (collapsed: boolean) => {
+      const newState = collapsed ? 'collapsed' : 'expanded';
+      onStateChange?.(newState);
+    };
+
+    // Manejar click en item
+    const handleItemClick = (index: number) => {
+      const commercialItem = items[index];
+      if (commercialItem) {
+        onItemClick?.(commercialItem);
+      }
+    };
+
+    // Manejar hover en item desde NavigationRailTypes
+    const handleItemHoverFromRail = (index: number) => {
+      const commercialItem = items[index];
+      if (commercialItem && isCollapsed) {
+        handleItemHover(commercialItem);
+      }
+    };
+
+    // Manejar hover en item (solo en modo collapsed)
+    const handleItemHover = (item: NavigationRailCommercialMenuItem) => {
+      if (isCollapsed && item.isCollapsible && item.children) {
+        setHoveredItem(item);
+        setPanelType('hover');
+        setShowPanel(true);
+        onItemHover?.(item);
+      }
+    };
+
+    // Manejar click en botón de búsqueda
+
+
+    // Convertir items a formato NavigationRailTypes
+    const railItems = items.map((item) => ({
+      id: item.id,
+      label: item.label,
+      icon: item.icon,
+      active: item.active,
+      disabled: item.disabled,
+      badge: item.badge,
+      badgeCount: item.badgeCount,
+      children: item.children,
+      defaultOpen: item.defaultOpen,
+      onClick: () => {
+        item.onClick?.();
+      },
+    }));
+
+    return (
+      <div
+        ref={ref}
+        className={`relative flex items-start h-full ${className || ''}`}
+        data-testid="navigation-rail-commercial"
+      >
+        {/* NavigationRailTypes - Barra lateral principal */}
+        <NavigationRailTypes
+          collapsed={isCollapsed}
+          items={railItems}
+          showRecentButton={false}
+          showSearchButton={showSearchButton}
+          onCollapsedChange={handleCollapsedChange}
+          onItemClick={handleItemClick}
+          onItemHover={handleItemHoverFromRail}
+          labels={{
+            searchButton: finalLabels.searchPlaceholder,
+            searchPlaceholder: finalLabels.searchPlaceholder,
+            collapseButton: finalLabels.collapseButton,
+          }}
+        />
+
+        {/* NavigationRailPanel - Panel lateral (hover o searcher) */}
+        {showPanel && isCollapsed && (
+          <div
+            className="absolute left-[80px] top-0 z-10 h-full"
+            onMouseLeave={() => setShowPanel(false)}
+          >
+            <NavigationRailPanel
+              height="100%"
+              width={248}
+              showHeading={panelType === 'hover' && hoveredItem !== null}
+              heading={
+                panelType === 'hover' && hoveredItem
+                  ? {
+                    label: hoveredItem.label,
+                    iconName: 'cog-6-tooth',
+                    showDescription: false,
+                    showAction: false,
+                  }
+                  : undefined
+              }
+              showSearch={panelType === 'searcher'}
+              search={{
+                placeholder: finalLabels.searchPlaceholder,
+              }}
+              sections={
+                panelType === 'hover' && hoveredItem?.children
+                  ? [
+                    {
+                      items: hoveredItem.children.map((child) => ({
+                        label: child.label,
+                        icon: child.icon,
+                        onClick: child.onClick,
+                        disabled: child.disabled,
+                      })),
+                    },
+                  ]
+                  : panelType === 'searcher'
+                    ? [
+                      {
+                        heading: finalLabels.recentSection,
+                        items: [
+                          {
+                            label: 'Configuración',
+                            icon: <MagnifyingGlassIcon className="size-4" />,
+                          },
+                        ],
+                      },
+                      {
+                        heading: finalLabels.frequentSection,
+                        items: [
+                          {
+                            label: 'Item',
+                          },
+                        ],
+                      },
+                    ]
+                    : []
+              }
+            />
+          </div>
+        )}
+      </div>
+    );
+  }
+);
+
+NavigationRailCommercial.displayName = 'NavigationRailCommercial';
+
+export default NavigationRailCommercial;

package/src/components/NavigationRailCommercial/NavigationRailCommercial.types.ts

@@ -0,0 +1,162 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Definición de un item de menú para el NavigationRailCommercial
+ */
+export interface NavigationRailCommercialMenuItem {
+  /**
+   * Identificador único del item
+   */
+  id: string;
+
+  /**
+   * Etiqueta/texto del item (visible en modo expanded)
+   */
+  label: string;
+
+  /**
+   * Icono del item (16x16px recomendado)
+   */
+  icon: ReactNode;
+
+  /**
+   * Si el item es colapsable (tiene submenu)
+   * @default false
+   */
+  isCollapsible?: boolean;
+
+  /**
+   * Items hijos (solo si isCollapsible es true)
+   */
+  children?: NavigationRailCommercialMenuItem[];
+
+  /**
+   * Si el item colapsable está abierto por defecto (solo si isCollapsible es true)
+   * @default false
+   */
+  defaultOpen?: boolean;
+
+  /**
+   * Si el item está seleccionado/activo
+   * @default false
+   */
+  active?: boolean;
+
+  /**
+   * Si el item está deshabilitado
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Callback cuando se hace click en el item
+   */
+  onClick?: () => void;
+
+  /**
+   * Badge de notificación
+   * @default false
+   */
+  badge?: boolean;
+
+  /**
+   * Contador de notificaciones (si badge es true)
+   */
+  badgeCount?: number;
+}
+
+/**
+ * Props del componente NavigationRailCommercial
+ *
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6146-34487
+ */
+export interface NavigationRailCommercialProps {
+  /**
+   * Estado del rail:
+   * - `collapsed`: 80px width, solo iconos
+   * - `expanded`: 215px width, con labels
+   * - `hover`: muestra panel lateral con submenu (estado temporal)
+   * - `searcher`: muestra panel lateral con búsqueda (estado temporal)
+   * @default 'collapsed'
+   */
+  state?: 'collapsed' | 'expanded' | 'hover' | 'searcher';
+
+  /**
+   * Items de menú a mostrar en la barra
+   */
+  items?: NavigationRailCommercialMenuItem[];
+
+  /**
+   * Panel lateral que se muestra en estados hover/searcher
+   * Contiene el menú detallado del item seleccionado
+   */
+  panelContent?: {
+    /**
+     * Título del panel (ej: "Administración")
+     */
+    heading?: string;
+
+    /**
+     * Items del panel
+     */
+    items?: NavigationRailCommercialMenuItem[];
+  };
+
+  /**
+   * Callback cuando cambia el estado del rail
+   * @param state - nuevo estado
+   */
+  onStateChange?: (state: NavigationRailCommercialProps['state']) => void;
+
+  /**
+   * Callback cuando se hace click en un item
+   * @param item - item clickeado
+   */
+  onItemClick?: (item: NavigationRailCommercialMenuItem) => void;
+
+  /**
+   * Callback cuando se hace hover en un item (para mostrar panel)
+   * @param item - item con hover
+   */
+  onItemHover?: (item: NavigationRailCommercialMenuItem) => void;
+
+  /**
+   * Labels de internacionalización
+   */
+  labels?: {
+    /**
+     * Placeholder del input de búsqueda
+     * @default 'Buscar módulo'
+     */
+    searchPlaceholder?: string;
+
+    /**
+     * Label del botón colapsar
+     * @default 'Colapsar'
+     */
+    collapseButton?: string;
+
+    /**
+     * Label sección recientes (panel búsqueda)
+     * @default 'Recientes'
+     */
+    recentSection?: string;
+
+    /**
+     * Label sección opciones frecuentes (panel búsqueda)
+     * @default 'Opciones frecuentes'
+     */
+    frequentSection?: string;
+  };
+
+  /**
+   * Clases CSS adicionales
+   */
+  className?: string;
+
+  /**
+   * Si mostrar el botón de búsqueda (en modo collapsed)
+   * @default true
+   */
+  showSearchButton?: boolean;
+}

package/src/components/NavigationRailCommercial/README.md

@@ -0,0 +1,251 @@
+# NavigationRailCommercial
+
+Componente de navegación lateral especializado para aplicaciones comerciales que combina `NavigationRailTypes` y `NavigationRailPanel` para proporcionar una experiencia de navegación completa con múltiples estados.
+
+## Características
+
+- **4 Estados**: collapsed, expanded, hover y searcher
+- **Reutiliza componentes**: NavigationRailTypes y NavigationRailPanel
+- **Dark mode completo**: Soporte total para modo oscuro
+- **Responsive**: Se adapta según el viewport
+- **Focus rings adaptativos**: Anillos de foco según el contexto
+- **TypeScript estricto**: Tipos completos y seguros
+- **Accesibilidad**: ARIA labels y navegación por teclado
+
+## Estados del Componente
+
+### 1. Collapsed (Colapsado)
+- Ancho: 80px
+- Solo muestra iconos
+- Botón de búsqueda en la parte superior
+- Al hacer hover en un item con submenú, muestra panel lateral
+
+### 2. Expanded (Expandido)
+- Ancho: 215px
+- Muestra iconos y labels
+- Input de búsqueda integrado en la parte superior
+- Items colapsables con chevron down
+
+### 3. Hover
+- Estado temporal cuando se hace hover en un item con submenú
+- Muestra panel lateral (248px) con los items hijos
+- El panel desaparece cuando el mouse sale del área
+
+### 4. Searcher (Búsqueda)
+- Estado temporal cuando se hace click en el botón de búsqueda
+- Muestra panel lateral con input de búsqueda
+- Incluye sección de recientes y opciones frecuentes
+
+## Instalación
+
+Este componente está incluido en el paquete `siesa-ui-kit`.
+
+```bash
+npm install siesa-ui-kit
+```
+
+## Uso Básico
+
+```tsx
+import { NavigationRailCommercial } from 'siesa-ui-kit';
+import {
+  Cog6ToothIcon,
+  ShoppingCartIcon,
+  CubeIcon,
+  DocumentIcon,
+} from '@heroicons/react/24/outline';
+
+const items = [
+  {
+    id: 'admin',
+    label: 'Administración',
+    icon: <Cog6ToothIcon className="size-4" />,
+    isCollapsible: true,
+    children: [
+      { id: 'users', label: 'Usuarios' },
+      { id: 'roles', label: 'Roles y Permisos' },
+    ],
+  },
+  {
+    id: 'sales',
+    label: 'Ventas',
+    icon: <ShoppingCartIcon className="size-4" />,
+  },
+];
+
+function App() {
+  return (
+    <NavigationRailCommercial
+      state="collapsed"
+      items={items}
+      onItemClick={(item) => console.log('Clicked:', item.label)}
+    />
+  );
+}
+```
+
+## Con Control de Estado
+
+```tsx
+import { useState } from 'react';
+import { NavigationRailCommercial } from 'siesa-ui-kit';
+
+function App() {
+  const [state, setState] = useState('collapsed');
+
+  return (
+    <NavigationRailCommercial
+      state={state}
+      items={items}
+      onStateChange={setState}
+      onItemClick={(item) => {
+        console.log('Item clicked:', item.label);
+        // Navegar a la ruta correspondiente
+      }}
+      onItemHover={(item) => {
+        console.log('Item hovered:', item.label);
+        // Precargar datos del submenú si es necesario
+      }}
+    />
+  );
+}
+```
+
+## Props
+
+### NavigationRailCommercialProps
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `state` | `'collapsed' \| 'expanded' \| 'hover' \| 'searcher'` | `'collapsed'` | Estado visual del componente |
+| `items` | `NavigationRailCommercialMenuItem[]` | `[]` | Items de menú a mostrar |
+| `panelContent` | `object` | - | Contenido del panel lateral (hover/searcher) |
+| `onStateChange` | `(state) => void` | - | Callback cuando cambia el estado |
+| `onItemClick` | `(item) => void` | - | Callback cuando se hace click en un item |
+| `onItemHover` | `(item) => void` | - | Callback cuando se hace hover en un item |
+| `labels` | `object` | - | Labels de internacionalización |
+| `className` | `string` | - | Clases CSS adicionales |
+| `showSearchButton` | `boolean` | `true` | Si mostrar el botón de búsqueda |
+
+### NavigationRailCommercialMenuItem
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `id` | `string` | - | Identificador único del item |
+| `label` | `string` | - | Etiqueta/texto del item |
+| `icon` | `ReactNode` | - | Icono del item (16x16px) |
+| `isCollapsible` | `boolean` | `false` | Si el item tiene submenú |
+| `children` | `NavigationRailCommercialMenuItem[]` | - | Items hijos (si isCollapsible es true) |
+| `active` | `boolean` | `false` | Si el item está seleccionado |
+| `disabled` | `boolean` | `false` | Si el item está deshabilitado |
+| `onClick` | `() => void` | - | Callback cuando se hace click |
+| `badge` | `boolean` | `false` | Si mostrar badge de notificación |
+| `badgeCount` | `number` | - | Contador de notificaciones |
+
+## Ejemplos
+
+### Con Items Activos
+
+```tsx
+<NavigationRailCommercial
+  state="collapsed"
+  items={items.map((item, index) => ({
+    ...item,
+    active: index === 0, // Primer item activo
+  }))}
+/>
+```
+
+### Con Badges de Notificación
+
+```tsx
+<NavigationRailCommercial
+  state="collapsed"
+  items={items.map((item, index) => ({
+    ...item,
+    badge: index === 1,
+    badgeCount: 5,
+  }))}
+/>
+```
+
+### Con Internacionalización
+
+```tsx
+<NavigationRailCommercial
+  state="collapsed"
+  items={items}
+  labels={{
+    searchPlaceholder: 'Search module',
+    collapseButton: 'Collapse',
+    recentSection: 'Recent',
+    frequentSection: 'Frequent options',
+  }}
+/>
+```
+
+## Componentes Reutilizados
+
+- **NavigationRailTypes**: Barra lateral principal con estados collapsed/expanded
+- **NavigationRailPanel**: Panel lateral para hover y búsqueda
+- **Button**: Botón de búsqueda
+- **Input**: Input de búsqueda en el panel
+- **Divider**: Separadores entre secciones
+- **DropdownItemCollapsible**: Items colapsables en modo expanded
+
+## Tokens de Color
+
+### Light Mode
+- Background rail: `bg-bg-primary` (#ffffff)
+- Background panel: `bg-bg-primary` (#ffffff)
+- Borders: `border-border-primary` (#e4e4e7)
+- Text: `text-content-primary` (#18181b)
+- Icons: `text-content-secondary` (#a1a1aa)
+
+### Dark Mode
+- Background rail: `dark:bg-dark-bg-primary` (#18181b)
+- Background panel: `dark:bg-dark-bg-primary` (#18181b)
+- Borders: `dark:border-dark-border-primary` (#71717a)
+- Text: `dark:text-dark-content-primary` (#f4f4f5)
+- Icons: `dark:text-content-secondary` (#a1a1aa)
+
+## Mejores Prácticas
+
+1. **Usa items colapsables para navegación jerárquica**
+   ```tsx
+   {
+     id: 'admin',
+     label: 'Administración',
+     isCollapsible: true,
+     children: [/* subitems */],
+   }
+   ```
+
+2. **Gestiona el estado externamente para control total**
+   ```tsx
+   const [state, setState] = useState('collapsed');
+   <NavigationRailCommercial state={state} onStateChange={setState} />
+   ```
+
+3. **Usa badges para notificaciones importantes**
+   ```tsx
+   { id: 'orders', label: 'Pedidos', badge: true, badgeCount: 12 }
+   ```
+
+4. **Proporciona callbacks para tracking de eventos**
+   ```tsx
+   onItemClick={(item) => analytics.track('nav_item_clicked', { item: item.id })}
+   ```
+
+## Accesibilidad
+
+- Navegación por teclado con Tab y Enter
+- ARIA labels en todos los elementos interactivos
+- Focus rings visibles y adaptativos
+- Soporte completo para screen readers
+
+## Referencias
+
+- **Figma Design**: [Navigation Rail Commercial](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6146-34487)
+- **Storybook**: Ver todas las variantes en Storybook
+- **Documentación**: `docs/colors.md`, `docs/typography.md`, `docs/spacing.md`