basalt-ui 1.27.0 → 1.29.0

package/src/shell/page-bar.tsx

@@ -7,10 +7,11 @@
  * - **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.
+ *   `filtersEnd`) portals into a shell-owned band between the header and the scrollport
+ *   (`PageBarBandOutlet`, mounted once by `BasaltShell`) — it is never in-flow or sticky inside the
+ *   scrollport itself, since the band already sits outside it. The outlet renders unconditionally
+ *   as a zero-height, seam-less box while no page claims it (law C14), so an empty home costs
+ *   nothing.
  * - **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.
@@ -21,31 +22,53 @@
  * 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 { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
 import { createPortal } from 'react-dom'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { CtlSlot } from '../theme'
 import { BarActionRow, BarExtrasProvider, globalActionAsBarAction } from '../controls/actions'
+import { FilterPill } from '../controls/filter-pill'
+import { FilterSheet } from '../controls/filter-sheet'
 import { SyncButton } from '../controls/sync-button'
 import type { ActionGroupProps, BarAction, GlobalAction } from '../controls/actions'
 import type { SyncButtonProps } from '../controls/sync-button'
+import { useIsomorphicLayoutEffect } from './isomorphic-layout-effect'
 import classes from './page-bar.module.css'
+import asideClasses from './page-aside.module.css'
 
 /** The custom property row 2's measured height is published on. */
 export const PAGE_BAR_HEIGHT_VAR = '--basalt-page-bar-h'
 
+/**
+ * What a `PageAside` publishes when it projects itself into row 2 below `sm`
+ * (`docs/ASIDE-SPEC.md` §0 "Desktop and mobile are one declaration"). Metadata only — the aside's
+ * CHILDREN never travel through this context: they are portalled into the sheet's own node
+ * ({@link PageBarSlots.panelTarget}), because a `ReactNode` in state would be a fresh object on
+ * every parent render and the claim effect would loop.
+ */
+export type AsidePanelClaim = {
+  /** The aside's `title` — the pill's accessible name and the sheet's heading. */
+  readonly title: string
+  /** The aside's own glyph, supplied by the claimant so this module owns no aside iconography. */
+  readonly icon: ReactNode
+}
+
 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
+  /**
+   * The BAND node row 2 portals into — a shell-owned box between the header and the scrollport.
+   * Same mechanism as `target` one region down, and it exists for the same reason: where a row
+   * renders must not depend on where the consumer wrote `<PageBar>` in its page tree. Row 2 used to
+   * render in flow at the top of Main and stick there, which meant a bar nested inside a `Stack`
+   * (every real page) had `position: sticky` clamped to that wrapper and sat one shell padding low.
+   * `null` outside a shell, and until the outlet mounts.
+   */
+  bandTarget: HTMLElement | null
+  setBandTarget: (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. */
@@ -53,15 +76,34 @@ type PageBarSlots = {
   /** How many page kebabs are mounted. `> 0` means the shell must not render one of its own. */
   kebabClaims: number
   claimKebab: () => () => void
+  /** True while a mounted `PageBar` is rendering a row 2 — the row that can host the aside's pill.
+   * Without one the aside keeps its in-flow mobile form; there is nowhere to put the trigger. */
+  panelHost: boolean
+  claimPanelHost: () => () => void
+  /** The projecting aside, or `null`. At most one — the aside region holds one page at a time. */
+  panel: AsidePanelClaim | null
+  claimPanel: (panel: AsidePanelClaim) => () => void
+  /** The node inside the open panel sheet the aside's children portal into. `null` while closed —
+   * the Drawer unmounts its body, which is what keeps ONE node mounted at a time (law C9). */
+  panelTarget: HTMLElement | null
+  setPanelTarget: (el: HTMLElement | null) => void
 }
 
 const NO_SLOTS: PageBarSlots = {
   target: null,
   setTarget: () => {},
+  bandTarget: null,
+  setBandTarget: () => {},
   inShell: false,
   mobileMoreActions: [],
   kebabClaims: 0,
   claimKebab: () => () => {},
+  panelHost: false,
+  claimPanelHost: () => () => {},
+  panel: null,
+  claimPanel: () => () => {},
+  panelTarget: null,
+  setPanelTarget: () => {},
 }
 
 const PageBarContext = createContext<PageBarSlots>(NO_SLOTS)
@@ -78,13 +120,32 @@ export function PageBarProvider({
   children: ReactNode
 }): ReactNode {
   const [target, setTarget] = useState<HTMLElement | null>(null)
+  const [bandTarget, setBandTarget] = useState<HTMLElement | null>(null)
   const [kebabClaims, setKebabClaims] = useState(0)
+  const [panelHostClaims, setPanelHostClaims] = useState(0)
+  const [panel, setPanel] = useState<AsidePanelClaim | null>(null)
+  const [panelTarget, setPanelTarget] = useState<HTMLElement | null>(null)
 
   const claimKebab = useCallback(() => {
     setKebabClaims((n) => n + 1)
     return () => setKebabClaims((n) => n - 1)
   }, [])
 
+  const claimPanelHost = useCallback(() => {
+    setPanelHostClaims((n) => n + 1)
+    return () => setPanelHostClaims((n) => n - 1)
+  }, [])
+
+  // Identity-checked on release, not an unconditional `null`: two asides never coexist, but a route
+  // change can mount the next one's claim before the previous one's cleanup runs, and clearing
+  // blindly there would drop the live claim.
+  const claimPanel = useCallback((next: AsidePanelClaim) => {
+    setPanel(next)
+    return () => {
+      setPanel((current) => (current === next ? null : current))
+    }
+  }, [])
+
   const mobileMoreActions = globalActions
     .filter((action, index) => (action.mobile ?? (index < 2 ? 'bar' : 'more')) === 'more')
     .map(globalActionAsBarAction)
@@ -92,10 +153,18 @@ export function PageBarProvider({
   const value: PageBarSlots = {
     target,
     setTarget,
+    bandTarget,
+    setBandTarget,
     inShell: true,
     mobileMoreActions,
     kebabClaims,
     claimKebab,
+    panelHost: panelHostClaims > 0,
+    claimPanelHost,
+    panel,
+    claimPanel,
+    panelTarget,
+    setPanelTarget,
   }
 
   return (
@@ -111,75 +180,122 @@ export function PageBarOutlet({ className }: { className?: string }) {
   return <div ref={setTarget} className={className} />
 }
 
+/**
+ * Internal — the BAND between the header and the scrollport that the active page's row 2 portals
+ * into. `BasaltShell` mounts exactly one.
+ *
+ * It is rendered unconditionally and is a zero-height, seam-less box while no `PageBar` claims it:
+ * law C14 says an empty home renders nothing, and an outlet that only existed once something was
+ * inside it could not be a portal target in the first place. The `:empty` seam rule in
+ * `app-main.module.css` is what makes "nothing mounted" and "nothing painted" the same state.
+ */
+export function PageBarBandOutlet({ className }: { className?: string }) {
+  const { setBandTarget } = useContext(PageBarContext)
+  return <div ref={setBandTarget} 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-surface-hairline)`).
-   *
-   * 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
+/**
+ * Internal — the seam `PageAside` projects itself through below `sm` (`docs/ASIDE-SPEC.md` §0).
+ * `host` says whether there is a row 2 to hang the pill off at all; `claim` publishes the aside's
+ * title and glyph; `target` is the node inside the opened sheet its children portal into.
+ */
+export function useAsidePanelSlot(): {
+  host: boolean
+  claim: (panel: AsidePanelClaim) => () => void
+  target: HTMLElement | null
+} {
+  const { panelHost, claimPanel, panelTarget } = useContext(PageBarContext)
+  return { host: panelHost, claim: claimPanel, target: panelTarget }
 }
 
 /**
- * `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.
+ * The boxes `PageBar` paints (`common/props.ts`). `root` is whichever element is the bar's own
+ * outer node for the active mode — the shell-less standalone bar, or row 2's wrapper inside the
+ * shell's band (row 1 portals into the app-shell header and has no wrapper of PageBar's own,
+ * which is what `row1`/`row2` target directly).
+ *
+ * `className`/`classNames.root` land on that same root — the shell-less
+ * `<div data-basalt-page-bar="standalone">`, or row 2's band wrapper
+ * (`data-basalt-page-bar="shell"`) inside a `BasaltShell`. The one thing only the consumer's own
+ * layout knows is bleeding the sticky bar across its container's gutters
+ * (`margin-inline: calc(var(--gutter) * -1); padding-inline: var(--gutter)`) for the shell-less
+ * form. 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.
  */
-const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect
+export type PageBarSlot = 'root' | 'row1' | 'row2'
+
+export type PageBarProps = BasaltProps &
+  SlotStylesProps<PageBarSlot> & {
+    /**
+     * 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
+  }
 
 /**
  * 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.
+ * **A LAYOUT effect, and a CALLBACK REF keyed into the effect.** The layout effect is what puts the
+ * property in place before 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 past its heading.
+ *
+ * The callback ref replaced a plain `RefObject`, and the reason is the row-2 portal. A `RefObject`
+ * is not a dependency, so the effect ran ONCE — on the commit where `active` became true — and read
+ * whatever `ref.current` held at that instant. In a shell that is `null`: the band outlet publishes
+ * its node through state, so row 2 has no target to portal into until the SECOND commit, by which
+ * time `active` has not changed and the effect never re-runs. The observer was then attached to
+ * nothing and `--basalt-page-bar-h` was never published. Node-as-state costs one extra commit
+ * before the first measurement and is the only form that survives a target arriving late.
  *
  * 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)
+function publishBarHeight(node: HTMLElement): void {
+  const { height } = node.getBoundingClientRect()
+  if (height > 0) {
+    document.documentElement.style.setProperty(PAGE_BAR_HEIGHT_VAR, `${height}px`)
+  }
+}
+
+function useMeasuredHeightVar(active: boolean): (el: HTMLDivElement | null) => void {
+  const [node, setNode] = useState<HTMLDivElement | null>(null)
+  const activeRef = useRef(active)
+  activeRef.current = active
+
+  // The FIRST measurement happens here, in the ref callback, which React runs during the COMMIT —
+  // before paint, before layout effects, and one full commit before the state below has propagated.
+  // That is what keeps the property in place for a cold `/page#anchor` load. The state is only how
+  // the observer effect learns the node exists, which it has to, because in a shell the node is a
+  // portal into an outlet that publishes ITS node through state too: `active` alone is not a
+  // dependency that changes when the target finally arrives.
+  const attach = useCallback((el: HTMLDivElement | null) => {
+    setNode(el)
+    if (el !== null && activeRef.current) publishBarHeight(el)
+  }, [])
 
   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`)
-      }
-    }
+    const publish = () => publishBarHeight(node)
     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.
@@ -194,14 +310,9 @@ function useMeasuredHeightVar(active: boolean): RefObject<HTMLDivElement | null>
       observer.disconnect()
       document.documentElement.style.removeProperty(PAGE_BAR_HEIGHT_VAR)
     }
-  }, [active])
-
-  return ref
-}
+  }, [active, node])
 
-/** 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(' ')
+  return attach
 }
 
 export function PageBar({
@@ -213,8 +324,25 @@ export function PageBar({
   filtersEnd,
   tabs,
   className,
+  style,
+  classNames,
 }: PageBarProps): ReactNode {
-  const { target, inShell } = useContext(PageBarContext)
+  const { target, bandTarget, inShell, panel, claimPanelHost, setPanelTarget } =
+    useContext(PageBarContext)
+  // An overlay's open flag, like `FilterPill`'s and `FilterSet`'s — not page state (C3).
+  const [panelOpened, setPanelOpened] = useState(false)
+
+  // The flag belongs to the CLAIM, not to the bar. `FilterSheet`'s `onClose` was the only thing
+  // clearing it, so a route change that released the aside's claim while the sheet was open left
+  // `true` behind — and the NEXT page's `PageAside` mounted its sheet already open, with no user
+  // action anywhere. Keyed on the claim's IDENTITY rather than on `panel === null` because the
+  // release and the next claim can land in one commit, where `panel` is never observed null.
+  const seenPanel = useRef(panel)
+  useEffect(() => {
+    if (seenPanel.current === panel) return
+    seenPanel.current = panel
+    setPanelOpened(false)
+  }, [panel])
 
   const filtersEndActions = filtersEnd ?? []
   const hasRow2 = tabs !== undefined || filters !== undefined || filtersEndActions.length > 0
@@ -225,8 +353,16 @@ export function PageBar({
     actions !== undefined || sync !== undefined || hasLead || filtersEndActions.length > 0
   const measureRef = useMeasuredHeightVar(hasRow2 || (!inShell && hasRow1))
 
+  // Row 2 is what an aside's mobile pill needs; publishing the claim from here is what lets
+  // `PageAside` decide between projecting and staying in flow without either component knowing
+  // about the other's props.
+  useIsomorphicLayoutEffect(() => {
+    if (!inShell || !hasRow2) return
+    return claimPanelHost()
+  }, [inShell, hasRow2, claimPanelHost])
+
   const row1 = hasRow1 ? (
-    <div className={classes.row1}>
+    <div className={cx(classes.row1, classNames?.row1)}>
       {hasLead && (
         <div className={classes.lead}>
           {icon !== undefined && (
@@ -261,34 +397,85 @@ export function PageBar({
     </div>
   ) : null
 
+  // Desktop-shaped, not viewport-aware: `filtersEndActions` alone still renders the `.pills` line
+  // here even though below `sm` those items live in the row-1 kebab and paint nothing in it
+  // (`BarActionRow viewport="desktop"`). `page-bar.module.css`'s mobile `.pills:not(:has(…))` rule
+  // is what actually hides an empty line there — see that rule's comment for why this stays JS-free.
+  const hasPills = filters !== undefined || panel !== null || filtersEndActions.length > 0
+
   const row2 = hasRow2 ? (
-    <div className={classes.row2}>
-      {tabs !== undefined && <CtlSlot>{tabs}</CtlSlot>}
-      {filters !== undefined && (
-        <div className={classes.filters}>
-          <CtlSlot>{filters}</CtlSlot>
+    <div className={cx(classes.row2, classNames?.row2)}>
+      {tabs !== undefined && (
+        <div className={classes.tabs} data-basalt-page-bar-line="tabs">
+          <CtlSlot>{tabs}</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>
+      {hasPills && (
+        <div className={classes.pills} data-basalt-page-bar-line="pills">
+          {filters !== undefined && (
+            <div className={classes.filters}>
+              <CtlSlot>{filters}</CtlSlot>
+            </div>
+          )}
+          {panel !== null && (
+            <FilterPill
+              // One word, no count: unlike `Filters (n)` an aside has no census to count (its
+              // children are not a `FilterSet`), and a number nobody can derive is worse than none.
+              label="Panel"
+              ariaLabel={panel.title}
+              icon={panel.icon}
+              className={classes.panelPill}
+              hideGlyph
+              onClick={() => {
+                setPanelOpened(true)
+              }}
+            />
+          )}
+          {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 (`docs/CONTROLS-SPEC.md` §2.1: mobile row 2 is two lines: tabs, then the
+                    first pill + `Filters (n)` + the aside's `Panel` pill — `docs/CONTROLS-SPEC.md`
+                    §2.1 still describes the pre-aside one-line form). */}
+                <BarActionRow secondary={filtersEndActions} host="slot" viewport="desktop" />
+              </CtlSlot>
+            </div>
+          )}
         </div>
       )}
     </div>
   ) : null
 
