infi-grid 1.0.0

package/lib/models/config.types.d.ts

@@ -0,0 +1,390 @@
+import type { ColumnConfig, GridDataType, GridStyleValue, GridClassValue } from './column.types';
+import type { ActionColumnConfig, GridChangeSet, GridRowValidationResult } from './crud.types';
+import type { DataRefreshConfig, GridRowKey } from './data.types';
+import type { CellSelectionConfig, SelectionConfig } from './selection.types';
+import type { TooltipConfig } from './tooltip.types';
+import type { FilterIconVisibility, FilterModel } from './filter.types';
+import type { SortDirection, SortIconVisibility, SortModelItem } from './sort.types';
+import type { GridSummaryScope, GridSummaryType } from './summary.types';
+import type { GridCellContext, GridEditContext, GridEmptyContext, GridErrorContext, GridHeaderContext, GridLoadingContext, GridSummaryCellContext, GridTemplate } from './template.types';
+/** Virtualization settings. */
+export interface VirtualizationConfig {
+    /** Render only the rows in (and near) the viewport. Default `true`. */
+    rows?: boolean;
+    /** Render only the columns in (and near) the viewport. Default `true`. */
+    columns?: boolean;
+    /** Extra rows rendered above and below the viewport. Default 6. */
+    rowBuffer?: number;
+    /** Extra columns rendered left and right of the viewport. Default 2. */
+    columnBuffer?: number;
+    /**
+     * Keep the drawn rows and columns in place while the browser scrolls, and move them in the same frame the grid
+     * draws the new ones. Browsers scroll on their own thread, ahead of the page's code: without this, fast scrolling
+     * (a flick, a scrollbar drag) shows areas that aren't drawn yet as blank rows or columns until the grid catches
+     * up. With it, the content follows the scrollbar a frame later instead, and is never blank. Default `true`.
+     */
+    syncScroll?: boolean;
+}
+/** Global sorting settings. */
+export interface SortConfig {
+    /** Global sorting flag, the default for every column's `sortable`. Default `true`. */
+    enabled?: boolean;
+    /** Allow sorting by several columns (Shift/Ctrl/Cmd + click adds a column). Default `true`. */
+    multiSort?: boolean;
+    /** Key that adds a column to the sort. `'always'` makes every click add a column. Default `'shift'`. */
+    multiSortKey?: 'shift' | 'ctrl' | 'always';
+    /** Maximum number of sorted columns. Default unlimited. */
+    maxSortColumns?: number;
+    /** Show the sort icon in headers. Default `true`. */
+    showSortIcon?: boolean;
+    /** When the sort icon is visible. Default `'hover'`. */
+    sortIconVisibility?: SortIconVisibility;
+    /** Show the 1, 2, 3… sort order next to the icon when several columns are sorted. Default `true`. */
+    showSortIndex?: boolean;
+    /** Order of states when a header is clicked. Default `['asc', 'desc', null]`. */
+    cycle?: readonly (SortDirection | null)[];
+    /** Where empty values go. Default `'last'` (for both directions, like Excel). */
+    nulls?: 'first' | 'last';
+    /** Sort applied when the grid is created. */
+    initialSort?: readonly SortModelItem[];
+}
+/** Global filtering settings. */
+export interface FilterConfig {
+    /** Global filtering flag, the default for every column's `filterable`. Default `true`. */
+    enabled?: boolean;
+    /** Show the filter icon in headers. Default `true`. */
+    showFilterIcon?: boolean;
+    /** When the filter icon is visible. Default `'always'`. */
+    filterIconVisibility?: FilterIconVisibility;
+    /** Show the Excel-style checkbox list of values. Default `true`. */
+    valueList?: boolean;
+    /** Show the condition (operator + value) section. Default `true`. */
+    conditions?: boolean;
+    /** Conditions available in the popup (1 to 5, combined with AND or OR). Default 2. */
+    maxConditions?: 1 | 2 | 3 | 4 | 5;
+    /** Case-sensitive text matching. Default `false`. */
+    caseSensitive?: boolean;
+    /** Show "Sort ascending/descending" buttons at the top of the popup. Default `true`. */
+    showSortButtons?: boolean;
+    /** Maximum distinct values listed in the checkbox list. Default 100 000. */
+    valueListLimit?: number;
+    /** Filter applied when the grid is created. */
+    initialFilter?: FilterModel;
+    /**
+     * Filter UI: the Excel-style popup of the header's filter button (`'menu'`), a filter row under the header
+     * with an input per column (`'row'`), or both. The filter row is shown while at least one displayed column is
+     * filterable (`enabled` or the column's `filterable`). Default `'menu'`.
+     */
+    mode?: 'menu' | 'row' | 'both';
+    /** Filter row: typing applies after this many ms (Enter applies at once). Default 300. */
+    rowDebounce?: number;
+    /** Filter row height in px. Default: `rowHeight`. */
+    rowHeight?: number;
+}
+/** Global editing settings, including adding and deleting rows. */
+export interface EditConfig<TRow = any> {
+    /** Global editing flag, the default for every column's `editable`. Default `false`. */
+    enabled?: boolean;
+    /** `'cell'` edits one cell at a time; `'row'` edits all editable cells of a row together. Default `'cell'`. */
+    mode?: 'cell' | 'row';
+    /** What starts editing with the mouse. Enter/F2 always work on the focused cell. Default `'dblclick'`. */
+    trigger?: 'click' | 'dblclick' | 'manual';
+    /** Save when focus leaves the editor (not for the inline add row). Default `true`. */
+    commitOnBlur?: boolean;
+    /** Start in grid edit mode (every editable cell shows its editor). Default `false`. */
+    gridEditMode?: boolean;
+    /**
+     * Let users add rows: the + button of the action column. `addRow()` and `beginAddRow()` always work.
+     * Default `false`.
+     */
+    allowAdd?: boolean;
+    /**
+     * Let users delete rows: the delete button of the action column and the Delete key (selected rows, or the
+     * focused row). `deleteRow()` and the other delete methods always work. Default `false`.
+     */
+    allowDelete?: boolean;
+    /** Where the inline add row is shown and new rows are added: first or last in the data. Default `'top'`. */
+    addPosition?: 'top' | 'bottom';
+    /** Creates the initial object of every new row (for example with a generated key). Given values are applied on top. */
+    newRow?: () => Partial<TRow>;
+    /**
+     * Validates a whole row before it is added or updated (after the column validators), for rules that
+     * involve several fields. Return a message, messages by field, or nothing when the row is valid.
+     * For updates it receives a copy of the row with the changes applied.
+     */
+    rowValidator?: (row: TRow) => GridRowValidationResult;
+    /** Ask for confirmation before deleting from the UI or `requestDeleteRows()`. Default `true`. */
+    confirmDelete?: boolean;
+    /** A column pinned at the right with edit, delete and (in the header) add buttons. Default `false`. */
+    actionColumn?: boolean | ActionColumnConfig;
+    /**
+     * Batch editing: adds, updates and deletes are kept as pending changes (shown as new, modified and deleted
+     * rows) and the data is only changed by `saveChanges()`; `cancelChanges()` discards them. Default `false`.
+     */
+    batch?: boolean;
+    /** Batch mode: steps kept for undo (Ctrl/Cmd+Z) and redo (Ctrl/Cmd+Shift+Z, Ctrl+Y). Default 100. */
+    undoLimit?: number;
+    /** Batch mode: show the loading state while a save handler runs. Default `true`. */
+    loadingWhileSaving?: boolean;
+    /** Batch mode: a bar under the rows with the number of changes, undo, redo, discard and save. Default `true`. */
+    batchToolbar?: boolean;
+    /**
+     * Batch mode: persists the changes for the toolbar's Save button and `saveChanges()` without a handler
+     * (for example an HTTP call). Return a Promise or an Observable; throw or reject to keep the changes pending.
+     */
+    saveHandler?: (changes: GridChangeSet<TRow>) => unknown;
+}
+/** Global summary-row settings. */
+export interface SummaryConfig {
+    /** Show the summary row. Default: shown when at least one column has a summary. */
+    enabled?: boolean;
+    /** `true` pins the summary row to the bottom of the grid; `false` shows it as a normal last row. Default `true`. */
+    sticky?: boolean;
+    /** Calculate over filtered rows or all rows. Default `'filtered'`. */
+    scope?: GridSummaryScope;
+    /** Show labels such as "Sum:" before values. Default `true`. */
+    showLabels?: boolean;
+}
+/** Loading-state settings. */
+export interface LoadingConfig {
+    /** Enable the loading state. Default `true`. */
+    enabled?: boolean;
+    /** Use the custom loading template when one is provided. Default `true`. */
+    useCustomTemplate?: boolean;
+    /** Block interaction with the grid (only the grid) while loading. Default `true`. */
+    blockGrid?: boolean;
+    /** Message of the built-in loader. */
+    message?: string;
+}
+/** Empty-data ("No Data Found") settings. */
+export interface EmptyStateConfig {
+    /** Enable the empty-data state. Default `true`. */
+    enabled?: boolean;
+    /** Show the custom empty template when one is provided; `false` uses the built-in one. Default `true`. */
+    useCustomTemplate?: boolean;
+    /** Also show the empty state when filters remove every row. Default `true`. */
+    showWhenFiltered?: boolean;
+    /** Message when the data array is empty. */
+    message?: string;
+    /** Message when filters removed every row. */
+    filteredMessage?: string;
+}
+/** Error-state settings. */
+export interface ErrorStateConfig {
+    /** Enable the error state (shown when the `error` input or `api.setError()` is set). Default `true`. */
+    enabled?: boolean;
+    /** Show the custom error template when one is provided; `false` uses the built-in one. Default `true`. */
+    useCustomTemplate?: boolean;
+    /** Message used when the error has no message. */
+    message?: string;
+}
+/** Click and pointer event settings. */
+export interface GridEventsConfig {
+    /**
+     * `'immediate'` (default): a click emits `cellClick`/`rowClick` at once; the second click of a double click
+     * emits nothing, so a double click is one click plus one double click.
+     * `'waitForDoubleClick'`: click events wait `doubleClickDelay` ms and are dropped when a double click follows.
+     * In that mode a click event can't cancel the built-in behaviour (it has already happened).
+     */
+    clickMode?: 'immediate' | 'waitForDoubleClick';
+    /** Wait time of `'waitForDoubleClick'`. Default 250 ms. */
+    doubleClickDelay?: number;
+    /** Suppress the browser's context menu on cells (`cellContextMenu` still fires). Default `false`. */
+    preventContextMenu?: boolean;
+}
+/** Templates set through configuration instead of `<ng-template>` directives. */
+export interface TemplateConfig<TRow = any> {
+    /** Display templates per data type (used when a column has no own template). */
+    displayByType?: Partial<Record<GridDataType, GridTemplate<GridCellContext<TRow>>>>;
+    /** Edit templates per data type (used when a column has no own edit template). */
+    editByType?: Partial<Record<GridDataType, GridTemplate<GridEditContext<TRow>>>>;
+    /** Header template for every column without its own. */
+    header?: GridTemplate<GridHeaderContext<TRow>>;
+    /** Summary cell template for every column without its own. */
+    summary?: GridTemplate<GridSummaryCellContext<TRow>>;
+    loading?: GridTemplate<GridLoadingContext<TRow>>;
+    empty?: GridTemplate<GridEmptyContext<TRow>>;
+    error?: GridTemplate<GridErrorContext<TRow>>;
+}
+/** All user-facing text, for translation. */
+export interface GridText {
+    loading: string;
+    noData: string;
+    noResults: string;
+    error: string;
+    apply: string;
+    cancel: string;
+    clear: string;
+    selectAll: string;
+    blanks: string;
+    search: string;
+    and: string;
+    or: string;
+    sortAscending: string;
+    sortDescending: string;
+    valuePlaceholder: string;
+    valueToPlaceholder: string;
+    valueListTruncated: string;
+    noMatchingValues: string;
+    booleanTrue: string;
+    booleanFalse: string;
+    /** Label of a row checkbox. */
+    selectRow: string;
+    /** Label of the header checkbox. */
+    selectAllRows: string;
+    /** Message of an empty `required` field. */
+    required: string;
+    /** Message when a new row has no primary-key value. */
+    keyRequired: string;
+    /** Message when a new row's primary key is already used. */
+    duplicateKey: string;
+    /** Delete confirmation for one row. */
+    deleteRowConfirm: string;
+    /** Delete confirmation for several rows; `{count}` is replaced by the number of rows. */
+    deleteRowsConfirm: string;
+    /** Confirm button of the delete confirmation. */
+    delete: string;
+    /** Labels of the action-column buttons. */
+    editRow: string;
+    deleteRow: string;
+    saveRow: string;
+    cancelRowEdit: string;
+    addRow: string;
+    /** Accessible name of the action column. */
+    actions: string;
+    /** Filter popup: clears this column's filter. */
+    clearFilter: string;
+    /** Filter popup: clears every column's filter. */
+    clearAllFilters: string;
+    addCondition: string;
+    removeCondition: string;
+    /** Header filter button; `{column}` is replaced by the header. */
+    filterColumn: string;
+    /** Header filter button of a filtered column. */
+    filteredColumn: string;
+    /** Filter row: placeholder of the inputs. */
+    filterPlaceholder: string;
+    /** Filter row: label of the operator button; `{operator}` is replaced by the operator. */
+    filterOperator: string;
+    /** Filter row: the "no filter" choice of boolean columns. */
+    allValues: string;
+    /** Action-column button of a deleted row (batch mode). */
+    restoreRow: string;
+    /** Batch toolbar: `{count}` is replaced by the number of changed rows. */
+    pendingChanges: string;
+    undo: string;
+    redo: string;
+    discardChanges: string;
+    saveChanges: string;
+    saving: string;
+    /** Batch toolbar after a failed save. */
+    saveFailed: string;
+    operators: Readonly<Record<string, string>>;
+    summaryLabels: Readonly<Record<GridSummaryType, string>>;
+}
+/** Grid configuration. Every section is optional; defaults are documented on each property. */
+export interface GridConfig<TRow = any> {
+    /**
+     * Field (or dot path) whose value uniquely identifies each row, or a function returning the key.
+     * Selection, data refresh and add/update/delete use it. Without it, the row object is its identity.
+     */
+    primaryKey?: string | ((row: TRow) => GridRowKey);
+    /** What a data refresh keeps (filters, sort, selection, scroll position). */
+    dataRefresh?: DataRefreshConfig;
+    /** Row selection (single or multiple, click, checkbox and keyboard). */
+    selection?: SelectionConfig<TRow>;
+    /** Cell selection: a click or the arrow keys select one cell. Independent of `selection`. */
+    cellSelection?: CellSelectionConfig;
+    /** Click and pointer event behaviour. */
+    events?: GridEventsConfig;
+    /** Tooltips of cells, headers and summary cells (by default only for text that is cut off). */
+    tooltips?: TooltipConfig;
+    /** Row height in px (fixed, used by row virtualization). Default 36. */
+    rowHeight?: number;
+    /** Header height in px. Default 40. */
+    headerHeight?: number;
+    /** Summary row height in px. Default: `rowHeight`. */
+    summaryRowHeight?: number;
+    /** Defaults applied to every column (a column's own settings win). */
+    defaultColumn?: Partial<Omit<ColumnConfig<TRow>, 'field'>>;
+    /** Extra CSS class(es) per row. */
+    rowClass?: GridClassValue | ((row: TRow, rowIndex: number) => GridClassValue);
+    /** Inline styles per row. */
+    rowStyle?: (row: TRow, rowIndex: number) => GridStyleValue | null | undefined;
+    /** Alternate row background. Default `true`. */
+    stripedRows?: boolean;
+    /** Allow drag-resizing of columns (column `resizable` overrides). Default `true`. */
+    resizableColumns?: boolean;
+    /** Arrow-key cell navigation, Enter/F2 to edit, Escape to cancel. Default `true`. */
+    keyboardNavigation?: boolean;
+    /** Locale for number/date formatting and text sorting. Default: the browser locale. */
+    locale?: string;
+    /** Theme class suffix: `'light'` (default), `'dark'`, or your own (`infi-grid-theme-<name>`). */
+    theme?: string;
+    /** Accessible label of the grid. */
+    ariaLabel?: string;
+    virtualization?: VirtualizationConfig;
+    sorting?: SortConfig;
+    filtering?: FilterConfig;
+    editing?: EditConfig<TRow>;
+    summary?: SummaryConfig;
+    loading?: LoadingConfig;
+    emptyState?: EmptyStateConfig;
+    errorState?: ErrorStateConfig;
+    templates?: TemplateConfig<TRow>;
+    /** Override any user-facing text (translation). */
+    text?: Partial<Omit<GridText, 'operators' | 'summaryLabels'>> & {
+        operators?: Readonly<Record<string, string>>;
+        summaryLabels?: Partial<Record<GridSummaryType, string>>;
+    };
+}
+type Resolved<T> = {
+    readonly [K in keyof T]-?: Exclude<T[K], undefined>;
+};
+/** Grid configuration with every default filled in. Returned by `api.getConfig()`. */
+export interface ResolvedGridConfig<TRow = any> {
+    readonly primaryKey: string | ((row: TRow) => GridRowKey) | null;
+    readonly dataRefresh: Resolved<DataRefreshConfig>;
+    readonly selection: Resolved<Omit<SelectionConfig<TRow>, 'rowSelectable'>> & {
+        readonly rowSelectable: ((row: TRow) => boolean) | null;
+    };
+    /** `activeRow` is false unless `enabled` is on. */
+    readonly cellSelection: Resolved<CellSelectionConfig>;
+    readonly events: Resolved<GridEventsConfig>;
+    readonly tooltips: Resolved<TooltipConfig>;
+    readonly rowHeight: number;
+    readonly headerHeight: number;
+    readonly summaryRowHeight: number;
+    readonly defaultColumn: Partial<Omit<ColumnConfig<TRow>, 'field'>>;
+    readonly rowClass: GridConfig<TRow>['rowClass'] | null;
+    readonly rowStyle: GridConfig<TRow>['rowStyle'] | null;
+    readonly stripedRows: boolean;
+    readonly resizableColumns: boolean;
+    readonly keyboardNavigation: boolean;
+    readonly locale: string | undefined;
+    readonly theme: string;
+    readonly ariaLabel: string;
+    readonly virtualization: Resolved<VirtualizationConfig>;
+    readonly sorting: Resolved<Omit<SortConfig, 'maxSortColumns'>> & {
+        readonly maxSortColumns: number;
+    };
+    readonly filtering: Resolved<Omit<FilterConfig, 'maxConditions'>> & {
+        readonly maxConditions: number;
+    };
+    readonly editing: Resolved<Omit<EditConfig<TRow>, 'newRow' | 'rowValidator' | 'actionColumn' | 'saveHandler'>> & {
+        readonly newRow: (() => Partial<TRow>) | null;
+        readonly rowValidator: ((row: TRow) => GridRowValidationResult) | null;
+        readonly saveHandler: ((changes: GridChangeSet<TRow>) => unknown) | null;
+        /** Null when there is no action column. */
+        readonly actionColumn: Resolved<ActionColumnConfig> | null;
+    };
+    readonly summary: Resolved<Omit<SummaryConfig, 'enabled'>> & {
+        readonly enabled: boolean | null;
+    };
+    readonly loading: Resolved<LoadingConfig>;
+    readonly emptyState: Resolved<EmptyStateConfig>;
+    readonly errorState: Resolved<ErrorStateConfig>;
+    readonly templates: TemplateConfig<TRow>;
+    readonly text: GridText;
+}
+export {};

