@gtkx/react 0.1.48 → 0.1.50

package/README.md

@@ -159,7 +159,9 @@ Query types: `ByRole`, `ByText`, `ByLabelText`, `ByTestId`
 - `userEvent.activate(element)` - Activate element (e.g., press Enter in input)
 - `userEvent.type(element, text)` - Type text into input
 - `userEvent.clear(element)` - Clear input text
-- `userEvent.setup()` - Create reusable instance
+- `userEvent.tab(element, options?)` - Simulate Tab navigation
+- `userEvent.selectOptions(element, values)` - Select options in ComboBox/ListBox
+- `userEvent.deselectOptions(element, values)` - Deselect options in ListBox
 
 **Low-level Events**:
 - `fireEvent(element, signalName, ...args)` - Emit any GTK signal with optional arguments
@@ -170,14 +172,6 @@ Query types: `ByRole`, `ByText`, `ByLabelText`, `ByTestId`
 
 ## Examples
 
-### Counter
-
-A minimal counter app demonstrating state management:
-
-```bash
-turbo start --filter=counter-example
-```
-
 ### GTK4 Demo
 
 A comprehensive showcase of GTK4 widgets and features:
@@ -186,12 +180,13 @@ A comprehensive showcase of GTK4 widgets and features:
 turbo start --filter=gtk4-demo
 ```
 
-### List Example
+### Todo App
 
-Comprehensive showcase of ListView, GridView, and ColumnView with sorting:
+A todo app demonstrating `@gtkx/testing` with realistic component tests:
 
 ```bash
-turbo start --filter=list-example
+turbo start --filter=todo
+turbo test --filter=todo
 ```
 
 ## Packages

package/dist/codegen/jsx-generator.d.ts

@@ -6,6 +6,15 @@ interface JsxGeneratorOptions {
     /** Optional Prettier configuration for formatting output. */
     prettierConfig?: unknown;
 }
+/**
+ * Result of the JSX generation containing both public and internal files.
+ */
+interface JsxGeneratorResult {
+    /** Public JSX types and components for user consumption. */
+    jsx: string;
+    /** Internal metadata for reconciler use (not exported to users). */
+    internal: string;
+}
 /**
  * Generates JSX type definitions for React components from GTK widget classes.
  * Creates TypeScript interfaces for props and augments React's JSX namespace.
@@ -29,10 +38,11 @@ export declare class JsxGenerator {
      * Generates JSX type definitions for all widgets in a namespace.
      * @param namespace - The parsed GIR namespace
      * @param classMap - Map of class names to class definitions
-     * @returns Generated TypeScript code as a string
+     * @returns Generated TypeScript code as public jsx.ts and internal.ts files
      */
-    generate(namespace: GirNamespace, classMap: Map<string, GirClass>): Promise<string>;
+    generate(namespace: GirNamespace, classMap: Map<string, GirClass>): Promise<JsxGeneratorResult>;
     private generateImports;
+    private generateInternalImports;
     private generateCommonTypes;
     private generateWidgetPropsContent;
     private buildContainerMetadata;

package/dist/codegen/jsx-generator.js

@@ -5,7 +5,6 @@ const COLUMN_VIEW_WIDGET = "ColumnView";
 const DROPDOWN_WIDGETS = new Set(["DropDown"]);
 const GRID_WIDGETS = new Set(["Grid"]);
 const NOTEBOOK_WIDGET = "Notebook";
-const TEXT_VIEW_WIDGET = "TextView";
 const INTERNALLY_PROVIDED_PARAMS = {
     ApplicationWindow: new Set(["application"]),
 };
@@ -34,7 +33,6 @@ const isColumnViewWidget = (widgetName) => widgetName === COLUMN_VIEW_WIDGET;
 const isDropDownWidget = (widgetName) => DROPDOWN_WIDGETS.has(widgetName);
 const isGridWidget = (widgetName) => GRID_WIDGETS.has(widgetName);
 const isNotebookWidget = (widgetName) => widgetName === NOTEBOOK_WIDGET;
-const isTextViewWidget = (widgetName) => widgetName === TEXT_VIEW_WIDGET;
 const sanitizeDoc = (doc) => {
     let result = doc;
     result = result.replace(/<picture>[\s\S]*?<\/picture>/gi, "");
@@ -100,7 +98,7 @@ export class JsxGenerator {
      * Generates JSX type definitions for all widgets in a namespace.
      * @param namespace - The parsed GIR namespace
      * @param classMap - Map of class names to class definitions
-     * @returns Generated TypeScript code as a string
+     * @returns Generated TypeScript code as public jsx.ts and internal.ts files
      */
     async generate(namespace, classMap) {
         this.classMap = classMap;
@@ -113,18 +111,24 @@ export class JsxGenerator {
         this.widgetPropertyNames = new Set(widgetClass?.properties.map((p) => toCamelCase(p.name)) ?? []);
         this.widgetSignalNames = new Set(widgetClass?.signals.map((s) => toCamelCase(s.name)) ?? []);
         const widgetPropsInterfaces = this.generateWidgetPropsInterfaces(widgets, containerMetadata);
-        const sections = [
+        const jsxSections = [
             this.generateImports(),
             this.generateCommonTypes(widgetClass),
             widgetPropsInterfaces,
-            this.generateConstructorArgsMetadata(widgets),
-            this.generatePropSettersMap(widgets),
-            this.generateSetterGetterMap(widgets),
             this.generateExports(widgets, containerMetadata),
             this.generateJsxNamespace(widgets, containerMetadata),
             "export {};",
         ];
-        return this.formatCode(sections.join("\n"));
+        const internalSections = [
+            this.generateInternalImports(),
+            this.generateConstructorArgsMetadata(widgets),
+            this.generatePropSettersMap(widgets),
+            this.generateSetterGetterMap(widgets),
+        ];
+        return {
+            jsx: await this.formatCode(jsxSections.join("\n")),
+            internal: await this.formatCode(internalSections.join("\n")),
+        };
     }
     generateImports() {
         const externalImports = [...this.usedExternalNamespaces]
@@ -140,6 +144,9 @@ export class JsxGenerator {
             "",
         ].join("\n");
     }
+    generateInternalImports() {
+        return "/** Internal metadata for the reconciler. Not part of the public API. */\n";
+    }
     generateCommonTypes(widgetClass) {
         const widgetPropsContent = this.generateWidgetPropsContent(widgetClass);
         return `
