laif-ds 1.0.0 → 1.0.2-app-data-grid.76

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

@@ -43,13 +43,13 @@ Date picker component that supports both **single date** and **date range** sele
 
 ### Single Mode Props (mode="single" or undefined)
 
-| Prop          | Type                                | Default     | Description                                                   |
-| ------------- | ----------------------------------- | ----------- | ------------------------------------------------------------- |
-| `value`       | `Date`                              | `undefined` | Controlled selected date.                                     |
-| `onChange`    | `(date: Date \| undefined) => void` | `undefined` | Called when the date changes.                                 |
-| `showTime`    | `boolean`                           | `false`     | Show time picker columns (HH, MM) alongside the calendar.     |
-| `withSeconds` | `boolean`                           | `false`     | Show seconds column in the time picker (requires `showTime`). |
-| `minuteStep`  | `number`                            | `1`         | Step interval for minute options (`1`-`59`, requires `showTime`). |
+| Prop          | Type                                | Default     | Description                                                             |
+| ------------- | ----------------------------------- | ----------- | ----------------------------------------------------------------------- |
+| `value`       | `Date`                              | `undefined` | Controlled selected date.                                               |
+| `onChange`    | `(date: Date \| undefined) => void` | `undefined` | Called when the date changes.                                           |
+| `showTime`    | `boolean`                           | `false`     | Show time picker columns (HH, MM) alongside the calendar.               |
+| `withSeconds` | `boolean`                           | `false`     | Show seconds column in the time picker (requires `showTime`).           |
+| `minuteStep`  | `number`                            | `1`         | Step interval for minute options (`1`-`59`, requires `showTime`).       |
 | `secondStep`  | `number`                            | `1`         | Step interval for second options (`1`-`59`, useful with `withSeconds`). |
 
 ### Range Mode Props (mode="range")

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