package/lib/models/crud.types.d.ts

@@ -0,0 +1,179 @@
+import type { GridRowKey } from './data.types';
+/** Where a new row goes in the data: first, last, or at a data index. */
+export type GridAddPosition = 'top' | 'bottom' | number;
+/** Options of `addRow()`. */
+export interface GridAddRowOptions {
+    /** Default `editing.addPosition` (`'top'`). A number is an index in the data array. */
+    position?: GridAddPosition;
+    /** Scroll the new row into view. Default `true`. */
+    scroll?: boolean;
+}
+/** Options of `beginAddRow()`. */
+export interface GridBeginAddRowOptions<TRow = any> {
+    /** Where the add row is shown and the row is added. Default `editing.addPosition`. */
+    position?: 'top' | 'bottom';
+    /** Initial values of the new row (applied after `editing.newRow` and before column defaults). */
+    values?: Partial<TRow>;
+}
+/**
+ * Why an add, update or delete was refused:
+ * - `'cancelled'`: a `rowAdding` / `rowUpdating` / `rowDeleting` handler, or the delete confirmation, cancelled it;
+ * - `'invalid'`: validation failed (`required`, a column `validator` or `editing.rowValidator`), see `errors`;
+ * - `'duplicateKey'`: another row already has this primary-key value;
+ * - `'missingKey'`: the new row has no primary-key value;
+ * - `'notFound'`: no row has this key;
+ * - `'readOnly'`: a changed field can't be written (a computed column without `valueSetter`);
+ * - `'primaryKeyChange'`: the update would change the row's primary key (keys are immutable);
+ * - `'busy'`: another delete confirmation is open.
+ */
+export type GridCrudFailure = 'cancelled' | 'invalid' | 'duplicateKey' | 'missingKey' | 'notFound' | 'readOnly' | 'primaryKeyChange' | 'busy';
+/** Result of `addRow()`, `updateRow()`, `deleteRow()` and the other CRUD methods. */
+export interface GridCrudResult<TRow = any> {
+    ok: boolean;
+    /** Set when `ok` is false. */
+    reason?: GridCrudFailure;
+    /** Validation messages by field; `'$row'` holds row-level messages (`rowValidator`, function keys). */
+    errors?: Readonly<Record<string, string>>;
+    /** The added or updated row (the first deleted row for deletes). */
+    row?: TRow;
+    key?: GridRowKey;
+    /** Every deleted row. */
+    rows?: readonly TRow[];
+    keys?: readonly GridRowKey[];
+}
+/** What `editing.rowValidator` returns: a row-level message, messages by field, or nothing when valid. */
+export type GridRowValidationResult = string | Readonly<Record<string, string | null | undefined>> | null | undefined;
+/** Buttons of the action column (`editing.actionColumn`). */
+export interface ActionColumnConfig {
+    /** ✎ edits the row (row mode); ✓ and ✕ save or cancel while editing. Default `true`. */
+    edit?: boolean;
+    /** 🗑 deletes the row (with the configured confirmation; in batch mode ↶ restores a deleted row). Default `editing.allowDelete`. */
+    delete?: boolean;
+    /** + in the header opens the inline add row. Default `editing.allowAdd`. */
+    add?: boolean;
+    /** Width in px. Default: fits the buttons. */
+    width?: number;
+}
+/** `(rowAdding)`: a row is about to be added. Set `cancel` to prevent it. */
+export interface GridRowAddingEvent<TRow = any> {
+    /** The new row, with defaults applied. A handler may still change it (the key is checked again). */
+    row: TRow;
+    key: GridRowKey;
+    /** Index in the data array the row will get. */
+    position: number;
+    /** `'ui'`: the inline add row; `'api'`: `addRow()`. */
+    source: 'ui' | 'api';
+    cancel: boolean;
+}
+/** `(rowAdded)`: a row was added. */
+export interface GridRowAddedEvent<TRow = any> {
+    row: TRow;
+    key: GridRowKey;
+    /** Index in the data array. */
+    position: number;
+    /** Batch mode: the add is pending until `saveChanges()`. */
+    pending: boolean;
+    source: 'ui' | 'api';
+}
+/** `(rowUpdating)`: a row is about to change. Set `cancel` to prevent it. */
+export interface GridRowUpdatingEvent<TRow = any> {
+    /** The row, still unchanged. */
+    row: TRow;
+    key: GridRowKey;
+    /** Values before the change, by field. */
+    oldValues: Readonly<Record<string, unknown>>;
+    /** Values after the change, by field. */
+    newValues: Readonly<Record<string, unknown>>;
+    changedFields: readonly string[];
+    /** `'edit'`: an inline edit; `'api'`: `updateRow()`. */
+    source: 'edit' | 'api';
+    cancel: boolean;
+}
+/** `(rowUpdated)`: a row changed. */
+export interface GridRowUpdatedEvent<TRow = any> {
+    /** The row (the same object, now changed). */
+    row: TRow;
+    /** A copy of the row as it was before the change (objects along the changed paths are copied too). */
+    oldRow: TRow;
+    key: GridRowKey;
+    oldValues: Readonly<Record<string, unknown>>;
+    newValues: Readonly<Record<string, unknown>>;
+    changedFields: readonly string[];
+    /** Batch mode: the change is pending until `saveChanges()`. */
+    pending: boolean;
+    source: 'edit' | 'api';
+}
+/** `(rowDeleting)`: rows are about to be deleted (after the confirmation, if any). Set `cancel` to prevent it. */
+export interface GridRowDeletingEvent<TRow = any> {
+    rows: readonly TRow[];
+    keys: readonly GridRowKey[];
+    /** `'ui'`: the action column; `'keyboard'`: the Delete key; `'api'`: the API. */
+    source: 'ui' | 'api' | 'keyboard';
+    cancel: boolean;
+}
+/** `(rowDeleted)`: rows were deleted (once per operation). */
+export interface GridRowDeletedEvent<TRow = any> {
+    /** The first deleted row (the only one for single deletes). */
+    row: TRow;
+    key: GridRowKey;
+    rows: readonly TRow[];
+    keys: readonly GridRowKey[];
+    /** Batch mode: the delete is pending until `saveChanges()`. */
+    pending: boolean;
+    source: 'ui' | 'api' | 'keyboard';
+}
+/** A row with pending changes (batch mode). */
+export interface GridPendingUpdate<TRow = any> {
+    key: GridRowKey;
+    /** A copy of the row with the pending values applied (the data row is unchanged until saved). */
+    row: TRow;
+    /** The row in the data. */
+    original: TRow;
+    /** Pending values by field. */
+    changes: Readonly<Record<string, unknown>>;
+    /** Values in the data, by field. */
+    oldValues: Readonly<Record<string, unknown>>;
+}
+/** Pending changes of batch mode: what `saveChanges()` would apply. */
+export interface GridChangeSet<TRow = any> {
+    /** New rows, in the order they were added. */
+    readonly added: readonly TRow[];
+    readonly addedKeys: readonly GridRowKey[];
+    /** Changed rows (rows that are also deleted are only in `deleted`). */
+    readonly updated: readonly GridPendingUpdate<TRow>[];
+    readonly updatedKeys: readonly GridRowKey[];
+    /** Rows to delete (as they are in the data). */
+    readonly deleted: readonly TRow[];
+    readonly deletedKeys: readonly GridRowKey[];
+    /** Number of rows with a change. */
+    readonly count: number;
+}
+/** Result of `saveChanges()`. The promise never rejects. */
+export interface GridSaveResult<TRow = any> {
+    ok: boolean;
+    /**
+     * `'invalid'`: an open edit couldn't be committed; `'failed'`: the save handler threw or rejected (the
+     * changes stay pending); `'busy'`: a save is already running.
+     */
+    reason?: 'invalid' | 'failed' | 'busy';
+    /** What the save handler threw or rejected with. */
+    error?: unknown;
+    changes: GridChangeSet<TRow>;
+}
+/** `(changesSaveFailed)`: the save handler threw or rejected; nothing was applied. */
+export interface GridSaveFailedEvent<TRow = any> {
+    error: unknown;
+    changes: GridChangeSet<TRow>;
+}
+/** `(pendingChange)`: the pending changes of batch mode changed (for Save / Undo buttons of your own). */
+export interface GridPendingChangeEvent {
+    /** What changed them. */
+    action: 'add' | 'update' | 'delete' | 'restore' | 'undo' | 'redo' | 'save' | 'cancel' | 'refresh';
+    hasChanges: boolean;
+    /** Pending rows by kind. */
+    added: number;
+    updated: number;
+    deleted: number;
+    canUndo: boolean;
+    canRedo: boolean;
+}

