@dreamboard-games/ui-sdk 0.0.41

package/src/components/index.ts

@@ -0,0 +1,208 @@
+/** Reducer-native UI primitives for building game interfaces. */
+
+// Presentational components (no hooks, receive data as props)
+export { Card, type CardProps, type ViewCard } from "./Card.js";
+export { Hand, type HandProps } from "./Hand.js";
+export {
+  HandDock,
+  type HandDockMode,
+  type HandDockPlacement,
+  type HandDockPresentation,
+  type HandDockProps,
+  type HandDockToggleContext,
+} from "./HandDock.js";
+export { PlayArea, type PlayAreaProps } from "./PlayArea.js";
+
+// Other UI components
+export { GameSkeleton, type GameSkeletonProps } from "./GameSkeleton.js";
+export {
+  ToastProvider,
+  useToast,
+  type Toast,
+  type ToastType,
+} from "./Toast.js";
+export { ErrorBoundary, type ErrorBoundaryProps } from "./ErrorBoundary.js";
+export { PluginRuntime, type PluginRuntimeProps } from "./PluginRuntime.js";
+export {
+  Drawer,
+  DrawerPortal,
+  DrawerOverlay,
+  DrawerTrigger,
+  DrawerClose,
+  DrawerContent,
+  DrawerHeader,
+  DrawerFooter,
+  DrawerTitle,
+  DrawerDescription,
+} from "./Drawer.js";
+export {
+  Dialog,
+  DialogPortal,
+  DialogOverlay,
+  DialogTrigger,
+  DialogClose,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+  DialogTitle,
+  DialogDescription,
+} from "../internal/ui/dialog.js";
+
+// Game UI primitives (SDK v0.1.0+)
+export {
+  ResourceCounter,
+  type ResourceCounterProps,
+  type ResourceDisplayConfig,
+} from "./ResourceCounter.js";
+export {
+  CostDisplay,
+  type CostDisplayProps,
+  type ResourceDefinition,
+} from "./CostDisplay.js";
+export { ActionButton, type ActionButtonProps } from "./ActionButton.js";
+export { PrimaryButton, type PrimaryButtonProps } from "./PrimaryButton.js";
+export { ThemedButton, type ThemedButtonProps } from "./ThemedButton.js";
+export {
+  PrimaryActionButton,
+  type PrimaryActionButtonProps,
+  type PrimaryActionAttention,
+} from "./PrimaryActionButton.js";
+export {
+  InteractionForm,
+  InteractionField,
+  defaultFormInputs,
+  hasDefaultInteractionFormFields,
+  type InteractionFieldProps,
+  type InteractionFieldRenderMap,
+  type InteractionFieldRenderProps,
+  type InteractionFormProps,
+} from "./InteractionForm.js";
+export {
+  ActionPanel,
+  ActionGroup,
+  type ActionPanelProps,
+  type ActionGroupProps,
+} from "./ActionPanel.js";
+export { MoreActions, type MoreActionsProps } from "./MoreActions.js";
+export { DiceRoller, type DiceRollerProps } from "./DiceRoller.js";
+export { PhaseIndicator, type PhaseIndicatorProps } from "./PhaseIndicator.js";
+export {
+  GameEndDisplay,
+  type GameEndDisplayProps,
+  type PlayerScore,
+} from "./GameEndDisplay.js";
+export {
+  PromptDialogHost,
+  type PromptDialogHostProps,
+} from "./PromptDialogHost.js";
+
+// Board primitives (SDK v0.2.0+)
+export {
+  NetworkGraph,
+  DefaultNetworkNode,
+  DefaultNetworkEdge,
+  DefaultNetworkPiece,
+  type NetworkGraphProps,
+  type NetworkNode,
+  type NetworkEdge,
+  type NetworkPiece,
+  type DefaultNetworkNodeProps,
+  type DefaultNetworkEdgeProps,
+  type DefaultNetworkPieceProps,
+} from "./board/NetworkGraph.js";
+
+export {
+  ZoneMap,
+  DefaultZone,
+  DefaultZonePieces,
+  DefaultZonePiece,
+  type ZoneMapProps,
+  type ZoneDefinition,
+  type ZonePiece,
+  type ZoneShape,
+  type ZoneHighlightType,
+  type DefaultZoneProps,
+  type DefaultZonePiecesProps,
+  type DefaultZonePieceProps,
+} from "./board/ZoneMap.js";
+
+export {
+  TrackBoard,
+  DefaultTrackSpace,
+  DefaultTrackPiece,
+  DefaultTrackConnection,
+  DefaultTrackJump,
+  type TrackBoardProps,
+  type TrackSpace,
+  type TrackPiece,
+  type DefaultTrackSpaceProps,
+  type DefaultTrackPieceProps,
+  type DefaultTrackConnectionProps,
+  type DefaultTrackJumpProps,
+} from "./board/TrackBoard.js";
+
+export {
+  SlotSystem,
+  DefaultSlotItem,
+  DefaultSlotOccupant,
+  DefaultEmptySlot,
+  type SlotSystemProps,
+  type SlotDefinition,
+  type SlotOccupant,
+  type DefaultSlotItemProps,
+  type DefaultSlotOccupantProps,
+  type DefaultEmptySlotProps,
+} from "./board/SlotSystem.js";
+
+export {
+  SquareGrid,
+  DefaultGridCell,
+  DefaultGridPiece,
+  DefaultChessPiece,
+  toAlgebraic,
+  toNumeric,
+  type SquareGridBoardProps,
+  type SquareGridProps,
+  type InteractiveSquareEdge,
+  type InteractiveSquareVertex,
+  type SquareEdgePosition,
+  type SquareVertexPosition,
+  type DefaultGridCellProps,
+  type DefaultGridPieceProps,
+  type DefaultChessPieceProps,
+} from "./board/SquareGrid.js";
+
+export {
+  HexGrid,
+  hexUtils,
+  DefaultHexTile,
+  DefaultHexEdge,
+  DefaultHexVertex,
+  type HexGridBoardProps,
+  type HexGridProps,
+  type HexOrientation,
+  type HexTileGeometry,
+  type InteractiveHexEdge,
+  type InteractiveHexVertex,
+  type InteractiveTargetLayer,
+  type InteractiveTargetRenderState,
+  type EdgePosition,
+  type DefaultHexTileProps,
+  type DefaultHexEdgeProps,
+  type DefaultHexVertexProps,
+} from "./board/HexGrid.js";
+export {
+  createHexBoardView,
+  type HexBoardView,
+  type HexBoardViewTile,
+} from "./board/hex-board-view.js";
+export type {
+  HexTileState,
+  HexEdgeState,
+  HexVertexState,
+  SquareCellState,
+  SquareEdgeState,
+  SquarePieceState,
+  SquareVertexState,
+} from "../types/player-state.js";
+export type { CardCollection, ViewSlotOccupant } from "@dreamboard/sdk-types";

