@gtkx/react 0.9.4 → 0.10.0

package/dist/portal.js

@@ -1,23 +1,26 @@
-import { ROOT_NODE_CONTAINER } from "./factory.js";
 /**
- * Creates a portal that renders children into a different GTK widget container.
+ * Creates a React portal for rendering children into a different part of the widget tree.
  *
- * Similar to ReactDOM.createPortal, this allows you to render a subtree into
- * a different part of the widget tree.
+ * Portals are useful for rendering dialogs, tooltips, or other floating content
+ * that should visually appear outside its parent component's boundaries.
  *
- * 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.
- *
- * Implementation note: ReactPortal is an opaque type, so we manually construct
- * the internal representation required by custom reconcilers.
+ * @param children - The React elements to render in the portal
+ * @param container - The target container widget to render into
+ * @param key - Optional key for the portal element
+ * @returns A ReactPortal element
  *
  * @example
  * ```tsx
- * // Render dialog at root level (no container needed)
- * {createPortal(<AboutDialog programName="My App" />)}
+ * import { createPortal } from "@gtkx/react";
  *
- * // Render into a specific container
- * {createPortal(<Label label="This is in the Box" />, boxRef.current)}
+ * const Modal = ({ container, children }) => {
+ *   return createPortal(
+ *     <GtkWindow modal>
+ *       {children}
+ *     </GtkWindow>,
+ *     container
+ *   );
+ * };
  * ```
  */
 export const createPortal = (children, container, key) => {
@@ -25,7 +28,7 @@ export const createPortal = (children, container, key) => {
         $$typeof: Symbol.for("react.portal"),
         key: key ?? null,
         children,
-        containerInfo: container ?? ROOT_NODE_CONTAINER,
+        containerInfo: container,
         implementation: null,
     };
 };

package/dist/reconciler.d.ts

@@ -5,9 +5,5 @@ declare class Reconciler {
     getInstance(): ReconcilerInstance;
     private injectDevTools;
 }
-/**
- * The singleton GTKX React reconciler instance.
- * @private This is an internal API used only by @gtkx/testing. Do not use directly.
- */
 export declare const reconciler: Reconciler;
 export {};

package/dist/reconciler.js

@@ -1,14 +1,10 @@
 import ReactReconciler from "react-reconciler";
 import packageJson from "../package.json" with { type: "json" };
-import { createNode } from "./factory.js";
 import { createHostConfig } from "./host-config.js";
 class Reconciler {
     instance;
     constructor() {
-        const createNodeFromContainer = (container) => {
-            return createNode(container.constructor.name, {}, container);
-        };
-        this.instance = ReactReconciler(createHostConfig(createNodeFromContainer));
+        this.instance = ReactReconciler(createHostConfig());
         this.injectDevTools();
     }
     getInstance() {
@@ -24,8 +20,4 @@ class Reconciler {
         });
     }
 }
-/**
- * The singleton GTKX React reconciler instance.
- * @private This is an internal API used only by @gtkx/testing. Do not use directly.
- */
 export const reconciler = new Reconciler();

package/dist/registry.d.ts

@@ -0,0 +1,8 @@
+import type { Node } from "./node.js";
+import type { Container, Props } from "./types.js";
+type NodeClass<T = unknown, P = Props> = {
+    new (typeName: string, props: P, container: T, rootContainer?: Container): Node<T, P>;
+} & Omit<typeof Node, "prototype">;
+export declare const NODE_CLASSES: NodeClass[];
+export declare const registerNodeClass: <T, P>(nodeClass: NodeClass<T, P>) => void;
+export {};

package/dist/registry.js

@@ -0,0 +1,5 @@
+export const NODE_CLASSES = [];
+export const registerNodeClass = (nodeClass) => {
+    NODE_CLASSES.push(nodeClass);
+    NODE_CLASSES.sort((a, b) => a.priority - b.priority);
+};

package/dist/render.d.ts

@@ -1,22 +1,118 @@
 import type * as Gio from "@gtkx/ffi/gio";