@@ -336,24 +343,14 @@ ${widgetPropsContent}
             lines.push(`\t * Render function for list items.`);
             lines.push(`\t * Called with null during setup (for loading state) and with the actual item during bind.`);
             lines.push(`\t */`);
-            lines.push(`\t// biome-ignore lint/suspicious/noExplicitAny: Internal type, use generic ListView<T> export`);
-            lines.push(`\trenderItem: (item: any) => import("react").ReactElement;`);
+            lines.push(`\trenderItem: (item: unknown) => import("react").ReactElement;`);
         }
         if (isDropDownWidget(widget.name)) {
             lines.push("");
             lines.push(`\t/** Function to convert item to display label */`);
-            lines.push(`\t// biome-ignore lint/suspicious/noExplicitAny: Internal type, use generic DropDown<T> export`);
-            lines.push(`\titemLabel?: (item: any) => string;`);
+            lines.push(`\titemLabel?: (item: unknown) => string;`);
             lines.push(`\t/** Called when selection changes */`);
-            lines.push(`\t// biome-ignore lint/suspicious/noExplicitAny: Internal type, use generic DropDown<T> export`);
-            lines.push(`\tonSelectionChanged?: (item: any, index: number) => void;`);
-        }
-        if (isTextViewWidget(widget.name)) {
-            lines.push("");
-            lines.push(`\t/** The contents of the text buffer. */`);
-            lines.push(`\ttext?: string;`);
-            lines.push(`\t/** Called when the text buffer content changes */`);
-            lines.push(`\tonChanged?: (text: string) => void;`);
+            lines.push(`\tonSelectionChanged?: (item: unknown, index: number) => void;`);
         }
         lines.push("");
         lines.push(`\tref?: Ref<Gtk.${widgetName}>;`);
