@dreamboard-games/ui-sdk 0.0.41

package/src/hooks/useHandLayout.ts

@@ -0,0 +1,349 @@
+import { useState, useRef, useEffect, useMemo, useCallback } from "react";
+import type { RefObject } from "react";
+
+// Card dimensions used for fan offset and total-width calculations.
+// These must match the rendered widths from `Card.tsx`'s `sizeClasses`
+// at the `sm` Tailwind breakpoint (≥640px), since that's the size
+// player decks render at on virtually all gameplay viewports. Older
+// values here were ~30% smaller than what `Card` actually paints,
+// which caused cards to overlap by 30+ pixels even when there was
+// plenty of horizontal room in the hand container.
+const CARD_DIMENSIONS = {
+  sm: { width: 80, height: 112 },
+  md: { width: 96, height: 144 },
+  lg: { width: 128, height: 192 },
+} as const;
+
+const MIN_VISIBLE_PORTION = 16; // minimum visible pixels per card when overlapping
+const HOVER_LIFT = 20; // pixels to lift on hover
+const SELECTED_LIFT = 8; // pixels to lift when selected
+const DRAWER_THRESHOLD_RATIO = 0.3; // if overlap is less than 30% of card width, use drawer
+
+export type CardSize = "sm" | "md" | "lg";
+export type HandLayout = "spread" | "stack" | "overlap";
+
+export interface CardPositionProps {
+  /** X position (left offset) */
+  x: number;
+  /** Y position (vertical offset for hover/selected) */
+  y: number;
+  /** Z-index for layering */
+  zIndex: number;
+  /** CSS transform origin */
+  transformOrigin: string;
+}
+
+export interface UseHandLayoutOptions {
+  /** Number of cards in the hand */
+  cardCount: number;
+  /** Card size variant */
+  cardSize?: CardSize;
+  /** Layout style */
+  layout?: HandLayout;
+  /** Padding to subtract from container width */
+  containerPadding?: number;
+}
+
+export interface UseHandLayoutReturn {
+  /** Ref to attach to the container element */
+  containerRef: RefObject<HTMLDivElement | null>;
+  /** Ref to attach to the cards container element (for mouse tracking) */
+  cardsContainerRef: RefObject<HTMLDivElement | null>;
+  /** Measured container width */
+  containerWidth: number;
+  /** Calculated offset between cards */
+  cardOffset: number;
+  /** Total width of all cards */
+  totalWidth: number;
+  /** Whether drawer mode should be used */
+  useDrawerMode: boolean;
+  /** Card dimensions for the current size */
+  cardDimensions: { width: number; height: number };
+  /** Constants for positioning */
+  constants: {
+    hoverLift: number;
+    selectedLift: number;
+  };
+  /** Currently hovered card index */
+  hoveredIndex: number | null;
+  /** Mouse move handler for the cards container */
+  handleMouseMove: (e: React.MouseEvent<HTMLDivElement>) => void;
+  /** Mouse leave handler for the cards container */
+  handleMouseLeave: () => void;
+  /** Get position props for a card at the given index */
+  getCardPosition: (
+    index: number,
+    isHovered: boolean,
+    isSelected: boolean,
+  ) => CardPositionProps;
+}
+
+/**
+ * Hook for managing hand layout calculations and interactions.
+ *
+ * Provides container measurement, overlap calculations, drawer mode detection,
+ * and hover state management for card hand displays.
+ *
+ * @example
+ * ```tsx
+ * function MyHand({ cards, selectedIds }) {
+ *   const {
+ *     containerRef,
+ *     cardsContainerRef,
+ *     totalWidth,
+ *     useDrawerMode,
+ *     cardDimensions,
+ *     hoveredIndex,
+ *     handleMouseMove,
+ *     handleMouseLeave,
+ *     getCardPosition,
+ *     constants,
+ *   } = useHandLayout({
+ *     cardCount: cards.length,
+ *     cardSize: "md",
+ *     layout: "overlap",
+ *   });
+ *
+ *   if (useDrawerMode) {
+ *     return <MyDrawerUI cards={cards} />;
+ *   }
+ *
+ *   return (
+ *     <div ref={containerRef}>
+ *       <div
+ *         ref={cardsContainerRef}
+ *         style={{ width: totalWidth, height: cardDimensions.height + constants.hoverLift }}
+ *         onMouseMove={handleMouseMove}
+ *         onMouseLeave={handleMouseLeave}
+ *       >
+ *         {cards.map((card, index) => {
+ *           const isHovered = hoveredIndex === index;
+ *           const isSelected = selectedIds.includes(card.id);
+ *           const position = getCardPosition(index, isHovered, isSelected);
+ *
+ *           return (
+ *             <div
+ *               key={card.id}
+ *               style={{
+ *                 position: "absolute",
+ *                 left: position.x,
+ *                 transform: `translateY(${position.y}px)`,
+ *                 zIndex: position.zIndex,
+ *               }}
+ *             >
+ *               <MyCard card={card} />
+ *             </div>
+ *           );
+ *         })}
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useHandLayout({
+  cardCount,
+  cardSize = "md",
+  layout = "overlap",
+  containerPadding = 32,
+}: UseHandLayoutOptions): UseHandLayoutReturn {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const cardsContainerRef = useRef<HTMLDivElement>(null);
+  const [containerWidth, setContainerWidth] = useState(0);
+  const [hoveredIndex, setHoveredIndex] = useState<number | null>(null);
+
+  const cardDimensions = CARD_DIMENSIONS[cardSize];
+
+  // Measure container width with ResizeObserver
+  useEffect(() => {
+    const updateWidth = () => {
+      if (containerRef.current) {
+        setContainerWidth(containerRef.current.clientWidth - containerPadding);
+      }
+    };
+
+    updateWidth();
+    const observer = new ResizeObserver(updateWidth);
+    if (containerRef.current) {
+      observer.observe(containerRef.current);
+    }
+
+    return () => observer.disconnect();
+  }, [containerPadding]);
+
+  // Calculate adaptive overlap based on container width and card count
+  const { cardOffset, totalWidth, useDrawerMode } = useMemo(() => {
+    if (layout !== "overlap") {
+      return {
+        cardOffset: cardDimensions.width,
+        totalWidth: 0,
+        useDrawerMode: false,
+      };
+    }
+
+    if (cardCount === 0) {
+      return { cardOffset: 0, totalWidth: 0, useDrawerMode: false };
+    }
+    if (cardCount === 1) {
+      return {
+        cardOffset: cardDimensions.width,
+        totalWidth: cardDimensions.width,
+        useDrawerMode: false,
+      };
+    }
+
+    // Available width for overlap distribution
+    const availableWidth = containerWidth;
+    if (availableWidth <= 0) {
+      return {
+        cardOffset: cardDimensions.width,
+        totalWidth: cardDimensions.width * cardCount,
+        useDrawerMode: false,
+      };
+    }
+
+    // Calculate the offset needed to fit all cards
+    // Total width = cardWidth + (cardCount - 1) * offset
+    // So offset = (availableWidth - cardWidth) / (cardCount - 1)
+    const idealOffset =
+      (availableWidth - cardDimensions.width) / (cardCount - 1);
+
+    // Clamp offset between minimum visible portion and full card width
+    const clampedOffset = Math.max(
+      MIN_VISIBLE_PORTION,
+      Math.min(cardDimensions.width, idealOffset),
+    );
+
+    // Calculate total width with this offset
+    const width = cardDimensions.width + (cardCount - 1) * clampedOffset;
+
+    // Determine if we should use drawer mode
+    // Use drawer if cards are overlapping too much (less than threshold of card visible)
+    const visiblePortion = clampedOffset / cardDimensions.width;
+    const shouldUseDrawer =
+      visiblePortion < DRAWER_THRESHOLD_RATIO && cardCount > 2;
+
+    return {
+      cardOffset: clampedOffset,
+      totalWidth: width,
+      useDrawerMode: shouldUseDrawer,
+    };
+  }, [cardCount, containerWidth, layout, cardDimensions.width]);
+
+  // Calculate hovered card index based on mouse X position
+  // This allows hovering on adjacent cards even when one is popped up
+  const handleMouseMove = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      if (
+        !cardsContainerRef.current ||
+        cardCount === 0 ||
+        layout === "spread" ||
+        layout === "stack"
+      ) {
+        return;
+      }
+
+      const rect = cardsContainerRef.current.getBoundingClientRect();
+      const mouseX = e.clientX - rect.left;
+
+      let newHoveredIndex: number | null = null;
+
+      // Find which card the mouse is over based on X position
+      for (let i = cardCount - 1; i >= 0; i--) {
+        const cardLeft = i * cardOffset;
+        const cardRight =
+          i === cardCount - 1
+            ? cardLeft + cardDimensions.width
+            : (i + 1) * cardOffset;
+
+        if (mouseX >= cardLeft && mouseX < cardRight) {
+          newHoveredIndex = i;
+          break;
+        }
+      }
+
+      // Check if mouse is in the rightmost card's full area
+      if (newHoveredIndex === null && mouseX >= 0 && mouseX < totalWidth) {
+        const lastCardLeft = (cardCount - 1) * cardOffset;
+        if (mouseX >= lastCardLeft) {
+          newHoveredIndex = cardCount - 1;
+        }
+      }
+
+      setHoveredIndex(newHoveredIndex);
+    },
+    [cardCount, cardOffset, totalWidth, layout, cardDimensions.width],
+  );
+
+  const handleMouseLeave = useCallback(() => {
+    setHoveredIndex(null);
+  }, []);
+
+  // Calculate z-index: hovered > selected > position
+  const getZIndex = useCallback(
+    (index: number, isHovered: boolean, isSelected: boolean) => {
+      if (isHovered) return 200;
+      if (isSelected) return 100 + index;
+      return index;
+    },
+    [],
+  );
+
+  // Get card position props for different layouts
+  const getCardPosition = useCallback(
+    (
+      index: number,
+      isHovered: boolean,
+      isSelected: boolean,
+    ): CardPositionProps => {
+      const zIndex = getZIndex(index, isHovered, isSelected);
+
+      if (layout === "stack") {
+        return {
+          x: index * 4,
+          y: 0,
+          zIndex,
+          transformOrigin: "bottom center",
+        };
+      }
+
+      if (layout === "spread") {
+        return {
+          x: 0,
+          y: 0,
+          zIndex,
+          transformOrigin: "bottom center",
+        };
+      }
+
+      // Overlap layout (default) - simple horizontal overlap with lift on hover/select
+      const yOffset = isHovered ? -HOVER_LIFT : isSelected ? -SELECTED_LIFT : 0;
+
+      return {
+        x: index * cardOffset,
+        y: yOffset,
+        zIndex,
+        transformOrigin: "bottom center",
+      };
+    },
+    [layout, cardOffset, getZIndex],
+  );
+
+  return {
+    containerRef,
+    cardsContainerRef,
+    containerWidth,
+    cardOffset,
+    totalWidth,
+    useDrawerMode,
+    cardDimensions,
+    constants: {
+      hoverLift: HOVER_LIFT,
+      selectedLift: SELECTED_LIFT,
+    },
+    hoveredIndex,
+    handleMouseMove,
+    handleMouseLeave,
+    getCardPosition,
+  };
+}

package/src/hooks/useHexBoard.ts

@@ -0,0 +1,74 @@
+import { useCallback, useMemo } from "react";
+import type {
+  AnyHexBoardInput,
+  BoardSpaceIdOf,
+  NormalizedHexBoard,
+  NormalizedHexTileOf,
+} from "../types/tiled-board.js";
+import { normalizeHexBoardInput } from "../types/tiled-board.js";
+import { useBoardTopology } from "./useBoardTopology.js";
+
+export function useHexBoard<const TBoard extends AnyHexBoardInput>(
+  board: TBoard,
+) {
+  const normalizedBoard = useMemo<NormalizedHexBoard<TBoard>>(
+    () => normalizeHexBoardInput(board),
+    [board],
+  );
+  const topology = useBoardTopology(board);
+
+  const tileByCoordinate = useMemo(
+    () =>
+      new Map(
+        normalizedBoard.tiles.map(
+          (tile) => [`${tile.q},${tile.r}`, tile] as const,
+        ),
+      ),
+    [normalizedBoard.tiles],
+  );
+
+  const getTile = useCallback(
+    (tileId: BoardSpaceIdOf<TBoard>) => {
+      return topology.getSpace(tileId) as
+        | NormalizedHexTileOf<TBoard>
+        | undefined;
+    },
+    [topology],
+  );
+
+  const getTileAt = useCallback(
+    (q: number, r: number) => {
+      return tileByCoordinate.get(`${q},${r}`) as
+        | NormalizedHexTileOf<TBoard>
+        | undefined;
+    },
+    [tileByCoordinate],
+  );
+
+  const getNeighbors = useCallback(
+    (tileId: BoardSpaceIdOf<TBoard>) => {
+      return topology.getAdjacentSpaces(tileId) as Array<
+        NormalizedHexTileOf<TBoard>
+      >;
+    },
+    [topology],
+  );
+
+  const getTilesInRange = useCallback(
+    (centerTileId: BoardSpaceIdOf<TBoard>, range: number) => {
+      return normalizedBoard.tiles.filter(
+        (tile) => topology.getDistance(centerTileId, tile.id) <= range,
+      ) as Array<NormalizedHexTileOf<TBoard>>;
+    },
+    [normalizedBoard.tiles, topology],
+  );
+
+  return {
+    ...topology,
+    board: normalizedBoard,
+    getTile,
+    getTileAt,
+    getNeighbors,
+    getTilesInRange,
+  };
+}

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