@gtkx/components 0.21.0 → 1.0.0-rc.1

package/src/list-view.tsx

@@ -1,85 +1,148 @@
-import type * as Gio from "@gtkx/gi/gio";
 import type * as Gtk from "@gtkx/gi/gtk";
 import { GtkListView, type GtkListViewProps } 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 { ListViewProps } from "./types.js";
+import {
+    type CellRenderer,
+    CellRenderHost,
+    createTreeRenderContext,
+    HeaderRenderHost,
+    itemRenderer,
+    type TreeRenderContext,
+} from "./cell.js";
+import { makeFactoryInstaller, useCellContainers } from "./hooks/use-cell-containers.js";
+import { useCollectionWidget } from "./hooks/use-collection-widget.js";
+import type {
+    CollectionItemSizeProps,
+    ControlledExpansionProps,
+    ControlledSelectionProps,
+    ItemNode,
+    RenderItemProps,
+    SectionNode,
+} from "./types.js";
+import type { CellContainerStore } from "./utils/cell-container-store.js";
+import type { ItemResolver } from "./utils/item-resolver.js";
 
-const factoryBinding = {
-    install: (widget: Gtk.ListView, factory: Gtk.SignalListItemFactory) => widget.setFactory(factory),
-    uninstall: (widget: Gtk.ListView) => widget.setFactory(null),
-};
+const factoryInstaller = makeFactoryInstaller<Gtk.ListView>((widget, factory) => widget.setFactory(factory));
 
-const headerFactoryBinding = {
-    install: (widget: Gtk.ListView, factory: Gtk.SignalListItemFactory) => widget.setHeaderFactory(factory),
-    uninstall: (widget: Gtk.ListView) => widget.setHeaderFactory(null),
-};
+const headerFactoryInstaller = makeFactoryInstaller<Gtk.ListView>((widget, factory) =>
+    widget.setHeaderFactory(factory),
+);
 
-const modelBinding: ModelBinding<Gtk.ListView> = {
-    install: (widget, model) => widget.setModel(model as Gtk.SelectionModel),
-};
+export type ListViewDeclarativeProps<T = unknown, S = unknown> = CollectionItemSizeProps &
+    ControlledSelectionProps &
+    ControlledExpansionProps & {
+        items?: ItemNode<T>[] | undefined;
+        sections?: SectionNode<S, T>[] | undefined;
+        renderItem: (props: RenderItemProps<T>) => ReactNode;
+        renderHeader?: ((info: { section: S }) => ReactNode) | null | undefined;
+    };
 
 /**
- * Props for the {@link ListView} component: the raw `GtkListView` element
- * surface with its factory/model wiring replaced by the declarative
- * {@link ListViewProps} API.
+ * Props for {@link ListView}. Combines the underlying Gtk.ListView props with
+ * declarative collection props: flat items or grouped sections, a per-row renderItem,
+ * an optional section header renderer, controlled selection and expansion, and
+ * estimated item sizing.
  */
-export type ListViewComponentProps<T = unknown, S = unknown> = Omit<GtkListViewProps, keyof ListViewProps<T, S>> &
-    ListViewProps<T, S>;
+export type ListViewProps<T = unknown, S = unknown> = Omit<
+    GtkListViewProps,
+    "model" | "factory" | "headerFactory" | keyof ListViewDeclarativeProps<T, S>
+> &
+    ListViewDeclarativeProps<T, S>;
+
+interface ListViewWiring<T, S> {
+    setRef: (value: Gtk.ListView | null) => void;
+    resolver: ItemResolver<T, S>;
+    headerResolver: ItemResolver<T, S>;
+    itemStore: CellContainerStore;
+    headerStore: CellContainerStore;
+    useHeader: boolean;
+    rowId: (row: Gtk.TreeListRow) => string | undefined;
+}
+
+const useListViewWiring = <T, S>(props: NormalizedListViewProps<T, S>): ListViewWiring<T, S> => {
+    const { widgetRef, setRef, collection } = useCollectionWidget<Gtk.ListView, T, S>(props);
+
+    const useHeader = collection.useHeader;
+
+    const itemStore = useCellContainers<Gtk.ListView>({
+        object: widgetRef,
+        installer: factoryInstaller,
+        estimatedHeight: props.estimatedItemHeight,
+        estimatedWidth: props.estimatedItemWidth,
+    });
+    const headerStore = useCellContainers<Gtk.ListView>({
+        object: useHeader ? widgetRef : null,
+        installer: headerFactoryInstaller,
+        estimatedHeight: props.estimatedItemHeight,
+        estimatedWidth: props.estimatedItemWidth,
+    });
+
+    return {
+        setRef,
+        resolver: collection.resolver,
+        headerResolver: collection.headerResolver,
+        itemStore,
+        headerStore,
+        useHeader,
+        rowId: collection.rowId,
+    };
+};
+
+type NormalizedListViewProps<T, S> = ListViewDeclarativeProps<T, S> & {
+    ref?: Ref<Gtk.ListView | null>;
+    estimatedItemHeight?: number;
+    estimatedItemWidth?: number;
+    [key: string]: unknown;
+};
 
 /**
- * A `GtkListView` driven by a declarative `items`/`renderItem` API with
- * optional controlled selection, section headers, and tree autoexpansion.
- * Supplying an external `model` switches to the uncontrolled form.
+ * Renders a Gtk.ListView: a scrollable, single-column list backed by a collection
+ * model, with each row drawn by renderItem and optional section headers.
  */
