@gtkx/components 0.21.0 → 1.0.0-rc.2

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/expansion.ts

@@ -0,0 +1,123 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import type { RefObject } from "react";
+import { useSignal } from "@gtkx/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);
+    });
+
+    useSignal(collection.isTree ? collection.model : null, "items-changed", () => {
+        reportWhenIdle(collection, last, expanding, onExpandedChange);
+    });
+
+    useLayoutEffect(() => {
+        runControlledExpansion(collection, expandedIds, expanding, report);
+    }, [collection, expandedIds]);
+}
+
+export { useExpansion, type ExpansionOptions };

package/src/internal/selection.tsx

@@ -0,0 +1,159 @@
+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 type { Collection } from "./collection.js";
+
+type SelectionOptions = {
+    collection: Collection;
+    selectedIds?: string[] | null | undefined;
+    onSelectionChanged?: ((ids: string[]) => void) | null | undefined;
+    selectionMode?: Gtk.SelectionMode | null | undefined;
+};
+
+type LastSelection = {
+    selection: Gtk.SelectionModel | null;
+    key: string | null;
+};
+
+type SelectionElementProps = {
+    ref: (value: Gtk.SelectionModel | null) => void;
+    model: Gio.ListModel;
+    onSelectionChanged: () => void;
+};
+
+function getSelectedIds(selection: Gtk.SelectionModel, collection: Collection): string[] {
+    const bitset = selection.getSelection();
+    const size = Number(bitset.getSize());
+    const ids: string[] = [];
+
+    for (let index = 0; index < size; index++) {
+        pushId(collection.idAt(bitset.getNth(index)), ids);
+    }
+
+    return ids;
+}
+
+function pushId(id: string | null, ids: string[]): void {
+    if (id !== null) {
+        ids.push(id);
+    }
+}
+
+function applySingleSelection(selection: Gtk.SingleSelection, positions: number[]): void {
+    const [first] = positions;
+
+    if (first === undefined) {
+        selection.unselectAll();
+
+        return;
+    }
+
+    selection.selectItem(first, true);
+}
+
+function applyMultiSelection(selection: Gtk.SelectionModel, positions: number[]): void {
+    const selected = Gtk.Bitset.newEmpty();
+
+    for (const position of positions) {
+        selected.add(position);
+    }
+
+    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;
+    }
+
+    if (selection instanceof Gtk.SingleSelection) {
+        applySingleSelection(selection, positions);
+
+        return;
+    }
+
+    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(" ");
+
+    if (last.selection === selection && last.key === key) {
+        return;
+    }
+
+    last.selection = selection;
+    last.key = key;
+    onSelectionChanged?.(ids);
+}
+
+function selectionElement(mode: Gtk.SelectionMode | null | undefined, props: SelectionElementProps): ReactElement {
+    if (mode === Gtk.SelectionMode.MULTIPLE) {
+        return <GtkMultiSelection {...props} />;
+    }
+
+    if (mode === Gtk.SelectionMode.NONE) {
+        return <GtkNoSelection {...props} />;
+    }
+
+    return <GtkSingleSelection {...props} autoselect={false} canUnselect />;
+}
+
+function syncSelection(
+    selection: Gtk.SelectionModel | null,
+    collection: Collection,
+    selectedIds: string[] | null | undefined,
+): void {
+    if (selection === null || selectedIds == null) {
+        return;
+    }
+
+    applySelection(selection, collection, selectedIds);
+}
+
+function newLastSelection(): LastSelection {
+    return { selection: null, key: null };
+}
+
+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);
+    });
+
+    useLayoutEffect(() => {
+        syncSelection(selection, collection, selectedIds);
+        report();
+    }, [selection, collection, selectedIds]);
+
+    return selectionElement(selectionMode, {
+        ref: setSelection,
+        model: collection.model,
+        onSelectionChanged: () => {
+            reportSelection(selection, collection, last, onSelectionChanged);
+        },
+    });
+}
+
+export { useSelection, type SelectionOptions };

package/src/internal/use-collection.tsx

@@ -0,0 +1,70 @@
+import type { ReactElement, RefObject } from "react";
+import { useLayoutEffect, useMemo, useState } from "react";
+import type { ExpansionProps, Item, Section, SelectionProps } from "../types.js";
+import type { CollectionIndex } from "./collection-index.js";
+import type { CollectionModel } from "./collection-model.js";
+import type { Collection } from "./collection.js";
+import { createCollectionIndex } from "./collection-index.js";
+import { createCollectionModel } from "./collection-model.js";
+import { createCollection } from "./collection.js";
+import { useExpansion } from "./expansion.js";
+import { useSelection } from "./selection.js";
+
+type CollectionDataOptions = {
+    items?: Item[] | undefined;
+    sections?: Section[] | undefined;
+    flat?: boolean | undefined;
+    applying?: RefObject<boolean> | undefined;
+};
+
+type CollectionOptions = CollectionDataOptions & SelectionProps & ExpansionProps;
+
+type CollectionResult = {
+    collection: Collection;
+    selection: ReactElement;
+};
+
+function runSync(gtk: CollectionModel, index: CollectionIndex, applying: RefObject<boolean> | undefined): void {
+    if (applying === undefined) {
+        gtk.sync(index);
+
+        return;
+    }
+
+    applying.current = true;
+
+    try {
+        gtk.sync(index);
+    } finally {
+        applying.current = false;
+    }
+}
+
+function useCollectionData(options: CollectionDataOptions): Collection {
+    const { items, sections, flat, applying } = options;
+    const [gtk] = useState(createCollectionModel);
+    const index = useMemo(() => createCollectionIndex(items, sections, flat === true), [items, sections, flat]);
+    const collection = useMemo(() => createCollection(gtk, index), [gtk, index]);
+
+    useLayoutEffect(() => {
+        runSync(gtk, index, applying);
+    }, [gtk, index, applying]);
+
+    return collection;
+}
+
+function useCollection(options: CollectionOptions): CollectionResult {
+    const collection = useCollectionData(options);
+    useExpansion({ collection, expandedIds: options.expandedIds, onExpandedChange: options.onExpandedChange });
+
+    const selection = useSelection({
+        collection,
+        selectedIds: options.selectedIds,
+        onSelectionChanged: options.onSelectionChanged,
+        selectionMode: options.selectionMode,
+    });
+
+    return { collection, selection };
+}
+
+export { useCollection, useCollectionData, type CollectionDataOptions, type CollectionOptions };

package/src/internal/use-widget-ref.ts

@@ -0,0 +1,11 @@
+import type { Ref, RefCallback } from "react";
+import { useMergedRef } from "@gtkx/react/internal";
+import { useState } from "react";
+
+const useWidgetRef = <T>(external: Ref<T | null> | null | undefined): [T | null, RefCallback<T | null>] => {
+    const [widget, setWidget] = useState<T | null>(null);
+
+    return [widget, useMergedRef<T | null>(external, setWidget)];
+};
+
+export { useWidgetRef };