@guinetik/gcanvas 1.0.0

package/src/shapes/geometry.js

@@ -0,0 +1,220 @@
+import { Euclidian } from "./euclidian.js";
+
+/**
+ * Geometry2d
+ * ----------
+ *
+ * A foundational class representing any object with spatial boundaries.
+ * Builds upon `Euclidian` by adding:
+ *
+ * - **Bounding logic** with memoization
+ * - **Constraint enforcement** (`minX`, `maxX`, etc.)
+ * - **Property change tracking** for dirty bounding recalculations
+ *
+ * This class is *not* concerned with transforms, rendering, or visibility.
+ * Instead, it's the core layer where **position + size = spatial identity**.
+ *
+ * ### Core Responsibilities
+ *
+ * 1. **Bounds Calculation**: Caches and computes bounding boxes using the Template Method pattern:
+ *    - `getBounds()` → returns cached bounds
+ *    - `calculateBounds()` → override point for subclasses
+ * 2. **Constraints**: Applies optional min/max limits on x/y positions
+ * 3. **Change Tracking**: Automatically marks bounds as dirty when spatial props are modified
+ * 4. **Tick Awareness**: Supports `update(dt)` to re-evaluate bounds when needed
+ *
+ * ### Coordinate System
+ *
+ * - The `x` and `y` properties refer to the **center** of the object.
+ * - Use `getLocalPosition()` for top-left alignment in layout systems.
+ *
+ * ### Subclassing Guidelines
+ *
+ * - Override `calculateBounds()` if the object has non-rectangular or transformed geometry.
+ * - Call `markBoundsDirty()` in custom logic if bounds-affecting state changes.
+ *
+ * @abstract
+ * @extends Euclidian
+ */
+export class Geometry2d extends Euclidian {
+  /**
+   * @param {Object} [options={}]
+   * @param {number} [options.minX] - Minimum X constraint (optional)
+   * @param {number} [options.maxX] - Maximum X constraint (optional)
+   * @param {number} [options.minY] - Minimum Y constraint (optional)
+   * @param {number} [options.maxY] - Maximum Y constraint (optional)
+   * @param {boolean} [options.crisp=true] - Whether to round to whole pixels
+   */
+  constructor(options = {}) {
+    super(options);
+    this._minX = options.minX;
+    this._maxX = options.maxX;
+    this._minY = options.minY;
+    this._maxY = options.maxY;
+    this._boundsDirty = true;
+    this._cachedBounds = null;
+    this.crisp = options.crisp ?? true;
+    this.logger.log("Geometry2d", this.x, this.y, this.width, this.height);
+  }
+
+  update() {
+    this.trace("Geometry2d.update");
+    this.applyConstraints();
+    this.getBounds(); // Trigger lazy recompute if dirty
+  }
+
+  /**
+   * Gets the minimum allowed X value.
+   * @type {number|undefined}
+   */
+  get minX() {
+    return this._minX;
+  }
+  set minX(v) {
+    this._minX = v;
+  }
+
+  /**
+   * Gets the maximum allowed X value.
+   * @type {number|undefined}
+   */
+  get maxX() {
+    return this._maxX;
+  }
+  set maxX(v) {
+    this._maxX = v;
+  }
+
+  /**
+   * Gets the minimum allowed Y value.
+   * @type {number|undefined}
+   */
+  get minY() {
+    return this._minY;
+  }
+  set minY(v) {
+    this._minY = v;
+  }
+
+  /**
+   * Gets the maximum allowed Y value.
+   * @type {number|undefined}
+   */
+  get maxY() {
+    return this._maxY;
+  }
+  set maxY(v) {
+    this._maxY = v;
+  }
+
+  /**
+   * Whether the bounding box is dirty and needs recalculation.
+   * @type {boolean}
+   * @readonly
+   */
+  get boundsDirty() {
+    return this._boundsDirty;
+  }
+
+  /**
+   * Applies positional constraints and optionally rounds to whole pixels.
+   */
+  applyConstraints() {
+    if (this._minX !== undefined) this.x = Math.max(this.x, this._minX);
+    if (this._maxX !== undefined) this.x = Math.min(this.x, this._maxX);
+    if (this._minY !== undefined) this.y = Math.max(this.y, this._minY);
+    if (this._maxY !== undefined) this.y = Math.min(this.y, this._maxY);
+
+    if (this.crisp) {
+      this.x = Math.round(this.x);
+      this.y = Math.round(this.y);
+      this.width = Math.round(this.width);
+      this.height = Math.round(this.height);
+    }
+  }
+
+  /**
+   * Returns the object's bounding box.
+   * Uses memoization to avoid unnecessary recomputation.
+   *
+   * @returns {{x: number, y: number, width: number, height: number}}
+   */
+  getBounds() {
+    if (this._boundsDirty || !this._cachedBounds) {
+      //this.trace("Geometry2d.getBounds", this.name || this.constructor.name, this._boundsDirty, this._cachedBounds);
+      this._cachedBounds = this.calculateBounds();
+      this._boundsDirty = false;
+    }
+    return this._cachedBounds;
+  }
+
+  /**
+   * Called by `getBounds()` when bounds are dirty.
+   * Can be overridden to support more complex bounds (e.g. transformed shapes).
+   *
+   * @protected
+   * @returns {{x: number, y: number, width: number, height: number}}
+   */
+  calculateBounds() {
+    return {
+      width: this.width,
+      height: this.height,
+      x: this.x,
+      y: this.y,
+    };
+  }
+
+  /**
+   * Returns the object's top-left corner, taking into account group containment.
+   * Useful for layouting or aligning objects to pixel grids.
+   *
+   * @returns {{x: number, y: number}}
+   */
+  getLocalPosition() {
+    // Get the parent group's position if it exists
+    let parentX = 0;
+    let parentY = 0;
+    
+    // If this object is part of a group, adjust for the group's position
+    if (this.parent) {
+      parentX = this.parent.x;
+      parentY = this.parent.y;
+    }
+
+    return {
+      x: (this.x - parentX) - this.width / 2,
+      y: (this.y - parentY) - this.height / 2,
+    };
+  }
+
+  /**
+   * Marks bounds as dirty.
+   * Called automatically by internal setters, but exposed for custom logic.
+   *
+   * @protected
+   */
+  markBoundsDirty() {
+    this._boundsDirty = true;
+  }
+
+  validateProp(v, prop) {
+    super.validateProp(v, prop);
+    const originalProp = this[prop];
+    if(v !== originalProp) {
+      //console.log("Geometry2d.marking bounds dirty", this.name || this.constructor.name, prop, v, "originalProp", originalProp);
+      this.markBoundsDirty();
+    }
+  }
+
+  setTopLeft(x, y) {
+    this.x = x + this.width / 2;
+    this.y = y + this.height / 2;
+    return this;
+  }
+  
+  setCenter(x, y) {
+    this.x = x;
+    this.y = y;
+    return this;
+  }
+}

