@dreamboard-games/ui-sdk 0.0.41

package/src/ui-contract.ts

@@ -0,0 +1,168 @@
+import type { ReactElement } from "react";
+import {
+  PromptDialogHost as PromptDialogHostComponent,
+  type PromptDialogHostProps,
+} from "./components/PromptDialogHost.js";
+import {
+  Board as BoardPrimitive,
+  Interaction as InteractionPrimitive,
+  Phase as PhasePrimitive,
+  PlayerRoster as PlayerRosterPrimitive,
+  Prompt as PromptPrimitive,
+  PromptInbox as PromptInboxPrimitive,
+  Zone as ZonePrimitive,
+  type BoardTargetProps,
+  type InteractionCardInputProps,
+  type InteractionRootProps,
+  type PhaseSwitchProps,
+  type PlayerRosterComponents,
+  type PromptOptionProps,
+  type PromptRootProps,
+  type ZoneRootProps,
+} from "./primitives/index.js";
+
+/**
+ * Workspace-aware UI typing extension point.
+ *
+ * Generated workspaces will augment this interface with their concrete UI
+ * contract. The unregistered SDK keeps all public keys string-compatible so
+ * package-local tests and generic consumers can still import ui-sdk directly.
+ */
+export interface DreamboardUIRegister {}
+
+export type UIContractBucket = Record<string, unknown>;
+
+export interface UIContract {
+  interactions?: UIContractBucket;
+  inputs?: UIContractBucket;
+  prompts?: UIContractBucket;
+  promptOptions?: UIContractBucket;
+  zones?: UIContractBucket;
+  cards?: UIContractBucket;
+  phases?: UIContractBucket;
+  boardTargets?: UIContractBucket;
+}
+
+type RegisteredUIContract = DreamboardUIRegister extends {
+  ui: infer Registered extends UIContract;
+}
+  ? Registered
+  : UIContract;
+
+type BucketOf<Contract extends UIContract, Key extends keyof UIContract> =
+  NonNullable<Contract[Key]> extends UIContractBucket
+    ? NonNullable<Contract[Key]>
+    : UIContractBucket;
+
+type StringKeysOrFallback<Bucket extends UIContractBucket> =
+  string extends Extract<keyof Bucket, string>
+    ? string
+    : Extract<keyof Bucket, string>;
+
+export type RegisteredUI = RegisteredUIContract;
+
+export type InteractionKey<Contract extends UIContract = RegisteredUI> =
+  StringKeysOrFallback<BucketOf<Contract, "interactions">>;
+
+export type InteractionInputKey<Contract extends UIContract = RegisteredUI> =
+  StringKeysOrFallback<BucketOf<Contract, "inputs">>;
+
+export type PromptKey<Contract extends UIContract = RegisteredUI> =
+  StringKeysOrFallback<BucketOf<Contract, "prompts">>;
+
+export type PromptOptionKey<Contract extends UIContract = RegisteredUI> =
+  StringKeysOrFallback<BucketOf<Contract, "promptOptions">>;
+
+export type ZoneKey<Contract extends UIContract = RegisteredUI> =
+  StringKeysOrFallback<BucketOf<Contract, "zones">>;
+
+export type CardKey<Contract extends UIContract = RegisteredUI> =
+  StringKeysOrFallback<BucketOf<Contract, "cards">>;
+
+export type PhaseKey<Contract extends UIContract = RegisteredUI> =
+  StringKeysOrFallback<BucketOf<Contract, "phases">>;
+
+export type BoardTargetKey<Contract extends UIContract = RegisteredUI> =
+  StringKeysOrFallback<BucketOf<Contract, "boardTargets">>;
+
+export type TypedInteraction<Contract extends UIContract> = Omit<
+  typeof InteractionPrimitive,
+  "Root" | "CardInput"
+> & {
+  Root<Interaction extends InteractionKey<Contract>>(
+    props: InteractionRootProps<Interaction>,
+  ): ReactElement | null;
+  CardInput<Input extends InteractionInputKey<Contract>>(
+    props: Omit<InteractionCardInputProps, "input"> & { input: Input },
+  ): ReactElement;
+};
+
+export type TypedPrompt<Contract extends UIContract> = Omit<
+  typeof PromptPrimitive,
+  "Root" | "Option"
+> & {
+  Root<Prompt extends PromptKey<Contract>>(
+    props: PromptRootProps<Prompt>,
+  ): ReactElement | null;
+  Option<Option extends PromptOptionKey<Contract>>(
+    props: Omit<PromptOptionProps, "value"> & { value: Option },
+  ): ReactElement;
+};
+
+export type TypedPromptInbox = typeof PromptInboxPrimitive;
+export type TypedPlayerRoster = PlayerRosterComponents;
+
+export type TypedPhase<Contract extends UIContract> = Omit<
+  typeof PhasePrimitive,
+  "Switch"
+> & {
+  Switch(props: PhaseSwitchProps<PhaseKey<Contract>>): ReactElement | null;
+};
+
+export type TypedZone<Contract extends UIContract> = Omit<
+  typeof ZonePrimitive,
+  "Root"
+> & {
+  Root<Zone extends ZoneKey<Contract>>(
+    props: Omit<ZoneRootProps, "zone"> & { zone: Zone },
+  ): ReactElement;
+};
+
+export type TypedBoard<Contract extends UIContract> = Omit<
+  typeof BoardPrimitive,
+  "Target"
+> & {
+  Target<Target extends BoardTargetKey<Contract>>(
+    props: Omit<BoardTargetProps, "value"> & { value: Target },
+  ): ReactElement;
+};
+
+export interface DreamboardUI<Contract extends UIContract = RegisteredUI> {
+  readonly contract: Contract;
+  readonly Interaction: TypedInteraction<Contract>;
+  readonly Prompt: TypedPrompt<Contract>;
+  readonly PromptInbox: TypedPromptInbox;
+  readonly PlayerRoster: TypedPlayerRoster;
+  readonly PromptDialogHost: (
+    props: PromptDialogHostProps,
+  ) => ReactElement | null;
+  readonly Phase: TypedPhase<Contract>;
+  readonly Zone: TypedZone<Contract>;
+  readonly Board: TypedBoard<Contract>;
+}
+
+export function createDreamboardUI<const Contract extends UIContract>(
+  contract: Contract,
+): DreamboardUI<Contract> {
+  return {
+    contract,
+    Interaction: InteractionPrimitive,
+    Prompt: PromptPrimitive,
+    PromptInbox: PromptInboxPrimitive,
+    PlayerRoster: PlayerRosterPrimitive,
+    PromptDialogHost: PromptDialogHostComponent,
+    Phase: PhasePrimitive,
+    Zone: ZonePrimitive,
+    Board: BoardPrimitive,
+  } as DreamboardUI<Contract>;
+}

