@gtkx/react 1.0.0-rc.4 → 1.1.0

package/src/reconciler/root.ts

@@ -2,6 +2,7 @@ import type { ErrorInfo, ReactNode, ReactPortal } from "react";
 import * as Gdk from "@gtkx/gi/gdk";
 import { createLogger, type Logger } from "@gtkx/utils";
 import { ConcurrentRoot } from "react-reconciler/constants.js";
+import { injectIntoDevTools } from "./devtools.js";
 import { type Container, reconciler } from "./host-config.js";
 import { rootElement } from "./root-element.js";
 
@@ -15,14 +16,23 @@ type RootErrorCallbacks = {
 
 type ReconcilerRootOptions = RootErrorCallbacks & { containerInfo: Container };
 
+/** A render root whose updates and teardown the caller drives, with error handling left to it. */
 type ReconcilerRoot = {
+    /**
+     * Mounts an element tree into the container, or updates the tree already mounted there. Passing `null` unmounts
+     * the container instead.
+     */
     update: (element: ReactNode) => void;
+    /** Hands the root to `teardown`, then stops {@link quit} from unmounting the container. */
     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 = {
-    /** Mounts an element tree into the container, or updates the tree already mounted there. */
+    /**
+     * Mounts an element tree into the container, or updates the tree already mounted there. Rendering `null` unmounts
+     * the container instead.
+     */
     render: (element: ReactNode) => void;
     /** Unmounts the rendered tree and runs its effect cleanups. */
     unmount: () => void;
@@ -61,7 +71,9 @@ const logCaughtRenderError = (error: unknown): void => {
 };
 
 const openContainer = (containerInfo: Container, callbacks: RootErrorCallbacks): OpaqueRoot => {
-    const container = reconciler.createContainer(
+    injectIntoDevTools(reconciler);
+
+    return reconciler.createContainer(
         containerInfo,
         ConcurrentRoot,
         null,
@@ -81,10 +93,6 @@ const openContainer = (containerInfo: Container, callbacks: RootErrorCallbacks):
         },
         (): void => undefined,
     ) as OpaqueRoot;
-
-    activeRoots.add(container);
-
-    return container;
 };
 
 const unmountContainer = (container: OpaqueRoot): void => {
@@ -92,12 +100,23 @@ const unmountContainer = (container: OpaqueRoot): void => {
     activeRoots.delete(container);
 };
 
+const mountContainer = (container: OpaqueRoot, element: ReactNode): void => {
+    if (element === null) {
+        unmountContainer(container);
+
+        return;
+    }
+
+    activeRoots.add(container);
+    reconciler.updateContainer(element, container, null, null);
+};
+
 const createReconcilerRoot = (options: ReconcilerRootOptions): ReconcilerRoot => {
     const container = openContainer(options.containerInfo, options);
 
     const root: ReconcilerRoot = {
         update: (element) => {
-            reconciler.updateContainer(element, container, null, null);
+            mountContainer(container, element);
         },
         unmount: async (teardown) => {
             await teardown(root);
@@ -122,7 +141,7 @@ const createRoot = (container: Container = rootElement): Root => {
 
     return {
         render: (element) => {
-            reconciler.updateContainer(element, opaque, null, null);
+            mountContainer(opaque, element);
         },
         unmount: () => {
             unmountContainer(opaque);
@@ -130,13 +149,20 @@ const createRoot = (container: Container = rootElement): Root => {
     };
 };
 
-/** Unmounts every active render root and stops the originating signal from propagating further. */
-const quit = (): typeof Gdk.EVENT_STOP => {
-    for (const container of activeRoots) {
+/**
+ * Unmounts every render root that currently holds a mounted tree.
+ *
+ * @returns `Gdk.EVENT_STOP` when at least one root came down, so a close-request handler keeps GTK4 from closing the
+ * window itself, and `Gdk.EVENT_PROPAGATE` when there was nothing to unmount, so the default handler still runs.
+ */
+const quit = (): typeof Gdk.EVENT_PROPAGATE | typeof Gdk.EVENT_STOP => {
+    const containers = [...activeRoots];
+
+    for (const container of containers) {
         unmountContainer(container);
     }
 
-    return Gdk.EVENT_STOP;
+    return containers.length > 0 ? Gdk.EVENT_STOP : Gdk.EVENT_PROPAGATE;
 };
 
 /**

package/src/reconciler/signals.ts

@@ -85,7 +85,6 @@ const disconnectAllHandlers = (target: SignalTarget): void => {
 
 export {
     applyWrite,
-    isApplyingWrite,
     connectHandler,
     disconnectHandler,
     disconnectAllHandlers,

package/src/utils/accessible-props.ts

@@ -1,7 +1,6 @@
 import * as GObject from "@gtkx/gi/gobject";
 import * as Gtk from "@gtkx/gi/gtk";
 import type { Props } from "../reconciler/registry.js";
-import { deleteAccessibleMetadata, setAccessibleMetadata } from "./accessible-metadata.js";
 
 /**
  * Accessibility props available on every widget. Each member maps to a GTK4 accessible attribute
@@ -69,7 +68,7 @@ type AccessibleProps = {
     /** Whether the link has already been followed. */
     accessibleVisited?: boolean | null | undefined;
     /** Descendant that holds the focus while the widget itself keeps it. */
-    accessibleActiveDescendant?: Gtk.Widget | null | undefined;
+    accessibleActiveDescendant?: Gtk.Accessible | null | undefined;
     /** Total number of columns in the table, including any that are not rendered. */
     accessibleColCount?: number | null | undefined;
     /** One-based column position of the cell within its table. */
@@ -79,19 +78,19 @@ type AccessibleProps = {
     /** Number of columns the cell spans. */
     accessibleColSpan?: number | null | undefined;
     /** Widgets whose content or presence this widget controls. */
-    accessibleControls?: Gtk.Widget[] | null | undefined;
+    accessibleControls?: Gtk.Accessible[] | null | undefined;
     /** Widgets that describe this one. */
-    accessibleDescribedBy?: Gtk.Widget[] | null | undefined;
+    accessibleDescribedBy?: Gtk.Accessible[] | null | undefined;
     /** Widgets holding extended detail about this one. */
-    accessibleDetails?: Gtk.Widget[] | null | undefined;
+    accessibleDetails?: Gtk.Accessible[] | null | undefined;
     /** Widgets holding the message that explains why the value is invalid. */
-    accessibleErrorMessage?: Gtk.Widget[] | null | undefined;
+    accessibleErrorMessage?: Gtk.Accessible[] | null | undefined;
     /** Widgets to read next, overriding the default reading order. */
-    accessibleFlowTo?: Gtk.Widget[] | null | undefined;
+    accessibleFlowTo?: Gtk.Accessible[] | null | undefined;
     /** Widgets that label this one. */
-    accessibleLabelledBy?: Gtk.Widget[] | null | undefined;
+    accessibleLabelledBy?: Gtk.Accessible[] | null | undefined;
     /** Widgets this one owns that the widget hierarchy does not already imply. */
-    accessibleOwns?: Gtk.Widget[] | null | undefined;
+    accessibleOwns?: Gtk.Accessible[] | null | undefined;
     /** One-based position of the widget within its set. */
     accessiblePosInSet?: number | null | undefined;
     /** Total number of rows in the table, including any that are not rendered. */
@@ -106,7 +105,7 @@ type AccessibleProps = {
     accessibleSetSize?: number | null | undefined;
 };
 
-type AccessibleValueType = "string" | "boolean" | "int" | "double" | "object" | "list";
+type AccessibleValueType = "string" | "boolean" | "optionalBoolean" | "int" | "double" | "object" | "list";
 
 type AccessiblePropertyDescriptor = {
     kind: "property";
@@ -152,12 +151,12 @@ const ACCESSIBLE_PROP_MAP: Record<keyof AccessibleProps, AccessibleDescriptor> =
     accessibleBusy: buildState(Gtk.AccessibleState.BUSY, "boolean"),
     accessibleChecked: buildState(Gtk.AccessibleState.CHECKED, "int"),
     accessibleDisabled: buildState(Gtk.AccessibleState.DISABLED, "boolean"),
-    accessibleExpanded: buildState(Gtk.AccessibleState.EXPANDED, "int"),
+    accessibleExpanded: buildState(Gtk.AccessibleState.EXPANDED, "optionalBoolean"),
     accessibleHidden: buildState(Gtk.AccessibleState.HIDDEN, "boolean"),
     accessibleInvalid: buildState(Gtk.AccessibleState.INVALID, "int"),
     accessiblePressed: buildState(Gtk.AccessibleState.PRESSED, "int"),
-    accessibleSelected: buildState(Gtk.AccessibleState.SELECTED, "int"),
-    accessibleVisited: buildState(Gtk.AccessibleState.VISITED, "int"),
+    accessibleSelected: buildState(Gtk.AccessibleState.SELECTED, "optionalBoolean"),
+    accessibleVisited: buildState(Gtk.AccessibleState.VISITED, "optionalBoolean"),
     accessibleActiveDescendant: buildRelation(Gtk.AccessibleRelation.ACTIVE_DESCENDANT, "object"),
     accessibleColCount: buildRelation(Gtk.AccessibleRelation.COL_COUNT, "int"),
     accessibleColIndex: buildRelation(Gtk.AccessibleRelation.COL_INDEX, "int"),
@@ -214,6 +213,11 @@ const buildValue = (descriptor: AccessibleDescriptor, jsValue: unknown): GObject
                 v.setBoolean(jsValue as boolean);
             });
         }
+        case "optionalBoolean": {
+            return GObject.buildValue(GObject.TYPE_INT, (v) => {
+                v.setInt(jsValue === true ? 1 : 0);
+            });
+        }
         case "int": {
             return GObject.buildValue(GObject.TYPE_INT, (v) => {
                 v.setInt(jsValue as number);
@@ -230,7 +234,7 @@ const buildValue = (descriptor: AccessibleDescriptor, jsValue: unknown): GObject
             });
         }
         case "list": {
-            const list = Gtk.AccessibleList.newFromList(jsValue as Gtk.Widget[]);
+            const list = Gtk.AccessibleList.newFromList(jsValue as Gtk.Accessible[]);
 
             return GObject.buildValue(Gtk.AccessibleList.prototype.__type__, (v) => {
                 v.setBoxed(list);
@@ -281,24 +285,18 @@ function resetDescriptor(widget: Gtk.Accessible, descriptor: AccessibleDescripto
 const applyChangedProp = (widget: Gtk.Accessible, name: keyof AccessibleProps, newValue: unknown): void => {
     if (newValue == null) {
         resetDescriptor(widget, ACCESSIBLE_PROP_MAP[name]);
-        deleteAccessibleMetadata(widget, name);
     } else {
         applyDescriptor(widget, ACCESSIBLE_PROP_MAP[name], newValue);
-        setAccessibleMetadata(widget, name, newValue);
     }
 };
 
-const applyChangedProps = (widget: Gtk.Accessible, oldProps: Props | null, newProps: Props): void => {
+const applyChangedProps = (widget: Gtk.Accessible, newProps: Props): void => {
     for (const name in newProps) {
         if (!isAccessibleProp(name)) {
             continue;
         }
 
-        const newValue = newProps[name];
-
-        if (oldProps?.[name] !== newValue) {
-            applyChangedProp(widget, name, newValue);
-        }
+        applyChangedProp(widget, name, newProps[name]);
     }
 };
 
@@ -312,12 +310,11 @@ const resetRemovedProps = (widget: Gtk.Accessible, oldProps: Props, newProps: Pr
         }
 
         resetDescriptor(widget, ACCESSIBLE_PROP_MAP[name]);
-        deleteAccessibleMetadata(widget, name);
     }
 };
 
 const applyAccessibleProps = (widget: Gtk.Accessible, oldProps: Props | null, newProps: Props): void => {
-    applyChangedProps(widget, oldProps, newProps);
+    applyChangedProps(widget, newProps);
 
     if (oldProps) {
         resetRemovedProps(widget, oldProps, newProps);

package/src/utils/settings.ts

@@ -3,8 +3,9 @@ import { packVariant, parseVariantType, unpackVariant, type VariantValue } from
 
 /** Maps each key of a GSettings schema to its kind: a GVariant type string, or `enum` or `flags`. */
 type SettingsSchemaKeys = Record<string, string>;
+/** Value type a key kind stands for: `number` for `enum` and `flags`, otherwise the unpacked GVariant. */
 type SettingKindValue<S extends string> = S extends "enum" | "flags" ? number : VariantValue<S>;
-/** The JavaScript type key `P` holds: `number` for `enum` and `flags`, otherwise the unpacked GVariant. */
+/** Value type of key `P`, looked up by its kind in schema `K`, that reads and writes of that key take. */
 type SettingValue<K extends SettingsSchemaKeys, P extends keyof K> = SettingKindValue<K[P] & string>;
 
 /** A GSettings schema, as described by the modules GTKX generates from a project's `.gschema.xml` files. */

package/src/utils/variant.ts

@@ -1,26 +1,45 @@
 import * as GLib from "@gtkx/gi/glib";
 
+/** JavaScript type every GVariant basic type code unpacks to. */
 type BasicValueMap = {
+    /** Boolean, held as a single byte reading 0 or 1. */
     b: boolean;
+    /** Unsigned byte. */
     y: number;
+    /** Signed 16-bit integer. */
     n: number;
+    /** Unsigned 16-bit integer. */
     q: number;
+    /** Signed 32-bit integer. */
     i: number;
+    /** Unsigned 32-bit integer. */
     u: number;
+    /** Index into the file descriptor list a message carries. */
     h: number;
+    /** Double precision floating point number. */
     d: number;
+    /** Signed 64-bit integer. */
     x: bigint;
+    /** Unsigned 64-bit integer. */
     t: bigint;
+    /** UTF-8 string, under no further constraint on what it holds. */
     s: string;
+    /** D-Bus object path. */
     o: string;
+    /** GVariant type signature. */
     g: string;
+    /** Boxed variant holding a value of any type. */
     v: GLib.Variant;
 };
 
+/** Single-character code of one of the GVariant basic types in {@link BasicValueMap}. */
 type BasicCode = keyof BasicValueMap;
+/** Parses the element type of an array, yielding the array type it produces and the rest of the string. */
 type ParseArray<S extends string> = Parse<S> extends [infer V, infer R extends string] ? [V[], R] : never;
+/** Parses the element type of a maybe, yielding the nullable type it produces and the rest of the string. */
 type ParseMaybe<S extends string> = Parse<S> extends [infer V, infer R extends string] ? [V | null, R] : never;
 
+/** Collects tuple member types into `Acc` up to the closing parenthesis, yielding them and the rest of the string. */
 type ParseTuple<S extends string, Acc extends unknown[]> = S extends `)${infer Rest}`
     ? [Acc, Rest]
     : [Parse<S>] extends [never]
@@ -29,8 +48,10 @@ type ParseTuple<S extends string, Acc extends unknown[]> = S extends `)${infer R
                 ? ParseTuple<R, [...Acc, V]>
                 : never;
 
+/** Types a dictionary entry key can hold. */
 type DictKey = string | number | bigint | boolean;
 
+/** Parses the key and value types of a dictionary entry, yielding them and the rest of the string after its brace. */
 type ParsePair<S extends string> =
     Parse<S> extends [infer K, infer R1 extends string]
         ? Parse<R1> extends [infer V, infer R2 extends string]
@@ -42,16 +63,26 @@ type ParsePair<S extends string> =
             : never
         : never;
 
+/**
+ * Parses a dictionary entry into the collection an array of those entries unpacks to, a record for string keys and a
+ * `Map` otherwise, plus the rest of the string.
+ */
 type ParseDict<S extends string> =
     ParsePair<S> extends [infer K, infer V, infer R extends string]
         ? [[K] extends [string] ? Record<string, V> : Map<K, V>, R]
         : never;
 
+/** Parses a standalone dictionary entry into a key and value pair, yielding it and the rest of the string. */
 type ParseEntry<S extends string> =
     ParsePair<S> extends [infer K, infer V, infer R extends string] ? [[K, V], R] : never;
 
+/** Parses what follows an `a` as a dictionary when it opens an entry, and as a plain array otherwise. */
 type ParseArrayOrDict<S extends string> = S extends `{${infer Rest}` ? ParseDict<Rest> : ParseArray<S>;
 
+/**
+ * Parses the type at the head of `S`, yielding the JavaScript type it unpacks to and the rest of the string, or
+ * `never` when the string is malformed.
+ */
 type Parse<S extends string> = S extends `a${infer Rest}`
     ? ParseArrayOrDict<Rest>
     : S extends `m${infer Rest}`
@@ -66,6 +97,7 @@ type Parse<S extends string> = S extends `a${infer Rest}`
                         : never
                     : never;
 
+/** JavaScript type a variant of type string `S` unpacks to, or `unknown` when `S` is not one complete type. */
 type VariantValue<S extends string> = [Parse<S>] extends [never]
     ? unknown
     : Parse<S> extends [infer V, ""]
@@ -365,4 +397,4 @@ const packVariant = (node: VariantTypeNode, value: unknown): GLib.Variant => {
     }
 };
 
-export { parseVariantType, unpackVariant, packVariant, type VariantValue, type VariantTypeNode };
+export { parseVariantType, unpackVariant, packVariant, type VariantValue };

package/dist/utils/accessible-metadata.d.ts

@@ -1,5 +0,0 @@
-declare const setAccessibleMetadata: (widget: object, name: string, value: unknown) => void;
-declare const deleteAccessibleMetadata: (widget: object, name: string) => void;
-declare const getAccessibleMetadata: (widget: object, name: string) => unknown;
-export { setAccessibleMetadata, deleteAccessibleMetadata, getAccessibleMetadata };
-//# sourceMappingURL=accessible-metadata.d.ts.map

package/dist/utils/accessible-metadata.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"accessible-metadata.d.ts","sourceRoot":"","sources":["../../src/utils/accessible-metadata.ts"],"names":[],"mappings":"AAEA,QAAA,MAAM,qBAAqB,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,EAAE,OAAO,OAAO,KAAG,IAS7E,CAAC;AAEF,QAAA,MAAM,wBAAwB,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,KAAG,IAEhE,CAAC;AAEF,QAAA,MAAM,qBAAqB,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,KAAG,OAI7D,CAAC;AAEF,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/utils/accessible-metadata.js

@@ -1,18 +0,0 @@
-const metadataStore = new WeakMap();
-const setAccessibleMetadata = (widget, name, value) => {
-    let entries = metadataStore.get(widget);
-    if (entries === undefined) {
-        entries = new Map();
-        metadataStore.set(widget, entries);
-    }
-    entries.set(name, value);
-};
-const deleteAccessibleMetadata = (widget, name) => {
-    metadataStore.get(widget)?.delete(name);
-};
-const getAccessibleMetadata = (widget, name) => {
-    const value = metadataStore.get(widget)?.get(name);
-    return value === undefined ? null : value;
-};
-export { setAccessibleMetadata, deleteAccessibleMetadata, getAccessibleMetadata };
-//# sourceMappingURL=accessible-metadata.js.map

package/dist/utils/accessible-metadata.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"accessible-metadata.js","sourceRoot":"","sources":["../../src/utils/accessible-metadata.ts"],"names":[],"mappings":"AAAA,MAAM,aAAa,GAA0C,IAAI,OAAO,EAAE,CAAC;AAE3E,MAAM,qBAAqB,GAAG,CAAC,MAAc,EAAE,IAAY,EAAE,KAAc,EAAQ,EAAE;IACjF,IAAI,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAExC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;QACpB,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC7B,CAAC,CAAC;AAEF,MAAM,wBAAwB,GAAG,CAAC,MAAc,EAAE,IAAY,EAAQ,EAAE;IACpE,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC,CAAC;AAEF,MAAM,qBAAqB,GAAG,CAAC,MAAc,EAAE,IAAY,EAAW,EAAE;IACpE,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAEnD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;AAC9C,CAAC,CAAC;AAEF,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,CAAC","sourcesContent":["const metadataStore: WeakMap<object, Map<string, unknown>> = new WeakMap();\n\nconst setAccessibleMetadata = (widget: object, name: string, value: unknown): void => {\n    let entries = metadataStore.get(widget);\n\n    if (entries === undefined) {\n        entries = new Map();\n        metadataStore.set(widget, entries);\n    }\n\n    entries.set(name, value);\n};\n\nconst deleteAccessibleMetadata = (widget: object, name: string): void => {\n    metadataStore.get(widget)?.delete(name);\n};\n\nconst getAccessibleMetadata = (widget: object, name: string): unknown => {\n    const value = metadataStore.get(widget)?.get(name);\n\n    return value === undefined ? null : value;\n};\n\nexport { setAccessibleMetadata, deleteAccessibleMetadata, getAccessibleMetadata };\n"]}

package/src/utils/accessible-metadata.ts

@@ -1,24 +0,0 @@
-const metadataStore: WeakMap<object, Map<string, unknown>> = new WeakMap();
-
-const setAccessibleMetadata = (widget: object, name: string, value: unknown): void => {
-    let entries = metadataStore.get(widget);
-
-    if (entries === undefined) {
-        entries = new Map();
-        metadataStore.set(widget, entries);
-    }
-
-    entries.set(name, value);
-};
-
-const deleteAccessibleMetadata = (widget: object, name: string): void => {
-    metadataStore.get(widget)?.delete(name);
-};
-
-const getAccessibleMetadata = (widget: object, name: string): unknown => {
-    const value = metadataStore.get(widget)?.get(name);
-
-    return value === undefined ? null : value;
-};
-
-export { setAccessibleMetadata, deleteAccessibleMetadata, getAccessibleMetadata };