basalt-ui 1.25.0 → 1.26.0

package/src/shell/page-bar.test.tsx

@@ -0,0 +1,316 @@
+/**
+ * `PageBar`'s two invariants that only a rendered tree can prove (`docs/CONTROLS-SPEC.md` §2.1):
+ * row 1 leaves the page and lands in the app-shell header, row 2 does NOT — it stays in the page
+ * flow, sticks under the header, and publishes its measured height. Both are decided by context
+ * (is there a `BasaltShell` above me?), so a unit test of the component alone can't see either.
+ *
+ * The `--basalt-page-bar-h` publish is the one piece needing a real ResizeObserver callback. The
+ * harness shim (`tests/setup/dom.ts`) is a deliberate no-op, so this file installs a controllable
+ * fake for the duration of the suite and fires the callback by hand against a stubbed rect —
+ * happy-dom evaluates no layout, so a genuine observer would only ever report 0 (which the
+ * `height > 0` guard correctly refuses to publish).
+ */
+import { MantineProvider } from '@mantine/core'
+import { render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { useEffect } from 'react'
+import type { ReactNode } from 'react'
+import { BasaltShell, PageBar } from './index'
+import type { SidebarSection } from './index'
+
+const BRAND = { name: 'Argo' }
+const ONE_SECTION: SidebarSection[] = [
+  { label: 'Main', items: [{ key: 'home', label: 'Home', icon: null }] },
+]
+
+const HEIGHT_VAR = '--basalt-page-bar-h'
+
+type Observed = { node: Element; trigger: () => void }
+
+let observed: Observed[] = []
+let nativeResizeObserver: typeof ResizeObserver
+
+/** A ResizeObserver whose callback the test fires — see this file's doc for why the shim can't. */
+function installFakeResizeObserver(): void {
+  observed = []
+  class FakeResizeObserver {
+    constructor(private readonly callback: ResizeObserverCallback) {}
+    observe(node: Element): void {
+      observed.push({
+        node,
+        trigger: () => this.callback([], this as unknown as ResizeObserver),
+      })
+    }
+    unobserve(): void {}
+    disconnect(): void {}
+  }
+  window.ResizeObserver = FakeResizeObserver as unknown as typeof ResizeObserver
+}
+
+/** Every element measures `height` — the layout happy-dom never evaluates, for the whole tree. */
+function stubEveryRect(height: number): void {
+  Element.prototype.getBoundingClientRect = function rect() {
+    return { height, width: 0, top: 0, left: 0, right: 0, bottom: height, x: 0, y: 0 } as DOMRect
+  }
+}
+
+function stubHeight(node: HTMLElement, height: number): void {
+  Object.defineProperty(node, 'getBoundingClientRect', {
+    configurable: true,
+    value: () => ({ height, width: 0, top: 0, left: 0, right: 0, bottom: height, x: 0, y: 0 }),
+  })
+}
+
+beforeEach(() => {
+  nativeResizeObserver = window.ResizeObserver
+  installFakeResizeObserver()
+})
+
+afterEach(() => {
+  window.ResizeObserver = nativeResizeObserver
+  document.documentElement.style.removeProperty(HEIGHT_VAR)
+})
+
+const shellRow = () => document.querySelector<HTMLElement>('[data-basalt-page-bar="shell"]')
+
+describe('PageBar inside a BasaltShell', () => {
+  const renderInShell = () =>
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION}>
+          <PageBar
+            actions={{
+              primary: { key: 'row1', kind: 'custom', node: <span data-testid="row1" /> },
+            }}
+            tabs={<span data-testid="row2" />}
+          />
+        </BasaltShell>
+      </MantineProvider>,
+    )
+
+  test('row 1 portals into the app-shell header — every copy of it', () => {
+    renderInShell()
+    const header = document.querySelector('.mantine-AppShell-header')
+    expect(header).not.toBeNull()
+    const copies = screen.getAllByTestId('row1')
+    expect(copies.length).toBeGreaterThan(0)
+    for (const copy of copies) expect(header?.contains(copy)).toBe(true)
+  })
+
+  test('row 2 stays in the page flow — NOT in the header', () => {
+    renderInShell()
+    const header = document.querySelector('.mantine-AppShell-header')
+    const row2 = screen.getByTestId('row2')
+    expect(header?.contains(row2)).toBe(false)
+    expect(shellRow()?.contains(row2)).toBe(true)
+  })
+
+  test('a ResizeObserver reading publishes --basalt-page-bar-h on documentElement', () => {
+    renderInShell()
+    const row = shellRow()
+    expect(row).not.toBeNull()
+    stubHeight(row as HTMLElement, 44)
+    const entry = observed.find((o) => o.node === row)
+    expect(entry).toBeDefined()
+    entry?.trigger()
+    expect(document.documentElement.style.getPropertyValue(HEIGHT_VAR)).toBe('44px')
+  })
+
+  test('a zero reading is refused — the guard is what kept a consumer sticky offset from collapsing', () => {
+    renderInShell()
+    const row = shellRow()
+    stubHeight(row as HTMLElement, 0)
+    observed.find((o) => o.node === row)?.trigger()
+    expect(document.documentElement.style.getPropertyValue(HEIGHT_VAR)).toBe('')
+  })
+
+  test('unmounting removes the property, so the next route does not inherit this height', () => {
+    const { unmount } = renderInShell()
+    const row = shellRow()
+    stubHeight(row as HTMLElement, 44)
+    observed.find((o) => o.node === row)?.trigger()
+    unmount()
+    expect(document.documentElement.style.getPropertyValue(HEIGHT_VAR)).toBe('')
+  })
+
+  test('title is ignored inside a shell — the breadcrumb names the page (law C8)', () => {
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION}>
+          <PageBar title="Ignored" tabs={<span data-testid="row2" />} />
+        </BasaltShell>
+      </MantineProvider>,
+    )
+    expect(screen.queryByText('Ignored')).toBeNull()
+  })
+})
+
+/**
+ * A consumer's own test DOM has no `ResizeObserver` unless it installs a shim — happy-dom and jsdom
+ * both lack it. An unguarded `new ResizeObserver` in the effect turned that into a hard throw from
+ * every page test that mounted a bar, which is a framework bug, not a consumer one.
+ */
+describe('PageBar with no ResizeObserver at all', () => {
+  test('a shell-less bar still mounts, and publishes nothing rather than throwing', () => {
+    // @ts-expect-error deliberately removing a DOM global the guard exists to survive
+    window.ResizeObserver = undefined
+    expect(() =>
+      render(
+        <MantineProvider>
+          <PageBar title="linewatch" tabs={<span data-testid="row2" />} />
+        </MantineProvider>,
+      ),
+    ).not.toThrow()
+    expect(screen.getByRole('heading', { level: 1 }).textContent).toBe('linewatch')
+    // happy-dom evaluates no layout, so the one-shot measure reads 0 and the guard refuses it.
+    expect(document.documentElement.style.getPropertyValue(HEIGHT_VAR)).toBe('')
+  })
+
+  test('a filters row mounts too, and unmounting still cleans up', () => {
+    // Only the SHELL-LESS form is exercised: `BasaltShell` mounts a Mantine `AppShell` whose own
+    // internals construct a `ResizeObserver`, so that half can never run without one — which is
+    // also why the guard matters for the shell-less consumer (linewatch) specifically.
+    // @ts-expect-error see above
+    window.ResizeObserver = undefined
+    const { unmount } = render(
+      <MantineProvider>
+        <PageBar title="linewatch" filters={<span data-testid="filters" />} />
+      </MantineProvider>,
+    )
+    expect(screen.getByTestId('filters')).toBeDefined()
+    expect(() => unmount()).not.toThrow()
+    expect(document.documentElement.style.getPropertyValue(HEIGHT_VAR)).toBe('')
+  })
+})
+
+describe('PageBar without a shell', () => {
+  test('renders the title as the page heading and sticks both rows at the top', () => {
+    render(
+      <MantineProvider>
+        <PageBar title="linewatch" tabs={<span data-testid="row2" />} />
+      </MantineProvider>,
+    )
+    const heading = screen.getByRole('heading', { level: 1 })
+    expect(heading.textContent).toBe('linewatch')
+    const bar = document.querySelector<HTMLElement>('[data-basalt-page-bar="standalone"]')
+    expect(bar).not.toBeNull()
+    expect(bar?.contains(heading)).toBe(true)
+    expect(bar?.contains(screen.getByTestId('row2'))).toBe(true)
+  })
+
+  test('renders nothing at all when every slot is empty (law C14)', () => {
+    render(
+      <MantineProvider>
+        <PageBar />
+      </MantineProvider>,
+    )
+    expect(document.querySelector('[data-basalt-page-bar]')).toBeNull()
+  })
+})
+
+/**
+ * The sticky offsets and law C7's no-horizontal-scroll rule live entirely in CSS, and a CSS module
+ * resolves to `''` under `bun test` (no bundler in the loop) — so they are asserted against the
+ * shipped CSS TEXT, the same pattern `prose.module.css.test.ts` and `styles.floor.test.ts` use.
+ */
+describe('page-bar.module.css', () => {
+  const css = readFileSync(
+    resolve(dirname(fileURLToPath(import.meta.url)), 'page-bar.module.css'),
+    'utf8',
+  )
+  /** Declarations only — the block comments above them discuss `::before` and `overflow` by name. */
+  const decls = css.replace(/\/\*[\s\S]*?\*\//g, '')
+
+  test('row 2 inside a shell sticks at the AppShell header-height VAR, never a measured number', () => {
+    const rule = decls.match(/\.row2Sticky\s*\{([^}]+)\}/)
+    expect(rule).not.toBeNull()
+    expect(rule?.[1]).toContain('position: sticky')
+    expect(rule?.[1]).toContain('top: var(--app-shell-header-height, 0px)')
+  })
+
+  test('the shell-less bar sticks at the top of the document', () => {
+    const rule = decls.match(/\.bar\s*\{([^}]+)\}/)
+    expect(rule?.[1]).toContain('position: sticky')
+    expect(rule?.[1]).toContain('top: 0')
+  })
+
+  test('no row ever scrolls sideways or wraps (law C7)', () => {
+    expect(decls).not.toContain('overflow-x')
+    expect(decls).not.toMatch(/overflow(-y)?:\s*(auto|scroll)/)
+    expect(decls.match(/flex-wrap: nowrap/g)?.length).toBeGreaterThanOrEqual(5)
+  })
+
+  test('the mobile hit area rides ::after — Mantine owns Button::before for its loading overlay', () => {
+    expect(decls).toContain('::after')
+    expect(decls).not.toContain('::before')
+    expect(decls).toContain('min-height: var(--vx-space-touch-control-height)')
+  })
+
+  test('the hit area un-clips its own host — Mantine roots are overflow: hidden', () => {
+    // Without this the overlay is clipped back to the 30px box and law C15's 36px target does not
+    // exist at all, which no token assertion can catch.
+    expect(decls).toMatch(/:not\(\[data-loading\]\)[\s\S]{0,80}overflow: visible/)
+  })
+})
+
+/**
+ * The height has to exist at the FIRST paint, not one frame later: `Section`'s scroll anchor reads
+ * `var(--basalt-page-bar-h, 0px)`, so a cold load of `/page#anchor` that scrolls before the property
+ * lands leaves the anchored heading under the sticky bar.
+ *
+ * The probe is what makes the timing observable. Passive effects run child-first, so a probe INSIDE
+ * the bar reads the property before the bar's own passive effect would have written it — it can only
+ * see `44px` if the publish happened in the layout phase.
+ */
+describe('the height var is published before first paint', () => {
+  const nativeRect = Element.prototype.getBoundingClientRect
+
+  afterEach(() => {
+    Element.prototype.getBoundingClientRect = nativeRect
+  })
+
+  test('a passive effect inside the bar already sees --basalt-page-bar-h', () => {
+    const seen: { current: string | null } = { current: null }
+    function Probe(): ReactNode {
+      useEffect(() => {
+        seen.current = document.documentElement.style.getPropertyValue(HEIGHT_VAR)
+      }, [])
+      return <span data-testid="row2" />
+    }
+
+    stubEveryRect(44)
+    render(
+      <MantineProvider>
+        <PageBar title="linewatch" tabs={<Probe />} />
+      </MantineProvider>,
+    )
+
+    expect(seen.current).toBe('44px')
+  })
+})
+
+describe('className reaches the bar root in both forms', () => {
+  test('shell-less: it joins the standalone root, keeping the module class', () => {
+    render(
+      <MantineProvider>
+        <PageBar title="linewatch" tabs={<span data-testid="row2" />} className="lw-bleed" />
+      </MantineProvider>,
+    )
+    const bar = document.querySelector<HTMLElement>('[data-basalt-page-bar="standalone"]')
+    expect(bar?.classList.contains('lw-bleed')).toBe(true)
+  })
+
+  test('in a shell: it joins row 2s sticky wrapper, not the portalled row 1', () => {
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION}>
+          <PageBar tabs={<span data-testid="row2" />} className="argo-bleed" />
+        </BasaltShell>
+      </MantineProvider>,
+    )
+    expect(shellRow()?.classList.contains('argo-bleed')).toBe(true)
+  })
+})

