@reforgium/data-grid 1.0.3 → 2.0.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://badge.fury.io/js/%40reforgium%2Fdata-grid.svg)](https://www.npmjs.com/package/@reforgium/data-grid)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**High-performance data grid for Angular (20+).**
+**High-performance data grid for Angular (18+).**
 
 `@reforgium/data-grid` provides a flexible and performant component for displaying large tabular datasets.  
 It focuses on smooth scrolling, predictable layout, and full control over rendering via templates and signals.
@@ -18,13 +18,17 @@ Designed for **real-world datasets**, not demo tables.
 - Virtual row rendering (smooth, no jumps)
 - Infinity scroll (loads data when reaching the bottom)
 - Jitter-free fixed (sticky) columns
-- Two-line headers max, with ellipsis + tooltip
+- Two-line headers max, with ellipsis and tooltip
+- Declarative column DSL (`<re-dg-column>`) *[NEW in 2.0.0]*
 - Column expanders (hidden columns via toggler)
 - Scrollable overlay scrollbar
 - Pinned rows (top and bottom)
-- Custom templates for headers, cells, pinned rows
+- Custom templates for headers, cells, pinned rows, icons
+- Skeleton loading rows for pagination/infinity *[NEW in 2.0.0]*
 - Row selection (single / multi)
 - Signals-based API (`signal()` first)
+- Paginator component *[NEW in 1.1.0]*
+- Column manager dropdown *[NEW in 2.0.0]*
 
 ---
 
@@ -36,142 +40,545 @@ npm install @reforgium/data-grid
 
 ```ts
 import { DataGrid } from '@reforgium/data-grid';
+import { DataGridPaginator } from '@reforgium/data-grid/paginator';
+import { DataGridColumnManager } from '@reforgium/data-grid/column-manager';
 
-@Component({ imports: [DataGrid]})
-export class SomeComponent {}
+@Component({ imports: [DataGrid, DataGridPaginator] })
+export class SomeComponent {
+}
 ```
 
 ```html
+
 <re-data-grid
+  mode="infinity"
   [data]="users"
   [columns]="columns"
   [pageSize]="50"
   [loading]="loading"
-  (loadData)="loadMore($event)"
+  (pageChange)="loadMore($event)"
+/>
+```
+
+### Column manager
+
+Column manager is a secondary entrypoint that provides a dropdown UI for reordering, show/hide, and pinning columns.
+
+```ts
+import { DataGridColumnManager } from '@reforgium/data-grid/column-manager';
+```
+
+```html
+
+<re-data-grid-column-manager
+  triggerLabel="Columns"
+  [columns]="managedColumns()"
+  (columnsChange)="managedColumns.set($event)"
+/>
+
+<re-data-grid [columns]="managedColumns()" ... />
+```
+
+Custom trigger template:
+
+```html
+
+<ng-template #cmTrigger let-label let-visible="visible" let-total="total">
+  <span>{{ label }}</span>
+  <strong>{{ visible }}/{{ total }}</strong>
+</ng-template>
+
+<re-data-grid-column-manager
+  [columns]="managedColumns()"
+  [triggerTemplate]="cmTrigger"
+  (columnsChange)="managedColumns.set($event)"
 />
 ```
 
+Trigger template context:
+
+- `$implicit` — trigger label
+- `visible` — visible columns count
+- `total` — total columns count
+
+Inputs:
+
+- `columns: GridColumn<T>[]`
+- `triggerLabel?: string`
+- `triggerTemplate?: TemplateRef<{ $implicit: string; visible: number; total: number }>`
+- `controlsVisible?: boolean` — hides search and “show all / hide optional” panel
+- `searchable?: boolean`
+- `allowReorder?: boolean`
+- `allowPin?: boolean`
+- `allowVisibility?: boolean`
+
+Outputs:
+
+- `columnsChange: GridColumn<T>[]`
+
 ---
 
+## Migration notes (1.1.0 → 2.0.0)
+
+- **Column tooltips are now explicit.** Use `tooltip` on a column (string / function / `TemplateRef`) to show a popover on hover.
+- **New column manager entrypoint.** Import it from `@reforgium/data-grid/column-manager` and wire `columns` + `columnsChange`.
+- **Sticky columns use sides.** Prefer `sticky="left"` / `sticky="right"`; legacy `true` still maps to left.
+
 ## Configuration
 