package/lib/models/data.types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Value that identifies a row: the result of the `primaryKey` field (or function).
+ * Keys are compared with `===` (SameValueZero); use a string for composite keys.
+ * Without a configured `primaryKey`, the row object itself is the key, so every key-based API
+ * also accepts row objects.
+ */
+export type GridRowKey = string | number | bigint | object;
+/** How a data refresh treats the current view state. */
+export interface DataRefreshConfig {
+    /** Keep or clear the filters when the data is replaced or refreshed. Default `'keep'`. */
+    filter?: 'keep' | 'reset';
+    /** Keep or clear the sort. Default `'keep'`. */
+    sort?: 'keep' | 'reset';
+    /** Keep the selection (rows that still exist stay selected) or clear it. Default `'keep'`. */
+    selection?: 'keep' | 'reset';
+    /** Keep the scroll position or go back to the first row. Default `'keep'`. */
+    scroll?: 'keep' | 'top';
+}
+/** Per-call override of `config.dataRefresh`. */
+export type GridRefreshOptions = DataRefreshConfig;
+/** What a data refresh did. Returned by `setData()` / `refreshData()` and emitted by `(dataRefresh)`. */
+export interface GridRefreshResult {
+    /** Rows in the data. */
+    rowCount: number;
+    /** Rows after filtering. */
+    displayedRowCount: number;
+    /** Selected keys removed because their rows no longer exist (or are now filtered out). */
+    removedSelectionKeys: readonly GridRowKey[];
+    filterReset: boolean;
+    sortReset: boolean;
+}
+/** Why the data was refreshed. */
+export type GridDataRefreshReason = 'input' | 'setData' | 'refreshData' | 'crud' | 'save';
+export interface GridDataRefreshEvent extends GridRefreshResult {
+    reason: GridDataRefreshReason;
+}
+export interface GridLoadingChangeEvent {
+    loading: boolean;
+    /** `'input'` for the `[loading]` binding, `'api'` for `setLoading()`. */
+    source: 'input' | 'api';
+}