@dreamboard-games/sdk 0.2.0

package/src/ui/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/ui/components/board/target-layer.ts

@@ -0,0 +1,66 @@
+export type BoardTargetKind = "edge" | "vertex" | "space" | "tile";
+
+export interface InteractiveTargetState {
+  kind?: BoardTargetKind;
+  id: string;
+  eligible: boolean;
+  selectable: boolean;
+  hovered: boolean;
+  pending: boolean;
+  conflict: boolean;
+  unavailableReason?: string;
+  select?: () => unknown | Promise<unknown>;
+}
+
+export interface InteractiveTargetLayer {
+  enabled?: boolean;
+  eligible?: ReadonlySet<string>;
+  selectTargetId?: (targetId: string) => unknown | Promise<unknown>;
+  targetState?: (targetId: string) => Partial<InteractiveTargetState>;
+}
+
+export interface InteractiveTargetRenderState extends InteractiveTargetState {
+  isEnabled: boolean;
+  isEligible: boolean;
+  isHovered: boolean;
+}
+
+export function interactiveTargetRenderState(
+  layer: InteractiveTargetLayer,
+  targetId: string,
+  isHovered: boolean,
+): InteractiveTargetRenderState {
+  const enabled = layer.enabled !== false;
+  const eligible = layer.eligible?.has(targetId) ?? true;
+  const extra = layer.targetState?.(targetId) ?? {};
+  const selectable =
+    extra.selectable ?? (enabled && eligible && !!layer.selectTargetId);
+  return {
+    id: targetId,
+    ...extra,
+    eligible: extra.eligible ?? eligible,
+    selectable,
+    hovered: isHovered,
+    pending: extra.pending ?? false,
+    conflict: extra.conflict ?? false,
+    select:
+      extra.select ??
+      (layer.selectTargetId
+        ? () => layer.selectTargetId?.(targetId)
+        : undefined),
+    isEnabled: enabled,
+    isEligible: extra.eligible ?? eligible,
+    isHovered,
+  };
+}
+
+export function isInteractiveTargetSelectable(
+  layer: InteractiveTargetLayer,
+  state: InteractiveTargetRenderState,
+): boolean {
+  return (
+    state.isEnabled &&
+    state.selectable &&
+    !!(state.select ?? layer.selectTargetId)
+  );
+}

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

@@ -0,0 +1,27 @@
+import type { ViewCard } from "../index.js";
+import type { CardFaceProps } 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<CardFaceProps<TypedCard>["renderContent"]>
+>[0];
+
+type _CardIdIsPreserved = ExpectExtends<RenderContentCard["id"], "tech-card-1">;
+type _CardTypeIsPreserved = ExpectExtends<
+  RenderContentCard["cardType"],
+  "breakthrough"
+>;
+type _PropertiesArePreserved = ExpectExtends<
+  RenderContentCard["properties"]["cost"],
+  number
+>;

package/src/ui/components/hand-layout-math.ts

