@gtkx/testing 0.21.0 → 1.0.0-rc.2

package/src/user-event/keyboard.ts

@@ -0,0 +1,290 @@
+import * as Gdk from "@gtkx/gi/gdk";
+import * as Gtk from "@gtkx/gi/gtk";
+import type { UserEventState } from "./state.js";
+import { getEditableDelegate } from "../editable.js";
+import { fireEvent } from "../fire-event.js";
+import { getOrCreateControllers } from "./controller.js";
+import { wrapEvent } from "./event-wrapper.js";
+
+/** Options for {@link tab}: when `shift` is set, move focus backward instead of forward. */
+type TabOptions = {
+    shift?: boolean;
+};
+
+type KeyAction = { keyval: number; press: boolean };
+type ParseStep = { actions: KeyAction[]; next: number };
+
+const KEY_MAP: Record<string, number> = {
+    Enter: Gdk.KEY_Return,
+    Tab: Gdk.KEY_Tab,
+    Escape: Gdk.KEY_Escape,
+    Backspace: Gdk.KEY_BackSpace,
+    Delete: Gdk.KEY_Delete,
+    ArrowUp: Gdk.KEY_Up,
+    ArrowDown: Gdk.KEY_Down,
+    ArrowLeft: Gdk.KEY_Left,
+    ArrowRight: Gdk.KEY_Right,
+    Home: Gdk.KEY_Home,
+    End: Gdk.KEY_End,
+    PageUp: Gdk.KEY_Page_Up,
+    PageDown: Gdk.KEY_Page_Down,
+    Space: Gdk.KEY_space,
+    Shift: Gdk.KEY_Shift_L,
+    Control: Gdk.KEY_Control_L,
+    Alt: Gdk.KEY_Alt_L,
+    Meta: Gdk.KEY_Meta_L,
+    F1: Gdk.KEY_F1,
+    F2: Gdk.KEY_F2,
+    F3: Gdk.KEY_F3,
+    F4: Gdk.KEY_F4,
+    F5: Gdk.KEY_F5,
+    F6: Gdk.KEY_F6,
+    F7: Gdk.KEY_F7,
+    F8: Gdk.KEY_F8,
+    F9: Gdk.KEY_F9,
+    F10: Gdk.KEY_F10,
+    F11: Gdk.KEY_F11,
+    F12: Gdk.KEY_F12,
+};
+
+const MODIFIER_KEYVAL_TO_MASK: Record<number, number> = {
+    [Gdk.KEY_Shift_L]: Gdk.ModifierType.SHIFT_MASK,
+    [Gdk.KEY_Shift_R]: Gdk.ModifierType.SHIFT_MASK,
+    [Gdk.KEY_Control_L]: Gdk.ModifierType.CONTROL_MASK,
+    [Gdk.KEY_Control_R]: Gdk.ModifierType.CONTROL_MASK,
+    [Gdk.KEY_Alt_L]: Gdk.ModifierType.ALT_MASK,
+    [Gdk.KEY_Alt_R]: Gdk.ModifierType.ALT_MASK,
+    [Gdk.KEY_Meta_L]: Gdk.ModifierType.META_MASK,
+    [Gdk.KEY_Meta_R]: Gdk.ModifierType.META_MASK,
+};
+
+const tab = (widget: Gtk.Widget, options?: TabOptions): Promise<void> =>
+    wrapEvent(widget, () => {
+        const direction = options?.shift ? Gtk.DirectionType.TAB_BACKWARD : Gtk.DirectionType.TAB_FORWARD;
+        const root = widget.getRoot();
+
+        if (root) {
+            root.childFocus(direction);
+        }
+    });
+
+const parseKeyToken = (token: string): { keyval: number; press: boolean; release: boolean } => {
+    let keyName = token;
+    let isPress = true;
+    let isRelease = true;
+
+    if (keyName.startsWith("/")) {
+        keyName = keyName.slice(1);
+        isPress = false;
+    } else if (keyName.endsWith(">")) {
+        keyName = keyName.slice(0, -1);
+        isRelease = false;
+    }
+
+    const keyval = KEY_MAP[keyName];
+
+    if (keyval === undefined) {
+        throw new Error(`Unknown key: {${keyName}}`);
+    }
+
+    return { keyval, press: isPress, release: isRelease };
+};
+
+const parseCharAt = (input: string, i: number): ParseStep => {
+    const keyval = input.codePointAt(i) ?? 0;
+
+    return {
+        actions: [
+            { keyval, press: true },
+            { keyval, press: false },
+        ],
+        next: i + 1,
+    };
+};
+
+const parseBraceAt = (input: string, i: number): ParseStep | null => {
+    const endBrace = input.indexOf("}", i);
+
+    if (endBrace === -1) {
+        return null;
+    }
+
+    const { keyval, press, release } = parseKeyToken(input.slice(i + 1, endBrace));
+    const actions: KeyAction[] = [];
+
+    if (press) {
+        actions.push({ keyval, press: true });
+    }
+
+    if (release) {
+        actions.push({ keyval, press: false });
+    }
+
+    return { actions, next: endBrace + 1 };
+};
+
+const parseStepAt = (input: string, i: number): ParseStep | null =>
+    input[i] === "{" ? parseBraceAt(input, i) : parseCharAt(input, i);
+
+const parseKeyboardInput = (input: string): KeyAction[] => {
+    const actions: KeyAction[] = [];
+    let i = 0;
+
+    while (i < input.length) {
+        const step = parseStepAt(input, i);
+
+        if (step === null) {
+            break;
+        }
+
+        actions.push(...step.actions);
+        i = step.next;
+    }
+
+    return actions;
+};
+
+const updateModifierState = (state: UserEventState, action: KeyAction): void => {
+    const mask = MODIFIER_KEYVAL_TO_MASK[action.keyval];
+
+    if (!mask) {
+        return;
+    }
+
+    if (action.press) {
+        state.modifierState |= mask;
+    } else {
+        state.modifierState &= ~mask;
+    }
+};
+
+const isTriggerMatch = (
+    trigger: Gtk.ShortcutTrigger | null,
+    keyval: number,
+    modifiers: Gdk.ModifierType,
+): boolean => {
+    if (trigger instanceof Gtk.KeyvalTrigger) {
+        return trigger.getKeyval() === keyval && trigger.getModifiers() === modifiers;
+    }
+
+    if (trigger instanceof Gtk.AlternativeTrigger) {
+        return (
+            isTriggerMatch(trigger.getFirst(), keyval, modifiers) ||
+            isTriggerMatch(trigger.getSecond(), keyval, modifiers)
+        );
+    }
+
+    return false;
+};
+
+const didActivateShortcut = (
+    shortcut: Gtk.Shortcut,
+    widget: Gtk.Widget,
+    keyval: number,
+    modifiers: Gdk.ModifierType,
+): boolean => {
+    if (!isTriggerMatch(shortcut.getTrigger(), keyval, modifiers)) {
+        return false;
+    }
+
+    const action = shortcut.getAction();
+
+    if (action instanceof Gtk.SignalAction && action.getSignalName() === "move-focus") {
+        return false;
+    }
+
+    return action?.activate(0 as Gtk.ShortcutActionFlags, widget, shortcut.getArguments()) ?? false;
+};
+
+const didActivateMatchingShortcut = (
+    controller: Gtk.ShortcutController,
+    widget: Gtk.Widget,
+    keyval: number,
+    modifiers: number,
+): boolean => {
+    const count = controller.getNItems();
+
+    for (let j = 0; j < count; j++) {
+        const shortcut = controller.getItem(j);
+
+        if (!(shortcut instanceof Gtk.Shortcut)) {
+            continue;
+        }
+
+        if (didActivateShortcut(shortcut, widget, keyval, modifiers)) {
+            return true;
+        }
+    }
+
+    return false;
+};
+
+const didDispatchShortcutsOnWidget = (widget: Gtk.Widget, keyval: number, modifiers: number): boolean => {
+    const controllers = widget.observeControllers();
+
+    for (let i = 0; i < controllers.getNItems(); i++) {
+        const controller = controllers.getItem(i);
+
+        if (
+            controller instanceof Gtk.ShortcutController &&
+            didActivateMatchingShortcut(controller, widget, keyval, modifiers)
+        ) {
+            return true;
+        }
+    }
+
+    return false;
+};
+
+const didDispatchShortcuts = (widget: Gtk.Widget, keyval: number, modifiers: number): boolean => {
+    const delegate = getEditableDelegate(widget);
+
+    if (delegate && didDispatchShortcutsOnWidget(delegate, keyval, modifiers)) {
+        return true;
+    }
+
+    for (let current: Gtk.Widget | null = widget; current; current = current.getParent()) {
+        if (didDispatchShortcutsOnWidget(current, keyval, modifiers)) {
+            return true;
+        }
+    }
+
+    return false;
+};
+
+const handleKeyPress = async (widget: Gtk.Widget, keyval: number, modifiers: number): Promise<void> => {
+    const isHandled = didDispatchShortcuts(widget, keyval, modifiers);
+
+    if (!isHandled && keyval === Gdk.KEY_Return && widget instanceof Gtk.Editable) {
+        await fireEvent(widget, "activate");
+    }
+};
+
+const applyKeyAction = async (
+    widget: Gtk.Widget,
+    controllers: Gtk.EventControllerKey[],
+    state: UserEventState,
+    action: KeyAction,
+): Promise<void> => {
+    updateModifierState(state, action);
+    const signalName = action.press ? "key-pressed" : "key-released";
+
+    for (const controller of controllers) {
+        controller.emit(signalName, action.keyval, 0, state.modifierState);
+    }
+
+    if (action.press) {
+        await handleKeyPress(widget, action.keyval, state.modifierState);
+    }
+};
+
+const keyboard = (state: UserEventState, widget: Gtk.Widget, input: string): Promise<void> =>
+    wrapEvent(widget, async () => {
+        const controllers = getOrCreateControllers(widget, Gtk.EventControllerKey);
+
+        for (const action of parseKeyboardInput(input)) {
+            await applyKeyAction(widget, controllers, state, action);
+        }
+    });
+
+export { tab, keyboard, type TabOptions };

