@gtkx/components 0.21.0 → 1.0.0-rc.2

package/package.json

@@ -1,55 +1,65 @@
 {
-    "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"
+  "name": "@gtkx/components",
+  "version": "1.0.0-rc.2",
+  "description": "High-level GTKX components for declarative collection views, menus, and containers with attach-time placement",
+  "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": "git+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",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
-    "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"
+    "./adw": {
+      "types": "./dist/adw/index.d.ts",
+      "default": "./dist/adw/index.js"
     }
-}
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@gtkx/react": "1.0.0-rc.2",
+    "@gtkx/utils": "1.0.0-rc.2"
+  },
+  "peerDependencies": {
+    "react": "^19.2"
+  },
+  "devDependencies": {
+    "@codspeed/vitest-plugin": "^5.7.1",
+    "vitest": "^4.1.10",
+    "@gtkx/config": "1.0.0-rc.2",
+    "@gtkx/runtime": "1.0.0-rc.2",
+    "@gtkx/testing": "1.0.0-rc.2",
+    "@gtkx/vitest": "1.0.0-rc.2"
+  },
+  "scripts": {
+    "bench": "NODE_ENV=production vitest bench --run --config vitest.bench.config.ts",
+    "release": "tsx ../../scripts/release-package.ts"
+  }
+}

package/src/adw/index.ts

@@ -0,0 +1,2 @@
+export { ToastProvider, useToast, useToastOverlay } from "./toast.js";
+export type { ToastController, ToastOptions, ToastOverlayController, ToastProviderProps } from "./types.js";

package/src/adw/toast.tsx

@@ -0,0 +1,74 @@
+import type { ReactNode, RefObject } from "react";
+import * as Adw from "@gtkx/gi/adw";
+import { createContext, useContext, useMemo } from "react";
+import type { ToastController, ToastOptions, ToastOverlayController, ToastProviderProps } from "./types.js";
+
+type OverlayRef = RefObject<Adw.ToastOverlay | null>;
+
+const ToastContext = createContext<OverlayRef | null>(null);
+
+const useOverlayRef = (): OverlayRef => {
+    const overlayRef = useContext(ToastContext);
+
+    if (overlayRef === null) {
+        throw new Error("useToast and useToastOverlay must be used within a ToastProvider");
+    }
+
+    return overlayRef;
+};
+
+const buildToast = (options: ToastOptions): Adw.Toast => {
+    const { onButtonClicked, onDismissed, ...props } = options;
+    const toast = new Adw.Toast(props);
+
+    if (onButtonClicked != null) {
+        toast.on("button-clicked", onButtonClicked);
+    }
+
+    if (onDismissed != null) {
+        toast.on("dismissed", onDismissed);
+    }
+
+    return toast;
+};
+
+/** Shares an Adw.ToastOverlay reference with the toast hooks in every descendant. */
+function ToastProvider(props: ToastProviderProps): ReactNode {
+    return <ToastContext.Provider value={props.overlayRef}>{props.children}</ToastContext.Provider>;
+}
+
+/** Returns a {@link ToastController} that shows and dismisses toasts on the nearest provider's overlay. */
+function useToast(): ToastController {
+    const overlayRef = useOverlayRef();
+
+    return useMemo<ToastController>(
+        () => ({
+            show: (options?: ToastOptions) => {
+                const toast = buildToast(options ?? {});
+                overlayRef.current?.addToast(toast);
+
+                return toast;
+            },
+            dismiss: (toast: Adw.Toast) => {
+                toast.dismiss();
+            },
+        }),
+        [overlayRef],
+    );
+}
+
+/** Returns a {@link ToastOverlayController} for the nearest provider's overlay as a whole. */
+function useToastOverlay(): ToastOverlayController {
+    const overlayRef = useOverlayRef();
+
+    return useMemo<ToastOverlayController>(
+        () => ({
+            dismissAll: () => {
+                overlayRef.current?.dismissAll();
+            },
+        }),
+        [overlayRef],
+    );
+}
+
+export { ToastProvider, useToast, useToastOverlay };

package/src/adw/types.ts

