@gtkx/react 0.21.0 → 1.0.0-rc.2

package/src/reconciler/node.ts

@@ -0,0 +1,161 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { SignalHandler } from "@gtkx/runtime";
+import { getOrInsert } from "@gtkx/utils";
+import type { ElementBehavior, Props } from "./registry.js";
+
+type ContentKind = "label" | "buffer" | "tag" | "anchor";
+type HandlerRecord = { signal: string; handler: SignalHandler; wrapped: SignalHandler; blockable: boolean };
+type Dispatch = (fn: () => unknown) => unknown;
+
+type SignalTarget = {
+    object: GObject.Object;
+    handlers: Map<string, HandlerRecord>;
+    typeName: string;
+    dispatch: Dispatch;
+};
+
+type PlacedChild = {
+    node: PlaceableNode;
+    object: GObject.Object;
+    adopted: GObject.Object | null;
+    slot: string;
+    behavior: ElementBehavior | null;
+    attached: boolean;
+};
+
+type ElementNode = SignalTarget & {
+    kind: typeof ELEMENT_KIND;
+    props: Props;
+    placements: Map<string, PlacedChild[]>;
+    contexts: Map<ElementBehavior, unknown>;
+    parent: ParentNode | null;
+    content: ContentChild[];
+    contentKind: ContentKind | null;
+    bufferView: Gtk.TextView | null;
+};
+
+type PropNode = {
+    kind: typeof PROP_KIND;
+    slot: string;
+    children: PlaceableNode[];
+    parent: ElementNode | null;
+};
+
+type LazyNode = {
+    kind: typeof LAZY_KIND;
+    typeName: string;
+    props: Props;
+    children: PlaceableNode[];
+    parent: ElementNode | null;
+    adopted: GObject.Object | null;
+    handlers: Map<string, HandlerRecord>;
+    dispatch: Dispatch;
+};
+
+type TextNode = {
+    kind: typeof TEXT_KIND;
+    text: string;
+    parent: ParentNode | null;
+};
+
+type PlaceableNode = ElementNode | LazyNode;
+type ParentNode = ElementNode | PropNode | LazyNode;
+type ContentChild = TextNode | ElementNode;
+type Instance = ElementNode | PropNode | LazyNode;
+type AnyNode = Instance | TextNode;
+
+const ELEMENT_KIND = "element";
+const PROP_KIND = "prop";
+const TEXT_KIND = "text";
+const LAZY_KIND = "lazy";
+const DEFAULT_SLOT = "children";
+
+const createPropNode = (slot: string): PropNode => ({
+    kind: PROP_KIND,
+    slot,
+    children: [],
+    parent: null,
+});
+
+const createLazyNode = (typeName: string, props: Props, dispatch: Dispatch): LazyNode => ({
+    kind: LAZY_KIND,
+    typeName,
+    props,
+    children: [],
+    parent: null,
+    adopted: null,
+    handlers: new Map(),
+    dispatch,
+});
+
+const createElementNode = (
+    typeName: string,
+    object: GObject.Object,
+    dispatch: Dispatch,
+    contentKind: ContentKind | null,
+): ElementNode => ({
+    kind: ELEMENT_KIND,
+    typeName,
+    object,
+    props: {},
+    handlers: new Map(),
+    placements: new Map(),
+    contexts: new Map(),
+    parent: null,
+    content: [],
+    contentKind,
+    bufferView: null,
+    dispatch,
+});
+
+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);
+    }
+
+    return node.object;
+};
+
+const lazyTarget = (node: LazyNode, adopted: GObject.Object): SignalTarget => ({
+    object: adopted,
+    handlers: node.handlers,
+    typeName: node.typeName,
+    dispatch: node.dispatch,
+});
+
+const getOrCreateContext = (node: ElementNode, behavior: ElementBehavior): unknown =>
+    getOrInsert(node.contexts, behavior, () => behavior.createContext?.(node.object));
+
+export {
+    ELEMENT_KIND,
+    PROP_KIND,
+    TEXT_KIND,
+    LAZY_KIND,
+    DEFAULT_SLOT,
+    createPropNode,
+    createLazyNode,
+    createElementNode,
+    createTextNode,
+    nodeObject,
+    lazyTarget,
+    getOrCreateContext,
+    type ContentKind,
+    type HandlerRecord,
+    type Dispatch,
+    type SignalTarget,
+    type PlacedChild,
+    type ElementNode,
+    type PropNode,
+    type LazyNode,
+    type TextNode,
+    type PlaceableNode,
+    type ParentNode,
+    type ContentChild,
+    type Instance,
+    type AnyNode,
+};

