@neynar/ui 0.3.1 → 0.5.0

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

@@ -1,277 +1,46 @@
-import * as React from "react";
-import * as NavigationMenuPrimitive from "@radix-ui/react-navigation-menu";
+import { NavigationMenu as NavigationMenuPrimitive } from "@base-ui/react/navigation-menu";
 import { cva } from "class-variance-authority";
-import { ChevronDownIcon } from "lucide-react";
 
 import { cn } from "@/lib/utils";
+import { ChevronDownIcon } from "lucide-react";
 
-/**
- * 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">;
+type NavigationMenuProps = NavigationMenuPrimitive.Root.Props;
 
 /**
- * NavigationMenu - A collection of links for navigating websites
- *
- * 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.
- *
- * @example
- * ```tsx
- * // Basic navigation with dropdown
- * <NavigationMenu>
- *   <NavigationMenuList>
- *     <NavigationMenuItem value="products">
- *       <NavigationMenuTrigger>Products</NavigationMenuTrigger>
- *       <NavigationMenuContent>
- *         <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>
- * </NavigationMenu>
- * ```
- *
- * @example
- * ```tsx
- * // Simple navigation links without dropdowns
- * <NavigationMenu>
- *   <NavigationMenuList>
- *     <NavigationMenuItem>
- *       <NavigationMenuLink href="/about" className={navigationMenuTriggerStyle()}>
- *         About
- *       </NavigationMenuLink>
- *     </NavigationMenuItem>
- *     <NavigationMenuItem>
- *       <NavigationMenuLink href="/contact" className={navigationMenuTriggerStyle()}>
- *         Contact
- *       </NavigationMenuLink>
- *     </NavigationMenuItem>
- *   </NavigationMenuList>
- * </NavigationMenu>
- * ```
- *
- * @example
- * ```tsx
- * // With Next.js Link integration using asChild
- * <NavigationMenu>
- *   <NavigationMenuList>
- *     <NavigationMenuItem>
- *       <NavigationMenuLink asChild className={navigationMenuTriggerStyle()}>
- *         <Link href="/dashboard">Dashboard</Link>
- *       </NavigationMenuLink>
- *     </NavigationMenuItem>
- *   </NavigationMenuList>
- * </NavigationMenu>
- * ```
- *
- * @example
- * ```tsx
- * // 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 value="docs">
- *       <NavigationMenuTrigger>Documentation</NavigationMenuTrigger>
- *       <NavigationMenuContent>
- *         <div className="bg-white border rounded-lg shadow-lg p-6 w-[500px]">
- *           <NavigationMenuLink href="/docs/getting-started">Getting Started</NavigationMenuLink>
- *         </div>
- *       </NavigationMenuContent>
- *     </NavigationMenuItem>
- *   </NavigationMenuList>
- * </NavigationMenu>
- * ```
- *
- * @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
+ * Root container for horizontal navigation with mega menu support.
+ * Manages active state and provides keyboard navigation.
  */
 function NavigationMenu({
   className,
   children,
-  viewport = true,
   ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.Root> & {
-  /** Whether to render the navigation viewport container for dropdown content positioning. @default true */
-  viewport?: boolean;
-}) {
+}: NavigationMenuProps) {
   return (
     <NavigationMenuPrimitive.Root
       data-slot="navigation-menu"
-      data-viewport={viewport}
       className={cn(
-        "group/navigation-menu relative flex max-w-max flex-1 items-center justify-center",
+        "max-w-max group/navigation-menu relative flex max-w-max flex-1 items-center justify-center",
         className,
       )}
       {...props}
     >
       {children}
-      {viewport && <NavigationMenuViewport />}
+      <NavigationMenuPositioner />
     </NavigationMenuPrimitive.Root>
   );
 }
 
-/**
- * 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">;
+type NavigationMenuListProps = NavigationMenuPrimitive.List.Props;
 
 /**
- * NavigationMenuList - Container for navigation menu items
- *
- * 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.
- *
- * @example
- * ```tsx
- * <NavigationMenuList>
- *   <NavigationMenuItem value="products">
- *     <NavigationMenuTrigger>Products</NavigationMenuTrigger>
- *     <NavigationMenuContent>
- *       <NavigationMenuLink href="/products">All Products</NavigationMenuLink>
- *     </NavigationMenuContent>
- *   </NavigationMenuItem>
- *   <NavigationMenuItem>
- *     <NavigationMenuLink href="/about" className={navigationMenuTriggerStyle()}>
- *       About
- *     </NavigationMenuLink>
- *   </NavigationMenuItem>
- * </NavigationMenuList>
- * ```
- *
- * @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
+ * Container for navigation menu items. Renders as a horizontal list.
  */
