@gtkx/testing 1.6.0 → 2.0.0-beta.10

package/src/traversal.ts

@@ -1,25 +1,41 @@
 import * as Gtk from "@gtkx/gi/gtk";
+import { getClassType, getInstanceType, typeIsA } from "@gtkx/runtime";
 
 /**
  * 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;
+type QueryContainer = Gtk.Accessible | Gtk.EventController | Gtk.LayoutManager | Gtk.ListItem | Gtk.ListHeader;
 /**
  * A scope that queries and traversal can run against: a widget, an event
  * controller, a layout manager, a list item or header, an application, or the
  * sentinel representing all current toplevel windows.
  */
 type Container = QueryContainer | Gtk.Application | typeof TOPLEVELS;
-type WidgetClass<T extends Gtk.Widget> = abstract new (...args: never[]) => T;
+type WidgetClass<T extends object> = abstract new (...args: never[]) => T;
 
 /** Container sentinel that widens a query to every toplevel window currently open. */
 const TOPLEVELS: unique symbol = Symbol("gtkx.toplevels");
+const nativeWidgetTypes: Map<bigint, boolean> = new Map();
 
 const isApplication = (container: Container): container is Gtk.Application => container instanceof Gtk.Application;
 const isAnyWidget = (): boolean => true;
 const isOnScreen = (widget: Gtk.Widget): boolean => widget.getMapped();
 
+const isNativeWidget = (widget: Gtk.Widget): boolean => {
+    const type = getInstanceType(widget);
+    const cached = nativeWidgetTypes.get(type);
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const isNative = typeIsA(type, getClassType(Gtk.Native));
+    nativeWidgetTypes.set(type, isNative);
+
+    return isNative;
+};
+
 const traverseWidgetTree = function* (
     root: Gtk.Widget,
     isIncluded: (widget: Gtk.Widget) => boolean,
@@ -60,7 +76,7 @@ const ancestors = function* (widget: Gtk.Widget): Generator<Gtk.Widget> {
     }
 };
 
