@gtkx/testing 0.20.0 → 1.0.0-rc.1

package/dist/widget-accessible-properties.js

@@ -0,0 +1,215 @@
+import * as Gtk from "@gtkx/gi/gtk";
+import { getAccessibleMetadata } from "@gtkx/react/internal";
+import { EDITABLE_ROLES, isEditable, readEditableText } from "./editable.js";
+import { descendants } from "./traversal.js";
+const callStringGetter = (widget, method) => {
+    const fn = Reflect.get(widget, method);
+    if (typeof fn !== "function")
+        return null;
+    const value = fn.call(widget);
+    return value ?? null;
+};
+const readAccessibleString = (widget, key) => {
+    const value = getAccessibleMetadata(widget, key);
+    return typeof value === "string" ? value : null;
+};
+const readAccessibleNumber = (widget, key) => {
+    const value = getAccessibleMetadata(widget, key);
+    return typeof value === "number" ? value : null;
+};
+const readAccessibleBoolean = (widget, key) => {
+    const value = getAccessibleMetadata(widget, key);
+    return typeof value === "boolean" ? value : null;
+};
+const getLabelText = (widget) => {
+    if (widget instanceof Gtk.Label)
+        return widget.getLabel();
+    if (widget instanceof Gtk.Inscription)
+        return widget.getText() ?? null;
+    return null;
+};
+const DEFAULT_TEXT_GETTERS = ["getLabel", "getText", "getTitle"];
+/**
+ * Returns a widget's own text by trying its label, text, and title getters in
+ * order, or null when none produce a value.
+ *
+ * @param widget The widget to read text from.
+ */
+export const getWidgetNodeText = (widget) => {
+    for (const getter of DEFAULT_TEXT_GETTERS) {
+        const value = callStringGetter(widget, getter);
+        if (value)
+            return value;
+    }
+    return null;
+};
+const stripMnemonic = (text) => text.replace(/_(.)/g, "$1");
+const namingLabelText = (widget) => {
+    const text = getLabelText(widget);
+    if (text === null)
+        return null;
+    return widget instanceof Gtk.Label && widget.getUseUnderline() ? stripMnemonic(text) : text;
+};
+const isNamingLabelRole = (role, includePresentation) => role === Gtk.AccessibleRole.LABEL || (includePresentation && role === Gtk.AccessibleRole.PRESENTATION);
+const collectLabels = (widget) => {
+    const includePresentation = widget.getAccessibleRole() === Gtk.AccessibleRole.MENU_ITEM;
+    const labels = [];
+    for (const descendant of descendants(widget)) {
+        if (!isNamingLabelRole(descendant.getAccessibleRole(), includePresentation))
+            continue;
+        const labelText = namingLabelText(descendant);
+        if (labelText)
+            labels.push(labelText);
+    }
+    return labels;
+};
+export const getWidgetLabelText = (widget) => {
+    if (widget.getAccessibleRole() !== Gtk.AccessibleRole.LABEL)
+        return null;
+    return getLabelText(widget);
+};
+export const getWidgetAccessibleName = (widget) => {
+    const role = widget.getAccessibleRole();
+    if (role === Gtk.AccessibleRole.TAB_PANEL) {
+        const parent = widget.getParent();
+        if (parent instanceof Gtk.Stack) {
+            const page = parent.getPage(widget);
+            return page.getTitle() ?? null;
+        }
+        return null;
+    }
+    const accessibleLabel = getAccessibleMetadata(widget, "accessibleLabel");
+    if (accessibleLabel)
+        return accessibleLabel;
+    const ownText = getWidgetNodeText(widget);
+    if (ownText)
+        return ownText;
+    const childLabels = collectLabels(widget);
+    if (childLabels.length > 0)
+        return childLabels.join(" ");
+    return callStringGetter(widget, "getTooltipText");
+};
+export const getWidgetName = (widget) => {
+    return widget.getName();
+};
+export const getWidgetPlaceholderText = (widget) => {
+    if (!EDITABLE_ROLES.has(widget.getAccessibleRole()) || !(widget instanceof Gtk.Editable)) {
+        return null;
+    }
+    return callStringGetter(widget, "getPlaceholderText");
+};
+export const getWidgetDisplayValue = (widget) => {
+    if (EDITABLE_ROLES.has(widget.getAccessibleRole()) && isEditable(widget)) {
+        return readEditableText(widget);
+    }
+    return null;
+};
+export const getWidgetCheckedState = (widget) => {
+    if (widget instanceof Gtk.CheckButton)
+        return widget.getActive();
+    if (widget instanceof Gtk.Switch)
+        return widget.getActive();
+    if (widget instanceof Gtk.ToggleButton && widget.getAccessibleRole() === Gtk.AccessibleRole.RADIO) {
+        return widget.getActive();
+    }
+    return null;
+};
+export const getWidgetPressedState = (widget) => {
+    if (widget instanceof Gtk.ToggleButton)
+        return widget.getActive();
+    return null;
+};
+export const getWidgetExpandedState = (widget) => {
+    if (widget instanceof Gtk.Expander) {
+        return widget.getExpanded();
+    }
+    if (widget instanceof Gtk.TreeExpander) {
+        return widget.getListRow()?.getExpanded() ?? null;
+    }
+    return null;
+};
+export const getWidgetSelectedState = (widget) => {
+    if (widget instanceof Gtk.ListBoxRow) {
+        return widget.isSelected();
+    }
+    if (widget.getAccessibleRole() === Gtk.AccessibleRole.ROW) {
+        return (widget.getStateFlags() & Gtk.StateFlags.SELECTED) !== 0;
+    }
+    return null;
+};
+export const getWidgetLevel = (widget) => {
+    return readAccessibleNumber(widget, "accessibleLevel");
+};
+export const getWidgetInvalidState = (widget) => {
+    return getAccessibleMetadata(widget, "accessibleInvalid");
+};
+export const getWidgetErrorMessage = (widget) => {
+    const targets = getAccessibleMetadata(widget, "accessibleErrorMessage");
+    return Array.isArray(targets) && targets.length > 0 ? targets : null;
+};
+export const getWidgetBusyState = (widget) => {
+    return readAccessibleBoolean(widget, "accessibleBusy");
+};
+export const getWidgetDescription = (widget) => {
+    return readAccessibleString(widget, "accessibleDescription");
+};
+const adjustmentValue = (adjustment) => ({
+    now: adjustment.getValue(),
+    min: adjustment.getLower(),
+    max: adjustment.getUpper(),
+});
+const getWidgetLiveValue = (widget) => {
+    if (widget instanceof Gtk.Range)
+        return adjustmentValue(widget.getAdjustment());
+    if (widget instanceof Gtk.Scrollbar)
+        return adjustmentValue(widget.getAdjustment());
+    if (widget instanceof Gtk.SpinButton)
+        return adjustmentValue(widget.getAdjustment());
+    if (widget instanceof Gtk.ScaleButton)
+        return adjustmentValue(widget.getAdjustment());
+    if (widget instanceof Gtk.LevelBar) {
+        return { now: widget.getValue(), min: widget.getMinValue(), max: widget.getMaxValue() };
+    }
+    if (widget instanceof Gtk.ProgressBar)
+        return { now: widget.getFraction(), min: 0, max: 1 };
+    return null;
+};
+export const getWidgetValue = (widget) => {
+    const text = readAccessibleString(widget, "accessibleValueText");
+    const live = getWidgetLiveValue(widget);
+    if (live)
+        return { ...live, text };
+    return {
+        now: readAccessibleNumber(widget, "accessibleValueNow"),
+        min: readAccessibleNumber(widget, "accessibleValueMin"),
+        max: readAccessibleNumber(widget, "accessibleValueMax"),
+        text,
+    };
+};
+export const getWidgetOwnLabel = (widget) => {
+    return readAccessibleString(widget, "accessibleLabel");
+};
+export const getWidgetLabelledByText = (widget) => {
+    const targets = getAccessibleMetadata(widget, "accessibleLabelledBy");
+    if (!Array.isArray(targets) || targets.length === 0)
+        return null;
+    const texts = [];
+    for (const target of targets) {
+        const text = getWidgetAccessibleName(target);
+        if (text !== null)
+            texts.push(text);
+    }
+    return texts.length > 0 ? texts.join(" ") : null;
+};
+export const isInaccessible = (widget) => {
+    let current = widget;
+    while (current) {
+        if (!current.getVisible())
+            return true;
+        if (readAccessibleBoolean(current, "accessibleHidden") === true)
+            return true;
+        current = current.getParent();
+    }
+    return false;
+};
+//# sourceMappingURL=widget-accessible-properties.js.map

