@gtkx/testing 0.21.0 → 1.0.0-rc.2

package/src/pretty-widget.ts

@@ -1,201 +1,218 @@
-import * as Gtk from "@gtkx/ffi/gtk";
+import type * as Gtk from "@gtkx/gi/gtk";
+import { sortStringsBy } from "@gtkx/utils";
 import { formatRole } from "./role-helpers.js";
-import { type Container, isApplication } from "./traversal.js";
-import { getWidgetPropertyText } from "./widget-text.js";
+import { type Container, roots } from "./traversal.js";
+import { getWidgetNodeText } from "./widget-accessible-properties.js";
 
-const DEFAULT_MAX_LENGTH = 7000;
-const INDENT = "  ";
-
-const debugIdMap = new WeakMap<Gtk.Widget, string>();
-let nextDebugId = 0;
-
-const getWidgetDebugId = (widget: Gtk.Widget): string => {
-    let id = debugIdMap.get(widget);
-    if (!id) {
-        id = String(nextDebugId++);
-        debugIdMap.set(widget, id);
-    }
-    return id;
-};
+type WidgetIdResolver = (widget: Gtk.Widget) => string;
 
 /**
- * Options for {@link prettyWidget}.
+ * Options controlling how a widget tree is rendered to a string by
+ * {@link prettyWidget} and {@link logWidget}.
  */
