basalt-ui 1.25.0 → 1.27.0

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"}

package/dist/shell/app-mobile-nav.js

@@ -3,6 +3,8 @@ import { Drawer, Menu, NavLink, ScrollArea, Stack, Text, UnstyledButton } from "
 import { useReducedMotion } from "@mantine/hooks";
 import { Fragment as Fragment2, useState } from "react";
 import { NavCountBadge } from "./nav-count-badge.js";
+import { SidebarBlockToneDot } from "./sidebar-blocks.js";
+import { sidebarBlockMobile } from "./sidebar-block-model.js";
 import { useBasaltSpacing } from "../theme/index.js";
 import classes from "./app-mobile-nav.module.css";
 const MENU_MIDDLEWARES = { flip: false, shift: { padding: 8 } };
@@ -134,9 +136,11 @@ function MobileNav({
   model,
   config,
   account,
-  settingsMenuItems
+  settingsMenuItems,
+  blocks
 }) {
   const [openKey, setOpenKey] = useState(null);
+  const [openBlockKey, setOpenBlockKey] = useState(null);
   const reduceMotion = useReducedMotion();
   const { step } = useBasaltSpacing();
   const close = () => setOpenKey(null);
@@ -145,6 +149,61 @@ function MobileNav({
     target.scrollTo({ top: 0, behavior: reduceMotion ? "auto" : "smooth" });
   };
   const extraRows = [...accountRows(account), ...settingsRows(settingsMenuItems)];
+  const moreBlocks = (blocks ?? []).filter(
+    (block) => block.kind !== "custom" && sidebarBlockMobile(block) === "more" && (block.kind !== "list" || block.items.length > 0)
+  );
+  const listBlocks = moreBlocks.filter((block) => block.kind === "list");
+  const activateBlock = (block) => {
+    close();
+    if (block.kind === "list") {
+      setOpenBlockKey(block.key);
+      return;
+    }
+    block.onClick?.();
+  };
+  const menuBlockRow = (block) => /* @__PURE__ */ jsx(Menu.Item, { className: classes.menuItem, onClick: () => activateBlock(block), children: blockRowLabel(block) }, block.key);
+  const sheetBlockRow = (block) => /* @__PURE__ */ jsx(
+    NavLink,
+    {
+      classNames: { root: classes.row },
+      label: blockRowLabel(block),
+      onClick: () => activateBlock(block)
+    },
+    block.key
+  );
+  const blockItemRow = (item) => {
+    const lead = item.icon ?? (item.tone !== void 0 ? /* @__PURE__ */ jsx(SidebarBlockToneDot, { tone: item.tone }) : void 0);
+    const meta = item.meta !== void 0 ? /* @__PURE__ */ jsx(Text, { component: "span", className: classes.rowMeta, children: item.meta }) : void 0;
+    const interactive = item.Anchor !== void 0 || item.href !== void 0 || item.onClick !== void 0;
+    if (!interactive) {
+      return /* @__PURE__ */ jsxs("div", { className: classes.row, children: [
+        lead,
+        /* @__PURE__ */ jsx(Text, { component: "span", children: item.label }),
+        meta
+      ] }, item.key);
+    }
+    const shared = {
+      classNames: { root: classes.row },
+      label: item.label,
+      ...lead !== void 0 && { leftSection: lead },
+      ...meta !== void 0 && { rightSection: meta },
+      onClick: () => {
+        item.onClick?.();
+        setOpenBlockKey(null);
+      }
+    };
+    const Anchor = item.Anchor;
+    if (Anchor) return /* @__PURE__ */ jsx(NavLink, { component: Anchor, ...shared }, item.key);
+    return /* @__PURE__ */ jsx(
+      NavLink,
+      {
+        component: "a",
+        ...item.href !== void 0 && { href: item.href },
+        ...shared
+      },
+      item.key
+    );
+  };
   const hasCount = (slot) => slot.kind === "link" ? Boolean(slot.item.count) : slot.groups.some((g) => groupHasCount(g.items));
   const tabInner = (slot) => /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsxs("span", { className: classes.tabIcon, children: [
@@ -271,9 +330,9 @@ function MobileNav({
             ...group.label ? [/* @__PURE__ */ jsx(Menu.Label, { children: group.label }, `${group.key}-label`)] : [],
             ...rows(group.items, 0, menuRow)
           ]),
-          slot.isMore && extraRows.length > 0 && slotHasRows(slot) ? /* @__PURE__ */ jsx(Menu.Divider, {}) : null,
-          slot.isMore ? extraRows.map(menuActionRow) : null,
-          slot.isMore ? config?.moreExtra : null
+          slot.isMore && moreBlocks.length + extraRows.length > 0 && slotHasRows(slot) ? /* @__PURE__ */ jsx(Menu.Divider, {}) : null,
+          slot.isMore ? moreBlocks.map(menuBlockRow) : null,
+          slot.isMore ? extraRows.map(menuActionRow) : null
         ] })
       ]
     },
@@ -304,17 +363,45 @@ function MobileNav({
             sheetGroupLabel(group),
             rows(group.items, 0, sheetRow)
           ] }, group.key)),