+### Global defaults provider
+
+You can override default input values for all grid instances via DI:
+
+```ts
+import { provideDataGridDefaults } from '@reforgium/data-grid';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideDataGridDefaults({
+      mode: 'pagination',
+      hasIndexColumn: true,
+      pageSize: 50,
+    }),
+  ],
+};
+```
+
+Supported default fields:
+
+- `mode`
+- `hasIndexColumn`
+- `selection`
+- `pageSize`
+- `rowHeight`
+- `headerHeight`
+- `height`
+- `virtualBuffer`
+- `loadingMode`
+- `pageStartFromZero`
+- `translations`
+- `debounce`
+
 ### Inputs
 
-| Parameter         | Type                                         | Default     | Description                     |
-|-------------------|----------------------------------------------|-------------|---------------------------------|
-| data              | `T[]`                                        | `[]`        | Data array to render            |
-| columns           | `GridColumns<T>`                             | `[]`        | Column configuration            |
-| pinnedRows        | `GridPinnedRows<T>`                          | `undefined` | Top / bottom pinned rows        |
-| mode              | `'default' \| 'infinity' \| 'none'`          | `'default'` | Grid operation mode             |
-| pageSize          | `number`                                     | `20`        | Page size                       |
-| pageStartFromZero | `boolean`                                    | `false`     | Start page index from 0         |
-| hasIndexColumn    | `boolean`                                    | `false`     | Show index column               |
-| selection         | `{ mode: 'single' \| 'multi', key: string }` | `undefined` | Row selection configuration     |
-| fillHeight        | `boolean`                                    | `false`     | Fill available container height |
-| loading           | `boolean`                                    | `false`     | Loading state                   |
-| rowKey            | `(item: T) => string`                        | `undefined` | Unique row key resolver         |
+| Parameter         | Type                                             | Default            | Description                                                                                     |                  |
+|-------------------|--------------------------------------------------|--------------------|-------------------------------------------------------------------------------------------------|------------------|
+| data              | `T[]`                                            | `[]`               | Data array to render                                                                            |                  |
+| columns           | `GridColumn<T>[]`                                | `[]`               | Programmatic column configuration (used when no declarative columns are provided)               |                  |
+| headerGroups      | `GridHeaderGroup<T>[]`                           | `[]`               | Optional top header row groups (`from`..`to`) for 2-level headers                               | *[NEW in 2.0.0]* |
+| pinnedRows        | `GridPinnedRow<T>[]`                             | `[]`               | Top / bottom pinned rows                                                                        |                  |
+| isRowSticky       | `(row: T, index: number) => boolean`             | `undefined`        | Predicate that marks rows as sticky at the top                                                  |                  |
+| getRowTemplate    | `(row: T, index: number) => TemplateRef \| null` | `undefined`        | Optional resolver for custom row template                                                       |                  |
+| mode              | `'none' \| 'pagination' \| 'infinity'`           | `'pagination'`     | Grid operation mode                                                                             |                  |
+| pageSize          | `number`                                         | `20`               | Number of items per page (pagination/infinity modes)                                            |                  |
+| pageStartFromZero | `boolean`                                        | `true`             | If true, page indexing starts from 0, otherwise from 1                                          |                  |
+| hasIndexColumn    | `boolean`                                        | `false`            | If true, an index column will be shown                                                          |                  |
+| selection         | `GridSelection<T>`                               | `{ mode: 'none' }` | Row selection configuration                                                                     |                  |
+| rowHeight         | `number`                                         | `40`               | Fixed height of each row in pixels                                                              | *[FIX in 1.1.0]* |
+| virtualBuffer     | `number`                                         | `8`                | Extra rows to render above/below viewport to reduce flickering during scrolling                 |                  |
+| height            | `number \| 'full' \| 'default'`                  | `'default'`        | Grid height configuration (`number` for px, `'full'` for 100%, `'default'` for CSS variable)    |                  |
+| loading           | `boolean`                                        | `false`            | Displays loading state template when true                                                       |                  |
+| loadingMode       | `'spinner' \| 'skeleton'`                        | `'spinner'`        | Loading rendering mode (`spinner` shows centered spinner, `skeleton` enables row skeleton mode) | *[NEW in 2.0.0]* |
+| rowKey            | `DataKey<T> \| ((item: T) => string \| number)`  | `undefined`        | Property name or function to resolve unique row key                                             |                  |
+
+When selection mode is `'single'` or `'multi'`, provide a `key` (data property) and optionally `defaultSelected`.
+
+Loading behavior:
+
+- `loadingMode="spinner"`: shows centered spinner over grid content.
+- `loadingMode="skeleton"` + `mode="infinity"` + `loading=true`: appends 4 skeleton rows at the end of the current data.
+- `loadingMode="skeleton"` + `mode="pagination"` + `loading=true` + empty data: renders 4 skeleton rows in the table body.
+
+Sticky rows:
+
+- Provide `isRowSticky` to mark rows that should stick to the top during scroll.
+- You can customize the sticky row rendering with `reDataGridStickyRow` template.
+
+```html
+
+<re-data-grid [data]="items" [columns]="columns" [isRowSticky]="isSticky">
+  <ng-template reDataGridStickyRow let-row let-index="index">
+    <div class="my-sticky-row">{{ index + 1 }}. {{ row.name }}</div>
+  </ng-template>
+</re-data-grid>
+```
+
+Row templates:
+
+- Provide `getRowTemplate` to select a custom row template per row.
+- Use `reDataGridRow` as a default row template.
+
+```html
+
+<re-data-grid [data]="items" [columns]="columns" [getRowTemplate]="rowTpl">
+  <ng-template reDataGridRow let-index="index">
+    <div class="my-row">{{ index + 1 }}. {{ row.name }}</div>
+  </ng-template>
+</re-data-grid>
+```
 
 ### Outputs
 
