@gtkx/components 2.0.0-beta.11 → 2.0.0-beta.13

package/src/internal/use-collection.tsx

@@ -1,6 +1,7 @@
 import type * as Gtk from "@gtkx/gi/gtk";
 import type { ReactElement } from "react";
 import { GtkFlattenListModel } from "@gtkx/jsx/gtk";
+import { useLatestRef } from "@gtkx/react/internal";
 import { useLayoutEffect, useMemo, useState } from "react";
 import type { ExpansionProps, ListItem, ListSection, SelectionProps } from "../types.js";
 import type { Collection } from "./collection.js";
@@ -14,6 +15,7 @@ type CollectionDataOptions = {
     items?: ListItem[] | undefined;
     sections?: ListSection[] | undefined;
     isFlat?: boolean | undefined;
+    onSectionsFilled?: (() => void) | undefined;
 };
 
 type CollectionOptions = CollectionDataOptions & SelectionProps & ExpansionProps;
@@ -44,9 +46,13 @@ function useCollectionData(options: CollectionDataOptions): CollectionDataResult
         return gtkModel.clear;
     }, [gtkModel, root, model]);
 
+    const onSectionsFilled = useLatestRef(options.onSectionsFilled);
+
     useLayoutEffect(() => {
-        gtkModel.sync(index);
-    }, [gtkModel, index, root, model]);
+        gtkModel.sync(index, () => {
+            onSectionsFilled.current?.();
+        });
+    }, [gtkModel, index, root, model, onSectionsFilled]);
 
     return {
         collection,

package/src/list-item-factory.tsx

@@ -10,6 +10,7 @@ import { NativeItemPortals, useItemCells } from "./internal/cells.js";
  */
 function ListItemFactory<T extends GObject.Object>({
     renderItem,
+    rowProps,
     estimatedItemHeight = -1,
     estimatedItemWidth = -1,
 }: ListItemFactoryProps<T>): ReactNode {
@@ -19,7 +20,7 @@ function ListItemFactory<T extends GObject.Object>({
     return (
         <>
             <GtkSignalListItemFactory {...cells.handlers} />
-            <NativeItemPortals registry={cells} render={renderItem} size={size} />
+            <NativeItemPortals registry={cells} render={renderItem} rowProps={rowProps} size={size} />
         </>
     );
 }

package/src/list-view.tsx

@@ -1,9 +1,12 @@
+import type * as Gtk from "@gtkx/gi/gtk";
 import type { ReactNode } from "react";
 import { GtkListView, GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
 import { omit } from "@gtkx/utils";
 import type { ListViewProps } from "./types.js";
 import { ItemPortals, useItemCells, useSectionHeader } from "./internal/cells.js";
+import { showFirstHeader } from "./internal/first-header.js";
 import { useCollection } from "./internal/use-collection.js";
+import { useWidgetRef } from "./internal/use-widget-ref.js";
 
 const LIST_VIEW_PROPS = [
     "items",
@@ -11,6 +14,7 @@ const LIST_VIEW_PROPS = [
     "isFlat",
     "renderItem",
     "renderHeader",
+    "rowProps",
     "selectedIds",
     "onSelectionChanged",
     "selectionMode",
@@ -19,6 +23,7 @@ const LIST_VIEW_PROPS = [
     "expanderDescriptions",
     "estimatedItemHeight",
     "estimatedItemWidth",
+    "ref",
 ] as const satisfies (keyof ListViewProps)[];
 
 /**
@@ -26,17 +31,19 @@ const LIST_VIEW_PROPS = [
  * controlled selection, controlled tree expansion, and estimated item sizing.
  */
 function ListView<T = unknown, S = unknown>(props: ListViewProps<T, S>): ReactNode {
-    const { renderItem, renderHeader, expandedIds, expanderDescriptions } = props;
+    const { renderItem, renderHeader, rowProps, expandedIds, expanderDescriptions, ref } = props;
     const { estimatedItemHeight, estimatedItemWidth } = props;
     const rest = omit(props, LIST_VIEW_PROPS);
     const size = { width: estimatedItemWidth ?? -1, height: estimatedItemHeight ?? -1 };
-    const { collection, selection } = useCollection(props);
+    const [view, refCallback] = useWidgetRef<Gtk.ListView>(ref);
+    const { collection, selection } = useCollection({ ...props, onSectionsFilled: () => showFirstHeader(view) });
     const itemCells = useItemCells(size);
     const header = useSectionHeader(renderHeader, collection, size);
 
     return (
         <>
             <GtkListView
+                ref={refCallback}
                 model={selection}
                 factory={<GtkSignalListItemFactory {...itemCells.handlers} />}
                 {...header.factoryProps}
@@ -45,6 +52,7 @@ function ListView<T = unknown, S = unknown>(props: ListViewProps<T, S>): ReactNo
             <ItemPortals
                 registry={itemCells}
                 render={renderItem}
+                rowProps={rowProps}
                 collection={collection}
                 expandedIds={expandedIds}
                 expanderDescriptions={expanderDescriptions}

package/src/types.ts

@@ -17,7 +17,10 @@ import type { ReactNode, RefObject } from "react";
  * arbitrary value. Nested items form a tree.
  */
 type ListItem<T = unknown> = {
-    /** Stable identifier, unique across the collection, used to preserve identity across updates and selection. */
+    /**
+     * Stable identifier that names the item in selection and expansion, so keep it unique across the collection.
+     * A row keeps its component state while its id stays among the same siblings.
+     */
     id: string;
     /** Payload handed to the cell renderer as `ListItemRenderArgs.item`. */
     value: T;
@@ -45,7 +48,10 @@ type ListSection<S = unknown, T = unknown> = {
 type ListItemRenderArgs<T> = {
     /** Value of the `ListItem` being rendered. */
     item: T;
-    /** Position of the item in the flattened item list, which excludes section headers and collapsed tree rows. */
+    /**
+     * Position of the item in the flattened item list, which excludes section headers and collapsed tree rows.
+     * A drop-down popup filtered by `enableSearch` still passes this position, not the row's place in the results.
+     */
     index: number;
     /** Depth of the item within a tree, starting at zero for top-level items. */
     depth?: number | undefined;
@@ -54,9 +60,10 @@ type ListItemRenderArgs<T> = {
 };
 
 /**
- * Properties applied to the row that carries one item's cells. A Gtk.ColumnViewRow is not a widget, so
- * these are the only handles it offers; anything omitted falls back to the row's own default, which
- * leaves the accessibility strings unset rather than setting them to an empty string.
+ * Properties applied to the row that carries one item: the Gtk.ListItem of a list or grid, or the
+ * Gtk.ColumnViewRow of a table. Neither is a widget, so these are the only handles they offer; anything
+ * omitted falls back to the row's own default, which leaves the accessibility strings unset rather than
+ * setting them to an empty string.
  */
 type ListRowProps = {
     /** Name a screen reader announces for the row, through `accessible-label`. */
@@ -94,6 +101,14 @@ type ItemSizeProps = {
 
 type ListItemFactoryProps<T extends GObject.Object> = ItemSizeProps & {
     renderItem: ListItemRenderer<T>;
+    /** Resolves the props of the row carrying one model object, such as its screen-reader label. */
+    rowProps?: ListRowPropsResolver<T> | null | undefined;
+};
+
+/** Per-row properties shared by the collection views. */
+type RowPropsProps<T> = {
+    /** Resolves the props of the row carrying one item, such as its screen-reader label. */
+    rowProps?: ListRowPropsResolver<T> | null | undefined;
 };
 
 /** The flat-collection hint shared by {@link ListView} and {@link ColumnView}. */
@@ -113,7 +128,10 @@ type SelectionProps = {
      * user's selection is adopted into it.
      */
     selectedIds?: string[] | null | undefined;
-    /** Called with one id per selected row whenever the selection changes, and once on mount. */
+    /**
+     * Called with one id per selected row when the user or the widget changes the selection, or when an item
+     * `selectedIds` names is not in the collection; a `selectedIds` change is not reported back.
+     */
     onSelectionChanged?: ((ids: string[]) => void) | null | undefined;
     /** How much the user may select, one item at a time unless `MULTIPLE` or `NONE` is given. */
     selectionMode?: Gtk.SelectionMode | null | undefined;
@@ -138,7 +156,10 @@ type ExpansionProps = {
      * user's expansion is adopted into it.
      */
     expandedIds?: string[] | null | undefined;
-    /** Called with one id per expanded row, in visible order, whenever expansion changes. */
+    /**
+     * Called with one id per expanded row, in visible order, when the user or the widget changes expansion, or
+     * when a row `expandedIds` names cannot expand; an `expandedIds` change is not reported back.
+     */
     onExpandedChange?: ((ids: string[]) => void) | null | undefined;
     /**
      * Wording announced for the expander of every row that can expand, describing what activating it does.
@@ -159,15 +180,18 @@ type SortProps = {
 };
 
 /** The data a collection view renders, either as a plain item list or grouped into sections. */
-type SourceProps<T, S> = ({
-    /** Items to render, nesting through `ListItem.children` for a tree. */
-    items?: ListItem<T>[] | undefined;
-} & Partial<Record<"sections", undefined>> & Partial<Record<"renderHeader", null | undefined>>) | ({
-    /** Items grouped under section headers. */
-    sections: ListSection<S, T>[];
-    /** Renders the header shown above each section. */
-    renderHeader?: ListSectionRenderer<S> | null | undefined;
-} & Partial<Record<"items", undefined>>);
+type SourceProps<T, S> =
+    | ({
+          /** Items to render, nesting through `ListItem.children` for a tree. */
+          items?: ListItem<T>[] | undefined;
+      } & Partial<Record<"sections", undefined>> &
+          Partial<Record<"renderHeader", null | undefined>>)
+    | ({
+          /** Items grouped under section headers. */
+          sections: ListSection<S, T>[];
+          /** Renders the header shown above each section. */
+          renderHeader?: ListSectionRenderer<S> | null | undefined;
+      } & Partial<Record<"items", undefined>>);
 
 /** One column of a {@link ColumnView}, pairing Gtk.ColumnViewColumn props with a cell renderer. */
 type ColumnViewColumn<T = unknown> = Omit<GtkColumnViewColumnProps, "factory" | "sorter" | "id" | "title"> & {
@@ -179,6 +203,11 @@ type ColumnViewColumn<T = unknown> = Omit<GtkColumnViewColumnProps, "factory" |
     renderCell: ListItemRenderer<T>;
     /** Makes the column header clickable, reporting the choice through `onSortChanged`. */
     isSortable?: boolean | undefined;
+    /**
+     * Draws the tree expander and depth indentation in this column. Without a visible column marked this way,
+     * the first visible column draws them.
+     */
+    hasExpander?: boolean | undefined;
     /** Menu element popped up as the column header's context menu, on a right-click. */
     headerMenu?: ReactNode;
 };
@@ -189,11 +218,10 @@ type ColumnViewOwnProps<T, S> = SelectionProps &
     SortProps &
     SourceProps<T, S> &
     FlatnessProps &
+    RowPropsProps<T> &
     Omit<ItemSizeProps, "estimatedItemWidth"> & {
         /** Columns to render, in order; each carries its own cell renderer. */
         columns: ColumnViewColumn<T>[];
-        /** Resolves the props of the row carrying one item's cells, such as its screen-reader label. */
-        rowProps?: ListRowPropsResolver<T> | null | undefined;
     };
 
 /**
@@ -203,7 +231,7 @@ type ColumnViewProps<T = unknown, S = unknown> = Omit<
     GtkColumnViewProps,
     "children" | "columns" | "model" | "headerFactory" | "rowFactory" | keyof ColumnViewOwnProps<T, S>
 > &
-ColumnViewOwnProps<T, S>;
+    ColumnViewOwnProps<T, S>;
 
 /** The declarative collection props {@link DropDown} and `ComboRow` add on top of their widget's own. */
 type DropDownOwnProps<T, S> = SourceProps<T, S> & {
@@ -222,8 +250,8 @@ type DropDownWidgetProps<Widget, T, S> = Omit<
     Widget,
     "model" | "factory" | "listFactory" | "headerFactory" | keyof DropDownOwnProps<T, S>
 > &
-DropDownOwnProps<T, S> &
-(SourceProps<T & Primitive, S> | Record<"renderItem", ListItemRenderer<T>>);
+    DropDownOwnProps<T, S> &
+    (SourceProps<T & Primitive, S> | Record<"renderItem", ListItemRenderer<T>>);
 
 /**
  * Native `Gtk.DropDown` props with declarative collections, controlled selection, and display/popup renderers.
@@ -232,7 +260,8 @@ type DropDownProps<T = unknown, S = unknown> = DropDownWidgetProps<GtkDropDownPr
 
 /** The declarative collection props {@link GridView} adds on top of Gtk.GridView's own. */
 type GridViewOwnProps<T> = ItemSizeProps &
-    SelectionProps & {
+    SelectionProps &
+    RowPropsProps<T> & {
         /** Items to render as cells; a grid is always flat, so `ListItem.children` is ignored. */
         items?: ListItem<T>[] | undefined;
         /** Renders the contents of one cell. */
@@ -250,7 +279,8 @@ type ListViewOwnProps<T, S> = ItemSizeProps &
     SelectionProps &
     ExpansionProps &
     SourceProps<T, S> &
-    FlatnessProps & {
+    FlatnessProps &
+    RowPropsProps<T> & {
         /** Renders the contents of one row. */
         renderItem: ListItemRenderer<T>;
     };
@@ -263,7 +293,7 @@ type ListViewProps<T = unknown, S = unknown> = Omit<
     GtkListViewProps,
     "model" | "factory" | "headerFactory" | keyof ListViewOwnProps<T, S>
 > &
-ListViewOwnProps<T, S>;
+    ListViewOwnProps<T, S>;
 
 /**
  * Native `Adw.ComboRow` props with declarative collections, controlled selection, and display/popup renderers.