@gtkx/components 1.0.0-rc.2 → 1.0.0-rc.4

package/src/column-view.tsx

@@ -1,12 +1,12 @@
-import type { ReactNode } from "react";
+import type { ReactNode, RefObject } from "react";
 import * as Gtk from "@gtkx/gi/gtk";
 import { GtkColumnView, GtkColumnViewColumn, GtkCustomSorter, GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
-import { useProperty, useSignal } from "@gtkx/react";
+import { useSignal } from "@gtkx/react";
 import { omit } from "@gtkx/utils";
 import { useLayoutEffect, useRef } from "react";
 import type { CellSize } from "./internal/cells.js";
 import type { Collection } from "./internal/collection.js";
-import type { Column, ColumnViewProps } from "./types.js";
+import type { ColumnViewColumn, ColumnViewProps } from "./types.js";
 import { HeaderPortals, ItemPortals, useHeaderCells, useItemCells } from "./internal/cells.js";
 import { useCollection } from "./internal/use-collection.js";
 import { useWidgetRef } from "./internal/use-widget-ref.js";
@@ -20,14 +20,14 @@ type SortProps = {
 type SortTarget = { view: Gtk.ColumnView; column: Gtk.ColumnViewColumn | null };
 
 type ColumnCellsProps = {
-    column: Column<never>;
+    column: ColumnViewColumn<never>;
     collection: Collection;
     expandedIds: string[] | null | undefined;
     size: CellSize;
 };
 
 type ColumnListProps = Omit<ColumnCellsProps, "column"> & {
-    columns: Column<never>[];
+    columns: ColumnViewColumn<never>[];
 };
 
 const COLUMN_VIEW_PROPS = [
@@ -77,7 +77,7 @@ const getSortTarget = (view: Gtk.ColumnView | null, sortColumn: string | null |
 };
 
 const applySort = (
-    sorting: { current: boolean },
+    sorting: RefObject<boolean>,
     view: Gtk.ColumnView,
     column: Gtk.ColumnViewColumn | null,
     order: Gtk.SortType | null | undefined,
@@ -93,7 +93,7 @@ const applySort = (
 
 const emitSortChanged = (
     sorter: Gtk.ColumnViewSorter | null,
-    sorting: { current: boolean },
+    sorting: RefObject<boolean>,
     sort: SortProps,
 ): void => {
     if (sorter === null || sorting.current) {
@@ -104,7 +104,7 @@ const emitSortChanged = (
 };
 
 const syncSort = (
-    sorting: { current: boolean },
+    sorting: RefObject<boolean>,
     view: Gtk.ColumnView | null,
     sortColumn: string | null | undefined,
     sortOrder: Gtk.SortType | null | undefined,
@@ -118,9 +118,9 @@ const syncSort = (
     applySort(sorting, target.view, target.column, sortOrder);
 };
 
-const useColumnSorting = (view: Gtk.ColumnView | null, sort: SortProps, columns: Column<never>[]): void => {
+const useColumnSorting = (view: Gtk.ColumnView | null, sort: SortProps, columns: ColumnViewColumn<never>[]): void => {
     const sorting = useRef(false);
-    const sorter = useProperty(view, "sorter");
+    const sorter = view?.getSorter() ?? null;
     const columnSorter = sorter instanceof Gtk.ColumnViewSorter ? sorter : null;
 
     useSignal(columnSorter, "changed", (): void => {
@@ -136,14 +136,14 @@ const useColumnSorting = (view: Gtk.ColumnView | null, sort: SortProps, columns:
 
 const ColumnCells = ({ column, collection, expandedIds, size }: ColumnCellsProps): ReactNode => {
     const cells = useItemCells(size);
-    const rest = omit(column, ["id", "renderCell", "sortable"]);
+    const rest = omit(column, ["id", "renderCell", "isSortable"]);
 
     return (
         <>
             <GtkColumnViewColumn
                 id={column.id}
                 factory={<GtkSignalListItemFactory {...cells.handlers} />}
-                sorter={column.sortable === true ? <GtkCustomSorter /> : null}
+                sorter={column.isSortable === true ? <GtkCustomSorter /> : null}
                 {...rest}
             />
             <ItemPortals
@@ -181,7 +181,7 @@ function ColumnView<T = unknown, S = unknown>(props: ColumnViewProps<T, S>): Rea
     const size = { width: -1, height: estimatedItemHeight ?? -1 };
     const { collection, selection } = useCollection(props);
     const headerCells = useHeaderCells(size);
-    const columnList = columns as Column<never>[];
+    const columnList = columns as ColumnViewColumn<never>[];
     useColumnSorting(view, { sortColumn, sortOrder, onSortChanged }, columnList);
 
     return (

package/src/drop-down.tsx

@@ -1,205 +1,20 @@
-import type * as GObject from "@gtkx/gi/gobject";
-import type { ElementType, ReactNode, Ref, RefObject } from "react";
-import { GtkDropDown, GtkLabel, GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
-import { useSignal } from "@gtkx/react";
-import { omit } from "@gtkx/utils";
-import { useEffectEvent, useLayoutEffect, useRef } from "react";
-import type { Collection } from "./internal/collection.js";
-import type { DropDownProps, ItemRenderer, RenderItemArgs } from "./types.js";
-import { HeaderPortals, ItemPortals, useHeaderCells, useItemCells } from "./internal/cells.js";
-import { useCollectionData } from "./internal/use-collection.js";
-import { useWidgetRef } from "./internal/use-widget-ref.js";
+import type { ReactNode } from "react";
+import { GtkDropDown } from "@gtkx/jsx/gtk";
+import type { DropDownBaseProps } from "./internal/drop-down.js";
+import type { DropDownProps } from "./types.js";
+import { DropDownBase } from "./internal/drop-down.js";
 
-type SelectableWidget = GObject.Object & { getSelected: () => number; selected: number };
-
-type DropDownRuntimeProps = DropDownProps & {
-    component?: ElementType | undefined;
-    ref?: Ref<SelectableWidget | null> | undefined;
-} & Record<string, unknown>;
-
-type SelectionOptions = {
-    widget: SelectableWidget | null;
-    collection: Collection;
-    applying: RefObject<boolean>;
-    props: DropDownRuntimeProps;
-};
-
-type KnownSelection = {
-    known: { current: string | null };
-    onSelectionChanged: ((id: string) => void) | null | undefined;
-};
-
-type DropDownComponent = <T = unknown, S = unknown, C extends ElementType = typeof GtkDropDown>(
-    props: DropDownProps<T, S, C>,
-) => ReactNode;
-
-const DROP_DOWN_PROPS: string[] = [
-    "component",
-    "items",
-    "sections",
-    "selectedId",
-    "onSelectionChanged",
-    "renderItem",
-    "renderListItem",
-    "renderHeader",
-    "ref",
-];
+/** Call signature of {@link DropDown}, generic in the item and section value types. */
+type DropDownComponent = <T = unknown, S = unknown>(props: DropDownProps<T, S>) => ReactNode;
 
 /**
- * Renders a drop-down backed by a collection model, with customizable renderers for the
+ * Renders a `Gtk.DropDown` backed by a collection model, with customizable renderers for the
  * collapsed display, popup rows, and popup section headers, and controlled selection.
- * The backing widget defaults to GtkDropDown and is swappable through `component`.
  */
 const DropDown: DropDownComponent = DropDownImpl as DropDownComponent;
 
-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: DropDownRuntimeProps): ItemRenderer<never> =>
-    props.renderItem ?? defaultRenderItem;
-
-const listRenderer = (props: DropDownRuntimeProps): 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,
-    applying: RefObject<boolean>,
-): void => {
-    const { widget, collection } = options;
-
-    if (widget === null || applying.current) {
-        return;
-    }
-
-    reportKnownSelection(tracker, collection.idAt(widget.getSelected()));
-};
-
-const applySelectedPosition = (widget: SelectableWidget, position: number, applying: RefObject<boolean>): void => {
-    applying.current = true;
-
-    try {
-        widget.selected = position;
-    } finally {
-        applying.current = false;
-    }
-};
-
-const useDropDownSelection = (options: SelectionOptions): void => {
-    const { widget, collection, applying } = 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, applying);
-        syncKnownSelection(position);
-    }, [widget, collection, selectedId, applying]);
-
-    useSignal(widget, "notify::selected", (): void => {
-        reportSelectedNotify(options, { known, onSelectionChanged: options.props.onSelectionChanged }, applying);
-    });
-};
-
-function DropDownImpl(props: DropDownRuntimeProps): ReactNode {
-    const { component, items, sections, renderListItem, renderHeader, ref } = props;
-    const rest = omit(props, DROP_DOWN_PROPS);
-    const [widget, refCallback] = useWidgetRef<SelectableWidget>(ref);
-    const applying = useRef(false);
-    const collection = useCollectionData({ items, sections, applying });
-    const faceCells = useItemCells({ width: -1, height: -1 });
-    const listCells = useItemCells({ width: -1, height: -1 });
-    const headerCells = useHeaderCells({ width: -1, height: -1 });
-    useDropDownSelection({ widget, collection, applying, props });
-    const Component = component ?? GtkDropDown;
-    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}
-            />
-            <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} />}
-        </>
-    );
+function DropDownImpl(props: DropDownBaseProps): ReactNode {
+    return <DropDownBase {...props} component={GtkDropDown} />;
 }
 
 export { DropDown };

package/src/grid-view.tsx

@@ -23,7 +23,7 @@ function GridView<T = unknown>(props: GridViewProps<T>): ReactNode {
     const { renderItem, estimatedItemHeight, estimatedItemWidth } = props;
     const rest = omit(props, GRID_VIEW_PROPS);
     const size = { width: estimatedItemWidth ?? -1, height: estimatedItemHeight ?? -1 };
-    const { collection, selection } = useCollection({ ...props, flat: true });
+    const { collection, selection } = useCollection({ ...props, isFlat: true });
     const itemCells = useItemCells(size);
 
     return (

package/src/index.ts

@@ -2,21 +2,16 @@ export { ColumnView } from "./column-view.js";
 export { DropDown } from "./drop-down.js";
 export { GridView } from "./grid-view.js";
 export { ListView } from "./list-view.js";
-export { SizeGroup } from "./size-group.js";
 export type {
-    ChildProps,
-    Column,
+    ColumnViewColumn,
     ColumnViewProps,
     DropDownProps,
     GridViewProps,
-    HeaderRenderer,
-    Item,
-    ItemRenderer,
+    ListItem,
+    ListItemRenderArgs,
+    ListItemRenderer,
+    ListSection,
+    ListSectionRenderArgs,
+    ListSectionRenderer,
     ListViewProps,
-    RenderHeaderArgs,
-    RenderItemArgs,
-    Section,
-    SizeGroupChildProps,
-    SizeGroupProps,
-    WidgetProps,
 } from "./types.js";

package/src/internal/cells.tsx

@@ -4,7 +4,7 @@ import * as Gtk from "@gtkx/gi/gtk";
 import { GtkTreeExpander } from "@gtkx/jsx/gtk";
 import { createPortal, useProperty } from "@gtkx/react";
 import { memo, useLayoutEffect, useState, useSyncExternalStore } from "react";
-import type { HeaderRenderer, Item, ItemRenderer, RenderItemArgs } from "../types.js";
+import type { ListItem, ListItemRenderArgs, ListItemRenderer, ListSectionRenderer } from "../types.js";
 import type { Collection } from "./collection.js";
 import { getId } from "./collection-model.js";
 
@@ -56,34 +56,34 @@ type ItemBodyOptions = {
     position: number | undefined;
     row: Gtk.TreeListRow | null;
     isRowExpanded: boolean | undefined;
-    render: ItemRenderer<never>;
+    render: ListItemRenderer<never>;
     collection: Collection;
     expandedIds: string[] | null | undefined;
 };
 
 type ItemCellProps = {
     entry: CellEntry<Gtk.ListItem>;
-    render: ItemRenderer<never>;
+    render: ListItemRenderer<never>;
     collection: Collection;
     expandedIds: string[] | null | undefined;
 };
 
 type ItemPortalsProps = {
     store: CellStore<Gtk.ListItem>;
-    render: ItemRenderer<never>;
+    render: ListItemRenderer<never>;
     collection: Collection;
     expandedIds?: string[] | null | undefined;
 };
 
 type HeaderCellProps = {
     entry: CellEntry<Gtk.ListHeader>;
-    render: HeaderRenderer<never>;
+    render: ListSectionRenderer<never>;
     collection: Collection;
 };
 
 type HeaderPortalsProps = {
     store: CellStore<Gtk.ListHeader>;
-    render: HeaderRenderer<never>;
+    render: ListSectionRenderer<never>;
     collection: Collection;
 };
 
@@ -246,14 +246,14 @@ function useHeaderCells(size: CellSize): CellStore<Gtk.ListHeader> {
     return useCellStore(isListHeader, size);
 }
 
-function isRowWanted(options: ItemBodyOptions, item: Item): boolean {
+function isRowWanted(options: ItemBodyOptions, item: ListItem): boolean {
     const { expandedIds } = options;
 
     return expandedIds == null ? options.isRowExpanded === true : expandedIds.includes(item.id);
 }
 
-function itemArgs(item: Item, options: ItemBodyOptions): RenderItemArgs<unknown> {
-    const args: RenderItemArgs<unknown> = { item: item.value, index: options.position ?? 0 };
+function itemArgs(item: ListItem, options: ItemBodyOptions): ListItemRenderArgs<unknown> {
+    const args: ListItemRenderArgs<unknown> = { item: item.value, index: options.position ?? 0 };
     const row = options.row;
 
     if (row === null) {
@@ -269,7 +269,7 @@ function itemArgs(item: Item, options: ItemBodyOptions): RenderItemArgs<unknown>
     return args;
 }
 
-function wrapExpander(item: Item, row: Gtk.TreeListRow | null, content: ReactNode): ReactNode {
+function wrapExpander(item: ListItem, row: Gtk.TreeListRow | null, content: ReactNode): ReactNode {
     const expander: ReactNode =
         row === null
             ? (
@@ -297,7 +297,7 @@ function itemBody(options: ItemBodyOptions): ReactNode {
         return null;
     }
 
-    const render = options.render as ItemRenderer<unknown>;
+    const render = options.render as ListItemRenderer<unknown>;
 
     return wrapExpander(item, options.row, render(itemArgs(item, options)));
 }
@@ -315,7 +315,7 @@ function ItemCellImpl({ entry, render, collection, expandedIds }: ItemCellProps)
 function HeaderCellImpl({ entry, render, collection }: HeaderCellProps): ReactNode {
     const item = useSyncExternalStore(entry.subscribe, entry.getItem);
     const id = getId(item);
-    const renderHeader = render as HeaderRenderer<unknown>;
+    const renderHeader = render as ListSectionRenderer<unknown>;
     const body = id === null ? null : renderHeader({ section: collection.sectionFor(id) });
 
     return createPortal(body, entry.cell, entry.key);

package/src/internal/collection-index.ts

@@ -1,9 +1,9 @@
-import type { Item, Section } from "../types.js";
+import type { ListItem, ListSection } from "../types.js";
 
 type Level = {
     key: string;
     ids: string[];
-    isExpandable: boolean[];
+    expandableFlags: boolean[];
 };
 
 type CollectionIndex = {
@@ -11,8 +11,8 @@ type CollectionIndex = {
     size: number;
     groups: Level[];
     children: Map<string, Level>;
-    has: (id: string) => boolean;
-    itemFor: (id: string) => Item | undefined;
+    hasId: (id: string) => boolean;
+    itemFor: (id: string) => ListItem | undefined;
     sectionFor: (id: string) => unknown;
     positionFor: (id: string) => number;
 };
@@ -21,24 +21,24 @@ type IndexState = {
     isTree: boolean;
     groups: Level[];
     children: Map<string, Level>;
-    itemsById: Map<string, Item>;
-    sections: Section[] | undefined;
+    itemsById: Map<string, ListItem>;
+    sections: ListSection[] | undefined;
     positions: Map<string, number> | null;
     starts: number[] | null;
 };
 
 const ROOT_LEVEL_KEY = "";
 
-const hasChildren = (item: Item): boolean => item.children !== undefined && item.children.length > 0;
+const hasChildren = (item: ListItem): boolean => item.children !== undefined && item.children.length > 0;
 const childLevelKey = (id: string): string => `child:${id}`;
 
-function collectChildren(state: IndexState, level: Level, item: Item): void {
+function collectChildren(state: IndexState, level: Level, item: ListItem): void {
     if (!state.isTree) {
         return;
     }
 
     const canExpand = hasChildren(item);
-    level.isExpandable.push(canExpand);
+    level.expandableFlags.push(canExpand);
 
     if (!canExpand) {
         return;
@@ -48,8 +48,8 @@ function collectChildren(state: IndexState, level: Level, item: Item): void {
     state.children.set(key, collectLevel(state, key, item.children ?? []));
 }
 
-function collectLevel(state: IndexState, key: string, items: Item[]): Level {
-    const level: Level = { key, ids: [], isExpandable: [] };
+function collectLevel(state: IndexState, key: string, items: ListItem[]): Level {
+    const level: Level = { key, ids: [], expandableFlags: [] };
 
     for (const item of items) {
         level.ids.push(item.id);
@@ -118,7 +118,7 @@ function sectionFor(state: IndexState, id: string): unknown {
     return sections[sectionAt(state.starts, position)]?.value;
 }
 
-function buildGroups(state: IndexState, source: Item[], sections: Section[] | undefined): Level[] {
+function buildGroups(state: IndexState, source: ListItem[], sections: ListSection[] | undefined): Level[] {
     if (sections === undefined) {
         return [collectLevel(state, ROOT_LEVEL_KEY, source)];
     }
@@ -126,7 +126,7 @@ function buildGroups(state: IndexState, source: Item[], sections: Section[] | un
     return sections.map((section) => collectLevel(state, section.id, section.data));
 }
 
-function isTreeSource(source: Item[], sections: Section[] | undefined, isFlat: boolean): boolean {
+function isTreeSource(source: ListItem[], sections: ListSection[] | undefined, isFlat: boolean): boolean {
     if (sections !== undefined || isFlat) {
         return false;
     }
@@ -135,8 +135,8 @@ function isTreeSource(source: Item[], sections: Section[] | undefined, isFlat: b
 }
 
 function createCollectionIndex(
-    items: Item[] | undefined,
-    sections: Section[] | undefined,
+    items: ListItem[] | undefined,
+    sections: ListSection[] | undefined,
     isFlat: boolean,
 ): CollectionIndex {
     const source = items ?? [];
@@ -158,7 +158,7 @@ function createCollectionIndex(
         size: state.itemsById.size,
         groups: state.groups,
         children: state.children,
-        has: (id) => state.itemsById.has(id),
+        hasId: (id) => state.itemsById.has(id),
         itemFor: (id) => state.itemsById.get(id),
         sectionFor: (id) => sectionFor(state, id),
         positionFor: (id) => positionFor(state, id),

package/src/internal/collection-model.ts

@@ -104,7 +104,7 @@ 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 isWanted = level.expandableFlags[index] ?? false;
         const previous = current.canExpand.get(id);
         next.set(id, isWanted);
 
@@ -138,16 +138,13 @@ function dropUnvisited(state: ModelState, visited: Set<string>): void {
     }
 }
 
-// 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)) {
+        if (!index.hasId(id)) {
             state.objects.delete(id);
         }
     }

package/src/internal/collection.ts

@@ -1,6 +1,6 @@
 import type * as GObject from "@gtkx/gi/gobject";
 import type * as Gtk from "@gtkx/gi/gtk";
-import type { Item } from "../types.js";
+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";
@@ -9,7 +9,7 @@ type Collection = {
     isTree: boolean;
     model: Gtk.FlattenListModel;
     treeModel: () => Gtk.TreeListModel | null;
-    itemFor: (id: string) => Item | undefined;
+    itemFor: (id: string) => ListItem | undefined;
     sectionFor: (id: string) => unknown;
     idAt: (position: number) => string | null;
     positionFor: (id: string) => number;