@player-ui/player 0.8.0--canary.307.9621 → 0.8.0-next.0

package/src/controllers/flow/__tests__/controller.test.ts

@@ -0,0 +1,195 @@
+import { it, expect, vitest } from "vitest";
+import { FlowController } from "..";
+
+it("ends when the flow does", async () => {
+  const controller = new FlowController({
+    BEGIN: "foo",
+    foo: {
+      startState: "View1",
+      View1: {
+        state_type: "VIEW",
+        ref: "foo",
+        transitions: {
+          "*": "End",
+        },
+      },
+      End: {
+        state_type: "END",
+        outcome: "yay",
+      },
+    },
+  });
+  const controllerResult = controller.start();
+  controller.transition("foo");
+  const { outcome } = await controllerResult;
+  expect(outcome).toBe("yay");
+});
+
+it("calls another flow", async () => {
+  const controller = new FlowController({
+    BEGIN: "foo",
+    foo: {
+      startState: "View1",
+      View1: {
+        state_type: "VIEW",
+        ref: "foo",
+        transitions: {
+          "foo-1": "Flow2",
+        },
+      },
+      Flow2: {
+        state_type: "FLOW",
+        ref: "bar",
+        transitions: {
+          yay: "End",
+        },
+      },
+      End: {
+        state_type: "END",
+        outcome: "yay",
+      },
+    },
+    bar: {
+      startState: "View2",
+      View2: {
+        state_type: "VIEW",
+        ref: "bar",
+        transitions: {
+          "foo-2": "Done",
+        },
+      },
+      Done: {
+        state_type: "END",
+        outcome: "yay",
+      },
+    },
+  });
+
+  const controllerResult = controller.start();
+  expect(controller.current?.id).toBe("foo");
+  controller.transition("foo-1");
+  expect(controller.current?.id).toBe("bar");
+  controller.transition("foo-2");
+
+  const { outcome } = await controllerResult;
+  expect(outcome).toBe("yay");
+  expect(controller.current?.id).toBe("foo");
+});
+
+it("can switch between parent and sub flow", async () => {
+  const controller = new FlowController({
+    BEGIN: "Flow-1",
+    "Flow-1": {
+      startState: "Initial",
+      END_Back: {
+        outcome: "backBeforeTopic",
+        state_type: "END",
+      },
+      "Go-To-Flow-2": {
+        state_type: "FLOW",
+        ref: "Flow-2",
+        transitions: {
+          "*": "Initial",
+        },
+      },
+      Initial: {
+        ref: "Initial-View",
+        state_type: "VIEW",
+        transitions: {
+          Prev: "END_Back",
+          "*": "Go-To-Flow-2",
+        },
+        nodeName: "Initial",
+        fromAction: null,
+      },
+    },
+    "Flow-2": {
+      startState: "Result",
+      END_Done: {
+        state_type: "END",
+        outcome: "Done",
+      },
+      Result: {
+        ref: "Result-View",
+        state_type: "VIEW",
+        transitions: {
+          "*": "END_Done",
+        },
+      },
+    },
+  });
+
+  controller.start();
+  expect(controller.current?.id).toBe("Flow-1");
+  controller.transition("Next");
+  expect(controller.current?.id).toBe("Flow-2");
+  controller.transition("Back");
+
+  // Wait for all pending promises (in this case, the sub-flow promise) to complete.
+  await vitest.waitFor(() => expect(controller.current?.id).toBe("Flow-1"));
+
+  controller.transition("Next");
+  expect(controller.current?.id).toBe("Flow-2");
+  expect(controller.current?.currentState?.name).toBe("Result");
+});
+
+it("fails if BEGIN doesnt point to a flow", async () => {
+  const controller = new FlowController({
+    BEGIN: "foo",
+  } as any);
+
+  await expect(controller.start()).rejects.toThrowError(
+    "No flow defined for: foo",
+  );
+});
+
+it("fails if state isnt an object", async () => {
+  const controller = new FlowController({
+    BEGIN: "foo",
+    foo: "bar",
+  } as any);
+  await expect(controller.start()).rejects.toThrowError(
+    "Flow: foo needs to be an object",
+  );
+});
+
+it("fails if no BEGIN state", async () => {
+  const controller = new FlowController({} as any);
+  await expect(controller.start()).rejects.toThrowError(
+    "Must supply a BEGIN state",
+  );
+});
+
+it("fails if flow not started", async () => {
+  const controller = new FlowController({} as any);
+  expect(controller.transition).toThrowError(
+    "Not currently in a flow. Cannot transition.",
+  );
+});
+
+it("does not set current to undefined after run resolves with the last flow", async () => {
+  const controller = new FlowController({
+    BEGIN: "FLOW_1",
+    FLOW_1: {
+      startState: "VIEW_1",
+      VIEW_1: {
+        ref: "view-1",
+        state_type: "VIEW",
+        transitions: {
+          "*": "End",
+        },
+      },
+      End: {
+        state_type: "END",
+        outcome: "done",
+      },
+    },
+  } as any);
+  const p = controller.start();
+  controller.transition("Next");
+
+  await p;
+
+  expect(controller.current).toBeDefined();
+  expect(controller.current?.currentState?.value.outcome).toBe("done");
+});

