@gtkx/testing 1.0.0-rc.4 → 1.0.0

package/src/user-event/index.ts

@@ -5,28 +5,61 @@ import { drag, dragAndDrop, drop, hover, longPress, rotate, swipe, unhover, zoom
 import { keyboard, tab } from "./keyboard.js";
 import { pointer, type PointerInput } from "./pointer.js";
 import { deselectOptions, selectOptions } from "./selection.js";
-import { createInitialState } from "./state.js";
+import { createInitialState, type UserEventState } from "./state.js";
 import { clear, copy, cut, paste, type } from "./text.js";
 
+/** Options shared by every helper on a {@link UserEvent} instance. */
+type UserEventOptions = {
+    /** Milliseconds to wait after each helper resolves; null, the default, waits not at all. */
+    delay?: number | null | undefined;
+};
+
 /**
  * The set of user interaction helpers exposed by {@link userEvent}, covering clicks, typing,
  * 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.
+     * 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.
+     */
+    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 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;
-    /** Emits a two-press click gesture on the widget. */
+    /**
+     * 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, and a column
+     * header inverts its order after sorting.
+     */
     dblClick: typeof dblClick;
-    /** Emits a three-press click gesture on the widget. */
+    /**
+     * 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, 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, applies any initial selection, and inserts the text at the cursor. */
     type: typeof type;
-    /** Empties an editable widget's text. */
+    /** 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;
@@ -34,9 +67,12 @@ type UserEvent = {
     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. */
+    /**
+     * 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.
+     */
     selectOptions: typeof selectOptions;
-    /** Deselects the items at the given positions in a list view or list box. */
+    /** Unselects the items at those positions, leaving list box and flow box children unactivated. */
     deselectOptions: typeof deselectOptions;
     /** Emits a motion `enter` on the widget, adding a motion controller when it has none. */
     hover: typeof hover;
@@ -62,47 +98,74 @@ type UserEvent = {
     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. */
+    /**
+     * 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>;
 };
 
-const state = createInitialState();
-
 /**
  * High-level helpers that drive widgets by dispatching the same events and gestures GTK4 delivers
- * when someone clicks, types, or drags.
+ * when someone clicks, types, or drags. Call `setup` for an instance with its own keyboard and
+ * pointer state.
  */
 const userEvent: UserEvent = {
-    click,
-    dblClick,
-    tripleClick,
-    tab,
-    type,
-    clear,
-    copy,
-    cut,
-    paste,
-    selectOptions,
-    deselectOptions,
-    hover,
-    unhover,
-    rotate,
-    zoom,
-    swipe,
-    longPress,
-    drag,
-    drop,
-    dragAndDrop,
-    slide,
-    scroll,
-    keyboard: (widget: Gtk.Widget, input: string): Promise<void> => keyboard(state, widget, input),
-    pointer: (widget: Gtk.Widget, input: PointerInput): Promise<void> => pointer(state, widget, input),
+    ...createInstance(createInitialState(), {}),
+    setup: (options?: UserEventOptions): UserEvent => createInstance(createInitialState(), options ?? {}),
 };
 
+const settle = (delay: number | null | undefined): Promise<void> => {
+    if (delay === null || delay === undefined) {
+        return Promise.resolve();
+    }
+
+    return new Promise((resolve) => setTimeout(resolve, delay));
+};
+
+function createInstance(state: UserEventState, options: UserEventOptions): UserEvent {
+    const after =
+        <Args extends unknown[]>(helper: (...args: Args) => Promise<void>) =>
+            async (...args: Args): Promise<void> => {
+                await helper(...args);
+                await settle(options.delay);
+            };
+
+    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)),
+    };
+}
+
 export type { ScrollDelta } from "./adjustment.js";
 export type { DragOffset, DragOptions, DropContent, DropOptions } from "./gesture.js";
 export type { TabOptions } from "./keyboard.js";
 export type { PointerInput } from "./pointer.js";
 export type { TypeOptions } from "./text.js";
 export { resetClipboard } from "./text.js";
-export { userEvent, type UserEvent };
+export { userEvent, type UserEvent, type UserEventOptions };

package/src/user-event/indexed-children.ts

