@gtkx/react 0.4.1 → 0.5.0

package/dist/codegen/jsx-generator.d.ts

@@ -64,9 +64,11 @@ export declare class JsxGenerator {
     private addNamespacePrefix;
     private buildSignalHandlerType;
     private generateExports;
+    private generateApplicationMenuComponents;
     private getWrapperExportMembers;
     private generateGenericWrapperComponents;
     private generateJsxNamespace;
+    private addMenuIntrinsicElements;
     private formatCode;
 }
 export {};

package/dist/codegen/jsx-generator.js

@@ -590,7 +590,6 @@ ${widgetPropsContent}
                 isPopoverMenuWidget(widget.name);
             const docComment = widget.doc ? formatDoc(widget.doc).trimEnd() : "";
             if (hasMeaningfulSlots) {
-                // For list widgets, generate wrapper components with proper generics
                 if (isListWidget(widget.name) ||
                     isColumnViewWidget(widget.name) ||
                     isDropDownWidget(widget.name) ||
@@ -629,8 +628,11 @@ ${widgetPropsContent}
                 }
             }
         }
-        // Add ApplicationMenu and Menu namespace components
-        lines.push(`/**
+        lines.push(this.generateApplicationMenuComponents());
+        return `${lines.join("\n")}\n`;
+    }
+    generateApplicationMenuComponents() {
+        return `/**
  * Sets the application-wide menu bar.
  * The menu will appear in the window's title bar on supported platforms.
  * Use Menu.Item, Menu.Section, and Menu.Submenu as children.
@@ -658,8 +660,7 @@ export const Menu = {
 \tSection: MenuSection,
 \tSubmenu: MenuSubmenu,
 };
-`);
-        return `${lines.join("\n")}\n`;
+`;
     }
     getWrapperExportMembers(widgetName, metadata) {
         const name = toPascalCase(widgetName);
@@ -682,7 +683,6 @@ export const Menu = {
             members.push(`Section: ${name}Section`);
             members.push(`Submenu: ${name}Submenu`);
         }
-        // Add named child slots
         for (const slot of metadata.namedChildSlots) {
             members.push(`${slot.slotName}: ${name}${slot.slotName}`);
         }
@@ -747,7 +747,7 @@ export const Menu = {
             lines.push(`\t/** Function to convert an item to its display label. */`);
             lines.push(`\titemLabel?: (item: T) => string;`);
             lines.push(`\t/** Called when the selected item changes. */`);
-            lines.push(`\tonSelectionChanged?: (item: T, index: number) => void;`);
+            lines.push(`\tonSelectionChanged?: (item: T | null, index: number) => void;`);
             lines.push(`}`);
             lines.push(``);
             lines.push(`function ${name}Root<T>(props: ${name}RootProps<T>): import("react").ReactElement {`);
@@ -840,11 +840,7 @@ export const Menu = {
                 elements.push(`"${widgetName}.Page": StackPageProps;`);
             }
         }
-        // Add shared Menu elements (used by PopoverMenu, PopoverMenuBar, and ApplicationMenu)
-        elements.push(`"Menu.Item": MenuItemProps;`);
-        elements.push(`"Menu.Section": MenuSectionProps;`);
-        elements.push(`"Menu.Submenu": MenuSubmenuProps;`);
-        // Add ApplicationMenu element
+        this.addMenuIntrinsicElements(elements);
         elements.push(`ApplicationMenu: MenuRootProps;`);
         return `
 declare global {
@@ -858,6 +854,11 @@ declare global {
 }
 `;
     }
+    addMenuIntrinsicElements(elements) {
+        elements.push(`"Menu.Item": MenuItemProps;`);
+        elements.push(`"Menu.Section": MenuSectionProps;`);
+        elements.push(`"Menu.Submenu": MenuSubmenuProps;`);
+    }
     async formatCode(code) {
         try {
             return await format(code, {

package/dist/container-interfaces.d.ts

@@ -1,69 +1,69 @@
 import type * as Gtk from "@gtkx/ffi/gtk";
 import type { Node } from "./node.js";
 /**
- * Interface for containers that manage child widgets with attach/detach semantics.
+ * Type for containers that manage child widgets with attach/detach semantics.
  * Used by ActionBar, FlowBox, ListBox, Overlay.
  */
-export interface ChildContainer {
+export type ChildContainer = {
     attachChild(child: Gtk.Widget): void;
     insertChildBefore(child: Gtk.Widget, before: Gtk.Widget): void;
     detachChild(child: Gtk.Widget): void;
-}
+};
 /**
- * Interface for page-based containers like Notebook.
+ * Type for page-based containers like Notebook.
  */
-export interface PageContainer {
+export type PageContainer = {
     addPage(child: Gtk.Widget, label: string): void;
     insertPageBefore(child: Gtk.Widget, label: string, beforeChild: Gtk.Widget): void;
     removePage(child: Gtk.Widget): void;
     updatePageLabel(child: Gtk.Widget, label: string): void;
-}
+};
 /**
  * Props for Stack pages.
  */
-export interface StackPageProps {
+export type StackPageProps = {
     name?: string;
     title?: string;
     iconName?: string;
     needsAttention?: boolean;
     visible?: boolean;
     useUnderline?: boolean;
-}
+};
 /**
- * Interface for Stack containers.
+ * Type for Stack containers.
  */
-export interface StackPageContainer {
+export type StackPageContainer = {
     addStackPage(child: Gtk.Widget, props: StackPageProps): void;
     insertStackPageBefore(child: Gtk.Widget, props: StackPageProps, beforeChild: Gtk.Widget): void;
     removeStackPage(child: Gtk.Widget): void;
     updateStackPageProps(child: Gtk.Widget, props: StackPageProps): void;
-}
+};
 /**
- * Interface for grid-based containers.
+ * Type for grid-based containers.
  */
-export interface GridContainer {
+export type GridContainer = {
     attachToGrid(child: Gtk.Widget, column: number, row: number, colSpan: number, rowSpan: number): void;
     removeFromGrid(child: Gtk.Widget): void;
-}
+};
 /**
- * Interface for item-based containers like ListView, ColumnView, DropDown.
+ * Type for item-based containers like ListView, ColumnView, DropDown.
  */
-export interface ItemContainer<T> {
+export type ItemContainer<T> = {
     addItem(item: T): void;
     insertItemBefore(item: T, beforeItem: T): void;
     removeItem(item: T): void;
-}
+};
 /**
- * Interface for column-based containers like ColumnView.
+ * Type for column-based containers like ColumnView.
  * Note: Column type is generic to support both raw Gtk.ColumnViewColumn and wrapper nodes.
  */
-export interface ColumnContainer {
+export type ColumnContainer = {
     addColumn(column: unknown): void;
     insertColumnBefore(column: unknown, beforeColumn: unknown): void;
     removeColumn(column: unknown): void;
     getItems(): unknown[];
     getSortFn(): ((a: unknown, b: unknown, columnId: string) => number) | null;
-}
+};
 export declare const isChildContainer: (node: Node) => node is Node & ChildContainer;
 export declare const isPageContainer: (node: Node) => node is Node & PageContainer;
 export declare const isStackPageContainer: (node: Node) => node is Node & StackPageContainer;

package/dist/generated/jsx.d.ts

@@ -7502,7 +7502,7 @@ interface DropDownRootProps<T> extends Omit<DropDownProps, "itemLabel" | "onSele
     /** Function to convert an item to its display label. */
     itemLabel?: (item: T) => string;
     /** Called when the selected item changes. */
-    onSelectionChanged?: (item: T, index: number) => void;
+    onSelectionChanged?: (item: T | null, index: number) => void;
 }
 declare function DropDownRoot<T>(props: DropDownRootProps<T>): import("react").ReactElement;
 declare function DropDownItem<T>(props: ListItemProps<T>): import("react").ReactElement;

package/dist/nodes/column-view.d.ts

@@ -23,6 +23,8 @@ interface ColumnViewState {
 export declare class ColumnViewNode extends Node<Gtk.ColumnView, ColumnViewState> implements ItemContainer<unknown>, ColumnContainer {
     static matches(type: string): boolean;
     initialize(props: Props): void;
+    private initializeStateWithPlaceholders;
+    private createGtkModels;
     private connectSorterChangedSignal;
     private waitForSortComplete;
     private disconnectSorterChangedSignal;

package/dist/nodes/column-view.js

@@ -12,9 +12,12 @@ export class ColumnViewNode extends Node {
         return type === "ColumnView.Root";
     }
     initialize(props) {
-        // State must be initialized before super.initialize() since updateProps accesses this.state.
-        // GTK objects can't be created yet because this.widget doesn't exist until super.initialize().
-        // The null placeholders are immediately replaced after super.initialize() completes.
+        this.initializeStateWithPlaceholders(props);
+        super.initialize(props);
+        this.createGtkModels();
+        this.connectSorterChangedSignal();
+    }
+    initializeStateWithPlaceholders(props) {
         this.state = {
             stringList: null,
             selectionModel: null,
@@ -31,7 +34,8 @@ export class ColumnViewNode extends Node {
             lastNotifiedColumn: null,
             lastNotifiedOrder: Gtk.SortType.ASCENDING,
         };
-        super.initialize(props);
+    }
+    createGtkModels() {
         const stringList = new Gtk.StringList([]);
         const sortListModel = new Gtk.SortListModel(getInterface(stringList, Gio.ListModel), this.widget.getSorter());
         sortListModel.setIncremental(true);
@@ -40,7 +44,6 @@ export class ColumnViewNode extends Node {
         this.state.stringList = stringList;
         this.state.sortListModel = sortListModel;
         this.state.selectionModel = selectionModel;
-        this.connectSorterChangedSignal();
     }
     connectSorterChangedSignal() {
         const sorter = this.widget.getSorter();
@@ -221,8 +224,6 @@ export class ColumnViewColumnNode extends Node {
     }
     columnView = null;
     initialize(props) {
-        // Unlike ColumnViewNode, we can create GTK objects before super.initialize() here
-        // since this is a virtual node (no widget created by parent class).
         const factory = new Gtk.SignalListItemFactory();
         const column = new Gtk.ColumnViewColumn(props.title, factory);
         const columnId = props.id ?? null;

package/dist/nodes/list.d.ts

@@ -20,6 +20,9 @@ interface ListViewState {
 export declare class ListViewNode extends Node<Gtk.ListView | Gtk.GridView, ListViewState> implements ItemContainer<unknown> {
     static matches(type: string): boolean;
     initialize(props: Props): void;
+    private initializeStateWithPlaceholders;
+    private createGtkModels;
+    private connectFactorySignals;
     private syncStringList;
     addItem(item: unknown): void;
     insertItemBefore(item: unknown, beforeItem: unknown): void;

package/dist/nodes/list.js

@@ -11,9 +11,14 @@ export class ListViewNode extends Node {
         return type === "ListView.Root" || type === "GridView.Root";
     }
     initialize(props) {
-        // State must be initialized before super.initialize() since updateProps accesses this.state.
-        // GTK objects can't be created yet because this.widget doesn't exist until super.initialize().
-        // The null placeholders are immediately replaced after super.initialize() completes.
+        this.initializeStateWithPlaceholders(props);
+        super.initialize(props);
+        this.createGtkModels();
+        this.connectFactorySignals();
+        this.widget.setModel(this.state.selectionModel);
+        this.widget.setFactory(this.state.factory);
+    }
+    initializeStateWithPlaceholders(props) {
         this.state = {
             stringList: null,
             selectionModel: null,
@@ -23,13 +28,17 @@ export class ListViewNode extends Node {
             items: [],
             committedLength: 0,
         };
-        super.initialize(props);
+    }
+    createGtkModels() {
         const stringList = new Gtk.StringList([]);
         const selectionModel = new Gtk.SingleSelection(getInterface(stringList, Gio.ListModel));
         const factory = new Gtk.SignalListItemFactory();
         this.state.stringList = stringList;
         this.state.selectionModel = selectionModel;
         this.state.factory = factory;
+    }
+    connectFactorySignals() {
+        const factory = this.state.factory;
         factory.connect("setup", (_self, listItemObj) => {
             const listItem = getObject(listItemObj.id);
             const id = getObjectId(listItemObj.id);
@@ -66,8 +75,6 @@ export class ListViewNode extends Node {
                 this.state.listItemCache.delete(id);
             }
         });
-        this.widget.setModel(selectionModel);
-        this.widget.setFactory(factory);
     }
     syncStringList = () => {
         const newLength = this.state.items.length;

package/dist/nodes/menu.d.ts

@@ -56,7 +56,9 @@ export declare class MenuItemNode extends Node<never> {
     attachToParent(parent: Node): void;
     detachFromParent(parent: Node): void;
     protected consumedProps(): Set<string>;
+    private isFieldInitializationIncomplete;
     updateProps(oldProps: Props, newProps: Props): void;
+    private invokeCurrentCallback;
     private setupAction;
     private cleanupAction;
     private updateAccels;

package/dist/nodes/menu.js

@@ -138,27 +138,23 @@ export class MenuItemNode extends Node {
         consumed.add("accels");
         return consumed;
     }
+    isFieldInitializationIncomplete() {
+        return !this.entry;
+    }
     updateProps(oldProps, newProps) {
-        // If entry doesn't exist yet, fields aren't initialized
-        // This happens when base class constructor calls updateProps
-        // before derived class field initializers run - skip in that case
-        if (!this.entry) {
+        if (this.isFieldInitializationIncomplete()) {
             super.updateProps(oldProps, newProps);
             return;
         }
         const labelChanged = oldProps.label !== newProps.label;
-        const hadCallback = oldProps.onActivate !== undefined;
-        const hasCallback = newProps.onActivate !== undefined;
+        const callbackPresenceChanged = (oldProps.onActivate !== undefined) !== (newProps.onActivate !== undefined);
         const accelsChanged = oldProps.accels !== newProps.accels;
-        // Always update the callback reference - the signal handler uses this
         this.onActivateCallback = newProps.onActivate;
         this.currentAccels = newProps.accels;
         if (labelChanged) {
             this.entry.label = newProps.label;
         }
-        // Only cleanup/setup action if the presence of a callback changed
-        // (not when the callback reference changes - we store the ref and call it)
-        if (this.isAttached && hadCallback !== hasCallback) {
+        if (this.isAttached && callbackPresenceChanged) {
             this.cleanupAction();
             this.setupAction();
         }
@@ -167,15 +163,15 @@ export class MenuItemNode extends Node {
         }
         super.updateProps(oldProps, newProps);
     }
+    invokeCurrentCallback() {
+        this.onActivateCallback?.();
+    }
     setupAction() {
         if (!this.onActivateCallback)
             return;
         this.actionName = generateActionName();
         this.action = new Gio.SimpleAction(this.actionName);
-        this.signalHandlerId = this.action.connect("activate", () => {
-            // Call the current callback (may have been updated via updateProps)
-            this.onActivateCallback?.();
-        });
+        this.signalHandlerId = this.action.connect("activate", () => this.invokeCurrentCallback());
         const app = getCurrentApp();
         const action = getInterface(this.action, Gio.Action);
         if (!action) {

package/dist/nodes/stack.d.ts

@@ -15,6 +15,7 @@ export declare class StackNode extends Node<Gtk.Stack> implements StackPageConta
     insertChildBefore(child: Gtk.Widget, _before: Gtk.Widget): void;
     detachChild(child: Gtk.Widget): void;
     protected consumedProps(): Set<string>;
+    private setVisibleChildOrDefer;
     updateProps(oldProps: Props, newProps: Props): void;
 }
 export declare class StackPageNode extends Node {

package/dist/nodes/stack.js

@@ -30,8 +30,6 @@ export class StackNode extends Node {
         }
     }
     insertStackPageBefore(child, props, _beforeChild) {
-        // Stack doesn't have insertBefore, so we add and rely on order
-        // For now, just add at the end - GTK Stack doesn't support insertion at position
         this.addStackPage(child, props);
     }
     removeStackPage(child) {
@@ -65,7 +63,6 @@ export class StackNode extends Node {
         this.widget.addChild(child);
     }
     insertChildBefore(child, _before) {
-        // Stack doesn't support insertion at position
         this.widget.addChild(child);
     }
     detachChild(child) {
@@ -76,18 +73,19 @@ export class StackNode extends Node {
         consumed.add("visibleChildName");
         return consumed;
     }
+    setVisibleChildOrDefer(name) {
+        const child = this.widget.getChildByName(name);
+        if (child) {
+            this.widget.setVisibleChild(child);
+            this.pendingVisibleChildName = null;
+        }
+        else {
+            this.pendingVisibleChildName = name;
+        }
+    }
     updateProps(oldProps, newProps) {
         if (newProps.visibleChildName !== undefined) {
-            const name = newProps.visibleChildName;
-            const child = this.widget.getChildByName(name);
-            if (child) {
-                this.widget.setVisibleChild(child);
-                this.pendingVisibleChildName = null;
-            }
-            else {
-                // Child not yet added, defer until it's added
-                this.pendingVisibleChildName = name;
-            }
+            this.setVisibleChildOrDefer(newProps.visibleChildName);
         }
         super.updateProps(oldProps, newProps);
     }

package/dist/portal.d.ts

@@ -8,6 +8,9 @@ import type { ReactNode, ReactPortal } from "react";
  * When called without a container argument, the portal renders at the root level.
  * This is useful for dialogs which don't need a parent container.
  *
+ * Implementation note: ReactPortal is an opaque type, so we manually construct
+ * the internal representation required by custom reconcilers.
+ *
  * @example
  * ```tsx
  * // Render dialog at root level (no container needed)

package/dist/portal.js

@@ -8,6 +8,9 @@ import { ROOT_NODE_CONTAINER } from "./factory.js";
  * When called without a container argument, the portal renders at the root level.
  * This is useful for dialogs which don't need a parent container.
  *
+ * Implementation note: ReactPortal is an opaque type, so we manually construct
+ * the internal representation required by custom reconcilers.
+ *
  * @example
  * ```tsx
  * // Render dialog at root level (no container needed)
@@ -18,8 +21,6 @@ import { ROOT_NODE_CONTAINER } from "./factory.js";
  * ```
  */
 export const createPortal = (children, container, key) => {
-    // ReactPortal is an opaque type but we need to construct it manually for custom reconcilers.
-    // The shape matches React's internal portal representation.
     return {
         $$typeof: Symbol.for("react.portal"),
         key: key ?? null,

package/dist/types.d.ts

@@ -4,23 +4,23 @@ import type { ReactElement, ReactNode } from "react";
  * Props for slot components that accept children.
  * Used by container widgets that render child elements in designated slots.
  */
-export interface SlotProps {
+export type SlotProps = {
     children?: ReactNode;
-}
+};
 /**
  * Props passed to list item components.
  * @typeParam I - The type of the data item
  */
-export interface ListItemProps<I = unknown> {
+export type ListItemProps<I = unknown> = {
     /** The data item to render. */
     item: I;
-}
-export interface GridChildProps extends SlotProps {
+};
+export type GridChildProps = SlotProps & {
     column?: number;
     row?: number;
     columnSpan?: number;
     rowSpan?: number;
-}
+};
 /**
  * Render function for ListView/GridView items.
  * Called with null during setup (for loading state) and with the actual item during bind.
@@ -30,10 +30,10 @@ export type RenderItemFn<T> = (item: T | null) => ReactElement;
  * Props for ListView and GridView components.
  * @typeParam T - The type of the data items in the list
  */
-export interface ListViewRenderProps<T = unknown> {
+export type ListViewRenderProps<T = unknown> = {
     /** Render function called for each item in the list. */
     renderItem: RenderItemFn<T>;
-}
+};
 /**
  * Comparison function for sorting items by column.
  * Returns negative if a < b, 0 if a === b, positive if a > b.
@@ -46,7 +46,7 @@ export type ColumnSortFn<T, C extends string = string> = (a: T, b: T, columnId:
  * Props for individual columns in a ColumnView.
  * @typeParam T - The type of the data items displayed in the column
  */
-export interface ColumnViewColumnProps<T = unknown> {
+export type ColumnViewColumnProps<T = unknown> = {
     /** The column header title. */
     title?: string;
     /** Whether the column should expand to fill available space. */
@@ -63,13 +63,13 @@ export interface ColumnViewColumnProps<T = unknown> {
      * Always annotate your callback parameter type to include null, e.g.: `(item: MyItem | null) => ...`
      */
     renderCell: (item: T | null) => ReactElement;
-}
+};
 /**
  * Props for the ColumnView root component.
  * @typeParam T - The type of the data items in the view
  * @typeParam C - The union type of column IDs
  */
-export interface ColumnViewRootProps<T = unknown, C extends string = string> {
+export type ColumnViewRootProps<T = unknown, C extends string = string> = {
     /** The ID of the currently sorted column, or null if unsorted. */
     sortColumn?: C | null;
     /** The current sort direction. */
@@ -78,55 +78,55 @@ export interface ColumnViewRootProps<T = unknown, C extends string = string> {
     onSortChange?: (column: C | null, order: SortType) => void;
     /** Custom comparison function for sorting items. */
     sortFn?: ColumnSortFn<T, C>;
-}
-export interface NotebookPageProps extends SlotProps {
+};
+export type NotebookPageProps = SlotProps & {
     label: string;
-}
-export interface StackRootProps extends SlotProps {
+};
+export type StackRootProps = SlotProps & {
     visibleChildName?: string;
-}
-export interface StackPageProps extends SlotProps {
+};
+export type StackPageProps = SlotProps & {
     name?: string;
     title?: string;
     iconName?: string;
     needsAttention?: boolean;
     visible?: boolean;
     useUnderline?: boolean;
-}
+};
 /**
  * Props for the Menu.Root component.
  * Root container for declarative menu structures.
  */
-export interface MenuRootProps {
+export type MenuRootProps = {
     children?: ReactNode;
-}
+};
 /**
  * Props for Menu.Item components.
  * Represents a single menu item with an action.
  */
-export interface MenuItemProps {
+export type MenuItemProps = {
     /** The visible label for the menu item. */
     label: string;
     /** Callback invoked when the menu item is activated. */
     onActivate?: () => void;
     /** Keyboard accelerators for this menu item (e.g., `"<Control>q"` or `["<Control>q", "<Control>w"]`). */
     accels?: string | string[];
-}
+};
 /**
  * Props for Menu.Section components.
  * Groups related menu items with optional label.
  */
-export interface MenuSectionProps {
+export type MenuSectionProps = {
     /** Optional section label displayed as a header. */
     label?: string;
     children?: ReactNode;
-}
+};
 /**
  * Props for Menu.Submenu components.
  * Creates a nested submenu with its own items.
  */
-export interface MenuSubmenuProps {
+export type MenuSubmenuProps = {
     /** The submenu label shown in parent menu. */
     label: string;
     children?: ReactNode;
-}
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/react",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Build GTK4 desktop applications with React and TypeScript",
   "keywords": [
     "gtk",
@@ -36,10 +36,10 @@
   ],
   "dependencies": {
     "react-reconciler": "0.33.0",
-    "@gtkx/ffi": "0.4.1"
+    "@gtkx/ffi": "0.5.0"
   },
   "devDependencies": {
-    "@gtkx/gir": "0.4.1"
+    "@gtkx/gir": "0.5.0"
   },
   "peerDependencies": {
     "react": "^19"