js-draw 0.18.1 → 0.19.0

package/dist/mjs/src/Color4.mjs

@@ -0,0 +1,257 @@
+import  Vec3  from './math/Vec3.mjs';
+export default class Color4 {
+    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]. 0 = transparent */
+    a) {
+        this.r = r;
+        this.g = g;
+        this.b = b;
+        this.a = a;
+        this.hexString = null;
+    }
+    /**
+     * 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);
+    }
+    static ofRGBA(red, green, blue, alpha) {
+        red = Math.max(0, Math.min(red, 1));
+        green = Math.max(0, Math.min(green, 1));
+        blue = Math.max(0, Math.min(blue, 1));
+        alpha = Math.max(0, Math.min(alpha, 1));
+        return new Color4(red, green, blue, alpha);
+    }
+    static fromHex(hexString) {
+        var _a;
+        // Remove starting '#' (if present)
+        hexString = ((_a = hexString.match(/^[#]?(.*)$/)) !== null && _a !== void 0 ? _a : [])[1];
+        hexString = hexString.toUpperCase();
+        if (!hexString.match(/^[0-9A-F]+$/)) {
+            throw new Error(`${hexString} is not in a valid format.`);
+        }
+        // RGBA or RGB
+        if (hexString.length === 3 || hexString.length === 4) {
+            // Each character is a component
+            const components = hexString.split('');
+            // Convert to RRGGBBAA or RRGGBB format
+            hexString = components.map(component => `${component}0`).join('');
+        }
+        if (hexString.length === 6) {
+            // Alpha component
+            hexString += 'FF';
+        }
+        const components = [];
+        for (let i = 2; i <= hexString.length; i += 2) {
+            const chunk = hexString.substring(i - 2, i);
+            components.push(parseInt(chunk, 16) / 255);
+        }
+        if (components.length !== 4) {
+            throw new Error(`Unable to parse ${hexString}: Wrong number of components.`);
+        }
+        return Color4.ofRGBA(components[0], components[1], components[2], components[3]);
+    }
+    /** Like fromHex, but can handle additional colors if an `HTMLCanvasElement` is available. */
+    static fromString(text) {
+        if (text.startsWith('#')) {
+            return Color4.fromHex(text);
+        }
+        if (text === 'none' || text === 'transparent') {
+            return Color4.transparent;
+        }
+        // rgba?: Match both rgb and rgba strings.
+        // ([,0-9.]+): Match any string of only numeric, '.' and ',' characters.
+        const rgbRegex = /^rgba?\(([,0-9.]+)\)$/i;
+        const rgbMatch = text.replace(/\s*/g, '').match(rgbRegex);
+        if (rgbMatch) {
+            const componentsListStr = rgbMatch[1];
+            const componentsList = JSON.parse(`[ ${componentsListStr} ]`);
+            if (componentsList.length === 3) {
+                return Color4.ofRGB(componentsList[0] / 255, componentsList[1] / 255, componentsList[2] / 255);
+            }
+            else if (componentsList.length === 4) {
+                return Color4.ofRGBA(componentsList[0] / 255, componentsList[1] / 255, componentsList[2] / 255, componentsList[3]);
+            }
+            else {
+                throw new Error(`RGB string, ${text}, has wrong number of components: ${componentsList.length}`);
+            }
+        }
+        // Otherwise, try to use an HTMLCanvasElement to determine the color.
+        // Note: We may be unable to create an HTMLCanvasElement if running as a unit test.
+        const canvas = document.createElement('canvas');
+        canvas.width = 1;
+        canvas.height = 1;
+        const ctx = canvas.getContext('2d');
+        ctx.fillStyle = text;
+        ctx.fillRect(0, 0, 1, 1);
+        const data = ctx.getImageData(0, 0, 1, 1);
+        const red = data.data[0] / 255;
+        const green = data.data[1] / 255;
+        const blue = data.data[2] / 255;
+        const alpha = data.data[3] / 255;
+        return Color4.ofRGBA(red, green, blue, alpha);
+    }
+    /** @returns true if `this` and `other` are approximately equal. */
+    eq(other) {
+        if (other == null) {
+            return false;
+        }
+        // If both completely transparent,
+        if (this.a === 0 && other.a === 0) {
+            return true;
+        }
+        return this.toHexString() === other.toHexString();
+    }
+    /**
+     * If `fractionTo` is not in the range [0, 1], it will be clamped to the nearest number
+     * in that range. For example, `a.mix(b, -1)` is equivalent to `a.mix(b, 0)`.
+     *
+     * @returns a color `fractionTo` of the way from this color to `other`.
+     *
+     * @example
+     * ```ts
+     * Color4.ofRGB(1, 0, 0).mix(Color4.ofRGB(0, 1, 0), 0.1) // -> Color4(0.9, 0.1, 0)
+     * ```
+     */
+    mix(other, fractionTo) {
+        fractionTo = Math.min(Math.max(fractionTo, 0), 1);
+        const fractionOfThis = 1 - fractionTo;
+        return new Color4(this.r * fractionOfThis + other.r * fractionTo, this.g * fractionOfThis + other.g * fractionTo, this.b * fractionOfThis + other.b * fractionTo, this.a * fractionOfThis + other.a * fractionTo);
+    }
+    /**
+     * @returns the component-wise average of `colors`, or `Color4.transparent` if `colors` is empty.
+     */
+    static average(colors) {
+        let averageA = 0;
+        let averageR = 0;
+        let averageG = 0;
+        let averageB = 0;
+        for (const color of colors) {
+            averageA += color.a;
+            averageR += color.r;
+            averageG += color.g;
+            averageB += color.b;
+        }
+        if (colors.length > 0) {
+            averageA /= colors.length;
+            averageR /= colors.length;
+            averageG /= colors.length;
+            averageB /= colors.length;
+        }
+        return new Color4(averageR, averageG, averageB, averageA);
+    }
+    /**
+     * Converts to (hue, saturation, value).
+     * See also https://en.wikipedia.org/wiki/HSL_and_HSV#General_approach
+     *
+     * The resultant hue is represented in radians and is thus in [0, 2pi].
+     */
+    asHSV() {
+        // Ref: https://en.wikipedia.org/wiki/HSL_and_HSV#General_approach
+        //
+        // HUE:
+        // First, consider the unit cube. Rotate it such that one vertex is at the origin
+        // of a plane and its three neighboring vertices are equidistant from that plane:
+        //
+        //         /\
+        //       /  | \
+        //   2 /    3   \ 1
+        //     \    |   /
+        //       \  | /
+        //   .     \/      .
+        //                 
+        //        .        
+        //
+        // Let z be up and (x, y, 0) be in the plane.
+        //
+        // Label vectors 1,2,3 with R, G, and B, respectively. Let R's projection into the plane
+        // lie along the x axis.
+        //
+        // Because R is a unit vector and R, G, B are equidistant from the plane, they must
+        // form 30-60-90 triangles, which have side lengths proportional to (1, √3, 2)
+        //
+        //       /|
+        //    1/  | (√3)/2
+        //    /   |
+        //      1/2   
+        //
+        const minComponent = Math.min(this.r, this.g, this.b);
+        const maxComponent = Math.max(this.r, this.g, this.b);
+        const chroma = maxComponent - minComponent;
+        let hue;
+        // See https://en.wikipedia.org/wiki/HSL_and_HSV#General_approach
+        if (chroma === 0) {
+            hue = 0;
+        }
+        else if (this.r >= this.g && this.r >= this.b) {
+            hue = ((this.g - this.b) / chroma) % 6;
+        }
+        else if (this.g >= this.r && this.g >= this.b) {
+            hue = (this.b - this.r) / chroma + 2;
+        }
+        else {
+            hue = (this.r - this.g) / chroma + 4;
+        }
+        // Convert to degree representation, then to radians.
+        hue *= 60;
+        hue *= Math.PI / 180;
+        // Ensure positivity.
+        if (hue < 0) {
+            hue += Math.PI * 2;
+        }
+        const value = maxComponent;
+        const saturation = value > 0 ? chroma / value : 0;
+        return Vec3.of(hue, saturation, value);
+    }
+    /**
+     * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.
+     *
+     * @example
+     * ```
+     * Color4.red.toHexString(); // -> #ff0000ff
+     * ```
+     */
+    toHexString() {
+        if (this.hexString) {
+            return this.hexString;
+        }
+        const componentToHex = (component) => {
+            const res = Math.round(255 * component).toString(16);
+            if (res.length === 1) {
+                return `0${res}`;
+            }
+            return res;
+        };
+        const alpha = componentToHex(this.a);
+        const red = componentToHex(this.r);
+        const green = componentToHex(this.g);
+        const blue = componentToHex(this.b);
+        if (alpha === 'ff') {
+            return `#${red}${green}${blue}`;
+        }
+        this.hexString = `#${red}${green}${blue}${alpha}`;
+        return this.hexString;
+    }
+    toString() {
+        return this.toHexString();
+    }
+}
+Color4.transparent = Color4.ofRGBA(0, 0, 0, 0);
+Color4.red = Color4.ofRGB(1.0, 0.0, 0.0);
+Color4.green = Color4.ofRGB(0.0, 1.0, 0.0);
+Color4.blue = Color4.ofRGB(0.0, 0.0, 1.0);
+Color4.purple = Color4.ofRGB(0.5, 0.2, 0.5);
+Color4.yellow = Color4.ofRGB(1, 1, 0.1);
+Color4.clay = Color4.ofRGB(0.8, 0.4, 0.2);
+Color4.black = Color4.ofRGB(0, 0, 0);
+Color4.gray = Color4.ofRGB(0.5, 0.5, 0.5);
+Color4.white = Color4.ofRGB(1, 1, 1);
+export { Color4 };

