Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
refactor(menu): draw the menu's rows as components that register themselves
Elian Doraneee991e907be
diff --git a/apps/client/src/widgets/react/Menu.spec.tsx b/apps/client/src/widgets/react/Menu.spec.tsxindex 24cbee4bd0..aadb8b507f 100644--- a/apps/client/src/widgets/react/Menu.spec.tsx+++ b/apps/client/src/widgets/react/Menu.spec.tsx@@ -1,6 +1,7 @@-import { describe, expect, it } from "vitest";+import { render } from "preact";+import { afterEach, describe, expect, it, vi } from "vitest";-import { rowInNextColumn } from "./Menu";+import Menu, { MenuCommand, MenuHeader, MenuSeparator, rowInNextColumn } from "./Menu";/** A row 20px tall, `left` into the menu and `top` down it. */function row(left: number, top: number) {@@ -36,3 +37,118 @@ describe("rowInNextColumn", () => {expect(rowInNextColumn([ row(0, 0), undefined, row(100, 0) ], 0, "right")).toBe(2);});});++describe("Menu with declared rows", () => {+ const host = document.createElement("div");+ document.body.append(host);+ afterEach(() => render(null, host));++ /**+ * A menu written as components, with a submenu declared inside a component of its own, as the+ * global menu declares its "Advanced" submenu.+ */+ function renderMenu() {+ const calls: string[] = [];+ const onClose = vi.fn(() => calls.push("close"));+ function Advanced() {+ return (+ <MenuCommand title="Advanced" uiIcon="bx bx-chip">+ <MenuCommand title="Show log" onSelect={() => calls.push("log")} />+ <MenuCommand title="Reload" onSelect={() => calls.push("reload")} />+ </MenuCommand>+ );+ }+ render((+ <Menu x={10} y={10} onClose={onClose}>+ <MenuHeader title="Note" />+ <MenuCommand title="Copy" keyboardShortcut={undefined} onSelect={() => calls.push("copy")} />+ <MenuCommand title="Delete" enabled={false} onSelect={() => calls.push("delete")} />+ <MenuSeparator />+ <Advanced />+ </Menu>+ ), host);++ const menu = host.querySelector<HTMLElement>(".tn-menu");+ if (!menu) throw new Error("expected the menu to render");+ return { menu, calls, onClose };+ }++ function rowTitled(title: string) {+ const found = [ ...document.querySelectorAll<HTMLElement>("li.dropdown-item") ]+ .find((item) => item.querySelector(":scope > span")?.textContent === title);+ if (!found) throw new Error(`expected a row titled ${title}`);+ return found;+ }++ /** The open submenus' layers, each as the titles of its rows. */+ function layers(menu: HTMLElement) {+ return [ ...menu.querySelectorAll(":scope > div.dropdown-submenu > .dropdown-menu") ]+ .map((layer) => [ ...layer.querySelectorAll(":scope > .tn-menu-scroll > li") ].map((item) => item.textContent));+ }++ const press = (element: HTMLElement) =>+ element.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, cancelable: true, button: 0 }));+ const key = (menu: HTMLElement, name: string) =>+ menu.dispatchEvent(new KeyboardEvent("keydown", { key: name, bubbles: true, cancelable: true }));++ it("draws the rows it is given in order, and opens a declared submenu as a layer beside the scroller", async () => {+ const { menu, calls } = renderMenu();++ const rows = [ ...menu.querySelectorAll(":scope > .tn-menu-scroll > li") ]+ .map((item) => `${item.className || item.firstElementChild?.className} ${item.textContent}`);+ expect(rows).toEqual([+ "dropdown-header Note",+ "dropdown-item Copy",+ "dropdown-item disabled Delete",+ "dropdown-divider ",+ "dropdown-item dropdown-submenu Advanced"+ ]);++ rowTitled("Advanced").dispatchEvent(new PointerEvent("pointerenter"));+ await vi.waitFor(() => expect(layers(menu)).toEqual([ [ "Show log", "Reload" ] ]));+ expect(calls).toEqual([]);+ });++ it("closes the menu before running a row, but not for a row that opens a submenu or is disabled", async () => {+ const { menu, calls } = renderMenu();++ press(rowTitled("Delete"));+ press(rowTitled("Advanced"));+ await vi.waitFor(() => expect(layers(menu)).toHaveLength(1));+ expect(calls).toEqual([]);++ press(rowTitled("Show log"));+ expect(calls).toEqual([ "close", "log" ]);+ });++ it("walks the rows as they are drawn, into a declared submenu and back, skipping what cannot run", async () => {+ const { menu, calls } = renderMenu();+ const active = () => menu.querySelector(".tn-menu-active > span")?.textContent;++ key(menu, "ArrowDown");+ await vi.waitFor(() => expect(active()).toBe("Copy"));+ // "Delete" is disabled, and the header and the separator are not rows to stand on.+ key(menu, "ArrowDown");+ await vi.waitFor(() => expect(active()).toBe("Advanced"));++ key(menu, "ArrowRight");+ await vi.waitFor(() => expect(layers(menu)).toEqual([ [ "Show log", "Reload" ] ]));+ await vi.waitFor(() => expect(active()).toBe("Show log"));+ key(menu, "ArrowDown");+ await vi.waitFor(() => expect(active()).toBe("Reload"));++ key(menu, "ArrowLeft");+ await vi.waitFor(() => expect(layers(menu)).toEqual([]));+ expect(active()).toBe("Advanced");++ key(menu, "ArrowRight");+ await vi.waitFor(() => expect(active()).toBe("Show log"));+ key(menu, "Enter");+ expect(calls).toEqual([ "close", "log" ]);+ });++ it("refuses a row outside a menu", () => {+ vi.spyOn(console, "error").mockImplementation(() => {});+ expect(() => render(<MenuCommand title="Stray" />, host)).toThrow("inside a Menu");+ });+});diff --git a/apps/client/src/widgets/react/Menu.tsx b/apps/client/src/widgets/react/Menu.tsxindex 978c814083..297beaf5ef 100644--- a/apps/client/src/widgets/react/Menu.tsx+++ b/apps/client/src/widgets/react/Menu.tsx@@ -2,9 +2,11 @@ import "./Menu.css";import { autoUpdate, computePosition, flip, hide, offset, type Placement, type ReferenceElement, shift, size, type VirtualElement } from "@floating-ui/dom";import clsx from "clsx";-import { useCallback, useId, useLayoutEffect, useRef, useState } from "preact/hooks";+import { type ComponentChildren, createContext } from "preact";+import { createPortal } from "preact/compat";+import { useCallback, useContext, useId, useLayoutEffect, useRef, useState } from "preact/hooks";-import type { CustomMenuItem, MenuCommandItem, MenuItem } from "../../menus/context_menu";+import type { MenuCommandItem, MenuItem } from "../../menus/context_menu";import { getActionSync } from "../../services/keyboard_actions";import { handleRightToLeftPlacement, isMobile } from "../../services/utils";import { joinElements } from "./react_utils";@@ -14,6 +16,10 @@ import { renderShortcutKbds } from "./shortcut_kbd";* A menu of commands, drawn with the markup Bootstrap's dropdowns use (`.dropdown-menu`,* `.dropdown-item`, `.dropdown-divider`), so the stylesheets and themes that style those style* this too. Only the placement is its own.+ *+ * The rows come as data in {@link items}, or as components in {@link children}: `MenuCommand`,+ * `MenuSeparator`, `MenuHeader` and `MenuCustom`. A `MenuCommand` with children opens them as its+ * submenu.*/export interface MenuProps<T> {id?: string;@@ -30,10 +36,11 @@ export interface MenuProps<T> {bottomSheet?: boolean;/** Makes the first row the active one as the menu takes focus, for a menu a key opened. */startAtFirstRow?: boolean;- items: MenuItem<T>[];- /** Called when an item is pressed with the primary button, or run from the keyboard. */- onSelect(item: MenuCommandItem<T>, e: MouseEvent | KeyboardEvent): void;- /** Called on a click inside a custom item, which closes the menu like a pressed item does. */+ items?: MenuItem<T>[];+ /** Called when one of {@link items} is pressed with the primary button, or run from the keyboard. */+ onSelect?(item: MenuCommandItem<T>, e: MouseEvent | KeyboardEvent): void;+ children?: ComponentChildren;+ /** Called when a row that closes the menu runs, on a click inside a custom row, and on Escape. */onClose(): void;}@@ -41,11 +48,10 @@ export interface MenuProps<T> {const VIEWPORT_PADDING = 5;/** A submenu standing open, and the row it opened from. */-interface OpenSubmenu<T> {- item: MenuCommandItem<T>;+interface OpenSubmenu {+ /** The id of the row it opened from. */+ id: string;anchor: HTMLElement;- /** Remounts the layer when another submenu replaces it at the same level. */- key: number;/*** Shows the layer without the stylesheet's opening delay and fade: it replaces a submenu that* was open, or a key or a press chose it, so it is not a pointer passing over its row.@@ -53,13 +59,22 @@ interface OpenSubmenu<T> {immediate: boolean;}-/** A row the keyboard can stand on: a command, or a custom row with something to focus in it. */-type NavigableItem<T> = MenuCommandItem<T> | CustomMenuItem;+/** A row as it registers with its menu, for the keys to find and act on. */+interface RowEntry {+ level: number;+ element: HTMLElement;+ /** A custom row takes focus in itself instead of running anything. */+ custom: boolean;+ disabled: boolean;+ hasSubmenu: boolean;+ /** Runs the row, as a press or Enter does, once its submenu, if it has one, is open. */+ select(e: MouseEvent | KeyboardEvent): void;+}/** The row the keyboard acts on, and the level it stands at. */-interface ActiveRow<T> {+interface ActiveRow {level: number;- item: NavigableItem<T>;+ id: string;}/** The keys the menu keeps while focus is inside a custom row: those that leave it. */@@ -68,66 +83,121 @@ const KEYS_LEAVING_CUSTOM_ROW = new Set([ "ArrowUp", "ArrowDown", "Escape", "Tab/** How long typed letters keep adding to the text a row is looked up by. */const TYPEAHEAD_TIMEOUT = 500;-/** What every level of the menu shares. */-interface MenuState<T> {- onSelect: MenuProps<T>["onSelect"];- onClose: MenuProps<T>["onClose"];+/** What every row of a menu shares, at every level. */+interface MenuContextValue {+ /** The submenu standing open at each level, the top level's first. */+ open: OpenSubmenu[];/**- * Opens `item`'s submenu at `level`, closing whatever stood open at that level and deeper, or- * without an item only closes them.+ * Opens the submenu of the row `id` at `level`, closing whatever stood open at that level and+ * deeper, or without a row only closes them.*/- openSubmenu(level: number, item?: MenuCommandItem<T>, anchor?: HTMLElement, chosen?: boolean): void;- /** The item whose submenu stands open at each level. */- openItems: MenuCommandItem<T>[];- active?: ActiveRow<T>;- setActive(level: number, item: NavigableItem<T>): void;- /** Each row's element, for `aria-activedescendant` and for anchoring a submenu the keyboard opens. */- rows: Map<NavigableItem<T>, HTMLElement>;+ openSubmenu(level: number, id?: string, anchor?: HTMLElement, chosen?: boolean): void;+ active?: ActiveRow;+ setActive(level: number, id: string): void;+ /** The rows by id, as they registered. */+ rows: Map<string, RowEntry>;+ /** Registers a row as it mounts, and with `undefined` takes it back as it unmounts. */+ registerRow(id: string, row: RowEntry | undefined): void;/** Whether the keys moved the menu since the pointer last did. */keyboardDriven: boolean;+ close(): void;+ /**+ * Where a row renders its submenu's layer: the top level's element, so the rules scoped to the+ * menu apply, but outside its scroller and any other layer, as a fixed layer escapes a+ * scrolling menu only while no ancestor carries a filter.+ */+ layerHost: HTMLElement | null;}-export default function Menu<T>({ id, className, x, y, orientation, bottomSheet, startAtFirstRow, items, onSelect, onClose }: MenuProps<T>) {- const menuRef = useRef<HTMLDivElement>(null);- const [ submenus, setSubmenus ] = useState<OpenSubmenu<T>[]>([]);- const nextKey = useRef(0);-- const openSubmenu = useCallback((level: number, item?: MenuCommandItem<T>, anchor?: HTMLElement, chosen = false) => {- setSubmenus((open) => {- if (item ? open[level]?.item === item : open.length <= level) return open;- const kept = open.slice(0, level);- const immediate = chosen || !!open[level];- return item && anchor ? [ ...kept, { item, anchor, key: nextKey.current++, immediate } ] : kept;+const MenuContext = createContext<MenuContextValue | null>(null);+/** How deep the rows rendered here stand: 0 at the top level, 1 in its submenus, and so on. */+const MenuLevelContext = createContext(0);++export default function Menu<T>({ id, className, x, y, orientation, bottomSheet, startAtFirstRow, items, onSelect, children, onClose }: MenuProps<T>) {+ const menuRef = useRef<HTMLDivElement | null>(null);+ // The submenus' layers render into the menu element, which rows reach through the context.+ const [ layerHost, setLayerHost ] = useState<HTMLElement | null>(null);+ const setMenuElement = useCallback((element: HTMLDivElement | null) => {+ menuRef.current = element;+ setLayerHost(element);+ }, []);+ const [ open, setOpen ] = useState<OpenSubmenu[]>([]);++ const openSubmenu = useCallback((level: number, rowId?: string, anchor?: HTMLElement, chosen = false) => {+ setOpen((current) => {+ if (rowId ? current[level]?.id === rowId : current.length <= level) return current;+ const kept = current.slice(0, level);+ const immediate = chosen || !!current[level];+ return rowId && anchor ? [ ...kept, { id: rowId, anchor, immediate } ] : kept;});}, []);- const [ active, setActiveRow ] = useState<ActiveRow<T>>();- const rows = useRef(new Map<NavigableItem<T>, HTMLElement>()).current;+ const [ active, setActiveRow ] = useState<ActiveRow>();+ const rows = useRef(new Map<string, RowEntry>()).current;+ /** The level whose first row becomes active once it has rendered, for a submenu a key opened. */+ const pendingFirstRow = useRef<number>();const typeahead = useRef({ text: "", timeout: 0 });/** Whether the keys moved the menu since the pointer last did. See `Menu.css`. */const [ keyboardDriven, setKeyboardDriven ] = useState(false);- const setActive = useCallback((level: number, item: NavigableItem<T>) => {- setActiveRow({ level, item });- rows.get(item)?.scrollIntoView?.({ block: "nearest" });+ const setActive = useCallback((level: number, rowId: string) => {+ setActiveRow({ level, id: rowId });+ rows.get(rowId)?.element.scrollIntoView?.({ block: "nearest" });}, [ rows ]);- const state: MenuState<T> = {- onSelect, onClose, openSubmenu, openItems: submenus.map((submenu) => submenu.item), active, setActive, rows,- keyboardDriven+ const registerRow = useCallback((rowId: string, row: RowEntry | undefined) => {+ if (!row) {+ rows.delete(rowId);+ return;+ }+ rows.set(rowId, row);+ // A portaled submenu can commit after this component's effects, so the level a key opened+ // looks for its first row once the rows that register with it have all done so.+ if (pendingFirstRow.current !== row.level) return;+ queueMicrotask(() => {+ if (pendingFirstRow.current !== row.level) return;+ pendingFirstRow.current = undefined;+ activateFirstRowRef.current(row.level);+ });+ }, [ rows ]);+ const context: MenuContextValue = {+ open, openSubmenu, active, setActive, rows, registerRow, keyboardDriven, close: onClose, layerHost};+ /** The ids of the rows the keys can stand on at `level`, in the order they stand in. */+ function navigableRows(level: number) {+ const found: [ string, RowEntry ][] = [];+ for (const [ rowId, row ] of rows) {+ if (row.level !== level) continue;+ if (row.custom ? focusTarget(row.element) : !row.disabled) found.push([ rowId, row ]);+ }+ found.sort(([ , a ], [ , b ]) => (a.element.compareDocumentPosition(b.element) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1));+ return found.map(([ rowId ]) => rowId);+ }++ /** Makes the first row at `level` that runs something the active one, if the level has rendered. */+ function activateFirstRow(level: number) {+ const first = navigableRows(level).find((rowId) => !rows.get(rowId)?.custom);+ if (first) setActive(level, first);+ return !!first;+ }++ const activateFirstRowRef = useRef(activateFirstRow);+ activateFirstRowRef.current = activateFirstRow;+// After the commit: a submenu's rows register their elements only as they mount.useLayoutEffect(() => {- const id = active && !isCustom(active.item) ? rows.get(active.item)?.id : undefined;- if (id) menuRef.current?.setAttribute("aria-activedescendant", id);+ const row = active && rows.get(active.id);+ const rowId = row && !row.custom ? row.element.id : undefined;+ if (rowId) menuRef.current?.setAttribute("aria-activedescendant", rowId);else menuRef.current?.removeAttribute("aria-activedescendant");- }, [ active, submenus, rows ]);+ }, [ active, open, rows ]);// A custom row takes focus in itself, for its own keys; any other row hands it back to the menu.useLayoutEffect(() => {const menu = menuRef.current;- if (!menu || !active) return;- if (isCustom(active.item)) {- focusTarget(rows.get(active.item))?.focus({ preventScroll: true });+ const row = active && rows.get(active.id);+ if (!menu || !row) return;+ if (row.custom) {+ focusTarget(row.element)?.focus({ preventScroll: true });} else if (document.activeElement !== menu && menu.contains(document.activeElement)) {menu.focus({ preventScroll: true });}@@ -150,50 +220,41 @@ export default function Menu<T>({ id, className, x, y, orientation, bottomSheet,return () => window.removeEventListener("keydown", listener, true);}, []);- /** The rows the keys can stand on at `level`: those that run something, and custom rows with something to focus. */- function navigableRows(level: number) {- return menuRows(level === 0 ? items : submenus[level - 1]?.item.items ?? [])- .filter((row): row is NavigableItem<T> => isCustom(row)- ? !!focusTarget(rows.get(row))- : isRunnable(row));- }-function onKeyDown(e: KeyboardEvent) {const level = active?.level ?? 0;const levelRows = navigableRows(level);- const index = active ? levelRows.indexOf(active.item) : -1;+ const index = active ? levelRows.indexOf(active.id) : -1;const count = levelRows.length;+ const activeRow = active && rows.get(active.id);// A submenu goes with its row's highlight, as in a native menu, until Right opens it again.- const moveTo = (item: NavigableItem<T>) => {- if (submenus[level]?.item !== item) openSubmenu(level);- setActive(level, item);+ const moveTo = (rowId: string) => {+ if (open[level]?.id !== rowId) openSubmenu(level);+ setActive(level, rowId);};const goTo = (position: number) => {- const item = levelRows[((position % count) + count) % count];- if (item) moveTo(item);+ const rowId = levelRows[((position % count) + count) % count];+ if (rowId) moveTo(rowId);};const openActive = () => {- const item = active && !isCustom(active.item) ? active.item : undefined;- const anchor = item && rows.get(item);- if (!item?.items || !anchor) return;- openSubmenu(level, item, anchor, true);- const first = runnableRows(item.items)[0];- if (first) setActive(level + 1, first);+ if (!active || !activeRow?.hasSubmenu || activeRow.custom) return;+ openSubmenu(level, active.id, activeRow.element, true);+ // A submenu already open has its rows; one opening now has them once it renders.+ if (!activateFirstRow(level + 1)) pendingFirstRow.current = level + 1;};const closeLevel = (closing: number) => {- const parent = submenus[closing - 1];+ const parent = open[closing - 1];if (!parent) return;openSubmenu(closing - 1);- setActive(closing - 1, parent.item);+ setActive(closing - 1, parent.id);};const rtl = handleRightToLeftPlacement("right") !== "right";/** Moves to the row beside the active one in a menu laid out in columns, if there is one. */const moveAcross = (towards: "left" | "right") => {- const boxes = levelRows.map((item) => rows.get(item)?.getBoundingClientRect());+ const boxes = levelRows.map((rowId) => rows.get(rowId)?.element.getBoundingClientRect());const target = rowInNextColumn(boxes, index, towards);- const item = target !== undefined ? levelRows[target] : undefined;- if (item) moveTo(item);- return !!item;+ const rowId = target !== undefined ? levelRows[target] : undefined;+ if (rowId) moveTo(rowId);+ return !!rowId;};switch (e.key) {@@ -203,7 +264,7 @@ export default function Menu<T>({ id, className, x, y, orientation, bottomSheet,case "End": goTo(-1); break;// Into the active row's submenu, or else across to the next column.case rtl ? "ArrowLeft" : "ArrowRight":- if (active && !isCustom(active.item) && active.item.items) openActive();+ if (activeRow && !activeRow.custom && activeRow.hasSubmenu) openActive();else moveAcross(e.key === "ArrowRight" ? "right" : "left");break;// Back across a column, or else out of the submenu.@@ -212,13 +273,13 @@ export default function Menu<T>({ id, className, x, y, orientation, bottomSheet,break;case "Enter":case " ":- if (!active || isCustom(active.item)) break;+ if (!activeRow || activeRow.custom) break;openActive();- onSelect(active.item, e);+ activeRow.select(e);break;case "Escape":// One level at a time, then the menu itself.- if (submenus.length) closeLevel(submenus.length);+ if (open.length) closeLevel(open.length);else onClose();break;// Focus stays in the menu until it closes.@@ -232,9 +293,9 @@ export default function Menu<T>({ id, className, x, y, orientation, bottomSheet,// A first letter looks past the active row, so pressing it again moves on.const skip = typed.text.length === 1 ? 1 : 0;for (let step = skip; step < count + skip; step++) {- const item = levelRows[(index + step + count) % count];- if (item && rows.get(item)?.textContent?.trim().toLowerCase().startsWith(typed.text)) {- moveTo(item);+ const rowId = levelRows[(index + step + count) % count];+ if (rowId && rows.get(rowId)?.element.textContent?.trim().toLowerCase().startsWith(typed.text)) {+ moveTo(rowId);break;}}@@ -277,164 +338,89 @@ export default function Menu<T>({ id, className, x, y, orientation, bottomSheet,}, [ x, y, orientation, bottomSheet ]);return (- <div- ref={menuRef} id={id} role="menu" tabIndex={-1}- className={clsx("dropdown-menu show tn-menu", bottomSheet && "mobile-bottom-menu",- keyboardDriven && "tn-menu-keyboard", className)}- onPointerMove={(e) => {- if (pointerMoved(e)) setKeyboardDriven(false);- }}- // Neither the browser's menu nor another of the app's opens over this one. Every level- // is inside this element, so one handler covers them all.- onContextMenu={(e) => {- e.preventDefault();- e.stopPropagation();- }}- >- {/* The rows scroll in here rather than the menu itself, so the theme's blur on the- menu's `::before` stays behind them. A `<menu>`, as rows are its list items, out of- the accessibility tree so they read as the menu's own. */}- <menu className="tn-menu-scroll" role="none">- <MenuList level={0} items={items} state={state} />- </menu>- {/* Inside the menu, so the rules scoped to it apply, but none inside another: a fixed- layer escapes a scrolling menu only while no ancestor carries a filter. */}- {/* A phone unfolds the open submenus under their rows instead (see MenuRow). */}- {!isMobile() && submenus.map((submenu, index) => (- <SubmenuLayer key={submenu.key} level={index + 1} submenu={submenu} state={state} />- ))}- </div>- );-}--/**- * A submenu opened on the desktop, placed beside the row it opened from rather than nested in it,- * so a scrolling menu neither clips it nor scrolls it away.- */-function SubmenuLayer<T>({ level, submenu, state }: { level: number, submenu: OpenSubmenu<T>, state: MenuState<T> }) {- const layerRef = useRef<HTMLDivElement>(null);- const columns = (submenu.item.columns ?? 1) > 1 ? submenu.item.columns : undefined;- const items = submenu.item.items ?? [];-- useLayoutEffect(() => {- const layer = layerRef.current;- if (!layer) return;-- const placement = handleRightToLeftPlacement("right") === "right" ? "right-start" : "left-start";- return autoUpdate(submenu.anchor, layer, () => void placeMenu(layer, submenu.anchor, placement, true));- }, [ submenu.anchor ]);-- // In a `.dropdown-submenu`, so the theme's submenu rules apply.- return (- <div className="dropdown-submenu">+ <MenuContext.Provider value={context}><div- ref={layerRef} role="menu" aria-labelledby={titleId(submenu.anchor.id)}- className={clsx("dropdown-menu show tn-menu", submenu.immediate && "tn-menu-immediate")}+ ref={setMenuElement} id={id} role="menu" tabIndex={-1}+ className={clsx("dropdown-menu show tn-menu", bottomSheet && "mobile-bottom-menu",+ keyboardDriven && "tn-menu-keyboard", className)}+ onPointerMove={(e) => {+ if (pointerMoved(e)) setKeyboardDriven(false);+ }}+ // Neither the browser's menu nor another of the app's opens over this one. Every level+ // is inside this element, so one handler covers them all.+ onContextMenu={(e) => {+ e.preventDefault();+ e.stopPropagation();+ }}>- {/* Like the top level, so the blur on the layer's `::before` stays behind its rows. */}- {columns- // The columns go on an inner list of their full height, so a capped menu- // scrolls them rather than growing more columns to the side.- ? (- <div className="tn-menu-scroll">- <menu className="tn-menu-columns" role="none" style={{ columnCount: columns }}>- <MenuList level={level} items={items} state={state} columns />- </menu>- </div>- )- : (- <menu className="tn-menu-scroll" role="none">- <MenuList level={level} items={items} state={state} />- </menu>- )}+ {/* The rows scroll in here rather than the menu itself, so the theme's blur on the+ menu's `::before` stays behind them. A `<menu>`, as rows are its list items, out of+ the accessibility tree so they read as the menu's own. */}+ <menu className="tn-menu-scroll" role="none">+ {items ? <MenuItems items={items} onSelect={onSelect} /> : children}+ </menu>+ {/* The submenus' layers follow the scroller in here, portaled by their rows. */}</div>- </div>+ </MenuContext.Provider>);}-function MenuList<T>({ level, items, state, columns }: {- level: number,- items: MenuItem<T>[],- state: MenuState<T>,- /** Wraps the rows a column must not break between in `.dropdown-no-break`. */- columns?: boolean-}) {- const rows = menuRows(items);- if (!columns) return <>{rows.map((row, index) => <MenuListRow key={index} level={level} row={row} state={state} />)}</>;-- return <>- {unbreakableGroups(rows).map((group, groupIndex) => (group.length > 1- ? (- <li key={groupIndex} className="dropdown-no-break" role="none">- <menu role="none">- {group.map((row, index) => <MenuListRow key={index} level={level} row={row} state={state} />)}- </menu>- </li>- )- : <MenuListRow key={groupIndex} level={level} row={group[0]} state={state} />- ))}- </>;-}--function MenuListRow<T>({ level, row, state }: { level: number, row: MenuItem<T>, state: MenuState<T> }) {- if (!("kind" in row)) return <MenuRow level={level} item={row} state={state} />;- if (row.kind === "separator") return <li className="dropdown-divider" role="separator" />;- // As `FormListHeader` draws one.- if (row.kind === "header") return <li role="none"><h6 className="dropdown-header">{row.title}</h6></li>;- return (- <li- className="dropdown-custom-item"- // Its content carries the roles of what it acts with.- role="none"- ref={(element) => {- if (element) state.rows.set(row, element);- else state.rows.delete(row);- }}- // Only a click on what the row acts with closes the menu: one in the space around it,- // such as between the color picker's cells, picks nothing.- onClick={(e) => {- if (actsOnClick(e.target, e.currentTarget)) state.onClose();- }}- >- <row.componentFn />- </li>- );+export interface MenuCommandProps extends Pick<MenuCommandItem<unknown>, "title" | "uiIcon" | "iconColorClass" | "checked"+ | "enabled" | "shortcut" | "keyboardShortcut" | "badges" | "trailingIcon" | "className" | "columns"> {+ /** Called when the row is pressed with the primary button, or run from the keyboard. */+ onSelect?(e: MouseEvent | KeyboardEvent): void;+ /** Whether running the row closes the menu. A row does, and one that opens a submenu does not. */+ closeOnSelect?: boolean;+ /** The rows of the submenu this row opens. */+ children?: ComponentChildren;}-function MenuRow<T>({ level, item, state }: { level: number, item: MenuCommandItem<T>, state: MenuState<T> }) {- const disabled = item.enabled === false;- const hasSubmenu = !!item.items;- const open = state.openItems[level] === item;- const active = state.active?.level === level && state.active.item === item;+/**+ * A row that runs a command, or with children, opens them as its submenu. As with+ * {@link MenuCommandItem}, a row given `uiIcon` or `checked`, even as nothing, keeps a slot for+ * the icon, and one given `checked` can be checked.+ */+export function MenuCommand(props: MenuCommandProps) {+ const { title, enabled, badges, trailingIcon, className, columns, onSelect, closeOnSelect, children } = props;+ const menu = useMenu();+ const level = useContext(MenuLevelContext);const id = useId();- // As `MenuIconSlot` reads it: an item with a `checked` key is one that can be checked.- const checkable = "checked" in item;+ const disabled = enabled === false;+ const hasSubmenu = children !== undefined && children !== null && children !== false;+ const openSubmenu = menu.open[level];+ const open = openSubmenu?.id === id;+ const active = menu.active?.id === id;+ const checkable = "checked" in props;++ function select(e: MouseEvent | KeyboardEvent) {+ if (closeOnSelect ?? !hasSubmenu) menu.close();+ onSelect?.(e);+ }function onPointed(e: { currentTarget: HTMLLIElement }) {if (isMobile()) return;// The keyboard goes on from the row the pointer last pointed at.- if (!disabled) state.setActive(level, item);- state.openSubmenu(level, hasSubmenu && !disabled ? item : undefined, e.currentTarget);+ if (!disabled) menu.setActive(level, id);+ menu.openSubmenu(level, hasSubmenu && !disabled ? id : undefined, e.currentTarget);}return (<liid={id}ref={(element) => {- if (element) state.rows.set(item, element);- else state.rows.delete(item);+ menu.registerRow(id, element ? { level, element, custom: false, disabled, hasSubmenu, select } : undefined);}}className={clsx("dropdown-item", hasSubmenu && "dropdown-submenu", open && "submenu-open",- active && "tn-menu-active", disabled && "disabled", item.className)}+ active && "tn-menu-active", disabled && "disabled", className)}role={checkable ? "menuitemcheckbox" : "menuitem"}- aria-checked={checkable ? !!item.checked : undefined}+ aria-checked={checkable ? !!props.checked : undefined}aria-disabled={disabled || undefined}aria-haspopup={hasSubmenu ? "menu" : undefined}aria-expanded={hasSubmenu ? open : undefined}// While the keys drive the menu, a row entered by a pointer at rest, as when the menu// appears under it, keeps the keys' row. See `pointerMoved`.onPointerEnter={(e) => {- if (!state.keyboardDriven) onPointed(e);+ if (!menu.keyboardDriven) onPointed(e);}}// The keys can move the active row from under a pointer at rest, whose `:hover` would// then mark a second row. The next move of the pointer makes its row the active one.@@ -453,46 +439,189 @@ function MenuRow<T>({ level, item, state }: { level: number, item: MenuCommandIt// Pressed again, an unfolded row folds its submenu back.if (hasSubmenu && isMobile()) {- state.openSubmenu(level, open ? undefined : item, e.currentTarget, true);+ menu.openSubmenu(level, open ? undefined : id, e.currentTarget, true);return;}- if (hasSubmenu) state.openSubmenu(level, item, e.currentTarget, true);- state.onSelect(item, e);+ if (hasSubmenu) menu.openSubmenu(level, id, e.currentTarget, true);+ select(e);}}><span className={hasSubmenu ? "dropdown-toggle" : undefined}>- <MenuIconSlot item={item} />+ <MenuIconSlot {...props} /><span className="tn-menu-gap" />{/* Callers pass HTML: titles escaped with `escapeHtml()` or boxed by `menuName()`. */}- <span id={titleId(id)} dangerouslySetInnerHTML={{ __html: item.title }} />- {item.badges?.map((badge, index) => (+ <span id={titleId(id)} dangerouslySetInnerHTML={{ __html: title }} />+ {badges?.map((badge, index) => (<span key={index} className={clsx("badge", badge.className)}>{badge.title}</span>))}- <MenuShortcut item={item} />- {item.trailingIcon && <span className={clsx(item.trailingIcon, "tn-icon", "menu-trailing-icon")} />}+ <MenuShortcut {...props} />+ {trailingIcon && <span className={clsx(trailingIcon, "tn-icon", "menu-trailing-icon")} />}</span>- {/* A phone has no room beside the menu, so an open submenu unfolds under its row. */}- {hasSubmenu && isMobile() && (- <ul className={clsx("dropdown-menu", open && "show")} role="menu" aria-labelledby={titleId(id)}>- {open && <MenuList level={level + 1} items={item.items ?? []} state={state} />}- </ul>- )}+ {hasSubmenu && (isMobile()+ // A phone has no room beside the menu, so an open submenu unfolds under its row.+ ? (+ <ul className={clsx("dropdown-menu", open && "show")} role="menu" aria-labelledby={titleId(id)}>+ <MenuLevelContext.Provider value={level + 1}>{open && children}</MenuLevelContext.Provider>+ </ul>+ )+ : open && openSubmenu && menu.layerHost && createPortal((+ <SubmenuLayer level={level + 1} submenu={openSubmenu} columns={columns}>{children}</SubmenuLayer>+ ), menu.layerHost))}</li>);}+export function MenuSeparator() {+ return <li className="dropdown-divider" role="separator" />;+}++/** A heading over the rows after it. Its title is text, as it can be a name the user wrote. */+export function MenuHeader({ title }: { title: string }) {+ // As `FormListHeader` draws one.+ return <li role="none"><h6 className="dropdown-header">{title}</h6></li>;+}++/**+ * A row holding a control of its own, such as the color picker. The keys stand on it when its+ * content marks a way in with `tabindex="0"`, and a click on something in it that acts closes the+ * menu.+ */+export function MenuCustom({ children }: { children: ComponentChildren }) {+ const menu = useMenu();+ const level = useContext(MenuLevelContext);+ const id = useId();++ return (+ <li+ className="dropdown-custom-item"+ // Its content carries the roles of what it acts with.+ role="none"+ ref={(element) => {+ menu.registerRow(id, element+ ? { level, element, custom: true, disabled: false, hasSubmenu: false, select: () => {} }+ : undefined);+ }}+ // Only a click on what the row acts with closes the menu: one in the space around it,+ // such as between the color picker's cells, picks nothing.+ onClick={(e) => {+ if (actsOnClick(e.target, e.currentTarget)) menu.close();+ }}+ >+ {children}+ </li>+ );+}++function useMenu() {+ const menu = useContext(MenuContext);+ if (!menu) throw new Error("A menu row must be rendered inside a Menu.");+ return menu;+}++/**+ * A submenu opened on the desktop, placed beside the row it opened from rather than nested in it,+ * so a scrolling menu neither clips it nor scrolls it away.+ */+function SubmenuLayer({ level, submenu, columns, children }: {+ level: number,+ submenu: OpenSubmenu,+ columns?: number,+ children: ComponentChildren+}) {+ const layerRef = useRef<HTMLDivElement>(null);+ const columnCount = (columns ?? 1) > 1 ? columns : undefined;++ useLayoutEffect(() => {+ const layer = layerRef.current;+ if (!layer) return;++ const placement = handleRightToLeftPlacement("right") === "right" ? "right-start" : "left-start";+ return autoUpdate(submenu.anchor, layer, () => void placeMenu(layer, submenu.anchor, placement, true));+ }, [ submenu.anchor ]);++ // In a `.dropdown-submenu`, so the theme's submenu rules apply.+ return (+ <MenuLevelContext.Provider value={level}>+ <div className="dropdown-submenu">+ <div+ ref={layerRef} role="menu" aria-labelledby={titleId(submenu.anchor.id)}+ className={clsx("dropdown-menu show tn-menu", submenu.immediate && "tn-menu-immediate")}+ >+ {/* Like the top level, so the blur on the layer's `::before` stays behind its rows. */}+ {columnCount+ // The columns go on an inner list of their full height, so a capped menu+ // scrolls them rather than growing more columns to the side.+ ? (+ <div className="tn-menu-scroll">+ <menu className="tn-menu-columns" role="none" style={{ columnCount }}>+ {children}+ </menu>+ </div>+ )+ : <menu className="tn-menu-scroll" role="none">{children}</menu>}+ </div>+ </div>+ </MenuLevelContext.Provider>+ );+}++/**+ * `items` drawn as the rows that stand for them, with a run of separators reduced to one. In+ * `columns`, the rows a column must not break between are wrapped in `.dropdown-no-break`.+ */+function MenuItems<T>({ items, onSelect, columns }: {+ items: MenuItem<T>[],+ onSelect: MenuProps<T>["onSelect"],+ columns?: boolean+}) {+ const rows = menuRows(items);+ if (!columns) return <>{rows.map((row, index) => <MenuItemRow key={index} row={row} onSelect={onSelect} />)}</>;++ return <>+ {unbreakableGroups(rows).map((group, groupIndex) => (group.length > 1+ ? (+ <li key={groupIndex} className="dropdown-no-break" role="none">+ <menu role="none">+ {group.map((row, index) => <MenuItemRow key={index} row={row} onSelect={onSelect} />)}+ </menu>+ </li>+ )+ : <MenuItemRow key={groupIndex} row={group[0]} onSelect={onSelect} />+ ))}+ </>;+}++function MenuItemRow<T>({ row, onSelect }: { row: MenuItem<T>, onSelect: MenuProps<T>["onSelect"] }) {+ if ("kind" in row) {+ if (row.kind === "separator") return <MenuSeparator />;+ if (row.kind === "header") return <MenuHeader title={row.title} />;+ return <MenuCustom><row.componentFn /></MenuCustom>;+ }++ // The rest keeps `uiIcon` and `checked` only where the item has them, which `MenuCommand` reads.+ const { items, command: _command, handler: _handler, type: _type, mime: _mime, templateNoteId: _templateNoteId,+ spellingSuggestion: _spellingSuggestion, ...props } = row;+ return (+ // `onSelect` decides whether the menu closes, as `contextMenu` does.+ <MenuCommand {...props} closeOnSelect={false} onSelect={(e) => onSelect?.(row, e)}>+ {/* A phone unfolds a submenu in a single column. */}+ {items ? <MenuItems items={items} onSelect={onSelect} columns={(row.columns ?? 1) > 1 && !isMobile()} /> : undefined}+ </MenuCommand>+ );+}+/** The id of a row's title, which names the submenu it opens. */function titleId(rowId: string) {return `${rowId}-title`;}/**- * The shortcuts of the item's `keyboardShortcut` action as the user configured them, or else its+ * The shortcuts of the row's `keyboardShortcut` action as the user configured them, or else its* literal `shortcut`. Read synchronously, so the menu is placed at its final width.*/-function MenuShortcut<T>({ item }: { item: MenuCommandItem<T> }) {- if (item.keyboardShortcut) {- const shortcuts = getActionSync(item.keyboardShortcut)?.effectiveShortcuts;+function MenuShortcut({ keyboardShortcut, shortcut }: Pick<MenuCommandProps, "keyboardShortcut" | "shortcut">) {+ if (keyboardShortcut) {+ const shortcuts = getActionSync(keyboardShortcut)?.effectiveShortcuts;if (!shortcuts?.length) return null;return (<span className="keyboard-shortcut">@@ -501,20 +630,20 @@ function MenuShortcut<T>({ item }: { item: MenuCommandItem<T> }) {);}- return item.shortcut ? <kbd>{item.shortcut}</kbd> : null;+ return shortcut ? <kbd>{shortcut}</kbd> : null;}/**- * The icon, or a check mark in its place. An item that sets `uiIcon` to nothing gets a blank slot,+ * The icon, or a check mark in its place. A row that sets `uiIcon` to nothing gets a blank slot,* and one without `uiIcon` or `checked` an empty one.*/-function MenuIconSlot<T>({ item }: { item: MenuCommandItem<T> }) {- if (!("uiIcon" in item || "checked" in item)) return <span />;+function MenuIconSlot(props: Pick<MenuCommandProps, "uiIcon" | "checked" | "iconColorClass">) {+ if (!("uiIcon" in props || "checked" in props)) return <span />;- const icon = item.checked ? "bx bx-check" : item.uiIcon;+ const icon = props.checked ? "bx bx-check" : props.uiIcon;return icon- ? <span className={clsx(icon, "tn-icon", item.iconColorClass)} />- : <span>{"\u00a0"}</span>;+ ? <span className={clsx(icon, "tn-icon", props.iconColorClass)} />+ : <span>{" "}</span>;}/** How far apart, in pixels, two rows' left edges can be and still stand in one column. */@@ -555,11 +684,6 @@ export function rowInNextColumn(return nearest?.index;}-/** The rows the keyboard can reach: those that run something, and are enabled. */-function runnableRows<T>(items: MenuItem<T>[]) {- return menuRows(items).filter(isRunnable);-}-/*** Whether the pointer really moved. A menu appearing under a pointer at rest has the browser enter* the row there, and Chromium follow with a `pointermove` that goes nowhere; neither is the user@@ -569,14 +693,6 @@ function pointerMoved(e: PointerEvent) {return e.movementX !== 0 || e.movementY !== 0;}-function isRunnable<T>(row: MenuItem<T>): row is MenuCommandItem<T> {- return !("kind" in row) && row.enabled !== false;-}--function isCustom<T>(row: MenuItem<T>): row is CustomMenuItem {- return "kind" in row && row.kind === "custom";-}-/** What a custom row's content acts with: the elements a click on does something. */const ACTING_ELEMENTS = "button, a[href], input, select, textarea, [tabindex], "+ "[role='button'], [role='option'], [role='menuitem'], [role='checkbox'], [role='radio'], [role='switch']";