@gridkitjs/core 0.0.0-dev-20261107202111 → 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
@@ -3035,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
@@ -3050,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.
@@ -4259,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 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 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

@@ -4206,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" };
@@ -4238,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
   );
 }