@dreamboard-games/sdk 0.2.0

package/src/reducer/inputs/boardInput.ts

@@ -0,0 +1,217 @@
+import { z } from "zod";
+import type {
+  BoardTargetDomainDescriptor,
+  CollectorState,
+  InputCollector,
+  TargetKind,
+} from "../model/spec";
+import type { BoardTargetRule, PlayerBoardSpaceTarget } from "./boardTarget";
+import type { InputFieldRef } from "./defineInputs";
+
+/**
+ * `boardInput.*` helpers produce collectors that accept a board-element id
+ * (vertex / edge / space / tile) scoped to one built `boardTarget` rule.
+ *
+ * Id typing:
+ *   The `Id` type parameter is the branded id for the board you target,
+ *   e.g. `HexVertexIdOfTable<Table, "main">` or
+ *   `SquareSpaceIdOfTable<Table, "board">`. Once tightened,
+ *   `ParamsOf<Collectors>` downstream typing reflects the branded id too.
+ *
+ * Eligibility:
+ *   Pass a built `boardTarget.*(...).where(...).build()` rule. The same rule
+ *   feeds server-authoritative eligible-target projection, submit validation,
+ *   and tests through its `bind({ state, playerId, q })` helper.
+ *
+ * Runtime vs. compile time:
+ *   At runtime the submitted value is a string. Branding is purely a
+ *   compile-time discipline.
+ */
+function makeBoardCollector<
+  Kind extends "board-vertex" | "board-edge" | "board-tile" | "board-space",
+>(kind: Kind) {
+  return function collector<
+    State extends CollectorState = CollectorState,
+    Id extends string = string,
+  >(options: {
+    target: BoardTargetRule<State, Id>;
+    dependsOn?: readonly InputFieldRef<string, unknown>[];
+  }): InputCollector<z.ZodType<Id>, State, Kind> {
+    const target = options.target;
+    const dependsOn = options.dependsOn?.map((dependency) => dependency.key);
+    return {
+      kind,
+      schema: z.string() as unknown as z.ZodType<Id>,
+      eligibleTargets: ((state, playerId, q, values) =>
+        target.eligible({
+          state: state as State,
+          playerId: playerId as never,
+          q: q as never,
+          values,
+        })) as
+        | ((
+            state: CollectorState,
+            playerId: string,
+            q: unknown,
+            values?: Readonly<Record<string, unknown>>,
+          ) => ReadonlyArray<unknown>)
+        | undefined,
+      validateTarget: ((state, playerId, q, targetId, values) =>
+        target.validate(
+          {
+            state: state as State,
+            playerId: playerId as never,
+            q: q as never,
+            values,
+          },
+          targetId as Id,
+        )) as
+        | ((
+            state: CollectorState,
+            playerId: string,
+            q: unknown,
+            targetId: unknown,
+            values?: Readonly<Record<string, unknown>>,
+          ) => ReturnType<BoardTargetRule<CollectorState, string>["validate"]>)
+        | undefined,
+      ...(dependsOn ? { dependsOn } : {}),
+      domain: (
+        state: CollectorState,
+        playerId: string,
+        q: unknown,
+        _derived: unknown,
+        values?: Readonly<Record<string, unknown>>,
+      ) =>
+        ({
+          type: "boardTarget" as const,
+          projection: "resolved" as const,
+          targetKind: target.targetKind as Exclude<TargetKind, "card">,
+          boardId: target.boardId,
+          valueKind: target.valueKind,
+          eligibleTargets: target
+            .eligible({
+              state: state as State,
+              playerId: playerId as never,
+              q: q as never,
+              values,
+            })
+            .map(String),
+        }) satisfies BoardTargetDomainDescriptor,
+      meta: {
+        targetKind: target.targetKind,
+        boardId: target.boardId,
+        valueKind: target.valueKind,
+      },
+    } as unknown as InputCollector<z.ZodType<Id>, State, Kind>;
+  };
+}
+
+export const vertexInput = makeBoardCollector("board-vertex");
+export const edgeInput = makeBoardCollector("board-edge");
+export const tileInput = makeBoardCollector("board-tile");
+export const spaceInput = makeBoardCollector("board-space");
+
+export function playerSpaceInput<
+  State extends CollectorState = CollectorState,
+  BoardId extends string = string,
+  SpaceId extends string = string,
+  PlayerId extends string = string,
+>(options: {
+  target: BoardTargetRule<
+    State,
+    PlayerBoardSpaceTarget<BoardId, SpaceId, PlayerId>
+  >;
+  dependsOn?: readonly InputFieldRef<string, unknown>[];
+}): InputCollector<
+  z.ZodType<PlayerBoardSpaceTarget<BoardId, SpaceId, PlayerId>>,
+  State,
+  "board-space"
+> {
+  const target = options.target;
+  const dependsOn = options.dependsOn?.map((dependency) => dependency.key);
+  return {
+    kind: "board-space",
+    schema: z.object({
+      boardId: z.literal(target.boardId),
+      playerId: z.string(),
+      spaceId: z.string(),
+    }) as unknown as z.ZodType<
+      PlayerBoardSpaceTarget<BoardId, SpaceId, PlayerId>
+    >,
+    eligibleTargets: ((state, playerId, q, values) =>
+      target
+        .eligible({
+          state: state as State,
+          playerId: playerId as never,
+          q: q as never,
+          values,
+        })
+        .map((candidate) => candidate.spaceId)) as
+      | ((
+          state: CollectorState,
+          playerId: string,
+          q: unknown,
+          values?: Readonly<Record<string, unknown>>,
+        ) => ReadonlyArray<unknown>)
+      | undefined,
+    validateTarget: ((state, playerId, q, targetValue, values) =>
+      target.validate(
+        {
+          state: state as State,
+          playerId: playerId as never,
+          q: q as never,
+          values,
+        },
+        targetValue as PlayerBoardSpaceTarget<BoardId, SpaceId, PlayerId>,
+      )) as
+      | ((
+          state: CollectorState,
+          playerId: string,
+          q: unknown,
+          targetId: unknown,
+          values?: Readonly<Record<string, unknown>>,
+        ) => ReturnType<
+          BoardTargetRule<
+            CollectorState,
+            PlayerBoardSpaceTarget<string, string, string>
+          >["validate"]
+        >)
+      | undefined,
+    ...(dependsOn ? { dependsOn } : {}),
+    domain: (
+      state: CollectorState,
+      playerId: string,
+      q: unknown,
+      _derived: unknown,
+      values?: Readonly<Record<string, unknown>>,
+    ) =>
+      ({
+        type: "boardTarget" as const,
+        projection: "resolved" as const,
+        targetKind: target.targetKind as Exclude<TargetKind, "card">,
+        boardId: target.boardId,
+        valueKind: target.valueKind,
+        eligibleTargets: target
+          .eligible({
+            state: state as State,
+            playerId: playerId as never,
+            q: q as never,
+            values,
+          })
+          .map((candidate) => candidate.spaceId),
+      }) satisfies BoardTargetDomainDescriptor,
+    meta: {
+      targetKind: target.targetKind,
+      boardId: target.boardId,
+      valueKind: target.valueKind,
+    },
+  };
+}
+
+export const boardInput = {
+  vertex: vertexInput,
+  edge: edgeInput,
+  tile: tileInput,
+  space: spaceInput,
+  playerSpace: playerSpaceInput,
+};