-function NavigationMenuList({
-  className,
-  ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.List>) {
+function NavigationMenuList({ className, ...props }: NavigationMenuListProps) {
   return (
     <NavigationMenuPrimitive.List
       data-slot="navigation-menu-list"
       className={cn(
-        "group flex flex-1 list-none items-center justify-center gap-1",
+        "gap-0 group flex flex-1 list-none items-center justify-center",
         className,
       )}
       {...props}
@@ -279,76 +48,13 @@ 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">;
+type NavigationMenuItemProps = NavigationMenuPrimitive.Item.Props;
 
 /**
- * NavigationMenuItem - Individual navigation menu item container
- *
- * 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.
- *
- * @example
- * ```tsx
- * // Dropdown navigation item with controlled value
- * <NavigationMenuItem value="products">
- *   <NavigationMenuTrigger>Products</NavigationMenuTrigger>
- *   <NavigationMenuContent>
- *     <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 navigation link item
- * <NavigationMenuItem>
- *   <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>
- * ```
- *
- * @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
+ * Individual navigation item. Can contain a Link or Trigger + Content.
+ * Use `value` prop to identify the item for controlled state.
  */
-function NavigationMenuItem({
-  className,
-  ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.Item>) {
+function NavigationMenuItem({ className, ...props }: NavigationMenuItemProps) {
   return (
     <NavigationMenuPrimitive.Item
       data-slot="navigation-menu-item"
@@ -358,101 +64,21 @@ 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",
+  "bg-background hover:bg-muted focus:bg-muted data-open:hover:bg-muted data-open:focus:bg-muted data-open:bg-muted/50 focus-visible:ring-ring/50 data-popup-open:bg-muted/50 data-popup-open:hover:bg-muted rounded-md px-4 py-2 text-sm font-medium transition-all focus-visible:ring-[3px] focus-visible:outline-1 disabled:opacity-50 group/navigation-menu-trigger inline-flex h-9 w-max items-center justify-center disabled:pointer-events-none outline-none",
 );
 
-/**
- * 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">;
+type NavigationMenuTriggerProps = NavigationMenuPrimitive.Trigger.Props;
 
 /**
- * NavigationMenuTrigger - Interactive button that opens dropdown navigation content
- *
- * 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.
- *
- * @example
- * ```tsx
- * // 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
- * // Custom trigger styling with asChild
- * <NavigationMenuTrigger asChild>
- *   <Button variant="outline" size="lg">
- *     Custom Features Button
- *   </Button>
- * </NavigationMenuTrigger>
- * ```
- *
- * @example
- * ```tsx
- * // Trigger with additional icons
- * <NavigationMenuTrigger className="gap-2">
- *   <StarIcon className="size-4" />
- *   Featured Items
- * </NavigationMenuTrigger>
- * ```
- *
- * @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
+ * Button that opens the associated NavigationMenuContent panel.
+ * Automatically includes a rotating chevron icon.
  */
 function NavigationMenuTrigger({
   className,
   children,
   ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.Trigger>) {
+}: NavigationMenuTriggerProps) {
   return (
     <NavigationMenuPrimitive.Trigger
       data-slot="navigation-menu-trigger"
@@ -461,129 +87,28 @@ function NavigationMenuTrigger({
     >
       {children}{" "}
       <ChevronDownIcon
-        className="relative top-[1px] ml-1 size-3 transition duration-300 group-data-[state=open]:rotate-180"
+        className="relative top-[1px] ml-1 size-3 transition duration-300 group-data-open/navigation-menu-trigger:rotate-180 group-data-popup-open/navigation-menu-trigger:rotate-180"
         aria-hidden="true"
       />
     </NavigationMenuPrimitive.Trigger>
   );
 }
 
-/**
- * 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">;
+type NavigationMenuContentProps = NavigationMenuPrimitive.Content.Props;
 
 /**
- * NavigationMenuContent - Dropdown content panel for navigation items
- *
- * 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.).
- *
- * @example
- * ```tsx
- * // Grid layout with navigation links
- * <NavigationMenuContent>
- *   <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 multi-column layout
- * <NavigationMenuContent>
- *   <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>
- * ```
- *
- * @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>
- * ```
- *
- * @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
+ * Content panel for mega menus. Opened by NavigationMenuTrigger.
+ * Automatically renders in a positioned popup with smooth transitions.
  */
 function NavigationMenuContent({
   className,
   ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.Content>) {
+}: NavigationMenuContentProps) {
   return (
     <NavigationMenuPrimitive.Content
       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",
+        "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 group-data-[viewport=false]/navigation-menu:bg-popover group-data-[viewport=false]/navigation-menu:text-popover-foreground group-data-[viewport=false]/navigation-menu:data-open:animate-in group-data-[viewport=false]/navigation-menu:data-closed:animate-out group-data-[viewport=false]/navigation-menu:data-closed:zoom-out-95 group-data-[viewport=false]/navigation-menu:data-open:zoom-in-95 group-data-[viewport=false]/navigation-menu:data-open:fade-in-0 group-data-[viewport=false]/navigation-menu:data-closed:fade-out-0 group-data-[viewport=false]/navigation-menu:ring-foreground/10 p-2 pr-2.5 ease-[cubic-bezier(0.22,1,0.36,1)] group-data-[viewport=false]/navigation-menu:rounded-md group-data-[viewport=false]/navigation-menu:shadow group-data-[viewport=false]/navigation-menu:ring-1 group-data-[viewport=false]/navigation-menu:duration-300 h-full w-auto **:data-[slot=navigation-menu-link]:focus:ring-0 **:data-[slot=navigation-menu-link]:focus:outline-none",
         className,
       )}
       {...props}
@@ -591,206 +116,57 @@ function NavigationMenuContent({
   );
 }
 
-/**
- * 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">;
+type NavigationMenuPositionerProps = NavigationMenuPrimitive.Positioner.Props;
 
 /**
- * NavigationMenuViewport - Positioned container for dropdown content
- *
- * 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>
- * ```
- *
- * @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 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
- *
- * @see {@link NavigationMenu} Parent component that controls viewport rendering
- * @see {@link NavigationMenuContent} Content rendered within this viewport
- * @since 1.0.0
+ * Portal container for positioning content panels.
+ * Automatically included in NavigationMenu - do not use directly.
+ * @internal
  */
-function NavigationMenuViewport({
+function NavigationMenuPositioner({
   className,
+  side = "bottom",
+  sideOffset = 8,
+  align = "start",
+  alignOffset = 0,
   ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.Viewport>) {
+}: NavigationMenuPositionerProps) {
   return (
-    <div
-      className={cn(
-        "absolute top-full left-0 isolate z-50 flex justify-center",
-      )}
-    >
-      <NavigationMenuPrimitive.Viewport
-        data-slot="navigation-menu-viewport"
+    <NavigationMenuPrimitive.Portal>
+      <NavigationMenuPrimitive.Positioner
+        side={side}
+        sideOffset={sideOffset}
+        align={align}
+        alignOffset={alignOffset}
         className={cn(
-          "origin-top-center bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-90 relative mt-1.5 h-[var(--radix-navigation-menu-viewport-height)] w-full overflow-hidden rounded-md border shadow md:w-[var(--radix-navigation-menu-viewport-width)]",
+          "transition-[top,left,right,bottom] duration-300 ease-[cubic-bezier(0.22,1,0.36,1)] data-[side=bottom]:before:top-[-10px] data-[side=bottom]:before:right-0 data-[side=bottom]:before:left-0 isolate z-50 h-[var(--positioner-height)] w-[var(--positioner-width)] max-w-[var(--available-width)] data-[instant]:transition-none",
           className,
         )}
         {...props}
-      />
-    </div>
+      >
+        <NavigationMenuPrimitive.Popup
+          data-slot="navigation-menu-popup"
+          className="bg-popover text-popover-foreground ring-foreground/10 rounded-lg shadow ring-1 transition-all ease-[cubic-bezier(0.22,1,0.36,1)] outline-none data-[ending-style]:scale-90 data-[ending-style]:opacity-0 data-[ending-style]:duration-150 data-[starting-style]:scale-90 data-[starting-style]:opacity-0 xs:w-(--popup-width) relative h-(--popup-height) w-(--popup-width) origin-(--transform-origin)"
+        >
+          <NavigationMenuPrimitive.Viewport className="relative size-full overflow-hidden" />
+        </NavigationMenuPrimitive.Popup>
+      </NavigationMenuPrimitive.Positioner>
+    </NavigationMenuPrimitive.Portal>
   );
 }
 
-/**
- * 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">;
+type NavigationMenuLinkProps = NavigationMenuPrimitive.Link.Props;
 
 /**
- * NavigationMenuLink - Styled link component for navigation menus
- *
- * 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.
- *
- * @example
- * ```tsx
- * // Basic navigation link
- * <NavigationMenuLink href="/about">About Us</NavigationMenuLink>
- * ```
- *
- * @example
- * ```tsx
- * // 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" prefetch={false}>
- *     Products
- *   </Link>
- * </NavigationMenuLink>
- * ```
- *
- * @example
- * ```tsx
- * // With Remix Link using asChild pattern
- * <NavigationMenuLink asChild>
- *   <RemixLink to="/docs" prefetch="intent">
- *     Documentation
- *   </RemixLink>
- * </NavigationMenuLink>
- * ```
- *
- * @example
- * ```tsx
- * // 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 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
+ * Navigation link for direct navigation items or links within content panels.
+ * Use `active` prop to highlight the current page.
  */
-function NavigationMenuLink({
-  className,
-  ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.Link>) {
+function NavigationMenuLink({ className, ...props }: NavigationMenuLinkProps) {
   return (
     <NavigationMenuPrimitive.Link
       data-slot="navigation-menu-link"
       className={cn(
-        "data-[active=true]:focus:bg-accent data-[active=true]:hover:bg-accent data-[active=true]:bg-accent/50 data-[active=true]:text-accent-foreground hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground focus-visible:ring-ring/50 [&_svg:not([class*='text-'])]:text-muted-foreground flex flex-col gap-1 rounded-sm p-2 text-sm transition-all outline-none focus-visible:ring-[3px] focus-visible:outline-1 [&_svg:not([class*='size-'])]:size-4",
+        "data-[active=true]:focus:bg-muted data-[active=true]:hover:bg-muted data-[active=true]:bg-muted/50 focus-visible:ring-ring/50 hover:bg-muted focus:bg-muted flex items-center gap-1.5 rounded-sm p-2 text-sm transition-all outline-none focus-visible:ring-[3px] focus-visible:outline-1 [&_svg:not([class*='size-'])]:size-4",
         className,
       )}
       {...props}
@@ -798,83 +174,18 @@ function NavigationMenuLink({
   );
 }
 
-/**
- * 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">;
+type NavigationMenuIndicatorProps = NavigationMenuPrimitive.Icon.Props;
 
 /**
- * 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>
- * ```
- *
- * @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
- * " />
- * ```
- *
- * @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
+ * Visual indicator (arrow) that shows which item is active.
+ * Optional - not commonly used in modern designs.
  */
 function NavigationMenuIndicator({
   className,
   ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.Indicator>) {
+}: NavigationMenuIndicatorProps) {
   return (
-    <NavigationMenuPrimitive.Indicator
+    <NavigationMenuPrimitive.Icon
       data-slot="navigation-menu-indicator"
       className={cn(
         "data-[state=visible]:animate-in data-[state=hidden]:animate-out data-[state=hidden]:fade-out data-[state=visible]:fade-in top-full z-[1] flex h-1.5 items-end justify-center overflow-hidden",
@@ -882,19 +193,27 @@ function NavigationMenuIndicator({
       )}
       {...props}
     >
-      <div className="bg-border relative top-[60%] h-2 w-2 rotate-45 rounded-tl-sm shadow-md" />
-    </NavigationMenuPrimitive.Indicator>
+      <div className="bg-border rounded-tl-sm shadow-md relative top-[60%] h-2 w-2 rotate-45" />
+    </NavigationMenuPrimitive.Icon>
   );
 }
 
 export {
   NavigationMenu,
-  NavigationMenuList,
-  NavigationMenuItem,
   NavigationMenuContent,
-  NavigationMenuTrigger,
-  NavigationMenuLink,
   NavigationMenuIndicator,
-  NavigationMenuViewport,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  NavigationMenuTrigger,
   navigationMenuTriggerStyle,
+  NavigationMenuPositioner,
+  type NavigationMenuProps,
+  type NavigationMenuContentProps,
+  type NavigationMenuIndicatorProps,
+  type NavigationMenuItemProps,
+  type NavigationMenuLinkProps,
+  type NavigationMenuListProps,
+  type NavigationMenuTriggerProps,
+  type NavigationMenuPositionerProps,
 };