js-draw 0.17.3 → 0.18.0

package/dist/cjs/build_tools/BundledFile.js

@@ -0,0 +1,163 @@
+"use strict";
+// This file is taken from Joplin: https://github.com/laurent22/joplin
+// js-draw was originally created as a part of a pull request for joplin. This
+// is part of the functionality from Joplin it requires.
+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) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = require("path");
+const terser_webpack_plugin_1 = __importDefault(require("terser-webpack-plugin"));
+const webpack_1 = __importDefault(require("webpack"));
+class BundledFile {
+    constructor(bundleName, sourceFilePath, outputFilepath) {
+        this.bundleName = bundleName;
+        this.sourceFilePath = sourceFilePath;
+        this.rootFileDirectory = (0, path_1.dirname)(sourceFilePath);
+        this.bundleBaseName = (0, path_1.basename)(sourceFilePath, (0, path_1.extname)(sourceFilePath));
+        if (outputFilepath) {
+            this.outputDirectory = (0, path_1.dirname)(outputFilepath);
+            this.outputFilename = (0, path_1.basename)(outputFilepath);
+        }
+        else {
+            this.outputDirectory = this.rootFileDirectory;
+            this.outputFilename = `${this.bundleBaseName}.bundle.js`;
+        }
+    }
+    getWebpackOptions(mode) {
+        const config = {
+            mode,
+            entry: this.sourceFilePath,
+            output: {
+                path: this.outputDirectory,
+                filename: this.outputFilename,
+                library: {
+                    type: 'window',
+                    name: this.bundleName,
+                },
+            },
+            // See https://webpack.js.org/guides/typescript/
+            module: {
+                rules: [
+                    {
+                        // Include .tsx to include react components
+                        test: /\.tsx?$/i,
+                        use: 'ts-loader',
+                        exclude: /node_modules/,
+                    },
+                    {
+                        test: /\.css$/i,
+                        use: ['style-loader', 'css-loader'],
+                    },
+                ],
+            },
+            optimization: {
+                minimizer: [
+                    // Don't create separate files for comments.
+                    // See https://stackoverflow.com/a/65650316/17055750
+                    new terser_webpack_plugin_1.default({
+                        extractComments: false,
+                    }),
+                ],
+            },
+            // Increase the minimum size required
+            // to trigger warnings.
+            // See https://stackoverflow.com/a/53517149/17055750
+            performance: {
+                maxAssetSize: 2000000,
+                maxEntrypointSize: 2000000,
+            },
+            resolve: {
+                extensions: ['.tsx', '.ts', '.js'],
+            },
+        };
+        return config;
+    }
+    handleErrors(err, stats) {
+        let failed = false;
+        if (err) {
+            console.error(`Error: ${err.name}`, err.message, err.stack);
+            failed = true;
+        }
+        else if ((stats === null || stats === void 0 ? void 0 : stats.hasErrors()) || (stats === null || stats === void 0 ? void 0 : stats.hasWarnings())) {
+            const data = stats.toJson();
+            if (data.warnings && data.warningsCount) {
+                console.warn('Warnings: ', data.warningsCount);
+                for (const warning of data.warnings) {
+                    // Stack contains the message
+                    if (warning.stack) {
+                        console.warn(warning.stack);
+                    }
+                    else {
+                        console.warn(warning.message);
+                    }
+                }
+            }
+            if (data.errors && data.errorsCount) {
+                console.error('Errors: ', data.errorsCount);
+                for (const error of data.errors) {
+                    if (error.stack) {
+                        console.error(error.stack);
+                    }
+                    else {
+                        console.error(error.message);
+                    }
+                    console.error();
+                }
+                failed = true;
+            }
+        }
+        return failed;
+    }
+    // Create a minified JS file in the same directory as `this.sourceFilePath` with
+    // the same name.
+    build() {
+        const compiler = (0, webpack_1.default)(this.getWebpackOptions('production'));
+        return new Promise((resolve, reject) => {
+            console.info(`Building bundle: ${this.bundleName}...`);
+            compiler.run((err, stats) => {
+                let failed = this.handleErrors(err, stats);
+                // Clean up.
+                compiler.close((error) => __awaiter(this, void 0, void 0, function* () {
+                    if (error) {
+                        console.error('Error cleaning up:', error);
+                        failed = true;
+                    }
+                    if (!failed) {
+                        console.log('☑ Done building! ☑');
+                        resolve();
+                    }
+                    else {
+                        reject();
+                    }
+                }));
+            });
+        });
+    }
+    startWatching() {
+        const compiler = (0, webpack_1.default)(this.getWebpackOptions('development'));
+        const watchOptions = {
+            ignored: [
+                '**/node_modules',
+                '**/dist',
+            ],
+        };
+        console.info('Watching bundle: ', this.bundleName);
+        compiler.watch(watchOptions, (err, stats) => __awaiter(this, void 0, void 0, function* () {
+            const failed = this.handleErrors(err, stats);
+            if (!failed) {
+                console.log('☑ Built! ☑');
+            }
+        }));
+    }
+}
+exports.default = BundledFile;

