@dreamboard-games/sdk 0.2.0

package/src/ui/components/index.ts

@@ -0,0 +1,245 @@
+/** Reducer-native UI primitives for building game interfaces. */
+
+// Presentational components (no hooks, receive data as props)
+export { CardFace, type CardFaceProps, type ViewCard } from "./Card.js";
+export { Hand, type HandProps } from "./Hand.js";
+export { StagingZone, type StagingZoneProps } from "./StagingZone.js";
+export {
+  HandView,
+  type HandViewProps,
+  type HandLayoutKind,
+  type HandLayoutPolicy,
+} from "./HandView.js";
+export {
+  CardDragSurface,
+  CardDropTargetView,
+  useCardDragSurface,
+  type CardDragSurfaceProps,
+  type CardDragSurfaceController,
+  type CardDragSurfaceContextValue,
+  type CardDropTargetViewProps,
+  type DragPhase,
+} from "./CardDragSurface.js";
+export type { HandInteractionPolicy } from "./hand-pointer-engine.js";
+export {
+  HandDock,
+  type HandDockMode,
+  type HandDockPlacement,
+  type HandDockPresentation,
+  type HandDockProps,
+  type HandDockToggleContext,
+} from "./HandDock.js";
+export {
+  MobileHandTrayProvider,
+  useRegisterMobileHand,
+  useMobileHandTrayActive,
+  type HandRole,
+  type MobileHandRegistration,
+} from "./MobileHandTray.js";
+export { PlayArea, type PlayAreaProps } from "./PlayArea.js";
+export {
+  ChromeSuppressionProvider,
+  useChromeSuppression,
+} from "./ChromeSuppressionContext.js";
+
+// Other UI components
+export { GameSkeleton, type GameSkeletonProps } from "./GameSkeleton.js";
+export {
+  Toast,
+  ToastActions,
+  ToastProvider,
+  type ToastActionsProps,
+  type ToastActionsValue,
+  type ToastNotification,
+  type ToastType,
+} from "./Toast.js";
+export { ErrorBoundary, type ErrorBoundaryProps } from "./ErrorBoundary.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";
+export { Input } from "../internal/ui/input.js";
+export { Label } from "../internal/ui/label.js";
+export {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+} from "../internal/ui/select.js";
+
+// Game UI primitives (SDK v0.1.0+)
+export {
+  ResourceCounter,
+  ResourceCounterCount,
+  ResourceCounterIcon,
+  ResourceCounterItem,
+  ResourceCounterLabel,
+  ResourceCounterRoot,
+  createResourceCounter,
+  type BoundResourceCounterRootProps,
+  type ResourceCounterComponents,
+  type ResourceCounterItemState,
+  type ResourceCounterPartProps,
+  type ResourceCounterProps,
+  type ResourceCounterRootProps,
+  type ResourceDisplayConfig,
+  type ResourceIconProps,
+} 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 {
+  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";
+
+// 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 "../../types/index.js";

package/src/ui/components.ts

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

package/src/ui/defaults/components.tsx

@@ -0,0 +1,106 @@
+import type { CSSProperties, HTMLAttributes } from "react";
+import {
+  renderPrimitive,
+  type PrimitiveCommonProps,
+} from "../primitives/primitive-props.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,
+};

package/src/ui/defaults/index.ts

@@ -0,0 +1,8 @@
+export {
+  GameLayout,
+  GameLayoutBoard,
+  GameLayoutBottom,
+  GameLayoutHeader,
+  GameLayoutRoot,
+  GameLayoutSidebar,
+} from "./components.js";

package/src/ui/defaults.ts

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

package/src/ui/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);
+}

package/src/ui/helpers/cards.ts

@@ -0,0 +1,19 @@
+import type { CardCollection, ViewCard } from "../../types/index.js";
+
+export function materializeCards<
+  CardIdValue extends string,
+  CardValue extends ViewCard<CardIdValue>,
+>(collection: CardCollection<CardIdValue, CardValue>): CardValue[] {
+  const items: CardValue[] = [];
+
+  for (const cardId of collection.cardIds) {
+    const card = collection.cardsById[cardId];
+    if (!card) {
+      continue;
+    }
+
+    items.push(card);
+  }
+
+  return items;
+}

