@gtkx/components 0.21.0

package/src/constraint-layout-apply.ts

@@ -0,0 +1,121 @@
+import * as GObject from "@gtkx/gi/gobject";
+import * as Gtk from "@gtkx/gi/gtk";
+import type { ConstraintGuideProps, ConstraintProps, ConstraintVflProps } from "./types.js";
+
+const SUPER_ID = "super";
+
+const unknownIdMessage = (role: string, id: string): string =>
+    `<ConstraintLayout.Constraint> references unknown id '${id}'. ` +
+    `Set name="${id}" on the ${role} widget, or add a <ConstraintLayout.Guide id="${id}">.`;
+
+const guideRegistry = new WeakMap<Gtk.ConstraintLayout, Map<string, Gtk.ConstraintGuide>>();
+
+const guidesFor = (layout: Gtk.ConstraintLayout): Map<string, Gtk.ConstraintGuide> => {
+    let map = guideRegistry.get(layout);
+    if (!map) {
+        map = new Map<string, Gtk.ConstraintGuide>();
+        guideRegistry.set(layout, map);
+    }
+    return map;
+};
+
+const explicitWidgetName = (widget: Gtk.Widget): string | null => {
+    const value = new GObject.Value();
+    value.init(GObject.TYPE_STRING);
+    widget.getProperty("name", value);
+    const name = value.getString();
+    return name !== null && name.length > 0 ? name : null;
+};
+
+function* namedChildren(layout: Gtk.ConstraintLayout): Generator<[string, Gtk.Widget]> {
+    const host = layout.getWidget();
+    if (!host) return;
+    for (let child = host.getFirstChild(); child; child = child.getNextSibling()) {
+        const name = explicitWidgetName(child);
+        if (name !== null) yield [name, child];
+    }
+}
+
+const findChildByName = (layout: Gtk.ConstraintLayout, id: string): Gtk.Widget | undefined => {
+    for (const [name, child] of namedChildren(layout)) {
+        if (name === id) return child;
+    }
+    return undefined;
+};
+
+const resolveConstraintTarget = (
+    layout: Gtk.ConstraintLayout,
+    id: string | undefined,
+): Gtk.ConstraintTarget | null | undefined => {
+    if (id === undefined || id === SUPER_ID) return null;
+    return findChildByName(layout, id) ?? guidesFor(layout).get(id);
+};
+
+const constraintViews = (layout: Gtk.ConstraintLayout): Map<string, Gtk.ConstraintTarget> => {
+    const views = new Map<string, Gtk.ConstraintTarget>();
+    for (const [name, child] of namedChildren(layout)) views.set(name, child);
+    for (const [name, guide] of guidesFor(layout)) {
+        if (!views.has(name)) views.set(name, guide);
+    }
+    return views;
+};
+
+const isLayoutLive = (layout: Gtk.ConstraintLayout): boolean => layout.getWidget() !== null;
+
+export function applyConstraint(layout: Gtk.ConstraintLayout, props: ConstraintProps): () => void {
+    const target = resolveConstraintTarget(layout, props.target);
+    if (target === undefined) throw new Error(unknownIdMessage("target", String(props.target)));
+    const source = resolveConstraintTarget(layout, props.source);
+    if (source === undefined) throw new Error(unknownIdMessage("source", String(props.source)));
+
+    const constraint = new Gtk.Constraint({
+        target,
+        targetAttribute: props.targetAttribute,
+        relation: props.relation ?? Gtk.ConstraintRelation.EQ,
+        source,
+        sourceAttribute: props.sourceAttribute ?? Gtk.ConstraintAttribute.NONE,
+        multiplier: props.multiplier ?? 1,
+        constant: props.constant ?? 0,
+        strength: props.strength ?? Gtk.ConstraintStrength.REQUIRED,
+    });
+    layout.addConstraint(constraint);
+
+    return () => {
+        if (isLayoutLive(layout)) layout.removeConstraint(constraint);
+    };
+}
+
+export function applyVfl(layout: Gtk.ConstraintLayout, props: ConstraintVflProps): () => void {
+    const views = constraintViews(layout);
+    const constraints = layout.addConstraintsFromDescription(
+        props.lines,
+        props.hspacing ?? 0,
+        props.vspacing ?? 0,
+        views,
+    );
+
+    return () => {
+        if (!isLayoutLive(layout)) return;
+        for (const constraint of constraints) layout.removeConstraint(constraint);
+    };
+}
+
+export function applyGuide(layout: Gtk.ConstraintLayout, props: ConstraintGuideProps): () => void {
+    const guide = new Gtk.ConstraintGuide({
+        name: props.id,
+        minWidth: props.minWidth,
+        minHeight: props.minHeight,
+        natWidth: props.natWidth,
+        natHeight: props.natHeight,
+        maxWidth: props.maxWidth,
+        maxHeight: props.maxHeight,
+        strength: props.strength,
+    });
+    layout.addGuide(guide);
+    guidesFor(layout).set(props.id, guide);
+
+    return () => {
+        guidesFor(layout).delete(props.id);
+        if (isLayoutLive(layout)) layout.removeGuide(guide);
+    };
+}