-import type { ReactNode } from "react";
-export declare const getContainer: () => unknown;
+import type * as Gtk from "@gtkx/ffi/gtk";
+import { type ReactNode } from "react";
 /**
- * Renders a React element tree as a GTK application.
- * This is the main entry point for GTKX applications.
+ * React Context providing access to the GTK Application instance.
+ *
+ * Use {@link useApplication} to access the application in components.
  *
  * @example
  * ```tsx
- * render(
- *   <ApplicationWindow title="My App">
- *     Hello, GTKX!
- *   </ApplicationWindow>,
- *   "com.example.myapp"
- * );
+ * const App = () => {
+ *   const app = useApplication();
+ *   console.log(app.applicationId);
+ *   return <GtkLabel label="Hello" />;
+ * };
+ * ```
+ */
+export declare const ApplicationContext: React.Context<Gtk.Application | null>;
+/**
+ * Hook to access the GTK Application instance.
+ *
+ * Must be called within a component rendered by {@link render}.
+ * Throws an error if called outside the application context.
+ *
+ * @returns The GTK Application instance
+ *
+ * @example
+ * ```tsx
+ * const MyComponent = () => {
+ *   const app = useApplication();
+ *   return <GtkLabel label={app.applicationId} />;
+ * };
  * ```
  *
+ * @see {@link ApplicationContext} for the underlying context
+ */
+export declare const useApplication: () => Gtk.Application;
+/**
+ * Sets the hot reloading state.
+ *
+ * Used internally by the dev server to prevent quit() from closing
+ * the application during HMR updates.
+ *
+ * @internal
+ */
+export declare const setHotReloading: (value: boolean) => void;
+/**
+ * Renders a React element tree into a GTK4 application window.
+ *
+ * This is the main entry point for GTKX applications. It initializes the GTK4
+ * runtime, creates an application container, and begins the React reconciliation
+ * process.
+ *
  * @param element - The root React element to render
- * @param appId - The application ID (e.g., "com.example.myapp")
- * @param flags - Optional GIO application flags
+ * @param appId - Application ID in reverse domain notation (e.g., "com.example.myapp")
+ * @param flags - Optional GIO application flags for customizing behavior
+ *
+ * @example
+ * ```tsx
+ * import { render, quit } from "@gtkx/react";
+ *
+ * const App = () => (
+ *   <GtkApplicationWindow title="My App" onCloseRequest={quit}>
+ *     <GtkLabel label="Hello, GTKX!" />
+ *   </GtkApplicationWindow>
+ * );
+ *
+ * render(<App />, "com.example.myapp");
+ * ```
+ *
+ * @see {@link quit} for shutting down the application
+ * @see {@link update} for hot-reloading the rendered tree
  */
 export declare const render: (element: ReactNode, appId: string, flags?: Gio.ApplicationFlags) => void;
+/**
+ * Updates the rendered React element tree.
+ *
+ * Used primarily for hot module replacement (HMR) during development.
+ * Replaces the current component tree with a new element without
+ * reinitializing the GTK application.
+ *
+ * @param element - The new root React element to render
+ *
+ * @example
+ * ```tsx
+ * // In HMR handler
+ * if (import.meta.hot) {
+ *   import.meta.hot.accept(() => {
+ *     update(<App />);
+ *   });
+ * }
+ * ```
+ *
+ * @see {@link render} for initial rendering
+ */
+export declare const update: (element: ReactNode) => Promise<void>;
+/**
+ * Gracefully shuts down the GTK application.
+ *
+ * Unmounts the React component tree and stops the GTK main loop.
+ * Typically used as the `onCloseRequest` handler for the application window.
+ *
+ * @returns `false` to allow GTK to close the window
+ *
+ * @example
+ * ```tsx
+ * import { quit } from "@gtkx/react";
+ *
+ * const App = () => (
+ *   <GtkApplicationWindow title="My App" onCloseRequest={quit}>
+ *     <GtkButton label="Quit" onClicked={quit} />
+ *   </GtkApplicationWindow>
+ * );
+ * ```
+ *
+ * @see {@link render} for starting the application
+ */
+export declare const quit: () => boolean;

package/dist/render.js

