@flamingo-stack/openframe-frontend-core 0.0.704 → 0.0.705-snapshot.20261006160157

package/src/components/navigation/site-header.tsx

@@ -0,0 +1,339 @@
+'use client';
+
+import type React from 'react';
+import { useEffect, useRef, useState } from 'react';
+import Link from '../../embed-shims/next-link';
+import { useActiveSection } from '../../hooks/ui/use-active-section';
+import { useNavMenus } from '../../hooks/ui/use-nav-menus';
+import type { NavMenu, SiteNav } from '../../types/navigation';
+import { cn } from '../../utils/cn';
+import { EntityIcon } from '../icon-display';
+import { Chevron02DownIcon } from '../icons-v2-generated/arrows/chevron-02-down-icon';
+import { Menu01Icon } from '../icons-v2-generated/interface/menu-01-icon';
+import { XmarkIcon } from '../icons-v2-generated/signs-and-symbols/xmark-icon';
+import { Button } from '../ui/button';
+import { HeaderButton } from './header-button';
+import { MingoAiButton } from './mingo-ai-button';
+import { MOBILE_NAV_SHEET_ID } from './mobile-nav-sheet-id';
+import { isMegaMenu, NavPanel, type NavPanelMotion } from './nav-panel';
+import { defaultRenderSiteNavLink, NAV_FOCUS_CLASS, type SiteNavLinkRenderer } from './site-nav-link';
+import { TopNavigation } from './top-navigation';
+
+export interface SiteHeaderProps {
+  nav: SiteNav;
+  /** The host router's pathname: marks the active section and closes menus on navigation. */
+  pathname: string;
+  logo: React.ReactNode;
+  /** Omitted: the logo is not a link. */
+  logoHref?: string;
+  /** The host's link (Next `Link`, unified navigation). Default: `<a>`. */
+  renderLink?: SiteNavLinkRenderer;
+  /** Leading cells (admin sidebar toggle). Each cell owns its divider. */
+  leading?: React.ReactNode;
+  /** Host actions at the right (profile button, custom buttons). Shown at every width. */
+  actions?: React.ReactNode;
+  /** The primary CTA node when `nav.primaryCta` is `'trial'` or `'waitlist'`. */
+  cta?: React.ReactNode;
+  /** Trailing cells (ticket alerts). Each cell owns its divider. */
+  sideActions?: React.ReactNode;
+  /**
+   * The Mingo AI launcher, first in the right cluster (before Sign in).
+   * Omitted: no launcher. `icon` and `label` are the server-configured
+   * assistant identity (the same ones the chat panel shows); `source` scopes
+   * the `ask-ai:open` event the launcher dispatches.
+   */
+  mingo?: { source?: string; icon?: React.ReactNode; label?: string; shortcutHint?: boolean };
+  /** Omitted: no burger. */
+  mobile?: { isOpen: boolean; onToggle: () => void; controlsId?: string };
+  /** Values for `NavLink.badgeKey`. */
+  badges?: Record<string, number>;
+  /** Rendered under a menu with `showSocial`. */
+  social?: React.ReactNode;
+  autoHide?: boolean;
+  /** Opaque ODS background class. */
+  backgroundClassName?: string;
+  className?: string;
+  style?: React.CSSProperties;
+  /** The id the "Skip to content" link targets. Default `main-content`. */
+  skipToContentId?: string;
+}
+
+// A top-level item (prototype `.nv-l`): 40px tall, quiet until hovered, open
+// or current.
+const TOP_ITEM_CLASS =
+  'relative inline-flex h-10 items-center gap-1.5 whitespace-nowrap rounded-md px-3.5 text-ods-text-secondary transition-colors text-h6 hover:bg-ods-bg-hover hover:text-ods-text-primary';
+// The current section: a 2px accent underline and an accent wash.
+const TOP_ITEM_CURRENT_CLASS =
+  'rounded-b-none bg-gradient-to-b from-transparent to-ods-accent/10 text-ods-text-primary after:absolute after:inset-x-0 after:bottom-0 after:h-0.5 after:bg-ods-accent';
+
+/** A top-level item's optional glyph (`NavMenu.iconName`), before its label. */
+const menuIcon = (menu: NavMenu) =>
+  menu.iconName ? <EntityIcon icon={{ name: menu.iconName }} size={20} className="size-5 shrink-0" /> : null;
+
+/**
+ * The site header of every platform, drawn from one `SiteNav`: logo, the
+ * menus left-aligned after it, then the Mingo AI launcher, Sign in, the host's
+ * actions, the primary CTA (the only button) and the trailing cells. A
+ * platform differs only in the data and the slots it passes.
+ *
+ * Below `lg` the menus and Sign in leave the bar (they live in
+ * `MobileNavSheet`); the host's actions, the CTA and the launcher stay.
+ */
+export function SiteHeader({
+  nav,
+  pathname,
+  logo,
+  logoHref,
+  renderLink = defaultRenderSiteNavLink,
+  leading,
+  actions,
+  cta,
+  sideActions,
+  mingo,
+  mobile,
+  badges,
+  social,
+  autoHide = false,
+  backgroundClassName,
+  className,
+  style,
+  skipToContentId = 'main-content',
+}: SiteHeaderProps) {
+  const [show, setShow] = useState(true);
+  // Not state: nothing renders the previous offset, and as `useState` it
+  // re-rendered the whole header on every scroll event just to store a number.
+  const lastScrollY = useRef(0);
+
+  const activeId = useActiveSection(nav.menus, pathname);
+  const { openId, close, getTriggerProps, getPanelProps } = useNavMenus({ pathname });
+
+  // The menu that was open before this one, kept during render (no effect, no
+  // late frame): it tells an opening mega menu which side its content comes from.
+  const [trail, setTrail] = useState<{ id: string | null; from: string | null }>({ id: null, from: null });
+  if (trail.id !== openId) setTrail({ id: openId, from: trail.id });
+  const previousId = trail.id === openId ? trail.from : trail.id;
+  const megaIds = nav.menus.filter(isMegaMenu).map(menu => menu.id);
+  const openMegaIndex = openId === null ? -1 : megaIds.indexOf(openId);
+  const previousMegaIndex = previousId === null ? -1 : megaIds.indexOf(previousId);
+  const megaMotion: NavPanelMotion =
+    openMegaIndex < 0 || previousMegaIndex < 0 ? 'open' : openMegaIndex > previousMegaIndex ? 'from-end' : 'from-start';
+
+  useEffect(() => {
+    // Only add the scroll listener while auto-hide is on. Nothing to reset
+    // here: `show` is masked by `autoHide` where it is read (`headerShown`), so
+    // turning auto-hide off can never leave the header stuck off-screen.
+    if (!autoHide) return undefined;
+
+    const handleScroll = () => {
+      const currentScrollY = window.scrollY;
+      const prevScrollY = lastScrollY.current;
+      lastScrollY.current = currentScrollY;
+
+      if (currentScrollY > prevScrollY && currentScrollY > 50) setShow(false);
+      else if (currentScrollY < prevScrollY || currentScrollY <= 10) setShow(true);
+    };
+
+    window.addEventListener('scroll', handleScroll, { passive: true });
+    return () => window.removeEventListener('scroll', handleScroll);
+  }, [autoHide]);
+
+  // An open menu holds the header in place: hiding the bar would take the
+  // panel the visitor is reading with it.
+  const headerShown = !autoHide || show || openId !== null;
+
+  const renderMenu = (menu: NavMenu) => {
+    const current = menu.id === activeId;
+    const hasPanel = !!menu.columns?.length || !!menu.features?.length || !!menu.sideLinks?.length;
+
+    if (!hasPanel) {
+      if (!menu.href) return null;
+      return (
+        <div key={menu.id} className="flex">
+          <Button
+            asChild
+            variant="transparent"
+            size="wrap"
+            font="regular"
+            className={cn(TOP_ITEM_CLASS, NAV_FOCUS_CLASS, current && TOP_ITEM_CURRENT_CLASS)}
+          >
+            {renderLink({
+              link: { href: menu.href },
+              'aria-current': current ? 'page' : undefined,
+              children: (
+                <>
+                  {menuIcon(menu)}
+                  {menu.label}
+                </>
+              ),
+            })}
+          </Button>
+        </div>
+      );
+    }
+
+    const open = openId === menu.id;
+    return (
+      // A dropdown is anchored to its trigger (`relative`); a mega menu to the
+      // bar itself, so its wrapper stays unpositioned.
+      <div key={menu.id} className={cn('flex', !isMegaMenu(menu) && 'relative')}>
+        <Button
+          type="button"
+          variant="transparent"
+          size="wrap"
+          font="regular"
+          {...getTriggerProps(menu.id)}
+          aria-current={current ? 'page' : undefined}
+          className={cn(
+            TOP_ITEM_CLASS,
+            NAV_FOCUS_CLASS,
+            open && 'bg-ods-bg-hover text-ods-text-primary',
+            current && TOP_ITEM_CURRENT_CLASS,
+          )}
+        >
+          {menuIcon(menu)}
+          {menu.label}
+          <Chevron02DownIcon
+            aria-hidden="true"
+            // `!`: the Button sizes every glyph inside it at 20px; the chevron is 16.
+            className={cn('!h-4 !w-4 transition-transform duration-150', open && 'rotate-180')}
+          />
+        </Button>
+        <NavPanel
+          {...getPanelProps(menu.id)}
+          menu={menu}
+          open={open}
+          motion={open ? megaMotion : undefined}
+          handoff={openMegaIndex >= 0}
+          renderLink={renderLink}
+          badges={badges}
+          social={social}
+          onNavigate={close}
+        />
+      </div>
+    );
+  };
+
+  const primaryCta =
+    typeof nav.primaryCta === 'object' ? (
+      <Button variant="accent" href={nav.primaryCta.href}>
+        {nav.primaryCta.label}
+      </Button>
+    ) : nav.primaryCta === 'none' ? null : (
+      (cta ?? null)
+    );
+  const hasRight = !!mingo || !!nav.signIn || !!actions || !!primaryCta;
+
+  return (
+    <div
+      // Hook point for page-scoped header CSS (a full-screen deck hides the bar).
+      data-site-header=""
+      className="sticky top-0 z-[50] w-full transition-transform duration-300 ease-in-out"
+      style={{ transform: headerShown ? 'translateY(0)' : 'translateY(-100%)' }}
+    >
+      {/* First tab stop of the page; visible only while focused. */}
+      <Link
+        href={`#${skipToContentId}`}
+        className={cn(
+          'sr-only left-[var(--spacing-system-lf)] top-3 z-[70] rounded-md bg-ods-text-primary px-[var(--spacing-system-mf)] py-[var(--spacing-system-xsf)] text-ods-bg text-h6 focus:not-sr-only focus:absolute',
+          NAV_FOCUS_CLASS,
+        )}
+      >
+        Skip to content
+      </Link>
+      {/* Unified ODS top-navigation shell (Figma 2797-5978), cell model with
+          per-cell dividers. NOTE: no `backdrop-blur` anywhere in this bar.
+          Every platform ships an OPAQUE header background, so a
+          backdrop-filter would blur a backdrop that is then fully painted
+          over: zero visual effect, but the browser still re-rasterizes the
+          strip behind this sticky bar every scroll frame and content flickers
+          as it passes under the header. A translucent "glass" header needs
+          the blur and a translucent `backgroundClassName` together. */}
+      <TopNavigation
+        // `relative` anchors a mega menu to the bar: it opens full width
+        // right under it.
+        className={cn('relative', className)}
+        style={style}
+        backgroundClassName={backgroundClassName}
+        centerBreakpoint="lg"
+        size="big"
+        leading={
+          <>
+            {leading}
+            {/* Menu toggle: a leading cell, banded with the menus' breakpoint
+                (`lg`) so the desktop menus and the toggle never co-show. */}
+            {mobile && (
+              <HeaderButton
+                className="border-r border-ods-border lg:hidden"
+                onClick={mobile.onToggle}
+                isActive={mobile.isOpen}
+                aria-label={mobile.isOpen ? 'Close menu' : 'Open menu'}
+                aria-expanded={mobile.isOpen}
+                // Conditional: the sheet unmounts when closed, so an
+                // unconditional reference would dangle (axe aria-valid-attr-value).
+                aria-controls={mobile.isOpen ? (mobile.controlsId ?? MOBILE_NAV_SHEET_ID) : undefined}
+                icon={mobile.isOpen ? <XmarkIcon className="h-6 w-6" /> : <Menu01Icon className="h-6 w-6" />}
+              />
+            )}
+          </>
+        }
+        logo={
+          logoHref
+            ? renderLink({
+                link: { href: logoHref },
+                className: cn(
+                  'flex min-w-0 items-center rounded-md transition-opacity duration-200 hover:opacity-80',
+                  NAV_FOCUS_CLASS,
+                ),
+                'aria-label': nav.brand.name,
+                children: logo,
+              })
+            : logo
+        }
+        // Big-bar rule (Figma 2936-6812): a fixed 24px left inset on the logo
+        // zone at every breakpoint, which also reads as the gap between a
+        // leading cell and the logo. `shrink` lets the logo, never the CTA,
+        // give way on the narrowest phones.
+        logoClassName="shrink pl-[var(--spacing-system-lf)] md:pl-[var(--spacing-system-lf)] lg:pl-[var(--spacing-system-lf)]"
+        center={
+          nav.menus.length > 0 ? (
+            <nav aria-label="Main" className="flex items-center gap-[var(--spacing-system-xxs)]">
+              {nav.menus.map(renderMenu)}
+            </nav>
+          ) : undefined
+        }
+        centerClassName="justify-start pl-[var(--spacing-system-xlf)]"
+        cta={
+          hasRight ? (
+            <>
+              {mingo && (
+                <MingoAiButton
+                  source={mingo.source}
+                  icon={mingo.icon}
+                  label={mingo.label}
+                  shortcutHint={mingo.shortcutHint}
+                />
+              )}
+              {nav.signIn && (
+                <div className="hidden lg:flex">
+                  <Button
+                    asChild
+                    variant="transparent"
+                    size="wrap"
+                    font="regular"
+                    className={cn(TOP_ITEM_CLASS, NAV_FOCUS_CLASS)}
+                  >
+                    {renderLink({ link: nav.signIn, children: nav.signIn.label })}
+                  </Button>
+                </div>
+              )}
+              {actions}
+              {primaryCta}
+            </>
+          ) : undefined
+        }
+        ctaClassName="gap-[var(--spacing-system-xsf)]"
+        sideActions={sideActions}
+      />
+    </div>
+  );
+}

