basalt-ui 1.17.0 → 1.19.0

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { createBasaltTheme, baseTheme, cssVariablesResolver } from './theme/inde
 export type { BasaltFontsConfig, CreateBasaltThemeOptions } from './theme/index.js';
 export { ThemeToggle, type ThemeToggleProps } from './theme-toggle/index.js';
 export { MOTION_DURATION, MOTION_SPRING, MOTION_EASE_STANDARD } from './motion/index.js';
-export { BasaltShell, NavCountBadge, AppSidebar, SidebarSearch, type SidebarSearchConfig, SidebarAccount, MobileNav, AppBreadcrumbs, type BreadcrumbLinkRenderer, PageHeaderProvider, PageActions, PageActionsOutlet, type SidebarSection, type SidebarItem, type BasaltShellProps, type BrandConfig, type SettingsMenuItem, type AppSidebarProps, type MobileNavItem, type MobileNavSection, type NavLinkRenderer, type MobileNavLinkRenderer, type AccountBadgeTone, type BasaltIdentity, type BasaltRole, type BasaltPlan, type AccountMenuItem, type BasaltAccountState, type BasaltAccountActions, type BasaltAccountProps, } from './shell/index.js';
+export { BasaltShell, NavCountBadge, AppSidebar, SidebarSearch, type SidebarSearchConfig, SidebarAccount, MobileNav, type MobileNavProps, projectMobileNav, type ProjectMobileNavOptions, MOBILE_MAX_TABS_DEFAULT, MOBILE_MENU_MAX_DEFAULT, MOBILE_MORE_KEY, AppBreadcrumbs, PageHeaderProvider, PageActions, PageActionsOutlet, type SidebarSection, type SidebarItem, type NavAnchor, type NavAnchorProps, type NavMobilePlacement, type NavSectionMobile, type MobileNavConfig, type MobileNavGroup, type MobileNavModel, type MobileNavSlot, type MobileNavSurface, type BasaltShellProps, type BrandConfig, type SettingsMenuItem, type AppSidebarProps, type AccountBadgeTone, type BasaltIdentity, type BasaltRole, type BasaltPlan, type AccountMenuItem, type BasaltAccountState, type BasaltAccountActions, type BasaltAccountProps, } from './shell/index.js';
 export { type BasaltRegister, type Slot, type Series, type SeriesKey, type AsyncState, assertNever, type StandardSchemaV1, } from './register.js';
 export { createPersistedState, type PersistedStateOptions, useOnlineStatus, readPersistedValue, } from './state.js';
 export { DeltaBadge, type DeltaBadgeProps, StatCard, type StatCardProps, type StatCardTone, EmptyState, type EmptyStateProps, SettingsSection, type SettingsSectionProps, SettingsRow, type SettingsRowProps, DangerZone, type DangerZoneProps, } from './dashboard/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,mBAAmB,EACnB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAC5E,YAAY,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AAC1E,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAC/E,OAAO,EACL,WAAW,EACX,aAAa,EACb,UAAU,EACV,aAAa,EACb,KAAK,mBAAmB,EACxB,cAAc,EACd,SAAS,EACT,cAAc,EACd,KAAK,sBAAsB,EAC3B,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,SAAS,CAAA;AAKhB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,IAAI,EACT,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,UAAU,EACf,WAAW,EACX,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,eAAe,EACf,kBAAkB,GACnB,MAAM,SAAS,CAAA;AAGhB,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,QAAQ,EACR,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,UAAU,EACV,KAAK,eAAe,EACpB,eAAe,EACf,KAAK,oBAAoB,EACzB,WAAW,EACX,KAAK,gBAAgB,EACrB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAC7F,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,gBAAgB,CAAA;AAKvB,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAClE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAU9C,OAAO,EACL,eAAe,EACf,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,QAAQ,EACR,mBAAmB,EACnB,gBAAgB,EAChB,QAAQ,GACT,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,aAAa,GACd,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,yBAAyB,EACzB,kBAAkB,EAClB,gBAAgB,EAChB,2BAA2B,EAC3B,kBAAkB,GACnB,MAAM,SAAS,CAAA;AAChB,YAAY,EACV,0BAA0B,EAC1B,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,+BAA+B,EAC/B,mBAAmB,EACnB,eAAe,EACf,WAAW,EACX,SAAS,EACT,cAAc,GACf,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -12,6 +12,10 @@ import {
   SidebarSearch,
   SidebarAccount,
   MobileNav,
+  projectMobileNav,
+  MOBILE_MAX_TABS_DEFAULT,
+  MOBILE_MENU_MAX_DEFAULT,
+  MOBILE_MORE_KEY,
   AppBreadcrumbs,
   PageHeaderProvider,
   PageActions,
