@gtkx/react 0.20.0 → 1.0.0-rc.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gtkx/react",
-  "version": "0.20.0",
-  "description": "Build GTK4 desktop applications with React and TypeScript",
+  "version": "1.0.0-rc.1",
+  "description": "React reconciler that renders GTK4 object trees, with the portals, signal handling, and hooks GTKX apps use",
   "keywords": [
     "gtkx",
     "gtk",
@@ -19,7 +19,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/gtkx-org/gtkx.git",
+    "url": "git+https://github.com/gtkx-org/gtkx.git",
     "directory": "packages/react"
   },
   "license": "MPL-2.0",
@@ -30,17 +30,30 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
+    },
+    "./adw": {
+      "types": "./dist/libraries/adw/index.d.ts",
+      "default": "./dist/libraries/adw/index.js"
     }
   },
   "sideEffects": false,
   "files": [
     "dist",
-    "src"
+    "src",
+    "!**/*.tsbuildinfo"
   ],
+  "engines": {
+    "node": ">=24"
+  },
   "dependencies": {
     "react-reconciler": "^0.33.0",
-    "@gtkx/gir": "0.20.0",
-    "@gtkx/ffi": "0.20.0"
+    "@gtkx/config": "1.0.0-rc.1",
+    "@gtkx/runtime": "1.0.0-rc.1",
+    "@gtkx/utils": "1.0.0-rc.1"
   },
   "devDependencies": {
     "@types/react-reconciler": "^0.33.0"
@@ -49,7 +62,8 @@
     "react": "^19"
   },
   "scripts": {
-    "build": "tsc -b && cp ../../README.md .",
-    "typecheck": "tsc -b --emitDeclarationOnly"
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -b --emitDeclarationOnly",
+    "release": "tsx ../../scripts/release-package.ts"
   }
 }

package/src/components/application.tsx

@@ -0,0 +1,43 @@
+import { applicationId as defaultApplicationId } from "virtual:gtkx-config";
+import type * as Gtk from "@gtkx/gi/gtk";
+import { quitApplication, runApplication } from "@gtkx/runtime";
+import { type ElementType, type ReactNode, type Ref, useCallback, useState } from "react";
+import { ApplicationContext } from "../hooks/use-application.js";
+import { useMergeRefs } from "../hooks/use-merge-refs.js";
+
+const POST_ACTIVATE_PROPS = new Set(["menubar"]);
+
+type ApplicationComponentProps = {
+    applicationId?: string | null | undefined;
+    children?: ReactNode | undefined;
+    ref?: Ref<Gtk.Application | null> | undefined;
+};
+
+export const createApplicationComponent = (
+    Component: ElementType,
+): ((props: ApplicationComponentProps) => ReactNode) => {
+    return ({ applicationId = defaultApplicationId, children, ref, ...rest }: ApplicationComponentProps): ReactNode => {
+        const [app, setApp] = useState<Gtk.Application | null>(null);
+
+        const handleMount = useCallback((instance: Gtk.Application) => {
+            runApplication(instance);
+            setApp(instance);
+
+            return () => {
+                quitApplication(instance);
+                setApp(null);
+            };
+        }, []);
+
+        const mergedRef = useMergeRefs<Gtk.Application>(ref, handleMount);
+        const appliedProps = app
+            ? rest
+            : Object.fromEntries(Object.entries(rest).filter(([key]) => !POST_ACTIVATE_PROPS.has(key)));
+
+        return (
+            <Component ref={mergedRef} applicationId={applicationId} {...appliedProps}>
+                {app ? <ApplicationContext.Provider value={app}>{children}</ApplicationContext.Provider> : null}
+            </Component>
+        );
+    };
+};

package/src/components/window.tsx

@@ -0,0 +1,36 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { type ElementType, type ReactNode, type Ref, useCallback, useLayoutEffect, useState } from "react";
+import { useMergeRefs } from "../hooks/use-merge-refs.js";
+import { ParentWindowContext } from "../hooks/use-parent-window.js";
+
+type WindowComponentProps = {
+    ref?: Ref<Gtk.Window | null> | undefined;
+};
+
+export const createWindowComponent = (Component: ElementType): ((props: WindowComponentProps) => ReactNode) => {
+    return ({ ref, ...rest }: WindowComponentProps): ReactNode => {
+        const [window, setWindow] = useState<Gtk.Window | null>(null);
+
+        const handleMount = useCallback((window: Gtk.Window) => {
+            setWindow(window);
+
+            return () => {
+                window.setDefaultWidget(null);
+                window.destroy();
+                setWindow(null);
+            };
+        }, []);
+
+        useLayoutEffect(() => {
+            window?.present();
+        }, [window]);
+
+        const mergedRef = useMergeRefs(ref, handleMount);
+
+        return (
+            <ParentWindowContext.Provider value={window}>
+                <Component ref={mergedRef} {...rest} />
+            </ParentWindowContext.Provider>
+        );
+    };
+};

