@gtkx/components 0.21.0

package/src/list-view.tsx

@@ -0,0 +1,85 @@
+import type * as Gio from "@gtkx/gi/gio";
+import type * as Gtk from "@gtkx/gi/gtk";
+import { GtkListView, type GtkListViewProps } from "@gtkx/jsx/gtk";
+import type { ReactNode, Ref } from "react";
+import { CollectionView, type ModelBinding } from "./collection-view.js";
+import type { SlotRenderer } from "./list-slot.js";
+import type { ListViewProps } from "./types.js";
+
+const factoryBinding = {
+    install: (widget: Gtk.ListView, factory: Gtk.SignalListItemFactory) => widget.setFactory(factory),
+    uninstall: (widget: Gtk.ListView) => widget.setFactory(null),
+};
+
+const headerFactoryBinding = {
+    install: (widget: Gtk.ListView, factory: Gtk.SignalListItemFactory) => widget.setHeaderFactory(factory),
+    uninstall: (widget: Gtk.ListView) => widget.setHeaderFactory(null),
+};
+
+const modelBinding: ModelBinding<Gtk.ListView> = {
+    install: (widget, model) => widget.setModel(model as Gtk.SelectionModel),
+};
+
+/**
+ * Props for the {@link ListView} component: the raw `GtkListView` element
+ * surface with its factory/model wiring replaced by the declarative
+ * {@link ListViewProps} API.
+ */
+export type ListViewComponentProps<T = unknown, S = unknown> = Omit<GtkListViewProps, keyof ListViewProps<T, S>> &
+    ListViewProps<T, S>;
+
+/**
+ * A `GtkListView` driven by a declarative `items`/`renderItem` API with
+ * optional controlled selection, section headers, and tree autoexpansion.
+ * Supplying an external `model` switches to the uncontrolled form.
+ */
+export const ListView = <T = unknown, S = unknown>(props: ListViewComponentProps<T, S>): ReactNode => {
+    const {
+        ref,
+        items,
+        model,
+        renderItem,
+        autoexpand,
+        renderHeader,
+        selected,
+        selectionMode,
+        onSelectionChanged,
+        estimatedItemHeight,
+        estimatedItemWidth,
+        ...intrinsicProps
+    } = props as ListViewProps<T, S> & {
+        ref?: Ref<Gtk.ListView | null>;
+        estimatedItemHeight?: number;
+        estimatedItemWidth?: number;
+        [key: string]: unknown;
+    };
+
+    const renderItemFn = renderItem as (item: T, row?: Gtk.TreeListRow | null) => ReactNode;
+    const slotRenderer: SlotRenderer<T, S> = (value, treeRow, isHeader) => {
+        if (isHeader) return null;
+        return treeRow === null ? renderItemFn(value as T) : renderItemFn(value as T, treeRow);
+    };
+
+    const useHeader = model === undefined && typeof renderHeader === "function";
+
+    return (
+        <CollectionView<T, S, Gtk.ListView>
+            element={GtkListView}
+            intrinsicProps={intrinsicProps}
+            ref={ref}
+            items={model === undefined ? items : undefined}
+            model={model as Gio.ListModel | undefined}
+            renderItem={slotRenderer}
+            autoexpand={autoexpand}
+            renderHeader={useHeader ? (value) => renderHeader?.(value as S) ?? null : undefined}
+            estimatedHeight={estimatedItemHeight}
+            estimatedWidth={estimatedItemWidth}
+            selected={selected}
+            selectionMode={selectionMode}
+            onSelectionChanged={onSelectionChanged}
+            factoryBinding={factoryBinding}
+            headerFactoryBinding={useHeader ? headerFactoryBinding : undefined}
+            modelBinding={modelBinding}
+        />
+    );
+};

package/src/menu-items.ts

