@dreamboard-games/ui-sdk 0.0.41

package/src/primitives/board.test.tsx

@@ -0,0 +1,139 @@
+import { expect, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import type {
+  InteractionDescriptor,
+  PluginStateSnapshot,
+} from "../types/plugin-state.js";
+import type { PluginSessionState, RuntimeAPI } from "../types/runtime-api.js";
+import { Board } from "./board.js";
+import { GameUIProvider } from "./game-ui-provider.js";
+
+function createSessionState(): PluginSessionState {
+  return {
+    status: "ready",
+    sessionId: "session-1",
+    controllablePlayerIds: ["player-1"],
+    controllingPlayerId: "player-1",
+    userId: "user-1",
+  };
+}
+
+function createBoardDescriptor(
+  interactionId: string,
+  options: Partial<InteractionDescriptor> = {},
+): InteractionDescriptor {
+  return {
+    phaseName: "play",
+    interactionKey: `play.${interactionId}`,
+    interactionId,
+    surface: "board-space",
+    kind: "action",
+    label: interactionId,
+    inputs: [
+      {
+        key: "spaceId",
+        kind: "board-space",
+        domain: {
+          type: "target",
+          targetKind: "space",
+          eligibleTargets: ["space-1"],
+        },
+      },
+    ],
+    commit: { mode: "manual" },
+    available: true,
+    ...options,
+  };
+}
+
+function createSnapshot(
+  availableInteractions: readonly InteractionDescriptor[],
+): PluginStateSnapshot {
+  return {
+    view: {},
+    gameplay: {
+      currentPhase: "play",
+      currentStage: null,
+      activePlayers: ["player-1"],
+      zones: {},
+      availableInteractions,
+    },
+    lobby: null,
+    notifications: [],
+    session: createSessionState(),
+    history: null,
+    syncId: 1,
+  };
+}
+
+function createRuntime(snapshot: PluginStateSnapshot): RuntimeAPI {
+  return {
+    validateInteraction: async () => ({ valid: true }),
+    submitInteraction: async () => undefined,
+    getSessionState: () => snapshot.session,
+    disconnect: () => undefined,
+    getSnapshot: () => snapshot,
+    subscribeToState: () => () => undefined,
+  } as RuntimeAPI;
+}
+
+test("Board.Target exposes reducer-projected target eligibility", () => {
+  const runtime = createRuntime(
+    createSnapshot([createBoardDescriptor("claimSpace")]),
+  );
+
+  const html = renderToString(
+    <GameUIProvider runtime={runtime}>
+      <Board.Root>
+        <Board.Target kind="space" value="space-1">
+          Space one
+        </Board.Target>
+      </Board.Root>
+    </GameUIProvider>,
+  );
+
+  expect(html).toContain('data-dreamboard-board-root=""');
+  expect(html).toContain('data-dreamboard-board-target=""');
+  expect(html).toContain('data-target-kind="space"');
+  expect(html).toContain('data-target-id="space-1"');
+  expect(html).toContain('data-eligible="true"');
+  expect(html).not.toContain('data-ambiguous="true"');
+});
+
+test("Board.Target requires explicit routing when equal-priority matches are ambiguous", () => {
+  const runtime = createRuntime(
+    createSnapshot([
+      createBoardDescriptor("claimSpace"),
+      createBoardDescriptor("inspectSpace"),
+    ]),
+  );
+
+  const ambiguousHtml = renderToString(
+    <GameUIProvider runtime={runtime}>
+      <Board.Root>
+        <Board.Target kind="space" value="space-1">
+          Space one
+        </Board.Target>
+      </Board.Root>
+    </GameUIProvider>,
+  );
+  const explicitHtml = renderToString(
+    <GameUIProvider runtime={runtime}>
+      <Board.Root>
+        <Board.Target
+          kind="space"
+          value="space-1"
+          interaction="play.claimSpace"
+        >
+          Space one
+        </Board.Target>
+      </Board.Root>
+    </GameUIProvider>,
+  );
+
+  expect(ambiguousHtml).toContain('data-ambiguous="true"');
+  expect(ambiguousHtml).toContain("disabled=");
+  expect(explicitHtml).toContain('data-interaction-key="play.claimSpace"');
+  expect(explicitHtml).toContain('data-input-name="spaceId"');
+  expect(explicitHtml).not.toContain('data-ambiguous="true"');
+});

package/src/primitives/board.tsx

@@ -0,0 +1,267 @@
+import {
+  createContext,
+  useContext,
+  type ButtonHTMLAttributes,
+  type ReactNode,
+} from "react";
+import { useBoardInteractions } from "../hooks/useBoardInteractions.js";
+import { useInteractionHandle } from "../hooks/useInteractionHandle.js";
+import { usePluginState } from "../context/PluginStateContext.js";
+import type { InteractionDescriptor } from "../types/plugin-state.js";
+import type { BoardTargetKey } from "../ui-contract.js";
+import {
+  inputByKey,
+  inputKeyForTarget,
+  interactionInputKeys,
+  type BoardTargetKind,
+} from "../utils/interaction-inputs.js";
+import {
+  composeEventHandlers,
+  renderPrimitive,
+  type PrimitiveCommonProps,
+} from "./primitive-props.js";
+
+type BoardContextValue = ReturnType<typeof useBoardInteractions>;
+
+const BoardContext = createContext<BoardContextValue | null>(null);
+
+export function useBoardPrimitiveContext(): BoardContextValue {
+  const value = useContext(BoardContext);
+  if (!value) {
+    throw new Error("Board primitives must be rendered inside <Board.Root>.");
+  }
+  return value;
+}
+
+export interface BoardRootProps extends PrimitiveCommonProps {
+  children: ReactNode;
+  targetKinds?: readonly BoardTargetKind[];
+}
+
+export function BoardRoot({ children, targetKinds, ...props }: BoardRootProps) {
+  const board = useBoardInteractions({ targetKinds });
+  return (
+    <BoardContext.Provider value={board}>
+      {renderPrimitive("div", {
+        ...props,
+        "data-dreamboard-board-root": "",
+        children,
+      })}
+    </BoardContext.Provider>
+  );
+}
+
+export type BoardTargetExtraInputs =
+  | Record<string, unknown>
+  | ((targetId: string) => Record<string, unknown>);
+
+export type BoardTargetProps<Target extends string = BoardTargetKey> =
+  PrimitiveCommonProps &
+    ButtonHTMLAttributes<HTMLButtonElement> & {
+      kind: BoardTargetKind;
+      value: Target;
+      interaction?: string;
+      input?: string;
+      extraInputs?: BoardTargetExtraInputs;
+      onSelect?: (interactionKey: string | null) => void;
+      onSelectError?: (error: unknown) => void;
+    };
+
+export function BoardTarget<Target extends string = BoardTargetKey>({
+  interaction,
+  input,
+  ...props
+}: BoardTargetProps<Target>) {
+  const descriptor = usePluginState((state) =>
+    interaction
+      ? state.gameplay.availableInteractions.find(
+          (candidate) =>
+            candidate.interactionKey === interaction ||
+            candidate.interactionId === interaction,
+        )
+      : undefined,
+  );
+
+  if (interaction) {
+    return descriptor ? (
+      <ExplicitBoardTarget descriptor={descriptor} input={input} {...props} />
+    ) : (
+      <UnavailableBoardTarget
+        interaction={interaction}
+        input={input}
+        {...props}
+      />
+    );
+  }
+
+  return <UnambiguousBoardTarget input={input} {...props} />;
+}
+
+function UnambiguousBoardTarget({
+  kind,
+  value,
+  extraInputs,
+  onSelect,
+  onSelectError,
+  disabled,
+  onClick,
+  children,
+  ...props
+}: Omit<BoardTargetProps, "interaction">) {
+  const board = useBoardPrimitiveContext();
+  const eligible = board.isEligible(value, kind);
+  const ambiguous = isAmbiguousBoardTarget(board.interactions, kind, value);
+  const isDisabled = disabled ?? (!eligible || ambiguous);
+  return renderPrimitive("button", {
+    type: "button",
+    ...props,
+    children,
+    disabled: isDisabled,
+    "aria-disabled": isDisabled,
+    "data-dreamboard-board-target": "",
+    "data-target-kind": kind,
+    "data-target-id": value,
+    "data-eligible": eligible,
+    "data-ambiguous": ambiguous || undefined,
+    "data-disabled": isDisabled || undefined,
+    onClick: composeEventHandlers(onClick, () => {
+      if (isDisabled) return;
+      void board.select[kind](value, resolveExtraInputs(extraInputs, value))
+        .then((interactionKey) => {
+          onSelect?.(interactionKey);
+        })
+        .catch((error) => {
+          onSelectError?.(error);
+          if (!onSelectError) throw error;
+        });
+    }),
+  });
+}
+
+function ExplicitBoardTarget({
+  descriptor,
+  kind,
+  value,
+  input,
+  extraInputs,
+  onSelect,
+  onSelectError,
+  disabled,
+  onClick,
+  children,
+  ...props
+}: Omit<BoardTargetProps, "interaction"> & {
+  descriptor: InteractionDescriptor;
+}) {
+  const handle = useInteractionHandle(descriptor);
+  const inputKey = input ?? inputKeyForTarget(descriptor, kind, value);
+  const inputDescriptor = inputKey
+    ? inputByKey(descriptor, inputKey)
+    : undefined;
+  const eligible =
+    inputDescriptor !== undefined &&
+    inputDescriptor.domain.type === "target" &&
+    inputDescriptor.domain.targetKind === kind &&
+    (inputDescriptor.domain.eligibleTargets === undefined ||
+      inputDescriptor.domain.eligibleTargets.includes(value));
+  const isDisabled = disabled ?? (!descriptor.available || !eligible);
+  return renderPrimitive("button", {
+    type: "button",
+    ...props,
+    children,
+    disabled: isDisabled,
+    "aria-disabled": isDisabled,
+    "data-dreamboard-board-target": "",
+    "data-target-kind": kind,
+    "data-target-id": value,
+    "data-interaction-id": descriptor.interactionId,
+    "data-interaction-key": descriptor.interactionKey,
+    "data-input-name": inputKey ?? undefined,
+    "data-eligible": eligible,
+    "data-disabled": isDisabled || undefined,
+    onClick: composeEventHandlers(onClick, () => {
+      if (isDisabled || !inputKey) return;
+      const resolvedExtraInputs = resolveExtraInputs(extraInputs, value);
+      for (const [key, extraValue] of Object.entries(resolvedExtraInputs)) {
+        handle.setInput(key, extraValue);
+      }
+      handle.setInput(inputKey, value);
+      if (descriptor.commit.mode !== "autoWhenReady") {
+        handle.arm();
+        onSelect?.(descriptor.interactionKey);
+        return;
+      }
+      const params: Record<string, unknown> = {
+        ...handle.draft,
+        ...resolvedExtraInputs,
+        [inputKey]: value,
+      };
+      for (const required of interactionInputKeys(descriptor)) {
+        if (!(required in params)) params[required] = null;
+      }
+      void handle
+        .submit(params)
+        .then(() => {
+          onSelect?.(descriptor.interactionKey);
+        })
+        .catch((error) => {
+          onSelectError?.(error);
+          if (!onSelectError) throw error;
+        });
+    }),
+  });
+}
+
+function UnavailableBoardTarget({
+  kind,
+  value,
+  interaction,
+  input,
+  disabled,
+  children,
+  ...props
+}: Omit<BoardTargetProps, "onSelect" | "onSelectError" | "extraInputs">) {
+  const isDisabled = disabled ?? true;
+  return renderPrimitive("button", {
+    type: "button",
+    ...props,
+    children,
+    disabled: isDisabled,
+    "aria-disabled": isDisabled,
+    "data-dreamboard-board-target": "",
+    "data-target-kind": kind,
+    "data-target-id": value,
+    "data-interaction-key": interaction,
+    "data-input-name": input,
+    "data-eligible": false,
+    "data-disabled": isDisabled || undefined,
+  });
+}
+
+function resolveExtraInputs(
+  extraInputs: BoardTargetExtraInputs | undefined,
+  targetId: string,
+): Record<string, unknown> {
+  return typeof extraInputs === "function"
+    ? extraInputs(targetId)
+    : (extraInputs ?? {});
+}
+
+function isAmbiguousBoardTarget(
+  descriptors: readonly InteractionDescriptor[],
+  kind: BoardTargetKind,
+  value: string,
+): boolean {
+  const matches = descriptors.flatMap((descriptor) => {
+    if (!descriptor.available) return [];
+    const inputKey = inputKeyForTarget(descriptor, kind, value);
+    if (!inputKey) return [];
+    return [descriptor.interactionKey];
+  });
+  return matches.length > 1;
+}
+
+export const Board = {
+  Root: BoardRoot,
+  Target: BoardTarget,
+};

package/src/primitives/game-ui-provider.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from "react";
+import {
+  PluginStateProvider,
+  type PluginStateProviderProps,
+} from "../context/PluginStateContext.js";
+import { RuntimeProvider } from "../context/RuntimeContext.js";
+import {
+  InteractionUiProvider,
+  type InteractionUiStoreApi,
+} from "../context/InteractionDraftContext.js";
+import type { RuntimeAPI } from "../types/runtime-api.js";
+
+export interface GameUIProviderProps {
+  runtime: RuntimeAPI;
+  children: ReactNode;
+  loadingComponent?: PluginStateProviderProps["loadingComponent"];
+  interactionStore?: InteractionUiStoreApi;
+}
+
+export function GameUIProvider({
+  runtime,
+  children,
+  loadingComponent,
+  interactionStore,
+}: GameUIProviderProps) {
+  return (
+    <RuntimeProvider runtime={runtime}>
+      <PluginStateProvider loadingComponent={loadingComponent}>
+        <InteractionUiProvider store={interactionStore}>
+          {children}
+        </InteractionUiProvider>
+      </PluginStateProvider>
+    </RuntimeProvider>
+  );
+}

package/src/primitives/index.ts

@@ -0,0 +1,83 @@
+export {
+  Board,
+  BoardRoot,
+  BoardTarget,
+  useBoardPrimitiveContext,
+  type BoardRootProps,
+  type BoardTargetExtraInputs,
+  type BoardTargetProps,
+} from "./board.js";
+export {
+  Interaction,
+  InteractionCardInput,
+  InteractionDescription,
+  InteractionInput,
+  InteractionLabel,
+  InteractionRoot,
+  InteractionSubmit,
+  InteractionTrigger,
+  InteractionUnavailableMessage,
+  InteractionValidationMessage,
+  useInteractionPrimitiveContext,
+  type InteractionCardInputProps,
+  type InteractionInputProps,
+  type InteractionPartProps,
+  type InteractionRootProps,
+  type InteractionSubmitProps,
+  type InteractionTriggerProps,
+} from "./interaction.js";
+export {
+  Phase,
+  PhaseSwitch,
+  type PhaseFallback,
+  type PhaseRouteMap,
+  type PhaseSwitchProps,
+} from "./phase.js";
+export {
+  PlayerRoster,
+  PlayerRosterBadges,
+  PlayerRosterEmpty,
+  PlayerRosterList,
+  PlayerRosterName,
+  PlayerRosterRoot,
+  PlayerRosterScore,
+  PlayerRosterSwitchButton,
+  type PlayerRosterBadge,
+  type PlayerRosterComponents,
+  type PlayerRosterEntry,
+  type PlayerRosterListProps,
+  type PlayerRosterPartProps,
+  type PlayerRosterRootProps,
+  type PlayerRosterSwitchButtonProps,
+} from "./player-roster.js";
+export {
+  Prompt,
+  PromptInbox,
+  PromptInboxEmpty,
+  PromptInboxItems,
+  PromptInboxRoot,
+  PromptMessage,
+  PromptOption,
+  PromptOptions,
+  PromptRoot,
+  PromptTitle,
+  type PromptOptionProps,
+  type PromptRootProps,
+} from "./prompt.js";
+export {
+  composeEventHandlers,
+  renderPrimitive,
+  type PrimitiveCommonProps,
+  type PrimitiveDataAttributes,
+} from "./primitive-props.js";
+export {
+  Zone,
+  ZoneItem,
+  ZoneList,
+  ZoneRoot,
+  useZoneCardContext,
+  useZonePrimitiveContext,
+  type ZoneItemProps,
+  type ZoneListProps,
+  type ZoneRootProps,
+} from "./zone.js";