@neynar/ui 0.4.0 → 0.5.0

package/src/components/ui/select.tsx

@@ -1,687 +1,137 @@
 "use client";
 
 import * as React from "react";
-import * as SelectPrimitive from "@radix-ui/react-select";
-import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react";
+import { Select as SelectPrimitive } from "@base-ui/react/select";
 
 import { cn } from "@/lib/utils";
+import { ChevronDownIcon, CheckIcon, ChevronUpIcon } from "lucide-react";
 
-/**
- * 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>>;
+type SelectProps<T = unknown> = SelectPrimitive.Root.Props<T>;
 
 /**
- * Props for SelectLabel component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace Radix inferred types
+ * Select root component. Manages select state and provides context to children.
+ * Use with SelectTrigger, SelectContent, SelectItem, and SelectValue.
  */
-// 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>>;
+const Select = SelectPrimitive.Root;
 
-/**
- * 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>>;
+type SelectGroupProps = SelectPrimitive.Group.Props;
 
 /**
- * Props for SelectScrollDownButton component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace Radix inferred types
+ * Groups related select items with a label.
  */
-// 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. Built on Radix UI Select.Root with enhanced styling.
- *
- * @component
- * @example
- * ```tsx
- * // Basic uncontrolled select
- * <Select defaultValue="apple">
- *   <SelectTrigger className="w-[180px]">
- *     <SelectValue placeholder="Select a fruit" />
- *   </SelectTrigger>
- *   <SelectContent>
- *     <SelectItem value="apple">Apple</SelectItem>
- *     <SelectItem value="banana">Banana</SelectItem>
- *     <SelectItem value="orange">Orange</SelectItem>
- *   </SelectContent>
- * </Select>
- * ```
- *
- * @example
- * ```tsx
- * // Controlled select with state management
- * const [value, setValue] = useState("");
- *
- * <Select value={value} onValueChange={setValue}>
- *   <SelectTrigger>
- *     <SelectValue placeholder="Choose an option" />
- *   </SelectTrigger>
- *   <SelectContent>
- *     <SelectItem value="option1">Option 1</SelectItem>
- *     <SelectItem value="option2">Option 2</SelectItem>
- *   </SelectContent>
- * </Select>
- * ```
- *
- * @example
- * ```tsx
- * // Grouped options with separators and labels
- * <Select>
- *   <SelectTrigger>
- *     <SelectValue placeholder="Select a timezone" />
- *   </SelectTrigger>
- *   <SelectContent>
- *     <SelectGroup>
- *       <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>
- *       <SelectLabel>Europe</SelectLabel>
- *       <SelectItem value="gmt">Greenwich Mean Time (GMT)</SelectItem>
- *       <SelectItem value="cet">Central European Time (CET)</SelectItem>
- *     </SelectGroup>
- *   </SelectContent>
- * </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
- * - **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
- */
-function Select({
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Root>) {
-  return <SelectPrimitive.Root data-slot="select" {...props} />;
+function SelectGroup({ className, ...props }: SelectGroupProps) {
+  return (
+    <SelectPrimitive.Group
+      data-slot="select-group"
+      className={cn("scroll-my-1 p-1", className)}
+      {...props}
+    />
+  );
 }
 
-/**
- * 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. 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>
- * ```
- *
- * @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({
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Group>) {
-  return <SelectPrimitive.Group data-slot="select-group" {...props} />;
-}
+type SelectValueProps = SelectPrimitive.Value.Props;
 
 /**
- * SelectValue - Displays the selected value or placeholder
- *
- * Renders the currently selected option's text or a placeholder when no option
- * 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>
- * ```
- *
- * @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
+ * Displays the selected item's value or placeholder text.
  */
-function SelectValue({
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Value>) {
-  return <SelectPrimitive.Value data-slot="select-value" {...props} />;
+function SelectValue({ className, ...props }: SelectValueProps) {
+  return (
+    <SelectPrimitive.Value
+      data-slot="select-value"
+      className={cn("flex flex-1 text-left", className)}
+      {...props}
+    />
+  );
 }
 
+type SelectTriggerProps = SelectPrimitive.Trigger.Props & {
+  /** Select trigger size. @default "default" */
+  size?: "sm" | "default";
+};
+
 /**
- * SelectTrigger - The button that opens the select dropdown
- *
- * A styled button that displays the current value and triggers the dropdown menu.
- * 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
- * ```tsx
- * // Basic trigger with custom width
- * <SelectTrigger className="w-[200px]">
- *   <SelectValue placeholder="Select an option" />
- * </SelectTrigger>
- * ```
- *
- * @example
- * ```tsx
- * // Small size variant for compact layouts
- * <SelectTrigger size="sm" className="w-[150px]">
- *   <SelectValue placeholder="Compact select" />
- * </SelectTrigger>
- * ```
- *
- * @example
- * ```tsx
- * // 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 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
+ * Button that opens the select dropdown. Automatically includes chevron icon.
  */
 function SelectTrigger({
   className,
   size = "default",
   children,
   ...props
-}: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
-  size?: "sm" | "default";
-}) {
+}: SelectTriggerProps) {
   return (
     <SelectPrimitive.Trigger
       data-slot="select-trigger"
       data-size={size}
       className={cn(
-        "border-input data-[placeholder]:text-muted-foreground [&_svg:not([class*='text-'])]:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 dark:hover:bg-input/50 flex w-fit items-center justify-between gap-2 rounded-md border bg-transparent px-3 py-2 text-sm whitespace-nowrap shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-9 data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "border-input data-[placeholder]:text-muted-foreground dark:bg-input/30 dark:hover:bg-input/50 focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:aria-invalid:border-destructive/50 gap-1.5 rounded-md border bg-transparent py-2 pr-2 pl-2.5 text-sm shadow-xs transition-[color,box-shadow] focus-visible:ring-[3px] aria-invalid:ring-[3px] data-[size=default]:h-9 data-[size=sm]:h-8 *:data-[slot=select-value]:flex *:data-[slot=select-value]:gap-1.5 [&_svg:not([class*='size-'])]:size-4 flex w-fit items-center justify-between whitespace-nowrap outline-none disabled:cursor-not-allowed disabled:opacity-50 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       {...props}
     >
       {children}
-      <SelectPrimitive.Icon asChild>
-        <ChevronDownIcon className="size-4 opacity-50" />
-      </SelectPrimitive.Icon>
+      <SelectPrimitive.Icon
+        render={
+          <ChevronDownIcon className="text-muted-foreground size-4 pointer-events-none" />
+        }
+      />
     </SelectPrimitive.Trigger>
   );
 }
 
+type SelectContentProps = SelectPrimitive.Popup.Props &
+  Pick<
+    SelectPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset" | "alignItemWithTrigger"
+  >;
+
 /**
- * SelectContent - Container for the dropdown content
- *
- * The dropdown panel that contains all selectable items, groups, and labels.
- * 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>
- *   <SelectItem value="3">Option 3</SelectItem>
- * </SelectContent>
- * ```
- *
- * @example
- * ```tsx
- * // 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 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 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
+ * Select dropdown content. Automatically renders in a portal with positioning and scroll buttons.
  */
 function SelectContent({
   className,
   children,
-  position = "popper",
+  side = "bottom",
+  sideOffset = 4,
+  align = "center",
+  alignOffset = 0,
+  alignItemWithTrigger = true,
   ...props
-}: React.ComponentProps<typeof SelectPrimitive.Content>) {
+}: SelectContentProps) {
   return (
     <SelectPrimitive.Portal>
-      <SelectPrimitive.Content
-        data-slot="select-content"
-        className={cn(
-          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 relative z-50 max-h-(--radix-select-content-available-height) min-w-[8rem] origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border shadow-md",
-          position === "popper" &&
-            "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
-          className,
-        )}
-        position={position}
-        {...props}
+      <SelectPrimitive.Positioner
+        side={side}
+        sideOffset={sideOffset}
+        align={align}
+        alignOffset={alignOffset}
+        alignItemWithTrigger={alignItemWithTrigger}
+        className="isolate z-50"
       >
-        <SelectScrollUpButton />
-        <SelectPrimitive.Viewport
+        <SelectPrimitive.Popup
+          data-slot="select-content"
           className={cn(
-            "p-1",
-            position === "popper" &&
-              "h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)] scroll-my-1",
+            "bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 ring-foreground/10 min-w-36 rounded-md shadow-md ring-1 duration-100 relative isolate z-50 max-h-(--available-height) w-(--anchor-width) origin-(--transform-origin) overflow-x-hidden overflow-y-auto",
+            className,
           )}
+          {...props}
         >
-          {children}
-        </SelectPrimitive.Viewport>
-        <SelectScrollDownButton />
-      </SelectPrimitive.Content>
+          <SelectScrollUpButton />
+          <SelectPrimitive.List>{children}</SelectPrimitive.List>
+          <SelectScrollDownButton />
+        </SelectPrimitive.Popup>
+      </SelectPrimitive.Positioner>
     </SelectPrimitive.Portal>
   );
 }
 
+type SelectLabelProps = SelectPrimitive.GroupLabel.Props;
+
 /**
- * SelectLabel - Label for a group of select items
- *
- * Provides a non-selectable label for categorizing groups of options.
- * 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
- * - **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} - Required parent container
- * @see {@link SelectItem} - Items that this label describes
- * @since 1.0.0
+ * Label for a group of select items.
  */
-function SelectLabel({
-  className,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Label>) {
+function SelectLabel({ className, ...props }: SelectLabelProps) {
   return (
-    <SelectPrimitive.Label
+    <SelectPrimitive.GroupLabel
       data-slot="select-label"
       className={cn("text-muted-foreground px-2 py-1.5 text-xs", className)}
       {...props}
@@ -689,270 +139,97 @@ function SelectLabel({
   );
 }
 
+type SelectItemProps = SelectPrimitive.Item.Props;
+
 /**
- * SelectItem - Individual selectable option in the dropdown
- *
- * 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 that cannot be selected
- * <SelectItem value="sold-out" disabled>
- *   Sold Out - Unavailable
- * </SelectItem>
- * ```
- *
- * @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>
- * ```
- *
- * @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
+ * Individual selectable item. Automatically shows check icon when selected.
  */
-function SelectItem({
-  className,
-  children,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Item>) {
+function SelectItem({ className, children, ...props }: SelectItemProps) {
   return (
     <SelectPrimitive.Item
       data-slot="select-item"
       className={cn(
-        "focus:bg-accent focus:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex w-full cursor-default items-center gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+        "focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2 relative flex w-full cursor-default items-center outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       {...props}
     >
-      <span className="absolute right-2 flex size-3.5 items-center justify-center">
-        <SelectPrimitive.ItemIndicator>
-          <CheckIcon className="size-4" />
-        </SelectPrimitive.ItemIndicator>
-      </span>
-      <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+      <SelectPrimitive.ItemText className="flex flex-1 gap-2 shrink-0 whitespace-nowrap">
+        {children}
+      </SelectPrimitive.ItemText>
+      <SelectPrimitive.ItemIndicator
+        render={
+          <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center" />
+        }
+      >
+        <CheckIcon className="pointer-events-none" />
+      </SelectPrimitive.ItemIndicator>
     </SelectPrimitive.Item>
   );
 }
 
+type SelectSeparatorProps = SelectPrimitive.Separator.Props;
+
 /**
- * SelectSeparator - Visual divider between select groups
- *
- * 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 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
+ * Visual separator between select groups.
  */
-function SelectSeparator({
-  className,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Separator>) {
+function SelectSeparator({ className, ...props }: SelectSeparatorProps) {
   return (
     <SelectPrimitive.Separator
       data-slot="select-separator"
-      className={cn("bg-border pointer-events-none -mx-1 my-1 h-px", className)}
+      className={cn("bg-border -mx-1 my-1 h-px pointer-events-none", className)}
       {...props}
     />
   );
 }
 
+type SelectScrollUpButtonProps = React.ComponentProps<
+  typeof SelectPrimitive.ScrollUpArrow
+>;
+
 /**
- * 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. Built on Radix UI Select.ScrollUpButton with chevron
- * icon and hover states. Automatically shows/hides based on scroll position.
- *
- * @component
- * @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
+ * Scroll indicator button at the top of scrollable content.
  */
 function SelectScrollUpButton({
   className,
   ...props
-}: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>) {
+}: SelectScrollUpButtonProps) {
   return (
-    <SelectPrimitive.ScrollUpButton
+    <SelectPrimitive.ScrollUpArrow
       data-slot="select-scroll-up-button"
       className={cn(
-        "flex cursor-default items-center justify-center py-1",
+        "bg-popover z-10 flex cursor-default items-center justify-center py-1 [&_svg:not([class*='size-'])]:size-4 top-0 w-full",
         className,
       )}
       {...props}
     >
-      <ChevronUpIcon className="size-4" />
-    </SelectPrimitive.ScrollUpButton>
+      <ChevronUpIcon />
+    </SelectPrimitive.ScrollUpArrow>
   );
 }
 
+type SelectScrollDownButtonProps = React.ComponentProps<
+  typeof SelectPrimitive.ScrollDownArrow
+>;
+
 /**
- * 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. Built on Radix UI Select.ScrollDownButton with chevron
- * icon and hover states. Automatically shows/hides based on scroll position.
- *
- * @component
- * @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
+ * Scroll indicator button at the bottom of scrollable content.
  */
 function SelectScrollDownButton({
   className,
   ...props
-}: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>) {
+}: SelectScrollDownButtonProps) {
   return (
-    <SelectPrimitive.ScrollDownButton
+    <SelectPrimitive.ScrollDownArrow
       data-slot="select-scroll-down-button"
       className={cn(
-        "flex cursor-default items-center justify-center py-1",
+        "bg-popover z-10 flex cursor-default items-center justify-center py-1 [&_svg:not([class*='size-'])]:size-4 bottom-0 w-full",
         className,
       )}
       {...props}
     >
-      <ChevronDownIcon className="size-4" />
-    </SelectPrimitive.ScrollDownButton>
+      <ChevronDownIcon />
+    </SelectPrimitive.ScrollDownArrow>
   );
 }
 
@@ -967,4 +244,14 @@ export {
   SelectSeparator,
   SelectTrigger,
   SelectValue,
+  type SelectProps,
+  type SelectContentProps,
+  type SelectGroupProps,
+  type SelectItemProps,
+  type SelectLabelProps,
+  type SelectScrollDownButtonProps,
+  type SelectScrollUpButtonProps,
+  type SelectSeparatorProps,
+  type SelectTriggerProps,
+  type SelectValueProps,
 };