-| Event        | Type                    | Description      |
-|--------------|-------------------------|------------------|
-| cellClick    | `GridCellClickEvent<T>` | Cell click       |
-| rowClick     | `GridRowClickEvent<T>`  | Row click        |
-| sortChange   | `GridSortEvent<T>`      | Sort change      |
-| pageChange   | `GridPageChangeEvent`   | Page change      |
-| selectChange | `GridSelectEvent<T>`    | Selection change |
+| Event           | Type                          | Description                                            |                  |
+|-----------------|-------------------------------|--------------------------------------------------------|------------------|
+| cellClick       | `GridCellClickEvent<T>`       | Emitted when a cell is clicked (includes native event) | *[UPD in 2.0.0]* |
+| cellContext     | `GridCellContextEvent<T>`     | Emitted on cell context menu                           | *[NEW in 2.0.0]* |
+| cellDoubleClick | `GridCellDoubleClickEvent<T>` | Emitted when a cell is double-clicked                  | *[NEW in 2.0.0]* |
+| rowClick        | `GridRowClickEvent<T>`        | Emitted when a row is clicked (includes native event)  | *[UPD in 2.0.0]* |
+| rowContext      | `GridRowContextEvent<T>`      | Emitted on row context menu                            | *[NEW in 2.0.0]* |
+| rowDoubleClick  | `GridRowDoubleClickEvent<T>`  | Emitted when a row is double-clicked                   | *[NEW in 2.0.0]* |
+| sortChange      | `GridSortEvent<T>`            | Emitted when sort order changes                        |                  |
+| pageChange      | `GridPageChangeEvent`         | Emitted when requesting data for a new page            |                  |
+| selectChange    | `GridSelectEvent<T>`          | Emitted when selected rows change                      |                  |
 
-### Templates
+Notes:
+
+- A cell click also triggers the row click event (bubbling), so listen to one or stop propagation if needed.
+
+### GridColumn<T> reference
+
+`columns` accepts `GridColumn<T>[]`, where `GridColumn<T>` is a union of three column variants:
+
+- default column (`type` + optional `typeParams`)
+- value column (`value` + required `track`)
+- template column (`renderTemplate` + required `track`)
+
+Common (base) fields:
 
-| Directive          | Parameters         | Description                            |
-|--------------------|--------------------|----------------------------------------|
-| reDataGridHeader   | value: string      | Column header template                 |
-| reDataGridTypeCell | value: any, row: T | Cell template for specific column type |
-| reDataGridEmpty    | -                  | Empty state template                   |
-| reDataGridLoading  | -                  | Loading state template                 |
+| Field                   | Type                                                            | Description                                                                     |
+|-------------------------|-----------------------------------------------------------------|---------------------------------------------------------------------------------|
+| `sortKey`               | `string`                                                        | Alternative key used for sorting when display `key` differs from sortable data. |
+| `sticky`                | `'left' \| 'right' \| true`                                     | Keeps the column fixed while horizontally scrolling. `true` pins to the left.   |
+| `expandBy`              | `DataKey<T>`                                                    | Data key that controls expand/collapse behavior for the column.                 |
+| `flex`                  | `number`                                                        | Flex grow factor for width distribution in flexible layouts.                    |
+| `minWidth` / `maxWidth` | `number`                                                        | Column width limits in pixels.                                                  |
+| `cellClass`             | `string \| ((row: T) => string)`                                | Static CSS class or resolver per row.                                           |
+| `tooltip`               | `string \| ((row: T) => string) \| TemplateRef<TooltipContext>` | Popover tooltip content shown on cell hover.                                    |
 
