@almadar/ui 2.13.3 → 2.15.0

package/dist/components/organisms/game/three/components/Canvas3DErrorBoundary.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Canvas3DErrorBoundary
+ *
+ * Error boundary for 3D canvas components.
+ * Catches Three.js and React Three Fiber errors gracefully.
+ *
+ * @packageDocumentation
+ */
+import { Component, type ReactNode, type ErrorInfo } from 'react';
+import './Canvas3DErrorBoundary.css';
+export interface Canvas3DErrorBoundaryProps {
+    /** Child components */
+    children: ReactNode;
+    /** Custom fallback component */
+    fallback?: ReactNode;
+    /** Error callback */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /** Reset callback */
+    onReset?: () => void;
+}
+export interface Canvas3DErrorBoundaryState {
+    /** Whether an error has occurred */
+    hasError: boolean;
+    /** The error that occurred */
+    error: Error | null;
+    /** Error info from React */
+    errorInfo: ErrorInfo | null;
+}
+/**
+ * Canvas3DErrorBoundary Component
+ *
+ * Catches errors in 3D canvas and displays a user-friendly fallback.
+ *
+ * @example
+ * ```tsx
+ * <Canvas3DErrorBoundary
+ *     onError={(error) => console.error('3D Error:', error)}
+ *     onReset={() => console.log('Resetting...')}
+ * >
+ *     <GameCanvas3D {...props} />
+ * </Canvas3DErrorBoundary>
+ * ```
+ */
+export declare class Canvas3DErrorBoundary extends Component<Canvas3DErrorBoundaryProps, Canvas3DErrorBoundaryState> {
+    constructor(props: Canvas3DErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Canvas3DErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    handleReset: () => void;
+    render(): ReactNode;
+}
+export default Canvas3DErrorBoundary;

package/dist/components/organisms/game/three/components/Canvas3DLoadingState.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Canvas3DLoadingState
+ *
+ * Loading state component for 3D canvas with progress indicator.
+ * Displays asset loading progress and estimated time remaining.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import './Canvas3DLoadingState.css';
+export interface Canvas3DLoadingStateProps {
+    /** Current loading progress (0-100) */
+    progress?: number;
+    /** Number of assets loaded */
+    loaded?: number;
+    /** Total assets to load */
+    total?: number;
+    /** Loading message */
+    message?: string;
+    /** Secondary details message */
+    details?: string;
+    /** Whether to show spinner */
+    showSpinner?: boolean;
+    /** Custom className */
+    className?: string;
+}
+/**
+ * Canvas3DLoadingState Component
+ *
+ * Displays loading progress for 3D assets.
+ *
+ * @example
+ * ```tsx
+ * <Canvas3DLoadingState
+ *     progress={65}
+ *     loaded={13}
+ *     total={20}
+ *     message="Loading 3D models..."
+ *     details="character-knight.glb"
+ * />
+ * ```
+ */
+export declare function Canvas3DLoadingState({ progress, loaded, total, message, details, showSpinner, className, }: Canvas3DLoadingStateProps): React.JSX.Element;
+export default Canvas3DLoadingState;

package/dist/components/organisms/game/three/components/ModelLoader.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ModelLoader Component
+ *
+ * React Three Fiber component for loading and displaying GLB/GLTF models from URLs.
+ * Handles loading states and errors without requiring React Suspense.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface ModelLoaderProps {
+    /** URL to the GLB/GLTF model */
+    url: string;
+    /** Position [x, y, z] */
+    position?: [number, number, number];
+    /** Scale - either a single number or [x, y, z] */
+    scale?: number | [number, number, number];
+    /** Rotation in degrees [x, y, z] */
+    rotation?: [number, number, number];
+    /** Whether the model is selected */
+    isSelected?: boolean;
+    /** Whether the model is hovered */
+    isHovered?: boolean;
+    /** Click handler */
+    onClick?: () => void;
+    /** Hover handler */
+    onHover?: (hovered: boolean) => void;
+    /** Fallback geometry type */
+    fallbackGeometry?: 'box' | 'sphere' | 'cylinder' | 'none';
+    /** Enable shadows */
+    castShadow?: boolean;
+    /** Receive shadows */
+    receiveShadow?: boolean;
+    /**
+     * Base path for shared resources (textures, materials).
+     * If not provided, auto-detected from the URL by looking for a `/3d/` segment.
+     * E.g. "https://host/3d/" so that "Textures/colormap.png" resolves correctly.
+     */
+    resourceBasePath?: string;
+}
+/**
+ * ModelLoader component for rendering GLB models in React Three Fiber
+ */
+export declare function ModelLoader({ url, position, scale, rotation, isSelected, isHovered, onClick, onHover, fallbackGeometry, castShadow, receiveShadow, resourceBasePath, }: ModelLoaderProps): React.JSX.Element;
+export default ModelLoader;

package/dist/components/organisms/game/three/components/PhysicsObject3D.d.ts

@@ -0,0 +1,74 @@
+/**
+ * PhysicsObject3D Component
+ *
+ * Three.js component that syncs a 3D object's position with physics state.
+ * Use this to render physics-enabled entities in GameCanvas3D.
+ *
+ * @example
+ * ```tsx
+ * <PhysicsObject3D
+ *   entityId="player-1"
+ *   modelUrl="https://trait-wars-assets.web.app/3d/medieval/props/barrels.glb"
+ *   initialPosition={[0, 10, 0]}
+ *   mass={1}
+ * />
+ * ```
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface Physics3DState {
+    id: string;
+    x: number;
+    y: number;
+    z: number;
+    vx: number;
+    vy: number;
+    vz: number;
+    rx: number;
+    ry: number;
+    rz: number;
+    isGrounded: boolean;
+    gravity: number;
+    friction: number;
+    mass: number;
+    state: 'Active' | 'Frozen';
+}
+export interface PhysicsObject3DProps {
+    /** Unique entity ID */
+    entityId: string;
+    /** GLB model URL */
+    modelUrl: string;
+    /** Initial position [x, y, z] */
+    initialPosition?: [number, number, number];
+    /** Initial velocity [vx, vy, vz] */
+    initialVelocity?: [number, number, number];
+    /** Mass for collision response */
+    mass?: number;
+    /** Gravity force (default: 9.8) */
+    gravity?: number;
+    /** Ground plane Y position (default: 0) */
+    groundY?: number;
+    /** Model scale */
+    scale?: number | [number, number, number];
+    /** Called when physics state updates */
+    onPhysicsUpdate?: (state: Physics3DState) => void;
+    /** Called when object hits ground */
+    onGroundHit?: () => void;
+    /** Called when collision occurs */
+    onCollision?: (otherEntityId: string) => void;
+}
+/**
+ * 3D Physics-enabled object for GameCanvas3D
+ */
+export declare function PhysicsObject3D({ entityId, modelUrl, initialPosition, initialVelocity, mass, gravity, groundY, scale, onPhysicsUpdate, onGroundHit, onCollision, }: PhysicsObject3DProps): React.JSX.Element;
+/**
+ * Hook for controlling a PhysicsObject3D from parent component
+ */
+export declare function usePhysics3DController(entityId: string): {
+    applyForce: (fx: number, fy: number, fz: number) => void;
+    setVelocity: (vx: number, vy: number, vz: number) => void;
+    setPosition: (x: number, y: number, z: number) => void;
+    jump: (force?: number) => void;
+};
+export default PhysicsObject3D;

