siesa-ui-kit 1.0.0 → 1.0.2

package/src/components/DropdownItemHeading/DropdownItemHeading.stories.tsx

@@ -0,0 +1,386 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { DropdownItemHeading } from './DropdownItemHeading';
+
+/**
+ * El componente DropdownItemHeading es un encabezado especializado para menús dropdown.
+ * Muestra un icono, un label principal, descripción opcional y una acción opcional.
+ *
+ * Casos de uso:
+ * - Encabezados de secciones en dropdowns
+ * - Información de usuario con opciones de acción
+ * - Configuraciones rápidas en menús
+ *
+ * **Características:**
+ * - Icono opcional (16x16px) - especifica el nombre del icono como string
+ * - 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
+ */
+const meta: Meta<typeof DropdownItemHeading> = {
+  title: 'Components/DropdownItemHeading',
+  component: DropdownItemHeading,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Encabezado para menús dropdown con icono, label, descripción y acción. Implementa pixel-perfect según Figma node 6135:32539 con soporte completo para dark mode.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    label: {
+      control: 'text',
+      description: 'Texto del label principal (Label/Small - 14px Bold)',
+    },
+    description: {
+      control: 'text',
+      description: 'Texto de descripción secundaria (Paragraph/Tiny - 12px Regular)',
+    },
+    showDescription: {
+      control: 'boolean',
+      description: 'Si se debe mostrar la descripción',
+    },
+    iconName: {
+      control: 'select',
+      options: ['cog-6-tooth', 'check', 'x', 'chevron-down', null],
+      description: 'Nombre del icono a mostrar (nombre de heroicons como string)',
+    },
+    showIcon: {
+      control: 'boolean',
+      description: 'Si se debe mostrar el icono',
+    },
+    showAction: {
+      control: 'boolean',
+      description: 'Si se debe mostrar la acción',
+    },
+    actionLabel: {
+      control: 'text',
+      description: 'Texto de la acción (Paragraph/XXSmall - 10px Regular)',
+    },
+    onActionClick: {
+      action: 'onActionClick',
+      description: 'Callback ejecutado al hacer click en la acción',
+    },
+    className: {
+      control: 'text',
+      description: 'Clases CSS adicionales',
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Ejemplo por defecto con todos los elementos (icono cog-6-tooth)
+ */
+export const Default: Story = {
+  args: {
+    label: 'Label',
+    description: 'Description',
+    showDescription: true,
+    iconName: 'cog-6-tooth',
+    showIcon: true,
+    actionLabel: 'Clear',
+    showAction: true,
+  },
+};
+
+/**
+ * Con icono y label, sin descripción ni acción
+ */
+export const LabelOnly: Story = {
+  args: {
+    label: 'Quick Actions',
+    showDescription: false,
+    iconName: 'cog-6-tooth',
+    showIcon: true,
+    showAction: false,
+  },
+};
+
+/**
+ * Con label y descripción, sin icono ni acción
+ */
+export const WithDescription: Story = {
+  args: {
+    label: 'Settings',
+    description: 'Configure your preferences',
+    showDescription: true,
+    iconName: null,
+    showIcon: false,
+    showAction: false,
+  },
+};
+
+/**
+ * Solo label y descripción con icono (sin acción)
+ */
+export const WithIconAndDescription: Story = {
+  args: {
+    label: 'My Account',
+    description: 'user@example.com',
+    showDescription: true,
+    iconName: 'cog-6-tooth',
+    showIcon: true,
+    showAction: false,
+  },
+};
+
+/**
+ * Con todos los elementos (completo)
+ */
+export const Complete: Story = {
+  args: {
+    label: 'My Account',
+    description: 'user@example.com',
+    showDescription: true,
+    iconName: 'cog-6-tooth',
+    showIcon: true,
+    actionLabel: 'Clear',
+    showAction: true,
+    onActionClick: (e) => {
+      console.log('Action clicked!', e);
+      alert('Clear action triggered!');
+    },
+  },
+};
+
+/**
+ * Variante con label largo
+ */
+export const LongLabel: Story = {
+  args: {
+    label: 'Very Long Label That Might Overflow',
+    description: 'This is a description for the long label',
+    showDescription: true,
+    iconName: 'cog-6-tooth',
+    showIcon: true,
+    actionLabel: 'Clear',
+    showAction: true,
+  },
+};
+
+/**
+ * Variante con descripción largo
+ */
+export const LongDescription: Story = {
+  args: {
+    label: 'Settings',
+    description:
+      'Configure your preferences and settings for the application. This is a very long description that demonstrates text wrapping behavior.',
+    showDescription: true,
+    iconName: 'cog-6-tooth',
+    showIcon: true,
+    actionLabel: 'Reset',
+    showAction: true,
+  },
+};
+
+/**
+ * Sin mostrar icono (showIcon = false)
+ */
+export const NoIcon: Story = {
+  args: {
+    label: 'Menu Item',
+    description: 'Detailed description here',
+    showDescription: true,
+    iconName: 'cog-6-tooth',
+    showIcon: false,
+    actionLabel: 'Action',
+    showAction: true,
+  },
+};
+
+/**
+ * Sin acción (solo visualización)
+ */
+export const NoAction: Story = {
+  args: {
+    label: 'Profile',
+    description: 'user.profile@example.com',
+    showDescription: true,
+    iconName: 'cog-6-tooth',
+    showIcon: true,
+    showAction: false,
+  },
+};
+
+/**
+ * Minimal (solo label)
+ */
+export const Minimal: Story = {
+  args: {
+    label: 'Menu',
+    showDescription: false,
+    iconName: 'cog-6-tooth',
+    showIcon: false,
+    showAction: false,
+  },
+};
+
+/**
+ * Con icono check
+ */
+export const WithCheckIcon: Story = {
+  args: {
+    label: 'Completed',
+    description: 'Task finished successfully',
+    showDescription: true,
+    iconName: 'check',
+    showIcon: true,
+    actionLabel: 'Dismiss',
+    showAction: true,
+  },
+};
+
+/**
+ * Con icono x
+ */
+export const WithXIcon: Story = {
+  args: {
+    label: 'Close',
+    description: 'Click to close',
+    showDescription: true,
+    iconName: 'x',
+    showIcon: true,
+    actionLabel: 'Undo',
+    showAction: true,
+  },
+};
+
+/**
+ * Con icono chevron-down
+ */
+export const WithChevronIcon: Story = {
+  args: {
+    label: 'Expand',
+    description: 'Show more options',
+    showDescription: true,
+    iconName: 'chevron-down',
+    showIcon: true,
+    actionLabel: 'Collapse',
+    showAction: true,
+  },
+};
+
+/**
+ * Sin icono (iconName = null)
+ */
+export const NoIconType: Story = {
+  args: {
+    label: 'Menu Item',
+    description: 'Without icon',
+    showDescription: true,
+    iconName: null,
+    showIcon: true,
+    actionLabel: 'Action',
+    showAction: true,
+  },
+};
+
+/**
+ * Estado disabled (visual - el componente no controla esto)
+ * En un dropdown, la deshabilitación se maneja a nivel del parent
+ */
+export const DisabledState: Story = {
+  args: {
+    label: 'Disabled Item',
+    description: 'This item is not available',
+    showDescription: true,
+    iconName: 'cog-6-tooth',
+    showIcon: true,
+    actionLabel: 'N/A',
+    showAction: true,
+    className: 'opacity-50 pointer-events-none',
+  },
+};
+
+/**
+ * En contexto de dropdown (múltiples items)
+ */
+export const InDropdownContext: Story = {
+  render: () => (
+    <div className="w-full max-w-sm border border-border-primary rounded-lg shadow-lg p-2 bg-bg-primary dark:bg-dark-bg-primary">
+      <DropdownItemHeading
+        label="My Account"
+        description="user@example.com"
+        showDescription={true}
+        iconName="cog-6-tooth"
+        showIcon={true}
+        actionLabel="Clear"
+        showAction={true}
+      />
+      <div className="h-px bg-border-primary dark:bg-dark-border-primary my-2" />
+      <div className="px-4 py-2 text-content-secondary dark:text-dark-content-secondary text-sm">
+        Other items would go here...
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Demostración de dark mode
+ */
+export const DarkModeShowcase: Story = {
+  decorators: [
+    (Story) => (
+      <div className="dark">
+        <div className="bg-dark-bg-primary p-8 rounded-lg">
+          <Story />
+        </div>
+      </div>
+    ),
+  ],
+  args: {
+    label: 'Dark Mode Label',
+    description: 'Dark mode description text',
+    showDescription: true,
+    iconName: 'cog-6-tooth',
+    showIcon: true,
+    actionLabel: 'Clear',
+    showAction: true,
+  },
+};
+
+/**
+ * Comparación lado a lado (Light vs Dark)
+ */
+export const LightVsDark: Story = {
+  render: () => (
+    <div className="flex gap-8 p-8">
+      {/* Light Mode */}
+      <div className="bg-bg-primary p-4 rounded-lg border border-border-primary">
+        <p className="text-content-secondary text-sm mb-4 font-semibold">Light Mode</p>
+        <DropdownItemHeading
+          label="My Account"
+          description="user@example.com"
+          showDescription={true}
+          iconName="cog-6-tooth"
+          showIcon={true}
+          actionLabel="Clear"
+          showAction={true}
+        />
+      </div>
+
+      {/* Dark Mode */}
+      <div className="dark bg-dark-bg-primary p-4 rounded-lg border border-dark-border-primary">
+        <p className="text-dark-content-secondary text-sm mb-4 font-semibold">Dark Mode</p>
+        <DropdownItemHeading
+          label="My Account"
+          description="user@example.com"
+          showDescription={true}
+          iconName="cog-6-tooth"
+          showIcon={true}
+          actionLabel="Clear"
+          showAction={true}
+        />
+      </div>
+    </div>
+  ),
+};

package/src/components/DropdownItemHeading/DropdownItemHeading.tsx

@@ -0,0 +1,216 @@
+import React from 'react';
+import type { DropdownItemHeadingProps } from './DropdownItemHeading.types';
+import { getIcon } from './icons';
+
+/**
+ * Componente DropdownItemHeading del sistema de diseño Siesa
+ *
+ * Implementación pixel-perfect basada en Figma (node 6135:32539)
+ * para encabezados en menús dropdown con icono, label, descripción y acción.
+ *
+ * **Estructura:**
+ * - Icon Wrapper: Opcional, icono de 16x16px
+ * - Content Wrapper: Label + Description (flexible)
+ * - Action Wrapper: Opcional, texto de acción en la derecha
+ *
+ * **Dimensiones:**
+ * - Altura flexible (contenido vertical)
+ * - Width mínimo: 224px
+ * - Padding: 8px vertical, 16px horizontal
+ * - Border radius: 8px (rounded-lg)
+ *
+ * **Tipografía:**
+ * - Label: Label/Small (14px Bold) - content-primary
+ * - Description: Paragraph/Tiny (12px Regular) - content-secondary
+ * - Action: Paragraph/XXSmall (10px Regular) - content-secondary
+ *
+ * **Dark Mode:**
+ * - Label: #18181b (light) → #bfe2fe (dark)
+ * - Description: #a1a1aa (light) → #93d1fd (dark)
+ * - Icon: #0e79fd (light) → #bfe2fe (dark)
+ * - Action: #a1a1aa (light) → #93d1fd (dark)
+ *
+ * **Estados:**
+ * - Default: Sin hover/focus
+ * - Hover: Overlay sutil (managed by parent Dropdown)
+ * - Disabled: Opacity 50% (managed by parent Dropdown)
+ *
+ * **Especificaciones de Figma:**
+ * - Gap entre elementos: 12px
+ * - Gap entre label y description: 2px
+ * - Rounded: 8px (rounded-lg)
+ *
+ * @see docs/colors.md - Sistema de colores
+ * @see docs/typography.md - Sistema tipográfico (Label/Small, Paragraph/Tiny)
+ * @see docs/spacing.md - Sistema de espaciado
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6135-32539 - Diseño Figma
+ *
+ * @example
+ * ```tsx
+ * // Con icono, label, descripción y acción
+ * <DropdownItemHeading
+ *   label="Settings"
+ *   description="Configure your preferences"
+ *   showDescription={true}
+ *   icon={<SettingsIcon />}
+ *   showIcon={true}
+ *   actionLabel="Clear"
+ *   showAction={true}
+ *   onActionClick={handleClear}
+ * />
+ *
+ * // Solo label y descripción (sin icono ni acción)
+ * <DropdownItemHeading
+ *   label="My Account"
+ *   description="user@example.com"
+ *   showDescription={true}
+ * />
+ *
+ * // Solo label
+ * <DropdownItemHeading
+ *   label="Quick Actions"
+ *   showDescription={false}
+ * />
+ * ```
+ */
+export const DropdownItemHeading: React.FC<DropdownItemHeadingProps> = ({
+  label = 'Label',
+  description,
+  showDescription = true,
+  iconName = 'cog-6-tooth',
+  showIcon = true,
+  actionLabel,
+  showAction = false,
+  onActionClick,
+  className = '',
+  ...rest
+}) => {
+
+  return (
+    <div
+      className={`
+        flex
+        gap-3
+        items-center
+        px-4
+        py-2
+        rounded-lg
+        w-56
+        ${className}
+      `}
+      data-testid="dropdown-item-heading"
+      {...rest}
+    >
+      {/* ===== ICON WRAPPER ===== */}
+      {showIcon && iconName && (
+        <div
+          className="
+            flex
+            items-center
+            justify-center
+            shrink-0
+            w-4
+            h-4
+          "
+          data-testid="icon-wrapper"
+        >
+          <div className="text-primary-custom-600 dark:text-dark-content-inverse">
+            {getIcon(iconName, 'w-4 h-4')}
+          </div>
+        </div>
+      )}
+
+      {/* ===== CONTENT WRAPPER ===== */}
+      <div
+        className="
+          flex
+          flex-1
+          flex-col
+          gap-0.5
+          items-start
+          justify-center
+          min-w-0
+        "
+        data-testid="content-wrapper"
+      >
+        {/* Label */}
+        <p
+          className="
+            font-bold
+            text-sm
+            leading-5
+            text-content-primary
+            dark:text-dark-content-inverse
+            whitespace-nowrap
+            overflow-hidden
+            text-ellipsis
+          "
+          data-testid="label"
+        >
+          {label}
+        </p>
+
+        {/* Description */}
+        {showDescription && description && (
+          <p
+            className="
+              font-normal
+              text-xs
+              leading-4
+              text-content-secondary
+              dark:text-dark-border-inverse
+              w-full
+              whitespace-pre-wrap
+              overflow-hidden
+              text-ellipsis
+            "
+            data-testid="description"
+          >
+            {description}
+          </p>
+        )}
+      </div>
+
+      {/* ===== ACTION WRAPPER ===== */}
+      {showAction && actionLabel && (
+        <div
+          className="
+            flex
+            items-center
+            justify-center
+            shrink-0
+            cursor-pointer
+            hover:opacity-80
+            transition-opacity
+            duration-150
+          "
+          data-testid="action-wrapper"
+          onClick={onActionClick}
+          role="button"
+          tabIndex={0}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+              onActionClick?.(e as any);
+            }
+          }}
+        >
+          <p
+            className="
+              font-normal
+              text-xs
+              leading-3
+              text-content-secondary
+              dark:text-dark-border-inverse
+              whitespace-nowrap
+            "
+            data-testid="action-label"
+          >
+            {actionLabel}
+          </p>
+        </div>
+      )}
+    </div>
+  );
+};
+
+DropdownItemHeading.displayName = 'DropdownItemHeading';

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;
+}