@dreamboard-games/sdk 0.2.1-alpha.1 → 0.3.0-alpha.1

package/src/ui/hooks/useHandLayout.ts

@@ -1,378 +0,0 @@
-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/touch 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;
-  /** Touch move handler for the cards container (mirrors mouse hover lift on touch) */
-  handleTouchMove: (e: React.TouchEvent<HTMLDivElement>) => void;
-  /** Touch end handler for the cards container */
-  handleTouchEnd: () => 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]);
-
-  // Shared logic: map a clientX coordinate to the card index it's over.
-  // Used by both mouse and touch move handlers.
-  const getHoveredIndexFromClientX = useCallback(
-    (clientX: number): number | null => {
-      if (!cardsContainerRef.current) return null;
-      const rect = cardsContainerRef.current.getBoundingClientRect();
-      const mouseX = clientX - rect.left;
-
-      let newHoveredIndex: number | null = null;
-
-      // Find which card the pointer is over based on X position.
-      // Iterate right-to-left so cards on top (higher z-index) win.
-      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 pointer 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;
-        }
-      }
-
-      return newHoveredIndex;
-    },
-    [cardCount, cardOffset, totalWidth, 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 (cardCount === 0 || layout === "spread" || layout === "stack") {
-        return;
-      }
-      setHoveredIndex(getHoveredIndexFromClientX(e.clientX));
-    },
-    [cardCount, layout, getHoveredIndexFromClientX],
-  );
-
-  const handleMouseLeave = useCallback(() => {
-    setHoveredIndex(null);
-  }, []);
-
-  // Touch equivalents — mirror the hover-lift feedback on touch devices so
-  // the active card is clearly highlighted while the finger is moving.
-  const handleTouchMove = useCallback(
-    (e: React.TouchEvent<HTMLDivElement>) => {
-      if (cardCount === 0 || layout === "spread" || layout === "stack") {
-        return;
-      }
-      const touch = e.touches[0];
-      if (!touch) return;
-      setHoveredIndex(getHoveredIndexFromClientX(touch.clientX));
-    },
-    [cardCount, layout, getHoveredIndexFromClientX],
-  );
-
-  const handleTouchEnd = 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,
-    handleTouchMove,
-    handleTouchEnd,
-    getCardPosition,
-  };
-}

package/src/ui/hooks/useHandPresentation.ts

@@ -1,121 +0,0 @@
-/**
- * Width-aware presentation selector for the controlled `HandView`.
- *
- * Measures the wrapping element with `ResizeObserver` and returns the chosen
- * presentation mode plus the resolved fan geometry. The hook is purely
- * presentational: it does not consume runtime state or descriptors.
- */
-
-import { useEffect, useMemo, useRef, useState } from "react";
-import {
-  HAND_MODE_GEOMETRY,
-  chooseHandLayoutMode,
-  computeFanLayout,
-  type FanCardPosition,
-  type HandPresentationMode,
-} from "../components/hand-layout-math.js";
-
-export interface HandPresentationOptions {
-  cardCount: number;
-  cardWidth: number;
-  cardHeight: number;
-  /** Desktop preference; defaults to `fan`. */
-  desktop?: HandPresentationMode;
-  /** Mobile fallback; defaults to `tray`. */
-  mobile?: HandPresentationMode;
-  /** Subtracted from measured container width (gutter, scroll padding). */
-  containerPadding?: number;
-}
-
-export interface HandPresentationResult {
-  containerRef: React.RefObject<HTMLDivElement | null>;
-  containerWidth: number;
-  mode: HandPresentationMode;
-  fanPositions: FanCardPosition[];
-  fanStep: number;
-  totalWidth: number;
-  visibleSlice: number;
-}
-
-const DEFAULT_PADDING = 16;
-
-export function useHandPresentation({
-  cardCount,
-  cardWidth,
-  cardHeight,
-  desktop = "fan",
-  mobile = "tray",
-  containerPadding = DEFAULT_PADDING,
-}: HandPresentationOptions): HandPresentationResult {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const [containerWidth, setContainerWidth] = useState(0);
-
-  useEffect(() => {
-    const node = containerRef.current;
-    if (!node) return;
-    let frame = 0;
-    // Round to whole pixels and bail when the width is unchanged. The chosen
-    // mode (fan vs compressed-fan) feeds the rendered card geometry, so an
-    // unguarded float setState here can ping-pong the layout via ResizeObserver
-    // (sub-pixel jitter, or a content-sized ancestor) and re-render forever.
-    // Deferring to rAF also avoids "ResizeObserver loop limit exceeded".
-    const apply = () => {
-      const node = containerRef.current;
-      if (!node) return;
-      const next = Math.max(
-        0,
-        Math.round(node.getBoundingClientRect().width) - containerPadding,
-      );
-      setContainerWidth((prev) => (prev === next ? prev : next));
-    };
-    apply();
-    if (typeof ResizeObserver === "undefined") return;
-    const observer = new ResizeObserver(() => {
-      cancelAnimationFrame(frame);
-      frame = requestAnimationFrame(apply);
-    });
-    observer.observe(node);
-    return () => {
-      cancelAnimationFrame(frame);
-      observer.disconnect();
-    };
-  }, [containerPadding]);
-
-  return useMemo<HandPresentationResult>(() => {
-    const mode = chooseHandLayoutMode({
-      containerWidth,
-      cardCount,
-      cardWidth,
-      desktop,
-      mobile,
-    });
-    if (mode === "fan" || mode === "compressed-fan") {
-      const geometry = HAND_MODE_GEOMETRY[mode];
-      const layout = computeFanLayout({
-        availableWidth: containerWidth || cardWidth * cardCount,
-        cardWidth,
-        cardHeight,
-        count: cardCount,
-        ...geometry,
-      });
-      return {
-        containerRef,
-        containerWidth,
-        mode,
-        fanPositions: layout.positions,
-        fanStep: layout.step,
-        totalWidth: layout.totalWidth,
-        visibleSlice: layout.visibleSlice,
-      };
-    }
-    return {
-      containerRef,
-      containerWidth,
-      mode,
-      fanPositions: [],
-      fanStep: cardWidth,
-      totalWidth: cardWidth * cardCount,
-      visibleSlice: cardWidth,
-    };
-  }, [cardCount, cardHeight, cardWidth, containerWidth, desktop, mobile]);
-}

package/src/ui/hooks/useHexBoard.ts

@@ -1,74 +0,0 @@
-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,
-  };
-}