+Renderer-specific fields:
+
+| Variant           | Fields                                                                                                    | Notes                                                                                                 |
+|-------------------|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
+| Built-in renderer | `type?: 'plain' \| 'date' \| 'number' \| 'index' \| 'checkbox'`, `typeParams?: any`, `defaultValue?: any` | `defaultValue` is used when source value is `null`/`undefined`; `typeParams` passes formatter config. |
+| Value renderer    | `value: (row: T) => string \| number`, `track: (row: T) => string`                                        | `track` is required for stable row identity and efficient updates.                                    |
+| Template renderer | `renderTemplate: TemplateRef<...>`, `track: (row: T) => string`                                           | `track` is required when rendering through Angular templates.                                         |
+
+### Declarative columns *[NEW in 2.0.0]*
+
+You can define columns directly in markup via `<re-dg-column>`, then the grid will normalize them to `GridColumn<T>` internally.
+
+```html
+
+<re-data-grid [data]="items" [rowKey]="'id'">
+  <re-dg-column key="name">
+    <ng-template reHeader>Name</ng-template>
+    <ng-template reCell let-row="row">{{ row.name }}</ng-template>
+  </re-dg-column>
+
+  <re-dg-column key="age" sortKey="age">
+    <ng-template reHeader>Age</ng-template>
+    <ng-template reCell let-row="row">{{ row.age }}</ng-template>
+  </re-dg-column>
+
+  <re-dg-column key="extra" sticky="left" expandBy="age" disabled>
+    <ng-template reHeader>Extra</ng-template>
+    <ng-template reCell let-row="row">{{ row.extra }}</ng-template>
+  </re-dg-column>
+</re-data-grid>
+```
+
+Notes:
+
+- If at least one `<re-dg-column>` is present, declarative columns are used as the source of truth.
+- `reHeader` maps to `headerTemplate`.
+- `reCell` receives value as `$implicit`, and the row is available as `let-row="row"` via `RenderTemplateData`.
+- Most `GridColumn<T>` fields are available as `<re-dg-column>` inputs (`sortKey`, `sticky`, `expandBy`, `disabled`, `width`, `minWidth`, `maxWidth`, `flex`, `align`, `cellClass`, `type`, `typeParams`, `defaultValue`, `value`, `track`, `tooltip`).
+- `sticky` accepts `'left' | 'right'`; legacy `true` maps to `'left'` for backward compatibility.
+
+### Tooltip
+
+`tooltip` is opt-in per column and shows a popover on cell hover.
+
+```ts
+columns = [
+  { key: 'email', header: 'Email', tooltip: (row) => row.email },
+  { key: 'status', header: 'Status', tooltip: 'User status' },
+];
+```
+
+Template tooltip:
+
+```html
+
+<ng-template #tip let-row let-col="col" let-index="index" let-value="value">
+  <div><b>{{ col.header }}</b> #{{ index + 1 }}</div>
+  <div>{{ value }}</div>
+</ng-template>
+
+<re-dg-column key="email" [tooltip]="tip"></re-dg-column>
+```
+
+Tooltip template context (`TooltipContext`):
+
+- `$implicit` / `row`
+- `col`
+- `index`
+- `value`
+
+### GridHeaderGroup<T> reference
+
+#### NEW in 2.0.0
+
+Use `headerGroups` to render an optional top header row (2-level header layout) above regular column headers.
+
+| Field           | Type                              | Description                                                      |
+|-----------------|-----------------------------------|------------------------------------------------------------------|
+| `key`           | `string`                          | Unique id of the header group.                                   |
+| `from`          | `DataKey<T>`                      | Start column key (inclusive).                                    |
+| `to`            | `DataKey<T>`                      | End column key (inclusive). If omitted, group covers one column. |
+| `title`         | `string`                          | Plain text title for the group.                                  |
+| `titleTemplate` | `TemplateRef<HeaderTemplateData>` | Template-based title for the group.                              |
+| `align`         | `'left' \| 'center' \| 'right'`   | Optional group title alignment (plain title variant).            |
+
+Notes:
+
+- Groups are normalized against visible columns only.
+- Overlapping or invalid ranges are ignored during normalization.
+- Columns not covered by groups are automatically placed into technical spacer groups to keep width alignment.
+
+### Templates
+
+| Directive              | Parameters                        | Description                                       |                  |
+|------------------------|-----------------------------------|---------------------------------------------------|------------------|
+| reHeader               | -                                 | Declarative header template inside `re-dg-column` | *[NEW in 2.0.0]* |
+| reCell                 | let-row                           | Declarative cell template inside `re-dg-column`   | *[NEW in 2.0.0]* |
+| reDataGridHeader       | key: string                       | Template for specific column header by key        |                  |
+| reDataGridCell         | key: string                       | Template for specific column cell by key          | *[NEW in 1.1.0]* |
+| reDataGridTypeCell     | type: string                      | Template for cells of a specific column type      |                  |
+| reDataGridEmpty        | -                                 | Template for the empty state (no data)            |                  |
+| reDataGridLoading      | -                                 | Template for the loading state                    |                  |
+| reDataGridSortIcon     | order: GridSortOrder \| undefined | Template for custom sorting icon                  | *[NEW in 1.1.0]* |
+| reDataGridExpanderIcon | expanded: boolean                 | Template for custom expander icon                 | *[NEW in 1.1.0]* |
 
 ### CSS Variables
 
 Layout / Appearance:
