@player-ui/context-plugin 0.16.0--canary.891.38194

package/src/__tests__/state-plugin.test.ts

@@ -0,0 +1,346 @@
+import { test, expect, vitest } from "vitest";
+import { Player } from "@player-ui/player";
+import type { DataController } from "@player-ui/player";
+import { CommonTypesPlugin } from "@player-ui/common-types-plugin";
+import { ReferenceAssetsPlugin } from "@player-ui/reference-assets-plugin";
+import { ContextPlugin } from "../plugin";
+import { ContextPluginSymbol } from "../symbols";
+import {
+  StateContextPlugin,
+  dataContextKey,
+  flowIdContextKey,
+  flowStateContextKey,
+  playerStateContextKey,
+  playerStatusContextKey,
+  setDataActionKey,
+  transitionActionKey,
+  validationContextKey,
+  viewContextKey,
+  viewIdContextKey,
+} from "../state-plugin";
+
+/**
+ * A flow with a required `data.name` binding rendered by an input asset.
+ * Bindings are tracked by the reference-assets renderer and the `required`
+ * validator comes from the common-types plugin, so validation activates on a
+ * `change` trigger when the value is cleared.
+ */
+const validationFlow = {
+  id: "flow-validation",
+  views: [
+    {
+      id: "view-1",
+      type: "input",
+      binding: "data.name",
+      label: { asset: { id: "label", type: "text", value: "Name" } },
+    },
+  ],
+  data: { name: "Ada" },
+  schema: {
+    ROOT: { data: { type: "DataType" } },
+    DataType: {
+      name: {
+        type: "StringType",
+        validation: [{ type: "required", trigger: "change" }],
+      },
+    },
+  },
+  navigation: {
+    BEGIN: "FLOW_1",
+    FLOW_1: {
+      startState: "VIEW_1",
+      VIEW_1: {
+        ref: "view-1",
+        state_type: "VIEW",
+        transitions: { "*": "END_Done" },
+      },
+      END_Done: { state_type: "END", outcome: "done" },
+    },
+  },
+};
+
+const minimalFlow = {
+  id: "flow-state-test",
+  views: [{ id: "view-1", type: "info" }],
+  data: { name: "Ada" },
+  navigation: {
+    BEGIN: "FLOW_1",
+    FLOW_1: {
+      startState: "VIEW_1",
+      VIEW_1: {
+        ref: "view-1",
+        state_type: "VIEW",
+        transitions: { "*": "END_Done" },
+      },
+      END_Done: { state_type: "END", outcome: "done" },
+    },
+  },
+};
+
+const multiViewFlow = {
+  id: "flow-multi",
+  views: [
+    { id: "view-1", type: "info" },
+    { id: "view-2", type: "info" },
+  ],
+  navigation: {
+    BEGIN: "FLOW_1",
+    FLOW_1: {
+      startState: "VIEW_1",
+      VIEW_1: {
+        ref: "view-1",
+        state_type: "VIEW",
+        transitions: { Next: "VIEW_2", "*": "END_Done" },
+      },
+      VIEW_2: {
+        ref: "view-2",
+        state_type: "VIEW",
+        transitions: { "*": "END_Done" },
+      },
+      END_Done: { state_type: "END", outcome: "done" },
+    },
+  },
+};
+
+test("StateContextPlugin auto-registers a ContextPlugin if absent", () => {
+  const state = new StateContextPlugin();
+  const player = new Player({ plugins: [state] });
+  const ctx = player.findPlugin<ContextPlugin>(ContextPluginSymbol);
+  expect(ctx).toBeInstanceOf(ContextPlugin);
+});
+
+test("StateContextPlugin reuses an existing ContextPlugin", () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  const player = new Player({ plugins: [ctx, state] });
+  expect(player.findPlugin<ContextPlugin>(ContextPluginSymbol)).toBe(ctx);
+});
+
+test("publishes flow id, view id, view, data, status on flow start", () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  const player = new Player({ plugins: [ctx, state] });
+
+  player.start(minimalFlow as any);
+
+  expect(ctx.get(flowIdContextKey)).toBe("flow-state-test");
+  expect(ctx.get(playerStatusContextKey)).toBe("in-progress");
+  expect(ctx.get(flowStateContextKey)).toBe("VIEW_1");
+  expect(ctx.get(viewIdContextKey)).toBe("view-1");
+  expect(ctx.get(viewContextKey)).toMatchObject({
+    id: "view-1",
+    type: "info",
+  });
+  expect(ctx.get(dataContextKey)).toEqual({ name: "Ada" });
+});
+
+test("data context entry updates when the data controller updates", () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  const player = new Player({ plugins: [ctx, state] });
+
+  let dataController: DataController | undefined;
+  player.hooks.dataController.tap("test", (dc) => {
+    dataController = dc;
+  });
+
+  player.start(minimalFlow as any);
+  dataController!.set([["name", "Grace"]]);
+
+  expect(ctx.get(dataContextKey)).toEqual({ name: "Grace" });
+});
+
+test("list() reports all six state-context descriptors after StateContextPlugin applies", () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  new Player({ plugins: [ctx, state] });
+
+  const descriptions = ctx.list().map((d) => d.description);
+  expect(descriptions).toEqual(
+    expect.arrayContaining([
+      flowIdContextKey.description,
+      flowStateContextKey.description,
+      viewIdContextKey.description,
+      viewContextKey.description,
+      dataContextKey.description,
+      playerStatusContextKey.description,
+    ]),
+  );
+});
+
+test("aggregate playerStateContextKey composes every published source", () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  const player = new Player({ plugins: [ctx, state] });
+
+  player.start(minimalFlow as any);
+
+  const snapshot = ctx.get(playerStateContextKey);
+  expect(snapshot).toMatchObject({
+    status: "in-progress",
+    flow: { id: "flow-state-test", state: "VIEW_1" },
+    view: {
+      id: "view-1",
+      resolved: expect.objectContaining({ id: "view-1", type: "info" }),
+    },
+    data: { model: { name: "Ada" } },
+  });
+  // Actions are scoped to the construct they operate on.
+  expect(typeof snapshot!.flow.transition).toBe("function");
+  expect(typeof snapshot!.data.set).toBe("function");
+});
+
+test("aggregate player.state exposes invokable actions scoped to their constructs", () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  const player = new Player({ plugins: [ctx, state] });
+
+  player.start(multiViewFlow as any);
+  const before = ctx.get(playerStateContextKey)!;
+  expect(before.flow.state).toBe("VIEW_1");
+
+  // The scoped flow.transition action advances the running flow.
+  before.flow.transition!("Next");
+  expect(ctx.get(flowStateContextKey)).toBe("VIEW_2");
+
+  // The scoped data.set action drives the data model; reading the aggregate
+  // back reflects the write through data.model.
+  ctx.get(playerStateContextKey)!.data.set!("name", "Grace");
+  expect(ctx.get(playerStateContextKey)!.data.model).toEqual({ name: "Grace" });
+
+  // Transitioning again drives the flow to its terminal END state.
+  ctx.get(playerStateContextKey)!.flow.transition!("Next");
+  expect(ctx.get(flowStateContextKey)).toBe("END_Done");
+});
+
+test("aggregate subscribers fire when any source updates", () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  const player = new Player({ plugins: [ctx, state] });
+
+  let dataController: DataController | undefined;
+  player.hooks.dataController.tap("test", (dc) => {
+    dataController = dc;
+  });
+
+  const handler = vitest.fn();
+  ctx.subscribe(playerStateContextKey, handler);
+
+  player.start(minimalFlow as any);
+  handler.mockClear();
+  dataController!.set([["name", "Grace"]]);
+
+  expect(handler).toHaveBeenCalled();
+  const lastCall = handler.mock.calls[handler.mock.calls.length - 1];
+  expect(lastCall[0]).toMatchObject({ data: { model: { name: "Grace" } } });
+});
+
+test("setData action is a function-valued context entry that writes to the data model", () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  const player = new Player({ plugins: [ctx, state] });
+
+  player.start(minimalFlow as any);
+  const setData = ctx.get(setDataActionKey);
+  expect(typeof setData).toBe("function");
+  setData!("name", "Grace");
+
+  expect(ctx.get(dataContextKey)).toEqual({ name: "Grace" });
+});
+
+test("transition action is a function-valued context entry that advances the flow", () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  const player = new Player({ plugins: [ctx, state] });
+
+  player.start(multiViewFlow as any);
+  expect(ctx.get(flowStateContextKey)).toBe("VIEW_1");
+
+  ctx.get(transitionActionKey)!("Next");
+
+  expect(ctx.get(flowStateContextKey)).toBe("VIEW_2");
+});
+
+test("actions are absent until their controller instances exist", () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  new Player({ plugins: [ctx, state] });
+
+  // Before a flow starts there is no data/flow controller bound, so the
+  // action entries hold no callable.
+  expect(ctx.get(setDataActionKey)).toBeUndefined();
+  expect(ctx.get(transitionActionKey)).toBeUndefined();
+});
+
+test("action entries are re-bound to the live controllers when a flow starts", () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  const player = new Player({ plugins: [ctx, state] });
+
+  player.start(minimalFlow as any);
+  expect(typeof ctx.get(setDataActionKey)).toBe("function");
+  expect(typeof ctx.get(transitionActionKey)).toBe("function");
+});
+
+test("validation context is empty and transitionable with no failing validations", () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  const player = new Player({
+    plugins: [ctx, state, new CommonTypesPlugin(), new ReferenceAssetsPlugin()],
+  });
+
+  player.start(validationFlow as any);
+
+  expect(ctx.get(validationContextKey)).toEqual({
+    canTransition: true,
+    byBinding: {},
+  });
+});
+
+test("validation context reflects a failing binding and blocks transition", async () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  const player = new Player({
+    plugins: [ctx, state, new CommonTypesPlugin(), new ReferenceAssetsPlugin()],
+  });
+
+  player.start(validationFlow as any);
+  const dataController = (player.getState() as any).controllers.data;
+  dataController.set([["data.name", ""]]); // required → fails when empty
+
+  await vitest.waitFor(() => {
+    const validation = ctx.get(validationContextKey)!;
+    expect(validation.canTransition).toBe(false);
+    expect(validation.byBinding["data.name"]?.[0]).toMatchObject({
+      severity: "error",
+      message: expect.any(String),
+      blocking: true,
+    });
+  });
+
+  // The aggregate surfaces it too.
+  expect(ctx.get(playerStateContextKey)!.validation.canTransition).toBe(false);
+
+  // Fixing the value clears the validation and re-enables transition.
+  dataController.set([["data.name", "Ada"]]);
+  await vitest.waitFor(() => {
+    expect(ctx.get(validationContextKey)).toEqual({
+      canTransition: true,
+      byBinding: {},
+    });
+  });
+});
+
+test("status flips to completed after the flow ends", () => {
+  const ctx = new ContextPlugin();
+  const state = new StateContextPlugin();
+  const player = new Player({ plugins: [ctx, state] });
+
+  player.start(minimalFlow as any);
+  player.hooks.state.call({
+    status: "completed",
+    flow: minimalFlow as any,
+  } as any);
+
+  expect(ctx.get(playerStatusContextKey)).toBe("completed");
+});

