siesa-ui-kit 1.0.1 → 1.0.2

package/src/components/DropdownItemCollapsible/DropdownItemCollapsible.tsx

@@ -0,0 +1,287 @@
+import React, { useState } from 'react';
+import type {
+  DropdownItemCollapsibleProps,
+  DropdownItemCollapsibleChildProps,
+} from './DropdownItemCollapsible.types';
+import { ChevronDownIcon } from './icons';
+
+/**
+ * Componente DropdownItemCollapsible del sistema de diseño Siesa
+ *
+ * Item colapsable para uso dentro de Dropdowns que permite agrupar
+ * items relacionados en secciones expandibles.
+ *
+ * **Características:**
+ * - Soporte completo para expandir/colapsar
+ * - Iconos personalizables en header y children
+ * - Items anidados indentados automáticamente
+ * - Dark mode completo con inversión de colores
+ * - Estados: default, hover, active, disabled
+ * - Focus rings adaptativos
+ * - Animación suave de rotación del chevron
+ *
+ * **Estados visuales:**
+ * - `collapsed`: Muestra solo el header con chevron apuntando down
+ * - `expanded`: Muestra header y lista de items anidados
+ * - `disabled`: Opacidad 50%, sin interacción
+ * - `hover`: Fondo de hover sutil, color primario del icono
+ * - `active`: Item anidado seleccionado con fondo custom-primary
+ *
+ * **Espaciado según Figma:**
+ * - Header padding: px-4 py-2 (16px horizontal, 8px vertical)
+ * - Item anidado padding: pl-6 pr-4 py-2 (24px left, 16px right, 8px vertical)
+ * - Gap entre elementos: gap-3 (12px)
+ * - Gap interno (icon + text): gap-3 (12px)
+ * - Indent entre niveles: 8px adicional por nivel
+ * - Divisor: borde top de 1px con spacing-0.5 (2px) arriba
+ * - Sección heading: pt-3 pb-1 px-0 (12px top, 4px bottom, sin horizontal)
+ *
+ * **Tipografía:**
+ * - Header: Paragraph/Small (14px, Regular, line-height 20px) - text-content-primary
+ * - Items anidados: Paragraph/Small (14px, Regular, line-height 20px) - text-content-primary
+ * - Heading: Paragraph/Tiny (12px, Regular, line-height 16px) - text-content-tertiary
+ *
+ * **Colores (Light Mode):**
+ * - Header text: content-primary (#18181b)
+ * - Header icon: content-secondary (#a1a1aa)
+ * - Header hover: bg-background-custom-primary (#dbeefe)
+ * - Header text hover: content-custom-primary (#0e79fd)
+ * - Item text: content-primary (#18181b)
+ * - Item hover: bg-transparent (sin fondo)
+ * - Divider: border-border-primary (#e4e4e7)
+ * - Heading text: content-tertiary (#71717a)
+ *
+ * **Colores (Dark Mode):**
+ * - Header text: content-primary/dark (#fafafa)
+ * - Header icon: content-secondary/dark (#a1a1aa)
+ * - Header hover: bg-background-custom-primary/dark (#0e5ab0)
+ * - Header text hover: content-custom-primary/dark (#bfe2fe)
+ * - Item text: content-primary/dark (#fafafa)
+ * - Divider: border-border-primary/dark (#3f3f46)
+ * - Heading text: content-tertiary/dark (#a1a1aa)
+ *
+ * **Border radius:**
+ * - Todos los items: rounded-lg (8px)
+ *
+ * **Sombras:**
+ * - Ninguna (usado dentro de dropdowns)
+ *
+ * @see docs/colors.md - Sistema de colores
+ * @see docs/typography.md - Sistema tipográfico
+ * @see docs/spacing.md - Sistema de espaciado
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6135-34374
+ *
+ * @example
+ * ```tsx
+ * // Item colapsable simple
+ * <DropdownItemCollapsible
+ *   label="Users"
+ *   icon={<UserIcon />}
+ *   children={[
+ *     { label: "Active Users", icon: <CheckIcon /> },
+ *     { label: "Inactive Users", icon: <CloseIcon /> },
+ *   ]}
+ * />
+ *
+ * // Con encabezado de sección
+ * <DropdownItemCollapsible
+ *   label="Customers"
+ *   icon={<BuildingIcon />}
+ *   showHeading={true}
+ *   headingLabel="SECTION 1"
+ *   children={[...]}
+ * />
+ *
+ * // Item no colapsable (actúa como botón normal)
+ * <DropdownItemCollapsible
+ *   label="Single Item"
+ *   icon={<StarIcon />}
+ *   isCollapsible={false}
+ *   onClick={() => console.log('clicked')}
+ * />
+ * ```
+ */
+export const DropdownItemCollapsible: React.FC<DropdownItemCollapsibleProps> = ({
+  label,
+  icon,
+  children = [],
+  defaultOpen = false,
+  disabled = false,
+  onOpenChange,
+  onClick,
+  isCollapsible = children.length > 0,
+  showHeading = false,
+  headingLabel,
+  showDivider = true,
+  className = '',
+}) => {
+  const [isOpen, setIsOpen] = useState(defaultOpen);
+
+  const handleToggle = () => {
+    if (disabled || !isCollapsible) return;
+
+    const newOpen = !isOpen;
+    setIsOpen(newOpen);
+    onOpenChange?.(newOpen);
+  };
+
+  const handleHeaderClick = (e: React.MouseEvent<HTMLButtonElement>) => {
+    if (disabled) return;
+
+    if (isCollapsible) {
+      handleToggle();
+    } else {
+      onClick?.(e);
+    }
+  };
+
+  const handleChildClick = (child: DropdownItemCollapsibleChildProps) => (
+    e: React.MouseEvent<HTMLDivElement>,
+  ) => {
+    if (child.disabled) return;
+    child.onClick?.(e);
+  };
+
+  return (
+    <div className={`flex flex-col gap-0.5 w-full ${className}`}>
+      {/* Section Heading */}
+      {showHeading && headingLabel && (
+        <div className="flex flex-col gap-0 items-start pb-1 pt-3 px-0 w-full">
+          <p className="font-['Inter:Regular',sans-serif] font-normal leading-4 not-italic text-xs text-content-tertiary dark:text-content-tertiary w-full">
+            {headingLabel}
+          </p>
+        </div>
+      )}
+
+      {/* Header Button */}
+      <button
+        onClick={handleHeaderClick}
+        disabled={disabled}
+        className={[
+          // Base
+          'flex items-center gap-3 px-4 py-2 w-full',
+          'rounded-lg cursor-pointer',
+          'transition-all duration-150',
+
+          // Colores y estados (Light Mode)
+          !disabled && 'text-content-primary',
+          !disabled && 'hover:bg-primary-custom-100',
+          !disabled && 'hover:text-primary-custom-600',
+
+          // Dark Mode
+          !disabled && 'dark:text-content-primary',
+          !disabled && 'dark:hover:bg-dark-bg-custom',
+          !disabled && 'dark:hover:text-dark-content-custom',
+
+          // Focus ring
+          !disabled && 'focus:outline-none',
+          !disabled && 'focus:ring-2',
+          !disabled && 'focus:ring-offset-2',
+          !disabled && 'focus:ring-primary-custom-400',
+          !disabled && 'focus:ring-offset-bg-primary',
+          !disabled && 'dark:focus:ring-offset-dark-bg-primary',
+
+          // Disabled
+          disabled && 'opacity-50',
+          disabled && 'cursor-not-allowed',
+        ]
+          .filter(Boolean)
+          .join(' ')}
+        aria-expanded={isOpen && isCollapsible}
+        aria-disabled={disabled}
+      >
+        {/* Icon Wrapper */}
+        {icon && (
+          <div className="flex items-center justify-center w-4 h-4 shrink-0 text-content-secondary dark:text-content-secondary">
+            {icon}
+          </div>
+        )}
+
+        {/* Content Wrapper */}
+        <div className="flex flex-1 flex-col items-start justify-center gap-0.5">
+          <p className="font-['Inter:Regular',sans-serif] font-normal leading-5 not-italic text-sm text-left">
+            {label}
+          </p>
+        </div>
+
+        {/* Chevron (solo visible si es colapsable) */}
+        {isCollapsible && (
+          <div
+            className={[
+              'flex items-center justify-center w-4 h-4 shrink-0',
+              'text-content-secondary dark:text-content-secondary',
+              'transition-transform duration-200',
+              isOpen ? 'rotate-180' : 'rotate-0',
+            ].join(' ')}
+          >
+            <ChevronDownIcon className="w-4 h-4" />
+          </div>
+        )}
+      </button>
+
+      {/* Divider */}
+      {showDivider && <div className="w-full h-px bg-border-primary dark:bg-dark-border-primary" />}
+
+      {/* Children Container (expanded) */}
+      {isOpen && isCollapsible && children.length > 0 && (
+        <div className="flex flex-col gap-0.5 w-full py-2 px-0">
+          {children.map((child, index) => (
+            <div
+              key={index}
+              onClick={handleChildClick(child)}
+              className={[
+                // Base
+                'flex gap-3 items-center pl-6 pr-4 py-2 w-full',
+                'rounded-lg cursor-pointer',
+                'transition-all duration-150',
+
+                // Colores y estados (Light Mode)
+                !child.disabled && 'text-content-primary',
+                !child.disabled && 'hover:bg-primary-custom-100',
+                !child.disabled && 'hover:text-primary-custom-600',
+
+                // Dark Mode
+                !child.disabled && 'dark:text-content-primary',
+                !child.disabled && 'dark:hover:bg-dark-bg-custom',
+                !child.disabled && 'dark:hover:text-dark-content-custom',
+
+                // Focus ring
+                !child.disabled && 'focus:outline-none',
+                !child.disabled && 'focus:ring-2',
+                !child.disabled && 'focus:ring-offset-2',
+                !child.disabled && 'focus:ring-primary-custom-400',
+                !child.disabled && 'focus:ring-offset-bg-primary',
+                !child.disabled && 'dark:focus:ring-offset-dark-bg-primary',
+
+                // Disabled
+                child.disabled && 'opacity-50',
+                child.disabled && 'cursor-not-allowed',
+
+                // Custom classes
+                child.className,
+              ]
+                .filter(Boolean)
+                .join(' ')}
+            >
+              {/* Child Icon Wrapper */}
+              {child.icon && (
+                <div className="flex items-center justify-center w-4 h-4 shrink-0 text-content-secondary dark:text-content-secondary">
+                  {child.icon}
+                </div>
+              )}
+
+              {/* Child Content Wrapper */}
+              <div className="flex flex-1 flex-col items-start justify-center gap-0.5">
+                <p className="font-['Inter:Regular',sans-serif] font-normal leading-5 not-italic text-sm text-left">
+                  {child.label}
+                </p>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default DropdownItemCollapsible;

package/src/components/DropdownItemCollapsible/DropdownItemCollapsible.types.ts

@@ -0,0 +1,111 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Props del componente DropdownItemCollapsible
+ *
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6135-34374
+ */
+export interface DropdownItemCollapsibleProps {
+  /**
+   * Texto o contenido principal del item
+   * Ejemplo: "Users", "Customers", "Departments"
+   */
+  label: string;
+
+  /**
+   * Icono a mostrar antes del texto (izquierda)
+   * Recomendado: 16x16px
+   */
+  icon?: ReactNode;
+
+  /**
+   * Items anidados que se muestran cuando el item está expandido
+   * Cada item anidado tiene label e icono opcional
+   */
+  children?: DropdownItemCollapsibleChildProps[];
+
+  /**
+   * Si el item está expandido inicialmente
+   * @default false
+   */
+  defaultOpen?: boolean;
+
+  /**
+   * Si el item está deshabilitado
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Callback cuando el item se expande/contrae
+   * @param open - nuevo estado de expansión
+   */
+  onOpenChange?: (open: boolean) => void;
+
+  /**
+   * Callback cuando se hace click en el item (sin expandir)
+   * Útil para items que actúan como botones normales
+   */
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+
+  /**
+   * Si el item debería actuar como un botón normal sin colapsable
+   * @default false
+   */
+  isCollapsible?: boolean;
+
+  /**
+   * Si mostrar un encabezado de sección antes del item
+   * @default false
+   */
+  showHeading?: boolean;
+
+  /**
+   * Texto del encabezado de sección
+   * Se usa cuando showHeading es true
+   * Ejemplo: "Section Title"
+   */
+  headingLabel?: string;
+
+  /**
+   * Si mostrar divisor después del item/encabezado
+   * @default true
+   */
+  showDivider?: boolean;
+
+  /**
+   * Clases CSS adicionales
+   */
+  className?: string;
+}
+
+/**
+ * Props de items anidados dentro del colapsable
+ */
+export interface DropdownItemCollapsibleChildProps {
+  /**
+   * Texto del item anidado
+   */
+  label: string;
+
+  /**
+   * Icono opcional del item anidado
+   */
+  icon?: ReactNode;
+
+  /**
+   * Si el item anidado está deshabilitado
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Callback cuando se hace click en el item anidado
+   */
+  onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
+
+  /**
+   * Clases CSS adicionales
+   */
+  className?: string;
+}

package/src/components/DropdownItemCollapsible/README.md

@@ -0,0 +1,264 @@
+# DropdownItemCollapsible
+
+Item colapsable para uso dentro de Dropdowns que permite agrupar items relacionados en secciones expandibles.
+
+## 🎯 Propósito
+
+El componente `DropdownItemCollapsible` es un item especializado de dropdown que:
+
+- Agrupa items relacionados en secciones expandibles
+- Muestra/oculta items anidados con animación suave
+- Mantiene jerarquía visual clara con indentación
+- Soporta iconos personalizables
+- Proporciona feedback visual completo (hover, focus, active, disabled)
+- Implementa dark mode completo
+
+## 📋 Uso
+
+### Básico
+
+```tsx
+import { DropdownItemCollapsible } from '@/components/DropdownItemCollapsible';
+import { UserIcon } from '@/components/DropdownItemCollapsible/icons';
+
+<DropdownItemCollapsible
+  label="Users"
+  icon={<UserIcon />}
+  children={[
+    { label: 'Active Users' },
+    { label: 'Inactive Users' },
+  ]}
+/>
+```
+
+### Con Encabezado de Sección
+
+```tsx
+<DropdownItemCollapsible
+  label="Customers"
+  icon={<CustomerIcon />}
+  showHeading={true}
+  headingLabel="SECTION 1"
+  children={[
+    { label: 'Enterprise' },
+    { label: 'SMB' },
+    { label: 'Startup' },
+  ]}
+  showDivider={true}
+/>
+```
+
+### Expandido por Defecto
+
+```tsx
+<DropdownItemCollapsible
+  label="Departments"
+  icon={<DepartmentIcon />}
+  defaultOpen={true}
+  children={[
+    { label: 'Sales' },
+    { label: 'Marketing' },
+    { label: 'Engineering' },
+  ]}
+/>
+```
+
+### Item Simple (No Colapsable)
+
+```tsx
+<DropdownItemCollapsible
+  label="Settings"
+  icon={<SettingsIcon />}
+  isCollapsible={false}
+  onClick={() => console.log('Settings clicked')}
+/>
+```
+
+### Con Callbacks
+
+```tsx
+<DropdownItemCollapsible
+  label="Actions"
+  children={[
+    {
+      label: 'Edit',
+      onClick: (e) => console.log('Edit clicked'),
+    },
+    {
+      label: 'Delete',
+      onClick: (e) => console.log('Delete clicked'),
+    },
+  ]}
+  onOpenChange={(open) => console.log('Toggle:', open)}
+/>
+```
+
+## 🎨 Props
+
+### Interfaz `DropdownItemCollapsibleProps`
+
+| Prop | Tipo | Defecto | Descripción |
+|------|------|---------|-------------|
+| `label` | `string` | **Requerido** | Texto principal del item |
+| `icon` | `ReactNode` | `undefined` | Icono a mostrar antes del texto (16x16px recomendado) |
+| `children` | `DropdownItemCollapsibleChildProps[]` | `[]` | Items anidados cuando está expandido |
+| `defaultOpen` | `boolean` | `false` | Si el item está expandido inicialmente |
+| `disabled` | `boolean` | `false` | Si el item está deshabilitado |
+| `onOpenChange` | `(open: boolean) => void` | `undefined` | Callback cuando se expande/contrae |
+| `onClick` | `(e: React.MouseEvent) => void` | `undefined` | Callback cuando se hace click (para items no colapsables) |
+| `isCollapsible` | `boolean` | `true si children.length > 0` | Si el item puede expanderse/contraerse |
+| `showHeading` | `boolean` | `false` | Si mostrar encabezado de sección |
+| `headingLabel` | `string` | `undefined` | Texto del encabezado (se usa si showHeading es true) |
+| `showDivider` | `boolean` | `true` | Si mostrar divisor después del item |
+| `className` | `string` | `''` | Clases CSS adicionales |
+
+### Interfaz `DropdownItemCollapsibleChildProps`
+
+| Prop | Tipo | Defecto | Descripción |
+|------|------|---------|-------------|
+| `label` | `string` | **Requerido** | Texto del item anidado |
+| `icon` | `ReactNode` | `undefined` | Icono opcional (16x16px recomendado) |
+| `disabled` | `boolean` | `false` | Si el item está deshabilitado |
+| `onClick` | `(e: React.MouseEvent) => void` | `undefined` | Callback cuando se hace click |
+| `className` | `string` | `''` | Clases CSS adicionales |
+
+## 🎯 Estados
+
+### Visual States
+
+- **Default**: Colores base del sistema
+- **Hover**: Fondo `background-custom-primary`, texto `content-custom-primary`
+- **Focus**: Ring de 2px con offset (adaptive dark mode)
+- **Active**: Animación scale-95 para feedback táctil
+- **Disabled**: Opacidad 50%, sin interacción
+
+### Colapsable States
+
+- **Collapsed**: Solo muestra header, chevron apunta down
+- **Expanded**: Muestra header + lista de items anidados
+- **Chevron Animation**: Rotación suave de 180° al expandir/contraer
+
+## 🌓 Dark Mode
+
+El componente soporta dark mode completo:
+
+| Elemento | Light | Dark |
+|----------|-------|------|
+| Header text | `content-primary` | `content-primary/dark` |
+| Header icon | `content-secondary` | `content-secondary/dark` |
+| Header hover | `bg-background-custom-primary` | `bg-background-custom-primary/dark` |
+| Item text | `content-primary` | `content-primary/dark` |
+| Divider | `border-border-primary` | `border-border-primary/dark` |
+| Heading | `content-tertiary` | `content-tertiary/dark` |
+| Focus ring offset | `background-primary` | `background-primary/dark` |
+
+## 📐 Espaciado
+
+Basado en especificaciones de Figma:
+
+```
+┌─────────────────────────────────────┐
+│ Section Heading (pt-3 pb-1)         │
+├─────────────────────────────────────┤
+│ ┌───────────────────────────────┐   │
+│ │ 🎯 Header (px-4 py-2)         │   │ gap-3
+│ └───────────────────────────────┘   │
+├─────────────────────────────────────┤
+│ ┌───────────────────────────────┐   │
+│ │   ├─ Item 1 (pl-6 pr-4 py-2)  │   │ gap-0.5
+│ │   ├─ Item 2                   │   │
+│ │   └─ Item 3                   │   │
+│ └───────────────────────────────┘   │
+├─────────────────────────────────────┤
+│ Divider (h-px, color: border-primary)│
+└─────────────────────────────────────┘
+```
+
+## 🔧 Personalización
+
+### Con Tailwind CSS
+
+```tsx
+<DropdownItemCollapsible
+  label="Custom Styled"
+  className="my-custom-class"
+  children={[
+    {
+      label: "Item",
+      className: "custom-child-class"
+    }
+  ]}
+/>
+```
+
+### Iconos Personalizados
+
+```tsx
+import { MyCustomIcon } from '@/icons';
+
+<DropdownItemCollapsible
+  label="Custom Icon"
+  icon={<MyCustomIcon className="w-4 h-4" />}
+  children={[
+    {
+      label: "Child",
+      icon={<AnotherIcon className="w-4 h-4" />}
+    }
+  ]}
+/>
+```
+
+## 🎬 Transiciones
+
+- **Chevron rotation**: 200ms ease-in-out
+- **Color hover**: 150ms ease-in-out
+- **Scale active**: Inmediato
+
+## ♿ Accesibilidad
+
+- `aria-expanded`: Indica si el item está expandido
+- `aria-disabled`: Indica si el item está deshabilitado
+- Soporte completo para navegación por teclado
+- Focus rings visibles y adaptativos
+- Colores con suficiente contraste (WCAG AA)
+
+## 📚 Integración con Dropdown
+
+Se diseñó para integrar perfectamente dentro del componente Dropdown:
+
+```tsx
+<Dropdown
+  items={[
+    {
+      children: (
+        <DropdownItemCollapsible
+          label="Users"
+          children={[...]}
+        />
+      )
+    }
+  ]}
+/>
+```
+
+## 🔗 Referencias
+
+- **Figma**: [node-id=6135-34374](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6135-34374)
+- **Colors**: [docs/colors.md](../../docs/colors.md)
+- **Typography**: [docs/typography.md](../../docs/typography.md)
+- **Spacing**: [docs/spacing.md](../../docs/spacing.md)
+- **Shadows**: [docs/shadows.md](../../docs/shadows.md)
+
+## 📝 Historial de Cambios
+
+### v1.0.0 (2025-12-23)
+
+- ✅ Componente inicial creado
+- ✅ Soporte completo para expandir/contraer
+- ✅ Dark mode completo
+- ✅ States: hover, focus, active, disabled
+- ✅ Iconos personalizables
+- ✅ Items anidados con indentación
+- ✅ Animaciones suaves
+- ✅ Stories Storybook completas
+- ✅ Accesibilidad (ARIA labels)