Skip to content

AI media harness for planning, generating, and editing locally

TypeScript
15.3 KB
Raw Blame
/* ContextMenu — the WinUI MenuFlyout.

   Acrylic, 8px corners, 4px vertical padding; 32px items with 4px corners
   inset 4px from the edge and 11px of text inset; 16px icons; accelerator
   text right-aligned in secondary ink; disabled items dimmed by colour, not
   opacity. Opens at a point (a contextmenu event) or anchored to an element,
   flipping to stay inside the window.

   Focus: opened by the keyboard (Shift+F10, the Menu key, a button's Enter)
   the first item takes focus; opened by the mouse the menu itself takes it,
   so arrows, Enter and Esc still work without painting a focus visual.
   Arrows / Home / End move, Enter / Space run, Esc / Tab close, typing jumps
   to the next item starting with that letter, and pressing an item's own
   shortcut runs it.

   Hook form, for most screens:

     const menu = useContextMenu();
     <div onContextMenu={(e) => menu.open(e, [
       { id: "rename", label: "Rename", icon: <Rename16 />, shortcut: "F2", onSelect: rename },
       { separator: true },
       { id: "delete", label: "Delete", icon: <Delete16 />, shortcut: "Delete", onSelect: remove },
     ])} />
     {menu.element}

   `open` also takes a KeyboardEvent (anchors to its target and focuses the
   first item) or an element / DOMRect (anchors below it).

   Submenus: an item with `items` instead of `onSelect` opens a cascading
   menu beside it: on hover after a short pause, or on click, Enter, Space or
   Right. Left or Esc closes just that level and puts focus back on its item;
   a command anywhere in the cascade closes all of it. The item shows a
   chevron, and the submenu flips to the left when there is no room on the
   right:

     { id: "move", label: "Move to", items: scenes.map((scene) => ({ label: scene.title, onSelect: … })) } */

import { Check16, ChevronRight16 } from "./icons";
import {
  useCallback, useEffect, useLayoutEffect, useRef, useState,
  type CSSProperties, type KeyboardEvent, type ReactNode, type SyntheticEvent,
} from "react";
import { createPortal } from "react-dom";
import { ariaKeyShortcuts, formatShortcut, matchesCombo } from "../../lib/commands";
import {
  LAYER_ATTR, createTypeahead, cx, focusSafely, isPrintableKey, lastInputWasKeyboard, placeAnchored, placeAtPoint,
  useLightDismiss, type RectLike,
} from "./internal";

export interface MenuItem {
  id?: string;
  label: string;
  icon?: ReactNode;
  /** A combo ("Ctrl+C", "Delete"); shown formatted and honoured while the menu is open. */
  shortcut?: string;
  disabled?: boolean;
  /** Kept for callers; Fluent paints destructive items like any other. */
  danger?: boolean;
  /** Renders a check column and role="menuitemcheckbox". */
  checked?: boolean;
  /** Runs the command. Optional only for a submenu item (one with `items`). */
  onSelect?: () => void;
  /** Makes this a submenu item: these entries open in a cascading menu. */
  items?: MenuEntry[];
}

export interface MenuSeparator { separator: true; id?: string }

export type MenuEntry = MenuItem | MenuSeparator;

export const isSeparator = (entry: MenuEntry): entry is MenuSeparator => "separator" in entry && entry.separator === true;

export type MenuPosition =
  | { x: number; y: number }
  | { anchor: Element | RectLike; placement?: "bottom" | "top" | "right" | "bottom-end" };

