@dreamboard-games/ui-sdk 0.0.42 → 0.0.45

package/src/primitives/interaction.tsx

@@ -7,23 +7,61 @@ import {
   type InputHTMLAttributes,
   type ReactNode,
 } from "react";
-import { useInteractionHandle } from "../hooks/useInteractionHandle.js";
-import { useInteractionUiStore } from "../context/InteractionDraftContext.js";
+import {
+  useInteractionHandle,
+  type InteractionHandle,
+  type InteractionParamsShape,
+} from "../hooks/useInteractionHandle.js";
+import {
+  useInteractionUiStore,
+  usePendingInteractionKey,
+} from "../context/InteractionDraftContext.js";
 import { usePluginState } from "../context/PluginStateContext.js";
 import type { InteractionInputKey, InteractionKey } from "../ui-contract.js";
-import type { InteractionDescriptor } from "../types/plugin-state.js";
+import type {
+  InteractionDescriptor,
+  InteractionInputDescriptor,
+  ZoneHandlesSnapshot,
+} from "../types/plugin-state.js";
 import {
+  hasInteractionFieldErrors,
   inputByKey,
   isManyTargetSelectable,
   toggleManyValue,
 } from "../utils/interaction-inputs.js";
+import {
+  applyInteractionDraftMutation,
+  getInteractionDraftReadiness,
+  markInteractionPending,
+  shouldRouteInteractionPending,
+} from "../utils/interaction-router.js";
 import { interactionLabel } from "../utils/interaction-labels.js";
 import {
   composeEventHandlers,
   renderPrimitive,
   type PrimitiveCommonProps,
 } from "./primitive-props.js";
-import { useZoneCardContext } from "./zone.js";
+import {
+  BoundInteractionForm,
+  castInteractionDraft,
+  castInteractionHandle,
+  type BoundInteractionFormProps,
+} from "./interaction-form-binding.js";
+import {
+  InteractionField as BaseInteractionField,
+  type InteractionFieldProps as BaseInteractionFieldProps,
+} from "../components/InteractionForm.js";
+import {
+  submitInteractionDraft,
+  submitInteractionParams,
+  type InteractionSubmitCallbacks,
+} from "./interaction-submit.js";
+import {
+  useDialogLifecycle,
+  type DialogLifecycleState,
+} from "./dialog-lifecycle.js";
+import { useGameActionError } from "./game.js";
+import { useOptionalZonePrimitiveContext, useZoneCardContext } from "./zone.js";
 
 interface InteractionContextValue {
   interaction: string;
@@ -123,6 +161,98 @@ export function InteractionRoot<Interaction extends string = InteractionKey>({
   );
 }
 
+export type InteractionDialogState = DialogLifecycleState;
+
+export interface InteractionDialogRenderState<
+  Interaction extends string = InteractionKey,
+> {
+  interaction: Interaction;
+  state: InteractionDialogState;
+  open: boolean;
+  minimized: boolean;
+  dismissed: boolean;
+  setOpen: (open: boolean) => void;
+  restore: () => void;
+  minimize: () => void;
+  dismiss: () => void;
+}
+
+export interface InteractionDialogProps<
+  Interaction extends string = InteractionKey,
+> {
+  defaultOpen?: boolean;
+  onStateChange?: (state: InteractionDialogState) => void;
+  children: (state: InteractionDialogRenderState<Interaction>) => ReactNode;
+}
+
+export function InteractionDialog<Interaction extends string = InteractionKey>({
+  defaultOpen = true,
+  onStateChange,
+  children,
+}: InteractionDialogProps<Interaction>) {
+  const { interaction } = useInteractionPrimitiveContext();
+  const lifecycle = useDialogLifecycle({ defaultOpen, onStateChange });
+  const renderState = useMemo<InteractionDialogRenderState<Interaction>>(
+    () => ({
+      interaction: interaction as Interaction,
+      ...lifecycle,
+    }),
+    [interaction, lifecycle],
+  );
+  return <>{children(renderState)}</>;
+}
+
+export interface InteractionSwitchRenderState<
+  Interaction extends string = InteractionKey,
+> {
+  interaction: Interaction;
+  descriptor: InteractionDescriptor<Interaction>;
+}
+
+export type InteractionRouteMap<Interaction extends string = InteractionKey> = {
+  [Key in Interaction]?: (
+    state: InteractionSwitchRenderState<Key>,
+  ) => ReactNode;
+};
+
+export interface InteractionSwitchProps<
+  Interaction extends string = InteractionKey,
+> {
+  interaction?: Interaction;
+  routes: InteractionRouteMap<Interaction>;
+  fallback?: ReactNode;
+}
+
+export function InteractionSwitch<Interaction extends string = InteractionKey>({
+  interaction,
+  routes,
+  fallback = null,
+}: InteractionSwitchProps<Interaction>) {
+  const pendingInteractionKey = usePendingInteractionKey();
+  const descriptors = usePluginState(
+    (state) => state.gameplay.availableInteractions,
+  );
+  const routedInteraction = interaction ?? pendingInteractionKey;
+  const descriptor = routedInteraction
+    ? descriptors.find(
+        (candidate) => candidate.interactionKey === routedInteraction,
+      )
+    : undefined;
+  if (!descriptor) return <>{fallback}</>;
+  const route =
+    routes[descriptor.interactionKey as keyof typeof routes] ?? null;
+  if (!route) return <>{fallback}</>;
+  const typedInteraction = descriptor.interactionKey as Interaction;
+  return (
+    <InteractionRoot interaction={typedInteraction}>
+      {route({
+        interaction: typedInteraction,
+        descriptor: descriptor as InteractionDescriptor<Interaction>,
+      })}
+    </InteractionRoot>
+  );
+}
+
 export type InteractionPartProps = PrimitiveCommonProps &
   HTMLAttributes<HTMLElement>;
 
@@ -215,20 +345,144 @@ export function InteractionTrigger({
   });
 }
 
