apex-grid 3.5.0 → 4.0.0-beta.1

package/internal/types.d.ts

@@ -4,7 +4,6 @@ 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>;
 /**
  * A custom action button contributed to the toolbar's trailing actions area.
@@ -404,9 +403,18 @@ export interface ColumnGroupConfiguration {
 export interface ValidatorContext<T extends object, K extends Keys<T> = Keys<T>> {
     /** The column configuration the value is being validated against. */
     column: ColumnConfiguration<T, K>;
-    /** The full data record being edited (a live reference). */
+    /**
+     * The full data record being edited (a live reference). In a row-mode
+     * commit it is the staged row instead: a copy of the record (same
+     * prototype) with the row's staged values applied, so cross-field rules
+     * see the row being saved. A validator that throws on the copy (one that
+     * reads private class fields, say) is run again with the live record.
+     */
     data: T;
-    /** The view-relative row index of the edited cell. */
+    /**
+     * The view-relative row index of the edited cell (`-1` for a pinned row or
+     * a record on another page).
+     */
     rowIndex: number;
 }
 /**
@@ -439,12 +447,29 @@ export interface ApexHeaderContext<T extends object> {
 export interface BaseApexCellContext<T extends object, K extends Keys<T> = Keys<T>> {
     /**
      * The cell element parent of the template.
+     *
+     * @remarks
+     * A rendered element, not the record: the grid may later re-bind it to show
+     * another record (a pinned band does when a row above it is unpinned). Read
+     * {@link data} for the record, and do not hold this element across an
+     * `await`.
      */
     parent: ApexGridCell<T>;
     /**
      * The row element containing the cell.
+     *
+     * @remarks
+     * A rendered element that may later show another record, as for
+     * {@link parent}. Read {@link data} for the record, and do not hold this
+     * element across an `await`.
      */
     row: ApexGridRow<T>;
+    /**
+     * The record (row data object) this cell was rendered for. Stays the same
+     * record for the life of this context object, even after the cell element
+     * is re-bound to another record.
+     */
+    readonly data: T;
     /**
      * The current configuration for the column.
      */
@@ -460,6 +485,8 @@ export interface BaseApexCellContext<T extends object, K extends Keys<T> = Keys<
      *
      * Goes through the cancellable `cellValueChanging` event and follow-up
      * `cellValueChanged` event — same write path as an edit-mode commit.
+     * Writes to {@link data}, the record the context was built for, so a commit
+     * issued after an `await` still lands on that record.
      */
     commit?: (value: PropertyType<T, K>) => Promise<boolean>;
 }
@@ -480,6 +507,12 @@ export interface BaseApexEditorContext<T extends object, K extends Keys<T> = Key
      * Commits `value` as the new cell value, going through the cancellable
      * `cellValueChanging` event and then `cellValueChanged`.
      *
+     * @remarks
+     * Unlike the display context's `commit`, this one is not bound to
+     * {@link BaseApexCellContext.data}: it commits the cell that is in edit
+     * when it is called. Do not call it after an `await` that can outlive the
+     * edit, as another cell may be in edit by then.
+     *
      * @returns `true` if the value was applied, `false` if cancelled.
      */
     commit: (value: PropertyType<T, K>) => Promise<boolean>;
@@ -524,7 +557,7 @@ export type SelectionMode = 'single' | 'multiple';
 /**
  * Grid-level row-selection configuration.
  */
-export interface GridSelectionConfiguration {
+export interface GridSelectionConfiguration<T extends object = any> {
     /**
      * Whether row selection is enabled. Disabled by default.
      */
@@ -540,6 +573,32 @@ export interface GridSelectionConfiguration {
      * Defaults to `false`.
      */
     showCheckboxColumn?: boolean;
+    /**
+     * Decides per row whether it can be selected. When unset every row is
+     * selectable, pinned rows included.
+     *
+     * @remarks
+     * A row this returns `false` for renders no checkbox (its cell stays, so
+     * the columns line up), carries no `aria-selected`, and is skipped by
+     * every selection path: checkbox and cell clicks, Shift and Ctrl/Cmd
+     * clicks, Space, Select all, `selectRow`, `selectedRows = ...` and
+     * `setState`. The header checkbox counts only selectable rows. When
+     * `selection` or `data` is reassigned, selected rows the predicate now
+     * rejects are dropped through the cancellable `rowSelecting` event. A
+     * selected row it comes to reject otherwise (pinned or edited in place)
+     * keeps its checkbox until it is deselected.
+     *
+     * @example
+     * ```ts
+     * // A pinned total row is a summary, not a record to pick.
+     * grid.selection = {
+     *   enabled: true,
+     *   showCheckboxColumn: true,
+     *   isRowSelectable: (row) => row !== totalRow,
+     * };
+     * ```
+     */
+    isRowSelectable?: (row: T) => boolean;
 }
 /**
  * Context passed to {@link GridExpansionConfiguration.detailTemplate}.
@@ -627,6 +686,12 @@ export interface GridExpansionConfiguration<T extends object> {
      * custom cell template.
      */
     showToggleColumn?: boolean;
+    /**
+     * Parts used inside the `detailTemplate` content to re-export, so
+     * `apex-grid::part(name)` can style them from outside the grid. The panel
+     * itself is always reachable as `detail-panel`.
+     */
+    exportParts?: ReadonlyArray<string>;
 }
 /**
  * Undo / redo history configuration for cell-data edits.
@@ -724,7 +789,7 @@ export type DataPipelineParams<T extends object> = {
     /**
      * The type of data operation being performed.
      */
-    type: 'sort' | 'filter' | 'quickFilter' | 'pagination';
+    type: 'sort' | 'filter' | 'quickFilter';
 };
 /**
  * Callback function for customizing data operations in the grid.
@@ -742,15 +807,6 @@ export interface DataPipelineConfiguration<T extends object> {
      * 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.
      *
@@ -764,10 +820,11 @@ export interface DataPipelineConfiguration<T extends object> {
  * 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`.
+ * `'local'`: the grid slices the in-memory {@link ApexGrid.dataView} by `page` and `pageSize`.
+ * `'remote'`: the consumer drives data fetching. The grid does not slice `data`; it renders
+ *  whatever `data` holds as the current page. Listen for `pageChanged`, fetch that page and
+ *  assign it to `data`, and keep {@link PaginationConfiguration.totalItems} at the number of
+ *  rows the server holds for the current filter so the paginator can count the pages.
  */
 export type PaginationMode = 'local' | 'remote';
 /**
@@ -800,10 +857,22 @@ export interface PaginationConfiguration {
      */
     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.
+     * In `'remote'` mode, the number of rows the server holds for the current filter, so the
+     * paginator can compute the page count. Update it when a server side filter changes that
+     * number. Ignored in `'local'` mode, where the grid counts the rows itself.
      */
     totalItems?: number;
+    /**
+     * The paginator layout. Defaults to `'full'`.
+     *
+     * @remarks
+     * `'full'` shows the page size select, the "start-end of total" summary, first, previous,
+     * "page / count", next and last. When the grid is too narrow for all of them it drops the
+     * page size select first, then first and last, so previous and next always stay reachable.
+     *
+     * `'compact'` always uses the narrow layout: the summary, previous, "page / count" and next.
+     */
+    paginator?: 'compact' | 'full';
 }
 /**
  * Resolved pagination state passed to controllers and event payloads.
@@ -822,7 +891,9 @@ export interface PaginationState {
      */
     pageCount: number;
     /**
-     * The total number of records before pagination (after filter/sort).
+     * The post-filter, post-sort row count. With pagination enabled, the rows paged
+     * through: rows pinned to the top or bottom (they show on every page) are left out.
+     * In `'remote'` mode, the {@link PaginationConfiguration.totalItems} you supplied.
      */
     totalItems: number;
 }

package/internal/types.js.map

