js-draw 1.17.0 → 1.18.0

package/dist/cjs/tools/lib.d.ts

@@ -1,6 +1,3 @@
-/**
- * @packageDocumentation
- */
 export { default as BaseTool } from './BaseTool';
 export { default as ToolController } from './ToolController';
 export { default as ToolEnabledGroup } from './ToolEnabledGroup';
@@ -11,7 +8,7 @@ export { default as PenTool, PenStyle } from './Pen';
 export { default as TextTool } from './TextTool';
 export { default as SelectionTool } from './SelectionTool/SelectionTool';
 export { default as SelectAllShortcutHandler } from './SelectionTool/SelectAllShortcutHandler';
-export { default as EraserTool } from './Eraser';
+export { default as EraserTool, EraserMode } from './Eraser';
 export { default as PasteHandler } from './PasteHandler';
 export { default as SoundUITool } from './SoundUITool';
 export { default as ToolbarShortcutHandler } from './ToolbarShortcutHandler';

package/dist/cjs/tools/lib.js

@@ -1,12 +1,9 @@
 "use strict";
-/**
- * @packageDocumentation
- */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolbarShortcutHandler = exports.SoundUITool = exports.PasteHandler = exports.EraserTool = exports.SelectAllShortcutHandler = exports.SelectionTool = exports.TextTool = exports.PenTool = exports.PanZoomMode = exports.PanZoomTool = exports.ToolSwitcherShortcut = exports.UndoRedoShortcut = exports.ToolEnabledGroup = exports.ToolController = exports.BaseTool = void 0;
+exports.ToolbarShortcutHandler = exports.SoundUITool = exports.PasteHandler = exports.EraserMode = exports.EraserTool = exports.SelectAllShortcutHandler = exports.SelectionTool = exports.TextTool = exports.PenTool = exports.PanZoomMode = exports.PanZoomTool = exports.ToolSwitcherShortcut = exports.UndoRedoShortcut = exports.ToolEnabledGroup = exports.ToolController = exports.BaseTool = void 0;
 var BaseTool_1 = require("./BaseTool");
 Object.defineProperty(exports, "BaseTool", { enumerable: true, get: function () { return __importDefault(BaseTool_1).default; } });
 var ToolController_1 = require("./ToolController");