package/dist/widget-accessible-properties.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-accessible-properties.js","sourceRoot":"","sources":["../src/widget-accessible-properties.ts"],"names":[],"mappings":"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","sourcesContent":["import * as Gtk from \"@gtkx/gi/gtk\";\nimport { getAccessibleMetadata } from \"@gtkx/react/internal\";\nimport { EDITABLE_ROLES, isEditable, readEditableText } from \"./editable.js\";\nimport { descendants } from \"./traversal.js\";\n\nconst callStringGetter = (widget: Gtk.Widget, method: string): string | null => {\n    const fn: unknown = Reflect.get(widget, method);\n    if (typeof fn !== \"function\") return null;\n    const value = (fn as () => string | null).call(widget);\n    return value ?? null;\n};\n\nconst readAccessibleString = (widget: Gtk.Widget, key: string): string | null => {\n    const value = getAccessibleMetadata<string>(widget, key);\n    return typeof value === \"string\" ? value : null;\n};\n\nconst readAccessibleNumber = (widget: Gtk.Widget, key: string): number | null => {\n    const value = getAccessibleMetadata<number>(widget, key);\n    return typeof value === \"number\" ? value : null;\n};\n\nconst readAccessibleBoolean = (widget: Gtk.Widget, key: string): boolean | null => {\n    const value = getAccessibleMetadata<boolean>(widget, key);\n    return typeof value === \"boolean\" ? value : null;\n};\n\nconst getLabelText = (widget: Gtk.Widget): string | null => {\n    if (widget instanceof Gtk.Label) return widget.getLabel();\n    if (widget instanceof Gtk.Inscription) return widget.getText() ?? null;\n    return null;\n};\n\nconst DEFAULT_TEXT_GETTERS = [\"getLabel\", \"getText\", \"getTitle\"] as const;\n\n/**\n * Returns a widget's own text by trying its label, text, and title getters in\n * order, or null when none produce a value.\n *\n * @param widget The widget to read text from.\n */\nexport const getWidgetNodeText = (widget: Gtk.Widget): string | null => {\n    for (const getter of DEFAULT_TEXT_GETTERS) {\n        const value = callStringGetter(widget, getter);\n        if (value) return value;\n    }\n    return null;\n};\n\nconst stripMnemonic = (text: string): string => text.replace(/_(.)/g, \"$1\");\n\nconst namingLabelText = (widget: Gtk.Widget): string | null => {\n    const text = getLabelText(widget);\n    if (text === null) return null;\n    return widget instanceof Gtk.Label && widget.getUseUnderline() ? stripMnemonic(text) : text;\n};\n\nconst isNamingLabelRole = (role: Gtk.AccessibleRole, includePresentation: boolean): boolean =>\n    role === Gtk.AccessibleRole.LABEL || (includePresentation && role === Gtk.AccessibleRole.PRESENTATION);\n\nconst collectLabels = (widget: Gtk.Widget): string[] => {\n    const includePresentation = widget.getAccessibleRole() === Gtk.AccessibleRole.MENU_ITEM;\n    const labels: string[] = [];\n    for (const descendant of descendants(widget)) {\n        if (!isNamingLabelRole(descendant.getAccessibleRole(), includePresentation)) continue;\n        const labelText = namingLabelText(descendant);\n        if (labelText) labels.push(labelText);\n    }\n    return labels;\n};\n\nexport const getWidgetLabelText = (widget: Gtk.Widget): string | null => {\n    if (widget.getAccessibleRole() !== Gtk.AccessibleRole.LABEL) return null;\n    return getLabelText(widget);\n};\n\nexport const getWidgetAccessibleName = (widget: Gtk.Widget): string | null => {\n    const role = widget.getAccessibleRole();\n\n    if (role === Gtk.AccessibleRole.TAB_PANEL) {\n        const parent = widget.getParent();\n        if (parent instanceof Gtk.Stack) {\n            const page = parent.getPage(widget);\n            return page.getTitle() ?? null;\n        }\n        return null;\n    }\n\n    const accessibleLabel = getAccessibleMetadata<string>(widget, \"accessibleLabel\");\n    if (accessibleLabel) return accessibleLabel;\n\n    const ownText = getWidgetNodeText(widget);\n    if (ownText) return ownText;\n\n    const childLabels = collectLabels(widget);\n    if (childLabels.length > 0) return childLabels.join(\" \");\n\n    return callStringGetter(widget, \"getTooltipText\");\n};\n\nexport const getWidgetName = (widget: Gtk.Widget): string | null => {\n    return widget.getName();\n};\n\nexport const getWidgetPlaceholderText = (widget: Gtk.Widget): string | null => {\n    if (!EDITABLE_ROLES.has(widget.getAccessibleRole()) || !(widget instanceof Gtk.Editable)) {\n        return null;\n    }\n\n    return callStringGetter(widget, \"getPlaceholderText\");\n};\n\nexport const getWidgetDisplayValue = (widget: Gtk.Widget): string | null => {\n    if (EDITABLE_ROLES.has(widget.getAccessibleRole()) && isEditable(widget)) {\n        return readEditableText(widget);\n    }\n\n    return null;\n};\n\nexport const getWidgetCheckedState = (widget: Gtk.Widget): boolean | null => {\n    if (widget instanceof Gtk.CheckButton) return widget.getActive();\n    if (widget instanceof Gtk.Switch) return widget.getActive();\n    if (widget instanceof Gtk.ToggleButton && widget.getAccessibleRole() === Gtk.AccessibleRole.RADIO) {\n        return widget.getActive();\n    }\n    return null;\n};\n\nexport const getWidgetPressedState = (widget: Gtk.Widget): boolean | null => {\n    if (widget instanceof Gtk.ToggleButton) return widget.getActive();\n    return null;\n};\n\nexport const getWidgetExpandedState = (widget: Gtk.Widget): boolean | null => {\n    if (widget instanceof Gtk.Expander) {\n        return widget.getExpanded();\n    }\n\n    if (widget instanceof Gtk.TreeExpander) {\n        return widget.getListRow()?.getExpanded() ?? null;\n    }\n\n    return null;\n};\n\nexport const getWidgetSelectedState = (widget: Gtk.Widget): boolean | null => {\n    if (widget instanceof Gtk.ListBoxRow) {\n        return widget.isSelected();\n    }\n\n    if (widget.getAccessibleRole() === Gtk.AccessibleRole.ROW) {\n        return (widget.getStateFlags() & Gtk.StateFlags.SELECTED) !== 0;\n    }\n\n    return null;\n};\n\nexport const getWidgetLevel = (widget: Gtk.Widget): number | null => {\n    return readAccessibleNumber(widget, \"accessibleLevel\");\n};\n\nexport const getWidgetInvalidState = (widget: Gtk.Widget): Gtk.AccessibleInvalidState | null => {\n    return getAccessibleMetadata<Gtk.AccessibleInvalidState>(widget, \"accessibleInvalid\");\n};\n\nexport const getWidgetErrorMessage = (widget: Gtk.Widget): Gtk.Widget[] | null => {\n    const targets = getAccessibleMetadata<Gtk.Widget[]>(widget, \"accessibleErrorMessage\");\n    return Array.isArray(targets) && targets.length > 0 ? targets : null;\n};\n\nexport const getWidgetBusyState = (widget: Gtk.Widget): boolean | null => {\n    return readAccessibleBoolean(widget, \"accessibleBusy\");\n};\n\nexport const getWidgetDescription = (widget: Gtk.Widget): string | null => {\n    return readAccessibleString(widget, \"accessibleDescription\");\n};\n\nexport type WidgetValue = {\n    now: number | null;\n    min: number | null;\n    max: number | null;\n    text: string | null;\n};\n\ntype ValueTriplet = { now: number | null; min: number | null; max: number | null };\n\nconst adjustmentValue = (adjustment: Gtk.Adjustment): ValueTriplet => ({\n    now: adjustment.getValue(),\n    min: adjustment.getLower(),\n    max: adjustment.getUpper(),\n});\n\nconst getWidgetLiveValue = (widget: Gtk.Widget): ValueTriplet | null => {\n    if (widget instanceof Gtk.Range) return adjustmentValue(widget.getAdjustment());\n    if (widget instanceof Gtk.Scrollbar) return adjustmentValue(widget.getAdjustment());\n    if (widget instanceof Gtk.SpinButton) return adjustmentValue(widget.getAdjustment());\n    if (widget instanceof Gtk.ScaleButton) return adjustmentValue(widget.getAdjustment());\n    if (widget instanceof Gtk.LevelBar) {\n        return { now: widget.getValue(), min: widget.getMinValue(), max: widget.getMaxValue() };\n    }\n    if (widget instanceof Gtk.ProgressBar) return { now: widget.getFraction(), min: 0, max: 1 };\n    return null;\n};\n\nexport const getWidgetValue = (widget: Gtk.Widget): WidgetValue => {\n    const text = readAccessibleString(widget, \"accessibleValueText\");\n    const live = getWidgetLiveValue(widget);\n    if (live) return { ...live, text };\n    return {\n        now: readAccessibleNumber(widget, \"accessibleValueNow\"),\n        min: readAccessibleNumber(widget, \"accessibleValueMin\"),\n        max: readAccessibleNumber(widget, \"accessibleValueMax\"),\n        text,\n    };\n};\n\nexport const getWidgetOwnLabel = (widget: Gtk.Widget): string | null => {\n    return readAccessibleString(widget, \"accessibleLabel\");\n};\n\nexport const getWidgetLabelledByText = (widget: Gtk.Widget): string | null => {\n    const targets = getAccessibleMetadata<Gtk.Widget[]>(widget, \"accessibleLabelledBy\");\n    if (!Array.isArray(targets) || targets.length === 0) return null;\n\n    const texts: string[] = [];\n    for (const target of targets) {\n        const text = getWidgetAccessibleName(target);\n        if (text !== null) texts.push(text);\n    }\n\n    return texts.length > 0 ? texts.join(\" \") : null;\n};\n\nexport const isInaccessible = (widget: Gtk.Widget): boolean => {\n    let current: Gtk.Widget | null = widget;\n    while (current) {\n        if (!current.getVisible()) return true;\n        if (readAccessibleBoolean(current, \"accessibleHidden\") === true) return true;\n        current = current.getParent();\n    }\n    return false;\n};\n"]}