@@ -0,0 +1,48 @@
+import * as Gio from "@gtkx/gi/gio";
+import type { MenuEntry } from "./types.js";
+
+const buildMenuModel = (entries: MenuEntry[]): Gio.Menu => {
+    const menu = new Gio.Menu();
+    appendEntries(menu, entries);
+    return menu;
+};
+
+const appendEntries = (menu: Gio.Menu, entries: MenuEntry[]): void => {
+    for (const entry of entries) {
+        if (entry.section !== undefined) {
+            menu.appendSection(entry.label ?? null, buildMenuModel(entry.section));
+            continue;
+        }
+        if (entry.submenu !== undefined) {
+            menu.appendSubmenu(entry.label ?? null, buildMenuModel(entry.submenu));
+            continue;
+        }
+        const item = new Gio.MenuItem();
+        if (entry.label !== undefined) item.setLabel(entry.label);
+        if (entry.action !== undefined) item.setDetailedAction(entry.action);
+        menu.appendItem(item);
+    }
+};
+
+export const applyMenuItems = (menu: Gio.Menu, entries: MenuEntry[] | null): void => {
+    menu.removeAll();
+    if (entries) appendEntries(menu, entries);
+};
+
+const entryEqual = (a: MenuEntry, b: MenuEntry): boolean =>
+    a.label === b.label &&
+    a.action === b.action &&
+    entryListEqual(a.submenu, b.submenu) &&
+    entryListEqual(a.section, b.section);
+
+const entryListEqual = (a: MenuEntry[] | undefined, b: MenuEntry[] | undefined): boolean => {
+    if (a === b) return true;
+    if (a === undefined || b === undefined) return false;
+    return a.length === b.length && a.every((entry, index) => entryEqual(entry, b[index] as MenuEntry));
+};
+
+export const menuItemsEqual = (a: MenuEntry[] | null, b: MenuEntry[] | null): boolean => {
+    if (a === b) return true;
+    if (a === null || b === null) return false;
+    return entryListEqual(a, b);
+};

package/src/menu.tsx

@@ -0,0 +1,34 @@
+import type * as Gio from "@gtkx/gi/gio";
+import { GMenu, type GMenuProps } from "@gtkx/jsx/gio";
+import { useForwardedRef } from "@gtkx/react";
+import { createElement, type ReactNode, type Ref, useLayoutEffect, useRef } from "react";
+import { applyMenuItems, menuItemsEqual } from "./menu-items.js";
+import type { MenuEntry, MenuItemsProps } from "./types.js";
+
+/**
+ * Props for the {@link Menu} component: the raw `GMenu` element surface with a
+ * declarative `items` model layered on top.
+ */
+export type MenuProps = Omit<GMenuProps, keyof MenuItemsProps> & MenuItemsProps & { ref?: Ref<Gio.Menu | null> };
+
+/**
+ * A declarative `Gio.Menu` built from an `items` tree of {@link MenuEntry}
+ * values. Rebuilds the underlying menu model whenever the item structure
+ * changes.
+ */
+export const Menu = (props: MenuProps): ReactNode => {
+    const { items, ref, ...rest } = props;
+    const [menuRef, mergedRef] = useForwardedRef(ref);
+    const appliedRef = useRef<MenuEntry[] | null>(null);
+
+    useLayoutEffect(() => {
+        const menu = menuRef.current;
+        if (!menu) return;
+        const entries = items ?? null;
+        if (menuItemsEqual(appliedRef.current, entries)) return;
+        appliedRef.current = entries;
+        applyMenuItems(menu, entries);
+    });
+
+    return createElement(GMenu, { ...rest, ref: mergedRef });
+};

package/src/types.ts

