@gtkx/react 0.1.49 → 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

@@ -98,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;
@@ -111,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]
@@ -138,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 `
@@ -635,66 +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)) {
+            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/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>>;