basalt-ui 1.25.0 → 1.27.0

package/src/router-tanstack/use-nav.test.tsx

@@ -0,0 +1,187 @@
+/**
+ * `useNav`'s active-resolution pass, under a REAL TanStack memory router — the half that cannot be
+ * tested headlessly (`matchRoute`/`useRouterState` both need a live router). The fixture below
+ * mirrors every collision shape the playground's own `demo/nav-model.tsx` actually has: a root `/`
+ * item, a `/dashboard` parent with three children, flat siblings, a same-path duplicate
+ * (`reports`/`components`, mirroring the playground's disabled-placeholder shape), and a
+ * search-bearing link (mirroring `dashboardFilters.linkSearch`-style destinations).
+ *
+ * The harness is modeled on `controls/controls.router.test.tsx`'s `mountPage`, narrowed to a
+ * headless probe: `useNav` renders no JSX itself (`./router-tanstack` is a no-JSX barrel), so the
+ * probe component only reads its return value into a sink — no `MantineProvider` needed.
+ */
+import { cleanup, render, waitFor } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import type { ReactNode } from 'react'
+import {
+  Outlet,
+  RouterProvider,
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+} from '@tanstack/react-router'
+import type { SidebarItem, SidebarSection } from '../nav/types'
+import type { AnyNavItem } from './nav'
+import { defineNav, navGroup } from './nav'
+import { useNav } from './use-nav'
+
+const NAV = defineNav({
+  groups: [
+    navGroup({ id: 'main', label: 'Main' }, [
+      { id: 'home', label: 'Home', link: { to: '/' } },
+      {
+        id: 'dashboard',
+        label: 'Dashboard',
+        // A store-backed destination (law C10's shape) — `search` rides the link like every
+        // other field; `matchOf` below never reads it, so it must not affect matching either.
+        link: { to: '/dashboard', search: { window: '30d' } },
+        children: [
+          { id: 'dashboard-sessions', label: 'Sessions', link: { to: '/dashboard/sessions' } },
+          { id: 'dashboard-traffic', label: 'Traffic', link: { to: '/dashboard/traffic' } },
+          { id: 'dashboard-revenue', label: 'Revenue', link: { to: '/dashboard/revenue' } },
+        ],
+      },
+      { id: 'mobile-nav-pill', label: 'Mobile nav pill', link: { to: '/mobile-nav-pill' } },
+      {
+        id: 'controls-mobile',
+        label: 'Controls (mobile)',
+        link: { to: '/controls-mobile' },
+      },
+      { id: 'components', label: 'Components', link: { to: '/components' } },
+      { id: 'charts-page', label: 'Charts', link: { to: '/charts' } },
+      // The playground's `reports` shape: a disabled placeholder that deliberately borrows an
+      // already-covered route rather than inventing one. Declared AFTER `components`, so the
+      // definition-order tie-break keeps `components` the winner at `/components`.
+      { id: 'reports', label: 'Reports', disabled: true, link: { to: '/components' } },
+    ]),
+  ],
+})
+
+const ROUTE_PATHS = [
+  '/',
+  '/dashboard',
+  '/dashboard/sessions',
+  '/dashboard/traffic',
+  '/dashboard/revenue',
+  '/mobile-nav-pill',
+  '/controls-mobile',
+  '/components',
+  '/charts',
+]
+
+type NavProbeOpts = { isActive?: (item: AnyNavItem) => boolean }
+type NavResult = { sections: SidebarSection[] }
+type Sink = { current: NavResult | null }
+
+/** Depth-first flatten of the rendered `SidebarSection[]` — the same shape every downstream reader
+ * (the sidebar, the mobile bar, the breadcrumb) walks. */
+function flattenItems(sections: SidebarSection[]): SidebarItem[] {
+  const out: SidebarItem[] = []
+  const walk = (items: SidebarItem[]): void => {
+    for (const item of items) {
+      out.push(item)
+      if (item.children) walk(item.children)
+    }
+  }
+  for (const section of sections) walk(section.items)
+  return out
+}
+
+async function mountNav(entry: string, opts?: NavProbeOpts): Promise<Sink> {
+  const sink: Sink = { current: null }
+
+  function NavProbe(): ReactNode {
+    const nav = useNav(NAV, opts)
+    sink.current = { sections: nav.sections }
+    return null
+  }
+
+  const rootRoute = createRootRoute({
+    component: () => (
+      <>
+        <NavProbe />
+        <Outlet />
+      </>
+    ),
+  })
+  const children = ROUTE_PATHS.map((path) =>
+    createRoute({ getParentRoute: () => rootRoute, path, component: () => null }),
+  )
+  const router = createRouter({
+    routeTree: rootRoute.addChildren(children),
+    history: createMemoryHistory({ initialEntries: [entry] }),
+  })
+
+  render(<RouterProvider router={router} />)
+  await waitFor(() => {
+    expect(router.state.status).toBe('idle')
+  })
+  return sink
+}
+
+describe('useNav — exclusivity', () => {
+  test('exactly one row is active at every route in the definition', async () => {
+    for (const path of ROUTE_PATHS) {
+      const sink = await mountNav(path)
+      const items = flattenItems(sink.current!.sections)
+      const activeCount = items.filter((item) => item.active).length
+      expect(activeCount).toBe(1)
+      cleanup()
+    }
+  })
+
+  test('the deepest match wins — a child route does not also light its parent', async () => {
+    const sink = await mountNav('/dashboard/sessions')
+    const items = flattenItems(sink.current!.sections)
+    const dashboard = items.find((item) => item.key === 'dashboard')
+    const sessions = items.find((item) => item.key === 'dashboard-sessions')
+    expect(dashboard?.active).toBe(false)
+    expect(sessions?.active).toBe(true)
+  })
+
+  test('the parent of the active row is an ancestor, not active', async () => {
+    const sink = await mountNav('/dashboard/sessions')
+    const items = flattenItems(sink.current!.sections)
+    const dashboard = items.find((item) => item.key === 'dashboard')
+    expect(dashboard?.ancestor).toBe(true)
+    expect(dashboard?.active).toBe(false)
+  })
+
+  test('a same-path duplicate destination is neither active nor an ancestor', async () => {
+    const sink = await mountNav('/components')
+    const items = flattenItems(sink.current!.sections)
+    const components = items.find((item) => item.key === 'components')
+    const reports = items.find((item) => item.key === 'reports')
+    expect(components?.active).toBe(true)
+    expect(reports?.active).toBe(false)
+    expect(reports?.ancestor).toBeFalsy()
+  })
+
+  test("'/' stays exact — the root never lights on a nested route", async () => {
+    const sink = await mountNav('/dashboard')
+    const items = flattenItems(sink.current!.sections)
+    const home = items.find((item) => item.key === 'home')
+    expect(home?.active).toBe(false)
+    expect(home?.ancestor).toBeFalsy()
+  })
+
+  test('an item whose exact route is never visited still lights on a descendant route', async () => {
+    // `/dashboard` itself is never the visited entry in this test — only its descendant is —
+    // proving the fix kept `fuzzy: true` as the default rather than flipping every item to exact.
+    const sink = await mountNav('/dashboard/traffic')
+    const items = flattenItems(sink.current!.sections)
+    const dashboard = items.find((item) => item.key === 'dashboard')
+    expect(dashboard?.ancestor).toBe(true)
+    expect(dashboard?.active).toBe(false)
+  })
+
+  test('an isActive override cannot light two rows either', async () => {
+    const sink = await mountNav('/', {
+      isActive: (item) => item.id === 'components' || item.id === 'charts-page',
+    })
+    const items = flattenItems(sink.current!.sections)
+    const activeCount = items.filter((item) => item.active).length
+    expect(activeCount).toBe(1)
+  })
+})

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

