@player-ui/player 1.1.0-next.1 → 1.1.0-next.3

package/package.json

@@ -6,12 +6,12 @@
     "types"
   ],
   "name": "@player-ui/player",
-  "version": "1.1.0-next.1",
+  "version": "1.1.0-next.3",
   "main": "dist/cjs/index.cjs",
   "dependencies": {
-    "@player-ui/partial-match-registry": "1.1.0-next.1",
-    "@player-ui/make-flow": "1.1.0-next.1",
-    "@player-ui/types": "1.1.0-next.1",
+    "@player-ui/partial-match-registry": "1.1.0-next.3",
+    "@player-ui/make-flow": "1.1.0-next.3",
+    "@player-ui/types": "1.1.0-next.3",
     "@types/dlv": "^1.1.4",
     "dequal": "^2.0.2",
     "dlv": "^1.1.3",

package/src/__tests__/player.test.ts

@@ -8,6 +8,7 @@ import type { ViewController } from "..";
 import actionsFlow from "./helpers/actions.flow";
 import type { InProgressState } from "../types";
 import { ActionExpPlugin } from "./helpers/action-exp.plugin";
+import TrackBindingPlugin from "./helpers/binding.plugin";
 
 const minimal = {
   id: "minimal-player-content-response-format",
@@ -722,3 +723,175 @@ test("view trigger once when moving between views", async () => {
     expect(viewTap).toHaveBeenCalledOnce();
   });
 });
+
+test("prevents invalid data from being committed during action-driven backward navigation", async () => {
+  const player = new Player({
+    plugins: [new TrackBindingPlugin()],
+  });
+
+  player.hooks.validationController.tap("test", (validationProvider) => {
+    validationProvider.hooks.createValidatorRegistry.tap("test", (registry) => {
+      registry.register("minValue", (_context, value) => {
+        if (typeof value === "number" && value < 0) {
+          return {
+            message: "Amount must be non-negative",
+            severity: "error",
+          };
+        }
+      });
+    });
+  });
+
+  const flow = {
+    id: "schema-invalid-force-navigation",
+    schema: {
+      ROOT: {
+        someValue: {
+          type: "SomeType",
+          validation: [
+            {
+              type: "minValue",
+              severity: "error",
+              trigger: "change",
+            },
+          ],
+        },
+      },
+    },
+    views: [
+      {
+        id: "input-view",
+        type: "info",
+        fields: {
+          asset: {
+            id: "input-fields",
+            type: "collection",
+            values: [
+              {
+                asset: {
+                  id: "some-input",
+                  type: "input",
+                  binding: "someValue",
+                },
+              },
+            ],
+          },
+        },
+        actions: [
+          {
+            asset: {
+              id: "back-action",
+              type: "action",
+              value: "previous",
+              label: {
+                asset: {
+                  id: "back-label",
+                  type: "text",
+                  value: "Back",
+                },
+              },
+            },
+          },
+        ],
+      },
+      {
+        id: "result-view",
+        type: "info",
+        title: {
+          asset: {
+            id: "result-title",
+            type: "text",
+            value: "Result",
+          },
+        },
+        primaryInfo: {
+          asset: {
+            id: "result-text",
+            type: "text",
+            value: "Leaked value: {{someValue}}",
+          },
+        },
+      },
+    ],
+    navigation: {
+      BEGIN: "FLOW_1",
+      FLOW_1: {
+        startState: "VIEW_INPUT",
+        VIEW_INPUT: {
+          state_type: "VIEW",
+          ref: "input-view",
+          transitions: {
+            previous: "ACTION_BACK",
+          },
+        },
+        ACTION_BACK: {
+          state_type: "ACTION",
+          exp: "{{unrelated}} = 'touched'",
+          transitions: {
+            "*": "VIEW_RESULT",
+          },
+        },
+        VIEW_RESULT: {
+          state_type: "VIEW",
+          ref: "result-view",
+          transitions: {
+            "*": "END_done",
+          },
+        },
+        END_done: {
+          state_type: "END",
+          outcome: "done",
+        },
+      },
+    },
+  };
+
+  player.start(flow as any);
+
+  await vitest.waitFor(() => {
+    const state = player.getState() as InProgressState;
+    return (
+      state?.controllers?.flow?.current?.currentState?.name === "VIEW_INPUT"
+    );
+  });
+
+  let state = player.getState() as InProgressState;
+  expect(state.controllers.flow.current?.currentState?.name).toBe("VIEW_INPUT");
+
+  // Simulate entering invalid data
+  state.controllers.data.set([["someValue", -1]]);
+
+  // The invalid data should be rejected and only available in the shadow model
+  expect(state.controllers.data.get("someValue")).toBeUndefined();
+  expect(
+    state.controllers.data.get("someValue", { includeInvalid: true }),
+  ).toBe(-1);
+
+  // Ensure normal navigation is blocked
+  state.controllers.flow.current?.transition("previous");
+
+  let currentState = player.getState() as InProgressState;
+  expect(currentState?.controllers?.flow?.current?.currentState?.name).toBe(
+    "VIEW_INPUT",
+  );
+
+  // Simulate forcing back navigation (bypassing validation)
+  state.controllers.flow.current?.transition("previous", { force: true });
+
+  currentState = player.getState() as InProgressState;
+  expect(currentState?.controllers?.flow?.current?.currentState?.name).toBe(
+    "VIEW_RESULT",
+  );
+
+  state = player.getState() as InProgressState;
+
+  // The invalid data should NOT be committed to the main model because of the transition
+  const finalValue = state.controllers.data.get("someValue");
+  expect(finalValue).toBeUndefined();
+  // The transition should have dropped the invalid data entirely, not just
+  // hidden it from the main model
+  const shadowValue = state.controllers.data.get("someValue", {
+    includeInvalid: true,
+  });
+  expect(shadowValue).toBeUndefined();
+});

