siesa-ui-kit 1.0.3 → 1.0.4

package/src/components/Select/Select.tsx

@@ -0,0 +1,457 @@
+import React, { useState, useRef, useEffect } from 'react';
+import type { SelectProps, SelectOption } from './Select.types';
+import { ChevronUpDownIcon, CheckIcon } from './icons';
+
+/**
+ * Select - Componente de selección (dropdown) del sistema de diseño Siesa
+ *
+ * Componente Select personalizado con menú desplegable para seleccionar opciones
+ * de una lista. Incluye navegación por teclado, click outside y dark mode completo.
+ *
+ * Mejores prácticas implementadas:
+ * - Orden de modificadores: {responsive}:{dark}:{state}:{utility}
+ * - Dark mode con estrategia 'class' (darkMode: 'class')
+ * - Tokens de color consistentes con la documentación
+ * - Type safety con TypeScript estricto
+ * - Accesibilidad con ARIA labels y keyboard navigation
+ * - Click outside para cerrar el menú
+ * - Soporte de teclado (Enter, Escape, Arrow Up/Down)
+ *
+ * @see docs/colors.md - Sistema de colores
+ * @see docs/typography.md - Sistema tipográfico
+ * @see docs/spacing.md - Sistema de espaciado
+ *
+ * @example
+ * ```tsx
+ * <Select
+ *   options={[
+ *     { value: '1', label: 'Option 1' },
+ *     { value: '2', label: 'Option 2' },
+ *   ]}
+ *   value={selectedValue}
+ *   onChange={setSelectedValue}
+ *   placeholder="Select an option"
+ *   label="Choose one"
+ * />
+ * ```
+ */
+export const Select: React.FC<SelectProps> = ({
+  options = [],
+  value,
+  defaultValue,
+  placeholder = 'Seleccionar...',
+  disabled = false,
+  error = false,
+  label,
+  description,
+  showLabel = true,
+  showDescription = true,
+  menuHeader,
+  onChange,
+  className = '',
+  triggerClassName = '',
+  menuClassName = '',
+  ariaLabel,
+  id,
+  name,
+  required = false,
+  menuPosition = 'bottom',
+  fullWidth = false,
+}) => {
+  // ===== ESTADO Y REFS =====
+  const [isOpen, setIsOpen] = useState(false);
+  const [selectedValue, setSelectedValue] = useState<string | number | undefined>(
+    value !== undefined ? value : defaultValue
+  );
+  const [focusedIndex, setFocusedIndex] = useState(-1);
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  // ===== SINCRONIZAR VALOR CONTROLADO =====
+  useEffect(() => {
+    if (value !== undefined) {
+      setSelectedValue(value);
+    }
+  }, [value]);
+
+  // ===== CERRAR AL HACER CLICK FUERA =====
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
+        setIsOpen(false);
+      }
+    };
+
+    if (isOpen) {
+      document.addEventListener('mousedown', handleClickOutside);
+      return () => {
+        document.removeEventListener('mousedown', handleClickOutside);
+      };
+    }
+  }, [isOpen]);
+
+  // ===== KEYBOARD NAVIGATION =====
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (!isOpen) return;
+
+      switch (event.key) {
+        case 'Escape':
+          setIsOpen(false);
+          triggerRef.current?.focus();
+          break;
+        case 'ArrowDown':
+          event.preventDefault();
+          setFocusedIndex((prev) => (prev < options.length - 1 ? prev + 1 : 0));
+          break;
+        case 'ArrowUp':
+          event.preventDefault();
+          setFocusedIndex((prev) => (prev > 0 ? prev - 1 : options.length - 1));
+          break;
+        case 'Enter':
+          event.preventDefault();
+          if (focusedIndex >= 0 && focusedIndex < options.length) {
+            handleSelect(options[focusedIndex]);
+          }
+          break;
+      }
+    };
+
+    if (isOpen) {
+      document.addEventListener('keydown', handleKeyDown);
+      return () => {
+        document.removeEventListener('keydown', handleKeyDown);
+      };
+    }
+  }, [isOpen, focusedIndex, options]);
+
+  // ===== HELPERS =====
+  const selectedOption = options.find((opt) => opt.value === selectedValue);
+
+  const toggleMenu = () => {
+    if (!disabled) {
+      setIsOpen(!isOpen);
+      setFocusedIndex(-1);
+    }
+  };
+
+  const handleSelect = (option: SelectOption) => {
+    if (option.disabled) return;
+
+    setSelectedValue(option.value);
+    setIsOpen(false);
+    onChange?.(option.value);
+
+    setTimeout(() => {
+      triggerRef.current?.focus();
+    }, 0);
+  };
+
+  // ===== CLASES BASE DEL TRIGGER =====
+  // Usando el sistema tipográfico Paragraph Regular (14px = text-sm)
+  // Border radius rounded-lg (8px) consistente con especificaciones
+  // Gap de 12px (gap-3) entre texto e icono según Figma
+  const baseTriggerClasses = `
+    inline-flex
+    items-center
+    justify-between
+    gap-3
+    w-full
+    px-3
+    py-2
+    text-sm
+    font-normal
+    leading-5
+    rounded-lg
+    border
+    transition-all
+    duration-150
+  `;
+
+  // ===== CLASES DE WIDTH =====
+  const widthClasses = fullWidth ? 'w-full' : 'min-w-[200px]';
+
+  // ===== CLASES PARA ESTADOS DEL TRIGGER =====
+  // Orden de modificadores: {responsive}:{dark}:{state}:{utility}
+  const triggerStateClasses = error
+    ? `
+      border-error-border
+      bg-error-bg
+      text-content-primary
+      dark:border-error-border
+      dark:bg-error-bg
+      dark:text-dark-content-primary
+    `
+    : `
+      bg-bg-primary
+      border-border-primary
+      text-content-primary
+      dark:bg-dark-bg-primary
+      dark:border-dark-border-primary
+      dark:text-dark-content-primary
+    `;
+
+  // ===== CLASES PARA HOVER DEL TRIGGER =====
+  // Hover: border más claro según Figma (#f9f9f9)
+  const triggerHoverClasses =
+    !disabled && !error
+      ? `
+        hover:border-[#f9f9f9]
+        dark:hover:border-[#3a3a3f]
+      `
+      : '';
+
+  // ===== CLASES PARA FOCUS DEL TRIGGER =====
+  // Focus: border-2 con color específico #329cff según Figma
+  const triggerFocusClasses = !disabled
+    ? `
+      focus:outline-none
+      focus-within:border-2
+      focus-within:border-[#329cff]
+      dark:focus-within:border-[#329cff]
+    `
+    : '';
+
+  // ===== CLASES PARA DISABLED DEL TRIGGER =====
+  const triggerDisabledClasses = disabled
+    ? `
+      opacity-50
+      cursor-not-allowed
+    `
+    : '';
+
+  // ===== COMBINAR CLASES DEL TRIGGER =====
+  const finalTriggerClasses = [
+    baseTriggerClasses,
+    widthClasses,
+    triggerStateClasses,
+    triggerHoverClasses,
+    triggerFocusClasses,
+    triggerDisabledClasses,
+    triggerClassName,
+  ]
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  // ===== CLASES BASE DEL MENU =====
+  // Según Figma: altura fija 160px (h-40), border secundario,
+  // spacing de 4px desde trigger (mt-1), shadow-lg para elevación
+  const baseMenuClasses = `
+    absolute
+    z-50
+    w-full
+    min-w-[200px]
+    max-h-40
+    overflow-y-auto
+    p-1
+    rounded-md
+    border
+    shadow-lg
+    transition-all
+    duration-150
+  `;
+
+  // ===== CLASES DE POSICIÓN DEL MENU =====
+  // Figma muestra 4px de separación, usando mt-1 en lugar de mt-2
+  const menuPositionClasses = menuPosition === 'top' ? 'bottom-full mb-1' : 'top-full mt-1';
+
+  // ===== CLASES DE COLOR DEL MENU =====
+  // Background secundario según Figma con border secundario
+  const menuColorClasses = `
+    bg-background-secondary
+    border-border-secondary
+    dark:bg-dark-bg-primary
+    dark:border-dark-border-primary
+  `;
+
+  // ===== CLASES DE VISIBILIDAD DEL MENU =====
+  const menuVisibilityClasses = isOpen ? 'opacity-100 visible' : 'opacity-0 invisible';
+
+  // ===== COMBINAR CLASES DEL MENU =====
+  const finalMenuClasses = [
+    baseMenuClasses,
+    menuPositionClasses,
+    menuColorClasses,
+    menuVisibilityClasses,
+    menuClassName,
+  ]
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  // ===== CLASES BASE DEL MENU ITEM =====
+  // CRÍTICO: Figma especifica text-[10px] leading-[12px] (Label XXSmall)
+  // Gap de 2px (gap-0.5) entre elementos según Figma
+  const baseMenuItemClasses = `
+    flex
+    items-center
+    cursor-pointer
+    rounded-md
+    transition-all
+    duration-150
+    pl-2
+    pr-2.5
+    py-0.5
+    gap-0.5
+    text-[10px]
+    leading-[12px]
+    font-bold
+  `;
+
+  // ===== FUNCIÓN PARA OBTENER CLASES DE MENU ITEM =====
+  const getMenuItemClasses = (option: SelectOption, index: number) => {
+    const isSelected = option.value === selectedValue;
+    const isFocused = index === focusedIndex;
+
+    // Estados de color según Figma:
+    // - Default: text-content-primary
+    // - Hover: bg-primary-custom-600 + text-primary-inverse-content
+    // - Selected: muestra check icon, mismo text color que default
+    const colorClasses =
+      isFocused || (isSelected && isFocused)
+        ? 'bg-primary-custom-600 text-primary-inverse-content dark:bg-primary-custom-600 dark:text-primary-inverse-content'
+        : 'text-content-primary dark:text-dark-content-primary';
+
+    // Hover: fondo azul primario con texto blanco
+    const hoverClasses = !option.disabled
+      ? 'hover:bg-primary-custom-600 hover:text-primary-inverse-content dark:hover:bg-primary-custom-600 dark:hover:text-primary-inverse-content'
+      : '';
+
+    // Disabled
+    const disabledClasses = option.disabled ? 'opacity-50 cursor-not-allowed' : '';
+
+    return [baseMenuItemClasses, colorClasses, hoverClasses, disabledClasses]
+      .join(' ')
+      .replace(/\s+/g, ' ')
+      .trim();
+  };
+
+  // ===== CLASES DEL ICONO DEL TRIGGER =====
+  // Chevron icon 20x20px (size-5) según sistema Heroicons
+  const iconClasses = [
+    'size-5',
+    'flex-shrink-0',
+    'transition-transform',
+    'duration-150',
+    isOpen && 'rotate-180',
+    disabled ? 'text-content-tertiary dark:text-content-tertiary' : 'text-content-secondary dark:text-content-secondary',
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  // ===== CLASES DEL CHECK ICON =====
+  // Check icon 16x16px (size-4) según sistema Heroicons
+  const checkIconClasses = 'size-4 flex-shrink-0';
+
+  // ===== RENDERIZAR COMPONENTE =====
+  return (
+    <div className={`relative ${fullWidth ? 'w-full' : ''} ${className}`} ref={containerRef}>
+      {/* Label and Description - Según Figma, van ANTES del trigger con gap-1 (4px) */}
+      {(showLabel && label) || (showDescription && description) ? (
+        <div className="flex flex-col gap-1 mb-1 w-full">
+          {/* Label - Label Small (14px bold) */}
+          {showLabel && label && (
+            <label
+              htmlFor={id}
+              className="text-sm font-bold leading-5 text-content-primary dark:text-dark-content-primary"
+            >
+              {label}
+              {required && <span className="ml-1 text-error-content">*</span>}
+            </label>
+          )}
+
+          {/* Description - Paragraph Small (14px regular) */}
+          {showDescription && description && (
+            <p className="text-sm font-normal leading-5 text-content-tertiary dark:text-content-tertiary">
+              {description}
+            </p>
+          )}
+        </div>
+      ) : null}
+
+      {/* Trigger Button */}
+      <button
+        ref={triggerRef}
+        type="button"
+        className={finalTriggerClasses}
+        onClick={toggleMenu}
+        disabled={disabled}
+        aria-label={ariaLabel || label}
+        aria-haspopup="listbox"
+        aria-expanded={isOpen}
+        id={id}
+      >
+        {/* Selected value or placeholder */}
+        <span
+          className={
+            selectedOption ? '' : 'text-content-secondary dark:text-content-secondary'
+          }
+        >
+          {selectedOption ? selectedOption.label : placeholder}
+        </span>
+
+        {/* Chevron icon */}
+        <ChevronUpDownIcon className={iconClasses} />
+      </button>
+
+      {/* Hidden input for forms */}
+      {name && (
+        <input
+          type="hidden"
+          name={name}
+          value={selectedValue !== undefined ? String(selectedValue) : ''}
+        />
+      )}
+
+      {/* Menu */}
+      {isOpen && (
+        <div ref={menuRef} className={finalMenuClasses} role="listbox">
+          {/* Menu Header - Opcional según Figma */}
+          {menuHeader && (
+            <div className="flex items-center gap-0.5 px-6 py-0.5 rounded-[5px]">
+              <span className="text-[10px] font-bold leading-[12px] text-content-tertiary dark:text-content-tertiary">
+                {menuHeader}
+              </span>
+            </div>
+          )}
+
+          {/* Empty state */}
+          {options.length === 0 && (
+            <div className="px-2 py-1.5 text-[10px] leading-[12px] text-content-secondary dark:text-content-secondary">
+              No hay opciones disponibles
+            </div>
+          )}
+
+          {/* Options */}
+          {options.map((option, index) => (
+            <div
+              key={option.value}
+              className={getMenuItemClasses(option, index)}
+              onClick={() => handleSelect(option)}
+              onMouseEnter={() => setFocusedIndex(index)}
+              role="option"
+              aria-selected={option.value === selectedValue}
+              aria-disabled={option.disabled}
+            >
+              {/* Check icon for selected item */}
+              <div className="w-4 flex items-center justify-center">
+                {option.value === selectedValue && <CheckIcon className={checkIconClasses} />}
+              </div>
+
+              {/* Custom icon if provided */}
+              {option.icon && <span className="flex-shrink-0 w-4 h-4">{option.icon}</span>}
+
+              {/* Label */}
+              <span className="flex-1 text-left">{option.label}</span>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};

package/src/components/Select/Select.types.ts

@@ -0,0 +1,148 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Opción individual del Select
+ */
+export interface SelectOption {
+  /**
+   * Valor único de la opción
+   */
+  value: string | number;
+
+  /**
+   * Label visible de la opción
+   */
+  label: string;
+
+  /**
+   * Si la opción está deshabilitada
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Icono personalizado para la opción
+   */
+  icon?: ReactNode;
+}
+
+/**
+ * Props del componente Select
+ */
+export interface SelectProps {
+  /**
+   * Opciones disponibles para seleccionar
+   */
+  options: SelectOption[];
+
+  /**
+   * Valor seleccionado actual
+   */
+  value?: string | number;
+
+  /**
+   * Valor por defecto inicial
+   */
+  defaultValue?: string | number;
+
+  /**
+   * Texto del placeholder cuando no hay selección
+   * @default 'Seleccionar...'
+   */
+  placeholder?: string;
+
+  /**
+   * Si el select está deshabilitado
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Si el select muestra un error
+   * @default false
+   */
+  error?: boolean;
+
+  /**
+   * Label del select (opcional)
+   */
+  label?: string;
+
+  /**
+   * Texto descriptivo que aparece debajo del label y antes del trigger
+   * Equivale al "Description" de Figma
+   * @example "This will be visible to clients on the project."
+   */
+  description?: string;
+
+  /**
+   * Muestra el label
+   * @default true
+   */
+  showLabel?: boolean;
+
+  /**
+   * Muestra la descripción
+   * @default true
+   */
+  showDescription?: boolean;
+
+  /**
+   * Header opcional que aparece al inicio del menú
+   * @example "Header ..."
+   */
+  menuHeader?: string;
+
+  /**
+   * Handler cuando cambia la selección
+   */
+  onChange?: (value: string | number) => void;
+
+  /**
+   * Clases CSS adicionales
+   */
+  className?: string;
+
+  /**
+   * Clases CSS adicionales para el trigger
+   */
+  triggerClassName?: string;
+
+  /**
+   * Clases CSS adicionales para el menu
+   */
+  menuClassName?: string;
+
+  /**
+   * Label para accesibilidad (ARIA)
+   */
+  ariaLabel?: string;
+
+  /**
+   * ID del select para asociar con label
+   */
+  id?: string;
+
+  /**
+   * Nombre del campo para formularios
+   */
+  name?: string;
+
+  /**
+   * Si el campo es requerido
+   * @default false
+   */
+  required?: boolean;
+
+  /**
+   * Posición del menú desplegable
+   * @default 'bottom'
+   */
+  menuPosition?: 'top' | 'bottom';
+
+  /**
+   * Ancho completo
+   * @default false
+   */
+  fullWidth?: boolean;
+}

package/src/components/Select/icons.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import {
+  ChevronUpDownIcon as HeroChevronUpDown,
+  CheckIcon as HeroCheck
+} from '@heroicons/react/24/outline';
+
+/**
+ * Icono ChevronUpDown para el trigger del Select
+ * Basado en Heroicons 24/outline (24x24px)
+ *
+ * @see https://heroicons.com/
+ */
+export const ChevronUpDownIcon: React.FC<{ className?: string }> = ({ className = 'size-5' }) => (
+  <HeroChevronUpDown className={className} aria-hidden="true" />
+);
+
+/**
+ * Icono Check para los items seleccionados del menu
+ * Basado en Heroicons 24/outline (24x24px)
+ *
+ * @see https://heroicons.com/
+ */
+export const CheckIcon: React.FC<{ className?: string }> = ({ className = 'size-4' }) => (
+  <HeroCheck className={className} aria-hidden="true" />
+);

package/src/components/Select/index.ts

@@ -0,0 +1,3 @@
+export { Select } from './Select';
+export type { SelectProps, SelectOption } from './Select.types';
+export { ChevronUpDownIcon, CheckIcon } from './icons';