@uniflowed/router 0.0.0-alpha.40 → 0.0.0-alpha.42

package/native-navigation.js

@@ -0,0 +1,217 @@
+// @flow
+import * as React from "react";
+import { Pressable } from "react-native";
+import {
+  CommonActions,
+  NavigationContainer,
+  StackActions,
+  createNavigationContainerRef,
+  useRoute,
+} from "@react-navigation/native";
+import { resolveNativeNavigation, createNativeRouter, createNativeLinking } from "./native.js";
+import type { NativeLinkSource } from "./native.js";
+import type { RouteTable } from "./internal/routing.js";
+import type {
+  NativeLayout,
+  NativeNode,
+  NativeTree,
+  NavigationPayload,
+  NavigationState,
+} from "./internal/native-tree.js";
+import { nativeTree, stateForPath, hrefFromState, paramsForPath } from "./internal/native-tree.js";
+
+export interface NavigatorPair {
+  readonly Navigator: React.ComponentType<{ ... }>;
+  readonly Screen: React.ComponentType<{ ... }>;
+}
+export type FileRouter = {
+  readonly push: (href: string) => void,
+  readonly replace: (href: string) => void,
+  readonly back: () => void,
+  readonly prefetch: (href: string) => Promise<void>,
+};
+type Scope = {
+  tree: NativeTree,
+  node: NativeNode,
+  screens: Map<NativeNode, React.ComponentType<{ ... }>>,
+  stack: NavigatorPair,
+  tabs: ?NavigatorPair,
+  router: FileRouter,
+};
+const ScopeContext: React.Context<Scope | null> = React.createContext(null);
+
+function useScope(): Scope {
+  const scope = React.useContext(ScopeContext);
+  if (scope == null)
+    throw new Error(
+      "Native navigation: mount createNativeNavigation().Root before using its navigator or hooks",
+    );
+  return scope;
+}
+
+/** The application supplies its own React Navigation navigator factories. */
+export function createNativeNavigation(options: {
+  table: RouteTable<>,
+  layouts: $ReadOnlyArray<NativeLayout>,
+  stack: NavigatorPair,
+  tabs?: NavigatorPair,
+  initialHref?: string,
+  links?: NativeLinkSource,
+}): { Root: React.ComponentType<{ ... }>, router: FileRouter, linking: { ... } } {
+  const { table, layouts, stack, tabs } = options;
+  const tree = nativeTree(table, layouts);
+  const ref = createNavigationContainerRef();
+  const screens = new Map<NativeNode, React.ComponentType<{ ... }>>();
+  const resolve = (href: string): { names: $ReadOnlyArray<string>, payload: NavigationPayload } => {
+    const event = resolveNativeNavigation(table, href);
+    const names = tree.paths.get(event.route);
+    if (names == null) throw new Error(`Native navigation: no screen for ${event.route}`);
+    return { names, payload: { ufHref: event.href, ufParams: event.params } };
+  };
+  function actionFor(
+    names: $ReadOnlyArray<string>,
+    payload: NavigationPayload,
+    kind: "push" | "replace",
+  ): { readonly [string]: mixed } {
+    if (!ref.isReady()) throw new Error("Native navigation: NavigationContainer is not ready");
+    let state: NavigationState = ref.getRootState();
+    let depth = 0;
+    while (depth < names.length - 1) {
+      const active = state.routes[state.index ?? 0];
+      if (active?.name !== names[depth] || active?.state == null) break;
+      state = active.state;
+      depth += 1;
+    }
+    const name = names[depth];
+    const params = paramsForPath(names.slice(depth + 1), payload);
+    const action =
+      state.type === "stack"
+        ? StackActions[kind](name, params)
+        : CommonActions.navigate({ name, params });
+    return { ...action, target: state.key };
+  }
+  function navigate(href: string, kind: "push" | "replace"): void {
+    const { names, payload } = resolve(href);
+    ref.dispatch(actionFor(names, payload, kind));
+  }
+  const router: FileRouter = {
+    push: (href) => navigate(href, "push"),
+    replace: (href) => navigate(href, "replace"),
+    back: () => {
+      if (ref.canGoBack()) ref.goBack();
+    },
+    prefetch: createNativeRouter(table, {}).prefetch,
+  };
+  const source = options.links == null ? null : createNativeLinking(table, options.links);
+  const linking = {
+    prefixes: [""],
+    getInitialURL: source?.getInitialURL ?? (async () => null),
+    subscribe: source?.subscribe ?? (() => () => {}),
+    getStateFromPath: (href: string) => {
+      const { names, payload } = resolve(
+        href.startsWith("/") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(href) ? href : `/${href}`,
+      );
+      return stateForPath(names, payload);
+    },
+    getPathFromState: (state: NavigationState) => hrefFromState(state) ?? "/",
+    getActionFromState: (state: NavigationState) => {
+      const href = hrefFromState(state);
+      if (href == null) return undefined;
+      const { names, payload } = resolve(href);
+      return actionFor(names, payload, "push");
+    },
+  };
+  function build(node: NativeNode): React.ComponentType<{ ... }> {
+    const load = node.module;
+    const Content =
+      load == null
+        ? Stack
+        : React.lazy(async () => {
+            const module: $FlowFixMe = await load();
+            const Component = module.default ?? (node.layout ? module.Layout : module.Page);
+            if (
+              typeof Component !== "function" &&
+              (Component == null || typeof Component !== "object")
+            ) {
+              throw new Error(
+                `Native navigation: ${node.name} must export ${node.layout ? "Layout" : "Page"} or default`,
+              );
+            }
+            return { default: Component };
+          });
+    function Screen(props: { ... }): React.Node {
+      return (
+        <ScopeContext value={{ tree, node, screens, stack, tabs, router }}>
+          <React.Suspense fallback={null}>
+            <Content {...props} />
+          </React.Suspense>
+        </ScopeContext>
+      );
+    }
+    screens.set(node, Screen);
+    for (const child of node.children) build(child);
+    return Screen;
+  }
+  const RootScreen = build(tree.root);
+  const initialState =
+    options.initialHref == null ? undefined : linking.getStateFromPath(options.initialHref);
+  function Root(props: { ... }): React.Node {
+    return (
+      <NavigationContainer {...props} ref={ref} linking={linking} initialState={initialState}>
+        <RootScreen />
+      </NavigationContainer>
+    );
+  }
+  return { Root, router, linking };
+}
+
+/** Any React Navigation navigator can consume this segment's direct children. */
+export component Navigator(navigator: NavigatorPair, ...props: { ... }) {
+  const scope = useScope();
+  const Container = navigator.Navigator;
+  const Screen = navigator.Screen;
+  return (
+    <Container {...props}>
+      {scope.node.children.map((node) => (
+        <Screen key={node.name} name={node.name} component={scope.screens.get(node)} />
+      ))}
+    </Container>
+  );
+}
+
+export component Stack(...props: { ... }) {
+  return <Navigator {...props} navigator={useScope().stack} />;
+}
+
+export component Tabs(...props: { ... }) {
+  const tabs = useScope().tabs;
+  if (tabs == null)
+    throw new Error("Native navigation: supply the app's tab navigator to createNativeNavigation");
+  return <Navigator {...props} navigator={tabs} />;
+}
+
+export function useNativeRouter(): FileRouter {
+  return useScope().router;
+}
+export function useParams(): { readonly [string]: string | $ReadOnlyArray<string> } {
+  const route = useRoute();
+  return route.params?.ufParams ?? {};
+}
+
+export component Link(
+  href: string,
+  children: React.Node,
+  replace: boolean = false,
+  ...props: { ... }
+) {
+  const router = useNativeRouter();
+  return (
+    <Pressable
+      {...props}
+      accessibilityRole="link"
+      onPress={() => (replace ? router.replace(href) : router.push(href))}
+    >
+      {children}
+    </Pressable>
+  );
+}

