laif-ds 1.0.5-app-data-grid.102 → 1.0.5-app-data-grid.104

package/dist/CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 🚀 Added
 
-- **AppDataGrid**: New data grid, the successor to `DataTable`. Columns are declared with the `createGrid*Column` builders (string, number, boolean, date, date-time, single/multi select, computed, display, action, row menu, column groups). It supports filters in a filter row inside the columns (`filterMode="row"`, default) or in a panel, filters lifted outside the grid (`filters`, `GridFilterChips`, `useGridFilters`) and application-declared filter controls (`filterControls`); server mode via `onQueryChange`, fired only on search/sort/filter/page changes and debounced by `debounceTime`; `paginated` mode or an `infinite` source; `groupBy` grouping with aggregated cells; row selection with a page-selection bar for bulk actions; column pinning, resizing and reordering; `virtualized` rendering; `density` and full screen; saved views (`preset`, `readGridViewPreset`, `createInMemoryGridViewStore`); `i18n` (`defaultGridI18n`); loading, empty and error/retry states; a polite live region announcing result changes. See `AppDataGrid.md`
+- **AppDataGrid**: New data grid, the successor to `DataTable`. Columns are declared with the `createGrid*Column` builders (string, number, boolean, date, date-time, single/multi select, computed, display, action, row menu, column groups). Filters live in a filter row inside the columns by default (`filterMode="row"`) or in a panel (`filterMode="panel"`, work in progress), can be lifted outside the grid (`filters`, `GridFilterChips`, `useGridFilters`), and application-declared filter controls are supported (`filterControls`); a `toolbar.resetFilters` slot restores filters and search to the page's own defaults. Server mode via `onQueryChange`, fired only on search/sort/filter/page changes and debounced by `debounceTime`; `paginated` mode — with an AppSelect page-size picker, a "Page i/N" indicator and a default `pageSize` of 25 — or an `infinite` source; `groupBy` grouping with aggregated cells; row selection with a page-selection bar for bulk actions; column pinning, resizing and reordering, notified through `onColumnWidthsChange` / `onColumnOrderChange`; `virtualized` rendering; `density` and full screen, with ghost toolbar buttons for the filter row, column visibility and full screen shown by default and individually disableable; saved views capturing filters, search, sorting, density, column visibility, widths and order (`preset`, `readGridViewPreset`, `createInMemoryGridViewStore`); `i18n` (`defaultGridI18n`); loading, empty and error/retry states; a polite live region announcing result changes. See `AppDataGrid.md`
 - **DataTable**: The filter-option getters (`getStringFilterOptions`, `getNumberFilterOptions`, …), `defaultDataTableI18n` / `italianDataTableI18n` and the service helpers (`applyClientSideFilter`, `buildSearchFilter`, …) are now exported from the package root
 - **designTokens**: The shared design-token object is now exported from the package root, including the new `table` (row/header heights, cell padding) and `tableZ` (z-index layers) entries
 - **Button**: New `icon-xs` size
@@ -21,11 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **AppSelect**: The trigger is now an ARIA `combobox` (`aria-haspopup="listbox"`, `aria-controls`, `aria-activedescendant`): it opens with Enter, Space or the arrow keys, Arrow/Home/End move through the enabled options, and without `label`/`aria-label` its accessible name falls back to `placeholder`. The popover is no longer modal, so the rest of the page is not hidden from assistive technology while it is open. In multiple mode each chosen option exposes `aria-checked`, and search matches both the option label and its value
 - **Theme**: In the default light theme `--colors--surface--secondary` (behind `d-secondary` and `d-muted`) now uses a new `neutral--150` step instead of `neutral--125`, so it is distinguishable from the page background
-
-### 🗑️ Deprecated
-
 - **DataTable**: Deprecated in favour of **AppDataGrid**. It is still exported and existing code keeps compiling (no `@deprecated` tag, so consumer lint rules are not tripped); its docs and stories are marked deprecated. Migration guide: `AppDataGrid.md`
-- **GridFilterPanel**: Exported for the lifted-filters layout but deprecated in favour of the AppDataGrid filter row
+- **GridFilterPanel**: Exported for the lifted-filters panel layout but deprecated in favour of the AppDataGrid filter row (`filterMode="row"`)
 
 ### 🐛 Fixed
 

package/dist/_virtual/index6.js

@@ -1,5 +1,5 @@
 "use client";
-var e = { exports: {} };
+var e = {};
 export {
-  e as __module
+  e as __exports
 };

package/dist/_virtual/index7.js

@@ -1,5 +1,5 @@
 "use client";
-var e = {};
+var e = { exports: {} };
 export {
-  e as __exports
+  e as __module
 };

package/dist/agent-docs/adoption-report.json

