@gtkx/components 0.21.0

package/dist/utils/realized-slot-store.js

@@ -0,0 +1,103 @@
+let nextKey = 0;
+export class RealizedSlotStore {
+    entries = new Map();
+    published = new Map();
+    setListeners = new Set();
+    positionListeners = new Map();
+    positionFlushers = new Map();
+    keys = new WeakMap();
+    snapshot = [];
+    subscribeSet = (onChange) => {
+        this.setListeners.add(onChange);
+        return () => {
+            this.setListeners.delete(onChange);
+        };
+    };
+    getSlotsSnapshot = () => this.snapshot;
+    subscribePosition = (container, onChange) => {
+        let listeners = this.positionListeners.get(container);
+        if (listeners === undefined) {
+            listeners = new Set();
+            this.positionListeners.set(container, listeners);
+        }
+        listeners.add(onChange);
+        return () => {
+            const current = this.positionListeners.get(container);
+            if (current === undefined)
+                return;
+            current.delete(onChange);
+            if (current.size === 0)
+                this.positionListeners.delete(container);
+        };
+    };
+    getPosition = (container) => {
+        let entry = this.published.get(container);
+        if (entry === undefined) {
+            entry = { container, position: -1, treeRow: null, item: null };
+            this.published.set(container, entry);
+        }
+        return entry;
+    };
+    keyFor = (container) => {
+        const existing = this.keys.get(container);
+        if (existing !== undefined)
+            return existing;
+        const key = `slot-${nextKey++}`;
+        this.keys.set(container, key);
+        return key;
+    };
+    addContainer = (container) => {
+        if (this.entries.has(container))
+            return;
+        this.entries.set(container, { container, position: -1, treeRow: null, item: null });
+        this.notifySet();
+    };
+    bind = (container, position, treeRow, item) => {
+        if (!this.entries.has(container)) {
+            this.entries.set(container, { container, position, treeRow, item });
+            this.notifySet();
+            return;
+        }
+        this.entries.set(container, { container, position, treeRow, item });
+        this.notifyPosition(container);
+    };
+    unbind = (container) => {
+        if (!this.entries.has(container))
+            return;
+        this.entries.set(container, { container, position: -1, treeRow: null, item: null });
+        this.notifyPosition(container);
+    };
+    removeContainer = (container) => {
+        if (!this.entries.delete(container))
+            return;
+        this.published.delete(container);
+        this.positionFlushers.delete(container);
+        this.notifySet();
+    };
+    flushSet = () => {
+        this.snapshot = [...this.entries.keys()];
+        for (const listener of [...this.setListeners])
+            listener();
+    };
+    notifySet() {
+        this.flushSet();
+    }
+    notifyPosition(container) {
+        let flush = this.positionFlushers.get(container);
+        if (flush === undefined) {
+            flush = () => {
+                const live = this.entries.get(container);
+                if (live !== undefined)
+                    this.published.set(container, live);
+                const listeners = this.positionListeners.get(container);
+                if (listeners === undefined)
+                    return;
+                for (const listener of [...listeners])
+                    listener();
+            };
+            this.positionFlushers.set(container, flush);
+        }
+        flush();
+    }
+}
+//# sourceMappingURL=realized-slot-store.js.map

package/dist/utils/realized-slot-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realized-slot-store.js","sourceRoot":"","sources":["../../src/utils/realized-slot-store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "@gtkx/components",
+    "version": "0.21.0",
+    "description": "Hand-written higher-level GTKX components: list, grid, column, drop-down, menu, and constraint-layout abstractions over the generated bindings",
+    "keywords": [
+        "gtkx",
+        "gtk",
+        "gtk4",
+        "adwaita",
+        "react",
+        "components",
+        "linux",
+        "desktop"
+    ],
+    "homepage": "https://gtkx.dev",
+    "bugs": {
+        "url": "https://github.com/gtkx-org/gtkx/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/gtkx-org/gtkx.git",
+        "directory": "packages/components"
+    },
+    "license": "MPL-2.0",
+    "author": "Eugenio Depalo <eugeniodepalo@gmail.com>",
+    "type": "module",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "source": "./src/index.ts",
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        }
+    },
+    "sideEffects": false,
+    "files": [
+        "dist",
+        "src"
+    ],
+    "scripts": {
+        "build": "tsc -b"
+    },
+    "engines": {
+        "node": ">=24"
+    },
+    "dependencies": {
+        "@gtkx/react": "workspace:*"
+    },
+    "devDependencies": {
+        "@gtkx/vitest": "workspace:*"
+    },
+    "peerDependencies": {
+        "react": "^19"
+    }
+}

