basalt-ui 1.17.0 → 1.19.0

package/src/shell/nav-count-badge.tsx

@@ -0,0 +1,39 @@
+/**
+ * `NavCountBadge` — the sidebar/menu unread-count chip. Its own module rather than a member of the
+ * shell barrel so `app-mobile-nav.tsx` and `app-sidebar.tsx` can render it without importing the
+ * barrel that imports THEM (an ESM value cycle). `shell/index.tsx` re-exports it, so the published
+ * surface is unchanged.
+ */
+import { Badge } from '@mantine/core'
+import { VX } from '../tokens'
+
+/**
+ * Sidebar nav count badge (docs/DESIGN-SPEC.md §5): mono 10.5px, ink-8% bg, radius 5, height 16,
+ * padding 0 5px, muted text; `marginLeft: auto` pins it to the row end on any render path.
+ * `styles` (inline) rather than a token color prop, since none of Mantine's variant/color
+ * combinations land on the ink-tint idiom. Returns `null` for a zero/empty count so the badge slot
+ * stays clean ("ink earns its color", DESIGN.md).
+ */
+export function NavCountBadge({ count }: { count: number }) {
+  if (!count) return null
+  return (
+    <Badge
+      size="sm"
+      styles={{
+        root: {
+          backgroundColor: 'color-mix(in srgb, var(--vx-ink) 8%, transparent)',
+          color: 'var(--vx-muted)',
+          fontFamily: 'var(--basalt-font-mono)',
+          fontSize: VX.text.micro,
+          fontWeight: 500,
+          height: 16,
+          padding: '0 5px',
+          marginLeft: 'auto',
+          borderRadius: 'var(--vx-radius-tight)',
+        },
+      }}
+    >
+      {count}
+    </Badge>
+  )
+}

package/src/surfaces.ts

@@ -288,7 +288,7 @@ export const SURFACES = {
     skill: ['basalt-app'],
     guardKinds: [],
     description:
-      'TanStack Router bridge: useBasaltNav (active route) + useRouterBreadcrumbs + createSearchParamStore (single-select URL-state store) + createMultiSearchParamStore (multi-select URL-state store)',
+      'TanStack Router bridge: defineNav/navGroup/navTarget (one typed nav definition) + useNav (sections + mobileNav, spread onto BasaltShell) + useBasaltNav (active route) + useRouterBreadcrumbs + createSearchParamStore (single-select URL-state store) + createMultiSearchParamStore (multi-select URL-state store)',
     optionalPeers: ['@tanstack/react-router'],
     globs: {
       shipped: [],

package/src/theme/density-relations.test.ts

@@ -161,12 +161,28 @@ describe('Fix 4 — every interactive target clears the WCAG 2.5.8 24px floor at
     }
   })
 
