js-draw 1.22.0 → 1.23.1

package/dist/cjs/Editor.d.ts

@@ -411,9 +411,7 @@ export declare class Editor {
      * Use this to show finalized commands that don't need to have `announceForAccessibility`
      * called.
      *
-     * Prefer `command.apply(editor)` for incomplete commands. `dispatchNoAnnounce` may allow
-     * clients to listen for the application of commands (e.g. `SerializableCommand`s so they can
-     * be sent across the network), while `apply` does not.
+     * If `addToHistory` is `false`, this is equivalent to `command.apply(editor)`.
      *
      * @example
      * ```

package/dist/cjs/Editor.js

@@ -137,7 +137,7 @@ class Editor {
             maxZoom: settings.maxZoom ?? 1e12,
             keyboardShortcutOverrides: settings.keyboardShortcutOverrides ?? {},
             iconProvider: settings.iconProvider ?? new IconProvider_1.default(),
-            notices: [],
+            notices: settings.notices ?? [],
             appInfo: settings.appInfo ? { ...settings.appInfo } : null,
             pens: {
                 additionalPenTypes: settings.pens?.additionalPenTypes ?? [],
@@ -755,9 +755,7 @@ class Editor {
      * Use this to show finalized commands that don't need to have `announceForAccessibility`
      * called.
      *
-     * Prefer `command.apply(editor)` for incomplete commands. `dispatchNoAnnounce` may allow
-     * clients to listen for the application of commands (e.g. `SerializableCommand`s so they can
-     * be sent across the network), while `apply` does not.
+     * If `addToHistory` is `false`, this is equivalent to `command.apply(editor)`.
      *
      * @example
      * ```

package/dist/cjs/SVGLoader/SVGLoader.js

@@ -561,6 +561,7 @@ class SVGLoader {
         const { svgElem, cleanUp } = (() => {
             // If the user requested an iframe load (the default) try to load with an iframe.
             // There are some cases (e.g. in a sandboxed iframe) where this doesn't work.
+            // TODO(v2): Use domParserLoad by default.
             if (!domParserLoad) {
                 try {
                     const sandbox = document.createElement('iframe');
@@ -600,6 +601,7 @@ class SVGLoader {
 					`);
                     sandboxDoc.close();
                     const svgElem = sandboxDoc.createElementNS('http://www.w3.org/2000/svg', 'svg');
+                    // eslint-disable-next-line no-unsanitized/property -- setting innerHTML in a sandboxed document.
                     svgElem.innerHTML = text;
                     sandboxDoc.body.appendChild(svgElem);
                     const cleanUp = () => {

package/dist/cjs/Viewport.d.ts

@@ -53,7 +53,7 @@ export declare class Viewport {
     /**
      * Snaps `canvasPos` to the nearest grid cell corner.
      *
-     * @see {@link getGridSize} and {@link getScaleFactorToNearestPowerOf}.
+     * @see {@link getGridSize}.
      */
     snapToGrid(canvasPos: Point2): {
         readonly x: number;

package/dist/cjs/Viewport.js

@@ -107,7 +107,7 @@ class Viewport {
     /**
      * Snaps `canvasPos` to the nearest grid cell corner.
      *
-     * @see {@link getGridSize} and {@link getScaleFactorToNearestPowerOf}.
+     * @see {@link getGridSize}.
      */
     snapToGrid(canvasPos) {
         const scaleFactor = this.getScaleFactorToNearestPowerOf(2);

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

@@ -122,7 +122,7 @@ export default abstract class AbstractComponent {
      * updates the editor.
      *
      * The transformed component is also moved to the top (use
-     * {@link AbstractComponent.setZIndexAndTransformBy} to avoid this behavior).
+     * {@link AbstractComponent#setZIndexAndTransformBy} to avoid this behavior).
      */
     transformBy(affineTransfm: Mat33): SerializableCommand;
     setZIndex(newZIndex: number): SerializableCommand;

package/dist/cjs/components/AbstractComponent.js

@@ -162,7 +162,7 @@ class AbstractComponent {
      * updates the editor.
      *
      * The transformed component is also moved to the top (use
-     * {@link AbstractComponent.setZIndexAndTransformBy} to avoid this behavior).
+     * {@link AbstractComponent#setZIndexAndTransformBy} to avoid this behavior).
      */
     transformBy(affineTransfm) {
         return new AbstractComponent.TransformElementCommand(affineTransfm, this.getId(), this);

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

@@ -5,7 +5,7 @@ import Viewport from '../../Viewport';
 import AbstractComponent from '../AbstractComponent';
 import { ComponentBuilder, ComponentBuilderFactory } from './types';
 /**
- * Creates a stroke builder that generates arrows circles.
+ * Creates a stroke builder that generates arrows.
  *
  * Example:
  * [[include:doc-pages/inline-examples/changing-pen-types.md]]

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

@@ -8,7 +8,7 @@ const math_1 = require("@js-draw/math");
 const Stroke_1 = __importDefault(require("../Stroke"));
 const makeSnapToGridAutocorrect_1 = __importDefault(require("./autocorrect/makeSnapToGridAutocorrect"));
 /**
- * Creates a stroke builder that generates arrows circles.
+ * Creates a stroke builder that generates arrows.
  *
  * Example:
  * [[include:doc-pages/inline-examples/changing-pen-types.md]]

package/dist/cjs/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/cjs/image/EditorImage.js

@@ -51,7 +51,20 @@ var EditorImageEventType;
 })(EditorImageEventType || (exports.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
@@ -110,10 +123,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);
@@ -144,9 +160,12 @@ 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();
@@ -157,7 +176,11 @@ class EditorImage {
     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) {

package/dist/cjs/rendering/renderers/CanvasRenderer.d.ts

@@ -7,31 +7,8 @@ import RenderablePathSpec from '../RenderablePathSpec';
 /**
  * Renders onto a `CanvasRenderingContext2D`.
  *
- * @example
- * ```ts,runnable
- * import {Editor,CanvasRenderer} from 'js-draw';
- *
- * // Create an editor and load initial data -- don't add to the body (hidden editor).
- * const editor = new Editor(document.createElement('div'));
- * await editor.loadFromSVG('<svg><path d="m0,0 l100,5 l-50,60 l30,20 z" fill="green"/></svg>');
- * ---visible---
- * // Given some editor.
- * // Set up the canvas to be drawn onto.
- * const canvas = document.createElement('canvas');
- * const ctx = canvas.getContext('2d');
- *
- * // Ensure that the canvas can fit the entire rendering
- * const viewport = editor.image.getImportExportViewport();
- * canvas.width = viewport.getScreenRectSize().x;
- * canvas.height = viewport.getScreenRectSize().y;
- *
- * // Render editor.image onto the renderer
- * const renderer = new CanvasRenderer(ctx, viewport);
- * editor.image.render(renderer, viewport);
- *
- * // Add the rendered canvas to the document.
- * document.body.appendChild(canvas);
- * ```
+ * **Example**:
+ * [[include:doc-pages/inline-examples/canvas-renderer.md]]
  */
 export default class CanvasRenderer extends AbstractRenderer {
     private ctx;

package/dist/cjs/rendering/renderers/CanvasRenderer.js

@@ -10,31 +10,8 @@ const RenderablePathSpec_1 = require("../RenderablePathSpec");
 /**
  * Renders onto a `CanvasRenderingContext2D`.
  *
- * @example
- * ```ts,runnable
- * import {Editor,CanvasRenderer} from 'js-draw';
- *
- * // Create an editor and load initial data -- don't add to the body (hidden editor).
- * const editor = new Editor(document.createElement('div'));
- * await editor.loadFromSVG('<svg><path d="m0,0 l100,5 l-50,60 l30,20 z" fill="green"/></svg>');
- * ---visible---
- * // Given some editor.
- * // Set up the canvas to be drawn onto.
- * const canvas = document.createElement('canvas');
- * const ctx = canvas.getContext('2d');
- *
- * // Ensure that the canvas can fit the entire rendering
- * const viewport = editor.image.getImportExportViewport();
- * canvas.width = viewport.getScreenRectSize().x;
- * canvas.height = viewport.getScreenRectSize().y;
- *
- * // Render editor.image onto the renderer
- * const renderer = new CanvasRenderer(ctx, viewport);
- * editor.image.render(renderer, viewport);
- *
- * // Add the rendered canvas to the document.
- * document.body.appendChild(canvas);
- * ```
+ * **Example**:
+ * [[include:doc-pages/inline-examples/canvas-renderer.md]]
  */
 class CanvasRenderer extends AbstractRenderer_1.default {
     /**

package/dist/cjs/rendering/renderers/SVGRenderer.js

@@ -49,7 +49,7 @@ class SVGRenderer extends AbstractRenderer_1.default {
         if (!this.elem.querySelector(`#${exports.renderedStylesheetId}`)) {
             // Default to rounded strokes.
             const styleSheet = document.createElementNS('http://www.w3.org/2000/svg', 'style');
-            styleSheet.innerHTML = `
+            styleSheet.appendChild(document.createTextNode(`
 				path {
 					stroke-linecap: round;
 					stroke-linejoin: round;
@@ -58,7 +58,7 @@ class SVGRenderer extends AbstractRenderer_1.default {
 				text {
 					white-space: pre;
 				}
-			`.replace(/\s+/g, '');
+			`.replace(/\s+/g, '')));
             styleSheet.setAttribute('id', exports.renderedStylesheetId);
             this.elem.appendChild(styleSheet);
         }

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

@@ -110,6 +110,25 @@ export default abstract class AbstractToolbar {
      * as being the value of `mustBeToplevel`.
      *
      * @return The added button.
+     *
+     * **Example**:
+     * ```ts,runnable
+     * import { Editor } from 'js-draw';
+     * const editor = new Editor(document.body);
+     * const toolbar = editor.addToolbar();
+     *
+     * function makeTrashIcon() {
+     *   const container = document.createElement('div');
+     *   container.textContent = '🗑️';
+     *   return container;
+     * }
+     *
+     * toolbar.addActionButton({
+     *   icon: makeTrashIcon(), // can be any Element not in the DOM
+     *   label: 'Delete all',
+     * }, () => {
+     *   alert('to-do!');
+     * });
      */
     addActionButton(title: string | ActionButtonIcon, command: () => void, options?: ToolbarActionButtonOptions | boolean): BaseWidget;
     /**

package/dist/cjs/toolbar/AbstractToolbar.js

@@ -269,6 +269,25 @@ class AbstractToolbar {
      * as being the value of `mustBeToplevel`.
      *
      * @return The added button.
+     *
+     * **Example**:
+     * ```ts,runnable
+     * import { Editor } from 'js-draw';
+     * const editor = new Editor(document.body);
+     * const toolbar = editor.addToolbar();
+     *
+     * function makeTrashIcon() {
+     *   const container = document.createElement('div');
+     *   container.textContent = '🗑️';
+     *   return container;
+     * }
+     *
+     * toolbar.addActionButton({
+     *   icon: makeTrashIcon(), // can be any Element not in the DOM
+     *   label: 'Delete all',
+     * }, () => {
+     *   alert('to-do!');
+     * });
      */
     addActionButton(title, command, options = true) {
         const widget = this.makeActionButton(title, command, options);

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

@@ -80,9 +80,13 @@ export default class IconProvider {
      * @returns An object with both the definition of a checkerboard pattern and the syntax to
      * reference that pattern. The defs provided by this function should be wrapped within a
      * `<defs></defs>` element.
+     *
+     * **Note**: This function's return value includes both `patternDefElement` (which returns
+     * an Element) and a (deprecated) `patternDef` string. Avoid using the `patternDef` result.
      */
     protected makeCheckerboardPattern(): {
-        patternDef: string;
+        patternDefElement: SVGElement;
+        readonly patternDef: string;
         patternRef: string;
     };
     /**