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

Author: ENvironmentSet

.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";