package/src/shell/page-bar.tsx

@@ -0,0 +1,315 @@
+/**
+ * `PageBar` — the tier-1 home (`docs/CONTROLS-SPEC.md` §2.1). One per page; every page-level
+ * control enters through one of its slots (law C1) and is sized by it (law C5).
+ *
+ * Two rows, and WHERE they render is decided by context, never by a prop:
+ *
+ * - **Inside `BasaltShell`** row 1 (`actions`, `sync`) portals into the existing 48px app-shell
+ *   header — the same slot/portal mechanism `PageActions` used through 1.25.0, which this replaces.
+ *   The breadcrumb stays the header's lead, so `title` is ignored. Row 2 (`tabs`, `filters`,
+ *   `filtersEnd`) renders IN-FLOW at the top of the page content, sticky under the header, and
+ *   publishes its measured height as `--basalt-page-bar-h` on `documentElement` so a page can
+ *   compute a viewport-filling body (`calc(100dvh - var(--app-shell-header-height) -
+ *   var(--basalt-page-bar-h, 0px))`) without measuring anything itself.
+ * - **Without a shell** both rows render in-flow, sticky at the top of the document, with
+ *   `title` + `icon` leading row 1 — the page title is the bar's job when there is no breadcrumb
+ *   (law C8). The published height then covers the whole bar, since that is what content clears.
+ *
+ * An empty home renders NOTHING (law C14): a page with no tabs and no filters pays for no row 2,
+ * and the header never reserves a second mobile row the way the pre-1.26.0 two-row layout did.
+ *
+ * Originally extracted from argo's `apps/dashboard/src/components/app-shell/page-header.tsx`;
+ * linewatch's `page-header.tsx` measure-and-publish effect became the framework behaviour below.
+ */
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react'
+import type { ReactNode, RefObject } from 'react'
+import { createPortal } from 'react-dom'
+import { CtlSlot } from '../theme'
+import { BarActionRow, BarExtrasProvider, globalActionAsBarAction } from '../controls/actions'
+import { SyncButton } from '../controls/sync-button'
+import type { ActionGroupProps, BarAction, GlobalAction } from '../controls/actions'
+import type { SyncButtonProps } from '../controls/sync-button'
+import classes from './page-bar.module.css'
+
+/** The custom property row 2's measured height is published on. */
+export const PAGE_BAR_HEIGHT_VAR = '--basalt-page-bar-h'
+
+type PageBarSlots = {
+  /** The header node row 1 portals into. `null` outside a shell, and until the outlet mounts. */
+  target: HTMLElement | null
+  setTarget: (el: HTMLElement | null) => void
+  /** True only under `BasaltShell` — the provider is shell-internal, so the context IS the probe. */
+  inShell: boolean
+  /** Shell `globalActions` marked `mobile: 'more'`, already shaped as kebab rows. */
+  mobileMoreActions: readonly BarAction[]
+  /** How many page kebabs are mounted. `> 0` means the shell must not render one of its own. */
+  kebabClaims: number
+  claimKebab: () => () => void
+}
+
+const NO_SLOTS: PageBarSlots = {
+  target: null,
+  setTarget: () => {},
+  inShell: false,
+  mobileMoreActions: [],
+  kebabClaims: 0,
+  claimKebab: () => () => {},
+}
+
+const PageBarContext = createContext<PageBarSlots>(NO_SLOTS)
+
+/**
+ * Internal — mounted by `BasaltShell`. Owns the portal target, and the single-kebab claim that
+ * lets the shell fall back to its OWN kebab on a route that renders no `PageBar`.
+ */
+export function PageBarProvider({
+  globalActions,
+  children,
+}: {
+  globalActions: readonly GlobalAction[]
+  children: ReactNode
+}): ReactNode {
+  const [target, setTarget] = useState<HTMLElement | null>(null)
+  const [kebabClaims, setKebabClaims] = useState(0)
+
+  const claimKebab = useCallback(() => {
+    setKebabClaims((n) => n + 1)
+    return () => setKebabClaims((n) => n - 1)
+  }, [])
+
+  const mobileMoreActions = globalActions
+    .filter((action, index) => (action.mobile ?? (index < 2 ? 'bar' : 'more')) === 'more')
+    .map(globalActionAsBarAction)
+
+  const value: PageBarSlots = {
+    target,
+    setTarget,
+    inShell: true,
+    mobileMoreActions,
+    kebabClaims,
+    claimKebab,
+  }
+
+  return (
+    <PageBarContext.Provider value={value}>
+      <BarExtrasProvider value={{ mobileMoreActions, claimKebab }}>{children}</BarExtrasProvider>
+    </PageBarContext.Provider>
+  )
+}
+
+/** Internal — the app-shell header node the active page's row 1 portals into. */
+export function PageBarOutlet({ className }: { className?: string }) {
+  const { setTarget } = useContext(PageBarContext)
+  return <div ref={setTarget} className={className} />
+}
+
+/** Internal — `true` while a page's `ActionGroup` owns the header's one mobile kebab. */
+export function usePageKebabClaimed(): boolean {
+  return useContext(PageBarContext).kebabClaims > 0
+}
+
+export type PageBarProps = {
+  /**
+   * Read only when there is no `BasaltShell` outlet (a shell-less app such as linewatch). Inside a
+   * shell the breadcrumb names the page and this is ignored.
+   */
+  title?: string
+  icon?: ReactNode
+  actions?: ActionGroupProps
+  /** `scope` is fixed to `'page'` — a global sync belongs in the shell's `globalActions` (law C12). */
+  sync?: Omit<SyncButtonProps, 'scope'>
+  /** `FilterSet` descendants only (law C1). */
+  filters?: ReactNode
+  /** Right-aligned row-2 actions ("Manage metrics"). */
+  filtersEnd?: BarAction[]
+  /** One `ViewTabs`. */
+  tabs?: ReactNode
+  /**
+   * Added to the bar's ROOT — the shell-less `<div data-basalt-page-bar="standalone">`, or row 2's
+   * sticky wrapper (`data-basalt-page-bar="shell"`) inside a `BasaltShell`. The seam for the two
+   * things only the consumer's own layout knows: bleeding the sticky bar across its container's
+   * gutters (`margin-inline: calc(var(--gutter) * -1); padding-inline: var(--gutter)`) and drawing
+   * a hairline under it (`border-bottom: 1px solid var(--vx-border)`).
+   *
+   * Scope that CSS through this class, not through a global `[data-basalt-page-bar]` selector: the
+   * data attributes are stable enough to READ (a shell-less consumer can style
+   * `[data-basalt-page-bar="standalone"]` in a pinch, and this doc is the promise that the value
+   * stays), but a global rule reaches every page in the app including the ones that want neither.
+   */
+  className?: string
+}
+
+/**
+ * `useLayoutEffect` in the browser, `useEffect` on the server — the standard isomorphic pattern, so
+ * an SSR render never trips React's "useLayoutEffect does nothing on the server" warning. The
+ * branch reads a global that cannot change between renders, so the hook identity is stable.
+ */
+const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect
+
+/**
+ * Publishes an element's measured height as a custom property on `documentElement`.
+ *
+ * **A LAYOUT effect, and a plain ref rather than ref-state.** Both halves buy the same thing: the
+ * property exists at the FIRST paint. A passive effect publishes it one frame later, which is a
+ * frame in which a cold load of `/page#anchor` has already scrolled — `scroll-margin-top` reads
+ * `var(--basalt-page-bar-h, 0px)`, so the anchored heading lands under the sticky bar and stays
+ * there. A `useState` node would also have cost a second commit before the measure could run.
+ *
+ * The `height > 0` guard is the whole point: a ResizeObserver fires once with a zero box while the
+ * element is still being laid out (and again whenever it is hidden), and publishing that zero is
+ * what made a consumer's sticky offset collapse mid-navigation. The property is removed on unmount
+ * so a route without a bar does not inherit the last one's height.
+ */
+function useMeasuredHeightVar(active: boolean): RefObject<HTMLDivElement | null> {
+  const ref = useRef<HTMLDivElement | null>(null)
+
+  useIsomorphicLayoutEffect(() => {
+    const node = ref.current
+    if (!active || node === null) return
+    const publish = () => {
+      const { height } = node.getBoundingClientRect()
+      if (height > 0) {
+        document.documentElement.style.setProperty(PAGE_BAR_HEIGHT_VAR, `${height}px`)
+      }
+    }
+    publish()
+    // Guarded like `FilterSet`'s identical call: happy-dom and jsdom ship no `ResizeObserver`, and a
+    // consumer's page test mounting a bar without the shim would otherwise throw from this effect.
+    // The one-shot `publish()` above already ran, so a test DOM still gets a height when it has a
+    // layout engine — it just never re-measures.
+    if (typeof ResizeObserver === 'undefined') {
+      return () => document.documentElement.style.removeProperty(PAGE_BAR_HEIGHT_VAR)
+    }
+    const observer = new ResizeObserver(publish)
+    observer.observe(node)
+    return () => {
+      observer.disconnect()
+      document.documentElement.style.removeProperty(PAGE_BAR_HEIGHT_VAR)
+    }
+  }, [active])
+
+  return ref
+}
+
+/** The bar root's own class plus the consumer's, in that order (`content/toc.tsx`'s idiom). */
+function rootClass(own: string, extra: string | undefined): string {
+  return [own, extra].filter(Boolean).join(' ')
+}
+
+export function PageBar({
+  title,
+  icon,
+  actions,
+  sync,
+  filters,
+  filtersEnd,
+  tabs,
+  className,
+}: PageBarProps): ReactNode {
+  const { target, inShell } = useContext(PageBarContext)
+
+  const filtersEndActions = filtersEnd ?? []
+  const hasRow2 = tabs !== undefined || filters !== undefined || filtersEndActions.length > 0
+  const hasLead = !inShell && (title !== undefined || icon !== undefined)
+  // `filtersEnd` keeps row 1 alive on its own: below `sm` its items fold into the ROW-1 kebab (the
+  // header's single one), so the row that hosts that kebab has to exist even with no `actions`.
+  const hasRow1 =
+    actions !== undefined || sync !== undefined || hasLead || filtersEndActions.length > 0
+  const measureRef = useMeasuredHeightVar(hasRow2 || (!inShell && hasRow1))
+
+  const row1 = hasRow1 ? (
+    <div className={classes.row1}>
+      {hasLead && (
+        <div className={classes.lead}>
+          {icon !== undefined && (
+            <span className={classes.icon} aria-hidden>
+              {icon}
+            </span>
+          )}
+          {title !== undefined && <h1 className={classes.title}>{title}</h1>}
+        </div>
+      )}
+      <div className={classes.row1End}>
+        {(actions !== undefined || filtersEndActions.length > 0 || sync !== undefined) && (
+          <CtlSlot>
+            {/* THE row-1 group: the only `host: 'page'` instance, so the shell's `mobile: 'more'`
+                global actions reach exactly one kebab (`BarActionRowProps.host`). `filtersEnd`
+                joins that kebab below `sm` and renders in row 2 above it.
+
+                `sync` is handed DOWN as `syncNode` rather than rendered as a sibling here, because
+                the row's order is custom chips · secondaries · `More` · sync · primary
+                (`docs/CONTROLS-SPEC.md` §2.1) and only `BarActionRow` knows where the primary is.
+                One `CtlSlot` for the whole row now, so the sync button and the buttons around it
+                resolve the tier from the same provider. */}
+            <BarActionRow
+              {...actions}
+              host="page"
+              mobileOnly={filtersEndActions}
+              {...(sync !== undefined && { syncNode: <SyncButton {...sync} scope="page" /> })}
+            />
+          </CtlSlot>
+        )}
+      </div>
+    </div>
+  ) : null
+
+  const row2 = hasRow2 ? (
+    <div className={classes.row2}>
+      {tabs !== undefined && <CtlSlot>{tabs}</CtlSlot>}
+      {filters !== undefined && (
+        <div className={classes.filters}>
+          <CtlSlot>{filters}</CtlSlot>
+        </div>
+      )}
+      {filtersEndActions.length > 0 && (
+        <div className={classes.filtersEnd}>
+          <CtlSlot>
+            {/* Desktop only — below `sm` these live in the row-1 kebab above, never in a second one
+                (spec §2.1: mobile row 2 is tabs + the first pill + `Filters (n)`, nothing else). */}
+            <BarActionRow secondary={filtersEndActions} host="slot" viewport="desktop" />
+          </CtlSlot>
+        </div>
+      )}
+    </div>
+  ) : null
+
+  // Shell-less: one sticky bar at the top of the document holding both rows, `title` leading.
+  if (!inShell) {
+    if (row1 === null && row2 === null) return null
+    return (
+      <div
+        ref={measureRef}
+        className={rootClass(classes.bar, className)}
+        data-basalt-page-bar="standalone"
+      >
+        {row1}
+        {row2}
+      </div>
+    )
+  }
+
+  // In a shell: row 1 lives in the header (a portal), row 2 stays in the page flow and sticks
+  // underneath it. `target` is null for the first commit only — the outlet's ref sets it.
+  return (
+    <>
+      {row1 !== null && target !== null && createPortal(row1, target)}
+      {row2 !== null && (
+        <div
+          ref={measureRef}
+          className={rootClass(classes.row2Sticky, className)}
+          data-basalt-page-bar="shell"
+        >
+          {row2}
+        </div>
+      )}
+    </>
+  )
+}