@dreamboard-games/ui-sdk 0.0.41

package/src/primitives/player-roster.tsx

@@ -0,0 +1,301 @@
+import {
+  createContext,
+  Fragment,
+  useContext,
+  useMemo,
+  type ButtonHTMLAttributes,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import type { PlayerId } from "@dreamboard/manifest-contract";
+import { useActivePlayers } from "../hooks/useActivePlayers.js";
+import { usePlayerInfo } from "../hooks/usePlayerInfo.js";
+import { usePlayerTurnOrder } from "../hooks/usePlayerTurnOrder.js";
+import { usePluginActions } from "../context/PluginStateContext.js";
+import { usePluginSession } from "../context/PluginSessionContext.js";
+import {
+  composeEventHandlers,
+  renderPrimitive,
+  type PrimitiveCommonProps,
+} from "./primitive-props.js";
+
+export interface PlayerRosterBadge {
+  key: string;
+  label?: ReactNode;
+  icon?: ReactNode;
+  tooltip?: string;
+}
+
+export interface PlayerRosterEntry {
+  playerId: PlayerId;
+  name: string;
+  color?: string;
+  index: number;
+  isActive: boolean;
+  isCurrentPlayer: boolean;
+  isControllable: boolean;
+  canSwitchToPlayer: boolean;
+  score?: number;
+  scoreLabel?: string;
+  badges: readonly PlayerRosterBadge[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface PlayerRosterRootProps {
+  children: ReactNode;
+  order?: "turn" | "self-first";
+  include?: "all" | "self" | "opponents";
+  score?: (playerId: PlayerId) => number | undefined;
+  scoreLabel?: string | ((playerId: PlayerId) => string | undefined);
+  badges?: (
+    playerId: PlayerId,
+  ) => ReadonlyArray<PlayerRosterBadge | null | false | undefined>;
+  metadata?: (playerId: PlayerId) => Record<string, unknown> | undefined;
+}
+
+interface PlayerRosterContextValue {
+  players: readonly PlayerRosterEntry[];
+}
+
+const PlayerRosterContext = createContext<PlayerRosterContextValue | null>(
+  null,
+);
+
+function usePlayerRosterContext(): PlayerRosterContextValue {
+  const value = useContext(PlayerRosterContext);
+  if (!value) {
+    throw new Error(
+      "PlayerRoster primitives must be rendered inside <PlayerRoster.Root>.",
+    );
+  }
+  return value;
+}
+
+function projectBadges(
+  badges: PlayerRosterRootProps["badges"],
+  playerId: PlayerId,
+): readonly PlayerRosterBadge[] {
+  return (badges?.(playerId) ?? []).filter(
+    (badge): badge is PlayerRosterBadge => Boolean(badge),
+  );
+}
+
+export function PlayerRosterRoot({
+  children,
+  order = "turn",
+  include = "all",
+  score,
+  scoreLabel,
+  badges,
+  metadata,
+}: PlayerRosterRootProps) {
+  const playerInfo = usePlayerInfo();
+  const activePlayers = useActivePlayers();
+  const turnOrder = usePlayerTurnOrder();
+  const { controllingPlayerId, controllablePlayerIds } = usePluginSession();
+
+  const players = useMemo<readonly PlayerRosterEntry[]>(() => {
+    const orderedPlayerIds =
+      order === "self-first" && controllingPlayerId
+        ? [
+            ...turnOrder.filter((pid) => pid === controllingPlayerId),
+            ...turnOrder.filter((pid) => pid !== controllingPlayerId),
+          ]
+        : turnOrder;
+
+    return orderedPlayerIds
+      .map((playerId, index): PlayerRosterEntry => {
+        const player = playerInfo.get(playerId);
+        const isCurrentPlayer = playerId === controllingPlayerId;
+        const isControllable = controllablePlayerIds.includes(playerId);
+        const resolvedScoreLabel =
+          typeof scoreLabel === "function" ? scoreLabel(playerId) : scoreLabel;
+
+        return {
+          playerId,
+          name: player?.name ?? playerId,
+          color: player?.color,
+          index,
+          isActive: activePlayers.includes(playerId),
+          isCurrentPlayer,
+          isControllable,
+          canSwitchToPlayer:
+            controllablePlayerIds.length > 1 &&
+            isControllable &&
+            !isCurrentPlayer,
+          score: score?.(playerId),
+          scoreLabel: resolvedScoreLabel,
+          badges: projectBadges(badges, playerId),
+          metadata: metadata?.(playerId),
+        };
+      })
+      .filter((player) => {
+        if (include === "self") return player.isCurrentPlayer;
+        if (include === "opponents") return !player.isCurrentPlayer;
+        return true;
+      });
+  }, [
+    activePlayers,
+    badges,
+    controllablePlayerIds,
+    controllingPlayerId,
+    include,
+    metadata,
+    order,
+    playerInfo,
+    score,
+    scoreLabel,
+    turnOrder,
+  ]);
+
+  const value = useMemo<PlayerRosterContextValue>(
+    () => ({ players }),
+    [players],
+  );
+
+  return (
+    <PlayerRosterContext.Provider value={value}>
+      {children}
+    </PlayerRosterContext.Provider>
+  );
+}
+
+export type PlayerRosterListProps = Omit<PrimitiveCommonProps, "children"> &
+  Omit<HTMLAttributes<HTMLElement>, "children"> & {
+    children?: (player: PlayerRosterEntry) => ReactNode;
+  };
+
+export function PlayerRosterList({
+  children,
+  ...props
+}: PlayerRosterListProps) {
+  const { players } = usePlayerRosterContext();
+  return renderPrimitive("div", {
+    ...props,
+    "data-dreamboard-player-roster-list": "",
+    children: players.map((player) => (
+      <Fragment key={player.playerId}>
+        {children ? children(player) : <PlayerRosterName player={player} />}
+      </Fragment>
+    )),
+  });
+}
+
+export function PlayerRosterEmpty({ children }: { children?: ReactNode }) {
+  const { players } = usePlayerRosterContext();
+  if (players.length > 0) return null;
+  return <>{children}</>;
+}
+
+export type PlayerRosterSwitchButtonProps = Omit<
+  PrimitiveCommonProps,
+  "children"
+> &
+  ButtonHTMLAttributes<HTMLButtonElement> & {
+    player: PlayerRosterEntry;
+    children?: ReactNode;
+  };
+
+export function PlayerRosterSwitchButton({
+  player,
+  disabled,
+  onClick,
+  ...props
+}: PlayerRosterSwitchButtonProps) {
+  const { switchPlayer } = usePluginActions();
+  const isDisabled = disabled === true || !player.canSwitchToPlayer;
+  return renderPrimitive("button", {
+    type: "button",
+    ...props,
+    disabled: isDisabled,
+    "aria-current": player.isCurrentPlayer ? "true" : undefined,
+    "aria-disabled": isDisabled,
+    "data-dreamboard-player-roster-switch": "",
+    "data-player-id": player.playerId,
+    "data-active": player.isActive || undefined,
+    "data-current": player.isCurrentPlayer || undefined,
+    "data-controllable": player.isControllable || undefined,
+    "data-switchable": player.canSwitchToPlayer || undefined,
+    "data-disabled": isDisabled || undefined,
+    onClick: composeEventHandlers(onClick, () => {
+      if (!isDisabled) switchPlayer(player.playerId);
+    }),
+  });
+}
+
+export type PlayerRosterPartProps = PrimitiveCommonProps &
+  HTMLAttributes<HTMLElement> & {
+    player: PlayerRosterEntry;
+  };
+
+export interface PlayerRosterComponents {
+  Root(props: PlayerRosterRootProps): ReactElement | null;
+  List(props: PlayerRosterListProps): ReactElement;
+  Empty(props: { children?: ReactNode }): ReactElement | null;
+  SwitchButton(props: PlayerRosterSwitchButtonProps): ReactElement;
+  Name(props: PlayerRosterPartProps): ReactElement;
+  Score(props: PlayerRosterPartProps): ReactElement | null;
+  Badges(props: PlayerRosterPartProps): ReactElement | null;
+}
+
+export function PlayerRosterName({
+  player,
+  children,
+  ...props
+}: PlayerRosterPartProps) {
+  return renderPrimitive("span", {
+    ...props,
+    "data-dreamboard-player-roster-name": "",
+    children: children ?? player.name,
+  });
+}
+
+export function PlayerRosterScore({
+  player,
+  children,
+  ...props
+}: PlayerRosterPartProps) {
+  if (player.score === undefined && children === undefined) return null;
+  const label = player.scoreLabel ? ` ${player.scoreLabel}` : "";
+  return renderPrimitive("span", {
+    ...props,
+    "data-dreamboard-player-roster-score": "",
+    children: children ?? `${player.score}${label}`,
+  });
+}
+
+export function PlayerRosterBadges({
+  player,
+  children,
+  ...props
+}: PlayerRosterPartProps) {
+  if (player.badges.length === 0 && children === undefined) return null;
+  return renderPrimitive("span", {
+    ...props,
+    "data-dreamboard-player-roster-badges": "",
+    children:
+      children ??
+      player.badges.map((badge) => (
+        <span
+          key={badge.key}
+          data-dreamboard-player-roster-badge=""
+          title={badge.tooltip}
+          aria-label={badge.tooltip}
+        >
+          {badge.icon}
+          {badge.label}
+        </span>
+      )),
+  });
+}
+
+export const PlayerRoster: PlayerRosterComponents = {
+  Root: PlayerRosterRoot,
+  List: PlayerRosterList,
+  Empty: PlayerRosterEmpty,
+  SwitchButton: PlayerRosterSwitchButton,
+  Name: PlayerRosterName,
+  Score: PlayerRosterScore,
+  Badges: PlayerRosterBadges,
+};

package/src/primitives/primitive-props.tsx

@@ -0,0 +1,82 @@
+import {
+  cloneElement,
+  isValidElement,
+  type AriaAttributes,
+  type CSSProperties,
+  type HTMLAttributes,
+  type JSX,
+  type ChangeEvent,
+  type MouseEvent,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+
+export type PrimitiveDataAttributes = Record<
+  `data-${string}`,
+  string | boolean | number | undefined
+>;
+
+export type PrimitiveCommonProps = {
+  asChild?: boolean;
+  children?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+} & AriaAttributes &
+  PrimitiveDataAttributes;
+
+type EventHandler<Event> = (event: Event) => void;
+
+export function composeEventHandlers<
+  Event extends { defaultPrevented: boolean },
+>(
+  authorHandler: EventHandler<Event> | undefined,
+  primitiveHandler: EventHandler<Event> | undefined,
+): EventHandler<Event> | undefined {
+  if (!authorHandler) return primitiveHandler;
+  if (!primitiveHandler) return authorHandler;
+  return (event) => {
+    authorHandler(event);
+    if (!event.defaultPrevented) {
+      primitiveHandler(event);
+    }
+  };
+}
+
+export function renderPrimitive<
+  ElementProps extends HTMLAttributes<HTMLElement>,
+>(
+  tagName: keyof JSX.IntrinsicElements,
+  props: ElementProps & PrimitiveCommonProps,
+): ReactElement {
+  const { asChild, children, ...primitiveProps } = props;
+  if (asChild) {
+    if (!isValidElement(children)) {
+      throw new Error(
+        "asChild requires exactly one valid React element child.",
+      );
+    }
+    const element = children as ReactElement<HTMLAttributes<HTMLElement>>;
+    const childProps = element.props;
+    return cloneElement(element, {
+      ...primitiveProps,
+      ...childProps,
+      className: [primitiveProps.className, childProps.className]
+        .filter(Boolean)
+        .join(" "),
+      style: {
+        ...(primitiveProps.style ?? {}),
+        ...(childProps.style ?? {}),
+      },
+      onClick: composeEventHandlers(
+        childProps.onClick,
+        primitiveProps.onClick as EventHandler<MouseEvent<HTMLElement>>,
+      ),
+      onChange: composeEventHandlers(
+        childProps.onChange,
+        primitiveProps.onChange as EventHandler<ChangeEvent<HTMLElement>>,
+      ),
+    });
+  }
+  const Tag = tagName as keyof JSX.IntrinsicElements;
+  return <Tag {...(primitiveProps as object)}>{children}</Tag>;
+}

package/src/primitives/prompt.test.tsx

@@ -0,0 +1,159 @@
+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 { Prompt, PromptInbox } from "./prompt.js";
+
+function createSessionState(): PluginSessionState {
+  return {
+    status: "ready",
+    sessionId: "session-1",
+    controllablePlayerIds: ["player-1"],
+    controllingPlayerId: "player-1",
+    userId: "user-1",
+  };
+}
+
+function createSnapshot(
+  availableInteractions: PluginStateSnapshot["gameplay"]["availableInteractions"],
+): PluginStateSnapshot {
+  return {
+    view: {},
+    gameplay: {
+      currentPhase: "trading",
+      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;
+}
+
+const tradePrompt = {
+  phaseName: "trading",
+  interactionKey: "trade.respond",
+  interactionId: "respond",
+  surface: "inbox",
+  kind: "prompt",
+  label: "Respond to trade",
+  description: "Choose a response.",
+  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" },
+    ],
+  },
+} as const satisfies PluginStateSnapshot["gameplay"]["availableInteractions"][number];
+
+test("Prompt primitives render title, message, and option data", () => {
+  const runtime = createRuntime(createSnapshot([tradePrompt]));
+
+  const html = renderToString(
+    <GameUIProvider runtime={runtime}>
+      <Prompt.Root interaction="trade.respond">
+        <Prompt.Title />
+        <Prompt.Message />
+        <Prompt.Option value="accept" />
+        <Prompt.Option value="decline" asChild>
+          <button className="custom-option">No thanks</button>
+        </Prompt.Option>
+      </Prompt.Root>
+    </GameUIProvider>,
+  );
+
+  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"');
+  expect(html).toContain("Accept");
+  expect(html).toContain('class="custom-option"');
+  expect(html).toContain("No thanks");
+});
+
+test("Prompt options stay actionable when a prompt descriptor is unavailable", () => {
+  const runtime = createRuntime(
+    createSnapshot([
+      {
+        ...tradePrompt,
+        available: false,
+        unavailableReason: "Accept is not affordable.",
+      },
+    ]),
+  );
+
+  const html = renderToString(
+    <GameUIProvider runtime={runtime}>
+      <Prompt.Root interaction="trade.respond">
+        <Prompt.Option value="accept" />
+        <Prompt.Option value="decline" disableWhenUnavailable />
+      </Prompt.Root>
+    </GameUIProvider>,
+  );
+
+  expect(html).toContain('data-option-value="accept"');
+  expect(html).toContain('data-available="false"');
+  expect(html).not.toContain('data-option-value="accept" disabled=""');
+  expect(html).toContain('disabled=""');
+  expect(html).toContain('data-option-value="decline"');
+});
+
+test("PromptInbox defaults render prompt descriptors and empty state", () => {
+  const populatedRuntime = createRuntime(createSnapshot([tradePrompt]));
+  const emptyRuntime = createRuntime(createSnapshot([]));
+
+  const populatedHtml = renderToString(
+    <GameUIProvider runtime={populatedRuntime}>
+      <PromptInbox.Root>
+        <PromptInbox.Empty>No prompts</PromptInbox.Empty>
+        <PromptInbox.Items />
+      </PromptInbox.Root>
+    </GameUIProvider>,
+  );
+  const emptyHtml = renderToString(
+    <GameUIProvider runtime={emptyRuntime}>
+      <PromptInbox.Root>
+        <PromptInbox.Empty>No prompts</PromptInbox.Empty>
+        <PromptInbox.Items />
+      </PromptInbox.Root>
+    </GameUIProvider>,
+  );
+
+  expect(populatedHtml).toContain("Trade offer");
+  expect(populatedHtml).not.toContain("No prompts");
+  expect(emptyHtml).toContain("No prompts");
+});