@gtkx/react 0.21.0 → 1.0.0-rc.2

package/src/reconciler/apply-props.ts

@@ -0,0 +1,265 @@
+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 type { ElementBehavior, Props } from "./registry.js";
+import { applyAccessibleProps, isAccessibleProp } from "../utils/accessible-props.js";
+import { type TypeInfo, typeInfoFor } from "./metadata.js";
+import { type ElementNode, getOrCreateContext, type SignalTarget } from "./node.js";
+import { connectHandler, disconnectHandler } from "./signals.js";
+import { bufferText, hasSameText, isContentPaintableProp, markTextDirty, TEXT_PROP } from "./text.js";
+
+type PropDelta = { name: string; value: unknown; prevValue: unknown };
+type BehaviorUpdateContext = { node: ElementNode; prev: Props; next: Props; consumed: Set<string> };
+type PropChange = { prev: Props; next: Props };
+
+const REACT_RESERVED_PROPS = new Set(["children", "ref", "key"]);
+const NOTIFY_PREFIX = "onNotify";
+const HANDLER_PREFIX = "on";
+const flushDirty: Set<ElementNode> = new Set();
+
+const isHandlerName = (name: string): boolean => /^on[A-Z]/.test(name);
+
+const signalForProp = (info: TypeInfo, name: string): string => {
+    if (name === NOTIFY_PREFIX) {
+        return "notify";
+    }
+
+    if (name.startsWith(NOTIFY_PREFIX) && name.length > NOTIFY_PREFIX.length) {
+        return `notify::${kebabCase(name.slice(NOTIFY_PREFIX.length))}`;
+    }
+
+    return info.signals[name] ?? kebabCase(name.slice(HANDLER_PREFIX.length));
+};
+
+const isReservedName = (name: string, info: TypeInfo): boolean =>
+    REACT_RESERVED_PROPS.has(name) || isHandlerName(name) || isAccessibleProp(name) || info.constructOnly.has(name);
+
+const isSkippedValueName = (name: string, info: TypeInfo, consumed: Set<string>): boolean =>
+    isReservedName(name, info) || consumed.has(name);
+
+const writeValue = (object: GObject.Object, name: string, value: unknown): void => {
+    if (hasSameText(object, name, value)) {
+        return;
+    }
+
+    Reflect.set(object, name, value);
+};
+
+const resetPlain = (object: GObject.Object, info: TypeInfo, name: string): void => {
+    if (Object.hasOwn(info.defaults, name)) {
+        writeValue(object, name, info.defaults[name]);
+    }
+};
+
+const setOrReset = (object: GObject.Object, info: TypeInfo, name: string, value: unknown): void => {
+    if (value === undefined) {
+        resetPlain(object, info, name);
+    } else {
+        writeValue(object, name, value);
+    }
+};
+
+const applyBufferText = (buffer: Gtk.TextBuffer, text: string): void => {
+    if (bufferText(buffer) === text) {
+        return;
+    }
+
+    buffer.beginIrreversibleAction();
+    buffer.setText(text, -1);
+    buffer.endIrreversibleAction();
+};
+
+const isBufferText = (node: ElementNode, name: string): node is ElementNode & { object: Gtk.TextBuffer } =>
+    name === TEXT_PROP && node.contentKind === "buffer" && node.object instanceof Gtk.TextBuffer;
+
+const propText = (value: unknown): string => (typeof value === "string" ? value : JSON.stringify(value));
+
+const applyEntry = (node: ElementNode, info: TypeInfo, delta: PropDelta): void => {
+    const { name, value, prevValue } = delta;
+
+    if (value !== undefined && isBufferText(node, name)) {
+        applyBufferText(node.object, propText(value));
+
+        return;
+    }
+
+    if (isContentPaintableProp(node, name)) {
+        markTextDirty(node);
+
+        return;
+    }
+
+    const isInitialNull = value === null && prevValue === undefined;
+
+    if (!isInitialNull) {
+        setOrReset(node.object, info, name, value);
+    }
+};
+
+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) {
+        visit(name);
+    }
+};
+
+const constructOnlyChangeError = (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 " +
+        `changes with '${name}' and React will build a new one.`,
+    );
+
+const assertConstructOnlyUnchanged = (typeName: string, prev: Props, next: Props): void => {
+    const info = typeInfoFor(typeName);
+
+    eachChangedName(prev, next, (name) => {
+        if (!info.constructOnly.has(name) || Object.is(prev[name], next[name])) {
+            return;
+        }
+
+        throw constructOnlyChangeError(typeName, name);
+    });
+};
+
+const collectConsumed = (ctx: BehaviorUpdateContext, behavior: ElementBehavior): void => {
+    if (behavior.update === undefined) {
+        return;
+    }
+
+    const result = behavior.update(ctx.node.object, ctx.prev, ctx.next, getOrCreateContext(ctx.node, behavior));
+
+    if (result === undefined) {
+        return;
+    }
+
+    for (const name of result) {
+        ctx.consumed.add(name);
+    }
+};
+
+const runBehaviorUpdates = (node: ElementNode, info: TypeInfo, prev: Props, next: Props): Set<string> => {
+    const consumed: Set<string> = new Set();
+    const ctx: BehaviorUpdateContext = { node, prev, next, consumed };
+
+    for (const behavior of info.behaviors) {
+        collectConsumed(ctx, behavior);
+    }
+
+    return consumed;
+};
+
+const applyValueEntries = (node: ElementNode, info: TypeInfo, change: PropChange, consumed: Set<string>): void => {
+    eachChangedName(change.prev, change.next, (name) => {
+        if (isSkippedValueName(name, info, consumed) || Object.is(change.prev[name], change.next[name])) {
+            return;
+        }
+
+        applyEntry(node, info, { name, value: change.next[name], prevValue: change.prev[name] });
+    });
+};
+
+const restoreActionableSensitivity = (node: ElementNode, info: TypeInfo, prev: Props, next: Props): void => {
+    if (prev.actionName === undefined || next.actionName !== undefined) {
+        return;
+    }
+
+    const desired = "sensitive" in next ? next.sensitive : info.defaults.sensitive;
+
+    if (typeof desired === "boolean") {
+        Reflect.set(node.object, "sensitive", desired);
+    }
+};
+
+const applyHandlers = (target: SignalTarget, info: TypeInfo, prev: Props, next: Props): void => {
+    eachChangedName(prev, next, (name) => {
+        if (!isHandlerName(name)) {
+            return;
+        }
+
+        const value = next[name];
+
+        if (typeof value === "function") {
+            connectHandler(target, name, signalForProp(info, name), value as SignalHandler);
+        } else {
+            disconnectHandler(target, name);
+        }
+    });
+};
+
+const markFlush = (node: ElementNode): void => {
+    if (typeInfoFor(node.typeName).hasFlush) {
+        flushDirty.add(node);
+    }
+};
+
+const eachBehavior = (node: ElementNode, visit: (behavior: ElementBehavior, context: unknown) => void): void => {
+    for (const behavior of typeInfoFor(node.typeName).behaviors) {
+        visit(behavior, getOrCreateContext(node, behavior));
+    }
+};
+
+const flushBehaviors = (): void => {
+    drain(flushDirty, (node) => {
+        eachBehavior(node, (behavior, context) => behavior.flush?.(node.object, context));
+    });
+};
+
+const mountBehaviors = (node: ElementNode): void => {
+    if (!typeInfoFor(node.typeName).hasMount) {
+        return;
+    }
+
+    eachBehavior(node, (behavior, context) => behavior.mount?.(node.object, context));
+};
+
+const unmountBehaviors = (node: ElementNode): void => {
+    eachBehavior(node, (behavior, context) => behavior.unmount?.(node.object, context));
+};
+
+const applyAccessible = (object: GObject.Object, prev: Props, next: Props): void => {
+    if (object instanceof Gtk.Widget) {
+        applyAccessibleProps(object, prev, next);
+    }
+};
+
+const applyElementProps = (node: ElementNode, prev: Props, next: Props): void => {
+    const info = typeInfoFor(node.typeName);
+    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);
+    markFlush(node);
+    node.props = next;
+};
+
+const isSkippedAdoptedName = (info: TypeInfo, name: string): boolean => isReservedName(name, info);
+
+const applyAdoptedProps = (target: SignalTarget, prev: Props, next: Props): void => {
+    const { object, typeName } = target;
+    const info = typeInfoFor(typeName);
+
+    eachChangedName(prev, next, (name) => {
+        if (isSkippedAdoptedName(info, name) || Object.is(prev[name], next[name])) {
+            return;
+        }
+
+        setOrReset(object, info, name, next[name]);
+    });
+
+    applyAccessible(object, prev, next);
+    applyHandlers(target, info, prev, next);
+};
+
+export {
+    markFlush,
+    flushBehaviors,
+    mountBehaviors,
+    unmountBehaviors,
+    applyElementProps,
+    applyAdoptedProps,
+    assertConstructOnlyUnchanged,
+};

