@gtkx/react 1.0.0-rc.1 → 1.0.0-rc.2

package/src/reconciler/registry.ts

@@ -0,0 +1,161 @@
+import type * as GObject from "@gtkx/gi/gobject";
+
+/** The props of a host element or node, as React passes them through the reconciler. */
+type Props = Record<string, unknown>;
+
+/** Per-child values a slot hook receives while placing or moving one child. */
+type PlaceInfo = {
+    slot: string;
+    index: number;
+    sibling: GObject.Object | null;
+    adopted: GObject.Object | null;
+    props: Props;
+    context: unknown;
+};
+
+/** Per-child values a slot hook receives while removing one child. */
+type DetachInfo = {
+    slot: string;
+    adopted: GObject.Object | null;
+    props: Props;
+    context: unknown;
+};
+
+/**
+ * Customizes how one element type places children and applies props. Every hook receives the
+ * GObject instance and a private per-node `context` built once by `createContext`. A slot hook
+ * claims a child by returning a non-`undefined` value; that value, or `resolve`, is the object
+ * the container adopts for the child. `update` returns the prop names it consumed so those props
+ * are not also set as plain GObject properties. `create` builds the GObject for types whose
+ * constructor does more than set properties, and is consulted for its own type only, never
+ * inherited by subtypes.
+ */
+type ElementBehavior<T extends GObject.Object = GObject.Object> = {
+    create?: (props: Props) => GObject.Object;
+    createContext?: (object: T) => unknown;
+    attach?: (object: T, child: GObject.Object, info: PlaceInfo) => unknown;
+    reorder?: (object: T, child: GObject.Object, info: PlaceInfo) => unknown;
+    detach?: (object: T, child: GObject.Object, info: DetachInfo) => void;
+    resolve?: (object: T, child: GObject.Object) => GObject.Object | null;
+    update?: (object: T, prev: Props, next: Props, context: unknown) => Iterable<string> | undefined;
+    flush?: (object: T, context: unknown) => void;
+    mount?: (object: T, context: unknown) => void;
+    unmount?: (object: T, context: unknown) => void;
+    deferred?: string[];
+};
+
+/** A named export in a module, referenced as plain data (the module is never imported at runtime). */
+type ModuleExport = { module: string; export: string };
+
+/**
+ * Per-element configuration keyed by GLib type name: whether the element is lazy (its GObject is
+ * created by its parent container, as pages and layout children are), the custom behaviors bound to
+ * its type, an optional component that wraps the generated element, and the base props interface its
+ * generated props extend. `component` and `props` are inert at runtime; they are read only by codegen.
+ */
+type ElementConfig<T extends GObject.Object = GObject.Object> = {
+    lazy?: boolean;
+    behaviors?: ElementBehavior<T>[];
+    component?: ModuleExport;
+    props?: ModuleExport;
+};
+
+/**
+ * Every registered element config, keyed by GLib type name. Adwaita entries appear once `@gtkx/react/adw`
+ * is loaded.
+ */
+const ELEMENTS: Record<string, ElementConfig> = {};
+
+/** Props a behavior applies after construction; the constructor is never given them. */
+const deferredProps = (behavior: ElementBehavior): string[] => behavior.deferred ?? [];
+
+const mergeBehaviors = (base: ElementConfig, added: ElementBehavior[], isPrepended: boolean): ElementBehavior[] => {
+    const baseBehaviors = base.behaviors ?? [];
+
+    return isPrepended ? [...added, ...baseBehaviors] : [...baseBehaviors, ...added];
+};
+
+const mergeConfigEntry = (base: ElementConfig, added: ElementConfig<never>, isPrepended = false): ElementConfig => {
+    const entry: ElementConfig = { ...base };
+
+    if (added.behaviors !== undefined) {
+        entry.behaviors = mergeBehaviors(entry, added.behaviors as ElementBehavior[], isPrepended);
+    }
+
+    if (added.lazy === true) {
+        entry.lazy = true;
+    }
+
+    if (added.component !== undefined) {
+        entry.component = added.component;
+    }
+
+    if (added.props !== undefined) {
+        entry.props = added.props;
+    }
+
+    return entry;
+};
+
+/**
+ * Merges maps of {@link ElementConfig} keyed by GLib type name into one, concatenating each type's
+ * behaviors in the order the maps are given (an earlier map's behaviors come first) and taking the last
+ * lazy flag, component, and props seen. Use it to combine an app's element config with its behaviors.
+ */
+const mergeElementConfigs = (...maps: Record<string, ElementConfig<never>>[]): Record<string, ElementConfig> => {
+    const merged: Record<string, ElementConfig> = {};
+
+    for (const map of maps) {
+        for (const [type, config] of Object.entries(map)) {
+            merged[type] = mergeConfigEntry(merged[type] ?? {}, config);
+        }
+    }
+
+    return merged;
+};
+
+/**
+ * Registers a map of {@link ElementConfig} keyed by GLib type name, merging each entry into the
+ * registry. Behaviors are appended by default (the framework's built-ins register this way); pass
+ * `{ prepend: true }` for an app's own configuration so its behaviors are consulted before the
+ * built-ins for the same slot, letting it override them regardless of registration order.
+ */
+const registerElements = (
+    map: Record<string, ElementConfig<never>>,
+    options: { prepend?: boolean } = {},
+): void => {
+    for (const [type, config] of Object.entries(map)) {
+        ELEMENTS[type] = mergeConfigEntry(ELEMENTS[type] ?? {}, config, options.prepend === true);
+    }
+};
+
+/**
+ * Identity helper that types the module named by the `elements` entry of `gtkx.config.ts`, enabling
+ * editor autocompletion and type checking. Key each entry by GLib type name and annotate each hook's
+ * object parameter with the concrete GObject class the behavior applies to.
+ */
+const defineElements = (elements: Record<string, ElementConfig<never>>): Record<string, ElementConfig<never>> =>
+    elements;
+
+/** Spreads one config across many GLib type names. */
+const forTypes = (types: string[], config: ElementConfig<never>): Record<string, ElementConfig<never>> =>
+    Object.fromEntries(types.map((type) => [type, config]));
+
+/** References a base props interface exported from `@gtkx/react/internal`. */
+const internal = (name: string): ModuleExport => ({ module: "@gtkx/react/internal", export: name });
+
+export {
+    ELEMENTS,
+    deferredProps,
+    mergeElementConfigs,
+    registerElements,
+    defineElements,
+    forTypes,
+    internal,
+    type Props,
+    type PlaceInfo,
+    type DetachInfo,
+    type ElementBehavior,
+    type ModuleExport,
+    type ElementConfig,
+};