package/src/__tests__/transform-content.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, test, vitest } from "vitest";
+import { Player } from "..";
+import type { Flow, PlayerPlugin, InProgressState } from "..";
+
+/** Minimal Flow used to short-circuit setupFlow. */
+const flowFor = (id: string): Flow => ({
+  id,
+  views: [{ id: "v1", type: "text", value: "hi" }],
+  data: {},
+  navigation: {
+    BEGIN: "F",
+    F: {
+      startState: "VIEW_1",
+      VIEW_1: {
+        state_type: "VIEW",
+        ref: "v1",
+        transitions: { "*": "END" },
+      },
+      END: { state_type: "END", outcome: "done" },
+    },
+  },
+});
+
+describe("transformContent hook", () => {
+  test("default format 'player' passes the payload through unchanged", async () => {
+    const player = new Player();
+    const flow = flowFor("plain");
+    player.start(flow);
+    const state = player.getState() as InProgressState;
+    expect(state.flow).toBe(flow);
+  });
+
+  test("a plugin tapping for a custom format transforms the payload", async () => {
+    const greetPlugin: PlayerPlugin = {
+      name: "greet",
+      apply(p) {
+        p.hooks.transformContent.tap("greet", (content, meta) => {
+          if (meta.format !== "greet") return undefined;
+          const { message } = content as { message: string };
+          return { ...flowFor("greet"), data: { message } };
+        });
+      },
+    };
+
+    const player = new Player({ plugins: [greetPlugin] });
+    player.start({ message: "Hello world" }, { format: "greet" });
+
+    const state = player.getState() as InProgressState;
+    await vitest.waitFor(() =>
+      expect(state.controllers.view.currentView?.lastUpdate).toBeDefined(),
+    );
+    expect(state.controllers.data.get("message")).toBe("Hello world");
+  });
+
+  test("fires before resolveFlowContent", async () => {
+    const order: string[] = [];
+
+    const orderPlugin: PlayerPlugin = {
+      name: "order",
+      apply(p) {
+        p.hooks.transformContent.tap("order", () => {
+          order.push("transformContent");
+          // Return undefined so Player's default "player" handler claims it.
+          return undefined;
+        });
+        p.hooks.resolveFlowContent.tap("order", (c) => {
+          order.push("resolveFlowContent");
+          return c;
+        });
+      },
+    };
+
+    const player = new Player({ plugins: [orderPlugin] });
+    player.start(flowFor("order"));
+
+    expect(order).toEqual(["transformContent", "resolveFlowContent"]);
+  });
+
+  test("multiple format plugins coexist — only matching one transforms", async () => {
+    const aPlugin: PlayerPlugin = {
+      name: "a",
+      apply(p) {
+        p.hooks.transformContent.tap("a", (c, meta) =>
+          meta.format === "a" ? flowFor("from-a") : undefined,
+        );
+      },
+    };
+    const bPlugin: PlayerPlugin = {
+      name: "b",
+      apply(p) {
+        p.hooks.transformContent.tap("b", (c, meta) =>
+          meta.format === "b" ? flowFor("from-b") : undefined,
+        );
+      },
+    };
+
+    const player = new Player({ plugins: [aPlugin, bPlugin] });
+    player.start({ raw: true }, { format: "b" });
+
+    const state = player.getState() as InProgressState;
+    expect(state.flow.id).toBe("from-b");
+  });
+
+  test("version is plumbed from StartOptions to the hook's meta arg", () => {
+    const versions: Array<string | undefined> = [];
+    const probe: PlayerPlugin = {
+      name: "probe",
+      apply(p) {
+        p.hooks.transformContent.tap("probe", (c, meta) => {
+          versions.push(meta.version);
+          // For format !== "demo", return undefined so the default path runs.
+          if (meta.format !== "demo") return undefined;
+          return flowFor("demo");
+        });
+      },
+    };
+
+    const player = new Player({ plugins: [probe] });
+    player.start({ x: 1 }, { format: "demo", version: "2" });
+    player.start({ x: 1 }, { format: "demo", version: "1" });
+    player.start(flowFor("noversion"));
+
+    expect(versions).toEqual(["2", "1", undefined]);
+  });
+
+  test("errors when no tap transforms an unknown format into a Flow", async () => {
+    const player = new Player();
+    const result = player.start({ some: "content" }, { format: "unknown" });
+    await expect(result).rejects.toThrow(/format "unknown"/);
+  });
+});

