@gtkx/react 0.1.49 → 0.1.51

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,6 +5,8 @@ const COLUMN_VIEW_WIDGET = "ColumnView";
 const DROPDOWN_WIDGETS = new Set(["DropDown"]);
 const GRID_WIDGETS = new Set(["Grid"]);
 const NOTEBOOK_WIDGET = "Notebook";
+const STACK_WIDGET = "Stack";
+const POPOVER_MENU_WIDGET = "PopoverMenu";
 const INTERNALLY_PROVIDED_PARAMS = {
     ApplicationWindow: new Set(["application"]),
 };
@@ -33,6 +35,8 @@ 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 isStackWidget = (widgetName) => widgetName === STACK_WIDGET;
+const isPopoverMenuWidget = (widgetName) => widgetName === POPOVER_MENU_WIDGET;
 const sanitizeDoc = (doc) => {
     let result = doc;
     result = result.replace(/<picture>[\s\S]*?<\/picture>/gi, "");
@@ -98,7 +102,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;
@@ -111,18 +115,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]
@@ -134,14 +144,17 @@ export class JsxGenerator {
             `import type { ReactNode, Ref } from "react";`,
             ...externalImports,
             `import type * as Gtk from "@gtkx/ffi/gtk";`,
-            `import type { ColumnViewColumnProps, ColumnViewRootProps, GridChildProps, ListItemProps, ListViewRenderProps, NotebookPageProps, SlotProps } from "../types.js";`,
+            `import type { ColumnViewColumnProps, ColumnViewRootProps, GridChildProps, ListItemProps, ListViewRenderProps, MenuItemProps, MenuRootProps, MenuSectionProps, MenuSubmenuProps, NotebookPageProps, SlotProps, StackPageProps, StackRootProps } from "../types.js";`,
             "",
         ].join("\n");
     }
