@neynar/ui 0.1.1 → 0.1.2

package/dist/components/ui/navigation-menu.d.ts

@@ -3,20 +3,40 @@ import * as NavigationMenuPrimitive from "@radix-ui/react-navigation-menu";
 /**
  * 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>
+ * </NavigationMenu>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 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>
@@ -25,14 +45,18 @@ import * as NavigationMenuPrimitive from "@radix-ui/react-navigation-menu";
  *
  * @example
  * ```tsx
- * // Simple navigation links
+ * // 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>
@@ -40,11 +64,11 @@ import * as NavigationMenuPrimitive from "@radix-ui/react-navigation-menu";
  *
  * @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>
@@ -54,14 +78,32 @@ import * as NavigationMenuPrimitive from "@radix-ui/react-navigation-menu";
  *
  * @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>
@@ -69,248 +111,523 @@ import * as NavigationMenuPrimitive from "@radix-ui/react-navigation-menu";
  * </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
- */
 declare function NavigationMenu({ className, children, viewport, ...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;
 }): import("react/jsx-runtime").JSX.Element;
 /**
  * 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
  */
 declare function NavigationMenuList({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.List>): import("react/jsx-runtime").JSX.Element;
 /**
  * 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>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom container element using asChild
+ * <NavigationMenuItem asChild>
+ *   <div className="custom-menu-item">
+ *     <NavigationMenuLink href="/about">About</NavigationMenuLink>
+ *   </div>
  * </NavigationMenuItem>
  * ```
  *
- * @param className - Additional CSS classes for styling
+ * @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
  */
 declare function NavigationMenuItem({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Item>): import("react/jsx-runtime").JSX.Element;
+/**
+ * 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
+ */
 declare const navigationMenuTriggerStyle: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
 /**
- * NavigationMenuTrigger - Button that opens dropdown navigation content
+ * 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
  */
 declare function NavigationMenuTrigger({ className, children, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Trigger>): import("react/jsx-runtime").JSX.Element;
 /**
- * NavigationMenuContent - Dropdown content panel for navigation menu
+ * 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>
+ * ```
+ *
+ * @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>
+ * ```
  *
- * @param className - Additional CSS classes for styling
- * @param children - Content to display in the dropdown (links, layouts, etc.)
+ * @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
  */
 declare function NavigationMenuContent({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
 /**
- * NavigationMenuViewport - Viewport container for dropdown content positioning
+ * 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.
  *
- * @component
- * @internal This component is typically not used directly by consumers
+ * @example
+ * ```tsx
+ * // Typically used automatically by NavigationMenu
+ * <NavigationMenu>
+ *   <NavigationMenuList>
+ *     // menu items
+ *   </NavigationMenuList>
+ *   // NavigationMenuViewport is rendered automatically
+ * </NavigationMenu>
+ * ```
+ *
+ * @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
  */
 declare function NavigationMenuViewport({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Viewport>): import("react/jsx-runtime").JSX.Element;
 /**
  * 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
  */
 declare function NavigationMenuLink({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Link>): import("react/jsx-runtime").JSX.Element;
 /**
- * NavigationMenuIndicator - Visual indicator for active menu item
+ * NavigationMenuIndicator - Animated visual indicator for active menu items
  *
- * 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.
+ * 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.
  *
- * @component
  * @example
  * ```tsx
- * // Typically used automatically, but can be customized
- * <NavigationMenuIndicator className="custom-indicator-styles" />
+ * // 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>
  * ```
  *
- * @accessibility
- * - Purely decorative visual element
- * - Does not interfere with screen reader navigation
- * - Hidden from assistive technologies (aria-hidden)
+ * @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
+ * " />
+ * ```
  *
- * @param className - Additional CSS classes for custom indicator styling
+ * @example
+ * ```tsx
+ * // Force mounted indicator for custom animations
+ * <NavigationMenuIndicator
+ *   forceMount
+ *   className="custom-indicator-animation"
+ * />
+ * ```
+ *
+ * @accessibility
+ * - 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
  */
 declare function NavigationMenuIndicator({ className, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Indicator>): import("react/jsx-runtime").JSX.Element;