@gtkx/testing 1.0.0-rc.3 → 1.0.0-rc.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/testing",
-  "version": "1.0.0-rc.3",
+  "version": "1.0.0-rc.4",
   "description": "Testing Library-style queries, user events, and screenshots for GTK4 widget trees rendered by GTKX",
   "keywords": [
     "gtkx",
@@ -44,20 +44,20 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@gtkx/runtime": "1.0.0-rc.3",
-    "@gtkx/react": "1.0.0-rc.3",
-    "@gtkx/utils": "1.0.0-rc.3"
+    "@gtkx/react": "1.0.0-rc.4",
+    "@gtkx/runtime": "1.0.0-rc.4",
+    "@gtkx/utils": "1.0.0-rc.4"
   },
   "peerDependencies": {
     "@types/react": "^19.2",
     "react": "^19.2"
   },
   "devDependencies": {
-    "@types/react": "^19.2.17",
+    "@types/react": "^19.2.18",
     "@vitest/expect": "^4.1.10",
     "vitest": "^4.1.10",
-    "@gtkx/config": "1.0.0-rc.3",
-    "@gtkx/vitest": "1.0.0-rc.3"
+    "@gtkx/vitest": "1.0.0-rc.4",
+    "@gtkx/config": "1.0.0-rc.4"
   },
   "scripts": {
     "release": "tsx ../../scripts/release-package.ts"

package/src/act.ts

@@ -4,7 +4,9 @@ declare global {
     var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;
 }
 
+/** Work run inside the act environment, either synchronous or asynchronous. */
 type ActCallback<T> = () => T | PromiseLike<T>;
+/** Runs a callback inside React's act environment and settles with its result once updates flush. */
 type ActImplementation = <T>(callback: ActCallback<T>) => PromiseLike<T>;
 
 const actImplementation: ActImplementation = reactAct;

package/src/build-queries.ts

@@ -39,7 +39,7 @@ const extractWaitForOptions = (args: unknown[]): WaitForOptions => {
     return {};
 };
 
-const extractSuggestOption = (args: unknown[]): boolean | undefined => {
+const extractShouldSuggest = (args: unknown[]): boolean | undefined => {
     const last = args.at(-1);
 
     if (last && typeof last === "object" && !(last instanceof RegExp)) {
@@ -54,12 +54,11 @@ const maybeThrowSuggestion = (options: {
     match: Gtk.Widget;
     queryName: Method;
     variant: Variant;
-    suggest: boolean | undefined;
+    shouldSuggest: boolean | undefined;
 }): void => {
-    const { container, match, queryName, variant, suggest } = options;
-    const shouldSuggest = suggest ?? getConfig().throwSuggestions;
+    const { container, match, queryName, variant, shouldSuggest } = options;
 
-    if (!shouldSuggest) {
+    if (!(shouldSuggest ?? getConfig().throwSuggestions)) {
         return;
     }
 
@@ -141,7 +140,13 @@ const wrapSingleWithSuggestion =
             const match = query(container, ...args);
 
             if (match) {
-                maybeThrowSuggestion({ container, match, queryName, variant, suggest: extractSuggestOption(args) });
+                maybeThrowSuggestion({
+                    container,
+                    match,
+                    queryName,
+                    variant,
+                    shouldSuggest: extractShouldSuggest(args),
+                });
             }
 
             return match;
@@ -159,7 +164,7 @@ const wrapAllWithSuggestion =
                     match: first,
                     queryName,
                     variant,
-                    suggest: extractSuggestOption(args),
+                    shouldSuggest: extractShouldSuggest(args),
                 });
             }
 
@@ -197,7 +202,14 @@ const buildQueries = <Args extends unknown[]>(
 
     const getByWithSuggestion: (container: Container, ...args: Args) => Gtk.Widget = (container, ...args) => {
         const match = getBy(container, ...args);
-        maybeThrowSuggestion({ container, match, queryName, variant: "get", suggest: extractSuggestOption(args) });
+
+        maybeThrowSuggestion({
+            container,
+            match,
+            queryName,
+            variant: "get",
+            shouldSuggest: extractShouldSuggest(args),
+        });
 
         return match;
     };

package/src/config.ts

@@ -6,6 +6,7 @@ import type { Container } from "./traversal.js";
  * checks.
  */
 type Config = {
+    /** Whether a successful query throws instead, naming a better query, when one is available. */
     throwSuggestions: boolean;
 
     /** Builds the error thrown when a query fails, given a message and optional container. */
@@ -34,7 +35,7 @@ const defaultConfig: Config = {
 const currentConfig: Config = { ...defaultConfig };
 
 function defaultGetElementError(message: string): Error {
-    return new GtkxElementError(message);
+    return new ElementError(message);
 }
 
 /**
@@ -55,8 +56,8 @@ const configure = (newConfig: Partial<Config> | ConfigFn): void => {
     Object.assign(currentConfig, updates);
 };
 
-class GtkxElementError extends Error {
-    override name = "GtkxElementError";
+class ElementError extends Error {
+    override name = "ElementError";
 }
 
 export { getConfig, configure, type Config, type ConfigFn };

package/src/errors.ts

@@ -125,7 +125,7 @@ const buildElementError = (container: Container, headLines: string[]): Error =>
 
     const lines = expensiveErrorDiagnostics.isDisabled
         ? headLines
-        : [...headLines, "", prettyWidget(container, { highlight: false })];
+        : [...headLines, "", prettyWidget(container, { shouldHighlight: false })];
 
     return config.getElementError(lines.join("\n"), container);
 };
@@ -160,7 +160,7 @@ const multipleFoundError = (container: Container, descriptor: QueryDescriptor, m
     ];
 
     if (!expensiveErrorDiagnostics.isDisabled) {
-        const renderedMatches = matches.map((widget) => prettyWidget(widget, { highlight: false }));
+        const renderedMatches = matches.map((widget) => prettyWidget(widget, { shouldHighlight: false }));
         headLines.push("", "Here are the matching elements:", "", ...renderedMatches);
     }
 

package/src/matchers.ts

@@ -39,45 +39,89 @@ type TextContentOptions = {
 
 /** The expected value for a style class: an exact class name or a regular expression. */
 type ClassExpectation = string | RegExp;
+/** The outcome of a matcher: whether it passed, and the failure text built on demand. */
 type MatcherResult = { pass: boolean; message: () => string };
+/** The matcher state bound as `this`, supplying the test runner's deep equality check. */
 type MatcherContext = { equals: (actual: unknown, expected: unknown) => boolean };
+/** Compares text read from the received widget; with no expected value, asserts the text is non-empty. */
 type TextMatcher = (received: unknown, expected?: TextExpectation) => MatcherResult;
+/** Asserts a single state of the received widget, taking no expected value. */
 type StateMatcher = (received: unknown) => MatcherResult;
 type TextMatcherContext = { matcherName: string; widget: Gtk.Widget; actual: string | null };
 type ClassArguments = { expected: ClassExpectation[]; isExact: boolean };
 
+/** A text matcher that also takes normalization options for the text it reads. */
 type TextContentMatcher = (
     received: unknown,
     expected?: TextExpectation,
     options?: TextContentOptions,
 ) => MatcherResult;
 
+/** Signatures of the widget assertion matchers, keyed by the name each is registered under. */
 type MatcherImplementations = {
+    /** Asserts the text an editable widget or combo box shows; with no argument, that it is not empty. */
     toHaveDisplayValue: TextMatcher;
+    /** Asserts the widget's own text, or its descendants' when it has none, contains or matches the expectation. */
     toHaveTextContent: TextContentMatcher;
+    /** Asserts the widget's accessible name; with no argument, that it has one. */
     toHaveAccessibleName: TextMatcher;
+    /**
+     * Asserts the joined accessible names of the widget's `described-by` targets, falling back to its
+     * `description` and then to its tooltip.
+     */
     toHaveAccessibleDescription: TextMatcher;
+    /** Asserts the joined accessible names of the widget's `error-message` targets, read only while it is invalid. */
     toHaveAccessibleErrorMessage: TextMatcher;
+    /** Asserts the widget's placeholder text; with no argument, that it has some. */
     toHavePlaceholderText: TextMatcher;
+    /** Asserts the text currently selected in an editable widget. */
     toHaveSelection: TextMatcher;
+    /** Asserts the widget's checked state is checked rather than unchecked or mixed. */
     toBeChecked: StateMatcher;
+    /** Asserts the widget's checked state is mixed. */
     toBePartiallyChecked: StateMatcher;
+    /** Asserts a `Gtk.ToggleButton` is active, and throws for any other widget. */
     toBePressed: StateMatcher;
+    /** Asserts a `Gtk.Expander` or the row behind a `Gtk.TreeExpander` is expanded, and throws for anything else. */
     toBeExpanded: StateMatcher;
+    /**
+     * Asserts a `Gtk.ListBoxRow` or `Gtk.FlowBoxChild` is selected, or that a widget in a selectable role
+     * carries the selected state flag, and throws for anything else.
+     */
     toBeSelected: StateMatcher;
+    /** Asserts the widget is insensitive, or sits inside an insensitive ancestor. */
     toBeDisabled: StateMatcher;
+    /** Asserts the widget and all of its ancestors are sensitive. */
     toBeEnabled: StateMatcher;
+    /** Asserts the widget and its ancestors are all visible, and that none of them is fully transparent. */
     toBeVisible: StateMatcher;
+    /** Asserts the widget's root is a window that is still in the toplevel list. */
     toBeRooted: StateMatcher;
+    /** Asserts the widget has neither a child nor label text. */
     toBeEmpty: StateMatcher;
+    /** Asserts the widget's accessible invalid state is set to anything other than false. */
     toBeInvalid: StateMatcher;
+    /** Asserts the widget's accessible invalid state is unset or false. */
     toBeValid: StateMatcher;
+    /** Asserts the widget's accessible required state. */
     toBeRequired: StateMatcher;
+    /** Asserts the widget holds the platform focus state. */
     toHaveFocus: StateMatcher;
+    /** Asserts a widget's numeric value, or its display value when a string is given. */
     toHaveValue: (received: unknown, expected?: number | string) => MatcherResult;
+    /** Asserts the widget's accessible role. */
     toHaveRole: (received: unknown, expected: Gtk.AccessibleRole) => MatcherResult;
+    /** Asserts the widget is, or is an ancestor of, the given widget. */
     toContainElement: (received: unknown, descendant: Gtk.Widget | null) => MatcherResult;
+    /**
+     * Asserts the widget carries every given style class, each a name, a space-separated list, or a pattern.
+     * Pass `{ exact: true }` last to require exactly that set, which rules out patterns.
+     */
     toHaveClass: (received: unknown, ...args: unknown[]) => MatcherResult;
+    /**
+     * Asserts a GObject property, named as in GObject and looked up by its camel-cased accessor, equals the
+     * expected value. With no expected value, asserts the property is set. GObject values compare by identity.
+     */
     toHaveObjectProperty: (this: MatcherContext, received: unknown, ...args: unknown[]) => MatcherResult;
 };
 

package/src/pretty-widget.ts

@@ -4,6 +4,7 @@ import { formatRole } from "./role-helpers.js";
 import { type Container, roots } from "./traversal.js";
 import { getWidgetNodeText } from "./widget-accessible-properties.js";
 
+/** Produces the value of the `id` attribute printed first on a widget's opening tag. */
 type WidgetIdResolver = (widget: Gtk.Widget) => string;
 
 /**
@@ -14,7 +15,7 @@ type PrettyWidgetOptions = {
     /** Truncates the output once it exceeds this many characters. */
     maxLength?: number;
     /** Whether to apply ANSI color highlighting; defaults to the terminal capabilities. */
-    highlight?: boolean;
+    shouldHighlight?: boolean;
     /** Resolves an `id` attribute to show for each widget. */
     getId?: WidgetIdResolver;
     /** Stops descending past this depth, replacing deeper children with a summary line. */
@@ -76,7 +77,7 @@ const buildAttrs = (widget: Gtk.Widget, getId: WidgetIdResolver | undefined): [s
     return [...idAttrs, ...otherAttrs];
 };
 
-const shouldHighlight = (): boolean => {
+const isHighlightSupported = (): boolean => {
     if (typeof process === "undefined") {
         return false;
     }
@@ -206,8 +207,8 @@ const prettyWidget = (container: Container, options: PrettyWidgetOptions = {}):
         return "";
     }
 
-    const isHighlight = options.highlight ?? shouldHighlight();
-    const colors = createColors(isHighlight);
+    const shouldHighlight = options.shouldHighlight ?? isHighlightSupported();
+    const colors = createColors(shouldHighlight);
     let output = "";
 
     for (const root of roots(container)) {

package/src/queries.ts

@@ -30,6 +30,7 @@ import {
     isWidgetChecked,
 } from "./widget-accessible-properties.js";
 
+/** The built-in queries in their unbound form, each taking the container to search as its first argument. */
 type BuiltinQueries = QueryFamilies<[container: Container]>;
 
 const roleQueries = nameQueryFamily(

package/src/render.tsx

@@ -165,7 +165,7 @@ const render = async <Q extends QueryMap = Record<never, never>>(
     options?: RenderOptions<Q>,
 ): Promise<RenderResult<Q>> => {
     installErrorHandler();
-    applyEnableAnimations(options?.animations === true);
+    applyEnableAnimations(options?.areAnimationsEnabled === true);
     const baseElement: Container = options?.baseElement ?? TOPLEVELS;
     const Wrapper = options?.wrapper;
     const resolved = resolveContainer(options?.container);
@@ -184,7 +184,7 @@ const render = async <Q extends QueryMap = Record<never, never>>(
     const wrap = (node: ReactNode): ReactNode => {
         const wrapped = Wrapper ? <Wrapper>{node}</Wrapper> : node;
 
-        return options?.reactStrictMode ? <StrictMode>{wrapped}</StrictMode> : wrapped;
+        return options?.isReactStrictMode ? <StrictMode>{wrapped}</StrictMode> : wrapped;
     };
 
     await update(wrap(element), root);

package/src/suggestions.ts

@@ -20,10 +20,13 @@ type Method = "Role" | "LabelText" | "PlaceholderText" | "Text" | "DisplayValue"
  * `toString` that renders the full call.
  */
 type Suggestion = {
+    /** The query family, such as `Role`. */
     queryName: Method;
     /** The full query function name, such as `getByRole`. */
     queryMethod: string;
+    /** The variant the suggestion was asked for, which prefixes `Suggestion.queryMethod`. */
     variant: Variant;
+    /** Renders the suggested call with its arguments, such as `getByRole(Gtk.AccessibleRole.BUTTON)`. */
     toString: () => string;
 };
 

package/src/traversal.ts

@@ -1,5 +1,9 @@
 import * as Gtk from "@gtkx/gi/gtk";
 
+/**
+ * A scope that resolves to a single root widget: the widget itself, the widget a controller or
+ * layout manager is attached to, or a list item's or header's child.
+ */
 type QueryContainer = Gtk.Widget | Gtk.EventController | Gtk.LayoutManager | Gtk.ListItem | Gtk.ListHeader;
 /**
  * A scope that queries and traversal can run against: a widget, an event
@@ -8,6 +12,7 @@ type QueryContainer = Gtk.Widget | Gtk.EventController | Gtk.LayoutManager | Gtk
  */
 type Container = QueryContainer | Gtk.Application | typeof TOPLEVELS;
 
+/** Container sentinel that widens a query to every toplevel window currently open. */
 const TOPLEVELS: unique symbol = Symbol("gtkx.toplevels");
 
 const isApplication = (container: Container): container is Gtk.Application => container instanceof Gtk.Application;

package/src/types.ts

@@ -59,7 +59,9 @@ type MatcherOptions<T extends Gtk.Widget = Gtk.Widget> = {
 type ByRoleValue = {
     /** The current value. */
     now?: number | undefined;
+    /** The lower bound of the value's range. */
     min?: number | undefined;
+    /** The upper bound of the value's range. */
     max?: number | undefined;
     /** Matcher for the value's textual representation. */
     text?: Matcher | undefined;
@@ -67,15 +69,23 @@ type ByRoleValue = {
 
 /** Options for role queries: an accessible name matcher plus accessible state and value constraints. */
 type ByRoleOptions<T extends Gtk.Widget = Gtk.Widget> = MatcherOptions<T> & {
+    /** Matcher for the widget's accessible name. */
     name?: Matcher | undefined;
+    /** Required checked state; a mixed check button reads as neither, so it matches neither value. */
     checked?: boolean | undefined;
+    /** Required active state of a toggle button; any other widget matches neither value. */
     pressed?: boolean | undefined;
+    /** Required selected state of a row, list item, grid cell, option or tree item. */
     selected?: boolean | undefined;
+    /** Required expanded state of an expander or tree expander. */
     expanded?: boolean | undefined;
     /** Heading or hierarchy level. */
     level?: number | undefined;
+    /** Required busy state, which an unset state satisfies as false. */
     busy?: boolean | undefined;
+    /** Matcher for the widget's own accessible description, ignoring its `described-by` targets. */
     description?: Matcher | undefined;
+    /** Constraints on the widget's range value, each checked only when given. */
     value?: ByRoleValue | undefined;
     /** When true, include widgets excluded from the accessibility tree. */
     hidden?: boolean | undefined;
@@ -86,26 +96,39 @@ type WrapperComponent = ComponentType<{
     children: ReactNode;
 }>;
 
+/** A custom query, taking the scope to search as its first argument and its matcher arguments after it. */
 type Query = (container: Container, ...args: never[]) => unknown;
+/** Custom queries keyed by the name each is bound under. */
 type QueryMap = Record<string, Query>;
 
+/** A query with its container argument already applied. */
 type BoundQuery<Q extends Query> = Q extends (container: Container, ...args: infer A) => infer R
     ? (...args: A) => R
     : never;
 
+/** Custom queries with their container argument already applied, keyed as they were passed in. */
 type BoundCustomQueries<Q extends QueryMap> = { [K in keyof Q]: BoundQuery<Q[K]> };
 
+/** What each variant of a query family yields for the widget type it matched. */
 type QueryFamilyReturns<T extends Gtk.Widget> = {
+    /** The single match, or null when nothing matched; throws when more than one matched. */
     queryBy: T | null;
+    /** Every match, empty when nothing matched. */
     queryAllBy: T[];
+    /** The single match; throws when nothing or more than one matched. */
     getBy: T;
+    /** Every match; throws when nothing matched. */
     getAllBy: T[];
+    /** The single match, retried until it appears or the timeout elapses. */
     findBy: Promise<T>;
+    /** Every match, retried until at least one appears or the timeout elapses. */
     findAllBy: Promise<T[]>;
 };
 
+/** What a query family matches against, which fixes the arguments it takes. */
 type QueryKind = "role" | "text" | "name" | "value";
 
+/** The arguments a query of the given kind takes after the family's leading ones. */
 type QueryArgs<Kind extends QueryKind, T extends Gtk.Widget> = Kind extends "role"
     ? [role: Gtk.AccessibleRole, options?: ByRoleOptions<T>]
     : Kind extends "name"
@@ -115,9 +138,8 @@ type QueryArgs<Kind extends QueryKind, T extends Gtk.Widget> = Kind extends "rol
             : [text: Matcher, options?: MatcherOptions<T>];
 
 /**
- * One query family (`queryBy`, `getBy`, `findBy` and their `All` variants) for a single suffix.
- * Each member takes an explicit widget type, as Testing Library's queries do, and also infers it
- * from an `as` option.
+ * One family's query variants, each named for its variant followed by `Suffix` and taking `Head`
+ * ahead of the family's own arguments.
  */
 type QueryFamily<Suffix extends string, Kind extends QueryKind, Head extends unknown[]> = {
     [K in keyof QueryFamilyReturns<Gtk.Widget> as `${K & string}${Suffix}`]: <T extends Gtk.Widget = Gtk.Widget>(
@@ -125,6 +147,10 @@ type QueryFamily<Suffix extends string, Kind extends QueryKind, Head extends unk
     ) => QueryFamilyReturns<T>[K];
 };
 
+/**
+ * Every built-in query, spanning the Role, LabelText, Text, Name, PlaceholderText, and DisplayValue
+ * families, with `Head` prepended to each signature.
+ */
 type QueryFamilies<Head extends unknown[]> = QueryFamily<"Role", "role", Head> &
     QueryFamily<"LabelText", "text", Head> &
     QueryFamily<"Text", "text", Head> &
@@ -137,14 +163,16 @@ type QueryFamilies<Head extends unknown[]> = QueryFamily<"Role", "role", Head> &
  * React behavior toggles, error callbacks, and custom queries to bind.
  */
 type RenderOptions<Q extends QueryMap = Record<never, never>> = {
+    /** Widget or root element to mount into; an undecorated harness window is created when omitted. */
     container?: Gtk.Widget | RootElement | undefined;
     /** Root of the subtree that bound queries search. */
     baseElement?: Container | undefined;
+    /** Component wrapped around the rendered element, such as a context provider. */
     wrapper?: WrapperComponent | undefined;
     /** Render inside React StrictMode. */
-    reactStrictMode?: boolean | undefined;
+    isReactStrictMode?: boolean | undefined;
     /** Enable widget animations during the test. */
-    animations?: boolean | undefined;
+    areAnimationsEnabled?: boolean | undefined;
     /** Called for errors caught by React error boundaries. */
     onCaughtError?: ((error: unknown, errorInfo: ErrorInfo) => void) | undefined;
     /** Called for errors React recovered from automatically. */
@@ -153,17 +181,25 @@ type RenderOptions<Q extends QueryMap = Record<never, never>> = {
     queries?: Q | undefined;
 };
 
+/** Console helpers bundled with the bound queries on {@link screen} and on a render result. */
 type DebugUtilities = {
+    /** Prints the widget tree of the given containers, or of the whole scope, to the console. */
     debug: (element?: Container | Container[], options?: PrettyWidgetOptions) => void;
+    /** Prints the accessible roles found in the scope, with the widgets carrying each one. */
     logRoles: () => void;
+    /** Captures a window, writes the image to a temporary file, and logs its path. */
     screenshot: (selector?: WindowSelector, options?: ScreenshotOptions) => Promise<ScreenshotResult>;
 };
 
 /** A captured screenshot: base64-encoded image data, its MIME type, and pixel dimensions. */
 type ScreenshotResult = {
+    /** Base64-encoded image bytes. */
     data: string;
+    /** MIME type of the encoded image, always `image/png`. */
     mimeType: string;
+    /** Image width in pixels, after the scale factor is applied. */
     width: number;
+    /** Image height in pixels, after the scale factor is applied. */
     height: number;
 };
 
@@ -200,7 +236,9 @@ type RenderHookOptions<Props> = {
 type RenderHookResult<Result, Props> = {
     /** Holds the most recent value returned by the hook under `current`. */
     result: { current: Result };
+    /** Re-invokes the hook, keeping the previous props when none are given. */
     rerender: (newProps?: Props) => Promise<void>;
+    /** Unmounts the component that calls the hook. */
     unmount: () => Promise<void>;
 };
 

package/src/user-event/adjustment.ts

@@ -3,7 +3,9 @@ import { wrapEvent } from "./event-wrapper.js";
 
 /** A scroll distance in pixels along each axis. */
 type ScrollDelta = {
+    /** Distance added to the horizontal adjustment. */
     x?: number;
+    /** Distance added to the vertical adjustment. */
     y?: number;
 };
 
@@ -12,6 +14,11 @@ type ScrollAdjustments = {
     vertical: Gtk.Adjustment | null;
 };
 
+/**
+ * Emits a jump `change-value` so a Gtk.Range moves to the given value.
+ *
+ * @throws When the widget is not a Gtk.Range.
+ */
 const slide = (widget: Gtk.Widget, value: number): Promise<void> =>
     wrapEvent(widget, () => {
         if (!(widget instanceof Gtk.Range)) {
@@ -45,6 +52,12 @@ const applyScrollDelta = (adjustment: Gtk.Adjustment | null, delta: number): voi
     adjustment.setValue(adjustment.getValue() + delta);
 };
 
+/**
+ * Adds the delta to the adjustments of the widget itself, or of its nearest Gtk.ScrolledWindow or
+ * Gtk.Scrollable ancestor.
+ *
+ * @throws When neither the widget nor any of its ancestors is scrollable.
+ */
 const scroll = (widget: Gtk.Widget, delta: ScrollDelta): Promise<void> =>
     wrapEvent(widget, () => {
         const adjustments = resolveScrollAdjustments(widget);

package/src/user-event/click.ts

@@ -67,6 +67,11 @@ const tryActivate = async (widget: Gtk.Widget): Promise<boolean> => {
     return isActivated;
 };
 
+/**
+ * Presses and releases a Gtk.Button, flips a Gtk.Switch, and otherwise activates the widget,
+ * falling back to a click gesture on the nearest Gtk.Button or click-gesture ancestor when
+ * activation does nothing. A widget with the label role is never activated.
+ */
 const click = async (widget: Gtk.Widget): Promise<void> => {
     if (widget instanceof Gtk.Button) {
         await emitClickSequence(widget, widget, 1);
@@ -93,7 +98,9 @@ const click = async (widget: Gtk.Widget): Promise<void> => {
     }
 };
 
+/** Emits a two-press click gesture at the widget's center, adding a Gtk.GestureClick when it has none. */
 const dblClick = (widget: Gtk.Widget): Promise<void> => emitClickSequence(widget, widget, 2);
+/** Emits a three-press click gesture at the widget's center, adding a Gtk.GestureClick when it has none. */
 const tripleClick = (widget: Gtk.Widget): Promise<void> => emitClickSequence(widget, widget, 3);
 
 export { emitPress, emitRelease, click, dblClick, tripleClick };

package/src/user-event/controller.ts

@@ -1,7 +1,15 @@
 import type * as Gtk from "@gtkx/gi/gtk";
 
+/** An event controller class that can be constructed without arguments, such as `Gtk.GestureClick`. */
 type ControllerConstructor<T extends Gtk.EventController> = new () => T;
 
+/**
+ * Returns every controller of the given type attached to a widget, in the order GTK4 reports them.
+ *
+ * @param widget The widget whose controllers are inspected.
+ * @param controllerType The controller class to match.
+ * @returns The matching controllers, or an empty array when the widget has none.
+ */
 const queryAllControllers = <T extends Gtk.EventController>(
     widget: Gtk.Widget,
     controllerType: ControllerConstructor<T>,
@@ -21,11 +29,25 @@ const queryAllControllers = <T extends Gtk.EventController>(
     return matches;
 };
 
+/**
+ * Returns the first controller of the given type attached to a widget.
+ *
+ * @param widget The widget whose controllers are inspected.
+ * @param controllerType The controller class to match.
+ * @returns The first matching controller, or null when the widget has none.
+ */
 const queryController = <T extends Gtk.EventController>(
     widget: Gtk.Widget,
     controllerType: ControllerConstructor<T>,
 ): T | null => queryAllControllers(widget, controllerType)[0] ?? null;
 
+/**
+ * Returns every controller of the given type attached to a widget.
+ *
+ * @param widget The widget whose controllers are inspected.
+ * @param controllerType The controller class to match.
+ * @throws When the widget has no controller of that type.
+ */
 const getAllControllers = <T extends Gtk.EventController>(
     widget: Gtk.Widget,
     controllerType: ControllerConstructor<T>,
@@ -39,6 +61,13 @@ const getAllControllers = <T extends Gtk.EventController>(
     return controllers;
 };
 
+/**
+ * Returns the first controller of the given type attached to a widget.
+ *
+ * @param widget The widget whose controllers are inspected.
+ * @param controllerType The controller class to match.
+ * @throws When the widget has no controller of that type.
+ */
 const getController = <T extends Gtk.EventController>(
     widget: Gtk.Widget,
     controllerType: ControllerConstructor<T>,