@gtkx/components 1.0.0-rc.1 → 1.0.0-rc.3

package/src/internal/selection.tsx

@@ -0,0 +1,162 @@
+import type * as Gio from "@gtkx/gi/gio";
+import type { ReactElement } from "react";
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkMultiSelection, GtkNoSelection, GtkSingleSelection } from "@gtkx/jsx/gtk";
+import { useEffectEvent, useLayoutEffect, useState } from "react";
+import type { Collection } from "./collection.js";
+
+type SelectionOptions = {
+    collection: Collection;
+    selectedIds?: string[] | null | undefined;
+    onSelectionChanged?: ((ids: string[]) => void) | null | undefined;
+    selectionMode?: Gtk.SelectionMode | null | undefined;
+    onItemsChanged: () => void;
+};
+
+type LastSelection = {
+    selection: Gtk.SelectionModel | null;
+    key: string | null;
+};
+
+type SelectionElementProps = {
+    ref: (value: Gtk.SelectionModel | null) => void;
+    model: Gio.ListModel;
+    onSelectionChanged: () => void;
+    onItemsChanged: () => void;
+};
+
+function getSelectedIds(selection: Gtk.SelectionModel, collection: Collection): string[] {
+    const bitset = selection.getSelection();
+    const size = Number(bitset.getSize());
+    const ids: string[] = [];
+
+    for (let index = 0; index < size; index++) {
+        pushId(collection.idAt(bitset.getNth(index)), ids);
+    }
+
+    return ids;
+}
+
+function pushId(id: string | null, ids: string[]): void {
+    if (id !== null) {
+        ids.push(id);
+    }
+}
+
+function applySingleSelection(selection: Gtk.SingleSelection, positions: number[]): void {
+    const [first] = positions;
+
+    if (first === undefined) {
+        selection.unselectAll();
+
+        return;
+    }
+
+    selection.selectItem(first, true);
+}
+
+function applyMultiSelection(selection: Gtk.SelectionModel, positions: number[]): void {
+    const selected = Gtk.Bitset.newEmpty();
+
+    for (const position of positions) {
+        selected.add(position);
+    }
+
+    selection.setSelection(selected, Gtk.Bitset.newRange(0, selection.getNItems()));
+}
+
+function applySelection(selection: Gtk.SelectionModel, collection: Collection, ids: string[]): void {
+    if (selection instanceof Gtk.NoSelection) {
+        return;
+    }
+
+    const positions = collection.positionsFor(ids);
+
+    if (ids.length > 0 && positions.length === 0) {
+        return;
+    }
+
+    if (selection instanceof Gtk.SingleSelection) {
+        applySingleSelection(selection, positions);
+
+        return;
+    }
+
+    applyMultiSelection(selection, positions);
+}
+
+function reportSelection(
+    selection: Gtk.SelectionModel | null,
+    collection: Collection,
+    last: LastSelection,
+    onSelectionChanged: ((ids: string[]) => void) | null | undefined,
+): void {
+    if (selection === null) {
+        return;
+    }
+
+    const ids = getSelectedIds(selection, collection);
+    const key = ids.join(" ");
+
+    if (last.selection === selection && last.key === key) {
+        return;
+    }
+
+    last.selection = selection;
+    last.key = key;
+    onSelectionChanged?.(ids);
+}
+
+function selectionElement(mode: Gtk.SelectionMode | null | undefined, props: SelectionElementProps): ReactElement {
+    if (mode === Gtk.SelectionMode.MULTIPLE) {
+        return <GtkMultiSelection {...props} />;
+    }
+
+    if (mode === Gtk.SelectionMode.NONE) {
+        return <GtkNoSelection {...props} />;
+    }
+
+    return <GtkSingleSelection {...props} autoselect={false} canUnselect />;
+}
+
+function syncSelection(
+    selection: Gtk.SelectionModel | null,
+    collection: Collection,
+    selectedIds: string[] | null | undefined,
+): void {
+    if (selection === null || selectedIds == null) {
+        return;
+    }
+
+    applySelection(selection, collection, selectedIds);
+}
+
+function newLastSelection(): LastSelection {
+    return { selection: null, key: null };
+}
+
+function useSelection(options: SelectionOptions): ReactElement {
+    const { collection, selectedIds, onSelectionChanged, selectionMode } = options;
+    const [selection, setSelection] = useState<Gtk.SelectionModel | null>(null);
+    const [last] = useState<LastSelection>(newLastSelection);
+
+    const report = useEffectEvent((): void => {
+        reportSelection(selection, collection, last, onSelectionChanged);
+    });
+
+    useLayoutEffect(() => {
+        syncSelection(selection, collection, selectedIds);
+        report();
+    }, [selection, collection, selectedIds]);
+
+    return selectionElement(selectionMode, {
+        ref: setSelection,
+        model: collection.model,
+        onSelectionChanged: () => {
+            reportSelection(selection, collection, last, onSelectionChanged);
+        },
+        onItemsChanged: options.onItemsChanged,
+    });
+}
+
+export { useSelection, type SelectionOptions };