-  test('the mobile header actions row (appHeaderMobileActionsHeight — the closest in-scope, density-tracked mobile nav target size; the app-mobile-nav tab bar itself is a fixed AppShell footer height, out of scope for this pass)', () => {
+  test('the mobile header actions row (appHeaderMobileActionsHeight)', () => {
     for (const level of ALL_LEVELS) {
       expect(deriveSpacing(level).step.appHeaderMobileActionsHeight).toBeGreaterThanOrEqual(24)
     }
   })
 
+  // The mobile bar's own two targets clear a HIGHER bar than WCAG 2.5.8's 24px: a thumb on a phone
+  // is not a mouse pointer, so `deriveSpacing` floors them at Apple HIG 44pt / WCAG 2.5.5 AAA
+  // instead. Without those floors the 1 + 0.1*level multiplier takes 56 -> 39 and 44 -> 31 at level
+  // -3 — both under even the 24px floor the rest of this block asserts.
+  test('the mobile nav bar height never drops below its own 48px floor', () => {
+    for (const level of ALL_LEVELS) {
+      expect(deriveSpacing(level).step.mobileNavBarHeight).toBeGreaterThanOrEqual(48)
+    }
+  })
+
+  test('a mobile nav menu/sheet row never drops below its own 44px floor', () => {
+    for (const level of ALL_LEVELS) {
+      expect(deriveSpacing(level).step.mobileNavRowHeight).toBeGreaterThanOrEqual(44)
+    }
+  })
+
   test('the resolved control/input height (size="md" Button/ActionIcon/Input) clears the floor too', () => {
     for (const level of ALL_LEVELS) {
       const { anchors } = deriveSpacing(level)
@@ -212,6 +228,8 @@ function oldLawFlatten(level: number): Record<string, number> {
     step[k] = scaleSpace(v, level, multiplier)
   }
   step['sidebarSearchTriggerHeight'] = Math.max(24, step['sidebarSearchTriggerHeight']!)
+  step['mobileNavBarHeight'] = Math.max(48, step['mobileNavBarHeight']!)
+  step['mobileNavRowHeight'] = Math.max(44, step['mobileNavRowHeight']!)
   step['stickyHeaderClearance'] = step['appShellHeaderHeight']! + anchors['stackMd']!
   step['stickyHeaderClearanceMobile'] = step['appShellHeaderMobileHeight']! + anchors['stackMd']!
   return { ...anchors, ...scale, ...step }

package/src/theme/index.ts

@@ -549,10 +549,10 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
       // panel-filled row read as a button sitting in the nav rather than as the current location.
       // Selection is carried by the tint + ink text + weight 600 + the accent icon instead. Forced
       // here at the THEME level via NavLink's `--nl-*` vars so it holds for every render path —
-      // including a consumer's router `<Link>` via `renderNavLink`, which never sees the shell CSS
-      // module; the active ICON is accent-colored via `nav-link.module.css` (targets the
-      // `[data-position='left']` leftSection, which the flat `vars`/`styles` API can't express
-      // conditionally on `[data-active]`).
+      // including a consumer's router `<Link>` hosted through `SidebarItem.Anchor`, which never
+      // sees the shell CSS module; the active ICON is accent-colored via `nav-link.module.css`
+      // (targets the `[data-position='left']` leftSection, which the flat `vars`/`styles` API
+      // can't express conditionally on `[data-active]`).
       //
       // `--nl-hover` (ink-13%) only ever reaches an ACTIVE row in practice — the inactive hover is
       // set at ink-6% by higher-specificity `:not([data-active])` rules in `nav-link.module.css` /
@@ -568,9 +568,10 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
           children: {},
         }),
         // Dense, rounded nav rows — applied at the THEME level so they survive EVERY render path,
-        // including a consumer's router `<Link>` via `renderNavLink`, which never sees the shell CSS
-        // module (the module's `.link` only reaches the shell's own fallback `<NavLink>`). Same
-        // reasoning as the `--nl-*` fill above: layout is single-sourced here, not in two places.
+        // including a consumer's router `<Link>` hosted through `SidebarItem.Anchor`, which never
+        // sees the shell CSS module (the module's `.link` only reaches the shell's own fallback
+        // `<NavLink>`). Same reasoning as the `--nl-*` fill above: layout is single-sourced here,
+        // not in two places.
         // The active-weight/shadow/icon-accent state selectors can't live in `styles` (flat inline
         // props only) — they're in nav-link.module.css, wired via `classNames` so they reach the
         // same every-render-path scope.

package/src/theme/nav-link.module.css

@@ -5,7 +5,8 @@
  * tint rather than as a button, so the row never competes with the real filled controls around it.
  *
  * Applied at the THEME level via `classNames` so it reaches EVERY NavLink render path — including a
- * consumer's router `<Link>` mounted through `renderNavLink`, which a shell-scoped CSS module never
+ * consumer's router `<Link>` mounted through `SidebarItem.Anchor`, which a shell-scoped CSS
+ * module never
  * sees. Mantine's `styles` prop only takes flat inline properties (a nested `&[data-active]` there
  * throws a React warning), so the state selectors live here. React Router's NavLink marks the
  * active item via `aria-current` rather than the `active` prop's `data-active`, so both states are
@@ -42,7 +43,8 @@
 
 /*
  * Inactive hover — the ink-6% ghost tint + ink text/icon (docs/DESIGN-SPEC.md §5). Lives here (not
- * only in the shell module) so a consumer's `renderNavLink` path gets the same hover; Mantine's own
+ * only in the shell module) so a consumer's `SidebarItem.Anchor` path gets the same hover;
+ * Mantine's own
  * hover fill uses `:where(scheme) .m_*:hover` (gray-0/dark-6), which this outranks on specificity.
  * Active rows keep their panel fill + `--nl-hover` untouched.
  */

package/src/theme/spacing.test.ts

@@ -352,6 +352,13 @@ const SPACE_STEP_SWEEP: ReadonlyArray<
   ['appShellNavbarWidth', 216, null],
   ['appShellNavbarRailWidth', 48, null],
   ['mobileNavTabGap', 3, 'space-mobile-nav-tab-gap'],
+  // JS-number-only, and for the same two reasons the six above are: `shell/index.tsx` hands
+  // `mobileNavBarHeight` to AppShell's `footer.height` (a number, not a `var()` string), and
+  // `app-mobile-nav.tsx` hands `mobileNavMenuWidth` to `<Menu width={…}>`.
+  ['mobileNavBarHeight', 56, null],
+  ['mobileNavIconSize', 24, 'space-mobile-nav-icon-size'],
+  ['mobileNavRowHeight', 44, 'space-mobile-nav-row-height'],
+  ['mobileNavMenuWidth', 232, null],
   ['agentRailInsetX', 10, 'space-agent-rail-inset-x'],
   ['agentPartGapTop', 6, 'space-agent-part-gap-top'],
   ['agentCodeInset', 8, 'space-agent-code-inset'],
@@ -404,6 +411,8 @@ describe('SPACE_STEP CSS-module spacing-sweep one-offs match the shipped identit
       'appShellHeaderMobileHeight',
       'appShellNavbarWidth',
       'appShellNavbarRailWidth',
+      'mobileNavBarHeight',
+      'mobileNavMenuWidth',
       'chartLegendGap',
       'chartMarginTop',
       'chartMarginRight',
@@ -420,6 +429,8 @@ describe('SPACE_STEP CSS-module spacing-sweep one-offs match the shipped identit
     expect(css).not.toContain('--vx-space-app-shell-header-mobile-height')
     expect(css).not.toContain('--vx-space-app-shell-navbar-width')
     expect(css).not.toContain('--vx-space-app-shell-navbar-rail-width')
+    expect(css).not.toContain('--vx-space-mobile-nav-bar-height')
+    expect(css).not.toContain('--vx-space-mobile-nav-menu-width')
     expect(css).not.toContain('--vx-space-chart-legend-gap')
     expect(css).not.toContain('--vx-space-progress-bar-size')
     expect(css).not.toContain('--vx-space-timeline-bullet')

package/src/tokens/density.test.ts

@@ -239,6 +239,8 @@ describe('buildDensityCss', () => {
       'space-app-shell-header-mobile-height',
       'space-app-shell-navbar-width',
       'space-app-shell-navbar-rail-width',
+      'space-mobile-nav-bar-height', // AppShell footer.height prop
+      'space-mobile-nav-menu-width', // Menu width prop
       'space-chart-legend-gap', // VX.legendGap / VX.margin / VX.dotR — visx SVG props
       'space-chart-margin-top',
       'space-chart-margin-right',

package/src/tokens/index.ts

@@ -400,14 +400,15 @@ function frameworkPrimitives(side: Side, data: PaletteData, legacyAliases: boole
  * only invite someone to think it does.
  *
  * Deliberately DOES NOT emit a var for every `SpaceValues` number — `space.scale.*` (the generic
- * Mantine spacing scale) and fourteen `space.step.*` keys have ZERO `var()` consumers anywhere in
+ * Mantine spacing scale) and seventeen `space.step.*` keys have ZERO `var()` consumers anywhere in
  * the framework or its tests beyond the CSS-emission test itself. Each is read straight off the
  * resolved `SpaceValues` as a JS NUMBER instead, in one of three ways:
  * `{timelineBullet,progressBarSize}` are Mantine `defaultProps` (`theme/index.ts`'s Timeline/
- * Progress); `{sidebarAccountMenuWidth,sidebarSettingsMenuWidth,appShellHeaderHeight,
- * appShellHeaderMobileHeight,appShellNavbarWidth,appShellNavbarRailWidth}` are numeric Mantine
- * component props (Menu `width`, AppShell `header`/`navbar`); and `{chartLegendGap,chartMarginTop,
- * chartMarginRight,chartMarginBottom,chartMarginLeft,chartDotR}` are visx SVG props via
+ * Progress); `{sidebarAccountMenuWidth,sidebarSettingsMenuWidth,mobileNavMenuWidth,
+ * appShellHeaderHeight,appShellHeaderMobileHeight,appShellNavbarWidth,appShellNavbarRailWidth,
+ * mobileNavBarHeight}` are numeric Mantine component props (Menu `width`, AppShell `header`/
+ * `navbar`/`footer`); and `{chartLegendGap,chartMarginTop,chartMarginRight,chartMarginRightAxis,
+ * chartMarginBottom,chartMarginLeft,chartDotR}` are visx SVG props via
  * `VX.legendGap`/`VX.margin`/`VX.dotR` in this file's own `VX` object. The full list is locked
  * against the `SpaceValues` key set by `tokens/density.test.ts`'s declaration-set test, so adding a
  * one-off silently omits nothing. A `--vx-space-*` declaration for any of them would be dead weight
@@ -531,6 +532,8 @@ function spaceDecls(space: SpaceValues): string[] {
     decl('space-sidebar-child-row-indent', `${space.step.sidebarChildRowIndent}px`),
     decl('space-app-header-mobile-actions-height', `${space.step.appHeaderMobileActionsHeight}px`),
     decl('space-mobile-nav-tab-gap', `${space.step.mobileNavTabGap}px`),
+    decl('space-mobile-nav-icon-size', `${space.step.mobileNavIconSize}px`),
+    decl('space-mobile-nav-row-height', `${space.step.mobileNavRowHeight}px`),
     decl('space-agent-rail-inset-x', `${space.step.agentRailInsetX}px`),
     decl('space-agent-part-gap-top', `${space.step.agentPartGapTop}px`),
     decl('space-agent-code-inset', `${space.step.agentCodeInset}px`),

package/src/tokens/palette.ts

@@ -609,6 +609,17 @@ const SPACE_STEP_BASE = {
   // ── shell/app-mobile-nav.module.css ───────────────────────────────────────────────────────────
   /** Tab's icon-to-label gap. */
   mobileNavTabGap: 3,
+  /** Bar height, EXCLUDING the safe-area inset — Mantine's own `AppShell.footer` rule adds
+   *  `env(safe-area-inset-bottom)` to it. JS-consumed (AppShell `footer.height`), no `--vx-*` var,
+   *  same shape as `appShellHeaderHeight`. Floored at 48px in `deriveSpacing`. */
+  mobileNavBarHeight: 56,
+  /** Slot icon box. */
+  mobileNavIconSize: 24,
+  /** Menu/sheet row height. Floored at 44px in `deriveSpacing` (Apple HIG 44pt / WCAG 2.5.5 AAA). */
+  mobileNavRowHeight: 44,
+  /** More/group `<Menu width={…}>`. JS-consumed, no var — same rationale as
+   *  `sidebarSettingsMenuWidth` directly above. */
+  mobileNavMenuWidth: 232,
 
   // ── charts (tokens/index.ts's `VX` object — structural, tracks density) ──────────────────────
   // `VX.lineWidth`/`VX.line2Width` are DELIBERATELY absent here — they are stroke WEIGHTS (line
@@ -927,6 +938,11 @@ export function deriveSpacing(level: number): SpaceValues {
   // WCAG 2.5.8 minimum interactive-target size — see this function's doc for why the trigger's
   // density-tracking height alone can't be trusted to stay accessible at a negative level.
   mappedStep.sidebarSearchTriggerHeight = Math.max(24, mappedStep.sidebarSearchTriggerHeight)
+  // Touch targets: the 1 + 0.1*level multiplier would take 56 -> 39 and 44 -> 31 at level -3,
+  // silently breaking the minimum interactive-target size. Same guardrail, same reason, as the
+  // sidebar search trigger's 24px floor directly above.
+  mappedStep.mobileNavBarHeight = Math.max(48, mappedStep.mobileNavBarHeight)
+  mappedStep.mobileNavRowHeight = Math.max(44, mappedStep.mobileNavRowHeight)
   const step: SpaceValues['step'] = {
     ...mappedStep,
     // RESPONSIVE, one per AppShell breakpoint — each DERIVED from its own header, plus