-export const ListView = <T = unknown, S = unknown>(props: ListViewComponentProps<T, S>): ReactNode => {
+export const ListView = <T = unknown, S = unknown>(props: ListViewProps<T, S>): ReactNode => {
     const {
         ref,
         items,
-        model,
+        sections,
         renderItem,
-        autoexpand,
         renderHeader,
-        selected,
+        selectedIds,
         selectionMode,
         onSelectionChanged,
+        expandedIds,
+        onExpandedChange,
         estimatedItemHeight,
         estimatedItemWidth,
         ...intrinsicProps
-    } = props as ListViewProps<T, S> & {
-        ref?: Ref<Gtk.ListView | null>;
-        estimatedItemHeight?: number;
-        estimatedItemWidth?: number;
-        [key: string]: unknown;
-    };
+    } = props as NormalizedListViewProps<T, S>;
 
-    const renderItemFn = renderItem as (item: T, row?: Gtk.TreeListRow | null) => ReactNode;
-    const slotRenderer: SlotRenderer<T, S> = (value, treeRow, isHeader) => {
-        if (isHeader) return null;
-        return treeRow === null ? renderItemFn(value as T) : renderItemFn(value as T, treeRow);
-    };
+    const wiring = useListViewWiring<T, S>({
+        ref,
+        items,
+        sections,
+        renderHeader,
+        selectedIds,
+        selectionMode,
+        onSelectionChanged,
+        expandedIds,
+        onExpandedChange,
+        estimatedItemHeight,
+        estimatedItemWidth,
+    } as NormalizedListViewProps<T, S>);
 
-    const useHeader = model === undefined && typeof renderHeader === "function";
+    const treeContext: TreeRenderContext = createTreeRenderContext(expandedIds, wiring.rowId);
+    const cellRenderer: CellRenderer<T, S> = itemRenderer<T, S>(renderItem, treeContext);
 
     return (
-        <CollectionView<T, S, Gtk.ListView>
-            element={GtkListView}
-            intrinsicProps={intrinsicProps}
-            ref={ref}
-            items={model === undefined ? items : undefined}
-            model={model as Gio.ListModel | undefined}
-            renderItem={slotRenderer}
-            autoexpand={autoexpand}
-            renderHeader={useHeader ? (value) => renderHeader?.(value as S) ?? null : undefined}
-            estimatedHeight={estimatedItemHeight}
-            estimatedWidth={estimatedItemWidth}
-            selected={selected}
-            selectionMode={selectionMode}
-            onSelectionChanged={onSelectionChanged}
-            factoryBinding={factoryBinding}
-            headerFactoryBinding={useHeader ? headerFactoryBinding : undefined}
-            modelBinding={modelBinding}
-        />
+        <>
+            <GtkListView {...intrinsicProps} ref={wiring.setRef} />
+            <CellRenderHost store={wiring.itemStore} resolver={wiring.resolver} render={cellRenderer} />
+            <HeaderRenderHost
+                useHeader={wiring.useHeader}
+                store={wiring.headerStore}
+                resolver={wiring.headerResolver}
+                renderHeader={renderHeader}
+            />
+        </>
     );
 };

package/src/menu.tsx

@@ -1,24 +1,22 @@
 import type * as Gio from "@gtkx/gi/gio";
 import { GMenu, type GMenuProps } from "@gtkx/jsx/gio";
-import { useForwardedRef } from "@gtkx/react";
-import { createElement, type ReactNode, type Ref, useLayoutEffect, useRef } from "react";
+import { useMergeRefs } from "@gtkx/react/internal";
+import { type ReactNode, type Ref, useLayoutEffect, useRef } from "react";
 import { applyMenuItems, menuItemsEqual } from "./menu-items.js";
-import type { MenuEntry, MenuItemsProps } from "./types.js";
+import type { MenuEntry } from "./types.js";
 
