@gtkx/react 0.21.0 → 1.0.0-rc.1

package/src/registry.ts

@@ -1,119 +0,0 @@
-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 { AlertDialogNode } from "./nodes/alert-dialog.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 { 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 { 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 { LevelBarNode } from "./nodes/level-bar.js";
-import { ListNode } from "./nodes/list.js";
-import { ListItemNode } from "./nodes/list-item-node.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 { SlotNode } from "./nodes/slot.js";
-import { SourceViewNode } from "./nodes/source-view.js";
-import { SpinRowNode } from "./nodes/spin-row.js";
-import { StackNode } from "./nodes/stack.js";
-import { StackPageNode } from "./nodes/stack-page.js";
-import { SwitchRowNode } from "./nodes/switch-row.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 { 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 PopoverMenuWidgets = [Gtk.PopoverMenu, Gtk.PopoverMenuBar, Gtk.MenuButton] as const;
-export type PopoverMenuWidget = InstanceType<(typeof PopoverMenuWidgets)[number]>;
-
-export type NodeClass = (new (
-    // biome-ignore lint/suspicious/noExplicitAny: Registry entries require flexible typing for varied node constructors
-    ...args: any[]
-) => Node) & {
-    // biome-ignore lint/suspicious/noExplicitAny: Registry entries require flexible typing for varied node constructors
-    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],
-    [["AdwTimedAnimation", "AdwSpringAnimation"], AnimationNode],
-    ["ColumnViewColumn", ColumnViewColumnNode],
-    ["FixedChild", FixedChildNode],
-    ["GridChild", GridChildNode],
-    [["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],
-    [Gtk.Application, ApplicationNode],
-    [Gtk.EventController, EventControllerNode],
-    [GtkSource.View, SourceViewNode],
-    [Gtk.TextView, TextViewNode],
-    [WebKit.WebView, WebViewNode],
-    [Adw.AlertDialog, AlertDialogNode],
-    [Adw.Dialog, DialogNode],
-    [Gtk.Window, WindowNode],
-    [Adw.SpinRow, SpinRowNode],
-    [Adw.SwitchRow, SwitchRowNode],
-    [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.ListView, Gtk.ColumnView, Gtk.GridView, Gtk.DropDown, Adw.ComboRow], ListNode],
-    [PopoverMenuWidgets, PopoverMenuNode],
-    [AdjustableWidgets, AdjustableNode],
-    [[Gtk.ListItem, Gtk.ListHeader], ListItemNode],
-    [Gtk.Widget, WidgetNode],
-];

package/src/render.tsx

@@ -1,192 +0,0 @@
-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

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

package/src/use-property.ts

@@ -1,58 +0,0 @@
-import * as GObject from "@gtkx/ffi/gobject";
-import { useEffect, useState } from "react";
-
-type ReadableKey<T> = {
-    [K in keyof T]: K extends string ? (T[K] extends (...args: unknown[]) => unknown ? never : K) : never;
-}[keyof T];
-
-const toKebabCase = (str: string): string =>
-    str.replace(/[A-Z]/g, (c, i: number) => (i === 0 ? c.toLowerCase() : `-${c.toLowerCase()}`));
-
-/**
- * Subscribes to a GObject property and returns its current value as React state.
- *
- * Connects to the `notify::property-name` signal on `obj` and re-renders
- * whenever the property changes. The initial value is read synchronously
- * at mount time. Disconnects automatically on unmount or when inputs change.
- *
- * When `obj` is `null` or `undefined`, the hook is inactive and returns
- * `undefined`. This allows safe usage with nullable objects without
- * violating React's rules of hooks.
- *
- * @param obj - The GObject instance to observe, or null/undefined to disable
- * @param propertyName - The property name matching an ES6 accessor on the object
- * @returns The current property value, or undefined when obj is null/undefined
- *
- * @example
- * ```tsx
- * const app = useApplication();
- * const activeWindow = useProperty(app, "activeWindow");
- * const title = useProperty(activeWindow, "title");
- * ```
- */
-export function useProperty<T extends GObject.Object, K extends ReadableKey<T>>(
-    obj: T | null | undefined,
-    propertyName: K,
-): T[K] | undefined {
-    const [value, setValue] = useState<T[K] | undefined>(() => (obj ? (obj[propertyName] as T[K]) : undefined));
-
-    useEffect(() => {
-        if (!obj) {
-            setValue(undefined);
-            return;
-        }
-
-        setValue(obj[propertyName] as T[K]);
-
-        const signal = `notify::${toKebabCase(propertyName as string)}`;
-        const handlerId = obj.connect(signal, () => {
-            setValue(obj[propertyName] as T[K]);
-        });
-
-        return () => {
-            GObject.signalHandlerDisconnect(obj, handlerId);
-        };
-    }, [obj, propertyName]);
-
-    return value;
-}

