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

package/src/plugin.ts

@@ -0,0 +1,261 @@
+import type { Player, PlayerPlugin, Flow } from "@player-ui/player";
+import { SyncHook, SyncWaterfallHook } from "tapable-ts";
+import { ContextStore } from "./store";
+import { ContextHistory } from "./history";
+import { ContextPluginSymbol } from "./symbols";
+import { defineContextKey, nameOfContextKey } from "./key";
+import type {
+  ContextEntryDescriptor,
+  ContextGlobalSubscriber,
+  ContextKey,
+  ContextSubscriber,
+  ContextTransform,
+  FrozenContextSnapshot,
+  SubscriptionToken,
+} from "./types";
+
+type TransformRegistration = {
+  key: ContextKey;
+  transform: ContextTransform<unknown>;
+};
+
+let subscriptionCounter = 0;
+
+/**
+ * Maintains a per-flow store of context entries keyed by symbol, with
+ * registered transforms for derived values and a subscription API for
+ * external consumers. On flow end the active store is frozen into a snapshot
+ * and pushed onto a history stack; a fresh store is created for the next flow,
+ * with transforms re-applied. Subscribers persist across flow rotations.
+ */
+export class ContextPlugin implements PlayerPlugin {
+  name = "context";
+
+  static Symbol: symbol = ContextPluginSymbol;
+  public readonly symbol: symbol = ContextPlugin.Symbol;
+
+  public readonly hooks = {
+    onSet: new SyncHook<[ContextKey, unknown]>(),
+    resolveValue: new SyncWaterfallHook<[unknown, ContextKey]>(),
+    onRegister: new SyncHook<[ContextKey]>(),
+    onFlowFrozen: new SyncHook<[FrozenContextSnapshot]>(),
+  };
+
+  protected store: ContextStore;
+  protected historyStack: ContextHistory;
+  private transforms = new Map<symbol, TransformRegistration>();
+  private perKeySubs = new Map<
+    symbol,
+    Map<SubscriptionToken, ContextSubscriber<unknown>>
+  >();
+  private globalSubs = new Map<SubscriptionToken, ContextGlobalSubscriber>();
+  private tokenIndex = new Map<SubscriptionToken, symbol | undefined>();
+  private currentFlowId: string | undefined;
+
+  constructor() {
+    this.store = new ContextStore();
+    this.historyStack = new ContextHistory();
+  }
+
+  apply(player: Player) {
+    const existing = player.findPlugin<ContextPlugin>(ContextPluginSymbol);
+    if (existing !== undefined && existing !== this) {
+      this.store = existing.store;
+      this.historyStack = existing.historyStack;
+      this.transforms = existing.transforms;
+      this.perKeySubs = existing.perKeySubs;
+      this.globalSubs = existing.globalSubs;
+      this.tokenIndex = existing.tokenIndex;
+      return;
+    }
+
+    player.hooks.onStart.tap(this.name, (flow: Flow) => {
+      this.currentFlowId = flow?.id;
+    });
+
+    player.hooks.onEnd.tap(this.name, () => {
+      const snapshot = this.store.freeze({
+        flowId: this.currentFlowId,
+        endedAt: Date.now(),
+      });
+      this.historyStack.push(snapshot);
+      this.hooks.onFlowFrozen.call(snapshot);
+      this.rotateStore();
+      this.currentFlowId = undefined;
+    });
+  }
+
+  register<Value>(key: ContextKey<Value>): void {
+    const added = this.store.register(key);
+    if (added) {
+      this.hooks.onRegister.call(key);
+    }
+  }
+
+  set<Value>(key: ContextKey<Value>, value: Value): void {
+    const isFirstSighting = !this.store.has(key);
+    this.store.set(key, value);
+    if (isFirstSighting) {
+      this.hooks.onRegister.call(key);
+    }
+    this.notify(key, value);
+
+    const dependents = this.store.dependentsOf(key.symbol);
+    for (const dep of dependents) {
+      const computed = this.store.get(dep);
+      this.notify(dep, computed);
+    }
+  }
+
+  get<Value>(key: ContextKey<Value>): Value | undefined {
+    const raw = this.store.get(key);
+    const resolved = this.hooks.resolveValue.call(raw, key);
+    return resolved as Value | undefined;
+  }
+
+  has(key: ContextKey): boolean {
+    return this.store.has(key);
+  }
+
+  registerTransform<Value>(
+    key: ContextKey<Value>,
+    transform: ContextTransform<Value>,
+  ): void {
+    const isFirstSighting = !this.store.has(key);
+    this.store.registerTransform(key, transform);
+    this.transforms.set(key.symbol, {
+      key,
+      transform: {
+        sources: transform.sources,
+        compute: transform.compute as ContextTransform<unknown>["compute"],
+      },
+    });
+    if (isFirstSighting) {
+      this.hooks.onRegister.call(key);
+    }
+  }
+
+  subscribe<Value>(
+    key: ContextKey<Value>,
+    handler: ContextSubscriber<Value>,
+  ): SubscriptionToken {
+    const token = this.nextToken();
+    let bucket = this.perKeySubs.get(key.symbol);
+    if (!bucket) {
+      bucket = new Map();
+      this.perKeySubs.set(key.symbol, bucket);
+    }
+    bucket.set(token, handler as ContextSubscriber<unknown>);
+    this.tokenIndex.set(token, key.symbol);
+    return token;
+  }
+
+  subscribeAll(handler: ContextGlobalSubscriber): SubscriptionToken {
+    const token = this.nextToken();
+    this.globalSubs.set(token, handler);
+    this.tokenIndex.set(token, undefined);
+    return token;
+  }
+
+  unsubscribe(token: SubscriptionToken): void {
+    const owner = this.tokenIndex.get(token);
+    if (owner === undefined) {
+      this.globalSubs.delete(token);
+    } else {
+      this.perKeySubs.get(owner)?.delete(token);
+    }
+    this.tokenIndex.delete(token);
+  }
+
+  list(): ReadonlyArray<ContextEntryDescriptor> {
+    return this.store.list();
+  }
+
+  history(): ReadonlyArray<FrozenContextSnapshot> {
+    return this.historyStack.entries();
+  }
+
+  snapshot(): FrozenContextSnapshot {
+    return this.store.freeze({
+      flowId: this.currentFlowId,
+      endedAt: Date.now(),
+    });
+  }
+
+  /**
+   * Bridge-friendly: set a value by string name. Used by native wrappers that
+   * cannot construct a `ContextKey` object directly.
+   */
+  setByName(name: string, description: string, value: unknown): void {
+    this.set(this.ensureNamedKey(name, description), value);
+  }
+
+  /** Bridge-friendly: get a value by string name. */
+  getByName(name: string): unknown {
+    return this.get(this.ensureNamedKey(name));
+  }
+
+  /** Bridge-friendly: check presence by string name. */
+  hasByName(name: string): boolean {
+    return this.has(this.ensureNamedKey(name));
+  }
+
+  /** Bridge-friendly: subscribe by string name. */
+  subscribeByName(
+    name: string,
+    description: string,
+    handler: (value: unknown, name: string) => void,
+  ): SubscriptionToken {
+    return this.subscribe(this.ensureNamedKey(name, description), (value) =>
+      handler(value, name),
+    );
+  }
+
+  /**
+   * Bridge-friendly: subscribe to all updates. The handler receives the
+   * key's resolved name (or undefined for non-namespaced keys).
+   */
+  subscribeAllByName(
+    handler: (
+      value: unknown,
+      name: string | undefined,
+      description: string,
+    ) => void,
+  ): SubscriptionToken {
+    return this.subscribeAll((value, key) =>
+      handler(value, nameOfContextKey(key), key.description),
+    );
+  }
+
+  private ensureNamedKey(
+    name: string,
+    description?: string,
+  ): ContextKey<unknown> {
+    return defineContextKey<unknown>(name, description ?? name);
+  }
+
+  private notify<Value>(key: ContextKey<Value>, value: Value | undefined) {
+    this.hooks.onSet.call(key, value);
+    const bucket = this.perKeySubs.get(key.symbol);
+    if (bucket) {
+      for (const handler of bucket.values()) {
+        (handler as ContextSubscriber<Value>)(value, key);
+      }
+    }
+    for (const handler of this.globalSubs.values()) {
+      handler(value, key);
+    }
+  }
+
+  private rotateStore() {
+    this.store = new ContextStore();
+    for (const { key, transform } of this.transforms.values()) {
+      this.store.registerTransform(key, transform);
+    }
+  }
+
+  private nextToken(): SubscriptionToken {
+    subscriptionCounter += 1;
+    return `ctx_${subscriptionCounter}`;
+  }
+}