package/dist/cjs/build_tools/buildTranslationTemplate.js

@@ -0,0 +1,119 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const localization_1 = require("../src/localization");
+// Adds markdown formatting to format text like code.
+const codeFormat = (text) => {
+    let maxConsecutiveBackticks = 0;
+    // Find the longest number of consecutive backticks — we need to have more
+    // than that for the delimiters.
+    const backtickRuns = text.matchAll(/[`]+/g);
+    for (const backticks of backtickRuns) {
+        if (backticks.length > maxConsecutiveBackticks) {
+            maxConsecutiveBackticks = backticks.length;
+        }
+    }
+    let codeStartEnd = '';
+    for (let i = 0; i < maxConsecutiveBackticks + 1; i++) {
+        codeStartEnd += '`';
+    }
+    // If the text already starts with a `, add a space to prevent the
+    // markdown parser from treating it as part of the delimiter.
+    if (text.startsWith('`')) {
+        text = ' ' + text;
+    }
+    if (text.endsWith('`')) {
+        text = text + ' ';
+    }
+    return `${codeStartEnd}${text}${codeStartEnd}`;
+};
+const collapseSpaces = (text) => text.replace(/\s+/g, ' ');
+const generateTranslationTemplate = () => {
+    const bodyContentLines = [];
+    const addInput = (type, id, attrs, required = false) => {
+        const lines = [];
+        lines.push(`  - type: ${type}`);
+        lines.push(`    id: ${id}`);
+        lines.push('    attributes:');
+        for (const key in attrs) {
+            const value = `${attrs[key]}`;
+            const escapedValue = value.replace(/[\\]/g, '\\\\').replace(/"/g, '\\"');
+            lines.push(`      ${key}: "${escapedValue}"`);
+        }
+        lines.push('    validations:');
+        lines.push(`      required: ${required}`);
+        bodyContentLines.push(...lines);
+    };
+    const addLabel = (text) => {
+        bodyContentLines.push('  - type: markdown');
+        bodyContentLines.push('    attributes:');
+        bodyContentLines.push('      value: |');
+        bodyContentLines.push('        ' + text);
+    };
+    addLabel(collapseSpaces(`
+		Thank you for taking the time to translate \`js-draw\`! If you don't have time to translate
+		all of the strings below, feel free to submit an incomplete translation and edit it later.
+		Use this template to update an existing translation or to create a new translation.
+	`));
+    addLabel(collapseSpaces(`
+		(Optional) If you would like to submit a pull request that applies this translation, 
+		note that existing translations are present in
+		[src/localizations/](https://github.com/personalizedrefrigerator/js-draw/tree/main/src/localizations).
+	`));
+    addInput('input', 'language-name', {
+        label: 'Language',
+        description: 'The name of the language to translate to in English (e.g. Spanish)',
+    }, true);
+    for (const key in localization_1.defaultEditorLocalization) {
+        const englishTranslation = `${localization_1.defaultEditorLocalization[key]}`;
+        addInput('input', `translation-${key}`, {
+            label: `${key}`,
+            description: `Translate ${codeFormat(englishTranslation)}.`,
+            placeholder: englishTranslation,
+        });
+    }
+    addInput('textarea', 'additional-comments', {
+        label: 'Additional information',
+        placeholder: 'Any additional information/comments on the translation can go here.',
+    });
+    return `name: Translation
+# This template is auto-generated by build_tools/buildTranslationTemplate.ts
+# Do not modify it directly.
+description: Translate the editor to a new language!
+title: "[Translation]: <language>"
+labels: [localization]
+assignees: []
+body:
+${bodyContentLines.join('\n')}`;
+};
+const template = generateTranslationTemplate();
+// According to https://stackoverflow.com/a/13650454, fs should
+// be able to handle forward and back slashes (both) on Windows (so extra
+// path logic shouldn't be needed here.)
+const rootDir = path.dirname(__dirname);
+const translationTempaltePath = path.join(rootDir, '.github/ISSUE_TEMPLATE/translation.yml');
+fs.writeFileSync(translationTempaltePath, template);

package/dist/cjs/build_tools/bundle.js

@@ -0,0 +1,10 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = require("path");
+const BundledFile_1 = __importDefault(require("./BundledFile"));
+const rootDir = (0, path_1.dirname)(__dirname);
+const mainBundle = new BundledFile_1.default('jsdraw', `${rootDir}/src/bundle/bundled.ts`, `${rootDir}/dist/bundle.js`);
+void mainBundle.build();

package/dist/cjs/build_tools/postDist.js

@@ -0,0 +1,72 @@
+"use strict";
+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) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = require("fs/promises");
+const path_1 = __importDefault(require("path"));
+// Script to be run after building JavaScript files from TypeScript.
+// TODO: This is very hacky.
+// TODO: [Use the TypeScript Compiler API instead.](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API)
+// Iterates over every JavaScript file in [directory].
+const forEachFile = (directory, processFile) => __awaiter(void 0, void 0, void 0, function* () {
+    const files = yield (0, promises_1.readdir)(directory);
+    yield Promise.all(files.map((file) => __awaiter(void 0, void 0, void 0, function* () {
+        const filePath = path_1.default.join(directory, file);
+        const stats = yield (0, promises_1.stat)(filePath);
+        if (stats.isDirectory()) {
+            yield forEachFile(filePath, processFile);
+        }
+        else if (stats.isFile()) {
+            yield processFile(filePath);
+        }
+        else {
+            throw new Error('Unknown file type!');
+        }
+    })));
+});
+const removeFiles = (directory, filePattern) => __awaiter(void 0, void 0, void 0, function* () {
+    yield forEachFile(directory, (filePath) => __awaiter(void 0, void 0, void 0, function* () {
+        if (!filePath.match(filePattern)) {
+            return;
+        }
+        yield (0, promises_1.unlink)(filePath);
+    }));
+});
+const main = () => __awaiter(void 0, void 0, void 0, function* () {
+    const rootDir = path_1.default.dirname(__dirname);
+    const cjsPath = `${rootDir}/dist/cjs`;
+    const mjsPath = `${rootDir}/dist/mjs`;
+    const testPattern = /\.test\.js$/;
+    yield removeFiles(cjsPath, testPattern);
+    yield removeFiles(mjsPath, testPattern);
+    // We need to replace imports in ESM files.
+    yield forEachFile(mjsPath, (filePath) => __awaiter(void 0, void 0, void 0, function* () {
+        if (!filePath.endsWith('.js')) {
+            return;
+        }
+        // Rename
+        const newPath = filePath.replace(/\.js$/, '.mjs');
+        yield (0, promises_1.rename)(filePath, newPath);
+        // Change imports from
+        //   import foo from './bar'
+        // to
+        //   import foo from './bar.mjs'
+        // and exports similarly.
+        let contents = yield (0, promises_1.readFile)(newPath, { encoding: 'utf-8' });
+        // TODO: Switch to using the TypeScript compiler API. This has the danger of changing imports
+        // in multi-line strings.
+        contents = contents.replace(/([\n]|^)(import|export)(.*)from\s+(['"])(\.*\/[^\n]+)(['"])/g, '$1$2 $3 from $4$5.mjs$6');
+        yield (0, promises_1.writeFile)(newPath, contents);
+    }));
+});
+main();

package/dist/{src → cjs/src}/Color4.d.ts

@@ -58,3 +58,4 @@ export default class Color4 {
     static gray: Color4;
     static white: Color4;
 }
+export { Color4 };

package/dist/cjs/src/Color4.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Color4 = void 0;
+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);
+    }
+    /**
+     * @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();
+    }
+}
+exports.default = Color4;
+exports.Color4 = Color4;
+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);

package/dist/{src → cjs/src}/Editor.d.ts

@@ -46,6 +46,9 @@ export interface EditorSettings {
  *   // 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;
@@ -123,6 +126,8 @@ export declare class Editor {
      *
      * // Add the default toolbar
      * const toolbar = editor.addToolbar();
+     *
+     * // Add a save button
      * toolbar.addActionButton({
      *   label: 'Save'
      *   icon: createSaveIcon(),
@@ -138,6 +143,7 @@ export declare class Editor {
      *
      * @example
      * ```
+     *   // Set the editor's height to 500px
      *   editor.getRootElement().style.height = '500px';
      * ```
      */
@@ -146,6 +152,10 @@ export declare class Editor {
     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.
@@ -162,6 +172,25 @@ export declare class 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;
@@ -200,25 +229,52 @@ export declare class Editor {
      * 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
+     * @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;