@neynar/ui 0.4.0 → 0.5.0

package/src/components/ui/radio-group.tsx

@@ -1,392 +1,54 @@
-"use client";
-
-import * as React from "react";
-import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
-import { CircleIcon } from "lucide-react";
+import { Radio as RadioPrimitive } from "@base-ui/react/radio";
+import { RadioGroup as RadioGroupPrimitive } from "@base-ui/react/radio-group";
 
 import { cn } from "@/lib/utils";
+import { CircleIcon } from "lucide-react";
 
-/**
- * Props for RadioGroup 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 RadioGroupDocsProps = {
-  /** The value of the radio item that should be checked when initially rendered. Use when you do not need to control the checked state */
-  defaultValue?: string;
-  /** The controlled value of the radio item to check. Should be used in conjunction with onValueChange */
-  value?: string;
-  /** Event handler called when the value changes */
-  onValueChange?: (value: string) => void;
-  /** When true, prevents the user from interacting with the radio group */
-  disabled?: boolean;
-  /** The name of the group. Submitted with its owning form as part of a name/value pair */
-  name?: string;
-  /** When true, indicates that the user must check a radio item before the owning form can be submitted */
-  required?: boolean;
-  /** The orientation of the component, which determines how focus moves: horizontal for left/right arrows, vertical for up/down arrows @default "vertical" */
-  orientation?: "horizontal" | "vertical";
-  /** The reading direction of the radio group. If omitted, assumes LTR (left-to-right) reading mode */
-  dir?: "ltr" | "rtl";
-  /** When true, keyboard navigation will loop from last item to first, and vice versa @default true */
-  loop?: boolean;
-  /** Change the default rendered element for the one passed as a child, merging their props and behavior @default false */
-  asChild?: boolean;
-} & Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue" | "onChange">;
-
-/**
- * Props for RadioGroupItem 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 RadioGroupItemDocsProps = {
-  /** The value given as data when submitted with a name */
-  value: string;
-  /** When true, prevents the user from interacting with the item */
-  disabled?: boolean;
-  /** When true, indicates that the user must check the item before the owning form can be submitted */
-  required?: boolean;
-  /** Change the default rendered element for the one passed as a child, merging their props and behavior @default false */
-  asChild?: boolean;
-} & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "value">;
-
-/**
- * Props for RadioGroupIndicator 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 RadioGroupIndicatorDocsProps = {
-  /** Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries */
-  forceMount?: boolean;
-  /** Change the default rendered element for the one passed as a child, merging their props and behavior @default false */
-  asChild?: boolean;
-} & React.HTMLAttributes<HTMLSpanElement>;
+type RadioGroupProps = RadioGroupPrimitive.Props;
 
 /**
- * A radio group component for single selection from multiple options
- *
- * RadioGroup allows users to select exactly one option from a set of mutually exclusive choices.
- * Built on Radix UI RadioGroup primitives with enhanced accessibility and keyboard navigation.
- * Each radio group should contain RadioGroupItem components paired with Labels for proper accessibility.
- *
- * The component follows the WAI-ARIA Radio Group design pattern and uses roving tabindex to manage
- * focus movement among radio items. It provides comprehensive keyboard navigation with arrow keys
- * and supports both controlled and uncontrolled usage patterns.
- *
- * @example Basic uncontrolled usage
- * ```tsx
- * <RadioGroup defaultValue="option-one">
- *   <div className="flex items-center space-x-2">
- *     <RadioGroupItem value="option-one" id="option-one" />
- *     <Label htmlFor="option-one">Option One</Label>
- *   </div>
- *   <div className="flex items-center space-x-2">
- *     <RadioGroupItem value="option-two" id="option-two" />
- *     <Label htmlFor="option-two">Option Two</Label>
- *   </div>
- * </RadioGroup>
- * ```
- *
- * @example Controlled radio group
- * ```tsx
- * function SizeSelector() {
- *   const [size, setSize] = useState("medium");
- *
- *   return (
- *     <RadioGroup value={size} onValueChange={setSize}>
- *       <div className="flex items-center space-x-2">
- *         <RadioGroupItem value="small" id="size-small" />
- *         <Label htmlFor="size-small">Small</Label>
- *       </div>
- *       <div className="flex items-center space-x-2">
- *         <RadioGroupItem value="medium" id="size-medium" />
- *         <Label htmlFor="size-medium">Medium</Label>
- *       </div>
- *       <div className="flex items-center space-x-2">
- *         <RadioGroupItem value="large" id="size-large" />
- *         <Label htmlFor="size-large">Large</Label>
- *       </div>
- *     </RadioGroup>
- *   );
- * }
- * ```
- *
- * @example Horizontal orientation
- * ```tsx
- * <RadioGroup
- *   defaultValue="option-one"
- *   orientation="horizontal"
- *   className="flex gap-4"
- * >
- *   <div className="flex items-center space-x-2">
- *     <RadioGroupItem value="option-one" id="r1" />
- *     <Label htmlFor="r1">Option One</Label>
- *   </div>
- *   <div className="flex items-center space-x-2">
- *     <RadioGroupItem value="option-two" id="r2" />
- *     <Label htmlFor="r2">Option Two</Label>
- *   </div>
- * </RadioGroup>
- * ```
- *
- * @example With rich content and descriptions
- * ```tsx
- * <RadioGroup defaultValue="card" name="payment-method">
- *   <div className="flex items-start space-x-2">
- *     <RadioGroupItem value="card" id="card" className="mt-1" />
- *     <div className="grid gap-1">
- *       <Label htmlFor="card">Credit Card</Label>
- *       <p className="text-sm text-muted-foreground">
- *         Pay with your credit or debit card via secure payment
- *       </p>
- *     </div>
- *   </div>
- *   <div className="flex items-start space-x-2">
- *     <RadioGroupItem value="paypal" id="paypal" className="mt-1" />
- *     <div className="grid gap-1">
- *       <Label htmlFor="paypal">PayPal</Label>
- *       <p className="text-sm text-muted-foreground">
- *         Pay with your PayPal account balance or linked bank account
- *       </p>
- *     </div>
- *   </div>
- * </RadioGroup>
- * ```
- *
- * @example Disabled state and form usage
- * ```tsx
- * <form>
- *   <RadioGroup
- *     name="subscription"
- *     required
- *     defaultValue="basic"
- *   >
- *     <div className="flex items-center space-x-2">
- *       <RadioGroupItem value="basic" id="basic" />
- *       <Label htmlFor="basic">Basic Plan</Label>
- *     </div>
- *     <div className="flex items-center space-x-2">
- *       <RadioGroupItem value="premium" id="premium" disabled />
- *       <Label htmlFor="premium" className="opacity-50">
- *         Premium Plan (Coming Soon)
- *       </Label>
- *     </div>
- *   </RadioGroup>
- * </form>
- * ```
- *
- * @param defaultValue The value of the radio item that should be checked when initially rendered. Use when you do not need to control the checked state
- * @param value The controlled value of the radio item to check. Should be used in conjunction with onValueChange
- * @param onValueChange Event handler called when the value changes
- * @param disabled When true, prevents the user from interacting with the radio group
- * @param name The name of the group. Submitted with its owning form as part of a name/value pair
- * @param required When true, indicates that the user must check a radio item before the owning form can be submitted
- * @param orientation The orientation of the component, which determines how focus moves @default "vertical"
- * @param dir The reading direction of the radio group. If omitted, assumes LTR reading mode
- * @param loop When true, keyboard navigation will loop from last item to first, and vice versa @default true
- * @param asChild Change the default rendered element for the one passed as a child @default false
- * @param className Additional CSS classes to apply to the radio group
- * @param children RadioGroupItem components and their associated labels
- *
- * @accessibility
- * - Supports keyboard navigation with Tab to enter/exit and Arrow keys to navigate between items
- * - Space key selects the focused radio item
- * - Uses roving tabindex to manage focus within the group
- * - Provides proper ARIA roles and states for screen readers
- * - Announces selected/unselected states to assistive technologies
- * - Supports Right-to-Left (RTL) text direction
- * - Works with form validation and submission
- *
- * @see {@link RadioGroupItem} for individual radio button items
- * @see {@link RadioGroupIndicator} for the visual checked indicator
- * @see {@link https://ui.shadcn.com/docs/components/radio-group} shadcn/ui Radio Group documentation
- * @see {@link https://www.radix-ui.com/primitives/docs/components/radio-group} Radix UI Radio Group primitives
- * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/radiobutton/} WAI-ARIA Radio Group Pattern
- * @since 1.0.0
+ * Container for radio button items. Manages shared state and ensures only one option can be selected.
+ * Supports controlled and uncontrolled usage.
  */
