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

package/src/internal/collection-model.ts

@@ -0,0 +1,246 @@
+import * as Gio from "@gtkx/gi/gio";
+import * as GObject from "@gtkx/gi/gobject";
+import * as Gtk from "@gtkx/gi/gtk";
+import type { CollectionIndex, Level } from "./collection-index.js";
+import { childLevelKey, ROOT_LEVEL_KEY } from "./collection-index.js";
+
+type LevelState = {
+    store: Gio.ListStore;
+    ids: string[];
+    canExpand: Map<string, boolean>;
+};
+
+type SpliceRange = {
+    start: number;
+    removed: number;
+    added: string[];
+};
+
+type ModelState = {
+    root: Gio.ListStore;
+    rootModels: GObject.Object[];
+    model: Gtk.FlattenListModel;
+    objects: Map<string, Gtk.StringObject>;
+    levels: Map<string, LevelState>;
+    tree: Gtk.TreeListModel | null;
+};
+
+type CollectionModel = {
+    model: Gtk.FlattenListModel;
+    treeModel: () => Gtk.TreeListModel | null;
+    sync: (index: CollectionIndex) => void;
+};
+
+const OBJECT_CACHE_MAX = 1 << 20;
+
+const newStore = (): Gio.ListStore => new Gio.ListStore({ itemType: GObject.TYPE_OBJECT });
+
+function getId(value: GObject.Object | null): string | null {
+    const item = value instanceof Gtk.TreeListRow ? value.getItem() : value;
+
+    return item instanceof Gtk.StringObject ? item.getString() : null;
+}
+
+function objectFor(state: ModelState, id: string): Gtk.StringObject {
+    const existing = state.objects.get(id);
+
+    if (existing !== undefined) {
+        return existing;
+    }
+
+    const created = Gtk.StringObject.new(id);
+    state.objects.set(id, created);
+
+    return created;
+}
+
+function commonPrefix(previous: string[], next: string[], max: number): number {
+    let count = 0;
+
+    while (count < max && previous[count] === next[count]) {
+        count += 1;
+    }
+
+    return count;
+}
+
+function commonSuffix(previous: string[], next: string[], max: number): number {
+    let count = 0;
+
+    while (count < max && previous[previous.length - 1 - count] === next[next.length - 1 - count]) {
+        count += 1;
+    }
+
+    return count;
+}
+
+function spliceRange(previous: string[], next: string[]): SpliceRange | null {
+    const shared = Math.min(previous.length, next.length);
+    const start = commonPrefix(previous, next, shared);
+
+    if (start === previous.length && start === next.length) {
+        return null;
+    }
+
+    const tail = commonSuffix(previous, next, shared - start);
+
+    return { start, removed: previous.length - start - tail, added: next.slice(start, next.length - tail) };
+}
+
+function levelFor(state: ModelState, key: string): LevelState {
+    const existing = state.levels.get(key);
+
+    if (existing !== undefined) {
+        return existing;
+    }
+
+    const created: LevelState = { store: newStore(), ids: [], canExpand: new Map() };
+    state.levels.set(key, created);
+
+    return created;
+}
+
+function refreshExpandable(current: LevelState, level: Level): void {
+    const next: Map<string, boolean> = new Map();
+
+    for (const [index, id] of level.ids.entries()) {
+        const isWanted = level.isExpandable[index] ?? false;
+        const previous = current.canExpand.get(id);
+        next.set(id, isWanted);
+
+        if (previous !== undefined && previous !== isWanted) {
+            current.store.itemsChanged(index, 1, 1);
+        }
+    }
+
+    current.canExpand = next;
+}
+
+function didSpliceLevel(state: ModelState, level: Level): boolean {
+    const current = levelFor(state, level.key);
+    const range = spliceRange(current.ids, level.ids);
+
+    if (range === null) {
+        return false;
+    }
+
+    current.store.splice(range.start, range.removed, range.added.map((id) => objectFor(state, id)));
+    current.ids = [...level.ids];
+
+    return true;
+}
+
+function dropUnvisited(state: ModelState, visited: Set<string>): void {
+    for (const key of state.levels.keys()) {
+        if (!visited.has(key)) {
+            state.levels.delete(key);
+        }
+    }
+}
+
+// Items keep their identity by id, so a collection that shrinks keeps its objects cached: filtering a long
+// list down and back up reuses them instead of rebuilding one GObject per row. Incremental filters shrink and
+// grow the list many times per keystroke, so the cache is only swept once it passes an absolute bound.
+function pruneObjects(state: ModelState, index: CollectionIndex): void {
+    if (state.objects.size <= OBJECT_CACHE_MAX) {
+        return;
+    }
+
+    for (const id of state.objects.keys()) {
+        if (!index.has(id)) {
+            state.objects.delete(id);
+        }
+    }
+}
+
+function childStoreFor(state: ModelState, object: GObject.Object): Gio.ListStore | null {
+    const id = getId(object);
+
+    if (id === null) {
+        return null;
+    }
+
+    return state.levels.get(childLevelKey(id))?.store ?? null;
+}
+
+function ensureTree(state: ModelState): Gtk.TreeListModel {
+    state.tree ??= Gtk.TreeListModel.new(levelFor(state, ROOT_LEVEL_KEY).store, false, false, (object) =>
+        childStoreFor(state, object));
+
+    return state.tree;
+}
+
+function desiredRootModels(state: ModelState, index: CollectionIndex): GObject.Object[] {
+    if (index.isTree) {
+        return [ensureTree(state)];
+    }
+
+    return index.groups.map((level) => levelFor(state, level.key).store);
+}
+
+function hasSameModels(previous: GObject.Object[], next: GObject.Object[]): boolean {
+    return previous.length === next.length && next.every((model, index) => previous[index] === model);
+}
+
+function syncRoot(state: ModelState, index: CollectionIndex): void {
+    const next = desiredRootModels(state, index);
+
+    if (hasSameModels(state.rootModels, next)) {
+        return;
+    }
+
+    state.root.splice(0, state.rootModels.length, next);
+    state.rootModels = next;
+}
+
+function syncModel(state: ModelState, index: CollectionIndex): void {
+    const levels = [...index.groups, ...index.children.values()];
+    const visited: Set<string> = new Set();
+    let didChange = false;
+
+    for (const level of levels) {
+        didChange = didSpliceLevel(state, level) || didChange;
+        visited.add(level.key);
+    }
+
+    if (didChange || visited.size !== state.levels.size) {
+        dropUnvisited(state, visited);
+        pruneObjects(state, index);
+    }
+
+    syncRoot(state, index);
+    refreshExpandableLevels(state, index, levels);
+}
+
+function refreshExpandableLevels(state: ModelState, index: CollectionIndex, levels: Level[]): void {
+    if (!index.isTree) {
+        return;
+    }
+
+    for (const level of levels) {
+        refreshExpandable(levelFor(state, level.key), level);
+    }
+}
+
+function createCollectionModel(): CollectionModel {
+    const root = newStore();
+
+    const state: ModelState = {
+        root,
+        rootModels: [],
+        model: Gtk.FlattenListModel.new(root),
+        objects: new Map(),
+        levels: new Map(),
+        tree: null,
+    };
+
+    return {
+        model: state.model,
+        treeModel: () => state.tree,
+        sync: (index) => {
+            syncModel(state, index);
+        },
+    };
+}
+
+export { createCollectionModel, getId, type CollectionModel };