+  // The aside's mobile sheet. `onResetAll` is deliberately absent — the children mount under a
+  // `null` registry, so there is nothing registered to reset. The body is an OUTLET, not the
+  // children: `PageAside` portals into it, which is what keeps the aside's node singular (C9) and
+  // keeps a `ReactNode` out of context state (see `AsidePanelClaim`). The outlet carries the
+  // desktop panel's own `.body` class — same flex rhythm, and the same `> * + *` flush-hairline
+  // rule between groups (`page-aside.module.css`) — so the aside's groups separate identically in
+  // both projections instead of only in the portalled panel.
+  const panelSheet =
+    panel === null ? null : (
+      <FilterSheet
+        opened={panelOpened}
+        title={panel.title}
+        onClose={() => {
+          setPanelOpened(false)
+        }}
+      >
+        <div ref={setPanelTarget} className={asideClasses.body} />
+      </FilterSheet>
+    )
+
   // 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)}
+        className={cx(classes.bar, classNames?.root, className)}
         data-basalt-page-bar="standalone"
+        {...(style !== undefined && { style })}
       >
         {row1}
         {row2}
@@ -296,20 +483,33 @@ export function PageBar({
     )
   }
 
-  // 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.
+  // In a shell BOTH rows are portals: row 1 into the header, row 2 into the shell-owned band
+  // between the header and the scrollport. Neither target exists on the first commit — the outlets'
+  // refs set them — so a `null` target renders nothing for exactly one frame.
+  //
+  // Row 2 portals rather than rendering in flow because WHERE the band paints must not depend on
+  // where the consumer wrote `<PageBar>`. In flow it was `position: sticky` inside whatever wrapper
+  // held it, so a bar nested one `Stack` deep — which is every real page — had its sticky offset
+  // clamped to that wrapper's top edge and sat one `--app-shell-padding` below the header seam,
+  // while a bar written as Main's direct child sat flush. Same markup, two geometries. Out here the
+  // band is a sibling of the scrollport, so it is neither sticky nor nested and there is one answer.
   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>
