makersclaw 0.1.0 → 0.3.0

package/templates/next/files/components/ui/menu.jsx

@@ -1,73 +1,457 @@
 "use client";
 
-import { useEffect, useId, useRef, useState } from "react";
+import { createContext, useContext, useEffect, useId, useMemo, useRef, useState } from "react";
 import { cx } from "./cx";
 import { Icon } from "./icon";
+import { KbdGroup } from "./separator";
+import { panelClass, usePopoverPosition } from "./popover";
 
-// Menu — the "…" of a row, the kebab of a card. The Popover API does the
-// hard part (top layer, light dismiss, Escape); this positions it under
-// its button and moves focus with the arrow keys. `items` with nothing in
-// them render nothing: a menu is earned by having actions.
+// Menu — the "…" of a row, the kebab of a card, a "View" or "Account"
+// dropdown. The Popover API does the hard part (top layer, light dismiss,
+// Escape); usePopoverPosition (./popover) keeps it beside its button,
+// flipping at the window's edge and following scroll. The keys are the
+// WAI-ARIA menu pattern: arrows, Home/End, a first letter jumps to the
+// item it starts, ArrowRight/Left into and out of a submenu, Escape and
+// Tab close it. `items` with nothing in them render nothing: a menu is
+// earned by having actions.
 //
-//   items   [{ label, onSelect, icon?, tone?: "danger", disabled? }]
+//   items   the entries, in order; any mix of
+//             { label, onSelect, icon?, tone?: "danger", disabled?,
+//               shortcut?: "⌘K", description? }        an action (closes)
+//             { type: "checkbox", label, checked, onCheckedChange(next),
+//               icon?, shortcut?, description?, disabled? }  stays open
+//             { type: "radio", label?, value, onValueChange(value),
+//               options: [{ value, label, description?, disabled? }] or
+//               ["a", "b"] }                                   stays open
+//             { group: "Account", items: [...] }   a labelled group
+//             { type: "label", label }    a heading (a reader skips it;
+//                                         `group` is the one it names)
+//             { type: "separator" }       a line
+//             { label, icon?, items: [...] }  a submenu: to the side on a
+//                                         wide window, inline on a phone
+//           a falsy entry is skipped, so `cond && {…}` works
 //   trigger a node to use as the button's content; default is the ⋯ icon