package/src/hooks/use-application.ts

@@ -0,0 +1,17 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { type Context, createContext, use } from "react";
+
+export const ApplicationContext: Context<Gtk.Application | null> = createContext<Gtk.Application | null>(null);
+
+/**
+ * Returns the `Gtk.Application` provided by the nearest `Application` ancestor, throwing if used outside one.
+ */
+export const useApplication = (): Gtk.Application => {
+    const context = use(ApplicationContext);
+
+    if (!context) {
+        throw new Error("Expected ApplicationContext: useApplication must be called within Application");
+    }
+
+    return context;
+};

package/src/hooks/use-bind-setting.ts

@@ -0,0 +1,35 @@
+import * as Gio from "@gtkx/gi/gio";
+import type * as GObject from "@gtkx/gi/gobject";
+import { toKebabCase } from "@gtkx/utils";
+import type { ObjectProp } from "../utils/object-prop.js";
+import { useObjectAttachment } from "./use-object-attachment.js";
+import { type SchemaRef, useSettingsInstance } from "./use-setting.js";
+
+export function useBindSetting<K extends object, P extends keyof K & string>(
+    schema: SchemaRef<K>,
+    key: P,
+    object: ObjectProp<GObject.Object>,
+    property: string,
+    flags?: Gio.SettingsBindFlags,
+): void;
+export function useBindSetting(
+    schema: SchemaRef,
+    key: string,
+    object: ObjectProp<GObject.Object>,
+    property: string,
+    flags: Gio.SettingsBindFlags = Gio.SettingsBindFlags.DEFAULT,
+): void {
+    const settings = useSettingsInstance(schema);
+    const propertyName = toKebabCase(property);
+
+    useObjectAttachment<GObject.Object, GObject.Object>(object, {
+        attach: (obj) => {
+            settings.bind(key, obj, propertyName, flags);
+            return obj;
+        },
+        detach: (obj) => {
+            Gio.Settings.unbind(obj, propertyName);
+        },
+        isSame: (attachment, current) => attachment === current,
+    });
+}

package/src/hooks/use-merge-refs.ts

@@ -0,0 +1,53 @@
+import { type Ref, type RefCallback, useCallback, useLayoutEffect, useRef } from "react";
+
+type MergedRefEntry<T> = {
+    ref: Ref<T | null> | undefined;
+    cleanup: (() => void) | undefined;
+};
+
+const attachRef = <T>(ref: Ref<T | null> | undefined, value: T): (() => void) | undefined => {
+    if (typeof ref === "function") {
+        const cleanup = ref(value);
+        return typeof cleanup === "function" ? cleanup : () => ref(null);
+    }
+    if (ref) {
+        ref.current = value;
+        return () => {
+            ref.current = null;
+        };
+    }
+    return undefined;
+};
+
+export const useMergeRefs = <T>(...refs: Array<Ref<T | null> | undefined>): RefCallback<T> => {
+    const latestRefs = useRef(refs);
+    latestRefs.current = refs;
+    const attachedRef = useRef<{ value: T; entries: MergedRefEntry<T>[] } | null>(null);
+
+    useLayoutEffect(() => {
+        const attached = attachedRef.current;
+        if (attached === null) return;
+        const next = latestRefs.current;
+        for (let index = next.length; index < attached.entries.length; index += 1) {
+            attached.entries[index]?.cleanup?.();
+        }
+        attached.entries = next.map((ref, index) => {
+            const entry = attached.entries[index];
+            if (entry !== undefined && entry.ref === ref) return entry;
+            entry?.cleanup?.();
+            return { ref, cleanup: attachRef(ref, attached.value) };
+        });
+    });
+
+    return useCallback((value: T) => {
+        const entries = latestRefs.current.map((ref) => ({ ref, cleanup: attachRef(ref, value) }));
+        attachedRef.current = { value, entries };
+        return () => {
+            const attached = attachedRef.current;
+            attachedRef.current = null;
+            if (attached) {
+                for (const entry of attached.entries) entry.cleanup?.();
+            }
+        };
+    }, []);
+};

package/src/hooks/use-object-attachment.ts