package/src/controllers/flow/__tests__/flow.test.ts

@@ -0,0 +1,381 @@
+import { describe, it, test, expect, vitest } from "vitest";
+import { FlowInstance } from "..";
+
+test("starts the right state", () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View1",
+    View1: {
+      state_type: "VIEW",
+      ref: "foo",
+      transitions: {
+        Next: "View2",
+      },
+    },
+  } as const);
+
+  flow.start();
+  expect(flow.currentState!.name).toBe("View1");
+});
+
+test("works with just END state", async () => {
+  const flow = new FlowInstance("flow", {
+    startState: "END_done",
+    END_before_topic: { state_type: "END", outcome: "BACK" },
+    END_done: { state_type: "END", outcome: "doneWithTopic" },
+  } as const);
+
+  expect(await flow.start()).toStrictEqual({
+    state_type: "END",
+    outcome: "doneWithTopic",
+  });
+});
+
+test("simple transitions between states", () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View1",
+    View1: {
+      state_type: "VIEW",
+      ref: "foo",
+
+      transitions: {
+        Next: "View2",
+      },
+    },
+    View2: {
+      state_type: "VIEW",
+      ref: "foo",
+      transitions: {
+        Prev: "View1",
+      },
+    },
+  } as const);
+
+  flow.start();
+  expect(flow.currentState!.name).toBe("View1");
+  flow.transition("Next");
+  expect(flow.currentState!.name).toBe("View2");
+  flow.transition("Prev");
+  expect(flow.currentState!.name).toBe("View1");
+});
+
+test("transition from end state returns", () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View1",
+    View1: {
+      state_type: "VIEW",
+      ref: "foo",
+      transitions: {
+        Next: "Done1",
+      },
+    },
+    Done1: {
+      state_type: "END",
+      outcome: "foo-bar",
+    },
+  });
+
+  flow.start();
+  flow.transition("Next");
+  expect(() => flow.transition("Prev")).not.toThrowError();
+});
+
+test("fails when theres no startState", async () => {
+  const flow = new FlowInstance("flow", {
+    View1: {
+      state_type: "Foo",
+      transitions: {},
+    },
+  } as any);
+
+  await expect(flow.start()).rejects.toThrowError(
+    "No 'startState' defined for flow",
+  );
+});
+
+test("uses * as fallback transition", () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View1",
+    View1: {
+      state_type: "VIEW",
+      ref: "foo",
+      transitions: {
+        "*": "SpecialView",
+      },
+    },
+    SpecialView: {
+      ref: "foo",
+      state_type: "VIEW",
+      transitions: {},
+    },
+  });
+
+  flow.start();
+  expect(flow.currentState!.name).toBe("View1");
+  flow.transition("Prev");
+  expect(flow.currentState!.name).toBe("SpecialView");
+});
+
+test("Do not throw exception when no transitions", () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View1",
+    View1: {
+      state_type: "VIEW",
+      ref: "foo",
+      transitions: {
+        Next: "View2",
+      },
+    },
+  });
+
+  flow.start();
+  expect(flow.currentState!.name).toBe("View1");
+  expect(() => flow.transition("Prev")).not.toThrowError();
+});
+
+test("Fails to transition when not started", () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View1",
+    View1: {
+      state_type: "VIEW",
+      ref: "foo",
+      transitions: {
+        Next: "View2",
+      },
+    },
+  });
+
+  expect(() => flow.transition("foo")).toThrowError();
+});
+
+test("Fails to transition during another transition", async () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View1",
+    View1: {
+      state_type: "VIEW",
+      onStart: "foo bar",
+      ref: "foo",
+      transitions: {
+        Next: "View2",
+      },
+    },
+    View2: {
+      state_type: "VIEW",
+      ref: "bar",
+      transitions: {
+        Next: "View3",
+      },
+    },
+  });
+
+  let deferredVar: string;
+
+  const transition = () => {
+    try {
+      flow.transition("Next");
+      return "foo";
+    } catch (error: unknown) {
+      return "bar";
+    }
+  };
+
+  flow.hooks.resolveTransitionNode.intercept({
+    call: (nextState) => {
+      if (nextState?.onStart) {
+        deferredVar = transition();
+      }
+    },
+  });
+
+  flow.start();
+
+  await vitest.waitFor(() => {
+    expect(deferredVar).toBeDefined();
+  });
+
+  expect(deferredVar!).toBe("bar");
+});
+
+describe("promise api", () => {
+  it("resolves when were done", async () => {
+    const flow = new FlowInstance("flow", {
+      startState: "View1",
+      View1: {
+        state_type: "VIEW",
+        ref: "foo",
+        transitions: {
+          Next: "Done1",
+        },
+      },
+      Done1: {
+        state_type: "END",
+        outcome: "foo-bar",
+      },
+    });
+
+    const flowProm = flow.start();
+    flow.transition("Next");
+    const result = await flowProm;
+    expect(result.state_type).toBe("END");
+    expect(result.outcome).toBe("foo-bar");
+  });
+});
+
+test("reuses the same promise if started again", async () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View1",
+    View1: {
+      state_type: "VIEW",
+      ref: "foo",
+      transitions: { "*": "End1" },
+    },
+    End1: {
+      state_type: "END",
+      outcome: "bar",
+    },
+  });
+
+  flow.start();
+  flow.transition("foo");
+  const result = await flow.start();
+  expect(result.outcome).toBe("bar");
+});
+
+test("calls onStart hook", async () => {
+  const flow = new FlowInstance("flow", {
+    onStart: "foo bar",
+  } as any);
+  const hook = vitest.fn();
+  flow.hooks.onStart.tap("test", hook);
+  const result = flow.start();
+  expect(hook).toBeCalledWith("foo bar");
+
+  await expect(result).rejects.toThrowError("No 'startState' defined for flow");
+});
+
+test("calls the onEnd hook", async () => {
+  const flow = new FlowInstance("flow", {
+    onEnd: "foo bar",
+    startState: "FOO",
+    FOO: {
+      state_type: "END",
+      outcome: "done",
+    },
+  });
+  const hook = vitest.fn();
+
+  flow.hooks.onEnd.tap("test", hook);
+  const result = flow.start();
+  expect(hook).toBeCalledWith("foo bar");
+  expect(await result).toStrictEqual({
+    state_type: "END",
+    outcome: "done",
+  });
+});
+
+test("keeps current state if skipped", () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View1",
+    View1: {
+      state_type: "VIEW",
+      ref: "foo",
+      transitions: {
+        Next: "View2",
+      },
+    },
+    View2: {
+      state_type: "VIEW",
+      ref: "bar",
+      transitions: {},
+    },
+  });
+
+  flow.hooks.skipTransition.tap("test", (curr) => curr !== undefined);
+  flow.start();
+  expect(flow.currentState!.name).toBe("View1");
+  flow.transition("Next");
+  expect(flow.currentState!.name).toBe("View1");
+});
+
+test("fails to transition if not started", () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View1",
+  });
+
+  expect(() => flow.transition("foo")).toThrowError();
+});
+
+test("fails if no transition", () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View1",
+    View1: {
+      state_type: "VIEW",
+      ref: "foo",
+    },
+  } as any);
+  flow.start();
+  expect(() => flow.transition("foo")).toThrowError();
+});
+
+test("fails if no startState points to unknown state", async () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View2",
+  } as any);
+
+  await expect(flow.start()).rejects.toThrowError(
+    "No flow definition for: View2 was found.",
+  );
+});
+
+test("force transition", () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View1",
+    View1: {
+      state_type: "VIEW",
+      ref: "foo",
+      transitions: {
+        Next: "Done1",
+      },
+    },
+    Done1: {
+      state_type: "END",
+      outcome: "foo-bar",
+    },
+  });
+
+  flow.start();
+  flow.hooks.skipTransition.tap("tst", () => true);
+  expect(flow.currentState?.name).toBe("View1");
+
+  // Transition without the force flag
+  flow.transition("Next");
+
+  // Should stay on the same page
+  expect(flow.currentState?.name).toBe("View1");
+
+  flow.transition("Next", { force: true });
+
+  // Forced transition ignore the skip hook
+  expect(flow.currentState?.name).toBe("Done1");
+});
+
+test("fails if transitioning to unknown state", () => {
+  const flow = new FlowInstance("flow", {
+    startState: "View1",
+    View1: {
+      state_type: "VIEW",
+      ref: "foo",
+      transitions: {
+        Next: "Done1",
+      },
+    },
+    Done1: {
+      outcome: "foo-bar",
+    },
+  } as any);
+
+  flow.start();
+
+  expect(flow.currentState?.name).toBe("View1");
+  flow.transition("Next");
+  expect(flow.currentState?.name).toBe("View1");
+});

