SWKite Class Reference

/*
File: swKite.js
Date: 2026-04-24
Author: klp + GitHub Copilot
Workspace: SketchWaveTNT2026-04-21-Stg8
Purpose: SWKite class for SketchWaveJS
Comment(s):

SWKite: A kite shape — the general quadrilateral with two pairs of consecutive
equal sides. Unlike a rhombus (where all four sides are equal), a kite only requires:
  • two upper sides equal: √(diagX² + diagTop²) each
  • two lower sides equal: √(diagX² + diagBottom²) each

A rhombus (SWDiamond) is a special case of a kite where diagTop === diagBottom,
making all four sides equal. SWDiamond correctly extends SWKite — not the reverse.

Defaults: orange fill (HSB 30, 100, 100 = #ff8000), diagX=7, diagTop=10, diagBottom=4.
Breathing scales diagX (sinX) and both vertical halves proportionally (sinY).
Rotation tracks a cumulative angle (degrees, CCW in user/math convention).

Dependencies: p5.js, SWColor, SWPoint, SWGrid, SWSinusoid
*/

console.log("[swKite.js] SWKite class loaded.");

class SWKite {
    /**
     * @param {SWPoint} center       - Center point (SWPoint instance)
     * @param {number}  diagX        - Half-length of horizontal diagonal (user units)
     * @param {number}  diagTop      - Half-length of upper vertical diagonal (user units)
     * @param {number}  diagBottom   - Half-length of lower vertical diagonal (user units)
     * @param {SWColor} fillColor    - Fill color (SWColor instance)
     * @param {Object}  [options]
     *   strokeColor  : SWColor  — border color (optional)
     *   strokeWeight : number   — border thickness (default 3)
     *   showCenter   : boolean  — show center SWPoint (default false)
     *   rotation     : number   — initial rotation in degrees CCW (default 0)
     */
    constructor(center, diagX, diagTop, diagBottom, fillColor, options = {}) {
        // Pass diagTop as diagY to parent; parent handles center, diagX, colors, rotation
        super(center, diagX, diagTop, fillColor, options);
        this.diagTop    = diagTop;
        this.diagBottom = diagBottom;
        this.originalDiagTop    = diagTop;
        this.originalDiagBottom = diagBottom;
    }//end constructor

    // ── Geometric getters ──────────────────────────────────────────────────

    /**
     * Side length of the two upper sides: √(diagX² + diagTop²)
     */
    get topSideLength() {
        return Math.sqrt(this.diagX * this.diagX + this.diagTop * this.diagTop);
    }//end topSideLength

    /**
     * Side length of the two lower sides: √(diagX² + diagBottom²)
     */
    get bottomSideLength() {
        return Math.sqrt(this.diagX * this.diagX + this.diagBottom * this.diagBottom);
    }//end bottomSideLength

    /**
     * Area of a kite = (full horizontal diagonal × full vertical diagonal) / 2
     *                = (2 × diagX) × (diagTop + diagBottom) / 2
     *                = diagX × (diagTop + diagBottom)
     */
    get area() {
        return this.diagX * (this.diagTop + this.diagBottom);
    }//end area

    /**
     * Perimeter = 2 × (topSideLength + bottomSideLength)
     */
    get perimeter() {
        return 2 * (this.topSideLength + this.bottomSideLength);
    }//end perimeter

    /**
     * isRhombus — true when diagTop ≈ diagBottom (within 1% tolerance).
     * A kite becomes a rhombus when both vertical half-diagonals are equal.
     */
    get isRhombus() {
        const denom = Math.max(this.diagTop, this.diagBottom);
        if (denom === 0) return true;
        return Math.abs(this.diagTop - this.diagBottom) / denom < 0.01;
    }//end isRhombus

    // ── Drawing ────────────────────────────────────────────────────────────

    /**
     * Draw the kite in pixel space (no grid conversion).
     * Coordinates are already in screen pixels.
     */
    draw() {
        const rx  = this.diagX;
        const ryT = this.diagTop;
        const ryB = this.diagBottom;
        push();
        translate(this.center.x, this.center.y);
        rotate(-this.rotation * Math.PI / 180);

        if (this.fillColor && this.fillColor.col) {
            fill(this.fillColor.col);
        } else {
            noFill();
        }
        if (this.strokeColor && this.strokeColor.col) {
            stroke(this.strokeColor.col);
            strokeWeight(this.strokeWeight);
        } else {
            noStroke();
        }

        // quad(top, right, bottom, left) — kite vertices
        quad(0, -ryT,  rx, 0,  0, ryB,  -rx, 0);
        pop();

        if (this.showCenter) {
            this.center.draw();
        }
    }//end draw