@@ -0,0 +1,227 @@
+import type * as Gio from "@gtkx/gi/gio";
+import type * as GObject from "@gtkx/gi/gobject";
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { ReactNode } from "react";
+
+/**
+ * A declarative item rendered by the {@link ListView}, {@link GridView},
+ * {@link ColumnView}, and {@link DropDown} components.
+ *
+ * A non-section item carries an arbitrary value of type `T` and may declare
+ * tree `children`. A section item carries a value of type `S` and groups a list
+ * of child items underneath a header.
+ */
+export type ListItem<T = unknown, S = unknown> =
+    | {
+          id: string;
+          value: T;
+          section?: false | undefined;
+          children?: ListItem<T, S>[] | undefined;
+          hideExpander?: boolean | undefined;
+          indentForDepth?: boolean | undefined;
+          indentForIcon?: boolean | undefined;
+      }
+    | {
+          id: string;
+          value: S;
+          section: true;
+          children: ListItem<T, S>[];
+      };
+
+type ListViewSharedProps = {
+    estimatedItemHeight?: number | undefined;
+    estimatedItemWidth?: number | undefined;
+};
+
+type ListViewControlledSelectionProps = {
+    selected?: string[] | null | undefined;
+    onSelectionChanged?: ((ids: string[]) => void) | null | undefined;
+    selectionMode?: Gtk.SelectionMode | null | undefined;
+};
+
+type UncontrolledItemType<T> = [T] extends [GObject.Object] ? T : GObject.Object;
+
+/**
+ * Props for the {@link ListView} component, replacing the raw `GtkListView`
+ * factory/model surface with a declarative `items`/`renderItem` API, optional
+ * controlled selection, section headers, and tree autoexpansion. Supplying an
+ * external `model` switches to the uncontrolled form.
+ */
+export type ListViewProps<T = unknown, S = unknown> = ListViewSharedProps &
+    (
+        | (ListViewControlledSelectionProps & {
+              items?: ListItem<T, S>[] | undefined;
+              renderItem: (item: T, row?: Gtk.TreeListRow | null) => ReactNode;
+              autoexpand?: boolean | undefined;
+              renderHeader?: ((item: S) => ReactNode) | null | undefined;
+              model?: never;
+          })
+        | {
+              model: Gio.ListModel;
+              renderItem: (item: UncontrolledItemType<T>) => ReactNode;
+              items?: never;
+              autoexpand?: never;
+              renderHeader?: never;
+              selected?: never;
+              onSelectionChanged?: never;
+              selectionMode?: never;
+          }
+    );
+
+/**
+ * Props for the {@link GridView} component, replacing the raw `GtkGridView`
+ * factory/model surface with a declarative `items`/`renderItem` API and
+ * optional controlled selection. Supplying an external `model` switches to the
+ * uncontrolled form.
+ */
+export type GridViewProps<T = unknown> = ListViewSharedProps &
+    (
+        | (ListViewControlledSelectionProps & {
+              items?: ListItem<T>[] | undefined;
+              renderItem: (item: T) => ReactNode;
+              model?: never;
+          })
+        | {
+              model: Gio.ListModel;
+              renderItem: (item: UncontrolledItemType<T>) => ReactNode;
+              items?: never;
+              selected?: never;
+              onSelectionChanged?: never;
+              selectionMode?: never;
+          }
+    );
+
+type ColumnViewSortProps = {
+    sortColumn?: string | null | undefined;
+    sortOrder?: Gtk.SortType | null | undefined;
+    onSortChanged?: ((column: string | null, order: Gtk.SortType) => void) | null | undefined;
+    estimatedRowHeight?: number | null | undefined;
+};
+
+/**
+ * Props for the {@link ColumnView} component, replacing the raw `GtkColumnView`
+ * surface with a declarative `items` model, optional controlled selection,
+ * controlled sorting, and section headers. Columns are declared as
+ * {@link ColumnViewColumn} children. Supplying an external `model` switches to
+ * the uncontrolled form.
+ */
+export type ColumnViewProps<T = unknown, S = unknown> = ColumnViewSortProps &
+    (
+        | (ListViewControlledSelectionProps & {
+              items?: ListItem<T, S>[] | undefined;
+              renderHeader?: ((item: S) => ReactNode) | null | undefined;
+              model?: never;
+          })
+        | {
+              model: Gio.ListModel;
+              items?: never;
+              renderHeader?: never;
+              selected?: never;
+              onSelectionChanged?: never;
+              selectionMode?: never;
+          }
+    );
+
+/**
+ * Props for a single {@link ColumnViewColumn} of a {@link ColumnView},
+ * replacing the raw `GtkColumnViewColumn` factory/sorter surface with a
+ * declarative `renderCell` callback and an optional header context menu.
+ */
+export type ColumnViewColumnProps<T = unknown> = {
+    title: string;
+    expand?: boolean | undefined;
+    resizable?: boolean | undefined;
+    fixedWidth?: number | undefined;
+    id: string;
+    sortable?: boolean | undefined;
+    visible?: boolean | undefined;
+    renderCell: (item: T) => ReactNode;
+    headerMenu?: ReactNode;
+};
+
+/**
+ * Props shared by the {@link DropDown} and {@link ComboRow} components,
+ * replacing the raw factory/model surface with declarative `items`, controlled
+ * `selectedId`, and per-slot renderers for the selected face, the popup list,
+ * and section headers. Supplying an external `model` switches to the
+ * uncontrolled form.
+ */
+export type DropDownProps<T = unknown, S = unknown> =
+    | {
+          items?: ListItem<T, S>[] | undefined;
+          selectedId?: string | null | undefined;
+          onSelectionChanged?: ((id: string) => void) | null | undefined;
+          renderItem?: ((item: T) => ReactNode) | null | undefined;
+          renderListItem?: ((item: T) => ReactNode) | null | undefined;
+          renderHeader?: ((item: S) => ReactNode) | null | undefined;
+          model?: never;
+      }
+    | {
+          model: Gio.ListModel;
+          renderItem?: ((item: UncontrolledItemType<T>) => ReactNode) | null | undefined;
+          renderListItem?: ((item: UncontrolledItemType<T>) => ReactNode) | null | undefined;
+          items?: never;
+          selectedId?: never;
+          onSelectionChanged?: never;
+          renderHeader?: never;
+      };
+
+/**
+ * A single declarative entry in a {@link Menu} model. An entry is a plain item
+ * (`label` plus `action`), a `submenu`, or a `section` of nested entries.
+ */
+export type MenuEntry = {
+    label?: string | undefined;
+    action?: string | undefined;
+    submenu?: MenuEntry[] | undefined;
+    section?: MenuEntry[] | undefined;
+};
+
+/**
+ * The declarative menu-model surface added by the {@link Menu} component on top
+ * of the raw `GMenu` element.
+ */
+export type MenuItemsProps = {
+    items?: MenuEntry[] | null | undefined;
+};
+
+/**
+ * Props for a `<ConstraintLayout.Constraint>` declaring a single relation
+ * between a target attribute and a source attribute within a
+ * {@link ConstraintLayout}.
+ */
+export type ConstraintProps = {
+    target?: string;
+    targetAttribute: Gtk.ConstraintAttribute;
+    relation?: Gtk.ConstraintRelation;
+    source?: string;
+    sourceAttribute?: Gtk.ConstraintAttribute;
+    multiplier?: number;
+    constant?: number;
+    strength?: number;
+};
+
+/**
+ * Props for a `<ConstraintLayout.Guide>` declaring an invisible layout guide
+ * that other constraints can reference by `id` within a {@link ConstraintLayout}.
+ */
+export type ConstraintGuideProps = {
+    id: string;
+    minWidth?: number;
+    minHeight?: number;
+    natWidth?: number;
+    natHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    strength?: Gtk.ConstraintStrength;
+};
+
+/**
+ * Props for a `<ConstraintLayout.Vfl>` declaring constraints through the GTK
+ * Visual Format Language within a {@link ConstraintLayout}.
+ */
+export type ConstraintVflProps = {
+    lines: string[];
+    hspacing?: number;
+    vspacing?: number;
+};