package/src/components/interaction-dialog-behavior.test.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "bun:test";
+import { resolveDialogDismissBehavior } from "./interaction-dialog-behavior.js";
+
+test("resolveDialogDismissBehavior prefers structured dismissBehavior", () => {
+  expect(
+    resolveDialogDismissBehavior({
+      dismissBehavior: {
+        type: "minimize",
+        trayLabel: "Trade",
+        trayIcon: "🤝",
+      },
+    }),
+  ).toEqual({
+    type: "minimize",
+    trayLabel: "Trade",
+    trayIcon: "🤝",
+  });
+});
+
+test("resolveDialogDismissBehavior defaults to non-dismissible", () => {
+  expect(resolveDialogDismissBehavior({})).toEqual({ type: "none" });
+  expect(resolveDialogDismissBehavior(undefined)).toEqual({ type: "none" });
+});

package/src/components/interaction-dialog-behavior.ts

@@ -0,0 +1,22 @@
+export type InteractionDialogDismissBehavior =
+  | { type: "none" }
+  | { type: "dismiss" }
+  | { type: "minimize"; trayLabel: string; trayIcon?: string };
+
+export interface InteractionDialogPresentation {
+  dismissBehavior?: InteractionDialogDismissBehavior;
+}
+
+export function resolveDialogDismissBehavior(
+  dialog: InteractionDialogPresentation | undefined,
+): InteractionDialogDismissBehavior {
+  const dismissBehavior = dialog?.dismissBehavior;
+  if (dismissBehavior) return dismissBehavior;
+  return { type: "none" };
+}
+
+export function canCloseDialog(
+  dismissBehavior: InteractionDialogDismissBehavior,
+): boolean {
+  return dismissBehavior.type !== "none";
+}

package/src/components/surfaces/BlockerSurface.test.tsx

