@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/navigation-menu.tsx

@@ -5,23 +5,50 @@ import { ChevronDownIcon } from "lucide-react";
 
 import { cn } from "@/lib/utils";
 
+/**
+ * Props for NavigationMenu 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 NavigationMenuDocsProps = {
+  /** The value of the menu item that should be active when initially rendered. Use when not controlling the value state */
+  defaultValue?: string;
+  /** The controlled value of the menu item that should be active. Should be used in conjunction with onValueChange */
+  value?: string;
+  /** Event handler called when the value changes */
+  onValueChange?: (value: string) => void;
+  /** The duration from when the pointer enters the trigger until the tooltip gets opened. @default 200 */
+  delayDuration?: number;
+  /** How much time a user has to enter another trigger without incurring a delay again. @default 300 */
+  skipDelayDuration?: number;
+  /** The reading direction when applicable. If omitted, inherits globally from DirectionProvider or assumes LTR */
+  dir?: "ltr" | "rtl";
+  /** The orientation of the menu. @default "horizontal" */
+  orientation?: "horizontal" | "vertical";
+  /** Whether to render the navigation viewport container for dropdown content positioning. @default true */
+  viewport?: boolean;
+} & React.ComponentProps<"nav">;
+
 /**
  * NavigationMenu - A collection of links for navigating websites
  *
- * A horizontal navigation component built on Radix UI primitives that provides
- * flexible navigation patterns with dropdown content support. Features full
- * keyboard navigation, accessibility compliance, and responsive design.
+ * A flexible navigation component built on Radix UI primitives that provides
+ * sophisticated navigation patterns with dropdown content support. Features full
+ * keyboard navigation, accessibility compliance, controlled/uncontrolled states,
+ * and responsive design. Supports both horizontal and vertical orientations.
  *
- * @component
  * @example
  * ```tsx
  * // Basic navigation with dropdown
  * <NavigationMenu>
  *   <NavigationMenuList>
- *     <NavigationMenuItem>
+ *     <NavigationMenuItem value="products">
  *       <NavigationMenuTrigger>Products</NavigationMenuTrigger>
  *       <NavigationMenuContent>
- *         <NavigationMenuLink href="/products">All Products</NavigationMenuLink>
+ *         <div className="grid gap-3 p-6 w-[400px]">
+ *           <NavigationMenuLink href="/products/analytics">Analytics</NavigationMenuLink>
+ *           <NavigationMenuLink href="/products/dashboard">Dashboard</NavigationMenuLink>
+ *         </div>
  *       </NavigationMenuContent>
  *     </NavigationMenuItem>
  *   </NavigationMenuList>
@@ -30,14 +57,35 @@ import { cn } from "@/lib/utils";
  *
  * @example
  * ```tsx
- * // Simple navigation links
+ * // Controlled navigation with state
+ * const [value, setValue] = React.useState<string | undefined>();
+ *
+ * <NavigationMenu value={value} onValueChange={setValue}>
+ *   <NavigationMenuList>
+ *     <NavigationMenuItem value="features">
+ *       <NavigationMenuTrigger>Features</NavigationMenuTrigger>
+ *       <NavigationMenuContent>
+ *         <NavigationMenuLink href="/features">All Features</NavigationMenuLink>
+ *       </NavigationMenuContent>
+ *     </NavigationMenuItem>
+ *   </NavigationMenuList>
+ * </NavigationMenu>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Simple navigation links without dropdowns
  * <NavigationMenu>
  *   <NavigationMenuList>
  *     <NavigationMenuItem>
- *       <NavigationMenuLink href="/about">About</NavigationMenuLink>
+ *       <NavigationMenuLink href="/about" className={navigationMenuTriggerStyle()}>
+ *         About
+ *       </NavigationMenuLink>
  *     </NavigationMenuItem>
  *     <NavigationMenuItem>
- *       <NavigationMenuLink href="/contact">Contact</NavigationMenuLink>
+ *       <NavigationMenuLink href="/contact" className={navigationMenuTriggerStyle()}>
+ *         Contact
+ *       </NavigationMenuLink>
  *     </NavigationMenuItem>
  *   </NavigationMenuList>
  * </NavigationMenu>
@@ -45,11 +93,11 @@ import { cn } from "@/lib/utils";
  *
  * @example
  * ```tsx
- * // With Next.js Link using asChild
+ * // With Next.js Link integration using asChild
  * <NavigationMenu>
  *   <NavigationMenuList>
  *     <NavigationMenuItem>
- *       <NavigationMenuLink asChild>
+ *       <NavigationMenuLink asChild className={navigationMenuTriggerStyle()}>
  *         <Link href="/dashboard">Dashboard</Link>
  *       </NavigationMenuLink>
  *     </NavigationMenuItem>
@@ -59,14 +107,32 @@ import { cn } from "@/lib/utils";
  *
  * @example
  * ```tsx
- * // Without viewport for simpler styling
+ * // Vertical navigation menu
+ * <NavigationMenu orientation="vertical">
+ *   <NavigationMenuList>
+ *     <NavigationMenuItem value="settings">
+ *       <NavigationMenuTrigger>Settings</NavigationMenuTrigger>
+ *       <NavigationMenuContent>
+ *         <div className="p-4 w-[200px]">
+ *           <NavigationMenuLink href="/settings/profile">Profile</NavigationMenuLink>
+ *           <NavigationMenuLink href="/settings/account">Account</NavigationMenuLink>
+ *         </div>
+ *       </NavigationMenuContent>
+ *     </NavigationMenuItem>
+ *   </NavigationMenuList>
+ * </NavigationMenu>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Without viewport for custom dropdown styling
  * <NavigationMenu viewport={false}>
  *   <NavigationMenuList>
- *     <NavigationMenuItem>
- *       <NavigationMenuTrigger>Features</NavigationMenuTrigger>
+ *     <NavigationMenuItem value="docs">
+ *       <NavigationMenuTrigger>Documentation</NavigationMenuTrigger>
  *       <NavigationMenuContent>
- *         <div className="p-4 w-[300px]">
- *           <NavigationMenuLink href="/analytics">Analytics</NavigationMenuLink>
+ *         <div className="bg-white border rounded-lg shadow-lg p-6 w-[500px]">
+ *           <NavigationMenuLink href="/docs/getting-started">Getting Started</NavigationMenuLink>
  *         </div>
  *       </NavigationMenuContent>
  *     </NavigationMenuItem>
@@ -74,34 +140,55 @@ import { cn } from "@/lib/utils";
  * </NavigationMenu>
  * ```
  *
- * @accessibility
- * - Full keyboard navigation with arrow keys for menu traversal
- * - Tab key moves between focusable menu items
- * - Escape key closes open dropdown menus
- * - Enter/Space activates triggers and links
- * - ARIA attributes for proper screen reader support
- * - Focus management with automatic focus trapping in dropdowns
- * - Semantic HTML structure for navigation landmarks
+ * @example
+ * ```tsx
+ * // With custom timing and active indicator
+ * <NavigationMenu
+ *   delayDuration={100}
+ *   skipDelayDuration={200}
+ *   defaultValue="home"
+ * >
+ *   <NavigationMenuList>
+ *     <NavigationMenuItem value="home">
+ *       <NavigationMenuTrigger>Home</NavigationMenuTrigger>
+ *       <NavigationMenuContent>
+ *         <NavigationMenuLink href="/">Homepage</NavigationMenuLink>
+ *       </NavigationMenuContent>
+ *     </NavigationMenuItem>
+ *     <NavigationMenuIndicator />
+ *   </NavigationMenuList>
+ * </NavigationMenu>
+ * ```
  *
+ * @accessibility
+ * - Full keyboard navigation with arrow keys for horizontal/vertical menu traversal
+ * - Tab key moves between focusable menu items and maintains logical tab sequence
+ * - Escape key closes open dropdown menus and returns focus to trigger
+ * - Enter and Space keys activate triggers and follow links
+ * - Home/End keys jump to first/last menu items
+ * - ARIA expanded/collapsed states automatically managed for triggers
+ * - ARIA current="page" support through active prop on links
+ * - Focus management with automatic focus trapping in dropdown content
+ * - Screen reader announcements for state changes and navigation
+ * - Semantic HTML nav structure for navigation landmarks
+ * - Proper ARIA labeling and relationships between triggers and content
+ *
+ * @see {@link NavigationMenuList} Container for menu items
+ * @see {@link NavigationMenuItem} Individual menu item wrapper
+ * @see {@link NavigationMenuTrigger} Dropdown trigger button
+ * @see {@link NavigationMenuContent} Dropdown content panel
+ * @see {@link NavigationMenuLink} Navigation link component
  * @see {@link https://ui.shadcn.com/docs/components/navigation-menu} shadcn/ui Navigation Menu
  * @see {@link https://www.radix-ui.com/primitives/docs/components/navigation-menu} Radix UI Navigation Menu
  * @since 1.0.0
  */
