laif-ds 0.2.92 → 1.0.0

package/dist/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.0.0]
+
+### 🚀 Added
+
+- **AppSidebar**: Below 768px, the sidebar now renders a Settings-style drill-down menu instead of the desktop tree in a full-screen sheet — grouped cards with dividers, 44px rows with a leading icon and a chevron only where there are children, and items with `subItems` open a level-1 screen (with a `‹ Menu` back control) instead of expanding inline. This replaces the previous mobile behavior unconditionally; there is no prop to opt out, and `collapsible` has no effect below 768px
+- **AppSidebar**: Added `navigationDisplay` prop (`"list" | "tab"`, default `"list"`) — in `"tab"` mode the `navigation` groups render as a tab bar at the top of the sidebar and show one group at a time, instead of stacking every group under its own label. Only the selected tab shows its label, animating open to fit it exactly; every other tab is icon-only. `navigationFooter` is never tabbed and always stays visible at the bottom. A lone `navigation` group still renders without a label (in both displays and on mobile), and with a single group the tab bar is dropped entirely. Collapsed to the icon rail, the bar becomes a single group selector — the active group's icon with a chevron — that opens a `menuitemradio` menu. `NavGroup` gained an optional `iconName`, read only in tab mode
+- **AppBottomNav**: Added a new mobile bottom navigation bar (visible below 768px, `md:hidden`), meant to be mounted as the last child of `SidebarInset`, in the normal flow and never `fixed`. The bar is full-bleed and attached to the bottom edge — `bg-d-card` with a top border only, rounded top corners, `overflow-hidden`, no shadow — for a total height of 55px plus the safe-area inset, painted as bar surface with no minimum floor. It renders up to 5 destinations (`BottomNavItem[]`, already filtered, sorted and route-matched by the app) with 16px icons over a 12px label — deliberately below both native tab-bar baselines, label-forward — plus a Menu cell that opens `AppSidebar`'s mobile panel (`showMenu={false}` drops it and spends the freed slot on a 6th destination instead). A cell with its own `subItems` opens the panel already drilled into that level instead of navigating, via the sidebar context's new `mobileNavTarget`. The active cell is marked with a rounded pill using the sidebar's own active-row colors (`bg-d-sidebar-accent` / `text-d-sidebar-accent-foreground` / `font-bold`, no border) instead of a solid brand fill — the same low-contrast tradeoff the desktop sidebar's active row has always carried on that surface (~1.1–1.2:1, under the 3:1 WCAG 1.4.11 floor for a non-text indicator), carried here by weight rather than tint; label and icon stay at 10:1+ regardless. Hover is limited to fine-pointer, hover-capable devices so a tap can't leave a stuck hover tint next to the active cell
+- **design-tokens**: Added `designTokens.sizes.touch` (44px), `designTokens.motion` (shared easing/duration for the sidebar's tab animation), and `designTokens.navItem` (selected-row styling built on foreground weight and a leading bar for the sidebar's own rows, plus a `basePill`/`selectedPill` variant carrying the rounded-pill treatment for `AppBottomNav`'s active cell)
+
+### 🔧 Changed
+
+- **Sidebar**: On mobile, the full-screen `Sheet` branch now takes precedence over `collapsible="none"` — previously, pinning `collapsible="none"` left the trigger toggling `openMobile` with no sheet listening to it, making navigation unreachable below 768px. The mobile sheet now also takes focus on open (instead of landing on whatever `headerContent` renders first, which could raise the keyboard over the menu) and restores focus to the trigger on close
+- **Sheet**: `side="full"` no longer zooms under `prefers-reduced-motion` — the fade stays
+
+### 🐛 Fixed
+
+- **AppSidebar**: Mobile row labels now wrap instead of clamping to two lines, so long labels remain fully readable at 200% text zoom (WCAG 1.4.4)
+- **AppSidebar**: Mobile group titles no longer render at a 3.94:1 contrast ratio (muted text on a muted panel)
+- **AppSidebar**: In `navigationDisplay="tab"` mode, focus now survives collapsing and re-expanding the sidebar while a tab is focused, and the selected tab is tracked via React state instead of Radix's `data-state` — `TooltipTrigger asChild` was silently overwriting that attribute on the trigger, which had been killing every active-state rule keyed off it
+
 ## [laif-ds@0.2.92]
 
 ### 🐛 Fixed

package/dist/_virtual/index3.js

@@ -1,8 +1,8 @@
 "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);
+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 {
-  m as default
+  a as default
 };

package/dist/_virtual/index4.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/index5.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 { __require as t } from "../node_modules/eventemitter3/index2.js";
+var r = t();
+const m = /* @__PURE__ */ e(r);
 export {
-  x as default
+  m as default
 };

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

@@ -1,12 +1,12 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-08-20T15:52:41.132Z",
+  "generatedAt": "2026-09-02T16:31:01.025Z",
   "package": {
     "name": "laif-ds",
-    "version": "0.2.92"
+    "version": "1.0.0"
   },
   "summary": {
-    "scannedFiles": 398,
+    "scannedFiles": 402,
     "deprecatedComponentsCount": 2,
     "deprecatedComponentsUsedCount": 0,
     "componentsWithoutExamplesCount": 5,
@@ -14,8 +14,8 @@
     "repeatedClassPatternsCount": 25,
     "lowAiReadinessComponentsCount": 41,
     "componentsWithoutAccessibilityCoverageCount": 45,
-    "componentsWithWeakStateCoverageCount": 72,
-    "averageAiReadinessScore": 55.54
+    "componentsWithWeakStateCoverageCount": 71,
+    "averageAiReadinessScore": 56.17
   },
   "deprecatedUsage": [],
   "documentationGaps": {
@@ -111,7 +111,6 @@
       "AlertDialog",
       "AppDialog",
       "AppMultipleSelectDropdown",
-      "AppSidebar",
       "AspectRatio",
       "AudioVisualizer",
       "Avatar",
@@ -452,6 +451,14 @@
           "src/components/stories/app-form.stories.tsx"
         ]
       },
