siesa-ui-kit 1.0.3 → 1.0.5

package/src/components/Radio/Radio.types.ts

@@ -0,0 +1,122 @@
+import type { InputHTMLAttributes } from 'react';
+
+/**
+ * Estados visuales del Radio Button
+ *
+ * @see Radio.tsx - Implementación del componente
+ */
+export type RadioState = 'default' | 'hover' | 'focus' | 'disabled';
+
+/**
+ * Props del componente Radio
+ *
+ * Extiende las props nativas de HTMLInputElement excepto 'type' y 'size'
+ * que están manejados internamente por el componente.
+ *
+ * @see docs/colors.md - Sistema de colores para estados
+ * @see docs/typography.md - Tipografía para labels y descriptions
+ * @see docs/spacing.md - Espaciado entre elementos
+ *
+ * @example
+ * ```tsx
+ * // Radio simple
+ * <Radio
+ *   label="Accept terms"
+ *   value="accept"
+ *   name="terms"
+ *   checked={accepted}
+ *   onChange={(e) => setAccepted(e.target.checked)}
+ * />
+ *
+ * // Radio con description
+ * <Radio
+ *   label="Allow tickets to be resold"
+ *   description="Customers can resell or transfer their tickets"
+ *   value="resell"
+ *   name="ticketOptions"
+ *   checked={resellAllowed}
+ *   onChange={(e) => setResellAllowed(e.target.checked)}
+ * />
+ *
+ * // Radio disabled
+ * <Radio
+ *   label="Premium feature"
+ *   description="Upgrade to access this feature"
+ *   disabled
+ *   value="premium"
+ *   name="features"
+ * />
+ * ```
+ */
+export interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'size'> {
+  /**
+   * Etiqueta del radio button
+   *
+   * Se muestra con tipografía Label Small (14px Bold) según sistema de diseño.
+   *
+   * @see docs/typography.md - Label Small (text-sm font-bold)
+   */
+  label?: string;
+
+  /**
+   * Descripción debajo del label
+   *
+   * Se muestra con tipografía Paragraph Small (14px Regular) según sistema de diseño.
+   *
+   * @see docs/typography.md - Paragraph Small (text-sm font-normal)
+   */
+  description?: string;
+
+  /**
+   * Si el radio está seleccionado
+   *
+   * Controla el estado checked del radio button. En grupos de radio buttons,
+   * solo uno puede estar checked a la vez.
+   *
+   * @default false
+   */
+  checked?: boolean;
+
+  /**
+   * Valor del radio button (requerido para grupos)
+   *
+   * Identifica el valor único de este radio button dentro de un grupo.
+   * Es esencial para manejar la selección en grupos de radio buttons.
+   */
+  value?: string | number;
+
+  /**
+   * Nombre del grupo de radio buttons
+   *
+   * Agrupa múltiples radio buttons para permitir selección única.
+   * Todos los radios con el mismo `name` pertenecen al mismo grupo.
+   */
+  name?: string;
+
+  /**
+   * Clases CSS adicionales
+   *
+   * Permite extender los estilos del componente con clases de Tailwind CSS
+   * o clases personalizadas.
+   */
+  className?: string;
+
+  /**
+   * Callback cuando el estado del radio cambia
+   *
+   * Se ejecuta cuando el usuario selecciona o deselecciona el radio button.
+   *
+   * @param event - Evento de cambio del input nativo
+   *
+   * @example
+   * ```tsx
+   * <Radio
+   *   onChange={(e) => {
+   *     console.log('Checked:', e.target.checked);
+   *     console.log('Value:', e.target.value);
+   *   }}
+   * />
+   * ```
+   */
+  onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+}

package/src/components/Select/README.md