package/src/collection-view.tsx

@@ -0,0 +1,125 @@
+import type * as Gio from "@gtkx/gi/gio";
+import type * as Gtk from "@gtkx/gi/gtk";
+import { useForwardedRef } from "@gtkx/react";
+import {
+    createElement,
+    type ElementType,
+    type ReactElement,
+    type ReactNode,
+    type Ref,
+    useCallback,
+    useRef,
+} from "react";
+import { useListModel } from "./hooks/use-list-model.js";
+import { useModelInstallation } from "./hooks/use-model-installation.js";
+import { type FactoryBinding, useRealizedSlots } from "./hooks/use-realized-slots.js";
+import { useSelectionModel } from "./hooks/use-selection-model.js";
+import { ListPortalHost } from "./list-portal-host.js";
+import type { SlotRenderer } from "./list-slot.js";
+import type { ListItem } from "./types.js";
+import type { ItemResolver } from "./utils/item-resolver.js";
+import type { RealizedSlotStore } from "./utils/realized-slot-store.js";
+
+export interface ModelBinding<W extends Gtk.Widget> {
+    install(widget: W, model: Gio.ListModel): void;
+}
+
+export interface CollectionViewProps<T, S, W extends Gtk.Widget> {
+    element: ElementType;
+    intrinsicProps: Record<string, unknown>;
+    ref: Ref<W | null> | undefined;
+    items: ListItem<T, S>[] | undefined;
+    model: Gio.ListModel | undefined;
+    renderItem: SlotRenderer<T, S>;
+    autoexpand: boolean | undefined;
+    renderHeader: ((value: S | undefined) => ReactNode) | undefined;
+    estimatedHeight: number | undefined;
+    estimatedWidth: number | undefined;
+    selected: string[] | null | undefined;
+    selectionMode: Gtk.SelectionMode | null | undefined;
+    onSelectionChanged: ((ids: string[]) => void) | null | undefined;
+    factoryBinding: FactoryBinding<W>;
+    headerFactoryBinding: FactoryBinding<W> | undefined;
+    modelBinding: ModelBinding<W>;
+    children?: ReactNode;
+}
+
+const headerRenderer =
+    <T, S>(renderHeader: ((value: S | undefined) => ReactNode) | undefined): SlotRenderer<T, S> =>
+    (value) =>
+        renderHeader ? renderHeader(value as S | undefined) : null;
+
+interface CollectionWiring<T, S, W extends Gtk.Widget> {
+    setRef: (value: W | null) => void;
+    resolver: ItemResolver<T, S>;
+    headerResolver: ItemResolver<T, S>;
+    itemStore: RealizedSlotStore;
+    headerStore: RealizedSlotStore;
+}
+
+const useCollectionWiring = <T, S, W extends Gtk.Widget>(
+    props: CollectionViewProps<T, S, W>,
+): CollectionWiring<T, S, W> => {
+    const widgetRef = useRef<W | null>(null);
+    const captureWidget = useCallback((value: W | null) => {
+        widgetRef.current = value;
+    }, []);
+    const [, setRef] = useForwardedRef<W>(props.ref, captureWidget);
+
+    const externalModel = props.model;
+    const listModel = useListModel<T, S>(
+        externalModel === undefined ? { items: props.items, autoexpand: props.autoexpand } : { model: externalModel },
+    );
+
+    const controlledSelection = useSelectionModel<T, S>({
+        base: listModel.model,
+        selectionMode: props.selectionMode,
+        selected: props.selected,
+        onSelectionChanged: props.onSelectionChanged,
+        resolver: listModel.resolver,
+    });
+    const installedModel: Gio.ListModel = externalModel === undefined ? controlledSelection : externalModel;
+
+    const items = useRealizedSlots<W>({
+        target: widgetRef,
+        binding: props.factoryBinding,
+        estimatedHeight: props.estimatedHeight,
+        estimatedWidth: props.estimatedWidth,
+    });
+    const headers = useRealizedSlots<W>({
+        target: props.headerFactoryBinding ? widgetRef : null,
+        binding: props.headerFactoryBinding ?? props.factoryBinding,
+        estimatedHeight: props.estimatedHeight,
+        estimatedWidth: props.estimatedWidth,
+    });
+
+    useModelInstallation(widgetRef, installedModel, (widget, model) => props.modelBinding.install(widget, model));
+
+    return {
+        setRef,
+        resolver: listModel.resolver,
+        headerResolver: listModel.headerResolver,
+        itemStore: items.store,
+        headerStore: headers.store,
+    };
+};
+
+export const CollectionView = <T, S, W extends Gtk.Widget>(props: CollectionViewProps<T, S, W>): ReactNode => {
+    const { setRef, resolver, headerResolver, itemStore, headerStore } = useCollectionWiring(props);
+    const intrinsic: ReactElement = createElement(props.element, { ...props.intrinsicProps, ref: setRef });
+
+    return (
+        <>
+            {intrinsic}
+            <ListPortalHost store={itemStore} resolver={resolver} render={props.renderItem} />
+            {props.headerFactoryBinding ? (
+                <ListPortalHost
+                    store={headerStore}
+                    resolver={headerResolver}
+                    render={headerRenderer<T, S>(props.renderHeader)}
+                />
+            ) : null}
+            {props.children}
+        </>
+    );
+};

