laif-ds 1.0.0 → 1.0.2

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

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

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

@@ -46,9 +46,9 @@ This document provides a complete mapping of all components available in the lai
 ### Layout & Structure Components
 
 - **Accordion** - Collapsible content panels for organizing information hierarchically
-- **AppBottomNav** - Mobile bottom navigation bar (`md:hidden`, in the normal flow as the last child of `SidebarInset`): six equal cells — up to 5 primary destinations plus a Menu cell that opens `AppSidebar`'s mobile panel, optionally already drilled into a level, or up to 6 destinations with `showMenu={false}` when the app opens that panel from its own header
+- **AppBottomNav** - Mobile bottom navigation bar (`md:hidden`, in the normal flow as the last child of `SidebarInset`): six equal cells — up to 5 primary destinations plus a Menu cell that opens `AppSidebar`'s mobile panel, optionally already drilled into a level, or up to 6 destinations with `showMenu={false}` when the app opens that panel from its own header, with an optional badge per cell (`badge`: a count as a superscript on the glyph, `99+` past 99, short text degrading to a dot) and `menuBadge` for a dot on the Menu cell, OR-ed with the badged items dropped past the cell budget
 - **AppCard** - Enhanced card component with variant styles, semantic states, size control, and loading skeleton support
-- **AppSidebar** - Application sidebar navigation component, with groups rendered as a stacked list or as a tab bar (`navigationDisplay="tab"`, one group at a time, only the selected tab labelled and animated open to fit it, `navigationFooter` always visible), optional icon-only collapse (`collapsible="icon"`: tooltips on top-level items, dropdown for sub-items) and, below 768px, a Settings-style mobile menu (grouped cards, 44px rows, drill-down on sub-items)
+- **AppSidebar** - Application sidebar navigation component, with groups rendered as a stacked list or as a tab bar (`navigationDisplay="tab"`, one group at a time, only the selected tab labelled and animated open to fit it, `navigationFooter` always visible), optional icon-only collapse (`collapsible="icon"`: tooltips on top-level items, dropdown for sub-items), optional hover expansion over that (`expandOnHover`: the pointer or the focus expands the panel as an overlay that does not move the page, a Pin in the header makes it permanent, `pinned`/`defaultPinned`/`onPinnedChange` alias the primitive's `open`) and, below 768px, a Settings-style mobile menu (grouped cards, 44px rows, drill-down on sub-items), plus an optional badge on every row and group (`badge`: `number | string | true` with `badgeLabel` for the spoken form, degrading per surface — pill when expanded, dot in the icon rail with the value in the tooltip, superscript in `AppBottomNav` — and never aggregating counts)
 - **AppStepper** - Step-by-step progress indicator for multi-step processes
 - **AspectRatio** - Container that maintains a specific aspect ratio for responsive layouts
 - **Breadcrumb** - Breadcrumb navigation component for hierarchical navigation
@@ -152,6 +152,7 @@ The following components are marked as deprecated and should not be used in new
 - **MultipleSelector** - ~~Use `AppSelect` instead~~
 - **AppMultipleSelectDropdown** - ~~Use `AppSelect` instead~~
 - **ResizePrompt** - ~~Use alternative resize handling methods~~
+- **SidebarMenuBadge** - ~~Use `NavItem.badge` instead~~ (on `AppSidebar`, with `badgeLabel` for the spoken form; the primitive stays exported and functional, but it is hidden in icon mode and has no spoken form — see `Sidebar.md`)
 
 ---
 

package/dist/agent-docs/manifest.json

@@ -1,20 +1,21 @@
 {
   "schemaVersion": "1.1.0",
-  "generatedAt": "2026-09-02T16:31:00.468Z",
+  "generatedAt": "2026-09-18T09:11:12.439Z",
   "package": {
     "name": "laif-ds",
-    "version": "1.0.0"
+    "version": "1.0.2"
   },
   "stats": {
     "documentedComponentCount": 94,
-    "catalogedComponentCount": 93,
-    "missingFromDocsCount": 1,
+    "catalogedComponentCount": 94,
+    "missingFromDocsCount": 2,
     "deprecatedComponentCount": 2,
     "averageAiReadinessScore": 56.17,
     "highAiReadinessCount": 38,
     "lowAiReadinessCount": 41
   },
   "missingFromDocs": [
+    "SidebarMenuBadge",
     "TruncatedCell"
   ],
   "components": [
@@ -286,8 +287,9 @@
         "exampleTitles": [
           "`BottomNavItem`",
           "Layout",
-          "Icon size: a deliberate divergence from the native baselines",
+          "Icon size",
           "Active state",
+          "Badges",
           "Opening the menu",
           "Accessibility",
           "Motion",
@@ -295,6 +297,7 @@
           "Edge cases",
           "App shell",
           "Localised copy",
+          "A Menu cell of the app's own",
           "Without the Menu cell"
         ],
         "controlledPattern": "likely-controlled",
@@ -307,10 +310,10 @@
       },
       "metadata": {
         "props": {
-          "totalProps": 15,
+          "totalProps": 19,
           "requiredPropsCount": 4,
-          "typedPropsCount": 15,
-          "describedPropsCount": 14
+          "typedPropsCount": 19,
+          "describedPropsCount": 18
         },
         "accessibility": {
           "hasCoverage": true
@@ -1016,6 +1019,10 @@
             "title": "Behavior",
             "slug": "behavior"
           },
+          {
+            "title": "Badges (`badge` / `badgeLabel`)",
+            "slug": "badges-badge-badgelabel"
+          },
           {
             "title": "Navigation display (`navigationDisplay`)",
             "slug": "navigation-display-navigationdisplay"
@@ -1024,6 +1031,10 @@
             "title": "Icon mode (`collapsible=\"icon\"`)",
             "slug": "icon-mode-collapsible-icon"
           },
+          {
+            "title": "Hover expansion (`expandOnHover`)",
+            "slug": "hover-expansion-expandonhover"
+          },
           {
             "title": "Mobile menu (`<768px`)",
             "slug": "mobile-menu-768px"
@@ -1041,8 +1052,24 @@
         "hasExamples": true,
         "exampleTitles": [
           "Icons: `iconName` or `icon`",
+          "The three forms",
+          "Degradation per surface",
+          "Counts never aggregate",
+          "Colour and geometry",
+          "Accessibility",
+          "Live counts vs static ones, and who announces them",
+          "What this deliberately does not do",
           "The group selector (`navigationDisplay=\"tab\"` + `collapsible=\"icon\"`, collapsed)",
+          "The peek is an overlay, the pin is a push",
+          "Preconditions",
+          "Timing",
+          "The Pin",
+          "`pinned` is `open`",
+          "Keyboard and focus",
+          "Menus that live in a portal",
+          "Other things worth knowing",
           "Basic",
+          "With badges",
           "With Header/Footer Content"
         ],
         "controlledPattern": "controlled-uncontrolled-documented",
@@ -1052,10 +1079,10 @@
       },
       "metadata": {
         "props": {
-          "totalProps": 11,
+          "totalProps": 21,
           "requiredPropsCount": 1,
-          "typedPropsCount": 11,
-          "describedPropsCount": 11
+          "typedPropsCount": 21,
+          "describedPropsCount": 19
         },
         "accessibility": {
           "hasCoverage": true
@@ -1064,10 +1091,11 @@
           "coveredStates": [
             "hover",
             "focus",
+            "disabled",
             "empty",
             "selected"
           ],
-          "coveredStateCount": 4
+          "coveredStateCount": 5
         }
       },
       "aiReadiness": {
@@ -5080,6 +5108,14 @@
             "title": "Behavior",
             "slug": "behavior"
           },
+          {
+            "title": "`SidebarMenuBadge` is deprecated",
+            "slug": "sidebarmenubadge-is-deprecated"
+          },
+          {
+            "title": "Peek — `useSidebar().peek` / `setPeek`",
+            "slug": "peek-usesidebar-peek-setpeek"
+          },
           {
             "title": "Example",
             "slug": "example"
@@ -5092,7 +5128,7 @@
         "hasPropsTable": false,
         "hasExamples": false,
         "exampleTitles": [],
-        "controlledPattern": "not-specified",
+        "controlledPattern": "likely-controlled",
         "requiredProps": []
       },
       "metadata": {
@@ -5107,9 +5143,10 @@
         },
         "states": {
           "coveredStates": [
+            "hover",
             "focus"
           ],
-          "coveredStateCount": 1
+          "coveredStateCount": 2
         }
       },
       "aiReadiness": {
@@ -6275,5 +6312,5 @@
       ]
     }
   ],