@@ -0,0 +1,299 @@
+# Select Component
+
+Componente Select (dropdown) del sistema de diseño Siesa con soporte completo de dark mode, estados interactivos y accesibilidad.
+
+## Características
+
+- ✓ Soporte completo de dark mode
+- ✓ Keyboard navigation (Arrow keys, Enter, Escape)
+- ✓ Click outside para cerrar el menú
+- ✓ TypeScript con types estrictos
+- ✓ Accesibilidad con ARIA labels
+- ✓ Estados: Default, Hover, Focus, Disabled, Error
+- ✓ Transiciones suaves
+- ✓ Opciones deshabilitadas individuales
+- ✓ Label y descripción configurables
+- ✓ Menu header opcional
+- ✓ Full width opcional
+- ✓ Posición del menú configurable (top/bottom)
+
+## Instalación
+
+```tsx
+import { Select } from '@/components/Select';
+import type { SelectOption } from '@/components/Select';
+```
+
+## Uso Básico
+
+```tsx
+import { Select } from '@/components/Select';
+import { useState } from 'react';
+
+function MyComponent() {
+  const [value, setValue] = useState<string | number>('');
+
+  const options = [
+    { value: '1', label: 'Opción 1' },
+    { value: '2', label: 'Opción 2' },
+    { value: '3', label: 'Opción 3' },
+  ];
+
+  return (
+    <Select
+      options={options}
+      value={value}
+      onChange={setValue}
+      placeholder="Selecciona una opción"
+      label="Label"
+      description="Texto descriptivo opcional"
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Descripción |
+|------|------|---------|-------------|
+| `options` | `SelectOption[]` | **required** | Array de opciones disponibles |
+| `value` | `string \| number` | `undefined` | Valor seleccionado (controlado) |
+| `defaultValue` | `string \| number` | `undefined` | Valor inicial (no controlado) |
+| `placeholder` | `string` | `'Seleccionar...'` | Texto cuando no hay selección |
+| `disabled` | `boolean` | `false` | Si el select está deshabilitado |
+| `error` | `boolean` | `false` | Si muestra estado de error |
+| `label` | `string` | `undefined` | Label del select |
+| `description` | `string` | `undefined` | Texto descriptivo debajo del label (antes del trigger) |
+| `showLabel` | `boolean` | `true` | Muestra el label |
+| `showDescription` | `boolean` | `true` | Muestra la descripción |
+| `menuHeader` | `string` | `undefined` | Header opcional al inicio del menú |
+| `onChange` | `(value: string \| number) => void` | `undefined` | Handler de cambio |
+| `className` | `string` | `''` | Clases CSS adicionales |
+| `triggerClassName` | `string` | `''` | Clases para el trigger |
+| `menuClassName` | `string` | `''` | Clases para el menú |
+| `ariaLabel` | `string` | `undefined` | Label ARIA |
+| `id` | `string` | `undefined` | ID para asociar con label |
+| `name` | `string` | `undefined` | Nombre para formularios |
+| `required` | `boolean` | `false` | Si es campo requerido |
+| `menuPosition` | `'top' \| 'bottom'` | `'bottom'` | Posición del menú |
+| `fullWidth` | `boolean` | `false` | Ancho completo |
+
+### SelectOption
+
+```tsx
+interface SelectOption {
+  value: string | number;
+  label: string;
+  disabled?: boolean;
+  icon?: ReactNode;
+}
+```
+
+## Ejemplos
+
+### Con Label y Descripción
+
+```tsx
+<Select
+  options={options}
+  value={value}
+  onChange={setValue}
+  label="País"
+  description="Selecciona tu país de residencia"
+  placeholder="Selecciona un país"
+/>
+```
+
+### Con Estado de Error
+
+```tsx
+<Select
+  options={options}
+  value={value}
+  onChange={setValue}
+  label="País"
+  error={!value && submitted}
+  description="El país es requerido"
+  required
+/>
+```
+
+### Con Opciones Deshabilitadas
+
+```tsx
+const options = [
+  { value: 'active', label: 'Activo' },
+  { value: 'pending', label: 'Pendiente' },
+  { value: 'inactive', label: 'Inactivo', disabled: true },
+];
+
+<Select
+  options={options}
+  value={value}
+  onChange={setValue}
+  placeholder="Selecciona un estado"
+/>
+```
+
+### Full Width
+
+```tsx
+<Select
+  options={options}
+  value={value}
+  onChange={setValue}
+  fullWidth
+/>
+```
+
+### Menú hacia Arriba
+
+```tsx
+<Select
+  options={options}
+  value={value}
+  onChange={setValue}
+  menuPosition="top"
+/>
+```
+
+### En Formularios
+
+```tsx
+<form onSubmit={handleSubmit}>
+  <Select
+    options={countryOptions}
+    value={country}
+    onChange={setCountry}
+    label="País"
+    description="Selecciona tu país de residencia"
+    name="country"
+    required
+    fullWidth
+  />
+
+  <button type="submit">Enviar</button>
+</form>
+```
+
+## Estados
+
+### Default
+Estado normal del select, listo para interacción.
+
+### Hover
+Al pasar el mouse sobre el trigger, se muestra un overlay sutil.
+
+### Focus
+Al hacer foco en el select, muestra un focus ring con el color primario.
+
+### Open
+Cuando el menú está abierto, muestra las opciones disponibles.
+
+### Disabled
+El select no puede ser interactuado, con opacity reducida.
+
+### Error
+Muestra bordes y colores de error, con mensaje de error opcional.
+
+## Navegación por Teclado
+
+- **Click / Enter / Space**: Abrir/cerrar el menú
+- **Arrow Down**: Navegar a la siguiente opción
+- **Arrow Up**: Navegar a la opción anterior
+- **Enter**: Seleccionar la opción enfocada
+- **Escape**: Cerrar el menú
+- **Tab**: Navegar fuera del select
+
+## Accesibilidad
+
+- ✓ Labels semánticos con `<label>` asociado
+- ✓ ARIA roles (`listbox`, `option`)
+- ✓ ARIA states (`aria-expanded`, `aria-selected`, `aria-disabled`)
+- ✓ ARIA labels para screen readers
+- ✓ Keyboard navigation completa
+- ✓ Focus visible y claro
+- ✓ Campos requeridos indicados con asterisco
+
+## Dark Mode
+
+El componente se adapta automáticamente al modo oscuro cuando la clase `dark` está presente en el elemento `<html>`.
+
+```tsx
+// Funciona automáticamente
+<Select
+  options={options}
+  value={value}
+  onChange={setValue}
+/>
+```
+
+Todos los colores, bordes y sombras se ajustan según el modo activo.
+
+## Especificaciones de Figma
+
+Este componente implementa las especificaciones del diseño de Figma (node-id: 4165-14710):
+
+- **Trigger Button**: `px-3 py-2`, `rounded-lg`, `text-sm`, `gap-3`, `leading-5`
+- **Menu**: `p-1`, `max-h-40` (160px), `border-0`, `mt-1` (4px spacing), `rounded-md`, `bg-background-secondary`
+- **Menu Item**: `px-2 pr-2.5 py-0.5`, `text-[10px] leading-[12px]` (Label XXSmall), `font-bold`, `rounded-md`
+- **Label/Description**: Van ANTES del trigger con `gap-1` (4px) entre ellos
+- **Menu Header**: Opcional, `text-[10px] leading-[12px]`, color terciario
+- **Hover overlay**: `rgba(0,0,0,0.024)` en light mode
+
+## Mejores Prácticas
+
+1. **Usa labels descriptivos**: Siempre incluye un label claro para el select
+2. **Marca campos requeridos**: Usa `required` y muestra el asterisco
+3. **Proporciona descripción**: Ayuda al usuario con la prop `description`
+4. **Maneja errores**: Usa la prop `error` combinada con `description` para mostrar mensajes de error
+5. **Opciones claras**: Usa labels descriptivos para las opciones
+6. **Deshabilita opciones cuando sea necesario**: Usa `disabled: true` en opciones no disponibles
+7. **Menu header**: Usa `menuHeader` para agrupar opciones cuando sea relevante
+
+## Tokens del Sistema Utilizados
+
+### Colores
+- `bg-bg-primary` - Fondo del trigger (white)
+- `border-border-primary` - Borde del trigger
+- `text-content-primary` - Texto principal
+- `text-content-secondary` - Texto del placeholder
+- `bg-background-secondary` - Fondo del menú
+- `bg-primary-custom-600` - Fondo del item seleccionado (hover)
+- `text-primary-inverse-content` - Texto del item seleccionado
+
+### Dark Mode
+- `dark:bg-dark-bg-primary` - Fondo en dark mode
+- `dark:border-dark-border-primary` - Borde en dark mode
+- `dark:text-dark-content-primary` - Texto en dark mode
+- `dark:focus:ring-dark-border-custom` - Focus ring en dark mode
+
+### Tipografía
+- `text-sm` - Paragraph Regular (14px) para el trigger, `leading-5` (20px line-height)
+- `text-[10px] leading-[12px]` - Label XXSmall (10px) para los items del menu
+- `font-bold` - Peso bold para labels e items
+
+### Espaciado
+- `px-3 py-2` - Padding del trigger (12px/8px)
+- `gap-3` - Gap interno del trigger (12px)
+- `p-1` - Padding del menú (4px)
+- `gap-0.5` - Gap entre items (2px)
+- `px-2 pr-2.5 py-0.5` - Padding de items (8px/10px/2px)
+
+## Archivos del Componente
+
+```
+Select/
+├── Select.tsx           # Componente principal
+├── Select.types.ts      # TypeScript types
+├── Select.stories.tsx   # Storybook stories
+├── icons.tsx            # Iconos (ChevronUpDown, Check)
+├── index.ts             # Exports
+└── README.md            # Documentación
+```
+
+## Referencias
+
+- **Figma**: [Select Component](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4165-14710)
+- **Código**: `src/components/Select/Select.tsx`
+- **Docs**: `docs/colors.md`, `docs/typography.md`, `docs/spacing.md`