@thkl/agrid 0.1.11 → 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,14 +82,119 @@ be dragged.
 `confirmRowDelete` protects grid delete actions with a localized in-row Yes/No confirmation.
 Direct calls to `AgridDataSource.removeRow()` remain immediate.
 
-`enableRowMarking` adds a checkbox to each control cell. Marked rows are included in keyboard,
-cell-context, and row-context copy operations. Read `grid.markedRowIndices()` or call
+`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
+keyboard, cell-context, and row-context copy operations. Read `grid.markedRowIndices()` or call
 `grid.clearMarkedRows()` when the host needs to inspect or reset the copy basket.
 
 Marking is independent from row selection. Cell and range copy use the same copied columns for
 every marked row, while Copy row uses every visible column. Duplicate rows are omitted, and marked
 rows remain included when filters hide them.
 
+Selecting numeric cells displays a live status bar with count, sum, average, minimum, and maximum.
+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)`.
+
+Append custom commands to one column's menu and handle them through one typed output:
+
+```ts
+{ field: 'status', header: 'Status', headerMenuItems: [
+  { key: 'archive', label: 'Archive', icon: '⌂' },
+] }
+```
+
+```html
+<agrid [provider]="provider" (columnHeaderAction)="onColumnHeaderAction($event)" />
+```
+
+The event contains `{ column, key }`.
+
+Use `(firstDataRendered)` when host logic must wait until the grid has completed its first render
+containing datasource rows:
+
+```html
+<agrid [provider]="provider" (firstDataRendered)="onGridReady($event)" />
+```
+
+The event fires once per grid component. An initially empty datasource delays it until rows arrive.
+Server-side loading placeholders do not count as rendered data. The payload contains `rows`,
+`rowCount`, `provider`, and `datasource`.
+
+For commands that change `textAlign` at runtime, keep the writable signal in the host instead of
+mutating `event.column`:
+
+```ts
+readonly salaryAlignment = signal<'left' | 'center' | 'right'>('right');
+
+// Column definition
+{ field: 'salary', header: 'Salary', textAlign: this.salaryAlignment }
+
+onColumnHeaderAction(event: ColumnHeaderActionEvent<Employee>): void {
+  if (event.column.field !== 'salary') return;
+  if (event.key === 'align-left') this.salaryAlignment.set('left');
+  if (event.key === 'align-center') this.salaryAlignment.set('center');
+  if (event.key === 'align-right') this.salaryAlignment.set('right');
+}
+```
+
+Assigning `event.column.textAlign = 'center'` mutates plain configuration and does not trigger an
+Angular update. Calling `.set()` on `event.column.textAlign` is also not type-safe because the
+property may contain a static string or a read-only signal.
+
 ## Menu bar
 
 Set `menuBarItems` to render command buttons above the headers. An item with `items` becomes a
@@ -112,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
@@ -171,6 +289,10 @@ does not include. Numbers offer `=`, `≠`, `>`, `≥`, `<`, `≤`, and `between
 before / after / between. Conditions combine with the header text filter, value picker, and other
 columns using AND semantics, and are included in `AgridControl.toJSON()` state.
 
+The header arrow opens the complete column menu. The condition button beside the inline filter
+opens only the condition operator and operand controls; sorting, layout, grouping, custom commands,
+clear-all actions, and distinct-value selection remain in the complete menu.
+
 ```ts
 const columns: ColDef<Order>[] = [
   { field: 'reference', header: 'Reference', filterable: true },
@@ -219,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"
@@ -237,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
@@ -316,6 +463,14 @@ tree.
 Tree mode can be combined with `masterDetail: true` and a `detailRenderer`. Detail expanders are
 shown only for leaf rows; parent rows retain their tree expand/collapse control.
 
+Set `detailColumnField` to a column field when the panel should expose one larger multiline value.
+The formatted value is shown normally; click it or focus it and press Enter to open a textarea.
+Blur or Ctrl/Cmd+Enter commits, while Escape cancels. Editability, validation, history, and edit
+events follow the linked column's normal cell behavior.
+Set `detailActions` to add text-template buttons above the textarea. Each action has an `id`,
+`label`, and optional `text` string or row-aware resolver; clicking inserts at the current
+selection, or appends if the button opens the textarea.
+
 ## Standalone tree control
 
 Use `<agrid-tree>` for the same parent-ID or path hierarchy without grid columns. It adds tree
@@ -453,7 +608,8 @@ Use `rowChanged` to send one request after the user edits one or more fields in
 ```ts
 saveRow(event: RowUpdateEvent<Person>): void {
   this.http.patch(`/api/people/${event.row.id}`, event.row).subscribe(() => {
-    this.grid()?.clearChangedCells(event.originalIndex);
+    this.provider.control.indicate(event.originalIndex, '#2da44e', 1000);
+    this.provider.control.clearChangedCells(event.originalIndex);
   });
 }
 ```
@@ -461,6 +617,8 @@ saveRow(event: RowUpdateEvent<Person>): void {
 The event fires with the latest complete row when inline navigation leaves that row, or when the
 sidebar editor Save button is used. `cellEdit` and `recordEdit` remain available for every committed
 field change. With `showChangedCellIndicator: true`, changed cells keep a corner marker until the
-PATCH succeeds. Override `--agrid-color-cell-changed` to customize its color.
+PATCH succeeds. Override `--agrid-color-cell-changed` to customize its color. Call
+`control.indicate(index, color, durationMs)` to flash a complete row for transient server-side
+feedback.
 
 Full documentation and demos: https://thkl.github.io/agrid/