package/dist/within.d.ts

@@ -1,30 +1,13 @@
-import type * as Gtk from "@gtkx/ffi/gtk";
-import type { BoundQueries } from "./types.js";
+import type { BoundQueries } from "./bound-queries.js";
+import type { Container } from "./traversal.js";
+import type { BoundCustomQueries, QueryMap } from "./types.js";
 /**
- * Creates scoped query methods for a container widget.
+ * Binds the built-in queries, and any custom queries, to a specific container
+ * so they search only within that scope.
  *
- * Use this to query within a specific section of your UI rather than
- * the entire application.
- *
- * @param container - The widget to scope queries to
- * @returns Object with query methods bound to the container
- *
- * @example
- * ```tsx
- * import { render, within } from "@gtkx/testing";
- *
- * test("scoped queries", async () => {
- *   await render(<MyPage />);
- *
- *   const sidebar = await screen.findByRole(Gtk.AccessibleRole.NAVIGATION);
- *   const sidebarQueries = within(sidebar);
- *
- *   // Only searches within the sidebar
- *   const navButton = await sidebarQueries.findByRole(Gtk.AccessibleRole.BUTTON);
- * });
- * ```
- *
- * @see {@link screen} for global queries
+ * @param container The scope the returned queries operate on.
+ * @param queries Optional custom queries to bind alongside the built-in ones.
+ * @returns The queries bound to the container.
  */