@@ -0,0 +1,75 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { callBooleanGetter, getCallableMethod, hasWidgetMethod } from "../widget-getters.js";
+
+const CHILD_AT_INDEX_GETTERS = ["getRowAtIndex", "getChildAtIndex"];
+const CHILD_SELECTORS = ["selectRow", "selectChild"];
+const CHILD_DESELECTORS = ["unselectRow", "unselectChild"];
+const SELECTED_CHILD_GETTERS = ["getSelectedRows", "getSelectedChildren"];
+const SELECTED_PROBE = "isSelected";
+
+const hasIndexedChildren = (widget: Gtk.Widget): boolean =>
+    CHILD_AT_INDEX_GETTERS.some((getter) => hasWidgetMethod(widget, getter));
+
+const getChildAtIndex = (widget: Gtk.Widget, index: number): Gtk.Widget | null => {
+    for (const getter of CHILD_AT_INDEX_GETTERS) {
+        const fn = getCallableMethod<[number], Gtk.Widget | null>(widget, getter);
+
+        if (fn) {
+            return fn(index) ?? null;
+        }
+    }
+
+    return null;
+};
+
+const applyChildMethod = (container: Gtk.Widget, names: string[], child: Gtk.Widget): void => {
+    for (const name of names) {
+        const fn = getCallableMethod<[Gtk.Widget], unknown>(container, name);
+
+        if (fn) {
+            fn(child);
+
+            return;
+        }
+    }
+};
+
+const selectContainerChild = (container: Gtk.Widget, child: Gtk.Widget): void => {
+    applyChildMethod(container, CHILD_SELECTORS, child);
+};
+
+const unselectContainerChild = (container: Gtk.Widget, child: Gtk.Widget): void => {
+    applyChildMethod(container, CHILD_DESELECTORS, child);
+};
+
+const isChildSelected = (child: Gtk.Widget): boolean => callBooleanGetter(child, SELECTED_PROBE) ?? false;
+
+const getSelectedChildren = (container: Gtk.Widget): Gtk.Widget[] => {
+    for (const getter of SELECTED_CHILD_GETTERS) {
+        const fn = getCallableMethod<[], Gtk.Widget[]>(container, getter);
+
+        if (fn) {
+            return fn();
+        }
+    }
+
+    return [];
+};
+
+const unselectOtherChildren = (container: Gtk.Widget, child: Gtk.Widget): void => {
+    for (const selected of getSelectedChildren(container)) {
+        if (selected !== child) {
+            unselectContainerChild(container, selected);
+        }
+    }
+};
+
+export {
+    getChildAtIndex,
+    hasIndexedChildren,
+    isChildSelected,
+    SELECTED_PROBE,
+    selectContainerChild,
+    unselectContainerChild,
+    unselectOtherChildren,
+};

package/src/user-event/keyboard.ts

@@ -1,4 +1,5 @@
 import * as Gdk from "@gtkx/gi/gdk";
+import * as Gio from "@gtkx/gi/gio";
 import * as Gtk from "@gtkx/gi/gtk";
 import type { UserEventState } from "./state.js";
 import { getEditableDelegate } from "../editable.js";
@@ -238,13 +239,55 @@ const didDispatchShortcutsOnWidget = (widget: Gtk.Widget, keyval: number, modifi
     return false;
 };
 