package/src/user-event/pointer.ts

@@ -0,0 +1,46 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import type { UserEventState } from "./state.js";
+import { emitPress, emitRelease } from "./click.js";
+import { getOrCreateControllers } from "./controller.js";
+import { wrapEvent } from "./event-wrapper.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]";
+
+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 applyPointerInput = (widget: Gtk.Widget, state: UserEventState, input: PointerInput): void => {
+    const controllers = getOrCreateControllers(widget, Gtk.GestureClick);
+
+    if (CLICK_INPUTS.has(input)) {
+        emitPress(widget, controllers, 1);
+        emitRelease(widget, controllers, 1);
+        state.mouseLeftDown = false;
+
+        return;
+    }
+
+    if (PRESS_INPUTS.has(input) && !state.mouseLeftDown) {
+        emitPress(widget, controllers, 1);
+        state.mouseLeftDown = true;
+
+        return;
+    }
+
+    if (RELEASE_INPUTS.has(input) && state.mouseLeftDown) {
+        emitRelease(widget, controllers, 1);
+        state.mouseLeftDown = false;
+    }
+};
+
+const pointer = (state: UserEventState, widget: Gtk.Widget, input: PointerInput): Promise<void> =>
+    wrapEvent(widget, () => {
+        applyPointerInput(widget, state, input);
+    });
+
+export { pointer, type PointerInput };