-      )}
+      {row2 !== null &&
+        bandTarget !== null &&
+        createPortal(
+          <div
+            ref={measureRef}
+            className={cx(classes.row2Band, classNames?.root, className)}
+            data-basalt-page-bar="shell"
+            {...(style !== undefined && { style })}
+          >
+            {row2}
+          </div>,
+          bandTarget,
+        )}
+      {panelSheet}
     </>
   )
 }

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

@@ -0,0 +1,33 @@
+/*
+ * `PageTitle` — the shell-less page-title primitive (C5 consolidation, `docs/CONTROLS-SPEC.md`
+ * law C8's third named spot alongside the breadcrumb and `PageBar.title`). Same treatment as
+ * `page-bar.module.css`'s `.title` (head font, 88% stretch, weight 550) — a page is named once,
+ * and every named spot reads identically regardless of which one a given surface uses.
+ */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.titleRow {
+  display: flex;
+  align-items: center;
+  gap: var(--vx-space-nav-icon-gap, 8px);
+}
+
+.title {
+  margin: 0;
+  font-family: var(--basalt-font-head);
+  font-size: var(--vx-text-xl);
+  font-weight: 550;
+  font-stretch: 88%;
+  color: var(--vx-ink);
+}
+
+.subtitle {
+  margin: 0;
+  font-size: var(--vx-text-sm);
+  color: var(--vx-faint);
+}

