@gtkx/testing 0.21.0 → 1.0.0-rc.2

package/dist/render.js

@@ -1,147 +1,164 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { start, stop } from "@gtkx/ffi";
-import * as Gio from "@gtkx/ffi/gio";
-import { ApplicationContext, GtkApplicationWindow, reconciler } from "@gtkx/react";
-import { createRef } from "react";
-import { bindQueries } from "./bind-queries.js";
-import { prettyWidget } from "./pretty-widget.js";
-import { setScreenRoot } from "./screen.js";
-import { tick } from "./timing.js";
-import { isApplication, traverse } from "./traversal.js";
-let application = null;
-let container = null;
-let lastRenderError = null;
-const update = async (instance, element, fiberRoot) => {
-    lastRenderError = null;
-    instance.updateContainer(element, fiberRoot, null, () => { });
-    await tick();
-    if (lastRenderError) {
-        const error = lastRenderError;
-        lastRenderError = null;
-        throw error;
+import * as Gtk from "@gtkx/gi/gtk";
+import { createReconcilerRoot, isRootElement, setReconcilerErrorHandler, } from "@gtkx/react/internal";
+import { StrictMode } from "react";
+import { runInAct } from "./act.js";
+import { addToCleanupQueue, runCleanup } from "./cleanup-registry.js";
+import { scheduleAfterLayout } from "./frame-sync.js";
+import { logWidget } from "./pretty-widget.js";
+import { logRoles } from "./role-helpers.js";
+import { clearScreen, setScreen } from "./screen.js";
+import { captureAndSaveScreenshot } from "./screenshot.js";
+import { TOPLEVELS, traverse } from "./traversal.js";
+import { resetClipboard } from "./user-event/index.js";
+import { within } from "./within.js";
+const reconcilerErrors = { lastError: null, isHandlerInstalled: false };
+const activeRenders = new Set();
+const HARNESS_WINDOW_WIDTH = 800;
+const HARNESS_WINDOW_HEIGHT = 600;
+const flushLayout = (window) => new Promise((resolve) => {
+    scheduleAfterLayout(window, resolve);
+});
+const update = async (element, root) => {
+    await runInAct(() => {
+        root.update(element);
+    });
+    if (reconcilerErrors.lastError) {
+        const captured = reconcilerErrors.lastError;
+        reconcilerErrors.lastError = null;
+        throw captured;
+    }
+};
+const disposeActiveRender = async (active) => {
+    if (!activeRenders.delete(active)) {
+        return;
+    }
+    await active.root.unmount(async (root) => {
+        await update(null, root);
+        active.window?.destroy();
+    });
+};
+const disposeAllActiveRenders = async () => {
+    for (const active of activeRenders) {
+        await disposeActiveRender(active);
     }
 };
 const handleError = (error) => {
-    lastRenderError = error;
+    reconcilerErrors.lastError = error instanceof Error ? error : new Error(String(error));
 };
-const ensureInitialized = () => {
-    application = start("org.gtkx.testing", Gio.ApplicationFlags.NON_UNIQUE);
-    if (!container) {
-        const instance = reconciler.getInstance();
-        container = instance.createContainer(application, 1, null, false, null, "", handleError, handleError, () => { }, () => { });
+const installErrorHandler = () => {
+    if (reconcilerErrors.isHandlerInstalled) {
+        return;
     }
-    return { app: application, container };
+    setReconcilerErrorHandler(handleError);
+    reconcilerErrors.isHandlerInstalled = true;
 };
-const DefaultWrapper = ({ children, ref }) => (_jsx(GtkApplicationWindow, { ref: ref, defaultWidth: 800, defaultHeight: 600, children: children }));
-const findFirstWidget = (root) => {
-    for (const widget of traverse(root)) {
-        if (isApplication(root))
-            return widget;
-        return root;
+const resolveContainer = (container) => {
+    if (isRootElement(container)) {
+        return { containerInfo: container, window: null };
+    }
+    if (container instanceof Gtk.Widget) {
+        return { containerInfo: container, window: null };
     }
-    return null;
+    const window = new Gtk.Window({ defaultWidth: HARNESS_WINDOW_WIDTH, defaultHeight: HARNESS_WINDOW_HEIGHT });
+    window.setTitlebar(new Gtk.HeaderBar({ showTitleButtons: false }));
+    return { containerInfo: window, window };
 };
-const wrapElement = (element, wrapperRef, wrapper) => {
-    if (wrapper === false || wrapper === undefined)
-        return element;
-    const Wrapper = wrapper === true ? DefaultWrapper : wrapper;
-    return _jsx(Wrapper, { ref: wrapperRef, children: element });
+const firstToplevelWidget = (baseElement) => {
+    if (baseElement instanceof Gtk.Widget) {
+        return baseElement;
+    }
+    const [first] = traverse(baseElement);
+    if (first) {
+        return first;
+    }
+    throw new Error("render() produced no widgets: ensure the element renders visible content");
 };
-const resolveContainer = (wrapper, wrapperRef, baseElement) => {
-    if (wrapper !== false && wrapper !== undefined && wrapperRef.current) {
-        return wrapperRef.current;
+const resolveResultContainer = (resolved, container, baseElement) => {
+    if (resolved.window) {
+        return resolved.window;
+    }
+    if (container instanceof Gtk.Widget) {
+        return container;
     }
-    const firstWidget = findFirstWidget(baseElement);
-    if (!firstWidget) {
-        throw new Error("render() produced no widgets: ensure the element renders visible content");
+    return firstToplevelWidget(baseElement);
+};
+const renderErrorHandlers = (options) => ({
+    onUncaughtError: handleError,
+    onCaughtError: (error, errorInfo) => {
+        handleError(error);
+        options?.onCaughtError?.(error, errorInfo);
+    },
+    onRecoverableError: (error, errorInfo) => {
+        options?.onRecoverableError?.(error, errorInfo);
+    },
+});
+const applyEnableAnimations = (areAnimationsEnabled) => {
+    const settings = Gtk.Settings.getDefault();
+    if (settings) {
+        settings.gtkEnableAnimations = areAnimationsEnabled;
     }
-    return firstWidget;
 };
 /**
- * Renders a React element for testing.
- *
- * Creates a GTK application context and renders the element, returning
- * query methods and utilities for interacting with the rendered widgets.
- *
- * @param element - The React element to render
- * @param options - Render options including wrapper configuration
- * @returns A promise resolving to query methods and utilities
- *
- * @example
- * ```tsx
- * import { render, screen } from "@gtkx/testing";
+ * Renders a React element into a GTK4 widget tree and returns queries
+ * scoped to it along with controls for rerendering and unmounting. When no
+ * container is supplied, a harness window is created and presented.
  *
- * test("button click", async () => {
- * await render(<MyButton />);
- * const button = await screen.findByRole(Gtk.AccessibleRole.BUTTON);
- * await userEvent.click(button);
- * });
- * ```
- *
- * @see {@link cleanup} for cleaning up after tests
- * @see {@link screen} for global query access
+ * @param element The React element to render.
+ * @param options Optional container, wrapper, custom queries, and other render settings.
+ * @returns A render result with bound queries, debug helpers, and lifecycle controls.
  */
-export const render = async (element, options) => {
-    const { app: application, container: fiberRoot } = ensureInitialized();
-    const instance = reconciler.getInstance();
-    const baseElement = options?.baseElement ?? application;
-    const wrapper = options?.wrapper ?? true;
-    const wrapperRef = createRef();
-    const wrappedElement = wrapElement(element, wrapperRef, wrapper);
-    const withContext = _jsx(ApplicationContext.Provider, { value: application, children: wrappedElement });
-    await update(instance, withContext, fiberRoot);
-    setScreenRoot(application);
-    return {
-        container: resolveContainer(wrapper, wrapperRef, baseElement),
+const render = async (element, options) => {
+    installErrorHandler();
+    applyEnableAnimations(options?.animations === true);
+    const baseElement = options?.baseElement ?? TOPLEVELS;
+    const Wrapper = options?.wrapper;
+    const resolved = resolveContainer(options?.container);
+    const root = createReconcilerRoot({
+        containerInfo: resolved.containerInfo,
+        ...renderErrorHandlers(options),
+    });
+    const active = { root, window: resolved.window };
+    activeRenders.add(active);
+    addToCleanupQueue(disposeAllActiveRenders);
+    addToCleanupQueue(clearScreen);
+    addToCleanupQueue(resetClipboard);
+    const wrap = (node) => {
+        const wrapped = Wrapper ? _jsx(Wrapper, { children: node }) : node;
+        return options?.reactStrictMode ? _jsx(StrictMode, { children: wrapped }) : wrapped;
+    };
+    await update(wrap(element), root);
+    resolved.window?.present();
+    await flushLayout(resolved.window);
+    const container = resolveResultContainer(resolved, options?.container, baseElement);
+    const result = {
+        ...within(baseElement, options?.queries),
+        container,
         baseElement,
-        ...bindQueries(baseElement),
-        unmount: () => update(instance, null, fiberRoot),
+        unmount: async () => {
+            await disposeActiveRender(active);
+        },
         rerender: async (newElement) => {
-            const newWrapperRef = createRef();
-            const wrapped = wrapElement(newElement, newWrapperRef, wrapper);
-            const withCtx = _jsx(ApplicationContext.Provider, { value: application, children: wrapped });
-            await update(instance, withCtx, fiberRoot);
+            await update(wrap(newElement), root);
+            await flushLayout(resolved.window);
         },
-        debug: () => {
-            console.log(prettyWidget(application));
+        debug: (element = baseElement, debugOptions) => {
+            logWidget(element, debugOptions);
         },
+        logRoles: () => {
+            logRoles(baseElement);
+        },
+        screenshot: (selector, screenshotOptions) => captureAndSaveScreenshot(selector, screenshotOptions),
     };
+    setScreen(result);
+    return result;
 };
 /**
- * Cleans up the rendered component tree.
- *
- * Unmounts all rendered components and resets the testing environment.
- * Call this in `afterEach` to ensure tests don't affect each other.
- *
- * @example
- * ```tsx
- * import { render, cleanup } from "@gtkx/testing";
- *
- * afterEach(async () => {
- * await cleanup();
- * });
- *
- * test("my test", async () => {
- * await render(<MyComponent />);
- * // ...
- * });
- * ```
+ * Unmounts every active render and runs all registered cleanup callbacks,
+ * resetting the screen and clipboard. Called automatically after each test.
  */
-export const cleanup = async () => {
-    if (container && application) {
-        const instance = reconciler.getInstance();
-        await update(instance, null, container);
-    }
-    container = null;
-    setScreenRoot(null);
-};
-const handleSignal = () => {
-    try {
-        stop();
-    }
-    catch { }
-    process.exit(0);
+const cleanup = async () => {
+    await runCleanup();
 };
-process.on("SIGTERM", handleSignal);
-process.on("SIGINT", handleSignal);
+export { render, cleanup };
 //# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -1 +1 @@
-{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.tsx"],"names":[],"mappings":"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","sourcesContent":["import type { RootElement } from \"@gtkx/react\";\nimport * as Gtk from \"@gtkx/gi/gtk\";\nimport {\n    createReconcilerRoot,\n    isRootElement,\n    type ReconcilerRoot,\n    setReconcilerErrorHandler,\n} from \"@gtkx/react/internal\";\nimport { type ErrorInfo, type ReactNode, StrictMode } from \"react\";\nimport type { RenderResult } from \"./bound-queries.js\";\nimport type { QueryMap, RenderOptions, ScreenshotOptions, WindowSelector } from \"./types.js\";\nimport { runInAct } from \"./act.js\";\nimport { addToCleanupQueue, runCleanup } from \"./cleanup-registry.js\";\nimport { scheduleAfterLayout } from \"./frame-sync.js\";\nimport { logWidget, type PrettyWidgetOptions } from \"./pretty-widget.js\";\nimport { logRoles } from \"./role-helpers.js\";\nimport { clearScreen, setScreen } from \"./screen.js\";\nimport { captureAndSaveScreenshot } from \"./screenshot.js\";\nimport { type Container, TOPLEVELS, traverse } from \"./traversal.js\";\nimport { resetClipboard } from \"./user-event/index.js\";\nimport { within } from \"./within.js\";\n\ntype ActiveRender = {\n    root: ReconcilerRoot;\n    window: Gtk.Window | null;\n};\n\ntype ResolvedContainer = {\n    containerInfo: Gtk.Widget | RootElement;\n    window: Gtk.Window | null;\n};\n\ntype ReconcilerErrorState = {\n    lastError: Error | null;\n    isHandlerInstalled: boolean;\n};\n\nconst reconcilerErrors: ReconcilerErrorState = { lastError: null, isHandlerInstalled: false };\nconst activeRenders: Set<ActiveRender> = new Set();\nconst HARNESS_WINDOW_WIDTH = 800;\nconst HARNESS_WINDOW_HEIGHT = 600;\n\nconst flushLayout = (window: Gtk.Window | null): Promise<void> =>\n    new Promise((resolve) => {\n        scheduleAfterLayout(window, resolve);\n    });\n\nconst update = async (element: ReactNode, root: ReconcilerRoot): Promise<void> => {\n    await runInAct(() => {\n        root.update(element);\n    });\n\n    if (reconcilerErrors.lastError) {\n        const captured = reconcilerErrors.lastError;\n        reconcilerErrors.lastError = null;\n        throw captured;\n    }\n};\n\nconst disposeActiveRender = async (active: ActiveRender): Promise<void> => {\n    if (!activeRenders.delete(active)) {\n        return;\n    }\n\n    await active.root.unmount(async (root) => {\n        await update(null, root);\n        active.window?.destroy();\n    });\n};\n\nconst disposeAllActiveRenders = async (): Promise<void> => {\n    for (const active of activeRenders) {\n        await disposeActiveRender(active);\n    }\n};\n\nconst handleError = (error: unknown): void => {\n    reconcilerErrors.lastError = error instanceof Error ? error : new Error(String(error));\n};\n\nconst installErrorHandler = (): void => {\n    if (reconcilerErrors.isHandlerInstalled) {\n        return;\n    }\n\n    setReconcilerErrorHandler(handleError);\n    reconcilerErrors.isHandlerInstalled = true;\n};\n\nconst resolveContainer = (container: RenderOptions[\"container\"]): ResolvedContainer => {\n    if (isRootElement(container)) {\n        return { containerInfo: container, window: null };\n    }\n\n    if (container instanceof Gtk.Widget) {\n        return { containerInfo: container, window: null };\n    }\n\n    const window = new Gtk.Window({ defaultWidth: HARNESS_WINDOW_WIDTH, defaultHeight: HARNESS_WINDOW_HEIGHT });\n    window.setTitlebar(new Gtk.HeaderBar({ showTitleButtons: false }));\n\n    return { containerInfo: window, window };\n};\n\nconst firstToplevelWidget = (baseElement: Container): Gtk.Widget => {\n    if (baseElement instanceof Gtk.Widget) {\n        return baseElement;\n    }\n\n    const [first] = traverse(baseElement);\n\n    if (first) {\n        return first;\n    }\n\n    throw new Error(\"render() produced no widgets: ensure the element renders visible content\");\n};\n\nconst resolveResultContainer = (\n    resolved: ResolvedContainer,\n    container: RenderOptions[\"container\"],\n    baseElement: Container,\n): Gtk.Widget => {\n    if (resolved.window) {\n        return resolved.window;\n    }\n\n    if (container instanceof Gtk.Widget) {\n        return container;\n    }\n\n    return firstToplevelWidget(baseElement);\n};\n\nconst renderErrorHandlers = <Q extends QueryMap>(options: RenderOptions<Q> | undefined) => ({\n    onUncaughtError: handleError,\n    onCaughtError: (error: unknown, errorInfo: ErrorInfo): void => {\n        handleError(error);\n        options?.onCaughtError?.(error, errorInfo);\n    },\n    onRecoverableError: (error: unknown, errorInfo: ErrorInfo): void => {\n        options?.onRecoverableError?.(error, errorInfo);\n    },\n});\n\nconst applyEnableAnimations = (areAnimationsEnabled: boolean): void => {\n    const settings = Gtk.Settings.getDefault();\n\n    if (settings) {\n        settings.gtkEnableAnimations = areAnimationsEnabled;\n    }\n};\n\n/**\n * Renders a React element into a GTK4 widget tree and returns queries\n * scoped to it along with controls for rerendering and unmounting. When no\n * container is supplied, a harness window is created and presented.\n *\n * @param element The React element to render.\n * @param options Optional container, wrapper, custom queries, and other render settings.\n * @returns A render result with bound queries, debug helpers, and lifecycle controls.\n */\nconst render = async <Q extends QueryMap = Record<never, never>>(\n    element: ReactNode,\n    options?: RenderOptions<Q>,\n): Promise<RenderResult<Q>> => {\n    installErrorHandler();\n    applyEnableAnimations(options?.animations === true);\n    const baseElement: Container = options?.baseElement ?? TOPLEVELS;\n    const Wrapper = options?.wrapper;\n    const resolved = resolveContainer(options?.container);\n\n    const root = createReconcilerRoot({\n        containerInfo: resolved.containerInfo,\n        ...renderErrorHandlers(options),\n    });\n\n    const active: ActiveRender = { root, window: resolved.window };\n    activeRenders.add(active);\n    addToCleanupQueue(disposeAllActiveRenders);\n    addToCleanupQueue(clearScreen);\n    addToCleanupQueue(resetClipboard);\n\n    const wrap = (node: ReactNode): ReactNode => {\n        const wrapped = Wrapper ? <Wrapper>{node}</Wrapper> : node;\n\n        return options?.reactStrictMode ? <StrictMode>{wrapped}</StrictMode> : wrapped;\n    };\n\n    await update(wrap(element), root);\n    resolved.window?.present();\n    await flushLayout(resolved.window);\n    const container = resolveResultContainer(resolved, options?.container, baseElement);\n\n    const result: RenderResult<Q> = {\n        ...within(baseElement, options?.queries),\n        container,\n        baseElement,\n        unmount: async () => {\n            await disposeActiveRender(active);\n        },\n        rerender: async (newElement: ReactNode) => {\n            await update(wrap(newElement), root);\n            await flushLayout(resolved.window);\n        },\n        debug: (element: Container | Container[] = baseElement, debugOptions?: PrettyWidgetOptions) => {\n            logWidget(element, debugOptions);\n        },\n        logRoles: () => {\n            logRoles(baseElement);\n        },\n        screenshot: (selector?: WindowSelector, screenshotOptions?: ScreenshotOptions) =>\n            captureAndSaveScreenshot(selector, screenshotOptions),\n    };\n\n    setScreen(result);\n\n    return result;\n};\n\n/**\n * Unmounts every active render and runs all registered cleanup callbacks,\n * resetting the screen and clipboard. Called automatically after each test.\n */\nconst cleanup = async (): Promise<void> => {\n    await runCleanup();\n};\n\nexport { render, cleanup };\n"]}

package/dist/role-helpers.d.ts

@@ -1,67 +1,33 @@
-import * as Gtk from "@gtkx/ffi/gtk";
+import * as Gtk from "@gtkx/gi/gtk";
 import { type Container } from "./traversal.js";
 /**
- * Information about a widget and its accessible name.
- */
-export type RoleInfo = {
-    widget: Gtk.Widget;
-    name: string | null;
-};
-/**
- * Formats a GTK accessible role to a lowercase string.
+ * Converts an accessible role enum value into its lowercase name, falling back
+ * to the numeric value when the role is unknown.
  *
- * @param role - The GTK accessible role
- * @returns Lowercase role name (e.g., "button", "checkbox")
+ * @param role The accessible role to format.
  */
-export declare const formatRole: (role: Gtk.AccessibleRole | undefined) => string;
+declare const formatRole: (role: Gtk.AccessibleRole) => string;
+declare const formatRoleList: (roles: Iterable<Gtk.AccessibleRole>) => string;
 /**
- * Collects all accessible roles and their widgets from a container.
- *
- * Returns a Map where keys are role names (lowercase) and values are
- * arrays of widgets with that role, including their accessible names.
- *
- * @param container - The container to scan for roles
- * @returns Map of role names to arrays of RoleInfo
+ * Groups every widget in a container's tree by its accessible role name.
  *
- * @example
- * ```tsx
- * import { getRoles } from "@gtkx/testing";
- *
- * const roles = getRoles(container);
- * // Map {
- * //   "button" => [{ widget: ..., name: "Submit" }, { widget: ..., name: "Cancel" }],
- * //   "checkbox" => [{ widget: ..., name: "Remember me" }]
- * // }
- * ```
+ * @param container The scope to traverse.
+ * @returns A map from role name to the widgets that have that role.
  */
-export declare const getRoles: (container: Container) => Map<string, RoleInfo[]>;
+declare const getRoles: (container: Container) => Map<string, Gtk.Widget[]>;
 /**
- * Formats roles into a readable string for error messages.
+ * Formats the accessible roles in a container's tree as a readable string,
+ * listing each role together with its widgets and their accessible names.
  *
- * @param container - The container to format roles for
- * @returns Formatted string showing all roles and their accessible names
+ * @param container The scope to inspect.
  */
-export declare const prettyRoles: (container: Container) => string;
+declare const prettyRoles: (container: Container) => string;
 /**
- * Logs all accessible roles in a container to the console.
- *
- * Useful for debugging test failures and discovering available roles.
- *
- * @param container - The container to log roles for
- *
- * @example
- * ```tsx
- * import { render, logRoles } from "@gtkx/testing";
+ * Prints the accessible roles in a container's tree to the console using
+ * {@link prettyRoles}.
  *
- * const { container } = await render(<MyComponent />);
- * logRoles(container);
- * // Console output:
- * // button:
- * //   Name "Submit": <GtkButton role="button">Submit</GtkButton>
- * //   Name "Cancel": <GtkButton role="button">Cancel</GtkButton>
- * // checkbox:
- * //   Name "Remember me": <GtkCheckButton role="checkbox">Remember me</GtkCheckButton>
- * ```
+ * @param container The scope to inspect.
  */
-export declare const logRoles: (container: Container) => void;
+declare const logRoles: (container: Container) => void;
+export { formatRole, formatRoleList, getRoles, prettyRoles, logRoles };
 //# sourceMappingURL=role-helpers.d.ts.map

package/dist/role-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role-helpers.d.ts","sourceRoot":"","sources":["../src/role-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,KAAK,SAAS,EAAY,MAAM,gBAAgB,CAAC;AAG1D;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG;IACnB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,GAAG,CAAC,cAAc,GAAG,SAAS,KAAG,MAKjE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,SAAS,KAAG,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAoBrE,CAAC;AASF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,WAAW,SAAS,KAAG,MAoBlD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,SAAS,KAAG,IAE/C,CAAC"}
+{"version":3,"file":"role-helpers.d.ts","sourceRoot":"","sources":["../src/role-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,cAAc,CAAC;AAEpC,OAAO,EAAE,KAAK,SAAS,EAAY,MAAM,gBAAgB,CAAC;AAa1D;;;;;GAKG;AACH,QAAA,MAAM,UAAU,GAAI,MAAM,GAAG,CAAC,cAAc,KAAG,MAQ9C,CAAC;AAEF,QAAA,MAAM,cAAc,GAAI,OAAO,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC,KAAG,MAe7D,CAAC;AAEF;;;;;GAKG;AACH,QAAA,MAAM,QAAQ,GAAI,WAAW,SAAS,KAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAehE,CAAC;AAUF;;;;;GAKG;AACH,QAAA,MAAM,WAAW,GAAI,WAAW,SAAS,KAAG,MAqB3C,CAAC;AAEF;;;;;GAKG;AACH,QAAA,MAAM,QAAQ,GAAI,WAAW,SAAS,KAAG,IAExC,CAAC;AAEF,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC"}

package/dist/role-helpers.js

@@ -1,109 +1,94 @@
-import * as Gtk from "@gtkx/ffi/gtk";
+import * as Gtk from "@gtkx/gi/gtk";
+import { sortStringsBy } from "@gtkx/utils";
 import { traverse } from "./traversal.js";
-import { getWidgetAccessibleName } from "./widget-text.js";
+import { getWidgetAccessibleName } from "./widget-accessible-properties.js";
+const ROLE_NAMES_BY_VALUE = enumNamesByValue(Gtk.AccessibleRole);
+function enumNamesByValue(enumObject) {
+    return new Map(Object.entries(enumObject)
+        .filter((entry) => typeof entry[1] === "number")
+        .map(([name, value]) => [value, name]));
+}
 /**
- * Formats a GTK accessible role to a lowercase string.
+ * Converts an accessible role enum value into its lowercase name, falling back
+ * to the numeric value when the role is unknown.
  *
- * @param role - The GTK accessible role
- * @returns Lowercase role name (e.g., "button", "checkbox")
+ * @param role The accessible role to format.
  */
-export const formatRole = (role) => {
-    if (role === undefined)
-        return "unknown";
-    const name = Gtk.AccessibleRole[role];
-    if (!name)
+const formatRole = (role) => {
+    const name = ROLE_NAMES_BY_VALUE.get(role);
+    if (!name) {
         return String(role);
+    }
     return name.toLowerCase();
 };
+const formatRoleList = (roles) => {
+    const names = [...roles].map((role) => formatRole(role).toUpperCase());
+    if (names.length <= 1) {
+        return names.join("");
+    }
+    if (names.length === 2) {
+        return names.join(" or ");
+    }
+    const head = names.slice(0, -1);
+    const last = names.at(-1) ?? "";
+    return `${head.join(", ")}, or ${last}`;
+};
 /**
- * Collects all accessible roles and their widgets from a container.
- *
- * Returns a Map where keys are role names (lowercase) and values are
- * arrays of widgets with that role, including their accessible names.
+ * Groups every widget in a container's tree by its accessible role name.
  *
- * @param container - The container to scan for roles
- * @returns Map of role names to arrays of RoleInfo
- *
- * @example
- * ```tsx
- * import { getRoles } from "@gtkx/testing";
- *
- * const roles = getRoles(container);
- * // Map {
- * //   "button" => [{ widget: ..., name: "Submit" }, { widget: ..., name: "Cancel" }],
- * //   "checkbox" => [{ widget: ..., name: "Remember me" }]
- * // }
- * ```
+ * @param container The scope to traverse.
+ * @returns A map from role name to the widgets that have that role.
  */
-export const getRoles = (container) => {
+const getRoles = (container) => {
     const roles = new Map();
     for (const widget of traverse(container)) {
-        const role = widget.getAccessibleRole?.();
-        if (role === undefined)
-            continue;
-        const roleName = formatRole(role);
-        const name = getWidgetAccessibleName(widget);
-        const info = { widget, name };
+        const roleName = formatRole(widget.getAccessibleRole());
         const existing = roles.get(roleName);
         if (existing) {
-            existing.push(info);
+            existing.push(widget);
         }
         else {
-            roles.set(roleName, [info]);
+            roles.set(roleName, [widget]);
         }
     }
     return roles;
 };
 const formatWidgetPreview = (widget, name) => {
     const tagName = widget.constructor.name;
-    const roleAttr = formatRole(widget.getAccessibleRole?.());
+    const roleAttr = formatRole(widget.getAccessibleRole());
     const nameDisplay = name ? `Name "${name}"` : 'Name ""';
     return `${nameDisplay}: <${tagName} role="${roleAttr}">${name ?? ""}</${tagName}>`;
 };
 /**
- * Formats roles into a readable string for error messages.
+ * Formats the accessible roles in a container's tree as a readable string,
+ * listing each role together with its widgets and their accessible names.
  *
- * @param container - The container to format roles for
- * @returns Formatted string showing all roles and their accessible names
+ * @param container The scope to inspect.
  */
-export const prettyRoles = (container) => {
+const prettyRoles = (container) => {
     const roles = getRoles(container);
     if (roles.size === 0) {
         return "No accessible roles found in the widget tree.";
     }
     const lines = [];
-    const sortedRoles = [...roles.entries()].sort(([a], [b]) => a.localeCompare(b));
+    const sortedRoles = sortStringsBy([...roles], ([roleName]) => roleName);
     for (const [roleName, widgets] of sortedRoles) {
         lines.push(`${roleName}:`);
-        for (const { widget, name } of widgets) {
-            lines.push(`  ${formatWidgetPreview(widget, name)}`);
+        for (const widget of widgets) {
+            lines.push(`  ${formatWidgetPreview(widget, getWidgetAccessibleName(widget))}`);
         }
         lines.push("");
     }
     return lines.join("\n").trimEnd();
 };
 /**
- * Logs all accessible roles in a container to the console.
- *
- * Useful for debugging test failures and discovering available roles.
- *
- * @param container - The container to log roles for
- *
- * @example
- * ```tsx
- * import { render, logRoles } from "@gtkx/testing";
+ * Prints the accessible roles in a container's tree to the console using
+ * {@link prettyRoles}.
  *
- * const { container } = await render(<MyComponent />);
- * logRoles(container);
- * // Console output:
- * // button:
- * //   Name "Submit": <GtkButton role="button">Submit</GtkButton>
- * //   Name "Cancel": <GtkButton role="button">Cancel</GtkButton>
- * // checkbox:
- * //   Name "Remember me": <GtkCheckButton role="checkbox">Remember me</GtkCheckButton>
- * ```
+ * @param container The scope to inspect.
  */
-export const logRoles = (container) => {
+const logRoles = (container) => {
     console.log(prettyRoles(container));
 };
+export { formatRole, formatRoleList, getRoles, prettyRoles, logRoles };
 //# sourceMappingURL=role-helpers.js.map

package/dist/role-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"role-helpers.js","sourceRoot":"","sources":["../src/role-helpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"role-helpers.js","sourceRoot":"","sources":["../src/role-helpers.ts"],"names":[],"mappings":"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","sourcesContent":["import * as Gtk from \"@gtkx/gi/gtk\";\nimport { sortStringsBy } from \"@gtkx/utils\";\nimport { type Container, traverse } from \"./traversal.js\";\nimport { getWidgetAccessibleName } from \"./widget-accessible-properties.js\";\n\nconst ROLE_NAMES_BY_VALUE = enumNamesByValue(Gtk.AccessibleRole);\n\nfunction enumNamesByValue(enumObject: Record<string, string | number>): Map<number, string> {\n    return new Map<number, string>(\n        Object.entries(enumObject)\n            .filter((entry): entry is [string, number] => typeof entry[1] === \"number\")\n            .map(([name, value]) => [value, name]),\n    );\n}\n\n/**\n * Converts an accessible role enum value into its lowercase name, falling back\n * to the numeric value when the role is unknown.\n *\n * @param role The accessible role to format.\n */\nconst formatRole = (role: Gtk.AccessibleRole): string => {\n    const name = ROLE_NAMES_BY_VALUE.get(role);\n\n    if (!name) {\n        return String(role);\n    }\n\n    return name.toLowerCase();\n};\n\nconst formatRoleList = (roles: Iterable<Gtk.AccessibleRole>): string => {\n    const names = [...roles].map((role) => formatRole(role).toUpperCase());\n\n    if (names.length <= 1) {\n        return names.join(\"\");\n    }\n\n    if (names.length === 2) {\n        return names.join(\" or \");\n    }\n\n    const head = names.slice(0, -1);\n    const last = names.at(-1) ?? \"\";\n\n    return `${head.join(\", \")}, or ${last}`;\n};\n\n/**\n * Groups every widget in a container's tree by its accessible role name.\n *\n * @param container The scope to traverse.\n * @returns A map from role name to the widgets that have that role.\n */\nconst getRoles = (container: Container): Map<string, Gtk.Widget[]> => {\n    const roles: Map<string, Gtk.Widget[]> = new Map();\n\n    for (const widget of traverse(container)) {\n        const roleName = formatRole(widget.getAccessibleRole());\n        const existing = roles.get(roleName);\n\n        if (existing) {\n            existing.push(widget);\n        } else {\n            roles.set(roleName, [widget]);\n        }\n    }\n\n    return roles;\n};\n\nconst formatWidgetPreview = (widget: Gtk.Widget, name: string | null): string => {\n    const tagName = widget.constructor.name;\n    const roleAttr = formatRole(widget.getAccessibleRole());\n    const nameDisplay = name ? `Name \"${name}\"` : 'Name \"\"';\n\n    return `${nameDisplay}: <${tagName} role=\"${roleAttr}\">${name ?? \"\"}</${tagName}>`;\n};\n\n/**\n * Formats the accessible roles in a container's tree as a readable string,\n * listing each role together with its widgets and their accessible names.\n *\n * @param container The scope to inspect.\n */\nconst prettyRoles = (container: Container): string => {\n    const roles = getRoles(container);\n\n    if (roles.size === 0) {\n        return \"No accessible roles found in the widget tree.\";\n    }\n\n    const lines: string[] = [];\n    const sortedRoles = sortStringsBy([...roles], ([roleName]) => roleName);\n\n    for (const [roleName, widgets] of sortedRoles) {\n        lines.push(`${roleName}:`);\n\n        for (const widget of widgets) {\n            lines.push(`  ${formatWidgetPreview(widget, getWidgetAccessibleName(widget))}`);\n        }\n\n        lines.push(\"\");\n    }\n\n    return lines.join(\"\\n\").trimEnd();\n};\n\n/**\n * Prints the accessible roles in a container's tree to the console using\n * {@link prettyRoles}.\n *\n * @param container The scope to inspect.\n */\nconst logRoles = (container: Container): void => {\n    console.log(prettyRoles(container));\n};\n\nexport { formatRole, formatRoleList, getRoles, prettyRoles, logRoles };\n"]}