-/**
- * Main NavigationMenu component props
- *
- * @param viewport - Whether to render the navigation viewport container. Defaults to true.
- *                   Set to false for simpler dropdown styling without viewport positioning.
- * @param className - Additional CSS classes to apply to the navigation menu root
- * @param children - NavigationMenuList and NavigationMenuViewport components
- */
 function NavigationMenu({
   className,
   children,
   viewport = true,
   ...props
 }: React.ComponentProps<typeof NavigationMenuPrimitive.Root> & {
-  /** Whether to render the navigation viewport container for dropdown positioning */
+  /** Whether to render the navigation viewport container for dropdown content positioning. @default true */
   viewport?: boolean;
 }) {
   return (
@@ -120,26 +207,60 @@ function NavigationMenu({
   );
 }
 
+/**
+ * Props for NavigationMenuList 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 NavigationMenuListDocsProps = {
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior */
+  asChild?: boolean;
+} & React.ComponentProps<"ul">;
+
 /**
  * NavigationMenuList - Container for navigation menu items
  *
- * A horizontal list container that groups NavigationMenuItem components.
- * Provides the foundational layout structure for the navigation menu.
+ * The list container that groups NavigationMenuItem components within a NavigationMenu.
+ * Renders as an unordered list (ul) by default and provides the foundational layout
+ * structure for the navigation menu. Supports both horizontal and vertical orientations
+ * based on the parent NavigationMenu orientation prop.
  *
- * @component
  * @example
  * ```tsx
  * <NavigationMenuList>
- *   <NavigationMenuItem>
- *     <NavigationMenuLink href="/home">Home</NavigationMenuLink>
+ *   <NavigationMenuItem value="products">
+ *     <NavigationMenuTrigger>Products</NavigationMenuTrigger>
+ *     <NavigationMenuContent>
+ *       <NavigationMenuLink href="/products">All Products</NavigationMenuLink>
+ *     </NavigationMenuContent>
  *   </NavigationMenuItem>
  *   <NavigationMenuItem>
- *     <NavigationMenuLink href="/about">About</NavigationMenuLink>
+ *     <NavigationMenuLink href="/about" className={navigationMenuTriggerStyle()}>
+ *       About
+ *     </NavigationMenuLink>
  *   </NavigationMenuItem>
  * </NavigationMenuList>
  * ```
  *
- * @param className - Additional CSS classes for styling
+ * @example
+ * ```tsx
+ * // Custom list element using asChild
+ * <NavigationMenuList asChild>
+ *   <div className="custom-nav-container">
+ *     <NavigationMenuItem>
+ *       <NavigationMenuLink href="/home">Home</NavigationMenuLink>
+ *     </NavigationMenuItem>
+ *   </div>
+ * </NavigationMenuList>
+ * ```
+ *
+ * @accessibility
+ * - Renders as semantic ul element by default for proper list structure
+ * - Maintains proper ARIA relationships with contained NavigationMenuItem elements
+ * - Supports keyboard navigation between contained items
+ *
+ * @see {@link NavigationMenuItem} Individual menu item containers
+ * @see {@link NavigationMenu} Parent navigation menu component
  * @since 1.0.0
  */
 function NavigationMenuList({
@@ -158,34 +279,70 @@ function NavigationMenuList({
   );
 }
 
+/**
+ * Props for NavigationMenuItem 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 NavigationMenuItemDocsProps = {
+  /** A unique value that associates the item with an active value when controlled or defaultValue when uncontrolled */
+  value?: string;
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior */
+  asChild?: boolean;
+} & React.ComponentProps<"li">;
+
 /**
  * NavigationMenuItem - Individual navigation menu item container
  *
- * Wraps a single navigation item, which can contain either:
- * - A NavigationMenuTrigger with NavigationMenuContent for dropdowns
- * - A NavigationMenuLink for direct navigation
+ * A list item container that wraps a single navigation element within a NavigationMenuList.
+ * Each item can contain either a NavigationMenuTrigger with NavigationMenuContent for dropdown
+ * functionality, or a NavigationMenuLink for direct navigation. The value prop is used for
+ * controlled state management and active item tracking.
  *
- * @component
  * @example
  * ```tsx
- * // With dropdown content
- * <NavigationMenuItem>
+ * // Dropdown navigation item with controlled value
+ * <NavigationMenuItem value="products">
  *   <NavigationMenuTrigger>Products</NavigationMenuTrigger>
  *   <NavigationMenuContent>
- *     <NavigationMenuLink href="/products/all">All Products</NavigationMenuLink>
+ *     <div className="grid gap-3 p-6 w-[400px] grid-cols-2">
+ *       <NavigationMenuLink href="/products/analytics">Analytics</NavigationMenuLink>
+ *       <NavigationMenuLink href="/products/dashboard">Dashboard</NavigationMenuLink>
+ *     </div>
  *   </NavigationMenuContent>
  * </NavigationMenuItem>
  * ```
  *
  * @example
  * ```tsx
- * // Simple link
+ * // Simple navigation link item
  * <NavigationMenuItem>
- *   <NavigationMenuLink href="/contact">Contact</NavigationMenuLink>
+ *   <NavigationMenuLink href="/contact" className={navigationMenuTriggerStyle()}>
+ *     Contact Us
+ *   </NavigationMenuLink>
  * </NavigationMenuItem>
  * ```
  *
- * @param className - Additional CSS classes for styling
+ * @example
+ * ```tsx
+ * // With custom container element using asChild
+ * <NavigationMenuItem asChild>
+ *   <div className="custom-menu-item">
+ *     <NavigationMenuLink href="/about">About</NavigationMenuLink>
+ *   </div>
+ * </NavigationMenuItem>
+ * ```
+ *
+ * @accessibility
+ * - Renders as semantic li element by default for proper list item structure
+ * - Associates with parent NavigationMenu state through value prop
+ * - Maintains focus management within navigation sequences
+ * - Supports both direct links and trigger/content dropdown patterns
+ *
+ * @see {@link NavigationMenuTrigger} Dropdown trigger button
+ * @see {@link NavigationMenuContent} Dropdown content panel
+ * @see {@link NavigationMenuLink} Navigation link component
+ * @see {@link NavigationMenuList} Parent list container
  * @since 1.0.0
  */
 function NavigationMenuItem({
@@ -201,39 +358,94 @@ function NavigationMenuItem({
   );
 }
 
+/**
+ * Navigation menu trigger styling configuration using CVA (Class Variance Authority)
+ *
+ * Provides consistent button styling for navigation triggers with interactive states.
+ * Can be applied to NavigationMenuLink components for uniform trigger-style appearance.
+ *
+ * @variant base - Default trigger button styling with hover, focus, and disabled states
+ * - Interactive states: hover (accent background), focus (accent + ring), disabled (opacity + pointer-events)
+ * - Open state: Special styling when dropdown is open (accent background with opacity)
+ * - Focus visible: Ring indicator for keyboard navigation accessibility
+ *
+ * @example
+ * ```tsx
+ * // Apply to NavigationMenuLink for consistent button styling
+ * <NavigationMenuLink href="/docs" className={navigationMenuTriggerStyle()}>
+ *   Documentation
+ * </NavigationMenuLink>
+ * ```
+ *
+ * @see {@link NavigationMenuTrigger} Uses this styling automatically
+ * @see {@link NavigationMenuLink} Can use this for consistent trigger appearance
+ */
 const navigationMenuTriggerStyle = cva(
   "group inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2 text-sm font-medium hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground disabled:pointer-events-none disabled:opacity-50 data-[state=open]:hover:bg-accent data-[state=open]:text-accent-foreground data-[state=open]:focus:bg-accent data-[state=open]:bg-accent/50 focus-visible:ring-ring/50 outline-none transition-[color,box-shadow] focus-visible:ring-[3px] focus-visible:outline-1",
 );
 
 /**
- * NavigationMenuTrigger - Button that opens dropdown navigation content
+ * Props for NavigationMenuTrigger 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 NavigationMenuTriggerDocsProps = {
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior */
+  asChild?: boolean;
+} & React.ComponentProps<"button">;
+
+/**
+ * NavigationMenuTrigger - Interactive button that opens dropdown navigation content
  *
- * An interactive trigger button that displays NavigationMenuContent when activated.
- * Features automatic chevron icon rotation and hover/focus states. Supports the
- * asChild prop for custom button styling.
+ * A button component that toggles NavigationMenuContent visibility when activated.
+ * Automatically includes a chevron down icon that rotates when the dropdown is open.
+ * Features comprehensive keyboard and mouse interaction support with proper ARIA
+ * state management. The asChild prop allows composition with custom button components.
  *
- * @component
  * @example
  * ```tsx
- * <NavigationMenuTrigger>Features</NavigationMenuTrigger>
+ * // Basic trigger with dropdown content
+ * <NavigationMenuItem value="products">
+ *   <NavigationMenuTrigger>Products</NavigationMenuTrigger>
+ *   <NavigationMenuContent>
+ *     <div className="p-6 w-[400px]">
+ *       <NavigationMenuLink href="/products/analytics">Analytics</NavigationMenuLink>
+ *       <NavigationMenuLink href="/products/dashboard">Dashboard</NavigationMenuLink>
+ *     </div>
+ *   </NavigationMenuContent>
+ * </NavigationMenuItem>
  * ```
  *
  * @example
  * ```tsx
- * // With custom button styling using asChild
+ * // Custom trigger styling with asChild
  * <NavigationMenuTrigger asChild>
- *   <Button variant="outline">Custom Trigger</Button>
+ *   <Button variant="outline" size="lg">
+ *     Custom Features Button
+ *   </Button>
  * </NavigationMenuTrigger>
  * ```
  *
- * @accessibility
- * - Automatic ARIA expanded state management
- * - Keyboard activation with Enter/Space keys
- * - Focus visible indicator for keyboard navigation
- * - Screen reader accessible button semantics
+ * @example
+ * ```tsx
+ * // Trigger with additional icons
+ * <NavigationMenuTrigger className="gap-2">
+ *   <StarIcon className="size-4" />
+ *   Featured Items
+ * </NavigationMenuTrigger>
+ * ```
  *
- * @param className - Additional CSS classes for styling
- * @param children - Button content (text, icons, etc.)
+ * @accessibility
+ * - Automatic ARIA expanded state management (expanded="true/false")
+ * - Button role with proper keyboard activation (Enter/Space keys)
+ * - Focus visible ring indicator for keyboard navigation
+ * - Screen reader accessible button semantics and state announcements
+ * - Disabled state handling with pointer-events and opacity
+ * - Chevron icon marked as aria-hidden for screen reader exclusion
+ *
+ * @see {@link NavigationMenuContent} Content panel this trigger controls
+ * @see {@link NavigationMenuItem} Required parent container
+ * @see {@link navigationMenuTriggerStyle} Styling function used internally
  * @since 1.0.0
  */
 function NavigationMenuTrigger({
@@ -257,43 +469,109 @@ function NavigationMenuTrigger({
 }
 
 /**
- * NavigationMenuContent - Dropdown content panel for navigation menu
+ * Props for NavigationMenuContent 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 NavigationMenuContentDocsProps = {
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior */
+  asChild?: boolean;
+  /** Used to force mounting when more control is needed. Useful when controlling animation with external libraries */
+  forceMount?: boolean;
+  /** Event handler called when the escape key is down. Can be prevented by calling event.preventDefault */
+  onEscapeKeyDown?: (event: KeyboardEvent) => void;
+  /** Event handler called when a pointer event occurs outside the bounds of the component. Can be prevented by calling event.preventDefault */
+  onPointerDownOutside?: (event: PointerEvent) => void;
+  /** Event handler called when focus moves outside the bounds of the component. Can be prevented by calling event.preventDefault */
+  onFocusOutside?: (event: FocusEvent) => void;
+  /** Event handler called when an interaction (pointer or focus) happens outside the component. Can be prevented by calling event.preventDefault */
+  onInteractOutside?: (event: PointerEvent | FocusEvent) => void;
+} & React.ComponentProps<"div">;
+
+/**
+ * NavigationMenuContent - Dropdown content panel for navigation items
  *
- * The content container that appears when a NavigationMenuTrigger is activated.
- * Supports enter/exit animations, responsive positioning, and flexible layouts.
- * Can be styled differently based on the viewport prop setting.
+ * The collapsible content container that appears when a NavigationMenuTrigger is activated.
+ * Supports smooth enter/exit animations, flexible positioning (with or without viewport),
+ * and comprehensive interaction handling. The content automatically manages focus and
+ * provides multiple ways to dismiss the dropdown (Escape key, outside clicks, etc.).
  *
- * @component
  * @example
  * ```tsx
+ * // Grid layout with navigation links
  * <NavigationMenuContent>
- *   <div className="grid gap-3 p-6 w-[400px]">
- *     <NavigationMenuLink href="/feature1">Feature 1</NavigationMenuLink>
- *     <NavigationMenuLink href="/feature2">Feature 2</NavigationMenuLink>
+ *   <div className="grid gap-3 p-6 w-[500px] grid-cols-2">
+ *     <NavigationMenuLink href="/products/analytics">
+ *       <div className="text-sm font-medium">Analytics</div>
+ *       <p className="text-sm text-muted-foreground">Track your performance</p>
+ *     </NavigationMenuLink>
+ *     <NavigationMenuLink href="/products/dashboard">
+ *       <div className="text-sm font-medium">Dashboard</div>
+ *       <p className="text-sm text-muted-foreground">Manage your data</p>
+ *     </NavigationMenuLink>
  *   </div>
  * </NavigationMenuContent>
  * ```
  *
  * @example
  * ```tsx
- * // Complex layout with sections
+ * // Complex multi-column layout
  * <NavigationMenuContent>
- *   <div className="grid gap-6 p-6 w-[600px] grid-cols-3">
- *     <div>
- *       <h4>Analytics</h4>
- *       <NavigationMenuLink href="/dashboard">Dashboard</NavigationMenuLink>
+ *   <div className="grid gap-6 p-8 w-[800px] grid-cols-3">
+ *     <div className="space-y-2">
+ *       <h4 className="text-sm font-medium">Features</h4>
+ *       <NavigationMenuLink href="/features/auth">Authentication</NavigationMenuLink>
+ *       <NavigationMenuLink href="/features/api">API Management</NavigationMenuLink>
+ *     </div>
+ *     <div className="space-y-2">
+ *       <h4 className="text-sm font-medium">Tools</h4>
+ *       <NavigationMenuLink href="/tools/cli">Command Line</NavigationMenuLink>
+ *       <NavigationMenuLink href="/tools/sdk">SDK</NavigationMenuLink>
  *     </div>
  *   </div>
  * </NavigationMenuContent>
  * ```
  *
- * @accessibility
- * - Automatic focus management when opened
- * - Escape key support for closing
- * - Proper ARIA labeling and relationships
+ * @example
+ * ```tsx
+ * // With custom interaction handlers
+ * <NavigationMenuContent
+ *   onEscapeKeyDown={(e) => {
+ *     console.log('Escape pressed');
+ *     // Don't prevent default to allow normal closing behavior
+ *   }}
+ *   onPointerDownOutside={(e) => {
+ *     console.log('Clicked outside');
+ *     // e.preventDefault() would prevent closing
+ *   }}
+ * >
+ *   <div className="p-6 w-[300px]">
+ *     <NavigationMenuLink href="/help">Help Center</NavigationMenuLink>
+ *   </div>
+ * </NavigationMenuContent>
+ * ```
  *
- * @param className - Additional CSS classes for styling
- * @param children - Content to display in the dropdown (links, layouts, etc.)
+ * @example
+ * ```tsx
+ * // Force mounted for animation control
+ * <NavigationMenuContent forceMount>
+ *   <div className="p-4 w-[250px] animate-in slide-in-from-top">
+ *     <NavigationMenuLink href="/docs">Documentation</NavigationMenuLink>
+ *   </div>
+ * </NavigationMenuContent>
+ * ```
+ *
+ * @accessibility
+ * - Automatic focus management when content opens and closes
+ * - Escape key support for dismissing dropdown (can be customized via onEscapeKeyDown)
+ * - Outside interaction handling for dismissing (clicks and focus outside)
+ * - Proper ARIA relationships with trigger button
+ * - Content is accessible via keyboard navigation within the dropdown
+ * - Screen reader announcements for state changes
+ *
+ * @see {@link NavigationMenuTrigger} Button that controls this content
+ * @see {@link NavigationMenuLink} Links typically used within content
+ * @see {@link NavigationMenuViewport} Viewport container for positioning
  * @since 1.0.0
  */
 function NavigationMenuContent({
@@ -305,7 +583,7 @@ function NavigationMenuContent({
       data-slot="navigation-menu-content"
       className={cn(
         "data-[motion^=from-]:animate-in data-[motion^=to-]:animate-out data-[motion^=from-]:fade-in data-[motion^=to-]:fade-out data-[motion=from-end]:slide-in-from-right-52 data-[motion=from-start]:slide-in-from-left-52 data-[motion=to-end]:slide-out-to-right-52 data-[motion=to-start]:slide-out-to-left-52 top-0 left-0 w-full p-2 pr-2.5 md:absolute md:w-auto",
-        "group-data-[viewport=false]/navigation-menu:bg-popover group-data-[viewport=false]/navigation-menu:text-popover-foreground group-data-[viewport=false]/navigation-menu:data-[state=open]:animate-in group-data-[viewport=false]/navigation-menu:data-[state=closed]:animate-out group-data-[viewport=false]/navigation-menu:data-[state=closed]:zoom-out-95 group-data-[viewport=false]/navigation-menu:data-[state=open]:zoom-in-95 group-data-[viewport=false]/navigation-menu:data-[state=open]:fade-in-0 group-data-[viewport=false]/navigation-menu:data-[state=closed]:fade-out-0 group-data-[viewport=false]/navigation-menu:top-full group-data-[viewport=false]/navigation-menu:mt-1.5 group-data-[viewport=false]/navigation-menu:overflow-hidden group-data-[viewport=false]/navigation-menu:rounded-md group-data-[viewport=false]/navigation-menu:border group-data-[viewport=false]/navigation-menu:shadow group-data-[viewport=false]/navigation-menu:duration-200 **:data-[slot=navigation-menu-link]:focus:ring-0 **:data-[slot=navigation-menu-link]:focus:outline-none",
+        "group-data-[viewport=false]/navigation-menu:bg-popover group-data-[viewport=false]/navigation-menu:text-popover-foreground group-data-[viewport=false]/navigation-menu:data-[state=open]:animate-in group-data-[viewport=false]/navigation-menu:data-[state=closed]:animate-out group-data-[viewport=false]/navigation-menu:data-[state=closed]:zoom-out-95 group-data-[viewport=false]/navigation-menu:data-[state=open]:zoom-in-95 group-data-[viewport=false]/navigation-menu:data-[state=open]:fade-in-0 group-data-[viewport=false]/navigation-menu:data-[state=closed]:fade-out-0 group-data-[viewport=false]/navigation-menu:top-full group-data-[viewport=false]/navigation-menu:mt-1.5 group-data-[viewport=false]/navigation-menu:overflow-hidden group-data-[viewport=false]/navigation-menu:rounded-md group-data-[viewport=false]/navigation-menu:border group-data-[viewport=false]/navigation-menu:shadow group-data-[viewport=false]/navigation-menu:duration-200 [&_[data-slot=navigation-menu-link]]:focus:ring-0 [&_[data-slot=navigation-menu-link]]:focus:outline-none",
         className,
       )}
       {...props}
@@ -314,20 +592,56 @@ function NavigationMenuContent({
 }
 
 /**
- * NavigationMenuViewport - Viewport container for dropdown content positioning
+ * Props for NavigationMenuViewport 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 NavigationMenuViewportDocsProps = {
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior */
+  asChild?: boolean;
+  /** Used to force mounting when more control is needed. Useful when controlling animation with external libraries */
+  forceMount?: boolean;
+} & React.ComponentProps<"div">;
+
+/**
+ * NavigationMenuViewport - Positioned container for dropdown content
  *
- * Manages the positioning, sizing, and animation of NavigationMenuContent panels.
- * Automatically adjusts dimensions based on content size and provides smooth
- * enter/exit animations. Only rendered when viewport prop is true on NavigationMenu.
+ * The viewport container that manages positioning, sizing, and animation of NavigationMenuContent
+ * panels. It automatically calculates dimensions based on content size and provides smooth
+ * enter/exit animations. The viewport uses CSS custom properties for dynamic sizing and
+ * positioning. Only rendered when the viewport prop is true (default) on NavigationMenu.
+ *
+ * @example
+ * ```tsx
+ * // Typically used automatically by NavigationMenu
+ * <NavigationMenu>
+ *   <NavigationMenuList>
+ *     // menu items
+ *   </NavigationMenuList>
+ *   // NavigationMenuViewport is rendered automatically
+ * </NavigationMenu>
+ * ```
  *
- * @component
- * @internal This component is typically not used directly by consumers
+ * @example
+ * ```tsx
+ * // Custom viewport styling
+ * <NavigationMenuViewport className="border-2 border-primary shadow-xl" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Force mounted viewport for animation control
+ * <NavigationMenuViewport forceMount className="custom-animation" />
+ * ```
  *
  * @accessibility
- * - Handles focus containment for dropdown content
- * - Manages viewport announcements for screen readers
+ * - Handles focus containment for dropdown content within the viewport
+ * - Manages viewport size announcements for screen readers
+ * - Provides proper z-index layering for dropdown content
+ * - Maintains content visibility and accessibility during animations
  *
- * @param className - Additional CSS classes for styling
+ * @see {@link NavigationMenu} Parent component that controls viewport rendering
+ * @see {@link NavigationMenuContent} Content rendered within this viewport
  * @since 1.0.0
  */
 function NavigationMenuViewport({
@@ -352,54 +666,120 @@ function NavigationMenuViewport({
   );
 }
 
+/**
+ * Props for NavigationMenuLink component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+type NavigationMenuLinkDocsProps = {
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior */
+  asChild?: boolean;
+  /** Whether the link is currently active/selected. Used for highlighting current page @default false */
+  active?: boolean;
+  /** Event handler called when the link is selected (clicked or activated) */
+  onSelect?: (event: Event) => void;
+} & React.ComponentProps<"a">;
+
 /**
  * NavigationMenuLink - Styled link component for navigation menus
  *
- * A link component designed specifically for navigation menus. Supports active
- * states, hover effects, and the asChild pattern for framework integration.
- * Can be used both within dropdown content and as direct navigation items.
+ * A versatile link component designed specifically for navigation menus with comprehensive
+ * styling and state management. Supports active states, hover/focus effects, and seamless
+ * framework integration through the asChild pattern. Can be used both within dropdown
+ * content and as direct navigation items. Features proper keyboard navigation and
+ * accessibility support.
  *
- * @component
  * @example
  * ```tsx
- * // Direct navigation link
+ * // Basic navigation link
  * <NavigationMenuLink href="/about">About Us</NavigationMenuLink>
  * ```
  *
  * @example
  * ```tsx
- * // With Next.js Link using asChild
+ * // Active link with current page styling
+ * <NavigationMenuLink href="/dashboard" active>
+ *   Dashboard
+ * </NavigationMenuLink>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Rich content link in dropdown with description
+ * <NavigationMenuLink href="/features/analytics">
+ *   <div className="text-sm font-medium leading-none">Analytics</div>
+ *   <p className="text-sm text-muted-foreground mt-1">
+ *     View detailed insights and performance metrics
+ *   </p>
+ * </NavigationMenuLink>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Next.js Link using asChild pattern
  * <NavigationMenuLink asChild>
- *   <Link href="/products">Products</Link>
+ *   <Link href="/products" prefetch={false}>
+ *     Products
+ *   </Link>
  * </NavigationMenuLink>
  * ```
  *
  * @example
  * ```tsx
- * // In dropdown content with description
- * <NavigationMenuLink href="/analytics">
- *   <div className="text-sm font-medium">Analytics</div>
- *   <p className="text-sm text-muted-foreground">View your data insights</p>
+ * // With Remix Link using asChild pattern
+ * <NavigationMenuLink asChild>
+ *   <RemixLink to="/docs" prefetch="intent">
+ *     Documentation
+ *   </RemixLink>
  * </NavigationMenuLink>
  * ```
  *
  * @example
  * ```tsx
- * // With trigger styling for direct navigation
- * <NavigationMenuLink href="/docs" className={navigationMenuTriggerStyle()}>
- *   Documentation
+ * // Direct navigation with trigger button styling
+ * <NavigationMenuLink
+ *   href="/contact"
+ *   className={navigationMenuTriggerStyle()}
+ * >
+ *   Contact Us
+ * </NavigationMenuLink>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom selection handler
+ * <NavigationMenuLink
+ *   href="/logout"
+ *   onSelect={(event) => {
+ *     event.preventDefault();
+ *     handleLogout();
+ *   }}
+ * >
+ *   Sign Out
+ * </NavigationMenuLink>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // External link with icon
+ * <NavigationMenuLink href="https://github.com" target="_blank" rel="noopener">
+ *   <GitHubIcon className="size-4" />
+ *   GitHub
+ *   <ExternalLinkIcon className="size-3 ml-auto" />
  * </NavigationMenuLink>
  * ```
  *
  * @accessibility
- * - Focus visible ring for keyboard navigation
- * - Active state styling for current page indication
- * - Proper link semantics and ARIA attributes
- * - Keyboard activation support (Enter key)
- * - Screen reader compatible text content
- *
- * @param className - Additional CSS classes for styling
- * @param children - Link content (text, elements, descriptions)
+ * - Focus visible ring indicator for keyboard navigation (3px ring with outline)
+ * - Active state styling with proper contrast for current page indication
+ * - Proper link semantics and ARIA attributes (including aria-current when active)
+ * - Keyboard activation support (Enter key) and tab navigation
+ * - Screen reader compatible text content and descriptions
+ * - Icon sizing and color inheritance for consistent visual hierarchy
+ * - External link indicators and proper rel attributes for security
+ *
+ * @see {@link NavigationMenuContent} Content container where links are often used
+ * @see {@link NavigationMenuItem} Item container for direct navigation links
+ * @see {@link navigationMenuTriggerStyle} Styling function for button-like appearance
  * @since 1.0.0
  */
 function NavigationMenuLink({
@@ -419,25 +799,74 @@ function NavigationMenuLink({
 }
 
 /**
- * NavigationMenuIndicator - Visual indicator for active menu item
+ * Props for NavigationMenuIndicator component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+type NavigationMenuIndicatorDocsProps = {
+  /** Change the default rendered element for the one passed as a child, merging their props and behavior */
+  asChild?: boolean;
+  /** Used to force mounting when more control is needed. Useful when controlling animation with external libraries */
+  forceMount?: boolean;
+} & React.ComponentProps<"div">;
+
+/**
+ * NavigationMenuIndicator - Animated visual indicator for active menu items
+ *
+ * An optional visual indicator that displays an animated arrow pointing to the currently
+ * active or focused navigation menu item. Automatically transitions between positions as
+ * users navigate through menu items, providing clear visual feedback about the current
+ * selection. The indicator appears below the active item and includes smooth fade and
+ * position animations.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage within NavigationMenuList
+ * <NavigationMenuList>
+ *   <NavigationMenuItem value="home">
+ *     <NavigationMenuTrigger>Home</NavigationMenuTrigger>
+ *     <NavigationMenuContent>
+ *       <NavigationMenuLink href="/">Homepage</NavigationMenuLink>
+ *     </NavigationMenuContent>
+ *   </NavigationMenuItem>
+ *   <NavigationMenuItem value="about">
+ *     <NavigationMenuTrigger>About</NavigationMenuTrigger>
+ *     <NavigationMenuContent>
+ *       <NavigationMenuLink href="/about">About Us</NavigationMenuLink>
+ *     </NavigationMenuContent>
+ *   </NavigationMenuItem>
+ *   <NavigationMenuIndicator className="data-[state=visible]:bg-primary" />
+ * </NavigationMenuList>
+ * ```
  *
- * Displays an animated arrow indicator that points to the currently active
- * or hovered navigation menu item. Automatically transitions between positions
- * as users navigate through menu items, providing visual feedback.
+ * @example
+ * ```tsx
+ * // Custom styled indicator
+ * <NavigationMenuIndicator className="
+ *   data-[state=visible]:animate-pulse
+ *   data-[state=visible]:bg-gradient-to-r
+ *   data-[state=visible]:from-blue-500
+ *   data-[state=visible]:to-purple-500
+ * " />
+ * ```
  *
- * @component
  * @example
  * ```tsx
- * // Typically used automatically, but can be customized
- * <NavigationMenuIndicator className="custom-indicator-styles" />
+ * // Force mounted indicator for custom animations
+ * <NavigationMenuIndicator
+ *   forceMount
+ *   className="custom-indicator-animation"
+ * />
  * ```
  *
  * @accessibility
- * - Purely decorative visual element
- * - Does not interfere with screen reader navigation
- * - Hidden from assistive technologies (aria-hidden)
- *
- * @param className - Additional CSS classes for custom indicator styling
+ * - Purely decorative visual element that enhances UX
+ * - Does not interfere with keyboard or screen reader navigation
+ * - Arrow element is properly hidden from assistive technologies
+ * - Does not affect focus management or navigation behavior
+ * - Provides visual feedback that complements accessible navigation patterns
+ *
+ * @see {@link NavigationMenuList} Container where indicator is typically placed
+ * @see {@link NavigationMenuItem} Items that the indicator highlights
  * @since 1.0.0
  */
 function NavigationMenuIndicator({