siesa-ui-kit 1.0.0 → 1.0.2

package/src/components/Select/README.md

@@ -1,299 +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`
+# 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`