@gtkx/react 1.0.0-rc.4 → 1.1.0

package/src/reconciler/behaviors.ts

@@ -1,6 +1,15 @@
 import type * as GObject from "@gtkx/gi/gobject";
 import type * as Gtk from "@gtkx/gi/gtk";
-import { getInstanceType, TYPE_INVALID, typeFromName, typeIsA } from "@gtkx/runtime";
+import {
+    type AnyClass,
+    type ApplicationClass,
+    type CommandLineApplication,
+    createApplication,
+    getClassType,
+    TYPE_INVALID,
+    typeFromName,
+    typeIsA,
+} from "@gtkx/runtime";
 import { getOrInsert, isDeepEqual, structuredClone } from "@gtkx/utils";
 import type { DetachInfo, ElementBehavior, PlaceInfo, Props } from "./registry.js";
 import { applyWrite } from "./signals.js";
@@ -36,9 +45,9 @@ type BoxLike = GObject.Object & {
 
 type RowCache = WeakMap<GObject.Object, Gtk.Widget>;
 
-type IndexedInserter = GObject.Object & {
-    remove: (child: Gtk.Widget) => void;
-    insert: (child: Gtk.Widget, position: number) => unknown;
+type IndexedChildHost<C extends GObject.Object> = GObject.Object & {
+    remove: (child: C) => void;
+    insert: (child: C, position: number) => unknown;
 };
 
 const childTypeCache: Map<string, bigint> = new Map();
@@ -50,7 +59,7 @@ const childMatcher =
         (child) => {
             const type = childTypeFor(name);
 
-            return type === TYPE_INVALID || typeIsA(getInstanceType(child), type);
+            return type === TYPE_INVALID || typeIsA(getClassType(child.constructor as AnyClass), type);
         };
 
 const slotAttach =
@@ -117,43 +126,50 @@ const teardownList = <P extends GObject.Object, I, H>(
         return;
     }
 
-    const remove = hooks.remove;
-
-    if (remove === undefined) {
-        return;
-    }
-
     for (const entry of entries) {
-        remove(object, entry.item as I, entry.handle as H);
+        hooks.remove?.(object, entry.item as I, entry.handle as H);
     }
 };
 
-const list = <P extends GObject.Object, I, H = void>(
+const listUpdate = <P extends GObject.Object, I, H>(
     prop: string,
     hooks: ListHooks<P, I, H>,
-): ElementBehavior<P> => {
+): NonNullable<ElementBehavior<P>["update"]> => {
     const { add } = hooks;
 
-    return {
-        initialize: (): ListState => ({ snapshot: [], entries: [] }),
-        update: (object, _prev, next, context) => {
-            const state = context as ListState;
-            const raw = next[prop];
-            const items: unknown[] = Array.isArray(raw) ? raw : [];
+    return (object, _prev, next, context) => {
+        const state = context as ListState;
+        const raw = next[prop];
+        const items: unknown[] = Array.isArray(raw) ? raw : [];
 
-            if (isDeepEqual(state.snapshot, items)) {
-                return [prop];
-            }
+        if (isDeepEqual(state.snapshot, items)) {
+            return [prop];
+        }
 
-            teardownList(object, state.entries, hooks);
-            state.entries = items.map((item) => ({ item, handle: add?.(object, item as I) }));
-            state.snapshot = structuredClone(items);
+        teardownList(object, state.entries, hooks);
+        state.entries = items.map((item) => ({ item, handle: add?.(object, item as I) }));
+        state.snapshot = structuredClone(items);
 
-            return [prop];
-        },
+        return [prop];
     };
 };
 
+const list = <P extends GObject.Object, I, H = void>(
+    prop: string,
+    hooks: ListHooks<P, I, H>,
+): ElementBehavior<P> => {
+    const behavior: ElementBehavior<P> = {
+        initialize: (): ListState => ({ snapshot: [], entries: [] }),
+        update: listUpdate(prop, hooks),
+    };
+
+    if (hooks.remove === undefined && hooks.clear === undefined) {
+        behavior.constructOnly = [prop];
+    }
+
+    return behavior;
+};
+
 const flushDeferred = <P extends GObject.Object, V>(
     object: GObject.Object,
     context: unknown,
@@ -244,6 +260,23 @@ const addRemoveSlot = <C extends GObject.Object, P extends GObject.Object>(
     remove: (parent: P, child: C) => void,
 ): ElementBehavior => slot<P, C>(slotName, childType, { attach: add, detach: remove });
 
+const indexedSlot = <P extends IndexedChildHost<C>, C extends GObject.Object>(
+    slotName: string,
+    childType: string,
+): ElementBehavior<P> =>
+    slot<P, C>(slotName, childType, {
+        attach: (parent, child, info) => {
+            parent.insert(child, info.index);
+        },
+        detach: (parent, child) => {
+            parent.remove(child);
+        },
+        reorder: (parent, child, info) => {
+            parent.remove(child);
+            parent.insert(child, info.index);
+        },
+    });
+
 const adoptedChildrenSlot = <P extends GObject.Object, C extends GObject.Object>(
     childType: string,
     add: (parent: P, item: C) => unknown,
@@ -275,7 +308,7 @@ const wrappedRow = <W extends Gtk.Widget>(
 
 const removeWrappedRow = (
     Wrapper: new (props: Props) => Gtk.Widget,
-    parent: IndexedInserter,
+    parent: IndexedChildHost<Gtk.Widget>,
     child: Gtk.Widget,
     rows: RowCache,
 ): void => {
@@ -286,7 +319,7 @@ const removeWrappedRow = (
     }
 };
 
-const wrappingIndexedSlot = <W extends Gtk.Widget, P extends IndexedInserter>(
+const wrappingIndexedSlot = <W extends Gtk.Widget, P extends IndexedChildHost<Gtk.Widget>>(
     Wrapper: new (props: Props) => W,
     setChild: (wrapper: W, inner: Gtk.Widget) => void,
 ): ElementBehavior<P> => ({
@@ -300,7 +333,15 @@ const wrappingIndexedSlot = <W extends Gtk.Widget, P extends IndexedInserter>(
     initialize: (): RowCache => new WeakMap(),
 });
 
+const applicationCreator = <P extends GObject.Object & CommandLineApplication, C extends Props>(
+    base: ApplicationClass<P, C>,
+): ElementBehavior<P> => ({
+    create: (props) => createApplication(base, props as C),
+});
+
 export {
+    applicationCreator,
+    childMatcher,
     slot,
     value,
     list,
@@ -311,5 +352,6 @@ export {
     boxSlot,
     addRemoveSlot,
     adoptedChildrenSlot,
+    indexedSlot,
     wrappingIndexedSlot,
 };

package/src/reconciler/devtools.ts

@@ -0,0 +1,18 @@
+type DevToolsInjectable = {
+    injectIntoDevTools: (...args: never[]) => unknown;
+};
+
+const injection = { isDone: false };
+
+const hasDevToolsHook = (): boolean => Reflect.get(globalThis, "__REACT_DEVTOOLS_GLOBAL_HOOK__") !== undefined;
+
+const injectIntoDevTools = (reconciler: DevToolsInjectable): void => {
+    if (injection.isDone || !hasDevToolsHook()) {
+        return;
+    }
+
+    injection.isDone = true;
+    reconciler.injectIntoDevTools();
+};
+
+export { injectIntoDevTools };

package/src/reconciler/host-config.ts

@@ -1,29 +1,27 @@
 import type * as GObject from "@gtkx/gi/gobject";
 import * as Gtk from "@gtkx/gi/gtk";
-import { getInstanceType, typeName } from "@gtkx/runtime";
+import { type AnyClass, getClassType, typeName } from "@gtkx/runtime";
 import { getOrInsert } from "@gtkx/utils";
 import { createContext } from "react";
 import ReactReconciler from "react-reconciler";
 import { DefaultEventPriority, DiscreteEventPriority, NoEventPriority } from "react-reconciler/constants.js";
 import type { Props } from "./registry.js";
+import packageManifest from "../../package.json" with { type: "json" };
 import { Prop } from "../components/element.js";
 import {
     applyAdoptedProps,
     applyElementProps,
-    assertConstructOnlyUnchanged,
+    assertPropsCanChange,
+    flushAccessible,
     flushBehaviors,
-    mountBehaviors,
-    unmountBehaviors,
 } from "./apply-props.js";
 import { attachChild, detachChild } from "./child-routing.js";
 import { resolveElementNode } from "./instance.js";
-import { typeInfoFor } from "./metadata.js";
 import {
     type AnyNode,
     createElementNode,
     createPropNode,
     createTextNode,
-    type Dispatch,
     ELEMENT_KIND,
     type ElementNode,
     type Instance,
@@ -50,14 +48,21 @@ type PriorityTracker = {
     withDiscrete: <T>(fn: () => T) => T;
 };
 
+const RENDERER_VERSION = packageManifest.version;
 const HOST_CONTEXT: Record<string, never> = {};
 const containerNodes: WeakMap<object, ElementNode> = new WeakMap();
 const priority = createPriorityTracker();
 
 const hostConfig = {
+    rendererPackageName: "@gtkx/react",
+    rendererVersion: RENDERER_VERSION,
     supportsMutation: true,
     supportsPersistence: false,
     supportsHydration: false,
+    supportsMicrotasks: true,
+    scheduleMicrotask: (fn: () => void): void => {
+        queueMicrotask(fn);
+    },
     isPrimaryRenderer: true,
     noTimeout: -1,
     scheduleTimeout: (fn: (...args: unknown[]) => unknown, delay?: number): ReturnType<typeof setTimeout> =>
@@ -71,18 +76,11 @@ const hostConfig = {
         attachChild(parent, child, null);
     },
     finalizeInitialChildren: (instance: Instance, _type: string, props: Props): boolean => {
-        if (instance.kind !== ELEMENT_KIND) {
-            return false;
-        }
-
-        validateContentMix(instance, props);
-
-        return typeInfoFor(instance.typeName).hasMount;
-    },
-    commitMount: (instance: Instance): void => {
         if (instance.kind === ELEMENT_KIND) {
-            mountBehaviors(instance);
+            validateContentMix(instance, props);
         }
+
+        return false;
     },
     shouldSetTextContent: (): boolean => false,
     getRootHostContext: (): Record<string, never> => HOST_CONTEXT,
@@ -92,6 +90,7 @@ const hostConfig = {
     resetAfterCommit: (): void => {
         flushTextHosts();
         flushBehaviors();
+        flushAccessible();
     },
     preparePortalMount: (): void => undefined,
     clearContainer: (): void => undefined,
@@ -135,7 +134,6 @@ const hostConfig = {
     detachDeletedInstance: (instance: Instance): void => {
         if (instance.kind === ELEMENT_KIND) {
             disconnectAllHandlers(instance);
-            unmountBehaviors(instance);
         } else if (instance.kind === LAZY_KIND && instance.adopted !== null) {
             disconnectAllHandlers(lazyTarget(instance, instance.adopted));
         }
@@ -191,14 +189,14 @@ function createPriorityTracker(): PriorityTracker {
 
 const updateInstance = (instance: Instance, prev: Props, next: Props): void => {
     if (instance.kind === ELEMENT_KIND) {
-        assertConstructOnlyUnchanged(instance.typeName, prev, next);
+        assertPropsCanChange(instance.typeName, prev, next);
         applyElementProps(instance, prev, next);
 
         return;
     }
 
     if (instance.kind === LAZY_KIND && instance.adopted !== null) {
-        assertConstructOnlyUnchanged(instance.typeName, prev, next);
+        assertPropsCanChange(instance.typeName, prev, next);
         applyAdoptedProps(lazyTarget(instance, instance.adopted), prev, next);
         instance.props = next;
     }
@@ -234,22 +232,14 @@ const setWidgetVisible = (instance: Instance, isVisible: boolean): void => {
     }
 };
 
-const runDiscrete: Dispatch = (fn) => {
-    try {
-        return priority.withDiscrete(fn);
-    } finally {
-        reconciler.flushSyncWork();
-    }
-};
-
 const adoptContainer = (container: GObject.Object): ElementNode => {
-    const name = typeName(getInstanceType(container));
+    const name = typeName(getClassType(container.constructor as AnyClass));
 
     if (name === null) {
         throw new Error("Cannot adopt a container whose GType has no registered name");
     }
 
-    return createElementNode(name, container, runDiscrete, null);
+    return createElementNode(name, container, priority.withDiscrete, null);
 };
 
 const getOrCreateContainerNode = (container: GObject.Object): ElementNode =>
@@ -260,7 +250,7 @@ const createNode = (type: string, props: Props): Instance => {
         return createPropNode(props.propName as string);
     }
 
-    const node = resolveElementNode(type, props, runDiscrete);
+    const node = resolveElementNode(type, props, priority.withDiscrete);
 
     if (node.kind === ELEMENT_KIND) {
         containerNodes.set(node.object, node);

package/src/reconciler/instance.ts

@@ -1,6 +1,6 @@
 import type * as GObject from "@gtkx/gi/gobject";
 import { getWrapperClass, TYPE_INVALID, typeFromName, typeIsA } from "@gtkx/runtime";
-import { pickBy } from "@gtkx/utils";
+import { getOrInsert, pickBy } from "@gtkx/utils";
 import type { Props } from "./registry.js";
 import { type TypeInfo, typeInfoFor } from "./metadata.js";
 import {
@@ -24,6 +24,7 @@ const CONTENT_TYPE_NAMES: { kind: ContentKind; name: string }[] = [
 ];
 
 const getContentTypes = createContentTypeCache();
+const contentKinds: Map<bigint, ContentKind | null> = new Map();
 
 function createContentTypeCache(): () => ContentType[] {
     let cached: ContentType[] | null = null;
@@ -35,7 +36,7 @@ function createContentTypeCache(): () => ContentType[] {
     };
 }
 
-const resolveContentKind = (type: bigint): ContentKind | null => {
+const findContentKind = (type: bigint): ContentKind | null => {
     for (const entry of getContentTypes()) {
         if (entry.type !== TYPE_INVALID && typeIsA(type, entry.type)) {
             return entry.kind;
@@ -45,6 +46,8 @@ const resolveContentKind = (type: bigint): ContentKind | null => {
     return null;
 };
 
+const contentKindFor = (type: bigint): ContentKind | null => getOrInsert(contentKinds, type, findContentKind);
+
 const constructInput = (info: TypeInfo, props: Props): Props =>
     pickBy(
         props,
@@ -76,7 +79,7 @@ const resolveElementNode = (typeName: string, props: Props, dispatch: Dispatch):
     const type = typeFromName(typeName);
     const object = createObject(typeName, type, constructInput(info, props));
 
-    return createElementNode(typeName, object, dispatch, resolveContentKind(type));
+    return createElementNode(typeName, object, dispatch, contentKindFor(type));
 };
 
 export { resolveElementNode };

package/src/reconciler/metadata.ts

@@ -9,9 +9,9 @@ type TypeInfo = {
     userEventSignals: Set<string>;
     behaviors: ElementBehavior[];
     deferred: Set<string>;
+    declaredConstructOnly: Set<string>;
     isLazy: boolean;
     hasFlush: boolean;
-    hasMount: boolean;
     constructOnly: Set<string>;
     construct: Set<string>;
     defaults: Record<string, unknown>;
@@ -70,11 +70,8 @@ const applyBehaviorFlags = (info: TypeInfo, behavior: ElementBehavior): void =>
         info.hasFlush = true;
     }
 
-    if (behavior.mount !== undefined) {
-        info.hasMount = true;
-    }
-
     addAll(info.deferred, deferredProps(behavior));
+    addAll(info.declaredConstructOnly, behavior.constructOnly);
 };
 
 const resolveBehaviorFlags = (info: TypeInfo): void => {
@@ -92,9 +89,9 @@ const buildTypeInfo = (name: string): TypeInfo => {
         userEventSignals: new Set(),
         behaviors: [],
         deferred: new Set(),
+        declaredConstructOnly: new Set(),
         isLazy: false,
         hasFlush: false,
-        hasMount: false,
         constructOnly: new Set(),
         construct: new Set(),
         defaults: {},

package/src/reconciler/node.ts

@@ -18,10 +18,10 @@ type SignalTarget = {
 type PlacedChild = {
     node: PlaceableNode;
     object: GObject.Object;
+    typeName: string;
     adopted: GObject.Object | null;
     slot: string;
     behavior: ElementBehavior | null;
-    isAttached: boolean;
 };
 
 type ElementNode = SignalTarget & {
@@ -111,16 +111,18 @@ const createElementNode = (
 
 const createTextNode = (text: string): TextNode => ({ kind: TEXT_KIND, text, parent: null });
 
-const nodeObject = (node: PlaceableNode): GObject.Object | null => {
-    if (node.kind === LAZY_KIND) {
-        const [child] = node.children;
-
-        return child === undefined ? null : nodeObject(child);
+const leafElement = (node: PlaceableNode): ElementNode | null => {
+    if (node.kind !== LAZY_KIND) {
+        return node;
     }
 
-    return node.object;
+    const [child] = node.children;
+
+    return child === undefined ? null : leafElement(child);
 };
 
+const nodeObject = (node: PlaceableNode): GObject.Object | null => leafElement(node)?.object ?? null;
+
 const lazyTarget = (node: LazyNode, adopted: GObject.Object): SignalTarget => ({
     object: adopted,
     handlers: node.handlers,
@@ -141,6 +143,7 @@ export {
     createLazyNode,
     createElementNode,
     createTextNode,
+    leafElement,
     nodeObject,
     lazyTarget,
     getOrCreateContext,

package/src/reconciler/placement.ts

@@ -1,6 +1,6 @@
 import * as GObject from "@gtkx/gi/gobject";
 import * as Gtk from "@gtkx/gi/gtk";
-import { getOrInsert, indexBeforeOrEnd, remove } from "@gtkx/utils";
+import { getOrInsert, indexBeforeOrEnd } from "@gtkx/utils";
 import type { DetachInfo, ElementBehavior, PlaceInfo } from "./registry.js";
 import { applyAdoptedProps, markFlush } from "./apply-props.js";
 import { typeInfoFor } from "./metadata.js";
@@ -11,7 +11,7 @@ import {
     getOrCreateContext,
     LAZY_KIND,
     lazyTarget,
-    nodeObject,
+    leafElement,
     type PlaceableNode,
     type PlacedChild,
 } from "./node.js";
@@ -21,13 +21,20 @@ import { markTextDirty } from "./text.js";
 type AttachContext = { parent: ElementNode; entry: PlacedChild; index: number; sibling: GObject.Object | null };
 
 const createEntry = (slot: string, node: PlaceableNode): PlacedChild | null => {
-    const object = nodeObject(node);
+    const leaf = leafElement(node);
 
-    if (object === null) {
+    if (leaf === null) {
         return null;
     }
 
-    return { node, object, adopted: null, slot, behavior: null, isAttached: false };
+    return {
+        node,
+        object: leaf.object,
+        typeName: leaf.typeName,
+        adopted: null,
+        slot,
+        behavior: null,
+    };
 };
 
 const siblingAt = (entries: PlacedChild[], index: number): GObject.Object | null =>
@@ -80,7 +87,6 @@ const setObjectSlot = (parent: ElementNode, entry: PlacedChild): void => {
     writeSlot(parent, entry, entry.object);
     wireBufferView(entry.node, parent);
     entry.behavior = null;
-    entry.isAttached = true;
 };
 
 const didAttach = (ctx: AttachContext, behavior: ElementBehavior): boolean => {
@@ -99,12 +105,19 @@ const didAttach = (ctx: AttachContext, behavior: ElementBehavior): boolean => {
 
     ctx.entry.behavior = behavior;
     adoptedFrom(ctx.parent, ctx.entry, behavior, claim);
-    ctx.entry.isAttached = true;
     applyLazyProps(ctx.entry);
 
     return true;
 };
 
+const unclaimedChildError = (parentTypeName: string, childTypeName: string): Error =>
+    new Error(
+        `<${childTypeName}> cannot be a child of <${parentTypeName}>. Pass it to the ` +
+        `<${parentTypeName}> prop that takes it, if there is one, portal it to rootElement with createPortal ` +
+        `if it does not belong inside <${parentTypeName}>, or register an attach behavior for ` +
+        `<${parentTypeName}> with defineElements from "@gtkx/react/config" if it belongs among its children.`,
+    );
+
 const runAttach = (parent: ElementNode, entry: PlacedChild, index: number, sibling: GObject.Object | null): void => {
     const ctx: AttachContext = { parent, entry, index, sibling };
 
@@ -114,9 +127,11 @@ const runAttach = (parent: ElementNode, entry: PlacedChild, index: number, sibli
         }
     }
 
-    if (entry.slot !== DEFAULT_SLOT) {
-        setObjectSlot(parent, entry);
+    if (entry.slot === DEFAULT_SLOT) {
+        throw unclaimedChildError(parent.typeName, entry.typeName);
     }
+
+    setObjectSlot(parent, entry);
 };
 
 const attachEntry = (parent: ElementNode, entry: PlacedChild, index: number, sibling: GObject.Object | null): void => {
@@ -136,9 +151,7 @@ const runDetach = (parent: ElementNode, entry: PlacedChild): void => {
     const behavior = entry.behavior;
 
     if (behavior === null) {
-        if (entry.slot !== DEFAULT_SLOT) {
-            writeSlot(parent, entry, null);
-        }
+        writeSlot(parent, entry, null);
 
         return;
     }
@@ -147,12 +160,6 @@ const runDetach = (parent: ElementNode, entry: PlacedChild): void => {
 };
 
 const detachEntry = (parent: ElementNode, entry: PlacedChild): void => {
-    if (!entry.isAttached) {
-        return;
-    }
-
-    entry.isAttached = false;
-
     applyWrite(() => {
         runDetach(parent, entry);
     });
@@ -174,13 +181,6 @@ const getPosition = (entries: PlacedChild[], before: PlaceableNode | null): numb
 
 const placeNew = (parent: ElementNode, entry: PlacedChild, entries: PlacedChild[], index: number): void => {
     attachEntry(parent, entry, index, siblingAt(entries, index));
-
-    if (!entry.isAttached) {
-        remove(entries, entry);
-
-        return;
-    }
-
     const isInsertedBeforeEnd = index < entries.length - 1;
     const isCannotReorderInPlace = entry.behavior !== null && entry.behavior.reorder === undefined;
 

package/src/reconciler/registry.ts

@@ -33,9 +33,9 @@ type DetachInfo = {
 
 /**
  * Customizes how one element type places children and applies props. Hooks other than `create` receive the
- * GObject instance; `update`, `flush`, `mount` and `unmount` also take the private per-node context
- * `initialize` built, and `attach`, `reorder` and `detach` read it off their info object. Subtypes inherit a
- * type's behaviors, except for `create`, which is consulted only for the type it is registered on.
+ * GObject instance; `update` and `flush` also take the private per-node context `initialize` built, and
+ * `attach`, `reorder` and `detach` read it off their info object. Subtypes inherit a type's behaviors,
+ * except for `create`, which is consulted only for the type it is registered on.
  */
 type ElementBehavior<T extends GObject.Object = GObject.Object> = {
     /** Builds the GObject from its construct props, for types whose constructor does more than set properties. */
@@ -54,12 +54,14 @@ type ElementBehavior<T extends GObject.Object = GObject.Object> = {
     update?: (object: T, prev: Props, next: Props, context: unknown) => Iterable<string> | undefined;
     /** Runs after the commit that touched the node, once every child has been placed. */
     flush?: (object: T, context: unknown) => void;
-    /** Runs once the node and its initial children are attached. */
-    mount?: (object: T, context: unknown) => void;
-    /** Runs when React deletes the node. */
-    unmount?: (object: T, context: unknown) => void;
     /** Props to withhold from the constructor, leaving them for a later hook to apply. */
     deferred?: string[];
+    /**
+     * Props the behavior can only apply while the element is being built, because the library exposes no
+     * counterpart to whatever applied them. Changing one after it has been applied throws instead of
+     * silently applying the new value on top of the old.
+     */
+    constructOnly?: string[];
 };
 
 /** A named export in a module, referenced as plain data (the module is never imported at runtime). */

package/src/reconciler/root-element.ts

@@ -1,5 +1,8 @@
 /** The type of the shared {@link rootElement} marker used as a default top-level container. */
-type RootElement = { [ROOT_ELEMENT_BRAND]: true };
+type RootElement = {
+    /** Marks a container as the top level rather than a GObject; `isRootElement` tests for it. */
+    [ROOT_ELEMENT_BRAND]: 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. */