@astryxdesign/core 0.4.1 → 0.4.2-canary.356d2f9

package/src/hooks/useMenuHover.ts

@@ -4,42 +4,98 @@
 
 /**
  * @file useMenuHover.ts
- * @input Uses React hooks, useListFocus
+ * @input Uses React hooks, useListFocus, useMediaQuery
  * @output Exports useMenuHover hook
- * @position Internal hook; used by nav heading components and TopNavMenu
+ * @position Internal hook; used by nav heading components, TopNavMenu,
+ *           TopNavMegaMenu and DropdownMenuSubMenu
  *
- * Hover as a progressive enhancement on top of standard popover behavior:
+ * Hover as a progressive enhancement over standard popover behavior: click
+ * toggles, Escape and outside-click close, arrows navigate; on top of that,
+ * mouseenter opens after a delay and mouseleave closes one that hover opened.
  *
- * 1. Default popover: click toggles, Escape closes, outside-click closes,
- *    arrow keys navigate menu items.
+ * Three behaviors here are not obvious and are load-bearing:
  *
- * 2. Hover add-on:
- *    - mouseenter activates "hover mode" and opens after delay
- *    - While in hover mode, mouseleave closes after delay
- *    - Any close (click, Escape, outside-click) resets hover mode
- *    - Click-to-close additionally skips the next mouseenter
+ * 1. Hover→click guard (#3121). A hover-opened menu is already open under the
+ *    cursor when the pointer arrives, so the click that naturally follows would
+ *    toggle it shut. Within `clickGuardMs` a click instead confirms it: the menu
+ *    pins and behaves like a click-open from then on.
  *
- * Only uses mouseenter/mouseleave (not mouseover).
+ * 2. Focus moves synchronously. `useLayer.show()` calls `showPopover()` in the
+ *    same tick and the layer's children are always mounted, so items are
+ *    focusable the moment `show()` returns — a `requestAnimationFrame` here
+ *    lands after paint and races anything else moving focus. Hover-opens are the
+ *    exception: the pointer is driving, so focus stays on the trigger. The hook
+ *    always passes `skipAutoFocus` and owns focus itself, because the popover's
+ *    auto-focus targets the first *tabbable* node while a menu wants its first
+ *    item — under roving tabindex those are different elements.
+ *
+ * 3. Native light dismiss. A `popover="auto"` is dismissed by the browser on
+ *    pointer interaction outside the panel, and a trigger outside the panel
+ *    counts — before React's click handler runs. `popoverId` makes the trigger
+ *    the panel's invoker, which exempts it. jsdom implements neither light
+ *    dismiss nor invokers, so that wiring is only verifiable in a browser.
  */
 
 import {useCallback, useEffect, useRef} from 'react';
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 import {useListFocus} from './useListFocus';
 import {useMediaQuery} from './useMediaQuery';
 
