@dreamboard-games/sdk 0.2.0

package/src/ui/hooks/useHexGrid.ts

@@ -0,0 +1,185 @@
+/**
+ * useHexGrid hook - Headless logic for hex grid games
+ *
+ * Provides utilities for:
+ * - Coordinate conversion and neighbor finding
+ * - Distance calculations
+ * - Tile lookups
+ *
+ * @example
+ * ```tsx
+ * const { getNeighbors, getDistance, getTile } = useHexGrid(tiles);
+ *
+ * // Find all adjacent tiles
+ * const neighbors = getNeighbors('center');
+ *
+ * // Check if two tiles are adjacent
+ * const isAdjacent = getDistance('tile1', 'tile2') === 1;
+ * ```
+ */
+
+import { useMemo, useCallback } from "react";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface HexTileData {
+  /** Unique tile identifier */
+  id: string;
+  /** Axial coordinate Q */
+  q: number;
+  /** Axial coordinate R */
+  r: number;
+  /** Tile type */
+  type?: string;
+  /** Additional data */
+  data?: Record<string, unknown>;
+}
+
+export interface UseHexGridReturn {
+  /** Get a tile by ID */
+  getTile: (tileId: string) => HexTileData | undefined;
+  /** Get a tile by coordinates */
+  getTileAt: (q: number, r: number) => HexTileData | undefined;
+  /** Get neighboring tiles */
+  getNeighbors: (tileId: string) => HexTileData[];
+  /** Get distance between two tiles */
+  getDistance: (fromId: string, toId: string) => number;
+  /** Get all tiles within a range */
+  getHexesInRange: (centerId: string, range: number) => HexTileData[];
+  /** Convert axial to cube coordinates */
+  axialToCube: (q: number, r: number) => { x: number; y: number; z: number };
+  /** Convert cube to axial coordinates */
+  cubeToAxial: (x: number, y: number, z: number) => { q: number; r: number };
+}
+
+// ============================================================================
+// Axial direction vectors
+// ============================================================================
+
+const AXIAL_DIRECTIONS = [
+  { q: 1, r: 0 },
+  { q: 1, r: -1 },
+  { q: 0, r: -1 },
+  { q: -1, r: 0 },
+  { q: -1, r: 1 },
+  { q: 0, r: 1 },
+];
+
+// ============================================================================
+// Hook Implementation
+// ============================================================================
+
+export function useHexGrid(tiles: HexTileData[]): UseHexGridReturn {
+  // Create lookup maps
+  const tileById = useMemo(() => {
+    return new Map(tiles.map((t) => [t.id, t]));
+  }, [tiles]);
+
+  const tileByCoord = useMemo(() => {
+    return new Map(tiles.map((t) => [`${t.q},${t.r}`, t]));
+  }, [tiles]);
+
+  // Get tile by ID
+  const getTile = useCallback(
+    (tileId: string): HexTileData | undefined => {
+      return tileById.get(tileId);
+    },
+    [tileById],
+  );
+
+  // Get tile by coordinates
+  const getTileAt = useCallback(
+    (q: number, r: number): HexTileData | undefined => {
+      return tileByCoord.get(`${q},${r}`);
+    },
+    [tileByCoord],
+  );
+
+  // Get neighboring tiles
+  const getNeighbors = useCallback(
+    (tileId: string): HexTileData[] => {
+      const tile = tileById.get(tileId);
+      if (!tile) return [];
+
+      const neighbors: HexTileData[] = [];
+      for (const dir of AXIAL_DIRECTIONS) {
+        const neighbor = tileByCoord.get(`${tile.q + dir.q},${tile.r + dir.r}`);
+        if (neighbor) {
+          neighbors.push(neighbor);
+        }
+      }
+      return neighbors;
+    },
+    [tileById, tileByCoord],
+  );
+
+  // Calculate distance between two tiles
+  const getDistance = useCallback(
+    (fromId: string, toId: string): number => {
+      const from = tileById.get(fromId);
+      const to = tileById.get(toId);
+      if (!from || !to) return Infinity;
+
+      // Hex distance formula using axial coordinates
+      return (
+        (Math.abs(from.q - to.q) +
+          Math.abs(from.q + from.r - to.q - to.r) +
+          Math.abs(from.r - to.r)) /
+        2
+      );
+    },
+    [tileById],
+  );
+
+  // Get all tiles within range
+  const getHexesInRange = useCallback(
+    (centerId: string, range: number): HexTileData[] => {
+      const center = tileById.get(centerId);
+      if (!center) return [];
+
+      const results: HexTileData[] = [];
+
+      for (let dq = -range; dq <= range; dq++) {
+        const minR = Math.max(-range, -dq - range);
+        const maxR = Math.min(range, -dq + range);
+        for (let dr = minR; dr <= maxR; dr++) {
+          const tile = tileByCoord.get(`${center.q + dq},${center.r + dr}`);
+          if (tile) {
+            results.push(tile);
+          }
+        }
+      }
+
+      return results;
+    },
+    [tileById, tileByCoord],
+  );
+
+  // Convert axial to cube coordinates
+  const axialToCube = useCallback(
+    (q: number, r: number): { x: number; y: number; z: number } => {
+      return { x: q, z: r, y: -q - r };
+    },
+    [],
+  );
+
+  // Convert cube to axial coordinates
+  const cubeToAxial = useCallback(
+    (x: number, _y: number, z: number): { q: number; r: number } => {
+      return { q: x, r: z };
+    },
+    [],
+  );
+
+  return {
+    getTile,
+    getTileAt,
+    getNeighbors,
+    getDistance,
+    getHexesInRange,
+    axialToCube,
+    cubeToAxial,
+  };
+}

