@primitiv-ui/react 0.1.0

package/src/Dropdown/__tests__/Dropdown.trigger.test.tsx

@@ -0,0 +1,110 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Dropdown } from "../Dropdown";
+
+describe("Dropdown trigger", () => {
+  it("toggles aria-expanded when the trigger is clicked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Dropdown.Root>
+        <Dropdown.Trigger>Options</Dropdown.Trigger>
+      </Dropdown.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Options" });
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+
+    // Act
+    await user.click(trigger);
+
+    // Assert
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+
+    // Act again
+    await user.click(trigger);
+
+    // Assert
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("drives the native popover open/closed when the trigger is clicked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Dropdown.Root>
+        <Dropdown.Trigger>Options</Dropdown.Trigger>
+        <Dropdown.Content>Items</Dropdown.Content>
+      </Dropdown.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Options" });
+    const menu = screen.getByRole("menu", { hidden: true });
+    // Popover polyfill: open state is mirrored to `data-popover-open`.
+    expect(menu).not.toHaveAttribute("data-popover-open");
+
+    // Act
+    await user.click(trigger);
+
+    // Assert
+    expect(menu).toHaveAttribute("data-popover-open");
+
+    // Act
+    await user.click(trigger);
+
+    // Assert
+    expect(menu).not.toHaveAttribute("data-popover-open");
+  });
+
+  it("syncs aria-expanded to false when the popover is light-dismissed by clicking outside", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Dropdown.Root>
+        <Dropdown.Trigger>Options</Dropdown.Trigger>
+        <Dropdown.Content>
+          <Dropdown.Item>Rename</Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Options" });
+
+    // Act — open, then light-dismiss by clicking outside the popover
+    await user.click(trigger);
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    await user.click(document.body);
+
+    // Assert
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("does not route a trigger click through the outside-click listener", async () => {
+    // The Content's outside-click listener must ignore clicks on the trigger
+    // itself — the trigger's own onClick already decides whether to open or
+    // close. Without this guard, a trigger click while open would produce two
+    // onOpenChange(false) calls (one from the trigger, one from the document
+    // listener), and the opening click on a freshly-mounted trigger would be
+    // seen as "outside" and self-dismiss the popover (this manifests in real
+    // browsers where React 19 can flush the opening commit's effects
+    // synchronously, leaving the listener attached before the click bubbles
+    // to the document).
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    render(
+      <Dropdown.Root defaultOpen onOpenChange={onOpenChange}>
+        <Dropdown.Trigger>Options</Dropdown.Trigger>
+        <Dropdown.Content>
+          <Dropdown.Item>Rename</Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Options" });
+
+    // Act — click the trigger while the menu is open
+    await user.click(trigger);
+
+    // Assert — exactly one onOpenChange(false): from the trigger's own
+    // onClick, not a duplicate from the document listener.
+    expect(onOpenChange).toHaveBeenCalledTimes(1);
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+});

package/src/Dropdown/__tests__/Dropdown.typeahead.test.tsx

@@ -0,0 +1,133 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Dropdown } from "../Dropdown";
+
+describe("Dropdown typeahead", () => {
+  it("moves focus to the next item starting with the typed letter", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Dropdown.Root defaultOpen>
+        <Dropdown.Trigger>Options</Dropdown.Trigger>
+        <Dropdown.Content>
+          <Dropdown.Item>Apple</Dropdown.Item>
+          <Dropdown.Item>Banana</Dropdown.Item>
+          <Dropdown.Item>Cherry</Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>,
+    );
+    const banana = screen.getByRole("menuitem", { name: "Banana", hidden: true });
+
+    // Act
+    await user.keyboard("b");
+
+    // Assert
+    expect(banana).toHaveFocus();
+  });
+
+  it("resets the typeahead query after a pause so the next keystroke starts a fresh search", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Dropdown.Root defaultOpen>
+        <Dropdown.Trigger>Options</Dropdown.Trigger>
+        <Dropdown.Content>
+          <Dropdown.Item>Banana</Dropdown.Item>
+          <Dropdown.Item>Cherry</Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>,
+    );
+    const banana = screen.getByRole("menuitem", {
+      name: "Banana",
+      hidden: true,
+    });
+    const cherry = screen.getByRole("menuitem", {
+      name: "Cherry",
+      hidden: true,
+    });
+
+    // Act — match "Banana"
+    await user.keyboard("b");
+    expect(banana).toHaveFocus();
+
+    // Act — wait past the typeahead reset window, then start a fresh search
+    await new Promise((resolve) => setTimeout(resolve, 600));
+    await user.keyboard("c");
+
+    // Assert — the query did not accumulate to "bc"; it reset to "c"
+    expect(cherry).toHaveFocus();
+  });
+
+  it("cycles through items sharing a starting letter when the same letter is pressed repeatedly", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Dropdown.Root defaultOpen>
+        <Dropdown.Trigger>Options</Dropdown.Trigger>
+        <Dropdown.Content>
+          <Dropdown.Item>Apple</Dropdown.Item>
+          <Dropdown.Item>Apricot</Dropdown.Item>
+          <Dropdown.Item>Avocado</Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>,
+    );
+    const apple = screen.getByRole("menuitem", { name: "Apple", hidden: true });
+    const apricot = screen.getByRole("menuitem", {
+      name: "Apricot",
+      hidden: true,
+    });
+    const avocado = screen.getByRole("menuitem", {
+      name: "Avocado",
+      hidden: true,
+    });
+    expect(apple).toHaveFocus();
+
+    // Act
+    await user.keyboard("a");
+
+    // Assert
+    expect(apricot).toHaveFocus();
+
+    // Act
+    await user.keyboard("a");
+
+    // Assert
+    expect(avocado).toHaveFocus();
+
+    // Act — wraps back to Apple
+    await user.keyboard("a");
+
+    // Assert
+    expect(apple).toHaveFocus();
+  });
+
+  it("ignores non-printable keys so they do not pollute the typeahead query", () => {
+    // Arrange
+    render(
+      <Dropdown.Root defaultOpen>
+        <Dropdown.Trigger>Options</Dropdown.Trigger>
+        <Dropdown.Content>
+          <Dropdown.Item>Apple</Dropdown.Item>
+          <Dropdown.Item>Banana</Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>,
+    );
+    const menu = screen.getByRole("menu", { hidden: true });
+    const banana = screen.getByRole("menuitem", {
+      name: "Banana",
+      hidden: true,
+    });
+
+    // Act — "Tab" is a multi-character event.key (length 3), so the
+    //        typeahead branch must be skipped. If the length guard
+    //        weren't there, the query would accumulate to "tabb" after
+    //        the following "b" press and no item would match.
+    fireEvent.keyDown(menu, { key: "Tab" });
+    fireEvent.keyDown(menu, { key: "b" });
+
+    // Assert — the "Tab" press did not contribute to the typeahead
+    //          query; "b" started a fresh search and matched Banana.
+    expect(banana).toHaveFocus();
+  });
+});