@@ -0,0 +1,158 @@
+import { expect, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import { RuntimeContext } from "../../context/RuntimeContext.js";
+import { PluginSessionContext } from "../../context/PluginSessionContext.js";
+import type {
+  InteractionDescriptor,
+  PluginStateSnapshot,
+} from "../../types/plugin-state.js";
+import type {
+  PluginSessionState,
+  RuntimeAPI,
+} from "../../types/runtime-api.js";
+import { BlockerSurface } from "./BlockerSurface.js";
+
+function createSessionState(): PluginSessionState {
+  return {
+    status: "ready",
+    sessionId: "session-1",
+    controllablePlayerIds: ["player-1"],
+    controllingPlayerId: "player-1",
+    userId: "user-1",
+  };
+}
+
+function createBlockerDescriptor(
+  id: string,
+  available: boolean,
+  overrides: Partial<InteractionDescriptor> = {},
+): InteractionDescriptor {
+  return {
+    phaseName: "takeTurn",
+    interactionKey: `takeTurn.${id}`,
+    interactionId: id,
+    kind: "action",
+    inputs: [],
+    commit: { mode: "manual" },
+    available,
+    ...overrides,
+  };
+}
+
+function createSnapshot(
+  session: PluginSessionState,
+  descriptors: InteractionDescriptor[],
+): PluginStateSnapshot {
+  return {
+    view: null,
+    gameplay: {
+      currentPhase: "takeTurn",
+      currentStage: null,
+      activePlayers: ["player-1"],
+      availableInteractions: descriptors,
+      zones: {},
+    },
+    lobby: null,
+    notifications: [],
+    session,
+    history: null,
+    syncId: 1,
+  };
+}
+
+function createRuntime(snapshot: PluginStateSnapshot): RuntimeAPI & {
+  getSnapshot: () => PluginStateSnapshot;
+  subscribeToState: (
+    listener: (state: PluginStateSnapshot) => void,
+  ) => () => void;
+} {
+  return {
+    validateInteraction: async () => ({ valid: true }),
+    submitInteraction: async () => undefined,
+    getSessionState: () => snapshot.session,
+    disconnect: () => undefined,
+    getSnapshot: () => snapshot,
+    subscribeToState: () => () => undefined,
+  };
+}
+
+function renderShell(snapshot: PluginStateSnapshot): string {
+  const runtime = createRuntime(snapshot);
+  return renderToString(
+    <RuntimeContext.Provider value={runtime}>
+      <PluginSessionContext.Provider value={snapshot.session}>
+        <BlockerSurface />
+      </PluginSessionContext.Provider>
+    </RuntimeContext.Provider>,
+  );
+}
+
+// Regression: blocker-surface interactions whose `available` predicate is
+// false must not escalate into a modal overlay. Without this filter an
+// interaction like Catan's `discardCards`, which is surfaced as a blocker
+// but only addresses specific seats, would render an un-dismissable prompt
+// for every other active player.
+test("BlockerSurface hides descriptors where available is false", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createBlockerDescriptor("discardCards", false),
+  ]);
+
+  const html = renderShell(snapshot);
+
+  expect(html).not.toContain("discardCards");
+  expect(html).not.toContain('data-surface="blocker"');
+});
+
+test("BlockerSurface does not infer blocking overlays from plain action descriptors", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createBlockerDescriptor("mustDiscard", true),
+  ]);
+
+  const html = renderShell(snapshot);
+
+  expect(html).not.toContain("mustDiscard");
+  expect(html).not.toContain('data-surface="blocker"');
+});
+
+test("BlockerSurface ignores action descriptors after reducer-owned blocker surfaces are removed", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createBlockerDescriptor("skipMe", false),
+    createBlockerDescriptor("showMe", true),
+  ]);
+
+  const html = renderShell(snapshot);
+
+  expect(html).not.toContain("skipMe");
+  expect(html).not.toContain("showMe");
+});
+
+test("BlockerSurface does not escalate form actions into blocking overlays", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createBlockerDescriptor("discardCards", true, {
+      inputs: [
+        {
+          key: "discard",
+          kind: "form",
+          domain: {
+            type: "resourceMap",
+            resources: [
+              { resourceId: "wood", label: "Wood", min: 0, max: 4 },
+              { resourceId: "brick", label: "Brick", min: 0, max: 4 },
+            ],
+          },
+        },
+      ],
+    }),
+  ]);
+
+  const html = renderShell(snapshot);
+
+  expect(html).not.toContain('data-surface="blocker"');
+  expect(html).not.toContain('data-interaction-form="true"');
+  expect(html).not.toContain("Wood");
+  expect(html).not.toContain("Brick");
+});

package/src/components/surfaces/BlockerSurface.tsx