+      {
+        "className": "flex h-full overflow-hidden",
+        "occurrences": 14,
+        "files": [
+          "src/components/stories/app-sidebar.stories.tsx",
+          "src/components/stories/sidebar.stories.tsx"
+        ]
+      },
       {
         "className": "text-muted-foreground mt-2 text-sm",
         "occurrences": 13,
@@ -459,6 +466,14 @@
           "src/components/stories/tabs.stories.tsx"
         ]
       },
+      {
+        "className": "text-d-muted-foreground max-w-prose text-sm",
+        "occurrences": 10,
+        "files": [
+          "src/components/stories/app-bottom-nav.stories.tsx",
+          "src/components/stories/app-sidebar.stories.tsx"
+        ]
+      },
       {
         "className": "flex w-[550px] flex-col gap-6",
         "occurrences": 10,
@@ -508,6 +523,13 @@
           "src/components/stories/async-select.stories.tsx"
         ]
       },
+      {
+        "className": "flex-1 space-y-3 overflow-auto p-4",
+        "occurrences": 8,
+        "files": [
+          "src/components/stories/app-sidebar.stories.tsx"
+        ]
+      },
       {
         "className": "!text-d-foreground opacity-50",
         "occurrences": 8,
@@ -569,46 +591,23 @@
         ]
       },
       {
-        "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"
-        ]
-      },
-      {
-        "className": "flex h-full overflow-hidden",
+        "className": "text-sm font-semibold",
         "occurrences": 6,
         "files": [
-          "src/components/stories/app-sidebar.stories.tsx",
-          "src/components/stories/sidebar.stories.tsx"
-        ]
-      },
-      {
-        "className": "mb-2 text-sm font-medium",
-        "occurrences": 6,
-        "files": [
-          "src/components/stories/chat-message.stories.tsx",
+          "src/components/stories/app-bottom-nav.stories.tsx",
+          "src/components/stories/collapsible.stories.tsx",
           "src/components/stories/data-table-utils-example.stories.tsx",
-          "src/components/stories/dialog.stories.tsx"
-        ]
-      },
-      {
-        "className": "border-d-border border px-1 capitalize",
-        "occurrences": 6,
-        "files": [
-          "src/components/stories/data-table-docs.stories.tsx",
-          "src/components/stories/data-table-no-utils-example.stories.tsx",
-          "src/components/stories/data-table-utils-example.stories.tsx"
+          "src/components/stories/truncated-cell.stories.tsx",
+          "src/components/ui/weekly-calendar/appointment-card.tsx"
         ]
       },
       {
-        "className": "list-disc space-y-1 pl-5 text-sm",
+        "className": "text-lg font-semibold",
         "occurrences": 6,
         "files": [
-          "src/components/stories/data-table-no-utils-example.stories.tsx",
-          "src/components/stories/data-table-utils-example.stories.tsx"
+          "src/components/stories/app-kanban.stories.tsx",
+          "src/components/stories/changelog.stories.tsx",
+          "src/components/stories/playground.stories.tsx"
         ]
       }
     ]

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

