apex-grid 1.0.1 → 2.0.0

package/components/grid.d.ts

@@ -0,0 +1,1173 @@
+import { ContextProvider } from '@lit/context';
+import { nothing } from 'lit';
+import { DataOperationsController } from '../controllers/data-operation.js';
+import { GridDOMController } from '../controllers/dom.js';
+import { StateController } from '../controllers/state.js';
+import { type CSVExportOptions, type XLSXExportOptions } from '../internal/export.js';
+import { EventEmitterBase } from '../internal/mixins/event-emitter.js';
+import type { ColumnConfiguration, DataPipelineConfiguration, GridEditingConfiguration, GridExpansionConfiguration, GridSelectionConfiguration, GridSortConfiguration, GridTreeConfiguration, Keys, PaginationConfiguration, PaginationState, PinPosition } from '../internal/types.js';
+import type { FilterExpression } from '../operations/filter/types.js';
+import type { SortExpression } from '../operations/sort/types.js';
+import ApexFilterRow from './filter-row.js';
+import ApexGridHeaderRow from './header-row.js';
+import ApexGridPaginator from './paginator.js';
+import ApexGridRow from './row.js';
+import ApexGridToolbar from './toolbar.js';
+import ApexVirtualizer from './virtualizer.js';
+/**
+ * Event object for the filtering event of the grid.
+ */
+export interface ApexFilteringEvent<T extends object> {
+    /**
+     * The target column for the filter operation.
+     */
+    key: Keys<T>;
+    /**
+     * The filter expression(s) to apply.
+     */
+    expressions: FilterExpression<T>[];
+    /**
+     * The type of modification which will be applied to the filter
+     * state of the column.
+     *
+     * @remarks
+     * `add` - a new filter expression will be added to the state of the column.
+     * `modify` - an existing filter expression will be modified.
+     * `remove` - the expression(s) will be removed from the state of the column.
+     */
+    type: 'add' | 'modify' | 'remove';
+}
+/**
+ * Event object for the filtered event of the grid.
+ */
+export interface ApexFilteredEvent<T extends object> {
+    /**
+     * The target column for the filter operation.
+     */
+    key: Keys<T>;
+    /**
+     * The filter state of the column after the operation.
+     */
+    state: FilterExpression<T>[];
+}
+/**
+ * Event payload for the cancellable `pageChanging` event.
+ */
+export interface ApexPageChangingEvent {
+    /**
+     * The current page (zero-based) before the change.
+     */
+    page: number;
+    /**
+     * The current page size before the change.
+     */
+    pageSize: number;
+    /**
+     * The proposed page (zero-based) the grid will navigate to.
+     */
+    nextPage: number;
+    /**
+     * The proposed page size after the change.
+     */
+    nextPageSize: number;
+}
+/**
+ * Event payload for the `pageChanged` event. Mirrors {@link PaginationState}.
+ */
+export interface ApexPageChangedEvent extends PaginationState {
+}
+/**
+ * Event payload for the cancellable `quickFilterChanging` event.
+ */
+export interface ApexQuickFilterChangingEvent {
+    /**
+     * The current quick-filter value before the change.
+     */
+    value: string;
+    /**
+     * The proposed quick-filter value.
+     */
+    nextValue: string;
+}
+/**
+ * Event payload for the `quickFilterChanged` event.
+ */
+export interface ApexQuickFilterChangedEvent {
+    /**
+     * The resolved quick-filter value after the change.
+     */
+    value: string;
+}
+/**
+ * Drop position relative to a target column when reordering.
+ */
+export type ColumnDropPosition = 'before' | 'after';
+/**
+ * Event payload for the cancellable `cellValueChanging` event.
+ */
+export interface ApexCellValueChangingEvent<T extends object> {
+    /**
+     * The column key of the edited cell.
+     */
+    key: Keys<T>;
+    /**
+     * The view-relative row index (matches {@link ApexGrid.pageItems}).
+     */
+    rowIndex: number;
+    /**
+     * The data record being edited (a live reference to the row in
+     * {@link ApexGrid.data}).
+     */
+    data: T;
+    /**
+     * The value before the edit.
+     */
+    oldValue: unknown;
+    /**
+     * The candidate new value.
+     */
+    newValue: unknown;
+}
+/**
+ * Event payload for the `cellValueChanged` event.
+ */
+export interface ApexCellValueChangedEvent<T extends object> {
+    /**
+     * The column key of the edited cell.
+     */
+    key: Keys<T>;
+    /**
+     * The view-relative row index after the change.
+     */
+    rowIndex: number;
+    /**
+     * The data record after the change (a live reference to the row in
+     * {@link ApexGrid.data}).
+     */
+    data: T;
+    /**
+     * The applied value.
+     */
+    value: unknown;
+}
+/**
+ * Event payload for the `rowEditStarted` event.
+ */
+export interface ApexRowEditStartedEvent {
+    /**
+     * The view-relative row index entering edit mode.
+     */
+    rowIndex: number;
+}
+/**
+ * Event payload for the `rowEditEnded` event.
+ */
+export interface ApexRowEditEndedEvent {
+    /**
+     * The view-relative row index that left edit mode.
+     */
+    rowIndex: number;
+    /**
+     * `true` when pending edits were applied, `false` when discarded.
+     */
+    committed: boolean;
+}
+/**
+ * Event payload for the cancellable `columnMoving` event.
+ */
+export interface ApexColumnMovingEvent<T extends object> {
+    /**
+     * The column being moved.
+     */
+    key: Keys<T>;
+    /**
+     * The current index of the moving column in {@link ApexGrid.columns}.
+     */
+    fromIndex: number;
+    /**
+     * The target column key. The dragged column will be placed `position`
+     * (before/after) this column.
+     */
+    toKey: Keys<T>;
+    /**
+     * Whether the dragged column is being placed before or after `toKey`.
+     */
+    position: ColumnDropPosition;
+}
+/**
+ * Event payload for the `columnMoved` event.
+ */
+export interface ApexColumnMovedEvent<T extends object> {
+    /**
+     * The column that was moved.
+     */
+    key: Keys<T>;
+    /**
+     * The original index in {@link ApexGrid.columns}.
+     */
+    fromIndex: number;
+    /**
+     * The resolved index in {@link ApexGrid.columns} after the move.
+     */
+    toIndex: number;
+}
+/**
+ * Event payload for the cancellable `rowSelecting` event.
+ */
+export interface ApexRowSelectingEvent<T extends object> {
+    /**
+     * The rows that will become selected by this change.
+     */
+    added: T[];
+    /**
+     * The rows that will become deselected by this change.
+     */
+    removed: T[];
+    /**
+     * The full current selection before this change is applied.
+     */
+    current: T[];
+    /**
+     * The full selection after this change would be applied. Listeners can
+     * inspect this to decide whether to cancel.
+     */
+    next: T[];
+}
+/**
+ * Event payload for the `rowSelected` event.
+ */
+export interface ApexRowSelectedEvent<T extends object> {
+    /**
+     * The rows that became selected in this change.
+     */
+    added: T[];
+    /**
+     * The rows that became deselected in this change.
+     */
+    removed: T[];
+    /**
+     * The full current selection after the change has been applied.
+     */
+    selected: T[];
+}
+/**
+ * Event payload for the cancellable `treeRowExpanding` event.
+ */
+export interface ApexTreeRowExpandingEvent<T extends object> {
+    /** Rows that will become expanded by this change. */
+    added: T[];
+    /** Rows that will become collapsed by this change. */
+    removed: T[];
+    /** The full current tree-expansion set before this change is applied. */
+    current: T[];
+    /** The full set after this change would be applied. */
+    next: T[];
+}
+/**
+ * Event payload for the `treeRowExpanded` event.
+ */
+export interface ApexTreeRowExpandedEvent<T extends object> {
+    /** Rows that became expanded in this change. */
+    added: T[];
+    /** Rows that became collapsed in this change. */
+    removed: T[];
+    /** The full tree-expansion set after the change has been applied. */
+    expanded: T[];
+}
+/**
+ * Event payload for the cancellable `rowExpanding` event.
+ */
+export interface ApexRowExpandingEvent<T extends object> {
+    /** The rows that will become expanded by this change. */
+    added: T[];
+    /** The rows that will become collapsed by this change. */
+    removed: T[];
+    /** The full current expansion set before this change is applied. */
+    current: T[];
+    /**
+     * The full expansion set after this change would be applied. Listeners can
+     * inspect this to decide whether to cancel.
+     */
+    next: T[];
+}
+/**
+ * Event payload for the `rowExpanded` event.
+ */
+export interface ApexRowExpandedEvent<T extends object> {
+    /** The rows that became expanded in this change. */
+    added: T[];
+    /** The rows that became collapsed in this change. */
+    removed: T[];
+    /** The full expansion set after the change has been applied. */
+    expanded: T[];
+}
+/**
+ * Event payload for the cancellable `columnPinning` event.
+ */
+export interface ApexColumnPinningEvent<T extends object> {
+    /**
+     * The target column key.
+     */
+    key: Keys<T>;
+    /**
+     * The current pin position before the change (`null` if unpinned).
+     */
+    previous: PinPosition;
+    /**
+     * The proposed pin position (`null` to unpin).
+     */
+    next: PinPosition;
+}
+/**
+ * Event payload for the `columnPinned` event.
+ */
+export interface ApexColumnPinnedEvent<T extends object> {
+    /**
+     * The target column key.
+     */
+    key: Keys<T>;
+    /**
+     * The resolved pin position after the change.
+     */
+    pinned: PinPosition;
+}
+/**
+ * Events for the apex-grid.
+ */
+export interface ApexGridEventMap<T extends object> {
+    /**
+     * Emitted when sorting is initiated through the UI.
+     * Returns the sort expression which will be used for the operation.
+     *
+     * @remarks
+     * The event is cancellable which prevents the operation from being applied.
+     * The expression can be modified prior to the operation running.
+     *
+     * @event
+     */
+    sorting: CustomEvent<SortExpression<T>>;
+    /**
+     * Emitted when a sort operation initiated through the UI has completed.
+     * Returns the sort expression used for the operation.
+     *
+     * @event
+     */
+    sorted: CustomEvent<SortExpression<T>>;
+    /**
+     * Emitted when filtering is initiated through the UI.
+     *
+     * @remarks
+     * The event is cancellable which prevents the operation from being applied.
+     * The expression can be modified prior to the operation running.
+     *
+     * @event
+     */
+    filtering: CustomEvent<ApexFilteringEvent<T>>;
+    /**
+     * Emitted when a filter operation initiated through the UI has completed.
+     * Returns the filter state for the affected column.
+     *
+     * @event
+     */
+    filtered: CustomEvent<ApexFilteredEvent<T>>;
+    /**
+     * Emitted before the grid navigates to a new page or applies a new page size.
+     *
+     * @remarks
+     * Cancellable — calling `preventDefault()` (or returning a falsy result from
+     * `addEventListener` synchronously) aborts the page change.
+     *
+     * @event
+     */
+    pageChanging: CustomEvent<ApexPageChangingEvent>;
+    /**
+     * Emitted after a page or page-size change has been applied and the pipeline has run.
+     *
+     * @event
+     */
+    pageChanged: CustomEvent<ApexPageChangedEvent>;
+    /**
+     * Emitted before the quick-filter value is applied.
+     *
+     * @remarks
+     * Cancellable — calling `preventDefault()` aborts the change. The value can
+     * be replaced inside the listener by reassigning {@link ApexGrid.quickFilter}.
+     *
+     * @event
+     */
+    quickFilterChanging: CustomEvent<ApexQuickFilterChangingEvent>;
+    /**
+     * Emitted after a quick-filter change has been applied and the pipeline has run.
+     *
+     * @event
+     */
+    quickFilterChanged: CustomEvent<ApexQuickFilterChangedEvent>;
+    /**
+     * Emitted before a column's pin position changes.
+     *
+     * @remarks
+     * Cancellable — calling `preventDefault()` aborts the change.
+     *
+     * @event
+     */
+    columnPinning: CustomEvent<ApexColumnPinningEvent<T>>;
+    /**
+     * Emitted after a column's pin position change has been applied.
+     *
+     * @event
+     */
+    columnPinned: CustomEvent<ApexColumnPinnedEvent<T>>;
+    /**
+     * Emitted before a column is moved through the UI or {@link ApexGrid.moveColumn}.
+     *
+     * @remarks
+     * Cancellable — calling `preventDefault()` aborts the move. The event detail
+     * carries the source column key, its current array index, the target column
+     * key and the drop position.
+     *
+     * @event
+     */
+    columnMoving: CustomEvent<ApexColumnMovingEvent<T>>;
+    /**
+     * Emitted after a column has been moved.
+     *
+     * @event
+     */
+    columnMoved: CustomEvent<ApexColumnMovedEvent<T>>;
+    /**
+     * Emitted before a cell value is committed.
+     *
+     * @remarks
+     * Cancellable — `preventDefault()` rolls back the candidate value. In row
+     * edit mode the event still fires per-cell at commit time.
+     *
+     * @event
+     */
+    cellValueChanging: CustomEvent<ApexCellValueChangingEvent<T>>;
+    /**
+     * Emitted after a cell value has been committed.
+     *
+     * @event
+     */
+    cellValueChanged: CustomEvent<ApexCellValueChangedEvent<T>>;
+    /**
+     * Emitted when a row enters edit mode (row edit mode only).
+     *
+     * @event
+     */
+    rowEditStarted: CustomEvent<ApexRowEditStartedEvent>;
+    /**
+     * Emitted when a row leaves edit mode, with `committed` reporting whether
+     * pending edits were applied (row edit mode only).
+     *
+     * @event
+     */
+    rowEditEnded: CustomEvent<ApexRowEditEndedEvent>;
+    /**
+     * Emitted before the row selection set changes.
+     *
+     * @remarks
+     * Cancellable — calling `preventDefault()` aborts the selection change.
+     * Fires for every selection-mutating call (toggle, range select, select-all,
+     * programmatic `selectedRows = ...`).
+     *
+     * @event
+     */
+    /**
+     * Emitted before the tree-row expansion set changes.
+     *
+     * @remarks
+     * Fires only when {@link ApexGrid.tree} is enabled and a row's tree
+     * expansion is toggled (via the chevron, the public API, or
+     * `expand-all/collapse-all`). Cancellable.
+     *
+     * @event
+     */
+    treeRowExpanding: CustomEvent<ApexTreeRowExpandingEvent<T>>;
+    /**
+     * Emitted after a tree-row expansion change has been applied.
+     *
+     * @event
+     */
+    treeRowExpanded: CustomEvent<ApexTreeRowExpandedEvent<T>>;
+    /**
+     * Emitted before the row expansion set changes.
+     *
+     * @remarks
+     * Cancellable — calling `preventDefault()` aborts the change. Fires for
+     * every expansion-mutating call (toggle, expand-all, programmatic
+     * `expandedRows = ...`).
+     *
+     * @event
+     */
+    rowExpanding: CustomEvent<ApexRowExpandingEvent<T>>;
+    /**
+     * Emitted after a row-expansion change has been applied.
+     *
+     * @event
+     */
+    rowExpanded: CustomEvent<ApexRowExpandedEvent<T>>;
+    rowSelecting: CustomEvent<ApexRowSelectingEvent<T>>;
+    /**
+     * Emitted after a row-selection change has been applied.
+     *
+     * @event
+     */
+    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 four setup steps:
+ *  1. Register the element: `import 'apex-grid/define'` (or `ApexGrid.register()`).
+ *  2. Configure an Ignite UI theme + import the matching CSS, e.g.
+ *     `import { configureTheme } from 'igniteui-webcomponents';`
+ *     `import 'igniteui-webcomponents/themes/light/bootstrap.css';`
+ *     `configureTheme('bootstrap');`
+ *  3. Give the host element a bounded height, e.g. `apex-grid { height: 480px }` —
+ *     the virtualizer collapses without one.
+ *  4. Do NOT set `display` on the host — the component declares `:host { display: grid }`
+ *     internally and any override breaks the track layout.
+ *
+ * See the README "Getting Started" section for the full example.
+ *
+ * @element apex-grid
+ *
+ * @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.
+ *
+ */
+export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGridEventMap<T>> {
+    static get tagName(): "apex-grid";
+    static styles: import("lit").CSSResult;
+    /**
+     * Registers `<apex-grid>` and its internal dependencies with the custom-element
+     * registry. Idempotent — safe to call more than once.
+     *
+     * @remarks
+     * Registering the element is only step one of four required for a visible, styled
+     * grid. You must also configure an Ignite UI theme + CSS, give the host a bounded
+     * height, and avoid overriding `display` on the host. See the README
+     * "Getting Started" section for the full setup.
+     */
+    static register(): void;
+    protected stateController: StateController<T>;
+    protected DOM: GridDOMController<T>;
+    protected dataController: DataOperationsController<T>;
+    protected stateProvider: ContextProvider<{
+        __context__: StateController<any>;
+    }, this>;
+    protected scrollContainer: ApexVirtualizer;
+    protected headerRow: ApexGridHeaderRow<T>;
+    protected filterRow: ApexFilterRow<T>;
+    protected paginator: ApexGridPaginator<T>;
+    protected toolbar: ApexGridToolbar<T>;
+    protected dataState: Array<T>;
+    protected _rows: NodeListOf<ApexGridRow<T>>;
+    /** Column configuration for the grid. */
+    columns: Array<ColumnConfiguration<T>>;
+    /** The data source for the grid. */
+    data: Array<T>;
+    /**
+     * Whether the grid will try to "resolve" its column configuration based on the passed
+     * data source.
+     *
+     * @remarks
+     * This is usually executed on initial rendering in the DOM. It depends on having an existing data source
+     * to infer the column configuration for the grid.
+     * Passing an empty data source or having a late bound data source (such as a HTTP request) will usually
+     * result in empty column configuration for the grid.
+     *
+     * This property is ignored if any existing column configuration already exists in the grid.
+     *
+     * In a scenario where you want to bind a new data source and still keep the auto-generation behavior,
+     * make sure to reset the column collection of the grid before passing in the new data source.
+     *
+     * @example
+     * ```typescript
+     * // assuming autoGenerate is set to true
+     * grid.columns = [];
+     * grid.data = [...];
+     * ```
+     *
+     * @attr auto-generate
+     */
+    autoGenerate: boolean;
+    /** Sort configuration property for the grid. */
+    sortConfiguration: GridSortConfiguration;
+    /**
+     * Configuration object which controls remote data operations for the grid.
+     */
+    dataPipelineConfiguration: DataPipelineConfiguration<T>;
+    /**
+     * Pagination configuration for the grid.
+     *
+     * @remarks
+     * Pagination is disabled by default. Set `enabled: true` and (optionally) `pageSize`
+     * to render the built-in `<apex-grid-paginator>` and slice the dataView. For
+     * server-side pagination set `mode: 'remote'` and supply `totalItems`. The grid
+     * emits the cancellable `pageChanging` event before applying a change and the
+     * `pageChanged` event after the pipeline has run.
+     *
+     * @example
+     * ```ts
+     * grid.pagination = { enabled: true, pageSize: 25 };
+     * grid.addEventListener('pageChanged', (event) => {
+     *   console.log('Now on page', event.detail.page, 'of', event.detail.pageCount);
+     * });
+     * ```
+     */
+    pagination?: PaginationConfiguration;
+    /**
+     * The quick-filter (global search) value applied to the dataView.
+     *
+     * @remarks
+     * When non-empty, the grid filters records whose visible-column values contain
+     * the term (case-insensitive substring match). Customise by providing
+     * {@link DataPipelineConfiguration.quickFilter}.
+     *
+     * @attr quick-filter
+     */
+    quickFilter: string;
+    /**
+     * Whether the built-in quick-filter input is rendered in the toolbar.
+     *
+     * @remarks
+     * The {@link ApexGrid.quickFilter} value can be controlled programmatically
+     * regardless of this flag; this only controls the toolbar input UI.
+     *
+     * @attr show-quick-filter
+     */
+    showQuickFilter: boolean;
+    /**
+     * Whether the built-in export menu is rendered in the toolbar.
+     *
+     * @remarks
+     * When `true`, the toolbar shows a download button on the trailing side;
+     * clicking it opens a menu with "Export CSV" and "Export XLSX" entries
+     * that call {@link ApexGrid.exportToCSV} and {@link ApexGrid.exportToXLSX}
+     * respectively. Both methods remain callable programmatically regardless
+     * of this flag.
+     *
+     * @attr show-export
+     */
+    showExport: boolean;
+    /**
+     * Enables drag-and-drop column reordering on the column headers.
+     *
+     * @remarks
+     * Per-column opt-out is available through {@link BaseColumnConfiguration.reorderable}.
+     * Reordering is constrained to a column's own pinning group — start-pinned
+     * columns can only swap with start-pinned, unpinned with unpinned, and
+     * end-pinned with end-pinned.
+     *
+     * @attr column-reordering
+     */
+    columnReordering: boolean;
+    /**
+     * Inline editing configuration for the grid.
+     *
+     * @remarks
+     * Editing is disabled by default. Set `enabled: true` and (optionally) `mode`
+     * (`'cell' | 'row'`) and `trigger` (`'click' | 'doubleClick'`) to opt in.
+     * Per-column opt-in is required via {@link BaseColumnConfiguration.editable}.
+     *
+     * @example
+     * ```ts
+     * grid.editing = { enabled: true, mode: 'cell', trigger: 'doubleClick' };
+     * ```
+     */
+    editing?: GridEditingConfiguration;
+    /**
+     * Row selection configuration for the grid.
+     *
+     * @remarks
+     * Selection is disabled by default. Set `enabled: true` and (optionally)
+     * `mode` (`'single' | 'multiple'`) and `showCheckboxColumn` to opt in.
+     *
+     * @example
+     * ```ts
+     * grid.selection = { enabled: true, mode: 'multiple', showCheckboxColumn: true };
+     * ```
+     */
+    selection?: GridSelectionConfiguration;
+    /**
+     * The currently selected rows, in insertion order.
+     *
+     * @remarks
+     * Returned as a plain array snapshot — mutating the returned array does
+     * not change the grid's selection. Set this property to replace the
+     * selection programmatically (goes through the cancellable
+     * `rowSelecting` event).
+     */
+    get selectedRows(): T[];
+    set selectedRows(rows: ReadonlyArray<T>);
+    /**
+     * Selects `row`, replacing the existing selection in `'single'` mode or
+     * 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.
+     */
+    selectRow(row: T): Promise<boolean>;
+    /**
+     * Deselects `row`. No-op if `row` is not currently selected.
+     */
+    deselectRow(row: T): Promise<boolean>;
+    /**
+     * Toggles selection of `row`.
+     */
+    toggleRowSelection(row: T): Promise<boolean>;
+    /**
+     * Selects every row in the current view ({@link dataView}). No-op in
+     * `'single'` selection mode.
+     */
+    selectAllRows(): Promise<boolean>;
+    /**
+     * Clears the row selection.
+     */
+    clearSelection(): Promise<boolean>;
+    /**
+     * Whether `row` is currently selected.
+     */
+    isRowSelected(row: T): boolean;
+    /**
+     * Row-expansion (master-detail) configuration for the grid.
+     *
+     * @remarks
+     * Expansion is disabled by default. Set `enabled: true` and supply a
+     * `detailTemplate` to opt in. The default UX renders a chevron toggle in a
+     * dedicated leading column; set `showToggleColumn: false` to drive
+     * expansion entirely through the public API or a custom cell template.
+     *
+     * @example
+     * ```ts
+     * grid.expansion = {
+     *   enabled: true,
+     *   detailTemplate: ({ data }) => html`<order-summary .order=${data}></order-summary>`,
+     * };
+     * ```
+     */
+    expansion?: GridExpansionConfiguration<T>;
+    /**
+     * The currently expanded rows, in insertion order.
+     *
+     * @remarks
+     * Returned as a plain array snapshot — mutating the returned array does
+     * not change the grid's expansion state. Set this property to replace the
+     * expansion set programmatically (goes through the cancellable
+     * `rowExpanding` event).
+     */
+    get expandedRows(): T[];
+    set expandedRows(rows: ReadonlyArray<T>);
+    /**
+     * Expands `row`. No-op when the row is already expanded, expansion is
+     * disabled, or the optional `isExpandable` predicate rejects it.
+     */
+    expandRow(row: T): Promise<boolean>;
+    /**
+     * Collapses `row`. No-op when the row is not currently expanded.
+     */
+    collapseRow(row: T): Promise<boolean>;
+    /**
+     * Toggles expansion of `row`.
+     */
+    toggleRowExpansion(row: T): Promise<boolean>;
+    /**
+     * Expands every row in {@link ApexGrid.dataView} that passes the optional
+     * `isExpandable` predicate.
+     */
+    expandAllRows(): Promise<boolean>;
+    /**
+     * Collapses every currently expanded row.
+     */
+    collapseAllRows(): Promise<boolean>;
+    /**
+     * Whether `row` is currently expanded.
+     */
+    isRowExpanded(row: T): boolean;
+    /**
+     * Tree-data (nested rows) configuration for the grid.
+     *
+     * @remarks
+     * Tree mode keeps {@link ApexGrid.data} flat; the grid derives the
+     * hierarchy from a user-supplied `getDataPath(row)` callback (AG Grid's
+     * "tree data" pattern). When enabled, the first visible data column (or
+     * the column referenced by `groupColumnKey`) renders a chevron toggle
+     * and depth-based indentation.
+     *
+     * @example
+     * ```ts
+     * grid.tree = {
+     *   enabled: true,
+     *   getDataPath: (row) => row.path,    // e.g., ['Adrian'], ['Adrian', 'Bryan']
+     *   defaultExpanded: true,
+     * };
+     * ```
+     */
+    tree?: GridTreeConfiguration<T>;
+    /**
+     * Toggles tree-expansion of `row`. No-op when tree mode is disabled or
+     * the row has no children.
+     */
+    toggleTreeRow(row: T): Promise<boolean>;
+    /**
+     * Expands a tree row. No-op when the row is already expanded, has no
+     * children, or tree mode is disabled.
+     */
+    expandTreeRow(row: T): Promise<boolean>;
+    /**
+     * Collapses a tree row. No-op when the row is not currently expanded.
+     */
+    collapseTreeRow(row: T): Promise<boolean>;
+    /** Expands every parent row in the current tree. */
+    expandAllTreeRows(): Promise<boolean>;
+    /** Collapses every currently-expanded tree row. */
+    collapseAllTreeRows(): Promise<boolean>;
+    /** Whether `row` is currently expanded in the tree. */
+    isTreeRowExpanded(row: T): boolean;
+    /**
+     * Set the sort state for the grid.
+     */
+    set sortExpressions(expressions: SortExpression<T>[]);
+    /**
+     * Get the sort state for the grid.
+     */
+    get sortExpressions(): SortExpression<T>[];
+    /**
+     * Set the filter state for the grid.
+     */
+    set filterExpressions(expressions: FilterExpression<T>[]);
+    /**
+     * Get the filter state for the grid.
+     */
+    get filterExpressions(): FilterExpression<T>[];
+    /**
+     * Returns the collection of rendered row elements in the grid.
+     *
+     * @remarks
+     * Since the grid has virtualization, this property returns only the currently rendered
+     * chunk of elements in the DOM.
+     */
+    get rows(): ApexGridRow<T>[];
+    /**
+     * Returns the state of the data source after sort/filter operations
+     * have been applied.
+     */
+    get dataView(): ReadonlyArray<T>;
+    /**
+     * The columns in visual render order: `'start'`-pinned columns first, then
+     * unpinned columns, then `'end'`-pinned columns.
+     *
+     * @remarks
+     * 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.
+     */
+    get displayColumns(): ReadonlyArray<ColumnConfiguration<T>>;
+    /**
+     * The total number of items in the {@link ApexGrid.dataView} collection.
+     *
+     * @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.
+     */
+    get totalItems(): number;
+    /**
+     * 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.
+     */
+    get pageItems(): ReadonlyArray<T>;
+    /**
+     * The current zero-based page index.
+     */
+    get page(): number;
+    set page(value: number);
+    /**
+     * The current page size.
+     */
+    get pageSize(): number;
+    set pageSize(value: number);
+    /**
+     * The total number of pages computed from {@link ApexGrid.totalItems} and {@link ApexGrid.pageSize}.
+     */
+    get pageCount(): number;
+    protected watchColumns(_: ColumnConfiguration<T>[], newConfig?: ColumnConfiguration<T>[]): void;
+    protected dataChanged(): void;
+    protected pipeline(): Promise<void>;
+    protected paginationChanged(): void;
+    protected quickFilterChanged(): void;
+    constructor();
+    protected updated(): void;
+    protected firstUpdated(): void;
+    /**
+     * Performs a filter operation in the grid based on the passed expression(s).
+     */
+    filter(config: FilterExpression<T> | FilterExpression<T>[]): void;
+    /**
+     * Performs a sort operation in the grid based on the passed expression(s).
+     */
+    sort(expressions: SortExpression<T> | SortExpression<T>[]): void;
+    /**
+     * Resets the current sort state of the control.
+     */
+    clearSort(key?: Keys<T>): void;
+    /**
+     * Resets the current filter state of the control.
+     */
+    clearFilter(key?: Keys<T>): void;
+    /**
+     * Navigates the grid to the given zero-based `page` index.
+     *
+     * @remarks
+     * Emits the cancellable `pageChanging` event before applying the change and the
+     * `pageChanged` event after. Out-of-range values are clamped into `[0, pageCount - 1]`.
+     *
+     * @param page - The target zero-based page index.
+     * @returns `true` if the change was applied, `false` if cancelled or a no-op.
+     *
+     * @example
+     * ```ts
+     * await grid.gotoPage(2);
+     * ```
+     */
+    gotoPage(page: number): Promise<boolean>;
+    /**
+     * Updates the grid's page size and returns to the first page.
+     *
+     * @remarks
+     * Emits the cancellable `pageChanging` event before applying the change and the
+     * `pageChanged` event after.
+     *
+     * @param size - The new page size (must be a positive integer).
+     * @returns `true` if the change was applied, `false` if cancelled or a no-op.
+     */
+    setPageSize(size: number): Promise<boolean>;
+    /**
+     * Navigates to the next page. No-op if already on the last page.
+     */
+    nextPage(): Promise<boolean>;
+    /**
+     * Navigates to the previous page. No-op if already on the first page.
+     */
+    previousPage(): Promise<boolean>;
+    /**
+     * Navigates to the first page.
+     */
+    firstPage(): Promise<boolean>;
+    /**
+     * Navigates to the last page.
+     */
+    lastPage(): Promise<boolean>;
+    /**
+     * Applies a new quick-filter (global search) value, emitting the cancellable
+     * `quickFilterChanging` event first and the `quickFilterChanged` event after the
+     * pipeline has run.
+     *
+     * @param value - The new quick-filter value. Pass `''` to clear.
+     * @returns `true` if the change was applied, `false` if cancelled or a no-op.
+     *
+     * @example
+     * ```ts
+     * await grid.setQuickFilter('john');
+     * ```
+     */
+    setQuickFilter(value: string): Promise<boolean>;
+    /**
+     * Returns a {@link ColumnConfiguration} for a given column.
+     */
+    getColumn(id: Keys<T> | number): ColumnConfiguration<T> | undefined;
+    /**
+     * Updates the column configuration of the grid.
+     *
+     * @remarks
+     * Each updated column is replaced with a fresh object reference so that cells
+     * and headers re-render with the new template / configuration. The
+     * user-supplied `columns` array is also reassigned for Lit reactivity.
+     */
+    updateColumns(columns: ColumnConfiguration<T> | ColumnConfiguration<T>[]): void;
+    /**
+     * Pins a column to one of the grid's edges, or unpins it when `position` is `null`.
+     *
+     * @remarks
+     * Emits the cancellable `columnPinning` event first and the `columnPinned`
+     * event after the update is applied. The user-supplied {@link ApexGrid.columns}
+     * array is not reordered — only the visual render order changes.
+     *
+     * @param key - The target column key.
+     * @param position - `'start'`, `'end'`, or `null` to unpin.
+     * @returns `true` if the change was applied, `false` if cancelled or a no-op.
+     *
+     * @example
+     * ```ts
+     * await grid.pinColumn('name', 'start');
+     * await grid.pinColumn('actions', 'end');
+     * ```
+     */
+    pinColumn(key: Keys<T>, position: PinPosition): Promise<boolean>;
+    /**
+     * Unpins a column. Equivalent to {@link ApexGrid.pinColumn}(`key`, `null`).
+     *
+     * @param key - The target column key.
+     * @returns `true` if the change was applied, `false` if the column was already
+     * unpinned or the operation was cancelled.
+     */
+    unpinColumn(key: Keys<T>): Promise<boolean>;
+    /**
+     * The cell currently in edit mode, or `null`.
+     */
+    get editingCell(): {
+        rowIndex: number;
+        columnKey: Keys<T>;
+    } | null;
+    /**
+     * The view-relative index of the row currently in edit mode (row edit mode
+     * only), or `null`.
+     */
+    get editingRow(): number | null;
+    /**
+     * Begins editing the cell at `(rowIndex, columnKey)`.
+     *
+     * @remarks
+     * `rowIndex` is the view-relative index (matches {@link ApexGrid.pageItems}).
+     * Returns `false` when the column isn't editable, the row index is out of
+     * range, or the request was rejected (for example in row mode with pending
+     * changes that couldn't be committed).
+     */
+    editCell(rowIndex: number, columnKey: Keys<T>): Promise<boolean>;
+    /**
+     * Begins editing the entire row at `rowIndex` (row edit mode only).
+     *
+     * @returns `false` when editing is disabled, the grid is in cell mode, or
+     * the row index is out of range.
+     */
+    editRow(rowIndex: number): Promise<boolean>;
+    /**
+     * Commits the current edit.
+     *
+     * @remarks
+     * In cell mode this writes the active cell's pending value. In row mode it
+     * flushes all pending values for the active row. Emits `cellValueChanging`
+     * per changed cell (cancellable) and `cellValueChanged` after, followed by
+     * `rowEditEnded` in row mode.
+     */
+    commitEdit(): Promise<boolean>;
+    /**
+     * Discards the current edit without writing back to {@link ApexGrid.data}.
+     */
+    cancelEdit(): void;
+    /**
+     * Exports the current grid contents as a CSV string and (in a browser
+     * context) triggers a download.
+     *
+     * @remarks
+     * By default the export uses the post-filter/post-sort `dataView`, includes
+     * every visible column with `exportable !== false`, and prepends a UTF-8 BOM
+     * so Excel opens the file with the right encoding. Pass `source: 'page'` to
+     * export only the current page, `source: 'selected'` to export the current
+     * row selection, or `source: 'all'` to export the raw `data` array. The
+     * returned string is the same content written to the file — useful for
+     * tests or routing the bytes elsewhere.
+     *
+     * @example
+     * ```ts
+     * grid.exportToCSV();                                  // download data.csv
+     * grid.exportToCSV({ filename: 'users', source: 'selected' });
+     * const text = grid.exportToCSV({ filename: '' });     // string only, no download
+     * ```
+     */
+    exportToCSV(options?: CSVExportOptions<T>): string;
+    /**
+     * Exports the current grid contents as an `.xlsx` workbook and (in a browser
+     * context) triggers a download.
+     *
+     * @remarks
+     * Produces a single-sheet workbook with a bold header row. Numbers, booleans
+     * and `Date` values keep their native cell type in Excel; everything else is
+     * written as inline strings. Sharing the same `source` / `columns` /
+     * `formatter` options as {@link ApexGrid.exportToCSV}, plus an optional
+     * `sheetName`. Pass `filename: ''` to skip the download and only receive
+     * the bytes back.
+     *
+     * @example
+     * ```ts
+     * grid.exportToXLSX();
+     * grid.exportToXLSX({ filename: 'users', sheetName: 'Users' });
+     * ```
+     */
+    exportToXLSX(options?: XLSXExportOptions<T>): Uint8Array;
+    /**
+     * Moves a column relative to another column.
+     *
+     * @remarks
+     * Emits the cancellable `columnMoving` event first and `columnMoved` after.
+     * Reordering only succeeds when the source and target columns share the same
+     * pinning group (start / unpinned / end) — cross-group moves return `false`.
+     * Use {@link ApexGrid.pinColumn} to change a column's pinning group first.
+     *
+     * @param fromKey - The column to move.
+     * @param toKey - The reference column.
+     * @param position - Whether to place `fromKey` before or after `toKey`. Defaults to `'before'`.
+     * @returns `true` if the move was applied, `false` if cancelled or a no-op.
+     *
+     * @example
+     * ```ts
+     * await grid.moveColumn('email', 'name', 'after');
+     * ```
+     */
+    moveColumn(fromKey: Keys<T>, toKey: Keys<T>, position?: ColumnDropPosition): Promise<boolean>;
+    protected bodyClickHandler(event: MouseEvent): void;
+    protected bodyKeydownHandler(event: KeyboardEvent): void;
+    protected renderHeaderRow(): import("lit-html").TemplateResult<1>;
+    protected renderBody(): import("lit-html").TemplateResult<1>;
+    protected renderFilterRow(): typeof nothing | import("lit-html").TemplateResult<1>;
+    protected renderToolbar(): typeof nothing | import("lit-html").TemplateResult<1>;
+    protected renderPaginator(): typeof nothing | import("lit-html").TemplateResult<1>;
+    /**
+     * Renders a visually-hidden polite live region. Status messages set via
+     * {@link announce} land here; screen readers will read them aloud without
+     * stealing focus. We intentionally keep this in the shadow root so we
+     * don't have to coordinate consumer DOM placement.
+     */
+    protected renderLiveRegion(): import("lit-html").TemplateResult<1>;
+    protected render(): import("lit-html").TemplateResult<1>;
+    /**
+     * Sets the live region's announcement text. Screen readers configured to
+     * read polite live updates will read the new value aloud.
+     *
+     * @remarks
+     * Use this from custom UI affordances (e.g. an "Apply filter" button) so
+     * the change is announced. Built-in operations (sort / filter / page /
+     * select / expand) call this internally already.
+     */
+    announce(message: string): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        [ApexGrid.tagName]: ApexGrid<object>;
+    }
+}