-- `--re-data-grid-height` — component height / max-height (`400px`).
-- `--re-data-grid-rounded` — border radius (`var(--radius-md, 6px)`).
-- `--re-data-grid-surface` — table background (`#fff`).
-- `--re-data-grid-active` — active color (`#2a90f4`).
+
+- `--re-data-grid-min-height` - component min height (`200px`)
+- `--re-data-grid-height` - component height (`400px`)
+- `--re-data-grid-rounded` - border radius (`var(--radius-md, 6px)`)
+- `--re-data-grid-separator-color` - outer border color (`var(--border-color)`)
+- `--re-data-grid-separator` - outer border (`1px solid var(--re-data-grid-separator-color)`)
+- `--re-data-grid-surface` - table background (`#fff`)
+- `--re-data-grid-active` - active color (`#2a90f4`)
 
 Empty / Loading States:
-- `--re-data-grid-empty-color` — empty text color (`#777`)
-- `--re-data-grid-loading-color` — loading indicator color (`#444`)
-- `--re-data-grid-loading-surface` — loading overlay (`rgba(255,255,255,0.5)`)
+
+- `--re-data-grid-empty-color` - empty text color (`#777`)
+- `--re-data-grid-empty-surface` - empty text background (`transparent`)
+- `--re-data-grid-loading-color` - loading indicator color (`#444`)
+- `--re-data-grid-loading-surface` - loading spinner (`rgba(255,255,255,0.5)`)
+- `--re-data-grid-spinner-size` - spinner size (`2rem`)
+- `--re-data-grid-spinner-width` - spinner ring thickness (`0.25rem`)
+- `--re-data-grid-spinner-track` - spinner track color (`rgba(0, 0, 0, 0.12)`)
+- `--re-data-grid-skeleton-width` - skeleton line width (`100%`)
+- `--re-data-grid-skeleton-height` - skeleton line height (`100%`)
+- `--re-data-grid-skeleton-rounded` - skeleton border radius (`var(--re-data-grid-rounded, 0.75rem)`)
+- `--re-data-grid-skeleton-line` - skeleton base color (`#e7ebf0`)
+- `--re-data-grid-skeleton-shine` - skeleton highlight color (`rgba(255, 255, 255, 0.8)`)
+
+Note: for `--re-data-grid-skeleton-height` it's usually better to use percentages (for example `60%` / `70%`) so the line scales naturally with row height.
 
 Scrollbar:
-- `--re-data-grid-scrollbar-size` — track size (`10px`)
-- `--re-data-grid-scrollbar-offset` — inner offset (`2px`)
-- `--re-data-grid-scrollbar-thumb-size` — thumb size (`8px`)
-- `--re-data-grid-scrollbar-thumb-color` — thumb color (`rgba(0,0,0,0.35)`)
-- `--re-data-grid-scrollbar-thumb-rounded` — thumb radius (`4px`)
+
+- `--re-data-grid-scrollbar-size` - track size (`4px`)
+- `--re-data-grid-scrollbar-offset` - inner offset (`2px`)
+- `--re-data-grid-scrollbar-track-rounded` - track radius (`0.25rem`)
+- `--re-data-grid-scrollbar-track-surface` - track surface (`transparent`)
+- `--re-data-grid-scrollbar-thumb-size` - thumb size (`8px`)
+- `--re-data-grid-scrollbar-thumb-color` - thumb color (`rgba(0,0,0,0.25)`)
+- `--re-data-grid-scrollbar-thumb-active-color` - thumb active color (`rgba(0,0,0,0.45)`)
+- `--re-data-grid-scrollbar-thumb-rounded` - thumb radius (`var(--re-data-grid-scrollbar-track-rounded)`)
 
 Header:
