laif-ds 1.0.5 → 1.1.0

package/dist/agent-docs/components/AppDataGrid/dom-hooks.md

@@ -0,0 +1,75 @@
+# AppDataGrid — DOM hooks
+
+> Part of the [AppDataGrid](../AppDataGrid.md) docs. The Props table and the `onQueryChange` payload are in the main file.
+
+## DOM hooks (for tests)
+
+Stable attributes, independent of the i18n language.
+
+| Selector / attribute                        | Meaning                                                                                                  |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `[data-app-data-grid]`                      | Grid root.                                                                                               |
+| `data-emissions` (root)                     | Query emissions: `0` at mount, +1 per emission, unchanged by view actions. Debounced: read in `waitFor`. |
+| `data-render-count` (root)                  | React commits of the root since mount.                                                                   |
+| `data-mount-count` (root)                   | Mounts of a grid with this `id` / `data-testid` (stays `1` across full-screen toggles).                  |
+| `data-loadmore-call-count` (root)           | Load-more requests issued (infinite mode).                                                               |
+| `data-grid-fullscreen` (root)               | `"true"` / `"false"`.                                                                                    |
+| `[data-grid-toolbar]`                       | Toolbar.                                                                                                 |
+| `[data-grid-search]`                        | Search input.                                                                                            |
+| `[data-grid-viewport]`                      | Scroll container; its `clientHeight` equals `viewportHeight`.                                            |
+| `[data-grid-table]`                         | The `<table>`.                                                                                           |
+| `[data-grid-col="<id>"]`                    | `<col>` of a column — count columns with this (the extra layout col is `[data-grid-col-filler]`).        |
+| `[data-grid-header="<id>"]`                 | Leaf `<th>` (`aria-sort`).                                                                               |
+| `[data-grid-header-group="<id>"]`           | Group `<th>` (`scope="colgroup"`).                                                                       |
+| `[data-grid-header-row="<n>"]`              | Header `<tr>`, 0-based.                                                                                  |
+| `[data-grid-sort="<id>"]`                   | Sort button.                                                                                             |
+| `[data-grid-sort-index]`                    | Multi-sort priority badge.                                                                               |
+| `[data-grid-resize-handle="<id>"]`          | Resize handle (`aria-valuenow` = width).                                                                 |
+| `[data-grid-row]`                           | Data row, never a spacer. Use `querySelector` for the first one (the first `<tr>` may be a spacer).      |
+| `[data-grid-cell="<id>"]`                   | Body cell.                                                                                               |
+| `[data-grid-row-header]`                    | Row-header cell (`<th scope="row">`).                                                                    |
+| `[data-grid-spacer]`                        | Virtualization spacer rows.                                                                              |
+| `[data-grid-skeleton-row]`                  | Skeleton row (`aria-hidden`).                                                                            |
+| `[data-grid-pinned="true"]`                 | Pinned cell (either side).                                                                               |
+| `[data-grid-cell-text]`                     | Text cell that fits.                                                                                     |
+| `[data-grid-cell-expand]`                   | Focusable target of a truncated text cell.                                                               |
+| `[data-grid-row-menu]`                      | Row-menu trigger.                                                                                        |
+| `[data-grid-row-menu-item="<id>"]`          | Row-menu item (`data-variant="destructive"` when destructive).                                           |
+| `[data-grid-live-region]`                   | The single status region.                                                                                |
+| `[data-grid-empty]`                         | Empty-outcome cell.                                                                                      |
+| `[data-grid-error]`                         | Error-outcome cell.                                                                                      |
+| `[data-grid-status-cell]`                   | The outcome cell, empty or error.                                                                        |
+| `[data-grid-retry]`                         | Retry button (absent without `onRetry`).                                                                 |
+| `[data-grid-footer]`                        | Totals `<tfoot>`.                                                                                        |
+| `[data-grid-footer-cell="<id>"]`            | Footer cell.                                                                                             |
+| `[data-grid-pagination]`                    | Paginator.                                                                                               |
+| `[data-grid-page-range]`                    | «Rows x-y of N».                                                                                         |
+| `[data-grid-page-number="<n>"]`             | Page button (1-based; current one has `aria-current="page"`).                                            |
+| `[data-grid-page-size]`                     | Wrapper of the page-size selector.                                                                       |
+| `tr[data-grid-filter-row]`                  | Filter row (absent while hidden).                                                                        |
+| `[data-grid-filter-cell="<id>"]`            | Filter cell.                                                                                             |
+| `[data-grid-filter-cell-trigger="<id>"]`    | Filter cell's button.                                                                                    |
+| `[data-grid-header-filtered="<id>"]`        | Funnel on a filtered column's header.                                                                    |
+| `[data-grid-toolbar-filter-row-toggle]`     | Filter-row toggle.                                                                                       |
+| `[data-grid-toolbar-columns]`               | Columns-panel trigger.                                                                                   |
+| `[data-grid-fullscreen-toggle]`             | Full-screen toggle.                                                                                      |
+| `[data-grid-actions-row]`                   | Container of the `actions` prop buttons.                                                                 |
+| `[data-grid-action="<label>"]`              | One `actions` command.                                                                                   |
+| `[data-grid-actions-trigger]`               | Collapsed trigger (two or more actions).                                                                 |
+| `[data-grid-group-row="<path>"]`            | Group row (`aria-expanded`).                                                                             |
+| `[data-grid-group-toggle="<path>"]`         | Group expand/collapse control.                                                                           |
+| `[data-grid-group-count]`                   | Group row count — read the attribute (the text has parentheses).                                         |
+| `[data-grid-group-select="<path>"]`         | Group checkbox.                                                                                          |
+| `[data-grid-select-all]`                    | Header checkbox.                                                                                         |
+| `[data-grid-selection-bar]`                 | Selection bar.                                                                                           |
+| `[data-grid-selection-count]`               | Selected count.                                                                                          |
+| `[data-grid-selection-action="<label>"]`    | Bulk action.                                                                                             |
+| `[data-grid-toolbar-custom-filters]`        | Toolbar group of custom filters.                                                                         |
+| `[data-grid-toolbar-custom-filter="<id>"]`  | One custom filter (by badge id).                                                                         |
+| `[data-grid-filter-chip-trigger="<id>"]`    | A chip in `GridFilterChips`.                                                                             |
+| `[data-grid-filter-add-chip]`               | «+ Filter» chip.                                                                                         |
+| `[data-grid-filter-scope]`                  | Chips' scope clause.                                                                                     |
+| `[data-grid-column-registry-item="<id>"]`   | Columns-panel row.                                                                                       |
+| `[data-grid-column-registry-toggle="<id>"]` | Columns-panel visibility checkbox.                                                                       |
+
+---