-interface UseMenuHoverOptions {
+const DEFAULT_CLICK_GUARD_MS = 500;
+
+/**
+ * How long after a close a mouseenter on the trigger is ignored.
+ *
+ * A panel positioned over its own trigger puts that trigger back under a
+ * stationary pointer when it closes, and the browser fires a fresh mouseenter —
+ * which reopened the menu the user had just dismissed. Time-bounded rather than
+ * a one-shot flag, so a deliberate re-hover seconds later still opens; a real
+ * mouseleave clears it early.
+ */
+const REOPEN_SUPPRESS_MS = 300;
+
+export interface UseMenuHoverOptions {
   show: (options?: {skipAutoFocus?: boolean}) => void;
   hide: () => void;
   isOpen: boolean;
   isEnabled: boolean;
+  /** Delay before a hover opens the menu (ms). @default 150 */
   showDelay?: number;
+  /** Delay before leaving the trigger or menu closes it (ms). @default 200 */
   hideDelay?: number;
+  /**
+   * Window after a hover-open in which a click confirms the menu instead of
+   * closing it. 0 opts out, making every click toggle. @default 500
+   */
+  clickGuardMs?: number;
+  /**
+   * Selector for the menu's focusable items, forwarded to `useListFocus`. A
+   * panel of links (a mega menu) needs an override; `role="menuitem"` rows do
+   * not. @default '[role="menuitem"]'
+   */
+  itemSelector?: string;
+  /**
+   * The popup's DOM id (`usePopover().id`). Supply it when the popup is a
+   * native `popover="auto"` and the trigger sits outside it; omit it for
+   * `popover="manual"` popups and triggers inside the panel.
+   */
+  popoverId?: string;
+  /**
+   * Whether the hook moves focus on a click or keyboard open. False for
+   * consumers that wire the pointer half only and leave focus to the popover's
+   * own trap — a panel that is a dialog rather than a menu (`SideNavItem`'s
+   * collapsed flyout) has no items for the hook to focus. @default true
+   */
+  ownsFocus?: boolean;
 }
 
-interface UseMenuHoverReturn<T extends HTMLElement = HTMLElement> {
+export interface UseMenuHoverReturn<T extends HTMLElement = HTMLElement> {
   triggerProps: {
-    onClick: () => void;
+    onClick: (event?: React.MouseEvent) => void;
     onMouseEnter: () => void;
     onMouseLeave: () => void;
+    /** Present only when `popoverId` is supplied. */
+    popoverTarget?: string;
   };
   contentProps: {
     onMouseEnter: () => void;
@@ -47,7 +103,25 @@ interface UseMenuHoverReturn<T extends HTMLElement = HTMLElement> {
     onKeyDown: (e: React.KeyboardEvent) => void;
   };
   menuRef: React.RefObject<T | null>;
-  focusFirst: () => void;
+  /** Focus the first enabled item. Returns false when there was none. */
+  focusFirst: () => boolean;
+  /**
+   * Focus the first enabled item, falling back to the menu container when the
+   * menu is empty or still loading.
+   */
+  focusMenu: () => void;
+  /**
+   * For consumers with their own click handler: call this in the open branch.
+   * Returns `true` when the click was the one following a hover-open — the menu
+   * is now pinned and the click must NOT be treated as a dismissal.
+   */
+  confirmHoverOpen: () => boolean;
+  /**
+   * Close, restoring focus to the trigger. For dismiss affordances rendered
+   * inside the popup, which are close buttons rather than the trigger and so
+   * must not carry its toggle and keyboard-activation semantics.
+   */
+  close: () => void;
   setTriggerEl: (el: HTMLElement | null) => void;
 }
 
@@ -61,6 +135,10 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
     isEnabled,
     showDelay = 150,
     hideDelay = 200,
+    clickGuardMs = DEFAULT_CLICK_GUARD_MS,
+    itemSelector,
+    popoverId,
+    ownsFocus = true,
   } = options;
 
   const hasHover = useMediaQuery('(hover: hover)');
@@ -68,17 +146,25 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
   const showTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const hideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const triggerElRef = useRef<HTMLElement | null>(null);
-  // Whether the menu was opened/interacted via hover (enables mouseleave-to-close)
+  /** Menu was hover-opened, so mouseleave may close it. */
   const hoverModeRef = useRef(false);
-  // One-shot: skip the next mouseenter after click-to-close
-  const skipNextEnterRef = useRef(false);
+  const closedAtRef = useRef(0);
+  /** When the current open began as a hover-open; 0 once confirmed or closed. */
+  const hoverOpenedAtRef = useRef(0);
   const prevIsOpenRef = useRef(isOpen);
 
-  // When popover closes (any reason), reset hover mode
-  if (prevIsOpenRef.current && !isOpen) {
-    hoverModeRef.current = false;
-  }
-  prevIsOpenRef.current = isOpen;
+  // Catches every close, whatever caused it. A layout effect, not render: it
+  // must land before the browser hit-tests the vanished panel and fires the
+  // mouseenter REOPEN_SUPPRESS_MS exists to swallow.
+  useIsomorphicLayoutEffect(() => {
+    const wasOpen = prevIsOpenRef.current;
+    prevIsOpenRef.current = isOpen;
+    if (wasOpen && !isOpen) {
+      hoverModeRef.current = false;
+      hoverOpenedAtRef.current = 0;
+      closedAtRef.current = Date.now();
+    }
+  }, [isOpen]);
 
   const clearTimeouts = useCallback(() => {
     if (showTimerRef.current) {
@@ -91,56 +177,160 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
     }
   }, []);
 
+  // useListFocus needs an onEscape that is defined in terms of its own listRef;
+  // the indirection avoids the use-before-declare.
+  const escapeHandlerRef = useRef<() => void>(() => {});
+
   const {
     listRef: menuRef,
     handleKeyDown: handleListKeyDown,
     focusFirst,
   } = useListFocus<T>({
-    onEscape: () => {
-      clearTimeouts();
-      hide();
-    },
+    itemSelector,
+    onEscape: () => escapeHandlerRef.current(),
   });
 
+  const hideAndRestoreFocus = useCallback(() => {
+    // Read before hiding: closing the layer moves focus itself.
+    const menuHadFocus =
+      menuRef.current?.contains(document.activeElement) ?? false;
+    hide();
+    if (menuHadFocus) {
+      triggerElRef.current?.focus();
+    }
+  }, [hide, menuRef]);
+
+  useEffect(() => {
+    escapeHandlerRef.current = () => {
+      clearTimeouts();
+      hideAndRestoreFocus();
+    };
+  }, [clearTimeouts, hideAndRestoreFocus]);
+
   useEffect(() => {
     return () => clearTimeouts();
   }, [clearTimeouts]);
 
-  // Click: always toggle
-  const handleClick = useCallback(() => {
-    clearTimeouts();
-    if (isOpen) {
-      skipNextEnterRef.current = true;
-      hide();
-    } else {
-      skipNextEnterRef.current = false;
+  const focusMenu = useCallback(() => {
+    // An empty or still-loading menu has no focusable item; focus the container
+    // so keyboard ownership still transfers off the trigger's list.
+    if (!focusFirst()) {
+      menuRef.current?.focus();
+    }
+  }, [focusFirst, menuRef]);
+
+  const openAndFocus = useCallback(() => {
+    if (!ownsFocus) {
       show();
-      requestAnimationFrame(() => focusFirst());
+      return;
+    }
+    show({skipAutoFocus: true});
+    focusMenu();
+  }, [ownsFocus, show, focusMenu]);
+
+  const confirmHoverOpen = useCallback((): boolean => {
+    const isConfirming =
+      clickGuardMs > 0 &&
+      hoverOpenedAtRef.current > 0 &&
+      Date.now() - hoverOpenedAtRef.current < clickGuardMs;
+    if (!isConfirming) {
+      return false;
     }
-  }, [isOpen, clearTimeouts, show, hide, focusFirst]);
+    hoverModeRef.current = false;
+    hoverOpenedAtRef.current = 0;
+    return true;
+  }, [clickGuardMs]);
+
+  const handleClick = useCallback(
+    (event?: React.MouseEvent) => {
+      // Cancel the invoker's default toggle so this handler stays the single
+      // source of truth; popoverTarget still exempts the trigger from dismissal.
+      if (popoverId) {
+        event?.preventDefault();
+      }
+      clearTimeouts();
+
+      // Enter/Space arrive as a click with detail 0, and always open. A keyboard
+      // user reaches the trigger of an open menu only because a hover-open left
+      // focus behind; closing there would stranded them outside a visible menu.
+      const isKeyboardActivation = event != null && event.detail === 0;
+      if (isKeyboardActivation) {
+        closedAtRef.current = 0;
+        hoverModeRef.current = false;
+        hoverOpenedAtRef.current = 0;
+        if (isOpen) {
+          if (ownsFocus) {
+            focusMenu();
+          }
+        } else {
+          openAndFocus();
+        }
+        return;
+      }
+
+      if (!isOpen) {
+        closedAtRef.current = 0;
+        hoverModeRef.current = false;
+        hoverOpenedAtRef.current = 0;
+        openAndFocus();
+        return;
+      }
+
+      if (confirmHoverOpen()) {
+        if (ownsFocus) {
+          focusMenu();
+        }
+        return;
+      }
+
+      hideAndRestoreFocus();
+    },
+    [
+      popoverId,
+      clearTimeouts,
+      isOpen,
+      ownsFocus,
+      confirmHoverOpen,
+      openAndFocus,
+      focusMenu,
+      hideAndRestoreFocus,
+    ],
+  );
 
-  // Hover: mouseenter activates hover mode and opens
   const handleMouseEnter = useCallback(() => {
     if (!hasHover) {
       return;
     }
-    if (skipNextEnterRef.current) {
-      skipNextEnterRef.current = false;
+    if (
+      closedAtRef.current > 0 &&
+      Date.now() - closedAtRef.current < REOPEN_SUPPRESS_MS
+    ) {
+      return;
+    }
+    // Re-entering an open menu's trigger must not un-pin it or re-arm the
+    // guard, which would make the next deliberate click another "confirm" and
+    // leave the menu undismissable.
+    if (isOpen) {
+      clearTimeouts();
       return;
     }
     hoverModeRef.current = true;
     clearTimeouts();
+    const openByHover = () => {
+      hoverOpenedAtRef.current = Date.now();
+      show({skipAutoFocus: true});
+    };
     if (showDelay > 0) {
-      showTimerRef.current = setTimeout(() => {
-        show({skipAutoFocus: true});
-      }, showDelay);
+      showTimerRef.current = setTimeout(openByHover, showDelay);
     } else {
-      show({skipAutoFocus: true});
+      openByHover();
     }
-  }, [hasHover, clearTimeouts, show, showDelay]);
+  }, [hasHover, isOpen, clearTimeouts, show, showDelay]);
 
-  // Hover: mouseleave only closes if in hover mode
   const handleMouseLeave = useCallback(() => {
+    // A real leave ends the stationary-pointer case the suppression window
+    // exists for, so the next enter is deliberate whenever it arrives.
+    closedAtRef.current = 0;
     if (!hoverModeRef.current) {
       return;
     }
@@ -150,7 +340,6 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
     }, hideDelay);
   }, [clearTimeouts, hide, hideDelay]);
 
