@gtkx/testing 1.0.0-rc.3 → 1.0.0

package/src/user-event/selection.ts

@@ -1,11 +1,23 @@
 import * as Gtk from "@gtkx/gi/gtk";
 import { formatRoleList } from "../role-helpers.js";
+import { getCallableMethod } from "../widget-getters.js";
 import { wrapEvent } from "./event-wrapper.js";
+import {
+    getChildAtIndex,
+    hasIndexedChildren,
+    isChildSelected,
+    selectContainerChild,
+    unselectContainerChild,
+} from "./indexed-children.js";
 
 type CollectionWidget = Gtk.ListView | Gtk.GridView | Gtk.ColumnView;
-type ListBoxRowAction = (listBox: Gtk.ListBox, row: Gtk.ListBoxRow) => void;
+type IndexedChildAction = (container: Gtk.Widget, child: Gtk.Widget) => void;
 
-const SELECTABLE_ROLES: Set<Gtk.AccessibleRole> = new Set([Gtk.AccessibleRole.COMBO_BOX, Gtk.AccessibleRole.LIST]);
+const SELECTABLE_ROLES: Set<Gtk.AccessibleRole> = new Set([
+    Gtk.AccessibleRole.COMBO_BOX,
+    Gtk.AccessibleRole.GRID,
+    Gtk.AccessibleRole.LIST,
+]);
 
 const isSelectable = (widget: Gtk.Widget): boolean => {
     return SELECTABLE_ROLES.has(widget.getAccessibleRole());
@@ -44,42 +56,40 @@ const selectListViewItems = (
 const isListView = (widget: Gtk.Widget): widget is CollectionWidget =>
     widget instanceof Gtk.ListView || widget instanceof Gtk.GridView || widget instanceof Gtk.ColumnView;
 
-const selectComboBoxOption = (widget: Gtk.Widget, valueArray: number[]): void => {
-    if (valueArray.length > 1) {
-        throw new Error("Cannot select multiple options: ComboBox only supports single selection");
-    }
+const getIndexSelector = (widget: Gtk.Widget): ((position: number) => void) | null =>
+    getCallableMethod<[number], unknown>(widget, "setSelected");
 
-    const [selection] = valueArray;
+const selectDropDownOption = (widget: Gtk.Widget, valueArray: number[]): void => {
+    const setSelected = getIndexSelector(widget);
 
-    if (selection === undefined) {
-        return;
+    if (!setSelected) {
+        throw new TypeError("Cannot select options: the COMBO_BOX role needs a widget exposing setSelected");
     }
 
-    if (widget instanceof Gtk.DropDown) {
-        widget.setSelected(selection);
-    } else if (widget instanceof Gtk.ComboBox) {
-        widget.setActive(selection);
+    if (valueArray.length > 1) {
+        throw new Error("Cannot select multiple options: a drop-down only supports single selection");
     }
-};
 
-const selectListBoxRow = (listBox: Gtk.ListBox, row: Gtk.ListBoxRow): void => {
-    listBox.selectRow(row);
-    row.activate();
+    const [selection] = valueArray;
+
+    if (selection !== undefined) {
+        setSelected(selection);
+    }
 };
 
-const unselectListBoxRow = (listBox: Gtk.ListBox, row: Gtk.ListBoxRow): void => {
-    listBox.unselectRow(row);
+const unselectChildRow = (container: Gtk.Widget, child: Gtk.Widget): void => {
+    if (isChildSelected(child)) {
+        unselectContainerChild(container, child);
+    }
 };
 
-const applyListBoxRows = (listBox: Gtk.ListBox, valueArray: number[], apply: ListBoxRowAction): void => {
+const applyIndexedChildren = (widget: Gtk.Widget, valueArray: number[], apply: IndexedChildAction): void => {
     for (const value of valueArray) {
-        const row = listBox.getRowAtIndex(value);
+        const child = getChildAtIndex(widget, value);
 
-        if (!row) {
-            continue;
+        if (child) {
+            apply(widget, child);
         }
-
-        apply(listBox, row);
     }
 };
 
@@ -102,18 +112,29 @@ const selectInListView = (widget: CollectionWidget, valueArray: number[]): void
     selectListViewItems(selectionModel, valueArray, !isMultiSelection);
 };
 
-const selectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
+const requireSelectableRole = (widget: Gtk.Widget, verb: string): void => {
     if (!isSelectable(widget)) {
-        throw new Error(`Cannot select options: expected selectable widget (${formatRoleList(SELECTABLE_ROLES)})`);
+        throw new Error(
+            `Cannot ${verb} options: expected selectable widget (${formatRoleList(SELECTABLE_ROLES)})`,
+        );
     }
+};
 
+const selectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
+    requireSelectableRole(widget, "select");
     const role = widget.getAccessibleRole();
 
     if (role === Gtk.AccessibleRole.COMBO_BOX) {
-        selectComboBoxOption(widget, valueArray);
-    } else if (widget instanceof Gtk.ListBox) {
-        applyListBoxRows(widget, valueArray, selectListBoxRow);
+        selectDropDownOption(widget, valueArray);
+
+        return;
+    }
+
+    if (!hasIndexedChildren(widget)) {
+        throw new TypeError("Cannot select options: the widget exposes no children to select by index");
     }
+
+    applyIndexedChildren(widget, valueArray, selectContainerChild);
 };
 
 const runSelectionEvent = (
@@ -134,6 +155,16 @@ 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);
 
@@ -146,13 +177,23 @@ const deselectInListView = (widget: Gtk.ListView | Gtk.GridView | Gtk.ColumnView
 };
 
 const deselectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
-    if (!(widget instanceof Gtk.ListBox)) {
-        throw new TypeError("Cannot deselect options: only ListBox supports deselection");
+    requireSelectableRole(widget, "deselect");
+
+    if (!hasIndexedChildren(widget)) {
+        throw new TypeError("Cannot deselect options: the widget exposes no children to deselect by index");
     }
 
-    applyListBoxRows(widget, valueArray, unselectListBoxRow);
+    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);
 

package/src/user-event/state.ts

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

package/src/user-event/text.ts

@@ -1,14 +1,21 @@
 import * as Gdk from "@gtkx/gi/gdk";
 import * as GObject from "@gtkx/gi/gobject";
 import * as Gtk from "@gtkx/gi/gtk";
-import { EDITABLE_ROLES, type EditableTarget, getEditableDelegate, isEditable } from "../editable.js";
+import { EDITABLE_ROLES, type EditableTarget, getEditableDelegate, isEditable, readEditableText } from "../editable.js";
 import { formatRoleList } from "../role-helpers.js";
+import { getWidgetSelection } from "../widget-accessible-properties.js";
+import { callBooleanGetter } from "../widget-getters.js";
 import { wrapEvent } from "./event-wrapper.js";
 
-/** Options for {@link type}. */
+type SignalWatchTarget = {
+    on(signal: string, handler: (...args: unknown[]) => unknown, isAfter?: boolean): unknown;
+    off(signal: string, handler: (...args: unknown[]) => unknown): unknown;
+};
+
+/** Options for `userEvent.type`. */
 type TypeOptions = {
-    /** Do not focus the widget before typing. */
-    skipClick?: boolean | undefined;
+    /** Focus the widget before typing; defaults to true. */
+    shouldFocus?: boolean | undefined;
     /** Select from this offset before typing, replacing the selected range with the typed text. */
     initialSelectionStart?: number | undefined;
     /** End offset of the initial selection (defaults to the start offset). */
@@ -16,6 +23,7 @@ type TypeOptions = {
 };
 
 const EDITABLE_REQUIRED = `expected editable widget (${formatRoleList(EDITABLE_ROLES)})`;
+const CLEAR_REFUSED = "Cannot clear element: the widget refuses to delete part of its text";
 
 const insertEditableText = (widget: EditableTarget, text: string): void => {
     if (widget instanceof Gtk.TextView) {
@@ -37,18 +45,7 @@ const insertEditableText = (widget: EditableTarget, text: string): void => {
     widget.setPosition(newPosition);
 };
 
-const readSelection = (widget: EditableTarget): string => {
-    if (widget instanceof Gtk.TextView) {
-        const buffer = widget.getBuffer();
-        const [hasSelection, start, end] = buffer.getSelectionBounds();
-
-        return hasSelection ? buffer.getText(start, end, true) : "";
-    }
-
-    const [hasSelection, start, end] = widget.getSelectionBounds();
-
-    return hasSelection ? widget.getChars(start, end) : "";
-};
+const readSelection = (widget: EditableTarget): string => getWidgetSelection(widget) ?? "";
 
 const deleteSelection = (widget: EditableTarget): void => {
     if (widget instanceof Gtk.TextView) {
@@ -60,14 +57,15 @@ const deleteSelection = (widget: EditableTarget): void => {
     widget.deleteSelection();
 };
 
-const setEditableText = (widget: EditableTarget, text: string): void => {
+const deleteAllText = (widget: EditableTarget): void => {
     if (widget instanceof Gtk.TextView) {
-        widget.getBuffer().setText(text, text.length);
+        const buffer = widget.getBuffer();
+        buffer.deleteInteractive(buffer.getStartIter(), buffer.getEndIter(), widget.getEditable());
 
         return;
     }
 
-    widget.setText(text);
+    widget.deleteText(0, -1);
 };
 
 const applyTextViewSelection = (widget: Gtk.TextView, start: number, end: number): void => {
@@ -131,9 +129,15 @@ const runEditableEvent = (
         action(widget);
     });
 
+/**
+ * Focuses the widget unless `shouldFocus` is false, applies any initial selection, and inserts the text
+ * at the cursor.
+ *
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ */
 const type = (widget: Gtk.Widget, text: string, options?: TypeOptions): Promise<void> =>
     runEditableEvent(widget, "Cannot type into element", (editable) => {
-        if (!options?.skipClick) {
+        if (options?.shouldFocus ?? true) {
             editable.grabFocus();
         }
 
@@ -141,22 +145,116 @@ const type = (widget: Gtk.Widget, text: string, options?: TypeOptions): Promise<
         insertEditableText(editable, text);
     });
 
-const clear = (widget: Gtk.Widget): Promise<void> =>
-    runEditableEvent(widget, "Cannot clear element", (editable) => {
-        setEditableText(editable, "");
+const isWidgetEditable = (widget: Gtk.Widget): boolean => callBooleanGetter(widget, "getEditable") ?? true;
+
+const hasNonEditableChar = (iter: Gtk.TextIter, isDefaultEditable: boolean): boolean => {
+    while (!iter.isEnd()) {
+        if (!iter.editable(isDefaultEditable)) {
+            return true;
+        }
+
+        if (!iter.forwardChar()) {
+            return false;
+        }
+    }
+
+    return false;
+};
+
+const hasProtectedText = (widget: EditableTarget): boolean =>
+    widget instanceof Gtk.TextView && hasNonEditableChar(widget.getBuffer().getStartIter(), widget.getEditable());
+
+const requireClearableText = (editable: EditableTarget): void => {
+    if (!isWidgetEditable(editable)) {
+        throw new Error("Cannot clear element: the widget is not editable");
+    }
+
+    if (hasProtectedText(editable)) {
+        throw new Error(CLEAR_REFUSED);
+    }
+};
+
+const deletionSignalFor = (widget: EditableTarget): [SignalWatchTarget, string] =>
+    widget instanceof Gtk.TextView ? [widget.getBuffer(), "delete-range"] : [widget, "delete-text"];
+
+const isDeletionApplied = (emitter: SignalWatchTarget, signal: string, apply: () => void): boolean => {
+    let isApplied = false;
+
+    const watch = (): void => {
+        isApplied = true;
+    };
+
+    emitter.on(signal, watch, true);
+
+    try {
+        apply();
+    } finally {
+        emitter.off(signal, watch);
+    }
+
+    return isApplied;
+};
+
+const didDeleteAllText = (widget: EditableTarget): boolean => {
+    const [emitter, signal] = deletionSignalFor(widget);
+
+    return isDeletionApplied(emitter, signal, () => {
+        deleteAllText(widget);
     });
+};
+
+const clearEditable = (editable: EditableTarget): void => {
+    requireClearableText(editable);
+    editable.grabFocus();
+
+    if (readEditableText(editable) === "") {
+        return;
+    }
+
+    if (!didDeleteAllText(editable)) {
+        throw new Error(CLEAR_REFUSED);
+    }
+};
+
+/**
+ * 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.
+ */
+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.
+ */
 const copy = (widget: Gtk.Widget): Promise<void> =>
     runEditableEvent(widget, "Cannot copy", (editable) => {
         writeClipboardText(editable, readSelection(editable));
     });
 
+/**
+ * Writes an editable widget's selected text to its clipboard, then deletes that selection.
+ *
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ */
 const cut = (widget: Gtk.Widget): Promise<void> =>
     runEditableEvent(widget, "Cannot cut", (editable) => {
         writeClipboardText(editable, readSelection(editable));
         deleteSelection(editable);
     });
 
+/**
+ * Inserts the given text at an editable widget's cursor, reading the clipboard instead when no text
+ * is given.
+ *
+ * @throws When the widget is neither a Gtk.Editable nor a Gtk.TextView.
+ */
 const paste = async (widget: Gtk.Widget, text?: string): Promise<void> => {
     if (!isEditable(widget)) {
         throw new Error(`Cannot paste: ${EDITABLE_REQUIRED}`);

package/src/wait-for.ts

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