siesa-ui-kit 1.0.3 → 1.0.5

package/src/components/Switch/Switch.tsx

@@ -0,0 +1,246 @@
+import { forwardRef } from 'react';
+import type { SwitchProps } from './Switch.types';
+
+/**
+ * Switch - Componente de switch del sistema de diseño Siesa
+ *
+ * Campo de activación/desactivación con soporte para:
+ * - Estados: default, hover, focus, disabled
+ * - On, off
+ * - Label y description opcionales
+ * - Posición del label: leading (izquierda) o trailing (derecha)
+ * - Animación suave de transición
+ * - Dark mode completo
+ * - Accesibilidad completa
+ *
+ * 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
+ * - Focus ring con shadow especial según Figma
+ * - Type safety con TypeScript estricto
+ * - Accesibilidad con ARIA labels
+ *
+ * @see docs/colors.md - Sistema de colores
+ * @see docs/typography.md - Sistema tipográfico
+ * @see docs/spacing.md - Sistema de espaciado
+ *
+ * @example
+ * ```tsx
+ * // Label a la izquierda (default)
+ * <Switch
+ *   label="Permitir inserción"
+ *   description="Permite que otros inserten los detalles de tu evento."
+ *   checked={true}
+ *   onChange={(e) => console.log(e.target.checked)}
+ * />
+ *
+ * // Label a la derecha
+ * <Switch
+ *   label="Activar notificaciones"
+ *   labelPosition="trailing"
+ *   checked={false}
+ *   onChange={(e) => console.log(e.target.checked)}
+ * />
+ * ```
+ */
+export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
+  (
+    {
+      label,
+      description,
+      labelPosition = 'leading',
+      checked = false,
+      disabled = false,
+      className = '',
+      id,
+      onChange,
+      ariaLabel,
+      ...props
+    },
+    ref
+  ) => {
+    // Generar ID único si no se proporciona
+    const switchId = id || `switch-${Math.random().toString(36).substr(2, 9)}`;
+
+    // ===== CLASES BASE DEL TRACK =====
+    const baseTrackClasses = `
+      w-8
+      h-5
+      rounded-xl
+      border
+      overflow-hidden
+      relative
+      transition-all
+      duration-200
+    `;
+
+    // ===== CLASES DE ESTADO DEL TRACK =====
+    const getTrackStateClasses = () => {
+      if (disabled) {
+        return checked
+          ? `
+            bg-primary-custom-600
+            border-primary-inverse-border
+            opacity-50
+            cursor-not-allowed
+            dark:bg-primary-custom-600
+            dark:border-primary-inverse-border
+          `
+          : `
+            bg-[#fafafa]
+            border-border-primary
+            opacity-50
+            cursor-not-allowed
+            dark:bg-dark-bg-primary
+            dark:border-dark-border-primary
+          `;
+      }
+
+      return checked
+        ? `
+          bg-primary-custom-600
+          border-primary-inverse-border
+          cursor-pointer
+          peer-hover:border-[#307cc5]
+          peer-focus:shadow-[0px_0px_0px_2px_#dbeefe,0px_1px_2px_0px_rgba(0,0,0,0.05),0px_0px_0px_4px_#60b6fa]
+          dark:bg-primary-custom-600
+          dark:border-primary-inverse-border
+          dark:peer-hover:border-[#307cc5]
+          dark:peer-focus:shadow-[0px_0px_0px_2px_#dbeefe,0px_1px_2px_0px_rgba(0,0,0,0.05),0px_0px_0px_4px_#60b6fa]
+        `
+        : `
+          bg-[#fafafa]
+          border-border-primary
+          cursor-pointer
+          peer-hover:border-[#b6b6b9]
+          peer-focus:shadow-[0px_0px_0px_2px_#dbeefe,0px_1px_2px_0px_rgba(0,0,0,0.05),0px_0px_0px_4px_#60b6fa]
+          dark:bg-dark-bg-primary
+          dark:border-dark-border-primary
+          dark:peer-hover:border-[#b6b6b9]
+          dark:peer-focus:shadow-[0px_0px_0px_2px_#dbeefe,0px_1px_2px_0px_rgba(0,0,0,0.05),0px_0px_0px_4px_#60b6fa]
+        `;
+    };
+
+    // ===== CLASES DEL BOTÓN (CÍRCULO) =====
+    const getButtonClasses = () => {
+      const baseButtonClasses = `
+        absolute
+        w-4
+        h-4
+        bg-white
+        rounded-[10px]
+        border
+        top-1/2
+        -translate-y-1/2
+        transition-all
+        duration-200
+      `;
+
+      // Posición: OFF = left-px (1px), ON = left-[13px]
+      const positionClass = checked ? 'left-[13px]' : 'left-px';
+
+      if (disabled) {
+        const borderClass = checked
+          ? 'border-primary-inverse-border dark:border-primary-inverse-border'
+          : 'border-border-primary dark:border-dark-border-primary';
+        return `${baseButtonClasses} ${positionClass} ${borderClass}`;
+      }
+
+      const borderClass = checked
+        ? `
+          border-primary-inverse-border
+          peer-hover:border-[#307cc5]
+          dark:border-primary-inverse-border
+          dark:peer-hover:border-[#307cc5]
+        `
+        : `
+          border-border-primary
+          peer-hover:border-[#b6b6b9]
+          dark:border-dark-border-primary
+          dark:peer-hover:border-[#b6b6b9]
+        `;
+
+      return `${baseButtonClasses} ${positionClass} ${borderClass}`;
+    };
+
+    // ===== COMBINAR CLASES =====
+    const trackClasses = [
+      baseTrackClasses,
+      getTrackStateClasses(),
+    ]
+      .join(' ')
+      .replace(/\s+/g, ' ')
+      .trim();
+
+    const buttonClasses = getButtonClasses()
+      .replace(/\s+/g, ' ')
+      .trim();
+
+    // ===== COMPONENTES REUTILIZABLES =====
+    const LabelContent = (label || description) ? (
+      <label
+        htmlFor={switchId}
+        className={`flex-1 flex flex-col gap-1 text-sm leading-5 ${
+          disabled ? 'cursor-not-allowed opacity-50' : 'cursor-pointer'
+        }`}
+      >
+        {label && (
+          <span className="font-bold text-content-primary dark:text-dark-content-primary">
+            {label}
+          </span>
+        )}
+        {description && (
+          <span className="font-normal text-content-secondary dark:text-content-secondary">
+            {description}
+          </span>
+        )}
+      </label>
+    ) : null;
+
+    const SwitchInput = (
+      <div className="flex items-center justify-center shrink-0">
+        {/* Native Input (hidden but accessible) */}
+        <input
+          ref={ref}
+          type="checkbox"
+          id={switchId}
+          checked={checked}
+          disabled={disabled}
+          onChange={onChange}
+          className="peer sr-only"
+          aria-label={ariaLabel || label}
+          {...props}
+        />
+
+        {/* Custom Switch Visual */}
+        <label
+          htmlFor={switchId}
+          className={trackClasses}
+          aria-hidden="true"
+        >
+          {/* Button (sliding circle) */}
+          <div className={buttonClasses} />
+        </label>
+      </div>
+    );
+
+    return (
+      <div className={`flex gap-2 items-center w-[344px] ${className}`}>
+        {labelPosition === 'leading' ? (
+          <>
+            {LabelContent}
+            {SwitchInput}
+          </>
+        ) : (
+          <>
+            {SwitchInput}
+            {LabelContent}
+          </>
+        )}
+      </div>
+    );
+  }
+);
+
+Switch.displayName = 'Switch';

