siesa-ui-kit 1.0.3 → 1.0.5

package/src/components/Checkbox/Checkbox.stories.tsx

@@ -0,0 +1,453 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Checkbox } from './Checkbox';
+import { useState } from 'react';
+
+/**
+ * Checkbox - Componente de checkbox del sistema de diseño Siesa
+ *
+ * Sistema completo de checkboxes con soporte para:
+ * - **Estados**: Default, Hover, Focus, Disabled
+ * - **Selección**: Unchecked, Checked, Indeterminate
+ * - **Label y Description**: Etiquetas con descripción opcional
+ * - **Accesibilidad**: Completa con keyboard navigation
+ * - **Dark mode**: Adaptación completa al tema oscuro
+ */
+const meta = {
+  title: 'Siesa UI Kit/Checkbox',
+  component: Checkbox,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Campos de selección binaria con soporte para múltiples estados, indeterminate, y opciones de etiquetado. Diseñado para mantener consistencia visual y funcional en toda la aplicación.',
+      },
+    },
+    backgrounds: {
+      default: 'light',
+      values: [
+        { name: 'light', value: '#ffffff' },
+        { name: 'gray', value: '#f3f4f6' },
+        { name: 'dark', value: '#1f2937' },
+      ],
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    label: {
+      control: 'text',
+      description: 'Etiqueta del checkbox',
+      table: {
+        type: { summary: 'string' },
+        category: 'Content',
+      },
+    },
+    description: {
+      control: 'text',
+      description: 'Descripción debajo del label',
+      table: {
+        type: { summary: 'string' },
+        category: 'Content',
+      },
+    },
+    checked: {
+      control: 'boolean',
+      description: 'Si el checkbox está marcado',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        category: 'State',
+      },
+    },
+    indeterminate: {
+      control: 'boolean',
+      description: 'Si el checkbox está en estado indeterminado',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        category: 'State',
+      },
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Deshabilita el checkbox',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        category: 'State',
+      },
+    },
+  },
+} satisfies Meta<typeof Checkbox>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ============================================
+// 1. PLAYGROUND INTERACTIVO
+// ============================================
+
+/**
+ * Playground Interactivo
+ *
+ * Usa los controles para experimentar con todas las props del Checkbox en tiempo real.
+ * Cambia el estado, textos y más para ver cómo se comporta el componente.
+ */
+export const Playground: Story = {
+  name: 'Playground',
+  args: {
+    label: 'Mostrar en Página de Eventos',
+    description: 'Hacer este evento visible en tu perfil.',
+    checked: false,
+    indeterminate: false,
+    disabled: false,
+  },
+  render: (args) => {
+    const [checked, setChecked] = useState(args.checked);
+
+    return (
+      <Checkbox
+        {...args}
+        checked={checked}
+        onChange={(e) => setChecked(e.target.checked)}
+      />
+    );
+  },
+};
+
+// ============================================
+// 2. TODOS LOS ESTADOS
+// ============================================
+
+/**
+ * Todos los Estados
+ *
+ * Vista rápida de todos los estados del Checkbox: default, hover, focus, disabled.
+ * Muestra estados checked y unchecked para cada uno.
+ */
+export const AllStates: Story = {
+  name: 'Todos los Estados',
+  render: () => (
+    <div className="space-y-6">
+      {/* Unchecked States */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Estados Sin Marcar</h3>
+        <div className="space-y-3">
+          <Checkbox label="Por Defecto" description="Checkbox sin marcar en estado por defecto" />
+          <Checkbox label="Hover" description="Pasa el mouse sobre el checkbox para ver el estado" />
+          <Checkbox label="Foco" description="Haz clic para enfocar (intenta presionar Tab)" />
+          <Checkbox label="Deshabilitado" description="Checkbox deshabilitado sin marcar" disabled />
+        </div>
+      </div>
+
+      {/* Checked States */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Estados Marcados</h3>
+        <div className="space-y-3">
+          <Checkbox
+            label="Por Defecto"
+            description="Checkbox marcado en estado por defecto"
+            checked
+            onChange={() => {}}
+          />
+          <Checkbox
+            label="Hover"
+            description="Pasa el mouse sobre el checkbox para ver el estado"
+            checked
+            onChange={() => {}}
+          />
+          <Checkbox
+            label="Seleccionado"
+            description="Checkbox seleccionado"
+            checked
+            onChange={() => {}}
+          />
+          <Checkbox
+            label="Deshabilitado"
+            description="Checkbox marcado deshabilitado"
+            checked
+            disabled
+            onChange={() => {}}
+          />
+        </div>
+      </div>
+
+      {/* Indeterminate States */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Estados Indeterminados</h3>
+        <div className="space-y-3">
+          <Checkbox
+            label="Indeterminado"
+            description="Estado parcialmente seleccionado"
+            indeterminate
+            onChange={() => {}}
+          />
+          <Checkbox
+            label="Hover"
+            description="Pasa el mouse sobre el checkbox indeterminado"
+            indeterminate
+            onChange={() => {}}
+          />
+          <Checkbox
+            label="Deshabilitado"
+            description="Checkbox indeterminado deshabilitado"
+            indeterminate
+            disabled
+            onChange={() => {}}
+          />
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+// ============================================
+// 3. CON Y SIN LABELS
+// ============================================
+
+/**
+ * Con y Sin Labels
+ *
+ * Ejemplos de checkboxes con diferentes combinaciones de label y description.
+ */
+export const ConEtiquetas: Story = {
+  name: 'Con y Sin Etiquetas',
+  render: () => (
+    <div className="space-y-6">
+      {/* Sin Label ni Description */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Sin Label ni Description</h3>
+        <Checkbox />
+      </div>
+
+      {/* Solo Label */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Solo Label</h3>
+        <Checkbox label="Aceptar términos y condiciones" />
+      </div>
+
+      {/* Label + Description */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Label + Description</h3>
+        <Checkbox
+          label="Mostrar en Página de Eventos"
+          description="Hacer este evento visible en tu perfil."
+        />
+      </div>
+
+      {/* Label Largo */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Con Texto Largo</h3>
+        <Checkbox
+          label="Enviarme correos promocionales y actualizaciones"
+          description="Puedes darte de baja en cualquier momento. Nunca compartiremos tu dirección de correo con terceros."
+        />
+      </div>
+    </div>
+  ),
+};
+
+// ============================================
+// 4. CHECKBOX GROUPS
+// ============================================
+
+/**
+ * Checkbox Groups
+ *
+ * Ejemplos de grupos de checkboxes relacionados, incluyendo "select all" con estado indeterminado.
+ */
+export const CheckboxGroups: Story = {
+  name: 'Grupos de Checkbox',
+  render: () => {
+    const [items, setItems] = useState({
+      item1: true,
+      item2: false,
+      item3: false,
+    });
+
+    const allChecked = Object.values(items).every(Boolean);
+    const someChecked = Object.values(items).some(Boolean) && !allChecked;
+
+    const toggleAll = () => {
+      const newValue = !allChecked;
+      setItems({
+        item1: newValue,
+        item2: newValue,
+        item3: newValue,
+      });
+    };
+
+    return (
+      <div className="space-y-6">
+        {/* Select All Example */}
+        <div>
+          <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">
+            Select All (con estado indeterminate)
+          </h3>
+          <div className="space-y-2">
+            <Checkbox
+              label="Seleccionar Todo"
+              checked={allChecked}
+              indeterminate={someChecked}
+              onChange={toggleAll}
+            />
+            <div className="ml-8 space-y-2">
+              <Checkbox
+                label="Elemento 1"
+                checked={items.item1}
+                onChange={(e) => setItems({ ...items, item1: e.target.checked })}
+              />
+              <Checkbox
+                label="Elemento 2"
+                checked={items.item2}
+                onChange={(e) => setItems({ ...items, item2: e.target.checked })}
+              />
+              <Checkbox
+                label="Elemento 3"
+                checked={items.item3}
+                onChange={(e) => setItems({ ...items, item3: e.target.checked })}
+              />
+            </div>
+          </div>
+        </div>
+
+        {/* Simple Group */}
+        <div>
+          <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Grupo Simple</h3>
+          <div className="space-y-2">
+            <Checkbox label="JavaScript" />
+            <Checkbox label="TypeScript" />
+            <Checkbox label="Python" />
+            <Checkbox label="Rust" />
+          </div>
+        </div>
+      </div>
+    );
+  },
+};
+
+// ============================================
+// 5. CASOS DE USO REALES
+// ============================================
+
+/**
+ * Casos de Uso Reales
+ *
+ * Ejemplos prácticos de cómo usar los checkboxes en situaciones reales:
+ * formularios, configuraciones, listas de tareas, etc.
+ */
+export const UseCases: Story = {
+  name: 'Casos de Uso Reales',
+  render: () => {
+    const [preferences, setPreferences] = useState({
+      emails: true,
+      notifications: false,
+      updates: true,
+    });
+
+    const [tasks, setTasks] = useState({
+      task1: true,
+      task2: false,
+      task3: false,
+    });
+
+    return (
+      <div className="space-y-6">
+        {/* Formulario de Preferencias */}
+        <div>
+          <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">
+            Formulario de Preferencias
+          </h3>
+          <div className="p-6 bg-white dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary rounded-lg max-w-md">
+            <h4 className="font-bold mb-4 text-base text-content-primary dark:text-dark-content-primary">Preferencias de Email</h4>
+            <div className="space-y-3">
+              <Checkbox
+                label="Correos promocionales"
+                description="Recibir correos sobre nuevos productos y ofertas"
+                checked={preferences.emails}
+                onChange={(e) =>
+                  setPreferences({ ...preferences, emails: e.target.checked })
+                }
+              />
+              <Checkbox
+                label="Notificaciones push"
+                description="Recibir notificaciones push en tu dispositivo"
+                checked={preferences.notifications}
+                onChange={(e) =>
+                  setPreferences({ ...preferences, notifications: e.target.checked })
+                }
+              />
+              <Checkbox
+                label="Actualizaciones de productos"
+                description="Recibir notificaciones sobre actualizaciones y características de productos"
+                checked={preferences.updates}
+                onChange={(e) =>
+                  setPreferences({ ...preferences, updates: e.target.checked })
+                }
+              />
+            </div>
+          </div>
+        </div>
+
+        {/* Lista de Tareas */}
+        <div>
+          <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Lista de Tareas</h3>
+          <div className="p-6 bg-white dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary rounded-lg max-w-md">
+            <h4 className="font-bold mb-4 text-base text-content-primary dark:text-dark-content-primary">Tareas de Hoy</h4>
+            <div className="space-y-3">
+              <Checkbox
+                label="Revisar pull requests"
+                checked={tasks.task1}
+                onChange={(e) => setTasks({ ...tasks, task1: e.target.checked })}
+              />
+              <Checkbox
+                label="Actualizar documentación"
+                checked={tasks.task2}
+                onChange={(e) => setTasks({ ...tasks, task2: e.target.checked })}
+              />
+              <Checkbox
+                label="Desplegar a producción"
+                checked={tasks.task3}
+                onChange={(e) => setTasks({ ...tasks, task3: e.target.checked })}
+              />
+            </div>
+          </div>
+        </div>
+
+        {/* Terms and Conditions */}
+        <div>
+          <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">
+            Términos y Condiciones
+          </h3>
+          <div className="p-6 bg-white dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary rounded-lg max-w-md">
+            <div className="space-y-3">
+              <Checkbox
+                label="Acepto los términos y condiciones"
+                description="Al marcar esta casilla, aceptas nuestros Términos de Servicio y Política de Privacidad"
+              />
+              <Checkbox
+                label="Quiero recibir comunicaciones de marketing"
+                description="Opcional: Recibir actualizaciones sobre nuevas características y promociones"
+              />
+            </div>
+          </div>
+        </div>
+
+        {/* Filtros */}
+        <div>
+          <h3 className="text-sm font-bold mb-4 text-gray-700 dark:text-white">Filtros de Búsqueda</h3>
+          <div className="p-6 bg-white dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary rounded-lg max-w-md">
+            <h4 className="font-bold mb-4 text-base text-content-primary dark:text-dark-content-primary">Filtrar por Categoría</h4>
+            <div className="space-y-2">
+              <Checkbox label="Electrónica" />
+              <Checkbox label="Ropa" />
+              <Checkbox label="Libros" />
+              <Checkbox label="Hogar y Jardín" />
+              <Checkbox label="Deportes" />
+            </div>
+          </div>
+        </div>
+      </div>
+    );
+  },
+};

package/src/components/Checkbox/Checkbox.tsx

@@ -0,0 +1,208 @@
+import { forwardRef, useEffect, useRef } from 'react';
+import type { CheckboxProps } from './Checkbox.types';
+
+/**
+ * Checkbox del sistema de diseño Siesa
+ *
+ * Componente de checkbox con soporte completo para estados interactivos,
+ * indeterminate, y dark mode pixel-perfect según especificaciones de Figma.
+ *
+ * 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
+ * - Sombra button-inset para estado checked
+ * - Type safety con TypeScript estricto
+ * - Accesibilidad con input nativo y ARIA
+ *
+ * @see docs/colors.md - Sistema de colores
+ * @see docs/typography.md - Sistema tipográfico (Label/Paragraph)
+ * @see docs/spacing.md - Sistema de espaciado
+ *
+ * @example
+ * ```tsx
+ * <Checkbox
+ *   label="Show on Events Page"
+ *   description="Make this event visible on your profile"
+ *   checked={true}
+ *   onChange={(e) => console.log(e.target.checked)}
+ * />
+ * ```
+ */
+export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(
+  (
+    {
+      label,
+      description,
+      checked = false,
+      indeterminate = false,
+      disabled = false,
+      className = '',
+      id,
+      onChange,
+      ...props
+    },
+    ref
+  ) => {
+    const inputRef = useRef<HTMLInputElement>(null);
+    const combinedRef = (ref as any) || inputRef;
+
+    // Generar ID único si no se proporciona
+    const checkboxId = id || `checkbox-${Math.random().toString(36).substr(2, 9)}`;
+
+    // Manejar el estado indeterminate
+    useEffect(() => {
+      if (combinedRef.current) {
+        combinedRef.current.indeterminate = indeterminate;
+      }
+    }, [indeterminate, combinedRef]);
+
+    // ===== CLASES BASE DEL CHECKBOX =====
+    const baseCheckboxClasses = `
+      w-4
+      h-4
+      rounded
+      border
+      border-border-primary
+      bg-bg-primary
+      transition-all
+      duration-150
+      flex
+      items-center
+      justify-center
+      dark:bg-dark-bg-primary
+      dark:border-dark-border-primary
+    `;
+
+    // ===== CLASES PARA ESTADOS INTERACTIVOS =====
+    const interactiveClasses = !disabled
+      ? (checked || indeterminate)
+        ? `
+          peer-hover:border-[#50a5f7]
+          peer-focus:ring-2
+          peer-focus:ring-primary-custom-400/20
+          peer-focus:border-primary-custom-600
+          dark:peer-hover:border-[#50a5f7]
+          dark:peer-focus:border-dark-border-custom
+          dark:peer-focus:ring-dark-border-custom/20
+        `
+        : `
+          peer-hover:border-[#b6b6b9]
+          peer-focus:ring-2
+          peer-focus:ring-primary-custom-400/20
+          peer-focus:border-primary-custom-600
+          dark:peer-hover:border-[#b6b6b9]
+          dark:peer-focus:border-dark-border-custom
+          dark:peer-focus:ring-dark-border-custom/20
+        `
+      : `
+        opacity-50
+        cursor-not-allowed
+      `;
+
+    // ===== CLASES PARA ESTADO CHECKED/INDETERMINATE =====
+    // Orden de modificadores: {responsive}:{dark}:{state}:{utility}
+    const checkedClasses = checked || indeterminate
+      ? `
+        !bg-primary-custom-600
+        !border-primary-custom-500
+        shadow-button-inset
+        dark:!bg-dark-bg-inverse
+        dark:!border-dark-bg-inverse
+      `
+      : '';
+
+    // ===== COMBINAR TODAS LAS CLASES DEL CHECKBOX =====
+    const checkboxClasses = [
+      baseCheckboxClasses,
+      interactiveClasses,
+      checkedClasses,
+      disabled ? 'cursor-not-allowed' : 'cursor-pointer',
+    ]
+      .join(' ')
+      .replace(/\s+/g, ' ')
+      .trim();
+
+    return (
+      <div className={`inline-flex gap-3 items-start ${className}`}>
+        {/* Checkbox Input Container */}
+        <div className="flex items-center justify-center h-5 w-4 shrink-0">
+          {/* Native Input (hidden but accessible) */}
+          <input
+            ref={combinedRef}
+            type="checkbox"
+            id={checkboxId}
+            checked={checked}
+            disabled={disabled}
+            onChange={onChange}
+            className="peer sr-only"
+            {...props}
+          />
+
+          {/* Custom Checkbox Visual */}
+          <label htmlFor={checkboxId} className={checkboxClasses}>
+            {/* Check Icon - Usar primary-inverse-content para consistencia */}
+            {checked && !indeterminate && (
+              <svg
+                className="w-3 h-3 text-primary-inverse-content pointer-events-none"
+                viewBox="0 0 12 12"
+                fill="none"
+                xmlns="http://www.w3.org/2000/svg"
+              >
+                <path
+                  d="M10 3L4.5 8.5L2 6"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                />
+              </svg>
+            )}
+
+            {/* Indeterminate Icon (minus) - Usar primary-inverse-content */}
+            {indeterminate && (
+              <svg
+                className="w-3 h-3 text-primary-inverse-content pointer-events-none"
+                viewBox="0 0 12 12"
+                fill="none"
+                xmlns="http://www.w3.org/2000/svg"
+              >
+                <path
+                  d="M2 6H10"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                />
+              </svg>
+            )}
+          </label>
+        </div>
+
+        {/* Label and Description */}
+        {(label || description) && (
+          <label
+            htmlFor={checkboxId}
+            className={`flex-1 flex flex-col gap-1 text-sm leading-5 ${
+              disabled ? 'cursor-not-allowed opacity-50' : 'cursor-pointer'
+            }`}
+          >
+            {/* Label - Label/Small (14px, Bold) */}
+            {label && (
+              <span className="font-bold text-content-primary dark:text-dark-content-primary">
+                {label}
+              </span>
+            )}
+            {/* Description - Paragraph/Small (14px, Regular) */}
+            {description && (
+              <span className="font-normal text-content-secondary dark:text-content-secondary">
+                {description}
+              </span>
+            )}
+          </label>
+        )}
+      </div>
+    );
+  }
+);
+
+Checkbox.displayName = 'Checkbox';