apex-grid 3.5.0 → 4.0.0-beta.1

package/components/grid.d.ts

@@ -1,5 +1,5 @@
 import { ContextProvider } from '@lit/context';
-import { nothing } from 'lit';
+import { nothing, type PropertyDeclaration } from 'lit';
 import { DataOperationsController } from '../controllers/data-operation.js';
 import { GridDOMController } from '../controllers/dom.js';
 import type { RowPinPosition } from '../controllers/row-pin.js';
@@ -116,7 +116,8 @@ export interface ApexCellValueChangingEvent<T extends object> {
      */
     key: Keys<T>;
     /**
-     * The view-relative row index (matches {@link ApexGrid.pageItems}).
+     * The view-relative row index (matches {@link ApexGrid.pageItems}), or
+     * -1 when the record is pinned or on another page.
      */
     rowIndex: number;
     /**
@@ -142,7 +143,9 @@ export interface ApexCellValueChangedEvent<T extends object> {
      */
     key: Keys<T>;
     /**
-     * The view-relative row index after the change.
+     * The view-relative row index after the change (matches
+     * {@link ApexGrid.pageItems}), or -1 when the record is pinned or on
+     * another page. Use `data` to identify the row.
      */
     rowIndex: number;
     /**
@@ -164,7 +167,8 @@ export interface ApexCellValidationFailedEvent<T extends object> {
      */
     key: Keys<T>;
     /**
-     * The view-relative row index of the rejected cell.
+     * The view-relative row index of the rejected cell, or -1 when the record
+     * is pinned or on another page.
      */
     rowIndex: number;
     /**
@@ -203,6 +207,14 @@ export interface ApexRowMovingEvent<T extends object> {
     from: number;
     /** The target row's view index. */
     to: number;
+    /** Whether the row lands before or after the target row. */
+    position: RowDropPosition;
+    /**
+     * The view index the row lands at, resolved from `to` and `position`
+     * (`moveRow(0, 3)` lands the row at 2). Splice the row out of `from` and in
+     * at `toIndex` to mirror the move.
+     */
+    toIndex: number;
     /** The row being moved (a live reference into {@link ApexGrid.data}). */
     data: T;
 }
