@gtkx/react 1.0.0-rc.4 → 1.0.0

package/src/components/window.tsx

@@ -1,11 +1,13 @@
 import type * as Gtk from "@gtkx/gi/gtk";
-import { type ElementType, type ReactNode, type Ref, useLayoutEffect, useState } from "react";
-import { useMergedRef } from "../hooks/use-merged-refs.js";
+import { type ElementType, type ReactElement, type ReactNode, use } from "react";
 import { ParentWindowContext } from "../hooks/use-parent-window.js";
+import { createPresentedComponent, type PresentedProps } from "../hooks/use-presented-instance.js";
 import { applyWrite } from "../reconciler/signals.js";
+import { createPortaledComponent } from "./portaled.js";
 
-type WindowComponentProps = {
-    ref?: Ref<Gtk.Window | null> | undefined;
+type WindowComponentProps = PresentedProps<Gtk.Window> & {
+    // eslint-disable-next-line gtkx/accessor-naming
+    transientFor?: Gtk.Window | ReactElement | null | undefined;
 };
 
 const presentWindow = (window: Gtk.Window): void => {
@@ -20,30 +22,29 @@ const destroyWindow = (window: Gtk.Window): void => {
     });
 };
 
-const createWindowComponent = (Component: ElementType): ((props: WindowComponentProps) => ReactNode) => {
-    return ({ ref, ...rest }: WindowComponentProps): ReactNode => {
-        const [window, setWindow] = useState<Gtk.Window | null>(null);
-        const mergedRef = useMergedRef(ref, setWindow);
+const usePresentWindow = (): ((window: Gtk.Window) => void) => presentWindow;
 
-        useLayoutEffect(() => {
-            if (!window) {
-                return;
-            }
-
-            presentWindow(window);
+const createPresentedWindowComponent = (Component: ElementType): ((props: PresentedProps<Gtk.Window>) => ReactNode) =>
+    createPresentedComponent<Gtk.Window>(Component, {
+        usePresent: usePresentWindow,
+        dismiss: destroyWindow,
+        wrap: (element, window) => (
+            <ParentWindowContext.Provider value={window}>{element}</ParentWindowContext.Provider>
+        ),
+    });
 
-            return () => {
-                destroyWindow(window);
-            };
-        }, [window]);
+const withDefaultTransientFor = (Component: ElementType): ((props: WindowComponentProps) => ReactNode) => {
+    return (props: WindowComponentProps): ReactNode => {
+        const parent = use(ParentWindowContext);
+        const isDefaulted = props.transientFor === undefined && parent !== null;
 
-        return (
-            <ParentWindowContext.Provider value={window}>
-                <Component ref={mergedRef} {...rest} />
-            </ParentWindowContext.Provider>
-        );
+        return <Component {...(isDefaulted ? { ...props, transientFor: parent } : props)} />;
     };
 };
 
+const createWindowComponent = (Component: ElementType): ((props: unknown) => ReactNode) =>
+    createPortaledComponent(withDefaultTransientFor(createPresentedWindowComponent(Component)));
+
+export { createPresentedWindowComponent };
 /** @internal */
 export { createWindowComponent };

package/src/config.ts

@@ -1,6 +1,15 @@
 /** @public */
+export { createElementComponent } from "./components/element.js";
+/** @public */
 export { BUILTIN_ELEMENTS } from "./element-config.js";
 /** @public */
-export type { DetachInfo, ElementBehavior, ElementConfig, PlaceInfo, Props } from "./reconciler/registry.js";
+export type {
+    DetachInfo,
+    ElementBehavior,
+    ElementConfig,
+    ModuleExport,
+    PlaceInfo,
+    Props,
+} from "./reconciler/registry.js";
 /** @public */
 export { defineBehavior, defineElements, ELEMENTS, mergeElementConfigs } from "./reconciler/registry.js";

package/src/element-behaviors.ts

@@ -1,11 +1,13 @@
 import type * as GObject from "@gtkx/gi/gobject";
 import * as Gio from "@gtkx/gi/gio";
+import * as GLib from "@gtkx/gi/glib";
 import * as Gtk from "@gtkx/gi/gtk";
 import type {
     ActionAccel,
     CreditSection,
     DragSourceIcon,
     LevelBarOffset,
+    MainOption,
     MenuItem,
     ScaleMark,
     VflConstraints,
@@ -14,6 +16,7 @@ import { BUILTIN_ELEMENTS, SINGLE_CHILD_TYPES } from "./element-config.js";
 import {
     addRemoveSlot,
     adoptedChildrenSlot,
+    applicationCreator,
     boxSlot,
     childSetterSlot,
     controlledText,
@@ -295,6 +298,7 @@ const BUILTIN_BEHAVIORS: Record<string, ElementConfig<never>> = {
     },
     GtkApplication: {
         behaviors: [
+            applicationCreator(Gtk.Application),
             addRemoveSlot<Gtk.Window, Gtk.Application>(
                 "children",
                 "GtkWindow",
@@ -313,6 +317,11 @@ const BUILTIN_BEHAVIORS: Record<string, ElementConfig<never>> = {
                     application.setAccelsForAction(item.detailedActionName, []);
                 },
             }),
+            list<Gtk.Application, MainOption>("mainOptions", {
+                add: (application, option) => {
+                    addMainOption(application, option);
+                },
+            }),
         ],
     },
     GtkAboutDialog: {
@@ -391,6 +400,17 @@ function layoutChild(parent: Gtk.Widget, child: Gtk.Widget): GObject.Object | nu
     return parent.getLayoutManager()?.getLayoutChild(child) ?? null;
 }
 
+const addMainOption = (application: Gtk.Application, option: MainOption): void => {
+    application.addMainOption(
+        option.longName,
+        option.shortName?.codePointAt(0) ?? 0,
+        option.flags ?? GLib.OptionFlags.NONE,
+        option.arg ?? GLib.OptionArg.NONE,
+        option.description,
+        option.argDescription ?? null,
+    );
+};
+
 const buildMenu = (items: MenuItem[]): Gio.Menu => {
     const menu = Gio.Menu.new();
 

package/src/element-config.ts

@@ -4,7 +4,6 @@ const SINGLE_CHILD_TYPES: string[] = [
     "GtkAspectFrame",
     "GtkButton",
     "GtkCheckButton",
-    "GtkComboBox",
     "GtkDragIcon",
     "GtkExpander",
     "GtkFlowBoxChild",
@@ -43,6 +42,9 @@ const BUILTIN_ELEMENTS: Record<string, ElementConfig> = {
         component: internal("createWindowComponent"),
         omittedProps: ["child"],
     },
+    GtkApplicationWindow: {
+        component: internal("createApplicationWindowComponent"),
+    },
     GtkLabel: {
         props: internal("ChildrenProps"),
     },
@@ -71,7 +73,7 @@ const BUILTIN_ELEMENTS: Record<string, ElementConfig> = {
         isLazy: true,
     },
     GActionGroup: {
-        props: internal("GActionGroupProps"),
+        props: internal("ActionGroupProps"),
     },
     GtkWidget: {
         props: internal("GtkWidgetProps"),
@@ -96,10 +98,10 @@ const BUILTIN_ELEMENTS: Record<string, ElementConfig> = {
         props: internal("ChildrenProps"),
     },
     GActionMap: {
-        props: internal("GActionMapProps"),
+        props: internal("ActionMapProps"),
     },
     GMenu: {
-        props: internal("GMenuProps"),
+        props: internal("MenuProps"),
     },
     GtkColumnView: {
         props: internal("ChildrenProps"),
@@ -112,6 +114,7 @@ const BUILTIN_ELEMENTS: Record<string, ElementConfig> = {
     },
     GtkSizeGroup: {
         props: internal("GtkSizeGroupProps"),
+        component: internal("createPortaledComponent"),
     },
     GtkConstraintLayout: {
         props: internal("GtkConstraintLayoutProps"),

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

@@ -61,4 +61,4 @@ function useMergedRef<T>(first: PossibleRef<T>, second: PossibleRef<T>): RefCall
     return useMemo(() => mergeRefs(first, second), [first, second]);
 }
 
-export { assignRef, mergeRefs, useMergedRef };
+export { useMergedRef };

package/src/hooks/use-presented-instance.tsx

@@ -0,0 +1,50 @@
+import { type ElementType, type ReactNode, type Ref, type RefCallback, useLayoutEffect, useState } from "react";
+import { useMergedRef } from "./use-merged-refs.js";
+
+type PresentedProps<T> = {
+    ref?: Ref<T | null> | undefined;
+};
+
+type PresentedOptions<T> = {
+    usePresent: () => (instance: T) => void;
+    dismiss: (instance: T) => void;
+    wrap?: (element: ReactNode, instance: T | null) => ReactNode;
+};
+
+const usePresentedInstance = <T,>(
+    ref: Ref<T | null> | undefined,
+    present: (instance: T) => void,
+    dismiss: (instance: T) => void,
+): [T | null, RefCallback<T>] => {
+    const [instance, setInstance] = useState<T | null>(null);
+    const mergedRef = useMergedRef(ref, setInstance);
+
+    useLayoutEffect(() => {
+        if (!instance) {
+            return;
+        }
+
+        present(instance);
+
+        return () => {
+            dismiss(instance);
+        };
+    }, [instance, present, dismiss]);
+
+    return [instance, mergedRef];
+};
+
+const createPresentedComponent = <T,>(
+    Component: ElementType,
+    options: PresentedOptions<T>,
+): ((props: PresentedProps<T>) => ReactNode) => {
+    return ({ ref, ...rest }: PresentedProps<T>): ReactNode => {
+        const present = options.usePresent();
+        const [instance, mergedRef] = usePresentedInstance(ref, present, options.dismiss);
+        const element = <Component ref={mergedRef} {...rest} />;
+
+        return options.wrap ? options.wrap(element, instance) : element;
+    };
+};
+
+export { createPresentedComponent, type PresentedProps };

package/src/hooks/use-property.ts

@@ -3,6 +3,7 @@ import { kebabCase } from "@gtkx/utils";
 import type { RefProp } from "../utils/ref-prop.js";
 import { useObjectValue } from "./use-object-value.js";
 
+/** The property map `T` declares, from camelCase property name to value type. */
 type Properties<T extends GObject.Object> = NonNullable<T["__properties__"]>;
 /** Every property `T` declares that is also readable off the instance, in camelCase. */
 type PropertyName<T extends GObject.Object> = keyof Properties<T> & keyof T;
@@ -20,4 +21,4 @@ function useProperty<T extends GObject.Object, P extends PropertyName<T>>(
     return useObjectValue(object, `notify::${kebabCase(propertyName)}`, (obj) => obj?.[propertyName]);
 }
 
-export { useProperty, type PropertyName };
+export { useProperty };

package/src/hooks/use-signal.ts

@@ -3,6 +3,7 @@ import type { SignalHandler } from "@gtkx/runtime";
 import { useEffectEvent, useLayoutEffect } from "react";
 import { type RefProp, resolveRefProp } from "../utils/ref-prop.js";
 
+/** The signal map `T` declares, from signal name to handler signature. */
 type Signals<T extends GObject.Object> = NonNullable<T["__signals__"]>;
 /** Every signal name `T` declares, on its own or narrowed by a `::detail` suffix. */
 type SignalName<T extends GObject.Object> = keyof Signals<T> | `${keyof Signals<T> & string}::${string}`;
@@ -67,4 +68,4 @@ function useSignal<T extends GObject.Object, S extends SignalName<T> & string>(
     }, [object, signal, isAfter, isImmediate]);
 }
 
-export { useSignal, type SignalName, type TypedSignalHandler };
+export { useSignal };

package/src/internal.ts

@@ -1,15 +1,17 @@
 import "./bootstrap.js";
 
+/** @internal */
+export { createApplicationWindowComponent } from "./components/application-window.js";
 /** @internal */
 export { createApplicationComponent } from "./components/application.js";
 export { createElementComponent } from "./components/element.js";
 /** @internal */
+export { createPortaledComponent } from "./components/portaled.js";
+/** @internal */
 export { createWindowComponent } from "./components/window.js";
 export { useMergedRef } from "./hooks/use-merged-refs.js";
 export type * from "./prop-types.js";
-export type { ModuleExport } from "./reconciler/registry.js";
+export { settleAccessible } from "./reconciler/apply-props.js";
 export { isRootElement } from "./reconciler/root-element.js";
 export { createReconcilerRoot, type ReconcilerRoot, setReconcilerErrorHandler } from "./reconciler/root.js";
-export { applyWrite } from "./reconciler/signals.js";
-export { getAccessibleMetadata } from "./utils/accessible-metadata.js";
 export type { SettingsSchema, SettingsSchemaKeys, SettingValue } from "./utils/settings.js";

package/src/prop-types.ts

@@ -1,4 +1,6 @@
+/* eslint-disable gtkx/no-library-prefix */
 import type * as Gdk from "@gtkx/gi/gdk";
+import type * as GLib from "@gtkx/gi/glib";
 import type * as GObject from "@gtkx/gi/gobject";
 import type * as Gtk from "@gtkx/gi/gtk";
 import type { ReactNode } from "react";
@@ -53,6 +55,22 @@ type CreditSection = {
     people: string[];
 };
 
+/** One command-line option a `Gtk.Application` accepts. */
+type MainOption = {
+    /** Name the option is spelled with after two dashes, such as `verbose` for `--verbose`. */
+    longName: string;
+    /** Single character the option is spelled with after one dash, such as `v` for `-v`; defaults to none. */
+    shortName?: string | null;
+    /** How the option itself is parsed and listed; defaults to `GLib.OptionFlags.NONE`. */
+    flags?: GLib.OptionFlags;
+    /** Type of argument the option takes; defaults to `GLib.OptionArg.NONE`, meaning it takes none. */
+    arg?: GLib.OptionArg;
+    /** Text describing the option in `--help`. */
+    description: string;
+    /** Placeholder standing for the option's argument in `--help`; defaults to none. */
+    argDescription?: string | null;
+};
+
 /** One accelerator binding on a `Gtk.Application`. */
 type ActionAccel = {
     /** Action the accelerators activate, such as `app.quit` or `win.open('file')`. */
@@ -86,19 +104,19 @@ type GtkWidgetProps = {
 } & ChildrenProps;
 
 /** Props of an action group placed in a widget's `actionGroups` slot. */
-type GActionGroupProps = {
+type ActionGroupProps = {
     /** Prefix the group's actions are addressed by, such as `win`; defaults to the empty string. */
     prefix?: string | null | undefined;
 };
 
 /** Props of an element implementing `Gio.ActionMap`. */
-type GActionMapProps = {
+type ActionMapProps = {
     /** `Gio.Action` elements added to the map, removed again by their `name`. */
     actions?: ReactNode | null | undefined;
 };
 
 /** Props of a `Gio.Menu` element. */
-type GMenuProps = {
+type MenuProps = {
     /** Entries the menu is rebuilt from whenever they change. */
     items?: MenuItem[] | null | undefined;
 };
@@ -165,7 +183,10 @@ type GtkSizeGroupProps = {
 
 /** Props of a `Gtk.AboutDialog` element. */
 type GtkAboutDialogProps = {
-    /** Extra sections appended to the dialog's credits, which GTK offers no way to remove. */
+    /**
+     * Extra sections appended to the dialog's credits. GTK offers no way to remove one, so the list
+     * cannot change once it has been applied.
+     */
     creditSections?: CreditSection[] | null | undefined;
 };
 
@@ -173,6 +194,11 @@ type GtkAboutDialogProps = {
 type GtkApplicationProps = {
     /** Accelerators bound to the application's actions. */
     actionAccels?: ActionAccel[] | null | undefined;
+    /**
+     * Command-line options the application parses, registered before it starts. GLib offers no way to
+     * unregister one, so the list cannot change once it has been applied.
+     */
+    mainOptions?: MainOption[] | null | undefined;
 } & ChildrenProps;
 
 /** Props of a `Gtk.DropTarget` element. */
@@ -199,13 +225,14 @@ export {
     type ScaleMark,
     type LevelBarOffset,
     type CreditSection,
+    type MainOption,
     type ActionAccel,
     type DragSourceIcon,
     type ChildrenProps,
     type GtkWidgetProps,
-    type GActionGroupProps,
-    type GActionMapProps,
-    type GMenuProps,
+    type ActionGroupProps,
+    type ActionMapProps,
+    type MenuProps,
     type GtkShortcutControllerProps,
     type GtkOverlayProps,
     type GtkTextChildAnchorProps,

package/src/reconciler/apply-props.ts

@@ -1,7 +1,7 @@
 import type * as GObject from "@gtkx/gi/gobject";
 import type { SignalHandler } from "@gtkx/runtime";
 import * as Gtk from "@gtkx/gi/gtk";
-import { drain, kebabCase } from "@gtkx/utils";
+import { drain, isDeepEqual, kebabCase } from "@gtkx/utils";
 import type { ElementBehavior, Props } from "./registry.js";
 import { applyAccessibleProps, isAccessibleProp } from "../utils/accessible-props.js";
 import { type TypeInfo, typeInfoFor } from "./metadata.js";
@@ -16,9 +16,13 @@ type PropChange = { prev: Props; next: Props };
 const REACT_RESERVED_PROPS = new Set(["children", "ref", "key"]);
 const NOTIFY_PREFIX = "onNotify";
 const HANDLER_PREFIX = "on";
+const HANDLER_NAME = /^on[A-Z]/;
 const flushDirty: Set<ElementNode> = new Set();
+const accessibleDirty: Map<ElementNode, Props> = new Map();
+const mapWatched: WeakSet<ElementNode> = new WeakSet();
+const pendingMap: Set<ElementNode> = new Set();
 
-const isHandlerName = (name: string): boolean => /^on[A-Z]/.test(name);
+const isHandlerName = (name: string): boolean => HANDLER_NAME.test(name);
 
 const signalForProp = (info: TypeInfo, name: string): string => {
     if (name === NOTIFY_PREFIX) {
@@ -102,29 +106,42 @@ const applyEntry = (node: ElementNode, info: TypeInfo, delta: PropDelta): void =
 };
 
 const eachChangedName = (prev: Props, next: Props, visit: (name: string) => void): void => {
-    const names = new Set([...Object.keys(prev), ...Object.keys(next)]);
-
-    for (const name of names) {
+    for (const name in prev) {
         visit(name);
     }
+
+    for (const name in next) {
+        if (!Object.hasOwn(prev, name)) {
+            visit(name);
+        }
+    }
 };
 
-const constructOnlyChangeError = (typeName: string, name: string): Error =>
+const propChangeError = (typeName: string, name: string): Error =>
     new Error(
         `Cannot change the construct-only prop '${name}' of <${typeName}> after it is created. ` +
-        "GTK accepts it only while the object is being built, so give the element a key that " +
+        "It is only accepted while the element is being built, so give the element a key that " +
         `changes with '${name}' and React will build a new one.`,
     );
 
-const assertConstructOnlyUnchanged = (typeName: string, prev: Props, next: Props): void => {
+const hasAppliedValue = (value: unknown): boolean => (Array.isArray(value) ? value.length > 0 : value !== undefined);
+
+const isConstructOnlyChange = (info: TypeInfo, name: string, change: PropChange): boolean =>
+    info.constructOnly.has(name) && !Object.is(change.prev[name], change.next[name]);
+
+const isDeclaredConstructOnlyChange = (info: TypeInfo, name: string, change: PropChange): boolean =>
+    info.declaredConstructOnly.has(name) &&
+    hasAppliedValue(change.prev[name]) &&
+    !isDeepEqual(change.prev[name], change.next[name]);
+
+const assertPropsCanChange = (typeName: string, prev: Props, next: Props): void => {
     const info = typeInfoFor(typeName);
+    const change: PropChange = { prev, next };
 
     eachChangedName(prev, next, (name) => {
-        if (!info.constructOnly.has(name) || Object.is(prev[name], next[name])) {
-            return;
+        if (isConstructOnlyChange(info, name, change) || isDeclaredConstructOnlyChange(info, name, change)) {
+            throw propChangeError(typeName, name);
         }
-
-        throw constructOnlyChangeError(typeName, name);
     });
 };
 
@@ -213,22 +230,58 @@ const flushBehaviors = (): void => {
     });
 };
 
-const mountBehaviors = (node: ElementNode): void => {
-    if (!typeInfoFor(node.typeName).hasMount) {
+const applyAccessible = (object: GObject.Object, prev: Props | null, next: Props): void => {
+    if (object instanceof Gtk.Accessible) {
+        applyAccessibleProps(object, prev, next);
+    }
+};
+
+const markAccessible = (node: ElementNode, prev: Props): void => {
+    if (!accessibleDirty.has(node)) {
+        accessibleDirty.set(node, prev);
+    }
+};
+
+const hasAccessibleProp = (props: Props): boolean => {
+    for (const name in props) {
+        if (isAccessibleProp(name)) {
+            return true;
+        }
+    }
+
+    return false;
+};
+
+const watchMap = (node: ElementNode): void => {
+    const { object } = node;
+
+    if (mapWatched.has(node) || !(object instanceof Gtk.Widget) || !hasAccessibleProp(node.props)) {
         return;
     }
 
-    eachBehavior(node, (behavior, context) => behavior.mount?.(node.object, context));
+    mapWatched.add(node);
+
+    object.connect("map", () => {
+        pendingMap.add(node);
+        setTimeout(settleAccessible, 0);
+    });
 };
 
-const unmountBehaviors = (node: ElementNode): void => {
-    eachBehavior(node, (behavior, context) => behavior.unmount?.(node.object, context));
+const settleAccessible = (): void => {
+    drain(pendingMap, (node) => {
+        if (node.object instanceof Gtk.Widget && node.object.getMapped()) {
+            applyAccessible(node.object, null, node.props);
+        }
+    });
 };
 
-const applyAccessible = (object: GObject.Object, prev: Props, next: Props): void => {
-    if (object instanceof Gtk.Widget) {
-        applyAccessibleProps(object, prev, next);
+const flushAccessible = (): void => {
+    for (const [node, prev] of accessibleDirty) {
+        applyAccessible(node.object, prev, node.props);
+        watchMap(node);
     }
+
+    accessibleDirty.clear();
 };
 
 const applyElementProps = (node: ElementNode, prev: Props, next: Props): void => {
@@ -236,8 +289,8 @@ const applyElementProps = (node: ElementNode, prev: Props, next: Props): void =>
     const consumed = runBehaviorUpdates(node, info, prev, next);
     applyValueEntries(node, info, { prev, next }, consumed);
     restoreActionableSensitivity(node, info, prev, next);
-    applyAccessible(node.object, prev, next);
     applyHandlers(node, info, prev, next);
+    markAccessible(node, prev);
     markFlush(node);
     node.props = next;
 };
@@ -262,10 +315,10 @@ const applyAdoptedProps = (target: SignalTarget, prev: Props, next: Props): void
 
 export {
     markFlush,
+    flushAccessible,
+    settleAccessible,
     flushBehaviors,
-    mountBehaviors,
-    unmountBehaviors,
     applyElementProps,
     applyAdoptedProps,
-    assertConstructOnlyUnchanged,
+    assertPropsCanChange,
 };