-export declare const within: (container: Gtk.Widget) => BoundQueries;
+export declare const within: <Q extends QueryMap = Record<never, never>>(container: Container, queries?: Q) => BoundQueries & BoundCustomQueries<Q>;
 //# sourceMappingURL=within.d.ts.map

package/dist/within.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"within.d.ts","sourceRoot":"","sources":["../src/within.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,eAAe,CAAC;AAE1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,MAAM,GAAI,WAAW,GAAG,CAAC,MAAM,KAAG,YAAsC,CAAC"}
+{"version":3,"file":"within.d.ts","sourceRoot":"","sources":["../src/within.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAY/D;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,QAAQ,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,aACjD,SAAS,YACV,CAAC,KACZ,YAAY,GAAG,kBAAkB,CAAC,CAAC,CAGpC,CAAC"}

package/dist/within.js

@@ -1,29 +1,19 @@
-import { bindQueries } from "./bind-queries.js";
+import { builtinQueries } from "./queries.js";
+const bindQuery = (query, container) => (...args) => query(container, ...args);
+const bindCustomQueries = (customQueries, container) => {
+    const entries = Object.entries(customQueries).map(([key, query]) => [key, bindQuery(query, container)]);
+    return Object.fromEntries(entries);
+};
 /**
- * Creates scoped query methods for a container widget.
+ * Binds the built-in queries, and any custom queries, to a specific container
+ * so they search only within that scope.
  *
- * Use this to query within a specific section of your UI rather than
- * the entire application.
- *
- * @param container - The widget to scope queries to
- * @returns Object with query methods bound to the container
- *
- * @example
- * ```tsx
- * import { render, within } from "@gtkx/testing";
- *
- * test("scoped queries", async () => {
- *   await render(<MyPage />);
- *
- *   const sidebar = await screen.findByRole(Gtk.AccessibleRole.NAVIGATION);
- *   const sidebarQueries = within(sidebar);
- *
- *   // Only searches within the sidebar
- *   const navButton = await sidebarQueries.findByRole(Gtk.AccessibleRole.BUTTON);
- * });
- * ```
- *
- * @see {@link screen} for global queries
+ * @param container The scope the returned queries operate on.
+ * @param queries Optional custom queries to bind alongside the built-in ones.
+ * @returns The queries bound to the container.
  */
-export const within = (container) => bindQueries(container);
+export const within = (container, queries) => ({
+    ...bindCustomQueries(builtinQueries, container),
+    ...(queries ? bindCustomQueries(queries, container) : {}),
+});
 //# sourceMappingURL=within.js.map

package/dist/within.js.map

@@ -1 +1 @@
-{"version":3,"file":"within.js","sourceRoot":"","sources":["../src/within.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,SAAqB,EAAgB,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC"}
+{"version":3,"file":"within.js","sourceRoot":"","sources":["../src/within.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAI9C,MAAM,SAAS,GACX,CAAiC,KAAsD,EAAE,SAAoB,EAAE,EAAE,CACjH,CAAC,GAAG,IAAU,EAAU,EAAE,CACtB,KAAK,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CAAC;AAElC,MAAM,iBAAiB,GAAG,CAAqB,aAAgB,EAAE,SAAoB,EAAyB,EAAE;IAC5G,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAAU,CAAC,CAAC;IACjH,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAA0B,CAAC;AAChE,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAClB,SAAoB,EACpB,OAAW,EACyB,EAAE,CAAC,CAAC;IACxC,GAAG,iBAAiB,CAAC,cAAc,EAAE,SAAS,CAAC;IAC/C,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAE,EAA4B,CAAC;CACvF,CAAC,CAAC","sourcesContent":["import type { BoundQueries } from \"./bound-queries.js\";\nimport { builtinQueries } from \"./queries.js\";\nimport type { Container } from \"./traversal.js\";\nimport type { BoundCustomQueries, QueryMap } from \"./types.js\";\n\nconst bindQuery =\n    <Args extends unknown[], Result>(query: (container: Container, ...args: Args) => Result, container: Container) =>\n    (...args: Args): Result =>\n        query(container, ...args);\n\nconst bindCustomQueries = <Q extends QueryMap>(customQueries: Q, container: Container): BoundCustomQueries<Q> => {\n    const entries = Object.entries(customQueries).map(([key, query]) => [key, bindQuery(query, container)] as const);\n    return Object.fromEntries(entries) as BoundCustomQueries<Q>;\n};\n\n/**\n * Binds the built-in queries, and any custom queries, to a specific container\n * so they search only within that scope.\n *\n * @param container The scope the returned queries operate on.\n * @param queries Optional custom queries to bind alongside the built-in ones.\n * @returns The queries bound to the container.\n */\nexport const within = <Q extends QueryMap = Record<never, never>>(\n    container: Container,\n    queries?: Q,\n): BoundQueries & BoundCustomQueries<Q> => ({\n    ...bindCustomQueries(builtinQueries, container),\n    ...(queries ? bindCustomQueries(queries, container) : ({} as BoundCustomQueries<Q>)),\n});\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gtkx/testing",
-  "version": "0.20.0",
-  "description": "Testing utilities for GTKX applications",
+  "version": "1.0.0-rc.1",
+  "description": "Testing Library-style queries, user events, and screenshots for GTK4 widget trees rendered by GTKX",
   "keywords": [
     "gtkx",
     "gtk",
@@ -19,7 +19,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/gtkx-org/gtkx.git",
+    "url": "git+https://github.com/gtkx-org/gtkx.git",
     "directory": "packages/testing"
   },
   "license": "MPL-2.0",
@@ -32,23 +32,32 @@
       "default": "./dist/index.js"
     }
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./src/register-test-hooks.ts",
+    "./dist/register-test-hooks.js"
+  ],
   "files": [
     "dist",
     "src"
   ],
+  "engines": {
+    "node": ">=24"
+  },
   "dependencies": {
-    "@gtkx/ffi": "0.20.0",
-    "@gtkx/react": "0.20.0"
+    "@gtkx/runtime": "1.0.0-rc.1",
+    "@gtkx/utils": "1.0.0-rc.1",
+    "@gtkx/react": "1.0.0-rc.1"
   },
   "devDependencies": {
-    "@types/react-reconciler": "^0.33.0",
-    "react-reconciler": "^0.33.0",
-    "@gtkx/vitest": "0.20.0"
+    "@vitest/expect": "^4.1.10",
+    "vitest": "^4.1.10",
+    "@gtkx/config": "1.0.0-rc.1",
+    "@gtkx/components": "1.0.0-rc.1",
+    "@gtkx/vitest": "1.0.0-rc.1"
   },
   "scripts": {
-    "build": "tsc -b && cp ../../README.md .",
-    "test": "vitest run",
-    "typecheck": "tsc -b --emitDeclarationOnly"
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -b --emitDeclarationOnly",
+    "release": "tsx ../../scripts/release-package.ts"
   }
 }

package/src/act.ts

@@ -0,0 +1,68 @@
+import { act as reactAct } from "react";
+
+declare global {
+    var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;
+}
+
+const getGlobalThis = (): typeof globalThis => {
+    if (typeof globalThis !== "undefined") return globalThis;
+    throw new Error("unable to locate global object");
+};
+
+export const getIsReactActEnvironment = (): boolean | undefined => getGlobalThis().IS_REACT_ACT_ENVIRONMENT;
+
+export const setIsReactActEnvironment = (value: boolean | undefined): void => {
+    getGlobalThis().IS_REACT_ACT_ENVIRONMENT = value;
+};
+
+type ActCallback<T> = () => T | PromiseLike<T>;
+type ActImplementation = <T>(callback: ActCallback<T>) => PromiseLike<T>;
+
+const isThenable = <T>(value: unknown): value is PromiseLike<T> =>
+    value !== null && typeof value === "object" && typeof (value as PromiseLike<T>).then === "function";
+
+export const runWithActEnvironment = <T>(forced: boolean, fn: () => T | PromiseLike<T>): T | PromiseLike<T> => {
+    const previousActEnvironment = getIsReactActEnvironment();
+    setIsReactActEnvironment(forced);
+    try {
+        const result = fn();
+        if (isThenable<T>(result)) {
+            return Promise.resolve(result).then(
+                (value) => {
+                    setIsReactActEnvironment(previousActEnvironment);
+                    return value;
+                },
+                (error) => {
+                    setIsReactActEnvironment(previousActEnvironment);
+                    throw error;
+                },
+            );
+        }
+        setIsReactActEnvironment(previousActEnvironment);
+        return result;
+    } catch (error) {
+        setIsReactActEnvironment(previousActEnvironment);
+        throw error;
+    }
+};
+
+const withGlobalActEnvironment =
+    (actImplementation: ActImplementation) =>
+    <T>(callback: ActCallback<T>): PromiseLike<T> => {
+        const settled = runWithActEnvironment(true, () => actImplementation(() => callback()));
+        return Promise.resolve(settled);
+    };
+
+const actImplementation: ActImplementation = reactAct as ActImplementation;
+
+/**
+ * Runs a callback inside React's act environment, flushing pending state
+ * updates and effects, and resolves once the work has settled.
+ *
+ * @param callback Work to run within the act environment.
+ * @returns A promise that resolves with the callback's result after updates flush.
+ */
+export const act: ActImplementation = withGlobalActEnvironment(actImplementation);
+
+export const runInAct = (callback: () => unknown): Promise<void> =>
+    Promise.resolve(act(() => callback())).then(() => undefined);

package/src/bound-queries.ts

@@ -0,0 +1,36 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { ReactNode } from "react";
+import type { builtinQueries } from "./queries.js";
+import type { Container } from "./traversal.js";
+import type { BoundCustomQueries, DebugUtilities, QueryMap } from "./types.js";
+
+/**
+ * The set of built-in queries (getBy, findBy, queryBy, and their All variants)
+ * bound to a specific container.
+ */
+export type BoundQueries = BoundCustomQueries<typeof builtinQueries>;
+
+/**
+ * The global screen object's shape: built-in queries scoped to the current
+ * toplevels, plus debug utilities.
+ */
+export type Screen = BoundQueries & DebugUtilities;
+
+/**
+ * The result of a render call: queries scoped to the rendered tree, debug
+ * utilities, and controls for updating or tearing down the render.
+ *
+ * @typeParam Q Custom queries provided at render time, merged with the built-in ones.
+ */
+export type RenderResult<Q extends QueryMap = Record<never, never>> = BoundQueries &
+    BoundCustomQueries<Q> &
+    DebugUtilities & {
+        /** The top-level widget the element was rendered into. */
+        container: Gtk.Widget;
+        /** The root the queries are scoped to (defaults to all toplevels). */
+        baseElement: Container;
+        /** Unmounts the rendered tree and disposes its resources. */
+        unmount: () => Promise<void>;
+        /** Re-renders the tree with a new element, reusing the same root. */
+        rerender: (element: ReactNode) => Promise<void>;
+    };