@gridkitjs/core 0.0.0-dev-20261107195236 → 0.0.0-dev-20261107203826

package/dist/index.d.ts

@@ -1374,6 +1374,15 @@ interface ToolbarCustomEntry {
  * dropdown of the export commands that show; and a custom entry.
  */
 type ToolbarEntry<Row> = MenuEntry<Row> | "search" | "spacer" | "export" | ToolbarCustomEntry;
+/**
+ * Attributes of the app's own for a toolbar entry's element, as hooks for
+ * its tests, analytics or styles: an `id` and `data-*` attributes, nothing
+ * that could change what the entry means or does.
+ */
+interface ToolbarItemAttributes {
+    readonly id?: string | undefined;
+    readonly [name: `data-${string}`]: string;
+}
 /**
  * A toolbar button ready to draw — a command, or an inline item — with
  * every label a string, every flag a boolean, and `run` bound to the
@@ -1397,6 +1406,8 @@ interface ResolvedToolbarButton {
     readonly pressed: boolean | undefined;
     /** Runs the button, and says whether it ran — see `ResolvedMenuItem.run`. */
     readonly run: () => boolean;
+    /** The app's attributes for its element, from `itemAttributes`. */
+    readonly attributes?: ToolbarItemAttributes | undefined;
 }
 /** A dropdown button, opening the menu its submenu entry lists. */
 interface ResolvedToolbarMenu {
@@ -1408,12 +1419,16 @@ interface ResolvedToolbarMenu {
     readonly icon?: string | undefined;
     /** Never empty: a dropdown with nothing to show is left out. */
     readonly items: readonly ResolvedMenuEntry[];
+    /** The app's attributes for its element, from `itemAttributes`. */
+    readonly attributes?: ToolbarItemAttributes | undefined;
 }
 /** The search box, over the grid's global text filter. */
 interface ResolvedToolbarSearch {
     readonly type: "search";
     /** Always `"search"`. */
     readonly key: string;
+    /** The app's attributes for its element, from `itemAttributes`. */
+    readonly attributes?: ToolbarItemAttributes | undefined;
 }
 /** The free space between the entries either side of it. */
 interface ResolvedToolbarSpacer {
@@ -1427,6 +1442,8 @@ interface ResolvedToolbarCustom {
     readonly id: string;
     /** The same as `id`. */
     readonly key: string;
+    /** The app's attributes for its element, from `itemAttributes`. */
+    readonly attributes?: ToolbarItemAttributes | undefined;
 }
 /**
  * One entry of a toolbar as `resolveToolbar` hands it to a renderer to draw.
@@ -1436,12 +1453,21 @@ interface ResolvedToolbarCustom {
  */
 type ResolvedToolbarItem = ResolvedToolbarButton | ResolvedToolbarMenu | ResolvedToolbarSearch | ResolvedToolbarSpacer | ResolvedMenuSeparator | ResolvedToolbarCustom;
 
-/** A grid's toolbar: what it lists, and what a screen reader calls it. */
+/**
+ * A grid's toolbar: what it lists, what a screen reader calls it, and the
+ * attributes of the app's own its entries' elements carry.
+ */
 interface GridToolbarOptions<Row> {
     /** The toolbar's entries, in order. Left out, the defaults. */
     readonly items?: readonly ToolbarEntry<Row>[] | undefined;
     /** The toolbar's accessible name. Left out, `messages.toolbarLabel`. */
     readonly label?: string | undefined;
+    /**
+     * Attributes for entries' elements, by the entry's key: a command's,
+     * inline item's, dropdown's or custom entry's id, `"search"` or
+     * `"export"`. A key naming no entry, or a separator or spacer, is ignored.
+     */
+    readonly itemAttributes?: Readonly<Record<string, ToolbarItemAttributes>> | undefined;
 }
 /**
  * What a toolbar lists unless the grid says otherwise: the search box, then
@@ -1732,11 +1758,23 @@ interface GridOptions<Row> {
      */
     filterMenu?: GridFilterMenuOptions | undefined;
     /**
-     * Whether the grid's rows are split into pages. A page's unit is a
-     * top-level group or a bare data row, never a leaf row — a group is never
-     * split across a page boundary. Off by default, matching `sortableColumns`.
+     * Whether the grid's rows are split into pages. Off by default, matching
+     * `sortableColumns`. What a page's `pageSize` counts once the rows are
+     * grouped is `paginationUnit`'s choice.
      */
     paginated?: boolean | undefined;
+    /**
+     * What `pageSize` counts in a grouped grid. `"group"` (the default) counts
+     * top-level groups, each with everything beneath it, so a page never
+     * splits a group but can grow as large as its groups. `"row"` counts data
+     * rows, plus collapsed group headers, which stand in for their hidden
+     * rows: every page holds `pageSize` of them, and a page continuing a group
+     * starts with that group's headers again, with a group's summary row on
+     * the page holding its last row. An ungrouped grid pages by data rows
+     * under either. Selection, export and aggregates behave the same under
+     * either unit.
+     */
+    paginationUnit?: PaginationUnit | undefined;
     /**
      * The page and page size to start on. Uncontrolled. Defaults to
      * `{ pageIndex: 0, pageSize: 25 }` when `paginated` is on and this is
@@ -1749,9 +1787,9 @@ interface GridOptions<Row> {
      * them itself, starting from `defaultPagination`.
      *
      * The grid sends an uncontrolled pagination back to the first page when
-     * the filter, sort or grouping changes; a controlled one is the parent's
-     * to reset alongside that change. Until it does, the grid shows the last
-     * page that exists rather than an empty one.
+     * the filter, sort, grouping or `paginationUnit` changes; a controlled
+     * one is the parent's to reset alongside that change. Until it does, the
+     * grid shows the last page that exists rather than an empty one.
      */
     pagination?: PaginationState | undefined;
     /** Called once when the user changes the page or the page size. */
@@ -2219,6 +2257,15 @@ interface PaginationState {
     readonly pageIndex: number;
     readonly pageSize: number;
 }
+/**
+ * What a grouped grid's `pageSize` counts. `"group"` counts top-level groups,
+ * each with everything beneath it, so a page never splits a group. `"row"`
+ * counts data rows and collapsed group headers, so every page holds
+ * `pageSize` of them however large the groups are; a page continuing a group
+ * starts with that group's headers again. An ungrouped grid pages by data
+ * rows under either.
+ */
+type PaginationUnit = "group" | "row";
 /** Reports a user page/page-size change whole — the one to persist from, mirroring ColumnSortEvent. */
 interface PaginationChangeEvent {
     readonly pagination: PaginationState;
@@ -2857,6 +2904,8 @@ type GridViewState<Row> = Omit<GridState<Row>, "rowSelection" | "columnSelection
 interface GridViewOptions<Row> {
     /** Whether `pageRows` is one page of `displayRows` rather than all of it. Defaults to `false`. */
     readonly paginated?: boolean | undefined;
+    /** What a page's `pageSize` counts once grouped. Defaults to `"group"`. */
+    readonly paginationUnit?: PaginationUnit | undefined;
     readonly aggregates?: AggregateState<Row> | undefined;
     /** Defaults to `"inline"`. */
     readonly groupAggregateDisplay?: GroupAggregateDisplay | undefined;
@@ -3012,6 +3061,8 @@ interface ToolbarResolveOptions<Row> {
      * opens a panel anchors it there.
      */
     readonly contextFor: (target: GridToolbarTarget) => GridCommandContext<Row>;
+    /** Attributes for entries' elements, by key — see `GridToolbarOptions`. */
+    readonly itemAttributes?: Readonly<Record<string, ToolbarItemAttributes>> | undefined;
 }
 /**
  * A toolbar's entries resolved against the grid, ready to draw, by the
@@ -3027,6 +3078,8 @@ interface ToolbarResolveOptions<Row> {
  * - `"search"`, `"spacer"` and custom entries stay as they are.
  * - Separators never lead, trail, double up or sit next to a spacer, which
  *   already parts what is on either side of it.
+ * - A button, dropdown, search box or custom entry whose key
+ *   `itemAttributes` names carries those `attributes`.
  *
  * Resolve again whenever the grid changes, so each button's label, flags
  * and `run` follow its state.
@@ -3636,18 +3689,27 @@ interface PaginatedRows<Row> {
      */
     readonly pageIndex: number;
 }
+interface PaginateRowsOptions {
+    /** What `pageSize` counts — see `PaginationUnit`. Defaults to `"group"`. */
+    readonly unit?: PaginationUnit | undefined;
+}
 /**
- * `rows` sliced into pages of `pagination.pageSize` units — see `unitsOf`
- * for what a unit is. `pageIndex` is clamped into range, `pageSize <= 0` is
- * clamped to `1` (this codebase's general tolerance for stale/odd stored
- * state, matching `sortRows`/`filterRows`), and the returned page's
- * `rowIndex` is renumbered to be page-relative — 0-based from the top of the
- * page, header rows included, mirroring `groupRows`'s own renumbering
- * invariant. `datasetIndex` is left untouched: the stages ahead of this one
- * set it to each row's position in the whole displayed result, which stays
- * the same whichever page is showing.
- */
-declare function paginateRows<Row>(rows: readonly DisplayRow<Row>[], pagination: PaginationState): PaginatedRows<Row>;
+ * `rows` sliced into pages of `pagination.pageSize` units — see
+ * `groupUnitsOf` and `rowUnitsOf` for what a unit is under each
+ * `options.unit`. A page opens with its first unit's enclosing headers, so
+ * under `"row"` a header repeated from the page before is the same
+ * `DisplayRow`, and toggling it toggles its group on every page.
+ *
+ * `pageIndex` is clamped into range, `pageSize <= 0` is clamped to `1`
+ * (this codebase's general tolerance for stale/odd stored state, matching
+ * `sortRows`/`filterRows`), and the returned page's `rowIndex` is renumbered
+ * to be page-relative — 0-based from the top of the page, header rows
+ * included, mirroring `groupRows`'s own renumbering invariant.
+ * `datasetIndex` is left untouched: the stages ahead of this one set it to
+ * each row's position in the whole displayed result, which stays the same
+ * whichever page is showing.
+ */
+declare function paginateRows<Row>(rows: readonly DisplayRow<Row>[], pagination: PaginationState, options?: PaginateRowsOptions): PaginatedRows<Row>;
 
 type PaginationWindowEntry = number | "ellipsis";
 /**
@@ -4227,4 +4289,4 @@ declare const excelFilter: {
     };
 };
 
-export { type AggregateFn, type AggregateResults, type AggregateSpec, type AggregateState, type Borders, type BuiltInAggregate, type BuiltInCommandIcon, type BuiltInCommandId, type CellSelectEvent, type CellSelectionChangeEvent, type CellSelectionMode, type CellSelectionState, type CellTemplateContext, type ColumnAlignment, type ColumnChooserEntry, type ColumnChooserInput, type ColumnChooserModel, type ColumnChooserToggle, type ColumnConstraints, type ColumnDefinition, type ColumnFilterMenuOptions, type ColumnFilterShape, type ColumnOrderEvent, type ColumnOrderState, type ColumnResizeEvent, type ColumnResizeSession, type ColumnResolveOptions, type ColumnSelectEvent, type ColumnSelectionChangeEvent, type ColumnSizeDefaults, type ColumnSizingState, type ColumnSortEntry, type ColumnSortEvent, type ColumnSortState, type ColumnType, type ColumnValueCacheQuery, type ColumnValueOption, type ColumnValueOptions, type ColumnValueOptionsCache, type ColumnValueQuery, type ColumnVisibilityEvent, type ColumnVisibilityState, type ColumnWrapConfig, type ColumnsSelectEvent, type ConditionRowDraft, type ContextMenuOpenChangeEvent, type CopyContent, type CopyRequest, type CopySource, type CsvOptions, DEFAULT_COLUMN_SIZES, DEFAULT_FILTER_VALUE_LIMIT, type DataColumn, type DisplayRow, type DropSide, type ExportCell, type ExportColumn, type ExportDataRow, type ExportFile, type ExportFileSource, type ExportGroupRow, type ExportGroupSummaryRow, type ExportOptions, type ExportRow, type ExportScalar, type ExportSource, type ExportTable, type ExportTotalRow, type ExportWriteContext, type ExportWriter, type FieldPath, type FilterChangeEvent, type FilterChecklist, type FilterChecklistItem, type FilterChecklistOptions, type FilterEditorAction, type FilterEditorDraft, type FilterEntry, type FilterMenuUi, type FilterOperator, type FilterOperatorFamily, type FilterPredicate, type FilterScalar, type FilterState, type FooterTemplateContext, type FormatLocale, type GridCommand, type GridCommandActions, type GridCommandContext, type GridCommandContextInput, type GridCommandEvent, type GridCommandHost, type GridCommandSource, type GridCommandTarget, type GridContextMenuArea, type GridContextMenuEntries, type GridContextMenuOptions, type GridContextMenuRequest, type GridContextMenuTarget, type GridController, type GridControllerOptions, type GridExportOptions, type GridFilterMenuOptions, type GridFocus, type GridMessages, type GridOptions, type GridPanelKind, type GridState, type GridToolbarOptions, type GridToolbarTarget, type GridView, type GridViewInput, type GridViewOptions, type GridViewState, type GroupAggregateDisplay, type GroupByBarVisibility, type GroupByEntry, type GroupByEvent, type GroupByState, type GroupExpansionEvent, type GroupExpansionState, type GroupFilterEntry, HEADER_ROW, type HoverableConfig, type HtmlTableOptions, type JsonOptions, KEYBOARD_STEP, type KeyShortcutCapabilities, type MenuEntry, type MenuItemEntry, type MenuMove, type MenuResolveOptions, type MenuSubmenuEntry, type NavigationModifiers, type OperatorFilterEntry, type PaginatedRows, type PaginationChangeEvent, type PaginationState, type PaginationWindowEntry, type ParsedConditionRows, type PredicateFilterEntry, type PrintDocument, type PrintOptions, type PrintOrientation, type PrintPage, type PrintSource, type ResizeMode, type ResolvedColumn, type ResolvedColumnFilterMenu, type ResolvedGroupRow, type ResolvedGroupSummaryRow, type ResolvedMenuEntry, type ResolvedMenuItem, type ResolvedMenuSeparator, type ResolvedMenuSubmenu, type ResolvedRow, type ResolvedToolbarButton, type ResolvedToolbarCustom, type ResolvedToolbarItem, type ResolvedToolbarMenu, type ResolvedToolbarSearch, type ResolvedToolbarSpacer, type RowHeights, type RowPointerEvent, type RowProps, type RowSelectEvent, type RowSelectionChangeEvent, type RowsSelectEvent, type SelectAllState, type SelectIntent, type SelectableConfig, type SelectedCell, type SelectedCellRef, type SelectedColumn, type SelectionCallbacks, type SelectionDiff, type SelectionDiffEvent, type SelectionMode, type SelectionState, type SerializedFilterEntry, type SerializedFilterScalar, type SerializedFilterState, type SerializedGridState, type SerializedGroupFilterEntry, type SerializedOperatorFilterEntry, type SerializedValueFilterEntry, type SortDirection, type TextFilterEntry, type ToolbarCustomEntry, type ToolbarEntry, type ToolbarFitInput, type ToolbarResolveOptions, type ToolbarSplit, type TsvOptions, type ValueFilterEntry, type VisibleRange, accessDotted, alignmentForType, applyColumnOrder, applyColumnResize, applyColumnVisibility, applySelectionIntent, beginColumnResize, buildExportTable, buildKeyShortcuts, buildPrintDocument, builtInCommands, clampColumnWidth, clampFocus, clearAllFilters, clearSelection, collapseAllGroups, columnValueOptions, compareValues, computeAggregates, conditionRowsFrom, conditionsFromRows, contextMenuEntries, copyContent, createColumnValueOptionsCache, createCommandContext, createDefaultMessages, createGridController, createGridViewResolver, csvWriter, defaultContextMenu, defaultFilterOperators, defaultMessages, defaultToolbar, defineColumnsFromRows, describeColumnFilter, diffSelection, draftToFilter, excelFilter, expandAllGroups, exportFile, exportPrintDocument, filterChecklist, filterEditorReducer, filterOperandArity, filterOperatorFamily, filterQueryFor, filterRows, fitColumnsToWidth, fitToolbarItems, formatAggregateValue, formatCellValue, formatFilterOperand, formatGroupValue, getColumnId, groupRowId, groupRows, hasContextMenu, initialFilterEditorDraft, intentOf, isColumnFiltered, isColumnVisible, isPinnedToolbarItem, isSameCell, jsonWriter, matchesQuery, moveColumnBefore, moveGroupByBefore, movesColumn, movesGroupBy, nextFocusForKey, nextMenuIndex, paginateRows, paginationWindow, parseFilterOperand, resolveCell, resolveColumnChooser, resolveColumnConstraints, resolveColumnFilterMenu, resolveColumnHeaderText, resolveColumnLabel, resolveColumnWidths, resolveColumns, resolveCommands, resolveDataColumns, resolveDropBefore, resolveExportWriters, resolveGridView, resolveKeyboardDropTarget, resolveMenu, resolveMessages, resolveRowId, resolveRows, resolveShownRows, resolveToolbar, revertColumnSize, runCommand, searchTextOf, selectAll, selectAllState, selectCell, selectOnly, selectRange, serializeGridState, setColumnFilter, setColumnVisibility, setSearchText, sizeColumnToContent, sortDirectionFor, sortPriorityFor, sortRows, splitToolbarItems, toCsv, toHtmlTable, toJson, toTsv, toggleCellSelection, toggleColumnSort, toggleGroupExpansion, toggleSelection, toolbarEntries, totalColumnWidth, typeaheadIndex, visibleFilterOptions, visibleRange, withGroupAggregates };
+export { type AggregateFn, type AggregateResults, type AggregateSpec, type AggregateState, type Borders, type BuiltInAggregate, type BuiltInCommandIcon, type BuiltInCommandId, type CellSelectEvent, type CellSelectionChangeEvent, type CellSelectionMode, type CellSelectionState, type CellTemplateContext, type ColumnAlignment, type ColumnChooserEntry, type ColumnChooserInput, type ColumnChooserModel, type ColumnChooserToggle, type ColumnConstraints, type ColumnDefinition, type ColumnFilterMenuOptions, type ColumnFilterShape, type ColumnOrderEvent, type ColumnOrderState, type ColumnResizeEvent, type ColumnResizeSession, type ColumnResolveOptions, type ColumnSelectEvent, type ColumnSelectionChangeEvent, type ColumnSizeDefaults, type ColumnSizingState, type ColumnSortEntry, type ColumnSortEvent, type ColumnSortState, type ColumnType, type ColumnValueCacheQuery, type ColumnValueOption, type ColumnValueOptions, type ColumnValueOptionsCache, type ColumnValueQuery, type ColumnVisibilityEvent, type ColumnVisibilityState, type ColumnWrapConfig, type ColumnsSelectEvent, type ConditionRowDraft, type ContextMenuOpenChangeEvent, type CopyContent, type CopyRequest, type CopySource, type CsvOptions, DEFAULT_COLUMN_SIZES, DEFAULT_FILTER_VALUE_LIMIT, type DataColumn, type DisplayRow, type DropSide, type ExportCell, type ExportColumn, type ExportDataRow, type ExportFile, type ExportFileSource, type ExportGroupRow, type ExportGroupSummaryRow, type ExportOptions, type ExportRow, type ExportScalar, type ExportSource, type ExportTable, type ExportTotalRow, type ExportWriteContext, type ExportWriter, type FieldPath, type FilterChangeEvent, type FilterChecklist, type FilterChecklistItem, type FilterChecklistOptions, type FilterEditorAction, type FilterEditorDraft, type FilterEntry, type FilterMenuUi, type FilterOperator, type FilterOperatorFamily, type FilterPredicate, type FilterScalar, type FilterState, type FooterTemplateContext, type FormatLocale, type GridCommand, type GridCommandActions, type GridCommandContext, type GridCommandContextInput, type GridCommandEvent, type GridCommandHost, type GridCommandSource, type GridCommandTarget, type GridContextMenuArea, type GridContextMenuEntries, type GridContextMenuOptions, type GridContextMenuRequest, type GridContextMenuTarget, type GridController, type GridControllerOptions, type GridExportOptions, type GridFilterMenuOptions, type GridFocus, type GridMessages, type GridOptions, type GridPanelKind, type GridState, type GridToolbarOptions, type GridToolbarTarget, type GridView, type GridViewInput, type GridViewOptions, type GridViewState, type GroupAggregateDisplay, type GroupByBarVisibility, type GroupByEntry, type GroupByEvent, type GroupByState, type GroupExpansionEvent, type GroupExpansionState, type GroupFilterEntry, HEADER_ROW, type HoverableConfig, type HtmlTableOptions, type JsonOptions, KEYBOARD_STEP, type KeyShortcutCapabilities, type MenuEntry, type MenuItemEntry, type MenuMove, type MenuResolveOptions, type MenuSubmenuEntry, type NavigationModifiers, type OperatorFilterEntry, type PaginateRowsOptions, type PaginatedRows, type PaginationChangeEvent, type PaginationState, type PaginationUnit, type PaginationWindowEntry, type ParsedConditionRows, type PredicateFilterEntry, type PrintDocument, type PrintOptions, type PrintOrientation, type PrintPage, type PrintSource, type ResizeMode, type ResolvedColumn, type ResolvedColumnFilterMenu, type ResolvedGroupRow, type ResolvedGroupSummaryRow, type ResolvedMenuEntry, type ResolvedMenuItem, type ResolvedMenuSeparator, type ResolvedMenuSubmenu, type ResolvedRow, type ResolvedToolbarButton, type ResolvedToolbarCustom, type ResolvedToolbarItem, type ResolvedToolbarMenu, type ResolvedToolbarSearch, type ResolvedToolbarSpacer, type RowHeights, type RowPointerEvent, type RowProps, type RowSelectEvent, type RowSelectionChangeEvent, type RowsSelectEvent, type SelectAllState, type SelectIntent, type SelectableConfig, type SelectedCell, type SelectedCellRef, type SelectedColumn, type SelectionCallbacks, type SelectionDiff, type SelectionDiffEvent, type SelectionMode, type SelectionState, type SerializedFilterEntry, type SerializedFilterScalar, type SerializedFilterState, type SerializedGridState, type SerializedGroupFilterEntry, type SerializedOperatorFilterEntry, type SerializedValueFilterEntry, type SortDirection, type TextFilterEntry, type ToolbarCustomEntry, type ToolbarEntry, type ToolbarFitInput, type ToolbarItemAttributes, type ToolbarResolveOptions, type ToolbarSplit, type TsvOptions, type ValueFilterEntry, type VisibleRange, accessDotted, alignmentForType, applyColumnOrder, applyColumnResize, applyColumnVisibility, applySelectionIntent, beginColumnResize, buildExportTable, buildKeyShortcuts, buildPrintDocument, builtInCommands, clampColumnWidth, clampFocus, clearAllFilters, clearSelection, collapseAllGroups, columnValueOptions, compareValues, computeAggregates, conditionRowsFrom, conditionsFromRows, contextMenuEntries, copyContent, createColumnValueOptionsCache, createCommandContext, createDefaultMessages, createGridController, createGridViewResolver, csvWriter, defaultContextMenu, defaultFilterOperators, defaultMessages, defaultToolbar, defineColumnsFromRows, describeColumnFilter, diffSelection, draftToFilter, excelFilter, expandAllGroups, exportFile, exportPrintDocument, filterChecklist, filterEditorReducer, filterOperandArity, filterOperatorFamily, filterQueryFor, filterRows, fitColumnsToWidth, fitToolbarItems, formatAggregateValue, formatCellValue, formatFilterOperand, formatGroupValue, getColumnId, groupRowId, groupRows, hasContextMenu, initialFilterEditorDraft, intentOf, isColumnFiltered, isColumnVisible, isPinnedToolbarItem, isSameCell, jsonWriter, matchesQuery, moveColumnBefore, moveGroupByBefore, movesColumn, movesGroupBy, nextFocusForKey, nextMenuIndex, paginateRows, paginationWindow, parseFilterOperand, resolveCell, resolveColumnChooser, resolveColumnConstraints, resolveColumnFilterMenu, resolveColumnHeaderText, resolveColumnLabel, resolveColumnWidths, resolveColumns, resolveCommands, resolveDataColumns, resolveDropBefore, resolveExportWriters, resolveGridView, resolveKeyboardDropTarget, resolveMenu, resolveMessages, resolveRowId, resolveRows, resolveShownRows, resolveToolbar, revertColumnSize, runCommand, searchTextOf, selectAll, selectAllState, selectCell, selectOnly, selectRange, serializeGridState, setColumnFilter, setColumnVisibility, setSearchText, sizeColumnToContent, sortDirectionFor, sortPriorityFor, sortRows, splitToolbarItems, toCsv, toHtmlTable, toJson, toTsv, toggleCellSelection, toggleColumnSort, toggleGroupExpansion, toggleSelection, toolbarEntries, totalColumnWidth, typeaheadIndex, visibleFilterOptions, visibleRange, withGroupAggregates };

package/dist/index.js

@@ -411,7 +411,8 @@ function resolveKeyboardDropTarget(orderedIds, columnId, direction) {
 }
 
 // src/util/paging.ts
-function unitsOf(rows) {
+var NO_HEADERS = [];
+function groupUnitsOf(rows) {
   const units = [];
   let start = 0;
   let openedByGroup = false;
@@ -423,7 +424,7 @@ function unitsOf(rows) {
     const isTopLevelHeader = "kind" in entry && entry.kind === "group" && entry.level === 0;
     const isBoundary = index !== start && (isTopLevelHeader || !openedByGroup);
     if (isBoundary) {
-      units.push({ start, end: index });
+      units.push({ start, end: index, headers: NO_HEADERS });
       start = index;
       openedByGroup = isTopLevelHeader;
     } else if (index === start) {
@@ -431,13 +432,38 @@ function unitsOf(rows) {
     }
   }
   if (start < rows.length) {
-    units.push({ start, end: rows.length });
+    units.push({ start, end: rows.length, headers: NO_HEADERS });
   }
   return units;
 }
-function paginateRows(rows, pagination) {
+function rowUnitsOf(rows) {
+  const units = [];
+  let open = NO_HEADERS;
+  for (let index = 0; index < rows.length; index++) {
+    const entry = rows[index];
+    if (entry === void 0) {
+      continue;
+    }
+    if (!("kind" in entry)) {
+      units.push({ start: index, end: index + 1, headers: open });
+    } else if (entry.kind === "group") {
+      const ancestors = open.slice(0, entry.level);
+      open = entry.expanded ? [...ancestors, entry] : ancestors;
+      if (!entry.expanded) {
+        units.push({ start: index, end: index + 1, headers: ancestors });
+      }
+    } else {
+      const last = units.at(-1);
+      if (last !== void 0) {
+        units[units.length - 1] = { ...last, end: index + 1 };
+      }
+    }
+  }
+  return units;
+}
+function paginateRows(rows, pagination, options = {}) {
   const pageSize = Math.max(1, pagination.pageSize);
-  const units = unitsOf(rows);
+  const units = options.unit === "row" ? rowUnitsOf(rows) : groupUnitsOf(rows);
   const pageCount = Math.ceil(units.length / pageSize);
   if (pageCount === 0) {
     return { rows: [], pageCount: 0, pageIndex: 0 };
@@ -448,7 +474,10 @@ function paginateRows(rows, pagination) {
   if (firstUnit === void 0 || lastUnit === void 0) {
     return { rows: [], pageCount, pageIndex };
   }
-  const page = rows.slice(firstUnit.start, lastUnit.end);
+  const page = [
+    ...firstUnit.headers,
+    ...rows.slice(firstUnit.start, lastUnit.end)
+  ];
   const renumbered = page.map(
     (entry, index) => entry.rowIndex === index ? entry : { ...entry, rowIndex: index }
   );
@@ -1250,8 +1279,8 @@ function totalAggregates(rows, aggregates, dataColumns) {
     dataColumns
   );
 }
-function paginate(displayRows, paginated, pagination) {
-  return paginated ? paginateRows(displayRows, pagination) : { rows: displayRows, pageCount: 1, pageIndex: 0 };
+function paginate(displayRows, paginated, pagination, unit) {
+  return paginated ? paginateRows(displayRows, pagination, { unit }) : { rows: displayRows, pageCount: 1, pageIndex: 0 };
 }
 function narrowToDataRows(pageRows, rows, reshaped) {
   return reshaped ? pageRows.filter((entry) => !("kind" in entry)) : rows;
@@ -1312,7 +1341,12 @@ function createGridViewResolver() {
       rows: pageRows,
       pageCount,
       pageIndex
-    } = page(displayRows, paginated, state.pagination);
+    } = page(
+      displayRows,
+      paginated,
+      state.pagination,
+      options.paginationUnit ?? "group"
+    );
     return assemble(
       dataColumns,
       columns,
@@ -1759,11 +1793,12 @@ function definedColumns(columns, rows) {
   }
   return NO_COLUMNS;
 }
-function pagingInputsOf(state) {
+function pagingInputsOf(state, options) {
   return {
     filter: state.filter,
     columnSort: state.columnSort,
-    groupBy: state.groupBy
+    groupBy: state.groupBy,
+    paginationUnit: options.paginationUnit ?? "group"
   };
 }
 function createGridController(initial) {
@@ -1775,7 +1810,7 @@ function createGridController(initial) {
   const reportedConflicts = /* @__PURE__ */ new Set();
   let heldReports;
   let state = resolveSlices();
-  let pagingInputs = pagingInputsOf(state);
+  let pagingInputs = pagingInputsOf(state, options);
   reportConflicts();
   function controlledValue(key) {
     const controlled = options;
@@ -1817,8 +1852,9 @@ function createGridController(initial) {
   }
   function refresh() {
     let next = resolveSlices();
-    if (next.filter !== pagingInputs.filter || next.columnSort !== pagingInputs.columnSort || next.groupBy !== pagingInputs.groupBy) {
-      pagingInputs = pagingInputsOf(next);
+    const inputs = pagingInputsOf(next, options);
+    if (inputs.filter !== pagingInputs.filter || inputs.columnSort !== pagingInputs.columnSort || inputs.groupBy !== pagingInputs.groupBy || inputs.paginationUnit !== pagingInputs.paginationUnit) {
+      pagingInputs = inputs;
       if (!isControlled("pagination") && own.pagination.pageIndex !== 0) {
         own.pagination = { ...own.pagination, pageIndex: 0 };
         next = { ...next, pagination: own.pagination };
@@ -1854,6 +1890,7 @@ function createGridController(initial) {
       state,
       options: {
         paginated: options.paginated,
+        paginationUnit: options.paginationUnit,
         aggregates: options.aggregates,
         groupAggregateDisplay: options.groupAggregateDisplay,
         columnSizeDefaults: options.columnSizeDefaults,
@@ -1921,20 +1958,22 @@ function createGridController(initial) {
     commit("pagination", next, () => {
       options.onPaginationChange?.({
         pagination: next,
-        pageCount: paginateRows(getView().displayRows, next).pageCount
+        pageCount: pageOf(next).pageCount
       });
     });
   }
+  function pageOf(pagination) {
+    return paginateRows(getView().displayRows, pagination, {
+      unit: options.paginationUnit
+    });
+  }
   function goToPage(pageIndex) {
     const current = state.pagination;
-    const clamped = paginateRows(getView().displayRows, {
-      ...current,
-      pageIndex
-    }).pageIndex;
+    const clamped = pageOf({ ...current, pageIndex }).pageIndex;
     commitPagination({ ...current, pageIndex: clamped });
   }
   function shownPageIndex() {
-    return paginateRows(getView().displayRows, state.pagination).pageIndex;
+    return pageOf(state.pagination).pageIndex;
   }
   const selection = createSelectionActions({
     getState: () => state,
@@ -1961,7 +2000,7 @@ function createGridController(initial) {
         heldReports = void 0;
       }
       if (saved.pagination !== void 0) {
-        pagingInputs = pagingInputsOf(resolveSlices());
+        pagingInputs = pagingInputsOf(resolveSlices(), options);
       }
       refresh();
       for (const report of reports) {
@@ -2123,7 +2162,7 @@ function createGridController(initial) {
       const first = { pageIndex: 0, pageSize };
       commitPagination({
         ...first,
-        pageIndex: paginateRows(getView().displayRows, first).pageIndex
+        pageIndex: pageOf(first).pageIndex
       });
     }
   };
@@ -4167,7 +4206,14 @@ function exportMenu() {
   };
 }
 function resolveToolbar(entries, options) {
-  const { commands, contextFor } = options;
+  const { commands, contextFor, itemAttributes } = options;
+  function withAttributes(item) {
+    if (item.type === "separator" || item.type === "spacer" || itemAttributes === void 0 || !Object.hasOwn(itemAttributes, item.key)) {
+      return item;
+    }
+    const attributes = itemAttributes[item.key];
+    return attributes === void 0 ? item : { ...item, attributes };
+  }
   function resolveEntry(entry, index) {
     if (entry === "search") {
       return { type: "search", key: "search" };
@@ -4199,7 +4245,7 @@ function resolveToolbar(entries, options) {
     return { ...item, type: "button", key: item.id, pressed: checked };
   }
   return collapseSeparators(
-    entries.map(resolveEntry).filter((entry) => entry !== null),
+    entries.map(resolveEntry).filter((entry) => entry !== null).map(withAttributes),
     isSpacer
   );
 }