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

.changeset/chilled-hats-love.md

@@ -0,0 +1,7 @@
+---
+"@stackflow/plugin-basic-ui": minor
+"@stackflow/react": minor
+"@stackflow/core": minor
+---
+
+Supports dynamic import for activities, and delays transition effects while loading an activity or waiting for a loader response

core/src/Stack.ts

@@ -47,5 +47,5 @@ export type Stack = {
   activities: Activity[];
   registeredActivities: RegisteredActivity[];
   transitionDuration: number;
-  globalTransitionState: "idle" | "loading";
+  globalTransitionState: "idle" | "loading" | "paused";
 };

core/src/activity-utils/makeActivitiesReducers.ts

@@ -3,9 +3,11 @@ import type {
   ActivityRegisteredEvent,
   DomainEvent,
   InitializedEvent,
+  PausedEvent,
   PoppedEvent,
   PushedEvent,
   ReplacedEvent,
+  ResumedEvent,
   StepPoppedEvent,
   StepPushedEvent,
   StepReplacedEvent,
@@ -89,4 +91,14 @@ export const makeActivitiesReducers = (isTransitionDone: boolean) =>
      */
     StepPopped: (activities: Activity[], event: StepPoppedEvent): Activity[] =>
       activities,
+
+    /**
+     * noop
+     */
+    Paused: (activities: Activity[], event: PausedEvent) => activities,
+
+    /**
+     * noop
+     */
+    Resumed: (activities: Activity[], event: ResumedEvent) => activities,
   });

core/src/activity-utils/makeActivityReducers.ts

@@ -116,4 +116,14 @@ export const makeActivityReducers = (isTransitionDone: boolean) =>
         params: beforeActivityParams ?? activity.params,
       };
     },
+
+    /**
+     * noop
+     */
+    Paused: (activity: Activity) => activity,
+
+    /**
+     * noop
+     */
+    Resumed: (activity: Activity) => activity,
   } as const);

core/src/aggregate.spec.ts

@@ -3931,3 +3931,155 @@ test("aggregate - StepPushedEvent must be ignored when top activity is not targe
     globalTransitionState: "idle",
   });
 });
+
+test("aggregate - Pause되면 이벤트가 반영되지 않고, globalTransitionState를 paused으로 바꿉니다", () => {
+  let pushedEvent1: PushedEvent;
+  let pushedEvent2: PushedEvent;
+
+  const events = [
+    initializedEvent({
+      transitionDuration: 300,
+    }),
+    registeredEvent({
+      activityName: "a",
+    }),
+    registeredEvent({
+      activityName: "b",
+    }),
+    (pushedEvent1 = makeEvent("Pushed", {
+      activityId: "activity-1",
+      activityName: "a",
+      eventDate: enoughPastTime(),
+      activityParams: {},
+    })),
+    makeEvent("Paused", {}),
+    (pushedEvent2 = makeEvent("Pushed", {
+      activityId: "activity-2",
+      activityName: "b",
+      activityParams: {},
+    })),
+  ];
+
+  const output = aggregate(events, nowTime());
+
+  expect(output).toStrictEqual({
+    activities: [
+      activity({
+        id: "activity-1",
+        name: "a",
+        transitionState: "enter-done",
+        params: {},
+        steps: [
+          {
+            id: "activity-1",
+            params: {},
+            enteredBy: pushedEvent1,
+          },
+        ],
+        enteredBy: pushedEvent1,
+        isActive: true,
+        isTop: true,
+        isRoot: true,
+        zIndex: 0,
+      }),
+    ],
+    registeredActivities: [
+      {
+        name: "a",
+      },
+      {
+        name: "b",
+      },
+    ],
+    transitionDuration: 300,
+    globalTransitionState: "paused",
+  });
+});
+
+test("aggregate - Resumed 되면 해당 시간 이후로 Transition이 정상작동합니다", () => {
+  let pushedEvent1: PushedEvent;
+  let pushedEvent2: PushedEvent;
+
+  const events = [
+    initializedEvent({
+      transitionDuration: 300,
+    }),
+    registeredEvent({
+      activityName: "a",
+    }),
+    registeredEvent({
+      activityName: "b",
+    }),
+    (pushedEvent1 = makeEvent("Pushed", {
+      activityId: "activity-1",
+      activityName: "a",
+      eventDate: enoughPastTime(),
+      activityParams: {},
+    })),
+    makeEvent("Paused", {
+      eventDate: enoughPastTime(),
+    }),
+    (pushedEvent2 = makeEvent("Pushed", {
+      activityId: "activity-2",
+      activityName: "b",
+      eventDate: enoughPastTime(),
+      activityParams: {},
+    })),
+    makeEvent("Resumed", {
+      eventDate: nowTime() - 150,
+    }),
+  ];
+
+  const output = aggregate(events, nowTime());
+
+  expect(output).toStrictEqual({
+    activities: [
+      activity({
+        id: "activity-1",
+        name: "a",
+        transitionState: "enter-done",
+        params: {},
+        steps: [
+          {
+            id: "activity-1",
+            params: {},
+            enteredBy: expect.anything(),
+          },
+        ],
+        enteredBy: expect.anything(),
+        isActive: false,
+        isTop: false,
+        isRoot: true,
+        zIndex: 0,
+      }),
+      activity({
+        id: "activity-2",
+        name: "b",
+        transitionState: "enter-active",
+        params: {},
+        steps: [
+          {
+            id: "activity-2",
+            params: {},
+            enteredBy: expect.anything(),
+          },
+        ],
+        enteredBy: expect.anything(),
+        isActive: true,
+        isTop: true,
+        isRoot: false,
+        zIndex: 1,
+      }),
+    ],
+    registeredActivities: [
+      {
+        name: "a",
+      },
+      {
+        name: "b",
+      },
+    ],
+    transitionDuration: 300,
+    globalTransitionState: "loading",
+  });
+});