package/src/shapes/group.js

@@ -0,0 +1,375 @@
+import { Painter } from "../painter/painter";
+import { Transformable } from "./transformable";
+import { ZOrderedCollection } from "../util";
+/**
+ * Group - A powerful container for composing and manipulating multiple transformable objects
+ * 
+ * ### Core Capabilities
+ * 
+ * - Aggregate multiple transformable objects into a single unit
+ * - Efficient bounding box calculation with memoization
+ * - Performant object management 
+ * - Property inheritance from group to children
+ *
+ * ### Rendering Behavior
+ * 
+ * - Applies group's transformations to all children 
+ * - Renders children in order of addition
+ * - Supports both Shape and GameObject hierarchies
+ *
+ * @extends Transformable
+ */
+export class Group extends Transformable {
+  /**
+   * Creates a new Group instance
+   * 
+   * @param {Object} [options={}] - Additional rendering options
+   * @param {boolean} [options.inheritOpacity=true] - Whether opacity should cascade to children 
+   * @param {boolean} [options.inheritVisible=true] - Whether visibility should cascade to children
+   * @param {boolean} [options.inheritScale=false] - Whether scale should cascade to children
+   */
+  constructor(options = {}) {
+    // Call parent constructor with all options
+    super(options);
+
+    // Create the z-ordered collection
+    this._collection = new ZOrderedCollection({
+      sortByZIndex: options.sortByZIndex || true
+    });
+    this._collection._owner = this; // Give collection a reference to its owner
+
+    // Initialize state tracking
+    this._childrenVersion = 0;
+    this._cachedBounds = null;
+
+    options.width = Math.max(0, options.width || 0);
+    options.height = Math.max(0, options.height || 0);
+
+    // Track if dimensions were explicitly set in constructor
+    this.userDefinedWidth = options.width;
+    this.userDefinedHeight = options.height;
+
+    // Only consider dimensions as user-defined if they were explicitly provided in options
+    this.userDefinedDimensions = options.width !== undefined && options.height !== undefined &&
+      (options.width > 0 || options.height > 0);
+  }
+
+
+  /**
+   * Add object to group with type checking
+   * @param {Transformable} object - Object to add
+   * @returns {Transformable} The added object
+   */
+  add(object) {
+    if (object == null || object == undefined) {
+      throw new Error("Object is null or undefined");
+    }
+    if (!(object instanceof Transformable)) {
+      throw new TypeError("Group can only add Transformable instances");
+    }
+    object.parent = this;
+    this._collection.add(object);
+    this._childrenVersion++;
+    this.markBoundsDirty();
+    this.invalidateCache();
+    return object;
+  }
+
+  /**
+   * Remove object from group
+   * @param {Transformable} object - Object to remove
+   * @returns {boolean} Whether object was removed
+   */
+  remove(object) {
+    const result = this._collection.remove(object);
+    if (result) {
+      object.parent = null;
+      this._childrenVersion++;
+      this.markBoundsDirty();
+      this.invalidateCache();
+    }
+    return result;
+  }
+
+  /**
+   * Clear all objects from group
+   */
+  clear() {
+    this._collection.clear();
+    this._childrenVersion++;
+    this.markBoundsDirty();
+    this.invalidateCache();
+  }
+
+  // Z-ordering methods
+  bringToFront(object) {
+    return this._collection.bringToFront(object);
+  }
+
+  sendToBack(object) {
+    return this._collection.sendToBack(object);
+  }
+
+  bringForward(object) {
+    return this._collection.bringForward(object);
+  }
+
+  sendBackward(object) {
+    return this._collection.sendBackward(object);
+  }
+
+  /**
+   * Render group and all children.
+   * Transformations are already applied by super.draw().
+   */
+  draw() {
+    super.draw();
+    this.logger.log("Group.draw children:", this.children.length);
+    this._renderChildren();
+  }
+
+  /**
+   * Render children normally (non-cached path)
+   * @private
+   */
+  _renderChildren() {
+    const sortedChildren = this._collection.getSortedChildren();
+    for (let i = 0; i < sortedChildren.length; i++) {
+      const child = sortedChildren[i];
+      if (child.visible) {
+        Painter.save();
+        child.render();
+        Painter.restore();
+      }
+    }
+  }
+
+
+  /**
+   * Update all children with active update methods
+   * @param {number} dt - Delta time in seconds
+   */
+  update(dt) {
+    this.logger.groupCollapsed("Group.update");
+    const sortedChildren = this._collection.getSortedChildren();
+
+    for (let i = 0; i < sortedChildren.length; i++) {
+      const child = sortedChildren[i];
+      if (child.active && typeof child.update === 'function') {
+        child.update(dt);
+      }
+    }
+    super.update(dt);
+    this.logger.groupEnd();
+  }
+
+  /**
+   * Get group's children array
+   * @returns {Array} Children array
+   */
+  get children() {
+    // Check if the collection exists and if it doesn't, return an empty array
+    return this._collection?.children || [];
+  }
+
+  /**
+   * Override width getter
+   * @returns {number} Width
+   */
+  get width() {
+    if (this.userDefinedDimensions) {
+      return this._width;
+    }
+    return this.getBounds().width;
+  }
+
+  /**
+   * Override width setter
+   * @param {number} v - New width
+   */
+  set width(v) {
+    const max = Math.max(0, v);
+    this._width = max;
+    this.userDefinedWidth = max;
+    this.userDefinedDimensions = (this.userDefinedWidth > 0 || this.userDefinedHeight > 0) &&
+      this.userDefinedWidth !== undefined && this.userDefinedHeight !== undefined;
+    this.markBoundsDirty();
+  }
+
+  /**
+   * Override height getter
+   * @returns {number} Height
+   */
+  get height() {
+    if (this.userDefinedDimensions) {
+      return this._height;
+    }
+    return this.getBounds().height;
+  }
+
+  /**
+   * Override height setter
+   * @param {number} v - New height
+   */
+  set height(v) {
+    const max = Math.max(0, v);
+    this._height = max;
+    this.userDefinedHeight = max;
+    this.userDefinedDimensions = (this.userDefinedWidth > 0 || this.userDefinedHeight > 0) &&
+      this.userDefinedWidth !== undefined && this.userDefinedHeight !== undefined;
+    this.markBoundsDirty();
+  }
+
+
+  /**
+   * Override calculateBounds to compute from children
+   * @returns {Object} Bounds object
+   */
+  calculateBounds() {
+    // If explicitly sized, use those dimensions
+    if (this.userDefinedDimensions) {
+      return {
+        x: this.x,
+        y: this.y,
+        width: this._width,
+        height: this._height
+      };
+    }
+
+    // No children = empty bounds
+    if (!this.children?.length) {
+      return {
+        x: this.x,
+        y: this.y,
+        width: 0,
+        height: 0
+      };
+    }
+
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+
+    // Calculate bounds from all children
+    for (const child of this.children) {
+      // Get the child's position and dimensions
+      const childX = child.x;
+      const childY = child.y;
+      const childWidth = child.width;
+      const childHeight = child.height;
+
+      // Calculate the child's bounding box edges
+      const childLeft = childX - childWidth / 2;
+      const childRight = childX + childWidth / 2;
+      const childTop = childY - childHeight / 2;
+      const childBottom = childY + childHeight / 2;
+
+      // Update min/max coordinates
+      minX = Math.min(minX, childLeft);
+      maxX = Math.max(maxX, childRight);
+      minY = Math.min(minY, childTop);
+      maxY = Math.max(maxY, childBottom);
+    }
+
+    // Calculate dimensions
+    const width = maxX - minX;
+    const height = maxY - minY;
+
+    // Return bounds centered on group position
+    return {
+      x: this.x,
+      y: this.y,
+      width: width,
+      height: height
+    };
+  }
+
+  /**
+   * Returns debug bounds in local space (centered at origin).
+   * Used for debug drawing after transforms have been applied.
+   * @returns {{x: number, y: number, width: number, height: number}}
+   */
+  getDebugBounds() {
+    const bounds = this.calculateBounds();
+
+    // Return bounds centered at local origin (0, 0)
+    // This works because debug is drawn after translation to group's position
+    return {
+      width: bounds.width,
+      height: bounds.height,
+      x: -bounds.width / 2,
+      y: -bounds.height / 2,
+    };
+  }
+
+  // ============================================================
+  // Group-wide Transform Operations
+  // ============================================================
+
+  /**
+   * Applies a transform callback to each child in the group.
+   * Useful for batch operations on all children.
+   *
+   * @param {function(import('./transform.js').Transform, import('./transformable.js').Transformable, number): void} callback
+   *   Callback receiving (transform, child, index)
+   * @returns {Group} this for chaining
+   *
+   * @example
+   * // Scale all children by 0.5
+   * group.forEachTransform((t) => t.scale(0.5));
+   *
+   * // Rotate each child differently
+   * group.forEachTransform((t, child, i) => t.rotation(i * 15));
+   */
+  forEachTransform(callback) {
+    this.children.forEach((child, index) => {
+      if (child.transform) {
+        callback(child.transform, child, index);
+      }
+    });
+    return this;
+  }
+
+  /**
+   * Translates all children by the given offset.
+   * This moves children relative to their current positions,
+   * not the group itself.
+   *
+   * @param {number} dx - Delta X
+   * @param {number} dy - Delta Y
+   * @returns {Group} this for chaining
+   */
+  translateChildren(dx, dy) {
+    return this.forEachTransform((t) => t.translateBy(dx, dy));
+  }
+
+  /**
+   * Scales all children by the given factor.
+   *
+   * @param {number} factor - Scale factor (1 = no change)
+   * @returns {Group} this for chaining
+   */
+  scaleChildren(factor) {
+    return this.forEachTransform((t) => t.scaleBy(factor));
+  }
+
+  /**
+   * Rotates all children by the given amount.
+   *
+   * @param {number} degrees - Rotation amount in degrees
+   * @returns {Group} this for chaining
+   */
+  rotateChildren(degrees) {
+    return this.forEachTransform((t) => t.rotateBy(degrees));
+  }
+
+  /**
+   * Resets transforms on all children to default values.
+   *
+   * @returns {Group} this for chaining
+   */
+  resetChildTransforms() {
+    return this.forEachTransform((t) => t.reset());
+  }
+}