-/**
- * Props for the {@link Menu} component: the raw `GMenu` element surface with a
- * declarative `items` model layered on top.
- */
+export type MenuItemsProps = {
+    items?: MenuEntry[] | null | undefined;
+};
+
+/** Props for {@link Menu}, combining Gio.Menu props with a declarative items array. */
 export type MenuProps = Omit<GMenuProps, keyof MenuItemsProps> & MenuItemsProps & { ref?: Ref<Gio.Menu | null> };
 
-/**
- * A declarative `Gio.Menu` built from an `items` tree of {@link MenuEntry}
- * values. Rebuilds the underlying menu model whenever the item structure
- * changes.
- */
+/** Builds a Gio.Menu model from a declarative array of {@link MenuEntry} items. */
 export const Menu = (props: MenuProps): ReactNode => {
     const { items, ref, ...rest } = props;
-    const [menuRef, mergedRef] = useForwardedRef(ref);
+    const menuRef = useRef<Gio.Menu | null>(null);
+    const mergedRef = useMergeRefs(ref, menuRef);
     const appliedRef = useRef<MenuEntry[] | null>(null);
 
     useLayoutEffect(() => {
@@ -30,5 +28,5 @@ export const Menu = (props: MenuProps): ReactNode => {
         applyMenuItems(menu, entries);
     });
 
-    return createElement(GMenu, { ...rest, ref: mergedRef });
+    return <GMenu {...rest} ref={mergedRef} />;
 };

package/src/overlay.tsx

@@ -0,0 +1,88 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { GtkOverlay, type GtkOverlayProps } from "@gtkx/jsx/gtk";
+import { useMergeRefs } from "@gtkx/react/internal";
+import { Children, type ElementType, isValidElement, type ReactNode, type Ref, useRef } from "react";
+import { createParentContext, usePlacedChild } from "./hooks/use-placed-child.js";
+import type { ChildProps } from "./types.js";
+
+const { Context: OverlayContext, useParentRef: useOverlayRef } = createParentContext<Gtk.Overlay>(
+    "<Overlay.Child> must be a child of <Overlay>",
+);
+
+/** Props for {@link Overlay}. */
+export type OverlayProps = GtkOverlayProps & { ref?: Ref<Gtk.Overlay | null> };
+
+export type OverlayPlacementProps = {
+    /** Whether this overlay contributes to the Overlay's measured size. */
+    measure?: boolean | null | undefined;
+    /** Whether the overlay is clipped to the main child's allocation. */
+    clipOverlay?: boolean | null | undefined;
+};
+
+/** Adds a single widget as an overlay on top of an {@link Overlay}'s main child. */
+export type OverlayChildProps<C extends ElementType> = ChildProps<C, OverlayPlacementProps>;
+
+type OverlayPlacement = { measure: boolean; clipOverlay: boolean };
+
+const placementOf = (props: OverlayPlacementProps): OverlayPlacement => ({
+    measure: props.measure ?? false,
+    clipOverlay: props.clipOverlay ?? false,
+});
+
+const samePlacement = (a: OverlayPlacement, b: OverlayPlacement): boolean =>
+    a.measure === b.measure && a.clipOverlay === b.clipOverlay;
+
+const OverlayChild = <C extends ElementType>({
+    component,
+    measure,
+    clipOverlay,
+    ref,
+    ...rest
+}: OverlayChildProps<C>): ReactNode => {
+    const overlayRef = useOverlayRef();
+    const Component: ElementType = component;
+    return usePlacedChild<Gtk.Widget, OverlayPlacement>({
+        render: (placeRef) => <Component {...rest} ref={placeRef} />,
+        ref,
+        placement: placementOf({ measure, clipOverlay }),
+        samePlacement,
+        place: (widget, placement) => {
+            const overlay = overlayRef.current;
+            if (!overlay) return;
+            if (widget.getParent() !== overlay) overlay.addOverlay(widget);
+            overlay.setMeasureOverlay(widget, placement.measure);
+            overlay.setClipOverlay(widget, placement.clipOverlay);
+        },
+        release: (widget) => {
+            const overlay = overlayRef.current;
+            if (overlay && widget.getParent() === overlay) overlay.removeOverlay(widget);
+        },
+    });
+};
+
+const isOverlayChild = (node: ReactNode): boolean => isValidElement(node) && node.type === OverlayChild;
+
+/**
+ * Renders a Gtk.Overlay: a main child with one or more widgets stacked on top,
+ * declared via {@link Overlay.Child}. Non-Child children form the main content.
+ */
+export const Overlay: ((props: OverlayProps) => ReactNode) & {
+    Child: <C extends ElementType>(props: OverlayChildProps<C>) => ReactNode;
+} = Object.assign(
+    ({ children, ref, ...rest }: OverlayProps): ReactNode => {
+        const overlayRef = useRef<Gtk.Overlay | null>(null);
+        const mergedRef = useMergeRefs<Gtk.Overlay>(ref, overlayRef);
+        const items = Children.toArray(children);
+        const overlays = items.filter(isOverlayChild);
+        const base = items.filter((node) => !isOverlayChild(node));
+        return (
+            <>
+                <GtkOverlay {...rest} ref={mergedRef}>
+                    {base}
+                </GtkOverlay>
+                <OverlayContext.Provider value={overlayRef}>{overlays}</OverlayContext.Provider>
+            </>
+        );
+    },
+    { Child: OverlayChild },
+);

package/src/size-group.tsx

@@ -0,0 +1,96 @@
+import type * as Gtk from "@gtkx/gi/gtk";
+import { GtkSizeGroup } from "@gtkx/jsx/gtk";
+import { useMergeRefs } from "@gtkx/react/internal";
+import {
+    createContext,
+    type ElementType,
+    type ReactNode,
+    type Ref,
+    type RefCallback,
+    useCallback,
+    useContext,
+    useRef,
+} from "react";
+import type { ChildProps } from "./types.js";
+
+type SizeGroupRegistry = {
+    addWidget: (widget: Gtk.Widget) => void;
+    removeWidget: (widget: Gtk.Widget) => void;
+    setGroup: (group: Gtk.SizeGroup | null) => void;
+};
+
+const SizeGroupContext = createContext<SizeGroupRegistry | null>(null);
+
+const useSizeGroupRegistry = (): SizeGroupRegistry => {
+    const registry = useContext(SizeGroupContext);
+    if (!registry) throw new Error("<SizeGroup.Child> must be a child of <SizeGroup>");
+    return registry;
+};
+
+/** Props for {@link SizeGroup}. */
+export type SizeGroupProps = {
+    /** How the group equalizes sizes: horizontal, vertical, or both. */
+    mode?: Gtk.SizeGroupMode | null | undefined;
+    ref?: Ref<Gtk.SizeGroup | null>;
+    children?: ReactNode;
+};
+
+/** Adds a single widget, rendered by the given component, to the enclosing {@link SizeGroup}. */
+export type SizeGroupChildProps<C extends ElementType> = ChildProps<C>;
+
+const SizeGroupChild = <C extends ElementType>({ component, ref, ...rest }: SizeGroupChildProps<C>): ReactNode => {
+    const registry = useSizeGroupRegistry();
+    const joinGroup = useCallback<RefCallback<Gtk.Widget>>(
+        (widget) => {
+            if (widget === null) return;
+            registry.addWidget(widget);
+            return () => registry.removeWidget(widget);
+        },
+        [registry],
+    );
+    const Component: ElementType = component;
+    const setWidget = useMergeRefs<Gtk.Widget>(ref, joinGroup);
+    return <Component {...rest} ref={setWidget} />;
+};
+
+const createRegistry = (): SizeGroupRegistry => {
+    const members = new Set<Gtk.Widget>();
+    let group: Gtk.SizeGroup | null = null;
+    return {
+        addWidget: (widget) => {
+            members.add(widget);
+            group?.addWidget(widget);
+        },
+        removeWidget: (widget) => {
+            members.delete(widget);
+            group?.removeWidget(widget);
+        },
+        setGroup: (next) => {
+            group = next;
+            if (next) for (const member of members) next.addWidget(member);
+        },
+    };
+};
+
+/**
+ * Creates a Gtk.SizeGroup that keeps its member widgets at a common size. Members join the group
+ * through {@link SizeGroup.Child}.
+ */
+export const SizeGroup: ((props: SizeGroupProps) => ReactNode) & {
+    Child: <C extends ElementType>(props: SizeGroupChildProps<C>) => ReactNode;
+} = Object.assign(
+    ({ mode, ref, children }: SizeGroupProps): ReactNode => {
+        const registryRef = useRef<SizeGroupRegistry | null>(null);
+        if (registryRef.current === null) registryRef.current = createRegistry();
+        const registry = registryRef.current;
+        const setGroup = useCallback<RefCallback<Gtk.SizeGroup>>((group) => registry.setGroup(group), [registry]);
+        const mergedRef = useMergeRefs<Gtk.SizeGroup>(ref, setGroup);
+        return (
+            <>
+                <GtkSizeGroup ref={mergedRef} mode={mode} />
+                <SizeGroupContext.Provider value={registry}>{children}</SizeGroupContext.Provider>
+            </>
+        );
+    },
+    { Child: SizeGroupChild },
+);