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

package/src/drop-down.tsx

@@ -1,192 +1,205 @@
-import type * as Gtk from "@gtkx/gi/gtk";
-import { GtkDropDown, GtkLabel } from "@gtkx/jsx/gtk";
-import { useMergeRefs } from "@gtkx/react/internal";
-import { type ElementType, type ReactNode, type Ref, useCallback, useRef, useState } from "react";
-import { type CellRenderer, CellRenderHost, HeaderRenderHost, itemRenderer } from "./cell.js";
-import { makeFactoryInstaller, useCellContainers } from "./hooks/use-cell-containers.js";
-import { useDropDownSelection } from "./hooks/use-drop-down-selection.js";
-import { useInstalledModel } from "./hooks/use-installed-model.js";
-import { useListModel } from "./hooks/use-list-model.js";
-import type { ItemNode, RenderItemProps, SectionNode, WidgetProps } from "./types.js";
-import type { CellContainerStore } from "./utils/cell-container-store.js";
-import type { ItemResolver } from "./utils/item-resolver.js";
-
-export type DropDownItemRenderer<T> = (props: RenderItemProps<T>) => ReactNode;
-
-const itemFactoryInstaller = makeFactoryInstaller<Gtk.DropDown>((widget, factory) => widget.setFactory(factory));
-
-const listFactoryInstaller = makeFactoryInstaller<Gtk.DropDown>((widget, factory) => widget.setListFactory(factory));
-
-const headerFactoryInstaller = makeFactoryInstaller<Gtk.DropDown>((widget, factory) =>
-    widget.setHeaderFactory(factory),
-);
-
-const defaultRenderer: CellRenderer<unknown, unknown> = (value) => {
-    if (value === undefined || value === null) return null;
-    return <GtkLabel>{String(value)}</GtkLabel>;
+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";
+
+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;
 };
 
-const toItemRenderer = <T, S>(renderItem: DropDownItemRenderer<T> | null | undefined): CellRenderer<T, S> => {
-    if (typeof renderItem !== "function") return defaultRenderer as CellRenderer<T, S>;
-    return itemRenderer<T, S>(renderItem);
+type KnownSelection = {
+    known: { current: string | null };
+    onSelectionChanged: ((id: string) => void) | null | undefined;
 };
 
-const toListRenderer = <T, S>(
-    renderListItem: DropDownItemRenderer<T> | null | undefined,
-    renderItem: DropDownItemRenderer<T> | null | undefined,
-): CellRenderer<T, S> => {
-    if (typeof renderListItem === "function") return itemRenderer<T, S>(renderListItem);
-    return toItemRenderer<T, S>(renderItem);
+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",
+];
+
+/**
+ * Renders a drop-down 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 createSelectionResolver = <T, S>(resolver: ItemResolver<T, S>, selectedPosition: number): ItemResolver<T, S> => ({
-    positionOfId: (id) => resolver.positionOfId(id),
-    idOf: (position) => resolver.idOf(position),
-    resolve: (_position, treeRow) => resolver.resolve(selectedPosition, treeRow),
-});
-
-/** Declarative props for {@link DropDown}'s backing collection and cell rendering. */
-export type DropDownDeclarativeProps<T = unknown, S = unknown> = {
-    items?: ItemNode<T>[] | undefined;
-    sections?: SectionNode<S, T>[] | undefined;
-    /** Id of the currently selected item, making the selection controlled. */
-    selectedId?: string | null | undefined;
-    onSelectionChanged?: ((id: string) => void) | null | undefined;
-    renderItem?: DropDownItemRenderer<T> | null | undefined;
-    /** Renderer for items in the open popup list, falling back to renderItem when omitted. */
-    renderListItem?: DropDownItemRenderer<T> | null | undefined;
-    /** Renderer for section headers in the popup list. */
-    renderHeader?: ((info: { section: S }) => ReactNode) | null | undefined;
+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();
 };
 
-/**
- * Props for {@link DropDown}. The backing widget is chosen through the `component` prop, defaulting to
- * GtkDropDown, and its own props combine with {@link DropDownDeclarativeProps}.
- */
-export type DropDownProps<T = unknown, S = unknown, C extends ElementType = typeof GtkDropDown> = WidgetProps<
-    C,
-    DropDownDeclarativeProps<T, S>,
-    "model" | "factory" | "listFactory" | "headerFactory"
->;
-
-interface NormalizedDropDownProps<T, S> {
-    ref: Ref<Gtk.DropDown | null> | undefined;
-    items: ItemNode<T>[] | undefined;
-    sections: SectionNode<S, T>[] | undefined;
-    selectedId: string | null | undefined;
-    onSelectionChanged: ((id: string) => void) | null | undefined;
-    renderHeader: ((info: { section: S }) => ReactNode) | null | undefined;
-}
+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);
+    }
+};
 