export interface ContextMenuProps {
  items: MenuEntry[];
  /** Where to open: a point, or an anchor element / rect. */
  position: MenuPosition;
  onClose: () => void;
  "aria-label"?: string;
  /** Focus the first item on open. Default: only when the last input was the keyboard. */
  focusFirst?: boolean;
  /** Return focus to the element that had it when the menu closes via Esc or a command. Default true. */
  restoreFocus?: boolean;
  className?: string;
  /** Minimum width in px (default 160 — Fluent's 120 is too tight for accelerators). */
  minWidth?: number;
  /** Internal, for submenus: a command ran somewhere below, close everything. */
  onChosen?: () => void;
  /** Internal, for submenus: Left closes this level. */
  closeOnLeft?: boolean;
  /** Internal, for submenus opened by hovering: leave focus on the parent item. */
  keepFocus?: boolean;
  /** Internal, for submenus: the pointer reached it (cancels a pending close). */
  onPointerEnter?: () => void;
}

/** How long the pointer rests on a submenu item before it opens. WinUI waits
 *  about this long, so a diagonal move towards the submenu does not flicker. */
export const SUBMENU_HOVER_DELAY = 250;

const rectOf = (anchor: Element | RectLike): RectLike =>
  anchor instanceof Element ? anchor.getBoundingClientRect() : anchor;