-- `--re-data-grid-header-height` — header row height (`40px`)
-- `--re-data-grid-header-separator-color` — separator color (`#ccc`)
-- `--re-data-grid-header-separator` — separator line
-- `--re-data-grid-header-surface` — header background (`#fff`)
+
+- `--re-data-grid-header-surface` - header area background (`#fff`)
+- `--re-data-grid-header-row-height` - main header row height (`40px`)
+- `--re-data-grid-header-row-separator-color` - main header separator color (`#ccc`)
+- `--re-data-grid-header-row-separator` - main header separator (`1px solid var(--re-data-grid-header-row-separator-color)`)
+- `--re-data-grid-header-group-row-height` - group header row height (`var(--re-data-grid-header-row-height)`)
+- `--re-data-grid-header-group-row-separator-color` - group header separator color (`var(--re-data-grid-header-row-separator-color)`)
+- `--re-data-grid-header-group-row-separator` - group header separator (`1px solid var(--re-data-grid-header-group-row-separator-color)`)
 
 Header Cells:
 
-- `--re-data-grid-header-cell-font-weight` — font weight; `600`.
-- `--re-data-grid-header-cell-font-size` — font size; `0.8rem`.
-- `--re-data-grid-header-cell-color` — text color; `#000`.
-- `--re-data-grid-header-cell-surface` — cell background; `#fafafa`.
+- `--re-data-grid-header-cell-font-weight` - font weight (`600`)
+- `--re-data-grid-header-cell-font-size` - font size (`0.8rem`)
+- `--re-data-grid-header-cell-color` - text color (`#000`)
+- `--re-data-grid-header-cell-surface` - cell background (`#fafafa`)
+- `--re-data-grid-header-group-cell-font-weight` - group font weight (`var(--re-data-grid-header-cell-font-weight)`)
+- `--re-data-grid-header-group-cell-font-size` - group font size (`var(--re-data-grid-header-cell-font-size)`)
+- `--re-data-grid-header-group-cell-color` - group text color (`var(--re-data-grid-header-cell-color)`)
+- `--re-data-grid-header-group-cell-surface` - group cell background (`var(--re-data-grid-header-cell-surface)`)
 
 Footer:
 
-- `--re-data-grid-footer-separator-color` — separator color; `#ccc`.
-- `--re-data-grid-footer-separator` — separator line; `1px solid var(--re-data-grid-footer-separator-color)`.
-- `--re-data-grid-footer-surface` — footer background; `#fff`.
+- `--re-data-grid-footer-separator-color` - separator color (`#ccc`)
+- `--re-data-grid-footer-separator` - separator line (`1px solid var(--re-data-grid-footer-separator-color)`)
+- `--re-data-grid-footer-surface` - footer background (`#fff`)
 
 Rows:
 
-- `--re-data-grid-row-separator-color` — row separator color; `#bbb`.
-- `--re-data-grid-row-separator` — separator line; `1px solid var(--re-data-grid-row-separator-color)`.
-- `--re-data-grid-row-odd-surface` — odd rows background; `var(--re-data-grid-cell-surface)`.
+- `--re-data-grid-row-separator-color` - row separator color (`#bbb`)
+- `--re-data-grid-row-separator` - separator line (`1px solid var(--re-data-grid-row-separator-color)`)
+- `--re-data-grid-row-odd-surface` - odd rows background (`var(--re-data-grid-cell-surface)`)
 
 Columns:
-- `--re-data-grid-column-separator-color` — column divider color `transparent`.
-- `--re-data-grid-column-separator` — column divider `1px solid var(--re-data-grid-column-separator-color)`.
-- `--re-data-grid-column-odd-surface` — odd column background `var(--re-data-grid-cell-surface)`.
+
+- `--re-data-grid-column-separator-color` - column divider color (`transparent`)
+- `--re-data-grid-column-separator` - column divider (`1px solid var(--re-data-grid-column-separator-color)`)
+- `--re-data-grid-column-odd-surface` - odd column background (`var(--re-data-grid-cell-surface)`)
 
 Cells:
 
-- `--re-data-grid-cell-paddings` — inner paddings; `0.4rem 0.625rem`.
-- `--re-data-grid-cell-font-weight` — font weight; `400`.
-- `--re-data-grid-cell-font-size` — font size; `0.75rem`.
-- `--re-data-grid-cell-color` — text color; `#000`.
-- `--re-data-grid-cell-surface` — cell background; `#fff`.
+- `--re-data-grid-cell-paddings` - inner paddings (`0.4rem 0.625rem`)
+- `--re-data-grid-cell-font-weight` - font weight (`400`)
+- `--re-data-grid-cell-font-size` - font size (`0.75rem`)
+- `--re-data-grid-cell-color` - text color (`#000`)
+- `--re-data-grid-cell-surface` - cell background (`#fff`)
 
 Sticky Cells:
 