+//   label   what a reader calls the menu, and the button: always the ⋯
+//           one's name (default "More"); with a `trigger`, the button's
+//           name only when given — else its visible text is. Begin it
+//           with that text ("Ada Lovelace, account menu"), so a voice
+//           user who says what they see still hits it
+//   side    bottom (default) · top · right · left; flips when no room
+//   align   end (default) · start · center, along that side
+//   size    the button: sm (36px, the default — a row's or a card's ⋯) ·
+//           md (44px, a touch target: a toolbar, a menubar, a phone)
+//
+// A shortcut is only a hint: the menu draws it, the app binds it. The
+// one rule: an action closes the menu, a choice (checkbox, radio) does
+// not — it is a setting, and the next one is usually beside it.
+//
+// MenuPanel is the menu itself without its button — ContextMenu
+// (./context-menu) opens the same `items` at the pointer.
+
+const Root = createContext({ close() {}, narrow: false });
+const Level = createContext(null);
+
+const SYMBOL_KEYS = { "⌘": "Meta", "⌥": "Alt", "⇧": "Shift", "⌃": "Control", "↵": "Enter", "⏎": "Enter", "⌫": "Backspace", "⌦": "Delete", "⎋": "Escape", "⇥": "Tab", "↑": "ArrowUp", "↓": "ArrowDown", "←": "ArrowLeft", "→": "ArrowRight" };
+const SYMBOLS = /[⌘⌥⇧⌃↵⏎⌫⌦⎋⇥↑↓←→]|[^⌘⌥⇧⌃↵⏎⌫⌦⎋⇥↑↓←→]+/g;
+
+// "⌘K" → ["⌘", "K"]; "Ctrl+Shift+P" → ["Ctrl", "Shift", "P"]; an array as is.
+function keysOf(shortcut) {
+  if (Array.isArray(shortcut)) return shortcut;
+  const s = String(shortcut).trim();
+  return /[+\s]/.test(s) && s.length > 1 ? s.split(/\s*\+\s*|\s+/).filter(Boolean) : s.match(SYMBOLS) ?? [];
+}
+
+// Only this menu's items — not a submenu's, which sit inside it.
+function own(menu) {
+  if (!menu) return [];
+  return [...menu.querySelectorAll('[role^="menuitem"]:not([disabled])')].filter((n) => n.closest('[role="menu"]') === menu);
+}
+
+const nameOf = (n) => (n.dataset.text || n.textContent || "").trim().toLowerCase();
+
+// A first letter moves to the next item it starts; letters typed quickly
+// spell a longer prefix; the same letter again walks through its items.
+function typeahead(nodes, key, memo) {
+  const now = Date.now();
+  memo.text = now - memo.at < 500 ? memo.text + key.toLowerCase() : key.toLowerCase();
+  memo.at = now;
+  const same = [...memo.text].every((c) => c === memo.text[0]);
+  const q = same ? memo.text[0] : memo.text;
+  const i = nodes.indexOf(document.activeElement);
+  const from = i < 0 ? 0 : i + (same ? 1 : 0);
+  return [...nodes.slice(from), ...nodes.slice(0, from)].find((n) => nameOf(n).startsWith(q));
+}
+
+function useNarrow() {
+  const [narrow, setNarrow] = useState(false);
+  useEffect(() => {
+    const mq = window.matchMedia("(max-width: 767.98px)");
+    const on = () => setNarrow(mq.matches);
+    on();
+    mq.addEventListener("change", on);
+    return () => mq.removeEventListener("change", on);
+  }, []);
+  return narrow;
+}
+
+const focus = (n) => n?.focus({ preventScroll: true });
+
+const ITEM =
+  "flex w-full min-h-10 items-center gap-2 rounded-sm px-2 text-left text-sm outline-none hover:bg-accent focus-visible:bg-accent disabled:opacity-50";
+
+/** The menu's list — role=menu, its keys and its items — for a part that
+ *  opens it its own way (Menu under a button, ContextMenu at the pointer).
+ *  `onExit` runs on Escape and Tab; `onClose` closes everything after an
+ *  action. Pass `popover` and a `panelRef` to make it the floating panel. */
+export function MenuPanel({ items, label, labelledBy, id, panelRef, popover, onToggle, onExit, onClose, onBack, className, style, onPointerEnter }) {
+  const root = useContext(Root);
+  const narrow = useNarrow();
+  const [openSub, setOpenSub] = useState(null);
+  const timer = useRef(0);
+  const typed = useRef({ text: "", at: 0 });
+  const live = (items ?? []).filter(Boolean);
+  // A level that holds choices keeps a gutter for their marks, so every
+  // label in it starts at the same line.
+  const gutter = live.some((it) => it.type === "checkbox" || it.type === "radio" || (it.group && (it.items ?? []).some((c) => c?.type === "checkbox" || c?.type === "radio")));
+
+  useEffect(() => () => clearTimeout(timer.current), []);
+
+  const level = useMemo(
+    () => ({
+      openSub,
+      setOpenSub,
+      gutter,
+      later(fn, ms) {
+        clearTimeout(timer.current);
+        timer.current = setTimeout(fn, ms);
+      },
+      cancel: () => clearTimeout(timer.current),
+    }),
+    [openSub, gutter],
+  );
+  const ctx = useMemo(() => (onClose ? { close: onClose, narrow } : { ...root, narrow }), [onClose, root, narrow]);
+
+  function onKeyDown(e) {
+    const menu = e.currentTarget;
+    const nodes = own(menu);
+    const i = nodes.indexOf(document.activeElement);
+    const k = e.key;
+    if (k === "ArrowDown") focus(nodes[(i + 1) % nodes.length]);
+    else if (k === "ArrowUp") focus(nodes[(i - 1 + nodes.length) % nodes.length]);
+    else if (k === "Home" || k === "PageUp") focus(nodes[0]);
+    else if (k === "End" || k === "PageDown") focus(nodes[nodes.length - 1]);
+    else if (k === "ArrowLeft" && onBack) onBack();
+    else if (k === "Escape") (onBack ?? onExit)?.();
+    else if (k === "Tab" && onExit) onExit();
+    else if (k.length === 1 && k !== " " && !e.ctrlKey && !e.metaKey && !e.altKey) focus(typeahead(nodes, k, typed.current));
+    else return; // Tab in a submenu reaches the top menu, which closes
+    e.preventDefault();
+    e.stopPropagation();
+  }
+
+  return (
+    <Root.Provider value={ctx}>
+      <Level.Provider value={level}>
+        <div
+          ref={panelRef}
+          id={id}
+          popover={popover}
+          role="menu"
+          aria-label={labelledBy ? undefined : label}
+          aria-labelledby={labelledBy}
+          aria-orientation="vertical"
+          tabIndex={-1}
+          onToggle={onToggle}
+          onKeyDown={onKeyDown}
+          onPointerEnter={onPointerEnter}
+          className={className}
+          style={style}
+        >
+          <Entries items={live} />
+        </div>
+      </Level.Provider>
+    </Root.Provider>
+  );
+}
+
+function Entries({ items }) {
+  return items.filter(Boolean).map((item, i) => <Entry key={item.key ?? i} item={item} />);
+}
+
+function Heading({ id, children }) {
+  const { gutter } = useContext(Level);
+  return (
+    <div id={id} role={id ? undefined : "none"} className={cx("px-2 py-1.5 text-xs font-medium text-muted-foreground", gutter && "pl-8")}>
+      {children}
+    </div>
+  );
+}
+
+function Entry({ item }) {
+  if (item.type === "separator") return <div role="separator" className="-mx-1 my-1 h-px bg-border" />;
+  if (item.type === "label") return <Heading>{item.label}</Heading>;
+  if (item.type === "checkbox") return <Choice item={item} kind="checkbox" checked={Boolean(item.checked)} onPick={() => item.onCheckedChange?.(!item.checked)} />;
+  if (item.type === "radio") return <RadioGroup item={item} />;
+  if (item.group !== undefined) return <Group item={item} />;
+  if (Array.isArray(item.items)) return <Submenu item={item} />;
+  return <Action item={item} />;
+}
+
+function Group({ item }) {
+  const id = useId();
+  const live = (item.items ?? []).filter(Boolean);
+  if (live.length === 0) return null;
+  return (
+    <div role="group" aria-labelledby={item.group ? id : undefined}>
+      {item.group ? <Heading id={id}>{item.group}</Heading> : null}
+      <Entries items={live} />
+    </div>
+  );
+}
+
+function RadioGroup({ item }) {
+  const id = useId();
+  const options = (item.options ?? []).filter((o) => o !== null && o !== undefined && o !== false).map((o) => (typeof o === "object" ? o : { value: o, label: String(o) }));
+  return (
+    <div role="group" aria-labelledby={item.label ? id : undefined}>
+      {item.label ? <Heading id={id}>{item.label}</Heading> : null}
+      {options.map((o) => (
+        <Choice key={String(o.value)} item={o} kind="radio" checked={o.value === item.value} onPick={() => o.value !== item.value && item.onValueChange?.(o.value)} />
+      ))}
+    </div>
+  );
+}
 
