argus-table 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -150,15 +150,41 @@ interface SortItem {
     /** `true` for descending order. */
     desc: boolean;
 }
-/** The sort order: an empty array when unsorted. v0.1 sorts by one column at a time. */
-type SortState = SortItem[];
+/**
+ * The sort order: an empty array when unsorted. Several items sort by each in turn
+ * (the first decides, the next breaks ties). A header click replaces the order with
+ * that one column; sorting by several columns is set by the host or a plugin.
+ */
+type SortState = readonly SortItem[];
+/**
+ * A header over several columns (`columnGroups`). Groups nest: a group lists column
+ * ids and other groups, and each level of nesting adds a header row above the
+ * column headers. The columns of a group stay next to each other in the column
+ * order; a group whose columns are pinned to different sides shows once per side.
+ */
+interface ColumnGroup$1<TContent = unknown> {
+    /** Stable key. Unique among groups; it may equal a column id. */
+    id: string;
+    /** Header content, or a function returning it. Default: the id. */
+    header?: TContent | (() => TContent);
+    /**
+     * Whether the group can be moved as a whole (a drag on its header, Alt+Shift+Arrow
+     * on it). Default: `true`. Its columns can still move within it.
+     */
+    reorderable?: boolean;
+    /**
+     * The group's columns (by id) and groups, in order. Unknown ids are ignored, and
+     * a column listed twice belongs to the first group that lists it.
+     */
+    columns: readonly (string | ColumnGroup$1<TContent>)[];
+}
 /** Column widths in px set by resizing, keyed by column id. */
 type ColumnSizingState = Record<string, number>;
 /**
  * The column order: column ids as the table shows them (start-pinned, scrolling,
  * end-pinned). An empty array means the order of `columns`.
  */
-type ColumnOrderState = string[];
+type ColumnOrderState = readonly string[];
 /**
  * Pins set at runtime, keyed by column id: `'start'` or `'end'` pins a column, `false`
  * unpins a column whose definition pins it. A column not listed keeps its `pin`.
@@ -208,7 +234,7 @@ interface DateFilter {
 /** Keeps rows whose value is one of `values` (`null` stands for an empty value). */
 interface SetFilter {
     kind: 'set';
-    values: FilterValue[];
+    values: readonly FilterValue[];
 }
 /** One column's filter. */
 type ColumnFilter = TextFilter | NumberFilter | DateFilter | SetFilter;
@@ -223,20 +249,27 @@ type ColumnFilterState = Record<string, ColumnFilter>;
  */
 type SelectionMode = 'none' | 'single' | 'multi';
 /** The selected rows, as row ids (from `getRowId`, or the row's index as a string). */