@@ -0,0 +1,32 @@
+import type * as Adw from "@gtkx/gi/adw";
+import type { AdwToastProps } from "@gtkx/jsx/adw";
+import type { ReactNode, RefObject } from "react";
+
+/**
+ * Describes a toast raised through {@link useToast}: the construct-time properties of an
+ * `Adw.Toast` plus its `button-clicked` and `dismissed` handlers.
+ */
+type ToastOptions = Adw.ToastConstructorProps & Pick<AdwToastProps, "onButtonClicked" | "onDismissed">;
+
+/** Imperative controls for individual toasts, returned by {@link useToast}. */
+type ToastController = {
+    /** Builds a toast, shows it through the overlay, and returns it. */
+    show: (options?: ToastOptions) => Adw.Toast;
+    /** Dismisses a single toast, typically one returned by {@link ToastController.show}. */
+    dismiss: (toast: Adw.Toast) => void;
+};
+
+/** Imperative controls for the overlay as a whole, returned by {@link useToastOverlay}. */
+type ToastOverlayController = {
+    /** Dismisses the shown toast and every queued one. */
+    dismissAll: () => void;
+};
+
+/** Props for {@link ToastProvider}. */
+type ToastProviderProps = {
+    /** Ref also given to the `AdwToastOverlay` the toasts appear over. */
+    overlayRef: RefObject<Adw.ToastOverlay | null>;
+    children?: ReactNode | undefined;
+};
+
+export { type ToastOptions, type ToastController, type ToastOverlayController, type ToastProviderProps };

package/src/column-view.tsx

@@ -1,206 +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),
+import type { ReactNode } from "react";
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkColumnView, GtkColumnViewColumn, GtkCustomSorter, GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
+import { useProperty, useSignal } from "@gtkx/react";
+import { omit } from "@gtkx/utils";
+import { useLayoutEffect, useRef } from "react";
+import type { CellSize } from "./internal/cells.js";
+import type { Collection } from "./internal/collection.js";
+import type { Column, ColumnViewProps } from "./types.js";
+import { HeaderPortals, ItemPortals, useHeaderCells, useItemCells } from "./internal/cells.js";
+import { useCollection } from "./internal/use-collection.js";
+import { useWidgetRef } from "./internal/use-widget-ref.js";
+
+type SortProps = {
+    sortColumn?: string | null | undefined;
+    sortOrder?: Gtk.SortType | null | undefined;
+    onSortChanged?: ((column: string | null, order: Gtk.SortType) => void) | null | undefined;
 };
 
-interface ColumnRegistry {
-    columns: ColumnRegistration[];
-    register(registration: ColumnRegistration): void;
-    unregister(id: string): void;
-}
+type SortTarget = { view: Gtk.ColumnView; column: Gtk.ColumnViewColumn | null };
 
-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 };
+type ColumnCellsProps = {
+    column: Column<never>;
+    collection: Collection;
+    expandedIds: string[] | null | undefined;
+    size: CellSize;
 };
 