package/src/ui/hooks/useIsMobile.ts

@@ -0,0 +1,35 @@
+import { useState, useEffect } from "react";
+
+const MOBILE_BREAKPOINT = 768;
+
+/**
+ * Hook to detect if the user is on a mobile/small screen device
+ * @param breakpoint - The width threshold in pixels (default: 768)
+ * @returns boolean indicating if the screen is mobile-sized
+ */
+export function useIsMobile(breakpoint: number = MOBILE_BREAKPOINT): boolean {
+  const [isMobile, setIsMobile] = useState(() => {
+    // SSR-safe: default to false if window is not available
+    if (typeof window === "undefined") return false;
+    return window.innerWidth < breakpoint;
+  });
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+
+    const mediaQuery = window.matchMedia(`(max-width: ${breakpoint - 1}px)`);
+
+    const handleChange = (e: MediaQueryListEvent | MediaQueryList) => {
+      setIsMobile(e.matches);
+    };
+
+    // Set initial value
+    handleChange(mediaQuery);
+
+    // Listen for changes
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
+  }, [breakpoint]);
+
+  return isMobile;
+}

package/src/ui/hooks/usePanZoom.ts

@@ -0,0 +1,278 @@
+/**
+ * usePanZoom hook - Unified pan and zoom gestures using @use-gesture/react
+ *
+ * Provides a declarative API for pan and zoom interactions on board components.
+ * Works with both SVG (via viewBox) and HTML (via CSS transforms) elements.
+ *
+ * Features:
+ * - Single finger/mouse drag for panning
+ * - Pinch-to-zoom on touch devices
+ * - Mouse wheel zoom on desktop
+ * - Configurable zoom limits
+ * - Optional momentum/inertia
+ *
+ * @example SVG usage (NetworkGraph, HexGrid, etc.)
+ * ```tsx
+ * const { transform, bind, resetTransform } = usePanZoom({
+ *   enabled: enablePanZoom,
+ *   minZoom: 0.5,
+ *   maxZoom: 3,
+ * });
+ *
+ * // Apply to viewBox calculation
+ * const viewBoxWidth = contentWidth / transform.zoom;
+ * const viewBoxX = baseX - transform.pan.x;
+ *
+ * <svg {...bind()} style={{ touchAction: 'none' }}>
+ *   ...
+ * </svg>
+ * ```
+ *
+ * @example HTML usage (SlotSystem, etc.)
+ * ```tsx
+ * const { transform, bind, style } = usePanZoom({
+ *   enabled: enablePanZoom,
+ *   mode: 'css',
+ * });
+ *
+ * <div {...bind()} style={{ ...style, touchAction: 'none' }}>
+ *   ...
+ * </div>
+ * ```
+ */
+
+import { useState, useCallback, useEffect, useMemo } from "react";
+import { useGesture, type Handler } from "@use-gesture/react";
+
+export interface PanZoomTransform {
+  /** Current zoom level (1 = 100%) */
+  zoom: number;
+  /** Current pan offset */
+  pan: { x: number; y: number };
+}
+
+export interface UsePanZoomOptions {
+  /** Whether pan/zoom is enabled */
+  enabled?: boolean;
+  /** Initial zoom level */
+  initialZoom?: number;
+  /** Minimum zoom level */
+  minZoom?: number;
+  /** Maximum zoom level */
+  maxZoom?: number;
+  /** Initial pan offset */
+  initialPan?: { x: number; y: number };
+  /** Transform mode: 'viewbox' for SVG, 'css' for HTML elements */
+  mode?: "viewbox" | "css";
+  /** Zoom sensitivity for wheel events (default: 0.002) */
+  wheelSensitivity?: number;
+  /** Called when transform changes */
+  onTransformChange?: (transform: PanZoomTransform) => void;
+}
+
+/** Type for gesture bind function that returns props to spread on element
+ * Note: We omit ref from the return type to avoid conflicts with explicit refs on elements.
+ * The gesture library handles its own internal ref binding.
+ */
+type GestureBindFunction = () => Omit<React.HTMLAttributes<Element>, "ref">;
+
+export interface UsePanZoomReturn {
+  /** Current transform state */
+  transform: PanZoomTransform;
+  /** Gesture handlers to spread on the target element - always returns spreadable props */
+  bind: GestureBindFunction;
+  /** Reset transform to initial values */
+  resetTransform: () => void;
+  /** Set zoom programmatically */
+  setZoom: (zoom: number) => void;
+  /** Set pan programmatically */
+  setPan: (pan: { x: number; y: number }) => void;
+  /** CSS transform style (for mode: 'css') */
+  style: React.CSSProperties;
+  /** Whether currently dragging/panning */
+  isDragging: boolean;
+  /** Whether currently pinching */
+  isPinching: boolean;
+}
+
+/**
+ * Hook for pan and zoom gestures on board components
+ */
+export function usePanZoom(options: UsePanZoomOptions = {}): UsePanZoomReturn {
+  const {
+    enabled = true,
+    initialZoom = 1,
+    minZoom = 0.5,
+    maxZoom = 3,
+    initialPan = { x: 0, y: 0 },
+    mode = "viewbox",
+    wheelSensitivity = 0.002,
+    onTransformChange,
+  } = options;
+
+  const [zoom, setZoomState] = useState(initialZoom);
+  const [pan, setPanState] = useState(initialPan);
+  const [isDragging, setIsDragging] = useState(false);
+  const [isPinching, setIsPinching] = useState(false);
+
+  // Clamp zoom to bounds
+  const clampZoom = useCallback(
+    (z: number) => Math.min(maxZoom, Math.max(minZoom, z)),
+    [minZoom, maxZoom],
+  );
+
+  // Update transform and notify
+  const updateTransform = useCallback(
+    (newZoom: number, newPan: { x: number; y: number }) => {
+      const clampedZoom = clampZoom(newZoom);
+      setZoomState(clampedZoom);
+      setPanState(newPan);
+      onTransformChange?.({ zoom: clampedZoom, pan: newPan });
+    },
+    [clampZoom, onTransformChange],
+  );
+
+  // Gesture bindings
+  const bind = useGesture(
+    {
+      onDrag: (({
+        delta: [dx, dy],
+        active,
+        pinching,
+      }: Parameters<Handler<"drag">>[0]) => {
+        if (!enabled || pinching) return;
+
+        setIsDragging(active);
+
+        if (active) {
+          // For viewbox mode, we invert and scale the delta
+          // For CSS mode, we apply directly
+          const scaleFactor = mode === "viewbox" ? 1 / zoom : 1;
+          setPanState((prev) => ({
+            x: prev.x + dx * scaleFactor,
+            y: prev.y + dy * scaleFactor,
+          }));
+        }
+      }) as Handler<"drag">,
+      onPinch: (({
+        offset: [scale],
+        active,
+      }: Parameters<Handler<"pinch">>[0]) => {
+        if (!enabled) return;
+
+        setIsPinching(active);
+
+        if (active) {
+          const newZoom = clampZoom(scale);
+          setZoomState(newZoom);
+          onTransformChange?.({ zoom: newZoom, pan });
+        }
+      }) as Handler<"pinch">,
+      onWheel: (({ delta: [, dy], event }: Parameters<Handler<"wheel">>[0]) => {
+        if (!enabled) return;
+
+        event.preventDefault();
+        const newZoom = clampZoom(zoom - dy * wheelSensitivity);
+        setZoomState(newZoom);
+        onTransformChange?.({ zoom: newZoom, pan });
+      }) as Handler<"wheel">,
+    },
+    {
+      drag: {
+        enabled,
+        filterTaps: true,
+      },
+      pinch: {
+        enabled,
+        scaleBounds: { min: minZoom, max: maxZoom },
+        from: () => [zoom, 0],
+      },
+      wheel: {
+        enabled,
+        eventOptions: { passive: false },
+      },
+    },
+  );
+
+  // Reset to initial values
+  const resetTransform = useCallback(() => {
+    updateTransform(initialZoom, initialPan);
+  }, [initialZoom, initialPan, updateTransform]);
+
+  useEffect(() => {
+    updateTransform(initialZoom, initialPan);
+  }, [initialZoom, initialPan.x, initialPan.y, updateTransform]);
+
+  // Programmatic setters
+  const setZoom = useCallback(
+    (newZoom: number) => {
+      updateTransform(clampZoom(newZoom), pan);
+    },
+    [pan, clampZoom, updateTransform],
+  );
+
+  const setPan = useCallback(
+    (newPan: { x: number; y: number }) => {
+      updateTransform(zoom, newPan);
+    },
+    [zoom, updateTransform],
+  );
+
+  // CSS transform style for HTML mode
+  const style = useMemo<React.CSSProperties>(
+    () =>
+      mode === "css"
+        ? {
+            transform: `translate(${pan.x}px, ${pan.y}px) scale(${zoom})`,
+            transformOrigin: "center center",
+          }
+        : {},
+    [mode, pan.x, pan.y, zoom],
+  );
+
+  // Current transform state
+  const transform = useMemo<PanZoomTransform>(
+    () => ({ zoom, pan }),
+    [zoom, pan],
+  );
+
+  // Wrap bind to ensure it always returns spreadable props (never void)
+  // We exclude 'ref' from the result to avoid type conflicts with explicit element refs
+  const safeBind: GestureBindFunction = useCallback(() => {
+    const result = bind();
+    // If bind returns void (shouldn't happen with our config), return empty object
+    // Destructure to omit ref, avoiding type conflicts with SVG/HTML element refs
+
+    const { ref: _ref, ...propsWithoutRef } = (result ??
+      {}) as React.HTMLAttributes<Element> & { ref?: unknown };
+    return propsWithoutRef;
+  }, [bind]);
+
+  return {
+    transform,
+    bind: safeBind,
+    resetTransform,
+    setZoom,
+    setPan,
+    style,
+    isDragging,
+    isPinching,
+  };
+}
+
+/**
+ * Helper to calculate SVG viewBox with pan/zoom applied
+ */
+export function calculateViewBox(
+  bounds: { minX: number; minY: number; width: number; height: number },
+  transform: PanZoomTransform,
+): string {
+  const viewBoxWidth = bounds.width / transform.zoom;
+  const viewBoxHeight = bounds.height / transform.zoom;
+  const viewBoxX =
+    bounds.minX + (bounds.width - viewBoxWidth) / 2 - transform.pan.x;
+  const viewBoxY =
+    bounds.minY + (bounds.height - viewBoxHeight) / 2 - transform.pan.y;
+
+  return `${viewBoxX} ${viewBoxY} ${viewBoxWidth} ${viewBoxHeight}`;
+}

