js-draw 1.21.3 → 1.23.1

package/dist/mjs/components/builders/FreehandLineBuilder.mjs

@@ -3,6 +3,12 @@ import  Stroke  from '../Stroke.mjs';
 import  Viewport  from '../../Viewport.mjs';
 import  { StrokeSmoother }  from '../util/StrokeSmoother.mjs';
 import  makeShapeFitAutocorrect  from './autocorrect/makeShapeFitAutocorrect.mjs';
+/**
+ * Creates a stroke builder that draws freehand lines.
+ *
+ * Example:
+ * [[include:doc-pages/inline-examples/changing-pen-types.md]]
+ */
 export const makeFreehandLineBuilder = makeShapeFitAutocorrect((initialPoint, viewport) => {
     // Don't smooth if input is more than ± 3 pixels from the true curve, do smooth if
     // less than ±1 px from the curve.
@@ -32,7 +38,7 @@ export default class FreehandLineBuilder {
             stroke: {
                 color: this.startPoint.color,
                 width: this.roundDistance(this.averageWidth),
-            }
+            },
         };
     }
     previewCurrentPath() {
@@ -129,7 +135,7 @@ export default class FreehandLineBuilder {
                     kind: PathCommandType.QuadraticBezierTo,
                     controlPoint: center.plus(Vec2.of(width, -width)),
                     endPoint: center.plus(Vec2.of(width, 0)),
-                }
+                },
             ];
         }
         const result = [];
@@ -157,7 +163,7 @@ export default class FreehandLineBuilder {
         this.curveFitter.addPoint(newPoint);
         this.widthAverageNumSamples++;
         this.averageWidth =
-            this.averageWidth * (this.widthAverageNumSamples - 1) / this.widthAverageNumSamples
-                + newPoint.width / this.widthAverageNumSamples;
+            (this.averageWidth * (this.widthAverageNumSamples - 1)) / this.widthAverageNumSamples +
+                newPoint.width / this.widthAverageNumSamples;
     }
 }

package/dist/mjs/components/builders/LineBuilder.d.ts

@@ -4,6 +4,12 @@ import { StrokeDataPoint } from '../../types';
 import Viewport from '../../Viewport';
 import AbstractComponent from '../AbstractComponent';
 import { ComponentBuilder, ComponentBuilderFactory } from './types';
