@pacem/pacem-2d 1.0.0-bessel → 1.0.0-dirac

package/dist/browser/pacem-2d.min.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-2d v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-2d v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/bundle/pacem-2d.min.mjs

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-2d v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-2d v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */

package/dist/bundle/pacem-2d.mjs

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-2d v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-2d v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -91,6 +91,13 @@ function isRadialGradient(object) {
   return isGradient(object) && "center" in object && Point.isPoint(object.center) && "radius" in object && typeof object.radius === "number";
 }
 var PresentationState = class {
+  /**
+   * Combines two presentation states (typically an item's own state and the one inherited from its
+   * ancestors), giving precedence to `lhs` whenever both define a value.
+   * @param lhs Own/most specific presentation state.
+   * @param rhs Inherited/fallback presentation state.
+   * @param precomputedMatrix If provided, used as-is instead of multiplying `lhs`'s and `rhs`'s transform matrices.
+   */
   static combine(lhs, rhs, precomputedMatrix = null) {
     return {
       opacity: (lhs.opacity ?? 1) * (rhs.opacity ?? 1),
@@ -129,11 +136,13 @@ var UI2DEvent = class extends CustomUIEvent {
   get transformMatrix() {
     return this.#transformMatrix;
   }
+  /** Projects a point (defaults to the event's screen coordinates) through the event's transform matrix. */
   project(pt = { x: this.screenX, y: this.screenY }) {
     return Matrix2D.multiply(pt, this.#transformMatrix);
   }
 };
 var Shape = class {
+  /** Returns an empty `ShapeGeometry` (no path, no vertices, zero-sized bounding rect). */
   static empty() {
     return { pathData: "", vertices: [], boundingRect: { x: 0, y: 0, width: 0, height: 0 } };
   }
@@ -249,9 +258,11 @@ var Pacem2DElement = class Pacem2DElement2 extends Components.PacemItemsContaine
       this.#panningStart = null;
     };
   }
+  /** @readonly Gets the DOM element hosting the stage content. */
   get stage() {
     return this._stage;
   }
+  /** Processes the stage content and returns a snapshot image (delegates to the current `adapter`). */
   snapshot(bgColor, type, quality) {
     const adapter = this.adapter;
     if (Utils2.isNull(adapter)) {
@@ -261,6 +272,7 @@ var Pacem2DElement = class Pacem2DElement2 extends Components.PacemItemsContaine
   }
   #originalViewBox;
   #transformMatrix;
+  /** @readonly Gets the matrix that projects stage coords into screen coords. */
   get transformMatrix() {
     return this.#transformMatrix;
   }
@@ -513,9 +525,11 @@ var DrawableElement = class _DrawableElement extends Components2.PacemCrossItems
   findContainer() {
     return this.parent || this.stage;
   }
+  /** @readonly Gets the `Pacem2DElement` stage this drawable belongs to. */
   get stage() {
     return this["_scene"] = this["_scene"] || CustomElementUtils.findAncestorOfType(this, Pacem2DElement);
   }
+  /** @readonly Gets the closest ancestor `DrawableElement` (e.g. a containing group), if any. */
   get parent() {
     return this["_drawableParent"] = this["_drawableParent"] || CustomElementUtils.findAncestor(this, (i) => i instanceof _DrawableElement);
   }
@@ -661,20 +675,24 @@ var ShapeElement = class extends PresentationElement {
     super.viewActivatedCallback();
     this.recomputeShape();
   }
+  /** Recomputes `data`, `vertices` and `boundingRect` from `getShapeGeometry()`. */
   recomputeShape() {
     const { pathData, vertices, boundingRect } = this.getShapeGeometry();
     this.#vertices = vertices;
     this.#boundingRect = boundingRect;
     this.data = pathData;
   }
+  /** @readonly Gets the SVG path data backing the shape. */
   get pathData() {
     return this.data;
   }
   #boundingRect;
+  /** @readonly Gets the bounding rectangle of the shape. */
   get boundingRect() {
     return this.#boundingRect;
   }
   #vertices;
+  /** @readonly Gets the vertices making up the shape. */
   get vertices() {
     return this.#vertices;
   }
@@ -696,6 +714,7 @@ var PacemGroupElement = class PacemGroupElement2 extends PresentationElement {
     return item instanceof DrawableElement && item.parent === this;
   }
   #children = [];
+  /** @readonly Gets the child drawables currently in the group. */
   get childDrawables() {
     return this.#children;
   }
@@ -797,6 +816,7 @@ var PacemEllipseElement = PacemEllipseElement_1 = class PacemEllipseElement2 ext
       }
     }
   }
+  /** Computes the SVG path data of the ellipse (or sector) out of its own `center`/`rx`/`ry`/`start`/`end`. */
   getPathData() {
     const a = this.rx, b = this.ry, c = this.center, s = this.start ?? 0, e = this.end ?? 0;
     if (!Utils5.isNull(c) && !Utils5.isNull(a) && !Utils5.isNull(b)) {
@@ -809,6 +829,14 @@ var PacemEllipseElement = PacemEllipseElement_1 = class PacemEllipseElement2 ext
     const a = this.rx ?? 0, b = this.ry ?? 0;
     return getShapeGeometry(center, a, b, this.start, this.end);
   }
+  /**
+   * Computes the SVG path data of an ellipse, or of a pie-slice sector when `start`/`end` don't describe a full turn.
+   * @param c Center point.
+   * @param rx Horizontal radius.
+   * @param ry Vertical radius.
+   * @param start Sector start angle, in degrees.
+   * @param end Sector end angle, in degrees.
+   */
   static getPathData(c = { x: NaN, y: NaN }, rx = NaN, ry = NaN, start, end) {
     const { pathData } = getShapeGeometry(c, rx, ry, start, end);
     return pathData;
@@ -846,6 +874,7 @@ var PacemCircleElement = PacemCircleElement_1 = class PacemCircleElement2 extend
       }
     }
   }
