basalt-ui 1.18.0 → 1.19.0

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

@@ -0,0 +1,163 @@
+/**
+ * Typed navigation definition. Wraps TanStack's own `linkOptions` rather than reimplementing its
+ * validator, so `to` / `search` / `params` get the router's full checking, and nav metadata rides
+ * OUTSIDE the validated object in a sibling `link:` key.
+ *
+ * Why not flat (`{ id, label, to, search }`) via a carrier `TComp` over `ValidateLinkOptions`:
+ * `Constrain<T, C> = (T extends C ? T : never) | C` is an ASSIGNABILITY check, and assignability
+ * does not do excess-property checking — so `{ id, label, to: '/charts', colour: 'red' }` compiles
+ * silently. Compile-verified. A config whose selling point is "typos are compile errors" cannot
+ * have a hole exactly where metadata typos live.
+ *
+ * No JSX and no Mantine in this module — `./router-tanstack` is a headless barrel by contract.
+ */
+import type { ReactNode } from 'react';
+import type { NavMobilePlacement, NavSectionMobile } from '../nav/types.js';
+export type NavItemMeta = {
+    id: string;
+    label: string;
+    /** Bar/menu label. Falls back to `label`. */
+    short?: string;
+    icon?: ReactNode;
+    disabled?: boolean;
+    /** Mobile placement. `true` ≡ `'tab'`, `false` ≡ `'hidden'`. @default 'more' */
+    mobile?: boolean | NavMobilePlacement;
+    /** Active on an exact path match only. Default: prefix (`fuzzy: true`). `'/'` is always exact. */
+    exact?: boolean;
+};
+export type NavGroupMeta = {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    collapsible?: boolean;
+    defaultCollapsed?: boolean;
+    mobile?: false | NavSectionMobile;
+};
+/** Widened read shapes. The framework reads through these; a consumer never writes them. */
+export type AnyNavLink = {
+    to: string;
+    search?: unknown;
+    params?: unknown;
+};
+export type AnyNavItem = NavItemMeta & {
+    link: AnyNavLink;
+    children?: ReadonlyArray<AnyNavItem>;
+};
+export type AnyNavGroup = NavGroupMeta & {
+    items: ReadonlyArray<AnyNavItem>;
+};
+/** Exact-object check: any key outside `Shape` is typed `never`, which surfaces as an error. */
+export type Exact<T, Shape> = T & {
+    readonly [K in Exclude<keyof T, keyof Shape>]: never;
+};
+/**
+ * `Exact` for ONE item, recursing into `children`.
+ *
+ * The recursion is the whole point: `AnyNavItem['children']` is a plain
+ * `ReadonlyArray<AnyNavItem>` constraint, and a constraint is an assignability check — so a
+ * top-level-only `Exact` leaves the metadata-typo hole wide open exactly one level down
+ * (`children: [{ id, label, colour: 'red', link }]` compiled silently). Reapplying `Exact` per
+ * child, at every depth, is what makes the nested `link:` design actually deliver "every typo is a
+ * compile error" rather than "every typo in the top row is a compile error".
+ *
+ * The `[K in Extract<keyof T, 'children'>]` form rather than a `children?:` property is what keeps
+ * this inference-safe: it evaluates to `{}` for an item that declares no children (so no phantom
+ * key is added to the checked shape and nothing becomes required), and the intersection with
+ * `Exact<T, AnyNavItem>` keeps `T` in a naked inference position so the caller's literal types
+ * still flow out of `navGroup`'s `const T`.
+ */
+export type ExactNavItem<T> = Exact<T, AnyNavItem> & {
+    readonly [K in Extract<keyof T, 'children'>]: T[K] extends ReadonlyArray<AnyNavItem> ? NavItemsInput<T[K]> : T[K];
+};
+/** Per-element `Exact` over a tuple of items, so an unknown key errors at the item that owns it. */
+export type NavItemsInput<T extends ReadonlyArray<AnyNavItem>> = {
+    readonly [K in keyof T]: ExactNavItem<T[K]>;
+};
+type ItemsOf<G> = G extends ReadonlyArray<{
+    items: ReadonlyArray<infer I>;
+}> ? I : never;
+/**
+ * One item plus every descendant, at arbitrary depth. Recursive so the TYPE side matches what
+ * `findById` / `flattenNav` already do at RUNTIME — a one-level walk made `navTarget(nav,
+ * 'grandchild')` a compile error against an id the runtime resolves fine.
+ */
+type WithDescendants<I> = I | (I extends {
+    children: ReadonlyArray<infer C>;
+} ? WithDescendants<C> : never);
+type AllItemsOf<G> = WithDescendants<ItemsOf<G>>;
+/**
+ * id → link options, as a mapped type with key remapping. Do NOT replace this with
+ * `Extract<AllItemsOf<G>, { id: K }>['link']` — that form was compile-tested and returns the
+ * WHOLE union, silently losing per-id precision.
+ */
+export type NavIndex<G> = {
+    [I in AllItemsOf<G> as I extends {
+        id: infer K extends string;
+    } ? K : never]: I extends {
+        link: infer L;
+    } ? L : never;
+};
+/**
+ * The literal union of every addressable destination id in a definition — parents, children and
+ * grandchildren alike, at ARBITRARY depth, matching what `findById` / `flattenNav` resolve at
+ * runtime. Verified to seven levels of `children` with no instantiation-depth complaint.
+ *
+ * If this ever resolves to plain `string`, the entire nav API validates nothing while reporting
+ * zero errors — so any change to the generics above must be re-checked against
+ * `apps/playground/src/nav.type-guard.tsx`, whose `@ts-expect-error` rows go UNUSED (TS2578) the
+ * moment the union widens.
+ */
+export type NavItemId<G> = Extract<keyof NavIndex<G>, string>;
+export type NavGroupId<G> = G extends ReadonlyArray<{
+    id: infer I;
+}> ? I : never;
+export type NavTabId<G> = NavItemId<G> | NavGroupId<G>;
+export type NavConfig<G extends ReadonlyArray<AnyNavGroup>, T extends ReadonlyArray<NavTabId<G>>> = {
+    groups: G;
+    mobile?: {
+        /** Explicit bar order by item/group id. Omit to let each item's `mobile` field decide. */
+        tabs?: T;
+        /** @default 5 */ maxTabs?: number;
+        /** @default 6 */ menuMax?: number;
+        /** @default 'More' */ moreLabel?: string;
+    };
+};
+/**
+ * One nav group. `const M` on the meta is load-bearing: without it the group `id` widens to
+ * `string` from `NavGroupMeta` and `mobile.tabs` silently stops validating group ids.
+ */
+export declare function navGroup<const M extends NavGroupMeta, const T extends ReadonlyArray<AnyNavItem>>(meta: Exact<M, NavGroupMeta>, items: NavItemsInput<T>): M & {
+    items: T;
+};
+/**
+ * The whole navigation — desktop and mobile — in one inferred definition.
+ *
+ * There is deliberately NO compile-time cap on `mobile.tabs.length`. Both a
+ * `T extends … & { length: 0|1|2|3|4|5 }` constraint and a `tabs: T & MaxFive` property form were
+ * compile-tested: each makes the length check work but silently degrades `NavTabId<G>` to `string`,
+ * killing the far more valuable id-union validation. The cap is a runtime concern — the shell's
+ * `projectMobileNav` slices to `maxTabs` and DEV-warns about what it dropped.
+ */
+export declare function defineNav<const G extends ReadonlyArray<AnyNavGroup>, const T extends ReadonlyArray<NavTabId<G>>>(config: NavConfig<G, T>): NavConfig<G, T>;
+/**
+ * The link options for one destination, by id. Spreadable into `<Link>`, `router.navigate()`
+ * and `redirect()`. This is what collapses a consumer's Spotlight commands and index redirect.
+ *
+ * `id` is the definition's literal id union (`NavItemId`) at any nesting depth, so a nested child
+ * or grandchild is addressable exactly like a top-level item — the type side and `findById`'s
+ * runtime walk agree.
+ */
+export declare function navTarget<const C extends {
+    groups: ReadonlyArray<AnyNavGroup>;
+}, K extends NavItemId<C['groups']>>(config: C, id: K): NavIndex<C['groups']>[K];
+/** A flattened destination, tagged with the group it was declared in. */
+export type FlatNavItem = AnyNavItem & {
+    groupId: string;
+    groupLabel: string;
+};
+/** Depth-first flatten, parent then children — the leaf every other surface reads. */
+export declare function flattenNav(config: {
+    groups: ReadonlyArray<AnyNavGroup>;
+}): FlatNavItem[];
+export {};
+//# sourceMappingURL=nav.d.ts.map

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

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