+export interface InteractionStateSnapshot<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+  DefaultedKeys extends keyof Params & string = never,
+> {
+  interaction: string;
+  descriptor: InteractionDescriptor;
+  handle: InteractionHandle<Params, DefaultedKeys>;
+  draft: InteractionHandle<Params, DefaultedKeys>["draft"];
+  values: InteractionHandle<Params, DefaultedKeys>["values"];
+  status: InteractionHandle<Params, DefaultedKeys>["status"];
+  available: boolean;
+  isReady: boolean;
+  isArmed: boolean;
+  inputKeys: readonly string[];
+  missingInputs: readonly string[];
+  readyFrontier: readonly string[];
+  blockedInputs: readonly string[];
+  hasInputs: boolean;
+}
+
+export interface InteractionStateProps<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+  DefaultedKeys extends keyof Params & string = never,
+> {
+  unavailable: ReactNode;
+  children: (
+    state: InteractionStateSnapshot<Params, DefaultedKeys>,
+  ) => ReactNode;
+}
+
+export function InteractionState<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+  DefaultedKeys extends keyof Params & string = never,
+>({ children, unavailable }: InteractionStateProps<Params, DefaultedKeys>) {
+  const { interaction, descriptor, handle } = useInteractionPrimitiveContext();
+  const store = useInteractionUiStore();
+  if (!descriptor || !handle) {
+    return <>{unavailable}</>;
+  }
+  const typedHandle = castInteractionHandle<Params, DefaultedKeys>(handle);
+  const liveDraft = castInteractionDraft<Params, DefaultedKeys>(
+    store.getDraft(descriptor.interactionKey),
+  );
+  const inputKeys = descriptor.inputs.map((input) => input.key);
+  const readiness = getInteractionDraftReadiness(descriptor, liveDraft);
+  return (
+    <>
+      {children({
+        interaction,
+        descriptor,
+        handle: typedHandle,
+        draft: liveDraft,
+        values: typedHandle.values,
+        status: typedHandle.status,
+        available: typedHandle.available,
+        isReady: readiness.ready,
+        isArmed: typedHandle.isArmed,
+        inputKeys,
+        missingInputs: readiness.missingInputs,
+        readyFrontier: readiness.readyFrontier,
+        blockedInputs: readiness.blockedInputs,
+        hasInputs: inputKeys.length > 0,
+      })}
+    </>
+  );
+}
+
+export type InteractionFormPrimitiveProps<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+  DefaultedKeys extends keyof Params & string = never,
+> = BoundInteractionFormProps<Params, DefaultedKeys>;
+
+export function InteractionFormPrimitive<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+  DefaultedKeys extends keyof Params & string = never,
+>(props: InteractionFormPrimitiveProps<Params, DefaultedKeys>) {
+  const { descriptor, handle } = useInteractionPrimitiveContext();
+  if (!descriptor || !handle) return null;
+  return (
+    <BoundInteractionForm<Params, DefaultedKeys>
+      descriptor={descriptor}
+      handle={handle}
+      {...props}
+    />
+  );
+}
+
+export type InteractionFieldPrimitiveProps<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+  Input extends keyof Params & string = keyof Params & string,
+> = Omit<
+  BaseInteractionFieldProps<Params, Input>,
+  "descriptor" | "handle" | "inputKey"
+> & {
+  input: Input;
+};
+
+export function InteractionFieldPrimitive<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+  Input extends keyof Params & string = keyof Params & string,
+>({ input, ...props }: InteractionFieldPrimitiveProps<Params, Input>) {
+  const { descriptor, handle } = useInteractionPrimitiveContext();
+  if (!descriptor || !handle) return null;
+  return (
+    <BaseInteractionField<Params, Input>
+      descriptor={descriptor}
+      handle={castInteractionHandle<Params>(handle)}
+      inputKey={input}
+      {...props}
+    />
+  );
+}
+
 export type InteractionSubmitProps = PrimitiveCommonProps &