package/dist/agent-docs/components/AppDataGrid/examples.md

@@ -0,0 +1,129 @@
+# AppDataGrid — Examples
+
+> Part of the [AppDataGrid](../AppDataGrid.md) docs. The Props table and the `onQueryChange` payload are in the main file.
+
+## Examples
+
+### Server grid with `onQueryChange`
+
+```tsx
+import { useState } from "react";
+import {
+  AppDataGrid,
+  type GridColumnNode,
+  type GridServerState,
+} from "laif-ds";
+
+const initialQuery: GridServerState = {
+  pagination: { pageIndex: 0, pageSize: 25 },
+};
+
+export const UsersGrid = ({ columns }: { columns: GridColumnNode<User>[] }) => {
+  // The grid does not emit at mount: the initial query is fetched by the consumer.
+  const [query, setQuery] = useState<GridServerState>(initialQuery);
+  const { data, isLoading, isError, refetch } = useUsersSearch(query); // your data hook
+
+  return (
+    <AppDataGrid
+      columns={columns}
+      data={data?.items ?? []}
+      getRowId={(row) => String(row.id)}
+      serverMode
+      paginated
+      serverConfig={{ totalItems: data?.total ?? 0, onStateChange: setQuery }}
+      loading={isLoading}
+      error={isError}
+      onRetry={() => void refetch()}
+    />
+  );
+};
+// In useUsersSearch, send query.computedFilter, query.computedSorting and query.pagination.
+```
+
+### Grouping with aggregates
+
+```tsx
+const columns: GridColumnNode<Sale>[] = [
+  createGridStringColumn<Sale>({ accessorKey: "country", header: "Country" }),
+  createGridStringColumn<Sale>({ accessorKey: "city", header: "City" }),
+  createGridNumberColumn<Sale, number>({
+    accessorKey: "amount",
+    header: "Amount",
+    align: "right",
+    aggregatedCell: (rows) => rows.reduce((sum, r) => sum + r.amount, 0),
+    aggregate: (rows) => rows.reduce((sum, r) => sum + r.amount, 0),
+  }),
+];
+
+<AppDataGrid
+  columns={columns}
+  data={sales}
+  groupBy={["country", "city"]}
+  initialOpenGroups="first"
+  groupLabelPlacement="first-column"
+  viewportHeight={520}
+/>;
+```
+
+### Lifted filters with chips and the filter row
+
+```tsx
+import { useMemo, useState } from "react";
+import {
+  AppDataGrid,
+  GridFilterChips,
+  gridResultScope,
+  gridViewportHeight,
+  toGridFilterColumns,
+  useGridFilters,
+} from "laif-ds";
+
+export const OrdersPage = ({ orders }: { orders: Order[] }) => {
+  const filters = useGridFilters({ columns: toGridFilterColumns(columns) });
+  const [filterRowOpen, setFilterRowOpen] = useState(true); // the row starts open
+
+  // With lifted filters the consumer filters the rows (client) or sends
+  // filters.computedFilter to the server.
+  const visibleOrders = useMemo(
+    () => applyMyFilters(orders, filters.committedBadges),
+    [orders, filters.committedBadges],
+  );
+
+  return (
+    <>
+      <GridFilterChips
+        badges={filters.badges}
+        onRemove={filters.removeBadge}
+        onClearAll={filters.clearBadges}
+        scope={gridResultScope({
+          badges: filters.badges,
+          resultTotal: visibleOrders.length,
+        })}
+      />
+      <AppDataGrid
+        columns={columns}
+        data={visibleOrders}
+        resultTotal={visibleOrders.length}
+        filters={filters.badges}
+        columnVisibility={filters.columnVisibility}
+        onColumnVisibilityChange={(next) => {
+          for (const [id, visible] of Object.entries(next))
+            if (filters.columnVisibility[id] !== visible)
+              filters.setColumnVisible(id, visible);
+        }}
+        onAddFilter={filters.addBadge}
+        onUpdateFilter={filters.updateBadge}
+        onRemoveFilter={filters.removeBadge}
+        onFilterRowOpenChange={setFilterRowOpen}
+        viewportHeight={gridViewportHeight({
+          rowCount: 10,
+          density: "default",
+          hasFilterRow: filterRowOpen,
+        })}
+      />
+    </>
+  );
+};
+```
+
+---