package/dist/router-tanstack/nav.js

@@ -0,0 +1,38 @@
+function navGroup(meta, items) {
+  return { ...meta, items };
+}
+function defineNav(config) {
+  return config;
+}
+function findById(items, id) {
+  for (const item of items) {
+    if (item.id === id) return item;
+    const hit = item.children ? findById(item.children, id) : void 0;
+    if (hit) return hit;
+  }
+  return void 0;
+}
+function navTarget(config, id) {
+  for (const g of config.groups) {
+    const hit = findById(g.items, id);
+    if (hit) return hit.link;
+  }
+  throw new Error(`navTarget: no nav item with id "${id}"`);
+}
+function flattenNav(config) {
+  const out = [];
+  const walk = (items, groupId, groupLabel) => {
+    for (const item of items) {
+      out.push({ ...item, groupId, groupLabel });
+      if (item.children) walk(item.children, groupId, groupLabel);
+    }
+  };
+  for (const g of config.groups) walk(g.items, g.id, g.label);
+  return out;
+}
+export {
+  defineNav,
+  flattenNav,
+  navGroup,
+  navTarget
+};

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

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

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

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

package/dist/router-tanstack/search-param-store.d.ts

@@ -49,16 +49,26 @@
  *       return <Charts data={data} range={range} />
  *     }
  *