package/src/__tests__/store.test.ts

@@ -0,0 +1,107 @@
+import { test, expect } from "vitest";
+import { ContextStore } from "../store";
+import { defineContextKey } from "../key";
+
+test("set / get / has literal", () => {
+  const store = new ContextStore();
+  const key = defineContextKey<number>("count", "A count");
+
+  expect(store.has(key)).toBe(false);
+  store.set(key, 42);
+  expect(store.has(key)).toBe(true);
+  expect(store.get(key)).toBe(42);
+
+  const descriptors = store.list();
+  expect(descriptors).toHaveLength(1);
+  expect(descriptors[0]).toMatchObject({
+    description: "A count",
+    hasValue: true,
+    hasTransform: false,
+  });
+});
+
+test("transform aggregates from sources on get", () => {
+  const store = new ContextStore();
+  const a = defineContextKey<number>("a", "A");
+  const b = defineContextKey<number>("b", "B");
+  const sum = defineContextKey<number>("sum", "A + B");
+
+  store.set(a, 2);
+  store.set(b, 3);
+  store.registerTransform(sum, {
+    sources: [a, b],
+    compute: (read) => (read(a) ?? 0) + (read(b) ?? 0),
+  });
+
+  expect(store.get(sum)).toBe(5);
+  expect(store.has(sum)).toBe(true);
+});
+
+test("literal overrides transform on get", () => {
+  const store = new ContextStore();
+  const a = defineContextKey<number>("a", "A");
+  const target = defineContextKey<number>("t", "T");
+
+  store.set(a, 10);
+  store.registerTransform(target, {
+    sources: [a],
+    compute: (read) => (read(a) ?? 0) * 2,
+  });
+  expect(store.get(target)).toBe(20);
+
+  store.set(target, 99);
+  expect(store.get(target)).toBe(99);
+});
+
+test("dependentsOf tracks reverse index from transform sources", () => {
+  const store = new ContextStore();
+  const src = defineContextKey<number>("src", "src");
+  const t1 = defineContextKey<number>("t1", "t1");
+  const t2 = defineContextKey<number>("t2", "t2");
+
+  store.registerTransform(t1, { sources: [src], compute: () => 1 });
+  store.registerTransform(t2, { sources: [src], compute: () => 2 });
+
+  const deps = store.dependentsOf(src.symbol);
+  const depSymbols = new Set(deps.map((k) => k.symbol));
+  expect(depSymbols.has(t1.symbol)).toBe(true);
+  expect(depSymbols.has(t2.symbol)).toBe(true);
+  expect(deps).toHaveLength(2);
+});
+
+test("re-registering a transform updates the reverse index", () => {
+  const store = new ContextStore();
+  const oldSrc = defineContextKey<number>("old", "old");
+  const newSrc = defineContextKey<number>("new", "new");
+  const target = defineContextKey<number>("target", "target");
+
+  store.registerTransform(target, { sources: [oldSrc], compute: () => 1 });
+  store.registerTransform(target, { sources: [newSrc], compute: () => 2 });
+
+  expect(store.dependentsOf(oldSrc.symbol)).toHaveLength(0);
+  expect(store.dependentsOf(newSrc.symbol)).toHaveLength(1);
+});
+
+test("freeze captures literal and transform-computed values, deep-freezes the snapshot", () => {
+  const store = new ContextStore();
+  const a = defineContextKey<number>("a", "A");
+  const doubled = defineContextKey<number>("doubled", "A doubled");
+
+  store.set(a, 7);
+  store.registerTransform(doubled, {
+    sources: [a],
+    compute: (read) => (read(a) ?? 0) * 2,
+  });
+
+  const snapshot = store.freeze({ endedAt: 1000 });
+  expect(snapshot.endedAt).toBe(1000);
+  expect(snapshot.entries).toHaveLength(2);
+  const byDesc = Object.fromEntries(
+    snapshot.entries.map((e) => [e.description, e.value]),
+  );
+  expect(byDesc).toEqual({ A: 7, "A doubled": 14 });
+
+  expect(Object.isFrozen(snapshot)).toBe(true);
+  expect(Object.isFrozen(snapshot.entries)).toBe(true);
+  expect(Object.isFrozen(snapshot.entries[0])).toBe(true);
+});

