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

package/src/types.ts

@@ -13,6 +13,11 @@ type MatcherFunction = (content: string, widget: Gtk.Widget) => boolean;
 type Matcher = string | number | RegExp | MatcherFunction;
 /** Normalizes a widget's text before it is compared against a matcher. */
 type NormalizerFn = (text: string) => string;
+/**
+ * A widget class usable as a query's `as` constraint, such as `Gtk.Button`. Abstract classes and
+ * generated GInterface pseudo-classes are accepted.
+ */
+type WidgetType<T extends Gtk.Widget = Gtk.Widget> = abstract new (...args: never[]) => T;
 
 /** Options controlling the default text normalizer. */
 type NormalizerOptions = {
@@ -35,7 +40,7 @@ type WaitForOptions = {
 };
 
 /** Options controlling text matching and, for asynchronous queries, polling behavior. */
-type MatcherOptions = {
+type MatcherOptions<T extends Gtk.Widget = Gtk.Widget> = {
     /** When true (the default), require an exact match; when false, match case-insensitively as a substring. */
     exact?: boolean | undefined;
     /** Custom normalizer replacing the default; cannot be combined with `trim` or `collapseWhitespace`. */
@@ -46,29 +51,41 @@ type MatcherOptions = {
     collapseWhitespace?: boolean | undefined;
     /** Whether to include a suggested better query in error messages. */
     suggest?: boolean | undefined;
+    /** Restricts matches to instances of this widget class, and narrows the query's return type to it. */
+    as?: WidgetType<T> | undefined;
 } & WaitForOptions;
 
 /** Constraints on a widget's numeric range value used by role queries. */
 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;
 };
 
 /** Options for role queries: an accessible name matcher plus accessible state and value constraints. */
-type ByRoleOptions = MatcherOptions & {
+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;
@@ -79,28 +96,83 @@ 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"
+        ? [name: Matcher, options?: MatcherOptions<T>]
+        : Kind extends "value"
+            ? [value: Matcher, options?: MatcherOptions<T>]
+            : [text: Matcher, options?: MatcherOptions<T>];
+
+/**
+ * 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>(
+        ...args: [...Head, ...QueryArgs<Kind, T>]
+    ) => 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> &
+    QueryFamily<"Name", "name", Head> &
+    QueryFamily<"PlaceholderText", "text", Head> &
+    QueryFamily<"DisplayValue", "value", Head>;
+
 /**
  * Options for {@link render}: the container and base element to mount into, an optional wrapper,
  * 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. */
@@ -109,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;
 };
 
@@ -156,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>;
 };
 
@@ -169,9 +251,11 @@ export {
     type MatcherOptions,
     type ByRoleValue,
     type ByRoleOptions,
+    type WidgetType,
     type WrapperComponent,
     type QueryMap,
     type BoundCustomQueries,
+    type QueryFamilies,
     type RenderOptions,
     type DebugUtilities,
     type ScreenshotResult,

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,26 @@ 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>,
+): T => {
+    const [controller] = getAllControllers(widget, controllerType);
+
+    if (controller === undefined) {
+        throw new Error(`No ${controllerType.name} controller is attached to the widget`);
+    }
+
+    return controller;
+};
+
 const getOrCreateControllers = <T extends Gtk.EventController>(
     widget: Gtk.Widget,
     controllerType: ControllerConstructor<T>,
@@ -55,4 +97,11 @@ const getOrCreateControllers = <T extends Gtk.EventController>(
     return [controller];
 };
 
-export { queryAllControllers, queryController, getAllControllers, getOrCreateControllers, type ControllerConstructor };
+export {
+    queryAllControllers,
+    queryController,
+    getAllControllers,
+    getController,
+    getOrCreateControllers,
+    type ControllerConstructor,
+};

package/src/user-event/gesture.ts

@@ -9,13 +9,17 @@ type DropContent = string | number | boolean | GObject.Value;
 
 /** Options for a drop: the drop coordinates within the target. */
 type DropOptions = {
+    /** Horizontal drop coordinate within the target, in pixels. */
     x?: number;
+    /** Vertical drop coordinate within the target, in pixels. */
     y?: number;
 };
 
 /** A drag offset relative to the drag start point. */
 type DragOffset = {
+    /** Horizontal distance from the drag start point, in pixels. */
     x: number;
+    /** Vertical distance from the drag start point, in pixels. */
     y: number;
 };
 
@@ -24,9 +28,13 @@ type DragOffset = {
  * explicit intermediate offsets emitted before the final one.
  */
 type DragOptions = {
+    /** Horizontal coordinate the drag begins at; defaults to 0. */
     startX?: number;
+    /** Vertical coordinate the drag begins at; defaults to 0. */
     startY?: number;
+    /** Number of evenly interpolated drag updates, the last of which is the requested offset; defaults to 2. */
     steps?: number;
+    /** Explicit intermediate offsets emitted before the requested one, used instead of `steps`. */
     offsets?: DragOffset[];
 };
 
@@ -37,8 +45,8 @@ type DragInstancePatch = {
 
 type SavedDragState = {
     instance: DragInstancePatch;
-    ownsStartPoint: boolean;
-    ownsOffset: boolean;
+    hasOwnStartPoint: boolean;
+    hasOwnOffset: boolean;
     previousStartPoint: DragInstancePatch["getStartPoint"];
     previousOffset: DragInstancePatch["getOffset"];
 };
@@ -65,32 +73,56 @@ const buildDropValue = (content: DropContent): GObject.Value => {
     });
 };
 
+/** Emits `enter` at the widget's origin on its motion controllers, adding one when it has none. */
 const hover = (widget: Gtk.Widget): Promise<void> =>
     dispatchOnOrCreateControllers(widget, Gtk.EventControllerMotion, (controller) => {
         controller.emit("enter", 0, 0);
     });
 
+/** Emits `leave` on the widget's motion controllers, adding one when it has none. */
 const unhover = (widget: Gtk.Widget): Promise<void> =>
     dispatchOnOrCreateControllers(widget, Gtk.EventControllerMotion, (controller) => {
         controller.emit("leave");
     });
 
+/**
+ * Emits `angle-changed` on the widget's rotate gestures.
+ *
+ * @param angle Current angle, in radians.
+ * @param deltaAngle Difference from the angle the gesture started at; defaults to `angle`.
+ * @throws When the widget has no Gtk.GestureRotate.
+ */
 const rotate = (widget: Gtk.Widget, angle: number, deltaAngle: number = angle): Promise<void> =>
     dispatchOnControllers(widget, Gtk.GestureRotate, (controller) => {
         controller.emit("angle-changed", angle, deltaAngle);
     },
     );
 
+/**
+ * Emits `scale-changed` with the given scale delta on the widget's zoom gestures.
+ *
+ * @throws When the widget has no Gtk.GestureZoom.
+ */
 const zoom = (widget: Gtk.Widget, scale: number): Promise<void> =>
     dispatchOnControllers(widget, Gtk.GestureZoom, (controller) => {
         controller.emit("scale-changed", scale);
     });
 
+/**
+ * Emits `swipe` with the given per-axis velocity, in pixels per second, on the widget's swipe gestures.
+ *
+ * @throws When the widget has no Gtk.GestureSwipe.
+ */
 const swipe = (widget: Gtk.Widget, velocityX: number, velocityY: number): Promise<void> =>
     dispatchOnControllers(widget, Gtk.GestureSwipe, (controller) => {
         controller.emit("swipe", velocityX, velocityY);
     });
 
+/**
+ * Emits `pressed` at the given point in widget coordinates on the widget's long-press gestures.
+ *
+ * @throws When the widget has no Gtk.GestureLongPress.
+ */
 const longPress = (widget: Gtk.Widget, x = 0, y = 0): Promise<void> =>
     dispatchOnControllers(widget, Gtk.GestureLongPress, (controller) => {
         controller.emit("pressed", x, y);
@@ -99,13 +131,13 @@ const longPress = (widget: Gtk.Widget, x = 0, y = 0): Promise<void> =>
 const restoreDragState = (saved: SavedDragState): void => {
     const { instance } = saved;
 
-    if (saved.ownsStartPoint) {
+    if (saved.hasOwnStartPoint) {
         instance.getStartPoint = saved.previousStartPoint;
     } else {
         delete instance.getStartPoint;
     }
 
-    if (saved.ownsOffset) {
+    if (saved.hasOwnOffset) {
         instance.getOffset = saved.previousOffset;
     } else {
         delete instance.getOffset;
@@ -117,8 +149,8 @@ const patchDragState = (controller: Gtk.GestureDrag, start: DragOffset, offset:
 
     const saved: SavedDragState = {
         instance,
-        ownsStartPoint: Object.hasOwn(instance, "getStartPoint"),
-        ownsOffset: Object.hasOwn(instance, "getOffset"),
+        hasOwnStartPoint: Object.hasOwn(instance, "getStartPoint"),
+        hasOwnOffset: Object.hasOwn(instance, "getOffset"),
         previousStartPoint: instance.getStartPoint,
         previousOffset: instance.getOffset,
     };
@@ -177,6 +209,14 @@ const resolveDragUpdates = (dx: number, dy: number, options: DragOptions): DragO
     return updates;
 };
 
+/**
+ * Runs a `drag-begin`, `drag-update`, `drag-end` sequence ending at the offset `dx`, `dy` on the
+ * widget's drag gestures, overriding each gesture's start point and offset for the duration so
+ * handlers read the simulated values back.
+ *
+ * @throws When the widget is a Gtk.Range, whose slider reads pointer coordinates from the display,
+ * or when it has no Gtk.GestureDrag.
+ */
 const drag = async (widget: Gtk.Widget, dx: number, dy: number, options: DragOptions = {}): Promise<void> => {
     if (widget instanceof Gtk.Range) {
         throw new TypeError(
@@ -202,11 +242,22 @@ const emitDrop = (target: Gtk.Widget, content: DropContent, options: DropOptions
     }
 };
 
+/**
+ * Emits `drop` with the given content on every drop target attached to the widget.
+ *
+ * @throws When the widget has no Gtk.DropTarget.
+ */
 const drop = (widget: Gtk.Widget, content: DropContent, options: DropOptions = {}): Promise<void> =>
     wrapEvent(widget, () => {
         emitDrop(widget, content, options);
     });
 
+/**
+ * Emits `drop` with the given content on the target's drop targets, after checking that the source
+ * carries a drag source.
+ *
+ * @throws When the source has no Gtk.DragSource, or the target no Gtk.DropTarget.
+ */
 const dragAndDrop = async (
     source: Gtk.Widget,
     target: Gtk.Widget,

package/src/user-event/index.ts

@@ -13,29 +13,56 @@ import { clear, copy, cut, paste, type } from "./text.js";
  * keyboard, pointer, gestures, selection, and scrolling.
  */
 type UserEvent = {
+    /**
+     * Clicks a button, toggles a switch, and otherwise activates the widget, falling back to a click
+     * gesture on its nearest clickable ancestor when activation does nothing.
+     */
     click: typeof click;
+    /** Emits a two-press click gesture on the widget. */
     dblClick: typeof dblClick;
+    /** Emits a three-press click gesture on the widget. */
     tripleClick: typeof tripleClick;
+    /** Moves focus within the widget's root, forward by default and backward with `isShiftHeld`. */
     tab: typeof tab;
+    /** Focuses an editable widget, applies any initial selection, and inserts the text at the cursor. */
     type: typeof type;
+    /** Empties an editable widget's text. */
     clear: typeof clear;
+    /** Writes an editable widget's current selection to the clipboard. */
     copy: typeof copy;
+    /** Writes an editable widget's current selection to the clipboard and deletes it. */
     cut: typeof cut;
+    /** Inserts the given text, or the clipboard's text, at an editable widget's cursor. */
     paste: typeof paste;
+    /** Selects the items at the given positions in a list view, drop-down, combo box, or list box. */
     selectOptions: typeof selectOptions;
+    /** Deselects the items at the given positions in a list view or list box. */
     deselectOptions: typeof deselectOptions;
+    /** Emits a motion `enter` on the widget, adding a motion controller when it has none. */
     hover: typeof hover;
+    /** Emits a motion `leave` on the widget, adding a motion controller when it has none. */
     unhover: typeof unhover;
+    /** Emits `angle-changed` on the widget's rotate gestures. */
     rotate: typeof rotate;
+    /** Emits `scale-changed` on the widget's zoom gestures. */
     zoom: typeof zoom;
+    /** Emits `swipe` with the given velocity on the widget's swipe gestures. */
     swipe: typeof swipe;
+    /** Emits `pressed` at the given point on the widget's long-press gestures. */
     longPress: typeof longPress;
+    /** Runs a begin, update, and end sequence on the widget's drag gestures, ending at the given offset. */
     drag: typeof drag;
+    /** Emits `drop` with the given content on the widget's drop targets. */
     drop: typeof drop;
+    /** Requires a drag source on the source widget, then emits `drop` with the content on the target's drop targets. */
     dragAndDrop: typeof dragAndDrop;
+    /** Emits a jump `change-value` on a Gtk.Range so it moves to the given value. */
     slide: typeof slide;
+    /** Adds the delta to the adjustments of the widget itself, or of its nearest scrollable ancestor. */
     scroll: typeof scroll;
+    /** Sends a key sequence, dispatching matching shortcuts and tracking held modifiers across calls. */
     keyboard: (widget: Gtk.Widget, input: string) => Promise<void>;
+    /** Applies a pointer token, tracking whether the left button is held across calls. */
     pointer: (widget: Gtk.Widget, input: PointerInput) => Promise<void>;
 };
 

package/src/user-event/keyboard.ts

@@ -6,12 +6,13 @@ import { fireEvent } from "../fire-event.js";
 import { getOrCreateControllers } from "./controller.js";
 import { wrapEvent } from "./event-wrapper.js";
 
-/** Options for {@link tab}: when `shift` is set, move focus backward instead of forward. */
+/** Options for `userEvent.tab`. */
 type TabOptions = {
-    shift?: boolean;
+    /** Move focus backward instead of forward. */
+    isShiftHeld?: boolean;
 };
 
-type KeyAction = { keyval: number; press: boolean };
+type KeyAction = { keyval: number; isPress: boolean };
 type ParseStep = { actions: KeyAction[]; next: number };
 
 const KEY_MAP: Record<string, number> = {
@@ -58,9 +59,10 @@ const MODIFIER_KEYVAL_TO_MASK: Record<number, number> = {
     [Gdk.KEY_Meta_R]: Gdk.ModifierType.META_MASK,
 };
 
+/** Moves focus within the widget's root, forward by default and backward when `isShiftHeld` is set. */
 const tab = (widget: Gtk.Widget, options?: TabOptions): Promise<void> =>
     wrapEvent(widget, () => {
-        const direction = options?.shift ? Gtk.DirectionType.TAB_BACKWARD : Gtk.DirectionType.TAB_FORWARD;
+        const direction = options?.isShiftHeld ? Gtk.DirectionType.TAB_BACKWARD : Gtk.DirectionType.TAB_FORWARD;
         const root = widget.getRoot();
 
         if (root) {
@@ -68,7 +70,7 @@ const tab = (widget: Gtk.Widget, options?: TabOptions): Promise<void> =>
         }
     });
 
-const parseKeyToken = (token: string): { keyval: number; press: boolean; release: boolean } => {
+const parseKeyToken = (token: string): { keyval: number; isPress: boolean; isRelease: boolean } => {
     let keyName = token;
     let isPress = true;
     let isRelease = true;
@@ -87,7 +89,7 @@ const parseKeyToken = (token: string): { keyval: number; press: boolean; release
         throw new Error(`Unknown key: {${keyName}}`);
     }
 
-    return { keyval, press: isPress, release: isRelease };
+    return { keyval, isPress, isRelease };
 };
 
 const parseCharAt = (input: string, i: number): ParseStep => {
@@ -95,8 +97,8 @@ const parseCharAt = (input: string, i: number): ParseStep => {
 
     return {
         actions: [
-            { keyval, press: true },
-            { keyval, press: false },
+            { keyval, isPress: true },
+            { keyval, isPress: false },
         ],
         next: i + 1,
     };
@@ -109,15 +111,15 @@ const parseBraceAt = (input: string, i: number): ParseStep | null => {
         return null;
     }
 
-    const { keyval, press, release } = parseKeyToken(input.slice(i + 1, endBrace));
+    const { keyval, isPress, isRelease } = parseKeyToken(input.slice(i + 1, endBrace));
     const actions: KeyAction[] = [];
 
-    if (press) {
-        actions.push({ keyval, press: true });
+    if (isPress) {
+        actions.push({ keyval, isPress: true });
     }
 
-    if (release) {
-        actions.push({ keyval, press: false });
+    if (isRelease) {
+        actions.push({ keyval, isPress: false });
     }
 
     return { actions, next: endBrace + 1 };
@@ -151,7 +153,7 @@ const updateModifierState = (state: UserEventState, action: KeyAction): void =>
         return;
     }
 
-    if (action.press) {
+    if (action.isPress) {
         state.modifierState |= mask;
     } else {
         state.modifierState &= ~mask;
@@ -267,13 +269,13 @@ const applyKeyAction = async (
     action: KeyAction,
 ): Promise<void> => {
     updateModifierState(state, action);
-    const signalName = action.press ? "key-pressed" : "key-released";
+    const signalName = action.isPress ? "key-pressed" : "key-released";
 
     for (const controller of controllers) {
         controller.emit(signalName, action.keyval, 0, state.modifierState);
     }
 
-    if (action.press) {
+    if (action.isPress) {
         await handleKeyPress(widget, action.keyval, state.modifierState);
     }
 };