apex-grid 1.0.1 → 2.0.0

package/internal/types.d.ts

@@ -0,0 +1,619 @@
+import type { ReactiveControllerHost, TemplateResult } from 'lit';
+import type ApexGridCell from '../components/cell.js';
+import type { ApexGrid } from '../components/grid.js';
+import type ApexGridHeader from '../components/header.js';
+import type ApexGridRow from '../components/row.js';
+import type { SortComparer } from '../operations/sort/types.js';
+export type NavigationState = 'previous' | 'current';
+export type GridHost<T extends object> = ReactiveControllerHost & ApexGrid<T>;
+/**
+ * Helper type for resolving keys of type T.
+ */
+export type Keys<T> = keyof T;
+/**
+ * Helper type for resolving types of type T.
+ */
+export type BasePropertyType<T, K extends Keys<T> = Keys<T>> = T[K];
+/**
+ * Helper type for resolving types of type T.
+ */
+export type PropertyType<T, K extends Keys<T> = Keys<T>> = K extends Keys<T> ? BasePropertyType<T, K> : never;
+/**
+ * The data type — or, for the declarative built-ins (`'select'`, `'rating'`,
+ * `'date'`, `'image'`), the presentation type — for the current column.
+ *
+ * @remarks
+ * - `'string'` / `'number'` are the primitive data types. They drive the
+ *   default filter operands, the default editor, and the default sort
+ *   comparison.
+ * - `'boolean'` stores `true` / `false`. In display mode the grid renders
+ *   a check-mark icon for `true` and a dimmed mark for `false`. In edit
+ *   mode the default editor is a native checkbox.
+ * - `'select'` is a presentation type for columns that store one of a fixed
+ *   set of values. Supply the available options via
+ *   {@link BaseColumnConfiguration.options}. The cell renders the matching
+ *   option's label in display mode and a native `<select>` in edit mode.
+ *   For sorting / filtering, select columns behave as their underlying
+ *   value type (typically string).
+ * - `'rating'` renders a numeric value (0..`max`) as filled stars in display
+ *   mode and as an interactive star picker in edit mode. Configure the star
+ *   count via {@link BaseColumnConfiguration.max} (defaults to `5`).
+ *   For sorting / filtering, rating columns behave as numbers.
+ * - `'date'` renders values as locale-aware formatted dates in display mode
+ *   and a native `<input type="date">` in edit mode. Accepts `Date`
+ *   instances, ISO strings, or millisecond timestamps as input and commits
+ *   back in the same shape. Configure the display format via
+ *   {@link BaseColumnConfiguration.format} (`'short' | 'medium' | 'long' |
+ *   'full'`, default `'medium'`).
+ * - `'image'` renders the value as an `<img>` source. Use
+ *   {@link BaseColumnConfiguration.shape} to pick between `'square'`
+ *   (default) and `'circle'`. The cell's default text editor is used for
+ *   editing the URL string when `editable: true` is set.
+ */
+export type DataType = 'number' | 'string' | 'boolean' | 'select' | 'rating' | 'date' | 'image';
+/**
+ * Display format presets for `'date'` columns. Map to
+ * `Intl.DateTimeFormatOptions.dateStyle`.
+ */
+export type ColumnDateFormat = 'short' | 'medium' | 'long' | 'full';
+/**
+ * An entry in a `'select'` column's `options` list. Bare values use
+ * `String(value)` as their display label; the explicit form lets you give
+ * a value a separate display label.
+ */
+export type ColumnSelectOption<V = unknown> = V | {
+    value: V;
+    label?: string;
+};
+/**
+ * Configures the sort behavior for the grid.
+ */
+export interface GridSortConfiguration {
+    /**
+     * Whether multiple sorting is enabled.
+     */
+    multiple: boolean;
+    /**
+     * Whether tri-state sorting is enabled.
+     */
+    triState: boolean;
+}
+/**
+ * Extended sort configuration for a column.
+ */
+export interface BaseColumnSortConfiguration<T, K extends Keys<T> = Keys<T>> {
+    /**
+     * Whether the sort operations will be case sensitive.
+     */
+    caseSensitive?: boolean;
+    /**
+     * Custom comparer function for sort operations for this column.
+     */
+    comparer?: SortComparer<T, K>;
+}
+/**
+ * See {@link BaseColumnSortConfiguration} for the full documentation.
+ */
+export type ColumnSortConfiguration<T, K extends Keys<T> = Keys<T>> = K extends Keys<T> ? BaseColumnSortConfiguration<T, K> : never;
+/**
+ * Extended filter configuration for a column.
+ */
+export interface ColumnFilterConfiguration {
+    /**
+     * Whether the filter operations will be case sensitive.
+     */
+    caseSensitive?: boolean;
+}
+/**
+ * Pin position for a column.
+ *
+ * @remarks
+ * `'start'` pins the column to the leading edge of the grid (inline-start);
+ * `'end'` pins it to the trailing edge. `null` or `undefined` means the column
+ * is part of the scrollable region.
+ */
+export type PinPosition = 'start' | 'end' | null;
+/** Configuration object for grid columns. */
+export interface BaseColumnConfiguration<T extends object, K extends Keys<T> = Keys<T>> {
+    /**
+     * The field for from the data the this column will reference.
+     */
+    key: K;
+    /**
+     * The type of data this column will reference.
+     *
+     * Affects the default filter operands if the column is with filtering enabled.
+     *
+     * @remarks
+     * If not passed, `string` is assumed to be the default type.
+     *
+     */
+    type?: DataType;
+    /**
+     * Optional text to display in the column header. By default, the column key is used
+     * to render the header text.
+     */
+    headerText?: string;
+    /**
+     * Width for the current column.
+     *
+     * Accepts most CSS units for controlling width.
+     *
+     * @remarks
+     * If not passed, the column will try to size itself based on the number of other
+     * columns and the total width of the grid.
+     *
+     */
+    width?: string;
+    /**
+     * Whether the column is hidden or not.
+     */
+    hidden?: boolean;
+    /**
+     * Whether this column is included when exporting via
+     * {@link ApexGrid.exportToCSV} or {@link ApexGrid.exportToXLSX}.
+     *
+     * @remarks
+     * Defaults to `true`. Set to `false` to omit a column from generated files
+     * (useful for action columns, derived UI, or sensitive fields). The
+     * grid-rendered selection checkbox column is never exported regardless of
+     * this flag.
+     */
+    exportable?: boolean;
+    /**
+     * Pin the column to a side of the grid.
+     *
+     * @remarks
+     * Pinned columns stay fixed during horizontal scroll. Use `'start'` (left in LTR,
+     * right in RTL) for the leading edge or `'end'` for the trailing edge. The grid
+     * renders columns in the order: `'start'`-pinned, unpinned, `'end'`-pinned, while
+     * preserving the original array order inside each group. The `columns` array
+     * itself is not mutated.
+     */
+    pinned?: PinPosition;
+    /**
+     * Whether this column can be reordered via drag-and-drop or the
+     * {@link ApexGrid.moveColumn} API.
+     *
+     * @remarks
+     * Has no effect unless the grid's `columnReordering` flag is `true`. When
+     * unset, columns inherit the grid-wide flag. Reordering is constrained to the
+     * column's own pinning group — start-pinned columns can only swap with other
+     * start-pinned columns, and likewise for end-pinned and unpinned.
+     */
+    reorderable?: boolean;
+    /**
+     * Whether the the column can be resized or not.
+     */
+    resizable?: boolean;
+    /**
+     * Whether the column can be sorted or not.
+     */
+    sort?: ColumnSortConfiguration<T, K> | boolean;
+    /**
+     * Whether filter operation can be applied on the column or not.
+     */
+    filter?: ColumnFilterConfiguration | boolean;
+    /**
+     * Header template callback.
+     */
+    headerTemplate?: (params: ApexHeaderContext<T>) => TemplateResult | unknown;
+    /**
+     * Cell template callback.
+     */
+    cellTemplate?: (params: ApexCellContext<T, K>) => TemplateResult | unknown;
+    /**
+     * Whether values in this column can be edited inline.
+     *
+     * @remarks
+     * Has no effect unless the grid's `editing.enabled` is `true`. The default
+     * editor is chosen from the column's `type` (`'string'` → text input,
+     * `'number'` → number input, `'boolean'` → checkbox). Supply
+     * {@link BaseColumnConfiguration.editorTemplate} for full control.
+     */
+    editable?: boolean;
+    /**
+     * Custom editor template invoked while this column's cell is in edit mode.
+     *
+     * @remarks
+     * The callback receives an {@link ApexEditorContext} that includes the cell
+     * value plus `commit` / `cancel` helpers. Returning a focusable element is
+     * recommended so keyboard handoff works.
+     */
+    editorTemplate?: (params: ApexEditorContext<T, K>) => TemplateResult | unknown;
+    /**
+     * Option list for columns with `type: 'select'`.
+     *
+     * @remarks
+     * Each entry is either a bare value or an explicit `{ value, label }` pair.
+     * The cell renders the matching option's `label` in display mode and a
+     * native `<select>` of all options in edit mode. Has no effect on columns
+     * with another `type`.
+     */
+    options?: ColumnSelectOption<BasePropertyType<T, K>>[];
+    /**
+     * Star count for columns with `type: 'rating'`.
+     *
+     * @remarks
+     * The displayed value is clamped to the range `[0, max]`. Defaults to `5`.
+     * Has no effect on columns with another `type`.
+     */
+    max?: number;
+    /**
+     * Display format for columns with `type: 'date'`.
+     *
+     * @remarks
+     * Selects an `Intl.DateTimeFormatOptions.dateStyle` preset. Defaults to
+     * `'medium'`. Has no effect on columns with another `type`.
+     */
+    format?: ColumnDateFormat;
+    /**
+     * Cropping shape for columns with `type: 'image'`.
+     *
+     * @remarks
+     * `'square'` (default) renders the image at its native aspect. `'circle'`
+     * crops to a circle (useful for avatars). Has no effect on columns with
+     * another `type`.
+     */
+    shape?: 'square' | 'circle';
+    /**
+     * Alt text for `<img>` elements rendered by `type: 'image'` columns.
+     *
+     * @remarks
+     * Defaults to the column key. Has no effect on columns with another
+     * `type`.
+     */
+    alt?: string;
+}
+/**
+ * See {@link BaseColumnConfiguration} for the full documentation.
+ */
+export type ColumnConfiguration<T extends object, K extends Keys<T> = Keys<T>> = K extends Keys<T> ? BaseColumnConfiguration<T, K> : never;
+export interface ActiveNode<T> {
+    column: Keys<T>;
+    row: number;
+}
+/**
+ * Context object for the column header template callback.
+ */
+export interface ApexHeaderContext<T extends object> {
+    /**
+     * The header element parent of the template.
+     */
+    parent: ApexGridHeader<T>;
+    /**
+     * The current configuration for the column.
+     */
+    column: ColumnConfiguration<T>;
+}
+/**
+ * Context object for the row cell template callback.
+ */
+export interface BaseApexCellContext<T extends object, K extends Keys<T> = Keys<T>> {
+    /**
+     * The cell element parent of the template.
+     */
+    parent: ApexGridCell<T>;
+    /**
+     * The row element containing the cell.
+     */
+    row: ApexGridRow<T>;
+    /**
+     * The current configuration for the column.
+     */
+    column: ColumnConfiguration<T, K>;
+    /**
+     * The value from the data source for this cell.
+     */
+    value: PropertyType<T, K>;
+    /**
+     * Commits a new value for this cell without entering edit mode. Available
+     * when the column is editable. Used by interactive display widgets
+     * (e.g. the built-in boolean checkbox) so they can toggle inline.
+     *
+     * Goes through the cancellable `cellValueChanging` event and follow-up
+     * `cellValueChanged` event — same write path as an edit-mode commit.
+     */
+    commit?: (value: PropertyType<T, K>) => Promise<boolean>;
+}
+/**
+ * See {@link BaseApexCellContext} for the full documentation.
+ */
+export type ApexCellContext<T extends object, K extends Keys<T> = Keys<T>> = K extends Keys<T> ? BaseApexCellContext<T, K> : never;
+/**
+ * Context object handed to a custom editor template.
+ *
+ * @remarks
+ * Includes the cell's current `value` plus `commit` / `cancel` callbacks so
+ * the editor can hand its result back to the grid. The custom editor is also
+ * responsible for forwarding `Enter` / `Escape` to those callbacks.
+ */
+export interface BaseApexEditorContext<T extends object, K extends Keys<T> = Keys<T>> extends BaseApexCellContext<T, K> {
+    /**
+     * Commits `value` as the new cell value, going through the cancellable
+     * `cellValueChanging` event and then `cellValueChanged`.
+     *
+     * @returns `true` if the value was applied, `false` if cancelled.
+     */
+    commit: (value: PropertyType<T, K>) => Promise<boolean>;
+    /**
+     * Discards the in-progress edit and exits edit mode.
+     */
+    cancel: () => void;
+}
+/**
+ * See {@link BaseApexEditorContext} for the full documentation.
+ */
+export type ApexEditorContext<T extends object, K extends Keys<T> = Keys<T>> = K extends Keys<T> ? BaseApexEditorContext<T, K> : never;
+/**
+ * The edit trigger used to enter cell edit mode.
+ *
+ * @remarks
+ * `'click'` enters edit on a single click on the cell; `'doubleClick'`
+ * requires a double click. Defaults to `'doubleClick'`.
+ */
+export type EditTrigger = 'click' | 'doubleClick';
+/**
+ * Edit mode for the grid.
+ *
+ * @remarks
+ * `'cell'` — each cell is committed independently on blur or `Enter`.
+ * `'row'` — all editable cells in the row enter edit mode together; changes
+ *  are batched and applied via {@link ApexGrid.commitEdit} or rolled back via
+ *  {@link ApexGrid.cancelEdit}.
+ */
+export type EditMode = 'cell' | 'row';
+/**
+ * Selection mode for the grid.
+ *
+ * @remarks
+ * `'single'` — at most one row may be selected at any time. New clicks
+ * replace the existing selection.
+ * `'multiple'` — multiple rows can be selected. Plain clicks replace the
+ * selection, Ctrl/Cmd+click toggles a row additively, and Shift+click
+ * selects a range from the previous anchor.
+ */
+export type SelectionMode = 'single' | 'multiple';
+/**
+ * Grid-level row-selection configuration.
+ */
+export interface GridSelectionConfiguration {
+    /**
+     * Whether row selection is enabled. Disabled by default.
+     */
+    enabled?: boolean;
+    /**
+     * Single-row vs multi-row selection. Defaults to `'multiple'`.
+     */
+    mode?: SelectionMode;
+    /**
+     * Whether to render the built-in checkbox column at the start of every
+     * row. When `false`, selection is still available via the public API
+     * (`selectRow`, `selectedRows = ...`) and via Space on the active row.
+     * Defaults to `false`.
+     */
+    showCheckboxColumn?: boolean;
+}
+/**
+ * Context passed to {@link GridExpansionConfiguration.detailTemplate}.
+ */
+export interface ApexDetailContext<T extends object> {
+    /** The row data for the expanded row. */
+    data: T;
+    /** The view-relative row index of the master row. */
+    rowIndex: number;
+    /** The grid element. Useful for emitting events back from the detail. */
+    parent: ApexGrid<T>;
+}
+/**
+ * Grid-level tree-data (nested rows) configuration.
+ *
+ * @remarks
+ * Tree mode renders hierarchical data as nested rows that share the same
+ * column layout — collapsible parents with indented children, AG Grid's
+ * "tree data" pattern. The data array stays flat; the grid derives the
+ * hierarchy from {@link getDataPath} at runtime.
+ *
+ * This is distinct from {@link GridExpansionConfiguration} (master-detail),
+ * which expands a row to show an arbitrary detail panel. Tree mode and
+ * expansion mode can be enabled together, but the chevron column is
+ * reserved by whichever is currently rendering the chevron — typically the
+ * tree feature when both are enabled.
+ *
+ * @example
+ * ```ts
+ * grid.tree = {
+ *   enabled: true,
+ *   getDataPath: (row) => row.path,
+ * };
+ * ```
+ */
+export interface GridTreeConfiguration<T extends object> {
+    /** Whether tree mode is enabled. Disabled by default. */
+    enabled?: boolean;
+    /**
+     * Callback that returns the hierarchical path for a row. The path is a
+     * sequence of segments from root to the row's own position — for example
+     * `['Adrian']` for a CEO, `['Adrian', 'Bryan']` for a VP under Adrian,
+     * and so on. Required when `enabled` is `true`.
+     */
+    getDataPath: (row: T) => readonly string[];
+    /**
+     * Which column displays the chevron + indentation. Defaults to the first
+     * visible non-hidden data column.
+     */
+    groupColumnKey?: Keys<T>;
+    /**
+     * Initial expansion state:
+     * - `false` (default): all rows collapsed.
+     * - `true`: every row expanded.
+     * - `number`: expand all rows up to and including the given depth (0 = roots only).
+     */
+    defaultExpanded?: boolean | number;
+    /**
+     * Pixels of indentation per depth level. Defaults to `20`.
+     */
+    childIndent?: number;
+}
+/**
+ * Grid-level row-expansion (master-detail) configuration.
+ */
+export interface GridExpansionConfiguration<T extends object> {
+    /**
+     * Whether row expansion is enabled. Disabled by default.
+     */
+    enabled?: boolean;
+    /**
+     * Callback that produces the detail panel content for an expanded row.
+     * Required when `enabled` is `true`.
+     */
+    detailTemplate?: (context: ApexDetailContext<T>) => TemplateResult | unknown;
+    /**
+     * Optional per-row predicate that gates which rows may be expanded. When
+     * omitted, every row is expandable.
+     */
+    isExpandable?: (row: T) => boolean;
+    /**
+     * Whether to render the built-in chevron toggle column at the start of
+     * every row (after the selection column, when present). Defaults to `true`.
+     * Set to `false` to drive expansion entirely through the public API or a
+     * custom cell template.
+     */
+    showToggleColumn?: boolean;
+}
+/**
+ * Grid-level editing configuration.
+ */
+export interface GridEditingConfiguration {
+    /**
+     * Whether editing is enabled. Per-column opt-in still applies via
+     * {@link BaseColumnConfiguration.editable}.
+     */
+    enabled?: boolean;
+    /**
+     * Whether each cell commits independently or whether the whole row is edited
+     * as a batch. Defaults to `'cell'`.
+     */
+    mode?: EditMode;
+    /**
+     * The interaction that opens an editor. Defaults to `'doubleClick'`.
+     */
+    trigger?: EditTrigger;
+}
+/**
+ * The parameters passed to a {@link DataPipelineHook} callback.
+ */
+export type DataPipelineParams<T extends object> = {
+    /**
+     * The current data state of the grid.
+     */
+    data: T[];
+    /**
+     * The grid component itself.
+     */
+    grid: ApexGrid<T>;
+    /**
+     * The type of data operation being performed.
+     */
+    type: 'sort' | 'filter' | 'quickFilter' | 'pagination';
+};
+/**
+ * Callback function for customizing data operations in the grid.
+ */
+export type DataPipelineHook<T extends object> = (state: DataPipelineParams<T>) => T[] | Promise<T[]>;
+/**
+ * Configuration for customizing the various data operations of the grid.
+ */
+export interface DataPipelineConfiguration<T extends object> {
+    /**
+     * Hook for customizing sort operations.
+     */
+    sort?: DataPipelineHook<T>;
+    /**
+     * Hook for customizing filter operations.
+     */
+    filter?: DataPipelineHook<T>;
+    /**
+     * Hook for customizing pagination operations.
+     *
+     * @remarks
+     * The hook receives the filtered + sorted data slice for the grid to render and the current
+     * pagination state. Return the page slice. For server-driven pagination, return the externally
+     * fetched page and report the row total via {@link ApexGrid.totalItems}.
+     */
+    pagination?: DataPipelineHook<T>;
+    /**
+     * Hook for customizing quick (global) filter operations.
+     *
+     * @remarks
+     * Called before column filtering. Return the records that match the {@link ApexGrid.quickFilter}
+     * value. If omitted, the default substring matcher is used.
+     */
+    quickFilter?: DataPipelineHook<T>;
+}
+/**
+ * The pagination mode for the grid.
+ *
+ * @remarks
+ * `'local'` — the grid slices the in-memory {@link ApexGrid.dataView} by `page` and `pageSize`.
+ * `'remote'` — the consumer drives data fetching; the grid emits paging events but does not
+ *  slice the data. Use together with {@link DataPipelineConfiguration.pagination} or by setting
+ *  `data` to the current page on `pageChanged`.
+ */
+export type PaginationMode = 'local' | 'remote';
+/**
+ * Pagination configuration for the grid.
+ */
+export interface PaginationConfiguration {
+    /**
+     * Whether pagination is enabled.
+     *
+     * @remarks
+     * When `false`, the grid renders no paginator and applies no slicing — the full
+     * {@link ApexGrid.dataView} is virtualized as usual.
+     */
+    enabled?: boolean;
+    /**
+     * The pagination mode. Defaults to `'local'`.
+     */
+    mode?: PaginationMode;
+    /**
+     * The current page (zero-based). Defaults to `0`.
+     */
+    page?: number;
+    /**
+     * The number of records per page. Defaults to `25`.
+     */
+    pageSize?: number;
+    /**
+     * The list of page sizes offered in the paginator's page-size dropdown.
+     * Defaults to `[10, 25, 50, 100]`.
+     */
+    pageSizeOptions?: number[];
+    /**
+     * In `'remote'` mode the consumer must supply the unfiltered row total so the paginator
+     * can compute the page count. Ignored in `'local'` mode.
+     */
+    totalItems?: number;
+}
+/**
+ * Resolved pagination state passed to controllers and event payloads.
+ */
+export interface PaginationState {
+    /**
+     * The current page (zero-based).
+     */
+    page: number;
+    /**
+     * The number of records per page.
+     */
+    pageSize: number;
+    /**
+     * The total number of pages.
+     */
+    pageCount: number;
+    /**
+     * The total number of records before pagination (after filter/sort).
+     */
+    totalItems: number;
+}

