laif-ds 1.0.5 → 1.1.0

package/dist/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable technical changes to the laif-ds core will be documented in this fil
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [laif-ds@1.1.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). 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 — 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` and capturable in saved views; `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
+- **DatePicker** / **AppSelect**: New `portalContainer` prop to portal the popover into a given element instead of `<body>`, for use inside containers with their own stacking context (e.g. a full-screen grid)
+- **DropdownMenu**: `DropdownMenuContent` accepts a `container` prop with the same purpose
+- **AppSelect**: New `aria-label` and `aria-labelledby` props, used to name the trigger when no `label` is passed
+
+### 🔧 Changed
+
+- **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
+- **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 panel layout but deprecated in favour of the AppDataGrid filter row (`filterMode="row"`)
+
+### 🐛 Fixed
+
+- **AppSelect**: Options sharing the same label are no longer highlighted together, since each option is now keyed by its value instead of its label
+
 ## [laif-ds@1.0.5]
 
 ### 🚀 Added

package/dist/_virtual/index2.js

@@ -1,8 +1,5 @@
 "use client";
-import { getDefaultExportFromCjs as e } from "./_commonjsHelpers.js";
-import { __require as t } from "../node_modules/eventemitter3/index2.js";
-var r = t();
-const m = /* @__PURE__ */ e(r);
+var e = { exports: {} };
 export {
-  m as default
+  e as __module
 };

package/dist/_virtual/index3.js

@@ -1,5 +1,8 @@
 "use client";
-var e = { exports: {} };
+import { getDefaultExportFromCjs as e } from "./_commonjsHelpers.js";
+import { __require as t } from "../node_modules/eventemitter3/index2.js";
+var r = t();
+const m = /* @__PURE__ */ e(r);
 export {
-  e as __module
+  m as default
 };

package/dist/_virtual/index4.js

@@ -1,8 +1,8 @@
 "use client";
-import { getDefaultExportFromCjs as e } from "./_commonjsHelpers.js";
-import { __require as r } from "../node_modules/extend/index.js";
-var t = r();
-const x = /* @__PURE__ */ e(t);
+import { getDefaultExportFromCjs as r } from "./_commonjsHelpers.js";
+import { __require as e } from "../node_modules/style-to-js/cjs/index.js";
+var t = e();
+const a = /* @__PURE__ */ r(t);
 export {
-  x as default
+  a as default
 };

package/dist/_virtual/index5.js

@@ -1,8 +1,8 @@
 "use client";
-import { getDefaultExportFromCjs as r } from "./_commonjsHelpers.js";
-import { __require as e } from "../node_modules/style-to-js/cjs/index.js";
-var t = e();
-const a = /* @__PURE__ */ r(t);
+import { getDefaultExportFromCjs as e } from "./_commonjsHelpers.js";
+import { __require as r } from "../node_modules/extend/index.js";
+var t = r();
+const x = /* @__PURE__ */ e(t);
 export {
-  a as default
+  x as default
 };

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,23 +1,137 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-09-23T17:05:08.621Z",
+  "generatedAt": "2026-09-30T14:40:24.024Z",
   "package": {
     "name": "laif-ds",
-    "version": "1.0.5"
+    "version": "1.1.0"
   },
   "summary": {
-    "scannedFiles": 404,
-    "deprecatedComponentsCount": 2,
-    "deprecatedComponentsUsedCount": 0,
+    "scannedFiles": 502,
+    "deprecatedComponentsCount": 5,
+    "deprecatedComponentsUsedCount": 3,
     "componentsWithoutExamplesCount": 5,
     "componentsWithoutPropsTableCount": 30,
     "repeatedClassPatternsCount": 25,
-    "lowAiReadinessComponentsCount": 41,
+    "lowAiReadinessComponentsCount": 42,
     "componentsWithoutAccessibilityCoverageCount": 44,
-    "componentsWithWeakStateCoverageCount": 71,
-    "averageAiReadinessScore": 56.33
+    "componentsWithWeakStateCoverageCount": 72,
+    "averageAiReadinessScore": 57.06
   },
