@canvas-tile-engine/core 0.0.4 → 0.2.0

package/dist/index.d.mts

@@ -54,6 +54,7 @@ type CanvasTileEngineConfig = {
         maxWidth?: number;
         maxHeight?: number;
     };
+    responsive?: "preserve-scale" | "preserve-viewport" | false;
     eventHandlers?: EventHandlers;
     bounds?: {
         minX: number;
@@ -146,23 +147,27 @@ type DrawObject = {
     radius?: number | number[];
 };
 type Rect = DrawObject;
+type Circle = Omit<DrawObject, "rotate" | "radius">;
+type ImageItem = Omit<DrawObject, "style"> & {
+    img: HTMLImageElement;
+};
+type Text = Omit<DrawObject, "radius" | "size"> & {
+    text: string;
+    /** Font size in world units (scales with zoom). Default: 1 */
+    size?: number;
+    style?: {
+        fillStyle?: string;
+        /** Font family (default: "sans-serif") */
+        fontFamily?: string;
+        textAlign?: CanvasTextAlign;
+        textBaseline?: CanvasTextBaseline;
+    };
+};
 type Line = {
     from: Coords;
     to: Coords;
-    style: {
-        strokeStyle?: string;
-        lineWidth?: number;
-    };
-};
-type Circle = Omit<DrawObject, "rotate" | "radius">;
-type Text = {
-    coords: Coords;
-    text: string;
 };
 type Path = Coords[];
-type ImageItem = Omit<DrawObject, "style"> & {
-    img: HTMLImageElement;
-};
 
 /**
  * Core engine wiring camera, config, renderer, events, and draw helpers.
@@ -179,36 +184,148 @@ declare class CanvasTileEngine {
     images: ImageLoader;
     private sizeController;
     private animationController;
+    private responsiveWatcher?;
     canvasWrapper: HTMLDivElement;
     canvas: HTMLCanvasElement;
-    /** Callback: center coordinates change */
+    /**
+     * Callback when center coordinates change (pan or zoom).
+     * @param coords - Center world coordinates: `{ x, y }`
+     * @example
+     * ```ts
+     * engine.onCoordsChange = (coords) => {
+     *     console.log(`Center: ${coords.x}, ${coords.y}`);
+     * };
+     * ```
+     */
     onCoordsChange?: (coords: Coords) => void;
     private _onClick?;
+    /**
+     * 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
+     * ```ts
+     * engine.onClick = (coords, mouse, client) => {
+     *     console.log(`Clicked tile: ${coords.snapped.x}, ${coords.snapped.y}`);
+     * };
+     * ```
+     */
     get onClick(): onClickCallback | undefined;
     set onClick(cb: onClickCallback | undefined);
     private _onRightClick?;
+    /**
+     * 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
+     * ```ts
+     * engine.onRightClick = (coords) => {
+     *     showContextMenu(coords.snapped.x, coords.snapped.y);
+     * };
+     * ```
+     */
     get onRightClick(): onRightClickCallback | undefined;
     set onRightClick(cb: onRightClickCallback | undefined);
     private _onHover?;
+    /**
+     * 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
+     * ```ts
+     * engine.onHover = (coords) => {
+     *     setHoveredTile({ x: coords.snapped.x, y: coords.snapped.y });
+     * };
+     * ```
+     */
     get onHover(): onHoverCallback | undefined;
     set onHover(cb: onHoverCallback | undefined);
     private _onMouseDown?;
+    /**
+     * 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
+     * ```ts
+     * engine.onMouseDown = (coords) => {
+     *     startPainting(coords.snapped.x, coords.snapped.y);
+     * };
+     * ```
+     */
     get onMouseDown(): onMouseDownCallback | undefined;
     set onMouseDown(cb: onMouseDownCallback | undefined);
     private _onMouseUp?;
+    /**
+     * 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
+     * ```ts
+     * engine.onMouseUp = (coords) => {
+     *     stopPainting();
+     * };
+     * ```
+     */
     get onMouseUp(): onMouseUpCallback | undefined;
     set onMouseUp(cb: onMouseUpCallback | undefined);
     private _onMouseLeave?;
+    /**
+     * 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
+     * ```ts
+     * engine.onMouseLeave = () => {
+     *     clearHoveredTile();
+     * };
+     * ```
+     */
     get onMouseLeave(): onMouseLeaveCallback | undefined;
     set onMouseLeave(cb: onMouseLeaveCallback | undefined);
     private _onDraw?;
+    /**
+     * 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
+     * ```ts
+     * engine.onDraw = (ctx, info) => {
+     *     ctx.fillStyle = "red";
+     *     ctx.fillText(`Scale: ${info.scale}`, 10, 20);
+     * };
+     * ```
+     */
     get onDraw(): onDrawCallback | undefined;
     set onDraw(cb: onDrawCallback | undefined);
     private _onResize?;
+    /**
+     * Callback on canvas resize.
+     * @example
+     * ```ts
+     * engine.onResize = () => {
+     *     console.log("Canvas resized:", engine.getSize());
+     * };
+     * ```
+     */
     get onResize(): (() => void) | undefined;
     set onResize(cb: (() => void) | undefined);
     private _onZoom?;
-    /** Callback: zoom level changes (wheel or pinch) */
+    /**
+     * Callback when zoom level changes (wheel or pinch).
+     * @param scale - The new scale value
+     * @example
+     * ```ts
+     * engine.onZoom = (scale) => {
+     *     console.log(`Zoom level: ${scale}`);
+     * };
+     * ```
+     */
     get onZoom(): ((scale: number) => void) | undefined;
     set onZoom(cb: ((scale: number) => void) | undefined);
     /**
@@ -242,6 +359,12 @@ declare class CanvasTileEngine {
      * @returns Current canvas scale.
      */
     getScale(): number;
+    /**
+     * Set the canvas scale directly, clamped to min/max bounds.
+     * @param newScale The desired scale value.
+     * @throws {ConfigValidationError} If scale is not a positive finite number.
+     */
+    setScale(newScale: number): void;
     /**
      * Zoom in by a given factor, centered on the viewport.
      * @param factor Zoom multiplier (default: 1.5). Higher values zoom in more.
@@ -275,7 +398,11 @@ declare class CanvasTileEngine {
         minY: number;
         maxY: number;
     };
-    /** Set center coordinates from outside (adjusts the camera accordingly). */
+    /**
+     * Set center coordinates from outside (adjusts the camera accordingly).
+     * @param newCenter The new center coordinates.
+     * @throws {ConfigValidationError} If coordinates are not finite numbers.
+     */
     updateCoords(newCenter: Coords): void;
     /**
      * Smoothly move the camera center to target coordinates over the given duration.
@@ -283,6 +410,7 @@ declare class CanvasTileEngine {
      * @param y Target world y.
      * @param durationMs Animation duration in milliseconds (default: 500ms). Set to 0 for instant move.
      * @param onComplete Optional callback fired when animation completes.
+     * @throws {ConfigValidationError} If coordinates are not finite numbers.
      */
     goCoords(x: number, y: number, durationMs?: number, onComplete?: () => void): void;
     /**
@@ -335,7 +463,7 @@ declare class CanvasTileEngine {
      * @param items Rectangle definitions.
      * @param layer Layer order (lower draws first).
      */
-    drawRect(items: DrawObject | Array<DrawObject>, layer?: number): LayerHandle;
+    drawRect(items: Rect | Array<Rect>, layer?: number): LayerHandle;
     /**
      * Draw rectangles with pre-rendering cache (canvas renderer only).
      * Renders all items once to an offscreen canvas, then blits the visible portion each frame.
@@ -345,7 +473,7 @@ declare class CanvasTileEngine {
      * @param cacheKey Unique key for this cache (e.g., "minimap-items").
      * @param layer Layer order (lower draws first).
      */
-    drawStaticRect(items: Array<DrawObject>, cacheKey: string, layer?: number): LayerHandle;
+    drawStaticRect(items: Array<Rect>, cacheKey: string, layer?: number): LayerHandle;
     /**
      * Draw circles with pre-rendering cache (canvas renderer only).
      * Renders all items once to an offscreen canvas, then blits the visible portion each frame.
@@ -354,7 +482,7 @@ declare class CanvasTileEngine {
      * @param cacheKey Unique key for this cache (e.g., "minimap-circles").
      * @param layer Layer order (lower draws first).
      */
-    drawStaticCircle(items: Array<DrawObject>, cacheKey: string, layer?: number): LayerHandle;
+    drawStaticCircle(items: Array<Circle>, cacheKey: string, layer?: number): LayerHandle;
     /**
      * Draw images with pre-rendering cache (canvas renderer only).
      * Renders all items once to an offscreen canvas, then blits the visible portion each frame.
@@ -364,9 +492,7 @@ declare class CanvasTileEngine {
      * @param cacheKey Unique key for this cache (e.g., "terrain-cache").
      * @param layer Layer order (lower draws first).
      */
-    drawStaticImage(items: Array<Omit<DrawObject, "style"> & {
-        img: HTMLImageElement;
-    }>, cacheKey: string, layer?: number): LayerHandle;
+    drawStaticImage(items: Array<ImageItem>, cacheKey: string, layer?: number): LayerHandle;
     /**
      * Clear a static rendering cache.
      * @param cacheKey The cache key to clear, or undefined to clear all caches.
@@ -378,13 +504,7 @@ declare class CanvasTileEngine {
      * @param style Line style overrides.
      * @param layer Layer order.
      */
-    drawLine(items: Array<{
-        from: Coords;
-        to: Coords;
-    }> | {
-        from: Coords;
-        to: Coords;
-    }, style?: {
+    drawLine(items: Array<Line> | Line, style?: {
         strokeStyle?: string;
         lineWidth?: number;
     }, layer?: number): LayerHandle;
@@ -393,32 +513,36 @@ declare class CanvasTileEngine {
      * @param items Circle definitions.
      * @param layer Layer order.
      */
-    drawCircle(items: DrawObject | Array<DrawObject>, layer?: number): LayerHandle;
+    drawCircle(items: Circle | Array<Circle>, layer?: number): LayerHandle;
     /**
      * Draw one or many texts at world positions (canvas renderer only).
-     * @param items Text definitions.
-     * @param style Text style overrides.
+     * @param items Text definitions with position, text, size, and style.
      * @param layer Layer order.
+     * @example
+     * ```ts
+     * engine.drawText({
+     *     x: 0,
+     *     y: 0,
+     *     text: "Hello",
+     *     size: 1, // 1 tile height
+     *     style: { fillStyle: "black", fontFamily: "Arial" }
+     * });
+     *
+     * // Multiple texts
+     * engine.drawText([
+     *     { x: 0, y: 0, text: "A", size: 2 },
+     *     { x: 1, y: 0, text: "B", size: 2 }
+     * ]);
+     * ```
      */
-    drawText(items: Array<{
-        coords: Coords;
-        text: string;
-    }> | {
-        coords: Coords;
-        text: string;
-    }, style?: {
-        fillStyle?: string;
-        font?: string;
-        textAlign?: CanvasTextAlign;
-        textBaseline?: CanvasTextBaseline;
-    }, layer?: number): LayerHandle;
+    drawText(items: Array<Text> | Text, layer?: number): LayerHandle;
     /**
      * Draw one or many polylines through world points (canvas renderer only).
      * @param items Polyline point collections.
      * @param style Stroke style overrides.
      * @param layer Layer order.
      */
-    drawPath(items: Array<Coords[]> | Coords[], style?: {
+    drawPath(items: Array<Path> | Path, style?: {
         strokeStyle?: string;
         lineWidth?: number;
     }, layer?: number): LayerHandle;
@@ -428,11 +552,7 @@ declare class CanvasTileEngine {
      * @param items Image definitions.
      * @param layer Layer order.
      */
-    drawImage(items: Array<Omit<DrawObject, "style"> & {
-        img: HTMLImageElement;
-    }> | (Omit<DrawObject, "style"> & {
-        img: HTMLImageElement;
-    }), layer?: number): LayerHandle;
+    drawImage(items: Array<ImageItem> | ImageItem, layer?: number): LayerHandle;
     /**
      *  Draw grid lines at specified cell size (canvas renderer only).
      * @param cellSize Size of each grid cell in world units.
@@ -546,4 +666,24 @@ declare const VISIBILITY_BUFFER: {
     readonly TILE_BUFFER: 1;
 };
 
-export { COORDINATE_OVERLAY, CanvasTileEngine, type CanvasTileEngineConfig, type Circle, type Coords, DEBUG_HUD, DEFAULT_VALUES, type DrawObject, type EventHandlers, type ImageItem, type LayerHandle, type Line, type Path, RENDER_DEFAULTS, type Rect, SCALE_LIMITS, SIZE_LIMITS, type Text, VISIBILITY_BUFFER, type onClickCallback, type onDrawCallback, type onHoverCallback, type onMouseDownCallback, type onMouseLeaveCallback, type onMouseUpCallback, type onRightClickCallback, type onZoomCallback };
+/**
+ * Convert grid-based dimensions to pixel-based config.
+ * @param options Grid configuration with columns, rows, and cell size.
+ * @returns Config object with size and scale properties.
+ * @example
+ * ```ts
+ * const config = {
+ *     ...gridToSize({ columns: 12, rows: 12, cellSize: 50 }),
+ *     backgroundColor: "#337426",
+ * };
+ * // config.size = { width: 600, height: 600 }
+ * // config.scale = 50
+ * ```
+ */
+declare function gridToSize(options: {
+    columns: number;
+    rows: number;
+    cellSize: number;
+}): Pick<CanvasTileEngineConfig, "size" | "scale">;
+
+export { COORDINATE_OVERLAY, CanvasTileEngine, type CanvasTileEngineConfig, type Circle, type Coords, DEBUG_HUD, DEFAULT_VALUES, type DrawObject, type EventHandlers, type ImageItem, type LayerHandle, type Line, type Path, RENDER_DEFAULTS, type Rect, SCALE_LIMITS, SIZE_LIMITS, type Text, VISIBILITY_BUFFER, gridToSize, type onClickCallback, type onDrawCallback, type onHoverCallback, type onMouseDownCallback, type onMouseLeaveCallback, type onMouseUpCallback, type onRightClickCallback, type onZoomCallback };