package/src/Dropdown/constants.ts

@@ -0,0 +1,4 @@
+export const MENUITEM_SELECTOR =
+  '[role="menuitem"]:not([aria-disabled="true"]), [role="menuitemcheckbox"]:not([aria-disabled="true"]), [role="menuitemradio"]:not([aria-disabled="true"])';
+
+export const TYPEAHEAD_RESET_MS = 500;

package/src/Dropdown/hooks/index.ts

@@ -0,0 +1,9 @@
+export { useCloseSiblingSub } from "./useCloseSiblingSub";
+export { useDropdownContent } from "./useDropdownContent";
+export { useDropdownContext } from "./useDropdownContext";
+export { useDropdownGroup } from "./useDropdownGroup";
+export { useDropdownItem } from "./useDropdownItem";
+export { useDropdownLabel } from "./useDropdownLabel";
+export { useDropdownRoot } from "./useDropdownRoot";
+export { useDropdownSubContext } from "./useDropdownSubContext";
+export { useDropdownTrigger } from "./useDropdownTrigger";

package/src/Dropdown/hooks/useCloseSiblingSub.ts

@@ -0,0 +1,13 @@
+import { useContext } from "react";
+import { DropdownContentContext } from "../DropdownContentContext";
+
+/**
+ * Returns a callback that closes any direct-child sub-menu registered with
+ * the enclosing {@link DropdownContent} / {@link DropdownSubContent}. Items
+ * invoke this on mouse-enter so hovering a sibling dismisses an open sub,
+ * mirroring the keyboard contract.
+ */
+export function useCloseSiblingSub() {
+  const content = useContext(DropdownContentContext);
+  return () => content?.closeOpenSubRef.current?.();
+}