package/internal/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/internal/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { ReactiveControllerHost, TemplateResult } from 'lit';\nimport type ApexGridCell from '../components/cell.js';\nimport type { ApexGrid } from '../components/grid.js';\nimport type ApexGridHeader from '../components/header.js';\nimport type ApexGridRow from '../components/row.js';\nimport type { SortComparer } from '../operations/sort/types.js';\n\nexport type NavigationState = 'previous' | 'current';\nexport type GridHost<T extends object> = ReactiveControllerHost & ApexGrid<T>;\n\n/**\n * Helper type for resolving keys of type T.\n */\nexport type Keys<T> = keyof T;\n\n/**\n * Helper type for resolving types of type T.\n */\nexport type BasePropertyType<T, K extends Keys<T> = Keys<T>> = T[K];\n\n/**\n * Helper type for resolving types of type T.\n */\nexport type PropertyType<T, K extends Keys<T> = Keys<T>> = K extends Keys<T>\n  ? BasePropertyType<T, K>\n  : never;\n\n/**\n * The data type — or, for the declarative built-ins (`'select'`, `'rating'`,\n * `'date'`, `'image'`), the presentation type — for the current column.\n *\n * @remarks\n * - `'string'` / `'number'` are the primitive data types. They drive the\n *   default filter operands, the default editor, and the default sort\n *   comparison.\n * - `'boolean'` stores `true` / `false`. In display mode the grid renders\n *   a check-mark icon for `true` and a dimmed mark for `false`. In edit\n *   mode the default editor is a native checkbox.\n * - `'select'` is a presentation type for columns that store one of a fixed\n *   set of values. Supply the available options via\n *   {@link BaseColumnConfiguration.options}. The cell renders the matching\n *   option's label in display mode and a native `<select>` in edit mode.\n *   For sorting / filtering, select columns behave as their underlying\n *   value type (typically string).\n * - `'rating'` renders a numeric value (0..`max`) as filled stars in display\n *   mode and as an interactive star picker in edit mode. Configure the star\n *   count via {@link BaseColumnConfiguration.max} (defaults to `5`).\n *   For sorting / filtering, rating columns behave as numbers.\n * - `'date'` renders values as locale-aware formatted dates in display mode\n *   and a native `<input type=\"date\">` in edit mode. Accepts `Date`\n *   instances, ISO strings, or millisecond timestamps as input and commits\n *   back in the same shape. Configure the display format via\n *   {@link BaseColumnConfiguration.format} (`'short' | 'medium' | 'long' |\n *   'full'`, default `'medium'`).\n * - `'image'` renders the value as an `<img>` source. Use\n *   {@link BaseColumnConfiguration.shape} to pick between `'square'`\n *   (default) and `'circle'`. The cell's default text editor is used for\n *   editing the URL string when `editable: true` is set.\n */\nexport type DataType = 'number' | 'string' | 'boolean' | 'select' | 'rating' | 'date' | 'image';\n\n/**\n * Display format presets for `'date'` columns. Map to\n * `Intl.DateTimeFormatOptions.dateStyle`.\n */\nexport type ColumnDateFormat = 'short' | 'medium' | 'long' | 'full';\n\n/**\n * An entry in a `'select'` column's `options` list. Bare values use\n * `String(value)` as their display label; the explicit form lets you give\n * a value a separate display label.\n */\nexport type ColumnSelectOption<V = unknown> = V | { value: V; label?: string };\n\n/**\n * Configures the sort behavior for the grid.\n */\nexport interface GridSortConfiguration {\n  /**\n   * Whether multiple sorting is enabled.\n   */\n  multiple: boolean;\n  /**\n   * Whether tri-state sorting is enabled.\n   */\n  triState: boolean;\n}\n\n/**\n * Extended sort configuration for a column.\n */\nexport interface BaseColumnSortConfiguration<T, K extends Keys<T> = Keys<T>> {\n  /**\n   * Whether the sort operations will be case sensitive.\n   */\n  caseSensitive?: boolean;\n  /**\n   * Custom comparer function for sort operations for this column.\n   */\n  comparer?: SortComparer<T, K>;\n}\n\n/**\n * See {@link BaseColumnSortConfiguration} for the full documentation.\n */\nexport type ColumnSortConfiguration<T, K extends Keys<T> = Keys<T>> = K extends Keys<T>\n  ? BaseColumnSortConfiguration<T, K>\n  : never;\n\n/**\n * Extended filter configuration for a column.\n */\nexport interface ColumnFilterConfiguration {\n  /**\n   * Whether the filter operations will be case sensitive.\n   */\n  caseSensitive?: boolean;\n}\n\n/**\n * Pin position for a column.\n *\n * @remarks\n * `'start'` pins the column to the leading edge of the grid (inline-start);\n * `'end'` pins it to the trailing edge. `null` or `undefined` means the column\n * is part of the scrollable region.\n */\nexport type PinPosition = 'start' | 'end' | null;\n\n/** Configuration object for grid columns. */\nexport interface BaseColumnConfiguration<T extends object, K extends Keys<T> = Keys<T>> {\n  /**\n   * The field for from the data the this column will reference.\n   */\n  key: K;\n  /**\n   * The type of data this column will reference.\n   *\n   * Affects the default filter operands if the column is with filtering enabled.\n   *\n   * @remarks\n   * If not passed, `string` is assumed to be the default type.\n   *\n   */\n  type?: DataType;\n  /**\n   * Optional text to display in the column header. By default, the column key is used\n   * to render the header text.\n   */\n  headerText?: string;\n  /**\n   * Width for the current column.\n   *\n   * Accepts most CSS units for controlling width.\n   *\n   * @remarks\n   * If not passed, the column will try to size itself based on the number of other\n   * columns and the total width of the grid.\n   *\n   */\n  width?: string;\n  /**\n   * Whether the column is hidden or not.\n   */\n  hidden?: boolean;\n  /**\n   * Whether this column is included when exporting via\n   * {@link ApexGrid.exportToCSV} or {@link ApexGrid.exportToXLSX}.\n   *\n   * @remarks\n   * Defaults to `true`. Set to `false` to omit a column from generated files\n   * (useful for action columns, derived UI, or sensitive fields). The\n   * grid-rendered selection checkbox column is never exported regardless of\n   * this flag.\n   */\n  exportable?: boolean;\n  /**\n   * Pin the column to a side of the grid.\n   *\n   * @remarks\n   * Pinned columns stay fixed during horizontal scroll. Use `'start'` (left in LTR,\n   * right in RTL) for the leading edge or `'end'` for the trailing edge. The grid\n   * renders columns in the order: `'start'`-pinned, unpinned, `'end'`-pinned, while\n   * preserving the original array order inside each group. The `columns` array\n   * itself is not mutated.\n   */\n  pinned?: PinPosition;\n  /**\n   * Whether this column can be reordered via drag-and-drop or the\n   * {@link ApexGrid.moveColumn} API.\n   *\n   * @remarks\n   * Has no effect unless the grid's `columnReordering` flag is `true`. When\n   * unset, columns inherit the grid-wide flag. Reordering is constrained to the\n   * column's own pinning group — start-pinned columns can only swap with other\n   * start-pinned columns, and likewise for end-pinned and unpinned.\n   */\n  reorderable?: boolean;\n  /**\n   * Whether the the column can be resized or not.\n   */\n  resizable?: boolean;\n  /**\n   * Whether the column can be sorted or not.\n   */\n  sort?: ColumnSortConfiguration<T, K> | boolean;\n  /**\n   * Whether filter operation can be applied on the column or not.\n   */\n  filter?: ColumnFilterConfiguration | boolean;\n  /**\n   * Header template callback.\n   */\n  headerTemplate?: (params: ApexHeaderContext<T>) => TemplateResult | unknown;\n  /**\n   * Cell template callback.\n   */\n  cellTemplate?: (params: ApexCellContext<T, K>) => TemplateResult | unknown;\n  /**\n   * Whether values in this column can be edited inline.\n   *\n   * @remarks\n   * Has no effect unless the grid's `editing.enabled` is `true`. The default\n   * editor is chosen from the column's `type` (`'string'` → text input,\n   * `'number'` → number input, `'boolean'` → checkbox). Supply\n   * {@link BaseColumnConfiguration.editorTemplate} for full control.\n   */\n  editable?: boolean;\n  /**\n   * Custom editor template invoked while this column's cell is in edit mode.\n   *\n   * @remarks\n   * The callback receives an {@link ApexEditorContext} that includes the cell\n   * value plus `commit` / `cancel` helpers. Returning a focusable element is\n   * recommended so keyboard handoff works.\n   */\n  editorTemplate?: (params: ApexEditorContext<T, K>) => TemplateResult | unknown;\n  /**\n   * Option list for columns with `type: 'select'`.\n   *\n   * @remarks\n   * Each entry is either a bare value or an explicit `{ value, label }` pair.\n   * The cell renders the matching option's `label` in display mode and a\n   * native `<select>` of all options in edit mode. Has no effect on columns\n   * with another `type`.\n   */\n  options?: ColumnSelectOption<BasePropertyType<T, K>>[];\n  /**\n   * Star count for columns with `type: 'rating'`.\n   *\n   * @remarks\n   * The displayed value is clamped to the range `[0, max]`. Defaults to `5`.\n   * Has no effect on columns with another `type`.\n   */\n  max?: number;\n  /**\n   * Display format for columns with `type: 'date'`.\n   *\n   * @remarks\n   * Selects an `Intl.DateTimeFormatOptions.dateStyle` preset. Defaults to\n   * `'medium'`. Has no effect on columns with another `type`.\n   */\n  format?: ColumnDateFormat;\n  /**\n   * Cropping shape for columns with `type: 'image'`.\n   *\n   * @remarks\n   * `'square'` (default) renders the image at its native aspect. `'circle'`\n   * crops to a circle (useful for avatars). Has no effect on columns with\n   * another `type`.\n   */\n  shape?: 'square' | 'circle';\n  /**\n   * Alt text for `<img>` elements rendered by `type: 'image'` columns.\n   *\n   * @remarks\n   * Defaults to the column key. Has no effect on columns with another\n   * `type`.\n   */\n  alt?: string;\n}\n\n/**\n * See {@link BaseColumnConfiguration} for the full documentation.\n */\nexport type ColumnConfiguration<T extends object, K extends Keys<T> = Keys<T>> = K extends Keys<T>\n  ? BaseColumnConfiguration<T, K>\n  : never;\n\nexport interface ActiveNode<T> {\n  column: Keys<T>;\n  row: number;\n}\n\n/**\n * Context object for the column header template callback.\n */\nexport interface ApexHeaderContext<T extends object> {\n  /**\n   * The header element parent of the template.\n   */\n  parent: ApexGridHeader<T>;\n  /**\n   * The current configuration for the column.\n   */\n  column: ColumnConfiguration<T>;\n}\n\n/**\n * Context object for the row cell template callback.\n */\nexport interface BaseApexCellContext<T extends object, K extends Keys<T> = Keys<T>> {\n  /**\n   * The cell element parent of the template.\n   */\n  parent: ApexGridCell<T>;\n  /**\n   * The row element containing the cell.\n   */\n  row: ApexGridRow<T>;\n  /**\n   * The current configuration for the column.\n   */\n  column: ColumnConfiguration<T, K>;\n  /**\n   * The value from the data source for this cell.\n   */\n  value: PropertyType<T, K>;\n  /**\n   * Commits a new value for this cell without entering edit mode. Available\n   * when the column is editable. Used by interactive display widgets\n   * (e.g. the built-in boolean checkbox) so they can toggle inline.\n   *\n   * Goes through the cancellable `cellValueChanging` event and follow-up\n   * `cellValueChanged` event — same write path as an edit-mode commit.\n   */\n  commit?: (value: PropertyType<T, K>) => Promise<boolean>;\n}\n\n/**\n * See {@link BaseApexCellContext} for the full documentation.\n */\nexport type ApexCellContext<T extends object, K extends Keys<T> = Keys<T>> = K extends Keys<T>\n  ? BaseApexCellContext<T, K>\n  : never;\n\n/**\n * Context object handed to a custom editor template.\n *\n * @remarks\n * Includes the cell's current `value` plus `commit` / `cancel` callbacks so\n * the editor can hand its result back to the grid. The custom editor is also\n * responsible for forwarding `Enter` / `Escape` to those callbacks.\n */\nexport interface BaseApexEditorContext<T extends object, K extends Keys<T> = Keys<T>>\n  extends BaseApexCellContext<T, K> {\n  /**\n   * Commits `value` as the new cell value, going through the cancellable\n   * `cellValueChanging` event and then `cellValueChanged`.\n   *\n   * @returns `true` if the value was applied, `false` if cancelled.\n   */\n  commit: (value: PropertyType<T, K>) => Promise<boolean>;\n  /**\n   * Discards the in-progress edit and exits edit mode.\n   */\n  cancel: () => void;\n}\n\n/**\n * See {@link BaseApexEditorContext} for the full documentation.\n */\nexport type ApexEditorContext<T extends object, K extends Keys<T> = Keys<T>> = K extends Keys<T>\n  ? BaseApexEditorContext<T, K>\n  : never;\n\n/**\n * The edit trigger used to enter cell edit mode.\n *\n * @remarks\n * `'click'` enters edit on a single click on the cell; `'doubleClick'`\n * requires a double click. Defaults to `'doubleClick'`.\n */\nexport type EditTrigger = 'click' | 'doubleClick';\n\n/**\n * Edit mode for the grid.\n *\n * @remarks\n * `'cell'` — each cell is committed independently on blur or `Enter`.\n * `'row'` — all editable cells in the row enter edit mode together; changes\n *  are batched and applied via {@link ApexGrid.commitEdit} or rolled back via\n *  {@link ApexGrid.cancelEdit}.\n */\nexport type EditMode = 'cell' | 'row';\n\n/**\n * Selection mode for the grid.\n *\n * @remarks\n * `'single'` — at most one row may be selected at any time. New clicks\n * replace the existing selection.\n * `'multiple'` — multiple rows can be selected. Plain clicks replace the\n * selection, Ctrl/Cmd+click toggles a row additively, and Shift+click\n * selects a range from the previous anchor.\n */\nexport type SelectionMode = 'single' | 'multiple';\n\n/**\n * Grid-level row-selection configuration.\n */\nexport interface GridSelectionConfiguration {\n  /**\n   * Whether row selection is enabled. Disabled by default.\n   */\n  enabled?: boolean;\n  /**\n   * Single-row vs multi-row selection. Defaults to `'multiple'`.\n   */\n  mode?: SelectionMode;\n  /**\n   * Whether to render the built-in checkbox column at the start of every\n   * row. When `false`, selection is still available via the public API\n   * (`selectRow`, `selectedRows = ...`) and via Space on the active row.\n   * Defaults to `false`.\n   */\n  showCheckboxColumn?: boolean;\n}\n\n/**\n * Context passed to {@link GridExpansionConfiguration.detailTemplate}.\n */\nexport interface ApexDetailContext<T extends object> {\n  /** The row data for the expanded row. */\n  data: T;\n  /** The view-relative row index of the master row. */\n  rowIndex: number;\n  /** The grid element. Useful for emitting events back from the detail. */\n  parent: ApexGrid<T>;\n}\n\n/**\n * Grid-level tree-data (nested rows) configuration.\n *\n * @remarks\n * Tree mode renders hierarchical data as nested rows that share the same\n * column layout — collapsible parents with indented children, AG Grid's\n * \"tree data\" pattern. The data array stays flat; the grid derives the\n * hierarchy from {@link getDataPath} at runtime.\n *\n * This is distinct from {@link GridExpansionConfiguration} (master-detail),\n * which expands a row to show an arbitrary detail panel. Tree mode and\n * expansion mode can be enabled together, but the chevron column is\n * reserved by whichever is currently rendering the chevron — typically the\n * tree feature when both are enabled.\n *\n * @example\n * ```ts\n * grid.tree = {\n *   enabled: true,\n *   getDataPath: (row) => row.path,\n * };\n * ```\n */\nexport interface GridTreeConfiguration<T extends object> {\n  /** Whether tree mode is enabled. Disabled by default. */\n  enabled?: boolean;\n  /**\n   * Callback that returns the hierarchical path for a row. The path is a\n   * sequence of segments from root to the row's own position — for example\n   * `['Adrian']` for a CEO, `['Adrian', 'Bryan']` for a VP under Adrian,\n   * and so on. Required when `enabled` is `true`.\n   */\n  getDataPath: (row: T) => readonly string[];\n  /**\n   * Which column displays the chevron + indentation. Defaults to the first\n   * visible non-hidden data column.\n   */\n  groupColumnKey?: Keys<T>;\n  /**\n   * Initial expansion state:\n   * - `false` (default): all rows collapsed.\n   * - `true`: every row expanded.\n   * - `number`: expand all rows up to and including the given depth (0 = roots only).\n   */\n  defaultExpanded?: boolean | number;\n  /**\n   * Pixels of indentation per depth level. Defaults to `20`.\n   */\n  childIndent?: number;\n}\n\n/**\n * Grid-level row-expansion (master-detail) configuration.\n */\nexport interface GridExpansionConfiguration<T extends object> {\n  /**\n   * Whether row expansion is enabled. Disabled by default.\n   */\n  enabled?: boolean;\n  /**\n   * Callback that produces the detail panel content for an expanded row.\n   * Required when `enabled` is `true`.\n   */\n  detailTemplate?: (context: ApexDetailContext<T>) => TemplateResult | unknown;\n  /**\n   * Optional per-row predicate that gates which rows may be expanded. When\n   * omitted, every row is expandable.\n   */\n  isExpandable?: (row: T) => boolean;\n  /**\n   * Whether to render the built-in chevron toggle column at the start of\n   * every row (after the selection column, when present). Defaults to `true`.\n   * Set to `false` to drive expansion entirely through the public API or a\n   * custom cell template.\n   */\n  showToggleColumn?: boolean;\n}\n\n/**\n * Grid-level editing configuration.\n */\nexport interface GridEditingConfiguration {\n  /**\n   * Whether editing is enabled. Per-column opt-in still applies via\n   * {@link BaseColumnConfiguration.editable}.\n   */\n  enabled?: boolean;\n  /**\n   * Whether each cell commits independently or whether the whole row is edited\n   * as a batch. Defaults to `'cell'`.\n   */\n  mode?: EditMode;\n  /**\n   * The interaction that opens an editor. Defaults to `'doubleClick'`.\n   */\n  trigger?: EditTrigger;\n}\n\n/**\n * The parameters passed to a {@link DataPipelineHook} callback.\n */\nexport type DataPipelineParams<T extends object> = {\n  /**\n   * The current data state of the grid.\n   */\n  data: T[];\n  /**\n   * The grid component itself.\n   */\n  grid: ApexGrid<T>;\n  /**\n   * The type of data operation being performed.\n   */\n  type: 'sort' | 'filter' | 'quickFilter' | 'pagination';\n};\n\n/**\n * Callback function for customizing data operations in the grid.\n */\nexport type DataPipelineHook<T extends object> = (\n  state: DataPipelineParams<T>\n) => T[] | Promise<T[]>;\n\n/**\n * Configuration for customizing the various data operations of the grid.\n */\nexport interface DataPipelineConfiguration<T extends object> {\n  /**\n   * Hook for customizing sort operations.\n   */\n  sort?: DataPipelineHook<T>;\n  /**\n   * Hook for customizing filter operations.\n   */\n  filter?: DataPipelineHook<T>;\n  /**\n   * Hook for customizing pagination operations.\n   *\n   * @remarks\n   * The hook receives the filtered + sorted data slice for the grid to render and the current\n   * pagination state. Return the page slice. For server-driven pagination, return the externally\n   * fetched page and report the row total via {@link ApexGrid.totalItems}.\n   */\n  pagination?: DataPipelineHook<T>;\n  /**\n   * Hook for customizing quick (global) filter operations.\n   *\n   * @remarks\n   * Called before column filtering. Return the records that match the {@link ApexGrid.quickFilter}\n   * value. If omitted, the default substring matcher is used.\n   */\n  quickFilter?: DataPipelineHook<T>;\n}\n\n/**\n * The pagination mode for the grid.\n *\n * @remarks\n * `'local'` — the grid slices the in-memory {@link ApexGrid.dataView} by `page` and `pageSize`.\n * `'remote'` — the consumer drives data fetching; the grid emits paging events but does not\n *  slice the data. Use together with {@link DataPipelineConfiguration.pagination} or by setting\n *  `data` to the current page on `pageChanged`.\n */\nexport type PaginationMode = 'local' | 'remote';\n\n/**\n * Pagination configuration for the grid.\n */\nexport interface PaginationConfiguration {\n  /**\n   * Whether pagination is enabled.\n   *\n   * @remarks\n   * When `false`, the grid renders no paginator and applies no slicing — the full\n   * {@link ApexGrid.dataView} is virtualized as usual.\n   */\n  enabled?: boolean;\n  /**\n   * The pagination mode. Defaults to `'local'`.\n   */\n  mode?: PaginationMode;\n  /**\n   * The current page (zero-based). Defaults to `0`.\n   */\n  page?: number;\n  /**\n   * The number of records per page. Defaults to `25`.\n   */\n  pageSize?: number;\n  /**\n   * The list of page sizes offered in the paginator's page-size dropdown.\n   * Defaults to `[10, 25, 50, 100]`.\n   */\n  pageSizeOptions?: number[];\n  /**\n   * In `'remote'` mode the consumer must supply the unfiltered row total so the paginator\n   * can compute the page count. Ignored in `'local'` mode.\n   */\n  totalItems?: number;\n}\n\n/**\n * Resolved pagination state passed to controllers and event payloads.\n */\nexport interface PaginationState {\n  /**\n   * The current page (zero-based).\n   */\n  page: number;\n  /**\n   * The number of records per page.\n   */\n  pageSize: number;\n  /**\n   * The total number of pages.\n   */\n  pageCount: number;\n  /**\n   * The total number of records before pagination (after filter/sort).\n   */\n  totalItems: number;\n}\n"]}