export function ContextMenu({
  items, position, onClose, focusFirst, restoreFocus = true, className, minWidth = 160, onChosen, closeOnLeft = false, onPointerEnter, keepFocus = false, ...aria
}: ContextMenuProps) {
  const menu = useRef<HTMLDivElement>(null);
  const opener = useRef<HTMLElement | null>(null);
  const [style, setStyle] = useState<CSSProperties>({ visibility: "hidden", left: 0, top: 0 });
  const typeahead = useRef(createTypeahead());
  const closeRef = useRef(onClose);
  closeRef.current = onClose;
  const [sub, setSub] = useState<{ index: number; anchor: HTMLElement; keyboard: boolean; hover: boolean; key: number } | null>(null);
  const subCounter = useRef(0);
  const hoverTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
  const clearHover = () => { if (hoverTimer.current !== undefined) { clearTimeout(hoverTimer.current); hoverTimer.current = undefined; } };
  useEffect(() => clearHover, []);
  const hasGlyphColumn = items.some((entry) => !isSeparator(entry) && (entry.icon !== undefined || entry.checked !== undefined));

  const buttons = () => [...(menu.current?.querySelectorAll<HTMLButtonElement>("button[data-menu-item]:not(:disabled)") ?? [])];

  const positionKey = "x" in position ? `${position.x},${position.y}` : position.anchor;

  useLayoutEffect(() => {
    if (!opener.current) opener.current = document.activeElement as HTMLElement | null;
    const element = menu.current;
    if (!element) return;
    const size = { width: element.offsetWidth || minWidth, height: element.offsetHeight || 0 };
    const placed = "x" in position
      ? placeAtPoint(position.x, position.y, size)
      : placeAnchored(rectOf(position.anchor), size, position.placement ?? "bottom", 4);
    setStyle({ left: placed.left, top: placed.top, minWidth });
    const keyboard = focusFirst ?? lastInputWasKeyboard();
    if (keyboard) focusSafely(buttons()[0] ?? element);
    else if (!keepFocus) focusSafely(element);
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [positionKey]);

  const close = useCallback((restore: boolean) => {
    if (restore && restoreFocus) focusSafely(opener.current);
    closeRef.current();
  }, [restoreFocus]);

  useLightDismiss(menu, true, (reason) => close(reason === "escape"));

  /* A command closes the whole cascade: a submenu hands it up to the root,
     which restores focus to whatever had it before the menu opened. */
  const chosen = useCallback(() => {
    if (onChosen) onChosen();
    else close(true);
  }, [onChosen, close]);

  const openSub = (index: number, anchor: HTMLElement, keyboard: boolean, hover = false) => {
    clearHover();
    subCounter.current += 1;
    setSub({ index, anchor, keyboard, hover, key: subCounter.current });
  };

  const cascadeAt = (button: HTMLElement | null) => {
    const entry = button ? items[Number(button.dataset.index)] : undefined;
    return entry && !isSeparator(entry) && entry.items ? Number(button!.dataset.index) : -1;
  };

  const run = (item: MenuItem, button?: HTMLElement | null) => {
    if (item.disabled) return;
    if (item.items) {
      const index = items.indexOf(item);
      if (button && sub?.index !== index) openSub(index, button, lastInputWasKeyboard());
      return;
    }
    chosen();
    item.onSelect?.();
  };

  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
    // Keys pressed in a menu never reach the surface behind it.
    event.stopPropagation();
    const entries = items.filter((entry): entry is MenuItem => !isSeparator(entry));
    const accelerated = entries.find((item) => item.shortcut && !item.disabled && !item.items && matchesCombo(event.nativeEvent, item.shortcut));
    if (accelerated && (event.ctrlKey || event.altKey || event.metaKey || event.key.length > 1)) {
      event.preventDefault();
      run(accelerated);
      return;
    }
    const list = buttons();
    const index = list.indexOf(document.activeElement as HTMLButtonElement);
    const focused = index >= 0 ? list[index] : null;
    let next = -1;
    switch (event.key) {
      case "ArrowRight": {
        const at = cascadeAt(focused);
        if (focused && at >= 0) { event.preventDefault(); openSub(at, focused, true); }
        return;
      }
      case "ArrowLeft":
        if (closeOnLeft) { event.preventDefault(); close(true); }
        return;
      case "ArrowDown": next = index < 0 ? 0 : (index + 1) % list.length; break;
      case "ArrowUp": next = index < 0 ? list.length - 1 : (index - 1 + list.length) % list.length; break;
      case "Home": next = 0; break;
      case "End": next = list.length - 1; break;
      case "Tab": event.preventDefault(); close(true); return;
      case "Escape": event.preventDefault(); close(true); return;
      case "Enter":
      case " ":
        if (focused) {
          event.preventDefault();
          const at = cascadeAt(focused);
          if (at >= 0) openSub(at, focused, true);
          else focused.click();
        }
        return;
      default:
        if (isPrintableKey(event)) {
          next = typeahead.current(event.key, list.map((button) => button.dataset.label ?? ""), index);
          if (next < 0) return;
        } else return;
    }
    event.preventDefault();
    focusSafely(list[next]);
  };

  const subItem = sub ? items[sub.index] : undefined;
  const submenu = sub && subItem && !isSeparator(subItem) && subItem.items ? (
    <ContextMenu
      key={sub.key}
      items={subItem.items}
      position={{ anchor: sub.anchor, placement: "right" }}
      focusFirst={sub.keyboard}
      keepFocus={sub.hover}
      aria-label={subItem.label}
      minWidth={minWidth}
      closeOnLeft
      onChosen={chosen}
      onPointerEnter={clearHover}
      onClose={() => setSub(null)}
    />
  ) : null;

  return createPortal(
    <div
      ref={menu}
      role="menu"
      tabIndex={-1}
      aria-label={aria["aria-label"]}
      className={cx("ui-menu", hasGlyphColumn && "ui-menu--glyphs", className)}
      style={style}
      {...{ [LAYER_ATTR]: "menu" }}
      onContextMenu={(event: SyntheticEvent) => event.preventDefault()}
      onMouseEnter={onPointerEnter}
      onKeyDown={onKeyDown}
    >
      {items.map((entry, index) => {
        if (isSeparator(entry)) return <div key={entry.id ?? `separator-${index}`} role="separator" className="ui-menu__separator" />;
        const checkable = entry.checked !== undefined;
        const cascade = Boolean(entry.items);
        return (
          <button
            key={entry.id ?? entry.label}
            type="button"
            role={checkable ? "menuitemcheckbox" : "menuitem"}
            aria-checked={checkable ? entry.checked : undefined}
            aria-keyshortcuts={cascade ? undefined : ariaKeyShortcuts(entry.shortcut)}
            aria-haspopup={cascade ? "menu" : undefined}
            aria-expanded={cascade ? sub?.index === index : undefined}
            tabIndex={-1}
            disabled={entry.disabled}
            data-menu-item=""
            data-index={index}
            data-label={entry.label}
            className={cx("ui-menu__item", entry.danger && "ui-menu__item--danger", cascade && "ui-menu__item--cascade")}
            onClick={(event) => run(entry, event.currentTarget)}
            onMouseEnter={(event) => {
              clearHover();
              if (entry.disabled) return;
              const button = event.currentTarget;
              focusSafely(button);
              if (cascade) {
                if (sub?.index !== index) hoverTimer.current = setTimeout(() => openSub(index, button, false, true), SUBMENU_HOVER_DELAY);
              } else if (sub) {
                hoverTimer.current = setTimeout(() => setSub(null), SUBMENU_HOVER_DELAY);
              }
            }}
          >
            {hasGlyphColumn && (
              <span className="ui-menu__glyph" aria-hidden="true">
                {checkable ? (entry.checked ? <Check16 /> : null) : entry.icon}
              </span>
            )}
            <span className="ui-menu__label">{entry.label}</span>
            {entry.shortcut && !cascade && <kbd className="ui-menu__shortcut">{formatShortcut(entry.shortcut)}</kbd>}
            {cascade && <ChevronRight16 className="ui-menu__chevron" aria-hidden="true" />}
          </button>
        );
      })}
      {submenu}
    </div>,
    document.body,
  );
}

