basalt-ui 1.24.0 → 1.26.0

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-border)`).
+     *
+     * 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
+};

package/dist/shell/page-bar.module.css

@@ -0,0 +1,178 @@
+/*
+ * `PageBar` layout (docs/CONTROLS-SPEC.md §2.1).
+ *
+ * Law C7 in CSS form: `flex-wrap: nowrap` on every row and NO `overflow-x` anywhere. A home that
+ * scrolls sideways hides its own controls; the fold is computed instead — `More` for actions
+ * (`ActionGroup`), a `Filters (n)` sheet for filters (`FilterSet`'s job, wave 4). The filter
+ * container below only supplies `min-width: 0` so that fold has a box to measure against.
+ */
+
+/* The shell-less bar: both rows, sticky at the top of the document. One layer under the AppShell
+ * header (`--app-shell-header-z-index`, default 100) so it never wins a stacking fight with ordinary
+ * in-flow content — Mantine's Input section, Indicator, sticky table headers, and Slider thumbs all
+ * sit at `z-index: 1` or higher, which used to paint over a bare `z-index: 1` bar while scrolling. */
+.bar {
+  position: sticky;
+  top: 0;
+  z-index: calc(var(--app-shell-header-z-index, 100) - 1);
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-xs);
+  background-color: var(--vx-surface-bg);
+}
+
+/*
+ * Row 2 inside a shell: in the page flow, sticky under the 48px header. `--app-shell-header-height`
+ * is Mantine's own AppShell variable, so the offset tracks the header at any density with no React
+ * state and no measurement. `z-index` sits one layer below the header itself (see `.bar` above) —
+ * high enough to stay above ordinary page content, never above the AppShell header.
+ */
+.row2Sticky {
+  position: sticky;
+  top: var(--app-shell-header-height, 0px);
+  z-index: calc(var(--app-shell-header-z-index, 100) - 1);
+  background-color: var(--vx-surface-bg);
+}
+
+.row1 {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  min-width: 0;
+  min-height: var(--vx-space-page-bar-row-height);
+}
+
+.lead {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  flex-shrink: 0;
+  min-width: 0;
+}
+
+.icon {
+  display: inline-flex;
+  align-items: center;
+  color: var(--vx-muted);
+}
+
+/*
+ * The shell-less page title (law C8: the breadcrumb names the page inside a shell, this does it
+ * outside one). Head-font treatment, same 88%/550 as every `WidgetHeader` title.
+ */
+.title {
+  margin: 0;
+  font-family: var(--basalt-font-head);
+  font-size: var(--vx-text-xl);
+  font-weight: 550;
+  font-stretch: 88%;
+  color: var(--vx-ink);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/*
+ * Icons inside a row-1 button are 16px and sit 6px from their label. Mantine spends
+ * `--mantine-spacing-xs` (11px) on a Button's section gap regardless of the size tier, which is the
+ * BODY tier's number — at 30px it detached the glyph from the word it belongs to. Scoped to the row
+ * rather than themed on `Button` globally: a `size="md"` button in a form still wants Mantine's gap.
+ */
+.row1 :global(.mantine-Button-section[data-position='left']),
+.row2 :global(.mantine-Button-section[data-position='left']) {
+  margin-inline-end: var(--vx-space-control-gap);
+}
+
+.row1 :global(.mantine-Button-section) > svg,
+.row1 :global(.mantine-ActionIcon-root) > svg {
+  width: 1rem;
+  height: 1rem;
+}
+
+/* Actions and sync are right-aligned; the lead (or the breadcrumb, in a shell) holds the left. */
+.row1End {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--vx-space-control-gap);
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+/*
+ * Row 2's rhythm is 8px · pills · 8px, NOT a 40px reserved row.
+ *
+ * `min-height: var(--vx-space-page-bar-row-height)` (40px) left a 30px pill floating inside a 40px
+ * box with the 5px above and below it belonging to nothing — and because the row sat in a `Stack`
+ * that already spaced it, the visible gap between the header and the pills read as ~19px while the
+ * gap from the pills to the first card read as ~19px too. Symmetric padding on the row itself is the
+ * same total height (46px vs 40px) with both halves owned by one declaration, so the sticky bar's
+ * published height covers exactly the band it paints.
+ */
+.row2 {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  min-width: 0;
+  padding-block: var(--vx-space-stack-sm);
+}
+
+.filters {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.filtersEnd {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  margin-inline-start: auto;
+  flex-shrink: 0;
+}
+
+/*
+ * Law C15 — every touch target inside a home is at least `touchControlHeight` (36px at level 0)
+ * below `sm`, while the VISIBLE box stays the 30px `ctl` tier. `::after` and not `::before`:
+ * Mantine's Button owns `::before` for its loading overlay (`@mantine/core/styles/Button.css`),
+ * so a hit area drawn there would fight it. `pointer-events` stays default so the overlay is the
+ * one receiving the tap.
+ *
+ * `overflow: visible` is LOAD-BEARING, not tidying. Mantine's Button and ActionIcon roots both set
+ * `overflow: hidden` (`Button.css`, `ActionIcon.css`), which clips an overlay that by definition
+ * extends past the 30px box — so without this the 36px target simply does not exist and a tap 3px
+ * above the control misses. What `overflow: hidden` buys those roots is clipping the loading
+ * overlay's blur, and that overlay is only painted under `[data-loading]`, which is excluded below.
+ */
+@media (max-width: 47.99375em) {
+  .row1 :is(button, a),
+  .row2 :is(button, a) {
+    position: relative;
+  }
+
+  .row1 :is(button, a):not([data-loading]),
+  .row2 :is(button, a):not([data-loading]) {
+    overflow: visible;
+  }
+
+  .row1 :is(button, a)::after,
+  .row2 :is(button, a)::after {
+    content: '';
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    translate: -50% -50%;
+    width: 100%;
+    height: 100%;
+    min-width: var(--vx-space-touch-control-height);
+    min-height: var(--vx-space-touch-control-height);
+  }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * 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 bar: string
+  readonly row2Sticky: string
+  readonly row1: string
+  readonly lead: string
+  readonly icon: string
+  readonly title: string
+  readonly row2: string
+  readonly row1End: string
+  readonly filters: string
+  readonly filtersEnd: string
+}
+export default classes

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

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

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

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