@elabs-ai/components-ui 4.0.0 → 4.1.0

package/src/components/nav-notifications/nav-notifications.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import type { ComponentProps } from "react";
 import { BellIcon } from "lucide-react";
 import { Avatar, AvatarFallback } from "../avatar";
 import { Button } from "../button";
@@ -11,6 +12,8 @@ import {
   DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "../dropdown-menu";
+import { useLocale } from "../locale-provider";
+import { cn } from "../../lib/cn";
 
 export interface NavNotification {
   id: string;
@@ -24,30 +27,79 @@ export interface NavNotificationsProps {
   notifications: NavNotification[];
   /** Label for the "view all" footer item. @default "View all notifications" */
   viewAllLabel?: string;
+  /**
+   * Which side of the trigger the menu opens on.
+   *
+   * The default is `"right"`, which is right for the surface this component was
+   * extracted from — a bell sitting in a left-hand nav rail. It is WRONG for a
+   * trigger at the end of a top bar: Radix collision-handling then flips the
+   * menu back across the trigger and it covers the controls beside it. Set
+   * `side="bottom"` (usually with `align="end"`) for a top-bar bell.
+   *
+   * @default "right"
+   */
+  side?: ComponentProps<typeof DropdownMenuContent>["side"];
+  /**
+   * How the menu aligns along that side. Radix's own default is `"center"`;
+   * pass `"end"` so a top-bar menu hangs from the trigger's outer edge instead
+   * of straddling it.
+   */
+  align?: ComponentProps<typeof DropdownMenuContent>["align"];
+  /**
+   * Extra classes for the component ROOT — the bell trigger — merged last, so a
+   * caller can override the shipped `rounded-full` (`component-api.md`).
+   *
+   * There is deliberately NO seam for the portalled menu surface: nothing needs
+   * one today, and an unused prop is a worse API than a missing one. The one
+   * thing a caller used to reach for it (dropping the rail's vertical inset for
+   * a top-bar menu) is now derived from `side` instead — see below.
+   */
+  className?: string;
 }
 
 /**
- * Sidebar notifications dropdown button. Shared primitive from sidebar-02 (issue #99).
- * Renders a bell-icon ghost button that opens a dropdown listing recent notifications.
+ * Notifications dropdown button. Shared primitive from sidebar-02 (issue #99).
+ * Renders a bell-icon ghost button that opens a dropdown listing recent
+ * notifications.
+ *
+ * Placement is caller-owned via `side`/`align`; the defaults are the original
+ * rail placement, so every existing call site renders unchanged. `className`
+ * styles the trigger, not the menu.
  */
 export function NavNotifications({
   notifications,
   viewAllLabel = "View all notifications",
+  side = "right",
+  align,
+  className,
 }: NavNotificationsProps) {
+  const { t } = useLocale();
   return (
     <DropdownMenu>
       <DropdownMenuTrigger asChild>
         <Button
           variant="ghost"
           size="icon"
-          className="rounded-full"
+          className={cn("rounded-full", className)}
           aria-label="Open notifications"
         >
           <BellIcon className="size-5" />
         </Button>
       </DropdownMenuTrigger>
-      <DropdownMenuContent side="right" className="my-6 w-80">
-        <DropdownMenuLabel>Notifications</DropdownMenuLabel>
+      <DropdownMenuContent
+        side={side}
+        align={align}
+        className={cn(
+          // The vertical inset belongs to the SIDE-opening rail placement, where
+          // the menu runs alongside its trigger and needs clearance from it. A
+          // menu that opens above or below the trigger is already clear of it,
+          // and the inset would just hang it 24px off the bar. Derived from
+          // `side` rather than exposed as a second className seam.
+          (side === "left" || side === "right") && "my-6",
+          "w-80",
+        )}
+      >
+        <DropdownMenuLabel>{t("ui.navNotifications.label")}</DropdownMenuLabel>
         <DropdownMenuSeparator />
         {notifications.map(({ id, fallback, text, time }) => (
           <DropdownMenuItem key={id} className="flex items-start gap-3">

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

@@ -86,7 +86,29 @@ export const Default: Story = {
     const analytics = await canvas.findByText("Analytics");
     await waitFor(() => expect(analytics).toBeVisible());
     await waitFor(() => expect(canvas.getByText("Data Integration")).toBeVisible());
+    // userEvent.click() synthesizes a real pointer sequence (pointerenter +
+    // pointermove before the click), which — independently of the click's own
+    // open — arms Radix's hover-intent open timer inside
+    // @radix-ui/react-navigation-menu's NavigationMenu root (delayDuration,
+    // default 200ms). That timer is cleared only by a subsequent pointer
+    // leave/enter, never by the click-open path or by Escape's dismiss path,
+    // so left alone it fires ~200ms after this interaction regardless of the
+    // explicit Escape below — silently reopening the menu well after play()
+    // has returned (confirmed via instrumentation: aria-expanded flips back
+    // to "true" at ~t+207ms). That reopen is what axe's afterEach scan was
+    // intermittently catching — a real defect in the underlying menu, not a
+    // wrong wait condition; filed separately (residual, not fixed here).
+    // Unhovering cancels that stray timer through Radix's own cancellation
+    // path (onTriggerLeave), the same way a real user moving the pointer away
+    // before dismissing would.
+    await userEvent.unhover(trigger);
     // Escape dismisses the open panel
     await userEvent.keyboard("{Escape}");
+    // Wait for the close transition to complete via a real post-condition:
+    // aria-expanded flips to "false" in the same React commit that removes
+    // the trigger's aria-hidden focus-proxy span (both derive from the same
+    // `open` value in NavigationMenuTrigger's render), so this dominates the
+    // axe scan that runs immediately after play() resolves.
+    await waitFor(() => expect(trigger).toHaveAttribute("aria-expanded", "false"));
   },
 };

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

@@ -0,0 +1,174 @@
+import { act, cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  NavigationMenu,
+  NavigationMenuContent,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  NavigationMenuTrigger,
+} from "./navigation-menu";
+
+afterEach(cleanup);
+
+function renderMenu() {
+  render(
+    <NavigationMenu>
+      <NavigationMenuList>
+        <NavigationMenuItem>
+          <NavigationMenuTrigger>Products</NavigationMenuTrigger>
+          <NavigationMenuContent>
+            <NavigationMenuLink href="#">Analytics</NavigationMenuLink>
+          </NavigationMenuContent>
+        </NavigationMenuItem>
+      </NavigationMenuList>
+    </NavigationMenu>,
+  );
+}
+
+describe("NavigationMenuTrigger", () => {
+  /**
+   * Residual of #54 (issue #85). `userEvent.click()` — like a real mouse click
+   * — synthesizes a pointer move onto the trigger before the click itself,
+   * which arms `@radix-ui/react-navigation-menu`'s root-level hover-intent
+   * open timer (`openTimerRef`, default `delayDuration` 200ms). Neither the
+   * click-open path (`onItemSelect`) nor any dismiss path (Escape /
+   * outside-click / focus-out, all funnelled through one
+   * `ROOT_CONTENT_DISMISS` handler) clears that timer, so — left unpatched —
+   * it fires ~200ms later and silently reopens the panel even though the user
+   * already dismissed it.
+   *
+   * Fake timers are load-bearing here, not incidental: asserting
+   * `aria-expanded` immediately after Escape passes on the UNPATCHED wrapper
+   * too, because the stray timer has not fired yet. The lock only means
+   * anything once the assertion runs from INSIDE the delay window.
+   */
+  it("does not spontaneously reopen after Escape dismisses it inside the hover-intent delay window", async () => {
+    // `shouldAdvanceTime` keeps the fake clock ticking in step with real time
+    // (in addition to responding to explicit `advanceTimersByTime` calls)
+    // so React's own scheduler — which falls back to a real `setTimeout` for
+    // its internal flush in this jsdom environment — is never left waiting
+    // on a fake timer nothing ever advances; plain `vi.useFakeTimers()` here
+    // hangs `userEvent.click()` indefinitely for exactly that reason.
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+    try {
+      const user = userEvent.setup({ delay: null, advanceTimers: vi.advanceTimersByTime });
+      renderMenu();
+      const trigger = screen.getByRole("button", { name: /products/i });
+
+      // Deliberately the opposite of #54's story-level unhover() workaround:
+      // hover-then-click with NO intervening pointer-leave, so the real
+      // click-then-dismiss sequence is exercised instead of routed around it.
+      await user.click(trigger);
+      expect(trigger).toHaveAttribute("aria-expanded", "true");
+
+      await user.keyboard("{Escape}");
+      expect(trigger).toHaveAttribute("aria-expanded", "false");
+
+      // Advance past delayDuration (200ms) + a margin so the stray timer, if
+      // still armed, fires.
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(300);
+      });
+
+      expect(trigger).toHaveAttribute("aria-expanded", "false");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  /**
+   * Acceptance criterion from #85: the fix must not regress ordinary
+   * click-to-toggle behaviour into the "menu never opens" failure mode hit by
+   * an earlier, abandoned `delayDuration={0}` attempt. Several rapid
+   * open/close/open cycles, entirely via click (no hover), must all still
+   * land the menu in the expected state.
+   */
+  it("still opens and closes normally across rapid repeated click cycles", async () => {
+    const user = userEvent.setup();
+    renderMenu();
+    const trigger = screen.getByRole("button", { name: /products/i });
+
+    for (let cycle = 0; cycle < 3; cycle += 1) {
+      await user.click(trigger);
+      expect(trigger).toHaveAttribute("aria-expanded", "true");
+
+      await user.click(trigger);
+      expect(trigger).toHaveAttribute("aria-expanded", "false");
+    }
+  });
+
+  /**
+   * Fix-round-1 regression (validator finding): a synthetic pointer-leave
+   * dispatched on every click — the first attempt at fixing #85 — runs
+   * Radix's real `onTriggerLeave`, which does two things, not one: it clears
+   * the stray open timer (wanted) AND unconditionally arms Radix's 150ms
+   * close timer (`startCloseTimer`/`closeTimerRef`, unwanted) via
+   * `context.onTriggerLeave` (`@radix-ui/react-navigation-menu@1.2.14 and
+   * 1.2.22`'s index.mjs, root `onTriggerLeave`). Since a click-opened menu
+   * never gets a real pointerenter on its content, nothing ever clears that
+   * close timer, so it silently closes itself ~150ms after every click-open
+   * unless the mouse happens to move onto the panel — breaking keyboard and
+   * touch entry entirely, and any mouse user who pauses before reaching the
+   * panel. This test opens the menu via click and asserts it is STILL OPEN
+   * well past that delay with no further pointer interaction at all.
+   */
+  it("stays open past the close-timer delay when opened by click with no further pointer movement", async () => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+    try {
+      const user = userEvent.setup({ delay: null, advanceTimers: vi.advanceTimersByTime });
+      renderMenu();
+      const trigger = screen.getByRole("button", { name: /products/i });
+
+      await user.click(trigger);
+      expect(trigger).toHaveAttribute("aria-expanded", "true");
+
+      // Advance well past both Radix's 150ms close-timer delay and its
+      // 200ms open-timer delay, with no further interaction of any kind.
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(400);
+      });
+
+      expect(trigger).toHaveAttribute("aria-expanded", "true");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  /**
+   * Fix-round-1 requirement: the guard against #85's stray reopen must be
+   * scoped to genuine, still-hovering pointer dismissals — it must never
+   * interfere with a pure keyboard sequence (no mouse involved at all).
+   * Opening and dismissing via keyboard alone must behave exactly as an
+   * unpatched menu would: the panel closes on Escape, focus returns to the
+   * trigger (Radix's own `triggerRef.current?.focus()` on dismiss), and
+   * nothing reopens it afterward.
+   */
+  it("keyboard: Escape dismisses, returns focus to the trigger, and does not reopen", async () => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+    try {
+      const user = userEvent.setup({ delay: null, advanceTimers: vi.advanceTimersByTime });
+      renderMenu();
+      const trigger = screen.getByRole("button", { name: /products/i });
+
+      act(() => {
+        trigger.focus();
+      });
+      await user.keyboard("{Enter}");
+      expect(trigger).toHaveAttribute("aria-expanded", "true");
+
+      await user.keyboard("{Escape}");
+      expect(trigger).toHaveAttribute("aria-expanded", "false");
+      expect(trigger).toHaveFocus();
+
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(300);
+      });
+
+      expect(trigger).toHaveAttribute("aria-expanded", "false");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

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

@@ -1,22 +1,164 @@
-import { forwardRef, type ComponentPropsWithoutRef, type ElementRef } from "react";
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentPropsWithoutRef,
+  type ElementRef,
+  type PointerEvent as ReactPointerEvent,
+} from "react";
 import * as NavigationMenuPrimitive from "@radix-ui/react-navigation-menu";
 import { cva } from "class-variance-authority";
 import { ChevronDown } from "lucide-react";
 import { cn } from "../../lib/cn";
 
+/**
+ * Residual of #54 (issue #85, fix round 1 → round 2): a pointer move onto a
+ * trigger arms `@radix-ui/react-navigation-menu`'s root-level hover-intent
+ * open timer (`openTimerRef`, default `delayDuration` 200ms — confirmed
+ * unchanged through `@radix-ui/react-navigation-menu@1.2.22`, the current
+ * latest stable). Neither the click-open path (root `onItemSelect`) nor any
+ * dismiss path (Escape, outside-click, focus-out — all funnelled through one
+ * `ROOT_CONTENT_DISMISS` handler → `onItemDismiss`) clears that timer, so it
+ * fires later and silently reopens the panel even after an explicit
+ * dismissal.
+ *
+ * Round 1 ran Radix's own `onTriggerLeave` cancellation path (a synthetic
+ * `pointerout`) on every click. That clears the stray open timer, but
+ * `onTriggerLeave` does two things, not one — it ALSO unconditionally arms
+ * Radix's 150ms close timer (`startCloseTimer`/`closeTimerRef`), which
+ * nothing then cancels for a click-opened (or keyboard/touch-opened) menu,
+ * since it never gets a real pointerenter on its content. Every click-opened
+ * menu silently closed itself ~150ms later. No supported, finer-grained Radix
+ * API exists to clear only the open timer — the 6 context callbacks
+ * (`onTriggerEnter`/`onTriggerLeave`/`onContentEnter`/`onContentLeave`/
+ * `onItemSelect`/`onItemDismiss`) are the only reachable surface, and none of
+ * the internal refs (`openTimerRef`, `closeTimerRef`, `wasClickCloseRef`,
+ * `wasEscapeCloseRef`) are exported.
+ *
+ * Round 2 fix: stop reaching into Radix's internal timers via synthetic
+ * events entirely. `NavigationMenu` takes over `value`/`onValueChange` as a
+ * controlled proxy (transparent to a consumer's own controlled/uncontrolled
+ * usage) and rejects, ONCE, a reopen request for an item that was just
+ * dismissed (value → "") while a REAL mouse pointer was still resting on its
+ * trigger — exactly the #85 scenario (dismissed inside the hover-intent
+ * window, pointer never left). The guard is a one-shot, pointer-scoped
+ * suppression per item (`suppressReopenForRef` in `NavigationMenu`, armed by
+ * `NavigationMenuItemValueContext` + a small guard context), cleared the
+ * instant ANY of the following happens, so it can never block a genuine
+ * interaction: (a) the real pointer leaves that trigger (a fresh hover-intent
+ * cycle is legitimate — Radix's own `wasEscapeCloseRef`/`wasClickCloseRef`
+ * guards reset on the same real pointerenter), or (b) any click on that
+ * trigger (`noteExplicitActivation`, which runs synchronously before Radix's
+ * own `onItemSelect` in the same click dispatch, per
+ * `composeEventHandlers(props.onClick, () => context.onItemSelect(...))` in
+ * `@radix-ui/react-navigation-menu`'s Trigger). A pure keyboard sequence never
+ * touches this guard at all (no pointer event ever marks the trigger as
+ * "resting"), so it cannot regress keyboard or touch entry — see the 3
+ * scenarios locked in `navigation-menu.test.tsx` (pointer dismiss stays
+ * dismissed, click-open survives past the close-timer delay with no pointer
+ * movement, keyboard open/Escape/no-reopen).
+ *
+ * `NavigationMenuItem` is wrapped (was a bare re-export) purely so its
+ * resolved item value — the same value Radix's OWN auto-`useId()` fallback
+ * would otherwise compute internally and never expose — is available to
+ * `NavigationMenuTrigger` without inventing a new public prop or reaching
+ * into Radix's non-exported item context.
+ *
+ * Tracked upstream: https://github.com/radix-ui/primitives/issues (file and
+ * link the specific issue here once opened — non-blocking, parallel to this
+ * interim fix; confirmed still present in 1.2.22, the latest stable release
+ * as of this fix).
+ */
+type NavigationMenuGuard = {
+  notePointerPresence(itemValue: string, present: boolean): void;
+  noteExplicitActivation(itemValue: string): void;
+  /** One-shot: returns true (and clears the flag) iff this reopen should be swallowed. */
+  consumeSuppressionFlag(itemValue: string): boolean;
+};
+
+const NavigationMenuGuardContext = createContext<NavigationMenuGuard | null>(null);
+const NavigationMenuItemValueContext = createContext<string | undefined>(undefined);
+
 export const NavigationMenu = forwardRef<
   ElementRef<typeof NavigationMenuPrimitive.Root>,
   ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Root>
->(function NavigationMenu({ className, children, ...props }, ref) {
+>(function NavigationMenu(
+  { className, children, value: valueProp, defaultValue, onValueChange, ...props },
+  ref,
+) {
+  const isControlled = valueProp !== undefined;
+  const [internalValue, setInternalValue] = useState(defaultValue ?? "");
+  const currentValue = isControlled ? (valueProp as string) : internalValue;
+  const currentValueRef = useRef(currentValue);
+  currentValueRef.current = currentValue;
+
+  // itemValue currently under a resting, real (mouse) pointer — at most one
+  // at a time in practice, since a real pointer can only be inside one
+  // trigger's bounds.
+  const pointerPresentForRef = useRef<string | null>(null);
+  // One-shot: the itemValue whose next reopen request should be swallowed.
+  const suppressReopenForRef = useRef<string | null>(null);
+
+  const guard = useMemo<NavigationMenuGuard>(
+    () => ({
+      notePointerPresence(itemValue, present) {
+        if (present) {
+          pointerPresentForRef.current = itemValue;
+          return;
+        }
+        if (pointerPresentForRef.current === itemValue) pointerPresentForRef.current = null;
+        // A genuine leave ends the suspicious window this guard exists for —
+        // any future reopen must come from a fresh interaction (a new
+        // hover-intent cycle after re-entering, or a click), both legitimate.
+        if (suppressReopenForRef.current === itemValue) suppressReopenForRef.current = null;
+      },
+      noteExplicitActivation(itemValue) {
+        if (suppressReopenForRef.current === itemValue) suppressReopenForRef.current = null;
+      },
+      consumeSuppressionFlag(itemValue) {
+        if (suppressReopenForRef.current === itemValue) {
+          suppressReopenForRef.current = null;
+          return true;
+        }
+        return false;
+      },
+    }),
+    [],
+  );
+
+  const handleValueChange = (next: string) => {
+    const previous = currentValueRef.current;
+    if (next === "") {
+      if (previous !== "" && pointerPresentForRef.current === previous) {
+        // Dismissed while a real pointer still rests on its trigger, inside
+        // the hover-intent window — the #85 defect. Arm the one-shot guard
+        // against exactly this item's next reopen request.
+        suppressReopenForRef.current = previous;
+      }
+    } else if (guard.consumeSuppressionFlag(next)) {
+      return; // Swallow the stray reopen — stay on `previous` (closed).
+    }
+    if (!isControlled) setInternalValue(next);
+    onValueChange?.(next);
+  };
+
   return (
-    <NavigationMenuPrimitive.Root
-      ref={ref}
-      className={cn("relative z-10 flex max-w-max flex-1 items-center justify-center", className)}
-      {...props}
-    >
-      {children}
-      <NavigationMenuViewport />
-    </NavigationMenuPrimitive.Root>
+    <NavigationMenuGuardContext.Provider value={guard}>
+      <NavigationMenuPrimitive.Root
+        ref={ref}
+        value={currentValue}
+        onValueChange={handleValueChange}
+        className={cn("relative z-10 flex max-w-max flex-1 items-center justify-center", className)}
+        {...props}
+      >
+        {children}
+        <NavigationMenuViewport />
+      </NavigationMenuPrimitive.Root>
+    </NavigationMenuGuardContext.Provider>
   );
 });
 
@@ -33,7 +175,18 @@ export const NavigationMenuList = forwardRef<
   );
 });
 
-export const NavigationMenuItem = NavigationMenuPrimitive.Item;
+export const NavigationMenuItem = forwardRef<
+  ElementRef<typeof NavigationMenuPrimitive.Item>,
+  ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Item>
+>(function NavigationMenuItem({ value: valueProp, ...props }, ref) {
+  const autoValue = useId();
+  const value = valueProp ?? autoValue;
+  return (
+    <NavigationMenuItemValueContext.Provider value={value}>
+      <NavigationMenuPrimitive.Item ref={ref} value={value} {...props} />
+    </NavigationMenuItemValueContext.Provider>
+  );
+});
 
 export const navigationMenuTriggerStyle = cva(
   "group inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2 text-sm font-medium transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:outline-none disabled:pointer-events-none disabled:opacity-50 data-[state=open]:bg-accent",
@@ -42,11 +195,35 @@ export const navigationMenuTriggerStyle = cva(
 export const NavigationMenuTrigger = forwardRef<
   ElementRef<typeof NavigationMenuPrimitive.Trigger>,
   ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Trigger>
->(function NavigationMenuTrigger({ className, children, ...props }, ref) {
+>(function NavigationMenuTrigger(
+  { className, children, onClick, onPointerEnter, onPointerLeave, ...props },
+  ref,
+) {
+  const itemValue = useContext(NavigationMenuItemValueContext);
+  const guard = useContext(NavigationMenuGuardContext);
+
+  const notePointer = (event: ReactPointerEvent<HTMLButtonElement>, present: boolean) => {
+    if (itemValue !== undefined && guard && event.pointerType === "mouse") {
+      guard.notePointerPresence(itemValue, present);
+    }
+  };
+
   return (
     <NavigationMenuPrimitive.Trigger
       ref={ref}
       className={cn(navigationMenuTriggerStyle(), "group", className)}
+      onPointerEnter={(event) => {
+        onPointerEnter?.(event);
+        notePointer(event, true);
+      }}
+      onPointerLeave={(event) => {
+        onPointerLeave?.(event);
+        notePointer(event, false);
+      }}
+      onClick={(event) => {
+        if (itemValue !== undefined) guard?.noteExplicitActivation(itemValue);
+        onClick?.(event);
+      }}
       {...props}
     >
       {children}