js-draw 1.16.1 → 1.18.0

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

@@ -8,6 +8,7 @@ const math_1 = require("@js-draw/math");
 const types_1 = require("../../types");
 const Viewport_1 = __importDefault(require("../../Viewport"));
 const BaseTool_1 = __importDefault(require("../BaseTool"));
+const CanvasRenderer_1 = __importDefault(require("../../rendering/renderers/CanvasRenderer"));
 const SVGRenderer_1 = __importDefault(require("../../rendering/renderers/SVGRenderer"));
 const Selection_1 = __importDefault(require("./Selection"));
 const TextComponent_1 = __importDefault(require("../../components/TextComponent"));
@@ -376,19 +377,37 @@ class SelectionTool extends BaseTool_1.default {
             return false;
         }
         const exportViewport = new Viewport_1.default(() => { });
-        exportViewport.updateScreenSize(math_1.Vec2.of(bbox.w, bbox.h));
-        exportViewport.resetTransform(math_1.Mat33.translation(bbox.topLeft.times(-1)));
-        const sanitize = true;
-        const { element: svgExportElem, renderer: svgRenderer } = SVGRenderer_1.default.fromViewport(exportViewport, sanitize);
+        const selectionScreenSize = this.selectionBox.getScreenRegion().size.times(this.editor.display.getDevicePixelRatio());
+        // Update the viewport to have screen size roughly equal to the size of the selection box
+        let scaleFactor = selectionScreenSize.maximumEntryMagnitude() / (bbox.size.maximumEntryMagnitude() || 1);
+        // Round to a nearby power of two
+        scaleFactor = Math.pow(2, Math.ceil(Math.log2(scaleFactor)));
+        exportViewport.updateScreenSize(bbox.size.times(scaleFactor));
+        exportViewport.resetTransform(math_1.Mat33.scaling2D(scaleFactor)
+            // Move the selection onto the screen
+            .rightMul(math_1.Mat33.translation(bbox.topLeft.times(-1))));
+        const { element: svgExportElem, renderer: svgRenderer } = SVGRenderer_1.default.fromViewport(exportViewport, { sanitize: true, useViewBoxForPositioning: true });
+        const { element: canvas, renderer: canvasRenderer } = CanvasRenderer_1.default.fromViewport(exportViewport, { maxCanvasDimen: 4096 });
         const text = [];
         for (const elem of selectedElems) {
             elem.render(svgRenderer);
+            elem.render(canvasRenderer);
             if (elem instanceof TextComponent_1.default) {
                 text.push(elem.getText());
             }
         }
         event.setData('image/svg+xml', svgExportElem.outerHTML);
         event.setData('text/html', svgExportElem.outerHTML);
+        event.setData('image/png', new Promise((resolve, reject) => {
+            canvas.toBlob((blob) => {
+                if (blob) {
+                    resolve(blob);
+                }
+                else {
+                    reject('Failed to convert canvas to blob.');
+                }
+            }, 'image/png');
+        }));
         if (text.length > 0) {
             event.setData('text/plain', text.join('\n'));
         }

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

@@ -28,7 +28,7 @@ class ToPointerAutoscroller {
             return math_1.Vec2.zero;
         }
         const closestEdgePoint = autoscrollBoundary.getClosestPointOnBoundaryTo(screenPoint);
-        const distToEdge = closestEdgePoint.minus(screenPoint).magnitude();
+        const distToEdge = closestEdgePoint.distanceTo(screenPoint);
         const toEdge = closestEdgePoint.minus(screenPoint);
         // Go faster for points further away from the boundary.
         const maximumScaleFactor = 1.25;

package/dist/cjs/tools/ToolController.d.ts