package/src/components/navigation/site-nav-link.tsx

@@ -0,0 +1,41 @@
+import type React from 'react';
+import Link from '../../embed-shims/next-link';
+import type { NavLink } from '../../types/navigation';
+
+/**
+ * How a host renders one navigation link (Next `Link`, a unified-navigation
+ * anchor). Every site navigation component takes one; omitted, links go
+ * through {@link defaultRenderSiteNavLink}.
+ */
+export type SiteNavLinkRenderer = (props: {
+  link: Pick<NavLink, 'href' | 'external'>;
+  className?: string;
+  children: React.ReactNode;
+  onClick?: (e: React.MouseEvent) => void;
+  'aria-current'?: 'page';
+  'aria-label'?: string;
+}) => React.ReactNode;
+
+/**
+ * The default link: the library's `Link` shim (a plain `<a>`, or the host's
+ * registered router link, so internal links soft-navigate), opened in a new
+ * tab for a link that leaves the site.
+ */
+export const defaultRenderSiteNavLink: SiteNavLinkRenderer = ({ link, children, ...rest }) =>
+  link.external ? (
+    <Link href={link.href} target="_blank" rel="noopener noreferrer" {...rest}>
+      {children}
+    </Link>
+  ) : (
+    <Link href={link.href} {...rest}>
+      {children}
+    </Link>
+  );
+
+/** A link's label, with its `{count}` token filled from `link.count`. */
+export function navLinkLabel(link: Pick<NavLink, 'label' | 'count'>): string {
+  return link.count === undefined ? link.label : link.label.replace('{count}', String(link.count));
+}
+
+/** Focus ring shared by every navigation link and trigger. */
+export const NAV_FOCUS_CLASS = 'outline-none focus-visible:ring-2 focus-visible:ring-ods-accent';