package/dist/components/organisms/game/three/components/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 3D Components
+ *
+ * UI components for 3D canvas states and error handling.
+ *
+ * @packageDocumentation
+ */
+export { Canvas3DLoadingState, type Canvas3DLoadingStateProps, } from './Canvas3DLoadingState';
+export { Canvas3DErrorBoundary, type Canvas3DErrorBoundaryProps, type Canvas3DErrorBoundaryState, } from './Canvas3DErrorBoundary';
+export { ModelLoader, type ModelLoaderProps, } from './ModelLoader';

package/dist/components/organisms/game/three/hooks/useAssetLoader.d.ts

@@ -0,0 +1,58 @@
+import * as THREE from 'three';
+import { AssetLoader, LoadedModel } from '../loaders/AssetLoader';
+export interface UseAssetLoaderOptions {
+    /** URLs to preload on mount */
+    preloadUrls?: string[];
+    /** Asset loader instance (uses singleton if not provided) */
+    loader?: AssetLoader;
+}
+export interface AssetLoadingState {
+    /** Whether assets are currently loading */
+    isLoading: boolean;
+    /** Loading progress (0-100) */
+    progress: number;
+    /** Number of loaded assets */
+    loaded: number;
+    /** Total assets to load */
+    total: number;
+    /** Any loading errors */
+    errors: string[];
+}
+export interface UseAssetLoaderReturn extends AssetLoadingState {
+    /** Load a single model */
+    loadModel: (url: string) => Promise<LoadedModel>;
+    /** Load a single OBJ model */
+    loadOBJ: (url: string) => Promise<THREE.Group>;
+    /** Load a single texture */
+    loadTexture: (url: string) => Promise<THREE.Texture>;
+    /** Preload multiple assets */
+    preload: (urls: string[]) => Promise<void>;
+    /** Check if model is cached */
+    hasModel: (url: string) => boolean;
+    /** Check if texture is cached */
+    hasTexture: (url: string) => boolean;
+    /** Get cached model */
+    getModel: (url: string) => LoadedModel | undefined;
+    /** Get cached texture */
+    getTexture: (url: string) => THREE.Texture | undefined;
+    /** Clear all caches */
+    clearCache: () => void;
+}
+/**
+ * Hook for managing 3D asset loading in React components
+ *
+ * @example
+ * ```tsx
+ * const { loadModel, isLoading, progress } = useAssetLoader({
+ *     preloadUrls: ['/assets/model.glb']
+ * });
+ *
+ * useEffect(() => {
+ *     loadModel('/assets/character.glb').then((model) => {
+ *         scene.add(model.scene);
+ *     });
+ * }, []);
+ * ```
+ */
+export declare function useAssetLoader(options?: UseAssetLoaderOptions): UseAssetLoaderReturn;
+export default useAssetLoader;