@@ -12,6 +12,12 @@ export default class ToolController implements InputEventListener {
     private isEditorReadOnly;
     /** @internal */
     constructor(editor: Editor, localization: ToolLocalization);
+    /**
+     * Replaces the current set of tools with `tools`. This should only be done before
+     * the creation of the app's toolbar (if using `AbstractToolbar`).
+     *
+     * If no `primaryToolGroup` is given, an empty one will be created.
+     */
     setTools(tools: BaseTool[], primaryToolGroup?: ToolEnabledGroup): void;
     /**
      * Add a tool that acts like one of the primary tools (only one primary tool can be enabled at a time).
@@ -22,7 +28,17 @@ export default class ToolController implements InputEventListener {
      */
     addPrimaryTool(tool: BaseTool): void;
     getPrimaryTools(): BaseTool[];
-    addTool(tool: BaseTool): void;
+    /**
+     * Add a tool to the end of this' tool list (the added tool receives events after tools already added to this).
+     * This should be called before creating the app's toolbar.
+     *
+     * If `options.addToFront`, the tool is added to the beginning of this' tool list.
+     *
+     * Does nothing if the tool is already present.
+     */
+    addTool(tool: BaseTool, options?: {
+        addToFront: boolean;
+    }): void;
     /**
      * Removes **and destroys** all tools in `tools` from this.
      */

package/dist/cjs/tools/ToolController.js

@@ -109,8 +109,12 @@ class ToolController {
         });
         this.activeTool = null;
     }
-    // Replaces the current set of tools with `tools`. This should only be done before
-    // the creation of the app's toolbar (if using `AbstractToolbar`).
+    /**
+     * Replaces the current set of tools with `tools`. This should only be done before
+     * the creation of the app's toolbar (if using `AbstractToolbar`).
+     *
+     * If no `primaryToolGroup` is given, an empty one will be created.
+     */
     setTools(tools, primaryToolGroup) {
         this.tools = tools;
         this.primaryToolGroup = primaryToolGroup ?? new ToolEnabledGroup_1.default();
@@ -136,14 +140,23 @@ class ToolController {
             return tool.getToolGroup() === this.primaryToolGroup;
         });
     }
