js-draw 1.9.1 → 1.11.0

package/dist/cjs/components/ImageComponent.js

@@ -6,7 +6,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const math_1 = require("@js-draw/math");
 const assertions_1 = require("../util/assertions");
 const AbstractComponent_1 = __importDefault(require("./AbstractComponent"));
-// Represents a raster image.
+const waitForImageLoaded_1 = __importDefault(require("../util/waitForImageLoaded"));
+/**
+ * Represents a raster image.
+ *
+ * **Example: Adding images**:
+ * [[include:doc-pages/inline-examples/adding-an-image-and-data-urls.md]]
+ */
 class ImageComponent extends AbstractComponent_1.default {
     constructor(image) {
         super('image-component');
@@ -29,15 +35,14 @@ class ImageComponent extends AbstractComponent_1.default {
         this.contentBBox = this.getImageRect();
         this.contentBBox = this.contentBBox.transformedBoundingBox(this.image.transform);
     }
-    // Load from an image. Waits for the image to load if incomplete.
+    /**
+     * Load from an image. Waits for the image to load if incomplete.
+     *
+     * The image, `elem`, must not [taint](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image#security_and_tainted_canvases)
+     * an HTMLCanvasElement when rendered.
+     */
     static async fromImage(elem, transform) {
-        if (!elem.complete) {
-            await new Promise((resolve, reject) => {
-                elem.onload = resolve;
-                elem.onerror = reject;
-                elem.onabort = reject;
-            });
-        }
+        await (0, waitForImageLoaded_1.default)(elem);
         let width, height;
         if (typeof elem.width === 'number' && typeof elem.height === 'number'
             && elem.width !== 0 && elem.height !== 0) {
@@ -79,6 +84,7 @@ class ImageComponent extends AbstractComponent_1.default {
         canvas.drawImage(this.image);
         canvas.endObject(this.getLoadSaveData());
     }
+    // A *very* rough estimate of how long it takes to render this component
     getProportionalRenderingTime() {
         // Estimate: Equivalent to a stroke with 10 segments.
         return 10;
@@ -103,6 +109,7 @@ class ImageComponent extends AbstractComponent_1.default {
     getAltText() {
         return this.image.label;
     }
+    // The base64 image URL of this image.
     getURL() {
         return this.image.base64Url;
     }

package/dist/cjs/components/Stroke.d.ts

@@ -5,7 +5,7 @@ import AbstractRenderer from '../rendering/renderers/AbstractRenderer';
 import AbstractComponent from './AbstractComponent';
 import { ImageComponentLocalization } from './localization';
 import RestyleableComponent, { ComponentStyle } from './RestylableComponent';
-import RenderablePathSpec from '../rendering/RenderablePathSpec';
+import RenderablePathSpec, { RenderablePathSpecWithPath } from '../rendering/RenderablePathSpec';
 /**
  * Represents an {@link AbstractComponent} made up of one or more {@link Path}s.
  *
@@ -21,6 +21,9 @@ import RenderablePathSpec from '../rendering/RenderablePathSpec';
  * ```ts
  * editor.dispatch(stroke.transformBy(Mat33.translation(Vec2.of(10, 0))));
  * ```
+ *
+ * **Adding**:
+ * [[include:doc-pages/inline-examples/adding-a-stroke.md]]
  */
 export default class Stroke extends AbstractComponent implements RestyleableComponent {
     private parts;
@@ -39,7 +42,7 @@ export default class Stroke extends AbstractComponent implements RestyleableComp
      *
      * const stroke = new Stroke([
      *     // Fill with red
-     *     pathToRenderable({ fill: Color4.red })
+     *     pathToRenderable(path, { fill: Color4.red })
      * ]);
      * ```
      */
@@ -57,6 +60,17 @@ export default class Stroke extends AbstractComponent implements RestyleableComp
     private bboxForPart;
     getExactBBox(): Rect2;
     protected applyTransformation(affineTransfm: Mat33): void;
+    /**
+     * @returns A list of the parts that make up this path. Many paths only have one part.
+     *
+     * Each part (a {@link RenderablePathSpec}) contains information about the style and geometry
+     * of that part of the stroke. Use the `.path` property to do collision detection and other
+     * operations involving the stroke's geometry.
+     *
+     * Note that many of {@link Path}'s methods (e.g. {@link Path.intersection}) take a
+     * `strokeWidth` parameter that can be gotten from {@link RenderablePathSpec.style} `.stroke.width`.
+     */
+    getParts(): Readonly<RenderablePathSpecWithPath>[];
     /**
      * @returns the {@link Path.union} of all paths that make up this stroke.
      */

package/dist/cjs/components/Stroke.js

@@ -23,6 +23,9 @@ const RenderablePathSpec_1 = require("../rendering/RenderablePathSpec");
  * ```ts
  * editor.dispatch(stroke.transformBy(Mat33.translation(Vec2.of(10, 0))));
  * ```
+ *
+ * **Adding**:
+ * [[include:doc-pages/inline-examples/adding-a-stroke.md]]
  */
 class Stroke extends AbstractComponent_1.default {
     /**
@@ -37,7 +40,7 @@ class Stroke extends AbstractComponent_1.default {
      *
      * const stroke = new Stroke([
      *     // Fill with red
-     *     pathToRenderable({ fill: Color4.red })
+     *     pathToRenderable(path, { fill: Color4.red })
      * ]);
      * ```
      */
@@ -295,6 +298,19 @@ class Stroke extends AbstractComponent_1.default {
             };
         });
     }
+    /**
+     * @returns A list of the parts that make up this path. Many paths only have one part.
+     *
+     * Each part (a {@link RenderablePathSpec}) contains information about the style and geometry
+     * of that part of the stroke. Use the `.path` property to do collision detection and other
+     * operations involving the stroke's geometry.
+     *
+     * Note that many of {@link Path}'s methods (e.g. {@link Path.intersection}) take a
+     * `strokeWidth` parameter that can be gotten from {@link RenderablePathSpec.style} `.stroke.width`.
+     */
+    getParts() {
+        return [...this.parts];
+    }
     /**
      * @returns the {@link Path.union} of all paths that make up this stroke.
      */

package/dist/cjs/components/builders/ArrowBuilder.js

@@ -6,10 +6,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeArrowBuilder = void 0;
 const math_1 = require("@js-draw/math");
 const Stroke_1 = __importDefault(require("../Stroke"));
-const makeArrowBuilder = (initialPoint, viewport) => {
+const makeSnapToGridAutocorrect_1 = __importDefault(require("./autocorrect/makeSnapToGridAutocorrect"));
+exports.makeArrowBuilder = (0, makeSnapToGridAutocorrect_1.default)((initialPoint, viewport) => {
     return new ArrowBuilder(initialPoint, viewport);
-};
-exports.makeArrowBuilder = makeArrowBuilder;
+});
 class ArrowBuilder {
     constructor(startPoint, viewport) {
         this.startPoint = startPoint;

package/dist/cjs/components/builders/CircleBuilder.js

@@ -8,10 +8,10 @@ const math_1 = require("@js-draw/math");
 const RenderablePathSpec_1 = require("../../rendering/RenderablePathSpec");
 const Viewport_1 = __importDefault(require("../../Viewport"));
 const Stroke_1 = __importDefault(require("../Stroke"));
-const makeOutlinedCircleBuilder = (initialPoint, viewport) => {
+const makeSnapToGridAutocorrect_1 = __importDefault(require("./autocorrect/makeSnapToGridAutocorrect"));
+exports.makeOutlinedCircleBuilder = (0, makeSnapToGridAutocorrect_1.default)((initialPoint, viewport) => {
     return new CircleBuilder(initialPoint, viewport);
-};
-exports.makeOutlinedCircleBuilder = makeOutlinedCircleBuilder;
+});
 class CircleBuilder {
     constructor(startPoint, viewport) {
         this.startPoint = startPoint;

package/dist/cjs/components/builders/FreehandLineBuilder.js

@@ -8,14 +8,14 @@ const math_1 = require("@js-draw/math");
 const Stroke_1 = __importDefault(require("../Stroke"));
 const Viewport_1 = __importDefault(require("../../Viewport"));
 const StrokeSmoother_1 = require("../util/StrokeSmoother");
-const makeFreehandLineBuilder = (initialPoint, viewport) => {
+const makeShapeFitAutocorrect_1 = __importDefault(require("./autocorrect/makeShapeFitAutocorrect"));
+exports.makeFreehandLineBuilder = (0, makeShapeFitAutocorrect_1.default)((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.
     const maxSmoothingDist = viewport.getSizeOfPixelOnCanvas() * 3;
     const minSmoothingDist = viewport.getSizeOfPixelOnCanvas();
     return new FreehandLineBuilder(initialPoint, minSmoothingDist, maxSmoothingDist, viewport);
-};
-exports.makeFreehandLineBuilder = makeFreehandLineBuilder;
+});
 // Handles stroke smoothing and creates Strokes from user/stylus input.
 class FreehandLineBuilder {
     constructor(startPoint, minFitAllowed, maxFitAllowed, viewport) {

package/dist/cjs/components/builders/LineBuilder.js

@@ -7,10 +7,10 @@ exports.makeLineBuilder = void 0;
 const math_1 = require("@js-draw/math");
 const RenderablePathSpec_1 = require("../../rendering/RenderablePathSpec");
 const Stroke_1 = __importDefault(require("../Stroke"));
-const makeLineBuilder = (initialPoint, viewport) => {
+const makeSnapToGridAutocorrect_1 = __importDefault(require("./autocorrect/makeSnapToGridAutocorrect"));
+exports.makeLineBuilder = (0, makeSnapToGridAutocorrect_1.default)((initialPoint, viewport) => {
     return new LineBuilder(initialPoint, viewport);
-};
-exports.makeLineBuilder = makeLineBuilder;
+});
 class LineBuilder {
     constructor(startPoint, viewport) {
         this.startPoint = startPoint;

package/dist/cjs/components/builders/PressureSensitiveFreehandLineBuilder.js

@@ -9,14 +9,14 @@ const math_1 = require("@js-draw/math");
 const Stroke_1 = __importDefault(require("../Stroke"));
 const Viewport_1 = __importDefault(require("../../Viewport"));
 const StrokeSmoother_1 = require("../util/StrokeSmoother");
-const makePressureSensitiveFreehandLineBuilder = (initialPoint, viewport) => {
+const makeShapeFitAutocorrect_1 = __importDefault(require("./autocorrect/makeShapeFitAutocorrect"));
+exports.makePressureSensitiveFreehandLineBuilder = (0, makeShapeFitAutocorrect_1.default)((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.
     const maxSmoothingDist = viewport.getSizeOfPixelOnCanvas() * 3;
     const minSmoothingDist = viewport.getSizeOfPixelOnCanvas();
     return new PressureSensitiveFreehandLineBuilder(initialPoint, minSmoothingDist, maxSmoothingDist, viewport);
-};
-exports.makePressureSensitiveFreehandLineBuilder = makePressureSensitiveFreehandLineBuilder;
+});
 // Handles stroke smoothing and creates Strokes from user/stylus input.
 class PressureSensitiveFreehandLineBuilder {
     constructor(startPoint, 

package/dist/cjs/components/builders/RectangleBuilder.js

@@ -7,14 +7,13 @@ exports.makeOutlinedRectangleBuilder = exports.makeFilledRectangleBuilder = void
 const math_1 = require("@js-draw/math");
 const RenderablePathSpec_1 = require("../../rendering/RenderablePathSpec");
 const Stroke_1 = __importDefault(require("../Stroke"));
-const makeFilledRectangleBuilder = (initialPoint, viewport) => {
+const makeSnapToGridAutocorrect_1 = __importDefault(require("./autocorrect/makeSnapToGridAutocorrect"));
+exports.makeFilledRectangleBuilder = (0, makeSnapToGridAutocorrect_1.default)((initialPoint, viewport) => {
     return new RectangleBuilder(initialPoint, true, viewport);
-};
-exports.makeFilledRectangleBuilder = makeFilledRectangleBuilder;
-const makeOutlinedRectangleBuilder = (initialPoint, viewport) => {
+});
+exports.makeOutlinedRectangleBuilder = (0, makeSnapToGridAutocorrect_1.default)((initialPoint, viewport) => {
     return new RectangleBuilder(initialPoint, false, viewport);
-};
-exports.makeOutlinedRectangleBuilder = makeOutlinedRectangleBuilder;
+});
 class RectangleBuilder {
     constructor(startPoint, filled, viewport) {
         this.startPoint = startPoint;

package/dist/cjs/components/builders/autocorrect/makeShapeFitAutocorrect.d.ts

@@ -0,0 +1,3 @@
+import { ComponentBuilderFactory } from '../types';
+declare const makeShapeFitAutocorrect: (sourceFactory: ComponentBuilderFactory) => ComponentBuilderFactory;
+export default makeShapeFitAutocorrect;

package/dist/cjs/components/builders/autocorrect/makeShapeFitAutocorrect.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const math_1 = require("@js-draw/math");
+const makeShapeFitAutocorrect = (sourceFactory) => {
+    return (startPoint, viewport) => {
+        return new ShapeFitBuilder(sourceFactory, startPoint, viewport);
+    };
+};
+exports.default = makeShapeFitAutocorrect;
+const makeLineTemplate = (startPoint, points, _bbox) => {
+    const templatePoints = [
+        startPoint,
+        points[points.length - 1],
+    ];
+    return { points: templatePoints, };
+};
+const makeRectangleTemplate = (_startPoint, _points, bbox) => {
+    return { points: [...bbox.corners, bbox.corners[0]], };
+};
+class ShapeFitBuilder {
+    constructor(sourceFactory, startPoint, viewport) {
+        this.sourceFactory = sourceFactory;
+        this.startPoint = startPoint;
+        this.viewport = viewport;
+        this.builder = sourceFactory(startPoint, viewport);
+        this.points = [startPoint];
+    }
+    getBBox() {
+        return this.builder.getBBox();
+    }
+    build() {
+        return this.builder.build();
+    }
+    preview(renderer) {
+        this.builder.preview(renderer);
+    }
+    addPoint(point) {
+        this.points.push(point);
+        this.builder.addPoint(point);
+    }
+    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 bbox = math_1.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 snappedBBox = math_1.Rect2.bboxOf(snappedPoints);
+        // Only fit larger shapes
+        if (bbox.maxDimension < 32) {
+            return null;
+        }
+        const maxError = Math.min(30, bbox.maxDimension / 4);
+        // Create templates
+        const templates = [
+            {
+                ...makeLineTemplate(snappedStartPoint, snappedPoints, snappedBBox),
+                toleranceMultiplier: 0.5,
+            },
+            makeLineTemplate(startPoint, points, bbox),
+            {
+                ...makeRectangleTemplate(snappedStartPoint, snappedPoints, snappedBBox),
+                toleranceMultiplier: 0.6,
+            },
+            makeRectangleTemplate(startPoint, points, bbox),
+        ];
+        // Find a good fit fit
+        const selectTemplate = (maximumAllowedError) => {
+            for (const template of templates) {
+                const templatePoints = template.points;
+                // Maximum square error to accept the template
+                const acceptMaximumSquareError = maximumAllowedError * maximumAllowedError * (template.toleranceMultiplier ?? 1);
+                // Gets the point at index, wrapping the the start of the template if
+                // outside the array of points.
+                const templateAt = (index) => {
+                    while (index < 0) {
+                        index += templatePoints.length;
+                    }
+                    index %= templatePoints.length;
+                    return templatePoints[index];
+                };
+                let closestToFirst = null;
+                let closestToFirstSqrDist = Infinity;
+                let templateStartIndex = 0;
+                // Find the closest point to the startPoint
+                for (let i = 0; i < templatePoints.length; i++) {
+                    const current = templatePoints[i];
+                    const currentSqrDist = current.minus(startPoint).magnitudeSquared();
+                    if (!closestToFirst || currentSqrDist < closestToFirstSqrDist) {
+                        closestToFirstSqrDist = currentSqrDist;
+                        closestToFirst = current;
+                        templateStartIndex = i;
+                    }
+                }
+                // Walk through the points and find the maximum error
+                let maximumSqrError = 0;
+                let templateIndex = templateStartIndex;
+                for (const point of points) {
+                    let minimumCurrentSqrError = Infinity;
+                    let minimumErrorAtIndex = templateIndex;
+                    const windowRadius = 6;
+                    for (let i = -windowRadius; i <= windowRadius; i++) {
+                        const index = templateIndex + i;
+                        const prevTemplatePoint = templateAt(index - 1);
+                        const currentTemplatePoint = templateAt(index);
+                        const nextTemplatePoint = templateAt(index + 1);
+                        const prevToCurrent = new math_1.LineSegment2(prevTemplatePoint, currentTemplatePoint);
+                        const currentToNext = new math_1.LineSegment2(currentTemplatePoint, nextTemplatePoint);
+                        const prevToCurrentDist = prevToCurrent.distance(point);
+                        const nextToCurrentDist = currentToNext.distance(point);
+                        const error = Math.min(prevToCurrentDist, nextToCurrentDist);
+                        const squareError = error * error;
+                        if (squareError < minimumCurrentSqrError) {
+                            minimumCurrentSqrError = squareError;
+                            minimumErrorAtIndex = index;
+                        }
+                    }
+                    templateIndex = minimumErrorAtIndex;
+                    maximumSqrError = Math.max(minimumCurrentSqrError, maximumSqrError);
+                    if (maximumSqrError > acceptMaximumSquareError) {
+                        break;
+                    }
+                }
+                if (maximumSqrError < acceptMaximumSquareError) {
+                    return templatePoints;
+                }
+            }
+            return null;
+        };
+        const template = selectTemplate(maxError);
+        if (!template) {
+            return null;
+        }
+        const lastDataPoint = this.points[this.points.length - 1];
+        const startWidth = this.startPoint.width;
+        const endWidth = lastDataPoint.width;
+        const startColor = this.startPoint.color;
+        const endColor = lastDataPoint.color;
+        const startTime = this.startPoint.time;
+        const endTime = lastDataPoint.time;
+        const templateIndexToStrokeDataPoint = (index) => {
+            const prevPoint = template[Math.max(0, Math.floor(index))];
+            const nextPoint = template[Math.min(Math.ceil(index), template.length - 1)];
+            const point = prevPoint.lerp(nextPoint, index - Math.floor(index));
+            const fractionToEnd = index / template.length;
+            return {
+                pos: this.viewport.screenToCanvas(point),
+                width: startWidth * (1 - fractionToEnd) + endWidth * fractionToEnd,
+                color: startColor.mix(endColor, fractionToEnd),
+                time: startTime * (1 - fractionToEnd) + endTime * fractionToEnd,
+            };
+        };
+        const builder = this.sourceFactory(templateIndexToStrokeDataPoint(0), this.viewport);
+        // Prevent the original builder from doing stroke smoothing if the template is short
+        // enough to likely have sharp corners.
+        const preventSmoothing = template.length < 10;
+        for (let i = 0; i < template.length; i++) {
+            if (preventSmoothing) {
+                builder.addPoint(templateIndexToStrokeDataPoint(i - 0.001));
+            }
+            builder.addPoint(templateIndexToStrokeDataPoint(i));
+            if (preventSmoothing) {
+                builder.addPoint(templateIndexToStrokeDataPoint(i + 0.001));
+            }
+        }
+        return builder.build();
+    }
+}

package/dist/cjs/components/builders/autocorrect/makeSnapToGridAutocorrect.d.ts

@@ -0,0 +1,3 @@
+import { ComponentBuilderFactory } from '../types';
+declare const makeSnapToGridAutocorrect: (sourceFactory: ComponentBuilderFactory) => ComponentBuilderFactory;
+export default makeSnapToGridAutocorrect;

package/dist/cjs/components/builders/autocorrect/makeSnapToGridAutocorrect.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const makeSnapToGridAutocorrect = (sourceFactory) => {
+    return (startPoint, viewport) => {
+        return new SnapToGridAutocompleteBuilder(sourceFactory, startPoint, viewport);
+    };
+};
+exports.default = makeSnapToGridAutocorrect;
+class SnapToGridAutocompleteBuilder {
+    constructor(sourceFactory, startPoint, viewport) {
+        this.sourceFactory = sourceFactory;
+        this.startPoint = startPoint;
+        this.viewport = viewport;
+        this.builder = sourceFactory(startPoint, viewport);
+        this.points = [startPoint];
+    }
+    getBBox() {
+        return this.builder.getBBox();
+    }
+    build() {
+        return this.builder.build();
+    }
+    preview(renderer) {
+        this.builder.preview(renderer);
+    }
+    addPoint(point) {
+        this.points.push(point);
+        this.builder.addPoint(point);
+    }
+    async autocorrectShape() {
+        const snapToGrid = (point) => {
+            return {
+                ...point,
+                pos: this.viewport.snapToGrid(point.pos),
+            };
+        };
+        // 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));
+        for (const point of points) {
+            builder.addPoint(point);
+        }
+        return builder.build();
+    }
+}

package/dist/cjs/components/builders/types.d.ts

@@ -7,6 +7,18 @@ export interface ComponentBuilder {
     getBBox(): Rect2;
     build(): AbstractComponent;
     preview(renderer: AbstractRenderer): void;
+    /**
+     * Called when the pen is stationary (or the user otherwise
+     * activates autocomplete). This might attempt to fit the user's
+     * drawing to a particular shape.
+     *
+     * The shape returned by this function may be ignored if it has
+     * an empty bounding box.
+     *
+     * Although this returns a Promise, it should return *as fast as
+     * possible*.
+     */
+    autocorrectShape?: () => Promise<AbstractComponent | null>;
     addPoint(point: StrokeDataPoint): void;
 }
 export type ComponentBuilderFactory = (startPoint: StrokeDataPoint, viewport: Viewport) => ComponentBuilder;

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

@@ -87,6 +87,9 @@ export default class EditorImage {
      * rendered onto the main rendering canvas instead of doing a full re-render.
      *
      * @see {@link Display.flatten}
+     *
+     * @example
+     * [[include:doc-pages/inline-examples/adding-a-stroke.md]]
      */
     static addElement(elem: AbstractComponent, applyByFlattening?: boolean): SerializableCommand;
     /** @see EditorImage.addElement */
@@ -105,8 +108,36 @@ export default class EditorImage {
      * autoresize (if it was previously enabled).
      */
     setImportExportRect(imageRect: Rect2): SerializableCommand;
+    /** @see {@link setAutoresizeEnabled} */
     getAutoresizeEnabled(): boolean;
-    /** Returns a `Command` that sets whether the image should autoresize. */
+    /**
+     * Returns a `Command` that sets whether the image should autoresize when
+     * {@link AbstractComponent}s are added/removed.
+     *
+     * @example
+     *
+     * ```ts,runnable
+     * import { Editor } from 'js-draw';
+     *
+     * const editor = new Editor(document.body);
+     * const toolbar = editor.addToolbar();
+     *
+     * // Add a save button to demonstrate what the output looks like
+     * // (it should change size to fit whatever was drawn)
+     * toolbar.addSaveButton(() => {
+     *   document.body.replaceChildren(editor.toSVG({ sanitize: true }));
+     * });
+     *
+     * // Actually using setAutoresizeEnabled:
+     * //
+     * // To set autoresize without announcing for accessibility/making undoable
+     * const addToHistory = false;
+     * editor.dispatchNoAnnounce(editor.image.setAutoresizeEnabled(true), addToHistory);
+     *
+     * // Add to undo history **and** announce for accessibility
+     * //editor.dispatch(editor.image.setAutoresizeEnabled(true), true);
+     * ```
+     */
     setAutoresizeEnabled(autoresize: boolean): Command;
     private setAutoresizeEnabledDirectly;
     /** Updates the size/position of the viewport */

package/dist/cjs/image/EditorImage.js

@@ -210,6 +210,9 @@ class EditorImage {
      * rendered onto the main rendering canvas instead of doing a full re-render.
      *
      * @see {@link Display.flatten}
+     *
+     * @example
+     * [[include:doc-pages/inline-examples/adding-a-stroke.md]]
      */
     static addElement(elem, applyByFlattening = false) {
         return new _a.AddElementCommand(elem, applyByFlattening);
@@ -237,10 +240,38 @@ class EditorImage {
     setImportExportRect(imageRect) {
         return _a.SetImportExportRectCommand.of(this, imageRect, false);
     }
+    /** @see {@link setAutoresizeEnabled} */
     getAutoresizeEnabled() {
         return this.shouldAutoresizeExportViewport;
     }
-    /** Returns a `Command` that sets whether the image should autoresize. */
+    /**
+     * Returns a `Command` that sets whether the image should autoresize when
+     * {@link AbstractComponent}s are added/removed.
+     *
+     * @example
+     *
+     * ```ts,runnable
+     * import { Editor } from 'js-draw';
+     *
+     * const editor = new Editor(document.body);
+     * const toolbar = editor.addToolbar();
+     *
+     * // Add a save button to demonstrate what the output looks like
+     * // (it should change size to fit whatever was drawn)
+     * toolbar.addSaveButton(() => {
+     *   document.body.replaceChildren(editor.toSVG({ sanitize: true }));
+     * });
+     *
+     * // Actually using setAutoresizeEnabled:
+     * //
+     * // To set autoresize without announcing for accessibility/making undoable
+     * const addToHistory = false;
+     * editor.dispatchNoAnnounce(editor.image.setAutoresizeEnabled(true), addToHistory);
+     *
+     * // Add to undo history **and** announce for accessibility
+     * //editor.dispatch(editor.image.setAutoresizeEnabled(true), true);
+     * ```
+     */
     setAutoresizeEnabled(autoresize) {
         if (autoresize === this.shouldAutoresizeExportViewport) {
             return Command_1.default.empty;

package/dist/cjs/rendering/RenderablePathSpec.d.ts

@@ -6,11 +6,15 @@ interface RenderablePathSpec {
     style: RenderingStyle;
     path?: Path;
 }
-interface RenderablePathSpecWithPath extends RenderablePathSpec {
+export interface RenderablePathSpecWithPath extends RenderablePathSpec {
     path: Path;
 }
 /** Converts a renderable path (a path with a `startPoint`, `commands`, and `style`). */
 export declare const pathFromRenderable: (renderable: RenderablePathSpec) => Path;
+/**
+ * Converts `path` into a format that can be rendered (by passing to a {@link Stroke} constructor
+ * or directly to an {@link AbstractRenderer.drawPath}).
+ */
 export declare const pathToRenderable: (path: Path, style: RenderingStyle) => RenderablePathSpecWithPath;
 interface RectangleSimplificationResult {
     rectangle: Rect2;

package/dist/cjs/rendering/RenderablePathSpec.js

@@ -10,6 +10,10 @@ const pathFromRenderable = (renderable) => {
     return new math_1.Path(renderable.startPoint, renderable.commands);
 };
 exports.pathFromRenderable = pathFromRenderable;
+/**
+ * Converts `path` into a format that can be rendered (by passing to a {@link Stroke} constructor
+ * or directly to an {@link AbstractRenderer.drawPath}).
+ */
 const pathToRenderable = (path, style) => {
     return {
         startPoint: path.startPoint,

package/dist/cjs/toolbar/AbstractToolbar.d.ts

@@ -3,6 +3,7 @@ import { ToolbarLocalization } from './localization';
 import { ActionButtonIcon } from './types';
 import BaseWidget, { ToolbarWidgetTag } from './widgets/BaseWidget';
 import { DispatcherEventListener } from '../EventDispatcher';
+import { BaseTool } from '../lib';
 export interface SpacerOptions {
     grow: number;
     minSize: string;
@@ -131,7 +132,7 @@ export default abstract class AbstractToolbar {
     /**
      * Adds an "Exit" button that, when clicked, calls `exitCallback`.
      *
-     * **Note**: This is roughly equivalent to
+     * **Note**: This is *roughly* equivalent to
      * ```ts
      * toolbar.addTaggedActionButton([ ToolbarWidgetTag.Exit ], {
      *   label: this.editor.localization.exit,
@@ -154,9 +155,24 @@ export default abstract class AbstractToolbar {
      */
     addUndoRedoButtons(undoFirst?: boolean): void;
     /**
-     * Adds toolbar widgets based on the enabled tools.
+     * Adds widgets for pen/eraser/selection/text/pan-zoom primary tools.
+     *
+     * If `filter` returns `false` for a tool, no widget is added for that tool.
+     * See {@link addDefaultToolWidgets}
+     */
+    addWidgetsForPrimaryTools(filter?: (tool: BaseTool) => boolean): void;
+    /**
+     * Adds toolbar widgets based on the enabled tools, and additional tool-like
+     * buttons (e.g. {@link DocumentPropertiesWidget} and {@link InsertImageWidget}).
      */
     addDefaultToolWidgets(): void;
+    /**
+     * Adds widgets that don't correspond to tools, but do allow the user to control
+     * the editor in some way.
+     *
+     * By default, this includes {@link DocumentPropertiesWidget} and {@link InsertImageWidget}.
+     */
+    addDefaultEditorControlWidgets(): void;
     addDefaultActionButtons(): void;
     /**
      * Adds both the default tool widgets and action buttons.