infi-grid 1.0.0

package/README.md

@@ -0,0 +1,654 @@
+# InfiGrid
+
+A fast, configurable data grid for **Angular 19+**.
+
+- **Large data without lag.** Row and column virtualization with reused DOM, and no blank rows or columns even when scrolling fast. Tested at 50,000 to 1,000,000 rows and up to 200 columns at a steady 60 fps.
+- **Excel-style filtering.** Typed conditions (text, number, date, boolean; up to 5, AND/OR) plus a searchable checkbox list of values, with Apply / Cancel / Clear filter / Clear all. Optional filter row under the header.
+- **Sorting.** Ascending/descending, multi-column sort with order numbers, and configurable sort icons.
+- **Row selection.** Single or multiple, by click, checkbox column (with select-all) or keyboard; identity by primary key, so it survives sorting, filtering, refreshes and virtualization.
+- **Cell selection.** One selected cell by click or arrow keys, independent of row selection, with an optional active row.
+- **Add, update and delete.** API and UI (action column, inline add row, Delete key), required fields, unique keys, row validation, delete confirmation, and cancelable before-events. **Batch mode** keeps changes pending (marked rows, undo/redo) until you save them.
+- **Editing.** Display and edit templates, and built-in text, number, dropdown, checkbox and date editors. Also custom editor components, validation, and cell, row or whole-grid edit modes.
+- **Tooltips** for cut-off cell and header text (or always, or custom templates), with delays and placement.
+- **Summaries.** Sum, Average, Count, Min, Max, or custom functions and formulas. The summary row can be pinned (sticky) or a normal last row.
+- **Templates.** Cell, header, edit, summary, loading, empty-data and error templates. Each can be an `ng-template` or an Angular component.
+- **Grid API and events** for everything, plus public TypeScript types.
+- **Themeable** with CSS variables, including a dark theme. No console output, and no dependencies beyond Angular.
+
+> The project source also includes a full developer guide (`docs/GUIDE.md`): architecture, data flow, every option and performance details.
+
+---
+
+## Contents
+
+1. [Install](#install)
+2. [Quick start](#quick-start)
+3. [Columns](#columns)
+4. [Configuration and feature flags](#configuration-and-feature-flags)
+5. [Templates](#templates)
+6. [Editing](#editing)
+7. [Row identity and selection](#row-identity-and-selection)
+8. [Cell selection](#cell-selection)
+9. [Add, update and delete](#add-update-and-delete)
+10. [Batch editing](#batch-editing)
+11. [Filtering](#filtering)
+12. [Sorting](#sorting)
+13. [Summaries](#summaries)
+14. [Tooltips](#tooltips)
+15. [Loading, empty and error states](#loading-empty-and-error-states)
+16. [Data refresh](#data-refresh)
+17. [Grid API](#grid-api)
+18. [Events](#events)
+19. [Styling and theming](#styling-and-theming)
+20. [Keyboard](#keyboard)
+21. [Performance tips](#performance-tips)
+22. [Notes and limitations](#notes-and-limitations)
+23. [Coming from angpackage-grid](#coming-from-angpackage-grid)
+24. [Compatibility](#compatibility)
+
+---
+
+## Install
+
+```bash
+npm install infi-grid
+
+# or, without a registry, from the packed file
+npm install ./infi-grid-1.0.0.tgz
+```
+
+Peer dependencies: `@angular/core` and `@angular/common` 19 or newer. There's nothing else to install, and no global stylesheet to add (styles ship with the component).
+
+## Quick start
+
+```ts
+import { Component, signal } from '@angular/core';
+import { INFI_GRID, type ColumnConfig, type GridApi, type GridConfig } from 'infi-grid';
+
+interface Order {
+  id: number;
+  customer: string;
+  amount: number;
+  orderDate: Date;
+  shipped: boolean;
+}
+
+@Component({
+  selector: 'app-orders',
+  imports: [INFI_GRID],
+  template: `
+    <infi-grid
+      style="height: 600px"
+      [data]="orders()"
+      [columns]="columns"
+      [config]="config"
+      (gridReady)="api = $event.api"
+      (cellValueChange)="save($event.row)"
+    />
+  `,
+})
+export class OrdersComponent {
+  readonly orders = signal<Order[]>([]);
+  api?: GridApi<Order>;
+
+  readonly columns: ColumnConfig<Order>[] = [
+    { field: 'id', header: 'ID', type: 'number', width: 90 },
+    { field: 'customer', header: 'Customer', editable: true },
+    { field: 'amount', header: 'Amount', type: 'number', numberFormat: { style: 'currency', currency: 'USD' }, summary: 'sum' },
+    { field: 'orderDate', header: 'Order date', type: 'date', editable: true },
+    { field: 'shipped', header: 'Shipped', type: 'boolean', editable: true },
+  ];
+
+  readonly config: GridConfig<Order> = {
+    sorting: { initialSort: [{ field: 'orderDate', direction: 'desc' }] },
+    summary: { sticky: true },
+  };
+
+  save(order: Order) {
+    /* persist the change */
+  }
+}
+```
+
+**The grid needs a height.** Set it with CSS (`infi-grid { height: 100% }`, `style="height: 600px"`, flex, and so on); the default is 400px.
+
+For NgModule-based apps, import `InfiGridModule` instead of `INFI_GRID`.
+
+## Columns
+
+Columns are an array of `ColumnConfig`. Every behaviour flag on a column overrides the matching global flag.
+
+| Property | Purpose |
+|---|---|
+| `field` | Property name or dot path (`'customer.name'`). Unique. |
+| `header` | Header text (defaults to the field). |
+| `type` | `'text'` (default), `'number'`, `'date'`, `'boolean'`. Drives formatting, sorting, filtering, editors and summaries. |
+| `width`, `minWidth`, `maxWidth` | Pixels. Default width 150, min 48. Columns can be drag-resized within min/max. |
+| `sortable`, `filterable`, `editable` | Column-level flags. `editable` can be a function `(row) => boolean`. |
+| `resizable`, `hidden`, `align` | Layout. Numbers are right-aligned by default. |
+| `displayTemplate`, `editTemplate`, `headerTemplate`, `summaryTemplate` | `TemplateRef` or component class. |
+| `templateKey` | Reuse key of the column's template cells: a cell scrolled out of view is reused for a column with the same key, so it only updates. Use the column's type when one template renders different content (an `@switch`). |
+| `cellClass`, `cellStyle` | Static value or `(ctx) => …` for per-cell styling. |
+| `headerClass`, `headerStyle` | Header styling. |
+| `summary` | `'sum'`, `'avg'`, `'count'`, `'min'`, `'max'`, or a `ColumnSummaryConfig` with a custom `fn`. |
+| `sort` | `{ comparator, showIcon, iconVisibility, cycle }` |
+| `filter` | `{ operators, defaultOperator, customOperators, valueList, conditions, maxConditions, caseSensitive, predicate, showIcon, iconVisibility }` |
+| `valueGetter`, `valueSetter` | Computed (formula) columns, and writing edits back. |
+| `valueFormatter`, `numberFormat`, `dateFormat`, `booleanLabels` | Display formatting. |
+| `editor`, `editorOptions`, `validator` | Editing (see below). |
+| `required`, `defaultValue`, `editableOnAdd` | Adding rows (see [Add, update and delete](#add-update-and-delete)). |
+| `tooltip`, `tooltipTemplate`, `description`, `headerTooltip`, `headerTooltipTemplate` | Tooltips (see [Tooltips](#tooltips)). |
+| `meta` | Anything you want to read in your own templates. |
+
+Use `defaultColumn` in the config to set defaults for all columns:
+
+```ts
+config = { defaultColumn: { width: 120, resizable: true } };
+```
+
+## Configuration and feature flags
+
+Every section is optional. Defaults are shown.
+
+```ts
+const config: GridConfig<Order> = {
+  primaryKey: 'id',              // field, dot path or (row) => key; identifies rows (selection, CRUD, refresh)
+  dataRefresh: { filter: 'keep', sort: 'keep', selection: 'keep', scroll: 'keep' }, // what a refresh keeps ('reset' / 'top')
+  selection: {
+    mode: 'none',                // 'single' | 'multiple'
+    checkbox: undefined,         // default: true in 'multiple' mode
+    checkboxWidth: 40, headerCheckbox: true,
+    selectOnClick: true,         // ignored while cellSelection.enabled is on
+    selectAllScope: 'filtered',  // 'all'
+    onFilter: 'deselectHidden',  // 'clear' | 'keep'
+    scrollToSelection: false, keyboard: true, rowSelectable: undefined,
+  },
+  cellSelection: { enabled: false, activeRow: false }, // one selected cell; never changes the row selection
+  events: { clickMode: 'immediate' /* 'waitForDoubleClick' */, doubleClickDelay: 250, preventContextMenu: false },
+  tooltips: { enabled: true, cells: 'truncated', headers: 'truncated', showDelay: 500, hideDelay: 100, placement: 'top', disabledTypes: [] },
+  rowHeight: 36,                 // fixed row height (px)
+  headerHeight: 40,
+  summaryRowHeight: 36,
+  stripedRows: true,
+  resizableColumns: true,
+  keyboardNavigation: true,
+  locale: undefined,             // browser locale for numbers, dates and text sorting
+  theme: 'light',                // 'dark' or your own name
+  ariaLabel: 'Data grid',
+  rowClass: (row, i) => (row.overdue ? 'is-overdue' : null),
+  rowStyle: undefined,
+
+  virtualization: { rows: true, columns: true, rowBuffer: 6, columnBuffer: 2, syncScroll: true },
+  sorting: {
+    enabled: true, multiSort: true, multiSortKey: 'shift', // 'shift' | 'ctrl' | 'always'
+    showSortIcon: true, sortIconVisibility: 'hover',        // 'always' | 'sorted' | 'hover'
+    showSortIndex: true, cycle: ['asc', 'desc', null], nulls: 'last', initialSort: [],
+  },
+  filtering: {
+    enabled: true, showFilterIcon: true, filterIconVisibility: 'always', // 'always' | 'hover'
+    valueList: true, conditions: true, maxConditions: 2 /* 1–5 */, caseSensitive: false,
+    showSortButtons: true, valueListLimit: 100_000, initialFilter: {},
+    mode: 'menu',                // 'row' | 'both': a filter row under the header
+    rowDebounce: 300, rowHeight: undefined /* rowHeight */,
+  },
+  editing: {
+    enabled: false, mode: 'cell', trigger: 'dblclick', commitOnBlur: true, gridEditMode: false,
+    allowAdd: false, allowDelete: false, addPosition: 'top', newRow: undefined, rowValidator: undefined,
+    confirmDelete: true, actionColumn: false,  // true | { edit, delete, add, width }
+    batch: false, undoLimit: 100, loadingWhileSaving: true, batchToolbar: true, saveHandler: undefined,
+  },
+  summary: { enabled: undefined /* auto */, sticky: true, scope: 'filtered', showLabels: true },
+  loading: { enabled: true, useCustomTemplate: true, blockGrid: true, message: 'Loading…' },
+  emptyState: { enabled: true, useCustomTemplate: true, showWhenFiltered: true, message: 'No data found' },
+  errorState: { enabled: true, useCustomTemplate: true, message: 'Something went wrong while loading the data.' },
+  templates: { displayByType: {}, editByType: {}, header: undefined, summary: undefined, loading: undefined, empty: undefined, error: undefined },
+  text: { apply: 'Apply' /* …every label, for translation */ },
+};
+```
+
+## Templates
+
+### Declarative templates (`ng-template` inside `<infi-grid>`)
+
+```html
+<infi-grid [data]="rows" [columns]="columns">
+  <!-- one column -->
+  <ng-template infiGridCell="status" let-value let-row="row">
+    <span class="badge" [class.late]="row.late">{{ value }}</span>
+  </ng-template>
+
+  <!-- every column of a data type -->
+  <ng-template infiGridCell type="boolean" let-value>{{ value ? '✓' : '—' }}</ng-template>
+
+  <!-- edit mode -->
+  <ng-template infiGridEdit="notes" let-value let-setValue="setValue" let-commit="commit" let-cancel="cancel">
+    <input #box [value]="value ?? ''" (input)="setValue(box.value)" (keydown.enter)="commit()" (keydown.escape)="cancel()" />
+  </ng-template>
+
+  <ng-template infiGridHeader="amount" let-column>💰 {{ column.header }}</ng-template>
+  <ng-template infiGridSummary="amount" let-formatted="formattedValue">Σ {{ formatted }}</ng-template>
+  <ng-template infiGridLoading>Fetching…</ng-template>
+  <ng-template infiGridEmpty let-reason let-clear="clearFilters">
+    @if (reason === 'noData') { No orders yet } @else { No match. <button (click)="clear()">Clear filters</button> }
+  </ng-template>
+  <ng-template infiGridError let-message="message">Could not load: {{ message }}</ng-template>
+</infi-grid>
+```
+
+### Templates in configuration (`TemplateRef` or component)
+
+```ts
+columns = [
+  { field: 'progress', type: 'number', displayTemplate: this.progressTpl },   // @ViewChild TemplateRef
+  { field: 'status', displayTemplate: StatusBadgeComponent },                  // component class
+  { field: 'rating', type: 'number', editTemplate: RatingEditorComponent },
+];
+config = { templates: { displayByType: { date: MyDateCell }, error: ErrorPanelComponent } };
+```
+
+One template for many kinds of columns: set `templateKey` to the kind, so scrolling sideways reuses each cell for a column of the same kind instead of re-rendering its content (no blank columns while scrolling fast, even with rich cells):
+
+```html
+<ng-template infiGridCell let-value let-column="column">
+  @switch (column.config.meta.kind) {
+    @case ('switch') { <app-switch-cell [value]="value" /> }
+    @case ('color') { <app-color-cell [value]="value" /> }
+    @default { {{ value }} }
+  }
+</ng-template>
+```
+
+```ts
+columns = fields.map((f) => ({ field: f.name, meta: { kind: f.kind }, templateKey: f.kind }));
+```
+
+A component used as a template receives its context through an input named `context`. Extend `GridTemplateComponent` to get it declared:
+
+```ts
+@Component({ template: `<b>{{ context().value }}</b>`, changeDetection: ChangeDetectionStrategy.OnPush })
+export class StatusBadgeComponent extends GridTemplateComponent<GridCellContext<Order, string>> {}
+```
+
+### Which template is used
+
+The most specific wins: column property → field directive → type template (`config.templates.*ByType`, then `type` directive) → `defaultColumn` → directive without field/type → built-in.
+
+### Template context
+
+| Template | Context (`let-x="name"`) |
+|---|---|
+| Cell (display) | `$implicit`/`value`, `formattedValue`, `row`, `rowIndex`, `dataIndex`, `column`, `columnIndex`, `field`, `editing`, `rowEditing`, `api` |
+| Edit | everything above plus `originalValue`, `error`, `editorOptions`, `autoFocus`, `setValue(v)`, `commit()`, `cancel()` |
+| Header | `$implicit`/`column`, `columnIndex`, `header`, `sortDirection`, `sortIndex`, `filterActive`, `api`, `toggleSort(multi?)`, `openFilter()` |
+| Summary | `$implicit`/`value`, `formattedValue`, `label`, `result`, `column`, `field`, `api` |
+| Loading | `$implicit`/`loading`, `message`, `api` |
+| Empty | `$implicit`/`reason` (`'noData'` or `'noResults'`), `message`, `api`, `clearFilters()` |
+| Error | `$implicit`/`error`, `message`, `api`, `dismiss()` |
+
+## Editing
+
+- Turn editing on for every column (`editing.enabled: true`) or per column (`editable: true`, or a function of the row).
+- Start editing with a double-click (or `trigger: 'click'`), Enter or F2 on the focused cell, or `api.enterEditMode(rowIndex, field?)`.
+- Enter saves, Escape cancels, and Tab moves to the next editable cell. Clicking away saves (`commitOnBlur`).
+- **Modes:**
+  - `mode: 'cell'` (default): one cell at a time.
+  - `mode: 'row'`: every editable cell of the row, saved together.
+  - **Grid edit mode:** `api.setGridEditMode(true)` or `editing.gridEditMode`. Every editable cell shows its editor, and each change saves immediately. This is the toggle between display mode and edit mode for the whole grid.
+- **Built-in editors:** `text`, `number`, `select` (when `editorOptions.options` is set), `checkbox`, `date`, chosen from the column type or `editor`.
+
+  ```ts
+  { field: 'status', editorOptions: { options: [{ label: 'Open', value: 'open' }, { label: 'Closed', value: 'closed' }] } }
+  { field: 'qty', type: 'number', editorOptions: { min: 1, step: 1 }, validator: (v) => (v >= 1 ? null : 'At least 1') }
+  ```
+
+- A failing `validator` keeps the cell in edit mode and shows the message.
+- `(cellValueChange)` fires for every saved value; `(editStart)`, `(editCommit)` and `(editCancel)` fire for the session.
+- Saving an edit re-renders only that row and recalculates only the affected summaries. Rows don't jump: sorting and filtering are not re-applied until `api.refresh()`.
+- Saving an edit goes through the same update as `api.updateRow()`: `required`, validators and `editing.rowValidator` run, `(rowUpdating)` can cancel it (the editor stays open), and `(rowUpdated)` reports it.
+
+## Row identity and selection
+
+```ts
+config = {
+  primaryKey: 'id',                                   // or 'customer.id', or (row) => `${row.region}-${row.no}`
+  selection: { mode: 'multiple' },                    // checkbox column on by default in 'multiple' mode
+};
+```
+
+- **Identity:** with a `primaryKey`, rows are identified by key, not by position or object. Selection, edits and refreshes survive sorting, filtering, virtualization and new row objects with the same keys. Duplicate or missing keys are reported once through `(gridError)` (source `'data'`).
+- **Selecting:** the mode decides what a click (on the checkbox, or on a cell or row with `selectOnClick`) and Space do.
+  - `'multiple'`: toggles that row and keeps the other selected rows. Shift+click selects the rows from the last clicked row to this one, in the current view order, keeping the rows selected before. Ctrl/Cmd+click is the same as a click.
+  - `'single'`: selects that row instead of the selected one; on the selected row, deselects it.
+  - Checkboxes always show the selection, right after any change. The header checkbox selects all rows in `selectAllScope` (the filtered rows by default) and shows an indeterminate state.
+  - Keys: Space toggles the focused row, Shift+↑/↓ extends the range, Ctrl/Cmd+A selects all.
+  - `rowSelectable: (row) => boolean` disables rows.
+  - With `selectOnClick: false`, or while [cell selection](#cell-selection) is on, only the checkboxes, the keyboard and the API select rows.
+- **Filters:** by default, rows hidden by a new filter are deselected (`onFilter: 'deselectHidden'`). Removing the filter doesn't select them again.
+- **API** (on `api` and on the component):
+  - `selectRowByKey(key, { scroll })`, `deselectRowByKey`, `selectRowsByKeys`, `deselectRowsByKeys`, `toggleRowSelection`
+  - `selectAll({ scope })`, `deselectAll`, `clearSelection`
+  - `getSelectedRows`, `getSelectedKeys`, `isRowSelected`
+  - `getRowKey`, `getRowByKey`, `getRowIndexByKey`, `scrollToRowByKey`
+- **Events:**
+  - `(selectionChange)`: once per operation, with `source`, `action`, `added`/`removed` (and their keys), `oldRow`/`newRow` in single mode, and the previous and current selection.
+  - `(rowSelected)`, `(rowDeselected)`, `(selectionCleared)`.
+  - `(selectionClick)`: cancelable, before a click or key changes the selection.
+
+```ts
+@ViewChild(InfiGridComponent) grid!: InfiGridComponent<Order>;
+selectFirstOverdue() {
+  const order = this.orders().find((o) => o.overdue);
+  if (order) this.grid.selectRowByKey(order.id, { scroll: true });
+}
+```
+
+## Cell selection
+
+```ts
+config = {
+  primaryKey: 'id',
+  selection: { mode: 'none' },                         // or rows too, with their checkboxes
+  cellSelection: { enabled: true, activeRow: true },
+};
+```
+
+- **Selecting:** a click on a cell selects that cell, and the arrow keys, Home/End, Page Up/Down and Ctrl+Home/End move it (the first key selects the top-left visible cell). The selected cell has the focus outline, the class `is-selected` and `aria-selected="true"`.
+- **Independent of row selection:** a cell click never selects or deselects rows and never emits `(selectionChange)`; `selection.selectOnClick` is ignored. Rows are still selected with the checkbox column, Space, Shift+↑/↓, Ctrl/Cmd+A and the API. No `selection` option affects cell selection.
+- **Identity:** the selected cell is kept by row key and field, so it follows its row through sorting, filtering, scrolling and refreshes. A filter that hides the row hides the cell until the filter is removed. The cell is cleared when its row leaves the data (refresh, delete, a saved batch delete) or its column is removed.
+- **Active row:** `activeRow: true` marks the selected cell's row with `.infi-grid__row--active` (`--infi-grid-active-row-bg`). It is visual only: it isn't in `getSelectedKeys()`, emits no `(selectionChange)` and has no checkbox. A selected row keeps the selected color.
+- **Events:**
+  - `(cellClick)`, `(cellDoubleClick)`, `(rowClick)` fire as before. Their `cancel` stops the cell selection (and starting an edit).
+  - `(cellSelectionChange)`: `source` (`'click'`, `'keyboard'`, `'api'`, `'dataRefresh'`, `'delete'`, `'columns'`), `row`, `key`, `rowIndex`, `dataIndex`, `field`, `column`, `value`, `formattedValue`, `previous` (`{ key, field }`) and `event`. When the cell is cleared, `row`, `key`, `field` and `column` are null.
+- **API:** `getSelectedCell()` (`{ row, key, field, rowIndex }` or null), `selectCell(key, field, { scroll })` (false when the row or column isn't displayed, or the cell is already selected), `clearCellSelection()`.
+
+```ts
+onCellSelectionChange(e: GridCellSelectionChangeEvent<Order>) {
+  this.details.set(e.row);                             // null when the cell was cleared
+}
+```
+
+## Add, update and delete
+
+```ts
+config = {
+  primaryKey: 'id',
+  editing: {
+    enabled: true,
+    allowAdd: true, allowDelete: true,      // the UI: + and 🗑 buttons, the Delete key
+    actionColumn: true,                     // ✎ 🗑 per row (✓ ✕ while editing), + in the header
+    newRow: () => ({ id: nextId++ }),       // initial object of new rows
+    rowValidator: (o) => (o.shipDate < o.orderDate ? { shipDate: 'Before the order date' } : null),
+  },
+};
+columns = [
+  { field: 'customer', required: true },
+  { field: 'status', defaultValue: 'open' },
+  { field: 'quantity', type: 'number', defaultValue: 1, validator: (q) => (q > 0 ? null : 'At least 1') },
+];
+```
+
+```html
+<infi-grid [(data)]="orders" [columns]="columns" [config]="config" (rowAdded)="…" (rowUpdated)="…" (rowDeleted)="…" />
+```
+
+- **API:**
+  - `addRow(row, { position: 'top' | 'bottom' | index, scroll })` and `beginAddRow({ position, values })` (the inline add row)
+  - `updateRow(key, { field: value, 'nested.path': value })`
+  - `deleteRow(key)` and `deleteRows(keys)` (no confirmation); `requestDeleteRows(keys)` and `deleteSelectedRows()` (with the confirmation)
+  - Each returns `{ ok, reason, errors, row, key }`. Reasons: `'cancelled'`, `'invalid'`, `'duplicateKey'`, `'missingKey'`, `'notFound'`, `'readOnly'`, `'primaryKeyChange'`, `'busy'`.
+- **New rows:**
+  - The object you pass becomes the row. Column `defaultValue`s fill the missing fields.
+  - Then `required`, the column validators, `rowValidator` and the key (present and unique) are checked.
+  - A new row stays visible even if the active filter wouldn't show it, until the filter changes.
+- **Updates** write into the row object. Its identity, selection and scroll position don't change, and keys can't change.
+- **Deletes** remove the rows from the data, the selection and the summaries. An edit of a deleted row is cancelled.
+- **Your array is never changed:** adds and deletes emit a new array through `(dataChange)`, so `[(data)]="orders"` keeps your signal in sync.
+- **The inline add row** shows under the header (or above the summary row) with editors. Enter or ✓ adds it, Escape or ✕ discards it. Columns get an editor by `editableOnAdd`, which defaults to `editable`; the key column only gets one when `newRow` gives no key.
+- **Delete confirmation:**
+  - A built-in dialog: "Delete 3 rows?". Escape cancels; Tab stays in the dialog.
+  - Or your own template: `<ng-template infiGridDeleteConfirm let-count="count" let-confirm="confirm" let-cancel="cancel">`.
+  - `confirmDelete: false` turns it off.
+- **Events:** `(rowAdding)`, `(rowUpdating)` and `(rowDeleting)` are cancelable (`event.cancel = true`). `(rowAdded)`, `(rowUpdated)` (with `oldRow`, `oldValues`, `newValues` and `changedFields`) and `(rowDeleted)` follow.
+
+## Batch editing
+
+```ts
+config = {
+  primaryKey: 'id',
+  editing: {
+    enabled: true, batch: true, allowAdd: true, allowDelete: true, actionColumn: true,
+    saveHandler: (changes) => this.http.post('/api/orders/batch', changes),   // Promise or Observable
+  },
+};
+```
+
+- **Changes stay pending.** Adds, updates and deletes are kept as pending changes, and your data isn't touched until saved.
+  - New rows are shown first (or last), modified rows and cells are marked, and deleted rows stay visible, struck through, with a restore button.
+  - Sorting, filtering and summaries use the pending values.
+- **The toolbar** under the rows shows "3 unsaved changes" with Undo, Redo, Discard and Save. Turn it off with `batchToolbar: false`.
+  - Undo and redo also work with Ctrl/Cmd+Z and Ctrl/Cmd+Shift+Z (or Ctrl+Y).
+- **`saveChanges(handler?)`:**
+  1. Commits an open edit.
+  2. Calls the handler (`editing.saveHandler` by default), showing the loading state meanwhile.
+  3. Applies everything to the data in one step: `(changesSaved)`, then `(dataChange)`.
+  - If the handler throws or rejects, nothing is applied and the changes stay pending (`(changesSaveFailed)`).
+  - The promise always resolves with `{ ok, reason, error, changes }`; it never rejects.
+- **Other methods and events:**
+  - `cancelChanges()` discards everything (`(changesCancelled)`).
+  - `getPendingChanges()` returns `{ added, updated: [{ key, row, original, changes, oldValues }], deleted, … }`, and `hasPendingChanges()` tells whether there are any.
+  - `undo()`, `redo()`, `canUndo()` and `canRedo()`; `(pendingChange)` reports every change, for your own buttons.
+- `(rowAdded)`, `(rowUpdated)` and `(rowDeleted)` fire with `pending: true` when a change is recorded. `(cellValueChange)` doesn't fire for pending changes.
+
+## Filtering
+
+- The filter icon in each header opens an Excel-style popup:
+  - "Clear filter" for the column and "Clear all filters";
+  - sort buttons;
+  - up to `maxConditions` (1–5) conditions with one AND/OR choice;
+  - a searchable, virtualized checkbox list of values, with counts.
+  Cancel and Escape close it without applying anything.
+- **Filter row** (`filtering.mode: 'row'` or `'both'`): an input under each header, with an operator button and a clear button. Booleans get a select.
+  - It's shown while at least one displayed column is filterable (`filtering.enabled`, or the column's `filterable`).
+  - Typing applies after `rowDebounce` (300 ms); Enter applies at once, and Escape reverts.
+  - It edits the first condition of the column's filter, so the popup and the row show the same filter.
+- Filtered columns show a filled funnel and an accent line under the header.
+- **Operators by type:**
+  - **text:** contains, does not contain, equals, does not equal, begins with, ends with, is empty, is not empty
+  - **number:** =, ≠, >, ≥, <, ≤, between, empty, not empty
+  - **date:** equals, not equals, before, after, on or before, on or after, between, empty, not empty
+  - **boolean:** is true, is false, empty, not empty
+- Through the API:
+
+  ```ts
+  api.applyFilter('country', { values: ['Germany', 'France'] });              // checkbox list
+  api.applyFilter('amount', { operator: 'greaterThan', value: 1000 });         // one condition
+  api.applyFilter('date', { conditions: [{ operator: 'onOrAfter', value: '2025-01-01' }, { operator: 'before', value: '2025-02-01' }], logic: 'and' });
+  api.clearFilter('amount');   // or api.clearFilter() / api.clearAllFilters() for all
+  api.isFiltered('amount');    // api.isFiltered() for any column; api.getDisplayedRowCount()
+  ```
+
+- Custom operators: `filter: { customOperators: [{ key: 'even', label: 'Is even', inputs: 0, predicate: (v) => v % 2 === 0 }] }`.
+- Fully custom logic: `filter: { predicate: (row, model, value) => … }`.
+
+## Sorting
+
+- Click a header to cycle asc → desc → none. Shift+click (configurable) adds a column to a multi-column sort; the order shows as 1, 2, 3 next to the icon.
+- API: `api.applySort('amount', 'desc')`, `api.applySort([{ field: 'country', direction: 'asc' }, { field: 'amount', direction: 'desc' }])`, `api.clearSort()`.
+- Text sorts case-insensitively and number-aware ("Item 2" before "Item 10"). Blanks go last. Provide `sort.comparator` for custom ordering.
+
+## Summaries
+
+```ts
+{ field: 'amount', type: 'number', summary: 'sum' }
+{ field: 'price',  type: 'number', summary: { type: 'avg', label: 'Average' } }
+{ field: 'margin', type: 'number', summary: {
+    label: 'Weighted',
+    // custom formula: gets data, rows, values, column, field, api, scope, filter/sort model, getSummary(), fn helpers
+    fn: (ctx) => ctx.fn.sum(ctx.rows.map((r) => r.amount * r.margin)) / (ctx.getSummary('amount') as number),
+    dependsOn: ['amount', 'margin'],   // recalculate only when these fields are edited
+} }
+```
+
+- `summary.sticky: true` pins the summary row to the bottom (like a pinned row); `false` shows it as a normal last row.
+- `summary.scope: 'filtered' | 'all'` (global or per column).
+- `api.recalculateSummary()` and `api.getSummaryValues()`.
+
+## Tooltips
+
+On by default for text that is cut off (ellipsis): the tooltip shows the full text after `showDelay`.
+
+```ts
+config = { tooltips: { cells: 'truncated' /* 'always' | 'never' */, headers: 'truncated', showDelay: 500, placement: 'top', disabledTypes: ['boolean'] } };
+columns = [
+  { field: 'notes', tooltip: 'always' },
+  { field: 'total', tooltip: (ctx) => `${ctx.row.quantity} × ${ctx.row.unitPrice}` },
+  { field: 'margin', description: 'Gross margin after discounts' },   // always shown in the header tooltip
+  { field: 'id', tooltip: false, headerTooltip: false },
+];
+```
+
+```html
+<ng-template infiGridCellTooltip="customer" let-row="row">{{ row.customer.name }}, {{ row.customer.country }}</ng-template>
+<ng-template infiGridHeaderTooltip="margin" let-column let-description="description"><b>{{ column.header }}</b>: {{ description }}</ng-template>
+```
+
+- **One tooltip per grid**, in `<body>` so it is never clipped. It is removed with the grid.
+- It hides on scroll, click, key press and any re-render, so recycled rows never keep a stale tooltip.
+- It flips to the other side near the window edges.
+- **Keyboard:** arrow-key focus on a cut-off cell shows its tooltip (focusing a header's filter button shows the header's). Escape hides it.
+- **Accessibility:** it has `role="tooltip"` and sets `aria-describedby` on its cell.
+
+## Loading, empty and error states
+
+```html
+<infi-grid [data]="rows()" [columns]="columns" [loading]="loading()" [error]="loadError()" />
+```
+
+- **Loading:** an overlay over the grid only; the rest of your app stays usable. `loading.blockGrid` decides whether the grid itself can be used meanwhile.
+- **Empty:** shown when the data array is empty, and also when filters remove every row (`showWhenFiltered`). `useCustomTemplate: false` switches back to the built-in message.
+- **Error:** shown when `[error]` (or `api.setError()`) is set. It's independent of the empty state and takes precedence. `errorState.enabled: false` hides it.
+
+## Data refresh
+
+| Call | What it does |
+|---|---|
+| a new `[data]` array, `setData(rows)`, `updateData(rows)` | Replace the data: re-sort, re-filter, summaries, and reconcile selection and edits by key |
+| `refreshData()`, `refresh()` | Re-read the same array after `push`/`splice` or changes to its objects |
+| `refreshRows(rows)` | Re-render only these rows after changing them in place |
+| `updateCell(rowIndex, field, value)` / `updateRow(key, changes)` | Change values (the row re-renders, rows don't move) |
+
+`config.dataRefresh` (or the options of `setData`/`refreshData`) decides what a refresh keeps: `filter`, `sort` and `selection` (`'keep'` or `'reset'`), and `scroll` (`'keep'` or `'top'`). `(dataRefresh)` reports `{ reason, rowCount, displayedRowCount, removedSelectionKeys, filterReset, sortReset }`; `(loadingChange)` reports each change of the loading state.
+
+## Grid API
+
+Get the API from `(gridReady)="api = $event.api"`, from the component's `api`, or call the methods on the component itself (`@ViewChild(InfiGridComponent) grid; grid.selectRowByKey(1)`).
+
+| Area | Methods |
+|---|---|
+| State | `getConfig`, `getColumns`, `getColumn`, `getDisplayedColumns`, `getVisibleColumns`, `getColumnState`, `getColumnWidth`, `getData`, `getDisplayedRows`, `getVisibleRows`, `getRow`, `getFilterModel`, `getSortModel`, `getSummaryConfig`, `getSummaryValues`, `getVirtualizationState`, `getEditState` |
+| Rows by key | `getRowKey`, `getRowByKey`, `getRowIndexByKey`, `scrollToRowByKey` |
+| Filtering | `applyFilter`, `setFilterModel`, `clearFilter`, `clearAllFilters`, `isFiltered`, `getDisplayedRowCount`, `openFilter`, `closeFilter` |
+| Sorting | `applySort`, `clearSort` |
+| Data | `setData`, `updateData`, `refreshData`, `refresh`, `updateCell`, `refreshRows` |
+| Editing | `enterEditMode`, `exitEditMode`, `isEditing`, `setGridEditMode`, `isGridEditMode` |
+| Selection | `selectRowByKey`, `deselectRowByKey`, `selectRowsByKeys`, `deselectRowsByKeys`, `toggleRowSelection`, `selectAll`, `deselectAll`, `clearSelection`, `getSelectedRows`, `getSelectedKeys`, `isRowSelected` |
+| Cell selection | `getSelectedCell`, `selectCell`, `clearCellSelection` |
+| Add, update, delete | `addRow`, `beginAddRow`, `updateRow`, `deleteRow`, `deleteRows`, `requestDeleteRows`, `deleteSelectedRows` |
+| Batch | `getPendingChanges`, `hasPendingChanges`, `saveChanges`, `cancelChanges`, `undo`, `redo`, `canUndo`, `canRedo` |
+| Summaries | `recalculateSummary` |
+| Scrolling | `scrollToRow(index, 'auto' \| 'start' \| 'center' \| 'end')`, `scrollToColumn(field \| index, …)` |
+| Columns | `setColumns`, `setColumnWidth`, `resetColumnWidth`, `setColumnVisible` |
+| States | `setLoading`, `isLoading`, `setError`, `getError` |
+
+Row indexes refer to the current (sorted and filtered) view. `getVisibleRows()` and `getVisibleColumns()` return what's in the viewport right now; `getDisplayedRows()` returns every row that passes the filters, in display order.
+
+## Events
+
+| Area | Outputs |
+|---|---|
+| Grid and data | `gridReady`, `dataRefresh`, `loadingChange`, `dataChange`, `viewportChange`, `gridError` |
+| Sorting, filtering, columns | `sortChange`, `filterChange`, `columnResize` (`oldWidth`, `newWidth`, `finished`, `source`) |
+| Clicks and pointer | `cellClick`, `cellDoubleClick`, `rowClick`, `rowDoubleClick`, `headerClick`, `cellContextMenu`, `cellMouseEnter`, `cellMouseLeave` |
+| Selection | `selectionChange`, `rowSelected`, `rowDeselected`, `selectionCleared`, `selectionClick`, `cellSelectionChange` |
+| Editing | `cellValueChange`, `editStart`, `editCommit`, `editCancel` |
+| Add, update, delete | `rowAdding`, `rowAdded`, `rowUpdating`, `rowUpdated`, `rowDeleting`, `rowDeleted` |
+| Batch | `changesSaved`, `changesCancelled`, `changesSaveFailed`, `pendingChange` |
+
+- **Context:** cell events carry `row`, `key`, `rowIndex`, `dataIndex`, `field`, `column`, `value` and `formattedValue`, so you never need to read the DOM.
+- **Cancelling:** set `event.cancel = true` in `cellClick`, `rowClick`, `cellDoubleClick`, `rowDoubleClick`, `headerClick` or `selectionClick` to stop the grid's own reaction (row or cell selection, starting an edit, sorting).
+- **Double clicks:** `events.clickMode: 'waitForDoubleClick'` holds clicks back for `doubleClickDelay`, so a double click emits only `cellDoubleClick`.
+- **No duplicates:** events come from the grid's state, not from DOM elements, so recycled rows never duplicate them. Events caused by an input change are emitted right after that change detection.
+
+The grid never writes to the console. Problems it catches (for example a custom summary function that throws, which shows `#ERROR`) are reported through `(gridError)`.
+
+## Styling and theming
+
+- **Per cell or column:** `cellClass` / `cellStyle` (static or functions of the cell), `headerClass` / `headerStyle`, and `rowClass` / `rowStyle` in the config.
+- **Themes:** set CSS variables on the grid, a wrapper or `:root`:
+
+  ```css
+  infi-grid.orders {
+    --infi-grid-accent: #7c3aed;
+    --infi-grid-header-bg: #f5f3ff;
+    --infi-grid-font-size: 14px;
+  }
+  ```
+
+  Variables: `--infi-grid-font-family`, `-font-size`, `-bg`, `-fg`, `-muted-fg`, `-border-color`, `-cell-border-color`, `-cell-padding`, `-header-bg`, `-header-fg`, `-row-alt-bg`, `-row-hover-bg`, `-accent`, `-accent-fg`, `-summary-bg`, `-editing-bg`, `-invalid`, `-popup-bg`, `-popup-shadow`, `-input-bg`, `-radius`, `-overlay-bg`, `-selected-bg`, `-selected-hover-bg`, `-active-row-bg`, `-selected-cell-bg`, `-danger`, `-added-color`, `-modified-color`, `-modified-bg`, `-tooltip-bg`, `-tooltip-fg`.
+- **Dark theme:** `config.theme = 'dark'`. A custom theme `'x'` adds the class `infi-grid-theme-x` for your own variables.
+- **Useful classes:**
+  - rows: `.infi-grid__row--odd`, `--editing`, `--selected`, `--active` (cell selection), and in batch mode `--added`, `--modified`, `--deleted`
+  - cells: `.infi-grid__cell.is-editing`, `.is-focused`, `.is-selected` (cell selection), `.is-invalid`, `.is-modified`
+  - headers: `.infi-grid__header-cell.is-sorted`, `.is-filtered`
+  - others: `.infi-grid__summary--sticky`, `.infi-grid-tooltip`
+
+## Keyboard
+
+| Keys | Action |
+|---|---|
+| Arrow keys, Page Up/Down, Home/End (Ctrl+Home/End) | Move the focused cell, which is the selected cell with `cellSelection` (the grid scrolls to it) |
+| Enter or F2 | Edit the focused cell |
+| Enter (in an editor) | Save |
+| Escape | Cancel editing, close the filter popup, or hide a tooltip |
+| Tab / Shift+Tab (in an editor) | Save and edit the next / previous editable cell |
+| Space, Shift+↑/↓, Ctrl/Cmd+A | Toggle, extend or select all rows (selection) |
+| Delete | Delete the selected rows, or the focused row (with `allowDelete`) |
+| Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z or Ctrl+Y | Undo and redo (batch mode) |
+| Tab / Shift+Tab (in the filter row) | The next or previous column's filter |
+
+## Performance tips
+
+- Scrolling runs outside Angular's zone and checks only the grid, so your app's change detection never runs while the user scrolls.
+- Fast scrolling never shows blank rows or columns (`virtualization.syncScroll`, on by default). Browsers scroll on their own thread, ahead of the page's code; the grid keeps the drawn content in place while they do, and moves it in the frame it draws the rows and columns for the new position. On a slow PC the content can follow the scrollbar a frame late, but it is never blank.
+- Row and cell elements are reused, never recreated. Template views are reused too.
+- Prefer `ng-template` or `OnPush` components in cell templates, and keep them light (no heavy pipes or functions).
+- Replace the data array (`data = [...data]`) or call `api.refresh()` after mutating it in place.
+- Only listen to `(viewportChange)` if you need it; it re-enters Angular's zone on every scroll frame.
+
+## Notes and limitations
+
+- All rows share one fixed height (`rowHeight`). That's what makes 1M-row virtualization O(1).
+- Above about 416,000 rows at 36px, the grid switches to scaled scrolling, because browsers cap element height.
+- Rows and cells are positioned absolutely and reused, so their DOM order can differ from the visual order. ARIA row and column indexes give the logical order.
+- After editing, rows stay where they are; call `api.refresh()` to re-sort and re-filter.
+- Keys are immutable: change a row's key by deleting it and adding a new row.
+
+## Coming from angpackage-grid
+
+InfiGrid 1.0.0 is angpackage-grid 1.2.1 under its new name. Inputs, outputs, configuration, the grid API, events and types are unchanged; only the names below change:
+
+| angpackage-grid | InfiGrid |
+|---|---|
+| `npm install angpackage-grid` | `npm install infi-grid` |
+| `import { … } from 'angpackage-grid'` | `import { … } from 'infi-grid'` |
+| `<ang-grid>` | `<infi-grid>` |
+| `AngGridComponent`, `AngGridModule`, `ANG_GRID` | `InfiGridComponent`, `InfiGridModule`, `INFI_GRID` |
+| Template directives `angGridCell`, `angGridEdit`, `angGridHeader`, `angGridSummary`, `angGridLoading`, `angGridEmpty`, `angGridError`, `angGridDeleteConfirm`, `angGridCellTooltip`, `angGridHeaderTooltip` | `infiGridCell`, `infiGridEdit`, `infiGridHeader`, `infiGridSummary`, `infiGridLoading`, `infiGridEmpty`, `infiGridError`, `infiGridDeleteConfirm`, `infiGridCellTooltip`, `infiGridHeaderTooltip` |
+| CSS classes `.ang-grid`, `.ang-grid__*`, `.ang-grid-theme-*`, `.ang-grid-popup`, `.ang-grid-menu`, `.ang-grid-tooltip` | `.infi-grid`, `.infi-grid__*`, `.infi-grid-theme-*`, `.infi-grid-popup`, `.infi-grid-menu`, `.infi-grid-tooltip` |
+| Theme variables `--ang-grid-*` | `--infi-grid-*` |
+
+A search and replace of `ang-grid` → `infi-grid`, `angGrid` → `infiGrid`, `AngGrid` → `InfiGrid` and `ANG_GRID` → `INFI_GRID`, plus the package name in imports and `package.json`, moves an app over.
+
+## Compatibility
+
+Built with Angular 19 (partial compilation). It works in Angular 19 apps and newer, with or without zone.js. Styles are included in the component, so no `angular.json` changes are needed.