-type SelectionState = string[];
+type SelectionState = readonly string[];
 /**
  * Where the body is scrolled: the row at the top, as an index in the current row
  * order, and the inline offset in px from the start edge (positive in RTL too).
  */
 interface ScrollState {
+    /** The row at the top, as an index in the current row order. */
     row: number;
-    left: number;
+    /** The inline offset in px from the start edge, positive in RTL too. */
+    inline: number;
 }
 /**
  * The state users change, as one object of plain JSON, for saving a user's layout:
  * `getState()` returns every key, and `setState()` applies the keys it is given.
  */
 interface TableState {
+    /**
+     * The format of the object: `1`. `getState()` sets it; `setState()` ignores an
+     * object with another version, and takes one without it as version 1.
+     */
+    version?: 1;
     sorting?: SortState;
     columnSizing?: ColumnSizingState;
     columnOrder?: ColumnOrderState;
@@ -247,54 +280,60 @@ interface TableState {
     quickFilter?: string;
     scroll?: ScrollState;
 }
-/** `detail` of `argus-row-select`. */
-interface RowSelectDetail {
+/** `detail` of `argus-selection-change`. */
+interface SelectionChangeDetail {
     /** The selected row ids: the new ones, or the proposed ones when `selection` is controlled. */
     selection: SelectionState;
 }
-/** `detail` of `argus-sort-change`. */
-interface SortChangeDetail {
+/** `detail` of `argus-sorting-change`. */
+interface SortingChangeDetail {
+    /** The sort order: the new one, or the proposed one when `sorting` is controlled. */
     sorting: SortState;
 }
-/** `detail` of `argus-column-resize`. */
-interface ColumnResizeDetail {
+/** `detail` of `argus-column-sizing-change`: fires once per column that changed width. */
+interface ColumnSizingChangeDetail {
+    /** The whole new sizing state, or the proposed one when `columnSizing` is controlled. */
+    columnSizing: ColumnSizingState;
+    /** The column resized. */
     columnId: string;
+    /** Its new width in px. */
     width: number;
-    sizing: ColumnSizingState;
 }
-/** `detail` of `argus-column-reorder`. */
-interface ColumnReorderDetail {
-    /** The column that moved. */
+/** `detail` of `argus-column-order-change`. */
+interface ColumnOrderChangeDetail {
+    /** The whole new order, or the proposed one when `columnOrder` is controlled. */
+    columnOrder: ColumnOrderState;
+    /** The column that moved; for a group, its first column that moved. */
     columnId: string;
-    /** The whole new order. */
-    order: ColumnOrderState;
+    /** The group that moved, when a group header was moved rather than a column. */
+    groupId?: string;
 }
-/** `detail` of `argus-column-pin`. */
-interface ColumnPinDetail {
+/** `detail` of `argus-column-pinning-change`: fires when a column is pinned and when it is unpinned. */
+interface ColumnPinningChangeDetail {
+    /** The whole new pinning state, or the proposed one when `columnPinning` is controlled. */
+    columnPinning: ColumnPinningState;
     /** The column pinned or unpinned. */
     columnId: string;
     /** Its new pin, or `false` when it no longer is pinned. */
     pin: ColumnPin | false;
-    /** The whole new pinning state. */
-    pinning: ColumnPinningState;
 }
-/** `detail` of `argus-column-hide`: fires when a column is hidden and when it is shown. */
-interface ColumnHideDetail {
+/** `detail` of `argus-column-visibility-change`: fires when a column is hidden and when it is shown. */
+interface ColumnVisibilityChangeDetail {
+    /** The whole new visibility state, or the proposed one when `columnVisibility` is controlled. */
+    columnVisibility: ColumnVisibilityState;
     /** The column hidden or shown. */
     columnId: string;
-    /** `true` when the column was hidden, `false` when it was shown. */
-    hidden: boolean;
-    /** The whole new visibility state. */
-    visibility: ColumnVisibilityState;
+    /** `true` when the column was shown, `false` when it was hidden: as in `columnVisibility`. */
+    visible: boolean;
 }
-/** `detail` of `argus-column-filter`: fires when a column's filter is set, changed or cleared. */
-interface ColumnFilterDetail {
+/** `detail` of `argus-column-filters-change`: fires when a column's filter is set, changed or cleared. */
+interface ColumnFiltersChangeDetail {
+    /** The whole new filter state, or the proposed one when `columnFilters` is controlled. */
+    columnFilters: ColumnFilterState;
     /** The column filtered. */
     columnId: string;
     /** Its new filter, or `undefined` when it was cleared. */
-    filter: ColumnFilter | undefined;
-    /** The whole new filter state. */
-    filters: ColumnFilterState;
+    columnFilter: ColumnFilter | undefined;
 }
 /** `detail` of `argus-row-click`. */
 interface RowClickDetail<TData> {
@@ -308,15 +347,23 @@ interface RowClickDetail<TData> {
 /** `detail` of `argus-cell-click`. */
 interface CellClickDetail<TData> {
     row: TData;
+    rowId: string;
+    /** Index of the row in the current row order; for a pinned row, its index in its list. */
+    index: number;
     columnId: string;
     value: unknown;
     /** Set when the row is from `pinnedRows`: the side it is pinned to. */
     pinned?: RowPin;
 }
-/** `detail` of `argus-range-change`: the first and last rendered row index (inclusive). */
+/**
+ * `detail` of `argus-range-change`: the first and last row in view, as indexes in the
+ * current order (both inclusive). Rows rendered ahead of the scroll position don't count.
+ */
 interface RangeChangeDetail {
-    start: number;
-    end: number;
+    /** Index of the first row in view. */
+    first: number;
+    /** Index of the last row in view, inclusive. */
+    last: number;
 }
 /** What `getRows()` receives: a range of rows, the sort order, the filters and an abort signal. */
 interface RowsRequest {
@@ -359,6 +406,9 @@ interface LoadErrorDetail {
     end: number;
 }
 
+/** Sort direction of a column, or `false` when it isn't sorted. */
+type SortDirection = 'asc' | 'desc' | false;
+
 /**
  * Renders content the table doesn't render itself, such as React elements, Vue
  * VNodes or Angular templates, into a target element the table keeps. Set it as the
@@ -397,6 +447,8 @@ declare const content: any;
  *
  * Set `columns`, and `data` or `dataSource`, as properties. Columns can also be
  * written as `<argus-column>` children; a non-empty `columns` wins over them.
+ * `columnGroups` (or `<argus-column-group>` children) adds headers over several
+ * columns, a header row per level of nesting.
  * Header and cell content is rendered into the element's light DOM and slotted
  * into the cells, so page CSS and the page's own components work inside cells.
  *
@@ -408,35 +460,45 @@ declare const content: any;
  *
  * @summary Data table with pinned rows and columns and infinite loading.
  *
- * @fires {CustomEvent<SortChangeDetail>} argus-sort-change - A sortable header was clicked, or activated with Enter or Space. `detail: { sorting }`: the new order, or the proposed one when `sorting` is controlled.
- * @fires {CustomEvent<ColumnResizeDetail>} argus-column-resize - A column was resized: by dragging its handle, with Alt+Arrow on its header, by a double-click on its handle (fit to content) or by `autosizeColumns()`. `detail: { columnId, width, sizing }`: the new widths, or the proposed ones when `columnSizing` is controlled. Fires on every frame of a drag, and once per column that `autosizeColumns()` changes.
- * @fires {CustomEvent<ColumnReorderDetail>} argus-column-reorder - A column was moved: by dragging its header, or with Alt+Shift+Arrow on its focused header. Columns move within their own group (start-pinned, scrolling, end-pinned). `detail: { columnId, order }`: the new order, or the proposed one when `columnOrder` is controlled. Fires once per move, on drop.
- * @fires {CustomEvent<ColumnPinDetail>} argus-column-pin - A column was pinned to a side or unpinned, through a plugin such as the column menu. `detail: { columnId, pin, pinning }`: `pin` is `'start'`, `'end'` or `false`; `pinning` is the new state, or the proposed one when `columnPinning` is controlled.
- * @fires {CustomEvent<ColumnHideDetail>} argus-column-hide - A column was hidden or shown, through a plugin such as the column menu. `detail: { columnId, hidden, visibility }`: `hidden` is `true` when it was hidden; `visibility` is the new state, or the proposed one when `columnVisibility` is controlled.
- * @fires {CustomEvent<ColumnFilterDetail>} argus-column-filter - A column's filter was set, changed or cleared, through a plugin such as the column menu. `detail: { columnId, filter, filters }`: `filter` is the column's new filter, or `undefined` when it was cleared; `filters` is the new state, or the proposed one when `columnFilters` is controlled.
- * @fires {CustomEvent<CellClickDetail<T>>} argus-cell-click - A body or pinned-row cell was clicked, or Enter was pressed on it. `detail: { row, columnId, value, pinned? }`; `pinned` is `'top'` or `'bottom'` for a pinned row. Fires before `argus-row-click`.
+ * @fires {CustomEvent<SortingChangeDetail>} argus-sorting-change - `sorting` changed: a sortable header was clicked, or activated with Enter or Space. `detail: { sorting }`. The new value fires after the update that applied it; when the property is controlled, the proposed value fires right away and nothing changes until the host sets it.
+ * @fires {CustomEvent<ColumnSizingChangeDetail>} argus-column-sizing-change - `columnSizing` changed: a column was resized by dragging its handle, with Alt+Arrow on its header, by a double-click on its handle (fit to content) or by `autosizeColumns()`. `detail: { columnSizing, columnId, width }`. Fires on every frame of a drag, and once per column that changes (a group resize, `autosizeColumns()`). The new value fires after the update that applied it; when the property is controlled, the proposed value fires right away and nothing changes until the host sets it.
+ * @fires {CustomEvent<ColumnOrderChangeDetail>} argus-column-order-change - `columnOrder` changed: a column or column group was moved by dragging its header, or with Alt+Shift+Arrow on its focused header. Columns move within their pin side (start-pinned, scrolling, end-pinned) and their column group; groups move as a whole. `detail: { columnOrder, columnId, groupId? }`: `groupId` is set when a group moved, and `columnId` is then its first column. Fires once per move, on drop. The new value fires after the update that applied it; when the property is controlled, the proposed value fires right away and nothing changes until the host sets it.
+ * @fires {CustomEvent<ColumnPinningChangeDetail>} argus-column-pinning-change - `columnPinning` changed: a column was pinned to a side or unpinned, through a plugin such as the column menu. `detail: { columnPinning, columnId, pin }`: `pin` is `'start'`, `'end'` or `false`. The new value fires after the update that applied it; when the property is controlled, the proposed value fires right away and nothing changes until the host sets it.
+ * @fires {CustomEvent<ColumnVisibilityChangeDetail>} argus-column-visibility-change - `columnVisibility` changed: a column was hidden or shown, through a plugin such as the column menu. `detail: { columnVisibility, columnId, visible }`: `visible` is `false` when it was hidden. The new value fires after the update that applied it; when the property is controlled, the proposed value fires right away and nothing changes until the host sets it.
+ * @fires {CustomEvent<ColumnFiltersChangeDetail>} argus-column-filters-change - `columnFilters` changed: a column's filter was set, changed or cleared, through a plugin such as the column menu. `detail: { columnFilters, columnId, columnFilter }`: `columnFilter` is the column's new filter, or `undefined` when it was cleared. The new value fires after the update that applied it; when the property is controlled, the proposed value fires right away and nothing changes until the host sets it.
+ * @fires {CustomEvent<SelectionChangeDetail>} argus-selection-change - `selection` changed: by a click on a row (Ctrl/Cmd toggles, Shift selects a range), with Space, Shift+Arrow or Shift+PageUp/PageDown on a body cell, or with Ctrl/Cmd+A. Only with a `selectionMode`. `detail: { selection }`. The new value fires after the update that applied it; when the property is controlled, the proposed value fires right away and nothing changes until the host sets it.
+ * @fires {CustomEvent<CellClickDetail<T>>} argus-cell-click - A body or pinned-row cell was clicked, or Enter was pressed on it. `detail: { row, rowId, index, columnId, value, pinned? }`; `pinned` is `'top'` or `'bottom'` for a pinned row, and `index` is then its index in its list. Fires before `argus-row-click`.
  * @fires {CustomEvent<RowClickDetail<T>>} argus-row-click - A body or pinned row was clicked, or Enter was pressed on one of its cells. `detail: { row, rowId, index, pinned? }`; for a pinned row, `index` is its index in its list.
- * @fires {CustomEvent<RangeChangeDetail>} argus-range-change - The visible rows changed. `detail: { start, end }` (row indices, inclusive).
- * @fires {CustomEvent<RowSelectDetail>} argus-row-select - The selected rows changed: by a click on a row (Ctrl/Cmd toggles, Shift selects a range), with Space, Shift+Arrow or Shift+PageUp/PageDown on a body cell, or with Ctrl/Cmd+A. Only with a `selectionMode`. `detail: { selection }`: the new row ids, or the proposed ones when `selection` is controlled.
+ * @fires {CustomEvent<RangeChangeDetail>} argus-range-change - The rows in view changed (rows rendered ahead of the scroll position not counted). `detail: { first, last }` (row indices in the current order, both inclusive).
  * @fires {CustomEvent<LoadErrorDetail>} argus-load-error - A `dataSource` page failed to load: `getRows()` rejected or threw. `detail: { error, start, end }` (`end` exclusive). The rows show a Retry button.
  *
  * @slot empty - Shown instead of the body when there are no rows. Default: "No rows".
  *
  * @csspart table - The scroll container that holds header and body.
  * @csspart header - The sticky header row group.
- * @csspart header-row - The header row.
- * @csspart header-cell - Every header cell.
- * @csspart header-cell-sorted - The header of the sorted column. The direction is in `aria-sort`.
+ * @csspart header-row - The row of column headers: the last header row when there are column groups.
+ * @csspart header-group-row - A row of column group headers (`columnGroups`), one per level of nesting, above `header-row`.
+ * @csspart header-group-cell - A column group's header, spanning its columns.
+ * @csspart header-group-cell-dragging - Added to `header-group-cell` on the group being dragged to a new position.
+ * @csspart header-group-filler - The empty cell of a group row over columns without a group at that level.
+ * @csspart header-cell - Every column header.
+ * @csspart header-cell-sorted - Added to `header-cell` on the headers of sorted columns. The direction is also in `aria-sort`.
+ * @csspart header-cell-sorted-asc - Added to `header-cell` on the headers of columns sorted ascending, next to `header-cell-sorted`.
+ * @csspart header-cell-sorted-desc - Added to `header-cell` on the headers of columns sorted descending, next to `header-cell-sorted`.
+ * @csspart header-cell-pinned - Added to `header-cell` on the headers of pinned columns, on either side.
+ * @csspart header-cell-pinned-edge - Added to `header-cell-pinned` on the pinned header next to the scrolling columns (one per pinned side).
+ * @csspart sort-indicator - The chevron in a sortable column's header, shown while it is sorted and pointing the way it sorts. It is drawn with borders in `currentColor`.
  * @csspart header-cell-filtered - Added to `header-cell` on the headers of filtered columns.
  * @csspart filter-indicator - The mark in the header of a filtered column, after the sort indicator.
- * @csspart header-cell-dragging - Added to `header-cell` on the header being dragged to a new position.
- * @csspart drop-indicator - The line on the edge of the header where a dragged column would land.
- * @csspart resize-handle - The drag handle on the inline-end edge of a resizable column's header. A double-click fits the column to its content.
+ * @csspart header-cell-dragging - Added to `header-cell` on the header being dragged to a new position, and on the headers of a dragged group's columns.
+ * @csspart drop-indicator - The line on the edge of the header where a dragged column or group would land.
+ * @csspart resize-handle - The drag handle on the inline-end edge of a resizable column's header, and of a column group's header with resizable columns. A double-click fits the column (or the group's columns) to its content.
  * @csspart body - The row group holding the rendered body rows.
  * @csspart row - Every body row.
  * @csspart row-even - Body rows with an even index (0-based).
  * @csspart row-odd - Body rows with an odd index.
  * @csspart row-loading - Body rows whose `dataSource` page hasn't loaded yet, or failed.
+ * @csspart row-error - Added to `row-loading` on body rows whose `dataSource` page failed to load.
  * @csspart row-selected - Body rows whose id is in `selection`.
  * @csspart cell-selection - Added to `cell` in the checkbox column (`selectionCheckboxes`), pinned rows included.
  * @csspart header-cell-selection - Added to `header-cell` on the checkbox column's header.
@@ -444,11 +506,11 @@ declare const content: any;
  * @csspart row-pinned - Every row from `pinnedRows`, on either side. Also has `row`, but no `row-even`/`row-odd`.
  * @csspart row-pinned-top - The rows pinned below the header.
  * @csspart row-pinned-bottom - The rows pinned to the bottom.
- * @csspart cell-pinned-row - Every cell of a pinned row (next to `cell`).
+ * @csspart cell-in-pinned-row - Every cell of a pinned row (next to `cell`).
  * @csspart cell - Every body cell.
- * @csspart cell-sorted - Body cells in the sorted column.
- * @csspart cell-pinned - Body cells in a pinned column, on either side.
- * @csspart cell-pinned-edge - The pinned body cell next to the scrolling columns (one per pinned side).
+ * @csspart cell-sorted - Body and pinned-row cells in the sorted column.
+ * @csspart cell-pinned - Body and pinned-row cells in a pinned column, on either side.
+ * @csspart cell-pinned-edge - The pinned cell next to the scrolling columns (one per pinned side), in body and pinned rows.
  * @csspart skeleton - The placeholder bar in each cell of a row that is still loading.
  * @csspart skeleton-error - Added to `skeleton` in a row whose page failed to load.
  * @csspart retry - The Retry button in the first cell of a failed page's first visible row.
@@ -461,19 +523,19 @@ declare const content: any;
  * @cssprop [--argus-header-fg=inherit] - Header text colour.
  * @cssprop [--argus-border-color] - Colour of the row borders.
  * @cssprop [--argus-border-width=1px] - Width of the row borders.
- * @cssprop [--argus-outline=none] - Border around the whole table, as a `border` shorthand (`1px solid …`). Inside the element's size.
- * @cssprop [--argus-radius=0] - Corner radius of the table. Header, rows and pinned columns are clipped to it.
- * @cssprop [--argus-row-height] - Height of a row. Default per density: 32px, 40px, 52px. With `rowHeight: 'auto'`: the header's height and the least a body or pinned row is.
+ * @cssprop [--argus-border=none] - Border around the whole table, as a `border` shorthand (`1px solid …`). Inside the element's size. The lines between rows are `--argus-border-width` and `--argus-border-color`.
+ * @cssprop [--argus-border-radius=0] - Corner radius of the table. Header, rows and pinned columns are clipped to it.
+ * @cssprop [--argus-row-height] - Height of a row, and of each header row. Default per density: 32px, 40px, 52px. With `rowHeight: 'auto'`: the height of each header row and the least a body or pinned row is.
  * @cssprop [--argus-cell-padding-inline] - Inline padding of cells. Default per density: 8px, 12px, 16px.
  * @cssprop [--argus-cell-padding-block] - Block padding of body and pinned-row cells with `rowHeight: 'auto'`, where content sits at the top of the cell. Default: what centres one line of text in `--argus-row-height`.
- * @cssprop [--argus-row-stripe-bg] - Background of odd rows. Default: no stripes.
+ * @cssprop [--argus-row-odd-bg] - Background of odd rows. Default: no stripes.
  * @cssprop [--argus-pinned-shadow] - Shadow on the pinned edge, as a `box-shadow` falling toward the end side (`4px 0 6px -4px …`). Mirrored for the end edge and in RTL; `none` removes it.
  * @cssprop [--argus-resize-handle-color] - Colour of the resize handle's line, shown on hover, focus and drag.
  * @cssprop [--argus-focus-ring=2px solid Highlight] - Outline of the focused header or cell.
  * @cssprop [--argus-filter-indicator-color=currentColor] - Colour of the mark in the header of a filtered column.
  * @cssprop [--argus-drop-indicator-color=Highlight] - Colour of the line that marks where a dragged column would land.
  * @cssprop [--argus-row-hover-bg] - Background of the hovered row. Default: no change.
- * @cssprop [--argus-pinned-row-bg=var(--argus-bg)] - Background of the pinned rows, pinned columns included.
+ * @cssprop [--argus-row-pinned-bg=var(--argus-bg)] - Background of the pinned rows, pinned columns included.
  * @cssprop [--argus-skeleton-bg] - Colour of the skeleton bars in rows still loading. Default: the text colour at low opacity.
  * @cssprop [--argus-row-selected-bg] - Background of selected rows, pinned columns included. Default: the system highlight colour, mixed into `--argus-bg`. It wins over `--argus-row-hover-bg`.
  */
@@ -487,6 +549,17 @@ declare class ArgusTable<T = unknown> extends LitElement {
      */
     get columns(): readonly ColumnDef<T>[];
     set columns(value: readonly ColumnDef<T>[] | null | undefined);
+    /**
+     * Headers over several columns: `{ id, header, columns }`, where `columns` lists
+     * column ids and nested groups. Each level of nesting adds a header row. A group's
+     * columns stay next to each other: they move within the group, and the group
+     * moves as a whole (drag its header, or Alt+Shift+Arrow). A group whose columns
+     * are pinned to different sides shows on each side. Property only. While empty
+     * and `columns` is too, the table reads its `<argus-column-group>` children.
+     * `null` or `undefined` means `[]`.
+     */
+    get columnGroups(): readonly ColumnGroup[];
+    set columnGroups(value: readonly ColumnGroup[] | null | undefined);
     /**
      * The rows to show. Replace the array to update; changes inside it aren't
      * detected. `null` or `undefined` means `[]`.
@@ -495,11 +568,12 @@ declare class ArgusTable<T = unknown> extends LitElement {
     set data(value: readonly T[] | null | undefined);
     /**
      * Loads rows page by page as they scroll into view, instead of `data`:
-     * `{ getRows({ start, end, sorting, signal }), pageSize? }`, where `end` is
-     * exclusive and `getRows` resolves to `{ rows, total? }`. Without a `total`,
-     * the table grows as pages arrive and a short page marks the end. Sorting
-     * happens on the server: a new order reloads from the top. While set, it wins
-     * over `data`. Replace the object to change `getRows` or `pageSize`.
+     * `{ getRows({ start, end, sorting, filters, quickFilter, signal }), pageSize? }`,
+     * where `end` is exclusive and `getRows` resolves to `{ rows, total? }`. Without a
+     * `total`, the table grows as pages arrive and a short page marks the end. Sorting
+     * and filtering happen on the server: a new order or filter reloads from the top.
+     * While set, it wins over `data`. Replace the object to change `getRows` or
+     * `pageSize`.
      */
     dataSource?: DataSource<T>;
     /**
@@ -535,12 +609,13 @@ declare class ArgusTable<T = unknown> extends LitElement {
      * explicitly, so page CSS that relies on their order in the DOM (`:nth-child`
      * on cells) doesn't apply. `autosizeColumns()` and `width: 'auto'` columns
      * still measure columns out of view: they render for the measurement.
+     * As an attribute, `virtualize-columns="false"` is off, like no attribute.
      */
     virtualizeColumns: boolean;
     /**
      * The sort order, e.g. `[{ id: 'total', desc: true }]`; `[]` when unsorted. Unset,
      * the table keeps it itself and header clicks change it. Once set, it is
-     * controlled: a click only fires `argus-sort-change` with the proposed order,
+     * controlled: a click only fires `argus-sorting-change` with the proposed order,
      * and nothing changes until you set the property. Set `undefined` to hand it back.
      */
     get sorting(): SortState;
@@ -548,7 +623,7 @@ declare class ArgusTable<T = unknown> extends LitElement {
     /**
      * Resized widths in px by column id, e.g. `{ name: 240 }`. A resized flex column
      * becomes fixed. Uncontrolled until set, like `sorting`: once set, a resize only
-     * fires `argus-column-resize` with the proposed widths. `undefined` hands it back.
+     * fires `argus-column-sizing-change` with the proposed widths. `undefined` hands it back.
      */
     get columnSizing(): ColumnSizingState;
     set columnSizing(value: ColumnSizingState | undefined);
@@ -558,7 +633,7 @@ declare class ArgusTable<T = unknown> extends LitElement {
      * Each pin group (start-pinned, scrolling, end-pinned) takes its columns in this
      * order; unknown ids are ignored and columns it doesn't list follow the listed
      * ones of their group. After a move it holds every column id. Uncontrolled
-     * until set, like `sorting`: once set, a move only fires `argus-column-reorder`
+     * until set, like `sorting`: once set, a move only fires `argus-column-order-change`
      * with the proposed order. `undefined` hands it back.
      */
     get columnOrder(): ColumnOrderState;
@@ -569,7 +644,7 @@ declare class ArgusTable<T = unknown> extends LitElement {
      * `{ total: 'end', id: false }`. Columns it doesn't list keep their `pin`. A pinned
      * column joins the edge of its group nearest its place in `columnOrder`, and stops
      * flexing. Uncontrolled until set, like `sorting`: once set, pinning from a plugin
-     * only fires `argus-column-pin` with the proposed pins. `undefined` hands it back.
+     * only fires `argus-column-pinning-change` with the proposed pins. `undefined` hands it back.
      */
     get columnPinning(): ColumnPinningState;
     set columnPinning(value: ColumnPinningState | undefined);
@@ -579,7 +654,7 @@ declare class ArgusTable<T = unknown> extends LitElement {
      * doesn't list keep their `hidden`. A hidden column isn't rendered, but sorting by
      * it still works and it keeps its place in `columnOrder`. Uncontrolled until set,
      * like `sorting`: once set, hiding or showing from a plugin only fires
-     * `argus-column-hide` with the proposed visibility. `undefined` hands it back.
+     * `argus-column-visibility-change` with the proposed visibility. `undefined` hands it back.
      */
     get columnVisibility(): ColumnVisibilityState;
     set columnVisibility(value: ColumnVisibilityState | undefined);
@@ -591,7 +666,7 @@ declare class ArgusTable<T = unknown> extends LitElement {
      * `dataSource`, the filters go to `getRows()` and the server filters. Users set
      * filters through plugins (the column menu) on columns with a `filter` kind.
      * Uncontrolled until set, like `sorting`: once set, a change from a plugin only
-     * fires `argus-column-filter` with the proposed filters. `undefined` hands it back.
+     * fires `argus-column-filters-change` with the proposed filters. `undefined` hands it back.
      */
     get columnFilters(): ColumnFilterState;
     set columnFilters(value: ColumnFilterState | undefined);
@@ -619,12 +694,13 @@ declare class ArgusTable<T = unknown> extends LitElement {
      * every row, or clears the selection when all are selected. Space on a
      * focused checkbox cell does the same. The column isn't part of `columns`,
      * `columnOrder` or `columnSizing`, and it fires no `argus-cell-click`.
+     * As an attribute, `selection-checkboxes="false"` is off, like no attribute.
      */
     selectionCheckboxes: boolean;
     /**
      * The selected rows, as row ids (from `getRowId`, or the row's index as a
      * string), e.g. `['p4', 'p7']`. Uncontrolled until set, like `sorting`: once
-     * set, a click only fires `argus-row-select` with the proposed ids.
+     * set, a click only fires `argus-selection-change` with the proposed ids.
      * `undefined` hands it back. The table never drops ids on its own: they stay
      * through sorting, a new `data` or reloaded pages. With a `dataSource`,
      * Ctrl/Cmd+A selects the loaded rows only.
@@ -662,7 +738,7 @@ declare class ArgusTable<T = unknown> extends LitElement {
     /**
      * Fits columns to their content: the header, the pinned rows and the body rows
      * rendered now (rows out of view aren't measured). It resizes them like a drag
-     * would, so `argus-column-resize` fires for each column that changes, and with a
+     * would, so `argus-column-sizing-change` fires for each column that changes, and with a
      * controlled `columnSizing` nothing changes until you set it. Without `ids`, fits
      * every resizable column; columns with `resizable: false` keep their width.
      * With `virtualizeColumns`, columns out of view render for the measurement.
@@ -675,7 +751,7 @@ declare class ArgusTable<T = unknown> extends LitElement {
      * The state users change, as one object of plain JSON for saving a user's
      * layout: `sorting`, `columnSizing`, `columnOrder`, `columnPinning`,
      * `columnVisibility`, `columnFilters`, `selection`, `quickFilter`, and `scroll`
-     * (the row at the top and the horizontal offset). Controlled properties are
+     * (the row at the top and the inline offset), with `version: 1`. Controlled properties are
      * included with the values you set. The object is a copy: changing it changes
      * nothing in the table.
      */
@@ -683,7 +759,7 @@ declare class ArgusTable<T = unknown> extends LitElement {
     /**
      * Restores state from `getState()`, for example a layout saved in
      * `localStorage`. Only the keys given change; ids of columns that no longer
-     * exist are ignored. Properties you control are left alone (set them
+     * exist are ignored. State of another `version` is ignored as a whole. Properties you control are left alone (set them
      * yourself), and the others stay uncontrolled. No change events fire.
      * `quickFilter` is set like the property: a search box of yours shows it only
      * if you read it back. `scroll` is applied after the rest, so with a
@@ -717,15 +793,35 @@ interface ArgusPlugin<T = unknown> {
      * runs when the plugin leaves `plugins` or the table is disconnected.
      */
     connect?(host: PluginHost<T>): (() => void) | undefined;
+    /**
+     * Runs at the start of each update of the table, before the `columns` and
+     * `columnGroups` transforms, with the names of the table's properties that
+     * changed (`data`, `columnFilters`, `quickFilter`, `columnVisibility`, …).
+     * Call `host.invalidateColumns()` here to have `columns` run again in this same
+     * update, for columns that depend on more than the column definitions.
+     */
+    willUpdate?(changed: ReadonlySet<string>, host: PluginHost<T>): void;
     /**
      * Changes the column definitions before the table reads them: add computed
      * columns, wrap `header` content, change defaults. Gets the output of the
      * plugin before it (the first one gets `columns` or the `<argus-column>`
      * children). Runs again only when those columns or `plugins` change, or after
      * `host.invalidateColumns()`; a `header` or `cell` function it returns still
-     * runs on every render.
+     * runs on every render. Return `undefined` to leave them as they are.
+     *
+     * Content is `unknown` here: in the framework wrappers, `header` and `cell` return
+     * React nodes or Vue VNodes. Nest a column's own content in a template of the
+     * plugin's through `host.content()`.
      */
-    columns?(defs: readonly ColumnDef<T>[], host: PluginHost<T>): readonly ColumnDef<T>[];
+    columns?(defs: readonly ColumnDef<T, unknown>[], host: PluginHost<T>): readonly ColumnDef<T, unknown>[] | undefined;
+    /**
+     * Changes the column groups before the table reads them, as `columns` does the
+     * columns: wrap a group's `header`, for example. Gets the output of the plugin
+     * before it (the first one gets `columnGroups` or the `<argus-column-group>`
+     * children). Runs again only when those groups or `plugins` change, or after
+     * `host.invalidateColumns()`. Return `undefined` to leave them as they are.
+     */
+    columnGroups?(groups: readonly ColumnGroup<unknown>[], host: PluginHost<T>): readonly ColumnGroup<unknown>[] | undefined;
     /**
      * A key pressed on a focused header or cell, before the table handles it.
      * Return `true` to claim the key: the table then ignores it (call
@@ -760,19 +856,17 @@ interface ColumnInfo {
     /** Current width in px. */
     width: number;
     /** The sort direction, if the table is sorted by this column. */
-    sorted: 'asc' | 'desc' | undefined;
-    /**
-     * The kind of filter users can set (the column's `filter`), or `undefined` when they
-     * can't filter it. Optional, like any later addition.
-     */
-    filter?: FilterKind | undefined;
+    sorted: SortDirection | undefined;
+    /** The kind of filter users can set (the column's `filter`), or `undefined` when they can't filter it. */
+    filter: FilterKind | undefined;
     /** The column's filter in `columnFilters`, if it has one. */
-    filterValue?: ColumnFilter | undefined;
+    columnFilter: ColumnFilter | undefined;
 }
 /**
- * What the table offers a plugin. Plugins get it; they don't implement it.
- * The table's public API (`sorting`, `columnSizing`, `autosizeColumns()`,
- * `updateComplete`) is on `element`.
+ * What the table offers a plugin. Plugins get it; they don't implement it, so
+ * members added in later versions are there too (check the table's version, not
+ * the member). The table's public API (`sorting`, `columnSizing`,
+ * `autosizeColumns()`, `updateComplete`) is on `element`.
  */
 interface PluginHost<T = unknown> {
     readonly element: ArgusTable<T>;
@@ -785,52 +879,61 @@ interface PluginHost<T = unknown> {
      * Every column, hidden ones included, in the column order (start-pinned,
      * scrolling, end-pinned), for lists such as "show hidden columns".
      */
-    columns?(): ColumnInfo[];
+    columns(): ColumnInfo[];
     /** The header or cell an event happened in, if any. */
     cellOf(event: Event): CellTarget | undefined;
     /**
-     * Sorts by a column, or (`null`) clears the sort if it is by that column.
+     * Sorts by a column, or (`undefined`) clears the sort if it is by that column.
      * Follows the `sorting` rules: when it is controlled, only
-     * `argus-sort-change` fires with the proposed order. Does nothing for a
+     * `argus-sorting-change` fires with the proposed order. Does nothing for a
      * column that isn't sortable. Use this rather than setting `sorting`, which
      * would make it controlled.
      */
-    setSort(columnId: string, direction: 'asc' | 'desc' | null): void;
+    setSort(columnId: string, direction: SortDirection | undefined): void;
     /**
      * Pins a column to a side, or (`false`) unpins it. Follows the `columnPinning`
-     * rules: when it is controlled, only `argus-column-pin` fires with the proposed
+     * rules: when it is controlled, only `argus-column-pinning-change` fires with the proposed
      * pins. Does nothing for a column with `pinnable: false`, or without a change.
      */
-    setPin?(columnId: string, pin: ColumnPin | false): void;
+    setPin(columnId: string, pin: ColumnPin | false): void;
     /**
      * Hides or shows a column. Follows the `columnVisibility` rules: when it is
-     * controlled, only `argus-column-hide` fires with the proposed visibility. Does
+     * controlled, only `argus-column-visibility-change` fires with the proposed visibility. Does
      * nothing without a change, when hiding a column with `hideable: false`, or
      * when hiding the last column shown.
      */
-    setHidden?(columnId: string, hidden: boolean): void;
+    setHidden(columnId: string, hidden: boolean): void;
     /**
      * Sets a column's filter, or (`undefined`) clears it. Follows the `columnFilters`
-     * rules: when it is controlled, only `argus-column-filter` fires with the proposed
+     * rules: when it is controlled, only `argus-column-filters-change` fires with the proposed
      * filters. Does nothing without a change, or when setting a filter on a column
      * without `filter`.
      */
-    setFilter?(columnId: string, filter: ColumnFilter | undefined): void;
+    setFilter(columnId: string, filter: ColumnFilter | undefined): void;
     /**
      * The values a `'set'` filter on the column can offer: its `filterOptions`, else the
      * distinct values of the rows the other filters keep, sorted, at most `limit`
      * (default 1000; `truncated` when there are more). `undefined` with a `dataSource`
      * and no `filterOptions`, and for an unknown column.
      */
-    filterValues?(columnId: string, limit?: number): {
+    filterValues(columnId: string, limit?: number): {
         values: FilterValue[];
         truncated: boolean;
     } | undefined;
+    /**
+     * The indexes in `data` of the rows the column filters and the quick filter
+     * keep, ascending (not in the sorted order), leaving out the filters on the
+     * `except` columns and their text in the quick filter: for values computed over
+     * the rows shown, such as a share of a total. `undefined` with a `dataSource`.
+     * A column's `accessor` may call it while the table filters or sorts, as long as
+     * that column is one of `except` (the table doesn't read it for this list).
+     */
+    filteredIndexes(except?: readonly string[]): readonly number[] | undefined;
     /** Moves focus to a column's header, after the next update. */
     focusHeader(columnId: string): void;
     /** Says something to screen readers through a polite live region. */
     announce(message: string): void;
-    /** Runs the plugins' `columns` again on the next update. */
+    /** Runs the plugins' `columns` and `columnGroups` again on the next update. */
     invalidateColumns(): void;
     /** Renders again: header and cell functions run with the plugin's new state. */
     requestUpdate(): void;
@@ -838,14 +941,14 @@ interface PluginHost<T = unknown> {
      * The body row at `index` in the current order (sorted, as shown), or
      * `undefined` past the end and for a `dataSource` row that isn't loaded.
      */
-    row?(index: number): T | undefined;
+    row(index: number): T | undefined;
     /**
      * Wraps a column's own header or cell content for a template of the plugin's: in
      * `html\`<b>${host.content(own)}</b>\``, framework content (React elements, Vue
      * VNodes) still reaches the table's `contentRenderer`, and plain content renders
      * as usual. Use it wherever a plugin nests what `header` or `cell` returned.
      */
-    content?(value: unknown): unknown;
+    content(value: unknown): unknown;
 }
 
 /**
@@ -861,6 +964,11 @@ type CellContent = TemplateResult | Node | string | number;
  * `contentRenderer`.
  */
 type ColumnDef<T = unknown, TContent = CellContent> = ColumnDef$1<T, TContent>;
+/**
+ * A header over several columns (`columnGroups`): an `id`, a `header`, and the
+ * `columns` it spans, by id, with nested groups among them.
+ */
+type ColumnGroup<TContent = CellContent> = ColumnGroup$1<TContent>;
 /** Row density. Each one sets defaults for `--argus-row-height` and `--argus-cell-padding-inline`. */
 type Density = 'compact' | 'comfortable' | 'spacious';
 
@@ -868,8 +976,8 @@ type Density = 'compact' | 'comfortable' | 'spacious';
  * One column of the parent `<argus-table>`, written as markup instead of an entry in
  * its `columns` property. It is data only and renders nothing.
  *
- * Only direct children of the table count, in document order. A non-empty `columns`
- * property wins over the children. Adding, removing, moving or changing a column
+ * Only direct children of the table or of an `<argus-column-group>` count, in
+ * document order. A non-empty `columns` property wins over the children. Adding, removing, moving or changing a column
  * updates the table; sizes, order and sorting are kept by `column-id`.
  *
  * A `<template>` child is the content of every cell in the column (static: the same
@@ -943,6 +1051,7 @@ declare class ArgusColumn<T = unknown> extends ReactiveElement {
      * The column as the table reads it. Unset fields stay `undefined`, which the
      * table reads as its defaults. An unknown `pin` is ignored and an unknown
      * `align` falls back to `start`.
+     * @internal
      */
     toColumnDef(): ColumnDef<T>;
     protected willUpdate(): void;
@@ -954,43 +1063,80 @@ declare global {
     }
 }
 
-/** Fired after an update when the visible row range changed. */
+/**
+ * A header over the `<argus-column>` children it wraps, written as markup instead
+ * of an entry in the table's `columnGroups` property. Groups nest: a group inside
+ * a group adds a header row. It is data only and renders nothing.
+ *
+ * Only direct children of the table or of another group count. A non-empty
+ * `columnGroups` property wins over the children, and a non-empty `columns`
+ * property turns all column and group children off.
+ *
+ * @summary Declarative column group of an `<argus-table>`.
+ */
+declare class ArgusColumnGroup extends ReactiveElement {
+    #private;
+    /** Stable key. Must be unique among the table's groups; it may equal a column id. */
+    groupId: string;
+    /** Header content: text as an attribute; a Lit template, a node or a function as a property. Default: the id. */
+    header?: CellContent | (() => CellContent);
+    /** Whether the group can be moved as a whole. Default: `true`; `reorderable="false"` turns it off. */
+    reorderable?: boolean;
+    /** Data only: no shadow root, nothing rendered. */
+    protected createRenderRoot(): HTMLElement;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * The group as the table reads it, with its column and group children in document order.
+     * @internal
+     */
+    toColumnGroup(): ColumnGroup;
+    protected willUpdate(): void;
+    protected updated(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'argus-column-group': ArgusColumnGroup;
+    }
+}
+
+/** Fired after an update when the rows in view changed. */
 declare const RANGE_CHANGE = "argus-range-change";
-/** Fired after the sort order changed (uncontrolled), or with the proposed order (controlled). */
-declare const SORT_CHANGE = "argus-sort-change";
-/** Fired when a column was resized (uncontrolled), or with the proposed widths (controlled). */
-declare const COLUMN_RESIZE = "argus-column-resize";
-/** Fired when a column was moved (uncontrolled), or with the proposed order (controlled). */
-declare const COLUMN_REORDER = "argus-column-reorder";
-/** Fired when a column was pinned or unpinned (uncontrolled), or with the proposed pins (controlled). */
-declare const COLUMN_PIN = "argus-column-pin";
-/** Fired when a column was hidden or shown (uncontrolled), or with the proposed visibility (controlled). */
-declare const COLUMN_HIDE = "argus-column-hide";
-/** Fired when a column's filter was set, changed or cleared (uncontrolled), or with the proposed filters (controlled). */
-declare const COLUMN_FILTER = "argus-column-filter";
+/** `sorting` changed (uncontrolled), or the proposed order (controlled). */
+declare const SORTING_CHANGE = "argus-sorting-change";
+/** `columnSizing` changed (uncontrolled), or the proposed widths (controlled). Once per column. */
+declare const COLUMN_SIZING_CHANGE = "argus-column-sizing-change";
+/** `columnOrder` changed (uncontrolled), or the proposed order (controlled). */
+declare const COLUMN_ORDER_CHANGE = "argus-column-order-change";
+/** `columnPinning` changed (uncontrolled), or the proposed pins (controlled). */
+declare const COLUMN_PINNING_CHANGE = "argus-column-pinning-change";
+/** `columnVisibility` changed (uncontrolled), or the proposed visibility (controlled). */
+declare const COLUMN_VISIBILITY_CHANGE = "argus-column-visibility-change";
+/** `columnFilters` changed (uncontrolled), or the proposed filters (controlled). */
+declare const COLUMN_FILTERS_CHANGE = "argus-column-filters-change";
+/** `selection` changed (uncontrolled), or the proposed ids (controlled). */
+declare const SELECTION_CHANGE = "argus-selection-change";
 /** Fired when a body row was clicked, after `argus-cell-click`. */
 declare const ROW_CLICK = "argus-row-click";
 /** Fired when a body cell was clicked, before `argus-row-click`. */
 declare const CELL_CLICK = "argus-cell-click";
-/** Fired when the selected rows changed (uncontrolled), or with the proposed ids (controlled). */
-declare const ROW_SELECT = "argus-row-select";
 /** Fired after the update when a `dataSource` page failed to load. */
 declare const LOAD_ERROR = "argus-load-error";
 declare global {
     interface HTMLElementEventMap {
         'argus-range-change': CustomEvent<RangeChangeDetail>;
-        'argus-sort-change': CustomEvent<SortChangeDetail>;
-        'argus-column-resize': CustomEvent<ColumnResizeDetail>;
-        'argus-column-reorder': CustomEvent<ColumnReorderDetail>;
-        'argus-column-pin': CustomEvent<ColumnPinDetail>;
-        'argus-column-hide': CustomEvent<ColumnHideDetail>;
-        'argus-column-filter': CustomEvent<ColumnFilterDetail>;
+        'argus-sorting-change': CustomEvent<SortingChangeDetail>;
+        'argus-column-sizing-change': CustomEvent<ColumnSizingChangeDetail>;
+        'argus-column-order-change': CustomEvent<ColumnOrderChangeDetail>;
+        'argus-column-pinning-change': CustomEvent<ColumnPinningChangeDetail>;
+        'argus-column-visibility-change': CustomEvent<ColumnVisibilityChangeDetail>;
+        'argus-column-filters-change': CustomEvent<ColumnFiltersChangeDetail>;
+        'argus-selection-change': CustomEvent<SelectionChangeDetail>;
         'argus-row-click': CustomEvent<RowClickDetail<unknown>>;
         'argus-cell-click': CustomEvent<CellClickDetail<unknown>>;
         'argus-load-error': CustomEvent<LoadErrorDetail>;
-        'argus-row-select': CustomEvent<RowSelectDetail>;
     }
 }
 
-export { ArgusColumn, ArgusTable, CELL_CLICK, COLUMN_FILTER, COLUMN_HIDE, COLUMN_PIN, COLUMN_REORDER, COLUMN_RESIZE, LOAD_ERROR, RANGE_CHANGE, ROW_CLICK, ROW_SELECT, SORT_CHANGE, content };
-export type { ArgusPlugin, CellClickDetail, CellContent, CellContext, CellTarget, ColumnAlign, ColumnDef, ColumnFilter, ColumnFilterDetail, ColumnFilterState, ColumnHideDetail, ColumnInfo, ColumnOrderState, ColumnPin, ColumnPinDetail, ColumnPinningState, ColumnReorderDetail, ColumnResizeDetail, ColumnSizingState, ColumnVisibilityState, ColumnWidth, ContentRenderer, DataSource, DateFilter, Density, FilterKind, FilterValue, LoadErrorDetail, NumberFilter, PinnedRows, PluginHost, RangeChangeDetail, RangeFilterOp, RowClickDetail, RowPin, RowSelectDetail, RowsRequest, RowsResponse, ScrollState, SelectionMode, SelectionState, SetFilter, SortChangeDetail, SortItem, SortState, TableState, TextFilter, TextFilterOp };
+export { ArgusColumn, ArgusColumnGroup, ArgusTable, CELL_CLICK, COLUMN_FILTERS_CHANGE, COLUMN_ORDER_CHANGE, COLUMN_PINNING_CHANGE, COLUMN_SIZING_CHANGE, COLUMN_VISIBILITY_CHANGE, LOAD_ERROR, RANGE_CHANGE, ROW_CLICK, SELECTION_CHANGE, SORTING_CHANGE, content };
+export type { ArgusPlugin, CellClickDetail, CellContent, CellContext, CellTarget, ColumnAlign, ColumnDef, ColumnFilter, ColumnFilterState, ColumnFiltersChangeDetail, ColumnGroup, ColumnInfo, ColumnOrderChangeDetail, ColumnOrderState, ColumnPin, ColumnPinningChangeDetail, ColumnPinningState, ColumnSizingChangeDetail, ColumnSizingState, ColumnVisibilityChangeDetail, ColumnVisibilityState, ColumnWidth, ContentRenderer, DataSource, DateFilter, Density, FilterKind, FilterValue, LoadErrorDetail, NumberFilter, PinnedRows, PluginHost, RangeChangeDetail, RangeFilterOp, RowClickDetail, RowPin, RowsRequest, RowsResponse, ScrollState, SelectionChangeDetail, SelectionMode, SelectionState, SetFilter, SortDirection, SortItem, SortState, SortingChangeDetail, TableState, TextFilter, TextFilterOp };