@neynar/ui 0.1.1 → 0.1.2

package/dist/components/ui/combobox.d.ts

@@ -1,3 +1,5 @@
+import * as React from "react";
+import { Popover } from "@/components/ui/popover";
 /**
  * Option structure for combobox items
  *
@@ -28,111 +30,30 @@ export type ComboboxOption = {
      */
     disabled?: boolean;
 };
-/**
- * Properties for the Combobox component
- *
- * Comprehensive configuration options for customizing combobox behavior,
- * appearance, and interaction patterns.
- *
- * @since 1.0.0
- */
-export type ComboboxProps = {
-    /**
-     * 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.
-     */
-    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.
-     */
-    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.
-     *
-     * @param value - The newly selected option value or empty string for deselection
-     */
-    onValueChange?: (value: string) => void;
-    /**
-     * Placeholder text displayed when no option is selected
-     *
-     * Should be descriptive and help users understand what they're selecting.
-     *
-     * @default "Select option..."
-     */
-    placeholder?: string;
-    /**
-     * Text displayed when search query returns no matching options
-     *
-     * Customize this message to match your application's tone and context.
-     *
-     * @default "No option found."
-     */
-    emptyText?: string;
-    /**
-     * Placeholder text for the search input field
-     *
-     * Should guide users on how to search effectively within your option set.
-     *
-     * @default "Search options..."
-     */
-    searchPlaceholder?: string;
-    /**
-     * Additional CSS classes for the root container element
-     *
-     * Use for custom spacing, positioning, or layout adjustments.
-     */
-    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.
-     *
-     * @default false
-     */
-    disabled?: boolean;
-    /**
-     * Additional CSS classes for the trigger button
-     *
-     * Commonly used to control width (e.g., "w-[300px]"), styling variants,
-     * or responsive behavior. For best UX, consider matching popoverClassName width.
-     *
-     * @example "w-full sm:w-[280px] border-primary/50"
-     */
-    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.
-     *
-     * @example "w-full sm:w-[280px] border-primary/50"
-     */
-    popoverClassName?: string;
-};
 /**
  * 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 top of shadcn/ui Command and Popover primitives.
+ * improves user experience. Built on Radix UI Popover primitives for accessibility and
+ * CMDK for powerful command menu functionality with real-time filtering.
  *
- * Use this component when:
- * - You have 10+ options that would benefit from filtering
- * - Users need to quickly find specific options
- * - You want to provide a better UX than a basic select dropdown
- * - You need real-time search/filtering capabilities
+ * **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
  *
- * For fewer options or simpler selection, consider using the Select component instead.
+ * **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
@@ -141,9 +62,9 @@ export type ComboboxProps = {
  * const [framework, setFramework] = useState("")
  *
  * const frameworks = [
- *   { value: "next", label: "Next.js" },
+ *   { value: "nextjs", label: "Next.js" },
  *   { value: "remix", label: "Remix" },
- *   { value: "svelte", label: "SvelteKit" },
+ *   { value: "sveltekit", label: "SvelteKit" },
  *   { value: "nuxt", label: "Nuxt.js" },
  * ]
  *
@@ -154,11 +75,12 @@ export type ComboboxProps = {
  *   placeholder="Select framework..."
  *   searchPlaceholder="Search frameworks..."
  *   buttonClassName="w-[300px]"
+ *   popoverClassName="w-[300px]"
  * />
  * ```
  *
  * @example
- * Combobox with disabled options and custom styling
+ * Advanced combobox with disabled options and custom styling
  * ```tsx
  * const statusOptions = [
  *   { value: "active", label: "Active" },
@@ -170,101 +92,227 @@ export type ComboboxProps = {
  * <Combobox
  *   options={statusOptions}
  *   value={status}
- *   onValueChange={setStatus}
+ *   onValueChange={(value) => {
+ *     setStatus(value)
+ *     // Track selection analytics
+ *     analytics.track('status_selected', { value })
+ *   }}
  *   placeholder="Select status..."
- *   emptyText="No status found."
+ *   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 states
+ * Form integration with validation and error handling
  * ```tsx
  * import { Label } from "@/components/ui/label"
+ * import { useFormContext } from "react-hook-form"
  *
- * <form onSubmit={handleSubmit}>
- *   <div className="space-y-2">
- *     <Label htmlFor="country">Country</Label>
- *     <Combobox
- *       options={countries}
- *       value={formData.country}
- *       onValueChange={(value) =>
- *         setFormData(prev => ({ ...prev, country: value }))
- *       }
- *       placeholder="Choose a country..."
- *       searchPlaceholder="Type to search countries..."
- *       emptyText="Country not found."
- *       buttonClassName="w-full"
- *       disabled={isSubmitting}
- *     />
- *     {errors.country && (
- *       <p className="text-sm text-destructive">{errors.country}</p>
- *     )}
- *   </div>
- * </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 width with mobile optimization
+ * Responsive design with mobile optimization
  * ```tsx
  * <Combobox
- *   options={userOptions}
- *   value={selectedUser}
- *   onValueChange={setSelectedUser}
- *   placeholder="Select team member..."
- *   searchPlaceholder="Search users..."
- *   buttonClassName="w-full sm:w-[280px]"
- *   popoverClassName="w-full sm:w-[280px]"
+ *   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:**
- * - Uses `role="combobox"` on trigger button with proper `aria-expanded` state
- * - Implements `aria-controls` to reference the popup when visible
- * - Uses `aria-activedescendant` for focus management within the dropdown
- * - Provides `aria-haspopup="listbox"` to indicate popup type
+ * **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 compliant):**
- * - **Tab**: Moves focus to/from combobox in page tab order
- * - **Down Arrow**: Opens dropdown and moves to first option, or navigates to next option
+ * **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)
- * - **Enter**: Selects the focused option and closes dropdown
- * - **Escape**: Closes dropdown and returns focus to trigger
- * - **Home/End**: Moves to first/last option in list
+ * - **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:**
- * - Announces current selection state and option count
- * - Provides clear labels for empty states and loading states
- * - Announces selection changes and dropdown open/close states
- * - Disabled options are properly announced and skipped during navigation
+ * - **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:**
- * - DOM focus remains on combobox trigger for screen reader compatibility
- * - Visual focus moves through options using `aria-activedescendant`
- * - Search input automatically receives focus when dropdown opens
- * - Focus returns to trigger when dropdown closes via Escape or selection
+ * - **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:**
- * - Maintains sufficient color contrast for all states
- * - Provides hover and focus indicators for all interactive elements
- * - Disabled options are visually distinct and non-interactive
- * - Clear visual feedback for selected state with check icon
+ * - **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
- * - Efficient option lookup with single find() operation
- * - Minimal re-renders through proper state management
- * - Supports large option lists with built-in virtualization via cmdk
+ *
+ * **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
  */