package/src/ui/helpers/track-board.ts

@@ -0,0 +1,211 @@
+import type { TrackPiece, TrackSpace } from "../components/board/TrackBoard.js";
+
+interface GenericBoardSpaceLike<
+  SpaceIdValue extends string = string,
+  Fields = Record<string, unknown>,
+> {
+  id: SpaceIdValue;
+  name?: string | null;
+  typeId?: string | null;
+  fields: Fields;
+}
+
+interface GenericBoardRelationLike<SpaceIdValue extends string = string> {
+  fromSpaceId: SpaceIdValue;
+  toSpaceId: SpaceIdValue;
+  directed: boolean;
+}
+
+export interface GenericBoardLike<
+  BoardIdValue extends string = string,
+  SpaceIdValue extends string = string,
+  SpaceFields = Record<string, unknown>,
+> {
+  id: BoardIdValue;
+  spaces: Readonly<
+    Record<SpaceIdValue, GenericBoardSpaceLike<SpaceIdValue, SpaceFields>>
+  >;
+  relations?: ReadonlyArray<GenericBoardRelationLike<SpaceIdValue>>;
+}
+
+export interface TrackBoardPieceLike<
+  PieceIdValue extends string = string,
+  SpaceIdValue extends string = string,
+  OwnerIdValue extends string = string,
+  Fields = unknown,
+> {
+  id: PieceIdValue;
+  spaceId: SpaceIdValue;
+  owner: OwnerIdValue;
+  typeId?: string | null;
+  fields?: Fields;
+}
+
+type BoardSpaceOf<TBoard extends GenericBoardLike> =
+  TBoard["spaces"][keyof TBoard["spaces"]];
+type SpaceIdOf<TBoard extends GenericBoardLike> =
+  BoardSpaceOf<TBoard> extends {
+    id: infer Id extends string;
+  }
+    ? Id
+    : never;
+type SpaceFieldsOf<TBoard extends GenericBoardLike> =
+  BoardSpaceOf<TBoard> extends { fields: infer Fields } ? Fields : never;
+type PieceIdOf<TPiece extends TrackBoardPieceLike> = TPiece extends {
+  id: infer Id extends string;
+}
+  ? Id
+  : never;
+type PieceOwnerOf<TPiece extends TrackBoardPieceLike> = TPiece extends {
+  owner: infer Owner extends string;
+}
+  ? Owner
+  : never;
+type PieceFieldsOf<TPiece extends TrackBoardPieceLike> = TPiece extends {
+  fields?: infer Fields;
+}
+  ? Fields
+  : never;
+
+type TrackLayout =
+  | {
+      type: "linear";
+      axis?: "x" | "y";
+      spacing?: number;
+      origin?: { x: number; y: number };
+    }
+  | {
+      type: "circular";
+      center: { x: number; y: number };
+      radius: number;
+      startAngleDeg?: number;
+      clockwise?: boolean;
+    };
+
+type PositionOptions<TBoard extends GenericBoardLike> =
+  | {
+      getPosition: (
+        space: BoardSpaceOf<TBoard>,
+        index: number,
+        spaces: ReadonlyArray<BoardSpaceOf<TBoard>>,
+      ) => { x: number; y: number };
+      layout?: never;
+    }
+  | {
+      getPosition?: never;
+      layout: TrackLayout;
+    };
+
+export type ToTrackBoardDataOptions<
+  TBoard extends GenericBoardLike,
+  TPiece extends TrackBoardPieceLike<
+    string,
+    SpaceIdOf<TBoard>,
+    string,
+    unknown
+  >,
+> = PositionOptions<TBoard> & {
+  pieces?: readonly TPiece[];
+  getNextSpaces?: (
+    space: BoardSpaceOf<TBoard>,
+    board: TBoard,
+  ) => ReadonlyArray<SpaceIdOf<TBoard>> | undefined;
+  getJumpTo?: (
+    space: BoardSpaceOf<TBoard>,
+    board: TBoard,
+  ) => SpaceIdOf<TBoard> | undefined;
+};
+
+function positionForLayout(
+  layout: TrackLayout,
+  index: number,
+  count: number,
+): { x: number; y: number } {
+  if (layout.type === "linear") {
+    const spacing = layout.spacing ?? 72;
+    const origin = layout.origin ?? { x: 0, y: 0 };
+    return layout.axis === "y"
+      ? { x: origin.x, y: origin.y + index * spacing }
+      : { x: origin.x + index * spacing, y: origin.y };
+  }
+
+  const startAngleDeg = layout.startAngleDeg ?? -90;
+  const clockwise = layout.clockwise ?? true;
+  const angleStep = count === 0 ? 0 : 360 / count;
+  const angleDeg = startAngleDeg + (clockwise ? 1 : -1) * angleStep * index;
+  const angle = (angleDeg * Math.PI) / 180;
+  return {
+    x: layout.center.x + Math.cos(angle) * layout.radius,
+    y: layout.center.y + Math.sin(angle) * layout.radius,
+  };
+}
+
+function defaultNextSpaces<TBoard extends GenericBoardLike>(
+  board: TBoard,
+  spaceId: SpaceIdOf<TBoard>,
+): Array<SpaceIdOf<TBoard>> {
+  const relations = board.relations ?? [];
+  return relations.flatMap((relation) => {
+    if (relation.fromSpaceId === spaceId) {
+      return [relation.toSpaceId];
+    }
+    if (!relation.directed && relation.toSpaceId === spaceId) {
+      return [relation.fromSpaceId];
+    }
+    return [];
+  }) as Array<SpaceIdOf<TBoard>>;
+}
+
+export function toTrackBoardData<
+  TBoard extends GenericBoardLike,
+  TPiece extends TrackBoardPieceLike<
+    string,
+    SpaceIdOf<TBoard>,
+    string,
+    unknown
+  >,
+>(
+  board: TBoard,
+  options: ToTrackBoardDataOptions<TBoard, TPiece>,
+): {
+  spaces: Array<TrackSpace<SpaceIdOf<TBoard>, SpaceFieldsOf<TBoard>>>;
+  pieces: Array<
+    TrackPiece<
+      PieceIdOf<TPiece>,
+      SpaceIdOf<TBoard>,
+      PieceOwnerOf<TPiece>,
+      PieceFieldsOf<TPiece>
+    >
+  >;
+} {
+  const spaces = Object.values(board.spaces) as Array<BoardSpaceOf<TBoard>>;
+  const orderedSpaces = [...spaces].sort((left, right) =>
+    left.id.localeCompare(right.id),
+  );
+
+  return {
+    spaces: orderedSpaces.map((space, index, allSpaces) => ({
+      id: space.id as SpaceIdOf<TBoard>,
+      index,
+      name: space.name ?? undefined,
+      type: space.typeId ?? undefined,
+      nextSpaces: (options.getNextSpaces?.(space, board) ??
+        defaultNextSpaces(board, space.id as SpaceIdOf<TBoard>)) as Array<
+        SpaceIdOf<TBoard>
+      >,
+      jumpTo: options.getJumpTo?.(space, board),
+      position:
+        "getPosition" in options && options.getPosition
+          ? options.getPosition(space, index, allSpaces)
+          : positionForLayout(options.layout, index, allSpaces.length),
+      data: space.fields as SpaceFieldsOf<TBoard>,
+    })),
+    pieces: (options.pieces ?? []).map((piece) => ({
+      id: piece.id as PieceIdOf<TPiece>,
+      spaceId: piece.spaceId,
+      owner: piece.owner as PieceOwnerOf<TPiece>,
+      type: piece.typeId ?? undefined,
+      data: piece.fields as PieceFieldsOf<TPiece>,
+    })),
+  };
+}