package/src/reconciler/root-element.ts

@@ -1,14 +1,12 @@
-const ROOT_ELEMENT: unique symbol = Symbol.for("gtkx.rootElement");
+/** The type of the shared {@link rootElement} marker used as a default top-level container. */
+type RootElement = { [ROOT_ELEMENT_BRAND]: true };
 
-/**
- * The type of the singleton marker used as the top-level render container.
- */
-export type RootElement = { [ROOT_ELEMENT]: true };
+const ROOT_ELEMENT_BRAND: unique symbol = Symbol.for("gtkx:root-element");
+/** A shared marker value used as the default top-level container for rendering and portals. */
+const rootElement: RootElement = { [ROOT_ELEMENT_BRAND]: true };
 
-/**
- * The shared root element used as the default container for `createRoot`.
- */
-export const rootElement: RootElement = { [ROOT_ELEMENT]: true };
+/** Reports whether an arbitrary value is a {@link rootElement} marker. */
+const isRootElement = (value: unknown): value is RootElement =>
+    typeof value === "object" && value !== null && Object.hasOwn(value, ROOT_ELEMENT_BRAND);
 
-export const isRootElement = (value: unknown): value is RootElement =>
-    typeof value === "object" && value !== null && ROOT_ELEMENT in value;
+export { rootElement, isRootElement, type RootElement };

package/src/reconciler/root.ts

