feat(react/future): Add prefetch API for lazy activity component and loader data.

.changeset/slick-heads-tan.md

@@ -0,0 +1,7 @@
+---
+"@stackflow/react": minor
+---
+
+Add prefetch API for lazy activity component and loader data.
+- A hook `usePrepare()` which returns `prepare(activityName[, activityParams])` is added for navigation warmup.
+- A hook `useActivityPreparation(activities)` for preparing navigations inside a component is added.

config/src/ActivityLoader.ts

@@ -1,6 +1,19 @@
 import type { ActivityLoaderArgs } from "./ActivityLoaderArgs";
 import type { RegisteredActivityName } from "./RegisteredActivityName";
 
-export type ActivityLoader<ActivityName extends RegisteredActivityName> = (
-  args: ActivityLoaderArgs<ActivityName>,
-) => any;
+export type ActivityLoader<ActivityName extends RegisteredActivityName> = {
+  (args: ActivityLoaderArgs<ActivityName>): any;
+  loaderCacheMaxAge?: number;
+};
+
+export function loader<ActivityName extends RegisteredActivityName>(
+  loaderFn: (args: ActivityLoaderArgs<ActivityName>) => any,
+  options?: {
+    loaderCacheMaxAge?: number;
+  },
+): ActivityLoader<ActivityName> {
+  return Object.assign(
+    (args: ActivityLoaderArgs<ActivityName>) => loaderFn(args),
+    options,
+  );
+}

integrations/react/src/__internal__/ActivityComponentMapProvider.tsx

@@ -0,0 +1,38 @@
+import type { RegisteredActivityName } from "@stackflow/config";
+import type { PropsWithChildren } from "react";
+import { createContext, useContext } from "react";
+import type { ActivityComponentType } from "./ActivityComponentType";
+
+const ActivityComponentMapContext = createContext<
+  | {
+      [activityName in RegisteredActivityName]: ActivityComponentType;
+    }
+  | null
+>(null);
+
+export function useActivityComponentMap() {
+  const context = useContext(ActivityComponentMapContext);
+  if (context === null) {
+    throw new Error(
+      "useActivityComponentMap must be used within ActivityComponentMapProvider",
+    );
+  }
+  return context;
+}
+
+type ActivityComponentMapProviderProps = PropsWithChildren<{
+  value: {
+    [activityName in RegisteredActivityName]: ActivityComponentType;
+  };
+}>;
+
+export function ActivityComponentMapProvider({
+  children,
+  value,
+}: ActivityComponentMapProviderProps) {
+  return (
+    <ActivityComponentMapContext.Provider value={value}>
+      {children}
+    </ActivityComponentMapContext.Provider>
+  );
+}

integrations/react/src/__internal__/MainRenderer.tsx

@@ -7,15 +7,9 @@ import { StackProvider } from "./stack";
 import type { WithRequired } from "./utils";
 
 interface MainRendererProps {
-  activityComponentMap: {
-    [key: string]: ActivityComponentType;
-  };
   initialContext: any;
 }