@@ -13,6 +13,7 @@ import { createElement, useMemo } from 'react'
 import type { ElementType, ReactNode } from 'react'
 import { Link, useMatchRoute, useRouterState } from '@tanstack/react-router'
 import type { MobileNavConfig, NavAnchor, SidebarItem, SidebarSection } from '../nav/types'
+import { flattenNav } from './nav'
 import type { AnyNavGroup, AnyNavItem, NavConfig, NavItemId, NavTabId } from './nav'
 
 export type UseNavOptions<G extends ReadonlyArray<AnyNavGroup>> = {
@@ -24,8 +25,6 @@ export type UseNavOptions<G extends ReadonlyArray<AnyNavGroup>> = {
   badges?: Partial<Record<NavItemId<G>, number | ReactNode>>
   /** Override active detection entirely. */
   isActive?: (item: AnyNavItem) => boolean
-  /** Passed straight through into the returned `mobileNav`. */
-  moreExtra?: ReactNode
   getScrollElement?: () => HTMLElement | null
 }
 
@@ -57,40 +56,101 @@ export function useNav<
     const badgeOf = (id: string): number | ReactNode =>
       (badges as Record<string, number | ReactNode> | undefined)?.[id]
 
-    const isActive = (item: AnyNavItem): boolean =>
+    // Per-item match, exactly as before: the override wins when supplied, otherwise a router
+    // prefix match (`'/'` stays exact). What changed is that this boolean no longer BECOMES
+    // `active` on its own — it only says "on the path", and the pass below picks ONE winner
+    // across the whole definition so a parent and its child can no longer both read `active`.
+    const matchOf = (item: AnyNavItem): boolean =>
       isActiveOverride?.(item) ??
       Boolean(
         matchRoute({
           to: item.link.to,
           ...(item.link.params !== undefined && { params: item.link.params }),
-          // Prefix match by default so a parent stays lit on its children; `'/'` would then match
-          // everything, so it is always exact.
           fuzzy: item.exact !== true && item.link.to !== '/',
         }),
       )
 
+    // One pass over the WHOLE flattened definition (`flattenNav` — depth-first, parent then
+    // children, the same order every other reader of a nav config walks it) rather than a
+    // per-item independent check, which is what let a parent prefix-match stay lit alongside an
+    // exact-matching child. The most SPECIFIC match (most non-empty `/`-segments in `link.to`)
+    // wins; a tie (the playground's `reports`/`components` shape, both pointing at `/components`)
+    // keeps the FIRST item in definition order, since only a strictly later, strictly longer match
+    // ever replaces the current winner below.
+    const allItems = flattenNav(config)
+    const specificity = (to: string): number => to.split('/').filter(Boolean).length
+    const matchedById = new Map<string, boolean>()
+    let winnerId: string | undefined
+    let winnerTo: string | undefined
+    for (const item of allItems) {
+      const matched = matchOf(item)
+      matchedById.set(item.id, matched)
+      if (
+        matched &&
+        (winnerTo === undefined || specificity(item.link.to) > specificity(winnerTo))
+      ) {
+        winnerId = item.id
+        winnerTo = item.link.to
+      }
+    }
+
+    // `active` is true for the winner only. `ancestor` is true for a matched item that sits
+    // strictly on the winner's PATH (`winnerTo` starts with `item.link.to + '/'`) — a same-length
+    // tie loser matches nothing here (its own `to` cannot be a strict prefix of an equally long
+    // `winnerTo`), so it reads as neither active nor an ancestor, which is the point: two
+    // destinations sharing one route are siblings, not a hierarchy.
+    const resolveState = (item: AnyNavItem): { active: boolean; ancestor: boolean } => {
+      if (item.id === winnerId) return { active: true, ancestor: false }
+      const matched = matchedById.get(item.id) ?? false
+      const ancestor = winnerTo !== undefined && matched && winnerTo.startsWith(`${item.link.to}/`)
+      return { active: false, ancestor }
+    }
+
     const toSidebarItem = (item: AnyNavItem): SidebarItem => {
       // One anchor per destination. Basalt renders every pixel of chrome around it (desktop row,
       // 56px slot, 44px sheet row) and only hosts this component, so `preload`, middle-click and
       // back/forward all keep working. `Link as ElementType` is the single cast in the whole
       // chain: the widened `AnyNavLink['search']` is `unknown`, which `LinkComponentProps` rejects.
       // The consumer gets zero casts, which is the point.
+      //
+      // `activeOptions: { exact: true }` is what makes `resolveState` above the ONLY authority on
+      // active, and it is not a preference — a `Link` computes its own `isActive` (default
+      // `activeOptions.exact: false`, i.e. prefix) and spreads `{ 'data-status': 'active',
+      // 'aria-current': 'page' }` LAST, after `activeProps` and after every caller prop
+      // (`@tanstack/react-router/dist/esm/link.js` — `...isActive && STATIC_ACTIVE_PROPS` is the
+      // final entry of the returned object). So `aria-current` cannot be overridden from outside;
+      // the only lever is `isActive` itself. Left at its default, the router re-derived the exact
+      // fuzzy match this resolver exists to replace, and at `/dashboard/sessions` BOTH the parent
+      // and the child anchor carried `aria-current="page"` even with basalt's own model marking one
+      // of them an ancestor — verified in Chrome, and the reason the first attempt at this fix
+      // measured as no fix at all.
+      //
+      // Exact here does NOT narrow basalt's own law. `resolveState` still matches fuzzily and still
+      // lights an item whose exact route is never visited; that item is simply named by the
+      // `aria-current` `app-sidebar.tsx` stamps itself, which survives because the router's spread
+      // is conditional on ITS `isActive` being true.
       const Anchor: NavAnchor = (props) =>
-        createElement(Link as ElementType, { ...item.link, ...props })
+        createElement(Link as ElementType, {
+          ...item.link,
+          activeOptions: { exact: true },
+          ...props,
+        })
 
       const badge = badgeOf(item.id)
       const children = item.children?.map(toSidebarItem)
+      const { active, ancestor } = resolveState(item)
 
       return {
         key: item.id,
         label: item.label,
         icon: item.icon,
         Anchor,
-        // Per-destination active only. Rolling a child's active state up into its parent is the
-        // MOBILE SLOT's rule (§2.3.12) and belongs to `projectMobileNav`, which reads `children`
-        // anyway — doing it here too would also light a desktop parent row whose own route does
-        // not match.
-        active: isActive(item),
+        // Exactly one destination in the WHOLE definition reads `active` (`resolveState` above).
+        // Rolling that up into a mobile SLOT (any descendant active → the slot reads active) is
+        // still `projectMobileNav`'s job, which reads `children` for that. `ancestor` is the
+        // desktop-only middle state: a matched item that sits on the winner's path but isn't it.
+        active,
+        ...(ancestor && { ancestor }),
         ...(item.short !== undefined && { short: item.short }),
         ...(item.mobile !== undefined && { mobile: item.mobile }),
         ...(item.disabled !== undefined && { disabled: item.disabled }),
@@ -119,7 +179,6 @@ export function useNav<
   }, [config, matchRoute, href, badges, isActiveOverride])
 
   const mobile = config.mobile
-  const moreExtra = opts?.moreExtra
   const getScrollElement = opts?.getScrollElement
 
   const mobileNav = useMemo<MobileNavConfig>(() => {
@@ -137,10 +196,9 @@ export function useNav<
       ...(mobile?.maxTabs !== undefined && { maxTabs: mobile.maxTabs }),
       ...(mobile?.menuMax !== undefined && { menuMax: mobile.menuMax }),
       ...(mobile?.moreLabel !== undefined && { moreLabel: mobile.moreLabel }),
-      ...(moreExtra !== undefined && { moreExtra }),
       ...(getScrollElement !== undefined && { getScrollElement }),
     }
-  }, [config, mobile, moreExtra, getScrollElement])
+  }, [config, mobile, getScrollElement])
 
   return { sections, mobileNav }
 }

