@adamosuiteservices/ui 2.11.21 → 2.12.0

package/docs/components/ui/select.md

@@ -1,352 +1,357 @@
-# Select
-
-Dropdown de selección con búsqueda y scroll. Basado en Radix UI con 10 subcomponentes.
-
-## Descripción
-
-El componente `Select` muestra una lista de opciones en las que el usuario puede seleccionar una opción de la lista.
-
-## Importación
-
-```typescript
-import {
-  Select,
-  SelectContent,
-  SelectGroup,
-  SelectItem,
-  SelectLabel,
-  SelectTrigger,
-  SelectValue,
-} from "@adamosuiteservices/ui/select";
-```
-
-## Anatomía
-
-```tsx
-<Select>
-  <SelectTrigger className="w-[180px]">
-    <SelectValue placeholder="Select option" />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value="option1">Option 1</SelectItem>
-    <SelectItem value="option2">Option 2</SelectItem>
-  </SelectContent>
-</Select>
-```
-
-**Componentes**: 10 (Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectLabel, SelectSeparator, SelectScrollUpButton, SelectScrollDownButton)
-
-## Props
-
-### Select (Root)
-
-| Prop            | Tipo                      | Descripción                  |
-| --------------- | ------------------------- | ---------------------------- |
-| `defaultValue`  | `string`                  | Valor inicial (uncontrolled) |
-| `value`         | `string`                  | Valor controlado             |
-| `onValueChange` | `(value: string) => void` | Callback al cambiar valor    |
-| `disabled`      | `boolean`                 | Deshabilita el select        |
-| `required`      | `boolean`                 | Campo requerido              |
-| `name`          | `string`                  | Nombre (formularios)         |
-
-### SelectTrigger
-
-| Prop        | Tipo                | Descripción            |
-| ----------- | ------------------- | ---------------------- |
-| `size`      | `"sm" \| "default"` | Tamaño del trigger     |
-| `className` | `string`            | Clases CSS adicionales |
-
-**Nota**: `size="sm"` = h-8, `size="default"` = h-9
-
-### SelectValue
-
-| Prop          | Tipo     | Descripción                   |
-| ------------- | -------- | ----------------------------- |
-| `placeholder` | `string` | Texto cuando no hay selección |
-
-### SelectContent
-
-| Prop        | Tipo                           | Descripción            |
-| ----------- | ------------------------------ | ---------------------- |
-| `position`  | `"popper" \| "item-aligned"`   | Posición del dropdown  |
-| `align`     | `"start" \| "center" \| "end"` | Alineación horizontal  |
-| `className` | `string`                       | Clases CSS adicionales |
-
-### SelectItem
-
-| Prop        | Tipo      | Descripción            |
-| ----------- | --------- | ---------------------- |
-| `value`     | `string`  | Valor único del item   |
-| `disabled`  | `boolean` | Deshabilita este item  |
-| `className` | `string`  | Clases CSS adicionales |
-
-### SelectLabel
-
-| Prop        | Tipo     | Descripción                        |
-| ----------- | -------- | ---------------------------------- |
-| `className` | `string` | Clases CSS para el label del grupo |
-
-## Patrones de Uso
-
-### Básico
-
-```tsx
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from "@adamosuiteservices/ui/select";
-
-<Select>
-  <SelectTrigger className="w-[180px]">
-    <SelectValue placeholder="Select a theme" />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value="light">Light</SelectItem>
-    <SelectItem value="dark">Dark</SelectItem>
-    <SelectItem value="system">System</SelectItem>
-  </SelectContent>
-</Select>;
-```
-
-### Controlado
-
-```tsx
-import { useState } from "react";
-
-function App() {
-  const [value, setValue] = useState("");
-
-  return (
-    <Select value={value} onValueChange={setValue}>
-      <SelectTrigger className="w-[180px]">
-        <SelectValue placeholder="Select a language" />
-      </SelectTrigger>
-      <SelectContent>
-        <SelectItem value="javascript">JavaScript</SelectItem>
-        <SelectItem value="typescript">TypeScript</SelectItem>
-        <SelectItem value="python">Python</SelectItem>
-      </SelectContent>
-    </Select>
-  );
-}
-```
-
-### Con Label
-
-```tsx
-import { Label } from "@adamosuiteservices/ui/label";
-
-<div className="grid w-full max-w-sm items-center gap-2">
-  <Label htmlFor="email-provider">Email provider</Label>
-  <Select>
-    <SelectTrigger id="email-provider">
-      <SelectValue placeholder="Select a provider" />
-    </SelectTrigger>
-    <SelectContent>
-      <SelectItem value="gmail">Gmail</SelectItem>
-      <SelectItem value="outlook">Outlook</SelectItem>
-      <SelectItem value="yahoo">Yahoo</SelectItem>
-    </SelectContent>
-  </Select>
-</div>;
-```
-
-### Con Grupos
-
-```tsx
-import { SelectGroup, SelectLabel } from "@adamosuiteservices/ui/select";
-
-<Select>
-  <SelectTrigger className="w-[200px]">
-    <SelectValue placeholder="Select a fruit" />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectGroup>
-      <SelectLabel>Fruits</SelectLabel>
-      <SelectItem value="apple">Apple</SelectItem>
-      <SelectItem value="banana">Banana</SelectItem>
-      <SelectItem value="blueberry">Blueberry</SelectItem>
-    </SelectGroup>
-  </SelectContent>
-</Select>;
-```
-
-### Con Iconos
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<Select>
-  <SelectTrigger className="w-[200px]">
-    <SelectValue placeholder="Select a fruit" />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value="apple">
-      <Icon symbol="nutrition" className="mr-2 text-lg" />
-      Apple
-    </SelectItem>
-    <SelectItem value="banana">
-      <Icon symbol="nutrition" className="mr-2 text-lg" />
-      Banana
-    </SelectItem>
-    <SelectItem value="cherry">
-      <Icon symbol="nutrition" className="mr-2 text-lg" />
-      Cherry
-    </SelectItem>
-  </SelectContent>
-</Select>;
-```
-
-### Tamaño Pequeño
-
-```tsx
-<Select>
-  <SelectTrigger size="sm" className="w-[160px]">
-    <SelectValue placeholder="Small select" />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value="xs">Extra Small</SelectItem>
-    <SelectItem value="sm">Small</SelectItem>
-    <SelectItem value="md">Medium</SelectItem>
-  </SelectContent>
-</Select>
-```
-
-### Scrollable
-
-```tsx
-<Select>
-  <SelectTrigger className="w-[280px]">
-    <SelectValue placeholder="Select a timezone" />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectGroup>
-      <SelectLabel>North America</SelectLabel>
-      <SelectItem value="est">Eastern Standard Time (EST)</SelectItem>
-      <SelectItem value="cst">Central Standard Time (CST)</SelectItem>
-      <SelectItem value="mst">Mountain Standard Time (MST)</SelectItem>
-      <SelectItem value="pst">Pacific Standard Time (PST)</SelectItem>
-    </SelectGroup>
-    <SelectGroup>
-      <SelectLabel>Europe & Africa</SelectLabel>
-      <SelectItem value="gmt">Greenwich Mean Time (GMT)</SelectItem>
-      <SelectItem value="cet">Central European Time (CET)</SelectItem>
-      <SelectItem value="eet">Eastern European Time (EET)</SelectItem>
-    </SelectGroup>
-  </SelectContent>
-</Select>
-```
-
-### Con Validación
-
-```tsx
-import { Button } from "@adamosuiteservices/ui/button";
-
-function App() {
-  const [value, setValue] = useState("");
-  const [error, setError] = useState("");
-
-  const handleValidate = () => {
-    if (!value) {
-      setError("Please select a priority level");
-    } else {
-      setError("");
-    }
-  };
-
-  return (
-    <div className="space-y-4">
-      <div className="grid w-full max-w-sm items-center gap-2">
-        <Label htmlFor="priority">
-          Priority level <span className="text-destructive">*</span>
-        </Label>
-        <Select value={value} onValueChange={setValue}>
-          <SelectTrigger
-            id="priority"
-            className={error ? "border-destructive" : ""}
-          >
-            <SelectValue placeholder="Select priority" />
-          </SelectTrigger>
-          <SelectContent>
-            <SelectItem value="low">Low</SelectItem>
-            <SelectItem value="medium">Medium</SelectItem>
-            <SelectItem value="high">High</SelectItem>
-          </SelectContent>
-        </Select>
-        {error && <p className="text-destructive text-sm">{error}</p>}
-      </div>
-      <Button onClick={handleValidate} variant="outline">
-        Validate Selection
-      </Button>
-    </div>
-  );
-}
-```
-
-### Deshabilitado
-
-```tsx
-<Select disabled>
-  <SelectTrigger className="w-[180px]">
-    <SelectValue placeholder="Select a theme" />
-  </SelectTrigger>
-  <SelectContent>
-    <SelectItem value="light">Light</SelectItem>
-    <SelectItem value="dark">Dark</SelectItem>
-  </SelectContent>
-</Select>
-```
-
-## Casos de Uso### Configuración
-
-```tsx## Casos de Uso
-
-**Selección simple**: Elegir una opción de lista larga
-**Formularios**: País, estado, categoría, idioma
-**Filtros**: Ordenar por, filtrar por tipo
-**Settings**: Theme, tamaño de texto, timezone
-**Navegación**: Cambio rápido entre secciones/vistas
-
-## Estilos Base
-
-- **Trigger height**: `h-9` (default), `h-8` (sm)
-- **Border**: `border-input` con `shadow-xs`
-- **Focus**: `ring-ring/50` con `ring-[3px]`
-- **Content**: `bg-popover` con `shadow-md` y `border`
-- **Item hover**: `bg-accent text-accent-foreground`
-- **Check icon**: Icon `check` con `text-lg` en item seleccionado
-
-## Accesibilidad
-
-- ✅ **Role**: `role="combobox"` en trigger, `role="option"` en items
-- ✅ **ARIA**: `aria-expanded`, `aria-controls`, `aria-selected`
-- ✅ **Keyboard**: Arrow keys, Enter, Escape, Type-ahead search
-- ✅ **Focus**: Focus trap en content abierto
-- ✅ **Label**: Asociar con `id` en SelectTrigger
-
-## Notas de Implementación
-
-- **Radix UI**: Basado en `@radix-ui/react-select`
-- **Portal**: SelectContent se renderiza en portal
-- **Iconos**: Icon `expand_more` en trigger, Icon `check` en items seleccionados, Icon `expand_less`/`expand_more` en scroll buttons
-- **Scroll buttons**: Auto-mostrados cuando content es scrollable
-- **Position**: `popper` (default) para absolute positioning
-- **Type-ahead**: Buscar items escribiendo
-
-## Troubleshooting
-
-**Dropdown no abre**: Verifica que SelectContent esté dentro de Select
-**No muestra valor**: Asegura que `value` del item seleccionado coincida con `value` del Select
-**Portal issues**: SelectContent usa Portal, puede afectar z-index
-**Width mismatch**: SelectTrigger necesita `className="w-[Xpx]"` explícito
-**Scroll no funciona**: Scroll automático cuando items exceden max-height
-**Placeholder no desaparece**: SelectValue.placeholder solo visible cuando no hay valor
-
-## Referencias
-
-- **Radix UI Select**: <https://www.radix-ui.com/primitives/docs/components/select>
-- **shadcn/ui Select**: <https://ui.shadcn.com/docs/components/select>
-```
+# Select
+
+Dropdown de selección con búsqueda y scroll. Basado en Radix UI con 10 subcomponentes.
+
+## Descripción
+
+El componente `Select` muestra una lista de opciones en las que el usuario puede seleccionar una opción de la lista.
+
+## Importación
+
+```typescript
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectTrigger,
+  SelectValue,
+} from "@adamosuiteservices/ui/select";
+```
+
+## Anatomía
+
+```tsx
+<Select>
+  <SelectTrigger className="w-[180px]">
+    <SelectValue placeholder="Select option" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="option1">Option 1</SelectItem>
+    <SelectItem value="option2">Option 2</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+**Componentes**: 10 (Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectLabel, SelectSeparator, SelectScrollUpButton, SelectScrollDownButton)
+
+## Props
+
+### Select (Root)
+
+| Prop            | Tipo                      | Descripción                  |
+| --------------- | ------------------------- | ---------------------------- |
+| `defaultValue`  | `string`                  | Valor inicial (uncontrolled) |
+| `value`         | `string`                  | Valor controlado             |
+| `onValueChange` | `(value: string) => void` | Callback al cambiar valor    |
+| `disabled`      | `boolean`                 | Deshabilita el select        |
+| `required`      | `boolean`                 | Campo requerido              |
+| `name`          | `string`                  | Nombre (formularios)         |
+
+### SelectTrigger
+
+| Prop        | Tipo                | Descripción            |
+| ----------- | ------------------- | ---------------------- |
+| `size`      | `"sm" \| "default"` | Tamaño del trigger     |
+| `className` | `string`            | Clases CSS adicionales |
+
+**Nota**: `size="sm"` = h-9, `size="default"` = h-10
+
+### SelectValue
+
+| Prop          | Tipo     | Descripción                   |
+| ------------- | -------- | ----------------------------- |
+| `placeholder` | `string` | Texto cuando no hay selección |
+
+### SelectContent
+
+| Prop        | Tipo                           | Descripción            |
+| ----------- | ------------------------------ | ---------------------- |
+| `position`  | `"popper" \| "item-aligned"`   | Posición del dropdown  |
+| `align`     | `"start" \| "center" \| "end"` | Alineación horizontal  |
+| `className` | `string`                       | Clases CSS adicionales |
+
+### SelectItem
+
+| Prop        | Tipo      | Descripción            |
+| ----------- | --------- | ---------------------- |
+| `value`     | `string`  | Valor único del item   |
+| `disabled`  | `boolean` | Deshabilita este item  |
+| `className` | `string`  | Clases CSS adicionales |
+
+### SelectLabel
+
+| Prop        | Tipo     | Descripción                        |
+| ----------- | -------- | ---------------------------------- |
+| `className` | `string` | Clases CSS para el label del grupo |
+
+## Patrones de Uso
+
+### Básico
+
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@adamosuiteservices/ui/select";
+
+<Select>
+  <SelectTrigger className="w-[180px]">
+    <SelectValue placeholder="Select a theme" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="light">Light</SelectItem>
+    <SelectItem value="dark">Dark</SelectItem>
+    <SelectItem value="system">System</SelectItem>
+  </SelectContent>
+</Select>;
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react";
+
+function App() {
+  const [value, setValue] = useState("");
+
+  return (
+    <Select value={value} onValueChange={setValue}>
+      <SelectTrigger className="w-[180px]">
+        <SelectValue placeholder="Select a language" />
+      </SelectTrigger>
+      <SelectContent>
+        <SelectItem value="javascript">JavaScript</SelectItem>
+        <SelectItem value="typescript">TypeScript</SelectItem>
+        <SelectItem value="python">Python</SelectItem>
+      </SelectContent>
+    </Select>
+  );
+}
+```
+
+### Con Label
+
+```tsx
+import { Label } from "@adamosuiteservices/ui/label";
+
+<div className="grid w-full max-w-sm items-center gap-2">
+  <Label htmlFor="email-provider">Email provider</Label>
+  <Select>
+    <SelectTrigger id="email-provider">
+      <SelectValue placeholder="Select a provider" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="gmail">Gmail</SelectItem>
+      <SelectItem value="outlook">Outlook</SelectItem>
+      <SelectItem value="yahoo">Yahoo</SelectItem>
+    </SelectContent>
+  </Select>
+</div>;
+```
+
+### Con Grupos
+
+```tsx
+import { SelectGroup, SelectLabel } from "@adamosuiteservices/ui/select";
+
+<Select>
+  <SelectTrigger className="w-[200px]">
+    <SelectValue placeholder="Select a fruit" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectLabel>Fruits</SelectLabel>
+      <SelectItem value="apple">Apple</SelectItem>
+      <SelectItem value="banana">Banana</SelectItem>
+      <SelectItem value="blueberry">Blueberry</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>;
+```
+
+### Con Iconos
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<Select>
+  <SelectTrigger className="w-[200px]">
+    <SelectValue placeholder="Select a fruit" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="apple">
+      <Icon symbol="nutrition" className="mr-2 text-lg" />
+      Apple
+    </SelectItem>
+    <SelectItem value="banana">
+      <Icon symbol="nutrition" className="mr-2 text-lg" />
+      Banana
+    </SelectItem>
+    <SelectItem value="cherry">
+      <Icon symbol="nutrition" className="mr-2 text-lg" />
+      Cherry
+    </SelectItem>
+  </SelectContent>
+</Select>;
+```
+
+### Tamaño Pequeño
+
+```tsx
+<Select>
+  <SelectTrigger size="sm" className="w-[160px]">
+    <SelectValue placeholder="Small select" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="xs">Extra Small</SelectItem>
+    <SelectItem value="sm">Small</SelectItem>
+    <SelectItem value="md">Medium</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Scrollable
+
+```tsx
+<Select>
+  <SelectTrigger className="w-[280px]">
+    <SelectValue placeholder="Select a timezone" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectLabel>North America</SelectLabel>
+      <SelectItem value="est">Eastern Standard Time (EST)</SelectItem>
+      <SelectItem value="cst">Central Standard Time (CST)</SelectItem>
+      <SelectItem value="mst">Mountain Standard Time (MST)</SelectItem>
+      <SelectItem value="pst">Pacific Standard Time (PST)</SelectItem>
+    </SelectGroup>
+    <SelectGroup>
+      <SelectLabel>Europe & Africa</SelectLabel>
+      <SelectItem value="gmt">Greenwich Mean Time (GMT)</SelectItem>
+      <SelectItem value="cet">Central European Time (CET)</SelectItem>
+      <SelectItem value="eet">Eastern European Time (EET)</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+### Con Validación
+
+```tsx
+import { Button } from "@adamosuiteservices/ui/button";
+
+function App() {
+  const [value, setValue] = useState("");
+  const [error, setError] = useState("");
+
+  const handleValidate = () => {
+    if (!value) {
+      setError("Please select a priority level");
+    } else {
+      setError("");
+    }
+  };
+
+  return (
+    <div className="space-y-4">
+      <div className="grid w-full max-w-sm items-center gap-2">
+        <Label htmlFor="priority">
+          Priority level <span className="text-destructive">*</span>
+        </Label>
+        <Select value={value} onValueChange={setValue}>
+          <SelectTrigger
+            id="priority"
+            className={error ? "border-destructive" : ""}
+          >
+            <SelectValue placeholder="Select priority" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="low">Low</SelectItem>
+            <SelectItem value="medium">Medium</SelectItem>
+            <SelectItem value="high">High</SelectItem>
+          </SelectContent>
+        </Select>
+        {error && <p className="text-destructive text-sm">{error}</p>}
+      </div>
+      <Button onClick={handleValidate} variant="outline">
+        Validate Selection
+      </Button>
+    </div>
+  );
+}
+```
+
+### Deshabilitado
+
+```tsx
+<Select disabled>
+  <SelectTrigger className="w-[180px]">
+    <SelectValue placeholder="Select a theme" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="light">Light</SelectItem>
+    <SelectItem value="dark">Dark</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+## Casos de Uso### Configuración
+
+```tsx## Casos de Uso
+
+**Selección simple**: Elegir una opción de lista larga
+**Formularios**: País, estado, categoría, idioma
+**Filtros**: Ordenar por, filtrar por tipo
+**Settings**: Theme, tamaño de texto, timezone
+**Navegación**: Cambio rápido entre secciones/vistas
+
+## Estilos Base
+
+- **Trigger height**: `h-10` (default, 40px), `h-9` (sm, 36px)
+- **Item height**: `h-10` (40px) - consistent with trigger default
+- **Padding**: Trigger uses `px-3` (no vertical padding, height defines size)
+- **Item padding**: `px-3` horizontal, `pr-10` when with check icon
+- **Separators**: Border-bottom between items, removed on last item
+- **Border radius**: Items have rounded corners on first (top) and last (bottom) to match container
+- **Border**: `border-input` con `shadow-xs`
+- **Focus**: `ring-ring/50` con `ring-[3px]`
+- **Content**: `bg-popover` con `shadow-md` y `border`
+- **Item hover**: `bg-accent text-accent-foreground`
+- **Check icon**: Icon `check` con `text-lg` en item seleccionado
+
+## Accesibilidad
+
+- ✅ **Role**: `role="combobox"` en trigger, `role="option"` en items
+- ✅ **ARIA**: `aria-expanded`, `aria-controls`, `aria-selected`
+- ✅ **Keyboard**: Arrow keys, Enter, Escape, Type-ahead search
+- ✅ **Focus**: Focus trap en content abierto
+- ✅ **Label**: Asociar con `id` en SelectTrigger
+
+## Notas de Implementación
+
+- **Radix UI**: Basado en `@radix-ui/react-select`
+- **Portal**: SelectContent se renderiza en portal
+- **Iconos**: Icon `expand_more` en trigger, Icon `check` en items seleccionados, Icon `expand_less`/`expand_more` en scroll buttons
+- **Scroll buttons**: Auto-mostrados cuando content es scrollable
+- **Position**: `popper` (default) para absolute positioning
+- **Type-ahead**: Buscar items escribiendo
+
+## Troubleshooting
+
+**Dropdown no abre**: Verifica que SelectContent esté dentro de Select
+**No muestra valor**: Asegura que `value` del item seleccionado coincida con `value` del Select
+**Portal issues**: SelectContent usa Portal, puede afectar z-index
+**Width mismatch**: SelectTrigger necesita `className="w-[Xpx]"` explícito
+**Scroll no funciona**: Scroll automático cuando items exceden max-height
+**Placeholder no desaparece**: SelectValue.placeholder solo visible cuando no hay valor
+
+## Referencias
+
+- **Radix UI Select**: <https://www.radix-ui.com/primitives/docs/components/select>
+- **shadcn/ui Select**: <https://ui.shadcn.com/docs/components/select>
+```