-const MainRenderer: React.FC<MainRendererProps> = ({
-  activityComponentMap,
-  initialContext,
-}) => {
+const MainRenderer: React.FC<MainRendererProps> = ({ initialContext }) => {
   const coreState = useCoreState();
   const plugins = usePlugins();
 
@@ -40,7 +34,6 @@ const MainRenderer: React.FC<MainRendererProps> = ({
       {renderingPlugins.map((plugin) => (
         <PluginRenderer
           key={plugin.key}
-          activityComponentMap={activityComponentMap}
           plugin={plugin}
           initialContext={initialContext}
         />

integrations/react/src/__internal__/PluginRenderer.tsx

@@ -1,23 +1,20 @@
 import type React from "react";
-import type { ActivityComponentType } from "./ActivityComponentType";
+import { useActivityComponentMap } from "./ActivityComponentMapProvider";
 import { ActivityProvider } from "./activity";
 import { useCoreState } from "./core";
 import { usePlugins } from "./plugins";
 import type { StackflowReactPlugin } from "./StackflowReactPlugin";
 import type { WithRequired } from "./utils";
 
 interface PluginRendererProps {
-  activityComponentMap: {
-    [key: string]: ActivityComponentType;
-  };
   plugin: WithRequired<ReturnType<StackflowReactPlugin>, "render">;
   initialContext: any;
 }
 const PluginRenderer: React.FC<PluginRendererProps> = ({
-  activityComponentMap,
   plugin,
   initialContext,
 }) => {
+  const activityComponentMap = useActivityComponentMap();
   const coreState = useCoreState();
   const plugins = usePlugins();
 

integrations/react/src/__internal__/utils/isPromiseLike.ts

@@ -0,0 +1,8 @@
+export function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "then" in value &&
+    typeof value.then === "function"
+  );
+}

integrations/react/src/future/index.ts

@@ -1,28 +1,16 @@
-/**
- * Main
- */
-
 export * from "../__internal__/activity/useActivity";
-
-/**
- * Types
- */
 export * from "../__internal__/StackflowReactPlugin";
-/**
- * Hooks
- */
 export * from "../__internal__/stack/useStack";
 export * from "./Actions";
 export * from "./ActivityComponentType";
-/**
- * Utils
- */
 export * from "./lazy";
 export * from "./loader/useLoaderData";
 export * from "./StackComponentType";
 export * from "./StepActions";
 export * from "./stackflow";
 export * from "./useActivityParams";
+export * from "./useActivityPreparation";
 export * from "./useConfig";
 export * from "./useFlow";
+export * from "./usePrepare";
 export * from "./useStepFlow";

integrations/react/src/future/lazy.ts

@@ -5,12 +5,17 @@ import type { StaticActivityComponentType } from "../__internal__/StaticActivity
 export function lazy<T extends { [K in keyof T]: any } = {}>(
   load: () => Promise<{ default: StaticActivityComponentType<T> }>,
 ): LazyActivityComponentType<T> {
-  let cachedValue: { default: StaticActivityComponentType<T> } | null = null;
+  let cachedValue: Promise<{ default: StaticActivityComponentType<T> }> | null =
+    null;
 
-  const cachedLoad = async () => {
+  const cachedLoad = () => {
     if (!cachedValue) {
-      const value = await load();
-      cachedValue = value;
+      cachedValue = load();
+      cachedValue.catch((error) => {
+        cachedValue = null;
+
+        throw error;
+      });
     }
     return cachedValue;
   };

integrations/react/src/future/loader/DataLoaderContext.tsx

@@ -0,0 +1,29 @@
+import { createContext, type ReactNode, useContext } from "react";
+
+export const DataLoaderContext = createContext<
+  ((activityName: string, activityParams: {}) => unknown) | null
+>(null);
+
+export function DataLoaderProvider({
+  loadData,
+  children,
+}: {
+  loadData: (activityName: string, activityParams: {}) => unknown;
+  children: ReactNode;
+}) {
+  return (
+    <DataLoaderContext.Provider value={loadData}>
+      {children}
+    </DataLoaderContext.Provider>
+  );
+}
+
+export function useDataLoader() {
+  const loadData = useContext(DataLoaderContext);
+
+  if (!loadData) {
+    throw new Error("useDataLoader() must be used within a DataLoaderProvider");
+  }
+
+  return loadData;
+}

integrations/react/src/future/loader/index.ts

@@ -1,2 +1,3 @@
+export * from "./DataLoaderContext";
 export * from "./loaderPlugin";
 export * from "./useLoaderData";

integrations/react/src/future/loader/loaderPlugin.tsx

@@ -4,74 +4,79 @@ import type {
 } from "@stackflow/config";
 import type { ActivityComponentType } from "../../__internal__/ActivityComponentType";
 import type { StackflowReactPlugin } from "../../__internal__/StackflowReactPlugin";
+import { isPromiseLike } from "../../__internal__/utils/isPromiseLike";
 import type { StackflowInput } from "../stackflow";
 
 export function loaderPlugin<
   T extends ActivityDefinition<RegisteredActivityName>,
   R extends {
     [activityName in RegisteredActivityName]: ActivityComponentType<any>;
   },
->(input: StackflowInput<T, R>): StackflowReactPlugin {
-  return () => ({
-    key: "plugin-loader",
-    overrideInitialEvents({ initialEvents, initialContext }) {
-      if (initialEvents.length === 0) {
-        return [];
-      }
-
-      return initialEvents.map((event) => {
-        if (event.name !== "Pushed") {
-          return event;
+>(
+  input: StackflowInput<T, R>,
+  loadData: (activityName: string, activityParams: {}) => unknown,
+): StackflowReactPlugin {
+  return () => {
+    return {
+      key: "plugin-loader",
+      overrideInitialEvents({ initialEvents, initialContext }) {
+        if (initialEvents.length === 0) {
+          return [];
         }
 
-        if (initialContext.initialLoaderData) {
+        return initialEvents.map((event) => {
+          if (event.name !== "Pushed") {
+            return event;
+          }
+
+          if (initialContext.initialLoaderData) {
+            return {
+              ...event,
+              activityContext: {
+                ...event.activityContext,
+                loaderData: initialContext.initialLoaderData,
+              },
+            };
+          }
+
+          const { activityName, activityParams } = event;
+
+          const matchActivity = input.config.activities.find(
+            (activity) => activity.name === activityName,
+          );
+
+          const loader = matchActivity?.loader;
+
+          if (!loader) {
+            return event;
+          }
+
+          const loaderData = loadData(activityName, activityParams);
+
+          if (isPromiseLike(loaderData)) {
+            Promise.allSettled([loaderData]).then(
+              ([loaderDataPromiseResult]) => {
+                printLoaderDataPromiseError({
+                  promiseResult: loaderDataPromiseResult,
+                  activityName: matchActivity.name,
+                });
+              },
+            );
+          }
+
           return {
             ...event,
             activityContext: {
               ...event.activityContext,
-              loaderData: initialContext.initialLoaderData,
+              loaderData,
             },
           };
-        }
-
-        const { activityName, activityParams } = event;
-
-        const matchActivity = input.config.activities.find(
-          (activity) => activity.name === activityName,
-        );
-
-        const loader = matchActivity?.loader;
-
-        if (!loader) {
-          return event;
-        }
-
-        const loaderData = loader({
-          params: activityParams,
-          config: input.config,
         });
-
-        if (loaderData instanceof Promise) {
-          Promise.allSettled([loaderData]).then(([loaderDataPromiseResult]) => {
-            printLoaderDataPromiseError({
-              promiseResult: loaderDataPromiseResult,
-              activityName: matchActivity.name,
-            });
-          });
-        }
-
-        return {
-          ...event,
-          activityContext: {
-            ...event.activityContext,
-            loaderData,
-          },
-        };
-      });
-    },
-    onBeforePush: createBeforeRouteHandler(input),
-    onBeforeReplace: createBeforeRouteHandler(input),
-  });
+      },
+      onBeforePush: createBeforeRouteHandler(input, loadData),
+      onBeforeReplace: createBeforeRouteHandler(input, loadData),
+    };
+  };
 }
 
 type OnBeforeRoute = NonNullable<
@@ -83,7 +88,10 @@ function createBeforeRouteHandler<
   R extends {
     [activityName in RegisteredActivityName]: ActivityComponentType<any>;
   },
->(input: StackflowInput<T, R>): OnBeforeRoute {
+>(
+  input: StackflowInput<T, R>,
+  loadData: (activityName: string, activityParams: {}) => unknown,
+): OnBeforeRoute {
   return ({
     actionParams,
     actions: { overrideActionParams, pause, resume },
@@ -99,13 +107,12 @@ function createBeforeRouteHandler<
       return;
     }
 
-    const loaderData = matchActivity.loader?.({
-      params: activityParams,
-      config: input.config,
-    });
+    const loaderData =
+      matchActivity.loader && loadData(activityName, activityParams);
 
-    const loaderDataPromise =
-      loaderData instanceof Promise ? loaderData : undefined;
+    const loaderDataPromise = isPromiseLike(loaderData)
+      ? loaderData
+      : undefined;
     const lazyComponentPromise =
       "_load" in matchActivityComponent
         ? matchActivityComponent._load?.()

integrations/react/src/future/makeActions.ts

@@ -35,10 +35,10 @@ export function makeActions(
       };
     },
     replace(activityName, activityParams, options) {
-      const activityId = makeActivityId();
+      const activityId = options?.activityId ?? makeActivityId();
 
       getCoreActions()?.replace({
-        activityId: options?.activityId ?? makeActivityId(),
+        activityId,
         activityName,
         activityParams,
         skipEnterActiveState: parseActionOptions(options).skipActiveState,