js-draw 1.27.2 → 1.28.0

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

@@ -15,6 +15,9 @@ type FromViewportOptions = {
      */
     useViewBoxForPositioning?: boolean;
 };
+type DrawWithSVGParentContext = {
+    sanitize: boolean;
+};
 /**
  * Renders onto an `SVGElement`.
  *
@@ -57,7 +60,22 @@ export default class SVGRenderer extends AbstractRenderer {
     protected traceCubicBezierCurve(_controlPoint1: Point2, _controlPoint2: Point2, _endPoint: Point2): void;
     protected traceQuadraticBezierCurve(_controlPoint: Point2, _endPoint: Point2): void;
     drawPoints(...points: Point2[]): void;
+    /**
+     * Adds a **copy** of the given element directly to the container
+     * SVG element, **without applying transforms**.
+     *
+     * If `sanitize` is enabled, this does nothing.
+     */
     drawSVGElem(elem: SVGElement): void;
+    /**
+     * Allows rendering directly to the underlying SVG element. Rendered
+     * content is added to a `<g>` element that's passed as `parent` to `callback`.
+     *
+     * **Note**: Unlike {@link drawSVGElem}, this method can be used even if `sanitize` is `true`.
+     * In this case, it's the responsibility of `callback` to ensure that everything added
+     * to `parent` is safe to render.
+     */
+    drawWithSVGParent(callback: (parent: SVGGElement, context: DrawWithSVGParentContext) => void): void;
     isTooSmallToRender(_rect: Rect2): boolean;
     /**
      * Creates a new SVG element and `SVGRenerer` with `width`, `height`, `viewBox`,

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

@@ -347,7 +347,12 @@ class SVGRenderer extends AbstractRenderer_1.default {
             this.elem.appendChild(elem);
         });
     }
-    // Renders a **copy** of the given element.
+    /**
+     * Adds a **copy** of the given element directly to the container
+     * SVG element, **without applying transforms**.
+     *
+     * If `sanitize` is enabled, this does nothing.
+     */
     drawSVGElem(elem) {
         if (this.sanitize) {
             return;
@@ -361,6 +366,21 @@ class SVGRenderer extends AbstractRenderer_1.default {
         this.elem.appendChild(elemToDraw);
         this.objectElems?.push(elemToDraw);
     }
+    /**
+     * Allows rendering directly to the underlying SVG element. Rendered
+     * content is added to a `<g>` element that's passed as `parent` to `callback`.
+     *
+     * **Note**: Unlike {@link drawSVGElem}, this method can be used even if `sanitize` is `true`.
+     * In this case, it's the responsibility of `callback` to ensure that everything added
+     * to `parent` is safe to render.
+     */
+    drawWithSVGParent(callback) {
+        const parent = document.createElementNS(svgNameSpace, 'g');
+        this.transformFrom(math_1.Mat33.identity, parent, true);
+        callback(parent, { sanitize: this.sanitize });
+        this.elem.appendChild(parent);
+        this.objectElems?.push(parent);
+    }
     isTooSmallToRender(_rect) {
         return false;
     }

package/dist/cjs/toolbar/utils/HelpDisplay.js

@@ -139,6 +139,8 @@ const createHelpPage = (helpItems, onItemClick, onBackgroundClick, context) => {
                 clonedElement.style.margin = '0';
                 const clonedElementContainer = document.createElement('div');
                 clonedElementContainer.classList.add('cloned-element-container');
+                clonedElementContainer.role = 'group';
+                clonedElementContainer.ariaLabel = context.localization.helpControlsAccessibilityLabel;
                 clonedElementContainer.style.position = 'absolute';
                 clonedElementContainer.style.left = `${targetBBox.topLeft.x}px`;
                 clonedElementContainer.style.top = `${targetBBox.topLeft.y}px`;
@@ -157,11 +159,11 @@ const createHelpPage = (helpItems, onItemClick, onBackgroundClick, context) => {
     };
     const onItemChange = () => {
         const helpTextElement = document.createElement('div');
-        helpTextElement.innerText = currentItem?.helpText ?? '';
+        helpTextElement.textContent = currentItem?.helpText ?? '';
         // For tests
         helpTextElement.classList.add('current-item-help');
         const navigationHelpElement = document.createElement('div');
-        navigationHelpElement.innerText = context.localization.helpScreenNavigationHelp;
+        navigationHelpElement.textContent = context.localization.helpScreenNavigationHelp;
         navigationHelpElement.classList.add('navigation-help');
         textLabel.replaceChildren(helpTextElement, ...(currentItemIndex === 0 ? [navigationHelpElement] : []));
         updateClonedElementStates();
@@ -278,8 +280,8 @@ class HelpDisplay {
             navigationButtonContainer.classList.add('navigation-buttons');
             const nextButton = document.createElement('button');
             const previousButton = document.createElement('button');
-            nextButton.innerText = this.context.localization.next;
-            previousButton.innerText = this.context.localization.previous;
+            nextButton.textContent = this.context.localization.next;
+            previousButton.textContent = this.context.localization.previous;
             nextButton.classList.add('next');
             previousButton.classList.add('previous');
             const updateButtonVisibility = () => {

package/dist/cjs/toolbar/utils/localization.d.ts

@@ -1,6 +1,7 @@
 export interface ToolbarUtilsLocalization {
     help: string;
     helpScreenNavigationHelp: string;
+    helpControlsAccessibilityLabel: string;
     helpHidden: string;
     next: string;
     previous: string;

package/dist/cjs/toolbar/utils/localization.js

@@ -8,4 +8,5 @@ exports.defaultToolbarUtilsLocalization = {
     previous: 'Previous',
     close: 'Close',
     helpScreenNavigationHelp: 'Click on a control for more information.',
+    helpControlsAccessibilityLabel: 'Controls: Activate a control to show help.',
 };

package/dist/cjs/toolbar/widgets/DocumentPropertiesWidget.js

@@ -100,7 +100,7 @@ class DocumentPropertiesWidget extends BaseWidget_1.default {
     setBackgroundType(backgroundType) {
         const prevBackgroundColor = this.editor.estimateBackgroundColor();
         const newBackground = new BackgroundComponent_1.default(backgroundType, prevBackgroundColor);
-        const addBackgroundCommand = this.editor.image.addElement(newBackground);
+        const addBackgroundCommand = this.editor.image.addComponent(newBackground);
         return (0, uniteCommands_1.default)([this.removeBackgroundComponents(), addBackgroundCommand]);
     }
     /** Returns the type of the topmost background component */

package/dist/cjs/toolbar/widgets/InsertImageWidget/InsertImageWidget.js

@@ -275,7 +275,7 @@ class InsertImageWidget extends BaseWidget_1.default {
                     const widthAdjustTransform = math_1.Mat33.scaling2D(originalWidth / newWidth);
                     const commands = [];
                     for (const component of newComponents) {
-                        commands.push(EditorImage_1.default.addElement(component), component.transformBy(originalTransform.rightMul(widthAdjustTransform)), component.setZIndex(editingImage.getZIndex()));
+                        commands.push(EditorImage_1.default.addComponent(component), component.transformBy(originalTransform.rightMul(widthAdjustTransform)), component.setZIndex(editingImage.getZIndex()));
                     }
                     this.editor.dispatch((0, uniteCommands_1.default)([...commands, eraseCommand]));
                     selectionTools[0]?.setSelection(newComponents);

package/dist/cjs/toolbar/widgets/components/makeGridSelector.js

@@ -22,7 +22,7 @@ labelText, defaultId, choices) => {
     outerContainer.classList.add(`${constants_1.toolbarCSSPrefix}grid-selector`);
     const selectedValue = ReactiveValue_1.MutableReactiveValue.fromInitialValue(defaultId);
     const menuContainer = document.createElement('div');
-    menuContainer.setAttribute('role', 'menu');
+    menuContainer.role = 'group';
     menuContainer.id = `${constants_1.toolbarCSSPrefix}-grid-select-id-${idCounter++}`;
     (0, stopPropagationOfScrollingWheelEvents_1.default)(menuContainer);
     const label = document.createElement('label');

package/dist/cjs/tools/Eraser.js

@@ -145,7 +145,7 @@ class Eraser extends BaseTool_1.default {
         const line = new math_1.LineSegment2(this.lastPoint, currentPoint);
         const region = math_1.Rect2.union(line.bbox, eraserRect);
         const intersectingElems = this.editor.image
-            .getElementsIntersectingRegion(region)
+            .getComponentsIntersecting(region)
             .filter((component) => {
             return component.intersects(line) || component.intersectsRect(eraserRect);
         });
@@ -184,7 +184,7 @@ class Eraser extends BaseTool_1.default {
                 toAdd.push(...targetElem.withRegionErased(erasePath, this.editor.viewport));
             }
             const eraseCommand = new Erase_1.default(toErase);
-            const newAddCommands = toAdd.map((elem) => EditorImage_1.default.addElement(elem));
+            const newAddCommands = toAdd.map((elem) => EditorImage_1.default.addComponent(elem));
             eraseCommand.apply(this.editor);
             newAddCommands.forEach((command) => command.apply(this.editor));
             const finalToErase = [];
@@ -240,7 +240,7 @@ class Eraser extends BaseTool_1.default {
                     this.toRemove = this.toRemove.filter((other) => other !== item);
                 }
             }
-            commands.push(...[...this.toAdd].map((a) => EditorImage_1.default.addElement(a)));
+            commands.push(...[...this.toAdd].map((a) => EditorImage_1.default.addComponent(a)));
             this.addCommands = [];
         }
         if (this.eraseCommands.length > 0) {

package/dist/cjs/tools/FindTool.js

@@ -27,7 +27,7 @@ class FindTool extends BaseTool_1.default {
     }
     getMatches(searchFor) {
         const lowerSearchFor = searchFor.toLocaleLowerCase();
-        const matchingComponents = this.editor.image.getAllElements().filter((component) => {
+        const matchingComponents = this.editor.image.getAllComponents().filter((component) => {
             let text = '';
             if (component instanceof TextComponent_1.default) {
                 text = component.getText();

package/dist/cjs/tools/PasteHandler.js

@@ -76,7 +76,10 @@ class PasteHandler extends BaseTool_1.default {
     async doSVGPaste(data) {
         this.editor.showLoadingWarning(0);
         try {
-            const loader = SVGLoader_1.default.fromString(data, true);
+            const loader = SVGLoader_1.default.fromString(data, {
+                sanitize: true,
+                plugins: this.editor.getCurrentSettings().svg?.loaderPlugins ?? [],
+            });
             const components = [];
             await loader.start((component) => {
                 components.push(component);

package/dist/cjs/tools/Pen.js

@@ -251,7 +251,7 @@ class Pen extends BaseTool_1.default {
                     this.editor.announceForAccessibility(this.editor.localization.autocorrectedTo(stroke.description(this.editor.localization)));
                 }
                 const canFlatten = true;
-                const action = EditorImage_1.default.addElement(stroke, canFlatten);
+                const action = EditorImage_1.default.addComponent(stroke, canFlatten);
                 this.editor.dispatch(action);
             }
             else {

package/dist/cjs/tools/SelectionTool/SelectAllShortcutHandler.js

@@ -22,7 +22,7 @@ class SelectAllShortcutHandler extends BaseTool_1.default {
             if (selectionTools.length > 0) {
                 const selectionTool = selectionTools[0];
                 selectionTool.setEnabled(true);
-                selectionTool.setSelection(this.editor.image.getAllElements());
+                selectionTool.setSelection(this.editor.image.getAllComponents());
                 return true;
             }
         }

package/dist/cjs/tools/SelectionTool/Selection.js

@@ -53,6 +53,8 @@ const types_1 = require("./types");
 const EditorImage_1 = __importDefault(require("../../image/EditorImage"));
 const uniteCommands_1 = __importDefault(require("../../commands/uniteCommands"));
 const SelectionMenuShortcut_1 = __importDefault(require("./SelectionMenuShortcut"));
+const assertions_1 = require("../../util/assertions");
+const describeTransformation_1 = __importDefault(require("../../util/describeTransformation"));
 const updateChunkSize = 100;
 const maxPreviewElemCount = 500;
 // @internal
@@ -186,7 +188,7 @@ class Selection {
             return 0;
         }
         const selectedBottommostZIndex = this.selectedElems[0].getZIndex();
-        const visibleObjects = this.editor.image.getElementsIntersectingRegion(this.region);
+        const visibleObjects = this.editor.image.getComponentsIntersecting(this.region);
         const topMostVisibleZIndex = visibleObjects[visibleObjects.length - 1]?.getZIndex() ?? selectedBottommostZIndex;
         const deltaZIndex = topMostVisibleZIndex + 1 - selectedBottommostZIndex;
         return deltaZIndex;
@@ -205,13 +207,13 @@ class Selection {
         // z-index of the just-transformed commands.
         if (this.selectedElems.length > 0) {
             const deltaZIndex = this.getDeltaZIndexToMoveSelectionToTop();
-            transformPromise = this.editor.dispatch(new _a.ApplyTransformationCommand(this, selectedElems, fullTransform, deltaZIndex));
+            transformPromise = this.editor.dispatch(new _a.ApplyTransformationCommand(this, selectedElems, this.originalRegion.center, fullTransform, deltaZIndex));
         }
         return transformPromise;
     }
     /** Sends all selected elements to the bottom of the visible image. */
     sendToBack() {
-        const visibleObjects = this.editor.image.getElementsIntersectingRegion(this.editor.viewport.visibleRect);
+        const visibleObjects = this.editor.image.getComponentsIntersecting(this.editor.viewport.visibleRect);
         // VisibleObjects and selectedElems should both be sorted by z-index
         const lowestVisibleZIndex = visibleObjects[0]?.getZIndex() ?? 0;
         const highestSelectedZIndex = this.selectedElems[this.selectedElems.length - 1]?.getZIndex() ?? 0;
@@ -338,7 +340,7 @@ class Selection {
             // If we're making things visible and the selected object wasn't previously
             // visible,
             else if (!parent && this.removedFromImage[elem.getId()]) {
-                EditorImage_1.default.addElement(elem).apply(this.editor);
+                EditorImage_1.default.addComponent(elem).apply(this.editor);
                 this.removedFromImage[elem.getId()] = false;
                 delete this.removedFromImage[elem.getId()];
             }
@@ -476,14 +478,14 @@ class Selection {
             // Don't update the selection's focus when redoing/undoing
             const selectionToUpdate = null;
             const deltaZIndex = this.getDeltaZIndexToMoveSelectionToTop();
-            tmpApplyCommand = new _a.ApplyTransformationCommand(selectionToUpdate, this.selectedElems, this.transform, deltaZIndex);
+            tmpApplyCommand = new _a.ApplyTransformationCommand(selectionToUpdate, this.selectedElems, this.region.center, this.transform, deltaZIndex);
             // Transform to ensure that the duplicates are in the correct location
             await tmpApplyCommand.apply(this.editor);
             // Show items again
             this.addRemoveSelectionFromImage(true);
             // With the transformation applied, create the duplicates
             command = (0, uniteCommands_1.default)(this.selectedElems.map((elem) => {
-                return EditorImage_1.default.addElement(elem.clone());
+                return EditorImage_1.default.addComponent(elem.clone());
             }));
             // Move the selected objects back to the correct location.
             await tmpApplyCommand?.unapply(this.editor);
@@ -541,21 +543,31 @@ class Selection {
 _a = Selection;
 (() => {
     SerializableCommand_1.default.register('selection-tool-transform', (json, _editor) => {
+        const rawTransformArray = json.transform;
+        const rawCenterArray = json.selectionCenter ?? [0, 0];
+        const rawElementIds = json.elems ?? [];
+        (0, assertions_1.assertIsNumberArray)(rawTransformArray);
+        (0, assertions_1.assertIsNumberArray)(rawCenterArray);
+        (0, assertions_1.assertIsStringArray)(rawElementIds);
         // The selection box is lost when serializing/deserializing. No need to store box rotation
-        const fullTransform = new math_1.Mat33(...json.transform);
-        const elemIds = json.elems ?? [];
+        const fullTransform = new math_1.Mat33(...rawTransformArray);
+        const elemIds = rawElementIds;
         const deltaZIndex = parseInt(json.deltaZIndex ?? 0);
-        return new _a.ApplyTransformationCommand(null, elemIds, fullTransform, deltaZIndex);
+        const center = math_1.Vec2.of(rawCenterArray[0] ?? 0, rawCenterArray[1] ?? 0);
+        return new _a.ApplyTransformationCommand(null, elemIds, center, fullTransform, deltaZIndex);
     });
 })();
 Selection.ApplyTransformationCommand = class extends SerializableCommand_1.default {
     constructor(selection, 
     // If a `string[]`, selectedElems is a list of element IDs.
     selectedElems, 
+    // Information used to describe the transformation
+    selectionCenter, 
     // Full transformation used to transform elements.
     fullTransform, deltaZIndex) {
         super('selection-tool-transform');
         this.selection = selection;
+        this.selectionCenter = selectionCenter;
         this.fullTransform = fullTransform;
         this.deltaZIndex = deltaZIndex;
         const isIDList = (arr) => {
@@ -623,10 +635,11 @@ Selection.ApplyTransformationCommand = class extends SerializableCommand_1.defau
             elems: this.selectedElemIds,
             transform: this.fullTransform.toArray(),
             deltaZIndex: this.deltaZIndex,
+            selectionCenter: this.selectionCenter.asArray(),
         };
     }
     description(_editor, localizationTable) {
-        return localizationTable.transformedElements(this.selectedElemIds.length);
+        return localizationTable.transformedElements(this.selectedElemIds.length, (0, describeTransformation_1.default)(this.selectionCenter, this.fullTransform, false, localizationTable));
     }
 };
 exports.default = Selection;

package/dist/cjs/tools/SelectionTool/SelectionBuilders/LassoSelectionBuilder.js

@@ -38,7 +38,7 @@ class LassoSelectionBuilder extends SelectionBuilder_1.default {
     resolveInternal(image) {
         const path = this.previewPath();
         const lines = path.polylineApproximation();
-        const candidates = image.getElementsIntersectingRegion(path.bbox);
+        const candidates = image.getComponentsIntersecting(path.bbox);
         const componentIsInSelection = (component) => {
             if (path.closedContainsRect(component.getExactBBox())) {
                 return true;

package/dist/cjs/tools/SelectionTool/SelectionBuilders/RectSelectionBuilder.js

@@ -20,7 +20,7 @@ class RectSelectionBuilder extends SelectionBuilder_1.default {
         return math_1.Path.fromRect(this.rect);
     }
     resolveInternal(image) {
-        return image.getElementsIntersectingRegion(this.rect).filter((element) => {
+        return image.getComponentsIntersecting(this.rect).filter((element) => {
             // Filter out the case where the selection rectangle is completely contained
             // within the element (and does not intersect it).
             // This is useful, for example, if a very large stroke is used as the background

package/dist/cjs/tools/SelectionTool/SelectionBuilders/SelectionBuilder.js

@@ -22,7 +22,7 @@ class SelectionBuilder {
         if (isClick) {
             const searchRegionSize = viewport.visibleRect.maxDimension / 200;
             const minSizeBox = path.bbox.grownBy(searchRegionSize);
-            components = image.getElementsIntersectingRegion(minSizeBox).filter((component) => {
+            components = image.getComponentsIntersecting(minSizeBox).filter((component) => {
                 return minSizeBox.containsRect(component.getBBox()) || component.intersectsRect(minSizeBox);
             });
             components = filterComponents(components);

package/dist/cjs/tools/SelectionTool/SelectionTool.js

@@ -259,7 +259,7 @@ class SelectionTool extends BaseTool_1.default {
             return true;
         }
         else if (shortcucts.matchesShortcut(keybindings_1.selectAllKeyboardShortcut, event)) {
-            this.setSelection(this.editor.image.getAllElements());
+            this.setSelection(this.editor.image.getAllComponents());
             return true;
         }
         else if (event.ctrlKey) {
@@ -462,7 +462,8 @@ class SelectionTool extends BaseTool_1.default {
         this.handleOverlay.style.display = enabled ? 'block' : 'none';
         if (enabled) {
             this.handleOverlay.tabIndex = 0;
-            this.handleOverlay.setAttribute('aria-label', this.editor.localization.selectionToolKeyboardShortcuts);
+            this.handleOverlay.role = 'group';
+            this.handleOverlay.ariaLabel = this.editor.localization.selectionToolKeyboardShortcuts;
         }
         else {
             this.handleOverlay.tabIndex = -1;

package/dist/cjs/tools/SoundUITool.js

@@ -156,7 +156,7 @@ class SoundUITool extends BaseTool_1.default {
         this.soundFeedback?.setColor(this.editor.display.getColorAt(current.screenPos) ?? math_1.Color4.black);
         const pointerMotionLine = new math_1.LineSegment2(this.lastPointerPos, current.canvasPos);
         const collisions = this.editor.image
-            .getElementsIntersectingRegion(pointerMotionLine.bbox)
+            .getComponentsIntersecting(pointerMotionLine.bbox)
             .filter((component) => component.intersects(pointerMotionLine));
         this.lastPointerPos = current.canvasPos;
         if (collisions.length > 0) {

package/dist/cjs/tools/TextTool.js

@@ -103,7 +103,7 @@ class TextTool extends BaseTool_1.default {
             const scrollCorrectionCanvas = this.editor.viewport.screenToCanvasTransform.transformVec3(scrollCorrectionScreen);
             const scrollTransform = math_1.Mat33.translation(scrollCorrectionCanvas);
             const textComponent = TextComponent_1.default.fromLines(content.split('\n'), scrollTransform.rightMul(this.contentTransform.get()), this.textStyle);
-            const action = EditorImage_1.default.addElement(textComponent);
+            const action = EditorImage_1.default.addComponent(textComponent);
             if (this.removeExistingCommand) {
                 // Unapply so that `removeExistingCommand` can be added to the undo stack.
                 this.removeExistingCommand.unapply(this.editor);
@@ -213,7 +213,7 @@ class TextTool extends BaseTool_1.default {
             const canvasPos = current.canvasPos;
             const halfTestRegionSize = math_1.Vec2.of(4, 4).times(this.editor.viewport.getSizeOfPixelOnCanvas());
             const testRegion = math_1.Rect2.fromCorners(canvasPos.minus(halfTestRegionSize), canvasPos.plus(halfTestRegionSize));
-            const targetNodes = this.editor.image.getElementsIntersectingRegion(testRegion);
+            const targetNodes = this.editor.image.getComponentsIntersecting(testRegion);
             let targetTextNodes = targetNodes.filter((node) => node instanceof TextComponent_1.default);
             // Don't try to edit text nodes that contain the viewport (this allows us
             // to zoom in on text nodes and add text on top of them.)

package/dist/cjs/util/assertions.d.ts

@@ -15,11 +15,17 @@ export declare function assertUnreachable(key: never): never;
  * ```
  */
 export declare function assertIsNumber(value: unknown, allowNaN?: boolean): asserts value is number;
+/** Throws an `Error` if the given `value` is not a `string`. */
+export declare function assertIsString(value: unknown): asserts value is string;
 export declare function assertIsArray(values: unknown): asserts values is unknown[];
 /**
  * Throws if any of `values` is not of type number.
  */
 export declare function assertIsNumberArray(values: unknown, allowNaN?: boolean): asserts values is number[];
+/**
+ * Throws if any of `values` is not of type `string`.
+ */
+export declare function assertIsStringArray(values: unknown): asserts values is string[];
 /**
  * Throws an exception if `typeof value` is not a boolean.
  */

package/dist/cjs/util/assertions.js

@@ -4,8 +4,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assertUnreachable = assertUnreachable;
 exports.assertIsNumber = assertIsNumber;
+exports.assertIsString = assertIsString;
 exports.assertIsArray = assertIsArray;
 exports.assertIsNumberArray = assertIsNumberArray;
+exports.assertIsStringArray = assertIsStringArray;
 exports.assertIsBoolean = assertIsBoolean;
 exports.assertTruthy = assertTruthy;
 exports.assertIsObject = assertIsObject;
@@ -33,6 +35,12 @@ function assertIsNumber(value, allowNaN = false) {
         throw new Error('Given value is not a number');
     }
 }
+/** Throws an `Error` if the given `value` is not a `string`. */
+function assertIsString(value) {
+    if (typeof value !== 'string') {
+        throw new Error('Given value is not a string');
+    }
+}
 function assertIsArray(values) {
     if (!Array.isArray(values)) {
         throw new Error('Asserting isArray: Given entity is not an array');
@@ -48,6 +56,16 @@ function assertIsNumberArray(values, allowNaN = false) {
         assertIsNumber(value, allowNaN);
     }
 }
+/**
+ * Throws if any of `values` is not of type `string`.
+ */
+function assertIsStringArray(values) {
+    assertIsArray(values);
+    assertIsNumber(values.length);
+    for (const value of values) {
+        assertIsString(value);
+    }
+}
 /**
  * Throws an exception if `typeof value` is not a boolean.
  */

package/dist/cjs/util/describeTransformation.d.ts

@@ -0,0 +1,12 @@
+import { Mat33, Vec2 } from '@js-draw/math';
+interface Descriptions {
+    zoomedIn: string;
+    zoomedOut: string;
+    movedLeft: string;
+    movedRight: string;
+    movedUp: string;
+    movedDown: string;
+    rotatedBy: (deg: number) => string;
+}
+declare const describeTransformation: (origin: Vec2, transform: Mat33, invertDirections: boolean, localizationTable: Descriptions) => string;
+export default describeTransformation;

package/dist/cjs/util/describeTransformation.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const math_1 = require("@js-draw/math");
+const describeTransformation = (
+// The location of the object before being transformed
+origin, 
+// The transformation
+transform, 
+// If true, moving the object right, for example, reads as "moved left"
+invertDirections, localizationTable) => {
+    // Describe the transformation's affect on the viewport (note that transformation transforms
+    // the **elements** within the viewport). Assumes the transformation only does rotation/scale/translation.
+    const linearTransformedVec = transform.transformVec3(math_1.Vec2.unitX);
+    const affineTransformedVec = transform.transformVec2(origin);
+    const scale = linearTransformedVec.magnitude();
+    const clockwiseRotation = -(180 / Math.PI) * linearTransformedVec.angle();
+    const translation = affineTransformedVec.minus(origin);
+    const result = [];
+    if (scale > 1.2) {
+        result.push(localizationTable.zoomedIn);
+    }
+    else if (scale < 0.8) {
+        result.push(localizationTable.zoomedOut);
+    }
+    if (Math.floor(Math.abs(clockwiseRotation)) > 0) {
+        const roundedRotation = Math.round(invertDirections ? -clockwiseRotation : clockwiseRotation);
+        result.push(localizationTable.rotatedBy(roundedRotation));
+    }
+    const minTranslation = 1e-4;
+    if (translation.x > minTranslation) {
+        result.push(invertDirections ? localizationTable.movedLeft : localizationTable.movedRight);
+    }
+    else if (translation.x < -minTranslation) {
+        result.push(invertDirections ? localizationTable.movedRight : localizationTable.movedLeft);
+    }
+    if (translation.y < -minTranslation) {
+        result.push(invertDirections ? localizationTable.movedDown : localizationTable.movedUp);
+    }
+    else if (translation.y > minTranslation) {
+        result.push(invertDirections ? localizationTable.movedUp : localizationTable.movedDown);
+    }
+    return result.join('; ');
+};
+exports.default = describeTransformation;

package/dist/cjs/version.js

@@ -7,5 +7,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 exports.default = {
     // Note: Auto-updated by prebuild.js:
-    number: '1.27.2',
+    number: '1.28.0',
 };

package/dist/mjs/Editor.d.ts

@@ -7,6 +7,7 @@ import UndoRedoHistory from './UndoRedoHistory';
 import Viewport from './Viewport';
 import { Point2, Vec2, Color4, Mat33, Rect2 } from '@js-draw/math';
 import Display, { RenderingMode } from './rendering/Display';
+import { SVGLoaderPlugin } from './SVGLoader/SVGLoader';
 import Pointer from './Pointer';
 import { EditorLocalization } from './localization';
 import IconProvider from './toolbar/IconProvider';
@@ -131,6 +132,10 @@ export interface EditorSettings {
         /** Called to write data to the clipboard. Keys in `data` are MIME types. Values are the data associated with that type. */
         write(data: Map<string, Blob | Promise<Blob> | string>): void | Promise<void>;
     } | null;
+    svg: {
+        /** Plugins that create custom components while loading with {@link Editor.loadFromSVG}. */
+        loaderPlugins?: SVGLoaderPlugin[];
+    } | null;
 }
 /**
  * The main entrypoint for the full editor.
@@ -184,10 +189,10 @@ export declare class Editor {
      * const stroke = new Stroke([
      *   pathToRenderable(Path.fromString('M0,0 L100,100 L300,30 z'), { fill: Color4.red }),
      * ]);
-     * const addElementCommand = editor.image.addElement(stroke);
+     * const addComponentCommand = editor.image.addComponent(stroke);
      *
      * // Add the stroke to the editor
-     * editor.dispatch(addElementCommand);
+     * editor.dispatch(addComponentCommand);
      * ```
      */
     readonly image: EditorImage;

package/dist/mjs/Editor.mjs

@@ -120,6 +120,9 @@ export class Editor {
             image: {
                 showImagePicker: settings.image?.showImagePicker ?? undefined,
             },
+            svg: {
+                loaderPlugins: settings.svg?.loaderPlugins ?? [],
+            },
             clipboardApi: settings.clipboardApi ?? null,
         };
         // Validate settings
@@ -1019,7 +1022,7 @@ export class Editor {
         const commands = [];
         for (const component of components) {
             // To allow deserialization, we need to add first, then transform.
-            commands.push(EditorImage.addElement(component));
+            commands.push(EditorImage.addComponent(component));
             commands.push(component.transformBy(transfm));
         }
         const applyChunkSize = 100;
@@ -1099,7 +1102,7 @@ export class Editor {
         const originalBackgrounds = this.image.getBackgroundComponents();
         const eraseBackgroundCommand = new Erase(originalBackgrounds);
         await loader.start(async (component) => {
-            await this.dispatchNoAnnounce(EditorImage.addElement(component));
+            await this.dispatchNoAnnounce(EditorImage.addComponent(component));
         }, (countProcessed, totalToProcess) => {
             if (countProcessed % 500 === 0) {
                 this.showLoadingWarning(countProcessed / totalToProcess);
@@ -1173,7 +1176,7 @@ export class Editor {
         const fillsScreen = style.autoresize ?? originalFillsScreen;
         if (backgroundType !== BackgroundType.None) {
             const newBackground = new BackgroundComponent(backgroundType, backgroundColor);
-            commands.push(EditorImage.addElement(newBackground));
+            commands.push(EditorImage.addComponent(newBackground));
         }
         if (fillsScreen !== originalFillsScreen) {
             commands.push(this.image.setAutoresizeEnabled(fillsScreen));
@@ -1199,7 +1202,7 @@ export class Editor {
                 ? BackgroundType.None
                 : BackgroundType.SolidColor;
             background = new BackgroundComponent(backgroundType, color);
-            return this.image.addElement(background);
+            return this.image.addComponent(background);
         }
         else {
             return background.updateStyle({ color });
@@ -1248,7 +1251,10 @@ export class Editor {
      * ```
      */
     async loadFromSVG(svgData, sanitize = false) {
-        const loader = SVGLoader.fromString(svgData, sanitize);
+        const loader = SVGLoader.fromString(svgData, {
+            sanitize,
+            plugins: this.getCurrentSettings().svg?.loaderPlugins,
+        });
         await this.loadFrom(loader);
     }
     /**