basalt-ui 1.17.0 → 1.19.0

package/src/charts/primitives/CartesianChart.tsx

@@ -101,6 +101,23 @@ export type CartesianTooltipConfig<T> = {
   prependRows?: (d: T, ctx: CartesianTooltipRowContext<T>) => ReactNode
   /** Rows appended after the derived per-series rows. Same `ctx` as {@link prependRows}. */
   extraRows?: (d: T, ctx: CartesianTooltipRowContext<T>) => ReactNode
+  /**
+   * Render this chart's tooltip when it is a cursor FOLLOWER (the crosshair came from a sibling
+   * chart sharing the cursor), not only when this chart is the SOURCE. Default false — today's
+   * behaviour, nothing moves. A follower has no pointer under it, so its tooltip is always ANCHORED
+   * to the crosshair — the same positioning `follow: false` gives the source — regardless of what
+   * `follow` is set to on this chart: there is no other valid position for a chart nobody is
+   * hovering. `follow` keeps governing the SOURCE's own tooltip exactly as before; the two options
+   * only interact for a follower, where `onFollow` always wins on positioning. Only the SOURCE's
+   * tooltip is `aria-live` — followers announce nothing, so a shared-cursor page doesn't fire N
+   * live-region updates per pointer move.
+   *
+   * Cost, since it scales with the page rather than the chart: anchoring reads one
+   * `getBoundingClientRect` per hovered frame (the same cost `follow: false` documents), so N
+   * opted-in followers pay N of them per frame. That is the reason this is opt-in per chart rather
+   * than a page-level switch — turn it on for the charts a reader actually correlates.
+   */
+  onFollow?: boolean
 }
 
 /** Everything a mark renderer needs. Handed to `CartesianChart`'s child on every render. */
