@neynar/ui 0.1.1

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

@@ -0,0 +1,182 @@
+import * as React from "react";
+import * as CollapsiblePrimitive from "@radix-ui/react-collapsible";
+/**
+ * An interactive component which expands/collapses a panel
+ *
+ * A flexible container component built on Radix UI primitives that allows users to
+ * toggle the visibility of content sections. Unlike Accordion, Collapsible provides
+ * more flexibility without enforcing specific visual structures. Perfect for FAQ sections,
+ * expandable details, settings panels, and any content that should be initially hidden.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic controlled collapsible
+ * const [isOpen, setIsOpen] = React.useState(false)
+ *
+ * <Collapsible open={isOpen} onOpenChange={setIsOpen}>
+ *   <CollapsibleTrigger asChild>
+ *     <Button variant="outline">
+ *       Can I use this in my project?
+ *       <ChevronDown className="h-4 w-4" />
+ *     </Button>
+ *   </CollapsibleTrigger>
+ *   <CollapsibleContent>
+ *     <div className="p-4 border rounded-md bg-muted/50">
+ *       Yes. Free to use for personal and commercial projects.
+ *       No attribution required.
+ *     </div>
+ *   </CollapsibleContent>
+ * </Collapsible>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled collapsible with custom styling
+ * <Collapsible className="w-full space-y-2">
+ *   <div className="flex items-center justify-between">
+ *     <h4 className="text-sm font-semibold">@radix-ui/primitives</h4>
+ *     <CollapsibleTrigger asChild>
+ *       <Button variant="ghost" size="sm">
+ *         <ChevronDown className="h-4 w-4" />
+ *         <span className="sr-only">Toggle</span>
+ *       </Button>
+ *     </CollapsibleTrigger>
+ *   </div>
+ *   <CollapsibleContent className="space-y-2">
+ *     <div className="rounded-md border px-4 py-2 text-sm shadow-sm">
+ *       @radix-ui/react-collapsible
+ *     </div>
+ *   </CollapsibleContent>
+ * </Collapsible>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // FAQ-style implementation
+ * <Collapsible>
+ *   <CollapsibleTrigger className="flex w-full items-center justify-between py-4 text-sm font-medium transition-all hover:underline">
+ *     How do I get started?
+ *     <ChevronDown className="h-4 w-4 shrink-0 transition-transform duration-200" />
+ *   </CollapsibleTrigger>
+ *   <CollapsibleContent className="overflow-hidden text-sm transition-all">
+ *     <div className="pb-4 pt-0">
+ *       Getting started is easy! Simply follow our quick setup guide...
+ *     </div>
+ *   </CollapsibleContent>
+ * </Collapsible>
+ * ```
+ *
+ * @accessibility
+ * - Full keyboard navigation support (Space/Enter to toggle)
+ * - ARIA expanded state automatically managed
+ * - Content properly hidden from screen readers when collapsed
+ * - Focus management and screen reader announcements
+ * - Built on WAI-ARIA design patterns for disclosure widgets
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/collapsible} for design patterns
+ * @see {@link CollapsibleTrigger} - Interactive element to toggle visibility
+ * @see {@link CollapsibleContent} - Content container that can be hidden/shown
+ * @since 1.0.0
+ */
+declare function Collapsible({ ...props }: React.ComponentProps<typeof CollapsiblePrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Interactive trigger element that toggles collapsible content visibility
+ *
+ * The clickable element that controls the expanded/collapsed state of the associated
+ * CollapsibleContent. Supports the asChild prop for composition with custom elements
+ * like buttons or other interactive components.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Simple text trigger
+ * <CollapsibleTrigger>
+ *   Can I use this in my project?
+ * </CollapsibleTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Composed with Button component
+ * <CollapsibleTrigger asChild>
+ *   <Button variant="outline" className="w-full justify-between">
+ *     Advanced Settings
+ *     <ChevronDown className="h-4 w-4" />
+ *   </Button>
+ * </CollapsibleTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styled trigger
+ * <CollapsibleTrigger className="flex w-full items-center justify-between py-4 text-left text-sm font-medium transition-all hover:underline">
+ *   How does it work?
+ *   <ChevronDown className="h-4 w-4 shrink-0 transition-transform duration-200" />
+ * </CollapsibleTrigger>
+ * ```
+ *
+ * @accessibility
+ * - Keyboard activation with Space or Enter keys
+ * - aria-expanded attribute reflects current expanded state
+ * - aria-controls connects trigger to its content panel
+ * - Role of button for screen reader compatibility
+ * - Focus visible indicator for keyboard navigation
+ *
+ * @since 1.0.0
+ */
+declare function CollapsibleTrigger({ ...props }: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleTrigger>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Content container that can be expanded or collapsed
+ *
+ * The panel containing content that is shown or hidden based on the collapsible state.
+ * Automatically handles smooth animations, height transitions, and accessibility attributes
+ * when toggling between expanded and collapsed states.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic content panel
+ * <CollapsibleContent>
+ *   <div className="rounded-md border px-4 py-2 text-sm">
+ *     Yes. Free to use for personal and commercial projects.
+ *     No attribution required.
+ *   </div>
+ * </CollapsibleContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Content with custom styling and multiple elements
+ * <CollapsibleContent className="space-y-2">
+ *   <div className="rounded-md border px-4 py-3 font-mono text-sm">
+ *     @radix-ui/react-collapsible
+ *   </div>
+ *   <div className="rounded-md border px-4 py-3 font-mono text-sm">
+ *     @radix-ui/react-dialog
+ *   </div>
+ * </CollapsibleContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Content with overflow handling
+ * <CollapsibleContent className="overflow-hidden text-sm transition-all data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down">
+ *   <div className="pb-4 pt-0">
+ *     Content with custom animations and overflow handling.
+ *   </div>
+ * </CollapsibleContent>
+ * ```
+ *
+ * @accessibility
+ * - Automatically hidden from accessibility tree when collapsed
+ * - Smooth height animations with data-state attributes
+ * - Properly associated with trigger via aria-controls
+ * - Supports custom animation classes and transitions
+ * - Content is announced by screen readers when expanded
+ *
+ * @since 1.0.0
+ */
+declare function CollapsibleContent({ ...props }: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleContent>): import("react/jsx-runtime").JSX.Element;
+export { Collapsible, CollapsibleTrigger, CollapsibleContent };
+//# sourceMappingURL=collapsible.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"collapsible.d.ts","sourceRoot":"","sources":["../../../src/components/ui/collapsible.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,oBAAoB,MAAM,6BAA6B,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,iBAAS,WAAW,CAAC,EACnB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,IAAI,CAAC,2CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,iBAAS,kBAAkB,CAAC,EAC1B,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,kBAAkB,CAAC,2CAOtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,iBAAS,kBAAkB,CAAC,EAC1B,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,kBAAkB,CAAC,2CAOtE;AAED,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,CAAC"}

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

@@ -0,0 +1,270 @@
+/**
+ * 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
+ */
+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;
+};
+/**
+ * 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.
+ *
+ * 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
+ *
+ * For fewer options or simpler selection, consider using the Select component instead.
+ *
+ * @component
+ * @example
+ * Basic controlled combobox with framework selection
+ * ```tsx
+ * const [framework, setFramework] = useState("")
+ *
+ * const frameworks = [
+ *   { value: "next", label: "Next.js" },
+ *   { value: "remix", label: "Remix" },
+ *   { value: "svelte", label: "SvelteKit" },
+ *   { value: "nuxt", label: "Nuxt.js" },
+ * ]
+ *
+ * <Combobox
+ *   options={frameworks}
+ *   value={framework}
+ *   onValueChange={setFramework}
+ *   placeholder="Select framework..."
+ *   searchPlaceholder="Search frameworks..."
+ *   buttonClassName="w-[300px]"
+ * />
+ * ```
+ *
+ * @example
+ * 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={setStatus}
+ *   placeholder="Select status..."
+ *   emptyText="No status found."
+ *   buttonClassName="w-[250px] border-primary/50"
+ *   popoverClassName="w-[250px]"
+ * />
+ * ```
+ *
+ * @example
+ * Form integration with validation and error states
+ * ```tsx
+ * import { Label } from "@/components/ui/label"
+ *
+ * <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>
+ * ```
+ *
+ * @example
+ * Responsive width 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]"
+ * />
+ * ```
+ *
+ * @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
+ *
+ * **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
+ * - **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
+ * - **Type-ahead**: Real-time filtering as user types in search input
+ *
+ * **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
+ *
+ * **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
+ *
+ * **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
+ *
+ * @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
+ *
+ * @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 Select} For simpler dropdowns without search functionality
+ * @see {@link Command} The underlying command menu component
+ * @see {@link Popover} The popover container 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;
+//# sourceMappingURL=combobox.d.ts.map

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

@@ -0,0 +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"}