@@ -0,0 +1,163 @@
+/**
+ * Pure layout math for the controlled `HandView`.
+ *
+ * The functions here are independent of React and DOM measurement so they can
+ * be unit-tested directly. {@link computeFanLayout} matches the algorithm
+ * documented in `docs/references/ui-sdk-mobile-hand-and-card-interactions.md`,
+ * and {@link chooseHandLayoutMode} translates a measured container width and a
+ * caller policy into the actual presentation mode the hand should render.
+ */
+
+export type HandPresentationMode = "fan" | "compressed-fan" | "strip" | "tray";
+
+export interface FanLayoutOptions {
+  availableWidth: number;
+  cardWidth: number;
+  cardHeight: number;
+  count: number;
+  /** Minimum visible slice for any card (touch readability floor). */
+  minVisibleSlice: number;
+  /** Maximum tilt of the outermost card, in degrees. */
+  maxAngle: number;
+  /** How many pixels the outermost cards drop below the center card. */
+  arcDepth: number;
+}
+
+export interface FanCardPosition {
+  left: number;
+  rotate: number;
+  translateY: number;
+  zIndex: number;
+}
+
+export interface FanLayoutResult {
+  positions: FanCardPosition[];
+  /** Step between successive card origins (left offset). */
+  step: number;
+  /** Minimum bounding width of the laid-out hand. */
+  totalWidth: number;
+  /** Visible portion of each card after overlap, in pixels. */
+  visibleSlice: number;
+}
+
+export function computeFanLayout(options: FanLayoutOptions): FanLayoutResult {
+  const {
+    availableWidth,
+    cardWidth,
+    count,
+    minVisibleSlice,
+    maxAngle,
+    arcDepth,
+  } = options;
+  if (count <= 0) {
+    return { positions: [], step: 0, totalWidth: 0, visibleSlice: cardWidth };
+  }
+  if (count === 1) {
+    return {
+      positions: [{ left: 0, rotate: 0, translateY: 0, zIndex: 1 }],
+      step: cardWidth,
+      totalWidth: cardWidth,
+      visibleSlice: cardWidth,
+    };
+  }
+
+  const idealStep =
+    availableWidth > cardWidth
+      ? (availableWidth - cardWidth) / (count - 1)
+      : minVisibleSlice;
+  const step = Math.max(minVisibleSlice, Math.min(cardWidth, idealStep));
+  const center = (count - 1) / 2;
+
+  const positions: FanCardPosition[] = Array.from(
+    { length: count },
+    (_, index) => {
+      const t = center === 0 ? 0 : (index - center) / center;
+      return {
+        left: index * step,
+        rotate: t * maxAngle,
+        translateY: Math.abs(t) * arcDepth,
+        zIndex: index + 1,
+      };
+    },
+  );
+
+  return {
+    positions,
+    step,
+    totalWidth: cardWidth + (count - 1) * step,
+    visibleSlice: step,
+  };
+}
+
+export interface ChooseHandLayoutModeOptions {
+  /** Measured container width in CSS pixels. `0` means unmeasured. */
+  containerWidth: number;
+  cardCount: number;
+  cardWidth: number;
+  /**
+   * Caller-stated layout preference. The pair represents the desktop/mobile
+   * intent — the visible-slice gate decides which one renders.
+   */
+  desktop: HandPresentationMode;
+  mobile: HandPresentationMode;
+  /** Minimum visible per-card slice that still feels touch-usable. */
+  comfortableSlice?: number;
+  /** Floor for compressed fan; below this the mobile fallback wins. */
+  compressedSlice?: number;
+}
+
+/**
+ * Choose the actual presentation mode for the current viewport.
+ *
+ * The decision is target-exposure based, not breakpoint based:
+ *
+ * - if the desktop preference fits with a comfortable slice, render it as-is;
+ * - if it would only barely fit, use a `compressed-fan` when the desktop side
+ *   is fan-like;
+ * - otherwise switch to the mobile fallback (`tray`, `strip`, or whatever the
+ *   caller asked for) so playable targets stay usable.
+ */
+export function chooseHandLayoutMode({
+  containerWidth,
+  cardCount,
+  cardWidth,
+  desktop,
+  mobile,
+  comfortableSlice = HAND_MODE_GEOMETRY.fan.minVisibleSlice,
+  compressedSlice = HAND_MODE_GEOMETRY["compressed-fan"].minVisibleSlice,
+}: ChooseHandLayoutModeOptions): HandPresentationMode {
+  if (cardCount <= 1) return desktop;
+  if (containerWidth <= 0) return desktop;
+
+  const idealStep = (containerWidth - cardWidth) / (cardCount - 1);
+  const step = Math.max(0, Math.min(cardWidth, idealStep));
+
+  const desktopIsFanLike = desktop === "fan" || desktop === "compressed-fan";
+  if (!desktopIsFanLike) {
+    if (containerWidth >= cardWidth * cardCount) return desktop;
+    return mobile;
+  }
+
+  if (step >= comfortableSlice) {
+    return desktop === "compressed-fan" ? "compressed-fan" : "fan";
+  }
+  if (step >= compressedSlice) {
+    return "compressed-fan";
+  }
+  return mobile;
+}
+
+export interface HandModeGeometry {
+  minVisibleSlice: number;
+  maxAngle: number;
+  arcDepth: number;
+}
+
+/** Recommended starting values from the mobile-hand reference. */
+export const HAND_MODE_GEOMETRY: Record<
+  Exclude<HandPresentationMode, "tray" | "strip">,
+  HandModeGeometry
+> = {
+  fan: { minVisibleSlice: 64, maxAngle: 5, arcDepth: 12 },
+  "compressed-fan": { minVisibleSlice: 44, maxAngle: 4, arcDepth: 8 },
+};

package/src/ui/components/hand-pointer-engine.ts