@@ -8,18 +8,18 @@ Drag-and-drop uploader with keyboard activation, file type filtering, limits (co
 
 ## Props
 
-| Prop                | Type                      | Default                                            | Description                                               |
-| ------------------- | ------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
-| `extensions`        | `AcceptItem[]`            | `["pdf","image","video","audio"]`                  | Allowed extensions/categories (maps to accept attribute). |
-| `multiple`          | `boolean`                 | `false`                                            | Enables multiple file selection.                          |
-| `onUpload`          | `(files: File[]) => void` | `undefined`                                        | Called when files are **added**, with the resulting list. |
-| `onRemove`          | `(removed: File[], remaining: File[]) => void` | `undefined`                           | Called when files are **removed** (single or remove-all), with the removed files and the list that remains. |
-| `description`       | `string`                  | `"Trascina un file o clicca per selezionare"`      | Dropzone hint.                                            |
-| `formatDescription` | `string`                  | `"Formato accettato: PDF, Immagini, Video, Audio"` | Accepted formats hint.                                    |
-| `selectedLabel`     | `string`                  | `"File selezionati"`                               | Title shown above selected files list.                    |
-| `removeAllLabel`    | `string`                  | `"rimuovi tutto"`                                  | Label for the "remove all" button.                        |
-| `maxTotalSize`      | `number` (bytes)          | `undefined`                                        | Maximum total size of selected files.                     |
-| `maxFiles`          | `number`                  | `undefined`                                        | Maximum number of files (when `multiple` is true).        |
+| Prop                | Type                                           | Default                                            | Description                                                                                                 |
+| ------------------- | ---------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `extensions`        | `AcceptItem[]`                                 | `["pdf","image","video","audio"]`                  | Allowed extensions/categories (maps to accept attribute).                                                   |
+| `multiple`          | `boolean`                                      | `false`                                            | Enables multiple file selection.                                                                            |
+| `onUpload`          | `(files: File[]) => void`                      | `undefined`                                        | Called when files are **added**, with the resulting list.                                                   |
+| `onRemove`          | `(removed: File[], remaining: File[]) => void` | `undefined`                                        | Called when files are **removed** (single or remove-all), with the removed files and the list that remains. |
+| `description`       | `string`                                       | `"Trascina un file o clicca per selezionare"`      | Dropzone hint.                                                                                              |
+| `formatDescription` | `string`                                       | `"Formato accettato: PDF, Immagini, Video, Audio"` | Accepted formats hint.                                                                                      |
+| `selectedLabel`     | `string`                                       | `"File selezionati"`                               | Title shown above selected files list.                                                                      |
+| `removeAllLabel`    | `string`                                       | `"rimuovi tutto"`                                  | Label for the "remove all" button.                                                                          |
+| `maxTotalSize`      | `number` (bytes)                               | `undefined`                                        | Maximum total size of selected files.                                                                       |
+| `maxFiles`          | `number`                                       | `undefined`                                        | Maximum number of files (when `multiple` is true).                                                          |
 
 `AcceptItem` includes: `pdf | doc | docx | xls | xlsx | ppt | pptx | txt | csv | jpg | jpeg | png | gif | image | video | audio | zip | rar | 7z | tar | gz | tgz`.
 

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

@@ -0,0 +1,112 @@
+# GridFilterPanel
+
+## Overview
+
+The overlay filter inventory of `AppDataGrid`: a toggle button that opens a panel listing one entry per
+filterable column, plus the badges currently applied. It is a **controlled** surface — it owns no filter
+state, it renders the `badges` it is handed and reports every change through `onAdd` / `onUpdate` /
+`onRemove`.
+
+⚠️ **Deprecated, not removed.** New work should use the Riga Zero filter row instead — `AppDataGrid` with
+`filterMode="row"` puts one filter cell per column inside the grid itself, opened in place. `GridFilterPanel`
+is still exported as a value and as a type from both barrels (`organisms/index.ts` and
+`ui/app-data-grid/index.ts`), and every existing call-site keeps compiling. There is no `@deprecated` JSDoc
+tag on the source, deliberately: it would trip the consumer lint rules that ban deprecated APIs.
+
+⚠️ **It ships without rendered coverage, and that is the reason the deprecation entry exists** — a
+measurement, not a style preference. Since `adg-r25` (2026-09-04) no story mounts this component, so its
+rendered behaviour has no executable coverage at all. The docblock of
+`app-data-grid-atomo-filtro.stories.tsx :: BersagliDellaRigaDeiChip` lists **eight known falsifications of
+the overlay inventory that would pass green today**: body opening upwards, absolute positioning removed,
+narrow width, `elementFromPoint` missing the panel, flipped anchor, `focus()` removed, and the primary
+action placed inside the scrolling container. A consumer who mounts it is mounting a surface this repository
+no longer measures.
+
+What still guards it is narrow and worth knowing: `scripts/check-filter-panel-selectors.mjs` binds the two
+selectors the stories assert **only in the negative** (`data-grid-filter-panel` and
+`data-grid-filter-panel-toggle`) to the source that emits them, so a **rename** goes red instead of leaving
+those assertions green forever. That gate catches a rename, not a behavioural break — the eight above stay
+uncovered.
+
+Recorded in `docs/analysis/datatable-v2/PIANO-COMPLETAMENTO.md` §«`GridFilterPanel` è spedito senza
+copertura resa».
+
+---
+
+## Props
+
+### GridFilterPanelProps
+
+| Prop               | Type                                             | Default | Description                                                                                                                                                                                                                                          |
+| ------------------ | ------------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `columns`          | `readonly GridFilterColumn[]`                    | —       | **Required.** The filterable columns offered in the panel's dropdown.                                                                                                                                                                                |
+| `badges`           | `readonly GridBadgeFilter[]`                     | —       | **Required.** The applied filters, rendered as badges. Built with the one badge constructor, so the panel and the Riga Zero produce the same state.                                                                                                   |
+| `open`             | `boolean`                                        | —       | **Required.** Whether the panel is open. Controlled — the component never holds this itself.                                                                                                                                                         |
+| `onOpenChange`     | `(open: boolean) => void`                        | —       | **Required.** Fired when the toggle opens or closes the panel.                                                                                                                                                                                       |
+| `onAdd`            | `(badge: GridBadgeFilter) => void`               | —       | **Required.** Fired when a new filter badge is created.                                                                                                                                                                                              |
+| `onUpdate`         | `(id: string, patch: Partial<GridBadgeFilter>) => void` | —  | **Required.** Fired with a partial patch when an existing badge changes.                                                                                                                                                                             |
+| `onRemove`         | `(id: string) => void`                           | —       | **Required.** Fired when a badge is removed.                                                                                                                                                                                                         |
+| `onBuildCondition` | `() => void`                                     | —       | The panel's primary action, «Costruisci una condizione». ⚠️ The panel composes nothing itself — the composer is its own surface (the filter atom) and this is only where it opens from. **Omitted ⇒ the button renders `disabled` rather than hidden**, because the criterion «the primary action does not scroll away» needs the node to exist either way, and a button that accepts a click and discards it is worse than one that declares it cannot act. |
+| `registry`         | `React.ReactNode`                                | —       | The column registry (R9), rendered inside the panel when present.                                                                                                                                                                                    |
+| `columnVisibility` | `Readonly<Record<string, boolean>>`              | all visible | Column visibility, so a hidden column is not offered in the dropdown. Absent means every column is visible.                                                                                                                                       |
+| `i18n`             | `GridI18n`                                       | `defaultGridI18n` | Label overrides, same object shape the grid takes.                                                                                                                                                                                         |
+| `className`        | `string`                                         | —       | Extra classes on the panel root.                                                                                                                                                                                                                     |
+
+---
+
+## Behavior
+
+- **Fully controlled.** `open` and `badges` both come from the call-site; the panel renders and reports,
+  it never stores.
+- **Two stable selectors**, and they are contractual: `data-grid-filter-panel` on the panel and
+  `data-grid-filter-panel-toggle` on the trigger. `scripts/check-filter-panel-selectors.mjs` fails the
+  build if either is renamed in the source without the assertions following.
+- **The primary action is always present**, `disabled` when `onBuildCondition` is omitted — see the prop
+  note above.
+- **Hidden columns are not offered**: a column whose `columnVisibility` entry is `false` is dropped from
+  the dropdown rather than shown and rejected.
+
+---
+
+## Examples
+
+### Preferred: the Riga Zero instead
+
+New work should not mount this component. The same filters live inside the grid:
+
+```tsx
+import { AppDataGrid } from "laif-ds";
+
+export function Commesse({ rows, columns }) {
+  return <AppDataGrid data={rows} columns={columns} filterMode="row" />;
+}
+```
+
+### Existing call-sites: the controlled panel
+
+```tsx
+import { GridFilterPanel } from "laif-ds";
+import { useState } from "react";
+
+export function InventarioFiltri({ columns }) {
+  const [open, setOpen] = useState(false);
+  const [badges, setBadges] = useState([]);
+
+  return (
+    <GridFilterPanel
+      columns={columns}
+      badges={badges}
+      open={open}
+      onOpenChange={setOpen}
+      onAdd={(badge) => setBadges((prev) => [...prev, badge])}
+      onUpdate={(id, patch) =>
+        setBadges((prev) =>
+          prev.map((badge) => (badge.id === id ? { ...badge, ...patch } : badge)),
+        )
+      }
+      onRemove={(id) => setBadges((prev) => prev.filter((badge) => badge.id !== id))}
+      onBuildCondition={() => setOpen(false)}
+    />
+  );
+}
+```

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

@@ -16,7 +16,7 @@ Low-level primitives to build responsive sidebars with desktop/offcanvas modes,
 - **SidebarHeader / SidebarFooter**: Top/bottom containers.
 - **SidebarContent**: Scrollable body.
 - **SidebarGroup / SidebarGroupLabel / SidebarGroupAction / SidebarGroupContent**: Labeled groups with optional action.
-- **SidebarMenu / SidebarMenuItem / SidebarMenuButton / SidebarMenuAction / SidebarMenuBadge**: Menu building blocks.
+- **SidebarMenu / SidebarMenuItem / SidebarMenuButton / SidebarMenuAction / SidebarMenuBadge**: Menu building blocks. `SidebarMenuBadge` is **deprecated** — see below.
 - **SidebarMenuSub / SidebarMenuSubItem / SidebarMenuSubButton**: Nested menus.
 
 ---
@@ -30,8 +30,78 @@ Low-level primitives to build responsive sidebars with desktop/offcanvas modes,
   toggle an `openMobile` no sheet is listening to, leaving the navigation
   unreachable. So on mobile `collapsible` has no effect at all.
 - **Collapsible**: `icon` mode shows only icons and tooltips; `offcanvas` moves panel off-screen.
+- **Icon-mode geometry** (`SidebarMenuButton` in the 3rem rail): a 32px pill
+  (`!size-8`, `mx-auto`) with **6px** of padding (`!p-1.5`) around a **20px**
+  glyph (`[&>svg]:size-5`) — 16px in expanded rows, where the button's own
+  `[&>svg]:size-4` applies. The three numbers come from
+  `navTokens.rail.button` (`src/components/nav-tokens.ts`) and are one decision: `32 - 2*6 = 20` makes the
+  content box **exactly** the glyph, which is what keeps every glyph on the
+  panel's centre line. The label stays mounted as a `flex-1` sibling (it is the
+  row's accessible name), so any slack in that box is claimed by the label and
+  pushes the glyph off-centre by half of it. Give the glyph a different size and
+  the padding has to follow.
 - **Keyboard**: Toggle with ⌘/Ctrl + B.
 - **Tooltips**: Menu buttons show tooltips only when collapsed on desktop.
+- **Peek (overlay expansion)**: see below.
+
+---
+
+## `SidebarMenuBadge` is deprecated
+
+Use `AppSidebar` with **`NavItem.badge` / `NavItem.badgeLabel`** instead (see
+`AppSidebar.md` → "Badges"). The primitive still works and is still exported,
+unchanged, for a consumer hand-building a `Sidebar` out of these parts — but it
+is the wrong tool for a navigation row:
+
+- it is `group-data-[collapsible=icon]:hidden`, so whatever it carries simply
+  **disappears** in the 3rem rail, where `NavItem.badge` degrades to a dot and
+  moves the value into the tooltip;
+- it has **no spoken form** — `NavItem.badgeLabel` rides an `sr-only` span
+  inside the row while the visual mark is `aria-hidden`;
+- it is positioned absolutely over the row rather than laid out in it, so it
+  cannot share the row with a chevron or an action;
+- it renders on one surface, where `NavItem.badge` renders on all four a
+  `NavItem` feeds, the mobile panel and `AppBottomNav` included.
+
+Removing it would be a breaking change on a published package, so it stays until
+a major.
+
+---
+
+## Peek — `useSidebar().peek` / `setPeek`
+
+A second, temporary way for the sidebar to be expanded, used by `AppSidebar`'s
+`expandOnHover`. The primitive provides the mechanism only: the hover, focus and
+pin logic lives in `AppSidebar`, which calls `setPeek` and nothing else.
+
+```ts
+const { state, open, setOpen, peek, setPeek } = useSidebar();
+```
+
+- `peek: boolean` — temporary expansion driven by hover or focus.
+- `setPeek(peek: boolean)` — the only thing the owner of the logic writes.
+
+Three things follow from it, and each exists for a reason:
+
+- **`state` is `open || peek ? "expanded" : "collapsed"`.** Widening the panel
+  alone would not work: the children read `state` and the
+  `group-data-[collapsible=icon]:*` rules, not the panel's width, so labels,
+  inline submenus and the tooltip suppression on `SidebarMenuButton` all hang off
+  this. Note that `data-collapsible` empties as soon as `state` is `"expanded"`,
+  peek included.
+- **`peek` never goes through `setOpen`,** so it never writes the
+  `sidebar_state` cookie. Otherwise every pass of the mouse would overwrite the
+  consumer's persisted preference with noise.
+- **The wrapper gets `data-peek="true"`,** and that is what keeps the peek an
+  _overlay_ rather than a push: the gap element and `SidebarInset` cancel the
+  effect of `data-state` on `data-peek="true"` and stay at icon width (per
+  variant — `floating` / `inset` keep their
+  `calc(var(--sidebar-width-icon) + 1rem)`), while the `fixed` panel takes the
+  raised z-index and the shadow. Any consumer styling that keys off
+  `data-state="collapsed"` for layout has to be re-anchored the same way.
+
+`peek` is forced to `false` below 768px, where the panel is a Sheet and there is
+no hover to speak of.
 
 ---
 
@@ -66,6 +136,7 @@ export function Shell() {
                 <SidebarMenuButton isActive>
                   <span>Dashboard</span>
                 </SidebarMenuButton>
+                {/* Deprecated — prefer `AppSidebar` + `NavItem.badge`. */}
                 <SidebarMenuBadge>3</SidebarMenuBadge>
               </SidebarMenuItem>
             </SidebarMenu>

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

@@ -0,0 +1,87 @@
+# SidebarMenuBadge
+
+## Overview
+
+⚠️ **Deprecated — use `AppSidebar` with `NavItem.badge` / `NavItem.badgeLabel` instead.**
+The primitive still works and is still exported, unchanged: removing it would be a
+breaking change on a published package, so it stays until a major.
+
+A small count or mark pinned to the right edge of a `SidebarMenuButton` row, for a
+consumer hand-building a `Sidebar` out of the primitives. It renders a `<div>` carrying
+`data-sidebar="menu-badge"`, positioned **absolutely** over the row and
+`pointer-events-none`, with its vertical offset following the sibling button's size
+(`sm` / `default` / `lg`).
+
+The full rationale for the deprecation — four reasons, each measurable — lives in
+`Sidebar.md` § «`SidebarMenuBadge` is deprecated», and the replacement is documented in
+`AppSidebar.md` § «Badges». The short version, because it is what decides whether you
+may use it:
+
+- it is `group-data-[collapsible=icon]:hidden`, so whatever it carries **disappears** in
+  the 3rem rail, where `NavItem.badge` degrades to a dot and moves the value into the
+  tooltip;
+- it has **no spoken form**, while `NavItem.badgeLabel` rides an `sr-only` span inside
+  the row with the visual mark `aria-hidden`;
+- being absolutely positioned rather than laid out in the row, it cannot share that row
+  with a chevron or an action;
+- it renders on one surface, where `NavItem.badge` renders on all four a `NavItem` feeds
+  — the mobile panel and `AppBottomNav` included.
+
+---
+
+## Props
+
+No own props. Extends `React.ComponentProps<"div">` — `className` is merged through
+`cn()`, everything else is spread onto the `<div>`.
+
+---
+
+## Behavior
+
+- **Hidden in icon mode.** `group-data-[collapsible=icon]:hidden`: in the collapsed rail
+  the badge is not rendered to the user at all. This is the reason it must not carry
+  information that exists nowhere else.
+- **Not interactive.** `pointer-events-none`, so clicks fall through to the menu button
+  underneath; it cannot host a control.
+- **Follows the button's size**, not its own prop: `top-1` next to a `sm` button,
+  `top-1.5` next to `default`, `top-2.5` next to `lg`, driven by the sibling's
+  `data-size` through the `peer/menu-button` group.
+- **Colour follows the row's state**, again through the peer: it takes the accent
+  foreground when the menu button is hovered or `data-active=true`.
+- **Numerals are tabular** (`tabular-nums`) so a changing count does not shift width.
+
+---
+
+## Example
+
+```tsx
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarMenuBadge,
+} from "laif-ds";
+
+export function Example() {
+  return (
+    <Sidebar>
+      <SidebarContent>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton>Inbox</SidebarMenuButton>
+            <SidebarMenuBadge>3</SidebarMenuBadge>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarContent>
+    </Sidebar>
+  );
+}
+```
+
+For new work, the same row in `AppSidebar`:
+
+```tsx
+<AppSidebar navigation={[{ items: [{ label: "Inbox", badge: 3, badgeLabel: "3 non lette" }] }]} />
+```

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

@@ -46,9 +46,9 @@ This document provides a complete mapping of all components available in the lai
 ### Layout & Structure Components
 
 - **Accordion** - Collapsible content panels for organizing information hierarchically
-- **AppBottomNav** - Mobile bottom navigation bar (`md:hidden`, in the normal flow as the last child of `SidebarInset`): six equal cells — up to 5 primary destinations plus a Menu cell that opens `AppSidebar`'s mobile panel, optionally already drilled into a level, or up to 6 destinations with `showMenu={false}` when the app opens that panel from its own header
+- **AppBottomNav** - Mobile bottom navigation bar (`md:hidden`, in the normal flow as the last child of `SidebarInset`): six equal cells — up to 5 primary destinations plus a Menu cell that opens `AppSidebar`'s mobile panel, optionally already drilled into a level, or up to 6 destinations with `showMenu={false}` when the app opens that panel from its own header, with an optional badge per cell (`badge`: a count as a superscript on the glyph, `99+` past 99, short text degrading to a dot) and `menuBadge` for a dot on the Menu cell, OR-ed with the badged items dropped past the cell budget
 - **AppCard** - Enhanced card component with variant styles, semantic states, size control, and loading skeleton support
-- **AppSidebar** - Application sidebar navigation component, with groups rendered as a stacked list or as a tab bar (`navigationDisplay="tab"`, one group at a time, only the selected tab labelled and animated open to fit it, `navigationFooter` always visible), optional icon-only collapse (`collapsible="icon"`: tooltips on top-level items, dropdown for sub-items) and, below 768px, a Settings-style mobile menu (grouped cards, 44px rows, drill-down on sub-items)
+- **AppSidebar** - Application sidebar navigation component, with groups rendered as a stacked list or as a tab bar (`navigationDisplay="tab"`, one group at a time, only the selected tab labelled and animated open to fit it, `navigationFooter` always visible), optional icon-only collapse (`collapsible="icon"`: tooltips on top-level items, dropdown for sub-items), optional hover expansion over that (`expandOnHover`: the pointer or the focus expands the panel as an overlay that does not move the page, a Pin in the header makes it permanent, `pinned`/`defaultPinned`/`onPinnedChange` alias the primitive's `open`) and, below 768px, a Settings-style mobile menu (grouped cards, 44px rows, drill-down on sub-items), plus an optional badge on every row and group (`badge`: `number | string | true` with `badgeLabel` for the spoken form, degrading per surface — pill when expanded, dot in the icon rail with the value in the tooltip, superscript in `AppBottomNav` — and never aggregating counts)
 - **AppStepper** - Step-by-step progress indicator for multi-step processes
 - **AspectRatio** - Container that maintains a specific aspect ratio for responsive layouts
 - **Breadcrumb** - Breadcrumb navigation component for hierarchical navigation
@@ -73,6 +73,7 @@ This document provides a complete mapping of all components available in the lai
 - **Drawer** - Slide-out panel for secondary content
 - **DropdownMenu** - Dropdown menu component with keyboard navigation
 - **HoverCard** - Popover card displayed on hover
+- **InterruptPrompt** - Animated prompt to interrupt an action (e.g. hitting Enter twice)
 - **Menubar** - Application menu bar component
 - **Popover** - Floating content container triggered by user interaction
 - **Sheet** - Side sheet component for secondary content
@@ -81,6 +82,7 @@ This document provides a complete mapping of all components available in the lai
 ### Data Display Components
 
 - **Avatar** - User profile image display with fallback initials
+- **AppDataGrid** - Data grid that replaces the deprecated `DataTable`: a single emitter (a column resize no longer refetches), opt-in virtualization keeping native `<table>` semantics, column widths/resize/left-pinning, multi-level headers with a real `id`/`headers` chain, lifted filter panel and chips, density and full screen, an infinite source with skeleton rows, client-side row grouping and saved views. Independent of `DataTable` — it imports nothing from it and the two can live on the same page
 - **Badge** - Small status indicator or label for highlighting information
 - **DataCrossTable** - Cross-tabulation data display component
 - **DataTable** - Advanced table component with sorting, filtering, and pagination
@@ -152,6 +154,49 @@ The following components are marked as deprecated and should not be used in new
 - **MultipleSelector** - ~~Use `AppSelect` instead~~
 - **AppMultipleSelectDropdown** - ~~Use `AppSelect` instead~~
 - **ResizePrompt** - ~~Use alternative resize handling methods~~
+- **DataTable** - ~~Use `AppDataGrid` instead~~
+
+- **GridFilterPanel** - ~~Use the Riga Zero filter row instead (`filterMode="row"`)~~
+
+  ⚠️ **Deprecated, not removed** — same distinction as `DataTable` above. `GridFilterPanel` is still
+  exported as a value and as a type from both barrels (`organisms/index.ts` and
+  `ui/app-data-grid/index.ts`), and every existing call-site keeps compiling. What changed is that
+  `AppDataGrid` now offers the filters **in the grid itself**, on the Riga Zero — one filter cell per
+  column, opened in place — and that is where new work should go.
+
+  ⚠️ **AND THE REASON THIS ENTRY EXISTS IS A COVERAGE FACT, not a style preference.** Since
+  `adg-r25` (2026-09-04, decision of Lorenzo) **no story mounts this component**, so its rendered
+  behaviour has **no executable coverage at all**: the docblock of
+  `app-data-grid-atomo-filtro.stories.tsx :: BersagliDellaRigaDeiChip` lists **eight known
+  falsifications of its overlay inventory that would pass green today** — body opening upwards,
+  absolute positioning removed, narrow width, `elementFromPoint` missing the panel, flipped anchor,
+  `focus()` removed, primary action inside the scrolling container. A consumer who mounts it is
+  mounting a surface this repository no longer measures.
+
+  What still guards it is narrow and worth knowing: `scripts/check-filter-panel-selectors.mjs` binds
+  the two selectors that the stories assert **only in the negative** (`data-grid-filter-panel` and
+  `data-grid-filter-panel-toggle`) to the source that emits them, so a rename goes red instead of
+  leaving four assertions green forever. That gate catches a **rename**, not a behavioural break: the
+  eight above stay uncovered.
+
+  Recorded in `docs/analysis/datatable-v2/PIANO-COMPLETAMENTO.md` §«`GridFilterPanel` è spedito senza
+  copertura resa».
+
+  ⚠️ **Deprecated, not removed, and the difference matters.** `DataTable` still works and is still
+  exported; every existing call-site keeps compiling. What changed is that new work should reach for
+  `AppDataGrid`, which is the same table rewritten to satisfy the fifteen requirements the old one
+  could not — a single emitter (a column resize no longer refetches), virtualization that keeps
+  native `<table>` semantics, multi-level headers with a real `id`/`headers` chain, an infinite
+  source, and client-side row grouping.
+
+  **The two can live on the same page.** `AppDataGrid` imports nothing from `DataTable` and shares no
+  state with it, which is what makes a call-site-by-call-site migration possible instead of a
+  flag day.
+
+  **Migrating is mostly a rename.** `scripts/codemod/rename-map.json` records, name by name, which
+  old export maps to which new one and which parts of the new surface have no old equivalent.
+
+- **SidebarMenuBadge** - ~~Use `NavItem.badge` instead~~ (on `AppSidebar`, with `badgeLabel` for the spoken form; the primitive stays exported and functional, but it is hidden in icon mode and has no spoken form — see `Sidebar.md`)
 
 ---