package/src/internal/collection.ts

@@ -0,0 +1,104 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { Item } from "../types.js";
+import type { CollectionIndex } from "./collection-index.js";
+import type { CollectionModel } from "./collection-model.js";
+import { getId } from "./collection-model.js";
+
+type Collection = {
+    isTree: boolean;
+    model: Gtk.FlattenListModel;
+    treeModel: () => Gtk.TreeListModel | null;
+    itemFor: (id: string) => Item | undefined;
+    sectionFor: (id: string) => unknown;
+    idAt: (position: number) => string | null;
+    positionFor: (id: string) => number;
+    positionsFor: (ids: string[]) => number[];
+};
+
+const ascending = (a: number, b: number): number => a - b;
+
+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;
+    }
+
+    visit(row, getId(row.getItem()));
+}
+
+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);
+    }
+}
+
+function collectWanted(item: GObject.Object | null, position: number, wanted: Set<string>, out: number[]): void {
+    const id = getId(item);
+
+    if (id !== null && wanted.has(id)) {
+        out.push(position);
+    }
+}
+
+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);
+    }
+
+    return positions;
+}
+
+function indexPositions(index: CollectionIndex, ids: string[]): number[] {
+    const positions: number[] = [];
+
+    for (const id of ids) {
+        const position = index.positionFor(id);
+
+        if (position >= 0) {
+            positions.push(position);
+        }
+    }
+
+    return positions.toSorted(ascending);
+}
+
+function positionsFor(gtk: CollectionModel, index: CollectionIndex, ids: string[]): number[] {
+    if (!index.isTree) {
+        return indexPositions(index, ids);
+    }
+
+    const tree = gtk.treeModel();
+
+    return tree === null ? [] : scanPositions(tree, ids);
+}
+
+function positionFor(gtk: CollectionModel, index: CollectionIndex, id: string): number {
+    const [first = -1] = positionsFor(gtk, index, [id]);
+
+    return first;
+}
+
+function createCollection(gtk: CollectionModel, index: CollectionIndex): Collection {
+    return {
+        isTree: index.isTree,
+        model: gtk.model,
+        treeModel: () => (index.isTree ? gtk.treeModel() : null),
+        itemFor: index.itemFor,
+        sectionFor: index.sectionFor,
+        idAt: (position) => getId(gtk.model.getItem(position)),
+        positionFor: (id) => positionFor(gtk, index, id),
+        positionsFor: (ids) => positionsFor(gtk, index, ids),
+    };
+}
+
+export { createCollection, eachRow, type Collection };