package/src/components/navigation/ticket-alerts-button.tsx

@@ -2,8 +2,8 @@
 
 /**
  * TicketAlertsButton — the unified header affordance for support-ticket
- * unread indication. Mounted by BOTH header shells (hub `Header` via
- * `HeaderConfig.tickets`, console `AppHeader` via `showTicketAlerts`).
+ * unread indication. Mounted by BOTH header shells (the `SiteHeader` through its
+ * `sideActions` slot, console `AppHeader` via `showTicketAlerts`).
  *
  * ATTENTION-ONLY element, deliberately unlike the always-on header cells:
  *   - renders NOTHING unless there are unread support replies (and a

package/src/components/navigation/top-navigation.tsx

@@ -59,7 +59,7 @@ export interface TopNavigationProps extends React.HTMLAttributes<HTMLElement> {
   sideActions?: React.ReactNode;
   /** Opaque ODS background class. Defaults to `bg-ods-card`. Keep it opaque —
    *  translucent backgrounds under a sticky bar need a deliberate
-   *  backdrop-blur treatment (see the note in `header.tsx`). */
+   *  backdrop-blur treatment (see the note in `site-header.tsx`). */
   backgroundClassName?: string;
   /** Top border on mobile (the ODS spec bar shows it below md). Default true. */
   mobileTopBorder?: boolean;