package/src/constraint-layout.tsx

@@ -0,0 +1,130 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { GtkConstraintLayout } from "@gtkx/jsx/gtk";
+import { useForwardedRef } from "@gtkx/react";
+import {
+    type Context,
+    createContext,
+    createElement,
+    type ReactNode,
+    type Ref,
+    type RefObject,
+    useCallback,
+    useContext,
+    useEffect,
+    useLayoutEffect,
+    useRef,
+} from "react";
+import { applyConstraint, applyGuide, applyVfl } from "./constraint-layout-apply.js";
+import type { ConstraintGuideProps, ConstraintProps, ConstraintVflProps } from "./types.js";
+
+const ORPHAN_MESSAGE = "<ConstraintLayout.Constraint> / <Guide> / <Vfl> must be a child of <ConstraintLayout>";
+
+const ConstraintLayoutContext: Context<RefObject<Gtk.ConstraintLayout | null> | null> =
+    createContext<RefObject<Gtk.ConstraintLayout | null> | null>(null);
+
+const useConstraintLayoutRef = (): RefObject<Gtk.ConstraintLayout | null> => {
+    const ref = useContext(ConstraintLayoutContext);
+    if (!ref) throw new Error(ORPHAN_MESSAGE);
+    return ref;
+};
+
+export type ConstraintLayoutProps = {
+    children?: ReactNode;
+    ref?: Ref<Gtk.ConstraintLayout | null>;
+};
+
+type ContributionCleanupRef = { current: (() => void) | null };
+
+const cleanupContribution = (cleanupRef: ContributionCleanupRef): void => {
+    const cleanup = cleanupRef.current;
+    if (!cleanup) return;
+    cleanupRef.current = null;
+    cleanup();
+};
+
+const useLayoutContribution = (apply: (layout: Gtk.ConstraintLayout) => () => void, deps: unknown[]): void => {
+    const layoutRef = useConstraintLayoutRef();
+    useLayoutEffect(() => {
+        const layout = layoutRef.current;
+        if (!layout) return;
+        return apply(layout);
+    }, deps);
+};
+
+const useDeferredContribution = (apply: (layout: Gtk.ConstraintLayout) => () => void, deps: unknown[]): void => {
+    const layoutRef = useConstraintLayoutRef();
+    const cleanupRef = useRef<(() => void) | null>(null);
+
+    useLayoutEffect(() => () => cleanupContribution(cleanupRef), deps);
+
+    useEffect(() => {
+        const layout = layoutRef.current;
+        if (!layout) return;
+        const cleanup = apply(layout);
+        cleanupRef.current = cleanup;
+        return () => {
+            if (cleanupRef.current === cleanup) cleanupContribution(cleanupRef);
+        };
+    }, deps);
+};
+
+export const ConstraintLayout: ((props: ConstraintLayoutProps) => ReactNode) & {
+    Guide: (props: ConstraintGuideProps) => ReactNode;
+    Constraint: (props: ConstraintProps) => ReactNode;
+    Vfl: (props: ConstraintVflProps) => ReactNode;
+} = Object.assign(
+    ({ children, ref }: ConstraintLayoutProps): ReactNode => {
+        const layoutRef = useRef<Gtk.ConstraintLayout | null>(null);
+        const captureLayout = useCallback(
+            (layout: Gtk.ConstraintLayout | null): void => {
+                layoutRef.current = layout;
+            },
+            [layoutRef],
+        );
+        const [, mergedRef] = useForwardedRef<Gtk.ConstraintLayout>(ref, captureLayout);
+        return (
+            <>
+                {createElement(GtkConstraintLayout, { ref: mergedRef })}
+                <ConstraintLayoutContext.Provider value={layoutRef}>{children}</ConstraintLayoutContext.Provider>
+            </>
+        );
+    },
+    {
+        Guide: (props: ConstraintGuideProps): ReactNode => {
+            useLayoutContribution(
+                (layout) => applyGuide(layout, props),
+                [
+                    props.id,
+                    props.minWidth,
+                    props.minHeight,
+                    props.natWidth,
+                    props.natHeight,
+                    props.maxWidth,
+                    props.maxHeight,
+                    props.strength,
+                ],
+            );
+            return null;
+        },
+        Constraint: (props: ConstraintProps): ReactNode => {
+            useDeferredContribution(
+                (layout) => applyConstraint(layout, props),
+                [
+                    props.target,
+                    props.targetAttribute,
+                    props.relation,
+                    props.source,
+                    props.sourceAttribute,
+                    props.multiplier,
+                    props.constant,
+                    props.strength,
+                ],
+            );
+            return null;
+        },
+        Vfl: (props: ConstraintVflProps): ReactNode => {
+            useDeferredContribution((layout) => applyVfl(layout, props), [props.lines, props.hspacing, props.vspacing]);
+            return null;
+        },
+    },
+);