package/src/internal/drop-down.tsx

@@ -0,0 +1,186 @@
+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 type { DropDownOwnProps, ItemRenderer, RenderItemArgs } from "../types.js";
+import type { Collection } from "./collection.js";
+import { HeaderPortals, ItemPortals, useHeaderCells, useItemCells } from "./cells.js";
+import { useCollectionData } from "./use-collection.js";
+import { useWidgetRef } from "./use-widget-ref.js";
+
+type SelectableWidget = GObject.Object & { getSelected: () => number; selected: number };
+
+type DropDownBaseProps = DropDownOwnProps<unknown, unknown> & {
+    onNotifySelected?: ((value: number | null, self: SelectableWidget) => void) | null | undefined;
+    ref?: Ref<SelectableWidget | null> | undefined;
+} & Record<string, unknown>;
+
+type SelectionOptions = {
+    widget: SelectableWidget | null;
+    collection: Collection;
+    props: DropDownBaseProps;
+};
+
+type NotifySelectedHandler = NonNullable<DropDownBaseProps["onNotifySelected"]>;
+
+type KnownSelection = {
+    known: { current: string | null };
+    onSelectionChanged: ((id: string) => void) | null | undefined;
+};
+
+const DROP_DOWN_PROPS: string[] = [
+    "component",
+    "items",
+    "sections",
+    "selectedId",
+    "onSelectionChanged",
+    "onNotifySelected",
+    "renderItem",
+    "renderListItem",
+    "renderHeader",
+    "ref",
+];
+
+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 }: RenderItemArgs<unknown>): ReactNode => defaultItemContent(item);
+const faceRenderer = (props: DropDownBaseProps): ItemRenderer<never> => props.renderItem ?? defaultRenderItem;
+
+const listRenderer = (props: DropDownBaseProps): ItemRenderer<never> =>
+    props.renderListItem ?? props.renderItem ?? defaultRenderItem;
+
+const resolvePosition = (
+    widget: SelectableWidget,
+    collection: Collection,
+    selectedId: string | null | undefined,
+): number => {
+    const requested = selectedId == null ? -1 : collection.positionFor(selectedId);
+
+    return requested >= 0 ? requested : widget.getSelected();
+};
+
+const updateKnownSelection = (
+    tracker: KnownSelection,
+    effectiveId: string,
+    selectedId: string | null | undefined,
+): void => {
+    const { known, onSelectionChanged } = tracker;
+    const expectedId = selectedId ?? known.current;
+    const isNew = effectiveId !== known.current;
+    known.current = effectiveId;
+
+    if (expectedId !== null && effectiveId !== expectedId && isNew) {
+        onSelectionChanged?.(effectiveId);
+    }
+};
+
+const reportKnownSelection = (tracker: KnownSelection, id: string | null): void => {
+    const { known, onSelectionChanged } = tracker;
+
+    if (id === null || id === known.current) {
+        return;
+    }
+
+    known.current = id;
+    onSelectionChanged?.(id);
+};
+
+const reportSelectedNotify = (options: SelectionOptions, tracker: KnownSelection): void => {
+    const { widget, collection } = options;
+
+    if (widget === null) {
+        return;
+    }
+
+    reportKnownSelection(tracker, collection.idAt(widget.getSelected()));
+};
+
+const applySelectedPosition = (widget: SelectableWidget, position: number): void => {
+    applyWrite(() => {
+        widget.selected = position;
+    });
+};
+
+const useDropDownSelection = (options: SelectionOptions): NotifySelectedHandler => {
+    const { widget, collection } = options;
+    const { selectedId } = options.props;
+    const known = useRef<string | null>(null);
+
+    const syncKnownSelection = useEffectEvent((position: number): void => {
+        const effectiveId = collection.idAt(position);
+
+        if (effectiveId === null) {
+            known.current = null;
+
+            return;
+        }
+
+        const { onSelectionChanged } = options.props;
+        updateKnownSelection({ known, onSelectionChanged }, effectiveId, selectedId);
+    });
+
+    useLayoutEffect(() => {
+        if (widget === null) {
+            return;
+        }
+
+        const position = resolvePosition(widget, collection, selectedId);
+        applySelectedPosition(widget, position);
+        syncKnownSelection(position);
+    }, [widget, collection, selectedId]);
+
+    return (value, self) => {
+        reportSelectedNotify(options, { known, onSelectionChanged: options.props.onSelectionChanged });
+        options.props.onNotifySelected?.(value, self);
+    };
+};
+
+function DropDownBase(props: DropDownBaseProps & { component: ElementType }): ReactNode {
+    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 faceCells = useItemCells({ width: -1, height: -1 });
+    const listCells = useItemCells({ width: -1, height: -1 });
+    const headerCells = useHeaderCells({ width: -1, height: -1 });
+    const handleNotifySelected = useDropDownSelection({ widget, collection, props });
+    const hasHeader = typeof renderHeader === "function";
+
+    return (
+        <>
+            <Component
+                ref={refCallback}
+                model={collection.model}
+                factory={<GtkSignalListItemFactory {...faceCells.handlers} />}
+                {...(renderListItem != null && {
+                    listFactory: <GtkSignalListItemFactory {...listCells.handlers} />,
+                })}
+                {...(hasHeader && { headerFactory: <GtkSignalListItemFactory {...headerCells.handlers} /> })}
+                {...rest}
+                onNotifySelected={handleNotifySelected}
+            />
+            <ItemPortals store={faceCells} render={faceRenderer(props)} collection={collection} />
+            {renderListItem != null && (
+                <ItemPortals store={listCells} render={listRenderer(props)} collection={collection} />
+            )}
+            {hasHeader && <HeaderPortals store={headerCells} render={renderHeader} collection={collection} />}
+        </>
+    );
+}
+
+export { DropDownBase, type DropDownBaseProps };