package/src/components/Switch/Switch.types.ts

@@ -0,0 +1,67 @@
+import type { InputHTMLAttributes } from 'react';
+
+/**
+ * Estados visuales del Switch
+ */
+export type SwitchState = 'default' | 'hover' | 'focus' | 'disabled';
+
+/**
+ * Posición del label respecto al switch
+ * - `leading`: Label a la izquierda, switch a la derecha
+ * - `trailing`: Switch a la izquierda, label a la derecha
+ */
+export type LabelPosition = 'leading' | 'trailing';
+
+/**
+ * Props del componente Switch
+ *
+ * @see docs/colors.md - Sistema de colores
+ * @see docs/typography.md - Sistema tipográfico
+ */
+export interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'size'> {
+  /**
+   * Etiqueta del switch
+   */
+  label?: string;
+
+  /**
+   * Descripción debajo del label
+   */
+  description?: string;
+
+  /**
+   * Posición del label respecto al switch
+   * - `leading`: Label a la izquierda, switch a la derecha (default)
+   * - `trailing`: Switch a la izquierda, label a la derecha
+   * @default 'leading'
+   */
+  labelPosition?: LabelPosition;
+
+  /**
+   * Si el switch está activado
+   * @default false
+   */
+  checked?: boolean;
+
+  /**
+   * Si el switch está deshabilitado
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Clases CSS adicionales
+   */
+  className?: string;
+
+  /**
+   * Callback cuando el estado del switch cambia
+   */
+  onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+
+  /**
+   * Label para accesibilidad (ARIA)
+   * Si no se proporciona, se usa el valor de `label`
+   */
+  ariaLabel?: string;
+}