package/src/controllers/flow/controller.ts

@@ -1,8 +1,8 @@
-import { SyncHook } from 'tapable-ts';
-import type { Navigation, NavigationFlowEndState } from '@player-ui/types';
-import type { Logger } from '../../logger';
-import type { NamedState, TransitionOptions } from './flow';
-import { FlowInstance } from './flow';
+import { SyncHook } from "tapable-ts";
+import type { Navigation, NavigationFlowEndState } from "@player-ui/types";
+import type { Logger } from "../../logger";
+import type { TransitionOptions } from "./flow";
+import { FlowInstance } from "./flow";
 
 /** A manager for the navigation section of a Content blob */
 export class FlowController {
@@ -20,7 +20,7 @@ export class FlowController {
     options?: {
       /** A logger instance to use */
       logger?: Logger;
-    }
+    },
   ) {
     this.navigation = navigation;
     this.navStack = [];
@@ -35,7 +35,7 @@ export class FlowController {
   /** Navigate to another state in the state-machine */
   public transition(stateTransition: string, options?: TransitionOptions) {
     if (this.current === undefined) {
-      throw new Error('Not currently in a flow. Cannot transition.');
+      throw new Error("Not currently in a flow. Cannot transition.");
     }
 
     this.current.transition(stateTransition, options);
@@ -54,9 +54,9 @@ export class FlowController {
 
     const startFlow = this.navigation[startState];
 
-    if (startFlow === null || typeof startFlow !== 'object') {
+    if (startFlow === null || typeof startFlow !== "object") {
       return Promise.reject(
-        new Error(`Flow: ${startState} needs to be an object`)
+        new Error(`Flow: ${startState} needs to be an object`),
       );
     }
 
@@ -65,13 +65,13 @@ export class FlowController {
     const flow = new FlowInstance(startState, startFlow, { logger: this.log });
     this.addNewFlow(flow);
 
-    flow.hooks.afterTransition.tap('flow-controller', (flowInstance) => {
-      if (flowInstance.currentState?.value.state_type === 'FLOW') {
+    flow.hooks.afterTransition.tap("flow-controller", (flowInstance) => {
+      if (flowInstance.currentState?.value.state_type === "FLOW") {
         const subflowId = flowInstance.currentState?.value.ref;
         this.log?.debug(`Loading subflow ${subflowId}`);
         this.run(subflowId).then((subFlowEndState) => {
           this.log?.debug(
-            `Subflow ended. Using outcome: ${subFlowEndState.outcome}`
+            `Subflow ended. Using outcome: ${subFlowEndState.outcome}`,
           );
           flowInstance.transition(subFlowEndState?.outcome);
         });
@@ -91,7 +91,7 @@ export class FlowController {
 
   public async start(): Promise<NavigationFlowEndState> {
     if (!this.navigation.BEGIN) {
-      return Promise.reject(new Error('Must supply a BEGIN state'));
+      return Promise.reject(new Error("Must supply a BEGIN state"));
     }
 
     return this.run(this.navigation.BEGIN);