@@ -0,0 +1,35 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import { useLayoutEffect, useRef } from "react";
+import { type ObjectProp, resolveObjectProp } from "../utils/object-prop.js";
+
+type ObjectAttachmentOps<T extends GObject.Object, A> = {
+    attach(object: T): A;
+    detach(attachment: A): void;
+    isSame(attachment: A, object: T): boolean;
+};
+
+export const useObjectAttachment = <T extends GObject.Object, A>(
+    object: ObjectProp<T>,
+    ops: ObjectAttachmentOps<T, A>,
+): void => {
+    const attachmentRef = useRef<A | null>(null);
+
+    const drop = (): void => {
+        const attachment = attachmentRef.current;
+        if (attachment !== null) {
+            ops.detach(attachment);
+            attachmentRef.current = null;
+        }
+    };
+
+    useLayoutEffect(() => {
+        const resolved = resolveObjectProp(object);
+        const attachment = attachmentRef.current;
+        if (attachment !== null && resolved !== null && ops.isSame(attachment, resolved)) return;
+        drop();
+        if (resolved === null) return;
+        attachmentRef.current = ops.attach(resolved);
+    });
+
+    useLayoutEffect(() => () => drop(), []);
+};

package/src/hooks/use-object-value.ts

@@ -0,0 +1,50 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import type { SignalHandler } from "@gtkx/runtime";
+import { useCallback, useRef, useSyncExternalStore } from "react";
+import { type ObjectProp, resolveObjectProp } from "../utils/object-prop.js";
+
+type ObjectValueCache<T extends GObject.Object, V> = {
+    object: T | null;
+    signal: string;
+    value: V;
+};
+
+export function useObjectValue<T extends GObject.Object, V>(
+    object: ObjectProp<T>,
+    signal: string,
+    read: (object: T | null) => V,
+): V {
+    const resolved = resolveObjectProp(object);
+    const readRef = useRef(read);
+    readRef.current = read;
+    const cacheRef = useRef<ObjectValueCache<T, V> | null>(null);
+
+    const readNow = useCallback((): ObjectValueCache<T, V> => {
+        const cache = { object: resolved, signal, value: readRef.current(resolved) };
+        cacheRef.current = cache;
+        return cache;
+    }, [resolved, signal]);
+
+    const getSnapshot = useCallback((): V => {
+        const cache = cacheRef.current;
+        if (cache !== null && cache.object === resolved && cache.signal === signal) {
+            return cache.value;
+        }
+        return readNow().value;
+    }, [resolved, signal, readNow]);
+
+    const subscribe = useCallback(
+        (onStoreChange: () => void): (() => void) => {
+            if (resolved === null) return () => {};
+            const handler: SignalHandler = () => {
+                readNow();
+                onStoreChange();
+            };
+            resolved.on(signal, handler);
+            return () => resolved.off(signal, handler);
+        },
+        [resolved, signal, readNow],
+    );
+
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/src/hooks/use-parent-window.ts

@@ -0,0 +1,9 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { type Context, createContext, use } from "react";
+
+export const ParentWindowContext: Context<Gtk.Window | null> = createContext<Gtk.Window | null>(null);
+
+/**
+ * Returns the `Gtk.Window` provided by the nearest window ancestor, or `null` when there is none.
+ */
+export const useParentWindow = (): Gtk.Window | null => use(ParentWindowContext);

package/src/hooks/use-property.ts

@@ -0,0 +1,22 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import { propToNotifySignal } from "../utils/notify-name.js";
+import type { ObjectProp } from "../utils/object-prop.js";
+import { useObjectValue } from "./use-object-value.js";
+
+type PropertiesOf<T extends GObject.Object> = NonNullable<T["__properties__"]>;
+
+export type PropertyNameOf<T extends GObject.Object> = keyof PropertiesOf<T> & keyof T & string;
+
+/**
+ * Subscribes to a GObject property and returns its current value, re-rendering when the property changes.
+ *
+ * @param object The GObject (or ref to one) whose property to observe.
+ * @param propertyName The camelCase name of a readable property on the object.
+ * @returns The current property value, or `undefined` when the object is not resolved.
+ */
+export function useProperty<T extends GObject.Object, K extends PropertyNameOf<T>>(
+    object: ObjectProp<T>,
+    propertyName: K,
+): T[K] | undefined {
+    return useObjectValue(object, propToNotifySignal(propertyName), (obj) => (obj ? obj[propertyName] : undefined));
+}

package/src/hooks/use-setting.ts

@@ -0,0 +1,47 @@
+import * as Gio from "@gtkx/gi/gio";
+import { useCallback, useMemo } from "react";
+import { resolveAccessor } from "../utils/settings-accessor.js";
+import { useObjectValue } from "./use-object-value.js";
+
+/**
+ * A typed reference to a GSettings schema: its id, path, and the mapping of typed keys to their setting names.
+ */
+export type SchemaRef<K extends object = Record<string, unknown>> = {
+    id: string;
+    /** The schema's object path, or `null` to use the schema's default path. */
+    path: string | null;
+    /** Maps each typed key of `K` to its corresponding GSettings key name. */
+    keys: { [P in keyof K]: string };
+    /** Phantom field carrying the value type `K`; never populated at runtime. */
+    __keys__?: K;
+};
+
+export const useSettingsInstance = ({ id, path }: Pick<SchemaRef, "id" | "path">): Gio.Settings =>
+    useMemo(() => (path === null ? Gio.Settings.new(id) : new Gio.Settings({ schemaId: id, path })), [id, path]);
+
+/**
+ * Reads and writes a single key of a GSettings schema, re-rendering when the stored value changes.
+ *
+ * @param schema The schema reference identifying the settings backend.
+ * @param key The key within the schema to read and write.
+ * @returns A tuple of the current value and a setter that persists a new value.
+ */
+export function useSetting<K extends object, P extends keyof K & string>(
+    schema: SchemaRef<K>,
+    key: P,
+): [K[P], (value: K[P]) => void];
+export function useSetting(schema: SchemaRef, key: string): [unknown, (value: unknown) => void] {
+    const accessor = resolveAccessor(schema.keys[key], key, schema.id);
+    const settings = useSettingsInstance(schema);
+
+    const value = useObjectValue(settings, `changed::${key}`, () => accessor.read(settings, key));
+
+    const set = useCallback(
+        (newValue: unknown) => {
+            accessor.write(settings, key, newValue);
+        },
+        [accessor, settings, key],
+    );
+
+    return [value, set];
+}

package/src/hooks/use-signal.ts

@@ -0,0 +1,71 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import type { SignalHandler } from "@gtkx/runtime";
+import { useRef } from "react";
+import type { ObjectProp } from "../utils/object-prop.js";
+import { useObjectAttachment } from "./use-object-attachment.js";
+
+type AnySignalHandler = (...args: unknown[]) => unknown;
+
+type SignalsOf<T extends GObject.Object> = NonNullable<T["__signals__"]>;
+
+export type SignalNameOf<T extends GObject.Object> =
+    | (keyof SignalsOf<T> & string)
+    | `${keyof SignalsOf<T> & string}::${string}`;
+
+export type SignalHandlerFor<T extends GObject.Object, S extends string> = S extends keyof SignalsOf<T>
+    ? SignalsOf<T>[S]
+    : S extends `${infer TBase}::${string}`
+      ? TBase extends keyof SignalsOf<T>
+          ? SignalsOf<T>[TBase]
+          : AnySignalHandler
+      : AnySignalHandler;
+
+type UseSignalOptions = {
+    after?: boolean;
+    immediate?: boolean;
+};
+
+type SignalSubscription = {
+    obj: GObject.Object;
+    signal: string;
+    after: boolean;
+    listener: SignalHandler;
+};
+
+/**
+ * Connects a handler to a GObject signal for the lifetime of the component, reconnecting when the object changes.
+ *
+ * @param object The GObject (or ref to one) to connect to.
+ * @param signal The signal name, optionally with a detail suffix.
+ * @param handler The callback invoked when the signal is emitted.
+ * @param options Connection options such as running after the default handler or invoking immediately.
+ */
+export function useSignal<T extends GObject.Object, S extends SignalNameOf<T>>(
+    object: ObjectProp<T>,
+    signal: S,
+    handler: SignalHandlerFor<T, S>,
+    options?: UseSignalOptions,
+): void;
+export function useSignal(
+    object: ObjectProp<GObject.Object>,
+    signal: string,
+    handler: AnySignalHandler,
+    options?: UseSignalOptions,
+): void {
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    const after = options?.after ?? false;
+    const immediate = options?.immediate ?? false;
+
+    useObjectAttachment<GObject.Object, SignalSubscription>(object, {
+        attach: (obj) => {
+            const listener: SignalHandler = (...args) => handlerRef.current(...args);
+            obj.on(signal, listener, after);
+            if (immediate) handlerRef.current();
+            return { obj, signal, after, listener };
+        },
+        detach: (subscription) => subscription.obj.off(subscription.signal, subscription.listener),
+        isSame: (subscription, obj) =>
+            subscription.obj === obj && subscription.signal === signal && subscription.after === after,
+    });
+}

package/src/index.ts

@@ -1,12 +1,15 @@
-export { GtkxError } from "./errors.js";
-export * from "./jsx.js";
-export { createPortal } from "./portal.js";
-export { reconciler } from "./reconciler.js";
-export {
-    ApplicationContext,
-    quit,
-    render,
-    setHotReloading,
-    update,
-    useApplication,
-} from "./render.js";
+import "./utils/wrapper-node-jsx.js";
+
+export type { ElementProp } from "@gtkx/config";
+export { useApplication } from "./hooks/use-application.js";
+export { useBindSetting } from "./hooks/use-bind-setting.js";
+export { useParentWindow } from "./hooks/use-parent-window.js";
+export { useProperty } from "./hooks/use-property.js";
+export { type SchemaRef, useSetting } from "./hooks/use-setting.js";
+export { useSignal } from "./hooks/use-signal.js";
+export type { AccessibleProps } from "./reconciler/accessible.js";
+export { createPortal } from "./reconciler/portal.js";
+export { createRoot, quit, type Root } from "./reconciler/render.js";
+export { type RootElement, rootElement } from "./reconciler/root-element.js";
+export type { ObjectProp } from "./utils/object-prop.js";
+export type { TextAnchorProps, TextPaintableProps } from "./utils/wrapper-node-jsx.js";

package/src/internal.ts

@@ -0,0 +1,24 @@
+export { createApplicationComponent } from "./components/application.js";
+export { createWindowComponent } from "./components/window.js";
+export { ApplicationContext } from "./hooks/use-application.js";
+export { useMergeRefs } from "./hooks/use-merge-refs.js";
+export { useObjectAttachment } from "./hooks/use-object-attachment.js";
+export { useObjectValue } from "./hooks/use-object-value.js";
+export { setReconcilerErrorHandler } from "./reconciler/reconciler-error-handler.js";
+export { createReconcilerRoot, type ReconcilerRoot } from "./reconciler/reconciler-root.js";
+export { isRootElement } from "./reconciler/root-element.js";
+export {
+    BUFFER_TEXT_KIND,
+    CONTAINER_PROP_KIND,
+    isWrapperKind,
+    LABEL_TEXT_KIND,
+    LAZY_ELEMENT_KIND,
+    OBJECT_PROP_KIND,
+    TEXT_ANCHOR_KIND,
+    TEXT_PAINTABLE_KIND,
+    WRAPPER_NODE_ELEMENT,
+    type WrapperKind,
+} from "./reconciler/wrapper-protocol.js";
+export { getAccessibleMetadata } from "./utils/accessible-metadata.js";
+export { createElementComponent, createLazyElementComponent } from "./utils/create-element-component.js";
+export { type ObjectProp, resolveObjectProp } from "./utils/object-prop.js";

package/src/libraries/adw/dialog.tsx

@@ -0,0 +1,34 @@
+import type * as Adw from "@gtkx/gi/adw";
+import { type ElementType, type ReactNode, type Ref, useCallback, useLayoutEffect, useState } from "react";
+import { useMergeRefs } from "../../hooks/use-merge-refs.js";
+import { useParentWindow } from "../../hooks/use-parent-window.js";
+import { createPortal } from "../../reconciler/portal.js";
+import { rootElement } from "../../reconciler/root-element.js";
+
+type DialogComponentProps = {
+    ref?: Ref<Adw.Dialog | null> | undefined;
+};
+
+export const createDialogComponent = (Component: ElementType): ((props: DialogComponentProps) => ReactNode) => {
+    return ({ ref, ...rest }: DialogComponentProps): ReactNode => {
+        const parent = useParentWindow();
+        const [dialog, setDialog] = useState<Adw.Dialog | null>(null);
+
+        const handleMount = useCallback((instance: Adw.Dialog) => {
+            setDialog(instance);
+
+            return () => {
+                instance.forceClose();
+                setDialog(null);
+            };
+        }, []);
+
+        useLayoutEffect(() => {
+            dialog?.present(parent);
+        }, [dialog, parent]);
+
+        const mergedRef = useMergeRefs<Adw.Dialog>(ref, handleMount);
+
+        return createPortal(<Component ref={mergedRef} {...rest} />, rootElement);
+    };
+};

package/src/libraries/adw/index.ts

@@ -0,0 +1 @@
+export { createDialogComponent } from "./dialog.js";