@dreamboard-games/ui-sdk 0.0.41

package/src/primitives/interaction.tsx

@@ -0,0 +1,405 @@
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type ButtonHTMLAttributes,
+  type HTMLAttributes,
+  type InputHTMLAttributes,
+  type ReactNode,
+} from "react";
+import { useInteractionHandle } from "../hooks/useInteractionHandle.js";
+import { useInteractionUiStore } from "../context/InteractionDraftContext.js";
+import { usePluginState } from "../context/PluginStateContext.js";
+import type { InteractionInputKey, InteractionKey } from "../ui-contract.js";
+import type { InteractionDescriptor } from "../types/plugin-state.js";
+import {
+  inputByKey,
+  isManyTargetSelectable,
+  toggleManyValue,
+} from "../utils/interaction-inputs.js";
+import { interactionLabel } from "../utils/interaction-labels.js";
+import {
+  composeEventHandlers,
+  renderPrimitive,
+  type PrimitiveCommonProps,
+} from "./primitive-props.js";
+import { useZoneCardContext } from "./zone.js";
+
+interface InteractionContextValue {
+  interaction: string;
+  descriptor: InteractionDescriptor | null;
+  handle: ReturnType<typeof useInteractionHandle> | null;
+}
+
+const InteractionContext = createContext<InteractionContextValue | null>(null);
+
+function humanizeInteraction(value: string): string {
+  const parts = value.split(".");
+  const leaf = parts[parts.length - 1] ?? value;
+  return leaf
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[-_]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/^./, (first: string) => first.toUpperCase());
+}
+
+export function useInteractionPrimitiveContext(): InteractionContextValue {
+  const value = useContext(InteractionContext);
+  if (!value) {
+    throw new Error(
+      "Interaction primitives must be rendered inside <Interaction.Root>.",
+    );
+  }
+  return value;
+}
+
+function useInteractionDescriptor(interaction: string) {
+  return usePluginState((state) =>
+    state.gameplay.availableInteractions.find(
+      (descriptor) =>
+        descriptor.interactionKey === interaction ||
+        descriptor.interactionId === interaction,
+    ),
+  );
+}
+
+export interface InteractionRootProps<
+  Interaction extends string = InteractionKey,
+> {
+  interaction: Interaction;
+  children: ReactNode;
+  unavailable?: "render" | "hide";
+}
+
+function ResolvedInteractionRoot({
+  interaction,
+  descriptor,
+  children,
+}: {
+  interaction: string;
+  descriptor: InteractionDescriptor;
+  children: ReactNode;
+}) {
+  const handle = useInteractionHandle(descriptor);
+  const value = useMemo<InteractionContextValue>(
+    () => ({ interaction, descriptor, handle }),
+    [descriptor, handle, interaction],
+  );
+  return (
+    <InteractionContext.Provider value={value}>
+      {children}
+    </InteractionContext.Provider>
+  );
+}
+
+export function InteractionRoot<Interaction extends string = InteractionKey>({
+  interaction,
+  children,
+  unavailable = "render",
+}: InteractionRootProps<Interaction>) {
+  const descriptor = useInteractionDescriptor(interaction);
+  if (!descriptor) {
+    if (unavailable === "hide") return null;
+    return (
+      <InteractionContext.Provider
+        value={{
+          interaction,
+          descriptor: null,
+          handle: null,
+        }}
+      >
+        {children}
+      </InteractionContext.Provider>
+    );
+  }
+  if (!descriptor.available && unavailable === "hide") {
+    return null;
+  }
+  return (
+    <ResolvedInteractionRoot interaction={interaction} descriptor={descriptor}>
+      {children}
+    </ResolvedInteractionRoot>
+  );
+}
+
+export type InteractionPartProps = PrimitiveCommonProps &
+  HTMLAttributes<HTMLElement>;
+
+export function InteractionLabel({ children, ...props }: InteractionPartProps) {
+  const { descriptor, interaction } = useInteractionPrimitiveContext();
+  return renderPrimitive("span", {
+    ...props,
+    "data-dreamboard-interaction-label": "",
+    children:
+      children ??
+      (descriptor
+        ? interactionLabel(descriptor)
+        : humanizeInteraction(interaction)),
+  });
+}
+
+export function InteractionDescription({
+  children,
+  ...props
+}: InteractionPartProps) {
+  const content = children;
+  if (!content) return null;
+  return renderPrimitive("span", {
+    ...props,
+    "data-dreamboard-interaction-description": "",
+    children: content,
+  });
+}
+
+export function InteractionUnavailableMessage({
+  children,
+  ...props
+}: InteractionPartProps) {
+  const { descriptor, handle } = useInteractionPrimitiveContext();
+  const reason =
+    children ?? handle?.unavailableReason ?? descriptor?.unavailableReason;
+  if (!reason) return null;
+  return renderPrimitive("span", {
+    ...props,
+    "data-dreamboard-interaction-unavailable": "",
+    children: reason,
+  });
+}
+
+export function InteractionValidationMessage({
+  children,
+  ...props
+}: InteractionPartProps) {
+  const { handle } = useInteractionPrimitiveContext();
+  const validation = handle?.validateDraft();
+  const message =
+    children ??
+    validation?.formErrors[0] ??
+    Object.values(validation?.fieldErrors ?? {})[0]?.[0] ??
+    (validation?.missing[0]
+      ? `${String(validation.missing[0])} is required.`
+      : null);
+  if (!message) return null;
+  return renderPrimitive("span", {
+    ...props,
+    "data-dreamboard-interaction-validation": "",
+    children: message,
+  });
+}
+
+export type InteractionTriggerProps = PrimitiveCommonProps &
+  ButtonHTMLAttributes<HTMLButtonElement>;
+
+export function InteractionTrigger({
+  disabled,
+  onClick,
+  ...props
+}: InteractionTriggerProps) {
+  const { descriptor, handle } = useInteractionPrimitiveContext();
+  const isDisabled = disabled === true || !descriptor?.available;
+  return renderPrimitive("button", {
+    type: "button",
+    ...props,
+    disabled: isDisabled,
+    "aria-disabled": isDisabled,
+    "data-dreamboard-interaction-trigger": "",
+    "data-interaction-id": descriptor?.interactionId,
+    "data-interaction-key": descriptor?.interactionKey,
+    "data-available": descriptor?.available ?? false,
+    "data-disabled": isDisabled || undefined,
+    "data-state": handle?.isArmed ? "armed" : "idle",
+    onClick: composeEventHandlers(onClick, () => {
+      handle?.arm();
+    }),
+  });
+}
+
+export type InteractionSubmitProps = PrimitiveCommonProps &
+  ButtonHTMLAttributes<HTMLButtonElement>;
+
+export function InteractionSubmit({
+  disabled,
+  onClick,
+  ...props
+}: InteractionSubmitProps) {
+  const { descriptor, handle } = useInteractionPrimitiveContext();
+  const isSubmitting = handle?.status === "submitting";
+  const isDisabled =
+    disabled === true ||
+    !descriptor?.available ||
+    !handle?.isReady ||
+    isSubmitting;
+  return renderPrimitive("button", {
+    type: "button",
+    ...props,
+    disabled: isDisabled,
+    "aria-disabled": isDisabled,
+    "data-dreamboard-interaction-submit": "",
+    "data-interaction-id": descriptor?.interactionId,
+    "data-interaction-key": descriptor?.interactionKey,
+    "data-available": descriptor?.available ?? false,
+    "data-disabled": isDisabled || undefined,
+    "data-ready": handle?.isReady ?? false,
+    "data-submitting": isSubmitting || undefined,
+    "data-state": handle?.status ?? "unavailable",
+    onClick: composeEventHandlers(onClick, () => {
+      void handle?.submitDraft();
+    }),
+  });
+}
+
+export type InteractionInputProps = PrimitiveCommonProps &
+  Omit<InputHTMLAttributes<HTMLInputElement>, "name"> & {
+    name: string;
+    parse?: (value: string) => unknown;
+  };
+
+export function InteractionInput({
+  name,
+  parse,
+  onChange,
+  disabled,
+  ...props
+}: InteractionInputProps) {
+  const { descriptor, handle } = useInteractionPrimitiveContext();
+  const value = handle?.draft[name];
+  const isDisabled = disabled === true || !descriptor?.available;
+  return renderPrimitive("input", {
+    ...props,
+    name,
+    disabled: isDisabled,
+    "aria-disabled": isDisabled,
+    "data-dreamboard-interaction-input": "",
+    "data-input-name": name,
+    "data-disabled": isDisabled || undefined,
+    "data-selected": value !== undefined || undefined,
+    onChange: composeEventHandlers(onChange, (event) => {
+      const target = event.currentTarget;
+      handle?.setInput(name, parse ? parse(target.value) : target.value);
+    }),
+  });
+}
+
+export type InteractionCardInputProps<
+  Input extends string = InteractionInputKey,
+> = PrimitiveCommonProps &
+  ButtonHTMLAttributes<HTMLButtonElement> & {
+    input: Input;
+    value?: string;
+    card?: string;
+    selected?: boolean;
+    onSelectedChange?: (selected: boolean) => void;
+  };
+
+export function InteractionCardInput<
+  Input extends string = InteractionInputKey,
+>({
+  input,
+  value,
+  card,
+  selected,
+  onSelectedChange,
+  onClick,
+  disabled,
+  children,
+  ...props
+}: InteractionCardInputProps<Input>) {
+  const { descriptor, handle } = useInteractionPrimitiveContext();
+  const store = useInteractionUiStore();
+  const zoneCard = useZoneCardContext();
+  const cardId = value ?? card ?? zoneCard?.cardId;
+  const cardDescriptor = usePluginState((state) => {
+    if (!cardId || !zoneCard) return undefined;
+    return state.gameplay.zones[zoneCard.zone]?.playableByCardId[cardId]?.find(
+      (candidate) =>
+        candidate.interactionKey === descriptor?.interactionKey &&
+        candidate.inputs.some((candidateInput) => candidateInput.key === input),
+    );
+  });
+  const inputDescriptor = descriptor
+    ? inputByKey(descriptor, input)
+    : undefined;
+  const liveDraft = descriptor ? store.getDraft(descriptor.interactionKey) : {};
+  const currentValue =
+    liveDraft[input] ?? handle?.draft[input] ?? handle?.values[input];
+  const selection = inputDescriptor?.domain.selection;
+  const selectedByDraft =
+    selection?.mode === "many"
+      ? Array.isArray(currentValue) &&
+        currentValue.map((item) => String(item)).includes(String(cardId))
+      : currentValue !== undefined &&
+        cardId !== undefined &&
+        String(currentValue) === String(cardId);
+  const isSelected = selected ?? selectedByDraft;
+  const eligibleTargets =
+    inputDescriptor?.domain.type === "target"
+      ? inputDescriptor.domain.eligibleTargets
+      : undefined;
+  const isCardInput =
+    inputDescriptor?.domain.type === "target" &&
+    inputDescriptor.domain.targetKind === "card";
+  const isEligible =
+    cardId !== undefined &&
+    isCardInput &&
+    (eligibleTargets === undefined || eligibleTargets.includes(cardId));
+  const isSelectable =
+    cardId !== undefined &&
+    inputDescriptor !== undefined &&
+    isManyTargetSelectable(inputDescriptor, currentValue, cardId);
+  const isCandidateAvailable = cardDescriptor?.available ?? true;
+  const validation = handle?.validateDraft();
+  const fieldErrors = validation?.fieldErrors[input] ?? [];
+  const isInvalid = fieldErrors.length > 0;
+  const isDisabled =
+    disabled === true ||
+    !descriptor?.available ||
+    !cardId ||
+    !isEligible ||
+    !handle;
+
+  return renderPrimitive("button", {
+    type: "button",
+    ...props,
+    children,
+    disabled: isDisabled,
+    "aria-disabled": isDisabled,
+    "aria-pressed": isSelected,
+    "data-dreamboard-interaction-card-input": "",
+    "data-input-name": input,
+    "data-card-id": cardId,
+    "data-zone": zoneCard?.zone,
+    "data-selected": isSelected || undefined,
+    "data-eligible": isEligible,
+    "data-selectable": isSelectable,
+    "data-card-available": isCandidateAvailable,
+    "data-invalid": isInvalid || undefined,
+    "data-disabled": isDisabled || undefined,
+    "data-missing-resource": cardId ? undefined : true,
+    onClick: composeEventHandlers(onClick, () => {
+      if (isDisabled || !cardId || !handle || !inputDescriptor) return;
+      const nextValue =
+        selection?.mode === "many"
+          ? toggleManyValue(currentValue, cardId, selection)
+          : cardId;
+      handle.setInput(input, nextValue);
+      onSelectedChange?.(
+        selection?.mode === "many"
+          ? Array.isArray(nextValue) && nextValue.includes(cardId)
+          : true,
+      );
+    }),
+  });
+}
+
+export const Interaction = {
+  Root: InteractionRoot,
+  Trigger: InteractionTrigger,
+  Label: InteractionLabel,
+  Description: InteractionDescription,
+  UnavailableMessage: InteractionUnavailableMessage,
+  ValidationMessage: InteractionValidationMessage,
+  Input: InteractionInput,
+  CardInput: InteractionCardInput,
+  Submit: InteractionSubmit,
+};