    /**
     * Draw the kite mapped through a SWGrid.
     * @param {SWGrid} grid
     */
    drawOnGrid(grid) {
        const { x: cx, y: cy } = grid.userToScreen(this.center.x, this.center.y);
        const rx  = this.diagX      * grid.xScale;
        const ryT = this.diagTop    * grid.yScale;
        const ryB = this.diagBottom * grid.yScale;

        push();
        translate(cx, cy);
        rotate(-this.rotation * Math.PI / 180);

        if (this.fillColor && this.fillColor.col) {
            fill(this.fillColor.col);
        } else {
            noFill();
        }
        if (this.strokeColor && this.strokeColor.col) {
            stroke(this.strokeColor.col);
            strokeWeight(this.strokeWeight);
        } else {
            noStroke();
        }

        // quad(top, right, bottom, left) — kite vertices
        quad(0, -ryT,  rx, 0,  0, ryB,  -rx, 0);
        pop();

        if (this.showCenter) {
            this.center.drawOnGrid(grid);
        }
    }//end drawOnGrid

    /**
     * Draw the four kite tip vertices as dots on the grid.
     * Applies the same rotation as drawOnGrid() so dots follow the shape.
     * @param {SWGrid}  grid
     * @param {number}  [dotSize=8]   - Diameter of each dot in pixels
     * @param {SWColor} [dotColor]    - Color for the dots
     */
    drawVerticesOnGrid(grid, dotSize = 8, dotColor) {
        const { x: cx, y: cy } = grid.userToScreen(this.center.x, this.center.y);
        const rx  = this.diagX      * grid.xScale;
        const ryT = this.diagTop    * grid.yScale;
        const ryB = this.diagBottom * grid.yScale;

        // Four tip positions relative to center (screen space, un-rotated)
        const localVerts = [
            {x:  0,  y: -ryT},  // top
            {x:  rx, y:  0  },  // right
            {x:  0,  y:  ryB},  // bottom
            {x: -rx, y:  0  }   // left
        ];

        // Apply the same rotation as drawOnGrid()
        const angle = -this.rotation * Math.PI / 180;
        const cosA  = Math.cos(angle);
        const sinA  = Math.sin(angle);

        push();
        noStroke();
        if (dotColor && dotColor.col) {
            fill(dotColor.col);
        } else {
            fill(0, 75, 90, 100); // blue fallback
        }
        for (const v of localVerts) {
            const sx = cx + (v.x * cosA - v.y * sinA);
            const sy = cy + (v.x * sinA + v.y * cosA);
            circle(sx, sy, dotSize);
        }
        pop();
    }//end drawVerticesOnGrid

    // ── Animation ─────────────────────────────────────────────────────────

    /**
     * Apply sinusoidal breathing to diagX and/or the vertical diagonals.
     * sinX scales diagX; sinY scales both diagTop and diagBottom proportionally,
     * preserving the kite's asymmetry ratio.
     * Pass null to leave that dimension unchanged (holds at original value).
     * @param {SWSinusoid|null} sinX - Sinusoid for diagX scaling
     * @param {SWSinusoid|null} sinY - Sinusoid for diagTop/diagBottom scaling
     * @param {number} t             - Current time in seconds
     */
    breathe(sinX, sinY, t) {
        if (sinX !== null && sinX !== undefined) {
            this.diagX = this.originalDiagX * sinX.getValue(t);
        } else {
            this.diagX = this.originalDiagX;
        }
        if (sinY !== null && sinY !== undefined) {
            const scale = sinY.getValue(t);
            this.diagTop    = this.originalDiagTop    * scale;
            this.diagBottom = this.originalDiagBottom * scale;
        } else {
            this.diagTop    = this.originalDiagTop;
            this.diagBottom = this.originalDiagBottom;
        }
        // Keep parent's diagY in sync for any parent code that references it
        this.diagY = this.diagTop;
    }//end breathe

    /**
     * Reset all diagonals and center to their original (pre-animation) values.
     */
    reset() {
        this.diagX      = this.originalDiagX;
        this.diagTop    = this.originalDiagTop;
        this.diagBottom = this.originalDiagBottom;
        this.diagY      = this.originalDiagTop;
        this.center.x   = this.originalCenter.x;
        this.center.y   = this.originalCenter.y;
    }//end reset

    // ── Vertex helpers ────────────────────────────────────────────────────

    /**
     * Returns the four kite tip vertices in user coordinates (un-rotated).
     * @returns {{ top: {x,y}, right: {x,y}, bottom: {x,y}, left: {x,y} }}
     */
    getVerticesUserCoords() {
        return {
            top:    { x: this.center.x,              y: this.center.y + this.diagTop    },
            right:  { x: this.center.x + this.diagX, y: this.center.y                  },
            bottom: { x: this.center.x,              y: this.center.y - this.diagBottom },
            left:   { x: this.center.x - this.diagX, y: this.center.y                  }
        };
    }//end getVerticesUserCoords

    // ── Hit detection ─────────────────────────────────────────────────────
    // centerContainsPoint() is inherited from SWDiamond unchanged.

    /**
     * String representation
     */
    toString() {
        return `SWKite(center: (${this.center.x.toFixed(2)}, ${this.center.y.toFixed(2)}), ` +
               `diagX: ${this.diagX.toFixed(2)}, diagTop: ${this.diagTop.toFixed(2)}, ` +
               `diagBottom: ${this.diagBottom.toFixed(2)}, ` +
               `area: ${this.area.toFixed(2)}, rotation: ${this.rotation.toFixed(1)}°)`;
    }//end toString
}//end class SWKite

// export default SWKite;