argus-table 0.2.1 → 0.3.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 {
@@ -111,6 +159,99 @@ type ColumnSizingState = Record<string, number>;
  * end-pinned). An empty array means the order of `columns`.
  */
 type ColumnOrderState = 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: 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 = 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 {
+    row: number;
+    left: 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 {
+    sorting?: SortState;
+    columnSizing?: ColumnSizingState;
+    columnOrder?: ColumnOrderState;
+    columnPinning?: ColumnPinningState;
+    columnVisibility?: ColumnVisibilityState;
+    columnFilters?: ColumnFilterState;
+    selection?: SelectionState;
+    quickFilter?: string;
+    scroll?: ScrollState;
+}
+/** `detail` of `argus-row-select`. */
+interface RowSelectDetail {
+    /** The selected row ids: the new ones, or the proposed ones when `selection` is controlled. */
+    selection: SelectionState;
+}
 /** `detail` of `argus-sort-change`. */
 interface SortChangeDetail {
     sorting: SortState;
@@ -128,6 +269,33 @@ interface ColumnReorderDetail {
     /** The whole new order. */
     order: ColumnOrderState;
 }
+/** `detail` of `argus-column-pin`. */
+interface ColumnPinDetail {
+    /** 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 {
+    /** 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;
+}
+/** `detail` of `argus-column-filter`: fires when a column's filter is set, changed or cleared. */
+interface ColumnFilterDetail {
+    /** The column filtered. */
+    columnId: string;
+    /** Its new filter, or `undefined` when it was cleared. */
+    filter: ColumnFilter | undefined;
+    /** The whole new filter state. */
+    filters: ColumnFilterState;
+}
 /** `detail` of `argus-row-click`. */
 interface RowClickDetail<TData> {
     row: TData;
@@ -150,7 +318,7 @@ interface RangeChangeDetail {
     start: number;
     end: 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 +326,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;
 }
@@ -188,76 +360,37 @@ interface LoadErrorDetail {
 }
 
 /**
- * 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.
+ * 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.
  */
-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';
-
-/**
- * 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>`.
- */
-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.
@@ -278,9 +411,13 @@ declare global {
  * @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<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<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".
@@ -290,6 +427,8 @@ declare global {
  * @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-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.
@@ -298,6 +437,10 @@ declare global {
  * @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-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.
@@ -320,17 +463,19 @@ declare global {
  * @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-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-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-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-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;
@@ -367,13 +512,31 @@ 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.
+     */
+    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
@@ -400,6 +563,93 @@ declare class ArgusTable<T = unknown> extends LitElement {
      */
     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-pin` 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-hide` 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-filter` 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`.
+     */
+    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.
+     * `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;
     /**
@@ -415,11 +665,32 @@ declare class ArgusTable<T = unknown> extends LitElement {
      * would, so `argus-column-resize` 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 horizontal offset). 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. 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,6 +702,258 @@ declare global {
     }
 }
 
+/**
+ * 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;
+    /**
+     * 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.
+     */
+    columns?(defs: readonly ColumnDef<T>[], host: PluginHost<T>): readonly ColumnDef<T>[];
+    /**
+     * 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: '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;
+    /** The column's filter in `columnFilters`, if it has one. */
+    filterValue?: 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`.
+ */
+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 (`null`) 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
+     * column that isn't sortable. Use this rather than setting `sorting`, which
+     * would make it controlled.
+     */
+    setSort(columnId: string, direction: 'asc' | 'desc' | null): 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
+     * 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-hide` 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-filter` 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;
+    /** 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. */
+    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>;
+/** 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 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`.
+     */
+    toColumnDef(): ColumnDef<T>;
+    protected willUpdate(): void;
+    protected updated(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'argus-column': ArgusColumn;
+    }
+}
+
 /** Fired after an update when the visible row range changed. */
 declare const RANGE_CHANGE = "argus-range-change";
 /** Fired after the sort order changed (uncontrolled), or with the proposed order (controlled). */
@@ -439,10 +962,18 @@ declare const SORT_CHANGE = "argus-sort-change";
 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";
 /** 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 {
@@ -451,11 +982,15 @@ declare global {
         '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-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_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, 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 };