-const didDispatchShortcuts = (widget: Gtk.Widget, keyval: number, modifiers: number): boolean => {
-    const delegate = getEditableDelegate(widget);
+const isAccelMatch = (accel: string, keyval: number, modifiers: Gdk.ModifierType): boolean => {
+    const [isParsed, accelKeyval, accelModifiers] = Gtk.acceleratorParse(accel);
+
+    return isParsed && accelKeyval === keyval && accelModifiers === modifiers;
+};
+
+const hasMatchingAccel = (
+    application: Gtk.Application,
+    detailedActionName: string,
+    keyval: number,
+    modifiers: number,
+): boolean =>
+    application.getAccelsForAction(detailedActionName).some((accel) => isAccelMatch(accel, keyval, modifiers));
+
+const didActivateDetailedAction = (window: Gtk.Window, detailedActionName: string): boolean => {
+    const [isParsed, actionName, target] = Gio.Action.parseDetailedName(detailedActionName);
 
-    if (delegate && didDispatchShortcutsOnWidget(delegate, keyval, modifiers)) {
-        return true;
+    return isParsed && window.activateAction(actionName, target);
+};
+
+const didDispatchAccelsOnWindow = (window: Gtk.Window, keyval: number, modifiers: number): boolean => {
+    const application = window.getApplication();
+
+    if (!application) {
+        return false;
     }
 
+    for (const detailedActionName of application.listActionDescriptions()) {
+        if (hasMatchingAccel(application, detailedActionName, keyval, modifiers)) {
+            return didActivateDetailedAction(window, detailedActionName);
+        }
+    }
+
+    return false;
+};
+
+const didDispatchApplicationAccels = (widget: Gtk.Widget, keyval: number, modifiers: number): boolean => {
+    const root = widget.getRoot();
+
+    return root instanceof Gtk.Window && didDispatchAccelsOnWindow(root, keyval, modifiers);
+};
+
+const didDispatchDelegateShortcuts = (widget: Gtk.Widget, keyval: number, modifiers: number): boolean => {
+    const delegate = getEditableDelegate(widget);
+
+    return delegate !== null && didDispatchShortcutsOnWidget(delegate, keyval, modifiers);
+};
+
+const didDispatchShortcutsOnAncestors = (widget: Gtk.Widget, keyval: number, modifiers: number): boolean => {
     for (let current: Gtk.Widget | null = widget; current; current = current.getParent()) {
         if (didDispatchShortcutsOnWidget(current, keyval, modifiers)) {
             return true;
@@ -254,6 +297,11 @@ const didDispatchShortcuts = (widget: Gtk.Widget, keyval: number, modifiers: num
     return false;
 };
 
+const didDispatchShortcuts = (widget: Gtk.Widget, keyval: number, modifiers: number): boolean =>
+    didDispatchApplicationAccels(widget, keyval, modifiers) ||
+    didDispatchDelegateShortcuts(widget, keyval, modifiers) ||
+    didDispatchShortcutsOnAncestors(widget, keyval, modifiers);
+
 const handleKeyPress = async (widget: Gtk.Widget, keyval: number, modifiers: number): Promise<void> => {
     const isHandled = didDispatchShortcuts(widget, keyval, modifiers);
 

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

@@ -0,0 +1,57 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import * as GLib from "@gtkx/gi/glib";
+import { callBooleanGetter, hasWidgetMethod } from "../widget-getters.js";
+
+const SELECT_ACTION = "listitem.select";
+const SINGLE_CLICK_ACTIVATE_GETTER = "getSingleClickActivate";
+const DOUBLE_CLICK_PRESS = 2;
+
+const viewFor = (row: Gtk.Widget): Gtk.Widget | null => {
+    let current: Gtk.Widget | null = row.getParent();
+
+    while (current !== null) {
+        if (hasWidgetMethod(current, SINGLE_CLICK_ACTIVATE_GETTER)) {
+            return current;
+        }
+
+        current = current.getParent();
+    }
+
+    return null;
+};
+
+const isViewSingleClickActivating = (row: Gtk.Widget): boolean => {
+    const view = viewFor(row);
+
+    return view === null ? false : callBooleanGetter(view, SINGLE_CLICK_ACTIVATE_GETTER) ?? false;
+};
+
+const selectRow = (row: Gtk.Widget): void => {
+    row.activateAction(
+        SELECT_ACTION,
+        GLib.Variant.newTuple([GLib.Variant.newBoolean(false), GLib.Variant.newBoolean(false)]),
+    );
+};
+
+const isRowActivatedByPress = (row: Gtk.Widget, press: number): boolean =>
+    press === DOUBLE_CLICK_PRESS || isViewSingleClickActivating(row);
+
+const applyRowPress = (row: Gtk.Widget, press: number): void => {
+    if (row.getFocusOnClick()) {
+        row.grabFocus();
+    }
+
+    selectRow(row);
+
+    if (isRowActivatedByPress(row, press)) {
+        row.activate();
+    }
+};
+
+const applyRowClick = (row: Gtk.Widget, nPress: number): void => {
+    for (let press = 1; press <= nPress; press++) {
+        applyRowPress(row, press);
+    }
+};
+
+export { applyRowClick };

package/src/user-event/native-click.ts

@@ -0,0 +1,46 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { getWidgetTypeName } from "../widget-getters.js";
+import { applyHeaderClick } from "./column-header-click.js";
+import { applyRowClick } from "./list-row-click.js";
+
+type NativeClick = (widget: Gtk.Widget, nPress: number) => void;
+
+const COLUMN_ROW_TYPE_NAME = "GtkColumnViewRowWidget";
+const ROW_TYPE_NAMES: Set<string> = new Set([COLUMN_ROW_TYPE_NAME, "GtkListItemWidget"]);
+const CELL_TYPE_NAME = "GtkColumnViewCellWidget";
+const TITLE_TYPE_NAME = "GtkColumnViewTitle";
+const TOGGLE_EXPAND_ACTION = "listitem.toggle-expand";
+
+const isHeaderRow = (widget: Gtk.Widget): boolean =>
+    getWidgetTypeName(widget) === COLUMN_ROW_TYPE_NAME && widget.getParent() instanceof Gtk.ColumnView;
+
+const isClickTransparent = (widget: Gtk.Widget): boolean =>
+    getWidgetTypeName(widget) === CELL_TYPE_NAME || isHeaderRow(widget);
+
+const isExpanderToggling = (widget: Gtk.Widget): boolean =>
+    widget instanceof Gtk.TreeExpander &&
+    widget.getListRow()?.isExpandable() === true &&
+    !widget.getHideExpander();
+
+const isColumnHeader = (widget: Gtk.Widget): boolean => getWidgetTypeName(widget) === TITLE_TYPE_NAME;
+const isFactoryRow = (widget: Gtk.Widget): boolean => ROW_TYPE_NAMES.has(getWidgetTypeName(widget) ?? "");
+
+const toggleExpander = (widget: Gtk.Widget, nPress: number): void => {
+    for (let press = 1; press <= nPress; press++) {
+        widget.activateAction(TOGGLE_EXPAND_ACTION, null);
+    }
+};
+
+const nativeClickFor = (widget: Gtk.Widget, isClicked: boolean): NativeClick | null => {
+    if (isClicked && isExpanderToggling(widget)) {
+        return toggleExpander;
+    }
+
+    if (isColumnHeader(widget)) {
+        return applyHeaderClick;
+    }
+
+    return isFactoryRow(widget) ? applyRowClick : null;
+};
+
+export { isClickTransparent, type NativeClick, nativeClickFor };

package/src/user-event/pointer.ts

@@ -1,39 +1,78 @@
-import * as Gtk from "@gtkx/gi/gtk";
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { NativeClick } from "./native-click.js";
 import type { UserEventState } from "./state.js";
-import { emitPress, emitRelease } from "./click.js";
-import { getOrCreateControllers } from "./controller.js";
+import { clickGestures, emitClickPhase, getAuthoredClickGestures } from "./click.js";
 import { wrapEvent } from "./event-wrapper.js";
+import { isClickTransparent, nativeClickFor } 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 };
 
 const PRESS_INPUTS: Set<PointerInput> = new Set(["[MouseLeft>]", "down"]);
 const RELEASE_INPUTS: Set<PointerInput> = new Set(["[/MouseLeft]", "up"]);
 const CLICK_INPUTS: Set<PointerInput> = new Set(["[MouseLeft]", "click"]);
 
+const pointerWidgetFor = (widget: Gtk.Widget): Gtk.Widget => {
+    let current = widget;
+
+    while (isClickTransparent(current)) {
+        const parent = current.getParent();
+
+        if (parent === null) {
+            return current;
+        }
+
+        current = parent;
+    }
+
+    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 };
+};
+
+const pressPointer = ({ widget, gestures }: PointerTarget): void => {
+    emitClickPhase(widget, gestures, 1, "pressed");
+};
+
+const releasePointer = ({ widget, gestures, native }: PointerTarget): void => {
+    emitClickPhase(widget, gestures, 1, "released");
+    native?.(widget, 1);
+};
+
+const isPointerPressable = (target: PointerTarget): boolean => target.native !== null || target.gestures.length > 0;
+
 const applyPointerInput = (widget: Gtk.Widget, state: UserEventState, input: PointerInput): void => {
-    const controllers = getOrCreateControllers(widget, Gtk.GestureClick);
+    const target = pointerTargetFor(widget);
 
     if (CLICK_INPUTS.has(input)) {
-        emitPress(widget, controllers, 1);
-        emitRelease(widget, controllers, 1);
+        pressPointer(target);
+        releasePointer(target);
         state.isMouseLeftDown = false;
 
         return;
     }
 
-    if (PRESS_INPUTS.has(input) && !state.isMouseLeftDown) {
-        emitPress(widget, controllers, 1);
+    if (PRESS_INPUTS.has(input) && !state.isMouseLeftDown && isPointerPressable(target)) {
+        pressPointer(target);
         state.isMouseLeftDown = true;
 
         return;
     }
 
     if (RELEASE_INPUTS.has(input) && state.isMouseLeftDown) {
-        emitRelease(widget, controllers, 1);
+        releasePointer(target);
         state.isMouseLeftDown = false;
     }
 };