@gtkx/react 0.1.47 → 0.1.48

package/README.md

@@ -186,6 +186,14 @@ A comprehensive showcase of GTK4 widgets and features:
 turbo start --filter=gtk4-demo
 ```
 
+### List Example
+
+Comprehensive showcase of ListView, GridView, and ColumnView with sorting:
+
+```bash
+turbo start --filter=list-example
+```
+
 ## Packages
 
 | Package | Description |

package/dist/codegen/jsx-generator.js

@@ -136,14 +136,14 @@ export class JsxGenerator {
             `import type { ReactNode, Ref } from "react";`,
             ...externalImports,
             `import type * as Gtk from "@gtkx/ffi/gtk";`,
-            `import type { ColumnViewColumnProps, GridChildProps, ListItemProps, ListViewRenderProps, NotebookPageProps, SlotProps } from "../types.js";`,
+            `import type { ColumnViewColumnProps, ColumnViewRootProps, GridChildProps, ListItemProps, ListViewRenderProps, NotebookPageProps, SlotProps } from "../types.js";`,
             "",
         ].join("\n");
     }
     generateCommonTypes(widgetClass) {
         const widgetPropsContent = this.generateWidgetPropsContent(widgetClass);
         return `
-export { ColumnViewColumnProps, GridChildProps, ListItemProps, ListViewRenderProps, NotebookPageProps, SlotProps };
+export { ColumnViewColumnProps, ColumnViewRootProps, GridChildProps, ListItemProps, ListViewRenderProps, NotebookPageProps, SlotProps };
 
 ${widgetPropsContent}
 `;
@@ -664,8 +664,15 @@ ${widgetPropsContent}
             lines.push(`}`);
         }
         else if (isColumnViewWidget(widgetName)) {
-            // Root wrapper (non-generic)
-            lines.push(`function ${name}Root(props: ${name}Props): import("react").ReactElement {`);
+            // Root props type - extends with ColumnViewRootProps for sorting support
+            // Uses generics: T for item type, C for column ID union type
+            lines.push(`interface ${name}RootPropsExtended<T = unknown, C extends string = string> extends ${name}Props, ColumnViewRootProps<C> {`);
+            lines.push(`\t/** Comparison function for sorting items by column. Takes item a, item b, and column id. */`);
+            lines.push(`\tsortFn?: (a: T, b: T, columnId: C) => number;`);
+            lines.push(`}`);
+            lines.push(``);
+            // Root wrapper (generic)
+            lines.push(`function ${name}Root<T = unknown, C extends string = string>(props: ${name}RootPropsExtended<T, C>): import("react").ReactElement {`);
             lines.push(`\treturn createElement("${name}.Root", props);`);
             lines.push(`}`);
             lines.push(``);

package/dist/generated/jsx.d.ts

@@ -3,8 +3,8 @@ import type { ReactNode, Ref } from "react";
 import type * as Gdk from "@gtkx/ffi/gdk";
 import type * as Gio from "@gtkx/ffi/gio";
 import type * as Gtk from "@gtkx/ffi/gtk";
-import type { ColumnViewColumnProps, GridChildProps, ListItemProps, ListViewRenderProps, NotebookPageProps, SlotProps } from "../types.js";
-export { ColumnViewColumnProps, GridChildProps, ListItemProps, ListViewRenderProps, NotebookPageProps, SlotProps, };
+import type { ColumnViewColumnProps, ColumnViewRootProps, GridChildProps, ListItemProps, ListViewRenderProps, NotebookPageProps, SlotProps } from "../types.js";
+export { ColumnViewColumnProps, ColumnViewRootProps, GridChildProps, ListItemProps, ListViewRenderProps, NotebookPageProps, SlotProps, };
 /**
  * The base class for all widgets.
  *
@@ -7075,7 +7075,11 @@ export declare const ColorChooserWidget: "ColorChooserWidget";
  * it gets the .color style class.
  */
 export declare const ColorDialogButton: "ColorDialogButton";
-declare function ColumnViewRoot(props: ColumnViewProps): import("react").ReactElement;
+interface ColumnViewRootPropsExtended<T = unknown, C extends string = string> extends ColumnViewProps, ColumnViewRootProps<C> {
+    /** Comparison function for sorting items by column. Takes item a, item b, and column id. */
+    sortFn?: (a: T, b: T, columnId: C) => number;
+}
+declare function ColumnViewRoot<T = unknown, C extends string = string>(props: ColumnViewRootPropsExtended<T, C>): import("react").ReactElement;
 interface ColumnViewGenericColumnProps<T> extends Omit<ColumnViewColumnProps, "renderCell"> {
     /** Render function for column cells. Called with null during setup. */
     renderCell: (item: T | null) => import("react").ReactElement;

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

@@ -1,34 +1,58 @@
 import * as Gtk from "@gtkx/ffi/gtk";
 import type { Props } from "../factory.js";
 import { Node } from "../node.js";
+import type { ColumnSortFn } from "../types.js";
 export declare class ColumnViewNode extends Node<Gtk.ColumnView> {
     static matches(type: string): boolean;
     private stringList;
     private selectionModel;
+    private sortListModel;
     private items;
     private columns;
     private committedLength;
+    private sortColumn;
+    private sortOrder;
+    private sortFn;
+    private isSorting;
+    private onSortChange;
+    private sorterChangedHandlerId;
+    private lastNotifiedColumn;
+    private lastNotifiedOrder;
     constructor(type: string, props: Props, app: Gtk.Application);
+    private connectSorterChangedSignal;
+    private waitForSortComplete;
+    private disconnectSorterChangedSignal;
+    private notifySortChange;
     getItems(): unknown[];
-    addColumn(column: ColumnViewColumnNode): void;
+    getSortFn(): ColumnSortFn<unknown, string> | null;
+    compareItems(a: unknown, b: unknown, columnId: string): number;
+    addColumn(columnNode: ColumnViewColumnNode): void;
+    private applySortByColumn;
+    findColumnById(id: string): ColumnViewColumnNode | undefined;
     removeColumn(column: ColumnViewColumnNode): void;
     insertColumnBefore(column: ColumnViewColumnNode, before: ColumnViewColumnNode): void;
     private syncStringList;
     addItem(item: unknown): void;
     insertItemBefore(item: unknown, beforeItem: unknown): void;
     removeItem(item: unknown): void;
+    protected consumedProps(): Set<string>;
+    updateProps(oldProps: Props, newProps: Props): void;
 }
 export declare class ColumnViewColumnNode extends Node {
     static matches(type: string): boolean;
     protected isVirtual(): boolean;
-    private gtkColumn;
+    private column;
     private factory;
     private renderCell;
     private columnView;
     private listItemCache;
+    private columnId;
+    private sorter;
     constructor(type: string, props: Props, app: Gtk.Application);
-    getGtkColumn(): Gtk.ColumnViewColumn;
+    getColumn(): Gtk.ColumnViewColumn;
+    getId(): string | null;
     setColumnView(columnView: ColumnViewNode | null): void;
+    updateSorterFromRoot(): void;
     attachToParent(parent: Node): void;
     attachToParentBefore(parent: Node, before: Node): void;
     detachFromParent(parent: Node): void;

package/dist/nodes/column-view.js

@@ -1,4 +1,5 @@
 import { getObject, getObjectId } from "@gtkx/ffi";
+import * as GObject from "@gtkx/ffi/gobject";
 import * as Gtk from "@gtkx/ffi/gtk";
 import { scheduleFlush } from "../batch.js";
 import { createFiberRoot } from "../fiber-root.js";
@@ -10,29 +11,123 @@ export class ColumnViewNode extends Node {
     }
     stringList;
     selectionModel;
+    sortListModel;
     items = [];
     columns = [];
     committedLength = 0;
+    sortColumn = null;
+    sortOrder = Gtk.SortType.ASCENDING;
+    sortFn = null;
+    isSorting = false;
+    onSortChange = null;
+    sorterChangedHandlerId = null;
+    lastNotifiedColumn = null;
+    lastNotifiedOrder = Gtk.SortType.ASCENDING;
     constructor(type, props, app) {
         super(type, props, app);
         this.stringList = new Gtk.StringList([]);
-        this.selectionModel = new Gtk.SingleSelection(this.stringList);
+        this.sortListModel = new Gtk.SortListModel(this.stringList, this.widget.getSorter());
+        this.sortListModel.setIncremental(true);
+        this.selectionModel = new Gtk.SingleSelection(this.sortListModel);
         this.widget.setModel(this.selectionModel);
+        this.sortColumn = props.sortColumn ?? null;
+        this.sortOrder = props.sortOrder ?? Gtk.SortType.ASCENDING;
+        this.sortFn = props.sortFn ?? null;
+        this.onSortChange =
+            props.onSortChange ?? null;
+        this.connectSorterChangedSignal();
+    }
+    connectSorterChangedSignal() {
+        const sorter = this.widget.getSorter();
+        if (!sorter || !this.onSortChange)
+            return;
+        this.sorterChangedHandlerId = sorter.connect("changed", () => {
+            this.waitForSortComplete(() => this.notifySortChange());
+        });
+    }
+    waitForSortComplete(callback) {
+        const pending = this.sortListModel.getPending();
+        if (pending === 0) {
+            callback();
+        }
+        else {
+            // Sorting still in progress, check again after a short delay
+            setTimeout(() => this.waitForSortComplete(callback), 10);
+        }
+    }
+    disconnectSorterChangedSignal() {
+        if (this.sorterChangedHandlerId === null)
+            return;
+        const sorter = this.widget.getSorter();
+        if (sorter) {
+            GObject.signalHandlerDisconnect(sorter, this.sorterChangedHandlerId);
+        }
+        this.sorterChangedHandlerId = null;
+    }
+    notifySortChange() {
+        if (!this.onSortChange)
+            return;
+        const baseSorter = this.widget.getSorter();
+        if (!baseSorter)
+            return;
+        const sorter = getObject(baseSorter.ptr, Gtk.ColumnViewSorter);
+        const column = sorter.getPrimarySortColumn();
+        const order = sorter.getPrimarySortOrder();
+        const columnId = column?.getId() ?? null;
+        // Deduplicate: only notify if the sort state actually changed
+        if (columnId === this.lastNotifiedColumn && order === this.lastNotifiedOrder) {
+            return;
+        }
+        this.lastNotifiedColumn = columnId;
+        this.lastNotifiedOrder = order;
+        this.onSortChange(columnId, order);
     }
     getItems() {
         return this.items;
     }
-    addColumn(column) {
-        this.columns.push(column);
-        const gtkColumn = column.getGtkColumn();
-        this.widget.appendColumn(gtkColumn);
-        column.setColumnView(this);
+    getSortFn() {
+        return this.sortFn;
+    }
+    compareItems(a, b, columnId) {
+        if (this.isSorting || !this.sortFn)
+            return 0;
+        this.isSorting = true;
+        try {
+            return this.sortFn(a, b, columnId);
+        }
+        finally {
+            this.isSorting = false;
+        }
+    }
+    addColumn(columnNode) {
+        this.columns.push(columnNode);
+        const column = columnNode.getColumn();
+        this.widget.appendColumn(column);
+        columnNode.setColumnView(this);
+        if (columnNode.getId() === this.sortColumn && this.sortColumn !== null) {
+            this.applySortByColumn();
+        }
+    }
+    applySortByColumn() {
+        if (this.sortColumn === null) {
+            this.widget.sortByColumn(this.sortOrder, null);
+            return;
+        }
+        if (!this.columns)
+            return;
+        const column = this.columns.find((c) => c.getId() === this.sortColumn);
+        if (column) {
+            this.widget.sortByColumn(this.sortOrder, column.getColumn());
+        }
+    }
+    findColumnById(id) {
+        return this.columns.find((c) => c.getId() === id);
     }
     removeColumn(column) {
         const index = this.columns.indexOf(column);
         if (index !== -1) {
             this.columns.splice(index, 1);
-            this.widget.removeColumn(column.getGtkColumn());
+            this.widget.removeColumn(column.getColumn());
             column.setColumnView(null);
         }
     }
@@ -43,15 +138,16 @@ export class ColumnViewNode extends Node {
             return;
         }
         this.columns.splice(beforeIndex, 0, column);
-        this.widget.insertColumn(beforeIndex, column.getGtkColumn());
+        this.widget.insertColumn(beforeIndex, column.getColumn());
         column.setColumnView(this);
     }
     syncStringList = () => {
         const newLength = this.items.length;
         if (newLength === this.committedLength)
             return;
-        const placeholders = Array.from({ length: newLength }, () => "");
-        this.stringList.splice(0, this.committedLength, placeholders);
+        // Store indices as strings so we can map back to items in the sorter
+        const indices = Array.from({ length: newLength }, (_, i) => String(i));
+        this.stringList.splice(0, this.committedLength, indices);
         this.committedLength = newLength;
     };
     addItem(item) {
@@ -75,6 +171,46 @@ export class ColumnViewNode extends Node {
             scheduleFlush(this.syncStringList);
         }
     }
+    consumedProps() {
+        const consumed = super.consumedProps();
+        consumed.add("sortColumn");
+        consumed.add("sortOrder");
+        consumed.add("onSortChange");
+        consumed.add("sortFn");
+        return consumed;
+    }
+    updateProps(oldProps, newProps) {
+        super.updateProps(oldProps, newProps);
+        const newSortColumn = newProps.sortColumn ?? null;
+        const newSortOrder = newProps.sortOrder ?? Gtk.SortType.ASCENDING;
+        const newSortFn = newProps.sortFn ?? null;
+        const newOnSortChange = newProps.onSortChange ?? null;
+        if (oldProps.onSortChange !== newProps.onSortChange) {
+            const hadCallback = this.onSortChange !== null;
+            this.onSortChange = newOnSortChange;
+            const hasCallback = this.onSortChange !== null;
+            // Connect or disconnect the signal handler as needed
+            if (!hadCallback && hasCallback) {
+                this.connectSorterChangedSignal();
+            }
+            else if (hadCallback && !hasCallback) {
+                this.disconnectSorterChangedSignal();
+            }
+        }
+        if (oldProps.sortFn !== newProps.sortFn) {
+            this.sortFn = newSortFn;
+            if (this.columns) {
+                for (const column of this.columns) {
+                    column.updateSorterFromRoot();
+                }
+            }
+        }
+        if (oldProps.sortColumn !== newProps.sortColumn || oldProps.sortOrder !== newProps.sortOrder) {
+            this.sortColumn = newSortColumn;
+            this.sortOrder = newSortOrder;
+            this.applySortByColumn();
+        }
+    }
 }
 export class ColumnViewColumnNode extends Node {
     static matches(type) {
@@ -83,24 +219,30 @@ export class ColumnViewColumnNode extends Node {
     isVirtual() {
         return true;
     }
-    gtkColumn;
+    column;
     factory;
     renderCell;
     columnView = null;
     listItemCache = new Map();
+    columnId = null;
+    sorter = null;
     constructor(type, props, app) {
         super(type, props, app);
         this.factory = new Gtk.SignalListItemFactory();
-        this.gtkColumn = new Gtk.ColumnViewColumn(props.title, this.factory);
+        this.column = new Gtk.ColumnViewColumn(props.title, this.factory);
         this.renderCell = props.renderCell;
+        this.columnId = props.id ?? null;
+        if (this.columnId !== null) {
+            this.column.setId(this.columnId);
+        }
         if (props.expand !== undefined) {
-            this.gtkColumn.setExpand(props.expand);
+            this.column.setExpand(props.expand);
         }
         if (props.resizable !== undefined) {
-            this.gtkColumn.setResizable(props.resizable);
+            this.column.setResizable(props.resizable);
         }
         if (props.fixedWidth !== undefined) {
-            this.gtkColumn.setFixedWidth(props.fixedWidth);
+            this.column.setFixedWidth(props.fixedWidth);
         }
         this.factory.connect("setup", (_self, listItemObj) => {
             const listItem = getObject(listItemObj.ptr, Gtk.ListItem);
@@ -142,11 +284,48 @@ export class ColumnViewColumnNode extends Node {
             }
         });
     }
-    getGtkColumn() {
-        return this.gtkColumn;
+    getColumn() {
+        return this.column;
+    }
+    getId() {
+        return this.columnId;
     }
     setColumnView(columnView) {
         this.columnView = columnView;
+        this.updateSorterFromRoot();
+    }
+    updateSorterFromRoot() {
+        if (!this.columnView || this.columnId === null) {
+            this.column.setSorter(null);
+            this.sorter = null;
+            return;
+        }
+        const rootSortFn = this.columnView.getSortFn();
+        if (rootSortFn === null) {
+            this.column.setSorter(null);
+            this.sorter = null;
+            return;
+        }
+        const columnId = this.columnId;
+        const columnView = this.columnView;
+        const wrappedSortFn = (_a, _b) => {
+            const items = columnView.getItems();
+            // _a and _b are GtkStringObject pointers - get the string content (indices)
+            const stringObjA = getObject(_a, Gtk.StringObject);
+            const stringObjB = getObject(_b, Gtk.StringObject);
+            const indexA = Number.parseInt(stringObjA.getString(), 10);
+            const indexB = Number.parseInt(stringObjB.getString(), 10);
+            if (Number.isNaN(indexA) || Number.isNaN(indexB))
+                return 0;
+            const itemA = items[indexA] ?? null;
+            const itemB = items[indexB] ?? null;
+            if (itemA === null || itemB === null)
+                return 0;
+            const result = columnView.compareItems(itemA, itemB, columnId);
+            return typeof result === "number" ? result : 0;
+        };
+        this.sorter = new Gtk.CustomSorter(wrappedSortFn);
+        this.column.setSorter(this.sorter);
     }
     attachToParent(parent) {
         if (parent instanceof ColumnViewNode) {
@@ -173,25 +352,30 @@ export class ColumnViewColumnNode extends Node {
         consumed.add("expand");
         consumed.add("resizable");
         consumed.add("fixedWidth");
+        consumed.add("id");
         return consumed;
     }
     updateProps(oldProps, newProps) {
         if (oldProps.renderCell !== newProps.renderCell) {
             this.renderCell = newProps.renderCell;
         }
-        if (!this.gtkColumn)
+        if (!this.column)
             return;
         if (oldProps.title !== newProps.title) {
-            this.gtkColumn.setTitle(newProps.title);
+            this.column.setTitle(newProps.title);
         }
         if (oldProps.expand !== newProps.expand) {
-            this.gtkColumn.setExpand(newProps.expand);
+            this.column.setExpand(newProps.expand);
         }
         if (oldProps.resizable !== newProps.resizable) {
-            this.gtkColumn.setResizable(newProps.resizable);
+            this.column.setResizable(newProps.resizable);
         }
         if (oldProps.fixedWidth !== newProps.fixedWidth) {
-            this.gtkColumn.setFixedWidth(newProps.fixedWidth);
+            this.column.setFixedWidth(newProps.fixedWidth);
+        }
+        if (oldProps.id !== newProps.id) {
+            this.columnId = newProps.id ?? null;
+            this.column.setId(this.columnId);
         }
     }
 }

package/dist/types.d.ts

@@ -1,4 +1,9 @@
+import type { SortType } from "@gtkx/ffi/gtk";
 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 {
     children?: ReactNode;
 }
@@ -19,11 +24,20 @@ export type RenderItemFn<T> = (item: T | null) => ReactElement;
 export interface ListViewRenderProps<T = unknown> {
     renderItem: RenderItemFn<T>;
 }
+/**
+ * Comparison function for sorting items by column.
+ * Returns negative if a < b, 0 if a === b, positive if a > b.
+ * @param a - First item to compare
+ * @param b - Second item to compare
+ * @param columnId - The ID of the column being sorted
+ */
+export type ColumnSortFn<T, C extends string = string> = (a: T, b: T, columnId: C) => number;
 export interface ColumnViewColumnProps {
     title?: string;
     expand?: boolean;
     resizable?: boolean;
     fixedWidth?: number;
+    id?: string;
     /**
      * Render function for column cells.
      * Called with null during setup (for loading state) and with the actual item during bind.
@@ -31,6 +45,12 @@ export interface ColumnViewColumnProps {
      */
     renderCell: (item: any) => ReactElement;
 }
+export interface ColumnViewRootProps<C extends string = string> {
+    sortColumn?: C | null;
+    sortOrder?: SortType;
+    onSortChange?: (column: C | null, order: SortType) => void;
+    sortFn?: ColumnSortFn<any, C>;
+}
 export interface NotebookPageProps extends SlotProps {
     label: string;
 }

package/package.json

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