package/dist/components/organisms/game/three/hooks/useGameCanvas3DEvents.d.ts

@@ -0,0 +1,79 @@
+import type { IsometricTile, IsometricUnit, IsometricFeature } from '../../types/isometric';
+export interface GameCanvas3DEventConfig {
+    /** Event name for tile clicks */
+    tileClickEvent?: string;
+    /** Event name for unit clicks */
+    unitClickEvent?: string;
+    /** Event name for feature clicks */
+    featureClickEvent?: string;
+    /** Event name for canvas clicks */
+    canvasClickEvent?: string;
+    /** Event name for tile hover */
+    tileHoverEvent?: string;
+    /** Event name for tile leave */
+    tileLeaveEvent?: string;
+    /** Event name for unit animation changes */
+    unitAnimationEvent?: string;
+    /** Event name for camera changes */
+    cameraChangeEvent?: string;
+}
+/** Minimal mouse event interface — satisfied by both React.MouseEvent and ThreeEvent<MouseEvent> */
+export interface MinimalMouseEvent {
+    clientX: number;
+    clientY: number;
+    button: number;
+}
+export interface UseGameCanvas3DEventsOptions extends GameCanvas3DEventConfig {
+    /** Callback for tile clicks (direct) */
+    onTileClick?: (tile: IsometricTile, event: React.MouseEvent) => void;
+    /** Callback for unit clicks (direct) */
+    onUnitClick?: (unit: IsometricUnit, event: React.MouseEvent) => void;
+    /** Callback for feature clicks (direct) */
+    onFeatureClick?: (feature: IsometricFeature, event: React.MouseEvent) => void;
+    /** Callback for canvas clicks (direct) */
+    onCanvasClick?: (event: React.MouseEvent) => void;
+    /** Callback for tile hover (direct) */
+    onTileHover?: (tile: IsometricTile | null, event: React.MouseEvent) => void;
+    /** Callback for unit animation changes (direct) */
+    onUnitAnimation?: (unitId: string, state: string) => void;
+}
+export interface UseGameCanvas3DEventsReturn {
+    /** Handle tile click - emits event and calls callback */
+    handleTileClick: (tile: IsometricTile, event: React.MouseEvent) => void;
+    /** Handle unit click - emits event and calls callback */
+    handleUnitClick: (unit: IsometricUnit, event: React.MouseEvent) => void;
+    /** Handle feature click - emits event and calls callback */
+    handleFeatureClick: (feature: IsometricFeature, event: React.MouseEvent) => void;
+    /** Handle canvas click - emits event and calls callback */
+    handleCanvasClick: (event: MinimalMouseEvent) => void;
+    /** Handle tile hover - emits event and calls callback */
+    handleTileHover: (tile: IsometricTile | null, event: React.MouseEvent) => void;
+    /** Handle unit animation - emits event and calls callback */
+    handleUnitAnimation: (unitId: string, state: string) => void;
+    /** Handle camera change - emits event */
+    handleCameraChange: (position: {
+        x: number;
+        y: number;
+        z: number;
+    }) => void;
+}
+/**
+ * Hook for integrating GameCanvas3D with the event bus
+ *
+ * Supports both declarative event props (tileClickEvent) and
+ * direct callback props (onTileClick).
+ *
+ * @example
+ * ```tsx
+ * const events = useGameCanvas3DEvents({
+ *     tileClickEvent: 'TILE_SELECTED',
+ *     unitClickEvent: 'UNIT_SELECTED',
+ *     onTileClick: (tile) => console.log('Tile:', tile)
+ * });
+ *
+ * // In component:
+ * <TileRenderer onTileClick={events.handleTileClick} />
+ * ```
+ */
+export declare function useGameCanvas3DEvents(options: UseGameCanvas3DEventsOptions): UseGameCanvas3DEventsReturn;
+export default useGameCanvas3DEvents;