package/src/internal/use-collection.tsx

@@ -0,0 +1,57 @@
+import type { ReactElement } from "react";
+import { useLayoutEffect, useMemo, useState } from "react";
+import type { ExpansionProps, Item, Section, SelectionProps } from "../types.js";
+import type { Collection } from "./collection.js";
+import { createCollectionIndex } from "./collection-index.js";
+import { createCollectionModel } from "./collection-model.js";
+import { createCollection } from "./collection.js";
+import { useExpansion } from "./expansion.js";
+import { useSelection } from "./selection.js";
+
+type CollectionDataOptions = {
+    items?: Item[] | undefined;
+    sections?: Section[] | undefined;
+    flat?: boolean | undefined;
+};
+
+type CollectionOptions = CollectionDataOptions & SelectionProps & ExpansionProps;
+
+type CollectionResult = {
+    collection: Collection;
+    selection: ReactElement;
+};
+
+function useCollectionData(options: CollectionDataOptions): Collection {
+    const { items, sections, flat } = options;
+    const [gtk] = useState(createCollectionModel);
+    const index = useMemo(() => createCollectionIndex(items, sections, flat === true), [items, sections, flat]);
+    const collection = useMemo(() => createCollection(gtk, index), [gtk, index]);
+
+    useLayoutEffect(() => {
+        gtk.sync(index);
+    }, [gtk, index]);
+
+    return collection;
+}
+
+function useCollection(options: CollectionOptions): CollectionResult {
+    const collection = useCollectionData(options);
+
+    const onItemsChanged = useExpansion({
+        collection,
+        expandedIds: options.expandedIds,
+        onExpandedChange: options.onExpandedChange,
+    });
+
+    const selection = useSelection({
+        collection,
+        selectedIds: options.selectedIds,
+        onSelectionChanged: options.onSelectionChanged,
+        selectionMode: options.selectionMode,
+        onItemsChanged,
+    });
+
+    return { collection, selection };
+}
+
+export { useCollection, useCollectionData, type CollectionDataOptions, type CollectionOptions };

package/src/internal/use-widget-ref.ts

@@ -0,0 +1,11 @@
+import type { Ref, RefCallback } from "react";
+import { useMergedRef } from "@gtkx/react/internal";
+import { useState } from "react";
+
+const useWidgetRef = <T>(external: Ref<T | null> | null | undefined): [T | null, RefCallback<T | null>] => {
+    const [widget, setWidget] = useState<T | null>(null);
+
+    return [widget, useMergedRef<T | null>(external, setWidget)];
+};
+
+export { useWidgetRef };

package/src/list-view.tsx

