@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/select.tsx

@@ -6,13 +6,176 @@ import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react";
 
 import { cn } from "@/lib/utils";
 
+/**
+ * Props for Select component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SelectDocsProps = {
+  /** The value of the select when initially rendered. Use when you do not need to control the state of the select */
+  defaultValue?: string;
+  /** The controlled value of the select. Must be used in conjunction with onValueChange */
+  value?: string;
+  /** Event handler called when the value changes */
+  onValueChange?: (value: string) => void;
+  /** The open state of the select when it is initially rendered. Use when you do not need to control its open state */
+  defaultOpen?: boolean;
+  /** The controlled open state of the select. Must be used in conjunction with onOpenChange */
+  open?: boolean;
+  /** Event handler called when the open state of the select changes */
+  onOpenChange?: (open: boolean) => void;
+  /** The reading direction of the select when applicable. If omitted, inherits globally from DirectionProvider or assumes LTR (left-to-right) reading mode @default "ltr" */
+  dir?: "ltr" | "rtl";
+  /** The name of the select. Submitted with its owning form as part of a name/value pair */
+  name?: string;
+  /** When true, prevents the user from interacting with the select @default false */
+  disabled?: boolean;
+  /** When true, indicates that the user must select a value before the owning form can be submitted @default false */
+  required?: boolean;
+} & React.ComponentProps<typeof SelectPrimitive.Root>;
+
+/**
+ * Props for SelectGroup component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SelectGroupDocsProps = {
+  /** When true, renders a custom component instead of the default element @default false */
+  asChild?: boolean;
+} & React.HTMLAttributes<HTMLDivElement> &
+  React.RefAttributes<React.ElementRef<typeof SelectPrimitive.Group>>;
+
+/**
+ * Props for SelectValue component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SelectValueDocsProps = {
+  /** When true, renders a custom component instead of the default element @default false */
+  asChild?: boolean;
+  /** The content that will be rendered inside the SelectValue when no value or defaultValue is set. Must be a string when used with form submission */
+  placeholder?: React.ReactNode;
+} & React.HTMLAttributes<HTMLSpanElement> &
+  React.RefAttributes<React.ElementRef<typeof SelectPrimitive.Value>>;
+
+/**
+ * Props for SelectTrigger component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SelectTriggerDocsProps = {
+  /** When true, renders a custom component instead of the default element @default false */
+  asChild?: boolean;
+  /** The size variant of the trigger button affecting height and padding @default "default" */
+  size?: "sm" | "default";
+} & React.HTMLAttributes<HTMLButtonElement> &
+  React.RefAttributes<React.ElementRef<typeof SelectPrimitive.Trigger>>;
+
+/**
+ * Props for SelectContent component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SelectContentDocsProps = {
+  /** When true, renders a custom component instead of the default element @default false */
+  asChild?: boolean;
+  /** The positioning strategy to use for the content. "item-aligned" will position based on the active item. "popper" will position according to the side and align props @default "item-aligned" */
+  position?: "item-aligned" | "popper";
+  /** The preferred side of the anchor to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled @default "bottom" */
+  side?: "top" | "right" | "bottom" | "left";
+  /** The distance in pixels from the anchor @default 0 */
+  sideOffset?: number;
+  /** The preferred alignment against the anchor. May change when collisions occur @default "center" */
+  align?: "start" | "center" | "end";
+  /** An offset in pixels from the "start" or "end" alignment options @default 0 */
+  alignOffset?: number;
+  /** When true, overrides the side and align preferences to prevent collisions with boundary edges @default true */
+  avoidCollisions?: boolean;
+  /** The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check @default [] */
+  collisionBoundary?: Element | null | Array<Element | null>;
+  /** The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object @default 0 */
+  collisionPadding?:
+    | number
+    | Partial<Record<"top" | "right" | "bottom" | "left", number>>;
+  /** The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners @default 0 */
+  arrowPadding?: number;
+  /** The sticky behavior on the align axis. "partial" will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless @default "partial" */
+  sticky?: "partial" | "always";
+  /** Whether to hide the content when the trigger becomes fully occluded @default false */
+  hideWhenDetached?: boolean;
+} & React.HTMLAttributes<HTMLDivElement> &
+  React.RefAttributes<React.ElementRef<typeof SelectPrimitive.Content>>;
+
+/**
+ * Props for SelectLabel component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SelectLabelDocsProps = {
+  /** When true, renders a custom component instead of the default element @default false */
+  asChild?: boolean;
+} & React.HTMLAttributes<HTMLDivElement> &
+  React.RefAttributes<React.ElementRef<typeof SelectPrimitive.Label>>;
+
+/**
+ * Props for SelectItem component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SelectItemDocsProps = {
+  /** When true, renders a custom component instead of the default element @default false */
+  asChild?: boolean;
+  /** The value given as data when submitted with a name (required) */
+  value: string;
+  /** When true, prevents the user from interacting with the item @default false */
+  disabled?: boolean;
+  /** Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the SelectItem. Use this when the content is complex, or you have non-textual content inside */
+  textValue?: string;
+} & React.HTMLAttributes<HTMLDivElement> &
+  React.RefAttributes<React.ElementRef<typeof SelectPrimitive.Item>>;
+
+/**
+ * Props for SelectSeparator component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SelectSeparatorDocsProps = {
+  /** When true, renders a custom component instead of the default element @default false */
+  asChild?: boolean;
+} & React.HTMLAttributes<HTMLDivElement> &
+  React.RefAttributes<React.ElementRef<typeof SelectPrimitive.Separator>>;
+
+/**
+ * Props for SelectScrollUpButton component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SelectScrollUpButtonDocsProps = {
+  /** When true, renders a custom component instead of the default element @default false */
+  asChild?: boolean;
+} & React.HTMLAttributes<HTMLDivElement> &
+  React.RefAttributes<React.ElementRef<typeof SelectPrimitive.ScrollUpButton>>;
+
+/**
+ * Props for SelectScrollDownButton component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SelectScrollDownButtonDocsProps = {
+  /** When true, renders a custom component instead of the default element @default false */
+  asChild?: boolean;
+} & React.HTMLAttributes<HTMLDivElement> &
+  React.RefAttributes<
+    React.ElementRef<typeof SelectPrimitive.ScrollDownButton>
+  >;
+
 /**
  * Select - A dropdown selection component built on Radix UI primitives
  *
  * 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
@@ -48,7 +211,7 @@ import { cn } from "@/lib/utils";
  *
  * @example
  * ```tsx
- * // Grouped options with separators
+ * // Grouped options with separators and labels
  * <Select>
  *   <SelectTrigger>
  *     <SelectValue placeholder="Select a timezone" />
@@ -58,6 +221,7 @@ import { cn } from "@/lib/utils";
  *       <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>
@@ -69,19 +233,55 @@ import { cn } from "@/lib/utils";
  * </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
  */
