basalt-ui 1.41.0 → 2.0.1

package/src/index.ts

@@ -1,308 +1,56 @@
 /**
- * basalt-ui root barrel — the Mantine-coupled surface.
- *
- * Provider + theme + the app shell. The Mantine-free token/chart layer is published under the
- * `basalt-ui/tokens` and `basalt-ui/charts` subpath exports (see package.json), NOT re-exported
- * here, so a tokens/charts-only consumer never pulls in `@mantine/*`.
+ * basalt-ui root barrel — the Mantine-coupled surface: provider, theme, the app shell and the
+ * dashboard atoms. The Mantine-free token/chart layer is published under `basalt-ui/tokens` and
+ * `basalt-ui/charts`, NOT re-exported here, so a tokens/charts-only consumer never pulls in
+ * `@mantine/*`. One import path per symbol: `docs/V2-SPEC.md` § 1; the per-symbol verdicts are
+ * `docs/waves/v2-surface.md`.
  */
 
-export {
-  BasaltProvider,
-  type BasaltProviderProps,
-  BasaltErrorBoundary,
-  type BasaltErrorBoundaryProps,
-  type BasaltErrorContext,
-} from './provider'
-// -- Common primitives (src/common) ------------------------------------------------------------
-// Not a subpath of its own: `BasaltProps` is the base every component's props extend, so it belongs
-// on the entry a consumer already imports. The module is Mantine-free (`common/boundary.test.ts`),
-// which is what lets `./charts` reach `cx` without breaching the layer boundary.
-// The validate/errors internals (`useValidateProps`/`assertRequiredProps`/`requiredProp`/`oneOf`/
-// `deprecatedProp`/`duplicateMount`/`missingLayer`/`BASALT_PREFIX`) and the ref helpers
-// (`assignRef`/`mergeRefs`) are basalt's own diagnostic vocabulary, not a consumer's — no consumer
-// imports them, so they stay internal (C1 consolidation).
-export {
-  type BasaltProps,
-  type SlotClassNames,
-  type SlotStylesProps,
-  type Tone,
-  type ToneWithNeutral,
-  type Tier,
-  cx,
-  scrollParentOf,
-  SCROLLPORT_ATTRIBUTE,
-  useCoarsePointer,
-} from './common'
-
-export { createBasaltTheme, baseTheme, cssVariablesResolver } from './theme'
-export type { BasaltFontsConfig, CreateBasaltThemeOptions } from './theme'
-export { CTL_THEME, CtlSlot } from './theme'
-export type { CtlSlotProps } from './theme'
-/**
- * The ACTIVE resolved spacing off the running theme, not the frozen level-0 `SPACE`/`SPACE_STEP`
- * snapshot on `basalt-ui/tokens`. Public because a consumer laying out ITS OWN chrome beside the
- * shell's (a sticky sub-header under the app header, a fixed rail beside the navbar) has to hit the
- * same rhythm the shell resolved, and every one of those numbers is JS-consumed — an AppShell
- * dimension or a `<Menu width={…}>` — so there is no `--vx-*` var to read it from instead. See
- * `theme/use-basalt-spacing.ts` for the level-0 fallback contract.
- */
-export { useBasaltSpacing } from './theme'
-export { ThemeToggle, type ThemeToggleProps } from './theme/theme-toggle'
-/**
- * The action vocabulary every home's `actions` slot takes (`docs/CONTROLS-SPEC.md` §2.1). The
- * OTHER components that project it (`OverflowMenu`, `SyncButton`, and the filter family) live on
- * `basalt-ui/controls`; `ActionGroup` is re-exported here alongside its own types so a typed
- * `PageBar`/`BasaltShell` `actions` wrapper needs only this one subpath.
- */
-export {
-  ActionGroup,
-  type BarAction,
-  type ActionGroupProps,
-  type GlobalAction,
-} from './controls/actions'
-export { MOTION_DURATION, MOTION_SPRING, MOTION_EASE_STANDARD } from './common/motion'
+export { BasaltProvider } from './provider'
+export {
+  createBasaltRouter,
+  type BasaltRouter,
+  type BasaltRouterContext,
+} from './provider/create-router'
+export type { BasaltEvent } from './telemetry'
+export {
+  defineNav,
+  navGroup,
+  navTarget,
+  flattenNav,
+  useBasaltNav,
+  type NavItemId,
+} from './router-tanstack'
+export { scrollParentOf, useCoarsePointer } from './common'
+export { createBasaltTheme } from './theme'
+export { ThemeToggle } from './theme/theme-toggle'
 export {
   BasaltShell,
-  NavCountBadge,
-  type NavCountBadgeProps,
-  AppSidebar,
-  SidebarSearch,
-  type SidebarSearchProps,
-  type SidebarSearchConfig,
-  type SidebarSearchActions,
-  SidebarAccount,
-  MobileNav,
-  type MobileNavProps,
-  projectMobileNav,
-  type ProjectMobileNavOptions,
-  MOBILE_MAX_TABS_DEFAULT,
-  MOBILE_MENU_MAX_DEFAULT,
-  MOBILE_MORE_KEY,
-  AppBreadcrumbs,
-  type AppBreadcrumbsProps,
   PageBar,
-  type PageBarProps,
-  type PageBarSlot,
   PageAside,
-  type PageAsideProps,
-  type PageAsideSlot,
   useSizeClass,
-  type SizeClass,
   PageTitle,
-  type PageTitleProps,
-  type PageTitleSlot,
-  type SidebarSection,
-  type SidebarItem,
+  type ShellBaseProps,
   type SidebarBlock,
-  type SidebarBlockItem,
-  type SidebarBlockTone,
-  type SidebarListBlock,
-  type SidebarProgressBlock,
-  type SidebarCustomBlock,
-  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'
-
-// ── Design seam (register.ts) ─────────────────────────────────────────────────────────────────────
-// BasaltRegister MUST be exported from the package main entry so `declare module 'basalt-ui'`
-// augmentation works — a consumer cannot augment 'basalt-ui/charts'.
-export {
-  type BasaltRegister,
-  type Slot,
-  type Series,
-  type SeriesKey,
-  type AsyncState,
-  assertNever,
-  type StandardSchemaV1,
-} from './register'
-
-// ── Persisted state + the headless store kernel (state.ts) ───────────────────────────────────────
-// The `field.*` VALUE is deliberately not re-exported here. `basalt-ui/forms` used to own the
-// name `field` too and collide with this one; that forms helper is `inputProps` now (the
-// `@deprecated field` alias was removed in 1.29.0, C1 consolidation — see MIGRATING.md). Import
-// `field.*` from `basalt-ui/router-tanstack` (beside `createSearchStore`) or from `basalt-ui/state`
-// (beside `createLocalStore`).
-export {
-  createPersistedState,
-  type PersistedStateOptions,
-  readPersistedValue,
-  createLocalStore,
-  type LocalStore,
-  type AnyField,
-  type BooleanField,
-  type EnumField,
-  type FieldFallback,
-  type FieldHandle,
-  type FieldLane,
-  type FieldOption,
-  type FieldSetOptions,
-  type FieldValue,
-  type MultiField,
-  type NumberField,
-  type RangeField,
-  type RangeParams,
-  type RangePresets,
-  type RangeValue,
-  type RangeWindow,
-  type RangeWindows,
-  type ResolvedLane,
-  type ResolveLane,
-  type SearchValues,
-  type StoredValues,
-  type StringField,
-} from './state'
-
-// ── Dashboard composites (WidgetHeader/Section heading family + KPI atoms + settings building
-// blocks, docs/CONTROLS-SPEC.md §2.2) ──────────────────────────────────────────────────────────────
 export {
   WidgetHeader,
-  type WidgetHeaderDeltaProps,
-  type WidgetHeaderMetricProps,
-  type WidgetHeaderProps,
-  type WidgetHeaderSlot,
-  type WidgetHeaderTier,
-  type WidgetHeaderTitleProps,
   DeltaBadge,
-  type DeltaBadgeProps,
-  type DeltaPolarity,
   Section,
-  type SectionProps,
-  type SectionSlot,
   StatCard,
   type StatCardBreakdownRow,
-  type StatCardProps,
-  type StatCardSlot,
   type StatCardTone,
-  WidgetGrid,
-  type WidgetGridCols,
-  type WidgetGridItemProps,
-  type WidgetGridProps,
   StatGroup,
-  type StatGroupCols,
-  type StatGroupProps,
   EmptyState,
-  type EmptyStateProps,
-  type EmptyStateSlot,
   SettingsSection,
-  type SettingsSectionProps,
-  type SettingsSectionSlot,
   SettingsRow,
-  type SettingsRowProps,
-  type SettingsRowSlot,
   DangerZone,
-  type DangerZoneProps,
-  QueryState,
-  type QueryStateProps,
-  type QueryStateLike,
-  type QueryStateSlot,
-  type QueryStateTier,
-  type QueryEmptyCopy,
-  LoadingState,
-  type LoadingStateProps,
-  ErrorState,
-  type ErrorStateProps,
 } from './dashboard'
+export { unwrap } from './query-client'
 
-// ── Connectivity (auto-mounted by BasaltProvider, merged into ./provider — dropped ./connectivity
-// subpath) ──────────────────────────────────────────────────────────────────────────────────────
-export { ConnectivityProvider } from './provider/connectivity-provider'
-export { ConnectivityIndicator } from './provider/connectivity-indicator'
-export { useConnectivity } from './provider/use-connectivity'
-export type {
-  ConnectivityStatus,
-  ConnectivitySnapshot,
-  ConnectivityProviderProps,
-  ConnectivityOverride,
-} from './provider/connectivity-types'
-export type { ConnectivityIndicatorProps } from './provider/connectivity-indicator'
-
-// ── Query (createBasaltQueryClient, unwrap, lazy devtools — dropped ./query subpath) ──────────────
-export { createBasaltQueryClient, unwrap } from './query-client'
-export { BasaltQueryDevtools } from './query-devtools'
-export { toErrorMessage, errorStatus } from './common/errors'
-
-// ── BasaltDevDock (C5 consolidation) ────────────────────────────────────────────────────────────
-export { BasaltDevDock, type BasaltDevDockProps, type BasaltDevDockTool } from './dev-dock'
-
-// ── Type-only re-exports for compile fixtures (H.4) ──────────────────────────────────────────────
-// SurfaceSpec/RuleName/SkillName: the value SURFACES stays internal; types only for surfaces-broken
-// fixture. GuardKind: type-only for fixture completeness. No ./surfaces subpath exposed.
-export type { SurfaceSpec, RuleName, SkillName } from './surfaces'
-export type { GuardKind } from './guard/types'
-
-// ── Agent chat (thread feed + detail workspace) ──────────────────────────────────────────────────
-// Everything from `./agent-chat` (Mantine-styled thread-chat components + the flagship
-// ThreadWorkspace) belongs at the root. From the headless `./agent` layer, SELECTIVELY re-export
-// only the pieces a ThreadWorkspace consumer needs — NOT an export-star — so the optional-peer
-// BasaltStickToBottom and the rest of `./agent` stay off the root entry; `edenTransport` stays out
-// too, sourced from `basalt-ui/agent` instead. `agent-chat/thread-message.tsx` DOES reach
-// `./content`'s `Markdown` for its text renderer — root's markdown/shiki/mermaid optional peers
-// come from that path, not from `./agent`.
-export {
-  ThreadWorkspace,
-  ThreadFeed,
-  ThreadFeedRow,
-  ThreadOutcomeCard,
-  ThreadDetailPanel,
-  Composer,
-  threadPartRenderers,
-  ThreadTranscript,
-  ToolChip,
-} from './agent-chat'
-export type {
-  ThreadWorkspaceProps,
-  ThreadFeedProps,
-  ThreadFeedRowProps,
-  ThreadOutcomeCardProps,
-  ThreadDetailPanelProps,
-  ComposerProps,
-  ComposerSubmit,
-  ComposerAttachment,
-  ComposerHandle,
-  ThreadTranscriptProps,
-  MessageAffordances,
-  VirtualizeOptions,
-  VirtualizeProps,
-  RowHeightProps,
-  ToolChipProps,
-} from './agent-chat'
-export {
-  createAdapterThreadsStore,
-  createThreadsStore,
-  heuristicOutcome,
-  threadsStoreAdapterContract,
-  useAgentThreadRuns,
-} from './agent'
-export type {
-  AdapterThreadsStoreOptions,
-  AgentThread,
-  AgentOutcome,
-  ThreadStatus,
-  ThreadsStore,
-  ThreadsStoreAdapter,
-  ThreadsStoreAdapterContractCase,
-  ThreadsStoreOptions,
-  OutcomeResolver,
-  ChatMessage,
-  AgentPart,
-  AgentTransport,
-} from './agent'
+// The one augmentable seam: `declare module 'basalt-ui' { interface BasaltRegister { … } }` only
+// merges when the entry exports the interface. `v2-surface.md` marks it `delete` (no consumer
+// *names* it), but every typed registry (commands, overlays, notifications, series) resolves
+// through it — augmentation is not an import, so the consumer count missed it.
+export type { BasaltRegister, SeriesKey } from './register'

package/src/provider/create-router.tsx

@@ -0,0 +1,138 @@
+/**
+ * `createBasaltRouter` — the router + QueryClient wiring (V2-SPEC § 2). One `QueryClient` per call
+ * (so an SSR entry gets one per request), carried on `context.queryClient`, plus the router
+ * defaults basalt owns: intent preloading with Query-owned freshness, scroll restoration, the
+ * pending / error / not-found components, and the route view transition (direction from the
+ * `BasaltShell` nav order, V2-SPEC § 5).
+ */
+import { Button, Center, Loader, Stack, Text } from '@mantine/core'
+import type { QueryClient, QueryClientConfig } from '@tanstack/react-query'
+import { Router, createRouter } from '@tanstack/react-router'
+import type { AnyRoute, ErrorComponentProps, RouterHistory } from '@tanstack/react-router'
+import { toErrorMessage } from '../common/errors'
+import { makeQueryClient } from '../query-client'
+import { errorName, now, routerTelemetry } from '../telemetry'
+import {
+  guardViewTransitionRejections,
+  routeViewTransition,
+  supportsViewTransitionTypes,
+} from './route-transition'
+
+/** The root route's context: `createRootRouteWithContext<BasaltRouterContext>()`. */
+export type BasaltRouterContext = {
+  queryClient: QueryClient
+}
+
+type BasaltRouterBase<TRouteTree extends AnyRoute> = Router<
+  TRouteTree,
+  'never',
+  false,
+  RouterHistory,
+  Record<string, any> // oxlint-disable-line typescript/no-explicit-any -- TanStack's own default
+>
+
+declare const basaltRouterBrand: unique symbol
+
+/**
+ * What `createBasaltRouter` returns, and the only router `BasaltProvider` accepts. The brand is
+ * type-level only: a plain `createRouter(...)` has the same shape without it and fails to compile,
+ * because the provider needs the `queryClient` context and the defaults `createBasaltRouter` sets.
+ *
+ * The route-tree default is TanStack's own `AnyRouter` shape (`any`): a specific tree is not
+ * assignable to `AnyRoute`, and `BasaltProvider` accepts any tree.
+ */
+export type BasaltRouter<
+  TRouteTree extends AnyRoute = any, // oxlint-disable-line typescript/no-explicit-any -- see JSDoc
+> = BasaltRouterBase<TRouteTree> & {
+  readonly [basaltRouterBrand]: true
+}
+
+function PendingComponent() {
+  return (
+    <Center py="xl">
+      <Loader size="sm" />
+    </Center>
+  )
+}
+
+function ErrorComponent({ error, reset }: ErrorComponentProps) {
+  return (
+    <Stack align="flex-start" gap="xs" p="md">
+      <Text fw={600}>Something went wrong</Text>
+      <Text c="dimmed" size="sm">
+        {toErrorMessage(error)}
+      </Text>
+      <Button size="compact-sm" variant="default" onClick={reset}>
+        Try again
+      </Button>
+    </Stack>
+  )
+}
+
+function NotFoundComponent() {
+  return (
+    <Stack gap={4} p="md">
+      <Text fw={600}>Page not found</Text>
+      <Text c="dimmed" size="sm">
+        This address does not match any page.
+      </Text>
+    </Stack>
+  )
+}
+
+/**
+ * Side effect, once per document: wraps `document.startViewTransition` so a skipped route
+ * transition (`AbortError`) never becomes an unhandled rejection (`guardViewTransitionRejections`).
+ * Nothing else global is touched.
+ *
+ * @example
+ * const router = createBasaltRouter({ routeTree })
+ * declare module '@tanstack/react-router' {
+ *   interface Register { router: typeof router }
+ * }
+ * // extra context (argo's auth) extends BasaltRouterContext:
+ * const router = createBasaltRouter({ routeTree, context: { auth }, query: { queryCache } })
+ */
+export function createBasaltRouter<
+  TRouteTree extends AnyRoute,
+  TContext extends object = Record<never, never>,
+>(options: {
+  routeTree: TRouteTree
+  /** Context beyond `queryClient`; the root route's context type extends `BasaltRouterContext`. */
+  context?: TContext
+  /** Merged over basalt's QueryClient defaults (`staleTime` 30 s, `gcTime` 5 min, `retry` 2, no refetch on focus). */
+  query?: QueryClientConfig
+  /** Route transitions are basalt's (V2-SPEC § 5): the router's would double them. */
+  defaultViewTransition?: never
+}): BasaltRouter<TRouteTree> {
+  guardViewTransitionRejections()
+  const queryClient = makeQueryClient(options.query)
+  const router: BasaltRouterBase<TRouteTree> = createRouter({
+    routeTree: options.routeTree,
+    context: { ...options.context, queryClient },
+    defaultPreload: 'intent',
+    // Query owns freshness: a preload must not be cached a second time by the router.
+    defaultPreloadStaleTime: 0,
+    scrollRestoration: true,
+    // Route changes only; React's `<ViewTransition>` stays for in-page changes (the aside fold).
+    // Types-gated: without `:active-view-transition-type()` the router would crossfade the whole page.
+    defaultViewTransition: supportsViewTransitionTypes() ? routeViewTransition : false,
+    defaultPendingComponent: PendingComponent,
+    defaultErrorComponent: ErrorComponent,
+    defaultNotFoundComponent: NotFoundComponent,
+    defaultOnCatch: (error: unknown) => {
+      if (process.env.NODE_ENV !== 'production') console.error('[basalt] route error', error)
+      routerTelemetry(router)({
+        type: 'route.error',
+        failed: true,
+        start: now(),
+        attributes: {
+          'basalt.route.id': router.state.matches.at(-1)?.routeId ?? 'unknown',
+          'exception.type': errorName(error),
+          'basalt.error.kind': 'route',
+        },
+      })
+    },
+  })
+  return router as BasaltRouter<TRouteTree>
+}

package/src/provider/hotkeys.ts

@@ -0,0 +1,70 @@
+/**
+ * Command shortcuts from the `defineCommands` registry, bound only when the registry has a
+ * `shortcut`. `@tanstack/react-hotkeys` is subpath-required for `./commands`, so it is reached
+ * through `import()` only and its runtime stays off first paint (V2-SPEC § 2).
+ *
+ * `defineCommands` has no loader-registration seam yet; when `./commands` grows one (it calls this
+ * module's loader instead), this registry check is what goes away.
+ */
+import type { HotkeyRegistrationHandle } from '@tanstack/react-hotkeys'
+import { useEffect } from 'react'
+import { getActiveCommands } from '../commands/define-commands'
+import type { Command } from '../commands/define-commands'
+
+/**
+ * Runs a command, swallowing a sync throw or async rejection so a failing command never becomes an
+ * unhandled rejection (which the provider would report as a `window.error`). Dev logs it.
+ */
+export function runCommandSafely(cmd: Command): void {
+  const report = (error: unknown): void => {
+    if (process.env.NODE_ENV !== 'production') console.error('[basalt] command failed', error)
+  }
+  try {
+    Promise.resolve(cmd.run()).catch(report)
+  } catch (error) {
+    report(error)
+  }
+}
+
+export function useRegistryHotkeys(): void {
+  useEffect(() => {
+    const commands = Object.values(getActiveCommands()).filter((c) => c.shortcut !== undefined)
+    if (commands.length === 0) return
+
+    let cancelled = false
+    const handles: HotkeyRegistrationHandle[] = []
+
+    // An absent peer is a silent no-op: shortcuts simply do not bind.
+    void import('@tanstack/react-hotkeys')
+      .catch(() => undefined)
+      .then((peer) => {
+        if (cancelled || peer === undefined) return
+        const manager = peer.getHotkeyManager()
+        for (const cmd of commands) {
+          if (cmd.shortcut === undefined) continue
+          handles.push(
+            manager.register(
+              cmd.shortcut,
+              (event) => {
+                // The `when` gate is read at press time, not at registration.
+                if (cmd.when !== undefined && !cmd.when()) return
+                event.preventDefault()
+                runCommandSafely(cmd)
+              },
+              { preventDefault: false },
+            ),
+          )
+        }
+      })
+      .catch((error: unknown) => {
+        if (process.env.NODE_ENV !== 'production') {
+          console.error('[basalt] command hotkeys failed to bind', error)
+        }
+      })
+
+    return () => {
+      cancelled = true
+      for (const handle of handles) handle.unregister()
+    }
+  }, [])
+}