@gtkx/react 0.18.0 → 0.18.2

package/src/nodes/widget.ts

@@ -0,0 +1,398 @@
+import { getNativeObject, type NativeObject } from "@gtkx/ffi";
+import type * as GObject from "@gtkx/ffi/gobject";
+import {
+    ObjectClass,
+    ParamSpecString,
+    Type,
+    TypeInstance,
+    typeClassRef,
+    typeFromName,
+    typeFundamental,
+    typeNameFromInstance,
+} from "@gtkx/ffi/gobject";
+import * as Gtk from "@gtkx/ffi/gtk";
+import { CONSTRUCTOR_PROPS } from "../generated/internal.js";
+import { resolvePropMeta, resolveSignal } from "../metadata.js";
+import { Node } from "../node.js";
+import type { Container, Props } from "../types.js";
+import {
+    type InsertableWidget,
+    isAddable,
+    isAppendable,
+    isEditable,
+    isInsertable,
+    isRemovable,
+    isReorderable,
+    isSingleChild,
+    type ReorderableWidget,
+} from "./internal/predicates.js";
+import { filterProps } from "./internal/props.js";
+import type { SignalHandler } from "./internal/signal-store.js";
+import { attachChild, detachChild } from "./internal/widget.js";
+
+const EXCLUDED_PROPS = ["children", "widthRequest", "heightRequest", "grabFocus"];
+
+function findProperty(obj: NativeObject, key: string): GObject.ParamSpec | null {
+    const propertyName = key.replace(/([A-Z])/g, "-$1").toLowerCase();
+    const typeInstance = getNativeObject(obj.handle, TypeInstance);
+    const typeName = typeNameFromInstance(typeInstance);
+    const gtype = typeFromName(typeName);
+    const typeClass = typeClassRef(gtype);
+    const objectClass = getNativeObject(typeClass.handle, ObjectClass);
+    return objectClass.findProperty(propertyName) ?? null;
+}
+
+export class WidgetNode<
+    T extends Gtk.Widget = Gtk.Widget,
+    P extends Props = Props,
+    // biome-ignore lint/suspicious/noExplicitAny: Self-referential type bounds require any
+    TChild extends Node = any,
+    TParent extends Node = Node,
+> extends Node<T, P, TParent, TChild> {
+    public static override createContainer(
+        props: Props,
+        containerClass: typeof Gtk.Widget,
+        _rootContainer?: Container,
+    ): Container | null {
+        const WidgetClass = containerClass;
+        const typeName = WidgetClass.glibTypeName;
+        const args = (CONSTRUCTOR_PROPS[typeName] ?? []).map((name) => props[name]);
+
+        return new WidgetClass(...(args as ConstructorParameters<typeof Gtk.Widget>));
+    }
+
+    public override isValidChild(_child: Node): boolean {
+        return true;
+    }
+
+    protected shouldAttachToParent(): boolean {
+        return true;
+    }
+
+    public override appendChild(child: TChild): void {
+        super.appendChild(child);
+
+        if (child instanceof WidgetNode && child.shouldAttachToParent()) {
+            this.appendWidgetChild(child);
+        }
+    }
+
+    public override removeChild(child: TChild): void {
+        if (child instanceof WidgetNode && child.shouldAttachToParent()) {
+            if (this.isChildAutowrapped(child)) {
+                const wrapper = child.container.getParent();
+                if (wrapper && isSingleChild(wrapper)) {
+                    wrapper.setChild(null);
+                    if (isRemovable(this.container)) {
+                        this.container.remove(wrapper);
+                    }
+                }
+            } else {
+                detachChild(child.container, this.container);
+            }
+        }
+
+        super.removeChild(child);
+    }
+
+    public override insertBefore(child: TChild, before: TChild): void {
+        super.insertBefore(child, before);
+
+        if (!(child instanceof WidgetNode) || !child.shouldAttachToParent()) return;
+
+        if (!(before instanceof WidgetNode)) {
+            this.appendWidgetChild(child);
+            return;
+        }
+
+        if (this.container instanceof Gtk.ListBox || this.container instanceof Gtk.FlowBox) {
+            this.insertBeforeAutowrapping(child, before);
+        } else if (isReorderable(this.container)) {
+            this.insertBeforeReorderable(this.container, child, before);
+        } else if (isInsertable(this.container)) {
+            this.insertBeforeInsertable(this.container, child, before);
+        } else {
+            this.reinsertAllChildren();
+        }
+    }
+
+    public override commitUpdate(oldProps: P | null, newProps: P): void {
+        super.commitUpdate(oldProps, newProps);
+
+        if (!this.container) {
+            throw new Error(`Container is undefined for '${this.typeName}'`);
+        }
+
+        this.signalStore.blockAll();
+        try {
+            this.updateSizeRequest(oldProps, newProps);
+            this.updateGrabFocus(oldProps, newProps);
+
+            const propNames = new Set([
+                ...Object.keys(filterProps(oldProps ?? {}, EXCLUDED_PROPS)),
+                ...Object.keys(filterProps(newProps ?? {}, EXCLUDED_PROPS)),
+            ]);
+
+            const pendingSignals: Array<{ name: string; newValue: unknown }> = [];
+            const pendingProperties: Array<{ name: string; oldValue: unknown; newValue: unknown }> = [];
+
+            for (const name of propNames) {
+                const oldValue = oldProps?.[name];
+                const newValue = newProps[name];
+
+                if (oldValue === newValue) continue;
+
+                const signalName = resolveSignal(this.container, name);
+
+                if (signalName) {
+                    pendingSignals.push({ name, newValue });
+                } else if (newValue !== undefined) {
+                    pendingProperties.push({ name, oldValue, newValue });
+                } else if (oldValue !== undefined) {
+                    const defaultValue = this.getPropertyDefaultValue(name);
+                    if (defaultValue !== undefined) {
+                        pendingProperties.push({ name, oldValue, newValue: defaultValue });
+                    }
+                }
+            }
+
+            for (const { name, newValue } of pendingSignals) {
+                const signalName = resolveSignal(this.container, name);
+                if (!signalName) continue;
+                const handler = typeof newValue === "function" ? (newValue as SignalHandler) : undefined;
+                this.signalStore.set(this, this.container, signalName, handler);
+            }
+
+            for (const { name, oldValue, newValue } of pendingProperties) {
+                if (name === "text" && oldValue !== undefined && isEditable(this.container)) {
+                    if (oldValue !== this.container.getText()) {
+                        continue;
+                    }
+                }
+
+                this.setProperty(name, newValue);
+            }
+        } finally {
+            this.signalStore.unblockAll();
+        }
+    }
+
+    private appendWidgetChild(child: WidgetNode): void {
+        if (isAppendable(this.container) || isAddable(this.container)) {
+            if (this.isChildAutowrapped(child)) {
+                this.detachAutowrappedChild(child);
+            } else {
+                detachChildFromParent(child);
+            }
+        }
+        attachChild(child.container, this.container);
+    }
+
+    private isChildAutowrapped(child: WidgetNode): boolean {
+        return (
+            (this.container instanceof Gtk.ListBox || this.container instanceof Gtk.FlowBox) &&
+            !(child.container instanceof Gtk.ListBoxRow || child.container instanceof Gtk.FlowBoxChild)
+        );
+    }
+
+    private detachAutowrappedChild(child: WidgetNode): void {
+        const wrapper = child.container.getParent();
+        if (wrapper && isSingleChild(wrapper)) {
+            wrapper.setChild(null);
+            const wrapperParent = wrapper.getParent();
+            if (wrapperParent && isRemovable(wrapperParent)) {
+                wrapperParent.remove(wrapper);
+            }
+        }
+    }
+
+    private insertBeforeAutowrapping(child: WidgetNode, before: WidgetNode): void {
+        const currentParent = child.container.getParent();
+
+        if (currentParent !== null) {
+            if (child.container instanceof Gtk.ListBoxRow || child.container instanceof Gtk.FlowBoxChild) {
+                if (isRemovable(currentParent)) {
+                    currentParent.remove(child.container);
+                }
+            } else {
+                this.detachAutowrappedChild(child);
+            }
+        } else if (!(child.container instanceof Gtk.ListBoxRow || child.container instanceof Gtk.FlowBoxChild)) {
+            this.detachAutowrappedChild(child);
+        }
+
+        const container: Gtk.Widget = this.container;
+        if (!(container instanceof Gtk.ListBox) && !(container instanceof Gtk.FlowBox)) return;
+
+        const position = this.findAutowrappedPosition(before);
+
+        if (position !== null) {
+            container.insert(child.container, position);
+        } else {
+            container.append(child.container);
+        }
+    }
+
+    private findAutowrappedPosition(before: WidgetNode): number | null {
+        let position = 0;
+        let currentChild = this.container.getFirstChild();
+        const beforeIsRow = before.container instanceof Gtk.ListBoxRow || before.container instanceof Gtk.FlowBoxChild;
+
+        while (currentChild) {
+            const widgetToCompare = beforeIsRow ? currentChild : this.unwrapGtkChild(currentChild);
+
+            if (widgetToCompare && widgetToCompare === before.container) {
+                return position;
+            }
+
+            position++;
+            currentChild = currentChild.getNextSibling();
+        }
+
+        return null;
+    }
+
+    private unwrapGtkChild(child: Gtk.Widget): Gtk.Widget | null {
+        if ("getChild" in child && typeof child.getChild === "function") {
+            return child.getChild() as Gtk.Widget | null;
+        }
+        return child;
+    }
+
+    private reinsertAllChildren(): void {
+        const widgetChildren: WidgetNode[] = [];
+        for (const child of this.children) {
+            if (child instanceof WidgetNode && child.shouldAttachToParent()) {
+                widgetChildren.push(child);
+            }
+        }
+
+        for (const child of widgetChildren) {
+            detachChild(child.container, this.container);
+        }
+
+        for (const child of widgetChildren) {
+            attachChild(child.container, this.container);
+        }
+    }
+
+    private updateSizeRequest(oldProps: P | null, newProps: P): void {
+        const oldWidth = oldProps?.widthRequest as number | undefined;
+        const oldHeight = oldProps?.heightRequest as number | undefined;
+        const newWidth = newProps.widthRequest as number | undefined;
+        const newHeight = newProps.heightRequest as number | undefined;
+
+        if (oldWidth !== newWidth || oldHeight !== newHeight) {
+            this.container.setSizeRequest(newWidth ?? -1, newHeight ?? -1);
+        }
+    }
+
+    private updateGrabFocus(oldProps: P | null, newProps: P): void {
+        const oldGrabFocus = oldProps?.grabFocus as boolean | undefined;
+        const newGrabFocus = newProps.grabFocus as boolean | undefined;
+
+        if (!oldGrabFocus && newGrabFocus) {
+            this.container.grabFocus();
+        }
+    }
+
+    private getPropertyDefaultValue(key: string): unknown {
+        if (!resolvePropMeta(this.container, key)) return undefined;
+
+        const pspec = findProperty(this.container, key);
+        if (!pspec) return undefined;
+
+        const value = pspec.getDefaultValue();
+        const gtype = value.getType();
+        const fundamental = typeFundamental(gtype);
+
+        if (fundamental === Type.BOOLEAN) return value.getBoolean();
+        if (fundamental === Type.INT) return value.getInt();
+        if (fundamental === Type.UINT) return value.getUint();
+        if (fundamental === Type.LONG) return value.getLong();
+        if (fundamental === Type.ULONG) return value.getUlong();
+        if (fundamental === Type.INT64) return value.getInt64();
+        if (fundamental === Type.UINT64) return value.getUint64();
+        if (fundamental === Type.FLOAT) return value.getFloat();
+        if (fundamental === Type.DOUBLE) return value.getDouble();
+        if (fundamental === Type.STRING) return value.getString();
+        if (fundamental === Type.ENUM) return value.getEnum();
+        if (fundamental === Type.FLAGS) return value.getFlags();
+
+        return undefined;
+    }
+
+    private setProperty(key: string, value: unknown): void {
+        const propMeta = resolvePropMeta(this.container, key);
+        if (!propMeta) return;
+
+        const [getterName, setterName] = propMeta;
+        const setter = this.container[setterName as keyof typeof this.container];
+        if (!setter || typeof setter !== "function") return;
+
+        if (getterName && findProperty(this.container, key) instanceof ParamSpecString) {
+            const getter = this.container[getterName as keyof typeof this.container];
+
+            if (getter && typeof getter === "function") {
+                const currentValue = getter.call(this.container);
+                if (currentValue === value) return;
+            }
+        }
+
+        setter.call(this.container, value);
+    }
+
+    private insertBeforeReorderable(container: ReorderableWidget, child: WidgetNode, before: WidgetNode): void {
+        const previousSibling = this.findPreviousSibling(before);
+        const currentParent = child.container.getParent();
+        const isChildOfThisContainer = currentParent && currentParent === container;
+
+        if (isChildOfThisContainer) {
+            container.reorderChildAfter(child.container, previousSibling);
+        } else {
+            detachChildFromParent(child);
+            container.insertChildAfter(child.container, previousSibling);
+        }
+    }
+
+    private insertBeforeInsertable(container: InsertableWidget, child: WidgetNode, before: WidgetNode): void {
+        detachChildFromParent(child);
+        const position = this.findInsertPosition(before);
+        container.insert(child.container, position);
+    }
+
+    private findPreviousSibling(before: WidgetNode): Gtk.Widget | undefined {
+        let beforeChild = this.container.getFirstChild();
+
+        while (beforeChild) {
+            if (beforeChild === before.container) {
+                return beforeChild.getPrevSibling() ?? undefined;
+            }
+            beforeChild = beforeChild.getNextSibling();
+        }
+
+        throw new Error(`Cannot find 'before' sibling in '${this.typeName}'`);
+    }
+
+    private findInsertPosition(before: WidgetNode): number {
+        let position = 0;
+        let currentChild = this.container.getFirstChild();
+
+        while (currentChild) {
+            if (currentChild === before.container) {
+                return position;
+            }
+            position++;
+            currentChild = currentChild.getNextSibling();
+        }
+
+        throw new Error(`Cannot find 'before' child position in '${this.typeName}'`);
+    }
+}
+
+function detachChildFromParent(child: WidgetNode): void {
+    const currentParent = child.container.getParent();
+    if (currentParent !== null && isRemovable(currentParent)) {
+        currentParent.remove(child.container);
+    }
+}

