siesa-ui-kit 1.0.0 → 1.0.2

package/src/components/NavigationRailPanel/NavigationRailPanel.tsx

@@ -0,0 +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>
+  );
+};

package/src/components/NavigationRailPanel/NavigationRailPanel.types.ts

@@ -0,0 +1,178 @@
+import type { ReactNode } from 'react';
+import type { DropdownItemCollapsibleChildProps } from '../DropdownItemCollapsible/DropdownItemCollapsible.types';
+
+/**
+ * Props de la sección de items dentro del NavigationRailPanel
+ */
+export interface NavigationRailPanelSectionProps {
+  /**
+   * Encabezado de la sección (label del heading)
+   * Ejemplo: "Categorías", "Departamentos", "Opciones"
+   */
+  heading?: string;
+
+  /**
+   * Items que se muestran en la sección
+   * Pueden ser items simples o items colapsables
+   */
+  items: NavigationRailPanelItemProps[];
+
+  /**
+   * Si mostrar divisor después de esta sección
+   * @default true
+   */
+  showDivider?: boolean;
+
+  /**
+   * Clases CSS adicionales
+   */
+  className?: string;
+}
+
+/**
+ * Props de un item individual dentro del NavigationRailPanel
+ */
+export interface NavigationRailPanelItemProps {
+  /**
+   * Texto o contenido principal del item
+   * Ejemplo: "Users", "Settings", "Help"
+   */
+  label: string;
+
+  /**
+   * Icono a mostrar antes del texto (izquierda)
+   * Recomendado: 16x16px
+   */
+  icon?: ReactNode;
+
+  /**
+   * Si el item es colapsable (muestra items anidados)
+   * @default false
+   */
+  isCollapsible?: boolean;
+
+  /**
+   * Items anidados que se muestran cuando el item está expandido
+   * Se usa solo cuando isCollapsible es true
+   */
+  children?: DropdownItemCollapsibleChildProps[];
+
+  /**
+   * Si el item está expandido inicialmente (para items colapsables)
+   * @default false
+   */
+  defaultOpen?: boolean;
+
+  /**
+   * Si el item está deshabilitado
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Callback cuando se hace click en el item
+   */
+  onClick?: (e: React.MouseEvent<HTMLButtonElement | HTMLDivElement>) => void;
+
+  /**
+   * Callback cuando el item colapsable se expande/contrae
+   * @param open - nuevo estado de expansión
+   */
+  onOpenChange?: (open: boolean) => void;
+
+  /**
+   * Clases CSS adicionales
+   */
+  className?: string;
+}
+
+/**
+ * Props del componente NavigationRailPanel
+ *
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6134-34415
+ */
+export interface NavigationRailPanelProps {
+  /**
+   * Altura del panel en píxeles
+   * Se usa para el contenedor principal
+   * Ejemplo: 600, 800, 900
+   * @default 900
+   */
+  height?: number | string;
+
+  /**
+   * Ancho del panel en píxeles
+   * Ancho estándar: 248px (con padding incluido)
+   * @default 248
+   */
+  width?: number | string;
+
+  /**
+   * Encabezado del panel con icono, label, descripción y acción
+   * Ejemplo: { label: "Settings", description: "Configure your preferences" }
+   */
+  heading?: {
+    label: string;
+    description?: string;
+    showDescription?: boolean;
+    iconName?: string;
+    actionLabel?: string;
+    showAction?: boolean;
+    onActionClick?: () => void;
+  };
+
+  /**
+   * Si mostrar el encabezado (DropdownItemHeading)
+   * @default true
+   */
+  showHeading?: boolean;
+
+  /**
+   * Configuración del input de búsqueda
+   */
+  search?: {
+    /**
+     * Placeholder del input
+     * @default "Buscar módulo"
+     */
+    placeholder?: string;
+
+    /**
+     * Valor actual del input
+     */
+    value?: string;
+
+    /**
+     * Callback cuando cambia el valor del input
+     */
+    onChange?: (value: string) => void;
+  };
+
+  /**
+   * Si mostrar el input de búsqueda
+   * @default true
+   */
+  showSearch?: boolean;
+
+  /**
+   * Secciones de items dentro del panel
+   * Cada sección puede tener un encabezado y múltiples items
+   */
+  sections?: NavigationRailPanelSectionProps[];
+
+  /**
+   * Alternativa a sections: items simples sin agrupar
+   * Se usan cuando no necesitas secciones
+   */
+  items?: NavigationRailPanelItemProps[];
+
+  /**
+   * Clases CSS adicionales para el contenedor principal
+   */
+  className?: string;
+
+  /**
+   * Clases CSS adicionales para el panel interno
+   */
+  panelClassName?: string;
+}