-  ButtonHTMLAttributes<HTMLButtonElement>;
+  ButtonHTMLAttributes<HTMLButtonElement> & {
+    params?:
+      | InteractionParamsShape
+      | (() => InteractionParamsShape | null | undefined);
+    onSubmitSuccess?: InteractionSubmitCallbacks["onSubmitSuccess"];
+    onSubmitError?: InteractionSubmitCallbacks["onSubmitError"];
+  };
 
 export function InteractionSubmit({
   disabled,
   onClick,
+  params,
+  onSubmitSuccess,
+  onSubmitError,
   ...props
 }: InteractionSubmitProps) {
   const { descriptor, handle } = useInteractionPrimitiveContext();
+  const gameActionError = useGameActionError();
   const isSubmitting = handle?.status === "submitting";
+  const hasExplicitParams = params !== undefined;
   const isDisabled =
     disabled === true ||
     !descriptor?.available ||
-    !handle?.isReady ||
+    (!hasExplicitParams && !handle?.isReady) ||
     isSubmitting;
   return renderPrimitive("button", {
     type: "button",
@@ -241,10 +495,24 @@ export function InteractionSubmit({
     "data-available": descriptor?.available ?? false,
     "data-disabled": isDisabled || undefined,
     "data-ready": handle?.isReady ?? false,
+    "data-has-inputs": descriptor ? descriptor.inputs.length > 0 : undefined,
+    "data-input-count": descriptor?.inputs.length,
     "data-submitting": isSubmitting || undefined,
     "data-state": handle?.status ?? "unavailable",
     onClick: composeEventHandlers(onClick, () => {
-      void handle?.submitDraft();
+      if (isDisabled || !handle) return;
+      const resolvedParams = typeof params === "function" ? params() : params;
+      if (resolvedParams === null || resolvedParams === undefined) {
+        void submitInteractionDraft(handle, {
+          onSubmitSuccess,
+          onSubmitError: onSubmitError ?? gameActionError ?? undefined,
+        });
+        return;
+      }
+      void submitInteractionParams(handle, resolvedParams, {
+        onSubmitSuccess,
+        onSubmitError: onSubmitError ?? gameActionError ?? undefined,
+      });
     }),
   });
 }
@@ -286,8 +554,7 @@ export type InteractionCardInputProps<
 > = PrimitiveCommonProps &
   ButtonHTMLAttributes<HTMLButtonElement> & {
     input: Input;
-    value?: string;
-    card?: string;
+    unsafeCardId?: string;
     selected?: boolean;
     onSelectedChange?: (selected: boolean) => void;
   };
@@ -296,8 +563,7 @@ export function InteractionCardInput<
   Input extends string = InteractionInputKey,
 >({
   input,
-  value,
-  card,
+  unsafeCardId,
   selected,
   onSelectedChange,
   onClick,
@@ -308,10 +574,15 @@ export function InteractionCardInput<
   const { descriptor, handle } = useInteractionPrimitiveContext();
   const store = useInteractionUiStore();
   const zoneCard = useZoneCardContext();
-  const cardId = value ?? card ?? zoneCard?.cardId;
+  const zoneContext = useOptionalZonePrimitiveContext();
+  const cardId = zoneCard?.cardId ?? unsafeCardId;
+  const validationZone = zoneCard?.zone ?? zoneContext?.zone;
+  const zoneSnapshot = usePluginState((state) =>
+    validationZone ? state.gameplay.zones[validationZone] : undefined,
+  );
   const cardDescriptor = usePluginState((state) => {
-    if (!cardId || !zoneCard) return undefined;
-    return state.gameplay.zones[zoneCard.zone]?.playableByCardId[cardId]?.find(
+    if (!cardId || !validationZone) return undefined;
+    return state.gameplay.zones[validationZone]?.playableByCardId[cardId]?.find(
       (candidate) =>
         candidate.interactionKey === descriptor?.interactionKey &&
         candidate.inputs.some((candidateInput) => candidateInput.key === input),
@@ -320,6 +591,23 @@ export function InteractionCardInput<
   const inputDescriptor = descriptor
     ? inputByKey(descriptor, input)
     : undefined;
+  const targetInvalidReason = cardTargetInvalidReason({
+    cardDescriptor,
+    cardId,
+    inputDescriptor,
+    unsafeCardId,
+    validationZone,
+    zoneCard,
+    zoneSnapshot,
+  });
+  const isTargetValid = targetInvalidReason === undefined;
+  throwCardInputDevMismatch({
+    cardId,
+    targetInvalidReason,
+    unsafeCardId,
+    validationZone,
+    zoneCard,
+  });
   const liveDraft = descriptor ? store.getDraft(descriptor.interactionKey) : {};
   const currentValue =
     liveDraft[input] ?? handle?.draft[input] ?? handle?.values[input];
@@ -332,22 +620,18 @@ export function InteractionCardInput<
         cardId !== undefined &&
         String(currentValue) === String(cardId);
   const isSelected = selected ?? selectedByDraft;
-  const eligibleTargets =
-    inputDescriptor?.domain.type === "target"
-      ? inputDescriptor.domain.eligibleTargets
-      : undefined;
-  const isCardInput =
-    inputDescriptor?.domain.type === "target" &&
-    inputDescriptor.domain.targetKind === "card";
-  const isEligible =
-    cardId !== undefined &&
-    isCardInput &&
-    (eligibleTargets === undefined || eligibleTargets.includes(cardId));
+  const isCardAvailable =
+    cardDescriptor?.available ??
+    (isTargetValid && (descriptor?.available ?? false));
+  const cardUnavailableReason =
+    cardDescriptor?.unavailableReason ??
+    (!descriptor?.available
+      ? (descriptor?.unavailableReason ?? "interaction-unavailable")
+      : undefined);
   const isSelectable =
     cardId !== undefined &&
     inputDescriptor !== undefined &&
     isManyTargetSelectable(inputDescriptor, currentValue, cardId);
-  const isCandidateAvailable = cardDescriptor?.available ?? true;
   const validation = handle?.validateDraft();
   const fieldErrors = validation?.fieldErrors[input] ?? [];
   const isInvalid = fieldErrors.length > 0;
@@ -355,7 +639,9 @@ export function InteractionCardInput<
     disabled === true ||
     !descriptor?.available ||
     !cardId ||
-    !isEligible ||
+    !isTargetValid ||
+    !isCardAvailable ||
+    !isSelectable ||
     !handle;
 
   return renderPrimitive("button", {
@@ -368,11 +654,14 @@ export function InteractionCardInput<
     "data-dreamboard-interaction-card-input": "",
     "data-input-name": input,
     "data-card-id": cardId,
-    "data-zone": zoneCard?.zone,
+    "data-zone": validationZone,
     "data-selected": isSelected || undefined,
-    "data-eligible": isEligible,
+    "data-eligible": isTargetValid && isCardAvailable,
+    "data-target-valid": isTargetValid,
+    "data-target-invalid-reason": targetInvalidReason,
     "data-selectable": isSelectable,
-    "data-card-available": isCandidateAvailable,
+    "data-card-available": isCardAvailable,
+    "data-card-unavailable-reason": cardUnavailableReason,
     "data-invalid": isInvalid || undefined,
     "data-disabled": isDisabled || undefined,
     "data-missing-resource": cardId ? undefined : true,
@@ -382,7 +671,35 @@ export function InteractionCardInput<
         selection?.mode === "many"
           ? toggleManyValue(currentValue, cardId, selection)
           : cardId;
-      handle.setInput(input, nextValue);
+      const nextDraft = applyInteractionDraftMutation(store, descriptor, [
+        { key: input, value: nextValue },
+      ]);
+      const readiness = getInteractionDraftReadiness(descriptor, nextDraft);
+      const hasMissingSurfaceTarget = readiness.readyFrontier.some((key) => {
+        const candidate = inputByKey(descriptor, key);
+        return (
+          candidate?.domain.type === "target" &&
+          candidate.domain.targetKind !== "card" &&
+          candidate.domain.selection?.mode !== "many"
+        );
+      });
+      const hasMissingFormInput = readiness.readyFrontier.some((key) => {
+        const candidate = inputByKey(descriptor, key);
+        return (
+          candidate !== undefined &&
+          (candidate.domain.type !== "target" ||
+            candidate.domain.selection?.mode === "many")
+        );
+      });
+      const hasFieldErrors = hasInteractionFieldErrors(readiness.fieldErrors);
+      if (shouldRouteInteractionPending(descriptor, readiness)) {
+        markInteractionPending(store, descriptor);
+        store.setPendingInteraction(
+          !hasMissingSurfaceTarget && (hasMissingFormInput || hasFieldErrors)
+            ? descriptor.interactionKey
+            : null,
+        );
+      }
       onSelectedChange?.(
         selection?.mode === "many"
           ? Array.isArray(nextValue) && nextValue.includes(cardId)
@@ -392,14 +709,117 @@ export function InteractionCardInput<
   });
 }
 
+type CardTargetInvalidReason =
+  | "missing-card"
+  | "wrong-zone"
+  | "not-in-zone"
+  | "not-top-card"
+  | "not-in-domain";
+
+function cardTargetInvalidReason({
+  cardDescriptor,
+  cardId,
+  inputDescriptor,
+  unsafeCardId,
+  validationZone,
+  zoneCard,
+  zoneSnapshot,
+}: {
+  cardDescriptor: InteractionDescriptor | undefined;
+  cardId: string | undefined;
+  inputDescriptor: InteractionInputDescriptor | undefined;
+  unsafeCardId: string | undefined;
+  validationZone: string | undefined;
+  zoneCard: ReturnType<typeof useZoneCardContext>;
+  zoneSnapshot: ZoneHandlesSnapshot | undefined;
+}): CardTargetInvalidReason | undefined {
+  if (!cardId) return "missing-card";
+  if (
+    inputDescriptor?.domain.type !== "target" ||
+    inputDescriptor.domain.targetKind !== "card"
+  ) {
+    return "not-in-domain";
+  }
+  if (zoneCard && unsafeCardId && unsafeCardId !== zoneCard.cardId) {
+    return "wrong-zone";
+  }
+  if (
+    validationZone &&
+    zoneSnapshot &&
+    !zoneSnapshot.cardIds.includes(cardId)
+  ) {
+    return "not-in-zone";
+  }
+  if (
+    validationZone &&
+    inputDescriptor.domain.zoneIds &&
+    !inputDescriptor.domain.zoneIds.includes(validationZone)
+  ) {
+    return "wrong-zone";
+  }
+  if (validationZone && !cardDescriptor) {
+    return zoneSnapshot?.cardIds[0] !== cardId
+      ? "not-top-card"
+      : "not-in-domain";
+  }
+  if (
+    !zoneCard &&
+    inputDescriptor.domain.eligibleTargets &&
+    !inputDescriptor.domain.eligibleTargets.includes(cardId)
+  ) {
+    return "not-in-domain";
+  }
+  return undefined;
+}
+
+function throwCardInputDevMismatch({
+  cardId,
+  targetInvalidReason,
+  unsafeCardId,
+  validationZone,
+  zoneCard,
+}: {
+  cardId: string | undefined;
+  targetInvalidReason: CardTargetInvalidReason | undefined;
+  unsafeCardId: string | undefined;
+  validationZone: string | undefined;
+  zoneCard: ReturnType<typeof useZoneCardContext>;
+}) {
+  if (!isDevelopmentRuntime() || !validationZone) return;
+  if (zoneCard && unsafeCardId && unsafeCardId !== zoneCard.cardId) {
+    throw new Error(
+      `Interaction.CardInput unsafeCardId '${unsafeCardId}' does not match surrounding Zone.Item card '${zoneCard.cardId}'.`,
+    );
+  }
+  if (targetInvalidReason === "not-in-zone" && cardId) {
+    throw new Error(
+      `Interaction.CardInput card '${cardId}' is not present in surrounding zone '${validationZone}'.`,
+    );
+  }
+}
+
+function isDevelopmentRuntime(): boolean {
+  const processLike = (
+    globalThis as {
+      process?: { env?: { NODE_ENV?: string } };
+    }
+  ).process;
+  return processLike?.env?.NODE_ENV !== "production";
+}
+
 export const Interaction = {
   Root: InteractionRoot,
+  State: InteractionState,
+  Switch: InteractionSwitch,
+  Dialog: InteractionDialog,
   Trigger: InteractionTrigger,
   Label: InteractionLabel,
   Description: InteractionDescription,
   UnavailableMessage: InteractionUnavailableMessage,
   ValidationMessage: InteractionValidationMessage,
   Input: InteractionInput,
+  Field: InteractionFieldPrimitive,
   CardInput: InteractionCardInput,
+  Form: InteractionFormPrimitive,
   Submit: InteractionSubmit,
 };

package/src/primitives/player-roster.tsx

@@ -19,6 +19,7 @@ import {
   renderPrimitive,
   type PrimitiveCommonProps,
 } from "./primitive-props.js";
+import type { HexColor } from "../types/hex-color.js";
 
 export interface PlayerRosterBadge {
   key: string;
@@ -30,7 +31,7 @@ export interface PlayerRosterBadge {
 export interface PlayerRosterEntry {
   playerId: PlayerId;
   name: string;
-  color?: string;
+  color?: HexColor;
   index: number;
   isActive: boolean;
   isCurrentPlayer: boolean;