js-draw 1.22.0 → 1.23.1

package/dist/mjs/Viewport.mjs

@@ -100,7 +100,7 @@ export 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/mjs/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/mjs/components/AbstractComponent.mjs

@@ -156,7 +156,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/mjs/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/mjs/components/builders/ArrowBuilder.mjs

@@ -2,7 +2,7 @@ import { Path, PathCommandType } from '@js-draw/math';
 import  Stroke  from '../Stroke.mjs';
 import  makeSnapToGridAutocorrect  from './autocorrect/makeSnapToGridAutocorrect.mjs';
 /**
- * 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/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,9 +130,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();
@@ -127,7 +146,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/mjs/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/mjs/rendering/renderers/CanvasRenderer.mjs

@@ -5,31 +5,8 @@ import  { visualEquivalent }  from '../RenderablePathSpec.mjs';
 /**
  * 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 {
     /**

package/dist/mjs/rendering/renderers/SVGRenderer.mjs

@@ -43,7 +43,7 @@ export default class SVGRenderer extends AbstractRenderer {
         if (!this.elem.querySelector(`#${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;
@@ -52,7 +52,7 @@ export default class SVGRenderer extends AbstractRenderer {
 				text {
 					white-space: pre;
 				}
-			`.replace(/\s+/g, '');
+			`.replace(/\s+/g, '')));
             styleSheet.setAttribute('id', renderedStylesheetId);
             this.elem.appendChild(styleSheet);
         }

package/dist/mjs/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/mjs/toolbar/AbstractToolbar.mjs

@@ -264,6 +264,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/mjs/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;
     };
     /**