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

package/src/drop-down.tsx

@@ -1,205 +1,19 @@
-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",
-];
+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/index.ts

@@ -18,5 +18,4 @@ export type {
     Section,
     SizeGroupChildProps,
     SizeGroupProps,
-    WidgetProps,
 } from "./types.js";

package/src/internal/drop-down.tsx

@@ -0,0 +1,186 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import type { ElementType, ReactNode, Ref } from "react";
+import { GtkLabel, GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
+import { applyWrite } from "@gtkx/react/internal";
+import { omit } from "@gtkx/utils";
+import { useEffectEvent, useLayoutEffect, useRef } from "react";
+import type { DropDownOwnProps, ItemRenderer, RenderItemArgs } from "../types.js";
+import type { Collection } from "./collection.js";
+import { HeaderPortals, ItemPortals, useHeaderCells, useItemCells } from "./cells.js";
+import { useCollectionData } from "./use-collection.js";
+import { useWidgetRef } from "./use-widget-ref.js";
+
+type SelectableWidget = GObject.Object & { getSelected: () => number; selected: number };
+
+type DropDownBaseProps = DropDownOwnProps<unknown, unknown> & {
+    onNotifySelected?: ((value: number | null, self: SelectableWidget) => void) | null | undefined;
+    ref?: Ref<SelectableWidget | null> | undefined;
+} & Record<string, unknown>;
+
+type SelectionOptions = {
+    widget: SelectableWidget | null;
+    collection: Collection;
+    props: DropDownBaseProps;
+};
+
+type NotifySelectedHandler = NonNullable<DropDownBaseProps["onNotifySelected"]>;
+
+type KnownSelection = {
+    known: { current: string | null };
+    onSelectionChanged: ((id: string) => void) | null | undefined;
+};
+
+const DROP_DOWN_PROPS: string[] = [
+    "component",
+    "items",
+    "sections",
+    "selectedId",
+    "onSelectionChanged",
+    "onNotifySelected",
+    "renderItem",
+    "renderListItem",
+    "renderHeader",
+    "ref",
+];
+
+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: DropDownBaseProps): ItemRenderer<never> => props.renderItem ?? defaultRenderItem;
+
+const listRenderer = (props: DropDownBaseProps): 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): void => {
+    const { widget, collection } = options;
+
+    if (widget === null) {
+        return;
+    }
+
+    reportKnownSelection(tracker, collection.idAt(widget.getSelected()));
+};
+
+const applySelectedPosition = (widget: SelectableWidget, position: number): void => {
+    applyWrite(() => {
+        widget.selected = position;
+    });
+};
+
+const useDropDownSelection = (options: SelectionOptions): NotifySelectedHandler => {
+    const { widget, collection } = 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);
+        syncKnownSelection(position);
+    }, [widget, collection, selectedId]);
+
+    return (value, self) => {
+        reportSelectedNotify(options, { known, onSelectionChanged: options.props.onSelectionChanged });
+        options.props.onNotifySelected?.(value, self);
+    };
+};
+
+function DropDownBase(props: DropDownBaseProps & { component: ElementType }): ReactNode {
+    const { component: Component, items, sections, renderListItem, renderHeader, ref } = props;
+    const rest = omit(props, DROP_DOWN_PROPS);
+    const [widget, refCallback] = useWidgetRef<SelectableWidget>(ref);
+    const collection = useCollectionData({ items, sections });
+    const faceCells = useItemCells({ width: -1, height: -1 });
+    const listCells = useItemCells({ width: -1, height: -1 });
+    const headerCells = useHeaderCells({ width: -1, height: -1 });
+    const handleNotifySelected = useDropDownSelection({ widget, collection, props });
+    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}
+                onNotifySelected={handleNotifySelected}
+            />
+            <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 { DropDownBase, type DropDownBaseProps };

package/src/internal/expansion.ts

@@ -1,6 +1,5 @@
 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";
@@ -102,7 +101,7 @@ function runControlledExpansion(
     report();
 }
 
-function useExpansion(options: ExpansionOptions): void {
+function useExpansion(options: ExpansionOptions): () => void {
     const { collection, expandedIds, onExpandedChange } = options;
     const [last] = useState<LastExpansion>(newLastExpansion);
     const expanding = useRef(false);
@@ -111,13 +110,13 @@ function useExpansion(options: ExpansionOptions): 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]);
+
+    return () => {
+        reportWhenIdle(collection, last, expanding, onExpandedChange);
+    };
 }
 
 export { useExpansion, type ExpansionOptions };

package/src/internal/selection.tsx

