@dreamboard-games/ui-sdk 0.0.41

package/src/components/surfaces/internal/DefaultInteractionButton.tsx

@@ -0,0 +1,219 @@
+import { useState, type CSSProperties, type ReactNode } from "react";
+import type { ButtonVariant } from "../../../theme/derive.js";
+import { useTheme } from "../../../theme/ThemeProvider.js";
+import type {
+  InteractionHandle,
+  InteractionParamsShape,
+} from "../../../hooks/useInteractionHandle.js";
+import type { InteractionDescriptor } from "../../../types/plugin-state.js";
+import {
+  InteractionForm,
+  hasDefaultInteractionFormFields,
+} from "../../InteractionForm.js";
+import { interactionLabel } from "../../../utils/interaction-labels.js";
+import { ThemedButton } from "../../ThemedButton.js";
+
+export interface SubmittedActionConfig {
+  label?: ReactNode;
+  icon?: ReactNode;
+  variant?: ButtonVariant;
+}
+
+/**
+ * Default button used by every surface that does not get an explicit
+ * renderer override. The button reads its visual style from the active
+ * {@link useTheme()} via {@link buttonStyle}; styling is no longer
+ * configurable per call site. Authors who need a different look should
+ * either:
+ *
+ * 1. Mount a different theme via `<ThemeProvider>`, or
+ * 2. Provide a per-interaction renderer override on the surrounding
+ *    surface and draw their own button.
+ *
+ * The mapping from `descriptor.emphasis` to a {@link ButtonVariant}:
+ *
+ * - `"primary"`     → `primary`
+ * - `"destructive"` → `danger`
+ * - `"secondary"` (or unset) → `secondary`
+ *
+ * Override the mapping per call site with the `variant` prop when the
+ * descriptor's emphasis hint is wrong (e.g. an unavailable confirm that
+ * should still look prominent).
+ */
+export interface DefaultInteractionButtonProps<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+> {
+  descriptor: InteractionDescriptor;
+  handle: InteractionHandle<Params>;
+  /** Override the variant inferred from `descriptor.emphasis`. */
+  variant?: ButtonVariant;
+  /** Content slot before the descriptor's icon and label. */
+  leading?: ReactNode;
+  /** Content slot after the descriptor's label. */
+  trailing?: ReactNode;
+  /**
+   * Prefer `descriptor.shortLabel` over `label`. Set by surfaces that
+   * group lots of interactions in a tight row.
+   */
+  compact?: boolean;
+  /**
+   * Button size token. Defaults to `md` (or `sm` when {@link compact}
+   * is set, preserving the historical sub-row geometry). Surfaces that
+   * resolve a salience tier — e.g. {@link PanelSurface} — pass
+   * `lg` for hero items so the visual weight matches the importance.
+   */
+  size?: "sm" | "md" | "lg";
+  /** Submit params forwarded to `handle.submit`. Defaults to `{}`. */
+  params?: Record<string, unknown>;
+  /** Copy and visual overrides once this interaction has been submitted. */
+  whenSubmitted?: SubmittedActionConfig;
+  /** Additional inline style merged after the resolved button style. */
+  style?: CSSProperties;
+  /** Start expanded when the descriptor needs form input. */
+  defaultFormOpen?: boolean;
+  /**
+   * Additional `data-*` attribute forwarded onto the `<button>` so
+   * surfaces can tag DOM nodes for tests / theming hooks (e.g.
+   * `data-panel-tier="hero"`).
+   */
+  "data-panel-tier"?: string;
+}
+
+/**
+ * @see DefaultInteractionButtonProps
+ */
+export function DefaultInteractionButton<
+  Params extends InteractionParamsShape = InteractionParamsShape,
+>({
+  descriptor,
+  handle,
+  variant: variantOverride,
+  leading,
+  trailing,
+  compact,
+  size,
+  params,
+  whenSubmitted,
+  style,
+  defaultFormOpen = false,
+  "data-panel-tier": panelTier,
+}: DefaultInteractionButtonProps<Params>) {
+  const theme = useTheme();
+  const [pending, setPending] = useState(false);
+  const [formOpen, setFormOpen] = useState(defaultFormOpen);
+  const submitted = handle.status === "submitted";
+  const fallbackLabel = interactionLabel(descriptor);
+  const variant: ButtonVariant = submitted
+    ? (whenSubmitted?.variant ?? "submitted")
+    : (variantOverride ?? "secondary");
+  const disabled =
+    submitted ||
+    !descriptor.available ||
+    pending ||
+    handle.status === "submitting";
+  const needsForm = hasDefaultInteractionFormFields(descriptor);
+  const label = submitted
+    ? (whenSubmitted?.label ?? fallbackLabel)
+    : fallbackLabel;
+  const tooltip = descriptor.available
+    ? undefined
+    : formatUnavailableReason(descriptor.unavailableReason);
+
+  // Resolve size with the historical default — `compact` keeps `sm`
+  // for grouped sub-rows so existing call sites that rely on the
+  // tighter geometry don't change. Otherwise honour the explicit
+  // `size` prop, falling back to `md`.
+  const resolvedSize: "sm" | "md" | "lg" = size ?? (compact ? "sm" : "md");
+
+  const button = (
+    <ThemedButton
+      type="button"
+      variant={variant}
+      size={resolvedSize}
+      pressed={pending || handle.status === "submitting"}
+      aria-label={typeof label === "string" ? label : fallbackLabel}
+      aria-expanded={needsForm ? formOpen : undefined}
+      aria-disabled={disabled || undefined}
+      data-interaction-id={descriptor.interactionId}
+      data-emphasis="secondary"
+      data-panel-tier={panelTier}
+      data-available={descriptor.available && !submitted ? "true" : "false"}
+      data-action-state={
+        submitted
+          ? "submitted"
+          : handle.status === "submitting"
+            ? "submitting"
+            : descriptor.available
+              ? "available"
+              : "unavailable"
+      }
+      title={tooltip}
+      disabled={disabled}
+      style={style}
+      onClick={async (event) => {
+        event.preventDefault();
+        if (disabled) return;
+        if (needsForm) {
+          setFormOpen((open) => !open);
+          return;
+        }
+        setPending(true);
+        try {
+          if (params !== undefined) {
+            await handle.submit(params as Params);
+          } else {
+            await handle.submitDraft();
+          }
+        } catch {
+          // Descriptor-level availability is authoritative; submission
+          // errors flow through the runtime's error channel. We swallow
+          // here so consumers without an error boundary don't see an
+          // unhandled rejection warning.
+        } finally {
+          setPending(false);
+        }
+      }}
+    >
+      {leading}
+      {submitted && whenSubmitted?.icon ? (
+        <span aria-hidden style={{ fontSize: "1.1em" }}>
+          {whenSubmitted.icon}
+        </span>
+      ) : null}
+      <span>{label}</span>
+      {trailing}
+    </ThemedButton>
+  );
+
+  if (!needsForm) return button;
+  return (
+    <span
+      data-default-interaction
+      style={{
+        display: "inline-flex",
+        flexDirection: "column",
+        alignItems: "stretch",
+        gap: theme.space[2],
+      }}
+    >
+      {button}
+      {formOpen ? (
+        <InteractionForm
+          descriptor={descriptor}
+          handle={handle}
+          onCancel={() => setFormOpen(false)}
+          onSubmitSuccess={() => setFormOpen(false)}
+        />
+      ) : null}
+    </span>
+  );
+}
+
+function formatUnavailableReason(
+  reason: string | undefined,
+): string | undefined {
+  if (reason === "INSUFFICIENT_RESOURCES") {
+    return "Insufficient resources";
+  }
+  return reason;
+}