package/src/section/index.ts

@@ -0,0 +1 @@
+export { Section, type SectionProps } from './section'

package/src/section/section.module.css

@@ -0,0 +1,104 @@
+/*
+ * Section — the tier-2 heading composer (docs/CONTROLS-SPEC.md §2.2). No border/background of its
+ * own — one shaded container level per page belongs to the cards inside a Section
+ * (`ChartCard`/`StatCard`), not to the Section itself.
+ */
+
+/*
+ * 12px from the header to the body, and the same between two body children — one rhythm, read from
+ * the stack scale (`--vx-space-stack-md`) instead of the card-inset scale
+ * (`--mantine-spacing-sm`, 13px). A Section is a page-level GROUPING, so its gaps belong to the
+ * vertical rhythm, not to the inset ladder its cards use.
+ */
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-md, 0.75rem);
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-md, 0.75rem);
+}
+
+/*
+ * `summary` — the always-visible row under the header. No border, no background (the Section owns
+ * neither); it is a plain flow row, so a consumer's `Group` of stats or one line of `Text` lands
+ * where the body would have started.
+ */
+.summary {
+  display: flex;
+  flex-direction: column;
+  gap: var(--mantine-spacing-xs, 0.625rem);
+}
+
+/*
+ * The collapse chevron — a plain control, not a Mantine ActionIcon, so it sits directly in the header
+ * row (its own CtlSlot fragment would nest a theme provider around one glyph). It is sized to the
+ * `ctl` tier BY HAND for exactly that reason: a 12px glyph in a 20px box was a different height from
+ * every other control in the same header, which is what made the section header read as ragged. 30px
+ * square, glyph centred, no padding — the box IS the tier.
+ */
+.chevron {
+  /* `relative` is the anchor for the C15 hit-area overlay in the `< sm` block at the bottom. */
+  position: relative;
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  /* `--vx-space-control-height-ctl` is a bare rem — the theme's `ctlSizeVars` (`theme/index.ts`)
+   * reconstructs every OTHER ctl-tier box as `calc(<rem> * var(--mantine-scale))` so it tracks
+   * Mantine's `theme.scale`; read raw here, this box used to stay fixed while a scaled Button/Input
+   * beside it grew or shrank, reintroducing the exact raggedness this control was sized to fix. */
+  width: calc(var(--vx-space-control-height-ctl) * var(--mantine-scale, 1));
+  height: calc(var(--vx-space-control-height-ctl) * var(--mantine-scale, 1));
+  appearance: none;
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  border-radius: var(--vx-radius-ctrl);
+  color: var(--vx-muted);
+  cursor: pointer;
+}
+
+.chevron:hover,
+.chevron:focus-visible {
+  color: var(--vx-ink);
+  background: var(--vx-surface-subtle);
+}
+
+.chevron svg {
+  transition: transform 150ms ease;
+}
+
+.chevron[data-open='false'] svg {
+  transform: rotate(-90deg);
+}
+
+/*
+ * Law C15 — the chevron is a 12px glyph in a 20px box, which is a fine mouse target and an
+ * unusable thumb one. Below `sm` an `::after` overlay lifts the HIT area to
+ * `--vx-space-touch-control-height` (36px at level 0) while the visible glyph stays put — the same
+ * overlay `shell/page-bar.module.css` draws for the bar's own controls. `overflow: visible` is part
+ * of the fix, not tidying: an overlay that extends past the box is clipped by any `overflow:
+ * hidden` on the host (which is what made the identical overlay a no-op on Mantine's Button roots).
+ */
+@media (max-width: 47.99375em) {
+  .chevron {
+    overflow: visible;
+  }
+
+  .chevron::after {
+    content: '';
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    translate: -50% -50%;
+    width: 100%;
+    height: 100%;
+    min-width: var(--vx-space-touch-control-height, 2.25rem);
+    min-height: var(--vx-space-touch-control-height, 2.25rem);
+  }
+}

