@gtkx/components 1.0.0-rc.4 → 1.1.0

package/src/internal/collection.ts

@@ -1,104 +1,84 @@
-import type * as GObject from "@gtkx/gi/gobject";
-import type * as Gtk from "@gtkx/gi/gtk";
 import type { ListItem } from "../types.js";
 import type { CollectionIndex } from "./collection-index.js";
-import type { CollectionModel } from "./collection-model.js";
-import { getId } from "./collection-model.js";
+import type { CollectionModel, SlotRef } from "./collection-model.js";
+import { slotPathAt, slotRefFor } from "./collection-model.js";
+import { findPositions } from "./tree-order.js";
 
-type Collection = {
+type Collection = Pick<CollectionModel, "model" | "expansion" | "rowAt"> & {
     isTree: boolean;
-    model: Gtk.FlattenListModel;
-    treeModel: () => Gtk.TreeListModel | null;
-    itemFor: (id: string) => ListItem | undefined;
-    sectionFor: (id: string) => unknown;
+    itemAt: (ref: SlotRef) => ListItem | undefined;
+    sectionFor: (levelPath: string) => unknown;
     idAt: (position: number) => string | null;
+    pathAt: (position: number) => string | null;
     positionFor: (id: string) => number;
     positionsFor: (ids: string[]) => number[];
 };
 
-const ascending = (a: number, b: number): number => a - b;
+const NO_POSITIONS: number[] = [];
 
-function visitRow(
-    tree: Gtk.TreeListModel,
-    position: number,
-    visit: (row: Gtk.TreeListRow, id: string | null) => void,
-): void {
-    const row = tree.getRow(position);
-
-    if (row === null) {
-        return;
+function positionsFor(collectionModel: CollectionModel, ids: string[]): number[] {
+    if (ids.length === 0) {
+        return NO_POSITIONS;
     }
 
-    visit(row, getId(row.getItem()));
-}
+    const { expansion } = collectionModel;
 
-function eachRow(tree: Gtk.TreeListModel, visit: (row: Gtk.TreeListRow, id: string | null) => void): void {
-    for (let position = 0; position < tree.getNItems(); position++) {
-        visitRow(tree, position, visit);
-    }
+    return findPositions(expansion.index, expansion.slots, new Set(ids));
 }
 
-function collectWanted(item: GObject.Object | null, position: number, wanted: Set<string>, out: number[]): void {
-    const id = getId(item);
+function positionFor(collectionModel: CollectionModel, id: string): number {
+    const [first = -1] = positionsFor(collectionModel, [id]);
 
-    if (id !== null && wanted.has(id)) {
-        out.push(position);
-    }
+    return first;
 }
 
-function scanPositions(tree: Gtk.TreeListModel, ids: string[]): number[] {
-    const wanted = new Set(ids);
-    const positions: number[] = [];
-    const count = tree.getNItems();
-
-    for (let position = 0; position < count; position++) {
-        collectWanted(tree.getItem(position), position, wanted, positions);
+function refAt(collectionModel: CollectionModel, position: number): SlotRef | null {
+    if (position < 0) {
+        return null;
     }
 
-    return positions;
+    return slotRefFor(collectionModel.model.getItem(position));
 }
 
-function indexPositions(index: CollectionIndex, ids: string[]): number[] {
-    const positions: number[] = [];
-
-    for (const id of ids) {
-        const position = index.positionFor(id);
+function itemAt(index: CollectionIndex, ref: SlotRef): ListItem | undefined {
+    return index.itemAt(ref.store.level.path, ref.slot);
+}
 
-        if (position >= 0) {
-            positions.push(position);
-        }
-    }
+function idAt(collectionModel: CollectionModel, index: CollectionIndex, position: number): string | null {
+    const ref = refAt(collectionModel, position);
 
-    return positions.toSorted(ascending);
+    return ref === null ? null : (itemAt(index, ref)?.id ?? null);
 }
 
-function positionsFor(gtk: CollectionModel, index: CollectionIndex, ids: string[]): number[] {
-    if (!index.isTree) {
-        return indexPositions(index, ids);
-    }
+function pathAt(collectionModel: CollectionModel, position: number): string | null {
+    const ref = refAt(collectionModel, position);
 
-    const tree = gtk.treeModel();
+    if (ref === null) {
+        return null;
+    }
 
-    return tree === null ? [] : scanPositions(tree, ids);
+    return slotPathAt(ref.store, ref.slot);
 }
 
-function positionFor(gtk: CollectionModel, index: CollectionIndex, id: string): number {
-    const [first = -1] = positionsFor(gtk, index, [id]);
+function isCollectionIdle(collection: Collection): boolean {
+    const { expansion } = collection;
 
-    return first;
+    return !expansion.isApplying && !expansion.isSyncing;
 }
 
-function createCollection(gtk: CollectionModel, index: CollectionIndex): Collection {
+function createCollection(collectionModel: CollectionModel, index: CollectionIndex): Collection {
     return {
+        model: collectionModel.model,
+        expansion: collectionModel.expansion,
         isTree: index.isTree,
-        model: gtk.model,
-        treeModel: () => (index.isTree ? gtk.treeModel() : null),
-        itemFor: index.itemFor,
+        rowAt: collectionModel.rowAt,
+        itemAt: (ref) => itemAt(index, ref),
         sectionFor: index.sectionFor,
-        idAt: (position) => getId(gtk.model.getItem(position)),
-        positionFor: (id) => positionFor(gtk, index, id),
-        positionsFor: (ids) => positionsFor(gtk, index, ids),
+        idAt: (position) => idAt(collectionModel, index, position),
+        pathAt: (position) => pathAt(collectionModel, position),
+        positionFor: (id) => positionFor(collectionModel, id),
+        positionsFor: (ids) => positionsFor(collectionModel, ids),
     };
 }
 
-export { createCollection, eachRow, type Collection };
+export { createCollection, isCollectionIdle, type Collection };

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,13 @@
-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 { expandedPathsFor, walkVisible } from "./tree-order.js";
 
 type ExpansionOptions = {
     collection: Collection;
@@ -10,113 +15,133 @@ 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 hasSameExpansion(expanded: Set<string>, wanted: Set<string>): boolean {
+    return expanded.size === wanted.size && wanted.isSubsetOf(expanded);
 }
 
-function expandRow(row: Gtk.TreeListRow, id: string | null, wanted: Set<string>): void {
-    const isDesired = id !== null && wanted.has(id);
-
-    if (row.isExpandable() && row.getExpanded() !== isDesired) {
-        row.setExpanded(isDesired);
-    }
+function toggleOptions(collection: Collection, wanted: Set<string>): WalkOptions {
+    const { expansion } = collection;
+
+    return {
+        index: expansion.index,
+        slots: trackPaths(wanted),
+        marks: trackPaths(wanted.symmetricDifference(expansion.expanded)),
+        visit: (row) => {
+            if (row.isMarked) {
+                collection.rowAt(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(collection: Collection, expandedIds: string[]): void {
+    const { expansion } = collection;
+    const wanted = expandedPathsFor(expansion.index, new Set(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(collection, 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 {
+    if (!context.collection.isTree) {
         return;
     }
 
-    reportExpansion(collection, last, onExpandedChange);
+    applyWanted(context.collection, 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.isTree && 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 };