@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/client/router-types.ts

@@ -0,0 +1,370 @@
+/**
+ * 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 { TransitionResult, CommitOutcome, RenderOwner } from './navigation-transition.ts';
+import type { NavigationEpoch } from './router-lifecycle.ts';
+
+/**
+ * The view transition type the router adds to a render it hands React —
+ * exactly one per navigation, traversal, refresh or revalidation render,
+ * beside any `transitionTypes` the caller passed.
+ * A `<ViewTransition>` keys its animations on these
+ * (design/37-navigation-api.md §"Transition types", TIM-1471).
+ *
+ * - `navigation-forward` — a push or replace (`<Link>`, `router.push`,
+ *   a server action redirect, a non-shallow nuqs update), or a traversal
+ *   forward through history.
+ * - `navigation-back` — a traversal back through history.
+ * - `navigation-traverse` — a traversal whose direction the router cannot
+ *   know: the History API fallback, where `popstate` carries no index.
+ * - `refresh` — `router.refresh()`.
+ * - `revalidate` — the page re-rendered after a server action.
+ *
+ * The shallow search re-wrap and hydration add none. A server redirect the
+ * router follows keeps the types of the render it interrupted.
+ */
+export type NavigationTransitionType =
+  | 'navigation-forward'
+  | 'navigation-back'
+  | 'navigation-traverse'
+  | 'refresh'
+  | 'revalidate';
+
+/** The type a traversal adds: its direction, when the router knows it. */
+export type TraverseDirection = Extract<
+  NavigationTransitionType,
+  'navigation-forward' | 'navigation-back' | 'navigation-traverse'
+>;
+
+/** Options for `RouterInstance.refresh`. */
+export interface RefreshOptions {
+  /** See `NavigationOptions.onCommit`. */
+  onCommit?: (outcome: CommitOutcome) => void;
+  /**
+   * Why the page is being re-fetched, as the view transition type the render
+   * adds: `refresh` (the default) when the user asked, `revalidate` when a
+   * server action left the page to be re-fetched.
+   */
+  transitionType?: Extract<NavigationTransitionType, 'refresh' | 'revalidate'>;
+}
+
+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;
+  /**
+   * View transition types to add to this navigation, beside the router's own
+   * `navigation-forward`. They are added in the router's transition, the one
+   * that renders the destination — not in the caller's: React claims types
+   * per root at the next transition commit, and the destination is handed to
+   * React only after its fetch, so a type added around the `navigate()` call
+   * never reaches it (design/37-navigation-api.md §"Transition types").
+   */
+  transitionTypes?: readonly string[];
+  /**
+   * @internal The complete view transition types for this render, replacing
+   * `navigation-forward` + `transitionTypes`. Set only when the router
+   * follows a redirect, which keeps the types of the render it interrupted.
+   */
+  _renderTypes?: readonly string[];
+  /**
+   * 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 the payload root.
+ * In production: createFromFetch from @vitejs/plugin-rsc/browser. Tests use
+ * the same Flight client over Flight bytes (tests/helpers/router-harness.ts),
+ * so every response is classified and decoded by the one path production runs.
+ */
+export type RscDecoder = (fetchPromise: Promise<Response>) => unknown;
+
+/**
+ * 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 an RSC Flight stream into the payload root. */
+  decodeRsc: RscDecoder;
+  /**
+   * 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 — there is no store to read it
+   * from.
+   *
+   * Every render goes through here — a navigation, a refresh, a traversal
+   * (fetched or replayed) and a server action's revalidation — so each one
+   * gets the same handover, commit and supersession.
+   */
+  navigateTransition: (
+    pendingUrl: string,
+    owner: RenderOwner,
+    /** The view transition types this render adds; see `NavigationRender`. */
+    types: readonly string[],
+    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?: RefreshOptions): Promise<void>;
+  /**
+   * Handle a traversal (back/forward button). scrollY is read from the
+   * destination entry's state. `direction` is the transition type the
+   * render adds; it defaults to `navigation-traverse`, the type for a
+   * traversal whose direction is unknown.
+   */
+  handlePopState(
+    url: string,
+    scrollY?: number,
+    externalSignal?: AbortSignal,
+    direction?: TraverseDirection
+  ): 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;
+  /**
+   * True when no navigation has started since `epoch` was taken and the
+   * router was idle then and is idle now — the same test
+   * `applyActionResult` applies. Action branches that never reach
+   * `applyActionResult` use it to detect a navigation that ran while the
+   * action was in flight and may have rendered pre-mutation data (TIM-1483).
+   */
+  isEpochCurrent(epoch: NavigationEpoch): boolean;
+  /**
+   * 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;
+  /**
+   * Make the next navigation a full render: the server re-renders every
+   * segment instead of skipping the shared layouts the client reports as
+   * mounted (TIM-1466). Called when `revalidatePath` named a page other
+   * than the current one — a layout that page shares with this one may now
+   * be stale, and the server cannot tell that from the state tree.
+   */
+  suppressSegmentReuse(): 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. `applyActionResult` does not need the history
+   * stack: the current page's segment metadata is the committer's record.
+   */
+  evictStaleCaches(): void;
+  /**
+   * Make the server-rendered page the current page — the hydration entry
+   * point, and the only one: bootstrap does not reach into the router's
+   * caches. Returns the `NavigationState` the page renders with.
+   *
+   * Goes through the same `prepareNavigation` every navigation uses, and
+   * commits at once rather than on React's hydration commit. The server's
+   * HTML is already the page on screen, and React does not promise that
+   * commit: a render that reaches the root while hydration is suspended (a
+   * shallow search update, a navigation the Navigation API intercepted
+   * before hydration) switches the root to client rendering, and the
+   * hydration tree — with any publish attached to it — never commits. A
+   * status document is still kept out of the cache: its `StatusPageMarker`
+   * clears the cache when it reports (navigation-commit.ts).
+   */
+  hydrate(page: HydrationPage): NavigationState;
+
+  /** The segment cache (exposed for tests and <Link> prefetch) */
+  segmentCache: SegmentCache;
+  /** The prefetch cache (exposed for tests and <Link> prefetch) */
+  prefetchCache: PrefetchCache;
+}
+
+/** The page the server rendered, as the browser entry decoded it. */
+export interface HydrationPage {
+  /** The inlined payload's tree, or null when the document carried none. */
+  payload: unknown;
+  /** The params published beside it. */
+  params: ParamsSource;
+  /** The rendered chain's metadata (`self.__timber_segments`), or null. */
+  segmentInfo: SegmentInfo[] | null;
+}
+
+/**
+ * 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 };

package/src/client/router-url.ts

@@ -0,0 +1,32 @@
+/**
+ * How the client router reads the URLs it is handed.
+ *
+ * One parser, so the places that key or compare by URL — the history stack,
+ * the navigation state a page renders with, the departing page sent as
+ * `X-Timber-URL` — cannot disagree about what a URL says. They did: a
+ * history entry stored under `navigate('/café')`'s spelling was looked up
+ * under the address bar's `/caf%C3%A9`, and missed (TIM-1541).
+ */
+
+const BASE = 'http://localhost';
+
+/**
+ * Parse a router URL. A URL that starts with "/" is a path — including one
+ * that starts with "//": that is the pathname a document at
+ * `https://host//a/b` reports, and resolved against a base it would parse as
+ * a scheme-relative reference to host `a`. Anything else resolves against a
+ * placeholder origin, so an absolute URL keeps its own.
+ */
+export function parseRouterUrl(url: string): URL {
+  return url.startsWith('/') ? new URL(BASE + url) : new URL(url, BASE);
+}
+
+/**
+ * The spelling a URL is stored and looked up under: the browser's own
+ * pathname + search, so `/a?` and `/a`, `/café` and `/caf%C3%A9`, are one
+ * key. The fragment is dropped — it is client-only.
+ */
+export function routerUrlKey(url: string): string {
+  const parsed = parseRouterUrl(url);
+  return parsed.pathname + parsed.search;
+}