@guinetik/gcanvas 1.0.0

package/src/painter/painter.js

@@ -0,0 +1,295 @@
+import { Logger } from "../logger/logger";
+import { PainterColors } from "./painter.colors";
+import { PainterEffects } from "./painter.effects";
+import { PainterImages } from "./painter.img";
+import { PainterLines } from "./painter.lines";
+import { PainterOpacity } from "./painter.opacity";
+import { PainterShapes } from "./painter.shapes";
+import { PainterText } from "./painter.text";
+
+/**
+ * Painter - Static utility class for all canvas drawing operations
+ * Provides a cleaner API for common canvas operations with additional utilities
+ */
+export class Painter {
+  static #_colors = null;
+  static #_effects = null;
+  static #_img = null;
+  static #_lines = null;
+  static #_opacity = null;
+  static #_shapes = null;
+  static #_text = null;
+
+  static #checkInitialized(propName, value) {
+    if (!value) {
+        throw new Error(`Painter.${propName} is not initialized. Call Painter.init(ctx) first.`);
+    }
+  }
+
+  /**
+   * @type {PainterColors}
+   */
+  static get colors() {
+    this.#checkInitialized('colors', this.#_colors);
+    return this.#_colors;
+  }
+  /**
+   * @type {PainterEffects}
+   */
+  static get effects() {
+    this.#checkInitialized('effects', this.#_effects);
+    return this.#_effects;
+  }
+  /**
+   * @type {PainterImages}
+   */
+  static get img() {
+      this.#checkInitialized('img', this.#_img);
+      return this.#_img;
+  }
+  /**
+   * @type {PainterLines}
+   */
+  static get lines() {
+      this.#checkInitialized('lines', this.#_lines);
+      return this.#_lines;
+  }
+  /**
+   * @type {PainterOpacity}
+   */
+  static get opacity() {
+      this.#checkInitialized('opacity', this.#_opacity);
+      return this.#_opacity;
+  }
+  /**
+   * @type {PainterShapes}
+   */
+  static get shapes() {
+      this.#checkInitialized('shapes', this.#_shapes);
+      return this.#_shapes;
+  }
+  /**
+   * @type {PainterText}
+   */
+  static get text() {
+      this.#checkInitialized('text', this.#_text);
+      return this.#_text;
+  }
+  /**
+   * @type {Logger}
+   */
+  static logger;
+
+  static set ctx(ctx) {
+    this._ctx = ctx;
+  }
+
+  /**
+   * @type {CanvasRenderingContext2D}
+   */
+  static get ctx() {
+    if (!this._ctx) {
+      throw new Error("Cannot access Painter.ctx before initialization!");
+    }
+    return this._ctx;
+  }
+
+  /**
+   * Initialize the painter with a canvas context
+   * @param {CanvasRenderingContext2D} ctx - The canvas context
+   */
+  static init(ctx) {
+    this._ctx = ctx;
+    this.saveStack = [];
+    this.#_colors = PainterColors;
+    this.#_effects = PainterEffects;
+    this.#_img = PainterImages;
+    this.#_lines = PainterLines;
+    this.#_opacity = PainterOpacity;
+    this.#_shapes = PainterShapes;
+    this.#_text = PainterText;
+    Painter.logger = Logger.getLogger("Painter");
+    Painter.saveStack = [];
+  }
+
+  /**
+   * Switch the painter to a different canvas context.
+   * Used when multiple games/canvases exist on the same page.
+   * @param {CanvasRenderingContext2D} ctx - The canvas context to use
+   */
+  static setContext(ctx) {
+    this._ctx = ctx;
+  }
+
+  static save() {
+    // Extract just the method name from the stack trace
+    const stackLine = new Error().stack.split("\n")[2] || "";
+    const methodMatch = stackLine.match(/at\s+(\w+)\.(\w+)/);
+    const callerInfo = methodMatch
+      ? `${methodMatch[1]}.${methodMatch[2]}`
+      : "unknown";
+
+    // Add to tracking stack
+    this.saveStack.push(callerInfo);
+
+    // Log with caller info
+    this.logger.log(`Painter.save() by: ${callerInfo}`);
+
+    // Perform actual save
+    this.ctx.save();
+    Painter.opacity.saveOpacityState();
+  }
+
+  static restore() {
+    // Check for stack underflow
+    if (this.saveStack.length === 0) {
+      console.error("PAINTER ERROR: restore() without matching save()!");
+      return;
+    }
+
+    // Get the matching caller from stack
+    const caller = this.saveStack.pop();
+
+    // Log with caller info
+    this.logger.log(`Painter.restore() balancing save from: ${caller}`);
+
+    // Perform actual restore
+    // Note: ctx.restore() already restores fillStyle/strokeStyle from the save stack.
+    // Do NOT set fillStyle/strokeStyle to null here - it breaks subsequent fills.
+    this.ctx.restore();
+    Painter.opacity.restoreOpacityState();
+  }
+
+  static translateTo(x, y) {
+    // make sure x a valid number not NaN or undefined. default to 0 if so
+    if (isNaN(x) || x === undefined) {
+      x = 0;
+    }
+    if (isNaN(y) || y === undefined) {
+      y = 0;    
+    }
+    this.logger.log("moveTo", x, y);
+    this.ctx.translate(x, y);
+  }
+
+  static resetPosition() {
+    // Reset just the translation portion of the transform
+    this.logger.log("resetPosition");
+    const transform = this.ctx.getTransform();
+    this.ctx.setTransform(
+      transform.a,
+      transform.b,
+      transform.c,
+      transform.d,
+      0,
+      0
+    );
+  }
+
+  static withPosition(x, y, callback) {
+    this.logger.log("withPosition", x, y);
+    this.save();
+    this.translateTo(x, y);
+    callback();
+    this.restore();
+  }
+
+  /**
+   * Clear the entire canvas or a specific rectangle
+   * @param {number} [x=0] - X coordinate
+   * @param {number} [y=0] - Y coordinate
+   * @param {number} [width=canvas.width] - Width
+   * @param {number} [height=canvas.height] - Height
+   * @returns {void}
+   */
+  static clear(
+    x = 0,
+    y = 0,
+    width = Painter.ctx.canvas.width,
+    height = Painter.ctx.canvas.height
+  ) {
+    Painter.ctx.clearRect(x, y, width, height);
+  }
+
+  /**
+   * Translate the canvas
+   * @param {number} x - X translation
+   * @param {number} y - Y translation
+   * @returns {void}
+   */
+  static translate(x, y) {
+    Painter.ctx.translate(x, y);
+  }
+
+  /**
+   * Rotate the canvas
+   * @param {number} angle - Rotation angle in radians
+   * @returns {void}
+   */
+  static rotate(angle) {
+    Painter.logger.log("Painter.rotate", angle);
+    Painter.ctx.rotate(angle);
+  }
+
+  /**
+   * Scale the canvas
+   * @param {number} x - X scale factor
+   * @param {number} y - Y scale factor
+   * @returns {void}
+   */
+  static scale(x, y) {
+    Painter.logger.log("Painter.scale", x, y);
+    Painter.ctx.scale(x, y);
+  }
+
+  /**
+   * Safely use the canvas context for direct drawing operations.
+   * Automatically handles path cleanup to prevent fill/stroke bleeding
+   * between different drawing operations.
+   *
+   * @param {function(CanvasRenderingContext2D): void} callback - Function that receives ctx
+   * @param {object} [options={}] - Options for context handling
+   * @param {boolean} [options.saveState=false] - Whether to save/restore full canvas state
+   * @returns {void}
+   *
+   * @example
+   * // Basic usage - draws a custom path with automatic cleanup
+   * Painter.useCtx((ctx) => {
+   *   ctx.strokeStyle = "white";
+   *   ctx.lineWidth = 2;
+   *   ctx.moveTo(0, 0);
+   *   ctx.lineTo(100, 100);
+   *   ctx.stroke();
+   * });
+   *
+   * @example
+   * // With state preservation - restores all canvas state after
+   * Painter.useCtx((ctx) => {
+   *   ctx.fillStyle = "red";
+   *   ctx.fillRect(0, 0, 50, 50);
+   * }, { saveState: true });
+   */
+  static useCtx(callback, options = {}) {
+    const ctx = this.ctx;
+    const { saveState = false } = options;
+
+    // Optionally save full canvas state
+    if (saveState) {
+      this.save();
+    }
+
+    // Start with a fresh path
+    ctx.beginPath();
+
+    // Execute user's drawing code
+    callback(ctx);
+
+    // Clear path to prevent bleeding into subsequent renders
+    ctx.beginPath();
+
+    // Optionally restore full canvas state
+    if (saveState) {
+      this.restore();
+    }
+  }
+}

