@dreamboard-games/sdk 0.2.0

package/src/runtime-internal/hooks/useBoardInteractions.ts

@@ -0,0 +1,665 @@
+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,
+  InteractiveTargetState,
+} from "../components/board/target-layer.js";
+import type { InteractionDescriptor } from "../types/plugin-state.js";
+import {
+  applyInteractionInputDefaults,
+  eligibleTargetsByBoardKind,
+  eligibleTargetsForInput,
+  hasBoardTargetInput,
+  hasCardTargetInput,
+  inputByTarget,
+  inputKeyForTarget,
+  isTargetDomain,
+  type BoardTargetKind,
+} from "../utils/interaction-inputs.js";
+import {
+  claimInteractionSubmit,
+  clearInteractionRoute,
+  getInteractionDraftReadiness,
+  markInteractionPending,
+  routeInteractionTarget,
+  shouldRouteInteractionPending,
+} from "../utils/interaction-router.js";
+import { isInteractionAvailable } from "../utils/interaction-status.js";
+
+export type BoardEligibleTargets = Readonly<
+  Record<BoardTargetKind, ReadonlySet<string>>
+>;
+
+export interface BoardTargetLayerOptions {
+  enabled?: boolean;
+  interactionKeys?: readonly string[];
+  extraInputs?:
+    | Record<string, unknown>
+    | ((targetId: string) => Record<string, unknown>);
+  onBeforeSelect?: () => void;
+  onError?: (error: unknown) => void;
+}
+
+export type BoardTargetLayerFactory = (
+  options?: BoardTargetLayerOptions,
+) => InteractiveTargetLayer;
+
+export type BoardSelectionResult<I extends string = string> =
+  | { status: "none" }
+  | {
+      status: "pending";
+      interactionKey: I;
+      descriptor: InteractionDescriptor<I>;
+      missingInputs: readonly string[];
+    }
+  | {
+      status: "submitted";
+      interactionKey: I;
+      descriptor: InteractionDescriptor<I>;
+    };
+
+export interface BoardPendingInteraction<I extends string = string> {
+  interactionKey: I;
+  descriptor: InteractionDescriptor<I>;
+  missingInputs: readonly string[];
+  clear(): void;
+}
+
+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 `kind` to scope the check to a specific
+   * board target kind.
+   */
+  isEligible(targetId: string, kind?: BoardTargetKind): boolean;
+  /**
+   * Target-kind dispatch. Routes by board geometry (`edge`, `vertex`,
+   * `space`, `tile`) rather than authored input-key strings.
+   */
+  pendingInteraction: BoardPendingInteraction<I> | null;
+  select: {
+    edge(
+      targetId: string,
+      extraInputs?: Record<string, unknown>,
+    ): Promise<BoardSelectionResult<I>>;
+    vertex(
+      targetId: string,
+      extraInputs?: Record<string, unknown>,
+    ): Promise<BoardSelectionResult<I>>;
+    space(
+      targetId: string,
+      extraInputs?: Record<string, unknown>,
+    ): Promise<BoardSelectionResult<I>>;
+    tile(
+      targetId: string,
+      extraInputs?: Record<string, unknown>,
+    ): Promise<BoardSelectionResult<I>>;
+  };
+  /**
+   * 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;
+  };
+  targetState(
+    targetKind: BoardTargetKind,
+    targetId: string,
+    options?: Pick<BoardTargetLayerOptions, "enabled" | "interactionKeys">,
+  ): InteractiveTargetState;
+  selectTarget(
+    descriptor: InteractionDescriptor<I>,
+    targetKind: BoardTargetKind,
+    targetId: string,
+    inputKey: string,
+    extraInputs?: Record<string, unknown>,
+  ): Promise<BoardSelectionResult<I>>;
+}
+
+/**
+ * Board-surface orchestration helper that removes the boilerplate of
+ * wiring many `useInteractionById(...)` calls, merging their
+ * eligibility sets, and dispatching clicks to the right handle.
+ *
+ * Internal board primitive controller for games that keep multiple board
+ * interactions live simultaneously and dispatch by target geometry. 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)}
+ *   />
+ * );
+ * ```
+ *
+ * Mount generated interaction routes with `<Interaction.Switch routes={...}>`
+ * for interactions that need more input after a board target is selected.
+ *
+ * Eligibility and availability remain authoritative on reducer-projected
+ * descriptors. Armed routed 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 subscribedDrafts = useStore(store, (state) => state.drafts);
+  const pendingInteractionKey = useStore(
+    store,
+    (state) => state.pendingInteractionKey,
+  );
+  const armedBySurface = store.getState().arms ?? subscribedArmedBySurface;
+  const drafts = store.getState().drafts ?? subscribedDrafts;
+  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.flatMap(
+      (descriptor): Array<InteractionDescriptor<I>> => {
+        if (armedIds.has(descriptor.interactionKey)) {
+          return [
+            { ...descriptor, interactionKey: descriptor.interactionKey as I },
+          ];
+        }
+        if (hasCardTargetInput(descriptor)) return [];
+        if (!hasBoardTargetInput(descriptor)) return [];
+        const include =
+          !targetKinds || targetKinds.length === 0
+            ? true
+            : (
+                Object.keys(
+                  eligibleTargetsByBoardKind(descriptor),
+                ) as BoardTargetKind[]
+              ).some((kind) => targetKindSet.has(kind));
+        return include
+          ? [{ ...descriptor, interactionKey: descriptor.interactionKey as 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 (!isInteractionAvailable(descriptor)) continue;
+      const targetsByKind = eligibleTargetsByBoardKind(
+        descriptor,
+        drafts[descriptor.interactionKey] ?? {},
+      );
+      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;
+  }, [drafts, interactions]);
+
+  const isEligible = useCallback(
+    (targetId: string, kind?: BoardTargetKind) => {
+      if (kind !== undefined) {
+        return eligible[kind].has(targetId);
+      }
+      for (const bucket of Object.values(eligible)) {
+        if (bucket.has(targetId)) return true;
+      }
+      return false;
+    },
+    [eligible],
+  );
+
+  const clearPendingInteraction = useCallback(
+    (descriptor: InteractionDescriptor) => {
+      clearInteractionRoute(store, descriptor);
+    },
+    [store],
+  );
+
+  const resolveSelection = useCallback(
+    async (
+      descriptor: InteractionDescriptor<I>,
+      inputKey: string,
+      targetId: string,
+      extraInputs?: Record<string, unknown>,
+    ): Promise<BoardSelectionResult<I>> => {
+      if (!controllingPlayerId) return { status: "none" };
+      const { params, readiness } = routeInteractionTarget(store, descriptor, {
+        inputKey,
+        value: targetId,
+        extraInputs,
+      });
+      if (shouldRouteInteractionPending(descriptor, readiness)) {
+        markInteractionPending(store, descriptor);
+        return {
+          status: "pending",
+          interactionKey: descriptor.interactionKey as I,
+          descriptor,
+          missingInputs: readiness.missingInputs,
+        };
+      }
+
+      const submitParams = applyInteractionInputDefaults<
+        Record<string, unknown>
+      >(descriptor, params);
+      if (!claimInteractionSubmit(store, descriptor)) {
+        return {
+          status: "submitted",
+          interactionKey: descriptor.interactionKey as I,
+          descriptor,
+        };
+      }
+      try {
+        await runtime.submitInteraction(
+          controllingPlayerId,
+          descriptor.interactionId,
+          submitParams as Record<string, unknown>,
+        );
+        clearPendingInteraction(descriptor);
+        return {
+          status: "submitted",
+          interactionKey: descriptor.interactionKey as I,
+          descriptor,
+        };
+      } catch (error) {
+        throw validationErrorFromUnknown(error);
+      } finally {
+        store.setSubmitting(descriptor.interactionKey, false);
+      }
+    },
+    [clearPendingInteraction, controllingPlayerId, runtime, store],
+  );
+
+  const resolveTargetMatches = useCallback(
+    (
+      targetKind: BoardTargetKind,
+      targetId: string,
+      interactionKeys?: readonly string[],
+    ): Array<MatchingDescriptor<I>> => {
+      const allowedInteractionKeys = interactionKeys
+        ? new Set(interactionKeys)
+        : null;
+      const matches = interactions.flatMap((descriptor) => {
+        if (
+          allowedInteractionKeys &&
+          !allowedInteractionKeys.has(descriptor.interactionKey)
+        ) {
+          return [];
+        }
+        if (!isInteractionAvailable(descriptor)) return [];
+        const draft = store.getDraft(descriptor.interactionKey);
+        const inputKey = inputKeyForTarget(
+          descriptor,
+          targetKind,
+          targetId,
+          draft,
+        );
+        if (!inputKey) return [];
+        const input = inputByTarget(descriptor, targetKind, targetId, draft);
+        if (
+          input &&
+          !isTargetSelectable(
+            input,
+            store.getDraft(descriptor.interactionKey),
+            targetId,
+          )
+        ) {
+          return [];
+        }
+        const targets = eligibleTargetsForInput(descriptor, inputKey, draft);
+        if (!targets || !targets.includes(targetId)) return [];
+        return [
+          {
+            descriptor,
+            inputKey,
+            armed: armedIds.has(descriptor.interactionKey),
+          },
+        ];
+      });
+      return matches;
+    },
+    [armedIds, interactions, store],
+  );
+
+  const selectByKind = useCallback(
+    async (
+      targetKind: BoardTargetKind,
+      targetId: string,
+      extraInputs?: Record<string, unknown>,
+      interactionKeys?: readonly string[],
+    ): Promise<BoardSelectionResult<I>> => {
+      if (!controllingPlayerId) return { status: "none" };
+      const matches = resolveTargetMatches(
+        targetKind,
+        targetId,
+        interactionKeys,
+      );
+      const selected = selectDispatchCandidate(matches, targetKind, targetId);
+      if (selected) {
+        const { descriptor, inputKey } = selected;
+        return resolveSelection(descriptor, inputKey, targetId, extraInputs);
+      }
+      return { status: "none" };
+    },
+    [controllingPlayerId, resolveSelection, resolveTargetMatches],
+  );
+
+  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 targetState = useCallback(
+    (
+      targetKind: BoardTargetKind,
+      targetId: string,
+      options: Pick<
+        BoardTargetLayerOptions,
+        "enabled" | "interactionKeys"
+      > = {},
+    ): InteractiveTargetState => {
+      const enabled = options.enabled !== false;
+      const matches = enabled
+        ? resolveTargetMatches(targetKind, targetId, options.interactionKeys)
+        : [];
+      const armed = matches.filter((match) => match.armed);
+      const candidates = armed.length > 0 ? armed : matches;
+      const selected = candidates[0] ?? null;
+      const conflict = candidates.length > 1;
+      const pending = selected
+        ? pendingInteractionKey === selected.descriptor.interactionKey
+        : false;
+      const eligible = enabled && !!selected && !conflict;
+      return {
+        kind: targetKind,
+        id: targetId,
+        eligible,
+        selectable: eligible && !!controllingPlayerId,
+        hovered: false,
+        interactionKey: selected?.descriptor.interactionKey,
+        interactionId: selected?.descriptor.interactionId,
+        inputKey: selected?.inputKey,
+        pending,
+        conflict,
+        conflictInteractionKeys: conflict
+          ? candidates.map((candidate) => candidate.descriptor.interactionKey)
+          : undefined,
+        unavailableReason: candidateUnavailableReason(selected, conflict),
+      };
+    },
+    [controllingPlayerId, pendingInteractionKey, resolveTargetMatches],
+  );
+
+  const targetLayers = useMemo(() => {
+    const createLayer =
+      (targetKind: BoardTargetKind): BoardTargetLayerFactory =>
+      (layerOptions = {}) => {
+        const {
+          enabled,
+          interactionKeys,
+          extraInputs,
+          onBeforeSelect,
+          onError,
+        } = layerOptions;
+        const resolveExtraInputs = (targetId: string) =>
+          typeof extraInputs === "function"
+            ? extraInputs(targetId)
+            : extraInputs;
+        return {
+          enabled,
+          eligible: eligible[targetKind],
+          targetState: (targetId: string) => ({
+            ...targetState(targetKind, targetId, { enabled, interactionKeys }),
+            select: async () => {
+              if (enabled === false) return { status: "none" };
+              onBeforeSelect?.();
+              try {
+                return await selectByKind(
+                  targetKind,
+                  targetId,
+                  resolveExtraInputs(targetId),
+                  interactionKeys,
+                );
+              } catch (error) {
+                onError?.(error);
+                if (!onError) throw error;
+                return { status: "none" };
+              }
+            },
+          }),
+          selectTargetId: async (targetId: string) => {
+            if (enabled === false) return { status: "none" };
+            onBeforeSelect?.();
+            try {
+              return await selectByKind(
+                targetKind,
+                targetId,
+                resolveExtraInputs(targetId),
+                interactionKeys,
+              );
+            } catch (error) {
+              onError?.(error);
+              if (!onError) throw error;
+              return { status: "none" };
+            }
+          },
+        };
+      };
+    return {
+      edge: createLayer("edge"),
+      vertex: createLayer("vertex"),
+      space: createLayer("space"),
+      tile: createLayer("tile"),
+    };
+  }, [eligible, selectByKind, targetState]);
+
+  const pendingInteraction = useMemo<BoardPendingInteraction<I> | null>(() => {
+    if (!pendingInteractionKey) return null;
+    const descriptor = interactions.find(
+      (candidate) => candidate.interactionKey === pendingInteractionKey,
+    );
+    if (!descriptor) return null;
+    return {
+      interactionKey: descriptor.interactionKey as I,
+      descriptor,
+      missingInputs: missingInputsForDraft(
+        descriptor,
+        drafts[descriptor.interactionKey] ?? {},
+      ),
+      clear: () => clearPendingInteraction(descriptor),
+    };
+  }, [clearPendingInteraction, drafts, interactions, pendingInteractionKey]);
+
+  const selectTarget = useCallback(
+    (
+      descriptor: InteractionDescriptor<I>,
+      _targetKind: BoardTargetKind,
+      targetId: string,
+      inputKey: string,
+      extraInputs?: Record<string, unknown>,
+    ) => resolveSelection(descriptor, inputKey, targetId, extraInputs),
+    [resolveSelection],
+  );
+
+  return useMemo(
+    () => ({
+      interactions,
+      eligible,
+      isEligible,
+      pendingInteraction,
+      select,
+      targetLayers,
+      targetState,
+      selectTarget,
+    }),
+    [
+      interactions,
+      eligible,
+      isEligible,
+      pendingInteraction,
+      select,
+      targetLayers,
+      targetState,
+      selectTarget,
+    ],
+  );
+}
+
+function isTargetSelectable(
+  input: NonNullable<ReturnType<typeof inputByTarget>>,
+  draft: Readonly<Record<string, unknown>>,
+  targetId: string,
+): boolean {
+  const selection = isTargetDomain(input.domain)
+    ? 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 missingInputsForDraft(
+  descriptor: InteractionDescriptor,
+  draft: Readonly<Record<string, unknown>>,
+): string[] {
+  return [...getInteractionDraftReadiness(descriptor, draft).missingInputs];
+}
+
+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;
+}
+
+function candidateUnavailableReason<I extends string>(
+  match: MatchingDescriptor<I> | null,
+  conflict: boolean,
+): string | undefined {
+  if (conflict) return "conflict";
+  if (!match) return "unavailable";
+  if (!isInteractionAvailable(match.descriptor)) return "unavailable";
+  return undefined;
+}