📶 SWWifi Reference

/*
File:    swWifi.js
Date:    2026-04-23
Author:  klp + GitHub Copilot
App:     SketchWaveTNT2026-04-21-Stg8
Purpose: SWWifi — a WiFi signal composite shape made of concentric arcs
         and a center dot, all rendered as a single group.

=== Layout ===
  The shape is centered on `center` (an SWPoint in user/grid coords).
  `numArcs` concentric arcs are drawn with increasing radii:
    radius[i] = innerRadius + i * arcSpacing   (i = 0 is innermost)
  Each arc spans `theta` degrees, symmetrically centered on `direction`.
  A filled disk of radius `dotRadius` sits at the center (origin point).

=== Arc Angle Convention ===
  SketchWave uses math angles: CCW from +x axis, y increases upward.
  `direction` is the angle the signal points (default 90 = straight up).
  Each arc spans from (direction − theta/2) to (direction + theta/2).
  Conversion to p5 screen angles (y-axis flipped):
    p5Start = −radians(direction + theta/2)
    p5Stop  = −radians(direction − theta/2)

=== Signal Strength / Active Count ===
  `activeCount` (0..numArcs) controls how many arcs glow at full brightness.
  Arcs beyond activeCount are drawn dimmed by `dimFactor`.
  Set activeCount to 0 for “no signal”, numArcs for “full signal”.

=== Design Parameters (user/grid units unless noted) ===
  center           — SWPoint: anchor of the group (default origin)
  numArcs          — number of concentric arcs (default 3)
  innerRadius      — innermost arc radius in user units (default 1.5)
  arcSpacing       — radial gap between consecutive arcs (default 1.2)
  dotRadius        — center dot radius in user units (default 0.4)
  theta            — arc angular span in degrees (default 90)
  direction        — direction the signal points, °CCW from +x (default 90 = up)
  rotation         — static rotation offset in degrees (default 0)
  thickness        — arc stroke weight in pixels (default 6)
  arcColor         — SWColor for arcs (default sky-blue)
  dotColor         — SWColor for center dot (default sky-blue)
  fillOpacity      — alpha 0–100 for arcs and dot (default 100)
  activeCount      — arcs drawn at full brightness (default = numArcs)
  dimFactor        — brightness multiplier for inactive arcs (default 0.25)
  inactiveOpacity  — alpha 0–100 for inactive arcs (default 35)
  showCenter       — draw anchor crosshair (default false)

=== Interaction: Drag ===
  When showCenter is true a small crosshair handle is visible at the anchor.
  Grabbing that handle moves the shape in user-space coords.
    isDraggable              — enable/disable drag (default true)
    handleMousePressed(mx, my, grid [,tolerance]) → bool
    handleMouseDragged(mx, my, grid)              → bool
    handleMouseReleased()
    isDragging (read-only getter)

=== Animation ===
  breatheThickness(sinusoid, t)   — oscillate arc stroke weight
  rotateAboutCenter(degPerSec, t) — spin the whole group; accumulates _animRotDeg
  reset()                         — restore all original values

=== Drawing ===
  drawOnGrid(grid)  — preferred: center.x/y treated as user-space coords
  draw()            — raw: center.x/y treated as screen pixels (scale = 1)

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

console.log("[swWifi.js] SWWifi class loaded.");

class SWWifi {

    /**
     * @param {object}  opts
     * @param {SWPoint} opts.center           — anchor of the group (default origin)
     * @param {number}  opts.numArcs          — number of concentric arcs (default 3)
     * @param {number}  opts.innerRadius      — innermost arc radius in user units (default 1.5)
     * @param {number}  opts.arcSpacing       — radial gap between arcs in user units (default 1.2)
     * @param {number}  opts.dotRadius        — center dot radius in user units (default 0.4)
     * @param {number}  opts.theta            — arc angular span in degrees (default 90)
     * @param {number}  opts.direction        — signal direction, °CCW from +x axis (default 90 = up)
     * @param {number}  opts.rotation         — static rotation offset in degrees (default 0)
     * @param {number}  opts.thickness        — arc stroke weight in pixels (default 6)
     * @param {SWColor} opts.arcColor         — color for all arcs (default sky-blue)
     * @param {SWColor} opts.dotColor         — color for the center dot (default sky-blue)
     * @param {number}  opts.fillOpacity      — alpha 0–100 for arcs and dot (default 100)
     * @param {number}  opts.activeCount      — arcs at full brightness (default = numArcs)
     * @param {number}  opts.dimFactor        — brightness factor for inactive arcs 0–1 (default 0.25)
     * @param {number}  opts.inactiveOpacity  — alpha 0–100 for inactive arcs (default 35)
     * @param {boolean} opts.showCenter       — draw anchor crosshair (default false)
     */
    constructor({
        center      = new SWPoint(0, 0),
        numArcs     = 3,
        innerRadius = 1.5,
        arcSpacing  = 1.2,
        dotRadius   = 0.4,
        theta       = 90,
        direction   = 90,
        rotation    = 0,
        thickness   = 6,
        arcColor    = undefined,
        dotColor    = undefined,
        fillOpacity = 100,
        activeCount = undefined,
        dimFactor       = 0.25,
        inactiveOpacity = 35,
        showCenter      = false,
    } = {}) {
        this.center      = center;
        this.numArcs     = numArcs;
        this.innerRadius = innerRadius;
        this.arcSpacing  = arcSpacing;
        this.dotRadius   = dotRadius;
        this.theta       = theta;
        this.direction   = direction;
        this.rotation    = rotation;
        this.thickness   = thickness;
        this.fillOpacity = fillOpacity;
        this.activeCount = (activeCount !== undefined) ? activeCount : numArcs;
        this.dimFactor       = Math.max(0, Math.min(1, dimFactor));
        this.inactiveOpacity = Math.max(0, Math.min(100, inactiveOpacity));
        this.showCenter      = showCenter;
        this.pulseIndex      = -1;   // -1 = off (use activeCount); >=0 = single lit arc

        // Drag state
        this.isDraggable  = true;
        this._isDragging  = false;
        this._dragOffsetX = 0;      // user-unit offset at drag start
        this._dragOffsetY = 0;

        // Default color: sky-blue HSB(210, 80, 92)
        this.arcColor = arcColor
            ? SWColor.copy(arcColor)
            : new SWColor(210, 80, 92, fillOpacity, "arcColor");
        this.dotColor = dotColor
            ? SWColor.copy(dotColor)
            : new SWColor(210, 80, 92, fillOpacity, "dotColor");

        // Animated thickness — may differ from this.thickness when breathe is active
        this._thickness  = thickness;
        // Accumulated spin angle (degrees, CCW)
        this._animRotDeg = 0;

        // Store originals for reset()
        this._origNumArcs     = numArcs;
        this._origInnerRadius = innerRadius;
        this._origArcSpacing  = arcSpacing;
        this._origDotRadius   = dotRadius;
        this._origTheta       = theta;
        this._origDirection   = direction;
        this._origRotation    = rotation;
        this._origThickness   = thickness;
        this._origFillOpacity = fillOpacity;
        this._origActiveCount = (activeCount !== undefined) ? activeCount : numArcs;
        this._origDimFactor       = this.dimFactor;
        this._origInactiveOpacity = this.inactiveOpacity;
        this._origArcColor        = SWColor.copy(this.arcColor);
        this._origDotColor        = SWColor.copy(this.dotColor);
    }//end constructor

    // —— Computed helpers —————————————————————————————————————————————

    /** Radius of arc i (0 = innermost) in user units. */
    arcRadius(i) {
        return this.innerRadius + i * this.arcSpacing;
    }//arcRadius

    /** Outer radius of the outermost arc in user units. */
    get maxRadius() {
        return this.arcRadius(Math.max(0, this.numArcs - 1));
    }//get maxRadius

    // —— Animation ——————————————————————————————————————————————————————————————

    /**
     * Oscillate arc stroke weight using a sinusoid.
     * The sinusoid’s getValue(t) should return pixel values (e.g. 2–14).
     * @param {SWSinusoid} sinusoid
     * @param {number}     t — elapsed time in seconds since breath started
     */
    breatheThickness(sinusoid, t) {
        this._thickness = Math.max(0.5, sinusoid.getValue(t));
    }//breatheThickness

    /**
     * Rotate the WiFi group about its center.
     * @param {number} degPerSec — CCW positive; negative = CW
     * @param {number} t — elapsed time in seconds since spin started
     */
    rotateAboutCenter(degPerSec, t) {
        this._animRotDeg = degPerSec * t;
    }//rotateAboutCenter

    /** Restore all original parameter values and clear animation state. */
    reset() {
        this.numArcs     = this._origNumArcs;
        this.innerRadius = this._origInnerRadius;
        this.arcSpacing  = this._origArcSpacing;
        this.dotRadius   = this._origDotRadius;
        this.theta       = this._origTheta;
        this.direction   = this._origDirection;
        this.rotation    = this._origRotation;
        this.thickness   = this._origThickness;
        this.fillOpacity = this._origFillOpacity;
        this.activeCount = this._origActiveCount;
        this.dimFactor       = this._origDimFactor;
        this.inactiveOpacity = this._origInactiveOpacity;
        this.arcColor        = SWColor.copy(this._origArcColor);
        this.dotColor    = SWColor.copy(this._origDotColor);
        this._thickness  = this._origThickness;
        this._animRotDeg = 0;
        this.pulseIndex  = -1;
    }//reset

    // —— Interaction: Drag —————————————————————————————————————————————————————————————

    /**
     * Call from the p5.js mousePressed() function.
     * Starts a drag if the click is within the center handle (visible only when
     * showCenter is true). Returns true if this instance consumed the event.
     *
     * @param {number} mx            - p5 mouseX (screen pixels)
     * @param {number} my            - p5 mouseY (screen pixels)
     * @param {SWGrid} grid          - the active SWGrid
     * @param {number} [tolerance=0] - extra pixel margin around the 8 px handle
     * @returns {boolean}
     */
    handleMousePressed(mx, my, grid, tolerance = 0) {
        if (!this.isDraggable || !this.showCenter) return false;
        const s  = grid.userToScreen(this.center.x, this.center.y);
        const dx = mx - s.x;
        const dy = my - s.y;
        const hitR = 8 + tolerance;
        if (dx * dx + dy * dy > hitR * hitR) return false;
        const u = grid.screenToUser(mx, my);
        this._isDragging  = true;
        this._dragOffsetX = u.x - this.center.x;
        this._dragOffsetY = u.y - this.center.y;
        return true;
    }//end handleMousePressed

    /**
     * Call from the p5.js mouseDragged() function.
     * Moves the center while preserving the original grab offset.
     * Returns true while this instance is being dragged.
     *
     * @param {number} mx   - p5 mouseX (screen pixels)
     * @param {number} my   - p5 mouseY (screen pixels)
     * @param {SWGrid} grid - the active SWGrid
     * @returns {boolean}
     */
    handleMouseDragged(mx, my, grid) {
        if (!this._isDragging) return false;
        const u = grid.screenToUser(mx, my);
        this.center.setPosition(
            u.x - this._dragOffsetX,
            u.y - this._dragOffsetY
        );
        return true;
    }//end handleMouseDragged

    /**
     * Call from the p5.js mouseReleased() function.
     * Ends the drag operation.
     */
    handleMouseReleased() {
        this._isDragging = false;
    }//end handleMouseReleased

    /** True while the user is actively dragging this instance. @type {boolean} */
    get isDragging() { return this._isDragging; }

    // —— Drawing ——————————————————————————————————————————————————————————————————————
     /* center.x / center.y are treated as pixel positions; scale = 1 px/unit.
     */
    draw() {
        this._drawShape(this.center.x, this.center.y, 1);
    }//draw

    /**
     * Draw mapped through the given SWGrid.
     * center.x / center.y are user-space coordinates.
     * @param {SWGrid} grid
     */
    drawOnGrid(grid) {
        const s = grid.userToScreen(this.center.x, this.center.y);
        this._drawShape(s.x, s.y, grid.xScale);
    }//drawOnGrid

    /**
     * Internal rendering kernel.
     * @param {number} cx    — screen x of center
     * @param {number} cy    — screen y of center
     * @param {number} scale — pixels per user unit
     */
    _drawShape(cx, cy, scale) {
        const totalDeg = this.rotation + this._animRotDeg;
        const rotRad   = -totalDeg * (Math.PI / 180);   // CCW user → CW p5 (y-flipped)

        push();
        translate(cx, cy);
        rotate(rotRad);

        // —— Arcs (innermost first so outer arcs overlay inner on overlap) ——
        for (let i = 0; i < this.numArcs; i++) {
            const r        = this.arcRadius(i) * scale;
            // Pulse mode: only one arc lit at a time; otherwise use activeCount range
            const isActive = this.pulseIndex >= 0
                ? (i === this.pulseIndex)
                : (i < this.activeCount);

            // Active arcs: full color / opacity; inactive: dimmed brightness + reduced alpha
            const col   = isActive
                ? this.arcColor
                : this.arcColor.createDarkerColor(this.dimFactor);
            const alpha = isActive
                ? this.fillOpacity
                : this.inactiveOpacity;

            noFill();
            stroke(col.h, col.s, col.b, alpha);
            strokeWeight(this._thickness);
            strokeCap(ROUND);

            // Arc centered on `direction`, spanning `theta` degrees.
            //   User-space: arc goes CCW from (direction − theta/2) to (direction + theta/2)
            //   p5 screen (y-flipped, CW angles):
            //     p5Start = −radians(direction + theta/2)
            //     p5Stop  = −radians(direction − theta/2)
            //   Since theta > 0: p5Start < p5Stop → p5 draws the short CW arc ✓
            const half    = this.theta / 2;
            const p5Start = -((this.direction + half) * (Math.PI / 180));
            const p5Stop  = -((this.direction - half) * (Math.PI / 180));
            arc(0, 0, 2 * r, 2 * r, p5Start, p5Stop, OPEN);
        }

        // —— Center dot ——————————————————————————————————————————————
        const dr = this.dotRadius * scale;
        noStroke();
        // Dot is always “active” (lit) — it marks the signal origin
        fill(this.dotColor.h, this.dotColor.s, this.dotColor.b, this.fillOpacity);
        ellipse(0, 0, 2 * dr, 2 * dr);

        noStroke();
        noFill();
        pop();

        // —— Center-handle marker (drawn outside push/pop, at screen anchor) ——
        if (this.showCenter) {
            const r = 8;
            push();
            translate(cx, cy);
            strokeWeight(2);
            stroke(0, 0, 15, 100);
            fill(0, 0, 100, 85);
            ellipse(0, 0, r * 2, r * 2);
            stroke(0, 0, 15, 100);
            strokeWeight(1.5);
            line(-(r - 2), 0, r - 2, 0);
            line(0, -(r - 2), 0, r - 2);
            noStroke();
            noFill();
            pop();
        }
    }//_drawShape

    // —— toString ————————————————————————————————————————————————————————————————

    toString() {
        return `SWWifi(center:(${this.center.x.toFixed(2)},${this.center.y.toFixed(2)}), ` +
               `${this.numArcs} arcs, innerR:${this.innerRadius.toFixed(2)}, ` +
               `spacing:${this.arcSpacing.toFixed(2)}, dotR:${this.dotRadius.toFixed(2)}, ` +
               `theta:${this.theta.toFixed(0)}°, dir:${this.direction.toFixed(0)}°, ` +
               `active:${this.activeCount}/${this.numArcs})`;
    }//toString

}//end class SWWifi