feat(react): stabilize lazy load plugin

.changeset/spotty-comics-build.md

@@ -0,0 +1,5 @@
+---
+"@stackflow/react": minor
+---
+
+feat(react): stabilize lazy load plugin

integrations/react/src/future/index.ts

@@ -26,4 +26,4 @@ export * from "./useConfig";
 /**
  * Utils
  */
-export * from "./lazy";
+export * from "../__internal__/lazy";

integrations/react/src/stable/LazyLoadPlugin.ts

@@ -0,0 +1,67 @@
+import type { StackflowReactPlugin } from "../__internal__/StackflowReactPlugin";
+import type { BaseActivities } from "./BaseActivities";
+import type { StackflowOptions } from "./stackflow";
+
+export function lazyLoadPlugin<T extends BaseActivities>(
+  options: StackflowOptions<T>,
+): StackflowReactPlugin {
+  return () => ({
+    key: "plugin-lazy-load",
+    onBeforePush: createBeforeRouteHandler(options),
+    onBeforeReplace: createBeforeRouteHandler(options),
+  });
+}
+
+type OnBeforeRoute = NonNullable<
+  | ReturnType<StackflowReactPlugin>["onBeforePush"]
+  | ReturnType<StackflowReactPlugin>["onBeforeReplace"]
+>;
+
+function createBeforeRouteHandler<T extends BaseActivities>(
+  options: StackflowOptions<T>,
+): OnBeforeRoute {
+  return ({ actionParams, actions: { pause, resume } }) => {
+    const { activityName } = actionParams;
+
+    const matchActivityComponent = options.activities[activityName];
+
+    if (!matchActivityComponent) {
+      return;
+    }
+
+    const lazyComponentPromise =
+      "_load" in matchActivityComponent
+        ? matchActivityComponent._load?.()
+        : undefined;
+
+    if (!lazyComponentPromise) {
+      return;
+    }
+
+    pause();
+
+    lazyComponentPromise
+      .catch((reason) => {
+        printLazyComponentPromiseError({
+          reason,
+          activityName,
+        });
+      })
+      .finally(() => {
+        resume();
+      });
+  };
+}
+
+function printLazyComponentPromiseError({
+  reason,
+  activityName,
+}: {
+  reason: PromiseRejectedResult["reason"];
+  activityName: string;
+}) {
+  console.error(reason);
+  console.error(
+    `The above error occurred while loading a lazy react component of the "${activityName}" activity`,
+  );
+}

integrations/react/src/stable/index.ts

@@ -9,3 +9,4 @@ export * from "./useActiveEffect";
 export * from "./useEnterDoneEffect";
 export * from "./useStep";
 export * from "./useStepActions";
+export * from "../__internal__/lazy";

integrations/react/src/stable/stackflow.tsx

@@ -20,6 +20,7 @@ import { CoreProvider } from "../__internal__/core";
 import { PluginsProvider } from "../__internal__/plugins";
 import { isBrowser, makeRef } from "../__internal__/utils";
 import type { BaseActivities } from "./BaseActivities";
+import { lazyLoadPlugin } from "./LazyLoadPlugin";
 import type { UseActionsOutputType } from "./useActions";
 import { useActions } from "./useActions";
 import type { UseStepActionsOutputType } from "./useStepActions";
@@ -129,9 +130,12 @@ export type StackflowOutput<T extends BaseActivities> = {
 export function stackflow<T extends BaseActivities>(
   options: StackflowOptions<T>,
 ): StackflowOutput<T> {
-  const plugins = (options.plugins ?? [])
-    .flat(Number.POSITIVE_INFINITY as 0)
-    .map((p) => p as StackflowReactPlugin);
+  const plugins = [
+    ...(options.plugins ?? [])
+      .flat(Number.POSITIVE_INFINITY as 0)
+      .map((p) => p as StackflowReactPlugin),
+    lazyLoadPlugin(options),
+  ];
 
   const activityComponentMap = Object.entries(options.activities).reduce(
     (acc, [key, Activity]) => ({