@gtkx/react 0.1.45 → 0.1.46

package/dist/index.d.ts

@@ -3,4 +3,9 @@ export * from "./generated/jsx.js";
 export { createPortal } from "./portal.js";
 export { reconciler } from "./reconciler.js";
 export { render } from "./render.js";
+/**
+ * Quits the GTK application and cleans up resources.
+ * Unmounts the React tree and stops the GTK main loop.
+ * @returns Always returns true (useful for signal handlers)
+ */
 export declare const quit: () => boolean;

package/dist/index.js

@@ -6,6 +6,11 @@ export { render } from "./render.js";
 import { stop } from "@gtkx/ffi";
 import { reconciler } from "./reconciler.js";
 import { container } from "./render.js";
+/**
+ * Quits the GTK application and cleans up resources.
+ * Unmounts the React tree and stops the GTK main loop.
+ * @returns Always returns true (useful for signal handlers)
+ */
 export const quit = () => {
     if (container) {
         reconciler.getInstance().updateContainer(null, container, null, () => {

package/dist/node.js

@@ -29,6 +29,7 @@ export class Node {
     }
     createWidget(type, props, app) {
         const normalizedType = type.split(".")[0] || type;
+        // biome-ignore lint/performance/noDynamicNamespaceImportAccess: dynamic widget creation
         const WidgetClass = Gtk[normalizedType];
         if (!WidgetClass) {
             throw new Error(`Unknown GTK widget type: ${normalizedType}`);

package/dist/nodes/text-view.js

@@ -26,6 +26,7 @@ export class TextViewNode extends Node {
         if (typeof props.text === "string") {
             setBufferText(this.buffer, props.text);
         }
+        // Connect after a microtask to avoid signal firing during widget construction
         queueMicrotask(() => this.connectBufferSignal());
     }
     connectBufferSignal() {

package/dist/portal.d.ts

@@ -1,2 +1,20 @@
 import type { ReactNode, ReactPortal } from "react";
+/**
+ * Creates a portal that renders children into a different GTK widget container.
+ *
+ * Similar to ReactDOM.createPortal, this allows you to render a subtree into
+ * a different part of the widget tree.
+ *
+ * When called without a container argument, the portal renders at the root level.
+ * This is useful for dialogs which don't need a parent container.
+ *
+ * @example
+ * ```tsx
+ * // Render dialog at root level (no container needed)
+ * {createPortal(<AboutDialog programName="My App" />)}
+ *
+ * // Render into a specific container
+ * {createPortal(<Label.Root label="This is in the Box" />, boxRef.current)}
+ * ```
+ */
 export declare const createPortal: (children: ReactNode, container?: unknown, key?: string | null) => ReactPortal;

package/dist/portal.js

@@ -1,4 +1,22 @@
 import { ROOT_NODE_CONTAINER } from "./factory.js";
+/**
+ * Creates a portal that renders children into a different GTK widget container.
+ *
+ * Similar to ReactDOM.createPortal, this allows you to render a subtree into
+ * a different part of the widget tree.
+ *
+ * When called without a container argument, the portal renders at the root level.
+ * This is useful for dialogs which don't need a parent container.
+ *
+ * @example
+ * ```tsx
+ * // Render dialog at root level (no container needed)
+ * {createPortal(<AboutDialog programName="My App" />)}
+ *
+ * // Render into a specific container
+ * {createPortal(<Label.Root label="This is in the Box" />, boxRef.current)}
+ * ```
+ */
 export const createPortal = (children, container, key) => {
     return {
         $$typeof: Symbol.for("react.portal"),

package/dist/reconciler.d.ts

@@ -8,13 +8,22 @@ type SuspenseInstance = never;
 type PublicInstance = Gtk.Widget;
 type FormInstance = never;
 type ReconcilerInstance = ReactReconciler.Reconciler<Container, Node, TextInstance, SuspenseInstance, FormInstance, PublicInstance>;
+/**
+ * GTKX React reconciler class.
+ */
 declare class Reconciler {
     private instance;
+    /** Creates a new GTK reconciler instance. */
     constructor();
+    /**
+     * Gets the underlying React reconciler instance.
+     * @returns The react-reconciler instance
+     */
     getInstance(): ReconcilerInstance;
     private createHostConfig;
     private createReconcilerContext;
     private createNodeFromContainer;
 }
+/** The singleton GTKX React reconciler instance. */
 export declare const reconciler: Reconciler;
 export {};

package/dist/reconciler.js

@@ -3,11 +3,19 @@ import React from "react";
 import ReactReconciler from "react-reconciler";
 import { beginCommit, endCommit } from "./batch.js";
 import { createNode } from "./factory.js";
+/**
+ * GTKX React reconciler class.
+ */
 class Reconciler {
     instance;
+    /** Creates a new GTK reconciler instance. */
     constructor() {
         this.instance = ReactReconciler(this.createHostConfig());
     }
+    /**
+     * Gets the underlying React reconciler instance.
+     * @returns The react-reconciler instance
+     */
     getInstance() {
         return this.instance;
     }
@@ -100,4 +108,5 @@ class Reconciler {
         return createNode(container.constructor.name, {}, getCurrentApp(), container);
     }
 }
+/** The singleton GTKX React reconciler instance. */
 export const reconciler = new Reconciler();

package/dist/render.d.ts

@@ -1,4 +1,23 @@
 import type { ApplicationFlags } from "@gtkx/ffi/gio";
 import type { ReactNode } from "react";
+/** The root container for the React reconciler. */
 export declare let container: unknown;
+/**
+ * Renders a React element tree as a GTK application.
+ * This is the main entry point for GTKX applications.
+ *
+ * @example
+ * ```tsx
+ * render(
+ *   <ApplicationWindow title="My App">
+ *     Hello, GTKX!
+ *   </ApplicationWindow>,
+ *   "com.example.myapp"
+ * );
+ * ```
+ *
+ * @param element - The root React element to render
+ * @param appId - The application ID (e.g., "com.example.myapp")
+ * @param flags - Optional GIO application flags
+ */
 export declare const render: (element: ReactNode, appId: string, flags?: ApplicationFlags) => void;

package/dist/render.js

@@ -1,7 +1,26 @@
 import { start } from "@gtkx/ffi";
 import { ROOT_NODE_CONTAINER } from "./factory.js";
 import { reconciler } from "./reconciler.js";
+/** The root container for the React reconciler. */
 export let container = null;
+/**
+ * Renders a React element tree as a GTK application.
+ * This is the main entry point for GTKX applications.
+ *
+ * @example
+ * ```tsx
+ * render(
+ *   <ApplicationWindow title="My App">
+ *     Hello, GTKX!
+ *   </ApplicationWindow>,
+ *   "com.example.myapp"
+ * );
+ * ```
+ *
+ * @param element - The root React element to render
+ * @param appId - The application ID (e.g., "com.example.myapp")
+ * @param flags - Optional GIO application flags
+ */
 export const render = (element, appId, flags) => {
     start(appId, flags);
     const instance = reconciler.getInstance();

package/dist/types.d.ts

@@ -11,6 +11,10 @@ export interface GridChildProps extends SlotProps {
     columnSpan?: number;
     rowSpan?: number;
 }
+/**
+ * Render function for ListView/GridView items.
+ * Called with null during setup (for loading state) and with the actual item during bind.
+ */
 export type RenderItemFn<T> = (item: T | null) => ReactElement;
 export interface ListViewRenderProps<T = unknown> {
     renderItem: RenderItemFn<T>;
@@ -20,6 +24,11 @@ export interface ColumnViewColumnProps {
     expand?: boolean;
     resizable?: boolean;
     fixedWidth?: number;
+    /**
+     * Render function for column cells.
+     * Called with null during setup (for loading state) and with the actual item during bind.
+     * Always annotate your callback parameter type to include null, e.g.: `(item: MyItem | null) => ...`
+     */
     renderCell: (item: any) => ReactElement;
 }
 export interface NotebookPageProps extends SlotProps {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/react",
-  "version": "0.1.45",
+  "version": "0.1.46",
   "description": "Build GTK4 desktop applications with React and TypeScript",
   "keywords": [
     "gtk",
@@ -36,10 +36,10 @@
   ],
   "dependencies": {
     "react-reconciler": "0.33.0",
-    "@gtkx/ffi": "0.1.45"
+    "@gtkx/ffi": "0.1.46"
   },
   "devDependencies": {
-    "@gtkx/gir": "0.1.45"
+    "@gtkx/gir": "0.1.46"
   },
   "peerDependencies": {
     "react": "^19"