package/dist/mjs/src/Editor.d.ts

@@ -0,0 +1,308 @@
+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 './math/Vec2';
+import HTMLToolbar from './toolbar/HTMLToolbar';
+import { RenderablePathSpec } from './rendering/renderers/AbstractRenderer';
+import Display, { RenderingMode } from './rendering/Display';
+import Color4 from './Color4';
+import Pointer from './Pointer';
+import Rect2 from './math/Rect2';
+import { EditorLocalization } from './localization';
+import IconProvider from './toolbar/IconProvider';
+import AbstractComponent from './components/AbstractComponent';
+type HTMLPointerEventType = 'pointerdown' | 'pointermove' | 'pointerup' | 'pointercancel';
+type HTMLPointerEventFilter = (eventName: HTMLPointerEventType, event: PointerEvent) => boolean;
+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;
+    iconProvider: IconProvider;
+}
+/**
+ * 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...
+ * });
+ * ```
+ *
+ * See also
+ * [`docs/example/example.ts`](https://github.com/personalizedrefrigerator/js-draw/blob/main/docs/example/example.ts#L15).
+ */
+export declare class Editor {
+    private container;
+    private renderingRegion;
+    /** Manages drawing surfaces/{@link AbstractRenderer}s. */
+    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);
+     * ```
+     */
+    readonly image: EditorImage;
+    /**
+     * Allows transforming the view and querying information about
+     * what is currently visible.
+     */
+    readonly viewport: Viewport;
+    /** @internal */
+    readonly localization: EditorLocalization;
+    /** {@link EditorSettings.iconProvider} */
+    readonly icons: IconProvider;
+    /**
+     * Controls the list of tools. See
+     * [the custom tool example](https://github.com/personalizedrefrigerator/js-draw/tree/main/docs/example-custom-tools)
+     * for more.
+     */
+    readonly toolController: ToolController;
+    /**
+     * Global event dispatcher/subscriber.
+     */
+    readonly notifier: EditorNotifier;
+    private loadingWarning;
+    private accessibilityAnnounceArea;
+    private accessibilityControlArea;
+    private eventListenerTargets;
+    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();
+     *
+     * // Add a save button
+     * 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
+     * ```
+     *   // Set the editor's height to 500px
+     *   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;
+    /**
+     * Announce `message` for screen readers. If `message` is the same as the previous
+     * message, it is re-announced.
+     */
+    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;
+    private pointers;
+    private getPointerList;
+    /**
+     * Dispatches a `PointerEvent` to the editor. The target element for `evt` must have the same top left
+     * as the content of the editor.
+     */
+    handleHTMLPointerEvent(eventType: 'pointerdown' | 'pointermove' | 'pointerup' | 'pointercancel', evt: PointerEvent): boolean;
+    private isEventSink;
+    private handlePaste;
+    /**
+     * Forward pointer events from `elem` to this editor. Such that right-click/right-click drag
+     * events are also forwarded, `elem`'s contextmenu is disabled.
+     *
+     * @example
+     * ```ts
+     * const overlay = document.createElement('div');
+     * editor.createHTMLOverlay(overlay);
+     *
+     * // Send all pointer events that don't have the control key pressed
+     * // to the editor.
+     * editor.handlePointerEventsFrom(overlay, (event) => {
+     *   if (event.ctrlKey) {
+     *     return false;
+     *   }
+     *   return true;
+     * });
+     * ```
+     */
+    handlePointerEventsFrom(elem: HTMLElement, filter?: HTMLPointerEventFilter): void;
+    /** 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 | Promise<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 | Promise<void>;
+    /**
+     * 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, unapplyInReverseOrder?: boolean): Promise<void>;
+    private announceUndoCallback;
+    private announceRedoCallback;
+    private nextRerenderListeners;
+    private rerenderQueued;
+    /**
+     * 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.
+     *
+     * @returns a promise that resolves when re-rendering has completed.
+     */
+    queueRerender(): Promise<void>;
+    isRerenderQueued(): boolean;
+    /**
+     * Re-renders the entire image.
+     *
+     * @see {@link Editor.queueRerender}
+     */
+    rerender(showImageBounds?: boolean): void;
+    /**
+     * Draws the given path onto the wet ink renderer. The given path will
+     * be displayed on top of the main image.
+     *
+     * @see {@link Display.getWetInkRenderer} {@link Display.flatten}
+     */
+    drawWetInk(...path: RenderablePathSpec[]): void;
+    /**
+     * Clears the wet ink display.
+     *
+     * @see {@link Display.getWetInkRenderer}
+     */
+    clearWetInk(): void;
+    /**
+     * Focuses the region used for text input/key commands.
+     */
+    focus(): void;
+    /**
+     * Creates an element that will be positioned on top of the dry/wet ink
+     * renderers.
+     *
+     * This is useful for displaying content on top of the rendered content
+     * (e.g. a selection box).
+     */
+    createHTMLOverlay(overlay: HTMLElement): {
+        remove: () => void;
+    };
+    addStyleSheet(content: string): HTMLStyleElement;
+    sendKeyboardEvent(eventType: InputEvtType.KeyPressEvent | InputEvtType.KeyUpEvent, key: string, ctrlKey?: boolean, altKey?: boolean): void;
+    /**
+     * Dispatch a pen event to the currently selected tool.
+     * Intended primarially for unit tests.
+     *
+     * @deprecated
+     * @see {@link sendPenEvent} {@link sendTouchEvent}
+     */
+    sendPenEvent(eventType: InputEvtType.PointerDownEvt | InputEvtType.PointerMoveEvt | InputEvtType.PointerUpEvt, point: Point2, allPointers?: Pointer[]): void;
+    addAndCenterComponents(components: AbstractComponent[], selectComponents?: boolean): Promise<void>;
+    toDataURL(format?: 'image/png' | 'image/jpeg' | 'image/webp'): string;
+    toSVG(): SVGElement;
+    /**
+     * Load editor data from an `ImageLoader` (e.g. an {@link SVGLoader}).
+     *
+     * @see loadFromSVG
+     */
+    loadFrom(loader: ImageLoader): Promise<void>;
+    private getTopmostBackgroundComponent;
+    /**
+     * Set the background color of the image.
+     */
+    setBackgroundColor(color: Color4): Command;
+    /**
+     * @returns the average of the colors of all background components. Use this to get the current background
+     * color.
+     */
+    estimateBackgroundColor(): Color4;
+    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, sanitize?: boolean): Promise<void>;
+}
+export default Editor;