@neynar/ui 0.4.0 → 1.0.0

package/src/components/ui/combobox.tsx

@@ -1,574 +1,374 @@
 "use client";
 
 import * as React from "react";
-import { Check, ChevronsUpDown } from "lucide-react";
+import { Combobox as ComboboxPrimitive } from "@base-ui/react";
 
 import { cn } from "@/lib/utils";
 import { Button } from "@/components/ui/button";
 import {
-  Command,
-  CommandEmpty,
-  CommandGroup,
-  CommandInput,
-  CommandItem,
-  CommandList,
-} from "@/components/ui/command";
-import {
-  Popover,
-  PopoverContent,
-  PopoverTrigger,
-} from "@/components/ui/popover";
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+} from "@/components/ui/input-group";
+import { ChevronDownIcon, XIcon, CheckIcon } from "lucide-react";
+
+const Combobox = ComboboxPrimitive.Root;
+
+type ComboboxProps<T = unknown> = ComboboxPrimitive.Root.Props<T>;
+
+type ComboboxValueProps = ComboboxPrimitive.Value.Props;
+
+/** Displays the selected value(s) as text in the trigger or input. */
+function ComboboxValue({ ...props }: ComboboxValueProps) {
+  return <ComboboxPrimitive.Value data-slot="combobox-value" {...props} />;
+}
+
+type ComboboxTriggerProps = ComboboxPrimitive.Trigger.Props;
+
+/** Button that opens the combobox popup. Automatically includes a chevron icon. */
+function ComboboxTrigger({
+  className,
+  children,
+  ...props
+}: ComboboxTriggerProps) {
+  return (
+    <ComboboxPrimitive.Trigger
+      data-slot="combobox-trigger"
+      className={cn("[&_svg:not([class*='size-'])]:size-4", className)}
+      {...props}
+    >
+      {children}
+      <ChevronDownIcon className="text-muted-foreground size-4 pointer-events-none" />
+    </ComboboxPrimitive.Trigger>
+  );
+}
+
+type ComboboxClearProps = ComboboxPrimitive.Clear.Props;
+
+/** Button to clear the selected value. Renders as a ghost icon button with X icon. */
+function ComboboxClear({ className, ...props }: ComboboxClearProps) {
+  return (
+    <ComboboxPrimitive.Clear
+      data-slot="combobox-clear"
+      render={<InputGroupButton variant="ghost" size="icon-xs" />}
+      className={cn(className)}
+      {...props}
+    >
+      <XIcon className="pointer-events-none" />
+    </ComboboxPrimitive.Clear>
+  );
+}
+
+type ComboboxInputProps = ComboboxPrimitive.Input.Props & {
+  /** Show dropdown trigger button. @default true */
+  showTrigger?: boolean;
+  /** Show clear button when value is selected. @default false */
+  showClear?: boolean;
+};
 
 /**
- * Option structure for combobox items
- *
- * Defines the shape of each option that can be displayed and selected
- * in the combobox dropdown list.
- *
- * @since 1.0.0
+ * Text input for single-select combobox with optional trigger and clear buttons.
+ * Automatically renders within an InputGroup with inline-end addons.
  */
