@dreamboard-games/ui-sdk 0.0.41

package/src/hooks/useBoardInteractions.ts

@@ -0,0 +1,434 @@
+import { useCallback, useMemo } from "react";
+import { useStore } from "zustand";
+import { useInteractionUiStore } from "../context/InteractionDraftContext.js";
+import { usePluginSession } from "../context/PluginSessionContext.js";
+import { usePluginState } from "../context/PluginStateContext.js";
+import { useRuntimeContext } from "../context/RuntimeContext.js";
+import { validationErrorFromUnknown } from "../errors/ValidationError.js";
+import type { InteractiveTargetLayer } from "../components/board/target-layer.js";
+import type { InteractionDescriptor } from "../types/plugin-state.js";
+import {
+  eligibleTargetsByBoardKind,
+  eligibleTargetsForInput,
+  hasBoardTargetInput,
+  hasCardTargetInput,
+  hasInteractionFieldErrors,
+  inputByTarget,
+  inputKeyForTarget,
+  isInputValueReady,
+  interactionArmScope,
+  interactionInputKeys,
+  toggleManyValue,
+  validateInteractionInputDomains,
+  type BoardTargetKind,
+} from "../utils/interaction-inputs.js";
+
+export type BoardEligibleTargets = Readonly<
+  Record<BoardTargetKind, ReadonlySet<string>>
+>;
+
+export interface BoardTargetLayerOptions {
+  enabled?: boolean;
+  extraInputs?:
+    | Record<string, unknown>
+    | ((targetId: string) => Record<string, unknown>);
+  onBeforeSelect?: () => void;
+  onError?: (error: unknown) => void;
+}
+
+export type BoardTargetLayerFactory = (
+  options?: BoardTargetLayerOptions,
+) => InteractiveTargetLayer;
+
+export interface BoardInteractionsOptions {
+  /**
+   * Target kinds the hook pulls interactions from. Defaults to every board
+   * target kind. Restrict when a specific screen should only react to a subset
+   * (e.g. a discard screen that only cares about tile clicks).
+   */
+  targetKinds?: readonly BoardTargetKind[];
+}
+
+export class BoardInteractionConflictError extends Error {
+  readonly name = "BoardInteractionConflictError";
+  readonly targetKind: BoardTargetKind;
+  readonly targetId: string;
+  readonly interactionKeys: readonly string[];
+
+  constructor({
+    targetKind,
+    targetId,
+    interactionKeys,
+  }: {
+    targetKind: BoardTargetKind;
+    targetId: string;
+    interactionKeys: readonly string[];
+  }) {
+    super(
+      `Ambiguous ${targetKind} target '${targetId}' matched interactions: ${interactionKeys.join(
+        ", ",
+      )}. Arm one interaction explicitly or route with a narrower board primitive.`,
+    );
+    this.targetKind = targetKind;
+    this.targetId = targetId;
+    this.interactionKeys = interactionKeys;
+  }
+}
+
+/**
+ * Opinionated board-level dispatch context. Collapses the repeated
+ * "collect every board handle, merge target domains across them,
+ * route each click into the right interaction" pattern that advanced
+ * board games (Catan-class) otherwise have to re-implement by hand.
+ */
+export interface BoardInteractionsContext<I extends string = string> {
+  /**
+   * All board-surface interactions projected onto the controlling seat
+   * — both available and unavailable. Rendered greyed-out states can
+   * key off this even when the interaction isn't dispatchable yet.
+   */
+  interactions: ReadonlyArray<InteractionDescriptor<I>>;
+  /**
+   * Per-target-kind eligibility sets merged across every currently-
+   * available board interaction. `eligible.vertex` answers "which
+   * vertex ids can be clicked right now?" without the caller manually
+   * unioning descriptor eligibility across handles or knowing the
+   * authored input key.
+   */
+  eligible: BoardEligibleTargets;
+  /**
+   * True when `targetId` is eligible for at least one available
+   * interaction. Pass `targetKind` to scope the check to a specific
+   * board target kind.
+   */
+  isEligible(targetId: string, targetKind?: BoardTargetKind): boolean;
+  /**
+   * Target-kind dispatch. Routes by board geometry (`edge`, `vertex`,
+   * `space`, `tile`) rather than authored input-key strings.
+   */
+  select: {
+    edge(
+      targetId: string,
+      extraInputs?: Record<string, unknown>,
+    ): Promise<string | null>;
+    vertex(
+      targetId: string,
+      extraInputs?: Record<string, unknown>,
+    ): Promise<string | null>;
+    space(
+      targetId: string,
+      extraInputs?: Record<string, unknown>,
+    ): Promise<string | null>;
+    tile(
+      targetId: string,
+      extraInputs?: Record<string, unknown>,
+    ): Promise<string | null>;
+  };
+  /**
+   * Reducer-aware target layers for board primitives. Pass these directly
+   * to grids so eligibility, dispatch, and submit error handling stay in
+   * one place instead of being re-wired per component.
+   */
+  targetLayers: {
+    edge: BoardTargetLayerFactory;
+    vertex: BoardTargetLayerFactory;
+    space: BoardTargetLayerFactory;
+    tile: BoardTargetLayerFactory;
+  };
+}
+
+/**
+ * Board-surface orchestration helper that removes the boilerplate of
+ * wiring many `useInteractionById(...)` calls, merging their
+ * eligibility sets, and dispatching clicks to the right handle.
+ *
+ * Use this alongside (or instead of) `<BoardSurface>` when a game
+ * keeps multiple board interactions live simultaneously and dispatch
+ * is target-driven rather than armed-then-clicked. The typical
+ * Catan-class shape:
+ *
+ * ```tsx
+ * const board = useBoardInteractions();
+ *
+ * return (
+ *   <HexGrid
+ *     interactiveVertices={board.targetLayers.vertex()}
+ *     interactiveEdges={board.targetLayers.edge()}
+ *     onTileClick={(id) =>
+ *       board.select.space(id, { stealFromPlayerId: null })
+ *     }
+ *   />
+ * );
+ * ```
+ *
+ * Eligibility and availability remain authoritative on reducer-projected
+ * descriptors. Armed follow-up descriptors beat ambient board descriptors.
+ * Multiple unarmed matches are ambiguous and throw
+ * {@link BoardInteractionConflictError}.
+ */
+export function useBoardInteractions<I extends string = string>(
+  options: BoardInteractionsOptions = {},
+): BoardInteractionsContext<I> {
+  const { targetKinds } = options;
+
+  const runtime = useRuntimeContext();
+  const { controllingPlayerId } = usePluginSession();
+  const store = useInteractionUiStore();
+  const subscribedArmedBySurface = useStore(store, (state) => state.arms);
+  const armedBySurface = store.getState().arms ?? subscribedArmedBySurface;
+  const descriptors = usePluginState(
+    (state) => state.gameplay.availableInteractions ?? [],
+  );
+
+  const targetKindSet = useMemo(
+    () => new Set<BoardTargetKind>(targetKinds),
+    [targetKinds],
+  );
+  const armedIds = useMemo(
+    () => new Set(Object.values(armedBySurface)),
+    [armedBySurface],
+  );
+
+  const interactions = useMemo<ReadonlyArray<InteractionDescriptor<I>>>(() => {
+    return descriptors.filter((descriptor) => {
+      if (armedIds.has(descriptor.interactionKey)) return true;
+      if (hasCardTargetInput(descriptor)) return false;
+      if (!hasBoardTargetInput(descriptor)) return false;
+      if (!targetKinds || targetKinds.length === 0) return true;
+      const byKind = eligibleTargetsByBoardKind(descriptor);
+      return (Object.keys(byKind) as BoardTargetKind[]).some((kind) =>
+        targetKindSet.has(kind),
+      );
+    }) as unknown as ReadonlyArray<InteractionDescriptor<I>>;
+  }, [armedIds, descriptors, targetKindSet, targetKinds]);
+
+  const eligible = useMemo<BoardEligibleTargets>(() => {
+    const acc: Record<BoardTargetKind, Set<string>> = {
+      edge: new Set<string>(),
+      vertex: new Set<string>(),
+      space: new Set<string>(),
+      tile: new Set<string>(),
+    };
+    for (const descriptor of interactions) {
+      if (!descriptor.available) continue;
+      const targetsByKind = eligibleTargetsByBoardKind(descriptor);
+      for (const [targetKind, ids] of Object.entries(targetsByKind) as Array<
+        [BoardTargetKind, readonly string[] | undefined]
+      >) {
+        if (!ids) continue;
+        const bucket = acc[targetKind];
+        for (const id of ids) bucket.add(id);
+      }
+    }
+    return acc;
+  }, [interactions]);
+
+  const isEligible = useCallback(
+    (targetId: string, targetKind?: BoardTargetKind) => {
+      if (targetKind !== undefined) {
+        return eligible[targetKind].has(targetId);
+      }
+      for (const bucket of Object.values(eligible)) {
+        if (bucket.has(targetId)) return true;
+      }
+      return false;
+    },
+    [eligible],
+  );
+
+  const selectByKind = useCallback(
+    async (
+      targetKind: BoardTargetKind,
+      targetId: string,
+      extraInputs?: Record<string, unknown>,
+    ): Promise<string | null> => {
+      if (!controllingPlayerId) return null;
+      const matches = interactions.flatMap((descriptor) => {
+        if (!descriptor.available) return [];
+        const inputKey = inputKeyForTarget(descriptor, targetKind, targetId);
+        if (!inputKey) return [];
+        const input = inputByTarget(descriptor, targetKind, targetId);
+        if (
+          input?.domain.type === "target" &&
+          !isTargetSelectable(
+            input,
+            store.getDraft(descriptor.interactionKey),
+            targetId,
+          )
+        ) {
+          return [];
+        }
+        const targets = eligibleTargetsForInput(descriptor, inputKey);
+        if (!targets || !targets.includes(targetId)) return [];
+        return [
+          {
+            descriptor,
+            inputKey,
+            armed: armedIds.has(descriptor.interactionKey),
+          },
+        ];
+      });
+      const selected = selectDispatchCandidate(matches, targetKind, targetId);
+      if (selected) {
+        const { descriptor, inputKey } = selected;
+        const input = inputByTarget(descriptor, targetKind, targetId);
+        const currentDraft = store.getDraft(descriptor.interactionKey);
+        const selection =
+          input?.domain.type === "target" ? input.domain.selection : undefined;
+        const nextTargetValue =
+          selection?.mode === "many"
+            ? toggleManyValue(currentDraft[inputKey], targetId, selection)
+            : targetId;
+        const params: Record<string, unknown> = {
+          ...currentDraft,
+          ...(extraInputs ?? {}),
+          [inputKey]: nextTargetValue,
+        };
+        for (const [key, value] of Object.entries(extraInputs ?? {})) {
+          store.setInput(descriptor.interactionKey, key, value);
+        }
+        store.setInput(descriptor.interactionKey, inputKey, nextTargetValue);
+        if (
+          descriptor.commit.mode !== "autoWhenReady" ||
+          (selection?.mode === "many" && !isDraftReady(descriptor, params))
+        ) {
+          store.arm(interactionArmScope(descriptor), descriptor.interactionKey);
+          return descriptor.interactionKey;
+        }
+        // Fill any remaining required inputs with `null` so the reducer
+        // bundle can decide whether to reject (missing) or accept
+        // (optional). This matches the Catan "spaceId + null stealee"
+        // pattern without forcing callers to memorise each interaction's
+        // full input shape.
+        for (const required of interactionInputKeys(descriptor)) {
+          if (!(required in params)) params[required] = null;
+        }
+        try {
+          await runtime.submitInteraction(
+            controllingPlayerId,
+            descriptor.interactionId,
+            params,
+          );
+          store.clearInput(descriptor.interactionKey);
+          if (
+            store.getArmed(interactionArmScope(descriptor)) ===
+            descriptor.interactionKey
+          ) {
+            store.arm(interactionArmScope(descriptor), null);
+          }
+          return descriptor.interactionKey;
+        } catch (error) {
+          throw validationErrorFromUnknown(error);
+        }
+      }
+      return null;
+    },
+    [armedIds, controllingPlayerId, interactions, runtime, store],
+  );
+
+  const select = useMemo(
+    () => ({
+      edge: (targetId: string, extraInputs?: Record<string, unknown>) =>
+        selectByKind("edge", targetId, extraInputs),
+      vertex: (targetId: string, extraInputs?: Record<string, unknown>) =>
+        selectByKind("vertex", targetId, extraInputs),
+      space: (targetId: string, extraInputs?: Record<string, unknown>) =>
+        selectByKind("space", targetId, extraInputs),
+      tile: (targetId: string, extraInputs?: Record<string, unknown>) =>
+        selectByKind("tile", targetId, extraInputs),
+    }),
+    [selectByKind],
+  );
+
+  const targetLayers = useMemo(() => {
+    const createLayer =
+      (targetKind: BoardTargetKind): BoardTargetLayerFactory =>
+      (layerOptions = {}) => {
+        const { enabled, extraInputs, onBeforeSelect, onError } = layerOptions;
+        const resolveExtraInputs = (targetId: string) =>
+          typeof extraInputs === "function"
+            ? extraInputs(targetId)
+            : extraInputs;
+        return {
+          enabled,
+          eligible: eligible[targetKind],
+          selectTargetId: async (targetId: string) => {
+            if (enabled === false) return;
+            onBeforeSelect?.();
+            try {
+              await select[targetKind](targetId, resolveExtraInputs(targetId));
+            } catch (error) {
+              onError?.(error);
+              if (!onError) throw error;
+            }
+          },
+        };
+      };
+    return {
+      edge: createLayer("edge"),
+      vertex: createLayer("vertex"),
+      space: createLayer("space"),
+      tile: createLayer("tile"),
+    };
+  }, [eligible, select]);
+
+  return useMemo(
+    () => ({ interactions, eligible, isEligible, select, targetLayers }),
+    [interactions, eligible, isEligible, select, targetLayers],
+  );
+}
+
+function isTargetSelectable(
+  input: NonNullable<ReturnType<typeof inputByTarget>>,
+  draft: Readonly<Record<string, unknown>>,
+  targetId: string,
+): boolean {
+  const selection =
+    input.domain.type === "target" ? input.domain.selection : undefined;
+  if (selection?.mode !== "many" || !selection.distinct) return true;
+  const current = draft[input.key];
+  if (!Array.isArray(current)) return true;
+  if (current.map((item) => String(item)).includes(targetId)) return true;
+  return selection.max === undefined || current.length < selection.max;
+}
+
+function isDraftReady(
+  descriptor: InteractionDescriptor,
+  draft: Readonly<Record<string, unknown>>,
+): boolean {
+  const fieldErrors = validateInteractionInputDomains(descriptor, draft);
+  if (hasInteractionFieldErrors(fieldErrors)) return false;
+  return interactionInputKeys(descriptor).every((key) => {
+    const input = descriptor.inputs.find((candidate) => candidate.key === key);
+    const value =
+      draft[key] ??
+      (input && "defaultValue" in input ? input.defaultValue : undefined);
+    return input ? isInputValueReady(input, value) : value !== undefined;
+  });
+}
+
+interface MatchingDescriptor<I extends string> {
+  descriptor: InteractionDescriptor<I>;
+  inputKey: string;
+  armed: boolean;
+}
+
+function selectDispatchCandidate<I extends string>(
+  matches: ReadonlyArray<MatchingDescriptor<I>>,
+  targetKind: BoardTargetKind,
+  targetId: string,
+): MatchingDescriptor<I> | null {
+  if (matches.length === 0) return null;
+  const armed = matches.filter((match) => match.armed);
+  const candidates = armed.length > 0 ? armed : matches;
+  if (candidates.length > 1) {
+    throw new BoardInteractionConflictError({
+      targetKind,
+      targetId,
+      interactionKeys: candidates.map(
+        (winner) => winner.descriptor.interactionKey,
+      ),
+    });
+  }
+  return candidates[0] ?? null;
+}