package/src/reconciler/behaviors.ts

@@ -0,0 +1,324 @@
+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 { getOrInsert, isDeepEqual, structuredClone } from "@gtkx/utils";
+import type { DetachInfo, ElementBehavior, PlaceInfo, Props } from "./registry.js";
+import { hasSameText } from "./text.js";
+
+type SlotHooks<P extends GObject.Object, C extends GObject.Object> = {
+    attach: (parent: P, child: C, info: PlaceInfo) => unknown;
+    detach?: (parent: P, child: C, info: DetachInfo) => void;
+    reorder?: (parent: P, child: C, info: PlaceInfo) => unknown;
+    resolve?: (parent: P, child: C) => GObject.Object | null;
+};
+
+type ValueApply<P extends GObject.Object, V> = (object: P, value: V) => void;
+
+type ListHooks<P extends GObject.Object, I, H> = {
+    add?: (parent: P, item: I) => H;
+    remove?: (parent: P, item: I, handle: H) => void;
+    clear?: (parent: P) => void;
+};
+
+type ListEntry = { item: unknown; handle: unknown };
+type ListState = { snapshot: unknown[]; entries: ListEntry[] };
+type DeferredState = { desired: unknown; present: boolean; applied: unknown };
+type CanApply<P extends GObject.Object, V> = (object: P, value: V) => boolean;
+type ChildSetter = GObject.Object & { setChild: (child: Gtk.Widget | null) => void };
+type ContentSetter<C extends Gtk.Widget> = GObject.Object & { setContent: (content: C | null) => void };
+
+type BoxLike = GObject.Object & {
+    remove: (child: Gtk.Widget) => void;
+    insertChildAfter: (child: Gtk.Widget, sibling: Gtk.Widget | null) => unknown;
+    reorderChildAfter: (child: Gtk.Widget, sibling: Gtk.Widget | null) => void;
+};
+
+type RowCache = WeakMap<GObject.Object, Gtk.Widget>;
+
+type IndexedInserter = GObject.Object & {
+    remove: (child: Gtk.Widget) => void;
+    insert: (child: Gtk.Widget, position: number) => unknown;
+};
+
+const childTypeCache: Map<string, bigint> = new Map();
+
+const childTypeFor = (name: string): bigint => getOrInsert(childTypeCache, name, typeFromName);
+
+const childMatcher =
+    (name: string): ((child: GObject.Object) => boolean) =>
+        (child) => {
+            const type = childTypeFor(name);
+
+            return type === TYPE_INVALID || typeIsA(getInstanceType(child), type);
+        };
+
+const slotAttach =
+    <P extends GObject.Object, C extends GObject.Object>(
+        slotName: string,
+        isMatch: (child: GObject.Object) => boolean,
+        attach: SlotHooks<P, C>["attach"],
+    ): NonNullable<ElementBehavior["attach"]> =>
+        (object, child, info) => {
+            if (info.slot !== slotName || !isMatch(child)) {
+                return;
+            }
+
+            return attach(object as P, child as C, info) ?? true;
+        };
+
+/** Builds a behavior for a named child slot holding children of `childType`, claiming matches only. */
+const slot = <P extends GObject.Object, C extends GObject.Object>(
+    slotName: string,
+    childType: string,
+    hooks: SlotHooks<P, C>,
+): ElementBehavior => {
+    const matches = childMatcher(childType);
+    const { attach, detach, reorder, resolve } = hooks;
+    const behavior: ElementBehavior = { attach: slotAttach(slotName, matches, attach) };
+
+    if (reorder !== undefined) {
+        behavior.reorder = (object, child, info) => reorder(object as P, child as C, info) ?? true;
+    }
+
+    if (detach !== undefined) {
+        behavior.detach = (object, child, info) => {
+            detach(object as P, child as C, info);
+        };
+    }
+
+    if (resolve !== undefined) {
+        behavior.resolve = (object, child) => resolve(object as P, child as C);
+    }
+
+    return behavior;
+};
+
+/** Builds a scalar-prop behavior that invokes `apply` whenever the value changes, and claims the prop. */
+const value = <P extends GObject.Object, V>(
+    prop: string,
+    apply: ValueApply<P, V>,
+): ElementBehavior<P> => ({
+    update: (object, prev, next) => {
+        if (!Object.is(prev[prop], next[prop]) && next[prop] !== undefined) {
+            apply(object, next[prop] as V);
+        }
+
+        return [prop];
+    },
+});
+
+const teardownList = <P extends GObject.Object, I, H>(
+    object: P,
+    entries: ListEntry[],
+    hooks: ListHooks<P, I, H>,
+): void => {
+    if (hooks.clear !== undefined) {
+        hooks.clear(object);
+
+        return;
+    }
+
+    const remove = hooks.remove;
+
+    if (remove === undefined) {
+        return;
+    }
+
+    for (const entry of entries) {
+        remove(object, entry.item as I, entry.handle as H);
+    }
+};
+
+/**
+ * Builds an array-prop behavior that adds, removes, and clears its items, reapplying on structural
+ * change. `add` may return a handle that the same item's later `remove` receives, for items whose
+ * teardown needs what `add` produced (as VFL constraints need the objects the layout created).
+ */
+const list = <P extends GObject.Object, I, H = void>(
+    prop: string,
+    hooks: ListHooks<P, I, H>,
+): ElementBehavior<P> => {
+    const { add } = hooks;
+
+    return {
+        createContext: (): ListState => ({ snapshot: [], entries: [] }),
+        update: (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];
+            }
+
+            teardownList(object, state.entries, hooks);
+            state.entries = items.map((item) => ({ item, handle: add?.(object, item as I) }));
+            state.snapshot = structuredClone(items);
+
+            return [prop];
+        },
+    };
+};
+
+const flushDeferred = <P extends GObject.Object, V>(
+    object: GObject.Object,
+    context: unknown,
+    prop: string,
+    canApply: CanApply<P, V> | undefined,
+): void => {
+    const state = context as DeferredState;
+
+    if (!state.present || Object.is(state.applied, state.desired)) {
+        return;
+    }
+
+    if (canApply !== undefined && !canApply(object as P, state.desired as V)) {
+        return;
+    }
+
+    Reflect.set(object, prop, state.desired);
+    state.applied = state.desired;
+};
+
+/** Builds a behavior for a prop applied after the surrounding commit, deferred until `canApply` returns true. */
+const deferred = <P extends GObject.Object, V>(
+    prop: string,
+    canApply?: CanApply<P, V>,
+): ElementBehavior<P> => ({
+    deferred: [prop],
+    createContext: (): DeferredState => ({ desired: undefined, present: false, applied: undefined }),
+    update: (_object, _prev, next, context) => {
+        const state = context as DeferredState;
+        state.desired = next[prop];
+        state.present = next[prop] !== undefined;
+
+        return [prop];
+    },
+    flush: (object, context) => {
+        flushDeferred(object, context, prop, canApply);
+    },
+});
+
+/** Builds a behavior for a text prop kept in controlled-input sync: set when provided, never reset. */
+const controlledText = (prop: string): ElementBehavior =>
+    value(prop, (object, next) => {
+        if (!hasSameText(object, prop, next)) {
+            Reflect.set(object, prop, next);
+        }
+    });
+
+/** Behavior for a container that installs its single child with `setChild`. */
+const childSetterSlot = <P extends ChildSetter>(): ElementBehavior<P> =>
+    slot<P, Gtk.Widget>("children", "GtkWidget", {
+        attach: (parent, child) => {
+            parent.setChild(child);
+        },
+        detach: (parent) => {
+            parent.setChild(null);
+        },
+    });
+
+/** Behavior for a container that installs its single child with `setContent`. */
+const contentSetterSlot = <P extends ContentSetter<C>, C extends Gtk.Widget = Gtk.Widget>(
+    childType = "GtkWidget",
+): ElementBehavior<P> =>
+    slot<P, C>("children", childType, {
+        attach: (parent, child) => {
+            parent.setContent(child);
+        },
+        detach: (parent) => {
+            parent.setContent(null);
+        },
+    });
+
+/** Behavior for a `GtkBox`-style container that orders children by sibling. */
+const boxSlot = <P extends BoxLike>(): ElementBehavior<P> =>
+    slot<P, Gtk.Widget>("children", "GtkWidget", {
+        attach: (box, child, info) => box.insertChildAfter(child, info.sibling as Gtk.Widget | null),
+        detach: (box, child) => {
+            box.remove(child);
+        },
+        reorder: (box, child, info) => {
+            box.reorderChildAfter(child, info.sibling as Gtk.Widget | null);
+        },
+    });
+
+/** Behavior for a container whose children are added and removed by a pair of methods. */
+const addRemoveSlot = <C extends GObject.Object, P extends GObject.Object>(
+    slotName: string,
+    childType: string,
+    add: (parent: P, child: C) => unknown,
+    remove: (parent: P, child: C) => void,
+): ElementBehavior => slot<P, C>(slotName, childType, { attach: add, detach: remove });
+
+/** Behavior for a `children` slot whose attach call returns the page object the container adopts. */
+const adoptedChildrenSlot = <P extends GObject.Object, C extends GObject.Object>(
+    childType: string,
+    add: (parent: P, item: C) => unknown,
+    remove: (parent: P, item: C) => void,
+): ElementBehavior => addRemoveSlot<C, P>("children", childType, add, remove);
+
+const wrappedRow = <W extends Gtk.Widget>(
+    Wrapper: new (props: Props) => W,
+    setChild: (wrapper: W, inner: Gtk.Widget) => void,
+    rows: RowCache,
+    child: Gtk.Widget,
+): Gtk.Widget => {
+    if (child instanceof Wrapper) {
+        return child;
+    }
+
+    const existing = rows.get(child);
+
+    if (existing !== undefined) {
+        return existing;
+    }
+
+    const wrapper = new Wrapper({});
+    setChild(wrapper, child);
+    rows.set(child, wrapper);
+
+    return wrapper;
+};
+
+const removeWrappedRow = (
+    Wrapper: new (props: Props) => Gtk.Widget,
+    parent: IndexedInserter,
+    child: Gtk.Widget,
+    rows: RowCache,
+): void => {
+    const row = child instanceof Wrapper ? child : rows.get(child);
+
+    if (row !== undefined) {
+        parent.remove(row);
+    }
+};
+
+/** Behavior for an index-placed container that wraps each child in `Wrapper` before adding it. */
+const wrappingIndexedSlot = <W extends Gtk.Widget, P extends IndexedInserter>(
+    Wrapper: new (props: Props) => W,
+    setChild: (wrapper: W, inner: Gtk.Widget) => void,
+): ElementBehavior<P> => ({
+    ...slot<P, Gtk.Widget>("children", "GtkWidget", {
+        attach: (parent, child, info) =>
+            parent.insert(wrappedRow(Wrapper, setChild, info.context as RowCache, child), info.index),
+        detach: (parent, child, info) => {
+            removeWrappedRow(Wrapper, parent, child, info.context as RowCache);
+        },
+    }),
+    createContext: (): RowCache => new WeakMap(),
+});
+
+export {
+    slot,
+    value,
+    list,
+    deferred,
+    controlledText,
+    childSetterSlot,
+    contentSetterSlot,
+    boxSlot,
+    addRemoveSlot,
+    adoptedChildrenSlot,
+    wrappingIndexedSlot,
+};