package/src/painter/painter.lines.js

@@ -0,0 +1,189 @@
+import { Painter } from "./painter";
+
+export class PainterLines {
+  static path(commands, fill, stroke, lineWidth = 1) {
+    const ctx = Painter.ctx;
+    ctx.beginPath();
+    for (const cmd of commands) {
+      const [type, ...args] = cmd;
+      if (type === "M") ctx.moveTo(...args);
+      else if (type === "L") ctx.lineTo(...args);
+      else if (type === "C") ctx.bezierCurveTo(...args);
+      else if (type === "Q") ctx.quadraticCurveTo(...args);
+      else if (type === "Z") ctx.closePath();
+    }
+    if (fill) {
+      ctx.fillStyle = fill;
+      Painter.colors.fill(fill);
+    }
+    if (stroke) {
+      ctx.strokeStyle = stroke;
+      ctx.lineWidth = lineWidth;
+      Painter.colors.stroke();
+    }
+  }
+
+  /**
+   * Draw a line
+   * @param {number} x1 - Start X
+   * @param {number} y1 - Start Y
+   * @param {number} x2 - End X
+   * @param {number} y2 - End Y
+   * @param {string|CanvasGradient} [color] - Line color
+   * @param {number} [lineWidth] - Line width
+   * @returns {void}
+   */
+  static line(x1, y1, x2, y2, color, lineWidth) {
+    Painter.ctx.beginPath();
+    Painter.ctx.moveTo(x1, y1);
+    Painter.ctx.lineTo(x2, y2);
+    Painter.colors.stroke(color, lineWidth);
+  }
+
+  /**
+   * Start a new path
+   * @returns {void}
+   */
+  static beginPath() {
+    Painter.ctx.beginPath();
+  }
+
+  /**
+   * Close the current path
+   * @returns {void}
+   */
+  static closePath() {
+    Painter.ctx.closePath();
+  }
+
+  /**
+   * Move to a point without drawing
+   * @param {number} x - X coordinate
+   * @param {number} y - Y coordinate
+   * @returns {void}
+   */
+  static moveTo(x, y) {
+    Painter.ctx.moveTo(x, y);
+  }
+
+  /**
+   * Draw a line to a point
+   * @param {number} x - X coordinate
+   * @param {number} y - Y coordinate
+   * @returns {void}
+   */
+  static lineTo(x, y) {
+    Painter.ctx.lineTo(x, y);
+  }
+
+  /**
+   * Add a bezier curve to the current path
+   * @param {number} cp1x - Control point 1 X
+   * @param {number} cp1y - Control point 1 Y
+   * @param {number} cp2x - Control point 2 X
+   * @param {number} cp2y - Control point 2 Y
+   * @param {number} x - End X
+   * @param {number} y - End Y
+   * @returns {void}
+   */
+  static bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y) {
+    Painter.ctx.bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y);
+  }
+
+  /**
+   * Draw a dashed line
+   * @param {number} x1 - Start X
+   * @param {number} y1 - Start Y
+   * @param {number} x2 - End X
+   * @param {number} y2 - End Y
+   * @param {Array<number>} dash - Dash pattern array [dash, gap, dash, gap, ...]
+   * @param {string|CanvasGradient} [color] - Line color
+   * @param {number} [lineWidth] - Line width
+   * @returns {void}
+   */
+  static dashedLine(x1, y1, x2, y2, dash, color, lineWidth) {
+    Painter.ctx.beginPath();
+    if (color) Painter.ctx.strokeStyle = color;
+    if (lineWidth !== undefined) Painter.ctx.lineWidth = lineWidth;
+
+    // Set the dash pattern
+    Painter.ctx.setLineDash(dash);
+
+    Painter.ctx.moveTo(x1, y1);
+    Painter.ctx.lineTo(x2, y2);
+    Painter.colors.stroke();
+
+    // Reset the dash pattern
+    Painter.ctx.setLineDash([]);
+  }
+
+  /**
+   * Draw a dotted line
+   * @param {number} x1 - Start X
+   * @param {number} y1 - Start Y
+   * @param {number} x2 - End X
+   * @param {number} y2 - End Y
+   * @param {number} dotSize - Size of dots
+   * @param {number} gap - Gap between dots
+   * @param {string|CanvasGradient} [color] - Line color
+   * @returns {void}
+   */
+  static dottedLine(x1, y1, x2, y2, dotSize = 2, gap = 5, color) {
+    return Painter.lines.dashedLine(
+      x1,
+      y1,
+      x2,
+      y2,
+      [dotSize, gap],
+      color,
+      dotSize
+    );
+  }
+
+  /**
+   * Set line dash pattern
+   * @param {Array<number>} segments - Array of line, gap lengths
+   * @returns {void}
+   */
+  static setLineDash(segments) {
+    Painter.ctx.setLineDash(segments);
+  }
+
+  /**
+   * Reset line dash to solid line
+   * @returns {void}
+   */
+  static resetLineDash() {
+    Painter.ctx.setLineDash([]);
+  }
+
+  /**
+   * Set line width
+   * @param {number} width - Line width
+   * @returns {void}
+   */
+  static setLineWidth(width) {
+    Painter.ctx.lineWidth = width;
+  }
+
+  /**
+   * Draw quadratic curve
+   * @param {number} x1 - Start X
+   * @param {number} y1 - Start Y
+   * @param {number} cpx - Control point X
+   * @param {number} cpy - Control point Y
+   * @param {number} x2 - End X
+   * @param {number} y2 - End Y
+   * @param {string|CanvasGradient} [color] - Stroke color
+   * @param {number} [lineWidth] - Line width
+   * @returns {void}
+   */
+  static quadraticCurve(x1, y1, cpx, cpy, x2, y2, color, lineWidth) {
+    Painter.ctx.beginPath();
+    Painter.ctx.moveTo(x1, y1);
+    Painter.ctx.quadraticCurveTo(cpx, cpy, x2, y2);
+    if (color) Painter.ctx.strokeStyle = color;
+    if (lineWidth !== undefined) Painter.ctx.lineWidth = lineWidth;
+    Painter.colors.stroke();
+  }
+}

