apex-grid 3.4.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
      */
@@ -649,6 +676,99 @@ export interface ApexGridEventMap<T extends object> {
      */
     rowSelected: CustomEvent<ApexRowSelectedEvent<T>>;
 }
+/**
+ * Apex grid is a web component for displaying data in a tabular format quick and easy.
+ *
+ * Out of the box it provides row virtualization, sort and filter operations (client and server side),
+ * the ability to template cells and headers and column hiding.
+ *
+ * @remarks
+ * A working, styled grid requires three things:
+ *  1. Register the element: `import 'apex-grid/define'` (or `ApexGrid.register()`).
+ *  2. Give the host element a bounded height, e.g. `apex-grid { height: 480px }` —
+ *     the virtualizer collapses without one.
+ *  3. Do NOT set `display` on the host — the component declares `:host { display: grid }`
+ *     internally and any override breaks the track layout.
+ *
+ * The grid is styled out of the box through `--ag-*` CSS custom properties —
+ * there is no theme to import and no `configureTheme()` call. Override `--ag-*`
+ * tokens on the host (or any ancestor) to rebrand; where an Ignite UI palette is
+ * present, the brand tokens auto-tint from it. For dark mode, set
+ * the `theme="dark"` attribute on the host for the built-in slate dark palette
+ * (further `--ag-*` overrides still compose on top). Add `tinted` (e.g.
+ * `theme="tinted"` or `theme="dark tinted"`) to mix the brand into the chrome
+ * so the grid wears its brand even at rest. See the README "Getting Started"
+ * and "Theming" sections for the full example and token list.
+ *
+ * @element apex-grid
+ *
+ * @attr {string} theme - Space-separated theme flags. `dark` opts into the built-in dark palette; `tinted` mixes `--ag-brand` into the chrome surfaces. Combine as `theme="dark tinted"`.
+ *
+ * @fires sorting - Emitted when sorting is initiated through the UI.
+ * @fires sorted - Emitted when a sort operation initiated through the UI has completed.
+ * @fires filtering - Emitted when filtering is initiated through the UI.
+ * @fires filtered - Emitted when a filter operation initiated through the UI has completed.
+ * @fires pageChanging - Cancellable. Emitted before page/page-size changes are applied.
+ * @fires pageChanged - Emitted after a page/page-size change has been applied.
+ * @fires quickFilterChanging - Cancellable. Emitted before a quick-filter value is applied.
+ * @fires quickFilterChanged - Emitted after a quick-filter change has been applied.
+ * @fires columnPinning - Cancellable. Emitted before a column's pin position changes.
+ * @fires columnPinned - Emitted after a column's pin position has changed.
+ * @fires columnMoving - Cancellable. Emitted before a column is moved.
+ * @fires columnMoved - Emitted after a column has been moved.
+ * @fires cellValueChanging - Cancellable. Emitted before a cell value is committed.
+ * @fires cellValueChanged - Emitted after a cell value has been committed.
+ * @fires rowEditStarted - Emitted when a row enters edit mode (row mode only).
+ * @fires rowEditEnded - Emitted when a row leaves edit mode (row mode only).
+ * @fires rowSelecting - Cancellable. Emitted before a selection-set change is applied.
+ * @fires rowSelected - Emitted after a selection-set change has been applied.
+ * @fires rowExpanding - Cancellable. Emitted before the row-expansion set changes (master-detail).
+ * @fires rowExpanded - Emitted after a row-expansion change has been applied.
+ * @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 live-region - Visually-hidden ARIA live region used for screen-reader announcements.
+ *
+ * @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)` (`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.
+ * @cssprop [--ag-surface-elevated] - Header background.
+ * @cssprop [--ag-hairline] - Header / structural gridline color.
+ * @cssprop [--ag-border] - Row separator color.
+ * @cssprop [--ag-text] - Primary text color.
+ * @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.
+ * @cssprop [--ag-font] - Grid font family.
+ * @cssprop [--ag-fs-cell] - Cell font size.
+ *
+ * @see {@link https://github.com/apexcharts/apex-grid/blob/main/packages/core/src/styles/_tokens.scss | _tokens.scss} for the complete `--ag-*` token list.
+ *
+ * @fires cellValidationFailed - Emitted when a candidate cell value is rejected by a column validator; the value is not written.
+ * @fires historyChanged - Emitted after the undo / redo stacks change; carries the current `canUndo` / `canRedo`.
+ * @fires stateChanged - Emitted (debounced) whenever the grid's restorable state changes; carries the new `getState` snapshot.
+ * @fires rowPinning - Cancellable. Emitted before a row is pinned, moved between bands, or unpinned.
+ * @fires rowPinned - Emitted after a row's pin state has changed.
+ * @fires rowMoving - Cancellable. Emitted before a row is moved via drag, keyboard, or `moveRow`.
+ * @fires rowMoved - Emitted after a row has been moved.
+ */
 export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGridEventMap<T>> {
     #private;
     static get tagName(): string;
@@ -687,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.
      *
@@ -759,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.
      *
@@ -1083,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.
      */
@@ -1139,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.
      */
@@ -1152,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).
@@ -1275,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.
@@ -1327,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;
@@ -1335,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;
     /**
@@ -1365,6 +1532,58 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * `rowEditEnded` in row mode.
      */
     commitEdit(): Promise<boolean>;
+    /**
+     * Applies many cell edits as a **single** operation.
+     *
+     * Every write goes through the same choke point interactive editing uses, so
+     * each one emits the cancellable `cellValueChanging` and then
+     * `cellValueChanged`, and runs the column's validators. What differs from
+     * calling {@link editCell} + {@link commitEdit} in a loop is that the whole
+     * set lands as one undo step and triggers one pipeline run, which is the
+     * point: a thousand `editCell` round-trips would be a thousand entries in the
+     * undo stack and a thousand re-renders.
+     *
+     * 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.
+     * @returns A per-outcome tally. `applied` counts cells whose value actually
+     * 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, on any page
+     * ```ts
+     * grid.applyEdits(grid.selectedRows.map((row) => ({ row, column: 'discount', value: 0 })));
+     * ```
+     */
+    applyEdits(edits: ReadonlyArray<{
+        column: Keys<T>;
+        value: unknown;
+    } & ({
+        rowIndex: number;
+        row?: never;
+    } | {
+        row: T;
+        rowIndex?: never;
+    })>): {
+        applied: number;
+        unchanged: number;
+        invalid: number;
+        cancelled: number;
+        skipped: number;
+    };
     /**
      * Discards the current edit without writing back to {@link ApexGrid.data}.
      */
@@ -1427,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;
     /**
@@ -1504,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;
     /**