@gtkx/react 0.18.0 → 0.18.2

package/src/registry.ts

@@ -0,0 +1,123 @@
+import * as Adw from "@gtkx/ffi/adw";
+import * as Gtk from "@gtkx/ffi/gtk";
+import * as GtkSource from "@gtkx/ffi/gtksource";
+import * as WebKit from "@gtkx/ffi/webkit";
+import type { Node } from "./node.js";
+import { AdjustableNode } from "./nodes/adjustable.js";
+
+import { AlertDialogResponseNode } from "./nodes/alert-dialog-response.js";
+import { AnimationNode } from "./nodes/animation.js";
+import { ApplicationNode } from "./nodes/application.js";
+import { CalendarNode } from "./nodes/calendar.js";
+import { ColorDialogButtonNode } from "./nodes/color-dialog-button.js";
+import { ColumnViewNode } from "./nodes/column-view.js";
+import { ColumnViewColumnNode } from "./nodes/column-view-column.js";
+import { ContainerSlotNode } from "./nodes/container-slot.js";
+import { DialogNode } from "./nodes/dialog.js";
+import { DrawingAreaNode } from "./nodes/drawing-area.js";
+import { DropDownNode } from "./nodes/drop-down.js";
+import { EventControllerNode } from "./nodes/event-controller.js";
+import { FixedChildNode } from "./nodes/fixed-child.js";
+import { FontDialogButtonNode } from "./nodes/font-dialog-button.js";
+import { GridChildNode } from "./nodes/grid-child.js";
+import { GridViewNode } from "./nodes/grid-view.js";
+import { LevelBarNode } from "./nodes/level-bar.js";
+import { ListItemNode } from "./nodes/list-item.js";
+import { ListViewNode } from "./nodes/list-view.js";
+import { MenuNode } from "./nodes/menu.js";
+import { NavigationPageNode } from "./nodes/navigation-page.js";
+import { NavigationViewNode } from "./nodes/navigation-view.js";
+import { NotebookNode } from "./nodes/notebook.js";
+import { NotebookPageNode } from "./nodes/notebook-page.js";
+import { NotebookPageTabNode } from "./nodes/notebook-page-tab.js";
+import { OverlayChildNode } from "./nodes/overlay-child.js";
+import { PopoverMenuNode } from "./nodes/popover-menu.js";
+import { ScaleNode } from "./nodes/scale.js";
+import { ScrolledWindowNode } from "./nodes/scrolled-window.js";
+import { SearchBarNode } from "./nodes/search-bar.js";
+import { ShortcutNode } from "./nodes/shortcut.js";
+import { ShortcutControllerNode } from "./nodes/shortcut-controller.js";
+import { SlotNode } from "./nodes/slot.js";
+import { SourceViewNode } from "./nodes/source-view.js";
+import { StackNode } from "./nodes/stack.js";
+import { StackPageNode } from "./nodes/stack-page.js";
+import { TextAnchorNode } from "./nodes/text-anchor.js";
+import { TextPaintableNode } from "./nodes/text-paintable.js";
+import { TextSegmentNode } from "./nodes/text-segment.js";
+import { TextTagNode } from "./nodes/text-tag.js";
+import { TextViewNode } from "./nodes/text-view.js";
+import { ToggleNode } from "./nodes/toggle.js";
+import { ToggleGroupNode } from "./nodes/toggle-group.js";
+import { WebViewNode } from "./nodes/web-view.js";
+import { WidgetNode } from "./nodes/widget.js";
+import { WindowNode } from "./nodes/window.js";
+
+export const AdjustableWidgets = [Gtk.SpinButton, Gtk.ScaleButton, Gtk.Range] as const;
+export type AdjustableWidget = InstanceType<(typeof AdjustableWidgets)[number]>;
+
+export const StackWidgets = [Gtk.Stack, Adw.ViewStack] as const;
+export type StackWidget = InstanceType<(typeof StackWidgets)[number]>;
+
+export const DropDownWidgets = [Gtk.DropDown, Adw.ComboRow] as const;
+export type DropDownWidget = InstanceType<(typeof DropDownWidgets)[number]>;
+
+export const PopoverMenuWidgets = [Gtk.PopoverMenu, Gtk.PopoverMenuBar, Gtk.MenuButton] as const;
+export type PopoverMenuWidget = InstanceType<(typeof PopoverMenuWidgets)[number]>;
+
+// biome-ignore lint/suspicious/noExplicitAny: Registry entries require flexible typing for varied node constructors
+export type NodeClass = (new (...args: any[]) => Node) & { createContainer(...args: any[]): unknown };
+
+// biome-ignore lint/suspicious/noExplicitAny: Class keys require flexible typing for GTK class hierarchy matching
+type ClassKey = new (...args: any[]) => any;
+type RegistryKey = string | ClassKey | readonly (string | ClassKey)[];
+type NodeRegistryEntry = [RegistryKey, NodeClass];
+
+export const NODE_REGISTRY: NodeRegistryEntry[] = [
+    ["ContainerSlot", ContainerSlotNode],
+    ["AlertDialogResponse", AlertDialogResponseNode],
+    ["Animation", AnimationNode],
+    ["ColumnViewColumn", ColumnViewColumnNode],
+    ["FixedChild", FixedChildNode],
+    ["GridChild", GridChildNode],
+    ["ListItem", ListItemNode],
+    [["MenuItem", "MenuSection", "MenuSubmenu"], MenuNode],
+    ["NavigationPage", NavigationPageNode],
+    ["NotebookPage", NotebookPageNode],
+    ["NotebookPageTab", NotebookPageTabNode],
+    ["OverlayChild", OverlayChildNode],
+    ["Shortcut", ShortcutNode],
+    ["Slot", SlotNode],
+    ["StackPage", StackPageNode],
+    ["TextAnchor", TextAnchorNode],
+    ["TextPaintable", TextPaintableNode],
+    ["TextSegment", TextSegmentNode],
+    ["TextTag", TextTagNode],
+    ["Toggle", ToggleNode],
+    [Gtk.Application, ApplicationNode],
+    [Gtk.ShortcutController, ShortcutControllerNode],
+    [Gtk.EventController, EventControllerNode],
+    [GtkSource.View, SourceViewNode],
+    [Gtk.TextView, TextViewNode],
+    [WebKit.WebView, WebViewNode],
+    [Adw.Dialog, DialogNode],
+    [Gtk.Window, WindowNode],
+    [Gtk.Scale, ScaleNode],
+    [Gtk.LevelBar, LevelBarNode],
+    [Gtk.ScrolledWindow, ScrolledWindowNode],
+    [Gtk.Calendar, CalendarNode],
+    [Gtk.ColorDialogButton, ColorDialogButtonNode],
+    [Gtk.FontDialogButton, FontDialogButtonNode],
+    [Gtk.DrawingArea, DrawingAreaNode],
+    [Gtk.SearchBar, SearchBarNode],
+    [Adw.NavigationView, NavigationViewNode],
+    [Adw.ToggleGroup, ToggleGroupNode],
+    [Gtk.Notebook, NotebookNode],
+    [StackWidgets, StackNode],
+    [Gtk.ColumnView, ColumnViewNode],
+    [Gtk.ListView, ListViewNode],
+    [Gtk.GridView, GridViewNode],
+    [DropDownWidgets, DropDownNode],
+    [PopoverMenuWidgets, PopoverMenuNode],
+    [AdjustableWidgets, AdjustableNode],
+    [Gtk.Widget, WidgetNode],
+];

