basalt-ui 1.25.0 → 1.26.0

package/src/shell/mobile-nav-model.test.ts

@@ -13,9 +13,26 @@
  *  - a `disabled` destination that is silently dropped instead of rendered disabled (rule 11).
  */
 import { describe, expect, test } from 'bun:test'
-import { MOBILE_MORE_KEY, projectMobileNav } from './mobile-nav-model'
+import { MOBILE_MORE_KEY, blockRowCount, projectMobileNav } from './mobile-nav-model'
 import type { ProjectMobileNavOptions } from './mobile-nav-model'
-import type { MobileNavGroup, MobileNavModel, MobileNavSlot, SidebarItem } from '../nav/types'
+import {
+  sidebarBlockFoldKey,
+  sidebarBlockMobile,
+  sidebarBlockPlacement,
+  sidebarBlockRail,
+  sidebarBlockVisibleCount,
+  sidebarSectionFoldKey,
+  slugifyLabel,
+} from './sidebar-block-model'
+import type {
+  MobileNavGroup,
+  MobileNavModel,
+  MobileNavSlot,
+  SidebarCustomBlock,
+  SidebarItem,
+  SidebarListBlock,
+  SidebarProgressBlock,
+} from '../nav/types'
 
 // ── fixtures ─────────────────────────────────────────────────────────────────────────────────────
 
@@ -258,9 +275,34 @@ describe('projectMobileNav', () => {
     expect(rowKeys(more.groups)).toEqual(['reports', 'daily', 'weekly'])
   })
 
