@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.200

package/src/client/router-types.ts

@@ -0,0 +1,294 @@
+/**
+ * Router Types — the router's surface, stated once.
+ *
+ * Split out of `router.ts` so the factory file is navigation logic rather than
+ * declarations (design/18-build-system.md §"No file >500 lines"), and because
+ * `rsc-fetch.ts` needs `RouterDeps` while `router.ts` needs `FetchResult`:
+ * with the types here, neither imports the other.
+ *
+ * See design/19-client-navigation.md for the architecture these describe.
+ */
+
+import type { NavigationState } from './navigation-context.ts';
+import type { ParamsSource } from '../shared/payload-root.ts';
+import type { SegmentInfo } from '../shared/segment-info.ts';
+import type { SegmentCache, PrefetchCache } from './segment-cache.ts';
+import type { HistoryStack } from './history.ts';
+import type { TransitionResult, CommitOutcome, RenderOwner } from './navigation-transition.ts';
+import type { NavigationEpoch } from './router-lifecycle.ts';
+
+export interface NavigationOptions {
+  /** Set to false to prevent scroll-to-top on forward navigation */
+  scroll?: boolean;
+  /** Use replaceState instead of pushState (replaces current history entry) */
+  replace?: boolean;
+  /**
+   * Runs exactly once, when React commits this navigation's tree — or when
+   * the navigation is abandoned (superseded or failed) and no such commit
+   * will come. The returned promise resolves on decode, which can be before
+   * OR after the commit; this is the hook for the other event. `<Link>`
+   * holds `isPending` until both have happened (TIM-1418). The outcome says
+   * which of the three it was.
+   */
+  onCommit?: (outcome: CommitOutcome) => void;
+  /**
+   * @internal AbortSignal from the Navigation API's NavigateEvent.
+   * When provided, the signal is linked to the router's per-navigation
+   * AbortController so in-flight RSC fetches are cancelled when a new
+   * navigation starts.
+   */
+  _signal?: AbortSignal;
+  /**
+   * @internal Skip pushState/replaceState — the Navigation API has already
+   * updated the URL via event.intercept(). Used for external navigations
+   * intercepted by the navigate event handler.
+   */
+  _skipHistory?: boolean;
+  /**
+   * @internal The URL the user is navigating FROM, captured before the
+   * Navigation API commits the destination. Sent as X-Timber-URL for
+   * slot skip comparison on the server (TIM-1232).
+   */
+  _departingUrl?: string;
+}
+
+/**
+ * Function that decodes an RSC Flight stream into a React element tree.
+ * In production: createFromFetch from @vitejs/plugin-rsc/browser.
+ * In tests: a mock that returns the raw payload.
+ */
+export type RscDecoder = (fetchPromise: Promise<Response>) => unknown;
+
+/**
+ * Function that renders a decoded RSC element tree into the DOM.
+ * In production: reactRoot.render(element).
+ * In tests: a no-op or mock.
+ *
+ * Receives the current NavigationState explicitly — no temporal
+ * coupling with setNavigationState/getNavigationState. The renderer
+ * wraps the element in NavigationProvider with this state.
+ */
+export type RootRenderer = (
+  element: unknown,
+  navState: NavigationState,
+  params: ParamsSource,
+  /**
+   * Publishes the state that makes this tree the current page (segment
+   * cache, pathname, history stack, address bar). The renderer runs it when
+   * the tree is on screen — in production from React's commit of the tree
+   * (`NavigationRoot`'s layout effect), a test double synchronously. It is not run before
+   * handing the tree over: a replay or revalidation whose tree suspends is
+   * given to React without being on screen, and publishing then advertises
+   * slot content keys the slot content cache has not recorded (TIM-1423).
+   */
+  commit: () => void
+) => void;
+
+/**
+ * Platform dependencies injected for testability. In production these
+ * map to browser APIs; in tests they're replaced with mocks.
+ */
+export interface RouterDeps {
+  fetch: (url: string, init: RequestInit) => Promise<Response>;
+  pushState: (data: unknown, unused: string, url: string) => void;
+  replaceState: (data: unknown, unused: string, url: string) => void;
+  scrollTo: (x: number, y: number) => void;
+  getCurrentUrl: () => string;
+  getScrollY: () => number;
+  /** Decode RSC Flight stream into React elements. If not provided, raw response text is stored. */
+  decodeRsc?: RscDecoder;
+  /** Render decoded RSC tree into the DOM. If not provided, rendering is a no-op. */
+  renderRoot?: RootRenderer;
+  /**
+   * Schedule a callback after the next paint. In the browser, this is
+   * requestAnimationFrame + setTimeout(0) to run after React commits.
+   * In tests, this runs the callback synchronously.
+   */
+  afterPaint?: (callback: () => void) => void;
+  /**
+   * Hand a navigation's tree to React in a transition, so the departing page
+   * stays visible while the destination resolves. Pending state is not React
+   * state — it lives in this router's external store (`setPending`), which
+   * `TopLoader` and `usePendingNavigation()` subscribe to (TIM-1307).
+   *
+   * The `perform` callback receives a `wrapPayload` function to wrap the
+   * decoded RSC payload with NavigationProvider + NuqsAdapter before
+   * NavigationRoot sets it as the new element. The `wrapPayload` function
+   * receives the NavigationState explicitly — no temporal coupling with
+   * getNavigationState().
+   *
+   * If not provided (tests), the router falls back to renderRoot.
+   */
+  navigateTransition?: (
+    pendingUrl: string,
+    owner: RenderOwner,
+    perform: (
+      wrapPayload: (
+        payload: unknown,
+        navState: NavigationState,
+        /**
+         * The params to publish over `payload`. On a partial navigation
+         * `payload` is the *retained* tree and these are the *incoming*
+         * route's — the two deliberately come from different payloads,
+         * which is the entire point of the client owning the provider
+         * (TIM-1297).
+         */
+        params: ParamsSource,
+        segmentUpdates?: Map<string, unknown>
+      ) => unknown
+    ) => Promise<TransitionResult<unknown>>,
+    /** See `NavigationOptions.onCommit`; forwarded to `navigateTransition`. */
+    onCommit?: (outcome: CommitOutcome) => void
+  ) => Promise<void>;
+
+  /**
+   * Whether the Navigation API is active and handling traversals.
+   * When true, the popstate handler is a no-op — the Navigation API's
+   * navigate event covers back/forward button presses.
+   */
+  navigationApiActive?: boolean;
+
+  /**
+   * Called around pushState/replaceState to set a flag that prevents
+   * the Navigation API's navigate listener from double-handling
+   * router-initiated navigations.
+   */
+  setRouterNavigating?: (value: boolean) => void;
+
+  /**
+   * Save scroll position via the Navigation API's per-entry state.
+   * When provided, used instead of history.replaceState for scroll storage.
+   */
+  saveNavigationEntryScroll?: (scrollY: number) => void;
+
+  /**
+   * Signal that a router-initiated navigation has completed. Resolves the
+   * deferred promise that ties the browser's native loading state to the
+   * navigation lifecycle. Called in the finally block of navigate/refresh,
+   * the same place `setPending(false)` clears the TopLoader.
+   */
+  completeRouterNavigation?: () => void;
+
+  /**
+   * Get the current unwrapped RSC payload element. Used for partial
+   * navigation: the router re-wraps the same element with new
+   * NavigationProvider context so mounted SegmentOutlets are preserved.
+   */
+  _getCurrentPayload?: () => unknown;
+
+  /**
+   * Initiate a navigation via the Navigation API (`navigation.navigate()`).
+   * Fires the navigate event BEFORE committing the URL, allowing Chrome
+   * to show its native loading indicator. Falls back to pushState when
+   * unavailable.
+   */
+  navigationNavigate?: (url: string, replace: boolean) => void;
+
+  /**
+   * Scroll the element matching a URL #fragment into view. Returns true
+   * when a matching element was found and scrolled. When absent or false,
+   * the router falls back to scroll-to-top on forward navigation — same
+   * as a full page load with an unknown fragment landing at the top.
+   */
+  scrollToHash?: (hash: string) => boolean;
+
+  /**
+   * Whether the client segment cache is enabled. When false (the default),
+   * the router sends no segment/slot lists, so every navigation gets a full
+   * RSC payload.
+   *
+   * It does NOT gate the `treePaths` half of X-Timber-State-Tree. Those
+   * describe the tree currently mounted, and interception scoping needs them
+   * to open a modal on top of a modal — a routing behaviour, not a caching
+   * optimization, so it must not depend on a performance opt-in (TIM-1282).
+   */
+  clientSegmentCache?: boolean;
+}
+
+export interface RouterInstance {
+  /** Navigate to a new URL (forward navigation) */
+  navigate(url: string, options?: NavigationOptions): Promise<void>;
+  /** Full re-render of the current URL — no state tree sent */
+  refresh(options?: { onCommit?: (outcome: CommitOutcome) => void }): Promise<void>;
+  /** Handle a popstate event (back/forward button). scrollY is read from history.state. */
+  handlePopState(url: string, scrollY?: number, externalSignal?: AbortSignal): Promise<void>;
+  /** Whether a navigation is currently in flight */
+  isPending(): boolean;
+  /** The URL currently being navigated to, or null if idle */
+  getPendingUrl(): string | null;
+  /** Subscribe to pending state changes */
+  onPendingChange(listener: (pending: boolean) => void): () => void;
+  /** Prefetch an RSC payload for a URL (used by Link hover) */
+  prefetch(url: string): void;
+  /**
+   * Snapshot the router's navigation state before dispatching a server action.
+   * Hand the epoch back to `applyActionResult` with the response (TIM-1474).
+   */
+  epoch(): NavigationEpoch;
+  /**
+   * Reconcile the page after a server action. `tree` is the piggybacked
+   * revalidation payload root, or `undefined` when the server sent none.
+   *
+   * Returns `true` when the result was applied, `false` when stale (a
+   * navigation happened since `epoch` was taken or the router was busy at
+   * dispatch). Async because the no-tree path awaits `refresh()` — the next
+   * queued action must not capture its epoch while the refresh is in-flight.
+   *
+   * Does NOT call `runWhenIdle` — that is the action queue's responsibility
+   * (gated on "queue empty", not just "router idle").
+   *
+   * See design/08-forms-and-actions.md §"Single-Roundtrip Revalidation".
+   */
+  applyActionResult(epoch: NavigationEpoch, tree?: unknown): Promise<boolean>;
+  /**
+   * Run `task` now if the router is idle (not pending, no uncommitted tree),
+   * otherwise once when it next becomes idle. Single slot — the action queue
+   * uses this to flush one deferred refresh when both queue-empty and
+   * router-idle are true (TIM-1474).
+   */
+  runWhenIdle(task: () => void): void;
+  /**
+   * Settle any handed-off-but-uncommitted owners as superseded, then flush
+   * idle tasks. Called by `syncShallowSearch` when a shallow URL update
+   * displaces a suspended transition (TIM-1480).
+   */
+  settleHandoffs(): void;
+  /**
+   * Invalidate client caches for a path so the next navigation fetches
+   * fresh data. Called when `revalidatePath` targeted a non-current path.
+   */
+  invalidatePath(path: string): void;
+  /**
+   * Evict all prefetch cache entries and history stack payloads (TIM-1476).
+   * Called after a server action that revalidated data — the mutation may
+   * affect any route's data, not just the paths the server named, so every
+   * cached payload is stale. In-flight prefetch singleflights are fenced
+   * by the eviction generation — their results are discarded if they
+   * complete after eviction. The current URL's history entry is preserved
+   * so `applyActionResult` can read its segment metadata.
+   */
+  evictStaleCaches(): void;
+  /**
+   * Populate the segment cache from server-provided segment metadata.
+   * Called on initial hydration with segment info embedded in the HTML.
+   */
+  initSegmentCache(segments: SegmentInfo[]): void;
+
+  /** The segment cache (exposed for tests and <Link> prefetch) */
+  segmentCache: SegmentCache;
+  /** The prefetch cache (exposed for tests and <Link> prefetch) */
+  prefetchCache: PrefetchCache;
+  /** The history stack (exposed for tests) */
+  historyStack: HistoryStack;
+}
+
+/**
+ * Router navigation phase — discriminated union replacing scattered
+ * `pending` + `pendingUrl` boolean flags.
+ *
+ * - `idle`: No navigation in flight. The committed params/pathname
+ *   are current.
+ * - `navigating`: A fetch or render is in progress. `targetUrl` is
+ *   the destination being navigated to.
+ */
+export type RouterPhase = { phase: 'idle' } | { phase: 'navigating'; targetUrl: string };