-  "checksum": "7347dd0e46eb44f6186c98afd32585008fadbbbcdcb7909e342274f93f42e45d"
+  "checksum": "1b95270b522d7fdbd54fa834020be6d9bf1b0632fda8a9458556d024398a8574"
 }

package/dist/components/design-tokens.js

@@ -70,70 +70,6 @@ const e = {
   badge: {
     base: "inline-flex items-center justify-center border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 gap-1"
   },
-  // Navigation rows (sidebar / menu lists) specific.
-  //
-  // Not `dropdownItem.selected`: that one paints the accent colour *on a 10%
-  // dilution of itself* — measured 1.85:1 in light, 3.28 tangerine, 4.23
-  // claymorphism, 6.62 dark. Fine as a chip inside a dropdown, unreadable as a
-  // row label. Here the tint stays on the surface and the label keeps
-  // full-contrast `text-d-foreground` (12.19 / 10.35 / 9.35 / 10.22).
-  //
-  // The bar is `d-foreground`, not `d-primary`, for the same reason: in the
-  // light theme `--d-primary` is a pale cyan that measures 1.85:1 against the
-  // tinted row, so a primary bar would fail WCAG 1.4.11 (>= 3:1 for a non-text
-  // indicator) in the default theme. Shape and position carry the state; the
-  // tint adds the brand colour on top where the theme can afford it.
-  //
-  // `base` goes on every row so the selected row's 2px does not shift content.
-  navItem: {
-    base: "border-l-2 border-l-transparent",
-    selected: "bg-d-primary/10 border-l-d-foreground text-d-foreground font-semibold",
-    // A bottom bar's cells are columns, not rows, so the left rule has no edge
-    // to run along and the state has to be carried by the cell's own surface: a
-    // pill, no border on any side.
-    //
-    // The pill is the sidebar row's own state, ported: `bg-d-sidebar-accent` +
-    // `text-d-sidebar-accent-foreground` + a bold label, which is exactly what
-    // `sidebarMenuButtonVariants` paints under `data-[active=true]`. One
-    // vocabulary for "you are here" across the two navigations, which is worth
-    // more than either surface being optimal on its own.
-    //
-    // What comes with it is the sidebar's contrast, and it is very low.
-    // `--d-sidebar-accent` is `--colors--surface--tertiary` at 40% alpha, so on
-    // the bar (`d-card`, #fafafa light / #1f1f1f dark) it composites to #efefef
-    // and #2f2f2f — **1.10:1 in light and 1.23:1 in dark**, far under the 3:1 of
-    // WCAG 1.4.11 for a non-text state indicator. That is not a regression
-    // introduced here: 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. The label is never at risk either
-    // way — `--d-sidebar-accent-foreground` is `--colors--text--body-primary`,
-    // the colour the inactive cells already use, 11.9:1 on the composited fill.
-    //
-    // `font-bold` and not `semibold`: with a fill this faint the weight is the
-    // state, and it is the sidebar's own value. 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.
-    //
-    // Measured alternatives, for whenever the 3:1 floor has to be met.
-    // `bg-d-primary` + `text-d-primary-foreground`: 1.98:1 light / 7.99:1 dark —
-    // the brand fill this replaced, under the floor in light but separating by
-    // hue, which 1.4.11 does not measure. `bg-d-foreground` + `text-d-background`:
-    // 13.01:1 / 12.49:1 — conforming, but it reads as a selected chip rather
-    // than the current tab and leaves the bar with no brand. Not a tint of
-    // primary: /10 is 1.07:1 light, /40 still 1.30:1, solid `bg-d-accent` 1.26:1.
-    //
-    // `rounded-md` (6px, = `radius.default`) and not `radius.sm`: `sm` is 4px in
-    // the v4 build and 2px in the v3 one, and this would be the single place
-    // where the two CSS bundles disagree. Not `rounded-d-md` either — that maps
-    // onto `--d-radius` and becomes 18px under claymorphism, while the dock it
-    // sits inside is a fixed `rounded-t-lg`.
-    //
-    // `basePill` reserves nothing (there is no border to reserve), so activating
-    // a cell cannot shift its content; it is there so every cell shares the
-    // radius and only the fill changes.
-    basePill: "rounded-md",
-    selectedPill: "bg-d-sidebar-accent text-d-sidebar-accent-foreground font-bold"
-  },
   // Dropdown item specific
   dropdownItem: {
     selected: "bg-d-primary/10 text-d-primary font-medium data-[selected=true]:text-d-primary data-[selected=true]:bg-d-primary/30 hover:text-d-primary hover:bg-d-primary/30",

package/dist/components/nav-tokens.js

@@ -0,0 +1,41 @@
+"use client";
+const e = {
+  /**
+   * The state of a navigation item, in the two shapes the surfaces need: a left
+   * rule for a vertical list, a pill for a horizontal bar.
+   */
+  item: {
+    // The bar is `d-foreground`, not `d-primary`: in the light theme
+    // `--d-primary` measures 1.85:1 against the tinted row and a primary bar
+    // would fail WCAG 1.4.11 (>= 3:1 for a non-text indicator).
+    // `base` goes on every row so the selected row's 2px does not shift content.
+    base: "border-l-2 border-l-transparent",
+    selected: "bg-d-primary/10 border-l-d-foreground text-d-foreground font-semibold",
+    // Duplicates what `sidebarMenuButtonVariants` paints under
+    // `data-[active=true]` in `sidebar.tsx` — two copies of "you are here", by
+    // decision. The fill is ~1.1:1, under WCAG 1.4.11's 3:1, so `font-bold`
+    // carries the state and the tint is only a hint. `rounded-md` and not
+    // `radius.sm` (4px in v4, 2px in v3) nor `rounded-d-md` (18px in clay).
+    basePill: "rounded-md",
+    selectedPill: "bg-d-sidebar-accent text-d-sidebar-accent-foreground font-bold"
+  },
+  /**
+   * The icon rail at 3rem, where the glyph carries the whole row. One home for
+   * the geometry because `sidebarMenuButtonVariants`, the two initial-letter
+   * fallbacks in `app-sidebar.tsx` and the group selector must agree on it.
+   */
+  rail: {
+    // The content box is exactly the glyph (`32 - 2*6 = 20`), and that equality
+    // is the centring mechanism: the label stays mounted as a `flex-1` sibling,
+    // so any slack in the box is claimed by the label and pushes every glyph
+    // off-centre. Change one of the three numbers and the other two follow.
+    button: "group-data-[collapsible=icon]:!size-8 group-data-[collapsible=icon]:!p-1.5 group-data-[collapsible=icon]:mx-auto group-data-[collapsible=icon]:[&>svg]:size-5",
+    // Sized to the rail's content box in both states, for the same reason: a
+    // 16px box in the rail's 20px content box leaves 4px for the label to claim
+    // and that row's letter sits left of every glyph above it.
+    fallbackGlyph: "size-4 group-data-[collapsible=icon]:size-5 group-data-[collapsible=icon]:text-sm"
+  }
+};
+export {
+  e as navTokens
+};