infi-grid 1.0.0

package/lib/directives/template.directives.d.ts

@@ -0,0 +1,98 @@
+import { TemplateRef } from '@angular/core';
+import type { GridDataType } from '../models/column.types';
+import type { GridHeaderTooltipContext, GridTooltipContext } from '../models/tooltip.types';
+import type { GridCellContext, GridDeleteConfirmContext, GridEditContext, GridEmptyContext, GridErrorContext, GridHeaderContext, GridLoadingContext, GridSummaryCellContext } from '../models/template.types';
+import * as i0 from "@angular/core";
+/**
+ * Display-mode cell template.
+ * `<ng-template infiGridCell="price" let-value let-row="row">…</ng-template>` targets one column;
+ * `<ng-template infiGridCell type="date" let-value>…</ng-template>` targets every date column.
+ */
+export declare class GridCellTemplateDirective<TRow = any, TValue = any> {
+    readonly templateRef: TemplateRef<GridCellContext<TRow, TValue>>;
+    /** Column field. Leave empty and set `type` to target a data type. */
+    readonly field: import("@angular/core").InputSignal<string | undefined>;
+    readonly type: import("@angular/core").InputSignal<GridDataType | undefined>;
+    static ngTemplateContextGuard<TRow, TValue>(_dir: GridCellTemplateDirective<TRow, TValue>, ctx: unknown): ctx is GridCellContext<TRow, TValue>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<GridCellTemplateDirective<any, any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<GridCellTemplateDirective<any, any>, "ng-template[infiGridCell]", never, { "field": { "alias": "infiGridCell"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/** Edit-mode cell template: `infiGridEdit="field"` or `infiGridEdit type="number"`. */
+export declare class GridEditTemplateDirective<TRow = any, TValue = any> {
+    readonly templateRef: TemplateRef<GridEditContext<TRow, TValue>>;
+    readonly field: import("@angular/core").InputSignal<string | undefined>;
+    readonly type: import("@angular/core").InputSignal<GridDataType | undefined>;
+    static ngTemplateContextGuard<TRow, TValue>(_dir: GridEditTemplateDirective<TRow, TValue>, ctx: unknown): ctx is GridEditContext<TRow, TValue>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<GridEditTemplateDirective<any, any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<GridEditTemplateDirective<any, any>, "ng-template[infiGridEdit]", never, { "field": { "alias": "infiGridEdit"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/** Header template: `infiGridHeader="field"`, or without a field for every column. */
+export declare class GridHeaderTemplateDirective<TRow = any> {
+    readonly templateRef: TemplateRef<GridHeaderContext<TRow>>;
+    readonly field: import("@angular/core").InputSignal<string | undefined>;
+    readonly type: import("@angular/core").InputSignal<GridDataType | undefined>;
+    static ngTemplateContextGuard<TRow>(_dir: GridHeaderTemplateDirective<TRow>, ctx: unknown): ctx is GridHeaderContext<TRow>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<GridHeaderTemplateDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<GridHeaderTemplateDirective<any>, "ng-template[infiGridHeader]", never, { "field": { "alias": "infiGridHeader"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/** Summary cell template: `infiGridSummary="field"`, or without a field for every column. */
+export declare class GridSummaryTemplateDirective<TRow = any> {
+    readonly templateRef: TemplateRef<GridSummaryCellContext<TRow>>;
+    readonly field: import("@angular/core").InputSignal<string | undefined>;
+    readonly type: import("@angular/core").InputSignal<GridDataType | undefined>;
+    static ngTemplateContextGuard<TRow>(_dir: GridSummaryTemplateDirective<TRow>, ctx: unknown): ctx is GridSummaryCellContext<TRow>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<GridSummaryTemplateDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<GridSummaryTemplateDirective<any>, "ng-template[infiGridSummary]", never, { "field": { "alias": "infiGridSummary"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/** Loading template: `<ng-template infiGridLoading>…</ng-template>`. */
+export declare class GridLoadingTemplateDirective<TRow = any> {
+    readonly templateRef: TemplateRef<GridLoadingContext<TRow>>;
+    static ngTemplateContextGuard<TRow>(_dir: GridLoadingTemplateDirective<TRow>, ctx: unknown): ctx is GridLoadingContext<TRow>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<GridLoadingTemplateDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<GridLoadingTemplateDirective<any>, "ng-template[infiGridLoading]", never, {}, {}, never, never, true, never>;
+}
+/** Empty-data ("No Data Found") template: `<ng-template infiGridEmpty let-reason>…</ng-template>`. */
+export declare class GridEmptyTemplateDirective<TRow = any> {
+    readonly templateRef: TemplateRef<GridEmptyContext<TRow>>;
+    static ngTemplateContextGuard<TRow>(_dir: GridEmptyTemplateDirective<TRow>, ctx: unknown): ctx is GridEmptyContext<TRow>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<GridEmptyTemplateDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<GridEmptyTemplateDirective<any>, "ng-template[infiGridEmpty]", never, {}, {}, never, never, true, never>;
+}
+/** Error template: `<ng-template infiGridError let-error>…</ng-template>`. */
+export declare class GridErrorTemplateDirective<TRow = any> {
+    readonly templateRef: TemplateRef<GridErrorContext<TRow>>;
+    static ngTemplateContextGuard<TRow>(_dir: GridErrorTemplateDirective<TRow>, ctx: unknown): ctx is GridErrorContext<TRow>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<GridErrorTemplateDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<GridErrorTemplateDirective<any>, "ng-template[infiGridError]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Delete confirmation, replacing the built-in dialog:
+ * `<ng-template infiGridDeleteConfirm let-count="count" let-confirm="confirm" let-cancel="cancel">…</ng-template>`.
+ */
+export declare class GridDeleteConfirmTemplateDirective<TRow = any> {
+    readonly templateRef: TemplateRef<GridDeleteConfirmContext<TRow>>;
+    static ngTemplateContextGuard<TRow>(_dir: GridDeleteConfirmTemplateDirective<TRow>, ctx: unknown): ctx is GridDeleteConfirmContext<TRow>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<GridDeleteConfirmTemplateDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<GridDeleteConfirmTemplateDirective<any>, "ng-template[infiGridDeleteConfirm]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Cell tooltip template: `<ng-template infiGridCellTooltip="price" let-value let-row="row">…</ng-template>`
+ * for one column, `type="date"` for a data type, or no field for every column.
+ */
+export declare class GridCellTooltipTemplateDirective<TRow = any, TValue = any> {
+    readonly templateRef: TemplateRef<GridTooltipContext<TRow, TValue>>;
+    readonly field: import("@angular/core").InputSignal<string | undefined>;
+    readonly type: import("@angular/core").InputSignal<GridDataType | undefined>;
+    static ngTemplateContextGuard<TRow, TValue>(_dir: GridCellTooltipTemplateDirective<TRow, TValue>, ctx: unknown): ctx is GridTooltipContext<TRow, TValue>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<GridCellTooltipTemplateDirective<any, any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<GridCellTooltipTemplateDirective<any, any>, "ng-template[infiGridCellTooltip]", never, { "field": { "alias": "infiGridCellTooltip"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/** Header tooltip template: `<ng-template infiGridHeaderTooltip="price" let-column let-description="description">…</ng-template>`. */
+export declare class GridHeaderTooltipTemplateDirective<TRow = any> {
+    readonly templateRef: TemplateRef<GridHeaderTooltipContext<TRow>>;
+    readonly field: import("@angular/core").InputSignal<string | undefined>;
+    readonly type: import("@angular/core").InputSignal<GridDataType | undefined>;
+    static ngTemplateContextGuard<TRow>(_dir: GridHeaderTooltipTemplateDirective<TRow>, ctx: unknown): ctx is GridHeaderTooltipContext<TRow>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<GridHeaderTooltipTemplateDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<GridHeaderTooltipTemplateDirective<any>, "ng-template[infiGridHeaderTooltip]", never, { "field": { "alias": "infiGridHeaderTooltip"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}

package/lib/grid.module.d.ts

@@ -0,0 +1,15 @@
+import { InfiGridComponent } from './components/grid.component';
+import { GridTemplateComponent } from './directives/grid-template-component';
+import { GridCellTemplateDirective, GridCellTooltipTemplateDirective, GridDeleteConfirmTemplateDirective, GridEditTemplateDirective, GridEmptyTemplateDirective, GridErrorTemplateDirective, GridHeaderTemplateDirective, GridHeaderTooltipTemplateDirective, GridLoadingTemplateDirective, GridSummaryTemplateDirective } from './directives/template.directives';
+import * as i0 from "@angular/core";
+import * as i1 from "./components/grid.component";
+import * as i2 from "./directives/template.directives";
+/** Everything needed in a template: `imports: [INFI_GRID]` in a standalone component. */
+export declare const INFI_GRID: readonly [typeof InfiGridComponent, typeof GridCellTemplateDirective, typeof GridEditTemplateDirective, typeof GridHeaderTemplateDirective, typeof GridSummaryTemplateDirective, typeof GridLoadingTemplateDirective, typeof GridEmptyTemplateDirective, typeof GridErrorTemplateDirective, typeof GridDeleteConfirmTemplateDirective, typeof GridCellTooltipTemplateDirective, typeof GridHeaderTooltipTemplateDirective];
+/** For NgModule-based applications: `imports: [InfiGridModule]`. */
+export declare class InfiGridModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<InfiGridModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<InfiGridModule, never, [typeof i1.InfiGridComponent, typeof i2.GridCellTemplateDirective, typeof i2.GridEditTemplateDirective, typeof i2.GridHeaderTemplateDirective, typeof i2.GridSummaryTemplateDirective, typeof i2.GridLoadingTemplateDirective, typeof i2.GridEmptyTemplateDirective, typeof i2.GridErrorTemplateDirective, typeof i2.GridDeleteConfirmTemplateDirective, typeof i2.GridCellTooltipTemplateDirective, typeof i2.GridHeaderTooltipTemplateDirective], [typeof i1.InfiGridComponent, typeof i2.GridCellTemplateDirective, typeof i2.GridEditTemplateDirective, typeof i2.GridHeaderTemplateDirective, typeof i2.GridSummaryTemplateDirective, typeof i2.GridLoadingTemplateDirective, typeof i2.GridEmptyTemplateDirective, typeof i2.GridErrorTemplateDirective, typeof i2.GridDeleteConfirmTemplateDirective, typeof i2.GridCellTooltipTemplateDirective, typeof i2.GridHeaderTooltipTemplateDirective]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<InfiGridModule>;
+}
+export { GridTemplateComponent };

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

@@ -0,0 +1,249 @@
+import type { ColumnConfig, ResolvedColumn } from './column.types';
+import type { GridAddRowOptions, GridBeginAddRowOptions, GridChangeSet, GridCrudResult, GridSaveResult } from './crud.types';
+import type { GridRefreshOptions, GridRefreshResult, GridRowKey } from './data.types';
+import type { GridSelectAllOptions, GridSelectCellOptions, GridSelectOptions, GridSelectedCell } from './selection.types';
+import type { ResolvedGridConfig } from './config.types';
+import type { ColumnFilterModel, FilterCondition, FilterModel } from './filter.types';
+import type { SortDirection, SortModelItem } from './sort.types';
+import type { GridSummaryResult, ResolvedColumnSummary } from './summary.types';
+/** Snapshot of what the virtualization engine is rendering. */
+export interface VirtualizationState {
+    rowVirtualization: boolean;
+    columnVirtualization: boolean;
+    /** Rows after filtering. */
+    totalRows: number;
+    /** Displayed (non-hidden) columns. */
+    totalColumns: number;
+    /** Rows currently in the viewport: `[firstVisibleRow, lastVisibleRow]`, -1 when there are none. */
+    firstVisibleRow: number;
+    lastVisibleRow: number;
+    /** Rows in the DOM including the buffer: `[firstRenderedRow, lastRenderedRow]`. */
+    firstRenderedRow: number;
+    lastRenderedRow: number;
+    firstVisibleColumn: number;
+    lastVisibleColumn: number;
+    firstRenderedColumn: number;
+    lastRenderedColumn: number;
+    renderedRowCount: number;
+    renderedColumnCount: number;
+    /** Cells in the DOM (rendered rows × rendered columns). */
+    renderedCellCount: number;
+    scrollTop: number;
+    scrollLeft: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    rowHeight: number;
+    /** Full height of all rows in px. */
+    totalHeight: number;
+    totalWidth: number;
+    /** > 1 when the row count exceeds the browser's maximum element height and scrolling is scaled. */
+    scrollScale: number;
+}
+/** Current edit session. */
+export interface GridEditState<TRow = any> {
+    row: TRow;
+    /** View index of the row (-1 for the inline add row). */
+    rowIndex: number;
+    /** True for the inline add row (`beginAddRow()`): the row isn't in the data yet. */
+    isNew: boolean;
+    /** Fields being edited (one field in cell mode, every editable field in row mode). */
+    fields: readonly string[];
+    mode: 'cell' | 'row';
+    /** Values typed so far, by field. */
+    values: Readonly<Record<string, unknown>>;
+    errors: Readonly<Record<string, string | null>>;
+}
+/** Layout of one displayed column. */
+export interface GridColumnState {
+    field: string;
+    width: number;
+    left: number;
+    index: number;
+    hidden: boolean;
+    sort: SortDirection | null;
+    sortIndex: number | null;
+    filterActive: boolean;
+}
+export type GridScrollPosition = 'auto' | 'start' | 'center' | 'end';
+/**
+ * Grid reference/API. Get it from `(gridReady)`, or from the component instance (`grid.api`).
+ * Row indexes refer to the current (sorted and filtered) view unless stated otherwise.
+ */
+export interface GridApi<TRow = any> {
+    /** Configuration with every default filled in. */
+    getConfig(): ResolvedGridConfig<TRow>;
+    /** All column definitions (including hidden columns). */
+    getColumns(): readonly ResolvedColumn<TRow>[];
+    getColumn(field: string): ResolvedColumn<TRow> | undefined;
+    /** Non-hidden columns in display order. */
+    getDisplayedColumns(): readonly ResolvedColumn<TRow>[];
+    /** Columns currently inside the horizontal viewport. */
+    getVisibleColumns(): readonly ResolvedColumn<TRow>[];
+    /** Width, position, sort and filter state of each displayed column. */
+    getColumnState(): readonly GridColumnState[];
+    getColumnWidth(field: string): number | undefined;
+    /** The complete data array. */
+    getData(): readonly TRow[];
+    /** Rows after filtering and sorting, in display order. */
+    getDisplayedRows(): readonly TRow[];
+    /** Rows currently inside the vertical viewport. */
+    getVisibleRows(): readonly TRow[];
+    /** Row at a view index. */
+    getRow(rowIndex: number): TRow | undefined;
+    /** The key of a row (its `primaryKey` value, or the row itself without a primary key). */
+    getRowKey(row: TRow): GridRowKey;
+    /** The row with this key, if it is in the data. Works for rows that are filtered out or not rendered. */
+    getRowByKey(key: GridRowKey): TRow | undefined;
+    /** Current view index of the row with this key, or -1 when it isn't displayed. */
+    getRowIndexByKey(key: GridRowKey): number;
+    getFilterModel(): FilterModel;
+    getSortModel(): readonly SortModelItem[];
+    /** Summary configuration of the grid and of every column. */
+    getSummaryConfig(): {
+        enabled: boolean;
+        sticky: boolean;
+        scope: 'filtered' | 'all';
+        columns: Readonly<Record<string, ResolvedColumnSummary<TRow>>>;
+    };
+    /** Calculated summaries by field. */
+    getSummaryValues(): Readonly<Record<string, GridSummaryResult>>;
+    getVirtualizationState(): VirtualizationState;
+    getEditState(): GridEditState<TRow> | null;
+    /**
+     * Filter one column. Accepts a full column model, a single condition, or `null` to remove the filter.
+     * Merges with the filters of other columns.
+     */
+    applyFilter(field: string, filter: ColumnFilterModel | FilterCondition | null): void;
+    /** Replace the whole filter model. */
+    setFilterModel(model: FilterModel): void;
+    /** Remove the filter of one column, or of every column when no field is given. */
+    clearFilter(field?: string): void;
+    /** Remove every column's filter (same as `clearFilter()`). */
+    clearAllFilters(): void;
+    /** Whether a column (or, without a field, any column) is filtered. */
+    isFiltered(field?: string): boolean;
+    /** Rows left after filtering. */
+    getDisplayedRowCount(): number;
+    /** Open the filter popup of a column. */
+    openFilter(field: string): void;
+    closeFilter(): void;
+    /**
+     * Sort by one column (`applySort('price', 'desc')`), or set the whole sort model (`applySort([...])`).
+     * Pass `{ multi: true }` to add the column to the existing sort instead of replacing it.
+     */
+    applySort(field: string, direction?: SortDirection, options?: {
+        multi?: boolean;
+    }): void;
+    applySort(model: readonly SortModelItem[]): void;
+    /** Remove the sort of one column, or all sorting when no field is given. */
+    clearSort(field?: string): void;
+    /** Replace the data array. Same as binding a new `[data]` array; `options` override `config.dataRefresh`. */
+    setData(data: readonly TRow[], options?: GridRefreshOptions): GridRefreshResult;
+    /** Replace the data array (1.0 name of `setData`). */
+    updateData(data: readonly TRow[], options?: GridRefreshOptions): GridRefreshResult;
+    /**
+     * Re-read the current data after changing it in place (push, splice, edited objects): re-sorts,
+     * re-filters, rebuilds the key index, recalculates summaries and reconciles the selection.
+     */
+    refreshData(options?: GridRefreshOptions): GridRefreshResult;
+    /** Same as `refreshData()` (1.0 name). */
+    refresh(): void;
+    /** Set one cell value; only that row re-renders and only affected summaries recalculate. */
+    updateCell(rowIndex: number, field: string, value: unknown): void;
+    /** Re-render the given rows after you changed their objects in place. */
+    refreshRows(rows: readonly TRow[]): void;
+    /**
+     * Put a cell (field given) or a whole row (no field) into edit mode.
+     * Returns false when nothing there is editable.
+     */
+    enterEditMode(rowIndex: number, field?: string): boolean;
+    /** Leave edit mode, saving (default) or discarding the edited values. Returns false if validation failed. */
+    exitEditMode(options?: {
+        commit?: boolean;
+    }): boolean;
+    isEditing(): boolean;
+    /** Switch every editable cell between display mode and edit mode. */
+    setGridEditMode(enabled: boolean): void;
+    isGridEditMode(): boolean;
+    /**
+     * Add a row. The object becomes the row (with `editing.newRow`, the initializer's object does, with these
+     * values applied); column `defaultValue`s fill missing fields. Validates `required`, column validators,
+     * `editing.rowValidator` and the primary key (present and unique), then emits `rowAdding` (cancelable),
+     * `rowAdded` and `dataChange`. The new row stays visible until the filter changes, even if the filter would hide it.
+     */
+    addRow(row: Partial<TRow>, options?: GridAddRowOptions): GridCrudResult<TRow>;
+    /** Open the inline add row (editors for new values; Enter or ✓ adds it, Escape or ✕ discards it). */
+    beginAddRow(options?: GridBeginAddRowOptions<TRow>): boolean;
+    /**
+     * Change fields of a row in place (by field or dot path). Validates like an edit, refuses key changes, then
+     * emits `rowUpdating` (cancelable), `cellValueChange` per field and `rowUpdated`. Only that row re-renders.
+     */
+    updateRow(key: GridRowKey, changes: Partial<TRow> | Readonly<Record<string, unknown>>): GridCrudResult<TRow>;
+    /** Delete a row now (no confirmation). Emits `rowDeleting` (cancelable), `rowDeleted` and `dataChange`. */
+    deleteRow(key: GridRowKey): GridCrudResult<TRow>;
+    /** Delete several rows in one operation (no confirmation). */
+    deleteRows(keys: readonly GridRowKey[]): GridCrudResult<TRow>;
+    /** Delete rows after the configured confirmation (`editing.confirmDelete`). */
+    requestDeleteRows(keys: readonly GridRowKey[]): Promise<GridCrudResult<TRow>>;
+    /** Delete the selected rows after the configured confirmation. */
+    deleteSelectedRows(): Promise<GridCrudResult<TRow>>;
+    /** The pending adds, updates and deletes (empty outside batch mode). */
+    getPendingChanges(): GridChangeSet<TRow>;
+    hasPendingChanges(): boolean;
+    /**
+     * Commits an open edit, passes the changes to `handler` (default `editing.saveHandler`) and, when it
+     * succeeds, applies them to the data (`changesSaved`, `dataChange`). When it throws or rejects, nothing
+     * is applied and the changes stay pending (`changesSaveFailed`). The promise never rejects.
+     */
+    saveChanges(handler?: (changes: GridChangeSet<TRow>) => unknown): Promise<GridSaveResult<TRow>>;
+    /** Discards every pending change (`changesCancelled`). Returns what was discarded. */
+    cancelChanges(): GridChangeSet<TRow>;
+    /** Undo the last pending change. False when there is nothing to undo (or an edit is open). */
+    undo(): boolean;
+    redo(): boolean;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Select a row by key. In single mode it replaces the selection. False when missing, not selectable or already selected. */
+    selectRowByKey(key: GridRowKey, options?: GridSelectOptions): boolean;
+    deselectRowByKey(key: GridRowKey): boolean;
+    /** Select rows by key (added to the selection; single mode keeps the last). Returns how many were newly selected. */
+    selectRowsByKeys(keys: readonly GridRowKey[], options?: GridSelectOptions): number;
+    /** Returns how many were deselected. */
+    deselectRowsByKeys(keys: readonly GridRowKey[]): number;
+    /** Toggle a row's selection. Returns true when it is selected afterwards. */
+    toggleRowSelection(key: GridRowKey): boolean;
+    /** Select every row in scope (default `selection.selectAllScope`; multiple mode). Returns how many were newly selected. */
+    selectAll(options?: GridSelectAllOptions): number;
+    /** Deselect the rows in scope (default: every selected row). Returns how many were deselected. */
+    deselectAll(options?: GridSelectAllOptions): number;
+    /** Deselect everything. */
+    clearSelection(): void;
+    /** Selected rows in selection order (also rows that are filtered out or not rendered). */
+    getSelectedRows(): TRow[];
+    getSelectedKeys(): GridRowKey[];
+    isRowSelected(key: GridRowKey): boolean;
+    /** The selected cell, or null (also while cell selection is off). */
+    getSelectedCell(): GridSelectedCell<TRow> | null;
+    /**
+     * Select a cell by row key and field (emits `cellSelectionChange`). False when cell selection is off, the row or the
+     * column isn't displayed, or the cell is already selected.
+     */
+    selectCell(key: GridRowKey, field: string, options?: GridSelectCellOptions): boolean;
+    /** Clear the selected cell (emits `cellSelectionChange` when one was selected). */
+    clearCellSelection(): void;
+    /** Recalculate summaries (all, or the given fields). */
+    recalculateSummary(fields?: string | readonly string[]): void;
+    scrollToRow(rowIndex: number, position?: GridScrollPosition): void;
+    /** Scroll the row with this key into view. Returns false when it isn't displayed. */
+    scrollToRowByKey(key: GridRowKey, position?: GridScrollPosition): boolean;
+    scrollToColumn(field: string | number, position?: GridScrollPosition): void;
+    setColumns(columns: readonly ColumnConfig<TRow>[]): void;
+    setColumnWidth(field: string, width: number): void;
+    /** Restore the configured width of a column, or of every resized column when no field is given. */
+    resetColumnWidth(field?: string): void;
+    setColumnVisible(field: string, visible: boolean): void;
+    setLoading(loading: boolean): void;
+    isLoading(): boolean;
+    setError(error: unknown): void;
+    getError(): unknown;
+}

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

@@ -0,0 +1,184 @@
+import type { ColumnFilterConfig, FilterIconVisibility, ResolvedColumnFilter } from './filter.types';
+import type { ColumnSortConfig, SortIconVisibility } from './sort.types';
+import type { ColumnSummaryConfig, GridSummaryType, ResolvedColumnSummary } from './summary.types';
+import type { GridCellContext, GridEditContext, GridHeaderContext, GridSummaryCellContext, GridTemplate } from './template.types';
+import type { GridHeaderTooltipContext, GridTooltipContext, GridTooltipMode } from './tooltip.types';
+/** Data types understood by the grid. The type drives formatting, sorting, filtering, editors and summaries. */
+export type GridDataType = 'text' | 'number' | 'date' | 'boolean';
+export type GridCellAlign = 'left' | 'center' | 'right';
+/** Built-in editors. `select` is a dropdown; `date` is a date picker. */
+export type GridEditorType = 'text' | 'number' | 'select' | 'checkbox' | 'date';
+export interface GridSelectOption<TValue = unknown> {
+    label: string;
+    value: TValue;
+}
+/** Options passed to the built-in editors (and available to custom edit templates). */
+export interface GridEditorOptions<TRow = any> {
+    /** Options for the `select` editor. Can be computed per row. */
+    options?: readonly GridSelectOption[] | ((row: TRow) => readonly GridSelectOption[]);
+    /** `number` editor limits. */
+    min?: number;
+    max?: number;
+    step?: number;
+    /** `text`/`number` editor placeholder. */
+    placeholder?: string;
+    /** `text` editor max length. */
+    maxLength?: number;
+}
+export type GridClassValue = string | readonly string[] | null | undefined;
+export type GridStyleValue = Readonly<Record<string, string | number | null | undefined>>;
+/** Argument passed to `cellClass` / `cellStyle` functions. */
+export interface GridCellStyleContext<TRow = any, TValue = any> {
+    row: TRow;
+    value: TValue;
+    rowIndex: number;
+    field: string;
+    column: ResolvedColumn<TRow>;
+}
+/**
+ * Configuration for one column. Columns are passed to the grid as an array.
+ * Every behavior flag here overrides the matching global flag in `GridConfig`.
+ */
+export interface ColumnConfig<TRow = any, TValue = any> {
+    /** Property name or dot path (`'customer.name'`) in the row object. Must be unique across columns. */
+    field: string;
+    /** Header text. Defaults to the field name. */
+    header?: string;
+    /** Data type. Defaults to `'text'`. */
+    type?: GridDataType;
+    /** Width in px. Defaults to `defaultColumn.width` (150). */
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    hidden?: boolean;
+    /** Text alignment. Numbers default to right-aligned. */
+    align?: GridCellAlign;
+    /** Allow drag-resizing of this column. */
+    resizable?: boolean;
+    /** Column-level sorting flag (overrides `sorting.enabled`). */
+    sortable?: boolean;
+    /** Column-level filtering flag (overrides `filtering.enabled`). */
+    filterable?: boolean;
+    /** Column-level editing flag (overrides `editing.enabled`). A function decides per row. */
+    editable?: boolean | ((row: TRow) => boolean);
+    /** Summary shown in the summary row: a built-in name (`'sum'`) or a full config with custom functions. */
+    summary?: ColumnSummaryConfig<TRow> | GridSummaryType;
+    /** Sorting configuration (comparator, icon visibility, sort cycle). */
+    sort?: ColumnSortConfig<TRow>;
+    /** Filtering configuration (operators, value list, custom predicate, icon visibility). */
+    filter?: ColumnFilterConfig<TRow>;
+    /** Computed value (formula column). Used for display, sorting, filtering and summaries. */
+    valueGetter?: (row: TRow) => TValue;
+    /** Writes an edited value back into the row. Needed for computed or nested fields you want to edit. */
+    valueSetter?: (row: TRow, value: TValue) => void;
+    /** Custom display text for the default cell renderer and the filter value list. */
+    valueFormatter?: (value: TValue, row: TRow | undefined) => string;
+    /** `Intl.NumberFormat` options for number columns. */
+    numberFormat?: Intl.NumberFormatOptions;
+    /** `Intl.DateTimeFormat` options for date columns. */
+    dateFormat?: Intl.DateTimeFormatOptions;
+    /** Labels used for boolean values. */
+    booleanLabels?: {
+        true: string;
+        false: string;
+    };
+    /** Display-mode template (TemplateRef or component) for the cells of this column. */
+    displayTemplate?: GridTemplate<GridCellContext<TRow, TValue>>;
+    /**
+     * Reuse key of this column's template cells. Template cells are kept and reused while scrolling sideways: a cell
+     * that leaves the view is given to a column with the same `templateKey` (and template) when one comes in, so what
+     * it rendered stays and is only updated. Set it when columns share a template but render different content, for
+     * example a template with an `@switch` on the column's type (use that type as the key). Without keys, a cell can
+     * be given to any column, and then re-renders that column's content.
+     */
+    templateKey?: string;
+    /** Edit-mode template (TemplateRef or component) for the cells of this column. */
+    editTemplate?: GridTemplate<GridEditContext<TRow, TValue>>;
+    /** Header template (TemplateRef or component). Replaces the header label; sort/filter icons stay. */
+    headerTemplate?: GridTemplate<GridHeaderContext<TRow>>;
+    /** Summary cell template (TemplateRef or component). */
+    summaryTemplate?: GridTemplate<GridSummaryCellContext<TRow>>;
+    /**
+     * Cell tooltip: `true`/`false` turn it on or off, `'truncated'`/`'always'`/`'never'` choose when it shows,
+     * and a function returns the text (shown whenever it returns one). Default: `tooltips.cells`.
+     */
+    tooltip?: boolean | GridTooltipMode | ((ctx: GridTooltipContext<TRow, TValue>) => string | null | undefined);
+    /** Tooltip template (TemplateRef or component) for the cells of this column. */
+    tooltipTemplate?: GridTemplate<GridTooltipContext<TRow, TValue>>;
+    /** A description of the column, always shown in the header tooltip. */
+    description?: string;
+    /** Header tooltip: `true`/`false` turn it on or off, or choose when it shows. Default: `tooltips.headers`. */
+    headerTooltip?: boolean | GridTooltipMode;
+    /** Header tooltip template (TemplateRef or component). */
+    headerTooltipTemplate?: GridTemplate<GridHeaderTooltipContext<TRow>>;
+    /** Built-in editor to use. Defaults by type: text, number, date, checkbox; `select` when `editorOptions.options` is set. */
+    editor?: GridEditorType;
+    editorOptions?: GridEditorOptions<TRow>;
+    /** Validates an edited value. Return an error message to block the commit. Also runs when rows are added. */
+    validator?: (value: TValue, row: TRow) => string | null | undefined;
+    /** The field must have a value (not empty, not only spaces) when a row is added or edited. Default `false`. */
+    required?: boolean;
+    /** Value given to new rows that don't have one (inline add row and `addRow()`). A function receives the new row. */
+    defaultValue?: TValue | ((row: TRow) => TValue);
+    /**
+     * Whether the inline add row has an editor for this column. Default: the column's `editable`; for the
+     * primary-key column, an editor only when the new row has no key yet (none generated by `editing.newRow`).
+     */
+    editableOnAdd?: boolean | ((row: TRow) => boolean);
+    /** CSS class(es) for the cells of this column. A function styles individual cells. */
+    cellClass?: GridClassValue | ((ctx: GridCellStyleContext<TRow, TValue>) => GridClassValue);
+    /** Inline styles for the cells of this column. A function styles individual cells. */
+    cellStyle?: GridStyleValue | ((ctx: GridCellStyleContext<TRow, TValue>) => GridStyleValue | null | undefined);
+    /** CSS class(es) for the header cell. */
+    headerClass?: GridClassValue;
+    /** Inline styles for the header cell. */
+    headerStyle?: GridStyleValue;
+    /** Free-form data for your own templates. The grid never reads it. */
+    meta?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A column after the grid has merged it with the global configuration.
+ * Returned by the grid API and passed to every template context.
+ */
+export interface ResolvedColumn<TRow = any> {
+    readonly field: string;
+    readonly header: string;
+    readonly type: GridDataType;
+    /** Configured width. The current width after resizing is available from `api.getColumnWidth(field)`. */
+    readonly width: number;
+    readonly minWidth: number;
+    readonly maxWidth: number;
+    readonly align: GridCellAlign;
+    readonly hidden: boolean;
+    readonly resizable: boolean;
+    readonly sortable: boolean;
+    readonly filterable: boolean;
+    readonly editable: boolean | ((row: TRow) => boolean);
+    /** The field must have a value when a row is added or edited. */
+    readonly required: boolean;
+    readonly showSortIcon: boolean;
+    readonly sortIconVisibility: SortIconVisibility;
+    readonly showFilterIcon: boolean;
+    readonly filterIconVisibility: FilterIconVisibility;
+    readonly editor: GridEditorType;
+    readonly editorOptions: GridEditorOptions<TRow>;
+    readonly summary: ResolvedColumnSummary<TRow> | null;
+    readonly sort: ColumnSortConfig<TRow>;
+    readonly filter: ResolvedColumnFilter<TRow>;
+    readonly displayTemplate: GridTemplate<GridCellContext<TRow>> | null;
+    readonly editTemplate: GridTemplate<GridEditContext<TRow>> | null;
+    readonly headerTemplate: GridTemplate<GridHeaderContext<TRow>> | null;
+    readonly summaryTemplate: GridTemplate<GridSummaryCellContext<TRow>> | null;
+    readonly tooltipTemplate: GridTemplate<GridTooltipContext<TRow>> | null;
+    readonly headerTooltipTemplate: GridTemplate<GridHeaderTooltipContext<TRow>> | null;
+    /** Position of the column in the `columns` array. */
+    readonly index: number;
+    /** The original column configuration. */
+    readonly config: ColumnConfig<TRow>;
+    /** Reads this column's value from a row (field path or `valueGetter`). */
+    readonly getValue: (row: TRow) => any;
+    /** Writes a value into a row, or `null` when the column cannot be written. */
+    readonly setValue: ((row: TRow, value: any) => void) | null;
+    /** Formats a value the same way the default cell renderer does. */
+    readonly formatValue: (value: any, row?: TRow) => string;
+}