package/src/utils/item-resolver.ts

@@ -0,0 +1,143 @@
+import type * as Gio from "@gtkx/gi/gio";
+import type * as GObject from "@gtkx/gi/gobject";
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { ListItem } from "../types.js";
+import { flattenListItems, type TreeItemMetadata } from "./list-item-flatten.js";
+
+const NO_TREE_METADATA: TreeItemMetadata = { hideExpander: false, indentForDepth: true, indentForIcon: true };
+
+const treeItemCache = new WeakMap<Gtk.TreeListRow, GObject.Object>();
+
+const treeRowItem = (treeRow: Gtk.TreeListRow): GObject.Object | null => {
+    const cached = treeItemCache.get(treeRow);
+    if (cached !== undefined) return cached;
+    const item = treeRow.getItem();
+    if (item !== null) treeItemCache.set(treeRow, item);
+    return item;
+};
+
+export interface Resolved<T = unknown, S = unknown> {
+    value: T | S | undefined;
+    present: boolean;
+    isHeader: boolean;
+    treeRow: Gtk.TreeListRow | null;
+    metadata: TreeItemMetadata;
+}
+
+export interface ItemResolver<T = unknown, S = unknown> {
+    resolve(position: number, treeRow: Gtk.TreeListRow | null, boundItem: GObject.Object | null): Resolved<T, S>;
+    positionOf(id: string): number;
+    idOf(position: number): string | undefined;
+    count: number;
+}
+
+export interface RowValue<T = unknown, S = unknown> {
+    id: string;
+    value: T | S;
+    isHeader: boolean;
+    metadata: TreeItemMetadata;
+}
+
+export const createControlledResolver = <T, S>(
+    items: ListItem<T, S>[] | undefined,
+    flattenTreeChildren: boolean,
+    rowValues: WeakMap<GObject.Object, RowValue<T, S>>,
+): ItemResolver<T, S> => {
+    const flattened = flattenListItems(items, flattenTreeChildren);
+    return {
+        count: flattened.records.length,
+        positionOf(id: string): number {
+            const position = flattened.idToPosition.get(id);
+            return position === undefined ? -1 : position;
+        },
+        idOf(position: number): string | undefined {
+            return flattened.positionToId.get(position);
+        },
+        resolve(position: number, treeRow: Gtk.TreeListRow | null, _boundItem: GObject.Object | null): Resolved<T, S> {
+            if (treeRow !== null && !flattenTreeChildren) {
+                const rowItem = treeRowItem(treeRow);
+                if (rowItem !== null) {
+                    const tagged = rowValues.get(rowItem);
+                    if (tagged !== undefined) {
+                        return {
+                            value: tagged.value,
+                            present: true,
+                            isHeader: tagged.isHeader,
+                            treeRow,
+                            metadata: tagged.metadata,
+                        };
+                    }
+                }
+            }
+            const record = flattened.records[position];
+            if (record === undefined) {
+                return {
+                    value: undefined,
+                    present: false,
+                    isHeader: false,
+                    treeRow,
+                    metadata: NO_TREE_METADATA,
+                };
+            }
+            return {
+                value: record.value,
+                present: true,
+                isHeader: record.isHeader,
+                treeRow,
+                metadata: record.metadata,
+            };
+        },
+    };
+};
+
+export const createModelResolver = <T, S>(model: Gio.ListModel): ItemResolver<T, S> => {
+    return {
+        get count(): number {
+            return model.getNItems();
+        },
+        positionOf(id: string): number {
+            const numeric = Number(id);
+            return Number.isInteger(numeric) ? numeric : -1;
+        },
+        idOf(position: number): string {
+            return String(position);
+        },
+        resolve(position: number, treeRow: Gtk.TreeListRow | null, boundItem: GObject.Object | null): Resolved<T, S> {
+            const item = boundItem ?? model.getItem(position);
+            return {
+                value: (item ?? undefined) as T | undefined,
+                present: item !== null,
+                isHeader: false,
+                treeRow,
+                metadata: NO_TREE_METADATA,
+            };
+        },
+    };
+};
+
+export const createSectionHeaderResolver = <T, S>(items: ListItem<T, S>[] | undefined): ItemResolver<T, S> => {
+    const valueByStart = new Map<number, S>();
+    let start = 0;
+    for (const section of items ?? []) {
+        if (section.section !== true) continue;
+        valueByStart.set(start, section.value);
+        start += section.children?.length ?? 0;
+    }
+    return {
+        count: valueByStart.size,
+        positionOf: () => -1,
+        idOf: () => undefined,
+        resolve(position: number): Resolved<T, S> {
+            if (!valueByStart.has(position)) {
+                return { value: undefined, present: false, isHeader: true, treeRow: null, metadata: NO_TREE_METADATA };
+            }
+            return {
+                value: valueByStart.get(position),
+                present: true,
+                isHeader: true,
+                treeRow: null,
+                metadata: NO_TREE_METADATA,
+            };
+        },
+    };
+};

