@dreamboard-games/ui-sdk 0.0.43 → 0.0.46

package/src/primitives/board.tsx

@@ -1,18 +1,31 @@
 import {
   createContext,
   useContext,
+  useMemo,
   type ButtonHTMLAttributes,
   type ReactNode,
 } from "react";
-import { useBoardInteractions } from "../hooks/useBoardInteractions.js";
-import { useInteractionHandle } from "../hooks/useInteractionHandle.js";
+import {
+  createHexBoardView,
+  type HexBoardView,
+} from "../components/board/hex-board-view.js";
+import {
+  HexGrid,
+  type HexGridBoardProps,
+} from "../components/board/HexGrid.js";
+import {
+  useBoardInteractions,
+  type BoardInteractionsContext,
+  type BoardSelectionResult,
+  type BoardTargetLayerOptions,
+} from "../hooks/useBoardInteractions.js";
 import { usePluginState } from "../context/PluginStateContext.js";
+import type { AnyHexBoardInput, BoardSpaceIdOf } from "../types/tiled-board.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 {
@@ -20,8 +33,10 @@ import {
   renderPrimitive,
   type PrimitiveCommonProps,
 } from "./primitive-props.js";
+import { runInteractionAction } from "./interaction-submit.js";
+import { useGameActionError } from "./game.js";
 
-type BoardContextValue = ReturnType<typeof useBoardInteractions>;
+type BoardContextValue = BoardInteractionsContext;
 
 const BoardContext = createContext<BoardContextValue | null>(null);
 
@@ -51,6 +66,118 @@ export function BoardRoot({ children, targetKinds, ...props }: BoardRootProps) {
   );
 }
 
+export interface BoardStateProps {
+  children: (board: BoardInteractionsContext) => ReactNode;
+}
+
+export function BoardState({ children }: BoardStateProps) {
+  return <>{children(useBoardPrimitiveContext())}</>;
+}
+
+export interface BoardHexViewProps<
+  TBoard extends AnyHexBoardInput,
+  TSpaceView extends { id: BoardSpaceIdOf<TBoard> },
+> {
+  board: TBoard;
+  spaces: readonly TSpaceView[];
+  children: (view: HexBoardView<TBoard, TSpaceView>) => ReactNode;
+}
+
+export function BoardHexView<
+  const TBoard extends AnyHexBoardInput,
+  const TSpaceView extends { id: BoardSpaceIdOf<TBoard> },
+>({ board, spaces, children }: BoardHexViewProps<TBoard, TSpaceView>) {
+  const view = useMemo(
+    () => createHexBoardView<TBoard, TSpaceView>(board, { spaces }),
+    [board, spaces],
+  );
+  return <>{children(view)}</>;
+}
+
+export interface BoardHexGridInteractions {
+  edge?: BoardTargetLayerOptions;
+  vertex?: BoardTargetLayerOptions;
+  space?: BoardTargetLayerOptions;
+}
+
+export type BoardHexGridInteractionFilter =
+  | "auto"
+  | false
+  | {
+      edge?: readonly string[];
+      vertex?: readonly string[];
+      space?: readonly string[];
+    };
+
+type BoardHexGridView<
+  TBoard extends AnyHexBoardInput,
+  TSpaceView extends { id: BoardSpaceIdOf<TBoard> },
+> = HexBoardView<TBoard, TSpaceView> & AnyHexBoardInput;
+
+export type BoardHexGridProps<
+  TBoard extends AnyHexBoardInput,
+  TSpaceView extends { id: BoardSpaceIdOf<TBoard> },
+> = Omit<
+  HexGridBoardProps<BoardHexGridView<TBoard, TSpaceView>>,
+  "board" | "interactiveEdges" | "interactiveVertices" | "interactiveSpaces"
+> &
+  Omit<BoardHexViewProps<TBoard, TSpaceView>, "children"> & {
+    interactions?: BoardHexGridInteractionFilter;
+  };
+
+export function BoardHexGrid<
+  const TBoard extends AnyHexBoardInput,
+  const TSpaceView extends { id: BoardSpaceIdOf<TBoard> },
+>({
+  board,
+  spaces,
+  interactions = "auto",
+  ...props
+}: BoardHexGridProps<TBoard, TSpaceView>) {
+  const boardInteractions = useBoardPrimitiveContext();
+  const gameActionError = useGameActionError();
+  const edgeLayer =
+    interactions === false
+      ? undefined
+      : boardInteractions.targetLayers.edge({
+          enabled: boardInteractions.eligible.edge.size > 0,
+          interactionKeys:
+            interactions === "auto" ? undefined : interactions.edge,
+          onError: gameActionError ?? undefined,
+        });
+  const vertexLayer =
+    interactions === false
+      ? undefined
+      : boardInteractions.targetLayers.vertex({
+          enabled: boardInteractions.eligible.vertex.size > 0,
+          interactionKeys:
+            interactions === "auto" ? undefined : interactions.vertex,
+          onError: gameActionError ?? undefined,
+        });
+  const spaceLayer =
+    interactions === false
+      ? undefined
+      : boardInteractions.targetLayers.space({
+          enabled: boardInteractions.eligible.space.size > 0,
+          interactionKeys:
+            interactions === "auto" ? undefined : interactions.space,
+          onError: gameActionError ?? undefined,
+        });
+  return (
+    <BoardHexView board={board} spaces={spaces}>
+      {(view) => (
+        <HexGrid
+          {...props}
+          board={view as BoardHexGridView<TBoard, TSpaceView>}
+          interactiveEdges={edgeLayer}
+          interactiveVertices={vertexLayer}
+          interactiveSpaces={spaceLayer}
+        />
+      )}
+    </BoardHexView>
+  );
+}
+
 export type BoardTargetExtraInputs =
   | Record<string, unknown>
   | ((targetId: string) => Record<string, unknown>);