package/src/reducer/inputs/boardTarget.ts

@@ -0,0 +1,190 @@
+import type { CollectorState, TargetKind } from "../model/spec";
+import type { PlayerIdOfState } from "../model/extract";
+import type { TableQueriesOfState } from "../model/queries";
+import {
+  createTargetRule,
+  createTargetRuleBuilder,
+  type TargetPredicate,
+  type TargetRule,
+  type TargetRuleBuilder,
+} from "./targetRule";
+
+export type BoardTargetPredicate<
+  State extends CollectorState,
+  Target,
+> = TargetPredicate<State, Target>;
+
+export type BoardTargetRule<State extends CollectorState, Target> = TargetRule<
+  State,
+  Target
+> & {
+  readonly boardId: string;
+  readonly targetKind: TargetKind;
+  readonly valueKind: "board-id" | "player-board-space";
+};
+
+export type BoardTargetBuilder<
+  State extends CollectorState,
+  Target,
+> = TargetRuleBuilder<State, Target, BoardTargetRule<State, Target>>;
+
+export type PlayerBoardSpaceTarget<
+  BoardId extends string,
+  SpaceId extends string,
+  PlayerId extends string,
+> = {
+  readonly boardId: BoardId;
+  readonly playerId: PlayerId;
+  readonly spaceId: SpaceId;
+};
+
+function candidateIdsForKind<State extends CollectorState, Id extends string>(
+  q: TableQueriesOfState<State>,
+  boardId: string,
+  targetKind: TargetKind,
+): readonly Id[] {
+  if (targetKind === "edge") {
+    return idsFromCollection<Id>(q.board.tiled(boardId as never).edges);
+  }
+  if (targetKind === "vertex") {
+    return idsFromCollection<Id>(q.board.tiled(boardId as never).vertices);
+  }
+  return idsFromCollection<Id>(q.board.get(boardId as never)?.spaces);
+}
+
+function idsFromCollection<Id extends string>(
+  collection: unknown,
+): readonly Id[] {
+  if (!collection) return [];
+  const values = Array.isArray(collection)
+    ? collection
+    : Object.values(collection as Record<string, unknown>);
+  return values.flatMap((value) => {
+    if (typeof value === "string") return [value as Id];
+    if (
+      typeof value === "object" &&
+      value !== null &&
+      "id" in value &&
+      typeof (value as { id?: unknown }).id === "string"
+    ) {
+      return [(value as { id: string }).id as Id];
+    }
+    return [];
+  });
+}
+
+function createBoardTargetBuilder<
+  State extends CollectorState,
+  Id extends string,
+>(targetKind: TargetKind, boardId: string): BoardTargetBuilder<State, Id> {
+  return createTargetRuleBuilder<State, Id, BoardTargetRule<State, Id>>(
+    (predicates) => ({
+      ...createTargetRule(
+        ({ q }) => candidateIdsForKind<State, Id>(q, boardId, targetKind),
+        predicates,
+        {
+          missingCandidateIssue: {
+            errorCode: "BOARD_TARGET_NOT_ELIGIBLE",
+            message: "Board target is not eligible.",
+          },
+        },
+      ),
+      boardId,
+      targetKind,
+      valueKind: "board-id",
+    }),
+  );
+}
+
+function createPlayerSpaceTargetBuilder<
+  State extends CollectorState,
+  BoardId extends string,
+  SpaceId extends string,
+>(
+  boardId: BoardId,
+): BoardTargetBuilder<
+  State,
+  PlayerBoardSpaceTarget<BoardId, SpaceId, PlayerIdOfState<State>>
+> {
+  type Target = PlayerBoardSpaceTarget<
+    BoardId,
+    SpaceId,
+    PlayerIdOfState<State>
+  >;
+  return createTargetRuleBuilder<State, Target, BoardTargetRule<State, Target>>(
+    (predicates) => ({
+      ...createTargetRule(
+        ({ state, q }) => {
+          const spacesForPlayer = (playerId: string): readonly SpaceId[] =>
+            candidateIdsForKind<State, SpaceId>(
+              q,
+              `${boardId}:${playerId}`,
+              "space",
+            );
+          return state.table.playerOrder.flatMap((playerId) =>
+            spacesForPlayer(playerId).map((spaceId) => ({
+              boardId,
+              playerId: playerId as PlayerIdOfState<State>,
+              spaceId,
+            })),
+          );
+        },
+        predicates,
+        {
+          missingCandidateIssue: {
+            errorCode: "BOARD_TARGET_NOT_ELIGIBLE",
+            message: "Board target is not eligible.",
+          },
+          equals: (left, right) =>
+            isPlayerBoardSpaceTarget(left) &&
+            isPlayerBoardSpaceTarget(right) &&
+            left.boardId === right.boardId &&
+            left.playerId === right.playerId &&
+            left.spaceId === right.spaceId,
+        },
+      ),
+      boardId,
+      targetKind: "space",
+      valueKind: "player-board-space",
+    }),
+  );
+}
+
+function isPlayerBoardSpaceTarget(
+  value: unknown,
+): value is PlayerBoardSpaceTarget<string, string, string> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "boardId" in value &&
+    "playerId" in value &&
+    "spaceId" in value
+  );
+}
+
+function makeBoardTargetFactory(targetKind: TargetKind) {
+  return function target<State extends CollectorState, Id extends string>(
+    boardId: string,
+  ): BoardTargetBuilder<State, Id> {
+    return createBoardTargetBuilder<State, Id>(targetKind, boardId);
+  };
+}
+
+export const boardTarget = {
+  edge: makeBoardTargetFactory("edge"),
+  vertex: makeBoardTargetFactory("vertex"),
+  space: makeBoardTargetFactory("space"),
+  tile: makeBoardTargetFactory("tile"),
+  playerSpace<
+    State extends CollectorState,
+    BoardId extends string,
+    SpaceId extends string,
+  >(
+    boardId: BoardId,
+  ): BoardTargetBuilder<
+    State,
+    PlayerBoardSpaceTarget<BoardId, SpaceId, PlayerIdOfState<State>>
+  > {
+    return createPlayerSpaceTargetBuilder<State, BoardId, SpaceId>(boardId);
+  },
+};