package/src/utils/list-item-flatten.ts

@@ -0,0 +1,113 @@
+import type { ListItem } from "../types.js";
+
+export interface TreeItemMetadata {
+    hideExpander: boolean;
+    indentForDepth: boolean;
+    indentForIcon: boolean;
+}
+
+export interface FlattenedRecord<T = unknown, S = unknown> {
+    id: string;
+    value: T | S;
+    isHeader: boolean;
+    hasChildren: boolean;
+    children: ListItem<T, S>[];
+    metadata: TreeItemMetadata;
+}
+
+export interface FlattenResult<T = unknown, S = unknown> {
+    records: FlattenedRecord<T, S>[];
+    idToPosition: Map<string, number>;
+    positionToId: Map<number, string>;
+    isTree: boolean;
+    isSectioned: boolean;
+}
+
+export type ListStructure = "flat" | "tree" | "sections";
+
+/**
+ * Classify a controlled item list as flat, tree, or sectioned without building a
+ * {@link FlattenResult}. A list is sectioned if any top-level item is a section, a
+ * tree if any top-level item carries children, and flat otherwise.
+ */
+export const detectStructure = <T, S>(items: ListItem<T, S>[] | undefined): ListStructure => {
+    if (items === undefined) return "flat";
+    let sawTree = false;
+    for (const item of items) {
+        if (item.section === true) return "sections";
+        if (item.children !== undefined && item.children.length > 0) sawTree = true;
+    }
+    return sawTree ? "tree" : "flat";
+};
+
+export const structuralSignature = <T, S>(items: ListItem<T, S>[] | undefined): string => {
+    if (items === undefined) return "";
+    const parts: string[] = [];
+    const walk = (list: ListItem<T, S>[]): void => {
+        parts.push("[");
+        for (const item of list) {
+            const hidden = item.section === true ? false : item.hideExpander === true;
+            parts.push(`${item.id}|${item.section === true ? 1 : 0}|${hidden ? 1 : 0}`);
+            if (item.children !== undefined && item.children.length > 0) walk(item.children);
+        }
+        parts.push("]");
+    };
+    walk(items);
+    return parts.join(",");
+};
+
+export const treeItemMetadata = <T, S>(item: ListItem<T, S>): TreeItemMetadata => {
+    if (item.section === true) {
+        return { hideExpander: false, indentForDepth: false, indentForIcon: false };
+    }
+    return {
+        hideExpander: item.hideExpander ?? false,
+        indentForDepth: item.indentForDepth ?? true,
+        indentForIcon: item.indentForIcon ?? true,
+    };
+};
+
+const hasChildren = <T, S>(item: ListItem<T, S>): boolean => item.children !== undefined && item.children.length > 0;
+
+const appendRecord = <T, S>(item: ListItem<T, S>, result: FlattenResult<T, S>, includeChildren: boolean): void => {
+    const position = result.records.length;
+    result.idToPosition.set(item.id, position);
+    result.positionToId.set(position, item.id);
+    result.records.push({
+        id: item.id,
+        value: item.value,
+        isHeader: item.section === true,
+        hasChildren: hasChildren(item),
+        children: item.children ?? [],
+        metadata: treeItemMetadata(item),
+    });
+    if (includeChildren && item.children !== undefined) {
+        for (const child of item.children) appendRecord(child, result, includeChildren);
+    }
+};
+
+export const flattenListItems = <T, S>(
+    items: ListItem<T, S>[] | undefined,
+    flattenTreeChildren: boolean,
+): FlattenResult<T, S> => {
+    const result: FlattenResult<T, S> = {
+        records: [],
+        idToPosition: new Map(),
+        positionToId: new Map(),
+        isTree: false,
+        isSectioned: false,
+    };
+    if (items === undefined) return result;
+    for (const item of items) {
+        if (item.section === true) {
+            result.isSectioned = true;
+            if (item.children !== undefined) {
+                for (const child of item.children) appendRecord(child, result, true);
+            }
+            continue;
+        }
+        if (hasChildren(item)) result.isTree = true;
+        appendRecord(item, result, flattenTreeChildren);
+    }
+    return result;
+};