@gtkx/testing 1.6.0 → 2.0.0-beta.10

package/src/user-event/index.ts

@@ -1,8 +1,19 @@
 import type * as Gtk from "@gtkx/gi/gtk";
 import { delay } from "../timers.js";
+import { requireWidget } from "../widget-target.js";
 import { scroll, slide } from "./adjustment.js";
 import { click, dblClick, tripleClick } from "./click.js";
-import { drag, dragAndDrop, drop, hover, longPress, rotate, swipe, unhover, zoom } from "./gesture.js";
+import {
+    drag,
+    dragAndDrop,
+    drop,
+    hover,
+    longPress,
+    rotate,
+    swipe,
+    unhover,
+    zoom,
+} from "./gesture.js";
 import { keyboard, tab } from "./keyboard.js";
 import { pointer, type PointerInput } from "./pointer.js";
 import { deselectOptions, selectOptions } from "./selection.js";
@@ -15,130 +26,132 @@ type UserEventOptions = {
     delay?: number | null | undefined;
 };
 
-/**
- * The set of user interaction helpers exposed by {@link userEvent}, covering clicks, typing,
- * keyboard, pointer, gestures, selection, and scrolling.
- */
+/** User interactions exposed by {@link userEvent}. */
 type UserEvent = {
-    /**
-     * Returns a fresh instance whose helpers share one keyboard and pointer state, so held modifiers
-     * and buttons carry across its calls but not across instances.
-     */
+    /** Creates an instance with shared keyboard and pointer state. */
     setup: (options?: UserEventOptions) => UserEvent;
-    /**
-     * Activates a widget that neither claims the click nor carries a click gesture of its own, and
-     * otherwise presses and releases outwards from the clicked widget through every widget carrying
-     * a click gesture, stopping at the first button or indexed child. A list box row or flow box
-     * child receives its click gesture at the clicked position, passes one on to the gestures its
-     * container carries, and is then activated, or exclusively selected when its container does not
-     * activate on a single click. The press also stops at a widget whose click GTK4 implements
-     * itself, where the gestures that widget carries of its own still take the press and the same
-     * outcome is then applied through GTK's own public action: a list, grid, or column-view row is
-     * focused and selected, and activated as well when its view activates on a single click; an
-     * expandable tree expander that is itself the clicked widget toggles its expansion; a notebook
-     * tab, clicked directly or through its label, focuses its notebook and switches to its page; a
-     * column header sorts by its column. A column-view cell and the row carrying 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.
-     */
-    click: typeof click;
-    /**
-     * Delivers a two-press click gesture along the same path a single click takes, without trying
-     * activation first, activating a list box row or flow box child on that path and replacing its
-     * container's selection whether or not that container activates on a single click. A widget
-     * whose click GTK4 implements itself receives that outcome once per press, so a row is selected
-     * and 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 inverts its order after sorting.
-     */
-    dblClick: typeof dblClick;
-    /**
-     * 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, and applying the outcome GTK4 implements
-     * itself once per press to a row, tree expander, notebook tab, or column header.
-     */
-    tripleClick: typeof tripleClick;
-    /** Moves focus within the widget's root, forward by default and backward with `isShiftHeld`. */
-    tab: typeof tab;
-    /**
-     * Focuses an editable widget the way clicking into it does, leaving its text unselected, applies
-     * any initial selection, and inserts the text at the cursor, deleting the text the widget has
-     * selected first, the way GTK4 does.
-     */
-    type: typeof type;
-    /** Focuses an editable widget and deletes its whole text, leaving nothing selected. */
-    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, deleting the
-     * text the widget has selected first, the way GTK4 does.
-     */
-    paste: typeof paste;
-    /**
-     * Selects the items at those positions in a view or drop-down, or selects the indexed children of
-     * a list box or flow box through their container, without activating them.
-     */
+    /** Activates or presses and releases a widget. */
+    click: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof click> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
+    /** Delivers a double-click gesture. */
+    dblClick: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof dblClick> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
+    /** Delivers a triple-click gesture. */
+    tripleClick: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof tripleClick> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
+    /** Moves focus forward or backward within the root. */
+    tab: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof tab> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
+    /** Types into an editable widget. */
+    type: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof type> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
+    /** Deletes all text from an editable widget. */
+    clear: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof clear> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
+    /** Copies the current selection. */
+    copy: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof copy> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
+    /** Cuts the current selection. */
+    cut: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof cut> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
+    /** Pastes text or clipboard contents. */
+    paste: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof paste> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
+    /** Selects positions without activating them. */
     selectOptions: typeof selectOptions;
-    /** Unselects the items at those positions, leaving list box and flow box children unactivated. */
+    /** Unselects positions without activating them. */
     deselectOptions: typeof deselectOptions;
     /** Emits a motion `enter` on the widget, adding a motion controller when it has none. */
-    hover: typeof hover;
+    hover: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof hover> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
     /** Emits a motion `leave` on the widget, adding a motion controller when it has none. */
-    unhover: typeof unhover;
+    unhover: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof unhover> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
     /** Emits `angle-changed` on the widget's rotate gestures. */
-    rotate: typeof rotate;
+    rotate: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof rotate> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
     /** Emits `scale-changed` on the widget's zoom gestures. */
-    zoom: typeof zoom;
+    zoom: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof zoom> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
     /** Emits `swipe` with the given velocity on the widget's swipe gestures. */
-    swipe: typeof swipe;
+    swipe: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof swipe> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
     /** Emits `pressed` at the given point on the widget's long-press gestures. */
-    longPress: typeof longPress;
+    longPress: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof longPress> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
     /** Runs a begin, update, and end sequence on the widget's drag gestures, ending at the given offset. */
-    drag: typeof drag;
+    drag: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof drag> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
     /** Emits `drop` with the given content on the widget's drop targets. */
-    drop: typeof drop;
+    drop: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof drop> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
     /** Requires a drag source on the source widget, then emits `drop` with the content on the target's drop targets. */
-    dragAndDrop: typeof dragAndDrop;
+    dragAndDrop: (
+        source: Gtk.Accessible,
+        target: Gtk.Accessible,
+        ...args: Parameters<typeof dragAndDrop> extends [Gtk.Widget, Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
     /** Emits a jump `change-value` on a Gtk.Range so it moves to the given value. */
-    slide: typeof slide;
+    slide: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof slide> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
     /** Adds the delta to the adjustments of the widget itself, or of its nearest scrollable ancestor. */
-    scroll: typeof scroll;
-    /**
-     * Sends a key sequence along the chain GTK4 propagates a key event through: the application's
-     * accelerators first, then the capture-phase controllers from the root down to the event widget,
-     * the event widget's target-phase controllers, and the bubble-phase controllers from it back up
-     * to the root, so a key controller or shortcut controller a container or window above the widget
-     * carries receives the key too, each in the phase it declares. The event widget is the editable
-     * delegate GTK4 focuses when the widget has one, the `Gtk.Text` inside a `Gtk.Entry` for
-     * instance, so the delegate stands ahead of the widget in the chain. A shortcut controller whose
-     * scope is not local runs where it registered instead, the root for a global one and the nearest
-     * `Gtk.ShortcutManager` for a managed one, so it fires wherever focus sits inside that subtree
-     * and never at its own widget, while a shortcut whose widget is insensitive or unmapped stays
-     * inert wherever it sits. The first controller that handles a press ends the chain, and a
-     * `Gdk.KEY_Return` press none of them handled reaches an editable widget's activate handler.
-     * Built-in key bindings take part, since GTK4 carries them on a shortcut controller: a
-     * `Gtk.Text`'s arrow keys or a `Gtk.TextView`'s undo can consume a press before an ancestor
-     * sees it. Key controllers GTK4 attaches itself are the exception, since they read a GDK event
-     * that off-screen synthesis cannot produce, so only the key controllers the tree connected a
-     * `key-pressed` or `key-released` handler to take part. Held modifiers carry across calls.
-     */
-    keyboard: (widget: Gtk.Widget, input: string) => Promise<void>;
-    /**
-     * Applies a pointer token to the click gestures the widget already carries, tracking whether the
-     * left button is held across calls. On a widget whose click GTK4 implements itself, the release
-     * also applies GTK's own outcome, the way {@link UserEvent.click} does, and a column-view cell
-     * or the row carrying the column headers passes the token to the row or view behind it.
-     */
-    pointer: (widget: Gtk.Widget, input: PointerInput) => Promise<void>;
+    scroll: (
+        widget: Gtk.Accessible,
+        ...args: Parameters<typeof scroll> extends [Gtk.Widget, ...infer Args] ? Args : never
+    ) => Promise<void>;
+    /** Sends a key sequence through GTK's propagation chain. */
+    keyboard: (widget: Gtk.Accessible, input: string) => Promise<void>;
+    /** Applies a pointer token while preserving held-button state. */
+    pointer: (widget: Gtk.Accessible, input: PointerInput) => Promise<void>;
 };
 
-/**
- * High-level helpers that drive widgets by dispatching the same events and gestures GTK4 delivers
- * when someone clicks, types, or drags. Call `setup` for an instance with its own keyboard and
- * pointer state.
- */
+const onWidget =
+    <Args extends unknown[]>(helper: (widget: Gtk.Widget, ...args: Args) => Promise<void>) =>
+        (target: Gtk.Accessible, ...args: Args): Promise<void> =>
+            helper(requireWidget(target), ...args);
+
+const onWidgetPair =
+    <Args extends unknown[]>(helper: (source: Gtk.Widget, target: Gtk.Widget, ...args: Args) => Promise<void>) =>
+        (source: Gtk.Accessible, target: Gtk.Accessible, ...args: Args): Promise<void> =>
+            helper(requireWidget(source), requireWidget(target), ...args);
+
+/** User interactions that dispatch GTK events and gestures. */
 const userEvent: UserEvent = {
     ...createInstance(createInitialState(), {}),
     setup: (options?: UserEventOptions): UserEvent => createInstance(createInitialState(), options ?? {}),
@@ -162,30 +175,34 @@ function createInstance(state: UserEventState, options: UserEventOptions): UserE
 
     return {
         setup: (overrides?: UserEventOptions): UserEvent => createInstance(state, { ...options, ...overrides }),
-        click: after(click),
-        dblClick: after(dblClick),
-        tripleClick: after(tripleClick),
-        tab: after(tab),
-        type: after(type),
-        clear: after(clear),
-        copy: after(copy),
-        cut: after(cut),
-        paste: after(paste),
-        selectOptions: after(selectOptions),
-        deselectOptions: after(deselectOptions),
-        hover: after(hover),
-        unhover: after(unhover),
-        rotate: after(rotate),
-        zoom: after(zoom),
-        swipe: after(swipe),
-        longPress: after(longPress),
-        drag: after(drag),
-        drop: after(drop),
-        dragAndDrop: after(dragAndDrop),
-        slide: after(slide),
-        scroll: after(scroll),
-        keyboard: after((widget: Gtk.Widget, input: string): Promise<void> => keyboard(state, widget, input)),
-        pointer: after((widget: Gtk.Widget, input: PointerInput): Promise<void> => pointer(state, widget, input)),
+        click: after(onWidget(click)),
+        dblClick: after(onWidget(dblClick)),
+        tripleClick: after(onWidget(tripleClick)),
+        tab: after(onWidget(tab)),
+        type: after(onWidget(type)),
+        clear: after(onWidget(clear)),
+        copy: after(onWidget(copy)),
+        cut: after(onWidget(cut)),
+        paste: after(onWidget(paste)),
+        selectOptions: after(onWidget(selectOptions)),
+        deselectOptions: after(onWidget(deselectOptions)),
+        hover: after(onWidget(hover)),
+        unhover: after(onWidget(unhover)),
+        rotate: after(onWidget(rotate)),
+        zoom: after(onWidget(zoom)),
+        swipe: after(onWidget(swipe)),
+        longPress: after(onWidget(longPress)),
+        drag: after(onWidget(drag)),
+        drop: after(onWidget(drop)),
+        dragAndDrop: after(onWidgetPair(dragAndDrop)),
+        slide: after(onWidget(slide)),
+        scroll: after(onWidget(scroll)),
+        keyboard: after(
+            onWidget((widget: Gtk.Widget, input: string): Promise<void> => keyboard(state, widget, input)),
+        ),
+        pointer: after(
+            onWidget((widget: Gtk.Widget, input: PointerInput): Promise<void> => pointer(state, widget, input)),
+        ),
     };
 }
 

package/src/user-event/keyboard.ts

@@ -18,6 +18,7 @@ type KeyAction = { keyval: number; isPress: boolean };
 type ParseStep = { actions: KeyAction[]; next: number };
 type KeyStopController = Gtk.EventControllerKey | Gtk.ShortcutController;
 type KeyStop = { widget: Gtk.Widget; controller: KeyStopController };
+type KeyTarget = { root: Gtk.Root | null; focus: Gtk.Widget | null };
 
 const KEY_MAP: Record<string, number> = {
     Enter: Gdk.KEY_Return,
@@ -65,7 +66,7 @@ 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. */
+/** Moves focus within the widget's root. */
 const tab = (widget: Gtk.Widget, options?: TabOptions): Promise<void> =>
     wrapEvent(widget, () => {
         const direction = options?.isShiftHeld ? Gtk.DirectionType.TAB_BACKWARD : Gtk.DirectionType.TAB_FORWARD;
@@ -366,9 +367,37 @@ const didStopHandlePress = (stop: KeyStop, keyval: number, modifiers: Gdk.Modifi
     return controller.emit("key-pressed", keyval, 0, modifiers);
 };
 
-const didHandlePress = (widget: Gtk.Widget, keyval: number, modifiers: Gdk.ModifierType): boolean =>
-    didDispatchApplicationAccels(widget, keyval, modifiers) ||
-    keyPropagationChain(widget).some((stop) => didStopHandlePress(stop, keyval, modifiers));
+const keyTargetFor = (widget: Gtk.Widget): KeyTarget => {
+    const root = widget.getRoot();
+
+    return { root, focus: root instanceof Gtk.Window ? root.getFocus() : null };
+};
+
+const isKeyTargetInvalidated = (widget: Gtk.Widget, target: KeyTarget): boolean => {
+    const current = keyTargetFor(widget);
+
+    return current.root !== target.root || current.focus !== target.focus || !widget.getMapped();
+};
+
+const didHandlePress = (widget: Gtk.Widget, keyval: number, modifiers: Gdk.ModifierType): boolean => {
+    const target = keyTargetFor(widget);
+
+    if (didDispatchApplicationAccels(widget, keyval, modifiers)) {
+        return true;
+    }
+
+    if (isKeyTargetInvalidated(widget, target)) {
+        return true;
+    }
+
+    for (const stop of keyPropagationChain(widget)) {
+        if (didStopHandlePress(stop, keyval, modifiers) || isKeyTargetInvalidated(widget, target)) {
+            return true;
+        }
+    }
+
+    return false;
+};
 
 const emitKeyReleased = (widget: Gtk.Widget, keyval: number, modifiers: Gdk.ModifierType): void => {
     for (const stop of keyPropagationChain(widget)) {

package/src/user-event/list-row-click.ts

@@ -1,5 +1,5 @@
-import type * as Gtk from "@gtkx/gi/gtk";
 import * as GLib from "@gtkx/gi/glib";
+import * as Gtk from "@gtkx/gi/gtk";
 import { ancestors } from "../traversal.js";
 import { callBooleanGetter, hasWidgetMethod } from "../widget-getters.js";
 
@@ -41,7 +41,7 @@ const applyRowPress = (row: Gtk.Widget, press: number): void => {
     selectRow(row);
 
     if (isRowActivatedByPress(row, press)) {
-        row.activate();
+        Gtk.Widget.prototype.activate.call(row);
     }
 };
 

package/src/user-event/pointer.ts

@@ -1,16 +1,15 @@
 import type * as Gtk from "@gtkx/gi/gtk";
-import type { NativeClick } from "./native-click.js";
 import type { UserEventState } from "./state.js";
-import { clickGestures, emitClickPhase, getAuthoredClickGestures } from "./click.js";
+import { type DirectClick, directClickFor, emitSitePhase } from "./click.js";
 import { wrapEvent } from "./event-wrapper.js";
-import { isClickTransparent, nativeClickFor } from "./native-click.js";
+import { isClickTransparent } from "./native-click.js";
 
 /**
  * A pointer action token: a full click (`click`, `[MouseLeft]`), a button press (`down`,
  * `[MouseLeft>]`), or a button release (`up`, `[/MouseLeft]`).
  */
 type PointerInput = "click" | "down" | "up" | "[MouseLeft]" | "[MouseLeft>]" | "[/MouseLeft]";
-type PointerTarget = { widget: Gtk.Widget; gestures: Gtk.GestureClick[]; native: NativeClick | null };
+type PointerTarget = { widget: Gtk.Widget; click: DirectClick };
 
 const PRESS_INPUTS: Set<PointerInput> = new Set(["[MouseLeft>]", "down"]);
 const RELEASE_INPUTS: Set<PointerInput> = new Set(["[/MouseLeft]", "up"]);
@@ -32,26 +31,23 @@ const pointerWidgetFor = (widget: Gtk.Widget): Gtk.Widget => {
     return current;
 };
 
-const pointerGesturesFor = (widget: Gtk.Widget, native: NativeClick | null): Gtk.GestureClick[] =>
-    native === null ? clickGestures(widget) : getAuthoredClickGestures(widget);
-
 const pointerTargetFor = (widget: Gtk.Widget): PointerTarget => {
     const target = pointerWidgetFor(widget);
-    const native = nativeClickFor(target, true);
 
-    return { widget: target, gestures: pointerGesturesFor(target, native), native };
+    return { widget: target, click: directClickFor(target) };
 };
 
-const pressPointer = ({ widget, gestures }: PointerTarget): void => {
-    emitClickPhase(widget, gestures, 1, "pressed");
+const pressPointer = ({ click }: PointerTarget): void => {
+    emitSitePhase(click.sites, 1, "pressed");
 };
 
-const releasePointer = ({ widget, gestures, native }: PointerTarget): void => {
-    emitClickPhase(widget, gestures, 1, "released");
-    native?.(widget, 1);
+const releasePointer = ({ widget, click }: PointerTarget): void => {
+    emitSitePhase(click.sites, 1, "released");
+    click.outcome?.(widget, 1);
 };
 
-const isPointerPressable = (target: PointerTarget): boolean => target.native !== null || target.gestures.length > 0;
+const isPointerPressable = (target: PointerTarget): boolean =>
+    target.click.outcome !== null || target.click.sites.some((site) => site.gestures.length > 0);
 
 const applyPointerInput = (widget: Gtk.Widget, state: UserEventState, input: PointerInput): void => {
     const target = pointerTargetFor(widget);

package/src/user-event/selection.ts

@@ -19,9 +19,7 @@ const SELECTABLE_ROLES: Set<Gtk.AccessibleRole> = new Set([
     Gtk.AccessibleRole.LIST,
 ]);
 
-const isSelectable = (widget: Gtk.Widget): boolean => {
-    return SELECTABLE_ROLES.has(widget.getAccessibleRole());
-};
+const isSelectable = (widget: Gtk.Widget): boolean => SELECTABLE_ROLES.has(widget.getAccessibleRole());
 
 const selectListViewItems = (
     selectionModel: Gtk.SelectionModel,
@@ -155,18 +153,17 @@ 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 selected position of a widget with the COMBO_BOX role, or by selecting the indexed
- * children of a list box or flow box through their container. An empty array clears a view's
- * selection. The children are never activated, so no row-activated handler runs.
- *
- * @throws When a view has no selection model, when a COMBO_BOX-role widget is given more than one
- * position or exposes no `setSelected`, or when the widget's role is none of COMBO_BOX, GRID, or
- * LIST.
- */
-const selectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
-    runSelectionEvent(widget, values, selectInListView, selectByRole);
+const requireWidget = (target: Gtk.Accessible): Gtk.Widget => {
+    if (!(target instanceof Gtk.Widget)) {
+        throw new TypeError("Cannot select options on a non-widget accessible");
+    }
+
+    return target;
+};
+
+/** Selects positions without activating them. */
+const selectOptions = (widget: Gtk.Accessible, values: number | number[]): Promise<void> =>
+    runSelectionEvent(requireWidget(widget), values, selectInListView, selectByRole);
 
 const deselectInListView = (widget: Gtk.ListView | Gtk.GridView | Gtk.ColumnView, valueArray: number[]): void => {
     const selectionModel = requireSelectionModel(widget, "deselect");
@@ -186,15 +183,8 @@ const deselectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
     applyIndexedChildren(widget, valueArray, unselectChildRow);
 };
 
-/**
- * Unselects the items at the given positions in a list, grid, or column view, or unselects the
- * indexed children of a list box or flow box through their container. A child that is not selected
- * is left alone, and no child is activated.
- *
- * @throws When a view has no selection model, when the widget's role is none of COMBO_BOX, GRID, or
- * LIST, or when it exposes no indexed children.
- */
-const deselectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
-    runSelectionEvent(widget, values, deselectInListView, deselectByRole);
+/** Unselects positions without activating them. */
+const deselectOptions = (widget: Gtk.Accessible, values: number | number[]): Promise<void> =>
+    runSelectionEvent(requireWidget(widget), values, deselectInListView, deselectByRole);
 
 export { selectOptions, deselectOptions };

package/src/user-event/text.ts

@@ -198,15 +198,7 @@ const runEditableEvent = (
         action(widget);
     });
 
-/**
- * Focuses the widget unless `shouldFocus` is false, applies any initial selection, and inserts the
- * text at the cursor, deleting the text the widget has selected first, the way typing over a
- * selection does in GTK4. Focusing works the way clicking into the widget does, leaving its text
- * unselected: a `Gtk.Editable` takes its caret to the end of its text, a `Gtk.TextView` keeps the
- * caret where it stands, and the replaced text stays on the widget's undo stack either way.
- *
- * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
- */
+/** Types into an editable widget. */
 const type = (widget: Gtk.Widget, text: string, options?: TypeOptions): Promise<void> =>
     runEditableEvent(widget, "Cannot type into element", (editable) => {
         if (options?.shouldFocus ?? true) {
@@ -286,45 +278,24 @@ const clearEditable = (editable: EditableTarget): void => {
     }
 };
 
-/**
- * Focuses an editable widget and deletes its whole text through the widget's own editing API, so the
- * deletion emits the signals an edit made by hand emits. Text a tag protects is detected before the
- * deletion runs, leaving such a widget untouched. A widget that writes a new value back in response
- * to the deletion, as an input mask does, is cleared successfully and keeps whatever it wrote.
- *
- * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView, when it refuses edits, when
- * a tag protects part of its text, or when a handler blocks the deletion.
- */
+/** Deletes all text from an editable widget. */
 const clear = (widget: Gtk.Widget): Promise<void> =>
     runEditableEvent(widget, "Cannot clear element", clearEditable);
 
-/**
- * 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.
- */
+/** Copies the current selection. */
 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.
- */
+/** Cuts the current selection. */
 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, and deleting the text the widget has selected first, the way a paste does in GTK4.
- *
- * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
- */
+/** Pastes text or clipboard contents. */
 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

@@ -4,12 +4,13 @@ import { runWithActEnvironment } from "./act.js";
 import { getConfig } from "./config.js";
 import { timeoutError } from "./errors.js";
 import { advanceFakeClock, delay, now } from "./timers.js";
+import { requireWidget } from "./widget-target.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;
+type RemovalTarget = Gtk.Accessible | Gtk.Accessible[] | 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);
+type ElementOrCallback = Gtk.Accessible | Gtk.Accessible[] | (() => RemovalTarget);
 
 const DEFAULT_INTERVAL = 50;
 const ELEMENT_NOT_REMOVED = new Error("Element not yet removed");
@@ -102,10 +103,8 @@ const waitFor = <T>(callback: () => T | Promise<T>, options?: WaitForOptions): P
 const getTarget = (elementOrCallback: ElementOrCallback): RemovalTarget =>
     typeof elementOrCallback === "function" ? elementOrCallback() : elementOrCallback;
 
-const isWidgetRemoved = (widget: Gtk.Widget | null): boolean => {
-    if (widget === null) {
-        return true;
-    }
+const isWidgetRemoved = (target: Gtk.Accessible): boolean => {
+    const widget = requireWidget(target);
 
     try {
         return widget.getRoot() === null;
@@ -115,6 +114,10 @@ const isWidgetRemoved = (widget: Gtk.Widget | null): boolean => {
 };
 
 const isTargetRemoved = (target: RemovalTarget): boolean => {
+    if (target === null) {
+        return true;
+    }
+
     if (Array.isArray(target)) {
         return target.every((widget) => isWidgetRemoved(widget));
     }