-export function Menu({ items, label = "More", trigger, align = "end", className }) {
+// One row's inside: the mark or icon, the label (and its description),
+// the shortcut, a submenu's chevron.
+function useRow(item) {
   const id = useId();
+  const { gutter } = useContext(Level);
+  const keys = item.shortcut ? keysOf(item.shortcut) : null;
+  const props = {
+    "data-text": typeof item.label === "string" ? item.label : undefined,
+    "aria-labelledby": item.description ? `${id}l` : undefined,
+    "aria-describedby": item.description ? `${id}d` : undefined,
+    "aria-keyshortcuts": keys ? keys.map((k) => SYMBOL_KEYS[k] ?? k).join("+") : undefined,
+  };
+  const body = (lead, tail) => (
+    <>
+      {lead ?? (item.icon ? <Icon name={item.icon} /> : gutter ? <span aria-hidden="true" className="size-4 shrink-0" /> : null)}
+      {item.description ? (
+        <span className="min-w-0 flex-1 py-1.5">
+          <span id={`${id}l`} className="block">
+            {item.label}
+          </span>
+          <span id={`${id}d`} className="block max-w-64 text-xs text-muted-foreground">
+            {item.description}
+          </span>
+        </span>
+      ) : (
+        <span className="min-w-0 flex-1">{item.label}</span>
+      )}
+      {keys ? (
+        <span aria-hidden="true" className="ml-auto shrink-0 pl-4">
+          <KbdGroup keys={keys} />
+        </span>
+      ) : null}
+      {tail}
+    </>
+  );
+  return { props, body };
+}
+
+// Hovering an item with a mouse takes the focus to it (so the keys go on
+// from there) and closes a sibling's submenu a moment later.
+function useHover() {
+  const level = useContext(Level);
+  const { narrow } = useContext(Root);
+  return (e) => {
+    if (e.pointerType !== "mouse" || narrow) return;
+    focus(e.currentTarget);
+    if (level.openSub) level.later(() => level.setOpenSub(null), 200);
+    else level.cancel();
+  };
+}
+
+function Action({ item }) {
+  const { close } = useContext(Root);
+  const hover = useHover();
+  const { props, body } = useRow(item);
+  return (
+    <button
+      type="button"
+      role="menuitem"
+      disabled={item.disabled}
+      {...props}
+      onPointerEnter={hover}
+      onClick={() => {
+        close();
+        item.onSelect?.();
+      }}
+      className={cx(ITEM, item.tone === "danger" && "text-destructive")}
+    >
+      {body()}
+    </button>
+  );
+}
+
+function Choice({ item, kind, checked, onPick }) {
+  const hover = useHover();
+  const { props, body } = useRow(item);
+  const mark = (
+    <span aria-hidden="true" className="grid size-4 shrink-0 place-items-center">
+      {checked ? kind === "checkbox" ? <Icon name="check" size={16} /> : <span className="size-2 rounded-full bg-current" /> : null}
+    </span>
+  );
+  return (
+    <button
+      type="button"
+      role={kind === "checkbox" ? "menuitemcheckbox" : "menuitemradio"}
+      aria-checked={checked}
+      disabled={item.disabled}
+      {...props}
+      onPointerEnter={hover}
+      onClick={onPick}
+      className={cx(ITEM, item.tone === "danger" && "text-destructive")}
+    >
+      {body(mark)}
+    </button>
+  );
+}
+
+const NONE = { current: null };
+
+function Submenu({ item }) {
+  const key = useId();
+  const level = useContext(Level);
+  const { narrow } = useContext(Root);
   const btn = useRef(null);
-  const pop = useRef(null);
-  const [open, setOpen] = useState(false);
-  const live = (items ?? []).filter(Boolean);
+  const sub = useRef(null);
+  const wantFocus = useRef(false);
+  const open = level.openSub === key;
+  const live = (item.items ?? []).filter(Boolean);
+  const { props, body } = useRow(item);
+  usePopoverPosition(btn, narrow ? NONE : sub, { side: "right", align: "start", offset: 2 });
 
-  // A fixed-positioned popover does not follow its button; close it when
-  // the page moves rather than leave it floating where the button was.
+  // The state drives the panel; a light dismiss comes back through onToggle.
   useEffect(() => {
-    if (!open) return;
-    const close = () => pop.current?.hidePopover();
-    window.addEventListener("resize", close);
-    window.addEventListener("scroll", close, true);
-    return () => {
-      window.removeEventListener("resize", close);
-      window.removeEventListener("scroll", close, true);
-    };
-  }, [open]);
+    const p = sub.current;
+    if (p && !narrow) {
+      const shown = p.matches(":popover-open");
+      if (open && !shown) p.showPopover();
+      else if (!open && shown) p.hidePopover();
+    }
+    if (open && wantFocus.current) {
+      wantFocus.current = false;
+      focus(own(sub.current)[0]);
+    }
+  }, [open, narrow]);
 
   if (live.length === 0) return null;
 
