basalt-ui 1.25.0 → 1.27.0

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

@@ -10,6 +10,7 @@ declare const classes: {
   readonly brand: string
   readonly brandLead: string
   readonly brandName: string
+  readonly brandButton: string
   readonly searchSlot: string
   readonly navScroll: string
   readonly navViewport: string
@@ -27,7 +28,24 @@ declare const classes: {
   readonly sectionHeader: string
   readonly subnavDropdown: string
   readonly childList: string
-  readonly navExtra: string
   readonly ghostIcon: string
+  readonly block: string
+  readonly blockHeader: string
+  readonly blockHeaderButton: string
+  readonly blockIcon: string
+  readonly blockDot: string
+  readonly blockItems: string
+  readonly blockRow: string
+  readonly blockRowStatic: string
+  readonly blockRowLabel: string
+  readonly blockRowMeta: string
+  readonly blockToneDot: string
+  readonly blockMore: string
+  readonly blockProgress: string
+  readonly blockProgressHead: string
+  readonly blockRing: string
+  readonly footerLinks: string
+  readonly footerIconSlot: string
+  readonly footerVersion: string
 }
 export default classes

package/dist/shell/index.d.ts

@@ -1,22 +1,23 @@
 import type { MouseEvent, ReactNode } from 'react';
-import type { BasaltAccountProps } from './account-types.js';
-import type { SidebarSearchConfig } from './sidebar-search.js';
-import type { MobileNavConfig, SidebarSection } from '../nav/types.js';
+import type { GlobalAction } from '../controls/actions.js';
+import type { AccountMenuItem, BasaltAccountProps } from './account-types.js';
+import type { SidebarSearchActions, SidebarSearchConfig } from './sidebar-search.js';
+import type { MobileNavConfig, SidebarBlock, SidebarSection } from '../nav/types.js';
 export { AppSidebar, type AppSidebarProps } from './app-sidebar.js';
 export { NavCountBadge } from './nav-count-badge.js';
-export { SidebarSearch, type SidebarSearchConfig } from './sidebar-search.js';
+export { SidebarSearch, type SidebarSearchConfig, type SidebarSearchActions, } from './sidebar-search.js';
 export { SidebarAccount } from './app-sidebar-account.js';
 export type { AccountBadgeTone, BasaltIdentity, BasaltRole, BasaltPlan, AccountMenuItem, BasaltAccountState, BasaltAccountActions, BasaltAccountProps, } from './account-types.js';
 export { MobileNav, type MobileNavProps } from './app-mobile-nav.js';
 export { projectMobileNav, type ProjectMobileNavOptions, MOBILE_MAX_TABS_DEFAULT, MOBILE_MENU_MAX_DEFAULT, MOBILE_MORE_KEY, } from './mobile-nav-model.js';
 export { AppBreadcrumbs } from './app-breadcrumbs.js';
-export { PageHeaderProvider, PageActions, PageActionsOutlet } from './page-header.js';
+export { PageBar, type PageBarProps } from './page-bar.js';
 /**
  * The shared nav vocabulary lives in `src/nav/types.ts` so the headless router bridge can `import
  * type` it without reaching into the Mantine layer. Re-exported here so `SidebarItem` /
  * `SidebarSection` keep resolving straight from `basalt-ui`, exactly as before.
  */
-export type { NavAnchor, NavAnchorProps, NavMobilePlacement, NavSectionMobile, SidebarItem, SidebarSection, MobileNavConfig, MobileNavGroup, MobileNavModel, MobileNavSlot, MobileNavSurface, } from '../nav/types.js';
+export type { NavAnchor, NavAnchorProps, NavMobilePlacement, NavSectionMobile, SidebarItem, SidebarSection, SidebarBlock, SidebarBlockItem, SidebarBlockTone, SidebarListBlock, SidebarProgressBlock, SidebarCustomBlock, MobileNavConfig, MobileNavGroup, MobileNavModel, MobileNavSlot, MobileNavSurface, } from '../nav/types.js';
 /** Brand identity shown in the sidebar header (logo + name). */
 export type BrandConfig = {
     /** Display name (e.g. "Argo"). */
@@ -36,8 +37,13 @@ export type SettingsMenuItem = {
     onClick?: (e: MouseEvent) => void;
 };
 export type BasaltShellProps = {
-    /** Brand identity for the sidebar header. */
-    brand: BrandConfig;
+    /**
+     * 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.
+     */
+    brand: BrandConfig & {
+        menu?: AccountMenuItem[];
+    };
     /** Grouped nav sections — the ONE definition, rendered as the sidebar and projected to the bar. */
     sections: SidebarSection[];
     /**
@@ -45,28 +51,56 @@ export type BasaltShellProps = {
      * configured still produces a working bar (see `projectMobileNav`'s zero-config fallback).
      */
     mobileNav?: MobileNavConfig;
-    /** Persistent, shell-owned top-bar slot (timer, refresh, notifications). */
-    globalActions?: ReactNode;
     /**
-     * DESKTOP ONLY. Arbitrary content appended after `sections` inside the sidebar's nav scroll
-     * region (a tree, a filter panel, a project list, …), for anything a set of `SidebarItem`s can't
-     * express. Hidden on the collapsed desktop rail; the sidebar itself no longer exists below the
-     * `sm` breakpoint, so this slot has no mobile representation — put mobile-reachable extras in
-     * `mobileNav.moreExtra` instead.
+     * Persistent, shell-owned header actions (timer, notifications, a global `SyncButton`) — DECLARED
+     * DATA, not a `ReactNode` slot, so basalt owns the mobile projection: the first two ride the bar,
+     * the rest fold into the header's single kebab (`mobile: 'bar' | 'more' | 'hidden'`, see
+     * `GlobalAction`). That kebab is the SAME one `PageBar`'s ROW 1 opens — a route whose bar has
+     * row-1 actions (or `filtersEnd`) lends it, any other route gets it from the shell. An
+     * `ActionGroup` a consumer mounts in some other home never inherits these rows.
+     */
+    globalActions?: GlobalAction[];
+    /**
+     * Sidebar blocks — DECLARED DATA (law C13, `docs/CONTROLS-SPEC.md` §2.3), which replaced both
+     * `sidebarNavExtra` and `mobileNav.moreExtra`. `placement: 'nav'` (the default for `list` and
+     * `custom`) appends after the nav sections inside the scroll region; `'bottom'` pins above the
+     * settings footer.
+     *
+     * Because they are data, basalt owns the projections the two `ReactNode` slots could not express:
+     * a `list` with a `count` becomes a dot on its icon in the collapsed rail, a `progress` block
+     * becomes a ring on the settings row, and a block with `mobile: 'more'` becomes one More-sheet
+     * row opening a nested sheet of its items. A `kind: 'custom'` block is desktop-only, exactly as
+     * `sidebarNavExtra` was.
+     */
+    sidebarBlocks?: SidebarBlock[];
+    /**
+     * Entries appended to the sidebar settings footer — flat link rows at three or fewer, one gear
+     * menu at four or more (`AppSidebarProps.settingsMenuItems` documents the threshold).
      */
-    sidebarNavExtra?: ReactNode;
-    /** Entries appended to the sidebar settings menu. */
     settingsMenuItems?: SettingsMenuItem[];
     /**
-     * Optional account row rendered above the settings menu in the sidebar footer (see
+     * Forces the footer form instead of taking the count rule above: `'flat'` always renders link
+     * rows, `'menu'` always renders the gear dropdown. `'auto'` (the default) is today's ≤3 → flat
+     * behaviour. Reach for it when the rows are CONTROLS rather than destinations — three of those
+     * (a theme radio group, a devtools switch) read as a widget pile in the footer even though the
+     * count says flat. Full rationale on `AppSidebarProps.settingsMenu`.
+     *
+     * @default 'auto'
+     */
+    settingsMenu?: 'auto' | 'flat' | 'menu';
+    /**
+     * Optional account row rendered below the settings menu in the sidebar footer (see
      * `SidebarAccount` / `BasaltAccountProps`). Omitting it reproduces today's footer unchanged.
      */
     account?: BasaltAccountProps;
     /**
      * Optional search field below the brand in the sidebar (fixed, above the nav scroll). Supply
-     * `onOpen`, e.g. `() => openSpotlight()` from basalt-ui/commands.
+     * `onOpen`, e.g. `() => openSpotlight()` from basalt-ui/commands. `actions` adds one or two
+     * icon-only buttons to the right of that row (a tuple by type — see `SidebarSearchActions`).
      */
-    search?: SidebarSearchConfig;
+    search?: SidebarSearchConfig & {
+        actions?: SidebarSearchActions;
+    };
     /**
      * localStorage key for the persisted sidebar-collapsed flag. Ignored when `collapsed` is set.
      *
@@ -92,5 +126,5 @@ export type BasaltShellProps = {
     /** Page content. */
     children?: ReactNode;
 };
-export declare function BasaltShell({ brand, sections, mobileNav, globalActions, sidebarNavExtra, settingsMenuItems, storageKey, collapsed: collapsedProp, onCollapsedChange, account, search, children, }: BasaltShellProps): import("react").JSX.Element;
+export declare function BasaltShell({ brand, sections, mobileNav, globalActions, sidebarBlocks, settingsMenuItems, settingsMenu, storageKey, collapsed: collapsedProp, onCollapsedChange, account, search, children, }: BasaltShellProps): import("react").JSX.Element;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shell/index.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shell/index.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAOlD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AACjF,OAAO,KAAK,EACV,eAAe,EAEf,YAAY,EAEZ,cAAc,EACf,MAAM,cAAc,CAAA;AAMrB,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EACL,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACtD,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjE,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,uBAAuB,EACvB,uBAAuB,EACvB,eAAe,GAChB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAEvD;;;;GAIG;AACH,YAAY,EACV,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,cAAc,EACd,aAAa,EACb,gBAAgB,GACjB,MAAM,cAAc,CAAA;AAErB,gEAAgE;AAChE,MAAM,MAAM,WAAW,GAAG;IACxB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAA;CAClC,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;OAGG;IACH,KAAK,EAAE,WAAW,GAAG;QAAE,IAAI,CAAC,EAAE,eAAe,EAAE,CAAA;KAAE,CAAA;IACjD,mGAAmG;IACnG,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,YAAY,EAAE,CAAA;IAC9B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,YAAY,EAAE,CAAA;IAC9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAA;IACtC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAA;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,mBAAmB,GAAG;QAAE,OAAO,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAA;IACjE;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAA;IAChD,oBAAoB;IACpB,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAgGD,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,QAAQ,EACR,SAAS,EACT,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,UAAuC,EACvC,SAAS,EAAE,aAAa,EACxB,iBAAiB,EACjB,OAAO,EACP,MAAM,EACN,QAAQ,GACT,EAAE,gBAAgB,+BAiGlB"}

package/dist/shell/index.js

@@ -1,18 +1,21 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-import { AppShell } from "@mantine/core";
-import { useMemo } from "react";
+import { AppShell, Box } from "@mantine/core";
+import { Fragment, useMemo } from "react";
 import { AppSidebar } from "./app-sidebar.js";
 import { MobileNav, accountRowCount } from "./app-mobile-nav.js";
-import { projectMobileNav } from "./mobile-nav-model.js";
+import { blockRowCount, projectMobileNav } from "./mobile-nav-model.js";
 import { AppBreadcrumbs } from "./app-breadcrumbs.js";
-import { PageActionsOutlet, PageHeaderProvider } from "./page-header.js";
-import { useBasaltSpacing } from "../theme/index.js";
+import { PageBarOutlet, PageBarProvider, usePageKebabClaimed } from "./page-bar.js";
+import { OverflowMenu, globalActionAsBarAction, globalActionMobile } from "../controls/actions.js";
+import { CtlSlot, useBasaltSpacing } from "../theme/index.js";
 import { createPersistedState } from "../state.js";
 import headerClasses from "./app-header.module.css";
 import mobileNavClasses from "./app-mobile-nav.module.css";
 import { AppSidebar as AppSidebar2 } from "./app-sidebar.js";
 import { NavCountBadge } from "./nav-count-badge.js";
-import { SidebarSearch } from "./sidebar-search.js";
+import {
+  SidebarSearch
+} from "./sidebar-search.js";
 import { SidebarAccount } from "./app-sidebar-account.js";
 import { MobileNav as MobileNav2 } from "./app-mobile-nav.js";
 import {
@@ -22,7 +25,7 @@ import {
   MOBILE_MORE_KEY
 } from "./mobile-nav-model.js";
 import { AppBreadcrumbs as AppBreadcrumbs2 } from "./app-breadcrumbs.js";
-import { PageHeaderProvider as PageHeaderProvider2, PageActions, PageActionsOutlet as PageActionsOutlet2 } from "./page-header.js";
+import { PageBar } from "./page-bar.js";
 function findActiveCrumb(sections) {
   for (const section of sections) {
     const found = findActiveWithParent(section.items);
@@ -74,8 +77,9 @@ function BasaltShell({
   sections,
   mobileNav,
   globalActions,
-  sidebarNavExtra,
+  sidebarBlocks,
   settingsMenuItems,
+  settingsMenu,
   storageKey = "basalt-sidebar-collapsed",
   collapsed: collapsedProp,
   onCollapsedChange,
@@ -93,18 +97,19 @@ function BasaltShell({
     onCollapsedChange?.(next);
   };
   const activeCrumb = findActiveCrumb(sections);
-  const extraMoreRows = accountRowCount(account) + (settingsMenuItems?.length ?? 0) + (mobileNav?.moreExtra ? 1 : 0);
+  const extraMoreRows = accountRowCount(account) + (settingsMenuItems?.length ?? 0) + blockRowCount(sidebarBlocks);
   const model = useMemo(
     () => projectMobileNav(sections, { config: mobileNav, extraMoreRows }),
     [sections, mobileNav, extraMoreRows]
   );
-  return /* @__PURE__ */ jsx(PageHeaderProvider, { children: /* @__PURE__ */ jsxs(
+  return /* @__PURE__ */ jsx(PageBarProvider, { globalActions: globalActions ?? [], children: /* @__PURE__ */ jsxs(
     AppShell,
     {
       h: "100dvh",
       layout: "alt",
       header: {
-        height: { base: step.appShellHeaderMobileHeight, sm: step.appShellHeaderHeight }
+        // ONE height at every width (law C14): nothing reserves a second mobile row any more.
+        height: step.appShellHeaderHeight
       },
       navbar: {
         width: {
@@ -120,8 +125,8 @@ function BasaltShell({
       children: [
         /* @__PURE__ */ jsx(AppShell.Header, { px: "md", withBorder: false, children: /* @__PURE__ */ jsxs("div", { className: headerClasses.bar, children: [
           /* @__PURE__ */ jsx("div", { className: headerClasses.lead, children: /* @__PURE__ */ jsx(AppBreadcrumbs, { ...activeCrumb }) }),
-          /* @__PURE__ */ jsx(PageActionsOutlet, { className: headerClasses.pageActions }),
-          globalActions && /* @__PURE__ */ jsx("div", { className: headerClasses.global, children: globalActions })
+          /* @__PURE__ */ jsx(PageBarOutlet, { className: headerClasses.pageBar }),
+          /* @__PURE__ */ jsx(HeaderGlobalActions, { actions: globalActions ?? [] })
         ] }) }),
         /* @__PURE__ */ jsx(AppShell.Navbar, { p: 0, withBorder: false, children: /* @__PURE__ */ jsx(
           AppSidebar,
@@ -130,8 +135,9 @@ function BasaltShell({
             sections,
             collapsed,
             onToggleCollapse: toggleCollapse,
-            navExtra: sidebarNavExtra,
+            ...sidebarBlocks !== void 0 && { blocks: sidebarBlocks },
             ...settingsMenuItems !== void 0 && { settingsMenuItems },
+            ...settingsMenu !== void 0 && { settingsMenu },
             ...account !== void 0 && { account },
             ...search !== void 0 && { search }
           }
@@ -143,13 +149,31 @@ function BasaltShell({
             model,
             config: mobileNav,
             ...account !== void 0 && { account },
-            ...settingsMenuItems !== void 0 && { settingsMenuItems }
+            ...settingsMenuItems !== void 0 && { settingsMenuItems },
+            ...sidebarBlocks !== void 0 && { blocks: sidebarBlocks }
           }
         ) })
       ]
     }
   ) });
 }
+function HeaderGlobalActions({ actions }) {
+  const kebabClaimed = usePageKebabClaimed();
+  if (actions.length === 0) return null;
+  const more = actions.filter((action, index) => globalActionMobile(action, index) === "more").map(globalActionAsBarAction);
+  return (
+    // `CtlSlot` here for the same reason a home wraps its own slot (law C5): `globalActions` are
+    // consumer NODES, so basalt cannot pass them a size — it can only provide the tier they resolve
+    // against. Without it a `<NotificationBell/>`'s internal `ActionIcon` fell back to Mantine's
+    // `md` (28px) beside a 30px page group.
+    /* @__PURE__ */ jsx(CtlSlot, { children: /* @__PURE__ */ jsxs("div", { className: headerClasses.global, children: [
+      actions.map(
+        (action, index) => globalActionMobile(action, index) === "bar" ? /* @__PURE__ */ jsx(Fragment, { children: action.node }, action.key) : /* @__PURE__ */ jsx(Box, { visibleFrom: "sm", children: action.node }, action.key)
+      ),
+      !kebabClaimed && more.length > 0 && /* @__PURE__ */ jsx(Box, { hiddenFrom: "sm", children: /* @__PURE__ */ jsx(OverflowMenu, { actions: more, trigger: "kebab", label: "More actions" }) })
+    ] }) })
+  );
+}
 export {
   AppBreadcrumbs2 as AppBreadcrumbs,
   AppSidebar2 as AppSidebar,
@@ -159,9 +183,7 @@ export {
   MOBILE_MORE_KEY,
   MobileNav2 as MobileNav,
   NavCountBadge,
-  PageActions,
-  PageActionsOutlet2 as PageActionsOutlet,
-  PageHeaderProvider2 as PageHeaderProvider,
+  PageBar,
   SidebarAccount,
   SidebarSearch,
   projectMobileNav2 as projectMobileNav

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

@@ -13,7 +13,7 @@
  * ever rendering below the fold (6 x 44px + 8px padding = 272px against 415px of headroom on the
  * smallest supported viewport), so past that the surface becomes a bottom sheet.
  */
-import type { MobileNavConfig, MobileNavModel, SidebarSection } from '../nav/types.js';
+import type { MobileNavConfig, MobileNavModel, SidebarBlock, SidebarSection } from '../nav/types.js';
 /** Hard cap on bar slots, INCLUDING More. Five 72px slots is the widest a 360px viewport holds. */
 export declare const MOBILE_MAX_TABS_DEFAULT = 5;
 /**
@@ -27,12 +27,23 @@ export declare const MOBILE_MORE_KEY = "__more";
 export type ProjectMobileNavOptions = {
     config?: MobileNavConfig | undefined;
     /**
-     * Extra rows the More surface will hold — account + settings + `moreExtra`. Drives both
+     * Extra rows the More surface will hold — account + settings + sidebar blocks. Drives both
      * `needsMore` and the menu-vs-sheet threshold. The model cannot see those rows (they are
      * Mantine-rendered chrome, not `SidebarItem`s), so the shell counts them and passes the total.
      */
     extraMoreRows?: number;
 };
+/**
+ * How many More-surface rows `blocks` contribute — the `accountRowCount` sibling for sidebar
+ * blocks, and for the same reason: `BasaltShell` needs the number BEFORE the projection runs (it
+ * feeds `extraMoreRows`, which picks `menu` vs `sheet` against `menuMax`) while the renderer is
+ * what decides how many rows a block actually becomes.
+ *
+ * ONE row per block, never one per item: a list block projects to a single `Awaiting action · 3`
+ * row that opens a nested sheet of its items. Counting the items instead would push a 12-item
+ * block's More surface to a sheet on the strength of rows that surface never paints.
+ */
+export declare function blockRowCount(blocks: readonly SidebarBlock[] | undefined): number;
 /**
  * Projects `sections` onto the bar. Implements §2.3's thirteen rules in order, and is the ONLY
  * place slot selection happens — `MobileNav` receives a finished model and paints it.

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

@@ -1 +1 @@
-{"version":3,"file":"mobile-nav-model.d.ts","sourceRoot":"","sources":["../../src/shell/mobile-nav-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EAId,cAAc,EACf,MAAM,cAAc,CAAA;AAErB,mGAAmG;AACnG,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,iGAAiG;AACjG,eAAO,MAAM,eAAe,WAAW,CAAA;AAEvC,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACpC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAoQD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,EAAE,EAC1B,IAAI,CAAC,EAAE,uBAAuB,GAC7B,cAAc,CA2EhB"}
+{"version":3,"file":"mobile-nav-model.d.ts","sourceRoot":"","sources":["../../src/shell/mobile-nav-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EAGd,YAAY,EAEZ,cAAc,EACf,MAAM,cAAc,CAAA;AAGrB,mGAAmG;AACnG,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,iGAAiG;AACjG,eAAO,MAAM,eAAe,WAAW,CAAA;AAEvC,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACpC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,GAAG,MAAM,CAQjF;AAgSD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,EAAE,EAC1B,IAAI,CAAC,EAAE,uBAAuB,GAC7B,cAAc,CA2EhB"}

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

@@ -1,6 +1,14 @@
+import { sidebarBlockMobile } from "./sidebar-block-model.js";
 const MOBILE_MAX_TABS_DEFAULT = 5;
 const MOBILE_MENU_MAX_DEFAULT = 6;
 const MOBILE_MORE_KEY = "__more";
+function blockRowCount(blocks) {
+  if (blocks === void 0) return 0;
+  return blocks.filter((block) => {
+    if (sidebarBlockMobile(block) !== "more") return false;
+    return block.kind !== "list" || block.items.length > 0;
+  }).length;
+}
 const DEV = process.env["NODE_ENV"] !== "production";
 function placementOf(item, sectionHidden) {
   if (sectionHidden) return "hidden";
@@ -17,6 +25,9 @@ function hasActiveDestination(item) {
   if (item.active) return true;
   return item.children?.some(hasActiveDestination) ?? false;
 }
+function isActiveDestination(item) {
+  return item.active === true;
+}
 function countRows(items) {
   return items.reduce((total, item) => total + 1 + countRows(item.children ?? []), 0);
 }
@@ -51,13 +62,15 @@ function itemCandidate(item) {
   return {
     key: item.key,
     covered: /* @__PURE__ */ new Set([item.key]),
+    // `isActiveDestination`, not the rollup: this slot COVERS one key, so it reads one key
+    // (`hasActiveDestination`'s doc has the whole accounting).
     toSlot: () => ({
       kind: "link",
       key: item.key,
       label: item.label,
       short: item.short ?? item.label,
       icon: item.icon,
-      active: hasActiveDestination(item),
+      active: isActiveDestination(item),
       item
     })
   };
@@ -240,5 +253,6 @@ export {
   MOBILE_MAX_TABS_DEFAULT,
   MOBILE_MENU_MAX_DEFAULT,
   MOBILE_MORE_KEY,
+  blockRowCount,
   projectMobileNav
 };

package/dist/shell/nav-count-badge.d.ts

@@ -1,5 +1,5 @@
 /**
- * Sidebar nav count badge (docs/DESIGN-SPEC.md §5): mono 10.5px, ink-8% bg, radius 5, height 16,
+ * Sidebar nav count badge (docs/DESIGN-SPEC.md §5): mono micro (11px), ink-8% bg, radius 5, height 16,
  * padding 0 5px, muted text; `marginLeft: auto` pins it to the row end on any render path.
  * `styles` (inline) rather than a token color prop, since none of Mantine's variant/color
  * combinations land on the ink-tint idiom. Returns `null` for a zero/empty count so the badge slot

package/dist/shell/page-bar.d.ts

@@ -0,0 +1,51 @@
+import type { ReactNode } from 'react';
+import type { ActionGroupProps, BarAction, GlobalAction } from '../controls/actions.js';
+import type { SyncButtonProps } from '../controls/sync-button.js';
+/** The custom property row 2's measured height is published on. */
+export declare const PAGE_BAR_HEIGHT_VAR = "--basalt-page-bar-h";
+/**
+ * Internal — mounted by `BasaltShell`. Owns the portal target, and the single-kebab claim that
+ * lets the shell fall back to its OWN kebab on a route that renders no `PageBar`.
+ */
+export declare function PageBarProvider({ globalActions, children, }: {
+    globalActions: readonly GlobalAction[];
+    children: ReactNode;
+}): ReactNode;
+/** Internal — the app-shell header node the active page's row 1 portals into. */
+export declare function PageBarOutlet({ className }: {
+    className?: string;
+}): import("react").JSX.Element;
+/** Internal — `true` while a page's `ActionGroup` owns the header's one mobile kebab. */
+export declare function usePageKebabClaimed(): boolean;
+export type PageBarProps = {
+    /**
+     * Read only when there is no `BasaltShell` outlet (a shell-less app such as linewatch). Inside a
+     * shell the breadcrumb names the page and this is ignored.
+     */
+    title?: string;
+    icon?: ReactNode;
+    actions?: ActionGroupProps;
+    /** `scope` is fixed to `'page'` — a global sync belongs in the shell's `globalActions` (law C12). */
+    sync?: Omit<SyncButtonProps, 'scope'>;
+    /** `FilterSet` descendants only (law C1). */
+    filters?: ReactNode;
+    /** Right-aligned row-2 actions ("Manage metrics"). */
+    filtersEnd?: BarAction[];
+    /** One `ViewTabs`. */
+    tabs?: ReactNode;
+    /**
+     * Added to the bar's ROOT — the shell-less `<div data-basalt-page-bar="standalone">`, or row 2's
+     * sticky wrapper (`data-basalt-page-bar="shell"`) inside a `BasaltShell`. The seam for the two
+     * things only the consumer's own layout knows: bleeding the sticky bar across its container's
+     * gutters (`margin-inline: calc(var(--gutter) * -1); padding-inline: var(--gutter)`) and drawing
+     * a hairline under it (`border-bottom: 1px solid var(--vx-surface-hairline)`).
+     *
+     * Scope that CSS through this class, not through a global `[data-basalt-page-bar]` selector: the
+     * data attributes are stable enough to READ (a shell-less consumer can style
+     * `[data-basalt-page-bar="standalone"]` in a pinch, and this doc is the promise that the value
+     * stays), but a global rule reaches every page in the app including the ones that want neither.
+     */
+    className?: string;
+};
+export declare function PageBar({ title, icon, actions, sync, filters, filtersEnd, tabs, className, }: PageBarProps): ReactNode;
+//# sourceMappingURL=page-bar.d.ts.map

package/dist/shell/page-bar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-bar.d.ts","sourceRoot":"","sources":["../../src/shell/page-bar.tsx"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,OAAO,CAAA;AAKjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAG9D,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,wBAAwB,CAAA;AA0BxD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAC9B,aAAa,EACb,QAAQ,GACT,EAAE;IACD,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;IACtC,QAAQ,EAAE,SAAS,CAAA;CACpB,GAAG,SAAS,CA2BZ;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,EAAE,SAAS,EAAE,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,+BAGlE;AAED,yFAAyF;AACzF,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED,MAAM,MAAM,YAAY,GAAG;IACzB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,OAAO,CAAC,EAAE,gBAAgB,CAAA;IAC1B,qGAAqG;IACrG,IAAI,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAA;IACrC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,sDAAsD;IACtD,UAAU,CAAC,EAAE,SAAS,EAAE,CAAA;IACxB,sBAAsB;IACtB,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AA2DD,wBAAgB,OAAO,CAAC,EACtB,KAAK,EACL,IAAI,EACJ,OAAO,EACP,IAAI,EACJ,OAAO,EACP,UAAU,EACV,IAAI,EACJ,SAAS,GACV,EAAE,YAAY,GAAG,SAAS,CAmG1B"}

package/dist/shell/page-bar.js

@@ -0,0 +1,154 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState
+} from "react";
+import { createPortal } from "react-dom";
+import { CtlSlot } from "../theme/index.js";
+import { BarActionRow, BarExtrasProvider, globalActionAsBarAction } from "../controls/actions.js";
+import { SyncButton } from "../controls/sync-button.js";
+import classes from "./page-bar.module.css";
+const PAGE_BAR_HEIGHT_VAR = "--basalt-page-bar-h";
+const NO_SLOTS = {
+  target: null,
+  setTarget: () => {
+  },
+  inShell: false,
+  mobileMoreActions: [],
+  kebabClaims: 0,
+  claimKebab: () => () => {
+  }
+};
+const PageBarContext = createContext(NO_SLOTS);
+function PageBarProvider({
+  globalActions,
+  children
+}) {
+  const [target, setTarget] = useState(null);
+  const [kebabClaims, setKebabClaims] = useState(0);
+  const claimKebab = useCallback(() => {
+    setKebabClaims((n) => n + 1);
+    return () => setKebabClaims((n) => n - 1);
+  }, []);
+  const mobileMoreActions = globalActions.filter((action, index) => (action.mobile ?? (index < 2 ? "bar" : "more")) === "more").map(globalActionAsBarAction);
+  const value = {
+    target,
+    setTarget,
+    inShell: true,
+    mobileMoreActions,
+    kebabClaims,
+    claimKebab
+  };
+  return /* @__PURE__ */ jsx(PageBarContext.Provider, { value, children: /* @__PURE__ */ jsx(BarExtrasProvider, { value: { mobileMoreActions, claimKebab }, children }) });
+}
+function PageBarOutlet({ className }) {
+  const { setTarget } = useContext(PageBarContext);
+  return /* @__PURE__ */ jsx("div", { ref: setTarget, className });
+}
+function usePageKebabClaimed() {
+  return useContext(PageBarContext).kebabClaims > 0;
+}
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+function useMeasuredHeightVar(active) {
+  const ref = useRef(null);
+  useIsomorphicLayoutEffect(() => {
+    const node = ref.current;
+    if (!active || node === null) return;
+    const publish = () => {
+      const { height } = node.getBoundingClientRect();
+      if (height > 0) {
+        document.documentElement.style.setProperty(PAGE_BAR_HEIGHT_VAR, `${height}px`);
+      }
+    };
+    publish();
+    if (typeof ResizeObserver === "undefined") {
+      return () => document.documentElement.style.removeProperty(PAGE_BAR_HEIGHT_VAR);
+    }
+    const observer = new ResizeObserver(publish);
+    observer.observe(node);
+    return () => {
+      observer.disconnect();
+      document.documentElement.style.removeProperty(PAGE_BAR_HEIGHT_VAR);
+    };
+  }, [active]);
+  return ref;
+}
+function rootClass(own, extra) {
+  return [own, extra].filter(Boolean).join(" ");
+}
+function PageBar({
+  title,
+  icon,
+  actions,
+  sync,
+  filters,
+  filtersEnd,
+  tabs,
+  className
+}) {
+  const { target, inShell } = useContext(PageBarContext);
+  const filtersEndActions = filtersEnd ?? [];
+  const hasRow2 = tabs !== void 0 || filters !== void 0 || filtersEndActions.length > 0;
+  const hasLead = !inShell && (title !== void 0 || icon !== void 0);
+  const hasRow1 = actions !== void 0 || sync !== void 0 || hasLead || filtersEndActions.length > 0;
+  const measureRef = useMeasuredHeightVar(hasRow2 || !inShell && hasRow1);
+  const row1 = hasRow1 ? /* @__PURE__ */ jsxs("div", { className: classes.row1, children: [
+    hasLead && /* @__PURE__ */ jsxs("div", { className: classes.lead, children: [
+      icon !== void 0 && /* @__PURE__ */ jsx("span", { className: classes.icon, "aria-hidden": true, children: icon }),
+      title !== void 0 && /* @__PURE__ */ jsx("h1", { className: classes.title, children: title })
+    ] }),
+    /* @__PURE__ */ jsx("div", { className: classes.row1End, children: (actions !== void 0 || filtersEndActions.length > 0 || sync !== void 0) && /* @__PURE__ */ jsx(CtlSlot, { children: /* @__PURE__ */ jsx(
+      BarActionRow,
+      {
+        ...actions,
+        host: "page",
+        mobileOnly: filtersEndActions,
+        ...sync !== void 0 && { syncNode: /* @__PURE__ */ jsx(SyncButton, { ...sync, scope: "page" }) }
+      }
+    ) }) })
+  ] }) : null;
+  const row2 = hasRow2 ? /* @__PURE__ */ jsxs("div", { className: classes.row2, children: [
+    tabs !== void 0 && /* @__PURE__ */ jsx(CtlSlot, { children: tabs }),
+    filters !== void 0 && /* @__PURE__ */ jsx("div", { className: classes.filters, children: /* @__PURE__ */ jsx(CtlSlot, { children: filters }) }),
+    filtersEndActions.length > 0 && /* @__PURE__ */ jsx("div", { className: classes.filtersEnd, children: /* @__PURE__ */ jsx(CtlSlot, { children: /* @__PURE__ */ jsx(BarActionRow, { secondary: filtersEndActions, host: "slot", viewport: "desktop" }) }) })
+  ] }) : null;
+  if (!inShell) {
+    if (row1 === null && row2 === null) return null;
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref: measureRef,
+        className: rootClass(classes.bar, className),
+        "data-basalt-page-bar": "standalone",
+        children: [
+          row1,
+          row2
+        ]
+      }
+    );
+  }
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    row1 !== null && target !== null && createPortal(row1, target),
+    row2 !== null && /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref: measureRef,
+        className: rootClass(classes.row2Sticky, className),
+        "data-basalt-page-bar": "shell",
+        children: row2
+      }
+    )
+  ] });
+}
+export {
+  PAGE_BAR_HEIGHT_VAR,
+  PageBar,
+  PageBarOutlet,
+  PageBarProvider,
+  usePageKebabClaimed
+};