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

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

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

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