siesa-ui-kit 1.0.3 → 1.0.5

package/src/components/Checkbox/Checkbox.types.ts

@@ -0,0 +1,61 @@
+import type { InputHTMLAttributes } from 'react';
+
+/**
+ * Estados visuales del Checkbox
+ */
+export type CheckboxState = 'default' | 'hover' | 'focus' | 'disabled';
+
+/**
+ * Props del componente Checkbox
+ *
+ * Extiende HTMLInputElement con props adicionales específicas del componente.
+ * Excluye 'type' y 'size' que son manejados internamente.
+ */
+export interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'size'> {
+  /**
+   * Etiqueta del checkbox
+   * Tipografía: Label/Small (14px, Bold)
+   */
+  label?: string;
+
+  /**
+   * Descripción debajo del label
+   * Tipografía: Paragraph/Small (14px, Regular)
+   */
+  description?: string;
+
+  /**
+   * Si el checkbox está marcado
+   * @default false
+   */
+  checked?: boolean;
+
+  /**
+   * Si el checkbox está en estado indeterminado (parcialmente seleccionado)
+   * Útil para "select all" cuando solo algunos items están seleccionados
+   * @default false
+   */
+  indeterminate?: boolean;
+
+  /**
+   * Si el checkbox está deshabilitado
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Clases CSS adicionales para el contenedor principal
+   */
+  className?: string;
+
+  /**
+   * ID único para el checkbox
+   * Si no se proporciona, se genera automáticamente
+   */
+  id?: string;
+
+  /**
+   * Callback cuando el estado del checkbox cambia
+   */
+  onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+}

package/src/components/DescriptionList/DescriptionList.stories.tsx