package/src/user-event/selection.ts

@@ -0,0 +1,159 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { formatRoleList } from "../role-helpers.js";
+import { wrapEvent } from "./event-wrapper.js";
+
+type CollectionWidget = Gtk.ListView | Gtk.GridView | Gtk.ColumnView;
+type ListBoxRowAction = (listBox: Gtk.ListBox, row: Gtk.ListBoxRow) => void;
+
+const SELECTABLE_ROLES: Set<Gtk.AccessibleRole> = new Set([Gtk.AccessibleRole.COMBO_BOX, Gtk.AccessibleRole.LIST]);
+
+const isSelectable = (widget: Gtk.Widget): boolean => {
+    return SELECTABLE_ROLES.has(widget.getAccessibleRole());
+};
+
+const selectListViewItems = (
+    selectionModel: Gtk.SelectionModel,
+    positions: number[],
+    isExclusive: boolean,
+): void => {
+    if (positions.length === 0) {
+        selectionModel.unselectRange(0, selectionModel.getNItems());
+
+        return;
+    }
+
+    const [first] = positions;
+
+    if (isExclusive && first !== undefined && positions.length === 1) {
+        selectionModel.selectItem(first, true);
+
+        return;
+    }
+
+    const nItems = selectionModel.getNItems();
+    const selected = Gtk.Bitset.newEmpty();
+    const mask = Gtk.Bitset.newRange(0, nItems);
+
+    for (const pos of positions) {
+        selected.add(pos);
+    }
+
+    selectionModel.setSelection(selected, mask);
+};
+
+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 [selection] = valueArray;
+
+    if (selection === undefined) {
+        return;
+    }
+
+    if (widget instanceof Gtk.DropDown) {
+        widget.setSelected(selection);
+    } else if (widget instanceof Gtk.ComboBox) {
+        widget.setActive(selection);
+    }
+};
+
+const selectListBoxRow = (listBox: Gtk.ListBox, row: Gtk.ListBoxRow): void => {
+    listBox.selectRow(row);
+    row.activate();
+};
+
+const unselectListBoxRow = (listBox: Gtk.ListBox, row: Gtk.ListBoxRow): void => {
+    listBox.unselectRow(row);
+};
+
+const applyListBoxRows = (listBox: Gtk.ListBox, valueArray: number[], apply: ListBoxRowAction): void => {
+    for (const value of valueArray) {
+        const row = listBox.getRowAtIndex(value);
+
+        if (!row) {
+            continue;
+        }
+
+        apply(listBox, row);
+    }
+};
+
+const requireSelectionModel = (
+    widget: CollectionWidget,
+    verb: string,
+): Gtk.SelectionModel => {
+    const selectionModel = widget.getModel();
+
+    if (selectionModel === null) {
+        throw new Error(`Cannot ${verb} options: list view has no selection model`);
+    }
+
+    return selectionModel;
+};
+
+const selectInListView = (widget: CollectionWidget, valueArray: number[]): void => {
+    const selectionModel = requireSelectionModel(widget, "select");
+    const isMultiSelection = selectionModel instanceof Gtk.MultiSelection;
+    selectListViewItems(selectionModel, valueArray, !isMultiSelection);
+};
+
+const selectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
+    if (!isSelectable(widget)) {
+        throw new Error(`Cannot select options: expected selectable widget (${formatRoleList(SELECTABLE_ROLES)})`);
+    }
+
+    const role = widget.getAccessibleRole();
+
+    if (role === Gtk.AccessibleRole.COMBO_BOX) {
+        selectComboBoxOption(widget, valueArray);
+    } else if (widget instanceof Gtk.ListBox) {
+        applyListBoxRows(widget, valueArray, selectListBoxRow);
+    }
+};
+
+const runSelectionEvent = (
+    widget: Gtk.Widget,
+    values: number | number[],
+    inListView: (view: Gtk.ListView | Gtk.GridView | Gtk.ColumnView, valueArray: number[]) => void,
+    byRole: (widget: Gtk.Widget, valueArray: number[]) => void,
+): Promise<void> =>
+    wrapEvent(widget, () => {
+        const valueArray = Array.isArray(values) ? values : [values];
+
+        if (isListView(widget)) {
+            inListView(widget, valueArray);
+
+            return;
+        }
+
+        byRole(widget, valueArray);
+    });
+
+const selectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
+    runSelectionEvent(widget, values, selectInListView, selectByRole);
+
+const deselectInListView = (widget: Gtk.ListView | Gtk.GridView | Gtk.ColumnView, valueArray: number[]): void => {
+    const selectionModel = requireSelectionModel(widget, "deselect");
+
+    for (const pos of valueArray) {
+        selectionModel.unselectItem(pos);
+    }
+};
+
+const deselectByRole = (widget: Gtk.Widget, valueArray: number[]): void => {
+    if (!(widget instanceof Gtk.ListBox)) {
+        throw new TypeError("Cannot deselect options: only ListBox supports deselection");
+    }
+
+    applyListBoxRows(widget, valueArray, unselectListBoxRow);
+};
+
+const deselectOptions = (widget: Gtk.Widget, values: number | number[]): Promise<void> =>
+    runSelectionEvent(widget, values, deselectInListView, deselectByRole);
+
+export { selectOptions, deselectOptions };