-    // Add a tool to the end of this' tool list (the added tool receives events after tools already added to this).
-    // This should be called before creating the app's toolbar.
-    //
-    // A tool should only be added once.
-    addTool(tool) {
+    /**
+     * Add a tool to the end of this' tool list (the added tool receives events after tools already added to this).
+     * This should be called before creating the app's toolbar.
+     *
+     * If `options.addToFront`, the tool is added to the beginning of this' tool list.
+     *
+     * Does nothing if the tool is already present.
+     */
+    addTool(tool, options) {
         // Only add if not already present.
         if (!this.tools.includes(tool)) {
-            this.tools.push(tool);
+            if (options?.addToFront) {
+                this.tools.splice(0, 0, tool);
+            }
+            else {
+                this.tools.push(tool);
+            }
         }
     }
     /**

package/dist/cjs/tools/lib.d.ts

@@ -1,6 +1,3 @@
-/**
- * @packageDocumentation
- */
 export { default as BaseTool } from './BaseTool';
 export { default as ToolController } from './ToolController';
 export { default as ToolEnabledGroup } from './ToolEnabledGroup';
@@ -11,7 +8,7 @@ export { default as PenTool, PenStyle } from './Pen';
 export { default as TextTool } from './TextTool';
 export { default as SelectionTool } from './SelectionTool/SelectionTool';
 export { default as SelectAllShortcutHandler } from './SelectionTool/SelectAllShortcutHandler';
-export { default as EraserTool } from './Eraser';
+export { default as EraserTool, EraserMode } from './Eraser';
 export { default as PasteHandler } from './PasteHandler';
 export { default as SoundUITool } from './SoundUITool';
 export { default as ToolbarShortcutHandler } from './ToolbarShortcutHandler';

package/dist/cjs/tools/lib.js

@@ -1,12 +1,9 @@
 "use strict";
-/**
- * @packageDocumentation
- */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolbarShortcutHandler = exports.SoundUITool = exports.PasteHandler = 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 = void 0;
 var BaseTool_1 = require("./BaseTool");
 Object.defineProperty(exports, "BaseTool", { enumerable: true, get: function () { return __importDefault(BaseTool_1).default; } });
 var ToolController_1 = require("./ToolController");
@@ -30,6 +27,7 @@ var SelectAllShortcutHandler_1 = require("./SelectionTool/SelectAllShortcutHandl
 Object.defineProperty(exports, "SelectAllShortcutHandler", { enumerable: true, get: function () { return __importDefault(SelectAllShortcutHandler_1).default; } });
 var Eraser_1 = require("./Eraser");
 Object.defineProperty(exports, "EraserTool", { enumerable: true, get: function () { return __importDefault(Eraser_1).default; } });
+Object.defineProperty(exports, "EraserMode", { enumerable: true, get: function () { return Eraser_1.EraserMode; } });
 var PasteHandler_1 = require("./PasteHandler");
 Object.defineProperty(exports, "PasteHandler", { enumerable: true, get: function () { return __importDefault(PasteHandler_1).default; } });
 var SoundUITool_1 = require("./SoundUITool");

package/dist/cjs/tools/localization.d.ts

@@ -26,8 +26,8 @@ export interface ToolLocalization {
     findDialogHidden: string;
     focusedFoundText: (currentMatchNumber: number, totalMatches: number) => string;
     anyDevicePanning: string;
-    copied: (count: number, description: string) => string;
-    pasted: (count: number, description: string) => string;
+    copied: (count: number) => string;
+    pasted: (count: number) => string;
     toolEnabledAnnouncement: (toolName: string) => string;
     toolDisabledAnnouncement: (toolName: string) => string;
 }

package/dist/cjs/tools/localization.js

@@ -29,8 +29,8 @@ exports.defaultToolLocalization = {
     findDialogHidden: 'Find dialog hidden',
     focusedFoundText: (matchIdx, totalMatches) => `Viewing match ${matchIdx} of ${totalMatches}`,
     anyDevicePanning: 'Any device panning',
-    copied: (count, description) => `Copied ${count} ${description}`,
-    pasted: (count, description) => `Pasted ${count} ${description}`,
+    copied: (count) => `Copied ${count} item(s)`,
+    pasted: (count) => `Pasted ${count} item(s)`,
     toolEnabledAnnouncement: (toolName) => `${toolName} enabled`,
     toolDisabledAnnouncement: (toolName) => `${toolName} disabled`,
 };

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

@@ -0,0 +1,27 @@
+import { Editor } from '../Editor';
+/**
+ * Handles conversion between the browser clipboard APIs and internal
+ * js-draw clipboard events.
+ */
+export default class ClipboardHandler {
+    #private;
+    private editor;
+    constructor(editor: Editor);
+    /**
+     * Pastes data from the clipboard into the editor associated with
+     * this handler.
+     *
+     * @param event Optional -- a clipboard/drag event. If not provided,
+     * 				`navigator.clipboard` will be used instead.
+     * @returns true if the paste event was handled by the editor.
+     */
+    paste(event?: DragEvent | ClipboardEvent): Promise<boolean>;
+    /**
+     * Copies text from the editor associated with this.
+     *
+     * Even if `event` is provided, the `navigator.clipboard` API may be used if image data
+     * is to be copied. This is done because `ClipboardEvent`s seem to not support attaching
+     * images.
+     */
+    copy(event?: ClipboardEvent): Promise<void>;
+}

package/dist/cjs/util/ClipboardHandler.js

@@ -0,0 +1,205 @@
+"use strict";
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var _ClipboardHandler_preferClipboardEvents;
+Object.defineProperty(exports, "__esModule", { value: true });
+const inputEvents_1 = require("../inputEvents");
+const fileToBase64Url_1 = __importDefault(require("./fileToBase64Url"));
+const isTextMimeType = (mime) => 
+// +xml: Handles image/svg+xml
+mime.endsWith('+xml') || mime.startsWith('text/');
+/**
+ * Handles conversion between the browser clipboard APIs and internal
+ * js-draw clipboard events.
+ */
+class ClipboardHandler {
+    constructor(editor) {
+        this.editor = editor;
+        _ClipboardHandler_preferClipboardEvents.set(this, false);
+    }
+    /**
+     * Pastes data from the clipboard into the editor associated with
+     * this handler.
+     *
+     * @param event Optional -- a clipboard/drag event. If not provided,
+     * 				`navigator.clipboard` will be used instead.
+     * @returns true if the paste event was handled by the editor.
+     */
+    async paste(event) {
+        const editor = this.editor;
+        const clipboardData = event?.dataTransfer ?? event?.clipboardData ?? null;
+        const hasEvent = !!clipboardData;
+        const sendPasteEvent = (mime, data) => {
+            return data && editor.toolController.dispatchInputEvent({
+                kind: inputEvents_1.InputEvtType.PasteEvent,
+                mime,
+                data,
+            });
+        };
+        // Listed in order of precedence
+        const supportedMIMEs = [
+            'image/svg+xml',
+            'text/html',
+            'image/png',
+            'image/jpeg',
+            'text/plain',
+        ];
+        let files = [];
+        const textData = new Map();
+        if (hasEvent) {
+            // NOTE: On some browsers, .getData and .files must be used before any async operations.
+            files = [...clipboardData.files];
+            for (const mime of supportedMIMEs) {
+                const data = clipboardData.getData(mime);
+                if (data) {
+                    textData.set(mime, data);
+                }
+            }
+        }
+        else {
+            const clipboardData = await navigator.clipboard.read();
+            for (const item of clipboardData) {
+                for (const mime of item.types) {
+                    if (supportedMIMEs.includes(mime)) {
+                        files.push(await item.getType(mime));
+                    }
+                }
+            }
+        }
+        // Returns true if handled
+        const handleMIME = async (mime) => {
+            const isTextFormat = isTextMimeType(mime);
+            if (isTextFormat) {
+                const data = textData.get(mime);
+                if (sendPasteEvent(mime, data)) {
+                    event?.preventDefault();
+                    return true;
+                }
+            }
+            for (const file of files) {
+                const fileType = file.type.toLowerCase();
+                if (fileType !== mime) {
+                    continue;
+                }
+                if (isTextFormat) {
+                    const text = await file.text();
+                    if (sendPasteEvent(mime, text)) {
+                        event?.preventDefault();
+                        return true;
+                    }
+                }
+                else {
+                    editor.showLoadingWarning(0);
+                    const onprogress = (evt) => {
+                        editor.showLoadingWarning(evt.loaded / evt.total);
+                    };
+                    try {
+                        const data = await (0, fileToBase64Url_1.default)(file, { onprogress });
+                        if (sendPasteEvent(mime, data)) {
+                            event?.preventDefault();
+                            editor.hideLoadingWarning();
+                            return true;
+                        }
+                    }
+                    catch (e) {
+                        console.error('Error reading image:', e);
+                    }
+                    editor.hideLoadingWarning();
+                }
+            }
+            return false;
+        };
+        for (const mime of supportedMIMEs) {
+            if (await handleMIME(mime)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Copies text from the editor associated with this.
+     *
+     * Even if `event` is provided, the `navigator.clipboard` API may be used if image data
+     * is to be copied. This is done because `ClipboardEvent`s seem to not support attaching
+     * images.
+     */
+    copy(event) {
+        const mimeToData = Object.create(null);
+        if (this.editor.toolController.dispatchInputEvent({
+            kind: inputEvents_1.InputEvtType.CopyEvent,
+            setData: (mime, data) => {
+                mimeToData[mime] = data;
+            },
+        })) {
+            event?.preventDefault();
+        }
+        const mimeTypes = Object.keys(mimeToData);
+        const hasNonTextMimeTypes = mimeTypes.some(mime => !isTextMimeType(mime));
+        const copyToEvent = () => {
+            if (!event) {
+                throw new Error('Unable to paste -- no event provided.');
+            }
+            for (const key in mimeToData) {
+                const value = mimeToData[key];
+                if (typeof value === 'string') {
+                    event.clipboardData?.setData(key, value);
+                }
+            }
+        };
+        const copyToClipboardApi = () => {
+            const mappedMimeToData = Object.create(null);
+            const mimeMapping = {
+                // image/svg+xml is unsupported in Chrome.
+                'image/svg+xml': 'text/html',
+            };
+            for (const key in mimeToData) {
+                const data = mimeToData[key];
+                const mappedKey = mimeMapping[key] || key;
+                if (typeof data === 'string') {
+                    mappedMimeToData[mappedKey] = new Blob([new TextEncoder().encode(data)], { type: mappedKey });
+                }
+                else {
+                    mappedMimeToData[mappedKey] = data;
+                }
+            }
+            return navigator.clipboard.write([new ClipboardItem(mappedMimeToData)]);
+        };
+        const supportsClipboardApi = (typeof ClipboardItem !== 'undefined'
+            && typeof navigator?.clipboard?.write !== 'undefined');
+        if (!__classPrivateFieldGet(this, _ClipboardHandler_preferClipboardEvents, "f") && supportsClipboardApi && (hasNonTextMimeTypes || !event)) {
+            let clipboardApiPromise = null;
+            const fallBackToCopyEvent = (reason) => {
+                console.warn('Unable to copy to the clipboard API. Future calls to .copy will use ClipboardEvents if possible.', reason);
+                __classPrivateFieldSet(this, _ClipboardHandler_preferClipboardEvents, true, "f");
+                copyToEvent();
+            };
+            try {
+                clipboardApiPromise = copyToClipboardApi();
+            }
+            catch (error) {
+                fallBackToCopyEvent(error);
+            }
+            if (clipboardApiPromise) {
+                return clipboardApiPromise.catch(fallBackToCopyEvent);
+            }
+        }
+        else {
+            copyToEvent();
+        }
+        return Promise.resolve();
+    }
+}
+_ClipboardHandler_preferClipboardEvents = new WeakMap();
+exports.default = ClipboardHandler;

package/dist/cjs/util/ClipboardHandler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/version.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Contains the current version of the library -- used
+ * internaly (e.g. for documentation).
+ * @internal
+ */
 declare const _default: {
     number: string;
 };

package/dist/cjs/version.js

@@ -1,5 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Contains the current version of the library -- used
+ * internaly (e.g. for documentation).
+ * @internal
+ */
 exports.default = {
-    number: '1.16.1',
+    number: '1.18.0',
 };

package/dist/mjs/Editor.d.ts

@@ -11,12 +11,14 @@ import Pointer from './Pointer';
 import { EditorLocalization } from './localization';
 import IconProvider from './toolbar/IconProvider';
 import AbstractComponent from './components/AbstractComponent';
+import { BackgroundType } from './components/BackgroundComponent';
 import KeyboardShortcutManager from './shortcuts/KeyboardShortcutManager';
 import KeyBinding from './shortcuts/KeyBinding';
 import AbstractToolbar from './toolbar/AbstractToolbar';
 import RenderablePathSpec from './rendering/RenderablePathSpec';
 import { AboutDialogEntry } from './dialogs/makeAboutDialog';
 import ReactiveValue, { MutableReactiveValue } from './util/ReactiveValue';
+import { PenTypeRecord } from './toolbar/widgets/PenToolWidget';
 /**
  * Provides settings to an instance of an editor. See the Editor {@link Editor.constructor}.
  *
@@ -73,6 +75,33 @@ export interface EditorSettings {
         description?: string;
         version?: string;
     } | null;
+    /**
+     * Configures the default pen tools.
+     *
+     * **Example**:
+     * [[include:doc-pages/inline-examples/editor-settings-polyline-pen.md]]
+     */
+    pens: {
+        /**
+         * Additional pen types that can be selected in a toolbar.
+         */
+        additionalPenTypes?: readonly Readonly<PenTypeRecord>[];
+        /**
+         * Should return `true` if a pen type should be shown in the toolbar.
+         *
+         * @example
+         * ```ts,runnable
+         * import {Editor} from 'js-draw';
+         * const editor = new Editor(document.body, {
+         *   // Only allow selecting the polyline pen from the toolbar.
+         *   pens: { filterPenTypes: p => p.id === 'polyline-pen' },
+         * });
+         * editor.addToolbar();
+         * ```
+         * Notice that this setting only affects the toolbar GUI.
+         */
+        filterPenTypes?: (penType: PenTypeRecord) => boolean;
+    } | null;
 }
 /**
  * The main entrypoint for the full editor.
@@ -92,7 +121,7 @@ export interface EditorSettings {
  * ```
  *
  * See also
- * [`docs/example/example.ts`](https://github.com/personalizedrefrigerator/js-draw/blob/main/docs/demo/example.ts).
+ * * [`examples.md`](https://github.com/personalizedrefrigerator/js-draw/blob/main/docs/examples.md).
  */
 export declare class Editor {
     private container;
@@ -195,7 +224,7 @@ export declare class Editor {
     private accessibilityControlArea;
     private eventListenerTargets;
     private readOnly;
-    private settings;
+    private readonly settings;
     /**
      * @example
      * ```ts,runnable
@@ -227,6 +256,12 @@ export declare class Editor {
      * ```
      */
     constructor(parent: HTMLElement, settings?: Partial<EditorSettings>);
+    /**
+     * @returns a shallow copy of the current settings of the editor.
+     *
+     * Do not modify.
+     */
+    getCurrentSettings(): Readonly<EditorSettings>;
     /**
      * @returns a reference to the editor's container.
      *
@@ -254,7 +289,7 @@ export declare class Editor {
     private registerListeners;
     private updateEditorSizeVariables;
     /** @internal */
-    protected handleHTMLWheelEvent(event: WheelEvent): boolean | undefined;
+    handleHTMLWheelEvent(event: WheelEvent): boolean | undefined;
     private pointers;
     private getPointerList;
     /**
@@ -273,7 +308,7 @@ export declare class Editor {
     /** @internal */
     protected handleDrop(evt: DragEvent | ClipboardEvent): Promise<void>;
     /** @internal */
-    protected handlePaste(evt: DragEvent | ClipboardEvent): Promise<void>;
+    protected handlePaste(evt: DragEvent | ClipboardEvent): Promise<boolean | undefined>;
     /**
      * Forward pointer events from `elem` to this editor. Such that right-click/right-click drag
      * events are also forwarded, `elem`'s contextmenu is disabled.
@@ -317,9 +352,9 @@ export declare class Editor {
         remove: () => void;
     };
     /** @internal */
-    protected handleHTMLKeyDownEvent(htmlEvent: KeyboardEvent): boolean;
+    handleHTMLKeyDownEvent(htmlEvent: KeyboardEvent): boolean;
     /** @internal */
-    protected handleHTMLKeyUpEvent(htmlEvent: KeyboardEvent): boolean;
+    handleHTMLKeyUpEvent(htmlEvent: KeyboardEvent): boolean;
     /**
      * Adds event listners for keypresses (and drop events) on `elem` and forwards those
      * events to the editor.
@@ -444,8 +479,11 @@ export declare class Editor {
      * This is a convenience method that creates **and applies** a single command.
      *
      * If `selectComponents` is true (the default), the components are selected.
+     *
+     * `actionDescription`, if given, should be a screenreader-friendly description of the
+     * reason components were added (e.g. "pasted").
      */
-    addAndCenterComponents(components: AbstractComponent[], selectComponents?: boolean): Promise<void>;
+    addAndCenterComponents(components: AbstractComponent[], selectComponents?: boolean, actionDescription?: string): Promise<void>;
     /**
      * Get a data URL (e.g. as produced by `HTMLCanvasElement::toDataURL`).
      * If `format` is not `image/png`, a PNG image URL may still be returned (as in the
@@ -493,8 +531,38 @@ export declare class Editor {
      */
     loadFrom(loader: ImageLoader): Promise<void>;
     private getTopmostBackgroundComponent;
+    /**
+     * This is a convenience method for adding or updating the {@link BackgroundComponent}
+     * and {@link EditorImage.setAutoresizeEnabled} for the current image.
+     *
+     * If there are multiple {@link BackgroundComponent}s in the image, this only modifies
+     * the topmost such element.
+     *
+     * **Example**:
+     * ```ts,runnable
+     * import { Editor, Color4, BackgroundComponentBackgroundType } from 'js-draw';
+     * const editor = new Editor(document.body);
+     * editor.dispatch(editor.setBackgroundStyle({
+     *     color: Color4.orange,
+     *     type: BackgroundComponentBackgroundType.Grid,
+     *     autoresize: true,
+     * }));
+     * ```
+     *
+     * To change the background size, see {@link EditorImage.setImportExportRect}.
+     */
+    setBackgroundStyle(style: {
+        color?: Color4;
+        type?: BackgroundType;
+        autoresize?: boolean;
+    }): Command;
     /**
      * Set the background color of the image.
+     *
+     * This is a convenience method for adding or updating the {@link BackgroundComponent}
+     * for the current image.
+     *
+     * @see {@link setBackgroundStyle}
      */
     setBackgroundColor(color: Color4): Command;
     /**