package/dist/agent-docs/components/AppDataGrid/filtering.md

@@ -0,0 +1,126 @@
+# AppDataGrid — Filtering
+
+> Part of the [AppDataGrid](../AppDataGrid.md) docs. The Props table and the `onQueryChange` payload are in the main file.
+
+## Filtering
+
+### Global search
+
+The search field filters rows (client) or feeds `filters.searchbarFilter` and `computedFilter` (server).
+Only columns with `searchable: true` are matched. Keystrokes are debounced by `debounceTime`.
+
+### Filter row (default, `filterMode="row"`)
+
+A row inside `<thead>` with one filter cell per column (plus the checkbox column). Each cell is a button
+that opens an editor popover; the editor and its operators are derived from the column's `filterType`:
+text field, number field, boolean, date / date-time picker, single or multi list (from `options`). A
+list column without options is shown as an incomplete declaration, never as a free text field. Cells of
+filtered columns get an accent border; filtered headers show a funnel icon. The toolbar toggle unmounts
+and remounts the row.
+
+Without lifted `filters`, the grid owns the filter state and (on the client branch) filters `data`
+itself. Client-side matching reproduces the backend operators (`like`, `starts_with`, `eq`,
+`array_overlap`, `date_after`, …), with edge-case differences a client cannot replicate (database
+collation/case folding of non-ASCII text, `citext` columns, decimal precision). `%` and `_` in text
+filters behave as `LIKE` wildcards, as on the server.
+
+Operators (`GridFilterOperator`): `like`, `n_like`, `starts_with`, `ends_with`, `eq`, `ne`, `eq_null`,
+`n_eq_null`, `gt`, `ge`, `lt`, `le`, `checked`, `unchecked`, `date_after`, `date_before`,
+`date_time_after`, `date_time_before`, `array_overlap`, `n_array_overlap`. A range is expressed as two
+badges (e.g. `ge` + `le`).
+
+### Lifted filters (`useGridFilters`)
+
+Lift the filter state when chips, counts or a server fetch live outside the grid. The hook owns the
+badges; the grid, `GridFilterChips` and `GridFilterPanel` read/write the same store, and the chips work
+without a grid in the tree.
+
+```ts
+const filters = useGridFilters({
+  columns: toGridFilterColumns(leafColumns), // required, for pruning
+  initialBadges, // optional
+  initialColumnVisibility, // optional
+  debounceTime, // optional, default 200
+  onFiltersChange: (computedFilter) => refetch(computedFilter), // optional
+});
+```
+
+`GridFiltersApi`: `badges` (live, feed the grid and editors), `committedBadges` (debounced, use them to
+filter rows), `computedFilter`, `columnVisibility`, `panelOpen`, `emissions`, `addBadge`, `addBadges`
+(several in one mutation — use for ranges), `updateBadge`, `removeBadge`, `removeBadges`, `clearBadges`,
+`restore(badges, columnVisibility)`, `setColumnVisible(id, visible)`, `setPanelOpen(open)`.
+
+Rules when `filters` is passed to the grid:
+
+- **You filter the rows.** The grid does not apply lifted badges to `data`. On the client, filter with
+  `committedBadges`; on the server, send `filters.computedFilter` (or the value received by
+  `onFiltersChange`).
+- **The grid does not emit for them** (except in infinite mode, below). `onFiltersChange` is called
+  synchronously inside the hook's actions (keystrokes coalesced by the hook's `debounceTime`; adding,
+  removing and restoring are immediate), and only when the payload actually changes.
+- **Pagination resets to page 0** when the badges' content changes (compared by content, so an inline
+  `filters={badges.filter(...)}` is fine).
+- Wire `onAddFilter={filters.addBadge}`, `onUpdateFilter={filters.updateBadge}` and
+  `onRemoveFilter={filters.removeBadge}`; pass `columnVisibility={filters.columnVisibility}` with
+  `onColumnVisibilityChange` so hidden columns also prune their badges.
+
+#### Infinite mode restarts on its own
+
+With `infinite` on (and `paginated` off), a change in the content of lifted `filters` makes the grid
+emit **one** `onQueryChange` with `pageIndex: 0`; later load-mores ask for 1, 2, …. Keystrokes into an
+existing badge coalesce into one restart. It never fires at mount, and a change that matches the last
+emission (e.g. the `restore()` after a preset) does not restart. Recommended wiring in infinite mode:
+do **not** also refetch in `onFiltersChange`; if you do, treat `pageIndex: 0` as a replace and drop
+superseded responses.
+
+### Filter chips, panel and columns panel
+
+- `GridFilterChips` — `{ badges, onRemove, onClearAll?, scope?, onAddFilter?, onEditValue?, i18n?,
+className? }`. A row of chips (one button per badge with an edit/remove menu), an optional dashed «+
+  Filter» chip, and a scope clause («128 rows · 2 filters») when `scope` is passed. Build `scope` with
+  `gridResultScope({ badges, resultTotal, rowsInPage?, pageIndex?, pageSize?, locale? })`.
+- `GridFilterPanel` — the filter inventory overlay used by `filterMode="panel"`; see
+  [GridFilterPanel](./GridFilterPanel.md). Mount it inside the grid through `toolbar.filters.render`,
+  otherwise it is covered in full screen.
+- `GridColumnRegistryPanel` — the standalone columns panel (`columns`, `columnVisibility`,
+  `onColumnVisibleChange`, `columnOrder?`, `onColumnOrderChange?`, `i18n?`, `className?`). The grid
+  already renders one behind `toolbar.columns`.
+
+### Custom filters (without a column)
+
+A filter that cites no column («only favourites», «older than N days») is declared once as a
+`GridFilterControl` and enters the state as a badge with `kind: "custom"`. It is counted, cleared by
+reset, appended to `computedFilter`, and never pruned by column visibility.
+
+```tsx
+import {
+  createGridCustomFilterBadge,
+  defaultGridI18n,
+  type GridFilterControl,
+  type GridFilterControlRegistry,
+} from "laif-ds";
+
+const olderThan: GridFilterControl = {
+  type: "olderThan", // registry key
+  Control: ({ value, onChange, label }) => (
+    <DaysInput value={value} onChange={onChange} label={label} />
+  ), // rendered by YOUR app, not by the grid
+  toFragment: (value, ctx) => ({ [ctx.field]: { operator: "ge", value } }), // null = not applied
+  describe: (value) => `Older than ${String(value)} days`, // the only text source
+};
+const registry: GridFilterControlRegistry = { olderThan };
+
+filters.addBadge(
+  createGridCustomFilterBadge(olderThan, 30, defaultGridI18n, "older"),
+);
+// To change the value: rebuild with the SAME id and call filters.updateBadge("older", badge).
+```
+
+`toFragment` and `describe` are both mandatory. `createGridCustomFilterBadge(control, value, i18n, id)`
+is the only constructor; it fills `kind`, `customKey`, `customLabel` and `customFragment`. With lifted
+`filters` and `onRemoveFilter`, the toolbar shows a dashed group with each custom filter's full name and
+a remove button; chips show `customLabel`. Pass `filterControls={registry}` to flag badges whose key is
+not registered. The grid never renders `Control`: custom filters are named and removable in the grid,
+edited where your app creates them.
+
+---