@@ -0,0 +1,127 @@
+import type { ReactNode } from "react";
+import { useSeatInbox } from "../../hooks/useSeatInbox.js";
+import {
+  useInteractionHandle,
+  type InteractionHandle,
+} from "../../hooks/useInteractionHandle.js";
+import { useTheme } from "../../theme/ThemeProvider.js";
+import type { InteractionDescriptor } from "../../types/plugin-state.js";
+import { DefaultInteractionButton } from "./internal/DefaultInteractionButton.js";
+import type {
+  InteractionDefaultedKeysOf,
+  InteractionParamsByKeyShape,
+  InteractionParamsOf,
+  SurfaceRenderMap,
+} from "./types.js";
+
+export interface BlockerSurfaceProps<
+  I extends string = never,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+> {
+  /**
+   * Optional per-interaction overrides. Omit to fall back to the default
+   * `DefaultInteractionButton` inside the blocker overlay.
+   */
+  render?: SurfaceRenderMap<I, ParamsByKey>;
+  /**
+   * Fallback renderer for blocker interactions without a `render` entry.
+   * Defaults to the built-in `DefaultInteractionButton`.
+   */
+  renderItem?: (
+    descriptor: InteractionDescriptor<I>,
+    handle: InteractionHandle<
+      InteractionParamsOf<ParamsByKey, I>,
+      InteractionDefaultedKeysOf<ParamsByKey, I>
+    >,
+  ) => ReactNode;
+  /** Shown when no blocker interactions are addressed to the controlling seat. */
+  empty?: ReactNode;
+}
+
+/**
+ * Default renderer for legacy blocker interactions. Rendered as a layout-less
+ * item list; callers decide whether to mount it inline or wrap it in their own
+ * overlay container.
+ *
+ * Visual styling is sourced entirely from the active {@link useTheme}.
+ */
+export function BlockerSurface<
+  I extends string = never,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+>({ render, renderItem, empty = null }: BlockerSurfaceProps<I, ParamsByKey>) {
+  const theme = useTheme();
+  const inbox = useSeatInbox();
+  // Blocker semantics: only mount descriptors that are *actually blocking*.
+  // An unavailable blocker (e.g. `discardCards` when this seat is not on the
+  // discard list) must not escalate into a modal overlay — that would block
+  // the UI with no valid action to dismiss it.
+  const items = (
+    (inbox.bySurface.blocker ?? []) as ReadonlyArray<InteractionDescriptor<I>>
+  ).filter((descriptor) => descriptor.available !== false);
+  if (items.length === 0) return <>{empty}</>;
+  return (
+    <div
+      role="alertdialog"
+      aria-modal="true"
+      aria-label="Blocking interaction"
+      data-surface="blocker"
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: theme.space[3],
+        alignItems: "stretch",
+      }}
+    >
+      {items.map((descriptor) => (
+        <BlockerItem<I, ParamsByKey>
+          key={descriptor.interactionKey}
+          descriptor={descriptor}
+          render={render}
+          renderItem={renderItem}
+        />
+      ))}
+    </div>
+  );
+}
+
+function BlockerItem<
+  I extends string,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+>({
+  descriptor,
+  render,
+  renderItem,
+}: {
+  descriptor: InteractionDescriptor<I>;
+  render?: SurfaceRenderMap<I, ParamsByKey>;
+  renderItem?: (
+    descriptor: InteractionDescriptor<I>,
+    handle: InteractionHandle<
+      InteractionParamsOf<ParamsByKey, I>,
+      InteractionDefaultedKeysOf<ParamsByKey, I>
+    >,
+  ) => ReactNode;
+}) {
+  const handle = useInteractionHandle<
+    InteractionParamsOf<ParamsByKey, I>,
+    InteractionDefaultedKeysOf<ParamsByKey, I>
+  >(descriptor);
+  const override = render?.[descriptor.interactionKey] as
+    | ((
+        descriptor: InteractionDescriptor<I>,
+        handle: InteractionHandle<
+          InteractionParamsOf<ParamsByKey, I>,
+          InteractionDefaultedKeysOf<ParamsByKey, I>
+        >,
+      ) => ReactNode)
+    | undefined;
+  if (override) return <>{override(descriptor, handle)}</>;
+  if (renderItem) return <>{renderItem(descriptor, handle)}</>;
+  return (
+    <DefaultInteractionButton
+      descriptor={descriptor}
+      handle={handle}
+      defaultFormOpen
+    />
+  );
+}