@@ -0,0 +1,426 @@
+# AppBottomNav
+
+## Overview
+
+Mobile bottom navigation bar: up to 5 primary destinations plus a **Menu** cell
+that opens `AppSidebar`'s mobile panel — or up to 6 destinations with
+`showMenu={false}`, which is the same six cells either way. Visible below 768px
+only (`md:hidden`), and rendered **in the normal flow — never `fixed`**.
+
+The bar is **full-bleed and attached to the bottom edge**: the surface is
+`bg-d-card` with `border-t border-d-border`, `rounded-t-lg` on the top two
+corners only and `overflow-hidden`, which is the same language `DrawerContent`
+uses for its `bottom` direction. Below 768px `SidebarInset` is already
+full-viewport-width, so the full bleed needs no positioning of its own.
+
+**Mount it as the last child of `SidebarInset`**, outside any page-level padding
+wrapper, and make the page content beside it the scroll container
+(`flex-1 min-h-0 overflow-auto`). `SidebarInset` is a flex column, so with the
+dock's `shrink-0` the bar stays put while the page scrolls — the sticky feel
+without `fixed`, and without every consuming app having to add bottom padding to
+every scroll container. **Two things an app can get wrong**: if the document
+scrolls instead of the page container the bar scrolls off-screen, and any
+horizontal padding on an ancestor breaks the full bleed — that one is a layout
+bug, not only a cosmetic one.
+
+Total height is **55px** (measured) plus the safe-area reserve, which the
+component adds itself (`pb-[env(safe-area-inset-bottom)]`, with no `max()`
+floor) — budget that column in the page layout. It breaks down as 1px of
+`border-t` + 4px of top inset + a 46px pill (34px of content — a 16px icon, a
+2px gap and a 16px line — plus 12px of vertical padding) + 4px of bottom inset.
+The reserve is **painted bar surface**: under a home indicator you see bar
+colour, not page.
+
+The 46px cell clears the 44px touch floor (`min-h-11`) by **2px**, where the
+20px-icon version cleared it by 6. Measured, `min-h-11` is not engaged — the
+cell renders at 46px, so the height still comes from `py-1.5` — but the margin
+is thin: trim the padding, the icon or the label's line-height any further and
+`min-h-11` takes the height over, at which point the written padding stops
+describing what is rendered. **Measure the cell, not the padding.**
+
+It must be rendered inside a `SidebarProvider` (it reads the sidebar context to
+open the mobile panel); outside one, `useSidebar()` throws.
+
+---
+
+## Props
+
+| Prop            | Type                                                                                    | Default             | Description                                                         |
+| --------------- | --------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------- |
+| `items`         | `BottomNavItem[]`                                                                       | **required**        | Already filtered, sorted and route-matched by the app. Max 5 used, or 6 with `showMenu={false}`. |
+| `showMenu`      | `boolean`                                                                               | `true`              | `false` drops the Menu cell and spends its slot on a sixth destination. Only for an app that opens the mobile panel elsewhere — see below. |
+| `menuLabel`     | `string`                                                                                | `"Menu"`            | Label of the menu cell.                                             |
+| `ariaLabel`     | `string`                                                                                | `"Main navigation"` | Accessible name of the `<nav>` landmark.                            |
+| `menuIconName`  | `IconName`                                                                              | `"Menu"`            | Icon of the menu cell.                                              |
+| `linkComponent` | `React.ComponentType<React.AnchorHTMLAttributes<HTMLAnchorElement> & { href: string }>` | `undefined`         | Router link component (e.g. Next.js `Link`); plain `<a>` otherwise. |
+| `linkProps`     | `Record<string, unknown>`                                                               | `{}`                | Extra props forwarded to `linkComponent`.                           |
+| `className`     | `string`                                                                                | `undefined`         | Merged onto the dock wrapper.                                       |
+
+Inherits the remaining props from `Omit<React.ComponentProps<"div">, "children">`
+(the bar renders its own cells; it takes no children).
+
+### `BottomNavItem`
+
+| Field       | Type           | Default      | Description                                                                                    |
+| ----------- | -------------- | ------------ | ---------------------------------------------------------------------------------------------- |
+| `title`     | `string`       | **required** | Visible label. **Must equal the sidebar `NavItem.title`** of the same destination (see below). |
+| `url`       | `string`       | **required** | Ignored when `subItems` is non-empty; pass `"#"` there by convention.                          |
+| `iconName`  | `IconName`     | **required** | No fallback — at 16px the glyph no longer leads; what makes it required is the row, where a cell without one breaks the rhythm and reads as a failed image. |
+| `isActive`  | `boolean`      | `undefined`  | Leaf level only — the subtree state is derived from `subItems`.                                |
+| `subItems`  | `NavSubItem[]` | `undefined`  | Presence makes the cell open the mobile menu at this level instead of navigating.              |
+| `ariaLabel` | `string`       | `undefined`  | Only when the spoken name must differ from the label; it must still contain the visible text.  |
+
+`NavSubItem` is the same type `AppSidebar` uses:
+`{ title: string; url: string; isActive?: boolean; iconName?: IconName }`.
+
+---
+
+## Behavior
+
+### Layout
+
+- **6 cells maximum**: the first 5 `items` plus the Menu cell, or the first 6
+  `items` with `showMenu={false}`. The budget is on **cells and does not move
+  with `showMenu`** — hiding the Menu spends the slot it frees on a destination
+  rather than fattening the other cells, which is the only reason to hide it.
+  Neither number is configurable.
+- Cells are always **`flex-1 min-w-0`** — equal width, evenly distributed, at
+  every count and whatever a cell holds. Both halves matter: `flex-1` is
+  `1 1 0%`, which stays even only while no cell's content forces it wider, since
+  a flex item's automatic minimum size is its min-content width. `min-w-0`
+  removes that escape hatch, so the label truncates instead of the row going
+  uneven. (Without it the row would still be even at these widths — the
+  min-content floor is 24px, a `shrink-0` 16px icon plus `px-1`, against a
+  narrowest cell of 52px — but by arithmetic rather than by construction.)
+- **Six is a maximum, not a count.** Nothing pads the row: with fewer items the
+  cells simply get fatter, as every native tab bar does, and Menu stays pinned
+  to the thumb-reachable bottom-right corner. Minus the 4px inset on each side,
+  at 375px that is **61.2px** at 6 cells, **73.4px** at 5, **91.8px** at 4 and
+  **122.3px** at 3 (at 320px, 6 cells are 52px) — all above the 44px touch floor
+  (`min-h-11`, which lets a cell grow but never clip). The `FewerItems` story is
+  three items plus Menu.
+- **The sixth cell is paid for out of the label, and the bill is not small.**
+  Take off `px-1` and the label box is **53px at 375px**, against the 65.4px it
+  had at five cells. Measured in the `WithoutMenu` story at 375px, that is
+  enough to ellipsize labels that used to fit: `Dashboard` and `Documenti`
+  render at 63px and now truncate, `Impostazioni` at 74px truncates hard,
+  while `Clienti`, `Report` and `Storico` fit. **At six cells, plan for ~8
+  characters at 375px** — one-word labels, and short ones. `WithoutMenu` at
+  375px is the tightest row the component can render; check a real label set
+  there before shipping six.
+- The **dock carries the surface**, not the inner `<nav>`: full-bleed, attached
+  to the bottom edge, `border-t` + `rounded-t-lg` (8px, the value
+  `DrawerContent` uses for its bottom direction), and `overflow-hidden`, which
+  guarantees the corners of the surface stay the dock's own whatever a cell
+  paints. The `<nav>` is pure layout, with a **uniform 4px inset** (`p-1`): that
+  is what keeps the active pill clear of the 8px top curve — a full-bleed cell
+  with a radius of its own comes out shaved on the first and last slot — and it
+  is uniform because a pill nearer one edge than the other reads as a
+  misalignment. **No gap** between cells: only one is ever filled, so the
+  neighbours are transparent and a gap would only narrow the label.
+- **No shadow, deliberately.** The bar is in-flow, so nothing ever passes behind
+  it, and Tailwind's shadows project downwards — from the bottom edge that is
+  off-screen. In dark a black-alpha shadow is invisible anyway, so the
+  separation would rest on the border in one theme and on two mechanisms in the
+  other. The border is the single carrier.
+- **No visual hint on cells that open the menu** — no chevron, no caret. At
+  ~61px a chevron costs two characters of an already-truncating label, and a
+  hint on some cells only breaks the even rhythm that makes a tab bar scannable.
+  The feedback is the reveal itself.
+
+### Icon size: a deliberate divergence from the native baselines
+
+Cell icons are `Icon size="xs"` — **16px** — over a 12px (`text-xs`) label. That
+is under both native baselines on purpose: iOS HIG draws a tab glyph at ~25pt
+over a 10pt label, Material 3 at 24dp over a 12sp one. At the 20px this bar used
+before it was already below both; 16px puts it at two thirds of MD3. **This is a
+decision, not an oversight — do not "correct" it upwards.** The bar is
+label-forward.
+
+The measurement behind the call: 16px against 20px is −20% linear and −36% in
+area, enough that the glyph stops out-reading its label and settles level with
+it. The word is what identifies the destination; the icon is what keeps the row
+scannable and what makes a cell look intact — which is why `iconName` is still
+required with no fallback. The size is the `xs` rung of the shared `Icon` scale
+and not a per-call `className` override: an 18px rung was considered and
+refused, because adding a step to `sizeMap` is a scale decision for ~93
+components taken to serve one bar.
+
+The padding was **not** compensated when the icon shrank: `py-1.5` stayed, so
+the bar came down from 59px to 55px. A lower bar was the point of the smaller
+glyph, not a side effect of it.
+
+### Active state
+
+Exactly one cell is ever marked, with `data-active="true"` and a **rounded
+pill**: `bg-d-sidebar-accent text-d-sidebar-accent-foreground font-bold` on a
+`rounded-md` (6px) surface, inset 4px from every edge of the dock
+(`designTokens.navItem.selectedPill`, with `navItem.basePill` carrying the
+radius on every cell). **No border on any side.**
+
+This is the desktop sidebar row's own active state, ported verbatim — the pair
+`sidebarMenuButtonVariants` paints under `data-[active=true]`. One vocabulary
+for "you are here" across the two navigations was judged worth more than either
+surface being optimal on its own.
+
+#### Contrast: very low, and inherited on purpose
+
+With no border, the fill is the only carrier of the state, which puts it under
+WCAG 1.4.11 (≥ 3:1 for a non-text indicator) against the bar surface. **The
+sidebar's accent is nowhere near that floor in either theme**:
+`--d-sidebar-accent` is `--colors--surface--tertiary` at 40% alpha, so it
+composites to a few levels off whatever it sits on — `#efefef` on the light bar,
+`#2f2f2f` on the dark one.
+
+| against the bar (`d-card`)                  | light (`#fafafa`) | dark (`#1f1f1f`) |
+| ------------------------------------------- | ----------------- | ---------------- |
+| `bg-d-sidebar-accent` (in use, composited)  | **1.10:1** ✗      | **1.23:1** ✗     |
+| `bg-d-accent` (solid tertiary)              | 1.26:1 ✗          | 1.77:1 ✗         |
+| `bg-d-primary` (previous)                   | 1.98:1 ✗          | 7.99:1 ✓         |
+| `bg-d-primary/40`                           | 1.30:1 ✗          | 2.39:1 ✗         |
+| `bg-d-primary/10`                           | 1.07:1 ✗          | 1.20:1 ✗         |
+| `bg-d-foreground` (conforming, dropped)     | 13.01:1 ✓         | 12.49:1 ✓        |
+
+| on the fill                                   | light     | dark      |
+| --------------------------------------------- | --------- | --------- |
+| `text-d-sidebar-accent-foreground` (label, icon) | 11.9:1 ✓ | 10.1:1 ✓ |
+
+Two things follow. **The label is never at risk**:
+`--d-sidebar-accent-foreground` is `--colors--text--body-primary`, the very
+colour the inactive cells already use, so text and icon read 11.9:1 and 10.1:1
+on the composited fill — what falls under the floor is the _separation of the
+active surface from the bar_, not legibility. And **this is not a regression
+introduced by the bottom bar**: the same fill on the sidebar's own surface
+(`#f5f5f5`) measures 1.08:1, so the desktop sidebar has always marked the
+current row by **weight**, with the tint as a hint. Here the weight does the
+same job.
+
+Which is why the pill is `font-bold` and not `font-semibold`: with a fill this
+faint, the weight _is_ the state. It costs label width on a cell that already
+truncates at 375px — if that has to be bought back, `font-semibold` is the place
+to spend it, not the fill.
+
+If the 3:1 floor ever has to be met, the table's last row is the way back
+(`bg-d-foreground` + `text-d-background`) — a near-black pill, dropped once
+already because it reads as a selected chip rather than as the current tab.
+`bg-d-primary` + `text-d-primary-foreground` is the other history: under the
+floor in light at 1.98:1, but separating by hue, which 1.4.11 does not measure.
+A tint of primary is not an option, as the table shows.
+
+The sidebar's `navItem.selected` can still afford a 10% tint because a 2px rule
+carries the state there; here there is no rule to fall back on.
+
+`rounded-md` and not `radius.sm`: `sm` is 4px in the Tailwind v4 bundle and 2px
+in the v3 one, and this would be the only place the two disagree. Not
+`rounded-d-md` either — that maps onto `--d-radius` and becomes 18px under the
+claymorphism theme, while the dock around it is a fixed `rounded-t-lg`.
+
+- **Leaf item active** (`isActive`) → the cell is a link with
+  `aria-current="page"`.
+- **Parent whose child is current** (any `subItems[].isActive`) → the cell is a
+  `<button>`, marked, **without** `aria-current`: a button is not a page, it is a
+  disclosure. So the app only has to mark the leaf.
+- **Nothing in the bar owns the route** → the **Menu** cell takes the pill, with
+  no `aria-current` and no `aria-expanded="true"`. Five neutral cells read as
+  "the component failed to work out where I am"; the truthful statement is "the
+  page you are on is reachable through here", and it is redundant for a screen
+  reader, so nothing is added to the accessibility tree. With
+  `showMenu={false}` there is nothing to hand the pill to and the bar does
+  render entirely neutral — the honest state when every cell is a destination
+  and none of them is the current one.
+- Two active items is an app bug: the first in order wins and one warning is
+  logged.
+
+Inactive cells use `text-d-foreground` with `font-medium` (not
+`text-d-muted-foreground`, which measures 4.11:1 on the card in the light theme
+— below the 4.5:1 floor at 12px; on `d-background` it would be worse, 3.94:1,
+so the full-bleed surface does not change the conclusion). The subordination
+comes from the weight and from the absence of the pill.
+
+**Interaction states.** Inactive cells hover and press to
+`bg-d-sidebar-accent` + `text-d-sidebar-accent-foreground`, and the marked cell
+has **no hover or press variant at all** — again the sidebar's behaviour rather
+than an omission: `sidebarMenuButtonVariants` gives the active row the accent
+and then repeats that same accent under `hover:` and `active:`, so the current
+row is inert to the pointer. The consequence is that the three states share one
+colour and only the bold label separates the current cell from a hovered one.
+Survivable in a vertical list, where the pointer is on the row you are looking
+at; not in a six-cell row, where a hover tint left behind by a tap sits _beside_
+the active cell and reads as a second one. **So hover is gated behind
+`[@media(hover:hover) and (pointer:fine)]`** — the sidebar's own fix for exactly
+this, applied there on its tab triggers. Hover is for a real mouse (below 768px
+also covers a narrow desktop window); the finger gets the press state, which is
+immediate, cannot stick, and previews the destination becoming current. There is
+no `interaction.active` squash: its scale is for buttons, and a tab-bar cell is a
+surface you move between, not an object you push — an anisotropic scale on a
+12px truncating label distorts the one thing the cell exists to let you read.
+
+### Opening the menu
+
+Both the Menu cell and any cell with `subItems` open `AppSidebar`'s mobile Sheet
+(`setOpenMobile(true)`, never `toggleSidebar()`).
+
+- The **Menu** cell always opens at level 0. Its `aria-expanded` follows
+  `openMobile`. There is no visual treatment of the open state: the sheet is
+  full-screen, so the bar is entirely covered while it is open.
+- A cell with `subItems` opens the panel **already drilled into that level**. It
+  publishes `item.title` as the sidebar context's `mobileNavTarget` and
+  `AppSidebarMobile` resolves it, at mount, against the first `NavItem` across
+  `navigation` then `navigationFooter` whose `title` matches and which has
+  sub-items. **This is why `BottomNavItem.title` must equal the sidebar
+  `NavItem.title`** — both lists come from the same app-side source. No match
+  opens level 0 and logs a warning; it is never an error surface.
+- The target only ever describes the next open: it is cleared when the panel
+  closes, so a stale target can never re-drill.
+
+#### Opting out: `showMenu={false}`
+
+**"Under 768px there is always a way to open the navigation" is the invariant
+the bar guarantees on its own, and `showMenu={false}` is an app taking that
+guarantee over — not switching it off.** With no Menu cell, the only thing left
+in the bar that reaches the mobile panel is a cell that happens to carry
+`subItems`; the full navigation, and every destination that did not make the six
+slots, is otherwise unreachable.
+
+So the opt-out is for an app that already provides that way somewhere else — a
+`SidebarTrigger` in its own header is the case it exists for (see the
+`WithoutMenu` story, which renders one). **It is not warned about**, because the
+component cannot see the app's header and a warning it can neither confirm nor
+suppress is noise. Turning it off is a claim; the app has to honour it.
+
+### Accessibility
+
+- `<nav aria-label={ariaLabel}>` — a named landmark, because this is the primary
+  way around the app.
+- Cells that open the menu are `<button type="button">` with
+  `aria-expanded`, and deliberately **no** `aria-controls` (the drill panel's id
+  is Radix-generated and unreachable from the bar) and **no** `aria-haspopup`
+  (`"menu"` would promise arrow-key menu semantics the drill-down does not
+  implement).
+- No `title` attributes: they do nothing on touch and some screen readers read
+  them after the name.
+- Focus ring is `designTokens.focusRing` + `focus-visible:ring-inset` — the
+  cells touch each other, so a 3px outset ring would spill over the neighbouring
+  cell and read as if two cells were focused.
+- Above 768px the dock is `display: none`, which also removes every cell from
+  the tab order. There is no JS breakpoint gate: `useIsMobile` returns `false` on
+  the first render, so a JS gate would omit the bar on SSR and first paint and
+  pop it in on hydration.
+
+### Motion
+
+No entrance animation — the bar is chrome, present from first paint. The only
+transition is the colour change already carried by `designTokens.focusRing`, so
+there is nothing for `prefers-reduced-motion` to suppress. The absence of a
+shadow is equally deliberate (see Layout). The sheet's own 300ms open is owned
+by `SheetContent`.
+
+### Warnings (`console.warn`, deduplicated per message)
+
+- more `items` than slots, naming the dropped titles;
+- `items: []` together with `showMenu={false}`, where the bar renders `null`;
+- two or more active items;
+- a duplicate `url` + `title` pair (duplicate React keys make React reuse DOM
+  and state across cells);
+- an unresolved drill target (logged by `AppSidebarMobile`).
+
+### Edge cases
+
+- **`items: []`** renders the bar with the Menu cell only, spanning the full
+  width: "under 768px there is always a way to open the navigation" is the
+  design system's invariant, and `null` would strand a user whose permissions
+  resolve to zero primary destinations.
+- **`items: []` with `showMenu={false}`** is the one configuration that renders
+  **`null`**, with a warning: there is nothing left to put in the bar, and the
+  alternative is a 9px strip of card and a border. It is warned about where the
+  opt-out itself is not, because the two halves of it are set in different
+  places — permission filtering and a layout prop — so an app arrives here by
+  accident rather than on purpose.
+- **More items than slots**: the first 5 in order are kept (6 with
+  `showMenu={false}`), the rest dropped with a warning naming them. Ordering is
+  the app's job, so first-N is the only non-arbitrary cut.
+- **An item without an icon** is a compile error, not a runtime fallback.
+
+---
+
+## Examples
+
+### App shell
+
+```tsx
+import {
+  AppBottomNav,
+  AppSidebar,
+  SidebarInset,
+  SidebarProvider,
+  type BottomNavItem,
+} from "laif-ds";
+import Link from "next/link";
+
+// Permission filtering, ordering and route matching all stay in the app.
+const bottomNavItems: BottomNavItem[] = [
+  { title: "Dashboard", url: "/dashboard", iconName: "Home", isActive: true },
+  { title: "Clienti", url: "/clients", iconName: "Users" },
+  {
+    // Same title as the sidebar item, so the menu opens inside this level.
+    title: "Documenti",
+    url: "#",
+    iconName: "FileText",
+    subItems: [
+      { title: "Recenti", url: "/documents/recent" },
+      { title: "Condivisi", url: "/documents/shared" },
+    ],
+  },
+  { title: "Report", url: "/reports", iconName: "ChartLine" },
+];
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <SidebarProvider>
+      <AppSidebar navigation={navigation} linkComponent={Link} />
+      <SidebarInset>
+        {/* The page is the scroll container, not the document. */}
+        <div className="min-h-0 flex-1 overflow-auto p-4">{children}</div>
+        <AppBottomNav items={bottomNavItems} linkComponent={Link} />
+      </SidebarInset>
+    </SidebarProvider>
+  );
+}
+```
+
+### Localised copy
+
+```tsx
+<AppBottomNav
+  items={bottomNavItems}
+  menuLabel={t("nav.menu")}
+  ariaLabel={t("nav.mainNavigation")}
+/>
+```
+
+### Without the Menu cell
+
+The header trigger is not optional here — it is what keeps the mobile panel
+reachable once the Menu cell is gone.
+
+```tsx
+<SidebarInset>
+  <header className="flex h-14 shrink-0 items-center gap-2 border-b px-2">
+    <SidebarTrigger />
+  </header>
+  <div className="min-h-0 flex-1 overflow-auto p-4">{children}</div>
+  {/* Six destinations: the slot the Menu cell would have taken. */}
+  <AppBottomNav items={sixItems} showMenu={false} linkComponent={Link} />
+</SidebarInset>
+```
+
+---
+
+## Notes
+
+- **Routing**: pass `linkComponent` (e.g. Next.js `Link`) to avoid full page
+  reloads; the design system never imports a router itself.
+- **Icons**: `iconName` goes through the `Icon` component (lucide names).
+- **Pairing**: the bar is a sibling of `AppSidebar`, not a replacement — the
+  full navigation is still reachable through the Menu cell, or through whatever
+  opens the mobile panel in its place under `showMenu={false}`.