js-draw 0.1.11 → 0.2.0

package/dist/src/Color4.d.ts

@@ -1,15 +1,34 @@
 export default class Color4 {
+    /** Red component. Should be in the range [0, 1]. */
     readonly r: number;
+    /** Green component. `g` ∈ [0, 1] */
     readonly g: number;
+    /** Blue component. `b` ∈ [0, 1] */
     readonly b: number;
+    /** Alpha/transparent component. `a` ∈ [0, 1] */
     readonly a: number;
     private constructor();
+    /**
+     * Create a color from red, green, blue components. The color is fully opaque (`a = 1.0`).
+     *
+     * Each component should be in the range [0, 1].
+     */
     static ofRGB(red: number, green: number, blue: number): Color4;
     static ofRGBA(red: number, green: number, blue: number, alpha: number): Color4;
     static fromHex(hexString: string): Color4;
+    /** Like fromHex, but can handle additional colors if an `HTMLCanvasElement` is available. */
     static fromString(text: string): Color4;
+    /** @returns true if `this` and `other` are approximately equal. */
     eq(other: Color4 | null | undefined): boolean;
     private hexString;
+    /**
+     * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.
+     *
+     * @example
+     * ```
+     * Color4.red.toHexString(); // -> #ff0000ff
+     * ```
+     */
     toHexString(): string;
     static transparent: Color4;
     static red: Color4;

package/dist/src/Color4.js

@@ -1,12 +1,24 @@
 export default class Color4 {
-    constructor(r, g, b, a) {
+    constructor(
+    /** Red component. Should be in the range [0, 1]. */
+    r, 
+    /** Green component. `g` ∈ [0, 1] */
+    g, 
+    /** Blue component. `b` ∈ [0, 1] */
+    b, 
+    /** Alpha/transparent component. `a` ∈ [0, 1] */
+    a) {
         this.r = r;
         this.g = g;
         this.b = b;
         this.a = a;
         this.hexString = null;
     }
-    // Each component should be in the range [0, 1]
+    /**
+     * Create a color from red, green, blue components. The color is fully opaque (`a = 1.0`).
+     *
+     * Each component should be in the range [0, 1].
+     */
     static ofRGB(red, green, blue) {
         return Color4.ofRGBA(red, green, blue, 1.0);
     }
@@ -46,7 +58,7 @@ export default class Color4 {
         }
         return Color4.ofRGBA(components[0], components[1], components[2], components[3]);
     }
-    // Like fromHex, but can handle additional colors if an HTML5Canvas is available.
+    /** Like fromHex, but can handle additional colors if an `HTMLCanvasElement` is available. */
     static fromString(text) {
         if (text.startsWith('#')) {
             return Color4.fromHex(text);
@@ -67,12 +79,21 @@ export default class Color4 {
             return Color4.ofRGBA(red, green, blue, alpha);
         }
     }
+    /** @returns true if `this` and `other` are approximately equal. */
     eq(other) {
         if (other == null) {
             return false;
         }
         return this.toHexString() === other.toHexString();
     }
+    /**
+     * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.
+     *
+     * @example
+     * ```
+     * Color4.red.toHexString(); // -> #ff0000ff
+     * ```
+     */
     toHexString() {
         if (this.hexString) {
             return this.hexString;

package/dist/src/Editor.d.ts

@@ -1,48 +1,171 @@
+/**
+ * The main entrypoint for the full editor.
+ *
+ * @example
+ * To create an editor with a toolbar,
+ * ```
+ * const editor = new Editor(document.body);
+ *
+ * const toolbar = editor.addToolbar();
+ * toolbar.addActionButton('Save', () => {
+ *   const saveData = editor.toSVG().outerHTML;
+ *   // Do something with saveData...
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
 import EditorImage from './EditorImage';
 import ToolController from './tools/ToolController';
 import { InputEvtType, EditorNotifier, ImageLoader } from './types';
 import Command from './commands/Command';
 import UndoRedoHistory from './UndoRedoHistory';
 import Viewport from './Viewport';
-import { Point2 } from './geometry/Vec2';
+import { Point2 } from './math/Vec2';
 import HTMLToolbar from './toolbar/HTMLToolbar';
 import { RenderablePathSpec } from './rendering/renderers/AbstractRenderer';
 import Display, { RenderingMode } from './rendering/Display';
 import Pointer from './Pointer';
-import Rect2 from './geometry/Rect2';
+import Rect2 from './math/Rect2';
 import { EditorLocalization } from './localization';
 export interface EditorSettings {
+    /** Defaults to `RenderingMode.CanvasRenderer` */
     renderingMode: RenderingMode;
+    /** Uses a default English localization if a translation is not given. */
     localization: Partial<EditorLocalization>;
+    /**
+     * `true` if touchpad/mousewheel scrolling should scroll the editor instead of the document.
+     * This does not include pinch-zoom events.
+     * Defaults to true.
+     */
     wheelEventsEnabled: boolean | 'only-if-focused';
+    /** Minimum zoom fraction (e.g. 0.5 → 50% zoom). */
     minZoom: number;
     maxZoom: number;
 }
 export declare class Editor {
     private container;
     private renderingRegion;
-    history: UndoRedoHistory;
     display: Display;
+    /**
+     * Handles undo/redo.
+     *
+     * @example
+     * ```
+     * const editor = new Editor(document.body);
+     *
+     * // Do something undoable.
+     * // ...
+     *
+     * // Undo the last action
+     * editor.history.undo();
+     * ```
+     */
+    history: UndoRedoHistory;
+    /**
+     * Data structure for adding/removing/querying objects in the image.
+     *
+     * @example
+     * ```
+     * const editor = new Editor(document.body);
+     *
+     * // Create a path.
+     * const stroke = new Stroke([
+     *   Path.fromString('M0,0 L30,30 z').toRenderable({ fill: Color4.black }),
+     * ]);
+     * const addElementCommand = editor.image.addElement(stroke);
+     *
+     * // Add the stroke to the editor
+     * editor.dispatch(addElementCommand);
+     * ```
+     */
     image: EditorImage;
+    /** Viewport for the exported/imported image. */
     private importExportViewport;
+    /** @internal */
     localization: EditorLocalization;
     viewport: Viewport;
     toolController: ToolController;
+    /**
+     * Global event dispatcher/subscriber.
+     * @see {@link types.EditorEventType}
+     */
     notifier: EditorNotifier;
     private loadingWarning;
     private accessibilityAnnounceArea;
+    private accessibilityControlArea;
     private settings;
+    /**
+     * @example
+     * ```
+     * const container = document.body;
+     *
+     * // Create an editor
+     * const editor = new Editor(container, {
+     *   // 2e-10 and 1e12 are the default values for minimum/maximum zoom.
+     *   minZoom: 2e-10,
+     *   maxZoom: 1e12,
+     * });
+     *
+     * // Add the default toolbar
+     * const toolbar = editor.addToolbar();
+     * toolbar.addActionButton({
+     *   label: 'Save'
+     *   icon: createSaveIcon(),
+     * }, () => {
+     *   const saveData = editor.toSVG().outerHTML;
+     *   // Do something with saveData
+     * });
+     * ```
+     */
     constructor(parent: HTMLElement, settings?: Partial<EditorSettings>);
+    /**
+     * @returns a reference to the editor's container.
+     *
+     * @example
+     * ```
+     *   editor.getRootElement().style.height = '500px';
+     * ```
+     */
     getRootElement(): HTMLElement;
+    /** @param fractionLoaded - should be a number from 0 to 1, where 1 represents completely loaded. */
     showLoadingWarning(fractionLoaded: number): void;
     hideLoadingWarning(): void;
+    private previousAccessibilityAnnouncement;
     announceForAccessibility(message: string): void;
+    /**
+     * Creates a toolbar. If `defaultLayout` is true, default buttons are used.
+     * @returns a reference to the toolbar.
+     */
     addToolbar(defaultLayout?: boolean): HTMLToolbar;
     private registerListeners;
+    /** Adds event listners for keypresses to `elem` and forwards those events to the editor. */
     handleKeyEventsFrom(elem: HTMLElement): void;
+    /** `apply` a command. `command` will be announced for accessibility. */
     dispatch(command: Command, addToHistory?: boolean): void;
+    /**
+     * Dispatches a command without announcing it. By default, does not add to history.
+     * Use this to show finalized commands that don't need to have `announceForAccessibility`
+     * called.
+     *
+     * Prefer `command.apply(editor)` for incomplete commands. `dispatchNoAnnounce` may allow
+     * clients to listen for the application of commands (e.g. `SerializableCommand`s so they can
+     * be sent across the network), while `apply` does not.
+     *
+     * @example
+     * ```
+     * const addToHistory = false;
+     * editor.dispatchNoAnnounce(editor.viewport.zoomTo(someRectangle), addToHistory);
+     * ```
+     */
     dispatchNoAnnounce(command: Command, addToHistory?: boolean): void;
-    private asyncApplyOrUnapplyCommands;
+    /**
+     * Apply a large transformation in chunks.
+     * If `apply` is `false`, the commands are unapplied.
+     * Triggers a re-render after each `updateChunkSize`-sized group of commands
+     * has been applied.
+     */
+    asyncApplyOrUnapplyCommands(commands: Command[], apply: boolean, updateChunkSize: number): Promise<void>;
     asyncApplyCommands(commands: Command[], chunkSize: number): Promise<void>;
     asyncUnapplyCommands(commands: Command[], chunkSize: number): Promise<void>;
     private announceUndoCallback;
@@ -62,6 +185,12 @@ export declare class Editor {
     loadFrom(loader: ImageLoader): Promise<void>;
     getImportExportRect(): Rect2;
     setImportExportRect(imageRect: Rect2): Command;
+    /**
+     * Alias for loadFrom(SVGLoader.fromString).
+     *
+     * This is particularly useful when accessing a bundled version of the editor,
+     * where `SVGLoader.fromString` is unavailable.
+     */
     loadFromSVG(svgData: string): Promise<void>;
 }
 export default Editor;

package/dist/src/Editor.js

@@ -1,3 +1,20 @@
+/**
+ * The main entrypoint for the full editor.
+ *
+ * @example
+ * To create an editor with a toolbar,
+ * ```
+ * const editor = new Editor(document.body);
+ *
+ * const toolbar = editor.addToolbar();
+ * toolbar.addActionButton('Save', () => {
+ *   const saveData = editor.toSVG().outerHTML;
+ *   // Do something with saveData...
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -14,24 +31,49 @@ import Command from './commands/Command';
 import UndoRedoHistory from './UndoRedoHistory';
 import Viewport from './Viewport';
 import EventDispatcher from './EventDispatcher';
-import { Vec2 } from './geometry/Vec2';
-import Vec3 from './geometry/Vec3';
+import { Vec2 } from './math/Vec2';
+import Vec3 from './math/Vec3';
 import HTMLToolbar from './toolbar/HTMLToolbar';
 import Display, { RenderingMode } from './rendering/Display';
 import SVGRenderer from './rendering/renderers/SVGRenderer';
 import Color4 from './Color4';
 import SVGLoader from './SVGLoader';
 import Pointer from './Pointer';
-import Mat33 from './geometry/Mat33';
+import Mat33 from './math/Mat33';
 import getLocalizationTable from './localizations/getLocalizationTable';
+// { @inheritDoc Editor! }
 export class Editor {
+    /**
+     * @example
+     * ```
+     * const container = document.body;
+     *
+     * // Create an editor
+     * const editor = new Editor(container, {
+     *   // 2e-10 and 1e12 are the default values for minimum/maximum zoom.
+     *   minZoom: 2e-10,
+     *   maxZoom: 1e12,
+     * });
+     *
+     * // Add the default toolbar
+     * const toolbar = editor.addToolbar();
+     * toolbar.addActionButton({
+     *   label: 'Save'
+     *   icon: createSaveIcon(),
+     * }, () => {
+     *   const saveData = editor.toSVG().outerHTML;
+     *   // Do something with saveData
+     * });
+     * ```
+     */
     constructor(parent, settings = {}) {
         var _a, _b, _c, _d;
+        this.previousAccessibilityAnnouncement = '';
         this.announceUndoCallback = (command) => {
-            this.announceForAccessibility(this.localization.undoAnnouncement(command.description(this.localization)));
+            this.announceForAccessibility(this.localization.undoAnnouncement(command.description(this, this.localization)));
         };
         this.announceRedoCallback = (command) => {
-            this.announceForAccessibility(this.localization.redoAnnouncement(command.description(this.localization)));
+            this.announceForAccessibility(this.localization.redoAnnouncement(command.description(this, this.localization)));
         };
         this.rerenderQueued = false;
         this.localization = Object.assign(Object.assign({}, getLocalizationTable()), settings.localization);
@@ -51,14 +93,21 @@ export class Editor {
         this.loadingWarning.classList.add('loadingMessage');
         this.loadingWarning.ariaLive = 'polite';
         this.container.appendChild(this.loadingWarning);
+        this.accessibilityControlArea = document.createElement('textarea');
+        this.accessibilityControlArea.setAttribute('placeholder', this.localization.accessibilityInputInstructions);
+        this.accessibilityControlArea.style.opacity = '0';
+        this.accessibilityControlArea.style.width = '0';
+        this.accessibilityControlArea.style.height = '0';
+        this.accessibilityControlArea.style.position = 'absolute';
         this.accessibilityAnnounceArea = document.createElement('div');
-        this.accessibilityAnnounceArea.ariaLive = 'assertive';
+        this.accessibilityAnnounceArea.setAttribute('aria-live', 'assertive');
         this.accessibilityAnnounceArea.className = 'accessibilityAnnouncement';
         this.container.appendChild(this.accessibilityAnnounceArea);
         this.renderingRegion.style.touchAction = 'none';
         this.renderingRegion.className = 'imageEditorRenderArea';
+        this.renderingRegion.appendChild(this.accessibilityControlArea);
         this.renderingRegion.setAttribute('tabIndex', '0');
-        this.renderingRegion.ariaLabel = this.localization.imageEditor;
+        this.renderingRegion.setAttribute('alt', '');
         this.notifier = new EventDispatcher();
         this.importExportViewport = new Viewport(this.notifier);
         this.viewport = new Viewport(this.notifier);
@@ -88,13 +137,18 @@ export class Editor {
             }
         });
     }
-    // Returns a reference to this' container.
-    // Example usage:
-    //   editor.getRootElement().style.height = '500px';
+    /**
+     * @returns a reference to the editor's container.
+     *
+     * @example
+     * ```
+     *   editor.getRootElement().style.height = '500px';
+     * ```
+     */
     getRootElement() {
         return this.container;
     }
-    // [fractionLoaded] should be a number from 0 to 1, where 1 represents completely loaded.
+    /** @param fractionLoaded - should be a number from 0 to 1, where 1 represents completely loaded. */
     showLoadingWarning(fractionLoaded) {
         const loadingPercent = Math.round(fractionLoaded * 100);
         this.loadingWarning.innerText = this.localization.loading(loadingPercent);
@@ -104,9 +158,20 @@ export class Editor {
         this.loadingWarning.style.display = 'none';
         this.announceForAccessibility(this.localization.doneLoading);
     }
+    // Announce `message` for screen readers. If `message` is the same as the previous
+    // message, it is re-announced.
     announceForAccessibility(message) {
+        // Force re-announcing an announcement if announced again.
+        if (message === this.previousAccessibilityAnnouncement) {
+            message = message + '. ';
+        }
         this.accessibilityAnnounceArea.innerText = message;
+        this.previousAccessibilityAnnouncement = message;
     }
+    /**
+     * Creates a toolbar. If `defaultLayout` is true, default buttons are used.
+     * @returns a reference to the toolbar.
+     */
     addToolbar(defaultLayout = true) {
         const toolbar = new HTMLToolbar(this, this.container, this.localization);
         if (defaultLayout) {
@@ -237,12 +302,18 @@ export class Editor {
             });
             this.queueRerender();
         });
+        this.accessibilityControlArea.addEventListener('input', () => {
+            this.accessibilityControlArea.value = '';
+        });
     }
-    // Adds event listners for keypresses to [elem] and forwards those events to the
-    // editor.
+    /** Adds event listners for keypresses to `elem` and forwards those events to the editor. */
     handleKeyEventsFrom(elem) {
         elem.addEventListener('keydown', evt => {
-            if (this.toolController.dispatchInputEvent({
+            if (evt.key === 't' || evt.key === 'T') {
+                evt.preventDefault();
+                this.display.rerenderAsText();
+            }
+            else if (this.toolController.dispatchInputEvent({
                 kind: InputEvtType.KeyPressEvent,
                 key: evt.key,
                 ctrlKey: evt.ctrlKey,
@@ -263,7 +334,7 @@ export class Editor {
             }
         });
     }
-    // Adds to history by default
+    /** `apply` a command. `command` will be announced for accessibility. */
     dispatch(command, addToHistory = true) {
         if (addToHistory) {
             // .push applies [command] to this
@@ -272,9 +343,23 @@ export class Editor {
         else {
             command.apply(this);
         }
-        this.announceForAccessibility(command.description(this.localization));
+        this.announceForAccessibility(command.description(this, this.localization));
     }
-    // Dispatches a command without announcing it. By default, does not add to history.
+    /**
+     * Dispatches a command without announcing it. By default, does not add to history.
+     * Use this to show finalized commands that don't need to have `announceForAccessibility`
+     * called.
+     *
+     * Prefer `command.apply(editor)` for incomplete commands. `dispatchNoAnnounce` may allow
+     * clients to listen for the application of commands (e.g. `SerializableCommand`s so they can
+     * be sent across the network), while `apply` does not.
+     *
+     * @example
+     * ```
+     * const addToHistory = false;
+     * editor.dispatchNoAnnounce(editor.viewport.zoomTo(someRectangle), addToHistory);
+     * ```
+     */
     dispatchNoAnnounce(command, addToHistory = false) {
         if (addToHistory) {
             this.history.push(command);
@@ -283,10 +368,12 @@ export class Editor {
             command.apply(this);
         }
     }
-    // Apply a large transformation in chunks.
-    // If [apply] is false, the commands are unapplied.
-    // Triggers a re-render after each [updateChunkSize]-sized group of commands
-    // has been applied.
+    /**
+     * Apply a large transformation in chunks.
+     * If `apply` is `false`, the commands are unapplied.
+     * Triggers a re-render after each `updateChunkSize`-sized group of commands
+     * has been applied.
+     */
     asyncApplyOrUnapplyCommands(commands, apply, updateChunkSize) {
         return __awaiter(this, void 0, void 0, function* () {
             this.display.setDraftMode(true);
@@ -313,12 +400,16 @@ export class Editor {
             this.hideLoadingWarning();
         });
     }
+    // @see {@link #asyncApplyOrUnapplyCommands }
     asyncApplyCommands(commands, chunkSize) {
         return this.asyncApplyOrUnapplyCommands(commands, true, chunkSize);
     }
+    // @see {@link #asyncApplyOrUnapplyCommands }
     asyncUnapplyCommands(commands, chunkSize) {
         return this.asyncApplyOrUnapplyCommands(commands, false, chunkSize);
     }
+    // Schedule a re-render for some time in the near future. Does not schedule an additional
+    // re-render if a re-render is already queued.
     queueRerender() {
         if (!this.rerenderQueued) {
             this.rerenderQueued = true;
@@ -352,10 +443,12 @@ export class Editor {
     clearWetInk() {
         this.display.getWetInkRenderer().clear();
     }
-    // Focuses the region used for text input
+    // Focuses the region used for text input/key commands.
     focus() {
         this.renderingRegion.focus();
     }
+    // Creates an element that will be positioned on top of the dry/wet ink
+    // renderers.
     createHTMLOverlay(overlay) {
         overlay.classList.add('overlay');
         this.container.appendChild(overlay);
@@ -370,7 +463,7 @@ export class Editor {
         return styleSheet;
     }
     // Dispatch a pen event to the currently selected tool.
-    // Intented for unit tests.
+    // Intended primarially for unit tests.
     sendPenEvent(eventType, point, allPointers) {
         const mainPointer = Pointer.ofCanvasPoint(point, eventType !== InputEvtType.PointerUpEvt, this.viewport);
         this.toolController.dispatchInputEvent({
@@ -432,7 +525,7 @@ export class Editor {
     getImportExportRect() {
         return this.importExportViewport.visibleRect;
     }
-    // Resize the output SVG
+    // Resize the output SVG to match `imageRect`.
     setImportExportRect(imageRect) {
         const origSize = this.importExportViewport.visibleRect.size;
         const origTransform = this.importExportViewport.canvasToScreenTransform;
@@ -449,13 +542,17 @@ export class Editor {
                 viewport.resetTransform(origTransform);
                 editor.queueRerender();
             }
-            description(localizationTable) {
+            description(_editor, localizationTable) {
                 return localizationTable.resizeOutputCommand(imageRect);
             }
         };
     }
-    // Alias for loadFrom(SVGLoader.fromString).
-    // This is particularly useful when accessing a bundled version of the editor.
+    /**
+     * Alias for loadFrom(SVGLoader.fromString).
+     *
+     * This is particularly useful when accessing a bundled version of the editor,
+     * where `SVGLoader.fromString` is unavailable.
+     */
     loadFromSVG(svgData) {
         return __awaiter(this, void 0, void 0, function* () {
             const loader = SVGLoader.fromString(svgData);

package/dist/src/EditorImage.d.ts

@@ -1,26 +1,31 @@
 import AbstractRenderer from './rendering/renderers/AbstractRenderer';
-import Command from './commands/Command';
 import Viewport from './Viewport';
 import AbstractComponent from './components/AbstractComponent';
-import Rect2 from './geometry/Rect2';
+import Rect2 from './math/Rect2';
 import RenderingCache from './rendering/caching/RenderingCache';
+import SerializableCommand from './commands/SerializableCommand';
 export declare const sortLeavesByZIndex: (leaves: Array<ImageNode>) => void;
 export default class EditorImage {
     private root;
     private componentsById;
     constructor();
     findParent(elem: AbstractComponent): ImageNode | null;
+    /** @internal */
     renderWithCache(screenRenderer: AbstractRenderer, cache: RenderingCache, viewport: Viewport): void;
+    /** @internal */
     render(renderer: AbstractRenderer, viewport: Viewport): void;
+    /** Renders all nodes, even ones not within the viewport. @internal */
     renderAll(renderer: AbstractRenderer): void;
     getElementsIntersectingRegion(region: Rect2): AbstractComponent[];
+    /** @internal */
     onDestroyElement(elem: AbstractComponent): void;
     lookupElement(id: string): AbstractComponent | null;
     private addElementDirectly;
-    static addElement(elem: AbstractComponent, applyByFlattening?: boolean): Command;
+    static addElement(elem: AbstractComponent, applyByFlattening?: boolean): SerializableCommand;
     private static AddElementCommand;
 }
 declare type TooSmallToRenderCheck = (rect: Rect2) => boolean;
+/** Part of the Editor's image. @internal */
 export declare class ImageNode {
     private parent;
     private content;