@gtkx/testing 1.0.0-rc.3 → 1.0.0

package/src/user-event/click.ts

@@ -1,8 +1,29 @@
+import * as Gdk from "@gtkx/gi/gdk";
 import * as Gtk from "@gtkx/gi/gtk";
-import { getOrCreateControllers, queryController } from "./controller.js";
+import { hasSignalListener } from "@gtkx/runtime/internal";
+import { callBooleanGetter, getCallableMethod, hasWidgetMethod } from "../widget-getters.js";
+import { queryAllControllers } from "./controller.js";
 import { wrapEvent } from "./event-wrapper.js";
+import { hasIndexedChildren, selectContainerChild, SELECTED_PROBE, unselectOtherChildren } from "./indexed-children.js";
+import { isClickTransparent, type NativeClick, nativeClickFor } from "./native-click.js";
 
-const getPressPoint = (widget: Gtk.Widget): { x: number; y: number } => {
+type PressPoint = { x: number; y: number };
+type ClickPhase = "pressed" | "released";
+type ClickSite = { gestures: Gtk.GestureClick[]; point: PressPoint };
+type ClickScope = { isClicked: boolean; isInternalAllowed: boolean };
+
+type ClickTarget = {
+    widget: Gtk.Widget;
+    container: Gtk.Widget | null;
+    gestures: Gtk.GestureClick[];
+    isClaiming: boolean;
+    native: NativeClick | null;
+};
+
+const CLICK_SIGNALS = ["pressed", "released"];
+const PRIMARY_BUTTONS: Set<number> = new Set([0, Gdk.BUTTON_PRIMARY]);
+
+const getCenterPoint = (widget: Gtk.Widget): PressPoint => {
     const width = widget.getWidth();
     const height = widget.getHeight();
 
@@ -13,87 +34,268 @@ const getPressPoint = (widget: Gtk.Widget): { x: number; y: number } => {
     return { x: 0, y: 0 };
 };
 
-const emitGesture = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number, signal: string): void => {
-    const { x, y } = getPressPoint(widget);
+const getClickPoint = (clicked: Gtk.Widget, carrier: Gtk.Widget): PressPoint => {
+    if (clicked === carrier) {
+        return getCenterPoint(clicked);
+    }
+
+    const [isComputed, bounds] = clicked.computeBounds(carrier);
 
+    if (!isComputed) {
+        return getCenterPoint(carrier);
+    }
+
+    return { x: bounds.getX() + bounds.getWidth() / 2, y: bounds.getY() + bounds.getHeight() / 2 };
+};
+
+const emitGesture = (point: PressPoint, controllers: Gtk.GestureClick[], nPress: number, signal: string): void => {
     for (const controller of controllers) {
-        controller.emit(signal, nPress, x, y);
+        controller.emit(signal, nPress, point.x, point.y);
     }
 };
 
-const emitPress = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number): void => {
-    emitGesture(widget, controllers, nPress, "pressed");
+const emitClickPhase = (
+    widget: Gtk.Widget,
+    controllers: Gtk.GestureClick[],
+    nPress: number,
+    phase: ClickPhase,
+): void => {
+    emitGesture(getCenterPoint(widget), controllers, nPress, phase);
 };
 
-const emitRelease = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number): void => {
-    emitGesture(widget, controllers, nPress, "released");
+const emitSitePhase = (sites: ClickSite[], nPress: number, phase: ClickPhase): void => {
+    for (const site of sites) {
+        emitGesture(site.point, site.gestures, nPress, phase);
+    }
 };
 
-const emitClickSequence = (widget: Gtk.Widget, target: Gtk.Widget, nPress: number): Promise<void> =>
-    wrapEvent(widget, () => {
-        const controllers = getOrCreateControllers(target, Gtk.GestureClick);
+const emitClickSequence = (sites: ClickSite[], nPress: number): void => {
+    for (let i = 1; i <= nPress; i++) {
+        emitSitePhase(sites, i, "pressed");
+        emitSitePhase(sites, i, "released");
+    }
+};
 
-        for (let i = 1; i <= nPress; i++) {
-            emitPress(target, controllers, i);
-            emitRelease(target, controllers, i);
-        }
-    });
+const containerFor = (widget: Gtk.Widget): Gtk.Widget | null => {
+    const parent = widget.getParent();
 
-const findClickableAncestor = (widget: Gtk.Widget): Gtk.Widget | null => {
-    let current = widget.getParent();
+    return parent !== null && hasWidgetMethod(widget, SELECTED_PROBE) && hasIndexedChildren(parent) ? parent : null;
+};
 
-    while (current) {
-        if (current instanceof Gtk.Button || queryController(current, Gtk.GestureClick) !== null) {
-            return current;
-        }
+const hasClickHandlers = (gesture: Gtk.GestureClick): boolean => hasSignalListener(gesture, CLICK_SIGNALS);
+const isInternalGesture = (gesture: Gtk.GestureClick): boolean => !hasSignalListener(gesture);
+const isPrimaryGesture = (gesture: Gtk.GestureClick): boolean => PRIMARY_BUTTONS.has(gesture.getButton());
 
-        current = current.getParent();
+const clickGestures = (widget: Gtk.Widget): Gtk.GestureClick[] =>
+    queryAllControllers(widget, Gtk.GestureClick).filter((gesture) => isPrimaryGesture(gesture));
+
+const getAuthoredClickGestures = (widget: Gtk.Widget): Gtk.GestureClick[] =>
+    clickGestures(widget).filter((gesture) => hasClickHandlers(gesture));
+
+const isClaimingTarget = (widget: Gtk.Widget): boolean =>
+    widget instanceof Gtk.Button || containerFor(widget) !== null;
+
+const gestureTargetFor = (widget: Gtk.Widget, isInternalAllowed: boolean): ClickTarget | null => {
+    const gestures = clickGestures(widget);
+
+    if (isClaimingTarget(widget)) {
+        return { widget, container: containerFor(widget), gestures, isClaiming: true, native: null };
+    }
+
+    const authored = gestures.filter((gesture) => hasClickHandlers(gesture));
+
+    if (authored.length > 0) {
+        return { widget, container: null, gestures: authored, isClaiming: false, native: null };
+    }
+
+    if (isInternalAllowed && gestures.some((gesture) => isInternalGesture(gesture))) {
+        return { widget, container: null, gestures, isClaiming: true, native: null };
     }
 
     return null;
 };
 
-const tryActivate = async (widget: Gtk.Widget): Promise<boolean> => {
-    if (widget.getAccessibleRole() === Gtk.AccessibleRole.LABEL) {
-        return false;
+const clickTargetFor = (widget: Gtk.Widget, scope: ClickScope): ClickTarget | null => {
+    if (isClickTransparent(widget)) {
+        return null;
     }
 
-    let isActivated = false;
+    const native = nativeClickFor(widget, scope.isClicked);
 
-    await wrapEvent(widget, () => {
-        isActivated = widget.activate();
-    });
+    if (native !== null) {
+        return { widget, container: null, gestures: getAuthoredClickGestures(widget), isClaiming: true, native };
+    }
 
-    return isActivated;
+    return gestureTargetFor(widget, scope.isInternalAllowed);
 };
 
-const click = async (widget: Gtk.Widget): Promise<void> => {
-    if (widget instanceof Gtk.Button) {
-        await emitClickSequence(widget, widget, 1);
+const isSelfClickTarget = (widget: Gtk.Widget): boolean =>
+    isClickTransparent(widget) || clickTargetFor(widget, { isClicked: true, isInternalAllowed: false }) !== null;
+
+const nextClickWidget = (current: Gtk.Widget, target: ClickTarget | null): Gtk.Widget | null =>
+    target?.isClaiming === true ? null : current.getParent();
+
+const collectClickTargets = (widget: Gtk.Widget): ClickTarget[] => {
+    const targets: ClickTarget[] = [];
+    let current: Gtk.Widget | null = widget;
+
+    while (current !== null) {
+        const isClicked = current === widget;
+        const scope = { isClicked, isInternalAllowed: !isClicked && targets.length === 0 };
+        const target = clickTargetFor(current, scope);
+        const next = nextClickWidget(current, target);
+
+        if (target !== null) {
+            targets.push(target);
+        }
+
+        current = next;
+    }
+
+    return targets;
+};
+
+const targetSites = (clicked: Gtk.Widget, target: ClickTarget): ClickSite[] => {
+    const { container } = target;
+    const site = { gestures: target.gestures, point: getClickPoint(clicked, target.widget) };
+
+    if (container === null) {
+        return [site];
+    }
+
+    return [site, { gestures: getAuthoredClickGestures(container), point: getClickPoint(clicked, container) }];
+};
 
+const isSingleClickActivating = (container: Gtk.Widget): boolean =>
+    callBooleanGetter(container, "getActivateOnSingleClick") ?? true;
+
+const isMultipleSelection = (container: Gtk.Widget): boolean =>
+    getCallableMethod<[], Gtk.SelectionMode>(container, "getSelectionMode")?.() === Gtk.SelectionMode.MULTIPLE;
+
+const isChildSelectable = (child: Gtk.Widget): boolean => callBooleanGetter(child, "getSelectable") ?? true;
+
+const replaceContainerSelection = (container: Gtk.Widget, child: Gtk.Widget): void => {
+    if (!isChildSelectable(child)) {
         return;
     }
 
-    if (widget instanceof Gtk.Switch) {
-        await wrapEvent(widget, () => {
-            widget.setActive(!widget.getActive());
-        });
+    selectContainerChild(container, child);
+
+    if (isMultipleSelection(container)) {
+        unselectOtherChildren(container, child);
+    }
+};
 
+const isActivatedByClick = (container: Gtk.Widget, nPress: number): boolean =>
+    isSingleClickActivating(container) || nPress > 1;
+
+const isSelectionReplacedByClick = (container: Gtk.Widget, nPress: number): boolean =>
+    nPress > 1 || !isSingleClickActivating(container);
+
+const applyContainerOutcome = (target: ClickTarget, nPress: number): void => {
+    const { container, widget } = target;
+
+    if (container === null || widget.getParent() !== container) {
         return;
     }
 
-    if (await tryActivate(widget)) {
+    if (isActivatedByClick(container, nPress)) {
+        widget.activate();
+    }
+
+    if (isSelectionReplacedByClick(container, nPress)) {
+        replaceContainerSelection(container, widget);
+    }
+};
+
+const applyClickOutcome = (target: ClickTarget, nPress: number): void => {
+    if (target.native === null) {
+        applyContainerOutcome(target, nPress);
+
         return;
     }
 
-    const target = findClickableAncestor(widget);
+    target.native(target.widget, nPress);
+};
 
-    if (target) {
-        await emitClickSequence(widget, target, 1);
+const applyClickOutcomes = (targets: ClickTarget[], nPress: number): void => {
+    for (const target of targets) {
+        applyClickOutcome(target, nPress);
     }
 };
 
-const dblClick = (widget: Gtk.Widget): Promise<void> => emitClickSequence(widget, widget, 2);
-const tripleClick = (widget: Gtk.Widget): Promise<void> => emitClickSequence(widget, widget, 3);
+const deliverClick = (widget: Gtk.Widget, nPress: number): Promise<void> =>
+    wrapEvent(widget, () => {
+        const targets = collectClickTargets(widget);
+        const sites = targets.flatMap((target) => targetSites(widget, target));
+        emitClickSequence(sites, nPress);
+        applyClickOutcomes(targets, nPress);
+    });
+
+/* eslint-disable-next-line unicorn/consistent-boolean-name -- the boolean reports whether activation succeeded */
+const tryActivate = async (widget: Gtk.Widget): Promise<boolean> => {
+    if (widget.getAccessibleRole() === Gtk.AccessibleRole.LABEL) {
+        return false;
+    }
+
+    let isActivated = false;
+
+    await wrapEvent(widget, () => {
+        isActivated = widget.activate();
+    });
+
+    return isActivated;
+};
+
+/**
+ * Activates a widget that neither claims the click nor carries a click gesture of its own, and
+ * otherwise delivers a press and release. The press travels outwards from the clicked widget
+ * through every widget carrying a click gesture with a pressed or released handler, the way GTK
+ * hands the same press to each of them, and stops at the first Gtk.Button or indexed child of a
+ * list box or flow box, which claims it. A gesture GTK attached itself takes the press only when no
+ * widget below it handles one, and stops it there, so an expander or a notebook tab nested in a row
+ * opens instead of activating the row. Coordinates are the clicked widget's position in each
+ * carrier, so a gesture the container of an indexed child carries reads the child's position rather
+ * than the container's center. An indexed child that the press reaches is then activated, or
+ * exclusively selected when its container does not activate on a single click. A widget with the
+ * label role is never activated, but does consume the click when it carries a gesture of its own.
+ *
+ * The press also stops at a widget whose click GTK4 implements in C on a gesture it attached
+ * itself, reading a GdkEvent that off-screen synthesis cannot produce. Gestures that widget carries
+ * of its own still take the press and release, the way GTK hands them the press before its own
+ * gesture claims it, and the same outcome is then applied through the public action GTK's own
+ * handler invokes: a list, grid, or column-view row is focused and selected, and activated as well
+ * on a second press or when its view activates on a single click; an expandable tree expander
+ * toggles its expansion, once per press, and only when it is the widget clicked, so a click on its
+ * child falls through to the enclosing row; a column header sorts by its column. Sorting goes
+ * through Gtk.ColumnView.sortByColumn, so the primary sort column and order match what a pointer
+ * produces while previously sorted columns are dropped rather than kept as secondary keys. A
+ * column-view cell and the row that carries the column headers stand in the way of the click rather
+ * than taking it, so a click on either reaches the row or the view behind it.
+ */
+const click = async (widget: Gtk.Widget): Promise<void> => {
+    if (!isSelfClickTarget(widget) && (await tryActivate(widget))) {
+        return;
+    }
+
+    await deliverClick(widget, 1);
+};
+
+/**
+ * Delivers a two-press click gesture the way {@link click} delivers a single press, without trying
+ * activation first. A list box row or flow box child the presses reach, clicked directly or through
+ * a descendant, is activated and exclusively selected, as GTK's double-click path does whether or
+ * not the container activates on a single click. A widget whose click GTK4 implements itself
+ * receives that outcome once per press, so a list, grid, or column-view row is selected and then
+ * activated by the second press, a tree expander ends back where it started, and a column header
+ * sorts and then inverts its order.
+ */
+const dblClick = (widget: Gtk.Widget): Promise<void> => deliverClick(widget, 2);
+/**
+ * Delivers a three-press click gesture the same way a double click is delivered, applying the same
+ * outcome to a list box row or flow box child the presses reach, and applying the outcome GTK4
+ * implements itself once per press to a row, tree expander, or column header.
+ */
+const tripleClick = (widget: Gtk.Widget): Promise<void> => deliverClick(widget, 3);
 
-export { emitPress, emitRelease, click, dblClick, tripleClick };
+export { clickGestures, emitClickPhase, getAuthoredClickGestures, click, dblClick, tripleClick };

package/src/user-event/column-header-click.ts

@@ -0,0 +1,90 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { children } from "../traversal.js";
+import { getWidgetTextContent } from "../widget-accessible-properties.js";
+
+const columnViewFor = (header: Gtk.Widget): Gtk.ColumnView | null => {
+    let current: Gtk.Widget | null = header.getParent();
+
+    while (current !== null) {
+        if (current instanceof Gtk.ColumnView) {
+            return current;
+        }
+
+        current = current.getParent();
+    }
+
+    return null;
+};
+
+const columnsFor = (view: Gtk.ColumnView): Gtk.ColumnViewColumn[] => {
+    const model = view.getColumns();
+    const columns: Gtk.ColumnViewColumn[] = [];
+
+    for (let index = 0; index < model.getNItems(); index++) {
+        const column = model.getItem(index);
+
+        if (column instanceof Gtk.ColumnViewColumn) {
+            columns.push(column);
+        }
+    }
+
+    return columns;
+};
+
+const headerIndexFor = (header: Gtk.Widget): number => {
+    const parent = header.getParent();
+
+    return parent === null ? -1 : [...children(parent)].indexOf(header);
+};
+
+const titledColumnFor = (columns: Gtk.ColumnViewColumn[], title: string | null): Gtk.ColumnViewColumn | null => {
+    const matches = columns.filter((column) => column.getTitle() === title);
+
+    return matches.length === 1 ? matches[0] ?? null : null;
+};
+
+const columnFor = (header: Gtk.Widget, view: Gtk.ColumnView): Gtk.ColumnViewColumn | null => {
+    const columns = columnsFor(view);
+    const picked = columns[headerIndexFor(header)] ?? null;
+    const title = getWidgetTextContent(header);
+
+    if (picked !== null && picked.getTitle() === title) {
+        return picked;
+    }
+
+    return titledColumnFor(columns, title) ?? picked;
+};
+
+const sortableColumnFor = (header: Gtk.Widget, view: Gtk.ColumnView): Gtk.ColumnViewColumn | null => {
+    const column = columnFor(header, view);
+
+    return column !== null && column.getSorter() !== null ? column : null;
+};
+
+const invertedSortDirection = (order: Gtk.SortType): Gtk.SortType =>
+    order === Gtk.SortType.ASCENDING ? Gtk.SortType.DESCENDING : Gtk.SortType.ASCENDING;
+
+const nextSortDirection = (view: Gtk.ColumnView, column: Gtk.ColumnViewColumn): Gtk.SortType => {
+    const sorter = view.getSorter();
+
+    if (!(sorter instanceof Gtk.ColumnViewSorter) || sorter.getPrimarySortColumn() !== column) {
+        return Gtk.SortType.ASCENDING;
+    }
+
+    return invertedSortDirection(sorter.getPrimarySortOrder());
+};
+
+const applyHeaderClick = (header: Gtk.Widget, nPress: number): void => {
+    const view = columnViewFor(header);
+    const column = view === null ? null : sortableColumnFor(header, view);
+
+    if (view === null || column === null) {
+        return;
+    }
+
+    for (let press = 1; press <= nPress; press++) {
+        view.sortByColumn(column, nextSortDirection(view, column));
+    }
+};
+
+export { applyHeaderClick };

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>,

package/src/user-event/event-wrapper.ts

@@ -14,7 +14,9 @@ const canDisplayDeliverActivation = (window: Gtk.Window): boolean =>
     window.getDisplay().getDefaultSeat() !== null;
 
 const findWindowActionabilityFailure = (widget: Gtk.Widget, root: Gtk.Window): string | null => {
-    if (root.getAllocatedWidth() === 0) {
+    const [isComputed, allocation] = root.computeBounds(root);
+
+    if (!isComputed || allocation.getWidth() === 0) {
         return WINDOW_NOT_ALLOCATED;
     }
 

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,