@@ -73,7 +73,7 @@ const hasContent = (node: React.ReactNode): boolean => node !== null && node !==
 /**
  * Unified ODS top-navigation bar (Figma `[UPD] top-navigation`, node
  * 2797-5978): the single 48px/56px (mobile / md+) cell-based header shell
- * shared by the console `AppHeader` and the marketing `Header` across all
+ * shared by the console `AppHeader` and the `SiteHeader` across all
  * platforms.
  *
  * The shell owns the bar geometry only — height, borders, background, and the

package/src/components/platform/SoftwareSourceBadge.tsx

@@ -33,7 +33,7 @@
  */
 
 import type React from 'react';
-import { cn } from '../../utils/common';
+import { cn } from '../../utils/cn';
 import { PackageIcon, WindowsIcon, MacOSIcon, LinuxIcon } from '../icons';
 
 export type SoftwareSource =

package/src/hooks/index.ts

@@ -39,6 +39,7 @@ export * from './use-claude-mirror-src';
 // Deep-link "scroll to URL hash" after data loads. Pairs with URL
 // composers that emit `?<filter>=<id>#<prefix>-<id>` — the filter
 // narrows the list, the hash scrolls the matching DOM id.
+export * from './use-location-hash';
 export * from './use-scroll-to-hash';
 
 // Invisible bot-protection client primitive (honeypot ref + submit-timing).