package/src/use-setting.ts

@@ -1,96 +0,0 @@
-import * as Gio from "@gtkx/ffi/gio";
-import * as GObject from "@gtkx/ffi/gobject";
-import { useCallback, useEffect, useMemo, useState } from "react";
-
-interface SettingTypeMap {
-    boolean: boolean;
-    int: number;
-    double: number;
-    string: string;
-    strv: string[];
-}
-
-type SettingType = keyof SettingTypeMap;
-
-const GETTERS: Record<SettingType, string> = {
-    boolean: "getBoolean",
-    int: "getInt",
-    double: "getDouble",
-    string: "getString",
-    strv: "getStrv",
-};
-
-const SETTERS: Record<SettingType, string> = {
-    boolean: "setBoolean",
-    int: "setInt",
-    double: "setDouble",
-    string: "setString",
-    strv: "setStrv",
-};
-
-type SettingAccessor = (key: string, value?: unknown) => unknown;
-
-function readSetting(settings: Gio.Settings, key: string, type: SettingType): unknown {
-    const getter = (settings as unknown as Record<string, SettingAccessor>)[GETTERS[type]] as SettingAccessor;
-    return getter.call(settings, key);
-}
-
-function writeSetting(settings: Gio.Settings, key: string, type: SettingType, value: unknown): void {
-    const setter = (settings as unknown as Record<string, SettingAccessor>)[SETTERS[type]] as SettingAccessor;
-    setter.call(settings, key, value);
-}
-
-/**
- * Subscribes to a GSettings key and returns its current value alongside a
- * setter, similar to `useState`.
- *
- * Creates a `Gio.Settings` instance for the given schema (stable across
- * re-renders), connects to `changed::key`, and re-renders whenever the
- * setting changes. The initial value is read synchronously at mount time.
- * Calling the returned setter writes the new value to GSettings, which in
- * turn triggers a re-render through the `changed` signal.
- *
- * @param schemaId - The GSettings schema ID (e.g. `"org.gnome.desktop.interface"`)
- * @param key - The settings key in kebab-case (e.g. `"color-scheme"`)
- * @param type - The value type, used to select the appropriate GSettings getter/setter
- * @returns A `[value, setValue]` tuple kept in sync with the GSettings backend
- *
- * @example
- * ```tsx
- * const [colorScheme, setColorScheme] = useSetting("org.gnome.desktop.interface", "color-scheme", "string");
- * ```
- *
- * @example
- * ```tsx
- * const [fontSize, setFontSize] = useSetting("com.example.myapp", "font-size", "int");
- * ```
- */
-export function useSetting<T extends SettingType>(
-    schemaId: string,
-    key: string,
-    type: T,
-): [SettingTypeMap[T], (value: SettingTypeMap[T]) => void] {
-    const settings = useMemo(() => new Gio.Settings(schemaId), [schemaId]);
-    const [value, setValue] = useState<SettingTypeMap[T]>(() => readSetting(settings, key, type) as SettingTypeMap[T]);
-
-    useEffect(() => {
-        setValue(readSetting(settings, key, type) as SettingTypeMap[T]);
-
-        const handlerId = settings.connect(`changed::${key}`, () => {
-            setValue(readSetting(settings, key, type) as SettingTypeMap[T]);
-        });
-
-        return () => {
-            GObject.signalHandlerDisconnect(settings, handlerId);
-        };
-    }, [settings, key, type]);
-
-    const set = useCallback(
-        (newValue: SettingTypeMap[T]) => {
-            writeSetting(settings, key, type, newValue);
-        },
-        [settings, key, type],
-    );
-
-    return [value, set];
-}