core/src/aggregate.ts

@@ -6,19 +6,69 @@ import type { DomainEvent } from "./event-types";
 import { filterEvents, validateEvents } from "./event-utils";
 import { compareBy, uniqBy } from "./utils";
 
-export function aggregate(events: DomainEvent[], now: number): Stack {
+export function aggregate(inputEvents: DomainEvent[], now: number): Stack {
+  /**
+   * 1. Sorting by event ID (K-Sortable)
+   *
+   * The backward action may cause past events to be put behind, so when those events are dispatched, move them forward.
+   */
   const sortedEvents = uniqBy(
-    [...events].sort((a, b) => compareBy(a, b, (e) => e.id)),
+    [...inputEvents].sort((a, b) => compareBy(a, b, (e) => e.id)),
     (e) => e.id,
   );
 
-  validateEvents(sortedEvents);
-
-  const initEvent = filterEvents(sortedEvents, "Initialized")[0];
-  const activityRegisteredEvents = filterEvents(events, "ActivityRegistered");
+  /**
+   * 2. Handle `PausedEvent` and `ResumedEvent`
+   *
+   * 2-1. If a `PausedEvent` is fired, handle it so that all events after the pause are deleted
+   * (Transitions of events that have already happened will ensure normal behavior)
+   * 2-2. If a `ResumedEvent` is fired, handle it by delaying the `eventCreatedAt` of events
+   * after the pause by that much (`dt`)
+   */
+  const pauseAndResumeHandledEvents: DomainEvent[] = [];
+  let eventBufferAfterPaused: DomainEvent[] = [];
+
+  let pausedAt: number | null = null;
+
+  for (const event of sortedEvents) {
+    if (event.name === "Paused") {
+      pausedAt = event.eventDate;
+      continue;
+    }
+    if (event.name === "Resumed" && pausedAt) {
+      const dt = event.eventDate - pausedAt;
+
+      for (const pausedEvent of eventBufferAfterPaused) {
+        pauseAndResumeHandledEvents.push({
+          ...pausedEvent,
+          eventDate: pausedEvent.eventDate + dt,
+        });
+      }
+
+      pausedAt = null;
+      eventBufferAfterPaused = [];
+      continue;
+    }
+
+    if (pausedAt) {
+      eventBufferAfterPaused.push(event);
+    } else {
+      pauseAndResumeHandledEvents.push(event);
+    }
+  }
+
+  const events = pauseAndResumeHandledEvents;
+
+  validateEvents(events);
+
+  const initEvent = filterEvents(events, "Initialized")[0];
+  const activityRegisteredEvents = filterEvents(
+    inputEvents,
+    "ActivityRegistered",
+  );
   const { transitionDuration } = initEvent;
 
-  const activities = sortedEvents.reduce(
+  const activities = events.reduce(
     (activities: Activity[], event: DomainEvent) => {
       const isTransitionDone = now - event.eventDate >= transitionDuration;
 
@@ -63,13 +113,15 @@ export function aggregate(events: DomainEvent[], now: number): Stack {
   const lastVisibleActivity = visibleActivities[visibleActivities.length - 1];
   const lastEnteredActivity = enteredActivities[enteredActivities.length - 1];
 
-  const globalTransitionState = activities.find(
-    (activity) =>
-      activity.transitionState === "enter-active" ||
-      activity.transitionState === "exit-active",
-  )
-    ? "loading"
-    : "idle";
+  const globalTransitionState = pausedAt
+    ? "paused"
+    : activities.find(
+          (activity) =>
+            activity.transitionState === "enter-active" ||
+            activity.transitionState === "exit-active",
+        )
+      ? "loading"
+      : "idle";
 
   const output: Stack = {
     activities: uniqActivities

core/src/event-types/PausedEvent.ts

@@ -0,0 +1,3 @@
+import type { BaseDomainEvent } from "./_base";
+
+export type PausedEvent = BaseDomainEvent<"Paused", {}>;

core/src/event-types/ResumedEvent.ts

@@ -0,0 +1,3 @@
+import type { BaseDomainEvent } from "./_base";
+
+export type ResumedEvent = BaseDomainEvent<"Resumed", {}>;

core/src/event-types/index.ts

@@ -1,8 +1,10 @@
 import type { ActivityRegisteredEvent } from "./ActivityRegisteredEvent";
 import type { InitializedEvent } from "./InitializedEvent";
+import type { PausedEvent } from "./PausedEvent";
 import type { PoppedEvent } from "./PoppedEvent";
 import type { PushedEvent } from "./PushedEvent";
 import type { ReplacedEvent } from "./ReplacedEvent";
+import type { ResumedEvent } from "./ResumedEvent";
 import type { StepPoppedEvent } from "./StepPoppedEvent";
 import type { StepPushedEvent } from "./StepPushedEvent";
 import type { StepReplacedEvent } from "./StepReplacedEvent";
@@ -15,7 +17,9 @@ export type DomainEvent =
   | StepReplacedEvent
   | PoppedEvent
   | PushedEvent
-  | ReplacedEvent;
+  | ReplacedEvent
+  | PausedEvent
+  | ResumedEvent;
 
 export * from "./ActivityRegisteredEvent";
 export * from "./InitializedEvent";
@@ -25,3 +29,5 @@ export * from "./ReplacedEvent";
 export * from "./StepPoppedEvent";
 export * from "./StepPushedEvent";
 export * from "./StepReplacedEvent";
+export * from "./PausedEvent";
+export * from "./ResumedEvent";