-export type PrettyWidgetOptions = {
-    /** Maximum output length before truncation (default: 7000) */
+type PrettyWidgetOptions = {
+    /** Truncates the output once it exceeds this many characters. */
     maxLength?: number;
-    /** Enable ANSI color highlighting (default: auto-detect) */
+    /** Whether to apply ANSI color highlighting; defaults to the terminal capabilities. */
     highlight?: boolean;
-    /** Include widget IDs for MCP/agentic interactions (default: false) */
-    includeIds?: boolean;
+    /** Resolves an `id` attribute to show for each widget. */
+    getId?: WidgetIdResolver;
+    /** Stops descending past this depth, replacing deeper children with a summary line. */
+    maxDepth?: number;
 };
 
-type HighlightColors = {
+type Colors = {
     tag: (s: string) => string;
     attr: (s: string) => string;
     value: (s: string) => string;
-    text: (s: string) => string;
-    reset: string;
 };
 
-const shouldHighlight = (): boolean => {
-    if (typeof process === "undefined") return false;
-    if (process.env.COLORS === "false" || process.env.NO_COLOR) return false;
-    if (process.env.COLORS === "true" || process.env.FORCE_COLOR) return true;
-    return process.stdout?.isTTY ?? false;
+type FormatContext = {
+    getId: WidgetIdResolver | undefined;
+    colors: Colors;
+    maxDepth: number | undefined;
 };
 
-const ansi = {
-    cyan: "\x1b[36m",
-    yellow: "\x1b[33m",
-    green: "\x1b[32m",
-    reset: "\x1b[0m",
-};
-
-const createColors = (enabled: boolean): HighlightColors => {
-    if (!enabled) {
-        const identity = (s: string): string => s;
-        return { tag: identity, attr: identity, value: identity, text: identity, reset: "" };
-    }
-    return {
-        tag: (s) => `${ansi.cyan}${s}${ansi.reset}`,
-        attr: (s) => `${ansi.yellow}${s}${ansi.reset}`,
-        value: (s) => `${ansi.green}${s}${ansi.reset}`,
-        text: (s) => s,
-        reset: ansi.reset,
-    };
-};
-
-const formatTagName = (widget: Gtk.Widget): string => {
-    return widget.constructor.name;
-};
+const DEFAULT_MAX_LENGTH = 7000;
+const INDENT = "  ";
 
-const escapeAttrValue = (value: string): string => {
-    return value.replace(/"/g, "&quot;");
+const ansi = {
+    cyan: "\u{1B}[36m",
+    yellow: "\u{1B}[33m",
+    green: "\u{1B}[32m",
+    reset: "\u{1B}[0m",
 };
 
-const formatAttributes = (widget: Gtk.Widget, colors: HighlightColors, includeIds: boolean): string => {
+const buildAttrs = (widget: Gtk.Widget, getId: WidgetIdResolver | undefined): [string, string][] => {
     const attrs: [string, string][] = [];
 
-    if (includeIds) {
-        attrs.push(["id", getWidgetDebugId(widget)]);
+    if (getId) {
+        attrs.push(["id", getId(widget)]);
     }
 
     const name = widget.getName();
+
     if (name) {
         attrs.push(["name", name]);
     }
 
-    const role = widget.getAccessibleRole();
-    if (role !== undefined) {
-        attrs.push(["role", formatRole(role)]);
-    }
+    attrs.push(["role", formatRole(widget.getAccessibleRole())]);
 
     if (!widget.getSensitive()) {
-        attrs.push(["aria-disabled", "true"]);
+        attrs.push(["accessible-disabled", "true"]);
     }
 
     if (!widget.getVisible()) {
-        attrs.push(["aria-hidden", "true"]);
+        attrs.push(["accessible-hidden", "true"]);
     }
 
-    if (attrs.length === 0) return "";
+    const idAttrs = attrs.filter(([key]) => key === "id");
+
+    const otherAttrs = sortStringsBy(
+        attrs.filter(([key]) => key !== "id"),
+        ([key]) => key,
+    );
 
-    return attrs
-        .sort(([a], [b]) => {
-            if (a === "id") return -1;
-            if (b === "id") return 1;
-            return a.localeCompare(b);
-        })
-        .map(([key, value]) => ` ${colors.attr(key)}=${colors.value(`"${escapeAttrValue(value)}"`)}`)
-        .join("");
+    return [...idAttrs, ...otherAttrs];
 };
 
-const hasChildren = (widget: Gtk.Widget): boolean => {
-    return widget.getFirstChild() !== null;
+const shouldHighlight = (): boolean => {
+    if (typeof process === "undefined") {
+        return false;
+    }
+
+    if (process.env.COLORS === "false" || process.env.NO_COLOR) {
+        return false;
+    }
+
+    if (process.env.COLORS === "true" || process.env.FORCE_COLOR) {
+        return true;
+    }
+
+    return process.stdout.isTTY;
 };
 
-const printWidget = (widget: Gtk.Widget, colors: HighlightColors, depth: number, includeIds: boolean): string => {
-    const indent = INDENT.repeat(depth);
-    const tagName = formatTagName(widget);
-    const attributes = formatAttributes(widget, colors, includeIds);
-    const text = getWidgetPropertyText(widget);
-    const children: string[] = [];
+const createColors = (isEnabled: boolean): Colors => {
+    if (!isEnabled) {
+        const identity = (s: string): string => s;
+
+        return { tag: identity, attr: identity, value: identity };
+    }
+
+    return {
+        tag: (s) => `${ansi.cyan}${s}${ansi.reset}`,
+        attr: (s) => `${ansi.yellow}${s}${ansi.reset}`,
+        value: (s) => `${ansi.green}${s}${ansi.reset}`,
+    };
+};
+
+const escapeAttrValue = (value: string): string => value.replaceAll('"', "&quot;");
+
+const formatAttr = (key: string, value: string, colors: Colors): string => {
+    const quoted = `"${escapeAttrValue(value)}"`;
+
+    return ` ${colors.attr(key)}=${colors.value(quoted)}`;
+};
 
+const formatAttrs = (attrs: [string, string][], colors: Colors): string =>
+    attrs.map(([key, value]) => formatAttr(key, value, colors)).join("");
+
+const countChildren = (widget: Gtk.Widget): number => {
+    let count = 0;
     let child = widget.getFirstChild();
+
     while (child) {
-        children.push(printWidget(child, colors, depth + 1, includeIds));
+        count += 1;
         child = child.getNextSibling();
     }
 
-    const openTag = `${colors.tag("<")}${colors.tag(tagName)}${attributes}${colors.tag(">")}`;
+    return count;
+};
 
-    if (!hasChildren(widget) && !text) {
-        return `${indent}${openTag}\n`;
+const formatHiddenChildrenLine = (widget: Gtk.Widget, depth: number, ctx: FormatContext): string => {
+    const { getId, colors } = ctx;
+    const indent = INDENT.repeat(depth);
+    const count = countChildren(widget);
+    const hint = getId ? ` (pass rootId="${getId(widget)}" or raise maxDepth to expand)` : "";
+    const plural = count === 1 ? "" : "s";
+    const summary = `… ${String(count)} child widget${plural} hidden${hint}`;
+
+    return `${indent}${INDENT}${colors.tag(summary)}\n`;
+};
+
+const formatChildren = (widget: Gtk.Widget, depth: number, ctx: FormatContext): string => {
+    let output = "";
+    let child = widget.getFirstChild();
+
+    while (child) {
+        output += formatWidget(child, depth + 1, ctx);
+        child = child.getNextSibling();
     }
 
-    const closeTag = `${colors.tag("</")}${colors.tag(tagName)}${colors.tag(">")}`;
+    return output;
+};
 
-    if (text && !hasChildren(widget)) {
-        const textContent = colors.text(text);
-        return `${indent}${openTag}\n${indent}${INDENT}${textContent}\n${indent}${closeTag}\n`;
+const formatWidget = (widget: Gtk.Widget, depth: number, ctx: FormatContext): string => {
+    const { getId, colors, maxDepth } = ctx;
+    const indent = INDENT.repeat(depth);
+    const tag = widget.constructor.name;
+    const attrs = formatAttrs(buildAttrs(widget, getId), colors);
+    const openTag = `${colors.tag("<")}${colors.tag(tag)}${attrs}${colors.tag(">")}`;
+    const closeTag = `${colors.tag("</")}${colors.tag(tag)}${colors.tag(">")}`;
+    const text = getWidgetNodeText(widget);
+    const firstChild = widget.getFirstChild();
+
+    if (!text && !firstChild) {
+        return `${indent}${openTag}\n`;
     }
 
-    let result = `${indent}${openTag}\n`;
+    let output = `${indent}${openTag}\n`;
+
     if (text) {
-        result += `${indent}${INDENT}${colors.text(text)}\n`;
+        output += `${indent}${INDENT}${text}\n`;
     }
-    for (const childOutput of children) {
-        result += childOutput;
+
+    if (firstChild && maxDepth !== undefined && depth >= maxDepth) {
+        output += formatHiddenChildrenLine(widget, depth, ctx);
+        output += `${indent}${closeTag}\n`;
+
+        return output;
     }
-    result += `${indent}${closeTag}\n`;
 
-    return result;
+    output += formatChildren(widget, depth, ctx);
+    output += `${indent}${closeTag}\n`;
+
+    return output;
 };
 
-const printContainer = (container: Container, colors: HighlightColors, includeIds: boolean): string => {
-    if (isApplication(container)) {
-        const windows = Gtk.Window.listToplevels();
-        return windows.map((window) => printWidget(window, colors, 0, includeIds)).join("");
-    }
-    return printWidget(container, colors, 0, includeIds);
+const resolveMaxLength = (options: PrettyWidgetOptions): number => {
+    const envLimit = process.env.DEBUG_PRINT_LIMIT ? Number(process.env.DEBUG_PRINT_LIMIT) : DEFAULT_MAX_LENGTH;
+
+    return options.maxLength ?? envLimit;
 };
 
 /**
- * Formats a widget tree as a readable string for debugging.
- *
- * Renders the widget hierarchy in an HTML-like format with accessibility
- * attributes like role, name, and text content.
- *
- * @param container - The container widget or application to format
- * @param options - Formatting options for length and highlighting
- * @returns Formatted string representation of the widget tree
+ * Renders a widget tree as an indented, HTML-like string showing each widget's
+ * tag, accessible attributes, and text content.
  *
- * @example
- * ```tsx
- * import { prettyWidget } from "@gtkx/testing";
- *
- * console.log(prettyWidget(application));
- * // Output:
- * // <GtkApplicationWindow role="window">
- * //   <GtkButton role="button">
- * //     Click me
- * //   </GtkButton>
- * // </GtkApplicationWindow>
- * ```
+ * @param container The scope whose widget tree is formatted.
+ * @param options Formatting options such as truncation length and highlighting.
+ * @returns The formatted representation of the tree.
  */
-export const prettyWidget = (container: Container, options: PrettyWidgetOptions = {}): string => {
-    const envLimit = process.env.DEBUG_PRINT_LIMIT ? Number(process.env.DEBUG_PRINT_LIMIT) : DEFAULT_MAX_LENGTH;
-    const maxLength = options.maxLength ?? envLimit;
-    const highlight = options.highlight ?? shouldHighlight();
-    const includeIds = options.includeIds ?? false;
+const prettyWidget = (container: Container, options: PrettyWidgetOptions = {}): string => {
+    const maxLength = resolveMaxLength(options);
 
     if (maxLength === 0) {
         return "";
     }
 
-    const colors = createColors(highlight);
-    const output = printContainer(container, colors, includeIds);
+    const isHighlight = options.highlight ?? shouldHighlight();
+    const colors = createColors(isHighlight);
+    let output = "";
+
+    for (const root of roots(container)) {
+        output += formatWidget(root, 0, { getId: options.getId, colors, maxDepth: options.maxDepth });
+    }
 
     if (output.length > maxLength) {
         return `${output.slice(0, maxLength)}...`;
@@ -203,3 +220,19 @@ export const prettyWidget = (container: Container, options: PrettyWidgetOptions
 
     return output.trimEnd();
 };
+
+/**
+ * Prints one or more widget trees to the console using {@link prettyWidget}.
+ *
+ * @param container A single scope or an array of scopes to format and print.
+ * @param options Formatting options passed through to {@link prettyWidget}.
+ */
+const logWidget = (container: Container | Container[], options?: PrettyWidgetOptions): void => {
+    const containers: Container[] = Array.isArray(container) ? container : [container];
+
+    for (const target of containers) {
+        console.log(prettyWidget(target, options));
+    }
+};
+
+export { prettyWidget, logWidget, type PrettyWidgetOptions };