basalt-ui 1.17.0 → 1.19.0

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

@@ -0,0 +1,296 @@
+/**
+ * `projectMobileNav` — the slot-selection law, one test per numbered rule.
+ *
+ * This is the highest-value suite in the mobile-nav rewrite: every decision the bottom bar makes
+ * (which destinations get a slot, which slot navigates and which raises a surface, whether that
+ * surface is a menu or a sheet, what falls into More) is decided here and painted by
+ * `app-mobile-nav.tsx` without a single further choice. Pinning the projection therefore pins the
+ * interaction model itself, with no renderer, no DOM and no timing — a rule that regresses fails
+ * as a value comparison rather than as a flaky query against a portalled dropdown.
+ *
+ * Two regressions in particular are what this file exists to keep dead:
+ *  - a slot that raises a full surface to show ONE row (§2.2 cardinality inference), and
+ *  - 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 type { ProjectMobileNavOptions } from './mobile-nav-model'
+import type { MobileNavGroup, MobileNavModel, MobileNavSlot, SidebarItem } from '../nav/types'
+
+// ── fixtures ─────────────────────────────────────────────────────────────────────────────────────
+
+/** A destination. `icon: null` keeps the whole suite JSX-free — the model never reads the icon. */
+function item(key: string, extra: Partial<SidebarItem> = {}): SidebarItem {
+  return { key, label: key.toUpperCase(), icon: null, ...extra }
+}
+
+/** `n` plain destinations named `d1…dn`, the shape every cardinality case counts rows against. */
+function items(n: number, extra: Partial<SidebarItem> = {}): SidebarItem[] {
+  return Array.from({ length: n }, (_, i) => item(`d${i + 1}`, extra))
+}
+
+const keys = (model: MobileNavModel): string[] => model.slots.map((slot) => slot.key)
+const kinds = (model: MobileNavModel): string[] => model.slots.map((slot) => slot.kind)
+
+function slotAt(model: MobileNavModel, index: number): MobileNavSlot {
+  const slot = model.slots[index]
+  if (!slot) throw new Error(`expected a slot at index ${index}, got ${model.slots.length} slots`)
+  return slot
+}
+
+/** The trailing More slot, asserted to exist and to be a surface (a `link` More is rule 10's
+ *  collapse case and is asserted by key/kind directly where it is the point). */
+function moreSlot(model: MobileNavModel): Extract<MobileNavSlot, { groups: MobileNavGroup[] }> {
+  const slot = model.slots.at(-1)
+  if (!slot || slot.kind === 'link') throw new Error('expected a menu/sheet More slot last')
+  expect(slot.key).toBe(MOBILE_MORE_KEY)
+  expect(slot.isMore).toBe(true)
+  return slot
+}
+
+/** Every destination key a surface slot renders, depth-first — the reachability assertion. */
+function rowKeys(groups: readonly MobileNavGroup[]): string[] {
+  const out: string[] = []
+  const walk = (list: readonly SidebarItem[]): void => {
+    for (const row of list) {
+      out.push(row.key)
+      walk(row.children ?? [])
+    }
+  }
+  for (const group of groups) walk(group.items)
+  return out
+}
+
+/**
+ * Runs the projection with `console.warn` captured. The DEV warnings are part of the contract
+ * (rules 11 and 13 are "warn, then do the safe thing"), and swallowing them here also keeps the
+ * suite's output clean — the cases below deliberately trigger them.
+ */
+function projectQuietly(
+  sections: Parameters<typeof projectMobileNav>[0],
+  opts?: ProjectMobileNavOptions,
+): { model: MobileNavModel; warnings: string[] } {
+  const warnings: string[] = []
+  const original = console.warn
+  console.warn = (...args: unknown[]) => {
+    warnings.push(args.map(String).join(' '))
+  }
+  try {
+    return { model: projectMobileNav(sections, opts), warnings }
+  } finally {
+    console.warn = original
+  }
+}
+
+// ── the law ──────────────────────────────────────────────────────────────────────────────────────
+
+describe('projectMobileNav', () => {
+  /** Rule 6 — the bar must be usable with the consumer having configured nothing at all. */
+  test('1. zero-config fallback takes the first maxTabs-1 non-disabled top-level destinations', () => {
+    const model = projectMobileNav([
+      {
+        label: 'Main',
+        items: [
+          item('a'),
+          item('b', { disabled: true }),
+          item('c'),
+          item('d'),
+          item('e'),
+          item('f'),
+        ],
+      },
+    ])
+
+    // Four link slots (maxTabs 5 minus the More the leftovers force), the disabled one skipped.
+    expect(keys(model)).toEqual(['a', 'c', 'd', 'e', MOBILE_MORE_KEY])
+    expect(kinds(model)).toEqual(['link', 'link', 'link', 'link', 'menu'])
+    expect(rowKeys(moreSlot(model).groups)).toEqual(['b', 'f'])
+  })
+
+  /** Rules 8-9 — nothing left over, no account, no settings: the bar fills all five slots. */
+  test('2. no overflow and no extra rows yields maxTabs slots and NO More', () => {
+    const model = projectMobileNav([{ label: 'Main', items: items(5, { mobile: 'tab' }) }])
+
+    expect(model.slots).toHaveLength(5)
+    expect(kinds(model)).toEqual(['link', 'link', 'link', 'link', 'link'])
+    expect(keys(model)).not.toContain(MOBILE_MORE_KEY)
+  })
+
+  /** Rules 9 + 13 — the slice is what creates the overflow, and it says so in DEV. */
+  test('3. six tab requests become four slots plus More, with the last two in overflow', () => {
+    const { model, warnings } = projectQuietly([
+      { label: 'Main', items: items(6, { mobile: 'tab' }) },
+    ])
+
+    expect(keys(model)).toEqual(['d1', 'd2', 'd3', 'd4', MOBILE_MORE_KEY])
+    expect(rowKeys(moreSlot(model).groups)).toEqual(['d5', 'd6'])
+    expect(warnings.some((line) => line.includes('6 slot candidates for 4'))).toBe(true)
+  })
+
+  /** Rule 5 — the one named escape hatch, and it REPLACES the declarative pass rather than
+   *  reordering its result: `a` asks for a tab and still does not get one. */
+  test('4. config.tabs replaces every item placement and preserves the given order', () => {
+    const model = projectMobileNav(
+      [
+        {
+          label: 'Main',
+          items: [item('a', { mobile: 'tab' }), item('b', { mobile: 'tab' }), item('c'), item('d')],
+        },
+      ],
+      { config: { tabs: ['d', 'b'] } },
+    )
+
+    expect(keys(model)).toEqual(['d', 'b', MOBILE_MORE_KEY])
+    expect(rowKeys(moreSlot(model).groups)).toEqual(['a', 'c'])
+  })
+
+  /** §2.2 — a group of one IS a destination. This is the case that raises a full-viewport drawer
+   *  for a single row today, and the reason surface inference is cardinality, not configuration. */
+  test('5. a mobile:{tab:true} section holding one destination collapses to a link slot', () => {
+    const model = projectMobileNav([
+      { label: 'Main', items: [item('a')] },
+      { label: 'Admin', mobile: { tab: true }, items: [item('settings')] },
+    ])
+
+    const slot = slotAt(model, 0)
+    expect(slot.kind).toBe('link')
+    expect(slot.key).toBe('settings')
+    // The SLOT is what the consumer configured, so the section's label names it.
+    expect(slot.label).toBe('Admin')
+    if (slot.kind !== 'link') throw new Error('unreachable')
+    expect(slot.item.key).toBe('settings')
+  })
+
+  /** §2.2 — the same section, twice, differing only in how many rows it holds. */
+  test('6. a group slot of 4 destinations is a menu; of 9 it is a sheet', () => {
+    const small = projectMobileNav([{ label: 'Reports', mobile: { tab: true }, items: items(4) }])
+    const large = projectMobileNav([{ label: 'Reports', mobile: { tab: true }, items: items(9) }])
+
+    expect(slotAt(small, 0).kind).toBe('menu')
+    expect(slotAt(large, 0).kind).toBe('sheet')
+  })
+
+  /** The threshold is arithmetic (6 rows x 44px + 8px fits above a 56px bar on a 568px viewport),
+   *  so the boundary itself is worth pinning — off-by-one here renders a menu below the fold. */
+  test('7. menuMax is inclusive: exactly menuMax rows is a menu, one more is a sheet', () => {
+    const atLimit = projectMobileNav([{ label: 'Reports', mobile: { tab: true }, items: items(6) }])
+    const overLimit = projectMobileNav([
+      { label: 'Reports', mobile: { tab: true }, items: items(7) },
+    ])
+
+    expect(slotAt(atLimit, 0).kind).toBe('menu')
+    expect(slotAt(overLimit, 0).kind).toBe('sheet')
+
+    // And the threshold is a knob, not a constant: lowering it moves the same six rows to a sheet.
+    const tightened = projectMobileNav(
+      [{ label: 'Reports', mobile: { tab: true }, items: items(6) }],
+      { config: { menuMax: 5 } },
+    )
+    expect(slotAt(tightened, 0).kind).toBe('sheet')
+  })
+
+  /**
+   * Rule 8 + §11 risk 6 — account and settings rows are only reachable from More now that the
+   * full-height sidebar drawer is gone, so they must count toward the menu-vs-sheet threshold.
+   * The model cannot see them (they are Mantine chrome, not `SidebarItem`s); the shell counts.
+   */
+  test('8. extraMoreRows 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: 1 }), 1).kind).toBe('sheet')
+  })
+
+  /** Rule 1 — a section's `mobile: false` wins over every item inside it, everywhere. */
+  test('9. mobile:false on a section hides all its destinations from slots AND from overflow', () => {
+    const model = projectMobileNav([
+      { label: 'Main', items: [item('a')] },
+      {
+        label: 'Internal',
+        mobile: false,
+        items: [item('secret'), item('debug', { mobile: 'tab' })],
+      },
+    ])
+
+    expect(keys(model)).toEqual(['a'])
+    expect(JSON.stringify(model)).not.toContain('secret')
+    expect(JSON.stringify(model)).not.toContain('debug')
+  })
+
+  /**
+   * Rule 11 — THE REGRESSION THIS DESIGN FIXES. Today's projection drops `disabled` outright and
+   * ships a live row; the law is the opposite: never a tab (a tab that cannot be tapped is a dead
+   * 72px of bar), always a row, always rendered disabled.
+   */
+  test('10. a disabled destination is never a link slot but survives into the More rows', () => {
+    const { model, warnings } = projectQuietly([
+      {
+        label: 'Main',
+        items: [item('a', { mobile: 'tab' }), item('x', { mobile: 'tab', disabled: true })],
+      },
+    ])
+
+    expect(keys(model)).toEqual(['a', MOBILE_MORE_KEY])
+    const more = moreSlot(model)
+    expect(rowKeys(more.groups)).toEqual(['x'])
+    expect(more.groups[0]?.items[0]?.disabled).toBe(true)
+    expect(warnings.some((line) => line.includes('"x"') && line.includes('disabled'))).toBe(true)
+  })
+
+  /** Rule 2 — nesting is a lookup-order concern, not a rendering one: the tree reaches the rows
+   *  intact, so a child no longer reads as a sibling of its own parent on mobile. */
+  test('11. nested children are preserved as a tree in the overflow rows, not flattened away', () => {
+    const model = projectMobileNav([
+      {
+        label: 'Main',
+        items: [
+          item('a', { mobile: 'tab' }),
+          item('reports', { children: [item('daily'), item('weekly')] }),
+        ],
+      },
+    ])
+
+    const more = moreSlot(model)
+    const reports = more.groups[0]?.items[0]
+    expect(reports?.key).toBe('reports')
+    expect(reports?.children?.map((child) => child.key)).toEqual(['daily', 'weekly'])
+    // Depth-first, parent before children — the order the renderer indents against.
+    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', () => {
+    const model = projectMobileNav([
+      {
+        label: 'Main',
+        items: [
+          item('reports', { mobile: 'tab', children: [item('daily', { active: true })] }),
+          item('other', { mobile: 'tab' }),
+        ],
+      },
+    ])
+
+    expect(slotAt(model, 0).active).toBe(true)
+    expect(slotAt(model, 1).active).toBe(false)
+  })
+
+  /** §2.4 — a five-slot bar is ~72px wide, so the bar label is `short` when the consumer supplied
+   *  one and the full label otherwise. Both paths, one test. */
+  test('13. the slot label is `short`, falling back to `label`', () => {
+    const model = projectMobileNav([
+      {
+        label: 'Main',
+        items: [
+          item('dashboard', { mobile: 'tab', label: 'Dashboard', short: 'Dash' }),
+          item('activity', { mobile: 'tab', label: 'Activity' }),
+        ],
+      },
+    ])
+
+    expect(slotAt(model, 0).short).toBe('Dash')
+    // `label` stays the FULL text — it is the accessible name, which is never abbreviated.
+    expect(slotAt(model, 0).label).toBe('Dashboard')
+    expect(slotAt(model, 1).short).toBe('Activity')
+  })
+})

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