-  // Content: mouseenter cancels pending hide
   const handleContentMouseEnter = useCallback(() => {
     clearTimeouts();
   }, [clearTimeouts]);
@@ -173,6 +362,9 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
       },
       menuRef,
       focusFirst,
+      focusMenu,
+      confirmHoverOpen,
+      close: hideAndRestoreFocus,
       setTriggerEl: noopRef,
     };
   }
@@ -182,6 +374,7 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
       onClick: handleClick,
       onMouseEnter: handleMouseEnter,
       onMouseLeave: handleMouseLeave,
+      ...(popoverId ? {popoverTarget: popoverId} : null),
     },
     contentProps: {
       onMouseEnter: handleContentMouseEnter,
@@ -190,6 +383,9 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
     },
     menuRef,
     focusFirst,
+    focusMenu,
+    confirmHoverOpen,
+    close: hideAndRestoreFocus,
     setTriggerEl: setTriggerRef,
   };
 }

package/src/theme/defineTheme.test.ts

@@ -2,6 +2,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import type {IconRegistry} from '../Icon/globalIconRegistry';
+import type {DefinedTheme} from './defineTheme';
 import {defineTheme, generateThemeCSS, isDefinedTheme} from './defineTheme';
 
 function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
@@ -1126,4 +1127,130 @@ describe('defineTheme extends', () => {
       base.tokens['--font-size-base'],
     );
   });
