@thkl/agrid 0.1.12 → 0.1.14

package/README.md

@@ -1,8 +1,8 @@
 # @thkl/agrid
 
-A signal-based, standalone data grid for Angular 21 with virtual scrolling, editing,
+A signal-based, standalone data grid for Angular 21 and 22 with virtual scrolling, editing,
 filtering, sorting, grouping, tree data, pinned columns, selection, clipboard operations,
-and pagination.
+pagination, and linked SVG charts/graphs.
 
 ## Install
 
@@ -10,6 +10,16 @@ and pagination.
 npm install @thkl/agrid @angular/cdk
 ```
 
+## Feature Highlights
+
+- Virtual rows and virtual columns for large and wide datasets.
+- Text, value, quick, and condition filters with local or server-side workflows.
+- Inline editing, validation, undo/redo, paste, fill, custom editors, and custom renderers.
+- Range selection, selection summaries, row selection, row marking, column marking, and row numbers.
+- Grouping, aggregate footers, tree data with descendant rollups, pivot tables, and master/detail rows.
+- Pinned columns, pinned rows, column reordering, column autosize, and persistable settings.
+- CSV, zero-dependency `.xlsx` export, sparklines, and linked SVG charts/graphs.
+
 ## Usage
 
 ```ts
@@ -72,6 +82,10 @@ be dragged.
 `confirmRowDelete` protects grid delete actions with a localized in-row Yes/No confirmation.
 Direct calls to `AgridDataSource.removeRow()` remain immediate.
 
+`showRowNumbers` displays 1-based row numbers in the control column for the current filtered and
+sorted row order. When row reordering is enabled, the number replaces the drag-handle glyph while
+the control cell remains draggable.
+
 `enableRowMarking` makes each control-cell row header clickable and adds a checkbox. Clicking the
 header outside its nested controls toggles the same mark state and emits `(rowMark)` with the row,
 its original datasource index, and the resulting `marked` state. Marked rows are included in
@@ -86,6 +100,52 @@ Selecting numeric cells displays a live status bar with count, sum, average, min
 Read the same values from `grid.selectionSummary()`. The signal is `null` when the active selection
 contains no finite numeric values.
 
+## Charts / Graphs
+
+Use `AgridChartComponent` with an `AgridChartProvider` to render zero-dependency SVG graphs. The
+same provider pattern as the grid keeps setup predictable:
+
+```ts
+import { AgridChartComponent, AgridChartProvider } from '@thkl/agrid';
+
+readonly chartProvider = new AgridChartProvider({
+  type: 'column',
+  data: {
+    categories: ['Q1', 'Q2', 'Q3', 'Q4'],
+    series: [
+      { name: 'North', values: [120, 145, 138, 162] },
+      { name: 'South', values: [98, 110, 134, 128] },
+    ],
+  },
+  height: 300,
+});
+```
+
+```html
+<agrid-chart [provider]="chartProvider" />
+```
+
+Supported `type` values are `column`, `bar`, `line`, `area`, `pie`, and `donut`. `type`, `height`,
+`showLegend`, `showAxis`, and `palette` are signals, so runtime changes redraw immediately.
+
+To link a graph to a grid, pass `provider.visibleRows` as `source` and provide a `transform`. The
+chart follows filtering, sorting, and edits live:
+
+```ts
+readonly chartProvider = new AgridChartProvider<Person>({
+  type: 'bar',
+  source: this.provider.visibleRows,
+  transform: rows => ({
+    categories: rows.map(row => row.name),
+    series: [{ name: 'Score', values: rows.map(row => Number(row.score ?? 0)) }],
+  }),
+});
+```
+
+`visibleRows` is the filtered and sorted row set. It intentionally ignores grouping and pagination;
+aggregate inside `transform` when the graph should show grouped totals or page-specific summaries.
+Pie and donut graphs use the first series and label slices from `categories`.
+
 Set `enableColumnMarking: true` to toggle complete-column highlighting by clicking a header outside
 its menu and resize controls. The grid exposes `markedColumnFields()` and emits `(columnMark)`.
 
@@ -167,6 +227,9 @@ readonly provider = new AgridProvider<Person>({
 `visible`, `active`, and `disabled` may be booleans or callbacks. Callback context includes
 `rows`, `selectedRows`, `selectedCell`, `provider`, and `datasource`.
 
+For imperative selection reads, call `grid.getCurrentRow()` or `grid.getCurrentCell()`. The
+`(cellSelect)` output emits the same selected-cell shape and `null` when cell selection clears.
+
 ## Input masks
 
 Use `inputMask` to select a string mask for each row and cell. The callback
@@ -278,15 +341,40 @@ readonly provider = new AgridProvider<Person>({ columns, datasource, enableQuick
 Drive it programmatically with `control.setQuickFilter(text)`; it's part of `toJSON()` state and is
 cleared by `control.clearAllFilters()`.
 
+Use `control.getFilterModel()` and `control.setFilterModel(model)` to persist or restore just the
+filter, quick-filter, and sort state without the rest of the grid settings.
+
+Rows inserted while filters or sorts are active stay visible in insertion order even if their values
+do not currently match. Wire `control.reapplyFilters()` to a button or save action when those
+inserted rows should be filtered and sorted like the rest of the datasource again. Use
+`control.filterReapplyNeeded()` to show visual feedback when that action is available.
+
 ## Server-side filtering
 
-With `serverSideFiltering: true` the grid never filters locally — it emits events so the host can
-refetch:
+With `serverSideFiltering: true` the grid never filters locally. The recommended integration point
+is the complete query snapshot:
+
+```html
+<agrid [provider]="provider" (serverQueryChange)="loadRows($event)" />
+```
+
+```ts
+effect(() => {
+  const query = provider.serverQuery();
+  if (!query) return;
+  store.load(query);
+});
+```
+
+`AgridServerQuery` contains column filters, value selections, menu conditions, ordered sorts,
+quick-filter text, and page range (`startRow..endRow`, inclusive). The older granular outputs remain
+available for compatibility:
 
-- `(filterChange)` — header text filters emit `{ field, value }`; menu conditions emit
+- `(filterChange)` — header text filters emit `{ field, value }`; value filters emit
+  `{ field, value: '', selectedValues }`; menu conditions emit
   `{ field, value: '', operator, operand, operand2 }` (operator `null` clears the condition).
 - `(sortChange)` — `{ field, direction }`.
-- `(quickFilterChange)` — the quick-filter text (debounced by `filterDebounceMs`).
+- `(quickFilterChange)` — the quick-filter text.
 
 ```html
 <agrid [provider]="provider"
@@ -296,7 +384,7 @@ refetch:
 ```
 
 Text/range/quick events are debounced by `filterDebounceMs` (default 300 ms; `0` disables). The
-The distinct-value picker is hidden in this mode unless the column supplies an explicit `values`
+distinct-value picker is hidden in this mode unless the column supplies an explicit `values`
 list representing the complete server-side value set.
 
 ## Grouping and aggregates