-interface DropDownWiring<T, S> {
-    setRef: (value: Gtk.DropDown | null) => void;
-    resolver: ItemResolver<T, S>;
-    selectionResolver: ItemResolver<T, S>;
-    headerResolver: ItemResolver<T, S>;
-    selectionStore: CellContainerStore;
-    listStore: CellContainerStore;
-    headerStore: CellContainerStore;
-    useHeader: boolean;
-}
+const reportKnownSelection = (tracker: KnownSelection, id: string | null): void => {
+    const { known, onSelectionChanged } = tracker;
+
+    if (id === null || id === known.current) {
+        return;
+    }
 
-const useDropDownWiring = <T, S>(props: NormalizedDropDownProps<T, S>): DropDownWiring<T, S> => {
-    const widgetRef = useRef<Gtk.DropDown | null>(null);
-    const [widget, setWidget] = useState<Gtk.DropDown | null>(null);
-    const captureWidget = useCallback((value: Gtk.DropDown | null) => {
-        widgetRef.current = value;
-        setWidget(value);
-    }, []);
-    const setRef = useMergeRefs<Gtk.DropDown>(props.ref, captureWidget);
+    known.current = id;
+    onSelectionChanged?.(id);
+};
 
-    const listModel = useListModel<T, S>({ items: props.items, sections: props.sections });
+const reportSelectedNotify = (
+    options: SelectionOptions,
+    tracker: KnownSelection,
+    applying: RefObject<boolean>,
+): void => {
+    const { widget, collection } = options;
 
-    const useHeader = typeof props.renderHeader === "function";
+    if (widget === null || applying.current) {
+        return;
+    }
 
-    const selectionStore = useCellContainers<Gtk.DropDown>({ object: widgetRef, installer: itemFactoryInstaller });
-    const listStore = useCellContainers<Gtk.DropDown>({ object: widgetRef, installer: listFactoryInstaller });
-    const headerStore = useCellContainers<Gtk.DropDown>({
-        object: useHeader ? widgetRef : null,
-        installer: headerFactoryInstaller,
-    });
+    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);
 
-    useInstalledModel(widgetRef, listModel.model, (widget, value) => widget.setModel(value));
+    const syncKnownSelection = useEffectEvent((position: number): void => {
+        const effectiveId = collection.idAt(position);
 
-    const selectedPosition = useDropDownSelection<T, S>({
-        widget,
-        resolver: listModel.resolver,
-        selectedId: props.selectedId,
-        onSelectionChanged: props.onSelectionChanged,
+        if (effectiveId === null) {
+            known.current = null;
+
+            return;
+        }
+
+        const { onSelectionChanged } = options.props;
+        updateKnownSelection({ known, onSelectionChanged }, effectiveId, selectedId);
     });
 
-    const controlledPosition =
-        props.selectedId === undefined || props.selectedId === null
-            ? -1
-            : listModel.resolver.positionOfId(props.selectedId);
-    const selectionPosition =
-        controlledPosition >= 0 ? controlledPosition : selectedPosition < 0 ? 0 : selectedPosition;
-
-    return {
-        setRef,
-        resolver: listModel.resolver,
-        selectionResolver: createSelectionResolver(listModel.resolver, selectionPosition),
-        headerResolver: listModel.headerResolver,
-        selectionStore,
-        listStore,
-        headerStore,
-        useHeader,
-    };
-};
+    useLayoutEffect(() => {
+        if (widget === null) {
+            return;
+        }
 
-/**
- * Renders a drop-down widget (Gtk.DropDown by default, or the widget given as `component`) backed by a
- * collection model, with customizable rendering for the selected item, the popup list rows, and section
- * headers.
- */
-export const DropDown = <T = unknown, S = unknown, C extends ElementType = typeof GtkDropDown>(
-    props: DropDownProps<T, S, C>,
-): ReactNode => {
-    const {
-        component,
-        ref,
-        items,
-        sections,
-        renderItem,
-        renderListItem,
-        renderHeader,
-        selectedId,
-        onSelectionChanged,
-        ...intrinsicProps
-    } = props;
-    const Component: ElementType = component ?? GtkDropDown;
-
-    const wiring = useDropDownWiring<T, S>({
-        ref,
-        items,
-        sections,
-        selectedId,
-        onSelectionChanged,
-        renderHeader,
+        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 {...intrinsicProps} ref={wiring.setRef} />
-            <CellRenderHost
-                store={wiring.selectionStore}
-                resolver={wiring.selectionResolver}
-                render={toItemRenderer<T, S>(renderItem)}
-            />
-            <CellRenderHost
-                store={wiring.listStore}
-                resolver={wiring.resolver}
-                render={toListRenderer<T, S>(renderListItem, renderItem)}
-            />
-            <HeaderRenderHost
-                useHeader={wiring.useHeader}
-                store={wiring.headerStore}
-                resolver={wiring.headerResolver}
-                renderHeader={renderHeader}
+            <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} />}
         </>
     );
-};
+}
+
+export { DropDown };

package/src/grid-view.tsx

@@ -1,81 +1,37 @@
-import type * as Gtk from "@gtkx/gi/gtk";
-import { GtkGridView, type GtkGridViewProps } from "@gtkx/jsx/gtk";
-import { useMergeRefs } from "@gtkx/react/internal";
-import { type ReactNode, type Ref, useRef } from "react";
-import { type CellRenderer, CellRenderHost, itemRenderer } from "./cell.js";
-import { makeFactoryInstaller, useCellContainers } from "./hooks/use-cell-containers.js";
-import { useCollectionModel } from "./hooks/use-collection-model.js";
-import { useInstalledModel } from "./hooks/use-installed-model.js";
-import type { CollectionItemSizeProps, ControlledSelectionProps, ItemNode, RenderItemProps } from "./types.js";
-
-const factoryInstaller = makeFactoryInstaller<Gtk.GridView>((widget, factory) => widget.setFactory(factory));
-
-export type GridViewDeclarativeProps<T = unknown> = CollectionItemSizeProps &
-    ControlledSelectionProps & {
-        items?: ItemNode<T>[] | undefined;
-        renderItem: (props: RenderItemProps<T>) => ReactNode;
-    };
-
-/**
- * Props for {@link GridView}. Combines the underlying Gtk.GridView props with
- * declarative collection props: items, a per-cell renderItem, controlled selection,
- * and estimated item sizing.
- */
-export type GridViewProps<T = unknown> = Omit<
-    GtkGridViewProps,
-    "model" | "factory" | keyof GridViewDeclarativeProps<T>
-> &
-    GridViewDeclarativeProps<T>;
+import type { ReactNode } from "react";
+import { GtkGridView, GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
+import { omit } from "@gtkx/utils";
+import type { GridViewProps } from "./types.js";
+import { ItemPortals, useItemCells } from "./internal/cells.js";
+import { useCollection } from "./internal/use-collection.js";
+
+const GRID_VIEW_PROPS = [
+    "items",
+    "renderItem",
+    "selectedIds",
+    "onSelectionChanged",
+    "selectionMode",
+    "estimatedItemHeight",
+    "estimatedItemWidth",
+] as const satisfies (keyof GridViewProps)[];
 
 /**
- * Renders a Gtk.GridView: a scrollable grid of uniformly sized cells backed by a
- * collection model, with each cell drawn by renderItem.
+ * Renders a Gtk.GridView of uniform cells from declarative items, with per-cell
+ * rendering, controlled selection, and estimated item sizing.
  */
-export const GridView = <T = unknown>(props: GridViewProps<T>): ReactNode => {
-    const {
-        ref,
-        items,
-        renderItem,
-        selectedIds,
-        selectionMode,
-        onSelectionChanged,
-        estimatedItemHeight,
-        estimatedItemWidth,
-        ...intrinsicProps
-    } = props as GridViewDeclarativeProps<T> & {
-        ref?: Ref<Gtk.GridView | null>;
-        estimatedItemHeight?: number;
-        estimatedItemWidth?: number;
-        [key: string]: unknown;
-    };
-
-    const cellRenderer: CellRenderer<T, unknown> = itemRenderer<T, unknown>(renderItem);
-
-    const widgetRef = useRef<Gtk.GridView | null>(null);
-    const setRef = useMergeRefs<Gtk.GridView>(ref, widgetRef);
-
-    const collection = useCollectionModel<T, unknown>({
-        items,
-        sections: undefined,
-        selectionMode,
-        selectedIds,
-        onSelectionChanged,
-        renderHeader: undefined,
-    });
-
-    const itemStore = useCellContainers<Gtk.GridView>({
-        object: widgetRef,
-        installer: factoryInstaller,
-        estimatedHeight: estimatedItemHeight,
-        estimatedWidth: estimatedItemWidth,
-    });
-
-    useInstalledModel(widgetRef, collection.installedModel, (widget, value) => widget.setModel(value));
+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 itemCells = useItemCells(size);
 
     return (
         <>
-            <GtkGridView {...intrinsicProps} ref={setRef} />
-            <CellRenderHost store={itemStore} resolver={collection.resolver} render={cellRenderer} />
+            <GtkGridView model={selection} factory={<GtkSignalListItemFactory {...itemCells.handlers} />} {...rest} />
+            <ItemPortals store={itemCells} render={renderItem} collection={collection} />
         </>
     );
-};
+}
+
+export { GridView };

package/src/index.ts

@@ -1,29 +1,22 @@
-export {
-    type ColumnDef,
-    type ColumnDefDeclarativeProps,
-    ColumnView,
-    type ColumnViewDeclarativeProps,
-    type ColumnViewProps,
-    type ColumnViewSortProps,
-} from "./column-view.js";
-export { ConstraintLayout, type ConstraintLayoutProps } from "./constraint-layout.js";
-export type { ConstraintGuideProps, ConstraintProps, ConstraintVflProps } from "./constraint-layout-apply.js";
-export { DropDown, type DropDownDeclarativeProps, type DropDownItemRenderer, type DropDownProps } from "./drop-down.js";
-export { Fixed, type FixedChildProps, type FixedPlacementProps, type FixedProps } from "./fixed.js";
-export { Grid, type GridChildProps, type GridPlacement, type GridProps } from "./grid.js";
-export { GridView, type GridViewDeclarativeProps, type GridViewProps } from "./grid-view.js";
-export { ListView, type ListViewDeclarativeProps, type ListViewProps } from "./list-view.js";
-export { Menu, type MenuItemsProps, type MenuProps } from "./menu.js";
-export { Overlay, type OverlayChildProps, type OverlayPlacementProps, type OverlayProps } from "./overlay.js";
-export { SizeGroup, type SizeGroupChildProps, type SizeGroupProps } from "./size-group.js";
+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,
-    CollectionItemSizeProps,
-    ControlledExpansionProps,
-    ControlledSelectionProps,
-    ItemNode,
-    MenuEntry,
-    RenderItemProps,
-    SectionNode,
+    Column,
+    ColumnViewProps,
+    DropDownProps,
+    GridViewProps,
+    HeaderRenderer,
+    Item,
+    ItemRenderer,
+    ListViewProps,
+    RenderHeaderArgs,
+    RenderItemArgs,
+    Section,
+    SizeGroupChildProps,
+    SizeGroupProps,
     WidgetProps,
 } from "./types.js";