apex-grid 3.5.0 → 3.6.0

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
      */
@@ -704,7 +731,7 @@ export interface ApexGridEventMap<T extends object> {
  *
  * @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 +742,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.
@@ -769,8 +807,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 +885,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.
      *
@@ -1165,16 +1211,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.
      */
@@ -1221,9 +1275,17 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
     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 +1296,33 @@ 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 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 +1439,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 +1491,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 +1501,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 +1543,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 +1563,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 +1646,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,6 +1724,23 @@ 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;
     /**