+/**
+ * Creates a stroke builder that generates filled lines.
+ *
+ * Example:
+ * [[include:doc-pages/inline-examples/changing-pen-types.md]]
+ */
 export declare const makeLineBuilder: ComponentBuilderFactory;
 export default class LineBuilder implements ComponentBuilder {
     private readonly startPoint;

package/dist/mjs/components/builders/LineBuilder.mjs

@@ -2,6 +2,12 @@ import { Path, PathCommandType } from '@js-draw/math';
 import  { pathToRenderable }  from '../../rendering/RenderablePathSpec.mjs';
 import  Stroke  from '../Stroke.mjs';
 import  makeSnapToGridAutocorrect  from './autocorrect/makeSnapToGridAutocorrect.mjs';
+/**
+ * Creates a stroke builder that generates filled lines.
+ *
+ * Example:
+ * [[include:doc-pages/inline-examples/changing-pen-types.md]]
+ */
 export const makeLineBuilder = makeSnapToGridAutocorrect((initialPoint, viewport) => {
     return new LineBuilder(initialPoint, viewport);
 });
@@ -42,10 +48,8 @@ export default class LineBuilder {
                 kind: PathCommandType.LineTo,
                 point: startPoint.minus(scaledStartNormal),
             },
-        ]).mapPoints(point => this.viewport.roundPoint(point));
-        const preview = new Stroke([
-            pathToRenderable(path, { fill: this.startPoint.color })
-        ]);
+        ]).mapPoints((point) => this.viewport.roundPoint(point));
+        const preview = new Stroke([pathToRenderable(path, { fill: this.startPoint.color })]);
         return preview;
     }
     build() {

package/dist/mjs/components/builders/PolylineBuilder.d.ts

@@ -7,8 +7,11 @@ import { StrokeDataPoint } from '../../types';
 import { ComponentBuilder, ComponentBuilderFactory } from './types';
 import RenderingStyle from '../../rendering/RenderingStyle';
 /**
- * Creates strokes from line segments rather than Bézier curves.
+ * Creates a freehand line builder that creates strokes from line segments
+ * rather than Bézier curves.
  *
+ * Example:
+ * [[include:doc-pages/inline-examples/changing-pen-types.md]]
  */
 export declare const makePolylineBuilder: ComponentBuilderFactory;
 export default class PolylineBuilder implements ComponentBuilder {

package/dist/mjs/components/builders/PolylineBuilder.mjs

@@ -1,10 +1,13 @@
-import { Rect2, Color4, PathCommandType, Vec2, LineSegment2 } from '@js-draw/math';
+import { Rect2, Color4, PathCommandType, Vec2, LineSegment2, } from '@js-draw/math';
 import  Stroke  from '../Stroke.mjs';
 import  Viewport  from '../../Viewport.mjs';
 import  makeShapeFitAutocorrect  from './autocorrect/makeShapeFitAutocorrect.mjs';
 /**
- * Creates strokes from line segments rather than Bézier curves.
+ * Creates a freehand line builder that creates strokes from line segments
+ * rather than Bézier curves.
  *
+ * Example:
+ * [[include:doc-pages/inline-examples/changing-pen-types.md]]
  */
 export const makePolylineBuilder = makeShapeFitAutocorrect((initialPoint, viewport) => {
     // Fit to a value slightly smaller than the pixel size. A larger value can
@@ -42,7 +45,7 @@ export default class PolylineBuilder {
             stroke: {
                 color: this.startPoint.color,
                 width: this.roundDistance(this.averageWidth),
-            }
+            },
         };
     }
     previewCurrentPath() {
@@ -96,12 +99,13 @@ export default class PolylineBuilder {
     addPoint(newPoint) {
         this.widthAverageNumSamples++;
         this.averageWidth =
-            this.averageWidth * (this.widthAverageNumSamples - 1) / this.widthAverageNumSamples
-                + newPoint.width / this.widthAverageNumSamples;
+            (this.averageWidth * (this.widthAverageNumSamples - 1)) / this.widthAverageNumSamples +
+                newPoint.width / this.widthAverageNumSamples;
         const roundedPoint = this.roundPoint(newPoint.pos);
         if (!roundedPoint.eq(this.lastPoint)) {
             // If almost exactly in the same line as the previous
-            if (this.lastLineSegment && this.lastLineSegment.direction.dot(roundedPoint.minus(this.lastPoint).normalized()) > 0.997) {
+            if (this.lastLineSegment &&
+                this.lastLineSegment.direction.dot(roundedPoint.minus(this.lastPoint).normalized()) > 0.997) {
                 this.parts.pop();
                 this.lastPoint = this.lastLineSegment.p1;
             }

package/dist/mjs/components/builders/PressureSensitiveFreehandLineBuilder.mjs

@@ -1,4 +1,4 @@
-import { Vec2, Rect2, PathCommandType, QuadraticBezier } from '@js-draw/math';
+import { Vec2, Rect2, PathCommandType, QuadraticBezier, } from '@js-draw/math';
 import  Stroke  from '../Stroke.mjs';
 import  Viewport  from '../../Viewport.mjs';
 import  { StrokeSmoother }  from '../util/StrokeSmoother.mjs';
@@ -30,7 +30,7 @@ export default class PressureSensitiveFreehandLineBuilder {
         this.parts = [];
         this.upperSegments = [];
         this.lowerSegments = [];
-        this.curveFitter = new StrokeSmoother(startPoint, minFitAllowed, maxFitAllowed, curve => this.addCurve(curve));
+        this.curveFitter = new StrokeSmoother(startPoint, minFitAllowed, maxFitAllowed, (curve) => this.addCurve(curve));
         this.curveStartWidth = startPoint.width;
         this.bbox = new Rect2(this.startPoint.pos.x, this.startPoint.pos.y, 0, 0);
     }
@@ -64,7 +64,8 @@ export default class PressureSensitiveFreehandLineBuilder {
         }
         let startPoint;
         const lastLowerSegment = lowerPath[lowerPath.length - 1];
-        if (lastLowerSegment.kind === PathCommandType.LineTo || lastLowerSegment.kind === PathCommandType.MoveTo) {
+        if (lastLowerSegment.kind === PathCommandType.LineTo ||
+            lastLowerSegment.kind === PathCommandType.MoveTo) {
             startPoint = lastLowerSegment.point;
         }
         else {
@@ -163,11 +164,11 @@ export default class PressureSensitiveFreehandLineBuilder {
         // where the next stroke and the previous stroke are in different directions.
         //
         // Are the exit/enter directions of the previous and current curves in different enough directions?
-        if (getEnterDirection(upperCurve).dot(getExitDirection(this.lastUpperBezier)) < 0.35
-            || getEnterDirection(lowerCurve).dot(getExitDirection(this.lastLowerBezier)) < 0.35
+        if (getEnterDirection(upperCurve).dot(getExitDirection(this.lastUpperBezier)) < 0.35 ||
+            getEnterDirection(lowerCurve).dot(getExitDirection(this.lastLowerBezier)) < 0.35 ||
             // Also handle if the curves exit/enter directions differ
-            || getEnterDirection(upperCurve).dot(getExitDirection(upperCurve)) < 0
-            || getEnterDirection(lowerCurve).dot(getExitDirection(lowerCurve)) < 0) {
+            getEnterDirection(upperCurve).dot(getExitDirection(upperCurve)) < 0 ||
+            getEnterDirection(lowerCurve).dot(getExitDirection(lowerCurve)) < 0) {
             return true;
         }
         // Check whether the lower curve intersects the other wall:
@@ -274,8 +275,9 @@ export default class PressureSensitiveFreehandLineBuilder {
         // Approximate the normal at the location of the control point
         const projectionT = bezier.nearestPointTo(controlPoint).parameterValue;
         const halfVecT = projectionT;
-        const halfVec = bezier.normal(halfVecT).times(curve.startWidth / 2 * halfVecT
-            + curve.endWidth / 2 * (1 - halfVecT));
+        const halfVec = bezier
+            .normal(halfVecT)
+            .times((curve.startWidth / 2) * halfVecT + (curve.endWidth / 2) * (1 - halfVecT));
         // Each starts at startPt ± startVec
         const lowerCurveStartPoint = this.roundPoint(startPt.plus(startVec));
         const lowerCurveControlPoint = this.roundPoint(controlPoint.plus(halfVec));
@@ -318,8 +320,12 @@ export default class PressureSensitiveFreehandLineBuilder {
         const upperCurve = new QuadraticBezier(upperCurveStartPoint, upperCurveControlPoint, upperCurveEndPoint);
         const lowerCurve = new QuadraticBezier(lowerCurveStartPoint, lowerCurveControlPoint, lowerCurveEndPoint);
         return {
-            upperCurveCommand, upperToLowerConnector, lowerToUpperConnector, lowerCurveCommand,
-            upperCurve, lowerCurve,
+            upperCurveCommand,
+            upperToLowerConnector,
+            lowerToUpperConnector,
+            lowerCurveCommand,
+            upperCurve,
+            lowerCurve,
             nextCurveStartConnector,
         };
     }

package/dist/mjs/components/builders/RectangleBuilder.d.ts

@@ -4,7 +4,19 @@ import { StrokeDataPoint } from '../../types';
 import Viewport from '../../Viewport';
 import AbstractComponent from '../AbstractComponent';
 import { ComponentBuilder, ComponentBuilderFactory } from './types';
+/**
+ * Creates filled rectangles with sharp corners.
+ *
+ * Example:
+ * [[include:doc-pages/inline-examples/changing-pen-types.md]]
+ */
 export declare const makeFilledRectangleBuilder: ComponentBuilderFactory;
+/**
+ * Creates outlined rectangles with sharp corners.
+ *
+ * Example:
+ * [[include:doc-pages/inline-examples/changing-pen-types.md]]
+ */
 export declare const makeOutlinedRectangleBuilder: ComponentBuilderFactory;
 export default class RectangleBuilder implements ComponentBuilder {
     private readonly startPoint;

package/dist/mjs/components/builders/RectangleBuilder.mjs

@@ -2,9 +2,21 @@ import { Mat33, Rect2, Path } from '@js-draw/math';
 import  { pathToRenderable }  from '../../rendering/RenderablePathSpec.mjs';
 import  Stroke  from '../Stroke.mjs';
 import  makeSnapToGridAutocorrect  from './autocorrect/makeSnapToGridAutocorrect.mjs';
+/**
+ * Creates filled rectangles with sharp corners.
+ *
+ * Example:
+ * [[include:doc-pages/inline-examples/changing-pen-types.md]]
+ */
 export const makeFilledRectangleBuilder = makeSnapToGridAutocorrect((initialPoint, viewport) => {
     return new RectangleBuilder(initialPoint, true, viewport);
 });
+/**
+ * Creates outlined rectangles with sharp corners.
+ *
+ * Example:
+ * [[include:doc-pages/inline-examples/changing-pen-types.md]]
+ */
 export const makeOutlinedRectangleBuilder = makeSnapToGridAutocorrect((initialPoint, viewport) => {
     return new RectangleBuilder(initialPoint, false, viewport);
 });
@@ -28,12 +40,14 @@ export default class RectangleBuilder {
         const startPoint = rotationMat.inverse().transformVec2(this.startPoint.pos);
         const endPoint = rotationMat.inverse().transformVec2(this.endPoint.pos);
         const rect = Rect2.fromCorners(startPoint, endPoint);
-        const path = Path.fromRect(rect, this.filled ? null : this.endPoint.width).transformedBy(
+        const path = Path.fromRect(rect, this.filled ? null : this.endPoint.width)
+            .transformedBy(
         // Rotate the canvas rectangle so that its rotation matches the screen
-        rotationMat).mapPoints(point => this.viewport.roundPoint(point));
+        rotationMat)
+            .mapPoints((point) => this.viewport.roundPoint(point));
         const preview = new Stroke([
             pathToRenderable(path, {
-                fill: this.endPoint.color
+                fill: this.endPoint.color,
             }),
         ]);
         return preview;

package/dist/mjs/components/builders/autocorrect/makeShapeFitAutocorrect.mjs

@@ -6,14 +6,11 @@ const makeShapeFitAutocorrect = (sourceFactory) => {
 };
 export default makeShapeFitAutocorrect;
 const makeLineTemplate = (startPoint, points, _bbox) => {
-    const templatePoints = [
-        startPoint,
-        points[points.length - 1],
-    ];
-    return { points: templatePoints, };
+    const templatePoints = [startPoint, points[points.length - 1]];
+    return { points: templatePoints };
 };
 const makeRectangleTemplate = (_startPoint, _points, bbox) => {
-    return { points: [...bbox.corners, bbox.corners[0]], };
+    return { points: [...bbox.corners, bbox.corners[0]] };
 };
 class ShapeFitBuilder {
     constructor(sourceFactory, startPoint, viewport) {
@@ -39,10 +36,10 @@ class ShapeFitBuilder {
     async autocorrectShape() {
         // Use screen points so that autocorrected shapes rotate with the screen.
         const startPoint = this.viewport.canvasToScreen(this.startPoint.pos);
-        const points = this.points.map(point => this.viewport.canvasToScreen(point.pos));
+        const points = this.points.map((point) => this.viewport.canvasToScreen(point.pos));
         const bbox = Rect2.bboxOf(points);
         const snappedStartPoint = this.viewport.canvasToScreen(this.viewport.snapToGrid(this.startPoint.pos));
-        const snappedPoints = this.points.map(point => this.viewport.canvasToScreen(this.viewport.snapToGrid(point.pos)));
+        const snappedPoints = this.points.map((point) => this.viewport.canvasToScreen(this.viewport.snapToGrid(point.pos)));
         const snappedBBox = Rect2.bboxOf(snappedPoints);
         // Only fit larger shapes
         if (bbox.maxDimension < 32) {

package/dist/mjs/components/builders/autocorrect/makeSnapToGridAutocorrect.mjs

@@ -35,7 +35,7 @@ class SnapToGridAutocompleteBuilder {
         // Use screen points so that snapped shapes rotate with the screen.
         const startPoint = snapToGrid(this.startPoint);
         const builder = this.sourceFactory(startPoint, this.viewport);
-        const points = this.points.map(point => snapToGrid(point));
+        const points = this.points.map((point) => snapToGrid(point));
         for (const point of points) {
             builder.addPoint(point);
         }

package/dist/mjs/components/builders/lib.d.ts

@@ -0,0 +1,7 @@
+export { makeFreehandLineBuilder } from './FreehandLineBuilder';
+export { makePolylineBuilder } from './PolylineBuilder';
+export { makePressureSensitiveFreehandLineBuilder } from './PressureSensitiveFreehandLineBuilder';
+export { makeOutlinedCircleBuilder } from './CircleBuilder';
+export { makeArrowBuilder } from './ArrowBuilder';
+export { makeLineBuilder } from './LineBuilder';
+export { makeFilledRectangleBuilder, makeOutlinedRectangleBuilder } from './RectangleBuilder';

package/dist/mjs/components/builders/lib.mjs

@@ -0,0 +1,7 @@
+export  { makeFreehandLineBuilder }  from './FreehandLineBuilder.mjs';
+export  { makePolylineBuilder }  from './PolylineBuilder.mjs';
+export  { makePressureSensitiveFreehandLineBuilder }  from './PressureSensitiveFreehandLineBuilder.mjs';
+export  { makeOutlinedCircleBuilder }  from './CircleBuilder.mjs';
+export  { makeArrowBuilder }  from './ArrowBuilder.mjs';
+export  { makeLineBuilder }  from './LineBuilder.mjs';
+export  { makeFilledRectangleBuilder, makeOutlinedRectangleBuilder }  from './RectangleBuilder.mjs';

package/dist/mjs/components/lib.d.ts

@@ -1,8 +1,5 @@
 export * from './builders/types';
-export { makeFreehandLineBuilder } from './builders/FreehandLineBuilder';
-export { makePolylineBuilder } from './builders/PolylineBuilder';
-export { makePressureSensitiveFreehandLineBuilder } from './builders/PressureSensitiveFreehandLineBuilder';
-export { makeOutlinedCircleBuilder } from './builders/CircleBuilder';
+export * from './builders/lib';
 export { default as StrokeSmoother, Curve as StrokeSmootherCurve } from './util/StrokeSmoother';
 export * from './AbstractComponent';
 export { default as AbstractComponent } from './AbstractComponent';

package/dist/mjs/components/lib.mjs

@@ -1,15 +1,12 @@
 export  *  from './builders/types.mjs';
-export  { makeFreehandLineBuilder }  from './builders/FreehandLineBuilder.mjs';
-export  { makePolylineBuilder }  from './builders/PolylineBuilder.mjs';
-export  { makePressureSensitiveFreehandLineBuilder }  from './builders/PressureSensitiveFreehandLineBuilder.mjs';
-export  { makeOutlinedCircleBuilder }  from './builders/CircleBuilder.mjs';
+export  *  from './builders/lib.mjs';
 export  { default as StrokeSmoother }  from './util/StrokeSmoother.mjs';
 export  *  from './AbstractComponent.mjs';
 export  { default as AbstractComponent }  from './AbstractComponent.mjs';
 import  Stroke  from './Stroke.mjs';
 import  TextComponent  from './TextComponent.mjs';
 import  ImageComponent  from './ImageComponent.mjs';
-import  { createRestyleComponentCommand, isRestylableComponent }  from './RestylableComponent.mjs';
+import  { createRestyleComponentCommand, isRestylableComponent, }  from './RestylableComponent.mjs';
 import  BackgroundComponent, { BackgroundType }  from './BackgroundComponent.mjs';
 export { Stroke, createRestyleComponentCommand, isRestylableComponent, TextComponent, 
 /** @deprecated use {@link TextComponent} */

package/dist/mjs/components/util/StrokeSmoother.mjs

@@ -53,9 +53,7 @@ export class StrokeSmoother {
         console.assert(this.lastExitingVec.magnitude() !== 0, 'lastExitingVec has zero length!');
         // Use the last two points to start a new curve (the last point isn't used
         // in the current curve and we want connected curves to share end points)
-        this.buffer = [
-            this.buffer[this.buffer.length - 2], lastPoint,
-        ];
+        this.buffer = [this.buffer[this.buffer.length - 2], lastPoint];
         this.currentCurve = null;
         this.isFirstSegment = false;
     }
@@ -96,8 +94,7 @@ export class StrokeSmoother {
                 return;
             }
             const threshold = Math.min(this.lastPoint.width, newPoint.width) / 3;
-            const shouldSnapToInitial = this.startPoint.pos.distanceTo(newPoint.pos) < threshold
-                && this.isFirstSegment;
+            const shouldSnapToInitial = this.startPoint.pos.distanceTo(newPoint.pos) < threshold && this.isFirstSegment;
             // Snap to the starting point if the stroke is contained within a small ball centered
             // at the starting point.
             // This allows us to create a circle/dot at the start of the stroke.
@@ -150,7 +147,9 @@ export class StrokeSmoother {
         const startEndDist = segmentEnd.distanceTo(segmentStart);
         const maxControlPointDist = maxRelativeLength * startEndDist;
         // Exit in cases where we would divide by zero
-        if (maxControlPointDist === 0 || exitingVec.magnitude() === 0 || !isFinite(exitingVec.magnitude())) {
+        if (maxControlPointDist === 0 ||
+            exitingVec.magnitude() === 0 ||
+            !isFinite(exitingVec.magnitude())) {
             return;
         }
         console.assert(isFinite(enteringVec.magnitude()), 'Pre-normalized enteringVec has NaN or ∞ magnitude!');

package/dist/mjs/dialogs/makeAboutDialog.mjs

@@ -8,7 +8,7 @@ const makeAboutDialog = (editor, entries) => {
         const container = document.createElement(entry.minimized ? 'details' : 'div');
         container.classList.add('about-entry');
         const header = document.createElement(entry.minimized ? 'summary' : 'h2');
-        if (typeof (entry.heading) === 'string') {
+        if (typeof entry.heading === 'string') {
             header.innerText = entry.heading;
         }
         else {

package/dist/mjs/dialogs/makeMessageDialog.mjs

@@ -15,7 +15,7 @@ const makeAboutDialog = (editor, options) => {
     const scrollRegion = document.createElement('div');
     scrollRegion.classList.add('scroll');
     // Allow scrolling in the scrollable container -- don't forward wheel events.
-    scrollRegion.onwheel = evt => evt.stopPropagation();
+    scrollRegion.onwheel = (evt) => evt.stopPropagation();
     contentWrapper.replaceChildren(heading, scrollRegion, closeButton);
     dialog.replaceChildren(contentWrapper);
     overlay.replaceChildren(dialog);
@@ -27,7 +27,7 @@ const makeAboutDialog = (editor, options) => {
         dialog.close();
     };
     const addCloseListeners = () => {
-        dialog.addEventListener('pointerdown', event => {
+        dialog.addEventListener('pointerdown', (event) => {
             if (event.target === dialog) {
                 void closeDialog();
             }

package/dist/mjs/image/EditorImage.d.ts

@@ -22,7 +22,20 @@ export type EditorImageNotifier = EventDispatcher<EditorImageEventType, {
  */
 export type PreRenderComponentCallback = (component: AbstractComponent, componentsProcessed: number, totalComponents: number) => Promise<boolean>;
 /**
- * Handles lookup/storage of elements in the image.
+ * @summary Handles lookup/storage of elements in the image.
+ *
+ * `js-draw` images are made up of a collection of {@link AbstractComponent}s (which
+ * includes {@link Stroke}s, {@link TextComponent}s, etc.). An `EditorImage`
+ * is the data structure that stores these components.
+ *
+ * Here's how to do a few common operations:
+ * - **Get all components in a {@link @js-draw/math!Rect2 | Rect2}**:
+ *    {@link EditorImage.getElementsIntersectingRegion}.
+ * - **Draw an `EditorImage` onto a canvas/SVG**: {@link EditorImage.render}.
+ * - **Adding a new component**: {@link EditorImage.addElement}.
+ *
+ * **Example**:
+ * [[include:doc-pages/inline-examples/image-add-and-lookup.md]]
  */
 export default class EditorImage {
     private root;
@@ -40,10 +53,13 @@ export default class EditorImage {
     /** @internal */
     renderWithCache(screenRenderer: AbstractRenderer, cache: RenderingCache, viewport: Viewport): void;
     /**
-     * Renders all nodes visible from `viewport` (or all nodes if `viewport = null`).
+     * Renders this image to the given `renderer`.
      *
-     * `viewport` is used to improve rendering performance. If given, it must match
-     * the viewport used by the `renderer` (if any).
+     * If `viewport` is non-null, only components that can be seen from that viewport
+     * will be rendered. If `viewport` is `null`, **all** components are rendered.
+     *
+     * **Example**:
+     * [[include:doc-pages/inline-examples/canvas-renderer.md]]
      */
     render(renderer: AbstractRenderer, viewport: Viewport | null): void;
     /**
@@ -63,14 +79,21 @@ export default class EditorImage {
      */
     renderAll(renderer: AbstractRenderer): void;
     /**
-     * @returns all elements in the image, sorted by z-index. This can be slow for large images.
+     * @returns all elements in the image, sorted by z-index (low to high).
      *
-     * Does not include background elements. See {@link getBackgroundComponents}.
+     * This can be slow for large images. If you only need all elemenst in part of the image,
+     * consider using {@link getElementsIntersectingRegion} instead.
+     *
+     * **Note**: The result does not include background elements. See {@link getBackgroundComponents}.
      */
     getAllElements(): AbstractComponent[];
     /** Returns the number of elements added to this image. @internal */
     estimateNumElements(): number;
-    /** @returns a list of `AbstractComponent`s intersecting `region`, sorted by z-index. */
+    /**
+     * @returns a list of `AbstractComponent`s intersecting `region`, sorted by increasing z-index.
+     *
+     * Components in the background layer are only included if `includeBackground` is `true`.
+     */
     getElementsIntersectingRegion(region: Rect2, includeBackground?: boolean): AbstractComponent[];
     /** Called whenever (just after) an element is completely removed. @internal */
     onDestroyElement(elem: AbstractComponent): void;

package/dist/mjs/image/EditorImage.mjs

@@ -21,7 +21,20 @@ export var EditorImageEventType;
 })(EditorImageEventType || (EditorImageEventType = {}));
 let debugMode = false;
 /**
- * Handles lookup/storage of elements in the image.
+ * @summary Handles lookup/storage of elements in the image.
+ *
+ * `js-draw` images are made up of a collection of {@link AbstractComponent}s (which
+ * includes {@link Stroke}s, {@link TextComponent}s, etc.). An `EditorImage`
+ * is the data structure that stores these components.
+ *
+ * Here's how to do a few common operations:
+ * - **Get all components in a {@link @js-draw/math!Rect2 | Rect2}**:
+ *    {@link EditorImage.getElementsIntersectingRegion}.
+ * - **Draw an `EditorImage` onto a canvas/SVG**: {@link EditorImage.render}.
+ * - **Adding a new component**: {@link EditorImage.addElement}.
+ *
+ * **Example**:
+ * [[include:doc-pages/inline-examples/image-add-and-lookup.md]]
  */
 class EditorImage {
     // @internal
@@ -80,10 +93,13 @@ class EditorImage {
         }
     }
     /**
-     * Renders all nodes visible from `viewport` (or all nodes if `viewport = null`).
+     * Renders this image to the given `renderer`.
      *
-     * `viewport` is used to improve rendering performance. If given, it must match
-     * the viewport used by the `renderer` (if any).
+     * If `viewport` is non-null, only components that can be seen from that viewport
+     * will be rendered. If `viewport` is `null`, **all** components are rendered.
+     *
+     * **Example**:
+     * [[include:doc-pages/inline-examples/canvas-renderer.md]]
      */
     render(renderer, viewport) {
         this.background.render(renderer, viewport?.visibleRect);
@@ -114,27 +130,34 @@ class EditorImage {
         this.render(renderer, null);
     }
     /**
-     * @returns all elements in the image, sorted by z-index. This can be slow for large images.
+     * @returns all elements in the image, sorted by z-index (low to high).
      *
-     * Does not include background elements. See {@link getBackgroundComponents}.
+     * This can be slow for large images. If you only need all elemenst in part of the image,
+     * consider using {@link getElementsIntersectingRegion} instead.
+     *
+     * **Note**: The result does not include background elements. See {@link getBackgroundComponents}.
      */
     getAllElements() {
         const leaves = this.root.getLeaves();
         sortLeavesByZIndex(leaves);
-        return leaves.map(leaf => leaf.getContent());
+        return leaves.map((leaf) => leaf.getContent());
     }
     /** Returns the number of elements added to this image. @internal */
     estimateNumElements() {
         return this.componentCount;
     }
-    /** @returns a list of `AbstractComponent`s intersecting `region`, sorted by z-index. */
+    /**
+     * @returns a list of `AbstractComponent`s intersecting `region`, sorted by increasing z-index.
+     *
+     * Components in the background layer are only included if `includeBackground` is `true`.
+     */
     getElementsIntersectingRegion(region, includeBackground = false) {
         let leaves = this.root.getLeavesIntersectingRegion(region);
         if (includeBackground) {
             leaves = leaves.concat(this.background.getLeavesIntersectingRegion(region));
         }
         sortLeavesByZIndex(leaves);
-        return leaves.map(leaf => leaf.getContent());
+        return leaves.map((leaf) => leaf.getContent());
     }
     /** Called whenever (just after) an element is completely removed. @internal */
     onDestroyElement(elem) {
@@ -474,8 +497,8 @@ export const computeFirstIndexToRender = (sortedLeaves, visibleRect) => {
         for (let i = sortedLeaves.length - 1; i >= 1; i--) {
             if (
             // Check for occlusion
-            sortedLeaves[i].getBBox().containsRect(visibleRect)
-                && sortedLeaves[i].getContent()?.occludesEverythingBelowWhenRenderedInRect(visibleRect)) {
+            sortedLeaves[i].getBBox().containsRect(visibleRect) &&
+                sortedLeaves[i].getContent()?.occludesEverythingBelowWhenRenderedInRect(visibleRect)) {
                 startIndex = i;
                 break;
             }
@@ -510,7 +533,7 @@ export class ImageNode {
     }
     // Override this to change how children are considered within a given region.
     getChildrenIntersectingRegion(region, isTooSmallFilter) {
-        return this.children.filter(child => {
+        return this.children.filter((child) => {
             const bbox = child.getBBox();
             return !isTooSmallFilter?.(bbox) && bbox.intersects(region);
         });
@@ -601,7 +624,7 @@ export class ImageNode {
             }
             return nodeForNewLeaf.addLeaf(leaf);
         }
-        const containingNodes = this.children.filter(child => child.getBBox().containsRect(leafBBox));
+        const containingNodes = this.children.filter((child) => child.getBBox().containsRect(leafBBox));
         // Does the leaf already fit within one of the children?
         if (containingNodes.length > 0 && this.children.length >= this.targetChildCount) {
             // Sort the containers in ascending order by area
@@ -639,7 +662,7 @@ export class ImageNode {
             this.bbox = this.content.getBBox();
         }
         else {
-            this.bbox = Rect2.union(...this.children.map(child => child.getBBox()));
+            this.bbox = Rect2.union(...this.children.map((child) => child.getBBox()));
         }
         if (bubbleUp && !oldBBox.eq(this.bbox)) {
             if (this.bbox.containsRect(oldBBox)) {
@@ -674,7 +697,7 @@ export class ImageNode {
             const oldParent = this.parent;
             if (oldParent.parent !== null) {
                 const newParent = oldParent.parent;
-                newParent.children = newParent.children.filter(c => c !== oldParent);
+                newParent.children = newParent.children.filter((c) => c !== oldParent);
                 oldParent.parent = null;
                 oldParent.children = [];
                 this.parent = newParent;
@@ -746,11 +769,11 @@ export class ImageNode {
     removeChild(child) {
         this.checkRep();
         const oldChildCount = this.children.length;
-        this.children = this.children.filter(node => {
+        this.children = this.children.filter((node) => {
             return node !== child;
         });
         console.assert(this.children.length === oldChildCount - 1, `${oldChildCount - 1} ≠ ${this.children.length} after removing all nodes equal to ${child}. Nodes should only be removed once.`);
-        this.children.forEach(child => {
+        this.children.forEach((child) => {
             child.rebalance();
         });
         this.recomputeBBox(true);
@@ -799,7 +822,7 @@ export class ImageNode {
     render(renderer, visibleRect) {
         let leaves;
         if (visibleRect) {
-            leaves = this.getLeavesIntersectingRegion(visibleRect, rect => renderer.isTooSmallToRender(rect));
+            leaves = this.getLeavesIntersectingRegion(visibleRect, (rect) => renderer.isTooSmallToRender(rect));
         }
         else {
             leaves = this.getLeaves();
@@ -909,10 +932,8 @@ export class RootImageNode extends ImageNode {
         };
         // Check whether the child is stored in the data/fullscreen
         // component arrays first.
-        this.dataComponents = this.dataComponents
-            .filter(checkTargetChild);
-        this.fullscreenChildren = this.fullscreenChildren
-            .filter(checkTargetChild);
+        this.dataComponents = this.dataComponents.filter(checkTargetChild);
+        this.fullscreenChildren = this.fullscreenChildren.filter(checkTargetChild);
         if (!removed) {
             super.removeChild(child);
         }