@@ -1,14 +1,14 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-09-30T12:25:42.329Z",
+  "generatedAt": "2026-09-30T12:51:53.069Z",
   "package": {
     "name": "laif-ds",
-    "version": "1.0.5-app-data-grid.102"
+    "version": "1.0.5-app-data-grid.104"
   },
   "summary": {
-    "scannedFiles": 490,
-    "deprecatedComponentsCount": 4,
-    "deprecatedComponentsUsedCount": 2,
+    "scannedFiles": 502,
+    "deprecatedComponentsCount": 5,
+    "deprecatedComponentsUsedCount": 3,
     "componentsWithoutExamplesCount": 5,
     "componentsWithoutPropsTableCount": 30,
     "repeatedClassPatternsCount": 25,
@@ -89,6 +89,37 @@
         }
       ]
     },
+    {
+      "component": "GridFilterPanel",
+      "replacement": "AppDataGrid",
+      "totalOccurrences": 7,
+      "usages": [
+        {
+          "file": "src/components/ui/app-data-grid/app-data-grid.types.ts",
+          "occurrences": 2
+        },
+        {
+          "file": "src/components/ui/app-data-grid/app-data-grid.tsx",
+          "occurrences": 1
+        },
+        {
+          "file": "src/components/ui/app-data-grid/index.ts",
+          "occurrences": 1
+        },
+        {
+          "file": "src/components/ui/app-data-grid/parts/grid-filter-panel.tsx",
+          "occurrences": 1
+        },
+        {
+          "file": "src/components/ui/app-data-grid/parts/grid-filter-row.tsx",
+          "occurrences": 1
+        },
+        {
+          "file": "src/components/ui/app-data-grid/use-grid-filters.ts",
+          "occurrences": 1
+        }
+      ]
+    },
     {
       "component": "SidebarMenuBadge",
       "replacement": "NavItem.badge",

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

@@ -0,0 +1,113 @@
+# AppDataGrid — Columns
+
+> Part of the [AppDataGrid](../AppDataGrid.md) docs. The Props table and the `onQueryChange` payload are in the main file.
+
+## Column definition
+
+### Builders
+
+| Builder                        | Column type          | `cell` signature         | `cell` required | `id` required | Sortable / filterable / searchable by default |
+| ------------------------------ | -------------------- | ------------------------ | --------------- | ------------- | --------------------------------------------- |
+| `createGridStringColumn`       | `string`             | `(value, row, tableRow)` | no              | no            | yes / yes / no                                |
+| `createGridNumberColumn`       | `number`             | `(value, row, tableRow)` | no              | no            | yes / yes / no                                |
+| `createGridBooleanColumn`      | `boolean`            | `(value, row, tableRow)` | no              | no            | yes / yes / no                                |
+| `createGridDateColumn`         | `date`               | `(value, row, tableRow)` | no              | no            | yes / yes / no                                |
+| `createGridDateTimeColumn`     | `datetime`           | `(value, row, tableRow)` | no              | no            | yes / yes / no                                |
+| `createGridSingleSelectColumn` | `list_single_select` | `(value, row, tableRow)` | no              | no            | yes / yes / no                                |
+| `createGridMultiSelectColumn`  | `list_multi_select`  | `(value, row, tableRow)` | no              | no            | yes / yes / no                                |
+| `createGridComputedColumn`     | `other`              | `(value, row, tableRow)` | no              | no            | no / no / no                                  |
+| `createGridActionColumn`       | —                    | `(row)`                  | **yes**         | **yes**       | never                                         |
+| `createGridDisplayColumn`      | —                    | `(row)`                  | **yes**         | no            | no / no / opt-in                              |
+| `createGridRowMenuColumn`      | —                    | none (`rowMenu`)         | n/a             | **yes**       | never                                         |
+| `createGridColumnGroup`        | group                | —                        | —               | **yes**       | —                                             |
+
+The two `cell` arities are copied from `DataTable` on purpose, so existing `cell:` closures keep compiling
+after a rename. All builders are generic: `createGridNumberColumn<Row, number>({ ... })`.
+
+Column ids: explicit `id`, else `accessorKey`, else derived from `headerLabel` (`<type>-<slug>`); a
+column with none of them throws. Ids must be stable across reloads — they key widths, visibility, order,
+sorting and saved views.
+
+### Accessor builder options
+
+Applies to the eight accessor builders (`accessorKey`-based).
+
+| Option            | Type                                                                             | Default                                   | Description                                                                                                                                                       |
+| ----------------- | -------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `accessorKey`     | `string`                                                                         | —                                         | **Required.** Field to read; dotted paths (`user.name`) read nested values. Also the key used in `computedFilter`.                                                |
+| `header`          | `string \| ReactNode`                                                            | —                                         | **Required.** When not a string, `headerLabel` is required by the type.                                                                                           |
+| `headerLabel`     | `string`                                                                         | `header` if a non-empty string, else `id` | Text form of the header: accessible name, menus, chips, columns panel.                                                                                            |
+| `id`              | `string`                                                                         | `accessorKey`                             | Stable column id.                                                                                                                                                 |
+| `sortable`        | `boolean`                                                                        | `true` (`false` for computed)             | Renders the sort button. Note: `DataTable` defaulted to `false`.                                                                                                  |
+| `filterable`      | `boolean`                                                                        | `true` (`false` for computed)             | Offers the column in the filter row / panel. Note: `DataTable` defaulted to `false`.                                                                              |
+| `searchable`      | `boolean`                                                                        | `false`                                   | **Opt-in.** Includes the column in the global search (client matching and `computedFilter`). Enable it only on text-like columns the backend can search.          |
+| `filterType`      | `GridFilterType` (column types except `"other"`)                                 | the column type                           | How the column is filtered, when different from its type (e.g. `"list_single_select"` + `options` on a string column).                                            |
+| `options`         | `readonly string[] \| readonly GridSelectOption[] \| readonly AppSelectOption[]` | `undefined`                               | Choices of a list column (or of a list `filterType`). Bare strings are normalised to `{ value, label }`. Numeric `value`s are kept as numbers in the payload.     |
+| `pinned`          | `"left" \| "right"`                                                              | `undefined`                               | Sticks the column to an edge during horizontal scroll. Pin a **prefix** (left) or a **suffix** (right): offsets accumulate in declaration order.                  |
+| `align`           | `"left" \| "right"`                                                              | `"left"`                                  | Content alignment of header, cells, group cells and footer. `"right"` adds `tabular-nums`.                                                                        |
+| `width`           | `number`                                                                         | `160` (elastic)                           | Initial width in px (64–1200). Columns without a declared width share leftover space; a drag replaces it.                                                         |
+| `rowHeader`       | `boolean`                                                                        | `false`                                   | Renders this column's cells as `<th scope="row">` — the row's name for assistive tech and for row-menu labels. At most one column per grid (a second one throws). |
+| `cell`            | `(value, row, tableRow) => ReactNode`                                            | stringified value                         | Cell renderer. Text returned as a string gets automatic truncation handling (tooltip + focusable target only when it overflows).                                  |
+| `cellClassName`   | `string \| ((value, row) => string)`                                             | `undefined`                               | Cell classes. Note the two-parameter callback.                                                                                                                    |
+| `headerClassName` | `string`                                                                         | `undefined`                               | Header cell classes.                                                                                                                                              |
+| `aggregatedCell`  | `(rows: TData[]) => ReactNode`                                                   | `undefined`                               | Content of this column's cell in **group rows**. Receives every original row under the group, at any depth. Absent = empty group cell.                            |
+| `aggregate`       | `(rows: TData[]) => ReactNode`                                                   | `undefined`                               | Column total in the sticky `<tfoot>`, over the rows after search/filters/sort (the page when `paginated`). No footer unless a visible column declares one.        |
+
+Action / display / row-menu columns accept `id`, `header`/`headerLabel`, `pinned`, `width`, `align`,
+`rowHeader` (display: also `searchable`). `createGridRowMenuColumn` takes `rowMenu` instead of `cell`.
+
+### Column groups (multi-level headers)
+
+```tsx
+createGridColumnGroup<Row>({
+  id: "customer", // required, unique among ALL nodes (groups and leaves)
+  header: "Customer",
+  headerLabel: "Customer", // required when header is not a string
+  columns: [nameColumn, cityColumn /* or nested groups */],
+});
+```
+
+Groups add header rows only; rows, sorting, filtering, widths and pinning see the flat list of leaves.
+Nesting depth is unlimited. Each body cell is linked to its headers through `id`/`headers`. A group whose
+leaves are all hidden disappears.
+
+### Row menu column
+
+```tsx
+createGridRowMenuColumn<Job>({
+  id: "actions",
+  header: "Actions",
+  pinned: "right",
+  width: 100,
+  rowMenu: (row) => [
+    { id: "open", label: "Open", onSelect: () => open(row.id) },
+    {
+      id: "duplicate",
+      label: "Duplicate",
+      onSelect: () => duplicate(row.id),
+      disabled: row.closed,
+    },
+    {
+      id: "delete",
+      label: "Delete",
+      destructive: true,
+      onSelect: () => remove(row.id),
+    },
+  ],
+});
+```
+
+Items are data (`GridRowMenuItem`: `id`, `label`, `onSelect`, `destructive?`, `disabled?`); the grid
+renders the `…` trigger and a non-modal menu aligned to the end. The trigger's accessible name is
+`i18n.table.rowMenu` plus the row's identity (from the `rowHeader` column, else the row id). Returning an
+empty list (or `undefined`) renders no trigger.
+
+### Column helpers
+
+- `createGridSorting([{ column: "name", order: "asc" }])` → `GridSorting` (`{ sort_by, sort_order }`).
+- `createGridInitialState({ filters?, searchbarFilter?, sorting?, pagination?, columnVisibility? })` →
+  `GridInitialState` (for `initialState`).
+- `toGridFilterColumns(columns)` → `GridFilterColumn[]` for `useGridFilters` (flat leaf columns; columns
+  without `accessorKey` are skipped).
+
+---

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.
+
+---