package/src/user-event/state.ts

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

package/src/user-event/text.ts

@@ -0,0 +1,172 @@
+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 { formatRoleList } from "../role-helpers.js";
+import { wrapEvent } from "./event-wrapper.js";
+
+/** Options for {@link type}. */
+type TypeOptions = {
+    /** Do not focus the widget before typing. */
+    skipClick?: 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). */
+    initialSelectionEnd?: number | undefined;
+};
+
+const EDITABLE_REQUIRED = `expected editable widget (${formatRoleList(EDITABLE_ROLES)})`;
+
+const insertEditableText = (widget: EditableTarget, text: string): void => {
+    if (widget instanceof Gtk.TextView) {
+        widget.emit("insert-at-cursor", text);
+
+        return;
+    }
+
+    const target = getEditableDelegate(widget) ?? widget;
+
+    if (target instanceof Gtk.Text) {
+        target.emit("insert-at-cursor", text);
+
+        return;
+    }
+
+    const position = widget.getPosition();
+    const newPosition = widget.insertText(text, text.length, position);
+    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 deleteSelection = (widget: EditableTarget): void => {
+    if (widget instanceof Gtk.TextView) {
+        widget.getBuffer().deleteSelection(false, true);
+
+        return;
+    }
+
+    widget.deleteSelection();
+};
+
+const setEditableText = (widget: EditableTarget, text: string): void => {
+    if (widget instanceof Gtk.TextView) {
+        widget.getBuffer().setText(text, text.length);
+
+        return;
+    }
+
+    widget.setText(text);
+};
+
+const applyTextViewSelection = (widget: Gtk.TextView, start: number, end: number): void => {
+    const buffer = widget.getBuffer();
+    buffer.selectRange(buffer.getIterAtOffset(start), buffer.getIterAtOffset(end));
+
+    if (end !== start) {
+        deleteSelection(widget);
+    }
+};
+
+const applyEditableSelection = (widget: Gtk.Editable, start: number, end: number): void => {
+    widget.selectRegion(start, end);
+
+    if (end !== start) {
+        widget.deleteSelection();
+    }
+
+    widget.setPosition(start);
+};
+
+const applyInitialSelection = (widget: EditableTarget, options: TypeOptions): void => {
+    if (options.initialSelectionStart === undefined) {
+        return;
+    }
+
+    const start = options.initialSelectionStart;
+    const end = options.initialSelectionEnd ?? start;
+
+    if (widget instanceof Gtk.TextView) {
+        applyTextViewSelection(widget, start, end);
+
+        return;
+    }
+
+    applyEditableSelection(widget, start, end);
+};
+
+const writeClipboardText = (widget: Gtk.Widget, text: string): void => {
+    const value = GObject.buildValue(GObject.TYPE_STRING, (v) => {
+        v.setString(text);
+    });
+
+    widget.getClipboard().set(value);
+};
+
+const resetClipboard = (): void => {
+    Gdk.Display.getDefault()?.getClipboard().setContent(null);
+};
+
+const runEditableEvent = (
+    widget: Gtk.Widget,
+    failure: string,
+    action: (editable: EditableTarget) => void,
+): Promise<void> =>
+    wrapEvent(widget, () => {
+        if (!isEditable(widget)) {
+            throw new Error(`${failure}: ${EDITABLE_REQUIRED}`);
+        }
+
+        action(widget);
+    });
+
+const type = (widget: Gtk.Widget, text: string, options?: TypeOptions): Promise<void> =>
+    runEditableEvent(widget, "Cannot type into element", (editable) => {
+        if (!options?.skipClick) {
+            editable.grabFocus();
+        }
+
+        applyInitialSelection(editable, options ?? {});
+        insertEditableText(editable, text);
+    });
+
+const clear = (widget: Gtk.Widget): Promise<void> =>
+    runEditableEvent(widget, "Cannot clear element", (editable) => {
+        setEditableText(editable, "");
+    });
+
+const copy = (widget: Gtk.Widget): Promise<void> =>
+    runEditableEvent(widget, "Cannot copy", (editable) => {
+        writeClipboardText(editable, readSelection(editable));
+    });
+
+const cut = (widget: Gtk.Widget): Promise<void> =>
+    runEditableEvent(widget, "Cannot cut", (editable) => {
+        writeClipboardText(editable, readSelection(editable));
+        deleteSelection(editable);
+    });
+
+const paste = async (widget: Gtk.Widget, text?: string): Promise<void> => {
+    if (!isEditable(widget)) {
+        throw new Error(`Cannot paste: ${EDITABLE_REQUIRED}`);
+    }
+
+    const content = text ?? (await widget.getClipboard().readTextAsync(null)) ?? "";
+
+    await wrapEvent(widget, () => {
+        insertEditableText(widget, content);
+    });
+};
+
+export { resetClipboard, type, clear, copy, cut, paste, type TypeOptions };