@dreamboard-games/ui-sdk 0.0.41

package/src/components/board/index.ts

@@ -0,0 +1,142 @@
+/**
+ * Board Primitives
+ *
+ * Reusable board visualization components for different game types.
+ *
+ * Components:
+ * - NetworkGraph: For route-building games (Ticket to Ride, Pandemic)
+ * - HexGrid: For hex-based games (Catan, wargames)
+ * - SquareGrid: For grid-based games (Chess, Go, Checkers)
+ * - ZoneMap: For area control games (Risk, Small World)
+ * - TrackBoard: For track/racing games (Monopoly, Game of Life)
+ * - SlotSystem: For worker placement games (Agricola, Viticulture)
+ */
+
+// NetworkGraph - Route building games
+export {
+  NetworkGraph,
+  // Pre-built helper components for easy customization
+  DefaultNetworkNode,
+  DefaultNetworkEdge,
+  DefaultNetworkPiece,
+  type NetworkGraphProps,
+  type NetworkNode,
+  type NetworkEdge,
+  type NetworkPiece,
+  type DefaultNetworkNodeProps,
+  type DefaultNetworkEdgeProps,
+  type DefaultNetworkPieceProps,
+} from "./NetworkGraph.js";
+
+// HexGrid - Hex-based games (Catan, wargames)
+export {
+  HexGrid,
+  hexUtils,
+  // Pre-built helper components for easy customization
+  DefaultHexTile,
+  DefaultHexEdge,
+  DefaultHexVertex,
+  type HexGridBoardProps,
+  type HexGridProps,
+  type HexOrientation,
+  type HexTileGeometry,
+  type InteractiveHexEdge,
+  type InteractiveHexSpace,
+  type InteractiveHexVertex,
+  type EdgePosition,
+  type DefaultHexTileProps,
+  type DefaultHexEdgeProps,
+  type DefaultHexVertexProps,
+} from "./HexGrid.js";
+
+export type {
+  InteractiveTargetLayer,
+  InteractiveTargetRenderState,
+} from "./target-layer.js";
+
+export {
+  createHexBoardView,
+  type HexBoardView,
+  type HexBoardViewTile,
+} from "./hex-board-view.js";
+
+// SquareGrid - Grid-based games (Chess, Go, Checkers)
+export {
+  SquareGrid,
+  // Pre-built helper components for easy customization
+  DefaultGridCell,
+  DefaultGridPiece,
+  DefaultChessPiece,
+  // Utility functions
+  toAlgebraic,
+  toNumeric,
+  type SquareGridBoardProps,
+  type SquareGridProps,
+  type InteractiveSquareEdge,
+  type InteractiveSquareSpace,
+  type InteractiveSquareVertex,
+  type SquareEdgePosition,
+  type SquareVertexPosition,
+  type DefaultGridCellProps,
+  type DefaultGridPieceProps,
+  type DefaultChessPieceProps,
+} from "./SquareGrid.js";
+
+// ZoneMap - Area control games
+export {
+  ZoneMap,
+  // Pre-built helper components for easy customization
+  DefaultZone,
+  DefaultZonePieces,
+  DefaultZonePiece,
+  type ZoneMapProps,
+  type ZoneDefinition,
+  type ZonePiece,
+  type ZoneShape,
+  type ZoneHighlightType,
+  type DefaultZoneProps,
+  type DefaultZonePiecesProps,
+  type DefaultZonePieceProps,
+} from "./ZoneMap.js";
+
+// TrackBoard - Track/racing games
+export {
+  TrackBoard,
+  // Pre-built helper components for easy customization
+  DefaultTrackSpace,
+  DefaultTrackPiece,
+  DefaultTrackConnection,
+  DefaultTrackJump,
+  type TrackBoardProps,
+  type TrackSpace,
+  type TrackPiece,
+  type DefaultTrackSpaceProps,
+  type DefaultTrackPieceProps,
+  type DefaultTrackConnectionProps,
+  type DefaultTrackJumpProps,
+} from "./TrackBoard.js";
+
+// SlotSystem - Worker placement games
+export {
+  SlotSystem,
+  // Pre-built helper components for easy customization
+  DefaultSlotItem,
+  DefaultSlotOccupant,
+  DefaultEmptySlot,
+  type SlotSystemProps,
+  type SlotDefinition,
+  type SlotOccupant,
+  type DefaultSlotItemProps,
+  type DefaultSlotOccupantProps,
+  type DefaultEmptySlotProps,
+} from "./SlotSystem.js";
+
+export type {
+  HexTileState,
+  HexEdgeState,
+  HexVertexState,
+  SquareCellState,
+  SquareEdgeState,
+  SquarePieceState,
+  SquareVertexState,
+} from "../../types/player-state.js";

