@dreamboard-games/ui-sdk 0.0.41

package/src/hooks/useBoardInteractions.test.tsx

@@ -0,0 +1,622 @@
+import { expect, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import {
+  createInteractionUiStore,
+  InteractionUiProvider,
+  type InteractionUiStoreApi,
+} from "../context/InteractionDraftContext.js";
+import { PluginSessionContext } from "../context/PluginSessionContext.js";
+import { RuntimeContext } from "../context/RuntimeContext.js";
+import type {
+  InteractionDescriptor,
+  PluginStateSnapshot,
+} from "../types/plugin-state.js";
+import type { PluginSessionState, RuntimeAPI } from "../types/runtime-api.js";
+import { ValidationError } from "../errors/ValidationError.js";
+import {
+  BoardInteractionConflictError,
+  useBoardInteractions,
+} from "./useBoardInteractions.js";
+
+function createSessionState(
+  overrides: Partial<PluginSessionState> = {},
+): PluginSessionState {
+  return {
+    status: "ready",
+    sessionId: "session-1",
+    controllablePlayerIds: ["player-1"],
+    controllingPlayerId: "player-1",
+    userId: "user-1",
+    ...overrides,
+  };
+}
+
+type DescriptorOverrides = Partial<Omit<InteractionDescriptor, "inputs">> & {
+  interactionId: string;
+  inputs?: InteractionDescriptor["inputs"];
+  keys?: readonly string[];
+  targets?: Record<string, readonly string[]>;
+};
+
+function createDescriptor(
+  overrides: DescriptorOverrides,
+): InteractionDescriptor {
+  const {
+    targets: targetsOverride,
+    keys: keysOverride,
+    inputs: inputsOverride,
+    ...descriptorOverrides
+  } = overrides;
+  const eligibleTargets = targetsOverride ?? {};
+  const inputKeys = keysOverride ?? Object.keys(eligibleTargets);
+  const inputs =
+    inputsOverride ??
+    inputKeys.map((inputKey) => {
+      const targetKind = targetKindForInputKey(inputKey);
+      return {
+        key: inputKey,
+        kind: targetKind ? `board-${targetKind}` : "form",
+        domain: targetKind
+          ? {
+              type: "target" as const,
+              targetKind,
+              eligibleTargets: eligibleTargets[inputKey] ?? [],
+            }
+          : {
+              type: "choice" as const,
+              choices: [{ value: "fallback", label: "Fallback" }],
+            },
+      };
+    });
+  return {
+    phaseName: "play",
+    interactionKey: `play.${overrides.interactionId}`,
+    kind: "action",
+    inputs,
+    commit: { mode: "manual" },
+    available: true,
+    ...descriptorOverrides,
+    inputs,
+  };
+}
+
+function targetKindForInputKey(inputKey: string) {
+  if (inputKey.toLowerCase().includes("vertex")) return "vertex";
+  if (inputKey.toLowerCase().includes("edge")) return "edge";
+  if (inputKey.toLowerCase().includes("space")) return "space";
+  if (inputKey.toLowerCase().includes("tile")) return "tile";
+  if (inputKey.toLowerCase().includes("card")) return "card";
+  return undefined;
+}
+
+function createSnapshot(
+  session: PluginSessionState,
+  descriptors: InteractionDescriptor[],
+): PluginStateSnapshot {
+  return {
+    view: null,
+    gameplay: {
+      currentPhase: "play",
+      currentStage: null,
+      activePlayers: ["player-1"],
+      availableInteractions: descriptors,
+      zones: {},
+    },
+    lobby: null,
+    notifications: [],
+    session,
+    history: null,
+    syncId: 1,
+  };
+}
+
+interface RecordedSubmit {
+  playerId: string;
+  interactionId: string;
+  params: Record<string, unknown>;
+}
+
+function createRuntime(
+  snapshot: PluginStateSnapshot,
+  recorder?: RecordedSubmit[],
+  submitOverride?: RuntimeAPI["submitInteraction"],
+): RuntimeAPI & {
+  getSnapshot: () => PluginStateSnapshot;
+  subscribeToState: (
+    listener: (state: PluginStateSnapshot) => void,
+  ) => () => void;
+} {
+  return {
+    validateInteraction: async () => ({ valid: true }),
+    submitInteraction:
+      submitOverride ??
+      (async (playerId, interactionId, params) => {
+        recorder?.push({ playerId, interactionId, params });
+        return undefined;
+      }),
+    getSessionState: () => snapshot.session,
+    disconnect: () => undefined,
+    getSnapshot: () => snapshot,
+    subscribeToState: () => () => undefined,
+  };
+}
+
+function render<T>(
+  snapshot: PluginStateSnapshot,
+  harness: () => T,
+  recorder?: RecordedSubmit[],
+  setupDraft?: (store: InteractionUiStoreApi) => void,
+  submitOverride?: RuntimeAPI["submitInteraction"],
+): T {
+  const runtime = createRuntime(snapshot, recorder, submitOverride);
+  const draftStore = createInteractionUiStore();
+  setupDraft?.(draftStore);
+  let captured!: T;
+  function Harness() {
+    captured = harness();
+    return null;
+  }
+  renderToString(
+    <RuntimeContext.Provider value={runtime}>
+      <PluginSessionContext.Provider value={snapshot.session}>
+        <InteractionUiProvider store={draftStore}>
+          <Harness />
+        </InteractionUiProvider>
+      </PluginSessionContext.Provider>
+    </RuntimeContext.Provider>,
+  );
+  return captured;
+}
+
+test("useBoardInteractions unions eligibility across available handles", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "buildSettlement",
+      surface: "board-vertex",
+      targets: { vertexId: ["v-1", "v-2"] },
+      keys: ["vertexId"],
+    }),
+    createDescriptor({
+      interactionId: "upgradeToCity",
+      surface: "board-vertex",
+      targets: { vertexId: ["v-3"] },
+      keys: ["vertexId"],
+    }),
+    createDescriptor({
+      interactionId: "buildRoad",
+      surface: "board-edge",
+      targets: { edgeId: ["e-10"] },
+      keys: ["edgeId"],
+    }),
+  ]);
+
+  const board = render(snapshot, () => useBoardInteractions());
+
+  expect(board.interactions.map((d) => d.interactionId)).toEqual([
+    "buildSettlement",
+    "upgradeToCity",
+    "buildRoad",
+  ]);
+  expect(Array.from(board.eligible.vertex)).toEqual(["v-1", "v-2", "v-3"]);
+  expect(Array.from(board.eligible.edge)).toEqual(["e-10"]);
+  expect(board.isEligible("v-3")).toBe(true);
+  expect(board.isEligible("v-3", "vertex")).toBe(true);
+  expect(board.isEligible("v-3", "edge")).toBe(false);
+  expect(board.isEligible("missing")).toBe(false);
+});
+
+test("useBoardInteractions skips unavailable handles when merging eligibility", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "buildRoad",
+      surface: "board-edge",
+      available: false,
+      targets: { edgeId: ["e-1"] },
+      keys: ["edgeId"],
+    }),
+    createDescriptor({
+      interactionId: "placeSetupRoad",
+      surface: "board-edge",
+      targets: { edgeId: ["e-2"] },
+      keys: ["edgeId"],
+    }),
+  ]);
+
+  const board = render(snapshot, () => useBoardInteractions());
+
+  expect(Array.from(board.eligible.edge)).toEqual(["e-2"]);
+});
+
+test("useBoardInteractions unarmed matching interactions require an explicit route", async () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "buildSettlement",
+      commit: { mode: "autoWhenReady" },
+      targets: { vertexId: ["v-shared"] },
+      keys: ["vertexId"],
+    }),
+    createDescriptor({
+      interactionId: "placeSetupSettlement",
+      commit: { mode: "autoWhenReady" },
+      targets: { vertexId: ["v-shared"] },
+      keys: ["vertexId"],
+    }),
+  ]);
+
+  const recorder: RecordedSubmit[] = [];
+  const board = render(snapshot, () => useBoardInteractions(), recorder);
+
+  await expect(board.select.vertex("v-shared")).rejects.toThrow(
+    BoardInteractionConflictError,
+  );
+  expect(recorder).toEqual([]);
+});
+
+test("useBoardInteractions equal-rank unarmed matches throw BoardInteractionConflictError", async () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "buildSettlement",
+      surface: "board-vertex",
+      targets: { vertexId: ["v-shared"] },
+      keys: ["vertexId"],
+    }),
+    createDescriptor({
+      interactionId: "upgradeToCity",
+      surface: "board-vertex",
+      targets: { vertexId: ["v-shared"] },
+      keys: ["vertexId"],
+    }),
+  ]);
+
+  const board = render(snapshot, () => useBoardInteractions());
+
+  try {
+    await board.select.vertex("v-shared");
+    throw new Error("Expected board.select.vertex to throw");
+  } catch (error) {
+    expect(error).toBeInstanceOf(BoardInteractionConflictError);
+    expect((error as BoardInteractionConflictError).targetKind).toBe("vertex");
+    expect((error as BoardInteractionConflictError).targetId).toBe("v-shared");
+    expect((error as BoardInteractionConflictError).interactionKeys).toEqual([
+      "play.buildSettlement",
+      "play.upgradeToCity",
+    ]);
+  }
+});
+
+test("useBoardInteractions target-kind select skips unavailable handles and returns null when nothing matches", async () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "buildSettlement",
+      surface: "board-vertex",
+      available: false,
+      targets: { vertexId: ["v-1"] },
+      keys: ["vertexId"],
+    }),
+  ]);
+
+  const recorder: RecordedSubmit[] = [];
+  const board = render(snapshot, () => useBoardInteractions(), recorder);
+
+  const fired = await board.select.vertex("v-1");
+  expect(fired).toBeNull();
+  expect(recorder).toEqual([]);
+});
+
+test("useBoardInteractions target-kind select merges extraInputs and backfills null for missing required inputs", async () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "moveRobber",
+      surface: "board-tile",
+      commit: { mode: "autoWhenReady" },
+      targets: { spaceId: ["space-7"] },
+      keys: ["spaceId", "stealFromPlayerId"],
+    }),
+  ]);
+
+  const recorder: RecordedSubmit[] = [];
+  const board = render(snapshot, () => useBoardInteractions(), recorder);
+
+  await board.select.space("space-7");
+  expect(recorder).toEqual([
+    {
+      playerId: "player-1",
+      interactionId: "moveRobber",
+      params: { spaceId: "space-7", stealFromPlayerId: null },
+    },
+  ]);
+
+  recorder.length = 0;
+  await board.select.space("space-7", {
+    stealFromPlayerId: "player-2",
+  });
+  expect(recorder).toEqual([
+    {
+      playerId: "player-1",
+      interactionId: "moveRobber",
+      params: { spaceId: "space-7", stealFromPlayerId: "player-2" },
+    },
+  ]);
+});
+
+test("useBoardInteractions targetLayers expose reducer eligibility sets", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "buildRoad",
+      surface: "board-edge",
+      targets: { edgeId: ["e-1", "e-2"] },
+      keys: ["edgeId"],
+    }),
+    createDescriptor({
+      interactionId: "buildSettlement",
+      surface: "board-vertex",
+      targets: { vertexId: ["v-1"] },
+      keys: ["vertexId"],
+    }),
+  ]);
+
+  const board = render(snapshot, () => useBoardInteractions());
+
+  expect(board.targetLayers.edge().eligible).toBe(board.eligible.edge);
+  expect(board.targetLayers.vertex().eligible).toBe(board.eligible.vertex);
+  expect(Array.from(board.targetLayers.edge().eligible ?? [])).toEqual([
+    "e-1",
+    "e-2",
+  ]);
+  expect(Array.from(board.targetLayers.vertex().eligible ?? [])).toEqual([
+    "v-1",
+  ]);
+});
+
+test("useBoardInteractions targetLayers forward ambiguity through onError", async () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "buildRoad",
+      surface: "board-edge",
+      targets: { edgeId: ["e-shared"] },
+      keys: ["edgeId"],
+    }),
+    createDescriptor({
+      interactionId: "placeSetupRoad",
+      surface: "board-edge",
+      targets: { edgeId: ["e-shared"] },
+      keys: ["edgeId"],
+    }),
+  ]);
+
+  const recorder: RecordedSubmit[] = [];
+  const observedErrors: unknown[] = [];
+  const board = render(snapshot, () => useBoardInteractions(), recorder);
+
+  await board.targetLayers
+    .edge({
+      onError: (error) => observedErrors.push(error),
+    })
+    .selectTargetId?.("e-shared");
+
+  expect(recorder).toEqual([]);
+  expect(observedErrors).toHaveLength(1);
+  expect(observedErrors[0]).toBeInstanceOf(BoardInteractionConflictError);
+});
+
+test("useBoardInteractions targetLayers apply extraInputs and onBeforeSelect", async () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "moveRobber",
+      surface: "board-tile",
+      commit: { mode: "autoWhenReady" },
+      targets: { spaceId: ["space-7"] },
+      keys: ["spaceId", "stealFromPlayerId"],
+    }),
+  ]);
+
+  const recorder: RecordedSubmit[] = [];
+  let beforeCount = 0;
+  const board = render(snapshot, () => useBoardInteractions(), recorder);
+
+  await board.targetLayers
+    .space({
+      extraInputs: (targetId) => ({
+        stealFromPlayerId: targetId === "space-7" ? "player-2" : null,
+      }),
+      onBeforeSelect: () => {
+        beforeCount += 1;
+      },
+    })
+    .selectTargetId?.("space-7");
+
+  expect(beforeCount).toBe(1);
+  expect(recorder).toEqual([
+    {
+      playerId: "player-1",
+      interactionId: "moveRobber",
+      params: { spaceId: "space-7", stealFromPlayerId: "player-2" },
+    },
+  ]);
+});
+
+test("useBoardInteractions targetLayers route submit failures to onError", async () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "buildSettlement",
+      surface: "board-vertex",
+      commit: { mode: "autoWhenReady" },
+      targets: { vertexId: ["v-1"] },
+      keys: ["vertexId"],
+    }),
+  ]);
+
+  const submittedError = new Error("nope");
+  const observedErrors: unknown[] = [];
+  const board = render(
+    snapshot,
+    () => useBoardInteractions(),
+    undefined,
+    undefined,
+    async () => {
+      throw submittedError;
+    },
+  );
+
+  await board.targetLayers
+    .vertex({
+      onError: (error) => observedErrors.push(error),
+    })
+    .selectTargetId?.("v-1");
+
+  expect(observedErrors).toHaveLength(1);
+  expect(observedErrors[0]).toBeInstanceOf(ValidationError);
+  expect((observedErrors[0] as Error).message).toBe("nope");
+});
+
+test("useBoardInteractions targetLayers reject submit failures without onError", async () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "buildSettlement",
+      surface: "board-vertex",
+      commit: { mode: "autoWhenReady" },
+      targets: { vertexId: ["v-1"] },
+      keys: ["vertexId"],
+    }),
+  ]);
+
+  const board = render(
+    snapshot,
+    () => useBoardInteractions(),
+    undefined,
+    undefined,
+    async () => {
+      throw new Error("blocked");
+    },
+  );
+
+  const selectTargetId = board.targetLayers.vertex().selectTargetId;
+  expect(selectTargetId).toBeDefined();
+  await expect(selectTargetId!("v-1")).rejects.toThrow("blocked");
+});
+
+test("useBoardInteractions respects the targetKinds filter", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "buildRoad",
+      surface: "board-edge",
+      targets: { edgeId: ["e-1"] },
+      keys: ["edgeId"],
+    }),
+    createDescriptor({
+      interactionId: "moveRobber",
+      surface: "board-tile",
+      targets: { spaceId: ["space-7"] },
+      keys: ["spaceId"],
+    }),
+    createDescriptor({
+      interactionId: "nonBoardAction",
+      surface: "panel",
+      targets: {},
+      keys: [],
+    }),
+  ]);
+
+  const board = render(snapshot, () =>
+    useBoardInteractions({ targetKinds: ["edge"] }),
+  );
+
+  expect(board.interactions.map((d) => d.interactionId)).toEqual(["buildRoad"]);
+  expect(Array.from(board.eligible.space)).toEqual([]);
+});
+
+test("useBoardInteractions only exposes hand-card board targets after the card action is armed", async () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "playKnight",
+      surface: "hand",
+      commit: { mode: "autoWhenReady" },
+      targets: { cardId: ["dev-1"], spaceId: ["space-7"] },
+      keys: ["cardId", "spaceId"],
+    }),
+  ]);
+
+  const unarmed = render(snapshot, () => useBoardInteractions());
+  expect(unarmed.interactions).toEqual([]);
+  expect(Array.from(unarmed.eligible.space)).toEqual([]);
+
+  const recorder: RecordedSubmit[] = [];
+  const armed = render(
+    snapshot,
+    () => useBoardInteractions(),
+    recorder,
+    (store) => {
+      store.setInput("play.playKnight", "cardId", "dev-1");
+      store.arm("board:space", "play.playKnight");
+    },
+  );
+
+  expect(armed.interactions.map((d) => d.interactionId)).toEqual([
+    "playKnight",
+  ]);
+  expect(Array.from(armed.eligible.space)).toEqual(["space-7"]);
+
+  const fired = await armed.select.space("space-7");
+  expect(fired).toBe("play.playKnight");
+  expect(recorder).toEqual([
+    {
+      playerId: "player-1",
+      interactionId: "playKnight",
+      params: { cardId: "dev-1", spaceId: "space-7" },
+    },
+  ]);
+});
+
+test("useBoardInteractions armed follow-up beats unarmed ambient board action", async () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createDescriptor({
+      interactionId: "buildRoad",
+      surface: "board-edge",
+      targets: { edgeId: ["e-shared"] },
+      keys: ["edgeId"],
+    }),
+    createDescriptor({
+      interactionId: "playRoadBuilding",
+      interactionKey: "play.playRoadBuilding",
+      surface: "hand",
+      commit: { mode: "autoWhenReady" },
+      targets: { cardId: ["dev-1"], edgeId1: ["e-shared"] },
+      keys: ["cardId", "edgeId1"],
+    }),
+  ]);
+
+  const recorder: RecordedSubmit[] = [];
+  const board = render(
+    snapshot,
+    () => useBoardInteractions(),
+    recorder,
+    (store) => {
+      store.setInput("play.playRoadBuilding", "cardId", "dev-1");
+      store.arm("board:edge", "play.playRoadBuilding");
+    },
+  );
+
+  const fired = await board.select.edge("e-shared");
+  expect(fired).toBe("play.playRoadBuilding");
+  expect(recorder).toEqual([
+    {
+      playerId: "player-1",
+      interactionId: "playRoadBuilding",
+      params: { cardId: "dev-1", edgeId1: "e-shared" },
+    },
+  ]);
+});