@@ -1 +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 * A custom action button contributed to the toolbar's trailing actions area.\n *\n * @remarks\n * The seam derived grids use to add toolbar buttons, mirroring the export-format\n * seam: the community grid contributes none (its {@link ApexGrid.toolbarActions}\n * returns `[]`), and the toolbar renders one button per entry, invoking\n * {@link ToolbarAction.run} on click.\n */\nexport interface ToolbarAction {\n  /** Stable identifier, e.g. `'create-chart'`. */\n  id: string;\n  /** Button label. */\n  label: string;\n  /** Invoked when the button is clicked. */\n  run(): void;\n}\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>> =\n  K extends Keys<T> ? BasePropertyType<T, K> : 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 *\n * The remaining types are premium presentation renderers over primitive\n * values; for sorting / filtering they behave as their underlying value type:\n * - `'currency'` formats a number via `Intl.NumberFormat` (tabular, right\n *   aligned). Configure with {@link BaseColumnConfiguration.currency} /\n *   {@link BaseColumnConfiguration.locale}. Editable via a number input.\n * - `'avatar'` renders the value's first letter in a tinted circle (hue is\n *   derived from the value, stable per row).\n * - `'badge'` renders the value as a colored pill. Pick the look with\n *   {@link BaseColumnConfiguration.badgeVariant}.\n * - `'progress'` renders a number (0..`max`, default `max` 100) as a health\n *   bar; the fill color tiers at ≥80 / ≥65 / below.\n * - `'sparkline'` renders a `number[]` as an inline trend chart with an\n *   optional delta label ({@link BaseColumnConfiguration.showDelta}).\n * - `'status'` renders a pill with a leading dot. The state is taken from\n *   {@link BaseColumnConfiguration.statusVariant} or inferred from the value.\n */\nexport type DataType =\n  | 'number'\n  | 'string'\n  | 'boolean'\n  | 'select'\n  | 'rating'\n  | 'date'\n  | 'image'\n  | 'currency'\n  | 'avatar'\n  | 'badge'\n  | 'progress'\n  | 'sparkline'\n  | 'status';\n\n/** Visual variant for a `type: 'badge'` pill. */\nexport type BadgeVariant = 'gold' | 'brand' | 'neutral' | 'muted';\n\n/** State for a `type: 'status'` badge. */\nexport type StatusVariant = 'active' | 'trial' | 'churn';\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>> =\n  K extends Keys<T> ? BaseColumnSortConfiguration<T, K> : 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 the enterprise grid's XLSX export).\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   * The id of the {@link ColumnGroupConfiguration} this column belongs to.\n   *\n   * @remarks\n   * Columns sharing a `group` id render under a single spanning header cell in\n   * the group header row. Members must be **contiguous within one pin region**\n   * (the grid warns and skips the spanning cell otherwise). Has no effect unless\n   * {@link ApexGrid.columnGroups} defines a matching group.\n   */\n  group?: string;\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   * Allows cells in this column to hold spreadsheet-style formulas.\n   *\n   * @remarks\n   * An enterprise feature: the free core only carries this flag. With the\n   * enterprise formula module active and the column also\n   * {@link BaseColumnConfiguration.editable}, a cell whose edited text starts\n   * with `=` is parsed, stored as a formula, and its computed result becomes the\n   * cell value (so sorting, filtering, and aggregation keep working on the\n   * value). Has no effect without that module. Default `false`.\n   */\n  allowFormula?: boolean;\n  /**\n   * Declarative validators run before a candidate value is written to this\n   * column's cells.\n   *\n   * @remarks\n   * Each validator receives the candidate value and a {@link ValidatorContext}\n   * and returns an error message string (the cell is rejected) or `null` (it\n   * passes). All validators run and every message is collected, so a single\n   * failed commit can surface multiple errors. A failing commit keeps the\n   * inline editor open, marks the cell `aria-invalid`, and emits\n   * `cellValidationFailed`. Validation also covers bulk edits (paste / fill).\n   * Use the built-in factories ({@link required}, {@link min}, {@link max},\n   * {@link pattern}, {@link custom}) or supply your own function.\n   */\n  validators?: Validator<T, K>[];\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   * Upper bound for `type: 'rating'` and `type: 'progress'`.\n   *\n   * @remarks\n   * For `'rating'` this is the star count (default `5`); the displayed value is\n   * clamped to `[0, max]`. For `'progress'` this is the value that fills the bar\n   * to 100% (default `100`). 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   * ISO 4217 currency code for `type: 'currency'` columns (e.g. `'USD'`,\n   * `'EUR'`). Defaults to `'USD'`. Has no effect on columns with another\n   * `type`.\n   */\n  currency?: string;\n  /**\n   * BCP 47 locale for `type: 'currency'` number formatting. Defaults to the\n   * runtime locale. Has no effect on columns with another `type`.\n   */\n  locale?: string;\n  /**\n   * Visual variant for `type: 'badge'` columns. A literal applies to every\n   * cell; a callback picks per value. Defaults to `'neutral'`. Has no effect\n   * on columns with another `type`.\n   */\n  badgeVariant?: BadgeVariant | ((value: BasePropertyType<T, K>) => BadgeVariant);\n  /**\n   * State for `type: 'status'` columns. A literal applies to every cell; a\n   * callback maps a value to a state. When omitted the state is inferred from\n   * the value text. Has no effect on columns with another `type`.\n   */\n  statusVariant?: StatusVariant | ((value: BasePropertyType<T, K>) => StatusVariant);\n  /**\n   * Whether `type: 'sparkline'` columns render a trailing delta-% label.\n   * Defaults to `true`. Has no effect on columns with another `type`.\n   */\n  showDelta?: boolean;\n}\n\n/**\n * See {@link BaseColumnConfiguration} for the full documentation.\n */\nexport type ColumnConfiguration<T extends object, K extends Keys<T> = Keys<T>> =\n  K extends Keys<T> ? BaseColumnConfiguration<T, K> : never;\n\n/**\n * Context passed to a {@link ColumnGroupConfiguration.headerTemplate}.\n */\nexport interface ApexColumnGroupContext {\n  /** The group configuration being rendered. */\n  group: ColumnGroupConfiguration;\n  /** Number of (visible) member columns the group spans. */\n  span: number;\n}\n\n/**\n * Configuration for a spanning group header over a contiguous run of columns\n * (see {@link BaseColumnConfiguration.group}).\n */\nexport interface ColumnGroupConfiguration {\n  /** Unique group id, referenced by a column's {@link BaseColumnConfiguration.group}. */\n  id: string;\n  /** Text rendered in the spanning group header cell. */\n  headerText: string;\n  /**\n   * Reserved for a future collapse affordance. Inert in v1 (static spanning\n   * headers only).\n   */\n  collapsible?: boolean;\n  /** Custom template for the group header cell, overriding `headerText`. */\n  headerTemplate?: (context: ApexColumnGroupContext) => TemplateResult | unknown;\n}\n\n/**\n * Context passed to a {@link Validator} alongside the candidate value.\n */\nexport interface ValidatorContext<T extends object, K extends Keys<T> = Keys<T>> {\n  /** The column configuration the value is being validated against. */\n  column: ColumnConfiguration<T, K>;\n  /** The full data record being edited (a live reference). */\n  data: T;\n  /** The view-relative row index of the edited cell. */\n  rowIndex: number;\n}\n\n/**\n * A single declarative validation rule for a column.\n *\n * @returns An error message string when the value is invalid, or `null` when\n * it passes.\n */\nexport type Validator<T extends object, K extends Keys<T> = Keys<T>> = (\n  value: unknown,\n  context: ValidatorContext<T, K>\n) => string | null;\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>> =\n  K extends Keys<T> ? BaseApexCellContext<T, K> : 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>> =\n  K extends Keys<T> ? BaseApexEditorContext<T, K> : 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, the\n * flat-array \"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 * Undo / redo history configuration for cell-data edits.\n */\nexport interface EditingHistoryConfiguration {\n  /**\n   * Whether undo / redo tracking is enabled. When `true`, every committed cell\n   * edit (single, row-mode, and bulk paste / fill) is recorded and can be\n   * reversed via {@link ApexGrid.undo} / {@link ApexGrid.redo} or the keyboard\n   * (Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z, Ctrl+Y).\n   */\n  enabled: boolean;\n  /**\n   * Maximum number of commands retained on the undo stack. Older commands are\n   * evicted once the cap is exceeded. Defaults to `100`.\n   */\n  stackSize?: number;\n}\n\n/**\n * Grid-level row-pinning configuration.\n */\nexport interface GridRowPinningConfiguration {\n  /**\n   * Whether rows can be pinned to a sticky top / bottom band via\n   * {@link ApexGrid.pinRow}. Disabled when omitted.\n   */\n  enabled: boolean;\n}\n\n/**\n * Grid-level row-reordering configuration.\n */\nexport interface GridRowReorderingConfiguration {\n  /**\n   * Whether rows can be reordered by drag, keyboard, or {@link ApexGrid.moveRow}.\n   * A manual order, once set, is mutually exclusive with column sorting\n   * (applying a sort clears it). Disabled when omitted.\n   */\n  enabled: boolean;\n  /**\n   * When `true`, a reorder also splices {@link ApexGrid.data} in place so the\n   * source array reflects the new order. Defaults to `false`: the order lives in\n   * the grid and the app persists it via the `rowMoved` event.\n   */\n  applyToData?: boolean;\n  /**\n   * Controls how a pointer drag is initiated.\n   *\n   * - `true` (default): a dedicated drag-handle (grip) cell is rendered at the\n   *   start of every reorderable row, and a drag only begins from that handle.\n   *   The rest of the row stays free for selection / editing.\n   * - `false`: no handle is rendered and a drag begins by pressing anywhere on\n   *   the row (excluding interactive sub-parts like inputs and buttons).\n   *\n   * Either way the dragged row is shown as a floating ghost that follows the\n   * cursor, and the keyboard reorder flow (grab with Space, move with arrows) is\n   * unchanged.\n   */\n  handle?: 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   * Undo / redo history for cell-data edits. Disabled when omitted.\n   */\n  history?: EditingHistoryConfiguration;\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"]}
+{"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 GridHost<T extends object> = ReactiveControllerHost & ApexGrid<T>;\n\n/**\n * A custom action button contributed to the toolbar's trailing actions area.\n *\n * @remarks\n * The seam derived grids use to add toolbar buttons, mirroring the export-format\n * seam: the community grid contributes none (its {@link ApexGrid.toolbarActions}\n * returns `[]`), and the toolbar renders one button per entry, invoking\n * {@link ToolbarAction.run} on click.\n */\nexport interface ToolbarAction {\n  /** Stable identifier, e.g. `'create-chart'`. */\n  id: string;\n  /** Button label. */\n  label: string;\n  /** Invoked when the button is clicked. */\n  run(): void;\n}\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>> =\n  K extends Keys<T> ? BasePropertyType<T, K> : 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 *\n * The remaining types are premium presentation renderers over primitive\n * values; for sorting / filtering they behave as their underlying value type:\n * - `'currency'` formats a number via `Intl.NumberFormat` (tabular, right\n *   aligned). Configure with {@link BaseColumnConfiguration.currency} /\n *   {@link BaseColumnConfiguration.locale}. Editable via a number input.\n * - `'avatar'` renders the value's first letter in a tinted circle (hue is\n *   derived from the value, stable per row).\n * - `'badge'` renders the value as a colored pill. Pick the look with\n *   {@link BaseColumnConfiguration.badgeVariant}.\n * - `'progress'` renders a number (0..`max`, default `max` 100) as a health\n *   bar; the fill color tiers at ≥80 / ≥65 / below.\n * - `'sparkline'` renders a `number[]` as an inline trend chart with an\n *   optional delta label ({@link BaseColumnConfiguration.showDelta}).\n * - `'status'` renders a pill with a leading dot. The state is taken from\n *   {@link BaseColumnConfiguration.statusVariant} or inferred from the value.\n */\nexport type DataType =\n  | 'number'\n  | 'string'\n  | 'boolean'\n  | 'select'\n  | 'rating'\n  | 'date'\n  | 'image'\n  | 'currency'\n  | 'avatar'\n  | 'badge'\n  | 'progress'\n  | 'sparkline'\n  | 'status';\n\n/** Visual variant for a `type: 'badge'` pill. */\nexport type BadgeVariant = 'gold' | 'brand' | 'neutral' | 'muted';\n\n/** State for a `type: 'status'` badge. */\nexport type StatusVariant = 'active' | 'trial' | 'churn';\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>> =\n  K extends Keys<T> ? BaseColumnSortConfiguration<T, K> : 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 the enterprise grid's XLSX export).\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   * The id of the {@link ColumnGroupConfiguration} this column belongs to.\n   *\n   * @remarks\n   * Columns sharing a `group` id render under a single spanning header cell in\n   * the group header row. Members must be **contiguous within one pin region**\n   * (the grid warns and skips the spanning cell otherwise). Has no effect unless\n   * {@link ApexGrid.columnGroups} defines a matching group.\n   */\n  group?: string;\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   * Allows cells in this column to hold spreadsheet-style formulas.\n   *\n   * @remarks\n   * An enterprise feature: the free core only carries this flag. With the\n   * enterprise formula module active and the column also\n   * {@link BaseColumnConfiguration.editable}, a cell whose edited text starts\n   * with `=` is parsed, stored as a formula, and its computed result becomes the\n   * cell value (so sorting, filtering, and aggregation keep working on the\n   * value). Has no effect without that module. Default `false`.\n   */\n  allowFormula?: boolean;\n  /**\n   * Declarative validators run before a candidate value is written to this\n   * column's cells.\n   *\n   * @remarks\n   * Each validator receives the candidate value and a {@link ValidatorContext}\n   * and returns an error message string (the cell is rejected) or `null` (it\n   * passes). All validators run and every message is collected, so a single\n   * failed commit can surface multiple errors. A failing commit keeps the\n   * inline editor open, marks the cell `aria-invalid`, and emits\n   * `cellValidationFailed`. Validation also covers bulk edits (paste / fill).\n   * Use the built-in factories ({@link required}, {@link min}, {@link max},\n   * {@link pattern}, {@link custom}) or supply your own function.\n   */\n  validators?: Validator<T, K>[];\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   * Upper bound for `type: 'rating'` and `type: 'progress'`.\n   *\n   * @remarks\n   * For `'rating'` this is the star count (default `5`); the displayed value is\n   * clamped to `[0, max]`. For `'progress'` this is the value that fills the bar\n   * to 100% (default `100`). 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   * ISO 4217 currency code for `type: 'currency'` columns (e.g. `'USD'`,\n   * `'EUR'`). Defaults to `'USD'`. Has no effect on columns with another\n   * `type`.\n   */\n  currency?: string;\n  /**\n   * BCP 47 locale for `type: 'currency'` number formatting. Defaults to the\n   * runtime locale. Has no effect on columns with another `type`.\n   */\n  locale?: string;\n  /**\n   * Visual variant for `type: 'badge'` columns. A literal applies to every\n   * cell; a callback picks per value. Defaults to `'neutral'`. Has no effect\n   * on columns with another `type`.\n   */\n  badgeVariant?: BadgeVariant | ((value: BasePropertyType<T, K>) => BadgeVariant);\n  /**\n   * State for `type: 'status'` columns. A literal applies to every cell; a\n   * callback maps a value to a state. When omitted the state is inferred from\n   * the value text. Has no effect on columns with another `type`.\n   */\n  statusVariant?: StatusVariant | ((value: BasePropertyType<T, K>) => StatusVariant);\n  /**\n   * Whether `type: 'sparkline'` columns render a trailing delta-% label.\n   * Defaults to `true`. Has no effect on columns with another `type`.\n   */\n  showDelta?: boolean;\n}\n\n/**\n * See {@link BaseColumnConfiguration} for the full documentation.\n */\nexport type ColumnConfiguration<T extends object, K extends Keys<T> = Keys<T>> =\n  K extends Keys<T> ? BaseColumnConfiguration<T, K> : never;\n\n/**\n * Context passed to a {@link ColumnGroupConfiguration.headerTemplate}.\n */\nexport interface ApexColumnGroupContext {\n  /** The group configuration being rendered. */\n  group: ColumnGroupConfiguration;\n  /** Number of (visible) member columns the group spans. */\n  span: number;\n}\n\n/**\n * Configuration for a spanning group header over a contiguous run of columns\n * (see {@link BaseColumnConfiguration.group}).\n */\nexport interface ColumnGroupConfiguration {\n  /** Unique group id, referenced by a column's {@link BaseColumnConfiguration.group}. */\n  id: string;\n  /** Text rendered in the spanning group header cell. */\n  headerText: string;\n  /**\n   * Reserved for a future collapse affordance. Inert in v1 (static spanning\n   * headers only).\n   */\n  collapsible?: boolean;\n  /** Custom template for the group header cell, overriding `headerText`. */\n  headerTemplate?: (context: ApexColumnGroupContext) => TemplateResult | unknown;\n}\n\n/**\n * Context passed to a {@link Validator} alongside the candidate value.\n */\nexport interface ValidatorContext<T extends object, K extends Keys<T> = Keys<T>> {\n  /** The column configuration the value is being validated against. */\n  column: ColumnConfiguration<T, K>;\n  /**\n   * The full data record being edited (a live reference). In a row-mode\n   * commit it is the staged row instead: a copy of the record (same\n   * prototype) with the row's staged values applied, so cross-field rules\n   * see the row being saved. A validator that throws on the copy (one that\n   * reads private class fields, say) is run again with the live record.\n   */\n  data: T;\n  /**\n   * The view-relative row index of the edited cell (`-1` for a pinned row or\n   * a record on another page).\n   */\n  rowIndex: number;\n}\n\n/**\n * A single declarative validation rule for a column.\n *\n * @returns An error message string when the value is invalid, or `null` when\n * it passes.\n */\nexport type Validator<T extends object, K extends Keys<T> = Keys<T>> = (\n  value: unknown,\n  context: ValidatorContext<T, K>\n) => string | null;\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   * @remarks\n   * A rendered element, not the record: the grid may later re-bind it to show\n   * another record (a pinned band does when a row above it is unpinned). Read\n   * {@link data} for the record, and do not hold this element across an\n   * `await`.\n   */\n  parent: ApexGridCell<T>;\n  /**\n   * The row element containing the cell.\n   *\n   * @remarks\n   * A rendered element that may later show another record, as for\n   * {@link parent}. Read {@link data} for the record, and do not hold this\n   * element across an `await`.\n   */\n  row: ApexGridRow<T>;\n  /**\n   * The record (row data object) this cell was rendered for. Stays the same\n   * record for the life of this context object, even after the cell element\n   * is re-bound to another record.\n   */\n  readonly data: 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   * Writes to {@link data}, the record the context was built for, so a commit\n   * issued after an `await` still lands on that record.\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>> =\n  K extends Keys<T> ? BaseApexCellContext<T, K> : 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   * @remarks\n   * Unlike the display context's `commit`, this one is not bound to\n   * {@link BaseApexCellContext.data}: it commits the cell that is in edit\n   * when it is called. Do not call it after an `await` that can outlive the\n   * edit, as another cell may be in edit by then.\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>> =\n  K extends Keys<T> ? BaseApexEditorContext<T, K> : 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<T extends object = any> {\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   * Decides per row whether it can be selected. When unset every row is\n   * selectable, pinned rows included.\n   *\n   * @remarks\n   * A row this returns `false` for renders no checkbox (its cell stays, so\n   * the columns line up), carries no `aria-selected`, and is skipped by\n   * every selection path: checkbox and cell clicks, Shift and Ctrl/Cmd\n   * clicks, Space, Select all, `selectRow`, `selectedRows = ...` and\n   * `setState`. The header checkbox counts only selectable rows. When\n   * `selection` or `data` is reassigned, selected rows the predicate now\n   * rejects are dropped through the cancellable `rowSelecting` event. A\n   * selected row it comes to reject otherwise (pinned or edited in place)\n   * keeps its checkbox until it is deselected.\n   *\n   * @example\n   * ```ts\n   * // A pinned total row is a summary, not a record to pick.\n   * grid.selection = {\n   *   enabled: true,\n   *   showCheckboxColumn: true,\n   *   isRowSelectable: (row) => row !== totalRow,\n   * };\n   * ```\n   */\n  isRowSelectable?: (row: T) => 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, the\n * flat-array \"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   * Parts used inside the `detailTemplate` content to re-export, so\n   * `apex-grid::part(name)` can style them from outside the grid. The panel\n   * itself is always reachable as `detail-panel`.\n   */\n  exportParts?: ReadonlyArray<string>;\n}\n\n/**\n * Undo / redo history configuration for cell-data edits.\n */\nexport interface EditingHistoryConfiguration {\n  /**\n   * Whether undo / redo tracking is enabled. When `true`, every committed cell\n   * edit (single, row-mode, and bulk paste / fill) is recorded and can be\n   * reversed via {@link ApexGrid.undo} / {@link ApexGrid.redo} or the keyboard\n   * (Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z, Ctrl+Y).\n   */\n  enabled: boolean;\n  /**\n   * Maximum number of commands retained on the undo stack. Older commands are\n   * evicted once the cap is exceeded. Defaults to `100`.\n   */\n  stackSize?: number;\n}\n\n/**\n * Grid-level row-pinning configuration.\n */\nexport interface GridRowPinningConfiguration {\n  /**\n   * Whether rows can be pinned to a sticky top / bottom band via\n   * {@link ApexGrid.pinRow}. Disabled when omitted.\n   */\n  enabled: boolean;\n}\n\n/**\n * Grid-level row-reordering configuration.\n */\nexport interface GridRowReorderingConfiguration {\n  /**\n   * Whether rows can be reordered by drag, keyboard, or {@link ApexGrid.moveRow}.\n   * A manual order, once set, is mutually exclusive with column sorting\n   * (applying a sort clears it). Disabled when omitted.\n   */\n  enabled: boolean;\n  /**\n   * When `true`, a reorder also splices {@link ApexGrid.data} in place so the\n   * source array reflects the new order. Defaults to `false`: the order lives in\n   * the grid and the app persists it via the `rowMoved` event.\n   */\n  applyToData?: boolean;\n  /**\n   * Controls how a pointer drag is initiated.\n   *\n   * - `true` (default): a dedicated drag-handle (grip) cell is rendered at the\n   *   start of every reorderable row, and a drag only begins from that handle.\n   *   The rest of the row stays free for selection / editing.\n   * - `false`: no handle is rendered and a drag begins by pressing anywhere on\n   *   the row (excluding interactive sub-parts like inputs and buttons).\n   *\n   * Either way the dragged row is shown as a floating ghost that follows the\n   * cursor, and the keyboard reorder flow (grab with Space, move with arrows) is\n   * unchanged.\n   */\n  handle?: 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   * Undo / redo history for cell-data edits. Disabled when omitted.\n   */\n  history?: EditingHistoryConfiguration;\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';\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 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 does not slice `data`; it renders\n *  whatever `data` holds as the current page. Listen for `pageChanged`, fetch that page and\n *  assign it to `data`, and keep {@link PaginationConfiguration.totalItems} at the number of\n *  rows the server holds for the current filter so the paginator can count the pages.\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 number of rows the server holds for the current filter, so the\n   * paginator can compute the page count. Update it when a server side filter changes that\n   * number. Ignored in `'local'` mode, where the grid counts the rows itself.\n   */\n  totalItems?: number;\n  /**\n   * The paginator layout. Defaults to `'full'`.\n   *\n   * @remarks\n   * `'full'` shows the page size select, the \"start-end of total\" summary, first, previous,\n   * \"page / count\", next and last. When the grid is too narrow for all of them it drops the\n   * page size select first, then first and last, so previous and next always stay reachable.\n   *\n   * `'compact'` always uses the narrow layout: the summary, previous, \"page / count\" and next.\n   */\n  paginator?: 'compact' | 'full';\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 post-filter, post-sort row count. With pagination enabled, the rows paged\n   * through: rows pinned to the top or bottom (they show on every page) are left out.\n   * In `'remote'` mode, the {@link PaginationConfiguration.totalItems} you supplied.\n   */\n  totalItems: number;\n}\n"]}