-export declare function Combobox({ options, value, onValueChange, placeholder, emptyText, searchPlaceholder, className, disabled, buttonClassName, popoverClassName, }: ComboboxProps): import("react/jsx-runtime").JSX.Element;
+declare function Combobox({ options, value, onValueChange, placeholder, emptyText, searchPlaceholder, className, disabled, 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">): import("react/jsx-runtime").JSX.Element;
+export { Combobox };
 //# sourceMappingURL=combobox.d.ts.map

package/dist/components/ui/combobox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["../../../src/components/ui/combobox.tsx"],"names":[],"mappings":"AAqBA;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;;OAKG;IACH,OAAO,EAAE,cAAc,EAAE,CAAC;IAE1B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkJG;AACH,wBAAgB,QAAQ,CAAC,EACvB,OAAO,EACP,KAAK,EACL,aAAa,EACb,WAAgC,EAChC,SAA8B,EAC9B,iBAAuC,EACvC,SAAS,EACT,QAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,EAAE,aAAa,2CA2Df"}
+{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["../../../src/components/ui/combobox.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAa/B,OAAO,EACL,OAAO,EAGR,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAiKF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+QG;AACH,iBAAS,QAAQ,CAAC,EAChB,OAAO,EACP,KAAK,EACL,aAAa,EACb,WAAgC,EAChC,SAA8B,EAC9B,iBAAuC,EACvC,SAAS,EACT,QAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,GAAG,YAAY,EAChB,EAAE;IACD,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,OAAO,CAAC,EAAE,UAAU,CAAC,2CA+DzD;AAED,OAAO,EAAE,QAAQ,EAAE,CAAC"}