@@ -64,6 +68,9 @@ export {
   DangerZone,
   DeltaBadge,
   EmptyState,
+  MOBILE_MAX_TABS_DEFAULT,
+  MOBILE_MENU_MAX_DEFAULT,
+  MOBILE_MORE_KEY,
   MOTION_DURATION,
   MOTION_EASE_STANDARD,
   MOTION_SPRING,
@@ -93,6 +100,7 @@ export {
   createThreadsStore,
   cssVariablesResolver,
   heuristicOutcome,
+  projectMobileNav,
   readPersistedValue,
   threadPartRenderers,
   threadsStoreAdapterContract,

package/dist/nav/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The shared nav vocabulary. TYPE-ONLY BY CONTRACT — never add a value export here.
+ * `src/shell/**` (Mantine) and `src/router-tanstack/**` (headless) both `import type` from it,
+ * which is erased by tsup, so `dist/router-tanstack/index.js` gains no edge into `shell/` and
+ * `scripts/check-dist-layering.mjs` stays green with no config change.
+ */
+import type { MouseEvent, ReactNode } from 'react';
+/** Where a destination appears on the mobile bar. `true` ≡ `'tab'`, `false` ≡ `'hidden'`. */
+export type NavMobilePlacement = 'tab' | 'more' | 'hidden';
+/**
+ * Props basalt hands a nav anchor. Deliberately a PLAIN FUNCTION TYPE, not `ComponentType`
+ * or `ElementType`: both are unions, and a union defeats Mantine's polymorphic `component`
+ * inference (`<NavLink component={…}>` then rejects `label`). VERIFIED both ways.
+ */
+export type NavAnchorProps = {
+    className?: string;
+    children?: ReactNode;
+    onClick?: (e: MouseEvent<HTMLElement>) => void;
+    'aria-current'?: 'page' | undefined;
+    'aria-label'?: string;
+};
+export type NavAnchor = (props: NavAnchorProps) => ReactNode;
+/** A single nav destination. */
+export type SidebarItem = {
+    key: string;
+    label: string;
+    /** Bar/menu label. Falls back to `label`. Keep ≤ 10 chars — a 5-slot bar is ~72px wide. */
+    short?: string;
+    /** Mobile placement. `true` ≡ `'tab'`, `false` ≡ `'hidden'`. @default 'more' */
+    mobile?: boolean | NavMobilePlacement;
+    icon: ReactNode;
+    /**
+     * The router seam. basalt renders every pixel of chrome (desktop row, 56px slot, 44px sheet
+     * row) and only hosts this component. When absent the row falls back to `<a href>` + `onClick`.
+     */
+    Anchor?: NavAnchor;
+    /** Plain href — the no-router fallback, and the breadcrumb parent target. */
+    href?: string;
+    active?: boolean;
+    disabled?: boolean;
+    onClick?: (e: MouseEvent) => void;
+    /** Rich desktop badge (e.g. `NavCountBadge`). Desktop only. */
+    badge?: ReactNode;
+    /** Unread count. Renders `NavCountBadge` on desktop when `badge` is absent, and an accent
+     *  dot on the mobile slot icon. `0` renders nothing. */
+    count?: number;
+    children?: SidebarItem[];
+};
+/** Per-section mobile configuration. `false` hides the whole section from mobile. */
+export type NavSectionMobile = {
+    /** Give this SECTION a bar slot; its destinations open per §2.2 cardinality inference. */
+    tab?: true;
+    /** Slot label override; falls back to `SidebarSection.label`. */
+    label?: string;
+    /** Slot icon override; falls back to `SidebarSection.icon`. */
+    icon?: ReactNode;
+};
+export type SidebarSection = {
+    label: string;
+    items: SidebarItem[];
+    icon?: ReactNode;
+    collapsible?: boolean;
+    defaultCollapsed?: boolean;
+    /** Mobile behaviour for this section. Omit for the default (items place themselves). */
+    mobile?: false | NavSectionMobile;
+};
+export type MobileNavSurface = 'link' | 'menu' | 'sheet';
+/** One row inside a `menu`/`sheet` slot, grouped under its source section. */
+export type MobileNavGroup = {
+    key: string;
+    label?: string;
+    items: SidebarItem[];
+};
+export type MobileNavSlot = {
+    kind: 'link';
+    key: string;
+    label: string;
+    short: string;
+    icon: ReactNode;
+    active: boolean;
+    item: SidebarItem;
+} | {
+    kind: 'menu' | 'sheet';
+    key: string;
+    label: string;
+    short: string;
+    icon: ReactNode;
+    active: boolean;
+    groups: MobileNavGroup[];
+    isMore: boolean;
+};
+/** Pure projection of `sections` onto the bar. Unit-testable with no DOM. */
+export type MobileNavModel = {
+    slots: MobileNavSlot[];
+};
+export type MobileNavConfig = {
+    /** Explicit slot order by item/section key. Overrides every `item.mobile` placement. */
+    tabs?: readonly string[];
+    /** Hard cap on bar slots, INCLUDING More. @default 5 */
+    maxTabs?: number;
+    /** Rows a slot may hold before it becomes a sheet instead of a menu. @default 6 */
+    menuMax?: number;
+    /** @default 'More' */
+    moreLabel?: string;
+    /** Extra content pinned to the bottom of the More surface. */
+    moreExtra?: ReactNode;
+    /** Scroll container for active-slot re-tap. @default document.scrollingElement */
+    getScrollElement?: () => HTMLElement | null;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/nav/types.d.ts.map

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

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

@@ -1,11 +1,18 @@
 /**
  * ./router-tanstack — headless TanStack Router bridge for the app shell.
  * Optional peer: @tanstack/react-router.
- * Augments StaticDataRouteOption with title/icon/navSection for breadcrumb
- * and nav-active wiring — no Mantine, no JSX, no navigate() helper.
+ * Carries the typed navigation definition (`defineNav`/`navGroup`/`navTarget`/`flattenNav`) and
+ * `useNav`, which resolves it into `BasaltShell`'s `sections` + `mobileNav` props; plus the
+ * StaticDataRouteOption augmentation (title/icon/navSection) for router-derived breadcrumbs and
+ * the search-param stores — no Mantine, no JSX.
  */
 export { createSearchParamStore, type SearchParamStore, type SearchParamStoreOptions, } from './search-param-store.js';
 export { createMultiSearchParamStore, type MultiSearchParamStore, type MultiSearchParamStoreOptions, } from './multi-search-param-store.js';
+export { defineNav, navGroup, navTarget, flattenNav } from './nav.js';
+export type { NavItemMeta, NavGroupMeta, AnyNavItem, AnyNavGroup, AnyNavLink, FlatNavItem, NavConfig, NavItemId, NavGroupId, NavTabId, NavIndex, } from './nav.js';
+export { useNav } from './use-nav.js';
+export type { UseNavOptions, NavBinding } from './use-nav.js';
+export type { NavAnchor, NavAnchorProps, NavMobilePlacement } from '../nav/types.js';
 import type { ReactNode } from 'react';
 declare module '@tanstack/react-router' {
     interface StaticDataRouteOption {

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,2BAA2B,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,GAClC,MAAM,4BAA4B,CAAA;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,qBAAqB;QAC7B,0EAA0E;QAC1E,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,oEAAoE;QACpE,IAAI,CAAC,EAAE,SAAS,CAAA;QAChB,wDAAwD;QACxD,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB;CACF;AAID,mFAAmF;AACnF,MAAM,MAAM,SAAS,GAAG;IACtB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAA;CAChE,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAUxC;AAID,iEAAiE;AACjE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,EAAE,CASzD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router-tanstack/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,2BAA2B,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,GAClC,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAClE,YAAY,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,SAAS,EACT,SAAS,EACT,UAAU,EACV,QAAQ,EACR,QAAQ,GACT,MAAM,OAAO,CAAA;AACd,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAClC,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC1D,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,qBAAqB;QAC7B,0EAA0E;QAC1E,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,oEAAoE;QACpE,IAAI,CAAC,EAAE,SAAS,CAAA;QAChB,wDAAwD;QACxD,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB;CACF;AAID,mFAAmF;AACnF,MAAM,MAAM,SAAS,GAAG;IACtB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAA;CAChE,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAUxC;AAID,iEAAiE;AACjE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,EAAE,CASzD"}

package/dist/router-tanstack/index.js

@@ -4,6 +4,8 @@ import {
 import {
   createMultiSearchParamStore
 } from "./multi-search-param-store.js";
+import { defineNav, navGroup, navTarget, flattenNav } from "./nav.js";
+import { useNav } from "./use-nav.js";
 import { useLocation, useMatches } from "@tanstack/react-router";
 function useBasaltNav() {
   const currentPath = useLocation({ select: (l) => l.pathname });
@@ -24,6 +26,11 @@ function useRouterBreadcrumbs() {
 export {
   createMultiSearchParamStore,
   createSearchParamStore,
+  defineNav,
+  flattenNav,
+  navGroup,
+  navTarget,
   useBasaltNav,
+  useNav,
   useRouterBreadcrumbs
 };

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