-          slot.isMore && extraRows.length > 0 ? /* @__PURE__ */ jsx(Stack, { gap: 2, children: extraRows.map(sheetActionRow) }) : null,
-          slot.isMore ? config?.moreExtra : null
+          slot.isMore && moreBlocks.length > 0 ? /* @__PURE__ */ jsx(Stack, { gap: 2, children: moreBlocks.map(sheetBlockRow) }) : null,
+          slot.isMore && extraRows.length > 0 ? /* @__PURE__ */ jsx(Stack, { gap: 2, children: extraRows.map(sheetActionRow) }) : null
         ] }) })
       }
     )
   ] }, slot.key);
-  return /* @__PURE__ */ jsx("nav", { className: classes.bar, "aria-label": "Primary", children: model.slots.map((slot) => {
-    if (slot.kind === "link") return linkTab(slot);
-    if (slot.kind === "menu") return menuSlot(slot);
-    return sheetSlot(slot);
-  }) });
+  const blockSheet = (block) => /* @__PURE__ */ jsx(
+    Drawer,
+    {
+      opened: openBlockKey === block.key,
+      onClose: () => setOpenBlockKey(null),
+      position: "bottom",
+      padding: "md",
+      title: block.label,
+      classNames: {
+        content: classes.sheet,
+        title: classes.sheetTitle,
+        header: classes.sheetHeader
+      },
+      transitionProps: {
+        transition: "slide-up",
+        duration: reduceMotion ? 0 : 220,
+        timingFunction: "cubic-bezier(0.32, 0.72, 0, 1)"
+      },
+      children: /* @__PURE__ */ jsx(ScrollArea.Autosize, { mah: "62dvh", type: "scroll", children: /* @__PURE__ */ jsx(Stack, { gap: 2, children: block.items.map(blockItemRow) }) })
+    },
+    `block-${block.key}`
+  );
+  return /* @__PURE__ */ jsxs("nav", { className: classes.bar, "aria-label": "Primary", children: [
+    model.slots.map((slot) => {
+      if (slot.kind === "link") return linkTab(slot);
+      if (slot.kind === "menu") return menuSlot(slot);
+      return sheetSlot(slot);
+    }),
+    listBlocks.map(blockSheet)
+  ] });
+}
+function blockRowLabel(block) {
+  return block.kind === "list" ? `${block.label} \xB7 ${block.count ?? block.items.length}` : `${block.label} \xB7 ${block.value} of ${block.total}`;
 }
 function slotHasRows(slot) {
   return slot.groups.some((group) => group.items.length > 0);

package/dist/shell/app-mobile-nav.module.css

@@ -252,6 +252,14 @@
   background-color: color-mix(in srgb, var(--vx-ink) 10%, transparent);
 }
 
+/* Trailing meta on a block-item row (a timestamp, an owner) — the mobile twin of the sidebar's
+ * `.blockRowMeta`, so the same `SidebarBlockItem.meta` reads the same on both surfaces. */
+.rowMeta {
+  flex: none;
+  font-size: var(--vx-text-micro);
+  color: var(--vx-faint);
+}
+
 /*
  * Active = neutral surface fill + plain text color. Never the identity blue (DESIGN.md). --nl-color
  * forces NavLink's active text/icon color (otherwise the accent) to the plain text color. The

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

@@ -19,5 +19,6 @@ declare const classes: {
   readonly sheetHeader: string
   readonly row: string
   readonly rowNested: string
+  readonly rowMeta: string
 }
 export default classes

package/dist/shell/app-sidebar.d.ts

@@ -1,49 +1,76 @@
-import type { ReactNode } from 'react';
 import type { BrandConfig, SettingsMenuItem } from './index.js';
-import type { SidebarSection } from '../nav/types.js';
-import type { BasaltAccountProps } from './account-types.js';
-import type { SidebarSearchConfig } from './sidebar-search.js';
+import type { SidebarBlock, SidebarSection } from '../nav/types.js';
+import type { AccountMenuItem, BasaltAccountProps } from './account-types.js';
+import type { SidebarSearchActions, SidebarSearchConfig } from './sidebar-search.js';
 export type AppSidebarProps = {
-    brand: BrandConfig;
+    /**
+     * Brand identity. Supplying `menu` turns the brand row into a `Name ▾` workspace switcher —
+     * the entries are the existing `AccountMenuItem` shape, so a consumer already mapping account
+     * actions needs no second vocabulary.
+     */
+    brand: BrandConfig & {
+        menu?: AccountMenuItem[];
+    };
     sections: SidebarSection[];
     collapsed: boolean;
     onToggleCollapse: () => void;
     /**
      * Footer settings-menu entries (theme switcher, devtools, …) — supplied by the consumer.
-     * The pinned footer "Settings" row renders ONLY when this is a non-empty list — apps that put
-     * Settings in a nav section (the common case) omit this and get no duplicate footer row. The
-     * `brand.version` label renders inside this menu, so it also only shows when the row does.
+     * The pinned footer row renders ONLY when this is a non-empty list — apps that put Settings in a
+     * nav section (the common case) omit this and get no duplicate footer row.
+     *
+     * **Three entries or fewer render FLAT**, as one link row each (Settings · Integrations · Invite
+     * teammates), and four or more collapse into the single gear "Settings" menu. A menu that opens
+     * to show two rows costs a click for nothing; a footer of eight rows costs the nav its height.
+     * That threshold is basalt's — `docs/CONTROLS-SPEC.md` §2.3 — and `settingsMenu` is the override
+     * for the cases the count cannot see. `brand.version` renders as a faint label under the flat
+     * rows, and inside the dropdown in the menu form.
      */
     settingsMenuItems?: SettingsMenuItem[];
