@gtkx/components 0.21.0 → 1.0.0-rc.1

package/src/grid.tsx

@@ -0,0 +1,88 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { GtkGrid, type GtkGridProps } from "@gtkx/jsx/gtk";
+import { useMergeRefs } from "@gtkx/react/internal";
+import { Children, type ElementType, type ReactNode, type Ref, useRef } from "react";
+import { createParentContext, usePlacedChild } from "./hooks/use-placed-child.js";
+import type { ChildProps } from "./types.js";
+
+const { Context: GridContext, useParentRef: useGridRef } = createParentContext<Gtk.Grid>(
+    "<Grid.Child> must be a child of <Grid>",
+);
+
+/** Props for {@link Grid}. */
+export type GridProps = GtkGridProps & { ref?: Ref<Gtk.Grid | null>; children?: ReactNode };
+
+export type GridPlacement = {
+    column?: number | null | undefined;
+    row?: number | null | undefined;
+    /** Number of columns the child spans (defaults to 1). */
+    columnSpan?: number | null | undefined;
+    /** Number of rows the child spans (defaults to 1). */
+    rowSpan?: number | null | undefined;
+};
+
+/** Places a single child inside a {@link Grid} at a column and row, optionally spanning multiple cells. */
+export type GridChildProps<C extends ElementType> = ChildProps<C, GridPlacement>;
+
+type Placement = { column: number; row: number; columnSpan: number; rowSpan: number };
+
+const placementOf = (props: GridPlacement): Placement => ({
+    column: props.column ?? 0,
+    row: props.row ?? 0,
+    columnSpan: props.columnSpan ?? 1,
+    rowSpan: props.rowSpan ?? 1,
+});
+
+const samePlacement = (a: Placement, b: Placement): boolean =>
+    a.column === b.column && a.row === b.row && a.columnSpan === b.columnSpan && a.rowSpan === b.rowSpan;
+
+const GridChild = <C extends ElementType>({
+    component,
+    column,
+    row,
+    columnSpan,
+    rowSpan,
+    ref,
+    ...rest
+}: GridChildProps<C>): ReactNode => {
+    const gridRef = useGridRef();
+    const Component: ElementType = component;
+    return usePlacedChild<Gtk.Widget, Placement>({
+        render: (placeRef) => <Component {...rest} ref={placeRef} />,
+        ref,
+        placement: placementOf({ column, row, columnSpan, rowSpan }),
+        samePlacement,
+        place: (widget, placement, previous) => {
+            const grid = gridRef.current;
+            if (!grid) return;
+            if (previous !== undefined && widget.getParent() === grid) grid.remove(widget);
+            if (widget.getParent() !== grid) {
+                grid.attach(widget, placement.column, placement.row, placement.columnSpan, placement.rowSpan);
+            }
+        },
+        release: (widget) => {
+            const grid = gridRef.current;
+            if (grid && widget.getParent() === grid) grid.remove(widget);
+        },
+    });
+};
+
+/**
+ * Renders a Gtk.Grid whose children are attached at explicit column/row positions via
+ * {@link Grid.Child}.
+ */
+export const Grid: ((props: GridProps) => ReactNode) & {
+    Child: <C extends ElementType>(props: GridChildProps<C>) => ReactNode;
+} = Object.assign(
+    ({ children, ref, ...rest }: GridProps): ReactNode => {
+        const gridRef = useRef<Gtk.Grid | null>(null);
+        const mergedRef = useMergeRefs<Gtk.Grid>(ref, gridRef);
+        return (
+            <>
+                <GtkGrid {...rest} ref={mergedRef} />
+                <GridContext.Provider value={gridRef}>{Children.toArray(children)}</GridContext.Provider>
+            </>
+        );
+    },
+    { Child: GridChild },
+);

package/src/hooks/{use-realized-slots.ts → use-cell-containers.ts}

@@ -1,14 +1,14 @@
 import type * as GObject from "@gtkx/gi/gobject";
 import * as Gtk from "@gtkx/gi/gtk";
-import { type GObjectTarget, useTargetRegistration } from "@gtkx/react/internal";
+import { type ObjectProp, useObjectAttachment } from "@gtkx/react/internal";
 import { useRef } from "react";
-import { RealizedSlotStore } from "../utils/realized-slot-store.js";
+import { CellContainerStore } from "../utils/cell-container-store.js";
 
