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

package/src/grid-view.tsx

@@ -1,81 +1,37 @@
-import type * as Gtk from "@gtkx/gi/gtk";
-import { GtkGridView, type GtkGridViewProps } from "@gtkx/jsx/gtk";
-import { useMergeRefs } from "@gtkx/react/internal";
-import { type ReactNode, type Ref, useRef } from "react";
-import { type CellRenderer, CellRenderHost, itemRenderer } from "./cell.js";
-import { makeFactoryInstaller, useCellContainers } from "./hooks/use-cell-containers.js";
-import { useCollectionModel } from "./hooks/use-collection-model.js";
-import { useInstalledModel } from "./hooks/use-installed-model.js";
-import type { CollectionItemSizeProps, ControlledSelectionProps, ItemNode, RenderItemProps } from "./types.js";
-
-const factoryInstaller = makeFactoryInstaller<Gtk.GridView>((widget, factory) => widget.setFactory(factory));
-
-export type GridViewDeclarativeProps<T = unknown> = CollectionItemSizeProps &
-    ControlledSelectionProps & {
-        items?: ItemNode<T>[] | undefined;
-        renderItem: (props: RenderItemProps<T>) => ReactNode;
-    };
-
-/**
- * Props for {@link GridView}. Combines the underlying Gtk.GridView props with
- * declarative collection props: items, a per-cell renderItem, controlled selection,
- * and estimated item sizing.
- */
-export type GridViewProps<T = unknown> = Omit<
-    GtkGridViewProps,
-    "model" | "factory" | keyof GridViewDeclarativeProps<T>
-> &
-    GridViewDeclarativeProps<T>;
+import type { ReactNode } from "react";
+import { GtkGridView, GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
+import { omit } from "@gtkx/utils";
+import type { GridViewProps } from "./types.js";
+import { ItemPortals, useItemCells } from "./internal/cells.js";
+import { useCollection } from "./internal/use-collection.js";
+
+const GRID_VIEW_PROPS = [
+    "items",
+    "renderItem",
+    "selectedIds",
+    "onSelectionChanged",
+    "selectionMode",
+    "estimatedItemHeight",
+    "estimatedItemWidth",
+] as const satisfies (keyof GridViewProps)[];
 
 /**
- * Renders a Gtk.GridView: a scrollable grid of uniformly sized cells backed by a
- * collection model, with each cell drawn by renderItem.
+ * Renders a Gtk.GridView of uniform cells from declarative items, with per-cell
+ * rendering, controlled selection, and estimated item sizing.
  */
-export const GridView = <T = unknown>(props: GridViewProps<T>): ReactNode => {
-    const {
-        ref,
-        items,
-        renderItem,
-        selectedIds,
-        selectionMode,
-        onSelectionChanged,
-        estimatedItemHeight,
-        estimatedItemWidth,
-        ...intrinsicProps
-    } = props as GridViewDeclarativeProps<T> & {
-        ref?: Ref<Gtk.GridView | null>;
-        estimatedItemHeight?: number;
-        estimatedItemWidth?: number;
-        [key: string]: unknown;
-    };
-
-    const cellRenderer: CellRenderer<T, unknown> = itemRenderer<T, unknown>(renderItem);
-
-    const widgetRef = useRef<Gtk.GridView | null>(null);
-    const setRef = useMergeRefs<Gtk.GridView>(ref, widgetRef);
-
-    const collection = useCollectionModel<T, unknown>({
-        items,
-        sections: undefined,
-        selectionMode,
-        selectedIds,
-        onSelectionChanged,
-        renderHeader: undefined,
-    });
-
-    const itemStore = useCellContainers<Gtk.GridView>({
-        object: widgetRef,
-        installer: factoryInstaller,
-        estimatedHeight: estimatedItemHeight,
-        estimatedWidth: estimatedItemWidth,
-    });
-
-    useInstalledModel(widgetRef, collection.installedModel, (widget, value) => widget.setModel(value));
+function GridView<T = unknown>(props: GridViewProps<T>): ReactNode {
+    const { renderItem, estimatedItemHeight, estimatedItemWidth } = props;
+    const rest = omit(props, GRID_VIEW_PROPS);
+    const size = { width: estimatedItemWidth ?? -1, height: estimatedItemHeight ?? -1 };
+    const { collection, selection } = useCollection({ ...props, flat: true });
+    const itemCells = useItemCells(size);
 
     return (
         <>
-            <GtkGridView {...intrinsicProps} ref={setRef} />
-            <CellRenderHost store={itemStore} resolver={collection.resolver} render={cellRenderer} />
+            <GtkGridView model={selection} factory={<GtkSignalListItemFactory {...itemCells.handlers} />} {...rest} />
+            <ItemPortals store={itemCells} render={renderItem} collection={collection} />
         </>
     );
-};
+}
+
+export { GridView };

package/src/index.ts

@@ -1,29 +1,21 @@
-export {
-    type ColumnDef,
-    type ColumnDefDeclarativeProps,
-    ColumnView,
-    type ColumnViewDeclarativeProps,
-    type ColumnViewProps,
-    type ColumnViewSortProps,
-} from "./column-view.js";
-export { ConstraintLayout, type ConstraintLayoutProps } from "./constraint-layout.js";
-export type { ConstraintGuideProps, ConstraintProps, ConstraintVflProps } from "./constraint-layout-apply.js";
-export { DropDown, type DropDownDeclarativeProps, type DropDownItemRenderer, type DropDownProps } from "./drop-down.js";
-export { Fixed, type FixedChildProps, type FixedPlacementProps, type FixedProps } from "./fixed.js";
-export { Grid, type GridChildProps, type GridPlacement, type GridProps } from "./grid.js";
-export { GridView, type GridViewDeclarativeProps, type GridViewProps } from "./grid-view.js";
-export { ListView, type ListViewDeclarativeProps, type ListViewProps } from "./list-view.js";
-export { Menu, type MenuItemsProps, type MenuProps } from "./menu.js";
-export { Overlay, type OverlayChildProps, type OverlayPlacementProps, type OverlayProps } from "./overlay.js";
-export { SizeGroup, type SizeGroupChildProps, type SizeGroupProps } from "./size-group.js";
+export { ColumnView } from "./column-view.js";
+export { DropDown } from "./drop-down.js";
+export { GridView } from "./grid-view.js";
+export { ListView } from "./list-view.js";
+export { SizeGroup } from "./size-group.js";
 export type {
     ChildProps,
-    CollectionItemSizeProps,
-    ControlledExpansionProps,
-    ControlledSelectionProps,
-    ItemNode,
-    MenuEntry,
-    RenderItemProps,
-    SectionNode,
-    WidgetProps,
+    Column,
+    ColumnViewProps,
+    DropDownProps,
+    GridViewProps,
+    HeaderRenderer,
+    Item,
+    ItemRenderer,
+    ListViewProps,
+    RenderHeaderArgs,
+    RenderItemArgs,
+    Section,
+    SizeGroupChildProps,
+    SizeGroupProps,
 } from "./types.js";

package/src/internal/cells.tsx

@@ -0,0 +1,345 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import type { ReactNode } from "react";
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkTreeExpander } from "@gtkx/jsx/gtk";
+import { createPortal, useProperty } from "@gtkx/react";
+import { memo, useLayoutEffect, useState, useSyncExternalStore } from "react";
+import type { HeaderRenderer, Item, ItemRenderer, RenderItemArgs } from "../types.js";
+import type { Collection } from "./collection.js";
+import { getId } from "./collection-model.js";
+
+type CellSize = {
+    width: number;
+    height: number;
+};
+
+type CellHost = GObject.Object & {
+    getChild: () => Gtk.Widget | null;
+    setChild: (child: Gtk.Widget | null) => void;
+};
+
+type CellEntry<C extends CellHost> = {
+    key: string;
+    cell: C;
+    item: GObject.Object | null;
+    listeners: Set<() => void>;
+    subscribe: (onChange: () => void) => () => void;
+    getItem: () => GObject.Object | null;
+};
+
+type FactoryHandlers = {
+    onSetup: (cell: GObject.Object) => void;
+    onBind: (cell: GObject.Object) => void;
+    onUnbind: (cell: GObject.Object) => void;
+    onTeardown: (cell: GObject.Object) => void;
+};
+
+type CellStore<C extends CellHost> = {
+    handlers: FactoryHandlers;
+    setSize: (size: CellSize) => void;
+    subscribe: (onChange: () => void) => () => void;
+    getSnapshot: () => CellEntry<C>[];
+};
+
+type StoreState<C extends CellHost> = {
+    size: CellSize;
+    entries: Map<C, CellEntry<C>>;
+    snapshot: CellEntry<C>[] | null;
+    listeners: Set<() => void>;
+    serial: number;
+};
+
+type CellGuard<C extends CellHost> = (value: GObject.Object) => value is C;
+
+type ItemBodyOptions = {
+    item: GObject.Object | null;
+    position: number | undefined;
+    row: Gtk.TreeListRow | null;
+    isRowExpanded: boolean | undefined;
+    render: ItemRenderer<never>;
+    collection: Collection;
+    expandedIds: string[] | null | undefined;
+};
+
+type ItemCellProps = {
+    entry: CellEntry<Gtk.ListItem>;
+    render: ItemRenderer<never>;
+    collection: Collection;
+    expandedIds: string[] | null | undefined;
+};
+
+type ItemPortalsProps = {
+    store: CellStore<Gtk.ListItem>;
+    render: ItemRenderer<never>;
+    collection: Collection;
+    expandedIds?: string[] | null | undefined;
+};
+
+type HeaderCellProps = {
+    entry: CellEntry<Gtk.ListHeader>;
+    render: HeaderRenderer<never>;
+    collection: Collection;
+};
+
+type HeaderPortalsProps = {
+    store: CellStore<Gtk.ListHeader>;
+    render: HeaderRenderer<never>;
+    collection: Collection;
+};
+
+const ItemCell = memo(ItemCellImpl);
+const HeaderCell = memo(HeaderCellImpl);
+
+const isListItem = (value: GObject.Object): value is Gtk.ListItem => value instanceof Gtk.ListItem;
+const isListHeader = (value: GObject.Object): value is Gtk.ListHeader => value instanceof Gtk.ListHeader;
+
+const placeholder = (size: CellSize): Gtk.Widget =>
+    new Gtk.Box({ widthRequest: size.width, heightRequest: size.height });
+
+function notifyEntry<C extends CellHost>(entry: CellEntry<C>): void {
+    for (const listener of entry.listeners) {
+        listener();
+    }
+}
+
+function notifyRoster<C extends CellHost>(state: StoreState<C>): void {
+    state.snapshot = null;
+
+    for (const listener of state.listeners) {
+        listener();
+    }
+}
+
+function createEntry<C extends CellHost>(state: StoreState<C>, cell: C): CellEntry<C> {
+    state.serial += 1;
+
+    const entry: CellEntry<C> = {
+        key: `gtkx-cell-${String(state.serial)}`,
+        cell,
+        item: null,
+        listeners: new Set(),
+        subscribe: (onChange) => {
+            entry.listeners.add(onChange);
+
+            return () => {
+                entry.listeners.delete(onChange);
+            };
+        },
+        getItem: () => entry.item,
+    };
+
+    return entry;
+}
+
+function setupCell<C extends CellHost>(state: StoreState<C>, cell: C): void {
+    cell.setChild(placeholder(state.size));
+    state.entries.set(cell, createEntry(state, cell));
+    notifyRoster(state);
+}
+
+function teardownCell<C extends CellHost>(state: StoreState<C>, cell: C): void {
+    if (state.entries.delete(cell)) {
+        notifyRoster(state);
+    }
+}
+
+function writeBinding<C extends CellHost>(state: StoreState<C>, cell: C, item: GObject.Object | null): void {
+    const entry = state.entries.get(cell);
+
+    if (entry === undefined) {
+        return;
+    }
+
+    entry.item = item;
+    notifyEntry(entry);
+}
+
+function boundItem(cell: CellHost): GObject.Object | null {
+    if (cell instanceof Gtk.ListItem) {
+        return cell.getItem();
+    }
+
+    return cell instanceof Gtk.ListHeader ? cell.getItem() : null;
+}
+
+function bindCell<C extends CellHost>(state: StoreState<C>, cell: C): void {
+    if (cell.getChild() === null) {
+        cell.setChild(placeholder(state.size));
+    }
+
+    writeBinding(state, cell, boundItem(cell));
+}
+
+function subscribeRoster<C extends CellHost>(state: StoreState<C>, onChange: () => void): () => void {
+    state.listeners.add(onChange);
+
+    return () => {
+        state.listeners.delete(onChange);
+    };
+}
+
+function rosterSnapshot<C extends CellHost>(state: StoreState<C>): CellEntry<C>[] {
+    state.snapshot ??= state.entries.values().toArray();
+
+    return state.snapshot;
+}
+
+function guarded<C extends CellHost>(isCell: CellGuard<C>, run: (cell: C) => void): (cell: GObject.Object) => void {
+    return (cell) => {
+        if (isCell(cell)) {
+            run(cell);
+        }
+    };
+}
+
+function createHandlers<C extends CellHost>(state: StoreState<C>, isCell: CellGuard<C>): FactoryHandlers {
+    return {
+        onSetup: guarded(isCell, (cell) => {
+            setupCell(state, cell);
+        }),
+        onBind: guarded(isCell, (cell) => {
+            bindCell(state, cell);
+        }),
+        onUnbind: guarded(isCell, (cell) => {
+            writeBinding(state, cell, null);
+        }),
+        onTeardown: guarded(isCell, (cell) => {
+            teardownCell(state, cell);
+        }),
+    };
+}
+
+function createCellStore<C extends CellHost>(isCell: CellGuard<C>, size: CellSize): CellStore<C> {
+    const state: StoreState<C> = {
+        size,
+        entries: new Map(),
+        snapshot: null,
+        listeners: new Set(),
+        serial: 0,
+    };
+
+    return {
+        handlers: createHandlers(state, isCell),
+        setSize: (next) => {
+            state.size = next;
+        },
+        subscribe: (onChange) => subscribeRoster(state, onChange),
+        getSnapshot: () => rosterSnapshot(state),
+    };
+}
+
+function useCellStore<C extends CellHost>(isCell: CellGuard<C>, size: CellSize): CellStore<C> {
+    const [store] = useState(() => createCellStore(isCell, size));
+
+    useLayoutEffect(() => {
+        store.setSize(size);
+    });
+
+    return store;
+}
+
+function useItemCells(size: CellSize): CellStore<Gtk.ListItem> {
+    return useCellStore(isListItem, size);
+}
+
+function useHeaderCells(size: CellSize): CellStore<Gtk.ListHeader> {
+    return useCellStore(isListHeader, size);
+}
+
+function isRowWanted(options: ItemBodyOptions, item: Item): boolean {
+    const { expandedIds } = options;
+
+    return expandedIds == null ? options.isRowExpanded === true : expandedIds.includes(item.id);
+}
+
+function itemArgs(item: Item, options: ItemBodyOptions): RenderItemArgs<unknown> {
+    const args: RenderItemArgs<unknown> = { item: item.value, index: options.position ?? 0 };
+    const row = options.row;
+
+    if (row === null) {
+        return args;
+    }
+
+    args.depth = row.getDepth();
+
+    if (row.isExpandable()) {
+        args.isExpanded = isRowWanted(options, item);
+    }
+
+    return args;
+}
+
+function wrapExpander(item: Item, row: Gtk.TreeListRow | null, content: ReactNode): ReactNode {
+    const expander: ReactNode =
+        row === null
+            ? (
+                    content
+                )
+            : (
+                    <GtkTreeExpander
+                        listRow={row}
+                        hideExpander={item.hideExpander ?? false}
+                        indentForDepth={item.indentForDepth ?? true}
+                        indentForIcon={item.indentForIcon ?? true}
+                    >
+                        {content}
+                    </GtkTreeExpander>
+                );
+
+    return expander;
+}
+
+function itemBody(options: ItemBodyOptions): ReactNode {
+    const id = getId(options.item);
+    const item = id === null ? undefined : options.collection.itemFor(id);
+
+    if (item === undefined) {
+        return null;
+    }
+
+    const render = options.render as ItemRenderer<unknown>;
+
+    return wrapExpander(item, options.row, render(itemArgs(item, options)));
+}
+
+function ItemCellImpl({ entry, render, collection, expandedIds }: ItemCellProps): ReactNode {
+    const item = useSyncExternalStore(entry.subscribe, entry.getItem);
+    const position = useProperty(entry.cell, "position");
+    const row = item instanceof Gtk.TreeListRow ? item : null;
+    const isRowExpanded = useProperty(row, "expanded");
+    const body = itemBody({ item, position, row, isRowExpanded, render, collection, expandedIds });
+
+    return createPortal(body, entry.cell, entry.key);
+}
+
+function HeaderCellImpl({ entry, render, collection }: HeaderCellProps): ReactNode {
+    const item = useSyncExternalStore(entry.subscribe, entry.getItem);
+    const id = getId(item);
+    const renderHeader = render as HeaderRenderer<unknown>;
+    const body = id === null ? null : renderHeader({ section: collection.sectionFor(id) });
+
+    return createPortal(body, entry.cell, entry.key);
+}
+
+function usePortalEntries<C extends CellHost>(store: CellStore<C>): CellEntry<C>[] {
+    return useSyncExternalStore(store.subscribe, store.getSnapshot);
+}
+
+const ItemPortals = ({ store, render, collection, expandedIds }: ItemPortalsProps): ReactNode =>
+    usePortalEntries(store).map((entry) => (
+        <ItemCell key={entry.key} entry={entry} render={render} collection={collection} expandedIds={expandedIds} />
+    ));
+
+const HeaderPortals = ({ store, render, collection }: HeaderPortalsProps): ReactNode =>
+    usePortalEntries(store).map((entry) => (
+        <HeaderCell key={entry.key} entry={entry} render={render} collection={collection} />
+    ));
+
+export {
+    useItemCells,
+    useHeaderCells,
+    ItemPortals,
+    HeaderPortals,
+    type CellSize,
+    type CellStore,
+};

