siesa-ui-kit 1.0.3 → 1.0.4

package/src/components/NavigationRailItem/NavigationRailItem.tsx

@@ -0,0 +1,314 @@
+import React from 'react';
+import type { NavigationRailItemProps } from './NavigationRailItem.types';
+
+/**
+ * NavigationRailItem - Componente independiente para items de NavigationRail
+ *
+ * Item individual de navegación vertical (rail) para aplicaciones. Proporciona
+ * un punto de acceso a destinos mediante un icono, label opcional y badges.
+ *
+ * **Características principales:**
+ * - Ancho fijo de 56px según Figma
+ * - Estados completos: normal, hover, selected, focus, disabled
+ * - Badges de notificación con contador opcional
+ * - Tipografía Label XXSmall (10px Bold) según sistema de diseño
+ * - Dark mode completo con estrategia 'class'
+ * - Focus rings adaptativos para accesibilidad
+ * - Soporte para iconos 16x16px
+ *
+ * **Especificaciones de Figma (node 4294-22931):**
+ * - Ancho: 56px (w-14)
+ * - Icon container: 32px altura, px-4 py-1, rounded-full
+ * - Label: 10px Bold, leading 12px (Label XXSmall)
+ * - Gap: 4px (gap-1)
+ * - Badge: 13x13px, posición absolute
+ *
+ * **Estados visuales (según Figma):**
+ * - **Enabled**: Icon transparent, label text-content-primary
+ * - **Hover**: Icon container bg-primary-custom-100 (#dbeefe), icon text-primary-custom-600
+ * - **Selected**: Icon container bg-primary-custom-100 con overlay, icon text-primary-custom-600
+ * - **Focus**: Focus ring 2px (#60b6fa) con offset 2px (#dbeefe), sombras combinadas
+ * - **Disabled**: Opacity 55%, no interactivo
+ *
+ * **Dark Mode:**
+ * - Background: dark-bg-primary
+ * - Hover icon container: dark-bg-primary/20
+ * - Selected icon container: dark-primary-custom-600/30
+ * - Icon colors: dark-content-primary, dark-white on selected
+ * - Focus ring: dark-border-custom
+ *
+ * **Mejores prácticas implementadas:**
+ * - Orden de modificadores: {responsive}:{dark}:{state}:{utility}
+ * - Tokens de color consistentes con documentación
+ * - Accesibilidad ARIA completa
+ * - Focus visible para keyboard navigation
+ * - Badge positioning absoluto para no afectar layout
+ *
+ * @see docs/colors.md - Sistema de colores (primary-custom, dark-*, content-*)
+ * @see docs/typography.md - Tipografía (Label XXSmall)
+ * @see docs/spacing.md - Sistema de espaciado
+ * @see docs/shadows.md - Sistema de sombras y focus rings
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4294-22931
+ *
+ * @example
+ * ```tsx
+ * // Item básico
+ * <NavigationRailItem
+ *   id="home"
+ *   icon={<HomeIcon />}
+ *   label="Inicio"
+ *   selected={true}
+ *   onClick={() => navigate('/')}
+ * />
+ *
+ * // Con badge de notificación
+ * <NavigationRailItem
+ *   id="notifications"
+ *   icon={<BellIcon />}
+ *   label="Notificaciones"
+ *   badgeCount={5}
+ *   onClick={() => navigate('/notifications')}
+ * />
+ *
+ * // Item deshabilitado
+ * <NavigationRailItem
+ *   id="premium"
+ *   icon={<StarIcon />}
+ *   label="Premium"
+ *   disabled={true}
+ * />
+ *
+ * // Solo icono (sin label)
+ * <NavigationRailItem
+ *   id="home"
+ *   icon={<HomeIcon />}
+ *   label="Inicio"
+ *   showLabelText={false}
+ * />
+ * ```
+ */
+export const NavigationRailItem: React.FC<NavigationRailItemProps> = ({
+  icon,
+  label,
+  selected = false,
+  disabled = false,
+  badge = false,
+  badgeCount,
+  onClick,
+  onMouseEnter,
+  ariaLabel,
+  id,
+  showLabelText = true,
+  showIcon = true,
+  className = '',
+}) => {
+  // ===== CLASES DEL ICON CONTAINER =====
+  // Según Figma node 4294-22931, el icon container tiene comportamiento diferente
+  // según el estado:
+  // - Enabled: bg-transparent, hover:bg-primary-custom-100
+  // - Hover: bg-primary-custom-100
+  // - Selected: bg-primary-custom-100 con overlay (rgba(0,0,0,0.024))
+  // - Focus: bg-primary-custom-100 con focus ring y sombras
+  // - Disabled: opacidad 55%
+  const iconContainerClasses = [
+    // Base layout
+    'flex',
+    'flex-col',
+    'items-center',
+    'justify-center',
+    'px-4', // 16px horizontal según Figma
+    'py-1', // 4px vertical según Figma
+    'rounded-full',
+    'overflow-hidden',
+    'shrink-0',
+
+    // Estados - Background
+    selected
+      ? // Selected: bg-primary-custom-100 con overlay
+        'bg-primary-custom-100 dark:bg-primary-custom-600/30'
+      : // Default/Hover: transparent → hover:bg-primary-custom-100
+        'bg-transparent hover:bg-primary-custom-100 dark:hover:bg-primary-custom-600/20',
+
+    // Transiciones
+    'transition-colors',
+    'duration-150',
+  ].join(' ');
+
+  // ===== CLASES DEL ICONO =====
+  // Tamaño fijo 16x16px según Figma
+  // Colores según estado:
+  // - Default: text-content-primary
+  // - Hover: text-primary-custom-600
+  // - Selected: text-primary-custom-600
+  // - Disabled: text-content-tertiary
+  // Dark mode: invierte colores
+  const iconClasses = [
+    'w-4', // 16px
+    'h-4', // 16px
+    'shrink-0',
+
+    // Colores según estado
+    selected
+      ? // Selected: primary-custom-600 (azul oscuro)
+        'text-primary-custom-600 dark:text-white'
+      : disabled
+        ? // Disabled: content-tertiary
+          'text-content-tertiary dark:text-content-tertiary'
+        : // Default/Hover: content-primary → hover:primary-custom-600
+          'text-content-primary hover:text-primary-custom-600 dark:text-dark-content-primary dark:hover:text-white',
+
+    'transition-colors',
+    'duration-150',
+  ].join(' ');
+
+  // ===== CLASES DEL LABEL =====
+  // Tipografía: Label XXSmall (10px Bold, leading 12px) según Figma
+  // Color: text-content-primary, dark:text-dark-content-primary
+  const labelClasses = [
+    // Tipografía: Label XXSmall (10px Bold)
+    'text-xs', // 12px en lugar de text-[10px]
+    'leading-3', // 12px
+    'font-bold',
+    'text-center',
+    'w-full',
+    'min-w-full',
+
+    // Colores
+    'text-content-primary',
+    'dark:text-dark-content-primary',
+
+    // Para multiline labels, agregar truncate o text-nowrap si es necesario
+    'break-words',
+  ].join(' ');
+
+  // ===== CLASES DEL CONTENEDOR PRINCIPAL =====
+  // Según Figma: ancho 56px, flex-col, gap-1, items-center
+  const containerClasses = [
+    'relative',
+    'flex',
+    'flex-col',
+    'items-center',
+    'gap-1', // 4px según Figma
+    'px-0.5', // 2px horizontal según Figma
+    'py-0',
+    'w-14', // 56px según Figma
+    'shrink-0',
+
+    // Interactividad
+    disabled
+      ? 'cursor-not-allowed opacity-55 pointer-events-none'
+      : 'cursor-pointer',
+
+    // Focus visible (accesibilidad)
+    'focus:outline-none',
+    'focus-visible:ring-2',
+    'focus-visible:ring-primary-custom-400', // 4px ring
+    'focus-visible:ring-offset-2',
+    'focus-visible:ring-offset-primary-custom-100', // offset #dbeefe según Figma
+    'dark:focus-visible:ring-dark-border-custom',
+    'dark:focus-visible:ring-offset-dark-bg-primary',
+
+    // Focus sombras adicionales según Figma:
+    'focus-visible:shadow-lg',
+    'dark:focus-visible:shadow-2xl',
+
+    'rounded-lg',
+
+    // Clases personalizadas
+    className,
+  ].join(' ');
+
+  // ===== RENDERIZAR BADGE =====
+  const renderBadge = () => {
+    if (!badge && badgeCount === undefined) return null;
+
+    // Badge con número
+    if (badgeCount !== undefined) {
+      return (
+        <span
+          className="
+            absolute
+            -top-0.5
+            left-8
+            flex
+            items-center
+            justify-center
+            min-w-3
+            h-3
+            px-1
+            rounded-full
+            text-xs
+            font-bold
+            leading-none
+            bg-red-700
+            text-white
+            dark:bg-red-700
+            dark:text-white
+            pointer-events-none
+            select-none
+          "
+          aria-label={`${badgeCount} notificaciones`}
+          data-badge
+        >
+          {badgeCount > 99 ? '99+' : badgeCount}
+        </span>
+      );
+    }
+
+    // Badge dot simple
+    return (
+      <span
+        className="
+          absolute
+          -top-0.5
+          left-8
+          w-3
+          h-3
+          rounded-full
+          bg-red-700
+          dark:bg-red-700
+          pointer-events-none
+          select-none
+        "
+        aria-label="Notificación"
+        data-badge
+      />
+    );
+  };
+
+  return (
+    <button
+      type="button"
+      className={containerClasses}
+      disabled={disabled}
+      onClick={onClick}
+      onMouseEnter={onMouseEnter}
+      aria-label={ariaLabel || label}
+      aria-current={selected ? 'page' : undefined}
+      aria-disabled={disabled}
+      data-item-id={id}
+      data-testid={`navigation-rail-item-${id}`}
+    >
+      {/* Icon Container */}
+      {showIcon && (
+        <div className={iconContainerClasses}>
+          <span className={iconClasses}>
+            {icon}
+          </span>
+        </div>
+      )}
+
+      {/* Label */}
+      {showLabelText && (
+        <p className={labelClasses}>
+          {label}
+        </p>
+      )}
+
+      {/* Badge */}
+      {renderBadge()}
+    </button>
+  );
+};
+
+NavigationRailItem.displayName = 'NavigationRailItem';