-interface ChildContainer {
+type ChildContainer = {
     getChild(): Gtk.Widget | null;
     setChild(child: Gtk.Widget | null): void;
     getItem(): GObject.Object | null;
-}
+};
 
 const isChildContainer = (container: GObject.Object): container is GObject.Object & ChildContainer =>
     container instanceof Gtk.ListItem || container instanceof Gtk.ListHeader;
@@ -19,36 +19,38 @@ const positionOf = (container: GObject.Object & ChildContainer): number => {
     return -1;
 };
 
-export interface FactoryBinding<W extends GObject.Object> {
+export type FactoryInstaller<W extends GObject.Object> = {
     install(widget: W, factory: Gtk.SignalListItemFactory): void;
-    uninstall(widget: W, factory: Gtk.SignalListItemFactory): void;
-}
+    uninstall(widget: W): void;
+};
+
+export const makeFactoryInstaller = <W extends GObject.Object>(
+    setFactory: (widget: W, factory: Gtk.SignalListItemFactory | null) => void,
+): FactoryInstaller<W> => ({
+    install: (widget, factory) => setFactory(widget, factory),
+    uninstall: (widget) => setFactory(widget, null),
+});
 
-export interface RealizedSlotsOptions<W extends GObject.Object> {
-    target: GObjectTarget<W>;
-    binding: FactoryBinding<W>;
+type CellContainersOptions<W extends GObject.Object> = {
+    object: ObjectProp<W>;
+    installer: FactoryInstaller<W>;
     estimatedHeight?: number | undefined;
     estimatedWidth?: number | undefined;
-}
-
-export interface RealizedSlots {
-    factory: Gtk.SignalListItemFactory;
-    store: RealizedSlotStore;
-}
+};
 
 const applyEstimatedSize = (child: Gtk.Widget, height: number | undefined, width: number | undefined): void => {
     if (height === undefined && width === undefined) return;
     child.setSizeRequest(width ?? -1, height ?? -1);
 };
 
