siesa-ui-kit 1.0.0

package/src/components/Dropdown/Dropdown.tsx

@@ -0,0 +1,422 @@
+import React, { useState, useRef, useEffect } from 'react';
+import type {
+  DropdownProps,
+  DropdownItemProps,
+  DropdownHeadingProps,
+  DropdownDividerProps,
+} from './Dropdown.types';
+import { ChevronDownIcon } from './icons';
+
+/**
+ * Componente Dropdown del sistema de diseño Siesa
+ * Basado en especificaciones de Figma con Tailwind CSS
+ *
+ * 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
+ * - Cierre automático al hacer click fuera
+ *
+ * @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
+ *
+ * @example
+ * ```tsx
+ * <Dropdown
+ *   placeholder="Options"
+ *   items={[
+ *     { children: 'Account', icon: <UserIcon /> },
+ *     { children: 'Settings', icon: <CogIcon /> },
+ *     { isDivider: true },
+ *     { children: 'Logout' },
+ *   ]}
+ * />
+ * ```
+ */
+export const Dropdown: React.FC<DropdownProps> = ({
+  variant = 'default',
+  children,
+  items,
+  open: controlledOpen,
+  onOpenChange,
+  disabled = false,
+  className = '',
+  menuClassName = '',
+  ariaLabel,
+  placeholder = 'Options',
+}) => {
+  const [internalOpen, setInternalOpen] = useState(false);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  // Determinar si es controlado o no controlado
+  const isControlled = controlledOpen !== undefined;
+  const isOpen = isControlled ? controlledOpen : internalOpen;
+
+  // Función para cambiar el estado
+  const handleToggle = () => {
+    if (disabled) return;
+
+    const newOpen = !isOpen;
+
+    if (!isControlled) {
+      setInternalOpen(newOpen);
+    }
+
+    onOpenChange?.(newOpen);
+  };
+
+  // Cerrar al hacer click fuera
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+        if (!isControlled) {
+          setInternalOpen(false);
+        }
+        onOpenChange?.(false);
+      }
+    };
+
+    if (isOpen) {
+      document.addEventListener('mousedown', handleClickOutside);
+      return () => {
+        document.removeEventListener('mousedown', handleClickOutside);
+      };
+    }
+  }, [isOpen, isControlled, onOpenChange]);
+
+  // Cerrar al presionar Escape
+  useEffect(() => {
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape' && isOpen) {
+        if (!isControlled) {
+          setInternalOpen(false);
+        }
+        onOpenChange?.(false);
+      }
+    };
+
+    if (isOpen) {
+      document.addEventListener('keydown', handleEscape);
+      return () => {
+        document.removeEventListener('keydown', handleEscape);
+      };
+    }
+  }, [isOpen, isControlled, onOpenChange]);
+
+  // Handler para item click
+  const handleItemClick = (item: DropdownItemProps) => {
+    if (item.disabled || item.isDivider || item.isHeading) return;
+
+    // Ejecutar el onClick del item
+    if (item.onClick) {
+      item.onClick({} as React.MouseEvent<HTMLButtonElement>);
+    }
+
+    // Cerrar el dropdown
+    if (!isControlled) {
+      setInternalOpen(false);
+    }
+    onOpenChange?.(false);
+  };
+
+  // ===== CLASES DEL TRIGGER BUTTON =====
+  const triggerClasses = [
+    // Base
+    'inline-flex',
+    'items-center',
+    'justify-center',
+    'rounded-lg',
+    'font-bold',
+    'text-sm',
+    'whitespace-nowrap',
+    'transition-all',
+    'duration-150',
+
+    // Variant-specific sizing
+    variant === 'icon-only' ? 'w-9 h-9' : 'gap-3 px-3 py-2',
+
+    // Colores y estados (Light Mode)
+    'bg-bg-primary',
+    'text-content-secondary',
+    'border',
+    'border-border-primary',
+    'hover:bg-background-secondary',
+    'active:scale-95',
+
+    // Dark Mode
+    'dark:bg-dark-bg-primary',
+    'dark:text-content-secondary',
+    'dark:border-dark-border-primary',
+    'dark:hover:bg-dark-bg-primary',
+
+    // Focus ring
+    'focus:outline-none',
+    'focus:ring-2',
+    'focus:ring-primary-custom-400',
+    'focus:ring-offset-2',
+    'dark:focus:ring-dark-border-custom',
+    'dark:focus:ring-offset-dark-bg-primary',
+
+    // Disabled
+    disabled && 'opacity-50',
+    disabled && 'cursor-not-allowed',
+    disabled && 'pointer-events-none',
+
+    // Custom classes
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  // ===== CLASES DEL MENU =====
+  const menuClasses = [
+    // Base
+    'absolute',
+    'top-full',
+    'left-0',
+    'mt-2',
+    'min-w-[182px]',
+    'rounded-xl',
+    'p-1',
+    'border',
+    'z-50',
+
+    // Colores (Light Mode)
+    'bg-background-secondary',
+    'border-border-primary',
+
+    // Dark Mode
+    'dark:bg-dark-bg-primary',
+    'dark:border-dark-border-primary',
+
+    // Shadow
+    'shadow-menu',
+
+    // Custom classes
+    menuClassName,
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  return (
+    <div ref={dropdownRef} className="relative inline-block">
+      {/* Trigger Button */}
+      <button
+        type="button"
+        className={triggerClasses}
+        onClick={handleToggle}
+        disabled={disabled}
+        aria-label={ariaLabel || (variant === 'icon-only' ? 'Abrir menú' : undefined)}
+        aria-haspopup="true"
+        aria-expanded={isOpen}
+      >
+        {variant === 'default' && <span>{children || placeholder}</span>}
+        <ChevronDownIcon />
+      </button>
+
+      {/* Dropdown Menu */}
+      {isOpen && (
+        <div className={menuClasses}>
+          {items.map((item, index) => {
+            if (item.isDivider) {
+              return <DropdownDivider key={index} className={item.className} />;
+            }
+
+            if (item.isHeading) {
+              return (
+                <DropdownHeading key={index} className={item.className}>
+                  {item.children}
+                </DropdownHeading>
+              );
+            }
+
+            return (
+              <DropdownItem
+                key={index}
+                {...item}
+                onClick={() => handleItemClick(item)}
+              />
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+};
+
+/**
+ * Componente DropdownItem
+ * Item individual dentro del menú dropdown
+ *
+ * @example
+ * ```tsx
+ * <DropdownItem icon={<UserIcon />} shortcut="⌘ P">
+ *   Profile
+ * </DropdownItem>
+ * ```
+ */
+export const DropdownItem: React.FC<DropdownItemProps> = ({
+  children,
+  icon,
+  description,
+  shortcut,
+  disabled = false,
+  selected = false,
+  onClick,
+  className = '',
+}) => {
+  // ===== CLASES DEL ITEM =====
+  const itemClasses = [
+    // Base
+    'flex',
+    'items-center',
+    'gap-3',
+    'px-4',
+    'py-2',
+    'rounded-lg',
+    'text-sm',
+    'w-full',
+    'text-left',
+    'transition-colors',
+    'duration-150',
+
+    // Colores y estados (Light Mode)
+    'text-content-primary',
+    !disabled && 'hover:bg-white',
+    selected && 'bg-white',
+
+    // Dark Mode
+    'dark:text-dark-content-primary',
+    !disabled && 'dark:hover:bg-dark-bg-primary',
+    selected && 'dark:bg-dark-bg-primary',
+
+    // Disabled
+    disabled && 'opacity-50',
+    disabled && 'cursor-not-allowed',
+    !disabled && 'cursor-pointer',
+
+    // Custom classes
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  return (
+    <button
+      type="button"
+      className={itemClasses}
+      onClick={onClick}
+      disabled={disabled}
+    >
+      {/* Icon */}
+      {icon && (
+        <span className="inline-flex items-center justify-center w-4 h-4 text-content-secondary dark:text-content-secondary">
+          {icon}
+        </span>
+      )}
+
+      {/* Content */}
+      <div className="flex-1 min-w-0">
+        {/* Label */}
+        <div className="text-content-primary dark:text-dark-content-primary">
+          {children}
+        </div>
+
+        {/* Description */}
+        {description && (
+          <div className="text-xs text-content-secondary dark:text-content-secondary mt-0.5">
+            {description}
+          </div>
+        )}
+      </div>
+
+      {/* Shortcut */}
+      {shortcut && (
+        <span className="text-xs text-content-secondary dark:text-content-secondary ml-auto whitespace-nowrap">
+          {shortcut}
+        </span>
+      )}
+    </button>
+  );
+};
+
+/**
+ * Componente DropdownHeading
+ * Encabezado de sección dentro del menú dropdown
+ *
+ * @example
+ * ```tsx
+ * <DropdownHeading>My events</DropdownHeading>
+ * ```
+ */
+export const DropdownHeading: React.FC<DropdownHeadingProps> = ({
+  children,
+  className = '',
+}) => {
+  // ===== CLASES DEL HEADING =====
+  const headingClasses = [
+    // Base
+    'px-4',
+    'py-1',
+    'text-xs',
+    'font-normal',
+
+    // Colores
+    'text-content-tertiary',
+
+    // Dark Mode
+    'dark:text-content-tertiary',
+
+    // Custom classes
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  return <div className={headingClasses}>{children}</div>;
+};
+
+/**
+ * Componente DropdownDivider
+ * Separador visual entre items del menú dropdown
+ *
+ * @example
+ * ```tsx
+ * <DropdownDivider />
+ * ```
+ */
+export const DropdownDivider: React.FC<DropdownDividerProps> = ({
+  className = '',
+}) => {
+  // ===== CLASES DEL DIVIDER =====
+  const dividerClasses = [
+    // Base
+    'px-4',
+    'py-1',
+
+    // Custom classes
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  return (
+    <div className={dividerClasses}>
+      <div className="h-px bg-border-primary dark:bg-dark-border-primary" />
+    </div>
+  );
+};

package/src/components/Dropdown/Dropdown.types.ts

@@ -0,0 +1,146 @@
+import type { ReactNode, MouseEvent } from 'react';
+
+/**
+ * Props del componente Dropdown (trigger button)
+ */
+export interface DropdownProps {
+  /**
+   * Variante visual del dropdown
+   * - 'default': Botón con texto + ícono
+   * - 'icon-only': Solo ícono (sin texto)
+   * @default 'default'
+   */
+  variant?: 'default' | 'icon-only';
+
+  /**
+   * Texto o contenido del botón trigger
+   */
+  children?: ReactNode;
+
+  /**
+   * Items del menú dropdown
+   */
+  items: DropdownItemProps[];
+
+  /**
+   * Si el dropdown está abierto (controlado)
+   */
+  open?: boolean;
+
+  /**
+   * Callback cuando el dropdown cambia de estado
+   */
+  onOpenChange?: (open: boolean) => void;
+
+  /**
+   * Si el dropdown está deshabilitado
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Clases CSS adicionales para el trigger
+   */
+  className?: string;
+
+  /**
+   * Clases CSS adicionales para el menú
+   */
+  menuClassName?: string;
+
+  /**
+   * Label para accesibilidad (ARIA)
+   */
+  ariaLabel?: string;
+
+  /**
+   * Placeholder cuando no hay children
+   * @default 'Options'
+   */
+  placeholder?: string;
+}
+
+/**
+ * Props del componente DropdownItem
+ */
+export interface DropdownItemProps {
+  /**
+   * Contenido del item
+   * No requerido cuando isDivider es true
+   */
+  children?: ReactNode;
+
+  /**
+   * Icono a mostrar antes del texto (izquierda)
+   */
+  icon?: ReactNode;
+
+  /**
+   * Descripción secundaria del item
+   */
+  description?: string;
+
+  /**
+   * Atajo de teclado a mostrar (derecha)
+   */
+  shortcut?: string;
+
+  /**
+   * Si el item está deshabilitado
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Si el item está seleccionado
+   * @default false
+   */
+  selected?: boolean;
+
+  /**
+   * Función onClick del item
+   */
+  onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+
+  /**
+   * Clases CSS adicionales
+   */
+  className?: string;
+
+  /**
+   * Indica si este item es un divider (separador)
+   * @default false
+   */
+  isDivider?: boolean;
+
+  /**
+   * Indica si este item es un heading (encabezado)
+   * @default false
+   */
+  isHeading?: boolean;
+}
+
+/**
+ * Props del componente DropdownHeading
+ */
+export interface DropdownHeadingProps {
+  /**
+   * Texto del heading
+   */
+  children: ReactNode;
+
+  /**
+   * Clases CSS adicionales
+   */
+  className?: string;
+}
+
+/**
+ * Props del componente DropdownDivider
+ */
+export interface DropdownDividerProps {
+  /**
+   * Clases CSS adicionales
+   */
+  className?: string;
+}