package/src/contexts/column-view-context.ts

@@ -0,0 +1,28 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { type Context, createContext, type RefObject, useContext } from "react";
+import type { ItemResolver } from "../utils/item-resolver.js";
+
+export interface ColumnRegistration {
+    id: string;
+    column: Gtk.ColumnViewColumn;
+    sortable: boolean;
+}
+
+export interface ColumnViewContextValue {
+    columnView: RefObject<Gtk.ColumnView | null>;
+    resolver: ItemResolver<unknown, unknown>;
+    register(registration: ColumnRegistration): void;
+    unregister(id: string): void;
+}
+
+export const ColumnViewContext: Context<ColumnViewContextValue | null> = createContext<ColumnViewContextValue | null>(
+    null,
+);
+
+export const useColumnViewContext = (): ColumnViewContextValue => {
+    const context = useContext(ColumnViewContext);
+    if (context === null) {
+        throw new Error("<ColumnViewColumn> must be rendered inside a <ColumnView>.");
+    }
+    return context;
+};

package/src/drop-down.tsx

@@ -0,0 +1,259 @@
+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;
+}
+
+const itemFactoryBinding: FactoryBinding<DropDownWidget> = {
+    install: (widget, factory) => widget.setFactory(factory),
+    uninstall: (widget) => widget.setFactory(null),
+};
+
+const listFactoryBinding: FactoryBinding<DropDownWidget> = {
+    install: (widget, factory) => widget.setListFactory(factory),
+    uninstall: (widget) => widget.setListFactory(null),
+};
+
+const headerFactoryBinding: FactoryBinding<DropDownWidget> = {
+    install: (widget, factory) => widget.setHeaderFactory(factory),
+    uninstall: (widget) => widget.setHeaderFactory(null),
+};
+
+const defaultRenderer: SlotRenderer<unknown, unknown> = (value, _treeRow, isHeader) => {
+    if (isHeader || value === undefined || value === null) return null;
+    return createElement(GtkLabel, { label: String(value) });
+};
+
+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 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));
+};
+
+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 toHeaderRenderer = <T, S>(renderHeader: ((value: S) => ReactNode) | null | undefined): SlotRenderer<T, S> => {
+    if (typeof renderHeader !== "function") return () => null;
+    return (value) => renderHeader(value as S);
+};
+
+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 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 useHeader = externalModel === undefined && typeof props.renderHeader === "function";
+
+    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,
+    });
+
+    useModelInstallation(widgetRef, listModel.model, (widget, model) => widget.setModel(model));
+
+    const selectedPosition = useDropDownSelection<T, S>({
+        widget,
+        resolver: listModel.resolver,
+        selectedId: props.selectedId,
+        onSelectionChanged: props.onSelectionChanged,
+    });
+
+    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,
+    };
+};
+
+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 });
+
+    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)}
+            />
+            {useHeader ? (
+                <ListPortalHost
+                    store={headerStore}
+                    resolver={headerResolver}
+                    render={toHeaderRenderer<T, S>(props.renderHeader)}
+                />
+            ) : null}
+        </>
+    );
+};
+
+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} />;
+};