package/src/utils/interaction-inputs.test.ts

@@ -0,0 +1,109 @@
+import { expect, test } from "bun:test";
+import type { InteractionDescriptor } from "../types/plugin-state.js";
+import {
+  hasInteractionFieldErrors,
+  validateInteractionInputDomains,
+} from "./interaction-inputs.js";
+
+function descriptor(
+  inputs: InteractionDescriptor["inputs"],
+): InteractionDescriptor {
+  return {
+    phaseName: "play",
+    interactionKey: "play.configure",
+    interactionId: "configure",
+    surface: "panel",
+    kind: "action",
+    label: "Configure",
+    inputs,
+    commit: { mode: "manual" },
+    available: true,
+  };
+}
+
+test("choiceList domains validate minimum and maximum selection counts", () => {
+  const interaction = descriptor([
+    {
+      key: "players",
+      kind: "form",
+      domain: {
+        type: "choiceList",
+        min: 2,
+        max: 3,
+        choices: [
+          { value: "p1", label: "Alice" },
+          { value: "p2", label: "Bob" },
+          { value: "p3", label: "Cara" },
+          { value: "p4", label: "Dan" },
+        ],
+      },
+    },
+  ]);
+
+  expect(
+    validateInteractionInputDomains(interaction, { players: ["p1"] }),
+  ).toEqual({
+    players: ["Choose at least 2 options."],
+  });
+  expect(
+    validateInteractionInputDomains(interaction, {
+      players: ["p1", "p2", "p3", "p4"],
+    }),
+  ).toEqual({
+    players: ["Choose at most 3 options."],
+  });
+  expect(
+    hasInteractionFieldErrors(
+      validateInteractionInputDomains(interaction, {
+        players: ["p1", "p2"],
+      }),
+    ),
+  ).toBe(false);
+});
+
+test("many target domains validate count, distinctness, and eligibility", () => {
+  const interaction = descriptor([
+    {
+      key: "cardIds",
+      kind: "card",
+      domain: {
+        type: "target",
+        targetKind: "card",
+        eligibleTargets: ["card-1", "card-2", "card-3"],
+        selection: {
+          mode: "many",
+          min: 2,
+          max: 3,
+          distinct: true,
+        },
+      },
+    },
+  ]);
+
+  expect(
+    validateInteractionInputDomains(interaction, { cardIds: ["card-1"] }),
+  ).toEqual({
+    cardIds: ["Choose at least 2 values."],
+  });
+  expect(
+    validateInteractionInputDomains(interaction, {
+      cardIds: ["card-1", "card-1"],
+    }),
+  ).toEqual({
+    cardIds: ["Choose each value only once."],
+  });
+  expect(
+    validateInteractionInputDomains(interaction, {
+      cardIds: ["card-1", "card-4"],
+    }),
+  ).toEqual({
+    cardIds: ["Selected target is not eligible."],
+  });
+  expect(
+    hasInteractionFieldErrors(
+      validateInteractionInputDomains(interaction, {
+        cardIds: ["card-1", "card-2", "card-3"],
+      }),
+    ),
+  ).toBe(false);
+});

