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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gtkx/components",
-  "version": "2.0.0-beta.10",
-  "description": "Adwaita and GTK collection views, dropdowns, combo rows, and toasts.",
+  "version": "2.0.0-beta.11",
+  "description": "Collection views, selection controls, and toasts for GTKX.",
   "keywords": [
     "gtkx",
     "gtk",
@@ -53,18 +53,20 @@
     "node": ">=26.7.0"
   },
   "dependencies": {
-    "@gtkx/react": "2.0.0-beta.10",
-    "@gtkx/runtime": "2.0.0-beta.10",
-    "@gtkx/utils": "2.0.0-beta.10"
+    "@gtkx/react": "2.0.0-beta.11",
+    "@gtkx/runtime": "2.0.0-beta.11",
+    "@gtkx/utils": "2.0.0-beta.11"
   },
   "peerDependencies": {
-    "react": "^19.2"
+    "@types/react": "^19.3",
+    "react": "^19.3"
   },
   "devDependencies": {
-    "@gtkx/config": "2.0.0-beta.10",
-    "@gtkx/testing": "2.0.0-beta.10",
-    "@gtkx/vitest": "2.0.0-beta.10",
-    "vitest": "^5.0.0"
+    "@gtkx/config": "2.0.0-beta.11",
+    "@gtkx/testing": "2.0.0-beta.11",
+    "@gtkx/vitest": "2.0.0-beta.11",
+    "@types/react": "^19.3.0",
+    "vitest": "^5.0.1"
   },
   "scripts": {
     "release": "tsx ../../scripts/release-package.ts"

package/src/column-view.tsx

@@ -3,15 +3,17 @@ import * as Gtk from "@gtkx/gi/gtk";
 import { GtkColumnView, GtkColumnViewColumn, GtkCustomSorter, GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
 import { useSignal } from "@gtkx/react";
 import { omit } from "@gtkx/utils";
-import { useLayoutEffect, useRef } from "react";
+import { useMemo, useRef } from "react";
 import type { CellSize } from "./internal/cells.js";
 import type { Collection } from "./internal/collection.js";
 import type { ColumnViewColumn, ColumnViewProps, ExpanderDescriptions, SortProps } from "./types.js";
 import { ItemPortals, useItemCells, useRowProps, useSectionHeader } from "./internal/cells.js";
+import { useControlledSync } from "./internal/controlled-sync.js";
 import { useCollection } from "./internal/use-collection.js";
 import { useWidgetRef } from "./internal/use-widget-ref.js";
 
 type SortTarget = { view: Gtk.ColumnView; column: Gtk.ColumnViewColumn | null };
+type SortRequest = Pick<SortProps, "sortColumn" | "sortOrder">;
 
 type ColumnCellsProps = {
     column: ColumnViewColumn<never>;
@@ -43,7 +45,6 @@ const COLUMN_VIEW_PROPS = [
     "sortOrder",
     "onSortChanged",
     "estimatedItemHeight",
-    "children",
     "ref",
 ] as const satisfies (keyof ColumnViewProps)[];
 
@@ -93,16 +94,18 @@ const applySort = (
     }
 };
 
-const emitSortChanged = (
+const didEmitSortChanged = (
     sorter: Gtk.ColumnViewSorter | null,
     sorting: RefObject<boolean>,
     sort: SortProps,
-): void => {
+): boolean => {
     if (sorter === null || sorting.current) {
-        return;
+        return false;
     }
 
     sort.onSortChanged?.(sorter.getPrimarySortColumn()?.getId() ?? null, sorter.getPrimarySortOrder());
+
+    return true;
 };
 
 const syncSort = (
@@ -124,16 +127,24 @@ const useColumnSorting = (view: Gtk.ColumnView | null, sort: SortProps, columns:
     const sorting = useRef(false);
     const sorter = view?.getSorter() ?? null;
     const columnSorter = sorter instanceof Gtk.ColumnViewSorter ? sorter : null;
-
-    useSignal(columnSorter, "changed", (): void => {
-        emitSortChanged(columnSorter, sorting, sort);
+    const { sortColumn, sortOrder } = sort;
+    const request = useMemo<SortRequest>(() => ({ sortColumn, sortOrder }), [sortColumn, sortOrder]);
+    const markDrift = useControlledSync({
+        value: request,
+        source: columns,
+        target: view,
+        apply: (value) => {
+            syncSort(sorting, view, value.sortColumn, value.sortOrder);
+        },
     });
 
-    const { sortColumn, sortOrder } = sort;
+    useSignal(columnSorter, "changed", (): void => {
+        const didEmit = didEmitSortChanged(columnSorter, sorting, sort);
 
-    useLayoutEffect(() => {
-        syncSort(sorting, view, sortColumn, sortOrder);
-    }, [view, sortColumn, sortOrder, columns]);
+        if (sortColumn !== undefined && didEmit) {
+            markDrift();
+        }
+    });
 };
 
 const ColumnCells = ({

package/src/index.ts

@@ -2,8 +2,9 @@ export { ColumnView } from "./column-view.js";
 export { ComboRow } from "./combo-row.js";
 export { DropDown } from "./drop-down.js";
 export { GridView } from "./grid-view.js";
+export { ListItemFactory } from "./list-item-factory.js";
 export { ListView } from "./list-view.js";
-export { ToastProvider, useToast, useToastOverlay } from "./toast.js";
+export { ToastProvider, useToast } from "./toast.js";
 export type {
     ColumnViewColumn,
     ColumnViewProps,
@@ -12,6 +13,7 @@ export type {
     ExpanderDescriptions,
     GridViewProps,
     ListItem,
+    ListItemFactoryProps,
     ListItemRenderArgs,
     ListItemRenderer,
     ListRowProps,
@@ -22,6 +24,5 @@ export type {
     ListViewProps,
     ToastController,
     ToastOptions,
-    ToastOverlayController,
     ToastProviderProps,
 } from "./types.js";

package/src/internal/cells.tsx

@@ -1,10 +1,9 @@
 import type * as GObject from "@gtkx/gi/gobject";
 import type { ReactElement, ReactNode } from "react";
 import * as Gtk from "@gtkx/gi/gtk";
-import { GtkSignalListItemFactory, GtkTreeExpander } from "@gtkx/jsx/gtk";
+import { GtkBox, GtkSignalListItemFactory, GtkTreeExpander } from "@gtkx/jsx/gtk";
 import { createPortal, useProperty } from "@gtkx/react";
-import { setProperty, t } from "@gtkx/runtime";
-import { memo, useInsertionEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
+import { Fragment, memo, useInsertionEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
 import type {
     ExpanderDescriptions,
     ListItem,
@@ -15,7 +14,8 @@ import type {
     ListSectionRenderer,
 } from "../types.js";
 import type { Collection } from "./collection.js";
-import { slotRefFor } from "./collection-model.js";
+import { slotPathAt, type SlotRef, slotRefFor } from "./collection-model.js";
+import { joinParts } from "./keys.js";
 
 type CellSize = {
     width: number;
@@ -84,6 +84,7 @@ type ItemSlotOptions = {
 type PositionedHost = Gtk.ListItem | Gtk.ColumnViewRow;
 
 type ItemSlot = {
+    itemKey: string;
     item: ListItem;
     row: Gtk.TreeListRow | null;
     args: ListItemRenderArgs<unknown>;
@@ -100,6 +101,7 @@ type CollectionStateStore = {
 };
 
 type ItemIdentity = {
+    itemKey: string;
     item: ListItem | undefined;
     position: number;
     isExpanded: boolean;
@@ -152,6 +154,23 @@ type HeaderPortalsProps = {
     collection: Collection;
 };
 
+type NativeItemKeyStore = {
+    keyFor: (item: GObject.Object) => string;
+};
+
+type NativeItemCellProps<T extends GObject.Object> = {
+    entry: CellEntry<Gtk.ListItem>;
+    render: ListItemRenderer<T>;
+    keys: NativeItemKeyStore;
+    size: CellSize;
+};
+
+type NativeItemPortalsProps<T extends GObject.Object> = {
+    registry: CellRegistry<Gtk.ListItem>;
+    render: ListItemRenderer<T>;
+    size: CellSize;
+};
+
 type SectionHeaderSlot = {
     factoryProps: { headerFactory?: ReactElement };
     portals: ReactNode;
@@ -170,10 +189,14 @@ const HEADER_OPTIONS: CellRegistryOptions<Gtk.ListHeader> = { isHost: isListHead
 const ROW_OPTIONS: CellRegistryOptions<Gtk.ColumnViewRow> = { isHost: isColumnViewRow };
 const NO_SIZE: CellSize = { width: -1, height: -1 };
 const NO_ROW_PROPS: ListRowProps = {};
-const ROW_TEXT_DESCRIPTOR = t.string("borrowed");
+const placeholders: WeakSet<Gtk.Widget> = new WeakSet();
 
-const placeholder = (size: CellSize): Gtk.Widget =>
-    new Gtk.Box({ widthRequest: size.width, heightRequest: size.height });
+const placeholder = (size: CellSize): Gtk.Widget => {
+    const widget = new Gtk.Box({ widthRequest: size.width, heightRequest: size.height });
+    placeholders.add(widget);
+
+    return widget;
+};
 
 function isListItem(value: GObject.Object): value is Gtk.ListItem {
     return value instanceof Gtk.ListItem;
@@ -188,8 +211,12 @@ function isColumnViewRow(value: GObject.Object): value is Gtk.ColumnViewRow {
 }
 
 function prepareCell(host: CellHost, size: CellSize): void {
-    if (host.getChild() === null) {
+    const child = host.getChild();
+
+    if (child === null) {
         host.setChild(placeholder(size));
+    } else if (placeholders.has(child)) {
+        child.setSizeRequest(size.width, size.height);
     }
 }
 
@@ -274,7 +301,15 @@ function createCellRegistry<H extends FactoryHost>(options: CellRegistryOptions<
     return {
         handlers: createHandlers(state),
         setSize: (next) => {
+            if (state.size.width === next.width && state.size.height === next.height) {
+                return;
+            }
+
             state.size = next;
+
+            for (const host of state.entries.keys()) {
+                state.prepare?.(host, next);
+            }
         },
         subscribe: (onChange) => subscribeRegistry(state, onChange),
         getEntries: () => getRegistryEntries(state),
@@ -324,15 +359,25 @@ function itemArgs(
     return args;
 }
 
+function keyForItem(ref: SlotRef, item: ListItem): string {
+    return joinParts([slotPathAt(ref.store, ref.slot), item.id]);
+}
+
 function slotFor(options: ItemSlotOptions): ItemSlot | null {
     const ref = slotRefFor(options.item);
-    const item = ref === null ? undefined : options.collection.itemAt(ref);
+
+    if (ref === null) {
+        return null;
+    }
+
+    const item = options.collection.itemAt(ref);
 
     if (item === undefined) {
         return null;
     }
 
     return {
+        itemKey: keyForItem(ref, item),
         item,
         row: options.row,
         args: itemArgs(item, options.position, options.row, isRowWanted(options, item)),
@@ -352,6 +397,7 @@ function useItemSlot(
         return identity.item === undefined
             ? null
             : {
+                    itemKey: identity.itemKey,
                     item: identity.item,
                     row,
                     args: itemArgs(identity.item, position, row, identity.isExpanded),
@@ -372,15 +418,17 @@ function itemIdentity(
     const item = ref === null ? undefined : collection.itemAt(ref);
 
     return {
+        itemKey: ref === null || item === undefined ? "" : keyForItem(ref, item),
         item,
         position: entry.host.getPosition(),
-        isExpanded: item === undefined ? false : (expandedIds?.includes(item.id) ?? false),
+        isExpanded: item !== undefined && (expandedIds?.includes(item.id) ?? false),
     };
 }
 
 function isSameItemIdentity(previous: ItemIdentity, next: ItemIdentity): boolean {
     return (
         previous.item === next.item &&
+        previous.itemKey === next.itemKey &&
         previous.position === next.position &&
         previous.isExpanded === next.isExpanded
     );
@@ -415,8 +463,30 @@ function createItemIdentityStore(): ItemIdentityStore {
     };
 }
 
+function createNativeItemKeyStore(): NativeItemKeyStore {
+    const keys: WeakMap<GObject.Object, string> = new WeakMap();
+    let serial = 0;
+
+    return {
+        keyFor: (item) => {
+            const current = keys.get(item);
+
+            if (current !== undefined) {
+                return current;
+            }
+
+            serial += 1;
+            const key = `gtkx-native-item-${String(serial)}`;
+            keys.set(item, key);
+
+            return key;
+        },
+    };
+}
+
 function renderedIdentity(entry: CellEntry<PositionedHost>, slot: ItemSlot | null): ItemIdentity {
     return {
+        itemKey: slot?.itemKey ?? "",
         item: slot?.item,
         position: slot?.args.index ?? entry.host.getPosition(),
         isExpanded: slot?.args.isExpanded ?? false,
@@ -506,7 +576,9 @@ function itemBody(
     const renderItem = render as ListItemRenderer<unknown>;
     const content = renderItem(slot.args);
 
-    return hasExpander ? wrapExpander(slot, content, descriptions) : content;
+    return (
+        <Fragment key={slot.itemKey}>{hasExpander ? wrapExpander(slot, content, descriptions) : content}</Fragment>
+    );
 }
 
 function rowText(value: string | undefined): string | null {
@@ -531,21 +603,17 @@ function rowPropsFor(slot: ItemSlot | null, rowProps: ListRowPropsResolver<never
     };
 }
 
-function setRowText(host: Gtk.ColumnViewRow, name: string, value: string | null): void {
-    setProperty(host, name, ROW_TEXT_DESCRIPTOR, value);
-}
-
 function applyRowProps(
     host: Gtk.ColumnViewRow,
     props: ResolvedRowProps,
     previous: ResolvedRowProps | null,
 ): void {
     if (previous?.accessibleLabel !== props.accessibleLabel) {
-        setRowText(host, "accessible-label", props.accessibleLabel);
+        host.accessibleLabel = props.accessibleLabel;
     }
 
     if (previous?.accessibleDescription !== props.accessibleDescription) {
-        setRowText(host, "accessible-description", props.accessibleDescription);
+        host.accessibleDescription = props.accessibleDescription;
     }
 
     if (previous?.isActivatable !== props.isActivatable) {
@@ -592,13 +660,52 @@ function ItemRowImpl({ entry, rowProps, state, ...identity }: ItemRowProps): Rea
 
 function HeaderCellImpl({ entry, render, collection }: HeaderCellProps): ReactNode {
     const item = useProperty(entry.host, "item") ?? null;
-    const ref = slotRefFor(item);
-    const renderHeader = render as ListSectionRenderer<unknown>;
-    const body = ref === null ? null : renderHeader({ section: collection.sectionFor(ref.store.level.path) });
+
+    return createPortal(headerBody(slotRefFor(item), render, collection), entry.host, entry.key);
+}
+
+function NativeItemCell<T extends GObject.Object>({
+    entry,
+    render,
+    keys,
+    size,
+}: NativeItemCellProps<T>): ReactNode {
+    const position = useProperty(entry.host, "position");
+    const item = useProperty(entry.host, "item") ?? null;
+    let body: ReactNode = null;
+
+    if (item !== null && position !== undefined) {
+        const content = render({ item: item as T, index: position });
+        const child = content == null || typeof content === "boolean"
+            ? <GtkBox widthRequest={size.width} heightRequest={size.height} />
+            : content;
+        body = <Fragment key={keys.keyFor(item)}>{child}</Fragment>;
+    }
 
     return createPortal(body, entry.host, entry.key);
 }
 
+function headerBody(
+    ref: SlotRef | null,
+    render: ListSectionRenderer<never>,
+    collection: Collection,
+): ReactNode {
+    if (ref === null) {
+        return null;
+    }
+
+    const section = collection.sectionFor(ref.store.level.path);
+
+    if (section === undefined) {
+        return null;
+    }
+
+    const renderHeader = render as ListSectionRenderer<unknown>;
+    const key = joinParts([ref.store.level.path, section.id]);
+
+    return <Fragment key={key}>{renderHeader({ section: section.value })}</Fragment>;
+}
+
 function usePortalEntries<H extends FactoryHost>(registry: CellRegistry<H>): CellEntry<H>[] {
     return useSyncExternalStore(registry.subscribe, registry.getEntries);
 }
@@ -647,6 +754,15 @@ const HeaderPortals = ({ registry, render, collection }: HeaderPortalsProps): Re
         <HeaderCell key={entry.key} entry={entry} render={render} collection={collection} />
     ));
 
+function NativeItemPortals<T extends GObject.Object>({ registry, render, size }: NativeItemPortalsProps<T>): ReactNode {
+    const entries = usePortalEntries(registry);
+    const [keys] = useState(createNativeItemKeyStore);
+
+    return entries.map((entry) => (
+        <NativeItemCell key={entry.key} entry={entry} render={render} keys={keys} size={size} />
+    ));
+}
+
 const useSectionHeader = (
     render: ListSectionRenderer<never> | null | undefined,
     collection: Collection,
@@ -688,5 +804,6 @@ export {
     useRowProps,
     useSectionHeader,
     ItemPortals,
+    NativeItemPortals,
     type CellSize,
 };

package/src/internal/collection-index.ts

@@ -7,20 +7,22 @@ type Level = {
     expandableFlags: boolean[];
 };
 
+type SectionIdentity = Pick<ListSection, "id" | "value">;
+
 type CollectionIndex = {
     isTree: boolean;
     groups: Level[];
     childLevel: (level: Level, slot: number) => Level | undefined;
     levelFor: (levelPath: string) => Level | undefined;
     itemAt: (levelPath: string, slot: number) => ListItem | undefined;
-    sectionFor: (levelPath: string) => unknown;
+    sectionFor: (levelPath: string) => SectionIdentity | undefined;
 };
 
 type IndexState = {
     isTree: boolean;
     groups: Level[];
     levels: Map<string, Level>;
-    sectionValues: Map<string, unknown>;
+    sections: Map<string, SectionIdentity>;
 };
 
 type ParentItem = ListItem & { children: ListItem[] };
@@ -96,7 +98,7 @@ function buildGroups(state: IndexState, source: ListItem[], sections: ListSectio
 
     return sections.map((section, group) => {
         const path = encodePart(String(group));
-        state.sectionValues.set(path, section.value);
+        state.sections.set(path, { id: section.id, value: section.value });
 
         return newLevel(state, path, section.data);
     });
@@ -125,7 +127,7 @@ function createCollectionIndex(
         isTree: isTreeSource(source, sections, isFlat),
         groups: [],
         levels: new Map(),
-        sectionValues: new Map(),
+        sections: new Map(),
     };
 
     state.groups = buildGroups(state, source, sections);
@@ -136,8 +138,8 @@ function createCollectionIndex(
         childLevel: (level, slot) => childLevel(state, level, slot),
         levelFor: (levelPath) => levelFor(state, levelPath),
         itemAt: (levelPath, slot) => levelFor(state, levelPath)?.items[slot],
-        sectionFor: (levelPath) => state.sectionValues.get(levelPath),
+        sectionFor: (levelPath) => state.sections.get(levelPath),
     };
 }
 
-export { createCollectionIndex, type CollectionIndex, type Level };
+export { createCollectionIndex, type CollectionIndex, type Level, type SectionIdentity };