js-draw 0.3.1 → 0.4.0

package/dist/src/UndoRedoHistory.js

@@ -5,6 +5,7 @@ class UndoRedoHistory {
         this.editor = editor;
         this.announceRedoCallback = announceRedoCallback;
         this.announceUndoCallback = announceUndoCallback;
+        this.maxUndoRedoStackSize = 700;
         this.undoStack = [];
         this.redoStack = [];
     }
@@ -25,6 +26,11 @@ class UndoRedoHistory {
             elem.onDrop(this.editor);
         }
         this.redoStack = [];
+        if (this.undoStack.length > this.maxUndoRedoStackSize) {
+            const removeAtOnceCount = 10;
+            const removedElements = this.undoStack.splice(0, removeAtOnceCount);
+            removedElements.forEach(elem => elem.onDrop(this.editor));
+        }
         this.fireUpdateEvent();
         this.editor.notifier.dispatch(EditorEventType.CommandDone, {
             kind: EditorEventType.CommandDone,

package/dist/src/Viewport.d.ts

@@ -29,6 +29,8 @@ export declare class Viewport {
     getRotationAngle(): number;
     static roundPoint<T extends Point2 | number>(point: T, tolerance: number): PointDataType<T>;
     roundPoint(point: Point2): Point2;
+    static roundScaleRatio(scaleRatio: number, roundAmount?: number): number;
+    computeZoomToTransform(toMakeVisible: Rect2, allowZoomIn?: boolean, allowZoomOut?: boolean): Mat33;
     zoomTo(toMakeVisible: Rect2, allowZoomIn?: boolean, allowZoomOut?: boolean): Command;
 }
 export default Viewport;

package/dist/src/Viewport.js

@@ -29,6 +29,7 @@ export class Viewport {
     updateScreenSize(screenSize) {
         this.screenRect = this.screenRect.resizedTo(screenSize);
     }
+    // Get the screen's visible region transformed into canvas space.
     get visibleRect() {
         return this.screenRect.transformedBoundingBox(this.inverseTransform);
     }
@@ -72,7 +73,8 @@ export class Viewport {
     getSizeOfPixelOnCanvas() {
         return 1 / this.getScaleFactor();
     }
-    // Returns the angle of the canvas in radians
+    // Returns the angle of the canvas in radians.
+    // This is the angle by which the canvas is rotated relative to the screen.
     getRotationAngle() {
         return this.transform.transformVec3(Vec3.unitX).angle();
     }
@@ -93,10 +95,20 @@ export class Viewport {
     roundPoint(point) {
         return Viewport.roundPoint(point, 1 / this.getScaleFactor());
     }
-    // Returns a Command that transforms the view such that [rect] is visible, and perhaps
-    // centered in the viewport.
-    // Returns null if no transformation is necessary
-    zoomTo(toMakeVisible, allowZoomIn = true, allowZoomOut = true) {
+    // `roundAmount`: An integer >= 0, larger numbers cause less rounding. Smaller numbers cause more
+    // (as such `roundAmount = 0` does the most rounding).
+    static roundScaleRatio(scaleRatio, roundAmount = 1) {
+        if (Math.abs(scaleRatio) <= 1e-12) {
+            return 0;
+        }
+        // Represent as k 10ⁿ for some n, k ∈ ℤ.
+        const decimalComponent = Math.pow(10, Math.floor(Math.log10(Math.abs(scaleRatio))));
+        const roundAnountFactor = Math.pow(2, roundAmount);
+        scaleRatio = Math.round(scaleRatio / decimalComponent * roundAnountFactor) / roundAnountFactor * decimalComponent;
+        return scaleRatio;
+    }
+    // Computes and returns an affine transformation that makes `toMakeVisible` visible and roughly centered on the screen.
+    computeZoomToTransform(toMakeVisible, allowZoomIn = true, allowZoomOut = true) {
         let transform = Mat33.identity;
         if (toMakeVisible.w === 0 || toMakeVisible.h === 0) {
             throw new Error(`${toMakeVisible.toString()} rectangle is empty! Cannot zoom to!`);
@@ -136,6 +148,15 @@ export class Viewport {
             console.warn('Unable to zoom to ', toMakeVisible, '! Computed transform', transform, 'is singular.');
             transform = Mat33.identity;
         }
+        return transform;
+    }
+    // Returns a Command that transforms the view such that [rect] is visible, and perhaps
+    // centered in the viewport.
+    // Returns null if no transformation is necessary
+    //
+    // @see {@link computeZoomToTransform}
+    zoomTo(toMakeVisible, allowZoomIn = true, allowZoomOut = true) {
+        const transform = this.computeZoomToTransform(toMakeVisible, allowZoomIn, allowZoomOut);
         return new Viewport.ViewportTransform(transform);
     }
 }

package/dist/src/commands/lib.d.ts

@@ -3,4 +3,5 @@ import Duplicate from './Duplicate';
 import Erase from './Erase';
 import invertCommand from './invertCommand';
 import SerializableCommand from './SerializableCommand';
-export { Command, Duplicate, Erase, SerializableCommand, invertCommand, };
+import uniteCommands from './uniteCommands';
+export { Command, Duplicate, Erase, SerializableCommand, invertCommand, uniteCommands, };

package/dist/src/commands/lib.js

@@ -3,4 +3,5 @@ import Duplicate from './Duplicate';
 import Erase from './Erase';
 import invertCommand from './invertCommand';
 import SerializableCommand from './SerializableCommand';
-export { Command, Duplicate, Erase, SerializableCommand, invertCommand, };
+import uniteCommands from './uniteCommands';
+export { Command, Duplicate, Erase, SerializableCommand, invertCommand, uniteCommands, };

package/dist/src/commands/localization.d.ts

@@ -17,6 +17,7 @@ export interface CommandLocalization {
     eraseAction: (elemDescription: string, numElems: number) => string;
     duplicateAction: (elemDescription: string, count: number) => string;
     inverseOf: (actionDescription: string) => string;
+    unionOf: (actionDescription: string, actionCount: number) => string;
     selectedElements: (count: number) => string;
 }
 export declare const defaultCommandLocalization: CommandLocalization;

package/dist/src/commands/localization.js

@@ -5,6 +5,7 @@ export const defaultCommandLocalization = {
     addElementAction: (componentDescription) => `Added ${componentDescription}`,
     eraseAction: (componentDescription, numElems) => `Erased ${numElems} ${componentDescription}`,
     duplicateAction: (componentDescription, numElems) => `Duplicated ${numElems} ${componentDescription}`,
+    unionOf: (actionDescription, actionCount) => `Union: ${actionCount} ${actionDescription}`,
     inverseOf: (actionDescription) => `Inverse of ${actionDescription}`,
     elements: 'Elements',
     erasedNoElements: 'Erased nothing',

package/dist/src/commands/uniteCommands.d.ts

@@ -0,0 +1,4 @@
+import Command from './Command';
+import SerializableCommand from './SerializableCommand';
+declare const uniteCommands: <T extends Command>(commands: T[], applyChunkSize?: number) => T extends SerializableCommand ? SerializableCommand : Command;
+export default uniteCommands;

package/dist/src/commands/uniteCommands.js

@@ -0,0 +1,105 @@
+import Command from './Command';
+import SerializableCommand from './SerializableCommand';
+class NonSerializableUnion extends Command {
+    constructor(commands, applyChunkSize) {
+        super();
+        this.commands = commands;
+        this.applyChunkSize = applyChunkSize;
+    }
+    apply(editor) {
+        if (this.applyChunkSize === undefined) {
+            for (const command of this.commands) {
+                command.apply(editor);
+            }
+        }
+        else {
+            editor.asyncApplyCommands(this.commands, this.applyChunkSize);
+        }
+    }
+    unapply(editor) {
+        if (this.applyChunkSize === undefined) {
+            for (const command of this.commands) {
+                command.unapply(editor);
+            }
+        }
+        else {
+            editor.asyncUnapplyCommands(this.commands, this.applyChunkSize);
+        }
+    }
+    description(editor, localizationTable) {
+        const descriptions = [];
+        let lastDescription = null;
+        let duplicateDescriptionCount = 0;
+        for (const part of this.commands) {
+            const description = part.description(editor, localizationTable);
+            if (description !== lastDescription && lastDescription !== null) {
+                descriptions.push(localizationTable.unionOf(lastDescription, duplicateDescriptionCount));
+                lastDescription = null;
+                duplicateDescriptionCount = 0;
+            }
+            duplicateDescriptionCount++;
+            lastDescription !== null && lastDescription !== void 0 ? lastDescription : (lastDescription = description);
+        }
+        if (duplicateDescriptionCount > 1) {
+            descriptions.push(localizationTable.unionOf(lastDescription, duplicateDescriptionCount));
+        }
+        else if (duplicateDescriptionCount === 1) {
+            descriptions.push(lastDescription);
+        }
+        return descriptions.join(', ');
+    }
+}
+class SerializableUnion extends SerializableCommand {
+    constructor(commands, applyChunkSize) {
+        super('union');
+        this.commands = commands;
+        this.applyChunkSize = applyChunkSize;
+        this.nonserializableCommand = new NonSerializableUnion(commands, applyChunkSize);
+    }
+    serializeToJSON() {
+        return {
+            applyChunkSize: this.applyChunkSize,
+            data: this.commands.map(command => command.serialize()),
+        };
+    }
+    apply(editor) {
+        this.nonserializableCommand.apply(editor);
+    }
+    unapply(editor) {
+        this.nonserializableCommand.unapply(editor);
+    }
+    description(editor, localizationTable) {
+        return this.nonserializableCommand.description(editor, localizationTable);
+    }
+}
+const uniteCommands = (commands, applyChunkSize) => {
+    let allSerializable = true;
+    for (const command of commands) {
+        if (!(command instanceof SerializableCommand)) {
+            allSerializable = false;
+            break;
+        }
+    }
+    if (!allSerializable) {
+        return new NonSerializableUnion(commands, applyChunkSize);
+    }
+    else {
+        const castedCommands = commands;
+        return new SerializableUnion(castedCommands, applyChunkSize);
+    }
+};
+SerializableCommand.register('union', (data, editor) => {
+    if (typeof data.data.length !== 'number') {
+        throw new Error('Unions of commands must serialize to lists of serialization data.');
+    }
+    const applyChunkSize = data.applyChunkSize;
+    if (typeof applyChunkSize !== 'number' && applyChunkSize !== undefined) {
+        throw new Error('serialized applyChunkSize is neither undefined nor a number.');
+    }
+    const commands = [];
+    for (const part of data.data) {
+        commands.push(SerializableCommand.deserialize(part, editor));
+    }
+    return uniteCommands(commands, applyChunkSize);
+});
+export default uniteCommands;

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

@@ -28,6 +28,8 @@ export default abstract class AbstractComponent {
     protected abstract serializeToJSON(): any[] | Record<string, any> | number | string | null;
     protected abstract applyTransformation(affineTransfm: Mat33): void;
     transformBy(affineTransfm: Mat33): SerializableCommand;
+    private static transformElementCommandId;
+    private static UnresolvedTransformElementCommand;
     private static TransformElementCommand;
     abstract description(localizationTable: ImageComponentLocalization): string;
     protected abstract createClone(): AbstractComponent;

package/dist/src/components/AbstractComponent.js

@@ -113,9 +113,45 @@ export default class AbstractComponent {
 // Topmost z-index
 AbstractComponent.zIndexCounter = 0;
 AbstractComponent.deserializationCallbacks = {};
+AbstractComponent.transformElementCommandId = 'transform-element';
+AbstractComponent.UnresolvedTransformElementCommand = class extends SerializableCommand {
+    constructor(affineTransfm, componentID) {
+        super(AbstractComponent.transformElementCommandId);
+        this.affineTransfm = affineTransfm;
+        this.componentID = componentID;
+        this.command = null;
+    }
+    resolveCommand(editor) {
+        if (this.command) {
+            return;
+        }
+        const component = editor.image.lookupElement(this.componentID);
+        if (!component) {
+            throw new Error(`Unable to resolve component with ID ${this.componentID}`);
+        }
+        this.command = new AbstractComponent.TransformElementCommand(this.affineTransfm, component);
+    }
+    apply(editor) {
+        this.resolveCommand(editor);
+        this.command.apply(editor);
+    }
+    unapply(editor) {
+        this.resolveCommand(editor);
+        this.command.unapply(editor);
+    }
+    description(_editor, localizationTable) {
+        return localizationTable.transformedElements(1);
+    }
+    serializeToJSON() {
+        return {
+            id: this.componentID,
+            transfm: this.affineTransfm.toArray(),
+        };
+    }
+};
 AbstractComponent.TransformElementCommand = (_a = class extends SerializableCommand {
         constructor(affineTransfm, component) {
-            super('transform-element');
+            super(AbstractComponent.transformElementCommandId);
             this.affineTransfm = affineTransfm;
             this.component = component;
             this.origZIndex = component.zIndex;
@@ -155,13 +191,13 @@ AbstractComponent.TransformElementCommand = (_a = class extends SerializableComm
         }
     },
     (() => {
-        SerializableCommand.register('transform-element', (json, editor) => {
+        SerializableCommand.register(AbstractComponent.transformElementCommandId, (json, editor) => {
             const elem = editor.image.lookupElement(json.id);
+            const transform = new Mat33(...json.transfm);
             if (!elem) {
-                throw new Error(`Unable to retrieve non-existent element, ${elem}`);
+                return new AbstractComponent.UnresolvedTransformElementCommand(transform, json.id);
             }
-            const transform = json.transfm;
-            return new AbstractComponent.TransformElementCommand(new Mat33(...transform), elem);
+            return new AbstractComponent.TransformElementCommand(transform, elem);
         });
     })(),
     _a);

package/dist/src/components/ImageComponent.d.ts

@@ -0,0 +1,27 @@
+import LineSegment2 from '../math/LineSegment2';
+import Mat33, { Mat33Array } from '../math/Mat33';
+import Rect2 from '../math/Rect2';
+import AbstractRenderer, { RenderableImage } from '../rendering/renderers/AbstractRenderer';
+import AbstractComponent from './AbstractComponent';
+import { ImageComponentLocalization } from './localization';
+export default class ImageComponent extends AbstractComponent {
+    protected contentBBox: Rect2;
+    private image;
+    constructor(image: RenderableImage);
+    private getImageRect;
+    private recomputeBBox;
+    static fromImage(elem: HTMLImageElement, transform: Mat33): Promise<ImageComponent>;
+    render(canvas: AbstractRenderer, _visibleRect?: Rect2): void;
+    intersects(lineSegment: LineSegment2): boolean;
+    protected serializeToJSON(): {
+        src: string;
+        label: string | undefined;
+        width: number;
+        height: number;
+        transform: Mat33Array;
+    };
+    protected applyTransformation(affineTransfm: Mat33): void;
+    description(localizationTable: ImageComponentLocalization): string;
+    protected createClone(): AbstractComponent;
+    static deserializeFromJSON(data: any): ImageComponent;
+}

package/dist/src/components/ImageComponent.js

@@ -0,0 +1,129 @@
+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());
+    });
+};
+import Mat33 from '../math/Mat33';
+import Rect2 from '../math/Rect2';
+import AbstractComponent from './AbstractComponent';
+// Represents a raster image.
+export default class ImageComponent extends AbstractComponent {
+    constructor(image) {
+        var _a, _b, _c;
+        super('image-component');
+        this.image = Object.assign(Object.assign({}, image), { label: (_c = (_b = (_a = image.label) !== null && _a !== void 0 ? _a : image.image.getAttribute('alt')) !== null && _b !== void 0 ? _b : image.image.getAttribute('aria-label')) !== null && _c !== void 0 ? _c : undefined });
+        const isHTMLImageElem = (elem) => {
+            return elem.getAttribute('src') !== undefined;
+        };
+        if (isHTMLImageElem(image.image) && !image.image.complete) {
+            image.image.onload = () => this.recomputeBBox();
+        }
+        this.recomputeBBox();
+    }
+    getImageRect() {
+        return new Rect2(0, 0, this.image.image.width, this.image.image.height);
+    }
+    recomputeBBox() {
+        this.contentBBox = this.getImageRect();
+        this.contentBBox = this.contentBBox.transformedBoundingBox(this.image.transform);
+    }
+    // Load from an image. Waits for the image to load if incomplete.
+    static fromImage(elem, transform) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!elem.complete) {
+                yield new Promise((resolve, reject) => {
+                    elem.onload = resolve;
+                    elem.onerror = reject;
+                    elem.onabort = reject;
+                });
+            }
+            let width, height;
+            if (typeof elem.width === 'number' && typeof elem.height === 'number'
+                && elem.width !== 0 && elem.height !== 0) {
+                width = elem.width;
+                height = elem.height;
+            }
+            else {
+                width = elem.clientWidth;
+                height = elem.clientHeight;
+            }
+            let image;
+            let url = (_a = elem.src) !== null && _a !== void 0 ? _a : '';
+            if (!url.startsWith('data:image/')) {
+                // Convert to a data URL:
+                const canvas = document.createElement('canvas');
+                canvas.width = width;
+                canvas.height = height;
+                const ctx = canvas.getContext('2d');
+                ctx.drawImage(elem, 0, 0, canvas.width, canvas.height);
+                url = canvas.toDataURL();
+                image = canvas;
+            }
+            else {
+                image = new Image();
+                image.src = url;
+                image.width = width;
+                image.height = height;
+            }
+            return new ImageComponent({
+                image,
+                base64Url: url,
+                transform: transform,
+            });
+        });
+    }
+    render(canvas, _visibleRect) {
+        canvas.drawImage(this.image);
+    }
+    intersects(lineSegment) {
+        const rect = this.getImageRect();
+        const edges = rect.getEdges().map(edge => edge.transformedBy(this.image.transform));
+        for (const edge of edges) {
+            if (edge.intersects(lineSegment)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    serializeToJSON() {
+        return {
+            src: this.image.base64Url,
+            label: this.image.label,
+            // Store the width and height for bounding box computations while the image is loading.
+            width: this.image.image.width,
+            height: this.image.image.height,
+            transform: this.image.transform.toArray(),
+        };
+    }
+    applyTransformation(affineTransfm) {
+        this.image.transform = affineTransfm.rightMul(this.image.transform);
+        this.recomputeBBox();
+    }
+    description(localizationTable) {
+        return this.image.label ? localizationTable.imageNode(this.image.label) : localizationTable.unlabeledImageNode;
+    }
+    createClone() {
+        return new ImageComponent(Object.assign({}, this.image));
+    }
+    static deserializeFromJSON(data) {
+        if (!(typeof data.src === 'string')) {
+            throw new Error(`${data} has invalid format! Expected src property.`);
+        }
+        const image = new Image();
+        image.src = data.src;
+        image.width = data.width;
+        image.height = data.height;
+        return new ImageComponent({
+            image: image,
+            base64Url: image.src,
+            label: data.label,
+            transform: new Mat33(...data.transform),
+        });
+    }
+}
+AbstractComponent.registerComponent('image-component', ImageComponent.deserializeFromJSON);

package/dist/src/components/builders/FreehandLineBuilder.js

@@ -237,9 +237,9 @@ export default class FreehandLineBuilder {
             const lowerBoundary = computeBoundaryCurve(-1, halfVec);
             return upperBoundary.intersects(lowerBoundary).length > 0;
         };
-        // If the boundaries have two intersections, increasing the half vector's length could fix this.
+        // If the boundaries have intersections, increasing the half vector's length could fix this.
         if (boundariesIntersect()) {
-            halfVec = halfVec.times(2);
+            halfVec = halfVec.times(1.1);
         }
         // Each starts at startPt ± startVec
         const lowerCurve = {

package/dist/src/components/lib.d.ts

@@ -1,6 +1,8 @@
 export * from './builders/types';
 export { makeFreehandLineBuilder } from './builders/FreehandLineBuilder';
-import AbstractComponent from './AbstractComponent';
+export * from './AbstractComponent';
+export { default as AbstractComponent } from './AbstractComponent';
 import Stroke from './Stroke';
 import Text from './Text';
-export { AbstractComponent, Stroke, Text, };
+import ImageComponent from './ImageComponent';
+export { Stroke, Text, Text as TextComponent, Stroke as StrokeComponent, ImageComponent, };

package/dist/src/components/lib.js

@@ -1,6 +1,8 @@
 export * from './builders/types';
 export { makeFreehandLineBuilder } from './builders/FreehandLineBuilder';
-import AbstractComponent from './AbstractComponent';
+export * from './AbstractComponent';
+export { default as AbstractComponent } from './AbstractComponent';
 import Stroke from './Stroke';
 import Text from './Text';
-export { AbstractComponent, Stroke, Text, };
+import ImageComponent from './ImageComponent';
+export { Stroke, Text, Text as TextComponent, Stroke as StrokeComponent, ImageComponent, };

package/dist/src/components/localization.d.ts

@@ -1,5 +1,7 @@
 export interface ImageComponentLocalization {
+    unlabeledImageNode: string;
     text: (text: string) => string;
+    imageNode: (description: string) => string;
     stroke: string;
     svgObject: string;
 }

package/dist/src/components/localization.js

@@ -1,5 +1,7 @@
 export const defaultComponentLocalization = {
+    unlabeledImageNode: 'Unlabeled image node',
     stroke: 'Stroke',
     svgObject: 'SVG Object',
     text: (text) => `Text object: ${text}`,
+    imageNode: (description) => `Image: ${description}`,
 };

package/dist/src/language/assertions.d.ts

@@ -0,0 +1 @@
+export declare const assertUnreachable: (key: never) => never;

package/dist/src/language/assertions.js

@@ -0,0 +1,5 @@
+// Compile-time assertion that a branch of code is unreachable.
+// See https://stackoverflow.com/a/39419171/17055750
+export const assertUnreachable = (key) => {
+    throw new Error(`Should be unreachable. Key: ${key}.`);
+};

package/dist/src/math/LineSegment2.d.ts

@@ -1,3 +1,4 @@
+import Mat33 from './Mat33';
 import Rect2 from './Rect2';
 import { Vec2, Point2 } from './Vec2';
 interface IntersectionResult {
@@ -17,6 +18,7 @@ export default class LineSegment2 {
     intersection(other: LineSegment2): IntersectionResult | null;
     intersects(other: LineSegment2): boolean;
     closestPointTo(target: Point2): import("./Vec3").default;
+    transformedBy(affineTransfm: Mat33): LineSegment2;
     toString(): string;
 }
 export {};

package/dist/src/math/LineSegment2.js

@@ -116,6 +116,9 @@ export default class LineSegment2 {
             return this.p1;
         }
     }
+    transformedBy(affineTransfm) {
+        return new LineSegment2(affineTransfm.transformVec2(this.p1), affineTransfm.transformVec2(this.p2));
+    }
     toString() {
         return `LineSegment(${this.p1.toString()}, ${this.p2.toString()})`;
     }

package/dist/src/math/Mat33.d.ts

@@ -1,5 +1,16 @@
 import { Point2, Vec2 } from './Vec2';
 import Vec3 from './Vec3';
+export declare type Mat33Array = [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number
+];
 /**
  * Represents a three dimensional linear transformation or
  * a two-dimensional affine transformation. (An affine transformation scales/rotates/shears
@@ -68,11 +79,36 @@ export default class Mat33 {
      * ...
      * ```
      */
-    toArray(): number[];
+    toArray(): Mat33Array;
+    /**
+     * @example
+     * ```
+     * new Mat33(
+     *  1, 2, 3,
+     *  4, 5, 6,
+     *  7, 8, 9,
+     * ).mapEntries(component => component - 1);
+     * // → ⎡ 0, 1, 2 ⎤
+     * //   ⎢ 3, 4, 5 ⎥
+     * //   ⎣ 6, 7, 8 ⎦
+     * ```
+     */
+    mapEntries(mapping: (component: number) => number): Mat33;
     /** Constructs a 3x3 translation matrix (for translating `Vec2`s) */
     static translation(amount: Vec2): Mat33;
     static zRotation(radians: number, center?: Point2): Mat33;
     static scaling2D(amount: number | Vec2, center?: Point2): Mat33;
-    /** Converts a CSS-form `matrix(a, b, c, d, e, f)` to a Mat33. */
+    /** @see {@link !fromCSSMatrix} */
+    toCSSMatrix(): string;
+    /**
+     * Converts a CSS-form `matrix(a, b, c, d, e, f)` to a Mat33.
+     *
+     * Note that such a matrix has the form,
+     * ```
+     * ⎡ a c e ⎤
+     * ⎢ b d f ⎥
+     * ⎣ 0 0 1 ⎦
+     * ```
+     */
     static fromCSSMatrix(cssString: string): Mat33;
 }

package/dist/src/math/Mat33.js

@@ -183,6 +183,22 @@ export default class Mat33 {
             this.c1, this.c2, this.c3,
         ];
     }
+    /**
+     * @example
+     * ```
+     * new Mat33(
+     *  1, 2, 3,
+     *  4, 5, 6,
+     *  7, 8, 9,
+     * ).mapEntries(component => component - 1);
+     * // → ⎡ 0, 1, 2 ⎤
+     * //   ⎢ 3, 4, 5 ⎥
+     * //   ⎣ 6, 7, 8 ⎦
+     * ```
+     */
+    mapEntries(mapping) {
+        return new Mat33(mapping(this.a1), mapping(this.a2), mapping(this.a3), mapping(this.b1), mapping(this.b2), mapping(this.b3), mapping(this.c1), mapping(this.c2), mapping(this.c3));
+    }
     /** Constructs a 3x3 translation matrix (for translating `Vec2`s) */
     static translation(amount) {
         // When transforming Vec2s by a 3x3 matrix, we give the input
@@ -214,7 +230,20 @@ export default class Mat33 {
         // Translate such that [center] goes to (0, 0)
         return result.rightMul(Mat33.translation(center.times(-1)));
     }
-    /** Converts a CSS-form `matrix(a, b, c, d, e, f)` to a Mat33. */
+    /** @see {@link !fromCSSMatrix} */
+    toCSSMatrix() {
+        return `matrix(${this.a1},${this.b1},${this.a2},${this.b2},${this.a3},${this.b3})`;
+    }
+    /**
+     * Converts a CSS-form `matrix(a, b, c, d, e, f)` to a Mat33.
+     *
+     * Note that such a matrix has the form,
+     * ```
+     * ⎡ a c e ⎤
+     * ⎢ b d f ⎥
+     * ⎣ 0 0 1 ⎦
+     * ```
+     */
     static fromCSSMatrix(cssString) {
         if (cssString === '' || cssString === 'none') {
             return Mat33.identity;