package/src/ui/hooks/useSquareBoard.ts

@@ -0,0 +1,124 @@
+import { useCallback, useMemo } from "react";
+import type {
+  AnySquareBoardInput,
+  BoardSpaceIdOf,
+  NormalizedSquareBoard,
+  NormalizedSquareCellOf,
+} from "../types/tiled-board.js";
+import { normalizeSquareBoardInput } from "../types/tiled-board.js";
+import { useBoardTopology } from "./useBoardTopology.js";
+
+type NeighborMode = "orthogonal" | "diagonal" | "all";
+type DistanceMetric = "manhattan" | "chebyshev";
+
+export function useSquareBoard<const TBoard extends AnySquareBoardInput>(
+  board: TBoard,
+) {
+  const normalizedBoard = useMemo<NormalizedSquareBoard<TBoard>>(
+    () => normalizeSquareBoardInput(board),
+    [board],
+  );
+  const topology = useBoardTopology(board);
+
+  const cellByCoordinate = useMemo(
+    () =>
+      new Map(
+        normalizedBoard.cells.map(
+          (cell) => [`${cell.row},${cell.col}`, cell] as const,
+        ),
+      ),
+    [normalizedBoard.cells],
+  );
+
+  const getCell = useCallback(
+    (cellId: BoardSpaceIdOf<TBoard>) => {
+      return topology.getSpace(cellId) as
+        | NormalizedSquareCellOf<TBoard>
+        | undefined;
+    },
+    [topology],
+  );
+
+  const getCellAt = useCallback(
+    (row: number, col: number) => {
+      return cellByCoordinate.get(`${row},${col}`) as
+        | NormalizedSquareCellOf<TBoard>
+        | undefined;
+    },
+    [cellByCoordinate],
+  );
+
+  const getNeighbors = useCallback(
+    (cellId: BoardSpaceIdOf<TBoard>, mode: NeighborMode = "orthogonal") => {
+      const cell = getCell(cellId);
+      if (!cell) {
+        return [] as Array<NormalizedSquareCellOf<TBoard>>;
+      }
+
+      const offsets: ReadonlyArray<readonly [number, number]> =
+        mode === "diagonal"
+          ? [
+              [-1, -1],
+              [-1, 1],
+              [1, -1],
+              [1, 1],
+            ]
+          : mode === "all"
+            ? [
+                [-1, 0],
+                [0, 1],
+                [1, 0],
+                [0, -1],
+                [-1, -1],
+                [-1, 1],
+                [1, -1],
+                [1, 1],
+              ]
+            : [
+                [-1, 0],
+                [0, 1],
+                [1, 0],
+                [0, -1],
+              ];
+
+      return offsets
+        .map(([rowOffset, colOffset]) =>
+          getCellAt(cell.row + rowOffset, cell.col + colOffset),
+        )
+        .filter(
+          (candidate): candidate is NormalizedSquareCellOf<TBoard> =>
+            candidate !== undefined,
+        );
+    },
+    [getCell, getCellAt],
+  );
+
+  const getDistance = useCallback(
+    (
+      fromCellId: BoardSpaceIdOf<TBoard>,
+      toCellId: BoardSpaceIdOf<TBoard>,
+      metric: DistanceMetric = "manhattan",
+    ) => {
+      const fromCell = getCell(fromCellId);
+      const toCell = getCell(toCellId);
+      if (!fromCell || !toCell) {
+        return Number.POSITIVE_INFINITY;
+      }
+      const rowDistance = Math.abs(fromCell.row - toCell.row);
+      const colDistance = Math.abs(fromCell.col - toCell.col);
+      return metric === "chebyshev"
+        ? Math.max(rowDistance, colDistance)
+        : rowDistance + colDistance;
+    },
+    [getCell],
+  );
+
+  return {
+    ...topology,
+    board: normalizedBoard,
+    getCell,
+    getCellAt,
+    getNeighbors,
+    getDistance,
+  };
+}