@gtkx/components 2.0.0-beta.10 → 2.0.0-beta.11

package/src/internal/drop-down.tsx

@@ -1,12 +1,12 @@
 import type * as GObject from "@gtkx/gi/gobject";
 import type { ElementType, ReactNode, Ref } from "react";
 import { GtkLabel, GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
-import { useLatestRef } from "@gtkx/react/internal";
-import { omit } from "@gtkx/utils";
-import { useLayoutEffect, useRef, useState } from "react";
+import { omit, type Primitive } from "@gtkx/utils";
+import { useRef } from "react";
 import type { DropDownOwnProps, ListItemRenderArgs, ListItemRenderer } from "../types.js";
-import type { Collection } from "./collection.js";
 import { ItemPortals, useItemCells, useSectionHeader } from "./cells.js";
+import { type Collection, isCollectionIdle } from "./collection.js";
+import { useControlledSync } from "./controlled-sync.js";
 import { useCollectionData } from "./use-collection.js";
 import { useWidgetRef } from "./use-widget-ref.js";
 
@@ -24,17 +24,18 @@ type SelectionOptions = {
 };
 
 type NotifySelectedHandler = NonNullable<DropDownBaseProps["onNotifySelected"]>;
-type ApplyState = { isApplying: boolean };
+type ApplyState = { isApplying: boolean; isReady: boolean };
 
 type NotifyContext = {
     options: SelectionOptions;
     known: { current: string | null };
     state: ApplyState;
+    markDrift: () => void;
 };
 
 type KnownSelection = {
     known: { current: string | null };
-    onSelectionChanged: ((id: string) => void) | null | undefined;
+    onSelectionChanged: ((id: string | null) => void) | null | undefined;
 };
 
 const DROP_DOWN_PROPS: string[] = [
@@ -51,41 +52,31 @@ const DROP_DOWN_PROPS: string[] = [
 ];
 
 function newApplyState(): ApplyState {
-    return { isApplying: false };
+    return { isApplying: false, isReady: false };
 }
 
-const describeValue = (value: unknown): string => {
-    if (typeof value === "string") {
-        return value;
-    }
-
-    try {
-        return JSON.stringify(value);
-    } catch {
-        return String(value);
-    }
-};
-
-const defaultItemContent = (value: unknown): ReactNode =>
-    value == null ? null : <GtkLabel>{describeValue(value)}</GtkLabel>;
-
-const defaultRenderItem = ({ item }: ListItemRenderArgs<unknown>): ReactNode => defaultItemContent(item);
+const defaultRenderItem = ({ item }: ListItemRenderArgs<Primitive>): ReactNode =>
+    item == null ? null : <GtkLabel>{String(item)}</GtkLabel>;
 const faceRenderer = (props: DropDownBaseProps): ListItemRenderer<never> => props.renderItem ?? defaultRenderItem;
 
 const resolvePosition = (
     widget: SelectableWidget,
     collection: Collection,
-    selectedId: string | null | undefined,
+    selectedId: string | undefined,
 ): number => {
-    const requested = selectedId == null ? -1 : collection.positionFor(selectedId);
+    if (selectedId === undefined) {
+        return widget.getSelected();
+    }
+
+    const requested = collection.positionFor(selectedId);
 
     return requested >= 0 ? requested : widget.getSelected();
 };
 
 const updateKnownSelection = (
     tracker: KnownSelection,
-    effectiveId: string,
-    selectedId: string | null | undefined,
+    effectiveId: string | null,
+    selectedId: string | undefined,
 ): void => {
     const { known, onSelectionChanged } = tracker;
     const expectedId = selectedId ?? known.current;
@@ -100,7 +91,7 @@ const updateKnownSelection = (
 const reportKnownSelection = (tracker: KnownSelection, id: string | null): void => {
     const { known, onSelectionChanged } = tracker;
 
-    if (id === null || id === known.current) {
+    if (id === known.current) {
         return;
     }
 
@@ -108,14 +99,18 @@ const reportKnownSelection = (tracker: KnownSelection, id: string | null): void
     onSelectionChanged?.(id);
 };
 
-const reportSelectedNotify = (options: SelectionOptions, tracker: KnownSelection): void => {
-    const { widget, collection } = options;
-
-    if (widget === null) {
-        return;
+const hasSelectionDrifted = (
+    widget: SelectableWidget,
+    collection: Collection,
+    selectedId: string | undefined,
+): boolean => {
+    if (selectedId === undefined) {
+        return false;
     }
 
-    reportKnownSelection(tracker, collection.idAt(widget.getSelected()));
+    const requested = collection.positionFor(selectedId);
+
+    return requested >= 0 && widget.getSelected() !== requested;
 };
 
 const applySelectedPosition = (widget: SelectableWidget, position: number, state: ApplyState): void => {
@@ -129,49 +124,58 @@ const applySelectedPosition = (widget: SelectableWidget, position: number, state
 };
 
 const dispatchSelectedNotify = (context: NotifyContext, value: number | null, self: SelectableWidget): void => {
-    const { options, known, state } = context;
+    const { options, known, state, markDrift } = context;
 
     if (state.isApplying) {
         return;
     }
 
-    reportSelectedNotify(options, { known, onSelectionChanged: options.props.onSelectionChanged });
     options.props.onNotifySelected?.(value, self);
+
+    if (!state.isReady || !isCollectionIdle(options.collection)) {
+        return;
+    }
+
+    reportKnownSelection(
+        { known, onSelectionChanged: options.props.onSelectionChanged },
+        options.collection.idAt(self.getSelected()),
+    );
+
+    if (hasSelectionDrifted(self, options.collection, options.props.selectedId)) {
+        markDrift();
+    }
 };
 
 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 applyState = useRef<ApplyState>(newApplyState());
 
-    const syncKnownSelection = (position: number): void => {
+    const syncKnownSelection = (position: number, requestedId: string | undefined): void => {
         const effectiveId = collection.idAt(position);
-
-        if (effectiveId === null) {
-            known.current = null;
-
-            return;
-        }
-
         const { onSelectionChanged } = options.props;
-        updateKnownSelection({ known, onSelectionChanged }, effectiveId, selectedId);
+        updateKnownSelection({ known, onSelectionChanged }, effectiveId, requestedId);
+        applyState.current.isReady = true;
     };
 
-    const syncRef = useLatestRef(syncKnownSelection);
-
-    useLayoutEffect(() => {
-        if (widget === null) {
-            return;
-        }
-
-        const position = resolvePosition(widget, collection, selectedId);
-        applySelectedPosition(widget, position, applyState);
-        syncRef.current(position);
-    }, [syncRef, widget, collection, selectedId, applyState]);
+    const markDrift = useControlledSync({
+        value: selectedId,
+        source: collection,
+        target: widget,
+        apply: (value) => {
+            if (widget === null) {
+                return;
+            }
+
+            const position = resolvePosition(widget, collection, value);
+            applySelectedPosition(widget, position, applyState.current);
+            syncKnownSelection(position, value);
+        },
+    });
 
     return (value, self) => {
-        dispatchSelectedNotify({ options, known, state: applyState }, value, self);
+        dispatchSelectedNotify({ options, known, state: applyState.current, markDrift }, value, self);
     };
 };
 
@@ -179,7 +183,7 @@ 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, isFlat: true });
+    const { collection, model } = useCollectionData({ items, sections, isFlat: true });
     const faceCells = useItemCells({ width: -1, height: -1 });
     const listCells = useItemCells({ width: -1, height: -1 });
     const header = useSectionHeader(renderHeader, collection, { width: -1, height: -1 });
@@ -189,7 +193,7 @@ function DropDownBase(props: DropDownBaseProps & { component: ElementType }): Re
         <>
             <Component
                 ref={refCallback}
-                model={collection.model}
+                model={model}
                 factory={<GtkSignalListItemFactory {...faceCells.handlers} />}
                 {...(renderListItem != null && {
                     listFactory: <GtkSignalListItemFactory {...listCells.handlers} />,

package/src/internal/expansion.ts

@@ -124,10 +124,10 @@ function useExpansion(options: ExpansionOptions): ItemsChangeHandler {
     const context: ExpansionContext = { collection, last, onExpandedChange };
 
     const markDrift = useControlledSync({
-        ids: expandedIds,
-        collection,
-        apply: (ids) => {
-            applyControlledExpansion(context, ids);
+        value: expandedIds,
+        source: collection,
+        apply: (value) => {
+            applyControlledExpansion(context, value);
         },
     });
 

package/src/internal/selection.tsx

@@ -1,4 +1,3 @@
-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";
@@ -12,6 +11,7 @@ import { joinParts } from "./keys.js";
 
 type SelectionOptions = {
     collection: Collection;
+    model: ReactElement;
     selectedIds?: string[] | null | undefined;
     onSelectionChanged?: ((ids: string[]) => void) | null | undefined;
     selectionMode?: Gtk.SelectionMode | null | undefined;
@@ -42,7 +42,7 @@ type PositionRun = {
 
 type SelectionElementProps = {
     ref: (value: Gtk.SelectionModel | null) => void;
-    model: Gio.ListModel;
+    model: ReactElement;
     onSelectionChanged: () => void;
     onItemsChanged: ItemsChangeHandler;
 };
@@ -257,17 +257,17 @@ function useSelection(options: SelectionOptions): ReactElement {
     const context: SelectionContext = { selection, collection, last, state, onSelectionChanged };
 
     const markDrift = useControlledSync({
-        ids: selectedIds,
-        collection,
-        widget: selection,
-        apply: (ids) => {
-            applyControlledSelection(context, ids);
+        value: selectedIds,
+        source: collection,
+        target: selection,
+        apply: (value) => {
+            applyControlledSelection(context, value);
         },
     });
 
     return selectionElement(selectionMode, {
         ref: setSelection,
-        model: collection.model,
+        model: options.model,
         onSelectionChanged: () => {
             observeSelection(context, selectedIds, markDrift);
         },

package/src/internal/tree-expansion.ts

@@ -14,7 +14,7 @@ type TreeExpansion = {
     isSyncing: boolean;
 };
 
-function dropLevel(expansion: TreeExpansion, path: string, pending: string[]): void {
+function dropSubtree(expansion: TreeExpansion, path: string): void {
     expansion.expanded.delete(path);
     const level = expansion.slots.get(path);
 
@@ -25,19 +25,7 @@ function dropLevel(expansion: TreeExpansion, path: string, pending: string[]): v
     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);
-        }
+        dropSubtree(expansion, path + encodePart(String(slot)));
     }
 }
 

package/src/internal/tree-order.ts

@@ -28,133 +28,56 @@ type WalkOptions = {
     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;
+    position: number;
     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 walkLevel(options: WalkOptions, level: Level, state: WalkState): void {
+    const open = options.slots.get(level.path);
+    const marked = options.marks?.get(level.path);
 
-function descend(state: WalkState, level: Level, slot: number): void {
-    const child = state.options.index.childLevel(level, slot);
+    for (const [slot, item] of level.items.entries()) {
+        const isOpen = open?.has(slot) ?? false;
+        options.visit?.({ item, position: state.position, isOpen, isMarked: marked?.has(slot) ?? false });
+        state.position += 1;
 
-    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));
-}
+        if (!isOpen) {
+            continue;
+        }
 
-function visitSlot(state: WalkState, frame: WalkFrame, slot: number): void {
-    const item = frame.level.items[slot];
+        const child = options.index.childLevel(level, 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);
+        if (child !== undefined) {
+            state.order.expandedPaths.push(child.path);
+            state.order.expandedIds.push(item.id);
+            walkLevel(options, child, state);
+        }
     }
 }
 
 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);
-    };
+    const state: WalkState = { position: 0, order: { expandedPaths: [], expandedIds: [] } };
 
-    while (state.stack.length > 0) {
-        advanceStack(state.stack, onSlot);
+    for (const level of options.index.groups) {
+        walkLevel(options, level, state);
     }
 
-    return order;
+    return state.order;
 }
 
-function openSlot(walk: OpenWalk, frame: OpenFrame, slot: number): void {
-    const item = frame.level.items[slot];
+function expandLevel(index: CollectionIndex, level: Level, ids: Set<string>, paths: Set<string>): void {
+    for (const [slot, item] of level.items.entries()) {
+        if (!ids.has(item.id)) {
+            continue;
+        }
 
-    if (item === undefined || !walk.ids.has(item.id) || walk.ancestors.has(item)) {
-        return;
-    }
-
-    const child = walk.index.childLevel(frame.level, slot);
+        const child = index.childLevel(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);
+        if (child !== undefined) {
+            paths.add(child.path);
+            expandLevel(index, child, ids, paths);
+        }
     }
 }
 
@@ -165,19 +88,8 @@ function expandedPathsFor(index: CollectionIndex, ids: Set<string>): Set<string>
         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);
+    for (const level of index.groups) {
+        expandLevel(index, level, ids, paths);
     }
 
     return paths;

package/src/internal/use-collection.tsx

@@ -1,9 +1,11 @@
+import type * as Gtk from "@gtkx/gi/gtk";
 import type { ReactElement } from "react";
+import { GtkFlattenListModel } from "@gtkx/jsx/gtk";
 import { useLayoutEffect, useMemo, useState } from "react";
 import type { ExpansionProps, ListItem, ListSection, SelectionProps } from "../types.js";
 import type { Collection } from "./collection.js";
 import { createCollectionIndex } from "./collection-index.js";
-import { createCollectionModel } from "./collection-model.js";
+import { CollectionRoot, type CollectionRootStore, createCollectionModel } from "./collection-model.js";
 import { createCollection } from "./collection.js";
 import { useExpansion } from "./expansion.js";
 import { useSelection } from "./selection.js";
@@ -21,21 +23,39 @@ type CollectionResult = {
     selection: ReactElement;
 };
 
-function useCollectionData(options: CollectionDataOptions): Collection {
+type CollectionDataResult = {
+    collection: Collection;
+    model: ReactElement;
+};
+
+function useCollectionData(options: CollectionDataOptions): CollectionDataResult {
     const { items, sections, isFlat } = options;
-    const [collectionModel] = useState(createCollectionModel);
+    const [gtkModel] = useState(createCollectionModel);
+    const [root, setRoot] = useState<CollectionRootStore | null>(null);
+    const [model, setModel] = useState<Gtk.FlattenListModel | null>(null);
     const index = useMemo(() => createCollectionIndex(items, sections, isFlat === true), [items, sections, isFlat]);
-    const collection = useMemo(() => createCollection(collectionModel, index), [collectionModel, index]);
+    const collection = useMemo(() => createCollection(gtkModel, index, model), [gtkModel, index, model]);
 
     useLayoutEffect(() => {
-        collectionModel.sync(index);
-    }, [collectionModel, index]);
+        if (root !== null && model !== null) {
+            gtkModel.bind(root, model);
+        }
+
+        return gtkModel.clear;
+    }, [gtkModel, root, model]);
 
-    return collection;
+    useLayoutEffect(() => {
+        gtkModel.sync(index);
+    }, [gtkModel, index, root, model]);
+
+    return {
+        collection,
+        model: <GtkFlattenListModel ref={setModel} model={<CollectionRoot ref={setRoot} />} />,
+    };
 }
 
 function useCollection(options: CollectionOptions): CollectionResult {
-    const collection = useCollectionData(options);
+    const { collection, model } = useCollectionData(options);
 
     const onItemsChanged = useExpansion({
         collection,
@@ -45,6 +65,7 @@ function useCollection(options: CollectionOptions): CollectionResult {
 
     const selection = useSelection({
         collection,
+        model,
         selectedIds: options.selectedIds,
         onSelectionChanged: options.onSelectionChanged,
         selectionMode: options.selectionMode,

package/src/list-item-factory.tsx

@@ -0,0 +1,27 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import type { ReactNode } from "react";
+import { GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
+import type { ListItemFactoryProps } from "./types.js";
+import { NativeItemPortals, useItemCells } from "./internal/cells.js";
+
+/**
+ * Creates a Gtk.SignalListItemFactory that renders objects from an existing native model with React.
+ * Estimated dimensions keep cells stable until their content mounts.
+ */
+function ListItemFactory<T extends GObject.Object>({
+    renderItem,
+    estimatedItemHeight = -1,
+    estimatedItemWidth = -1,
+}: ListItemFactoryProps<T>): ReactNode {
+    const size = { width: estimatedItemWidth, height: estimatedItemHeight };
+    const cells = useItemCells(size);
+
+    return (
+        <>
+            <GtkSignalListItemFactory {...cells.handlers} />
+            <NativeItemPortals registry={cells} render={renderItem} size={size} />
+        </>
+    );
+}
+
+export { ListItemFactory };

package/src/toast.tsx

@@ -1,7 +1,7 @@
 import type { ReactNode, RefObject } from "react";
 import * as Adw from "@gtkx/gi/adw";
 import { createContext, useContext, useMemo } from "react";
-import type { ToastController, ToastOptions, ToastOverlayController, ToastProviderProps } from "./types.js";
+import type { ToastController, ToastOptions, ToastProviderProps } from "./types.js";
 
 type OverlayRef = RefObject<Adw.ToastOverlay | null>;
 
@@ -11,7 +11,7 @@ const useOverlayRef = (): OverlayRef => {
     const overlayRef = useContext(ToastContext);
 
     if (overlayRef === null) {
-        throw new Error("useToast and useToastOverlay must be used within a ToastProvider");
+        throw new Error("useToast must be used within a ToastProvider");
     }
 
     return overlayRef;
@@ -36,7 +36,7 @@ const buildToast = (options: ToastOptions): Adw.Toast => {
     return toast;
 };
 
-/** Shares an Adw.ToastOverlay reference with the toast hooks in every descendant. */
+/** Shares an Adw.ToastOverlay reference with useToast in every descendant. */
 function ToastProvider(props: ToastProviderProps): ReactNode {
     return <ToastContext.Provider value={props.overlayRef}>{props.children}</ToastContext.Provider>;
 }
@@ -53,20 +53,6 @@ function useToast(): ToastController {
 
                 return toast;
             },
-            dismiss: (toast: Adw.Toast) => {
-                toast.dismiss();
-            },
-        }),
-        [overlayRef],
-    );
-}
-
-/** Returns a {@link ToastOverlayController} for the nearest provider's overlay as a whole. */
-function useToastOverlay(): ToastOverlayController {
-    const overlayRef = useOverlayRef();
-
-    return useMemo<ToastOverlayController>(
-        () => ({
             dismissAll: () => {
                 overlayRef.current?.dismissAll();
             },
@@ -75,4 +61,4 @@ function useToastOverlay(): ToastOverlayController {
     );
 }
 
-export { ToastProvider, useToast, useToastOverlay };
+export { ToastProvider, useToast };