npm - @gtkx/testing - Versions diffs - 1.0.0-rc.4 → 1.1.0 - Mend

@gtkx/testing 1.0.0-rc.4 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (212) hide show

package/README.md +5 -5
package/dist/accessible-native.d.ts +16 -0
package/dist/accessible-native.d.ts.map +1 -0
package/dist/accessible-native.js +206 -0
package/dist/accessible-native.js.map +1 -0
package/dist/act.d.ts +1 -3
package/dist/act.d.ts.map +1 -1
package/dist/act.js +1 -1
package/dist/act.js.map +1 -1
package/dist/build-queries.d.ts +27 -10
package/dist/build-queries.d.ts.map +1 -1
package/dist/build-queries.js +22 -24
package/dist/build-queries.js.map +1 -1
package/dist/cleanup-registry.d.ts +1 -1
package/dist/cleanup-registry.d.ts.map +1 -1
package/dist/cleanup-registry.js.map +1 -1
package/dist/config.d.ts +8 -1
package/dist/config.d.ts.map +1 -1
package/dist/config.js +1 -0
package/dist/config.js.map +1 -1
package/dist/errors.d.ts +10 -1
package/dist/errors.d.ts.map +1 -1
package/dist/errors.js +10 -1
package/dist/errors.js.map +1 -1
package/dist/fire-event.d.ts +35 -6
package/dist/fire-event.d.ts.map +1 -1
package/dist/fire-event.js +23 -7
package/dist/fire-event.js.map +1 -1
package/dist/frame-sync.d.ts +3 -2
package/dist/frame-sync.d.ts.map +1 -1
package/dist/frame-sync.js +19 -9
package/dist/frame-sync.js.map +1 -1
package/dist/harness-window.d.ts +5 -0
package/dist/harness-window.d.ts.map +1 -0
package/dist/harness-window.js +17 -0
package/dist/harness-window.js.map +1 -0
package/dist/index.d.ts +14 -7
package/dist/index.d.ts.map +1 -1
package/dist/index.js +9 -5
package/dist/index.js.map +1 -1
package/dist/internal.d.ts +5 -0
package/dist/internal.d.ts.map +1 -0
package/dist/internal.js +5 -0
package/dist/internal.js.map +1 -0
package/dist/matchers.d.ts +88 -46
package/dist/matchers.d.ts.map +1 -1
package/dist/matchers.js +178 -20
package/dist/matchers.js.map +1 -1
package/dist/pretty-format.d.ts +2 -0
package/dist/pretty-format.d.ts.map +1 -0
package/dist/pretty-format.js +2 -0
package/dist/pretty-format.js.map +1 -0
package/dist/pretty-widget.d.ts +5 -2
package/dist/pretty-widget.d.ts.map +1 -1
package/dist/pretty-widget.js +75 -57
package/dist/pretty-widget.js.map +1 -1
package/dist/production.d.ts +8 -0
package/dist/production.d.ts.map +1 -0
package/dist/production.js +34 -0
package/dist/production.js.map +1 -0
package/dist/queries.d.ts +98 -56
package/dist/queries.d.ts.map +1 -1
package/dist/queries.js +123 -83
package/dist/queries.js.map +1 -1
package/dist/query-helpers.d.ts +44 -0
package/dist/query-helpers.d.ts.map +1 -0
package/dist/query-helpers.js +57 -0
package/dist/query-helpers.js.map +1 -0
package/dist/render-children.d.ts +9 -0
package/dist/render-children.d.ts.map +1 -0
package/dist/render-children.js +11 -0
package/dist/render-children.js.map +1 -0
package/dist/render.d.ts +12 -1
package/dist/render.d.ts.map +1 -1
package/dist/render.js +52 -16
package/dist/render.js.map +1 -1
package/dist/role-helpers.d.ts +12 -3
package/dist/role-helpers.d.ts.map +1 -1
package/dist/role-helpers.js +15 -5
package/dist/role-helpers.js.map +1 -1
package/dist/role-naming.d.ts +5 -0
package/dist/role-naming.d.ts.map +1 -0
package/dist/role-naming.js +96 -0
package/dist/role-naming.js.map +1 -0
package/dist/screenshot.d.ts +12 -20
package/dist/screenshot.d.ts.map +1 -1
package/dist/screenshot.js +179 -93
package/dist/screenshot.js.map +1 -1
package/dist/timers.d.ts +9 -0
package/dist/timers.d.ts.map +1 -0
package/dist/timers.js +21 -0
package/dist/timers.js.map +1 -0
package/dist/traversal.d.ts +7 -1
package/dist/traversal.d.ts.map +1 -1
package/dist/traversal.js +40 -6
package/dist/traversal.js.map +1 -1
package/dist/types.d.ts +32 -15
package/dist/types.d.ts.map +1 -1
package/dist/types.js.map +1 -1
package/dist/user-event/adjustment.d.ts +3 -0
package/dist/user-event/adjustment.d.ts.map +1 -1
package/dist/user-event/adjustment.js +25 -3
package/dist/user-event/adjustment.js.map +1 -1
package/dist/user-event/click.d.ts +44 -8
package/dist/user-event/click.d.ts.map +1 -1
package/dist/user-event/click.js +176 -44
package/dist/user-event/click.js.map +1 -1
package/dist/user-event/column-header-click.d.ts +4 -0
package/dist/user-event/column-header-click.d.ts.map +1 -0
package/dist/user-event/column-header-click.js +55 -0
package/dist/user-event/column-header-click.js.map +1 -0
package/dist/user-event/event-wrapper.d.ts.map +1 -1
package/dist/user-event/event-wrapper.js +34 -20
package/dist/user-event/event-wrapper.js.map +1 -1
package/dist/user-event/index.d.ts +80 -13
package/dist/user-event/index.d.ts.map +1 -1
package/dist/user-event/index.js +44 -26
package/dist/user-event/index.js.map +1 -1
package/dist/user-event/indexed-children.d.ts +10 -0
package/dist/user-event/indexed-children.d.ts.map +1 -0
package/dist/user-event/indexed-children.js +50 -0
package/dist/user-event/indexed-children.js.map +1 -0
package/dist/user-event/keyboard.d.ts.map +1 -1
package/dist/user-event/keyboard.js +115 -31
package/dist/user-event/keyboard.js.map +1 -1
package/dist/user-event/list-row-click.d.ts +4 -0
package/dist/user-event/list-row-click.d.ts.map +1 -0
package/dist/user-event/list-row-click.js +38 -0
package/dist/user-event/list-row-click.js.map +1 -0
package/dist/user-event/native-click.d.ts +6 -0
package/dist/user-event/native-click.d.ts.map +1 -0
package/dist/user-event/native-click.js +36 -0
package/dist/user-event/native-click.js.map +1 -0
package/dist/user-event/notebook-tab-click.d.ts +5 -0
package/dist/user-event/notebook-tab-click.d.ts.map +1 -0
package/dist/user-event/notebook-tab-click.js +39 -0
package/dist/user-event/notebook-tab-click.js.map +1 -0
package/dist/user-event/pointer.d.ts +1 -1
package/dist/user-event/pointer.d.ts.map +1 -1
package/dist/user-event/pointer.js +33 -9
package/dist/user-event/pointer.js.map +1 -1
package/dist/user-event/selection.d.ts +11 -8
package/dist/user-event/selection.d.ts.map +1 -1
package/dist/user-event/selection.js +49 -38
package/dist/user-event/selection.js.map +1 -1
package/dist/user-event/text.d.ts +12 -5
package/dist/user-event/text.d.ts.map +1 -1
package/dist/user-event/text.js +151 -46
package/dist/user-event/text.js.map +1 -1
package/dist/wait-for.d.ts.map +1 -1
package/dist/wait-for.js +4 -3
package/dist/wait-for.js.map +1 -1
package/dist/widget-accessible-properties.d.ts +14 -26
package/dist/widget-accessible-properties.d.ts.map +1 -1
package/dist/widget-accessible-properties.js +135 -190
package/dist/widget-accessible-properties.js.map +1 -1
package/dist/widget-getters.d.ts +11 -0
package/dist/widget-getters.d.ts.map +1 -0
package/dist/widget-getters.js +46 -0
package/dist/widget-getters.js.map +1 -0
package/dist/window-state.d.ts +10 -0
package/dist/window-state.d.ts.map +1 -0
package/dist/window-state.js +41 -0
package/dist/window-state.js.map +1 -0
package/dist/within.d.ts +3 -2
package/dist/within.d.ts.map +1 -1
package/dist/within.js +3 -2
package/dist/within.js.map +1 -1
package/package.json +21 -8
package/src/accessible-native.ts +333 -0
package/src/act.ts +1 -1
package/src/build-queries.ts +47 -41
package/src/cleanup-registry.ts +1 -1
package/src/config.ts +10 -1
package/src/errors.ts +12 -1
package/src/fire-event.ts +61 -8
package/src/frame-sync.ts +30 -9
package/src/harness-window.ts +23 -0
package/src/index.ts +18 -11
package/src/internal.ts +12 -0
package/src/matchers.ts +457 -72
package/src/pretty-format.ts +1 -0
package/src/pretty-widget.ts +98 -70
package/src/production.ts +51 -0
package/src/queries.ts +127 -89
package/src/query-helpers.ts +97 -0
package/src/render-children.ts +25 -0
package/src/render.tsx +77 -17
package/src/role-helpers.ts +16 -5
package/src/role-naming.ts +99 -0
package/src/screenshot.ts +266 -104
package/src/timers.ts +31 -0
package/src/traversal.ts +66 -6
package/src/types.ts +34 -17
package/src/user-event/adjustment.ts +31 -3
package/src/user-event/click.ts +248 -52
package/src/user-event/column-header-click.ts +76 -0
package/src/user-event/event-wrapper.ts +41 -23
package/src/user-event/index.ts +130 -40
package/src/user-event/indexed-children.ts +75 -0
package/src/user-event/keyboard.ts +161 -43
package/src/user-event/list-row-click.ts +54 -0
package/src/user-event/native-click.ts +51 -0
package/src/user-event/notebook-tab-click.ts +57 -0
package/src/user-event/pointer.ts +48 -9
package/src/user-event/selection.ts +67 -41
package/src/user-event/text.ts +192 -46
package/src/wait-for.ts +4 -4
package/src/widget-accessible-properties.ts +183 -230
package/src/widget-getters.ts +85 -0
package/src/window-state.ts +70 -0
package/src/within.ts +3 -2