@@ -30,6 +27,7 @@ var SelectAllShortcutHandler_1 = require("./SelectionTool/SelectAllShortcutHandl
 Object.defineProperty(exports, "SelectAllShortcutHandler", { enumerable: true, get: function () { return __importDefault(SelectAllShortcutHandler_1).default; } });
 var Eraser_1 = require("./Eraser");
 Object.defineProperty(exports, "EraserTool", { enumerable: true, get: function () { return __importDefault(Eraser_1).default; } });
+Object.defineProperty(exports, "EraserMode", { enumerable: true, get: function () { return Eraser_1.EraserMode; } });
 var PasteHandler_1 = require("./PasteHandler");
 Object.defineProperty(exports, "PasteHandler", { enumerable: true, get: function () { return __importDefault(PasteHandler_1).default; } });
 var SoundUITool_1 = require("./SoundUITool");

package/dist/cjs/version.js

@@ -6,5 +6,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @internal
  */
 exports.default = {
-    number: '1.17.0',
+    number: '1.18.0',
 };

package/dist/mjs/Editor.d.ts

@@ -79,30 +79,28 @@ export interface EditorSettings {
      * Configures the default pen tools.
      *
      * **Example**:
-     * ```ts,runnable
-     * import { Editor, makePolylineBuilder } from 'js-draw';
-     *
-     * const editor = new Editor(document.body, {
-     *     pens: {
-     *         additionalPenTypes: [{
-     *             name: 'Polyline (For debugging)',
-     *             id: 'custom-polyline',
-     *             factory: makePolylineBuilder,
-     *
-     *             // The pen doesn't create fixed shapes (e.g. squares, rectangles, etc)
-     *             // and so should go under the "pens" section.
-     *             isShapeBuilder: false,
-     *         }],
-     *     },
-     * });
-     * editor.addToolbar();
-     * ```
+     * [[include:doc-pages/inline-examples/editor-settings-polyline-pen.md]]
      */
     pens: {
         /**
          * Additional pen types that can be selected in a toolbar.
          */
-        additionalPenTypes: readonly Readonly<PenTypeRecord>[];
+        additionalPenTypes?: readonly Readonly<PenTypeRecord>[];
+        /**
+         * Should return `true` if a pen type should be shown in the toolbar.
+         *
+         * @example
+         * ```ts,runnable
+         * import {Editor} from 'js-draw';
+         * const editor = new Editor(document.body, {
+         *   // Only allow selecting the polyline pen from the toolbar.
+         *   pens: { filterPenTypes: p => p.id === 'polyline-pen' },
+         * });
+         * editor.addToolbar();
+         * ```
+         * Notice that this setting only affects the toolbar GUI.
+         */
+        filterPenTypes?: (penType: PenTypeRecord) => boolean;
     } | null;
 }
 /**
@@ -123,7 +121,7 @@ export interface EditorSettings {
  * ```
  *
  * See also
- * [`docs/example/example.ts`](https://github.com/personalizedrefrigerator/js-draw/blob/main/docs/demo/example.ts).
+ * * [`examples.md`](https://github.com/personalizedrefrigerator/js-draw/blob/main/docs/examples.md).
  */
 export declare class Editor {
     private container;

package/dist/mjs/Editor.mjs

@@ -47,7 +47,7 @@ import  ClipboardHandler  from './util/ClipboardHandler.mjs';
  * ```
  *
  * See also
- * [`docs/example/example.ts`](https://github.com/personalizedrefrigerator/js-draw/blob/main/docs/demo/example.ts).
+ * * [`examples.md`](https://github.com/personalizedrefrigerator/js-draw/blob/main/docs/examples.md).
  */
 export class Editor {
     /**
@@ -109,7 +109,10 @@ export class Editor {
             iconProvider: settings.iconProvider ?? new IconProvider(),
             notices: [],
             appInfo: settings.appInfo ? { ...settings.appInfo } : null,
-            pens: { additionalPenTypes: settings.pens?.additionalPenTypes ?? [], },
+            pens: {
+                additionalPenTypes: settings.pens?.additionalPenTypes ?? [],
+                filterPenTypes: settings.pens?.filterPenTypes ?? (() => true)
+            },
         };
         // Validate settings
         if (this.settings.minZoom > this.settings.maxZoom) {

package/dist/mjs/components/AbstractComponent.d.ts

@@ -1,8 +1,9 @@
 import SerializableCommand from '../commands/SerializableCommand';
 import EditorImage from '../image/EditorImage';
-import { LineSegment2, Mat33, Rect2 } from '@js-draw/math';
+import { LineSegment2, Mat33, Path, Rect2 } from '@js-draw/math';
 import AbstractRenderer from '../rendering/renderers/AbstractRenderer';
 import { ImageComponentLocalization } from './localization';
+import Viewport from '../Viewport';
 export type LoadSaveData = (string[] | Record<symbol, string | number>);
 export type LoadSaveDataTable = Record<string, Array<LoadSaveData>>;
 export type DeserializeCallback = (data: string) => AbstractComponent;
@@ -112,7 +113,9 @@ export default abstract class AbstractComponent {
      * this function.
      */
     intersectsRect(rect: Rect2): boolean;
-    protected abstract serializeToJSON(): any[] | Record<string, any> | number | string | null;
+    isSelectable(): boolean;
+    isBackground(): boolean;
+    getProportionalRenderingTime(): number;
     protected abstract applyTransformation(affineTransfm: Mat33): void;
     /**
      * Returns a command that, when applied, transforms this by [affineTransfm] and
@@ -131,9 +134,6 @@ export default abstract class AbstractComponent {
      *                         this command.
      */
     setZIndexAndTransformBy(affineTransfm: Mat33, newZIndex: number, originalZIndex?: number): SerializableCommand;
-    isSelectable(): boolean;
-    isBackground(): boolean;
-    getProportionalRenderingTime(): number;
     private static transformElementCommandId;
     private static TransformElementCommand;
     /**
@@ -143,6 +143,18 @@ export default abstract class AbstractComponent {
     abstract description(localizationTable: ImageComponentLocalization): string;
     protected abstract createClone(): AbstractComponent;
     clone(): AbstractComponent;
+    /**
+     * **Optional method**: Divides this component into sections roughly along the given path,
+     * removing parts that are roughly within `shape`.
+     *
+     * **Notes**:
+     * - A default implementation may be provided for this method in the future. Until then,
+     *   this method is `undefined` if unsupported.
+     *
+     * `viewport` should be provided to determine how newly-added points should be rounded.
+     */
+    withRegionErased?(shape: Path, viewport: Viewport): AbstractComponent[];
+    protected abstract serializeToJSON(): any[] | Record<string, any> | number | string | null;
     serialize(): {
         name: string;
         zIndex: number;

package/dist/mjs/components/AbstractComponent.mjs

@@ -136,6 +136,21 @@ class AbstractComponent {
         const testLines = rect.getEdges();
         return testLines.some(edge => this.intersects(edge));
     }
+    // @returns true iff this component can be selected (e.g. by the selection tool.)
+    isSelectable() {
+        return true;
+    }
+    // @returns true iff this component should be added to the background, rather than the
+    // foreground of the image.
+    isBackground() {
+        return false;
+    }
+    // @returns an approximation of the proportional time it takes to render this component.
+    // This is intended to be a rough estimate, but, for example, a stroke with two points sould have
+    // a renderingWeight approximately twice that of a stroke with one point.
+    getProportionalRenderingTime() {
+        return 1;
+    }
     /**
      * Returns a command that, when applied, transforms this by [affineTransfm] and
      * updates the editor.
@@ -160,21 +175,6 @@ class AbstractComponent {
     setZIndexAndTransformBy(affineTransfm, newZIndex, originalZIndex) {
         return new AbstractComponent.TransformElementCommand(affineTransfm, this.getId(), this, newZIndex, originalZIndex);
     }
-    // @returns true iff this component can be selected (e.g. by the selection tool.)
-    isSelectable() {
-        return true;
-    }
-    // @returns true iff this component should be added to the background, rather than the
-    // foreground of the image.
-    isBackground() {
-        return false;
-    }
-    // @returns an approximation of the proportional time it takes to render this component.
-    // This is intended to be a rough estimate, but, for example, a stroke with two points sould have
-    // a renderingWeight approximately twice that of a stroke with one point.
-    getProportionalRenderingTime() {
-        return 1;
-    }
     // Returns a copy of this component.
     clone() {
         const clone = this.createClone();

package/dist/mjs/components/Stroke.d.ts

@@ -6,6 +6,7 @@ import AbstractComponent from './AbstractComponent';
 import { ImageComponentLocalization } from './localization';
 import RestyleableComponent, { ComponentStyle } from './RestylableComponent';
 import RenderablePathSpec, { RenderablePathSpecWithPath } from '../rendering/RenderablePathSpec';
+import Viewport from '../Viewport';
 /**
  * Represents an {@link AbstractComponent} made up of one or more {@link Path}s.
  *
@@ -46,10 +47,12 @@ export default class Stroke extends AbstractComponent implements RestyleableComp
      * ]);
      * ```
      */
-    constructor(parts: RenderablePathSpec[]);
+    constructor(parts: RenderablePathSpec[], initialZIndex?: number);
     getStyle(): ComponentStyle;
     updateStyle(style: ComponentStyle): SerializableCommand;
     forceStyle(style: ComponentStyle, editor: Editor | null): void;
+    /** @beta -- May fail for concave `path`s */
+    withRegionErased(eraserPath: Path, viewport: Viewport): Stroke[];
     intersects(line: LineSegment2): boolean;
     intersectsRect(rect: Rect2): boolean;
     private simplifiedPath;

package/dist/mjs/components/Stroke.mjs

@@ -1,4 +1,4 @@
-import { Path, Rect2 } from '@js-draw/math';
+import { Path, Rect2, PathCommandType, comparePathIndices, stepPathIndexBy } from '@js-draw/math';
 import  { styleFromJSON, styleToJSON }  from '../rendering/RenderingStyle.mjs';
 import  AbstractComponent  from './AbstractComponent.mjs';
 import  { createRestyleComponentCommand }  from './RestylableComponent.mjs';
@@ -39,8 +39,8 @@ export default class Stroke extends AbstractComponent {
      * ]);
      * ```
      */
-    constructor(parts) {
-        super('stroke');
+    constructor(parts, initialZIndex) {
+        super('stroke', initialZIndex);
         // @internal
         // eslint-disable-next-line @typescript-eslint/prefer-as-const
         this.isRestylableComponent = true;
@@ -118,6 +118,162 @@ export default class Stroke extends AbstractComponent {
             editor.queueRerender();
         }
     }
+    /** @beta -- May fail for concave `path`s */
+    withRegionErased(eraserPath, viewport) {
+        const polyline = eraserPath.polylineApproximation();
+        const isPointInsideEraser = (point) => {
+            return eraserPath.closedContainsPoint(point);
+        };
+        const newStrokes = [];
+        let failedAssertions = false;
+        for (const part of this.parts) {
+            const path = part.path;
+            const makeStroke = (path) => {
+                if (part.style.fill.a > 0) {
+                    // Remove visually empty paths.
+                    if (path.parts.length < 1 || (path.parts.length === 1 && path.parts[0].kind === PathCommandType.LineTo)) {
+                        // TODO: If this isn't present, a very large number of strokes are created while erasing.
+                        return null;
+                    }
+                    else {
+                        // Filled paths must be closed (allows for optimizations elsewhere)
+                        path = path.asClosed();
+                    }
+                }
+                if (isNaN(path.getExactBBox().area)) {
+                    console.warn('Prevented creating a stroke with NaN area');
+                    failedAssertions = true;
+                    return null;
+                }
+                return new Stroke([pathToRenderable(path, part.style)], this.getZIndex());
+            };
+            const intersectionPoints = [];
+            // If stroked, finds intersections with the middle of the stroke.
+            // If filled, finds intersections with the edge of the stroke.
+            for (const segment of polyline) {
+                intersectionPoints.push(...path.intersection(segment));
+            }
+            // When stroked, if the stroke width is significantly larger than the eraser,
+            // it can't intersect both the edge of the stroke and its middle at the same time
+            // (generally, erasing is triggered by the eraser touching the edge of this stroke).
+            //
+            // As such, we also look for intersections along the edge of this, if none with the
+            // center were found, but only within a certain range of sizes because:
+            // 1. Intersection testing with stroked paths is generally much slower than with
+            //    non-stroked paths.
+            // 2. If zoomed in significantly, it's unlikely that the user wants to erase a large
+            //    part of the stroke.
+            let isErasingFromEdge = false;
+            if (intersectionPoints.length === 0
+                && part.style.stroke
+                && part.style.stroke.width > eraserPath.bbox.minDimension * 0.3
+                && part.style.stroke.width < eraserPath.bbox.maxDimension * 30) {
+                for (const segment of polyline) {
+                    intersectionPoints.push(...path.intersection(segment, part.style.stroke.width / 2));
+                }
+                isErasingFromEdge = true;
+            }
+            // Sort first by curve index, then by parameter value
+            intersectionPoints.sort(comparePathIndices);
+            const isInsideJustBeforeFirst = (() => {
+                if (intersectionPoints.length === 0) {
+                    return false;
+                }
+                // The eraser may not be near the center of the curve -- approximate.
+                if (isErasingFromEdge) {
+                    return intersectionPoints[0].curveIndex === 0 && intersectionPoints[0].parameterValue <= 0;
+                }
+                const justBeforeFirstIntersection = stepPathIndexBy(intersectionPoints[0], -1e-10);
+                return isPointInsideEraser(path.at(justBeforeFirstIntersection));
+            })();
+            let intersectionCount = isInsideJustBeforeFirst ? 1 : 0;
+            const addNewPath = (path, knownToBeInside) => {
+                const component = makeStroke(path);
+                let isInside = intersectionCount % 2 === 1;
+                intersectionCount++;
+                if (knownToBeInside !== undefined) {
+                    isInside = knownToBeInside;
+                }
+                // Here, we work around bugs in the underlying Bezier curve library
+                // (including https://github.com/Pomax/bezierjs/issues/179).
+                // Even if not all intersections are returned correctly, we still want
+                // isInside to be roughly correct.
+                if (knownToBeInside === undefined && !isInside && eraserPath.closedContainsPoint(path.getExactBBox().center)) {
+                    isInside = !isInside;
+                }
+                if (!component) {
+                    return;
+                }
+                // Assertion: Avoid deleting sections that are much larger than the eraser.
+                failedAssertions ||= isInside && path.getExactBBox().maxDimension > eraserPath.getExactBBox().maxDimension * 2;
+                if (!isInside) {
+                    newStrokes.push(component);
+                }
+            };
+            if (part.style.fill.a === 0) { // Not filled?
+                // An additional case where we erase completely -- without the padding of the stroke,
+                // the path is smaller than the eraser (allows us to erase dots completely).
+                const shouldEraseCompletely = eraserPath.getExactBBox().maxDimension / 10 > path.getExactBBox().maxDimension;
+                if (!shouldEraseCompletely) {
+                    const split = path.splitAt(intersectionPoints, { mapNewPoint: p => viewport.roundPoint(p) });
+                    for (const splitPart of split) {
+                        addNewPath(splitPart);
+                    }
+                }
+            }
+            else if (intersectionPoints.length >= 2 && intersectionPoints.length % 2 === 0) {
+                // TODO: Support subtractive erasing on small scales -- see https://github.com/personalizedrefrigerator/js-draw/pull/63/commits/568686e2384219ad0bb07617ea4efff1540aed00
+                //       for a broken implementation.
+                //
+                // We currently assume that a 4-point intersection means that the intersection
+                // looks similar to this:
+                //   -----------
+                //  |   STROKE  |
+                //  |           |
+                //%%x-----------x%%%%%%%
+                //%                    %
+                //%      ERASER        %
+                //%                    %
+                //%%x-----------x%%%%%%%
+                //  |   STROKE  |
+                //   -----------
+                //
+                // Our goal is to separate STROKE into the contiguous parts outside
+                // of the eraser (as shown above).
+                //
+                // To do this, we split STROKE at each intersection:
+                //   3 3 3 3 3 3
+                //  3   STROKE  3
+                //  3           3
+                //  x           x
+                //  2           4
+                //  2   STROKE  4
+                //  2           4
+                //  x           x
+                //  1   STROKE  5
+                //   . 5 5 5 5 5
+                //   ^
+                // Start
+                //
+                // The difficulty here is correctly pairing edges to create the the output
+                // strokes, particularly because we don't know the order of intersection points.
+                const parts = path.splitAt(intersectionPoints, { mapNewPoint: p => viewport.roundPoint(p) });
+                for (let i = 0; i < Math.floor(parts.length / 2); i++) {
+                    addNewPath(parts[i].union(parts[parts.length - i - 1]).asClosed());
+                }
+                if (parts.length % 2 !== 0) {
+                    addNewPath(parts[Math.floor(parts.length / 2)].asClosed());
+                }
+            }
+            else {
+                addNewPath(path, false);
+            }
+        }
+        if (failedAssertions) {
+            return [this];
+        }
+        return newStrokes;
+    }
     intersects(line) {
         for (const part of this.parts) {
             const strokeWidth = part.style.stroke?.width;

package/dist/mjs/components/builders/PolylineBuilder.d.ts

@@ -9,7 +9,6 @@ import RenderingStyle from '../../rendering/RenderingStyle';
 /**
  * Creates strokes from line segments rather than Bézier curves.
  *
- * @beta Output behavior may change significantly between versions. For now, intended for debugging.
  */
 export declare const makePolylineBuilder: ComponentBuilderFactory;
 export default class PolylineBuilder implements ComponentBuilder {
@@ -21,6 +20,7 @@ export default class PolylineBuilder implements ComponentBuilder {
     private widthAverageNumSamples;
     private lastPoint;
     private startPoint;
+    private lastLineSegment;
     constructor(startPoint: StrokeDataPoint, minFitAllowed: number, viewport: Viewport);
     getBBox(): Rect2;
     protected getRenderingStyle(): RenderingStyle;

package/dist/mjs/components/builders/PolylineBuilder.mjs

@@ -1,11 +1,10 @@
-import { Rect2, Color4, PathCommandType } from '@js-draw/math';
+import { Rect2, Color4, PathCommandType, Vec2, LineSegment2 } from '@js-draw/math';
 import  Stroke  from '../Stroke.mjs';
 import  Viewport  from '../../Viewport.mjs';
 import  makeShapeFitAutocorrect  from './autocorrect/makeShapeFitAutocorrect.mjs';
 /**
  * Creates strokes from line segments rather than Bézier curves.
  *
- * @beta Output behavior may change significantly between versions. For now, intended for debugging.
  */
 export const makePolylineBuilder = makeShapeFitAutocorrect((initialPoint, viewport) => {
     const minFit = viewport.getSizeOfPixelOnCanvas();
@@ -17,6 +16,7 @@ export default class PolylineBuilder {
         this.viewport = viewport;
         this.parts = [];
         this.widthAverageNumSamples = 1;
+        this.lastLineSegment = null;
         this.averageWidth = startPoint.width;
         this.startPoint = {
             ...startPoint,
@@ -50,7 +50,7 @@ export default class PolylineBuilder {
         if (commands.length <= 1) {
             commands.push({
                 kind: PathCommandType.LineTo,
-                point: startPoint,
+                point: startPoint.plus(Vec2.of(this.averageWidth / 4, 0)),
             });
         }
         return {
@@ -98,11 +98,18 @@ export default class PolylineBuilder {
                 + newPoint.width / this.widthAverageNumSamples;
         const roundedPoint = this.roundPoint(newPoint.pos);
         if (!roundedPoint.eq(this.lastPoint)) {
+            // If almost exactly in the same line as the previous
+            if (this.lastLineSegment && this.lastLineSegment.direction.dot(roundedPoint.minus(this.lastPoint).normalized()) > 0.997) {
+                this.parts.pop();
+                this.lastPoint = this.lastLineSegment.p1;
+            }
             this.parts.push({
                 kind: PathCommandType.LineTo,
                 point: this.roundPoint(newPoint.pos),
             });
             this.bbox = this.bbox.grownToPoint(roundedPoint);
+            this.lastLineSegment = new LineSegment2(this.lastPoint, roundedPoint);
+            this.lastPoint = roundedPoint;
         }
     }
 }

package/dist/mjs/components/builders/PressureSensitiveFreehandLineBuilder.d.ts

@@ -12,6 +12,7 @@ export default class PressureSensitiveFreehandLineBuilder implements ComponentBu
     private isFirstSegment;
     private pathStartConnector;
     private mostRecentConnector;
+    private nextCurveStartConnector;
     private upperSegments;
     private lowerSegments;
     private lastUpperBezier;
@@ -25,7 +26,6 @@ export default class PressureSensitiveFreehandLineBuilder implements ComponentBu
     private getRenderingStyle;
     private previewCurrentPath;
     private previewFullPath;
-    private previewStroke;
     preview(renderer: AbstractRenderer): void;
     build(): Stroke;
     private roundPoint;