basalt-ui 1.24.0 → 1.26.0

package/dist/router-tanstack/use-nav.js

@@ -1,5 +1,6 @@
 import { createElement, useMemo } from "react";
 import { Link, useMatchRoute, useRouterState } from "@tanstack/react-router";
+import { flattenNav } from "./nav.js";
 function useNav(config, opts) {
   const matchRoute = useMatchRoute();
   const href = useRouterState({ select: (s) => s.location.href });
@@ -7,29 +8,52 @@ function useNav(config, opts) {
   const isActiveOverride = opts?.isActive;
   const sections = useMemo(() => {
     const badgeOf = (id) => badges?.[id];
-    const isActive = (item) => isActiveOverride?.(item) ?? Boolean(
+    const matchOf = (item) => isActiveOverride?.(item) ?? Boolean(
       matchRoute({
         to: item.link.to,
         ...item.link.params !== void 0 && { params: item.link.params },
-        // Prefix match by default so a parent stays lit on its children; `'/'` would then match
-        // everything, so it is always exact.
         fuzzy: item.exact !== true && item.link.to !== "/"
       })
     );
+    const allItems = flattenNav(config);
+    const specificity = (to) => to.split("/").filter(Boolean).length;
+    const matchedById = /* @__PURE__ */ new Map();
+    let winnerId;
+    let winnerTo;
+    for (const item of allItems) {
+      const matched = matchOf(item);
+      matchedById.set(item.id, matched);
+      if (matched && (winnerTo === void 0 || specificity(item.link.to) > specificity(winnerTo))) {
+        winnerId = item.id;
+        winnerTo = item.link.to;
+      }
+    }
+    const resolveState = (item) => {
+      if (item.id === winnerId) return { active: true, ancestor: false };
+      const matched = matchedById.get(item.id) ?? false;
+      const ancestor = winnerTo !== void 0 && matched && winnerTo.startsWith(`${item.link.to}/`);
+      return { active: false, ancestor };
+    };
     const toSidebarItem = (item) => {
-      const Anchor = (props) => createElement(Link, { ...item.link, ...props });
+      const Anchor = (props) => createElement(Link, {
+        ...item.link,
+        activeOptions: { exact: true },
+        ...props
+      });
       const badge = badgeOf(item.id);
       const children = item.children?.map(toSidebarItem);
+      const { active, ancestor } = resolveState(item);
       return {
         key: item.id,
         label: item.label,
         icon: item.icon,
         Anchor,
-        // Per-destination active only. Rolling a child's active state up into its parent is the
-        // MOBILE SLOT's rule (§2.3.12) and belongs to `projectMobileNav`, which reads `children`
-        // anyway — doing it here too would also light a desktop parent row whose own route does
-        // not match.
-        active: isActive(item),
+        // Exactly one destination in the WHOLE definition reads `active` (`resolveState` above).
+        // Rolling that up into a mobile SLOT (any descendant active → the slot reads active) is
+        // still `projectMobileNav`'s job, which reads `children` for that. `ancestor` is the
+        // desktop-only middle state: a matched item that sits on the winner's path but isn't it.
+        active,
+        ...ancestor && { ancestor },
         ...item.short !== void 0 && { short: item.short },
         ...item.mobile !== void 0 && { mobile: item.mobile },
         ...item.disabled !== void 0 && { disabled: item.disabled },
@@ -47,7 +71,6 @@ function useNav(config, opts) {
     }));
   }, [config, matchRoute, href, badges, isActiveOverride]);
   const mobile = config.mobile;
-  const moreExtra = opts?.moreExtra;
   const getScrollElement = opts?.getScrollElement;
   const mobileNav = useMemo(() => {
     const groupLabelById = new Map(config.groups.map((g) => [g.id, g.label]));
@@ -60,10 +83,9 @@ function useNav(config, opts) {
       ...mobile?.maxTabs !== void 0 && { maxTabs: mobile.maxTabs },
       ...mobile?.menuMax !== void 0 && { menuMax: mobile.menuMax },
       ...mobile?.moreLabel !== void 0 && { moreLabel: mobile.moreLabel },
-      ...moreExtra !== void 0 && { moreExtra },
       ...getScrollElement !== void 0 && { getScrollElement }
     };
-  }, [config, mobile, moreExtra, getScrollElement]);
+  }, [config, mobile, getScrollElement]);
   return { sections, mobileNav };
 }
 export {

package/dist/router-tanstack/use-nav.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-nav.test.d.ts.map

package/dist/router-tanstack/use-nav.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-nav.test.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/use-nav.test.tsx"],"names":[],"mappings":""}

package/dist/section/index.d.ts

@@ -0,0 +1,2 @@
+export { Section, type SectionProps } from './section.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/section/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/section/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAA"}

package/dist/section/index.js

@@ -0,0 +1,4 @@
+import { Section } from "./section.js";
+export {
+  Section
+};

package/dist/section/section.d.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+import type { WidgetHeaderProps } from '../widget-header/index.js';
+export type SectionProps = Omit<WidgetHeaderProps, 'tier'> & {
+    /** Rendered in the header row, in its own `CtlSlot` — hidden while the section is collapsed. */
+    tabs?: ReactNode;
+    /** Renders a chevron toggle in the header; the header stays drawn when closed, only `children`
+     * (and `tabs`) unmount. @default false */
+    collapsible?: boolean;
+    /** Persists the fold state at `basalt:section:<persistKey>`. Omit for a local, unpersisted fold
+     * (`useState`). */
+    persistKey?: string;
+    /** The fold state a section opens on, respected only while no persisted value exists — a section
+     * a reader has closed stays closed. `false` is what a long secondary block wants. @default true */
+    defaultOpen?: boolean;
+    /** Rendered directly under the header and ALWAYS visible, collapsed or not: a collapsed section
+     * still states its headline figures, which is what makes collapsing it a real option. Keep it to
+     * one row — the body is what `children` is for. */
+    summary?: ReactNode;
+    /** Turns the root into a scroll anchor (`id` + `scroll-margin-top` cleared for both sticky bars). */
+    id?: string;
+    children: ReactNode;
+};
+export declare function Section({ title, icon, subtitle, info, value, delta, deltaPeriod, sparkline, count, actions, tabs, collapsible, persistKey, defaultOpen, summary, id, children, }: SectionProps): import("react").JSX.Element;
+//# sourceMappingURL=section.d.ts.map

package/dist/section/section.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../../src/section/section.tsx"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAGzD,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,GAAG;IAC3D,gGAAgG;IAChG,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;8CAC0C;IAC1C,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;uBACmB;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;uGACmG;IACnG,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;uDAEmD;IACnD,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAgFD,wBAAgB,OAAO,CAAC,EACtB,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,KAAK,EACL,WAAW,EACX,SAAS,EACT,KAAK,EACL,OAAO,EACP,IAAI,EACJ,WAAmB,EACnB,UAAU,EACV,WAAkB,EAClB,OAAO,EACP,EAAE,EACF,QAAQ,GACT,EAAE,YAAY,+BAiDd"}