package/dist/components/organisms/game/three/hooks/useRaycaster.d.ts

@@ -0,0 +1,86 @@
+import * as THREE from 'three';
+export interface RaycastHit {
+    /** Intersected object */
+    object: THREE.Object3D;
+    /** Intersection point */
+    point: THREE.Vector3;
+    /** Distance from camera */
+    distance: number;
+    /** UV coordinates (if available) */
+    uv?: THREE.Vector2;
+    /** Face normal */
+    face?: THREE.Face;
+    /** Face index */
+    faceIndex?: number;
+    /** Instance ID (for instanced meshes) */
+    instanceId?: number;
+}
+export interface GridHit {
+    /** Grid X coordinate */
+    gridX: number;
+    /** Grid Z coordinate */
+    gridZ: number;
+    /** World position */
+    worldPosition: THREE.Vector3;
+    /** Intersected object type */
+    objectType?: 'tile' | 'unit' | 'feature';
+    /** Object ID if available */
+    objectId?: string;
+}
+export interface UseRaycasterOptions {
+    /** Camera reference */
+    camera: THREE.Camera | null;
+    /** Canvas element for coordinate conversion */
+    canvas: HTMLCanvasElement | null;
+    /** Grid cell size */
+    cellSize?: number;
+    /** Grid offset X */
+    offsetX?: number;
+    /** Grid offset Z */
+    offsetZ?: number;
+}
+export interface UseRaycasterReturn {
+    /** Raycaster instance */
+    raycaster: React.MutableRefObject<THREE.Raycaster>;
+    /** Mouse vector instance */
+    mouse: React.MutableRefObject<THREE.Vector2>;
+    /** Get intersection at client coordinates */
+    getIntersection: (clientX: number, clientY: number, objects: THREE.Object3D[]) => RaycastHit | null;
+    /** Get all intersections at client coordinates */
+    getAllIntersections: (clientX: number, clientY: number, objects: THREE.Object3D[]) => RaycastHit[];
+    /** Get grid coordinates at client position */
+    getGridCoordinates: (clientX: number, clientY: number) => {
+        x: number;
+        z: number;
+    } | null;
+    /** Get tile at client position from scene */
+    getTileAtPosition: (clientX: number, clientY: number, scene: THREE.Scene) => GridHit | null;
+    /** Convert client coordinates to normalized device coordinates */
+    clientToNDC: (clientX: number, clientY: number) => {
+        x: number;
+        y: number;
+    };
+    /** Check if point is within canvas bounds */
+    isWithinCanvas: (clientX: number, clientY: number) => boolean;
+}
+/**
+ * Hook for 3D raycasting operations
+ *
+ * @example
+ * ```tsx
+ * const { getIntersection, getGridCoordinates } = useRaycaster({
+ *     camera,
+ *     canvas: canvasRef.current
+ * });
+ *
+ * const handleClick = (e: MouseEvent) => {
+ *     const hit = getIntersection(e.clientX, e.clientY, tileMeshes);
+ *     if (hit) {
+ *         const grid = getGridCoordinates(e.clientX, e.clientY);
+ *         console.log('Clicked grid:', grid);
+ *     }
+ * };
+ * ```
+ */
+export declare function useRaycaster(options: UseRaycasterOptions): UseRaycasterReturn;
+export default useRaycaster;

package/dist/components/organisms/game/three/hooks/useSceneGraph.d.ts