+  /** Computes the SVG path data of the circle (or sector) out of its own `center`/`radius`/`start`/`end`. */
   getPathData() {
     const r = this.radius, c = this.center;
     if (!Utils5.isNull(c) && !Utils5.isNull(r)) {
@@ -858,6 +887,13 @@ var PacemCircleElement = PacemCircleElement_1 = class PacemCircleElement2 extend
     const r = this.radius ?? 0;
     return getShapeGeometry(center, r, r, this.start, this.end);
   }
+  /**
+   * Computes the SVG path data of a circle, or of a pie-slice sector when `start`/`end` don't describe a full turn.
+   * @param c Center point.
+   * @param r Radius.
+   * @param start Sector start angle, in degrees.
+   * @param end Sector end angle, in degrees.
+   */
   static getPathData(c = { x: NaN, y: NaN }, r = NaN, start, end) {
     return PacemEllipseElement.getPathData(c, r, r, start, end);
   }
@@ -939,6 +975,7 @@ var PacemRectElement = PacemRectElement_1 = class PacemRectElement2 extends Shap
       this.recomputeShape();
     }
   }
+  /** Computes the SVG path data of the rectangle out of its own `x`/`y`/`w`/`h`/`r`/`cornerType`. */
   getPathData() {
     const x = this.x, y = this.y, w = this.w, h = this.h;
     let r = this.r ?? { rx: { value: 0 }, ry: { value: 0 }, type: CornerType.Rounded };
@@ -1072,6 +1109,7 @@ var PacemLineElement = PacemLineElement_1 = class PacemLineElement2 extends Shap
     const boundingRect = { x: Math.min(x0, x1), y: Math.min(y0, y1), width: Math.abs(x0 - x1), height: Math.abs(y0 - y1) };
     return { pathData: this.getPathData(), vertices: [from, to], boundingRect };
   }
+  /** Computes the SVG path data of the line out of its own `from`/`to` points. */
   getPathData() {
     const from = this.from, to = this.to;
     if (!Utils7.isNull(from) && !Utils7.isNull(to)) {
@@ -1079,6 +1117,7 @@ var PacemLineElement = PacemLineElement_1 = class PacemLineElement2 extends Shap
     }
     return null;
   }
+  /** Computes the SVG path data of a straight segment between `from` and `to`. */
   static getPathData(from = { x: NaN, y: NaN }, to = { x: NaN, y: NaN }) {
     const x0 = from.x, y0 = from.y, x1 = to.x, y1 = to.y;
     return `M ${x0} ${y0} L ${x1} ${y1}`;
@@ -1151,6 +1190,7 @@ var PacemPolygonElement = PacemPolygonElement_1 = class PacemPolygonElement2 ext
       }
     }
   }
+  /** Computes the SVG path data of the polygon out of its own `center`, `radius`, `sides` and `starIndent`. */
   getPathData() {
     const sides = this.sides, radius = this.radius, center = this.center;
     if (!Utils8.isNull(sides) && !Utils8.isNull(radius)) {
@@ -1165,6 +1205,13 @@ var PacemPolygonElement = PacemPolygonElement_1 = class PacemPolygonElement2 ext
     }
     return PacemPolygonElement_1.getShapeGeometry(c, r, sides, si);
   }