package/src/controllers/data/utils.ts

@@ -12,7 +12,7 @@ export class ReadOnlyDataController
     this.controller = controller;
   }
 
-  get(binding: BindingLike, options?: DataModelOptions | undefined) {
+  get(binding: BindingLike, options?: DataModelOptions | undefined): any {
     return this.controller.get(binding, options);
   }
 }

package/src/controllers/validation/controller.ts

@@ -420,6 +420,7 @@ export class ValidationController implements BindingTracker {
   private viewValidationProvider?: ValidationProvider;
   private options?: SimpleValidatorContext;
   private weakBindingTracker = new Set<BindingInstance>();
+  private validationMiddleware?: ValidationMiddleware;
 
   constructor(schema: SchemaController, options?: SimpleValidatorContext) {
     this.schema = schema;
@@ -433,6 +434,55 @@ export class ValidationController implements BindingTracker {
 
   /** Return the middleware for the data-model to stop propagation of invalid data */
   public getDataMiddleware(): Array<DataModelMiddleware> {
+    const validationMiddleware = new ValidationMiddleware(
+      (binding) => {
+        if (!this.options) {
+          return;
+        }
+
+        this.updateValidationsForBinding(binding, "change", this.options);
+        const strongValidation = this.getValidationForBinding(binding);
+
+        // return validation issues directly on bindings first
+        if (strongValidation?.get()?.severity === "error") {
+          return strongValidation.get();
+        }
+
+        // if none, check to see any validations this binding may be a weak ref of and return
+        const newInvalidBindings: Set<StrongOrWeakBinding> = new Set();
+        this.validations.forEach((weakValidation, strongBinding) => {
+          if (
+            caresAboutDataChanges(
+              new Set([binding]),
+              weakValidation.weakBindings,
+            ) &&
+            weakValidation?.get()?.severity === "error"
+          ) {
+            weakValidation?.weakBindings.forEach((weakBinding) => {
+              if (weakBinding === strongBinding) {
+                newInvalidBindings.add({
+                  binding: weakBinding,
+                  isStrong: true,
+                });
+              } else {
+                newInvalidBindings.add({
+                  binding: weakBinding,
+                  isStrong: false,
+                });
+              }
+            });
+          }
+        });
+
+        if (newInvalidBindings.size > 0) {
+          return newInvalidBindings;
+        }
+      },
+      { logger: new ProxyLogger(() => this.options?.logger) },
+    );
+
+    this.validationMiddleware = validationMiddleware;
+
     return [
       {
         set: (transaction, options, next) => {
@@ -450,52 +500,7 @@ export class ValidationController implements BindingTracker {
           return next?.delete(binding, options);
         },
       },
-      new ValidationMiddleware(
-        (binding) => {
-          if (!this.options) {
-            return;
-          }
-
-          this.updateValidationsForBinding(binding, "change", this.options);
-          const strongValidation = this.getValidationForBinding(binding);
-
-          // return validation issues directly on bindings first
-          if (strongValidation?.get()?.severity === "error") {
-            return strongValidation.get();
-          }
-
-          // if none, check to see any validations this binding may be a weak ref of and return
-          const newInvalidBindings: Set<StrongOrWeakBinding> = new Set();
-          this.validations.forEach((weakValidation, strongBinding) => {
-            if (
-              caresAboutDataChanges(
-                new Set([binding]),
-                weakValidation.weakBindings,
-              ) &&
-              weakValidation?.get()?.severity === "error"
-            ) {
-              weakValidation?.weakBindings.forEach((weakBinding) => {
-                if (weakBinding === strongBinding) {
-                  newInvalidBindings.add({
-                    binding: weakBinding,
-                    isStrong: true,
-                  });
-                } else {
-                  newInvalidBindings.add({
-                    binding: weakBinding,
-                    isStrong: false,
-                  });
-                }
-              });
-            }
-          });
-
-          if (newInvalidBindings.size > 0) {
-            return newInvalidBindings;
-          }
-        },
-        { logger: new ProxyLogger(() => this.options?.logger) },
-      ),
+      validationMiddleware,
     ];
   }
 
@@ -533,10 +538,11 @@ export class ValidationController implements BindingTracker {
   public reset() {
     this.validations.clear();
     this.tracker = undefined;
+    this.validationMiddleware?.reset();
   }
 
   public onView(view: ViewInstance): void {
-    this.validations.clear();
+    this.reset();
     if (!this.options) {
       return;
     }

package/src/player.ts

@@ -3,7 +3,7 @@ import deferred from "p-defer";
 import type { Flow, FlowResult } from "@player-ui/types";
 import queueMicrotask from "queue-microtask";
 
-import { SyncHook, SyncWaterfallHook } from "tapable-ts";
+import { SyncBailHook, SyncHook, SyncWaterfallHook } from "tapable-ts";
 import type { Logger } from "./logger";
 import { TapableLogger } from "./logger";
 import type { ExpressionType } from "./expressions";
@@ -29,6 +29,8 @@ import type {
   CompletedState,
   ErrorState,
   PlayerHooks,
+  ContentMeta,
+  StartOptions,
 } from "./types";
 import { NOT_STARTED_STATE } from "./types";
 
@@ -125,6 +127,7 @@ export class Player {
     onStart: new SyncHook<[Flow]>(),
     onEnd: new SyncHook<[]>(),
     resolveFlowContent: new SyncWaterfallHook<[Flow]>(),
+    transformContent: new SyncBailHook<[unknown, ContentMeta], Flow>(),
   };
 
   constructor(config?: PlayerConfigOptions) {
@@ -141,6 +144,13 @@ export class Player {
     this.config.plugins?.forEach((plugin) => {
       plugin.apply(this);
     });
+
+    // Default content handler: a `"player"`-format payload is already a `Flow`.
+    // Registered after plugins so a format plugin gets first claim on the bail
+    // hook; this is the fallback that lets `start()` require a `Flow` out.
+    this.hooks.transformContent.tap("player", (payload, meta) =>
+      meta.format === "player" ? (payload as Flow) : undefined,
+    );
   }
 
   /**  Returns currently registered plugins */
@@ -513,8 +523,21 @@ export class Player {
     };
   }
 
-  public async start(payload: Flow): Promise<CompletedState> {
-    const ref = Symbol(payload?.id ?? "payload");
+  public async start(
+    payload: unknown,
+    options?: StartOptions,
+  ): Promise<CompletedState> {
+    const meta: ContentMeta = {
+      format: options?.format ?? "player",
+      version: options?.version,
+    };
+    const flow = this.hooks.transformContent.call(payload, meta);
+    if (!flow) {
+      throw new Error(
+        `Player.start received content with format "${meta.format}" that no plugin transformed into a Flow.`,
+      );
+    }
+    const ref = Symbol(flow.id ?? "payload");
 
     /** A check to avoid updating the state for a flow that's not the current one */
     const maybeUpdateState = <T extends PlayerFlowState>(newState: T) => {
@@ -537,7 +560,7 @@ export class Player {
     });
 
     try {
-      const { state, start } = this.setupFlow(payload);
+      const { state, start } = this.setupFlow(flow);
       this.setState({
         ref,
         ...state,
@@ -564,7 +587,7 @@ export class Player {
       const errorState: ErrorState = {
         status: "error",
         ref,
-        flow: payload,
+        flow,
         error,
       };
 

package/src/types.ts

@@ -11,9 +11,39 @@ import type {
   ErrorController,
 } from "./controllers";
 import type { ReadOnlyDataController } from "./controllers/data/utils";
-import { SyncHook, SyncWaterfallHook } from "tapable-ts";
+import { SyncBailHook, SyncHook, SyncWaterfallHook } from "tapable-ts";
 import { ViewInstance } from "./view";
 
+/**
+ * Metadata describing the incoming content to `Player.start()`. Passed
+ * alongside the raw payload through the `transformContent` hook so plugins
+ * can decide whether to claim/convert it.
+ */
+export interface ContentMeta {
+  /**
+   * Content format identifier. `"player"` (default) means the input is
+   * already a `Flow` and needs no conversion. Anything else is a free-form
+   * string a plugin can recognize.
+   */
+  format: string;
+  /**
+   * Optional format version (e.g., `"0.9"`). Free-form — plugins decide the
+   * convention. Lets a single format plugin dispatch across major/minor
+   * versions without the caller picking a different `format` string.
+   */
+  version?: string;
+}
+
+/**
+ * Options passed to `Player.start()` alongside the payload.
+ */
+export interface StartOptions {
+  /** Identifier of the input content's format. Default: `"player"`. */
+  format?: string;
+  /** Optional content-format version. See `ContentMeta.version`. */
+  version?: string;
+}
+
 /**
  * Public Player Hooks
  */
@@ -47,6 +77,16 @@ export interface PlayerHooks {
     [Flow<Asset<string>>],
     Record<string, any>
   >;
+  /**
+   * Transform raw input content into a Player `Flow` before any state is set
+   * up. Fires at the top of `Player.start()` — after plugins are applied,
+   * before `resolveFlowContent`. Being a bail hook, taps inspect `meta.format`
+   * (and optionally `meta.version`) and return a `Flow` to claim the content;
+   * returning `undefined` passes to the next tap. Player registers a default
+   * tap for the `"player"` format that returns the payload as-is, so the hook
+   * is guaranteed to yield a `Flow` and `start()` needs no type-casting.
+   */
+  transformContent: SyncBailHook<[unknown, ContentMeta], Flow<Asset<string>>>;
 }
 
 /** The status for a flow's execution state */

package/src/validator/validation-middleware.ts

@@ -163,4 +163,9 @@ export class ValidationMiddleware implements DataModelMiddleware {
 
     return next?.delete(binding, options);
   }
+
+  /** Clears any invalid values staged in the shadow model */
+  public reset(): void {
+    this.shadowModelPaths.clear();
+  }
 }

package/types/controllers/validation/controller.d.ts

@@ -120,6 +120,7 @@ export declare class ValidationController implements BindingTracker {
     private viewValidationProvider?;
     private options?;
     private weakBindingTracker;
+    private validationMiddleware?;
     constructor(schema: SchemaController, options?: SimpleValidatorContext);
     setOptions(options: SimpleValidatorContext): void;
     /** Return the middleware for the data-model to stop propagation of invalid data */

package/types/player.d.ts

@@ -1,8 +1,7 @@
-import type { Flow } from "@player-ui/types";
 import type { Logger } from "./logger";
 import { TapableLogger } from "./logger";
 import { ConstantsController } from "./controllers";
-import type { PlayerFlowState, CompletedState, PlayerHooks } from "./types";
+import type { PlayerFlowState, CompletedState, PlayerHooks, StartOptions } from "./types";
 /**
 Variables injected at build time
 */
@@ -75,7 +74,7 @@ export declare class Player {
     private setState;
     /** Start Player with the given flow */
     private setupFlow;
-    start(payload: Flow): Promise<CompletedState>;
+    start(payload: unknown, options?: StartOptions): Promise<CompletedState>;
 }
 export {};
 //# sourceMappingURL=player.d.ts.map