package/src/utils/interaction-inputs.ts

@@ -0,0 +1,331 @@
+import type {
+  InteractionDescriptor,
+  InteractionInputDescriptor,
+  InputSelection,
+} from "../types/plugin-state.js";
+
+export type BoardTargetKind = "edge" | "vertex" | "space" | "tile";
+
+export function interactionInputKeys(
+  descriptor: Pick<InteractionDescriptor, "inputs">,
+): string[] {
+  return descriptor.inputs.map((input) => input.key);
+}
+
+export function applyInteractionInputDefaults<
+  Params extends Record<string, unknown>,
+>(
+  descriptor: Pick<InteractionDescriptor, "inputs">,
+  params: Readonly<Partial<Params>>,
+): Partial<Params> {
+  const next: Record<string, unknown> = { ...params };
+  for (const input of descriptor.inputs) {
+    if (next[input.key] !== undefined) continue;
+    if (!("defaultValue" in input)) continue;
+    next[input.key] = input.defaultValue;
+  }
+  return next as Partial<Params>;
+}
+
+export function validateInteractionInputDomains(
+  descriptor: Pick<InteractionDescriptor, "inputs">,
+  params: Readonly<Record<string, unknown>>,
+): Partial<Record<string, readonly string[]>> {
+  const fieldErrors: Record<string, string[]> = {};
+
+  for (const input of descriptor.inputs) {
+    const value = params[input.key];
+    if (value === undefined || value === null) continue;
+
+    const selectionErrors = validateInputSelection(input, value);
+    for (const error of selectionErrors) {
+      pushFieldError(fieldErrors, input.key, error);
+    }
+
+    if (input.domain.type === "choiceList") {
+      if (!Array.isArray(value)) {
+        pushFieldError(fieldErrors, input.key, "Expected a list of choices.");
+        continue;
+      }
+
+      const min = input.domain.min ?? 0;
+      const max =
+        input.domain.max ??
+        input.domain.choices?.length ??
+        Number.POSITIVE_INFINITY;
+      if (value.length < min) {
+        pushFieldError(
+          fieldErrors,
+          input.key,
+          `Choose at least ${min} ${pluralize("option", min)}.`,
+        );
+      }
+      if (value.length > max) {
+        pushFieldError(
+          fieldErrors,
+          input.key,
+          `Choose at most ${max} ${pluralize("option", max)}.`,
+        );
+      }
+    }
+
+    if (input.domain.type === "target") {
+      const values = valuesForSelection(input.domain.selection, value);
+      const eligible = input.domain.eligibleTargets;
+      if (eligible) {
+        for (const item of values) {
+          if (!eligible.includes(String(item))) {
+            pushFieldError(
+              fieldErrors,
+              input.key,
+              "Selected target is not eligible.",
+            );
+            break;
+          }
+        }
+      }
+    }
+  }
+
+  return fieldErrors;
+}
+
+export function isInputValueReady(
+  input: InteractionInputDescriptor,
+  value: unknown,
+): boolean {
+  if (value === undefined || value === null) return false;
+  const selection = input.domain.selection;
+  if (selection?.mode !== "many") return true;
+  return Array.isArray(value) && value.length >= (selection.min ?? 0);
+}
+
+export function isManyInput(input: InteractionInputDescriptor): boolean {
+  return input.domain.selection?.mode === "many";
+}
+
+export function maxSelectedForInput(
+  input: InteractionInputDescriptor,
+): number | undefined {
+  const selection = input.domain.selection;
+  return selection?.mode === "many" ? selection.max : undefined;
+}
+
+export function toggleManyValue(
+  current: unknown,
+  value: string,
+  selection: InputSelection,
+): string[] {
+  const previous = Array.isArray(current)
+    ? current.map((item) => String(item))
+    : [];
+  const existing = previous.indexOf(value);
+  if (existing >= 0) {
+    return previous.filter((item) => item !== value);
+  }
+  if (selection.max !== undefined && previous.length >= selection.max) {
+    return previous;
+  }
+  return [...previous, value];
+}
+
+export function isManyTargetSelectable(
+  input: InteractionInputDescriptor,
+  current: unknown,
+  targetId: string,
+): boolean {
+  const selection = input.domain.selection;
+  if (selection?.mode !== "many") return true;
+  const currentValues = Array.isArray(current)
+    ? current.map((item) => String(item))
+    : [];
+  if (currentValues.includes(targetId)) return true;
+  if (selection.distinct && currentValues.includes(targetId)) return false;
+  return selection.max === undefined || currentValues.length < selection.max;
+}
+
+export function mergeInteractionFieldErrors(
+  ...sources: Array<Partial<Record<string, readonly string[]>>>
+): Partial<Record<string, readonly string[]>> {
+  const merged: Record<string, string[]> = {};
+  for (const source of sources) {
+    for (const [key, messages] of Object.entries(source)) {
+      if (!messages || messages.length === 0) continue;
+      merged[key] = [...(merged[key] ?? []), ...messages];
+    }
+  }
+  return merged;
+}
+
+export function hasInteractionFieldErrors(
+  fieldErrors: Partial<Record<string, readonly string[]>>,
+): boolean {
+  return Object.values(fieldErrors).some(
+    (messages) => (messages?.length ?? 0) > 0,
+  );
+}
+
+export function inputByKey(
+  descriptor: Pick<InteractionDescriptor, "inputs">,
+  key: string,
+): InteractionInputDescriptor | undefined {
+  return descriptor.inputs.find((input) => input.key === key);
+}
+
+export function inputByTarget(
+  descriptor: Pick<InteractionDescriptor, "inputs">,
+  targetKind: BoardTargetKind | "card",
+  targetId: string,
+): InteractionInputDescriptor | null {
+  for (const input of descriptor.inputs) {
+    if (input.domain.type !== "target") continue;
+    if (input.domain.targetKind !== targetKind) continue;
+    if (input.domain.eligibleTargets?.includes(targetId)) return input;
+  }
+  return null;
+}
+
+export function eligibleTargetsForInput(
+  descriptor: Pick<InteractionDescriptor, "inputs">,
+  key: string,
+): readonly string[] | undefined {
+  const domain = inputByKey(descriptor, key)?.domain;
+  return domain?.type === "target" ? domain.eligibleTargets : undefined;
+}
+
+export function eligibleTargetsByInput(
+  descriptor: Pick<InteractionDescriptor, "inputs">,
+): Record<string, readonly string[]> {
+  return Object.fromEntries(
+    descriptor.inputs.flatMap((input) => {
+      const targets =
+        input.domain.type === "target"
+          ? input.domain.eligibleTargets
+          : undefined;
+      return targets ? [[input.key, targets]] : [];
+    }),
+  );
+}
+
+export function eligibleTargetsByBoardKind(
+  descriptor: Pick<InteractionDescriptor, "inputs">,
+): Partial<Record<BoardTargetKind, readonly string[]>> {
+  const result: Record<BoardTargetKind, Set<string>> = {
+    edge: new Set<string>(),
+    vertex: new Set<string>(),
+    space: new Set<string>(),
+    tile: new Set<string>(),
+  };
+  for (const input of descriptor.inputs) {
+    if (input.domain.type !== "target") continue;
+    const targetKind = input.domain.targetKind;
+    if (!isBoardTargetKind(targetKind)) continue;
+    for (const targetId of input.domain.eligibleTargets ?? []) {
+      result[targetKind].add(targetId);
+    }
+  }
+  return Object.fromEntries(
+    Object.entries(result).flatMap(([kind, ids]) =>
+      ids.size > 0 ? [[kind, [...ids]]] : [],
+    ),
+  ) as Partial<Record<BoardTargetKind, readonly string[]>>;
+}
+
+export function hasBoardTargetInput(
+  descriptor: Pick<InteractionDescriptor, "inputs">,
+): boolean {
+  return Object.keys(eligibleTargetsByBoardKind(descriptor)).length > 0;
+}
+
+export function hasCardTargetInput(
+  descriptor: Pick<InteractionDescriptor, "inputs">,
+): boolean {
+  return descriptor.inputs.some(
+    (input) =>
+      input.domain.type === "target" && input.domain.targetKind === "card",
+  );
+}
+
+export function interactionArmScope(
+  descriptor: Pick<
+    InteractionDescriptor,
+    "inputs" | "interactionKey" | "zoneId"
+  >,
+): string {
+  const byKind = eligibleTargetsByBoardKind(descriptor);
+  const boardKinds = (Object.keys(byKind) as BoardTargetKind[]).filter(
+    (kind) => byKind[kind] !== undefined,
+  );
+  if (boardKinds.length === 1) return `board:${boardKinds[0]}`;
+  if (boardKinds.length > 1) return "board";
+  if (descriptor.zoneId) return `zone:${descriptor.zoneId}`;
+  return `interaction:${descriptor.interactionKey}`;
+}
+
+export function inputKeyForTarget(
+  descriptor: Pick<InteractionDescriptor, "inputs">,
+  targetKind: BoardTargetKind | "card",
+  targetId: string,
+): string | null {
+  return inputByTarget(descriptor, targetKind, targetId)?.key ?? null;
+}
+
+function validateInputSelection(
+  input: InteractionInputDescriptor,
+  value: unknown,
+): string[] {
+  const selection = input.domain.selection;
+  if (selection?.mode !== "many") return [];
+  if (!Array.isArray(value)) return ["Expected a list of values."];
+  const errors: string[] = [];
+  const min = selection.min ?? 0;
+  if (value.length < min) {
+    errors.push(`Choose at least ${min} ${pluralize("value", min)}.`);
+  }
+  if (selection.max !== undefined && value.length > selection.max) {
+    errors.push(
+      `Choose at most ${selection.max} ${pluralize("value", selection.max)}.`,
+    );
+  }
+  if (selection.distinct) {
+    const seen = new Set<string>();
+    for (const item of value) {
+      const key = String(item);
+      if (seen.has(key)) {
+        errors.push("Choose each value only once.");
+        break;
+      }
+      seen.add(key);
+    }
+  }
+  return errors;
+}
+
+function valuesForSelection(
+  selection: InputSelection | undefined,
+  value: unknown,
+): readonly unknown[] {
+  if (selection?.mode === "many") return Array.isArray(value) ? value : [];
+  return [value];
+}
+
+function isBoardTargetKind(value: unknown): value is BoardTargetKind {
+  return (
+    value === "edge" ||
+    value === "vertex" ||
+    value === "space" ||
+    value === "tile"
+  );
+}
+
+function pushFieldError(
+  fieldErrors: Record<string, string[]>,
+  key: string,
+  message: string,
+): void {
+  fieldErrors[key] = [...(fieldErrors[key] ?? []), message];
+}
+
+function pluralize(word: string, count: number): string {
+  return count === 1 ? word : `${word}s`;
+}