+  /**
+   * Computes the geometry (path data, vertices, bounding rect) of a regular polygon or star.
+   * @param center Center point.
+   * @param radius Circumradius.
+   * @param sides Number of sides (or points, for a star).
+   * @param starIndent Star indentation factor (0 = regular polygon).
+   */
   static getShapeGeometry(center, radius, sides, starIndent = 0) {
     const p0 = { x: center.x, y: center.y - radius };
     let retval = `M ${p0.x} ${p0.y}`;
@@ -1196,6 +1243,7 @@ var PacemPolygonElement = PacemPolygonElement_1 = class PacemPolygonElement2 ext
       boundingRect: { x: p0.x - radius, y: p0.y, width, height: width }
     };
   }
+  /** Computes the SVG path data of a regular polygon or star. See `getShapeGeometry` for the parameters. */
   static getPathData(center, radius, sides, starIndent = 0) {
     const { pathData } = PacemPolygonElement_1.getShapeGeometry(center, radius, sides, starIndent);
     return pathData;
@@ -1253,6 +1301,11 @@ var PacemPolylineElement = PacemPolylineElement_1 = class PacemPolylineElement2
       }
     }
   }
+  /**
+   * Computes the geometry (path data, vertices, bounding rect) of a polyline.
+   * @param points Vertices, in order.
+   * @param closed Whether the polyline is closed back onto its first point.
+   */
   static getShapeGeometry(points, closed) {
     if (Utils9.isNullOrEmpty(points)) {
       return Shape.empty();
@@ -1276,10 +1329,12 @@ var PacemPolylineElement = PacemPolylineElement_1 = class PacemPolylineElement2
   getShapeGeometry() {
     return PacemPolylineElement_1.getShapeGeometry(this.points, this.closed);
   }
+  /** Computes the SVG path data of the polyline out of its own `points`/`closed`. */
   getPathData() {
     const { pathData } = this.getShapeGeometry();
     return pathData;
   }
+  /** Computes the SVG path data of a polyline. See `getShapeGeometry` for the parameters. */
   static getPathData(points, closed) {
     const { pathData } = PacemPolylineElement_1.getShapeGeometry(points, closed);
     return pathData;
@@ -1397,11 +1452,18 @@ PacemTextElement = __decorate12([
 import { Utils as Utils11, UI } from "@pacem/pacem-core";
 import { Rect as Rect3 } from "@pacem/pacem-foundation";
 var AdapterUtils = class {
+  /**
+   * Dispatches a `StageEvent` (prefixed with `'stage'`) on the given stage, when it is an `EventTarget`.
+   * @param stage The target stage.
+   * @param type Short event type name.
+   * @param evt The original event.
+   */
   static stageDispatch(stage, type, evt) {
     if (stage instanceof EventTarget) {
       stage.dispatchEvent(new StageEvent("stage" + type, stage, evt, stage.transformMatrix));
     }
   }
+  /** Type guard telling whether `viewbox` is a well-formed, finite `Rect` usable as a stage viewbox. */
   static isValidViewbox(viewbox) {
     return !Utils11.isNullOrEmpty(viewbox) && Rect3.isRect(viewbox) && Number.isFinite(viewbox.x) && Number.isFinite(viewbox.y) && Number.isFinite(viewbox.width) && Number.isFinite(viewbox.height);
   }
@@ -1451,6 +1513,14 @@ var Pacem2DAdapterElement = class extends PacemEventTarget {
       fill: "#fff"
     };
   }
+  /**
+   * Rasterizes the given DOM element into an image `Blob`, defaulting to JPEG when `bgColor` is provided
+   * (to flatten transparency against it) and to PNG otherwise.
+   * @param element Element to snapshot.
+   * @param bgColor Background color to flatten transparency against; if set, defaults `type` to `'image/jpeg'`.
+   * @param type Explicit image MIME type, overrides the `bgColor`-based default.
+   * @param quality Compression quality, applicable to lossy formats (defaults to `.9` for JPEG).
+   */
   snapshotElement(element, bgColor, type, quality) {
     const jpeg = !Utils12.isNullOrEmpty(bgColor), mime = type ?? (jpeg ? "image/jpeg" : null), compression = quality ?? (jpeg ? JPEG_QUALITY : null);
     return Utils12.snapshotElement(element, bgColor, mime, compression);