-export const useRealizedSlots = <W extends GObject.Object>(options: RealizedSlotsOptions<W>): RealizedSlots => {
-    const { target, binding, estimatedHeight, estimatedWidth } = options;
-    const storeRef = useRef<RealizedSlotStore | null>(null);
-    if (storeRef.current === null) storeRef.current = new RealizedSlotStore();
+export const useCellContainers = <W extends GObject.Object>(options: CellContainersOptions<W>): CellContainerStore => {
+    const { object, installer, estimatedHeight, estimatedWidth } = options;
+    const storeRef = useRef<CellContainerStore | null>(null);
+    if (storeRef.current === null) storeRef.current = new CellContainerStore();
     const store = storeRef.current;
 
-    const bindingRef = useRef(binding);
-    bindingRef.current = binding;
+    const installerRef = useRef(installer);
+    installerRef.current = installer;
 
     const factoryRef = useRef<Gtk.SignalListItemFactory | null>(null);
     if (factoryRef.current === null) {
@@ -65,9 +67,7 @@ export const useRealizedSlots = <W extends GObject.Object>(options: RealizedSlot
             if (isChildContainer(container)) {
                 const item = container.getItem();
                 const treeRow = item instanceof Gtk.TreeListRow ? item : null;
-                store.bind(container, positionOf(container), treeRow, item);
-            } else {
-                store.bind(container, -1, null, null);
+                store.bind(container, positionOf(container), treeRow);
             }
         });
         factory.on("unbind", (container) => {
@@ -80,14 +80,14 @@ export const useRealizedSlots = <W extends GObject.Object>(options: RealizedSlot
     }
     const factory = factoryRef.current;
 
-    useTargetRegistration<W, { widget: W }>(target, {
+    useObjectAttachment<W, { widget: W }>(object, {
         attach: (widget) => {
-            bindingRef.current.install(widget, factory);
+            installerRef.current.install(widget, factory);
             return { widget };
         },
-        detach: (registration) => bindingRef.current.uninstall(registration.widget, factory),
-        isSame: (registration, widget) => registration.widget === widget,
+        detach: (attachment) => installerRef.current.uninstall(attachment.widget),
+        isSame: (attachment, widget) => attachment.widget === widget,
     });
 
-    return { factory, store };
+    return store;
 };

package/src/hooks/use-collection-model.ts

@@ -0,0 +1,60 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { type ReactNode, useCallback } from "react";
+import type { ItemNode, SectionNode } from "../types.js";
+import { type ItemResolver, rowIdOf } from "../utils/item-resolver.js";
+import { useExpansionModel } from "./use-expansion-model.js";
+import { useListModel } from "./use-list-model.js";
+import { useSelectionModel } from "./use-selection-model.js";
+
+type CollectionModelInput<T, S> = {
+    items: ItemNode<T>[] | undefined;
+    sections: SectionNode<S, T>[] | undefined;
+    selectionMode: Gtk.SelectionMode | null | undefined;
+    selectedIds: string[] | null | undefined;
+    onSelectionChanged: ((ids: string[]) => void) | null | undefined;
+    expandedIds?: string[] | null | undefined;
+    onExpandedChange?: ((ids: string[]) => void) | null | undefined;
+    renderHeader: ((info: { section: S }) => ReactNode) | null | undefined;
+};
+
+export type CollectionModelResult<T, S> = {
+    resolver: ItemResolver<T, S>;
+    headerResolver: ItemResolver<T, S>;
+    installedModel: Gtk.SelectionModel;
+    useHeader: boolean;
+    rowId: (row: Gtk.TreeListRow) => string | undefined;
+};
+
+export const useCollectionModel = <T, S>(input: CollectionModelInput<T, S>): CollectionModelResult<T, S> => {
+    const listModel = useListModel<T, S>({
+        items: input.items,
+        sections: input.sections,
+    });
+
+    useExpansionModel<T>({
+        treeModel: listModel.treeModel,
+        rowValues: listModel.rowValues,
+        expandedIds: input.expandedIds,
+        onExpandedChange: input.onExpandedChange,
+    });
+
+    const installedModel = useSelectionModel<T, S>({
+        base: listModel.model,
+        resolver: listModel.resolver,
+        selectionMode: input.selectionMode,
+        selectedIds: input.selectedIds,
+        onSelectionChanged: input.onSelectionChanged,
+    });
+
+    const useHeader = typeof input.renderHeader === "function";
+    const { rowValues } = listModel;
+    const rowId = useCallback((row: Gtk.TreeListRow): string | undefined => rowIdOf(rowValues, row), [rowValues]);
+
+    return {
+        resolver: listModel.resolver,
+        headerResolver: listModel.headerResolver,
+        installedModel,
+        useHeader,
+        rowId,
+    };
+};

package/src/hooks/use-collection-widget.ts

@@ -0,0 +1,47 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { useMergeRefs } from "@gtkx/react/internal";
+import { type ReactNode, type Ref, type RefCallback, type RefObject, useRef } from "react";
+import type { ItemNode, SectionNode } from "../types.js";
+import { type CollectionModelResult, useCollectionModel } from "./use-collection-model.js";
+import { useInstalledModel } from "./use-installed-model.js";
+
+type CollectionWidget = Gtk.Widget & {
+    setModel(model: Gtk.SelectionModel | null): void;
+};
+
+type CollectionWidgetInput<W extends CollectionWidget, T, S> = {
+    ref?: Ref<W | null> | undefined;
+    items?: ItemNode<T>[] | undefined;
+    sections?: SectionNode<S, T>[] | undefined;
+    selectionMode?: Gtk.SelectionMode | null | undefined;
+    selectedIds?: string[] | null | undefined;
+    onSelectionChanged?: ((ids: string[]) => void) | null | undefined;
+    expandedIds?: string[] | null | undefined;
+    onExpandedChange?: ((ids: string[]) => void) | null | undefined;
+    renderHeader?: ((info: { section: S }) => ReactNode) | null | undefined;
+};
+
+type CollectionWidgetResult<W extends CollectionWidget, T, S> = {
+    widgetRef: RefObject<W | null>;
+    setRef: RefCallback<W>;
+    collection: CollectionModelResult<T, S>;
+};
+
+export const useCollectionWidget = <W extends CollectionWidget, T, S>(
+    props: CollectionWidgetInput<W, T, S>,
+): CollectionWidgetResult<W, T, S> => {
+    const widgetRef = useRef<W | null>(null);
+    const setRef = useMergeRefs<W>(props.ref, widgetRef);
+    const collection = useCollectionModel<T, S>({
+        items: props.items,
+        sections: props.sections,
+        selectionMode: props.selectionMode,
+        selectedIds: props.selectedIds,
+        onSelectionChanged: props.onSelectionChanged,
+        expandedIds: props.expandedIds,
+        onExpandedChange: props.onExpandedChange,
+        renderHeader: props.renderHeader,
+    });
+    useInstalledModel(widgetRef, collection.installedModel, (widget, model) => widget.setModel(model));
+    return { widgetRef, setRef, collection };
+};

package/src/hooks/use-drop-down-selection.ts

@@ -1,32 +1,31 @@
 import type * as GObject from "@gtkx/gi/gobject";
+import * as Gtk from "@gtkx/gi/gtk";
 import { useSignal } from "@gtkx/react";
-import { type GObjectTarget, resolveGobjectTarget, useGObjectSnapshot } from "@gtkx/react/internal";
+import { type ObjectProp, resolveObjectProp, useObjectValue } from "@gtkx/react/internal";
 import { useLayoutEffect, useRef } from "react";
 import type { ItemResolver } from "../utils/item-resolver.js";
 
-export interface DropDownSelectionTarget extends GObject.Object {
+type DropDownSelectionObject = GObject.Object & {
     getSelected(): number;
     setSelected(position: number): void;
-}
+};
 
-export interface DropDownSelectionOptions<T, S> {
-    widget: GObjectTarget<DropDownSelectionTarget>;
+type DropDownSelectionOptions<T, S> = {
+    widget: ObjectProp<DropDownSelectionObject>;
     resolver: ItemResolver<T, S>;
     selectedId: string | null | undefined;
     onSelectionChanged: ((id: string) => void) | null | undefined;
-}
-
-const GTK_INVALID_LIST_POSITION = 4294967295;
+};
 
 const normalizeSelected = (position: number): number =>
-    position === GTK_INVALID_LIST_POSITION || position < 0 ? -1 : position;
+    position === Gtk.INVALID_LIST_POSITION || position < 0 ? -1 : position;
 
 export const useDropDownSelection = <T, S>(options: DropDownSelectionOptions<T, S>): number => {
     const { widget, resolver, selectedId, onSelectionChanged } = options;
-    const resolved = resolveGobjectTarget(widget);
+    const resolved = resolveObjectProp(widget);
 
-    const selectedPosition = useGObjectSnapshot(widget, "notify::selected", (target) =>
-        target === null ? -1 : normalizeSelected(target.getSelected()),
+    const selectedPosition = useObjectValue(widget, "notify::selected", (object) =>
+        object === null ? -1 : normalizeSelected(object.getSelected()),
     );
 
     const resolverRef = useRef(resolver);
@@ -36,7 +35,7 @@ export const useDropDownSelection = <T, S>(options: DropDownSelectionOptions<T,
 
     useLayoutEffect(() => {
         if (resolved === null || selectedId === undefined || selectedId === null) return;
-        const position = resolverRef.current.positionOf(selectedId);
+        const position = resolverRef.current.positionOfId(selectedId);
         if (position < 0) return;
         if (normalizeSelected(resolved.getSelected()) !== position) resolved.setSelected(position);
     }, [resolved, selectedId, resolver]);

package/src/hooks/use-expansion-model.ts

@@ -0,0 +1,82 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import type * as Gtk from "@gtkx/gi/gtk";
+import { useSignal } from "@gtkx/react";
+import { isSameArray } from "@gtkx/utils";
+import { useLayoutEffect, useRef } from "react";
+import { type RowValue, rowIdOf } from "../utils/item-resolver.js";
+
+type ExpansionModelOptions<T> = {
+    treeModel: Gtk.TreeListModel | null;
+    rowValues: WeakMap<GObject.Object, RowValue<T>>;
+    expandedIds: string[] | null | undefined;
+    onExpandedChange: ((ids: string[]) => void) | null | undefined;
+};
+
+const readExpandedIds = <T>(model: Gtk.TreeListModel, rowValues: WeakMap<GObject.Object, RowValue<T>>): string[] => {
+    const ids: string[] = [];
+    const count = model.getNItems();
+    for (let position = 0; position < count; position++) {
+        const row = model.getRow(position);
+        if (row?.getExpanded()) {
+            const id = rowIdOf(rowValues, row);
+            if (id !== undefined) ids.push(id);
+        }
+    }
+    return ids;
+};
+
+const applyExpanded = <T>(
+    model: Gtk.TreeListModel,
+    rowValues: WeakMap<GObject.Object, RowValue<T>>,
+    ids: string[],
+): void => {
+    const target = new Set(ids);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        const count = model.getNItems();
+        for (let position = 0; position < count; position++) {
+            const row = model.getRow(position);
+            if (row === null || !row.isExpandable()) continue;
+            const id = rowIdOf(rowValues, row);
+            if (id === undefined) continue;
+            const desired = target.has(id);
+            if (row.getExpanded() !== desired) {
+                row.setExpanded(desired);
+                changed = true;
+            }
+        }
+    }
+};
+
+export const useExpansionModel = <T>(options: ExpansionModelOptions<T>): void => {
+    const { treeModel, rowValues, expandedIds, onExpandedChange } = options;
+    const onChangeRef = useRef(onExpandedChange);
+    onChangeRef.current = onExpandedChange;
+    const rowValuesRef = useRef(rowValues);
+    rowValuesRef.current = rowValues;
+    const lastReportedRef = useRef<string[] | null>(null);
+    const applyingRef = useRef(false);
+
+    const report = (): void => {
+        if (treeModel === null || applyingRef.current) return;
+        const callback = onChangeRef.current;
+        if (!callback) return;
+        const ids = readExpandedIds(treeModel, rowValuesRef.current);
+        if (lastReportedRef.current !== null && isSameArray(lastReportedRef.current, ids)) return;
+        lastReportedRef.current = ids;
+        callback(ids);
+    };
+
+    useSignal(treeModel, "items-changed", report);
+
+    useLayoutEffect(() => {
+        if (treeModel === null) return;
+        if (expandedIds !== undefined && expandedIds !== null) {
+            applyingRef.current = true;
+            applyExpanded(treeModel, rowValuesRef.current, expandedIds);
+            applyingRef.current = false;
+        }
+        report();
+    }, [treeModel, expandedIds]);
+};

package/src/hooks/use-header-menu.ts

@@ -1,33 +1,34 @@
-import * as Gio from "@gtkx/gi/gio";
-import * as GObject from "@gtkx/gi/gobject";
+import type * as Gio from "@gtkx/gi/gio";
 import type * as Gtk from "@gtkx/gi/gtk";
-import { createPortal } from "@gtkx/react";
-import { stateOf } from "@gtkx/react/internal";
-import { type ReactNode, useLayoutEffect, useRef } from "react";
+import { createPortal, rootElement } from "@gtkx/react";
+import { useMergeRefs } from "@gtkx/react/internal";
+import {
+    cloneElement,
+    isValidElement,
+    type ReactElement,
+    type ReactNode,
+    type Ref,
+    type RefCallback,
+    useCallback,
+    useLayoutEffect,
+    useRef,
+} from "react";
 
-const findMenuModel = (container: GObject.Object): Gio.MenuModel | null => {
-    for (const child of stateOf(container).children) {
-        if (child instanceof Gio.MenuModel) return child;
-    }
-    return null;
-};
+type MenuElement = ReactElement<{ ref?: Ref<Gio.MenuModel | null> }>;
 
 export const useHeaderMenu = (column: Gtk.ColumnViewColumn | null, headerMenu: ReactNode): ReactNode => {
-    const containerRef = useRef<GObject.Object | null>(null);
-    if (containerRef.current === null) {
-        containerRef.current = new GObject.Object();
-    }
-    const container = containerRef.current;
+    const modelRef = useRef<Gio.MenuModel | null>(null);
+    const setModel = useCallback<RefCallback<Gio.MenuModel>>((model) => {
+        modelRef.current = model;
+    }, []);
+    const element = isValidElement(headerMenu) ? (headerMenu as MenuElement) : null;
+    const mergedRef = useMergeRefs<Gio.MenuModel>(setModel, element?.props.ref);
 
     useLayoutEffect(() => {
         if (column === null) return;
-        if (headerMenu === undefined || headerMenu === null) {
-            column.setHeaderMenu(null);
-            return;
-        }
-        column.setHeaderMenu(findMenuModel(container));
+        column.setHeaderMenu(headerMenu == null ? null : modelRef.current);
     });
 
-    if (headerMenu === undefined || headerMenu === null) return null;
-    return createPortal(headerMenu, container, "header-menu");
+    if (element === null) return null;
+    return createPortal(cloneElement(element, { ref: mergedRef }), rootElement);
 };

package/src/hooks/use-installed-model.ts

@@ -0,0 +1,20 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { useObjectAttachment } from "@gtkx/react/internal";
+import { type RefObject, useRef } from "react";
+
+export const useInstalledModel = <W extends Gtk.Widget, M>(
+    object: RefObject<W | null>,
+    model: M,
+    install: (widget: W, model: M) => void,
+): void => {
+    const installRef = useRef(install);
+    installRef.current = install;
+    useObjectAttachment<W, { widget: W; model: M }>(object, {
+        attach: (widget) => {
+            installRef.current(widget, model);
+            return { widget, model };
+        },
+        detach: () => {},
+        isSame: (attachment, widget) => attachment.widget === widget && attachment.model === model,
+    });
+};