@@ -0,0 +1,66 @@
+import * as THREE from 'three';
+export type NodeType = 'tile' | 'unit' | 'feature' | 'highlight' | 'effect';
+export interface SceneGraphNode {
+    /** Unique node identifier */
+    id: string;
+    /** Node type classification */
+    type: NodeType;
+    /** Three.js object */
+    mesh: THREE.Object3D;
+    /** World position */
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Grid position */
+    gridPosition: {
+        x: number;
+        z: number;
+    };
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface UseSceneGraphReturn {
+    /** Reference to the nodes map */
+    nodesRef: React.MutableRefObject<Map<string, SceneGraphNode>>;
+    /** Add a node to the scene */
+    addNode: (node: SceneGraphNode) => void;
+    /** Remove a node from the scene */
+    removeNode: (id: string) => void;
+    /** Get a node by ID */
+    getNode: (id: string) => SceneGraphNode | undefined;
+    /** Update node position */
+    updateNodePosition: (id: string, x: number, y: number, z: number) => void;
+    /** Update node grid position */
+    updateNodeGridPosition: (id: string, gridX: number, gridZ: number) => void;
+    /** Get node at grid position */
+    getNodeAtGrid: (x: number, z: number, type?: NodeType) => SceneGraphNode | undefined;
+    /** Get all nodes of a specific type */
+    getNodesByType: (type: NodeType) => SceneGraphNode[];
+    /** Get all nodes within a bounding box */
+    getNodesInBounds: (minX: number, maxX: number, minZ: number, maxZ: number) => SceneGraphNode[];
+    /** Clear all nodes */
+    clearNodes: () => void;
+    /** Count nodes by type */
+    countNodes: (type?: NodeType) => number;
+}
+/**
+ * Hook for managing the 3D scene graph
+ *
+ * @example
+ * ```tsx
+ * const { addNode, removeNode, getNodeAtGrid } = useSceneGraph();
+ *
+ * // Add a tile
+ * addNode({
+ *     id: 'tile-0-0',
+ *     type: 'tile',
+ *     mesh: tileMesh,
+ *     position: { x: 0, y: 0, z: 0 },
+ *     gridPosition: { x: 0, z: 0 }
+ * });
+ * ```
+ */
+export declare function useSceneGraph(): UseSceneGraphReturn;
+export default useSceneGraph;

package/dist/components/organisms/game/three/hooks/useThree.d.ts

@@ -0,0 +1,58 @@
+import * as THREE from 'three';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { AssetLoader } from '../loaders/AssetLoader';
+export type CameraMode = 'isometric' | 'perspective' | 'top-down';
+export interface UseThreeOptions {
+    /** Camera mode for viewing the scene */
+    cameraMode?: CameraMode;
+    /** Initial camera position [x, y, z] */
+    cameraPosition?: [number, number, number];
+    /** Background color */
+    backgroundColor?: string;
+    /** Enable shadows */
+    shadows?: boolean;
+    /** Enable grid helper */
+    showGrid?: boolean;
+    /** Grid size */
+    gridSize?: number;
+    /** Asset loader instance */
+    assetLoader?: AssetLoader;
+}
+export interface UseThreeReturn {
+    /** Canvas element reference (for React Three Fiber) */
+    canvasRef: React.RefObject<HTMLCanvasElement | null>;
+    /** Three.js renderer */
+    renderer: THREE.WebGLRenderer | null;
+    /** Three.js scene */
+    scene: THREE.Scene | null;
+    /** Three.js camera */
+    camera: THREE.Camera | null;
+    /** Orbit controls */
+    controls: OrbitControls | null;
+    /** Is scene ready */
+    isReady: boolean;
+    /** Canvas dimensions */
+    dimensions: {
+        width: number;
+        height: number;
+    };
+    /** Set camera position */
+    setCameraPosition: (x: number, y: number, z: number) => void;
+    /** Look at a specific point */
+    lookAt: (x: number, y: number, z: number) => void;
+    /** Reset camera to initial position */
+    resetCamera: () => void;
+    /** Fit view to bounds */
+    fitView: (bounds: {
+        minX: number;
+        maxX: number;
+        minZ: number;
+        maxZ: number;
+    }) => void;
+}
+/**
+ * Hook for managing a Three.js scene
+ * This is a lower-level hook used by GameCanvas3D
+ */
+export declare function useThree(options?: UseThreeOptions): UseThreeReturn;
+export default useThree;