-/**
- * 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;
+type ColumnListProps = Omit<ColumnCellsProps, "column"> & {
+    columns: Column<never>[];
 };
 
-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 COLUMN_VIEW_PROPS = [
+    "items",
+    "sections",
+    "renderHeader",
+    "columns",
+    "selectedIds",
+    "onSelectionChanged",
+    "selectionMode",
+    "expandedIds",
+    "onExpandedChange",
+    "sortColumn",
+    "sortOrder",
+    "onSortChanged",
+    "estimatedItemHeight",
+    "children",
+    "ref",
+] as const satisfies (keyof ColumnViewProps)[];
+
+const columnById = (view: Gtk.ColumnView, id: string): Gtk.ColumnViewColumn | null => {
+    const columns = view.getColumns();
+
+    for (let index = 0; index < columns.getNItems(); index++) {
+        const column = columns.getItem(index);
+
+        if (column instanceof Gtk.ColumnViewColumn && column.getId() === id) {
+            return column;
+        }
+    }
+
+    return null;
+};
 
-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 getSortTarget = (view: Gtk.ColumnView | null, sortColumn: string | null | undefined): SortTarget | null => {
+    if (view === null || sortColumn === undefined) {
+        return null;
+    }
 
-    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,
-    });
+    if (sortColumn === null) {
+        return { view, column: null };
+    }
+
+    const column = columnById(view, sortColumn);
+
+    return column === null ? null : { view, column };
+};
+
+const applySort = (
+    sorting: { current: boolean },
+    view: Gtk.ColumnView,
+    column: Gtk.ColumnViewColumn | null,
+    order: Gtk.SortType | null | undefined,
+): void => {
+    sorting.current = true;
+
+    try {
+        view.sortByColumn(column, order ?? Gtk.SortType.ASCENDING);
+    } finally {
+        sorting.current = false;
+    }
+};
+
+const emitSortChanged = (
+    sorter: Gtk.ColumnViewSorter | null,
+    sorting: { current: boolean },
+    sort: SortProps,
+): void => {
+    if (sorter === null || sorting.current) {
+        return;
+    }
+
+    sort.onSortChanged?.(sorter.getPrimarySortColumn()?.getId() ?? null, sorter.getPrimarySortOrder());
+};
+
+const syncSort = (
+    sorting: { current: boolean },
+    view: Gtk.ColumnView | null,
+    sortColumn: string | null | undefined,
+    sortOrder: Gtk.SortType | null | undefined,
+): void => {
+    const target = getSortTarget(view, sortColumn);
+
+    if (target === null) {
+        return;
+    }
 
-    useSortHandler({
-        columnView: widgetRef,
-        sortColumn: props.sortColumn,
-        sortOrder: props.sortOrder,
-        onSortChanged: props.onSortChanged,
-        columns: registry.columns,
+    applySort(sorting, target.view, target.column, sortOrder);
+};
+
+const useColumnSorting = (view: Gtk.ColumnView | null, sort: SortProps, columns: Column<never>[]): void => {
+    const sorting = useRef(false);
+    const sorter = useProperty(view, "sorter");
+    const columnSorter = sorter instanceof Gtk.ColumnViewSorter ? sorter : null;
+
+    useSignal(columnSorter, "changed", (): void => {
+        emitSortChanged(columnSorter, sorting, sort);
     });
 
-    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],
-    );
+    const { sortColumn, sortOrder } = sort;
 
-    return {
-        setRef,
-        resolver: listModel.resolver,
-        headerResolver: listModel.headerResolver,
-        headerStore: headers.store,
-        useHeader,
-        contextValue,
-    };
+    useLayoutEffect(() => {
+        syncSort(sorting, view, sortColumn, sortOrder);
+    }, [view, sortColumn, sortOrder, columns]);
 };
 
-/**
- * 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 ColumnCells = ({ column, collection, expandedIds, size }: ColumnCellsProps): ReactNode => {
+    const cells = useItemCells(size);
+    const rest = omit(column, ["id", "renderCell", "sortable"]);
 
-    const intrinsic = createElement(
-        GtkColumnView,
-        { ...intrinsicProps, ref: wiring.setRef },
-        <ColumnViewContext.Provider value={wiring.contextValue}>{children}</ColumnViewContext.Provider>,
+    return (
+        <>
+            <GtkColumnViewColumn
+                id={column.id}
+                factory={<GtkSignalListItemFactory {...cells.handlers} />}
+                sorter={column.sortable === true ? <GtkCustomSorter /> : null}
+                {...rest}
+            />
+            <ItemPortals
+                store={cells}
+                render={column.renderCell}
+                collection={collection}
+                expandedIds={expandedIds}
+            />
+        </>
     );
+};
+
+const ColumnList = ({ columns, collection, expandedIds, size }: ColumnListProps): ReactNode =>
+    columns.map((column) => (
+        <ColumnCells
+            key={column.id}
+            column={column}
+            collection={collection}
+            expandedIds={expandedIds}
+            size={size}
+        />
+    ));
+
+/**
+ * Renders a Gtk.ColumnView from declarative items or sections and a columns array,
+ * with controlled selection, expansion, and sorting, per-column header menus, and
+ * section header rendering.
+ */
+function ColumnView<T = unknown, S = unknown>(props: ColumnViewProps<T, S>): ReactNode {
+    const { renderHeader, columns, expandedIds, sortColumn, sortOrder, onSortChanged, estimatedItemHeight, ref } =
+        props;
+
+    const rest = omit(props, COLUMN_VIEW_PROPS);
+    const [view, refCallback] = useWidgetRef<Gtk.ColumnView>(ref);
+    const size = { width: -1, height: estimatedItemHeight ?? -1 };
+    const { collection, selection } = useCollection(props);
+    const headerCells = useHeaderCells(size);
+    const columnList = columns as Column<never>[];
+    useColumnSorting(view, { sortColumn, sortOrder, onSortChanged }, columnList);
 
     return (
         <>
-            {intrinsic}
-            {wiring.useHeader ? (
-                <ListPortalHost
-                    store={wiring.headerStore}
-                    resolver={wiring.headerResolver}
-                    render={headerRenderer<T, S>(renderHeader)}
-                />
-            ) : null}
+            <GtkColumnView
+                ref={refCallback}
+                model={selection}
+                {...(renderHeader != null && {
+                    headerFactory: <GtkSignalListItemFactory {...headerCells.handlers} />,
+                })}
+                {...rest}
+            >
+                <ColumnList columns={columnList} collection={collection} expandedIds={expandedIds} size={size} />
+            </GtkColumnView>
+            {renderHeader != null && (
+                <HeaderPortals store={headerCells} render={renderHeader} collection={collection} />
+            )}
         </>
     );
-};
+}
+
+export { ColumnView };