@adamosuiteservices/ui 1.2.4 → 1.3.5

package/docs/components/ui/combobox.md

@@ -0,0 +1,328 @@
+# Combobox
+
+Componente de selección avanzado que combina Popover + Command para búsqueda y selección. Soporta selección simple/múltiple, búsqueda filtrable, opciones deshabilitadas, y feedback visual con checkbox o check.
+
+## Importación
+
+```tsx
+import { Combobox } from "@adamosuiteservices/ui/combobox";
+```
+
+## Anatomía
+
+```tsx
+<Combobox
+  options={[
+    { value: "option1", label: "Option 1" },
+    { value: "option2", label: "Option 2", disabled: true },
+  ]}
+  value={selectedValue}
+  onValueChange={setSelectedValue}
+/>
+```
+
+**Componente único**: Internamente usa Popover, Command, Button, Checkbox
+
+## Props Principales
+
+| Prop               | Tipo                                  | Default      | Descripción                                                |
+| ------------------ | ------------------------------------- | ------------ | ---------------------------------------------------------- |
+| `options`          | `ComboboxOption[]`                    | **required** | Array de opciones `{ value, label, disabled? }`            |
+| `value`            | `string \| string[]`                  | -            | Valor controlado (string para single, array para multiple) |
+| `onValueChange`    | `(value: string \| string[]) => void` | -            | Callback al cambiar selección                              |
+| `searchable`       | `boolean`                             | `false`      | Habilita input de búsqueda                                 |
+| `multiple`         | `boolean`                             | `false`      | Permite selección múltiple                                 |
+| `selectedFeedback` | `"checkbox" \| "check"`               | `"checkbox"` | Tipo de indicador visual                                   |
+| `labels`           | `ComboboxLabels`                      | -            | Textos personalizables (ver tabla abajo)                   |
+| `classNames`       | `ComboboxClassNames`                  | -            | Clases CSS por sección (ver tabla abajo)                   |
+
+### ComboboxLabels
+
+| Prop                | Tipo                        | Default                | Descripción                                     |
+| ------------------- | --------------------------- | ---------------------- | ----------------------------------------------- |
+| `placeholder`       | `string`                    | `"Select options..."`  | Texto cuando no hay selección                   |
+| `searchPlaceholder` | `string`                    | `"Search options..."`  | Placeholder del input de búsqueda               |
+| `noItemsFound`      | `string`                    | `"No options found."`  | Mensaje cuando búsqueda no encuentra resultados |
+| `multipleSelected`  | `(count: number) => string` | `"X options selected"` | Función para texto de múltiples seleccionados   |
+
+### ComboboxClassNames
+
+| Prop       | Descripción                                              |
+| ---------- | -------------------------------------------------------- |
+| `trigger`  | Button trigger del popover                               |
+| `popover`  | Contenedor del popover                                   |
+| `command`  | Componente Command root                                  |
+| `input`    | Input de búsqueda                                        |
+| `list`     | Lista de opciones                                        |
+| `empty`    | Mensaje de no resultados                                 |
+| `group`    | Grupo de items                                           |
+| `item`     | Cada opción individual                                   |
+| `checkbox` | Checkbox de selección (si `selectedFeedback="checkbox"`) |
+| `check`    | Icono de check (si `selectedFeedback="check"`)           |
+
+## Patrones de Uso
+
+### Básico (Sin Búsqueda)
+
+```tsx
+const frameworks = [
+  { value: "next", label: "Next.js" },
+  { value: "remix", label: "Remix" },
+  { value: "astro", label: "Astro" },
+];
+
+<Combobox
+  options={frameworks}
+  labels={{ placeholder: "Select framework..." }}
+/>;
+```
+
+### Con Búsqueda
+
+```tsx
+<Combobox
+  searchable
+  options={frameworks}
+  labels={{
+    placeholder: "Select framework...",
+    searchPlaceholder: "Search frameworks...",
+    noItemsFound: "No framework found.",
+  }}
+/>
+```
+
+### Selección Simple Controlada
+
+```tsx
+const [value, setValue] = useState("");
+
+<Combobox
+  searchable
+  options={frameworks}
+  value={value}
+  onValueChange={(newValue) => setValue(newValue as string)}
+  labels={{ placeholder: "Select framework..." }}
+/>;
+```
+
+### Selección Múltiple
+
+```tsx
+const [values, setValues] = useState<string[]>([]);
+
+<Combobox
+  searchable
+  multiple
+  options={frameworks}
+  value={values}
+  onValueChange={(newValues) => setValues(newValues as string[])}
+  labels={{
+    placeholder: "Select frameworks...",
+    multipleSelected: (count) => `${count} frameworks selected`,
+  }}
+/>;
+```
+
+### Con Feedback de Check
+
+```tsx
+<Combobox
+  searchable
+  options={frameworks}
+  selectedFeedback="check"
+  labels={{ placeholder: "Select option..." }}
+/>
+```
+
+**Diferencia**: `"checkbox"` muestra checkboxes a la izquierda, `"check"` muestra ícono check a la derecha.
+
+### Opciones Deshabilitadas
+
+```tsx
+const options = [
+  { value: "us", label: "United States" },
+  { value: "ca", label: "Canada" },
+  { value: "mx", label: "Mexico", disabled: true },
+];
+
+<Combobox
+  searchable
+  options={options}
+  labels={{ placeholder: "Select country..." }}
+/>;
+```
+
+### Labels Personalizadas
+
+```tsx
+<Combobox
+  searchable
+  multiple
+  options={frameworks}
+  labels={{
+    placeholder: "Choose your stack...",
+    searchPlaceholder: "Type to filter...",
+    noItemsFound: "No matching technologies found.",
+    multipleSelected: (count) =>
+      `${count} ${count === 1 ? "tech" : "techs"} selected`,
+  }}
+/>
+```
+
+### Styling Personalizado
+
+```tsx
+<Combobox
+  searchable
+  options={frameworks}
+  classNames={{
+    trigger: "border-2 border-blue-500 w-64",
+    popover: "border-blue-200 shadow-lg",
+    item: "rounded px-3 py-2 hover:bg-blue-50",
+    check: "text-blue-600",
+  }}
+/>
+```
+
+### En Formulario
+
+```tsx
+import { Field, FieldLabel } from "@adamosuiteservices/ui/field";
+
+function FormExample() {
+  const [framework, setFramework] = useState("");
+  const [country, setCountry] = useState("");
+
+  return (
+    <form className="space-y-4">
+      <Field>
+        <FieldLabel>Framework</FieldLabel>
+        <Combobox
+          searchable
+          options={frameworks}
+          value={framework}
+          onValueChange={(value) => setFramework(value as string)}
+          labels={{ placeholder: "Select framework..." }}
+        />
+      </Field>
+
+      <Field>
+        <FieldLabel>Country</FieldLabel>
+        <Combobox
+          searchable
+          options={countries}
+          value={country}
+          onValueChange={(value) => setCountry(value as string)}
+          selectedFeedback="check"
+          labels={{ placeholder: "Select country..." }}
+        />
+      </Field>
+
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+### Multiple con Clear All
+
+```tsx
+const [values, setValues] = useState<string[]>([]);
+
+<div className="space-y-2">
+  <Combobox
+    searchable
+    multiple
+    options={frameworks}
+    value={values}
+    onValueChange={(newValues) => setValues(newValues as string[])}
+  />
+
+  {values.length > 0 && (
+    <button
+      onClick={() => setValues([])}
+      className="text-xs text-blue-600 hover:text-blue-800 underline"
+    >
+      Clear all
+    </button>
+  )}
+</div>;
+```
+
+## Modos de Operación
+
+### Single Selection
+
+- `multiple={false}` (default)
+- `value` es `string`
+- Click en opción cierra el popover automáticamente
+- Seleccionar opción ya seleccionada la deselecciona
+
+### Multiple Selection
+
+- `multiple={true}`
+- `value` es `string[]`
+- Click en opción NO cierra el popover
+- Checkboxes permiten toggle de múltiples opciones
+- Display muestra contador cuando >1 seleccionado
+
+## Casos de Uso Comunes
+
+**Framework selector**: Selección de tecnología con búsqueda  
+**Country/City picker**: Selección geográfica con opciones deshabilitadas  
+**Tags/Categories**: Selección múltiple de categorías  
+**Settings filters**: Filtros multi-selección en dashboards  
+**User assignment**: Asignar múltiples usuarios a tarea  
+**Language selector**: Selección de idioma con búsqueda
+
+## Estados Internos
+
+### Display Text
+
+- **Sin selección**: Muestra `labels.placeholder`
+- **Single selection**: Muestra `label` de la opción seleccionada
+- **Multiple (1 item)**: Muestra `label` del único item seleccionado
+- **Multiple (>1 items)**: Muestra resultado de `labels.multipleSelected(count)`
+
+### Popover State
+
+- Controlado internamente con `useState`
+- Se cierra automáticamente en single selection
+- Permanece abierto en multiple selection
+
+## Accesibilidad
+
+- ✅ **ARIA**: Button tiene `role="combobox"` y `aria-expanded`
+- ✅ **Navegación teclado**: Arrow keys para navegar opciones, Enter para seleccionar, Escape para cerrar
+- ✅ **Screen readers**: Anuncia opciones y estado seleccionado
+- ✅ **Focus management**: Focus automático en input cuando searchable
+- ✅ **Disabled options**: No seleccionables, estilo visual diferente
+
+## Notas de Implementación
+
+- **Composición**: Usa Popover + Command + Button + Checkbox internamente
+- **Búsqueda**: Command component maneja fuzzy search automáticamente
+- **Estado interno**: Soporta modo controlado y no controlado
+- **Tipo de value**: Cambia según `multiple` (string vs string[])
+- **selectedFeedback**:
+  - `"checkbox"`: Muestra Checkbox a la izquierda de cada opción
+  - `"check"`: Muestra CheckIcon a la derecha (agrega `pr-8` automáticamente)
+- **Popover alignment**: `align="start"` por defecto para alinear con trigger
+- **ChevronDownIcon**: Se muestra en trigger con `opacity-50`
+- **No animation**: Selección instantánea, sin delays
+
+## Troubleshooting
+
+**Value no cambia**: Verifica que uses `onValueChange` en modo controlado  
+**Búsqueda no funciona**: Asegúrate de pasar `searchable={true}`  
+**Multiple selection cierra popover**: Verifica que `multiple={true}` esté activo  
+**Labels incorrectas en multiple**: Usa función `multipleSelected` para pluralización  
+**Tipo de value incorrecto**: Single usa `string`, Multiple usa `string[]`  
+**Checkboxes no aparecen**: Solo aparecen cuando `selectedFeedback="checkbox"` (default)  
+**Check icon no visible**: Solo aparece cuando `selectedFeedback="check"`
+
+## Referencias
+
+- **Radix UI Popover**: https://www.radix-ui.com/primitives/docs/components/popover
+- **Command Component**: Ver documentación de Command
+- **ARIA Combobox**: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/