+
+  it('inherits indicators when the child has none', () => {
+    const indicator = (() => null) as unknown as NonNullable<
+      DefinedTheme['indicators']
+    >['check'];
+    const base = defineTheme({name: 'base', indicators: {check: indicator}});
+    const child = defineTheme({name: 'child', extends: base});
+    expect(child.indicators?.check).toBe(indicator);
+  });
+
+  it('inherits onDark token overrides from base theme', () => {
+    const base = defineTheme({
+      name: 'base',
+      onDark: {tokens: {'--color-border': '#ffffff'}},
+    });
+    const child = defineTheme({name: 'child', extends: base});
+    expect(child.__onDark?.tokens['--color-border']).toBe('#ffffff');
+  });
+
+  it('inherits onLight token overrides from base theme', () => {
+    const base = defineTheme({
+      name: 'base',
+      onLight: {tokens: {'--color-border': '#000000'}},
+    });
+    const child = defineTheme({name: 'child', extends: base});
+    expect(child.__onLight?.tokens['--color-border']).toBe('#000000');
+  });
+
+  it('lets the child override an inherited onDark token', () => {
+    const base = defineTheme({
+      name: 'base',
+      onDark: {tokens: {'--color-border': '#ffffff', '--color-track': '#eee'}},
+    });
+    const child = defineTheme({
+      name: 'child',
+      extends: base,
+      onDark: {tokens: {'--color-border': '#cccccc'}},
+    });
+    expect(child.__onDark?.tokens['--color-border']).toBe('#cccccc');
+    expect(child.__onDark?.tokens['--color-track']).toBe('#eee');
+  });
+
+  it('inherits and deep-merges onDark component overrides', () => {
+    const base = defineTheme({
+      name: 'base',
+      onDark: {
+        components: {
+          card: {base: {borderColor: '#fff', backgroundColor: '#111'}},
+          badge: {base: {color: '#fff'}},
+        },
+      },
+    });
+    const child = defineTheme({
+      name: 'child',
+      extends: base,
+      onDark: {components: {card: {base: {borderColor: '#ccc'}}}},
+    });
+    expect(child.__onDark?.components?.card?.base).toEqual({
+      borderColor: '#ccc',
+      backgroundColor: '#111',
+    });
+    expect(child.__onDark?.components?.badge?.base).toEqual({color: '#fff'});
+  });
+
+  it('inherits __inputTokens so inherited [light, dark] tuples survive', () => {
+    const base = defineTheme({
+      name: 'base',
+      tokens: {'--color-accent': ['#111111', '#eeeeee']},
+    });
+    const child = defineTheme({
+      name: 'child',
+      extends: base,
+      tokens: {'--color-border': '#cccccc'},
+    });
+    expect(child.__inputTokens?.['--color-accent']).toEqual([
+      '#111111',
+      '#eeeeee',
+    ]);
+    expect(child.__inputTokens?.['--color-border']).toBe('#cccccc');
+  });
+
+  it('__inputTokens from the child win over the base', () => {
+    const base = defineTheme({
+      name: 'base',
+      tokens: {'--color-accent': ['#111111', '#eeeeee']},
+    });
+    const child = defineTheme({
+      name: 'child',
+      extends: base,
+      tokens: {'--color-accent': '#ff0000'},
+    });
+    expect(child.__inputTokens?.['--color-accent']).toBe('#ff0000');
+  });
+
+  // The failure that motivated these: `extends` resolving to `undefined` (a
+  // named import that silently missed — see the theme-build resolution tests)
+  // used to inherit nothing and build a stylesheet that looked fine.
+  it('throws when extends is present but undefined', () => {
+    expect(() =>
+      defineTheme({
+        name: 'child',
+        extends: undefined,
+        tokens: {'--color-accent': '#ff0000'},
+      }),
+    ).toThrow(/extends/);
+  });
+
+  it('throws when extends is not a theme', () => {
+    expect(() =>
+      defineTheme({
+        name: 'child',
+        // A module namespace object is the shape a bad import hands over.
+        extends: {foo: 'bar'} as unknown as DefinedTheme,
+      }),
+    ).toThrow(/extends/);
+  });
+
+  it('accepts a pre-built theme module as a base', () => {
+    const built = {
+      name: 'built-base',
+      __built: true,
+      tokens: {'--color-accent': '#111111'},
+    } as DefinedTheme;
+    const child = defineTheme({name: 'child', extends: built});
+    expect(child.tokens['--color-accent']).toBe('#111111');
+  });
 });