@gtkx/react 0.1.44 → 0.1.46

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

@@ -1,7 +1,15 @@
 import type { GirClass, GirNamespace, TypeMapper } from "@gtkx/gir";
+/**
+ * Configuration options for the JSX type generator.
+ */
 interface JsxGeneratorOptions {
+    /** Optional Prettier configuration for formatting output. */
     prettierConfig?: unknown;
 }
+/**
+ * Generates JSX type definitions for React components from GTK widget classes.
+ * Creates TypeScript interfaces for props and augments React's JSX namespace.
+ */
 export declare class JsxGenerator {
     private typeMapper;
     private options;
@@ -11,7 +19,18 @@ export declare class JsxGenerator {
     private usedExternalNamespaces;
     private widgetPropertyNames;
     private widgetSignalNames;
+    /**
+     * Creates a new JSX generator.
+     * @param typeMapper - TypeMapper for converting GIR types to TypeScript
+     * @param options - Generator configuration options
+     */
     constructor(typeMapper: TypeMapper, options?: JsxGeneratorOptions);
+    /**
+     * 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
+     */
     generate(namespace: GirNamespace, classMap: Map<string, GirClass>): Promise<string>;
     private generateImports;
     private generateCommonTypes;
@@ -34,6 +53,8 @@ export declare class JsxGenerator {
     private addNamespacePrefix;
     private buildSignalHandlerType;
     private generateExports;
+    private getWrapperExportMembers;
+    private generateGenericWrapperComponents;
     private generateJsxNamespace;
     private formatCode;
 }

package/dist/codegen/jsx-generator.js

@@ -74,6 +74,10 @@ const isWidgetSubclass = (typeName, classMap, visited = new Set()) => {
         return true;
     return cls.parent ? isWidgetSubclass(cls.parent, classMap, visited) : false;
 };
+/**
+ * Generates JSX type definitions for React components from GTK widget classes.
+ * Creates TypeScript interfaces for props and augments React's JSX namespace.
+ */
 export class JsxGenerator {
     typeMapper;
     options;
@@ -83,10 +87,21 @@ export class JsxGenerator {
     usedExternalNamespaces = new Set();
     widgetPropertyNames = new Set();
     widgetSignalNames = new Set();
+    /**
+     * Creates a new JSX generator.
+     * @param typeMapper - TypeMapper for converting GIR types to TypeScript
+     * @param options - Generator configuration options
+     */
     constructor(typeMapper, options = {}) {
         this.typeMapper = typeMapper;
         this.options = options;
     }
+    /**
+     * 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
+     */
     async generate(namespace, classMap) {
         this.classMap = classMap;
         this.interfaceMap = new Map(namespace.interfaces.map((iface) => [iface.name, iface]));
@@ -116,6 +131,7 @@ export class JsxGenerator {
             .map((ns) => `import type * as ${ns} from "@gtkx/ffi/${ns.toLowerCase()}";`);
         return [
             `import "react";`,
+            `import { createElement } from "react";`,
             `import type { ReactNode, Ref } from "react";`,
             ...externalImports,
             `import type * as Gtk from "@gtkx/ffi/gtk";`,
@@ -319,18 +335,22 @@ ${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: allows typed renderItem callbacks`);
+            lines.push(`\t// biome-ignore lint/suspicious/noExplicitAny: Internal type, use generic ListView<T> export`);
             lines.push(`\trenderItem: (item: any) => 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(`\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;`);
         }
@@ -544,22 +564,30 @@ ${widgetPropsContent}
                 isNotebookWidget(widget.name);
             const docComment = widget.doc ? formatDoc(widget.doc).trimEnd() : "";
             if (hasMeaningfulSlots) {
-                const valueMembers = [
-                    `Root: "${widgetName}.Root" as const`,
-                    ...metadata.namedChildSlots.map((slot) => `${slot.slotName}: "${widgetName}.${slot.slotName}" as const`),
-                    ...(isListWidget(widget.name) ? [`Item: "${widgetName}.Item" as const`] : []),
-                    ...(isColumnViewWidget(widget.name)
-                        ? [`Column: "${widgetName}.Column" as const`, `Item: "${widgetName}.Item" as const`]
-                        : []),
-                    ...(isDropDownWidget(widget.name) ? [`Item: "${widgetName}.Item" as const`] : []),
-                    ...(isGridWidget(widget.name) ? [`Child: "${widgetName}.Child" as const`] : []),
-                    ...(isNotebookWidget(widget.name) ? [`Page: "${widgetName}.Page" as const`] : []),
-                ];
-                if (docComment) {
-                    lines.push(`${docComment}\nexport const ${widgetName} = {\n\t${valueMembers.join(",\n\t")},\n};`);
+                // For list widgets, generate wrapper components with proper generics
+                if (isListWidget(widget.name) || isColumnViewWidget(widget.name) || isDropDownWidget(widget.name)) {
+                    const wrapperComponents = this.generateGenericWrapperComponents(widget.name, metadata);
+                    const exportMembers = this.getWrapperExportMembers(widget.name, metadata);
+                    if (docComment) {
+                        lines.push(`${wrapperComponents}\n${docComment}\nexport const ${widgetName} = {\n\t${exportMembers.join(",\n\t")},\n};`);
+                    }
+                    else {
+                        lines.push(`${wrapperComponents}\nexport const ${widgetName} = {\n\t${exportMembers.join(",\n\t")},\n};`);
+                    }
                 }
                 else {
-                    lines.push(`export const ${widgetName} = {\n\t${valueMembers.join(",\n\t")},\n};`);
+                    const valueMembers = [
+                        `Root: "${widgetName}.Root" as const`,
+                        ...metadata.namedChildSlots.map((slot) => `${slot.slotName}: "${widgetName}.${slot.slotName}" as const`),
+                        ...(isGridWidget(widget.name) ? [`Child: "${widgetName}.Child" as const`] : []),
+                        ...(isNotebookWidget(widget.name) ? [`Page: "${widgetName}.Page" as const`] : []),
+                    ];
+                    if (docComment) {
+                        lines.push(`${docComment}\nexport const ${widgetName} = {\n\t${valueMembers.join(",\n\t")},\n};`);
+                    }
+                    else {
+                        lines.push(`export const ${widgetName} = {\n\t${valueMembers.join(",\n\t")},\n};`);
+                    }
                 }
             }
             else {
@@ -573,6 +601,95 @@ ${widgetPropsContent}
         }
         return `${lines.join("\n")}\n`;
     }
+    getWrapperExportMembers(widgetName, metadata) {
+        const name = toPascalCase(widgetName);
+        const members = [`Root: ${name}Root`];
+        if (isListWidget(widgetName)) {
+            members.push(`Item: ${name}Item`);
+        }
+        else if (isColumnViewWidget(widgetName)) {
+            members.push(`Column: ${name}Column`);
+            members.push(`Item: ${name}Item`);
+        }
+        else if (isDropDownWidget(widgetName)) {
+            members.push(`Item: ${name}Item`);
+        }
+        // Add named child slots
+        for (const slot of metadata.namedChildSlots) {
+            members.push(`${slot.slotName}: ${name}${slot.slotName}`);
+        }
+        return members;
+    }
+    generateGenericWrapperComponents(widgetName, metadata) {
+        const name = toPascalCase(widgetName);
+        const lines = [];
+        if (isListWidget(widgetName)) {
+            // Props type for the generic Root component
+            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(`\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 wrapper (non-generic)
+            lines.push(`function ${name}Root(props: ${name}Props): 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(`interface ${name}GenericColumnProps<T> extends Omit<ColumnViewColumnProps, "renderCell"> {`);
+            lines.push(`\t/** Render function for column cells. Called with null during setup. */`);
+            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(`interface ${name}RootProps<T> extends Omit<${name}Props, "itemLabel" | "onSelectionChanged"> {`);
+            lines.push(`\t/** Function to convert item to display label */`);
+            lines.push(`\titemLabel?: (item: T) => string;`);
+            lines.push(`\t/** Called when selection 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 {`);
+            lines.push(`\treturn createElement("${name}.${slot.slotName}", props);`);
+            lines.push(`}`);
+        }
+        return lines.join("\n");
+    }
     generateJsxNamespace(widgets, containerMetadata) {
         const elements = [];
         for (const widget of widgets) {

package/dist/fiber-root.d.ts

@@ -1,3 +1,8 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type Reconciler from "react-reconciler";
+/**
+ * Creates a new fiber root container for rendering React elements.
+ * @param container - Optional GTK widget to use as the container. If not provided,
+ *                    uses the ROOT_NODE_CONTAINER sentinel for virtual roots.
+ */
 export declare const createFiberRoot: (container?: Gtk.Widget) => Reconciler.FiberRoot;

package/dist/fiber-root.js

@@ -1,5 +1,10 @@
 import { ROOT_NODE_CONTAINER } from "./factory.js";
 import { reconciler } from "./reconciler.js";
+/**
+ * Creates a new fiber root container for rendering React elements.
+ * @param container - Optional GTK widget to use as the container. If not provided,
+ *                    uses the ROOT_NODE_CONTAINER sentinel for virtual roots.
+ */
 export const createFiberRoot = (container) => {
     const instance = reconciler.getInstance();
     return instance.createContainer(container ?? ROOT_NODE_CONTAINER, 0, null, false, null, "", (error) => console.error("Fiber root render error:", error), () => { }, () => { }, () => { }, null);