@adamosuiteservices/ui 1.6.7 → 1.7.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/combobox.cjs +2 -2
- package/dist/combobox.js +377 -345
- package/dist/components/ui/combobox/combobox.d.ts +20 -1
- package/dist/components/ui/combobox/combobox.stories.d.ts +4 -0
- package/dist/custom-layered-styles.css +1 -1
- package/dist/styles.css +1 -1
- package/docs/components/ui/combobox.md +654 -631
- package/package.json +1 -1
|
@@ -1,631 +1,654 @@
|
|
|
1
|
-
# Combobox
|
|
2
|
-
|
|
3
|
-
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, feedback visual con checkbox o check, placeholder persistente, iconos personalizados, y renderizado completamente personalizable mediante render props.
|
|
4
|
-
|
|
5
|
-
## Importación
|
|
6
|
-
|
|
7
|
-
```tsx
|
|
8
|
-
import { Combobox } from "@adamosuiteservices/ui/combobox";
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
## Anatomía
|
|
12
|
-
|
|
13
|
-
```tsx
|
|
14
|
-
<Combobox
|
|
15
|
-
options={[
|
|
16
|
-
{ value: "option1", label: "Option 1" },
|
|
17
|
-
{ value: "option2", label: "Option 2", disabled: true },
|
|
18
|
-
]}
|
|
19
|
-
value={selectedValue}
|
|
20
|
-
onValueChange={setSelectedValue}
|
|
21
|
-
/>
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
**Componente único**: Internamente usa Popover, Command, Button, Checkbox
|
|
25
|
-
|
|
26
|
-
## Props Principales
|
|
27
|
-
|
|
28
|
-
| Prop | Tipo | Default | Descripción |
|
|
29
|
-
| ----------------------- | --------------------------------------- | ------------ | ----------------------------------------------------------- |
|
|
30
|
-
| `options` | `ComboboxOption[]` | **required** | Array de opciones `{ value, label, disabled? }` |
|
|
31
|
-
| `value` | `string \| string[]` | - | Valor controlado (string para single, array para multiple) |
|
|
32
|
-
| `onValueChange` | `(value: string \| string[]) => void` | - | Callback al cambiar selección |
|
|
33
|
-
| `searchable` | `boolean` | `false` | Habilita input de búsqueda |
|
|
34
|
-
| `multiple` | `boolean` | `false` | Permite selección múltiple |
|
|
35
|
-
| `selectedFeedback` | `"checkbox" \| "check"` | `"checkbox"` | Tipo de indicador visual |
|
|
36
|
-
| `icon` | `ComponentType<{ className?: string }>` | - | Componente de icono opcional para mostrar en el trigger |
|
|
37
|
-
| `alwaysShowPlaceholder` | `boolean` | `false` | Mantiene el placeholder visible junto al valor seleccionado |
|
|
38
|
-
| `valuePosition` | `"left" \| "right"` | `"right"` | Posición del valor cuando alwaysShowPlaceholder es true |
|
|
39
|
-
| `labels` | `ComboboxLabels` | - | Textos personalizables (ver tabla abajo) |
|
|
40
|
-
| `classNames` | `ComboboxClassNames` | - | Clases CSS por sección (ver tabla abajo) |
|
|
41
|
-
| `renders` | `ComboboxRenderProps` | - | Funciones de renderizado personalizadas (ver tabla abajo) |
|
|
42
|
-
|
|
43
|
-
### ComboboxLabels
|
|
44
|
-
|
|
45
|
-
| Prop | Tipo | Default | Descripción |
|
|
46
|
-
| ------------------- | --------------------------- | ---------------------- | ----------------------------------------------- |
|
|
47
|
-
| `placeholder` | `string` | `"Select options..."` | Texto cuando no hay selección |
|
|
48
|
-
| `searchPlaceholder` | `string` | `"Search options..."` | Placeholder del input de búsqueda |
|
|
49
|
-
| `noItemsFound` | `string` | `"No options found."` | Mensaje cuando búsqueda no encuentra resultados |
|
|
50
|
-
| `multipleSelected` | `(count: number) => string` | `"X options selected"` | Función para texto de múltiples seleccionados |
|
|
51
|
-
|
|
52
|
-
### ComboboxClassNames
|
|
53
|
-
|
|
54
|
-
| Prop | Descripción |
|
|
55
|
-
| ---------- | -------------------------------------------------------- |
|
|
56
|
-
| `trigger` | Button trigger del popover |
|
|
57
|
-
| `popover` | Contenedor del popover |
|
|
58
|
-
| `command` | Componente Command root |
|
|
59
|
-
| `input` | Input de búsqueda |
|
|
60
|
-
| `list` | Lista de opciones |
|
|
61
|
-
| `empty` | Mensaje de no resultados |
|
|
62
|
-
| `group` | Grupo de items |
|
|
63
|
-
| `item` | Cada opción individual |
|
|
64
|
-
| `checkbox` | Checkbox de selección (si `selectedFeedback="checkbox"`) |
|
|
65
|
-
| `check` | Icono de check (si `selectedFeedback="check"`) |
|
|
66
|
-
|
|
67
|
-
### ComboboxRenderProps
|
|
68
|
-
|
|
69
|
-
Funciones de renderizado personalizadas para control total sobre la UI. Todas son opcionales y reciben props relevantes.
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
{ value: "
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
<
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
{ value: "
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
</
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
<
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
```
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
)
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
}
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
<
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
-
|
|
574
|
-
-
|
|
575
|
-
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
- **
|
|
598
|
-
- **
|
|
599
|
-
- **
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
-
|
|
605
|
-
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
- **
|
|
610
|
-
- **
|
|
611
|
-
- **
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
**
|
|
618
|
-
**
|
|
619
|
-
**
|
|
620
|
-
**
|
|
621
|
-
**
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
**
|
|
625
|
-
**
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
- **
|
|
630
|
-
- **
|
|
631
|
-
- **
|
|
1
|
+
# Combobox
|
|
2
|
+
|
|
3
|
+
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, feedback visual con checkbox o check, placeholder persistente, iconos personalizados, y renderizado completamente personalizable mediante render props.
|
|
4
|
+
|
|
5
|
+
## Importación
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import { Combobox } from "@adamosuiteservices/ui/combobox";
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Anatomía
|
|
12
|
+
|
|
13
|
+
```tsx
|
|
14
|
+
<Combobox
|
|
15
|
+
options={[
|
|
16
|
+
{ value: "option1", label: "Option 1" },
|
|
17
|
+
{ value: "option2", label: "Option 2", disabled: true },
|
|
18
|
+
]}
|
|
19
|
+
value={selectedValue}
|
|
20
|
+
onValueChange={setSelectedValue}
|
|
21
|
+
/>
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
**Componente único**: Internamente usa Popover, Command, Button, Checkbox
|
|
25
|
+
|
|
26
|
+
## Props Principales
|
|
27
|
+
|
|
28
|
+
| Prop | Tipo | Default | Descripción |
|
|
29
|
+
| ----------------------- | --------------------------------------- | ------------ | ----------------------------------------------------------- |
|
|
30
|
+
| `options` | `ComboboxOption[]` | **required** | Array de opciones `{ value, label, disabled? }` |
|
|
31
|
+
| `value` | `string \| string[]` | - | Valor controlado (string para single, array para multiple) |
|
|
32
|
+
| `onValueChange` | `(value: string \| string[]) => void` | - | Callback al cambiar selección |
|
|
33
|
+
| `searchable` | `boolean` | `false` | Habilita input de búsqueda |
|
|
34
|
+
| `multiple` | `boolean` | `false` | Permite selección múltiple |
|
|
35
|
+
| `selectedFeedback` | `"checkbox" \| "check"` | `"checkbox"` | Tipo de indicador visual |
|
|
36
|
+
| `icon` | `ComponentType<{ className?: string }>` | - | Componente de icono opcional para mostrar en el trigger |
|
|
37
|
+
| `alwaysShowPlaceholder` | `boolean` | `false` | Mantiene el placeholder visible junto al valor seleccionado |
|
|
38
|
+
| `valuePosition` | `"left" \| "right"` | `"right"` | Posición del valor cuando alwaysShowPlaceholder es true |
|
|
39
|
+
| `labels` | `ComboboxLabels` | - | Textos personalizables (ver tabla abajo) |
|
|
40
|
+
| `classNames` | `ComboboxClassNames` | - | Clases CSS por sección (ver tabla abajo) |
|
|
41
|
+
| `renders` | `ComboboxRenderProps` | - | Funciones de renderizado personalizadas (ver tabla abajo) |
|
|
42
|
+
|
|
43
|
+
### ComboboxLabels
|
|
44
|
+
|
|
45
|
+
| Prop | Tipo | Default | Descripción |
|
|
46
|
+
| ------------------- | --------------------------- | ---------------------- | ----------------------------------------------- |
|
|
47
|
+
| `placeholder` | `string` | `"Select options..."` | Texto cuando no hay selección |
|
|
48
|
+
| `searchPlaceholder` | `string` | `"Search options..."` | Placeholder del input de búsqueda |
|
|
49
|
+
| `noItemsFound` | `string` | `"No options found."` | Mensaje cuando búsqueda no encuentra resultados |
|
|
50
|
+
| `multipleSelected` | `(count: number) => string` | `"X options selected"` | Función para texto de múltiples seleccionados |
|
|
51
|
+
|
|
52
|
+
### ComboboxClassNames
|
|
53
|
+
|
|
54
|
+
| Prop | Descripción |
|
|
55
|
+
| ---------- | -------------------------------------------------------- |
|
|
56
|
+
| `trigger` | Button trigger del popover |
|
|
57
|
+
| `popover` | Contenedor del popover |
|
|
58
|
+
| `command` | Componente Command root |
|
|
59
|
+
| `input` | Input de búsqueda |
|
|
60
|
+
| `list` | Lista de opciones |
|
|
61
|
+
| `empty` | Mensaje de no resultados |
|
|
62
|
+
| `group` | Grupo de items |
|
|
63
|
+
| `item` | Cada opción individual |
|
|
64
|
+
| `checkbox` | Checkbox de selección (si `selectedFeedback="checkbox"`) |
|
|
65
|
+
| `check` | Icono de check (si `selectedFeedback="check"`) |
|
|
66
|
+
|
|
67
|
+
### ComboboxRenderProps
|
|
68
|
+
|
|
69
|
+
Funciones de renderizado personalizadas para control total sobre la UI. Todas son opcionales y reciben props relevantes.
|
|
70
|
+
|
|
71
|
+
**Patrón Original Component**: Cada render prop recibe un componente `Original` que renderiza la implementación por defecto, permitiendo envolver o mejorar el renderizado sin reimplementar toda la lógica.
|
|
72
|
+
|
|
73
|
+
| Prop | Parámetros | Descripción |
|
|
74
|
+
| ------------------ | --------------------------------------------------------------------- | --------------------------------------- |
|
|
75
|
+
| `trigger` | `{ Original, open, value, displayText, placeholder, hasValue, icon }` | Renderiza el botón trigger completo |
|
|
76
|
+
| `triggerIcon` | `{ Original, open }` | Renderiza el icono del dropdown |
|
|
77
|
+
| `placeholder` | `{ Original, text, hasValue }` | Renderiza el texto del placeholder |
|
|
78
|
+
| `displayValue` | `{ Original, text, value }` | Renderiza el valor seleccionado |
|
|
79
|
+
| `option` | `{ Original, option, isSelected, selectedFeedback }` | Renderiza una opción completa |
|
|
80
|
+
| `optionLabel` | `{ Original, option }` | Renderiza solo la etiqueta de la opción |
|
|
81
|
+
| `selectedFeedback` | `{ Original, option, isSelected, type }` | Renderiza el indicador de selección |
|
|
82
|
+
| `empty` | `{ Original, text }` | Renderiza el estado vacío |
|
|
83
|
+
| `searchInput` | `{ Original, placeholder }` | Renderiza el input de búsqueda |
|
|
84
|
+
|
|
85
|
+
## Patrones de Uso
|
|
86
|
+
|
|
87
|
+
### Básico (Sin Búsqueda)
|
|
88
|
+
|
|
89
|
+
```tsx
|
|
90
|
+
const frameworks = [
|
|
91
|
+
{ value: "next", label: "Next.js" },
|
|
92
|
+
{ value: "remix", label: "Remix" },
|
|
93
|
+
{ value: "astro", label: "Astro" },
|
|
94
|
+
];
|
|
95
|
+
|
|
96
|
+
<Combobox
|
|
97
|
+
options={frameworks}
|
|
98
|
+
labels={{ placeholder: "Select framework..." }}
|
|
99
|
+
/>;
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Con Icono
|
|
103
|
+
|
|
104
|
+
```tsx
|
|
105
|
+
import { CalendarIcon } from "lucide-react";
|
|
106
|
+
|
|
107
|
+
<Combobox
|
|
108
|
+
searchable
|
|
109
|
+
icon={CalendarIcon}
|
|
110
|
+
options={frameworks}
|
|
111
|
+
labels={{ placeholder: "Select framework..." }}
|
|
112
|
+
/>;
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Placeholder Persistente
|
|
116
|
+
|
|
117
|
+
Útil para usar el placeholder como etiqueta que permanece visible.
|
|
118
|
+
|
|
119
|
+
```tsx
|
|
120
|
+
<Combobox
|
|
121
|
+
searchable
|
|
122
|
+
alwaysShowPlaceholder
|
|
123
|
+
valuePosition="right"
|
|
124
|
+
options={frameworks}
|
|
125
|
+
value={value}
|
|
126
|
+
onValueChange={setValue}
|
|
127
|
+
labels={{ placeholder: "Framework" }}
|
|
128
|
+
/>
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
**Comportamiento**:
|
|
132
|
+
|
|
133
|
+
- Sin valor: Muestra solo "Framework"
|
|
134
|
+
- Con valor y `valuePosition="right"`: Muestra "Framework" a la izquierda y el valor a la derecha
|
|
135
|
+
- Con valor y `valuePosition="left"`: Muestra "Framework" y el valor ambos a la izquierda
|
|
136
|
+
|
|
137
|
+
### Posición del Valor
|
|
138
|
+
|
|
139
|
+
Cuando `alwaysShowPlaceholder` es true, puedes controlar dónde aparece el valor seleccionado:
|
|
140
|
+
|
|
141
|
+
```tsx
|
|
142
|
+
// Valor a la derecha (default)
|
|
143
|
+
<Combobox
|
|
144
|
+
alwaysShowPlaceholder
|
|
145
|
+
valuePosition="right"
|
|
146
|
+
options={frameworks}
|
|
147
|
+
/>
|
|
148
|
+
|
|
149
|
+
// Valor a la izquierda junto al placeholder
|
|
150
|
+
<Combobox
|
|
151
|
+
alwaysShowPlaceholder
|
|
152
|
+
valuePosition="left"
|
|
153
|
+
options={frameworks}
|
|
154
|
+
/>
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
**Layouts resultantes**:
|
|
158
|
+
|
|
159
|
+
- `valuePosition="right"`: `[Icon] [Placeholder]` ... `[Value] [Chevron]`
|
|
160
|
+
- `valuePosition="left"`: `[Icon] [Placeholder] [Value]` ... `[Chevron]`
|
|
161
|
+
|
|
162
|
+
### Icono + Placeholder Persistente
|
|
163
|
+
|
|
164
|
+
```tsx
|
|
165
|
+
<Combobox
|
|
166
|
+
searchable
|
|
167
|
+
alwaysShowPlaceholder
|
|
168
|
+
icon={CalendarIcon}
|
|
169
|
+
options={frameworks}
|
|
170
|
+
value={value}
|
|
171
|
+
onValueChange={setValue}
|
|
172
|
+
labels={{ placeholder: "Framework" }}
|
|
173
|
+
/>
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Con Búsqueda
|
|
177
|
+
|
|
178
|
+
```tsx
|
|
179
|
+
<Combobox
|
|
180
|
+
searchable
|
|
181
|
+
options={frameworks}
|
|
182
|
+
labels={{
|
|
183
|
+
placeholder: "Select framework...",
|
|
184
|
+
searchPlaceholder: "Search frameworks...",
|
|
185
|
+
noItemsFound: "No framework found.",
|
|
186
|
+
}}
|
|
187
|
+
/>
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### Selección Simple Controlada
|
|
191
|
+
|
|
192
|
+
```tsx
|
|
193
|
+
const [value, setValue] = useState("");
|
|
194
|
+
|
|
195
|
+
<Combobox
|
|
196
|
+
searchable
|
|
197
|
+
options={frameworks}
|
|
198
|
+
value={value}
|
|
199
|
+
onValueChange={(newValue) => setValue(newValue as string)}
|
|
200
|
+
labels={{ placeholder: "Select framework..." }}
|
|
201
|
+
/>;
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
### Selección Múltiple
|
|
205
|
+
|
|
206
|
+
```tsx
|
|
207
|
+
const [values, setValues] = useState<string[]>([]);
|
|
208
|
+
|
|
209
|
+
<Combobox
|
|
210
|
+
searchable
|
|
211
|
+
multiple
|
|
212
|
+
options={frameworks}
|
|
213
|
+
value={values}
|
|
214
|
+
onValueChange={(newValues) => setValues(newValues as string[])}
|
|
215
|
+
labels={{
|
|
216
|
+
placeholder: "Select frameworks...",
|
|
217
|
+
multipleSelected: (count) => `${count} frameworks selected`,
|
|
218
|
+
}}
|
|
219
|
+
/>;
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
### Con Feedback de Check
|
|
223
|
+
|
|
224
|
+
```tsx
|
|
225
|
+
<Combobox
|
|
226
|
+
searchable
|
|
227
|
+
options={frameworks}
|
|
228
|
+
selectedFeedback="check"
|
|
229
|
+
labels={{ placeholder: "Select option..." }}
|
|
230
|
+
/>
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
**Diferencia**: `"checkbox"` muestra checkboxes a la izquierda, `"check"` muestra ícono check a la derecha.
|
|
234
|
+
|
|
235
|
+
### Opciones Deshabilitadas
|
|
236
|
+
|
|
237
|
+
```tsx
|
|
238
|
+
const options = [
|
|
239
|
+
{ value: "us", label: "United States" },
|
|
240
|
+
{ value: "ca", label: "Canada" },
|
|
241
|
+
{ value: "mx", label: "Mexico", disabled: true },
|
|
242
|
+
];
|
|
243
|
+
|
|
244
|
+
<Combobox
|
|
245
|
+
searchable
|
|
246
|
+
options={options}
|
|
247
|
+
labels={{ placeholder: "Select country..." }}
|
|
248
|
+
/>;
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### Labels Personalizadas
|
|
252
|
+
|
|
253
|
+
```tsx
|
|
254
|
+
<Combobox
|
|
255
|
+
searchable
|
|
256
|
+
multiple
|
|
257
|
+
options={frameworks}
|
|
258
|
+
labels={{
|
|
259
|
+
placeholder: "Choose your stack...",
|
|
260
|
+
searchPlaceholder: "Type to filter...",
|
|
261
|
+
noItemsFound: "No matching technologies found.",
|
|
262
|
+
multipleSelected: (count) =>
|
|
263
|
+
`${count} ${count === 1 ? "tech" : "techs"} selected`,
|
|
264
|
+
}}
|
|
265
|
+
/>
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
### Styling Personalizado
|
|
269
|
+
|
|
270
|
+
```tsx
|
|
271
|
+
<Combobox
|
|
272
|
+
searchable
|
|
273
|
+
options={frameworks}
|
|
274
|
+
classNames={{
|
|
275
|
+
trigger: "border-2 border-blue-500 w-64",
|
|
276
|
+
popover: "border-blue-200 shadow-lg",
|
|
277
|
+
item: "rounded px-3 py-2 hover:bg-blue-50",
|
|
278
|
+
check: "text-blue-600",
|
|
279
|
+
}}
|
|
280
|
+
/>
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
### En Formulario
|
|
284
|
+
|
|
285
|
+
```tsx
|
|
286
|
+
import { Field, FieldLabel } from "@adamosuiteservices/ui/field";
|
|
287
|
+
|
|
288
|
+
function FormExample() {
|
|
289
|
+
const [framework, setFramework] = useState("");
|
|
290
|
+
const [country, setCountry] = useState("");
|
|
291
|
+
|
|
292
|
+
return (
|
|
293
|
+
<form className="space-y-4">
|
|
294
|
+
<Field>
|
|
295
|
+
<FieldLabel>Framework</FieldLabel>
|
|
296
|
+
<Combobox
|
|
297
|
+
searchable
|
|
298
|
+
options={frameworks}
|
|
299
|
+
value={framework}
|
|
300
|
+
onValueChange={(value) => setFramework(value as string)}
|
|
301
|
+
labels={{ placeholder: "Select framework..." }}
|
|
302
|
+
/>
|
|
303
|
+
</Field>
|
|
304
|
+
|
|
305
|
+
<Field>
|
|
306
|
+
<FieldLabel>Country</FieldLabel>
|
|
307
|
+
<Combobox
|
|
308
|
+
searchable
|
|
309
|
+
options={countries}
|
|
310
|
+
value={country}
|
|
311
|
+
onValueChange={(value) => setCountry(value as string)}
|
|
312
|
+
selectedFeedback="check"
|
|
313
|
+
labels={{ placeholder: "Select country..." }}
|
|
314
|
+
/>
|
|
315
|
+
</Field>
|
|
316
|
+
|
|
317
|
+
<button type="submit">Submit</button>
|
|
318
|
+
</form>
|
|
319
|
+
);
|
|
320
|
+
}
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
### Multiple con Clear All
|
|
324
|
+
|
|
325
|
+
```tsx
|
|
326
|
+
const [values, setValues] = useState<string[]>([]);
|
|
327
|
+
|
|
328
|
+
<div className="space-y-2">
|
|
329
|
+
<Combobox
|
|
330
|
+
searchable
|
|
331
|
+
multiple
|
|
332
|
+
options={frameworks}
|
|
333
|
+
value={values}
|
|
334
|
+
onValueChange={(newValues) => setValues(newValues as string[])}
|
|
335
|
+
/>
|
|
336
|
+
|
|
337
|
+
{values.length > 0 && (
|
|
338
|
+
<button
|
|
339
|
+
onClick={() => setValues([])}
|
|
340
|
+
className="text-xs text-blue-600 hover:text-blue-800 underline"
|
|
341
|
+
>
|
|
342
|
+
Clear all
|
|
343
|
+
</button>
|
|
344
|
+
)}
|
|
345
|
+
</div>;
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
## Renderizado Personalizado
|
|
349
|
+
|
|
350
|
+
El prop `renders` permite personalizar completamente la UI usando el patrón render prop. Todas las funciones son opcionales.
|
|
351
|
+
|
|
352
|
+
### Patrón Original Component
|
|
353
|
+
|
|
354
|
+
Cada render prop recibe un componente `Original` que renderiza la implementación por defecto. Esto permite:
|
|
355
|
+
|
|
356
|
+
- **Envolver**: Agregar contenedores o elementos adicionales
|
|
357
|
+
- **Mejorar**: Añadir badges, iconos o decoraciones junto al original
|
|
358
|
+
- **Condicional**: Usar el original como fallback para ciertos estados
|
|
359
|
+
- **Componer**: Mezclar renderizado custom y default según condiciones
|
|
360
|
+
|
|
361
|
+
### Envolver el Trigger con Label
|
|
362
|
+
|
|
363
|
+
```tsx
|
|
364
|
+
<Combobox
|
|
365
|
+
searchable
|
|
366
|
+
options={frameworks}
|
|
367
|
+
value={value}
|
|
368
|
+
onValueChange={setValue}
|
|
369
|
+
renders={{
|
|
370
|
+
trigger: ({ Original }) => (
|
|
371
|
+
<div className="border border-purple-300 p-2 rounded-lg bg-purple-50">
|
|
372
|
+
<label className="text-xs font-medium text-purple-700 mb-1 block">
|
|
373
|
+
Choose your framework:
|
|
374
|
+
</label>
|
|
375
|
+
<Original />
|
|
376
|
+
</div>
|
|
377
|
+
),
|
|
378
|
+
}}
|
|
379
|
+
/>
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
### Mejorar Display Value con Badge
|
|
383
|
+
|
|
384
|
+
```tsx
|
|
385
|
+
<Combobox
|
|
386
|
+
searchable
|
|
387
|
+
options={frameworks}
|
|
388
|
+
value={value}
|
|
389
|
+
onValueChange={setValue}
|
|
390
|
+
renders={{
|
|
391
|
+
displayValue: ({ Original, text }) => (
|
|
392
|
+
<div className="flex items-center gap-2">
|
|
393
|
+
<Original />
|
|
394
|
+
{text && (
|
|
395
|
+
<span className="px-1.5 py-0.5 text-xs bg-green-100 text-green-700 rounded">
|
|
396
|
+
Active
|
|
397
|
+
</span>
|
|
398
|
+
)}
|
|
399
|
+
</div>
|
|
400
|
+
),
|
|
401
|
+
}}
|
|
402
|
+
/>
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
### Fallback Condicional
|
|
406
|
+
|
|
407
|
+
```tsx
|
|
408
|
+
<Combobox
|
|
409
|
+
searchable
|
|
410
|
+
options={frameworks}
|
|
411
|
+
value={value}
|
|
412
|
+
onValueChange={setValue}
|
|
413
|
+
renders={{
|
|
414
|
+
trigger: ({ Original, hasValue, displayText }) => {
|
|
415
|
+
// Custom cuando hay valor
|
|
416
|
+
if (hasValue) {
|
|
417
|
+
return (
|
|
418
|
+
<button className="w-full px-4 py-2 bg-green-600 text-white rounded-md">
|
|
419
|
+
✓ {displayText}
|
|
420
|
+
</button>
|
|
421
|
+
);
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
// Fallback al original cuando está vacío
|
|
425
|
+
return <Original />;
|
|
426
|
+
},
|
|
427
|
+
}}
|
|
428
|
+
/>
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
### Envolver Options con Styling
|
|
432
|
+
|
|
433
|
+
```tsx
|
|
434
|
+
<Combobox
|
|
435
|
+
searchable
|
|
436
|
+
options={frameworks}
|
|
437
|
+
value={value}
|
|
438
|
+
onValueChange={setValue}
|
|
439
|
+
selectedFeedback="check"
|
|
440
|
+
renders={{
|
|
441
|
+
option: ({ Original, isSelected }) => (
|
|
442
|
+
<div
|
|
443
|
+
className={`border-l-4 ${
|
|
444
|
+
isSelected ? "border-l-blue-500 bg-blue-50" : "border-l-transparent"
|
|
445
|
+
}`}
|
|
446
|
+
>
|
|
447
|
+
<Original />
|
|
448
|
+
</div>
|
|
449
|
+
),
|
|
450
|
+
}}
|
|
451
|
+
/>
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
### Mejorar Empty State con Acción
|
|
455
|
+
|
|
456
|
+
```tsx
|
|
457
|
+
<Combobox
|
|
458
|
+
searchable
|
|
459
|
+
options={[]}
|
|
460
|
+
renders={{
|
|
461
|
+
empty: ({ Original }) => (
|
|
462
|
+
<div className="space-y-3">
|
|
463
|
+
<Original />
|
|
464
|
+
<div className="px-4 pb-3">
|
|
465
|
+
<button
|
|
466
|
+
onClick={() => console.log("Add new")}
|
|
467
|
+
className="w-full px-3 py-1.5 text-xs text-blue-600 border border-blue-200 rounded hover:bg-blue-50"
|
|
468
|
+
>
|
|
469
|
+
+ Create new item
|
|
470
|
+
</button>
|
|
471
|
+
</div>
|
|
472
|
+
</div>
|
|
473
|
+
),
|
|
474
|
+
}}
|
|
475
|
+
/>
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
### Custom Option Label (Sin Original)
|
|
479
|
+
|
|
480
|
+
```tsx
|
|
481
|
+
<Combobox
|
|
482
|
+
searchable
|
|
483
|
+
options={frameworks}
|
|
484
|
+
value={value}
|
|
485
|
+
onValueChange={setValue}
|
|
486
|
+
renders={{
|
|
487
|
+
optionLabel: ({ option }) => (
|
|
488
|
+
<div className="flex items-center gap-2">
|
|
489
|
+
<span className="font-semibold text-blue-600">🚀</span>
|
|
490
|
+
<span>{option.label}</span>
|
|
491
|
+
</div>
|
|
492
|
+
),
|
|
493
|
+
}}
|
|
494
|
+
/>
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
### Custom Trigger Completo (Sin Original)
|
|
498
|
+
|
|
499
|
+
```tsx
|
|
500
|
+
<Combobox
|
|
501
|
+
searchable
|
|
502
|
+
options={frameworks}
|
|
503
|
+
value={value}
|
|
504
|
+
onValueChange={setValue}
|
|
505
|
+
renders={{
|
|
506
|
+
trigger: ({ open, displayText, placeholder, hasValue }) => (
|
|
507
|
+
<button
|
|
508
|
+
type="button"
|
|
509
|
+
className="flex items-center justify-between w-full px-4 py-2 text-sm bg-gradient-to-r from-purple-500 to-pink-500 text-white rounded-lg shadow-md hover:shadow-lg transition-all"
|
|
510
|
+
>
|
|
511
|
+
<span>{hasValue ? displayText : placeholder}</span>
|
|
512
|
+
<span className={`transition-transform ${open ? "rotate-180" : ""}`}>
|
|
513
|
+
▼
|
|
514
|
+
</span>
|
|
515
|
+
</button>
|
|
516
|
+
),
|
|
517
|
+
}}
|
|
518
|
+
/>
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
### Combinando Original y Custom
|
|
522
|
+
|
|
523
|
+
```tsx
|
|
524
|
+
<Combobox
|
|
525
|
+
searchable
|
|
526
|
+
multiple
|
|
527
|
+
options={frameworks}
|
|
528
|
+
value={values}
|
|
529
|
+
onValueChange={setValues}
|
|
530
|
+
renders={{
|
|
531
|
+
// Usa Original para envolver
|
|
532
|
+
trigger: ({ Original }) => (
|
|
533
|
+
<div className="relative">
|
|
534
|
+
<Original />
|
|
535
|
+
{values.length > 0 && (
|
|
536
|
+
<span className="absolute -top-2 -right-2 bg-red-500 text-white text-xs rounded-full w-5 h-5 flex items-center justify-center">
|
|
537
|
+
{values.length}
|
|
538
|
+
</span>
|
|
539
|
+
)}
|
|
540
|
+
</div>
|
|
541
|
+
),
|
|
542
|
+
// Custom completo sin Original
|
|
543
|
+
optionLabel: ({ option }) => (
|
|
544
|
+
<div className="flex items-center gap-2">
|
|
545
|
+
<span>🚀</span>
|
|
546
|
+
<span className="font-medium">{option.label}</span>
|
|
547
|
+
</div>
|
|
548
|
+
),
|
|
549
|
+
// Mejora el Original
|
|
550
|
+
displayValue: ({ Original, text }) => (
|
|
551
|
+
<div className="flex items-center gap-2">
|
|
552
|
+
<Original />
|
|
553
|
+
{text && <span className="text-xs opacity-50">selected</span>}
|
|
554
|
+
</div>
|
|
555
|
+
),
|
|
556
|
+
}}
|
|
557
|
+
/>
|
|
558
|
+
```
|
|
559
|
+
|
|
560
|
+
## Modos de Operación
|
|
561
|
+
|
|
562
|
+
### Single Selection
|
|
563
|
+
|
|
564
|
+
- `multiple={false}` (default)
|
|
565
|
+
- `value` es `string`
|
|
566
|
+
- Click en opción cierra el popover automáticamente
|
|
567
|
+
- Seleccionar opción ya seleccionada la deselecciona
|
|
568
|
+
|
|
569
|
+
### Multiple Selection
|
|
570
|
+
|
|
571
|
+
- `multiple={true}`
|
|
572
|
+
- `value` es `string[]`
|
|
573
|
+
- Click en opción NO cierra el popover
|
|
574
|
+
- Checkboxes permiten toggle de múltiples opciones
|
|
575
|
+
- Display muestra contador cuando >1 seleccionado
|
|
576
|
+
|
|
577
|
+
## Casos de Uso Comunes
|
|
578
|
+
|
|
579
|
+
**Framework selector**: Selección de tecnología con búsqueda
|
|
580
|
+
**Country/City picker**: Selección geográfica con opciones deshabilitadas
|
|
581
|
+
**Tags/Categories**: Selección múltiple de categorías
|
|
582
|
+
**Settings filters**: Filtros multi-selección en dashboards
|
|
583
|
+
**User assignment**: Asignar múltiples usuarios a tarea
|
|
584
|
+
**Language selector**: Selección de idioma con búsqueda
|
|
585
|
+
**Status selector con icono**: Usar `icon` + `alwaysShowPlaceholder` para selectores etiquetados
|
|
586
|
+
**Rich options**: Usar `renders.optionLabel` para mostrar avatares, badges, etc.
|
|
587
|
+
**Custom UI**: Usar `renders.trigger` para triggers completamente personalizados
|
|
588
|
+
|
|
589
|
+
## Estados Internos
|
|
590
|
+
|
|
591
|
+
### Display Text
|
|
592
|
+
|
|
593
|
+
- **Sin selección**: Muestra `labels.placeholder`
|
|
594
|
+
- **Single selection**: Muestra `label` de la opción seleccionada
|
|
595
|
+
- **Single selection + alwaysShowPlaceholder**: Muestra `placeholder: label` separados
|
|
596
|
+
- **Multiple (1 item)**: Muestra `label` del único item seleccionado
|
|
597
|
+
- **Multiple (1 item) + alwaysShowPlaceholder**: Muestra `placeholder: label` separados
|
|
598
|
+
- **Multiple (>1 items)**: Muestra resultado de `labels.multipleSelected(count)`
|
|
599
|
+
- **Multiple (>1 items) + alwaysShowPlaceholder**: Muestra `placeholder: X items selected` separados
|
|
600
|
+
|
|
601
|
+
### Popover State
|
|
602
|
+
|
|
603
|
+
- Controlado internamente con `useState`
|
|
604
|
+
- Se cierra automáticamente en single selection
|
|
605
|
+
- Permanece abierto en multiple selection
|
|
606
|
+
|
|
607
|
+
## Accesibilidad
|
|
608
|
+
|
|
609
|
+
- ✅ **ARIA**: Button tiene `role="combobox"` y `aria-expanded`
|
|
610
|
+
- ✅ **Navegación teclado**: Arrow keys para navegar opciones, Enter para seleccionar, Escape para cerrar
|
|
611
|
+
- ✅ **Screen readers**: Anuncia opciones y estado seleccionado
|
|
612
|
+
- ✅ **Focus management**: Focus automático en input cuando searchable
|
|
613
|
+
- ✅ **Disabled options**: No seleccionables, estilo visual diferente
|
|
614
|
+
|
|
615
|
+
## Notas de Implementación
|
|
616
|
+
|
|
617
|
+
- **Composición**: Usa Popover + Command + Button + Checkbox internamente
|
|
618
|
+
- **Búsqueda**: Command component maneja fuzzy search automáticamente
|
|
619
|
+
- **Estado interno**: Soporta modo controlado y no controlado
|
|
620
|
+
- **Tipo de value**: Cambia según `multiple` (string vs string[])
|
|
621
|
+
- **selectedFeedback**:
|
|
622
|
+
- `"checkbox"`: Muestra Checkbox a la izquierda de cada opción
|
|
623
|
+
- `"check"`: Muestra CheckIcon a la derecha (agrega `pr-8` automáticamente)
|
|
624
|
+
- **Popover alignment**: `align="start"` por defecto para alinear con trigger
|
|
625
|
+
- **ChevronDownIcon**: Se muestra en trigger con `opacity-50` (puede sobrescribirse con `renders.triggerIcon`)
|
|
626
|
+
- **No animation**: Selección instantánea, sin delays
|
|
627
|
+
- **alwaysShowPlaceholder**: Renderiza placeholder y valor como elementos separados con gap
|
|
628
|
+
- **valuePosition**: Controla donde aparece el valor cuando `alwaysShowPlaceholder` es true ("left" o "right", default "right")
|
|
629
|
+
- **icon**: Se muestra con `opacity-50` por defecto cuando se proporciona el prop `icon`
|
|
630
|
+
- **Render props**: Tienen prioridad sobre renderizado por defecto, permiten personalización completa
|
|
631
|
+
- **Composición de renders**: Puedes combinar múltiples render props para personalización granular
|
|
632
|
+
- **Original component**: Cada render prop recibe un componente `Original` para renderizar la implementación por defecto, permitiendo envolver o mejorar sin reimplementar
|
|
633
|
+
|
|
634
|
+
## Troubleshooting
|
|
635
|
+
|
|
636
|
+
**Value no cambia**: Verifica que uses `onValueChange` en modo controlado
|
|
637
|
+
**Búsqueda no funciona**: Asegúrate de pasar `searchable={true}`
|
|
638
|
+
**Multiple selection cierra popover**: Verifica que `multiple={true}` esté activo
|
|
639
|
+
**Labels incorrectas en multiple**: Usa función `multipleSelected` para pluralización
|
|
640
|
+
**Tipo de value incorrecto**: Single usa `string`, Multiple usa `string[]`
|
|
641
|
+
**Checkboxes no aparecen**: Solo aparecen cuando `selectedFeedback="checkbox"` (default)
|
|
642
|
+
**Check icon no visible**: Solo aparece cuando `selectedFeedback="check"`
|
|
643
|
+
**Icon no se muestra**: Asegúrate de pasar el prop `icon` con un componente válido
|
|
644
|
+
**Placeholder desaparece al seleccionar**: Si quieres mantenerlo visible, usa `alwaysShowPlaceholder={true}`
|
|
645
|
+
**Render prop no funciona**: Verifica que el render prop retorne un `ReactNode` válido
|
|
646
|
+
**Custom trigger pierde funcionalidad**: Cuando usas `renders.trigger`, debes manejar el click manualmente o envolver en `PopoverTrigger`
|
|
647
|
+
**Original component no renderiza**: Asegúrate de usar `<Original />` como componente JSX, no como función
|
|
648
|
+
**Quiero envolver sin reimplementar**: Usa el componente `Original` que recibe cada render prop para mantener la funcionalidad por defecto
|
|
649
|
+
|
|
650
|
+
## Referencias
|
|
651
|
+
|
|
652
|
+
- **Radix UI Popover**: <https://www.radix-ui.com/primitives/docs/components/popover>
|
|
653
|
+
- **Command Component**: Ver documentación de Command
|
|
654
|
+
- **ARIA Combobox**: <https://www.w3.org/WAI/ARIA/apg/patterns/combobox/>
|