@thkl/agrid 0.1.7 → 0.1.10

package/README.md

@@ -30,7 +30,12 @@ interface Person {
 
 const columns: ColDef<Person>[] = [
   { field: 'id', header: 'ID', editable: false },
-  { field: 'name', header: 'Name', filterable: true },
+  {
+    field: 'name',
+    header: 'Name',
+    filterable: true,
+    infoIcon: ({ row }) => Boolean(row.name),
+  },
 ];
 
 @Component({
@@ -55,6 +60,10 @@ export class PeopleComponent {
 }
 ```
 
+Set `infoIcon: true` to show a right-aligned `?` action for every cell in a
+column, or use a predicate to enable it per row. Listen to `(cellInfo)` to
+receive the row, field, value, original row index, and column definition.
+
 Set `group: 'employee'` on adjacent columns to render the `Employee` label above them. Dragging
 that grouped header moves its current contiguous column segment as one block. Reordering, hiding,
 or pinning may split one group ID into multiple headers. Segments containing locked columns cannot
@@ -71,6 +80,59 @@ 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.
 
+## Menu bar
+
+Set `menuBarItems` to render command buttons above the headers. An item with `items` becomes a
+split button: its label emits the parent id and its chevron opens additional commands. Every
+command emits through the single `(menuBarAction)` output.
+
+```ts
+readonly provider = new AgridProvider<Person>({
+  columns,
+  datasource,
+  menuBarItems: [
+    { id: 'refresh', label: 'Refresh', icon: '↻' },
+    {
+      id: 'selection',
+      label: 'Selection',
+      disabled: ({ selectedRows }) => selectedRows.length === 0,
+      items: [
+        { id: 'activate', label: 'Activate' },
+        { id: 'deactivate', label: 'Deactivate', active: ({ rows }) => rows.some(row => !row.active) },
+      ],
+    },
+  ],
+});
+```
+
+```html
+<agrid [provider]="provider" (menuBarAction)="runCommand($event)" />
+```
+
+`visible`, `active`, and `disabled` may be booleans or callbacks. Callback context includes
+`rows`, `selectedRows`, `selectedCell`, `provider`, and `datasource`.
+
+## Input masks
+
+Use `inputMask` to select a string mask for each row and cell. The callback
+receives `{ row, value, column }`; return `null` for cells that should remain
+unrestricted.
+
+```ts
+{
+  field: 'reference',
+  header: 'Reference',
+  inputMask: ({ row }) =>
+    row.numeric
+      ? /\d{0,3}(?:-\d{0,5}(?:-\d{0,5})?)?/
+      : /[a-z0-9]{0,3}(?: [a-z0-9]{0,3}(?: [a-z0-9]{0,5})?)?/i,
+}
+```
+
+The regex is matched against the complete proposed value and must allow
+partial input. Separators are typed explicitly rather than inserted
+automatically. Invalid edits revert to the last accepted value.
+
 ## Boolean columns
 
 Set `type: 'boolean'` to render a cell as an inline checkbox. Clicking it toggles the value and
@@ -85,22 +147,41 @@ const columns: ColDef<Person>[] = [
 ];
 ```
 
-## Typed filters
+## Runtime readonly cells
 
-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.
+Use `cellReadonly` when editability depends on the current row. Returning `true` blocks inline
+editing, boolean toggles, paste, fill, and sidebar edits for that cell.
 
 ```ts
 const columns: ColDef<Order>[] = [
+  { field: 'status', header: 'Status' },
+  {
+    field: 'approvedBy',
+    header: 'Approved by',
+    cellReadonly: ({ row }) => row.status !== 'Draft',
+  },
+];
+```
+
+## Condition filters
+
+Mark a column `filterable: true` and its column menu gains a **condition** filter in addition to
+the value picker. Text columns offer equals, not equal, like, starts with, ends with, includes, and
+does not include. Numbers offer `=`, `≠`, `>`, `≥`, `<`, `≤`, and `between`; dates offer on /
+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.
+
+```ts
+const columns: ColDef<Order>[] = [
+  { field: 'reference', header: 'Reference', filterable: true },
   { 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).
+`operator` can also be `'like' | 'startsWith' | 'endsWith' | 'includes' | 'notIncludes'` for text
+columns (pass `null` to clear). `like` uses `%` for any sequence and `_` for one character.
 
 ## Edit validation
 
@@ -143,7 +224,7 @@ cleared by `control.clearAllFilters()`.
 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
+- `(filterChange)` — header text filters emit `{ field, value }`; menu conditions emit
   `{ field, value: '', operator, operand, operand2 }` (operator `null` clears the condition).
 - `(sortChange)` — `{ field, direction }`.
 - `(quickFilterChange)` — the quick-filter text (debounced by `filterDebounceMs`).
@@ -179,9 +260,8 @@ one aggregated column are both active.
 
 ## Tree data
 
-Pass `treeConfig` to render rows as a hierarchical tree. The hierarchy lives on the flat row
-array via stable `id` / `parentId` accessors, so there are no nested `children` arrays and
-selection and editing keep working on the same indices.
+Pass `treeConfig` to render rows as a hierarchical tree. Use stable `id` / `parentId` accessors
+for an existing hierarchy, or `getPath` to generate display-only branches from each row.
 
 ```ts
 import { AgridTreeConfig } from '@thkl/agrid';
@@ -199,12 +279,90 @@ readonly provider = new AgridProvider<OrgRow>({
 });
 ```
 
+For path-like values such as `01.01.0001`, return the ordered segments:
+
+```ts
+const treeConfig: AgridTreeConfig<Row> = {
+  getPath: row => row.oz.split('.'),
+  nodeUuid: row => row.uuid,
+  formatPathSegment: ({ row, segment, level, leaf }) =>
+    leaf
+      ? `${segment} ${row.description}`
+      : `${segment} ${level === 0 ? row.areaLabel : row.groupLabel}`,
+  treeField: 'oz',
+};
+```
+
+This renders `01 / 01 / 0001, 0002`. Generated `01` branch rows are display-only; the leaf remains
+the original datasource row. Its tree cell displays `0001`, while editing still uses the complete
+`01.01.0001` value. `formatPathSegment` changes labels only; raw segments still control grouping,
+expansion identity, and sort order. The callback receives the original `row`; shared branch nodes
+use the first row encountered for that raw path prefix. `nodeUuid` uses the same source row and is
+included in generated branch-node click events.
+
 The `treeField` column shows an indented expand/collapse twisty. Filtering and sorting behave as
 in a flat grid; with `keepAncestorsOnFilter` (default `true`) a match deep in the tree keeps its
 parents visible and force-opens the path to it. Tree mode takes precedence over grouping and
 disables pagination. Call `grid.expandAllNodes()` / `grid.collapseAllNodes()` to toggle the whole
 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.
+
+## 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.
+
+```ts
+readonly treeProvider = new AgridTreeProvider<OrgRow>({
+  datasource: new AgridDataSource(rows),
+  treeConfig: {
+    getId: row => row.id,
+    getParentId: row => row.parentId,
+    treeField: 'name',
+    defaultExpanded: true,
+  },
+  getDescription: row => row.role,
+  selection: 'single',
+  ariaLabel: 'Organization',
+});
+```
+
+```html
+<agrid-tree [provider]="treeProvider"
+  (nodeClick)="openNode($event)"
+  (nodeDoubleClicked)="openNode($event)"
+  (selectionChange)="selectionChanged($event)" />
+```
+
+Row and generated path-branch clicks emit `AgridTreeNodeEvent<T>`. Branch events include their
+configured or generated `uuid`. `expandAllNodes()` and `collapseAllNodes()` are public methods.
+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.
+
+## Page selector
+
+Use `<agrid-page-selector>` to navigate pages by previous/next button, dropdown, or typed ID.
+All three interactions emit an `AgridPageItem<TId>` through the single `(selectPage)` output.
+
+```ts
+readonly pages: AgridPageItem<number>[] = [
+  { id: 1, label: 'Cover' },
+  { id: 2, label: 'Measurements' },
+  { id: 3, label: 'Summary' },
+];
+```
+
+```html
+<agrid-page-selector [items]="pages" [selectedId]="currentPageId()"
+  (selectPage)="currentPageId.set($event.id)" />
+```
+
+IDs can be strings or numbers. Typed IDs are selected with Enter. Available inputs are
+`disabled`, `previousLabel`, `nextLabel`, `inputLabel`, `menuLabel`, and `emptyText`.
+
 ## Saving edited rows
 
 Use `rowChanged` to send one request after the user edits one or more fields in a row: