argus-table 0.2.2 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { TemplateResult, ReactiveElement, LitElement, CSSResultGroup, PropertyValues } from 'lit';
+import { LitElement, CSSResultGroup, PropertyValues, TemplateResult, ReactiveElement } from 'lit';
 
 /**
  * Public types shared by `@argus-table/core` and `argus-table`. `argus-table`
@@ -38,7 +38,7 @@ interface CellContext<TData> {
      * `getRowId` gets `'top-0'`, `'bottom-0'` and so on.
      */
     rowId: string;
-    /** Index of the row in the current (sorted) row model; for a pinned row, its index in its list. */
+    /** Index of the row in the current (filtered and sorted) row model; for a pinned row, its index in its list. */
     index: number;
     /** The column's id. */
     columnId: string;
@@ -65,6 +65,12 @@ interface ColumnDef$1<TData, TContent = unknown> {
      * then needs a `cell` function to show anything.
      */
     accessor?: string | ((row: TData, index: number) => unknown);
+    /**
+     * A spreadsheet formula computed per row from other columns, such as
+     * `'[price] * [quantity]'`. The `formulas()` plugin from `@argus-table/formulas`
+     * reads it and replaces `accessor`; without that plugin the table ignores it.
+     */
+    formula?: string;
     /** Custom cell content. Without it, the cell shows the accessor's value as text. */
     cell?: (row: TData, context: CellContext<TData>) => TContent;
     /**
@@ -80,8 +86,16 @@ interface ColumnDef$1<TData, TContent = unknown> {
     minWidth?: number;
     /** Upper bound for resizing, in px. Default: no limit. */
     maxWidth?: number;
-    /** Pins the column to the start or end side. */
+    /**
+     * Pins the column to the start or end side. `columnPinning` overrides it for a
+     * column it lists.
+     */
     pin?: ColumnPin;
+    /**
+     * Hides the column: it isn't rendered, but its values still sort and its formulas
+     * still read it. `columnVisibility` overrides it for a column it lists. Default: `false`.
+     */
+    hidden?: boolean;
     /** Whether the header can be clicked to sort. Default: `false`. */
     sortable?: boolean;
     /** Whether the column can be resized. Default: `true`. */
@@ -92,8 +106,42 @@ interface ColumnDef$1<TData, TContent = unknown> {
      * end-pinned). Other columns can still move past one that sets `false`.
      */
     reorderable?: boolean;
+    /**
+     * Whether the user can pin or unpin the column, for example from the column menu.
+     * Default: `true`. `pin` and `columnPinning` still apply.
+     */
+    pinnable?: boolean;
+    /**
+     * Whether the user can hide the column, for example from the column menu.
+     * Default: `true`. `hidden` and `columnVisibility` still apply.
+     */
+    hideable?: boolean;
+    /**
+     * The kind of filter users can set on the column, for example from the column menu:
+     * `'text'`, `'number'`, `'date'` or `'set'` (pick from a list of values). Without it
+     * users can't filter the column; `columnFilters` still applies.
+     */
+    filter?: FilterKind;
+    /**
+     * Replaces the built-in matching for this column: return `true` to keep the row.
+     * Receives the value read by `accessor`, the column's filter and the row.
+     */
+    filterFn?: (value: unknown, filter: ColumnFilter, row: TData) => boolean;
+    /**
+     * The values a `'set'` filter offers. Needed with a `dataSource`; with `data` the
+     * table lists the distinct values of the column when this isn't set.
+     */
+    filterOptions?: readonly FilterValue[];
     /** Text alignment. Default: `'start'`. */
     align?: ColumnAlign;
+    /**
+     * Wraps the cell text onto more lines instead of cutting it off. Default:
+     * `false`. With a fixed row height the row doesn't grow: one or two lines stay
+     * centred, longer text starts at the top and what doesn't fit is clipped. The
+     * header doesn't wrap. With `width: 'auto'` the column fits its unwrapped
+     * text, up to `maxWidth`.
+     */
+    wrap?: boolean;
 }
 /** One sorted column. */
 interface SortItem {
@@ -102,31 +150,190 @@ 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[];
-/** `detail` of `argus-sort-change`. */
-interface SortChangeDetail {
+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`.
+ */
+type ColumnPinningState = Record<string, ColumnPin | false>;
+/**
+ * Visibility set at runtime, keyed by column id: `false` hides a column, `true` shows
+ * a column whose definition is `hidden`. A column not listed keeps its `hidden`.
+ */
+type ColumnVisibilityState = Record<string, boolean>;
+/** The kinds of filter a column can offer. */
+type FilterKind = 'text' | 'number' | 'date' | 'set';
+/** A value a `'set'` filter can pick. */
+type FilterValue = string | number | boolean | null;
+/** Comparisons of a `'text'` filter. `'empty'` and `'notEmpty'` ignore `value`. */
+type TextFilterOp = 'contains' | 'equals' | 'startsWith' | 'empty' | 'notEmpty';
+/**
+ * Comparisons of a `'number'` or `'date'` filter. `'between'` is inclusive and needs
+ * `to`; `'empty'` and `'notEmpty'` ignore `value`.
+ */
+type RangeFilterOp = 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge' | 'between' | 'empty' | 'notEmpty';
+/** Keeps rows whose value as text matches, ignoring case. */
+interface TextFilter {
+    kind: 'text';
+    op: TextFilterOp;
+    value?: string;
+}
+/** Keeps rows whose number compares as `op` says. */
+interface NumberFilter {
+    kind: 'number';
+    op: RangeFilterOp;
+    value?: number;
+    /** The upper bound of `'between'`. */
+    to?: number;
+}
+/**
+ * Keeps rows whose date compares as `op` says, by local day. `value` and `to` are
+ * ISO dates (`'2026-11-10'`); cell values can be `Date`s, timestamps or ISO strings.
+ */
+interface DateFilter {
+    kind: 'date';
+    op: RangeFilterOp;
+    value?: string;
+    /** The last day of `'between'`. */
+    to?: string;
+}
+/** Keeps rows whose value is one of `values` (`null` stands for an empty value). */
+interface SetFilter {
+    kind: 'set';
+    values: readonly FilterValue[];
+}
+/** One column's filter. */
+type ColumnFilter = TextFilter | NumberFilter | DateFilter | SetFilter;
+/**
+ * Filters set at runtime, keyed by column id. A row shows when it passes every filter
+ * (and `quickFilter`). Filters on hidden columns still apply; unknown ids are ignored.
+ */
+type ColumnFilterState = Record<string, ColumnFilter>;
+/**
+ * How rows can be selected: `'none'` (the default), `'single'` (one row at a time)
+ * or `'multi'` (any number, with Ctrl/Cmd and Shift).
+ */
+type SelectionMode = 'none' | 'single' | 'multi';
+/** The selected rows, as row ids (from `getRowId`, or the row's index as a 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;
+    /** 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;
+    columnPinning?: ColumnPinningState;
+    columnVisibility?: ColumnVisibilityState;
+    columnFilters?: ColumnFilterState;
+    selection?: SelectionState;
+    quickFilter?: string;
+    scroll?: ScrollState;
+}
+/** `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-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 group that moved, when a group header was moved rather than a column. */
+    groupId?: string;
+}
+/** `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;
-    /** The whole new order. */
-    order: ColumnOrderState;
+    /** Its new pin, or `false` when it no longer is pinned. */
+    pin: ColumnPin | false;
+}
+/** `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 shown, `false` when it was hidden: as in `columnVisibility`. */
+    visible: boolean;
+}
+/** `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. */
+    columnFilter: ColumnFilter | undefined;
 }
 /** `detail` of `argus-row-click`. */
 interface RowClickDetail<TData> {
@@ -140,17 +347,25 @@ 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 and an abort signal. */
+/** What `getRows()` receives: a range of rows, the sort order, the filters and an abort signal. */
 interface RowsRequest {
     /** Index of the first row, inclusive. */
     start: number;
@@ -158,6 +373,10 @@ interface RowsRequest {
     end: number;
     /** The current sort order; sorting happens on the server. `[]` when unsorted. */
     sorting: SortState;
+    /** The column filters; filtering happens on the server. `{}` when nothing is filtered. */
+    filters: ColumnFilterState;
+    /** The `quickFilter` text to match in any column. `''` when unset. */
+    quickFilter: string;
     /** Aborted when the rows are no longer needed: scrolled far away, or the source was reset. */
     signal: AbortSignal;
 }
@@ -187,83 +406,49 @@ interface LoadErrorDetail {
     end: number;
 }
 
-/**
- * What a column's `header` or `cell` may produce: a Lit template, a DOM node, or
- * text. The content is rendered into the table's light DOM and slotted into the
- * cell, so page CSS and the page's own components work inside it.
- */
-type CellContent = TemplateResult | Node | string | number;
-/** One column of `<argus-table>`: what it shows, how wide it is, and how it behaves. */
-type ColumnDef<T = unknown> = ColumnDef$1<T, CellContent>;
-/** Row density. Each one sets defaults for `--argus-row-height` and `--argus-cell-padding-inline`. */
-type Density = 'compact' | 'comfortable' | 'spacious';
+/** Sort direction of a column, or `false` when it isn't sorted. */
+type SortDirection = 'asc' | 'desc' | false;
 
 /**
- * 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
- * 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
- * for each row). Set the `cell` property for content that depends on the row.
- *
- * @summary Declarative column of an `<argus-table>`.
+ * 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
+ * table's `contentRenderer`; the framework wrappers do.
  */
-declare class ArgusColumn<T = unknown> extends ReactiveElement {
-    #private;
-    /** Stable key, used in state objects, events and persistence. Must be unique within the table. */
-    columnId: string;
-    /** Header content: text as an attribute; a Lit template, a node or a function as a property. */
-    header?: CellContent | (() => CellContent);
+interface ContentRenderer {
     /**
-     * How to read the cell value: a property path such as `customer.name`, or (as a
-     * property) a function of the row and its index.
+     * Renders `content` into `target`, or updates what is there. Called on every update
+     * for each header and cell showing foreign content. A target is reused: when the
+     * table scrolls, the same target shows other rows.
      */
-    accessor?: string | ((row: T, index: number) => unknown);
-    /** Cell content from the row: `(row, context) => content`. Property only; wins over a `<template>` child. */
-    cell?: (row: T, context: CellContext<T>) => CellContent;
-    /** Width: `90` (px), `auto` to fit the content, or `2fr` for a share of the free space. Default: 150 px. */
-    width?: ColumnWidth;
-    /** Lower bound for resizing and for flex columns, in px. Default: 40. */
-    minWidth?: number;
-    /** Upper bound for resizing, in px. Default: no limit. */
-    maxWidth?: number;
-    /** Pins the column to the `start` or `end` side. */
-    pin?: ColumnPin;
-    /** Text alignment: `start`, `center` or `end`. Default: `start`. */
-    align?: ColumnAlign;
-    /** Whether the header can be clicked to sort. Default: `false`. */
-    sortable?: boolean;
-    /** Whether the column can be resized. Default: `true`; `resizable="false"` turns it off. */
-    resizable?: boolean;
-    /** Whether the column can be moved. Default: `true`; `reorderable="false"` turns it off. */
-    reorderable?: boolean;
-    /** Data only: no shadow root, nothing rendered. */
-    protected createRenderRoot(): HTMLElement;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
+    render(target: HTMLElement, content: unknown): void;
     /**
-     * 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`.
+     * `target` shows no foreign content any more: its cell scrolled away and wasn't
+     * reused, its row isn't loaded, its column left, or the table was disconnected.
+     * Unmount what `render` put there.
      */
-    toColumnDef(): ColumnDef<T>;
-    protected willUpdate(): void;
-    protected updated(): void;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        'argus-column': ArgusColumn;
-    }
+    release(target: HTMLElement): void;
+    /**
+     * Called once after each update in which `render` or `release` ran, before the
+     * table measures content (`width: 'auto'`). Commit batched work here, synchronously.
+     */
+    flush?(): void;
 }
+/**
+ * Header or cell content for a template of your own. The table renders what
+ * `header` and `cell` return through it already; a plugin that nests a column's
+ * content in its own template (`html\`<b>${content(own)}</b>\``) wraps it, so
+ * framework content (React elements, Vue VNodes) still reaches the
+ * `contentRenderer`. Only in templates the table renders.
+ */
+declare const content: any;
 
 /**
  * A virtualized data table.
  *
  * 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.
  *
@@ -275,37 +460,57 @@ declare global {
  *
  * @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<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<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-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-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, 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.
+ * @csspart selection-checkbox - The checkboxes of the checkbox column: one per selectable row, and the select-all one in the header (`multi` mode).
  * @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.
@@ -318,19 +523,21 @@ declare global {
  * @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.
+ * @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-row-stripe-bg] - Background of odd rows. Default: no stripes.
+ * @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-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] - Reserved for row selection, which comes after v0.1. The table doesn't read it yet.
+ * @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`.
  */
 declare class ArgusTable<T = unknown> extends LitElement {
     #private;
@@ -342,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 `[]`.
@@ -350,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>;
     /**
@@ -367,17 +586,36 @@ declare class ArgusTable<T = unknown> extends LitElement {
     pinnedRows?: PinnedRows<T>;
     /** Returns a stable id for a row. Default: the row's index (in `data`, or among all `dataSource` rows). */
     getRowId?: (row: T, index: number) => string;
-    /** Row height in px. Unset: the density (or the `--argus-row-height` token) decides. */
-    rowHeight?: number;
+    /**
+     * Row height in px, or `'auto'` to fit each row to its content (`row-height="auto"`).
+     * Unset: the density (or the `--argus-row-height` token) decides. With
+     * `'auto'`, that height is the header's and the least a body or pinned row is;
+     * rows grow to fit wrapped text (`wrap` columns) and taller content, and cell
+     * content sits at the top. Rows are measured as they render: a row's height
+     * counts the columns rendered (see `virtualizeColumns`), and rows not seen yet
+     * count as one line. Give images a size, so rows don't move when they load.
+     */
+    rowHeight?: number | 'auto';
     /** Row density: `compact`, `comfortable` or `spacious`. */
     density: Density;
     /** Rows rendered above and below the visible ones. `null` or `undefined` means the default, 6. */
     get overscan(): number;
     set overscan(value: number | null | undefined);
+    /**
+     * Renders only the scrolling columns in view (plus two on each side), for
+     * wide tables: a few dozen columns and more. Pinned columns, the checkbox
+     * column and the focused cell's column always render. Off by default: then
+     * every column renders, as before. Cells are placed in their grid column
+     * 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;
@@ -385,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);
@@ -395,11 +633,99 @@ 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;
     set columnOrder(value: ColumnOrderState | undefined);
+    /**
+     * Pins by column id, over the columns' own `pin`: `'start'` or `'end'` pins a
+     * column, `false` unpins one whose definition pins it, e.g.
+     * `{ 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-pinning-change` with the proposed pins. `undefined` hands it back.
+     */
+    get columnPinning(): ColumnPinningState;
+    set columnPinning(value: ColumnPinningState | undefined);
+    /**
+     * Visibility by column id, over the columns' own `hidden`: `false` hides a column,
+     * `true` shows one defined as `hidden`, e.g. `{ email: false }`. Columns it
+     * 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-visibility-change` with the proposed visibility. `undefined` hands it back.
+     */
+    get columnVisibility(): ColumnVisibilityState;
+    set columnVisibility(value: ColumnVisibilityState | undefined);
+    /**
+     * Filters by column id, e.g. `{ city: { kind: 'set', values: ['Berlin'] } }` or
+     * `{ total: { kind: 'number', op: 'gt', value: 100 } }`. A row shows when it passes
+     * every filter and `quickFilter`. Filters on hidden columns still apply; unknown ids
+     * are ignored. A column's `filterFn` replaces the built-in matching. With a
+     * `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-filters-change` with the proposed filters. `undefined` hands it back.
+     */
+    get columnFilters(): ColumnFilterState;
+    set columnFilters(value: ColumnFilterState | undefined);
+    /**
+     * Shows only rows that contain each word of this text in one of their shown
+     * columns, ignoring case, e.g. from a search box. Values are matched as text
+     * (dates as `2026-11-10`); objects aren't searched. With a `dataSource`, it goes
+     * to `getRows()` and the server filters. `''` (the default) shows every row.
+     */
+    get quickFilter(): string;
+    set quickFilter(value: string | null | undefined);
+    /**
+     * How rows can be selected: `none` (the default), `single` or `multi`. A click
+     * on a body row selects it; in `multi` mode Ctrl/Cmd+click toggles a row,
+     * Shift+click selects the range from the last clicked row, and Ctrl/Cmd+A
+     * selects every row. Space toggles the focused row. Clicks on buttons, links
+     * and inputs inside cells don't select. Pinned rows, and `dataSource` rows not
+     * loaded yet, can't be selected.
+     */
+    selectionMode: SelectionMode;
+    /**
+     * Adds a checkbox column, pinned first at the start, while `selectionMode` is
+     * `single` or `multi`. A row's checkbox toggles it (Shift+click adds the range
+     * from the last row clicked); in `multi` mode the header's checkbox selects
+     * 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-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.
+     */
+    get selection(): SelectionState;
+    set selection(value: SelectionState | undefined);
+    /**
+     * Renders header and cell content the table can't render itself, such as React
+     * elements, Vue VNodes or Angular templates: `{ render(target, content),
+     * release(target), flush?() }`. A `header` or `cell` that returns anything other
+     * than a string, a number, a DOM node or a Lit template hands it to the renderer,
+     * with a target element the table keeps while the cell is reused for other rows.
+     * The framework wrappers set it; set it yourself only for another framework.
+     */
+    contentRenderer?: ContentRenderer;
+    /**
+     * Add-ons, such as `headerMenu()` from `@argus-table/header-menu`. Each one can
+     * change the column definitions, handle keys on a focused header or cell, and
+     * use the table through a small API. They run in array order. Replace the
+     * array to change them; an array with the same plugins in the same order
+     * changes nothing. `null` or `undefined` means `[]`.
+     */
+    get plugins(): readonly ArgusPlugin<T>[];
+    set plugins(value: readonly ArgusPlugin<T>[] | null | undefined);
+    constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
     /**
@@ -412,14 +738,35 @@ 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.
      * Resolves once the table has re-rendered.
      */
     autosizeColumns(ids?: readonly string[]): Promise<void>;
     /** Scrolls so that the row at `index` (in the current row order) is at the top. */
     scrollToRow(index: number): Promise<void>;
+    /**
+     * 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 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.
+     */
+    getState(): Required<TableState>;
+    /**
+     * 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. 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
+     * `dataSource` the restored rows load where it points. Resolves once the table
+     * has re-rendered there.
+     */
+    setState(state: TableState): Promise<void>;
     protected willUpdate(changed: PropertyValues<this>): void;
     protected render(): TemplateResult;
     protected firstUpdated(): void;
@@ -431,14 +778,344 @@ declare global {
     }
 }
 
-/** Fired after an update when the visible row range changed. */
+/**
+ * An add-on for `<argus-table>`, set through its `plugins` property:
+ * `table.plugins = [headerMenu()]`. Every member is optional except `name`.
+ * Plugins run in array order. A plugin that throws is reported in the console
+ * and skipped; it never breaks the table.
+ */
+interface ArgusPlugin<T = unknown> {
+    /** Names the plugin in error messages. */
+    readonly name: string;
+    /**
+     * Runs when the plugin joins a connected table, and again each time the
+     * table is connected after a disconnect. Returns a cleanup function, which
+     * 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. 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, 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
+     * `event.preventDefault()` yourself). Keys pressed in content inside a cell
+     * don't come here, nor do keys on the checkbox column.
+     */
+    keydown?(event: KeyboardEvent, target: CellTarget, host: PluginHost<T>): boolean | undefined;
+}
+/** A header or cell of the grid, as plugins see it. */
+interface CellTarget {
+    /** The header row, the pinned rows (`top`, `bottom`) or the body. */
+    section: 'header' | 'top' | 'body' | 'bottom';
+    columnId: string;
+    /** The row's index in its section: in the current order for the body, in its list for a pinned row; `0` for the header. */
+    rowIndex: number;
+    /** The row's id; `undefined` for the header. */
+    rowId: string | undefined;
+}
+/** A column as the table resolved it. */
+interface ColumnInfo {
+    id: string;
+    sortable: boolean;
+    resizable: boolean;
+    /** Whether the user may pin and unpin it (`pinnable`). */
+    pinnable: boolean;
+    /** Whether the user may hide it (`hideable`). */
+    hideable: boolean;
+    /** The pin in effect: `columnPinning`'s, else the column's own. */
+    pin: ColumnPin | undefined;
+    /** `true` while the column is hidden (`columnVisibility`, else the column's `hidden`). */
+    hidden: boolean;
+    /** Current width in px. */
+    width: number;
+    /** The sort direction, if the table is sorted by this column. */
+    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. */
+    columnFilter: ColumnFilter | undefined;
+}
+/**
+ * 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>;
+    /**
+     * A column of `columns` (or the children) as resolved, after every plugin's
+     * `columns`. Hidden columns too, with `hidden: true`.
+     */
+    column(id: string): ColumnInfo | undefined;
+    /**
+     * Every column, hidden ones included, in the column order (start-pinned,
+     * scrolling, end-pinned), for lists such as "show hidden columns".
+     */
+    columns(): ColumnInfo[];
+    /** The header or cell an event happened in, if any. */
+    cellOf(event: Event): CellTarget | undefined;
+    /**
+     * 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-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: SortDirection | undefined): void;
+    /**
+     * Pins a column to a side, or (`false`) unpins it. Follows the `columnPinning`
+     * 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;
+    /**
+     * Hides or shows a column. Follows the `columnVisibility` rules: when it is
+     * 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;
+    /**
+     * Sets a column's filter, or (`undefined`) clears it. Follows the `columnFilters`
+     * 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;
+    /**
+     * 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): {
+        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` and `columnGroups` again on the next update. */
+    invalidateColumns(): void;
+    /** Renders again: header and cell functions run with the plugin's new state. */
+    requestUpdate(): void;
+    /**
+     * 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;
+    /**
+     * 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;
+}
+
+/**
+ * What a column's `header` or `cell` may produce: a Lit template, a DOM node, or
+ * text. The content is rendered into the table's light DOM and slotted into the
+ * cell, so page CSS and the page's own components work inside it.
+ */
+type CellContent = TemplateResult | Node | string | number;
+/**
+ * One column of `<argus-table>`: what it shows, how wide it is, and how it behaves.
+ * `TContent` is what `header` and `cell` may return; the framework wrappers widen it
+ * to their own content (React nodes, Vue VNodes), which reaches the table's
+ * `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';
+
+/**
+ * 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 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
+ * for each row). Set the `cell` property for content that depends on the row.
+ *
+ * The standard `hidden` attribute (or property) hides the column, like `hidden` in
+ * `columns`; the table's `columnVisibility` overrides it.
+ *
+ * @summary Declarative column of an `<argus-table>`.
+ */
+declare class ArgusColumn<T = unknown> extends ReactiveElement {
+    #private;
+    /** Stable key, used in state objects, events and persistence. Must be unique within the table. */
+    columnId: string;
+    /** Header content: text as an attribute; a Lit template, a node or a function as a property. */
+    header?: CellContent | (() => CellContent);
+    /**
+     * How to read the cell value: a property path such as `customer.name`, or (as a
+     * property) a function of the row and its index.
+     */
+    accessor?: string | ((row: T, index: number) => unknown);
+    /**
+     * A spreadsheet formula computed per row from other columns, such as
+     * `[price] * [quantity]`. Needs the `formulas()` plugin from `@argus-table/formulas`.
+     */
+    formula?: string;
+    /** Cell content from the row: `(row, context) => content`. Property only; wins over a `<template>` child. */
+    cell?: (row: T, context: CellContext<T>) => CellContent;
+    /** Width: `90` (px), `auto` to fit the content, or `2fr` for a share of the free space. Default: 150 px. */
+    width?: ColumnWidth;
+    /** Lower bound for resizing and for flex columns, in px. Default: 40. */
+    minWidth?: number;
+    /** Upper bound for resizing, in px. Default: no limit. */
+    maxWidth?: number;
+    /** Pins the column to the `start` or `end` side. The table's `columnPinning` overrides it. */
+    pin?: ColumnPin;
+    /** Whether the user can pin or unpin the column. Default: `true`; `pinnable="false"` turns it off. */
+    pinnable?: boolean;
+    /** Whether the user can hide the column. Default: `true`; `hideable="false"` turns it off. */
+    hideable?: boolean;
+    /** Text alignment: `start`, `center` or `end`. Default: `start`. */
+    align?: ColumnAlign;
+    /**
+     * Wraps the cell text onto more lines instead of cutting it off. Default:
+     * `false`. With a fixed row height, text that doesn't fit is clipped.
+     */
+    wrap?: boolean;
+    /** Whether the header can be clicked to sort. Default: `false`. */
+    sortable?: boolean;
+    /** Whether the column can be resized. Default: `true`; `resizable="false"` turns it off. */
+    resizable?: boolean;
+    /** Whether the column can be moved. Default: `true`; `reorderable="false"` turns it off. */
+    reorderable?: boolean;
+    /**
+     * The kind of filter users can set, e.g. from the column menu: `text`, `number`,
+     * `date` or `set`. Unset: users can't filter the column.
+     */
+    filter?: FilterKind;
+    /** Replaces the built-in matching for this column's filter. Property only. */
+    filterFn?: ColumnDef<T>['filterFn'];
+    /** The values a `set` filter offers; needed with a `dataSource`. Property only. */
+    filterOptions?: readonly FilterValue[];
+    /** `hidden` is the standard attribute: it updates the column like its own properties. */
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
+    /** Data only: no shadow root, nothing rendered. */
+    protected createRenderRoot(): HTMLElement;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * 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;
+    protected updated(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'argus-column': ArgusColumn;
+    }
+}
+
+/**
+ * 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";
+/** `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`. */
@@ -448,14 +1125,18 @@ 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-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>;
     }
 }
 
-export { ArgusColumn, ArgusTable, CELL_CLICK, COLUMN_REORDER, COLUMN_RESIZE, LOAD_ERROR, RANGE_CHANGE, ROW_CLICK, SORT_CHANGE };
-export type { CellClickDetail, CellContent, CellContext, ColumnAlign, ColumnDef, ColumnOrderState, ColumnPin, ColumnReorderDetail, ColumnResizeDetail, ColumnSizingState, ColumnWidth, DataSource, Density, LoadErrorDetail, PinnedRows, RangeChangeDetail, RowClickDetail, RowPin, RowsRequest, RowsResponse, SortChangeDetail, SortItem, SortState };
+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 };