package/src/nodes/window.ts

@@ -0,0 +1,159 @@
+import * as Adw from "@gtkx/ffi/adw";
+import * as Gtk from "@gtkx/ffi/gtk";
+import type { GtkAboutDialogProps, GtkWindowProps } from "../jsx.js";
+import type { Node } from "../node.js";
+import type { Container, Props } from "../types.js";
+import { AnimationNode } from "./animation.js";
+import type { DialogNode } from "./dialog.js";
+import { filterProps, hasChanged } from "./internal/props.js";
+import { MenuNode } from "./menu.js";
+import { MenuModel } from "./models/menu.js";
+import { NavigationPageNode } from "./navigation-page.js";
+import { SlotNode } from "./slot.js";
+import { WidgetNode } from "./widget.js";
+
+// biome-ignore lint/suspicious/noExplicitAny: Required for matching GTK class constructors with varying signatures
+const isOrExtendsClass = (target: object, cls: abstract new (...args: any[]) => any): boolean =>
+    target === cls || Object.prototype.isPrototypeOf.call(cls, target);
+
+const OWN_PROPS = ["onClose"] as const;
+
+export type WindowProps = Pick<GtkWindowProps, "onClose"> & Pick<GtkAboutDialogProps, "creditSections">;
+
+type WindowChild = WindowNode | DialogNode | MenuNode | SlotNode | AnimationNode | NavigationPageNode | WidgetNode;
+
+export class WindowNode extends WidgetNode<Gtk.Window, WindowProps, WindowChild> {
+    private menu: MenuModel;
+
+    public static override createContainer(
+        props: Props,
+        containerClass: typeof Gtk.Window,
+        rootContainer: Container | undefined,
+    ): Gtk.Window {
+        const WindowClass = containerClass;
+
+        if (
+            isOrExtendsClass(WindowClass, Gtk.ApplicationWindow) ||
+            isOrExtendsClass(WindowClass, Adw.ApplicationWindow)
+        ) {
+            if (!(rootContainer instanceof Gtk.Application)) {
+                throw new Error("Expected ApplicationWindow to be created within Application");
+            }
+
+            if (isOrExtendsClass(WindowClass, Adw.ApplicationWindow)) {
+                return new Adw.ApplicationWindow(rootContainer);
+            }
+
+            return new Gtk.ApplicationWindow(rootContainer);
+        }
+
+        return WidgetNode.createContainer(props, containerClass) as Gtk.Window;
+    }
+
+    constructor(typeName: string, props: WindowProps, container: Gtk.Window, rootContainer: Container) {
+        super(typeName, props, container, rootContainer);
+        const application = rootContainer instanceof Gtk.Application ? rootContainer : undefined;
+        const actionMap = container instanceof Gtk.ApplicationWindow ? container : undefined;
+        this.menu = new MenuModel("root", {}, rootContainer, actionMap, application);
+
+        if (container instanceof Gtk.AboutDialog && props.creditSections) {
+            for (const section of props.creditSections) {
+                container.addCreditSection(section.name, section.people);
+            }
+        }
+    }
+
+    protected override shouldAttachToParent(): boolean {
+        return false;
+    }
+
+    public override isValidChild(child: Node): boolean {
+        return (
+            child instanceof WidgetNode ||
+            child instanceof MenuNode ||
+            child instanceof SlotNode ||
+            child instanceof AnimationNode ||
+            child instanceof NavigationPageNode
+        );
+    }
+
+    public override appendChild(child: WindowChild): void {
+        if (child instanceof WindowNode) {
+            child.container.setTransientFor(this.container);
+            super.appendChild(child);
+            return;
+        }
+
+        if (child instanceof MenuNode) {
+            this.menu.appendChild(child);
+            return;
+        }
+
+        super.appendChild(child);
+    }
+
+    public override removeChild(child: WindowChild): void {
+        if (child instanceof WindowNode) {
+            child.container.setTransientFor(null);
+            super.removeChild(child);
+            return;
+        }
+
+        if (child instanceof MenuNode) {
+            this.menu.removeChild(child);
+            return;
+        }
+
+        super.removeChild(child);
+    }
+
+    public override insertBefore(child: WindowChild, before: WindowChild): void {
+        if (child instanceof MenuNode) {
+            if (before instanceof MenuNode) {
+                this.menu.insertBefore(child, before);
+            } else {
+                this.menu.appendChild(child);
+            }
+            return;
+        }
+
+        if (child instanceof WindowNode) {
+            child.container.setTransientFor(this.container);
+        }
+
+        super.insertBefore(child, before);
+    }
+
+    public override finalizeInitialChildren(props: WindowProps): boolean {
+        this.commitUpdate(null, props);
+        return true;
+    }
+
+    public override commitUpdate(oldProps: WindowProps | null, newProps: WindowProps): void {
+        super.commitUpdate(oldProps ? filterProps(oldProps, OWN_PROPS) : null, filterProps(newProps, OWN_PROPS));
+        this.applyOwnProps(oldProps, newProps);
+    }
+
+    public override commitMount(): void {
+        this.container.present();
+    }
+
+    public override detachDeletedInstance(): void {
+        this.container.setVisible(false);
+        this.container.destroy();
+        super.detachDeletedInstance();
+    }
+
+    private applyOwnProps(oldProps: WindowProps | null, newProps: WindowProps): void {
+        if (hasChanged(oldProps, newProps, "onClose")) {
+            const userHandler = newProps.onClose;
+            const wrappedHandler = userHandler
+                ? () => {
+                      userHandler();
+                      return true;
+                  }
+                : undefined;
+            this.signalStore.set(this, this.container, "close-request", wrappedHandler);
+        }
+    }
+}