package/src/reconciler/placement.ts

@@ -0,0 +1,255 @@
+import * as GObject from "@gtkx/gi/gobject";
+import * as Gtk from "@gtkx/gi/gtk";
+import { getOrInsert, indexBeforeOrEnd, remove } from "@gtkx/utils";
+import type { DetachInfo, ElementBehavior, PlaceInfo } from "./registry.js";
+import { applyAdoptedProps, markFlush } from "./apply-props.js";
+import { typeInfoFor } from "./metadata.js";
+import {
+    DEFAULT_SLOT,
+    ELEMENT_KIND,
+    type ElementNode,
+    getOrCreateContext,
+    LAZY_KIND,
+    lazyTarget,
+    nodeObject,
+    type PlaceableNode,
+    type PlacedChild,
+} from "./node.js";
+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);
+
+    if (object === null) {
+        return null;
+    }
+
+    return { node, object, adopted: null, slot, behavior: null, attached: false };
+};
+
+const siblingAt = (entries: PlacedChild[], index: number): GObject.Object | null =>
+    index > 0 ? (entries[index - 1]?.object ?? null) : null;
+
+const placeInfo = (entry: PlacedChild, index: number, sibling: GObject.Object | null, context: unknown): PlaceInfo => ({
+    slot: entry.slot,
+    index,
+    sibling,
+    adopted: entry.adopted,
+    props: entry.node.props,
+    context,
+});
+
+const adoptedFrom = (parent: ElementNode, entry: PlacedChild, behavior: ElementBehavior, claim: unknown): void => {
+    if (behavior.resolve !== undefined) {
+        entry.adopted = behavior.resolve(parent.object, entry.object);
+
+        return;
+    }
+
+    entry.adopted = claim instanceof GObject.Object ? claim : null;
+};
+
+const applyLazyProps = (entry: PlacedChild): void => {
+    if (entry.node.kind !== LAZY_KIND || entry.adopted === null) {
+        return;
+    }
+
+    applyAdoptedProps(lazyTarget(entry.node, entry.adopted), {}, entry.node.props);
+    entry.node.adopted = entry.adopted;
+};
+
+const wireBufferView = (node: PlaceableNode, parent: ElementNode): void => {
+    if (!(node.kind === ELEMENT_KIND && node.contentKind === "buffer" && parent.object instanceof Gtk.TextView)) {
+        return;
+    }
+
+    node.bufferView = parent.object;
+    markTextDirty(node);
+};
+
+const setObjectSlot = (parent: ElementNode, entry: PlacedChild): void => {
+    Reflect.set(parent.object, entry.slot, entry.object);
+    wireBufferView(entry.node, parent);
+    entry.behavior = null;
+    entry.attached = true;
+};
+
+const didAttach = (ctx: AttachContext, behavior: ElementBehavior): boolean => {
+    const attach = behavior.attach;
+
+    if (attach === undefined) {
+        return false;
+    }
+
+    const context = getOrCreateContext(ctx.parent, behavior);
+    const claim = attach(ctx.parent.object, ctx.entry.object, placeInfo(ctx.entry, ctx.index, ctx.sibling, context));
+
+    if (claim === undefined) {
+        return false;
+    }
+
+    ctx.entry.behavior = behavior;
+    adoptedFrom(ctx.parent, ctx.entry, behavior, claim);
+    ctx.entry.attached = true;
+    applyLazyProps(ctx.entry);
+
+    return true;
+};
+
+const attachEntry = (parent: ElementNode, entry: PlacedChild, index: number, sibling: GObject.Object | null): void => {
+    const ctx: AttachContext = { parent, entry, index, sibling };
+
+    for (const behavior of typeInfoFor(parent.typeName).behaviors) {
+        if (didAttach(ctx, behavior)) {
+            return;
+        }
+    }
+
+    if (entry.slot !== DEFAULT_SLOT) {
+        setObjectSlot(parent, entry);
+    }
+};
+
+const detachInfo = (entry: PlacedChild, context: unknown): DetachInfo => ({
+    slot: entry.slot,
+    adopted: entry.adopted,
+    props: entry.node.props,
+    context,
+});
+
+const detachEntry = (parent: ElementNode, entry: PlacedChild): void => {
+    if (!entry.attached) {
+        return;
+    }
+
+    entry.attached = false;
+    const behavior = entry.behavior;
+
+    if (behavior === null) {
+        if (entry.slot !== DEFAULT_SLOT) {
+            Reflect.set(parent.object, entry.slot, null);
+        }
+
+        return;
+    }
+
+    behavior.detach?.(parent.object, entry.object, detachInfo(entry, getOrCreateContext(parent, behavior)));
+};
+
+const rebuild = (parent: ElementNode, entries: PlacedChild[]): void => {
+    for (const entry of entries) {
+        detachEntry(parent, entry);
+    }
+
+    for (const [index, entry] of entries.entries()) {
+        entry.behavior = null;
+        attachEntry(parent, entry, index, siblingAt(entries, index));
+    }
+};
+
+const getPosition = (entries: PlacedChild[], before: PlaceableNode | null): number =>
+    indexBeforeOrEnd(entries, before, (entry, target) => entry.node === target);
+
+const placeNew = (parent: ElementNode, entry: PlacedChild, entries: PlacedChild[], index: number): void => {
+    attachEntry(parent, entry, index, siblingAt(entries, index));
+
+    if (!entry.attached) {
+        remove(entries, entry);
+
+        return;
+    }
+
+    const isInsertedBeforeEnd = index < entries.length - 1;
+    const isCannotReorderInPlace = entry.behavior !== null && entry.behavior.reorder === undefined;
+
+    if (isInsertedBeforeEnd && isCannotReorderInPlace) {
+        rebuild(parent, entries);
+    }
+};
+
+const moveEntry = (parent: ElementNode, entry: PlacedChild, entries: PlacedChild[], index: number): void => {
+    const behavior = entry.behavior;
+    const reorder = behavior?.reorder;
+
+    if (behavior === null || reorder === undefined) {
+        rebuild(parent, entries);
+
+        return;
+    }
+
+    const context = getOrCreateContext(parent, behavior);
+    const claim = reorder(parent.object, entry.object, placeInfo(entry, index, siblingAt(entries, index), context));
+    adoptedFrom(parent, entry, behavior, claim);
+    applyLazyProps(entry);
+};
+
+const resolveEntry = (
+    entries: PlacedChild[],
+    existing: number,
+    slot: string,
+    node: PlaceableNode,
+): PlacedChild | null => {
+    if (existing >= 0) {
+        return entries[existing] ?? null;
+    }
+
+    return createEntry(slot, node);
+};
+
+const placeChild = (
+    parent: ElementNode,
+    slot: string,
+    node: PlaceableNode,
+    before: PlaceableNode | null,
+): void => {
+    const entries = getOrInsert(parent.placements, slot, () => []);
+    const existing = entries.findIndex((entry) => entry.node === node);
+    const entry = resolveEntry(entries, existing, slot, node);
+
+    if (entry === null) {
+        return;
+    }
+
+    const isMove = existing !== -1;
+
+    if (isMove) {
+        entries.splice(existing, 1);
+    }
+
+    const index = getPosition(entries, before);
+    entries.splice(index, 0, entry);
+
+    if (isMove) {
+        moveEntry(parent, entry, entries, index);
+    } else {
+        placeNew(parent, entry, entries, index);
+    }
+
+    markFlush(parent);
+};
+
+const unplaceChild = (parent: ElementNode, slot: string, node: PlaceableNode): void => {
+    const entries = parent.placements.get(slot);
+
+    if (entries === undefined) {
+        return;
+    }
+
+    const index = entries.findIndex((entry) => entry.node === node);
+
+    if (index === -1) {
+        return;
+    }
+
+    const [entry] = entries.splice(index, 1);
+
+    if (entry !== undefined) {
+        detachEntry(parent, entry);
+    }
+
+    markFlush(parent);
+};
+
+export { placeChild, unplaceChild };