package/src/painter/painter.opacity.js

@@ -0,0 +1,41 @@
+import { Painter } from "./painter";
+
+export class PainterOpacity {
+  static _opacityStack = [1]; // Initialize with full opacity
+
+  static pushOpacity(opacity) {
+    // Compute compound opacity (multiply with current)
+    const currentOpacity = this._opacityStack[this._opacityStack.length - 1];
+    const newOpacity = currentOpacity * opacity;
+    // Push to stack and apply
+    this._opacityStack.push(newOpacity);
+    Painter.logger.log("NEXT OPACITY WILL BE", newOpacity);
+    Painter.effects.setAlpha(newOpacity);
+  }
+
+  static popOpacity() {
+    if (this._opacityStack.length > 1) {
+      this._opacityStack.pop();
+      const newOpacity = this._opacityStack[this._opacityStack.length - 1];
+      Painter.logger.log("NEXT OPACITY WILL BE", newOpacity);
+      Painter.effects.setAlpha(newOpacity);
+    }
+  }
+
+  static _clone() {
+    // Create a deep copy of the opacity stack
+    this._opacityStack = [...this._opacityStack];
+  }
+  
+
+  static saveOpacityState() {
+    this._opacityStateBackup = [...this._opacityStack];
+  }
+  
+  static restoreOpacityState() {
+    if (this._opacityStateBackup) {
+      this._opacityStack = this._opacityStateBackup;
+      delete this._opacityStateBackup;
+    }
+  }
+}