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

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);
     }
 };

package/src/user-event/pointer.ts

@@ -20,21 +20,21 @@ const applyPointerInput = (widget: Gtk.Widget, state: UserEventState, input: Poi
     if (CLICK_INPUTS.has(input)) {
         emitPress(widget, controllers, 1);
         emitRelease(widget, controllers, 1);
-        state.mouseLeftDown = false;
+        state.isMouseLeftDown = false;
 
         return;
     }
 
-    if (PRESS_INPUTS.has(input) && !state.mouseLeftDown) {
+    if (PRESS_INPUTS.has(input) && !state.isMouseLeftDown) {
         emitPress(widget, controllers, 1);
-        state.mouseLeftDown = true;
+        state.isMouseLeftDown = true;
 
         return;
     }
 
-    if (RELEASE_INPUTS.has(input) && state.mouseLeftDown) {
+    if (RELEASE_INPUTS.has(input) && state.isMouseLeftDown) {
         emitRelease(widget, controllers, 1);
-        state.mouseLeftDown = false;
+        state.isMouseLeftDown = false;
     }
 };
 

package/src/user-event/selection.ts

@@ -134,6 +134,14 @@ const runSelectionEvent = (
         byRole(widget, valueArray);
     });
 
+/**
+ * Selects the items at the given positions through a list, grid, or column view's selection model,
+ * by setting the active item of a drop-down or combo box, or by selecting list box rows. An empty
+ * array clears a view's selection.
+ *
+ * @throws When a view has no selection model, when a combo box is given more than one position, or
+ * when the widget is neither a view nor something with the combo box or list role.
+ */
 const selectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
     runSelectionEvent(widget, values, selectInListView, selectByRole);
 
@@ -153,6 +161,13 @@ const deselectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
     applyListBoxRows(widget, valueArray, unselectListBoxRow);
 };
 
+/**
+ * Unselects the items at the given positions in a list, grid, or column view, or the rows at those
+ * indices in a Gtk.ListBox.
+ *
+ * @throws When a view has no selection model, or when the widget is neither one of those views nor
+ * a Gtk.ListBox.
+ */
 const deselectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
     runSelectionEvent(widget, values, deselectInListView, deselectByRole);
 

package/src/user-event/state.ts

@@ -1,8 +1,8 @@
 type UserEventState = {
     modifierState: number;
-    mouseLeftDown: boolean;
+    isMouseLeftDown: boolean;
 };
 
-const createInitialState = (): UserEventState => ({ modifierState: 0, mouseLeftDown: false });
+const createInitialState = (): UserEventState => ({ modifierState: 0, isMouseLeftDown: false });
 
 export { createInitialState, type UserEventState };

package/src/user-event/text.ts

@@ -5,10 +5,10 @@ import { EDITABLE_ROLES, type EditableTarget, getEditableDelegate, isEditable }
 import { formatRoleList } from "../role-helpers.js";
 import { wrapEvent } from "./event-wrapper.js";
 
-/** Options for {@link type}. */
+/** Options for `userEvent.type`. */
 type TypeOptions = {
-    /** Do not focus the widget before typing. */
-    skipClick?: boolean | undefined;
+    /** Focus the widget before typing; defaults to true. */
+    shouldFocus?: boolean | undefined;
     /** Select from this offset before typing, replacing the selected range with the typed text. */
     initialSelectionStart?: number | undefined;
     /** End offset of the initial selection (defaults to the start offset). */
@@ -131,9 +131,15 @@ const runEditableEvent = (
         action(widget);
     });
 