package/src/grid-view.tsx

@@ -0,0 +1,73 @@
+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 { GridViewProps } from "./types.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>;
+
+/**
+ * A `GtkGridView` driven by a declarative `items`/`renderItem` API with
+ * optional controlled selection. Supplying an external `model` switches to the
+ * uncontrolled form.
+ */
+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);
+
+    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}
+        />
+    );
+};

package/src/hooks/use-drop-down-selection.ts

@@ -0,0 +1,53 @@
+import type * as GObject from "@gtkx/gi/gobject";
+import { useSignal } from "@gtkx/react";
+import { type GObjectTarget, resolveGobjectTarget, useGObjectSnapshot } from "@gtkx/react/internal";
+import { useLayoutEffect, useRef } from "react";
+import type { ItemResolver } from "../utils/item-resolver.js";
+
+export interface DropDownSelectionTarget extends GObject.Object {
+    getSelected(): number;
+    setSelected(position: number): void;
+}
+
+export interface DropDownSelectionOptions<T, S> {
+    widget: GObjectTarget<DropDownSelectionTarget>;
+    resolver: ItemResolver<T, S>;
+    selectedId: string | null | undefined;
+    onSelectionChanged: ((id: string) => void) | null | undefined;
+}
+
+const GTK_INVALID_LIST_POSITION = 4294967295;
+
+const normalizeSelected = (position: number): number =>
+    position === GTK_INVALID_LIST_POSITION || position < 0 ? -1 : position;
+
+export const useDropDownSelection = <T, S>(options: DropDownSelectionOptions<T, S>): number => {
+    const { widget, resolver, selectedId, onSelectionChanged } = options;
+    const resolved = resolveGobjectTarget(widget);
+
+    const selectedPosition = useGObjectSnapshot(widget, "notify::selected", (target) =>
+        target === null ? -1 : normalizeSelected(target.getSelected()),
+    );
+
+    const resolverRef = useRef(resolver);
+    resolverRef.current = resolver;
+    const onSelectionChangedRef = useRef(onSelectionChanged);
+    onSelectionChangedRef.current = onSelectionChanged;
+
+    useLayoutEffect(() => {
+        if (resolved === null || selectedId === undefined || selectedId === null) return;
+        const position = resolverRef.current.positionOf(selectedId);
+        if (position < 0) return;
+        if (normalizeSelected(resolved.getSelected()) !== position) resolved.setSelected(position);
+    }, [resolved, selectedId, resolver]);
+
+    useSignal(widget, "notify::selected", () => {
+        if (resolved === null) return;
+        const position = normalizeSelected(resolved.getSelected());
+        if (position < 0) return;
+        const id = resolverRef.current.idOf(position);
+        if (id !== undefined) onSelectionChangedRef.current?.(id);
+    });
+
+    return selectedPosition;
+};