package/internal/utils.d.ts

@@ -8,12 +8,32 @@ export declare const EXPANSION_COLUMN_WIDTH = 40;
 export declare const REORDER_HANDLE_COLUMN_WIDTH = 36;
 /** Width of the transient spreadsheet row-number gutter in CSS pixels. */
 export declare const ROW_NUMBER_COLUMN_WIDTH = 48;
-export declare function applyColumnWidths<T extends object>(columns: Array<ColumnConfiguration<T>>, options?: {
-    showSelectionColumn?: boolean;
-    showExpansionColumn?: boolean;
-    showReorderHandle?: boolean;
-    showRowNumbers?: boolean;
-}): StyleInfo;
+/** A leading chrome track the grid renders ahead of the data columns. */
+export type ChromeTrack = 'row-number' | 'reorder' | 'selection' | 'expansion';
+/** The state that decides which chrome tracks are shown (the grid's StateController). */
+interface ChromeSource {
+    selection: {
+        showCheckboxColumn: boolean;
+    };
+    expansion: {
+        showToggleColumn: boolean;
+    };
+    rowReorder: {
+        showHandleColumn: boolean;
+    };
+    host: {
+        coordinateHints?: boolean;
+    };
+}
+/**
+ * The leading chrome tracks in visual order, each with its width in CSS px:
+ * the spreadsheet row-number gutter first (matches A1), then the grip handle,
+ * the selection checkbox and the expansion chevron. The one list the grid
+ * template, the group header row's grid lines and the chrome cells' sticky
+ * offsets are all derived from, so they cannot drift apart.
+ */
+export declare function leadingChromeTracks(source?: ChromeSource): Array<[ChromeTrack, number]>;
+export declare function applyColumnWidths<T extends object>(columns: Array<ColumnConfiguration<T>>, chrome?: Array<[ChromeTrack, number]>): StyleInfo;
 /**
  * The spreadsheet column letter for a zero-based column index (`0 → A`,
  * `25 → Z`, `26 → AA`). Used for the transient A1 coordinate hints shown while a
@@ -38,6 +58,13 @@ export declare function getDisplayColumns<T extends object>(columns: Array<Colum
 export declare function getPinEdge<T extends object>(displayColumns: Array<ColumnConfiguration<T>>, index: number): 'start' | 'end' | null;
 export declare function autoGenerateColumns<T extends object>(grid: GridHost<T>): void;
 export declare function asArray<T>(value: T | T[]): T[];
+/**
+ * Whether a column holds numbers: `'number'` and the numeric presentation
+ * types `'currency'`, `'rating'` and `'progress'`, which filter as numbers.
+ * The one numeric-type rule; read it through
+ * {@link StateController.isNumericColumn} outside this package.
+ */
+export declare function isNumericColumn(column: Pick<ColumnConfiguration<any>, 'type'>): boolean;
 export declare function getFilterOperandsFor<T extends object>(column: ColumnConfiguration<T>): Readonly<import("../operations/filter/types.js").FilterOperands<number, import("../operations/filter/operands/number.js").NumberKeys>> | Readonly<import("../operations/filter/types.js").FilterOperands<string, import("../operations/filter/operands/string.js").StringKeys>> | Readonly<import("../operations/filter/types.js").FilterOperands<boolean, import("../operations/filter/operands/boolean.js").BooleanKeys>>;
 /**
  * Whether an element renders right-to-left.
@@ -53,3 +80,4 @@ export declare function getFilterOperandsFor<T extends object>(column: ColumnCon
  * inherited direction (the common case: `dir` on `<html>`) is honoured.
  */
 export declare function isRTL(element: Element): boolean;