package/src/Dropdown/hooks/useDropdownContent.ts

@@ -0,0 +1,162 @@
+import { useRef, useEffect, useMemo, KeyboardEventHandler } from "react";
+import { composeEventHandlers } from "../../Slot";
+import { MENUITEM_SELECTOR, TYPEAHEAD_RESET_MS } from "../constants";
+import { useDropdownContext } from "./useDropdownContext";
+import { DropdownContentProps } from "../types";
+
+type UseDropdownContentArgs = {
+  onKeyDown?: KeyboardEventHandler;
+  restProps: Omit<DropdownContentProps, "children" | "onKeyDown" | "asChild">;
+};
+
+export function useDropdownContent({
+  onKeyDown,
+  restProps,
+}: UseDropdownContentArgs) {
+  const { open, setOpen, contentId, triggerRef } = useDropdownContext();
+  const menuRef = useRef<HTMLMenuElement | null>(null);
+  const typeaheadRef = useRef<{ query: string; timer: number | null }>({
+    query: "",
+    timer: null,
+  });
+
+  useEffect(() => {
+    const menu = menuRef.current!;
+    if (open) {
+      menu.showPopover();
+      if (!menu.contains(document.activeElement)) {
+        const firstItem = menu.querySelector<HTMLElement>(MENUITEM_SELECTOR);
+        firstItem?.focus();
+      }
+    } else {
+      try {
+        menu.hidePopover();
+      } catch {
+        // already hidden — no-op (e.g. browser already light-dismissed it)
+      }
+    }
+  }, [open]);
+
+  // Sync React state when the browser closes the popover without our code
+  // doing it (real-browser ToggleEvent on light-dismiss or native Escape).
+  useEffect(() => {
+    const menu = menuRef.current!;
+    const handleToggle = (event: Event) => {
+      if ((event as ToggleEvent).newState === "closed") setOpen(false);
+    };
+    menu.addEventListener("toggle", handleToggle);
+    return () => menu.removeEventListener("toggle", handleToggle);
+  }, [setOpen]);
+
+  // Close on clicks outside the popover (belt-and-suspenders for environments
+  // where the native toggle event is not dispatched on light-dismiss, e.g.
+  // jsdom). Attached only while open. Clicks on the trigger are ignored —
+  // the trigger's own onClick already decides whether to open or close, and
+  // if this listener handled the trigger too it would immediately close the
+  // popover on the opening click (React 19 can flush the opening commit's
+  // effects synchronously, so the listener is already attached by the time
+  // the click bubbles up to the document). Clicks inside any [popover] are
+  // ignored so nested sub-menus don't close their parent.
+  useEffect(() => {
+    if (!open) return;
+    const handleClick = (event: MouseEvent) => {
+      const target = event.target as Element;
+      if (triggerRef.current?.contains(target)) return;
+      if (target.closest?.("[popover]")) return;
+      setOpen(false);
+    };
+    document.addEventListener("click", handleClick);
+    return () => document.removeEventListener("click", handleClick);
+  }, [open, setOpen, triggerRef]);
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLMenuElement>) => {
+    const menu = menuRef.current!;
+    // Sub-menus mount their own [popover] inside this menu's subtree, so a
+    // naive querySelectorAll would also pick up items in nested
+    // SubContents — items the user can't focus while the sub is closed
+    // (display:none) and shouldn't reach by arrow key while it's open. Scope
+    // to the popover holding focus, then drop anything that lives in a
+    // deeper popover (a closed sub at this same level).
+    const focused = document.activeElement as HTMLElement | null;
+    const scope = (focused?.closest("[popover]") as HTMLElement | null) ?? menu;
+    const items = Array.from(
+      scope.querySelectorAll<HTMLElement>(MENUITEM_SELECTOR),
+    ).filter((el) => el.closest("[popover]") === scope);
+    if (items.length === 0) return;
+    const currentIndex = items.indexOf(document.activeElement as HTMLElement);
+
+    let nextIndex: number | null = null;
+    if (event.key === "ArrowDown") {
+      nextIndex = (currentIndex + 1) % items.length;
+    } else if (event.key === "ArrowUp") {
+      nextIndex = currentIndex <= 0 ? items.length - 1 : currentIndex - 1;
+    } else if (event.key === "Home") {
+      nextIndex = 0;
+    } else if (event.key === "End") {
+      nextIndex = items.length - 1;
+    }
+
+    if (nextIndex !== null) {
+      event.preventDefault();
+      items[nextIndex].focus();
+      return;
+    }
+
+    if (event.key === "Enter" || event.key === " ") {
+      if (currentIndex < 0) return;
+      event.preventDefault();
+      items[currentIndex].click();
+      return;
+    }
+
+    if (event.key === "Escape") {
+      event.preventDefault();
+      setOpen(false);
+      triggerRef.current?.focus();
+      return;
+    }
+
+    if (event.key.length === 1 && event.key !== " ") {
+      const state = typeaheadRef.current;
+      if (state.timer !== null) window.clearTimeout(state.timer);
+      state.query = (state.query + event.key).toLowerCase();
+      state.timer = window.setTimeout(() => {
+        state.query = "";
+        state.timer = null;
+      }, TYPEAHEAD_RESET_MS);
+
+      const isRepeat =
+        state.query.length > 1 &&
+        state.query.split("").every((c) => c === state.query[0]);
+      const searchQuery = isRepeat ? state.query[0] : state.query;
+      const startIndex = currentIndex < 0 ? 0 : currentIndex;
+      const offset = searchQuery.length === 1 || isRepeat ? 1 : 0;
+      for (let i = 0; i < items.length; i++) {
+        const index = (startIndex + offset + i) % items.length;
+        const text = items[index].textContent!.trim().toLowerCase();
+        if (text.startsWith(searchQuery)) {
+          event.preventDefault();
+          items[index].focus();
+          return;
+        }
+      }
+    }
+  };
+
+  const closeOpenSubRef = useRef<(() => void) | null>(null);
+  const contentContextValue = useMemo(() => ({ closeOpenSubRef }), []);
+
+  const contentProps = {
+    ...restProps,
+    ref: menuRef,
+    id: contentId,
+    role: "menu" as const,
+    popover: "auto" as const,
+    onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+  };
+
+  return {
+    contentContextValue,
+    contentProps,
+  };
+}

