@thkl/agrid 0.1.5 → 0.1.7

package/README.md

@@ -71,6 +71,112 @@ Marking is independent from row selection. Cell and range copy use the same copi
 every marked row, while Copy row uses every visible column. Duplicate rows are omitted, and marked
 rows remain included when filters hide them.
 
+## Boolean columns
+
+Set `type: 'boolean'` to render a cell as an inline checkbox. Clicking it toggles the value and
+commits immediately — no edit mode, and the change is recorded in undo/redo like any other edit.
+Read-only columns (`editable: false`) or a read-only grid render the checkbox disabled. Values are
+truthy-coerced for display, so `true`, `1`, `'true'`, and `'1'` all render as checked.
+
+```ts
+const columns: ColDef<Person>[] = [
+  { field: 'name', header: 'Name' },
+  { field: 'active', header: 'Active', type: 'boolean' },
+];
+```
+
+## Typed filters
+
+Mark a `number` or `date` column `filterable: true` and its column menu gains a **condition**
+filter in addition to the value picker. Numbers offer `=`, `≠`, `>`, `≥`, `<`, `≤`, and `between`;
+dates offer on / before / after / between. The condition combines with the value picker and other
+columns using AND semantics, and is included in `AgridControl.toJSON()` state.
+
+```ts
+const columns: ColDef<Order>[] = [
+  { field: 'total', header: 'Total', type: 'number', filterable: true },
+  { field: 'placedAt', header: 'Placed', type: 'date', filterable: true },
+];
+```
+
+Set it programmatically with `control.setRangeFilter(field, operator, operand, operand2?)`, where
+`operator` is one of `'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'between'` (pass `null` to clear).
+
+## Edit validation
+
+Add a `validate` hook to a column to reject bad values. Return a message to block the edit (the
+value is not written and the message is shown), or `null` to accept it. It runs on inline commit,
+boolean-checkbox toggle, and sidebar save.
+
+```ts
+const columns: ColDef<Person>[] = [
+  { field: 'email', header: 'Email',
+    validate: v => /@/.test(String(v)) ? null : 'Enter a valid email' },
+  { field: 'age', header: 'Age', type: 'number',
+    validate: (v, row) => Number(v) >= 0 ? null : 'Age must be ≥ 0' },
+];
+```
+
+A rejected inline edit keeps the cell in edit mode with the message shown beneath it, so the user
+can correct it; Tab/Enter won't leave the cell until the value is valid. Rejected sidebar edits show
+the message under the field. Listen to `(validationFailed)` for `{ rowIndex, field, value, message,
+source }` (`source` is `'inline'` or `'sidebar'`).
+
+```html
+<agrid [provider]="provider" (validationFailed)="onInvalid($event)" />
+```
+
+## Quick filter
+
+Set `enableQuickFilter: true` to render a search box above the grid that keeps rows whose visible
+columns contain the text (resolved display values, so `ValueOption` labels and formatters count).
+
+```ts
+readonly provider = new AgridProvider<Person>({ columns, datasource, enableQuickFilter: true });
+```
+
+Drive it programmatically with `control.setQuickFilter(text)`; it's part of `toJSON()` state and is
+cleared by `control.clearAllFilters()`.
+
+## Server-side filtering
+
+With `serverSideFiltering: true` the grid never filters locally — it emits events so the host can
+refetch:
+
+- `(filterChange)` — text filters emit `{ field, value }`; typed range conditions emit
+  `{ field, value: '', operator, operand, operand2 }` (operator `null` clears the condition).
+- `(sortChange)` — `{ field, direction }`.
+- `(quickFilterChange)` — the quick-filter text (debounced by `filterDebounceMs`).
+
+```html
+<agrid [provider]="provider"
+  (filterChange)="onFilter($event)"
+  (sortChange)="onSort($event)"
+  (quickFilterChange)="onQuickFilter($event)" />
+```
+
+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.
+
+## Grouping and aggregates
+
+Give a column an `aggregate` (`'sum'`, `'avg'`, `'min'`, `'max'`, `'count'`, or a custom
+`(values) => unknown` function) and the grid renders a footer row with that column's total over all
+filtered rows. Set/clear it at runtime with `control.setAggregate(field, fn)`.
+
+```ts
+const columns: ColDef<Order>[] = [
+  { field: 'region', header: 'Region', groupable: true },
+  { field: 'total', header: 'Total', type: 'number', aggregate: 'sum' },
+];
+```
+
+When the grid is grouped (set `groupable: true` and group from the column menu, or call
+`control.setGroupBy(field)`), each **group header row also shows that group's subtotals** —
+the same aggregate functions applied to just the group's rows, displayed inline beside the group
+label and count. No extra configuration is needed; subtotals appear whenever grouping and at least
+one aggregated column are both active.
+
 ## Tree data
 
 Pass `treeConfig` to render rows as a hierarchical tree. The hierarchy lives on the flat row