@thkl/agrid 0.1.10 → 0.1.12

package/README.md

@@ -72,14 +72,69 @@ 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
+`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.
+
+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
@@ -171,6 +226,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 },
@@ -237,7 +296,8 @@ refetch:
 ```
 
 Text/range/quick events are debounced by `filterDebounceMs` (default 300 ms; `0` disables). The
-Excel-style value picker stays client-only and is hidden in this mode.
+The 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
 
@@ -270,6 +330,7 @@ const treeConfig: AgridTreeConfig<OrgRow> = {
   getId: row => row.id,
   getParentId: row => row.parentId, // null / unknown id ⇒ root row
   treeField: 'name',                // column that shows the twisty
+  aggregateTreeNodes: true,         // parent cells roll up descendant leaves
 };
 
 readonly provider = new AgridProvider<OrgRow>({
@@ -279,6 +340,11 @@ readonly provider = new AgridProvider<OrgRow>({
 });
 ```
 
+With `aggregateTreeNodes: true`, every expandable row displays descendant-leaf rollups in columns
+that define `aggregate` (or have one set through `AgridControl`). For example,
+`{ field: 'amount', aggregate: 'sum' }` shows the sum of a node's leaves in that node's amount cell.
+Collapsed leaves still contribute. Filtering recalculates the rollups over the matching tree.
+
 For path-like values such as `01.01.0001`, return the ordered segments:
 
 ```ts
@@ -309,10 +375,19 @@ 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
-keyboard navigation and optional single or multi-selection.
+keyboard navigation and optional single or multi-selection. Since this component has no columns,
+it ignores `aggregateTreeNodes`; descendant rollups apply only to tree mode in `<agrid>`.
 
 ```ts
 readonly treeProvider = new AgridTreeProvider<OrgRow>({
@@ -342,6 +417,77 @@ The tree uses the shared `--agrid-color-text`, `--agrid-color-text-muted`,
 `--agrid-color-accent`, `--agrid-color-accent-subtle`, `--agrid-color-accent-fg`,
 `--agrid-color-border`, `--agrid-color-bg`, and `--agrid-color-bg-muted` CSS variables.
 
+## Pivot tables
+
+Use `pivotConfig` to derive a read-only client-side cross-tabulation from a flat datasource. The
+first pivot release supports one row dimension, one column dimension, and one value field.
+
+```ts
+const provider = new AgridProvider<Sale>({
+  columns: [
+    { field: 'region', header: 'Region' },
+    { field: 'quarter', header: 'Quarter' },
+    { field: 'revenue', header: 'Revenue', type: 'number', formatter: currency },
+  ],
+  datasource: new AgridDataSource(sales),
+  pivotConfig: {
+    rowField: 'region',
+    columnField: 'quarter',
+    valueField: 'revenue',
+    aggregate: 'sum',
+  },
+});
+```
+
+Each distinct `rowField` value becomes one row and each distinct `columnField` value becomes a
+generated column. Intersections use `sum` by default and also support `avg`, `min`, `max`, `count`,
+or a custom `(values) => result` function. Dimension labels and pivot values reuse source column
+formatters. Missing intersections render empty.
+
+Pivot rows react to datasource replacement and updates. They are derived values, so editing,
+adding, reordering, master/detail, tree mode, server-side row models, and aggregate footers are
+disabled or rejected in pivot mode. Client-side filtering, sorting, selection, and pagination
+continue through the normal grid pipeline. Multi-level dimensions and totals are intentionally
+outside this first slice.
+
+When `showSidebar` is enabled, pivot grids add a **Pivot** sidebar tab. It updates `rowField`,
+`columnField`, `valueField`, and built-in aggregate functions immediately without replacing the
+provider. Assigning `provider.pivotConfig` programmatically uses the same reactive path.
+
+### Saving and restoring settings
+
+`saveSettings()` returns a detached, versioned object containing the pivot configuration and the
+existing control state (column visibility, width, order, pinning, filters, sorts, pagination, and
+aggregates). It is safe to JSON-encode and send to a backend. `loadSettings()` applies it to an
+already-rendered grid immediately.
+
+```ts
+const settings = provider.saveSettings();
+await api.saveGridSettings(settings);
+
+const restored = await api.loadGridSettings();
+provider.loadSettings(restored);
+```
+
+The component exposes the same methods through `viewChild(AgridComponent)`. Sidebar pivot and
+column-visibility changes emit the complete snapshot through `(settingsChange)`:
+
+```html
+<agrid #grid [provider]="provider" (settingsChange)="saveSettings($event)" />
+```
+
+```ts
+saveSettings(settings: AgridSettings): void {
+  void api.saveGridSettings(settings);
+}
+
+// Loading after the grid exists:
+grid().loadSettings(savedSettings);
+```
+
+Custom aggregate functions are executable code and cannot be represented in JSON; attempting to
+save one throws an explicit error. Register custom functions in application code instead.
+
 ## Page selector
 
 Use `<agrid-page-selector>` to navigate pages by previous/next button, dropdown, or typed ID.
@@ -374,7 +520,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);
   });
 }
 ```
@@ -382,6 +529,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/