package/dist/section/section.js

@@ -0,0 +1,126 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Children, useId, useMemo, useState } from "react";
+import { CtlSlot } from "../theme/index.js";
+import { createPersistedState } from "../state.js";
+import { WidgetHeader } from "../widget-header/index.js";
+import classes from "./section.module.css";
+function isDev() {
+  return process.env["NODE_ENV"] !== "production";
+}
+function warnPastActionBudget(title, actions) {
+  if (!isDev()) return;
+  const count = Children.count(actions);
+  if (count <= 3) return;
+  console.warn(
+    `Section "${title}": ${count} actions exceeds the \u22643 budget (docs/CONTROLS-SPEC.md C6) \u2014 move the rest behind a menu.`
+  );
+}
+const UNPERSISTED_KEY = "__local__";
+function useSectionOpen(persistKey, defaultOpen) {
+  const [localOpen, setLocalOpen] = useState(defaultOpen);
+  const usePersistedOpen = useMemo(
+    () => createPersistedState({
+      key: `section:${persistKey ?? UNPERSISTED_KEY}`,
+      version: 1,
+      initial: defaultOpen
+    }),
+    [persistKey, defaultOpen]
+  );
+  const [persistedOpen, setPersistedOpen] = usePersistedOpen();
+  if (persistKey !== void 0) return [persistedOpen, setPersistedOpen];
+  return [localOpen, setLocalOpen];
+}
+function ChevronToggle({
+  open,
+  onToggle,
+  controls
+}) {
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      className: classes.chevron,
+      "data-open": open,
+      "aria-expanded": open,
+      "aria-controls": controls,
+      "aria-label": open ? "Collapse section" : "Expand section",
+      onClick: onToggle,
+      children: /* @__PURE__ */ jsx(
+        "svg",
+        {
+          width: 12,
+          height: 12,
+          viewBox: "0 0 24 24",
+          fill: "none",
+          stroke: "currentColor",
+          strokeWidth: 2.5,
+          "aria-hidden": "true",
+          children: /* @__PURE__ */ jsx("path", { d: "M6 9l6 6 6-6", strokeLinecap: "round", strokeLinejoin: "round" })
+        }
+      )
+    }
+  );
+}
+function Section({
+  title,
+  icon,
+  subtitle,
+  info,
+  value,
+  delta,
+  deltaPeriod,
+  sparkline,
+  count,
+  actions,
+  tabs,
+  collapsible = false,
+  persistKey,
+  defaultOpen = true,
+  summary,
+  id,
+  children
+}) {
+  const [open, setOpen] = useSectionOpen(persistKey, defaultOpen);
+  const bodyId = useId();
+  if (actions !== void 0) warnPastActionBudget(title, actions);
+  const headerActions = tabs !== void 0 || actions !== void 0 || collapsible ? /* @__PURE__ */ jsxs(Fragment, { children: [
+    tabs !== void 0 && open && /* @__PURE__ */ jsx(CtlSlot, { children: tabs }),
+    actions !== void 0 && /* @__PURE__ */ jsx(CtlSlot, { children: actions }),
+    collapsible && /* @__PURE__ */ jsx(ChevronToggle, { open, onToggle: () => setOpen(!open), controls: bodyId })
+  ] }) : void 0;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: classes.root,
+      ...id !== void 0 && { id },
+      ...id !== void 0 && {
+        style: {
+          scrollMarginTop: "calc(var(--app-shell-header-height, 0px) + var(--basalt-page-bar-h, 0px))"
+        }
+      },
+      children: [
+        /* @__PURE__ */ jsx(
+          WidgetHeader,
+          {
+            tier: "section",
+            title,
+            ...icon !== void 0 && { icon },
+            ...subtitle !== void 0 && { subtitle },
+            ...info !== void 0 && { info },
+            ...value !== void 0 && { value },
+            ...delta !== void 0 && { delta },
+            ...deltaPeriod !== void 0 && { deltaPeriod },
+            ...sparkline !== void 0 && { sparkline },
+            ...count !== void 0 && { count },
+            ...headerActions !== void 0 && { actions: headerActions }
+          }
+        ),
+        summary !== void 0 && /* @__PURE__ */ jsx("div", { className: classes.summary, children: summary }),
+        open && /* @__PURE__ */ jsx("div", { id: bodyId, className: classes.body, children })
+      ]
+    }
+  );
+}
+export {
+  Section
+};

