@dreamboard-games/ui-sdk 0.0.43 → 0.0.45

package/src/hooks/useBoardInteractions.ts

@@ -5,23 +5,29 @@ 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 {
+  InteractiveTargetLayer,
+  InteractiveTargetState,
+} from "../components/board/target-layer.js";
 import type { InteractionDescriptor } from "../types/plugin-state.js";
 import {
+  applyInteractionInputDefaults,
   eligibleTargetsByBoardKind,
   eligibleTargetsForInput,
   hasBoardTargetInput,
   hasCardTargetInput,
-  hasInteractionFieldErrors,
   inputByTarget,
   inputKeyForTarget,
-  isInputValueReady,
-  interactionArmScope,
-  interactionInputKeys,
-  toggleManyValue,
-  validateInteractionInputDomains,
   type BoardTargetKind,
 } from "../utils/interaction-inputs.js";
+import {
+  claimInteractionSubmit,
+  clearInteractionRoute,
+  getInteractionDraftReadiness,
+  markInteractionPending,
+  routeInteractionTarget,
+  shouldRouteInteractionPending,
+} from "../utils/interaction-router.js";
 
 export type BoardEligibleTargets = Readonly<
   Record<BoardTargetKind, ReadonlySet<string>>
@@ -29,6 +35,7 @@ export type BoardEligibleTargets = Readonly<
 
 export interface BoardTargetLayerOptions {
   enabled?: boolean;
+  interactionKeys?: readonly string[];
   extraInputs?:
     | Record<string, unknown>
     | ((targetId: string) => Record<string, unknown>);
@@ -40,6 +47,27 @@ 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
@@ -106,23 +134,24 @@ export interface BoardInteractionsContext<I extends string = string> {
    * 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<string | null>;
+    ): Promise<BoardSelectionResult<I>>;
     vertex(
       targetId: string,
       extraInputs?: Record<string, unknown>,
-    ): Promise<string | null>;
+    ): Promise<BoardSelectionResult<I>>;
     space(
       targetId: string,
       extraInputs?: Record<string, unknown>,
-    ): Promise<string | null>;
+    ): Promise<BoardSelectionResult<I>>;
     tile(
       targetId: string,
       extraInputs?: Record<string, unknown>,
-    ): Promise<string | null>;
+    ): Promise<BoardSelectionResult<I>>;
   };
   /**
    * Reducer-aware target layers for board primitives. Pass these directly
@@ -135,6 +164,18 @@ export interface BoardInteractionsContext<I extends string = string> {
     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>>;
 }
 
 /**
@@ -142,9 +183,9 @@ export interface BoardInteractionsContext<I extends string = string> {
  * 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
+ * Internal board primitive controller for games that keep multiple board
+ * interactions live simultaneously and dispatch by target geometry. The
+ * typical
  * Catan-class shape:
  *
  * ```tsx
@@ -154,15 +195,16 @@ export interface BoardInteractionsContext<I extends string = string> {
  *   <HexGrid
  *     interactiveVertices={board.targetLayers.vertex()}
  *     interactiveEdges={board.targetLayers.edge()}
- *     onTileClick={(id) =>
- *       board.select.space(id, { stealFromPlayerId: null })
- *     }
+ *     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 follow-up descriptors beat ambient board descriptors.
+ * descriptors. Armed routed descriptors beat ambient board descriptors.
  * Multiple unarmed matches are ambiguous and throw
  * {@link BoardInteractionConflictError}.
  */
@@ -175,7 +217,13 @@ export function useBoardInteractions<I extends string = string>(
   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 ?? [],
   );
@@ -190,16 +238,28 @@ export function useBoardInteractions<I extends string = string>(
   );
 
   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>>;
