siesa-ui-kit 1.0.0 → 1.0.2

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)

package/src/components/DropdownItemCollapsible/icons.tsx

@@ -0,0 +1,57 @@
+import React from 'react';
+
+/**
+ * Icono ChevronDown para el toggle del colapsable
+ * Diseño basado en heroicons-micro/chevron-down
+ * Tamaño: 16x16px
+ *
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6135-34374
+ */
+export const ChevronDownIcon: React.FC<{ className?: string }> = ({ className = '' }) => (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    className={className}
+  >
+    <path
+      d="M4 6L8 10L12 6"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+/**
+ * Icono de usuario placeholder para ejemplos en stories
+ * Tamaño: 16x16px
+ */
+export const UserIcon: React.FC<{ className?: string }> = ({ className = '' }) => (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    className={className}
+  >
+    <path
+      d="M8 8C9.10457 8 10 7.10457 10 6C10 4.89543 9.10457 4 8 4C6.89543 4 6 4.89543 6 6C6 7.10457 6.89543 8 8 8Z"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M4.5 13C4.5 11.3431 6.13401 10 8 10C9.86599 10 11.5 11.3431 11.5 13"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);

package/src/components/DropdownItemCollapsible/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Exportaciones del componente DropdownItemCollapsible
+ *
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6135-34374
+ */
+
+export { DropdownItemCollapsible } from './DropdownItemCollapsible';
+export type {
+  DropdownItemCollapsibleProps,
+  DropdownItemCollapsibleChildProps,
+} from './DropdownItemCollapsible.types';
+export { ChevronDownIcon, UserIcon } from './icons';