@dreamboard-games/sdk 0.2.0

package/src/runtime-internal/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/runtime-internal/primitives/player-roster.tsx

@@ -0,0 +1,302 @@
+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";
+import type { HexColor } from "../../ui.js";
+
+export interface PlayerRosterBadge {
+  key: string;
+  label?: ReactNode;
+  icon?: ReactNode;
+  tooltip?: string;
+}
+
+export interface PlayerRosterEntry {
+  playerId: PlayerId;
+  name: string;
+  color?: HexColor;
+  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/runtime-internal/primitives/primitive-props.tsx

@@ -0,0 +1,101 @@
+import {
+  cloneElement,
+  isValidElement,
+  type AriaAttributes,
+  type CSSProperties,
+  type HTMLAttributes,
+  type JSX,
+  type ChangeEvent,
+  type MouseEvent,
+  type PointerEvent,
+  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>>,
+      ),
+      onPointerDown: composeEventHandlers(
+        childProps.onPointerDown,
+        primitiveProps.onPointerDown as EventHandler<PointerEvent<HTMLElement>>,
+      ),
+      onPointerMove: composeEventHandlers(
+        childProps.onPointerMove,
+        primitiveProps.onPointerMove as EventHandler<PointerEvent<HTMLElement>>,
+      ),
+      onPointerUp: composeEventHandlers(
+        childProps.onPointerUp,
+        primitiveProps.onPointerUp as EventHandler<PointerEvent<HTMLElement>>,
+      ),
+      onPointerCancel: composeEventHandlers(
+        childProps.onPointerCancel,
+        primitiveProps.onPointerCancel as EventHandler<
+          PointerEvent<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/runtime-internal/primitives/prompt.tsx

@@ -0,0 +1,255 @@
+import {
+  Fragment,
+  createContext,
+  useContext,
+  useMemo,
+  type ButtonHTMLAttributes,
+  type ReactNode,
+} from "react";
+import { useSeatInbox } from "../hooks/useSeatInbox.js";
+import type { PromptKey, PromptOptionKey } from "../ui-contract.js";
+import type {
+  InteractionDescriptor,
+  InteractionContextOption,
+} from "../types/plugin-state.js";
+import { interactionInputKeys } from "../utils/interaction-inputs.js";
+import { interactionLabel } from "../utils/interaction-labels.js";
+import { isInteractionAvailable } from "../utils/interaction-status.js";
+import {
+  InteractionDescription,
+  InteractionLabel,
+  InteractionRoot,
+  useInteractionPrimitiveContext,
+  type InteractionPartProps,
+  type InteractionRootProps,
+} from "./interaction.js";
+import {
+  composeEventHandlers,
+  renderPrimitive,
+  type PrimitiveCommonProps,
+} from "./primitive-props.js";
+import {
+  submitInteractionParams,
+  type InteractionSubmitCallbacks,
+} from "./interaction-submit.js";
+import {
+  useDialogLifecycle,
+  type DialogLifecycleState,
+} from "./dialog-lifecycle.js";
+import { useGameActionError } from "./game.js";
+
+export type PromptRootProps<Prompt extends string = PromptKey> =
+  InteractionRootProps<Prompt>;
+
+export function PromptRoot<Prompt extends string = PromptKey>(
+  props: PromptRootProps<Prompt>,
+) {
+  return <InteractionRoot {...props} />;
+}
+
+export function PromptTitle(props: InteractionPartProps) {
+  const { descriptor } = useInteractionPrimitiveContext();
+  const context =
+    descriptor?.kind === "prompt" ? descriptor.context : undefined;
+  return (
+    <InteractionLabel {...props}>
+      {props.children ??
+        context?.title ??
+        (descriptor ? interactionLabel(descriptor) : undefined)}
+    </InteractionLabel>
+  );
+}
+
+export function PromptMessage(props: InteractionPartProps) {
+  const { descriptor } = useInteractionPrimitiveContext();
+  const context =
+    descriptor?.kind === "prompt" ? descriptor.context : undefined;
+  const message =
+    props.children ??
+    (typeof context?.payload?.message === "string"
+      ? context.payload.message
+      : undefined);
+  if (!message) return null;
+  return <InteractionDescription {...props}>{message}</InteractionDescription>;
+}
+
+export type PromptOptionProps<Option extends string = PromptOptionKey> =
+  PrimitiveCommonProps &
+    ButtonHTMLAttributes<HTMLButtonElement> & {
+      value: Option;
+      disableWhenUnavailable?: boolean;
+      onSubmitError?: InteractionSubmitCallbacks["onSubmitError"];
+      onSubmitSuccess?: InteractionSubmitCallbacks["onSubmitSuccess"];
+    };
+
+export function PromptOption<Option extends string = PromptOptionKey>({
+  value,
+  disabled,
+  disableWhenUnavailable = false,
+  onClick,
+  onSubmitError,
+  onSubmitSuccess,
+  children,
+  ...props
+}: PromptOptionProps<Option>) {
+  const { descriptor, handle } = useInteractionPrimitiveContext();
+  const gameActionError = useGameActionError();
+  const context =
+    descriptor?.kind === "prompt" ? descriptor.context : undefined;
+  const option = context?.options?.find((candidate) => candidate.id === value);
+  const inputKey = descriptor ? interactionInputKeys(descriptor)[0] : undefined;
+  const choice = descriptor?.inputs.find(
+    (input) => input.key === inputKey,
+  )?.domain;
+  const optionChoice =
+    choice?.type === "choice"
+      ? choice.choices?.find((candidate) => candidate.value === value)
+      : undefined;
+  const isDisabled =
+    disabled ??
+    (!handle ||
+      !inputKey ||
+      handle.status !== "open" ||
+      optionChoice?.disabled === true ||
+      (disableWhenUnavailable && !isInteractionAvailable(descriptor)));
+  return renderPrimitive("button", {
+    type: "button",
+    ...props,
+    disabled: isDisabled,
+    "aria-disabled": isDisabled,
+    "data-dreamboard-prompt-option": "",
+    "data-option-value": value,
+    "data-disabled": isDisabled || undefined,
+    "data-available": isInteractionAvailable(descriptor),
+    "data-disabled-reason": optionChoice?.disabledReason,
+    title: props.title ?? optionChoice?.disabledReason,
+    onClick: composeEventHandlers(onClick, () => {
+      if (!handle || !inputKey || isDisabled) return;
+      void submitInteractionParams(
+        handle,
+        { [inputKey]: value },
+        {
+          onSubmitSuccess,
+          onSubmitError: onSubmitError ?? gameActionError ?? undefined,
+        },
+        { unhandledError: "log" },
+      );
+    }),
+    children: children ?? option?.label ?? value,
+  });
+}
+
+export interface PromptOptionRenderItem {
+  id: string;
+  label?: string;
+}
+
+export interface PromptOptionsProps {
+  children: (option: PromptOptionRenderItem) => ReactNode;
+}
+
+export function PromptOptions({ children }: PromptOptionsProps) {
+  const { descriptor } = useInteractionPrimitiveContext();
+  const options: readonly InteractionContextOption[] =
+    descriptor?.kind === "prompt" ? (descriptor.context.options ?? []) : [];
+  return (
+    <>
+      {options.map((option) => (
+        <Fragment key={option.id}>{children(option)}</Fragment>
+      ))}
+    </>
+  );
+}
+
+export type PromptDialogState = DialogLifecycleState;
+
+export interface PromptDialogRenderState<Prompt extends string = PromptKey> {
+  prompt: Prompt;
+  state: PromptDialogState;
+  open: boolean;
+  minimized: boolean;
+  dismissed: boolean;
+  setOpen: (open: boolean) => void;
+  restore: () => void;
+  minimize: () => void;
+  dismiss: () => void;
+}
+
+export interface PromptDialogProps<Prompt extends string = PromptKey> {
+  prompt: Prompt;
+  defaultOpen?: boolean;
+  onStateChange?: (state: PromptDialogState) => void;
+  children: (state: PromptDialogRenderState<Prompt>) => ReactNode;
+}
+
+export function PromptDialog<Prompt extends string = PromptKey>({
+  prompt,
+  defaultOpen = true,
+  onStateChange,
+  children,
+}: PromptDialogProps<Prompt>) {
+  const lifecycle = useDialogLifecycle({ defaultOpen, onStateChange });
+  const renderState = useMemo<PromptDialogRenderState<Prompt>>(
+    () => ({
+      prompt,
+      ...lifecycle,
+    }),
+    [lifecycle, prompt],
+  );
+  return <>{children(renderState)}</>;
+}
+
+interface PromptInboxContextValue {
+  prompts: readonly InteractionDescriptor[];
+}
+
+const PromptInboxContext = createContext<PromptInboxContextValue | null>(null);
+
+function usePromptInboxContext(): PromptInboxContextValue {
+  const value = useContext(PromptInboxContext);
+  if (!value) {
+    throw new Error(
+      "PromptInbox primitives must be rendered inside <PromptInbox.Root>.",
+    );
+  }
+  return value;
+}
+
+export function PromptInboxRoot({ children }: { children: ReactNode }) {
+  const inbox = useSeatInbox();
+  return (
+    <PromptInboxContext.Provider value={{ prompts: inbox.prompts }}>
+      {children}
+    </PromptInboxContext.Provider>
+  );
+}
+
+export function PromptInboxEmpty({ children }: { children?: ReactNode }) {
+  const { prompts } = usePromptInboxContext();
+  if (prompts.length > 0) return null;
+  return <>{children}</>;
+}
+
+export interface PromptInboxItemsProps {
+  children: (prompt: InteractionDescriptor) => ReactNode;
+}
+
+export function PromptInboxItems({ children }: PromptInboxItemsProps) {
+  const { prompts } = usePromptInboxContext();
+  return <>{prompts.map((prompt) => children(prompt))}</>;
+}
+
+export const Prompt = {
+  Root: PromptRoot,
+  Title: PromptTitle,
+  Message: PromptMessage,
+  Option: PromptOption,
+  Options: PromptOptions,
+  Dialog: PromptDialog,
+};
+
+export const PromptInbox = {
+  Root: PromptInboxRoot,
+  Empty: PromptInboxEmpty,
+  Items: PromptInboxItems,
+};