package/src/history.ts

@@ -0,0 +1,25 @@
+import type { FrozenContextSnapshot } from "./types";
+
+/**
+ * Append-only stack of frozen per-flow snapshots. The plugin pushes one
+ * snapshot on each flow end; consumers read via `entries()`.
+ */
+export class ContextHistory {
+  private stack: FrozenContextSnapshot[] = [];
+
+  push(snapshot: FrozenContextSnapshot): void {
+    this.stack.push(snapshot);
+  }
+
+  entries(): ReadonlyArray<FrozenContextSnapshot> {
+    return this.stack;
+  }
+
+  size(): number {
+    return this.stack.length;
+  }
+
+  clear(): void {
+    this.stack = [];
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./plugin";
+export * from "./symbols";
+export * from "./types";
+export * from "./key";
+export * from "./utils";
+export * from "./state-plugin";

package/src/key.ts

@@ -0,0 +1,35 @@
+import type { ContextKey } from "./types";
+
+const KEY_NAMESPACE = "player-ui.context.";
+
+/**
+ * Create a typed, globally-identifiable context key.
+ *
+ * Identity is backed by `Symbol.for`, so two keys created with the same `name`
+ * in different bundles refer to the same store entry. The `description` is the
+ * human-readable label used by introspection consumers.
+ */
+export const defineContextKey = <Value>(
+  name: string,
+  description: string,
+): ContextKey<Value> => ({
+  symbol: Symbol.for(`${KEY_NAMESPACE}${name}`),
+  description,
+});
+
+/**
+ * Resolve the global symbol for a context key name. Used by native wrappers
+ * that cross the JS bridge with string names instead of JS symbols.
+ */
+export const resolveContextKeySymbol = (name: string): symbol =>
+  Symbol.for(`${KEY_NAMESPACE}${name}`);
+
+/**
+ * Reverse-derive the name from a key created via `defineContextKey`. Returns
+ * `undefined` if the key's symbol was not created in the context namespace.
+ */
+export const nameOfContextKey = (key: ContextKey): string | undefined => {
+  const k = Symbol.keyFor(key.symbol);
+  if (!k || !k.startsWith(KEY_NAMESPACE)) return undefined;
+  return k.slice(KEY_NAMESPACE.length);
+};