js-draw - npm Package Compare versions

Comparing version 1.22.0 to 1.23.1

dist/cjs/components/AbstractComponent.d.ts

@@ -125,3 +125,3 @@ import SerializableCommand from '../commands/SerializableCommand';
      * The transformed component is also moved to the top (use
-     * {@link AbstractComponent.setZIndexAndTransformBy} to avoid this behavior).
+     * {@link AbstractComponent#setZIndexAndTransformBy} to avoid this behavior).
      */
@@ -128,0 +128,0 @@ transformBy(affineTransfm: Mat33): SerializableCommand;

dist/cjs/components/AbstractComponent.js

@@ -165,3 +165,3 @@ "use strict";
      * The transformed component is also moved to the top (use
-     * {@link AbstractComponent.setZIndexAndTransformBy} to avoid this behavior).
+     * {@link AbstractComponent#setZIndexAndTransformBy} to avoid this behavior).
      */
@@ -168,0 +168,0 @@ transformBy(affineTransfm) {

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

@@ -8,3 +8,3 @@ import { Rect2 } from '@js-draw/math';
 /**
- * Creates a stroke builder that generates arrows circles.
+ * Creates a stroke builder that generates arrows.
  *
@@ -11,0 +11,0 @@ * Example:

dist/cjs/components/builders/ArrowBuilder.js

@@ -11,3 +11,3 @@ "use strict";
 /**
- * Creates a stroke builder that generates arrows circles.
+ * Creates a stroke builder that generates arrows.
  *
@@ -14,0 +14,0 @@ * Example:

dist/cjs/Editor.d.ts

@@ -414,5 +414,3 @@ import EditorImage from './image/EditorImage';
      *
-     * 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)`.
      *
@@ -419,0 +417,0 @@ * @example

dist/cjs/Editor.js

@@ -140,3 +140,3 @@ "use strict";
             iconProvider: settings.iconProvider ?? new IconProvider_1.default(),
-            notices: [],
+            notices: settings.notices ?? [],
             appInfo: settings.appInfo ? { ...settings.appInfo } : null,
@@ -759,5 +759,3 @@ pens: {
      *
-     * 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)`.
      *
@@ -764,0 +762,0 @@ * @example

dist/cjs/image/EditorImage.d.ts

@@ -25,3 +25,16 @@ import AbstractRenderer from '../rendering/renderers/AbstractRenderer';
 /**
- * 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]]
  */
@@ -44,6 +57,9 @@ export default 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]]
      */
@@ -68,5 +84,8 @@ render(renderer: AbstractRenderer, viewport: Viewport | null): 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}.
      */
@@ -76,3 +95,7 @@ getAllElements(): AbstractComponent[];
     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[];
@@ -79,0 +102,0 @@ /** Called whenever (just after) an element is completely removed. @internal */

dist/cjs/image/EditorImage.js

@@ -54,3 +54,16 @@ "use strict";
 /**
- * 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]]
  */
@@ -114,6 +127,9 @@ 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]]
      */
@@ -149,5 +165,8 @@ render(renderer, viewport) {
     /**
-     * @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}.
      */
@@ -163,3 +182,7 @@ getAllElements() {
     }
-    /** @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) {
@@ -166,0 +189,0 @@ let leaves = this.root.getLeavesIntersectingRegion(region);

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

@@ -10,27 +10,4 @@ import { Mat33, Rect2, Point2, Vec2, Vec3 } from '@js-draw/math';
  *
- * @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]]
  */
@@ -37,0 +14,0 @@ export default class CanvasRenderer extends AbstractRenderer {

dist/cjs/rendering/renderers/CanvasRenderer.js

@@ -13,27 +13,4 @@ "use strict";
  *
- * @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]]
  */
