@neynar/ui 0.1.1

package/src/components/ui/select.tsx

@@ -0,0 +1,485 @@
+"use client";
+
+import * as React from "react";
+import * as SelectPrimitive from "@radix-ui/react-select";
+import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * 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.
+ *
+ * @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
+ * <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>
+ *     </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>
+ * ```
+ *
+ * @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
+ *
+ * @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 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} />;
+}
+
+/**
+ * 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.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <SelectGroup>
+ *   <SelectLabel>Fruits</SelectLabel>
+ *   <SelectItem value="apple">Apple</SelectItem>
+ *   <SelectItem value="banana">Banana</SelectItem>
+ * </SelectGroup>
+ * ```
+ *
+ * @see {@link SelectLabel} - Label for the group
+ * @see {@link SelectItem} - Items within the group
+ * @since 1.0.0
+ */
+function SelectGroup({
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Group>) {
+  return <SelectPrimitive.Group data-slot="select-group" {...props} />;
+}
+
+/**
+ * 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.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <SelectTrigger>
+ *   <SelectValue placeholder="Choose an option" />
+ * </SelectTrigger>
+ * ```
+ *
+ * @see {@link SelectTrigger} - Parent container for the value
+ * @since 1.0.0
+ */
+function SelectValue({
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Value>) {
+  return <SelectPrimitive.Value data-slot="select-value" {...props} />;
+}
+
+/**
+ * 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.
+ *
+ * @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" />
+ * </SelectTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With form integration
+ * <SelectTrigger id="user-role" aria-describedby="role-help">
+ *   <SelectValue placeholder="Choose role" />
+ * </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
+ *
+ * @see {@link SelectValue} - Displays the selected value or placeholder
+ * @since 1.0.0
+ */
+function SelectTrigger({
+  className,
+  size = "default",
+  children,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
+  /**
+   * The size variant of the trigger button
+   * @default "default"
+   */
+  size?: "sm" | "default";
+}) {
+  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",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      <SelectPrimitive.Icon asChild>
+        <ChevronDownIcon className="size-4 opacity-50" />
+      </SelectPrimitive.Icon>
+    </SelectPrimitive.Trigger>
+  );
+}
+
+/**
+ * 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.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <SelectContent>
+ *   <SelectItem value="1">Option 1</SelectItem>
+ *   <SelectItem value="2">Option 2</SelectItem>
+ *   <SelectItem value="3">Option 3</SelectItem>
+ * </SelectContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With fixed positioning
+ * <SelectContent position="item-aligned">
+ *   <SelectItem value="1">Option 1</SelectItem>
+ * </SelectContent>
+ * ```
+ *
+ * @accessibility
+ * - Focus trapped within dropdown when open
+ * - Scrollable with keyboard navigation
+ * - Escape key closes the dropdown
+ *
+ * @see {@link SelectItem} - Individual options
+ * @see {@link SelectGroup} - Group container
+ * @since 1.0.0
+ */
+function SelectContent({
+  className,
+  children,
+  position = "popper",
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Content>) {
+  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}
+      >
+        <SelectScrollUpButton />
+        <SelectPrimitive.Viewport
+          className={cn(
+            "p-1",
+            position === "popper" &&
+              "h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)] scroll-my-1",
+          )}
+        >
+          {children}
+        </SelectPrimitive.Viewport>
+        <SelectScrollDownButton />
+      </SelectPrimitive.Content>
+    </SelectPrimitive.Portal>
+  );
+}
+
+/**
+ * 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.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <SelectGroup>
+ *   <SelectLabel>Countries</SelectLabel>
+ *   <SelectItem value="us">United States</SelectItem>
+ *   <SelectItem value="uk">United Kingdom</SelectItem>
+ * </SelectGroup>
+ * ```
+ *
+ * @accessibility
+ * - Properly associated with group for screen readers
+ * - Non-selectable and non-focusable
+ *
+ * @see {@link SelectGroup} - Parent container
+ * @since 1.0.0
+ */
+function SelectLabel({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Label>) {
+  return (
+    <SelectPrimitive.Label
+      data-slot="select-label"
+      className={cn("text-muted-foreground px-2 py-1.5 text-xs", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * SelectItem - Individual selectable option in the dropdown
+ *
+ * Represents a single option that users can select. Shows a checkmark
+ * when selected and supports keyboard navigation.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <SelectItem value="apple">Apple</SelectItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled item
+ * <SelectItem value="sold-out" disabled>
+ *   Sold Out
+ * </SelectItem>
+ * ```
+ *
+ * @accessibility
+ * - Arrow keys navigate between items
+ * - Enter or Space selects the item
+ * - Shows checkmark icon when selected
+ * - Supports disabled state
+ *
+ * @see {@link SelectContent} - Parent container
+ * @since 1.0.0
+ */
+function SelectItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Item>) {
+  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",
+        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.Item>
+  );
+}
+
+/**
+ * SelectSeparator - Visual divider between select groups
+ *
+ * A horizontal line that visually separates groups of options
+ * for better organization and clarity.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <SelectContent>
+ *   <SelectGroup>
+ *     <SelectItem value="1">Option 1</SelectItem>
+ *   </SelectGroup>
+ *   <SelectSeparator />
+ *   <SelectGroup>
+ *     <SelectItem value="2">Option 2</SelectItem>
+ *   </SelectGroup>
+ * </SelectContent>
+ * ```
+ *
+ * @accessibility
+ * - Decorative element with no semantic meaning
+ * - Not focusable or interactive
+ *
+ * @since 1.0.0
+ */
+function SelectSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Separator>) {
+  return (
+    <SelectPrimitive.Separator
+      data-slot="select-separator"
+      className={cn("bg-border pointer-events-none -mx-1 my-1 h-px", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 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.
+ *
+ * @component
+ * @accessibility
+ * - Keyboard accessible
+ * - Only visible when scrolling is available
+ *
+ * @since 1.0.0
+ */
+function SelectScrollUpButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>) {
+  return (
+    <SelectPrimitive.ScrollUpButton
+      data-slot="select-scroll-up-button"
+      className={cn(
+        "flex cursor-default items-center justify-center py-1",
+        className,
+      )}
+      {...props}
+    >
+      <ChevronUpIcon className="size-4" />
+    </SelectPrimitive.ScrollUpButton>
+  );
+}
+
+/**
+ * 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.
+ *
+ * @component
+ * @accessibility
+ * - Keyboard accessible
+ * - Only visible when scrolling is available
+ *
+ * @since 1.0.0
+ */
+function SelectScrollDownButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>) {
+  return (
+    <SelectPrimitive.ScrollDownButton
+      data-slot="select-scroll-down-button"
+      className={cn(
+        "flex cursor-default items-center justify-center py-1",
+        className,
+      )}
+      {...props}
+    >
+      <ChevronDownIcon className="size-4" />
+    </SelectPrimitive.ScrollDownButton>
+  );
+}
+
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+};

package/src/components/ui/separator.tsx

@@ -0,0 +1,101 @@
+import * as React from "react";
+import * as SeparatorPrimitive from "@radix-ui/react-separator";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Separator component for visually dividing content sections
+ *
+ * A flexible separator component built on Radix UI primitives that creates
+ * visual or semantic divisions between content sections. Supports both horizontal
+ * and vertical orientations with full accessibility features including decorative
+ * and semantic separator modes for screen reader compatibility.
+ *
+ * @example
+ * ```tsx
+ * // Basic horizontal separator
+ * <div>
+ *   <p>Above content</p>
+ *   <Separator />
+ *   <p>Below content</p>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Vertical separator in toolbars
+ * <div className="flex items-center">
+ *   <button>Bold</button>
+ *   <Separator orientation="vertical" className="mx-2 h-6" />
+ *   <button>Italic</button>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Semantic separator for navigation
+ * <nav className="flex items-center">
+ *   <a href="/home">Home</a>
+ *   <Separator
+ *     orientation="vertical"
+ *     decorative={false}
+ *     aria-label="Navigation separator"
+ *     className="mx-2 h-4"
+ *   />
+ *   <a href="/about">About</a>
+ * </nav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styled separator
+ * <Separator className="my-6 h-0.5 bg-gradient-to-r from-transparent via-border to-transparent" />
+ * ```
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/separator} for design patterns
+ * @since 1.0.0
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/separator} for API reference
+ */
+/**
+ * Props for the Separator component
+ */
+type SeparatorProps = React.ComponentProps<typeof SeparatorPrimitive.Root> & {
+  /** Additional CSS class names to apply to the separator */
+  className?: string;
+  /** The orientation of the separator. @default "horizontal" */
+  orientation?: "horizontal" | "vertical";
+  /** Whether the separator is purely decorative (hidden from screen readers). @default true */
+  decorative?: boolean;
+};
+
+/**
+ * Separator component implementation
+ *
+ * @param className - Additional CSS class names to apply
+ * @param orientation - The orientation of the separator ("horizontal" | "vertical")
+ * @param decorative - Whether the separator is decorative (hidden from screen readers)
+ * @param props - Additional props passed to the underlying Radix Separator primitive
+ */
+function Separator({
+  className,
+  orientation = "horizontal",
+  decorative = true,
+  ...props
+}: SeparatorProps) {
+  return (
+    <SeparatorPrimitive.Root
+      data-slot="separator"
+      decorative={decorative}
+      orientation={orientation}
+      className={cn(
+        "bg-border shrink-0 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+Separator.displayName = "Separator";
+
+export { Separator, type SeparatorProps };