-  function place() {
-    const b = btn.current?.getBoundingClientRect();
-    const p = pop.current;
-    if (!b || !p) return;
-    p.style.position = "fixed";
-    p.style.top = `${Math.round(b.bottom + 4)}px`;
-    const width = p.offsetWidth || 200;
-    const left = align === "end" ? b.right - width : b.left;
-    p.style.left = `${Math.max(8, Math.min(left, window.innerWidth - width - 8))}px`;
+  function show(withFocus) {
+    wantFocus.current = withFocus;
+    level.cancel();
+    if (open && withFocus) focus(own(sub.current)[0]);
+    else level.setOpenSub(key);
+  }
+  function back() {
+    level.setOpenSub(null);
+    focus(btn.current);
   }
 
-  function toggle() {
-    const p = pop.current;
-    if (!p) return;
-    if (p.matches(":popover-open")) p.hidePopover();
-    else {
-      p.showPopover();
-      place();
-      p.querySelector('[role="menuitem"]:not([disabled])')?.focus();
+  return (
+    <div role="none">
+      <button
+        ref={btn}
+        type="button"
+        role="menuitem"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-controls={open ? `${key}m` : undefined}
+        id={`${key}t`}
+        disabled={item.disabled}
+        {...props}
+        onPointerEnter={(e) => {
+          if (e.pointerType !== "mouse" || narrow) return;
+          focus(e.currentTarget);
+          if (!open) level.later(() => level.setOpenSub(key), 100);
+          else level.cancel();
+        }}
+        onClick={(e) => {
+          // A key (Enter, Space) goes in; a click opens it, or closes it
+          // again on a phone, where the list unfolds in place.
+          if (e.detail === 0) show(true);
+          else if (open && narrow) level.setOpenSub(null);
+          else show(false);
+        }}
+        onKeyDown={(e) => {
+          if (e.key !== "ArrowRight") return;
+          e.preventDefault();
+          e.stopPropagation();
+          show(true);
+        }}
+        className={cx(ITEM, "aria-expanded:bg-accent")}
+      >
+        {body(null, <Icon name={narrow ? "chevron-down" : "chevron-right"} size={16} className={cx("ml-auto shrink-0 text-muted-foreground transition-transform motion-reduce:transition-none", narrow && open && "rotate-180")} />)}
+      </button>
+      {narrow ? (
+        open ? (
+          <MenuPanel id={`${key}m`} items={live} labelledBy={`${key}t`} panelRef={sub} onBack={back} className="ml-4 border-l border-border pl-1" />
+        ) : null
+      ) : (
+        <MenuPanel
+          id={`${key}m`}
+          items={live}
+          labelledBy={`${key}t`}
+          panelRef={sub}
+          popover="auto"
+          onBack={back}
+          onPointerEnter={() => level.cancel()}
+          onToggle={(e) => {
+            if (e.target === e.currentTarget && e.newState === "closed" && level.openSub === key) level.setOpenSub(null);
+          }}
+          className={panelClass("auto", "min-w-44 max-h-[calc(100vh-1rem)] overflow-y-auto p-1")}
+        />
+      )}
+    </div>
+  );
+}
+
+const TRIGGER_SIZES = {
+  sm: "min-h-9 min-w-9 px-2",
+  md: "min-h-11 min-w-11 px-3",
+};
+
+export function Menu({ items, label, trigger, align = "end", side = "bottom", size = "sm", className }) {
+  const name = label ?? "More";
+  const id = useId();
+  const btn = useRef(null);
+  const pop = useRef(null);
+  const start = useRef("first");
+  const [open, setOpen] = useState(false);
+  const live = (items ?? []).filter(Boolean);
+  usePopoverPosition(btn, pop, { side, align, offset: 4 });
+
+  if (live.length === 0) return null;
+
+  function onToggle(e) {
+    // React bubbles toggle: a submenu's opening is not this menu's.
+    if (e.target !== e.currentTarget) return;
+    const now = e.newState === "open";
+    setOpen(now);
+    if (now) {
+      const nodes = own(pop.current);
+      focus(start.current === "last" ? nodes[nodes.length - 1] : nodes[0]);
+      start.current = "first";
+    } else if (!document.activeElement || document.activeElement === document.body || pop.current?.contains(document.activeElement)) {
+      focus(btn.current);
     }
   }
 
-  function onKeyDown(e) {
-    const nodes = [...(pop.current?.querySelectorAll('[role="menuitem"]:not([disabled])') ?? [])];
-    const i = nodes.indexOf(document.activeElement);
-    if (e.key === "ArrowDown") nodes[(i + 1) % nodes.length]?.focus();
-    else if (e.key === "ArrowUp") nodes[(i - 1 + nodes.length) % nodes.length]?.focus();
-    else if (e.key === "Home") nodes[0]?.focus();
-    else if (e.key === "End") nodes[nodes.length - 1]?.focus();
-    else if (e.key === "Tab" || e.key === "Escape") {
-      pop.current?.hidePopover();
-      btn.current?.focus();
-    } else return;
-    e.preventDefault();
+  function exit() {
+    pop.current?.hidePopover();
+    focus(btn.current);
   }
 
   return (
@@ -75,49 +459,37 @@ export function Menu({ items, label = "More", trigger, align = "end", className
       <button
         ref={btn}
         type="button"
+        popoverTarget={id}
         aria-haspopup="menu"
         aria-expanded={open}
         aria-controls={id}
-        aria-label={trigger ? undefined : label}
-        title={trigger ? undefined : label}
-        onClick={toggle}
+        aria-label={trigger ? label : name}
+        title={trigger ? undefined : name}
+        onKeyDown={(e) => {
+          if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return;
+          e.preventDefault();
+          start.current = e.key === "ArrowUp" ? "last" : "first";
+          if (!pop.current?.matches(":popover-open")) pop.current?.showPopover();
+        }}
         className={cx(
-          "inline-flex min-h-9 min-w-9 items-center justify-center gap-2 rounded-md px-2 text-sm text-foreground outline-none hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring",
+          "inline-flex items-center justify-center gap-2 rounded-md text-sm text-foreground outline-none hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring",
+          TRIGGER_SIZES[size] ?? TRIGGER_SIZES.sm,
           className,
         )}
       >
         {trigger ?? <Icon name="more" />}
       </button>
-      <div
-        ref={pop}
+      <MenuPanel
         id={id}
+        items={live}
+        label={name}
+        panelRef={pop}
         popover="auto"
-        role="menu"
-        aria-label={label}
-        onToggle={(e) => setOpen(e.newState === "open")}
-        onKeyDown={onKeyDown}
-        className="min-w-44 rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-lg"
-      >
-        {live.map((item, i) => (
-          <button
-            key={i}
-            type="button"
-            role="menuitem"
-            disabled={item.disabled}
-            onClick={() => {
-              pop.current?.hidePopover();
-              item.onSelect?.();
-            }}
-            className={cx(
-              "flex w-full min-h-10 items-center gap-2 rounded-sm px-2 text-left text-sm outline-none hover:bg-accent focus-visible:bg-accent disabled:opacity-50",
-              item.tone === "danger" && "text-destructive",
-            )}
-          >
-            {item.icon ? <Icon name={item.icon} /> : null}
-            {item.label}
-          </button>
-        ))}
-      </div>
+        onToggle={onToggle}
+        onExit={exit}
+        onClose={() => pop.current?.hidePopover()}
+        className={panelClass("auto", "min-w-44 max-h-[calc(100vh-1rem)] overflow-y-auto p-1")}
+      />
     </>
   );
 }