package/src/utils/interaction-labels.ts

@@ -0,0 +1,23 @@
+import type { InteractionDescriptor } from "../types/plugin-state.js";
+
+export function humanizeInteractionId(id: string): string {
+  if (!id) return id;
+  const withSpaces = id
+    .replace(/[-_]+/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .trim();
+  if (!withSpaces) return id;
+  return withSpaces
+    .split(/\s+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+export function interactionLabel(
+  descriptor: Pick<InteractionDescriptor, "interactionId" | "interactionKey">,
+): string {
+  return humanizeInteractionId(
+    descriptor.interactionId || descriptor.interactionKey,
+  );
+}

package/src/utils/interaction-status.ts

@@ -0,0 +1,59 @@
+import type { InteractionHandleStatus } from "../hooks/useInteractionHandle.js";
+import type { InteractionDescriptor } from "../types/plugin-state.js";
+
+export type InteractionActionState =
+  | "available"
+  | "unavailable"
+  | "submitting"
+  | "submitted";
+
+export type InteractionDisabledReason =
+  | "unavailable"
+  | "selection-limit"
+  | "submitting"
+  | "submitted";
+
+export interface InteractionStatusSnapshot {
+  status: InteractionHandleStatus;
+  actionState: InteractionActionState;
+  disabled: boolean;
+  disabledReason?: InteractionDisabledReason;
+}
+
+export function interactionStatusSnapshot({
+  descriptor,
+  status,
+}: {
+  descriptor: InteractionDescriptor;
+  status: InteractionHandleStatus;
+}): InteractionStatusSnapshot {
+  if (status === "submitted") {
+    return {
+      status,
+      actionState: "submitted",
+      disabled: true,
+      disabledReason: "submitted",
+    };
+  }
+  if (status === "submitting") {
+    return {
+      status,
+      actionState: "submitting",
+      disabled: true,
+      disabledReason: "submitting",
+    };
+  }
+  if (descriptor.available === false) {
+    return {
+      status,
+      actionState: "unavailable",
+      disabled: true,
+      disabledReason: "unavailable",
+    };
+  }
+  return {
+    status,
+    actionState: "available",
+    disabled: false,
+  };
+}