@@ -479,10 +496,17 @@ function CartesianPlot<T>({
   const rows =
     tooltipEnabled && point !== null ? deriveTooltipRows(tooltipSeries, point, leftFormat) : []
 
+  // This chart renders its tooltip either as the cursor SOURCE (always) or, opted in via
+  // `onFollow`, as a FOLLOWER (a sibling owns the cursor). A follower has no pointer under it, so
+  // it is always positioned via the anchored (crosshair) path below, regardless of `follow`.
+  const isFollowerRender = !cursor.isSource && tooltipCfg?.onFollow === true
+  const showTooltip = tooltipEnabled && point !== null && (cursor.isSource || isFollowerRender)
+
   // Anchored mode resolves the crosshair's plot-local x into viewport space; following mode uses
-  // the pointer position `useChartCursor` already recorded.
-  const anchorX =
-    tooltipCfg?.follow === false && point !== null && cursorX !== null ? cursorX : null
+  // the pointer position `useChartCursor` already recorded. A follower render always anchors, since
+  // `follow`'s pointer-tracking path has no pointer to read on this chart.
+  const useAnchoredPosition = tooltipCfg?.follow === false || isFollowerRender
+  const anchorX = useAnchoredPosition && point !== null && cursorX !== null ? cursorX : null
   const svgRect = anchorX === null ? undefined : svgRef.current?.getBoundingClientRect()
   const tooltipAnchor =
     svgRect === undefined || anchorX === null
@@ -595,8 +619,8 @@ function CartesianPlot<T>({
         </Group>
       </svg>
 
-      {tooltipEnabled && cursor.isSource && point !== null && (
-        <ChartTooltipFloat anchor={tooltipAnchor}>
+      {showTooltip && (
+        <ChartTooltipFloat anchor={tooltipAnchor} ariaLive={cursor.isSource}>
           <TooltipHeader
             date={getX(point)}
             {...(formatHeader !== undefined && {

package/src/charts/primitives/ChartTooltip.test.tsx

@@ -3,9 +3,10 @@
  * `fmtTooltipDate` regexes `YYYY-MM-DD` out of the key and builds a LOCAL `Date`, so a UTC ISO
  * domain key names the wrong day next to `formatX`/the tooltip badge, which both resolve locally.
  */
+import { render, screen } from '@testing-library/react'
 import { describe, expect, test } from 'bun:test'
 import { renderToStaticMarkup } from 'react-dom/server'
-import { TooltipHeader } from './ChartTooltip'
+import { ChartTooltipFloat, TooltipHeader } from './ChartTooltip'
 
 describe('TooltipHeader — format prop', () => {
   test('defaults to fmtTooltipDate when omitted', () => {
@@ -21,3 +22,23 @@ describe('TooltipHeader — format prop', () => {
     expect(html).not.toContain('Tue Apr 21 2026')
   })
 })
+
+describe('ChartTooltipFloat — ariaLive', () => {
+  test('defaults to an aria-live="polite" region', () => {
+    render(
+      <ChartTooltipFloat anchor={{ x: 10, y: 10 }}>
+        <span>content</span>
+      </ChartTooltipFloat>,
+    )
+    expect(screen.getByRole('tooltip').getAttribute('aria-live')).toBe('polite')
+  })
+
+  test('ariaLive: false drops the live-region attribute entirely — a follower is visual only', () => {
+    render(
+      <ChartTooltipFloat anchor={{ x: 10, y: 10 }} ariaLive={false}>
+        <span>content</span>
+      </ChartTooltipFloat>,
+    )
+    expect(screen.getByRole('tooltip').hasAttribute('aria-live')).toBe(false)
+  })
+})

package/src/charts/primitives/ChartTooltip.tsx

@@ -155,9 +155,15 @@ const VIEWPORT_MARGIN = 8
  */
 export function ChartTooltipFloat({
   anchor,
+  ariaLive = true,
   children,
 }: {
   anchor: { x: number; y: number } | null
+  /** Whether this tooltip announces itself to screen readers on every position change. Default
+   * true. Pass false for a cursor FOLLOWER's tooltip — N followers on a shared-cursor page all
+   * announcing on every pointer move would make the page unusable with a screen reader; only the
+   * cursor SOURCE should be `aria-live`. */
+  ariaLive?: boolean
   children: ReactNode
 }) {
   const ref = useRef<HTMLDivElement>(null)
@@ -196,7 +202,7 @@ export function ChartTooltipFloat({
     <div
       ref={ref}
       role="tooltip"
-      aria-live="polite"
+      {...(ariaLive && { 'aria-live': 'polite' as const })}
       style={{ ...TOOLTIP_STYLES, left, top, visibility: box === null ? 'hidden' : 'visible' }}
     >
       {children}

package/src/charts/series.ts

@@ -66,6 +66,11 @@ export type SeriesStyle = {
    * that lies is the thing the derived-legend rule exists to prevent). The TOOLTIP ROW swatch and
    * the CROSSHAIR DOT deliberately do NOT honor it: those are 12px value-readout chips where a
    * sub-1 opacity reads as a rendering bug, not as data.
+   *
+   * Applies to STROKES only, so it silently no-ops on a `mark: 'bar'`/`'area'` series — a bar
+   * swatch has no stroke to dim. Dim those with `fillOpacity` instead. This bites the
+   * zone/reference-legend idiom in particular (`mark: 'bar'`, `getValue: () => null`), where
+   * reaching for `strokeOpacity` looks right and does nothing.
    */
   strokeOpacity?: number
   /** Which y-axis this series is measured against. Default 'left'. `'right'` is what makes a

package/src/index.ts

@@ -24,21 +24,31 @@ export {
   type SidebarSearchConfig,
   SidebarAccount,
   MobileNav,
+  type MobileNavProps,
+  projectMobileNav,
+  type ProjectMobileNavOptions,
+  MOBILE_MAX_TABS_DEFAULT,
+  MOBILE_MENU_MAX_DEFAULT,
+  MOBILE_MORE_KEY,
   AppBreadcrumbs,
-  type BreadcrumbLinkRenderer,
   PageHeaderProvider,
   PageActions,
   PageActionsOutlet,
   type SidebarSection,
   type SidebarItem,
+  type NavAnchor,
+  type NavAnchorProps,
+  type NavMobilePlacement,
+  type NavSectionMobile,
+  type MobileNavConfig,
+  type MobileNavGroup,
+  type MobileNavModel,
+  type MobileNavSlot,
+  type MobileNavSurface,
   type BasaltShellProps,
   type BrandConfig,
   type SettingsMenuItem,
   type AppSidebarProps,
-  type MobileNavItem,
-  type MobileNavSection,
-  type NavLinkRenderer,
-  type MobileNavLinkRenderer,
   type AccountBadgeTone,
   type BasaltIdentity,
   type BasaltRole,

package/src/nav/types.ts

@@ -0,0 +1,115 @@
+/**
+ * The shared nav vocabulary. TYPE-ONLY BY CONTRACT — never add a value export here.
+ * `src/shell/**` (Mantine) and `src/router-tanstack/**` (headless) both `import type` from it,
+ * which is erased by tsup, so `dist/router-tanstack/index.js` gains no edge into `shell/` and
+ * `scripts/check-dist-layering.mjs` stays green with no config change.
+ */
+import type { MouseEvent, ReactNode } from 'react'
+
+/** Where a destination appears on the mobile bar. `true` ≡ `'tab'`, `false` ≡ `'hidden'`. */
+export type NavMobilePlacement = 'tab' | 'more' | 'hidden'
+
+/**
+ * Props basalt hands a nav anchor. Deliberately a PLAIN FUNCTION TYPE, not `ComponentType`
+ * or `ElementType`: both are unions, and a union defeats Mantine's polymorphic `component`
+ * inference (`<NavLink component={…}>` then rejects `label`). VERIFIED both ways.
+ */
+export type NavAnchorProps = {
+  className?: string
+  children?: ReactNode
+  onClick?: (e: MouseEvent<HTMLElement>) => void
+  'aria-current'?: 'page' | undefined
+  'aria-label'?: string
+}
+export type NavAnchor = (props: NavAnchorProps) => ReactNode
+
+/** A single nav destination. */
+export type SidebarItem = {
+  key: string
+  label: string
+  /** Bar/menu label. Falls back to `label`. Keep ≤ 10 chars — a 5-slot bar is ~72px wide. */
+  short?: string
+  /** Mobile placement. `true` ≡ `'tab'`, `false` ≡ `'hidden'`. @default 'more' */
+  mobile?: boolean | NavMobilePlacement
+  icon: ReactNode
+  /**
+   * The router seam. basalt renders every pixel of chrome (desktop row, 56px slot, 44px sheet
+   * row) and only hosts this component. When absent the row falls back to `<a href>` + `onClick`.
+   */
+  Anchor?: NavAnchor
+  /** Plain href — the no-router fallback, and the breadcrumb parent target. */
+  href?: string
+  active?: boolean
+  disabled?: boolean
+  onClick?: (e: MouseEvent) => void
+  /** Rich desktop badge (e.g. `NavCountBadge`). Desktop only. */
+  badge?: ReactNode
+  /** Unread count. Renders `NavCountBadge` on desktop when `badge` is absent, and an accent
+   *  dot on the mobile slot icon. `0` renders nothing. */
+  count?: number
+  children?: SidebarItem[]
+}
+
+/** Per-section mobile configuration. `false` hides the whole section from mobile. */
+export type NavSectionMobile = {
+  /** Give this SECTION a bar slot; its destinations open per §2.2 cardinality inference. */
+  tab?: true
+  /** Slot label override; falls back to `SidebarSection.label`. */
+  label?: string
+  /** Slot icon override; falls back to `SidebarSection.icon`. */
+  icon?: ReactNode
+}
+
+export type SidebarSection = {
+  label: string
+  items: SidebarItem[]
+  icon?: ReactNode
+  collapsible?: boolean
+  defaultCollapsed?: boolean
+  /** Mobile behaviour for this section. Omit for the default (items place themselves). */
+  mobile?: false | NavSectionMobile
+}
+
+export type MobileNavSurface = 'link' | 'menu' | 'sheet'
+
+/** One row inside a `menu`/`sheet` slot, grouped under its source section. */
+export type MobileNavGroup = { key: string; label?: string; items: SidebarItem[] }
+
+export type MobileNavSlot =
+  | {
+      kind: 'link'
+      key: string
+      label: string
+      short: string
+      icon: ReactNode
+      active: boolean
+      item: SidebarItem
+    }
+  | {
+      kind: 'menu' | 'sheet'
+      key: string
+      label: string
+      short: string
+      icon: ReactNode
+      active: boolean
+      groups: MobileNavGroup[]
+      isMore: boolean
+    }
+
+/** Pure projection of `sections` onto the bar. Unit-testable with no DOM. */
+export type MobileNavModel = { slots: MobileNavSlot[] }
+
+export type MobileNavConfig = {
+  /** Explicit slot order by item/section key. Overrides every `item.mobile` placement. */
+  tabs?: readonly string[]
+  /** Hard cap on bar slots, INCLUDING More. @default 5 */
+  maxTabs?: number
+  /** Rows a slot may hold before it becomes a sheet instead of a menu. @default 6 */
+  menuMax?: number
+  /** @default 'More' */
+  moreLabel?: string
+  /** Extra content pinned to the bottom of the More surface. */
+  moreExtra?: ReactNode
+  /** Scroll container for active-slot re-tap. @default document.scrollingElement */
+  getScrollElement?: () => HTMLElement | null
+}

package/src/router-tanstack/index.ts

@@ -1,8 +1,10 @@
 /**
  * ./router-tanstack — headless TanStack Router bridge for the app shell.
  * Optional peer: @tanstack/react-router.
- * Augments StaticDataRouteOption with title/icon/navSection for breadcrumb
- * and nav-active wiring — no Mantine, no JSX, no navigate() helper.
+ * Carries the typed navigation definition (`defineNav`/`navGroup`/`navTarget`/`flattenNav`) and
+ * `useNav`, which resolves it into `BasaltShell`'s `sections` + `mobileNav` props; plus the
+ * StaticDataRouteOption augmentation (title/icon/navSection) for router-derived breadcrumbs and
+ * the search-param stores — no Mantine, no JSX.
  */
 
 export {
@@ -15,6 +17,23 @@ export {
   type MultiSearchParamStore,
   type MultiSearchParamStoreOptions,
 } from './multi-search-param-store'
+export { defineNav, navGroup, navTarget, flattenNav } from './nav'
+export type {
+  NavItemMeta,
+  NavGroupMeta,
+  AnyNavItem,
+  AnyNavGroup,
+  AnyNavLink,
+  FlatNavItem,
+  NavConfig,
+  NavItemId,
+  NavGroupId,
+  NavTabId,
+  NavIndex,
+} from './nav'
+export { useNav } from './use-nav'
+export type { UseNavOptions, NavBinding } from './use-nav'
+export type { NavAnchor, NavAnchorProps, NavMobilePlacement } from '../nav/types'
 import type { ReactNode } from 'react'
 import { useLocation, useMatches } from '@tanstack/react-router'
 

package/src/router-tanstack/nav.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from 'bun:test'
+import { defineNav, flattenNav, navGroup, navTarget } from './nav'
+
+/**
+ * The definition below is deliberately built with the real builders (not object literals) so the
+ * runtime-identity assertions below prove the builders are erased at runtime — every bit of value
+ * they add is compile-time. The type-level half of the contract lives in the playground's
+ * `nav.type-guard.ts` fixture, which is where a registered router exists to validate `to` against.
+ */
+const NAV = defineNav({
+  groups: [
+    navGroup({ id: 'main', label: 'Main' }, [
+      { id: 'dash', label: 'Dashboard', short: 'Home', mobile: 'tab', link: { to: '/dashboard' } },
+      {
+        id: 'reports',
+        label: 'Reports',
+        link: { to: '/reports' },
+        children: [
+          { id: 'reports-daily', label: 'Daily', link: { to: '/reports/daily' } },
+          { id: 'reports-weekly', label: 'Weekly', link: { to: '/reports/weekly' } },
+        ],
+      },
+    ]),
+    navGroup({ id: 'system', label: 'System', collapsible: true }, [
+      { id: 'usage', label: 'Usage', disabled: true, link: { to: '/usage', search: { r: '30d' } } },
+    ]),
+  ],
+})
+
+describe('defineNav / navGroup', () => {
+  test('defineNav is runtime identity — it returns the very object it was given', () => {
+    const config = { groups: [] } as const
+    expect(defineNav(config)).toBe(config)
+  })
+
+  test('navGroup merges meta and items into one plain object, preserving item order', () => {
+    const group = navGroup({ id: 'g', label: 'G', collapsible: true }, [
+      { id: 'a', label: 'A', link: { to: '/a' } },
+      { id: 'b', label: 'B', link: { to: '/b' } },
+    ])
+    expect(group).toEqual({
+      id: 'g',
+      label: 'G',
+      collapsible: true,
+      items: [
+        { id: 'a', label: 'A', link: { to: '/a' } },
+        { id: 'b', label: 'B', link: { to: '/b' } },
+      ],
+    })
+  })
+
+  test('navGroup does not mutate the meta object it was handed', () => {
+    const meta = { id: 'g', label: 'G' }
+    navGroup(meta, [{ id: 'a', label: 'A', link: { to: '/a' } }])
+    expect(meta).toEqual({ id: 'g', label: 'G' })
+  })
+})
+
+describe('flattenNav', () => {
+  test('walks depth-first — parent immediately before its own children', () => {
+    expect(flattenNav(NAV).map((d) => d.id)).toEqual([
+      'dash',
+      'reports',
+      'reports-daily',
+      'reports-weekly',
+      'usage',
+    ])
+  })
+
+  test('tags every destination — including nested children — with its declaring group', () => {
+    const byId = new Map(flattenNav(NAV).map((d) => [d.id, d]))
+    expect(byId.get('dash')).toMatchObject({ groupId: 'main', groupLabel: 'Main' })
+    expect(byId.get('reports-weekly')).toMatchObject({ groupId: 'main', groupLabel: 'Main' })
+    expect(byId.get('usage')).toMatchObject({ groupId: 'system', groupLabel: 'System' })
+  })
+
+  test('carries the authored metadata through untouched', () => {
+    const dash = flattenNav(NAV)[0]
+    expect(dash).toMatchObject({
+      label: 'Dashboard',
+      short: 'Home',
+      mobile: 'tab',
+      link: { to: '/dashboard' },
+    })
+  })
+
+  test('an empty definition flattens to an empty list', () => {
+    expect(flattenNav({ groups: [] })).toEqual([])
+  })
+})
+
+describe('navTarget', () => {
+  test('returns the destination link options by id', () => {
+    expect(navTarget(NAV, 'dash')).toEqual({ to: '/dashboard' })
+    expect(navTarget(NAV, 'usage')).toEqual({ to: '/usage', search: { r: '30d' } })
+  })
+
+  test('returns the SAME object the definition holds — spreadable with no copy', () => {
+    expect(navTarget(NAV, 'dash')).toBe(NAV.groups[0].items[0].link)
+  })
+
+  test('resolves ids nested under a parent destination', () => {
+    expect(navTarget(NAV, 'reports-weekly')).toEqual({ to: '/reports/weekly' })
+  })
+
+  test('throws a named error on an unknown id', () => {
+    // The id union makes this a compile error for a consumer; the throw is the runtime backstop
+    // for the untyped edge (a dynamic id, or an unregistered router degrading `NavItemId` away).
+    expect(() => navTarget(NAV, 'zzz' as 'dash')).toThrow('navTarget: no nav item with id "zzz"')
+  })
+})

package/src/router-tanstack/nav.ts

@@ -0,0 +1,205 @@
+/**
+ * Typed navigation definition. Wraps TanStack's own `linkOptions` rather than reimplementing its
+ * validator, so `to` / `search` / `params` get the router's full checking, and nav metadata rides
+ * OUTSIDE the validated object in a sibling `link:` key.
+ *
+ * Why not flat (`{ id, label, to, search }`) via a carrier `TComp` over `ValidateLinkOptions`:
+ * `Constrain<T, C> = (T extends C ? T : never) | C` is an ASSIGNABILITY check, and assignability
+ * does not do excess-property checking — so `{ id, label, to: '/charts', colour: 'red' }` compiles
+ * silently. Compile-verified. A config whose selling point is "typos are compile errors" cannot
+ * have a hole exactly where metadata typos live.
+ *
+ * No JSX and no Mantine in this module — `./router-tanstack` is a headless barrel by contract.
+ */
+import type { ReactNode } from 'react'
+import type { NavMobilePlacement, NavSectionMobile } from '../nav/types'
+
+// ── authoring shapes ─────────────────────────────────────────────────────────────────────────────
+
+export type NavItemMeta = {
+  id: string
+  label: string
+  /** Bar/menu label. Falls back to `label`. */
+  short?: string
+  icon?: ReactNode
+  disabled?: boolean
+  /** Mobile placement. `true` ≡ `'tab'`, `false` ≡ `'hidden'`. @default 'more' */
+  mobile?: boolean | NavMobilePlacement
+  /** Active on an exact path match only. Default: prefix (`fuzzy: true`). `'/'` is always exact. */
+  exact?: boolean
+}
+
+export type NavGroupMeta = {
+  id: string
+  label: string
+  icon?: ReactNode
+  collapsible?: boolean
+  defaultCollapsed?: boolean
+  mobile?: false | NavSectionMobile
+}
+
+/** Widened read shapes. The framework reads through these; a consumer never writes them. */
+export type AnyNavLink = { to: string; search?: unknown; params?: unknown }
+export type AnyNavItem = NavItemMeta & { link: AnyNavLink; children?: ReadonlyArray<AnyNavItem> }
+export type AnyNavGroup = NavGroupMeta & { items: ReadonlyArray<AnyNavItem> }
+
+// ── inference machinery ──────────────────────────────────────────────────────────────────────────
+
+/** Exact-object check: any key outside `Shape` is typed `never`, which surfaces as an error. */
+export type Exact<T, Shape> = T & { readonly [K in Exclude<keyof T, keyof Shape>]: never }
+
+/**
+ * `Exact` for ONE item, recursing into `children`.
+ *
+ * The recursion is the whole point: `AnyNavItem['children']` is a plain
+ * `ReadonlyArray<AnyNavItem>` constraint, and a constraint is an assignability check — so a
+ * top-level-only `Exact` leaves the metadata-typo hole wide open exactly one level down
+ * (`children: [{ id, label, colour: 'red', link }]` compiled silently). Reapplying `Exact` per
+ * child, at every depth, is what makes the nested `link:` design actually deliver "every typo is a
+ * compile error" rather than "every typo in the top row is a compile error".
+ *
+ * The `[K in Extract<keyof T, 'children'>]` form rather than a `children?:` property is what keeps
+ * this inference-safe: it evaluates to `{}` for an item that declares no children (so no phantom
+ * key is added to the checked shape and nothing becomes required), and the intersection with
+ * `Exact<T, AnyNavItem>` keeps `T` in a naked inference position so the caller's literal types
+ * still flow out of `navGroup`'s `const T`.
+ */
+export type ExactNavItem<T> = Exact<T, AnyNavItem> & {
+  readonly [K in Extract<keyof T, 'children'>]: T[K] extends ReadonlyArray<AnyNavItem>
+    ? NavItemsInput<T[K]>
+    : T[K]
+}
+
+/** Per-element `Exact` over a tuple of items, so an unknown key errors at the item that owns it. */
+export type NavItemsInput<T extends ReadonlyArray<AnyNavItem>> = {
+  readonly [K in keyof T]: ExactNavItem<T[K]>
+}
+
+type ItemsOf<G> = G extends ReadonlyArray<{ items: ReadonlyArray<infer I> }> ? I : never
+
+/**
+ * One item plus every descendant, at arbitrary depth. Recursive so the TYPE side matches what
+ * `findById` / `flattenNav` already do at RUNTIME — a one-level walk made `navTarget(nav,
+ * 'grandchild')` a compile error against an id the runtime resolves fine.
+ */
+type WithDescendants<I> =
+  | I
+  | (I extends { children: ReadonlyArray<infer C> } ? WithDescendants<C> : never)
+
+type AllItemsOf<G> = WithDescendants<ItemsOf<G>>
+
+/**
+ * id → link options, as a mapped type with key remapping. Do NOT replace this with
+ * `Extract<AllItemsOf<G>, { id: K }>['link']` — that form was compile-tested and returns the
+ * WHOLE union, silently losing per-id precision.
+ */
+export type NavIndex<G> = {
+  [I in AllItemsOf<G> as I extends { id: infer K extends string } ? K : never]: I extends {
+    link: infer L
+  }
+    ? L
+    : never
+}
+
+/**
+ * The literal union of every addressable destination id in a definition — parents, children and
+ * grandchildren alike, at ARBITRARY depth, matching what `findById` / `flattenNav` resolve at
+ * runtime. Verified to seven levels of `children` with no instantiation-depth complaint.
+ *
+ * If this ever resolves to plain `string`, the entire nav API validates nothing while reporting
+ * zero errors — so any change to the generics above must be re-checked against
+ * `apps/playground/src/nav.type-guard.tsx`, whose `@ts-expect-error` rows go UNUSED (TS2578) the
+ * moment the union widens.
+ */
+export type NavItemId<G> = Extract<keyof NavIndex<G>, string>
+export type NavGroupId<G> = G extends ReadonlyArray<{ id: infer I }> ? I : never
+export type NavTabId<G> = NavItemId<G> | NavGroupId<G>
+
+export type NavConfig<
+  G extends ReadonlyArray<AnyNavGroup>,
+  T extends ReadonlyArray<NavTabId<G>>,
+> = {
+  groups: G
+  mobile?: {
+    /** Explicit bar order by item/group id. Omit to let each item's `mobile` field decide. */
+    tabs?: T
+    /** @default 5 */ maxTabs?: number
+    /** @default 6 */ menuMax?: number
+    /** @default 'More' */ moreLabel?: string
+  }
+}
+
+// ── builders (identity at runtime) ───────────────────────────────────────────────────────────────
+
+/**
+ * One nav group. `const M` on the meta is load-bearing: without it the group `id` widens to
+ * `string` from `NavGroupMeta` and `mobile.tabs` silently stops validating group ids.
+ */
+export function navGroup<const M extends NavGroupMeta, const T extends ReadonlyArray<AnyNavItem>>(
+  meta: Exact<M, NavGroupMeta>,
+  items: NavItemsInput<T>,
+): M & { items: T } {
+  return { ...(meta as M), items: items as unknown as T }
+}
+
+/**
+ * The whole navigation — desktop and mobile — in one inferred definition.
+ *
+ * There is deliberately NO compile-time cap on `mobile.tabs.length`. Both a
+ * `T extends … & { length: 0|1|2|3|4|5 }` constraint and a `tabs: T & MaxFive` property form were
+ * compile-tested: each makes the length check work but silently degrades `NavTabId<G>` to `string`,
+ * killing the far more valuable id-union validation. The cap is a runtime concern — the shell's
+ * `projectMobileNav` slices to `maxTabs` and DEV-warns about what it dropped.
+ */
+export function defineNav<
+  const G extends ReadonlyArray<AnyNavGroup>,
+  const T extends ReadonlyArray<NavTabId<G>>,
+>(config: NavConfig<G, T>): NavConfig<G, T> {
+  return config
+}
+
+// ── readers ──────────────────────────────────────────────────────────────────────────────────────
+
+function findById(items: ReadonlyArray<AnyNavItem>, id: string): AnyNavItem | undefined {
+  for (const item of items) {
+    if (item.id === id) return item
+    const hit = item.children ? findById(item.children, id) : undefined
+    if (hit) return hit
+  }
+  return undefined
+}
+
+/**
+ * The link options for one destination, by id. Spreadable into `<Link>`, `router.navigate()`
+ * and `redirect()`. This is what collapses a consumer's Spotlight commands and index redirect.
+ *
+ * `id` is the definition's literal id union (`NavItemId`) at any nesting depth, so a nested child
+ * or grandchild is addressable exactly like a top-level item — the type side and `findById`'s
+ * runtime walk agree.
+ */
+export function navTarget<
+  const C extends { groups: ReadonlyArray<AnyNavGroup> },
+  K extends NavItemId<C['groups']>,
+>(config: C, id: K): NavIndex<C['groups']>[K] {
+  for (const g of config.groups) {
+    const hit = findById(g.items, id)
+    if (hit) return hit.link as NavIndex<C['groups']>[K]
+  }
+  throw new Error(`navTarget: no nav item with id "${id}"`)
+}
+
+/** A flattened destination, tagged with the group it was declared in. */
+export type FlatNavItem = AnyNavItem & { groupId: string; groupLabel: string }
+
+/** Depth-first flatten, parent then children — the leaf every other surface reads. */
+export function flattenNav(config: { groups: ReadonlyArray<AnyNavGroup> }): FlatNavItem[] {
+  const out: FlatNavItem[] = []
+  const walk = (items: ReadonlyArray<AnyNavItem>, groupId: string, groupLabel: string): void => {
+    for (const item of items) {
+      out.push({ ...item, groupId, groupLabel })
+      if (item.children) walk(item.children, groupId, groupLabel)
+    }
+  }
+  for (const g of config.groups) walk(g.items, g.id, g.label)
+  return out
+}