@@ -0,0 +1,413 @@
+/**
+ * Deterministic pointer recognizer for the controlled hand view.
+ *
+ * The engine is independent from React: it consumes pointer events and a
+ * caller-supplied callbacks bag, and produces semantic gesture events. It
+ * owns no DOM, emits no `CardIntent`, and does not track the drag-lifecycle
+ * `phase` — that responsibility lives in `CardDragSurface`. The engine only
+ * recognizes `tap`, `previewStart`/`previewEnd`, `liftStart`/`liftMove`/
+ * `liftEnd`/`liftCancel`, and a `horizontalBrowse` informational signal.
+ *
+ * The thresholds match
+ * `docs/references/ui-sdk-mobile-hand-and-card-interactions.md`:
+ *
+ * | Threshold                 | Default     |
+ * | ------------------------- | ----------- |
+ * | Press preview delay       | `220ms`     |
+ * | Movement slop             | `8px`       |
+ * | Axis bias                 | `1.25`      |
+ * | Drag lift distance        | `28px`      |
+ *
+ * Callers wire the engine's `handlePointerDown` / `handlePointerMove` /
+ * `handlePointerUp` / `handlePointerCancel` to the matching DOM events on
+ * each interactive card.
+ */
+
+export type HandInteractionPolicy = "direct-activate" | "drag-to-target";
+
+/**
+ * Internal recognition state. Not exposed to consumers because drag-lifecycle
+ * phases (`inspecting`/`dragging`/`settling`/`returning`) live in
+ * `CardDragSurface`.
+ */
+export type CardPointerState =
+  | { kind: "idle" }
+  | { kind: "pressing"; pointerId: number; cardId: string; startedAt: number }
+  | { kind: "preview"; pointerId: number; cardId: string }
+  | { kind: "horizontalBrowse"; pointerId: number; cardId: string }
+  | { kind: "lifted"; pointerId: number; cardId: string };
+
+export interface PointerEngineThresholds {
+  pressPreviewMs: number;
+  movementSlopPx: number;
+  axisBiasRatio: number;
+  dragLiftDistancePx: number;
+}
+
+export const DEFAULT_POINTER_THRESHOLDS: PointerEngineThresholds = {
+  pressPreviewMs: 220,
+  movementSlopPx: 8,
+  axisBiasRatio: 1.25,
+  dragLiftDistancePx: 28,
+};
+
+export type AxisDecision = "undecided" | "horizontal" | "upward";
+
+export function resolveAxis(
+  dx: number,
+  dy: number,
+  thresholds: PointerEngineThresholds = DEFAULT_POINTER_THRESHOLDS,
+): AxisDecision {
+  if (
+    Math.abs(dx) < thresholds.movementSlopPx &&
+    Math.abs(dy) < thresholds.movementSlopPx
+  ) {
+    return "undecided";
+  }
+  if (Math.abs(dx) > Math.abs(dy) * thresholds.axisBiasRatio)
+    return "horizontal";
+  if (-dy > Math.abs(dx) * thresholds.axisBiasRatio) return "upward";
+  return "undecided";
+}
+
+export interface PointerEngineCardSnapshot {
+  cardId: string;
+  /** Whether the runtime adapter says this card is interactive. */
+  eligible: boolean;
+  /** Whether the runtime adapter says this card is disabled. */
+  disabled: boolean;
+}
+
+export interface LiftStartEvent {
+  cardId: string;
+  pointerId: number;
+  startX: number;
+  startY: number;
+  pointerX: number;
+  pointerY: number;
+  grabOffsetX: number;
+  grabOffsetY: number;
+}
+
+export interface LiftMoveEvent {
+  cardId: string;
+  pointerId: number;
+  pointerX: number;
+  pointerY: number;
+}
+
+export interface LiftEndEvent {
+  cardId: string;
+  pointerId: number;
+  pointerX: number;
+  pointerY: number;
+}
+
+export interface PointerEngineCallbacks {
+  /**
+   * Recognized clean tap (no movement, no preview). Source is `pointer` for
+   * pointerup taps; the keyboard activation path is a separate caller method
+   * (see `triggerKeyboardActivate`/`triggerKeyboardLift`).
+   */
+  onTap?: (cardId: string) => void;
+  /** Long-press preview started. */
+  onPreviewStart?: (cardId: string) => void;
+  /** Preview ended (release or axis disqualification). */
+  onPreviewEnd?: (cardId: string) => void;
+  /** Vertical lift gesture began past the drag threshold. */
+  onLiftStart?: (event: LiftStartEvent) => void;
+  /** Pointer move while lifted. */
+  onLiftMove?: (event: LiftMoveEvent) => void;
+  /** Pointer release while lifted. */
+  onLiftEnd?: (event: LiftEndEvent) => void;
+  /** Lift was cancelled (pointer cancel/lost capture). */
+  onLiftCancel?: (cardId: string) => void;
+  /** Horizontal browse arbitration (informational). */
+  onHorizontalBrowse?: (cardId: string) => void;
+  /**
+   * Called when the engine has captured the pointer and wants the host to
+   * suppress scrolling. The host controls the `touch-action` value.
+   */
+  onLockScroll?: (locked: boolean) => void;
+  /** Called whenever the recognition state transitions, for visual hints. */
+  onStateChange?: (next: CardPointerState) => void;
+}
+
+interface ActivePointer {
+  cardId: string;
+  pointerId: number;
+  startedAt: number;
+  startX: number;
+  startY: number;
+  lastX: number;
+  lastY: number;
+  axis: AxisDecision;
+  /** Set when the long-press preview timer fires. */
+  previewActive: boolean;
+}
+
+export class HandPointerEngine {
+  private readonly callbacks: PointerEngineCallbacks;
+  private readonly thresholds: PointerEngineThresholds;
+  private active: ActivePointer | null = null;
+  private state: CardPointerState = { kind: "idle" };
+  private previewTimer: ReturnType<typeof setTimeout> | null = null;
+  private now: () => number;
+
+  constructor(
+    callbacks: PointerEngineCallbacks,
+    thresholds: PointerEngineThresholds = DEFAULT_POINTER_THRESHOLDS,
+    now: () => number = () => Date.now(),
+  ) {
+    this.callbacks = callbacks;
+    this.thresholds = thresholds;
+    this.now = now;
+  }
+
+  /** Returns the most recently emitted recognition state (test helper). */
+  getState(): CardPointerState {
+    return this.state;
+  }
+
+  dispose(): void {
+    this.clearPreviewTimer();
+    if (this.state.kind === "lifted") {
+      this.callbacks.onLiftCancel?.(this.state.cardId);
+    }
+    this.active = null;
+    this.transition({ kind: "idle" });
+    this.callbacks.onLockScroll?.(false);
+  }
+
+  handlePointerDown(
+    card: PointerEngineCardSnapshot,
+    event: { pointerId: number; clientX: number; clientY: number },
+  ): void {
+    if (this.active) return;
+    if (card.disabled) return;
+
+    const startedAt = this.now();
+    this.active = {
+      cardId: card.cardId,
+      pointerId: event.pointerId,
+      startedAt,
+      startX: event.clientX,
+      startY: event.clientY,
+      lastX: event.clientX,
+      lastY: event.clientY,
+      axis: "undecided",
+      previewActive: false,
+    };
+    this.transition({
+      kind: "pressing",
+      pointerId: event.pointerId,
+      cardId: card.cardId,
+      startedAt,
+    });
+    this.schedulePreview(card);
+  }
+
+  handlePointerMove(
+    card: PointerEngineCardSnapshot,
+    event: { pointerId: number; clientX: number; clientY: number },
+  ): void {
+    const pointer = this.active;
+    if (!pointer || pointer.pointerId !== event.pointerId) return;
+    if (pointer.cardId !== card.cardId) return;
+
+    pointer.lastX = event.clientX;
+    pointer.lastY = event.clientY;
+
+    const dx = event.clientX - pointer.startX;
+    const dy = event.clientY - pointer.startY;
+    const axis = resolveAxis(dx, dy, this.thresholds);
+    if (axis !== "undecided") pointer.axis = axis;
+
+    if (this.state.kind === "lifted") {
+      this.callbacks.onLiftMove?.({
+        cardId: pointer.cardId,
+        pointerId: pointer.pointerId,
+        pointerX: event.clientX,
+        pointerY: event.clientY,
+      });
+      return;
+    }
+
+    if (this.state.kind === "pressing") {
+      if (axis === "horizontal") {
+        this.clearPreviewTimer();
+        this.transition({
+          kind: "horizontalBrowse",
+          pointerId: pointer.pointerId,
+          cardId: pointer.cardId,
+        });
+        this.callbacks.onHorizontalBrowse?.(pointer.cardId);
+        return;
+      }
+      if (
+        axis === "upward" &&
+        card.eligible &&
+        -dy >= this.thresholds.dragLiftDistancePx
+      ) {
+        this.clearPreviewTimer();
+        this.beginLift(pointer, event.clientX, event.clientY);
+        return;
+      }
+      return;
+    }
+
+    if (this.state.kind === "preview") {
+      if (
+        axis === "upward" &&
+        card.eligible &&
+        -dy >= this.thresholds.dragLiftDistancePx
+      ) {
+        this.callbacks.onPreviewEnd?.(card.cardId);
+        pointer.previewActive = false;
+        this.beginLift(pointer, event.clientX, event.clientY);
+        return;
+      }
+      if (axis === "horizontal") {
+        this.callbacks.onPreviewEnd?.(card.cardId);
+        pointer.previewActive = false;
+        this.transition({
+          kind: "horizontalBrowse",
+          pointerId: pointer.pointerId,
+          cardId: pointer.cardId,
+        });
+        this.callbacks.onHorizontalBrowse?.(pointer.cardId);
+        return;
+      }
+      return;
+    }
+
+    // horizontalBrowse — remain locked until release.
+  }
+
+  handlePointerUp(
+    card: PointerEngineCardSnapshot,
+    event: { pointerId: number; clientX: number; clientY: number },
+  ): void {
+    const pointer = this.active;
+    if (!pointer || pointer.pointerId !== event.pointerId) return;
+    if (pointer.cardId !== card.cardId) return;
+    this.clearPreviewTimer();
+
+    const dx = event.clientX - pointer.startX;
+    const dy = event.clientY - pointer.startY;
+    const isTap =
+      pointer.axis === "undecided" &&
+      !pointer.previewActive &&
+      Math.abs(dx) < this.thresholds.movementSlopPx &&
+      Math.abs(dy) < this.thresholds.movementSlopPx;
+
+    if (this.state.kind === "lifted") {
+      this.callbacks.onLiftEnd?.({
+        cardId: pointer.cardId,
+        pointerId: pointer.pointerId,
+        pointerX: event.clientX,
+        pointerY: event.clientY,
+      });
+      this.reset();
+      return;
+    }
+
+    if (isTap) {
+      if (card.eligible && !card.disabled) {
+        this.callbacks.onTap?.(card.cardId);
+      }
+      this.reset();
+      return;
+    }
+
+    if (pointer.previewActive) {
+      this.callbacks.onPreviewEnd?.(card.cardId);
+    }
+    this.reset();
+  }
+
+  handlePointerCancel(card: PointerEngineCardSnapshot): void {
+    const pointer = this.active;
+    if (!pointer || pointer.cardId !== card.cardId) return;
+    this.clearPreviewTimer();
+    if (this.state.kind === "lifted") {
+      this.callbacks.onLiftCancel?.(card.cardId);
+      this.reset();
+      return;
+    }
+    if (pointer.previewActive) {
+      this.callbacks.onPreviewEnd?.(card.cardId);
+    }
+    this.reset();
+  }
+
+  /**
+   * Programmatic reset of recognition state (e.g. after the surface commits
+   * a keyboard lift externally). Does not emit callbacks.
+   */
+  resetRecognition(): void {
+    this.clearPreviewTimer();
+    this.active = null;
+    this.callbacks.onLockScroll?.(false);
+    this.transition({ kind: "idle" });
+  }
+
+  private beginLift(
+    pointer: ActivePointer,
+    clientX: number,
+    clientY: number,
+  ): void {
+    this.callbacks.onLockScroll?.(true);
+    const grabOffsetX = clientX - pointer.startX;
+    const grabOffsetY = clientY - pointer.startY;
+    this.transition({
+      kind: "lifted",
+      pointerId: pointer.pointerId,
+      cardId: pointer.cardId,
+    });
+    this.callbacks.onLiftStart?.({
+      cardId: pointer.cardId,
+      pointerId: pointer.pointerId,
+      startX: pointer.startX,
+      startY: pointer.startY,
+      pointerX: clientX,
+      pointerY: clientY,
+      grabOffsetX,
+      grabOffsetY,
+    });
+  }
+
+  private schedulePreview(card: PointerEngineCardSnapshot): void {
+    this.clearPreviewTimer();
+    this.previewTimer = setTimeout(() => {
+      const pointer = this.active;
+      if (!pointer || pointer.cardId !== card.cardId) return;
+      if (pointer.axis !== "undecided") return;
+      pointer.previewActive = true;
+      this.callbacks.onPreviewStart?.(card.cardId);
+      this.transition({
+        kind: "preview",
+        pointerId: pointer.pointerId,
+        cardId: card.cardId,
+      });
+    }, this.thresholds.pressPreviewMs);
+  }
+
+  private clearPreviewTimer(): void {
+    if (this.previewTimer !== null) {
+      clearTimeout(this.previewTimer);
+      this.previewTimer = null;
+    }
+  }
+
+  private reset(): void {
+    this.active = null;
+    this.callbacks.onLockScroll?.(false);
+    this.transition({ kind: "idle" });
+  }
+
+  private transition(next: CardPointerState): void {
+    this.state = next;
+    this.callbacks.onStateChange?.(next);
+  }
+}