@canvas-tile-engine/react 0.1.0 → 0.3.0

package/README.md

@@ -1,17 +1,22 @@
 # @canvas-tile-engine/react
 
+[![npm version](https://img.shields.io/npm/v/@canvas-tile-engine/react)](https://www.npmjs.com/package/@canvas-tile-engine/react)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@canvas-tile-engine/react)](https://bundlephobia.com/package/@canvas-tile-engine/react)
+[![license](https://img.shields.io/npm/l/@canvas-tile-engine/react)](../../LICENSE)
+
 React bindings for Canvas Tile Engine — build interactive 2D grid-based maps with declarative components.
 
 ## Install
 
 ```bash
-npm install @canvas-tile-engine/react
+npm install @canvas-tile-engine/react @canvas-tile-engine/renderer-canvas
 ```
 
 ## Quick Start
 
 ```tsx
 import { CanvasTileEngine, useCanvasTileEngine } from "@canvas-tile-engine/react";
+import { RendererCanvas } from "@canvas-tile-engine/renderer-canvas";
 
 const config = {
     scale: 50,
@@ -27,6 +32,7 @@ function App() {
         <CanvasTileEngine
             engine={engine}
             config={config}
+            renderer={new RendererCanvas()}
             center={{ x: 0, y: 0 }}
             onClick={(coords) => console.log("Clicked:", coords.snapped)}
         >
@@ -37,9 +43,22 @@ function App() {
 }
 ```
 
+## Architecture
+
+The React package wraps `@canvas-tile-engine/core` with declarative components. You inject a renderer via the `renderer` prop:
+
+```tsx
+// Canvas2D
+import { RendererCanvas } from "@canvas-tile-engine/renderer-canvas";
+<CanvasTileEngine engine={engine} config={config} renderer={new RendererCanvas()} />
+
+// Custom renderer
+<CanvasTileEngine engine={engine} config={config} renderer={new MyCustomRenderer()} />
+```
+
 ## Documentation
 
-Full API reference and examples: [https://www.canvastileengine.dev/docs/react/installation](https://www.canvastileengine.dev/docs/react/installation)
+Full API reference and examples: [canvastileengine.dev](https://canvastileengine.dev/docs/react/installation)
 
 ## License
 

package/dist/index.d.mts

@@ -1,15 +1,15 @@
 import * as react from 'react';
-import { DrawObject, ImageItem, Coords, CanvasTileEngineConfig, CanvasTileEngine as CanvasTileEngine$1, EventHandlers, LayerHandle, onClickCallback, onRightClickCallback, onHoverCallback, onMouseDownCallback, onMouseUpCallback, onMouseLeaveCallback, onDrawCallback, onZoomCallback } from '@canvas-tile-engine/core';
+import { Rect, Circle, ImageItem, Line, Text, Path, Coords, CanvasTileEngineConfig, CanvasTileEngine as CanvasTileEngine$1, EventHandlers, DrawHandle, IRenderer, onClickCallback, onRightClickCallback, onHoverCallback, onMouseDownCallback, onMouseUpCallback, onMouseLeaveCallback, onDrawCallback, onZoomCallback } from '@canvas-tile-engine/core';
 export { CanvasTileEngineConfig, CanvasTileEngine as CanvasTileEngineCore, Circle, Coords, DrawObject, EventHandlers, ImageItem, Line, Path, Rect, Text, gridToSize, onClickCallback, onDrawCallback, onHoverCallback, onMouseDownCallback, onMouseLeaveCallback, onMouseUpCallback } from '@canvas-tile-engine/core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface RectProps {
-    items: DrawObject | DrawObject[];
+    items: Rect | Rect[];
     layer?: number;
 }
 
 interface CircleProps {
-    items: DrawObject | DrawObject[];
+    items: Circle | Circle[];
     layer?: number;
 }
 
@@ -26,13 +26,7 @@ interface GridLinesProps {
 }
 
 interface LineProps {
-    items: {
-        from: Coords;
-        to: Coords;
-    } | {
-        from: Coords;
-        to: Coords;
-    }[];
+    items: Line | Line[];
     style?: {
         strokeStyle?: string;
         lineWidth?: number;
@@ -41,24 +35,12 @@ interface LineProps {
 }
 
 interface TextProps {
-    items: {
-        coords: Coords;
-        text: string;
-    } | {
-        coords: Coords;
-        text: string;
-    }[];
-    style?: {
-        fillStyle?: string;
-        font?: string;
-        textAlign?: CanvasTextAlign;
-        textBaseline?: CanvasTextBaseline;
-    };
+    items: Text | Text[];
     layer?: number;
 }
 
 interface PathProps {
-    items: Coords[] | Coords[][];
+    items: Path | Path[];
     style?: {
         strokeStyle?: string;
         lineWidth?: number;
@@ -67,13 +49,13 @@ interface PathProps {
 }
 
 interface StaticRectProps {
-    items: DrawObject[];
+    items: Rect[];
     cacheKey: string;
     layer?: number;
 }
 
 interface StaticCircleProps {
-    items: DrawObject[];
+    items: Circle[];
     cacheKey: string;
     layer?: number;
 }
@@ -86,7 +68,7 @@ interface StaticImageProps {
 
 interface DrawFunctionProps {
     /** The draw function to execute */
-    children: (ctx: CanvasRenderingContext2D, coords: Coords, config: Required<CanvasTileEngineConfig>) => void;
+    children: (ctx: unknown, coords: Coords, config: Required<CanvasTileEngineConfig>) => void;
     layer?: number;
 }
 
@@ -143,57 +125,34 @@ interface EngineHandle {
     }): void;
     /** Dynamically update event handlers at runtime */
     setEventHandlers(handlers: Partial<EventHandlers>): void;
+    /** Register a custom draw function */
+    addDrawFunction(fn: (ctx: unknown, coords: Coords, config: Required<CanvasTileEngineConfig>) => void, layer?: number): DrawHandle;
     /** Draw rectangles */
-    drawRect(items: DrawObject | DrawObject[], layer?: number): LayerHandle;
+    drawRect(items: Rect | Rect[], layer?: number): DrawHandle;
     /** Draw static rectangles (cached) */
-    drawStaticRect(items: DrawObject[], cacheKey: string, layer?: number): LayerHandle;
+    drawStaticRect(items: Rect[], cacheKey: string, layer?: number): DrawHandle;
     /** Draw circles */
-    drawCircle(items: DrawObject | DrawObject[], layer?: number): LayerHandle;
+    drawCircle(items: Circle | Circle[], layer?: number): DrawHandle;
     /** Draw static circles (cached) */
-    drawStaticCircle(items: DrawObject[], cacheKey: string, layer?: number): LayerHandle;
+    drawStaticCircle(items: Circle[], cacheKey: string, layer?: number): DrawHandle;
     /** Draw lines */
-    drawLine(items: {
-        from: Coords;
-        to: Coords;
-    } | {
-        from: Coords;
-        to: Coords;
-    }[], style?: {
+    drawLine(items: Line | Line[], style?: {
         strokeStyle?: string;
         lineWidth?: number;
-    }, layer?: number): LayerHandle;
+    }, layer?: number): DrawHandle;
     /** Draw text */
-    drawText(items: {
-        coords: Coords;
-        text: string;
-    } | {
-        coords: Coords;
-        text: string;
-    }[], style?: {
-        fillStyle?: string;
-        font?: string;
-        textAlign?: CanvasTextAlign;
-        textBaseline?: CanvasTextBaseline;
-    }, layer?: number): LayerHandle;
+    drawText(items: Text | Text[], layer?: number): DrawHandle;
     /** Draw paths/polylines */
     drawPath(items: Coords[] | Coords[][], style?: {
         strokeStyle?: string;
         lineWidth?: number;
-    }, layer?: number): LayerHandle;
+    }, layer?: number): DrawHandle;
     /** Draw images */
-    drawImage(items: (Omit<DrawObject, "style"> & {
-        img: HTMLImageElement;
-    }) | (Omit<DrawObject, "style"> & {
-        img: HTMLImageElement;
-    })[], layer?: number): LayerHandle;
+    drawImage(items: ImageItem | ImageItem[], layer?: number): DrawHandle;
     /** Draw static images (cached) */
-    drawStaticImage(items: (Omit<DrawObject, "style"> & {
-        img: HTMLImageElement;
-    })[], cacheKey: string, layer?: number): LayerHandle;
+    drawStaticImage(items: ImageItem[], cacheKey: string, layer?: number): DrawHandle;
     /** Draw grid lines */
-    drawGridLines(cellSize: number, lineWidth?: number, strokeStyle?: string, layer?: number): LayerHandle;
-    /** Add custom draw function */
-    addDrawFunction(fn: (ctx: CanvasRenderingContext2D, coords: Coords, config: Required<CanvasTileEngineConfig>) => void, layer?: number): LayerHandle;
+    drawGridLines(cellSize: number, lineWidth?: number, strokeStyle?: string, layer?: number): DrawHandle;
     /** Clear a specific layer */
     clearLayer(layer: number): void;
     /** Clear all layers */
@@ -201,9 +160,20 @@ interface EngineHandle {
     /** Clear static cache */
     clearStaticCache(cacheKey?: string): void;
     /** Remove a previously registered draw callback */
-    removeLayerHandle(handle: LayerHandle): void;
+    removeDrawHandle(handle: DrawHandle): void;
     /** Image loader instance (undefined until engine mounts) */
     readonly images: CanvasTileEngine$1["images"] | undefined;
+    /**
+     * Load an image using the engine's image loader.
+     * Returns a rejected promise if engine is not ready.
+     * @param src - Image URL to load
+     * @param retry - Number of retries on failure (default: 1)
+     * @example
+     * ```tsx
+     * const img = await engine.loadImage("/sprites/player.png");
+     * ```
+     */
+    loadImage(src: string, retry?: number): Promise<HTMLImageElement>;
 }
 /**
  * React hook that creates an engine handle for use with CanvasTileEngine component.
@@ -241,6 +211,15 @@ declare function useCanvasTileEngine(): EngineHandle;
 interface CanvasTileEngineProps {
     /** Engine handle from useCanvasTileEngine hook (required) */
     engine: EngineHandle;
+    /**
+     * Renderer instance to use.
+     * @example
+     * ```tsx
+     * import { RendererCanvas } from "@canvas-tile-engine/renderer-canvas";
+     * <CanvasTileEngine config={config} engine={engine} renderer={new RendererCanvas()} />
+     * ```
+     */
+    renderer: IRenderer;
     /** Engine configuration */
     config: CanvasTileEngineConfig;
     /** Initial center coordinates */
@@ -251,25 +230,128 @@ interface CanvasTileEngineProps {
     style?: React.CSSProperties;
     /** Draw components (Rect, Circle, Image, GridLines, etc.) */
     children?: React.ReactNode;
-    /** Callback when center coordinates change */
+    /**
+     * Callback when center coordinates change (pan or zoom).
+     * @param coords - Center world coordinates: `{ x, y }`
+     * @example
+     * ```tsx
+     * onCoordsChange={(coords) => {
+     *     console.log(`Center: ${coords.x}, ${coords.y}`);
+     * }}
+     * ```
+     */
     onCoordsChange?: (coords: Coords) => void;
-    /** Callback when a tile is clicked */
+    /**
+     * Callback when a tile is clicked (mouse or touch tap).
+     * @param coords - World coordinates: `raw` (exact), `snapped` (floored to tile)
+     * @param mouse - Canvas-relative position: `raw` (exact), `snapped` (tile-aligned)
+     * @param client - Viewport position: `raw` (exact), `snapped` (tile-aligned)
+     * @example
+     * ```tsx
+     * onClick={(coords) => {
+     *     console.log(`Clicked tile: ${coords.snapped.x}, ${coords.snapped.y}`);
+     * }}
+     * ```
+     */
     onClick?: onClickCallback;
-    /** Callback when a tile is right-clicked */
+    /**
+     * Callback when a tile is right-clicked.
+     * @param coords - World coordinates: `raw` (exact), `snapped` (floored to tile)
+     * @param mouse - Canvas-relative position: `raw` (exact), `snapped` (tile-aligned)
+     * @param client - Viewport position: `raw` (exact), `snapped` (tile-aligned)
+     * @example
+     * ```tsx
+     * onRightClick={(coords) => {
+     *     showContextMenu(coords.snapped.x, coords.snapped.y);
+     * }}
+     * ```
+     */
     onRightClick?: onRightClickCallback;
-    /** Callback when hovering over tiles */
+    /**
+     * Callback when hovering over tiles.
+     * @param coords - World coordinates: `raw` (exact), `snapped` (floored to tile)
+     * @param mouse - Canvas-relative position: `raw` (exact), `snapped` (tile-aligned)
+     * @param client - Viewport position: `raw` (exact), `snapped` (tile-aligned)
+     * @example
+     * ```tsx
+     * onHover={(coords) => {
+     *     setHoveredTile({ x: coords.snapped.x, y: coords.snapped.y });
+     * }}
+     * ```
+     */
     onHover?: onHoverCallback;
-    /** Callback on mouse down */
+    /**
+     * Callback on mouse/touch down.
+     * @param coords - World coordinates: `raw` (exact), `snapped` (floored to tile)
+     * @param mouse - Canvas-relative position: `raw` (exact), `snapped` (tile-aligned)
+     * @param client - Viewport position: `raw` (exact), `snapped` (tile-aligned)
+     * @example
+     * ```tsx
+     * onMouseDown={(coords) => {
+     *     startPainting(coords.snapped.x, coords.snapped.y);
+     * }}
+     * ```
+     */
     onMouseDown?: onMouseDownCallback;
-    /** Callback on mouse up */
+    /**
+     * Callback on mouse/touch up.
+     * @param coords - World coordinates: `raw` (exact), `snapped` (floored to tile)
+     * @param mouse - Canvas-relative position: `raw` (exact), `snapped` (tile-aligned)
+     * @param client - Viewport position: `raw` (exact), `snapped` (tile-aligned)
+     * @example
+     * ```tsx
+     * onMouseUp={() => {
+     *     stopPainting();
+     * }}
+     * ```
+     */
     onMouseUp?: onMouseUpCallback;
-    /** Callback on mouse leave */
+    /**
+     * Callback when mouse/touch leaves the canvas.
+     * @param coords - World coordinates: `raw` (exact), `snapped` (floored to tile)
+     * @param mouse - Canvas-relative position: `raw` (exact), `snapped` (tile-aligned)
+     * @param client - Viewport position: `raw` (exact), `snapped` (tile-aligned)
+     * @example
+     * ```tsx
+     * onMouseLeave={() => {
+     *     clearHoveredTile();
+     * }}
+     * ```
+     */
     onMouseLeave?: onMouseLeaveCallback;
-    /** Callback after each draw frame */
+    /**
+     * Callback after each draw frame. Use for custom canvas drawing.
+     * @param ctx - The canvas 2D rendering context
+     * @param info - Frame info: `scale`, `width`, `height`, `coords` (center)
+     * @example
+     * ```tsx
+     * onDraw={(ctx, info) => {
+     *     ctx.fillStyle = "red";
+     *     ctx.fillText(`Scale: ${info.scale}`, 10, 20);
+     * }}
+     * ```
+     */
     onDraw?: onDrawCallback;
-    /** Callback on canvas resize */
+    /**
+     * Callback on canvas resize.
+     * @example
+     * ```tsx
+     * onResize={() => {
+     *     console.log("Canvas resized");
+     * }}
+     * ```
+     */
     onResize?: () => void;
-    /** Callback when zoom level changes */
+    /**
+     * Callback when zoom level changes (wheel or pinch).
+     * @param scale - The new scale value
+     * @example
+     * ```tsx
+     * onZoom={(scale) => {
+     *     console.log(`Zoom level: ${scale}`);
+     * }}
+     * ```
+     */
     onZoom?: onZoomCallback;
 }
 
@@ -308,7 +390,7 @@ interface CanvasTileEngineProps {
  * }
  * ```
  */
-declare function CanvasTileEngineBase({ engine, config, center, className, style, children, onCoordsChange, onClick, onRightClick, onHover, onMouseDown, onMouseUp, onMouseLeave, onDraw, onResize, onZoom, }: CanvasTileEngineProps): react_jsx_runtime.JSX.Element;
+declare function CanvasTileEngineBase({ engine, renderer, config, center, className, style, children, onCoordsChange, onClick, onRightClick, onHover, onMouseDown, onMouseUp, onMouseLeave, onDraw, onResize, onZoom, }: CanvasTileEngineProps): react_jsx_runtime.JSX.Element;
 declare const CanvasTileEngine: typeof CanvasTileEngineBase & {
     Rect: react.NamedExoticComponent<RectProps>;
     Circle: react.NamedExoticComponent<CircleProps>;