package/dist/section/section.module.css

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

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

@@ -0,0 +1,11 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly root: string
+  readonly body: string
+  readonly summary: string
+  readonly chevron: string
+}
+export default classes

package/dist/section/section.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=section.test.d.ts.map

package/dist/section/section.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section.test.d.ts","sourceRoot":"","sources":["../../src/section/section.test.tsx"],"names":[],"mappings":""}

package/dist/shell/app-breadcrumbs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-breadcrumbs.d.ts","sourceRoot":"","sources":["../../src/shell/app-breadcrumbs.tsx"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAkB7C,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,MAAM,EACN,YAAY,EACZ,UAAU,EACV,IAAI,GACL,EAAE;IACD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IACpC,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,sCAyCA"}
+{"version":3,"file":"app-breadcrumbs.d.ts","sourceRoot":"","sources":["../../src/shell/app-breadcrumbs.tsx"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAmB7C,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,MAAM,EACN,YAAY,EACZ,UAAU,EACV,IAAI,GACL,EAAE;IACD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IACpC,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,sCAqDA"}

package/dist/shell/app-breadcrumbs.js

@@ -1,6 +1,7 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { Anchor, Group, Text } from "@mantine/core";
 import { VX } from "../tokens/index.js";
+import classes from "./app-header.module.css";
 const crumbStyle = { fontSize: VX.text.md, color: "var(--vx-faint)" };
 const separatorStyle = { fontSize: VX.text.md, color: "var(--vx-surface-border)" };
 const currentStyle = {
@@ -19,21 +20,23 @@ function AppBreadcrumbs({
 }) {
   if (!page) return null;
   return /* @__PURE__ */ jsxs(Group, { gap: 6, wrap: "nowrap", style: { minWidth: 0 }, children: [
-    section && /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx(Text, { style: crumbStyle, truncate: true, children: section }),
-      /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
-    ] }),
-    parent && parentAnchor && /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx(Anchor, { style: crumbStyle, underline: "never", component: parentAnchor, truncate: true, children: parent }),
-      /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
-    ] }),
-    parent && !parentAnchor && parentHref && /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx(Anchor, { style: crumbStyle, underline: "never", href: parentHref, truncate: true, children: parent }),
-      /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
-    ] }),
-    parent && !parentAnchor && !parentHref && /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx(Text, { style: crumbStyle, truncate: true, children: parent }),
-      /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
+    (section !== void 0 || parent !== void 0) && /* @__PURE__ */ jsxs(Group, { gap: 6, wrap: "nowrap", className: classes.crumbAncestors, style: { minWidth: 0 }, children: [
+      section && /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx(Text, { style: crumbStyle, truncate: true, children: section }),
+        /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
+      ] }),
+      parent && parentAnchor && /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx(Anchor, { style: crumbStyle, underline: "never", component: parentAnchor, truncate: true, children: parent }),
+        /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
+      ] }),
+      parent && !parentAnchor && parentHref && /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx(Anchor, { style: crumbStyle, underline: "never", href: parentHref, truncate: true, children: parent }),
+        /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
+      ] }),
+      parent && !parentAnchor && !parentHref && /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx(Text, { style: crumbStyle, truncate: true, children: parent }),
+        /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
+      ] })
     ] }),
     /* @__PURE__ */ jsx(Text, { style: currentStyle, truncate: true, children: page })
   ] });

