@gtkx/components 1.0.0-rc.4 → 1.0.0

package/src/internal/controlled-sync.ts

@@ -0,0 +1,34 @@
+import { startTransition, useEffectEvent, useLayoutEffect, useState } from "react";
+import type { Collection } from "./collection.js";
+
+type ControlledIds = string[] | null | undefined;
+
+type ControlledSyncOptions = {
+    ids: ControlledIds;
+    collection: Collection;
+    widget?: object | null | undefined;
+    apply: (ids: ControlledIds) => void;
+};
+
+function useControlledSync(options: ControlledSyncOptions): () => void {
+    const { ids, collection, widget } = options;
+    const [drift, setDrift] = useState(0);
+
+    const markDrift = (): void => {
+        startTransition(() => {
+            setDrift((count) => count + 1);
+        });
+    };
+
+    const apply = useEffectEvent((next: ControlledIds): void => {
+        options.apply(next);
+    });
+
+    useLayoutEffect(() => {
+        apply(ids);
+    }, [widget, collection, ids, drift]);
+
+    return markDrift;
+}
+
+export { useControlledSync };

package/src/internal/drop-down.tsx

@@ -1,12 +1,11 @@
 import type * as GObject from "@gtkx/gi/gobject";
 import type { ElementType, ReactNode, Ref } from "react";
 import { GtkLabel, GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
-import { applyWrite } from "@gtkx/react/internal";
 import { omit } from "@gtkx/utils";
-import { useEffectEvent, useLayoutEffect, useRef } from "react";
+import { useEffectEvent, useLayoutEffect, useRef, useState } from "react";
 import type { DropDownOwnProps, ListItemRenderArgs, ListItemRenderer } from "../types.js";
 import type { Collection } from "./collection.js";
-import { HeaderPortals, ItemPortals, useHeaderCells, useItemCells } from "./cells.js";
+import { ItemPortals, useItemCells, useSectionHeader } from "./cells.js";
 import { useCollectionData } from "./use-collection.js";
 import { useWidgetRef } from "./use-widget-ref.js";
 
@@ -24,6 +23,13 @@ type SelectionOptions = {
 };
 
 type NotifySelectedHandler = NonNullable<DropDownBaseProps["onNotifySelected"]>;
+type ApplyState = { isApplying: boolean };
+
+type NotifyContext = {
+    options: SelectionOptions;
+    known: { current: string | null };
+    state: ApplyState;
+};
 
 type KnownSelection = {
     known: { current: string | null };
@@ -43,6 +49,10 @@ const DROP_DOWN_PROPS: string[] = [
     "ref",
 ];
 
+function newApplyState(): ApplyState {
+    return { isApplying: false };
+}
+
 const describeValue = (value: unknown): string => {
     if (typeof value === "string") {
         return value;
@@ -61,9 +71,6 @@ const defaultItemContent = (value: unknown): ReactNode =>
 const defaultRenderItem = ({ item }: ListItemRenderArgs<unknown>): ReactNode => defaultItemContent(item);
 const faceRenderer = (props: DropDownBaseProps): ListItemRenderer<never> => props.renderItem ?? defaultRenderItem;
 
-const listRenderer = (props: DropDownBaseProps): ListItemRenderer<never> =>
-    props.renderListItem ?? props.renderItem ?? defaultRenderItem;
-
 const resolvePosition = (
     widget: SelectableWidget,
     collection: Collection,
@@ -110,16 +117,32 @@ const reportSelectedNotify = (options: SelectionOptions, tracker: KnownSelection
     reportKnownSelection(tracker, collection.idAt(widget.getSelected()));
 };
 
-const applySelectedPosition = (widget: SelectableWidget, position: number): void => {
-    applyWrite(() => {
+const applySelectedPosition = (widget: SelectableWidget, position: number, state: ApplyState): void => {
+    state.isApplying = true;
+
+    try {
         widget.selected = position;
-    });
+    } finally {
+        state.isApplying = false;
+    }
+};
+
+const dispatchSelectedNotify = (context: NotifyContext, value: number | null, self: SelectableWidget): void => {
+    const { options, known, state } = context;
+
+    if (state.isApplying) {
+        return;
+    }
+
+    reportSelectedNotify(options, { known, onSelectionChanged: options.props.onSelectionChanged });
+    options.props.onNotifySelected?.(value, self);
 };
 
 const useDropDownSelection = (options: SelectionOptions): NotifySelectedHandler => {
     const { widget, collection } = options;
     const { selectedId } = options.props;
     const known = useRef<string | null>(null);
+    const [applyState] = useState<ApplyState>(newApplyState);
 
     const syncKnownSelection = useEffectEvent((position: number): void => {
         const effectiveId = collection.idAt(position);
@@ -140,13 +163,12 @@ const useDropDownSelection = (options: SelectionOptions): NotifySelectedHandler
         }
 
         const position = resolvePosition(widget, collection, selectedId);
-        applySelectedPosition(widget, position);
+        applySelectedPosition(widget, position, applyState);
         syncKnownSelection(position);
-    }, [widget, collection, selectedId]);
+    }, [widget, collection, selectedId, applyState]);
 
     return (value, self) => {
-        reportSelectedNotify(options, { known, onSelectionChanged: options.props.onSelectionChanged });
-        options.props.onNotifySelected?.(value, self);
+        dispatchSelectedNotify({ options, known, state: applyState }, value, self);
     };
 };
 
@@ -154,12 +176,11 @@ function DropDownBase(props: DropDownBaseProps & { component: ElementType }): Re
     const { component: Component, items, sections, renderListItem, renderHeader, ref } = props;
     const rest = omit(props, DROP_DOWN_PROPS);
     const [widget, refCallback] = useWidgetRef<SelectableWidget>(ref);
-    const collection = useCollectionData({ items, sections });
+    const collection = useCollectionData({ items, sections, isFlat: true });
     const faceCells = useItemCells({ width: -1, height: -1 });
     const listCells = useItemCells({ width: -1, height: -1 });
-    const headerCells = useHeaderCells({ width: -1, height: -1 });
+    const header = useSectionHeader(renderHeader, collection, { width: -1, height: -1 });
     const handleNotifySelected = useDropDownSelection({ widget, collection, props });
-    const hasHeader = typeof renderHeader === "function";
 
     return (
         <>
@@ -170,15 +191,15 @@ function DropDownBase(props: DropDownBaseProps & { component: ElementType }): Re
                 {...(renderListItem != null && {
                     listFactory: <GtkSignalListItemFactory {...listCells.handlers} />,
                 })}
-                {...(hasHeader && { headerFactory: <GtkSignalListItemFactory {...headerCells.handlers} /> })}
+                {...header.factoryProps}
                 {...rest}
                 onNotifySelected={handleNotifySelected}
             />
-            <ItemPortals store={faceCells} render={faceRenderer(props)} collection={collection} />
+            <ItemPortals registry={faceCells} render={faceRenderer(props)} collection={collection} />
             {renderListItem != null && (
-                <ItemPortals store={listCells} render={listRenderer(props)} collection={collection} />
+                <ItemPortals registry={listCells} render={renderListItem} collection={collection} />
             )}
-            {hasHeader && <HeaderPortals store={headerCells} render={renderHeader} collection={collection} />}
+            {header.portals}
         </>
     );
 }

package/src/internal/expansion.ts

@@ -1,8 +1,14 @@
 import type * as Gtk from "@gtkx/gi/gtk";
-import type { RefObject } from "react";
-import { useEffectEvent, useLayoutEffect, useRef, useState } from "react";
+import { useState } from "react";
 import type { Collection } from "./collection.js";
-import { eachRow } from "./collection.js";
+import type { TreeExpansion } from "./tree-expansion.js";
+import type { VisibleOrder, WalkOptions } from "./tree-order.js";
+import { isCollectionIdle } from "./collection.js";
+import { useControlledSync } from "./controlled-sync.js";
+import { joinParts } from "./keys.js";
+import { trackPaths } from "./slots.js";
+import { adoptOrder, markExpanded, orderFor } from "./tree-expansion.js";
+import { walkVisible } from "./tree-order.js";
 
 type ExpansionOptions = {
     collection: Collection;
@@ -10,113 +16,144 @@ type ExpansionOptions = {
     onExpandedChange?: ((ids: string[]) => void) | null | undefined;
 };
 
+type ItemsChange = {
+    position: number;
+    removed: number;
+    added: number;
+};
+
+type ItemsChangeHandler = (position: number, removed: number, added: number) => void;
 type LastExpansion = { key: string };
 
+type ExpansionContext = {
+    collection: Collection;
+    last: LastExpansion;
+    onExpandedChange?: ((ids: string[]) => void) | null | undefined;
+};
+
 function newLastExpansion(): LastExpansion {
     return { key: "" };
 }
 
-function collectExpanded(row: Gtk.TreeListRow, id: string | null, ids: string[]): void {
-    if (id !== null && row.getExpanded()) {
-        ids.push(id);
+function wantedSet(expansion: TreeExpansion, expandedIds: string[]): Set<string> {
+    const wanted: Set<string> = new Set();
+
+    for (const id of expandedIds) {
+        for (const path of expansion.index.expandablePathsFor(id)) {
+            wanted.add(path);
+        }
     }
+
+    return wanted;
 }
 
-function expandRow(row: Gtk.TreeListRow, id: string | null, wanted: Set<string>): void {
-    const isDesired = id !== null && wanted.has(id);
+function hasSameExpansion(expanded: Set<string>, wanted: Set<string>): boolean {
+    return expanded.size === wanted.size && wanted.isSubsetOf(expanded);
+}
 
-    if (row.isExpandable() && row.getExpanded() !== isDesired) {
-        row.setExpanded(isDesired);
-    }
+function toggleOptions(expansion: TreeExpansion, tree: Gtk.TreeListModel, wanted: Set<string>): WalkOptions {
+    return {
+        index: expansion.index,
+        slots: trackPaths(wanted),
+        marks: trackPaths(wanted.symmetricDifference(expansion.expanded)),
+        visit: (row) => {
+            if (row.isMarked) {
+                tree.getRow(row.position)?.setExpanded(row.isOpen);
+            }
+        },
+    };
 }
 
-function applyExpansion(tree: Gtk.TreeListModel, expandedIds: string[]): void {
-    const wanted = new Set(expandedIds);
+function walkApplying(expansion: TreeExpansion, options: WalkOptions): VisibleOrder {
+    expansion.isApplying = true;
 
-    eachRow(tree, (row, id) => {
-        expandRow(row, id, wanted);
-    });
+    try {
+        return walkVisible(options);
+    } finally {
+        expansion.isApplying = false;
+    }
 }
 
-function reportExpansion(
-    collection: Collection,
-    last: LastExpansion,
-    onExpandedChange: ((ids: string[]) => void) | null | undefined,
-): void {
-    const tree = collection.treeModel();
+function applyWanted(expansion: TreeExpansion, tree: Gtk.TreeListModel, expandedIds: string[]): void {
+    const wanted = wantedSet(expansion, expandedIds);
 
-    if (tree === null) {
+    if (hasSameExpansion(expansion.expanded, wanted)) {
         return;
     }
 
-    const ids: string[] = [];
-
-    eachRow(tree, (row, id) => {
-        collectExpanded(row, id, ids);
-    });
+    adoptOrder(expansion, walkApplying(expansion, toggleOptions(expansion, tree, wanted)));
+}
 
-    const key = ids.join(" ");
+function reportExpansion(context: ExpansionContext): void {
+    const { expandedIds, expandedPaths } = orderFor(context.collection.expansion);
+    const key = joinParts(expandedPaths);
 
-    if (last.key === key) {
+    if (context.last.key === key) {
         return;
     }
 
-    last.key = key;
-    onExpandedChange?.(ids);
+    context.last.key = key;
+    context.onExpandedChange?.([...expandedIds]);
 }
 
-function reportWhenIdle(
-    collection: Collection,
-    last: LastExpansion,
-    expanding: RefObject<boolean>,
-    onExpandedChange: ((ids: string[]) => void) | null | undefined,
-): void {
-    if (expanding.current) {
+function applyControlledExpansion(context: ExpansionContext, expandedIds: string[] | null | undefined): void {
+    const tree = context.collection.treeModel();
+
+    if (tree === null) {
         return;
     }
 
-    reportExpansion(collection, last, onExpandedChange);
+    applyWanted(context.collection.expansion, tree, expandedIds ?? []);
+    reportExpansion(context);
 }
 
-function runControlledExpansion(
-    collection: Collection,
-    expandedIds: string[] | null | undefined,
-    expanding: RefObject<boolean>,
-    report: () => void,
-): void {
-    const tree = collection.treeModel();
+function isExpansionIdle(collection: Collection): boolean {
+    return collection.treeModel() !== null && isCollectionIdle(collection);
+}
 
-    if (tree === null || expandedIds == null) {
-        return;
+function didRowDrift(collection: Collection, change: ItemsChange): boolean {
+    const path = collection.pathAt(change.position - 1);
+    const isExpanded = change.removed === 0 && change.added > 0;
+    const isCollapsed = change.added === 0 && change.removed > 0;
+
+    if (path === null || isExpanded === isCollapsed) {
+        return false;
     }
 
-    expanding.current = true;
+    markExpanded(collection.expansion, path, isExpanded);
 
-    try {
-        applyExpansion(tree, expandedIds);
-    } finally {
-        expanding.current = false;
+    return true;
+}
+
+function observeExpansion(context: ExpansionContext, change: ItemsChange, onDrift: () => void): void {
+    if (!isExpansionIdle(context.collection)) {
+        return;
     }
 
-    report();
+    const didDrift = didRowDrift(context.collection, change);
+    reportExpansion(context);
+
+    if (didDrift) {
+        onDrift();
+    }
 }
 
-function useExpansion(options: ExpansionOptions): () => void {
+function useExpansion(options: ExpansionOptions): ItemsChangeHandler {
     const { collection, expandedIds, onExpandedChange } = options;
     const [last] = useState<LastExpansion>(newLastExpansion);
-    const expanding = useRef(false);
-
-    const report = useEffectEvent((): void => {
-        reportWhenIdle(collection, last, expanding, onExpandedChange);
+    const context: ExpansionContext = { collection, last, onExpandedChange };
+
+    const markDrift = useControlledSync({
+        ids: expandedIds,
+        collection,
+        apply: (ids) => {
+            applyControlledExpansion(context, ids);
+        },
     });
 
-    useLayoutEffect(() => {
-        runControlledExpansion(collection, expandedIds, expanding, report);
-    }, [collection, expandedIds]);
-
-    return () => {
-        reportWhenIdle(collection, last, expanding, onExpandedChange);
+    return (position, removed, added) => {
+        observeExpansion(context, { position, removed, added }, markDrift);
     };
 }
 
-export { useExpansion, type ExpansionOptions };
+export { useExpansion, type ItemsChangeHandler };

package/src/internal/keys.ts

@@ -0,0 +1,18 @@
+const LENGTH_SEPARATOR = "\u{1}";
+
+const encodePart = (value: string): string => `${String(value.length)}${LENGTH_SEPARATOR}${value}`;
+const joinParts = (values: string[]): string => values.map((value) => encodePart(value)).join("");
+
+const decodePartAt = (value: string, offset: number): string | null => {
+    const separator = value.indexOf(LENGTH_SEPARATOR, offset);
+
+    if (separator === -1) {
+        return null;
+    }
+
+    const length = Number(value.slice(offset, separator));
+
+    return value.slice(separator + 1, separator + 1 + length);
+};
+
+export { decodePartAt, encodePart, joinParts };

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 };