package/src/Dropdown/hooks/useDropdownContext.ts

@@ -0,0 +1 @@
+export { useDropdownContext } from "../DropdownContext";

package/src/Dropdown/hooks/useDropdownGroup.ts

@@ -0,0 +1,18 @@
+import { useId, useMemo } from "react";
+import { DropdownGroupProps } from "../types";
+
+type UseDropdownGroupArgs = {
+  restProps: Omit<DropdownGroupProps, "children" | "asChild">;
+};
+
+export function useDropdownGroup({ restProps }: UseDropdownGroupArgs) {
+  const labelId = useId();
+  const contextValue = useMemo(() => ({ labelId }), [labelId]);
+  const groupProps = {
+    ...restProps,
+    role: "group" as const,
+    "aria-labelledby": labelId,
+  };
+
+  return { contextValue, groupProps };
+}

package/src/Dropdown/hooks/useDropdownItem.ts

@@ -0,0 +1,49 @@
+import { MouseEventHandler, useState } from "react";
+import { composeEventHandlers, SlotProps } from "../../Slot";
+import { useCloseSiblingSub } from "./useCloseSiblingSub";
+import { useDropdownContext } from "./useDropdownContext";
+import { DropdownItemProps } from "../types";
+
+type UseDropdownItemArgs = {
+  disabled?: boolean;
+  onClick?: MouseEventHandler<HTMLLIElement>;
+  onSelect?: (event: Event) => void;
+  restProps: Omit<DropdownItemProps, "children" | "asChild">;
+};
+
+export function useDropdownItem({
+  disabled,
+  onClick,
+  onSelect,
+  restProps,
+}: UseDropdownItemArgs) {
+  const { setOpen, triggerRef } = useDropdownContext();
+  const closeSiblingSub = useCloseSiblingSub();
+  const [highlighted, setHighlighted] = useState(false);
+  const handleClick = () => {
+    if (disabled) return;
+    const event = new Event("dropdown.select", { cancelable: true });
+    onSelect?.(event);
+    if (!event.defaultPrevented) {
+      setOpen(false);
+      triggerRef.current?.focus();
+    }
+  };
+  const itemProps = {
+    ...restProps,
+    role: "menuitem" as const,
+    tabIndex: -1,
+    "aria-disabled": disabled || undefined,
+    "data-highlighted": highlighted ? "" : undefined,
+    onClick: composeEventHandlers(onClick, handleClick),
+    onMouseEnter: composeEventHandlers(restProps.onMouseEnter, () => {
+      setHighlighted(true);
+      closeSiblingSub();
+    }),
+    onMouseLeave: composeEventHandlers(restProps.onMouseLeave, () =>
+      setHighlighted(false),
+    ),
+  } as Omit<SlotProps, "children">;
+
+  return { itemProps };
+}

