@dreamboard-games/ui-sdk 0.0.41

package/src/defaults/components.tsx

@@ -0,0 +1,442 @@
+import type {
+  CSSProperties,
+  HTMLAttributes,
+  ReactNode,
+  SelectHTMLAttributes,
+} from "react";
+import {
+  Interaction,
+  Prompt,
+  PromptInbox,
+  Zone,
+  renderPrimitive,
+  useInteractionPrimitiveContext,
+  useZonePrimitiveContext,
+  type InteractionRootProps,
+  type PrimitiveCommonProps,
+} from "../primitives/index.js";
+import type {
+  InteractionDescriptor,
+  InteractionInputDescriptor,
+} from "../types/plugin-state.js";
+import type {
+  InteractionInputKey,
+  InteractionKey,
+  ZoneKey,
+} from "../ui-contract.js";
+import { useSeatInbox } from "../hooks/useSeatInbox.js";
+
+type LayoutPrimitiveProps = PrimitiveCommonProps & HTMLAttributes<HTMLElement>;
+
+function layoutStyle(
+  base: CSSProperties,
+  style: CSSProperties | undefined,
+): CSSProperties {
+  return style ? { ...base, ...style } : base;
+}
+
+export function GameLayoutRoot({
+  children,
+  style,
+  ...props
+}: LayoutPrimitiveProps) {
+  return renderPrimitive("div", {
+    ...props,
+    "data-dreamboard-game-layout": "",
+    style: layoutStyle(
+      {
+        display: "grid",
+        gridTemplateColumns: "minmax(0, 1fr) minmax(18rem, 24rem)",
+        gridTemplateRows: "auto minmax(0, 1fr) auto",
+        gridTemplateAreas: `"header header" "board sidebar" "bottom sidebar"`,
+        minHeight: "100%",
+        gap: "1rem",
+      },
+      style,
+    ),
+    children,
+  });
+}
+
+export function GameLayoutHeader({
+  children,
+  style,
+  ...props
+}: LayoutPrimitiveProps) {
+  return renderPrimitive("header", {
+    ...props,
+    "data-dreamboard-game-layout-header": "",
+    style: layoutStyle({ gridArea: "header" }, style),
+    children,
+  });
+}
+
+export function GameLayoutBoard({
+  children,
+  style,
+  ...props
+}: LayoutPrimitiveProps) {
+  return renderPrimitive("section", {
+    ...props,
+    "data-dreamboard-game-layout-board": "",
+    style: layoutStyle({ gridArea: "board", minWidth: 0 }, style),
+    children,
+  });
+}
+
+export function GameLayoutSidebar({
+  children,
+  style,
+  ...props
+}: LayoutPrimitiveProps) {
+  return renderPrimitive("aside", {
+    ...props,
+    "data-dreamboard-game-layout-sidebar": "",
+    style: layoutStyle(
+      {
+        gridArea: "sidebar",
+        minWidth: 0,
+        display: "flex",
+        flexDirection: "column",
+        gap: "0.75rem",
+      },
+      style,
+    ),
+    children,
+  });
+}
+
+export function GameLayoutBottom({
+  children,
+  style,
+  ...props
+}: LayoutPrimitiveProps) {
+  return renderPrimitive("section", {
+    ...props,
+    "data-dreamboard-game-layout-bottom": "",
+    style: layoutStyle({ gridArea: "bottom", minWidth: 0 }, style),
+    children,
+  });
+}
+
+export const GameLayout = {
+  Root: GameLayoutRoot,
+  Header: GameLayoutHeader,
+  Board: GameLayoutBoard,
+  Sidebar: GameLayoutSidebar,
+  Bottom: GameLayoutBottom,
+};
+
+export interface DefaultPromptInboxProps extends PrimitiveCommonProps {
+  empty?: ReactNode;
+  renderPrompt?: (prompt: InteractionDescriptor) => ReactNode;
+}
+
+export function DefaultPromptInbox({
+  empty = "No available prompts.",
+  renderPrompt,
+  ...props
+}: DefaultPromptInboxProps) {
+  return (
+    <PromptInbox.Root>
+      {renderPrimitive("section", {
+        ...props,
+        "data-dreamboard-default-prompt-inbox": "",
+        children: (
+          <>
+            <PromptInbox.Empty>{empty}</PromptInbox.Empty>
+            <PromptInbox.Items>
+              {(prompt) =>
+                renderPrompt ? (
+                  renderPrompt(prompt)
+                ) : (
+                  <Prompt.Root
+                    key={prompt.interactionKey}
+                    interaction={prompt.interactionKey}
+                  >
+                    <Prompt.Title />
+                    <Prompt.Message />
+                    <div data-dreamboard-default-prompt-options="">
+                      <Prompt.Options />
+                    </div>
+                  </Prompt.Root>
+                )
+              }
+            </PromptInbox.Items>
+          </>
+        ),
+      })}
+    </PromptInbox.Root>
+  );
+}
+
+export interface DefaultInteractionListProps extends PrimitiveCommonProps {
+  empty?: ReactNode;
+  includeUnavailable?: boolean;
+  renderInteraction?: (interaction: InteractionDescriptor) => ReactNode;
+}
+
+export function DefaultInteractionList({
+  empty = null,
+  includeUnavailable = false,
+  renderInteraction,
+  ...props
+}: DefaultInteractionListProps) {
+  const inbox = useSeatInbox();
+  const interactions = (inbox.bySurface.panel ?? []).filter(
+    (descriptor) => includeUnavailable || descriptor.available,
+  );
+  if (interactions.length === 0) return <>{empty}</>;
+
+  return renderPrimitive("section", {
+    ...props,
+    "data-dreamboard-default-interaction-list": "",
+    children: interactions.map((descriptor) =>
+      renderInteraction ? (
+        renderInteraction(descriptor)
+      ) : (
+        <DefaultInteractionItem
+          key={descriptor.interactionKey}
+          interaction={descriptor.interactionKey}
+        />
+      ),
+    ),
+  });
+}
+
+export type DefaultInteractionItemProps<
+  InteractionKeyValue extends string = InteractionKey,
+> = Omit<InteractionRootProps<InteractionKeyValue>, "children"> &
+  PrimitiveCommonProps;
+
+export function DefaultInteractionItem<
+  InteractionKeyValue extends string = InteractionKey,
+>({
+  interaction,
+  unavailable,
+  ...props
+}: DefaultInteractionItemProps<InteractionKeyValue>) {
+  return (
+    <Interaction.Root interaction={interaction} unavailable={unavailable}>
+      {renderPrimitive("article", {
+        ...props,
+        "data-dreamboard-default-interaction-item": "",
+        children: (
+          <>
+            <Interaction.Label />
+            <Interaction.UnavailableMessage />
+            <DefaultInteractionForm />
+          </>
+        ),
+      })}
+    </Interaction.Root>
+  );
+}
+
+export interface DefaultInteractionFormProps extends PrimitiveCommonProps {
+  submitLabel?: ReactNode;
+  renderField?: (input: InteractionInputDescriptor) => ReactNode;
+}
+
+export function DefaultInteractionForm({
+  submitLabel = "Submit",
+  renderField,
+  ...props
+}: DefaultInteractionFormProps) {
+  const { descriptor } = useInteractionPrimitiveContext();
+  const fields = descriptor?.inputs ?? [];
+  return renderPrimitive("div", {
+    ...props,
+    "data-dreamboard-default-interaction-form": "",
+    children: (
+      <>
+        {fields.map((input) =>
+          renderField ? (
+            renderField(input)
+          ) : (
+            <DefaultInteractionField key={input.key} input={input} />
+          ),
+        )}
+        <Interaction.ValidationMessage />
+        <Interaction.Submit>{submitLabel}</Interaction.Submit>
+      </>
+    ),
+  });
+}
+
+function DefaultInteractionField({
+  input,
+}: {
+  input: InteractionInputDescriptor;
+}) {
+  if (input.domain.type === "choice") {
+    return <DefaultChoiceField input={input} />;
+  }
+  if (input.domain.type === "boundedNumber") {
+    return (
+      <label data-dreamboard-default-interaction-field="">
+        {input.key}
+        <Interaction.Input
+          name={input.key}
+          type="number"
+          min={input.domain.min}
+          max={input.domain.max}
+          step={input.domain.step}
+          parse={(value) => Number(value)}
+        />
+      </label>
+    );
+  }
+  return (
+    <label data-dreamboard-default-interaction-field="">
+      {input.key}
+      <Interaction.Input name={input.key} />
+    </label>
+  );
+}
+
+function DefaultChoiceField({ input }: { input: InteractionInputDescriptor }) {
+  const { handle } = useInteractionPrimitiveContext();
+  const value = handle?.draft[input.key] ?? handle?.values[input.key];
+  return (
+    <label data-dreamboard-default-interaction-field="">
+      {input.key}
+      <select
+        name={input.key}
+        value={value === undefined ? "" : String(value)}
+        data-dreamboard-default-choice-input=""
+        disabled={!handle?.available}
+        onChange={(event) =>
+          handle?.setInput(input.key, event.currentTarget.value)
+        }
+      >
+        <option value="" />
+        {(input.domain.choices ?? []).map((choice) => (
+          <option
+            key={choice.value}
+            value={choice.value}
+            disabled={choice.disabled}
+          >
+            {choice.label}
+          </option>
+        ))}
+      </select>
+    </label>
+  );
+}
+
+export interface DefaultZoneProps<ZoneValue extends string = ZoneKey>
+  extends PrimitiveCommonProps {
+  zone: ZoneValue;
+  empty?: ReactNode;
+  layout?: "row" | "column" | "grid" | "fan";
+  interaction?: InteractionKey;
+  input?: InteractionInputKey;
+  renderCard?: (card: DefaultZoneCard) => ReactNode;
+}
+
+export interface DefaultZoneCard {
+  id: string;
+  serialized: string;
+  data: unknown;
+}
+
+export function DefaultZone<ZoneValue extends string = ZoneKey>({
+  zone,
+  empty = null,
+  layout = "row",
+  interaction,
+  input,
+  renderCard,
+  ...props
+}: DefaultZoneProps<ZoneValue>) {
+  const content = (
+    <Zone.Root zone={zone}>
+      <DefaultZoneList
+        empty={empty}
+        input={input}
+        layout={layout}
+        renderCard={renderCard}
+        {...props}
+      />
+    </Zone.Root>
+  );
+
+  return interaction ? (
+    <Interaction.Root interaction={interaction}>{content}</Interaction.Root>
+  ) : (
+    content
+  );
+}
+
+function DefaultZoneList({
+  empty,
+  input,
+  layout = "row",
+  renderCard,
+  style,
+  ...props
+}: Omit<DefaultZoneProps<string>, "zone" | "interaction">) {
+  const { snapshot } = useZonePrimitiveContext();
+  const cardIds = snapshot?.cardIds ?? [];
+  if (cardIds.length === 0) return <>{empty}</>;
+
+  return (
+    <Zone.List
+      {...props}
+      data-dreamboard-default-zone=""
+      data-layout={layout}
+      style={layoutStyle(defaultZoneLayoutStyle(layout), style)}
+    >
+      {cardIds.map((cardId) => {
+        const serialized = snapshot?.cardsById[cardId] ?? "";
+        const card: DefaultZoneCard = {
+          id: cardId,
+          serialized,
+          data: parseCardData(serialized),
+        };
+        const body = renderCard ? renderCard(card) : card.id;
+        return (
+          <Zone.Item key={cardId} card={cardId}>
+            {input ? (
+              <Interaction.CardInput input={input} card={cardId}>
+                {body}
+              </Interaction.CardInput>
+            ) : (
+              body
+            )}
+          </Zone.Item>
+        );
+      })}
+    </Zone.List>
+  );
+}
+
+function defaultZoneLayoutStyle(
+  layout: NonNullable<DefaultZoneProps["layout"]>,
+): CSSProperties {
+  if (layout === "grid") {
+    return {
+      display: "grid",
+      gridTemplateColumns: "repeat(auto-fit, minmax(5rem, 1fr))",
+      gap: "0.5rem",
+    };
+  }
+  return {
+    display: "flex",
+    flexDirection: layout === "column" ? "column" : "row",
+    flexWrap: layout === "fan" ? "nowrap" : "wrap",
+    gap: "0.5rem",
+  };
+}
+
+function parseCardData(serialized: string): unknown {
+  if (!serialized) return null;
+  try {
+    return JSON.parse(serialized);
+  } catch {
+    return serialized;
+  }
+}
+
+export type DefaultChoiceInputProps = SelectHTMLAttributes<HTMLSelectElement>;

