Combobox Glass

1/**
2 * ComboBoxGlass Component
3 *
4 * Glass-themed combobox (searchable select) combining autocomplete and dropdown functionality.
5 * Built on Radix UI Popover and cmdk for robust keyboard navigation and filtering.
6 *
7 * ## Features
8 * - Search/filter functionality with real-time results
9 * - Keyboard navigation (Arrow keys, Enter, Escape, Tab)
10 * - Optional FormFieldWrapper integration (label, error, success states)
11 * - Size variants (sm, md, lg, xl) via InputGlass variants
12 * - Icon support for both trigger button and individual options
13 * - Glass variant styles (glass, frosted, fluted, crystal)
14 * - Clearable selection (click selected item to deselect)
15 * - Customizable empty state and search placeholder
16 * - Disabled state with visual feedback
17 * - Popover positioning (side, align) configuration
18 *
19 * ## CSS Variables
20 * - `--input-bg` - Trigger button background
21 * - `--input-border` - Trigger button border
22 * - `--input-text` - Trigger button text
23 * - `--dropdown-bg` - Content background
24 * - `--dropdown-border` - Content border
25 * - `--dropdown-item-hover` - Item hover background
26 * - `--dropdown-item-text` - Item text color
27 * - `--dropdown-icon` - Option icon color
28 * - `--dropdown-glow` - Content box shadow
29 * - `--text-accent` - Check icon color when selected
30 * - `--text-muted` - Search icon and empty state text
31 *
32 * @example Basic usage
33 * ```tsx
34 * import { ComboBoxGlass, type ComboBoxOption } from 'shadcn-glass-ui'
35 * import { useState } from 'react'
36 *
37 * const options: ComboBoxOption[] = [
38 *   { value: 'react', label: 'React' },
39 *   { value: 'vue', label: 'Vue' },
40 *   { value: 'angular', label: 'Angular' },
41 * ]
42 *
43 * function FrameworkSelector() {
44 *   const [value, setValue] = useState<string>()
45 *   return (
46 *     <ComboBoxGlass
47 *       options={options}
48 *       value={value}
49 *       onValueChange={setValue}
50 *       placeholder="Select framework..."
51 *     />
52 *   )
53 * }
54 * ```
55 *
56 * @example With form field wrapper
57 * ```tsx
58 * <ComboBoxGlass
59 *   options={countries}
60 *   value={country}
61 *   onValueChange={setCountry}
62 *   label="Country"
63 *   error="Please select a country"
64 *   required
65 *   placeholder="Select country..."
66 * />
67 * ```
68 *
69 * @example With icons
70 * ```tsx
71 * import { MapPin, Building } from 'lucide-react'
72 *
73 * const options: ComboBoxOption[] = [
74 *   { value: 'us', label: 'United States', icon: MapPin },
75 *   { value: 'uk', label: 'United Kingdom', icon: MapPin },
76 * ]
77 *
78 * <ComboBoxGlass
79// … truncated