@@ -1,148 +1,52 @@
-import type * as Gtk from "@gtkx/gi/gtk";
-import { GtkListView, type GtkListViewProps } from "@gtkx/jsx/gtk";
-import type { ReactNode, Ref } from "react";
-import {
-    type CellRenderer,
-    CellRenderHost,
-    createTreeRenderContext,
-    HeaderRenderHost,
-    itemRenderer,
-    type TreeRenderContext,
-} from "./cell.js";
-import { makeFactoryInstaller, useCellContainers } from "./hooks/use-cell-containers.js";
-import { useCollectionWidget } from "./hooks/use-collection-widget.js";
-import type {
-    CollectionItemSizeProps,
-    ControlledExpansionProps,
-    ControlledSelectionProps,
-    ItemNode,
-    RenderItemProps,
-    SectionNode,
-} from "./types.js";
-import type { CellContainerStore } from "./utils/cell-container-store.js";
-import type { ItemResolver } from "./utils/item-resolver.js";
-
-const factoryInstaller = makeFactoryInstaller<Gtk.ListView>((widget, factory) => widget.setFactory(factory));
-
-const headerFactoryInstaller = makeFactoryInstaller<Gtk.ListView>((widget, factory) =>
-    widget.setHeaderFactory(factory),
-);
-
-export type ListViewDeclarativeProps<T = unknown, S = unknown> = CollectionItemSizeProps &
-    ControlledSelectionProps &
-    ControlledExpansionProps & {
-        items?: ItemNode<T>[] | undefined;
-        sections?: SectionNode<S, T>[] | undefined;
-        renderItem: (props: RenderItemProps<T>) => ReactNode;
-        renderHeader?: ((info: { section: S }) => ReactNode) | null | undefined;
-    };
+import type { ReactNode } from "react";
+import { GtkListView, GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
+import { omit } from "@gtkx/utils";
+import type { ListViewProps } from "./types.js";
+import { HeaderPortals, ItemPortals, useHeaderCells, useItemCells } from "./internal/cells.js";
+import { useCollection } from "./internal/use-collection.js";
+
+const LIST_VIEW_PROPS = [
+    "items",
+    "sections",
+    "renderItem",
+    "renderHeader",
+    "selectedIds",
+    "onSelectionChanged",
+    "selectionMode",
+    "expandedIds",
+    "onExpandedChange",
+    "estimatedItemHeight",
+    "estimatedItemWidth",
+] as const satisfies (keyof ListViewProps)[];
 
 /**
- * Props for {@link ListView}. Combines the underlying Gtk.ListView props with
- * declarative collection props: flat items or grouped sections, a per-row renderItem,
- * an optional section header renderer, controlled selection and expansion, and
- * estimated item sizing.
+ * Renders a Gtk.ListView from declarative items or sections, with per-row rendering,
+ * controlled selection, controlled tree expansion, and estimated item sizing.
  */
-export type ListViewProps<T = unknown, S = unknown> = Omit<
-    GtkListViewProps,
-    "model" | "factory" | "headerFactory" | keyof ListViewDeclarativeProps<T, S>
-> &
-    ListViewDeclarativeProps<T, S>;
-
-interface ListViewWiring<T, S> {
-    setRef: (value: Gtk.ListView | null) => void;
-    resolver: ItemResolver<T, S>;
-    headerResolver: ItemResolver<T, S>;
-    itemStore: CellContainerStore;
-    headerStore: CellContainerStore;
-    useHeader: boolean;
-    rowId: (row: Gtk.TreeListRow) => string | undefined;
-}
-
-const useListViewWiring = <T, S>(props: NormalizedListViewProps<T, S>): ListViewWiring<T, S> => {
-    const { widgetRef, setRef, collection } = useCollectionWidget<Gtk.ListView, T, S>(props);
-
-    const useHeader = collection.useHeader;
-
-    const itemStore = useCellContainers<Gtk.ListView>({
-        object: widgetRef,
-        installer: factoryInstaller,
-        estimatedHeight: props.estimatedItemHeight,
-        estimatedWidth: props.estimatedItemWidth,
-    });
-    const headerStore = useCellContainers<Gtk.ListView>({
-        object: useHeader ? widgetRef : null,
-        installer: headerFactoryInstaller,
-        estimatedHeight: props.estimatedItemHeight,
-        estimatedWidth: props.estimatedItemWidth,
-    });
-
-    return {
-        setRef,
-        resolver: collection.resolver,
-        headerResolver: collection.headerResolver,
-        itemStore,
-        headerStore,
-        useHeader,
-        rowId: collection.rowId,
-    };
-};
-
-type NormalizedListViewProps<T, S> = ListViewDeclarativeProps<T, S> & {
-    ref?: Ref<Gtk.ListView | null>;
-    estimatedItemHeight?: number;
-    estimatedItemWidth?: number;
-    [key: string]: unknown;
-};
-
-/**
- * Renders a Gtk.ListView: a scrollable, single-column list backed by a collection
- * model, with each row drawn by renderItem and optional section headers.
- */
-export const ListView = <T = unknown, S = unknown>(props: ListViewProps<T, S>): ReactNode => {
-    const {
-        ref,
-        items,
-        sections,
-        renderItem,
-        renderHeader,
-        selectedIds,
-        selectionMode,
-        onSelectionChanged,
-        expandedIds,
-        onExpandedChange,
-        estimatedItemHeight,
-        estimatedItemWidth,
-        ...intrinsicProps
-    } = props as NormalizedListViewProps<T, S>;
-
-    const wiring = useListViewWiring<T, S>({
-        ref,
-        items,
-        sections,
-        renderHeader,
-        selectedIds,
-        selectionMode,
-        onSelectionChanged,
-        expandedIds,
-        onExpandedChange,
-        estimatedItemHeight,
-        estimatedItemWidth,
-    } as NormalizedListViewProps<T, S>);
-
-    const treeContext: TreeRenderContext = createTreeRenderContext(expandedIds, wiring.rowId);
-    const cellRenderer: CellRenderer<T, S> = itemRenderer<T, S>(renderItem, treeContext);
+function ListView<T = unknown, S = unknown>(props: ListViewProps<T, S>): ReactNode {
+    const { renderItem, renderHeader, expandedIds, estimatedItemHeight, estimatedItemWidth } = props;
+    const rest = omit(props, LIST_VIEW_PROPS);
+    const size = { width: estimatedItemWidth ?? -1, height: estimatedItemHeight ?? -1 };
+    const { collection, selection } = useCollection(props);
+    const itemCells = useItemCells(size);
+    const headerCells = useHeaderCells(size);
 
     return (
         <>
-            <GtkListView {...intrinsicProps} ref={wiring.setRef} />
-            <CellRenderHost store={wiring.itemStore} resolver={wiring.resolver} render={cellRenderer} />
-            <HeaderRenderHost
-                useHeader={wiring.useHeader}
-                store={wiring.headerStore}
-                resolver={wiring.headerResolver}
-                renderHeader={renderHeader}
+            <GtkListView
+                model={selection}
+                factory={<GtkSignalListItemFactory {...itemCells.handlers} />}
+                {...(renderHeader != null && {
+                    headerFactory: <GtkSignalListItemFactory {...headerCells.handlers} />,
+                })}
+                {...rest}
             />
+            <ItemPortals store={itemCells} render={renderItem} collection={collection} expandedIds={expandedIds} />
+            {renderHeader != null && (
+                <HeaderPortals store={headerCells} render={renderHeader} collection={collection} />
+            )}
         </>
     );
-};
+}
+
+export { ListView };

package/src/size-group.tsx

@@ -1,96 +1,77 @@
 import type * as Gtk from "@gtkx/gi/gtk";
+import type { ElementType, ReactNode, Ref, RefCallback } from "react";
 import { GtkSizeGroup } from "@gtkx/jsx/gtk";
-import { useMergeRefs } from "@gtkx/react/internal";
-import {
-    createContext,
-    type ElementType,
-    type ReactNode,
-    type Ref,
-    type RefCallback,
-    useCallback,
-    useContext,
-    useRef,
-} from "react";
-import type { ChildProps } from "./types.js";
-
-type SizeGroupRegistry = {
-    addWidget: (widget: Gtk.Widget) => void;
-    removeWidget: (widget: Gtk.Widget) => void;
-    setGroup: (group: Gtk.SizeGroup | null) => void;
-};
+import { useMergedRef } from "@gtkx/react/internal";
+import { createContext, useCallback, useContext, useState } from "react";
+import type { SizeGroupChildProps, SizeGroupProps } from "./types.js";
+
+type Register = RefCallback<Gtk.Widget | null>;
 
-const SizeGroupContext = createContext<SizeGroupRegistry | null>(null);
+type SizeGroupChildRuntimeProps = {
+    component: ElementType;
+    ref?: Ref<Gtk.Widget | null> | undefined;
+} & Record<string, unknown>;
 
-const useSizeGroupRegistry = (): SizeGroupRegistry => {
-    const registry = useContext(SizeGroupContext);
-    if (!registry) throw new Error("<SizeGroup.Child> must be a child of <SizeGroup>");
-    return registry;
+type SizeGroupComponent = ((props: SizeGroupProps) => ReactNode) & {
+    Child: <C extends ElementType>(props: SizeGroupChildProps<C>) => ReactNode;
 };
 
-/** Props for {@link SizeGroup}. */
-export type SizeGroupProps = {
-    /** How the group equalizes sizes: horizontal, vertical, or both. */
-    mode?: Gtk.SizeGroupMode | null | undefined;
-    ref?: Ref<Gtk.SizeGroup | null>;
-    children?: ReactNode;
+const SizeGroupContext = createContext<Register | null>(null);
+const SizeGroupChild = SizeGroupChildImpl as <C extends ElementType>(props: SizeGroupChildProps<C>) => ReactNode;
+/**
+ * Creates a Gtk.SizeGroup that keeps widgets joined through `SizeGroup.Child`
+ * at a common size in the given mode, without contributing a widget of its own.
+ */
+const SizeGroup: SizeGroupComponent = Object.assign(SizeGroupRoot, { Child: SizeGroupChild });
+
+const useRegister = (): Register => {
+    const register = useContext(SizeGroupContext);
+
+    if (register === null) {
+        throw new Error("<SizeGroup.Child> must be a child of <SizeGroup>");
+    }
+
+    return register;
 };
 
-/** Adds a single widget, rendered by the given component, to the enclosing {@link SizeGroup}. */
-export type SizeGroupChildProps<C extends ElementType> = ChildProps<C>;
+function SizeGroupChildImpl(props: SizeGroupChildRuntimeProps): ReactNode {
+    const { component: Component, ref, ...rest } = props;
+    const refCallback = useMergedRef<Gtk.Widget | null>(ref, useRegister());
+
+    return <Component {...rest} ref={refCallback} />;
+}
+
+const addWidget = (widgets: Gtk.Widget[], widget: Gtk.Widget): Gtk.Widget[] =>
+    widgets.includes(widget) ? widgets : [...widgets, widget];
+
+const removeWidget = (widgets: Gtk.Widget[], widget: Gtk.Widget): Gtk.Widget[] =>
+    widgets.filter((entry) => entry !== widget);
+
+function SizeGroupRoot(props: SizeGroupProps): ReactNode {
+    const { mode, ref, children } = props;
+    const [widgets, setWidgets] = useState<Gtk.Widget[]>([]);
 
-const SizeGroupChild = <C extends ElementType>({ component, ref, ...rest }: SizeGroupChildProps<C>): ReactNode => {
-    const registry = useSizeGroupRegistry();
-    const joinGroup = useCallback<RefCallback<Gtk.Widget>>(
+    const register = useCallback<Register>(
         (widget) => {
-            if (widget === null) return;
-            registry.addWidget(widget);
-            return () => registry.removeWidget(widget);
+            if (widget === null) {
+                return;
+            }
+
+            setWidgets((previous) => addWidget(previous, widget));
+
+            return () => {
+                setWidgets((previous) => removeWidget(previous, widget));
+            };
         },
-        [registry],
+        [setWidgets],
     );
-    const Component: ElementType = component;
-    const setWidget = useMergeRefs<Gtk.Widget>(ref, joinGroup);
-    return <Component {...rest} ref={setWidget} />;
-};
 
-const createRegistry = (): SizeGroupRegistry => {
-    const members = new Set<Gtk.Widget>();
-    let group: Gtk.SizeGroup | null = null;
-    return {
-        addWidget: (widget) => {
-            members.add(widget);
-            group?.addWidget(widget);
-        },
-        removeWidget: (widget) => {
-            members.delete(widget);
-            group?.removeWidget(widget);
-        },
-        setGroup: (next) => {
-            group = next;
-            if (next) for (const member of members) next.addWidget(member);
-        },
-    };
-};
+    return (
+        <>
+            <GtkSizeGroup ref={ref} mode={mode} widgets={widgets} />
+            <SizeGroupContext.Provider value={register}>{children}</SizeGroupContext.Provider>
+        </>
+    );
+}
 
-/**
- * Creates a Gtk.SizeGroup that keeps its member widgets at a common size. Members join the group
- * through {@link SizeGroup.Child}.
- */
-export const SizeGroup: ((props: SizeGroupProps) => ReactNode) & {
-    Child: <C extends ElementType>(props: SizeGroupChildProps<C>) => ReactNode;
-} = Object.assign(
-    ({ mode, ref, children }: SizeGroupProps): ReactNode => {
-        const registryRef = useRef<SizeGroupRegistry | null>(null);
-        if (registryRef.current === null) registryRef.current = createRegistry();
-        const registry = registryRef.current;
-        const setGroup = useCallback<RefCallback<Gtk.SizeGroup>>((group) => registry.setGroup(group), [registry]);
-        const mergedRef = useMergeRefs<Gtk.SizeGroup>(ref, setGroup);
-        return (
-            <>
-                <GtkSizeGroup ref={mergedRef} mode={mode} />
-                <SizeGroupContext.Provider value={registry}>{children}</SizeGroupContext.Provider>
-            </>
-        );
-    },
-    { Child: SizeGroupChild },
-);
+export { SizeGroup };