package/dist/agent-docs/components/AppDataGrid/grouping.md

@@ -0,0 +1,20 @@
+# AppDataGrid — Grouping
+
+> Part of the [AppDataGrid](../AppDataGrid.md) docs. The Props table and the `onQueryChange` payload are in the main file.
+
+## Grouping
+
+Client branch only. Each `groupBy` entry is one level; group rows show label, chevron and count
+(`data-grid-group-count`), and one cell per visible column filled by that column's `aggregatedCell`.
+
+- Groups are ordered by first appearance (i.e. by the current sort), not alphabetically.
+- Expanding is view state and never emits. Opening or closing a group above the viewport keeps what you
+  are reading in place; closing a group you are reading inside lands on the group row.
+- Hiding the grouping column does not ungroup: the label moves to the first visible column.
+- A grouped grid always has a bounded viewport (`viewportHeight`, default 480).
+- `aria-rowcount` counts the traversable rows — data rows plus the group rows on screen — so it changes
+  as groups open and close.
+- The `<tfoot>` total (`aggregate`) sums the data rows, not the group aggregates.
+- Group-row checkboxes select every leaf of the group, even when it is collapsed.
+
+---

package/dist/agent-docs/components/AppDataGrid/i18n-and-accessibility.md

@@ -0,0 +1,40 @@
+# AppDataGrid — i18n and accessibility
+
+> Part of the [AppDataGrid](../AppDataGrid.md) docs. The Props table and the `onQueryChange` payload are in the main file.
+
+## i18n
+
+`GridI18n` is a superset of `DataTableI18n`. Required top-level keys: `search`, `searchPlaceholder`,
+`clearSearch`, `reset`, `notFoundMessage`, `searchTooltipLabel`, `selectAll`, `selectRow`, and the
+sections `filters`, `stringOperators`, `numberOperators`, `booleanOperators`, `dateOperators`,
+`dateTimeOperators`, `listOperators`, `sorting`, `columnVisibility`, `pagination`, `tableActions`.
+Optional sections (fall back to `defaultGridI18n`): `selectColumnHeader`, `columnResize`, `columnOrder`,
+`loading`, `toolbar`, `table`, `grouping`, `selection`, `status`.
+
+`table` keys include `label` («Data grid», the `<table>` name), `skipToRows` / `skipToHeader` (bypass
+links), `expandCell`, `rowMenu`, `errorMessage`, `retry`, `totalsLabel`.
+
+Always start from the default bag: `i18n={{ ...defaultGridI18n, ...overrides }}`. There is no bundled
+Italian bag; `GRID_IT_LOCALE` (`"it-IT"`) is the locale constant for number formatting in
+`gridResultScope`.
+
+---
+
+## Accessibility
+
+- Native table semantics: `aria-sort` on sortable headers; `id`/`headers` chain for multi-level headers;
+  `aria-rowcount` / `aria-rowindex` over the traversable body rows (header rows excluded; `-1` while an
+  infinite source has more); `aria-colcount`.
+- One row header per row via `rowHeader: true`; `aria-label` on the table from `i18n.table.label`; two
+  bypass links («skip to rows», «skip to headers»).
+- **Exactly one live region** (`role="status"`, polite, atomic) announces loading, results, errors, sort,
+  filters and selection. Skeleton rows are `aria-hidden`.
+- Truncated text cells get a focusable target with the full value; cells that fit add no tab stop.
+  Copying a data row pastes as one spreadsheet row.
+- Full screen: `role="dialog"`, focus contained, Escape exits.
+- Menus and popovers are non-modal and portal inside the grid root when needed (so they stay reachable
+  in full screen).
+- Known gaps: column resize has no single-pointer alternative to dragging (WCAG 2.5.7) and the handle's
+  pointer target is 8 px wide (2.5.8); infinite loading has no keyboard trigger other than scrolling.
+
+---

