siesa-ui-kit 1.0.2 → 1.0.4

package/src/components/NavigationRailPanel/NavigationRailPanel.tsx

@@ -1,332 +1,332 @@
-import React, { useState } from 'react';
-import type { NavigationRailPanelProps } from './NavigationRailPanel.types';
-import { DropdownItemHeading } from '../DropdownItemHeading';
-import { DropdownItemCollapsible } from '../DropdownItemCollapsible';
-import { Input } from '../Input';
-import { Divider } from '../Divider/Divider';
-
-/**
- * Componente NavigationRailPanel del sistema de diseño Siesa
- *
- * 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.
- *
- * **Estructura principal:**
- * 1. Encabezado (DropdownItemHeading) - Opcional
- * 2. Input de búsqueda - Opcional
- * 3. Divisor - Siempre presente después de búsqueda/encabezado
- * 4. Body con secciones de items:
- *    - Heading de sección (Paragraph/Tiny, content-tertiary)
- *    - Items colapsables (DropdownItemCollapsible) o simples
- *    - Divisor entre secciones
- *
- * **Dimensiones según Figma:**
- * - Altura: Variable (por defecto 900px)
- * - Ancho del panel: 248px (con padding 12px)
- * - Ancho de contenido: 224px
- * - Padding del panel: 12px
- * - Padding del body: 12px
- * - Border: 1px left (border-primary)
- * - Border radius: 0px (es un panel recto)
- *
- * **Tipografía:**
- * - Heading (DropdownItemHeading): Label/Small (14px Bold)
- * - Section heading: Paragraph/Tiny (12px Regular) - content-tertiary
- * - Items: Paragraph/Small (14px Regular)
- *
- * **Colores (Light Mode):**
- * - Background: #ffffff (white)
- * - Border: #e4e4e7 (border-primary)
- * - Heading text: #18181b (content-primary)
- * - Section heading: #71717a (content-tertiary)
- * - Item text: #18181b (content-primary)
- * - Icon color: #a1a1aa (content-secondary)
- *
- * **Colores (Dark Mode):**
- * - Background: #18181b (dark bg)
- * - Border: #3f3f46 (border-primary/dark)
- * - Heading text: #fafafa (content-primary/dark)
- * - Section heading: #a1a1aa (content-tertiary/dark)
- * - Item text: #fafafa (content-primary/dark)
- * - Icon color: #a1a1aa (content-secondary/dark)
- *
- * **Estados:**
- * - Default: Sin interacción
- * - Hover: Items con hover overlay sutil
- * - Focus: Focus ring adaptativo
- * - Disabled: Opacidad 50%
- * - Active (items colapsables): Expanded state
- *
- * **Espaciado interno:**
- * - Gap entre section heading e items: 0.5 (2px)
- * - Gap entre items: 0.5 (2px)
- * - Gap entre elemento y contenido: 3 (12px)
- * - Padding vertical section heading: pt-3 pb-1 (12px top, 4px bottom)
- * - Padding items: py-2 px-4 (8px vertical, 16px horizontal)
- *
- * **Scroll:**
- * - El body es scrolleable verticalmente (overflow-y-auto)
- * - El encabezado y búsqueda se mantienen fijos en el tope
- *
- * @see docs/colors.md - Sistema de colores
- * @see docs/typography.md - Sistema tipográfico
- * @see docs/spacing.md - Sistema de espaciado
- * @see docs/shadows.md - Sistema de sombras
- * @see ../DropdownItemHeading - Componente reutilizado para encabezado
- * @see ../DropdownItemCollapsible - Componente reutilizado para items colapsables
- * @see ../Input - Componente reutilizado para búsqueda
- * @see ../Divider - Componente reutilizado para separadores
- * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6134-34415 - Diseño Figma
- *
- * @example
- * ```tsx
- * // Ejemplo simple con secciones
- * <NavigationRailPanel
- *   height={900}
- *   showHeading={true}
- *   heading={{
- *     label: 'Settings',
- *     description: 'Configure your preferences',
- *     iconName: 'cog-6-tooth',
- *     actionLabel: 'Clear',
- *     showAction: true,
- *   }}
- *   showSearch={true}
- *   search={{
- *     placeholder: 'Buscar módulo',
- *   }}
- *   sections={[
- *     {
- *       heading: 'Section 1',
- *       items: [
- *         { label: 'Item 1', isCollapsible: true, children: [...] },
- *         { label: 'Item 2', isCollapsible: false },
- *       ],
- *     },
- *     {
- *       heading: 'Section 2',
- *       items: [
- *         { label: 'Item 3' },
- *       ],
- *     },
- *   ]}
- * />
- *
- * // Ejemplo con items simples sin secciones
- * <NavigationRailPanel
- *   showHeading={false}
- *   showSearch={true}
- *   items={[
- *     { label: 'Dashboard', icon: <DashboardIcon /> },
- *     { label: 'Users', icon: <UserIcon /> },
- *     { label: 'Settings', icon: <SettingsIcon /> },
- *   ]}
- * />
- * ```
- */
-export const NavigationRailPanel: React.FC<NavigationRailPanelProps> = ({
-  height = 900,
-  width = 248,
-  showHeading = true,
-  heading,
-  showSearch = true,
-  search,
-  sections,
-  items,
-  className = '',
-  panelClassName = '',
-}) => {
-  const [searchValue, setSearchValue] = useState(search?.value || '');
-
-  const handleSearchChange = (value: string) => {
-    setSearchValue(value);
-    search?.onChange?.(value);
-  };
-
-  // Construir clase de altura dinámicamente
-  const containerStyle = {
-    height: typeof height === 'number' ? `${height}px` : height,
-  };
-
-  const panelStyle = {
-    width: typeof width === 'number' ? `${width}px` : width,
-  };
-
-  return (
-    <div
-      className={`flex items-start relative ${className}`}
-      style={containerStyle}
-      data-testid="navigation-rail-panel-container"
-    >
-      <div
-        className={`bg-bg-primary dark:bg-dark-bg-primary border-border-primary dark:border-dark-border-primary border-b-0 border-l border-r-0 border-solid border-t-0 flex flex-col h-full items-start overflow-clip relative shrink-0 ${panelClassName}`}
-        style={panelStyle}
-        data-testid="navigation-rail-panel"
-      >
-        {/* Encabezado (DropdownItemHeading) */}
-        {showHeading && heading && (
-          <div className="flex flex-col items-start p-3 relative shrink-0 w-full">
-            <DropdownItemHeading
-              label={heading.label}
-              description={heading.description}
-              showDescription={heading.showDescription !== false}
-              iconName={heading.iconName}
-              showIcon={true}
-              actionLabel={heading.actionLabel}
-              showAction={heading.showAction}
-              onActionClick={heading.onActionClick}
-              className="w-full"
-            />
-          </div>
-        )}
-
-        {/* Input de búsqueda */}
-        {showSearch && (
-          <div
-            className="flex flex-col items-start p-3 relative shrink-0 w-full"
-            data-testid="navigation-rail-search"
-          >
-            <Input
-              placeholder={search?.placeholder || 'Buscar módulo'}
-              value={searchValue}
-              onChange={(e) => handleSearchChange(e.target.value)}
-              className="w-full"
-            />
-          </div>
-        )}
-
-        {/* Divisor */}
-        <Divider className="w-full" />
-
-        {/* Body con items */}
-        <div
-          className="flex flex-1 flex-col gap-0.5 items-start min-h-px min-w-px p-3 relative shrink-0 overflow-y-auto w-full"
-          data-testid="navigation-rail-body"
-        >
-          {/* Renderizar secciones */}
-          {sections && sections.length > 0
-            ? sections.map((section, sectionIndex) => (
-                <div key={`section-${sectionIndex}`} className="w-full">
-                  {/* Section Heading */}
-                  {section.heading && (
-                    <div
-                      className="flex flex-col gap-0 items-start pb-1 pt-3 px-0 relative shrink-0 w-full"
-                      data-testid={`section-heading-${sectionIndex}`}
-                    >
-                      <p className="font-['Inter:Regular',sans-serif] font-normal text-xs leading-4 not-italic relative shrink-0 text-content-tertiary dark:text-content-tertiary w-full whitespace-pre-wrap">
-                        {section.heading}
-                      </p>
-                    </div>
-                  )}
-
-                  {/* Section Items */}
-                  <div
-                    className="flex flex-col gap-0.5 items-start relative shrink-0 w-full"
-                    data-testid={`section-items-${sectionIndex}`}
-                  >
-                    {section.items.map((item, itemIndex) => (
-                      <NavigationRailPanelItem
-                        key={`item-${sectionIndex}-${itemIndex}`}
-                        item={item}
-                      />
-                    ))}
-                  </div>
-
-                  {/* Section Divider */}
-                  {section.showDivider !== false && sectionIndex < sections.length - 1 && (
-                    <Divider className="mt-3 w-full" />
-                  )}
-                </div>
-              ))
-            : null}
-
-          {/* Renderizar items simples (sin secciones) */}
-          {items && items.length > 0 && !sections
-            ? items.map((item, itemIndex) => (
-                <NavigationRailPanelItem
-                  key={`item-${itemIndex}`}
-                  item={item}
-                />
-              ))
-            : null}
-        </div>
-      </div>
-    </div>
-  );
-};
-
-/**
- * Componente interno para renderizar un item del NavigationRailPanel
- * Puede ser un item simple o colapsable
- */
-interface NavigationRailPanelItemComponentProps {
-  item: NonNullable<NavigationRailPanelProps['items']>[0];
-}
-
-const NavigationRailPanelItem: React.FC<NavigationRailPanelItemComponentProps> = ({ item }) => {
-  if (item.isCollapsible) {
-    return (
-      <DropdownItemCollapsible
-        label={item.label}
-        icon={item.icon}
-        children={item.children}
-        defaultOpen={item.defaultOpen}
-        disabled={item.disabled}
-        onClick={item.onClick}
-        onOpenChange={item.onOpenChange}
-        className={item.className}
-        showDivider={false}
-        showHeading={false}
-      />
-    );
-  }
-
-  return (
-    <button
-      onClick={item.onClick}
-      disabled={item.disabled}
-      className={[
-        // Base
-        'flex items-center gap-3 px-4 py-2 w-full',
-        'rounded-lg cursor-pointer',
-        'transition-colors duration-150',
-
-        // Colores y estados (Light Mode)
-        !item.disabled && 'text-content-primary',
-        !item.disabled && 'hover:bg-primary-custom-100',
-
-        // Dark Mode
-        !item.disabled && 'dark:text-content-primary',
-        !item.disabled && 'dark:hover:bg-dark-bg-custom',
-
-        // Focus ring
-        !item.disabled && 'focus:outline-none',
-        !item.disabled && 'focus:ring-2',
-        !item.disabled && 'focus:ring-offset-2',
-        !item.disabled && 'focus:ring-primary-custom-400',
-        !item.disabled && 'focus:ring-offset-bg-primary',
-        !item.disabled && 'dark:focus:ring-offset-dark-bg-primary',
-
-        // Disabled
-        item.disabled && 'opacity-50',
-        item.disabled && 'cursor-not-allowed',
-
-        item.className,
-      ]
-        .filter(Boolean)
-        .join(' ')}
-      data-testid={`navigation-rail-item-${item.label}`}
-      aria-disabled={item.disabled}
-    >
-      {item.icon && (
-        <div className="flex items-center justify-center w-4 h-4 shrink-0 text-content-secondary dark:text-content-secondary">
-          {item.icon}
-        </div>
-      )}
-      <p className="font-['Inter:Regular',sans-serif] text-sm font-normal leading-5 not-italic relative shrink-0 text-left">
-        {item.label}
-      </p>
-    </button>
-  );
-};
+import React, { useState } from 'react';
+import type { NavigationRailPanelProps } from './NavigationRailPanel.types';
+import { DropdownItemHeading } from '../DropdownItemHeading';
+import { DropdownItemCollapsible } from '../DropdownItemCollapsible';
+import { Input } from '../Input';
+import { Divider } from '../Divider/Divider';
+
+/**
+ * Componente NavigationRailPanel del sistema de diseño Siesa
+ *
+ * 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.
+ *
+ * **Estructura principal:**
+ * 1. Encabezado (DropdownItemHeading) - Opcional
+ * 2. Input de búsqueda - Opcional
+ * 3. Divisor - Siempre presente después de búsqueda/encabezado
+ * 4. Body con secciones de items:
+ *    - Heading de sección (Paragraph/Tiny, content-tertiary)
+ *    - Items colapsables (DropdownItemCollapsible) o simples
+ *    - Divisor entre secciones
+ *
+ * **Dimensiones según Figma:**
+ * - Altura: Variable (por defecto 900px)
+ * - Ancho del panel: 248px (con padding 12px)
+ * - Ancho de contenido: 224px
+ * - Padding del panel: 12px
+ * - Padding del body: 12px
+ * - Border: 1px left (border-primary)
+ * - Border radius: 0px (es un panel recto)
+ *
+ * **Tipografía:**
+ * - Heading (DropdownItemHeading): Label/Small (14px Bold)
+ * - Section heading: Paragraph/Tiny (12px Regular) - content-tertiary
+ * - Items: Paragraph/Small (14px Regular)
+ *
+ * **Colores (Light Mode):**
+ * - Background: #ffffff (white)
+ * - Border: #e4e4e7 (border-primary)
+ * - Heading text: #18181b (content-primary)
+ * - Section heading: #71717a (content-tertiary)
+ * - Item text: #18181b (content-primary)
+ * - Icon color: #a1a1aa (content-secondary)
+ *
+ * **Colores (Dark Mode):**
+ * - Background: #18181b (dark bg)
+ * - Border: #3f3f46 (border-primary/dark)
+ * - Heading text: #fafafa (content-primary/dark)
+ * - Section heading: #a1a1aa (content-tertiary/dark)
+ * - Item text: #fafafa (content-primary/dark)
+ * - Icon color: #a1a1aa (content-secondary/dark)
+ *
+ * **Estados:**
+ * - Default: Sin interacción
+ * - Hover: Items con hover overlay sutil
+ * - Focus: Focus ring adaptativo
+ * - Disabled: Opacidad 50%
+ * - Active (items colapsables): Expanded state
+ *
+ * **Espaciado interno:**
+ * - Gap entre section heading e items: 0.5 (2px)
+ * - Gap entre items: 0.5 (2px)
+ * - Gap entre elemento y contenido: 3 (12px)
+ * - Padding vertical section heading: pt-3 pb-1 (12px top, 4px bottom)
+ * - Padding items: py-2 px-4 (8px vertical, 16px horizontal)
+ *
+ * **Scroll:**
+ * - El body es scrolleable verticalmente (overflow-y-auto)
+ * - El encabezado y búsqueda se mantienen fijos en el tope
+ *
+ * @see docs/colors.md - Sistema de colores
+ * @see docs/typography.md - Sistema tipográfico
+ * @see docs/spacing.md - Sistema de espaciado
+ * @see docs/shadows.md - Sistema de sombras
+ * @see ../DropdownItemHeading - Componente reutilizado para encabezado
+ * @see ../DropdownItemCollapsible - Componente reutilizado para items colapsables
+ * @see ../Input - Componente reutilizado para búsqueda
+ * @see ../Divider - Componente reutilizado para separadores
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6134-34415 - Diseño Figma
+ *
+ * @example
+ * ```tsx
+ * // Ejemplo simple con secciones
+ * <NavigationRailPanel
+ *   height={900}
+ *   showHeading={true}
+ *   heading={{
+ *     label: 'Settings',
+ *     description: 'Configure your preferences',
+ *     iconName: 'cog-6-tooth',
+ *     actionLabel: 'Clear',
+ *     showAction: true,
+ *   }}
+ *   showSearch={true}
+ *   search={{
+ *     placeholder: 'Buscar módulo',
+ *   }}
+ *   sections={[
+ *     {
+ *       heading: 'Section 1',
+ *       items: [
+ *         { label: 'Item 1', isCollapsible: true, children: [...] },
+ *         { label: 'Item 2', isCollapsible: false },
+ *       ],
+ *     },
+ *     {
+ *       heading: 'Section 2',
+ *       items: [
+ *         { label: 'Item 3' },
+ *       ],
+ *     },
+ *   ]}
+ * />
+ *
+ * // Ejemplo con items simples sin secciones
+ * <NavigationRailPanel
+ *   showHeading={false}
+ *   showSearch={true}
+ *   items={[
+ *     { label: 'Dashboard', icon: <DashboardIcon /> },
+ *     { label: 'Users', icon: <UserIcon /> },
+ *     { label: 'Settings', icon: <SettingsIcon /> },
+ *   ]}
+ * />
+ * ```
+ */
+export const NavigationRailPanel: React.FC<NavigationRailPanelProps> = ({
+  height = 900,
+  width = 248,
+  showHeading = true,
+  heading,
+  showSearch = true,
+  search,
+  sections,
+  items,
+  className = '',
+  panelClassName = '',
+}) => {
+  const [searchValue, setSearchValue] = useState(search?.value || '');
+
+  const handleSearchChange = (value: string) => {
+    setSearchValue(value);
+    search?.onChange?.(value);
+  };
+
+  // Construir clase de altura dinámicamente
+  const containerStyle = {
+    height: typeof height === 'number' ? `${height}px` : height,
+  };
+
+  const panelStyle = {
+    width: typeof width === 'number' ? `${width}px` : width,
+  };
+
+  return (
+    <div
+      className={`flex items-start relative ${className}`}
+      style={containerStyle}
+      data-testid="navigation-rail-panel-container"
+    >
+      <div
+        className={`bg-bg-primary dark:bg-dark-bg-primary border-border-primary dark:border-dark-border-primary border-b-0 border-l border-r border-solid border-t-0 flex flex-col h-full items-start overflow-clip relative shrink-0 ${panelClassName}`}
+        style={panelStyle}
+        data-testid="navigation-rail-panel"
+      >
+        {/* Encabezado (DropdownItemHeading) */}
+        {showHeading && heading && (
+          <div className="flex flex-col items-start p-3 relative shrink-0 w-full">
+            <DropdownItemHeading
+              label={heading.label}
+              description={heading.description}
+              showDescription={heading.showDescription !== false}
+              iconName={heading.iconName}
+              showIcon={true}
+              actionLabel={heading.actionLabel}
+              showAction={heading.showAction}
+              onActionClick={heading.onActionClick}
+              className="w-full"
+            />
+          </div>
+        )}
+
+        {/* Input de búsqueda */}
+        {showSearch && (
+          <div
+            className="flex flex-col items-start p-3 relative shrink-0 w-full"
+            data-testid="navigation-rail-search"
+          >
+            <Input
+              placeholder={search?.placeholder || 'Buscar módulo'}
+              value={searchValue}
+              onChange={(e) => handleSearchChange(e.target.value)}
+              className="w-full"
+            />
+          </div>
+        )}
+
+        {/* Divisor */}
+        <Divider className="w-full" />
+
+        {/* Body con items */}
+        <div
+          className="flex flex-1 flex-col gap-0.5 items-start min-h-px min-w-px p-3 relative shrink-0 overflow-y-auto w-full"
+          data-testid="navigation-rail-body"
+        >
+          {/* Renderizar secciones */}
+          {sections && sections.length > 0
+            ? sections.map((section, sectionIndex) => (
+                <div key={`section-${sectionIndex}`} className="w-full">
+                  {/* Section Heading */}
+                  {section.heading && (
+                    <div
+                      className="flex flex-col gap-0 items-start pb-1 pt-3 px-0 relative shrink-0 w-full"
+                      data-testid={`section-heading-${sectionIndex}`}
+                    >
+                      <p className="font-['Inter:Regular',sans-serif] font-normal text-xs leading-4 not-italic relative shrink-0 text-content-tertiary dark:text-content-tertiary w-full whitespace-pre-wrap">
+                        {section.heading}
+                      </p>
+                    </div>
+                  )}
+
+                  {/* Section Items */}
+                  <div
+                    className="flex flex-col gap-0.5 items-start relative shrink-0 w-full"
+                    data-testid={`section-items-${sectionIndex}`}
+                  >
+                    {section.items.map((item, itemIndex) => (
+                      <NavigationRailPanelItem
+                        key={`item-${sectionIndex}-${itemIndex}`}
+                        item={item}
+                      />
+                    ))}
+                  </div>
+
+                  {/* Section Divider */}
+                  {section.showDivider !== false && sectionIndex < sections.length - 1 && (
+                    <Divider className="mt-3 w-full" />
+                  )}
+                </div>
+              ))
+            : null}
+
+          {/* Renderizar items simples (sin secciones) */}
+          {items && items.length > 0 && !sections
+            ? items.map((item, itemIndex) => (
+                <NavigationRailPanelItem
+                  key={`item-${itemIndex}`}
+                  item={item}
+                />
+              ))
+            : null}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+/**
+ * Componente interno para renderizar un item del NavigationRailPanel
+ * Puede ser un item simple o colapsable
+ */
+interface NavigationRailPanelItemComponentProps {
+  item: NonNullable<NavigationRailPanelProps['items']>[0];
+}
+
+const NavigationRailPanelItem: React.FC<NavigationRailPanelItemComponentProps> = ({ item }) => {
+  if (item.isCollapsible) {
+    return (
+      <DropdownItemCollapsible
+        label={item.label}
+        icon={item.icon}
+        children={item.children}
+        defaultOpen={item.defaultOpen}
+        disabled={item.disabled}
+        onClick={item.onClick}
+        onOpenChange={item.onOpenChange}
+        className={item.className}
+        showDivider={false}
+        showHeading={false}
+      />
+    );
+  }
+
+  return (
+    <button
+      onClick={item.onClick}
+      disabled={item.disabled}
+      className={[
+        // Base
+        'flex items-center gap-3 px-4 py-2 w-full',
+        'rounded-lg cursor-pointer',
+        'transition-colors duration-150',
+
+        // Colores y estados (Light Mode)
+        !item.disabled && 'text-content-primary',
+        !item.disabled && 'hover:bg-primary-custom-100',
+
+        // Dark Mode
+        !item.disabled && 'dark:text-content-primary',
+        !item.disabled && 'dark:hover:bg-dark-bg-custom',
+
+        // Focus ring
+        !item.disabled && 'focus:outline-none',
+        !item.disabled && 'focus:ring-2',
+        !item.disabled && 'focus:ring-offset-2',
+        !item.disabled && 'focus:ring-primary-custom-400',
+        !item.disabled && 'focus:ring-offset-bg-primary',
+        !item.disabled && 'dark:focus:ring-offset-dark-bg-primary',
+
+        // Disabled
+        item.disabled && 'opacity-50',
+        item.disabled && 'cursor-not-allowed',
+
+        item.className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      data-testid={`navigation-rail-item-${item.label}`}
+      aria-disabled={item.disabled}
+    >
+      {item.icon && (
+        <div className="flex items-center justify-center w-4 h-4 shrink-0 text-content-secondary dark:text-content-secondary">
+          {item.icon}
+        </div>
+      )}
+      <p className="font-['Inter:Regular',sans-serif] text-sm font-normal leading-5 not-italic relative shrink-0 text-left">
+        {item.label}
+      </p>
+    </button>
+  );
+};