package/src/defaults/defaults.test.tsx

@@ -0,0 +1,230 @@
+import { expect, test } from "bun:test";
+import type { ReactElement } from "react";
+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 { GameUIProvider } from "../primitives/game-ui-provider.js";
+import {
+  DefaultInteractionList,
+  DefaultPromptInbox,
+  DefaultZone,
+  GameLayout,
+} from "./index.js";
+
+function createSessionState(): PluginSessionState {
+  return {
+    status: "ready",
+    sessionId: "session-1",
+    controllablePlayerIds: ["player-1"],
+    controllingPlayerId: "player-1",
+    userId: "user-1",
+  };
+}
+
+function createSnapshot(
+  overrides: Partial<PluginStateSnapshot["gameplay"]> = {},
+): PluginStateSnapshot {
+  return {
+    view: {},
+    gameplay: {
+      currentPhase: "setup",
+      currentStage: null,
+      activePlayers: ["player-1"],
+      availableInteractions: [],
+      zones: {},
+      ...overrides,
+    },
+    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;
+}
+
+function renderWithRuntime(
+  gameplay: Partial<PluginStateSnapshot["gameplay"]>,
+  element: ReactElement,
+): string {
+  const runtime = createRuntime(createSnapshot(gameplay));
+  return renderToString(
+    <GameUIProvider runtime={runtime}>{element}</GameUIProvider>,
+  );
+}
+
+test("DefaultPromptInbox composes PromptInbox and Prompt primitives", () => {
+  const prompt: InteractionDescriptor = {
+    phaseName: "trading",
+    interactionKey: "trading.respond",
+    interactionId: "respond",
+    kind: "prompt",
+    inputs: [
+      {
+        key: "response",
+        kind: "choice",
+        domain: {
+          type: "choice",
+          choices: [
+            { value: "accept", label: "Accept" },
+            { value: "decline", label: "Decline" },
+          ],
+        },
+      },
+    ],
+    commit: { mode: "manual" },
+    available: true,
+    context: {
+      to: "player-1",
+      title: "Trade offer",
+      payload: { message: "Two wheat for one ore?" },
+      options: [
+        { id: "accept", label: "Accept" },
+        { id: "decline", label: "Decline" },
+      ],
+    },
+  };
+
+  const html = renderWithRuntime(
+    { availableInteractions: [prompt] },
+    <DefaultPromptInbox />,
+  );
+
+  expect(html).toContain('data-dreamboard-default-prompt-inbox=""');
+  expect(html).toContain("Trade offer");
+  expect(html).toContain("Two wheat for one ore?");
+  expect(html).toContain('data-dreamboard-prompt-option=""');
+  expect(html).toContain('data-option-value="accept"');
+});
+
+test("DefaultInteractionList renders action items without descriptor style metadata", () => {
+  const ready: InteractionDescriptor = {
+    phaseName: "setup",
+    interactionKey: "setup.ready",
+    interactionId: "ready",
+    kind: "action",
+    inputs: [],
+    commit: { mode: "manual" },
+    available: true,
+  };
+  const chooseMode: InteractionDescriptor = {
+    phaseName: "setup",
+    interactionKey: "setup.chooseMode",
+    interactionId: "chooseMode",
+    kind: "action",
+    inputs: [
+      {
+        key: "mode",
+        kind: "choice",
+        domain: {
+          type: "choice",
+          choices: [
+            { value: "fast", label: "Fast" },
+            { value: "careful", label: "Careful" },
+          ],
+        },
+      },
+    ],
+    commit: { mode: "manual" },
+    available: true,
+  };
+
+  const html = renderWithRuntime(
+    { availableInteractions: [ready, chooseMode] },
+    <DefaultInteractionList />,
+  );
+
+  expect(html).toContain('data-dreamboard-default-interaction-list=""');
+  expect(html).toContain('data-dreamboard-default-interaction-item=""');
+  expect(html).toContain("Ready");
+  expect(html).toContain("Choose Mode");
+  expect(html).toContain('data-dreamboard-default-choice-input=""');
+  expect(html).toContain("Careful");
+  expect(html).not.toContain("data-surface=");
+});
+
+test("DefaultZone composes Zone items with Interaction.CardInput", () => {
+  const passCards: InteractionDescriptor = {
+    phaseName: "passing",
+    interactionKey: "passing.passCards",
+    interactionId: "passCards",
+    kind: "action",
+    zoneId: "hand",
+    inputs: [
+      {
+        key: "cardIds",
+        kind: "card",
+        domain: {
+          type: "target",
+          targetKind: "card",
+          eligibleTargets: ["card-1"],
+          selection: { mode: "many", min: 1, max: 3, distinct: true },
+        },
+      },
+    ],
+    commit: { mode: "manual" },
+    available: true,
+  };
+
+  const html = renderWithRuntime(
+    {
+      availableInteractions: [passCards],
+      zones: {
+        hand: {
+          cardIds: ["card-1"],
+          cardsById: { "card-1": '{"name":"Copper"}' },
+          playableByCardId: { "card-1": [passCards] },
+        },
+      },
+    },
+    <DefaultZone
+      zone="hand"
+      interaction="passing.passCards"
+      input="cardIds"
+      renderCard={(card) =>
+        typeof card.data === "object" &&
+        card.data !== null &&
+        "name" in card.data
+          ? String(card.data.name)
+          : card.id
+      }
+    />,
+  );
+
+  expect(html).toContain('data-dreamboard-zone-root=""');
+  expect(html).toContain('data-dreamboard-default-zone=""');
+  expect(html).toContain('data-dreamboard-interaction-card-input=""');
+  expect(html).toContain('data-card-id="card-1"');
+  expect(html).toContain("Copper");
+});
+
+test("GameLayout exposes Radix-style layout parts and asChild composition", () => {
+  const html = renderToString(
+    <GameLayout.Root className="root">
+      <GameLayout.Board asChild className="board">
+        <main className="custom-board">Board</main>
+      </GameLayout.Board>
+      <GameLayout.Sidebar>Sidebar</GameLayout.Sidebar>
+      <GameLayout.Bottom>Bottom</GameLayout.Bottom>
+    </GameLayout.Root>,
+  );
+
+  expect(html).toContain('data-dreamboard-game-layout=""');
+  expect(html).toContain('data-dreamboard-game-layout-board=""');
+  expect(html).toContain('class="board custom-board"');
+  expect(html).toContain('data-dreamboard-game-layout-sidebar=""');
+  expect(html).toContain('data-dreamboard-game-layout-bottom=""');
+});

package/src/defaults/index.ts

@@ -0,0 +1 @@
+export * from "./components.js";

package/src/errors/ValidationError.ts

@@ -0,0 +1,29 @@
+/**
+ * Error thrown when action validation fails.
+ * Contains the error code and optional message from the validation result.
+ */
+export class ValidationError extends Error {
+  constructor(
+    public readonly errorCode?: string,
+    message?: string,
+  ) {
+    super(message || errorCode || "Validation failed");
+    this.name = "ValidationError";
+  }
+}
+
+export function validationErrorFromUnknown(
+  error: unknown,
+  fallbackMessage = "Interaction submission failed",
+): ValidationError {
+  if (error instanceof ValidationError) return error;
+  const errorCode =
+    typeof error === "object" &&
+    error !== null &&
+    "errorCode" in error &&
+    typeof error.errorCode === "string"
+      ? error.errorCode
+      : undefined;
+  const message = error instanceof Error ? error.message : fallbackMessage;
+  return new ValidationError(errorCode, message);
+}