package/src/column-view-column.tsx

@@ -0,0 +1,73 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { GtkColumnViewColumn, type GtkColumnViewColumnProps } from "@gtkx/jsx/gtk";
+import { createElement, type ReactNode, useLayoutEffect, useRef, useState } from "react";
+import { useColumnViewContext } from "./contexts/column-view-context.js";
+import { useHeaderMenu } from "./hooks/use-header-menu.js";
+import { type FactoryBinding, useRealizedSlots } from "./hooks/use-realized-slots.js";
+import { ListPortalHost } from "./list-portal-host.js";
+import type { SlotRenderer } from "./list-slot.js";
+import type { ColumnViewColumnProps } from "./types.js";
+
+const factoryBinding: FactoryBinding<Gtk.ColumnViewColumn> = {
+    install: (column, factory) => column.setFactory(factory),
+    uninstall: (column) => column.setFactory(null),
+};
+
+/**
+ * Props for the {@link ColumnViewColumn} component: the raw
+ * `GtkColumnViewColumn` element surface (minus its imperative `factory` and
+ * `sorter` properties) with its cell wiring replaced by the declarative
+ * {@link ColumnViewColumnProps} API.
+ */
+export type ColumnViewColumnComponentProps<T = unknown> = Omit<GtkColumnViewColumnProps, "factory" | "sorter"> &
+    ColumnViewColumnProps<T>;
+
+/**
+ * A single column of a {@link ColumnView}, rendering each row's cell through
+ * the declarative `renderCell` callback and optionally attaching a header
+ * context menu.
+ */
+export const ColumnViewColumn = <T = unknown>(props: ColumnViewColumnComponentProps<T>): ReactNode => {
+    const { id, title, expand, resizable, fixedWidth, visible, sortable, renderCell, headerMenu } = props;
+    const context = useColumnViewContext();
+    const [column, setColumn] = useState<Gtk.ColumnViewColumn | null>(null);
+
+    const captureColumn = useRef((value: Gtk.ColumnViewColumn | null) => {
+        setColumn(value);
+    }).current;
+
+    const { store } = useRealizedSlots<Gtk.ColumnViewColumn>({
+        target: column,
+        binding: factoryBinding,
+    });
+
+    const registerRef = useRef(context.register);
+    registerRef.current = context.register;
+    const unregisterRef = useRef(context.unregister);
+    unregisterRef.current = context.unregister;
+
+    useLayoutEffect(() => {
+        if (column === null) return;
+        registerRef.current({ id, column, sortable: sortable ?? false });
+        return () => unregisterRef.current(id);
+    }, [column, id, sortable]);
+
+    const headerMenuPortal = useHeaderMenu(column, headerMenu);
+
+    const slotRenderer: SlotRenderer<unknown, unknown> = (value, _treeRow, isHeader) =>
+        isHeader ? null : renderCell(value as T);
+
+    const intrinsicProps: Record<string, unknown> = { id, title, ref: captureColumn };
+    if (expand !== undefined) intrinsicProps["expand"] = expand;
+    if (resizable !== undefined) intrinsicProps["resizable"] = resizable;
+    if (fixedWidth !== undefined) intrinsicProps["fixedWidth"] = fixedWidth;
+    if (visible !== undefined) intrinsicProps["visible"] = visible;
+
+    return (
+        <>
+            {createElement(GtkColumnViewColumn, intrinsicProps)}
+            <ListPortalHost store={store} resolver={context.resolver} render={slotRenderer} />
+            {headerMenuPortal}
+        </>
+    );
+};