package/src/primitives/phase.test.tsx

@@ -0,0 +1,82 @@
+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 { GameUIProvider } from "./game-ui-provider.js";
+import { Phase } from "./phase.js";
+
+function createSessionState(): PluginSessionState {
+  return {
+    status: "ready",
+    sessionId: "session-1",
+    controllablePlayerIds: ["player-1"],
+    controllingPlayerId: "player-1",
+    userId: "user-1",
+  };
+}
+
+function createSnapshot(currentPhase: string | null): PluginStateSnapshot {
+  return {
+    view: {},
+    gameplay: {
+      currentPhase,
+      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("Phase.Switch renders the route for the current gameplay phase", () => {
+  const runtime = createRuntime(createSnapshot("play"));
+
+  const html = renderToString(
+    <GameUIProvider runtime={runtime}>
+      <Phase.Switch
+        routes={{
+          setup: () => <span>Setup</span>,
+          play: () => <span>Play</span>,
+        }}
+      />
+    </GameUIProvider>,
+  );
+
+  expect(html).toContain("Play");
+  expect(html).not.toContain("Setup");
+});
+
+test("Phase.Switch renders fallback for missing or unknown phases", () => {
+  const runtime = createRuntime(createSnapshot("unknown"));
+
+  const html = renderToString(
+    <GameUIProvider runtime={runtime}>
+      <Phase.Switch
+        routes={{
+          setup: () => <span>Setup</span>,
+          play: () => <span>Play</span>,
+        }}
+        fallback={(phase) => <span>Fallback {phase}</span>}
+      />
+    </GameUIProvider>,
+  );
+
+  expect(html).toContain("Fallback");
+  expect(html).toContain("unknown");
+});

package/src/primitives/phase.tsx

@@ -0,0 +1,43 @@
+import type { ReactElement, ReactNode } from "react";
+import { usePluginState } from "../context/PluginStateContext.js";
+import type { PhaseKey } from "../ui-contract.js";
+
+export type PhaseRouteMap<Phase extends string = PhaseKey> = {
+  readonly [Key in Phase]: () => ReactNode;
+};
+
+export type PhaseFallback = ReactNode | ((phase: string | null) => ReactNode);
+
+export interface PhaseSwitchProps<Phase extends string = PhaseKey> {
+  routes: PhaseRouteMap<Phase>;
+  fallback?: PhaseFallback;
+}
+
+function hasRoute<Phase extends string>(
+  routes: PhaseRouteMap<Phase>,
+  phase: string,
+): phase is Phase {
+  return Object.prototype.hasOwnProperty.call(routes, phase);
+}
+
+function renderFallback(
+  fallback: PhaseFallback | undefined,
+  phase: string | null,
+): ReactNode {
+  return typeof fallback === "function" ? fallback(phase) : (fallback ?? null);
+}
+
+export function PhaseSwitch<Phase extends string = PhaseKey>({
+  routes,
+  fallback,
+}: PhaseSwitchProps<Phase>): ReactElement | null {
+  const phase = usePluginState((state) => state.gameplay.currentPhase);
+  if (phase && hasRoute(routes, phase)) {
+    return <>{routes[phase]()}</>;
+  }
+  return <>{renderFallback(fallback, phase)}</>;
+}
+
+export const Phase = {
+  Switch: PhaseSwitch,
+};

package/src/primitives/player-roster.test.tsx

@@ -0,0 +1,168 @@
+import { expect, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import type { PluginStateSnapshot } from "../types/plugin-state.js";
+import type { RuntimeAPI, PluginSessionState } from "../types/runtime-api.js";
+import { GameUIProvider } from "./game-ui-provider.js";
+import { PlayerRoster } from "./player-roster.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(
+  session = createSessionState(),
+  seats: NonNullable<PluginStateSnapshot["lobby"]>["seats"] = [
+    {
+      playerId: "player-1",
+      displayName: "Ada",
+      playerColor: "#d04848",
+      isHost: true,
+    },
+    {
+      playerId: "player-2",
+      displayName: "Grace",
+      playerColor: "#2d5da1",
+    },
+    {
+      playerId: "player-3",
+      displayName: "Linus",
+      playerColor: "#1f7d3e",
+    },
+  ],
+): PluginStateSnapshot {
+  return {
+    view: {},
+    gameplay: {
+      currentPhase: "playing",
+      currentStage: null,
+      activePlayers: ["player-2"],
+      zones: {},
+      availableInteractions: [],
+    },
+    lobby: {
+      hostUserId: "user-1",
+      canStart: true,
+      seats,
+    },
+    notifications: [],
+    session,
+    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,
+    switchPlayer: () => undefined,
+  } as RuntimeAPI;
+}
+
+test("PlayerRoster renders turn-order entries with projected state", () => {
+  const runtime = createRuntime(createSnapshot());
+
+  const html = renderToString(
+    <GameUIProvider runtime={runtime}>
+      <PlayerRoster.Root
+        score={(playerId) => (playerId === "player-2" ? 7 : 0)}
+        scoreLabel="VP"
+        badges={(playerId) => [
+          playerId === "player-2"
+            ? { key: "leader", label: "Leader", tooltip: "Current leader" }
+            : null,
+        ]}
+      >
+        <PlayerRoster.List>
+          {(player) => (
+            <PlayerRoster.SwitchButton key={player.playerId} player={player}>
+              <PlayerRoster.Name player={player} />
+              <PlayerRoster.Score player={player} />
+              <PlayerRoster.Badges player={player} />
+            </PlayerRoster.SwitchButton>
+          )}
+        </PlayerRoster.List>
+      </PlayerRoster.Root>
+    </GameUIProvider>,
+  );
+
+  expect(html).toContain('data-dreamboard-player-roster-list=""');
+  expect(html).toContain('data-player-id="player-1"');
+  expect(html).toContain('data-current="true"');
+  expect(html).toContain('data-player-id="player-2"');
+  expect(html).toContain('data-active="true"');
+  expect(html).toContain('data-switchable="true"');
+  expect(html).toContain("Ada");
+  expect(html).toContain("Grace");
+  expect(html).toContain("7 VP");
+  expect(html).toContain("Leader");
+});
+
+test("PlayerRoster supports self-first ordering, filters, empty state, and asChild", () => {
+  const runtime = createRuntime(
+    createSnapshot(
+      createSessionState({
+        controllablePlayerIds: ["player-2"],
+        controllingPlayerId: "player-2",
+      }),
+    ),
+  );
+
+  const selfFirstHtml = renderToString(
+    <GameUIProvider runtime={runtime}>
+      <PlayerRoster.Root order="self-first">
+        <PlayerRoster.List>
+          {(player) => <span key={player.playerId}>{player.name}</span>}
+        </PlayerRoster.List>
+      </PlayerRoster.Root>
+    </GameUIProvider>,
+  );
+
+  expect(selfFirstHtml.indexOf("Grace")).toBeLessThan(
+    selfFirstHtml.indexOf("Ada"),
+  );
+
+  const opponentsHtml = renderToString(
+    <GameUIProvider runtime={runtime}>
+      <PlayerRoster.Root include="opponents">
+        <PlayerRoster.List>
+          {(player) => (
+            <PlayerRoster.SwitchButton player={player} asChild>
+              <button className="author-row">{player.name}</button>
+            </PlayerRoster.SwitchButton>
+          )}
+        </PlayerRoster.List>
+      </PlayerRoster.Root>
+    </GameUIProvider>,
+  );
+
+  expect(opponentsHtml).not.toContain("Grace");
+  expect(opponentsHtml).toContain('class="author-row"');
+  expect(opponentsHtml).toContain('data-dreamboard-player-roster-switch=""');
+  expect(opponentsHtml).toContain('disabled=""');
+
+  const emptyRuntime = createRuntime(createSnapshot(createSessionState(), []));
+  const emptyHtml = renderToString(
+    <GameUIProvider runtime={emptyRuntime}>
+      <PlayerRoster.Root>
+        <PlayerRoster.Empty>No players</PlayerRoster.Empty>
+        <PlayerRoster.List />
+      </PlayerRoster.Root>
+    </GameUIProvider>,
+  );
+
+  expect(emptyHtml).toContain("No players");
+});