+/**
+ * Focuses the widget unless `shouldFocus` is false, applies any initial selection, and inserts the text
+ * at the cursor.
+ *
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ */
 const type = (widget: Gtk.Widget, text: string, options?: TypeOptions): Promise<void> =>
     runEditableEvent(widget, "Cannot type into element", (editable) => {
-        if (!options?.skipClick) {
+        if (options?.shouldFocus ?? true) {
             editable.grabFocus();
         }
 
@@ -141,22 +147,43 @@ const type = (widget: Gtk.Widget, text: string, options?: TypeOptions): Promise<
         insertEditableText(editable, text);
     });
 
+/**
+ * Replaces an editable widget's text with the empty string.
+ *
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ */
 const clear = (widget: Gtk.Widget): Promise<void> =>
     runEditableEvent(widget, "Cannot clear element", (editable) => {
         setEditableText(editable, "");
     });
 
+/**
+ * Writes an editable widget's selected text to its clipboard, or the empty string when nothing is selected.
+ *
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ */
 const copy = (widget: Gtk.Widget): Promise<void> =>
     runEditableEvent(widget, "Cannot copy", (editable) => {
         writeClipboardText(editable, readSelection(editable));
     });
 
+/**
+ * Writes an editable widget's selected text to its clipboard, then deletes that selection.
+ *
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ */
 const cut = (widget: Gtk.Widget): Promise<void> =>
     runEditableEvent(widget, "Cannot cut", (editable) => {
         writeClipboardText(editable, readSelection(editable));
         deleteSelection(editable);
     });
 
+/**
+ * Inserts the given text at an editable widget's cursor, reading the clipboard instead when no text
+ * is given.
+ *
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ */
 const paste = async (widget: Gtk.Widget, text?: string): Promise<void> => {
     if (!isEditable(widget)) {
         throw new Error(`Cannot paste: ${EDITABLE_REQUIRED}`);

package/src/wait-for.ts

@@ -5,7 +5,9 @@ import { getConfig } from "./config.js";
 import { timeoutError } from "./errors.js";
 
 type PollResult<T> = { status: "resolved"; value: T } | { status: "timedout"; lastError: Error | null };
+/** Widgets watched for removal; null counts as already removed. */
 type RemovalTarget = Gtk.Widget | Gtk.Widget[] | null;
+/** The widgets to watch for removal, or a function re-read on every poll to locate them. */
 type ElementOrCallback = Gtk.Widget | Gtk.Widget[] | (() => RemovalTarget);
 
 const DEFAULT_INTERVAL = 50;

package/src/widget-accessible-properties.ts

@@ -11,7 +11,6 @@ type WidgetValue = {
 };
 
 type ValueTriplet = { now: number | null; min: number | null; max: number | null };
-/** A widget's checked state: on, off, or the mixed state of an inconsistent check button. */
 type CheckedState = "checked" | "unchecked" | "mixed";
 
 const DEFAULT_TEXT_GETTERS = ["getLabel", "getText", "getTitle"] as const;
@@ -158,6 +157,12 @@ const textContentParts = (widget: Gtk.Widget): string[] => {
     return [...getChildren(widget)].flatMap((child) => textContentParts(child));
 };
 
+/**
+ * Returns a widget's own text, or the space-joined text of its descendants when it has none of its
+ * own, or null when neither produces a value.
+ *
+ * @param widget The widget whose subtree is read.
+ */
 const getWidgetTextContent = (widget: Gtk.Widget): string | null => {
     const parts = textContentParts(widget);
 
@@ -370,12 +375,23 @@ const getWidgetLevel = (widget: Gtk.Widget): number | null => {
     return readAccessibleNumber(widget, "accessibleLevel");
 };
 
+/**
+ * Returns the accessible invalid state declared on a widget, or null when it declares none.
+ *
+ * @param widget The widget to read the state from.
+ */
 const getWidgetInvalidState = (widget: Gtk.Widget): Gtk.AccessibleInvalidState | null => {
     const value = readAccessibleNumber(widget, "accessibleInvalid");
 
     return value ?? null;
 };
 
+/**
+ * Returns the widgets a widget's accessible error-message relation points at, or null when it
+ * declares none.
+ *
+ * @param widget The widget to read the relation from.
+ */
 const getWidgetErrorMessage = (widget: Gtk.Widget): Gtk.Widget[] | null =>
     readAccessibleWidgets(widget, "accessibleErrorMessage");