package/src/column-view.tsx

@@ -0,0 +1,206 @@
+import type * as Gio from "@gtkx/gi/gio";
+import type * as Gtk from "@gtkx/gi/gtk";
+import { GtkColumnView, type GtkColumnViewProps } from "@gtkx/jsx/gtk";
+import { useForwardedRef } from "@gtkx/react";
+import { createElement, type ReactNode, type Ref, useCallback, useMemo, useRef, useState } from "react";
+import {
+    type ColumnRegistration,
+    ColumnViewContext,
+    type ColumnViewContextValue,
+} from "./contexts/column-view-context.js";
+import { useListModel } from "./hooks/use-list-model.js";
+import { useModelInstallation } from "./hooks/use-model-installation.js";
+import { type FactoryBinding, useRealizedSlots } from "./hooks/use-realized-slots.js";
+import { useSelectionModel } from "./hooks/use-selection-model.js";
+import { useSortHandler } from "./hooks/use-sort-handler.js";
+import { ListPortalHost } from "./list-portal-host.js";
+import type { SlotRenderer } from "./list-slot.js";
+import type { ColumnViewProps } from "./types.js";
+import type { ItemResolver } from "./utils/item-resolver.js";
+
+const headerFactoryBinding: FactoryBinding<Gtk.ColumnView> = {
+    install: (widget, factory) => widget.setHeaderFactory(factory),
+    uninstall: (widget) => widget.setHeaderFactory(null),
+};
+
+interface ColumnRegistry {
+    columns: ColumnRegistration[];
+    register(registration: ColumnRegistration): void;
+    unregister(id: string): void;
+}
+
+const useColumnRegistry = (): ColumnRegistry => {
+    const [registrations, setRegistrations] = useState<Map<string, ColumnRegistration>>(() => new Map());
+    const register = useCallback((registration: ColumnRegistration): void => {
+        setRegistrations((current) => {
+            const next = new Map(current);
+            next.set(registration.id, registration);
+            return next;
+        });
+    }, []);
+    const unregister = useCallback((id: string): void => {
+        setRegistrations((current) => {
+            if (!current.has(id)) return current;
+            const next = new Map(current);
+            next.delete(id);
+            return next;
+        });
+    }, []);
+    const columns = useMemo(() => [...registrations.values()], [registrations]);
+    return { columns, register, unregister };
+};
+
+/**
+ * Props for the {@link ColumnView} component: the raw `GtkColumnView` element
+ * surface (minus its imperative `columns` property) with its model/sort wiring
+ * replaced by the declarative {@link ColumnViewProps} API. Columns are declared
+ * as {@link ColumnViewColumn} children.
+ */
+export type ColumnViewComponentProps<T = unknown, S = unknown> = Omit<
+    GtkColumnViewProps,
+    "columns" | keyof ColumnViewProps<T, S>
+> &
+    ColumnViewProps<T, S>;
+
+type NormalizedColumnViewProps<T, S> = ColumnViewProps<T, S> & {
+    ref?: Ref<Gtk.ColumnView | null>;
+    renderHeader?: ((value: S) => ReactNode) | null;
+    children?: ReactNode;
+    [key: string]: unknown;
+};
+
+const headerRenderer =
+    <T, S>(renderHeader: ((value: S) => ReactNode) | null | undefined): SlotRenderer<T, S> =>
+    (value) =>
+        renderHeader ? renderHeader(value as S) : null;
+
+interface ColumnViewWiring<T, S> {
+    setRef: (value: Gtk.ColumnView | null) => void;
+    resolver: ItemResolver<T, S>;
+    headerResolver: ItemResolver<T, S>;
+    headerStore: ReturnType<typeof useRealizedSlots>["store"];
+    useHeader: boolean;
+    contextValue: ColumnViewContextValue;
+}
+
+const useColumnViewWiring = <T, S>(
+    props: NormalizedColumnViewProps<T, S>,
+    registry: ColumnRegistry,
+): ColumnViewWiring<T, S> => {
+    const widgetRef = useRef<Gtk.ColumnView | null>(null);
+    const captureWidget = useCallback((value: Gtk.ColumnView | null) => {
+        widgetRef.current = value;
+    }, []);
+    const [, setRef] = useForwardedRef<Gtk.ColumnView>(props.ref, captureWidget);
+
+    const externalModel = props.model as Gio.ListModel | undefined;
+    const listModel = useListModel<T, S>(
+        externalModel === undefined ? { items: props.items } : { model: externalModel },
+    );
+
+    const controlledSelection = useSelectionModel<T, S>({
+        base: listModel.model,
+        selectionMode: props.selectionMode,
+        selected: props.selected,
+        onSelectionChanged: props.onSelectionChanged,
+        resolver: listModel.resolver,
+    });
+    const installedModel: Gtk.SelectionModel =
+        externalModel === undefined ? controlledSelection : (externalModel as Gtk.SelectionModel);
+    useModelInstallation(widgetRef, installedModel, (widget, model) => widget.setModel(model));
+
+    const useHeader = externalModel === undefined && typeof props.renderHeader === "function";
+    const headers = useRealizedSlots<Gtk.ColumnView>({
+        target: useHeader ? widgetRef : null,
+        binding: headerFactoryBinding,
+        estimatedHeight: props.estimatedRowHeight ?? undefined,
+    });
+
+    useSortHandler({
+        columnView: widgetRef,
+        sortColumn: props.sortColumn,
+        sortOrder: props.sortOrder,
+        onSortChanged: props.onSortChanged,
+        columns: registry.columns,
+    });
+
+    const contextValue = useMemo<ColumnViewContextValue>(
+        () => ({
+            columnView: widgetRef,
+            resolver: listModel.resolver as ItemResolver<unknown, unknown>,
+            register: registry.register,
+            unregister: registry.unregister,
+        }),
+        [listModel.resolver, registry.register, registry.unregister],
+    );
+
+    return {
+        setRef,
+        resolver: listModel.resolver,
+        headerResolver: listModel.headerResolver,
+        headerStore: headers.store,
+        useHeader,
+        contextValue,
+    };
+};
+
+/**
+ * A `GtkColumnView` driven by a declarative `items` model with 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 const ColumnView = <T = unknown, S = unknown>(props: ColumnViewComponentProps<T, S>): ReactNode => {
+    const {
+        ref,
+        items,
+        model,
+        selected,
+        selectionMode,
+        onSelectionChanged,
+        sortColumn,
+        sortOrder,
+        onSortChanged,
+        renderHeader,
+        estimatedRowHeight,
+        children,
+        ...intrinsicProps
+    } = props as NormalizedColumnViewProps<T, S>;
+
+    const registry = useColumnRegistry();
+    const wiring = useColumnViewWiring<T, S>(
+        {
+            ref,
+            items,
+            model,
+            selected,
+            selectionMode,
+            onSelectionChanged,
+            sortColumn,
+            sortOrder,
+            onSortChanged,
+            renderHeader,
+            estimatedRowHeight,
+        } as NormalizedColumnViewProps<T, S>,
+        registry,
+    );
+
+    const intrinsic = createElement(
+        GtkColumnView,
+        { ...intrinsicProps, ref: wiring.setRef },
+        <ColumnViewContext.Provider value={wiring.contextValue}>{children}</ColumnViewContext.Provider>,
+    );
+
+    return (
+        <>
+            {intrinsic}
+            {wiring.useHeader ? (
+                <ListPortalHost
+                    store={wiring.headerStore}
+                    resolver={wiring.headerResolver}
+                    render={headerRenderer<T, S>(renderHeader)}
+                />
+            ) : null}
+        </>
+    );
+};