package/src/components/surfaces/internal/useCardZoneInteractions.ts

@@ -0,0 +1,311 @@
+import { useCallback, useMemo, useState } 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 type {
+  InteractionDescriptor,
+  ZoneHandlesSnapshot,
+} from "../../../types/plugin-state.js";
+import {
+  hasInteractionFieldErrors,
+  inputByTarget,
+  interactionArmScope,
+  interactionInputKeys,
+  isInputValueReady,
+  toggleManyValue,
+  validateInteractionInputDomains,
+} from "../../../utils/interaction-inputs.js";
+import type {
+  InteractionActionState,
+  InteractionDisabledReason,
+} from "../../../utils/interaction-status.js";
+import type { ViewCard } from "@dreamboard/sdk-types";
+
+export interface CardZoneInteractionContext<I extends string = string> {
+  card: ViewCard;
+  interactions: ReadonlyArray<InteractionDescriptor<I>>;
+  play: ((params?: Record<string, unknown>) => Promise<void>) | null;
+  disabled: boolean;
+  disabledReason?: InteractionDisabledReason;
+  actionState: InteractionActionState;
+  selected: boolean;
+}
+
+export function useCardZoneInteractions<I extends string = string>(
+  zoneId: string,
+  _options: { surface: "hand" | "market" },
+) {
+  const runtime = useRuntimeContext();
+  const { controllingPlayerId } = usePluginSession();
+  const draftStore = useInteractionUiStore();
+  const draftSnapshot = useStore(draftStore, (state) => state.drafts);
+  const submittingSnapshot = useStore(draftStore, (state) => state.submitting);
+  const [followUp, setFollowUp] = useState<InteractionDescriptor<I> | null>(
+    null,
+  );
+  const zone = usePluginState((s) => s.gameplay.zones?.[zoneId]) as
+    | ZoneHandlesSnapshot<I>
+    | undefined;
+  const simultaneousPhase = usePluginState((s) => s.gameplay.simultaneousPhase);
+
+  const cards = useMemo<readonly ViewCard[]>(() => {
+    if (!zone) return [];
+    const list: ViewCard[] = [];
+    for (const cardId of zone.cardIds) {
+      const serialized = zone.cardsById[cardId];
+      if (!serialized) continue;
+      try {
+        list.push(JSON.parse(serialized) as ViewCard);
+      } catch {
+        // Skip malformed card snapshots defensively.
+      }
+    }
+    return list;
+  }, [zone]);
+
+  const submitInteractionDraft = useCallback(
+    async (
+      descriptor: InteractionDescriptor<I>,
+      params: Record<string, unknown>,
+    ) => {
+      if (!controllingPlayerId) return;
+      if (draftStore.isSubmitting(descriptor.interactionKey)) return;
+      draftStore.setSubmitting(descriptor.interactionKey, true);
+      try {
+        await runtime.submitInteraction(
+          controllingPlayerId,
+          descriptor.interactionId,
+          params,
+        );
+        draftStore.clearInput(descriptor.interactionKey);
+        const armScope = interactionArmScope(descriptor);
+        if (draftStore.getArmed(armScope) === descriptor.interactionKey) {
+          draftStore.arm(armScope, null);
+        }
+      } finally {
+        draftStore.setSubmitting(descriptor.interactionKey, false);
+      }
+    },
+    [controllingPlayerId, draftStore, runtime],
+  );
+
+  const playCardInteraction = useCallback(
+    async (
+      card: ViewCard,
+      descriptor: InteractionDescriptor<I>,
+      params?: Record<string, unknown>,
+    ) => {
+      if (!controllingPlayerId) return;
+      const cardInput = resolveCardInput(descriptor, card.id);
+      if (!cardInput) return;
+      const cardInputKey = cardInput.key;
+      const currentDraft = draftStore.getDraft(descriptor.interactionKey);
+      const nextCardValue =
+        cardInput.domain.type === "target" &&
+        cardInput.domain.selection?.mode === "many"
+          ? toggleManyValue(
+              currentDraft[cardInputKey],
+              card.id,
+              cardInput.domain.selection,
+            )
+          : card.id;
+      const nextDraft: Record<string, unknown> = {
+        ...currentDraft,
+        ...(params ?? {}),
+        [cardInputKey]: nextCardValue,
+      };
+      for (const [key, value] of Object.entries(params ?? {})) {
+        draftStore.setInput(descriptor.interactionKey, key, value);
+      }
+      draftStore.setInput(
+        descriptor.interactionKey,
+        cardInputKey,
+        nextCardValue,
+      );
+      if (
+        cardInput.domain.type === "target" &&
+        cardInput.domain.selection?.mode === "many"
+      ) {
+        if (
+          descriptor.commit.mode === "autoWhenReady" &&
+          isDraftReady(descriptor, nextDraft)
+        ) {
+          await submitInteractionDraft(descriptor, nextDraft);
+        }
+        return;
+      }
+      const remaining = descriptor.inputs.filter((input) => {
+        const value =
+          nextDraft[input.key] ??
+          ("defaultValue" in input ? input.defaultValue : undefined);
+        return input.key !== cardInputKey && value === undefined;
+      });
+      const needsBoardTarget = descriptor.inputs.some((input) => {
+        const value =
+          nextDraft[input.key] ??
+          ("defaultValue" in input ? input.defaultValue : undefined);
+        return (
+          input.key !== cardInputKey &&
+          input.domain.type === "target" &&
+          value === undefined
+        );
+      });
+      if (needsBoardTarget) {
+        setFollowUp(null);
+        draftStore.arm(
+          interactionArmScope(descriptor),
+          descriptor.interactionKey,
+        );
+        return;
+      }
+      if (remaining.length > 0) {
+        setFollowUp(descriptor);
+        return;
+      }
+      if (
+        !isDraftReady(descriptor, nextDraft) ||
+        descriptor.commit.mode !== "autoWhenReady"
+      ) {
+        setFollowUp(null);
+        draftStore.arm(
+          interactionArmScope(descriptor),
+          descriptor.interactionKey,
+        );
+        return;
+      }
+      await submitInteractionDraft(descriptor, nextDraft);
+    },
+    [controllingPlayerId, draftStore, submitInteractionDraft],
+  );
+
+  const contexts = useMemo<ReadonlyArray<CardZoneInteractionContext<I>>>(() => {
+    if (!zone) return [];
+    return cards.map((card) => {
+      const interactions = zone.playableByCardId[card.id] ?? [];
+      const submittedInteraction = interactions.find(
+        (d) =>
+          controllingPlayerId !== null &&
+          simultaneousPhase?.phaseName === d.phaseName &&
+          simultaneousPhase.interactionId === d.interactionId &&
+          simultaneousPhase.sealedPlayerIds.includes(controllingPlayerId),
+      );
+      const submittingInteraction = interactions.find((d) =>
+        draftStore.isSubmitting(d.interactionKey),
+      );
+      const selected = interactions.some((d) =>
+        isCardSelected(d, card.id, draftStore.getDraft(d.interactionKey)),
+      );
+      const blockedState: InteractionActionState | null = submittedInteraction
+        ? "submitted"
+        : submittingInteraction
+          ? "submitting"
+          : null;
+      const available = blockedState
+        ? []
+        : interactions.filter(
+            (d) =>
+              d.available !== false &&
+              isCardInteractionSelectable(
+                d,
+                card.id,
+                draftStore.getDraft(d.interactionKey),
+              ),
+          );
+      const first = available.length === 1 ? available[0] : undefined;
+      const limited =
+        !blockedState &&
+        interactions.some(
+          (d) =>
+            d.available !== false &&
+            !isCardInteractionSelectable(
+              d,
+              card.id,
+              draftStore.getDraft(d.interactionKey),
+            ),
+        );
+      const disabled = blockedState !== null || available.length === 0;
+      return {
+        card,
+        interactions,
+        play: first
+          ? (params?: Record<string, unknown>) =>
+              playCardInteraction(card, first, params)
+          : null,
+        disabled,
+        disabledReason:
+          blockedState ??
+          (limited ? "selection-limit" : disabled ? "unavailable" : undefined),
+        actionState: blockedState ?? (disabled ? "unavailable" : "available"),
+        selected,
+      };
+    });
+  }, [
+    cards,
+    controllingPlayerId,
+    draftSnapshot,
+    draftStore,
+    playCardInteraction,
+    simultaneousPhase,
+    submittingSnapshot,
+    zone,
+  ]);
+
+  return { cards, contexts, followUp, setFollowUp };
+}
+
+function isCardSelected(
+  descriptor: InteractionDescriptor,
+  cardId: string,
+  draft: Readonly<Record<string, unknown>>,
+): boolean {
+  const input = resolveCardInput(descriptor, cardId);
+  if (!input) return false;
+  const current = draft[input.key];
+  return Array.isArray(current)
+    ? current.map((item) => String(item)).includes(cardId)
+    : String(current) === cardId;
+}
+
+function isCardInteractionSelectable(
+  descriptor: InteractionDescriptor,
+  cardId: string,
+  draft: Readonly<Record<string, unknown>>,
+): boolean {
+  const input = resolveCardInput(descriptor, cardId);
+  if (!input || input.domain.type !== "target") return true;
+  const selection = input.domain.selection;
+  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(cardId)) 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;
+  });
+}
+
+function resolveCardInput(
+  descriptor: InteractionDescriptor,
+  cardId: string,
+): InteractionDescriptor["inputs"][number] | null {
+  const targetInput = inputByTarget(descriptor, "card", cardId);
+  if (targetInput) return targetInput;
+  if (interactionInputKeys(descriptor).includes("cardId")) {
+    return descriptor.inputs.find((input) => input.key === "cardId") ?? null;
+  }
+  return null;
+}