@@ -1,35 +1,159 @@
-import { start } from "@gtkx/ffi";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { discardAllBatches, start, stop } from "@gtkx/ffi";
+import { createContext, useContext } from "react";
 import { formatBoundaryError, formatRenderError } from "./errors.js";
-import { ROOT_NODE_CONTAINER } from "./factory.js";
 import { reconciler } from "./reconciler.js";
+/**
+ * React Context providing access to the GTK Application instance.
+ *
+ * Use {@link useApplication} to access the application in components.
+ *
+ * @example
+ * ```tsx
+ * const App = () => {
+ *   const app = useApplication();
+ *   console.log(app.applicationId);
+ *   return <GtkLabel label="Hello" />;
+ * };
+ * ```
+ */
+export const ApplicationContext = createContext(null);
+/**
+ * Hook to access the GTK Application instance.
+ *
+ * Must be called within a component rendered by {@link render}.
+ * Throws an error if called outside the application context.
+ *
+ * @returns The GTK Application instance
+ *
+ * @example
+ * ```tsx
+ * const MyComponent = () => {
+ *   const app = useApplication();
+ *   return <GtkLabel label={app.applicationId} />;
+ * };
+ * ```
+ *
+ * @see {@link ApplicationContext} for the underlying context
+ */
+export const useApplication = () => {
+    const context = useContext(ApplicationContext);
+    if (!context) {
+        throw new Error("Expected ApplicationContext: useApplication must be called within Application");
+    }
+    return context;
+};
 let container = null;