package/dist/shell/app-header.module.css

@@ -1,7 +1,10 @@
-/* App-shell top bar layout. Desktop: a single 56px row —
- * [burger? · breadcrumb] ········ [page actions] | [global actions].
- * Mobile (< sm): wraps to two rows — lead + global on row 1, the page action row
- * (horizontally scrollable) on row 2. Header height is responsive to match. */
+/* App-shell top bar layout. ONE 48px row on every viewport —
+ * [breadcrumb] ········ [page bar row 1] | [global actions].
+ *
+ * The pre-1.26.0 mobile layout wrapped to a second, always-reserved row for the page actions and
+ * scrolled it sideways. Both are gone (law C7 and law C14): the header height is now the
+ * `appShellHeaderHeight` token at every width, an empty page bar reserves nothing, and overflow
+ * folds into `ActionGroup`'s kebab instead of scrolling out of view. */
 
 /*
  * Transparent header (docs/DESIGN-SPEC.md §5): NO bottom rule at all. The header and the page body
@@ -16,58 +19,95 @@
   height: 100%;
 }
 
+/*
+ * **Exactly ONE side of the header row is elastic, and it is the side whose content can ellipsize.**
+ * That is the whole rule, and both collisions this header has produced were the same violation of
+ * it from opposite directions.
+ *
+ * First the breadcrumb was `flex-shrink: 0`, so it won the whole width and the primary action
+ * rendered UNDERNEATH it. Then BOTH sides were made shrinkable (`.lead` at `0 1 auto`, `.pageBar` at
+ * `1 1 auto` with `min-width: 0` pushed onto its children) — and at 390px the controls, which cannot
+ * clip, shrank below their content and spilled: a flex container with `justify-content: flex-end`
+ * overflows towards its START, so the sync button painted 30px INTO the page title. Measured in
+ * Chrome: the title spanned 119.7–197.1 and the sync button 158.3–188.3.
+ *
+ * So the lead is now the elastic side (`flex: 1 1 auto`, `min-width: 0`, each crumb truncating via
+ * its own `truncate` prop) and the control side is rigid. A row of buttons that genuinely does not
+ * fit is not a shrinking problem — it is the OVERFLOW FOLD's problem, and basalt already owns that
+ * (law C7: below `sm` row 1 is the primary plus ONE kebab).
+ */
 .lead {
   display: flex;
   align-items: center;
   gap: var(--mantine-spacing-sm);
-  flex-shrink: 0;
+  flex: 1 1 auto;
   min-width: 0;
 }
 