+    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>(() => {
@@ -211,7 +271,10 @@ export function useBoardInteractions<I extends string = string>(
     };
     for (const descriptor of interactions) {
       if (!descriptor.available) continue;
-      const targetsByKind = eligibleTargetsByBoardKind(descriptor);
+      const targetsByKind = eligibleTargetsByBoardKind(
+        descriptor,
+        drafts[descriptor.interactionKey] ?? {},
+      );
       for (const [targetKind, ids] of Object.entries(targetsByKind) as Array<
         [BoardTargetKind, readonly string[] | undefined]
       >) {
@@ -221,7 +284,7 @@ export function useBoardInteractions<I extends string = string>(
       }
     }
     return acc;
-  }, [interactions]);
+  }, [drafts, interactions]);
 
   const isEligible = useCallback(
     (targetId: string, targetKind?: BoardTargetKind) => {
@@ -236,18 +299,93 @@ export function useBoardInteractions<I extends string = string>(
     [eligible],
   );
 
-  const selectByKind = useCallback(
+  const clearPendingInteraction = useCallback(
+    (descriptor: InteractionDescriptor) => {
+      clearInteractionRoute(store, descriptor);
+    },
+    [store],
+  );
+
+  const resolveSelection = useCallback(
     async (
-      targetKind: BoardTargetKind,
+      descriptor: InteractionDescriptor<I>,
+      inputKey: string,
       targetId: string,
       extraInputs?: Record<string, unknown>,
-    ): Promise<string | null> => {
-      if (!controllingPlayerId) return null;
+    ): 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 (!descriptor.available) return [];
-        const inputKey = inputKeyForTarget(descriptor, targetKind, targetId);
+        const draft = store.getDraft(descriptor.interactionKey);
+        const inputKey = inputKeyForTarget(
+          descriptor,
+          targetKind,
+          targetId,
+          draft,
+        );
         if (!inputKey) return [];
-        const input = inputByTarget(descriptor, targetKind, targetId);
+        const input = inputByTarget(descriptor, targetKind, targetId, draft);
         if (
           input?.domain.type === "target" &&
           !isTargetSelectable(
@@ -258,7 +396,7 @@ export function useBoardInteractions<I extends string = string>(
         ) {
           return [];
         }
-        const targets = eligibleTargetsForInput(descriptor, inputKey);
+        const targets = eligibleTargetsForInput(descriptor, inputKey, draft);
         if (!targets || !targets.includes(targetId)) return [];
         return [
           {
@@ -268,62 +406,32 @@ export function useBoardInteractions<I extends string = string>(
           },
         ];
       });
+      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;
-        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 resolveSelection(descriptor, inputKey, targetId, extraInputs);
       }
-      return null;
+      return { status: "none" };
     },
-    [armedIds, controllingPlayerId, interactions, runtime, store],
+    [controllingPlayerId, resolveSelection, resolveTargetMatches],
   );
 
   const select = useMemo(
@@ -340,11 +448,55 @@ export function useBoardInteractions<I extends string = string>(
     [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,
+        unavailableReason: candidateUnavailableReason(selected, conflict),
+      };
+    },
+    [controllingPlayerId, pendingInteractionKey, resolveTargetMatches],
+  );
+
   const targetLayers = useMemo(() => {
     const createLayer =
       (targetKind: BoardTargetKind): BoardTargetLayerFactory =>
       (layerOptions = {}) => {
-        const { enabled, extraInputs, onBeforeSelect, onError } = layerOptions;
+        const {
+          enabled,
+          interactionKeys,
+          extraInputs,
+          onBeforeSelect,
+          onError,
+        } = layerOptions;
         const resolveExtraInputs = (targetId: string) =>
           typeof extraInputs === "function"
             ? extraInputs(targetId)
@@ -352,14 +504,39 @@ export function useBoardInteractions<I extends string = string>(
         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;
+            if (enabled === false) return { status: "none" };
             onBeforeSelect?.();
             try {
-              await select[targetKind](targetId, resolveExtraInputs(targetId));
+              return await selectByKind(
+                targetKind,
+                targetId,
+                resolveExtraInputs(targetId),
+                interactionKeys,
+              );
             } catch (error) {
               onError?.(error);
               if (!onError) throw error;
+              return { status: "none" };
             }
           },
         };
@@ -370,11 +547,57 @@ export function useBoardInteractions<I extends string = string>(
       space: createLayer("space"),
       tile: createLayer("tile"),
     };
-  }, [eligible, select]);
+  }, [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, select, targetLayers }),
-    [interactions, eligible, isEligible, select, targetLayers],
+    () => ({
+      interactions,
+      eligible,
+      isEligible,
+      pendingInteraction,
+      select,
+      targetLayers,
+      targetState,
+      selectTarget,
+    }),
+    [
+      interactions,
+      eligible,
+      isEligible,
+      pendingInteraction,
+      select,
+      targetLayers,
+      targetState,
+      selectTarget,
+    ],
   );
 }
 
@@ -392,19 +615,11 @@ function isTargetSelectable(
   return selection.max === undefined || current.length < selection.max;
 }
 
-function isDraftReady(
+function missingInputsForDraft(
   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;
-  });
+): string[] {
+  return [...getInteractionDraftReadiness(descriptor, draft).missingInputs];
 }
 
 interface MatchingDescriptor<I extends string> {
@@ -432,3 +647,13 @@ function selectDispatchCandidate<I extends string>(
   }
   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 (!match.descriptor.available) return "unavailable";
+  return undefined;
+}