package/dist/agent-docs/components/AppDataGrid/layout.md

@@ -0,0 +1,45 @@
+# AppDataGrid — Layout
+
+> Part of the [AppDataGrid](../AppDataGrid.md) docs. The Props table and the `onQueryChange` payload are in the main file.
+
+## Layout: widths, pinning, virtualization, density, full screen
+
+- **Widths and resize.** Every leaf header has a resize handle (drag, or arrow keys = 8 px on the
+  focused handle; `role="separator"` with `aria-valuenow`). Resizing never emits and commits once per
+  gesture (`onColumnWidthsChange`). Columns without a declared `width` fill the container; horizontal
+  overflow and scrollbars appear when widths exceed it.
+- **Pinning.** `pinned: "left" | "right"` on columns. Offsets are computed from declared widths, so they
+  are correct at first paint. A pinned block is visibly sticky only under horizontal overflow.
+- **Virtualization.** `virtualized` + a bounded viewport renders a window of rows (fewer than 60 `tr`
+  for 10,000 rows). Row heights are exact per density; switching density re-measures. Scrolling never
+  emits.
+- **Height helpers.** `gridViewportHeight({ rowCount, density, hasFooter?, hasFilterRow?,
+headerLevels? })` returns the scroll-box height to pass as `viewportHeight` (use the live density and
+  the filter-row state). `gridFrameHeight({ ...same, hasSelectionBar? })` returns viewport plus in-flow
+  bands, for computing a delta — it excludes toolbar, paginator, padding and border.
+  `gridFilterRowHeight` is the filter-row addend.
+- **Density.** `density` prop; offer a switch with `GridDensityControl`:
+
+  ```tsx
+  const [density, setDensity] = useState<GridDensity>("default");
+  <AppDataGrid
+    columns={columns}
+    data={rows}
+    density={density}
+    toolbar={{
+      actions: {
+        render: () => (
+          <GridDensityControl density={density} onChange={setDensity} />
+        ),
+      },
+    }}
+  />;
+  ```
+
+- **Full screen.** The toolbar toggle (or `initialFullscreen`) promotes the same DOM node to
+  `fixed inset-0` with a z-index above page overlays; nothing remounts or refetches and scroll position
+  is kept. The root becomes `role="dialog"` `aria-modal`, focus cycles inside it, Escape exits.
+  `requestFullscreen` is not used. If an ancestor creates a stacking context (`transform`, `filter`),
+  full screen renders inside that ancestor's context.
+
+---