package/src/reconciler/registry.ts

@@ -0,0 +1,161 @@
+import type * as GObject from "@gtkx/gi/gobject";
+
+/** The props of a host element or node, as React passes them through the reconciler. */
+type Props = Record<string, unknown>;
+
+/** Per-child values a slot hook receives while placing or moving one child. */
+type PlaceInfo = {
+    slot: string;
+    index: number;
+    sibling: GObject.Object | null;
+    adopted: GObject.Object | null;
+    props: Props;
+    context: unknown;
+};
+
+/** Per-child values a slot hook receives while removing one child. */
+type DetachInfo = {
+    slot: string;
+    adopted: GObject.Object | null;
+    props: Props;
+    context: unknown;
+};
+
+/**
+ * Customizes how one element type places children and applies props. Every hook receives the
+ * GObject instance and a private per-node `context` built once by `createContext`. A slot hook
+ * claims a child by returning a non-`undefined` value; that value, or `resolve`, is the object
+ * the container adopts for the child. `update` returns the prop names it consumed so those props
+ * are not also set as plain GObject properties. `create` builds the GObject for types whose
+ * constructor does more than set properties, and is consulted for its own type only, never
+ * inherited by subtypes.
+ */
+type ElementBehavior<T extends GObject.Object = GObject.Object> = {
+    create?: (props: Props) => GObject.Object;
+    createContext?: (object: T) => unknown;
+    attach?: (object: T, child: GObject.Object, info: PlaceInfo) => unknown;
+    reorder?: (object: T, child: GObject.Object, info: PlaceInfo) => unknown;
+    detach?: (object: T, child: GObject.Object, info: DetachInfo) => void;
+    resolve?: (object: T, child: GObject.Object) => GObject.Object | null;
+    update?: (object: T, prev: Props, next: Props, context: unknown) => Iterable<string> | undefined;
+    flush?: (object: T, context: unknown) => void;
+    mount?: (object: T, context: unknown) => void;
+    unmount?: (object: T, context: unknown) => void;
+    deferred?: string[];
+};
+
+/** A named export in a module, referenced as plain data (the module is never imported at runtime). */
+type ModuleExport = { module: string; export: string };
+
+/**
+ * Per-element configuration keyed by GLib type name: whether the element is lazy (its GObject is
+ * created by its parent container, as pages and layout children are), the custom behaviors bound to
+ * its type, an optional component that wraps the generated element, and the base props interface its
+ * generated props extend. `component` and `props` are inert at runtime; they are read only by codegen.
+ */
+type ElementConfig<T extends GObject.Object = GObject.Object> = {
+    lazy?: boolean;
+    behaviors?: ElementBehavior<T>[];
+    component?: ModuleExport;
+    props?: ModuleExport;
+};
+
+/**
+ * Every registered element config, keyed by GLib type name. Adwaita entries appear once `@gtkx/react/adw`
+ * is loaded.
+ */
+const ELEMENTS: Record<string, ElementConfig> = {};
+
+/** Props a behavior applies after construction; the constructor is never given them. */
+const deferredProps = (behavior: ElementBehavior): string[] => behavior.deferred ?? [];
+
+const mergeBehaviors = (base: ElementConfig, added: ElementBehavior[], isPrepended: boolean): ElementBehavior[] => {
+    const baseBehaviors = base.behaviors ?? [];
+
+    return isPrepended ? [...added, ...baseBehaviors] : [...baseBehaviors, ...added];
+};
+
+const mergeConfigEntry = (base: ElementConfig, added: ElementConfig<never>, isPrepended = false): ElementConfig => {
+    const entry: ElementConfig = { ...base };
+
+    if (added.behaviors !== undefined) {
+        entry.behaviors = mergeBehaviors(entry, added.behaviors as ElementBehavior[], isPrepended);
+    }
+
+    if (added.lazy === true) {
+        entry.lazy = true;
+    }
+
+    if (added.component !== undefined) {
+        entry.component = added.component;
+    }
+
+    if (added.props !== undefined) {
+        entry.props = added.props;
+    }
+
+    return entry;
+};
+
+/**
+ * Merges maps of {@link ElementConfig} keyed by GLib type name into one, concatenating each type's
+ * behaviors in the order the maps are given (an earlier map's behaviors come first) and taking the last
+ * lazy flag, component, and props seen. Use it to combine an app's element config with its behaviors.
+ */
+const mergeElementConfigs = (...maps: Record<string, ElementConfig<never>>[]): Record<string, ElementConfig> => {
+    const merged: Record<string, ElementConfig> = {};
+
+    for (const map of maps) {
+        for (const [type, config] of Object.entries(map)) {
+            merged[type] = mergeConfigEntry(merged[type] ?? {}, config);
+        }
+    }
+
+    return merged;
+};
+
+/**
+ * Registers a map of {@link ElementConfig} keyed by GLib type name, merging each entry into the
+ * registry. Behaviors are appended by default (the framework's built-ins register this way); pass
+ * `{ prepend: true }` for an app's own configuration so its behaviors are consulted before the
+ * built-ins for the same slot, letting it override them regardless of registration order.
+ */
+const registerElements = (
+    map: Record<string, ElementConfig<never>>,
+    options: { prepend?: boolean } = {},
+): void => {
+    for (const [type, config] of Object.entries(map)) {
+        ELEMENTS[type] = mergeConfigEntry(ELEMENTS[type] ?? {}, config, options.prepend === true);
+    }
+};
+
+/**
+ * Identity helper that types the module named by the `elements` entry of `gtkx.config.ts`, enabling
+ * editor autocompletion and type checking. Key each entry by GLib type name and annotate each hook's
+ * object parameter with the concrete GObject class the behavior applies to.
+ */
+const defineElements = (elements: Record<string, ElementConfig<never>>): Record<string, ElementConfig<never>> =>
+    elements;
+
+/** Spreads one config across many GLib type names. */
+const forTypes = (types: string[], config: ElementConfig<never>): Record<string, ElementConfig<never>> =>
+    Object.fromEntries(types.map((type) => [type, config]));
+
+/** References a base props interface exported from `@gtkx/react/internal`. */
+const internal = (name: string): ModuleExport => ({ module: "@gtkx/react/internal", export: name });
+
+export {
+    ELEMENTS,
+    deferredProps,
+    mergeElementConfigs,
+    registerElements,
+    defineElements,
+    forTypes,
+    internal,
+    type Props,
+    type PlaceInfo,
+    type DetachInfo,
+    type ElementBehavior,
+    type ModuleExport,
+    type ElementConfig,
+};

package/src/reconciler/root-element.ts

@@ -0,0 +1,12 @@
+/** The type of the shared {@link rootElement} marker used as a default top-level container. */
+type RootElement = { [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. */
+const rootElement: RootElement = { [ROOT_ELEMENT_BRAND]: true };
+
+/** Reports whether an arbitrary value is a {@link rootElement} marker. */
+const isRootElement = (value: unknown): value is RootElement =>
+    typeof value === "object" && value !== null && Object.hasOwn(value, ROOT_ELEMENT_BRAND);
+
+export { rootElement, isRootElement, type RootElement };