+    generateInternalImports() {
+        return "/** Internal metadata for the reconciler. Not part of the public API. */\n";
+    }
     generateCommonTypes(widgetClass) {
         const widgetPropsContent = this.generateWidgetPropsContent(widgetClass);
         return `
-export { ColumnViewColumnProps, ColumnViewRootProps, GridChildProps, ListItemProps, ListViewRenderProps, NotebookPageProps, SlotProps };
+export { ColumnViewColumnProps, ColumnViewRootProps, GridChildProps, ListItemProps, ListViewRenderProps, MenuItemProps, MenuRootProps, MenuSectionProps, MenuSubmenuProps, NotebookPageProps, SlotProps, StackPageProps, StackRootProps };
 
 ${widgetPropsContent}
 `;
@@ -572,11 +585,17 @@ ${widgetPropsContent}
                 isColumnViewWidget(widget.name) ||
                 isDropDownWidget(widget.name) ||
                 isGridWidget(widget.name) ||
-                isNotebookWidget(widget.name);
+                isNotebookWidget(widget.name) ||
+                isStackWidget(widget.name) ||
+                isPopoverMenuWidget(widget.name);
             const docComment = widget.doc ? formatDoc(widget.doc).trimEnd() : "";
             if (hasMeaningfulSlots) {
                 // For list widgets, generate wrapper components with proper generics
-                if (isListWidget(widget.name) || isColumnViewWidget(widget.name) || isDropDownWidget(widget.name)) {
+                if (isListWidget(widget.name) ||
+                    isColumnViewWidget(widget.name) ||
+                    isDropDownWidget(widget.name) ||
+                    isStackWidget(widget.name) ||
+                    isPopoverMenuWidget(widget.name)) {
                     const wrapperComponents = this.generateGenericWrapperComponents(widget.name, metadata);
                     const exportMembers = this.getWrapperExportMembers(widget.name, metadata);
                     if (docComment) {
@@ -610,6 +629,38 @@ ${widgetPropsContent}
                 }
             }
         }
+        // Add ApplicationMenu and Menu namespace components
+        lines.push(`/**
+ * Sets the application-wide menu bar.
+ * The menu will appear in the window's title bar on supported platforms.
+ * Use Menu.Item, Menu.Section, and Menu.Submenu as children.
+ */
+export function ApplicationMenu(props: MenuRootProps): import("react").ReactElement {
+\treturn createElement("ApplicationMenu", props);
+}
+
+function MenuItem(props: MenuItemProps): import("react").ReactElement {
+\treturn createElement("Menu.Item", props);
+}
+
+function MenuSection(props: MenuSectionProps): import("react").ReactElement {
+\treturn createElement("Menu.Section", props);
+}
+
+function MenuSubmenu(props: MenuSubmenuProps): import("react").ReactElement {
+\treturn createElement("Menu.Submenu", props);
+}
+
+/**
+ * Declarative menu builder for use with PopoverMenu and ApplicationMenu.
+ * Use Menu.Item for action items, Menu.Section for groups, Menu.Submenu for nested menus.
+ */
+export const Menu = {
+\tItem: MenuItem,
+\tSection: MenuSection,
+\tSubmenu: MenuSubmenu,
+};
+`);
         return `${lines.join("\n")}\n`;
     }
     getWrapperExportMembers(widgetName, metadata) {
@@ -625,6 +676,14 @@ ${widgetPropsContent}
         else if (isDropDownWidget(widgetName)) {
             members.push(`Item: ${name}Item`);
         }
+        else if (isStackWidget(widgetName)) {
+            members.push(`Page: ${name}Page`);
+        }
+        else if (isPopoverMenuWidget(widgetName)) {
+            members.push(`Item: ${name}Item`);
+            members.push(`Section: ${name}Section`);
+            members.push(`Submenu: ${name}Submenu`);
+        }
         // Add named child slots
         for (const slot of metadata.namedChildSlots) {
             members.push(`${slot.slotName}: ${name}${slot.slotName}`);
@@ -635,66 +694,98 @@ ${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)) {
+            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
+        else if (isStackWidget(widgetName)) {
+            lines.push(`function ${name}Root(props: StackRootProps & ${name}Props): import("react").ReactElement {`);
+            lines.push(`\treturn createElement("${name}.Root", props);`);
+            lines.push(`}`);
+            lines.push(``);
+            lines.push(`function ${name}Page(props: StackPageProps): import("react").ReactElement {`);
+            lines.push(`\treturn createElement("${name}.Page", props);`);
+            lines.push(`}`);
+        }
+        else if (isPopoverMenuWidget(widgetName)) {
+            lines.push(`function ${name}Root(props: MenuRootProps & ${name}Props): import("react").ReactElement {`);
+            lines.push(`\treturn createElement("${name}.Root", props);`);
+            lines.push(`}`);
+            lines.push(``);
+            lines.push(`function ${name}Item(props: MenuItemProps): import("react").ReactElement {`);
+            lines.push(`\treturn createElement("Menu.Item", props);`);
+            lines.push(`}`);
+            lines.push(``);
+            lines.push(`function ${name}Section(props: MenuSectionProps): import("react").ReactElement {`);
+            lines.push(`\treturn createElement("Menu.Section", props);`);
+            lines.push(`}`);
+            lines.push(``);
+            lines.push(`function ${name}Submenu(props: MenuSubmenuProps): import("react").ReactElement {`);
+            lines.push(`\treturn createElement("Menu.Submenu", props);`);
+            lines.push(`}`);
+        }
         for (const slot of metadata.namedChildSlots) {
             lines.push(``);
             lines.push(`function ${name}${slot.slotName}(props: SlotProps): import("react").ReactElement {`);
@@ -719,7 +810,9 @@ ${widgetPropsContent}
                 isColumnViewWidget(widget.name) ||
                 isDropDownWidget(widget.name) ||
                 isGridWidget(widget.name) ||
-                isNotebookWidget(widget.name);
+                isNotebookWidget(widget.name) ||
+                isStackWidget(widget.name) ||
+                isPopoverMenuWidget(widget.name);
             if (hasMeaningfulSlots) {
                 elements.push(`"${widgetName}.Root": ${propsName};`);
             }
@@ -745,7 +838,16 @@ ${widgetPropsContent}
             if (isNotebookWidget(widget.name)) {
                 elements.push(`"${widgetName}.Page": NotebookPageProps;`);
             }
+            if (isStackWidget(widget.name)) {
+                elements.push(`"${widgetName}.Page": StackPageProps;`);
+            }
         }
+        // Add shared Menu elements (used by PopoverMenu, PopoverMenuBar, and ApplicationMenu)
+        elements.push(`"Menu.Item": MenuItemProps;`);
+        elements.push(`"Menu.Section": MenuSectionProps;`);
+        elements.push(`"Menu.Submenu": MenuSubmenuProps;`);
+        // Add ApplicationMenu element
+        elements.push(`ApplicationMenu: MenuRootProps;`);
         return `
 declare global {
 \tnamespace React {

package/dist/container-interfaces.d.ts

@@ -18,6 +18,26 @@ export interface PageContainer {
     removePage(child: Gtk.Widget): void;
     updatePageLabel(child: Gtk.Widget, label: string): void;
 }
+/**
+ * Props for Stack pages.
+ */
+export interface StackPageProps {
+    name?: string;
+    title?: string;
+    iconName?: string;
+    needsAttention?: boolean;
+    visible?: boolean;
+    useUnderline?: boolean;
+}
+/**
+ * Interface for Stack containers.
+ */
+export interface StackPageContainer {
+    addStackPage(child: Gtk.Widget, props: StackPageProps): void;
+    insertStackPageBefore(child: Gtk.Widget, props: StackPageProps, beforeChild: Gtk.Widget): void;
+    removeStackPage(child: Gtk.Widget): void;
+    updateStackPageProps(child: Gtk.Widget, props: StackPageProps): void;
+}
 /**
  * Interface for grid-based containers.
  */
@@ -46,6 +66,7 @@ export interface ColumnContainer {
 }
 export declare const isChildContainer: (node: Node) => node is Node & ChildContainer;
 export declare const isPageContainer: (node: Node) => node is Node & PageContainer;
+export declare const isStackPageContainer: (node: Node) => node is Node & StackPageContainer;
 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

@@ -1,5 +1,6 @@
 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 isStackPageContainer = (node) => "addStackPage" in node && "removeStackPage" in node && "updateStackPageProps" 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.js

@@ -6,10 +6,12 @@ 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 { ApplicationMenuNode, MenuItemNode, MenuSectionNode, MenuSubmenuNode, PopoverMenuBarNode, PopoverMenuRootNode, } from "./nodes/menu.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 { StackNode, StackPageNode } from "./nodes/stack.js";
 import { TextViewNode } from "./nodes/text-view.js";
 import { WidgetNode } from "./nodes/widget.js";
 import { WindowNode } from "./nodes/window.js";
@@ -23,11 +25,18 @@ const NODE_CLASSES = [
     DropDownItemNode,
     GridChildNode,
     NotebookPageNode,
+    StackPageNode,
+    MenuItemNode,
+    MenuSectionNode,
+    MenuSubmenuNode,
     SlotNode,
     // Specialized widget nodes
     WindowNode,
     AboutDialogNode,
     TextViewNode,
+    ApplicationMenuNode,
+    PopoverMenuRootNode,
+    PopoverMenuBarNode,
     // Container nodes
     ActionBarNode,
     FlowBoxNode,
@@ -38,13 +47,16 @@ const NODE_CLASSES = [
     ColumnViewNode,
     ListViewNode,
     NotebookNode,
+    StackNode,
     // Catch-all (must be last)
     WidgetNode,
 ];
 export const createNode = (type, props, existingWidget) => {
     for (const NodeClass of NODE_CLASSES) {
         if (NodeClass.matches(type, existingWidget)) {
-            return new NodeClass(type, props, existingWidget);
+            const node = new NodeClass(type, existingWidget);
+            node.initialize(props);
+            return node;
         }
     }
     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>>;