@gtkx/react 0.18.9 → 0.20.0

package/src/host-config.ts

@@ -1,3 +1,4 @@
+import { freeze, unfreeze } from "@gtkx/ffi";
 import type * as Gtk from "@gtkx/ffi/gtk";
 import React from "react";
 import type ReactReconciler from "react-reconciler";
@@ -72,6 +73,8 @@ export function createHostConfig(): HostConfig {
         supportsMutation: true,
         supportsPersistence: false,
         supportsHydration: false,
+        supportsMicrotasks: true,
+        scheduleMicrotask: (fn: () => unknown) => queueMicrotask(fn),
         isPrimaryRenderer: true,
         noTimeout: -1,
         getRootHostContext: () => ({}),
@@ -93,22 +96,42 @@ export function createHostConfig(): HostConfig {
             if (hostContext.insideTextBuffer) {
                 const props = { text };
                 const node = createNode("TextSegment", props, undefined, rootContainer);
-                node.commitUpdate(null, props);
+                node.signalStore.blockAll();
+                try {
+                    node.commitUpdate(null, props);
+                } finally {
+                    node.signalStore.unblockAll();
+                }
                 return node;
             }
             const props = { label: text };
             const node = createNode("GtkLabel", props, undefined, rootContainer);
-            node.commitUpdate(null, props);
+            node.signalStore.blockAll();
+            try {
+                node.commitUpdate(null, props);
+            } finally {
+                node.signalStore.unblockAll();
+            }
             return node;
         },
         appendInitialChild: (parent, child) => {
             parent.appendInitialChild(child);
         },
         finalizeInitialChildren: (instance, _type, props) => {
-            return instance.finalizeInitialChildren(props);
+            instance.signalStore.blockAll();
+            try {
+                return instance.finalizeInitialChildren(props);
+            } finally {
+                instance.signalStore.unblockAll();
+            }
         },
         commitUpdate: (instance, _type, oldProps, newProps) => {
-            instance.commitUpdate(oldProps, newProps);
+            instance.signalStore.blockAll();
+            try {
+                instance.commitUpdate(oldProps, newProps);
+            } finally {
+                instance.signalStore.unblockAll();
+            }
         },
         commitMount: (instance) => {
             instance.commitMount();
@@ -135,14 +158,22 @@ export function createHostConfig(): HostConfig {
             parent.insertBefore(child, beforeChild);
         },
         prepareForCommit: () => {
+            freeze();
             return null;
         },
-        resetAfterCommit: () => {},
+        resetAfterCommit: () => {
+            unfreeze();
+        },
         commitTextUpdate: (textInstance, oldText, newText) => {
-            if (textInstance.typeName === "TextSegment") {
-                textInstance.commitUpdate({ text: oldText }, { text: newText });
-            } else {
-                textInstance.commitUpdate({ label: oldText }, { label: newText });
+            textInstance.signalStore.blockAll();
+            try {
+                if (textInstance.typeName === "TextSegment") {
+                    textInstance.commitUpdate({ text: oldText }, { text: newText });
+                } else {
+                    textInstance.commitUpdate({ label: oldText }, { label: newText });
+                }
+            } finally {
+                textInstance.signalStore.unblockAll();
             }
         },
         clearContainer: () => {},
@@ -165,7 +196,9 @@ export function createHostConfig(): HostConfig {
         afterActiveInstanceBlur: () => {},
         prepareScopeUpdate: () => {},
         getInstanceFromScope: () => null,
-        detachDeletedInstance: (instance) => instance.detachDeletedInstance(),
+        detachDeletedInstance: (instance) => {
+            instance.detachDeletedInstance();
+        },
         resetFormInstance: () => {},
         requestPostPaintCallback: () => {},
         shouldAttemptEagerTransition: () => false,

package/src/jsx.ts

@@ -132,15 +132,15 @@ export type AnimationProps = {
 /**
  * Props for the Shortcut virtual element.
  *
- * Defines a keyboard shortcut. Must be a child of `x.ShortcutController`.
+ * Defines a keyboard shortcut. Must be a child of `<GtkShortcutController>`.
  *
  * @example
  * ```tsx
- * <x.ShortcutController>
+ * <GtkShortcutController>
  *     <x.Shortcut trigger="<Control>s" onActivate={save} />
  *     <x.Shortcut trigger={["F5", "<Control>r"]} onActivate={refresh} />
  *     <x.Shortcut trigger="Escape" onActivate={cancel} disabled={!canCancel} />
- * </x.ShortcutController>
+ * </GtkShortcutController>
  * ```
  */
 export type ShortcutProps = {
@@ -174,6 +174,8 @@ export type ShortcutProps = {
  * ```
  */
 export type TextAnchorProps = {
+    /** Replacement character displayed when the widget is not visible (e.g. in serialized text) */
+    replacementChar?: string;
     /** The widget to embed at this anchor position */
     children?: ReactNode;
 };
@@ -359,8 +361,6 @@ export type ContainerSlotNames = {
 
 /**
  * Props for method-based container slot child positioning.
- *
- * @see {@link x.ContainerSlot} for type-safe usage
  */
 export type ContainerSlotProps = {
     /** The method name to call on the parent widget */
@@ -370,28 +370,36 @@ export type ContainerSlotProps = {
 };
 
 /**
- * Props for items in a GtkListView, GtkGridView, or GtkColumnView.
+ * A data item for list/grid/column views and dropdowns.
+ *
+ * Uses a discriminated union on the `section` field:
+ * - Regular items have `value: T` and optional tree-mode properties
+ * - Section headers have `value: S`, `section: true`, and required `children`
  *
- * When used inside a GtkListView, items can be nested to create tree hierarchies.
- * Tree-specific props (`indentForDepth`, `indentForIcon`, `hideExpander`) only
- * apply when items are used inside a GtkListView with nested children.
+ * Mode is detected from data shape:
+ * - Any item has `section: true` → section mode
+ * - Any item has non-empty `children` (without `section`) → tree mode
+ * - Otherwise → flat mode
  *
- * @typeParam T - The type of data associated with this list item
+ * @typeParam T - The type of data for regular items
+ * @typeParam S - The type of data for section headers
  */
-export type ListItemProps<T = unknown> = {
-    /** Unique identifier for this item */
-    id: string;
-    /** The data value for this item */
-    value: T;
-    /** Whether to indent based on tree depth (default: true) */
-    indentForDepth?: boolean;
-    /** Whether to indent for expander icon width */
-    indentForIcon?: boolean;
-    /** Whether to hide the expand/collapse arrow */
-    hideExpander?: boolean;
-    /** Nested list items (children of this item in a tree) */
-    children?: ReactNode;
-};
+export type ListItem<T = unknown, S = unknown> =
+    | {
+          id: string;
+          value: T;
+          section?: false | undefined;
+          children?: ListItem<T, S>[];
+          hideExpander?: boolean;
+          indentForDepth?: boolean;
+          indentForIcon?: boolean;
+      }
+    | {
+          id: string;
+          value: S;
+          section: true;
+          children: ListItem<T, S>[];
+      };
 
 /**
  * Props for positioning children within a GtkGrid.
@@ -447,8 +455,10 @@ export type ColumnViewColumnProps<T = unknown> = {
     id: string;
     /** Whether clicking the header sorts by this column */
     sortable?: boolean;
+    /** Whether this column is visible */
+    visible?: boolean;
     /** Function to render the cell content for each row */
-    renderCell: (item: T | null) => ReactNode;
+    renderCell: (item: T) => ReactNode;
     /** Menu items for the column header context menu */
     children?: ReactNode;
 };
@@ -662,6 +672,8 @@ export type TextBufferProps = {
 type BaseListViewProps = {
     /** Estimated item height in pixels for virtualization */
     estimatedItemHeight?: number;
+    /** Estimated item width in pixels for virtualization */
+    estimatedItemWidth?: number;
     /** Array of selected item IDs */
     selected?: string[] | null;
     /** Callback fired when the selection changes */
@@ -670,28 +682,40 @@ type BaseListViewProps = {
     selectionMode?: Gtk.SelectionMode | null;
 };
 
-export type ListViewProps = BaseListViewProps & {
+export type ListViewProps<T = unknown, S = unknown> = BaseListViewProps & {
+    /** Data items to display in the list */
+    items?: ListItem<T, S>[];
     /** Function to render each list item. The `row` parameter provides tree state for hierarchical lists. */
-    // biome-ignore lint/suspicious/noExplicitAny: contravariant parameter requires any for typed callbacks
-    renderItem: (item: any, row?: Gtk.TreeListRow | null) => ReactNode;
+    renderItem: (item: T, row?: Gtk.TreeListRow | null) => ReactNode;
     /** Whether to automatically expand new tree rows (default: false) */
     autoexpand?: boolean;
+    /** Function to render section headers when items contain section entries */
+    renderHeader?: ((item: S) => ReactNode) | null;
 };
 
-export type GridViewProps = BaseListViewProps & {
+export type GridViewProps<T = unknown> = BaseListViewProps & {
+    /** Data items to display in the grid */
+    items?: ListItem<T>[];
     /** Function to render each grid item */
-    // biome-ignore lint/suspicious/noExplicitAny: contravariant parameter requires any for typed callbacks
-    renderItem: (item: any) => ReactNode;
+    renderItem: (item: T) => ReactNode;
 };
 
 /**
  * Props shared by single-selection dropdown widgets (GtkDropDown, AdwComboRow).
  */
-export type DropDownProps = {
+export type DropDownProps<T = unknown, S = unknown> = {
+    /** Data items to display in the dropdown */
+    items?: ListItem<T, S>[];
     /** ID of the currently selected item */
     selectedId?: string | null;
     /** Callback fired when the selected item changes */
     onSelectionChanged?: ((id: string) => void) | null;
+    /** Function to render each item. Sets the primary factory, used for both button and popup list unless overridden by renderListItem. */
+    renderItem?: ((item: T) => ReactNode) | null;
+    /** Function to render items in the popup list only, overriding renderItem for the list. */
+    renderListItem?: ((item: T) => ReactNode) | null;
+    /** Function to render section headers when items contain section entries */
+    renderHeader?: ((item: S) => ReactNode) | null;
 };
 
 /**
@@ -735,18 +759,13 @@ export type AdjustableProps = {
  *
  * @example
  * ```tsx
- * import { x, GtkHeaderBar, GtkDropDown } from "@gtkx/react";
+ * import { x, GtkHeaderBar } from "@gtkx/react";
  *
  * <GtkHeaderBar>
  *   <x.Slot for={GtkHeaderBar} id="titleWidget">
  *     <GtkLabel label="App Title" />
  *   </x.Slot>
  * </GtkHeaderBar>
- *
- * <GtkDropDown>
- *   <x.ListItem id="opt1" value="Option 1" />
- *   <x.ListItem id="opt2" value="Option 2" />
- * </GtkDropDown>
  * ```
  */
 export const x = {
@@ -834,28 +853,6 @@ export const x = {
      */
     NotebookPageTab: "NotebookPageTab" as const,
 
-    /**
-     * Element type for items in a GtkListView, GtkGridView, or GtkColumnView.
-     *
-     * Items can be nested to create tree hierarchies inside a GtkListView.
-     *
-     * @example
-     * ```tsx
-     * // Flat list
-     * <GtkListView renderItem={(item) => <GtkLabel label={item.name} />}>
-     *   <x.ListItem id="1" value={{ name: "Item 1" }} />
-     * </GtkListView>
-     *
-     * // Tree list (nested items)
-     * <GtkListView renderItem={(item, row) => <GtkLabel label={item.name} />} autoexpand>
-     *   <x.ListItem id="parent" value={{ name: "Parent" }}>
-     *     <x.ListItem id="child" value={{ name: "Child" }} />
-     *   </x.ListItem>
-     * </GtkListView>
-     * ```
-     */
-    ListItem: "ListItem" as const,
-
     /**
      * Component for defining columns in a ColumnView (table widget).
      *
@@ -1078,7 +1075,7 @@ export const x = {
     /**
      * A keyboard shortcut definition.
      *
-     * Must be a child of `x.ShortcutController`.
+     * Must be a child of `<GtkShortcutController>`.
      *
      * @example
      * ```tsx
@@ -1124,7 +1121,6 @@ declare global {
                 ColumnViewColumn: ColumnViewColumnProps;
                 FixedChild: FixedChildProps;
                 GridChild: GridChildProps;
-                ListItem: ListItemProps;
                 MenuItem: MenuItemProps;
                 MenuSection: MenuSectionProps;
                 MenuSubmenu: MenuSubmenuProps;
@@ -1144,7 +1140,61 @@ declare global {
     }
 }
 
+export type AccessibleProps = {
+    accessibleAutocomplete?: Gtk.AccessibleAutocomplete;
+    accessibleDescription?: string;
+    accessibleHasPopup?: boolean;
+    accessibleKeyShortcuts?: string;
+    accessibleLabel?: string;
+    accessibleLevel?: number;
+    accessibleModal?: boolean;
+    accessibleMultiLine?: boolean;
+    accessibleMultiSelectable?: boolean;
+    accessibleOrientation?: Gtk.Orientation;
+    accessiblePlaceholder?: string;
+    accessibleReadOnly?: boolean;
+    accessibleRequired?: boolean;
+    accessibleRoleDescription?: string;
+    accessibleSort?: Gtk.AccessibleSort;
+    accessibleValueMax?: number;
+    accessibleValueMin?: number;
+    accessibleValueNow?: number;
+    accessibleValueText?: string;
+    accessibleHelpText?: string;
+
+    accessibleBusy?: boolean;
+    accessibleChecked?: Gtk.AccessibleTristate;
+    accessibleDisabled?: boolean;
+    accessibleExpanded?: boolean;
+    accessibleHidden?: boolean;
+    accessibleInvalid?: Gtk.AccessibleInvalidState;
+    accessiblePressed?: Gtk.AccessibleTristate;
+    accessibleSelected?: boolean;
+    accessibleVisited?: boolean;
+
+    accessibleActiveDescendant?: Gtk.Widget;
+    accessibleColCount?: number;
+    accessibleColIndex?: number;
+    accessibleColIndexText?: string;
+    accessibleColSpan?: number;
+    accessibleControls?: Gtk.Widget[];
+    accessibleDescribedBy?: Gtk.Widget[];
+    accessibleDetails?: Gtk.Widget[];
+    accessibleErrorMessage?: Gtk.Widget[];
+    accessibleFlowTo?: Gtk.Widget[];
+    accessibleLabelledBy?: Gtk.Widget[];
+    accessibleOwns?: Gtk.Widget[];
+    accessiblePosInSet?: number;
+    accessibleRowCount?: number;
+    accessibleRowIndex?: number;
+    accessibleRowIndexText?: string;
+    accessibleRowSpan?: number;
+    accessibleSetSize?: number;
+};
+
 declare module "./generated/jsx.js" {
+    interface WidgetProps extends AccessibleProps {}
+
     interface GtkRangeProps extends Omit<AdjustableProps, "onValueChanged"> {
         /** Callback fired when the range value changes */
         onValueChanged?: ((value: number, self: Gtk.Range) => void) | null;
@@ -1204,6 +1254,8 @@ declare module "./generated/jsx.js" {
     interface GtkGridViewProps extends GridViewProps {}
 
     interface GtkColumnViewProps {
+        /** Data items to display in the column view */
+        items?: ListItem[];
         /** Array of selected row IDs */
         selected?: string[] | null;
         /** Callback fired when the selection changes */
@@ -1218,6 +1270,8 @@ declare module "./generated/jsx.js" {
         onSortChanged?: ((column: string | null, order: Gtk.SortType) => void) | null;
         /** Estimated row height in pixels for virtualization */
         estimatedRowHeight?: number | null;
+        /** Function to render section headers when items contain section entries */
+        renderHeader?: ((item: unknown) => ReactNode) | null;
     }
 
     interface GtkDropDownProps extends DropDownProps {}
@@ -1261,6 +1315,10 @@ declare module "./generated/jsx.js" {
     interface GtkFontDialogButtonProps extends DialogButtonProps {
         /** Callback fired when the selected font changes */
         onFontDescChanged?: ((fontDesc: Pango.FontDescription) => void) | null;
+        /** Filter to restrict which fonts are shown in the dialog */
+        filter?: Gtk.Filter | null;
+        /** Custom font map to select fonts from */
+        fontMap?: Pango.FontMap | null;
     }
 
     interface GtkAboutDialogProps {
@@ -1293,4 +1351,5 @@ declare module "./generated/jsx.js" {
     }
 }
 
+export { AdwComboRow, GtkColumnView, GtkDropDown, GtkGridView, GtkListView } from "./components/list.js";
 export * from "./generated/jsx.js";

package/src/metadata.ts

@@ -1,5 +1,5 @@
 import type { NativeClass } from "@gtkx/ffi";
-import { PROPS, SIGNALS } from "./generated/internal.js";
+import { CONSTRUCTION_META, PROPS, SIGNALS } from "./generated/internal.js";
 import type { Container } from "./types.js";
 
 const walkPrototypeChain = <T>(instance: Container, lookup: (typeName: string) => T | null): T | null => {
@@ -30,6 +30,13 @@ const walkPrototypeChain = <T>(instance: Container, lookup: (typeName: string) =
 export const resolvePropMeta = (instance: Container, key: string): [string | null, string] | null =>
     walkPrototypeChain(instance, (typeName) => PROPS[typeName]?.[key] ?? null);
 
+export const isConstructOnlyProp = (instance: Container, key: string): boolean =>
+    walkPrototypeChain(instance, (typeName) => {
+        const meta = CONSTRUCTION_META[typeName];
+        if (!meta || !(key in meta)) return null;
+        return meta[key]?.constructOnly === true;
+    }) ?? false;
+
 export const resolveSignal = (instance: Container, propName: string): string | null => {
     if (propName === "onNotify") return "notify";
     return walkPrototypeChain(instance, (typeName) => SIGNALS[typeName]?.[propName] ?? null);

package/src/node.ts

@@ -14,7 +14,6 @@ export class Node<TContainer = any, TProps = any, TParent extends Node = any, TC
     rootContainer: Container;
     parent: TParent | null = null;
     children: TChild[] = [];
-    private childIndices = new Map<TChild, number>();
 
     constructor(typeName: string, props: TProps, container: TContainer, rootContainer: Container) {
         this.typeName = typeName;
@@ -36,6 +35,7 @@ export class Node<TContainer = any, TProps = any, TParent extends Node = any, TC
         if (parent !== null && !this.isValidParent(parent)) {
             throw new Error(`Cannot add '${this.typeName}' to '${parent.typeName}'`);
         }
+
         this.parent = parent;
     }
 
@@ -47,48 +47,46 @@ export class Node<TContainer = any, TProps = any, TParent extends Node = any, TC
         if (!this.isValidChild(child)) {
             throw new Error(`Cannot append '${child.typeName}' to '${this.typeName}'`);
         }
-        this.childIndices.set(child, this.children.length);
+
+        const existingIndex = this.children.indexOf(child);
+        if (existingIndex !== -1) {
+            this.children.splice(existingIndex, 1);
+        }
         this.children.push(child);
-        child.setParent(this);
+
+        if (child.parent !== this) {
+            child.setParent(this);
+        }
     }
 
     public removeChild(child: TChild): void {
-        const index = this.childIndices.get(child);
-        if (index !== undefined) {
-            child.setParent(null);
+        child.setParent(null);
+        const index = this.children.indexOf(child);
+
+        if (index !== -1) {
             this.children.splice(index, 1);
-            this.childIndices.delete(child);
-            this.rebuildChildIndices(index);
         }
     }
 
     public insertBefore(child: TChild, before: TChild): void {
-        const beforeIndex = this.childIndices.get(before);
-        if (beforeIndex === undefined) {
-            throw new Error(`Cannot find 'before' child '${before.typeName}' in '${this.typeName}'`);
+        if (!this.isValidChild(child)) {
+            throw new Error(`Cannot insert '${child.typeName}' into '${this.typeName}'`);
         }
 
-        const existingIndex = this.childIndices.get(child);
-        if (existingIndex !== undefined) {
+        const existingIndex = this.children.indexOf(child);
+        if (existingIndex !== -1) {
             this.children.splice(existingIndex, 1);
-            const adjustedIndex = existingIndex < beforeIndex ? beforeIndex - 1 : beforeIndex;
-            this.children.splice(adjustedIndex, 0, child);
-            this.rebuildChildIndices(Math.min(existingIndex, adjustedIndex));
-            return;
         }
 
-        if (!this.isValidChild(child)) {
-            throw new Error(`Cannot insert '${child.typeName}' into '${this.typeName}'`);
+        const beforeIndex = this.children.indexOf(before);
+        if (beforeIndex === -1) {
+            throw new Error(`Cannot find 'before' child '${before.typeName}' in '${this.typeName}'`);
         }
 
         this.children.splice(beforeIndex, 0, child);
-        this.rebuildChildIndices(beforeIndex);
-        child.setParent(this);
-    }
 
-    private rebuildChildIndices(fromIndex: number): void {
-        for (let i = fromIndex; i < this.children.length; i++) {
-            this.childIndices.set(this.children[i] as TChild, i);
+        if (child.parent !== this) {
+            child.setParent(this);
         }
     }
 

package/src/nodes/application.ts

@@ -3,6 +3,7 @@ import { Node } from "../node.js";
 import type { Container, Props } from "../types.js";
 import { MenuNode } from "./menu.js";
 import { MenuModel } from "./models/menu.js";
+import { WindowNode } from "./window.js";
 
 export class ApplicationNode extends Node<Gtk.Application, Props, Node, Node> {
     private menu: MenuModel;
@@ -51,6 +52,10 @@ export class ApplicationNode extends Node<Gtk.Application, Props, Node, Node> {
             return;
         }
 
+        if (child instanceof WindowNode) {
+            child.container.setVisible(false);
+        }
+
         super.removeChild(child);
     }
 }