@@ -647,71 +644,72 @@ ${widgetPropsContent}
         const name = toPascalCase(widgetName);
         const lines = [];
         if (isListWidget(widgetName)) {
-            // Props type for the generic Root component
+            lines.push(`/**`);
+            lines.push(` * Props for the ${name}.Root component with type-safe item rendering.`);
+            lines.push(` * @typeParam T - The type of items in the list.`);
+            lines.push(` */`);
             lines.push(`interface ${name}RootProps<T> extends Omit<${name}Props, "renderItem"> {`);
-            lines.push(`\t/** Render function for list items. Called with null during setup. */`);
+            lines.push(`\t/** Render function for list items. Called with null during setup (for loading state). */`);
             lines.push(`\trenderItem: (item: T | null) => import("react").ReactElement;`);
             lines.push(`}`);
             lines.push(``);
-            // Root wrapper component
             lines.push(`function ${name}Root<T>(props: ${name}RootProps<T>): import("react").ReactElement {`);
             lines.push(`\treturn createElement("${name}.Root", props);`);
             lines.push(`}`);
             lines.push(``);
-            // Item wrapper component
             lines.push(`function ${name}Item<T>(props: ListItemProps<T>): import("react").ReactElement {`);
             lines.push(`\treturn createElement("${name}.Item", props);`);
             lines.push(`}`);
         }
         else if (isColumnViewWidget(widgetName)) {
-            // Root props type - extends with ColumnViewRootProps for sorting support
-            // Uses generics: T for item type, C for column ID union type
-            lines.push(`interface ${name}RootPropsExtended<T = unknown, C extends string = string> extends ${name}Props, ColumnViewRootProps<C> {`);
-            lines.push(`\t/** Comparison function for sorting items by column. Takes item a, item b, and column id. */`);
-            lines.push(`\tsortFn?: (a: T, b: T, columnId: C) => number;`);
-            lines.push(`}`);
+            lines.push(`/**`);
+            lines.push(` * Props for the ${name}.Root component with type-safe item and column rendering.`);
+            lines.push(` * @typeParam T - The type of items in the column view.`);
+            lines.push(` * @typeParam C - The union type of column IDs for type-safe sorting.`);
+            lines.push(` */`);
+            lines.push(`interface ${name}RootPropsExtended<T = unknown, C extends string = string> extends ${name}Props, ColumnViewRootProps<T, C> {}`);
             lines.push(``);
-            // Root wrapper (generic)
             lines.push(`function ${name}Root<T = unknown, C extends string = string>(props: ${name}RootPropsExtended<T, C>): import("react").ReactElement {`);
             lines.push(`\treturn createElement("${name}.Root", props);`);
             lines.push(`}`);
             lines.push(``);
-            // Column props type - use GenericColumnProps to avoid conflict with imported ColumnViewColumnProps
+            lines.push(`/**`);
+            lines.push(` * Props for ${name}.Column with type-safe cell rendering.`);
+            lines.push(` * @typeParam T - The type of items passed to the renderCell function.`);
+            lines.push(` */`);
             lines.push(`interface ${name}GenericColumnProps<T> extends Omit<ColumnViewColumnProps, "renderCell"> {`);
-            lines.push(`\t/** Render function for column cells. Called with null during setup. */`);
+            lines.push(`\t/** Render function for column cells. Called with null during setup (for loading state). */`);
             lines.push(`\trenderCell: (item: T | null) => import("react").ReactElement;`);
             lines.push(`}`);
             lines.push(``);
-            // Column wrapper component
             lines.push(`function ${name}Column<T>(props: ${name}GenericColumnProps<T>): import("react").ReactElement {`);
             lines.push(`\treturn createElement("${name}.Column", props);`);
             lines.push(`}`);
             lines.push(``);
-            // Item wrapper component
             lines.push(`function ${name}Item<T>(props: ListItemProps<T>): import("react").ReactElement {`);
             lines.push(`\treturn createElement("${name}.Item", props);`);
             lines.push(`}`);
         }
         else if (isDropDownWidget(widgetName)) {
-            // Props type for the generic Root component
+            lines.push(`/**`);
+            lines.push(` * Props for the ${name}.Root component with type-safe item handling.`);
+            lines.push(` * @typeParam T - The type of items in the dropdown.`);
+            lines.push(` */`);
             lines.push(`interface ${name}RootProps<T> extends Omit<${name}Props, "itemLabel" | "onSelectionChanged"> {`);
-            lines.push(`\t/** Function to convert item to display label */`);
+            lines.push(`\t/** Function to convert an item to its display label. */`);
             lines.push(`\titemLabel?: (item: T) => string;`);
-            lines.push(`\t/** Called when selection changes */`);
+            lines.push(`\t/** Called when the selected item changes. */`);
             lines.push(`\tonSelectionChanged?: (item: T, index: number) => void;`);
             lines.push(`}`);
             lines.push(``);
-            // Root wrapper component
             lines.push(`function ${name}Root<T>(props: ${name}RootProps<T>): import("react").ReactElement {`);
             lines.push(`\treturn createElement("${name}.Root", props);`);
             lines.push(`}`);
             lines.push(``);
-            // Item wrapper component
             lines.push(`function ${name}Item<T>(props: ListItemProps<T>): import("react").ReactElement {`);
             lines.push(`\treturn createElement("${name}.Item", props);`);
             lines.push(`}`);
         }