+export {};

package/internal/utils.js

@@ -5,22 +5,25 @@ export const SELECTION_COLUMN_WIDTH = 44;
 export const EXPANSION_COLUMN_WIDTH = 40;
 export const REORDER_HANDLE_COLUMN_WIDTH = 36;
 export const ROW_NUMBER_COLUMN_WIDTH = 48;
-export function applyColumnWidths(columns, options = {}) {
-    const tracks = columns
-        .filter((each) => !each.hidden)
-        .map(({ width }) => width ?? 'minmax(136px, 1fr)');
-    if (options.showExpansionColumn) {
-        tracks.unshift(`${EXPANSION_COLUMN_WIDTH}px`);
-    }
-    if (options.showSelectionColumn) {
-        tracks.unshift(`${SELECTION_COLUMN_WIDTH}px`);
-    }
-    if (options.showReorderHandle) {
-        tracks.unshift(`${REORDER_HANDLE_COLUMN_WIDTH}px`);
-    }
-    if (options.showRowNumbers) {
-        tracks.unshift(`${ROW_NUMBER_COLUMN_WIDTH}px`);
-    }
+export function leadingChromeTracks(source) {
+    const tracks = [];
+    if (!source)
+        return tracks;
+    if (source.host.coordinateHints)
+        tracks.push(['row-number', ROW_NUMBER_COLUMN_WIDTH]);
+    if (source.rowReorder.showHandleColumn)
+        tracks.push(['reorder', REORDER_HANDLE_COLUMN_WIDTH]);
+    if (source.selection.showCheckboxColumn)
+        tracks.push(['selection', SELECTION_COLUMN_WIDTH]);
+    if (source.expansion.showToggleColumn)
+        tracks.push(['expansion', EXPANSION_COLUMN_WIDTH]);
+    return tracks;
+}
+export function applyColumnWidths(columns, chrome = []) {
+    const tracks = [
+        ...chrome.map(([, width]) => `${width}px`),
+        ...columns.filter((each) => !each.hidden).map(({ width }) => width ?? 'minmax(136px, 1fr)'),
+    ];
     return { 'grid-template-columns': tracks.join(' ') };
 }
 export function columnLetter(index) {
@@ -79,16 +82,22 @@ export function autoGenerateColumns(grid) {
 export function asArray(value) {
     return Array.isArray(value) ? value : [value];
 }
-export function getFilterOperandsFor(column) {
+export function isNumericColumn(column) {
     switch (column.type) {
-        case 'boolean':
-            return BooleanOperands;
         case 'number':
-            return NumberOperands;
+        case 'currency':
+        case 'rating':
+        case 'progress':
+            return true;
         default:
-            return StringOperands;
+            return false;
     }
 }
+export function getFilterOperandsFor(column) {
+    if (column.type === 'boolean')
+        return BooleanOperands;
+    return isNumericColumn(column) ? NumberOperands : StringOperands;
+}
 export function isRTL(element) {
     if (typeof getComputedStyle !== 'function')
         return false;

package/internal/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/internal/utils.ts"],"names":[],"mappings":"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","sourcesContent":["import type { StyleInfo } from 'lit/directives/style-map.js';\nimport { BooleanOperands } from '../operations/filter/operands/boolean.js';\nimport { NumberOperands } from '../operations/filter/operands/number.js';\nimport { StringOperands } from '../operations/filter/operands/string.js';\nimport type { ColumnConfiguration, DataType, GridHost } from './types.js';\n\n/** Width of the auto-rendered selection (checkbox) column in CSS pixels. */\nexport const SELECTION_COLUMN_WIDTH = 44;\n/** Width of the auto-rendered expansion (chevron) column in CSS pixels. */\nexport const EXPANSION_COLUMN_WIDTH = 40;\n/** Width of the auto-rendered row-reorder (grip handle) column in CSS pixels. */\nexport const REORDER_HANDLE_COLUMN_WIDTH = 36;\n/** Width of the transient spreadsheet row-number gutter in CSS pixels. */\nexport const ROW_NUMBER_COLUMN_WIDTH = 48;\n\nexport function applyColumnWidths<T extends object>(\n  columns: Array<ColumnConfiguration<T>>,\n  options: {\n    showSelectionColumn?: boolean;\n    showExpansionColumn?: boolean;\n    showReorderHandle?: boolean;\n    showRowNumbers?: boolean;\n  } = {}\n): StyleInfo {\n  const tracks = columns\n    .filter((each) => !each.hidden)\n    .map(({ width }) => width ?? 'minmax(136px, 1fr)');\n  if (options.showExpansionColumn) {\n    tracks.unshift(`${EXPANSION_COLUMN_WIDTH}px`);\n  }\n  if (options.showSelectionColumn) {\n    tracks.unshift(`${SELECTION_COLUMN_WIDTH}px`);\n  }\n  // Unshifted last so the grip handle is the leftmost leading column, ahead of\n  // any selection / expansion chrome.\n  if (options.showReorderHandle) {\n    tracks.unshift(`${REORDER_HANDLE_COLUMN_WIDTH}px`);\n  }\n  // The spreadsheet row-number gutter is the very first column (matches A1).\n  if (options.showRowNumbers) {\n    tracks.unshift(`${ROW_NUMBER_COLUMN_WIDTH}px`);\n  }\n  return { 'grid-template-columns': tracks.join(' ') };\n}\n\n/**\n * The spreadsheet column letter for a zero-based column index (`0 → A`,\n * `25 → Z`, `26 → AA`). Used for the transient A1 coordinate hints shown while a\n * formula cell is being edited.\n */\nexport function columnLetter(index: number): string {\n  let n = index;\n  let letters = '';\n  do {\n    letters = String.fromCharCode(65 + (n % 26)) + letters;\n    n = Math.floor(n / 26) - 1;\n  } while (n >= 0);\n  return letters;\n}\n\n/**\n * Returns the visual render order of the columns: start-pinned columns first,\n * then unpinned columns, then end-pinned columns. Within each group the\n * original `columns` array order is preserved.\n *\n * @remarks\n * The grid uses this order for rendering, navigation, and CSS grid track widths.\n * The user-supplied `columns` array is never mutated; this returns a new array.\n */\nexport function getDisplayColumns<T extends object>(\n  columns: Array<ColumnConfiguration<T>>\n): Array<ColumnConfiguration<T>> {\n  const start: Array<ColumnConfiguration<T>> = [];\n  const middle: Array<ColumnConfiguration<T>> = [];\n  const end: Array<ColumnConfiguration<T>> = [];\n  for (const column of columns) {\n    if (column.pinned === 'start') start.push(column);\n    else if (column.pinned === 'end') end.push(column);\n    else middle.push(column);\n  }\n  return [...start, ...middle, ...end];\n}\n\n/**\n * Returns `'start'` for the last visible start-pinned column, `'end'` for the\n * first visible end-pinned column, or `null` otherwise. The edge column gets a\n * subtle shadow / border to separate the pinned region from the scrolling one.\n */\nexport function getPinEdge<T extends object>(\n  displayColumns: Array<ColumnConfiguration<T>>,\n  index: number\n): 'start' | 'end' | null {\n  const column = displayColumns[index];\n  if (!column?.pinned) return null;\n\n  if (column.pinned === 'start') {\n    for (let i = index + 1; i < displayColumns.length; i++) {\n      const next = displayColumns[i];\n      if (next.hidden) continue;\n      return next.pinned === 'start' ? null : 'start';\n    }\n    return 'start';\n  }\n\n  for (let i = index - 1; i >= 0; i--) {\n    const prev = displayColumns[i];\n    if (prev.hidden) continue;\n    return prev.pinned === 'end' ? null : 'end';\n  }\n  return 'end';\n}\n\nexport function autoGenerateColumns<T extends object>(grid: GridHost<T>) {\n  if (grid.autoGenerate && grid.columns.length < 1) {\n    const record = grid.data[0] ?? {};\n\n    grid.columns = Object.entries(record).map(([key, value]) => {\n      const type: DataType =\n        typeof value === 'boolean' ? 'boolean' : typeof value === 'number' ? 'number' : 'string';\n      return { key, type } as ColumnConfiguration<T>;\n    });\n  }\n}\n\nexport function asArray<T>(value: T | T[]) {\n  return Array.isArray(value) ? value : [value];\n}\n\nexport function getFilterOperandsFor<T extends object>(column: ColumnConfiguration<T>) {\n  // Check for custom class in the filter config\n  switch (column.type) {\n    case 'boolean':\n      return BooleanOperands;\n    case 'number':\n      return NumberOperands;\n    default:\n      return StringOperands;\n  }\n}\n\n/**\n * Whether an element renders right-to-left.\n *\n * The grid's stylesheets are written entirely in logical properties\n * (`inline-size`, `inset-inline-start`, `border-inline-end`, …), so layout\n * mirrors under `dir=\"rtl\"` with no extra CSS. What does *not* mirror by itself\n * is code that reasons in physical pixels or physical key names: resizing from\n * a `clientX` delta, deciding a drop side from a midpoint, and mapping\n * ArrowLeft/ArrowRight onto previous/next column. Those read this.\n *\n * Resolved from the computed style rather than the `dir` attribute so an\n * inherited direction (the common case: `dir` on `<html>`) is honoured.\n */\nexport function isRTL(element: Element): boolean {\n  if (typeof getComputedStyle !== 'function') return false;\n  return getComputedStyle(element).direction === 'rtl';\n}\n"]}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/internal/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAIzE,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAE9C,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAoB1C,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACvD,MAAM,MAAM,GAAiC,EAAE,CAAC;IAChD,IAAI,CAAC,MAAM;QAAE,OAAO,MAAM,CAAC;IAC3B,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe;QAAE,MAAM,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,uBAAuB,CAAC,CAAC,CAAC;IACtF,IAAI,MAAM,CAAC,UAAU,CAAC,gBAAgB;QAAE,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,2BAA2B,CAAC,CAAC,CAAC;IAC9F,IAAI,MAAM,CAAC,SAAS,CAAC,kBAAkB;QAAE,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,sBAAsB,CAAC,CAAC,CAAC;IAC5F,IAAI,MAAM,CAAC,SAAS,CAAC,gBAAgB;QAAE,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,sBAAsB,CAAC,CAAC,CAAC;IAC1F,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,OAAsC,EACtC,SAAuC,EAAE;IAEzC,MAAM,MAAM,GAAG;QACb,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC;QAC1C,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,IAAI,oBAAoB,CAAC;KAC5F,CAAC;IACF,OAAO,EAAE,uBAAuB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACvD,CAAC;AAOD,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,CAAC,GAAG,KAAK,CAAC;IACd,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,GAAG,CAAC;QACF,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC;QACvD,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE;IACjB,OAAO,OAAO,CAAC;AACjB,CAAC;AAWD,MAAM,UAAU,iBAAiB,CAC/B,OAAsC;IAEtC,MAAM,KAAK,GAAkC,EAAE,CAAC;IAChD,MAAM,MAAM,GAAkC,EAAE,CAAC;IACjD,MAAM,GAAG,GAAkC,EAAE,CAAC;IAC9C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;aAC7C,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK;YAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;;YAC9C,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,EAAE,GAAG,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC;AACvC,CAAC;AAOD,MAAM,UAAU,UAAU,CACxB,cAA6C,EAC7C,KAAa;IAEb,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IAEjC,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QAC9B,KAAK,IAAI,CAAC,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvD,MAAM,IAAI,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;YAC/B,IAAI,IAAI,CAAC,MAAM;gBAAE,SAAS;YAC1B,OAAO,IAAI,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;QAClD,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,IAAI,CAAC,MAAM;YAAE,SAAS;QAC1B,OAAO,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;IAC9C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAmB,IAAiB;IACrE,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAElC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;YACzD,MAAM,IAAI,GACR,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;YAC3F,OAAO,EAAE,GAAG,EAAE,IAAI,EAA4B,CAAC;QACjD,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,MAAM,UAAU,OAAO,CAAI,KAAc;IACvC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC;AAQD,MAAM,UAAU,eAAe,CAAC,MAA8C;IAC5E,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,QAAQ,CAAC;QACd,KAAK,UAAU,CAAC;QAChB,KAAK,QAAQ,CAAC;QACd,KAAK,UAAU;YACb,OAAO,IAAI,CAAC;QACd;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAmB,MAA8B;IACnF,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,eAAe,CAAC;IACtD,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC;AACnE,CAAC;AAeD,MAAM,UAAU,KAAK,CAAC,OAAgB;IACpC,IAAI,OAAO,gBAAgB,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IACzD,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC,SAAS,KAAK,KAAK,CAAC;AACvD,CAAC","sourcesContent":["import type { StyleInfo } from 'lit/directives/style-map.js';\nimport { BooleanOperands } from '../operations/filter/operands/boolean.js';\nimport { NumberOperands } from '../operations/filter/operands/number.js';\nimport { StringOperands } from '../operations/filter/operands/string.js';\nimport type { ColumnConfiguration, DataType, GridHost } from './types.js';\n\n/** Width of the auto-rendered selection (checkbox) column in CSS pixels. */\nexport const SELECTION_COLUMN_WIDTH = 44;\n/** Width of the auto-rendered expansion (chevron) column in CSS pixels. */\nexport const EXPANSION_COLUMN_WIDTH = 40;\n/** Width of the auto-rendered row-reorder (grip handle) column in CSS pixels. */\nexport const REORDER_HANDLE_COLUMN_WIDTH = 36;\n/** Width of the transient spreadsheet row-number gutter in CSS pixels. */\nexport const ROW_NUMBER_COLUMN_WIDTH = 48;\n\n/** A leading chrome track the grid renders ahead of the data columns. */\nexport type ChromeTrack = 'row-number' | 'reorder' | 'selection' | 'expansion';\n\n/** The state that decides which chrome tracks are shown (the grid's StateController). */\ninterface ChromeSource {\n  selection: { showCheckboxColumn: boolean };\n  expansion: { showToggleColumn: boolean };\n  rowReorder: { showHandleColumn: boolean };\n  host: { coordinateHints?: boolean };\n}\n\n/**\n * The leading chrome tracks in visual order, each with its width in CSS px:\n * the spreadsheet row-number gutter first (matches A1), then the grip handle,\n * the selection checkbox and the expansion chevron. The one list the grid\n * template, the group header row's grid lines and the chrome cells' sticky\n * offsets are all derived from, so they cannot drift apart.\n */\nexport function leadingChromeTracks(source?: ChromeSource): Array<[ChromeTrack, number]> {\n  const tracks: Array<[ChromeTrack, number]> = [];\n  if (!source) return tracks;\n  if (source.host.coordinateHints) tracks.push(['row-number', ROW_NUMBER_COLUMN_WIDTH]);\n  if (source.rowReorder.showHandleColumn) tracks.push(['reorder', REORDER_HANDLE_COLUMN_WIDTH]);\n  if (source.selection.showCheckboxColumn) tracks.push(['selection', SELECTION_COLUMN_WIDTH]);\n  if (source.expansion.showToggleColumn) tracks.push(['expansion', EXPANSION_COLUMN_WIDTH]);\n  return tracks;\n}\n\nexport function applyColumnWidths<T extends object>(\n  columns: Array<ColumnConfiguration<T>>,\n  chrome: Array<[ChromeTrack, number]> = []\n): StyleInfo {\n  const tracks = [\n    ...chrome.map(([, width]) => `${width}px`),\n    ...columns.filter((each) => !each.hidden).map(({ width }) => width ?? 'minmax(136px, 1fr)'),\n  ];\n  return { 'grid-template-columns': tracks.join(' ') };\n}\n\n/**\n * The spreadsheet column letter for a zero-based column index (`0 → A`,\n * `25 → Z`, `26 → AA`). Used for the transient A1 coordinate hints shown while a\n * formula cell is being edited.\n */\nexport function columnLetter(index: number): string {\n  let n = index;\n  let letters = '';\n  do {\n    letters = String.fromCharCode(65 + (n % 26)) + letters;\n    n = Math.floor(n / 26) - 1;\n  } while (n >= 0);\n  return letters;\n}\n\n/**\n * Returns the visual render order of the columns: start-pinned columns first,\n * then unpinned columns, then end-pinned columns. Within each group the\n * original `columns` array order is preserved.\n *\n * @remarks\n * The grid uses this order for rendering, navigation, and CSS grid track widths.\n * The user-supplied `columns` array is never mutated; this returns a new array.\n */\nexport function getDisplayColumns<T extends object>(\n  columns: Array<ColumnConfiguration<T>>\n): Array<ColumnConfiguration<T>> {\n  const start: Array<ColumnConfiguration<T>> = [];\n  const middle: Array<ColumnConfiguration<T>> = [];\n  const end: Array<ColumnConfiguration<T>> = [];\n  for (const column of columns) {\n    if (column.pinned === 'start') start.push(column);\n    else if (column.pinned === 'end') end.push(column);\n    else middle.push(column);\n  }\n  return [...start, ...middle, ...end];\n}\n\n/**\n * Returns `'start'` for the last visible start-pinned column, `'end'` for the\n * first visible end-pinned column, or `null` otherwise. The edge column gets a\n * subtle shadow / border to separate the pinned region from the scrolling one.\n */\nexport function getPinEdge<T extends object>(\n  displayColumns: Array<ColumnConfiguration<T>>,\n  index: number\n): 'start' | 'end' | null {\n  const column = displayColumns[index];\n  if (!column?.pinned) return null;\n\n  if (column.pinned === 'start') {\n    for (let i = index + 1; i < displayColumns.length; i++) {\n      const next = displayColumns[i];\n      if (next.hidden) continue;\n      return next.pinned === 'start' ? null : 'start';\n    }\n    return 'start';\n  }\n\n  for (let i = index - 1; i >= 0; i--) {\n    const prev = displayColumns[i];\n    if (prev.hidden) continue;\n    return prev.pinned === 'end' ? null : 'end';\n  }\n  return 'end';\n}\n\nexport function autoGenerateColumns<T extends object>(grid: GridHost<T>) {\n  if (grid.autoGenerate && grid.columns.length < 1) {\n    const record = grid.data[0] ?? {};\n\n    grid.columns = Object.entries(record).map(([key, value]) => {\n      const type: DataType =\n        typeof value === 'boolean' ? 'boolean' : typeof value === 'number' ? 'number' : 'string';\n      return { key, type } as ColumnConfiguration<T>;\n    });\n  }\n}\n\nexport function asArray<T>(value: T | T[]) {\n  return Array.isArray(value) ? value : [value];\n}\n\n/**\n * Whether a column holds numbers: `'number'` and the numeric presentation\n * types `'currency'`, `'rating'` and `'progress'`, which filter as numbers.\n * The one numeric-type rule; read it through\n * {@link StateController.isNumericColumn} outside this package.\n */\nexport function isNumericColumn(column: Pick<ColumnConfiguration<any>, 'type'>): boolean {\n  switch (column.type) {\n    case 'number':\n    case 'currency':\n    case 'rating':\n    case 'progress':\n      return true;\n    default:\n      return false;\n  }\n}\n\nexport function getFilterOperandsFor<T extends object>(column: ColumnConfiguration<T>) {\n  if (column.type === 'boolean') return BooleanOperands;\n  return isNumericColumn(column) ? NumberOperands : StringOperands;\n}\n\n/**\n * Whether an element renders right-to-left.\n *\n * The grid's stylesheets are written entirely in logical properties\n * (`inline-size`, `inset-inline-start`, `border-inline-end`, …), so layout\n * mirrors under `dir=\"rtl\"` with no extra CSS. What does *not* mirror by itself\n * is code that reasons in physical pixels or physical key names: resizing from\n * a `clientX` delta, deciding a drop side from a midpoint, and mapping\n * ArrowLeft/ArrowRight onto previous/next column. Those read this.\n *\n * Resolved from the computed style rather than the `dir` attribute so an\n * inherited direction (the common case: `dir` on `<html>`) is honoured.\n */\nexport function isRTL(element: Element): boolean {\n  if (typeof getComputedStyle !== 'function') return false;\n  return getComputedStyle(element).direction === 'rtl';\n}\n"]}

package/internal/validators.js

@@ -24,6 +24,7 @@ export function pattern(regex, message = 'Invalid format') {
     return (value) => {
         if (isBlank(value))
             return null;
+        regex.lastIndex = 0;
         return regex.test(String(value)) ? null : message;
     };
 }

package/internal/validators.js.map

@@ -1 +1 @@
-{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/internal/validators.ts"],"names":[],"mappings":"AAgBA,SAAS,OAAO,CAAC,KAAc;IAC7B,OAAO,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAC7E,CAAC;AAMD,MAAM,UAAU,QAAQ,CACtB,OAAO,GAAG,wBAAwB;IAElC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC;AAMD,MAAM,UAAU,GAAG,CACjB,KAAa,EACb,OAAO,GAAG,oBAAoB,KAAK,EAAE;IAErC,OAAO,CAAC,KAAK,EAAE,EAAE;QACf,IAAI,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;IAC5D,CAAC,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,GAAG,CACjB,KAAa,EACb,OAAO,GAAG,mBAAmB,KAAK,EAAE;IAEpC,OAAO,CAAC,KAAK,EAAE,EAAE;QACf,IAAI,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;IAC5D,CAAC,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,OAAO,CACrB,KAAa,EACb,OAAO,GAAG,gBAAgB;IAE1B,OAAO,CAAC,KAAK,EAAE,EAAE;QACf,IAAI,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;IACpD,CAAC,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,MAAM,CACpB,EAAmB;IAEnB,OAAO,EAAE,CAAC;AACZ,CAAC;AAMD,MAAM,UAAU,aAAa,CAC3B,UAAyC,EACzC,KAAc,EACd,OAA+B;IAE/B,IAAI,CAAC,UAAU,EAAE,MAAM;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACzC,IAAI,OAAO;YAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import type { Keys, Validator, ValidatorContext } from './types.js';\n\n/**\n * Built-in declarative validators for {@link BaseColumnConfiguration.validators}\n * plus the {@link runValidators} runner that executes them.\n *\n * @remarks\n * Each factory returns a {@link Validator} — a function `(value, context) =>\n * string | null` that yields an error message when the value is invalid or\n * `null` when it passes. Bounds validators (`min` / `max`) and `pattern` treat\n * an empty value (`null` / `undefined` / `''`) as out of scope so they compose\n * cleanly with {@link required}; pair them with `required` when a value is\n * mandatory.\n */\n\n/** `true` for `null`, `undefined`, or an empty / whitespace-only string. */\nfunction isBlank(value: unknown): boolean {\n  return value == null || (typeof value === 'string' && value.trim() === '');\n}\n\n/**\n * Fails when the value is `null`, `undefined`, or an empty / whitespace-only\n * string.\n */\nexport function required<T extends object, K extends Keys<T> = Keys<T>>(\n  message = 'This field is required'\n): Validator<T, K> {\n  return (value) => (isBlank(value) ? message : null);\n}\n\n/**\n * Fails when the numeric value is below `limit`. Non-numeric and empty values\n * pass (compose with {@link required}).\n */\nexport function min<T extends object, K extends Keys<T> = Keys<T>>(\n  limit: number,\n  message = `Must be at least ${limit}`\n): Validator<T, K> {\n  return (value) => {\n    if (isBlank(value)) return null;\n    const num = Number(value);\n    return Number.isNaN(num) || num >= limit ? null : message;\n  };\n}\n\n/**\n * Fails when the numeric value is above `limit`. Non-numeric and empty values\n * pass (compose with {@link required}).\n */\nexport function max<T extends object, K extends Keys<T> = Keys<T>>(\n  limit: number,\n  message = `Must be at most ${limit}`\n): Validator<T, K> {\n  return (value) => {\n    if (isBlank(value)) return null;\n    const num = Number(value);\n    return Number.isNaN(num) || num <= limit ? null : message;\n  };\n}\n\n/**\n * Fails when the string form of the value does not match `regex`. Empty values\n * pass (compose with {@link required}).\n */\nexport function pattern<T extends object, K extends Keys<T> = Keys<T>>(\n  regex: RegExp,\n  message = 'Invalid format'\n): Validator<T, K> {\n  return (value) => {\n    if (isBlank(value)) return null;\n    return regex.test(String(value)) ? null : message;\n  };\n}\n\n/**\n * Wraps an arbitrary predicate as a {@link Validator}. Provided for symmetry and\n * type inference; an inline arrow function works identically.\n */\nexport function custom<T extends object, K extends Keys<T> = Keys<T>>(\n  fn: Validator<T, K>\n): Validator<T, K> {\n  return fn;\n}\n\n/**\n * Runs every validator in order and collects all error messages. Returns an\n * empty array when the value passes.\n */\nexport function runValidators<T extends object, K extends Keys<T> = Keys<T>>(\n  validators: Validator<T, K>[] | undefined,\n  value: unknown,\n  context: ValidatorContext<T, K>\n): string[] {\n  if (!validators?.length) return [];\n  const errors: string[] = [];\n  for (const validate of validators) {\n    const message = validate(value, context);\n    if (message) errors.push(message);\n  }\n  return errors;\n}\n"]}
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/internal/validators.ts"],"names":[],"mappings":"AAgBA,SAAS,OAAO,CAAC,KAAc;IAC7B,OAAO,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAC7E,CAAC;AAMD,MAAM,UAAU,QAAQ,CACtB,OAAO,GAAG,wBAAwB;IAElC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC;AAMD,MAAM,UAAU,GAAG,CACjB,KAAa,EACb,OAAO,GAAG,oBAAoB,KAAK,EAAE;IAErC,OAAO,CAAC,KAAK,EAAE,EAAE;QACf,IAAI,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;IAC5D,CAAC,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,GAAG,CACjB,KAAa,EACb,OAAO,GAAG,mBAAmB,KAAK,EAAE;IAEpC,OAAO,CAAC,KAAK,EAAE,EAAE;QACf,IAAI,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;IAC5D,CAAC,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,OAAO,CACrB,KAAa,EACb,OAAO,GAAG,gBAAgB;IAE1B,OAAO,CAAC,KAAK,EAAE,EAAE;QACf,IAAI,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAGhC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;QACpB,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;IACpD,CAAC,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,MAAM,CACpB,EAAmB;IAEnB,OAAO,EAAE,CAAC;AACZ,CAAC;AAMD,MAAM,UAAU,aAAa,CAC3B,UAAyC,EACzC,KAAc,EACd,OAA+B;IAE/B,IAAI,CAAC,UAAU,EAAE,MAAM;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACzC,IAAI,OAAO;YAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import type { Keys, Validator, ValidatorContext } from './types.js';\n\n/**\n * Built-in declarative validators for {@link BaseColumnConfiguration.validators}\n * plus the {@link runValidators} runner that executes them.\n *\n * @remarks\n * Each factory returns a {@link Validator} — a function `(value, context) =>\n * string | null` that yields an error message when the value is invalid or\n * `null` when it passes. Bounds validators (`min` / `max`) and `pattern` treat\n * an empty value (`null` / `undefined` / `''`) as out of scope so they compose\n * cleanly with {@link required}; pair them with `required` when a value is\n * mandatory.\n */\n\n/** `true` for `null`, `undefined`, or an empty / whitespace-only string. */\nfunction isBlank(value: unknown): boolean {\n  return value == null || (typeof value === 'string' && value.trim() === '');\n}\n\n/**\n * Fails when the value is `null`, `undefined`, or an empty / whitespace-only\n * string.\n */\nexport function required<T extends object, K extends Keys<T> = Keys<T>>(\n  message = 'This field is required'\n): Validator<T, K> {\n  return (value) => (isBlank(value) ? message : null);\n}\n\n/**\n * Fails when the numeric value is below `limit`. Non-numeric and empty values\n * pass (compose with {@link required}).\n */\nexport function min<T extends object, K extends Keys<T> = Keys<T>>(\n  limit: number,\n  message = `Must be at least ${limit}`\n): Validator<T, K> {\n  return (value) => {\n    if (isBlank(value)) return null;\n    const num = Number(value);\n    return Number.isNaN(num) || num >= limit ? null : message;\n  };\n}\n\n/**\n * Fails when the numeric value is above `limit`. Non-numeric and empty values\n * pass (compose with {@link required}).\n */\nexport function max<T extends object, K extends Keys<T> = Keys<T>>(\n  limit: number,\n  message = `Must be at most ${limit}`\n): Validator<T, K> {\n  return (value) => {\n    if (isBlank(value)) return null;\n    const num = Number(value);\n    return Number.isNaN(num) || num <= limit ? null : message;\n  };\n}\n\n/**\n * Fails when the string form of the value does not match `regex`. Empty values\n * pass (compose with {@link required}).\n */\nexport function pattern<T extends object, K extends Keys<T> = Keys<T>>(\n  regex: RegExp,\n  message = 'Invalid format'\n): Validator<T, K> {\n  return (value) => {\n    if (isBlank(value)) return null;\n    // A global or sticky RegExp resumes from `lastIndex`, so start every\n    // validation from the beginning of the value.\n    regex.lastIndex = 0;\n    return regex.test(String(value)) ? null : message;\n  };\n}\n\n/**\n * Wraps an arbitrary predicate as a {@link Validator}. Provided for symmetry and\n * type inference; an inline arrow function works identically.\n */\nexport function custom<T extends object, K extends Keys<T> = Keys<T>>(\n  fn: Validator<T, K>\n): Validator<T, K> {\n  return fn;\n}\n\n/**\n * Runs every validator in order and collects all error messages. Returns an\n * empty array when the value passes.\n */\nexport function runValidators<T extends object, K extends Keys<T> = Keys<T>>(\n  validators: Validator<T, K>[] | undefined,\n  value: unknown,\n  context: ValidatorContext<T, K>\n): string[] {\n  if (!validators?.length) return [];\n  const errors: string[] = [];\n  for (const validate of validators) {\n    const message = validate(value, context);\n    if (message) errors.push(message);\n  }\n  return errors;\n}\n"]}