-function RadioGroup({
-  className,
-  ...props
-}: React.ComponentProps<typeof RadioGroupPrimitive.Root>) {
+function RadioGroup({ className, ...props }: RadioGroupProps) {
   return (
-    <RadioGroupPrimitive.Root
+    <RadioGroupPrimitive
       data-slot="radio-group"
-      className={cn("grid gap-3", className)}
+      className={cn("grid gap-3 w-full", className)}
       {...props}
     />
   );
 }
 
+type RadioGroupItemProps = RadioPrimitive.Root.Props;
+
 /**
- * Individual radio button item for use within RadioGroup
- *
- * RadioGroupItem represents a single selectable option in a radio group.
- * Must be used within a RadioGroup component and should be paired with a Label for proper accessibility.
- * The component automatically handles visual states including checked, unchecked, focused, and disabled.
- * It includes a built-in indicator that displays when the item is selected.
- *
- * Each radio item requires a unique value prop that identifies it within the group.
- * The component forwards all standard button attributes and supports custom styling via className.
- *
- * @example Basic usage with label
- * ```tsx
- * <div className="flex items-center space-x-2">
- *   <RadioGroupItem value="option-one" id="option-one" />
- *   <Label htmlFor="option-one">Option One</Label>
- * </div>
- * ```
- *
- * @example Custom styling and theming
- * ```tsx
- * <RadioGroupItem
- *   value="premium"
- *   id="premium"
- *   className="border-purple-500 text-purple-500 data-[state=checked]:bg-purple-50"
- * />
- * <Label htmlFor="premium" className="text-purple-900">
- *   Premium Plan
- * </Label>
- * ```
- *
- * @example Disabled state
- * ```tsx
- * <div className="flex items-center space-x-2">
- *   <RadioGroupItem value="unavailable" id="unavailable" disabled />
- *   <Label htmlFor="unavailable" className="opacity-50 cursor-not-allowed">
- *     Unavailable Option
- *   </Label>
- * </div>
- * ```
- *
- * @example With complex content layout
- * ```tsx
- * <div className="flex items-start space-x-3 p-3 border rounded-lg">
- *   <RadioGroupItem value="plan-pro" id="plan-pro" className="mt-1" />
- *   <div className="grid gap-1">
- *     <Label htmlFor="plan-pro" className="font-semibold">
- *       Professional Plan
- *     </Label>
- *     <p className="text-sm text-muted-foreground">
- *       Advanced features for growing teams
- *     </p>
- *     <p className="text-lg font-bold">$29/month</p>
- *   </div>
- * </div>
- * ```
- *
- * @example Form integration with validation
- * ```tsx
- * <RadioGroupItem
- *   value="terms-accept"
- *   id="terms"
- *   required
- *   aria-describedby="terms-error"
- * />
- * <Label htmlFor="terms">
- *   I accept the terms and conditions
- * </Label>
- * ```
- *
- * @param value The value given as data when submitted with a name (required)
- * @param disabled When true, prevents the user from interacting with the item
- * @param required When true, indicates that the user must check the item before the owning form can be submitted
- * @param asChild Change the default rendered element for the one passed as a child @default false
- * @param id The id attribute for accessibility (should match Label's htmlFor)
- * @param className Additional CSS classes for custom styling
- * @param children Content to render inside the radio item (typically empty as styling is handled by the indicator)
- *
- * @accessibility
- * - Receives focus management from parent RadioGroup component
- * - Arrow keys navigate between radio options within the group
- * - Space key selects the focused radio item
- * - Screen readers announce checked/unchecked state changes
- * - Focus visible indicator appears on keyboard navigation
- * - Proper ARIA attributes (role="radio", aria-checked) applied automatically
- * - Works with form validation and submission
- * - Supports required attribute for form validation
- *
- * @see {@link RadioGroup} for the parent container component that manages the group behavior
- * @see {@link RadioGroupIndicator} for the visual checked state indicator
- * @see {@link https://ui.shadcn.com/docs/components/radio-group} shadcn/ui Radio Group usage patterns
- * @see {@link https://www.radix-ui.com/primitives/docs/components/radio-group} Radix UI Radio Group Item documentation
- * @since 1.0.0
+ * Individual radio button item. Use with RadioGroup to create mutually exclusive selections.
+ * Automatically renders an indicator when checked.
  */
-function RadioGroupItem({
-  className,
-  ...props
-}: React.ComponentProps<typeof RadioGroupPrimitive.Item>) {
+function RadioGroupItem({ className, ...props }: RadioGroupItemProps) {
   return (
-    <RadioGroupPrimitive.Item
+    <RadioPrimitive.Root
       data-slot="radio-group-item"
       className={cn(
-        "border-input text-primary 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 aspect-square size-4 shrink-0 rounded-full border shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50",
+        "border-input text-primary dark:bg-input/30 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 flex size-4 rounded-full shadow-xs focus-visible:ring-[3px] aria-invalid:ring-[3px] group/radio-group-item peer relative aspect-square shrink-0 border outline-none after:absolute after:-inset-x-3 after:-inset-y-2 disabled:cursor-not-allowed disabled:opacity-50",
         className,
       )}
       {...props}
     >
-      <RadioGroupIndicator />
-    </RadioGroupPrimitive.Item>
-  );
-}
-
-/**
- * Visual indicator shown when a RadioGroupItem is in the checked state
- *
- * RadioGroupIndicator automatically appears inside RadioGroupItem when that item is selected.
- * It provides the visual feedback for the checked state using a filled circle icon.
- * The indicator is automatically managed by the RadioGroupItem and only renders when checked.
- *
- * This component is typically not used directly but is included in RadioGroupItem.
- * It can be customized or replaced using the asChild pattern if needed.
- *
- * @example Default usage (automatic within RadioGroupItem)
- * ```tsx
- * // RadioGroupIndicator is automatically included in RadioGroupItem
- * <RadioGroupItem value="selected" id="selected" />
- * ```
- *
- * @example Custom indicator with asChild
- * ```tsx
- * <RadioGroupItem value="custom" id="custom">
- *   <RadioGroupIndicator asChild>
- *     <CheckIcon className="size-3 text-primary" />
- *   </RadioGroupIndicator>
- * </RadioGroupItem>
- * ```
- *
- * @example Force mounted indicator (for animations)
- * ```tsx
- * <RadioGroupIndicator forceMount className="animate-scale-in" />
- * ```
- *
- * @param forceMount Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries
- * @param asChild Change the default rendered element for the one passed as a child @default false
- * @param className Additional CSS classes for custom styling of the indicator
- * @param children Custom content to render instead of the default CircleIcon (when using asChild)
- *
- * @accessibility
- * - Automatically managed by RadioGroup state - no manual interaction needed
- * - Provides visual confirmation of selection for users who can see
- * - Works with high contrast mode and forced colors
- * - Scales appropriately with font size changes
- *
- * @see {@link RadioGroupItem} for the parent radio button component
- * @see {@link RadioGroup} for the container component
- * @since 1.0.0
- */
-function RadioGroupIndicator({
-  className,
-  ...props
-}: React.ComponentProps<typeof RadioGroupPrimitive.Indicator>) {
-  return (
-    <RadioGroupPrimitive.Indicator
-      data-slot="radio-group-indicator"
-      className={cn("relative flex items-center justify-center", className)}
-      {...props}
-    >
-      <CircleIcon className="fill-primary absolute top-1/2 left-1/2 size-2 -translate-x-1/2 -translate-y-1/2" />
-    </RadioGroupPrimitive.Indicator>
+      <RadioPrimitive.Indicator
+        data-slot="radio-group-indicator"
+        className="group-aria-invalid/radio-group-item:text-destructive text-primary flex size-4 items-center justify-center"
+      >
+        <CircleIcon className="absolute top-1/2 left-1/2 size-2 -translate-x-1/2 -translate-y-1/2 fill-current" />
+      </RadioPrimitive.Indicator>
+    </RadioPrimitive.Root>
   );
 }
 
-export { RadioGroup, RadioGroupItem, RadioGroupIndicator };
+export {
+  RadioGroup,
+  RadioGroupItem,
+  type RadioGroupProps,
+  type RadioGroupItemProps,
+};