package/src/reducer/inputs/cardInput.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import type { CollectorState, InputCollector } from "../model/spec";
+import type { CardIdOfState } from "../model/extract";
+import type { CardTargetRule } from "./cardTarget";
+import type { InputFieldRef } from "./defineInputs";
+
+/**
+ * `cardInput` produces a collector backed by one built `cardTarget` rule.
+ * The submitted value is a manifest-branded card id.
+ *
+ * The target rule feeds server-authoritative eligible-card projection, submit
+ * validation, and tests through its `bind({ state, playerId, q })` helper.
+ */
+export function cardInput<
+  State extends CollectorState = CollectorState,
+  Id extends string = CardIdOfState<State>,
+  const ZoneIds extends readonly string[] = readonly string[],
+>(options: {
+  target: CardTargetRule<State, Id, ZoneIds>;
+  dependsOn?: readonly InputFieldRef<string, unknown>[];
+}): InputCollector<z.ZodType<Id>, State, "card"> & {
+  readonly meta: {
+    readonly zoneId: ZoneIds[number];
+    readonly zoneIds: ZoneIds;
+    readonly targetKind: "card";
+  };
+} {
+  const target = options.target;
+  const dependsOn = options.dependsOn?.map((dependency) => dependency.key);
+  return {
+    kind: "card",
+    schema: z.string() as unknown as z.ZodType<Id>,
+    eligibleTargets: ((state, playerId, q, values) =>
+      target.eligible({
+        state: state as State,
+        playerId: playerId as never,
+        q: q as never,
+        values,
+      })) as
+      | ((
+          state: CollectorState,
+          playerId: string,
+          q: unknown,
+          values?: Readonly<Record<string, unknown>>,
+        ) => ReadonlyArray<unknown>)
+      | undefined,
+    validateTarget: ((state, playerId, q, targetId, values) =>
+      target.validate(
+        {
+          state: state as State,
+          playerId: playerId as never,
+          q: q as never,
+          values,
+        },
+        targetId as Id,
+      )) as
+      | ((
+          state: CollectorState,
+          playerId: string,
+          q: unknown,
+          targetId: unknown,
+          values?: Readonly<Record<string, unknown>>,
+        ) => ReturnType<CardTargetRule<CollectorState, string>["validate"]>)
+      | undefined,
+    ...(dependsOn ? { dependsOn } : {}),
+    domain: (state, playerId, q, _derived, values) => ({
+      type: "cardTarget" as const,
+      projection: "resolved" as const,
+      targetKind: target.targetKind,
+      zoneIds: target.zoneIds,
+      eligibleTargets: target
+        .eligible({
+          state: state as State,
+          playerId: playerId as never,
+          q: q as never,
+          values,
+        })
+        .map(String),
+    }),
+    meta: {
+      zoneId: target.zoneId,
+      zoneIds: target.zoneIds,
+      targetKind: target.targetKind,
+    },
+  };
+}