@@ -0,0 +1,389 @@
+/**
+ * The mobile-bar projection — `SidebarSection[]` + `MobileNavConfig` → `MobileNavModel`.
+ *
+ * PURE BY CONTRACT: no React, no Mantine, no DOM, no JSX. Everything the bottom bar decides —
+ * which destinations get a slot, which slot is a plain navigation link and which raises a surface,
+ * whether that surface is a menu or a sheet, what falls into the overflow "More" slot — is decided
+ * here and unit-testable with no renderer. `app-mobile-nav.tsx` only paints the result.
+ *
+ * The law it implements is the interaction model, not a heuristic: a slot is a DESTINATION, so a
+ * tap navigates with no overlay to dismiss. An overlay exists only where a slot genuinely holds
+ * more than one destination, and its surface is INFERRED from how many rows it holds rather than
+ * configured — six rows is the arithmetic ceiling for a menu that pops out of a 56px bar without
+ * ever rendering below the fold (6 x 44px + 8px padding = 272px against 415px of headroom on the
+ * smallest supported viewport), so past that the surface becomes a bottom sheet.
+ */
+import type {
+  MobileNavConfig,
+  MobileNavGroup,
+  MobileNavModel,
+  MobileNavSlot,
+  NavMobilePlacement,
+  SidebarItem,
+  SidebarSection,
+} from '../nav/types'
+
+/** Hard cap on bar slots, INCLUDING More. Five 72px slots is the widest a 360px viewport holds. */
+export const MOBILE_MAX_TABS_DEFAULT = 5
+
+/**
+ * Rows a slot may hold before it becomes a sheet instead of a menu. Arithmetic, not taste — see
+ * the module doc: six rows is the last count a bottom-anchored, non-flipping menu fits above the
+ * bar on the smallest supported viewport.
+ */
+export const MOBILE_MENU_MAX_DEFAULT = 6
+
+/** The overflow slot's reserved key. A slot like any other — it just exists only when needed. */
+export const MOBILE_MORE_KEY = '__more'
+
+export type ProjectMobileNavOptions = {
+  config?: MobileNavConfig | undefined
+  /**
+   * Extra rows the More surface will hold — account + settings + `moreExtra`. 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
+}
+
+const DEV = process.env['NODE_ENV'] !== 'production'
+
+/**
+ * §2.3 rule 1. A section's `mobile: false` wins over every item inside it; otherwise the item's own
+ * field decides, with the shorthand booleans normalized and `undefined` meaning "reachable, but not
+ * from the bar" — the default that makes a nav work with nothing configured.
+ */
+function placementOf(item: SidebarItem, sectionHidden: boolean): NavMobilePlacement {
+  if (sectionHidden) return 'hidden'
+  const mobile = item.mobile
+  if (mobile === undefined) return 'more'
+  if (mobile === true) return 'tab'
+  if (mobile === false) return 'hidden'
+  return mobile
+}
+
+/** A section opts its whole subtree out of mobile with `mobile: false`. */
+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. */
+function hasActiveDestination(item: SidebarItem): boolean {
+  if (item.active) return true
+  return item.children?.some(hasActiveDestination) ?? false
+}
+
+/** 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)
+}
+
+/** Every destination key in a tree — the reachability set a slot contributes. */
+function collectKeys(items: readonly SidebarItem[], out: Set<string>): void {
+  for (const item of items) {
+    out.add(item.key)
+    collectKeys(item.children ?? [], out)
+  }
+}
+
+/**
+ * Depth-first flatten, parent before children — the order every candidate list and the zero-config
+ * fallback read. Nesting is NOT lost: this is the lookup/selection view, while the overflow and
+ * group rendering below keep the tree (today's projection flattens it away, which is why a nested
+ * destination reads as a sibling of its own parent on mobile).
+ */
+function flattenItems(items: readonly SidebarItem[], out: SidebarItem[]): void {
+  for (const item of items) {
+    out.push(item)
+    flattenItems(item.children ?? [], out)
+  }
+}
+
+/**
+ * Drops every destination `keep` rejects, HOISTING a rejected parent's surviving children into its
+ * place rather than discarding the subtree — placement is normalized per destination (rule 1), so a
+ * visible child of a hidden parent is still a visible destination and must stay reachable.
+ */
+function pruneTree(
+  items: readonly SidebarItem[],
+  keep: (item: SidebarItem) => boolean,
+): SidebarItem[] {
+  const out: SidebarItem[] = []
+  for (const item of items) {
+    const children = pruneTree(item.children ?? [], keep)
+    if (!keep(item)) {
+      out.push(...children)
+      continue
+    }
+    const next: SidebarItem = { ...item }
+    if (children.length > 0) next.children = children
+    else delete next.children
+    out.push(next)
+  }
+  return out
+}
+
+/** A slot candidate before the `maxTabs` slice decides which ones survive. */
+type Candidate = {
+  /** What the candidate is CALLED — a destination key, or a section's label. Only rule 13's warn
+   *  reads it, and that warn exists to name the slots that lost the slice. */
+  key: string
+  /** Destination keys this slot makes reachable — everything else falls to overflow (rule 7). */
+  covered: Set<string>
+  /** Built after the slice, since a dropped candidate never becomes a slot. */
+  toSlot: () => MobileNavSlot | undefined
+}
+
+/** A destination becomes a `link` slot: one tap, one navigation, nothing to dismiss. */
+function itemCandidate(item: SidebarItem): Candidate {
+  return {
+    key: item.key,
+    covered: new Set([item.key]),
+    toSlot: () => ({
+      kind: 'link',
+      key: item.key,
+      label: item.label,
+      short: item.short ?? item.label,
+      icon: item.icon,
+      active: hasActiveDestination(item),
+      item,
+    }),
+  }
+}
+
+/**
+ * A SECTION becomes one slot (`mobile: { tab: true }`), holding its destinations. Cardinality picks
+ * the surface (§2.2): an empty section is not a slot at all, and a section of ONE destination IS
+ * that destination — collapsing to a `link` rather than raising a full surface for a single row,
+ * which is exactly what today's projection gets wrong.
+ */
+function sectionCandidate(section: SidebarSection, menuMax: number): Candidate {
+  const mobile =
+    section.mobile === false || section.mobile === undefined ? undefined : section.mobile
+  const items = pruneTree(section.items, (item) => placementOf(item, false) !== 'hidden')
+  const covered = new Set<string>()
+  collectKeys(items, covered)
+  const label = mobile?.label ?? section.label
+  const rows = countRows(items)
+  const only = items[0]
+
+  return {
+    key: section.label,
+    covered,
+    toSlot: () => {
+      if (rows === 0) return undefined
+      if (rows === 1 && only !== undefined && !only.disabled) {
+        return {
+          kind: 'link',
+          key: only.key,
+          label,
+          short: label,
+          // The section's own identity wins when it declares one — the consumer configured the
+          // SLOT — and falls back to the single destination's icon when it does not.
+          icon: mobile?.icon ?? section.icon ?? only.icon,
+          active: hasActiveDestination(only),
+          item: only,
+        }
+      }
+      return {
+        kind: rows <= menuMax ? 'menu' : 'sheet',
+        key: section.label,
+        label,
+        short: label,
+        icon: mobile?.icon ?? section.icon,
+        active: items.some(hasActiveDestination),
+        // One section, so the rows need no group heading — the tab itself names them.
+        groups: [{ key: section.label, items }],
+        isMore: false,
+      }
+    },
+  }
+}
+
+/**
+ * §2.3 rules 3-6 — the candidate list, in bar order.
+ *
+ * `config.tabs` REPLACES the declarative pass entirely (rule 5): it is the one named escape hatch
+ * for "bar order != sidebar order", so it wins over every `item.mobile`. Otherwise sections are
+ * walked in declaration order, which is what interleaves section slots with item slots correctly.
+ */
+function buildCandidates(
+  sections: readonly SidebarSection[],
+  config: MobileNavConfig | undefined,
+  maxTabs: number,
+  menuMax: number,
+): Candidate[] {
+  const flat: SidebarItem[] = []
+  for (const section of sections) {
+    if (isSectionHidden(section)) continue
+    flattenItems(section.items, flat)
+  }
+
+  /** Rule 11 — `mobile: 'tab'` on a disabled destination is a configuration mistake, not a slot. */
+  const tabbable = (item: SidebarItem): boolean => {
+    if (!item.disabled) return true
+    if (DEV) {
+      console.warn(
+        `[basalt] MobileNav: "${item.key}" asks for a bar slot but is disabled — a disabled destination never becomes a tab. It still renders, disabled, in the More surface.`,
+      )
+    }
+    return false
+  }
+
+  if (config?.tabs !== undefined) {
+    const candidates: Candidate[] = []
+    for (const id of config.tabs) {
+      const item = flat.find((candidate) => candidate.key === id)
+      if (item !== undefined) {
+        if (tabbable(item)) candidates.push(itemCandidate(item))
+        continue
+      }
+      // A section is named by its `label` — `SidebarSection` carries no key of its own.
+      const section = sections.find((s) => s.label === id && !isSectionHidden(s))
+      if (section !== undefined) {
+        candidates.push(sectionCandidate(section, menuMax))
+        continue
+      }
+      if (DEV) {
+        console.warn(
+          `[basalt] MobileNav: mobileNav.tabs names "${id}", which is neither a destination key nor a visible section label — ignoring it.`,
+        )
+      }
+    }
+    return candidates
+  }
+
+  const candidates: Candidate[] = []
+  for (const section of sections) {
+    if (isSectionHidden(section)) continue
+    // Rule 3: a section slot consumes its destinations, so they never also compete as item slots.
+    if (section.mobile !== undefined && section.mobile !== false && section.mobile.tab === true) {
+      candidates.push(sectionCandidate(section, menuMax))
+      continue
+    }
+    const items: SidebarItem[] = []
+    flattenItems(section.items, items)
+    for (const item of items) {
+      if (placementOf(item, false) !== 'tab') continue
+      if (tabbable(item)) candidates.push(itemCandidate(item))
+    }
+  }
+  if (candidates.length > 0) return candidates
+
+  // Rule 6 — nobody configured anything. The bar still works: the first few top-level destinations
+  // become slots, so a consumer gets a usable nav for free and tunes it only if it is wrong.
+  const fallback: Candidate[] = []
+  for (const section of sections) {
+    if (isSectionHidden(section)) continue
+    for (const item of section.items) {
+      if (fallback.length >= maxTabs - 1) return fallback
+      if (item.disabled) continue
+      if (placementOf(item, false) === 'hidden') continue
+      fallback.push(itemCandidate(item))
+    }
+  }
+  return fallback
+}
+
+/** Rule 7 — the leftovers, grouped by source section, tree intact. */
+function buildOverflow(
+  sections: readonly SidebarSection[],
+  covered: Set<string>,
+): MobileNavGroup[] {
+  const groups: MobileNavGroup[] = []
+  for (const section of sections) {
+    const hidden = isSectionHidden(section)
+    if (hidden) continue
+    const items = pruneTree(
+      section.items,
+      (item) => placementOf(item, hidden) !== 'hidden' && !covered.has(item.key),
+    )
+    if (items.length === 0) continue
+    groups.push({ key: section.label, label: section.label, items })
+  }
+  return groups
+}
+
+/**
+ * Projects `sections` onto the bar. Implements §2.3's thirteen rules in order, and is the ONLY
+ * place slot selection happens — `MobileNav` receives a finished model and paints it.
+ */
+export function projectMobileNav(
+  sections: SidebarSection[],
+  opts?: ProjectMobileNavOptions,
+): MobileNavModel {
+  const config = opts?.config
+  const maxTabs = Math.max(1, config?.maxTabs ?? MOBILE_MAX_TABS_DEFAULT)
+  const menuMax = Math.max(1, config?.menuMax ?? MOBILE_MENU_MAX_DEFAULT)
+  const extraMoreRows = opts?.extraMoreRows ?? 0
+
+  const candidates = buildCandidates(sections, config, maxTabs, menuMax)
+
+  // Rules 8-9 are mutually recursive on paper — `needsMore` reads the overflow, the slice writes
+  // it. The fixpoint is one line: a candidate list longer than the bar ALWAYS needs More, because
+  // the slice is what pushes the remainder into overflow.
+  const coveredByAll = new Set<string>()
+  for (const candidate of candidates) for (const key of candidate.covered) coveredByAll.add(key)
+  const overflowIfNoneDropped = buildOverflow(sections, coveredByAll)
+  const needsMore =
+    countRows(overflowIfNoneDropped.flatMap((group) => group.items)) > 0 ||
+    extraMoreRows > 0 ||
+    candidates.length > maxTabs
+
+  const limit = needsMore ? maxTabs - 1 : maxTabs
+  const kept = candidates.slice(0, limit)
+  const dropped = candidates.slice(limit)
+  if (DEV && dropped.length > 0) {
+    // Rule 13 wants the NAMES, not a tally: "2 candidates dropped" tells a consumer their bar is
+    // wrong, while the keys tell them which `mobile: 'tab'` to move or which section to reorder.
+    console.warn(
+      `[basalt] MobileNav: ${candidates.length} slot candidates for ${limit} available slot(s) — the last ${dropped.length} moved into the More surface: ${dropped.map((candidate) => `"${candidate.key}"`).join(', ')}. Raise mobileNav.maxTabs or drop a mobile: 'tab'.`,
+    )
+  }
+
+  const covered = new Set<string>()
+  for (const candidate of kept) for (const key of candidate.covered) covered.add(key)
+
+  const slots: MobileNavSlot[] = []
+  for (const candidate of kept) {
+    const slot = candidate.toSlot()
+    if (slot !== undefined) slots.push(slot)
+  }
+
+  if (!needsMore) return { slots }
+
+  // Rule 10 — the More slot, inferred over everything the bar could not reach.
+  const groups = buildOverflow(sections, covered)
+  const overflowItems = groups.flatMap((group) => group.items)
+  const rows = countRows(overflowItems) + extraMoreRows
+  if (rows === 0) return { slots }
+
+  const label = config?.moreLabel ?? 'More'
+  const only = overflowItems[0]
+  if (rows === 1 && extraMoreRows === 0 && only !== undefined && !only.disabled) {
+    // §2.2 again: a More surface holding one destination IS that destination.
+    slots.push({
+      kind: 'link',
+      key: only.key,
+      label: only.label,
+      short: only.short ?? only.label,
+      icon: only.icon,
+      active: hasActiveDestination(only),
+      item: only,
+    })
+    return { slots }
+  }
+
+  slots.push({
+    kind: rows <= menuMax ? 'menu' : 'sheet',
+    key: MOBILE_MORE_KEY,
+    label,
+    short: label,
+    // No icon: the More glyph is chrome the renderer owns, and this module holds no JSX.
+    icon: undefined,
+    active: overflowItems.some(hasActiveDestination),
+    groups,
+    isMore: true,
+  })
+  return { slots }
+}