argus-table 0.0.1 → 0.2.0

package/dist/events.js

@@ -5,10 +5,14 @@ var RANGE_CHANGE = "argus-range-change";
 var SORT_CHANGE = "argus-sort-change";
 /** Fired when a column was resized (uncontrolled), or with the proposed widths (controlled). */
 var COLUMN_RESIZE = "argus-column-resize";
+/** Fired when a column was moved (uncontrolled), or with the proposed order (controlled). */
+var COLUMN_REORDER = "argus-column-reorder";
 /** Fired when a body row was clicked, after `argus-cell-click`. */
 var ROW_CLICK = "argus-row-click";
 /** Fired when a body cell was clicked, before `argus-row-click`. */
 var CELL_CLICK = "argus-cell-click";
+/** Fired after the update when a `dataSource` page failed to load. */
+var LOAD_ERROR = "argus-load-error";
 /** Dispatches a bubbling, composed `CustomEvent`, the shape of every public event. */
 function fire(host, name, detail) {
 	return host.dispatchEvent(new CustomEvent(name, {
@@ -17,6 +21,6 @@ function fire(host, name, detail) {
 		composed: true
 	}));
 }
-export { CELL_CLICK, COLUMN_RESIZE, RANGE_CHANGE, ROW_CLICK, SORT_CHANGE, fire };
+export { CELL_CLICK, COLUMN_REORDER, COLUMN_RESIZE, LOAD_ERROR, RANGE_CHANGE, ROW_CLICK, SORT_CHANGE, fire };
 
 //# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","names":[],"sources":["../src/events.ts"],"sourcesContent":["import type {\n  CellClickDetail,\n  ColumnResizeDetail,\n  RangeChangeDetail,\n  RowClickDetail,\n  SortChangeDetail,\n} from '@argus-table/core';\n\n/** Fired after an update when the visible row range changed. */\nexport const RANGE_CHANGE = 'argus-range-change';\n\n/** Fired after the sort order changed (uncontrolled), or with the proposed order (controlled). */\nexport const SORT_CHANGE = 'argus-sort-change';\n\n/** Fired when a column was resized (uncontrolled), or with the proposed widths (controlled). */\nexport const COLUMN_RESIZE = 'argus-column-resize';\n\n/** Fired when a body row was clicked, after `argus-cell-click`. */\nexport const ROW_CLICK = 'argus-row-click';\n\n/** Fired when a body cell was clicked, before `argus-row-click`. */\nexport const CELL_CLICK = 'argus-cell-click';\n\ndeclare global {\n  interface HTMLElementEventMap {\n    'argus-range-change': CustomEvent<RangeChangeDetail>;\n    'argus-sort-change': CustomEvent<SortChangeDetail>;\n    'argus-column-resize': CustomEvent<ColumnResizeDetail>;\n    'argus-row-click': CustomEvent<RowClickDetail<unknown>>;\n    'argus-cell-click': CustomEvent<CellClickDetail<unknown>>;\n  }\n}\n\n/** Dispatches a bubbling, composed `CustomEvent`, the shape of every public event. */\nexport function fire(host: HTMLElement, name: string, detail: unknown): boolean {\n  return host.dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true }));\n}\n"],"mappings":";;AASA,IAAa,eAAe;;AAG5B,IAAa,cAAc;;AAG3B,IAAa,gBAAgB;;AAG7B,IAAa,YAAY;;AAGzB,IAAa,aAAa;;AAa1B,SAAgB,KAAK,MAAmB,MAAc,QAA0B;CAC9E,OAAO,KAAK,cAAc,IAAI,YAAY,MAAM;EAAE;EAAQ,SAAS;EAAM,UAAU;CAAK,CAAC,CAAC;AAC5F"}
+{"version":3,"file":"events.js","names":[],"sources":["../src/events.ts"],"sourcesContent":["import type {\n  CellClickDetail,\n  ColumnReorderDetail,\n  ColumnResizeDetail,\n  LoadErrorDetail,\n  RangeChangeDetail,\n  RowClickDetail,\n  SortChangeDetail,\n} from '@argus-table/core';\n\n/** Fired after an update when the visible row range changed. */\nexport const RANGE_CHANGE = 'argus-range-change';\n\n/** Fired after the sort order changed (uncontrolled), or with the proposed order (controlled). */\nexport const SORT_CHANGE = 'argus-sort-change';\n\n/** Fired when a column was resized (uncontrolled), or with the proposed widths (controlled). */\nexport const COLUMN_RESIZE = 'argus-column-resize';\n\n/** Fired when a column was moved (uncontrolled), or with the proposed order (controlled). */\nexport const COLUMN_REORDER = 'argus-column-reorder';\n\n/** Fired when a body row was clicked, after `argus-cell-click`. */\nexport const ROW_CLICK = 'argus-row-click';\n\n/** Fired when a body cell was clicked, before `argus-row-click`. */\nexport const CELL_CLICK = 'argus-cell-click';\n\n/** Fired after the update when a `dataSource` page failed to load. */\nexport const LOAD_ERROR = 'argus-load-error';\n\ndeclare global {\n  interface HTMLElementEventMap {\n    'argus-range-change': CustomEvent<RangeChangeDetail>;\n    'argus-sort-change': CustomEvent<SortChangeDetail>;\n    'argus-column-resize': CustomEvent<ColumnResizeDetail>;\n    'argus-column-reorder': CustomEvent<ColumnReorderDetail>;\n    'argus-row-click': CustomEvent<RowClickDetail<unknown>>;\n    'argus-cell-click': CustomEvent<CellClickDetail<unknown>>;\n    'argus-load-error': CustomEvent<LoadErrorDetail>;\n  }\n}\n\n/** Dispatches a bubbling, composed `CustomEvent`, the shape of every public event. */\nexport function fire(host: HTMLElement, name: string, detail: unknown): boolean {\n  return host.dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true }));\n}\n"],"mappings":";;AAWA,IAAa,eAAe;;AAG5B,IAAa,cAAc;;AAG3B,IAAa,gBAAgB;;AAG7B,IAAa,iBAAiB;;AAG9B,IAAa,YAAY;;AAGzB,IAAa,aAAa;;AAG1B,IAAa,aAAa;;AAe1B,SAAgB,KAAK,MAAmB,MAAc,QAA0B;CAC9E,OAAO,KAAK,cAAc,IAAI,YAAY,MAAM;EAAE;EAAQ,SAAS;EAAM,UAAU;CAAK,CAAC,CAAC;AAC5F"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { TemplateResult, LitElement, CSSResultGroup, PropertyValues } from 'lit';
+import { TemplateResult, ReactiveElement, LitElement, CSSResultGroup, PropertyValues } from 'lit';
 
 /**
  * Public types shared by `@argus-table/core` and `argus-table`. `argus-table`
@@ -8,27 +8,44 @@ import { TemplateResult, LitElement, CSSResultGroup, PropertyValues } from 'lit'
  */
 /** Logical side of a pinned column: `'start'` is the left in LTR and the right in RTL. */
 type ColumnPin = 'start' | 'end';
+/** Side of a pinned row: `'top'` (below the header) or `'bottom'`. */
+type RowPin = 'top' | 'bottom';
+/**
+ * Rows fixed above or below the scrolling body, such as a totals row. They are
+ * separate objects, not rows of `data`: never sorted, and not counted as data rows.
+ */
+interface PinnedRows<TData> {
+    /** Rows pinned below the header, in order. */
+    top?: readonly TData[];
+    /** Rows pinned to the bottom, in order. */
+    bottom?: readonly TData[];
+}
 /** Text alignment inside a cell, in logical terms. */
 type ColumnAlign = 'start' | 'center' | 'end';
 /**
- * Column width: a fixed pixel width, or a share of the free space (`{ flex: 1 }`).
- * `'auto'` (fit to content) arrives in Phase 2.
+ * Column width: a fixed pixel width, `'auto'` to fit the content, or a share of
+ * the free space (`{ flex: 1 }`).
  */
-type ColumnWidth = number | {
+type ColumnWidth = number | 'auto' | {
     flex: number;
 };
 /** What a `cell` function receives besides the row itself. */
 interface CellContext<TData> {
-    /** The row object from `data`. */
+    /** The row object from `data` (or from `pinnedRows`). */
     row: TData;
-    /** The id from `getRowId`, or the row's index as a string. */
+    /**
+     * The id from `getRowId`, or the row's index as a string. A pinned row without
+     * `getRowId` gets `'top-0'`, `'bottom-0'` and so on.
+     */
     rowId: string;
-    /** Index of the row in the current (sorted) row model. */
+    /** Index of the row in the current (sorted) row model; for a pinned row, its index in its list. */
     index: number;
     /** The column's id. */
     columnId: string;
     /** The value read by the column's `accessor`, or `undefined` without one. */
     value: unknown;
+    /** Set for a row from `pinnedRows`: the side it is pinned to. */
+    pinned?: RowPin;
 }
 /**
  * One column of the table.
@@ -51,8 +68,12 @@ interface ColumnDef$1<TData, TContent = unknown> {
     /** Custom cell content. Without it, the cell shows the accessor's value as text. */
     cell?: (row: TData, context: CellContext<TData>) => TContent;
     /**
-     * Fixed width in px, or `{ flex }` for a share of the free space (at least `minWidth`).
-     * Pinned columns ignore `flex`. Default: 150 px.
+     * Fixed width in px, `'auto'` to fit the content, or `{ flex }` for a share of the
+     * free space (at least `minWidth`). Pinned columns ignore `flex`. Default: 150 px.
+     *
+     * `'auto'` fits the header, the pinned rows and the rendered body rows, within
+     * `minWidth` and `maxWidth`. It measures once the first loaded rows render, then keeps
+     * that width; `autosizeColumns()` fits it again.
      */
     width?: ColumnWidth;
     /** Lower bound for resizing and for flex columns, in px. Default: 40. */
@@ -65,6 +86,12 @@ interface ColumnDef$1<TData, TContent = unknown> {
     sortable?: boolean;
     /** Whether the column can be resized. Default: `true`. */
     resizable?: boolean;
+    /**
+     * Whether the column can be moved by dragging its header or with Alt+Shift+Arrow.
+     * Default: `true`. Columns move within their own group (start-pinned, scrolling or
+     * end-pinned). Other columns can still move past one that sets `false`.
+     */
+    reorderable?: boolean;
     /** Text alignment. Default: `'start'`. */
     align?: ColumnAlign;
 }
@@ -79,6 +106,11 @@ interface SortItem {
 type SortState = SortItem[];
 /** 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 {
     sorting: SortState;
@@ -89,23 +121,71 @@ interface ColumnResizeDetail {
     width: number;
     sizing: ColumnSizingState;
 }
+/** `detail` of `argus-column-reorder`. */
+interface ColumnReorderDetail {
+    /** The column that moved. */
+    columnId: string;
+    /** The whole new order. */
+    order: ColumnOrderState;
+}
 /** `detail` of `argus-row-click`. */
 interface RowClickDetail<TData> {
     row: TData;
     rowId: string;
+    /** Index in the current row order; for a pinned row, its index in its list. */
     index: number;
+    /** Set when the row is from `pinnedRows`: the side it is pinned to. */
+    pinned?: RowPin;
 }
 /** `detail` of `argus-cell-click`. */
 interface CellClickDetail<TData> {
     row: TData;
     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). */
 interface RangeChangeDetail {
     start: number;
     end: number;
 }
+/** What `getRows()` receives: a range of rows, the sort order and an abort signal. */
+interface RowsRequest {
+    /** Index of the first row, inclusive. */
+    start: number;
+    /** Index after the last row: exclusive, like `Array.prototype.slice`. */
+    end: number;
+    /** The current sort order; sorting happens on the server. `[]` when unsorted. */
+    sorting: SortState;
+    /** Aborted when the rows are no longer needed: scrolled far away, or the source was reset. */
+    signal: AbortSignal;
+}
+/** What `getRows()` resolves to. */
+interface RowsResponse<TData> {
+    /** The rows from `start`, at most `end - start` of them. */
+    rows: readonly TData[];
+    /**
+     * Total number of rows, if known. Without it, the table grows as pages arrive,
+     * and a page with fewer rows than asked for marks the end.
+     */
+    total?: number;
+}
+/** A remote source of rows, loaded page by page as they scroll into view. */
+interface DataSource<TData> {
+    /** Loads one page of rows. Reject (or throw) to show the page as failed, with a Retry button. */
+    getRows(request: RowsRequest): Promise<RowsResponse<TData>>;
+    /** Rows per request. Default: 100. */
+    pageSize?: number;
+}
+/** `detail` of `argus-load-error`: what `getRows()` rejected with, and the rows it was asked for. */
+interface LoadErrorDetail {
+    error: unknown;
+    /** Index of the first row, inclusive. */
+    start: number;
+    /** Index after the last row, exclusive. */
+    end: number;
+}
 
 /**
  * What a column's `header` or `cell` may produce: a Lit template, a DOM node, or
@@ -118,20 +198,90 @@ 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);
+    /**
+     * 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);
+    /** 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;
+    /**
+     * 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;
+    }
+}
+
 /**
  * A virtualized data table.
  *
- * Set `columns` and `data` as properties. 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.
+ * Set `columns`, and `data` or `dataSource`, as properties. Columns can also be
+ * written as `<argus-column>` children; a non-empty `columns` wins over them.
+ * 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.
+ *
+ * Any number of rows scrolls to the end. Browsers limit an element's height
+ * (about 800k rows of 40 px in Chromium and Safari, 400k in Firefox), so a taller
+ * body renders shorter and its scroll position is scaled onto the rows: the
+ * scrollbar still spans every row, and a wheel step covers a few more of them.
+ * Use `scrollToRow()` rather than setting the scroll container's `scrollTop`.
  *
  * @summary Data table with pinned rows and columns and infinite loading.
  *
- * @fires 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 argus-column-resize - A column was resized by dragging its handle or with Alt+Arrow on its header. `detail: { columnId, width, sizing }`: the new widths, or the proposed ones when `columnSizing` is controlled. Fires on every frame of a drag.
- * @fires argus-cell-click - A body cell was clicked, or Enter was pressed on it. `detail: { row, columnId, value }`. Fires before `argus-row-click`.
- * @fires argus-row-click - A body row was clicked, or Enter was pressed on one of its cells. `detail: { row, rowId, index }`.
- * @fires argus-range-change - The visible rows changed. `detail: { start, end }` (row indices, inclusive).
+ * @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<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<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".
  *
@@ -140,15 +290,25 @@ type Density = 'compact' | 'comfortable' | 'spacious';
  * @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 resize-handle - The drag handle on the inline-end edge of a resizable column's header.
+ * @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 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-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 - 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 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.
  * @csspart empty - The empty-state container.
  *
  * @cssprop [--argus-bg=Canvas] - Background of the table and rows.
@@ -158,30 +318,62 @@ type Density = 'compact' | 'comfortable' | 'spacious';
  * @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-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-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-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.
  */
 declare class ArgusTable<T = unknown> extends LitElement {
     #private;
     static styles: CSSResultGroup;
-    /** Column definitions. Property only: functions can't be attributes. */
-    columns: readonly ColumnDef<T>[];
-    /** The rows to show. Replace the array to update; changes inside it aren't detected. */
-    data: readonly T[];
-    /** Returns a stable id for a row. Default: the row's index in `data`. */
+    /**
+     * Column definitions. Property only: functions can't be attributes. While empty,
+     * the table reads its `<argus-column>` children instead. `null` or `undefined`
+     * means `[]`.
+     */
+    get columns(): readonly ColumnDef<T>[];
+    set columns(value: readonly ColumnDef<T>[] | null | undefined);
+    /**
+     * The rows to show. Replace the array to update; changes inside it aren't
+     * detected. `null` or `undefined` means `[]`.
+     */
+    get data(): readonly T[];
+    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`.
+     */
+    dataSource?: DataSource<T>;
+    /**
+     * Rows fixed below the header (`top`) and at the bottom of the view (`bottom`),
+     * such as a totals row: `{ top?: T[], bottom?: T[] }`. They are separate
+     * objects, not rows of `data`: columns read them the same way, but they are
+     * never sorted and work the same with a `dataSource`. A `cell` function gets
+     * `pinned: 'top' | 'bottom'` in its context. Replace the object to update.
+     */
+    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 density: `compact`, `comfortable` or `spacious`. */
     density: Density;
-    /** Rows rendered above and below the visible ones. */
-    overscan: number;
+    /** Rows rendered above and below the visible ones. `null` or `undefined` means the default, 6. */
+    get overscan(): number;
+    set overscan(value: number | null | undefined);
     /**
      * 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
@@ -197,8 +389,35 @@ declare class ArgusTable<T = unknown> extends LitElement {
      */
     get columnSizing(): ColumnSizingState;
     set columnSizing(value: ColumnSizingState | undefined);
+    /**
+     * The column order: column ids as the table shows them, e.g.
+     * `['id', 'total', 'customer']`. `[]` (the default) keeps the order of `columns`.
+     * 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`
+     * with the proposed order. `undefined` hands it back.
+     */
+    get columnOrder(): ColumnOrderState;
+    set columnOrder(value: ColumnOrderState | undefined);
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * With a `dataSource`, drops every loaded page and loads the rows in view
+     * again, keeping the scroll position. With `data`, re-renders the cells (after
+     * changing row objects in place). Resolves once the table has re-rendered;
+     * reloaded rows arrive as their pages load.
+     */
+    refresh(): Promise<void>;
+    /**
+     * 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
+     * controlled `columnSizing` nothing changes until you set it. Without `ids`, fits
+     * every resizable column; columns with `resizable: false` keep their width.
+     * 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>;
     protected willUpdate(changed: PropertyValues<this>): void;
@@ -218,19 +437,25 @@ declare const RANGE_CHANGE = "argus-range-change";
 declare const SORT_CHANGE = "argus-sort-change";
 /** Fired when a column was resized (uncontrolled), or with the proposed widths (controlled). */
 declare const COLUMN_RESIZE = "argus-column-resize";
+/** Fired when a column was moved (uncontrolled), or with the proposed order (controlled). */
+declare const COLUMN_REORDER = "argus-column-reorder";
 /** Fired when a 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 after the update when a `dataSource` page failed to load. */
+declare const LOAD_ERROR = "argus-load-error";
 declare global {
     interface HTMLElementEventMap {
         'argus-range-change': CustomEvent<RangeChangeDetail>;
         'argus-sort-change': CustomEvent<SortChangeDetail>;
         'argus-column-resize': CustomEvent<ColumnResizeDetail>;
+        'argus-column-reorder': CustomEvent<ColumnReorderDetail>;
         'argus-row-click': CustomEvent<RowClickDetail<unknown>>;
         'argus-cell-click': CustomEvent<CellClickDetail<unknown>>;
+        'argus-load-error': CustomEvent<LoadErrorDetail>;
     }
 }
 
-export { ArgusTable, CELL_CLICK, COLUMN_RESIZE, RANGE_CHANGE, ROW_CLICK, SORT_CHANGE };
-export type { CellClickDetail, CellContent, CellContext, ColumnAlign, ColumnDef, ColumnPin, ColumnResizeDetail, ColumnSizingState, ColumnWidth, Density, RangeChangeDetail, RowClickDetail, SortChangeDetail, SortItem, SortState };
+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 };

package/dist/index.js

@@ -1,3 +1,4 @@
+import { ArgusColumn } from "./argus-column.js";
 import { ArgusTable } from "./argus-table.js";
-import { CELL_CLICK, COLUMN_RESIZE, RANGE_CHANGE, ROW_CLICK, SORT_CHANGE } from "./events.js";
-export { ArgusTable, CELL_CLICK, COLUMN_RESIZE, RANGE_CHANGE, ROW_CLICK, SORT_CHANGE };
+import { CELL_CLICK, COLUMN_REORDER, COLUMN_RESIZE, LOAD_ERROR, RANGE_CHANGE, ROW_CLICK, SORT_CHANGE } from "./events.js";
+export { ArgusColumn, ArgusTable, CELL_CLICK, COLUMN_REORDER, COLUMN_RESIZE, LOAD_ERROR, RANGE_CHANGE, ROW_CLICK, SORT_CHANGE };

package/dist/max-height.js

@@ -0,0 +1,68 @@
+// src/max-height.ts
+/**
+* The tallest element the engine renders, measured once per page.
+*
+* Chromium and WebKit clamp a taller element at about 33.5M px (fewer CSS px
+* when the page is zoomed in), and Firefox drops anything over about 17.9M px
+* to 0. A hidden probe tries a few heights and keeps the first that renders at
+* full size. A zoom change (a new `devicePixelRatio` on resize) measures again
+* and tells the tables, so a scaled body stays within the new limit.
+*/
+var HEIGHTS = [
+	32e6,
+	16e6,
+	8e6,
+	4e6,
+	2e6
+];
+/** Content below this never needs the probe: every engine renders it. */
+var SAFE_HEIGHT = 2e6;
+/** Room left for the scrollbar and rounding. */
+var MARGIN = 1e3;
+var measured;
+var dpr = 0;
+var listeners = /* @__PURE__ */ new Set();
+function onResize() {
+	if (window.devicePixelRatio === dpr) return;
+	dpr = window.devicePixelRatio;
+	measured = void 0;
+	for (const listener of listeners) listener();
+}
+/** The tallest element height in px the engine renders. */
+function maxElementHeight() {
+	if (measured !== void 0) return measured;
+	const probe = document.createElement("div");
+	probe.setAttribute("aria-hidden", "true");
+	probe.style.cssText = "position:fixed;inset-block-start:0;inset-inline-start:0;inline-size:1px;visibility:hidden;pointer-events:none";
+	document.body.append(probe);
+	measured = HEIGHTS.find((height) => {
+		probe.style.blockSize = `${String(height)}px`;
+		return probe.offsetHeight >= height - 1;
+	}) ?? SAFE_HEIGHT;
+	probe.remove();
+	return measured;
+}
+/**
+* The tallest the body may render: the engine's maximum less what scrolls with
+* it (`extra`: the header and pinned rows). `Infinity` for a body of `logical`
+* px that is far from any limit, without measuring.
+*/
+function bodyCap(logical, extra) {
+	if (logical + extra < SAFE_HEIGHT) return Infinity;
+	return Math.max(maxElementHeight() - extra - MARGIN, 0);
+}
+/** Calls `listener` when the maximum may have changed (the page was zoomed). Returns the unsubscribe. */
+function watchMaxElementHeight(listener) {
+	if (listeners.size === 0) {
+		dpr = window.devicePixelRatio;
+		window.addEventListener("resize", onResize, { passive: true });
+	}
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+		if (listeners.size === 0) window.removeEventListener("resize", onResize);
+	};
+}
+export { bodyCap, watchMaxElementHeight };
+
+//# sourceMappingURL=max-height.js.map

package/dist/max-height.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"max-height.js","names":[],"sources":["../src/max-height.ts"],"sourcesContent":["/**\n * The tallest element the engine renders, measured once per page.\n *\n * Chromium and WebKit clamp a taller element at about 33.5M px (fewer CSS px\n * when the page is zoomed in), and Firefox drops anything over about 17.9M px\n * to 0. A hidden probe tries a few heights and keeps the first that renders at\n * full size. A zoom change (a new `devicePixelRatio` on resize) measures again\n * and tells the tables, so a scaled body stays within the new limit.\n */\nconst HEIGHTS = [32_000_000, 16_000_000, 8_000_000, 4_000_000, 2_000_000];\n\n/** Content below this never needs the probe: every engine renders it. */\nconst SAFE_HEIGHT = 2_000_000;\n/** Room left for the scrollbar and rounding. */\nconst MARGIN = 1000;\n\nlet measured: number | undefined;\nlet forced: number | undefined;\nlet dpr = 0;\nconst listeners = new Set<() => void>();\n\nfunction onResize() {\n  if (window.devicePixelRatio === dpr) return;\n  dpr = window.devicePixelRatio;\n  measured = undefined;\n  for (const listener of listeners) listener();\n}\n\n/** The tallest element height in px the engine renders. */\nfunction maxElementHeight(): number {\n  if (forced !== undefined) return forced;\n  if (measured !== undefined) return measured;\n  // Fixed, so the probe never makes the page scroll.\n  const probe = document.createElement('div');\n  probe.setAttribute('aria-hidden', 'true');\n  probe.style.cssText =\n    'position:fixed;inset-block-start:0;inset-inline-start:0;inline-size:1px;visibility:hidden;pointer-events:none';\n  document.body.append(probe);\n  measured =\n    HEIGHTS.find((height) => {\n      probe.style.blockSize = `${String(height)}px`;\n      return probe.offsetHeight >= height - 1;\n    }) ?? SAFE_HEIGHT;\n  probe.remove();\n  return measured;\n}\n\n/**\n * The tallest the body may render: the engine's maximum less what scrolls with\n * it (`extra`: the header and pinned rows). `Infinity` for a body of `logical`\n * px that is far from any limit, without measuring.\n */\nexport function bodyCap(logical: number, extra: number): number {\n  if (forced === undefined && logical + extra < SAFE_HEIGHT) return Infinity;\n  return Math.max(maxElementHeight() - extra - MARGIN, 0);\n}\n\n/** Calls `listener` when the maximum may have changed (the page was zoomed). Returns the unsubscribe. */\nexport function watchMaxElementHeight(listener: () => void): () => void {\n  if (listeners.size === 0) {\n    dpr = window.devicePixelRatio;\n    window.addEventListener('resize', onResize, { passive: true });\n  }\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n    if (listeners.size === 0) window.removeEventListener('resize', onResize);\n  };\n}\n\n/** Tests: pretend the engine renders at most `height` px (`undefined` measures again). */\nexport function setMaxElementHeightForTests(height: number | undefined): void {\n  forced = height;\n}\n"],"mappings":";;;;;;;;;;AASA,IAAM,UAAU;CAAC;CAAY;CAAY;CAAW;CAAW;AAAS;;AAGxE,IAAM,cAAc;;AAEpB,IAAM,SAAS;AAEf,IAAI;AAEJ,IAAI,MAAM;AACV,IAAM,4BAAY,IAAI,IAAgB;AAEtC,SAAS,WAAW;CAClB,IAAI,OAAO,qBAAqB,KAAK;CACrC,MAAM,OAAO;CACb,WAAW,KAAA;CACX,KAAK,MAAM,YAAY,WAAW,SAAS;AAC7C;;AAGA,SAAS,mBAA2B;CAElC,IAAI,aAAa,KAAA,GAAW,OAAO;CAEnC,MAAM,QAAQ,SAAS,cAAc,KAAK;CAC1C,MAAM,aAAa,eAAe,MAAM;CACxC,MAAM,MAAM,UACV;CACF,SAAS,KAAK,OAAO,KAAK;CAC1B,WACE,QAAQ,MAAM,WAAW;EACvB,MAAM,MAAM,YAAY,GAAG,OAAO,MAAM,EAAE;EAC1C,OAAO,MAAM,gBAAgB,SAAS;CACxC,CAAC,KAAK;CACR,MAAM,OAAO;CACb,OAAO;AACT;;;;;;AAOA,SAAgB,QAAQ,SAAiB,OAAuB;CAC9D,IAA4B,UAAU,QAAQ,aAAa,OAAO;CAClE,OAAO,KAAK,IAAI,iBAAiB,IAAI,QAAQ,QAAQ,CAAC;AACxD;;AAGA,SAAgB,sBAAsB,UAAkC;CACtE,IAAI,UAAU,SAAS,GAAG;EACxB,MAAM,OAAO;EACb,OAAO,iBAAiB,UAAU,UAAU,EAAE,SAAS,KAAK,CAAC;CAC/D;CACA,UAAU,IAAI,QAAQ;CACtB,aAAa;EACX,UAAU,OAAO,QAAQ;EACzB,IAAI,UAAU,SAAS,GAAG,OAAO,oBAAoB,UAAU,QAAQ;CACzE;AACF"}

package/dist/render/body.js

@@ -6,44 +6,76 @@ import { repeat } from "lit/directives/repeat.js";
 /**
 * The virtualized body. Rows are keyed by pool slot, so a row entering the window
 * reuses the DOM of one that left (ADR 0001), and they stay in pool order: screen
-* readers get the position from `aria-rowindex` (the header row is 1).
+* readers get the position from `aria-rowindex`. `firstRowIndex` is the
+* `aria-rowindex` of row 0: after the header and the rows pinned to the top.
 */
-function renderBody(rows, columns, totalSize, active) {
+function renderBody(rows, columns, totalSize, active, firstRowIndex, loading) {
 	return html`<div
     part="body"
     role="rowgroup"
     style=${styleMap({ blockSize: `${String(totalSize)}px` })}
   >
-    ${repeat(rows, (r) => r.slot, (r) => renderRow(r, columns, r.index === active?.index ? active.col : void 0))}
+    ${repeat(rows, (r) => r.slot, (r) => renderRow(r, columns, r.index === active?.index ? active.col : void 0, firstRowIndex, loading))}
   </div>`;
 }
 /**
 * One body row. Every cell is focusable (`tabindex=-1`) so clicks focus it; the
-* active one is the grid's single tab stop (roving tabindex).
+* active one is the grid's single tab stop (roving tabindex). A row whose data
+* isn't loaded shows skeleton bars, and a Retry button if its page failed.
 */
-function renderRow(row, columns, activeCol) {
+function renderRow(row, columns, activeCol, firstRowIndex, loading) {
+	const state = loading?.stateAt(row.index) ?? "loaded";
+	let parts = row.index % 2 === 0 ? "row row-even" : "row row-odd";
+	if (state !== "loaded") parts += " row-loading";
+	const retry = state === "error" ? loading?.retry.get(row.index) : void 0;
 	return html`<div
-    part=${row.index % 2 === 0 ? "row row-even" : "row row-odd"}
+    part=${parts}
     class="row"
     role="row"
-    aria-rowindex=${row.index + 2}
+    aria-rowindex=${row.index + firstRowIndex}
+    aria-busy=${state === "loading" ? "true" : nothing}
     style=${styleMap({ transform: `translateY(${String(row.start)}px)` })}
   >
-    ${repeat(columns, (c) => c.id, (c) => html`<div
-          part=${cellParts(c)}
-          role="gridcell"
-          aria-colindex=${c.colIndex}
-          tabindex=${c.id === activeCol ? 0 : -1}
-          data-col=${c.id}
-          data-align=${c.align}
-          data-pin=${c.pin ?? nothing}
-          ?data-pin-edge=${c.pinEdge}
-          style=${pinStyle(c) ?? nothing}
-        >
-          <slot name=${cellSlot(row.slot, c.colIndex)}></slot>
-        </div>`)}
+    ${repeat(columns, (c) => c.id, (c) => renderCell(c, c.id === activeCol, cellSlot(row.slot, c.colIndex), false, placeholder(state, c.colIndex === 1 ? retry : void 0, row.index, loading)))}
   </div>`;
 }
-export { renderBody };
+/**
+* A body or pinned-row cell. Every cell is focusable (`tabindex=-1`) so clicks
+* focus it; `tabStop` marks the grid's single tab stop. `before` goes ahead of
+* the slot (a loading row's skeleton bar or Retry button).
+*/
+function renderCell(c, tabStop, slot, pinnedRow, before = nothing) {
+	return html`<div
+    part=${cellParts(c, pinnedRow)}
+    role="gridcell"
+    aria-colindex=${c.colIndex}
+    tabindex=${tabStop ? 0 : -1}
+    data-col=${c.id}
+    data-align=${c.align}
+    data-pin=${c.pin ?? nothing}
+    style=${pinStyle(c) ?? nothing}
+  >
+    ${before}<slot name=${slot}></slot>
+  </div>`;
+}
+/** What an unloaded cell shows: a skeleton bar, or the Retry button in a failed page's first cell. */
+function placeholder(state, retryLabel, index, loading) {
+	if (state === "loaded") return nothing;
+	if (retryLabel !== void 0 && loading) return html`<button
+      part="retry"
+      type="button"
+      tabindex="-1"
+      data-row=${index}
+      aria-label=${retryLabel}
+      @click=${loading.onRetry}
+    >
+      Retry
+    </button>`;
+	return html`<div
+    part=${state === "error" ? "skeleton skeleton-error" : "skeleton"}
+    aria-hidden="true"
+  ></div>`;
+}
+export { renderBody, renderCell };
 
 //# sourceMappingURL=body.js.map