js-draw 0.23.0 → 0.24.0

package/README.md

@@ -1,217 +0,0 @@
-# js-draw
-
-[NPM package](https://www.npmjs.com/package/js-draw) | [GitHub](https://github.com/personalizedrefrigerator/js-draw) | [Documentation](https://personalizedrefrigerator.github.io/js-draw/typedoc/modules/lib.html) | [Try it!](https://personalizedrefrigerator.github.io/js-draw/example/example.html)
-
-![](docs/img/js-draw.jpg)
-
-For example usage, see [one of the examples](https://github.com/personalizedrefrigerator/js-draw/blob/main/docs/examples.md) or read [the documentation](https://personalizedrefrigerator.github.io/js-draw/typedoc/modules/lib.html).
-
-# API
-
-To use `js-draw`,
-
-## Creating an `Editor`
-
-### With a bundler that supports importing `.css` files
-
-To create a new `Editor` and add it as a child of `document.body`,
-```ts
-import Editor from 'js-draw';
-import 'js-draw/styles';
-
-const editor = new Editor(document.body);
-```
-
-The `import js-draw/styles` step requires a bundler that can import `.css` files. For example, [`webpack` with `css-loader`.](https://webpack.js.org/loaders/css-loader/)
-
-### With a bundler that doesn't support importing `.css` files
-
-Import the pre-bundled version of the editor to apply CSS after loading the page.
-```ts
-import Editor from 'js-draw';
-import 'js-draw/bundledStyles';
-
-const editor = new Editor(document.body);
-```
-`js-draw/bundledStyles` is a version of the editor's stylesheets pre-processed by `Webpack`. As such, `import`ing or including it with a `<script src="..."></script>` tag applies editor-specific CSS to the document.
-
-### Without a bundler
-
-If you're not using a bundler, consider using the pre-bundled editor:
-```html
-<!-- Replace 0.20.0 with the latest version of js-draw -->
-<script src="https://cdn.jsdelivr.net/npm/js-draw@0.20.0/dist/bundle.js"></script>
-<script>
-    const editor = new jsdraw.Editor(document.body);
-    editor.addToolbar();
-    editor.getRootElement().style.height = '600px';
-</script>
-```
-
-**Note**: To ensure the CDN-hosted version of `js-draw` hasn't been tampered with, consider [including an `integrity="..."` attribute](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). [Read more about using SRI with JSDelivr](https://www.jsdelivr.com/using-sri-with-dynamic-files).
-
-
-## Adding a toolbar
-
-To create a toolbar with the default tools:
-```ts
-const toolbar = editor.addToolbar();
-```
-
-Custom actions can be added to the toolbar. For example, to add a `save` button:
-```ts
-toolbar.addActionButton('Save', () => {
-    const svgElem = editor.toSVG();
-    console.log('The saved SVG:', svgElem.outerHTML);
-});
-```
-or alternatively, with an icon,
-```ts
-toolbar.addActionButton({
-  label: 'Save'
-  icon: editor.icons.makeSaveIcon(),
-}, () => {
-    // Save content here.
-});
-```
-
-## Loading from an SVG
-
-```ts
-editor.loadFromSVG(`
-    <svg
-        viewBox="156 74 200 150"
-        width="200" height="150"
-    >
-        <path d="M156,150Q190,190 209,217L213,215Q193,187 160,148M209,217Q212,218 236,178L232,176Q210,215 213,215M236,178Q240,171 307,95L305,93Q237,168 232,176M307,95Q312,90 329,78L327,74Q309,87 305,93" fill="#07a837"></path>
-    </svg>
-`);
-```
-
-**Note**: While `js-draw` supports a small subset of the SVG markup language, it tries to preserve unrecognised SVG elements.
-
-For example, although `js-draw` doesn't support `<circle/>` elements,
-```xml
-<svg
-    viewBox="156 74 200 150"
-    width="200" height="150"
->
-    <path d="M156,150Q190,190 209,217L213,215Q193,187 160,148M209,217Q212,218 236,178L232,176Q210,215 213,215M236,178Q240,171 307,95L305,93Q237,168 232,176M307,95Q312,90 329,78L327,74Q309,87 305,93" fill="#07a837"></path>
-    <circle cx=200 cy=100 r=40 fill='red'/>
-</svg>
-```
-renders as
-
-![screenshot of the image editor, displaying a green checkmark. The circle is invisible](docs/img/unsupported-elements--in-editor.png)
-
-but exports to
-```xml
-<svg viewBox="156 74 200 150" width="200" height="150" version="1.1" baseProfile="full" xmlns="http://www.w3.org/2000/svg"><g><path d="M156,150M156,150Q190,190 209,217L213,215Q193,187 160,148M209,217M209,217Q212,218 236,178L232,176Q210,215 213,215M236,178M236,178Q240,171 307,95L305,93Q237,168 232,176M307,95M307,95Q312,90 329,78L327,74Q309,87 305,93" fill="#07a837"></path></g><circle cx="200" cy="100" r="40" fill="red"></circle></svg>
-```
-
-which **does** contain the `<circle/>` element.
-
-## Settings/configuration
-### Disabling touchpad panning
-
-Touchpad/mousewheel pan gestures can conflict with gestures used to scroll the document. To turn off touchpad pan gestures (and scrolling the editor with the mousewheel),
-```ts
-const editor = new Editor(document.body, {
-    wheelEventsEnabled: false,
-});
-```
-
-Alternatively, to only enable touchpad panning when the editor has focus,
-```ts
-const editor = new Editor(document.body, {
-    wheelEventsEnabled: 'only-if-focused',
-});
-```
-
-### Localization
-
-If a user's language is available in [src/localizations/](src/localizations/) (as determined by `navigator.languages`), that localization will be used.
-
-To override the default language, use `getLocalizationTable([ 'custom locale here' ])`. For example,
-```ts
-const editor = new Editor(document.body, {
-    // Force the Spanish (Español) localizaiton
-    localization: getLocalizationTable([ 'es' ]),
-});
-```
-
-<details><summary>Creating a custom localization</summary>
-
-See [src/localization.ts](src/localization.ts) for a list of strings that can be translated.
-
-Many of the default strings in the editor might be overridden like this:
-```ts
-const editor = new Editor(document.body, {
-    // Example partial Spanish localization
-    localization: {
-        // Not all translated strings need to be specified. If a string isn't given,
-        // the English (default) localization will be used
-
-        // Strings for the main editor interface
-        // (see src/localization.ts)
-        loading: (percentage: number) => `Cargando: ${percentage}%...`,
-        imageEditor: 'Editor de dibujos',
-
-        undoAnnouncement: (commandDescription: string) => `${commandDescription} fue deshecho`,
-        redoAnnouncement: (commandDescription: string) => `${commandDescription} fue rehecho`,
-
-        // Strings for the toolbar
-        // (see src/toolbar/localization.ts)
-        pen: 'Lapiz',
-        eraser: 'Borrador',
-        select: 'Selecciona',
-        thicknessLabel: 'Tamaño: ',
-        colorLabel: 'Color: ',
-
-        ...
-    },
-});
-```
-
-</details>
-
-## Changing the editor's color theme
-
-The editor's color theme is specified using CSS. Its default theme looks like this:
-```css
-.imageEditorContainer {
-    /* Deafult colors for the editor -- light mode */
-
-    --primary-background-color: white;
-    --primary-background-color-transparent: rgba(255, 255, 255, 0.5);
-    --secondary-background-color: #faf;
-    --primary-foreground-color: black;
-    --secondary-foreground-color: black;
-    --primary-shadow-color: rgba(0, 0, 0, 0.5);
-}
-
-@media (prefers-color-scheme: dark) {
-    .imageEditorContainer {
-        /* Deafult colors for the editor -- dark mode */
-
-        --primary-background-color: #151515;
-        --primary-background-color-transparent: rgba(50, 50, 50, 0.5);
-        --secondary-background-color: #607;
-        --primary-foreground-color: white;
-        --secondary-foreground-color: white;
-        --primary-shadow-color: rgba(250, 250, 250, 0.5);
-    }
-}
-```
-
-To override it, use a more specific CSS selector to set the theme variables. For example,
-```css
-body .imageEditorContainer {
-    --primary-background-color: green;
-    --primary-background-color-transparent: rgba(255, 240, 200, 0.5);
-    --secondary-background-color: yellow;
-    --primary-foreground-color: black;
-    --secondary-foreground-color: black;
-}
-```
-disables the dark theme and creates a theme that primarily uses yellow/green colors.

package/__mocks__/coloris.ts

@@ -1,8 +0,0 @@
-
-// @melloware/coloris tries to use the HTML5Canvas on import, which is not supported by
-// JSDom (without installing additional packages). As such, we need to mock it.
-
-export const coloris = (_options: any): void => {
-};
-
-export const init = () => {};

package/__mocks__/styleMock.js

@@ -1 +0,0 @@
-module.exports = {};

package/dist/cjs/src/Color4.js

@@ -1,264 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Color4 = void 0;
-const Vec3_1 = __importDefault(require("./math/Vec3"));
-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_1.default.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);
-exports.default = Color4;
-exports.Color4 = Color4;