- * **5. Nav links** — carry the param across sub-pages via search={true},
- * guarded by a path-prefix check so non-dashboard links stay clean:
+ * **5. Nav links** — carry the param across sub-pages, set per destination in
+ * the nav definition so only the dashboard sub-tree inherits it and every
+ * other link stays clean. Use a CLICK-TIME THUNK over `readStored`:
  *
- *     const renderNavLink = (item, { active }) => {
- *       const isDashboard = item.href?.startsWith('/dashboard/')
- *         || item.href === '/dashboard'
- *       return <MantineNavLink component={Link} to={item.href}
- *         {...(isDashboard ? { search: true } : {})}
- *         label={item.label} active={active} />
- *     }
+ *     const dashSearch = () => ({ range: dashboardRange.readStored() ?? '30d' })
+ *
+ *     navGroup({ id: 'dash', label: 'Dashboard' }, [
+ *       { id: 'dash-overview', label: 'Overview', icon: <IconHome />,
+ *         link: linkOptions({ to: '/dashboard', search: dashSearch }) },
+ *       { id: 'dash-activity', label: 'Activity', icon: <IconPulse />,
+ *         link: linkOptions({ to: '/dashboard/activity', search: dashSearch }) },
+ *     ])
+ *
+ * NOT `search: true`. That flag means "keep the current search" and TanStack
+ * only offers it where the target's search is OPTIONAL — a route wired to a
+ * store's `validateSearch` always returns the param, so the router requires a
+ * value and `search: true` is a type error. The thunk is also the better
+ * behaviour: `<Link>` re-evaluates it at click time, so arriving from OUTSIDE
+ * the sub-tree restores the last selection instead of landing on the factory
+ * default, and a definition evaluated once at module scope never goes stale.
  */
 export type SearchParamStoreOptions<T extends string, P extends string = string> = {
     /** localStorage key (namespaced `basalt:<key>` automatically). */

package/dist/router-tanstack/search-param-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-param-store.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/search-param-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAMH,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACjF,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAA;IACX,mEAAmE;IACnE,KAAK,EAAE,CAAC,CAAA;IACR,2DAA2D;IAC3D,MAAM,EAAE,SAAS,CAAC,EAAE,CAAA;IACpB,kEAAkE;IAClE,QAAQ,EAAE,CAAC,CAAA;IACX,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAC1E;;;OAGG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;SAAG,CAAC,IAAI,CAAC,GAAG,CAAC;KAAE,CAAA;IACpE;;;OAGG;IACH,QAAQ,EAAE,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;IAC/C,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;CAC3B,CAAA;AAID,wBAAgB,sBAAsB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,MAAM,EACnF,IAAI,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,GAClC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAyBxB"}
+{"version":3,"file":"search-param-store.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/search-param-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAMH,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACjF,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAA;IACX,mEAAmE;IACnE,KAAK,EAAE,CAAC,CAAA;IACR,2DAA2D;IAC3D,MAAM,EAAE,SAAS,CAAC,EAAE,CAAA;IACpB,kEAAkE;IAClE,QAAQ,EAAE,CAAC,CAAA;IACX,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAC1E;;;OAGG;IACH,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;SAAG,CAAC,IAAI,CAAC,GAAG,CAAC;KAAE,CAAA;IACpE;;;OAGG;IACH,QAAQ,EAAE,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,CAAA;IAC/C,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;CAC3B,CAAA;AAID,wBAAgB,sBAAsB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,MAAM,EACnF,IAAI,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,GAClC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAyBxB"}

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

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+import type { MobileNavConfig, SidebarSection } from '../nav/types.js';
+import type { AnyNavGroup, AnyNavItem, NavConfig, NavItemId, NavTabId } from './nav.js';
+export type UseNavOptions<G extends ReadonlyArray<AnyNavGroup>> = {
+    /**
+     * Live per-destination badges, keys typed to the definition's id union.
+     * A `number` becomes `item.count` (desktop `NavCountBadge` + mobile dot).
+     * Anything else becomes `item.badge` (desktop only).
+     */
+    badges?: Partial<Record<NavItemId<G>, number | ReactNode>>;
+    /** Override active detection entirely. */
+    isActive?: (item: AnyNavItem) => boolean;
+    /** Passed straight through into the returned `mobileNav`. */
+    moreExtra?: ReactNode;
+    getScrollElement?: () => HTMLElement | null;
+};
+/** Spread straight onto `<BasaltShell {...nav} />` — both keys are `BasaltShellProps` keys. */
+export type NavBinding = {
+    sections: SidebarSection[];
+    mobileNav: MobileNavConfig;
+};
+/**
+ * Resolve a nav definition against the live router.
+ *
+ * @example
+ * const nav = useNav(NAV, { badges: { calendar: 3 } })
+ * return <BasaltShell brand={brand} {...nav}>{children}</BasaltShell>
+ */
+export declare function useNav<const G extends ReadonlyArray<AnyNavGroup>, const T extends ReadonlyArray<NavTabId<G>>>(config: NavConfig<G, T>, opts?: UseNavOptions<G>): NavBinding;
+//# sourceMappingURL=use-nav.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-nav.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/use-nav.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,OAAO,CAAA;AAEnD,OAAO,KAAK,EAAE,eAAe,EAA0B,cAAc,EAAE,MAAM,cAAc,CAAA;AAC3F,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAEpF,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,aAAa,CAAC,WAAW,CAAC,IAAI;IAChE;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IAC1D,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAA;IACxC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,gBAAgB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;CAC5C,CAAA;AAED,+FAA+F;AAC/F,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAAC,SAAS,EAAE,eAAe,CAAA;CAAE,CAAA;AAEnF;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,WAAW,CAAC,EAC1C,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAC1C,MAAM,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,UAAU,CAqG9D"}

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

@@ -0,0 +1,71 @@
+import { createElement, useMemo } from "react";
+import { Link, useMatchRoute, useRouterState } from "@tanstack/react-router";
+function useNav(config, opts) {
+  const matchRoute = useMatchRoute();
+  const href = useRouterState({ select: (s) => s.location.href });
+  const badges = opts?.badges;
+  const isActiveOverride = opts?.isActive;
+  const sections = useMemo(() => {
+    const badgeOf = (id) => badges?.[id];
+    const isActive = (item) => isActiveOverride?.(item) ?? Boolean(
+      matchRoute({
+        to: item.link.to,
+        ...item.link.params !== void 0 && { params: item.link.params },
+        // Prefix match by default so a parent stays lit on its children; `'/'` would then match
+        // everything, so it is always exact.
+        fuzzy: item.exact !== true && item.link.to !== "/"
+      })
+    );
+    const toSidebarItem = (item) => {
+      const Anchor = (props) => createElement(Link, { ...item.link, ...props });
+      const badge = badgeOf(item.id);
+      const children = item.children?.map(toSidebarItem);
+      return {
+        key: item.id,
+        label: item.label,
+        icon: item.icon,
+        Anchor,
+        // Per-destination active only. Rolling a child's active state up into its parent is the
+        // MOBILE SLOT's rule (§2.3.12) and belongs to `projectMobileNav`, which reads `children`
+        // anyway — doing it here too would also light a desktop parent row whose own route does
+        // not match.
+        active: isActive(item),
+        ...item.short !== void 0 && { short: item.short },
+        ...item.mobile !== void 0 && { mobile: item.mobile },
+        ...item.disabled !== void 0 && { disabled: item.disabled },
+        ...typeof badge === "number" ? { count: badge } : badge === void 0 || badge === null ? {} : { badge },
+        ...children !== void 0 && { children }
+      };
+    };
+    return config.groups.map((group) => ({
+      label: group.label,
+      items: group.items.map(toSidebarItem),
+      ...group.icon !== void 0 && { icon: group.icon },
+      ...group.collapsible !== void 0 && { collapsible: group.collapsible },
+      ...group.defaultCollapsed !== void 0 && { defaultCollapsed: group.defaultCollapsed },
+      ...group.mobile !== void 0 && { mobile: group.mobile }
+    }));
+  }, [config, matchRoute, href, badges, isActiveOverride]);
+  const mobile = config.mobile;
+  const moreExtra = opts?.moreExtra;
+  const getScrollElement = opts?.getScrollElement;
+  const mobileNav = useMemo(() => {
+    const groupLabelById = new Map(config.groups.map((g) => [g.id, g.label]));
+    const tabs = mobile?.tabs?.map((id) => {
+      const key = id;
+      return groupLabelById.get(key) ?? key;
+    });
+    return {
+      ...tabs !== void 0 && { tabs },
+      ...mobile?.maxTabs !== void 0 && { maxTabs: mobile.maxTabs },
+      ...mobile?.menuMax !== void 0 && { menuMax: mobile.menuMax },
+      ...mobile?.moreLabel !== void 0 && { moreLabel: mobile.moreLabel },
+      ...moreExtra !== void 0 && { moreExtra },
+      ...getScrollElement !== void 0 && { getScrollElement }
+    };
+  }, [config, mobile, moreExtra, getScrollElement]);
+  return { sections, mobileNav };
+}
+export {
+  useNav
+};

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

@@ -1,17 +1,15 @@
-import type { ReactNode } from 'react';
-export type BreadcrumbLinkRenderer = (href: string, label: string) => ReactNode;
-export declare function AppBreadcrumbs({ section, parent, parentHref, renderBreadcrumbLink, page, }: {
+import type { NavAnchor } from '../nav/types.js';
+export declare function AppBreadcrumbs({ section, parent, parentAnchor, parentHref, page, }: {
     section?: string;
     /** Parent item label — shown when the active page is a nested child (e.g. "Dashboard"). */
     parent?: string | undefined;
-    /** Parent item href — when provided, the parent label renders as a clickable link. */
-    parentHref?: string | undefined;
     /**
-     * Optional router link renderer for the parent breadcrumb segment. When provided, the parent
-     * label is rendered through this callback instead of a plain `<a href>`, enabling client-side
-     * navigation (e.g. TanStack `<Link>`).
+     * The parent destination's router anchor (`SidebarItem.Anchor`), so the crumb navigates
+     * client-side. basalt still owns every pixel of the crumb — the anchor only hosts the label.
      */
-    renderBreadcrumbLink?: BreadcrumbLinkRenderer | undefined;
+    parentAnchor?: NavAnchor | undefined;
+    /** Parent item href — the no-router fallback; ignored when `parentAnchor` is present. */
+    parentHref?: string | undefined;
     page?: string;
 }): import("react").JSX.Element | null;
 //# sourceMappingURL=app-breadcrumbs.d.ts.map

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

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

package/dist/shell/app-breadcrumbs.js

@@ -13,8 +13,8 @@ const currentStyle = {
 function AppBreadcrumbs({
   section,
   parent,
+  parentAnchor,
   parentHref,
-  renderBreadcrumbLink,
   page
 }) {
   if (!page) return null;
@@ -23,11 +23,15 @@ function AppBreadcrumbs({
       /* @__PURE__ */ jsx(Text, { style: crumbStyle, truncate: true, children: section }),
       /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
     ] }),
-    parent && parentHref && /* @__PURE__ */ jsxs(Fragment, { children: [
-      renderBreadcrumbLink ? renderBreadcrumbLink(parentHref, parent) : /* @__PURE__ */ jsx(Anchor, { style: crumbStyle, underline: "never", href: parentHref, truncate: true, children: parent }),
+    parent && parentAnchor && /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(Anchor, { style: crumbStyle, underline: "never", component: parentAnchor, truncate: true, children: parent }),
       /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
     ] }),
-    parent && !parentHref && /* @__PURE__ */ jsxs(Fragment, { children: [
+    parent && !parentAnchor && parentHref && /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(Anchor, { style: crumbStyle, underline: "never", href: parentHref, truncate: true, children: parent }),
+      /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
+    ] }),
+    parent && !parentAnchor && !parentHref && /* @__PURE__ */ jsxs(Fragment, { children: [
       /* @__PURE__ */ jsx(Text, { style: crumbStyle, truncate: true, children: parent }),
       /* @__PURE__ */ jsx(Text, { style: separatorStyle, children: "/" })
     ] }),

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

@@ -1,26 +1,25 @@
-import type { MouseEvent, ReactNode } from 'react';
-export type MobileNavItem = {
-    key: string;
-    label: string;
-    icon: ReactNode;
-    href?: string;
-    active?: boolean;
-    onClick?: (e: MouseEvent) => void;
+import type { ReactElement } from 'react';
+import type { MobileNavConfig, MobileNavModel } from '../nav/types.js';
+import type { BasaltAccountProps } from './account-types.js';
+import type { SettingsMenuItem } from './index.js';
+export type MobileNavProps = {
+    /** The projection from `projectMobileNav` — `BasaltShell` builds it, memoized. */
+    model: MobileNavModel;
+    config?: MobileNavConfig | undefined;
+    /** Rendered as FLAT ROWS in the More surface, never by mounting `SidebarAccount` (which opens
+     *  its own `Menu` — a menu inside a menu). This is what makes the mobile sidebar drawer
+     *  deletable: everything it used to hold is reachable from More. */
+    account?: BasaltAccountProps | undefined;
+    settingsMenuItems?: SettingsMenuItem[] | undefined;
 };
-export type MobileNavSection = {
-    key: string;
-    label: string;
-    icon: ReactNode;
-    active: boolean;
-    items: MobileNavItem[];
-};
-/** Renders a single sheet row. The consumer's router `Link` lives here; `active` is precomputed. */
-export type MobileNavLinkRenderer = (item: MobileNavItem, opts: {
-    active: boolean;
-}) => ReactNode;
-export declare function MobileNav({ sections, onOpenMore, renderNavLink, }: {
-    sections: MobileNavSection[];
-    onOpenMore: () => void;
-    renderNavLink?: MobileNavLinkRenderer;
-}): import("react").JSX.Element;
+/**
+ * How many rows `account` contributes to the More surface — DELEGATED to `accountRows` rather than
+ * re-derived, because `BasaltShell` needs this number BEFORE the projection runs (it feeds
+ * `extraMoreRows`, which picks `menu` vs `sheet` against `menuMax`) while only this module knows
+ * how many rows an account actually expands into. Two independent counts is how a "1 row" account
+ * shipped a 9-row menu into headroom sized for 6, and how a `loading` account — which renders NO
+ * rows — still conjured a More slot that opened empty.
+ */
+export declare function accountRowCount(account: BasaltAccountProps | undefined): number;
+export declare function MobileNav({ model, config, account, settingsMenuItems, }: MobileNavProps): ReactElement;
 //# sourceMappingURL=app-mobile-nav.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"app-mobile-nav.d.ts","sourceRoot":"","sources":["../../src/shell/app-mobile-nav.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGlD,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,SAAS,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAA;CAClC,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,SAAS,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,aAAa,EAAE,CAAA;CACvB,CAAA;AAED,oGAAoG;AACpG,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,KAAK,SAAS,CAAA;AAwBjG,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,UAAU,EACV,aAAa,GACd,EAAE;IACD,QAAQ,EAAE,gBAAgB,EAAE,CAAA;IAC5B,UAAU,EAAE,MAAM,IAAI,CAAA;IACtB,aAAa,CAAC,EAAE,qBAAqB,CAAA;CACtC,+BA+EA"}
+{"version":3,"file":"app-mobile-nav.d.ts","sourceRoot":"","sources":["../../src/shell/app-mobile-nav.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,YAAY,EAAa,MAAM,OAAO,CAAA;AAChE,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EAGf,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAiB/C,MAAM,MAAM,cAAc,GAAG;IAC3B,kFAAkF;IAClF,KAAK,EAAE,cAAc,CAAA;IACrB,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACpC;;wEAEoE;IACpE,OAAO,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAA;IACxC,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,GAAG,SAAS,CAAA;CACnD,CAAA;AAkFD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,CAE/E;AAsFD,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,MAAM,EACN,OAAO,EACP,iBAAiB,GAClB,EAAE,cAAc,GAAG,YAAY,CAsO/B"}