@@ -0,0 +1,250 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { DescriptionList } from './DescriptionList';
+
+/**
+ * DescriptionList - Componente de lista de descripción del sistema de diseño Siesa
+ *
+ * Sistema completo para mostrar pares clave-valor con soporte para:
+ * - **Layout de dos columnas**: Term a la izquierda, Details a la derecha
+ * - **Separador**: Línea inferior sutil entre items
+ * - **Dark mode**: Adaptación completa al tema oscuro
+ * - **Responsive**: Se adapta al contenedor
+ */
+const meta = {
+  title: 'Siesa UI Kit/DescriptionList',
+  component: DescriptionList,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Componente para mostrar información estructurada en formato clave-valor. Ideal para detalles de productos, información de usuarios, datos de eventos, etc.',
+      },
+    },
+    backgrounds: {
+      default: 'light',
+      values: [
+        { name: 'light', value: '#ffffff' },
+        { name: 'gray', value: '#f3f4f6' },
+        { name: 'dark', value: '#1f2937' },
+      ],
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    term: {
+      control: 'text',
+      description: 'Término o etiqueta (columna izquierda)',
+      table: {
+        type: { summary: 'string' },
+        category: 'Content',
+      },
+    },
+    details: {
+      control: 'text',
+      description: 'Detalles o valor (columna derecha)',
+      table: {
+        type: { summary: 'string' },
+        category: 'Content',
+      },
+    },
+  },
+} satisfies Meta<typeof DescriptionList>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ============================================
+// 1. PLAYGROUND INTERACTIVO
+// ============================================
+
+/**
+ * Playground Interactivo
+ *
+ * Usa los controles para experimentar con el DescriptionList en tiempo real.
+ */
+export const Playground: Story = {
+  name: 'Playground',
+  args: {
+    term: 'Cliente',
+    details: 'Jhonatan Díaz',
+  },
+  render: (args) => (
+    <div className="w-[583px]">
+      <DescriptionList {...args} />
+    </div>
+  ),
+};
+
+// ============================================
+// 2. LISTA SIMPLE
+// ============================================
+
+/**
+ * Lista Simple
+ *
+ * Ejemplo de varios items en una lista de descripción.
+ */
+export const SimpleList: Story = {
+  name: 'Lista Simple',
+  args: {
+    term: '',
+    details: '',
+  },
+  render: () => (
+    <div className="w-[583px]">
+      <DescriptionList term="Cliente" details="Jhonatan Díaz" />
+      <DescriptionList term="Evento" details="Bear Hug: Concierto en Vivo" />
+      <DescriptionList term="Monto" details="$120,000 COP" />
+      <DescriptionList term="Tarifa" details="$20,000 COP" />
+    </div>
+  ),
+};
+
+// ============================================
+// 3. CASOS DE USO REALES
+// ============================================
+
+/**
+ * Casos de Uso Reales
+ *
+ * Ejemplos prácticos de cómo usar DescriptionList en situaciones reales.
+ */
+export const UseCases: Story = {
+  name: 'Casos de Uso Reales',
+  args: {
+    term: '',
+    details: '',
+  },
+  render: () => (
+    <div className="space-y-6">
+      {/* Detalles de pedido */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Detalles de Pedido</h3>
+        <div className="p-6 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg w-[583px]">
+          <h4 className="font-bold text-base mb-4 text-gray-900 dark:text-white">Orden #12345</h4>
+          <div>
+            <DescriptionList term="Cliente" details="Juan Pérez" />
+            <DescriptionList term="Fecha" details="15 de Enero, 2024" />
+            <DescriptionList term="Estado" details="Entregado" />
+            <DescriptionList term="Total" details="$250.00 USD" />
+            <DescriptionList term="Método de Pago" details="Tarjeta de Crédito" />
+          </div>
+        </div>
+      </div>
+
+      {/* Información de evento */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Información de Evento</h3>
+        <div className="p-6 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg w-[583px]">
+          <h4 className="font-bold text-base mb-4 text-gray-900 dark:text-white">Detalles del Concierto</h4>
+          <div>
+            <DescriptionList term="Evento" details="Bear Hug: Concierto en Vivo" />
+            <DescriptionList term="Lugar" details="Madison Square Garden" />
+            <DescriptionList term="Fecha" details="20 de Marzo, 2024" />
+            <DescriptionList term="Hora" details="8:00 PM" />
+            <DescriptionList term="Precio del Boleto" details="$120,000 COP" />
+            <DescriptionList term="Tarifa de Servicio" details="$20,000 COP" />
+          </div>
+        </div>
+      </div>
+
+      {/* Perfil de usuario */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Perfil de Usuario</h3>
+        <div className="p-6 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg w-[583px]">
+          <h4 className="font-bold text-base mb-4 text-gray-900 dark:text-white">Información de Usuario</h4>
+          <div>
+            <DescriptionList term="Nombre" details="Jhonatan Díaz" />
+            <DescriptionList term="Correo Electrónico" details="jhonatan.diaz@ejemplo.com" />
+            <DescriptionList term="Teléfono" details="+57 312 345 6789" />
+            <DescriptionList term="Ubicación" details="Bogotá, Colombia" />
+            <DescriptionList term="Miembro Desde" details="Enero 2023" />
+          </div>
+        </div>
+      </div>
+
+      {/* Detalles de producto */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Detalles de Producto</h3>
+        <div className="p-6 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg w-[583px]">
+          <h4 className="font-bold text-base mb-4 text-gray-900 dark:text-white">Especificaciones del Producto</h4>
+          <div>
+            <DescriptionList term="Marca" details="Apple" />
+            <DescriptionList term="Modelo" details="iPhone 15 Pro" />
+            <DescriptionList term="Color" details="Titanio Natural" />
+            <DescriptionList term="Almacenamiento" details="256GB" />
+            <DescriptionList term="Condición" details="Nuevo" />
+            <DescriptionList term="Garantía" details="1 Año" />
+          </div>
+        </div>
+      </div>
+
+      {/* Información de factura */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Información de Factura</h3>
+        <div className="p-6 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg w-[583px]">
+          <h4 className="font-bold text-base mb-4 text-gray-900 dark:text-white">Factura #INV-2024-001</h4>
+          <div>
+            <DescriptionList term="Fecha de Factura" details="15 de Enero, 2024" />
+            <DescriptionList term="Fecha de Vencimiento" details="15 de Febrero, 2024" />
+            <DescriptionList term="Subtotal" details="$200.00" />
+            <DescriptionList term="Impuesto (19%)" details="$38.00" />
+            <DescriptionList term="Total" details="$238.00" />
+            <DescriptionList term="Estado" details="Pagado" />
+          </div>
+        </div>
+      </div>
+
+      {/* Detalles de propiedad */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Detalles de Propiedad</h3>
+        <div className="p-6 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg w-[583px]">
+          <h4 className="font-bold text-base mb-4 text-gray-900 dark:text-white">Listado de Propiedad</h4>
+          <div>
+            <DescriptionList term="Dirección" details="Calle Principal 123" />
+            <DescriptionList term="Ciudad" details="Medellín" />
+            <DescriptionList term="Precio" details="$450,000,000 COP" />
+            <DescriptionList term="Habitaciones" details="3" />
+            <DescriptionList term="Baños" details="2" />
+            <DescriptionList term="Área" details="120 m²" />
+            <DescriptionList term="Año de Construcción" details="2020" />
+          </div>
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+// ============================================
+// 4. LAYOUT COMPACTO
+// ============================================
+
+/**
+ * Layout Compacto
+ *
+ * Ejemplo con layout más compacto para espacios reducidos.
+ */
+export const CompactLayout: Story = {
+  name: 'Diseño Compacto',
+  args: {
+    term: '',
+    details: '',
+  },
+  render: () => (
+    <div className="space-y-6">
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Vista Compacta</h3>
+        <div className="p-4 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg w-[266px]">
+          <h4 className="font-bold text-sm mb-3 text-gray-900 dark:text-white">Resumen</h4>
+          <div>
+            <DescriptionList term="Cliente" details="Jhonatan Díaz" />
+            <DescriptionList term="Evento" details="Bear Hug: Concierto en Vivo" />
+            <DescriptionList term="Monto" details="$120,000 COP" />
+            <DescriptionList term="Tarifa" details="$20,000 COP" />
+          </div>
+        </div>
+      </div>
+    </div>
+  ),
+};

package/src/components/DescriptionList/DescriptionList.tsx

@@ -0,0 +1,96 @@
+import { forwardRef } from 'react';
+import type { DescriptionListProps } from './DescriptionList.types';
+
+/**
+ * DescriptionList del sistema de diseño Siesa
+ *
+ * Componente para mostrar información estructurada en formato clave-valor (term/details).
+ * Layout de dos columnas con separador inferior entre items.
+ *
+ * Mejores prácticas implementadas:
+ * - Orden de modificadores: {responsive}:{dark}:{state}:{utility}
+ * - Dark mode con estrategia 'class' (darkMode: 'class')
+ * - Tokens de color consistentes con la documentación
+ * - Type safety con TypeScript estricto
+ * - Layout flexible y responsive
+ * - Tipografía del sistema (Paragraph/Small - 14px)
+ *
+ * @see docs/colors.md - Sistema de colores (content-primary, content-secondary)
+ * @see docs/typography.md - Sistema tipográfico (Paragraph/Small)
+ * @see docs/spacing.md - Sistema de espaciado (padding, gaps)
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4103-8449 - Especificaciones Figma
+ *
+ * @example
+ * ```tsx
+ * // Item básico
+ * <DescriptionList
+ *   term="Customer"
+ *   details="Jhonatan Diaz"
+ * />
+ *
+ * // Lista completa
+ * <div>
+ *   <DescriptionList term="Event" details="Bear Hug: Live in Concert" />
+ *   <DescriptionList term="Amount" details="$120,000 COP" />
+ *   <DescriptionList term="Fee" details="$20,000 COP" />
+ * </div>
+ * ```
+ */
+export const DescriptionList = forwardRef<HTMLDivElement, DescriptionListProps>(
+  (
+    {
+      term,
+      details,
+      className = '',
+      ...props
+    },
+    ref
+  ) => {
+    // ===== CLASES BASE =====
+    const baseClasses = `
+      flex
+      flex-wrap
+      gap-1
+      items-start
+      py-2.5
+      border-b
+      border-border-secondary
+      dark:border-gray-700
+    `;
+
+    // ===== CLASES DE COLUMNA =====
+    // Cada columna ocupa el 50% del espacio disponible (flex-1)
+    // con un ancho mínimo de 180px para mantener legibilidad
+    const columnClasses = 'flex-1 min-w-[180px]';
+
+    // ===== COMBINAR CLASES =====
+    const finalClasses = [baseClasses, className]
+      .join(' ')
+      .replace(/\s+/g, ' ')
+      .trim();
+
+    return (
+      <div ref={ref} className={finalClasses} {...props}>
+        {/* Term Column (izquierda) */}
+        {/* Light: content-secondary (#a1a1aa) */}
+        {/* Dark: gray-400 (#9ca3af - gris medio claro para mantener contraste) */}
+        <div className={columnClasses}>
+          <p className="text-sm leading-5 text-content-secondary dark:text-gray-400 font-normal">
+            {term}
+          </p>
+        </div>
+
+        {/* Details Column (derecha) */}
+        {/* Light: content-primary (#18181b) */}
+        {/* Dark: dark-content-primary (#ffffff) */}
+        <div className={columnClasses}>
+          <p className="text-sm leading-5 text-content-primary dark:text-dark-content-primary font-normal">
+            {details}
+          </p>
+        </div>
+      </div>
+    );
+  }
+);
+
+DescriptionList.displayName = 'DescriptionList';

package/src/components/DescriptionList/DescriptionList.types.ts

@@ -0,0 +1,29 @@
+import type { HTMLAttributes } from 'react';
+
+/**
+ * Props del componente DescriptionList
+ *
+ * Componente para mostrar pares clave-valor en formato de dos columnas.
+ */
+export interface DescriptionListProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Término o etiqueta (columna izquierda)
+   * Mostrado en color secundario para diferenciarlo del valor
+   *
+   * @example "Customer", "Event", "Amount"
+   */
+  term: string;
+
+  /**
+   * Detalles o valor (columna derecha)
+   * Mostrado en color primario como información principal
+   *
+   * @example "Jhonatan Diaz", "Bear Hug: Live in Concert", "$120,000 COP"
+   */
+  details: string;
+
+  /**
+   * Clases CSS adicionales para el contenedor
+   */
+  className?: string;
+}