feat(core, react): Supports dynamic import for activities, and delays transition effects while loading an activity or waiting for a loader response

[tonyfromundefined]

New Event (Core)

• Provide PausedEvent and ResumedEvent to delay the effect of transitions.

New Interface (React)

import { lazy } from “@stackflow/react/future”;

stackflow({
  // ...
  components: {
    MyActivity: lazy(() => import(“../activities/MyActivity”)),
  },
});

(Note) This API is only supported by the Future API with Loader implementation

• If the Activity is declared as lazy(() => import(“...”)), emit a PausedEvent before importing the Activity and a ResumedEvent if the Activity is successfully imported or an error occurs.
• If the Activity has a loader declared, it raises a PausedEvent before executing the loader and a ResumedEvent when the loader state resolves.

Why does it have to be of the form lazy(() => import(“...”))?

Other candidates considered

// Plan A
stackflow({
  // ...
  components: {
    MyActivity: React.lazy(...),
  },
});

// Plan B
stackflow({
  // ...
  components: {
    MyActivity: () => import(“...”),
  },
});

• For plan A, we have an issue where we don't know if it's wrapped in React.lazy or not. To find out, we'd have to float it in the React environment, which we decided was an unnecessary overhead.
• Plan B also had the unnecessary overhead of having to run the function to evaluate whether the passed component or function returns a Promise or a React.ReactNode.

Therefore, I introduced a new construct lazy() that allows to statically evaluate whether the currently passed argument requires lazy loading or not.

[changeset-bot]

🦋 Changeset detected

Latest commit: cd68c76

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@stackflow/plugin-basic-ui	Minor
@stackflow/react	Minor
@stackflow/core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
stackflow-docs	✅ Ready (Inspect)	Visit Preview	Jan 24, 2025 5:39am

[tonyfromundefined]

(참고) load -> lazy로 변경했습니다. cc. @2woongjae

[orionmiz]

I'm really appreciating your works for the tricky issue.

Here's a question:
Is PausedEvent and ResumedEvent allowed to be made by the 3rd-party users working with the plugins other than the integrations?

If so, please consider adding the hook interfaces for the plugin. (onBeforePaused, ...)

If not, hide those as internal events and block the event creation from calling dispatchEvent.

[tonyfromundefined]

@orionmiz I just finished reflecting your review, please review again.

[orionmiz]

My stack reducer proposal is accepted in kind of the different way I expected. (aspect of impureness for reducers)
May I create another pull request heading this branch?

[orionmiz]

It seems best to allow errors to be caught at the integration level, but quiet resuming in the core level could be confusing to the users. Wouldn't it be better to show a warning message?