@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/menu/passport.json

@@ -0,0 +1,322 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Menu",
+    "folder": "menu",
+    "exports": [
+      "Menu",
+      "MenuCheckboxItem",
+      "MenuGroup",
+      "MenuItem",
+      "MenuRadioGroup",
+      "MenuRadioItem",
+      "MenuSeparator",
+      "MenuSub",
+      "TYPEAHEAD_RESET_MS"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/index.ts",
+      "core/navigation.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Menu.tsx",
+      "react/context.ts",
+      "react/items.tsx",
+      "react/locale.ts",
+      "react/props.ts",
+      "react/useMenuKeys.ts"
+    ],
+    "sourceHash": "sha256:694bed6a5743fac9406d91991fc23d4ce046ab1ed5f21be668f1971ccf6a15d4"
+  },
+  "props": [
+    {
+      "name": "align",
+      "type": "enum",
+      "values": [
+        "end",
+        "start"
+      ],
+      "typeText": "MenuAlign | undefined",
+      "required": false,
+      "default": "start",
+      "origin": "derived",
+      "description": "Default `start`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "checked",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "children",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": true,
+      "origin": "derived"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<MenuSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "closeOnSelect",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Close the menu when an item is chosen. Default true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "defaultOpen",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "destructive",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Styles it as a destructive action.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "gap",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 4,
+      "origin": "derived",
+      "description": "Distance from the trigger. Default 4.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "icon",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Names the menu for screen readers. Defaults to the locale text.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<MenuLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "onCheckedChange",
+      "type": "function",
+      "signature": "((checked: boolean) => void) | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "onOpenChange",
+      "type": "function",
+      "signature": "((open: boolean, reason?: MenuCloseReason) => void) | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "onSelect",
+      "type": "function",
+      "signature": "(() => void) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Called when the item is chosen, by click, Enter or Space.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "onValueChange",
+      "type": "function",
+      "signature": "((value: string) => void) | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<MenuHandle> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "shortcut",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "A hint such as ⌘K. The menu shows it; binding the key is up to you.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "side",
+      "type": "enum",
+      "values": [
+        "bottom",
+        "left",
+        "right",
+        "top"
+      ],
+      "typeText": "MenuSide | undefined",
+      "required": false,
+      "default": "bottom",
+      "origin": "derived",
+      "description": "Default `bottom`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "trigger",
+      "type": "other",
+      "typeText": "ReactElement<{ [attribute: string]: unknown; }, string | import(\"react\").JSXElementConstructor<any>>",
+      "required": true,
+      "origin": "derived",
+      "description": "The element that opens the menu. It is cloned with the ARIA wiring, so pass\r\na single element — any button in this library works.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "value",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    }
+  ],
+  "events": [
+    {
+      "name": "onCheckedChange",
+      "signature": "((checked: boolean) => void) | undefined"
+    },
+    {
+      "name": "onOpenChange",
+      "signature": "((open: boolean, reason?: MenuCloseReason) => void) | undefined"
+    },
+    {
+      "name": "onSelect",
+      "signature": "(() => void) | undefined"
+    },
+    {
+      "name": "onValueChange",
+      "signature": "((value: string) => void) | undefined"
+    }
+  ],
+  "slots": [
+    "root",
+    "list",
+    "item",
+    "icon",
+    "label",
+    "shortcut",
+    "separator",
+    "group",
+    "groupLabel",
+    "indicator",
+    "submenu"
+  ],
+  "states": [
+    {
+      "attr": "data-destructive",
+      "values": [
+        "destructive"
+      ]
+    },
+    {
+      "attr": "data-disabled",
+      "values": [
+        "disabled"
+      ]
+    },
+    {
+      "attr": "data-side",
+      "values": [
+        "top"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 25,
+    "propsDescribed": 9,
+    "describedPct": 36,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}

package/source/components/menu/react/Menu.tsx

@@ -0,0 +1,371 @@
+"use client";
+
+import {
+  cloneElement,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type ContextType,
+  type CSSProperties,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { ChevronRightIcon } from "../../shared/react/icons";
+import { AnchoredPopover } from "../../shared/react/Popover";
+import { useControllableState } from "../../shared/react/useControllableState";
+import type {
+  MenuAlign,
+  MenuCloseReason,
+  MenuLocaleText,
+  MenuSide,
+  MenuSlot,
+} from "../core/types";
+import { MenuContext, useMenuContext } from "./context";
+import { defaultMenuText } from "./locale";
+import { cx } from "./props";
+import { useMenuKeys } from "./useMenuKeys";
+
+export interface MenuHandle {
+  open(): void;
+  close(): void;
+  getElement(): HTMLElement | null;
+}
+
+export interface MenuProps {
+  /**
+   * The element that opens the menu. It is cloned with the ARIA wiring, so pass
+   * a single element — any button in this library works.
+   */
+  trigger: ReactElement<{ [attribute: string]: unknown }>;
+  children: ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?(open: boolean, reason?: MenuCloseReason): void;
+  /** Names the menu for screen readers. Defaults to the locale text. */
+  label?: string;
+  /** Default `bottom`. */
+  side?: MenuSide;
+  /** Default `start`. */
+  align?: MenuAlign;
+  /** Distance from the trigger. Default 4. */
+  gap?: number;
+  /** Close the menu when an item is chosen. Default true. */
+  closeOnSelect?: boolean;
+  id?: string;
+  className?: string;
+  classNames?: Partial<Record<MenuSlot, string>>;
+  style?: CSSProperties;
+  localeText?: Partial<MenuLocaleText>;
+  ref?: Ref<MenuHandle>;
+}
+
+/**
+ * A menu of commands, following the WAI-ARIA menu button pattern: arrow keys
+ * with wrap-around, Home and End, typeahead, Escape to close and focus returned
+ * to the trigger.
+ *
+ * Rendered in the top layer, so it is never clipped by a toolbar or a scrolling
+ * panel. For a form or free content in a panel use the Popover instead.
+ */
+export function Menu(props: MenuProps) {
+  const {
+    ref,
+    trigger,
+    children,
+    open: openProp,
+    defaultOpen = false,
+    onOpenChange,
+    label,
+    side = "bottom",
+    align = "start",
+    gap = 4,
+    closeOnSelect = true,
+    id: idProp,
+    className,
+    classNames,
+    style,
+    localeText,
+  } = props;
+
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const text = useMemo(() => ({ ...defaultMenuText, ...localeText }), [localeText]);
+
+  const [open, setOpenState] = useControllableState(openProp, defaultOpen);
+  const [anchor, setAnchor] = useState<HTMLElement | null>(null);
+  // Where focus lands when it opens: the pattern says the first item, except
+  // when ArrowUp opened it, which starts at the bottom.
+  const [entry, setEntry] = useState<"first" | "last">("first");
+  const panelRef = useRef<HTMLDivElement>(null);
+
+  const setOpen = useCallback(
+    (next: boolean, reason?: MenuCloseReason) => {
+      setOpenState(next);
+      onOpenChange?.(next, reason);
+    },
+    [setOpenState, onOpenChange],
+  );
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      open: () => setOpen(true),
+      close: () => setOpen(false, "api"),
+      getElement: () => panelRef.current,
+    }),
+    [setOpen],
+  );
+
+  if (!isValidElement(trigger)) {
+    throw new Error("Menu: `trigger` must be a single React element.");
+  }
+
+  const triggerHandlers = trigger.props as {
+    onClick?(event: MouseEvent<HTMLElement>): void;
+    onKeyDown?(event: KeyboardEvent<HTMLElement>): void;
+  };
+
+  const triggerProps = {
+    "aria-haspopup": "menu" as const,
+    "aria-expanded": open,
+    "aria-controls": open ? `${id}-menu` : undefined,
+    onClick(event: MouseEvent<HTMLElement>) {
+      triggerHandlers.onClick?.(event);
+      if (event.defaultPrevented) return;
+      if (open) {
+        setOpen(false, "trigger");
+        return;
+      }
+      setEntry("first");
+      setAnchor(event.currentTarget);
+      setOpen(true);
+    },
+    onKeyDown(event: KeyboardEvent<HTMLElement>) {
+      triggerHandlers.onKeyDown?.(event);
+      if (event.defaultPrevented || open) return;
+      if (event.key !== "ArrowDown" && event.key !== "ArrowUp") return;
+      // Opening with an arrow key also says where to start.
+      event.preventDefault();
+      setEntry(event.key === "ArrowDown" ? "first" : "last");
+      setAnchor(event.currentTarget);
+      setOpen(true);
+    },
+  };
+
+  const context = useMemo(
+    () => ({
+      close: (reason: MenuCloseReason) => setOpen(false, reason),
+      closeOnSelect,
+      classNames,
+      depth: 0,
+    }),
+    [setOpen, closeOnSelect, classNames],
+  );
+
+  return (
+    <>
+      {cloneElement(trigger, triggerProps)}
+      {open && anchor && (
+        <AnchoredPopover
+          anchor={anchor}
+          onClose={() => setOpen(false, "outside")}
+          id={`${id}-menu`}
+          role="menu"
+          label={label ?? text.label}
+          side={side}
+          align={align}
+          gap={gap}
+          fitHeight
+          minHeight={120}
+          autoFocus={false}
+          observeResize="self"
+          returnFocus
+          className={cx("mn-root", classNames?.root, className)}
+        >
+          <MenuPanel
+            ref={panelRef}
+            entry={entry}
+            nested={false}
+            style={style}
+            context={context}
+            onDismiss={() => setOpen(false, "escape")}
+          >
+            {children}
+          </MenuPanel>
+        </AnchoredPopover>
+      )}
+    </>
+  );
+}
+
+/* --------------------------------------------------------------- the panel */
+
+interface MenuPanelProps {
+  children: ReactNode;
+  entry: "first" | "last";
+  nested: boolean;
+  style?: CSSProperties;
+  context: ContextType<typeof MenuContext>;
+  onDismiss(): void;
+  ref?: Ref<HTMLDivElement>;
+}
+
+/**
+ * The list itself. Focus is moved here rather than in the popover primitive
+ * because this runs as a passive effect — after the primitive's layout effect
+ * has called `showPopover()`, without which the items are still `display: none`
+ * and cannot take focus.
+ */
+function MenuPanel({ children, entry, nested, style, context, onDismiss, ref }: MenuPanelProps) {
+  const listRef = useRef<HTMLDivElement>(null);
+  const { onKeyDown, focusFirst, focusLast } = useMenuKeys({ listRef, onDismiss, nested });
+
+  useEffect(() => {
+    if (entry === "last") focusLast();
+    else focusFirst();
+  }, [entry, focusFirst, focusLast]);
+
+  return (
+    <MenuContext value={context}>
+      <div
+        ref={(element) => {
+          listRef.current = element;
+          if (typeof ref === "function") ref(element);
+          else if (ref) ref.current = element;
+        }}
+        className={cx("mn-list", context?.classNames?.list)}
+        style={style}
+        onKeyDown={onKeyDown}
+      >
+        {children}
+      </div>
+    </MenuContext>
+  );
+}
+
+/* ---------------------------------------------------------------- submenus */
+
+export interface MenuSubProps {
+  /** The label of the item that opens the submenu. */
+  label: ReactNode;
+  children: ReactNode;
+  icon?: ReactNode;
+  disabled?: boolean;
+  className?: string;
+}
+
+/** How long the pointer must rest before a submenu opens or closes. */
+const HOVER_DELAY = 140;
+const CLOSE_DELAY = 220;
+
+/** A nested menu, opened by hover, Enter, or the arrow key pointing into it. */
+export function MenuSub({ label, children, icon, disabled = false, className }: MenuSubProps) {
+  const parent = useMenuContext("MenuSub");
+  const id = useId();
+  const [open, setOpen] = useState(false);
+  const [entry, setEntry] = useState<"first" | "last">("first");
+  const [anchor, setAnchor] = useState<HTMLElement | null>(null);
+  const triggerRef = useRef<HTMLDivElement>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  const cancel = () => clearTimeout(timer.current);
+  const schedule = (next: boolean, delay: number) => {
+    cancel();
+    timer.current = setTimeout(() => setOpen(next), delay);
+  };
+
+  useEffect(() => cancel, []);
+
+  const openNow = (from: "first" | "last") => {
+    cancel();
+    setEntry(from);
+    setAnchor(triggerRef.current);
+    setOpen(true);
+  };
+
+  const closeToTrigger = () => {
+    cancel();
+    setOpen(false);
+    triggerRef.current?.focus();
+  };
+
+  const context = useMemo(
+    () => ({ ...parent, depth: parent.depth + 1 }),
+    [parent],
+  );
+
+  return (
+    <>
+      <div
+        ref={triggerRef}
+        role="menuitem"
+        tabIndex={-1}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-controls={open ? `${id}-submenu` : undefined}
+        aria-disabled={disabled || undefined}
+        data-disabled={disabled || undefined}
+        className={cx("mn-item", "mn-sub-trigger", parent.classNames?.item, className)}
+        onPointerEnter={() => {
+          if (!disabled) schedule(true, HOVER_DELAY);
+        }}
+        onPointerLeave={() => {
+          if (open) schedule(false, CLOSE_DELAY);
+          else cancel();
+        }}
+        onClick={(event) => {
+          event.stopPropagation();
+          if (!disabled) openNow("first");
+        }}
+        onKeyDown={(event) => {
+          if (disabled) return;
+          const forward = event.key === "ArrowRight";
+          if (forward || event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            event.stopPropagation();
+            openNow("first");
+          }
+        }}
+      >
+        {icon && <span className={cx("mn-icon", parent.classNames?.icon)}>{icon}</span>}
+        <span className={cx("mn-label", parent.classNames?.label)}>{label}</span>
+        <ChevronRightIcon className="mn-sub-arrow" width={14} height={14} />
+      </div>
+
+      {open && anchor && (
+        <AnchoredPopover
+          anchor={anchor}
+          onClose={() => setOpen(false)}
+          id={`${id}-submenu`}
+          role="menu"
+          label={typeof label === "string" ? label : undefined}
+          side="right"
+          align="start"
+          gap={2}
+          fitHeight
+          minHeight={120}
+          autoFocus={false}
+          observeResize="self"
+          // Manual: an `auto` popover closes every other one, which would take
+          // the parent menu down with it the moment this opened.
+          mode="manual"
+          className={cx("mn-root", "mn-submenu", parent.classNames?.submenu)}
+        >
+          <div onPointerEnter={cancel} onPointerLeave={() => schedule(false, CLOSE_DELAY)}>
+            <MenuPanel entry={entry} nested context={context} onDismiss={closeToTrigger}>
+              {children}
+            </MenuPanel>
+          </div>
+        </AnchoredPopover>
+      )}
+    </>
+  );
+}