package/src/components/NavigationRailItem/NavigationRailItem.types.ts

@@ -0,0 +1,175 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Props para NavigationRailItem
+ *
+ * Componente independiente para items individuales de NavigationRail.
+ * Implementación pixel-perfect según Figma (node 4294-22931).
+ *
+ * **Estados:**
+ * - `Enabled`: Estado normal del item
+ * - `Hover`: Overlay de color en el icon container
+ * - `Selected`: Background con overlay según Figma
+ * - `Focus`: Focus ring de 4px (#60b6fa) con offset de 2px (#dbeefe)
+ * - `Disabled`: Opacity 55% con pointer-events-none
+ *
+ * **Especificaciones de Figma:**
+ * - Ancho: 56px (w-14)
+ * - Altura: auto (flex-col)
+ * - Gap: 4px entre icon y label
+ * - Padding: 2px horizontal, 0px vertical (px-0.5)
+ * - Border radius: 9999px (rounded-full) en icon container
+ * - Tipografía label: Label XXSmall (10px Bold, leading 12px)
+ * - Icono: 16x16px
+ *
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4294-22931
+ * @see docs/colors.md - Sistema de colores
+ * @see docs/typography.md - Sistema tipográfico (Label XXSmall)
+ * @see docs/spacing.md - Sistema de espaciado
+ * @see docs/shadows.md - Sistema de sombras (focus ring)
+ */
+export interface NavigationRailItemProps {
+  /**
+   * Icono a mostrar en el item
+   * Tamaño recomendado: 16x16px
+   * Tipos compatibles: ReactNode, SVG, Heroicons, etc.
+   *
+   * @example
+   * ```tsx
+   * import { HomeIcon } from '@heroicons/react/24/outline';
+   * <NavigationRailItem icon={<HomeIcon />} />
+   * ```
+   */
+  icon: ReactNode;
+
+  /**
+   * Label/texto del item de navegación
+   * Se muestra debajo del icono en tipografía Label XXSmall
+   *
+   * @example
+   * <NavigationRailItem label="Inicio" />
+   */
+  label: string;
+
+  /**
+   * Si el item está seleccionado actualmente
+   *
+   * Estado visual:
+   * - Background: bg-primary-custom-100 (#dbeefe) con overlay rgba(0,0,0,0.024)
+   * - Icono: text-primary-custom-600 (#0e79fd)
+   * - Label: text-content-primary
+   *
+   * @default false
+   */
+  selected?: boolean;
+
+  /**
+   * Si el item está deshabilitado
+   *
+   * Estado visual:
+   * - Opacity: 55%
+   * - Cursor: not-allowed
+   * - Pointer-events: none
+   *
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Mostrar badge de notificación (dot rojo)
+   *
+   * El badge se posiciona en la esquina superior derecha del icon container.
+   * Tamaño: 13x13px
+   * Color: #b91c1c (red-700)
+   * Posición: left-[34px], top-[-3px]
+   *
+   * @default false
+   */
+  badge?: boolean;
+
+  /**
+   * Número a mostrar en el badge (reemplaza el dot simple)
+   *
+   * Si el número es mayor a 99, muestra "99+"
+   * Tipografía: 10px Bold
+   * Color: white (#ffffff)
+   *
+   * @example
+   * <NavigationRailItem badgeCount={5} />  // Muestra: 5
+   * <NavigationRailItem badgeCount={150} /> // Muestra: 99+
+   */
+  badgeCount?: number;
+
+  /**
+   * Handler para evento click del item
+   *
+   * Se ejecuta cuando el usuario hace click en el item,
+   * incluso si está en estado selected.
+   */
+  onClick?: () => void;
+
+  /**
+   * Handler para evento mouse enter del item
+   *
+   * Se ejecuta cuando el cursor entra en el área del item.
+   * Útil para mostrar paneles o menús contextuales.
+   */
+  onMouseEnter?: () => void;
+
+  /**
+   * Label para accesibilidad (ARIA-label)
+   *
+   * Si no se proporciona, usa el valor de `label`
+   *
+   * @example
+   * <NavigationRailItem label="Inicio" ariaLabel="Ir a la página de inicio" />
+   */
+  ariaLabel?: string;
+
+  /**
+   * ID único del item
+   *
+   * Usado para identificar el item en callbacks y para navegación.
+   * Se añade como atributo data-item-id en el elemento DOM.
+   *
+   * @example
+   * <NavigationRailItem id="home" label="Inicio" />
+   */
+  id?: string;
+
+  /**
+   * Mostrar el label del texto
+   *
+   * Si es false, solo se muestra el icono
+   *
+   * @default true
+   */
+  showLabelText?: boolean;
+
+  /**
+   * Mostrar icono
+   *
+   * Si es false, solo se muestra el label
+   *
+   * @default true
+   */
+  showIcon?: boolean;
+
+  /**
+   * Clases CSS adicionales personalizadas
+   *
+   * Se aplican al contenedor principal (button)
+   */
+  className?: string;
+}
+
+/**
+ * Estados posibles del componente según Figma
+ *
+ * - `Enabled`: Estado normal, sin interacción
+ * - `Hover`: Mouse over el item
+ * - `Selected`: Item actualmente seleccionado
+ * - `Focus`: Keyboard focus (accesibilidad)
+ * - `Disabled`: Item deshabilitado, no interactivo
+ */
+export type NavigationRailItemState = 'Enabled' | 'Hover' | 'Selected' | 'Focus' | 'Disabled';