@@ -10,6 +10,7 @@ type SelectionOptions = {
     selectedIds?: string[] | null | undefined;
     onSelectionChanged?: ((ids: string[]) => void) | null | undefined;
     selectionMode?: Gtk.SelectionMode | null | undefined;
+    onItemsChanged: () => void;
 };
 
 type LastSelection = {
@@ -21,6 +22,7 @@ type SelectionElementProps = {
     ref: (value: Gtk.SelectionModel | null) => void;
     model: Gio.ListModel;
     onSelectionChanged: () => void;
+    onItemsChanged: () => void;
 };
 
 function getSelectedIds(selection: Gtk.SelectionModel, collection: Collection): string[] {
@@ -153,6 +155,7 @@ function useSelection(options: SelectionOptions): ReactElement {
         onSelectionChanged: () => {
             reportSelection(selection, collection, last, onSelectionChanged);
         },
+        onItemsChanged: options.onItemsChanged,
     });
 }
 

package/src/internal/use-collection.tsx

@@ -1,8 +1,6 @@
-import type { ReactElement, RefObject } from "react";
+import type { ReactElement } 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";
@@ -14,7 +12,6 @@ type CollectionDataOptions = {
     items?: Item[] | undefined;
     sections?: Section[] | undefined;
     flat?: boolean | undefined;
-    applying?: RefObject<boolean> | undefined;
 };
 
 type CollectionOptions = CollectionDataOptions & SelectionProps & ExpansionProps;
@@ -24,44 +21,34 @@ type CollectionResult = {
     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 { items, sections, flat } = 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]);
+        gtk.sync(index);
+    }, [gtk, index]);
 
     return collection;
 }
 
 function useCollection(options: CollectionOptions): CollectionResult {
     const collection = useCollectionData(options);
-    useExpansion({ collection, expandedIds: options.expandedIds, onExpandedChange: options.onExpandedChange });
+
+    const onItemsChanged = useExpansion({
+        collection,
+        expandedIds: options.expandedIds,
+        onExpandedChange: options.onExpandedChange,
+    });
 
     const selection = useSelection({
         collection,
         selectedIds: options.selectedIds,
         onSelectionChanged: options.onSelectionChanged,
         selectionMode: options.selectionMode,
+        onItemsChanged,
     });
 
     return { collection, selection };

package/src/types.ts

@@ -2,7 +2,7 @@ import type * as Gtk from "@gtkx/gi/gtk";
 import type {
     GtkColumnViewColumnProps,
     GtkColumnViewProps,
-    GtkDropDown,
+    GtkDropDownProps,
     GtkGridViewProps,
     GtkListViewProps,
 } from "@gtkx/jsx/gtk";
@@ -13,11 +13,6 @@ type ChildProps<C extends ElementType> = {
     component: C;
 } & ComponentPropsWithRef<C>;
 
-/** Props of a component whose backing widget defaults to one type but can be swapped through `component`. */
-type WidgetProps<C extends ElementType, Own = unknown, ExtraOmit extends string = never> = Own & {
-    component?: C;
-} & Omit<ComponentPropsWithRef<C>, ExtraOmit | keyof Own>;
-
 /**
  * A single item in a collection model, identified by a stable id and holding an
  * arbitrary value. Nested items form a tree.
@@ -131,15 +126,18 @@ type DropDownOwnProps<T, S> = SourceProps<T, S> & {
     renderHeader?: HeaderRenderer<S> | null | undefined;
 };
 
+type DropDownWidgetProps<Widget, T, S> = Omit<
+    Widget,
+    "model" | "factory" | "listFactory" | "headerFactory" | keyof DropDownOwnProps<T, S>
+> &
+DropDownOwnProps<T, S>;
+
 /**
- * Props for {@link DropDown}. The backing widget is chosen through the `component` prop, defaulting to
- * GtkDropDown, and its own props combine with the declarative collection props.
+ * Props for {@link DropDown}. Combines the underlying Gtk.DropDown props with the declarative
+ * collection props: flat items or grouped sections, controlled single selection, and renderers
+ * for the collapsed display, popup rows, and popup section headers.
  */
-type DropDownProps<T = unknown, S = unknown, C extends ElementType = typeof GtkDropDown> = WidgetProps<
-    C,
-    DropDownOwnProps<T, S>,
-    "model" | "factory" | "listFactory" | "headerFactory"
->;
+type DropDownProps<T = unknown, S = unknown> = DropDownWidgetProps<GtkDropDownProps, T, S>;
 
 type GridViewOwnProps<T> = ItemSizeProps &
     SelectionProps & {
@@ -190,7 +188,8 @@ export {
     type SelectionProps,
     type ExpansionProps,
     type ChildProps,
-    type WidgetProps,
+    type DropDownOwnProps,
+    type DropDownWidgetProps,
     type Item,
     type Section,
     type RenderItemArgs,