@gtkx/components 0.21.0 → 1.0.0-rc.2

package/src/drop-down.tsx

@@ -1,259 +1,205 @@
-import type * as Adw from "@gtkx/gi/adw";
-import type * as Gio from "@gtkx/gi/gio";
-import type * as Gtk from "@gtkx/gi/gtk";
-import { AdwComboRow, type AdwComboRowProps } from "@gtkx/jsx/adw";
-import { GtkDropDown, type GtkDropDownProps, GtkLabel } from "@gtkx/jsx/gtk";
-import { useForwardedRef } from "@gtkx/react";
-import {
-    createElement,
-    type ElementType,
-    type ReactElement,
-    type ReactNode,
-    type Ref,
-    useCallback,
-    useRef,
-    useState,
-} from "react";
-import { useDropDownSelection } from "./hooks/use-drop-down-selection.js";
-import { useListModel } from "./hooks/use-list-model.js";
-import { useModelInstallation } from "./hooks/use-model-installation.js";
-import { type FactoryBinding, useRealizedSlots } from "./hooks/use-realized-slots.js";
-import { ListPortalHost } from "./list-portal-host.js";
-import type { SlotRenderer } from "./list-slot.js";
-import type { DropDownProps, ListItem } from "./types.js";
-import type { ItemResolver } from "./utils/item-resolver.js";
-import type { RealizedSlotStore } from "./utils/realized-slot-store.js";
-
-export interface DropDownWidget extends Gtk.Widget {
-    getSelected(): number;
-    setSelected(position: number): void;
-    setModel(model: Gio.ListModel | null): void;
-    setFactory(factory: Gtk.ListItemFactory | null): void;
-    setListFactory(factory: Gtk.ListItemFactory | null): void;
-    setHeaderFactory(factory: Gtk.ListItemFactory | null): void;
-}
+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 itemFactoryBinding: FactoryBinding<DropDownWidget> = {
-    install: (widget, factory) => widget.setFactory(factory),
-    uninstall: (widget) => widget.setFactory(null),
+type KnownSelection = {
+    known: { current: string | null };
+    onSelectionChanged: ((id: string) => void) | null | undefined;
 };
 
-const listFactoryBinding: FactoryBinding<DropDownWidget> = {
-    install: (widget, factory) => widget.setListFactory(factory),
-    uninstall: (widget) => widget.setListFactory(null),
+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 headerFactoryBinding: FactoryBinding<DropDownWidget> = {
-    install: (widget, factory) => widget.setHeaderFactory(factory),
-    uninstall: (widget) => widget.setHeaderFactory(null),
+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 defaultRenderer: SlotRenderer<unknown, unknown> = (value, _treeRow, isHeader) => {
-    if (isHeader || value === undefined || value === null) return null;
-    return createElement(GtkLabel, { label: String(value) });
+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 DropDownImplProps<T, S, W extends DropDownWidget> {
-    element: ElementType;
-    intrinsicProps: Record<string, unknown>;
-    ref: Ref<W | null> | undefined;
-    items: ListItem<T, S>[] | undefined;
-    model: Gio.ListModel | undefined;
-    renderItem: ((value: T) => ReactNode) | null | undefined;
-    renderListItem: ((value: T) => ReactNode) | null | undefined;
-    renderHeader: ((value: S) => ReactNode) | null | undefined;
-    selectedId: string | null | undefined;
-    onSelectionChanged: ((id: string) => void) | null | undefined;
-}
+const reportKnownSelection = (tracker: KnownSelection, id: string | null): void => {
+    const { known, onSelectionChanged } = tracker;
+
+    if (id === null || id === known.current) {
+        return;
+    }
 
-const toItemRenderer = <T, S>(renderItem: ((value: T) => ReactNode) | null | undefined): SlotRenderer<T, S> => {
-    if (typeof renderItem !== "function") return defaultRenderer as SlotRenderer<T, S>;
-    return (value, _treeRow, isHeader) => (isHeader ? null : renderItem(value as T));
+    known.current = id;
+    onSelectionChanged?.(id);
 };
 
-const toPopupRenderer = <T, S>(
-    renderListItem: ((value: T) => ReactNode) | null | undefined,
-    renderItem: ((value: T) => ReactNode) | null | undefined,
-): SlotRenderer<T, S> => {
-    if (typeof renderListItem === "function")
-        return (value, _treeRow, isHeader) => (isHeader ? null : renderListItem(value as T));
-    return toItemRenderer<T, S>(renderItem);
+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 toHeaderRenderer = <T, S>(renderHeader: ((value: S) => ReactNode) | null | undefined): SlotRenderer<T, S> => {
-    if (typeof renderHeader !== "function") return () => null;
-    return (value) => renderHeader(value as S);
+const applySelectedPosition = (widget: SelectableWidget, position: number, applying: RefObject<boolean>): void => {
+    applying.current = true;
+
+    try {
+        widget.selected = position;
+    } finally {
+        applying.current = false;
+    }
 };
 
-interface DropDownWiring<T, S, W extends DropDownWidget> {
-    setRef: (value: W | null) => void;
-    resolver: ItemResolver<T, S>;
-    faceResolver: ItemResolver<T, S>;
-    headerResolver: ItemResolver<T, S>;
-    faceStore: RealizedSlotStore;
-    popupStore: RealizedSlotStore;
-    headerStore: RealizedSlotStore;
-    useHeader: boolean;
-}
+const useDropDownSelection = (options: SelectionOptions): void => {
+    const { widget, collection, applying } = options;
+    const { selectedId } = options.props;
+    const known = useRef<string | null>(null);
 
-const createFaceResolver = <T, S>(resolver: ItemResolver<T, S>, selectedPosition: number): ItemResolver<T, S> => ({
-    count: resolver.count,
-    positionOf: (id) => resolver.positionOf(id),
-    idOf: (position) => resolver.idOf(position),
-    resolve: (_position, treeRow) => resolver.resolve(selectedPosition, treeRow, null),
-});
-
-const useDropDownWiring = <T, S, W extends DropDownWidget>(
-    props: DropDownImplProps<T, S, W>,
-): DropDownWiring<T, S, W> => {
-    const widgetRef = useRef<DropDownWidget | null>(null);
-    const [widget, setWidget] = useState<DropDownWidget | null>(null);
-    const captureWidget = useCallback((value: W | null) => {
-        widgetRef.current = value;
-        setWidget(value);
-    }, []);
-    const [, setRef] = useForwardedRef<W>(props.ref, captureWidget);
-
-    const externalModel = props.model;
-    const listModel = useListModel<T, S>(
-        externalModel === undefined ? { items: props.items ?? undefined } : { model: externalModel },
-    );
+    const syncKnownSelection = useEffectEvent((position: number): void => {
+        const effectiveId = collection.idAt(position);
 
-    const useHeader = externalModel === undefined && typeof props.renderHeader === "function";
+        if (effectiveId === null) {
+            known.current = null;
 
-    const face = useRealizedSlots<DropDownWidget>({ target: widgetRef, binding: itemFactoryBinding });
-    const popup = useRealizedSlots<DropDownWidget>({ target: widgetRef, binding: listFactoryBinding });
-    const header = useRealizedSlots<DropDownWidget>({
-        target: useHeader ? widgetRef : null,
-        binding: headerFactoryBinding,
+            return;
+        }
+
+        const { onSelectionChanged } = options.props;
+        updateKnownSelection({ known, onSelectionChanged }, effectiveId, selectedId);
     });
 
-    useModelInstallation(widgetRef, listModel.model, (widget, model) => widget.setModel(model));
+    useLayoutEffect(() => {
+        if (widget === null) {
+            return;
+        }
 
-    const selectedPosition = useDropDownSelection<T, S>({
-        widget,
-        resolver: listModel.resolver,
-        selectedId: props.selectedId,
-        onSelectionChanged: props.onSelectionChanged,
-    });
+        const position = resolvePosition(widget, collection, selectedId);
+        applySelectedPosition(widget, position, applying);
+        syncKnownSelection(position);
+    }, [widget, collection, selectedId, applying]);
 
-    const controlledPosition =
-        props.selectedId === undefined || props.selectedId === null
-            ? -1
-            : listModel.resolver.positionOf(props.selectedId);
-    const facePosition = controlledPosition >= 0 ? controlledPosition : selectedPosition < 0 ? 0 : selectedPosition;
-
-    return {
-        setRef,
-        resolver: listModel.resolver,
-        faceResolver: createFaceResolver(listModel.resolver, facePosition),
-        headerResolver: listModel.headerResolver,
-        faceStore: face.store,
-        popupStore: popup.store,
-        headerStore: header.store,
-        useHeader,
-    };
+    useSignal(widget, "notify::selected", (): void => {
+        reportSelectedNotify(options, { known, onSelectionChanged: options.props.onSelectionChanged }, applying);
+    });
 };
 
-const DropDownImpl = <T, S, W extends DropDownWidget>(props: DropDownImplProps<T, S, W>): ReactNode => {
-    const { setRef, resolver, faceResolver, headerResolver, faceStore, popupStore, headerStore, useHeader } =
-        useDropDownWiring(props);
-    const intrinsic: ReactElement = createElement(props.element, { ...props.intrinsicProps, ref: setRef });
+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 (
         <>
-            {intrinsic}
-            <ListPortalHost store={faceStore} resolver={faceResolver} render={toItemRenderer<T, S>(props.renderItem)} />
-            <ListPortalHost
-                store={popupStore}
-                resolver={resolver}
-                render={toPopupRenderer<T, S>(props.renderListItem, props.renderItem)}
+            <Component
+                ref={refCallback}
+                model={collection.model}
+                factory={<GtkSignalListItemFactory {...faceCells.handlers} />}
+                {...(renderListItem != null && {
+                    listFactory: <GtkSignalListItemFactory {...listCells.handlers} />,
+                })}
+                {...(hasHeader && { headerFactory: <GtkSignalListItemFactory {...headerCells.handlers} /> })}
+                {...rest}
             />
-            {useHeader ? (
-                <ListPortalHost
-                    store={headerStore}
-                    resolver={headerResolver}
-                    render={toHeaderRenderer<T, S>(props.renderHeader)}
-                />
-            ) : null}
+            <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} />}
         </>
     );
-};
-
-type DropDownImplComponentProps<T, S, W extends DropDownWidget> = DropDownProps<T, S> & {
-    ref?: Ref<W | null> | undefined;
-};
-
-const extractDropDownProps = <T, S, W extends DropDownWidget>(
-    props: DropDownImplComponentProps<T, S, W>,
-): {
-    impl: Omit<DropDownImplProps<T, S, W>, "element" | "intrinsicProps">;
-    intrinsicProps: Record<string, unknown>;
-} => {
-    const {
-        ref,
-        items,
-        model,
-        renderItem,
-        renderListItem,
-        renderHeader,
-        selectedId,
-        onSelectionChanged,
-        ...intrinsicProps
-    } = props as DropDownProps<T, S> & {
-        ref?: Ref<W | null>;
-        [key: string]: unknown;
-    };
-
-    return {
-        impl: {
-            ref,
-            items: items as ListItem<T, S>[] | undefined,
-            model: model as Gio.ListModel | undefined,
-            renderItem: renderItem as ((value: T) => ReactNode) | null | undefined,
-            renderListItem: renderListItem as ((value: T) => ReactNode) | null | undefined,
-            renderHeader: renderHeader as ((value: S) => ReactNode) | null | undefined,
-            selectedId: selectedId as string | null | undefined,
-            onSelectionChanged: onSelectionChanged as ((id: string) => void) | null | undefined,
-        },
-        intrinsicProps: intrinsicProps as Record<string, unknown>,
-    };
-};
-
-/**
- * Props for the {@link DropDown} component: the raw `GtkDropDown` element
- * surface with its factory/model wiring replaced by the declarative
- * {@link DropDownProps} API.
- */
-export type DropDownComponentProps<T = unknown, S = unknown> = Omit<GtkDropDownProps, keyof DropDownProps<T, S>> &
-    DropDownProps<T, S>;
-
-/**
- * Props for the {@link ComboRow} component: the raw `AdwComboRow` element
- * surface with its factory/model wiring replaced by the declarative
- * {@link DropDownProps} API.
- */
-export type ComboRowComponentProps<T = unknown, S = unknown> = Omit<AdwComboRowProps, keyof DropDownProps<T, S>> &
-    DropDownProps<T, S>;
-
-/**
- * A `GtkDropDown` driven by a declarative `items` model with a controlled
- * `selectedId` and per-slot renderers for the selected face, the popup list,
- * and section headers. Supplying an external `model` switches to the
- * uncontrolled form.
- */
-export const DropDown = <T = unknown, S = unknown>(props: DropDownComponentProps<T, S>): ReactNode => {
-    const { impl, intrinsicProps } = extractDropDownProps<T, S, Gtk.DropDown>(props);
-    return <DropDownImpl<T, S, Gtk.DropDown> element={GtkDropDown} intrinsicProps={intrinsicProps} {...impl} />;
-};
+}
 
-/**
- * An `AdwComboRow` driven by a declarative `items` model with a controlled
- * `selectedId` and per-slot renderers for the selected face, the popup list,
- * and section headers. Supplying an external `model` switches to the
- * uncontrolled form.
- */
-export const ComboRow = <T = unknown, S = unknown>(props: ComboRowComponentProps<T, S>): ReactNode => {
-    const { impl, intrinsicProps } = extractDropDownProps<T, S, Adw.ComboRow>(props);
-    return <DropDownImpl<T, S, Adw.ComboRow> element={AdwComboRow} intrinsicProps={intrinsicProps} {...impl} />;
-};
+export { DropDown };

package/src/grid-view.tsx

@@ -1,73 +1,37 @@
-import type * as Gio from "@gtkx/gi/gio";
-import type * as Gtk from "@gtkx/gi/gtk";
-import { GtkGridView, type GtkGridViewProps } from "@gtkx/jsx/gtk";
-import type { ReactNode, Ref } from "react";
-import { CollectionView, type ModelBinding } from "./collection-view.js";
-import type { SlotRenderer } from "./list-slot.js";
+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 factoryBinding = {
-    install: (widget: Gtk.GridView, factory: Gtk.SignalListItemFactory) => widget.setFactory(factory),
-    uninstall: (widget: Gtk.GridView) => widget.setFactory(null),
-};
-
-const modelBinding: ModelBinding<Gtk.GridView> = {
-    install: (widget, model) => widget.setModel(model as Gtk.SelectionModel),
-};
-
-/**
- * Props for the {@link GridView} component: the raw `GtkGridView` element
- * surface with its factory/model wiring replaced by the declarative
- * {@link GridViewProps} API.
- */
-export type GridViewComponentProps<T = unknown> = Omit<GtkGridViewProps, keyof GridViewProps<T>> & GridViewProps<T>;
+const GRID_VIEW_PROPS = [
+    "items",
+    "renderItem",
+    "selectedIds",
+    "onSelectionChanged",
+    "selectionMode",
+    "estimatedItemHeight",
+    "estimatedItemWidth",
+] as const satisfies (keyof GridViewProps)[];
 
 /**
- * A `GtkGridView` driven by a declarative `items`/`renderItem` API with
- * optional controlled selection. Supplying an external `model` switches to the
- * uncontrolled form.
+ * 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: GridViewComponentProps<T>): ReactNode => {
-    const {
-        ref,
-        items,
-        model,
-        renderItem,
-        selected,
-        selectionMode,
-        onSelectionChanged,
-        estimatedItemHeight,
-        estimatedItemWidth,
-        ...intrinsicProps
-    } = props as GridViewProps<T> & {
-        ref?: Ref<Gtk.GridView | null>;
-        estimatedItemHeight?: number;
-        estimatedItemWidth?: number;
-        [key: string]: unknown;
-    };
-
-    const renderItemFn = renderItem as (item: T) => ReactNode;
-    const slotRenderer: SlotRenderer<T, unknown> = (value, _treeRow, isHeader) =>
-        isHeader ? null : renderItemFn(value as T);
+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 (
-        <CollectionView<T, unknown, Gtk.GridView>
-            element={GtkGridView}
-            intrinsicProps={intrinsicProps}
-            ref={ref}
-            items={model === undefined ? items : undefined}
-            model={model as Gio.ListModel | undefined}
-            renderItem={slotRenderer}
-            autoexpand={undefined}
-            renderHeader={undefined}
-            estimatedHeight={estimatedItemHeight}
-            estimatedWidth={estimatedItemWidth}
-            selected={selected}
-            selectionMode={selectionMode}
-            onSelectionChanged={onSelectionChanged}
-            factoryBinding={factoryBinding}
-            headerFactoryBinding={undefined}
-            modelBinding={modelBinding}
-        />
+        <>
+            <GtkGridView model={selection} factory={<GtkSignalListItemFactory {...itemCells.handlers} />} {...rest} />
+            <ItemPortals store={itemCells} render={renderItem} collection={collection} />
+        </>
     );
-};
+}
+
+export { GridView };

package/src/index.ts

@@ -1,31 +1,22 @@
-/**
- * Higher-level GTKX components: declarative, opinionated abstractions layered on
- * top of the generated `@gtkx/jsx` element bindings and the `@gtkx/react`
- * runtime. Each component pairs a GObject widget with a gtkx-authored prop
- * surface (item models, render callbacks, selection, sorting) and is exported
- * under an unprefixed name to distinguish it from the raw `Gtk*`/`Adw*`/`G*`
- * intrinsic element it builds upon.
- *
- * @packageDocumentation
- */
-
-export { ColumnView, type ColumnViewComponentProps } from "./column-view.js";
-export { ColumnViewColumn, type ColumnViewColumnComponentProps } from "./column-view-column.js";
-export { ConstraintLayout, type ConstraintLayoutProps } from "./constraint-layout.js";
-export { ComboRow, type ComboRowComponentProps, DropDown, type DropDownComponentProps } from "./drop-down.js";
-export { GridView, type GridViewComponentProps } from "./grid-view.js";
-export { ListView, type ListViewComponentProps } from "./list-view.js";
-export { Menu, type MenuProps } from "./menu.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 {
-    ColumnViewColumnProps,
+    ChildProps,
+    Column,
     ColumnViewProps,
-    ConstraintGuideProps,
-    ConstraintProps,
-    ConstraintVflProps,
     DropDownProps,
     GridViewProps,
-    ListItem,
+    HeaderRenderer,
+    Item,
+    ItemRenderer,
     ListViewProps,
-    MenuEntry,
-    MenuItemsProps,
+    RenderHeaderArgs,
+    RenderItemArgs,
+    Section,
+    SizeGroupChildProps,
+    SizeGroupProps,
+    WidgetProps,
 } from "./types.js";