@@ -227,7 +239,8 @@ export interface ApexStateChangedEvent {
  */
 export interface ApexRowEditStartedEvent {
     /**
-     * The view-relative row index entering edit mode.
+     * The view-relative row index entering edit mode, or -1 when the record is
+     * pinned or on another page.
      */
     rowIndex: number;
 }
@@ -236,7 +249,8 @@ export interface ApexRowEditStartedEvent {
  */
 export interface ApexRowEditEndedEvent {
     /**
-     * The view-relative row index that left edit mode.
+     * The view-relative row index that left edit mode, or -1 when the record is
+     * pinned or on another page.
      */
     rowIndex: number;
     /**
@@ -324,6 +338,11 @@ export interface ApexRowSelectedEvent<T extends object> {
 }
 /**
  * Event payload for the cancellable `treeRowExpanding` event.
+ *
+ * @remarks
+ * A parent that exists only as a path segment (no row of its own in
+ * {@link ApexGrid.data}) appears in these arrays as a synthesized placeholder
+ * row, not as one of your records.
  */
 export interface ApexTreeRowExpandingEvent<T extends object> {
     /** Rows that will become expanded by this change. */
@@ -337,6 +356,11 @@ export interface ApexTreeRowExpandingEvent<T extends object> {
 }
 /**
  * Event payload for the `treeRowExpanded` event.
+ *
+ * @remarks
+ * A parent that exists only as a path segment (no row of its own in
+ * {@link ApexGrid.data}) appears in these arrays as a synthesized placeholder
+ * row, not as one of your records.
  */
 export interface ApexTreeRowExpandedEvent<T extends object> {
     /** Rows that became expanded in this change. */
@@ -550,6 +574,9 @@ export interface ApexGridEventMap<T extends object> {
      * Fires for programmatic changes (including `setState`) as well as user
      * interaction. To avoid a save loop, compare the snapshot to your last-saved
      * one before persisting (identical snapshots never fire a second time).
+     * Attach the listener to the grid element itself: the snapshot is computed
+     * only for listeners registered on the grid, so a listener on an ancestor
+     * (event delegation) receives nothing while none is attached to the grid.
      *
      * @event
      */
@@ -700,11 +727,37 @@ export interface ApexGridEventMap<T extends object> {
  * @fires treeRowExpanding - Cancellable. Emitted before a tree-row expansion change (tree mode).
  * @fires treeRowExpanded - Emitted after a tree-row expansion change has been applied.
  *
+ * @csspart table - The element with the `grid` (or `treegrid`) role, `aria-rowcount` and `aria-colcount`: holds the header rows, pinned rows and body.
  * @csspart live-region - Visually-hidden ARIA live region used for screen-reader announcements.
+ * @csspart paginator-host - The `<apex-grid-paginator>` element; the grid re-exports its parts below.
+ * @csspart paginator - The paginator's root container.
+ * @csspart paginator-size - The page-size selector wrapper.
+ * @csspart paginator-info - The "1-25 of 100" summary.
+ * @csspart paginator-controls - The first/prev/next/last button cluster.
+ * @csspart paginator-page - The "page / count" label.
+ * @csspart paginator-button - Each of the first, previous, next and last buttons.
+ * @csspart paginator-first - The first page button.
+ * @csspart paginator-prev - The previous page button.
+ * @csspart paginator-next - The next page button.
+ * @csspart paginator-last - The last page button.
+ * @csspart toolbar-host - The `<apex-grid-toolbar>` element; the grid re-exports its parts below.
+ * @csspart toolbar - The toolbar's container.
+ * @csspart toolbar-search - The quick-filter input wrapper.
+ * @csspart search-field - The bordered field holding the search icon and input.
+ * @csspart search-icon - The leading search icon.
+ * @csspart search-input - The quick-filter input.
+ * @csspart toolbar-actions - The trailing actions area.
+ * @csspart toolbar-action - A host-contributed action button.
+ * @csspart export - The export menu wrapper.
+ * @csspart export-trigger - The export menu trigger button.
+ * @csspart export-icon - The download icon in the trigger.
+ * @csspart export-caret - The caret icon in the trigger.
+ * @csspart export-menu - The export dropdown menu.
+ * @csspart export-menu-item - An item in the export menu.
  *
  * @cssprop [--ag-brand] - Brand color for selection, focus rings, and accents. Auto-tints from `--ig-primary-500` where an Ignite UI palette is present.
  * @cssprop [--ag-brand-strong] - Brand color for hover / pressed states.
- * @cssprop [--ag-grid-shadow] - Grid edge/shadow override. Default is a flat 1px hairline edge; set to `var(--ag-shadow-card)` for the elevated card look, or `none` to remove it.
+ * @cssprop [--ag-grid-shadow] - Grid edge/shadow override. Default is a flat 1px hairline edge; set to `var(--ag-shadow-card)` (`var(--ag-dark-shadow-card)` on a dark grid) for the elevated card look, or `none` to remove it.
  * @cssprop [--ag-grid-bg] - Host card background. Defaults to a subtle light gradient; override with a flat color (or use `theme="dark"`) for dark themes.
  * @cssprop [--ag-surface] - Grid card background (must be opaque).
  * @cssprop [--ag-surface-alt] - Alternating row tint.
@@ -715,6 +768,17 @@ export interface ApexGridEventMap<T extends object> {
  * @cssprop [--ag-text-body] - Row text color.
  * @cssprop [--ag-text-muted] - Muted text (roles, labels).
  * @cssprop [--ag-row-hover] - Row hover wash.
+ * @cssprop [--ag-dark-grid-bg] - Host card background on `theme="dark"` grids. Dark grids read the `--ag-dark-*` colours instead of the light ones.
+ * @cssprop [--ag-dark-surface] - Grid card background on dark grids (must be opaque).
+ * @cssprop [--ag-dark-surface-alt] - Alternating row tint on dark grids.
+ * @cssprop [--ag-dark-surface-elevated] - Header background on dark grids.
+ * @cssprop [--ag-dark-hairline] - Header / structural gridline color on dark grids.
+ * @cssprop [--ag-dark-border] - Row separator color on dark grids.
+ * @cssprop [--ag-dark-text] - Primary text color on dark grids.
+ * @cssprop [--ag-dark-text-body] - Row text color on dark grids.
+ * @cssprop [--ag-dark-text-muted] - Muted text (roles, labels) on dark grids.
+ * @cssprop [--ag-dark-row-hover] - Row hover wash on dark grids.
+ * @cssprop [--ag-dark-shadow-card] - Elevated card shadow for dark grids (see `--ag-grid-shadow`).
  * @cssprop [--ag-row-h] - Row height.
  * @cssprop [--ag-header-h] - Header height.
  * @cssprop [--ag-radius] - Outer card corner radius.
@@ -735,6 +799,14 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
     #private;
     static get tagName(): string;
     static styles: import("lit").CSSResult;
+    /**
+     * The `rowRecycling` every grid starts with: `true` unless the page global
+     * `__apexRowKeying` is `'item'`, which the test runner sets for its second
+     * suite run so every grid in it keeps record-keyed rows.
+     *
+     * @internal Test-only, for the suite-wide keying switch. Not public API.
+     */
+    static defaultRowRecycling: boolean;
     /**
      * Registers `<apex-grid>` and its internal dependencies with the custom-element
      * registry. Idempotent — safe to call more than once.
@@ -769,8 +841,14 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
     protected _rows: NodeListOf<ApexGridRow<T>>;
     /** Column configuration for the grid. */
     columns: Array<ColumnConfiguration<T>>;
-    /** The data source for the grid. */
-    data: Array<T>;
+    /**
+     * The data source for the grid. `null` or `undefined` (a framework prop that
+     * is still loading) is stored as an empty array.
+     *
+     * @default []
+     */
+    get data(): Array<T>;
+    set data(value: Array<T>);
     /**
      * Optional stable row-identity resolver.
      *
@@ -841,8 +919,10 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * {@link DataPipelineConfiguration.quickFilter}.
      *
      * @attr quick-filter
+     * @default ''
      */
-    quickFilter: string;
+    get quickFilter(): string;
+    set quickFilter(value: string);
     /**
      * Whether the built-in quick-filter input is rendered in the toolbar.
      *
@@ -931,6 +1011,33 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * @attr column-separator
      */
     columnSeparator: boolean;
+    /**
+     * Reuses body row elements across records. On by default: a scroll, sort or
+     * filter re-binds the rendered rows to the records now in view instead of
+     * building rows for them, which makes jumps and sorts cheaper on large
+     * grids. Set to `false` (or the `row-recycling="false"` attribute) to
+     * restore record-keyed rows, where each row element stays with its record.
+     * `undefined` or `null` (a framework prop that was set and then dropped)
+     * restores the default, so only `false` opts out.
+     *
+     * @remarks
+     * A row element (and its cells) shows another record after a scroll or a
+     * sort, so cell and editor templates must derive everything they render
+     * from their context on each render, and must not keep state in the
+     * elements they create. `ctx.row` and `ctx.parent` are row and cell
+     * elements that may show another record later: read `ctx.data` for the
+     * record, and do not hold `ctx.row` or `ctx.parent` across an `await`. A
+     * template that keeps element state wraps itself in
+     * `keyed(ctx.data, html...)` so the state never shows on the wrong record
+     * (it is rebuilt on every rebind). Turn recycling off for templates that
+     * must keep element state across a sort or a move, such as some
+     * third-party widgets.
+     *
+     * @attr row-recycling
+     * @default true
+     */
+    get rowRecycling(): boolean;
+    set rowRecycling(value: boolean);
     /**
      * Inline editing configuration for the grid.
      *
@@ -951,13 +1058,14 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * @remarks
      * Selection is disabled by default. Set `enabled: true` and (optionally)
      * `mode` (`'single' | 'multiple'`) and `showCheckboxColumn` to opt in.
+     * `isRowSelectable` keeps chosen rows (a pinned total row) out of it.
      *
      * @example
      * ```ts
      * grid.selection = { enabled: true, mode: 'multiple', showCheckboxColumn: true };
      * ```
      */
-    selection?: GridSelectionConfiguration;
+    selection?: GridSelectionConfiguration<T>;
     /**
      * The currently selected rows, in insertion order.
      *
@@ -974,7 +1082,8 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * adding to it in `'multiple'` mode.
      *
      * @returns `true` if the selection changed, `false` if the change was
-     * rejected by a `rowSelecting` listener or selection is disabled.
+     * rejected by a `rowSelecting` listener, the row is not selectable
+     * (`selection.isRowSelectable`) or selection is disabled.
      */
     selectRow(row: T): Promise<boolean>;
     /**
@@ -986,8 +1095,8 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      */
     toggleRowSelection(row: T): Promise<boolean>;
     /**
-     * Selects every row in the current view ({@link dataView}). No-op in
-     * `'single'` selection mode.
+     * Selects every selectable row in the current view ({@link dataView}).
+     * No-op in `'single'` selection mode.
      */
     selectAllRows(): Promise<boolean>;
     /**
@@ -1061,6 +1170,25 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * stay `true` by default.
      */
     columnMenu: boolean;
+    /**
+     * Whether the column header rows are shown. On by default. Set to `false`
+     * (or the `show-header="false"` attribute) for a compact table, such as a
+     * short dashboard tile, where the rows get the header's room.
+     *
+     * @remarks
+     * Hidden headers take no space, paint nothing and take no pointer, and the
+     * built-in header controls leave the tab order, so resizing, the column
+     * menu, drag reorder and the filter panel are unavailable until the header
+     * returns (an open column menu closes). A focusable control rendered by a
+     * `headerTemplate` stays in the tab order: give it `tabindex="-1"` while
+     * the header is hidden. The column header row
+     * stays in the accessibility tree, so screen readers still announce the
+     * column names, and `aria-rowcount` / `aria-rowindex` do not change. Sort,
+     * filter, column widths and the page are kept.
+     *
+     * @attr show-header
+     */
+    showHeader: boolean;
     /**
      * Column groups rendered as spanning headers above the column header row.
      *
@@ -1165,16 +1293,24 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
     isTreeRowExpanded(row: T): boolean;
     /**
      * Set the sort state for the grid.
+     *
+     * @remarks
+     * Replaces the current sort; `[]`, `null` or `undefined` clears it. Applied
+     * at the next update, against the columns as they are then.
      */
-    set sortExpressions(expressions: SortExpression<T>[]);
+    set sortExpressions(expressions: SortExpression<T>[] | null | undefined);
     /**
      * Get the sort state for the grid.
      */
     get sortExpressions(): SortExpression<T>[];
     /**
      * Set the filter state for the grid.
+     *
+     * @remarks
+     * Replaces the current filter; `[]`, `null` or `undefined` clears it. Applied
+     * at the next update, against the columns as they are then.
      */
-    set filterExpressions(expressions: FilterExpression<T>[]);
+    set filterExpressions(expressions: FilterExpression<T>[] | null | undefined);
     /**
      * Get the filter state for the grid.
      */
@@ -1184,7 +1320,9 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      *
      * @remarks
      * Since the grid has virtualization, this property returns only the currently rendered
-     * chunk of elements in the DOM.
+     * chunk of elements in the DOM. With `rowRecycling` on (the default) an element can
+     * show another record after a scroll, sort or filter; read its `data` each time
+     * rather than keeping the element as a handle to a record.
      */
     get rows(): ApexGridRow<T>[];
     /**
@@ -1200,30 +1338,49 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * Use this when you need to iterate the columns in the same order the grid
      * actually displays them (for example to build a column chooser). Public APIs
      * like {@link ApexGrid.getColumn} continue to operate on the user-supplied
-     * {@link ApexGrid.columns} array.
+     * {@link ApexGrid.columns} array. Each read builds a new array, so read it
+     * once and keep the result rather than reading it inside a loop.
      */
     get displayColumns(): ReadonlyArray<ColumnConfiguration<T>>;
     /**
-     * The total number of items in the {@link ApexGrid.dataView} collection.
+     * The post-filter, post-sort row count. With pagination enabled it counts
+     * the rows paged through, so rows pinned to the top or bottom (they show on
+     * every page) are left out. In `'remote'` pagination mode, the
+     * `pagination.totalItems` you supplied (the rows the server holds for the
+     * current filter).
      *
      * @remarks
-     * This is always the post-filter, post-sort row count — pagination does not change it.
-     * Use {@link ApexGrid.pageItems} to read the rows currently rendered into the body.
+     * The current page does not change it. Use {@link ApexGrid.pageItems} to read
+     * the rows currently rendered into the body.
      */
     get totalItems(): number;
+    /**
+     * The rows the body pages through: {@link ApexGrid.dataView} without the
+     * pinned rows, which render in their own sticky bands on every page. The
+     * page slice and the page count both read it, so they always agree.
+     */
+    protected get bodyRows(): ReadonlyArray<T>;
     /**
      * The records currently rendered into the virtualized body.
      *
      * @remarks
-     * Equal to {@link ApexGrid.dataView} when pagination is disabled. With pagination
-     * enabled (`'local'` mode) this is the active page slice.
+     * Equal to {@link ApexGrid.dataView} without the pinned rows when pagination is
+     * disabled. With pagination enabled (`'local'` mode) this is the active page slice.
      */
     get pageItems(): ReadonlyArray<T>;
     /**
      * The current zero-based page index.
+     *
+     * @remarks
+     * Navigates like {@link ApexGrid.gotoPage}, with the cancellable
+     * `pageChanging` and the `pageChanged` events. Assigned before the first
+     * render, or while a data, filter or quick filter change has yet to render,
+     * the page is kept as given and clamped once the view settles, without those
+     * events.
      */
     get page(): number;
     set page(value: number);
+    requestUpdate(name?: PropertyKey, oldValue?: unknown, options?: PropertyDeclaration, useNewValue?: boolean, newValue?: unknown): void;
     /**
      * The current page size.
      */
@@ -1234,13 +1391,34 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      */
     get pageCount(): number;
     protected watchColumns(_: ColumnConfiguration<T>[], newConfig?: ColumnConfiguration<T>[]): void;
+    /**
+     * The records undo history, the manual row order and row pins may still
+     * name after {@link ApexGrid.data} changes; anything naming another record is
+     * dropped. Defaults to `data`. A row model that writes only part of a larger
+     * record set into `data` (rows under a collapsed group leave `data` but stay
+     * cached and come back as the same objects) overrides this to also yield the
+     * records it keeps, so a collapse does not wipe them. Read only while there
+     * is history, a manual order or a pin to reconcile.
+     */
+    protected historyRecords(): Iterable<T>;
     protected dataChanged(): void;
-    protected pipeline(): Promise<void>;
     protected paginationChanged(): void;
     protected quickFilterChanged(): void;
+    /** The first render shapes the tree in dataChanged; later changes rebuild it. */
+    protected treeChanged(previous?: GridTreeConfiguration<T>): void;
+    protected pipeline(): Promise<void>;
+    /**
+     * Resolves once the pending update, the pipeline runs it started and the
+     * render of their result have settled. Events that report the new view
+     * (`sorted`, `filtered`, `pageChanged`, `quickFilterChanged`) await this,
+     * so with an async pipeline hook they fire after the rows changed.
+     */
+    protected pipelineSettled(): Promise<void>;
+    protected willUpdate(changed: Map<PropertyKey, unknown>): void;
     protected updated(): void;
     addEventListener<K extends keyof M, M extends ApexGridEventMap<T> & HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: M[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
     removeEventListener<K extends keyof M, M extends ApexGridEventMap<T> & HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: M[K]) => unknown, options?: boolean | EventListenerOptions): void;
+    connectedCallback(): void;
     protected firstUpdated(): void;
     /**
      * Performs a filter operation in the grid based on the passed expression(s).
@@ -1357,7 +1535,7 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
     /**
      * Applies a new quick-filter (global search) value, emitting the cancellable
      * `quickFilterChanging` event first and the `quickFilterChanged` event after the
-     * pipeline has run.
+     * pipeline has run. Moving back to the first page fires `pageChanged` too.
      *
      * @param value - The new quick-filter value. Pass `''` to clear.
      * @returns `true` if the change was applied, `false` if cancelled or a no-op.
@@ -1409,7 +1587,9 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      */
     unpinColumn(key: Keys<T>): Promise<boolean>;
     /**
-     * The cell currently in edit mode, or `null`.
+     * The cell currently in edit mode, or `null`. `rowIndex` is view-relative
+     * (matches {@link ApexGrid.pageItems}), or -1 when the edited record is
+     * pinned or on another page.
      */
     get editingCell(): {
         rowIndex: number;
@@ -1417,7 +1597,8 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
     } | null;
     /**
      * The view-relative index of the row currently in edit mode (row edit mode
-     * only), or `null`.
+     * only), or `null`. It is -1 when the edited record is pinned or on another
+     * page.
      */
     get editingRow(): number | null;
     /**
@@ -1458,11 +1639,19 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * point: a thousand `editCell` round-trips would be a thousand entries in the
      * undo stack and a thousand re-renders.
      *
-     * `rowIndex` is view-relative and matches {@link ApexGrid.pageItems}, the same
-     * as {@link editCell}. Edits naming an unknown column, a row index out of
-     * range, or a column the user could not edit either (editing off, not
-     * `editable`, or hidden — the same gate interactive editing uses) are skipped
-     * rather than throwing, so a partially-stale batch still applies what it can.
+     * Name each target cell's row in one of two ways. `rowIndex` is
+     * view-relative and matches {@link ApexGrid.pageItems}, the same as
+     * {@link editCell}, so it reaches the current page only. `row` is the record
+     * itself (a live reference into {@link ApexGrid.data}), which also reaches
+     * rows on other pages, pinned rows and rows under a collapsed tree parent;
+     * their events and validators see `rowIndex` -1. A `rowIndex` must be a
+     * whole number from 0 to `pageItems.length - 1`. Edits naming an unknown
+     * column, any other row index (negative, fractional or past the end of the
+     * page), a row a feature synthesized (a group header, a total, a row a
+     * server has not sent yet), or a column the user could not edit
+     * either (editing off, not `editable`, or hidden: the same gate interactive
+     * editing uses) are skipped rather than throwing, so a partially-stale batch
+     * still applies what it can.
      *
      * @param edits Cells to write. Order is preserved, so later edits to the same
      * cell win.
@@ -1470,22 +1659,21 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * changed; `unchanged`, `invalid` and `cancelled` explain the rest, so a caller
      * can tell a rejected batch from a no-op one.
      *
-     * @example Bulk-clear a column for the rows the user selected
+     * @example Bulk-clear a column for the rows the user selected, on any page
      * ```ts
-     * grid.applyEdits(
-     *   grid.selectedRows.map((row) => ({
-     *     rowIndex: grid.pageItems.indexOf(row),
-     *     column: 'discount',
-     *     value: 0,
-     *   }))
-     * );
+     * grid.applyEdits(grid.selectedRows.map((row) => ({ row, column: 'discount', value: 0 })));
      * ```
      */
     applyEdits(edits: ReadonlyArray<{
-        rowIndex: number;
         column: Keys<T>;
         value: unknown;
-    }>): {
+    } & ({
+        rowIndex: number;
+        row?: never;
+    } | {
+        row: T;
+        rowIndex?: never;
+    })>): {
         applied: number;
         unchanged: number;
         invalid: number;
@@ -1554,12 +1742,13 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * {@link ApexGrid.pageItems}.
      *
      * @remarks
-     * Requires `rowReordering.enabled`. Establishes a manual order (mutually
-     * exclusive with column sorting), goes through the cancellable `rowMoving`
-     * event, emits `rowMoved`, and animates the affected rows.
+     * Requires `rowReordering.enabled`. Establishes a manual order and clears
+     * any column sort (the two are mutually exclusive), goes through the
+     * cancellable `rowMoving` event, emits `rowMoved`, and animates the affected
+     * rows. Rows hidden by a filter keep their place in the order.
      *
-     * @returns `true` when applied, `false` when disabled, out of range, or
-     * cancelled.
+     * @returns `true` when applied, `false` when disabled, out of range, a no-op
+     * (the row would land where it already is), or cancelled.
      */
     moveRow(from: number, to: number, position?: RowDropPosition): boolean;
     /**
@@ -1631,13 +1820,38 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * ```
      */
     moveColumn(fromKey: Keys<T>, toKey: Keys<T>, position?: ColumnDropPosition): Promise<boolean>;
+    /**
+     * Whether `event` belongs to this grid, rather than to a grid nested inside
+     * it (the grid in a master-detail panel renders inside one of this grid's
+     * rows, so its events cross this grid's body on their way out). The first
+     * grid, or grid body, on the composed path from the event origin outward is
+     * the one that owns it.
+     *
+     * @param event - an event that reached this grid.
+     */
+    ownsEvent(event: Event): boolean;
+    /**
+     * The virtualizer is about to re-render a new range of rows. When the row
+     * holding focus leaves it, its cell is removed and focus would fall to the
+     * document, so the scroll container takes focus first and the keyboard
+     * keeps working from the active cell.
+     */
+    protected bodyRangeChanged(event: Event): void;
     protected bodyClickHandler(event: MouseEvent): void;
     protected bodyKeydownHandler(event: KeyboardEvent): void;
     /**
      * Tabbing into the grid body lands on the scroll container; forward focus to
      * the active cell (when one exists) so the roving tab stop is honored.
+     * Also tells navigation whether this body, not a grid nested in it, now
+     * holds focus.
      */
     protected bodyFocusHandler(event: FocusEvent): void;
+    /**
+     * Focus left something in the body; see {@link NavigationController.focusLeft}.
+     * Captured, so the body stops owning focus before a handler further down
+     * (an editor committing on focus loss) runs and lets queued work see it.
+     */
+    protected bodyFocusOutHandler(event: FocusEvent): void;
     /**
      * Forwards body-cell pointer interactions (press / drag-over / release) to
      * feature modules via {@link StateController.handleCellInteraction}. Gated on
@@ -1647,10 +1861,12 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      */
     protected bodyPointerHandler(event: PointerEvent): void;
     protected renderGroupHeaderRow(): import("lit-html").TemplateResult<1> | typeof nothing;
+    /**
+     * With {@link ApexGrid.showHeader} off the header rows stay in the DOM,
+     * visually hidden, so assistive technology keeps the column names.
+     */
     protected renderHeaderRow(): import("lit-html").TemplateResult<1>;
     protected renderBody(): import("lit-html").TemplateResult<1>;
-    /** Number of chrome rows above the body (group header + header + optional filter). */
-    protected get headerRowCount(): number;
     protected renderPinnedTop(): import("lit-html").TemplateResult<1> | typeof nothing;
     protected renderPinnedBottom(): import("lit-html").TemplateResult<1> | typeof nothing;
     protected renderFilterRow(): import("lit-html").TemplateResult<1> | typeof nothing;
@@ -1663,6 +1879,13 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * don't have to coordinate consumer DOM placement.
      */
     protected renderLiveRegion(): import("lit-html").TemplateResult<1>;
+    /**
+     * Floating "ghost" of the column header being dragged for reorder. Rendered
+     * here, next to the row ghost, rather than in the header row: a fixed
+     * element still paints inside its parent's stacking context, so inside the
+     * header row it slid under the group header row and the pinned-top band.
+     */
+    protected renderColumnDragGhost(): import("lit-html").TemplateResult<1> | typeof nothing;
     /**
      * Floating "ghost" of the row being pointer-dragged for reorder. Rendered at
      * the top of the shadow tree (outside the virtualizer) so its `position: fixed`
@@ -1670,6 +1893,15 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * time so it mirrors the row's visible content and column widths.
      */
     protected renderRowDragGhost(): import("lit-html").TemplateResult<1> | typeof nothing;
+    /**
+     * The element with the `grid` (or `treegrid`) role and the table semantics.
+     * It owns only rows: the header rows, the pinned bands and the body. The
+     * toolbar, filter panel, paginator and live region stay outside it. The
+     * host's own `aria-label`, `aria-labelledby` and `aria-describedby` name it:
+     * referenced elements go through element reflection where the browser has
+     * it, and their text is copied where it does not.
+     */
+    protected renderTable(): import("lit-html").TemplateResult<1>;
     protected render(): import("lit-html").TemplateResult<1>;
     /**
      * Sets the live region's announcement text. Screen readers configured to