@neynar/ui 0.1.1 → 0.1.2

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

@@ -6,14 +6,74 @@ import { CircleIcon } from "lucide-react";
 
 import { cn } from "@/lib/utils";
 
+/**
+ * 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>;
+
 /**
  * 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 primitives with custom styling that follows shadcn/ui design patterns.
- * Each radio group should contain RadioGroupItem components paired with Labels for accessibility.
+ * 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 usage
+ * @example Basic uncontrolled usage
  * ```tsx
  * <RadioGroup defaultValue="option-one">
  *   <div className="flex items-center space-x-2">
@@ -51,9 +111,13 @@ import { cn } from "@/lib/utils";
  * }
  * ```
  *
- * @example Horizontal layout
+ * @example Horizontal orientation
  * ```tsx
- * <RadioGroup defaultValue="option-one" className="flex gap-4">
+ * <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>
@@ -65,35 +129,80 @@ import { cn } from "@/lib/utils";
  * </RadioGroup>
  * ```
  *
- * @example With descriptions
+ * @example With rich content and descriptions
  * ```tsx
- * <RadioGroup defaultValue="card">
+ * <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
+ *         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>
  * ```
  *
- * @param defaultValue - The default selected value when uncontrolled
- * @param value - The controlled value of the radio group
- * @param onValueChange - Callback fired when the value changes
- * @param disabled - Whether the entire radio group is disabled
- * @param required - Whether the radio group is required for form validation
- * @param orientation - The orientation of the radio group (defaults to vertical)
- * @param className - Additional CSS classes to apply to the radio group
- * @param children - RadioGroupItem components and their associated labels
+ * @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>
+ * ```
  *
- * @see {@link https://ui.shadcn.com/docs/components/radio-group} for design patterns
+ * @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
- * @see {@link RadioGroupItem} for individual radio options
- * @see {@link Checkbox} for multiple selection use cases
- * @see {@link Select} for dropdown-style single selection
  */
 function RadioGroup({
   className,
@@ -112,49 +221,94 @@ function RadioGroup({
  * 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 paired with a Label for accessibility.
+ * 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
+ * @example Basic usage with label
  * ```tsx
- * <RadioGroupItem value="option-one" id="option-one" />
- * <Label htmlFor="option-one">Option One</Label>
+ * <div className="flex items-center space-x-2">
+ *   <RadioGroupItem value="option-one" id="option-one" />
+ *   <Label htmlFor="option-one">Option One</Label>
+ * </div>
  * ```
  *
- * @example With custom styling
+ * @example Custom styling and theming
  * ```tsx
  * <RadioGroupItem
  *   value="premium"
  *   id="premium"
- *   className="border-purple-500 text-purple-500"
+ *   className="border-purple-500 text-purple-500 data-[state=checked]:bg-purple-50"
  * />
- * <Label htmlFor="premium">Premium Plan</Label>
+ * <Label htmlFor="premium" className="text-purple-900">
+ *   Premium Plan
+ * </Label>
  * ```
  *
  * @example Disabled state
  * ```tsx
- * <RadioGroupItem value="unavailable" id="unavailable" disabled />
- * <Label htmlFor="unavailable" className="opacity-50">
- *   Unavailable Option
+ * <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 unique value for this radio option
- * @param id - The id attribute for accessibility (should match Label's htmlFor)
- * @param disabled - Whether this specific radio option is disabled
- * @param className - Additional CSS classes for custom styling
- * @param ref - React ref forwarded to the underlying input element
+ * @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
- * - Automatically receives focus management from parent RadioGroup
- * - Arrow keys navigate between radio options
- * - Space key toggles selection
- * - Screen readers announce checked/unchecked state
- * - Focus visible indicator for keyboard navigation
- * - Proper ARIA attributes and roles
- *
- * @see {@link RadioGroup} for the parent container component
- * @see {@link https://ui.shadcn.com/docs/components/radio-group} for usage patterns
+ * - 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
  */
 function RadioGroupItem({
@@ -170,14 +324,69 @@ function RadioGroupItem({
       )}
       {...props}
     >
-      <RadioGroupPrimitive.Indicator
-        data-slot="radio-group-indicator"
-        className="relative flex items-center justify-center"
-      >
-        <CircleIcon className="fill-primary absolute top-1/2 left-1/2 size-2 -translate-x-1/2 -translate-y-1/2" />
-      </RadioGroupPrimitive.Indicator>
+      <RadioGroupIndicator />
     </RadioGroupPrimitive.Item>
   );
 }
 
-export { RadioGroup, RadioGroupItem };
+/**
+ * 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>
+  );
+}
+
+export { RadioGroup, RadioGroupItem, RadioGroupIndicator };