package/src/Dropdown/hooks/useDropdownLabel.ts

@@ -0,0 +1,15 @@
+import { useContext } from "react";
+import { DropdownGroupContext } from "../DropdownGroupContext";
+import { DropdownLabelProps } from "../types";
+
+type UseDropdownLabelArgs = {
+  id?: string;
+  restProps: Omit<DropdownLabelProps, "id" | "children" | "asChild">;
+};
+
+export function useDropdownLabel({ id, restProps }: UseDropdownLabelArgs) {
+  const group = useContext(DropdownGroupContext);
+  const labelProps = { ...restProps, id: id ?? group?.labelId };
+
+  return { labelProps };
+}

package/src/Dropdown/hooks/useDropdownRoot.ts

@@ -0,0 +1,57 @@
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+} from "react";
+
+import { Direction } from "../../DirectionProvider";
+import { useControllableState } from "../../hooks";
+
+type UseDropdownRootArgs = {
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  dir?: Direction;
+};
+
+export function useDropdownRoot({
+  defaultOpen = false,
+  open: controlledOpen,
+  onOpenChange,
+  dir = "ltr",
+}: UseDropdownRootArgs) {
+  const contentId = useId();
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const [open, setOpenBase] = useControllableState<boolean>(
+    controlledOpen,
+    defaultOpen,
+    onOpenChange,
+  );
+  // Mirror `open` so setOpen can short-circuit repeat transitions within a
+  // single event without a re-render in between. Without this, internal
+  // paths that converge on the same close (e.g. a light-dismiss firing
+  // both a `toggle` event and a document click) would double-notify
+  // consumers via onOpenChange.
+  const openRef = useRef(open);
+  useEffect(() => {
+    openRef.current = open;
+  });
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (openRef.current === next) return;
+      openRef.current = next;
+      setOpenBase(next);
+    },
+    [setOpenBase],
+  );
+
+  const contextValue = useMemo(
+    () => ({ open, setOpen, contentId, triggerRef, dir }),
+    [open, setOpen, contentId, dir],
+  );
+
+  return { open, setOpen, contextValue };
+}

package/src/Dropdown/hooks/useDropdownSubContext.ts

@@ -0,0 +1 @@
+export { useDropdownSubContext } from "../DropdownSubContext";

package/src/Dropdown/hooks/useDropdownTrigger.ts

@@ -0,0 +1,31 @@
+import { MouseEventHandler } from "react";
+import { composeEventHandlers } from "../../Slot";
+import { DropdownTriggerProps } from "../types";
+import { useDropdownContext } from "./useDropdownContext";
+
+type UseDropdownTriggerArgs = {
+  onClick?: MouseEventHandler;
+  restProps: Omit<DropdownTriggerProps, "children" | "onClick" | "asChild">;
+};
+
+export function useDropdownTrigger({
+  onClick,
+  restProps,
+}: UseDropdownTriggerArgs) {
+  const { open, setOpen, contentId, triggerRef } = useDropdownContext();
+
+  const toggle = () => setOpen(!open);
+
+  const triggerProps = {
+    ...restProps,
+    ref: triggerRef,
+    "aria-haspopup": "menu" as const,
+    "aria-expanded": open,
+    "aria-controls": contentId,
+    onClick: composeEventHandlers(onClick, toggle),
+  };
+
+  return {
+    triggerProps,
+  };
+}

package/src/Dropdown/index.ts

@@ -0,0 +1 @@
+export { Dropdown } from "./Dropdown";