package/src/shell/page-title.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 titleRow: string
+  readonly title: string
+  readonly subtitle: string
+}
+export default classes

package/src/shell/page-title.tsx

@@ -0,0 +1,57 @@
+/**
+ * `PageTitle` — the shell-less page-title primitive (C5 consolidation). Law C8
+ * (`docs/CONTROLS-SPEC.md` §2.2) names two sanctioned spots for a page's ONE name: the breadcrumb
+ * inside `BasaltShell`, or `PageBar.title` in a shell-less app — but neither fits a surface that
+ * has no `PageBar` at all, which is exactly what `BasaltErrorBoundary`'s default fallback and an
+ * auth gate ARE. Both were the two named `in-body-page-title` waivers this primitive closes
+ * (argo's `lib/error-boundary.tsx:36`, `lib/auth-gate.tsx:30` — each a bare `<Title order={2}>` +
+ * a muted subtitle line, hand-copied).
+ *
+ * A plain `<h1>` + CSS module, NOT Mantine's `<Title>` component — same reason `page-bar.tsx`'s
+ * own `title` row does (`page-bar.module.css`'s `.title`): `basalt/in-body-page-title` and its
+ * text-lane twin both match the JSX tag `<Title`, so a THIRD sanctioned spot built out of that
+ * same tag would need a waiver on itself. A raw, styled `<h1>` needs none — it IS the remedy, not
+ * a case of it.
+ *
+ * @example
+ * import { PageTitle } from 'basalt-ui'
+ *
+ * <PageTitle title="Something went wrong" subtitle="The page hit an unexpected error." />
+ */
+import { cx } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
+import type { ReactNode } from 'react'
+import classes from './page-title.module.css'
+
+export type PageTitleSlot = 'root' | 'title' | 'subtitle'
+
+export type PageTitleProps = BasaltProps &
+  SlotStylesProps<PageTitleSlot> & {
+    /** The page's one name. */
+    title: ReactNode
+    /** Optional muted line below the title. */
+    subtitle?: ReactNode
+    /** Optional leading icon, rendered before the title. Decorative — hidden from assistive tech,
+     * same convention as `WidgetHeader.icon`. */
+    icon?: ReactNode
+  }
+
+export function PageTitle(props: PageTitleProps): ReactNode {
+  assertRequiredProps('PageTitle', props, ['title'])
+  const { title, subtitle, icon, className, classNames, style } = props
+  return (
+    <div
+      className={cx(classes.root, classNames?.root, className)}
+      {...(style !== undefined && { style })}
+    >
+      <div className={cx(classes.titleRow, classNames?.title)}>
+        {icon !== undefined && <span aria-hidden="true">{icon}</span>}
+        <h1 className={classes.title}>{title}</h1>
+      </div>
+      {subtitle !== undefined && (
+        <p className={cx(classes.subtitle, classNames?.subtitle)}>{subtitle}</p>
+      )}
+    </div>
+  )
+}

package/src/shell/sidebar-block-model.ts

@@ -9,7 +9,7 @@
  * A default re-derived per call site is how the count and the renderer drift apart (see
  * `accountRowCount`'s doc for the same failure with account rows).
  */
-import type { SidebarBlock } from '../nav/types'
+import type { SidebarBlock } from './nav-types'
 
 /** Envelope version for a persisted fold flag. Bump only if the value stops being a boolean. */
 export const FOLD_VERSION = 1