@@ -0,0 +1,175 @@
+import type { ErrorInfo, ReactNode } from "react";
+import * as Gdk from "@gtkx/gi/gdk";
+import { createLogger, type Logger } from "@gtkx/utils";
+import { ConcurrentRoot } from "react-reconciler/constants.js";
+import { type Container, reconciler } from "./host-config.js";
+import { rootElement } from "./root-element.js";
+import { endSuppressionNow } from "./signals.js";
+
+type OpaqueRoot = { [opaqueRoot]: true };
+
+type RootErrorCallbacks = {
+    onUncaughtError?: (error: unknown, info: ErrorInfo) => void;
+    onCaughtError?: (error: unknown, info: ErrorInfo) => void;
+    onRecoverableError?: (error: unknown, info: ErrorInfo) => void;
+};
+
+type ReconcilerRootOptions = RootErrorCallbacks & { containerInfo: Container };
+
+/** A root that mounts an element tree into an explicit container and reports render errors. */
+type ReconcilerRoot = {
+    update: (element: ReactNode) => void;
+    unmount: (teardown: (root: ReconcilerRoot) => Promise<void>) => Promise<void>;
+};
+
+/** The object {@link createRoot} returns: it renders an element tree into a container and can tear it down. */
+type Root = {
+    render: (element: ReactNode) => void;
+    unmount: () => void;
+};
+
+type ErrorHandler = (error: unknown) => void;
+type ErrorHandlerSlot = { get: () => ErrorHandler | null; set: (handler: ErrorHandler) => ErrorHandler | null };
+
+declare const opaqueRoot: unique symbol;
+const log: Logger = createLogger("react");
+const activeRoots: Set<OpaqueRoot> = new Set();
+const errorHandlerSlot = createErrorHandlerSlot();
+
+function createErrorHandlerSlot(): ErrorHandlerSlot {
+    let current: ErrorHandler | null = null;
+
+    return {
+        get: () => current,
+        set: (handler) => {
+            const previous = current;
+            current = handler;
+
+            return previous;
+        },
+    };
+}
+
+/**
+ * Installs a process-wide handler for errors thrown while rendering or applying an update.
+ *
+ * @param handler The handler to install.
+ * @returns The previously installed handler, or null.
+ */
+const setReconcilerErrorHandler = (handler: ErrorHandler): ErrorHandler | null => errorHandlerSlot.set(handler);
+
+const rethrowUncaughtRenderError = (error: unknown): never => {
+    endSuppressionNow();
+    throw error;
+};
+
+const logCaughtRenderError = (error: unknown): void => {
+    endSuppressionNow();
+    log.error("caught render error", error);
+};
+
+const openContainer = (containerInfo: Container, callbacks: RootErrorCallbacks): OpaqueRoot => {
+    const container = reconciler.createContainer(
+        containerInfo,
+        ConcurrentRoot,
+        null,
+        false,
+        null,
+        "",
+        (error, info) => {
+            errorHandlerSlot.get()?.(error);
+            callbacks.onUncaughtError?.(error, info);
+        },
+        (error, info) => {
+            errorHandlerSlot.get()?.(error);
+            callbacks.onCaughtError?.(error, info);
+        },
+        (error, info) => {
+            callbacks.onRecoverableError?.(error, info);
+        },
+        (): void => undefined,
+    ) as OpaqueRoot;
+
+    activeRoots.add(container);
+
+    return container;
+};
+
+const unmountContainer = (container: OpaqueRoot): void => {
+    reconciler.updateContainer(null, container, null, null);
+    activeRoots.delete(container);
+};
+
+/**
+ * Creates a root that mounts an element tree into a container, routing render errors to the supplied callbacks.
+ *
+ * @param options The container to render into and the error callbacks to route failures to.
+ * @returns A {@link ReconcilerRoot}.
+ */
+const createReconcilerRoot = (options: ReconcilerRootOptions): ReconcilerRoot => {
+    const container = openContainer(options.containerInfo, options);
+
+    const root: ReconcilerRoot = {
+        update: (element) => {
+            reconciler.updateContainer(element, container, null, null);
+        },
+        unmount: async (teardown) => {
+            await teardown(root);
+            activeRoots.delete(container);
+        },
+    };
+
+    return root;
+};
+
+/**
+ * Creates a render root for a GTKX application.
+ *
+ * @param container The top-level container to render into; defaults to the shared {@link rootElement}.
+ * @returns A {@link Root} exposing render and unmount.
+ */
+const createRoot = (container: Container = rootElement): Root => {
+    const opaque = openContainer(container, {
+        onUncaughtError: rethrowUncaughtRenderError,
+        onCaughtError: logCaughtRenderError,
+    });
+
+    return {
+        render: (element) => {
+            reconciler.updateContainer(element, opaque, null, null);
+        },
+        unmount: () => {
+            unmountContainer(opaque);
+        },
+    };
+};
+
+/** Unmounts every active render root and stops the originating signal from propagating further. */
+const quit = (): typeof Gdk.EVENT_STOP => {
+    for (const container of activeRoots) {
+        unmountContainer(container);
+    }
+
+    return Gdk.EVENT_STOP;
+};
+
+/**
+ * Renders children into a container other than the surrounding tree.
+ *
+ * @param children The element tree to render.
+ * @param container The GObject, application, or {@link rootElement} to render into.
+ * @param key An optional stable key.
+ * @returns A React portal.
+ */
+const createPortal = (children: ReactNode, container: Container, key?: string): ReactNode =>
+    Object.assign(reconciler.createPortal(children, container, null, key ?? null), { type: "gtkx-portal", props: {} });
+
+export {
+    setReconcilerErrorHandler,
+    createReconcilerRoot,
+    createRoot,
+    quit,
+    createPortal,
+    type ReconcilerRoot,
+    type Root,
+};