-  "deprecatedUsage": [],
+  "deprecatedUsage": [
+    {
+      "component": "DataTable",
+      "replacement": "AppDataGrid",
+      "totalOccurrences": 24,
+      "usages": [
+        {
+          "file": "src/components/ui/app-data-grid/parts/grid-filter-editor.tsx",
+          "occurrences": 3
+        },
+        {
+          "file": "src/components/design-tokens.ts",
+          "occurrences": 2
+        },
+        {
+          "file": "src/components/ui/app-data-grid/app-data-grid.tsx",
+          "occurrences": 2
+        },
+        {
+          "file": "src/components/ui/app-data-grid/app-data-grid.types.ts",
+          "occurrences": 2
+        },
+        {
+          "file": "src/components/ui/app-data-grid/grid-filter-operators.ts",
+          "occurrences": 2
+        },
+        {
+          "file": "src/components/ui/app-data-grid/parts/grid-scroll-area.tsx",
+          "occurrences": 2
+        },
+        {
+          "file": "src/components/ui/tables/data-table/data-table.tsx",
+          "occurrences": 2
+        },
+        {
+          "file": "src/components/ui/app-data-grid/grid-i18n.ts",
+          "occurrences": 1
+        },
+        {
+          "file": "src/components/ui/app-data-grid/parts/grid-cell-text.tsx",
+          "occurrences": 1
+        },
+        {
+          "file": "src/components/ui/app-data-grid/parts/grid-column-registry-panel.tsx",
+          "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/parts/grid-group-row.tsx",
+          "occurrences": 1
+        },
+        {
+          "file": "src/components/ui/app-data-grid/parts/grid-selection-bar.tsx",
+          "occurrences": 1
+        },
+        {
+          "file": "src/components/ui/app-select.tsx",
+          "occurrences": 1
+        },
+        {
+          "file": "src/components/ui/tables/data-table/data-table.utils.ts",
+          "occurrences": 1
+        }
+      ]
+    },
+    {
+      "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",
+      "totalOccurrences": 4,
+      "usages": [
+        {
+          "file": "src/components/ui/sidebar.tsx",
+          "occurrences": 4
+        }
+      ]
+    }
+  ],
   "documentationGaps": {
     "componentsWithoutExamples": [
       "AppMultipleSelectDropdown",
@@ -160,6 +274,7 @@
       "Sheet",
       "ShikiHighlighter",
       "Sidebar",
+      "SidebarMenuBadge",
       "Skeleton",
       "Slider",
       "Sonner",
@@ -312,6 +427,10 @@
         "name": "SecurePdfViewer",
         "score": 40
       },
+      {
+        "name": "SidebarMenuBadge",
+        "score": 40
+      },
       {
         "name": "Toggle",
         "score": 40
@@ -350,9 +469,10 @@
     "repeatedClassNames": [
       {
         "className": "flex items-center gap-2",
-        "occurrences": 36,
+        "occurrences": 39,
         "files": [
           "src/components/stories/app-checkbox.stories.tsx",
+          "src/components/stories/app-data-grid-completa.stories.tsx",
           "src/components/stories/app-dialog.stories.tsx",
           "src/components/stories/app-radio-group.stories.tsx",
           "src/components/stories/app-select.stories.tsx",
@@ -459,6 +579,22 @@
           "src/components/stories/tabs.stories.tsx"
         ]
       },
+      {
+        "className": "text-d-muted-foreground",
+        "occurrences": 12,
+        "files": [
+          "src/components/stories/app-data-grid-completa.stories.tsx",
+          "src/components/stories/app-data-grid-preset.stories.tsx",
+          "src/components/stories/app-dialog.stories.tsx",
+          "src/components/stories/app-time-picker.stories.tsx",
+          "src/components/ui/app-data-grid/parts/grid-toolbar-slots.tsx",
+          "src/components/ui/app-form.tsx",
+          "src/components/ui/app-multiple-select-dropdown.tsx",
+          "src/components/ui/app-select.tsx",
+          "src/components/ui/date-picker.tsx",
+          "src/components/ui/weekly-calendar/calendar-header.tsx"
+        ]
+      },
       {
         "className": "flex h-full overflow-hidden",
         "occurrences": 12,
@@ -524,16 +660,16 @@
         ]
       },
       {
-        "className": "text-d-muted-foreground",
+        "className": "text-d-muted-foreground text-xs",
         "occurrences": 7,
         "files": [
-          "src/components/stories/app-dialog.stories.tsx",
-          "src/components/stories/app-time-picker.stories.tsx",
-          "src/components/ui/app-form.tsx",
-          "src/components/ui/app-multiple-select-dropdown.tsx",
-          "src/components/ui/app-select.tsx",
-          "src/components/ui/date-picker.tsx",
-          "src/components/ui/weekly-calendar/calendar-header.tsx"
+          "src/components/editor/plugins/mention-plugin.tsx",
+          "src/components/stories/app-card.stories.tsx",
+          "src/components/stories/input.stories.tsx",
+          "src/components/ui/app-data-grid/parts/grid-filter-editor.tsx",
+          "src/components/ui/tables/data-cross-table/cell-editor-dialog.tsx",
+          "src/components/ui/tables/data-cross-table/data-cross-table.tsx",
+          "src/components/ui/tables/data-cross-table/editable-input.tsx"
         ]
       },
       {
@@ -566,18 +702,6 @@
           "src/components/stories/spinner.stories.tsx"
         ]
       },
-      {
-        "className": "text-d-muted-foreground text-xs",
-        "occurrences": 6,
-        "files": [
-          "src/components/editor/plugins/mention-plugin.tsx",
-          "src/components/stories/app-card.stories.tsx",
-          "src/components/stories/input.stories.tsx",
-          "src/components/ui/tables/data-cross-table/cell-editor-dialog.tsx",
-          "src/components/ui/tables/data-cross-table/data-cross-table.tsx",
-          "src/components/ui/tables/data-cross-table/editable-input.tsx"
-        ]
-      },
       {
         "className": "flex items-center gap-1 font-normal",
         "occurrences": 6,
@@ -590,6 +714,17 @@
           "src/components/editor/plugins/toolbar/block-format/format-quote.tsx"
         ]
       },
