apex-grid 3.6.0 → 4.0.0-beta.2

package/components/grid.d.ts

@@ -692,17 +692,19 @@ export interface ApexGridEventMap<T extends object> {
  *
  * 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.
+ * tokens on the host (or any ancestor) to rebrand; the family `--apx-*` tokens
+ * (`--apx-accent`, `--apx-fore`, `--apx-grid`, `--apx-surface`,
+ * `--apx-font-family`, `--apx-radius-factor`) apply where no `--ag-*` token is
+ * set. To follow an Ignite UI theme, import the `apex-grid/ignite-ui` add-on.
+ * 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"`.
+ * @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"`. With the `apex-grid/ignite-ui` add-on a grid without `dark` or `light` follows the Ignite UI variant, and `light` keeps it light.
  *
  * @fires sorting - Emitted when sorting is initiated through the UI.
  * @fires sorted - Emitted when a sort operation initiated through the UI has completed.
@@ -727,9 +729,35 @@ 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] - Brand color for selection, focus rings, and accents. Falls back to `--apx-accent`, then (with the `apex-grid/ignite-ui` add-on) the Ignite UI primary.
  * @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.
@@ -755,8 +783,12 @@ export interface ApexGridEventMap<T extends object> {
  * @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-radius] - Outer card corner radius. The radii (`--ag-radius`, `-sm`, `-xs`, not the pill) scale with `--apx-radius-factor` while it is set (single lengths only).
+ * @cssprop [--ag-font] - Grid font family. Falls back to `--apx-font-family`, then (with the `apex-grid/ignite-ui` add-on) the Ignite UI `--ig-font-family`.
+ * @cssprop [--ag-overlay] - Background of the enterprise popups (filter builder, set filter, AI panel, tool panel, status bar). Unset, each keeps its built-in colour; set it with `--ag-overlay-text`.
+ * @cssprop [--ag-overlay-text] - Text color of the enterprise popups; their lines, muted text and hover wash are mixed from the two.
+ * @cssprop [--ag-dark-overlay] - Popup background on dark grids.
+ * @cssprop [--ag-dark-overlay-text] - Popup text color on dark grids.
  * @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.
@@ -773,15 +805,23 @@ 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.
      *
      * @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.
+     * Registering the element is only step one of three required for a visible, styled
+     * grid. You must also 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>;
@@ -977,6 +1017,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.
      *
@@ -997,13 +1064,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.
      *
@@ -1020,7 +1088,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>;
     /**
@@ -1032,8 +1101,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>;
     /**
@@ -1107,6 +1176,43 @@ 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;
+    /**
+     * Whether this grid follows the design-system add-on (`apex-grid/ignite-ui`).
+     * `false`, reflected as `design-system="off"`, turns the Ignite UI colours
+     * and font off for this grid; the Ignite UI variant still picks its mode.
+     * Without the add-on it changes nothing.
+     *
+     * @attr design-system
+     */
+    designSystem: boolean;
+    /**
+     * Whether this grid reads the family `--apx-*` tokens and, with the
+     * `apex-grid/ignite-ui` add-on, Ignite UI (the variant included). `false`,
+     * reflected as `tokens="off"`, turns them off for the grid and the content
+     * it renders, so it keeps the built-in look and the `--ag-*` tokens you set.
+     *
+     * @attr tokens
+     */
+    tokens: boolean;
     /**
      * Column groups rendered as spanning headers above the column header row.
      *
@@ -1238,7 +1344,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>[];
     /**
@@ -1254,23 +1362,34 @@ 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>;
     /**
@@ -1319,10 +1438,12 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
      * 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;
+    disconnectedCallback(): void;
     protected firstUpdated(): void;
     /**
      * Performs a filter operation in the grid based on the passed expression(s).
@@ -1746,8 +1867,16 @@ export declare class ApexGrid<T extends object> extends EventEmitterBase<ApexGri
     /**
      * 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
@@ -1757,10 +1886,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;
@@ -1773,6 +1904,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`
@@ -1780,6 +1918,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