siesa-ui-kit 1.0.1 → 1.0.2

package/src/components/DropdownItemHeading/DropdownItemHeading.types.ts

@@ -0,0 +1,93 @@
+/**
+ * Props del componente DropdownItemHeading
+ *
+ * Especificaciones de Figma: node 6135:32539
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6135-32539&m=dev
+ */
+export interface DropdownItemHeadingProps {
+  /**
+   * Texto del label principal del heading
+   * Tipografía: Label/Small (14px, Bold)
+   * Color: content-primary (#18181b light, #bfe2fe dark)
+   *
+   * @default 'Label'
+   */
+  label?: string;
+
+  /**
+   * Texto de descripción secundaria bajo el label
+   * Tipografía: Paragraph/Tiny (12px, Regular)
+   * Color: content-secondary (#a1a1aa light, #93d1fd dark)
+   *
+   * @default undefined
+   */
+  description?: string;
+
+  /**
+   * Si se debe mostrar la descripción
+   * Cuando es false, solo muestra el label
+   *
+   * @default true
+   */
+  showDescription?: boolean;
+
+  /**
+   * Nombre del icono a mostrar (string)
+   * Iconos disponibles:
+   * - `'cog-6-tooth'`: Icono de engranaje (por defecto)
+   * - `'check'`: Icono de check
+   * - `'x'`: Icono de cerrar
+   * - `'chevron-down'`: Icono de chevron hacia abajo
+   *
+   * Tamaño: 16x16px
+   * Color: primary-custom-600 (#0e79fd light, #bfe2fe dark)
+   *
+   * Si no se proporciona, se usa 'cog-6-tooth' por defecto
+   *
+   * @default 'cog-6-tooth'
+   * @see icons.tsx para ver los iconos disponibles
+   */
+  iconName?: string | null;
+
+  /**
+   * Si se debe mostrar el icono en la izquierda
+   *
+   * @default true
+   */
+  showIcon?: boolean;
+
+  /**
+   * Texto de acción a mostrar en la derecha
+   * Tipografía: Paragraph/XXSmall (10px, Regular)
+   * Color: content-secondary (#a1a1aa light, #93d1fd dark)
+   *
+   * Comúnmente usado para "Clear", "Reset", etc.
+   *
+   * @default undefined
+   */
+  actionLabel?: string;
+
+  /**
+   * Si se debe mostrar el action label en la derecha
+   *
+   * @default false
+   */
+  showAction?: boolean;
+
+  /**
+   * Callback ejecutado al hacer click en el action label
+   */
+  onActionClick?: (event: React.MouseEvent<HTMLDivElement>) => void;
+
+  /**
+   * Clases CSS adicionales para personalización
+   *
+   * @default ''
+   */
+  className?: string;
+
+  /**
+   * Atributos HTML adicionales
+   */
+  [key: string]: unknown;
+}

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