@justin_evo/evo-ui 1.1.0 → 1.2.1

package/src/TopNav/TopNav.tsx

@@ -1,994 +1,1163 @@
-// EvoTopNav — compose-based top navigation with a mobile drawer, polymorphic
-// items, and dropdown sub-menus.
-//
-// Research notes (CLAUDE.md §2):
-//  - Radix Navigation Menu — adopted the compose + `asChild` slot pattern.
-//  - Mantine AppShell.Header — kept Burger / drawer as a separate sub-component
-//    so the header itself stays a thin layout primitive.
-//  - shadcn Navigation Menu — confirmed the same compose shape works without
-//    any runtime dependency.
-
-import React, {
-  forwardRef,
-  useCallback,
-  useEffect,
-  useId,
-  useLayoutEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
-import styles from '../css/topnav.module.scss';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface EvoTopNavProps
-  extends Omit<React.HTMLAttributes<HTMLElement>, 'onChange'> {
-  children: React.ReactNode;
-  open?: boolean;
-  defaultOpen?: boolean;
-  onOpenChange?: (open: boolean) => void;
-  /** Width in px below which Menu collapses into the drawer. @default 768 */
-  collapseBelow?: number;
-  className?: string;
-}
-
-export interface EvoTopNavBrandProps
-  extends React.HTMLAttributes<HTMLDivElement> {
-  children: React.ReactNode;
-  className?: string;
-}
-
-export interface EvoTopNavMenuProps
-  extends React.HTMLAttributes<HTMLUListElement> {
-  children: React.ReactNode;
-  className?: string;
-}
-
-export interface EvoTopNavItemProps {
-  children: React.ReactNode;
-  active?: boolean;
-  icon?: React.ReactNode;
-  href?: string;
-  target?: '_self' | '_blank' | '_parent' | '_top';
-  rel?: string;
-  onClick?: (e: React.MouseEvent) => void;
-  asChild?: boolean;
-  className?: string;
-}
-
-export interface EvoTopNavActionsProps
-  extends React.HTMLAttributes<HTMLDivElement> {
-  children: React.ReactNode;
-  className?: string;
-}
-
-export interface EvoTopNavToggleProps
-  extends Omit<
-    React.ButtonHTMLAttributes<HTMLButtonElement>,
-    'aria-expanded' | 'aria-controls'
-  > {
-  icon?: React.ReactNode;
-  className?: string;
-}
-
-export interface EvoTopNavDropdownProps {
-  label: React.ReactNode;
-  icon?: React.ReactNode;
-  active?: boolean;
-  hoverable?: boolean;
-  open?: boolean;
-  defaultOpen?: boolean;
-  onOpenChange?: (open: boolean) => void;
-  children: React.ReactNode;
-  className?: string;
-}
-
-export interface EvoTopNavDropdownItemProps {
-  children: React.ReactNode;
-  icon?: React.ReactNode;
-  active?: boolean;
-  href?: string;
-  target?: '_self' | '_blank' | '_parent' | '_top';
-  rel?: string;
-  onClick?: (e: React.MouseEvent) => void;
-  asChild?: boolean;
-  className?: string;
-}
-
-// ============================================================================
-// Internal helpers
-// ============================================================================
-
-const cn = (...c: Array<string | false | null | undefined>) =>
-  c.filter(Boolean).join(' ');
-
-function composeHandlers<E extends React.SyntheticEvent>(
-  ours?: (e: E) => void,
-  theirs?: (e: E) => void,
-) {
-  return (e: E) => {
-    ours?.(e);
-    if (!e.defaultPrevented) theirs?.(e);
-  };
-}
-
-function useControllableState<T>(opts: {
-  value?: T;
-  defaultValue: T;
-  onChange?: (v: T) => void;
-}) {
-  const { value, defaultValue, onChange } = opts;
-  const [internal, setInternal] = useState<T>(defaultValue);
-  const isControlled = value !== undefined;
-  const current = isControlled ? (value as T) : internal;
-  const setValue = useCallback(
-    (next: T) => {
-      if (!isControlled) setInternal(next);
-      onChange?.(next);
-    },
-    [isControlled, onChange],
-  );
-  return [current, setValue] as const;
-}
-
-const useIsoLayoutEffect =
-  typeof window !== 'undefined' ? useLayoutEffect : useEffect;
-
-function useMediaQuery(query: string, fallback = false) {
-  const [matches, setMatches] = useState(fallback);
-  useIsoLayoutEffect(() => {
-    if (typeof window === 'undefined' || !window.matchMedia) return;
-    const mql = window.matchMedia(query);
-    const update = () => setMatches(mql.matches);
-    update();
-    mql.addEventListener?.('change', update);
-    return () => mql.removeEventListener?.('change', update);
-  }, [query]);
-  return matches;
-}
-
-const useIsCollapsed = (breakpoint: number) =>
-  useMediaQuery(`(max-width: ${breakpoint - 1}px)`);
-
-const useHoverCapable = () =>
-  useMediaQuery('(hover: hover) and (pointer: fine)', true);
-
-const usePrefersReducedMotion = () =>
-  useMediaQuery('(prefers-reduced-motion: reduce)');
-
-function getFocusable(root: HTMLElement | null) {
-  if (!root) return [] as HTMLElement[];
-  return Array.from(
-    root.querySelectorAll<HTMLElement>(
-      'a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"]), input:not([disabled]), select:not([disabled]), textarea:not([disabled])',
-    ),
-  ).filter(
-    (el) =>
-      !el.hasAttribute('aria-hidden') &&
-      el.offsetParent !== null,
-  );
-}
-
-// ============================================================================
-// Slot — minimal Radix-style asChild implementation (single child)
-// ============================================================================
-
-interface SlotProps extends React.HTMLAttributes<HTMLElement> {
-  children: React.ReactNode;
-}
-
-const Slot = forwardRef<HTMLElement, SlotProps>(function Slot(
-  { children, ...slotProps },
-  _ref,
-) {
-  const child = React.Children.only(children) as React.ReactElement<
-    Record<string, unknown>
-  >;
-  const childProps = (child.props ?? {}) as Record<string, unknown>;
-
-  const merged: Record<string, unknown> = { ...slotProps, ...childProps };
-
-  // className: parent first, child appended
-  merged.className = cn(
-    slotProps.className as string | undefined,
-    childProps.className as string | undefined,
-  );
-
-  // style: shallow merge — child wins on key collisions
-  if (slotProps.style || childProps.style) {
-    merged.style = {
-      ...(slotProps.style as React.CSSProperties),
-      ...(childProps.style as React.CSSProperties),
-    };
-  }
-
-  // Compose event handlers (every on* prop on the slot)
-  for (const key of Object.keys(slotProps)) {
-    if (
-      key.startsWith('on') &&
-      typeof (slotProps as Record<string, unknown>)[key] === 'function'
-    ) {
-      const ours = (slotProps as Record<string, unknown>)[key] as (
-        e: React.SyntheticEvent,
-      ) => void;
-      const theirs = childProps[key] as
-        | ((e: React.SyntheticEvent) => void)
-        | undefined;
-      merged[key] = composeHandlers(ours, theirs);
-    }
-  }
-
-  return React.cloneElement(child, merged);
-});
-
-// ============================================================================
-// Context
-// ============================================================================
-
-interface TopNavContextValue {
-  drawerOpen: boolean;
-  setDrawerOpen: (open: boolean) => void;
-  isCollapsed: boolean;
-  menuId: string;
-  toggleId: string;
-  registerToggle: () => () => void;
-  toggleCount: number;
-  menuRef: React.RefObject<HTMLUListElement | null>;
-  toggleRef: React.RefObject<HTMLButtonElement | null>;
-}
-
-const TopNavContext = React.createContext<TopNavContextValue | null>(null);
-
-function useTopNavContext(component: string) {
-  const ctx = React.useContext(TopNavContext);
-  if (!ctx) {
-    throw new Error(
-      `EvoTopNav.${component} must be rendered inside <EvoTopNav>.`,
-    );
-  }
-  return ctx;
-}
-
-interface DropdownContextValue {
-  open: boolean;
-  setOpen: (open: boolean) => void;
-  triggerRef: React.RefObject<HTMLButtonElement | null>;
-  contentRef: React.RefObject<HTMLUListElement | null>;
-  contentId: string;
-  focusItem: (delta: 1 | -1 | 'first' | 'last') => void;
-  inDrawer: boolean;
-}
-
-const DropdownContext = React.createContext<DropdownContextValue | null>(null);
-
-// ============================================================================
-// Default icons
-// ============================================================================
-
-const HamburgerIcon = ({ open }: { open: boolean }) => (
-  <svg
-    width="18"
-    height="18"
-    viewBox="0 0 18 18"
-    fill="none"
-    aria-hidden="true"
-    className={styles.toggleIcon}
-  >
-    {open ? (
-      <>
-        <path
-          d="M4 4l10 10M14 4L4 14"
-          stroke="currentColor"
-          strokeWidth="1.75"
-          strokeLinecap="round"
-        />
-      </>
-    ) : (
-      <>
-        <path
-          d="M3 5h12M3 9h12M3 13h12"
-          stroke="currentColor"
-          strokeWidth="1.75"
-          strokeLinecap="round"
-        />
-      </>
-    )}
-  </svg>
-);
-
-const ChevronIcon = ({ open }: { open: boolean }) => (
-  <svg
-    viewBox="0 0 12 12"
-    width="10"
-    height="10"
-    fill="none"
-    aria-hidden="true"
-    className={cn(styles.dropdownChevron, open && styles.dropdownChevronOpen)}
-  >
-    <path
-      d="M3 4.5l3 3 3-3"
-      stroke="currentColor"
-      strokeWidth="1.5"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    />
-  </svg>
-);
-
-// ============================================================================
-// EvoTopNav.Brand
-// ============================================================================
-
-const EvoTopNavBrand = forwardRef<HTMLDivElement, EvoTopNavBrandProps>(
-  function EvoTopNavBrand({ children, className, ...rest }, ref) {
-    return (
-      <div
-        ref={ref}
-        className={cn(styles.topNavBrand, className)}
-        {...rest}
-      >
-        {children}
-      </div>
-    );
-  },
-);
-
-// ============================================================================
-// EvoTopNav.Menu
-// ============================================================================
-
-const EvoTopNavMenu = forwardRef<HTMLUListElement, EvoTopNavMenuProps>(
-  function EvoTopNavMenu({ children, className, ...rest }, forwardedRef) {
-    const ctx = useTopNavContext('Menu');
-    const localRef = useRef<HTMLUListElement | null>(null);
-
-    const setRef = (node: HTMLUListElement | null) => {
-      localRef.current = node;
-      ctx.menuRef.current = node;
-      if (typeof forwardedRef === 'function') forwardedRef(node);
-      else if (forwardedRef)
-        (forwardedRef as React.RefObject<HTMLUListElement | null>).current = node;
-    };
-
-    const hasToggle = ctx.toggleCount > 0;
-    const inDrawer = ctx.isCollapsed && hasToggle;
-    const drawerClosed = inDrawer && !ctx.drawerOpen;
-
-    return (
-      <ul
-        ref={setRef}
-        id={ctx.menuId}
-        className={cn(
-          styles.topNavMenu,
-          inDrawer && styles.topNavMenuDrawer,
-          drawerClosed && styles.topNavMenuDrawerClosed,
-          ctx.isCollapsed && !hasToggle && styles.topNavMenuScroll,
-          className,
-        )}
-        data-state={inDrawer ? (ctx.drawerOpen ? 'open' : 'closed') : 'inline'}
-        aria-hidden={drawerClosed || undefined}
-        {...rest}
-      >
-        {children}
-      </ul>
-    );
-  },
-);
-
-// ============================================================================
-// EvoTopNav.Item — polymorphic
-// ============================================================================
-
-const EvoTopNavItem = forwardRef<HTMLElement, EvoTopNavItemProps>(
-  function EvoTopNavItem(
-    { children, active, icon, href, target, rel, onClick, asChild, className },
-    ref,
-  ) {
-    const ctx = React.useContext(TopNavContext);
-    const inDrawerCtx = !!ctx && ctx.isCollapsed && ctx.drawerOpen;
-
-    // Auto-close drawer on activation (SPA route nav heuristic).
-    const handleActivation = (e: React.MouseEvent) => {
-      onClick?.(e);
-      if (!e.defaultPrevented && inDrawerCtx) ctx.setDrawerOpen(false);
-    };
-
-    const shared = {
-      className: cn(styles.topNavItem, active && styles.topNavItemActive, className),
-      'aria-current': active ? ('page' as const) : undefined,
-      'data-active': active || undefined,
-    };
-
-    const content = (
-      <>
-        {icon && (
-          <span className={styles.topNavIcon} aria-hidden="true">
-            {icon}
-          </span>
-        )}
-        <span className={styles.topNavItemLabel}>{children}</span>
-      </>
-    );
-
-    let element: React.ReactElement;
-
-    if (asChild) {
-      element = (
-        <Slot
-          {...shared}
-          onClick={handleActivation}
-          ref={ref as React.Ref<HTMLElement>}
-        >
-          {children}
-        </Slot>
-      );
-    } else if (href) {
-      element = (
-        <a
-          ref={ref as React.Ref<HTMLAnchorElement>}
-          href={href}
-          target={target}
-          rel={
-            rel ?? (target === '_blank' ? 'noopener noreferrer' : undefined)
-          }
-          onClick={handleActivation}
-          {...shared}
-        >
-          {content}
-        </a>
-      );
-    } else {
-      element = (
-        <button
-          ref={ref as React.Ref<HTMLButtonElement>}
-          type="button"
-          onClick={handleActivation}
-          {...shared}
-        >
-          {content}
-        </button>
-      );
-    }
-
-    return <li className={styles.topNavItemRow}>{element}</li>;
-  },
-);
-
-// ============================================================================
-// EvoTopNav.Actions
-// ============================================================================
-
-const EvoTopNavActions = forwardRef<HTMLDivElement, EvoTopNavActionsProps>(
-  function EvoTopNavActions({ children, className, ...rest }, ref) {
-    return (
-      <div
-        ref={ref}
-        className={cn(styles.topNavActions, className)}
-        {...rest}
-      >
-        {children}
-      </div>
-    );
-  },
-);
-
-// ============================================================================
-// EvoTopNav.Toggle — hamburger
-// ============================================================================
-
-const EvoTopNavToggle = forwardRef<HTMLButtonElement, EvoTopNavToggleProps>(
-  function EvoTopNavToggle(
-    { icon, className, onClick, 'aria-label': ariaLabel, ...rest },
-    forwardedRef,
-  ) {
-    const ctx = useTopNavContext('Toggle');
-    const localRef = useRef<HTMLButtonElement | null>(null);
-
-    useEffect(() => ctx.registerToggle(), [ctx]);
-
-    const setRef = (node: HTMLButtonElement | null) => {
-      localRef.current = node;
-      ctx.toggleRef.current = node;
-      if (typeof forwardedRef === 'function') forwardedRef(node);
-      else if (forwardedRef)
-        (forwardedRef as React.RefObject<HTMLButtonElement | null>).current = node;
-    };
-
-    const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
-      onClick?.(e);
-      if (!e.defaultPrevented) ctx.setDrawerOpen(!ctx.drawerOpen);
-    };
-
-    return (
-      <button
-        ref={setRef}
-        id={ctx.toggleId}
-        type="button"
-        className={cn(styles.topNavToggle, className)}
-        aria-expanded={ctx.drawerOpen}
-        aria-controls={ctx.menuId}
-        aria-label={
-          ariaLabel ?? (ctx.drawerOpen ? 'Close menu' : 'Open menu')
-        }
-        onClick={handleClick}
-        {...rest}
-      >
-        {icon ?? <HamburgerIcon open={ctx.drawerOpen} />}
-      </button>
-    );
-  },
-);
-
-// ============================================================================
-// EvoTopNav.Dropdown
-// ============================================================================
-
-const EvoTopNavDropdown: React.FC<EvoTopNavDropdownProps> = ({
-  label,
-  icon,
-  active,
-  hoverable = true,
-  open,
-  defaultOpen = false,
-  onOpenChange,
-  children,
-  className,
-}) => {
-  const ctx = React.useContext(TopNavContext);
-  const inDrawer = !!ctx && ctx.isCollapsed && ctx.toggleCount > 0;
-
-  const [isOpen, setOpen] = useControllableState({
-    value: open,
-    defaultValue: defaultOpen,
-    onChange: onOpenChange,
-  });
-
-  const hoverCapable = useHoverCapable();
-  const allowHover = hoverable && hoverCapable && !inDrawer;
-
-  const triggerRef = useRef<HTMLButtonElement | null>(null);
-  const contentRef = useRef<HTMLUListElement | null>(null);
-  const rootRef = useRef<HTMLLIElement | null>(null);
-  const contentId = useId();
-  const hoverTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  const closeAndRestore = useCallback(() => {
-    setOpen(false);
-    triggerRef.current?.focus();
-  }, [setOpen]);
-
-  // Click outside
-  useEffect(() => {
-    if (!isOpen || inDrawer) return;
-    const onDocDown = (e: MouseEvent) => {
-      const root = rootRef.current;
-      if (root && e.target instanceof Node && !root.contains(e.target)) {
-        setOpen(false);
-      }
-    };
-    document.addEventListener('mousedown', onDocDown);
-    return () => document.removeEventListener('mousedown', onDocDown);
-  }, [isOpen, inDrawer, setOpen]);
-
-  // Escape to close (only desktop dropdown — drawer handles its own Esc)
-  useEffect(() => {
-    if (!isOpen || inDrawer) return;
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') {
-        e.stopPropagation();
-        closeAndRestore();
-      }
-    };
-    document.addEventListener('keydown', onKey);
-    return () => document.removeEventListener('keydown', onKey);
-  }, [isOpen, inDrawer, closeAndRestore]);
-
-  const focusItem = useCallback(
-    (delta: 1 | -1 | 'first' | 'last') => {
-      const items = getFocusable(contentRef.current);
-      if (items.length === 0) return;
-      const activeEl = document.activeElement as HTMLElement | null;
-      const idx = activeEl ? items.indexOf(activeEl) : -1;
-      let next = 0;
-      if (delta === 'first') next = 0;
-      else if (delta === 'last') next = items.length - 1;
-      else if (delta === 1) next = idx < 0 ? 0 : (idx + 1) % items.length;
-      else next = idx < 0 ? items.length - 1 : (idx - 1 + items.length) % items.length;
-      items[next]?.focus();
-    },
-    [],
-  );
-
-  const handleTriggerKey = (e: React.KeyboardEvent<HTMLButtonElement>) => {
-    if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') {
-      e.preventDefault();
-      setOpen(true);
-      requestAnimationFrame(() => focusItem('first'));
-    } else if (e.key === 'ArrowUp') {
-      e.preventDefault();
-      setOpen(true);
-      requestAnimationFrame(() => focusItem('last'));
-    }
-  };
-
-  const handleContentKey = (e: React.KeyboardEvent<HTMLUListElement>) => {
-    if (e.key === 'ArrowDown') {
-      e.preventDefault();
-      focusItem(1);
-    } else if (e.key === 'ArrowUp') {
-      e.preventDefault();
-      focusItem(-1);
-    } else if (e.key === 'Home') {
-      e.preventDefault();
-      focusItem('first');
-    } else if (e.key === 'End') {
-      e.preventDefault();
-      focusItem('last');
-    } else if (e.key === 'Tab') {
-      // Allow Tab to leave the dropdown; close it.
-      setOpen(false);
-    }
-  };
-
-  const onMouseEnter = () => {
-    if (!allowHover) return;
-    if (hoverTimer.current) clearTimeout(hoverTimer.current);
-    setOpen(true);
-  };
-  const onMouseLeave = () => {
-    if (!allowHover) return;
-    if (hoverTimer.current) clearTimeout(hoverTimer.current);
-    hoverTimer.current = setTimeout(() => setOpen(false), 120);
-  };
-
-  const dropdownCtx = useMemo<DropdownContextValue>(
-    () => ({
-      open: isOpen,
-      setOpen,
-      triggerRef,
-      contentRef,
-      contentId,
-      focusItem,
-      inDrawer,
-    }),
-    [isOpen, setOpen, contentId, focusItem, inDrawer],
-  );
-
-  return (
-    <DropdownContext.Provider value={dropdownCtx}>
-      <li
-        ref={rootRef}
-        className={cn(
-          styles.topNavDropdown,
-          inDrawer && styles.topNavDropdownInDrawer,
-          isOpen && styles.topNavDropdownOpen,
-          className,
-        )}
-        onMouseEnter={onMouseEnter}
-        onMouseLeave={onMouseLeave}
-      >
-        <button
-          ref={triggerRef}
-          type="button"
-          className={cn(
-            styles.topNavItem,
-            styles.topNavDropdownTrigger,
-            active && styles.topNavItemActive,
-          )}
-          aria-haspopup="menu"
-          aria-expanded={isOpen}
-          aria-controls={contentId}
-          aria-current={active ? 'page' : undefined}
-          onClick={() => setOpen(!isOpen)}
-          onKeyDown={handleTriggerKey}
-        >
-          {icon && (
-            <span className={styles.topNavIcon} aria-hidden="true">
-              {icon}
-            </span>
-          )}
-          <span className={styles.topNavItemLabel}>{label}</span>
-          <ChevronIcon open={isOpen} />
-        </button>
-        <ul
-          ref={contentRef}
-          id={contentId}
-          role="menu"
-          className={cn(
-            styles.topNavDropdownContent,
-            isOpen && styles.topNavDropdownContentOpen,
-          )}
-          // Note: visibility is driven by the .topNavDropdownContentOpen class
-          // (display: none → flex). Avoid the `hidden` attribute because
-          // `[hidden] { display: none }` is overridden by class-level `display`
-          // rules — the two-source-of-truth setup leaked an empty panel onto
-          // the page in v1.
-          aria-hidden={!isOpen || undefined}
-          onKeyDown={handleContentKey}
-        >
-          {children}
-        </ul>
-      </li>
-    </DropdownContext.Provider>
-  );
-};
-
-// ============================================================================
-// EvoTopNav.DropdownItem
-// ============================================================================
-
-const EvoTopNavDropdownItem = forwardRef<HTMLElement, EvoTopNavDropdownItemProps>(
-  function EvoTopNavDropdownItem(
-    { children, icon, active, href, target, rel, onClick, asChild, className },
-    ref,
-  ) {
-    const dropdown = React.useContext(DropdownContext);
-    const top = React.useContext(TopNavContext);
-
-    const handleActivation = (e: React.MouseEvent) => {
-      onClick?.(e);
-      if (!e.defaultPrevented) {
-        dropdown?.setOpen(false);
-        // Also close the drawer if we're inside it.
-        if (top && top.isCollapsed && top.drawerOpen) top.setDrawerOpen(false);
-      }
-    };
-
-    const shared = {
-      className: cn(
-        styles.topNavDropdownItem,
-        active && styles.topNavItemActive,
-        className,
-      ),
-      role: 'menuitem' as const,
-      'aria-current': active ? ('page' as const) : undefined,
-    };
-
-    const content = (
-      <>
-        {icon && (
-          <span className={styles.topNavIcon} aria-hidden="true">
-            {icon}
-          </span>
-        )}
-        <span className={styles.topNavItemLabel}>{children}</span>
-      </>
-    );
-
-    let element: React.ReactElement;
-
-    if (asChild) {
-      element = (
-        <Slot
-          {...shared}
-          onClick={handleActivation}
-          ref={ref as React.Ref<HTMLElement>}
-        >
-          {children}
-        </Slot>
-      );
-    } else if (href) {
-      element = (
-        <a
-          ref={ref as React.Ref<HTMLAnchorElement>}
-          href={href}
-          target={target}
-          rel={rel ?? (target === '_blank' ? 'noopener noreferrer' : undefined)}
-          onClick={handleActivation}
-          {...shared}
-        >
-          {content}
-        </a>
-      );
-    } else {
-      element = (
-        <button
-          ref={ref as React.Ref<HTMLButtonElement>}
-          type="button"
-          onClick={handleActivation}
-          {...shared}
-        >
-          {content}
-        </button>
-      );
-    }
-
-    return <li>{element}</li>;
-  },
-);
-
-// ============================================================================
-// EvoTopNav — root
-// ============================================================================
-
-export const EvoTopNav = forwardRef<HTMLElement, EvoTopNavProps>(
-  function EvoTopNav(
-    {
-      children,
-      open,
-      defaultOpen = false,
-      onOpenChange,
-      collapseBelow = 768,
-      className,
-      ...rest
-    },
-    ref,
-  ) {
-    const [drawerOpen, setDrawerOpen] = useControllableState({
-      value: open,
-      defaultValue: defaultOpen,
-      onChange: onOpenChange,
-    });
-
-    const isCollapsed = useIsCollapsed(collapseBelow);
-    const reducedMotion = usePrefersReducedMotion();
-
-    const [toggleCount, setToggleCount] = useState(0);
-    const registerToggle = useCallback(() => {
-      setToggleCount((c) => c + 1);
-      return () => setToggleCount((c) => Math.max(0, c - 1));
-    }, []);
-
-    const menuId = useId();
-    const toggleId = useId();
-    const menuRef = useRef<HTMLUListElement | null>(null);
-    const toggleRef = useRef<HTMLButtonElement | null>(null);
-    const restoreFocusRef = useRef<HTMLElement | null>(null);
-
-    const drawerActive = isCollapsed && drawerOpen && toggleCount > 0;
-
-    // Close drawer when leaving the collapsed breakpoint.
-    useEffect(() => {
-      if (!isCollapsed && drawerOpen) setDrawerOpen(false);
-    }, [isCollapsed, drawerOpen, setDrawerOpen]);
-
-    // Body scroll lock while drawer is open.
-    useEffect(() => {
-      if (!drawerActive) return;
-      const prev = document.body.style.overflow;
-      document.body.style.overflow = 'hidden';
-      return () => {
-        document.body.style.overflow = prev;
-      };
-    }, [drawerActive]);
-
-    // Esc to close + focus trap inside Menu while drawer is open.
-    useEffect(() => {
-      if (!drawerActive) return;
-      restoreFocusRef.current =
-        (document.activeElement as HTMLElement | null) ?? null;
-
-      const focusFirst = () => {
-        const items = getFocusable(menuRef.current);
-        items[0]?.focus();
-      };
-      const id = requestAnimationFrame(focusFirst);
-
-      const onKey = (e: KeyboardEvent) => {
-        if (e.key === 'Escape') {
-          e.preventDefault();
-          setDrawerOpen(false);
-          return;
-        }
-        if (e.key !== 'Tab' || !menuRef.current) return;
-        const items = getFocusable(menuRef.current);
-        if (items.length === 0) return;
-        const first = items[0];
-        const last = items[items.length - 1];
-        const activeEl = document.activeElement as HTMLElement | null;
-        if (e.shiftKey && activeEl === first) {
-          e.preventDefault();
-          last.focus();
-        } else if (!e.shiftKey && activeEl === last) {
-          e.preventDefault();
-          first.focus();
-        } else if (activeEl && !menuRef.current.contains(activeEl)) {
-          e.preventDefault();
-          first.focus();
-        }
-      };
-      document.addEventListener('keydown', onKey);
-      return () => {
-        cancelAnimationFrame(id);
-        document.removeEventListener('keydown', onKey);
-      };
-    }, [drawerActive, setDrawerOpen]);
-
-    // Restore focus when drawer closes.
-    useEffect(() => {
-      if (drawerActive) return;
-      const target = restoreFocusRef.current;
-      if (target && typeof target.focus === 'function') {
-        // Only restore if focus is currently inside the menu (or nowhere).
-        const active = document.activeElement;
-        if (
-          !active ||
-          active === document.body ||
-          (menuRef.current && menuRef.current.contains(active))
-        ) {
-          target.focus();
-        }
-        restoreFocusRef.current = null;
-      }
-    }, [drawerActive]);
-
-    const ctxValue = useMemo<TopNavContextValue>(
-      () => ({
-        drawerOpen,
-        setDrawerOpen,
-        isCollapsed,
-        menuId,
-        toggleId,
-        registerToggle,
-        toggleCount,
-        menuRef,
-        toggleRef,
-      }),
-      [
-        drawerOpen,
-        setDrawerOpen,
-        isCollapsed,
-        menuId,
-        toggleId,
-        registerToggle,
-        toggleCount,
-      ],
-    );
-
-    return (
-      <TopNavContext.Provider value={ctxValue}>
-        <nav
-          ref={ref}
-          className={cn(
-            styles.topNav,
-            drawerActive && styles.topNavDrawerOpen,
-            reducedMotion && styles.topNavReducedMotion,
-            className,
-          )}
-          data-collapsed={isCollapsed || undefined}
-          data-drawer-open={drawerActive || undefined}
-          {...rest}
-        >
-          <div className={styles.topNavInner}>{children}</div>
-          {drawerActive && (
-            <div
-              className={styles.topNavBackdrop}
-              onClick={() => setDrawerOpen(false)}
-              aria-hidden="true"
-            />
-          )}
-        </nav>
-      </TopNavContext.Provider>
-    );
-  },
-) as React.ForwardRefExoticComponent<
-  EvoTopNavProps & React.RefAttributes<HTMLElement>
-> & {
-  Brand: typeof EvoTopNavBrand;
-  Menu: typeof EvoTopNavMenu;
-  Item: typeof EvoTopNavItem;
-  Actions: typeof EvoTopNavActions;
-  Toggle: typeof EvoTopNavToggle;
-  Dropdown: typeof EvoTopNavDropdown;
-  DropdownItem: typeof EvoTopNavDropdownItem;
-};
-
-EvoTopNavBrand.displayName = 'EvoTopNav.Brand';
-EvoTopNavMenu.displayName = 'EvoTopNav.Menu';
-EvoTopNavItem.displayName = 'EvoTopNav.Item';
-EvoTopNavActions.displayName = 'EvoTopNav.Actions';
-EvoTopNavToggle.displayName = 'EvoTopNav.Toggle';
-EvoTopNavDropdown.displayName = 'EvoTopNav.Dropdown';
-EvoTopNavDropdownItem.displayName = 'EvoTopNav.DropdownItem';
-(EvoTopNav as { displayName?: string }).displayName = 'EvoTopNav';
-
-EvoTopNav.Brand = EvoTopNavBrand;
-EvoTopNav.Menu = EvoTopNavMenu;
-EvoTopNav.Item = EvoTopNavItem;
-EvoTopNav.Actions = EvoTopNavActions;
-EvoTopNav.Toggle = EvoTopNavToggle;
-EvoTopNav.Dropdown = EvoTopNavDropdown;
-EvoTopNav.DropdownItem = EvoTopNavDropdownItem;
+// EvoTopNav — compose-based top navigation with a mobile drawer, polymorphic
+// items, and dropdown sub-menus.
+//
+// Research notes (CLAUDE.md §2):
+//  - Radix Navigation Menu — adopted the compose + `asChild` slot pattern.
+//  - Mantine AppShell.Header — kept Burger / drawer as a separate sub-component
+//    so the header itself stays a thin layout primitive.
+//  - shadcn Navigation Menu — confirmed the same compose shape works without
+//    any runtime dependency.
+
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import styles from '../css/topnav.module.scss';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface EvoTopNavProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, 'onChange'> {
+  children: React.ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Width in px below which Menu collapses into the drawer. @default 768 */
+  collapseBelow?: number;
+  /** Staggered mount animation for the bar's contents. @default 'none' */
+  entrance?: 'none' | 'rise' | 'fade';
+  /** Pin the bar with position: sticky; top: 0. @default false */
+  sticky?: boolean;
+  /** On-scroll treatment of a sticky bar. @default 'none' */
+  scrollBehavior?: 'none' | 'elevate' | 'shrink' | 'hide';
+  /** Render a thin scroll-progress accent line along the bottom edge. @default false */
+  showProgress?: boolean;
+  className?: string;
+}
+
+export interface EvoTopNavBrandProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface EvoTopNavMenuProps
+  extends React.HTMLAttributes<HTMLUListElement> {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface EvoTopNavItemProps {
+  children: React.ReactNode;
+  active?: boolean;
+  icon?: React.ReactNode;
+  href?: string;
+  target?: '_self' | '_blank' | '_parent' | '_top';
+  rel?: string;
+  onClick?: (e: React.MouseEvent) => void;
+  asChild?: boolean;
+  className?: string;
+}
+
+export interface EvoTopNavActionsProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface EvoTopNavToggleProps
+  extends Omit<
+    React.ButtonHTMLAttributes<HTMLButtonElement>,
+    'aria-expanded' | 'aria-controls'
+  > {
+  icon?: React.ReactNode;
+  className?: string;
+}
+
+export interface EvoTopNavSearchProps
+  extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  /** Placeholder text shown inside the trigger. @default 'Search…' */
+  placeholder?: string;
+  /** Opt-in global hotkey, e.g. 'mod+k' (mod = ⌘ on macOS, Ctrl elsewhere). Default: none. */
+  shortcut?: string;
+  /** Override the kbd hint. @default platform-aware ⌘K / Ctrl K */
+  shortcutHint?: React.ReactNode;
+  className?: string;
+}
+
+export interface EvoTopNavDropdownProps {
+  label: React.ReactNode;
+  icon?: React.ReactNode;
+  active?: boolean;
+  hoverable?: boolean;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface EvoTopNavDropdownItemProps {
+  children: React.ReactNode;
+  icon?: React.ReactNode;
+  active?: boolean;
+  href?: string;
+  target?: '_self' | '_blank' | '_parent' | '_top';
+  rel?: string;
+  onClick?: (e: React.MouseEvent) => void;
+  asChild?: boolean;
+  className?: string;
+}
+
+// ============================================================================
+// Internal helpers
+// ============================================================================
+
+const cn = (...c: Array<string | false | null | undefined>) =>
+  c.filter(Boolean).join(' ');
+
+function composeHandlers<E extends React.SyntheticEvent>(
+  ours?: (e: E) => void,
+  theirs?: (e: E) => void,
+) {
+  return (e: E) => {
+    ours?.(e);
+    if (!e.defaultPrevented) theirs?.(e);
+  };
+}
+
+function useControllableState<T>(opts: {
+  value?: T;
+  defaultValue: T;
+  onChange?: (v: T) => void;
+}) {
+  const { value, defaultValue, onChange } = opts;
+  const [internal, setInternal] = useState<T>(defaultValue);
+  const isControlled = value !== undefined;
+  const current = isControlled ? (value as T) : internal;
+  const setValue = useCallback(
+    (next: T) => {
+      if (!isControlled) setInternal(next);
+      onChange?.(next);
+    },
+    [isControlled, onChange],
+  );
+  return [current, setValue] as const;
+}
+
+const useIsoLayoutEffect =
+  typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+
+function useMediaQuery(query: string, fallback = false) {
+  const [matches, setMatches] = useState(fallback);
+  useIsoLayoutEffect(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return;
+    const mql = window.matchMedia(query);
+    const update = () => setMatches(mql.matches);
+    update();
+    mql.addEventListener?.('change', update);
+    return () => mql.removeEventListener?.('change', update);
+  }, [query]);
+  return matches;
+}
+
+const useIsCollapsed = (breakpoint: number) =>
+  useMediaQuery(`(max-width: ${breakpoint - 1}px)`);
+
+const useHoverCapable = () =>
+  useMediaQuery('(hover: hover) and (pointer: fine)', true);
+
+const usePrefersReducedMotion = () =>
+  useMediaQuery('(prefers-reduced-motion: reduce)');
+
+function useScrollState(
+  enabled: boolean,
+  behavior: 'none' | 'elevate' | 'shrink' | 'hide',
+  wantProgress: boolean,
+) {
+  const [scrolled, setScrolled] = useState(false);
+  const [hidden, setHidden] = useState(false);
+  const [progress, setProgress] = useState(0);
+  const lastY = useRef(0);
+
+  useEffect(() => {
+    if (typeof window === 'undefined' || !enabled) {
+      setScrolled(false);
+      setHidden(false);
+      setProgress(0);
+      lastY.current = 0;
+      return;
+    }
+    let raf = 0;
+    const read = () => {
+      raf = 0;
+      const doc = document.documentElement;
+      const y = window.scrollY || doc.scrollTop || 0;
+      setScrolled(y > 8);
+      setHidden(behavior === 'hide' ? y > lastY.current && y > 64 : false);
+      if (wantProgress) {
+        const max = doc.scrollHeight - doc.clientHeight || 1;
+        setProgress(Math.min(1, Math.max(0, y / max)));
+      }
+      lastY.current = y;
+    };
+    const onScroll = () => {
+      if (!raf) raf = requestAnimationFrame(read);
+    };
+    read();
+    window.addEventListener('scroll', onScroll, { passive: true });
+    window.addEventListener('resize', onScroll, { passive: true });
+    return () => {
+      if (raf) cancelAnimationFrame(raf);
+      window.removeEventListener('scroll', onScroll);
+      window.removeEventListener('resize', onScroll);
+    };
+  }, [enabled, behavior, wantProgress]);
+
+  return { scrolled, hidden, progress };
+}
+
+function getFocusable(root: HTMLElement | null) {
+  if (!root) return [] as HTMLElement[];
+  return Array.from(
+    root.querySelectorAll<HTMLElement>(
+      'a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"]), input:not([disabled]), select:not([disabled]), textarea:not([disabled])',
+    ),
+  ).filter(
+    (el) =>
+      !el.hasAttribute('aria-hidden') &&
+      el.offsetParent !== null,
+  );
+}
+
+// ============================================================================
+// Slot — minimal Radix-style asChild implementation (single child)
+// ============================================================================
+
+interface SlotProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+}
+
+const Slot = forwardRef<HTMLElement, SlotProps>(function Slot(
+  { children, ...slotProps },
+  _ref,
+) {
+  const child = React.Children.only(children) as React.ReactElement<
+    Record<string, unknown>
+  >;
+  const childProps = (child.props ?? {}) as Record<string, unknown>;
+
+  const merged: Record<string, unknown> = { ...slotProps, ...childProps };
+
+  // className: parent first, child appended
+  merged.className = cn(
+    slotProps.className as string | undefined,
+    childProps.className as string | undefined,
+  );
+
+  // style: shallow merge — child wins on key collisions
+  if (slotProps.style || childProps.style) {
+    merged.style = {
+      ...(slotProps.style as React.CSSProperties),
+      ...(childProps.style as React.CSSProperties),
+    };
+  }
+
+  // Compose event handlers (every on* prop on the slot)
+  for (const key of Object.keys(slotProps)) {
+    if (
+      key.startsWith('on') &&
+      typeof (slotProps as Record<string, unknown>)[key] === 'function'
+    ) {
+      const ours = (slotProps as Record<string, unknown>)[key] as (
+        e: React.SyntheticEvent,
+      ) => void;
+      const theirs = childProps[key] as
+        | ((e: React.SyntheticEvent) => void)
+        | undefined;
+      merged[key] = composeHandlers(ours, theirs);
+    }
+  }
+
+  return React.cloneElement(child, merged);
+});
+
+// ============================================================================
+// Context
+// ============================================================================
+
+interface TopNavContextValue {
+  drawerOpen: boolean;
+  setDrawerOpen: (open: boolean) => void;
+  isCollapsed: boolean;
+  menuId: string;
+  toggleId: string;
+  registerToggle: () => () => void;
+  toggleCount: number;
+  menuRef: React.RefObject<HTMLUListElement | null>;
+  toggleRef: React.RefObject<HTMLButtonElement | null>;
+}
+
+const TopNavContext = React.createContext<TopNavContextValue | null>(null);
+
+function useTopNavContext(component: string) {
+  const ctx = React.useContext(TopNavContext);
+  if (!ctx) {
+    throw new Error(
+      `EvoTopNav.${component} must be rendered inside <EvoTopNav>.`,
+    );
+  }
+  return ctx;
+}
+
+interface DropdownContextValue {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  triggerRef: React.RefObject<HTMLButtonElement | null>;
+  contentRef: React.RefObject<HTMLUListElement | null>;
+  contentId: string;
+  focusItem: (delta: 1 | -1 | 'first' | 'last') => void;
+  inDrawer: boolean;
+}
+
+const DropdownContext = React.createContext<DropdownContextValue | null>(null);
+
+// ============================================================================
+// Default icons
+// ============================================================================
+
+const HamburgerIcon = ({ open }: { open: boolean }) => (
+  <svg
+    width="18"
+    height="18"
+    viewBox="0 0 18 18"
+    fill="none"
+    aria-hidden="true"
+    className={styles.toggleIcon}
+  >
+    {open ? (
+      <>
+        <path
+          d="M4 4l10 10M14 4L4 14"
+          stroke="currentColor"
+          strokeWidth="1.75"
+          strokeLinecap="round"
+        />
+      </>
+    ) : (
+      <>
+        <path
+          d="M3 5h12M3 9h12M3 13h12"
+          stroke="currentColor"
+          strokeWidth="1.75"
+          strokeLinecap="round"
+        />
+      </>
+    )}
+  </svg>
+);
+
+const ChevronIcon = ({ open }: { open: boolean }) => (
+  <svg
+    viewBox="0 0 12 12"
+    width="10"
+    height="10"
+    fill="none"
+    aria-hidden="true"
+    className={cn(styles.dropdownChevron, open && styles.dropdownChevronOpen)}
+  >
+    <path
+      d="M3 4.5l3 3 3-3"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+const SearchGlyph = () => (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <circle cx="11" cy="11" r="7" />
+    <path d="m20 20-3.2-3.2" />
+  </svg>
+);
+
+// ============================================================================
+// EvoTopNav.Brand
+// ============================================================================
+
+const EvoTopNavBrand = forwardRef<HTMLDivElement, EvoTopNavBrandProps>(
+  function EvoTopNavBrand({ children, className, ...rest }, ref) {
+    return (
+      <div
+        ref={ref}
+        className={cn(styles.topNavBrand, className)}
+        {...rest}
+      >
+        {children}
+      </div>
+    );
+  },
+);
+
+// ============================================================================
+// EvoTopNav.Menu
+// ============================================================================
+
+const EvoTopNavMenu = forwardRef<HTMLUListElement, EvoTopNavMenuProps>(
+  function EvoTopNavMenu({ children, className, ...rest }, forwardedRef) {
+    const ctx = useTopNavContext('Menu');
+    const localRef = useRef<HTMLUListElement | null>(null);
+
+    const setRef = (node: HTMLUListElement | null) => {
+      localRef.current = node;
+      ctx.menuRef.current = node;
+      if (typeof forwardedRef === 'function') forwardedRef(node);
+      else if (forwardedRef)
+        (forwardedRef as React.RefObject<HTMLUListElement | null>).current = node;
+    };
+
+    const hasToggle = ctx.toggleCount > 0;
+    const inDrawer = ctx.isCollapsed && hasToggle;
+    const drawerClosed = inDrawer && !ctx.drawerOpen;
+
+    return (
+      <ul
+        ref={setRef}
+        id={ctx.menuId}
+        className={cn(
+          styles.topNavMenu,
+          inDrawer && styles.topNavMenuDrawer,
+          drawerClosed && styles.topNavMenuDrawerClosed,
+          ctx.isCollapsed && !hasToggle && styles.topNavMenuScroll,
+          className,
+        )}
+        data-state={inDrawer ? (ctx.drawerOpen ? 'open' : 'closed') : 'inline'}
+        aria-hidden={drawerClosed || undefined}
+        {...rest}
+      >
+        {children}
+      </ul>
+    );
+  },
+);
+
+// ============================================================================
+// EvoTopNav.Item — polymorphic
+// ============================================================================
+
+const EvoTopNavItem = forwardRef<HTMLElement, EvoTopNavItemProps>(
+  function EvoTopNavItem(
+    { children, active, icon, href, target, rel, onClick, asChild, className },
+    ref,
+  ) {
+    const ctx = React.useContext(TopNavContext);
+    const inDrawerCtx = !!ctx && ctx.isCollapsed && ctx.drawerOpen;
+
+    // Auto-close drawer on activation (SPA route nav heuristic).
+    const handleActivation = (e: React.MouseEvent) => {
+      onClick?.(e);
+      if (!e.defaultPrevented && inDrawerCtx) ctx.setDrawerOpen(false);
+    };
+
+    const shared = {
+      className: cn(styles.topNavItem, active && styles.topNavItemActive, className),
+      'aria-current': active ? ('page' as const) : undefined,
+      'data-active': active || undefined,
+    };
+
+    const content = (
+      <>
+        {icon && (
+          <span className={styles.topNavIcon} aria-hidden="true">
+            {icon}
+          </span>
+        )}
+        <span className={styles.topNavItemLabel}>{children}</span>
+      </>
+    );
+
+    let element: React.ReactElement;
+
+    if (asChild) {
+      element = (
+        <Slot
+          {...shared}
+          onClick={handleActivation}
+          ref={ref as React.Ref<HTMLElement>}
+        >
+          {children}
+        </Slot>
+      );
+    } else if (href) {
+      element = (
+        <a
+          ref={ref as React.Ref<HTMLAnchorElement>}
+          href={href}
+          target={target}
+          rel={
+            rel ?? (target === '_blank' ? 'noopener noreferrer' : undefined)
+          }
+          onClick={handleActivation}
+          {...shared}
+        >
+          {content}
+        </a>
+      );
+    } else {
+      element = (
+        <button
+          ref={ref as React.Ref<HTMLButtonElement>}
+          type="button"
+          onClick={handleActivation}
+          {...shared}
+        >
+          {content}
+        </button>
+      );
+    }
+
+    return <li className={styles.topNavItemRow}>{element}</li>;
+  },
+);
+
+// ============================================================================
+// EvoTopNav.Actions
+// ============================================================================
+
+const EvoTopNavActions = forwardRef<HTMLDivElement, EvoTopNavActionsProps>(
+  function EvoTopNavActions({ children, className, ...rest }, ref) {
+    return (
+      <div
+        ref={ref}
+        className={cn(styles.topNavActions, className)}
+        {...rest}
+      >
+        {children}
+      </div>
+    );
+  },
+);
+
+// ============================================================================
+// EvoTopNav.Toggle — hamburger
+// ============================================================================
+
+const EvoTopNavToggle = forwardRef<HTMLButtonElement, EvoTopNavToggleProps>(
+  function EvoTopNavToggle(
+    { icon, className, onClick, 'aria-label': ariaLabel, ...rest },
+    forwardedRef,
+  ) {
+    const ctx = useTopNavContext('Toggle');
+    const localRef = useRef<HTMLButtonElement | null>(null);
+
+    useEffect(() => ctx.registerToggle(), [ctx]);
+
+    const setRef = (node: HTMLButtonElement | null) => {
+      localRef.current = node;
+      ctx.toggleRef.current = node;
+      if (typeof forwardedRef === 'function') forwardedRef(node);
+      else if (forwardedRef)
+        (forwardedRef as React.RefObject<HTMLButtonElement | null>).current = node;
+    };
+
+    const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
+      onClick?.(e);
+      if (!e.defaultPrevented) ctx.setDrawerOpen(!ctx.drawerOpen);
+    };
+
+    return (
+      <button
+        ref={setRef}
+        id={ctx.toggleId}
+        type="button"
+        className={cn(styles.topNavToggle, className)}
+        aria-expanded={ctx.drawerOpen}
+        aria-controls={ctx.menuId}
+        aria-label={
+          ariaLabel ?? (ctx.drawerOpen ? 'Close menu' : 'Open menu')
+        }
+        onClick={handleClick}
+        {...rest}
+      >
+        {icon ?? <HamburgerIcon open={ctx.drawerOpen} />}
+      </button>
+    );
+  },
+);
+
+// ============================================================================
+// EvoTopNav.Search — presentational ⌘K quick-search trigger
+// ============================================================================
+
+const EvoTopNavSearch = forwardRef<HTMLButtonElement, EvoTopNavSearchProps>(
+  function EvoTopNavSearch(
+    { placeholder = 'Search…', shortcut, shortcutHint, className, onClick, ...rest },
+    forwardedRef,
+  ) {
+    const localRef = useRef<HTMLButtonElement | null>(null);
+    const setRef = (node: HTMLButtonElement | null) => {
+      localRef.current = node;
+      if (typeof forwardedRef === 'function') forwardedRef(node);
+      else if (forwardedRef)
+        (forwardedRef as React.RefObject<HTMLButtonElement | null>).current = node;
+    };
+
+    // Platform-aware hint resolved after mount to avoid SSR hydration mismatch.
+    const [autoHint, setAutoHint] = useState<React.ReactNode>(null);
+    useEffect(() => {
+      if (shortcutHint !== undefined) return;
+      const platform =
+        (typeof navigator !== 'undefined' &&
+          (navigator.platform || navigator.userAgent)) || '';
+      setAutoHint(/Mac|iPhone|iPad|iPod/.test(platform) ? '⌘K' : 'Ctrl K');
+    }, [shortcutHint]);
+    const hint = shortcutHint !== undefined ? shortcutHint : autoHint;
+
+    // Opt-in global hotkey → dispatch a real click so onClick fires naturally.
+    useEffect(() => {
+      if (!shortcut) return;
+      const parts = shortcut.toLowerCase().split('+').map((p) => p.trim());
+      const wantMod = parts.some((p) => ['mod', 'cmd', 'meta', 'ctrl', 'control'].includes(p));
+      const key = parts[parts.length - 1];
+      const handler = (e: KeyboardEvent) => {
+        const mod = e.metaKey || e.ctrlKey;
+        if ((!wantMod || mod) && e.key.toLowerCase() === key) {
+          e.preventDefault();
+          localRef.current?.click();
+        }
+      };
+      document.addEventListener('keydown', handler);
+      return () => document.removeEventListener('keydown', handler);
+    }, [shortcut]);
+
+    return (
+      <button
+        ref={setRef}
+        className={cn(styles.topNavSearch, className)}
+        onClick={onClick}
+        {...rest}
+        type="button"
+      >
+        <span className={styles.topNavSearchIcon} aria-hidden="true">
+          <SearchGlyph />
+        </span>
+        <span className={styles.topNavSearchText}>{placeholder}</span>
+        {hint != null && <kbd className={styles.topNavSearchKbd}>{hint}</kbd>}
+      </button>
+    );
+  },
+);
+
+// ============================================================================
+// EvoTopNav.Dropdown
+// ============================================================================
+
+const EvoTopNavDropdown: React.FC<EvoTopNavDropdownProps> = ({
+  label,
+  icon,
+  active,
+  hoverable = true,
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  children,
+  className,
+}) => {
+  const ctx = React.useContext(TopNavContext);
+  const inDrawer = !!ctx && ctx.isCollapsed && ctx.toggleCount > 0;
+
+  const [isOpen, setOpen] = useControllableState({
+    value: open,
+    defaultValue: defaultOpen,
+    onChange: onOpenChange,
+  });
+
+  const hoverCapable = useHoverCapable();
+  const allowHover = hoverable && hoverCapable && !inDrawer;
+
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const contentRef = useRef<HTMLUListElement | null>(null);
+  const rootRef = useRef<HTMLLIElement | null>(null);
+  const contentId = useId();
+  const hoverTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const closeAndRestore = useCallback(() => {
+    setOpen(false);
+    triggerRef.current?.focus();
+  }, [setOpen]);
+
+  // Click outside
+  useEffect(() => {
+    if (!isOpen || inDrawer) return;
+    const onDocDown = (e: MouseEvent) => {
+      const root = rootRef.current;
+      if (root && e.target instanceof Node && !root.contains(e.target)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener('mousedown', onDocDown);
+    return () => document.removeEventListener('mousedown', onDocDown);
+  }, [isOpen, inDrawer, setOpen]);
+
+  // Escape to close (only desktop dropdown — drawer handles its own Esc)
+  useEffect(() => {
+    if (!isOpen || inDrawer) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        closeAndRestore();
+      }
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [isOpen, inDrawer, closeAndRestore]);
+
+  const focusItem = useCallback(
+    (delta: 1 | -1 | 'first' | 'last') => {
+      const items = getFocusable(contentRef.current);
+      if (items.length === 0) return;
+      const activeEl = document.activeElement as HTMLElement | null;
+      const idx = activeEl ? items.indexOf(activeEl) : -1;
+      let next = 0;
+      if (delta === 'first') next = 0;
+      else if (delta === 'last') next = items.length - 1;
+      else if (delta === 1) next = idx < 0 ? 0 : (idx + 1) % items.length;
+      else next = idx < 0 ? items.length - 1 : (idx - 1 + items.length) % items.length;
+      items[next]?.focus();
+    },
+    [],
+  );
+
+  const handleTriggerKey = (e: React.KeyboardEvent<HTMLButtonElement>) => {
+    if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      setOpen(true);
+      requestAnimationFrame(() => focusItem('first'));
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setOpen(true);
+      requestAnimationFrame(() => focusItem('last'));
+    }
+  };
+
+  const handleContentKey = (e: React.KeyboardEvent<HTMLUListElement>) => {
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      focusItem(1);
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      focusItem(-1);
+    } else if (e.key === 'Home') {
+      e.preventDefault();
+      focusItem('first');
+    } else if (e.key === 'End') {
+      e.preventDefault();
+      focusItem('last');
+    } else if (e.key === 'Tab') {
+      // Allow Tab to leave the dropdown; close it.
+      setOpen(false);
+    }
+  };
+
+  const onMouseEnter = () => {
+    if (!allowHover) return;
+    if (hoverTimer.current) clearTimeout(hoverTimer.current);
+    setOpen(true);
+  };
+  const onMouseLeave = () => {
+    if (!allowHover) return;
+    if (hoverTimer.current) clearTimeout(hoverTimer.current);
+    hoverTimer.current = setTimeout(() => setOpen(false), 120);
+  };
+
+  const dropdownCtx = useMemo<DropdownContextValue>(
+    () => ({
+      open: isOpen,
+      setOpen,
+      triggerRef,
+      contentRef,
+      contentId,
+      focusItem,
+      inDrawer,
+    }),
+    [isOpen, setOpen, contentId, focusItem, inDrawer],
+  );
+
+  return (
+    <DropdownContext.Provider value={dropdownCtx}>
+      <li
+        ref={rootRef}
+        className={cn(
+          styles.topNavDropdown,
+          inDrawer && styles.topNavDropdownInDrawer,
+          isOpen && styles.topNavDropdownOpen,
+          className,
+        )}
+        onMouseEnter={onMouseEnter}
+        onMouseLeave={onMouseLeave}
+      >
+        <button
+          ref={triggerRef}
+          type="button"
+          className={cn(
+            styles.topNavItem,
+            styles.topNavDropdownTrigger,
+            active && styles.topNavItemActive,
+          )}
+          aria-haspopup="menu"
+          aria-expanded={isOpen}
+          aria-controls={contentId}
+          aria-current={active ? 'page' : undefined}
+          onClick={() => setOpen(!isOpen)}
+          onKeyDown={handleTriggerKey}
+        >
+          {icon && (
+            <span className={styles.topNavIcon} aria-hidden="true">
+              {icon}
+            </span>
+          )}
+          <span className={styles.topNavItemLabel}>{label}</span>
+          <ChevronIcon open={isOpen} />
+        </button>
+        <ul
+          ref={contentRef}
+          id={contentId}
+          role="menu"
+          className={cn(
+            styles.topNavDropdownContent,
+            isOpen && styles.topNavDropdownContentOpen,
+          )}
+          // Note: visibility is driven by the .topNavDropdownContentOpen class
+          // (display: none → flex). Avoid the `hidden` attribute because
+          // `[hidden] { display: none }` is overridden by class-level `display`
+          // rules — the two-source-of-truth setup leaked an empty panel onto
+          // the page in v1.
+          aria-hidden={!isOpen || undefined}
+          onKeyDown={handleContentKey}
+        >
+          {children}
+        </ul>
+      </li>
+    </DropdownContext.Provider>
+  );
+};
+
+// ============================================================================
+// EvoTopNav.DropdownItem
+// ============================================================================
+
+const EvoTopNavDropdownItem = forwardRef<HTMLElement, EvoTopNavDropdownItemProps>(
+  function EvoTopNavDropdownItem(
+    { children, icon, active, href, target, rel, onClick, asChild, className },
+    ref,
+  ) {
+    const dropdown = React.useContext(DropdownContext);
+    const top = React.useContext(TopNavContext);
+
+    const handleActivation = (e: React.MouseEvent) => {
+      onClick?.(e);
+      if (!e.defaultPrevented) {
+        dropdown?.setOpen(false);
+        // Also close the drawer if we're inside it.
+        if (top && top.isCollapsed && top.drawerOpen) top.setDrawerOpen(false);
+      }
+    };
+
+    const shared = {
+      className: cn(
+        styles.topNavDropdownItem,
+        active && styles.topNavItemActive,
+        className,
+      ),
+      role: 'menuitem' as const,
+      'aria-current': active ? ('page' as const) : undefined,
+    };
+
+    const content = (
+      <>
+        {icon && (
+          <span className={styles.topNavIcon} aria-hidden="true">
+            {icon}
+          </span>
+        )}
+        <span className={styles.topNavItemLabel}>{children}</span>
+      </>
+    );
+
+    let element: React.ReactElement;
+
+    if (asChild) {
+      element = (
+        <Slot
+          {...shared}
+          onClick={handleActivation}
+          ref={ref as React.Ref<HTMLElement>}
+        >
+          {children}
+        </Slot>
+      );
+    } else if (href) {
+      element = (
+        <a
+          ref={ref as React.Ref<HTMLAnchorElement>}
+          href={href}
+          target={target}
+          rel={rel ?? (target === '_blank' ? 'noopener noreferrer' : undefined)}
+          onClick={handleActivation}
+          {...shared}
+        >
+          {content}
+        </a>
+      );
+    } else {
+      element = (
+        <button
+          ref={ref as React.Ref<HTMLButtonElement>}
+          type="button"
+          onClick={handleActivation}
+          {...shared}
+        >
+          {content}
+        </button>
+      );
+    }
+
+    return <li>{element}</li>;
+  },
+);
+
+// ============================================================================
+// EvoTopNav — root
+// ============================================================================
+
+export const EvoTopNav = forwardRef<HTMLElement, EvoTopNavProps>(
+  function EvoTopNav(
+    {
+      children,
+      open,
+      defaultOpen = false,
+      onOpenChange,
+      collapseBelow = 768,
+      entrance = 'none',
+      sticky = false,
+      scrollBehavior = 'none',
+      showProgress = false,
+      className,
+      style,
+      ...rest
+    },
+    ref,
+  ) {
+    const [drawerOpen, setDrawerOpen] = useControllableState({
+      value: open,
+      defaultValue: defaultOpen,
+      onChange: onOpenChange,
+    });
+
+    const isCollapsed = useIsCollapsed(collapseBelow);
+    const reducedMotion = usePrefersReducedMotion();
+    const scrollEnabled = scrollBehavior !== 'none' || showProgress;
+    const { scrolled, hidden, progress } = useScrollState(scrollEnabled, scrollBehavior, showProgress);
+    const animateEntrance = entrance !== 'none' && !reducedMotion;
+    const mergedStyle: React.CSSProperties = showProgress
+      ? ({ ...style, ['--evo-topnav-progress' as string]: progress } as React.CSSProperties)
+      : (style as React.CSSProperties);
+
+    const [toggleCount, setToggleCount] = useState(0);
+    const registerToggle = useCallback(() => {
+      setToggleCount((c) => c + 1);
+      return () => setToggleCount((c) => Math.max(0, c - 1));
+    }, []);
+
+    const menuId = useId();
+    const toggleId = useId();
+    const menuRef = useRef<HTMLUListElement | null>(null);
+    const toggleRef = useRef<HTMLButtonElement | null>(null);
+    const restoreFocusRef = useRef<HTMLElement | null>(null);
+
+    const drawerActive = isCollapsed && drawerOpen && toggleCount > 0;
+
+    // Close drawer when leaving the collapsed breakpoint.
+    useEffect(() => {
+      if (!isCollapsed && drawerOpen) setDrawerOpen(false);
+    }, [isCollapsed, drawerOpen, setDrawerOpen]);
+
+    // Body scroll lock while drawer is open.
+    useEffect(() => {
+      if (!drawerActive) return;
+      const prev = document.body.style.overflow;
+      document.body.style.overflow = 'hidden';
+      return () => {
+        document.body.style.overflow = prev;
+      };
+    }, [drawerActive]);
+
+    // Esc to close + focus trap inside Menu while drawer is open.
+    useEffect(() => {
+      if (!drawerActive) return;
+      restoreFocusRef.current =
+        (document.activeElement as HTMLElement | null) ?? null;
+
+      const focusFirst = () => {
+        const items = getFocusable(menuRef.current);
+        items[0]?.focus();
+      };
+      const id = requestAnimationFrame(focusFirst);
+
+      const onKey = (e: KeyboardEvent) => {
+        if (e.key === 'Escape') {
+          e.preventDefault();
+          setDrawerOpen(false);
+          return;
+        }
+        if (e.key !== 'Tab' || !menuRef.current) return;
+        const items = getFocusable(menuRef.current);
+        if (items.length === 0) return;
+        const first = items[0];
+        const last = items[items.length - 1];
+        const activeEl = document.activeElement as HTMLElement | null;
+        if (e.shiftKey && activeEl === first) {
+          e.preventDefault();
+          last.focus();
+        } else if (!e.shiftKey && activeEl === last) {
+          e.preventDefault();
+          first.focus();
+        } else if (activeEl && !menuRef.current.contains(activeEl)) {
+          e.preventDefault();
+          first.focus();
+        }
+      };
+      document.addEventListener('keydown', onKey);
+      return () => {
+        cancelAnimationFrame(id);
+        document.removeEventListener('keydown', onKey);
+      };
+    }, [drawerActive, setDrawerOpen]);
+
+    // Restore focus when drawer closes.
+    useEffect(() => {
+      if (drawerActive) return;
+      const target = restoreFocusRef.current;
+      if (target && typeof target.focus === 'function') {
+        // Only restore if focus is currently inside the menu (or nowhere).
+        const active = document.activeElement;
+        if (
+          !active ||
+          active === document.body ||
+          (menuRef.current && menuRef.current.contains(active))
+        ) {
+          target.focus();
+        }
+        restoreFocusRef.current = null;
+      }
+    }, [drawerActive]);
+
+    const ctxValue = useMemo<TopNavContextValue>(
+      () => ({
+        drawerOpen,
+        setDrawerOpen,
+        isCollapsed,
+        menuId,
+        toggleId,
+        registerToggle,
+        toggleCount,
+        menuRef,
+        toggleRef,
+      }),
+      [
+        drawerOpen,
+        setDrawerOpen,
+        isCollapsed,
+        menuId,
+        toggleId,
+        registerToggle,
+        toggleCount,
+      ],
+    );
+
+    return (
+      <TopNavContext.Provider value={ctxValue}>
+        <nav
+          ref={ref}
+          className={cn(
+            styles.topNav,
+            sticky && styles.topNavSticky,
+            drawerActive && styles.topNavDrawerOpen,
+            reducedMotion && styles.topNavReducedMotion,
+            className,
+          )}
+          style={mergedStyle}
+          data-collapsed={isCollapsed || undefined}
+          data-drawer-open={drawerActive || undefined}
+          data-entrance={animateEntrance ? entrance : undefined}
+          data-scroll={scrollBehavior !== 'none' ? scrollBehavior : undefined}
+          data-scrolled={scrolled || undefined}
+          data-hidden={hidden || undefined}
+          {...rest}
+        >
+          <div className={styles.topNavInner}>{children}</div>
+          {showProgress && (
+            <span className={styles.topNavProgress} aria-hidden="true" />
+          )}
+          {drawerActive && (
+            <div
+              className={styles.topNavBackdrop}
+              onClick={() => setDrawerOpen(false)}
+              aria-hidden="true"
+            />
+          )}
+        </nav>
+      </TopNavContext.Provider>
+    );
+  },
+) as React.ForwardRefExoticComponent<
+  EvoTopNavProps & React.RefAttributes<HTMLElement>
+> & {
+  Brand: typeof EvoTopNavBrand;
+  Menu: typeof EvoTopNavMenu;
+  Item: typeof EvoTopNavItem;
+  Actions: typeof EvoTopNavActions;
+  Toggle: typeof EvoTopNavToggle;
+  Search: typeof EvoTopNavSearch;
+  Dropdown: typeof EvoTopNavDropdown;
+  DropdownItem: typeof EvoTopNavDropdownItem;
+};
+
+EvoTopNavBrand.displayName = 'EvoTopNav.Brand';
+EvoTopNavMenu.displayName = 'EvoTopNav.Menu';
+EvoTopNavItem.displayName = 'EvoTopNav.Item';
+EvoTopNavActions.displayName = 'EvoTopNav.Actions';
+EvoTopNavToggle.displayName = 'EvoTopNav.Toggle';
+EvoTopNavSearch.displayName = 'EvoTopNav.Search';
+EvoTopNavDropdown.displayName = 'EvoTopNav.Dropdown';
+EvoTopNavDropdownItem.displayName = 'EvoTopNav.DropdownItem';
+(EvoTopNav as { displayName?: string }).displayName = 'EvoTopNav';
+
+EvoTopNav.Brand = EvoTopNavBrand;
+EvoTopNav.Menu = EvoTopNavMenu;
+EvoTopNav.Item = EvoTopNavItem;
+EvoTopNav.Actions = EvoTopNavActions;
+EvoTopNav.Toggle = EvoTopNavToggle;
+EvoTopNav.Search = EvoTopNavSearch;
+EvoTopNav.Dropdown = EvoTopNavDropdown;
+EvoTopNav.DropdownItem = EvoTopNavDropdownItem;