package/src/state-plugin.ts

@@ -0,0 +1,286 @@
+import type { Player, PlayerPlugin } from "@player-ui/player";
+import { defineContextKey } from "./key";
+import { getContextPlugin } from "./utils";
+import type { ContextKey } from "./types";
+
+/** Set a single binding in the Player data model. */
+export type SetDataAction = (binding: string, value: unknown) => void;
+
+/** Transition the running flow using the given transition value. */
+export type TransitionAction = (transition: string) => void;
+
+/** A single validation, projected to its serializable fields. */
+export type ContextValidation = {
+  severity: "error" | "warning";
+  message: string;
+  displayTarget?: "page" | "section" | "field";
+  blocking?: boolean | "once";
+};
+
+/** Validation state for the running view, keyed by binding. */
+export type ValidationContext = {
+  /** Whether the view has no blocking validations (derived, no side effects). */
+  canTransition: boolean;
+  /** Active validations per binding string. */
+  byBinding: Record<string, ReadonlyArray<ContextValidation>>;
+};
+
+/** Identifier of the currently-running flow. */
+export const flowIdContextKey: ContextKey<string> = defineContextKey<string>(
+  "player.flow.id",
+  "Identifier of the running flow",
+);
+
+/** Name of the current FSM state within the running flow. */
+export const flowStateContextKey: ContextKey<string> = defineContextKey<string>(
+  "player.flow.state",
+  "Name of the current FSM state in the running flow",
+);
+
+/** Identifier of the view currently resolved by the ViewController. */
+export const viewIdContextKey: ContextKey<string> = defineContextKey<string>(
+  "player.view.id",
+  "Identifier of the currently-resolved view",
+);
+
+/** Full resolved view object for the current FSM state. */
+export const viewContextKey: ContextKey<unknown> = defineContextKey<unknown>(
+  "player.view",
+  "Full resolved view object for the current FSM state",
+);
+
+/** Full data model tree for the running flow. */
+export const dataContextKey: ContextKey<unknown> = defineContextKey<unknown>(
+  "player.data",
+  "Full data model tree for the running flow",
+);
+
+/** Player flow status: not-started, in-progress, completed, or error. */
+export const playerStatusContextKey: ContextKey<string> =
+  defineContextKey<string>(
+    "player.status",
+    "Player flow status: not-started, in-progress, completed, or error",
+  );
+
+/** Validation state for the running view, keyed by binding. */
+export const validationContextKey: ContextKey<ValidationContext> =
+  defineContextKey<ValidationContext>(
+    "player.validation",
+    "Validation state for the running view, keyed by binding",
+  );
+
+/**
+ * Action entry whose value is a callable that sets a binding in the data
+ * model. Read via `ctx.get(setDataActionKey)`; absent until a flow is running.
+ */
+export const setDataActionKey: ContextKey<SetDataAction> =
+  defineContextKey<SetDataAction>(
+    "player.data.set",
+    "Set a value in the Player data model at the given binding",
+  );
+
+/**
+ * Action entry whose value is a callable that transitions the running flow.
+ * Read via `ctx.get(transitionActionKey)`; absent until a flow is running.
+ */
+export const transitionActionKey: ContextKey<TransitionAction> =
+  defineContextKey<TransitionAction>(
+    "player.flow.transition",
+    "Transition the current flow using the given transition value",
+  );
+
+/**
+ * Aggregated snapshot composed from every other StateContextPlugin key.
+ *
+ * Actions are scoped to the construct they operate on — `transition` lives
+ * under `flow`, `set` under `data` — rather than in a flat actions bag. Each
+ * is bound to the live controller and is absent until a flow is in-progress.
+ */
+export type PlayerStateContext = {
+  status?: string;
+  flow: {
+    id?: string;
+    state?: string;
+    /** Transition the running flow (e.g. 'Next'). */
+    transition?: TransitionAction;
+  };
+  view: {
+    id?: string;
+    resolved?: unknown;
+  };
+  data: {
+    /** Full data model tree for the running flow. */
+    model?: unknown;
+    /** Set a value in the data model at the given binding. */
+    set?: SetDataAction;
+  };
+  /** Validation state for the running view, keyed by binding. */
+  validation: ValidationContext;
+};
+
+/**
+ * Single roll-up key that aggregates every other [[StateContextPlugin]] entry
+ * into one object. Backed by a transform — reading recomputes from the latest
+ * source values, and subscribers fire whenever any source updates.
+ */
+export const playerStateContextKey: ContextKey<PlayerStateContext> =
+  defineContextKey<PlayerStateContext>(
+    "player.state",
+    "Aggregated snapshot of every Player runtime context entry",
+  );
+
+/**
+ * A consumer plugin that mirrors Player runtime state into the ContextPlugin
+ * store. Registers a small, opinionated set of context entries (flow id,
+ * current FSM state, view id, full view, data model, status) so external
+ * automation/devtools can observe the running Player without tapping every
+ * controller hook themselves.
+ *
+ * Auto-registers a [[ContextPlugin]] if one isn't already on the player.
+ */
+export class StateContextPlugin implements PlayerPlugin {
+  name = "state-context";
+
+  apply(player: Player) {
+    const ctx = getContextPlugin(player);
+
+    // The validation controller for the running flow, captured so data/view
+    // updates can re-publish a passive (side-effect-free) validation snapshot.
+    type ValidationControllerLike = Parameters<
+      Parameters<typeof player.hooks.validationController.tap>[1]
+    >[0];
+    let validationController: ValidationControllerLike | undefined;
+
+    const publishValidation = () => {
+      if (!validationController) return;
+      const byBinding: Record<string, ReadonlyArray<ContextValidation>> = {};
+      let canTransition = true;
+      validationController.getBindings().forEach((binding) => {
+        const all = (validationController!
+          .getValidationForBinding(binding)
+          ?.getAll() ?? []) as ReadonlyArray<ContextValidation>;
+        if (all.length === 0) return;
+        byBinding[binding.asString()] = all.map((v) => ({
+          severity: v.severity,
+          message: v.message,
+          displayTarget: v.displayTarget,
+          blocking: v.blocking,
+        }));
+        if (all.some((v) => v.blocking)) {
+          canTransition = false;
+        }
+      });
+      ctx.set(validationContextKey, { canTransition, byBinding });
+    };
+
+    ctx.register(flowIdContextKey);
+    ctx.register(flowStateContextKey);
+    ctx.register(viewIdContextKey);
+    ctx.register(viewContextKey);
+    ctx.register(dataContextKey);
+    ctx.register(playerStatusContextKey);
+    ctx.register(validationContextKey);
+    ctx.register(setDataActionKey);
+    ctx.register(transitionActionKey);
+
+    ctx.registerTransform(playerStateContextKey, {
+      sources: [
+        flowIdContextKey,
+        flowStateContextKey,
+        viewIdContextKey,
+        viewContextKey,
+        dataContextKey,
+        playerStatusContextKey,
+        validationContextKey,
+        setDataActionKey,
+        transitionActionKey,
+      ],
+      compute: (read) => ({
+        status: read(playerStatusContextKey),
+        flow: {
+          id: read(flowIdContextKey),
+          state: read(flowStateContextKey),
+          transition: read(transitionActionKey),
+        },
+        view: {
+          id: read(viewIdContextKey),
+          resolved: read(viewContextKey),
+        },
+        data: {
+          model: read(dataContextKey),
+          set: read(setDataActionKey),
+        },
+        validation: read(validationContextKey) ?? {
+          canTransition: true,
+          byBinding: {},
+        },
+      }),
+    });
+
+    player.hooks.onStart.tap(this.name, (flow) => {
+      if (flow?.id) {
+        ctx.set(flowIdContextKey, flow.id);
+      }
+    });
+
+    player.hooks.state.tap(this.name, (state) => {
+      ctx.set(playerStatusContextKey, state.status);
+    });
+
+    player.hooks.flowController.tap(this.name, (flowController) => {
+      // Bind to the concrete controller instance for the running flow.
+      const transition: TransitionAction = (value) =>
+        flowController.transition(value);
+      ctx.set(transitionActionKey, transition);
+
+      flowController.hooks.flow.tap(this.name, (flowInstance) => {
+        const recordState = () => {
+          const name = flowInstance.currentState?.name;
+          if (name) {
+            ctx.set(flowStateContextKey, name);
+          }
+        };
+        recordState();
+        flowInstance.hooks.afterTransition.tap(this.name, recordState);
+      });
+    });
+
+    player.hooks.validationController.tap(this.name, (vc) => {
+      validationController = vc;
+      publishValidation();
+    });
+
+    player.hooks.viewController.tap(this.name, (viewController) => {
+      viewController.hooks.view.tap(this.name, (view) => {
+        const id = view.initialView?.id;
+        if (id) {
+          ctx.set(viewIdContextKey, id);
+        }
+        view.hooks.onUpdate.tap(this.name, (resolved) => {
+          ctx.set(viewContextKey, resolved);
+          if (resolved?.id) {
+            ctx.set(viewIdContextKey, resolved.id);
+          }
+          // Validation resets per view; re-publish for the resolved view.
+          publishValidation();
+        });
+      });
+    });
+
+    player.hooks.dataController.tap(this.name, (dataController) => {
+      // Bind the set-data action to this concrete controller instance.
+      const setData: SetDataAction = (binding, value) => {
+        dataController.set([[binding, value]]);
+      };
+      ctx.set(setDataActionKey, setData);
+
+      const publish = () => {
+        ctx.set(dataContextKey, dataController.serialize());
+        // Validation re-evaluates on data change.
+        publishValidation();
+      };
+      dataController.hooks.onUpdate.tap(this.name, publish);
+      publish();
+    });
+  }
+}