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(activityNames)` for preparing navigations inside a component is added.

integrations/react/src/__internal__/ActivityComponentMapProvider.tsx

@@ -0,0 +1,38 @@
+import type { RegisteredActivityName } from "@stackflow/config";
+import type { PropsWithChildren } from "react";
+import type { ActivityComponentType } from "./ActivityComponentType";
+import { createContext, useContext } from "react";
+
+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,75 +1,72 @@
 import type React from "react";
-import type { ActivityComponentType } from "./ActivityComponentType";
+import { useActivityComponentMap } from "./ActivityComponentMapProvider";
+import type { StackflowReactPlugin } from "./StackflowReactPlugin";
 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;
+	plugin: WithRequired<ReturnType<StackflowReactPlugin>, "render">;
+	initialContext: any;
 }
 const PluginRenderer: React.FC<PluginRendererProps> = ({
-  activityComponentMap,
-  plugin,
-  initialContext,
+	plugin,
+	initialContext,
 }) => {
-  const coreState = useCoreState();
-  const plugins = usePlugins();
+	const activityComponentMap = useActivityComponentMap();
+	const coreState = useCoreState();
+	const plugins = usePlugins();
 
-  return plugin.render({
-    stack: {
-      ...coreState,
-      render(overrideStack) {
-        const stack = {
-          ...coreState,
-          ...overrideStack,
-        };
+	return plugin.render({
+		stack: {
+			...coreState,
+			render(overrideStack) {
+				const stack = {
+					...coreState,
+					...overrideStack,
+				};
 
-        return {
-          activities: stack.activities.map((activity) => ({
-            ...activity,
-            key: activity.id,
-            render(overrideActivity) {
-              const Activity = activityComponentMap[activity.name];
+				return {
+					activities: stack.activities.map((activity) => ({
+						...activity,
+						key: activity.id,
+						render(overrideActivity) {
+							const Activity = activityComponentMap[activity.name];
 
-              let output: React.ReactNode = (
-                <Activity params={activity.params} />
-              );
+							let output: React.ReactNode = (
+								<Activity params={activity.params} />
+							);
 
-              plugins.forEach((p) => {
-                output =
-                  p.wrapActivity?.({
-                    activity: {
-                      ...activity,
-                      render: () => output,
-                    },
-                    initialContext,
-                  }) ?? output;
-              });
+							plugins.forEach((p) => {
+								output =
+									p.wrapActivity?.({
+										activity: {
+											...activity,
+											render: () => output,
+										},
+										initialContext,
+									}) ?? output;
+							});
 
-              return (
-                <ActivityProvider
-                  key={activity.id}
-                  value={{
-                    ...activity,
-                    ...overrideActivity,
-                  }}
-                >
-                  {output}
-                </ActivityProvider>
-              );
-            },
-          })),
-        };
-      },
-    },
-    initialContext,
-  });
+							return (
+								<ActivityProvider
+									key={activity.id}
+									value={{
+										...activity,
+										...overrideActivity,
+									}}
+								>
+									{output}
+								</ActivityProvider>
+							);
+						},
+					})),
+				};
+			},
+		},
+		initialContext,
+	});
 };
 
 PluginRenderer.displayName = "PluginRenderer";

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

@@ -0,0 +1,15 @@
+export interface Thenable<T> {
+  then<R>(
+    onFulfilled: (value: T) => R,
+    onRejected?: (reason: unknown) => R,
+  ): Thenable<Awaited<R>>;
+}
+
+export function isThenable(value: unknown): value is Thenable<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 "./usePrepare";
 export * from "./useConfig";
 export * from "./useFlow";
 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";