@@ -63,7 +190,7 @@ export type BoardTargetProps<Target extends string = BoardTargetKey> =
       interaction?: string;
       input?: string;
       extraInputs?: BoardTargetExtraInputs;
-      onSelect?: (interactionKey: string | null) => void;
+      onSelect?: (result: BoardSelectionResult) => void;
       onSelectError?: (error: unknown) => void;
     };
 
@@ -97,6 +224,35 @@ export function BoardTarget<Target extends string = BoardTargetKey>({
   return <UnambiguousBoardTarget input={input} {...props} />;
 }
 
+export type BoardSpaceTargetProps<Target extends string = BoardTargetKey> =
+  Omit<BoardTargetProps<Target>, "kind">;
+
+export function BoardSpaceTarget<Target extends string = BoardTargetKey>(
+  props: BoardSpaceTargetProps<Target>,
+) {
+  return <BoardTarget kind="space" {...props} />;
+}
+
+export type BoardEdgeTargetProps<Target extends string = BoardTargetKey> = Omit<
+  BoardTargetProps<Target>,
+  "kind"
+>;
+
+export function BoardEdgeTarget<Target extends string = BoardTargetKey>(
+  props: BoardEdgeTargetProps<Target>,
+) {
+  return <BoardTarget kind="edge" {...props} />;
+}
+
+export type BoardVertexTargetProps<Target extends string = BoardTargetKey> =
+  Omit<BoardTargetProps<Target>, "kind">;
+
+export function BoardVertexTarget<Target extends string = BoardTargetKey>(
+  props: BoardVertexTargetProps<Target>,
+) {
+  return <BoardTarget kind="vertex" {...props} />;
+}
+
 function UnambiguousBoardTarget({
   kind,
   value,
@@ -109,6 +265,7 @@ function UnambiguousBoardTarget({
   ...props
 }: Omit<BoardTargetProps, "interaction">) {
   const board = useBoardPrimitiveContext();
+  const gameActionError = useGameActionError();
   const eligible = board.isEligible(value, kind);
   const ambiguous = isAmbiguousBoardTarget(board.interactions, kind, value);
   const isDisabled = disabled ?? (!eligible || ambiguous);
@@ -126,14 +283,13 @@ function UnambiguousBoardTarget({
     "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;
-        });
+      void runInteractionAction(
+        () => board.select[kind](value, resolveExtraInputs(extraInputs, value)),
+        {
+          onSuccess: onSelect,
+          onError: onSelectError ?? gameActionError ?? undefined,
+        },
+      );
     }),
   });
 }
@@ -153,7 +309,8 @@ function ExplicitBoardTarget({
 }: Omit<BoardTargetProps, "interaction"> & {
   descriptor: InteractionDescriptor;
 }) {
-  const handle = useInteractionHandle(descriptor);
+  const board = useBoardPrimitiveContext();
+  const gameActionError = useGameActionError();
   const inputKey = input ?? inputKeyForTarget(descriptor, kind, value);
   const inputDescriptor = inputKey
     ? inputByKey(descriptor, inputKey)
@@ -182,32 +339,20 @@ function ExplicitBoardTarget({
     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;
-        });
+      void runInteractionAction(
+        () =>
+          board.selectTarget(
+            descriptor,
+            kind,
+            value,
+            inputKey,
+            resolvedExtraInputs,
+          ),
+        {
+          onSuccess: onSelect,
+          onError: onSelectError ?? gameActionError ?? undefined,
+        },
+      );
     }),
   });
 }