-const ancestorFor = <T extends Gtk.Widget>(widget: Gtk.Widget, type: WidgetClass<T>): T | null => {
+const ancestorFor = <T extends object>(widget: Gtk.Widget, type: WidgetClass<T>): T | null => {
     for (const ancestor of ancestors(widget)) {
         if (ancestor instanceof type) {
             return ancestor;
@@ -70,15 +86,23 @@ const ancestorFor = <T extends Gtk.Widget>(widget: Gtk.Widget, type: WidgetClass
     return null;
 };
 
-const relationCandidates = (widget: Gtk.Widget): Gtk.Accessible[] => {
-    const pool: Gtk.Accessible[] = [...widget.listMnemonicLabels(), ...descendants(widget)];
-    const root = widget.getRoot();
+const mappedWidgets = function* (widget: Gtk.Widget, isParentMapped: boolean): Generator<Gtk.Widget> {
+    const isMapped = (isParentMapped || isNativeWidget(widget)) && isOnScreen(widget);
 
-    if (root instanceof Gtk.Widget) {
-        pool.push(...traverseWidgetTree(root, isAnyWidget));
+    if (isMapped) {
+        yield widget;
     }
 
-    return [...new Set(pool)];
+    for (const child of children(widget)) {
+        yield* mappedWidgets(child, isMapped);
+    }
+};
+
+const relationCandidates = (widget: Gtk.Widget): Iterable<Gtk.Accessible>[] => {
+    const root = widget.getRoot();
+    const tree: Iterable<Gtk.Accessible> = root instanceof Gtk.Widget ? traverseWidgetTree(root, isAnyWidget) : [];
+
+    return [widget.listMnemonicLabels(), descendants(widget), tree];
 };
 
 const resolveRoot = (container: QueryContainer): Gtk.Widget | null => {
@@ -98,7 +122,7 @@ const resolveRoot = (container: QueryContainer): Gtk.Widget | null => {
         return container.getChild();
     }
 
-    return null;
+    throw new TypeError("Query container must resolve to a Gtk.Widget");
 };
 
 const roots = function* (container: Container): Generator<Gtk.Widget> {
@@ -117,7 +141,7 @@ const roots = function* (container: Container): Generator<Gtk.Widget> {
 
 const traverse = function* (container: Container): Generator<Gtk.Widget> {
     for (const root of roots(container)) {
-        yield* traverseWidgetTree(root, isOnScreen);
+        yield* mappedWidgets(root, true);
     }
 };
 

package/src/types.ts

@@ -1,5 +1,5 @@
 import type * as Gtk from "@gtkx/gi/gtk";
-import type { RootElement } from "@gtkx/react";
+import type { CaughtErrorInfo, RootElement } from "@gtkx/react";
 import type { ComponentType, ErrorInfo, ReactNode } from "react";
 import type { PrettyWidgetOptions } from "./pretty-widget.js";
 import type { Container } from "./traversal.js";
@@ -15,9 +15,11 @@ type Matcher = string | number | RegExp | MatcherFunction;
 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.
+ * generated GInterface pseudo-classes that extend `Gtk.Accessible` are accepted.
  */
-type WidgetType<T extends Gtk.Widget = Gtk.Widget> = abstract new (...args: never[]) => T;
+type WidgetType<T extends Gtk.Accessible = Gtk.Accessible> = abstract new (
+    ...args: never[]
+) => T;
 
 /** Options controlling the default text normalizer. */
 type NormalizerOptions = {
@@ -40,7 +42,7 @@ type WaitForOptions = {
 };
 
 /** Options controlling text matching and, for asynchronous queries, polling behavior. */
-type MatcherOptions<T extends Gtk.Widget = Gtk.Widget> = {
+type MatcherOptions<T extends Gtk.Accessible = Gtk.Accessible> = {
     /** 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`. */
@@ -74,7 +76,7 @@ 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> & {
+type ByRoleOptions<T extends Gtk.Accessible = Gtk.Accessible> = 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. */
@@ -116,7 +118,7 @@ type BoundQuery<Q extends Query> = Q extends (container: Container, ...args: inf
 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> = {
+type QueryFamilyReturns<T extends Gtk.Accessible> = {
     /** The single match, or null when nothing matched; throws when more than one matched. */
     queryBy: T | null;
     /** Every match, empty when nothing matched. */
@@ -135,7 +137,7 @@ type QueryFamilyReturns<T extends Gtk.Widget> = {
 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"
+type QueryArgs<Kind extends QueryKind, T extends Gtk.Accessible> = Kind extends "role"
     ? [role: Gtk.AccessibleRole, options?: ByRoleOptions<T>]
     : Kind extends "name"
         ? [name: Matcher, options?: MatcherOptions<T>]
@@ -148,7 +150,9 @@ type QueryArgs<Kind extends QueryKind, T extends Gtk.Widget> = Kind extends "rol
  * 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>(
+    [K in keyof QueryFamilyReturns<Gtk.Widget> as `${K & string}${Suffix}`]: <
+        T extends Gtk.Accessible = Gtk.Widget,
+    >(
         ...args: [...Head, ...QueryArgs<Kind, T>]
     ) => QueryFamilyReturns<T>[K];
 };
@@ -175,7 +179,7 @@ type RenderOptions<Q extends QueryMap = Record<never, never>> = {
      * out of reach of a pointer and a keyboard, so every `userEvent` helper aimed at it rejects
      * after `actionabilityTimeout`; `fireEvent` drives such a tree instead.
      */
-    container?: Gtk.Widget | RootElement | undefined;
+    container?: Gtk.Accessible | RootElement | undefined;
     /** Root of the subtree that bound queries search. */
     baseElement?: Container | undefined;
     /** Component wrapped around the rendered element, such as a context provider. */
@@ -185,7 +189,7 @@ type RenderOptions<Q extends QueryMap = Record<never, never>> = {
     /** Enable widget animations during the test. */
     areAnimationsEnabled?: boolean | undefined;
     /** Called for errors caught by React error boundaries. */
-    onCaughtError?: ((error: unknown, errorInfo: ErrorInfo) => void) | undefined;
+    onCaughtError?: ((error: unknown, errorInfo: CaughtErrorInfo) => void) | undefined;
     /** Called for errors React recovered from automatically. */
     onRecoverableError?: ((error: unknown, errorInfo: ErrorInfo) => void) | undefined;
     /** Custom queries to bind to the rendered result. */

package/src/user-event/adjustment.ts

@@ -16,11 +16,7 @@ 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.
- */
+/** Moves a range to a value. */
 const slide = (widget: Gtk.Widget, value: number): Promise<void> =>
     wrapEvent(widget, () => {
         if (!(widget instanceof Gtk.Range)) {
@@ -76,15 +72,7 @@ const applyScrollDelta = (adjustment: Gtk.Adjustment | null, delta: number): voi
     rampTo(adjustment, adjustment.getValue() + delta, pageSize > 0 ? pageSize : Math.abs(delta));
 };
 
-/**
- * Adds the delta to the adjustments of the widget itself, or of its nearest Gtk.ScrolledWindow or
- * Gtk.Scrollable ancestor.
- *
- * Each adjustment advances in viewport-sized steps rather than one jump, so virtualized views such
- * as Gtk.ListView, Gtk.GridView and Gtk.ColumnView re-anchor onto the rows the new offset shows.
- *
- * @throws When neither the widget nor any of its ancestors is scrollable.
- */
+/** Scrolls the widget or its nearest scrollable ancestor. */
 const scroll = (widget: Gtk.Widget, delta: ScrollDelta): Promise<void> =>
     wrapEvent(widget, async () => {
         const adjustments = resolveScrollAdjustments(widget);

package/src/user-event/click.ts

@@ -11,6 +11,7 @@ type PressPoint = { x: number; y: number };
 type ClickPhase = "pressed" | "released";
 type ClickSite = { gestures: Gtk.GestureClick[]; point: PressPoint };
 type ClickScope = { isClicked: boolean; isInternalAllowed: boolean };
+type DirectClick = { sites: ClickSite[]; outcome: NativeClick | null };
 
 type ClickTarget = {
     widget: Gtk.Widget;
@@ -59,15 +60,6 @@ const emitGesture = (
     }
 };
 
-const emitClickPhase = (
-    widget: Gtk.Widget,
-    controllers: Gtk.GestureClick[],
-    nPress: number,
-    phase: ClickPhase,
-): void => {
-    emitGesture(getCenterPoint(widget), controllers, nPress, phase);
-};
-
 const emitSitePhase = (sites: ClickSite[], nPress: number, phase: ClickPhase): void => {
     for (const site of sites) {
         emitGesture(site.point, site.gestures, nPress, phase);
@@ -97,14 +89,23 @@ const clickGestures = (widget: Gtk.Widget): Gtk.GestureClick[] =>
 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 };
+    if (widget instanceof Gtk.Button) {
+        return { widget, container: null, gestures, isClaiming: true, native: null };
+    }
+
+    const container = containerFor(widget);
+
+    if (container !== null) {
+        return {
+            widget,
+            container,
+            gestures: gestures.filter((gesture) => hasClickHandlers(gesture)),
+            isClaiming: true,
+            native: null,
+        };
     }
 
     const authored = gestures.filter((gesture) => hasClickHandlers(gesture));
@@ -205,7 +206,7 @@ const applyContainerOutcome = (target: ClickTarget, nPress: number): void => {
     }
 
     if (isActivatedByClick(container, nPress)) {
-        widget.activate();
+        Gtk.Widget.prototype.activate.call(widget);
     }
 
     if (isSelectionReplacedByClick(container, nPress)) {
@@ -223,6 +224,24 @@ const applyClickOutcome = (target: ClickTarget, nPress: number): void => {
     target.native(target.widget, nPress);
 };
 
+const applyContainerClick: NativeClick = (widget, nPress) => {
+    const container = containerFor(widget);
+
+    if (container !== null) {
+        applyContainerOutcome({ widget, container, gestures: [], isClaiming: true, native: null }, nPress);
+    }
+};
+
+const directClickFor = (widget: Gtk.Widget): DirectClick => {
+    const native = nativeClickFor(widget, true);
+    const container = native === null ? containerFor(widget) : null;
+    const gestures =
+        native !== null || container !== null ? getAuthoredClickGestures(widget) : clickGestures(widget);
+    const target: ClickTarget = { widget, container, gestures, isClaiming: true, native };
+
+    return { sites: targetSites(widget, target), outcome: native ?? (container === null ? null : applyContainerClick) };
+};
+
 const applyClickOutcomes = (targets: ClickTarget[], nPress: number): void => {
     for (const target of targets) {
         applyClickOutcome(target, nPress);
@@ -246,39 +265,13 @@ const tryActivate = async (widget: Gtk.Widget): Promise<boolean> => {
     let isActivated = false;
 
     await wrapEvent(widget, () => {
-        isActivated = widget.activate();
+        isActivated = Gtk.Widget.prototype.activate.call(widget);
     });
 
     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 notebook tab, clicked directly or through its label,
- * focuses its notebook and switches to its page; 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.
- */
+/** Activates or presses and releases a widget. */
 const click = async (widget: Gtk.Widget): Promise<void> => {
     if (!isSelfClickTarget(widget) && (await tryActivate(widget))) {
         return;
@@ -287,21 +280,10 @@ const click = async (widget: Gtk.Widget): Promise<void> => {
     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, a notebook tab stays on
- * the page the first press opened, and a column header sorts and then inverts its order.
- */
+/** Delivers a double-click gesture. */
 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, notebook tab, or column header.
- */
+/** Delivers a triple-click gesture. */
 const tripleClick = (widget: Gtk.Widget): Promise<void> => deliverClick(widget, 3);
 
-export { clickGestures, emitClickPhase, getAuthoredClickGestures, click, dblClick, tripleClick };
+export { directClickFor, emitSitePhase, click, dblClick, tripleClick };
+export type { DirectClick };

package/src/user-event/controller.ts

@@ -1,4 +1,5 @@
 import type * as Gtk from "@gtkx/gi/gtk";
+import { requireWidget } from "../widget-target.js";
 
 /** An event controller class that can be constructed without arguments, such as `Gtk.GestureClick`. */
 type ControllerConstructor<T extends Gtk.EventController> = new () => T;
@@ -11,9 +12,10 @@ type ControllerConstructor<T extends Gtk.EventController> = new () => T;
  * @returns The matching controllers, or an empty array when the widget has none.
  */
 const queryAllControllers = <T extends Gtk.EventController>(
-    widget: Gtk.Widget,
+    target: Gtk.Accessible,
     controllerType: ControllerConstructor<T>,
 ): T[] => {
+    const widget = requireWidget(target);
     const controllers = widget.observeControllers();
     const nItems = controllers.getNItems();
     const matches: T[] = [];
@@ -37,7 +39,7 @@ const queryAllControllers = <T extends Gtk.EventController>(
  * @returns The first matching controller, or null when the widget has none.
  */
 const queryController = <T extends Gtk.EventController>(
-    widget: Gtk.Widget,
+    widget: Gtk.Accessible,
     controllerType: ControllerConstructor<T>,
 ): T | null => queryAllControllers(widget, controllerType)[0] ?? null;
 
@@ -49,7 +51,7 @@ const queryController = <T extends Gtk.EventController>(
  * @throws When the widget has no controller of that type.
  */
 const getAllControllers = <T extends Gtk.EventController>(
-    widget: Gtk.Widget,
+    widget: Gtk.Accessible,
     controllerType: ControllerConstructor<T>,
 ): T[] => {
     const controllers = queryAllControllers(widget, controllerType);
@@ -69,7 +71,7 @@ const getAllControllers = <T extends Gtk.EventController>(
  * @throws When the widget has no controller of that type.
  */
 const getController = <T extends Gtk.EventController>(
-    widget: Gtk.Widget,
+    widget: Gtk.Accessible,
     controllerType: ControllerConstructor<T>,
 ): T => {
     const [controller] = getAllControllers(widget, controllerType);
@@ -82,9 +84,10 @@ const getController = <T extends Gtk.EventController>(
 };
 
 const getOrCreateControllers = <T extends Gtk.EventController>(
-    widget: Gtk.Widget,
+    target: Gtk.Accessible,
     controllerType: ControllerConstructor<T>,
 ): T[] => {
+    const widget = requireWidget(target);
     const existing = queryAllControllers(widget, controllerType);
 
     if (existing.length > 0) {

package/src/user-event/gesture.ts

@@ -83,56 +83,38 @@ const buildDropValue = (content: DropContent): GObject.Value => {
     });
 };
 
-/** Emits `enter` at the widget's origin on its motion controllers, adding one when it has none. */
+/** Enters a widget. */
 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. */
+/** Leaves a widget. */
 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.
- */
+/** Rotates a widget's gestures. */
 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.
- */
+/** Zooms a widget's gestures. */
 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.
- */
+/** Swipes a widget's gestures. */
 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.
- */
+/** Long-presses a widget. */
 const longPress = (widget: Gtk.Widget, x = 0, y = 0): Promise<void> =>
     dispatchOnControllers(widget, Gtk.GestureLongPress, (controller) => {
         controller.emit("pressed", x, y);
@@ -219,14 +201,7 @@ 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.
- */
+/** Drags a widget by an offset. */
 const drag = async (widget: Gtk.Widget, dx: number, dy: number, options: DragOptions = {}): Promise<void> => {
     if (widget instanceof Gtk.Range) {
         throw new TypeError(
@@ -252,22 +227,13 @@ 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.
- */
+/** Drops content on a widget. */
 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.
- */
+/** Drags content from one widget and drops it on another. */
 const dragAndDrop = async (
     source: Gtk.Widget,
     target: Gtk.Widget,