siesa-ui-kit 1.0.0 → 1.0.2

package/src/components/DropdownItemHeading/README.md

@@ -0,0 +1,573 @@
+# DropdownItemHeading
+
+Componente de encabezado especializado para menús dropdown del sistema de diseño Siesa. Muestra un icono, label principal, descripción opcional y acción opcional con soporte completo para dark mode.
+
+## 📋 Tabla de Contenidos
+
+1. [Descripción](#descripción)
+2. [Especificaciones](#especificaciones)
+3. [Instalación & Uso](#instalación--uso)
+4. [Props](#props)
+5. [Ejemplos](#ejemplos)
+6. [Guía de Componentes Relacionados](#guía-de-componentes-relacionados)
+7. [Mejores Prácticas](#mejores-prácticas)
+8. [Dark Mode](#dark-mode)
+9. [Accesibilidad](#accesibilidad)
+
+---
+
+## Descripción
+
+El componente `DropdownItemHeading` es un encabezado especializado para menús dropdown que proporciona una forma consistente de mostrar encabezados con icono, label, descripción y acciones.
+
+### Casos de Uso
+
+- Encabezados de secciones en dropdowns
+- Información de usuario con opciones de acción (Clear, Reset)
+- Configuraciones rápidas en menús
+- Menús contextuales con información descriptiva
+
+### Características Principales
+
+✅ Icono opcional de 16x16px
+✅ Label principal (14px Bold)
+✅ Descripción opcional (12px Regular)
+✅ Acción opcional en la derecha (10px Regular)
+✅ Soporte completo para dark mode
+✅ Focus rings adaptativos
+✅ Tipografía del sistema (Label/Small, Paragraph/Tiny)
+✅ Espaciado consistente (12px gaps)
+✅ Diseño flexible y responsivo
+
+---
+
+## Especificaciones
+
+### Dimensiones
+
+| Elemento | Valor |
+|----------|-------|
+| Altura | Flexible (contenido) |
+| Ancho mínimo | 224px / 56 (Tailwind: w-56) |
+| Padding H | 16px (px-4) |
+| Padding V | 8px (py-2) |
+| Border radius | 8px (rounded-lg) |
+
+### Tipografía
+
+| Elemento | Estilo | Tamaño | Peso | Altura de Línea | Color (Light) | Color (Dark) |
+|----------|--------|--------|------|-----------------|---------------|-------------|
+| Label | Label/Small | 14px | Bold (700) | 20px | #18181b | #bfe2fe |
+| Description | Paragraph/Tiny | 12px | Regular (400) | 16px | #a1a1aa | #93d1fd |
+| Action | Paragraph/XXSmall | 10px | Regular (400) | 12px | #a1a1aa | #93d1fd |
+
+### Espaciado
+
+| Elemento | Valor |
+|----------|-------|
+| Gap general (icon-content-action) | 12px (gap-3) |
+| Gap entre label y description | 2px (gap-0.5) |
+| Icon wrapper | 16x16px (w-4 h-4) |
+| Content wrapper | flex-1 (flexible) |
+
+### Icono
+
+| Propiedad | Valor |
+|-----------|-------|
+| Tamaño | 16x16px |
+| Color (Light) | primary-custom-600 (#0e79fd) |
+| Color (Dark) | dark-content-inverse (#bfe2fe) |
+| Icono por defecto | Cog (heroicons/cog-8-tooth) |
+
+---
+
+## Instalación & Uso
+
+### Importación
+
+```tsx
+import { DropdownItemHeading } from '@/components/DropdownItemHeading';
+```
+
+### Uso Básico
+
+```tsx
+<DropdownItemHeading
+  label="My Account"
+  description="user@example.com"
+  showDescription={true}
+  showIcon={true}
+  actionLabel="Clear"
+  showAction={true}
+/>
+```
+
+---
+
+## Props
+
+### Interface `DropdownItemHeadingProps`
+
+```typescript
+interface DropdownItemHeadingProps {
+  label?: string;
+  description?: string;
+  showDescription?: boolean;
+  icon?: ReactNode;
+  showIcon?: boolean;
+  actionLabel?: string;
+  showAction?: boolean;
+  onActionClick?: (event: React.MouseEvent<HTMLDivElement>) => void;
+  className?: string;
+  [key: string]: unknown;
+}
+```
+
+### Detalle de Props
+
+#### `label`
+- **Tipo**: `string`
+- **Default**: `'Label'`
+- **Descripción**: Texto del label principal
+- **Tipografía**: Label/Small (14px Bold)
+- **Dark Mode**: #18181b (light) → #bfe2fe (dark)
+
+#### `description`
+- **Tipo**: `string`
+- **Default**: `undefined`
+- **Descripción**: Texto de descripción secundaria
+- **Tipografía**: Paragraph/Tiny (12px Regular)
+- **Dark Mode**: #a1a1aa (light) → #93d1fd (dark)
+
+#### `showDescription`
+- **Tipo**: `boolean`
+- **Default**: `true`
+- **Descripción**: Si se debe mostrar la descripción
+
+#### `iconType`
+- **Tipo**: `'cog' | 'custom' | null`
+- **Default**: `'cog'`
+- **Descripción**: Tipo de icono a mostrar
+  - `'cog'`: Icono de engranaje (heroicons-micro/cog-6-tooth)
+  - `'custom'`: Icono personalizado (proporcionar en `icon`)
+  - `null`: Sin icono
+
+#### `icon`
+- **Tipo**: `ReactNode`
+- **Default**: `undefined`
+- **Descripción**: Icono personalizado a mostrar
+- **Solo se usa**: Cuando `iconType` es `'custom'`
+- **Tamaño recomendado**: 16x16px
+
+#### `showIcon`
+- **Tipo**: `boolean`
+- **Default**: `true`
+- **Descripción**: Si se debe mostrar el icono
+
+#### `actionLabel`
+- **Tipo**: `string`
+- **Default**: `undefined`
+- **Descripción**: Texto de la acción (derecha)
+- **Tipografía**: Paragraph/XXSmall (10px Regular)
+- **Ejemplos**: "Clear", "Reset", "Manage"
+
+#### `showAction`
+- **Tipo**: `boolean`
+- **Default**: `false`
+- **Descripción**: Si se debe mostrar la acción
+
+#### `onActionClick`
+- **Tipo**: `(event: React.MouseEvent<HTMLDivElement>) => void`
+- **Default**: `undefined`
+- **Descripción**: Callback ejecutado al hacer click en la acción
+
+#### `className`
+- **Tipo**: `string`
+- **Default**: `''`
+- **Descripción**: Clases CSS adicionales para personalización
+
+---
+
+## Ejemplos
+
+### Ejemplo 1: Información de Usuario
+
+```tsx
+<DropdownItemHeading
+  label="John Doe"
+  description="john@example.com"
+  showDescription={true}
+  iconType="cog"
+  showIcon={true}
+  actionLabel="Logout"
+  showAction={true}
+  onActionClick={() => {
+    console.log('User logged out');
+    // Handle logout logic
+  }}
+/>
+```
+
+### Ejemplo 2: Configuración Rápida
+
+```tsx
+<DropdownItemHeading
+  label="Preferences"
+  description="Customize your experience"
+  showDescription={true}
+  iconType="cog"
+  showIcon={true}
+  actionLabel="Reset"
+  showAction={true}
+  onActionClick={handleResetPreferences}
+/>
+```
+
+### Ejemplo 3: Solo Label
+
+```tsx
+<DropdownItemHeading
+  label="Quick Actions"
+  showDescription={false}
+  iconType="cog"
+  showIcon={true}
+/>
+```
+
+### Ejemplo 4: Sin Icono
+
+```tsx
+<DropdownItemHeading
+  label="Recent Searches"
+  description="Last 5 searches"
+  showDescription={true}
+  iconType={null}
+  showIcon={false}
+  actionLabel="Clear"
+  showAction={true}
+  onActionClick={handleClearSearches}
+/>
+```
+
+### Ejemplo 5: Icono Personalizado
+
+```tsx
+import UserIcon from '@/assets/icons/user.svg';
+import { DropdownItemHeading } from '@/components/DropdownItemHeading';
+
+<DropdownItemHeading
+  label="Profile"
+  description="user@example.com"
+  showDescription={true}
+  iconType="custom"
+  icon={<UserIcon className="w-4 h-4" />}
+  showIcon={true}
+  actionLabel="Edit"
+  showAction={true}
+  onActionClick={handleEditProfile}
+/>
+```
+
+### Ejemplo 6: En Contexto de Dropdown
+
+```tsx
+<Dropdown items={[
+  {
+    isHeading: true,
+    children: (
+      <DropdownItemHeading
+        label="My Account"
+        description="user@example.com"
+        iconType="cog"
+        actionLabel="Logout"
+        showAction={true}
+        onActionClick={handleLogout}
+      />
+    ),
+  },
+  { isDivider: true },
+  { children: 'Settings', icon: <SettingsIcon /> },
+  { children: 'Help', icon: <HelpIcon /> },
+]} />
+```
+
+---
+
+## Guía de Componentes Relacionados
+
+### Dropdown
+El componente padre que utiliza `DropdownItemHeading` como encabezado de menú.
+
+```tsx
+import { Dropdown, DropdownItemHeading } from '@/components';
+
+<Dropdown items={[
+  {
+    isHeading: true,
+    children: <DropdownItemHeading label="Account" description="user@example.com" />,
+  },
+]} />
+```
+
+### Button
+Componente de botón principal del sistema. Usado en acciones secundarias.
+
+### Badge
+Para mostrar notificaciones o estados junto a la información.
+
+---
+
+## Mejores Prácticas
+
+### 1. Mantén Labels Concisos
+```tsx
+// ✅ Bien
+<DropdownItemHeading label="My Account" />
+
+// ❌ Evitar
+<DropdownItemHeading label="Your Current Account Information and Settings" />
+```
+
+### 2. Proporciona Descripción Contextual
+```tsx
+// ✅ Bien
+<DropdownItemHeading
+  label="Settings"
+  description="Manage your preferences"
+/>
+
+// ❌ Evitar
+<DropdownItemHeading
+  label="Settings"
+  description="This is a menu item"
+/>
+```
+
+### 3. Usa Acciones Claras
+```tsx
+// ✅ Bien
+actionLabel="Clear"
+actionLabel="Reset"
+actionLabel="Edit"
+
+// ❌ Evitar
+actionLabel="Go"
+actionLabel="Do Something"
+```
+
+### 4. Maneja Errores en Callbacks
+
+```tsx
+<DropdownItemHeading
+  actionLabel="Delete"
+  onActionClick={async (e) => {
+    try {
+      await deleteItem();
+      console.log('Item deleted');
+    } catch (error) {
+      console.error('Delete failed:', error);
+    }
+  }}
+/>
+```
+
+### 5. Respeta la Jerarquía Visual
+
+```tsx
+// ✅ Bien: Información relevante en descripción
+<DropdownItemHeading
+  label="Documents"
+  description="3 items, 5.2 MB"
+  showDescription={true}
+/>
+
+// ❌ Evitar: Información no importante
+<DropdownItemHeading
+  label="Documents"
+  description="This is a folder location"
+  showDescription={true}
+/>
+```
+
+### 6. Gestiona Textos Largos
+
+```tsx
+// Para textos muy largos, considera truncar en el parent
+<div className="max-w-xs">
+  <DropdownItemHeading
+    label="Very Long Label That Might Overflow"
+    description="Truncated with ellipsis"
+  />
+</div>
+```
+
+---
+
+## Dark Mode
+
+El componente tiene soporte completo para dark mode con la estrategia `class` de Tailwind.
+
+### Colores en Dark Mode
+
+```css
+/* Label */
+.dark .dropdown-item-heading {
+  color: #bfe2fe; /* dark-content-inverse */
+}
+
+/* Description & Action */
+.dark .dropdown-item-description,
+.dark .dropdown-item-action {
+  color: #93d1fd; /* dark-border-inverse */
+}
+
+/* Icon */
+.dark .dropdown-item-icon {
+  color: #bfe2fe; /* dark-content-inverse */
+}
+```
+
+### Activar Dark Mode
+
+```tsx
+// En el elemento raíz de tu aplicación
+<div className="dark">
+  <DropdownItemHeading label="Dark mode enabled" />
+</div>
+```
+
+---
+
+## Accesibilidad
+
+### ARIA
+
+El componente usa etiquetas semánticas y atributos ARIA:
+
+```tsx
+// Acción con keyboard support
+<div
+  role="button"
+  tabIndex={0}
+  onClick={onActionClick}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      onActionClick?.(e as any);
+    }
+  }}
+>
+  {actionLabel}
+</div>
+```
+
+### Keyboard Navigation
+
+- **Tab**: Navega a la acción (si está visible)
+- **Enter / Space**: Activa la acción
+- **Escape**: Cierra el dropdown parent (manejo en Dropdown)
+
+### Screen Readers
+
+```tsx
+// Íconos son hidden para screen readers
+<svg className="w-4 h-4" aria-hidden="true">
+  {/* ... */}
+</svg>
+
+// Acciones tienen soporte de keyboard
+<div role="button" tabIndex={0}>
+  Clear
+</div>
+```
+
+### Colores y Contraste
+
+- **Light Mode**: WCAG AAA compliant
+- **Dark Mode**: WCAG AAA compliant
+- Ratio de contraste mínimo: 4.5:1 para texto normal
+- Ratio de contraste mínimo: 3:1 para texto grande
+
+---
+
+## Especificaciones de Figma
+
+**Figma Node**: `6135:32539`
+**Figma File**: [Siesa UI Kit - DropdownItemHeading](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6135-32539)
+
+### Componentes Relacionados en Figma
+
+- **Dropdown Item**: `6135:32529`
+- **Dropdown**: `6135:31234`
+- **Button**: `4001:17240`
+
+---
+
+## Troubleshooting
+
+### El texto se corta sin mostrar ellipsis
+
+Asegúrate de que el contenedor padre tenga un ancho definido:
+
+```tsx
+// ✅ Bien
+<div className="w-56">
+  <DropdownItemHeading label="Long label" />
+</div>
+
+// ❌ Evitar
+<DropdownItemHeading label="Long label" />
+```
+
+### El icono no se muestra en dark mode
+
+Verifica que el icono heredar colores correctamente:
+
+```tsx
+// ✅ Bien
+<MyIcon className="text-primary-custom-600 dark:text-dark-content-inverse" />
+
+// ❌ Evitar
+<MyIcon style={{ color: '#0e79fd' }} />
+```
+
+### La acción no responde al click
+
+Asegúrate de proporcionar el callback:
+
+```tsx
+<DropdownItemHeading
+  showAction={true}
+  actionLabel="Clear"
+  onActionClick={(e) => {
+    console.log('Action clicked');
+    // Handle action
+  }}
+/>
+```
+
+---
+
+## Referencia de Documentación del Sistema
+
+- [Sistema de Colores](../../../docs/colors.md)
+- [Sistema de Tipografía](../../../docs/typography.md)
+- [Sistema de Espaciado](../../../docs/spacing.md)
+- [Sistema de Sombras](../../../docs/shadows.md)
+
+---
+
+## Cambios Recientes
+
+### v1.0.0 (Inicial)
+- ✨ Componente inicial creado
+- ✅ Soporte completo para dark mode
+- ✅ Props opcionales para mostrar/ocultar elementos
+- ✅ Callback de acción
+- ✅ Typografía del sistema
+- ✅ Accesibilidad mejorada
+
+---
+
+## Licencia
+
+Part of Siesa UI Kit - Todos los derechos reservados © Siesa 2024

package/src/components/DropdownItemHeading/icons.tsx

@@ -0,0 +1,125 @@
+/**
+ * Iconos para el componente DropdownItemHeading
+ * Usando heroicons-micro según especificaciones de Figma
+ * 
+ * Los iconos se pueden pasar como strings al componente:
+ * - 'cog-6-tooth': Icono de engranaje
+ * - 'check': Icono de check
+ * - 'x': Icono de cerrar
+ * - 'chevron-down': Icono de chevron hacia abajo
+ * 
+ * @see DropdownItemHeading.tsx para ver cómo se usan
+ */
+
+import React from 'react';
+
+interface IconProps {
+  className?: string;
+}
+
+/**
+ * Icono Cog (heroicons-micro/cog-6-tooth)
+ * Usado como icono por defecto en DropdownItemHeading
+ * Tamaño: 16x16px
+ */
+export const CogIcon = ({ className = 'w-4 h-4' }: IconProps) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 16 16"
+    fill="currentColor"
+    className={className}
+  >
+    <path
+      fillRule="evenodd"
+      d="M6.455 1.45A.5.5 0 0 1 6.952 1h2.096a.5.5 0 0 1 .497.45l.186 1.858a4.996 4.996 0 0 1 1.466.848l1.703-.769a.5.5 0 0 1 .639.206l1.047 1.814a.5.5 0 0 1-.14.656l-1.517 1.09a5.026 5.026 0 0 1 0 1.694l1.516 1.09a.5.5 0 0 1 .141.656l-1.047 1.814a.5.5 0 0 1-.639.206l-1.703-.768c-.433.36-.928.649-1.466.847l-.186 1.858a.5.5 0 0 1-.497.45H6.952a.5.5 0 0 1-.497-.45l-.186-1.858a4.993 4.993 0 0 1-1.466-.848l-1.703.769a.5.5 0 0 1-.639-.206l-1.047-1.814a.5.5 0 0 1 .14-.656l1.517-1.09a5.033 5.033 0 0 1 0-1.694l-1.516-1.09a.5.5 0 0 1-.141-.656L2.461 3.39a.5.5 0 0 1 .639-.206l1.703.768c.433-.36.928-.649 1.466-.847l.186-1.858ZM8 11a3 3 0 1 0 0-6 3 3 0 0 0 0 6Z"
+      clipRule="evenodd"
+    />
+  </svg>
+);
+
+/**
+ * Icono Check (heroicons-micro/check)
+ */
+export const CheckIcon = ({ className = 'w-4 h-4' }: IconProps) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 16 16"
+    fill="currentColor"
+    className={className}
+  >
+    <path
+      fillRule="evenodd"
+      d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 1 1-1.06-1.06L12.69 4.22a.75.75 0 0 1 1.06 0Z"
+      clipRule="evenodd"
+    />
+    <path
+      fillRule="evenodd"
+      d="M2.22 9.28a.75.75 0 0 0 0 1.06l2.5 2.5a.75.75 0 1 0 1.06-1.06l-2.5-2.5a.75.75 0 0 0-1.06 0Z"
+      clipRule="evenodd"
+    />
+  </svg>
+);
+
+/**
+ * Icono X (heroicons-micro/x-mark)
+ */
+export const XIcon = ({ className = 'w-4 h-4' }: IconProps) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 16 16"
+    fill="currentColor"
+    className={className}
+  >
+    <path d="M5.28 4.22a.75.75 0 0 0-1.06 1.06L6.94 8l-2.72 2.72a.75.75 0 1 0 1.06 1.06L8 9.06l2.72 2.72a.75.75 0 1 0 1.06-1.06L9.06 8l2.72-2.72a.75.75 0 0 0-1.06-1.06L8 6.94 5.28 4.22Z" />
+  </svg>
+);
+
+/**
+ * Icono ChevronDown (heroicons-micro/chevron-down)
+ */
+export const ChevronDownIcon = ({ className = 'w-4 h-4' }: IconProps) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 16 16"
+    fill="currentColor"
+    className={className}
+  >
+    <path
+      fillRule="evenodd"
+      d="M4.22 6.22a.75.75 0 0 1 1.06 0L8 8.94l2.72-2.72a.75.75 0 1 1 1.06 1.06l-3.25 3.25a.75.75 0 0 1-1.06 0L4.22 7.28a.75.75 0 0 1 0-1.06Z"
+      clipRule="evenodd"
+    />
+  </svg>
+);
+
+/**
+ * Mapeo de nombres de iconos a componentes
+ * Permite usar strings para referenciar iconos
+ */
+export const iconMap: Record<string, React.FC<IconProps>> = {
+  'cog-6-tooth': CogIcon,
+  'check': CheckIcon,
+  'x': XIcon,
+  'chevron-down': ChevronDownIcon,
+};
+
+/**
+ * Obtener un icono por su nombre
+ * @param iconName - Nombre del icono (ej: 'cog-6-tooth', 'check', 'x', 'chevron-down')
+ * @param className - Clases CSS adicionales
+ * @returns Componente del icono o null si no existe
+ */
+export const getIcon = (
+  iconName: string | null | undefined,
+  className?: string
+): React.ReactNode => {
+  if (!iconName) return null;
+
+  const IconComponent = iconMap[iconName];
+  if (!IconComponent) {
+    console.warn(`Icon "${iconName}" not found in iconMap`);
+    return null;
+  }
+
+  return <IconComponent className={className} />;
+};

package/src/components/DropdownItemHeading/index.ts

@@ -0,0 +1,3 @@
+export { DropdownItemHeading } from './DropdownItemHeading';
+export type { DropdownItemHeadingProps } from './DropdownItemHeading.types';
+export { CogIcon, CheckIcon, XIcon, ChevronDownIcon, getIcon, iconMap } from './icons';