+      {
+        "className": "flex items-center gap-1",
+        "occurrences": 6,
+        "files": [
+          "src/components/editor/plugins/toolbar/history-toolbar-plugin.tsx",
+          "src/components/stories/app-select.stories.tsx",
+          "src/components/ui/app-data-grid/parts/grid-group-row.tsx",
+          "src/components/ui/app-kanban.tsx",
+          "src/components/ui/calendar.tsx"
+        ]
+      },
       {
         "className": "text-sm font-semibold",
         "occurrences": 6,
@@ -600,15 +735,6 @@
           "src/components/stories/truncated-cell.stories.tsx",
           "src/components/ui/weekly-calendar/appointment-card.tsx"
         ]
-      },
-      {
-        "className": "text-lg font-semibold",
-        "occurrences": 6,
-        "files": [
-          "src/components/stories/app-kanban.stories.tsx",
-          "src/components/stories/changelog.stories.tsx",
-          "src/components/stories/playground.stories.tsx"
-        ]
       }
     ]
   }

package/dist/agent-docs/components/AppCard.md

@@ -10,24 +10,24 @@ Enhanced card component built on top of the base Card component. Provides a simp
 
 ### AppCardProps
 
-| Prop               | Type                                                                                                   | Default     | Description                                                         |
-| ------------------ | ------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------- |
-| `title`            | `string \| React.ReactNode`                                                                            | `undefined` | Card title displayed in the header.                                 |
-| `description`      | `string \| React.ReactNode`                                                                            | `undefined` | Card description displayed below the title.                         |
-| `header`           | `React.ReactNode`                                                                                      | `undefined` | Custom header content; overrides `title` and `description`.         |
-| `body`             | `React.ReactNode`                                                                                      | `undefined` | Main content rendered inside CardContent.                           |
-| `children`         | `React.ReactNode`                                                                                      | `undefined` | Fallback body content when `body` is not provided.                  |
-| `actions`          | `React.ReactNode`                                                                                      | `undefined` | Right-aligned action elements inside the header.                    |
-| `footer`           | `React.ReactNode`                                                                                      | `undefined` | Footer content (typically action buttons).                          |
-| `variant`          | `AppCardVariant`                                                                                       | `"default"` | Visual variant of the card (see table below).                       |
-| `size`             | `"sm" \| "default" \| "lg" \| "none"`                                                                 | `undefined` | Controls internal padding via the base Card component.              |
-| `isLoading`        | `boolean`                                                                                              | `false`     | When true, renders skeleton placeholders instead of content.        |
-| `showHeaderBorder` | `boolean`                                                                                              | `false`     | Displays a border between the header and body sections.             |
-| `showFooterBorder` | `boolean`                                                                                              | `false`     | Displays a border between the body and footer sections.             |
-| `className`        | `string`                                                                                               | `undefined` | Additional classes for the card container.                          |
-| `headerClassName`  | `string`                                                                                               | `undefined` | Additional classes for the header section.                          |
-| `bodyClassName`    | `string`                                                                                               | `undefined` | Additional classes for the body section.                            |
-| `footerClassName`  | `string`                                                                                               | `undefined` | Additional classes for the footer section.                          |
+| Prop               | Type                                  | Default     | Description                                                  |
+| ------------------ | ------------------------------------- | ----------- | ------------------------------------------------------------ |
+| `title`            | `string \| React.ReactNode`           | `undefined` | Card title displayed in the header.                          |
+| `description`      | `string \| React.ReactNode`           | `undefined` | Card description displayed below the title.                  |
+| `header`           | `React.ReactNode`                     | `undefined` | Custom header content; overrides `title` and `description`.  |
+| `body`             | `React.ReactNode`                     | `undefined` | Main content rendered inside CardContent.                    |
+| `children`         | `React.ReactNode`                     | `undefined` | Fallback body content when `body` is not provided.           |
+| `actions`          | `React.ReactNode`                     | `undefined` | Right-aligned action elements inside the header.             |
+| `footer`           | `React.ReactNode`                     | `undefined` | Footer content (typically action buttons).                   |
+| `variant`          | `AppCardVariant`                      | `"default"` | Visual variant of the card (see table below).                |
+| `size`             | `"sm" \| "default" \| "lg" \| "none"` | `undefined` | Controls internal padding via the base Card component.       |
+| `isLoading`        | `boolean`                             | `false`     | When true, renders skeleton placeholders instead of content. |
+| `showHeaderBorder` | `boolean`                             | `false`     | Displays a border between the header and body sections.      |
+| `showFooterBorder` | `boolean`                             | `false`     | Displays a border between the body and footer sections.      |
+| `className`        | `string`                              | `undefined` | Additional classes for the card container.                   |
+| `headerClassName`  | `string`                              | `undefined` | Additional classes for the header section.                   |
+| `bodyClassName`    | `string`                              | `undefined` | Additional classes for the body section.                     |
+| `footerClassName`  | `string`                              | `undefined` | Additional classes for the footer section.                   |
 
 ### Variant Reference
 
@@ -203,13 +203,17 @@ export function NestedCards() {
         <div className="flex flex-col gap-3">
           <AppCard
             title="Nested Item A"
-            body={<p className="text-sm">Flat cards have no border or shadow.</p>}
+            body={
+              <p className="text-sm">Flat cards have no border or shadow.</p>
+            }
             variant="flat"
             size="sm"
           />
           <AppCard
             title="Nested Item B"
-            body={<p className="text-sm">Good for secondary content regions.</p>}
+            body={
+              <p className="text-sm">Good for secondary content regions.</p>
+            }
             variant="flat"
             size="sm"
           />
@@ -228,7 +232,7 @@ import { AppCard } from "laif-ds";
 
 export function SizeVariants() {
   return (
-    <div className="flex flex-col gap-6 w-[400px]">
+    <div className="flex w-[400px] flex-col gap-6">
       <AppCard
         size="sm"
         title="Size: Small"

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