@@ -40,0 +17,0 @@ class CanvasRenderer extends AbstractRenderer_1.default {

dist/cjs/rendering/renderers/SVGRenderer.js

@@ -52,3 +52,3 @@ "use strict";
             const styleSheet = document.createElementNS('http://www.w3.org/2000/svg', 'style');
-            styleSheet.innerHTML = `
+            styleSheet.appendChild(document.createTextNode(`
 				path {
@@ -62,3 +62,3 @@ stroke-linecap: round;
 				}
-			`.replace(/\s+/g, '');
+			`.replace(/\s+/g, '')));
             styleSheet.setAttribute('id', exports.renderedStylesheetId);
@@ -65,0 +65,0 @@ this.elem.appendChild(styleSheet);

dist/cjs/SVGLoader/SVGLoader.js

@@ -564,2 +564,3 @@ "use strict";
             // There are some cases (e.g. in a sandboxed iframe) where this doesn't work.
+            // TODO(v2): Use domParserLoad by default.
             if (!domParserLoad) {
@@ -604,2 +605,3 @@ try {
                     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;
@@ -606,0 +608,0 @@ sandboxDoc.body.appendChild(svgElem);

dist/cjs/toolbar/AbstractToolbar.d.ts

@@ -113,2 +113,21 @@ import Editor from '../Editor';
      * @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!');
+     * });
      */
@@ -115,0 +134,0 @@ addActionButton(title: string | ActionButtonIcon, command: () => void, options?: ToolbarActionButtonOptions | boolean): BaseWidget;

dist/cjs/toolbar/AbstractToolbar.js

@@ -272,2 +272,21 @@ "use strict";
      * @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!');
+     * });
      */