package/dist/agent-docs/components/AppDataGrid/migration-from-datatable.md

@@ -0,0 +1,32 @@
+# AppDataGrid — Migrating from DataTable
+
+> Part of the [AppDataGrid](../AppDataGrid.md) docs. The Props table and the `onQueryChange` payload are in the main file.
+
+## Migrating from `DataTable`
+
+`DataTable` is deprecated in favour of `AppDataGrid`; both keep working side by side, so migration can
+be done call site by call site. Most exports map by name:
+
+| `DataTable` export                                                                                                                                 | `AppDataGrid` export                                                                                                                           |
+| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DataTable`, `DataTableProps`                                                                                                                      | `AppDataGrid`, `AppDataGridProps`                                                                                                              |
+| `createStringColumn`, `createNumberColumn`, `createBooleanColumn`, `createDateColumn`, `createDateTimeColumn`                                      | `createGridStringColumn`, `createGridNumberColumn`, `createGridBooleanColumn`, `createGridDateColumn`, `createGridDateTimeColumn`              |
+| `createSingleSelectColumn`, `createMultiSelectColumn`, `createComputedColumn`, `createActionColumn`, `createDisplayColumn`                         | `createGridSingleSelectColumn`, `createGridMultiSelectColumn`, `createGridComputedColumn`, `createGridActionColumn`, `createGridDisplayColumn` |
+| `createInitialState`, `createSorting`                                                                                                              | `createGridInitialState`, `createGridSorting`                                                                                                  |
+| `ServerState`, `DataTableServerConfig`, `DataTableState` / `InitialTableState`                                                                     | `GridServerState`, `GridServerConfig`, `GridInitialState`                                                                                      |
+| `DataTableI18n`, `defaultDataTableI18n`                                                                                                            | `GridI18n`, `defaultGridI18n`                                                                                                                  |
+| `DataTableBadgeFilter`, `DataTableFilterForSearch`, `DataTableSorting`, `DataTablePagination`, `DataTableActions`, `FilterOperator`, `IColumnType` | `GridBadgeFilter`, `GridFilterForSearch`, `GridSorting`, `GridPagination`, `GridActions`, `GridFilterOperator`, `GridColumnType`               |
+
+Behaviour differences to check when migrating:
+
+- `sortable` and `filterable` default to `true` (were `false`); `searchable` stays opt-in.
+- `hideActionsRow` hides only the `actions` buttons, not the toolbar.
+- `serverDebounceTime` (default 200) coalesces emissions instead of delaying the loading overlay.
+- There is no `mode` prop: the server branch is selected by the server props; grouping is client-only.
+- No emission at mount — perform the initial fetch yourself.
+- Filters are in the header filter row by default; there is no bundled Italian i18n bag.
+- Filter helpers of `DataTable` (`createFilterBadge`, `applyClientSideFilter`, `getPinnedStyle`, …) have
+  no public equivalent: filter badges are created by the grid, by `useGridFilters` or by
+  `createGridCustomFilterBadge`.
+
+---

package/dist/agent-docs/components/AppDataGrid/saved-views.md

@@ -0,0 +1,76 @@
+# AppDataGrid — Saved views
+
+> Part of the [AppDataGrid](../AppDataGrid.md) docs. The Props table and the `onQueryChange` payload are in the main file.
+
+## Saved views (presets)
+
+A `GridViewPreset` captures one view:
+
+```ts
+interface GridViewPreset {
+  version: number; // GRID_VIEW_PRESET_VERSION
+  id: string;
+  name: string;
+  query: {
+    search: string;
+    sorting: { id: string; desc: boolean }[]; // GridSortDescriptor[]
+    filters: GridBadgeFilter[];
+    pageSize: number;
+  };
+  view: {
+    density: GridDensity;
+    columnWidths: Record<string, number>;
+    columnVisibility: Record<string, boolean>;
+    columnOrder: string[];
+  };
+}
+```
+
+- **Apply** by passing a new object to `preset` (identity-based; re-passing an equal new object applies
+  again). One application = one `onQueryChange` emission.
+- **Capture** the view half through `onDensityChange` (only for presets — own your density control),
+  `onColumnVisibilityChange`, `onColumnWidthsChange`, `onColumnOrderChange`. The query half you build from
+  your own state (`GridServerState.computedSorting` must be mapped to `GridSortDescriptor[]` by hand).
+- The capture callbacks do not fire on preset application; `onQueryChange` does. Save on an explicit user
+  action, not on every change.
+- `readGridViewPreset(raw)` validates a stored payload field by field (version, id, name, every
+  sort/filter element, operator vs. its `filterType`, finite numbers, integer `pageSize` ≥ 1, widths,
+  visibility, order). It throws `GridViewPresetVersionError` (`found`, `expected`, `reason` = offending
+  field path, `undefined` only for a version mismatch). It refuses, it does not sanitise: coerce values
+  (e.g. widths stored as strings in JSON columns) before reading.
+- Not validated: the inside of a custom badge's `customFragment` (treat presets from users as privileged
+  input), and ids that name no existing column.
+- `createInMemoryGridViewStore(initial?)` returns a `GridViewStore` (`list`, `load`, `save`, `remove`,
+  all async) kept in memory; implement the same interface for real persistence.
+
+```tsx
+const filters = useGridFilters({ columns: toGridFilterColumns(columns) });
+const [preset, setPreset] = useState<GridViewPreset>();
+const [columnWidths, setColumnWidths] = useState<Record<string, number>>({});
+const [columnOrder, setColumnOrder] = useState<string[]>([]);
+
+<AppDataGrid
+  columns={columns}
+  data={rows}
+  preset={preset}
+  filters={filters.badges}
+  columnVisibility={filters.columnVisibility}
+  onColumnVisibilityChange={(next) => {
+    for (const [id, visible] of Object.entries(next))
+      if (filters.columnVisibility[id] !== visible)
+        filters.setColumnVisible(id, visible);
+  }}
+  onAddFilter={filters.addBadge}
+  onUpdateFilter={filters.updateBadge}
+  onColumnWidthsChange={(next) => setColumnWidths({ ...next })}
+  onColumnOrderChange={setColumnOrder}
+  onPresetApplied={(p) => {
+    filters.restore(p.query.filters, p.view.columnVisibility);
+    // Re-seed captured state: preset application does not call the capture callbacks.
+    setColumnWidths({ ...p.view.columnWidths });
+    setColumnOrder([...p.view.columnOrder]);
+  }}
+/>;
+```
+
+---

package/dist/agent-docs/components/AppDataGrid/selection.md

@@ -0,0 +1,44 @@
+# AppDataGrid — Selection
+
+> Part of the [AppDataGrid](../AppDataGrid.md) docs. The Props table and the `onQueryChange` payload are in the main file.
+
+## Selection
+
+With `checkable`, a **selection bar** appears above the table as soon as a row is ticked (it occupies no
+space otherwise). It shows the count («2 rows selected»), the scope («of 8 on this page»), a totals band
+(the columns' `aggregate` over the selected rows, or `selection.summary.render()`), the bulk actions and
+a dismiss / «Deselect all» button.
+
+```ts
+type GridSelectionSlots =
+  | {
+      mode?: "page";
+      actions?: readonly GridSelectionAction[];
+      summary?: GridToolbarSlot;
+    }
+  | {
+      mode: "all";
+      actions?: readonly GridPromotableSelectionAction[];
+      summary?: GridToolbarSlot;
+    };
+
+interface GridSelectionAction {
+  id?: string; // stable key, recommended when labels can repeat
+  label: string; // visible label WITHOUT the number: the grid appends the count
+  icon?: IconName;
+  destructive?: boolean;
+  onSelect: (rowIds: readonly string[]) => void;
+  "data-testid"?: string;
+}
+// GridPromotableSelectionAction: same fields, but onSelectScope(scope: GridSelectionScope) instead of onSelect.
+```
+
+- `mode: "page"` (default): the header checkbox selects the rows of the current page.
+- `mode: "all"`: the bar also offers «Select all N rows» (N = `resultTotal` or `serverConfig.totalItems`)
+  when the result is larger than the page. Actions then receive `{ scope, rowIds, count }`: at scope
+  `"all"`, `rowIds` are only the ids the grid holds — use `count` and your current query to act on the
+  whole result. `onSelectScope` is required there (the compiler rejects a plain `onSelect`).
+- In full screen the bar takes its height from the viewport (one data row may be hidden).
+- Selected rows get an accent tint on every cell plus a left bar.
+
+---