package/src/render.tsx

@@ -0,0 +1,192 @@
+import { start, stop } from "@gtkx/ffi";
+import type * as Gio from "@gtkx/ffi/gio";
+import type * as Gtk from "@gtkx/ffi/gtk";
+import { createContext, type ReactNode, useContext } from "react";
+import { formatBoundaryError, formatRenderError } from "./errors.js";
+import { getSignalStore } from "./nodes/internal/signal-store.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<Gtk.Application | null>(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 = (): Gtk.Application => {
+    const context = useContext(ApplicationContext);
+
+    if (!context) {
+        throw new Error("Expected ApplicationContext: useApplication must be called within Application");
+    }
+
+    return context;
+};
+
+let container: unknown = null;
+let app: Gtk.Application | null = 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: boolean): void => {
+    isHotReloading = value;
+};
+
+/**
+ * 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
+ * import { render, quit } from "@gtkx/react";
+ *
+ * const App = () => (
+ * <GtkApplicationWindow title="My App" onClose={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 const render = (element: ReactNode, appId: string, flags?: Gio.ApplicationFlags): void => {
+    const application = start(appId, flags);
+    app = application;
+    const instance = reconciler.getInstance();
+
+    container = instance.createContainer(
+        application,
+        1,
+        null,
+        false,
+        null,
+        "",
+        (error: unknown) => {
+            getSignalStore(application).forceUnblockAll();
+            throw formatRenderError(error);
+        },
+        (error: unknown) => {
+            getSignalStore(application).forceUnblockAll();
+            const formattedError = formatBoundaryError(error);
+            console.error(formattedError.toString());
+        },
+        () => {},
+        () => {},
+    );
+
+    instance.updateContainer(
+        <ApplicationContext.Provider value={application}>{element}</ApplicationContext.Provider>,
+        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: ReactNode): Promise<void> => {
+    return new Promise((resolve) => {
+        reconciler
+            .getInstance()
+            .updateContainer(
+                <ApplicationContext.Provider value={app}>{element}</ApplicationContext.Provider>,
+                container,
+                null,
+                resolve,
+            );
+    });
+};
+
+/**
+ * Gracefully shuts down the GTK application.
+ *
+ * Unmounts the React component tree and stops the GTK main loop.
+ * Typically used as the `onClose` handler for the application window.
+ *
+ * @example
+ * ```tsx
+ * import { quit } from "@gtkx/react";
+ *
+ * const App = () => (
+ * <GtkApplicationWindow title="My App" onClose={quit}>
+ * <GtkButton label="Quit" onClicked={quit} />
+ * </GtkApplicationWindow>
+ * );
+ * ```
+ *
+ * @see {@link render} for starting the application
+ */
+export const quit = (): void => {
+    if (isHotReloading) {
+        return;
+    }
+
+    reconciler.getInstance().updateContainer(null, container, null, () => {
+        setTimeout(() => {
+            stop();
+        }, 0);
+    });
+};

package/src/types.ts

@@ -0,0 +1,7 @@
+import type * as Gtk from "@gtkx/ffi/gtk";
+
+export type Container = Gtk.Widget | Gtk.Application | Gtk.EventController;
+
+export type Props = Record<string, unknown>;
+
+export type ContainerClass = typeof Gtk.Widget | typeof Gtk.Application | typeof Gtk.EventController;