basalt-ui 1.27.0 → 1.29.0

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

@@ -22,7 +22,7 @@ import type {
   SidebarBlock,
   SidebarItem,
   SidebarSection,
-} from '../nav/types'
+} from './nav-types'
 import { sidebarBlockMobile } from './sidebar-block-model'
 
 /** Hard cap on bar slots, INCLUDING More. Five 72px slots is the widest a 360px viewport holds. */
@@ -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/{nav/types.ts → shell/nav-types.ts}

@@ -73,11 +73,14 @@ export type SidebarSection = {
 }
 
 /**
- * Status tone on a sidebar-block item — the same three-member vocabulary as `StatCardTone`, whose
- * members are `VX.status` keys by construction. Declared here rather than imported from
- * `../dashboard/stat-card`: this module is the one `./router-tanstack` reads, and even a
- * type-only edge into the Mantine layer would make `nav/types.d.ts` unresolvable without
- * `@mantine/core` installed.
+ * Status tone on a sidebar-block item — byte-identical to the common `Tone` vocabulary
+ * (`common/props.ts`, audit A13) and to `StatCardTone`, whose members are `VX.status` keys by
+ * construction. Declared here rather than aliased to `common`'s `Tone`: this module is the one
+ * `./router-tanstack` reads, and `common/props.ts` re-exports `Tier` (type-only) from
+ * `../widget-header/widget-header`, a Mantine-coupled file — importing anything from `common/props`
+ * here would pull that whole module's declaration graph into `nav/types.d.ts`, making it
+ * unresolvable without `@mantine/core` installed. Kept in step with `Tone` by convention, not by
+ * import.
  */
 export type SidebarBlockTone = 'good' | 'warn' | 'bad'
 
@@ -192,6 +195,12 @@ export type MobileNavConfig = {
   menuMax?: number
   /** @default 'More' */
   moreLabel?: string
-  /** Scroll container for active-slot re-tap. @default document.scrollingElement */
+  /**
+   * Scroll container for active-slot re-tap. Only needed when the page scrolls somewhere basalt
+   * cannot see — inside a shell the default already resolves `AppShell.Main`
+   * (`[data-basalt-scrollport]`), and outside one it falls back to the document.
+   *
+   * @default the `[data-basalt-scrollport]` element, else `document.scrollingElement`
+   */
   getScrollElement?: () => HTMLElement | null
 }

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