basalt-ui 1.18.0 → 1.19.0

package/src/router-tanstack/search-param-store.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.
  */
 
 import { createPersistedState, readPersistedValue } from '../state'

package/src/router-tanstack/use-nav.ts

@@ -0,0 +1,146 @@
+/**
+ * `useNav` — resolve a `defineNav` definition into the two props `BasaltShell` needs.
+ *
+ * One `defineNav([...])` in a leaf module produces the desktop sidebar AND the mobile bar: this
+ * hook resolves active state through the router and builds each destination's anchor, which is
+ * what deletes a consumer's `renderNavLink` / `renderBreadcrumbLink` / `NAV_TARGETS` table and
+ * every hand-written `useMatchRoute` call.
+ *
+ * No JSX — anchors are built with `createElement`, so `./router-tanstack` stays a headless,
+ * no-JSX `.ts` module per its own barrel contract.
+ */
+import { createElement, useMemo } from 'react'
+import type { ElementType, ReactNode } from 'react'
+import { Link, useMatchRoute, useRouterState } from '@tanstack/react-router'
+import type { MobileNavConfig, NavAnchor, SidebarItem, SidebarSection } from '../nav/types'
+import type { AnyNavGroup, AnyNavItem, NavConfig, NavItemId, NavTabId } from './nav'
+
+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 function useNav<
+  const G extends ReadonlyArray<AnyNavGroup>,
+  const T extends ReadonlyArray<NavTabId<G>>,
+>(config: NavConfig<G, T>, opts?: UseNavOptions<G>): NavBinding {
+  // `useMatchRoute` is `useCallback(fn, [router])` — a STABLE identity across renders — and it
+  // subscribes internally to `router.stores.matchRouteDeps`, so the component still re-renders on
+  // navigation. That makes it safe as a memo dep, and makes the memo below actually hit.
+  const matchRoute = useMatchRoute()
+  // The change signal: one string that moves on every navigation, including search-param-only ones.
+  const href = useRouterState({ select: (s) => s.location.href })
+
+  const badges = opts?.badges
+  const isActiveOverride = opts?.isActive
+
+  const sections = useMemo<SidebarSection[]>(() => {
+    const badgeOf = (id: string): number | ReactNode =>
+      (badges as Record<string, number | ReactNode> | undefined)?.[id]
+
+    const isActive = (item: AnyNavItem): boolean =>
+      isActiveOverride?.(item) ??
+      Boolean(
+        matchRoute({
+          to: item.link.to,
+          ...(item.link.params !== undefined && { 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: AnyNavItem): SidebarItem => {
+      // One anchor per destination. Basalt renders every pixel of chrome around it (desktop row,
+      // 56px slot, 44px sheet row) and only hosts this component, so `preload`, middle-click and
+      // back/forward all keep working. `Link as ElementType` is the single cast in the whole
+      // chain: the widened `AnyNavLink['search']` is `unknown`, which `LinkComponentProps` rejects.
+      // The consumer gets zero casts, which is the point.
+      const Anchor: NavAnchor = (props) =>
+        createElement(Link as ElementType, { ...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 !== undefined && { short: item.short }),
+        ...(item.mobile !== undefined && { mobile: item.mobile }),
+        ...(item.disabled !== undefined && { disabled: item.disabled }),
+        ...(typeof badge === 'number'
+          ? { count: badge }
+          : badge === undefined || badge === null
+            ? {}
+            : { badge }),
+        ...(children !== undefined && { children }),
+      }
+    }
+
+    return config.groups.map((group) => ({
+      label: group.label,
+      items: group.items.map(toSidebarItem),
+      ...(group.icon !== undefined && { icon: group.icon }),
+      ...(group.collapsible !== undefined && { collapsible: group.collapsible }),
+      ...(group.defaultCollapsed !== undefined && { defaultCollapsed: group.defaultCollapsed }),
+      ...(group.mobile !== undefined && { mobile: group.mobile }),
+    }))
+    // `href` is deliberately an unread dep, and the reason the memo is correct: `matchRoute` has a
+    // STABLE identity (`useCallback(fn, [router])`), so nothing else in this list moves on a
+    // navigation — while the `matchRoute` calls above read router state that just changed. `href`
+    // is the one value that always does move, so it is what re-derives `active`.
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+  }, [config, matchRoute, href, badges, isActiveOverride])
+
+  const mobile = config.mobile
+  const moreExtra = opts?.moreExtra
+  const getScrollElement = opts?.getScrollElement
+
+  const mobileNav = useMemo<MobileNavConfig>(() => {
+    // `MobileNavConfig.tabs` names SIDEBAR keys, and a `SidebarSection` is identified by its
+    // `label` (it carries no key). A group id in `mobile.tabs` is therefore translated to that
+    // group's label here; item ids pass through verbatim because `SidebarItem.key` IS the id.
+    const groupLabelById = new Map(config.groups.map((g) => [g.id, g.label]))
+    const tabs = mobile?.tabs?.map((id) => {
+      const key = id as string
+      return groupLabelById.get(key) ?? key
+    })
+
+    return {
+      ...(tabs !== undefined && { tabs }),
+      ...(mobile?.maxTabs !== undefined && { maxTabs: mobile.maxTabs }),
+      ...(mobile?.menuMax !== undefined && { menuMax: mobile.menuMax }),
+      ...(mobile?.moreLabel !== undefined && { moreLabel: mobile.moreLabel }),
+      ...(moreExtra !== undefined && { moreExtra }),
+      ...(getScrollElement !== undefined && { getScrollElement }),
+    }
+  }, [config, mobile, moreExtra, getScrollElement])
+
+  return { sections, mobileNav }
+}

package/src/shell/app-breadcrumbs.tsx

@@ -11,11 +11,10 @@
  * a consumer's bundler.
  */
 import { Anchor, Group, Text } from '@mantine/core'
-import type { CSSProperties, ReactNode } from 'react'
+import type { CSSProperties } from 'react'
+import type { NavAnchor } from '../nav/types'
 import { VX } from '../tokens'
 
-export type BreadcrumbLinkRenderer = (href: string, label: string) => ReactNode
-
 /** Parent/section crumbs — faint. */
 const crumbStyle: CSSProperties = { fontSize: VX.text.md, color: 'var(--vx-faint)' }
 
@@ -34,21 +33,20 @@ const currentStyle: CSSProperties = {
 export function AppBreadcrumbs({
   section,
   parent,
+  parentAnchor,
   parentHref,
-  renderBreadcrumbLink,
   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
 }) {
   if (!page) return null
@@ -62,19 +60,23 @@ export function AppBreadcrumbs({
           <Text style={separatorStyle}>/</Text>
         </>
       )}
-      {parent && parentHref && (
+      {parent && parentAnchor && (
         <>
-          {renderBreadcrumbLink ? (
-            renderBreadcrumbLink(parentHref, parent)
-          ) : (
-            <Anchor style={crumbStyle} underline="never" href={parentHref} truncate>
-              {parent}
-            </Anchor>
-          )}
+          <Anchor style={crumbStyle} underline="never" component={parentAnchor} truncate>
+            {parent}
+          </Anchor>
+          <Text style={separatorStyle}>/</Text>
+        </>
+      )}
+      {parent && !parentAnchor && parentHref && (
+        <>
+          <Anchor style={crumbStyle} underline="never" href={parentHref} truncate>
+            {parent}
+          </Anchor>
           <Text style={separatorStyle}>/</Text>
         </>
       )}
-      {parent && !parentHref && (
+      {parent && !parentAnchor && !parentHref && (
         <>
           <Text style={crumbStyle} truncate>
             {parent}

package/src/shell/app-mobile-nav.module.css

@@ -1,3 +1,8 @@
+/*
+ * The mobile bottom bar. Slots are DESTINATIONS: a tap navigates, so the bar must read as a tab
+ * bar rather than as chrome — hence a pill behind the icon for the active slot instead of a
+ * full-tab fill, and a press that depresses the icon without moving the hit box.
+ */
 .bar {
   display: flex;
   align-items: stretch;
@@ -5,6 +10,21 @@
   height: 100%;
   background: var(--mantine-color-body);
   border-top: 1px solid var(--mantine-color-default-border);
+  -webkit-tap-highlight-color: transparent;
+  /* NO padding-bottom / env() here: Mantine's own AppShell `.footer` rule already does
+   * `height: calc(var(--app-shell-footer-height) + env(safe-area-inset-bottom))` +
+   * `padding-bottom: env(safe-area-inset-bottom)`. Adding it here double-counts the inset. */
+}
+
+/* Mantine sets --app-shell-footer-OFFSET to the raw height WITHOUT the inset, so Main's
+ * padding-bottom is short by exactly one inset. This is the only real safe-area gap. */
+@media (max-width: 47.99375em) {
+  .mainSafeArea {
+    padding-bottom: calc(
+      var(--app-shell-footer-offset, 0rem) + var(--app-shell-padding) +
+        env(safe-area-inset-bottom, 0px)
+    );
+  }
 }
 
 .tab {
@@ -16,18 +36,127 @@
   justify-content: center;
   gap: var(--vx-space-mobile-nav-tab-gap);
   color: var(--mantine-color-dimmed);
+  /* Kills the 300ms double-tap-zoom delay and the text-selection flash on a fast repeat tap. */
+  touch-action: manipulation;
+  user-select: none;
 }
 
-/* Active = neutral surface fill + plain text color. Never the identity blue (DESIGN.md). */
+.tabIcon {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  /* Deliberately sub-scale: the active pill hugs a 24px glyph, so it is a shape inset rather than
+   * layout spacing — the xs..xl scale has no step this tight. */
+  padding: 2px 12px; /* theme-allow */
+  border-radius: var(--vx-radius-ctrl);
+  transition: transform 140ms cubic-bezier(0.32, 0.72, 0, 1);
+}
+
+/* A consumer's sidebar icons are typically 18px; the bar normalizes them in CSS so the same
+ * `SidebarItem.icon` renders at slot size with zero consumer change. */
+.tabIcon > svg {
+  width: var(--vx-space-mobile-nav-icon-size);
+  height: var(--vx-space-mobile-nav-icon-size);
+}
+
+.tab:active .tabIcon {
+  transform: scale(0.9);
+}
+
+/* Active = a neutral pill behind the ICON only, plus plain text color. A full-tab fill is what
+ * makes the bar read as chrome instead of a tab bar. Never the identity blue (DESIGN.md). */
 .tab[data-active] {
   color: var(--mantine-color-text);
+}
+
+.tab[data-active] .tabIcon {
   background-color: color-mix(in srgb, var(--vx-ink) 10%, transparent);
 }
 
+.tab[data-active] .label {
+  font-weight: 600;
+}
+
+/* Unread dot. This is a BADGE, not the active state — the "never the identity blue" rule above
+ * governs the active fill and is unchanged. A count GLYPH is unreadable in a 56px slot. */
+.tabDot {
+  position: absolute;
+  top: 0;
+  inset-inline-end: 8px;
+  width: 8px;
+  height: 8px;
+  border-radius: 999px;
+  background-color: var(--vx-accent);
+  box-shadow: 0 0 0 2px var(--mantine-color-body);
+}
+
+/* `text-overflow: clip`, never an ellipsis — a truncated word with a "…" in a 72px tab reads as
+ * broken rather than as abbreviated. `SidebarItem.short` is the fix, not the ellipsis. */
 .label {
   font-size: var(--vx-text-micro);
   line-height: 1;
   font-weight: 500;
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: clip;
+  white-space: nowrap;
+}
+
+/* The menu pops UP out of its tab and is configured `flip: false` — flipping a bottom-anchored
+ * menu would put it under the footer. `menuMax` is what guarantees it fits (§2.2). */
+.menuDropdown {
+  padding: 4px;
+  max-height: min(60dvh, 360px);
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+
+/* The theme's `Menu.extend` pins `styles.item` padding + font-size to the dense DESKTOP values
+ * INLINE, so a touch-sized mobile row needs `!important` — same cascade problem, same reason, as
+ * `.row` below. */
+.menuItem {
+  min-height: var(--vx-space-mobile-nav-row-height) !important;
+  align-items: center;
+}
+
+.menuItem :global(.mantine-Menu-itemLabel) {
+  font-size: var(--mantine-font-size-md) !important;
+}
+
+/* An active destination reads the same in the More surface as it does in the sheet. */
+.menuItem[aria-current='page'] {
+  background-color: color-mix(in srgb, var(--vx-ink) 13%, transparent);
+  font-weight: 600;
+}
+
+/*
+ * A disabled destination still RENDERS in the menu (§2.3 rule 11) — it just must not be reachable.
+ * Mantine's `Menu.css` styles `[data-disabled]` with a dimmed color and nothing else, and the row
+ * is polymorphic (`component="a"`), so the native `disabled` attribute does not apply either: with
+ * no rule here the row stays fully clickable. `pointer-events: none` is the real guard; `menuRow`
+ * carries a matching handler guard for the paths pointers do not cover (keyboard, synthetic
+ * clicks, a consumer stylesheet that resets this).
+ */
+.menuItem[data-disabled] {
+  pointer-events: none;
+  cursor: not-allowed;
+}
+
+/* Nesting survives to mobile — a child destination is an indented row, not a sibling of its own
+ * parent (which is what today's flattened projection makes it). */
+.menuItemNested {
+  padding-inline-start: calc(var(--mantine-spacing-md) + 12px) !important;
+}
+
+/* Overflow section heading inside the menu — inherits the theme's mono micro-label. */
+.menuLabel {
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-micro);
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--vx-faint);
 }
 
 /*
@@ -39,6 +168,8 @@
   box-shadow: var(--vx-shadow-card);
   border-top-left-radius: var(--mantine-radius-lg);
   border-top-right-radius: var(--mantine-radius-lg);
+  /* A Drawer is NOT an AppShell section, so Mantine adds no inset of its own here. */
+  padding-bottom: env(safe-area-inset-bottom, 0px);
 }
 
 /* Sheet title = a micro-label (docs/DESIGN-SPEC.md §3), matching the sidebar's `.sectionLabel`. */
@@ -51,7 +182,17 @@
   color: var(--vx-faint);
 }
 
-/* Large tap rows inside the group sheet. NavLink rows reuse the sidebar's neutral active fill.
+/* The dismiss affordance. There is no swipe-to-dismiss: Mantine ships no drag primitive and
+ * writing `transform` to Drawer.Content fights its own Transition on the same node. */
+.grabber {
+  width: 36px;
+  height: 4px;
+  margin: 0 auto 8px;
+  border-radius: 999px;
+  background-color: color-mix(in srgb, var(--vx-ink) 18%, transparent);
+}
+
+/* Large tap rows inside the sheet. NavLink rows reuse the sidebar's neutral active fill.
  * `padding` needs `!important`: the theme's `NavLink.extend` forces the dense desktop row padding
  * (6px 10px) INLINE on every NavLink root, which would shrink these touch targets otherwise. */
 .row {
@@ -59,13 +200,23 @@
   align-items: center;
   gap: var(--mantine-spacing-sm);
   width: 100%;
+  min-height: var(--vx-space-mobile-nav-row-height);
   padding: var(--mantine-spacing-sm) var(--mantine-spacing-md) !important;
   border-radius: var(--mantine-radius-sm);
   color: var(--mantine-color-text);
+  touch-action: manipulation;
+  user-select: none;
+}
+
+/* Hover must be gated: on touch an ungated :hover leaves the last-tapped row stuck lit. */
+@media (hover: hover) {
+  .row:hover {
+    background-color: color-mix(in srgb, var(--vx-ink) 8%, transparent);
+  }
 }
 
-.row:hover {
-  background-color: color-mix(in srgb, var(--vx-ink) 8%, transparent);
+.row:active {
+  background-color: color-mix(in srgb, var(--vx-ink) 10%, transparent);
 }
 
 /*
@@ -76,8 +227,7 @@
  * `classNames` are always injected, so the icon needs its own `!important` override here to hold
  * the mobile-only "never accent" doctrine.
  */
-.row[data-active],
-.row[data-active]:hover {
+.row[data-active] {
   --nl-color: var(--mantine-color-text);
   color: var(--mantine-color-text);
   background-color: color-mix(in srgb, var(--vx-ink) 13%, transparent);
@@ -88,13 +238,18 @@
   color: var(--mantine-color-text) !important;
 }
 
-.rowLabel {
-  font-size: var(--mantine-font-size-md);
-  line-height: 1.2;
+.rowNested {
+  padding-inline-start: calc(var(--mantine-spacing-md) + 12px) !important;
 }
 
-/* NavLink-rendered rows match `.rowLabel` — the theme pins the label at the dense desktop 13px
- * INLINE (`styles.label`), so `!important` is required to restore the mobile size. */
+/* Sheet rows read at the mobile body size — the theme pins the label at the dense desktop 13px
+ * INLINE (`styles.label`), so `!important` is required to restore it. */
 .row :global(.mantine-NavLink-label) {
   font-size: var(--mantine-font-size-md) !important;
 }
+
+@media (prefers-reduced-motion: reduce) {
+  .tabIcon {
+    transition: none;
+  }
+}

package/src/shell/app-mobile-nav.module.css.d.ts

@@ -1,14 +1,23 @@
 /**
  * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
- * signature — so dot access stays verbatim under the package's strict flags.
+ * signature — so dot access stays verbatim under the package's strict flags. HAND-MAINTAINED:
+ * there is no generator, so a new class in `app-mobile-nav.module.css` must be added here too.
  */
 declare const classes: {
   readonly bar: string
+  readonly mainSafeArea: string
   readonly tab: string
+  readonly tabIcon: string
+  readonly tabDot: string
   readonly label: string
+  readonly menuDropdown: string
+  readonly menuItem: string
+  readonly menuItemNested: string
+  readonly menuLabel: string
   readonly sheet: string
   readonly sheetTitle: string
+  readonly grabber: string
   readonly row: string
-  readonly rowLabel: string
+  readonly rowNested: string
 }
 export default classes