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

package/dist/esm/adapter.js

@@ -1,19 +1,33 @@
 /*!
- * @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
  */
 import { PacemEventTarget, Utils } from '@pacem/pacem-core';
 const JPEG_QUALITY = .9;
+/**
+ * Base class for the rendering adapters (SVG, Canvas) assignable to a `Pacem2DElement` stage. Concrete
+ * adapters are responsible for initializing/disposing the underlying DOM surface, sizing it, drawing the
+ * scene graph, hit-testing and producing snapshot images.
+ */
 export class Pacem2DAdapterElement extends PacemEventTarget {
     constructor() {
         super(...arguments);
+        /** Fallback stroke/fill/lineWidth values used when a shape doesn't provide its own. */
         this.DefaultShapeValues = {
             stroke: "#000",
             lineWidth: 1,
             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 = !Utils.isNullOrEmpty(bgColor), mime = type ?? (jpeg ? 'image/jpeg' : null), compression = quality ?? (jpeg ? JPEG_QUALITY : null);
         return Utils.snapshotElement(element, bgColor, mime, compression);

package/dist/esm/constants.js

@@ -1,7 +1,9 @@
 /*!
- * @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
  */
+/** Middle segment shared by every `<pacem-2d-*>` custom element tag name. */
 export const TAG_MIDDLE_NAME = "2d";
+/** `2 * Math.PI`, a full turn in radians. */
 export const TWO_PI = 2 * Math.PI;

package/dist/esm/drawable-element.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
  */
@@ -11,6 +11,11 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { Components, CustomElementUtils, PropertyConverters, Watch, } from '@pacem/pacem-core';
 import { Pacem2DElement } from './stage';
+/**
+ * Root of the `<pacem-2d-*>` drawable elements hierarchy: wires a custom element up to its containing
+ * `Pacem2DElement` stage and, in case of nesting, its parent drawable. By default children are not allowed
+ * (only `PacemGroupElement` overrides `validate` to accept them).
+ */
 export class DrawableElement extends Components.PacemCrossItemsContainerElement {
     validate(_) {
         // by default no children allowed (Group will except)
@@ -20,9 +25,11 @@ export class DrawableElement extends Components.PacemCrossItemsContainerElement
         // override
         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);
     }

package/dist/esm/drawing.js

@@ -1,28 +1,40 @@
 /*!
- * @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
  */
 import { Utils, CustomUIEvent } from '@pacem/pacem-core';
 import { Point, Matrix2D } from '@pacem/pacem-foundation';
+/** Type guard telling whether `object` implements `Drawable`. */
 export function isDrawable(object) {
     return !Utils.isNull(object) && 'stage' in object;
 }
+/** Type guard telling whether `object` implements `UiObject`. */
 export function isUiObject(object) {
     return /*'transformMatrix' in object &&*/ isDrawable(object);
 }
 function isGradient(object) {
     return 'stops' in object && Utils.isArray(object.stops);
 }
+/** Type guard telling whether `object` is a `LinearGradient`. */
 export function isLinearGradient(object) {
     return isGradient(object) && 'start' in object && Point.isPoint(object.start)
         && 'end' in object && Point.isPoint(object.end);
 }
+/** Type guard telling whether `object` is a `RadialGradient`. */
 export function isRadialGradient(object) {
     return isGradient(object) && 'center' in object && Point.isPoint(object.center)
         && 'radius' in object && typeof object.radius === 'number';
 }
+/** Static helpers to combine `PresentationState` instances (e.g. a shape's own state with its inherited parent state). */
 export class PresentationState {
+    /**
+     * 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),
@@ -36,6 +48,7 @@ export class PresentationState {
         };
     }
 }
+/** Type guard telling whether `object` implements `PresentationObject`. */
 export function isPresentationObject(object) {
     return isUiObject(object)
         && ('fill' in object
@@ -47,18 +60,26 @@ export function isPresentationObject(object) {
             || 'opacity' in object
             || 'lineCap' in object);
 }
+/** Type guard telling whether `object` implements `Shape`. */
 export function isShape(object) {
     return isUiObject(object) && 'pathData' in object;
 }
+/** Type guard telling whether `object` implements `Group` and has at least one child drawable. */
 export function isGroup(object) {
     return isUiObject(object) && 'childDrawables' in object && !Utils.isNullOrEmpty(object['childDrawables']);
 }
+/** Type guard telling whether `object` implements `Text`. */
 export function isText(object) {
     return isUiObject(object) && 'text' in object && typeof object['text'] === 'string';
 }
+/** Type guard telling whether `object` implements `Image`. */
 export function isImage(object) {
     return isUiObject(object) && 'src' in object && typeof object['src'] === 'string';
 }
+/**
+ * Base class for the custom UI events dispatched by the 2D stage/adapters, carrying the screen transform
+ * matrix in effect at dispatch time so consumers can project screen coordinates into stage coordinates.
+ */
 export class UI2DEvent extends CustomUIEvent {
     constructor(type, eventInit, originalEvent, transformMatrix) {
         super(type, eventInit, originalEvent);
@@ -69,22 +90,28 @@ export class UI2DEvent 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);
     }
 }
+/** Static helper to build an empty `ShapeGeometry`. */
 export class Shape {
+    /** 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 } };
     }
 }
+/** Event dispatched throughout a `Drawable`'s drag lifecycle, carrying `DragEventArgs`. */
 export class DragEvent extends UI2DEvent {
 }
+/** Event dispatched for pointer interactions (over/out/down/up/click) targeting a `Drawable`. */
 export class DrawableEvent extends UI2DEvent {
     constructor(type, args, originalEvent, m) {
         super(type, { detail: args, bubbles: true, cancelable: true }, originalEvent, m);
     }
 }
+/** Event dispatched for pointer interactions (move/down/up/click) targeting a `Stage` at large (i.e. no specific hit `Drawable`). */
 export class StageEvent extends UI2DEvent {
     constructor(type, args, originalEvent, m = args.transformMatrix) {
         super(type, { detail: args, bubbles: true, cancelable: true }, originalEvent, m);

package/dist/esm/ellipse.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
  */
@@ -65,6 +65,7 @@ function getShapeGeometry(c, rx, ry, start, end) {
     const threesixty = (start - end).isCloseTo(0);
     return threesixty ? full(c, rx, ry) : sect(c, rx, ry, start, end);
 }
+/** `<pacem-2d-ellipse>`: renders a full ellipse, or a pie-slice sector when `start`/`end` are set. */
 let PacemEllipseElement = PacemEllipseElement_1 = class PacemEllipseElement extends ShapeElement {
     propertyChangedCallback(name, old, val, first) {
         super.propertyChangedCallback(name, old, val, first);
@@ -80,6 +81,7 @@ let PacemEllipseElement = PacemEllipseElement_1 = class PacemEllipseElement exte
             }
         }
     }
+    /** 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 (!Utils.isNull(c) && !Utils.isNull(a) && !Utils.isNull(b)) {
@@ -92,6 +94,14 @@ let PacemEllipseElement = PacemEllipseElement_1 = class PacemEllipseElement exte
         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;
@@ -116,6 +126,7 @@ PacemEllipseElement = PacemEllipseElement_1 = __decorate([
     CustomElement({ tagName: P + '-' + TAG_MIDDLE_NAME + '-ellipse' })
 ], PacemEllipseElement);
 export { PacemEllipseElement };
+/** `<pacem-2d-circle>`: renders a full circle, or a pie-slice sector when `start`/`end` are set. */
 let PacemCircleElement = PacemCircleElement_1 = class PacemCircleElement extends ShapeElement {
     propertyChangedCallback(name, old, val, first) {
         super.propertyChangedCallback(name, old, val, first);
@@ -130,6 +141,7 @@ let PacemCircleElement = PacemCircleElement_1 = class PacemCircleElement extends
             }
         }
     }
+    /** 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 (!Utils.isNull(c) && !Utils.isNull(r)) {
@@ -142,6 +154,13 @@ let PacemCircleElement = PacemCircleElement_1 = class PacemCircleElement extends
         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);
     }

package/dist/esm/group.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
  */
@@ -14,11 +14,13 @@ import { PresentationElement } from './types';
 import { TAG_MIDDLE_NAME } from './constants';
 import { DrawableElement } from './drawable-element';
 //namespace Pacem.Components.Drawing {
+/** `<pacem-2d-group>`: a container that groups child drawables, applying its own transform/presentation state to all of them. */
 let PacemGroupElement = class PacemGroupElement extends PresentationElement {
     validate(item) {
         return item instanceof DrawableElement && item.parent === this;
     }
     #children = [];
+    /** @readonly Gets the child drawables currently in the group. */
     get childDrawables() {
         return this.#children;
     }

package/dist/esm/image.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
  */
@@ -13,6 +13,7 @@ import { CustomElement, Watch, PropertyConverters, P } from '@pacem/pacem-core';
 import { UiElement } from './types';
 import { TAG_MIDDLE_NAME } from './constants';
 //namespace Pacem.Components.Drawing {
+/** `<pacem-2d-image>`: renders a raster image at a given position and size within the stage. */
 let PacemImageElement = class PacemImageElement extends UiElement {
     propertyChangedCallback(name, old, val, first) {
         super.propertyChangedCallback(name, old, val, first);

package/dist/esm/index-components-drawing.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/esm/index-components.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/esm/index-iife.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/esm/index-root.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/esm/index.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/esm/line.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
  */
@@ -15,6 +15,7 @@ import { ShapeElement } from './types';
 import { TAG_MIDDLE_NAME } from './constants';
 import { Shape } from './drawing';
 //namespace Pacem.Components.Drawing {
+/** `<pacem-2d-line>`: renders a straight segment between two points. */
 let PacemLineElement = PacemLineElement_1 = class PacemLineElement extends ShapeElement {
     propertyChangedCallback(name, old, val, first) {
         super.propertyChangedCallback(name, old, val, first);
@@ -36,6 +37,7 @@ let PacemLineElement = PacemLineElement_1 = class PacemLineElement extends Shape
         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 (!Utils.isNull(from) && !Utils.isNull(to)) {
@@ -43,6 +45,7 @@ let PacemLineElement = PacemLineElement_1 = class PacemLineElement extends Shape
         }
         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}`;

package/dist/esm/path.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
  */
@@ -13,9 +13,11 @@ import { CustomElement, Watch, PropertyConverters, P } from '@pacem/pacem-core';
 import { ShapeElement } from './types';
 import { TAG_MIDDLE_NAME } from './constants';
 //namespace Pacem.Components.Drawing {
+/** `<pacem-2d-path>`: renders an arbitrary SVG path, provided verbatim through the `d` property. */
 let PacemPathElement = class PacemPathElement extends ShapeElement {
     constructor() {
         super(...arguments);
+        /** Returns the raw path data, i.e. `d`. */
         this.getPathData = () => this.d;
     }
     propertyChangedCallback(name, old, val, first) {

package/dist/esm/polygon.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
  */
@@ -15,6 +15,7 @@ import { ShapeElement } from './types';
 import { TAG_MIDDLE_NAME } from './constants';
 import { Shape } from './drawing';
 //namespace Pacem.Components.Drawing {
+/** `<pacem-2d-polygon>`: renders a regular polygon (or, with `starIndent` set, a star) centered on `center`. */
 let PacemPolygonElement = PacemPolygonElement_1 = class PacemPolygonElement extends ShapeElement {
     propertyChangedCallback(name, old, val, first) {
         super.propertyChangedCallback(name, old, val, first);
@@ -28,6 +29,7 @@ let PacemPolygonElement = PacemPolygonElement_1 = class PacemPolygonElement exte
             }
         }
     }
+    /** 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 (!Utils.isNull(sides) && !Utils.isNull(radius)) {
@@ -42,6 +44,13 @@ let PacemPolygonElement = PacemPolygonElement_1 = class PacemPolygonElement exte
         }
         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)}`;
@@ -72,6 +81,7 @@ let PacemPolygonElement = PacemPolygonElement_1 = class PacemPolygonElement exte
             pathData: retval + ' Z', vertices, 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;

package/dist/esm/polyline.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
  */
@@ -16,6 +16,7 @@ import { ShapeElement } from './types';
 import { TAG_MIDDLE_NAME } from './constants';
 import { Shape } from './drawing';
 //namespace Pacem.Components.Drawing {
+/** Converts the `points` attribute either from a flat `x1,y1,x2,y2,...` numeric list or from JSON. */
 const PointArrayOrJsonConverter = {
     convert: (attr) => {
         const arr = parseAsNumericalArray(attr);
@@ -30,6 +31,7 @@ const PointArrayOrJsonConverter = {
     },
     convertBack: (prop) => JSON.stringify(prop)
 };
+/** `<pacem-2d-polyline>`: renders a series of connected segments through `points`, optionally `closed` into a polygon. */
 let PacemPolylineElement = PacemPolylineElement_1 = class PacemPolylineElement extends ShapeElement {
     propertyChangedCallback(name, old, val, first) {
         super.propertyChangedCallback(name, old, val, first);
@@ -42,6 +44,11 @@ let PacemPolylineElement = PacemPolylineElement_1 = class PacemPolylineElement e
             }
         }
     }
+    /**
+     * 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 (Utils.isNullOrEmpty(points)) {
             return Shape.empty();
@@ -65,10 +72,12 @@ let PacemPolylineElement = PacemPolylineElement_1 = class PacemPolylineElement e
     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;

package/dist/esm/rect.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
  */
@@ -62,11 +62,13 @@ function stringifyCornerRadii(radii) {
     const blX = stringifyCornerRadiusComponent(bottomLeft.rx), blY = stringifyCornerRadiusComponent(bottomLeft.ry);
     return `${tlX},${tlY} ${trX},${trY} ${brX},${brY} ${blX},${blY}`;
 }
+/** How a `PacemRectElement` corner is rendered: smoothly `Rounded` or straight-line `Cut` (chamfered). */
 export var CornerType;
 (function (CornerType) {
     CornerType["Rounded"] = "rounded";
     CornerType["Cut"] = "cut";
 })(CornerType || (CornerType = {}));
+/** `<pacem-2d-rect>`: renders a rectangle, optionally with independently rounded or cut corners. */
 let PacemRectElement = PacemRectElement_1 = class PacemRectElement extends ShapeElement {
     propertyChangedCallback(name, old, val, first) {
         super.propertyChangedCallback(name, old, val, first);
@@ -74,6 +76,7 @@ let PacemRectElement = PacemRectElement_1 = class PacemRectElement extends Shape
             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 };

package/dist/esm/stage-abstractions.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/esm/stage.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
  */
@@ -43,10 +43,20 @@ const DEFAULT_STAGE_OPTIONS = {
     zoomModifiers: [EventKeyModifier.AltKey],
     clickModifiers: []
 };
+/**
+ * Returns the effective `StageOptions` for the given stage, filling in any option left unset with the
+ * library defaults.
+ * @param stage The stage to resolve options for.
+ */
 export function getStageOptions(stage) {
     const options = stage instanceof Pacem2DElement ? stage.options : {};
     return Utils.extend({}, DEFAULT_STAGE_OPTIONS, options);
 }
+/**
+ * The `<pacem-2d>` element: root stage/scene container for the drawable elements (shapes, text, images,
+ * groups...). Delegates actual rendering to the assigned `adapter` (SVG or Canvas) and handles the
+ * viewbox/aspect-ratio mapping plus built-in pan and zoom interactions.
+ */
 let Pacem2DElement = class Pacem2DElement extends Components.PacemItemsContainerElement {
     constructor() {
         super(...arguments);
@@ -111,9 +121,11 @@ let Pacem2DElement = class Pacem2DElement extends Components.PacemItemsContainer
             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 (Utils.isNull(adapter)) {
@@ -123,6 +135,7 @@ let Pacem2DElement = class Pacem2DElement extends Components.PacemItemsContainer
     }
     #originalViewBox;
     #transformMatrix;
+    /** @readonly Gets the matrix that projects stage coords into screen coords. */
     get transformMatrix() {
         return this.#transformMatrix;
     }

package/dist/esm/text.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
  */
@@ -13,6 +13,7 @@ import { CustomElement, Watch, PropertyConverters, P, Utils } from '@pacem/pacem
 import { UiElement } from './types';
 import { TAG_MIDDLE_NAME } from './constants';
 //namespace Pacem.Components.Drawing {
+/** `<pacem-2d-text>`: renders a text label anchored at a given point. */
 let PacemTextElement = class PacemTextElement extends UiElement {
     propertyChangedCallback(name, old, val, first) {
         if (!first) {

package/dist/esm/types.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
  */
@@ -14,6 +14,10 @@ import { Matrix2D } from '@pacem/pacem-foundation';
 import { DrawableElement } from './drawable-element';
 //namespace Pacem.Components.Drawing {
 const DEG2RAD = Math.PI / 180.0;
+/**
+ * Base class for every drawable that participates in the 2D transform pipeline (rotation, scale,
+ * translation) and exposes an `opacity`. Computes and caches the corresponding `transformMatrix`.
+ */
 export class UiElement extends DrawableElement {
     #transformMatrix = Matrix2D.identity;
     viewActivatedCallback() {
@@ -65,6 +69,10 @@ __decorate([
 __decorate([
     Watch({ emit: false, converter: PropertyConverters.Number })
 ], UiElement.prototype, "opacity", void 0);
+/**
+ * Base class for drawables that carry stroke/fill presentation state (color, line width, dash pattern,
+ * line join/cap), on top of the transform/opacity inherited from `UiElement`.
+ */
 export class PresentationElement extends UiElement {
     propertyChangedCallback(name, old, val, first) {
         super.propertyChangedCallback(name, old, val, first);
@@ -107,6 +115,11 @@ __decorate([
 __decorate([
     Watch({ emit: false, converter: PropertyConverters.String })
 ], PresentationElement.prototype, "lineCap", void 0);
+/**
+ * Base class for drawables whose visual is an SVG path (`pathData`) computed out of their own geometry
+ * properties (e.g. center/radius, points, corners). Subclasses implement `getShapeGeometry` and this
+ * class takes care of recomputing `data`/`vertices`/`boundingRect` and requesting a redraw.
+ */
 export class ShapeElement extends PresentationElement {
     propertyChangedCallback(name, old, val, first) {
         super.propertyChangedCallback(name, old, val, first);
@@ -122,20 +135,24 @@ export class ShapeElement 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;
     }

package/package.json

@@ -4,6 +4,7 @@
     "dist/browser/*.*",
     "dist/bundle/*.*",
     "dist/esm/*.*",
+    "dist/docs/*.*",
     "typings/*.*",
     "README.md",
     "LICENSE",
@@ -24,7 +25,7 @@
       "types": "./typings/index.d.ts"
     }
   },
-  "version": "1.0.0-bessel",
+  "version": "1.0.0-dirac",
   "author": {
     "name": "Pacem",
     "url": "https://pacem.it"