-export type ComboboxOption = {
-  /**
-   * Unique identifier for this option
-   *
-   * Used for selection tracking and should be unique within the options array.
-   */
-  value: string;
-
-  /**
-   * Display text shown to users in the dropdown
-   *
-   * Should be descriptive and help users understand what this option represents.
-   */
-  label: string;
-
-  /**
-   * Whether this option is disabled and cannot be selected
-   *
-   * Disabled options remain visible but are not selectable and appear dimmed.
-   *
-   * @default false
-   */
-  disabled?: boolean;
-};
+function ComboboxInput({
+  className,
+  children,
+  disabled = false,
+  showTrigger = true,
+  showClear = false,
+  ...props
+}: ComboboxInputProps) {
+  return (
+    <InputGroup className={cn("w-auto", className)}>
+      <ComboboxPrimitive.Input
+        render={<InputGroupInput disabled={disabled} />}
+        {...props}
+      />
+      <InputGroupAddon align="inline-end">
+        {showTrigger && (
+          <InputGroupButton
+            size="icon-xs"
+            variant="ghost"
+            render={<ComboboxTrigger />}
+            data-slot="input-group-button"
+            className="group-has-data-[slot=combobox-clear]/input-group:hidden data-pressed:bg-transparent"
+            disabled={disabled}
+          />
+        )}
+        {showClear && <ComboboxClear disabled={disabled} />}
+      </InputGroupAddon>
+      {children}
+    </InputGroup>
+  );
+}
+
+type ComboboxContentProps = ComboboxPrimitive.Popup.Props &
+  Pick<
+    ComboboxPrimitive.Positioner.Props,
+    "side" | "align" | "sideOffset" | "alignOffset" | "anchor"
+  >;
+
+/**
+ * Popup container for combobox items. Automatically renders in portal with positioner.
+ * Use `anchor` prop for multi-select with chips to position relative to chips container.
+ */
+function ComboboxContent({
+  className,
+  side = "bottom",
+  sideOffset = 6,
+  align = "start",
+  alignOffset = 0,
+  anchor,
+  ...props
+}: ComboboxContentProps) {
+  return (
+    <ComboboxPrimitive.Portal>
+      <ComboboxPrimitive.Positioner
+        side={side}
+        sideOffset={sideOffset}
+        align={align}
+        alignOffset={alignOffset}
+        anchor={anchor}
+        className="isolate z-50"
+      >
+        <ComboboxPrimitive.Popup
+          data-slot="combobox-content"
+          data-chips={!!anchor}
+          className={cn(
+            "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 ring-foreground/10 *:data-[slot=input-group]:bg-input/30 *:data-[slot=input-group]:border-input/30 max-h-72 min-w-36 overflow-hidden rounded-md shadow-md ring-1 duration-100 *:data-[slot=input-group]:m-1 *:data-[slot=input-group]:mb-0 *:data-[slot=input-group]:h-8 *:data-[slot=input-group]:shadow-none group/combobox-content relative max-h-(--available-height) w-(--anchor-width) max-w-(--available-width) min-w-[calc(var(--anchor-width)+--spacing(7))] origin-(--transform-origin) data-[chips=true]:min-w-(--anchor-width)",
+            className,
+          )}
+          {...props}
+        />
+      </ComboboxPrimitive.Positioner>
+    </ComboboxPrimitive.Portal>
+  );
+}
+
+type ComboboxListProps = ComboboxPrimitive.List.Props;
+
+/** Scrollable container for combobox items. Automatically manages overflow and empty states. */
+function ComboboxList({ className, ...props }: ComboboxListProps) {
+  return (
+    <ComboboxPrimitive.List
+      data-slot="combobox-list"
+      className={cn(
+        "no-scrollbar max-h-[min(calc(--spacing(72)---spacing(9)),calc(var(--available-height)---spacing(9)))] scroll-py-1 overflow-y-auto p-1 data-empty:p-0 overflow-y-auto overscroll-contain",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+type ComboboxItemProps = ComboboxPrimitive.Item.Props;
+
+/**
+ * Selectable item in combobox list. Shows check icon when selected.
+ * Requires unique `value` prop.
+ */
+function ComboboxItem({ className, children, ...props }: ComboboxItemProps) {
+  return (
+    <ComboboxPrimitive.Item
+      data-slot="combobox-item"
+      className={cn(
+        "data-highlighted:bg-accent data-highlighted:text-accent-foreground not-data-[variant=destructive]:data-highlighted:**:text-accent-foreground gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm [&_svg:not([class*='size-'])]:size-4 relative flex w-full cursor-default items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      <ComboboxPrimitive.ItemIndicator
+        render={
+          <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center" />
+        }
+      >
+        <CheckIcon className="pointer-events-none" />
+      </ComboboxPrimitive.ItemIndicator>
+    </ComboboxPrimitive.Item>
+  );
+}
+
+type ComboboxGroupProps = ComboboxPrimitive.Group.Props;
+
+/** Container for grouping related items together with optional label. */
+function ComboboxGroup({ className, ...props }: ComboboxGroupProps) {
+  return (
+    <ComboboxPrimitive.Group
+      data-slot="combobox-group"
+      className={cn(className)}
+      {...props}
+    />
+  );
+}
+
+type ComboboxLabelProps = ComboboxPrimitive.GroupLabel.Props;
+
+/** Label for a group of items. Use within ComboboxGroup. */
+function ComboboxLabel({ className, ...props }: ComboboxLabelProps) {
+  return (
+    <ComboboxPrimitive.GroupLabel
+      data-slot="combobox-label"
+      className={cn("text-muted-foreground px-2 py-1.5 text-xs", className)}
+      {...props}
+    />
+  );
+}
+
+type ComboboxCollectionProps = ComboboxPrimitive.Collection.Props;
+
+/** Defines collection of items for keyboard navigation and accessibility. */
+function ComboboxCollection({ ...props }: ComboboxCollectionProps) {
+  return (
+    <ComboboxPrimitive.Collection data-slot="combobox-collection" {...props} />
+  );
+}
+
+type ComboboxEmptyProps = ComboboxPrimitive.Empty.Props;
+
+/** Displays message when search returns no results. Automatically shown when list is empty. */
+function ComboboxEmpty({ className, ...props }: ComboboxEmptyProps) {
+  return (
+    <ComboboxPrimitive.Empty
+      data-slot="combobox-empty"
+      className={cn(
+        "text-muted-foreground hidden w-full justify-center py-2 text-center text-sm group-data-empty/combobox-content:flex",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+type ComboboxSeparatorProps = ComboboxPrimitive.Separator.Props;
+
+/** Visual separator between groups of items. */
+function ComboboxSeparator({ className, ...props }: ComboboxSeparatorProps) {
+  return (
+    <ComboboxPrimitive.Separator
+      data-slot="combobox-separator"
+      className={cn("bg-border -mx-1 my-1 h-px", className)}
+      {...props}
+    />
+  );
+}
+
+type ComboboxChipsProps = React.ComponentPropsWithRef<
+  typeof ComboboxPrimitive.Chips
+> &
+  ComboboxPrimitive.Chips.Props;
 
 /**
- * Props for Combobox component (Documentation only - NOT used in component implementation)
- *
- * Comprehensive configuration options for customizing combobox behavior,
- * appearance, and interaction patterns. Built on top of Radix UI Popover
- * primitives and CMDK command menu for robust accessibility and functionality.
- *
- * These types are for documentation generation and should not replace CVA/Radix inferred types.
- *
- * @since 1.0.0
+ * Container for selected chips in multi-select mode. Use with `useComboboxAnchor()` hook
+ * and pass ref to anchor the popup. Contains ComboboxChip and ComboboxChipsInput.
  */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type ComboboxDocsProps = {
-  /**
-   * Array of options to display in the combobox dropdown
-   *
-   * Each option should have a unique value and descriptive label.
-   * Options can be disabled to prevent selection while remaining visible.
-   * The array is filtered in real-time as users type in the search input.
-   *
-   * @example
-   * ```tsx
-   * const options = [
-   *   { value: "nextjs", label: "Next.js" },
-   *   { value: "remix", label: "Remix", disabled: false },
-   *   { value: "sveltekit", label: "SvelteKit" },
-   *   { value: "nuxt", label: "Nuxt.js", disabled: true }, // Disabled option
-   * ]
-   * ```
-   */
-  options: ComboboxOption[];
-
-  /**
-   * Currently selected value from the options array
-   *
-   * Should match the `value` property of one of the provided options.
-   * Use with `onValueChange` for controlled component behavior.
-   * When undefined or empty, no option is selected and placeholder is shown.
-   *
-   * @example
-   * ```tsx
-   * const [framework, setFramework] = useState("") // No selection
-   * const [language, setLanguage] = useState("typescript") // Pre-selected
-   * ```
-   */
-  value?: string;
-
-  /**
-   * Callback fired when the selected value changes
-   *
-   * Receives the new selected value as a string. If the same option
-   * is clicked again, an empty string is passed to allow deselection.
-   * This enables toggle behavior where clicking selected items deselects them.
-   *
-   * @param value - The newly selected option value or empty string for deselection
-   * @example
-   * ```tsx
-   * // Basic controlled usage
-   * onValueChange={(value) => setSelectedValue(value)}
-   *
-   * // With validation and side effects
-   * onValueChange={(value) => {
-   *   setSelectedValue(value)
-   *   if (value) {
-   *     console.log('Selected:', options.find(opt => opt.value === value)?.label)
-   *   }
-   * }}
-   * ```
-   */
-  onValueChange?: (value: string) => void;
-
-  /**
-   * Placeholder text displayed when no option is selected
-   *
-   * Should be descriptive and help users understand what they're selecting.
-   * Displayed in muted text color to distinguish from actual selections.
-   *
-   * @default "Select option..."
-   * @example "Choose a framework...", "Select your country..."
-   */
-  placeholder?: string;
-
-  /**
-   * Text displayed when search query returns no matching options
-   *
-   * Customize this message to match your application's tone and context.
-   * Shown in the dropdown when no options match the current search input.
-   *
-   * @default "No option found."
-   * @example "No frameworks found.", "Try a different search term."
-   */
-  emptyText?: string;
-
-  /**
-   * Placeholder text for the search input field
-   *
-   * Should guide users on how to search effectively within your option set.
-   * Displayed inside the search input when it's empty.
-   *
-   * @default "Search options..."
-   * @example "Search frameworks...", "Type to filter countries..."
-   */
-  searchPlaceholder?: string;
-
-  /**
-   * Additional CSS classes for the root container element
-   *
-   * Applied to the outermost div wrapper. Use for custom spacing,
-   * positioning, or layout adjustments that don't affect internal components.
-   *
-   * @example "mb-4", "w-full max-w-sm"
-   */
-  className?: string;
-
-  /**
-   * Whether the entire combobox is disabled
-   *
-   * When disabled, the trigger button cannot be clicked and the
-   * dropdown cannot be opened. Use individual `option.disabled` for
-   * granular control over specific options.
-   *
-   * @default false
-   * @example disabled={isLoading || !hasPermission}
-   */
-  disabled?: boolean;
-
-  /**
-   * Additional CSS classes for the trigger button
-   *
-   * Commonly used to control width (e.g., "w-[300px]"), styling variants,
-   * or responsive behavior. The button uses the "outline" variant by default.
-   * For best UX, consider matching `popoverClassName` width.
-   *
-   * @example "w-full sm:w-[280px] border-primary/50"
-   * @example "min-w-[200px] font-medium"
-   */
-  buttonClassName?: string;
-
-  /**
-   * Additional CSS classes for the popover dropdown content
-   *
-   * Should typically match `buttonClassName` width for consistent alignment.
-   * Use to control positioning, width, and styling of the dropdown container.
-   * The popover automatically handles z-index and positioning.
-   *
-   * @example "w-full sm:w-[280px] border-primary/50"
-   * @example "max-h-[300px] border-2"
-   */
-  popoverClassName?: string;
-  /**
-   * Inherited props from Radix UI Popover.Root
-   *
-   * Advanced props for controlling popover behavior. These are automatically
-   * passed through to the underlying Popover.Root component.
-   *
-   * @see {@link https://www.radix-ui.com/primitives/docs/components/popover#root} Radix Popover.Root API
-   */
-} & Omit<React.ComponentProps<typeof Popover>, "children">;
+function ComboboxChips({ className, ...props }: ComboboxChipsProps) {
+  return (
+    <ComboboxPrimitive.Chips
+      data-slot="combobox-chips"
+      className={cn(
+        "dark:bg-input/30 border-input focus-within:border-ring focus-within:ring-ring/50 has-aria-invalid:ring-destructive/20 dark:has-aria-invalid:ring-destructive/40 has-aria-invalid:border-destructive dark:has-aria-invalid:border-destructive/50 flex min-h-9 flex-wrap items-center gap-1.5 rounded-md border bg-transparent bg-clip-padding px-2.5 py-1.5 text-sm shadow-xs transition-[color,box-shadow] focus-within:ring-[3px] has-aria-invalid:ring-[3px] has-data-[slot=combobox-chip]:px-1.5",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+type ComboboxChipProps = ComboboxPrimitive.Chip.Props & {
+  /** Show remove button on chip. @default true */
+  showRemove?: boolean;
+};
 
 /**
- * Searchable dropdown selection component with typeahead functionality
- *
- * A versatile combobox that combines a button trigger with a searchable dropdown list.
- * Ideal for selecting from moderate to large lists of options where search functionality
- * improves user experience. Built on Radix UI Popover primitives for accessibility and
- * CMDK for powerful command menu functionality with real-time filtering.
- *
- * **Technical Architecture:**
- * - **Popover Container**: Radix UI Popover.Root provides modal/non-modal behavior, focus management, and positioning
- * - **Trigger Button**: Uses Button component with proper ARIA attributes and visual states
- * - **Command Menu**: CMDK provides keyboard navigation, filtering, and accessibility features
- * - **State Management**: Controlled/uncontrolled modes with proper React patterns
- *
- * **Use Cases:**
- * - Selecting from 10+ options that benefit from real-time filtering
- * - User interfaces requiring quick option discovery through search
- * - Forms needing better UX than basic select dropdowns
- * - Applications with dynamic or large option sets
- *
- * **When Not to Use:**
- * - Simple selection from few options (use Select component instead)
- * - Multi-select scenarios (use Checkbox group or specialized multi-select)
- * - Tree or hierarchical data (use TreeSelect or nested menus)
- *
- * @component
- * @example
- * Basic controlled combobox with framework selection
- * ```tsx
- * const [framework, setFramework] = useState("")
- *
- * const frameworks = [
- *   { value: "nextjs", label: "Next.js" },
- *   { value: "remix", label: "Remix" },
- *   { value: "sveltekit", label: "SvelteKit" },
- *   { value: "nuxt", label: "Nuxt.js" },
- * ]
- *
- * <Combobox
- *   options={frameworks}
- *   value={framework}
- *   onValueChange={setFramework}
- *   placeholder="Select framework..."
- *   searchPlaceholder="Search frameworks..."
- *   buttonClassName="w-[300px]"
- *   popoverClassName="w-[300px]"
- * />
- * ```
- *
- * @example
- * Advanced combobox with disabled options and custom styling
- * ```tsx
- * const statusOptions = [
- *   { value: "active", label: "Active" },
- *   { value: "pending", label: "Pending" },
- *   { value: "archived", label: "Archived (Read Only)", disabled: true },
- *   { value: "deleted", label: "Deleted (Unavailable)", disabled: true },
- * ]
- *
- * <Combobox
- *   options={statusOptions}
- *   value={status}
- *   onValueChange={(value) => {
- *     setStatus(value)
- *     // Track selection analytics
- *     analytics.track('status_selected', { value })
- *   }}
- *   placeholder="Select status..."
- *   emptyText="No matching status found."
- *   searchPlaceholder="Filter statuses..."
- *   buttonClassName="w-[250px] border-primary/50"
- *   popoverClassName="w-[250px]"
- *   disabled={isLoading}
- * />
- * ```
- *
- * @example
- * Form integration with validation and error handling
- * ```tsx
- * import { Label } from "@/components/ui/label"
- * import { useFormContext } from "react-hook-form"
- *
- * function CountryField() {
- *   const { register, setValue, watch, formState: { errors } } = useFormContext()
- *   const selectedCountry = watch("country")
- *
- *   return (
- *     <div className="space-y-2">
- *       <Label htmlFor="country" className={errors.country ? "text-destructive" : ""}>
- *         Country {errors.country && "*"}
- *       </Label>
- *       <Combobox
- *         options={countries}
- *         value={selectedCountry}
- *         onValueChange={(value) => setValue("country", value, { shouldValidate: true })}
- *         placeholder="Choose your country..."
- *         searchPlaceholder="Type to search countries..."
- *         emptyText="Country not found. Try a different search."
- *         buttonClassName={cn(
- *           "w-full",
- *           errors.country && "border-destructive focus-visible:ring-destructive"
- *         )}
- *         popoverClassName="w-full"
- *         disabled={isSubmitting}
- *       />
- *       {errors.country && (
- *         <p className="text-sm text-destructive" role="alert">
- *           {errors.country.message}
- *         </p>
- *       )}
- *     </div>
- *   )
- * }
- * ```
- *
- * @example
- * Responsive design with mobile optimization
- * ```tsx
- * <Combobox
- *   options={teamMembers}
- *   value={assignedTo}
- *   onValueChange={setAssignedTo}
- *   placeholder="Assign to team member..."
- *   searchPlaceholder="Search team members..."
- *   emptyText="No team members found."
- *   buttonClassName="w-full sm:w-[280px] md:w-[320px]"
- *   popoverClassName="w-full sm:w-[280px] md:w-[320px]"
- *   // Mobile: full width, Desktop: fixed width for consistent layout
- * />
- * ```
- *
- * @example
- * Async data loading with loading states
- * ```tsx
- * function AsyncCombobox() {
- *   const [options, setOptions] = useState([])
- *   const [loading, setLoading] = useState(false)
- *   const [searchTerm, setSearchTerm] = useState("")
- *
- *   // Debounced search effect
- *   useEffect(() => {
- *     if (!searchTerm) return
- *
- *     const timeoutId = setTimeout(async () => {
- *       setLoading(true)
- *       try {
- *         const results = await searchAPI(searchTerm)
- *         setOptions(results)
- *       } finally {
- *         setLoading(false)
- *       }
- *     }, 300)
- *
- *     return () => clearTimeout(timeoutId)
- *   }, [searchTerm])
- *
- *   return (
- *     <Combobox
- *       options={options}
- *       value={selectedValue}
- *       onValueChange={setSelectedValue}
- *       placeholder={loading ? "Searching..." : "Search items..."}
- *       emptyText={loading ? "Loading..." : "No results found."}
- *       disabled={loading}
- *     />
- *   )
- * }
- * ```
- *
- * @accessibility
- *
- * **ARIA Implementation (WCAG 2.1 Level AA Compliant):**
- * - **Combobox Role**: Trigger button uses `role="combobox"` with proper `aria-expanded` state
- * - **Popup Association**: `aria-controls` links trigger to popup when visible
- * - **Active Descendant**: `aria-activedescendant` manages focus within dropdown
- * - **Popup Type**: `aria-haspopup="listbox"` indicates the nature of the popup
- * - **Selection State**: `aria-selected` attributes on options indicate current selection
- * - **Disabled State**: Proper `aria-disabled` attributes for unavailable options
- *
- * **Keyboard Navigation (W3C ARIA 1.2 Combobox Pattern):**
- * - **Tab**: Moves focus to/from combobox in natural tab order
- * - **Space/Enter**: Opens/closes dropdown, selects focused option
- * - **Down Arrow**: Opens dropdown (if closed) or moves to next option
- * - **Up Arrow**: Moves to previous option (when dropdown is open)
- * - **Home**: Moves to first option in list
- * - **End**: Moves to last option in list
- * - **Escape**: Closes dropdown and returns focus to trigger button
- * - **Type-ahead**: Real-time filtering as user types in search input
- * - **Character Keys**: When dropdown is closed, opens and starts filtering
- *
- * **Screen Reader Support:**
- * - **Selection Announcements**: Current selection state announced on focus
- * - **Option Count**: Number of available options announced when dropdown opens
- * - **Filter Results**: Live announcements of filtered results count
- * - **State Changes**: Open/close state changes announced appropriately
- * - **Empty State**: Clear messaging when no options match search
- * - **Disabled Feedback**: Disabled options announced and properly skipped
- *
- * **Focus Management:**
- * - **Programmatic Focus**: DOM focus remains on combobox trigger for screen reader compatibility
- * - **Visual Focus**: Options highlighted using `aria-activedescendant` pattern
- * - **Auto Focus**: Search input automatically receives focus when dropdown opens
- * - **Focus Return**: Focus returns to trigger when dropdown closes via Escape or selection
- * - **Focus Trap**: Focus contained within popover when modal behavior is desired
- *
- * **Visual Accessibility:**
- * - **Color Contrast**: All states meet WCAG AA contrast requirements (4.5:1)
- * - **Focus Indicators**: Clear visual focus indicators for all interactive elements
- * - **Hover States**: Distinct hover states for better interaction feedback
- * - **Disabled State**: Visually distinct disabled options with reduced opacity
- * - **Selection Indicator**: Check icon provides clear visual selection feedback
- * - **High Contrast Mode**: Supports Windows High Contrast Mode
- *
- * **Touch and Mobile Accessibility:**
- * - **Touch Targets**: Minimum 44px touch target size for mobile interactions
- * - **Scroll Behavior**: Proper scroll support for long option lists
- * - **Responsive Design**: Adapts to different screen sizes and orientations
- * - **Mobile Navigation**: Touch-optimized selection and scrolling
- *
- * @performance
- *
- * **Optimization Strategies:**
- * - **Efficient Filtering**: Single-pass option filtering with memoized results
- * - **Minimal Re-renders**: Optimized state management prevents unnecessary renders
- * - **Virtual Scrolling**: Built-in support for large datasets via CMDK virtualization
- * - **Debounced Search**: Search input changes debounced to prevent excessive API calls
- * - **Lazy Loading**: Options can be loaded asynchronously as needed
- *
- * **Memory Management:**
- * - **Event Cleanup**: Proper cleanup of event listeners and timers
- * - **Reference Management**: No memory leaks through proper ref handling
- * - **Option Caching**: Previously loaded options cached for better performance
- *
- * @technical
- *
- * **Component Composition:**
- * ```
- * Combobox
- * ├── Popover (Radix UI)
- * │   ├── PopoverTrigger
- * │   │   └── Button (outline variant)
- * │   └── PopoverContent
- * │       └── Command (CMDK)
- * │           ├── CommandInput (search)
- * │           └── CommandList
- * │               ├── CommandEmpty
- * │               └── CommandGroup
- * │                   └── CommandItem(s)
- * ```
- *
- * **State Flow:**
- * 1. User clicks trigger → Popover opens → Command input focuses
- * 2. User types → CMDK filters options → Results update
- * 3. User navigates → aria-activedescendant updates → Visual focus moves
- * 4. User selects → onValueChange fires → Popover closes → Focus returns
- *
- * **Event Handling:**
- * - Popover manages open/close state and positioning
- * - CMDK handles keyboard navigation and filtering
- * - Button handles trigger interactions and ARIA states
- * - Custom logic manages selection and deselection behavior
- *
- * @see {@link https://ui.shadcn.com/docs/components/combobox} shadcn/ui Combobox documentation
- * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/combobox/} W3C ARIA Combobox Pattern
- * @see {@link https://www.radix-ui.com/primitives/docs/components/popover} Radix UI Popover API
- * @see {@link https://cmdk.paco.me/} CMDK Command Menu documentation
- * @see {@link Select} For simpler dropdowns without search functionality
- * @see {@link Command} The underlying command menu component
- * @see {@link Popover} The popover container component
- * @see {@link Button} The trigger button component
- * @since 1.0.0
+ * Individual chip representing a selected item in multi-select mode.
+ * Use within ComboboxChips. Includes remove button by default.
  */
-function Combobox({
-  options,
-  value,
-  onValueChange,
-  placeholder = "Select option...",
-  emptyText = "No option found.",
-  searchPlaceholder = "Search options...",
+function ComboboxChip({
   className,
-  disabled = false,
-  buttonClassName,
-  popoverClassName,
-  ...popoverProps
-}: {
-  options: ComboboxOption[];
-  value?: string;
-  onValueChange?: (value: string) => void;
-  placeholder?: string;
-  emptyText?: string;
-  searchPlaceholder?: string;
-  className?: string;
-  disabled?: boolean;
-  buttonClassName?: string;
-  popoverClassName?: string;
-} & Omit<React.ComponentProps<typeof Popover>, "children">) {
-  const [open, setOpen] = React.useState(false);
-
-  const selectedOption = options.find((option) => option.value === value);
-
-  const handleSelect = (selectedValue: string) => {
-    const newValue = selectedValue === value ? "" : selectedValue;
-    onValueChange?.(newValue);
-    setOpen(false);
-  };
+  children,
+  showRemove = true,
+  ...props
+}: ComboboxChipProps) {
+  return (
+    <ComboboxPrimitive.Chip
+      data-slot="combobox-chip"
+      className={cn(
+        "bg-muted text-foreground flex h-[calc(--spacing(5.5))] w-fit items-center justify-center gap-1 rounded-sm px-1.5 text-xs font-medium whitespace-nowrap has-data-[slot=combobox-chip-remove]:pr-0 has-disabled:pointer-events-none has-disabled:cursor-not-allowed has-disabled:opacity-50",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      {showRemove && (
+        <ComboboxPrimitive.ChipRemove
+          render={<Button variant="ghost" size="icon-xs" />}
+          className="-ml-1 opacity-50 hover:opacity-100"
+          data-slot="combobox-chip-remove"
+        >
+          <XIcon className="pointer-events-none" />
+        </ComboboxPrimitive.ChipRemove>
+      )}
+    </ComboboxPrimitive.Chip>
+  );
+}
+
+type ComboboxChipsInputProps = ComboboxPrimitive.Input.Props;
 
+/**
+ * Text input for multi-select combobox. Use within ComboboxChips alongside chips.
+ * This is the input field where users type to filter items.
+ */
+function ComboboxChipsInput({ className, ...props }: ComboboxChipsInputProps) {
   return (
-    <div className={className}>
-      <Popover open={open} onOpenChange={setOpen} {...popoverProps}>
-        <PopoverTrigger asChild>
-          <Button
-            variant="outline"
-            role="combobox"
-            aria-expanded={open}
-            aria-haspopup="listbox"
-            aria-controls={open ? "combobox-options" : undefined}
-            disabled={disabled}
-            className={cn(
-              "w-full justify-between",
-              !selectedOption && "text-muted-foreground",
-              buttonClassName,
-            )}
-          >
-            {selectedOption ? selectedOption.label : placeholder}
-            <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
-          </Button>
-        </PopoverTrigger>
-        <PopoverContent className={cn("w-full p-0", popoverClassName)}>
-          <Command>
-            <CommandInput placeholder={searchPlaceholder} className="h-9" />
-            <CommandList id="combobox-options">
-              <CommandEmpty>{emptyText}</CommandEmpty>
-              <CommandGroup>
-                {options.map((option) => (
-                  <CommandItem
-                    key={option.value}
-                    value={option.value}
-                    disabled={option.disabled}
-                    onSelect={handleSelect}
-                    aria-selected={value === option.value}
-                  >
-                    <Check
-                      className={cn(
-                        "mr-2 h-4 w-4",
-                        value === option.value ? "opacity-100" : "opacity-0",
-                      )}
-                      aria-hidden="true"
-                    />
-                    {option.label}
-                  </CommandItem>
-                ))}
-              </CommandGroup>
-            </CommandList>
-          </Command>
-        </PopoverContent>
-      </Popover>
-    </div>
+    <ComboboxPrimitive.Input
+      data-slot="combobox-chip-input"
+      className={cn("min-w-16 flex-1 outline-none", className)}
+      {...props}
+    />
   );
 }
 
-export { Combobox };
+/**
+ * Hook that returns a ref for anchoring the popup to the chips container.
+ * Use: `const anchorRef = useComboboxAnchor()` then pass to both ComboboxChips and ComboboxContent.
+ */
+function useComboboxAnchor() {
+  return React.useRef<HTMLDivElement | null>(null);
+}
+
+export {
+  Combobox,
+  ComboboxInput,
+  ComboboxContent,
+  ComboboxList,
+  ComboboxItem,
+  ComboboxGroup,
+  ComboboxLabel,
+  ComboboxCollection,
+  ComboboxEmpty,
+  ComboboxSeparator,
+  ComboboxChips,
+  ComboboxChip,
+  ComboboxChipsInput,
+  ComboboxTrigger,
+  ComboboxValue,
+  useComboboxAnchor,
+  type ComboboxProps,
+  type ComboboxInputProps,
+  type ComboboxContentProps,
+  type ComboboxListProps,
+  type ComboboxItemProps,
+  type ComboboxGroupProps,
+  type ComboboxLabelProps,
+  type ComboboxCollectionProps,
+  type ComboboxEmptyProps,
+  type ComboboxSeparatorProps,
+  type ComboboxChipsProps,
+  type ComboboxChipProps,
+  type ComboboxChipsInputProps,
+  type ComboboxTriggerProps,
+  type ComboboxValueProps,
+  type ComboboxClearProps,
+};