package/src/components/Table/README.md

@@ -0,0 +1,369 @@
+# Table Component
+
+Componente de tabla flexible y accesible con soporte para sorting, variantes visuales y dark mode completo.
+
+## Características
+
+- ✅ **Definición de columnas flexible** con `accessor` y `render` custom
+- ✅ **Sorting** en columnas (controlado o no controlado)
+- ✅ **Variantes visuales**: basic, fullWidth, striped, grid
+- ✅ **Dark mode completo** en todos los estados
+- ✅ **Estados de loading y empty**
+- ✅ **Filas clickeables**
+- ✅ **TypeScript** con tipos estrictos y generics
+- ✅ **Accesibilidad** con roles y keyboard navigation
+
+## Uso Básico
+
+```tsx
+import { Table } from '@/components/Table';
+import type { TableColumn } from '@/components/Table';
+
+interface Usuario {
+  id: number;
+  nombre: string;
+  email: string;
+}
+
+const usuarios: Usuario[] = [
+  { id: 1, nombre: 'Juan Pérez', email: 'juan@example.com' },
+  { id: 2, nombre: 'María García', email: 'maria@example.com' },
+];
+
+const columns: TableColumn<Usuario>[] = [
+  { header: 'Nombre', accessor: 'nombre' },
+  { header: 'Email', accessor: 'email' },
+];
+
+function App() {
+  return (
+    <Table
+      title="Usuarios"
+      columns={columns}
+      data={usuarios}
+    />
+  );
+}
+```
+
+## Variantes
+
+### Basic
+Tabla estándar con padding y spacing consistente.
+
+```tsx
+<Table
+  title="Usuarios"
+  columns={columns}
+  data={data}
+  variant="basic"
+/>
+```
+
+### Full Width
+Tabla que ocupa todo el ancho disponible.
+
+```tsx
+<Table
+  title="Usuarios"
+  columns={columns}
+  data={data}
+  variant="fullWidth"
+/>
+```
+
+### Striped (Filas Alternas)
+Filas con fondo alternado para mejor legibilidad.
+
+```tsx
+<Table
+  title="Usuarios"
+  columns={columns}
+  data={data}
+  variant="striped"
+/>
+```
+
+### Grid (Con Bordes)
+Tabla con bordes alrededor de las celdas.
+
+```tsx
+<Table
+  title="Usuarios"
+  columns={columns}
+  data={data}
+  variant="grid"
+/>
+```
+
+## Sorting
+
+### Sorting No Controlado (Interno)
+
+```tsx
+const columns: TableColumn<Usuario>[] = [
+  {
+    header: 'Nombre',
+    accessor: 'nombre',
+    sortable: true, // Habilitar sorting
+  },
+  {
+    header: 'Email',
+    accessor: 'email',
+    sortable: true,
+  },
+];
+
+<Table columns={columns} data={data} />
+```
+
+### Sorting Controlado (Externo)
+
+```tsx
+const [sortColumn, setSortColumn] = useState<keyof Usuario | null>(null);
+const [sortDirection, setSortDirection] = useState<SortDirection>(null);
+
+const handleSort = (column: keyof Usuario | string, direction: SortDirection) => {
+  setSortColumn(column as keyof Usuario);
+  setSortDirection(direction);
+
+  // Ordenar los datos
+  const sorted = [...data].sort((a, b) => {
+    // Lógica de ordenamiento
+  });
+  setData(sorted);
+};
+
+<Table
+  columns={columns}
+  data={data}
+  sortColumn={sortColumn}
+  sortDirection={sortDirection}
+  onSort={handleSort}
+/>
+```
+
+## Render Custom
+
+Puedes personalizar cómo se renderiza el contenido de una celda:
+
+```tsx
+const columns: TableColumn<Usuario>[] = [
+  {
+    header: 'Estado',
+    accessor: 'estado',
+    render: (value, row, index) => (
+      <span
+        className={`
+          px-2 py-1 rounded-md text-xs font-bold
+          ${value === 'activo' ? 'bg-green-100 text-green-800' : 'bg-red-100 text-red-800'}
+        `}
+      >
+        {value}
+      </span>
+    ),
+  },
+];
+```
+
+## Accessor Function
+
+Puedes usar una función para acceder a valores anidados o calculados:
+
+```tsx
+const columns: TableColumn<Usuario>[] = [
+  {
+    header: 'Nombre Completo',
+    accessor: (row) => `${row.nombre} ${row.apellido}`,
+  },
+  {
+    header: 'Email',
+    accessor: (row) => row.contacto.email.toLowerCase(),
+  },
+];
+```
+
+## Alineación de Columnas
+
+```tsx
+const columns: TableColumn<Usuario>[] = [
+  {
+    header: 'ID',
+    accessor: 'id',
+    align: 'center', // 'left' | 'center' | 'right'
+    width: '80px',   // Ancho fijo
+  },
+  {
+    header: 'Nombre',
+    accessor: 'nombre',
+    align: 'left',
+  },
+];
+```
+
+## Estados
+
+### Loading
+
+```tsx
+<Table
+  title="Usuarios"
+  columns={columns}
+  data={[]}
+  loading={true}
+  loadingRows={5}
+/>
+```
+
+### Empty
+
+```tsx
+<Table
+  title="Usuarios"
+  columns={columns}
+  data={[]}
+  emptyMessage="No hay usuarios registrados"
+/>
+```
+
+## Filas Clickeables
+
+```tsx
+const handleRowClick = (row: Usuario, index: number) => {
+  console.log('Clicked:', row);
+  // Navegar a detalle, abrir modal, etc.
+};
+
+<Table
+  columns={columns}
+  data={data}
+  onRowClick={handleRowClick}
+/>
+```
+
+## Props
+
+### TableProps
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `title` | `string` | `undefined` | Título opcional de la tabla |
+| `columns` | `TableColumn<T>[]` | **Required** | Definición de las columnas |
+| `data` | `T[]` | **Required** | Datos de las filas |
+| `variant` | `'basic' \| 'fullWidth' \| 'striped' \| 'grid'` | `'basic'` | Variante visual |
+| `showBorder` | `boolean` | `true` | Si se muestra el borde del container |
+| `showShadow` | `boolean` | `true` | Si se muestra la sombra del container |
+| `onRowClick` | `(row: T, index: number) => void` | `undefined` | Callback al hacer click en una fila |
+| `onSort` | `(column: string, direction: SortDirection) => void` | `undefined` | Callback al cambiar el sort |
+| `sortColumn` | `keyof T \| string` | `undefined` | Columna ordenada (controlado) |
+| `sortDirection` | `SortDirection` | `undefined` | Dirección de sort (controlado) |
+| `fullWidth` | `boolean` | `false` | Si ocupa todo el ancho |
+| `emptyMessage` | `string` | `'No hay datos disponibles'` | Mensaje cuando no hay datos |
+| `loading` | `boolean` | `false` | Si está cargando |
+| `loadingRows` | `number` | `5` | Número de rows skeleton |
+| `className` | `string` | `''` | Clases CSS adicionales |
+| `id` | `string` | `undefined` | ID único |
+
+### TableColumn
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `header` | `string` | **Required** | Título del header |
+| `accessor` | `keyof T \| (row: T) => any` | **Required** | Key o función para obtener valor |
+| `sortable` | `boolean` | `false` | Si la columna es sortable |
+| `render` | `(value: any, row: T, index: number) => ReactNode` | `undefined` | Función custom de render |
+| `align` | `'left' \| 'center' \| 'right'` | `'left'` | Alineación del contenido |
+| `width` | `string` | `undefined` | Ancho de la columna |
+
+## Dark Mode
+
+El componente Table se adapta automáticamente a dark mode usando los tokens de color del sistema:
+
+```tsx
+// Los colores se adaptan automáticamente
+<Table
+  columns={columns}
+  data={data}
+  // En light mode: bg-white, text-content-primary
+  // En dark mode: bg-dark-bg-primary, text-dark-content-primary
+/>
+```
+
+## Accesibilidad
+
+- ✅ Headers clickeables tienen `role="button"` y `tabIndex={0}`
+- ✅ Soporta navegación por teclado (Enter y Space)
+- ✅ Estados de sort anunciados visualmente con iconos
+- ✅ Filas clickeables con keyboard support
+
+## Ejemplos Avanzados
+
+### Tabla de Productos con Render Custom
+
+```tsx
+interface Producto {
+  id: number;
+  nombre: string;
+  precio: number;
+  stock: number;
+  disponible: boolean;
+}
+
+const columns: TableColumn<Producto>[] = [
+  {
+    header: 'Producto',
+    accessor: 'nombre',
+    sortable: true,
+  },
+  {
+    header: 'Precio',
+    accessor: 'precio',
+    align: 'right',
+    render: (value) => `$${value.toFixed(2)}`,
+  },
+  {
+    header: 'Stock',
+    accessor: 'stock',
+    align: 'center',
+    render: (value) => (
+      <span className={value < 10 ? 'text-red-600 font-bold' : ''}>
+        {value}
+      </span>
+    ),
+  },
+  {
+    header: 'Disponibilidad',
+    accessor: 'disponible',
+    align: 'center',
+    render: (value) => (
+      <span className={`
+        px-2 py-1 rounded text-xs font-bold
+        ${value ? 'bg-green-100 text-green-800' : 'bg-gray-100 text-gray-800'}
+      `}>
+        {value ? 'Disponible' : 'Agotado'}
+      </span>
+    ),
+  },
+];
+
+<Table
+  title="Inventario de Productos"
+  columns={columns}
+  data={productos}
+  variant="fullWidth"
+/>
+```
+
+## Archivos Relacionados
+
+- `Table.tsx` - Implementación del componente (561 líneas)
+- `Table.types.ts` - Tipos TypeScript (149 líneas)
+- `Table.stories.tsx` - Stories de Storybook (11 ejemplos)
+- `index.ts` - Exports del módulo
+
+## Referencias
+
+- [Figma Design](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4184-15615&m=dev)
+- `docs/colors.md` - Sistema de colores
+- `docs/typography.md` - Sistema tipográfico
+- `docs/spacing.md` - Sistema de espaciado