package/src/components/surfaces/types.ts

@@ -0,0 +1,100 @@
+import type { ReactNode } from "react";
+import type {
+  InteractionHandle,
+  InteractionParamsShape,
+} from "../../hooks/useInteractionHandle.js";
+import type { InteractionDescriptor } from "../../types/plugin-state.js";
+import type { SubmittedActionConfig } from "./internal/DefaultInteractionButton.js";
+
+export type InteractionParamsByKeyShape = Record<
+  string,
+  | InteractionParamsShape
+  | {
+      params: InteractionParamsShape;
+      defaulted?: string;
+    }
+>;
+
+export type InteractionParamsOf<
+  ParamsByKey extends Partial<InteractionParamsByKeyShape>,
+  Key extends string,
+> = Key extends keyof ParamsByKey
+  ? ParamsByKey[Key] extends {
+      params: infer Params extends InteractionParamsShape;
+    }
+    ? Params
+    : ParamsByKey[Key] extends InteractionParamsShape
+      ? ParamsByKey[Key]
+      : InteractionParamsShape
+  : InteractionParamsShape;
+
+export type InteractionDefaultedKeysOf<
+  ParamsByKey extends Partial<InteractionParamsByKeyShape>,
+  Key extends string,
+> = Key extends keyof ParamsByKey
+  ? ParamsByKey[Key] extends { defaulted?: infer Defaulted extends string }
+    ? Extract<Defaulted, keyof InteractionParamsOf<ParamsByKey, Key> & string>
+    : never
+  : never;
+
+/**
+ * Per-interaction renderer overrides for a surface. Partial: when omitted
+ * entirely, the surface uses its built-in default renderer for every
+ * interaction. When present, every key MUST be a valid member of `I` —
+ * typos are a compile-time error against the generated `*Interactions`
+ * id alias from `@dreamboard/ui-contract`.
+ *
+ * ```ts
+ * import type { PanelInteractions } from "@dreamboard/ui-contract";
+ *
+ * <PanelSurface<PanelInteractions> render={{ rollDice: ... }} />
+ * // ✗ <PanelSurface<PanelInteractions> render={{ rolldice: ... }} />
+ * //                                              ^^^^^^^^^ typo: not assignable
+ * ```
+ *
+ * If you want compile-time exhaustiveness (every interaction id in `I`
+ * must have an explicit renderer), use {@link ExhaustiveSurfaceRenderMap}
+ * instead.
+ */
+export interface DefaultInteractionRenderConfig {
+  whenSubmitted?: SubmittedActionConfig;
+}
+
+export type SurfaceRenderEntry<D, H> =
+  | ((descriptor: D, handle: H) => ReactNode)
+  | DefaultInteractionRenderConfig;
+
+export type SurfaceRenderMap<
+  I extends string,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+> = {
+  [K in I]?: SurfaceRenderEntry<
+    InteractionDescriptor<K>,
+    InteractionHandle<
+      InteractionParamsOf<ParamsByKey, K>,
+      InteractionDefaultedKeysOf<ParamsByKey, K>
+    >
+  >;
+};
+
+/**
+ * Exhaustive (required) variant of {@link SurfaceRenderMap}. Every key of
+ * `I` MUST have an explicit renderer — useful when authors want the
+ * compiler to enforce that no interaction id slips through without a
+ * deliberate visual treatment.
+ *
+ * ```ts
+ * import type { PanelInteractions } from "@dreamboard/ui-contract";
+ * import type { ExhaustiveSurfaceRenderMap } from "@dreamboard/ui-sdk";
+ *
+ * const panelRenderers: ExhaustiveSurfaceRenderMap<PanelInteractions> = {
+ *   rollDice: ...,
+ *   buildSettlement: ...,
+ *   // omitting any id here is a compile-time error
+ * };
+ * ```
+ */
+export type ExhaustiveSurfaceRenderMap<
+  I extends string,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+> = Required<SurfaceRenderMap<I, ParamsByKey>>;