package/src/types.ts CHANGED Viewed

@@ -55,13 +55,19 @@ type MatcherOptions<T extends Gtk.Widget = Gtk.Widget> = {
     as?: WidgetType<T> | undefined;
 } & WaitForOptions;
-/** Constraints on a widget's numeric range value used by role queries. */
+/**
+ * Constraints on a widget's numeric range value used by role queries. The numbers come from the
+ * accessibility tree and match within 0.001, the resolution GTK keeps them to.
+ */
 type ByRoleValue = {
     /** The current value. */
     now?: number | undefined;
     /** The lower bound of the value's range. */
     min?: number | undefined;
-    /** The upper bound of the value's range. */
+    /**
+     * The highest value the widget can reach, which on a paged widget such as a scrollbar is its
+     * adjustment's upper bound less one page.
+     */
     max?: number | undefined;
     /** Matcher for the value's textual representation. */
     text?: Matcher | undefined;
@@ -87,7 +93,7 @@ type ByRoleOptions<T extends Gtk.Widget = Gtk.Widget> = MatcherOptions<T> & {
     description?: Matcher | undefined;
     /** Constraints on the widget's range value, each checked only when given. */
     value?: ByRoleValue | undefined;
-    /** When true, include widgets excluded from the accessibility tree. */
+    /** When true, include widgets excluded from the accessibility tree. Widgets that are not mapped stay excluded. */
     hidden?: boolean | undefined;
 };
@@ -163,7 +169,12 @@ type QueryFamilies<Head extends unknown[]> = QueryFamily<"Role", "role", Head> &
  * React behavior toggles, error callbacks, and custom queries to bind.
  */
 type RenderOptions<Q extends QueryMap = Record<never, never>> = {
-    /** Widget or root element to mount into; an undecorated harness window is created when omitted. */
+    /**
+     * Widget or root element to mount into; an undecorated harness window is created when omitted.
+     * A widget container that sits outside every toplevel, such as a bare `Gtk.Box`, keeps the tree
+     * 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;
     /** Root of the subtree that bound queries search. */
     baseElement?: Container | undefined;
@@ -187,8 +198,11 @@ type DebugUtilities = {
     debug: (element?: Container | Container[], options?: PrettyWidgetOptions) => void;
     /** Prints the accessible roles found in the scope, with the widgets carrying each one. */
     logRoles: () => void;
-    /** Captures a window, writes the image to a temporary file, and logs its path. */
-    screenshot: (selector?: WindowSelector, options?: ScreenshotOptions) => Promise<ScreenshotResult>;
+    /**
+     * Captures what is on screen, which is the active toplevel window: GTK4 exposes no position for
+     * a toplevel, so windows cannot be composited into a single image.
+     */
+    screenshot: (options?: ScreenshotOptions) => Promise<ScreenshotResult>;
 };
 /** A captured screenshot: base64-encoded image data, its MIME type, and pixel dimensions. */
@@ -203,26 +217,27 @@ type ScreenshotResult = {
     height: number;
 };
-/** Options for capturing a screenshot: the poll timeout and interval, plus a rendering scale factor. */
+/**
+ * Options for capturing a screenshot: the poll timeout and interval, a rendering scale factor, and
+ * a file to write the PNG to.
+ */
 type ScreenshotOptions = Pick<WaitForOptions, "timeout" | "interval"> & {
     /** Device scale factor applied when rendering. */
-    scale?: number;
+    scale?: number | undefined;
+    /** File the PNG is written to, with its parent directories created as needed. */
+    path?: string | undefined;
 };
-/**
- * Selects the window to screenshot by index, or by title (exact string or regular expression);
- * undefined targets the default window.
- */
-type WindowSelector = number | string | RegExp | undefined;
 /**
  * Options for {@link renderHook}: an optional wrapper and the initial props (required unless the
  * props type permits undefined).
  */
 type RenderHookOptions<Props> = {
+    /** Component wrapped around the one calling the hook, such as a context provider. */
     wrapper?: WrapperComponent;
 } & (undefined extends Props
     ? {
+            /** Props the hook is invoked with until `rerender` is given new ones. */
             initialProps?: Props;
         }
     : {
@@ -234,8 +249,11 @@ type RenderHookOptions<Props> = {
  * props and to unmount.
  */
 type RenderHookResult<Result, Props> = {
-    /** Holds the most recent value returned by the hook under `current`. */
-    result: { current: Result };
+    /** Stable object the hook's return value is written to on every render. */
+    result: {
+        /** The hook's latest return value. */
+        current: Result;
+    };
     /** Re-invokes the hook, keeping the previous props when none are given. */
     rerender: (newProps?: Props) => Promise<void>;
     /** Unmounts the component that calls the hook. */
@@ -260,7 +278,6 @@ export {
     type DebugUtilities,
     type ScreenshotResult,
     type ScreenshotOptions,
-    type WindowSelector,
     type RenderHookOptions,
     type RenderHookResult,
 };

package/src/user-event/adjustment.ts CHANGED Viewed

@@ -1,4 +1,6 @@
 import * as Gtk from "@gtkx/gi/gtk";
+import { scheduleNextFrame } from "../frame-sync.js";
+import { getTypeTag } from "../widget-getters.js";
 import { wrapEvent } from "./event-wrapper.js";
 /** A scroll distance in pixels along each axis. */
@@ -23,7 +25,7 @@ const slide = (widget: Gtk.Widget, value: number): Promise<void> =>
     wrapEvent(widget, () => {
         if (!(widget instanceof Gtk.Range)) {
             throw new TypeError(
-                `userEvent.slide requires a Gtk.Range (e.g. Gtk.Scale), got ${widget.constructor.name}`,
+                `userEvent.slide requires a Gtk.Range (e.g. Gtk.Scale), got ${getTypeTag(widget)}`,
             );
         }
@@ -44,22 +46,47 @@ const resolveScrollAdjustments = (widget: Gtk.Widget): ScrollAdjustments | null
     return null;
 };
+const stepToward = (adjustment: Gtk.Adjustment, target: number, step: number): number => {
+    const value = adjustment.getValue();
+    adjustment.setValue(value < target ? Math.min(value + step, target) : Math.max(value - step, target));
+    return adjustment.getValue();
+};
+const rampTo = (adjustment: Gtk.Adjustment, target: number, step: number): void => {
+    let value = adjustment.getValue();
+    while (value !== target) {
+        const moved = stepToward(adjustment, target, step);
+        if (moved === value) {
+            return;
+        }
+        value = moved;
+    }
+};
 const applyScrollDelta = (adjustment: Gtk.Adjustment | null, delta: number): void => {
     if (!adjustment || delta === 0) {
         return;
     }
-    adjustment.setValue(adjustment.getValue() + delta);
+    const pageSize = adjustment.getPageSize();
+    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.
  */
 const scroll = (widget: Gtk.Widget, delta: ScrollDelta): Promise<void> =>
-    wrapEvent(widget, () => {
+    wrapEvent(widget, async () => {
         const adjustments = resolveScrollAdjustments(widget);
         if (!adjustments) {
@@ -70,6 +97,7 @@ const scroll = (widget: Gtk.Widget, delta: ScrollDelta): Promise<void> =>
         applyScrollDelta(adjustments.horizontal, delta.x ?? 0);
         applyScrollDelta(adjustments.vertical, delta.y ?? 0);
+        await scheduleNextFrame(widget);
     });
 export { slide, scroll, type ScrollDelta };

package/src/user-event/click.ts CHANGED Viewed

@@ -1,8 +1,29 @@
+import * as Gdk from "@gtkx/gi/gdk";
 import * as Gtk from "@gtkx/gi/gtk";
-import { getOrCreateControllers, queryController } from "./controller.js";
+import { hasSignalListener } from "@gtkx/runtime/internal";
+import { callBooleanGetter, getCallableMethod, hasWidgetMethod } from "../widget-getters.js";
+import { queryAllControllers } from "./controller.js";
 import { wrapEvent } from "./event-wrapper.js";
+import { hasIndexedChildren, selectContainerChild, SELECTED_PROBE, unselectOtherChildren } from "./indexed-children.js";
+import { isClickTransparent, type NativeClick, nativeClickFor } from "./native-click.js";
-const getPressPoint = (widget: Gtk.Widget): { x: number; y: number } => {
+type PressPoint = { x: number; y: number };
+type ClickPhase = "pressed" | "released";
+type ClickSite = { gestures: Gtk.GestureClick[]; point: PressPoint };
+type ClickScope = { isClicked: boolean; isInternalAllowed: boolean };
+type ClickTarget = {
+    widget: Gtk.Widget;
+    container: Gtk.Widget | null;
+    gestures: Gtk.GestureClick[];
+    isClaiming: boolean;
+    native: NativeClick | null;
+};
+const CLICK_SIGNALS = ["pressed", "released"];
+const PRIMARY_BUTTONS: Set<number> = new Set([0, Gdk.BUTTON_PRIMARY]);
+const getCenterPoint = (widget: Gtk.Widget): PressPoint => {
     const width = widget.getWidth();
     const height = widget.getHeight();
@@ -13,46 +34,205 @@ const getPressPoint = (widget: Gtk.Widget): { x: number; y: number } => {
     return { x: 0, y: 0 };
 };
-const emitGesture = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number, signal: string): void => {
-    const { x, y } = getPressPoint(widget);
+const getClickPoint = (clicked: Gtk.Widget, carrier: Gtk.Widget): PressPoint => {
+    if (clicked === carrier) {
+        return getCenterPoint(clicked);
+    }
+    const [isComputed, bounds] = clicked.computeBounds(carrier);
+    if (!isComputed) {
+        return getCenterPoint(carrier);
+    }
+    return { x: bounds.getX() + bounds.getWidth() / 2, y: bounds.getY() + bounds.getHeight() / 2 };
+};
+const emitGesture = (point: PressPoint, controllers: Gtk.GestureClick[], nPress: number, signal: string): void => {
     for (const controller of controllers) {
-        controller.emit(signal, nPress, x, y);
+        controller.emit(signal, nPress, point.x, point.y);
     }
 };
-const emitPress = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number): void => {
-    emitGesture(widget, controllers, nPress, "pressed");
+const emitClickPhase = (
+    widget: Gtk.Widget,
+    controllers: Gtk.GestureClick[],
+    nPress: number,
+    phase: ClickPhase,
+): void => {
+    emitGesture(getCenterPoint(widget), controllers, nPress, phase);
 };
-const emitRelease = (widget: Gtk.Widget, controllers: Gtk.GestureClick[], nPress: number): void => {
-    emitGesture(widget, controllers, nPress, "released");
+const emitSitePhase = (sites: ClickSite[], nPress: number, phase: ClickPhase): void => {
+    for (const site of sites) {
+        emitGesture(site.point, site.gestures, nPress, phase);
+    }
 };
-const emitClickSequence = (widget: Gtk.Widget, target: Gtk.Widget, nPress: number): Promise<void> =>
-    wrapEvent(widget, () => {
-        const controllers = getOrCreateControllers(target, Gtk.GestureClick);
+const emitClickSequence = (sites: ClickSite[], nPress: number): void => {
+    for (let i = 1; i <= nPress; i++) {
+        emitSitePhase(sites, i, "pressed");
+        emitSitePhase(sites, i, "released");
+    }
+};
-        for (let i = 1; i <= nPress; i++) {
-            emitPress(target, controllers, i);
-            emitRelease(target, controllers, i);
-        }
-    });
+const containerFor = (widget: Gtk.Widget): Gtk.Widget | null => {
+    const parent = widget.getParent();
-const findClickableAncestor = (widget: Gtk.Widget): Gtk.Widget | null => {
-    let current = widget.getParent();
+    return parent !== null && hasWidgetMethod(widget, SELECTED_PROBE) && hasIndexedChildren(parent) ? parent : null;
+};
-    while (current) {
-        if (current instanceof Gtk.Button || queryController(current, Gtk.GestureClick) !== null) {
-            return current;
-        }
+const hasClickHandlers = (gesture: Gtk.GestureClick): boolean => hasSignalListener(gesture, CLICK_SIGNALS);
+const isInternalGesture = (gesture: Gtk.GestureClick): boolean => !hasSignalListener(gesture);
+const isPrimaryGesture = (gesture: Gtk.GestureClick): boolean => PRIMARY_BUTTONS.has(gesture.getButton());
+const clickGestures = (widget: Gtk.Widget): Gtk.GestureClick[] =>
+    queryAllControllers(widget, Gtk.GestureClick).filter((gesture) => isPrimaryGesture(gesture));
+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 };
+    }
-        current = current.getParent();
+    const authored = gestures.filter((gesture) => hasClickHandlers(gesture));
+    if (authored.length > 0) {
+        return { widget, container: null, gestures: authored, isClaiming: false, native: null };
+    }
+    if (isInternalAllowed && gestures.some((gesture) => isInternalGesture(gesture))) {
+        return { widget, container: null, gestures, isClaiming: true, native: null };
     }
     return null;
 };
+const clickTargetFor = (widget: Gtk.Widget, scope: ClickScope): ClickTarget | null => {
+    if (isClickTransparent(widget)) {
+        return null;
+    }
+    const native = nativeClickFor(widget, scope.isClicked);
+    if (native !== null) {
+        return { widget, container: null, gestures: getAuthoredClickGestures(widget), isClaiming: true, native };
+    }
+    return gestureTargetFor(widget, scope.isInternalAllowed);
+};
+const isSelfClickTarget = (widget: Gtk.Widget): boolean =>
+    isClickTransparent(widget) || clickTargetFor(widget, { isClicked: true, isInternalAllowed: false }) !== null;
+const nextClickWidget = (current: Gtk.Widget, target: ClickTarget | null): Gtk.Widget | null =>
+    target?.isClaiming === true ? null : current.getParent();
+const collectClickTargets = (widget: Gtk.Widget): ClickTarget[] => {
+    const targets: ClickTarget[] = [];
+    let current: Gtk.Widget | null = widget;
+    while (current !== null) {
+        const isClicked = current === widget;
+        const scope = { isClicked, isInternalAllowed: !isClicked && targets.length === 0 };
+        const target = clickTargetFor(current, scope);
+        const next = nextClickWidget(current, target);
+        if (target !== null) {
+            targets.push(target);
+        }
+        current = next;
+    }
+    return targets;
+};
+const targetSites = (clicked: Gtk.Widget, target: ClickTarget): ClickSite[] => {
+    const { container } = target;
+    const site = { gestures: target.gestures, point: getClickPoint(clicked, target.widget) };
+    if (container === null) {
+        return [site];
+    }
+    return [site, { gestures: getAuthoredClickGestures(container), point: getClickPoint(clicked, container) }];
+};
+const isSingleClickActivating = (container: Gtk.Widget): boolean =>
+    callBooleanGetter(container, "getActivateOnSingleClick") ?? true;
+const isMultipleSelection = (container: Gtk.Widget): boolean =>
+    getCallableMethod<[], Gtk.SelectionMode>(container, "getSelectionMode")?.() === Gtk.SelectionMode.MULTIPLE;
+const isChildSelectable = (child: Gtk.Widget): boolean => callBooleanGetter(child, "getSelectable") ?? true;
+const replaceContainerSelection = (container: Gtk.Widget, child: Gtk.Widget): void => {
+    if (!isChildSelectable(child)) {
+        return;
+    }
+    selectContainerChild(container, child);
+    if (isMultipleSelection(container)) {
+        unselectOtherChildren(container, child);
+    }
+};
+const isActivatedByClick = (container: Gtk.Widget, nPress: number): boolean =>
+    isSingleClickActivating(container) || nPress > 1;
+const isSelectionReplacedByClick = (container: Gtk.Widget, nPress: number): boolean =>
+    nPress > 1 || !isSingleClickActivating(container);
+const applyContainerOutcome = (target: ClickTarget, nPress: number): void => {
+    const { container, widget } = target;
+    if (container === null || widget.getParent() !== container) {
+        return;
+    }
+    if (isActivatedByClick(container, nPress)) {
+        widget.activate();
+    }
+    if (isSelectionReplacedByClick(container, nPress)) {
+        replaceContainerSelection(container, widget);
+    }
+};
+const applyClickOutcome = (target: ClickTarget, nPress: number): void => {
+    if (target.native === null) {
+        applyContainerOutcome(target, nPress);
+        return;
+    }
+    target.native(target.widget, nPress);
+};
+const applyClickOutcomes = (targets: ClickTarget[], nPress: number): void => {
+    for (const target of targets) {
+        applyClickOutcome(target, nPress);
+    }
+};
+const deliverClick = (widget: Gtk.Widget, nPress: number): Promise<void> =>
+    wrapEvent(widget, () => {
+        const targets = collectClickTargets(widget);
+        const sites = targets.flatMap((target) => targetSites(widget, target));
+        emitClickSequence(sites, nPress);
+        applyClickOutcomes(targets, nPress);
+    });
+/* eslint-disable-next-line unicorn/consistent-boolean-name -- the boolean reports whether activation succeeded */
 const tryActivate = async (widget: Gtk.Widget): Promise<boolean> => {
     if (widget.getAccessibleRole() === Gtk.AccessibleRole.LABEL) {
         return false;
@@ -68,39 +248,55 @@ const tryActivate = async (widget: Gtk.Widget): Promise<boolean> => {
 };
 /**
- * Presses and releases a Gtk.Button, flips a Gtk.Switch, and otherwise activates the widget,
- * falling back to a click gesture on the nearest Gtk.Button or click-gesture ancestor when
- * activation does nothing. A widget with the label role is never activated.
+ * 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.
  */
 const click = async (widget: Gtk.Widget): Promise<void> => {
-    if (widget instanceof Gtk.Button) {
-        await emitClickSequence(widget, widget, 1);
-        return;
-    }
-    if (widget instanceof Gtk.Switch) {
-        await wrapEvent(widget, () => {
-            widget.setActive(!widget.getActive());
-        });
-        return;
-    }
-    if (await tryActivate(widget)) {
+    if (!isSelfClickTarget(widget) && (await tryActivate(widget))) {
         return;
     }
-    const target = findClickableAncestor(widget);
-    if (target) {
-        await emitClickSequence(widget, target, 1);
-    }
+    await deliverClick(widget, 1);
 };
-/** Emits a two-press click gesture at the widget's center, adding a Gtk.GestureClick when it has none. */
-const dblClick = (widget: Gtk.Widget): Promise<void> => emitClickSequence(widget, widget, 2);
-/** Emits a three-press click gesture at the widget's center, adding a Gtk.GestureClick when it has none. */
-const tripleClick = (widget: Gtk.Widget): Promise<void> => emitClickSequence(widget, widget, 3);
+/**
+ * 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.
+ */
+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.
+ */
+const tripleClick = (widget: Gtk.Widget): Promise<void> => deliverClick(widget, 3);
-export { emitPress, emitRelease, click, dblClick, tripleClick };
+export { clickGestures, emitClickPhase, getAuthoredClickGestures, click, dblClick, tripleClick };

package/src/user-event/column-header-click.ts ADDED Viewed

@@ -0,0 +1,76 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { ancestorFor, children } from "../traversal.js";
+import { getWidgetTextContent } from "../widget-accessible-properties.js";
+const columnsFor = (view: Gtk.ColumnView): Gtk.ColumnViewColumn[] => {
+    const model = view.getColumns();
+    const columns: Gtk.ColumnViewColumn[] = [];
+    for (let index = 0; index < model.getNItems(); index++) {
+        const column = model.getItem(index);
+        if (column instanceof Gtk.ColumnViewColumn) {
+            columns.push(column);
+        }
+    }
+    return columns;
+};
+const headerIndexFor = (header: Gtk.Widget): number => {
+    const parent = header.getParent();
+    return parent === null ? -1 : [...children(parent)].indexOf(header);
+};
+const titledColumnFor = (columns: Gtk.ColumnViewColumn[], title: string | null): Gtk.ColumnViewColumn | null => {
+    const matches = columns.filter((column) => column.getTitle() === title);
+    return matches.length === 1 ? matches[0] ?? null : null;
+};
+const columnFor = (header: Gtk.Widget, view: Gtk.ColumnView): Gtk.ColumnViewColumn | null => {
+    const columns = columnsFor(view);
+    const picked = columns[headerIndexFor(header)] ?? null;
+    const title = getWidgetTextContent(header);
+    if (picked !== null && picked.getTitle() === title) {
+        return picked;
+    }
+    return titledColumnFor(columns, title) ?? picked;
+};
+const sortableColumnFor = (header: Gtk.Widget, view: Gtk.ColumnView): Gtk.ColumnViewColumn | null => {
+    const column = columnFor(header, view);
+    return column !== null && column.getSorter() !== null ? column : null;
+};
+const invertedSortDirection = (order: Gtk.SortType): Gtk.SortType =>
+    order === Gtk.SortType.ASCENDING ? Gtk.SortType.DESCENDING : Gtk.SortType.ASCENDING;
+const nextSortDirection = (view: Gtk.ColumnView, column: Gtk.ColumnViewColumn): Gtk.SortType => {
+    const sorter = view.getSorter();
+    if (!(sorter instanceof Gtk.ColumnViewSorter) || sorter.getPrimarySortColumn() !== column) {
+        return Gtk.SortType.ASCENDING;
+    }
+    return invertedSortDirection(sorter.getPrimarySortOrder());
+};
+const applyHeaderClick = (header: Gtk.Widget, nPress: number): void => {
+    const view = ancestorFor(header, Gtk.ColumnView);
+    const column = view === null ? null : sortableColumnFor(header, view);
+    if (view === null || column === null) {
+        return;
+    }
+    for (let press = 1; press <= nPress; press++) {
+        view.sortByColumn(column, nextSortDirection(view, column));
+    }
+};
+export { applyHeaderClick };