@neynar/ui 0.1.1 → 0.1.2

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

@@ -6,7 +6,7 @@ import * as SelectPrimitive from "@radix-ui/react-select";
  * Provides a dropdown menu for selecting a single option from a list of choices.
  * Features comprehensive keyboard navigation, grouping capabilities, accessibility
  * compliance, and flexible styling options. Perfect for forms, filters, and
- * configuration interfaces.
+ * configuration interfaces. Built on Radix UI Select.Root with enhanced styling.
  *
  * @component
  * @example
@@ -42,7 +42,7 @@ import * as SelectPrimitive from "@radix-ui/react-select";
  *
  * @example
  * ```tsx
- * // Grouped options with separators
+ * // Grouped options with separators and labels
  * <Select>
  *   <SelectTrigger>
  *     <SelectValue placeholder="Select a timezone" />
@@ -52,6 +52,7 @@ import * as SelectPrimitive from "@radix-ui/react-select";
  *       <SelectLabel>North America</SelectLabel>
  *       <SelectItem value="est">Eastern Time (EST)</SelectItem>
  *       <SelectItem value="cst">Central Time (CST)</SelectItem>
+ *       <SelectItem value="pst">Pacific Time (PST)</SelectItem>
  *     </SelectGroup>
  *     <SelectSeparator />
  *     <SelectGroup>
@@ -63,19 +64,55 @@ import * as SelectPrimitive from "@radix-ui/react-select";
  * </Select>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Form integration with validation and required state
+ * <form>
+ *   <Select name="userRole" required defaultValue="">
+ *     <SelectTrigger id="role" aria-describedby="role-error">
+ *       <SelectValue placeholder="Choose your role" />
+ *     </SelectTrigger>
+ *     <SelectContent>
+ *       <SelectItem value="admin">Administrator</SelectItem>
+ *       <SelectItem value="user">User</SelectItem>
+ *       <SelectItem value="guest">Guest</SelectItem>
+ *     </SelectContent>
+ *   </Select>
+ * </form>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled states and interactions
+ * <Select disabled>
+ *   <SelectTrigger>
+ *     <SelectValue placeholder="Disabled select" />
+ *   </SelectTrigger>
+ *   <SelectContent>
+ *     <SelectItem value="1">Option 1</SelectItem>
+ *     <SelectItem value="2" disabled>Option 2 (disabled)</SelectItem>
+ *   </SelectContent>
+ * </Select>
+ * ```
+ *
  * @accessibility
- * - Full keyboard navigation (Arrow keys, Enter, Space, Escape, Home, End)
- * - ARIA compliant with proper roles, states, and properties
- * - Screen reader announcements for selection changes and state updates
- * - Focus management and trapping within dropdown
- * - Support for disabled state on both trigger and individual items
- * - Proper labeling and description associations
+ * - **Keyboard Navigation**: Arrow keys to navigate items, Enter/Space to select, Escape to close
+ * - **Focus Management**: Focus trapped within dropdown when open, returns to trigger on close
+ * - **Screen Reader Support**: Announces selected values, state changes, and item counts
+ * - **ARIA Compliance**: Proper roles (combobox, listbox, option), states (expanded, selected), and properties
+ * - **Typeahead**: Type characters to jump to matching items
+ * - **Home/End Keys**: Jump to first/last items in the list
+ * - **Disabled State**: Properly communicated to assistive technology
+ * - **Required Field**: Integrates with form validation and screen reader announcements
  *
  * @see {@link SelectTrigger} - The button that opens the dropdown
  * @see {@link SelectContent} - The dropdown content container
  * @see {@link SelectItem} - Individual selectable options
  * @see {@link SelectGroup} - Container for grouping related items
  * @see {@link SelectValue} - Displays selected value or placeholder