package/src/reducer/inputs/cardTarget.ts

@@ -0,0 +1,101 @@
+import type { CollectorState } from "../model/spec";
+import type { CardIdOfState } from "../model/extract";
+import {
+  createTargetRule,
+  createTargetRuleBuilder,
+  type TargetPredicate,
+  type TargetRule,
+  type TargetRuleBuilder,
+} from "./targetRule";
+
+export type CardTargetPredicate<
+  State extends CollectorState,
+  Id extends string,
+> = TargetPredicate<State, Id>;
+
+export type CardTargetRule<
+  State extends CollectorState,
+  Id extends string,
+  ZoneIds extends readonly string[] = readonly string[],
+> = TargetRule<State, Id> & {
+  readonly zoneIds: ZoneIds;
+  readonly zoneId: ZoneIds[number];
+  readonly targetKind: "card";
+};
+
+export type CardTargetBuilder<
+  State extends CollectorState,
+  Id extends string,
+  ZoneIds extends readonly string[] = readonly string[],
+> = TargetRuleBuilder<State, Id, CardTargetRule<State, Id, ZoneIds>>;
+
+function cardIdsForZone<State extends CollectorState, Id extends string>(
+  state: State,
+  playerId: string,
+  q: {
+    zone: {
+      sharedCards: (zoneId: never) => readonly unknown[];
+      playerCards: (playerId: never, zoneId: never) => readonly unknown[];
+    };
+  },
+  zoneId: string,
+): readonly Id[] {
+  const table = state.table as {
+    decks?: Record<string, unknown>;
+    hands?: Record<string, unknown>;
+    zones?: {
+      shared?: Record<string, unknown>;
+      perPlayer?: Record<string, unknown>;
+    };
+  };
+  if (
+    zoneId in (table.hands ?? {}) ||
+    zoneId in (table.zones?.perPlayer ?? {})
+  ) {
+    return q.zone.playerCards(
+      playerId as never,
+      zoneId as never,
+    ) as readonly Id[];
+  }
+  if (zoneId in (table.decks ?? {}) || zoneId in (table.zones?.shared ?? {})) {
+    return q.zone.sharedCards(zoneId as never) as readonly Id[];
+  }
+  return [];
+}
+
+function createCardTargetBuilder<
+  State extends CollectorState,
+  Id extends string,
+  ZoneIds extends readonly string[],
+>(zoneIds: ZoneIds): CardTargetBuilder<State, Id, ZoneIds> {
+  return createTargetRuleBuilder<State, Id, CardTargetRule<State, Id, ZoneIds>>(
+    (predicates) => ({
+      ...createTargetRule(
+        ({ state, playerId, q }) =>
+          zoneIds.flatMap((zoneId) =>
+            cardIdsForZone<State, Id>(state, playerId, q, zoneId),
+          ),
+        predicates,
+        {
+          missingCandidateIssue: {
+            errorCode: "CARD_TARGET_NOT_ELIGIBLE",
+            message: "Card target is not eligible.",
+          },
+        },
+      ),
+      zoneIds,
+      zoneId: zoneIds[0] as ZoneIds[number],
+      targetKind: "card",
+    }),
+  );
+}
+
+export const cardTarget = {
+  zones<
+    State extends CollectorState,
+    Id extends string = CardIdOfState<State>,
+    const ZoneIds extends readonly string[] = readonly string[],
+  >(zoneIds: ZoneIds): CardTargetBuilder<State, Id, ZoneIds> {
+    return createCardTargetBuilder<State, Id, ZoneIds>(zoneIds);
+  },
+};

