Skip to content

Build your personal knowledge base with Trilium Notes

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.css
index 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.css
index 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.tsx
index 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.tsx
index 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.tsx
index 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, wrappe
const 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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 {