@gtkx/components 1.0.0-rc.3 → 1.0.0

package/src/column-view.tsx

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import type { ReactNode, RefObject } from "react";
 import * as Gtk from "@gtkx/gi/gtk";
 import { GtkColumnView, GtkColumnViewColumn, GtkCustomSorter, GtkSignalListItemFactory } from "@gtkx/jsx/gtk";
 import { useSignal } from "@gtkx/react";
@@ -6,40 +6,37 @@ import { omit } from "@gtkx/utils";
 import { useLayoutEffect, useRef } from "react";
 import type { CellSize } from "./internal/cells.js";
 import type { Collection } from "./internal/collection.js";
-import type { Column, ColumnViewProps } from "./types.js";
-import { HeaderPortals, ItemPortals, useHeaderCells, useItemCells } from "./internal/cells.js";
+import type { ColumnViewColumn, ColumnViewProps, ExpanderDescriptions, SortProps } from "./types.js";
+import { ItemPortals, useItemCells, useRowProps, useSectionHeader } from "./internal/cells.js";
 import { useCollection } from "./internal/use-collection.js";
 import { useWidgetRef } from "./internal/use-widget-ref.js";
 
-type SortProps = {
-    sortColumn?: string | null | undefined;
-    sortOrder?: Gtk.SortType | null | undefined;
-    onSortChanged?: ((column: string | null, order: Gtk.SortType) => void) | null | undefined;
-};
-
 type SortTarget = { view: Gtk.ColumnView; column: Gtk.ColumnViewColumn | null };
 
 type ColumnCellsProps = {
-    column: Column<never>;
+    column: ColumnViewColumn<never>;
     collection: Collection;
     expandedIds: string[] | null | undefined;
+    expanderDescriptions: ExpanderDescriptions | null | undefined;
     size: CellSize;
 };
 
 type ColumnListProps = Omit<ColumnCellsProps, "column"> & {
-    columns: Column<never>[];
+    columns: ColumnViewColumn<never>[];
 };
 
 const COLUMN_VIEW_PROPS = [
     "items",
     "sections",
     "renderHeader",
+    "rowProps",
     "columns",
     "selectedIds",
     "onSelectionChanged",
     "selectionMode",
     "expandedIds",
     "onExpandedChange",
+    "expanderDescriptions",
     "sortColumn",
     "sortOrder",
     "onSortChanged",
@@ -77,7 +74,7 @@ const getSortTarget = (view: Gtk.ColumnView | null, sortColumn: string | null |
 };
 
 const applySort = (
-    sorting: { current: boolean },
+    sorting: RefObject<boolean>,
     view: Gtk.ColumnView,
     column: Gtk.ColumnViewColumn | null,
     order: Gtk.SortType | null | undefined,
@@ -93,7 +90,7 @@ const applySort = (
 
 const emitSortChanged = (
     sorter: Gtk.ColumnViewSorter | null,
-    sorting: { current: boolean },
+    sorting: RefObject<boolean>,
     sort: SortProps,
 ): void => {
     if (sorter === null || sorting.current) {
@@ -104,7 +101,7 @@ const emitSortChanged = (
 };
 
 const syncSort = (
-    sorting: { current: boolean },
+    sorting: RefObject<boolean>,
     view: Gtk.ColumnView | null,
     sortColumn: string | null | undefined,
     sortOrder: Gtk.SortType | null | undefined,
@@ -118,7 +115,7 @@ const syncSort = (
     applySort(sorting, target.view, target.column, sortOrder);
 };
 
-const useColumnSorting = (view: Gtk.ColumnView | null, sort: SortProps, columns: Column<never>[]): void => {
+const useColumnSorting = (view: Gtk.ColumnView | null, sort: SortProps, columns: ColumnViewColumn<never>[]): void => {
     const sorting = useRef(false);
     const sorter = view?.getSorter() ?? null;
     const columnSorter = sorter instanceof Gtk.ColumnViewSorter ? sorter : null;
@@ -134,54 +131,56 @@ const useColumnSorting = (view: Gtk.ColumnView | null, sort: SortProps, columns:
     }, [view, sortColumn, sortOrder, columns]);
 };
 
-const ColumnCells = ({ column, collection, expandedIds, size }: ColumnCellsProps): ReactNode => {
+const ColumnCells = ({ column, collection, expandedIds, expanderDescriptions, size }: ColumnCellsProps): ReactNode => {
     const cells = useItemCells(size);
-    const rest = omit(column, ["id", "renderCell", "sortable"]);
+    const rest = omit(column, ["id", "renderCell", "isSortable"]);
 
     return (
         <>
             <GtkColumnViewColumn
                 id={column.id}
                 factory={<GtkSignalListItemFactory {...cells.handlers} />}
-                sorter={column.sortable === true ? <GtkCustomSorter /> : null}
+                sorter={column.isSortable === true ? <GtkCustomSorter /> : null}
                 {...rest}
             />
             <ItemPortals
-                store={cells}
+                registry={cells}
                 render={column.renderCell}
                 collection={collection}
                 expandedIds={expandedIds}
+                expanderDescriptions={expanderDescriptions}
             />
         </>
     );
 };
 
-const ColumnList = ({ columns, collection, expandedIds, size }: ColumnListProps): ReactNode =>
+const ColumnList = ({ columns, collection, expandedIds, expanderDescriptions, size }: ColumnListProps): ReactNode =>
     columns.map((column) => (
         <ColumnCells
             key={column.id}
             column={column}
             collection={collection}
             expandedIds={expandedIds}
+            expanderDescriptions={expanderDescriptions}
             size={size}
         />
     ));
 
 /**
  * Renders a Gtk.ColumnView from declarative items or sections and a columns array,
- * with controlled selection, expansion, and sorting, per-column header menus, and
- * section header rendering.
+ * with controlled selection, expansion, and sorting, per-column header menus,
+ * section header rendering, and per-row props such as a screen-reader label.
  */
 function ColumnView<T = unknown, S = unknown>(props: ColumnViewProps<T, S>): ReactNode {
-    const { renderHeader, columns, expandedIds, sortColumn, sortOrder, onSortChanged, estimatedItemHeight, ref } =
-        props;
-
+    const { renderHeader, rowProps, columns, expandedIds, expanderDescriptions } = props;
+    const { sortColumn, sortOrder, onSortChanged, ref } = props;
     const rest = omit(props, COLUMN_VIEW_PROPS);
+    const size = { width: -1, height: props.estimatedItemHeight ?? -1 };
     const [view, refCallback] = useWidgetRef<Gtk.ColumnView>(ref);
-    const size = { width: -1, height: estimatedItemHeight ?? -1 };
     const { collection, selection } = useCollection(props);
-    const headerCells = useHeaderCells(size);
-    const columnList = columns as Column<never>[];
+    const header = useSectionHeader(renderHeader, collection, size);
+    const rows = useRowProps(rowProps, collection, expandedIds);
+    const columnList = columns as ColumnViewColumn<never>[];
     useColumnSorting(view, { sortColumn, sortOrder, onSortChanged }, columnList);
 
     return (
@@ -189,16 +188,20 @@ function ColumnView<T = unknown, S = unknown>(props: ColumnViewProps<T, S>): Rea
             <GtkColumnView
                 ref={refCallback}
                 model={selection}
-                {...(renderHeader != null && {
-                    headerFactory: <GtkSignalListItemFactory {...headerCells.handlers} />,
-                })}
+                {...header.factoryProps}
+                {...rows.factoryProps}
                 {...rest}
             >
-                <ColumnList columns={columnList} collection={collection} expandedIds={expandedIds} size={size} />
+                <ColumnList
+                    columns={columnList}
+                    collection={collection}
+                    expandedIds={expandedIds}
+                    expanderDescriptions={expanderDescriptions}
+                    size={size}
+                />
             </GtkColumnView>
-            {renderHeader != null && (
-                <HeaderPortals store={headerCells} render={renderHeader} collection={collection} />
-            )}
+            {header.portals}
+            {rows.portals}
         </>
     );
 }

package/src/drop-down.tsx

@@ -4,6 +4,7 @@ import type { DropDownBaseProps } from "./internal/drop-down.js";
 import type { DropDownProps } from "./types.js";
 import { DropDownBase } from "./internal/drop-down.js";
 
+/** Call signature of {@link DropDown}, generic in the item and section value types. */
 type DropDownComponent = <T = unknown, S = unknown>(props: DropDownProps<T, S>) => ReactNode;
 
 /**

package/src/grid-view.tsx

@@ -23,13 +23,13 @@ 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 { collection, selection } = useCollection({ ...props, isFlat: true });
     const itemCells = useItemCells(size);
 
     return (
         <>
             <GtkGridView model={selection} factory={<GtkSignalListItemFactory {...itemCells.handlers} />} {...rest} />
-            <ItemPortals store={itemCells} render={renderItem} collection={collection} />
+            <ItemPortals registry={itemCells} render={renderItem} collection={collection} />
         </>
     );
 }

package/src/index.ts

@@ -2,20 +2,19 @@ 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 {
-    ChildProps,
-    Column,
+    ColumnViewColumn,
     ColumnViewProps,
     DropDownProps,
+    ExpanderDescriptions,
     GridViewProps,
-    HeaderRenderer,
-    Item,
-    ItemRenderer,
+    ListItem,
+    ListItemRenderArgs,
+    ListItemRenderer,
+    ListRowProps,
+    ListRowPropsResolver,
+    ListSection,
+    ListSectionRenderArgs,
+    ListSectionRenderer,
     ListViewProps,
-    RenderHeaderArgs,
-    RenderItemArgs,
-    Section,
-    SizeGroupChildProps,
-    SizeGroupProps,
 } from "./types.js";