/* --- Hook ---------------------------------------------------------------------- */

type OpenSource =
  | { clientX: number; clientY: number; preventDefault?: () => void; stopPropagation?: () => void; type?: string; currentTarget?: EventTarget | null; target?: EventTarget | null; nativeEvent?: Event }
  | { key: string; preventDefault?: () => void; stopPropagation?: () => void; currentTarget?: EventTarget | null; target?: EventTarget | null }
  | Element
  | RectLike;

export interface OpenMenuOptions {
  "aria-label"?: string;
  focusFirst?: boolean;
  placement?: "bottom" | "top" | "right" | "bottom-end";
  onClose?: () => void;
}

export function useContextMenu() {
  const [state, setState] = useState<{ items: MenuEntry[]; position: MenuPosition; options: OpenMenuOptions; focusFirst?: boolean; key: number } | null>(null);
  const counter = useRef(0);

  const current = useRef(state);
  current.current = state;

  const close = useCallback(() => {
    const closing = current.current;
    current.current = null;
    setState(null);
    closing?.options.onClose?.();
  }, []);

  const open = useCallback((source: OpenSource, items: MenuEntry[], options: OpenMenuOptions = {}) => {
    let position: MenuPosition;
    let focusFirst = options.focusFirst;
    if (typeof Element !== "undefined" && source instanceof Element) {
      position = { anchor: source, placement: options.placement };
    } else if ("key" in source) {
      source.preventDefault?.();
      source.stopPropagation?.();
      const target = (source.currentTarget ?? source.target) as Element | null;
      position = target instanceof Element ? { anchor: target, placement: options.placement } : { x: 0, y: 0 };
      focusFirst ??= true;
    } else if ("clientX" in source) {
      source.preventDefault?.();
      source.stopPropagation?.();
      // A contextmenu event raised by the keyboard has no coordinates.
      const target = (source.currentTarget ?? source.target) as Element | null;
      if (source.clientX === 0 && source.clientY === 0 && target instanceof Element) position = { anchor: target, placement: options.placement };
      else position = { x: source.clientX, y: source.clientY };
    } else {
      position = { anchor: source, placement: options.placement };
    }
    counter.current += 1;
    setState({ items, position, options, focusFirst, key: counter.current });
  }, []);

  const element = state ? (
    <ContextMenu
      key={state.key}
      items={state.items}
      position={state.position}
      focusFirst={state.focusFirst}
      aria-label={state.options["aria-label"]}
      onClose={close}
    />
  ) : null;

  return { open, close, element, isOpen: state !== null };
}