laif-ds 1.0.0 → 1.0.2

package/dist/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.2]
+
+### 🐛 Fixed
+
+- **AppBottomNav**: When the current route matches none of the bar's destinations, the Menu cell no longer takes the active pill — the bar now renders entirely neutral, the same as `showMenu={false}`, since Menu is a disclosure and not a page
+
+## [laif-ds@1.0.1]
+
+### 🚀 Added
+
+- **AppSidebar**: New `expandOnHover` prop expands the sidebar as a hover/focus overlay (page content doesn't shift) when collapsed to `collapsible="icon"`; a Pin control in the header promotes that to a permanent expansion, controllable via `pinned` / `defaultPinned` / `onPinnedChange`
+- **AppSidebar / AppBottomNav**: `NavItem`, `NavSubItem`, `NavGroup` and `BottomNavItem` gained `badge` (`number | string | true`) and `badgeLabel` props for a count, short text or dot indicator; `AppBottomNav` also gained `menuBadge` for a dot on the Menu cell. The badge degrades per surface — a pill when the sidebar is expanded, a dot with the value in the tooltip when collapsed to icons, a superscript on `AppBottomNav`'s glyph (text degrades to a dot there) — and never aggregates child counts into a parent. `SidebarMenuBadge` is now deprecated in favor of `NavItem.badge`
+
+### 🔧 Changed
+
+- **AppBottomNav**: Cell height increased from 55px to 67px — icons are now `size="sm"` (20px, up from 16px) and vertical padding is `py-2.5` (up from `py-1.5`), bringing the cell further past the 44px touch-target floor
+- **AppBottomNav**: `menuIconName` renamed to `menuIcon`, now accepting `IconName | (() => React.ReactNode)` so the Menu cell can render a custom glyph (e.g. a brand mark) in addition to a lucide icon name
+
+### 🐛 Fixed
+
+- **AppSidebar**: On mobile, `navigationFooter` now anchors to the bottom of the panel instead of trailing immediately after the last `navigation` group, matching its desktop placement whenever the navigation list is short enough to leave room
+- **AppSidebar**: The mobile panel's header is no longer offset ~16px from center under the floating close button — centered `headerContent` (e.g. a logo) is now centered correctly
+- **AppSidebar**: Collapsible submenus now animate open/closed instead of snapping instantly (skipped under `prefers-reduced-motion`), and collapsed rows are removed from the tab order and accessibility tree instead of staying mounted
+- **Sidebar**: The panel's edge border (default, non-floating/inset variant) now resolves to the intended `border-d-sidebar-border` token instead of Tailwind v4's `currentColor` default, which rendered near-white on dark themes and near-black on light ones
+
 ## [laif-ds@1.0.0]
 
 ### 🚀 Added

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

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

@@ -1,12 +1,12 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-09-02T16:31:01.025Z",
+  "generatedAt": "2026-09-18T09:11:12.858Z",
   "package": {
     "name": "laif-ds",
-    "version": "1.0.0"
+    "version": "1.0.2"
   },
   "summary": {
-    "scannedFiles": 402,
+    "scannedFiles": 404,
     "deprecatedComponentsCount": 2,
     "deprecatedComponentsUsedCount": 0,
     "componentsWithoutExamplesCount": 5,
@@ -351,7 +351,7 @@
     "repeatedClassNames": [
       {
         "className": "flex items-center gap-2",
-        "occurrences": 35,
+        "occurrences": 36,
         "files": [
           "src/components/stories/app-checkbox.stories.tsx",
           "src/components/stories/app-dialog.stories.tsx",
@@ -367,6 +367,7 @@
           "src/components/stories/truncated-cell.stories.tsx",
           "src/components/ui/app-form.tsx",
           "src/components/ui/app-kanban.tsx",
+          "src/components/ui/app-sidebar.tsx",
           "src/components/ui/file-previewer.tsx",
           "src/components/ui/weekly-calendar/calendar-header.tsx"
         ]
@@ -391,11 +392,12 @@
       },
       {
         "className": "text-d-muted-foreground text-sm",
-        "occurrences": 26,
+        "occurrences": 27,
         "files": [
           "src/components/stories/app-card.stories.tsx",
           "src/components/stories/app-dialog.stories.tsx",
           "src/components/stories/app-kanban.stories.tsx",
+          "src/components/stories/app-sidebar.stories.tsx",
           "src/components/stories/changelog.stories.tsx",
           "src/components/stories/date-picker.stories.tsx",
           "src/components/stories/input.stories.tsx",
@@ -451,14 +453,6 @@
           "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,
@@ -467,11 +461,11 @@
         ]
       },
       {
-        "className": "text-d-muted-foreground max-w-prose text-sm",
-        "occurrences": 10,
+        "className": "flex h-full overflow-hidden",
+        "occurrences": 12,
         "files": [
-          "src/components/stories/app-bottom-nav.stories.tsx",
-          "src/components/stories/app-sidebar.stories.tsx"
+          "src/components/stories/app-sidebar.stories.tsx",
+          "src/components/stories/sidebar.stories.tsx"
         ]
       },
       {
@@ -482,6 +476,14 @@
           "src/components/stories/app-radio-group.stories.tsx"
         ]
       },
+      {
+        "className": "text-d-muted-foreground max-w-prose text-sm",
+        "occurrences": 9,
+        "files": [
+          "src/components/stories/app-bottom-nav.stories.tsx",
+          "src/components/stories/app-sidebar.stories.tsx"
+        ]
+      },
       {
         "className": "border-d-border mt-2 rounded-md border p-4",
         "occurrences": 9,
@@ -523,13 +525,6 @@
           "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,
@@ -562,6 +557,13 @@
           "src/components/stories/app-select.stories.tsx"
         ]
       },
+      {
+        "className": "flex-1 space-y-3 overflow-auto p-4",
+        "occurrences": 7,
+        "files": [
+          "src/components/stories/app-sidebar.stories.tsx"
+        ]
+      },
       {
         "className": "border-d-border border px-3 py-1 text-center text-sm font-light",
         "occurrences": 7,

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

@@ -23,20 +23,26 @@ 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.
+Total height is **67px** — 12px over the 55px that was measured when the cell
+had `py-1.5` and a 16px glyph, which is exactly what those two changes add —
+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
+58px pill (38px of content — a 20px icon, a 2px gap and a 16px line — plus 20px
+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.**
+The vertical padding is `py-2.5`, taken from `designTokens.sizes.touch` — the
+only part of that token a six-cell row can afford (`px-4` would leave 29px for
+the label, `text-sm` would widen it further), and the same value the mobile
+sidebar rows get from the token entire. The 58px cell clears the 44px touch
+floor (`min-h-11`) by **14px**, where `py-1.5` over a 16px glyph cleared it by
+2. `min-h-11` is not engaged — the height comes from the padding and the
+content — and the margin is now wide enough that it stays that way: at the old
+values any further trim to the padding, the icon or the label's line-height
+would have handed the height to `min-h-11`, 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.
@@ -51,7 +57,8 @@ open the mobile panel); outside one, `useSidebar()` throws.
 | `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.                                              |
+| `menuIcon`      | `IconName \| (() => React.ReactNode)`                                                   | `"Menu"`            | The menu cell's glyph: a lucide name, or a function returning the node to draw for shapes lucide lacks. Nullish back from the function falls back to the default. |
+| `menuBadge`     | `boolean`                                                                               | `false`             | A dot on the Menu cell — **never** a count. OR-ed with the badged items dropped past the cell budget. |
 | `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.                                       |
@@ -65,13 +72,15 @@ Inherits the remaining props from `Omit<React.ComponentProps<"div">, "children">
 | ----------- | -------------- | ------------ | ---------------------------------------------------------------------------------------------- |
 | `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. |
+| `iconName`  | `IconName`     | **required** | No fallback — at 20px the glyph is what the eye lands on first, and a cell without one breaks the rhythm of the row 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.  |
+| `badge`     | `number \| string \| true` | `undefined`  | Count, short text or dot — the same field as `AppSidebar`'s `NavItem.badge`. This surface is `compact`: numbers render as a superscript on the glyph, **text degrades to a dot**. |
+| `badgeLabel`| `string`       | `undefined`  | The spoken form of `badge`, announced by an `sr-only` span inside the cell. Effectively required for `badge: true`. |
 
 `NavSubItem` is the same type `AppSidebar` uses:
-`{ title: string; url: string; isActive?: boolean; iconName?: IconName }`.
+`{ title: string; url: string; isActive?: boolean; iconName?: IconName; badge?: number | string | true; badgeLabel?: string }`.
 
 ---
 
@@ -90,7 +99,7 @@ Inherits the remaining props from `Omit<React.ComponentProps<"div">, "children">
   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
+  min-content floor is 28px, a `shrink-0` 20px 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
@@ -128,34 +137,36 @@ Inherits the remaining props from `Omit<React.ComponentProps<"div">, "children">
   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
+### Icon size
+
+Cell icons are `Icon size="sm"` — **20px** — over a 12px (`text-xs`) label, one
+rung up from the `xs` (16px) the bar carried before. Still under both native
+baselines: iOS HIG draws a tab glyph at ~25pt over a 10pt label, Material 3 at
+24dp over a 12sp one, so 20px sits below MD3 rather than above it.
+
+The measurement behind the step: 16px against 20px is −20% linear and −36% in
+area. At 16px the glyph settled *level* with its label — a fine proportion to
+read, a poor one to aim at from across the screen. At 20px the icon leads and
+the label confirms, which is the order a tab bar is scanned in, and it is why
+`iconName` is required with no fallback.
+
+The size is a rung of the shared `Icon` scale, not a per-call `className`
+override, and never an intermediate value: 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.
+components taken to serve one bar. **The next size up is `md` (24px)** — MD3
+parity, and 4px more 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.
+Height history, so the trade is legible: the bar was 59px with a 20px glyph and
+`py-1.5`, came down to 55px when the glyph shrank to 16px with the padding
+uncompensated, and is 67px now — `py-2.5` from `designTokens.sizes.touch` (+8px,
+spent on the touch target) and the glyph back to 20px (+4px, spent on reach).
 
 ### 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
+(`navTokens.item.selectedPill`, with `navTokens.item.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
@@ -207,7 +218,7 @@ already because it reads as a selected chip rather than as the current tab.
 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
+The sidebar's `navTokens.item.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
@@ -220,14 +231,13 @@ claymorphism theme, while the dock around it is a fixed `rounded-t-lg`.
 - **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.
+- **Nothing in the bar owns the route** → **no cell is marked**, Menu included.
+  The bar renders entirely neutral, exactly as it always has with
+  `showMenu={false}`. The Menu cell is a disclosure, not a destination: the pill
+  means "this is the page you are on", and handing it to a button that opens a
+  panel says that about something which is not a page. A route outside the bar's
+  five destinations is a real state, and the honest way to render it is no pill
+  at all.
 - Two active items is an app bug: the first in order wins and one warning is
   logged.
 
@@ -255,6 +265,51 @@ no `interaction.active` squash: its scale is for buttons, and a tab-bar cell is
 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.
 
+### Badges
+
+`BottomNavItem.badge` is the same field as `AppSidebar`'s `NavItem.badge` — the
+three forms (count, short text, dot), the `99+` overflow, the `0`-renders-nothing
+rule and the warnings are all documented once, in `AppSidebar.md`. What is
+specific to this surface:
+
+- The capacity is **`compact`**: a **number** renders as a 14px superscript on
+  the glyph (`99+` included), and a **short text degrades to a dot**. Four
+  characters of superscript in a 52px cell either do not read or run into the
+  neighbouring cell, so text is not shrunk, it is dropped to the smallest form
+  that still says "there is something here".
+- The badge sits on the **glyph**, not beside the label, which is what keeps the
+  ~8-character label budget documented above exactly as it was. Measured at
+  320px, the tightest row the bar renders: the label box is 44px in the badged
+  story and 44px in `Default` — the badge costs the label nothing.
+- It **does not bleed**. Six cells at 320px give a 44px content box around a
+  20px glyph, so there are 12px of slack per side; the badge reaches 6px past
+  the glyph plus 2px of ring, and it sits ~11px below the top edge of the dock,
+  so it meets neither the `rounded-t-lg` corners nor the dock's
+  `overflow-hidden`.
+- **No interaction with the active pill.** The pill marks the position, the
+  badge marks the quantity; inverting the badge on the current cell would tie
+  two orthogonal channels together. `ring-2 ring-d-card` is safe over the pill
+  unconditionally — pill and card measure 1.10:1 light / 1.23:1 dark against
+  each other, so one ring colour works in both states.
+- A cell with `subItems` that has no badge of its own shows a **dot** when one
+  of its descendants is badged. Counts never aggregate.
+- **The Menu cell takes `menuBadge`, a dot and never a count**: the Menu opens
+  the whole navigation, a superset of `items`, so any number the bar computed
+  would be a lie. It is OR-ed with the items **dropped past the cell budget**,
+  so a drop cannot hide state as well as a destination — the drop warning still
+  fires, naming them. The Menu dot carries no announcement: there is no label to
+  give it, and what it stands for is announced on the rows of the panel it
+  opens.
+- **Live counts vs static ones** follow the contract written once in
+  `AppSidebar.md` ("Live counts vs static ones, and who announces them"): the
+  design system assumes neither and renders no live region; when a count changes
+  as the direct result of an action on the current screen, the app announces it
+  in its own status region next to that action.
+
+The `WithBadges` and `WithBadgesSmall` stories are the same five labels as
+`Default`, badged, at 390px and 375px; `MenuBadgeFromDroppedItem` is the drop
+case.
+
 ### Opening the menu
 
 Both the Menu cell and any cell with `subItems` open `AppSidebar`'s mobile Sheet
@@ -299,6 +354,13 @@ suppress is noise. Turning it off is a claim; the app has to honour it.
   implement).
 - No `title` attributes: they do nothing on touch and some screen readers read
   them after the name.
+- A badge is `aria-hidden="true"` and its `badgeLabel` rides an in-flow
+  `sr-only` span **inside the cell**, so the name composes as "Clienti, 12
+  clienti nuovi" and never "Clienti 12". `aria-current` is untouched, on the
+  destination cells as on the parent cells (which carry `aria-expanded` and no
+  `aria-current`, as above). An aggregate dot — a parent's, or the Menu cell's —
+  is visual only: it has no text of its own, and what it stands for is announced
+  on the row that owns it.
 - 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.
@@ -311,18 +373,24 @@ suppress is noise. Turning it off is a claim; the app has to honour it.
 
 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`.
+there is nothing for `prefers-reduced-motion` to suppress. **Badges add none**:
+no enter/exit transition, no pulse, no animated counter — a badge appearing is
+not a reason to open that chapter. 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;
+- more `items` than slots, naming the dropped titles — and if one of the dropped
+  items was badged, the Menu cell takes a dot so the state is not dropped with
+  it;
 - `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`).
+- an unresolved drill target (logged by `AppSidebarMobile`);
+- an invalid `badge` (negative, non-integer, empty string) or one over 8
+  characters, and a `badge: true` with no `badgeLabel` — all logged by the shared
+  normaliser, naming the row.
 
 ### Edge cases
 
@@ -398,6 +466,69 @@ export function Layout({ children }: { children: React.ReactNode }) {
 />
 ```
 
+### A Menu cell of the app's own
+
+Both halves of the cell are configurable: `menuLabel` for the copy, `menuIcon`
+for the glyph. **`menuIcon` is one prop with two forms**, told apart by
+`typeof`:
+
+| form                    | when                            | example                       |
+| ----------------------- | ------------------------------- | ----------------------------- |
+| `IconName` (string)     | the shape is in lucide          | `menuIcon="LayoutGrid"`       |
+| `() => React.ReactNode` | it is not — a brand mark, an SVG | `menuIcon={() => <AcmeMark/>}` |
+
+`IconName` is `keyof typeof LucideIcons`, so the string form already covers the
+whole set — the cell is not tied to the hamburger. Reach for that when the app
+already has one in its header, where two hamburgers on one screen read as two
+different menus.
+
+```tsx
+<AppBottomNav items={bottomNavItems} menuLabel="Altro" menuIcon="LayoutGrid" />
+```
+
+**Why a function and not a `ReactNode`.** A string is itself a valid
+`ReactNode`, so `IconName | ReactNode` collapses to `ReactNode` and there is no
+way left to tell a lucide name from literal text. The function form keeps the
+union discriminable by `typeof menuIcon === "string"` — and one prop instead of
+two makes "both passed" unrepresentable rather than something to warn about.
+
+**The function is called, not rendered as a component.** Hooks inside it are
+not supported; in exchange an inline arrow is safe, which is how this gets
+written in practice — as an element type it would change identity on every
+render and remount the subtree.
+
+#### A glyph lucide does not have
+
+```tsx
+<AppBottomNav
+  items={bottomNavItems}
+  menuLabel="Acme"
+  menuIcon={() => <AcmeMark />}
+/>
+```
+
+Returning nullish falls back to the default glyph, so a conditional icon cannot
+leave the cell bare: the row's argument for a mandatory glyph is that a cell
+without one reads as a failed image, and that does not stop applying here.
+
+**The geometry stays the design system's; only the drawing is the app's.** What
+the function returns is rendered inside a box of exactly the size
+`Icon size="sm"` occupies — 20px, `shrink-0` — and a direct `<svg>` child is
+stretched to fill it (`[&>svg]:size-full`), which is the case the wrapper exists
+for: a pasted SVG carries its own `width`/`height` and would otherwise land at
+whatever those say. `preserveAspectRatio` defaults to `meet`, so a non-square
+viewBox is letterboxed inside the box rather than distorted. A child that is not
+a direct `<svg>` has to size itself; centring is handled either way. Measured on
+the `CustomMenuIconNode` story, which returns a 48×32 SVG on purpose: it renders
+at 20×20, the same box as the lucide glyph in the first cell.
+
+This is the one cell whose glyph the design system does not control, and so the
+one that can break the rhythm of the other five — a drawing with a different
+stroke weight or optical density will read as foreign next to five lucide
+glyphs, and no wrapper can fix that. `BottomNavItem.iconName` stays name-only
+for exactly that reason: the escape hatch is deliberately this cell's alone.
+**Prefer the string form wherever lucide has the shape.**
+
 ### Without the Menu cell
 
 The header trigger is not optional here — it is what keeps the mobile panel