@@ -263,5 +408,11 @@ function isAmbiguousBoardTarget(
 
 export const Board = {
   Root: BoardRoot,
+  State: BoardState,
+  HexGrid: BoardHexGrid,
+  HexView: BoardHexView,
   Target: BoardTarget,
+  SpaceTarget: BoardSpaceTarget,
+  EdgeTarget: BoardEdgeTarget,
+  VertexTarget: BoardVertexTarget,
 };

package/src/primitives/dialog-lifecycle.ts

@@ -0,0 +1,58 @@
+import { useCallback, useMemo, useState } from "react";
+
+export type DialogLifecycleState = "open" | "minimized" | "dismissed";
+
+export interface DialogLifecycleValue {
+  state: DialogLifecycleState;
+  open: boolean;
+  minimized: boolean;
+  dismissed: boolean;
+  setOpen: (open: boolean) => void;
+  restore: () => void;
+  minimize: () => void;
+  dismiss: () => void;
+}
+
+export interface DialogLifecycleOptions {
+  defaultOpen?: boolean;
+  onStateChange?: (state: DialogLifecycleState) => void;
+}
+
+export function useDialogLifecycle({
+  defaultOpen = true,
+  onStateChange,
+}: DialogLifecycleOptions): DialogLifecycleValue {
+  const [state, setState] = useState<DialogLifecycleState>(
+    defaultOpen ? "open" : "minimized",
+  );
+  const updateState = useCallback(
+    (nextState: DialogLifecycleState) => {
+      setState(nextState);
+      onStateChange?.(nextState);
+    },
+    [onStateChange],
+  );
+  const restore = useCallback(() => updateState("open"), [updateState]);
+  const minimize = useCallback(() => updateState("minimized"), [updateState]);
+  const dismiss = useCallback(() => updateState("dismissed"), [updateState]);
+  const setOpen = useCallback(
+    (open: boolean) => {
+      updateState(open ? "open" : "minimized");
+    },
+    [updateState],
+  );
+
+  return useMemo<DialogLifecycleValue>(
+    () => ({
+      state,
+      open: state === "open",
+      minimized: state === "minimized",
+      dismissed: state === "dismissed",
+      setOpen,
+      restore,
+      minimize,
+      dismiss,
+    }),
+    [dismiss, minimize, restore, setOpen, state],
+  );
+}

package/src/primitives/dice.test.tsx

@@ -0,0 +1,47 @@
+import { expect, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import { Dice } from "./dice.js";
+
+test("Dice primitives expose normalized readonly values and sum", () => {
+  const html = renderToString(
+    <Dice.Root values={[3, 4] as const} count={2}>
+      <Dice.Values>
+        {({ values, sum, diceCount, allRolled }) => (
+          <span
+            data-values={values?.join(",")}
+            data-sum={sum}
+            data-count={diceCount}
+            data-all-rolled={allRolled}
+          />
+        )}
+      </Dice.Values>
+    </Dice.Root>,
+  );
+
+  expect(html).toContain('data-values="3,4"');
+  expect(html).toContain('data-sum="7"');
+  expect(html).toContain('data-count="2"');
+  expect(html).toContain('data-all-rolled="true"');
+});
+
+test("Dice primitives preserve unrolled state without a local adapter", () => {
+  const html = renderToString(
+    <Dice.Root values={null} count={2}>
+      <Dice.Values>
+        {({ values, sum, diceCount, allRolled }) => (
+          <span
+            data-values={values?.join(",") ?? "none"}
+            data-sum={sum ?? "none"}
+            data-count={diceCount}
+            data-all-rolled={allRolled}
+          />
+        )}
+      </Dice.Values>
+    </Dice.Root>,
+  );
+
+  expect(html).toContain('data-values="none"');
+  expect(html).toContain('data-sum="none"');
+  expect(html).toContain('data-count="2"');
+  expect(html).toContain('data-all-rolled="false"');
+});

package/src/primitives/dice.tsx

@@ -0,0 +1,79 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+export type DiceValue = number | null | undefined;
+
+export interface DiceState {
+  values: ReadonlyArray<number | undefined> | undefined;
+  /** Undefined if any die has not been rolled yet. */
+  sum: number | undefined;
+  diceCount: number;
+  allRolled: boolean;
+}
+
+export interface DiceRootProps {
+  values?: readonly DiceValue[] | null;
+  /** Used when values are not provided. */
+  count?: number;
+  children: ReactNode;
+}
+
+export interface DiceValuesProps {
+  children: (state: DiceState) => ReactNode;
+}
+
+export interface DiceComponents {
+  Root(props: DiceRootProps): ReactNode;
+  Values(props: DiceValuesProps): ReactNode;
+}
+
+const DiceContext = createContext<DiceState | null>(null);
+
+export function normalizeDiceState({
+  values,
+  count = 2,
+}: {
+  values?: readonly DiceValue[] | null;
+  count?: number;
+}): DiceState {
+  const normalizedValues = values?.map((value) => value ?? undefined);
+  const allRolled =
+    normalizedValues?.every((value) => value !== undefined) ?? false;
+  const sum = allRolled
+    ? normalizedValues?.reduce<number>(
+        (total, value) => total + (value ?? 0),
+        0,
+      )
+    : undefined;
+
+  return {
+    values: normalizedValues,
+    sum,
+    diceCount: normalizedValues?.length ?? count,
+    allRolled,
+  };
+}
+
+export function DiceRoot({ values, count, children }: DiceRootProps) {
+  return (
+    <DiceContext.Provider value={normalizeDiceState({ values, count })}>
+      {children}
+    </DiceContext.Provider>
+  );
+}
+
+export function useDicePrimitiveContext(): DiceState {
+  const value = useContext(DiceContext);
+  if (!value) {
+    throw new Error("Dice primitives must be rendered inside <Dice.Root>.");
+  }
+  return value;
+}
+
+export function DiceValues({ children }: DiceValuesProps) {
+  return children(useDicePrimitiveContext());
+}
+
+export const Dice: DiceComponents = {
+  Root: DiceRoot,
+  Values: DiceValues,
+};

package/src/primitives/game.test.tsx

@@ -0,0 +1,98 @@
+import { expect, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import type { PluginStateSnapshot } from "../types/plugin-state.js";
+import type { PluginSessionState, RuntimeAPI } from "../types/runtime-api.js";
+import { Game } from "./game.js";
+import { GameUIProvider } from "./game-ui-provider.js";
+
+function createSessionState(
+  overrides: Partial<PluginSessionState> = {},
+): PluginSessionState {
+  return {
+    status: "ready",
+    sessionId: "session-1",
+    controllablePlayerIds: ["player-1", "player-2"],
+    controllingPlayerId: "player-1",
+    userId: "user-1",
+    ...overrides,
+  };
+}
+
+function createSnapshot(): PluginStateSnapshot {
+  return {
+    view: {
+      score: 7,
+    },
+    gameplay: {
+      currentPhase: "playing",
+      currentStage: "main",
+      activePlayers: ["player-2"],
+      zones: {},
+      availableInteractions: [],
+    },
+    lobby: {
+      hostUserId: "user-1",
+      canStart: true,
+      seats: [
+        {
+          playerId: "player-1",
+          displayName: "Ada",
+          playerColor: "#d04848",
+          isHost: true,
+        },
+        {
+          playerId: "player-2",
+          displayName: "Grace",
+          playerColor: "#2d5da1",
+        },
+      ],
+    },
+    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("Game.Root projects typed author-facing game, player, and turn state", () => {
+  const runtime = createRuntime(createSnapshot());
+
+  const html = renderToString(
+    <GameUIProvider runtime={runtime}>
+      <Game.Root<{ score: number }, "player-1" | "player-2", "playing">>
+        {({ view, phase, stage, me, players, turn }) => (
+          <section>
+            <span>score:{view.score}</span>
+            <span>phase:{phase}</span>
+            <span>stage:{stage}</span>
+            <span>me:{me.player?.name}</span>
+            <span>current:{players.current?.name}</span>
+            <span>active:{turn.currentPlayerId}</span>
+            <span>mine:{String(turn.isMine)}</span>
+            <span>entries:{players.entries.length}</span>
+          </section>
+        )}
+      </Game.Root>
+    </GameUIProvider>,
+  ).replace(/<!-- -->/g, "");
+
+  expect(html).toContain("score:7");
+  expect(html).toContain("phase:playing");
+  expect(html).toContain("stage:main");
+  expect(html).toContain("me:Ada");
+  expect(html).toContain("current:Grace");
+  expect(html).toContain("active:player-2");
+  expect(html).toContain("mine:false");
+  expect(html).toContain("entries:2");
+});