+    /**
+     * Which footer form `settingsMenuItems` takes. `'auto'` (the default) is the count rule above;
+     * `'flat'` and `'menu'` force one regardless of how many entries there are.
+     *
+     * The override exists because the COUNT is not the whole question. Three rows that are each a
+     * theme radio group, a devtools switch and a density slider are three CONTROLS, not three
+     * destinations — flat they fill the footer with widgets and push the account row off the fold,
+     * and the count rule cannot tell them from three links. Equally, four short destinations may be
+     * worth their height on a tall sidebar. `'auto'` stays the default so nothing moves for a
+     * consumer that never had an opinion.
+     *
+     * DESKTOP FOOTER ONLY. Below `sm` there is no sidebar at all and the same entries are flat rows
+     * in the bottom bar's More surface either way — a dropdown inside that sheet would be a menu
+     * inside a menu.
+     *
+     * @default 'auto'
+     */
+    settingsMenu?: 'auto' | 'flat' | 'menu';
     /**
      * Optional account row rendered below the settings menu in the sidebar footer (see
-     * `SidebarAccount` / `BasaltAccountProps`), separated by its own top hairline. Omitting it
-     * reproduces today's footer unchanged.
+     * `SidebarAccount` / `BasaltAccountProps`) — no separating hairline, the row's own top padding
+     * supplies the separation. Omitting it reproduces today's footer unchanged.
      */
     account?: BasaltAccountProps;
     /**
      * Optional search field rendered directly below the brand and ABOVE the nav scroll region — a
-     * fixed, non-scrolling row. Pair with basalt-ui/commands' openSpotlight.
+     * fixed, non-scrolling row. Pair with basalt-ui/commands' openSpotlight. `actions` adds up to two
+     * icon-only buttons to the right of that row.
      */
-    search?: SidebarSearchConfig;
+    search?: SidebarSearchConfig & {
+        actions?: SidebarSearchActions;
+    };
     /**
-     * Arbitrary content appended after `sections` inside the nav `ScrollArea` — a tree, a filter
-     * panel, a project list, anything a set of `SidebarItem`s can't express. Renders as the last
-     * child of the scrolling nav column, so a long list scrolls with the rest of the nav instead of
-     * fighting it for height. Pass `sections={[]}` to use this slot exclusively; the section-spacing
-     * rule only fires between adjacent children, so an empty `sections` produces no orphan divider or
-     * dead padding above it.
+     * Declared blocks (`docs/CONTROLS-SPEC.md` §2.3, law C13) — an "Awaiting action" list, a
+     * "Recents" list, a "Getting started" progress row, or a `kind: 'custom'` node for a tree or
+     * filter panel no set of rows can express (`kind: 'custom'` is what replaced `navExtra`).
      *
-     * Hidden on the collapsed desktop rail; still present in the mobile drawer, which opens at full
-     * width. The rail is ~56px of icon buttons with no sensible representation for arbitrary
-     * consumer content, so the CSS media query that drives the rail hides this slot the same way it
-     * hides `.childList` — never a JS check on `collapsed`, since that one value is shared by the
-     * rail AND the drawer (only the media query tells them apart). `SidebarSearch` gets to adapt
-     * itself to the rail (it takes `collapsed` and renders its own icon-only form) because the shell
-     * owns that control; it cannot adapt content it knows nothing about, so this slot hides instead
-     * of squashing it.
+     * `placement: 'nav'` appends after `sections` INSIDE the nav scroll region, so a long list
+     * scrolls with the nav instead of fighting it for height; `'bottom'` pins above the settings
+     * footer. Because these are data and not a `ReactNode` slot, basalt owns both projections a slot
+     * could never express: the collapsed rail (a count dot on the icon, a ring on the settings row)
+     * and the mobile More sheet — see `sidebarBlockRail` / `sidebarBlockMobile`.
      */
-    navExtra?: ReactNode;
+    blocks?: SidebarBlock[];
 };
-export declare function AppSidebar({ brand, sections, collapsed, onToggleCollapse, settingsMenuItems, account, search, navExtra, }: AppSidebarProps): import("react").JSX.Element;
+export declare function AppSidebar({ brand, sections, collapsed, onToggleCollapse, settingsMenuItems, settingsMenu, account, search, blocks, }: AppSidebarProps): import("react").JSX.Element;
 //# sourceMappingURL=app-sidebar.d.ts.map