package/src/reducer/inputs/choiceTarget.ts

@@ -0,0 +1,104 @@
+import type { CollectorState } from "../model/spec";
+import type { PlayerIdOfState } from "../model/extract";
+import type { TableQueriesOfState } from "../model/queries";
+import {
+  createTargetRule,
+  createTargetRuleBuilder,
+  type TargetContext,
+  type TargetPredicate,
+  type TargetRule,
+  type TargetRuleBuilder,
+} from "./targetRule";
+
+export type ChoiceTargetOption<Id extends string> = {
+  id: Id;
+  label?: string;
+};
+
+export type ChoiceOptionsFactory<
+  State extends CollectorState,
+  Id extends string,
+> = (
+  state: State,
+  playerId: PlayerIdOfState<State>,
+  q: TableQueriesOfState<State>,
+) => ReadonlyArray<ChoiceTargetOption<Id>>;
+
+export type ChoiceTargetPredicate<
+  State extends CollectorState,
+  Id extends string,
+> = TargetPredicate<State, Id>;
+
+export type ChoiceTargetRule<
+  State extends CollectorState,
+  Id extends string,
+> = TargetRule<State, Id> & {
+  readonly targetKind: "choice";
+  readonly options: (
+    ctx: TargetContext<State>,
+  ) => ReadonlyArray<ChoiceTargetOption<Id>>;
+  readonly eligibleOptions: (
+    ctx: TargetContext<State>,
+  ) => ReadonlyArray<ChoiceTargetOption<Id>>;
+};
+
+export type ChoiceTargetBuilder<
+  State extends CollectorState,
+  Id extends string,
+> = TargetRuleBuilder<State, Id, ChoiceTargetRule<State, Id>>;
+
+function normalizeOptions<State extends CollectorState, Id extends string>(
+  options:
+    | ReadonlyArray<ChoiceTargetOption<Id>>
+    | ChoiceOptionsFactory<State, Id>,
+): ChoiceOptionsFactory<State, Id> {
+  if (typeof options === "function") return options;
+  return () => options;
+}
+
+function createChoiceTargetBuilder<
+  State extends CollectorState,
+  Id extends string,
+>(
+  options:
+    | ReadonlyArray<ChoiceTargetOption<Id>>
+    | ChoiceOptionsFactory<State, Id>,
+): ChoiceTargetBuilder<State, Id> {
+  const optionsFactory = normalizeOptions(options);
+  return createTargetRuleBuilder<State, Id, ChoiceTargetRule<State, Id>>(
+    (predicates) => {
+      const baseRule = createTargetRule(
+        (ctx) =>
+          optionsFactory(ctx.state, ctx.playerId, ctx.q).map(
+            (option) => option.id,
+          ),
+        predicates,
+        {
+          missingCandidateIssue: {
+            errorCode: "CHOICE_TARGET_NOT_ELIGIBLE",
+            message: "Choice target is not eligible.",
+          },
+        },
+      );
+      return {
+        ...baseRule,
+        targetKind: "choice",
+        options: (ctx) => optionsFactory(ctx.state, ctx.playerId, ctx.q),
+        eligibleOptions: (ctx) =>
+          optionsFactory(ctx.state, ctx.playerId, ctx.q).filter((option) =>
+            baseRule.isEligible(ctx, option.id),
+          ),
+      };
+    },
+  );
+}
+
+export const choiceTarget = {
+  options<State extends CollectorState, Id extends string>(
+    options:
+      | ReadonlyArray<ChoiceTargetOption<Id>>
+      | ChoiceOptionsFactory<State, Id>,
+  ): ChoiceTargetBuilder<State, Id> {
+    return createChoiceTargetBuilder(options);
+  },
+};