js-draw 1.16.1 → 1.17.0

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/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.17.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,35 @@ export interface EditorSettings {
         description?: string;
         version?: string;
     } | null;
+    /**
+     * Configures the default pen tools.
+     *
+     * **Example**:
+     * ```ts,runnable
+     * import { Editor, makePolylineBuilder } from 'js-draw';
+     *
+     * const editor = new Editor(document.body, {
+     *     pens: {
+     *         additionalPenTypes: [{
+     *             name: 'Polyline (For debugging)',
+     *             id: 'custom-polyline',
+     *             factory: makePolylineBuilder,
+     *
+     *             // The pen doesn't create fixed shapes (e.g. squares, rectangles, etc)
+     *             // and so should go under the "pens" section.
+     *             isShapeBuilder: false,
+     *         }],
+     *     },
+     * });
+     * editor.addToolbar();
+     * ```
+     */
+    pens: {
+        /**
+         * Additional pen types that can be selected in a toolbar.
+         */
+        additionalPenTypes: readonly Readonly<PenTypeRecord>[];
+    } | null;
 }
 /**
  * The main entrypoint for the full editor.
@@ -195,7 +226,7 @@ export declare class Editor {
     private accessibilityControlArea;
     private eventListenerTargets;
     private readOnly;
-    private settings;
+    private readonly settings;
     /**
      * @example
      * ```ts,runnable
@@ -227,6 +258,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 +291,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 +310,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 +354,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 +481,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 +533,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;
     /**