package/src/internal/collection-index.ts

@@ -0,0 +1,168 @@
+import type { Item, Section } from "../types.js";
+
+type Level = {
+    key: string;
+    ids: string[];
+    isExpandable: boolean[];
+};
+
+type CollectionIndex = {
+    isTree: boolean;
+    size: number;
+    groups: Level[];
+    children: Map<string, Level>;
+    has: (id: string) => boolean;
+    itemFor: (id: string) => Item | undefined;
+    sectionFor: (id: string) => unknown;
+    positionFor: (id: string) => number;
+};
+
+type IndexState = {
+    isTree: boolean;
+    groups: Level[];
+    children: Map<string, Level>;
+    itemsById: Map<string, Item>;
+    sections: Section[] | undefined;
+    positions: Map<string, number> | null;
+    starts: number[] | null;
+};
+
+const ROOT_LEVEL_KEY = "";
+
+const hasChildren = (item: Item): boolean => item.children !== undefined && item.children.length > 0;
+const childLevelKey = (id: string): string => `child:${id}`;
+
+function collectChildren(state: IndexState, level: Level, item: Item): void {
+    if (!state.isTree) {
+        return;
+    }
+
+    const canExpand = hasChildren(item);
+    level.isExpandable.push(canExpand);
+
+    if (!canExpand) {
+        return;
+    }
+
+    const key = childLevelKey(item.id);
+    state.children.set(key, collectLevel(state, key, item.children ?? []));
+}
+
+function collectLevel(state: IndexState, key: string, items: Item[]): Level {
+    const level: Level = { key, ids: [], isExpandable: [] };
+
+    for (const item of items) {
+        level.ids.push(item.id);
+        state.itemsById.set(item.id, item);
+        collectChildren(state, level, item);
+    }
+
+    return level;
+}
+
+function buildPositions(state: IndexState): void {
+    const positions: Map<string, number> = new Map();
+    const starts: number[] = [];
+    let offset = 0;
+
+    for (const level of state.groups) {
+        starts.push(offset);
+
+        for (const id of level.ids) {
+            positions.set(id, offset);
+            offset += 1;
+        }
+    }
+
+    state.positions = positions;
+    state.starts = starts;
+}
+
+function positionFor(state: IndexState, id: string): number {
+    if (state.isTree) {
+        return -1;
+    }
+
+    if (state.positions === null) {
+        buildPositions(state);
+    }
+
+    return state.positions?.get(id) ?? -1;
+}
+
+function sectionAt(starts: number[], position: number): number {
+    let low = 0;
+    let high = starts.length - 1;
+
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+
+        if ((starts[middle] ?? 0) <= position) {
+            low = middle;
+        } else {
+            high = middle - 1;
+        }
+    }
+
+    return low;
+}
+
+function sectionFor(state: IndexState, id: string): unknown {
+    const sections = state.sections;
+    const position = positionFor(state, id);
+
+    if (sections === undefined || position < 0 || state.starts === null) {
+        return undefined;
+    }
+
+    return sections[sectionAt(state.starts, position)]?.value;
+}
+
+function buildGroups(state: IndexState, source: Item[], sections: Section[] | undefined): Level[] {
+    if (sections === undefined) {
+        return [collectLevel(state, ROOT_LEVEL_KEY, source)];
+    }
+
+    return sections.map((section) => collectLevel(state, section.id, section.data));
+}
+
+function isTreeSource(source: Item[], sections: Section[] | undefined, isFlat: boolean): boolean {
+    if (sections !== undefined || isFlat) {
+        return false;
+    }
+
+    return source.some((item) => hasChildren(item));
+}
+
+function createCollectionIndex(
+    items: Item[] | undefined,
+    sections: Section[] | undefined,
+    isFlat: boolean,
+): CollectionIndex {
+    const source = items ?? [];
+
+    const state: IndexState = {
+        isTree: isTreeSource(source, sections, isFlat),
+        groups: [],
+        children: new Map(),
+        itemsById: new Map(),
+        sections,
+        positions: null,
+        starts: null,
+    };
+
+    state.groups = buildGroups(state, source, sections);
+
+    return {
+        isTree: state.isTree,
+        size: state.itemsById.size,
+        groups: state.groups,
+        children: state.children,
+        has: (id) => state.itemsById.has(id),
+        itemFor: (id) => state.itemsById.get(id),
+        sectionFor: (id) => sectionFor(state, id),
+        positionFor: (id) => positionFor(state, id),
+    };
+}
+
+export { createCollectionIndex, childLevelKey, ROOT_LEVEL_KEY, type CollectionIndex, type Level };