-export const getContainer = () => container;
+let app = null;
+let isHotReloading = false;
+/**
+ * Sets the hot reloading state.
+ *
+ * Used internally by the dev server to prevent quit() from closing
+ * the application during HMR updates.
+ *
+ * @internal
+ */
+export const setHotReloading = (value) => {
+    isHotReloading = value;
+};
 /**
- * Renders a React element tree as a GTK application.
- * This is the main entry point for GTKX applications.
+ * Renders a React element tree into a GTK4 application window.
+ *
+ * This is the main entry point for GTKX applications. It initializes the GTK4
+ * runtime, creates an application container, and begins the React reconciliation
+ * process.
+ *
+ * @param element - The root React element to render
+ * @param appId - Application ID in reverse domain notation (e.g., "com.example.myapp")
+ * @param flags - Optional GIO application flags for customizing behavior
  *
  * @example
  * ```tsx
- * render(
- *   <ApplicationWindow title="My App">
- *     Hello, GTKX!
- *   </ApplicationWindow>,
- *   "com.example.myapp"
+ * import { render, quit } from "@gtkx/react";
+ *
+ * const App = () => (
+ *   <GtkApplicationWindow title="My App" onCloseRequest={quit}>
+ *     <GtkLabel label="Hello, GTKX!" />
+ *   </GtkApplicationWindow>
  * );
+ *
+ * render(<App />, "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
+ * @see {@link quit} for shutting down the application
+ * @see {@link update} for hot-reloading the rendered tree
  */
 export const render = (element, appId, flags) => {
-    start(appId, flags);
+    app = start(appId, flags);
     const instance = reconciler.getInstance();
-    container = instance.createContainer(ROOT_NODE_CONTAINER, 0, null, false, null, "", (error) => {
+    container = instance.createContainer(app, 0, null, false, null, "", (error) => {
+        discardAllBatches();
         throw formatRenderError(error);
     }, (error) => {
+        discardAllBatches();
         const formattedError = formatBoundaryError(error);
         console.error(formattedError.toString());
     }, () => { }, () => { }, null);
-    instance.updateContainer(element, container, null, () => { });
+    instance.updateContainer(_jsx(ApplicationContext.Provider, { value: app, children: element }), container, null, () => { });
+};
+/**
+ * Updates the rendered React element tree.
+ *
+ * Used primarily for hot module replacement (HMR) during development.
+ * Replaces the current component tree with a new element without
+ * reinitializing the GTK application.
+ *
+ * @param element - The new root React element to render
+ *
+ * @example
+ * ```tsx
+ * // In HMR handler
+ * if (import.meta.hot) {
+ *   import.meta.hot.accept(() => {
+ *     update(<App />);
+ *   });
+ * }
+ * ```
+ *
+ * @see {@link render} for initial rendering
+ */
+export const update = (element) => {
+    return new Promise((resolve) => {
+        reconciler
+            .getInstance()
+            .updateContainer(_jsx(ApplicationContext.Provider, { value: app, children: element }), container, null, resolve);
+    });
+};
+/**
+ * Gracefully shuts down the GTK application.
+ *
+ * Unmounts the React component tree and stops the GTK main loop.
+ * Typically used as the `onCloseRequest` handler for the application window.
+ *
+ * @returns `false` to allow GTK to close the window
+ *
+ * @example
+ * ```tsx
+ * import { quit } from "@gtkx/react";
+ *
+ * const App = () => (
+ *   <GtkApplicationWindow title="My App" onCloseRequest={quit}>
+ *     <GtkButton label="Quit" onClicked={quit} />
+ *   </GtkApplicationWindow>
+ * );
+ * ```
+ *
+ * @see {@link render} for starting the application
+ */
+export const quit = () => {
+    if (isHotReloading) {
+        return true;
+    }
+    reconciler.getInstance().updateContainer(null, container, null, () => {
+        setTimeout(() => {
+            stop();
+        }, 0);
+    });
+    return true;
 };

package/dist/scheduler.d.ts

@@ -0,0 +1,4 @@
+type Callback = () => void;
+export declare const scheduleAfterCommit: (callback: Callback) => void;
+export declare const flushAfterCommit: () => void;
+export {};

package/dist/scheduler.js

@@ -0,0 +1,10 @@
+const pendingCallbacks = [];
+export const scheduleAfterCommit = (callback) => {
+    pendingCallbacks.push(callback);
+};
+export const flushAfterCommit = () => {
+    const callbacks = pendingCallbacks.splice(0);
+    for (const callback of callbacks) {
+        callback();
+    }
+};

package/dist/types.d.ts

@@ -1,137 +1,4 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
-import type { ReactElement, ReactNode } from "react";
-/**
- * Props for slot components that accept children.
- * Used by container widgets that render child elements in designated slots.
- */
-export type SlotProps = {
-    children?: ReactNode;
-};
-/**
- * Props passed to list item components (ListView, GridView, ColumnView).
- * @typeParam I - The type of the data item
- */
-export type ListItemProps<I = unknown> = {
-    /** Unique identifier for this item. Used for selection. */
-    id: string;
-    /** The data item to render. */
-    item: I;
-};
-/**
- * Props for string list items (DropDown, ComboRow).
- * Similar to HTML select option elements.
- */
-export type StringListItemProps = {
-    /** Unique identifier for this item. Used for selection. */
-    id: string;
-    /** Display text shown in the dropdown. */
-    label: string;
-};
-export type GridChildProps = SlotProps & {
-    column?: number;
-    row?: number;
-    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;
-/**
- * Props for ListView and GridView components.
- * @typeParam T - The type of the data items in the list
- */
-export type ListViewRenderProps<T = unknown> = {
-    /** Render function called for each item in the list. */
-    renderItem: RenderItemFn<T>;
-};
-/**
- * Props for individual columns in a ColumnView.
- * @typeParam T - The type of the data items displayed in the column
- */
-export type ColumnViewColumnProps<T = unknown> = {
-    /** The column header title. */
-    title?: string;
-    /** Whether the column should expand to fill available space. */
-    expand?: boolean;
-    /** Whether the column can be resized by the user. */
-    resizable?: boolean;
-    /** Fixed width in pixels. Overrides automatic sizing. */
-    fixedWidth?: number;
-    /** Unique identifier for the column. Used for sorting. */
-    id?: string;
-    /** Whether this column header can be clicked to trigger sorting. */
-    sortable?: boolean;
-    /**
-     * 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: T | null) => ReactElement;
-};
-/**
- * Props for the ColumnView root component.
- * Sorting is handled by the parent component - sort your items before rendering
- * and pass them as ColumnView.Item children in the desired order.
- * @typeParam C - The union type of column IDs
- */
-export type ColumnViewRootProps<C extends string = string> = {
-    /** The ID of the currently sorted column, or null if unsorted. Controls the sort indicator UI. */
-    sortColumn?: C | null;
-    /** The current sort direction. Controls the sort indicator UI. */
-    sortOrder?: Gtk.SortType;
-    /** Callback fired when the user clicks a column header to change sort. */
-    onSortChange?: (column: C | null, order: Gtk.SortType) => void;
-};
-export type NotebookPageProps = SlotProps & {
-    label: string;
-};
-export type StackRootProps = SlotProps & {
-    visibleChildName?: string;
-};
-export type StackPageProps = SlotProps & {
-    name?: string;
-    title?: string;
-    iconName?: string;
-    needsAttention?: boolean;
-    visible?: boolean;
-    useUnderline?: boolean;
-};
-/**
- * Props for the Menu.Root component.
- * Root container for declarative menu structures.
- */
-export type MenuRootProps = {
-    children?: ReactNode;
-};
-/**
- * Props for Menu.Item components.
- * Represents a single menu item with an action.
- */
-export type MenuItemProps = {
-    /** The visible label for the menu item. */
-    label: string;
-    /** Callback invoked when the menu item is activated. */
-    onActivate?: () => void;
-    /** Keyboard accelerators for this menu item (e.g., `"<Control>q"` or `["<Control>q", "<Control>w"]`). */
-    accels?: string | string[];
-};
-/**
- * Props for Menu.Section components.
- * Groups related menu items with optional label.
- */
-export type MenuSectionProps = {
-    /** Optional section label displayed as a header. */
-    label?: string;
-    children?: ReactNode;
-};
-/**
- * Props for Menu.Submenu components.
- * Creates a nested submenu with its own items.
- */
-export type MenuSubmenuProps = {
-    /** The submenu label shown in parent menu. */
-    label: string;
-    children?: ReactNode;
-};
+export type Container = Gtk.Widget | Gtk.Application;
+export type Props = Record<string, unknown>;
+export type ContainerClass = typeof Gtk.Widget | typeof Gtk.Application;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/react",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Build GTK4 desktop applications with React and TypeScript",
   "keywords": [
     "gtk",
@@ -36,18 +36,18 @@
   ],
   "dependencies": {
     "react-reconciler": "^0.33.0",
-    "@gtkx/ffi": "0.9.4"
+    "@gtkx/ffi": "0.10.0",
+    "@gtkx/gir": "0.10.0"
   },
   "devDependencies": {
-    "@gtkx/gir": "0.9.4",
-    "@gtkx/native": "0.9.4"
+    "@types/react-reconciler": "^0.32.3",
+    "@gtkx/codegen": "0.0.0"
   },
   "peerDependencies": {
     "react": "^19"
   },
   "scripts": {
     "build": "tsc -b && cp ../../README.md .",
-    "codegen": "tsx scripts/codegen.ts",
-    "test": "../../scripts/run-tests.sh"
+    "codegen": "gtkx-codegen jsx --girs-dir ../../girs --output-dir src/generated"
   }
 }

package/dist/batch.d.ts

@@ -1,5 +0,0 @@
-type FlushCallback = () => void;
-export declare const beginCommit: () => void;
-export declare const endCommit: () => void;
-export declare const scheduleFlush: (callback: FlushCallback) => void;
-export {};

package/dist/batch.js

@@ -1,31 +0,0 @@
-const state = {
-    depth: 0,
-    pendingFlushes: new Set(),
-};
-export const beginCommit = () => {
-    state.depth++;
-};
-export const endCommit = () => {
-    if (state.depth <= 0) {
-        state.depth = 0;
-        return;
-    }
-    state.depth--;
-    if (state.depth === 0 && state.pendingFlushes.size > 0) {
-        const callbacks = [...state.pendingFlushes];
-        state.pendingFlushes.clear();
-        queueMicrotask(() => {
-            for (const callback of callbacks) {
-                callback();
-            }
-        });
-    }
-};
-export const scheduleFlush = (callback) => {
-    if (state.depth > 0) {
-        state.pendingFlushes.add(callback);
-    }
-    else {
-        callback();
-    }
-};