package/native.js

@@ -28,6 +28,9 @@
 
 import type { RouteParams, RouteRecord, RouteTable } from "./internal/routing.js";
 import { hasClientPage, matchRoute, splitUrl } from "./internal/routing.js";
+import { nativeLinkHref } from "./internal/native-links.js";
+export { createNativeLinking } from "./internal/native-links.js";
+export type { NativeLinkSource } from "./internal/native-links.js";
 
 export type NativeNavigationKind = "push" | "replace" | "prefetch";
 
@@ -221,7 +224,7 @@ export function resolveNativeNavigation(
   to: string,
   kind?: NativeNavigationKind = "push",
 ): NativeNavigationEvent {
-  const href = normalizeNativeHref(to);
+  const href = normalizeNativeHref(to, table);
   const { pathname, search } = splitUrl(href);
   const matched = matchRoute(table.routes, pathname);
   if (matched == null) {
@@ -285,8 +288,13 @@ export function nativeScreenNavigationState(
   };
 }
 
-function normalizeNativeHref(to: string): string {
+function normalizeNativeHref(
+  to: string,
+  table: RouteTable<mixed, mixed, mixed, mixed, mixed>,
+): string {
   if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(to) || to.startsWith("//")) {
+    const claimed = nativeLinkHref(table, to);
+    if (claimed != null) return claimed;
     throw new NativeNavigationError(
       "external-url",
       `@uniflowed/router/native: ${to} is an external URL, and a native navigator needs an app route`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/router",
-  "version": "0.0.0-alpha.40",
+  "version": "0.0.0-alpha.42",
   "description": "The file-system router for Flow React applications: matching, layouts, loaders, navigation, server rendering and hydration.",
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,10 @@
     "./routing": "./routing.js",
     "./package.json": "./package.json",
     "./handler": "./handler.js",
-    "./middleware": "./middleware.js"
+    "./middleware": "./middleware.js",
+    "./native-navigation": "./native-navigation.js",
+    "./http-client": "./http-client.js",
+    "./instrumentation": "./instrumentation.js"
   },
   "files": [
     "action.js",
@@ -41,12 +44,17 @@
     "rsc.js",
     "server-components.js",
     "server.js",
+    "native-navigation.js",
+    "http-client.js",
+    "instrumentation.js",
     "!*.test.js"
   ],
   "peerDependencies": {
     "react": ">=19.2.3",
     "react-dom": ">=19.2.3",
-    "react-server-dom-parcel": ">=19.3.0"
+    "react-server-dom-parcel": ">=19.3.0",
+    "react-native": ">=0.86",
+    "@react-navigation/native": "^7.0.0"
   },
   "peerDependenciesMeta": {
     "react-dom": {
@@ -54,10 +62,16 @@
     },
     "react-server-dom-parcel": {
       "optional": true
+    },
+    "react-native": {
+      "optional": true
+    },
+    "@react-navigation/native": {
+      "optional": true
     }
   },
   "dependencies": {
-    "@uniflowed/hooks": "0.0.0-alpha.40",
-    "@uniflowed/server": "0.0.0-alpha.40"
+    "@uniflowed/hooks": "0.0.0-alpha.42",
+    "@uniflowed/server": "0.0.0-alpha.42"
   }
 }

package/rsc-ssr.js

@@ -27,7 +27,7 @@ import {
   installServerModules,
   readPayload,
 } from "./internal/flight-ssr.js";
-import { FLIGHT_CONTENT_TYPE, flightUrl } from "./internal/flight.js";
+import { FLIGHT_CONTENT_TYPE, INTERCEPTED_FROM_HEADER, flightUrl } from "./internal/flight.js";
 import { type StreamRecord, streamReporter } from "./internal/inspector.js";
 import { requireServerComponentsReact } from "./internal/react-version.js";
 import { RedirectError } from "./internal/routing.js";
@@ -312,9 +312,15 @@ export function createDocumentRenderer(options: DocumentRendererOptions): Render
 
   async function flight(
     url: string,
-    settings?: {| readonly onError?: (error: mixed) => void |},
+    settings?: {|
+      readonly onError?: (error: mixed) => void,
+      readonly interceptedFrom?: string,
+    |},
   ): Promise<FlightResponse> {
-    const rendered = await renderFlight(url, { onError: settings?.onError });
+    const rendered = await renderFlight(url, {
+      onError: settings?.onError,
+      interceptedFrom: settings?.interceptedFrom,
+    });
     if (rendered.kind === "redirect") {
       const { location } = rendered;
       // A redirect on this origin points at its target's payload, so the
@@ -330,7 +336,7 @@ export function createDocumentRenderer(options: DocumentRendererOptions): Render
     }
     return {
       status: rendered.status,
-      headers: { "content-type": FLIGHT_CONTENT_TYPE },
+      headers: { "content-type": FLIGHT_CONTENT_TYPE, vary: INTERCEPTED_FROM_HEADER },
       stream: rendered.stream,
       error: rendered.failure,
     };

package/rsc.js

@@ -44,6 +44,8 @@
 // in this graph, and a boundary module without the directive is refused here,
 // with its file named, rather than by React with a sentence about functions.
 
+import { traceLoader } from "./internal/server-instrumentation.js";
+
 import * as React from "react";
 import { use } from "react";
 // React's Flight server. Only this graph can load it: it refuses to evaluate
@@ -51,6 +53,7 @@ import { use } from "react";
 import { renderToReadableStream } from "react-server-dom-parcel/server";
 
 import { noteRoute } from "@uniflowed/server/host";
+import { reportRequestError } from "@uniflowed/server/instrumentation";
 
 import { BoundaryReporter } from "./internal/boundaries.js";
 import { routeBoundaries } from "./internal/boundary-data.js";
@@ -59,7 +62,7 @@ import { ErrorRoutePage } from "./internal/error-view.js";
 import { type FlightRoot, routeState } from "./internal/flight.js";
 import { requireServerComponentsReact } from "./internal/react-version.js";
 import type { ErrorModule, PageModule, ResolvedRoute, ResolvedSlot } from "./internal/resolve.js";
-import { resolveFailure, resolveMatch } from "./internal/resolve.js";
+import { resolveFailure, resolveInterception, resolveMatch } from "./internal/resolve.js";
 import type { RouteParams, RouteTable, SearchParams } from "./internal/routing.js";
 import { RedirectError, nearestBoundary } from "./internal/routing.js";
 import { withServerRoute } from "./internal/server-route.js";
@@ -95,6 +98,14 @@ export type FlightOptions = {|
    * did not.
    */
   readonly failure?: {| readonly error: mixed |},
+  /**
+   * The page a browser was showing when it asked for this payload.
+   *
+   * A document request never sets it. A client navigation may, because only the
+   * browser knows the page it is navigating from, while only this renderer can
+   * render the intercepted tree.
+   */
+  readonly interceptedFrom?: string,
   /** Stops the render, for a reader that went away. */
   readonly signal?: AbortSignal,
 |};
@@ -155,12 +166,22 @@ export function createFlightRenderer(options: {|
     let resolved: ResolvedRoute;
     try {
       const failure = settings?.failure;
-      resolved =
-        failure == null
-          ? // `onMatch` records the route pattern on the request before the
-            // loader runs, so every line the loader logs names its route.
-            await resolveMatch(table, url, { defer: settings?.defer !== false, onMatch: noteRoute })
-          : await resolveFailure(table, url, failure.error);
+      if (failure == null) {
+        const defer = settings?.defer !== false;
+        const intercepted = await resolveFlightInterception(
+          table,
+          url,
+          settings?.interceptedFrom,
+          defer,
+        );
+        resolved =
+          intercepted ??
+          // `onMatch` records the route pattern on the request before the
+          // loader runs, so every line the loader logs names its route.
+          (await resolveMatch(table, url, { defer, onMatch: noteRoute, runLoader: traceLoader }));
+      } else {
+        resolved = await resolveFailure(table, url, failure.error);
+      }
     } catch (error) {
       if (error instanceof RedirectError) {
         return { kind: "redirect", status: error.permanent ? 308 : 307, location: error.to };
@@ -181,13 +202,20 @@ export function createFlightRenderer(options: {|
       </>
     );
     const root: FlightRoot = { route: state, tree };
-    const report = settings?.onError;
+    const failure = renderFailure(route);
+    if (failure != null) reportRequestError(failure, "render");
+    const report = (error) => {
+      reportRequestError(error, "render");
+      if (settings?.onError != null) return settings.onError(error);
+      console.error(error);
+      return undefined;
+    };
     // Inside the route's store, so a server component's `useRoute()` finds the
     // route however many `await`s into the render it asks.
     const stream = withServerRoute(state, () =>
       renderToReadableStream(root, {
         // Handed over as it is, so that the digest it returns reaches the row.
-        // Absent, React logs the exception to the console itself.
+        // Our callback preserves React's console fallback when none was given.
         onError: report,
         signal: settings?.signal,
       }),
@@ -196,6 +224,39 @@ export function createFlightRenderer(options: {|
   };
 }
 
+async function resolveFlightInterception(
+  table: RouteTable,
+  url: string,
+  from: ?string,
+  defer: boolean,
+): Promise<?ResolvedRoute> {
+  const baseUrl = usableInterceptionBase(from);
+  if (baseUrl == null) {
+    return null;
+  }
+  try {
+    const base = await resolveMatch(table, baseUrl, {
+      defer,
+      onMatch: noteRoute,
+      runLoader: traceLoader,
+    });
+    return await resolveInterception(table, base, url);
+  } catch (error) {
+    if (error instanceof RedirectError) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+function usableInterceptionBase(from: ?string): ?string {
+  if (from == null || !from.startsWith("/") || from.startsWith("//")) {
+    return null;
+  }
+  const hash = from.indexOf("#");
+  return hash === -1 ? from : from.slice(0, hash);
+}
+
 /**
  * The page element: the route's page with its data, the deferred page that
  * waits for its loader, or the error route's page.

package/server-components.js

@@ -71,7 +71,7 @@ export type {
   TwitterCard,
 } from "./internal/runtime.js";
 
-export { Link, RouteView, RouterProvider, routerView } from "./internal/runtime.js";
+export { Link, RouteView, RouterProvider, routerView, useLinkStatus } from "./internal/runtime.js";
 // `app.router.basePath`, for a Server Component that builds an address itself.
 // The rsc entry installs it; `./internal/base-path.js` has no directive, so this
 // graph gets the function rather than a reference to it.

package/server.js

@@ -23,7 +23,9 @@
 // `internal/stream.js` holds the mechanics and says which React renderer serves
 // which.
 
-import { noteRoute } from "@uniflowed/server/host";
+import { currentNonce, noteRoute } from "@uniflowed/server/host";
+import { traceLoader } from "./internal/server-instrumentation.js";
+
 import * as React from "react";
 
 import {
@@ -44,7 +46,6 @@ import {
 } from "./internal/runtime.js";
 
 import { type StreamDiagnostic, streamReporter } from "./internal/inspector.js";
-import { currentNonce } from "@uniflowed/server/host";
 
 import { redirectDocument, redirectResult, shellFor } from "./internal/shell.js";
 
@@ -288,7 +289,10 @@ export type Renderer = {|
    */
   readonly flight?: (
     url: string,
-    options?: {| readonly onError?: (error: mixed) => void |},
+    options?: {|
+      readonly onError?: (error: mixed) => void,
+      readonly interceptedFrom?: string,
+    |},
   ) => Promise<FlightResponse>,
 |};
 
@@ -333,7 +337,11 @@ export function createRenderer(options: {|
     try {
       return {
         kind: "route",
-        route: await resolveMatch(table, url, { defer, onMatch: noteRoute }),
+        route: await resolveMatch(table, url, {
+          defer,
+          onMatch: noteRoute,
+          runLoader: traceLoader,
+        }),
       };
     } catch (error) {
       if (error instanceof RedirectError) {
@@ -510,3 +518,9 @@ export function shellDocument(assets: RenderAssets): string {
   const shell = shellFor(assets);
   return `${shell.open}${shell.body}${shell.close}`;
 }
+
+export {
+  createInstrumentation,
+  instrumentRender,
+  traceRequestPhase,
+} from "@uniflowed/server/instrumentation";