@@ -274,0 +293,0 @@ addActionButton(title, command, options = true) {

dist/cjs/toolbar/IconProvider.d.ts

@@ -83,5 +83,9 @@ import { Color4 } from '@js-draw/math';
      * `<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;
@@ -88,0 +92,0 @@ };

dist/cjs/toolbar/IconProvider.js

@@ -18,27 +18,28 @@ "use strict";
 const Eraser_1 = require("../tools/Eraser");
+const createElement_1 = require("../util/createElement");
 const svgNamespace = 'http://www.w3.org/2000/svg';
-const iconColorFill = `
-	style='fill: var(--icon-color);'
-`;
-const iconColorStrokeFill = `
-	style='fill: var(--icon-color); stroke: var(--icon-color);'
-`;
 let checkerboardIdCounter = 0;
 const makeCheckerboardPattern = () => {
     const id = `checkerboard-${checkerboardIdCounter++}`;
-    const patternDef = `
-		<pattern
-			id='${id}'
-			viewBox='0,0,10,10'
-			width='20%'
-			height='20%'
-			patternUnits='userSpaceOnUse'
-		>
-			<rect x='0' y='0' width='10' height='10' fill='white'/>
-			<rect x='0' y='0' width='5' height='5' fill='gray'/>
-			<rect x='5' y='5' width='5' height='5' fill='gray'/>
-		</pattern>
-	`;
+    const patternElement = (0, createElement_1.createSvgElement)('pattern', {
+        id: id,
+        viewBox: '0,0,10,10',
+        width: '20%',
+        height: '20%',
+        patternUnits: 'userSpaceOnUse',
+        children: (0, createElement_1.createSvgElements)('rect', [
+            { x: 0, y: 0, width: 10, height: 10, fill: 'white' },
+            { x: 0, y: 0, width: 5, height: 5, fill: 'gray' },
+            { x: 5, y: 5, width: 5, height: 5, fill: 'gray' },
+        ]),
+    });
     const patternRef = `url(#${id})`;
-    return { patternDef, patternRef };
+    return {
+        patternDefElement: patternElement,
+        // @deprecated use patternDefElement
+        get patternDef() {
+            return patternElement.innerHTML;
+        },
+        patternRef,
+    };
 };
@@ -59,7 +60,10 @@ const makeRedoIcon = (mirror) => {
 		</style>
-		<path
-			d='M20,20 A15,15 0 0 1 70,80 L80,90 L60,70 L65,90 L87,90 L65,80'
-			class='toolbar-svg-undo-redo-icon'
-			style='${mirror ? 'transform: scale(-1, 1);' : ''}'/>
 	`;
+    const path = document.createElementNS(svgNamespace, 'path');
+    path.setAttribute('d', 'M20,20 A15,15 0 0 1 70,80 L80,90 L60,70 L65,90 L87,90 L65,80');
+    path.classList.add('toolbar-svg-undo-redo-icon');
+    if (mirror) {
+        path.style.transform = 'scale(-1, 1)';
+    }
+    icon.appendChild(path);
     icon.setAttribute('viewBox', '0 0 100 100');
@@ -112,11 +116,3 @@ return icon;
     makeDropdownIcon() {
-        const icon = document.createElementNS(svgNamespace, 'svg');
-        icon.innerHTML = `
-		<g>
-			<path
-				d='M5,10 L50,90 L95,10 Z'
-				${iconColorFill}
-			/>
-		</g>
-		`;
+        const icon = this.makeIconFromPath('M5,10 L50,90 L95,10 Z');
         icon.setAttribute('viewBox', '-10 -10 110 110');
@@ -126,3 +122,2 @@ return icon;
     makeEraserIcon(eraserSize, mode) {
-        const icon = document.createElementNS(svgNamespace, 'svg');
         eraserSize ??= 10;
@@ -132,43 +127,49 @@ const scaledSize = eraserSize / 4;
         // Draw an eraser-like shape. Created with Inkscape
-        icon.innerHTML = `
-		<defs>
-			<linearGradient id="dash-pattern">
-				<stop offset="80%" stop-color="${eraserColor}"/>
-				<stop offset="85%" stop-color="white"/>
-				<stop offset="90%" stop-color="${eraserColor}"/>
-			</linearGradient>
-		</defs>
-		<g>
-			<path
-				style="fill:${mode === Eraser_1.EraserMode.PartialStroke ? 'url(#dash-pattern)' : eraserColor}"
-				stroke="black"
-				transform="rotate(41.35)"
-				d="M 52.5 27
-					C 50 28.9 48.9 31.7 48.9 34.8
-					L 48.9 39.8
-					C 48.9 45.3 53.4 49.8 58.9 49.8
-					L 103.9 49.8
-					C 105.8 49.8 107.6 49.2 109.1 48.3
-					L 110.2 ${scaledSize + 49.5} L 159.7 ${scaledSize + 5}
-					L 157.7 ${-scaledSize + 5.2} L 112.4 ${49.5 - scaledSize}
-					C 113.4 43.5 113.9 41.7 113.9 39.8
-					L 113.9 34.8
-					C 113.9 29.3 109.4 24.8 103.9 24.8
-					L 58.9 24.8
-					C 56.5 24.8 54.3 25.7 52.5 27
-					z "
-				id="path438" />
-
-			<rect
-				stroke="#cc8077"
-				${iconColorFill}
-				id="rect218"
-				width="65"
-				height="75"
-				x="48.9"
-				y="-38.7"
-				transform="rotate(41.35)" />
-		</g>
-		`;
-        icon.setAttribute('viewBox', '0 0 120 120');
+        const icon = (0, createElement_1.createSvgElement)('svg', {
+            viewBox: '0 0 120 120',
+            children: [
+                (0, createElement_1.createSvgElement)('defs', {
+                    children: [
+                        (0, createElement_1.createSvgElement)('linearGradient', {
+                            id: 'dash-pattern',
+                            children: (0, createElement_1.createSvgElements)('stop', [
+                                { offset: '80%', 'stop-color': eraserColor },
+                                { offset: '85%', 'stop-color': 'white' },
+                                { offset: '90%', 'stop-color': eraserColor },
+                            ]),
+                        }),
+                    ],
+                }),
+                (0, createElement_1.createSvgElement)('path', {
+                    fill: mode === Eraser_1.EraserMode.PartialStroke ? 'url(#dash-pattern)' : eraserColor,
+                    stroke: 'black',
+                    transform: 'rotate(41.35)',
+                    d: `
+						M 52.5 27
+						C 50 28.9 48.9 31.7 48.9 34.8
+						L 48.9 39.8
+						C 48.9 45.3 53.4 49.8 58.9 49.8
+						L 103.9 49.8
+						C 105.8 49.8 107.6 49.2 109.1 48.3
+						L 110.2 ${scaledSize + 49.5} L 159.7 ${scaledSize + 5}
+						L 157.7 ${-scaledSize + 5.2} L 112.4 ${49.5 - scaledSize}
+						C 113.4 43.5 113.9 41.7 113.9 39.8
+						L 113.9 34.8
+						C 113.9 29.3 109.4 24.8 103.9 24.8
+						L 58.9 24.8
+						C 56.5 24.8 54.3 25.7 52.5 27
+						z
+					`,
+                }),
+                (0, createElement_1.createSvgElement)('rect', {
+                    stroke: '#cc8077',
+                    fill: 'var(--icon-color)',
+                    width: 65,
+                    height: 75,
+                    x: 48.9,
+                    y: -38.7,
+                    transform: 'rotate(41.35)',
+                }),
+            ],
+        });
         return icon;
@@ -181,4 +182,4 @@ }
 		<g>
-			<rect x=10 y=10 width=70 height=70 fill='pink' stroke='black'/>
-			<rect x=75 y=75 width=10 height=10 fill='white' stroke='black'/>
+			<rect x="10" y="10" width="70" height="70" fill="pink" stroke="black"/>
+			<rect x="75" y="75" width="10" height="10" fill="white" stroke="black"/>
 		</g>
@@ -446,4 +447,2 @@ `;
         const rounded = this.isRoundedTipPen(penStyle);
-        const icon = document.createElementNS(svgNamespace, 'svg');
-        icon.setAttribute('viewBox', '0 0 100 100');
         const tipThickness = strokeSize / 2;
@@ -481,67 +480,31 @@ const inkTipPath = `
         const checkerboardPattern = makeCheckerboardPattern();
-        const ink = `
-			<path
-				fill="${checkerboardPattern.patternRef}"
-				d="${inkTipPath}"
-			/>
-			<path
-				fill="${checkerboardPattern.patternRef}"
-				d="${inkTrailPath}"
-			/>
-			<path
-				fill="${color}"
-				d="${inkTipPath}"
-			/>
-			<path
-				fill="${color}"
-				d="${inkTrailPath}"
-			/>
-		`;
-        const penTip = `
-			<path
-				fill="${checkerboardPattern.patternRef}"
-				d="${penTipPath}"
-			/>
-			<path
-				fill="${tipColor}"
-				stroke="${color}"
-				d="${penTipPath}"
-			/>
-		`;
-        const grip = `
-			<path
-				${iconColorStrokeFill}
-				d="${gripMainPath}"
-			/>
-
-			<!-- shadows -->
-			<path
-				fill="rgba(150, 150, 150, 0.3)"
-				d="${gripShadow1Path}"
-			/>
-			<path
-				fill="rgba(100, 100, 100, 0.2)"
-				d="${gripShadow2Path}"
-			/>
-
-			<!-- color bubble -->
-			<path
-				fill="${checkerboardPattern.patternRef}"
-				d="${colorBubblePath}"
-			/>
-			<path
-				fill="${color}"
-				d="${colorBubblePath}"
-			/>
-		`;
-        icon.innerHTML = `
-		<defs>
-			${checkerboardPattern.patternDef}
-		</defs>
-		<g>
-			${ink}
-			${penTip}
-			${grip}
-		</g>
-		`;
+        const colorString = color.toHexString();
+        const ink = (0, createElement_1.createSvgPaths)({
+            fill: checkerboardPattern.patternRef,
+            d: inkTipPath,
+        }, {
+            fill: checkerboardPattern.patternRef,
+            d: inkTrailPath,
+        }, {
+            fill: colorString,
+            d: inkTipPath,
+        }, {
+            fill: colorString,
+            d: inkTrailPath,
+        });
+        const penTip = (0, createElement_1.createSvgPaths)({ fill: checkerboardPattern.patternRef, d: penTipPath }, { fill: tipColor, stroke: colorString, d: penTipPath });
+        const grip = (0, createElement_1.createSvgPaths)({ fill: 'var(--icon-color)', stroke: 'var(--icon-color)', d: gripMainPath }, 
+        // Shadows
+        { fill: 'rgba(150, 150, 150, 0.3)', d: gripShadow1Path }, { fill: 'rgba(100, 100, 100, 0.2)', d: gripShadow2Path }, 
+        // Color bubble
+        { fill: checkerboardPattern.patternRef, d: colorBubblePath }, { fill: colorString, d: colorBubblePath });
+        const icon = document.createElementNS(svgNamespace, 'svg');
+        icon.setAttribute('viewBox', '0 0 100 100');
+        const iconMainContent = (0, createElement_1.createSvgElement)('g', {
+            children: [ink, penTip, grip].flat(),
+        });
+        const defs = (0, createElement_1.createSvgElement)('defs', {
+            children: [checkerboardPattern.patternDefElement],
+        });
+        icon.replaceChildren(defs, iconMainContent);
         return icon;
@@ -578,3 +541,3 @@ }
             const defs = document.createElementNS(svgNamespace, 'defs');
-            defs.innerHTML = checkerboardPattern.patternDef;
+            defs.appendChild(checkerboardPattern.patternDefElement);
             icon.appendChild(defs);
@@ -653,3 +616,3 @@ const background = document.createElementNS(svgNamespace, 'g');
             const defs = document.createElementNS(svgNamespace, 'defs');
-            defs.innerHTML = checkerboardPattern.patternDef;
+            defs.appendChild(checkerboardPattern.patternDefElement);
             icon.appendChild(defs);
@@ -859,2 +822,5 @@ const fluidBackground = document.createElementNS(svgNamespace, 'path');
      * `<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.
      */
@@ -861,0 +827,0 @@ makeCheckerboardPattern() {

dist/cjs/toolbar/localization.js

@@ -51,3 +51,3 @@ "use strict";
     strokeAutocorrect: 'Autocorrect',
-    touchPanning: 'Touchscreen panning',
+    touchPanning: 'Scroll with touch',
     roundedTipPen: 'Round',
@@ -79,3 +79,3 @@ roundedTipPen2: 'Polyline',
     handDropdown__zoomDisplayHelpText: 'Shows the current zoom level. 100% shows the image at its actual size.',
-    handDropdown__touchPanningHelpText: 'When enabled, touch gestures move the image rather than select or draw.',
+    handDropdown__touchPanningHelpText: 'When enabled, touchscreen gestures move the image rather than select or draw.',
     handDropdown__lockRotationHelpText: 'When enabled, prevents touch gestures from rotating the screen.',
@@ -82,0 +82,0 @@ eraserDropdown__baseHelpText: 'This tool removes strokes, images, and text under the cursor.',

dist/cjs/toolbar/widgets/BaseWidget.d.ts

@@ -101,3 +101,3 @@ import Editor from '../../Editor';
      * Remove this. This allows the widget to be added to a toolbar again
-     * in the future using {@link addTo}.
+     * in the future using `addTo`.
      */
@@ -104,0 +104,0 @@ remove(): void;

dist/cjs/toolbar/widgets/BaseWidget.js

@@ -309,3 +309,3 @@ "use strict";
      * Remove this. This allows the widget to be added to a toolbar again
-     * in the future using {@link addTo}.
+     * in the future using `addTo`.
      */
@@ -312,0 +312,0 @@ remove() {

dist/cjs/tools/lib.d.ts

@@ -0,1 +1,2 @@
+export { default as InputMapper } from './InputFilter/InputMapper';
 export { default as BaseTool } from './BaseTool';
@@ -2,0 +3,0 @@ export { default as ToolController } from './ToolController';

dist/cjs/tools/lib.js

@@ -6,3 +6,5 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolbarShortcutHandler = exports.SoundUITool = exports.PasteHandler = exports.EraserMode = exports.EraserTool = exports.SelectAllShortcutHandler = exports.SelectionTool = exports.TextTool = exports.PenTool = exports.PanZoomMode = exports.PanZoomTool = exports.ToolSwitcherShortcut = exports.UndoRedoShortcut = exports.ToolEnabledGroup = exports.ToolController = exports.BaseTool = void 0;
+exports.ToolbarShortcutHandler = exports.SoundUITool = exports.PasteHandler = exports.EraserMode = exports.EraserTool = exports.SelectAllShortcutHandler = exports.SelectionTool = exports.TextTool = exports.PenTool = exports.PanZoomMode = exports.PanZoomTool = exports.ToolSwitcherShortcut = exports.UndoRedoShortcut = exports.ToolEnabledGroup = exports.ToolController = exports.BaseTool = exports.InputMapper = void 0;
+var InputMapper_1 = require("./InputFilter/InputMapper");
+Object.defineProperty(exports, "InputMapper", { enumerable: true, get: function () { return __importDefault(InputMapper_1).default; } });
 var BaseTool_1 = require("./BaseTool");
@@ -9,0 +11,0 @@ Object.defineProperty(exports, "BaseTool", { enumerable: true, get: function () { return __importDefault(BaseTool_1).default; } });

dist/cjs/tools/PanZoom.js

@@ -436,3 +436,3 @@ "use strict";
         scale = 1 / scale;
-        // Work around an issue that seems to be related to rotation matricies losing precision on inversion.
+        // Work around an issue that seems to be related to rotation matrices losing precision on inversion.
         // TODO: Figure out why and implement a better solution.
@@ -439,0 +439,0 @@ if (rotation !== 0) {

dist/cjs/tools/Pen.d.ts

@@ -14,2 +14,8 @@ import { Color4 } from '@js-draw/math';
 }
+/**
+ * A tool that allows drawing shapes and freehand lines.
+ *
+ * To change the type of shape drawn by the pen (e.g. to switch to the rectangle
+ * pen type), see {@link setStrokeFactory}.
+ */
 export default class Pen extends BaseTool {
@@ -46,2 +52,9 @@ private editor;
     setThickness(thickness: number): void;
+    /**
+     * Changes the type of stroke created by the pen. The given `factory` can be one of the built-in
+     * stroke factories (e.g. {@link makeFreehandLineBuilder}) or a custom stroke factory.
+     *
+     * Example:
+     * [[include:doc-pages/inline-examples/changing-pen-types.md]]
+     */
     setStrokeFactory(factory: ComponentBuilderFactory): void;
@@ -48,0 +61,0 @@ setHasStabilization(hasStabilization: boolean): void;

dist/cjs/tools/Pen.js

@@ -40,2 +40,8 @@ "use strict";
 const StationaryPenDetector_1 = __importStar(require("./util/StationaryPenDetector"));
+/**
+ * A tool that allows drawing shapes and freehand lines.
+ *
+ * To change the type of shape drawn by the pen (e.g. to switch to the rectangle
+ * pen type), see {@link setStrokeFactory}.
+ */
 class Pen extends BaseTool_1.default {
@@ -276,2 +282,9 @@ constructor(editor, description, style) {
     }
+    /**
+     * Changes the type of stroke created by the pen. The given `factory` can be one of the built-in
+     * stroke factories (e.g. {@link makeFreehandLineBuilder}) or a custom stroke factory.
+     *
+     * Example:
+     * [[include:doc-pages/inline-examples/changing-pen-types.md]]
+     */
     setStrokeFactory(factory) {
@@ -278,0 +291,0 @@ if (factory !== this.style.factory) {

dist/cjs/util/cloneElementWithStyles.js

@@ -15,3 +15,3 @@ "use strict";
             const propertyValue = originalComputedStyle.getPropertyValue(propertyName);
-            clonedElement.style.setProperty(propertyName, propertyValue);
+            clonedElement.style?.setProperty(propertyName, propertyValue);
         }
@@ -18,0 +18,0 @@ for (let i = 0; i < originalElement.children.length; i++) {

dist/cjs/version.js

@@ -9,3 +9,3 @@ "use strict";
 exports.default = {
-    number: '1.22.0',
+    number: '1.23.1',
 };

dist/cjs/Viewport.d.ts

@@ -56,3 +56,3 @@ import Command from './commands/Command';
      *
-     * @see {@link getGridSize} and {@link getScaleFactorToNearestPowerOf}.
+     * @see {@link getGridSize}.
      */
@@ -59,0 +59,0 @@ snapToGrid(canvasPos: Point2): {

dist/cjs/Viewport.js

@@ -110,3 +110,3 @@ "use strict";
      *
-     * @see {@link getGridSize} and {@link getScaleFactorToNearestPowerOf}.
+     * @see {@link getGridSize}.
      */
@@ -113,0 +113,0 @@ snapToGrid(canvasPos) {

dist/mjs/components/AbstractComponent.d.ts

@@ -125,3 +125,3 @@ import SerializableCommand from '../commands/SerializableCommand';
      * The transformed component is also moved to the top (use
-     * {@link AbstractComponent.setZIndexAndTransformBy} to avoid this behavior).
+     * {@link AbstractComponent#setZIndexAndTransformBy} to avoid this behavior).
      */
@@ -128,0 +128,0 @@ transformBy(affineTransfm: Mat33): SerializableCommand;

dist/mjs/components/builders/ArrowBuilder.d.ts

@@ -8,3 +8,3 @@ import { Rect2 } from '@js-draw/math';
 /**
- * Creates a stroke builder that generates arrows circles.
+ * Creates a stroke builder that generates arrows.
  *
@@ -11,0 +11,0 @@ * Example:

dist/mjs/Editor.d.ts

@@ -414,5 +414,3 @@ import EditorImage from './image/EditorImage';
      *
-     * 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)`.
      *
@@ -419,0 +417,0 @@ * @example

dist/mjs/image/EditorImage.d.ts

@@ -25,3 +25,16 @@ import AbstractRenderer from '../rendering/renderers/AbstractRenderer';
 /**
- * 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]]
  */
@@ -44,6 +57,9 @@ export default 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]]
      */
@@ -68,5 +84,8 @@ render(renderer: AbstractRenderer, viewport: Viewport | null): 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}.
      */
@@ -76,3 +95,7 @@ getAllElements(): AbstractComponent[];
     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[];
@@ -79,0 +102,0 @@ /** Called whenever (just after) an element is completely removed. @internal */

dist/mjs/rendering/renderers/CanvasRenderer.d.ts

@@ -10,27 +10,4 @@ import { Mat33, Rect2, Point2, Vec2, Vec3 } from '@js-draw/math';
  *
- * @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]]
  */
@@ -37,0 +14,0 @@ export default class CanvasRenderer extends AbstractRenderer {

dist/mjs/toolbar/AbstractToolbar.d.ts

@@ -113,2 +113,21 @@ import Editor from '../Editor';
      * @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!');
+     * });
      */
@@ -115,0 +134,0 @@ addActionButton(title: string | ActionButtonIcon, command: () => void, options?: ToolbarActionButtonOptions | boolean): BaseWidget;

dist/mjs/toolbar/IconProvider.d.ts

@@ -83,5 +83,9 @@ import { Color4 } from '@js-draw/math';
      * `<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;
@@ -88,0 +92,0 @@ };

dist/mjs/toolbar/widgets/BaseWidget.d.ts

@@ -101,3 +101,3 @@ import Editor from '../../Editor';
      * Remove this. This allows the widget to be added to a toolbar again
-     * in the future using {@link addTo}.
+     * in the future using `addTo`.
      */
@@ -104,0 +104,0 @@ remove(): void;

dist/mjs/tools/lib.d.ts

@@ -0,1 +1,2 @@
+export { default as InputMapper } from './InputFilter/InputMapper';
 export { default as BaseTool } from './BaseTool';
@@ -2,0 +3,0 @@ export { default as ToolController } from './ToolController';

dist/mjs/tools/Pen.d.ts

@@ -14,2 +14,8 @@ import { Color4 } from '@js-draw/math';
 }
+/**
+ * A tool that allows drawing shapes and freehand lines.
+ *
+ * To change the type of shape drawn by the pen (e.g. to switch to the rectangle
+ * pen type), see {@link setStrokeFactory}.
+ */
 export default class Pen extends BaseTool {
@@ -46,2 +52,9 @@ private editor;
     setThickness(thickness: number): void;
+    /**
+     * Changes the type of stroke created by the pen. The given `factory` can be one of the built-in
+     * stroke factories (e.g. {@link makeFreehandLineBuilder}) or a custom stroke factory.
+     *
+     * Example:
+     * [[include:doc-pages/inline-examples/changing-pen-types.md]]
+     */
     setStrokeFactory(factory: ComponentBuilderFactory): void;
@@ -48,0 +61,0 @@ setHasStabilization(hasStabilization: boolean): void;

dist/mjs/Viewport.d.ts

@@ -56,3 +56,3 @@ import Command from './commands/Command';
      *
-     * @see {@link getGridSize} and {@link getScaleFactorToNearestPowerOf}.
+     * @see {@link getGridSize}.
      */
@@ -59,0 +59,0 @@ snapToGrid(canvasPos: Point2): {

package.json

 {
 	"name": "js-draw",
-	"version": "1.22.0",
+	"version": "1.23.1",
 	"description": "Draw pictures using a pen, touchscreen, or mouse! JS-draw is a drawing library for JavaScript and TypeScript. ",
@@ -67,7 +67,7 @@ "types": "./dist/mjs/lib.d.ts",
 	"dependencies": {
-		"@js-draw/math": "^1.22.0",
+		"@js-draw/math": "^1.23.1",
 		"@melloware/coloris": "0.22.0"
 	},
 	"devDependencies": {
-		"@js-draw/build-tool": "^1.22.0",
+		"@js-draw/build-tool": "^1.23.1",
 		"@types/jest": "29.5.5",
@@ -90,3 +90,3 @@ "@types/jsdom": "21.1.3"
 	],
-	"gitHead": "c922cf6e44d078133100e01383ba1bacdebe01bd"
+	"gitHead": "e0bb3336d5f3a94533c823906778d39a4880f4cf"
 }

README.md

@@ -417,2 +417,2 @@ <div align="center">
 - [A material icon theme for js-draw](https://personalizedrefrigerator.github.io/js-draw/typedoc/modules/_js_draw_material_icons.html#md:js-drawmaterial-icons)
-- [More documentation](https://personalizedrefrigerator.github.io/js-draw/typedoc/modules/Additional_Documentation.html)
+- [More documentation](https://personalizedrefrigerator.github.io/js-draw/typedoc/modules/Guides.html)

No alert changes

Improved metrics

Total package byte prevSize

4443776

increased by0.38%

Number of package files

870

increased by0.46%

Lines of code

62763

increased by0.48%

Dependency changes

• Updated@js-draw/math@^1.23.1