-.pageActions {
-  flex: 1 1 auto;
+/* No `overflow: hidden` here or on `.lead` above: Mantine's focus ring is `outline: 2px solid;
+ * outline-offset: 2px` — OUTSIDE the anchor box — and a wrapper clipping this tightly to the
+ * breadcrumb anchors clipped the ring on every edge, leaving the primary in-shell nav link with no
+ * visible focus indicator. Truncation is already owned by each crumb's own `truncate` prop
+ * (`app-breadcrumbs.tsx`, Mantine's `[data-truncate]` rule sets its own `overflow: hidden;
+ * text-overflow: ellipsis; white-space: nowrap` on the element that actually holds the text) — this
+ * wrapper only needs to let its children shrink. */
+.lead * {
   min-width: 0;
-  display: flex;
-  align-items: center;
-  justify-content: flex-end;
-  gap: var(--mantine-spacing-xs);
-  overflow-x: auto;
-  scrollbar-width: thin;
 }
 
-/* Keep the whole control row on one horizontally-scrollable line. Mantine Group
- * defaults to flex-wrap:wrap, which otherwise stacks the nested control groups and
- * clips them against the slim bar's fixed height. */
-.pageActions :global(.mantine-Group-root) {
+/*
+ * The `PageBar` row-1 portal target — the RIGID side of the row (see `.lead` above for the rule and
+ * for the two collisions that established it). Never a scroll container — see the header note above.
+ *
+ * `flex: 0 0 auto` and no `min-width: 0` anywhere below it, deliberately: a button cannot ellipsize,
+ * so letting this side shrink does not make it narrower, it makes it OVERFLOW — leftwards, into the
+ * breadcrumb, because of the `justify-content: flex-end` two lines down. The previous version pushed
+ * `min-width: 0` onto every child for exactly the reason that comment gave (a `wrap="nowrap"` group's
+ * automatic minimum size is its min-content width and flex will not go below it) — the reasoning was
+ * right and the conclusion was backwards: that floor is the row's protection, not its bug.
+ */
+.pageBar {
+  flex: 0 0 auto;
+  display: flex;
   flex-wrap: nowrap;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--vx-space-control-gap);
 }
 
+/*
+ * The shell globals sit at the SAME 30px tier as everything else in the row, and they get there the
+ * same way a home's slot does — `HeaderGlobalActions` wraps this region in a `CtlSlot`, so a
+ * consumer's bare `<ActionIcon>` in `globalActions` defaults to `size="ctl"` with no prop at the call
+ * site (law C5). They rendered at Mantine's `md` 28px before, which is 2px under the page group
+ * beside them: close enough to look like a mistake rather than a tier.
+ *
+ * The gap to the page group is `.bar`'s own `sm`, so the globals read as a separate cluster; between
+ * themselves they use the control gap, like every other adjacent-control pair.
+ */
 .global {
   display: flex;
+  flex-wrap: nowrap;
   align-items: center;
-  gap: var(--mantine-spacing-xs);
+  gap: var(--vx-space-control-gap);
   flex-shrink: 0;
 }
 
-@media (max-width: 47.99375em) {
-  .bar {
-    flex-wrap: wrap;
-    align-content: center;
-  }
-
-  .lead {
-    order: 1;
-    flex: 1 1 auto;
-  }
-
-  .global {
-    order: 2;
-  }
+.global :global(.mantine-ActionIcon-root) > svg {
+  width: 1rem;
+  height: 1rem;
+}
 
-  .pageActions {
-    order: 3;
-    flex-basis: 100%;
-    height: var(--vx-space-app-header-mobile-actions-height);
-    justify-content: flex-start;
+/*
+ * The breadcrumb's ANCESTOR crumbs — hidden below `sm`. See `app-breadcrumbs.tsx` for why: at 390px
+ * the row's elastic side truncated `Overview / Dashboard` to `O… / D…`, which is two ellipses and a
+ * separator in place of the one word that says where the reader is.
+ *
+ * `47.99375em` is the `sm` breakpoint in the exact literal form every other basalt CSS module uses —
+ * a media query cannot resolve a custom property.
+ */
+@media (max-width: 47.99375em) {
+  .crumbAncestors {
+    display: none;
   }
 }

package/dist/shell/app-header.module.css.d.ts

@@ -5,7 +5,8 @@
 declare const classes: {
   readonly bar: string
   readonly lead: string
-  readonly pageActions: string
+  readonly pageBar: string
   readonly global: string
+  readonly crumbAncestors: string
 }
 export default classes

package/dist/shell/app-mobile-nav.d.ts

@@ -1,5 +1,5 @@
 import type { ReactElement } from 'react';
-import type { MobileNavConfig, MobileNavModel } from '../nav/types.js';
+import type { MobileNavConfig, MobileNavModel, SidebarBlock } from '../nav/types.js';
 import type { BasaltAccountProps } from './account-types.js';
 import type { SettingsMenuItem } from './index.js';
 export type MobileNavProps = {
@@ -11,6 +11,13 @@ export type MobileNavProps = {
      *  deletable: everything it used to hold is reachable from More. */
     account?: BasaltAccountProps | undefined;
     settingsMenuItems?: SettingsMenuItem[] | undefined;
+    /**
+     * The sidebar's blocks, projected. A block with `mobile: 'more'` becomes ONE row in the More
+     * surface (`Awaiting action · 3`) that opens a nested 44px-row sheet of its items — the sidebar
+     * itself does not exist below `sm`, so this is the only way its blocks are reachable at all.
+     * Counted for the menu-vs-sheet threshold by `blockRowCount`, never re-counted here.
+     */
+    blocks?: SidebarBlock[] | undefined;
 };
 /**
  * How many rows `account` contributes to the More surface — DELEGATED to `accountRows` rather than
@@ -21,5 +28,5 @@ export type MobileNavProps = {
  * rows — still conjured a More slot that opened empty.
  */
 export declare function accountRowCount(account: BasaltAccountProps | undefined): number;
-export declare function MobileNav({ model, config, account, settingsMenuItems, }: MobileNavProps): ReactElement;
+export declare function MobileNav({ model, config, account, settingsMenuItems, blocks, }: MobileNavProps): ReactElement;
 //# sourceMappingURL=app-mobile-nav.d.ts.map

package/dist/shell/app-mobile-nav.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-mobile-nav.d.ts","sourceRoot":"","sources":["../../src/shell/app-mobile-nav.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,YAAY,EAAa,MAAM,OAAO,CAAA;AAChE,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EAGf,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAiB/C,MAAM,MAAM,cAAc,GAAG;IAC3B,kFAAkF;IAClF,KAAK,EAAE,cAAc,CAAA;IACrB,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACpC;;wEAEoE;IACpE,OAAO,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAA;IACxC,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,GAAG,SAAS,CAAA;CACnD,CAAA;AAkFD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,CAE/E;AAsFD,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,MAAM,EACN,OAAO,EACP,iBAAiB,GAClB,EAAE,cAAc,GAAG,YAAY,CAiP/B"}
+{"version":3,"file":"app-mobile-nav.d.ts","sourceRoot":"","sources":["../../src/shell/app-mobile-nav.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,YAAY,EAAa,MAAM,OAAO,CAAA;AAChE,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EAEd,YAAY,EAKb,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAmB/C,MAAM,MAAM,cAAc,GAAG;IAC3B,kFAAkF;IAClF,KAAK,EAAE,cAAc,CAAA;IACrB,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACpC;;wEAEoE;IACpE,OAAO,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAA;IACxC,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,GAAG,SAAS,CAAA;IAClD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,YAAY,EAAE,GAAG,SAAS,CAAA;CACpC,CAAA;AAkFD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,CAE/E;AAsFD,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,MAAM,EACN,OAAO,EACP,iBAAiB,EACjB,MAAM,GACP,EAAE,cAAc,GAAG,YAAY,CAuW/B"}