package/src/shapes/heart.js

@@ -0,0 +1,42 @@
+import { Shape } from "./shape.js";
+import { Painter } from "../painter/painter.js";
+
+export class Heart extends Shape {
+  constructor(options = {}) {
+    super(options);
+  }
+
+  draw() {
+    super.draw();
+    const w = this.width;
+    const h = this.height;
+    const topCurveHeight = h * 0.3;
+    const lines = Painter.lines;
+    lines.beginPath();
+    lines.moveTo(0, topCurveHeight);
+    // Left arc
+    lines.bezierCurveTo(0, 0, -w / 2, 0, -w / 2, topCurveHeight);
+    // Bottom point
+    lines.bezierCurveTo(-w / 2, h * 0.8, 0, h, 0, h);
+    // Right arc
+    lines.bezierCurveTo(0, h, w / 2, h * 0.8, w / 2, topCurveHeight);
+    lines.bezierCurveTo(w / 2, 0, 0, 0, 0, topCurveHeight);
+    lines.closePath();
+    if (this.color) {
+      Painter.colors.fill(this.color);
+    }
+
+    if (this.stroke) {
+      Painter.colors.stroke(this.stroke, this.lineWidth);
+    }
+  }
+
+  getBounds() {
+    return {
+      x: this.x,
+      y: this.y + this.height / 2,
+      width: this.width,
+      height: this.height,
+    };
+  }
+}

package/src/shapes/hexagon.js

@@ -0,0 +1,26 @@
+import { Shape } from "./shape.js";
+import { Painter } from "../painter/painter.js";
+export class Hexagon extends Shape {
+  constructor(radius, options = {}) {
+    super(options);
+    this.radius = radius;
+  }
+
+  draw() {
+    super.draw();
+    const points = Array.from({ length: 6 }, (_, i) => {
+      const angle = (Math.PI / 3) * i;
+      return {
+        x: Math.cos(angle) * this.radius,
+        y: Math.sin(angle) * this.radius,
+      };
+    });
+
+    Painter.shapes.polygon(
+      points,
+      this.color,
+      this.stroke,
+      this.lineWidth
+    );
+  }
+}