@@ -95,20 +295,57 @@ function Select({
  * 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
  */
 function SelectGroup({
@@ -121,17 +358,56 @@ function SelectGroup({
  * 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
  */
 function SelectValue({
@@ -144,8 +420,13 @@ function SelectValue({
  * 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
@@ -160,27 +441,42 @@ function SelectValue({
  * ```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
  */
 function SelectTrigger({
@@ -189,10 +485,6 @@ function SelectTrigger({
   children,
   ...props
 }: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
-  /**
-   * The size variant of the trigger button
-   * @default "default"
-   */
   size?: "sm" | "default";
 }) {
   return (
@@ -217,11 +509,18 @@ function SelectTrigger({
  * 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>
@@ -231,19 +530,56 @@ function SelectTrigger({
  *
  * @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
  */
 function SelectContent({
@@ -285,23 +621,59 @@ function SelectContent({
  * 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
  */
 function SelectLabel({
@@ -320,30 +692,60 @@ function SelectLabel({
 /**
  * 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
  */
 function SelectItem({
@@ -373,27 +775,54 @@ function SelectItem({
 /**
  * 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
  */
 function SelectSeparator({
@@ -413,13 +842,41 @@ function SelectSeparator({
  * 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
  */
 function SelectScrollUpButton({
@@ -444,13 +901,41 @@ function SelectScrollUpButton({
  * 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
  */
 function SelectScrollDownButton({