-- `--re-data-grid-sticky-cell-surface` — sticky cells background; `#fdfdfd`.
-- `--re-data-grid-sticky-cell-left-shadow` — left shadow; `2px 0 2px rgba(0, 0, 0, 0.03)`.
-- `--re-data-grid-sticky-cell-right-shadow` — right shadow; `-2px 0 2px rgba(0, 0, 0, 0.03)`.
+- `--re-data-grid-sticky-header-cell-surface` - sticky header cell background (`#fff`)
+- `--re-data-grid-sticky-cell-surface` - sticky body cell background (`#fdfdfd`)
+- `--re-data-grid-sticky-cell-left-shadow` - left shadow (`2px 0 2px rgba(0,0,0,0.03)`)
+- `--re-data-grid-sticky-cell-right-shadow` - right shadow (`-2px 0 2px rgba(0,0,0,0.03)`)
 
 Pinned Sections:
 
-- `--re-data-grid-pinned-surface` — pinned sections background; `#fcfcfc`.
-- `--re-data-grid-pinned-separator-color` — separator color; `#eee`.
-- `--re-data-grid-pinned-separator` — separator line; `1px solid var(--re-data-grid-pinned-separator-color)`.
+- `--re-data-grid-pinned-surface` - pinned sections background (`#fcfcfc`)
+- `--re-data-grid-pinned-separator-color` - separator color (`#eee`)
+- `--re-data-grid-pinned-separator` - separator line (`1px solid var(--re-data-grid-pinned-separator-color)`)
 
 Misc:
 
-- `--re-data-grid-expander-color` — expander indicator color; `var(--primary-color, currentColor)`.
+- `--re-data-grid-expander-color` - expander indicator color (`var(--primary-color, currentColor)`)
+- `--re-data-grid-expanded-color` - expanded column color (`var(--re-data-grid-cell-color, #000)`)
+- `--re-data-grid-expanded-surface` - expanded column background (`var(--re-data-grid-cell-surface, #fff)`)
+
+---
+
+## Paginator *[NEW in 1.1.0]*
+
+The paginator component is used to display a page selector and total count.
+
+### Inputs
+
+| Parameter       | Type       | Default           | Description                            |
+|-----------------|------------|-------------------|----------------------------------------|
+| current         | `number`   | 0                 | Current page                           |
+| pageSize        | `number`   | 0                 | Number of items per page               |
+| totalElements   | `number`   | 0                 | Total number of elements               |
+| maxShowPages    | `number`   | 7                 | Maximum number of page buttons to show |
+| showFirstLast   | `boolean`  | `false`           | Show "First" and "Last" buttons        |
+| showPerPage     | `boolean`  | `false`           | Show page-size dropdown                |
+| pageSizeOptions | `number[]` | `[10,20,50,100]`  | Options for per-page dropdown          |
+| perPageLabel    | `string`   | `Items per page:` | Label near dropdown                    |
+| firstLabel      | `string`   | `First`           | Fallback label for first-page button   |
+| lastLabel       | `string`   | `Last`            | Fallback label for last-page button    |
+
+### Outputs
+
+| Event          | Type     | Description                                                          |
+|----------------|----------|----------------------------------------------------------------------|
+| pageChange     | `number` | Emitted when the page changes. Returns the new page index (0-based). |
+| pageSizeChange | `number` | Emitted when per-page value changes.                                 |
+
+### Paginator templates
+
+You can customize first/last controls with `ng-template`:
 
