@neynar/ui 0.1.1

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

@@ -0,0 +1,471 @@
+import * as React from "react";
+import * as NavigationMenuPrimitive from "@radix-ui/react-navigation-menu";
+import { cva } from "class-variance-authority";
+import { ChevronDownIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * 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.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic navigation with dropdown
+ * <NavigationMenu>
+ *   <NavigationMenuList>
+ *     <NavigationMenuItem>
+ *       <NavigationMenuTrigger>Products</NavigationMenuTrigger>
+ *       <NavigationMenuContent>
+ *         <NavigationMenuLink href="/products">All Products</NavigationMenuLink>
+ *       </NavigationMenuContent>
+ *     </NavigationMenuItem>
+ *   </NavigationMenuList>
+ * </NavigationMenu>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Simple navigation links
+ * <NavigationMenu>
+ *   <NavigationMenuList>
+ *     <NavigationMenuItem>
+ *       <NavigationMenuLink href="/about">About</NavigationMenuLink>
+ *     </NavigationMenuItem>
+ *     <NavigationMenuItem>
+ *       <NavigationMenuLink href="/contact">Contact</NavigationMenuLink>
+ *     </NavigationMenuItem>
+ *   </NavigationMenuList>
+ * </NavigationMenu>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Next.js Link using asChild
+ * <NavigationMenu>
+ *   <NavigationMenuList>
+ *     <NavigationMenuItem>
+ *       <NavigationMenuLink asChild>
+ *         <Link href="/dashboard">Dashboard</Link>
+ *       </NavigationMenuLink>
+ *     </NavigationMenuItem>
+ *   </NavigationMenuList>
+ * </NavigationMenu>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Without viewport for simpler styling
+ * <NavigationMenu viewport={false}>
+ *   <NavigationMenuList>
+ *     <NavigationMenuItem>
+ *       <NavigationMenuTrigger>Features</NavigationMenuTrigger>
+ *       <NavigationMenuContent>
+ *         <div className="p-4 w-[300px]">
+ *           <NavigationMenuLink href="/analytics">Analytics</NavigationMenuLink>
+ *         </div>
+ *       </NavigationMenuContent>
+ *     </NavigationMenuItem>
+ *   </NavigationMenuList>
+ * </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
+ *
+ * @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 */
+  viewport?: boolean;
+}) {
+  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",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      {viewport && <NavigationMenuViewport />}
+    </NavigationMenuPrimitive.Root>
+  );
+}
+
+/**
+ * NavigationMenuList - Container for navigation menu items
+ *
+ * A horizontal list container that groups NavigationMenuItem components.
+ * Provides the foundational layout structure for the navigation menu.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <NavigationMenuList>
+ *   <NavigationMenuItem>
+ *     <NavigationMenuLink href="/home">Home</NavigationMenuLink>
+ *   </NavigationMenuItem>
+ *   <NavigationMenuItem>
+ *     <NavigationMenuLink href="/about">About</NavigationMenuLink>
+ *   </NavigationMenuItem>
+ * </NavigationMenuList>
+ * ```
+ *
+ * @param className - Additional CSS classes for styling
+ * @since 1.0.0
+ */
+function NavigationMenuList({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.List>) {
+  return (
+    <NavigationMenuPrimitive.List
+      data-slot="navigation-menu-list"
+      className={cn(
+        "group flex flex-1 list-none items-center justify-center gap-1",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 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
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // With dropdown content
+ * <NavigationMenuItem>
+ *   <NavigationMenuTrigger>Products</NavigationMenuTrigger>
+ *   <NavigationMenuContent>
+ *     <NavigationMenuLink href="/products/all">All Products</NavigationMenuLink>
+ *   </NavigationMenuContent>
+ * </NavigationMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Simple link
+ * <NavigationMenuItem>
+ *   <NavigationMenuLink href="/contact">Contact</NavigationMenuLink>
+ * </NavigationMenuItem>
+ * ```
+ *
+ * @param className - Additional CSS classes for styling
+ * @since 1.0.0
+ */
+function NavigationMenuItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Item>) {
+  return (
+    <NavigationMenuPrimitive.Item
+      data-slot="navigation-menu-item"
+      className={cn("relative", className)}
+      {...props}
+    />
+  );
+}
+
+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
+ *
+ * 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.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <NavigationMenuTrigger>Features</NavigationMenuTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom button styling using asChild
+ * <NavigationMenuTrigger asChild>
+ *   <Button variant="outline">Custom Trigger</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
+ *
+ * @param className - Additional CSS classes for styling
+ * @param children - Button content (text, icons, etc.)
+ * @since 1.0.0
+ */
+function NavigationMenuTrigger({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Trigger>) {
+  return (
+    <NavigationMenuPrimitive.Trigger
+      data-slot="navigation-menu-trigger"
+      className={cn(navigationMenuTriggerStyle(), "group", className)}
+      {...props}
+    >
+      {children}{" "}
+      <ChevronDownIcon
+        className="relative top-[1px] ml-1 size-3 transition duration-300 group-data-[state=open]:rotate-180"
+        aria-hidden="true"
+      />
+    </NavigationMenuPrimitive.Trigger>
+  );
+}
+
+/**
+ * NavigationMenuContent - Dropdown content panel for navigation menu
+ *
+ * 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.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <NavigationMenuContent>
+ *   <div className="grid gap-3 p-6 w-[400px]">
+ *     <NavigationMenuLink href="/feature1">Feature 1</NavigationMenuLink>
+ *     <NavigationMenuLink href="/feature2">Feature 2</NavigationMenuLink>
+ *   </div>
+ * </NavigationMenuContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex layout with sections
+ * <NavigationMenuContent>
+ *   <div className="grid gap-6 p-6 w-[600px] grid-cols-3">
+ *     <div>
+ *       <h4>Analytics</h4>
+ *       <NavigationMenuLink href="/dashboard">Dashboard</NavigationMenuLink>
+ *     </div>
+ *   </div>
+ * </NavigationMenuContent>
+ * ```
+ *
+ * @accessibility
+ * - Automatic focus management when opened
+ * - Escape key support for closing
+ * - Proper ARIA labeling and relationships
+ *
+ * @param className - Additional CSS classes for styling
+ * @param children - Content to display in the dropdown (links, layouts, etc.)
+ * @since 1.0.0
+ */
+function NavigationMenuContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Content>) {
+  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",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * NavigationMenuViewport - Viewport container for dropdown content positioning
+ *
+ * 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.
+ *
+ * @component
+ * @internal This component is typically not used directly by consumers
+ *
+ * @accessibility
+ * - Handles focus containment for dropdown content
+ * - Manages viewport announcements for screen readers
+ *
+ * @param className - Additional CSS classes for styling
+ * @since 1.0.0
+ */
+function NavigationMenuViewport({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Viewport>) {
+  return (
+    <div
+      className={cn(
+        "absolute top-full left-0 isolate z-50 flex justify-center",
+      )}
+    >
+      <NavigationMenuPrimitive.Viewport
+        data-slot="navigation-menu-viewport"
+        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)]",
+          className,
+        )}
+        {...props}
+      />
+    </div>
+  );
+}
+
+/**
+ * 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.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Direct navigation link
+ * <NavigationMenuLink href="/about">About Us</NavigationMenuLink>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Next.js Link using asChild
+ * <NavigationMenuLink asChild>
+ *   <Link href="/products">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>
+ * </NavigationMenuLink>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With trigger styling for direct navigation
+ * <NavigationMenuLink href="/docs" className={navigationMenuTriggerStyle()}>
+ *   Documentation
+ * </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)
+ * @since 1.0.0
+ */
+function NavigationMenuLink({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Link>) {
+  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",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * NavigationMenuIndicator - Visual indicator for active menu item
+ *
+ * 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.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Typically used automatically, but can be customized
+ * <NavigationMenuIndicator className="custom-indicator-styles" />
+ * ```
+ *
+ * @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
+ * @since 1.0.0
+ */
+function NavigationMenuIndicator({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Indicator>) {
+  return (
+    <NavigationMenuPrimitive.Indicator
+      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",
+        className,
+      )}
+      {...props}
+    >
+      <div className="bg-border relative top-[60%] h-2 w-2 rotate-45 rounded-tl-sm shadow-md" />
+    </NavigationMenuPrimitive.Indicator>
+  );
+}
+
+export {
+  NavigationMenu,
+  NavigationMenuList,
+  NavigationMenuItem,
+  NavigationMenuContent,
+  NavigationMenuTrigger,
+  NavigationMenuLink,
+  NavigationMenuIndicator,
+  NavigationMenuViewport,
+  navigationMenuTriggerStyle,
+};