package/src/reconciler/signals.ts

@@ -0,0 +1,113 @@
+import { getSignalBaseName, type SignalHandler } from "@gtkx/runtime";
+import { camelCase } from "@gtkx/utils";
+import type { HandlerRecord, SignalTarget } from "./node.js";
+import { type TypeInfo, typeInfoFor } from "./metadata.js";
+
+type SuppressionCounter = {
+    beginSuppression: () => void;
+    endSuppression: () => void;
+    endSuppressionNow: () => void;
+    isSuppressed: () => boolean;
+};
+
+const NOTIFY_DETAIL_PREFIX = "notify::";
+const suppressionCounter: SuppressionCounter = createSuppressionCounter();
+const beginSuppression: () => void = suppressionCounter.beginSuppression;
+const endSuppression: () => void = suppressionCounter.endSuppression;
+const endSuppressionNow: () => void = suppressionCounter.endSuppressionNow;
+const isSuppressed: () => boolean = suppressionCounter.isSuppressed;
+
+function createSuppressionCounter(): SuppressionCounter {
+    let depth = 0;
+
+    const release = (): void => {
+        if (depth > 0) {
+            depth -= 1;
+        }
+    };
+
+    return {
+        beginSuppression: () => {
+            depth += 1;
+        },
+        endSuppression: () => {
+            queueMicrotask(release);
+        },
+        endSuppressionNow: release,
+        isSuppressed: () => depth > 0,
+    };
+}
+
+const getNotifyProperty = (signal: string): string | null =>
+    signal.startsWith(NOTIFY_DETAIL_PREFIX) ? camelCase(signal.slice(NOTIFY_DETAIL_PREFIX.length)) : null;
+
+const isBlockableSignal = (info: TypeInfo, signal: string): boolean =>
+    info.userEventSignals.has(getSignalBaseName(signal));
+
+const invokeHandler = (
+    target: SignalTarget,
+    record: HandlerRecord,
+    notifyProperty: string | null,
+    args: unknown[],
+): unknown =>
+    notifyProperty === null
+        ? record.handler(...args, target.object)
+        : record.handler(Reflect.get(target.object, notifyProperty), target.object);
+
+const wrapHandler = (target: SignalTarget, record: HandlerRecord, notifyProperty: string | null): SignalHandler =>
+    (...args: unknown[]): unknown => {
+        if (record.blockable && isSuppressed()) {
+            return undefined;
+        }
+
+        return target.dispatch(() => invokeHandler(target, record, notifyProperty, args));
+    };
+
+const connectHandler = (target: SignalTarget, prop: string, signal: string, handler: SignalHandler): void => {
+    const existing = target.handlers.get(prop);
+
+    if (existing?.signal === signal) {
+        existing.handler = handler;
+
+        return;
+    }
+
+    if (existing !== undefined) {
+        target.object.off(existing.signal, existing.wrapped);
+    }
+
+    const isBlockable = isBlockableSignal(typeInfoFor(target.typeName), signal);
+    const notifyProperty = getNotifyProperty(signal);
+    const record: HandlerRecord = { signal, handler, wrapped: (): undefined => undefined, blockable: isBlockable };
+    record.wrapped = wrapHandler(target, record, notifyProperty);
+    target.object.on(signal, record.wrapped);
+    target.handlers.set(prop, record);
+};
+
+const disconnectHandler = (target: SignalTarget, prop: string): void => {
+    const record = target.handlers.get(prop);
+
+    if (record === undefined) {
+        return;
+    }
+
+    target.object.off(record.signal, record.wrapped);
+    target.handlers.delete(prop);
+};
+
+const disconnectAllHandlers = (target: SignalTarget): void => {
+    for (const record of target.handlers.values()) {
+        target.object.off(record.signal, record.wrapped);
+    }
+
+    target.handlers.clear();
+};
+
+export {
+    beginSuppression,
+    endSuppression,
+    endSuppressionNow,
+    connectHandler,
+    disconnectHandler,
+    disconnectAllHandlers,
+};