-## Theming via CSS Variables
+```html
+
+<re-data-grid-paginator
+  showFirstLast
+  showPerPage
+  [current]="page"
+  [pageSize]="20"
+  [pageSizeOptions]="[10, 20, 50]"
+  [totalElements]="total"
+  (pageChange)="page = $event"
+  (pageSizeChange)="pageSize = $event"
+>
+  <ng-template reDataGridPaginatorFirst let-targetPage let-disabled="disabled">
+    <span [style.opacity]="disabled ? 0.5 : 1">&lt;&lt; First</span>
+  </ng-template>
+
+  <ng-template reDataGridPaginatorPage let-label="label" let-active="active">
+    <span [style.fontWeight]="active ? 700 : 400">{{ label }}</span>
+  </ng-template>
+
+  <ng-template reDataGridPaginatorLast let-targetPage let-disabled="disabled">
+    <span [style.opacity]="disabled ? 0.5 : 1">Last &gt;&gt;</span>
+  </ng-template>
+</re-data-grid-paginator>
+```
+
+Template contexts:
+
+- `reDataGridPaginatorFirst` / `reDataGridPaginatorLast`: `$implicit` (target page), `current`, `total`, `disabled`
+- `reDataGridPaginatorPage`: `$implicit` / `page` (0-based index), `label` (1-based display), `current`, `total`, `active`
+
+### CSS Variables
+
+First / Last controls:
+
+- `--re-data-grid-paginator-edge-min-width` - min width (`2.5rem`)
+- `--re-data-grid-paginator-edge-height` - control height (`var(--re-data-grid-paginator-page-size)`)
+- `--re-data-grid-paginator-edge-paddings` - control paddings (`0 0.625rem`)
+- `--re-data-grid-paginator-edge-border` - control border (`var(--re-data-grid-paginator-page-border)`)
+- `--re-data-grid-paginator-edge-rounded` - control border radius (`var(--re-data-grid-paginator-page-rounded)`)
+- `--re-data-grid-paginator-edge-surface` - control background (`var(--re-data-grid-paginator-page-surface)`)
+- `--re-data-grid-paginator-edge-color` - control text color (`var(--re-data-grid-paginator-page-color)`)
+- `--re-data-grid-paginator-edge-font-size` - control font size (`var(--re-data-grid-paginator-page-font-size)`)
+- `--re-data-grid-paginator-edge-hover-surface` - hover background (`var(--re-data-grid-paginator-page-hover-surface)`)
+- `--re-data-grid-paginator-edge-hover-color` - hover text color (`var(--re-data-grid-paginator-page-hover-color)`)
+- `--re-data-grid-paginator-edge-disabled-opacity` - disabled opacity (`0.5`)
+
+Layout:
+
+- `--re-data-grid-paginator-gap` - gap between paginator elements (`0.5rem`)
+
+Page:
+
+- `--re-data-grid-paginator-page-size` - page button size (`1.75rem`)
+- `--re-data-grid-paginator-page-border` - page button border (`1px solid var(--re-data-grid-paginator-separator-color, #e2e8f0)`)
+- `--re-data-grid-paginator-page-separator-color` - page button border color (`var(--re-data-grid-separator-color, --border-color)`)
+- `--re-data-grid-paginator-page-rounded` - page button border radius (`var(--re-data-grid-rounded, --radius-md)`)
+- `--re-data-grid-paginator-page-surface` - page button background (`var(--re-data-grid-surface, white)`)
+- `--re-data-grid-paginator-page-color` - page button text color (`var(--text-primary, #1e293b)`)
+- `--re-data-grid-paginator-page-font-size` - page button font size (`0.875rem`)
+
+Active Page:
+
+- `--re-data-grid-paginator-page-active-surface` - active page button background (`var(--re-data-grid-active, #3b82f6)`)
+- `--re-data-grid-paginator-page-active-color` - active page button text color (`white`)
+
+Hover Page:
+
+- `--re-data-grid-paginator-page-hover-surface` - page button hover background (`var(--re-data-grid-active, #3b82f6)`)
+- `--re-data-grid-paginator-page-hover-color` - page button hover text color (`white`)
+
+---
+
+### Theming via CSS Variables
 
 Variables can be overridden globally (`:root`) or per grid container.
 
 ### Quick Theming Examples
 
 Dark Theme Example:
+
 ```css
 .dark .data-grid {
   --re-data-grid-surface: #121416;
@@ -183,28 +590,42 @@ Dark Theme Example:
 ```
 
 Compact Mode Example:
+
 ```css
 .compact-grid {
-  --re-data-grid-header-height: 32px;
+  --re-data-grid-header-row-height: 32px;
   --re-data-grid-cell-font-size: 12px;
   --re-data-grid-cell-paddings: 2px 8px;
 }
 ```
 
-## Custom Template Examples
+### Custom Template Examples
 
 Cell Template by Type
+
 ```html
-<ng-template reDataGridTypeCell type="link" let-value let-row="row">
+
+<ng-template reDataGridTypeCell="link" let-row="row">
   <a [href]="value" target="_blank">{{ value }}</a>
 </ng-template>
 ```
 
+Cell Template *[NEW in 1.1.0]*
+
+```html
+
+<ng-template reDataGridCell="fullName" let-row="row">
+  <span><b>{{ row.firstName }}</b> {{ row.lastName }}</span>
+</ng-template>
+```
+
 Custom Header Template:
+
 ```html
-<ng-template reDataGridHeader key="name" let-value>
+
+<ng-template reDataGridHeader="name" let-value="value">
   <span class="header-with-icon">
-    <re-icon name="user"></re-icon>
+    <icon name="user" size="20" />
     {{ value }}
   </span>
 </ng-template>
@@ -212,11 +633,11 @@ Custom Header Template:
 
 ## Compatibility
 
-- Angular: 20+
+- Angular: 18+
 - Rendering: ESM
 - Signals: required
 - Zone.js: optional
-  
 
 ## License
+
 MIT