basalt-ui 1.18.0 → 1.19.0

package/dist/shell/index.js

@@ -1,44 +1,28 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-import { AppShell, Badge } from "@mantine/core";
-import { useDisclosure, useLocalStorage } from "@mantine/hooks";
+import { AppShell } from "@mantine/core";
+import { useLocalStorage } from "@mantine/hooks";
+import { useMemo } from "react";
 import { AppSidebar } from "./app-sidebar.js";
-import { MobileNav } from "./app-mobile-nav.js";
+import { MobileNav, accountRowCount } from "./app-mobile-nav.js";
+import { projectMobileNav } from "./mobile-nav-model.js";
 import { AppBreadcrumbs } from "./app-breadcrumbs.js";
 import { PageActionsOutlet, PageHeaderProvider } from "./page-header.js";
-import { VX } from "../tokens/index.js";
 import { useBasaltSpacing } from "../theme/index.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 { SidebarAccount } from "./app-sidebar-account.js";
+import { MobileNav as MobileNav2 } from "./app-mobile-nav.js";
 import {
-  MobileNav as MobileNav2
-} from "./app-mobile-nav.js";
+  projectMobileNav as projectMobileNav2,
+  MOBILE_MAX_TABS_DEFAULT,
+  MOBILE_MENU_MAX_DEFAULT,
+  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";
-function NavCountBadge({ count }) {
-  if (!count) return null;
-  return /* @__PURE__ */ jsx(
-    Badge,
-    {
-      size: "sm",
-      styles: {
-        root: {
-          backgroundColor: "color-mix(in srgb, var(--vx-ink) 8%, transparent)",
-          color: "var(--vx-muted)",
-          fontFamily: "var(--basalt-font-mono)",
-          fontSize: VX.text.micro,
-          fontWeight: 500,
-          height: 16,
-          padding: "0 5px",
-          marginLeft: "auto",
-          borderRadius: "var(--vx-radius-tight)"
-        }
-      },
-      children: count
-    }
-  );
-}
 function findActiveCrumb(sections) {
   for (const section of sections) {
     const found = findActiveWithParent(section.items);
@@ -46,67 +30,38 @@ function findActiveCrumb(sections) {
       return {
         section: section.label,
         parent: found.parent,
+        parentAnchor: found.parentAnchor,
         parentHref: found.parentHref,
         page: found.page
       };
   }
   return void 0;
 }
-function findActiveWithParent(items, parentLabel, parentHref) {
+function findActiveWithParent(items, parentLabel, parentAnchor, parentHref) {
   for (const item of items) {
     if (item.children) {
-      const found = findActiveWithParent(item.children, item.label, item.href);
+      const found = findActiveWithParent(item.children, item.label, item.Anchor, item.href);
       if (found) return found;
     }
-    if (item.active) return { parent: parentLabel, parentHref, page: item.label };
+    if (item.active) return { parent: parentLabel, parentAnchor, parentHref, page: item.label };
   }
   return void 0;
 }
-function toMobileSections(sections, closeMobile) {
-  return sections.filter((s) => s.mobileTab !== false).map((s) => ({
-    key: s.label,
-    label: s.label,
-    icon: s.icon,
-    active: s.items.some((i) => i.active),
-    items: flattenSidebarItems(s.items).map(
-      (i) => ({
-        key: i.key,
-        label: i.label,
-        icon: i.icon,
-        ...i.href !== void 0 && { href: i.href },
-        ...i.active !== void 0 && { active: i.active },
-        onClick: (e) => {
-          i.onClick?.(e);
-          closeMobile();
-        }
-      })
-    )
-  }));
-}
-function flattenSidebarItems(items) {
-  return items.flatMap((item) => [
-    item,
-    ...item.children ? flattenSidebarItems(item.children) : []
-  ]);
-}
 function BasaltShell({
   brand,
   sections,
-  renderNavLink,
+  mobileNav,
   globalActions,
-  sidebarFooterExtra,
   sidebarNavExtra,
   settingsMenuItems,
   storageKey = "basalt-sidebar-collapsed",
   collapsed: collapsedProp,
   onCollapsedChange,
-  renderBreadcrumbLink,
   account,
   search,
   children
 }) {
   const { step } = useBasaltSpacing();
-  const [mobileOpened, { toggle: toggleMobile, close: closeMobile }] = useDisclosure();
   const [storedCollapsed, setStoredCollapsed] = useLocalStorage({
     key: storageKey,
     defaultValue: false,
@@ -120,7 +75,11 @@ function BasaltShell({
     onCollapsedChange?.(next);
   };
   const activeCrumb = findActiveCrumb(sections);
-  const mobileSections = toMobileSections(sections, closeMobile);
+  const extraMoreRows = accountRowCount(account) + (settingsMenuItems?.length ?? 0) + (mobileNav?.moreExtra ? 1 : 0);
+  const model = useMemo(
+    () => projectMobileNav(sections, { config: mobileNav, extraMoreRows }),
+    [sections, mobileNav, extraMoreRows]
+  );
   return /* @__PURE__ */ jsx(PageHeaderProvider, { children: /* @__PURE__ */ jsxs(
     AppShell,
     {
@@ -135,13 +94,14 @@ function BasaltShell({
           sm: collapsed ? step.appShellNavbarRailWidth : step.appShellNavbarWidth
         },
         breakpoint: "sm",
-        collapsed: { mobile: !mobileOpened }
+        // No mobile sidebar drawer, ever — the bottom bar is the entire mobile nav.
+        collapsed: { mobile: true }
       },
-      footer: { height: { base: 52, sm: 0 } },
+      footer: { height: { base: step.mobileNavBarHeight, sm: 0 } },
       padding: "sm",
       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, renderBreadcrumbLink }) }),
+          /* @__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 })
         ] }) }),
@@ -152,22 +112,20 @@ function BasaltShell({
             sections,
             collapsed,
             onToggleCollapse: toggleCollapse,
-            onClose: closeMobile,
-            footerExtra: sidebarFooterExtra,
             navExtra: sidebarNavExtra,
-            ...renderNavLink !== void 0 && { renderNavLink },
             ...settingsMenuItems !== void 0 && { settingsMenuItems },
             ...account !== void 0 && { account },
             ...search !== void 0 && { search }
           }
         ) }),
-        /* @__PURE__ */ jsx(AppShell.Main, { children }),
-        /* @__PURE__ */ jsx(AppShell.Footer, { hiddenFrom: "sm", p: 0, children: /* @__PURE__ */ jsx(
+        /* @__PURE__ */ jsx(AppShell.Main, { className: mobileNavClasses.mainSafeArea, children }),
+        /* @__PURE__ */ jsx(AppShell.Footer, { hiddenFrom: "sm", p: 0, withBorder: false, children: /* @__PURE__ */ jsx(
           MobileNav,
           {
-            sections: mobileSections,
-            onOpenMore: toggleMobile,
-            ...renderNavLink !== void 0 && { renderNavLink }
+            model,
+            config: mobileNav,
+            ...account !== void 0 && { account },
+            ...settingsMenuItems !== void 0 && { settingsMenuItems }
           }
         ) })
       ]
@@ -178,11 +136,15 @@ export {
   AppBreadcrumbs2 as AppBreadcrumbs,
   AppSidebar2 as AppSidebar,
   BasaltShell,
+  MOBILE_MAX_TABS_DEFAULT,
+  MOBILE_MENU_MAX_DEFAULT,
+  MOBILE_MORE_KEY,
   MobileNav2 as MobileNav,
   NavCountBadge,
   PageActions,
   PageActionsOutlet2 as PageActionsOutlet,
   PageHeaderProvider2 as PageHeaderProvider,
   SidebarAccount,
-  SidebarSearch
+  SidebarSearch,
+  projectMobileNav2 as projectMobileNav
 };

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

@@ -0,0 +1,41 @@
+/**
+ * The mobile-bar projection — `SidebarSection[]` + `MobileNavConfig` → `MobileNavModel`.
+ *
+ * PURE BY CONTRACT: no React, no Mantine, no DOM, no JSX. Everything the bottom bar decides —
+ * which destinations get a slot, which slot is a plain navigation link and which raises a surface,
+ * whether that surface is a menu or a sheet, what falls into the overflow "More" slot — is decided
+ * here and unit-testable with no renderer. `app-mobile-nav.tsx` only paints the result.
+ *
+ * The law it implements is the interaction model, not a heuristic: a slot is a DESTINATION, so a
+ * tap navigates with no overlay to dismiss. An overlay exists only where a slot genuinely holds
+ * more than one destination, and its surface is INFERRED from how many rows it holds rather than
+ * configured — six rows is the arithmetic ceiling for a menu that pops out of a 56px bar without
+ * 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';
+/** 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;
+/**
+ * Rows a slot may hold before it becomes a sheet instead of a menu. Arithmetic, not taste — see
+ * the module doc: six rows is the last count a bottom-anchored, non-flipping menu fits above the
+ * bar on the smallest supported viewport.
+ */
+export declare const MOBILE_MENU_MAX_DEFAULT = 6;
+/** The overflow slot's reserved key. A slot like any other — it just exists only when needed. */
+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
+     * `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;
+};
+/**
+ * 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.
+ */
+export declare function projectMobileNav(sections: SidebarSection[], opts?: ProjectMobileNavOptions): MobileNavModel;
+//# sourceMappingURL=mobile-nav-model.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,244 @@
+const MOBILE_MAX_TABS_DEFAULT = 5;
+const MOBILE_MENU_MAX_DEFAULT = 6;
+const MOBILE_MORE_KEY = "__more";
+const DEV = process.env["NODE_ENV"] !== "production";
+function placementOf(item, sectionHidden) {
+  if (sectionHidden) return "hidden";
+  const mobile = item.mobile;
+  if (mobile === void 0) return "more";
+  if (mobile === true) return "tab";
+  if (mobile === false) return "hidden";
+  return mobile;
+}
+function isSectionHidden(section) {
+  return section.mobile === false;
+}
+function hasActiveDestination(item) {
+  if (item.active) return true;
+  return item.children?.some(hasActiveDestination) ?? false;
+}
+function countRows(items) {
+  return items.reduce((total, item) => total + 1 + countRows(item.children ?? []), 0);
+}
+function collectKeys(items, out) {
+  for (const item of items) {
+    out.add(item.key);
+    collectKeys(item.children ?? [], out);
+  }
+}
+function flattenItems(items, out) {
+  for (const item of items) {
+    out.push(item);
+    flattenItems(item.children ?? [], out);
+  }
+}
+function pruneTree(items, keep) {
+  const out = [];
+  for (const item of items) {
+    const children = pruneTree(item.children ?? [], keep);
+    if (!keep(item)) {
+      out.push(...children);
+      continue;
+    }
+    const next = { ...item };
+    if (children.length > 0) next.children = children;
+    else delete next.children;
+    out.push(next);
+  }
+  return out;
+}
+function itemCandidate(item) {
+  return {
+    key: item.key,
+    covered: /* @__PURE__ */ new Set([item.key]),
+    toSlot: () => ({
+      kind: "link",
+      key: item.key,
+      label: item.label,
+      short: item.short ?? item.label,
+      icon: item.icon,
+      active: hasActiveDestination(item),
+      item
+    })
+  };
+}
+function sectionCandidate(section, menuMax) {
+  const mobile = section.mobile === false || section.mobile === void 0 ? void 0 : section.mobile;
+  const items = pruneTree(section.items, (item) => placementOf(item, false) !== "hidden");
+  const covered = /* @__PURE__ */ new Set();
+  collectKeys(items, covered);
+  const label = mobile?.label ?? section.label;
+  const rows = countRows(items);
+  const only = items[0];
+  return {
+    key: section.label,
+    covered,
+    toSlot: () => {
+      if (rows === 0) return void 0;
+      if (rows === 1 && only !== void 0 && !only.disabled) {
+        return {
+          kind: "link",
+          key: only.key,
+          label,
+          short: label,
+          // The section's own identity wins when it declares one — the consumer configured the
+          // SLOT — and falls back to the single destination's icon when it does not.
+          icon: mobile?.icon ?? section.icon ?? only.icon,
+          active: hasActiveDestination(only),
+          item: only
+        };
+      }
+      return {
+        kind: rows <= menuMax ? "menu" : "sheet",
+        key: section.label,
+        label,
+        short: label,
+        icon: mobile?.icon ?? section.icon,
+        active: items.some(hasActiveDestination),
+        // One section, so the rows need no group heading — the tab itself names them.
+        groups: [{ key: section.label, items }],
+        isMore: false
+      };
+    }
+  };
+}
+function buildCandidates(sections, config, maxTabs, menuMax) {
+  const flat = [];
+  for (const section of sections) {
+    if (isSectionHidden(section)) continue;
+    flattenItems(section.items, flat);
+  }
+  const tabbable = (item) => {
+    if (!item.disabled) return true;
+    if (DEV) {
+      console.warn(
+        `[basalt] MobileNav: "${item.key}" asks for a bar slot but is disabled \u2014 a disabled destination never becomes a tab. It still renders, disabled, in the More surface.`
+      );
+    }
+    return false;
+  };
+  if (config?.tabs !== void 0) {
+    const candidates2 = [];
+    for (const id of config.tabs) {
+      const item = flat.find((candidate) => candidate.key === id);
+      if (item !== void 0) {
+        if (tabbable(item)) candidates2.push(itemCandidate(item));
+        continue;
+      }
+      const section = sections.find((s) => s.label === id && !isSectionHidden(s));
+      if (section !== void 0) {
+        candidates2.push(sectionCandidate(section, menuMax));
+        continue;
+      }
+      if (DEV) {
+        console.warn(
+          `[basalt] MobileNav: mobileNav.tabs names "${id}", which is neither a destination key nor a visible section label \u2014 ignoring it.`
+        );
+      }
+    }
+    return candidates2;
+  }
+  const candidates = [];
+  for (const section of sections) {
+    if (isSectionHidden(section)) continue;
+    if (section.mobile !== void 0 && section.mobile !== false && section.mobile.tab === true) {
+      candidates.push(sectionCandidate(section, menuMax));
+      continue;
+    }
+    const items = [];
+    flattenItems(section.items, items);
+    for (const item of items) {
+      if (placementOf(item, false) !== "tab") continue;
+      if (tabbable(item)) candidates.push(itemCandidate(item));
+    }
+  }
+  if (candidates.length > 0) return candidates;
+  const fallback = [];
+  for (const section of sections) {
+    if (isSectionHidden(section)) continue;
+    for (const item of section.items) {
+      if (fallback.length >= maxTabs - 1) return fallback;
+      if (item.disabled) continue;
+      if (placementOf(item, false) === "hidden") continue;
+      fallback.push(itemCandidate(item));
+    }
+  }
+  return fallback;
+}
+function buildOverflow(sections, covered) {
+  const groups = [];
+  for (const section of sections) {
+    const hidden = isSectionHidden(section);
+    if (hidden) continue;
+    const items = pruneTree(
+      section.items,
+      (item) => placementOf(item, hidden) !== "hidden" && !covered.has(item.key)
+    );
+    if (items.length === 0) continue;
+    groups.push({ key: section.label, label: section.label, items });
+  }
+  return groups;
+}
+function projectMobileNav(sections, opts) {
+  const config = opts?.config;
+  const maxTabs = Math.max(1, config?.maxTabs ?? MOBILE_MAX_TABS_DEFAULT);
+  const menuMax = Math.max(1, config?.menuMax ?? MOBILE_MENU_MAX_DEFAULT);
+  const extraMoreRows = opts?.extraMoreRows ?? 0;
+  const candidates = buildCandidates(sections, config, maxTabs, menuMax);
+  const coveredByAll = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) for (const key of candidate.covered) coveredByAll.add(key);
+  const overflowIfNoneDropped = buildOverflow(sections, coveredByAll);
+  const needsMore = countRows(overflowIfNoneDropped.flatMap((group) => group.items)) > 0 || extraMoreRows > 0 || candidates.length > maxTabs;
+  const limit = needsMore ? maxTabs - 1 : maxTabs;
+  const kept = candidates.slice(0, limit);
+  const dropped = candidates.slice(limit);
+  if (DEV && dropped.length > 0) {
+    console.warn(
+      `[basalt] MobileNav: ${candidates.length} slot candidates for ${limit} available slot(s) \u2014 the last ${dropped.length} moved into the More surface: ${dropped.map((candidate) => `"${candidate.key}"`).join(", ")}. Raise mobileNav.maxTabs or drop a mobile: 'tab'.`
+    );
+  }
+  const covered = /* @__PURE__ */ new Set();
+  for (const candidate of kept) for (const key of candidate.covered) covered.add(key);
+  const slots = [];
+  for (const candidate of kept) {
+    const slot = candidate.toSlot();
+    if (slot !== void 0) slots.push(slot);
+  }
+  if (!needsMore) return { slots };
+  const groups = buildOverflow(sections, covered);
+  const overflowItems = groups.flatMap((group) => group.items);
+  const rows = countRows(overflowItems) + extraMoreRows;
+  if (rows === 0) return { slots };
+  const label = config?.moreLabel ?? "More";
+  const only = overflowItems[0];
+  if (rows === 1 && extraMoreRows === 0 && only !== void 0 && !only.disabled) {
+    slots.push({
+      kind: "link",
+      key: only.key,
+      label: only.label,
+      short: only.short ?? only.label,
+      icon: only.icon,
+      active: hasActiveDestination(only),
+      item: only
+    });
+    return { slots };
+  }
+  slots.push({
+    kind: rows <= menuMax ? "menu" : "sheet",
+    key: MOBILE_MORE_KEY,
+    label,
+    short: label,
+    // No icon: the More glyph is chrome the renderer owns, and this module holds no JSX.
+    icon: void 0,
+    active: overflowItems.some(hasActiveDestination),
+    groups,
+    isMore: true
+  });
+  return { slots };
+}
+export {
+  MOBILE_MAX_TABS_DEFAULT,
+  MOBILE_MENU_MAX_DEFAULT,
+  MOBILE_MORE_KEY,
+  projectMobileNav
+};

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

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

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

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

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

@@ -0,0 +1,11 @@
+/**
+ * Sidebar nav count badge (docs/DESIGN-SPEC.md §5): mono 10.5px, 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
+ * stays clean ("ink earns its color", DESIGN.md).
+ */
+export declare function NavCountBadge({ count }: {
+    count: number;
+}): import("react").JSX.Element | null;
+//# sourceMappingURL=nav-count-badge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nav-count-badge.d.ts","sourceRoot":"","sources":["../../src/shell/nav-count-badge.tsx"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,sCAsBzD"}

package/dist/shell/nav-count-badge.js

@@ -0,0 +1,29 @@
+import { jsx } from "react/jsx-runtime";
+import { Badge } from "@mantine/core";
+import { VX } from "../tokens/index.js";
+function NavCountBadge({ count }) {
+  if (!count) return null;
+  return /* @__PURE__ */ jsx(
+    Badge,
+    {
+      size: "sm",
+      styles: {
+        root: {
+          backgroundColor: "color-mix(in srgb, var(--vx-ink) 8%, transparent)",
+          color: "var(--vx-muted)",
+          fontFamily: "var(--basalt-font-mono)",
+          fontSize: VX.text.micro,
+          fontWeight: 500,
+          height: 16,
+          padding: "0 5px",
+          marginLeft: "auto",
+          borderRadius: "var(--vx-radius-tight)"
+        }
+      },
+      children: count
+    }
+  );
+}
+export {
+  NavCountBadge
+};

package/dist/surfaces.d.ts

@@ -209,7 +209,7 @@ export declare const SURFACES: {
         readonly rule: "router";
         readonly skill: readonly ["basalt-app"];
         readonly guardKinds: readonly [];
-        readonly description: "TanStack Router bridge: useBasaltNav (active route) + useRouterBreadcrumbs + createSearchParamStore (single-select URL-state store) + createMultiSearchParamStore (multi-select URL-state store)";
+        readonly description: "TanStack Router bridge: defineNav/navGroup/navTarget (one typed nav definition) + useNav (sections + mobileNav, spread onto BasaltShell) + useBasaltNav (active route) + useRouterBreadcrumbs + createSearchParamStore (single-select URL-state store) + createMultiSearchParamStore (multi-select URL-state store)";
         readonly optionalPeers: readonly ["@tanstack/react-router"];
         readonly globs: {
             readonly shipped: readonly [];

package/dist/surfaces.js

@@ -120,7 +120,7 @@ const SURFACES = {
     rule: "router",
     skill: ["basalt-app"],
     guardKinds: [],
-    description: "TanStack Router bridge: useBasaltNav (active route) + useRouterBreadcrumbs + createSearchParamStore (single-select URL-state store) + createMultiSearchParamStore (multi-select URL-state store)",
+    description: "TanStack Router bridge: defineNav/navGroup/navTarget (one typed nav definition) + useNav (sections + mobileNav, spread onto BasaltShell) + useBasaltNav (active route) + useRouterBreadcrumbs + createSearchParamStore (single-select URL-state store) + createMultiSearchParamStore (multi-select URL-state store)",
     optionalPeers: ["@tanstack/react-router"],
     globs: {
       shipped: [],

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AA+DA,OAAO,KAAK,EACV,oBAAoB,EAGpB,oBAAoB,EAErB,MAAM,eAAe,CAAA;AAStB,OAAO,KAAK,EAAe,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAOlD;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAIlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AASvD,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,iBAAiB;QACzB,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,WAAW,CAAC,EAAE,iBAAiB,CAAA;QAC/B,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,aAAa,CAAC,EAAE,WAAW,CAAA;KAC5B;CACF;AAk5BD;+EAC+E;AAC/E,eAAO,MAAM,SAAS,EAAE,oBAAuD,CAAA;AAmJ/E;;8FAE8F;AAC9F,eAAO,MAAM,oBAAoB,EAAE,oBACc,CAAA;AAEjD,kEAAkE;AAClE,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IAE9B;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAA;IAEzB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAYD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,CAAC,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,wBAAwB,GACjC,oBAAoB,CA+BtB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AA+DA,OAAO,KAAK,EACV,oBAAoB,EAGpB,oBAAoB,EAErB,MAAM,eAAe,CAAA;AAStB,OAAO,KAAK,EAAe,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAOlD;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAIlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AASvD,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,iBAAiB;QACzB,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,WAAW,CAAC,EAAE,iBAAiB,CAAA;QAC/B,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,aAAa,CAAC,EAAE,WAAW,CAAA;KAC5B;CACF;AAm5BD;+EAC+E;AAC/E,eAAO,MAAM,SAAS,EAAE,oBAAuD,CAAA;AAmJ/E;;8FAE8F;AAC9F,eAAO,MAAM,oBAAoB,EAAE,oBACc,CAAA;AAEjD,kEAAkE;AAClE,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IAE9B;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAA;IAEzB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAYD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,CAAC,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,wBAAwB,GACjC,oBAAoB,CA+BtB"}

package/dist/theme/index.js

@@ -304,10 +304,10 @@ function buildTheme(data, options = {}) {
       // panel-filled row read as a button sitting in the nav rather than as the current location.
       // Selection is carried by the tint + ink text + weight 600 + the accent icon instead. Forced
       // here at the THEME level via NavLink's `--nl-*` vars so it holds for every render path —
-      // including a consumer's router `<Link>` via `renderNavLink`, which never sees the shell CSS
-      // module; the active ICON is accent-colored via `nav-link.module.css` (targets the
-      // `[data-position='left']` leftSection, which the flat `vars`/`styles` API can't express
-      // conditionally on `[data-active]`).
+      // including a consumer's router `<Link>` hosted through `SidebarItem.Anchor`, which never
+      // sees the shell CSS module; the active ICON is accent-colored via `nav-link.module.css`
+      // (targets the `[data-position='left']` leftSection, which the flat `vars`/`styles` API
+      // can't express conditionally on `[data-active]`).
       //
       // `--nl-hover` (ink-13%) only ever reaches an ACTIVE row in practice — the inactive hover is
       // set at ink-6% by higher-specificity `:not([data-active])` rules in `nav-link.module.css` /
@@ -323,9 +323,10 @@ function buildTheme(data, options = {}) {
           children: {}
         }),
         // Dense, rounded nav rows — applied at the THEME level so they survive EVERY render path,
-        // including a consumer's router `<Link>` via `renderNavLink`, which never sees the shell CSS
-        // module (the module's `.link` only reaches the shell's own fallback `<NavLink>`). Same
-        // reasoning as the `--nl-*` fill above: layout is single-sourced here, not in two places.
+        // including a consumer's router `<Link>` hosted through `SidebarItem.Anchor`, which never
+        // sees the shell CSS module (the module's `.link` only reaches the shell's own fallback
+        // `<NavLink>`). Same reasoning as the `--nl-*` fill above: layout is single-sourced here,
+        // not in two places.
         // The active-weight/shadow/icon-accent state selectors can't live in `styles` (flat inline
         // props only) — they're in nav-link.module.css, wired via `classNames` so they reach the
         // same every-render-path scope.

package/dist/theme/nav-link.module.css

@@ -5,7 +5,8 @@
  * tint rather than as a button, so the row never competes with the real filled controls around it.
  *
  * Applied at the THEME level via `classNames` so it reaches EVERY NavLink render path — including a
- * consumer's router `<Link>` mounted through `renderNavLink`, which a shell-scoped CSS module never
+ * consumer's router `<Link>` mounted through `SidebarItem.Anchor`, which a shell-scoped CSS
+ * module never
  * sees. Mantine's `styles` prop only takes flat inline properties (a nested `&[data-active]` there
  * throws a React warning), so the state selectors live here. React Router's NavLink marks the
  * active item via `aria-current` rather than the `active` prop's `data-active`, so both states are
@@ -42,7 +43,8 @@
 
 /*
  * Inactive hover — the ink-6% ghost tint + ink text/icon (docs/DESIGN-SPEC.md §5). Lives here (not
- * only in the shell module) so a consumer's `renderNavLink` path gets the same hover; Mantine's own
+ * only in the shell module) so a consumer's `SidebarItem.Anchor` path gets the same hover;
+ * Mantine's own
  * hover fill uses `:where(scheme) .m_*:hover` (gray-0/dark-6), which this outranks on specificity.
  * Active rows keep their panel fill + `--nl-hover` untouched.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tokens/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tokens/index.ts"],"names":[],"mappings":"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"}

package/dist/tokens/index.js

@@ -357,6 +357,8 @@ function spaceDecls(space) {
     decl("space-sidebar-child-row-indent", `${space.step.sidebarChildRowIndent}px`),
     decl("space-app-header-mobile-actions-height", `${space.step.appHeaderMobileActionsHeight}px`),
     decl("space-mobile-nav-tab-gap", `${space.step.mobileNavTabGap}px`),
+    decl("space-mobile-nav-icon-size", `${space.step.mobileNavIconSize}px`),
+    decl("space-mobile-nav-row-height", `${space.step.mobileNavRowHeight}px`),
     decl("space-agent-rail-inset-x", `${space.step.agentRailInsetX}px`),
     decl("space-agent-part-gap-top", `${space.step.agentPartGapTop}px`),
     decl("space-agent-code-inset", `${space.step.agentCodeInset}px`),