js-draw 1.2.1 → 1.3.0

package/dist/cjs/Editor.js

@@ -37,7 +37,7 @@ const EventDispatcher_1 = __importDefault(require("./EventDispatcher"));
 const math_1 = require("@js-draw/math");
 const Display_1 = __importStar(require("./rendering/Display"));
 const SVGRenderer_1 = __importDefault(require("./rendering/renderers/SVGRenderer"));
-const SVGLoader_1 = __importDefault(require("./SVGLoader"));
+const SVGLoader_1 = __importStar(require("./SVGLoader"));
 const Pointer_1 = __importDefault(require("./Pointer"));
 const getLocalizationTable_1 = __importDefault(require("./localizations/getLocalizationTable"));
 const IconProvider_1 = __importDefault(require("./toolbar/IconProvider"));
@@ -58,25 +58,29 @@ const version_1 = __importDefault(require("./version"));
 /**
  * The main entrypoint for the full editor.
  *
- * @example
+ * ## Example
  * To create an editor with a toolbar,
- * ```
+ * ```ts,runnable
+ * import { Editor } from 'js-draw';
+ *
  * const editor = new Editor(document.body);
  *
  * const toolbar = editor.addToolbar();
- * toolbar.addActionButton('Save', () => {
+ * toolbar.addSaveButton(() => {
  *   const saveData = editor.toSVG().outerHTML;
  *   // Do something with saveData...
  * });
  * ```
  *
  * See also
- * [`docs/example/example.ts`](https://github.com/personalizedrefrigerator/js-draw/blob/main/docs/demo/example.ts#L15).
+ * [`docs/example/example.ts`](https://github.com/personalizedrefrigerator/js-draw/blob/main/docs/demo/example.ts).
  */
 class Editor {
     /**
      * @example
-     * ```
+     * ```ts,runnable
+     * import { Editor } from 'js-draw';
+     *
      * const container = document.body;
      *
      * // Create an editor
@@ -89,13 +93,16 @@ class Editor {
      * // Add the default toolbar
      * const toolbar = editor.addToolbar();
      *
-     * // Add a save button
+     * const createCustomIcon = () => {
+     *   // Create/return an icon here.
+     * };
+     *
+     * // Add a custom button
      * toolbar.addActionButton({
-     *   label: 'Save'
-     *   icon: createSaveIcon(),
+     *   label: 'Custom Button'
+     *   icon: createCustomIcon(),
      * }, () => {
-     *   const saveData = editor.toSVG().outerHTML;
-     *   // Do something with saveData
+     *   // Do something here
      * });
      * ```
      */
@@ -128,6 +135,10 @@ class Editor {
             iconProvider: settings.iconProvider ?? new IconProvider_1.default(),
             notices: [],
         };
+        // Validate settings
+        if (this.settings.minZoom > this.settings.maxZoom) {
+            throw new Error('Minimum zoom must be lesser than maximum zoom!');
+        }
         this.icons = this.settings.iconProvider;
         this.shortcuts = new KeyboardShortcutManager_1.default(this.settings.keyboardShortcutOverrides);
         this.container = document.createElement('div');
@@ -182,6 +193,10 @@ class Editor {
                     if (oldZoom <= this.settings.maxZoom && oldZoom >= this.settings.minZoom) {
                         resetTransform = evt.oldTransform;
                     }
+                    else {
+                        // If 1x zoom isn't acceptable, try a zoom between the minimum and maximum.
+                        resetTransform = math_1.Mat33.scaling2D((this.settings.minZoom + this.settings.maxZoom) / 2);
+                    }
                     this.viewport.resetTransform(resetTransform);
                 }
             }