package/src/internal/expansion.ts

@@ -0,0 +1,122 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { RefObject } from "react";
+import { useEffectEvent, useLayoutEffect, useRef, useState } from "react";
+import type { Collection } from "./collection.js";
+import { eachRow } from "./collection.js";
+
+type ExpansionOptions = {
+    collection: Collection;
+    expandedIds?: string[] | null | undefined;
+    onExpandedChange?: ((ids: string[]) => void) | null | undefined;
+};
+
+type LastExpansion = { key: string };
+
+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 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 applyExpansion(tree: Gtk.TreeListModel, expandedIds: string[]): void {
+    const wanted = new Set(expandedIds);
+
+    eachRow(tree, (row, id) => {
+        expandRow(row, id, wanted);
+    });
+}
+
+function reportExpansion(
+    collection: Collection,
+    last: LastExpansion,
+    onExpandedChange: ((ids: string[]) => void) | null | undefined,
+): void {
+    const tree = collection.treeModel();
+
+    if (tree === null) {
+        return;
+    }
+
+    const ids: string[] = [];
+
+    eachRow(tree, (row, id) => {
+        collectExpanded(row, id, ids);
+    });
+
+    const key = ids.join(" ");
+
+    if (last.key === key) {
+        return;
+    }
+
+    last.key = key;
+    onExpandedChange?.(ids);
+}
+
+function reportWhenIdle(
+    collection: Collection,
+    last: LastExpansion,
+    expanding: RefObject<boolean>,
+    onExpandedChange: ((ids: string[]) => void) | null | undefined,
+): void {
+    if (expanding.current) {
+        return;
+    }
+
+    reportExpansion(collection, last, onExpandedChange);
+}
+
+function runControlledExpansion(
+    collection: Collection,
+    expandedIds: string[] | null | undefined,
+    expanding: RefObject<boolean>,
+    report: () => void,
+): void {
+    const tree = collection.treeModel();
+
+    if (tree === null || expandedIds == null) {
+        return;
+    }
+
+    expanding.current = true;
+
+    try {
+        applyExpansion(tree, expandedIds);
+    } finally {
+        expanding.current = false;
+    }
+
+    report();
+}
+
+function useExpansion(options: ExpansionOptions): () => void {
+    const { collection, expandedIds, onExpandedChange } = options;
+    const [last] = useState<LastExpansion>(newLastExpansion);
+    const expanding = useRef(false);
+
+    const report = useEffectEvent((): void => {
+        reportWhenIdle(collection, last, expanding, onExpandedChange);
+    });
+
+    useLayoutEffect(() => {
+        runControlledExpansion(collection, expandedIds, expanding, report);
+    }, [collection, expandedIds]);
+
+    return () => {
+        reportWhenIdle(collection, last, expanding, onExpandedChange);
+    };
+}
+
+export { useExpansion, type ExpansionOptions };