@gtkx/components 1.0.0-rc.4 → 1.1.0

package/src/internal/selection.tsx

@@ -2,15 +2,19 @@ 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 { useState } from "react";
 import type { Collection } from "./collection.js";
+import type { ItemsChangeHandler } from "./expansion.js";
+import { isCollectionIdle } from "./collection.js";
+import { useControlledSync } from "./controlled-sync.js";
+import { joinParts } from "./keys.js";
 
 type SelectionOptions = {
     collection: Collection;
     selectedIds?: string[] | null | undefined;
     onSelectionChanged?: ((ids: string[]) => void) | null | undefined;
     selectionMode?: Gtk.SelectionMode | null | undefined;
-    onItemsChanged: () => void;
+    onItemsChanged: ItemsChangeHandler;
 };
 
 type LastSelection = {
@@ -18,29 +22,60 @@ type LastSelection = {
     key: string | null;
 };
 
+type SelectionContext = {
+    selection: Gtk.SelectionModel | null;
+    collection: Collection;
+    last: LastSelection;
+    onSelectionChanged?: ((ids: string[]) => void) | null | undefined;
+};
+
 type SelectionElementProps = {
     ref: (value: Gtk.SelectionModel | null) => void;
     model: Gio.ListModel;
     onSelectionChanged: () => void;
-    onItemsChanged: () => void;
+    onItemsChanged: ItemsChangeHandler;
 };
 
-function getSelectedIds(selection: Gtk.SelectionModel, collection: Collection): string[] {
+function selectedPositions(selection: Gtk.SelectionModel): number[] {
     const bitset = selection.getSelection();
     const size = Number(bitset.getSize());
-    const ids: string[] = [];
+    const positions: number[] = [];
 
     for (let index = 0; index < size; index++) {
-        pushId(collection.idAt(bitset.getNth(index)), ids);
+        positions.push(bitset.getNth(index));
+    }
+
+    return positions;
+}
+
+function idsAt(collection: Collection, positions: number[]): string[] {
+    const ids: string[] = [];
+
+    for (const position of positions) {
+        const id = collection.idAt(position);
+
+        if (id !== null) {
+            ids.push(id);
+        }
     }
 
     return ids;
 }
 
-function pushId(id: string | null, ids: string[]): void {
-    if (id !== null) {
-        ids.push(id);
+function plannedPositions(context: SelectionContext, ids: string[]): number[] | null {
+    const { selection, collection } = context;
+
+    if (selection === null || selection instanceof Gtk.NoSelection) {
+        return null;
     }
+
+    const positions = collection.positionsFor(ids);
+
+    if (ids.length > 0 && positions.length === 0) {
+        return null;
+    }
+
+    return selection instanceof Gtk.SingleSelection ? positions.slice(0, 1) : positions;
 }
 
 function applySingleSelection(selection: Gtk.SingleSelection, positions: number[]): void {
@@ -65,17 +100,7 @@ function applyMultiSelection(selection: Gtk.SelectionModel, positions: number[])
     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;
-    }
-
+function applySelection(selection: Gtk.SelectionModel, positions: number[]): void {
     if (selection instanceof Gtk.SingleSelection) {
         applySingleSelection(selection, positions);
 
@@ -85,26 +110,20 @@ function applySelection(selection: Gtk.SelectionModel, collection: Collection, i
     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(" ");
+function reportSelection(context: SelectionContext, ids: string[]): void {
+    const key = joinParts(ids);
 
-    if (last.selection === selection && last.key === key) {
+    if (context.last.selection === context.selection && context.last.key === key) {
         return;
     }
 
-    last.selection = selection;
-    last.key = key;
-    onSelectionChanged?.(ids);
+    context.last.selection = context.selection;
+    context.last.key = key;
+    context.onSelectionChanged?.(ids);
+}
+
+function hasSelectionDrifted(actual: number[], planned: number[]): boolean {
+    return actual.length !== planned.length || planned.some((position, index) => actual[index] !== position);
 }
 
 function selectionElement(mode: Gtk.SelectionMode | null | undefined, props: SelectionElementProps): ReactElement {
@@ -119,16 +138,45 @@ function selectionElement(mode: Gtk.SelectionMode | null | undefined, props: Sel
     return <GtkSingleSelection {...props} autoselect={false} canUnselect />;
 }
 
-function syncSelection(
-    selection: Gtk.SelectionModel | null,
-    collection: Collection,
+function applyControlledSelection(context: SelectionContext, selectedIds: string[] | null | undefined): void {
+    const { selection, collection } = context;
+
+    if (selection === null) {
+        return;
+    }
+
+    const planned = plannedPositions(context, selectedIds ?? []);
+
+    if (planned !== null) {
+        applySelection(selection, planned);
+    }
+
+    reportSelection(context, idsAt(collection, selectedPositions(selection)));
+}
+
+function observeSelection(
+    context: SelectionContext,
     selectedIds: string[] | null | undefined,
+    onDrift: () => void,
 ): void {
-    if (selection === null || selectedIds == null) {
+    const { selection, collection } = context;
+
+    if (selection === null) {
+        return;
+    }
+
+    const positions = selectedPositions(selection);
+    reportSelection(context, idsAt(collection, positions));
+
+    if (!isCollectionIdle(collection)) {
         return;
     }
 
-    applySelection(selection, collection, selectedIds);
+    const planned = plannedPositions(context, selectedIds ?? []);
+
+    if (planned !== null && hasSelectionDrifted(positions, planned)) {
+        onDrift();
+    }
 }
 
 function newLastSelection(): LastSelection {
@@ -139,24 +187,25 @@ 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);
+    const context: SelectionContext = { selection, collection, last, onSelectionChanged };
+
+    const markDrift = useControlledSync({
+        ids: selectedIds,
+        collection,
+        widget: selection,
+        apply: (ids) => {
+            applyControlledSelection(context, ids);
+        },
     });
 
-    useLayoutEffect(() => {
-        syncSelection(selection, collection, selectedIds);
-        report();
-    }, [selection, collection, selectedIds]);
-
     return selectionElement(selectionMode, {
         ref: setSelection,
         model: collection.model,
         onSelectionChanged: () => {
-            reportSelection(selection, collection, last, onSelectionChanged);
+            observeSelection(context, selectedIds, markDrift);
         },
         onItemsChanged: options.onItemsChanged,
     });
 }
 
-export { useSelection, type SelectionOptions };
+export { useSelection };

package/src/internal/slots.ts

@@ -0,0 +1,67 @@
+import { decodePartAt, encodePart } from "./keys.js";
+
+type SlotKey = {
+    levelPath: string;
+    slot: number;
+};
+
+type SlotMap = Map<string, Set<number>>;
+
+function getLevelBoundary(path: string): number {
+    let offset = 0;
+    let boundary = 0;
+
+    while (offset < path.length) {
+        const part = decodePartAt(path, offset);
+
+        if (part === null) {
+            return boundary;
+        }
+
+        boundary = offset;
+        offset += encodePart(part).length;
+    }
+
+    return boundary;
+}
+
+function getSlotKey(path: string): SlotKey | null {
+    const boundary = getLevelBoundary(path);
+    const part = decodePartAt(path, boundary);
+
+    if (part === null) {
+        return null;
+    }
+
+    return { levelPath: path.slice(0, boundary), slot: Number(part) };
+}
+
+function trackPath(slots: SlotMap, path: string): void {
+    const key = getSlotKey(path);
+
+    if (key === null) {
+        return;
+    }
+
+    const level = slots.get(key.levelPath);
+
+    if (level === undefined) {
+        slots.set(key.levelPath, new Set([key.slot]));
+
+        return;
+    }
+
+    level.add(key.slot);
+}
+
+function trackPaths(paths: Iterable<string>): SlotMap {
+    const slots: SlotMap = new Map();
+
+    for (const path of paths) {
+        trackPath(slots, path);
+    }
+
+    return slots;
+}
+
+export { getSlotKey, trackPath, trackPaths, type SlotMap };

package/src/internal/tree-expansion.ts

@@ -0,0 +1,115 @@
+import type { CollectionIndex } from "./collection-index.js";
+import type { SlotMap } from "./slots.js";
+import type { VisibleOrder } from "./tree-order.js";
+import { encodePart } from "./keys.js";
+import { getSlotKey, trackPath, trackPaths } from "./slots.js";
+import { buildVisibleOrder } from "./tree-order.js";
+
+type TreeExpansion = {
+    index: CollectionIndex;
+    expanded: Set<string>;
+    slots: SlotMap;
+    order: VisibleOrder | null;
+    isApplying: boolean;
+    isSyncing: boolean;
+};
+
+function dropLevel(expansion: TreeExpansion, path: string, pending: string[]): void {
+    expansion.expanded.delete(path);
+    const level = expansion.slots.get(path);
+
+    if (level === undefined) {
+        return;
+    }
+
+    expansion.slots.delete(path);
+
+    for (const slot of level) {
+        pending.push(path + encodePart(String(slot)));
+    }
+}
+
+function dropSubtree(expansion: TreeExpansion, path: string): void {
+    const pending: string[] = [path];
+
+    while (pending.length > 0) {
+        const current = pending.pop();
+
+        if (current !== undefined) {
+            dropLevel(expansion, current, pending);
+        }
+    }
+}
+
+function createTreeExpansion(index: CollectionIndex): TreeExpansion {
+    return { index, expanded: new Set(), slots: new Map(), order: null, isApplying: false, isSyncing: false };
+}
+
+function orderFor(expansion: TreeExpansion): VisibleOrder {
+    expansion.order ??= buildVisibleOrder(expansion.index, expansion.slots);
+
+    return expansion.order;
+}
+
+function adoptOrder(expansion: TreeExpansion, order: VisibleOrder): void {
+    expansion.expanded = new Set(order.expandedPaths);
+    expansion.slots = trackPaths(order.expandedPaths);
+    expansion.order = order;
+}
+
+function prunePath(expansion: TreeExpansion, path: string): void {
+    const key = getSlotKey(path);
+
+    if (key !== null) {
+        expansion.slots.get(key.levelPath)?.delete(key.slot);
+    }
+
+    dropSubtree(expansion, path);
+    expansion.order = null;
+}
+
+function pruneSlots(expansion: TreeExpansion, levelPath: string, isPruned: (slot: number) => boolean): void {
+    const level = expansion.slots.get(levelPath);
+
+    if (level === undefined) {
+        return;
+    }
+
+    for (const slot of level) {
+        if (!isPruned(slot)) {
+            continue;
+        }
+
+        level.delete(slot);
+        dropSubtree(expansion, levelPath + encodePart(String(slot)));
+    }
+
+    expansion.order = null;
+}
+
+function markExpanded(expansion: TreeExpansion, path: string, isExpanded: boolean): void {
+    if (isExpanded) {
+        expansion.expanded.add(path);
+        trackPath(expansion.slots, path);
+        expansion.order = null;
+
+        return;
+    }
+
+    prunePath(expansion, path);
+}
+
+function adoptIndex(expansion: TreeExpansion, index: CollectionIndex): void {
+    expansion.index = index;
+    expansion.order = null;
+}
+
+export {
+    adoptIndex,
+    adoptOrder,
+    createTreeExpansion,
+    markExpanded,
+    orderFor,
+    pruneSlots,
+    type TreeExpansion,
+};

package/src/internal/tree-order.ts

@@ -0,0 +1,208 @@
+import type { ListItem } from "../types.js";
+import type { CollectionIndex, Level } from "./collection-index.js";
+import type { SlotMap } from "./slots.js";
+
+type VisibleRow = {
+    item: ListItem;
+    position: number;
+    isOpen: boolean;
+    isMarked: boolean;
+};
+
+type VisibleOrder = {
+    expandedPaths: string[];
+    expandedIds: string[];
+};
+
+type RowVisitor = (row: VisibleRow) => void;
+
+type WalkOptions = {
+    index: CollectionIndex;
+    slots: SlotMap;
+    marks?: SlotMap | undefined;
+    visit?: RowVisitor | undefined;
+};
+
+type LevelFrame = {
+    level: Level;
+    cursor: number;
+};
+
+type WalkFrame = LevelFrame & {
+    open: Set<number> | undefined;
+    marked: Set<number> | undefined;
+};
+
+type WalkState = {
+    options: WalkOptions;
+    stack: WalkFrame[];
+    row: VisibleRow;
+    order: VisibleOrder;
+};
+
+type OpenFrame = LevelFrame & {
+    owner: ListItem | null;
+};
+
+type OpenWalk = {
+    index: CollectionIndex;
+    ids: Set<string>;
+    paths: Set<string>;
+    stack: OpenFrame[];
+    ancestors: Set<ListItem>;
+};
+
+const NO_ITEM: ListItem = { id: "", value: undefined };
+
+function advanceStack<F extends LevelFrame>(
+    stack: F[],
+    onSlot: (frame: F, slot: number) => void,
+    onLeave?: (frame: F) => void,
+): void {
+    const frame = stack.at(-1);
+
+    if (frame === undefined) {
+        return;
+    }
+
+    if (frame.cursor >= frame.level.items.length) {
+        stack.pop();
+        onLeave?.(frame);
+
+        return;
+    }
+
+    const slot = frame.cursor;
+    frame.cursor += 1;
+    onSlot(frame, slot);
+}
+
+function frameFor(options: WalkOptions, level: Level): WalkFrame {
+    return { level, cursor: 0, open: options.slots.get(level.path), marked: options.marks?.get(level.path) };
+}
+
+function descend(state: WalkState, level: Level, slot: number): void {
+    const child = state.options.index.childLevel(level, slot);
+
+    if (child === undefined) {
+        return;
+    }
+
+    state.order.expandedPaths.push(child.path);
+    state.order.expandedIds.push(state.row.item.id);
+    state.stack.push(frameFor(state.options, child));
+}
+
+function visitSlot(state: WalkState, frame: WalkFrame, slot: number): void {
+    const item = frame.level.items[slot];
+
+    if (item === undefined) {
+        return;
+    }
+
+    const { row } = state;
+    row.item = item;
+    row.isOpen = frame.open?.has(slot) ?? false;
+    row.isMarked = frame.marked?.has(slot) ?? false;
+    state.options.visit?.(row);
+    row.position += 1;
+
+    if (row.isOpen) {
+        descend(state, frame.level, slot);
+    }
+}
+
+function walkVisible(options: WalkOptions): VisibleOrder {
+    const order: VisibleOrder = { expandedPaths: [], expandedIds: [] };
+    const row: VisibleRow = { item: NO_ITEM, position: 0, isOpen: false, isMarked: false };
+    const frames = options.index.groups.map((level) => frameFor(options, level));
+    const state: WalkState = { options, stack: frames.toReversed(), row, order };
+
+    const onSlot = (frame: WalkFrame, slot: number): void => {
+        visitSlot(state, frame, slot);
+    };
+
+    while (state.stack.length > 0) {
+        advanceStack(state.stack, onSlot);
+    }
+
+    return order;
+}
+
+function openSlot(walk: OpenWalk, frame: OpenFrame, slot: number): void {
+    const item = frame.level.items[slot];
+
+    if (item === undefined || !walk.ids.has(item.id) || walk.ancestors.has(item)) {
+        return;
+    }
+
+    const child = walk.index.childLevel(frame.level, slot);
+
+    if (child === undefined) {
+        return;
+    }
+
+    walk.paths.add(child.path);
+    walk.ancestors.add(item);
+    walk.stack.push({ level: child, cursor: 0, owner: item });
+}
+
+function leaveOpenFrame(walk: OpenWalk, frame: OpenFrame): void {
+    if (frame.owner !== null) {
+        walk.ancestors.delete(frame.owner);
+    }
+}
+
+function expandedPathsFor(index: CollectionIndex, ids: Set<string>): Set<string> {
+    const paths: Set<string> = new Set();
+
+    if (ids.size === 0 || !index.isTree) {
+        return paths;
+    }
+
+    const frames = index.groups.map((level) => ({ level, cursor: 0, owner: null }));
+    const walk: OpenWalk = { index, ids, paths, stack: frames.toReversed(), ancestors: new Set() };
+
+    const onSlot = (frame: OpenFrame, slot: number): void => {
+        openSlot(walk, frame, slot);
+    };
+
+    const onLeave = (frame: OpenFrame): void => {
+        leaveOpenFrame(walk, frame);
+    };
+
+    while (walk.stack.length > 0) {
+        advanceStack(walk.stack, onSlot, onLeave);
+    }
+
+    return paths;
+}
+
+function buildVisibleOrder(index: CollectionIndex, slots: SlotMap): VisibleOrder {
+    return walkVisible({ index, slots });
+}
+
+function findPositions(index: CollectionIndex, slots: SlotMap, ids: Set<string>): number[] {
+    const found: number[] = [];
+
+    walkVisible({
+        index,
+        slots,
+        visit: (row) => {
+            if (ids.has(row.item.id)) {
+                found.push(row.position);
+            }
+        },
+    });
+
+    return found;
+}
+
+export {
+    buildVisibleOrder,
+    expandedPathsFor,
+    findPositions,
+    walkVisible,
+    type VisibleOrder,
+    type WalkOptions,
+};

package/src/internal/use-collection.tsx

@@ -23,13 +23,13 @@ type CollectionResult = {
 
 function useCollectionData(options: CollectionDataOptions): Collection {
     const { items, sections, isFlat } = options;
-    const [gtk] = useState(createCollectionModel);
+    const [collectionModel] = useState(createCollectionModel);
     const index = useMemo(() => createCollectionIndex(items, sections, isFlat === true), [items, sections, isFlat]);
-    const collection = useMemo(() => createCollection(gtk, index), [gtk, index]);
+    const collection = useMemo(() => createCollection(collectionModel, index), [collectionModel, index]);
 
     useLayoutEffect(() => {
-        gtk.sync(index);
-    }, [gtk, index]);
+        collectionModel.sync(index);
+    }, [collectionModel, index]);
 
     return collection;
 }
@@ -54,4 +54,4 @@ function useCollection(options: CollectionOptions): CollectionResult {
     return { collection, selection };
 }
 
-export { useCollection, useCollectionData, type CollectionDataOptions, type CollectionOptions };
+export { useCollection, useCollectionData };

package/src/list-view.tsx

@@ -2,7 +2,7 @@ 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 { ItemPortals, useItemCells, useSectionHeader } from "./internal/cells.js";
 import { useCollection } from "./internal/use-collection.js";
 
 const LIST_VIEW_PROPS = [
@@ -15,6 +15,7 @@ const LIST_VIEW_PROPS = [
     "selectionMode",
     "expandedIds",
     "onExpandedChange",
+    "expanderDescriptions",
     "estimatedItemHeight",
     "estimatedItemWidth",
 ] as const satisfies (keyof ListViewProps)[];
@@ -24,27 +25,30 @@ const LIST_VIEW_PROPS = [
  * controlled selection, controlled tree expansion, and estimated item sizing.
  */
 function ListView<T = unknown, S = unknown>(props: ListViewProps<T, S>): ReactNode {
-    const { renderItem, renderHeader, expandedIds, estimatedItemHeight, estimatedItemWidth } = props;
+    const { renderItem, renderHeader, expandedIds, expanderDescriptions } = props;
+    const { 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);
+    const header = useSectionHeader(renderHeader, collection, size);
 
     return (
         <>
             <GtkListView
                 model={selection}
                 factory={<GtkSignalListItemFactory {...itemCells.handlers} />}
-                {...(renderHeader != null && {
-                    headerFactory: <GtkSignalListItemFactory {...headerCells.handlers} />,
-                })}
+                {...header.factoryProps}
                 {...rest}
             />
-            <ItemPortals store={itemCells} render={renderItem} collection={collection} expandedIds={expandedIds} />
-            {renderHeader != null && (
-                <HeaderPortals store={headerCells} render={renderHeader} collection={collection} />
-            )}
+            <ItemPortals
+                registry={itemCells}
+                render={renderItem}
+                collection={collection}
+                expandedIds={expandedIds}
+                expanderDescriptions={expanderDescriptions}
+            />
+            {header.portals}
         </>
     );
 }