@@ -235,6 +250,7 @@ class Editor {
     registerListeners() {
         this.handlePointerEventsFrom(this.renderingRegion);
         this.handleKeyEventsFrom(this.renderingRegion);
+        this.handlePointerEventsFrom(this.accessibilityAnnounceArea);
         this.container.addEventListener('wheel', evt => {
             let delta = math_1.Vec3.of(evt.deltaX, evt.deltaY, evt.deltaZ);
             // Process wheel events if the ctrl key is down, even if disabled -- we do want to handle
@@ -311,6 +327,8 @@ class Editor {
         // still fill the screen.
         this.container.style.setProperty('--editor-current-width-px', `${this.container.clientWidth}px`);
         this.container.style.setProperty('--editor-current-height-px', `${this.container.clientHeight}px`);
+        this.container.style.setProperty('--editor-current-display-width-px', `${this.renderingRegion.clientWidth}px`);
+        this.container.style.setProperty('--editor-current-display-height-px', `${this.renderingRegion.clientHeight}px`);
     }
     getPointerList() {
         const nowTime = performance.now();
@@ -731,12 +749,12 @@ class Editor {
         this.display.setDraftMode(false);
         this.hideLoadingWarning();
     }
-    // @see {@link #asyncApplyOrUnapplyCommands }
+    // @see {@link asyncApplyOrUnapplyCommands }
     asyncApplyCommands(commands, chunkSize) {
         return this.asyncApplyOrUnapplyCommands(commands, true, chunkSize);
     }
     // If `unapplyInReverseOrder`, commands are reversed before unapplying.
-    // @see {@link #asyncApplyOrUnapplyCommands }
+    // @see {@link asyncApplyOrUnapplyCommands }
     asyncUnapplyCommands(commands, chunkSize, unapplyInReverseOrder = false) {
         if (unapplyInReverseOrder) {
             commands = [...commands]; // copy
@@ -783,8 +801,8 @@ class Editor {
         }
         const renderer = this.display.getDryInkRenderer();
         this.image.renderWithCache(renderer, this.display.getCache(), this.viewport);
-        if (showImageBounds) {
-            // Draw a rectangle around the region that will be visible on save
+        // Draw a rectangle around the region that will be visible on save
+        if (showImageBounds && !this.image.getAutoresizeEnabled()) {
             const exportRectFill = { fill: math_1.Color4.fromHex('#44444455') };
             const exportRectStrokeWidth = 5 * this.viewport.getSizeOfPixelOnCanvas();
             renderer.drawRect(this.getImportExportRect(), exportRectStrokeWidth, exportRectFill);
@@ -807,6 +825,9 @@ class Editor {
     /**
      * Clears the wet ink display.
      *
+     * The wet ink display can be used by the currently active tool to display a preview
+     * of an in-progress action.
+     *
      * @see {@link Display.getWetInkRenderer}
      */
     clearWetInk() {
@@ -822,16 +843,23 @@ class Editor {
      * Creates an element that will be positioned on top of the dry/wet ink
      * renderers.
      *
+     * So as not to change the position of other overlays, `overlay` should either
+     * be styled to have 0 height or have `position: absolute`.
+     *
      * This is useful for displaying content on top of the rendered content
      * (e.g. a selection box).
      */
     createHTMLOverlay(overlay) {
-        overlay.classList.add('overlay');
+        overlay.classList.add('overlay', 'js-draw-editor-overlay');
         this.container.appendChild(overlay);
         return {
             remove: () => overlay.remove(),
         };
     }
+    /**
+     * Creates a CSS stylesheet with `content` and applies it to the document
+     * (and thus, to this editor).
+     */
     addStyleSheet(content) {
         const styleSheet = document.createElement('style');
         styleSheet.innerText = content;
@@ -912,11 +940,14 @@ class Editor {
             }
         }
     }
-    // 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
-    // case of `HTMLCanvasElement::toDataURL`).
-    //
-    // The export resolution is the same as the size of the drawing canvas.
+    /**
+     * 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
+     * case of `HTMLCanvasElement::toDataURL`).
+     *
+     * The export resolution is the same as the size of the drawing canvas, unless `outputSize`
+     * is given.
+     */
     toDataURL(format = 'image/png', outputSize) {
         const canvas = document.createElement('canvas');
         const importExportViewport = this.image.getImportExportViewport();
@@ -933,6 +964,12 @@ class Editor {
         const dataURL = canvas.toDataURL(format);
         return dataURL;
     }
+    /**
+     * Converts the editor's content into an SVG image.
+     *
+     * @see
+     * {@link SVGRenderer}
+     */
     toSVG() {
         const importExportViewport = this.image.getImportExportViewport().getTemporaryClone();
         const sanitize = false;
@@ -948,6 +985,12 @@ class Editor {
         result.setAttribute('viewBox', [rect.x, rect.y, rect.w, rect.h].map(part => (0, math_1.toRoundedString)(part)).join(' '));
         result.setAttribute('width', (0, math_1.toRoundedString)(rect.w));
         result.setAttribute('height', (0, math_1.toRoundedString)(rect.h));
+        if (this.image.getAutoresizeEnabled()) {
+            result.classList.add(SVGLoader_1.svgLoaderAutoresizeClassName);
+        }
+        else {
+            result.classList.remove(SVGLoader_1.svgLoaderAutoresizeClassName);
+        }
         return result;
     }
     /**
@@ -960,6 +1003,7 @@ class Editor {
         this.display.setDraftMode(true);
         const originalBackgrounds = this.image.getBackgroundComponents();
         const eraseBackgroundCommand = new Erase_1.default(originalBackgrounds);
+        let autoresizeEnabled = false;
         await loader.start(async (component) => {
             await this.dispatchNoAnnounce(EditorImage_1.default.addElement(component));
         }, (countProcessed, totalToProcess) => {
@@ -969,10 +1013,17 @@ class Editor {
                 return (0, untilNextAnimationFrame_1.default)();
             }
             return null;
-        }, (importExportRect) => {
+        }, (importExportRect, options) => {
             this.dispatchNoAnnounce(this.setImportExportRect(importExportRect), false);
             this.dispatchNoAnnounce(this.viewport.zoomTo(importExportRect), false);
+            if (options) {
+                autoresizeEnabled = options.autoresize;
+            }
         });
+        // TODO: Move this call into the callback above. Currently, this would cause
+        //       decrease in performance as the main background would be repeatedly added
+        //       and removed from the editor every time another component is added.
+        this.dispatchNoAnnounce(this.image.setAutoresizeEnabled(autoresizeEnabled), false);
         // Ensure that we don't have multiple overlapping BackgroundComponents. Remove
         // old BackgroundComponents.
         // Overlapping BackgroundComponents may cause changing the background color to
@@ -1033,8 +1084,23 @@ class Editor {
     /**
      * Alias for `loadFrom(SVGLoader.fromString)`.
      *
-     * This is particularly useful when accessing a bundled version of the editor,
-     * where `SVGLoader.fromString` is unavailable.
+     * @example
+     * ```ts,runnable
+     * import {Editor} from 'js-draw';
+     * const editor = new Editor(document.body);
+     *
+     * ---visible---
+     * await editor.loadFromSVG(`
+     *   <svg viewBox="5 23 52 30" width="52" height="16" version="1.1" baseProfile="full" xmlns="http://www.w3.org/2000/svg">
+     *     <text style="
+     *       transform: matrix(0.181846, 0.1, 0, 0.181846, 11.4, 33.2);
+     *       font-family: serif;
+     *       font-size: 32px;
+     *       fill: rgb(100, 140, 61);
+     *     ">An SVG image!</text>
+     *   </svg>
+     * `);
+     * ```
      */
     async loadFromSVG(svgData, sanitize = false) {
         const loader = SVGLoader_1.default.fromString(svgData, sanitize);

package/dist/cjs/EditorImage.d.ts

@@ -5,9 +5,11 @@ import { Rect2 } from '@js-draw/math';
 import RenderingCache from './rendering/caching/RenderingCache';
 import SerializableCommand from './commands/SerializableCommand';
 import EventDispatcher from './EventDispatcher';
+import Command from './commands/Command';
 export declare const sortLeavesByZIndex: (leaves: Array<ImageNode>) => void;
 export declare enum EditorImageEventType {
-    ExportViewportChanged = 0
+    ExportViewportChanged = 0,
+    AutoresizeModeChanged = 1
 }
 export type EditorImageNotifier = EventDispatcher<EditorImageEventType, {
     image: EditorImage;
@@ -19,6 +21,7 @@ export default class EditorImage {
     private componentCount;
     /** Viewport for the exported/imported image. */
     private importExportViewport;
+    private shouldAutoresizeExportViewport;
     readonly notifier: EditorImageNotifier;
     constructor();
     getBackgroundComponents(): AbstractComponent[];
@@ -35,14 +38,20 @@ export default class EditorImage {
     render(renderer: AbstractRenderer, viewport: Viewport | null): void;
     /** Renders all nodes, even ones not within the viewport. @internal */
     renderAll(renderer: AbstractRenderer): void;
-    /** @returns all elements in the image, sorted by z-index. This can be slow for large images. */
+    /**
+     * @returns all elements in the image, sorted by z-index. This can be slow for large images.
+     *
+     * Does not include background elements. See {@link getBackgroundComponents}.
+     */
     getAllElements(): AbstractComponent[];
     /** Returns the number of elements added to this image. @internal */
     estimateNumElements(): number;
     /** @returns a list of `AbstractComponent`s intersecting `region`, sorted by z-index. */
-    getElementsIntersectingRegion(region: Rect2): AbstractComponent[];
-    /** Called whenever an element is completely removed. @internal */
+    getElementsIntersectingRegion(region: Rect2, includeBackground?: boolean): AbstractComponent[];
+    /** Called whenever (just after) an element is completely removed. @internal */
     onDestroyElement(elem: AbstractComponent): void;
+    /** Called just after an element is added. @internal */
+    private onElementAdded;
     /**
      * @returns the AbstractComponent with `id`, if it exists.
      *
@@ -66,11 +75,40 @@ export default class EditorImage {
      * @returns a `Viewport` for rendering the image when importing/exporting.
      */
     getImportExportViewport(): Viewport;
+    /**
+     * @see {@link setImportExportRect}
+     */
+    getImportExportRect(): Rect2;
+    /**
+     * Sets the import/export rectangle to the given `imageRect`. Disables
+     * autoresize (if it was previously enabled).
+     */
     setImportExportRect(imageRect: Rect2): SerializableCommand;
+    getAutoresizeEnabled(): boolean;
+    /** Returns a `Command` that sets whether the image should autoresize. */
+    setAutoresizeEnabled(autoresize: boolean): Command;
+    private setAutoresizeEnabledDirectly;
+    /** Updates the size/position of the viewport */
+    private autoresizeExportViewport;
+    private settingExportRect;
+    /**
+     * Sets the import/export viewport directly, without returning a `Command`.
+     * As such, this is not undoable.
+     *
+     * See setImportExportRect
+     *
+     * Returns true if changes to the viewport were made (and thus
+     * ExportViewportChanged was fired.)
+     */
+    private setExportRectDirectly;
+    private onExportViewportChanged;
     private static SetImportExportRectCommand;
 }
 type TooSmallToRenderCheck = (rect: Rect2) => boolean;
-/** Part of the Editor's image. @internal */
+/**
+ * Part of the Editor's image. Does not handle fullscreen/invisible components.
+ * @internal
+ */
 export declare class ImageNode {
     private parent;
     private content;
@@ -84,17 +122,31 @@ export declare class ImageNode {
     onContentChange(): void;
     getContent(): AbstractComponent | null;
     getParent(): ImageNode | null;
-    private getChildrenIntersectingRegion;
+    protected getChildrenIntersectingRegion(region: Rect2, isTooSmallFilter?: TooSmallToRenderCheck): ImageNode[];
     getChildrenOrSelfIntersectingRegion(region: Rect2): ImageNode[];
     getLeavesIntersectingRegion(region: Rect2, isTooSmall?: TooSmallToRenderCheck): ImageNode[];
     getChildWithContent(target: AbstractComponent): ImageNode | null;
     getLeaves(): ImageNode[];
     addLeaf(leaf: AbstractComponent): ImageNode;
+    protected static createLeafNode(parent: ImageNode, content: AbstractComponent): ImageNode;
     getBBox(): Rect2;
     recomputeBBox(bubbleUp: boolean): void;
+    private unionBBoxWith;
     private updateParents;
     private rebalance;
+    protected removeChild(child: ImageNode): void;
     remove(): void;
     render(renderer: AbstractRenderer, visibleRect?: Rect2): void;
+    renderDebugBoundingBoxes(renderer: AbstractRenderer, visibleRect: Rect2, depth?: number): void;
+}
+/** An `ImageNode` that can properly handle fullscreen/data components. @internal */
+export declare class RootImageNode extends ImageNode {
+    private fullscreenChildren;
+    private dataComponents;
+    protected getChildrenIntersectingRegion(region: Rect2, _isTooSmall?: TooSmallToRenderCheck): ImageNode[];
+    getLeaves(): ImageNode[];
+    removeChild(child: ImageNode): void;
+    getChildWithContent(target: AbstractComponent): ImageNode | null;
+    addLeaf(leafContent: AbstractComponent): ImageNode;
 }
 export {};