-        // Generate slot wrapper components
         for (const slot of metadata.namedChildSlots) {
             lines.push(``);
             lines.push(`function ${name}${slot.slotName}(props: SlotProps): import("react").ReactElement {`);

package/dist/container-interfaces.d.ts

@@ -0,0 +1,51 @@
+import type * as Gtk from "@gtkx/ffi/gtk";
+import type { Node } from "./node.js";
+/**
+ * Interface for containers that manage child widgets with attach/detach semantics.
+ * Used by ActionBar, FlowBox, ListBox, Overlay.
+ */
+export interface ChildContainer {
+    attachChild(child: Gtk.Widget): void;
+    insertChildBefore(child: Gtk.Widget, before: Gtk.Widget): void;
+    detachChild(child: Gtk.Widget): void;
+}
+/**
+ * Interface for page-based containers like Notebook.
+ */
+export interface PageContainer {
+    addPage(child: Gtk.Widget, label: string): void;
+    insertPageBefore(child: Gtk.Widget, label: string, beforeChild: Gtk.Widget): void;
+    removePage(child: Gtk.Widget): void;
+    updatePageLabel(child: Gtk.Widget, label: string): void;
+}
+/**
+ * Interface for grid-based containers.
+ */
+export interface GridContainer {
+    attachToGrid(child: Gtk.Widget, column: number, row: number, colSpan: number, rowSpan: number): void;
+    removeFromGrid(child: Gtk.Widget): void;
+}
+/**
+ * Interface for item-based containers like ListView, ColumnView, DropDown.
+ */
+export interface ItemContainer<T> {
+    addItem(item: T): void;
+    insertItemBefore(item: T, beforeItem: T): void;
+    removeItem(item: T): void;
+}
+/**
+ * Interface for column-based containers like ColumnView.
+ * Note: Column type is generic to support both raw Gtk.ColumnViewColumn and wrapper nodes.
+ */
+export interface ColumnContainer {
+    addColumn(column: unknown): void;
+    insertColumnBefore(column: unknown, beforeColumn: unknown): void;
+    removeColumn(column: unknown): void;
+    getItems(): unknown[];
+    getSortFn(): ((a: unknown, b: unknown, columnId: string) => number) | null;
+}
+export declare const isChildContainer: (node: Node) => node is Node & ChildContainer;
+export declare const isPageContainer: (node: Node) => node is Node & PageContainer;
+export declare const isGridContainer: (node: Node) => node is Node & GridContainer;
+export declare const isItemContainer: <T>(node: Node) => node is Node & ItemContainer<T>;
+export declare const isColumnContainer: (node: Node) => node is Node & ColumnContainer;

package/dist/container-interfaces.js

@@ -0,0 +1,5 @@
+export const isChildContainer = (node) => "attachChild" in node && "detachChild" in node && "insertChildBefore" in node;
+export const isPageContainer = (node) => "addPage" in node && "removePage" in node && "insertPageBefore" in node && "updatePageLabel" in node;
+export const isGridContainer = (node) => "attachToGrid" in node && "removeFromGrid" in node;
+export const isItemContainer = (node) => "addItem" in node && "insertItemBefore" in node && "removeItem" in node;
+export const isColumnContainer = (node) => "addColumn" in node && "removeColumn" in node && "getSortFn" in node;

package/dist/factory.d.ts

@@ -3,4 +3,4 @@ import type { Node } from "./node.js";
 import { type ROOT_NODE_CONTAINER } from "./nodes/root.js";
 export type Props = Record<string, unknown>;
 export { ROOT_NODE_CONTAINER } from "./nodes/root.js";
-export declare const createNode: (type: string, props: Props, app: Gtk.Application, existingWidget?: Gtk.Widget | typeof ROOT_NODE_CONTAINER) => Node;
+export declare const createNode: (type: string, props: Props, existingWidget?: Gtk.Widget | typeof ROOT_NODE_CONTAINER) => Node;

package/dist/factory.js

@@ -1,16 +1,22 @@
+import { AboutDialogNode } from "./nodes/about-dialog.js";
+import { ActionBarNode } from "./nodes/action-bar.js";
 import { ColumnViewColumnNode, ColumnViewItemNode, ColumnViewNode } from "./nodes/column-view.js";
 import { DropDownItemNode, DropDownNode } from "./nodes/dropdown.js";
+import { FlowBoxNode } from "./nodes/flow-box.js";
 import { GridChildNode, GridNode } from "./nodes/grid.js";
 import { ListItemNode, ListViewNode } from "./nodes/list.js";
+import { ListBoxNode } from "./nodes/list-box.js";
 import { NotebookNode, NotebookPageNode } from "./nodes/notebook.js";
 import { OverlayNode } from "./nodes/overlay.js";
 import { RootNode } from "./nodes/root.js";
 import { SlotNode } from "./nodes/slot.js";
 import { TextViewNode } from "./nodes/text-view.js";
 import { WidgetNode } from "./nodes/widget.js";
+import { WindowNode } from "./nodes/window.js";
 export { ROOT_NODE_CONTAINER } from "./nodes/root.js";
 const NODE_CLASSES = [
     RootNode,
+    // Virtual nodes (no widget)
     ColumnViewColumnNode,
     ColumnViewItemNode,
     ListItemNode,
@@ -18,19 +24,27 @@ const NODE_CLASSES = [
     GridChildNode,
     NotebookPageNode,
     SlotNode,
+    // Specialized widget nodes
+    WindowNode,
+    AboutDialogNode,
     TextViewNode,
+    // Container nodes
+    ActionBarNode,
+    FlowBoxNode,
+    ListBoxNode,
     DropDownNode,
     GridNode,
     OverlayNode,
     ColumnViewNode,
     ListViewNode,
     NotebookNode,
+    // Catch-all (must be last)
     WidgetNode,
 ];
-export const createNode = (type, props, app, existingWidget) => {
+export const createNode = (type, props, existingWidget) => {
     for (const NodeClass of NODE_CLASSES) {
-        if (NodeClass.matches(type, props, existingWidget)) {
-            return new NodeClass(type, props, app, existingWidget);
+        if (NodeClass.matches(type, existingWidget)) {
+            return new NodeClass(type, props, existingWidget);
         }
     }
     throw new Error(`No matching node class for type: ${type}`);

package/dist/generated/internal.d.ts

@@ -0,0 +1,7 @@
+/** Internal metadata for the reconciler. Not part of the public API. */
+export declare const CONSTRUCTOR_PARAMS: Record<string, {
+    name: string;
+    hasDefault: boolean;
+}[]>;
+export declare const PROP_SETTERS: Record<string, Record<string, string>>;
+export declare const SETTER_GETTERS: Record<string, Record<string, string>>;