package/src/hooks/ui/index.ts

@@ -31,3 +31,6 @@ export { usePreventScroll } from '@react-aria/overlays';
 export * from './use-prefers-reduced-motion';
 export * from './use-in-view';
 export * from './use-autoplay';
+export * from './use-active-section';
+export * from './use-nav-menus';
+export * from './use-visitor-os';

package/src/hooks/ui/use-active-section.ts

@@ -0,0 +1,44 @@
+'use client';
+
+import { useMemo } from 'react';
+import type { NavMenu } from '../../types/navigation';
+
+/** The path of an internal href, without its query or `#anchor`. `null` for an
+ *  absolute URL: another site is never the current section. */
+function pathOf(href: string | undefined): string | null {
+  if (!href || !href.startsWith('/') || href.startsWith('//')) return null;
+  const path = href.split(/[?#]/)[0];
+  return path.length > 1 ? path.replace(/\/+$/, '') : '/';
+}
+
+/** Boundary-aware prefix test: `/pricing` holds `/pricing` and `/pricing/x`,
+ *  never `/pricing-old`; `/` holds only `/`. */
+function prefixHolds(prefix: string, pathname: string): boolean {
+  if (prefix === '/') return pathname === '/';
+  return pathname === prefix || pathname.startsWith(`${prefix}/`);
+}
+
+/**
+ * Pure rule behind {@link useActiveSection}: the id of the menu whose `match`
+ * prefixes (else its `href`) hold the pathname. The longest prefix wins, the
+ * first menu on a tie; `null` when none holds it.
+ */
+export function resolveActiveSection(menus: readonly NavMenu[], pathname: string | null | undefined): string | null {
+  const current = pathOf(pathname ?? undefined);
+  if (!current) return null;
+  let best: { id: string; length: number } | null = null;
+  for (const menu of menus) {
+    const prefixes = menu.match?.length ? menu.match : [menu.href];
+    for (const raw of prefixes) {
+      const prefix = pathOf(raw);
+      if (!prefix || !prefixHolds(prefix, current)) continue;
+      if (!best || prefix.length > best.length) best = { id: menu.id, length: prefix.length };
+    }
+  }
+  return best?.id ?? null;
+}
+
+/** The id of the top-level menu the current page belongs to, or `null`. */
+export function useActiveSection(menus: readonly NavMenu[], pathname: string | null | undefined): string | null {
+  return useMemo(() => resolveActiveSection(menus, pathname), [menus, pathname]);
+}

package/src/hooks/ui/use-nav-menus.ts

@@ -0,0 +1,200 @@
+'use client';
+
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type MouseEvent as ReactMouseEvent,
+  type RefCallback,
+} from 'react';
+
+export interface UseNavMenusOptions {
+  /** The host router's pathname: any change closes the open menu. */
+  pathname: string;
+  /** Hover intent: how long the pointer rests on a trigger before it opens. */
+  hoverOpenMs?: number;
+  /** How long after the pointer left the trigger and the panel the menu closes. */
+  hoverCloseMs?: number;
+}
+
+export interface NavMenuTriggerProps {
+  ref: RefCallback<HTMLElement>;
+  'aria-expanded': boolean;
+  'aria-controls': string;
+  onClick: (event: ReactMouseEvent) => void;
+  onMouseEnter: () => void;
+  onMouseLeave: () => void;
+}
+
+export interface NavMenuPanelProps {
+  ref: RefCallback<HTMLElement>;
+  id: string;
+  inert: boolean;
+  'data-state': 'open' | 'closed';
+  onMouseEnter: () => void;
+  onMouseLeave: () => void;
+}
+
+export interface UseNavMenusResult {
+  /** The id of the open menu, or `null`. One menu is open at a time. */
+  openId: string | null;
+  close: () => void;
+  getTriggerProps: (id: string) => NavMenuTriggerProps;
+  getPanelProps: (id: string) => NavMenuPanelProps;
+}
+
+/**
+ * Open state for a row of disclosure menus (the site header's dropdowns and
+ * mega menus).
+ *
+ * - Click toggles; the trigger is a `<button>`, so Enter and Space arrive as
+ *   that same click.
+ * - Hover on a trigger opens after `hoverOpenMs`; with a menu already open,
+ *   hovering another trigger switches to it at once. Leaving the trigger and the
+ *   panel closes after `hoverCloseMs`; entering the panel or any trigger
+ *   cancels that close, so the pointer can cross the gap between them.
+ * - Escape closes and returns focus to the trigger. A pointer-down outside
+ *   every trigger and panel closes. A `pathname` change closes.
+ * - No arrow-key roving: these are plain disclosures, Tab moves in DOM order.
+ */
+export function useNavMenus({
+  pathname,
+  hoverOpenMs = 150,
+  hoverCloseMs = 300,
+}: UseNavMenusOptions): UseNavMenusResult {
+  const baseId = useId();
+  // The open menu is remembered WITH the pathname it was opened on, so a
+  // navigation closes it during render: no effect, no frame of a stale panel.
+  // The stale entry is dropped in the same render, or coming back to that
+  // pathname would reopen it.
+  const [opened, setOpened] = useState<{ id: string; pathname: string } | null>(null);
+  const stale = opened !== null && opened.pathname !== pathname;
+  if (stale) setOpened(null);
+  const openId = opened && !stale ? opened.id : null;
+
+  const triggers = useRef(new Map<string, HTMLElement>());
+  const panels = useRef(new Map<string, HTMLElement>());
+  const openTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // The menu a HOVER opened, until a click claims it (see `onClick`).
+  const openedByHover = useRef<string | null>(null);
+
+  const clearTimers = useCallback(() => {
+    if (openTimer.current) clearTimeout(openTimer.current);
+    if (closeTimer.current) clearTimeout(closeTimer.current);
+    openTimer.current = null;
+    closeTimer.current = null;
+  }, []);
+
+  useEffect(() => clearTimers, [clearTimers]);
+
+  const close = useCallback(() => {
+    clearTimers();
+    setOpened(null);
+  }, [clearTimers]);
+
+  const cancelClose = useCallback(() => {
+    if (closeTimer.current) clearTimeout(closeTimer.current);
+    closeTimer.current = null;
+  }, []);
+
+  const scheduleClose = useCallback(() => {
+    if (openTimer.current) clearTimeout(openTimer.current);
+    openTimer.current = null;
+    cancelClose();
+    closeTimer.current = setTimeout(() => {
+      closeTimer.current = null;
+      setOpened(null);
+    }, hoverCloseMs);
+  }, [cancelClose, hoverCloseMs]);
+
+  useEffect(() => {
+    if (!openId) return undefined;
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape') return;
+      const trigger = triggers.current.get(openId);
+      close();
+      trigger?.focus({ preventScroll: true });
+    };
+    const handlePointerDown = (event: PointerEvent) => {
+      const target = event.target;
+      if (!(target instanceof Node)) return;
+      for (const el of triggers.current.values()) if (el.contains(target)) return;
+      for (const el of panels.current.values()) if (el.contains(target)) return;
+      close();
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    document.addEventListener('pointerdown', handlePointerDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+      document.removeEventListener('pointerdown', handlePointerDown);
+    };
+  }, [openId, close]);
+
+  const getTriggerProps = useCallback(
+    (id: string): NavMenuTriggerProps => ({
+      ref: el => {
+        if (el) triggers.current.set(id, el);
+        else triggers.current.delete(id);
+      },
+      'aria-expanded': openId === id,
+      'aria-controls': `${baseId}-panel-${id}`,
+      onClick: () => {
+        // A touch tap fires mouseenter first: drop its pending open, or it
+        // would reopen the menu this click just closed.
+        clearTimers();
+        // A click on a menu the pointer's hover already opened means "open
+        // it": it keeps the menu open instead of toggling it shut (a mouse
+        // user hovers, then clicks; a touch tap fires mouseenter, then click).
+        // The click claims the menu, so the next click on it closes it.
+        const hovered = openedByHover.current === id;
+        openedByHover.current = null;
+        if (hovered) {
+          setOpened({ id, pathname });
+          return;
+        }
+        setOpened(prev => (prev && prev.id === id && prev.pathname === pathname ? null : { id, pathname }));
+      },
+      onMouseEnter: () => {
+        clearTimers();
+        if (openId === id) return;
+        // A menu is already open: the visitor is browsing the row, so the next
+        // one opens at once. The hover-intent wait is only for the FIRST open
+        // (it filters a pointer merely crossing the bar).
+        if (openId !== null) {
+          openedByHover.current = id;
+          setOpened({ id, pathname });
+          return;
+        }
+        openTimer.current = setTimeout(() => {
+          openTimer.current = null;
+          openedByHover.current = id;
+          setOpened({ id, pathname });
+        }, hoverOpenMs);
+      },
+      onMouseLeave: scheduleClose,
+    }),
+    [baseId, openId, pathname, hoverOpenMs, clearTimers, scheduleClose],
+  );
+
+  const getPanelProps = useCallback(
+    (id: string): NavMenuPanelProps => ({
+      ref: el => {
+        if (el) panels.current.set(id, el);
+        else panels.current.delete(id);
+      },
+      id: `${baseId}-panel-${id}`,
+      inert: openId !== id,
+      'data-state': openId === id ? 'open' : 'closed',
+      onMouseEnter: cancelClose,
+      onMouseLeave: scheduleClose,
+    }),
+    [baseId, openId, cancelClose, scheduleClose],
+  );
+
+  return { openId, close, getTriggerProps, getPanelProps };
+}