basalt-ui 1.27.0 → 1.28.0

package/src/shell/index.tsx

@@ -20,11 +20,16 @@
 import { AppShell, Box } from '@mantine/core'
 import { Fragment, useMemo } from 'react'
 import type { MouseEvent, ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import { AppSidebar } from './app-sidebar'
+import { AppBrand } from './app-brand'
 import { MobileNav, accountRowCount } from './app-mobile-nav'
 import { blockRowCount, projectMobileNav } from './mobile-nav-model'
 import { AppBreadcrumbs } from './app-breadcrumbs'
-import { PageBarOutlet, PageBarProvider, usePageKebabClaimed } from './page-bar'
+import { PageBarBandOutlet, PageBarOutlet, PageBarProvider, usePageKebabClaimed } from './page-bar'
+import { AsideOutlet, AsideProvider, useAsideRegion } from './page-aside'
 import { OverflowMenu, globalActionAsBarAction, globalActionMobile } from '../controls/actions'
 import type { GlobalAction } from '../controls/actions'
 import type { AccountMenuItem, BasaltAccountProps } from './account-types'
@@ -38,13 +43,16 @@ import type {
 } from '../nav/types'
 import { CtlSlot, useBasaltSpacing } from '../theme'
 import { createPersistedState } from '../state'
+import brandClasses from './app-brand.module.css'
 import headerClasses from './app-header.module.css'
-import mobileNavClasses from './app-mobile-nav.module.css'
+import mainClasses from './app-main.module.css'
+import asideClasses from './page-aside.module.css'
 
 export { AppSidebar, type AppSidebarProps } from './app-sidebar'
-export { NavCountBadge } from './nav-count-badge'
+export { NavCountBadge, type NavCountBadgeProps } from './nav-count-badge'
 export {
   SidebarSearch,
+  type SidebarSearchProps,
   type SidebarSearchConfig,
   type SidebarSearchActions,
 } from './sidebar-search'
@@ -67,8 +75,9 @@ export {
   MOBILE_MENU_MAX_DEFAULT,
   MOBILE_MORE_KEY,
 } from './mobile-nav-model'
-export { AppBreadcrumbs } from './app-breadcrumbs'
-export { PageBar, type PageBarProps } from './page-bar'
+export { AppBreadcrumbs, type AppBreadcrumbsProps } from './app-breadcrumbs'
+export { PageBar, type PageBarProps, type PageBarSlot } from './page-bar'
+export { PageAside, type PageAsideProps, type PageAsideSlot } from './page-aside'
 
 /**
  * The shared nav vocabulary lives in `src/nav/types.ts` so the headless router bridge can `import
@@ -115,7 +124,7 @@ export type SettingsMenuItem = {
   onClick?: (e: MouseEvent) => void
 }
 
-export type BasaltShellProps = {
+export type BasaltShellProps = BasaltProps & {
   /**
    * Brand identity for the sidebar header. Supplying `menu` turns the brand row into a `Name ▾`
    * workspace switcher — the rows are `AccountMenuItem`s, the shape the account menu already uses.
@@ -296,7 +305,28 @@ function collapseStore(key: string): () => readonly [boolean, (next: boolean) =>
   return store
 }
 
-export function BasaltShell({
+// The shared inset for the shell padding and the header's inline padding, so the breadcrumb's
+// left edge and the global actions' right edge land on the card column's edges.
+const SHELL_INSET = 'sm' as const
+
+/**
+ * The shell's two page-level regions are providers, and both wrap the frame rather than living
+ * inside it: `PageBarProvider` owns the header portal and the single-kebab claim, `AsideProvider`
+ * owns the aside portal, the region CLAIM and the claiming page's fold state — which `ShellFrame`
+ * has to READ to size `AppShell.Aside`, so it cannot be the component that provides it.
+ */
+export function BasaltShell(props: BasaltShellProps) {
+  assertRequiredProps('BasaltShell', props, ['brand', 'sections'])
+  return (
+    <PageBarProvider globalActions={props.globalActions ?? []}>
+      <AsideProvider>
+        <ShellFrame {...props} />
+      </AsideProvider>
+    </PageBarProvider>
+  )
+}
+
+function ShellFrame({
   brand,
   sections,
   mobileNav,
@@ -310,12 +340,15 @@ export function BasaltShell({
   account,
   search,
   children,
+  className,
+  style,
 }: BasaltShellProps) {
   // The active density level's resolved spacing — the AppShell dimensions below must track it
   // (see `SPACE_STEP_BASE`'s "shell/index.tsx" group doc in `tokens/palette.ts`): their contents
   // (controls, the search trigger/avatar, nav labels) already track density, so a fixed literal
   // container squeezes progressively worse as density rises.
   const { step } = useBasaltSpacing()
+  const aside = useAsideRegion()
   const [storedCollapsed, setStoredCollapsed] = collapseStore(storageKey)()
   // Controlled/uncontrolled seam (item 19): an explicit `collapsed` prop overrides the internal
   // localStorage-persisted state entirely — the consumer becomes the source of truth.
@@ -344,68 +377,126 @@ export function BasaltShell({
   )
 
   return (
-    <PageBarProvider globalActions={globalActions ?? []}>
-      <AppShell
-        h="100dvh"
-        layout="alt"
-        header={{
-          // ONE height at every width (law C14): nothing reserves a second mobile row any more.
-          height: step.appShellHeaderHeight,
-        }}
-        navbar={{
-          width: {
-            base: step.appShellNavbarWidth,
-            sm: collapsed ? step.appShellNavbarRailWidth : step.appShellNavbarWidth,
-          },
-          breakpoint: 'sm',
-          // No mobile sidebar drawer, ever — the bottom bar is the entire mobile nav.
-          collapsed: { mobile: true },
-        }}
-        // A plain number, NOT a `calc(... + env(safe-area-inset-bottom))` string: Mantine's own
-        // `.footer` rule already adds the inset to both the height and the padding (§2.7).
-        footer={{ height: { base: step.mobileNavBarHeight, sm: 0 } }}
-        padding="sm"
-      >
-        <AppShell.Header px="md" withBorder={false}>
-          <div className={headerClasses.bar}>
-            <div className={headerClasses.lead}>
-              <AppBreadcrumbs {...activeCrumb} />
-            </div>
-            <PageBarOutlet className={headerClasses.pageBar} />
-            <HeaderGlobalActions actions={globalActions ?? []} />
+    <AppShell
+      h="100dvh"
+      // Mantine's DEFAULT layout, not `alt`: the header spans the full viewport width on top and
+      // the navbar/aside start underneath it at `top: var(--app-shell-header-offset)`. `alt` did
+      // the opposite — a full-height navbar with the header inset beside it — which put the top
+      // bar to the RIGHT of the sidebar instead of above it.
+      header={{
+        // ONE height at every width (law C14): nothing reserves a second mobile row any more.
+        height: step.appShellHeaderHeight,
+      }}
+      navbar={{
+        width: {
+          base: step.appShellNavbarWidth,
+          sm: collapsed ? step.appShellNavbarRailWidth : step.appShellNavbarWidth,
+        },
+        breakpoint: 'sm',
+        // No mobile sidebar drawer, ever — the bottom bar is the entire mobile nav.
+        collapsed: { mobile: true },
+      }}
+      // The aside region (`docs/ASIDE-SPEC.md` §0). It is DECLARED here on every route and costs
+      // nothing until a page mounts a `PageAside` to claim it: unclaimed it is zero-wide and
+      // `collapsed.desktop`, so `--app-shell-aside-offset` stays 0 and the main column is
+      // full-width (law C14 — an empty home renders nothing). There is no `BasaltShellProps`
+      // prop for it on purpose; the ROUTE decides, the same way it decides its page bar.
+      aside={{
+        width: aside.claimed
+          ? aside.folded
+            ? step.appShellAsideRailWidth
+            : step.appShellAsideWidth
+          : 0,
+        breakpoint: 'sm',
+        // Below `sm` there is no region at all — `PageAside` renders its content in the page
+        // flow instead, one node, no responsive twin (law C9).
+        collapsed: { desktop: !aside.claimed, mobile: true },
+      }}
+      // A plain number, NOT a `calc(... + env(safe-area-inset-bottom))` string: Mantine's own
+      // `.footer` rule already adds the inset to both the height and the padding (§2.7).
+      footer={{ height: { base: step.mobileNavBarHeight, sm: 0 } }}
+      padding={SHELL_INSET}
+      // `mainClasses.shell` is not decoration — see its rule for why the root has to establish a
+      // block formatting context now that Main is offset with margins.
+      className={cx(mainClasses.shell, className)}
+      {...(style !== undefined && { style })}
+    >
+      {/* Region seams (docs/DESIGN-SPEC.md §5, §8 #12): Mantine's `[data-with-border]` painted in
+       * `--vx-divider` by the theme's `AppShell.extend({ vars })`. No shell module draws a region
+       * edge; never opt a section back out of its border here. */}
+      <AppShell.Header px={SHELL_INSET}>
+        <div className={headerClasses.bar}>
+          {/* The header's LEADING ZONE — exactly `--app-shell-navbar-offset` wide, so its trailing
+           * edge lands on the sidebar|main seam and the breadcrumb after it starts on Main's own
+           * content edge. The brand lives here rather than in the sidebar because with a full-width
+           * header a sidebar brand row painted as a SECOND 48px band under the header seam; see
+           * `app-brand.tsx`. `data-collapsed` is the rail's one signal — the zone narrows with the
+           * navbar and shows the toggle alone, exactly as the sidebar's own row did. */}
+          <div className={brandClasses.zone} data-collapsed={collapsed || undefined}>
+            <AppBrand brand={brand} collapsed={collapsed} onToggleCollapse={toggleCollapse} />
           </div>
-        </AppShell.Header>
+          <div className={headerClasses.lead}>
+            <AppBreadcrumbs {...activeCrumb} />
+          </div>
+          <PageBarOutlet className={headerClasses.pageBar} />
+          <HeaderGlobalActions actions={globalActions ?? []} />
+        </div>
+      </AppShell.Header>
 
-        <AppShell.Navbar p={0} withBorder={false}>
-          <AppSidebar
-            brand={brand}
-            sections={sections}
-            collapsed={collapsed}
-            onToggleCollapse={toggleCollapse}
-            {...(sidebarBlocks !== undefined && { blocks: sidebarBlocks })}
-            {...(settingsMenuItems !== undefined && { settingsMenuItems })}
-            {...(settingsMenu !== undefined && { settingsMenu })}
-            {...(account !== undefined && { account })}
-            {...(search !== undefined && { search })}
-          />
-        </AppShell.Navbar>
+      <AppShell.Navbar p={0}>
+        <AppSidebar
+          brand={brand}
+          sections={sections}
+          collapsed={collapsed}
+          onToggleCollapse={toggleCollapse}
+          {...(sidebarBlocks !== undefined && { blocks: sidebarBlocks })}
+          {...(settingsMenuItems !== undefined && { settingsMenuItems })}
+          {...(settingsMenu !== undefined && { settingsMenu })}
+          {...(account !== undefined && { account })}
+          {...(search !== undefined && { search })}
+        />
+      </AppShell.Navbar>
 
-        {/* `mainSafeArea` closes the one real safe-area gap: Mantine sets
-         * `--app-shell-footer-offset` to the RAW footer height, so Main's own padding-bottom is
-         * short by exactly `env(safe-area-inset-bottom)` (§2.7). */}
-        <AppShell.Main className={mobileNavClasses.mainSafeArea}>{children}</AppShell.Main>
+      {/* The PAGE-BAR BAND — a shell-owned outlet between the header and the scrollport that
+       * `PageBar` row 2 portals into, the same mechanism row 1 uses one region up. It is written
+       * BEFORE Main because the two are the AppShell root's only in-flow children (every other
+       * region is `position: fixed`), so DOM order is column order: band, then whatever height is
+       * left. Empty, it is a zero-height, seam-less box (law C14). */}
+      <PageBarBandOutlet className={mainClasses.band} />
 
-        <AppShell.Footer hiddenFrom="sm" p={0} withBorder={false}>
-          <MobileNav
-            model={model}
-            config={mobileNav}
-            {...(account !== undefined && { account })}
-            {...(settingsMenuItems !== undefined && { settingsMenuItems })}
-            {...(sidebarBlocks !== undefined && { blocks: sidebarBlocks })}
-          />
-        </AppShell.Footer>
-      </AppShell>
-    </PageBarProvider>
+      {/* MAIN IS THE SCROLLPORT (`app-main.module.css`), not the document: the scrollbar belongs
+       * on the content's own right edge, inside the aside, and every sticky offset in the package
+       * resolves against this box rather than the window. `data-basalt-scrollport` is the public
+       * handle — `scrollParentOf` (`../common`) and `MobileNav`'s scroll-to-top both resolve it —
+       * and `data-scroll-restoration-id` is the attribute TanStack Router's scroll restoration
+       * reads (`@tanstack/router-core`'s `scrollRestorationIdAttribute`), so a router-driven app
+       * restores THIS element's scrollTop instead of the window's, which no longer moves. */}
+      <AppShell.Main
+        className={mainClasses.main}
+        data-basalt-scrollport
+        data-scroll-restoration-id="basalt-main"
+      >
+        {children}
+      </AppShell.Main>
+
+      {/* The outlet is bare; the region's leading seam is the AppShell's own. An unclaimed region
+       * is zero-wide but NOT display-none — Mantine's collapsed aside keeps its border-box, so a
+       * seam would still paint as a 1px ghost at the viewport's right edge (measured on
+       * `/dashboard`). The border follows the claim, not the section (C14). */}
+      <AppShell.Aside p={0} withBorder={aside.claimed}>
+        <AsideOutlet className={asideClasses.outlet} />
+      </AppShell.Aside>
+
+      <AppShell.Footer hiddenFrom="sm" p={0}>
+        <MobileNav
+          model={model}
+          config={mobileNav}
+          {...(account !== undefined && { account })}
+          {...(settingsMenuItems !== undefined && { settingsMenuItems })}
+          {...(sidebarBlocks !== undefined && { blocks: sidebarBlocks })}
+        />
+      </AppShell.Footer>
+    </AppShell>
   )
 }
 

package/src/shell/isomorphic-layout-effect.ts

@@ -0,0 +1,14 @@
+/**
+ * Internal — `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 across every render of every caller.
+ *
+ * One module rather than one `const` per file: `page-bar.tsx` and `page-aside.tsx` declared the
+ * same line with the same doc, and the second copy's doc already said "see `page-bar.tsx`'s copy".
+ * Not exported from any barrel — this is a shell-internal utility, not a published hook.
+ */
+import { useEffect, useLayoutEffect } from 'react'
+
+export const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect

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

@@ -136,9 +136,10 @@ function collectKeys(items: readonly SidebarItem[], out: Set<string>): void {
 
 /**
  * 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).
+ * fallback read. Nesting is NOT lost: this is the lookup/selection view only (deciding which
+ * destinations are eligible for a bar slot), while the overflow and group rendering below keep the
+ * tree — `pruneOverflowTree` even preserves it across a covered parent, so a nested destination
+ * renders indented under its parent (or its parent's group anchor) rather than as a flat sibling.
  */
 function flattenItems(items: readonly SidebarItem[], out: SidebarItem[]): void {
   for (const item of items) {
@@ -147,6 +148,18 @@ function flattenItems(items: readonly SidebarItem[], out: SidebarItem[]): void {
   }
 }
 
+/**
+ * Attaches `children` to a shallow copy of `item` — or omits `children` from it entirely when
+ * there are none, rather than leaving a stale empty array — and pushes the result onto `out`.
+ * Shared tail of `pruneTree`/`pruneOverflowTree`'s keep branches.
+ */
+function pushWithChildren(out: SidebarItem[], item: SidebarItem, children: SidebarItem[]): void {
+  const next: SidebarItem = { ...item }
+  if (children.length > 0) next.children = children
+  else delete next.children
+  out.push(next)
+}
+
 /**
  * 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
@@ -163,10 +176,51 @@ function pruneTree(
       out.push(...children)
       continue
     }
-    const next: SidebarItem = { ...item }
-    if (children.length > 0) next.children = children
-    else delete next.children
-    out.push(next)
+    pushWithChildren(out, item, children)
+  }
+  return out
+}
+
+/**
+ * `pruneTree`'s overflow-only sibling — the More surface has TWO independent reasons a destination
+ * drops out, and they no longer resolve the same way. `hidden` (a consumer opted the destination
+ * fully out via rule 1) still hoists exactly like `pruneTree`: nothing should hint a hidden node
+ * exists, so its visible children rise to fill its place. `covered` (the destination already has
+ * its OWN slot elsewhere in the bar — a tab, or another section's slot) used to hoist identically,
+ * which is the bug this function fixes: hoisting discards the tree edge between a covered PARENT
+ * and its still-overflowing children, so `Sessions`/`Traffic`/`Revenue` rendered as flat siblings
+ * with no indication they belong under `Dashboard` at all — depth information the renderer has no
+ * way to reconstruct once it is gone. A covered parent with surviving children is kept instead, as
+ * the GROUP ANCHOR those children nest under (same row shape and same destination it already is on
+ * the bar — tapping it in the sheet does exactly what tapping its tab does); a covered LEAF (no
+ * surviving children) still drops entirely, since rule 7's original reasoning — a destination with
+ * nowhere new to add is not worth a second, redundant row — still holds for that case unchanged.
+ */
+function pruneOverflowTree(
+  items: readonly SidebarItem[],
+  isHidden: (item: SidebarItem) => boolean,
+  isCovered: (item: SidebarItem) => boolean,
+): SidebarItem[] {
+  const out: SidebarItem[] = []
+  for (const item of items) {
+    const children = pruneOverflowTree(item.children ?? [], isHidden, isCovered)
+    if (isHidden(item)) {
+      out.push(...children)
+      continue
+    }
+    if (isCovered(item)) {
+      // A covered leaf contributes nothing new — drop it, exactly like `pruneTree` would.
+      if (children.length === 0) continue
+      // Rule 12 (`hasActiveDestination`'s doc): this destination is covered, so its REAL slot is
+      // what lights when it is the active route — its own tab, or another section's slot. The
+      // anchor copied here is not that slot, so its own `active` is forced false; only a
+      // surviving CHILD's activeness may roll up and light the surface this anchor sits inside.
+      // Without this a route at the covered parent lit BOTH its own tab and the anchor's
+      // enclosing More/section surface — two `aria-current="page"` tabs for one location.
+      out.push({ ...item, active: false, children })
+      continue
+    }
+    pushWithChildren(out, item, children)
   }
   return out
 }
@@ -335,7 +389,8 @@ function buildCandidates(
   return fallback
 }
 
-/** Rule 7 — the leftovers, grouped by source section, tree intact. */
+/** Rule 7 — the leftovers, grouped by source section, tree intact — including a covered
+ *  parent kept on as its surviving children's group anchor (`pruneOverflowTree`'s doc). */
 function buildOverflow(
   sections: readonly SidebarSection[],
   covered: Set<string>,
@@ -344,9 +399,10 @@ function buildOverflow(
   for (const section of sections) {
     const hidden = isSectionHidden(section)
     if (hidden) continue
-    const items = pruneTree(
+    const items = pruneOverflowTree(
       section.items,
-      (item) => placementOf(item, hidden) !== 'hidden' && !covered.has(item.key),
+      (item) => placementOf(item, hidden) === 'hidden',
+      (item) => covered.has(item.key),
     )
     if (items.length === 0) continue
     groups.push({ key: section.label, label: section.label, items })

package/src/shell/nav-count-badge.tsx

@@ -6,6 +6,9 @@
  */
 import { Badge } from '@mantine/core'
 import { VX } from '../tokens'
+import type { BasaltProps } from '../common/props'
+
+export type NavCountBadgeProps = BasaltProps & { count: number }
 
 /**
  * Sidebar nav count badge (docs/DESIGN-SPEC.md §5): mono micro (11px), ink-8% bg, radius 5, height 16,
@@ -14,11 +17,13 @@ import { VX } from '../tokens'
  * combinations land on the ink-tint idiom. Returns `null` for a zero/empty count so the badge slot
  * stays clean ("ink earns its color", DESIGN.md).
  */
-export function NavCountBadge({ count }: { count: number }) {
+export function NavCountBadge({ count, className, style }: NavCountBadgeProps) {
   if (!count) return null
   return (
     <Badge
       size="sm"
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
       styles={{
         root: {
           backgroundColor: 'color-mix(in srgb, var(--vx-ink) 8%, transparent)',

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

@@ -0,0 +1,174 @@
+/*
+ * `PageAside` chrome (`docs/ASIDE-SPEC.md` §0, wave 1).
+ *
+ * Two forms, one class set, told apart by `data-basalt-page-aside`: `"shell"` is the portalled
+ * panel that fills `AppShell.Aside` and owns the region's paint, `"standalone"` is the in-flow node
+ * a phone (or a shell-less app) renders where the page wrote it — plain flow content, no surface of
+ * its own, exactly like the block that used to live in the page's second column.
+ */
+
+/* The `AppShell.Aside` inner node the panel portals into — a bare box, so an UNCLAIMED region
+ * paints nothing at all (law C14). Every pixel of chrome belongs to `.panel` below. */
+.outlet {
+  display: flex;
+  height: 100%;
+}
+
+.panel {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  gap: var(--vx-space-stack-md, 0.75rem);
+}
+
+/*
+ * The portalled form. Paints only the page background (the same surface the sidebar and the sticky
+ * page bar sit on — neither declares one, both inherit the body). The leading edge is the
+ * `AppShell.Aside` region seam (docs/DESIGN-SPEC.md §5) — same token, same pixel, now produced by
+ * the same rule as the other three region edges, so two 1px lines can never sit side by side.
+ */
+.panel[data-basalt-page-aside='shell'] {
+  flex: 1;
+  height: 100%;
+  gap: 0;
+  background-color: var(--vx-surface-bg);
+}
+
+/*
+ * Header row — the title (`.title` below, shared by both forms), plus the fold toggle in the
+ * portalled form only, at `sectionHeaderHeight` (standalone) / the header band (shell, below).
+ * Same horizontal inset every sidebar region aligns to.
+ */
+.header {
+  display: flex;
+  flex: none;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--vx-space-control-gap);
+  min-height: var(--vx-space-section-header-height, 2.25rem);
+}
+
+/* The portalled form's band matches the SHELL-OWNED page-bar band exactly, whenever one is
+ * present (`--basalt-page-bar-h`, `docs/DESIGN-SPEC.md` §5) — not a fixed 48px. `PageBar`
+ * publishes that var on `documentElement` from a ResizeObserver on the band's own content
+ * (`shell/page-bar.tsx`), so it inherits down to every descendant, this header included, with no
+ * extra wiring. Two seams, one line: MEASURED on `/cbbi` 1440x900, the band's outer edge (its own
+ * `border-bottom`, `app-main.module.css` `.band:not(:empty)`) used to sit at y87 while this header
+ * (unconditionally `var(--app-shell-header-height)`, 48px) sat at y96 — 9px apart.
+ *
+ * The `+ 1px` is not decorative. `--basalt-page-bar-h` measures the band's CONTENT box only (the
+ * portalled row-2 wrapper `page-bar.tsx` attaches its ResizeObserver to); the band's own
+ * `border-bottom` is drawn OUTSIDE that box, on a plain `height: auto` element, so it ADDS a pixel
+ * the published var never counted. This header is the opposite shape — an explicit `min-height`
+ * under the page's global `box-sizing: border-box` reset — so its OWN `border-bottom` is absorbed
+ * INSIDE whatever height is declared instead of adding on top. Feeding the raw var straight in
+ * therefore undershoots by exactly the band's border: `calc(38px + 1px)` = 39px, matching the
+ * band's true painted height, while the no-band fallback nets out unchanged (`calc((48px - 1px) +
+ * 1px)` = 48px) because the same `+ 1px` also wraps that branch. Without a `PageBar` there is no
+ * band seam to align to, so the header keeps closing the ordinary 48px top belt
+ * (`docs/DESIGN-SPEC.md` §5) the header and sidebar-brand bands also close.
+ */
+.panel[data-basalt-page-aside='shell'] .header {
+  padding-inline: var(--vx-space-row-inset-x);
+  min-height: calc(
+    var(
+        --basalt-page-bar-h,
+        calc(var(--app-shell-header-height, var(--vx-space-section-header-height, 2.25rem)) - 1px)
+      ) +
+      1px
+  );
+  border-bottom: 1px solid var(--vx-divider);
+}
+
+/* A real title (docs/DESIGN-SPEC.md §5): mirrors `widget-header.module.css` `.heading` and the
+ * breadcrumb's current-page treatment — the three 48px bands each carry one 550-weight head-font
+ * name. */
+.title {
+  font-family: var(--basalt-font-head);
+  font-size: var(--vx-text-md);
+  font-weight: 550;
+  font-stretch: 88%;
+  color: var(--vx-ink);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* The body scrolls, the header does not — `min-height: 0` is what lets a flex child shrink below
+ * its content and actually become a scroll box. In flow (standalone) it is plain content: no
+ * scroll region, no inset, so it sits in the page's own rhythm. */
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-md, 0.75rem);
+  min-width: 0;
+}
+
+.panel[data-basalt-page-aside='shell'] .body {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding-inline: var(--vx-space-row-inset-x);
+  padding-block: var(--vx-space-stack-md, 0.75rem);
+}
+
+/*
+ * FLUSH chrome (`docs/ASIDE-SPEC.md` §3, wave 2). An aside's groups separate with a hairline, not
+ * with cards — Lightroom, not a dashboard: at ~300px a stack of bordered, inset panels spends most
+ * of the column on its own edges, and the reader's job here is comparing rows across groups rather
+ * than reading one card at a time.
+ *
+ * It is drawn HERE and not in `Section`, on the `.body`'s own children, for two reasons. The
+ * component does not know where it is mounted (there is no aside context and no prop that would
+ * tell it), and a body child is not necessarily a `Section` at all — a bare `PanelRow`, a chart, a
+ * paragraph all take the same rhythm. `> * + *`, so the first child never draws a rule under the
+ * header that already bounds it.
+ */
+.body > * + * {
+  border-top: 1px solid var(--vx-divider);
+  padding-top: var(--vx-space-stack-md, 0.75rem);
+}
+
+/* The folded rail: one button, top-aligned, centred in the rail's own width. */
+.rail {
+  display: flex;
+  flex: 1;
+  justify-content: center;
+  align-items: flex-start;
+  padding-top: var(--vx-space-stack-xs, 0.25rem);
+}
+
+/*
+ * The fold toggle — a plain control sized to the `ctl` tier by hand, verbatim from `Section`'s
+ * chevron (`section/section.module.css`), including the `calc(<rem> * var(--mantine-scale))`
+ * reconstruction that keeps it tracking a scaled Button beside it. No `< sm` hit-area overlay
+ * (unlike that chevron): the toggle exists only in the portalled form, which is `sm` and up.
+ */
+/* Deliberately NOT shared with `section/section.module.css`'s `.chevron`, which it echoes: the two
+ * live in different CSS modules and this repo keeps one module per component, so sharing would need
+ * a third module + `composes` across that boundary. They also differ where it counts — `.fold` is
+ * `--vx-faint` and draws no rotation or C15 touch overlay, because the aside's fold is a desktop-
+ * only control. */
+.fold {
+  position: relative;
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  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-faint);
+  cursor: pointer;
+}
+
+.fold:hover,
+.fold:focus-visible {
+  color: var(--vx-ink);
+  background: var(--vx-surface-subtle);
+}

package/src/shell/page-aside.module.css.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 outlet: string
+  readonly panel: string
+  readonly header: string
+  readonly title: string
+  readonly body: string
+  readonly rail: string
+  readonly fold: string
+}
+export default classes