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
import { type ComponentChildren, render } from "preact";
import { act } from "preact/test-utils";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
// The tooltip itself is Bootstrap's; what this component decides is the configuration it hands over,
// so the hook is stubbed and the configuration asserted on.
const mocks = vi.hoisted(() => ({
useStaticTooltip: vi.fn(),
/** Which affordance the component is built for; read once, when its module is first evaluated. */
isMobile: vi.fn(() => false)
}));
vi.mock("./hooks", async (importOriginal) => ({
...(await importOriginal<typeof import("./hooks")>()),
useStaticTooltip: mocks.useStaticTooltip
}));
vi.mock("../../services/utils", async (importOriginal) => ({
...(await importOriginal<typeof import("../../services/utils")>()),
isMobile: mocks.isMobile
}));
// The sheet is the app's own modal, which on a phone every dialog already is; what matters here is
// that the message is handed to one, and only once the icon has been tapped.
vi.mock("./Modal", () => ({
default: ({ children, show, ariaLabel }: { children: ComponentChildren, show: boolean, ariaLabel?: string }) => (
show ? <div className="sheet-stub" role="dialog" aria-label={ariaLabel}>{children}</div> : null
)
}));
// Nothing initializes i18next for the tests, so the wording is stood in for by the key and the
// values interpolated into it — which is what the assertions here are actually about.
vi.mock("../../services/i18n", () => ({
t: (key: string, opts?: Record<string, string>) => `${key}(${opts?.message ?? ""})`
}));
import { Tooltip } from "bootstrap";
import ContextualHelp from "./ContextualHelp";
/** Presses a key on the icon the way a keyboard user would, and answers whether it was handled. */
function press(element: Element | null | undefined, key: string) {
const event = new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true });
act(() => { element?.dispatchEvent(event); });
return event.defaultPrevented;
}
describe("ContextualHelp", () => {
let container: HTMLElement;
beforeEach(() => {
vi.clearAllMocks();
container = document.createElement("div");
document.body.appendChild(container);
});
afterEach(() => {
render(null, container);
container.remove();
});
it("is an info icon explaining itself through the app's tooltip, raised above any dialog", () => {
act(() => render(<ContextualHelp helpMessage="What this figure covers." />, container));
const span = container.querySelector("span");
expect(span?.className).toBe("bx bx-info-circle contextual-help-icon");
// No title of its own: a native tooltip would open somewhere else, in its own styling.
expect(span?.getAttribute("title")).toBeNull();
expect(mocks.useStaticTooltip).toHaveBeenLastCalledWith(expect.anything(), {
title: "What this figure covers.",
placement: "bottom",
customClass: "tooltip-top"
});
});
it("is a control in its own right: reachable, named by its explanation, and worked by key", () => {
const tooltip = { toggle: vi.fn(), hide: vi.fn() };
vi.spyOn(Tooltip, "getInstance").mockReturnValue(tooltip as unknown as Tooltip);
act(() => render(<ContextualHelp helpMessage="What this figure covers." />, container));
const span = container.querySelector("span");
expect(span?.getAttribute("role")).toBe("button");
expect(span?.getAttribute("tabindex")).toBe("0");
// The explanation is the accessible name, so it is there to be read whether or not a
// tooltip happens to be on screen at the time.
expect(span?.getAttribute("aria-label")).toBe("contextual_help.label(What this figure covers.)");
// Both activation keys reveal it, and both are swallowed — Space would otherwise scroll the
// page out from under what is being explained.
expect(press(span, "Enter")).toBe(true);
expect(press(span, " ")).toBe(true);
expect(tooltip.toggle).toHaveBeenCalledTimes(2);
// Dismissed from the keyboard too, without having to tab away. Bootstrap stamps
// `aria-describedby` on the trigger for as long as its tooltip is on screen.
const escaped = vi.fn();
container.addEventListener("keydown", escaped);
span?.setAttribute("aria-describedby", "tooltip-1");
press(span, "Escape");
expect(tooltip.hide).toHaveBeenCalledTimes(1);
// And the key goes no further: these icons sit inside dialogs that close on Escape, and
// putting a tooltip away must not throw away what the dialog was being told.
expect(escaped).not.toHaveBeenCalled();
// With nothing up, the key was never ours — the dialog around it is welcome to it.
span?.removeAttribute("aria-describedby");
press(span, "Escape");
expect(tooltip.hide).toHaveBeenCalledTimes(1);
expect(escaped).toHaveBeenCalledTimes(1);
});
it("hands the tooltip the same configuration until the message itself changes", () => {
act(() => render(<ContextualHelp helpMessage="First." />, container));
const [ , first ] = mocks.useStaticTooltip.mock.calls.at(-1) ?? [];
// A re-render with the same message must not tear the tooltip down and build it again:
// the hook rebuilds on any new configuration object.
act(() => render(<ContextualHelp helpMessage="First." />, container));
expect(mocks.useStaticTooltip.mock.calls.at(-1)?.[1]).toBe(first);
act(() => render(<ContextualHelp helpMessage="Second." />, container));
expect(mocks.useStaticTooltip.mock.calls.at(-1)?.[1]).not.toBe(first);
expect(mocks.useStaticTooltip.mock.calls.at(-1)?.[1]).toMatchObject({ title: "Second." });
});
it("opens the message in a sheet on tap instead, where nothing hovers", async () => {
const OnMobile = await loadOnMobile();
act(() => render(<OnMobile helpMessage="What this figure covers." />, container));
// The same affordance, and no tooltip behind it: a phone would never show one.
const span = container.querySelector("span");
expect(span?.className).toBe("bx bx-info-circle contextual-help-icon");
expect(mocks.useStaticTooltip).not.toHaveBeenCalled();
expect(document.body.querySelector(".sheet-stub")).toBeNull();
act(() => { span?.dispatchEvent(new MouseEvent("click", { bubbles: true })); });
// Out at the body rather than beside the icon: where the icon sits — a chart, a cell, a
// scroll container — is exactly what must not lay the sheet out or clip it.
const sheet = document.body.querySelector(".sheet-stub");
expect(sheet?.textContent).toBe("What this figure covers.");
expect(container.contains(sheet)).toBe(false);
});
it("opens that sheet from the keyboard as well, and says that it opens one", async () => {
const OnMobile = await loadOnMobile();
act(() => render(<OnMobile helpMessage="What this figure covers." />, container));
const span = container.querySelector("span");
expect(span?.getAttribute("role")).toBe("button");
expect(span?.getAttribute("aria-haspopup")).toBe("dialog");
expect(press(span, "Enter")).toBe(true);
const sheet = document.body.querySelector(".sheet-stub");
expect(sheet?.textContent).toBe("What this figure covers.");
// Named, since it carries no title of its own: an unnamed dialog is announced as nothing
// more than "dialog", leaving the reader to work out what has just opened.
expect(sheet?.getAttribute("aria-label")).toBe("contextual_help.sheet_label()");
});
});
/** The component as a phone loads it — the layout is read as its module is evaluated, once. */
async function loadOnMobile() {
mocks.isMobile.mockReturnValue(true);
vi.resetModules();
return (await import("./ContextualHelp")).default;
}