package/src/components/board/interaction-accessibility.ts

@@ -0,0 +1,21 @@
+import type { KeyboardEvent } from "react";
+
+export function handleKeyboardActivation(
+  event: KeyboardEvent,
+  onActivate: (() => void) | undefined,
+  options?: { stopPropagation?: boolean },
+): void {
+  if (!onActivate) {
+    return;
+  }
+
+  if (event.key !== "Enter" && event.key !== " ") {
+    return;
+  }
+
+  event.preventDefault();
+  if (options?.stopPropagation) {
+    event.stopPropagation();
+  }
+  onActivate();
+}

package/src/components/board/target-layer-grids.test.tsx

@@ -0,0 +1,420 @@
+import { expect, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import { HexGrid, hexUtils, type HexTileGeometry } from "./HexGrid.js";
+import {
+  SquareGrid,
+  type SquareEdgePosition,
+  type SquareVertexPosition,
+} from "./SquareGrid.js";
+import type { InteractiveTargetRenderState } from "./target-layer.js";
+import type {
+  HexEdgeState,
+  HexTileState,
+  HexVertexState,
+  SquareCellState,
+  SquareEdgeState,
+  SquareVertexState,
+} from "../../types/player-state.js";
+
+const hexTiles: HexTileState[] = [
+  { id: "center", q: 0, r: 0 },
+  { id: "east", q: 1, r: -1 },
+  { id: "north", q: 0, r: -1 },
+  { id: "southeast", q: 1, r: 0 },
+];
+
+const hexEdges: HexEdgeState[] = [
+  { id: "edge-eligible", hex1: "center", hex2: "east" },
+  { id: "edge-ineligible", hex1: "center", hex2: "north" },
+];
+
+const hexVertices: HexVertexState[] = [
+  { id: "vertex-eligible", hexes: ["center", "east", "north"] },
+  { id: "vertex-ineligible", hexes: ["center", "east", "southeast"] },
+];
+
+test("HexGrid target layers make only eligible targets interactive", () => {
+  const spaceStates: InteractiveTargetRenderState[] = [];
+  const edgeStates: InteractiveTargetRenderState[] = [];
+  const vertexStates: InteractiveTargetRenderState[] = [];
+
+  const html = renderToString(
+    <HexGrid
+      tiles={hexTiles}
+      edges={hexEdges}
+      vertices={hexVertices}
+      hexSize={40}
+      enablePanZoom={false}
+      interactiveSpaces={{
+        eligible: new Set(["center"]),
+        selectTargetId: () => undefined,
+      }}
+      interactiveEdges={{
+        eligible: new Set(["edge-eligible"]),
+        selectTargetId: () => undefined,
+      }}
+      interactiveVertices={{
+        eligible: new Set(["vertex-eligible"]),
+        selectTargetId: () => undefined,
+      }}
+      renderTile={() => null}
+      renderEdge={() => null}
+      renderVertex={() => null}
+      renderInteractiveSpace={(_space, state) => {
+        spaceStates.push(state);
+        return (
+          <polygon
+            data-space-state={`${state.isEnabled}:${state.isEligible}`}
+          />
+        );
+      }}
+      renderInteractiveEdge={(_edge, _position, state) => {
+        edgeStates.push(state);
+        return (
+          <line data-edge-state={`${state.isEnabled}:${state.isEligible}`} />
+        );
+      }}
+      renderInteractiveVertex={(_vertex, _position, state) => {
+        vertexStates.push(state);
+        return (
+          <circle
+            data-vertex-state={`${state.isEnabled}:${state.isEligible}`}
+          />
+        );
+      }}
+    />,
+  );
+
+  expect(html).toContain('aria-label="Select space center"');
+  expect(html).not.toContain('aria-label="Select space east"');
+  expect(html).toContain('aria-label="Select edge edge-eligible"');
+  expect(html).not.toContain('aria-label="Select edge edge-ineligible"');
+  expect(html).toContain('aria-label="Select vertex vertex-eligible"');
+  expect(html).not.toContain('aria-label="Select vertex vertex-ineligible"');
+  expect(html.match(/role="button"/g)?.length).toBe(3);
+  expect(html.match(/(?:tabIndex|tabindex)="0"/g)?.length).toBe(3);
+  expect(spaceStates.map((state) => state.isEligible)).toEqual([
+    true,
+    false,
+    false,
+    false,
+  ]);
+  expect(edgeStates.map((state) => state.isEligible)).toEqual([true, false]);
+  expect(vertexStates.map((state) => state.isEligible)).toEqual([true, false]);
+  expect(spaceStates.every((state) => state.isEnabled)).toBe(true);
+  expect(edgeStates.every((state) => state.isEnabled)).toBe(true);
+  expect(vertexStates.every((state) => !state.isHovered)).toBe(true);
+});
+
+test("HexGrid target layers treat missing eligible set as all targets eligible", () => {
+  const html = renderToString(
+    <HexGrid
+      tiles={hexTiles}
+      edges={hexEdges}
+      vertices={hexVertices}
+      hexSize={40}
+      enablePanZoom={false}
+      interactiveSpaces={{ selectTargetId: () => undefined }}
+      interactiveEdges={{ selectTargetId: () => undefined }}
+      renderTile={() => null}
+      renderEdge={() => null}
+      renderVertex={() => null}
+    />,
+  );
+
+  expect(html).toContain('aria-label="Select space center"');
+  expect(html).toContain('aria-label="Select space east"');
+  expect(html).toContain('aria-label="Select edge edge-eligible"');
+  expect(html).toContain('aria-label="Select edge edge-ineligible"');
+});
+
+test("HexGrid disables space targets when layer enabled is false", () => {
+  const states: InteractiveTargetRenderState[] = [];
+  const html = renderToString(
+    <HexGrid
+      tiles={hexTiles}
+      edges={hexEdges}
+      vertices={hexVertices}
+      hexSize={40}
+      enablePanZoom={false}
+      interactiveSpaces={{
+        enabled: false,
+        eligible: new Set(["center"]),
+        selectTargetId: () => undefined,
+      }}
+      renderTile={() => null}
+      renderEdge={() => null}
+      renderVertex={() => null}
+      renderInteractiveSpace={(_space, state) => {
+        states.push(state);
+        return <polygon data-enabled={String(state.isEnabled)} />;
+      }}
+    />,
+  );
+
+  expect(html).not.toContain('role="button"');
+  expect(/(?:tabIndex|tabindex)="0"/.test(html)).toBe(false);
+  expect(html).not.toContain('aria-label="Select space center"');
+  expect(states.map((state) => state.isEnabled)).toEqual([
+    false,
+    false,
+    false,
+    false,
+  ]);
+  expect(states.map((state) => state.isEligible)).toEqual([
+    true,
+    false,
+    false,
+    false,
+  ]);
+});
+
+const squareCells: SquareCellState[] = Array.from({ length: 3 }, (_, row) =>
+  Array.from({ length: 3 }, (_, col) => ({
+    id: `cell-${row}-${col}`,
+    row,
+    col,
+  })),
+).flat();
+
+const squareEdges: SquareEdgeState[] = [
+  { id: "edge-eligible", spaceIds: ["cell-0-0", "cell-0-1"] },
+  { id: "edge-ineligible", spaceIds: ["cell-0-0", "cell-1-0"] },
+];
+
+const squareVertices: SquareVertexState[] = [
+  {
+    id: "vertex-eligible",
+    spaceIds: ["cell-0-0", "cell-0-1", "cell-1-0", "cell-1-1"],
+  },
+  {
+    id: "vertex-ineligible",
+    spaceIds: ["cell-1-1", "cell-1-2", "cell-2-1", "cell-2-2"],
+  },
+];
+
+test("SquareGrid target layers make only eligible targets interactive", () => {
+  const spaceStates: InteractiveTargetRenderState[] = [];
+  const edgeStates: InteractiveTargetRenderState[] = [];
+  const vertexStates: InteractiveTargetRenderState[] = [];
+  const edgePositions: SquareEdgePosition[] = [];
+  const vertexPositions: SquareVertexPosition[] = [];
+
+  const html = renderToString(
+    <SquareGrid
+      rows={3}
+      cols={3}
+      cells={squareCells}
+      pieces={[]}
+      edges={squareEdges}
+      vertices={squareVertices}
+      showCoordinates={false}
+      interactiveSpaces={{
+        eligible: new Set(["cell-0-0"]),
+        selectTargetId: () => undefined,
+      }}
+      interactiveEdges={{
+        eligible: new Set(["edge-eligible"]),
+        selectTargetId: () => undefined,
+      }}
+      interactiveVertices={{
+        eligible: new Set(["vertex-eligible"]),
+        selectTargetId: () => undefined,
+      }}
+      renderCell={() => null}
+      renderPiece={() => null}
+      renderInteractiveSpace={(_space, state) => {
+        spaceStates.push(state);
+        return (
+          <rect data-space-state={`${state.isEnabled}:${state.isEligible}`} />
+        );
+      }}
+      renderInteractiveEdge={(_edge, position, state) => {
+        edgePositions.push(position);
+        edgeStates.push(state);
+        return (
+          <line data-edge-state={`${state.isEnabled}:${state.isEligible}`} />
+        );
+      }}
+      renderInteractiveVertex={(_vertex, position, state) => {
+        vertexPositions.push(position);
+        vertexStates.push(state);
+        return (
+          <circle
+            data-vertex-state={`${state.isEnabled}:${state.isEligible}`}
+          />
+        );
+      }}
+    />,
+  );
+
+  expect(html).toContain('aria-label="Select space cell-0-0"');
+  expect(html).not.toContain('aria-label="Select space cell-0-1"');
+  expect(html).toContain('aria-label="Select edge edge-eligible"');
+  expect(html).not.toContain('aria-label="Select edge edge-ineligible"');
+  expect(html).toContain('aria-label="Select vertex vertex-eligible"');
+  expect(html).not.toContain('aria-label="Select vertex vertex-ineligible"');
+  expect(html.match(/role="button"/g)?.length).toBe(3);
+  expect(html.match(/(?:tabIndex|tabindex)="0"/g)?.length).toBe(3);
+  expect(spaceStates.map((state) => state.isEligible)).toEqual([
+    true,
+    false,
+    false,
+    false,
+    false,
+    false,
+    false,
+    false,
+    false,
+  ]);
+  expect(edgeStates.map((state) => state.isEligible)).toEqual([true, false]);
+  expect(vertexStates.map((state) => state.isEligible)).toEqual([true, false]);
+  expect(edgePositions).toHaveLength(2);
+  expect(vertexPositions).toHaveLength(2);
+  expect(edgePositions[0]?.midX).toBeGreaterThan(0);
+  expect(vertexPositions[0]?.x).toBeGreaterThan(0);
+});
+
+test("SquareGrid target layers treat missing eligible set as all spaces eligible", () => {
+  const html = renderToString(
+    <SquareGrid
+      rows={3}
+      cols={3}
+      cells={squareCells}
+      pieces={[]}
+      showCoordinates={false}
+      interactiveSpaces={{ selectTargetId: () => undefined }}
+      renderCell={() => null}
+      renderPiece={() => null}
+    />,
+  );
+
+  expect(html).toContain('aria-label="Select space cell-0-0"');
+  expect(html).toContain('aria-label="Select space cell-2-2"');
+});
+
+test("SquareGrid disables space targets when layer enabled is false", () => {
+  const states: InteractiveTargetRenderState[] = [];
+  const html = renderToString(
+    <SquareGrid
+      rows={3}
+      cols={3}
+      cells={squareCells}
+      pieces={[]}
+      edges={squareEdges}
+      showCoordinates={false}
+      interactiveSpaces={{
+        enabled: false,
+        eligible: new Set(["cell-0-0"]),
+        selectTargetId: () => undefined,
+      }}
+      renderCell={() => null}
+      renderPiece={() => null}
+      renderInteractiveSpace={(_space, state) => {
+        states.push(state);
+        return <rect data-enabled={String(state.isEnabled)} />;
+      }}
+    />,
+  );
+
+  expect(html).not.toContain('role="button"');
+  expect(/(?:tabIndex|tabindex)="0"/.test(html)).toBe(false);
+  expect(html).not.toContain('aria-label="Select space cell-0-0"');
+  expect(states.map((state) => state.isEnabled)).toEqual([
+    false,
+    false,
+    false,
+    false,
+    false,
+    false,
+    false,
+    false,
+    false,
+  ]);
+  expect(states.map((state) => state.isEligible)).toEqual([
+    true,
+    false,
+    false,
+    false,
+    false,
+    false,
+    false,
+    false,
+    false,
+  ]);
+});
+
+test("HexGrid renderTile receives geometry context with size, orientation, and points", () => {
+  const captured: Array<{ tileId: string; geometry: HexTileGeometry }> = [];
+
+  renderToString(
+    <HexGrid
+      tiles={hexTiles}
+      edges={[]}
+      vertices={[]}
+      hexSize={40}
+      enablePanZoom={false}
+      renderTile={(tile, geometry) => {
+        captured.push({ tileId: tile.id, geometry });
+        return <polygon points={geometry.points()} />;
+      }}
+      renderEdge={() => null}
+      renderVertex={() => null}
+    />,
+  );
+
+  expect(captured).toHaveLength(hexTiles.length);
+  const center = captured.find((entry) => entry.tileId === "center");
+  expect(center).toBeDefined();
+  if (!center) throw new Error("missing center geometry");
+  expect(center.geometry.size).toBe(40);
+  expect(center.geometry.orientation).toBe("pointy-top");
+  expect(center.geometry.center).toEqual({ x: 0, y: 0 });
+  expect(center.geometry.position).toEqual({ x: 0, y: 0 });
+  expect(center.geometry.points()).toBe(
+    hexUtils.getHexPoints(0, 0, 40, "pointy-top"),
+  );
+  expect(center.geometry.points({ inset: 6 })).toBe(
+    hexUtils.getHexPoints(0, 0, 34, "pointy-top"),
+  );
+  expect(center.geometry.corners()).toHaveLength(6);
+  expect(center.geometry.bounds.width).toBeGreaterThan(0);
+  expect(center.geometry.bounds.height).toBeGreaterThan(0);
+
+  const east = captured.find((entry) => entry.tileId === "east");
+  expect(east).toBeDefined();
+  if (!east) throw new Error("missing east geometry");
+  // `east` sits at axial (q=1, r=-1); its absolute board position should
+  // not collapse to (0,0) like the centered tile.
+  expect(east.geometry.position.x).not.toBe(0);
+});
+
+test("HexGrid renderTile remains assignable from zero-arg or one-arg callbacks", () => {
+  const html = renderToString(
+    <HexGrid
+      tiles={hexTiles}
+      edges={[]}
+      vertices={[]}
+      hexSize={40}
+      enablePanZoom={false}
+      renderTile={() => null}
+      renderEdge={() => null}
+      renderVertex={() => null}
+    />,
+  );
+  expect(html).toContain("hex-grid");
+
+  const htmlOneArg = renderToString(
+    <HexGrid
+      tiles={hexTiles}
+      edges={[]}
+      vertices={[]}
+      hexSize={40}
+      enablePanZoom={false}
+      renderTile={(tile) => <text>{tile.id}</text>}
+      renderEdge={() => null}
+      renderVertex={() => null}
+    />,
+  );
+  expect(htmlOneArg).toContain("center");
+});

package/src/components/board/target-layer.ts

@@ -0,0 +1,30 @@
+export interface InteractiveTargetLayer {
+  enabled?: boolean;
+  eligible?: ReadonlySet<string>;
+  selectTargetId?: (targetId: string) => void | Promise<void>;
+}
+
+export interface InteractiveTargetRenderState {
+  isEnabled: boolean;
+  isEligible: boolean;
+  isHovered: boolean;
+}
+
+export function interactiveTargetRenderState(
+  layer: InteractiveTargetLayer,
+  targetId: string,
+  isHovered: boolean,
+): InteractiveTargetRenderState {
+  return {
+    isEnabled: layer.enabled !== false,
+    isEligible: layer.eligible?.has(targetId) ?? true,
+    isHovered,
+  };
+}
+
+export function isInteractiveTargetSelectable(
+  layer: InteractiveTargetLayer,
+  state: InteractiveTargetRenderState,
+): boolean {
+  return state.isEnabled && state.isEligible && !!layer.selectTargetId;
+}

package/src/components/card-render-content.type-test.ts

@@ -0,0 +1,27 @@
+import type { ViewCard } from "@dreamboard/sdk-types";
+import type { CardProps } from "./Card.js";
+
+type ExpectExtends<Actual extends Expected, Expected> = true;
+
+type TypedCard = ViewCard<
+  "tech-card-1",
+  "breakthrough",
+  {
+    cost: number;
+    label: string;
+  }
+>;
+
+type RenderContentCard = Parameters<
+  NonNullable<CardProps<TypedCard>["renderContent"]>
+>[0];
+
+type _CardIdIsPreserved = ExpectExtends<RenderContentCard["id"], "tech-card-1">;
+type _CardTypeIsPreserved = ExpectExtends<
+  RenderContentCard["cardType"],
+  "breakthrough"
+>;
+type _PropertiesArePreserved = ExpectExtends<
+  RenderContentCard["properties"]["cost"],
+  number
+>;