@neynar/ui 0.1.1 → 0.1.2

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

@@ -12,18 +12,160 @@ const ToggleGroupContext = React.createContext<
   variant: "default",
 });
 
+/**
+ * Props for ToggleGroup (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ * 
+ * Combines Radix UI ToggleGroup.Root props with visual variant options from CVA.
+ * Supports both single and multiple selection modes with keyboard navigation.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ToggleGroupDocsProps = {
+  /** Additional CSS classes to apply to the toggle group container */
+  className?: string;
+  /** 
+   * Selection mode for the toggle group
+   * @description Determines how many items can be selected simultaneously
+   * - "single": Only one item can be selected at a time (radio-like behavior)
+   * - "multiple": Multiple items can be selected independently (checkbox-like behavior)
+   */
+  type: "single" | "multiple";
+  /** 
+   * Visual style variant inherited by all child items
+   * @description Controls the appearance and visual emphasis of toggle items
+   * @default "default"
+   */
+  variant?: "default" | "outline";
+  /** 
+   * Size variant inherited by all child items
+   * @description Controls the padding and dimensions of toggle items
+   * @default "default"
+   */
+  size?: "sm" | "default" | "lg";
+  /** 
+   * Default selected value(s) for uncontrolled usage
+   * @description Initial selection state when not controlling the component
+   * - For type="single": string value of initially selected item
+   * - For type="multiple": array of string values for initially selected items
+   */
+  defaultValue?: string | string[];
+  /** 
+   * Current selected value(s) for controlled usage
+   * @description Current selection state when controlling the component externally
+   * - For type="single": string value of currently selected item, or undefined for none
+   * - For type="multiple": array of string values for currently selected items
+   */
+  value?: string | string[];
+  /** 
+   * Callback fired when selection changes
+   * @description Called whenever the user selects or deselects items
+   * - For type="single": receives string value or undefined
+   * - For type="multiple": receives array of selected string values
+   * @param value - The new selection value(s)
+   */
+  onValueChange?: (value: string | string[]) => void;
+  /** 
+   * Whether the entire toggle group is disabled
+   * @description When true, all items become non-interactive and visually disabled
+   * @default false
+   */
+  disabled?: boolean;
+  /** 
+   * Whether to enable roving focus behavior
+   * @description Controls keyboard navigation between items using arrow keys
+   * @default true
+   */
+  rovingFocus?: boolean;
+  /** 
+   * Layout orientation of the toggle group
+   * @description Affects keyboard navigation direction and visual layout hints
+   * - "horizontal": Arrow Left/Right navigate, items laid out horizontally
+   * - "vertical": Arrow Up/Down navigate, items laid out vertically
+   * @default "horizontal"
+   */
+  orientation?: "horizontal" | "vertical";
+  /** 
+   * Reading direction for internationalization
+   * @description Affects the logical navigation order and layout direction
+   * - "ltr": Left-to-right reading direction
+   * - "rtl": Right-to-left reading direction
+   */
+  dir?: "ltr" | "rtl";
+  /** 
+   * Whether focus should loop from last to first item
+   * @description Controls behavior when navigating past the end of the group
+   * @default true
+   */
+  loop?: boolean;
+  /** 
+   * Render as a different element or merge props
+   * @description When true, merges props into immediate child instead of rendering div
+   * @default false
+   */
+  asChild?: boolean;
+  /** Toggle group items and other React children */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof ToggleGroupPrimitive.Root>;
+
+/**
+ * Props for ToggleGroupItem (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ * 
+ * Individual selectable items within a ToggleGroup. Inherits variant and size from
+ * parent ToggleGroup context but can override them for specific styling needs.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ToggleGroupItemDocsProps = {
+  /** Additional CSS classes to apply to the toggle item */
+  className?: string;
+  /** 
+   * Unique identifier for this toggle item (required)
+   * @description Used to track selection state and must be unique within the group
+   */
+  value: string;
+  /** 
+   * Whether this specific item is disabled
+   * @description When true, this item becomes non-interactive while others remain functional
+   * @default false
+   */
+  disabled?: boolean;
+  /** 
+   * Override visual style variant from parent ToggleGroup
+   * @description When provided, overrides the variant inherited from ToggleGroup context
+   */
+  variant?: "default" | "outline";
+  /** 
+   * Override size variant from parent ToggleGroup
+   * @description When provided, overrides the size inherited from ToggleGroup context
+   */
+  size?: "sm" | "default" | "lg";
+  /** 
+   * Render as a different element or merge props
+   * @description When true, merges props into immediate child instead of rendering button
+   * @default false
+   */
+  asChild?: boolean;
+  /** Content to display within the toggle item (icons, text, or both) */
+  children?: React.ReactNode;
+} & React.ComponentProps<typeof ToggleGroupPrimitive.Item>;
+
 /**
  * Toggle Group - A group of toggle buttons with single or multiple selection
  *
  * ToggleGroup provides a way to group related toggle buttons together, allowing users
  * to select from a set of mutually exclusive options (single selection) or independent
- * options (multiple selection). Built on Radix UI Toggle Group primitive with support
- * for keyboard navigation and accessibility features.
+ * options (multiple selection). Built on Radix UI Toggle Group primitive with enhanced
+ * styling through CVA variants and full accessibility support including keyboard navigation.
  *
- * @example
+ * The component supports both controlled and uncontrolled usage patterns, with automatic
+ * focus management and roving tabindex behavior. Visual variants are inherited by all child
+ * items but can be overridden per item if needed.
+ *
+ * @example Single selection with icons (radio button behavior)
  * ```tsx
- * // Single selection (like radio buttons)
- * <ToggleGroup type="single" defaultValue="center">
+ * import { AlignLeft, AlignCenter, AlignRight } from "lucide-react";
+ * 
+ * <ToggleGroup type="single" defaultValue="center" aria-label="Text alignment">
  *   <ToggleGroupItem value="left" aria-label="Align left">
  *     <AlignLeft className="h-4 w-4" />
  *   </ToggleGroupItem>
@@ -36,51 +178,92 @@ const ToggleGroupContext = React.createContext<
  * </ToggleGroup>
  * ```
  *
- * @example
+ * @example Multiple selection with controlled state
  * ```tsx
- * // Multiple selection (like checkboxes)
- * <ToggleGroup type="multiple" defaultValue={["bold", "italic"]}>
- *   <ToggleGroupItem value="bold" aria-label="Toggle bold">
- *     <Bold className="h-4 w-4" />
- *   </ToggleGroupItem>
- *   <ToggleGroupItem value="italic" aria-label="Toggle italic">
- *     <Italic className="h-4 w-4" />
- *   </ToggleGroupItem>
- *   <ToggleGroupItem value="underline" aria-label="Toggle underline">
- *     <Underline className="h-4 w-4" />
- *   </ToggleGroupItem>
- * </ToggleGroup>
+ * import { Bold, Italic, Underline } from "lucide-react";
+ * 
+ * function TextEditor() {
+ *   const [formatting, setFormatting] = useState<string[]>(["bold"]);
+ * 
+ *   return (
+ *     <ToggleGroup
+ *       type="multiple"
+ *       value={formatting}
+ *       onValueChange={setFormatting}
+ *       aria-label="Text formatting"
+ *     >
+ *       <ToggleGroupItem value="bold" aria-label="Toggle bold">
+ *         <Bold className="h-4 w-4" />
+ *       </ToggleGroupItem>
+ *       <ToggleGroupItem value="italic" aria-label="Toggle italic">
+ *         <Italic className="h-4 w-4" />
+ *       </ToggleGroupItem>
+ *       <ToggleGroupItem value="underline" aria-label="Toggle underline">
+ *         <Underline className="h-4 w-4" />
+ *       </ToggleGroupItem>
+ *     </ToggleGroup>
+ *   );
+ * }
  * ```
  *
- * @example
+ * @example Text-based options with outline variant
  * ```tsx
- * // Text-based options with variants
- * <ToggleGroup type="single" variant="outline" size="sm">
+ * <ToggleGroup type="single" variant="outline" size="sm" defaultValue="draft">
  *   <ToggleGroupItem value="draft">Draft</ToggleGroupItem>
+ *   <ToggleGroupItem value="review">In Review</ToggleGroupItem>
  *   <ToggleGroupItem value="published">Published</ToggleGroupItem>
  *   <ToggleGroupItem value="archived">Archived</ToggleGroupItem>
  * </ToggleGroup>
  * ```
  *
- * @param type - Selection mode: "single" for radio-like behavior, "multiple" for checkbox-like
- * @param variant - Visual style: "default" (subtle) or "outline" (bordered)
- * @param size - Size variant: "sm", "default", or "lg"
- * @param disabled - Whether the entire group is disabled
- * @param defaultValue - Initial selected value(s) - string for single, array for multiple
- * @param value - Controlled selected value(s) - string for single, array for multiple
- * @param onValueChange - Callback when selection changes
+ * @example Vertical orientation for sidebar controls
+ * ```tsx
+ * <ToggleGroup
+ *   type="multiple"
+ *   orientation="vertical"
+ *   variant="outline"
+ *   className="flex-col"
+ * >
+ *   <ToggleGroupItem value="notifications">Notifications</ToggleGroupItem>
+ *   <ToggleGroupItem value="sidebar">Show Sidebar</ToggleGroupItem>
+ *   <ToggleGroupItem value="minimap">Show Minimap</ToggleGroupItem>
+ * </ToggleGroup>
+ * ```
+ *
+ * @example Mixed content with icons and text
+ * ```tsx
+ * <ToggleGroup type="single" variant="outline" size="lg">
+ *   <ToggleGroupItem value="grid">
+ *     <Grid className="h-4 w-4" />
+ *     Grid View
+ *   </ToggleGroupItem>
+ *   <ToggleGroupItem value="list">
+ *     <List className="h-4 w-4" />
+ *     List View
+ *   </ToggleGroupItem>
+ * </ToggleGroup>
+ * ```
+ *
+ * @variant default - Subtle background styling with transparent base, accent color when pressed
+ * @variant outline - Bordered styling with subtle shadow, maintains outline when pressed
  *
  * @accessibility
- * - Uses role="group" with appropriate ARIA attributes
- * - Arrow keys navigate between items with roving tabindex
- * - Space or Enter key toggles item selection
- * - Home/End keys jump to first/last items
+ * - Implements WAI-ARIA ToggleButton pattern with proper roles and states
+ * - Uses roving tabindex for keyboard navigation between items
+ * - Arrow keys navigate between items (direction based on orientation)
+ * - Space or Enter key toggles item selection state
+ * - Home key moves focus to first item, End key to last item
+ * - Focus wraps from last to first item when loop=true (default)
  * - Supports disabled state for individual items or entire group
- * - Screen readers announce selection state changes
+ * - Screen readers announce selection state changes via aria-pressed
+ * - Proper focus management with visible focus indicators
+ * - Group labeling via aria-label or aria-labelledby recommended
  *
- * @see {@link ToggleGroupItem} - Individual toggle items within the group
- * @see {@link Toggle} - Standalone toggle button component
- * @see {@link https://ui.shadcn.com/docs/components/toggle-group} - Design system documentation
+ * @see {@link ToggleGroupItem} Individual toggle items within the group
+ * @see {@link Toggle} Standalone toggle button component  
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/toggle-group} Radix UI ToggleGroup primitive
+ * @see {@link https://ui.shadcn.com/docs/components/toggle-group} Design system documentation
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/button/} WAI-ARIA Toggle Button pattern
  * @since 1.0.0
  */
 function ToggleGroup({
@@ -89,8 +272,7 @@ function ToggleGroup({
   size,
   children,
   ...props
-}: React.ComponentProps<typeof ToggleGroupPrimitive.Root> &
-  VariantProps<typeof toggleVariants>) {
+}: React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root> & VariantProps<typeof toggleVariants>) {
   return (
     <ToggleGroupPrimitive.Root
       data-slot="toggle-group"
@@ -112,56 +294,86 @@ function ToggleGroup({
 /**
  * Toggle Group Item - Individual selectable item within a ToggleGroup
  *
- * Represents a single option within a ToggleGroup component. Automatically inherits
- * variant and size styling from the parent ToggleGroup context, but these can be
- * overridden for specific items if needed. Supports icons, text, or mixed content.
+ * Represents a single toggleable option within a ToggleGroup component. Each item
+ * automatically inherits variant and size styling from the parent ToggleGroup context
+ * through React Context, but these can be overridden for specific styling needs.
+ * Supports flexible content including icons, text, or mixed combinations.
+ *
+ * The component participates in the parent ToggleGroup's keyboard navigation and
+ * selection behavior, with proper ARIA attributes for accessibility. Focus management
+ * and selection state are handled automatically by the Radix UI primitive.
  *
- * @example
+ * @example Text-based item with inherited styling
  * ```tsx
- * // Text-based item
  * <ToggleGroupItem value="draft">Draft</ToggleGroupItem>
  * ```
  *
- * @example
+ * @example Icon-only item with required accessibility label
  * ```tsx
- * // Icon-only item (requires aria-label)
+ * import { Bold } from "lucide-react";
+ * 
  * <ToggleGroupItem value="bold" aria-label="Toggle bold formatting">
  *   <Bold className="h-4 w-4" />
  * </ToggleGroupItem>
  * ```
  *
- * @example
+ * @example Mixed content with icon and descriptive text
  * ```tsx
- * // Mixed content with icon and text
- * <ToggleGroupItem value="bold">
- *   <Bold className="h-4 w-4" />
- *   Bold
+ * import { Calendar } from "lucide-react";
+ * 
+ * <ToggleGroupItem value="calendar">
+ *   <Calendar className="h-4 w-4" />
+ *   Calendar View
+ * </ToggleGroupItem>
+ * ```
+ *
+ * @example Override inherited styling for special emphasis
+ * ```tsx
+ * <ToggleGroupItem 
+ *   value="premium" 
+ *   variant="outline" 
+ *   size="lg"
+ *   className="border-gold text-gold"
+ * >
+ *   Premium Feature
  * </ToggleGroupItem>
  * ```
  *
- * @example
+ * @example Disabled item within functional group
  * ```tsx
- * // Override inherited styling
- * <ToggleGroupItem value="special" variant="outline" size="lg">
- *   Special Option
+ * <ToggleGroupItem 
+ *   value="coming-soon" 
+ *   disabled
+ *   aria-label="Feature coming soon"
+ * >
+ *   <Sparkles className="h-4 w-4" />
+ *   Coming Soon
  * </ToggleGroupItem>
  * ```
  *
- * @param value - Unique identifier for this item within the group (required)
- * @param disabled - Whether this specific item is disabled
- * @param variant - Override variant from parent ToggleGroup
- * @param size - Override size from parent ToggleGroup
- * @param children - Content to display (icons, text, or both)
+ * @example Using asChild for custom element composition
+ * ```tsx
+ * <ToggleGroupItem value="custom" asChild>
+ *   <a href="/settings" className="no-underline">
+ *     <Settings className="h-4 w-4" />
+ *     Settings
+ *   </a>
+ * </ToggleGroupItem>
+ * ```
  *
  * @accessibility
- * - Participates in parent ToggleGroup's keyboard navigation
- * - Uses aria-pressed to indicate selection state
- * - Supports focus management with visible focus indicators
- * - For icon-only items, always provide aria-label for screen readers
- * - Disabled items are excluded from keyboard navigation
- *
- * @see {@link ToggleGroup} - Parent container component
- * @see {@link Toggle} - Standalone toggle button
+ * - Participates in parent ToggleGroup's roving tabindex navigation
+ * - Uses aria-pressed attribute to indicate selection state ("true"/"false")
+ * - Supports focus management with visible focus indicators and proper focus ring
+ * - For icon-only items, always provide aria-label for screen reader users
+ * - Disabled items are excluded from keyboard navigation and marked non-interactive
+ * - Inherits semantic meaning from parent group's aria-label or aria-labelledby
+ * - Proper button semantics with keyboard activation (Space/Enter)
+ *
+ * @see {@link ToggleGroup} Parent container component that manages selection state
+ * @see {@link Toggle} Standalone toggle button for independent usage
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/toggle-group} Radix UI primitive documentation
+ * @since 1.0.0
  */
 function ToggleGroupItem({
   className,
@@ -169,8 +381,7 @@ function ToggleGroupItem({
   variant,
   size,
   ...props
-}: React.ComponentProps<typeof ToggleGroupPrimitive.Item> &
-  VariantProps<typeof toggleVariants>) {
+}: React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> & VariantProps<typeof toggleVariants>) {
   const context = React.useContext(ToggleGroupContext);
 
   return (

package/src/components/ui/toggle.tsx

@@ -1,22 +1,35 @@
 import * as React from "react";
 import * as TogglePrimitive from "@radix-ui/react-toggle";
-import { cva, type VariantProps } from "class-variance-authority";
+import { cva } from "class-variance-authority";
 
 import { cn } from "@/lib/utils";
 
+/**
+ * Toggle component variant configuration
+ *
+ * Defines visual styles and sizing options for the toggle component
+ * with proper state indicators and accessibility features.
+ *
+ * @variant default - Clean transparent background with hover states
+ * @variant outline - Bordered style with subtle shadow for emphasis
+ *
+ * @size sm - Compact 32px height for dense layouts
+ * @size default - Standard 36px height for general use
+ * @size lg - Large 40px height for prominent actions
+ */
 const toggleVariants = cva(
   "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium hover:bg-muted hover:text-muted-foreground disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0 focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] outline-none transition-[color,box-shadow] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive whitespace-nowrap",
   {
     variants: {
       variant: {
-        default: "bg-transparent",
+        default: "bg-transparent", // Clean transparent background with hover states
         outline:
-          "border border-input bg-transparent shadow-xs hover:bg-accent hover:text-accent-foreground",
+          "border border-input bg-transparent shadow-xs hover:bg-accent hover:text-accent-foreground", // Bordered style with subtle shadow for emphasis
       },
       size: {
-        default: "h-9 px-2 min-w-9",
-        sm: "h-8 px-1.5 min-w-8",
-        lg: "h-10 px-2.5 min-w-10",
+        default: "h-9 px-2 min-w-9", // Standard 36px height for general use
+        sm: "h-8 px-1.5 min-w-8", // Compact 32px height for dense layouts
+        lg: "h-10 px-2.5 min-w-10", // Large 40px height for prominent actions
       },
     },
     defaultVariants: {
@@ -26,18 +39,46 @@ const toggleVariants = cva(
   },
 );
 
+/**
+ * Props for Toggle component
+ *
+ * Combines Radix UI Toggle primitive props with custom variant styling options.
+ * Supports both controlled and uncontrolled usage patterns.
+ */
+type ToggleProps = {
+  /** Whether to render as a child element instead of the default button */
+  asChild?: boolean;
+  /** The pressed state of the toggle when initially rendered (uncontrolled) @default false */
+  defaultPressed?: boolean;
+  /** The controlled pressed state of the toggle */
+  pressed?: boolean;
+  /** Event handler called when the pressed state changes */
+  onPressedChange?: (pressed: boolean) => void;
+  /** When true, prevents user interaction with the toggle */
+  disabled?: boolean;
+  /** Visual style variant for the toggle appearance */
+  variant?: "default" | "outline";
+  /** Size variant that affects dimensions and padding */
+  size?: "sm" | "default" | "lg";
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Toggle content - typically icons, text, or both */
+  children?: React.ReactNode;
+} & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'disabled' | 'children'>;
+
 /**
  * A two-state button that can be either on or off
  *
  * The Toggle component provides an accessible button with on/off state functionality.
  * Built on Radix UI Toggle primitives with customizable variants and sizes.
- * Ideal for text formatting controls, settings toggles, and any binary state controls.
+ * Perfect for text formatting controls, feature toggles, and any binary state controls.
+ * Automatically manages ARIA attributes and provides keyboard navigation.
  *
- * @example Basic usage with icon
+ * @example Basic toggle with icon
  * ```tsx
  * import { Bold } from "lucide-react"
  *
- * <Toggle aria-label="Toggle bold">
+ * <Toggle aria-label="Toggle bold formatting">
  *   <Bold className="h-4 w-4" />
  * </Toggle>
  * ```
@@ -55,7 +96,7 @@ const toggleVariants = cva(
  * </Toggle>
  * ```
  *
- * @example With text and outline variant
+ * @example Toggle with text and outline variant
  * ```tsx
  * <Toggle variant="outline" size="lg">
  *   <Italic className="h-4 w-4" />
@@ -65,42 +106,88 @@ const toggleVariants = cva(
  *
  * @example Text formatting toolbar
  * ```tsx
- * <div className="flex gap-1">
- *   <Toggle pressed={bold} onPressedChange={setBold}>
+ * <div className="flex gap-1 p-2 border rounded-md">
+ *   <Toggle
+ *     pressed={formatting.bold}
+ *     onPressedChange={(pressed) => setFormatting(prev => ({ ...prev, bold: pressed }))}
+ *     aria-label="Bold"
+ *   >
  *     <Bold className="h-4 w-4" />
  *   </Toggle>
- *   <Toggle pressed={italic} onPressedChange={setItalic}>
+ *   <Toggle
+ *     pressed={formatting.italic}
+ *     onPressedChange={(pressed) => setFormatting(prev => ({ ...prev, italic: pressed }))}
+ *     aria-label="Italic"
+ *   >
  *     <Italic className="h-4 w-4" />
  *   </Toggle>
+ *   <Toggle
+ *     pressed={formatting.underline}
+ *     onPressedChange={(pressed) => setFormatting(prev => ({ ...prev, underline: pressed }))}
+ *     aria-label="Underline"
+ *   >
+ *     <Underline className="h-4 w-4" />
+ *   </Toggle>
  * </div>
  * ```
  *
+ * @example Toggle group for settings
+ * ```tsx
+ * <div className="space-y-2">
+ *   <div className="flex items-center justify-between">
+ *     <Label htmlFor="notifications">Notifications</Label>
+ *     <Toggle
+ *       id="notifications"
+ *       pressed={settings.notifications}
+ *       onPressedChange={(pressed) => updateSetting('notifications', pressed)}
+ *       variant="outline"
+ *     >
+ *       <Bell className="h-4 w-4" />
+ *     </Toggle>
+ *   </div>
+ *   <div className="flex items-center justify-between">
+ *     <Label htmlFor="dark-mode">Dark Mode</Label>
+ *     <Toggle
+ *       id="dark-mode"
+ *       pressed={settings.darkMode}
+ *       onPressedChange={(pressed) => updateSetting('darkMode', pressed)}
+ *       variant="outline"
+ *     >
+ *       <Moon className="h-4 w-4" />
+ *     </Toggle>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @example Disabled state with tooltip
+ * ```tsx
+ * <Tooltip>
+ *   <TooltipTrigger asChild>
+ *     <Toggle disabled aria-label="Unavailable feature">
+ *       <Lock className="h-4 w-4" />
+ *       Pro Feature
+ *     </Toggle>
+ *   </TooltipTrigger>
+ *   <TooltipContent>
+ *     <p>This feature requires a Pro subscription</p>
+ *   </TooltipContent>
+ * </Tooltip>
+ * ```
+ *
  * @accessibility
- * - Supports keyboard navigation (Space/Enter to toggle)
- * - Automatically manages aria-pressed attribute
- * - Requires aria-label for icon-only toggles
- * - Focus management with visible focus indicators
- * - Disabled state properly communicated to assistive technology
+ * - Keyboard Support: Space and Enter keys activate/deactivate the toggle
+ * - Screen Reader Support: Automatically manages aria-pressed attribute ("true"/"false")
+ * - Focus Management: Visible focus indicators with customizable focus ring
+ * - State Communication: Uses data-state attribute ("on"/"off") for styling pressed state
+ * - Disabled State: Properly communicated to assistive technology with aria-disabled
+ * - Labeling: Requires accessible name via aria-label or aria-labelledby for icon-only toggles
+ * - High Contrast: Maintains visibility in high contrast mode with proper color combinations
  *
- * @see {@link https://ui.shadcn.com/docs/components/toggle} shadcn/ui Toggle documentation
- * @since 1.0.0
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/toggle} Radix UI Toggle Documentation
+ * @see {@link https://ui.shadcn.com/docs/components/toggle} shadcn/ui Toggle Documentation
  * @see {@link ToggleGroup} For mutually exclusive toggle groups
+ * @since 1.0.0
  */
-/**
- * Toggle component props
- *
- * @param className - Additional CSS classes to apply
- * @param variant - Visual style variant ("default" | "outline")
- * @param size - Size variant ("sm" | "default" | "lg")
- * @param pressed - Controlled pressed state
- * @param defaultPressed - Default pressed state for uncontrolled usage
- * @param onPressedChange - Callback fired when pressed state changes
- * @param disabled - Whether the toggle is disabled
- * @param children - Toggle content (typically icons or text)
- * @param ...props - Additional props passed to Radix Toggle primitive
- */
-type ToggleProps = React.ComponentProps<typeof TogglePrimitive.Root> &
-  VariantProps<typeof toggleVariants>;
 
 function Toggle({ className, variant, size, ...props }: ToggleProps) {
   return (
@@ -112,4 +199,6 @@ function Toggle({ className, variant, size, ...props }: ToggleProps) {
   );
 }
 
+Toggle.displayName = "Toggle";
+
 export { Toggle, toggleVariants };