package/src/section/section.module.css.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 root: string
+  readonly body: string
+  readonly summary: string
+  readonly chevron: string
+}
+export default classes

package/src/section/section.test.tsx

@@ -0,0 +1,204 @@
+/**
+ * `Section` — the tier-2 heading composer (docs/CONTROLS-SPEC.md §2.2): the collapse contract
+ * (persisted vs local, header stays drawn, body unmounts, tabs hide), the scroll-anchor style, and
+ * the ≤3-actions dev warning (C6).
+ */
+import { MantineProvider } from '@mantine/core'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, spyOn, test } from 'bun:test'
+import type { ReactElement } from 'react'
+import { Section } from './section'
+
+function renderWith(node: ReactElement) {
+  return render(<MantineProvider>{node}</MantineProvider>)
+}
+
+beforeEach(() => {
+  window.localStorage.clear()
+})
+
+describe('Section composes WidgetHeader at the section tier', () => {
+  test('renders an h2 carrying the title', () => {
+    renderWith(
+      <Section title="Revenue">
+        <div>body</div>
+      </Section>,
+    )
+    expect(screen.getByRole('heading', { level: 2, name: 'Revenue' })).toBeDefined()
+  })
+})
+
+describe('collapsible', () => {
+  test('the header stays drawn when closed; only the body unmounts', () => {
+    renderWith(
+      <Section title="Usage" collapsible>
+        <div>body content</div>
+      </Section>,
+    )
+    expect(screen.getByRole('heading', { level: 2, name: 'Usage' })).toBeDefined()
+    expect(screen.getByText('body content')).toBeDefined()
+
+    fireEvent.click(screen.getByRole('button', { name: 'Collapse section' }))
+
+    expect(screen.getByRole('heading', { level: 2, name: 'Usage' })).toBeDefined()
+    expect(screen.queryByText('body content')).toBeNull()
+  })
+
+  test('tabs hide while collapsed', () => {
+    renderWith(
+      <Section title="Usage" collapsible tabs={<div>the tabs</div>}>
+        <div>body</div>
+      </Section>,
+    )
+    expect(screen.getByText('the tabs')).toBeDefined()
+    fireEvent.click(screen.getByRole('button', { name: 'Collapse section' }))
+    expect(screen.queryByText('the tabs')).toBeNull()
+  })
+
+  test('an unpersisted fold (no persistKey) does not touch localStorage', () => {
+    renderWith(
+      <Section title="Usage" collapsible>
+        <div>body</div>
+      </Section>,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Collapse section' }))
+    expect(window.localStorage.length).toBe(0)
+  })
+
+  test('persistKey persists the fold state under basalt:section:<key>', () => {
+    renderWith(
+      <Section title="Usage" collapsible persistKey="usage">
+        <div>body</div>
+      </Section>,
+    )
+    fireEvent.click(screen.getByRole('button', { name: 'Collapse section' }))
+
+    const raw = window.localStorage.getItem('basalt:section:usage')
+    expect(raw).not.toBeNull()
+    expect(JSON.parse(raw ?? '{}')).toMatchObject({ value: false })
+  })
+})
+
+describe('id — the scroll-anchor contract', () => {
+  test('sets the id and a scrollMarginTop clearing both sticky bars', () => {
+    const { container } = renderWith(
+      <Section id="usage" title="Usage">
+        <div>body</div>
+      </Section>,
+    )
+    const root = container.querySelector('#usage')
+    expect(root).not.toBeNull()
+    const style = root?.getAttribute('style') ?? ''
+    expect(style).toContain('scroll-margin-top')
+    expect(style).toContain('--app-shell-header-height')
+    expect(style).toContain('--basalt-page-bar-h')
+  })
+
+  test('omitting id sets neither an id nor the anchor style', () => {
+    const { container } = renderWith(
+      <Section title="Usage">
+        <div>body</div>
+      </Section>,
+    )
+    const root = container.firstElementChild
+    expect(root?.id).toBe('')
+    expect(root?.getAttribute('style')).toBeNull()
+  })
+})
+
+// Relies on the default test-runner NODE_ENV being non-production (`isDev()` true), matching
+// `data/data-table.test.tsx`'s manualPagination dev-throw tests — no explicit env override needed.
+describe('≤3 actions — the dev-only budget warning (C6)', () => {
+  // `Children.count` (like every `Children.*` helper) does not recurse into a Fragment passed as
+  // a single node — an ARRAY of actions is what the count actually sees, same shape a consumer
+  // building the list programmatically would pass.
+  test('4 actions warns', () => {
+    const warn = spyOn(console, 'warn').mockImplementation(() => {})
+    renderWith(
+      <Section
+        title="Usage"
+        actions={[1, 2, 3, 4].map((n) => (
+          <button key={n} type="button">
+            {n}
+          </button>
+        ))}
+      >
+        <div>body</div>
+      </Section>,
+    )
+    expect(warn).toHaveBeenCalledTimes(1)
+    expect(String(warn.mock.calls[0]?.[0])).toContain('≤3 budget')
+    warn.mockRestore()
+  })
+
+  test('3 actions does not warn', () => {
+    const warn = spyOn(console, 'warn').mockImplementation(() => {})
+    renderWith(
+      <Section
+        title="Usage"
+        actions={[1, 2, 3].map((n) => (
+          <button key={n} type="button">
+            {n}
+          </button>
+        ))}
+      >
+        <div>body</div>
+      </Section>,
+    )
+    expect(warn).not.toHaveBeenCalled()
+    warn.mockRestore()
+  })
+})
+
+describe('defaultOpen', () => {
+  test('defaultOpen={false} opens collapsed, and the chevron still expands it', () => {
+    renderWith(
+      <Section title="Usage" collapsible defaultOpen={false}>
+        <div>body content</div>
+      </Section>,
+    )
+    expect(screen.queryByText('body content')).toBeNull()
+
+    fireEvent.click(screen.getByRole('button', { name: 'Expand section' }))
+    expect(screen.getByText('body content')).toBeDefined()
+  })
+
+  test('a persisted value outranks it — a section the reader opened stays open', () => {
+    window.localStorage.setItem('basalt:section:usage', JSON.stringify({ v: 1, value: true }))
+    renderWith(
+      <Section title="Usage" collapsible persistKey="usage" defaultOpen={false}>
+        <div>body content</div>
+      </Section>,
+    )
+    expect(screen.getByText('body content')).toBeDefined()
+  })
+})
+
+describe('summary — visible collapsed or not', () => {
+  test('a collapsed section still states its headline figures', () => {
+    renderWith(
+      <Section title="Usage" collapsible summary={<span>48,204 requests</span>}>
+        <div>body content</div>
+      </Section>,
+    )
+    expect(screen.getByText('48,204 requests')).toBeDefined()
+
+    fireEvent.click(screen.getByRole('button', { name: 'Collapse section' }))
+
+    expect(screen.queryByText('body content')).toBeNull()
+    expect(screen.getByText('48,204 requests')).toBeDefined()
+  })
+
+  test('it renders under the header, above where the body starts', () => {
+    renderWith(
+      <Section title="Usage" summary={<span>48,204 requests</span>}>
+        <div>body content</div>
+      </Section>,
+    )
+    const summary = screen.getByText('48,204 requests').parentElement
+    expect(
+      summary?.previousElementSibling?.contains(screen.getByRole('heading', { level: 2 })),
+    ).toBe(true)
+    expect(summary?.nextElementSibling?.contains(screen.getByText('body content'))).toBe(true)
+  })
+})