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
docs(menu): write this branch's recent comments and test names plainly
Elian Doran9d377ba41309
diff --git a/apps/client/src/stylesheets/style.css b/apps/client/src/stylesheets/style.cssindex d9c1440d61..ab709e87dc 100644--- a/apps/client/src/stylesheets/style.css+++ b/apps/client/src/stylesheets/style.css@@ -462,8 +462,8 @@ button kbd {display: contents;}-/* Just under the popup it is drawn for, whose z-index (1200) is set in `Popup.css`. Dressed as a- dialog's backdrop, a menu that dims the page being the same thing to the reader. */+/* Just under its popup, whose z-index (1200) is set in `Popup.css`. Styled as a dialog's+ backdrop. */body > .tn-dropdown-portal > .tn-dropdown-backdrop {position: fixed;inset: 0;diff --git a/apps/client/src/stylesheets/theme-next/base.css b/apps/client/src/stylesheets/theme-next/base.cssindex 4a45bc4645..bd66f161ba 100644--- a/apps/client/src/stylesheets/theme-next/base.css+++ b/apps/client/src/stylesheets/theme-next/base.css@@ -243,7 +243,7 @@ body.desktop .dropdown-item.dropdown-submenu .dropdown-toggle,}}-/* A level's rows are all in its `.tn-menu-scroll`, and its submenus' layers outside it. */+/* Each menu level holds its rows in its own `.tn-menu-scroll`; submenu layers are outside it. */body.desktop .tn-menu-scroll:has(.dropdown-submenu.dropstart) .dropdown-item:not(.dropdown-submenu),body.desktop .tn-menu-scroll:has(.dropdown-submenu.dropstart) .dropdown-item.dropdown-submenu .dropdown-toggle {padding-inline-end: var(--menu-item-start-padding) !important;diff --git a/apps/client/src/widgets/react/Button.spec.tsx b/apps/client/src/widgets/react/Button.spec.tsxindex 58400d717a..d2d5cee005 100644--- a/apps/client/src/widgets/react/Button.spec.tsx+++ b/apps/client/src/widgets/react/Button.spec.tsx@@ -13,13 +13,13 @@ describe("SplitButton", () => {document.body.append(host);afterEach(() => render(null, host));- /** A press and its release, as a pointer makes them. */+ /** Dispatches a press and its click. */const press = (element: Element) => {element.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true }));element.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));};- it("runs its own action from the main half, and opens the others as a menu from the split", async () => {+ it("runs its action from the main button, and opens the rest from the toggle", async () => {const calls: string[] = [];render((<SplitButton text="Search" icon="bx bx-search" onClick={() => calls.push("search")}>@@ -35,7 +35,7 @@ describe("SplitButton", () => {expect(calls).toEqual([ "search" ]);expect(document.querySelector("[role=menu]")).toBeNull();- // A menu of the app's own, which Bootstrap's data API has no part in.+ // The app's own menu, not one opened by Bootstrap's data API.expect(toggle.hasAttribute("data-bs-toggle")).toBe(false);expect(toggle.getAttribute("aria-label")).toBe("split_button.more_actions");expect(toggle.getAttribute("aria-haspopup")).toBe("menu");diff --git a/apps/client/src/widgets/react/FormList.spec.tsx b/apps/client/src/widgets/react/FormList.spec.tsxindex 72f82426d0..416985ef30 100644--- a/apps/client/src/widgets/react/FormList.spec.tsx+++ b/apps/client/src/widgets/react/FormList.spec.tsx@@ -1,7 +1,7 @@import { type ComponentChildren, render } from "preact";import { describe, expect, it, vi } from "vitest";-// Rows with a tooltip reach Bootstrap's; stub it so they mount without its layout machinery.+// Rows with a tooltip use Bootstrap's `Tooltip`, stubbed so they mount without its layout code.vi.mock("bootstrap", () => ({Tooltip: class { static getInstance() { return null; } }}));@@ -137,7 +137,7 @@ describe("FormListCustomItem", () => {});describe("FormDropdownSubmenu", () => {- it("heads its rows with its title outside any menu, where there is no layer to open", () => {+ it("renders its title as a header above its rows outside a menu", () => {const host = document.createElement("div");render(<menu><FormDropdownSubmenu icon="bx bx-chip" title="Advanced"><FormListItem>Reload</FormListItem>@@ -195,7 +195,7 @@ describe("FormList keyboard activation", () => {expect(event.defaultPrevented).toBe(false);});- it("moves focus over the enabled items with Up and Down, keeping the keys from the document", () => {+ it("moves focus over enabled items with Up and Down, stopping the keys", () => {const container = mount(<FormList><input className="embedded-search" />@@ -211,14 +211,14 @@ describe("FormList keyboard activation", () => {press(getItem(container, "text"), "ArrowDown");expect(document.activeElement).toBe(getItem(container, "book"));- // Round from the last item to the first.+ // Wraps from the last item to the first.press(getItem(container, "book"), "ArrowDown");expect(document.activeElement).toBe(getItem(container, "text"));press(getItem(container, "text"), "ArrowUp");expect(document.activeElement).toBe(getItem(container, "book"));expect(documentHeard).not.toHaveBeenCalled();- // A field keeps its own.+ // Arrow keys in a field are left to the field.const input = container.querySelector<HTMLInputElement>(".embedded-search");expect(input).not.toBeNull();const event = press(input as HTMLInputElement, "ArrowDown");@@ -226,7 +226,7 @@ describe("FormList keyboard activation", () => {document.removeEventListener("keydown", documentHeard, true);});- it("keeps Escape from Bootstrap's handler, and from a dialog around it as that handler did", () => {+ it("stops Escape before Bootstrap's handler and a dialog around the list", () => {const container = mount(<FormList><FormListItem value="text">Text</FormListItem></FormList>);const dialogHeard = vi.fn();container.addEventListener("keydown", dialogHeard);diff --git a/apps/client/src/widgets/react/FormList.tsx b/apps/client/src/widgets/react/FormList.tsxindex d20344ee2f..8a0b392d36 100644--- a/apps/client/src/widgets/react/FormList.tsx+++ b/apps/client/src/widgets/react/FormList.tsx@@ -30,8 +30,8 @@ export default function FormList({ children, onSelect, style, fullHeight, wrappeconst listRef = useRef<HTMLDivElement | null>(null);// Captured at the window: Bootstrap captures Escape, Up and Down at the document for any- // `.dropdown-menu`, and throws for one with no toggle beside it. Escape goes no further, as- // Bootstrap kept it from a dialog around the list too.+ // `.dropdown-menu`, and throws when no toggle is next to it. Escape is stopped here, as+ // Bootstrap's handler also kept it from a dialog around the list.useLayoutEffect(() => {const onKeyDown = (e: KeyboardEvent) => {const list = listRef.current;@@ -108,8 +108,8 @@ function onDropdownMenuKeyDown(e: KeyboardEvent) {}/**- * Focuses an enabled item of `list`'s own, not one in a submenu nested in it: the first or the- * last, or the one after or before `from`, going round at either end.+ * Focuses an enabled item that belongs to `list` itself, not to a nested submenu: the first, the+ * last, or the one after or before `from`, wrapping at either end.*/export function focusListItem(list: HTMLElement, where: "first" | "last" | "next" | "previous", from?: Element) {const items = [ ...list.querySelectorAll<HTMLElement>(".dropdown-item:not(.disabled):not(:disabled)") ]@@ -380,9 +380,9 @@ export interface FormDropdownSubmenuProps {}/**- * A row that opens its children as a submenu, in a layer of its own beside the row, which a- * scrolling menu neither clips nor scrolls away. Outside a `Menu`, which only a script can render,- * its title heads its children in the list.+ * A row that opens its children as a submenu, in a separate layer beside the row, so a scrolling+ * menu neither clips it nor scrolls it away. Outside a `Menu`, which only a script can arrange, it+ * renders its title as a `FormListHeader` above its children.*/export function FormDropdownSubmenu(props: FormDropdownSubmenuProps) {const menu = useContext(MenuContext);@@ -505,7 +505,7 @@ function SubmenuLayer({ level, submenu, columns, children }: {shiftAcross: true, capHeight: true, hideWithAnchor: true} as const;return autoUpdate(submenu.anchor, layer, () => void placeFloating(layer, submenu.anchor, options).then((placed) => {- // Flipped for want of room, it turns the arrows of its parent level's rows with it.+ // After a flip, the parent level follows, so its rows' arrows match.const placedDropStart = placed.startsWith(startSide);if (placedDropStart !== dropStart) {setDropStart(level - 1, placedDropStart);diff --git a/apps/client/src/widgets/react/Menu.spec.tsx b/apps/client/src/widgets/react/Menu.spec.tsxindex 542d6de8bc..fdd2cef8aa 100644--- a/apps/client/src/widgets/react/Menu.spec.tsx+++ b/apps/client/src/widgets/react/Menu.spec.tsx@@ -41,22 +41,22 @@ describe("rowInNextColumn", () => {});describe("shouldDropStart", () => {- /** A level 200px wide, standing at `left` in a viewport 1000px wide. */+ /** A level 200px wide at `left`, in a viewport 1000px wide. */const at = (left: number) => ({ left, right: left + 200, width: 200 });- it("opens towards the end while there is room there, and turns only for more room at the start", () => {+ it("opens towards the end, and towards the start only when the start has more room", () => {expect(shouldDropStart(at(100), 1000, false, false)).toBe(false);expect(shouldDropStart(at(750), 1000, false, false)).toBe(true);- // Cramped on both sides, it keeps to the end unless the start has more.+ // Short of room on both sides, it stays at the end unless the start has more.expect(shouldDropStart(at(50), 300, false, false)).toBe(false);});- it("keeps to the start once its level opened that way, until the room there runs out", () => {+ it("stays at the start once its level opened that way, until the room runs out", () => {expect(shouldDropStart(at(400), 1000, false, true)).toBe(true);expect(shouldDropStart(at(100), 1000, false, true)).toBe(false);});- it("measures the end on the left when the page reads right to left", () => {+ it("treats the left as the end in a right-to-left layout", () => {expect(shouldDropStart(at(750), 1000, true, false)).toBe(false);expect(shouldDropStart(at(50), 1000, true, false)).toBe(true);});@@ -175,8 +175,8 @@ describe("Menu with declared rows", () => {expect(calls).toEqual([ "log", "close" ]);});- it("turns its submenus and their arrows towards the start where the end has no room", async () => {- // The menus and their rows stand 120px wide against the right edge of a 1024px viewport.+ it("opens submenus towards the start, arrows too, when the end has no room", async () => {+ // The menus and their rows are 120px wide, at the right edge of a 1024px viewport.vi.spyOn(document.documentElement, "clientWidth", "get").mockReturnValue(1024);vi.spyOn(document.documentElement, "clientHeight", "get").mockReturnValue(768);const measure = HTMLElement.prototype.getBoundingClientRect;@@ -193,8 +193,8 @@ describe("Menu with declared rows", () => {advanced.dispatchEvent(new PointerEvent("pointerenter"));await vi.waitFor(() => expect(layers(menu)).toHaveLength(1));const layer = menu.querySelector<HTMLElement>(":scope > div.dropdown-submenu > .dropdown-menu");- // By the row's left edge, at 900px, rather than its right edge, at 1020px. happy-dom lays- // the layer out 0px wide.+ // Next to the row's left edge (900px), not its right edge (1020px). happy-dom gives the+ // layer no width.await vi.waitFor(() => expect(parseFloat(layer?.style.left ?? "")).toBeLessThan(910));expect(advanced.classList).toContain("dropstart");} finally {diff --git a/apps/client/src/widgets/react/Popup.spec.tsx b/apps/client/src/widgets/react/Popup.spec.tsxindex f111453a21..b3b6beceae 100644--- a/apps/client/src/widgets/react/Popup.spec.tsx+++ b/apps/client/src/widgets/react/Popup.spec.tsx@@ -164,12 +164,12 @@ describe("Popup", () => {outside.remove();});- it("keeps the click of a dismissing press from what the press uncovered, but not from what it pressed", async () => {+ it("drops the click after a dismissing press unless it lands on what was pressed", async () => {anchorAt(100, 50);const popup = await open({ onDismiss: vi.fn() });const press = (target: Element) => target.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true }));const click = (target: Element) => target.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));- // A phone's cover, which the popup takes away before the tap's click, and an icon under it.+ // A phone's cover, hidden with the popup before the tap's click, and an icon under it.const cover = document.createElement("div");const icon = document.createElement("button");const iconClicked = vi.fn();@@ -179,7 +179,7 @@ describe("Popup", () => {press(cover);click(icon);expect(iconClicked).not.toHaveBeenCalled();- // Only the one click.+ // Only the first click is dropped.click(icon);expect(iconClicked).toHaveBeenCalledTimes(1);@@ -187,7 +187,7 @@ describe("Popup", () => {click(icon);expect(iconClicked).toHaveBeenCalledTimes(2);- // A press inside dismisses nothing, so its click goes where it lands.+ // A press inside the popup does not dismiss it, so its click is kept.press(popup);click(icon);expect(iconClicked).toHaveBeenCalledTimes(3);diff --git a/apps/client/src/widgets/react/Popup.tsx b/apps/client/src/widgets/react/Popup.tsxindex 781d169cad..e874f4e4f0 100644--- a/apps/client/src/widgets/react/Popup.tsx+++ b/apps/client/src/widgets/react/Popup.tsx@@ -173,8 +173,8 @@ export default function Popup({ anchor, placement = "bottom-start", offset: gap/*** Drops the click that follows a press dismissing a popup when it lands on something other than- * `pressed`. A cover or a backdrop goes away with the popup before a tap's click, which then lands- * on whatever stood under it, as an icon under the icon picker's menu.+ * `pressed`. A cover or backdrop is removed with the popup before a tap's click, so the click lands+ * on the element under it, such as an icon under the icon picker's menu.*/function swallowStrayClick(pressed: Node) {const onClick = (e: MouseEvent) => {@@ -183,7 +183,8 @@ function swallowStrayClick(pressed: Node) {e.preventDefault();e.stopPropagation();};- // A press that makes no click, as one that scrolls, leaves nothing for the next press's.+ // The next press removes the listener, so a press without a click, such as a scroll, cannot+ // drop a later click.const stop = () => {window.removeEventListener("click", onClick, true);window.removeEventListener("pointerdown", stop, true);@@ -233,7 +234,7 @@ export interface FloatingPlacement {* Positions `element` beside `anchor`, preferring its placement, then the side opposite, then the* other alignment on either side, the way a native menu opens above or to the left of a pointer* near the viewport's edge. It stays hidden until placed, so it never paints at a stale position.- * Resolves to the placement it took.+ * Resolves to the placement Floating UI chose.*/export async function placeFloating(element: HTMLElement, anchor: ReferenceElement, { placement, offset: gap, shiftAcross, capHeight, hideWithAnchor, arrow: pointer }: FloatingPlacement) {const { x, y, placement: placed, middlewareData } = await computePosition(anchor, element, {diff --git a/apps/client/src/widgets/react/menu_context.ts b/apps/client/src/widgets/react/menu_context.tsindex 6c888bc756..12d3316029 100644--- a/apps/client/src/widgets/react/menu_context.ts+++ b/apps/client/src/widgets/react/menu_context.ts@@ -56,8 +56,8 @@ export interface MenuContextValue {/** Whether the keys moved the menu since the pointer last did. */keyboardDriven: boolean;/**- * Whether the submenus of each level's rows open towards the start, the top level's first. The- * rows show it as `.dropstart`, which turns their arrow that way.+ * Whether the submenus of each level's rows open towards the start, indexed by level. The rows+ * of a level that does carry `.dropstart`, which points their arrow that way.*/dropStart: boolean[];/** Records the side the submenus of `level`'s rows open on. */@@ -83,9 +83,9 @@ export function useMenu() {}/**- * Whether the submenus of a level's rows open towards the start, from where the level's menu or- * layer stands. They keep to `preferStart`, the side the level itself opened towards, unless that- * side has less room than the level is wide and the other side has more.+ * Whether the submenus of a level's rows open towards the start, given `frame`, the level's menu+ * or layer. They open towards the side `preferStart` names, which is where the level itself opened,+ * unless that side has less room than `frame` is wide and the other side has more.*/export function shouldDropStart(frame: Pick<DOMRect, "left" | "right" | "width">, viewportWidth: number, rtl: boolean, preferStart: boolean) {const roomAtEnd = rtl ? frame.left : viewportWidth - frame.right;@@ -94,7 +94,7 @@ export function shouldDropStart(frame: Pick<DOMRect, "left" | "right" | "width">return preferred < frame.width && other > preferred ? !preferStart : preferStart;}-/** Whether the page reads right to left, so a menu's end side is its left. */+/** Whether the page is right to left, which makes a menu's end side its left. */export function isRightToLeft() {return handleRightToLeftPlacement("right") !== "right";}diff --git a/packages/commons/src/lib/script_api_preact.ts b/packages/commons/src/lib/script_api_preact.tsindex 502ead3963..9ec01f614e 100644--- a/packages/commons/src/lib/script_api_preact.ts+++ b/packages/commons/src/lib/script_api_preact.ts@@ -242,7 +242,10 @@ interface FormDropdownSubmenuProps {children?: ComponentChildren;onDropdownToggleClicked?: () => void;}-/** A row that opens its children as a submenu. Outside a `Dropdown` menu, its title heads them. */+/**+ * A row that opens its children as a submenu. Outside a `Dropdown` menu, its title is shown as a+ * header above them.+ */export declare const FormDropdownSubmenu: FunctionComponent<FormDropdownSubmenuProps>;interface FormRadioGroupProps {