package/src/context/ClientParamSchemaContext.tsx

@@ -0,0 +1,44 @@
+import { createContext, useContext } from "react";
+
+export interface ClientParamSchema {
+  safeParse: (value: unknown) =>
+    | { success: true; data: Record<string, unknown> }
+    | {
+        success: false;
+        error: {
+          issues: ReadonlyArray<{
+            path: readonly PropertyKey[];
+            message: string;
+          }>;
+        };
+      };
+}
+
+export type ClientParamSchemaMap = Readonly<
+  Record<string, Readonly<Record<string, ClientParamSchema>>>
+>;
+
+const ClientParamSchemaContext = createContext<ClientParamSchemaMap>({});
+
+export function ClientParamSchemaProvider({
+  schemas,
+  children,
+}: {
+  schemas?: ClientParamSchemaMap;
+  children: React.ReactNode;
+}) {
+  return (
+    <ClientParamSchemaContext.Provider value={schemas ?? {}}>
+      {children}
+    </ClientParamSchemaContext.Provider>
+  );
+}
+
+export function useClientParamSchema(
+  phaseName: string | null | undefined,
+  interactionId: string,
+): ClientParamSchema | undefined {
+  const schemas = useContext(ClientParamSchemaContext);
+  if (!phaseName) return undefined;
+  return schemas[phaseName]?.[interactionId];
+}