+ * @see {@link SelectLabel} - Non-selectable labels for groups
+ * @see {@link SelectSeparator} - Visual dividers between groups
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/select} for Radix UI documentation
  * @see {@link https://ui.shadcn.com/docs/components/select} for design patterns
  * @since 1.0.0
  */
@@ -84,20 +121,57 @@ declare function Select({ ...props }: React.ComponentProps<typeof SelectPrimitiv
  * SelectGroup - Container for grouping related select items
  *
  * Groups related options together with an optional label for better organization
- * and improved user experience when dealing with many options.
+ * and improved user experience when dealing with many options. Built on Radix UI
+ * Select.Group with semantic grouping that enhances screen reader navigation.
  *
  * @component
  * @example
  * ```tsx
+ * // Basic group with label
  * <SelectGroup>
  *   <SelectLabel>Fruits</SelectLabel>
  *   <SelectItem value="apple">Apple</SelectItem>
  *   <SelectItem value="banana">Banana</SelectItem>
+ *   <SelectItem value="orange">Orange</SelectItem>
+ * </SelectGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple groups with separators
+ * <SelectContent>
+ *   <SelectGroup>
+ *     <SelectLabel>Popular Choices</SelectLabel>
+ *     <SelectItem value="most-popular">Most Popular</SelectItem>
+ *     <SelectItem value="trending">Trending</SelectItem>
+ *   </SelectGroup>
+ *   <SelectSeparator />
+ *   <SelectGroup>
+ *     <SelectLabel>All Options</SelectLabel>
+ *     <SelectItem value="option1">Option 1</SelectItem>
+ *     <SelectItem value="option2">Option 2</SelectItem>
+ *   </SelectGroup>
+ * </SelectContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Group without label for simple separation
+ * <SelectGroup>
+ *   <SelectItem value="item1">Item 1</SelectItem>
+ *   <SelectItem value="item2">Item 2</SelectItem>
  * </SelectGroup>
  * ```
  *
- * @see {@link SelectLabel} - Label for the group
- * @see {@link SelectItem} - Items within the group
+ * @accessibility
+ * - **Semantic Grouping**: Creates logical groups that screen readers can navigate
+ * - **Label Association**: SelectLabel properly associates with group items
+ * - **Focus Management**: Arrow keys move between items within and across groups
+ * - **Screen Reader Navigation**: Group boundaries announced to assistive technology
+ *
+ * @see {@link SelectLabel} - Optional label for the group
+ * @see {@link SelectItem} - Individual items within the group
+ * @see {@link SelectSeparator} - Visual divider between groups
  * @since 1.0.0
  */
 declare function SelectGroup({ ...props }: React.ComponentProps<typeof SelectPrimitive.Group>): import("react/jsx-runtime").JSX.Element;
@@ -105,17 +179,56 @@ declare function SelectGroup({ ...props }: React.ComponentProps<typeof SelectPri
  * SelectValue - Displays the selected value or placeholder
  *
  * Renders the currently selected option's text or a placeholder when no option
- * is selected. Must be used inside SelectTrigger.
+ * is selected. Built on Radix UI Select.Value with proper text truncation and
+ * styling. Must be used inside SelectTrigger to display the current selection state.
  *
  * @component
  * @example
  * ```tsx
+ * // Basic usage with placeholder
  * <SelectTrigger>
  *   <SelectValue placeholder="Choose an option" />
  * </SelectTrigger>
  * ```
  *
- * @see {@link SelectTrigger} - Parent container for the value
+ * @example
+ * ```tsx
+ * // Custom placeholder styling
+ * <SelectTrigger>
+ *   <SelectValue
+ *     placeholder={
+ *       <span className="text-muted-foreground italic">
+ *         No selection made
+ *       </span>
+ *     }
+ *   />
+ * </SelectTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using asChild for complete custom rendering
+ * <SelectValue asChild>
+ *   <div className="flex items-center gap-2">
+ *     {selectedItem ? (
+ *       <>
+ *         <ItemIcon />
+ *         <span>{selectedItem.label}</span>
+ *       </>
+ *     ) : (
+ *       <span className="text-muted-foreground">Select item...</span>
+ *     )}
+ *   </div>
+ * </SelectValue>
+ * ```
+ *
+ * @accessibility
+ * - **Value Announcement**: Selected value announced to screen readers
+ * - **Placeholder Semantics**: Placeholder properly identified for assistive technology
+ * - **Text Truncation**: Long values truncated with ellipsis to prevent layout issues
+ * - **Content Updates**: Dynamic content changes announced to screen readers
+ *
+ * @see {@link SelectTrigger} - Required parent container for the value display
  * @since 1.0.0
  */
 declare function SelectValue({ ...props }: React.ComponentProps<typeof SelectPrimitive.Value>): import("react/jsx-runtime").JSX.Element;
@@ -123,8 +236,13 @@ declare function SelectValue({ ...props }: React.ComponentProps<typeof SelectPri
  * SelectTrigger - The button that opens the select dropdown
  *
  * A styled button that displays the current value and triggers the dropdown menu.
- * Includes a chevron icon to indicate dropdown functionality and supports different
- * size variants for various UI contexts.
+ * Built on Radix UI Select.Trigger with enhanced styling including focus states,
+ * size variants, and proper hover interactions. Includes a chevron icon to indicate
+ * dropdown functionality and supports different size variants for various UI contexts.
+ *
+ * **Size Variants:**
+ * - `default`: Standard height (36px) suitable for most forms and interfaces
+ * - `sm`: Compact height (32px) ideal for dense layouts and table interfaces
  *
  * @component
  * @example
@@ -139,45 +257,63 @@ declare function SelectValue({ ...props }: React.ComponentProps<typeof SelectPri
  * ```tsx
  * // Small size variant for compact layouts
  * <SelectTrigger size="sm" className="w-[150px]">
- *   <SelectValue placeholder="Compact" />
+ *   <SelectValue placeholder="Compact select" />
  * </SelectTrigger>
  * ```
  *
  * @example
  * ```tsx
- * // With form integration
+ * // Form integration with accessibility attributes
+ * <label htmlFor="user-role">User Role</label>
  * <SelectTrigger id="user-role" aria-describedby="role-help">
  *   <SelectValue placeholder="Choose role" />
  * </SelectTrigger>
+ * <div id="role-help">Select the appropriate role for this user</div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom composition using asChild
+ * <SelectTrigger asChild>
+ *   <button className="custom-trigger-styles">
+ *     <SelectValue />
+ *     <CustomChevronIcon />
+ *   </button>
+ * </SelectTrigger>
  * ```
  *
  * @accessibility
- * - Keyboard accessible with Enter/Space to open dropdown
- * - Arrow keys navigate when closed (opens and moves to first/last item)
- * - Properly announces state changes to screen readers
- * - Focus visible ring for keyboard navigation
- * - Supports aria-describedby for additional context
- * - Disabled state properly communicated to assistive technology
+ * - **Keyboard Navigation**: Enter/Space to open dropdown, Arrow keys to navigate when closed
+ * - **Focus Management**: Clear focus ring for keyboard users, focus returns after selection
+ * - **State Announcements**: Screen readers announce open/closed state and selected value
+ * - **ARIA Support**: Proper combobox role with expanded state and controls relationship
+ * - **Form Integration**: Works with labels, validation, and form submission
+ * - **Disabled State**: Properly communicated to assistive technology with reduced opacity
+ * - **RTL Support**: Automatically adapts layout for right-to-left reading modes
  *
  * @see {@link SelectValue} - Displays the selected value or placeholder
+ * @see {@link SelectContent} - The dropdown content that opens
  * @since 1.0.0
  */
 declare function SelectTrigger({ className, size, children, ...props }: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
-    /**
-     * The size variant of the trigger button
-     * @default "default"
-     */
     size?: "sm" | "default";
 }): import("react/jsx-runtime").JSX.Element;
 /**
  * SelectContent - Container for the dropdown content
  *
  * The dropdown panel that contains all selectable items, groups, and labels.
- * Automatically handles scrolling for long lists and positioning relative to the trigger.
+ * Built on Radix UI Select.Content with Portal rendering for proper layering.
+ * Automatically handles scrolling for long lists, collision detection, and
+ * positioning relative to the trigger with smooth animations.
+ *
+ * **Positioning Strategy:**
+ * - `popper`: Uses Floating UI for precise positioning with collision detection
+ * - `item-aligned`: Aligns content with the selected item for natural feel
  *
  * @component
  * @example
  * ```tsx
+ * // Basic content with multiple items
  * <SelectContent>
  *   <SelectItem value="1">Option 1</SelectItem>
  *   <SelectItem value="2">Option 2</SelectItem>
@@ -187,19 +323,56 @@ declare function SelectTrigger({ className, size, children, ...props }: React.Co
  *
  * @example
  * ```tsx
- * // With fixed positioning
+ * // Item-aligned positioning (default behavior)
  * <SelectContent position="item-aligned">
+ *   <SelectItem value="apple">Apple</SelectItem>
+ *   <SelectItem value="banana">Banana</SelectItem>
+ * </SelectContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Popper positioning with custom placement
+ * <SelectContent position="popper" side="top" align="end">
  *   <SelectItem value="1">Option 1</SelectItem>
+ *   <SelectItem value="2">Option 2</SelectItem>
+ * </SelectContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex content with groups and scrolling
+ * <SelectContent>
+ *   <SelectGroup>
+ *     <SelectLabel>Recent Items</SelectLabel>
+ *     <SelectItem value="recent1">Recently Used 1</SelectItem>
+ *     <SelectItem value="recent2">Recently Used 2</SelectItem>
+ *   </SelectGroup>
+ *   <SelectSeparator />
+ *   <SelectGroup>
+ *     <SelectLabel>All Items</SelectLabel>
+ *     {items.map((item) => (
+ *       <SelectItem key={item.id} value={item.id}>
+ *         {item.label}
+ *       </SelectItem>
+ *     ))}
+ *   </SelectGroup>
  * </SelectContent>
  * ```
  *
  * @accessibility
- * - Focus trapped within dropdown when open
- * - Scrollable with keyboard navigation
- * - Escape key closes the dropdown
+ * - **Focus Management**: Focus trapped within dropdown when open, managed viewport scrolling
+ * - **Keyboard Navigation**: Arrow keys navigate items, Page Up/Down for quick navigation
+ * - **Portal Rendering**: Renders in document body for proper layering and screen reader access
+ * - **Collision Detection**: Automatically repositions to stay within viewport boundaries
+ * - **Scroll Indicators**: Shows scroll buttons when content exceeds available height
+ * - **Animation**: Smooth enter/exit animations that respect user's motion preferences
+ * - **Escape Handling**: Escape key closes dropdown and returns focus to trigger
  *
- * @see {@link SelectItem} - Individual options
- * @see {@link SelectGroup} - Group container
+ * @see {@link SelectItem} - Individual selectable options
+ * @see {@link SelectGroup} - Container for grouping related items
+ * @see {@link SelectScrollUpButton} - Scroll up indicator for long lists
+ * @see {@link SelectScrollDownButton} - Scroll down indicator for long lists
  * @since 1.0.0
  */
 declare function SelectContent({ className, children, position, ...props }: React.ComponentProps<typeof SelectPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
@@ -207,80 +380,173 @@ declare function SelectContent({ className, children, position, ...props }: Reac
  * SelectLabel - Label for a group of select items
  *
  * Provides a non-selectable label for categorizing groups of options.
- * Helps users understand the context of the options below.
+ * Built on Radix UI Select.Label with muted styling and proper typography.
+ * Helps users understand the context of the options below and improves
+ * navigation for screen reader users.
  *
  * @component
  * @example
  * ```tsx
+ * // Basic group label
  * <SelectGroup>
  *   <SelectLabel>Countries</SelectLabel>
  *   <SelectItem value="us">United States</SelectItem>
  *   <SelectItem value="uk">United Kingdom</SelectItem>
+ *   <SelectItem value="ca">Canada</SelectItem>
  * </SelectGroup>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Multiple labeled groups
+ * <SelectContent>
+ *   <SelectGroup>
+ *     <SelectLabel>Primary Options</SelectLabel>
+ *     <SelectItem value="primary1">Primary Choice 1</SelectItem>
+ *     <SelectItem value="primary2">Primary Choice 2</SelectItem>
+ *   </SelectGroup>
+ *   <SelectSeparator />
+ *   <SelectGroup>
+ *     <SelectLabel>Advanced Options</SelectLabel>
+ *     <SelectItem value="advanced1">Advanced Choice 1</SelectItem>
+ *     <SelectItem value="advanced2">Advanced Choice 2</SelectItem>
+ *   </SelectGroup>
+ * </SelectContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styling with asChild
+ * <SelectLabel asChild>
+ *   <div className="flex items-center gap-1 px-2 py-1 font-semibold">
+ *     <Icon className="size-3" />
+ *     <span>Categories</span>
+ *   </div>
+ * </SelectLabel>
+ * ```
+ *
  * @accessibility
- * - Properly associated with group for screen readers
- * - Non-selectable and non-focusable
+ * - **Semantic Association**: Properly associated with group items for screen readers
+ * - **Non-Interactive**: Cannot receive focus or be selected
+ * - **Group Navigation**: Helps screen reader users understand item organization
+ * - **Descriptive Text**: Provides context for the items that follow
  *
- * @see {@link SelectGroup} - Parent container
+ * @see {@link SelectGroup} - Required parent container
+ * @see {@link SelectItem} - Items that this label describes
  * @since 1.0.0
  */
 declare function SelectLabel({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Label>): import("react/jsx-runtime").JSX.Element;
 /**
  * SelectItem - Individual selectable option in the dropdown
  *
- * Represents a single option that users can select. Shows a checkmark
- * when selected and supports keyboard navigation.
+ * Represents a single option that users can select. Built on Radix UI Select.Item
+ * with enhanced styling including hover states, selection indicators, and proper
+ * spacing. Shows a checkmark when selected and supports keyboard navigation with
+ * proper focus management.
  *
  * @component
  * @example
  * ```tsx
+ * // Basic item
  * <SelectItem value="apple">Apple</SelectItem>
  * ```
  *
  * @example
  * ```tsx
- * // Disabled item
+ * // Disabled item that cannot be selected
  * <SelectItem value="sold-out" disabled>
- *   Sold Out
+ *   Sold Out - Unavailable
  * </SelectItem>
  * ```
  *
- * @accessibility
- * - Arrow keys navigate between items
- * - Enter or Space selects the item
- * - Shows checkmark icon when selected
- * - Supports disabled state
+ * @example
+ * ```tsx
+ * // Complex item content with custom text value for typeahead
+ * <SelectItem value="user-123" textValue="John Doe">
+ *   <div className="flex items-center gap-2">
+ *     <Avatar size="sm" />
+ *     <div>
+ *       <div>John Doe</div>
+ *       <div className="text-xs text-muted-foreground">john@example.com</div>
+ *     </div>
+ *   </div>
+ * </SelectItem>
+ * ```
  *
- * @see {@link SelectContent} - Parent container
+ * @example
+ * ```tsx
+ * // Using asChild for custom item composition
+ * <SelectItem value="custom" asChild>
+ *   <div className="custom-item-styles">
+ *     Custom item content
+ *   </div>
+ * </SelectItem>
+ * ```
+ *
+ * @accessibility
+ * - **Keyboard Navigation**: Arrow keys navigate between items, Home/End jump to first/last
+ * - **Selection**: Enter or Space selects the item and closes dropdown
+ * - **Visual Feedback**: Check icon indicates selected state, focus ring for keyboard users
+ * - **Disabled State**: Cannot be selected or focused, announced to screen readers
+ * - **Typeahead**: Type characters to jump to matching items (uses textValue or content)
+ * - **Screen Reader**: Announces item text and selection state changes
+ *
+ * @see {@link SelectContent} - Parent container that manages items
+ * @see {@link SelectGroup} - Optional grouping container
  * @since 1.0.0
  */
 declare function SelectItem({ className, children, ...props }: React.ComponentProps<typeof SelectPrimitive.Item>): import("react/jsx-runtime").JSX.Element;
 /**
  * SelectSeparator - Visual divider between select groups
  *
- * A horizontal line that visually separates groups of options
- * for better organization and clarity.
+ * A horizontal line that visually separates groups of options for better
+ * organization and clarity. Built on Radix UI Select.Separator with subtle
+ * border styling that adapts to the current theme.
  *
  * @component
  * @example
  * ```tsx
+ * // Basic separation between groups
  * <SelectContent>
  *   <SelectGroup>
+ *     <SelectLabel>Group 1</SelectLabel>
  *     <SelectItem value="1">Option 1</SelectItem>
  *   </SelectGroup>
  *   <SelectSeparator />
  *   <SelectGroup>
+ *     <SelectLabel>Group 2</SelectLabel>
  *     <SelectItem value="2">Option 2</SelectItem>
  *   </SelectGroup>
  * </SelectContent>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Multiple separators in complex layouts
+ * <SelectContent>
+ *   <SelectGroup>
+ *     <SelectItem value="recent">Recent Items</SelectItem>
+ *   </SelectGroup>
+ *   <SelectSeparator />
+ *   <SelectGroup>
+ *     <SelectItem value="favorite">Favorites</SelectItem>
+ *   </SelectGroup>
+ *   <SelectSeparator />
+ *   <SelectGroup>
+ *     <SelectLabel>All Items</SelectLabel>
+ *     <SelectItem value="all1">Item 1</SelectItem>
+ *     <SelectItem value="all2">Item 2</SelectItem>
+ *   </SelectGroup>
+ * </SelectContent>
+ * ```
+ *
  * @accessibility
- * - Decorative element with no semantic meaning
- * - Not focusable or interactive
+ * - **Decorative Role**: Pure visual element with no semantic meaning for screen readers
+ * - **Non-Interactive**: Cannot receive focus or be activated
+ * - **Visual Organization**: Helps sighted users understand content structure
+ * - **Theme Adaptive**: Border color adapts to light/dark themes automatically
  *
+ * @see {@link SelectGroup} - Typically used to separate different groups
  * @since 1.0.0
  */
 declare function SelectSeparator({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Separator>): import("react/jsx-runtime").JSX.Element;
@@ -288,13 +554,41 @@ declare function SelectSeparator({ className, ...props }: React.ComponentProps<t
  * SelectScrollUpButton - Scroll button for navigating up in long lists
  *
  * Appears at the top of the dropdown when there are more items above
- * the visible area. Allows scrolling through long option lists.
+ * the visible area. Built on Radix UI Select.ScrollUpButton with chevron
+ * icon and hover states. Automatically shows/hides based on scroll position.
  *
  * @component
- * @accessibility
- * - Keyboard accessible
- * - Only visible when scrolling is available
+ * @example
+ * ```tsx
+ * // Automatically included in SelectContent
+ * <SelectContent>
+ *   // ScrollUpButton appears here when needed
+ *   <SelectItem value="1">Item 1</SelectItem>
+ *   // ... many items ...
+ *   <SelectItem value="100">Item 100</SelectItem>
+ *   // ScrollDownButton appears here when needed
+ * </SelectContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom scroll button using asChild
+ * <SelectScrollUpButton asChild>
+ *   <button className="custom-scroll-styles">
+ *     <CustomUpIcon />
+ *   </button>
+ * </SelectScrollUpButton>
+ * ```
  *
+ * @accessibility
+ * - **Auto-Visibility**: Only appears when upward scrolling is possible
+ * - **Keyboard Accessible**: Can be activated with Enter/Space
+ * - **Focus Management**: Receives focus during keyboard navigation
+ * - **Screen Reader**: Announced as scroll control with directional context
+ * - **Mouse/Touch**: Responds to click/touch interactions for scrolling
+ *
+ * @see {@link SelectContent} - Container that manages scroll button visibility
+ * @see {@link SelectScrollDownButton} - Counterpart for downward scrolling
  * @since 1.0.0
  */
 declare function SelectScrollUpButton({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>): import("react/jsx-runtime").JSX.Element;
@@ -302,13 +596,41 @@ declare function SelectScrollUpButton({ className, ...props }: React.ComponentPr
  * SelectScrollDownButton - Scroll button for navigating down in long lists
  *
  * Appears at the bottom of the dropdown when there are more items below
- * the visible area. Allows scrolling through long option lists.
+ * the visible area. Built on Radix UI Select.ScrollDownButton with chevron
+ * icon and hover states. Automatically shows/hides based on scroll position.
  *
  * @component
- * @accessibility
- * - Keyboard accessible
- * - Only visible when scrolling is available
+ * @example
+ * ```tsx
+ * // Automatically included in SelectContent
+ * <SelectContent>
+ *   // ScrollUpButton appears here when needed
+ *   <SelectItem value="1">Item 1</SelectItem>
+ *   // ... many items ...
+ *   <SelectItem value="100">Item 100</SelectItem>
+ *   // ScrollDownButton appears here when needed
+ * </SelectContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom scroll button using asChild
+ * <SelectScrollDownButton asChild>
+ *   <button className="custom-scroll-styles">
+ *     <CustomDownIcon />
+ *   </button>
+ * </SelectScrollDownButton>
+ * ```
  *
+ * @accessibility
+ * - **Auto-Visibility**: Only appears when downward scrolling is possible
+ * - **Keyboard Accessible**: Can be activated with Enter/Space
+ * - **Focus Management**: Receives focus during keyboard navigation
+ * - **Screen Reader**: Announced as scroll control with directional context
+ * - **Mouse/Touch**: Responds to click/touch interactions for scrolling
+ *
+ * @see {@link SelectContent} - Container that manages scroll button visibility
+ * @see {@link SelectScrollUpButton} - Counterpart for upward scrolling
  * @since 1.0.0
  */
 declare function SelectScrollDownButton({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>): import("react/jsx-runtime").JSX.Element;

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

@@ -1 +1 @@
-{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../src/components/ui/select.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,eAAe,MAAM,wBAAwB,CAAC;AAK1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,iBAAS,MAAM,CAAC,EACd,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,IAAI,CAAC,2CAEnD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,WAAW,CAAC,EACnB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,KAAK,CAAC,2CAEpD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,iBAAS,WAAW,CAAC,EACnB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,KAAK,CAAC,2CAEpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,iBAAS,aAAa,CAAC,EACrB,SAAS,EACT,IAAgB,EAChB,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,OAAO,CAAC,GAAG;IACxD;;;OAGG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CACzB,2CAiBA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,iBAAS,aAAa,CAAC,EACrB,SAAS,EACT,QAAQ,EACR,QAAmB,EACnB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,OAAO,CAAC,2CA4BtD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,iBAAS,WAAW,CAAC,EACnB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,KAAK,CAAC,2CAQpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,iBAAS,UAAU,CAAC,EAClB,SAAS,EACT,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,IAAI,CAAC,2CAkBnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,iBAAS,eAAe,CAAC,EACvB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,SAAS,CAAC,2CAQxD;AAED;;;;;;;;;;;;GAYG;AACH,iBAAS,oBAAoB,CAAC,EAC5B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,cAAc,CAAC,2CAa7D;AAED;;;;;;;;;;;;GAYG;AACH,iBAAS,sBAAsB,CAAC,EAC9B,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,gBAAgB,CAAC,2CAa/D;AAED,OAAO,EACL,MAAM,EACN,aAAa,EACb,WAAW,EACX,UAAU,EACV,WAAW,EACX,sBAAsB,EACtB,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,WAAW,GACZ,CAAC"}
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../src/components/ui/select.tsx"],"names":[],"mappings":"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"}