package/src/portal.ts

@@ -0,0 +1,37 @@
+import type { ReactNode, ReactPortal } from "react";
+import type { Container } from "./types.js";
+
+/**
+ * Creates a React portal for rendering children 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.
+ *
+ * @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
+ * import { createPortal } from "@gtkx/react";
+ *
+ * const Modal = ({ container, children }) => {
+ *   return createPortal(
+ *     <GtkWindow modal>
+ *       {children}
+ *     </GtkWindow>,
+ *     container
+ *   );
+ * };
+ * ```
+ */
+export const createPortal = (children: ReactNode, container: Container, key?: string | null): ReactPortal => {
+    return {
+        $$typeof: Symbol.for("react.portal"),
+        key: key ?? null,
+        children,
+        containerInfo: container,
+        implementation: null,
+    } as unknown as ReactPortal;
+};

package/src/reconciler.ts

@@ -0,0 +1,52 @@
+import ReactReconciler from "react-reconciler";
+import packageJson from "../package.json" with { type: "json" };
+import { createHostConfig, type ReconcilerInstance } from "./host-config.js";
+
+/**
+ * Manages the React reconciler instance for GTKX.
+ *
+ * This class wraps the React Reconciler and handles initialization
+ * including DevTools integration for development environments.
+ *
+ * @internal
+ */
+class Reconciler {
+    private instance: ReconcilerInstance;
+
+    constructor() {
+        this.instance = ReactReconciler(createHostConfig());
+        this.injectDevTools();
+    }
+
+    /**
+     * Returns the underlying React Reconciler instance.
+     *
+     * @returns The React Reconciler instance for direct reconciler operations
+     */
+    getInstance(): ReconcilerInstance {
+        return this.instance;
+    }
+
+    private injectDevTools(): void {
+        if (process.env.NODE_ENV === "production") return;
+
+        this.instance.injectIntoDevTools({
+            bundleType: 1,
+            version: packageJson.version,
+            rendererPackageName: "@gtkx/react",
+        });
+    }
+}
+
+/**
+ * The GTKX React reconciler instance.
+ *
+ * Provides low-level access to the React reconciler for advanced use cases.
+ * Most applications should use {@link render} instead.
+ *
+ * @example
+ * ```tsx
+ * const instance = reconciler.getInstance();
+ * ```
+ */
+export const reconciler = new Reconciler();