-  /** Rule 12 — today's `items.some(i => i.active)` leaves the tab dark while a child route is
-   *  open, which reads as "you are nowhere". A slot is active when ANY destination under it is. */
-  test('12. a slot is active when a NESTED child is the active destination', () => {
+  /**
+   * Rule 12 — a slot is active when the active destination is one it COVERS, and coverage and
+   * activeness read the SAME set. See `hasActiveDestination`'s doc for why they used to differ and
+   * what that cost (two `aria-current="page"` tabs at `/dashboard/sessions`, measured in Chrome).
+   *
+   * A SECTION tab covers its whole pruned tree, so the rollup rule 12 was written for still holds
+   * there — that is the case below.
+   */
+  test('12. a SECTION slot is active when a NESTED child is the active destination', () => {
+    const model = projectMobileNav([
+      {
+        label: 'Main',
+        mobile: { tab: true },
+        items: [item('reports', { children: [item('daily', { active: true })] })],
+      },
+      { label: 'Other', items: [item('other', { mobile: 'tab' })] },
+    ])
+
+    expect(slotAt(model, 0).active).toBe(true)
+    expect(slotAt(model, 1).active).toBe(false)
+  })
+
+  /**
+   * The exclusivity half, and the one that was missing: an ITEM tab covers only the destination its
+   * tap navigates to, so a nested child that lives in the overflow lights the OVERFLOW slot instead.
+   * Lighting both was the defect — a bar cannot tell a reader they are in two places.
+   */
+  test('12. an ITEM tab does NOT light for a child it cannot navigate to — that child’s slot does', () => {
     const model = projectMobileNav([
       {
         label: 'Main',
@@ -271,8 +313,67 @@ describe('projectMobileNav', () => {
       },
     ])
 
-    expect(slotAt(model, 0).active).toBe(true)
-    expect(slotAt(model, 1).active).toBe(false)
+    const active = model.slots.filter((slot) => slot.active)
+    expect(active.length).toBe(1)
+    expect(active[0]?.key).toBe('daily')
+    expect(slotAt(model, 0).active).toBe(false)
+  })
+
+  /**
+   * The invariant, stated once over every shape this model produces: AT MOST ONE slot is active.
+   * `useNav` already guarantees exactly one active DESTINATION (`use-nav.test.tsx`); this is the
+   * projection's half of the same law, and it is what a rendered bar actually shows.
+   */
+  test('12. at most ONE slot is active, for every destination in a mixed definition', () => {
+    const sections = (activeKey: string) => [
+      {
+        label: 'Overview',
+        items: [
+          item('dashboard', {
+            mobile: 'tab' as const,
+            active: activeKey === 'dashboard',
+            children: [
+              item('sessions', { active: activeKey === 'sessions' }),
+              item('traffic', { active: activeKey === 'traffic' }),
+            ],
+          }),
+          item('activity', { mobile: 'tab' as const, active: activeKey === 'activity' }),
+        ],
+      },
+      {
+        label: 'Batteries',
+        mobile: { tab: true as const },
+        items: [
+          item('query', { active: activeKey === 'query' }),
+          item('router', { active: activeKey === 'router' }),
+          item('forms', { active: activeKey === 'forms' }),
+        ],
+      },
+      {
+        label: 'System',
+        items: [
+          item('settings', { active: activeKey === 'settings' }),
+          item('user', { active: activeKey === 'user' }),
+        ],
+      },
+    ]
+
+    const keys = [
+      'dashboard',
+      'sessions',
+      'traffic',
+      'activity',
+      'query',
+      'router',
+      'forms',
+      'settings',
+      'user',
+    ] as const
+    for (const key of keys) {
+      const model = projectMobileNav(sections(key))
+      const active = model.slots.filter((slot) => slot.active)
+      expect({ key, count: active.length }).toEqual({ key, count: 1 })
+    }
   })
 
   /** §2.4 — a five-slot bar is ~72px wide, so the bar label is `short` when the consumer supplied
@@ -294,3 +395,123 @@ describe('projectMobileNav', () => {
     expect(slotAt(model, 1).short).toBe('Activity')
   })
 })
+
+/**
+ * `blockRowCount` — the `accountRowCount` sibling for sidebar blocks (`docs/CONTROLS-SPEC.md`
+ * §2.3). It exists for one reason: `BasaltShell` needs the More-surface row count BEFORE the
+ * projection runs, because that count is what picks `menu` vs `sheet` against `menuMax`. A second,
+ * independent estimate of the same rows is exactly how a "1 row" account shipped a 9-row menu into
+ * headroom sized for 6.
+ */
+/** A three-item list block, the shape every row-count case counts against. */
+const list = (extra: Partial<SidebarListBlock> = {}): SidebarListBlock => ({
+  kind: 'list',
+  key: extra.key ?? 'awaiting',
+  label: 'Awaiting action',
+  items: [
+    { key: 'a', label: 'A' },
+    { key: 'b', label: 'B' },
+    { key: 'c', label: 'C' },
+  ],
+  ...extra,
+})
+
+describe('blockRowCount', () => {
+  test('undefined and an empty list are both zero', () => {
+    expect(blockRowCount(undefined)).toBe(0)
+    expect(blockRowCount([])).toBe(0)
+  })
+
+  test('ONE row per list block, never one per item — the row opens a nested sheet', () => {
+    expect(blockRowCount([list(), list({ key: 'second' })])).toBe(2)
+  })
+
+  test("mobile:'hidden' drops a list; a progress block is hidden until it asks otherwise", () => {
+    expect(blockRowCount([list({ mobile: 'hidden' })])).toBe(0)
+    const progress: SidebarProgressBlock = {
+      kind: 'progress',
+      key: 'onboarding',
+      label: 'Getting started',
+      value: 1,
+      total: 5,
+    }
+    expect(blockRowCount([progress])).toBe(0)
+    expect(blockRowCount([{ ...progress, mobile: 'more' }])).toBe(1)
+  })
+
+  test('a custom block never reaches mobile — it is desktop-only by kind', () => {
+    expect(blockRowCount([{ kind: 'custom', key: 'tree', node: null }])).toBe(0)
+  })
+
+  /** Same rule the renderer applies: an empty list would open a sheet with nothing in it. */
+  test('an empty list block contributes no row', () => {
+    expect(blockRowCount([list({ items: [] })])).toBe(0)
+  })
+
+  /** The threshold this number exists to move, asserted end to end against the projection. */
+  test('block rows push a six-destination More over the threshold into a sheet', () => {
+    const sections = [{ label: 'Main', items: [item('a', { mobile: 'tab' }), ...items(6)] }]
+    expect(slotAt(projectMobileNav(sections), 1).kind).toBe('menu')
+    expect(
+      slotAt(projectMobileNav(sections, { extraMoreRows: blockRowCount([list()]) }), 1).kind,
+    ).toBe('sheet')
+  })
+})
+
+/**
+ * The block-default resolvers. Three call sites read them — the sidebar (placement + rail), the
+ * renderer (paint) and `blockRowCount` (the count above) — and a default re-derived per call site
+ * is how the count and the renderer drift apart.
+ */
+describe('sidebar block defaults', () => {
+  const listBlock: SidebarListBlock = { kind: 'list', key: 'k', label: 'L', items: [] }
+  const progressBlock: SidebarProgressBlock = {
+    kind: 'progress',
+    key: 'p',
+    label: 'P',
+    value: 1,
+    total: 5,
+  }
+  const customBlock: SidebarCustomBlock = { kind: 'custom', key: 'c', node: null }
+
+  test('placement: list/custom default to nav, progress to bottom', () => {
+    expect(sidebarBlockPlacement(listBlock)).toBe('nav')
+    expect(sidebarBlockPlacement(customBlock)).toBe('nav')
+    expect(sidebarBlockPlacement(progressBlock)).toBe('bottom')
+    expect(sidebarBlockPlacement({ ...listBlock, placement: 'bottom' })).toBe('bottom')
+  })
+
+  test('rail: a dot only for a list with BOTH a count and an icon, a ring for progress', () => {
+    expect(sidebarBlockRail(listBlock)).toBe('hidden')
+    expect(sidebarBlockRail({ ...listBlock, count: 3, icon: null })).toBe('dot')
+    expect(sidebarBlockRail({ ...listBlock, count: 3, icon: null, rail: 'hidden' })).toBe('hidden')
+    // Neither half alone earns one — and an explicit `rail: 'dot'` cannot conjure the node either.
+    expect(sidebarBlockRail({ ...listBlock, count: 3 })).toBe('hidden')
+    expect(sidebarBlockRail({ ...listBlock, icon: null })).toBe('hidden')
+    expect(sidebarBlockRail({ ...listBlock, rail: 'dot' })).toBe('hidden')
+    expect(sidebarBlockRail(progressBlock)).toBe('ring')
+    expect(sidebarBlockRail({ ...progressBlock, rail: 'hidden' })).toBe('hidden')
+    expect(sidebarBlockRail(customBlock)).toBe('hidden')
+  })
+
+  test('mobile: a list is reachable from More by default, progress and custom are not', () => {
+    expect(sidebarBlockMobile(listBlock)).toBe('more')
+    expect(sidebarBlockMobile({ ...listBlock, mobile: 'hidden' })).toBe('hidden')
+    expect(sidebarBlockMobile(progressBlock)).toBe('hidden')
+    expect(sidebarBlockMobile({ ...progressBlock, mobile: 'more' })).toBe('more')
+    expect(sidebarBlockMobile(customBlock)).toBe('hidden')
+  })
+
+  test('visible count honours max, and a max past the count changes nothing', () => {
+    expect(sidebarBlockVisibleCount(6, 3)).toBe(3)
+    expect(sidebarBlockVisibleCount(6, undefined)).toBe(6)
+    expect(sidebarBlockVisibleCount(2, 9)).toBe(2)
+  })
+
+  /** The fold keys are a consumer-readable contract — a rename resets every user's sidebar. */
+  test('the fold keys namespace to basalt:sidebar-block:<key> / basalt:sidebar-section:<slug>', () => {
+    expect(sidebarBlockFoldKey('awaiting')).toBe('sidebar-block:awaiting')
+    expect(sidebarSectionFoldKey('Tools & More')).toBe('sidebar-section:tools-more')
+    expect(slugifyLabel('  Awaiting Action! ')).toBe('awaiting-action')
+  })
+})

package/src/shell/mobile-nav-model.ts

@@ -19,9 +19,11 @@ import type {
   MobileNavModel,
   MobileNavSlot,
   NavMobilePlacement,
+  SidebarBlock,
   SidebarItem,
   SidebarSection,
 } from '../nav/types'
+import { sidebarBlockMobile } from './sidebar-block-model'
 
 /** Hard cap on bar slots, INCLUDING More. Five 72px slots is the widest a 360px viewport holds. */
 export const MOBILE_MAX_TABS_DEFAULT = 5
@@ -39,13 +41,33 @@ export const MOBILE_MORE_KEY = '__more'
 export type ProjectMobileNavOptions = {
   config?: MobileNavConfig | undefined
   /**
-   * Extra rows the More surface will hold — account + settings + `moreExtra`. Drives both
+   * Extra rows the More surface will hold — account + settings + sidebar blocks. Drives both
    * `needsMore` and the menu-vs-sheet threshold. The model cannot see those rows (they are
    * Mantine-rendered chrome, not `SidebarItem`s), so the shell counts them and passes the total.
    */
   extraMoreRows?: number
 }
 
+/**
+ * How many More-surface rows `blocks` contribute — the `accountRowCount` sibling for sidebar
+ * blocks, and for the same reason: `BasaltShell` needs the number BEFORE the projection runs (it
+ * feeds `extraMoreRows`, which picks `menu` vs `sheet` against `menuMax`) while the renderer is
+ * what decides how many rows a block actually becomes.
+ *
+ * ONE row per block, never one per item: a list block projects to a single `Awaiting action · 3`
+ * row that opens a nested sheet of its items. Counting the items instead would push a 12-item
+ * block's More surface to a sheet on the strength of rows that surface never paints.
+ */
+export function blockRowCount(blocks: readonly SidebarBlock[] | undefined): number {
+  if (blocks === undefined) return 0
+  return blocks.filter((block) => {
+    if (sidebarBlockMobile(block) !== 'more') return false
+    // An empty list block would open a sheet with nothing in it — same failure as the `loading`
+    // account that used to conjure a More slot (`accountRowCount`).
+    return block.kind !== 'list' || block.items.length > 0
+  }).length
+}
+
 const DEV = process.env['NODE_ENV'] !== 'production'
 
 /**
@@ -67,12 +89,38 @@ function isSectionHidden(section: SidebarSection): boolean {
   return section.mobile === false
 }
 
-/** §2.3 rule 12 — a slot is active when ANY of its destinations is, nested children included. */
+/**
+ * §2.3 rule 12 — a slot is active when the active destination is one the slot COVERS.
+ *
+ * "Covers" is the load-bearing word, and it is what makes exclusivity structural: a slot's `covered`
+ * set is exactly the destinations it can navigate to, and activeness now reads that same set. Two
+ * slots therefore cannot both be lit for one location, because no destination is in two `covered`
+ * sets — the overflow is built by removing everything the bar already covers.
+ *
+ * It used to roll up unconditionally over `children`, and `itemCandidate.covered` was
+ * `new Set([item.key])` — the item's own key ONLY. The two disagreed, and the disagreement was the
+ * bug: at `/dashboard/sessions` the `Dashboard` link slot lit through the rollup while `Sessions`
+ * itself, uncovered, sat in the overflow and lit the `More` slot as well. Measured in Chrome: two
+ * `aria-current="page"` tabs in a five-slot bar.
+ *
+ * The rollup itself survives where coverage backs it — a SECTION slot covers its whole pruned tree
+ * (`collectKeys` recurses), so a nested destination inside a section tab still lights that tab, which
+ * is the "you are nowhere" case rule 12 was written for. What changed is an ITEM tab with children:
+ * it covers only itself, its children stay reachable in the overflow, and the slot that can actually
+ * reach the open route is the one that lights. That is strictly better than the alternative — folding
+ * the children into the parent's coverage would light the parent and make the child unreachable from
+ * the bar at all.
+ */
 function hasActiveDestination(item: SidebarItem): boolean {
   if (item.active) return true
   return item.children?.some(hasActiveDestination) ?? false
 }
 
+/** The half of rule 12 an ITEM slot reads: only the destination the tap actually navigates to. */
+function isActiveDestination(item: SidebarItem): boolean {
+  return item.active === true
+}
+
 /** Rows a group tree will render. Nesting costs a row per node — children are indented rows. */
 function countRows(items: readonly SidebarItem[]): number {
   return items.reduce((total, item) => total + 1 + countRows(item.children ?? []), 0)
@@ -139,13 +187,15 @@ function itemCandidate(item: SidebarItem): Candidate {
   return {
     key: item.key,
     covered: new Set([item.key]),
+    // `isActiveDestination`, not the rollup: this slot COVERS one key, so it reads one key
+    // (`hasActiveDestination`'s doc has the whole accounting).
     toSlot: () => ({
       kind: 'link',
       key: item.key,
       label: item.label,
       short: item.short ?? item.label,
       icon: item.icon,
-      active: hasActiveDestination(item),
+      active: isActiveDestination(item),
       item,
     }),
   }

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

@@ -8,7 +8,7 @@ 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,
+ * Sidebar nav count badge (docs/DESIGN-SPEC.md §5): mono micro (11px), 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

package/src/shell/page-bar.module.css

@@ -0,0 +1,178 @@
+/*
+ * `PageBar` layout (docs/CONTROLS-SPEC.md §2.1).
+ *
+ * Law C7 in CSS form: `flex-wrap: nowrap` on every row and NO `overflow-x` anywhere. A home that
+ * scrolls sideways hides its own controls; the fold is computed instead — `More` for actions
+ * (`ActionGroup`), a `Filters (n)` sheet for filters (`FilterSet`'s job, wave 4). The filter
+ * container below only supplies `min-width: 0` so that fold has a box to measure against.
+ */
+
+/* The shell-less bar: both rows, sticky at the top of the document. One layer under the AppShell
+ * header (`--app-shell-header-z-index`, default 100) so it never wins a stacking fight with ordinary
+ * in-flow content — Mantine's Input section, Indicator, sticky table headers, and Slider thumbs all
+ * sit at `z-index: 1` or higher, which used to paint over a bare `z-index: 1` bar while scrolling. */
+.bar {
+  position: sticky;
+  top: 0;
+  z-index: calc(var(--app-shell-header-z-index, 100) - 1);
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-xs);
+  background-color: var(--vx-surface-bg);
+}
+
+/*
+ * Row 2 inside a shell: in the page flow, sticky under the 48px header. `--app-shell-header-height`
+ * is Mantine's own AppShell variable, so the offset tracks the header at any density with no React
+ * state and no measurement. `z-index` sits one layer below the header itself (see `.bar` above) —
+ * high enough to stay above ordinary page content, never above the AppShell header.
+ */
+.row2Sticky {
+  position: sticky;
+  top: var(--app-shell-header-height, 0px);
+  z-index: calc(var(--app-shell-header-z-index, 100) - 1);
+  background-color: var(--vx-surface-bg);
+}
+
+.row1 {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  min-width: 0;
+  min-height: var(--vx-space-page-bar-row-height);
+}
+
+.lead {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  flex-shrink: 0;
+  min-width: 0;
+}
+
+.icon {
+  display: inline-flex;
+  align-items: center;
+  color: var(--vx-muted);
+}
+
+/*
+ * The shell-less page title (law C8: the breadcrumb names the page inside a shell, this does it
+ * outside one). Head-font treatment, same 88%/550 as every `WidgetHeader` title.
+ */
+.title {
+  margin: 0;
+  font-family: var(--basalt-font-head);
+  font-size: var(--vx-text-xl);
+  font-weight: 550;
+  font-stretch: 88%;
+  color: var(--vx-ink);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/*
+ * Icons inside a row-1 button are 16px and sit 6px from their label. Mantine spends
+ * `--mantine-spacing-xs` (11px) on a Button's section gap regardless of the size tier, which is the
+ * BODY tier's number — at 30px it detached the glyph from the word it belongs to. Scoped to the row
+ * rather than themed on `Button` globally: a `size="md"` button in a form still wants Mantine's gap.
+ */
+.row1 :global(.mantine-Button-section[data-position='left']),
+.row2 :global(.mantine-Button-section[data-position='left']) {
+  margin-inline-end: var(--vx-space-control-gap);
+}
+
+.row1 :global(.mantine-Button-section) > svg,
+.row1 :global(.mantine-ActionIcon-root) > svg {
+  width: 1rem;
+  height: 1rem;
+}
+
+/* Actions and sync are right-aligned; the lead (or the breadcrumb, in a shell) holds the left. */
+.row1End {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--vx-space-control-gap);
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+/*
+ * Row 2's rhythm is 8px · pills · 8px, NOT a 40px reserved row.
+ *
+ * `min-height: var(--vx-space-page-bar-row-height)` (40px) left a 30px pill floating inside a 40px
+ * box with the 5px above and below it belonging to nothing — and because the row sat in a `Stack`
+ * that already spaced it, the visible gap between the header and the pills read as ~19px while the
+ * gap from the pills to the first card read as ~19px too. Symmetric padding on the row itself is the
+ * same total height (46px vs 40px) with both halves owned by one declaration, so the sticky bar's
+ * published height covers exactly the band it paints.
+ */
+.row2 {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  min-width: 0;
+  padding-block: var(--vx-space-stack-sm);
+}
+
+.filters {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.filtersEnd {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  margin-inline-start: auto;
+  flex-shrink: 0;
+}
+
+/*
+ * Law C15 — every touch target inside a home is at least `touchControlHeight` (36px at level 0)
+ * below `sm`, while the VISIBLE box stays the 30px `ctl` tier. `::after` and not `::before`:
+ * Mantine's Button owns `::before` for its loading overlay (`@mantine/core/styles/Button.css`),
+ * so a hit area drawn there would fight it. `pointer-events` stays default so the overlay is the
+ * one receiving the tap.
+ *
+ * `overflow: visible` is LOAD-BEARING, not tidying. Mantine's Button and ActionIcon roots both set
+ * `overflow: hidden` (`Button.css`, `ActionIcon.css`), which clips an overlay that by definition
+ * extends past the 30px box — so without this the 36px target simply does not exist and a tap 3px
+ * above the control misses. What `overflow: hidden` buys those roots is clipping the loading
+ * overlay's blur, and that overlay is only painted under `[data-loading]`, which is excluded below.
+ */
+@media (max-width: 47.99375em) {
+  .row1 :is(button, a),
+  .row2 :is(button, a) {
+    position: relative;
+  }
+
+  .row1 :is(button, a):not([data-loading]),
+  .row2 :is(button, a):not([data-loading]) {
+    overflow: visible;
+  }
+
+  .row1 :is(button, a)::after,
+  .row2 :is(button, a)::after {
+    content: '';
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    translate: -50% -50%;
+    width: 100%;
+    height: 100%;
+    min-width: var(--vx-space-touch-control-height);
+    min-height: var(--vx-space-touch-control-height);
+  }
+}

package/src/shell/page-bar.module.css.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly bar: string
+  readonly row2Sticky: string
+  readonly row1: string
+  readonly lead: string
+  readonly icon: string
+  readonly title: string
+  readonly row2: string
+  readonly row1End: string
+  readonly filters: string
+  readonly filtersEnd: string
+}
+export default classes