js-draw 0.18.2 → 0.20.0

package/dist/mjs/src/SVGLoader.mjs

@@ -8,7 +8,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import  Color4  from './Color4.mjs';
-import  ImageBackground, { BackgroundType, imageBackgroundCSSClassName }  from './components/ImageBackground.mjs';
+import  BackgroundComponent, { BackgroundType, backgroundTypeToClassNameMap, imageBackgroundCSSClassName, imageBackgroundGridSizeCSSPrefix, imageBackgroundNonAutomaticSecondaryColorCSSClassName }  from './components/BackgroundComponent.mjs';
 import  ImageComponent  from './components/ImageComponent.mjs';
 import  Stroke  from './components/Stroke.mjs';
 import  SVGGlobalAttributesObject  from './components/SVGGlobalAttributesObject.mjs';
@@ -39,14 +39,13 @@ export default class SVGLoader {
     // If [computedStyles] is given, it is preferred to directly accessing node's style object.
     getStyle(node, computedStyles) {
         var _a, _b, _c, _d, _f, _g;
-        const style = {
-            fill: Color4.transparent,
-        };
+        let fill = Color4.transparent;
+        let stroke;
         // If possible, use computedStyles (allows property inheritance).
         const fillAttribute = (_b = (_a = node.getAttribute('fill')) !== null && _a !== void 0 ? _a : computedStyles === null || computedStyles === void 0 ? void 0 : computedStyles.fill) !== null && _b !== void 0 ? _b : node.style.fill;
         if (fillAttribute) {
             try {
-                style.fill = Color4.fromString(fillAttribute);
+                fill = Color4.fromString(fillAttribute);
             }
             catch (e) {
                 console.error('Unknown fill color,', fillAttribute);
@@ -62,7 +61,7 @@ export default class SVGLoader {
                 }
                 const strokeColor = Color4.fromString(strokeAttribute);
                 if (strokeColor.a > 0) {
-                    style.stroke = {
+                    stroke = {
                         width,
                         color: strokeColor,
                     };
@@ -72,6 +71,10 @@ export default class SVGLoader {
                 console.error('Error parsing stroke data:', e);
             }
         }
+        const style = {
+            fill,
+            stroke,
+        };
         return style;
     }
     strokeDataFromElem(node) {
@@ -147,11 +150,69 @@ export default class SVGLoader {
         });
     }
     addBackground(node) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         return __awaiter(this, void 0, void 0, function* () {
-            const fill = Color4.fromString((_b = (_a = node.getAttribute('fill')) !== null && _a !== void 0 ? _a : node.style.fill) !== null && _b !== void 0 ? _b : 'black');
-            const elem = new ImageBackground(BackgroundType.SolidColor, fill);
-            yield ((_c = this.onAddComponent) === null || _c === void 0 ? void 0 : _c.call(this, elem));
+            // If a grid background,
+            if (node.classList.contains(backgroundTypeToClassNameMap[BackgroundType.Grid])) {
+                let foregroundStr;
+                let backgroundStr;
+                let gridStrokeWidthStr;
+                // If a group,
+                if (node.tagName.toLowerCase() === 'g') {
+                    // We expect exactly two children. One of these is the solid
+                    // background of the grid
+                    if (node.children.length !== 2) {
+                        yield this.addUnknownNode(node);
+                        return;
+                    }
+                    const background = node.children[0];
+                    const grid = node.children[1];
+                    backgroundStr = background.getAttribute('fill');
+                    foregroundStr = grid.getAttribute('stroke');
+                    gridStrokeWidthStr = grid.getAttribute('stroke-width');
+                }
+                else {
+                    backgroundStr = node.getAttribute('fill');
+                    foregroundStr = node.getAttribute('stroke');
+                    gridStrokeWidthStr = node.getAttribute('stroke-width');
+                }
+                // Default to a transparent background.
+                backgroundStr !== null && backgroundStr !== void 0 ? backgroundStr : (backgroundStr = Color4.transparent.toHexString());
+                // A grid must have a foreground color specified.
+                if (!foregroundStr) {
+                    yield this.addUnknownNode(node);
+                    return;
+                }
+                // Extract the grid size from the class name
+                let gridSize = undefined;
+                for (const className of node.classList) {
+                    if (className.startsWith(imageBackgroundGridSizeCSSPrefix)) {
+                        const sizeStr = className.substring(imageBackgroundGridSizeCSSPrefix.length);
+                        gridSize = parseFloat(sizeStr.replace(/p/g, '.'));
+                    }
+                }
+                let gridStrokeWidth = undefined;
+                if (gridStrokeWidthStr) {
+                    gridStrokeWidth = parseFloat(gridStrokeWidthStr);
+                }
+                const backgroundColor = Color4.fromString(backgroundStr);
+                let foregroundColor = Color4.fromString(foregroundStr);
+                // Should the foreground color be determined automatically?
+                if (!node.classList.contains(imageBackgroundNonAutomaticSecondaryColorCSSClassName)) {
+                    foregroundColor = undefined;
+                }
+                const elem = BackgroundComponent.ofGrid(backgroundColor, gridSize, foregroundColor, gridStrokeWidth);
+                yield ((_a = this.onAddComponent) === null || _a === void 0 ? void 0 : _a.call(this, elem));
+            }
+            // Otherwise, if just a <path/>, it's a solid color background.
+            else if (node.tagName.toLowerCase() === 'path') {
+                const fill = Color4.fromString((_c = (_b = node.getAttribute('fill')) !== null && _b !== void 0 ? _b : node.style.fill) !== null && _c !== void 0 ? _c : 'black');
+                const elem = new BackgroundComponent(BackgroundType.SolidColor, fill);
+                yield ((_d = this.onAddComponent) === null || _d === void 0 ? void 0 : _d.call(this, elem));
+            }
+            else {
+                yield this.addUnknownNode(node);
+            }
         });
     }
     // If given, 'supportedAttrs' will have x, y, etc. attributes that were used in computing the transform added to it,
@@ -319,7 +380,11 @@ export default class SVGLoader {
             let visitChildren = true;
             switch (node.tagName.toLowerCase()) {
                 case 'g':
-                    // Continue -- visit the node's children.
+                    if (node.classList.contains(imageBackgroundCSSClassName)) {
+                        yield this.addBackground(node);
+                        visitChildren = false;
+                    }
+                    // Otherwise, continue -- visit the node's children.
                     break;
                 case 'path':
                     if (node.classList.contains(imageBackgroundCSSClassName)) {

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

@@ -50,6 +50,8 @@ export declare class Viewport {
      */
     getScaleFactorToNearestPowerOfTen(): number;
     private getScaleFactorToNearestPowerOf;
+    /** Returns the size of a grid cell (in canvas units) as used by {@link snapToGrid}. */
+    static getGridSize(scaleFactor: number): number;
     snapToGrid(canvasPos: Point2): Vec3;
     /** Returns the size of one screen pixel in canvas units. */
     getSizeOfPixelOnCanvas(): number;

package/dist/mjs/src/Viewport.mjs

@@ -97,10 +97,14 @@ export class Viewport {
         const scaleFactor = this.getScaleFactor();
         return Math.pow(powerOf, Math.round(Math.log(scaleFactor) / Math.log(powerOf)));
     }
+    /** Returns the size of a grid cell (in canvas units) as used by {@link snapToGrid}. */
+    static getGridSize(scaleFactor) {
+        return 50 / scaleFactor;
+    }
     snapToGrid(canvasPos) {
+        const scaleFactor = this.getScaleFactorToNearestPowerOf(2);
         const snapCoordinate = (coordinate) => {
-            const scaleFactor = this.getScaleFactorToNearestPowerOf(2);
-            const roundFactor = scaleFactor / 50;
+            const roundFactor = 1 / Viewport.getGridSize(scaleFactor);
             const snapped = Math.round(coordinate * roundFactor) / roundFactor;
             return snapped;
         };

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

@@ -26,13 +26,13 @@ export default abstract class AbstractComponent {
     /**
      * Attach data that can be used while exporting the component (e.g. to SVG).
      *
-     * This is intended for use by a {@link ImageLoader}.
+     * This is intended for use by an {@link ImageLoader}.
      */
     attachLoadSaveData(key: string, data: LoadSaveData): void;
     /** See {@link attachLoadSaveData} */
     getLoadSaveData(): LoadSaveDataTable;
     getZIndex(): number;
-    /** @returns the bounding box of  */
+    /** @returns the bounding box of this. */
     getBBox(): Rect2;
     /** Called when this component is added to the given image. */
     onAddToImage(_image: EditorImage): void;

package/dist/mjs/src/components/AbstractComponent.mjs

@@ -27,7 +27,7 @@ export default class AbstractComponent {
         }
     }
     // Returns a unique ID for this element.
-    // @see { @link lib!EditorImage.lookupElement }
+    // @see { @link EditorImage.lookupElement }
     getId() {
         return this.id;
     }
@@ -40,7 +40,7 @@ export default class AbstractComponent {
     /**
      * Attach data that can be used while exporting the component (e.g. to SVG).
      *
-     * This is intended for use by a {@link ImageLoader}.
+     * This is intended for use by an {@link ImageLoader}.
      */
     attachLoadSaveData(key, data) {
         if (!this.loadSaveData[key]) {
@@ -55,7 +55,7 @@ export default class AbstractComponent {
     getZIndex() {
         return this.zIndex;
     }
-    /** @returns the bounding box of  */
+    /** @returns the bounding box of this. */
     getBBox() {
         return this.contentBBox;
     }

package/dist/mjs/src/components/{ImageBackground.d.ts → BackgroundComponent.d.ts}

@@ -11,32 +11,52 @@ import { ImageComponentLocalization } from './localization';
 import RestyleableComponent, { ComponentStyle } from './RestylableComponent';
 export declare enum BackgroundType {
     SolidColor = 0,
-    None = 1
+    Grid = 1,
+    None = 2
 }
 export declare const imageBackgroundCSSClassName = "js-draw-image-background";
-export default class ImageBackground extends AbstractComponent implements RestyleableComponent {
+export declare const imageBackgroundGridSizeCSSPrefix = "js-draw-image-background-grid-";
+export declare const imageBackgroundNonAutomaticSecondaryColorCSSClassName = "js-draw-image-background-non-automatic-secondary-color";
+export declare const backgroundTypeToClassNameMap: {
+    1: string;
+    0: string;
+    2: string;
+};
+export default class BackgroundComponent extends AbstractComponent implements RestyleableComponent {
     private backgroundType;
     private mainColor;
     protected contentBBox: Rect2;
     private viewportSizeChangeListener;
+    private gridSize;
+    private gridStrokeWidth;
+    private secondaryColor;
     readonly isRestylableComponent: true;
     constructor(backgroundType: BackgroundType, mainColor: Color4);
+    static ofGrid(backgroundColor: Color4, gridSize?: number, gridColor?: Color4, gridStrokeWidth?: number): BackgroundComponent;
+    getBackgroundType(): BackgroundType;
+    getMainColor(): Color4;
+    getSecondaryColor(): Color4 | null;
+    getGridSize(): number;
     getStyle(): ComponentStyle;
     updateStyle(style: ComponentStyle): SerializableCommand;
     forceStyle(style: ComponentStyle, editor: Editor | null): void;
     onAddToImage(image: EditorImage): void;
     onRemoveFromImage(): void;
     private recomputeBBox;
+    private generateGridPath;
     render(canvas: AbstractRenderer, visibleRect?: Rect2): void;
     intersects(lineSegment: LineSegment2): boolean;
     isSelectable(): boolean;
     isBackground(): boolean;
     protected serializeToJSON(): {
         mainColor: string;
+        secondaryColor: string | undefined;
         backgroundType: BackgroundType;
+        gridSize: number;
+        gridStrokeWidth: number;
     };
     protected applyTransformation(_affineTransfm: Mat33): void;
     description(localizationTable: ImageComponentLocalization): string;
     protected createClone(): AbstractComponent;
-    static deserializeFromJSON(json: any): ImageBackground;
+    static deserializeFromJSON(json: any): BackgroundComponent;
 }

package/dist/mjs/src/components/BackgroundComponent.mjs

@@ -0,0 +1,279 @@
+import  Color4  from '../Color4.mjs';
+import  { EditorImageEventType }  from '../EditorImage.mjs';
+import  Rect2  from '../math/Rect2.mjs';
+import  AbstractComponent  from './AbstractComponent.mjs';
+import  { createRestyleComponentCommand }  from './RestylableComponent.mjs';
+import  Path, { PathCommandType }  from '../math/Path.mjs';
+import  { Vec2 }  from '../math/Vec2.mjs';
+import  Viewport  from '../Viewport.mjs';
+import  { toRoundedString }  from '../math/rounding.mjs';
+export var BackgroundType;
+(function (BackgroundType) {
+    BackgroundType[BackgroundType["SolidColor"] = 0] = "SolidColor";
+    BackgroundType[BackgroundType["Grid"] = 1] = "Grid";
+    BackgroundType[BackgroundType["None"] = 2] = "None";
+})(BackgroundType || (BackgroundType = {}));
+export const imageBackgroundCSSClassName = 'js-draw-image-background';
+// Class name prefix indicating the size of the background's grid cells (if present).
+export const imageBackgroundGridSizeCSSPrefix = 'js-draw-image-background-grid-';
+// Flag included in rendered SVGs (etc) that indicates that the secondary color of the
+// background has been manually set.
+export const imageBackgroundNonAutomaticSecondaryColorCSSClassName = 'js-draw-image-background-non-automatic-secondary-color';
+export const backgroundTypeToClassNameMap = {
+    [BackgroundType.Grid]: 'js-draw-image-background-grid',
+    [BackgroundType.SolidColor]: imageBackgroundCSSClassName,
+    [BackgroundType.None]: '',
+};
+// Represents the background of the editor's canvas.
+export default class BackgroundComponent extends AbstractComponent {
+    constructor(backgroundType, mainColor) {
+        super('image-background', 0);
+        this.backgroundType = backgroundType;
+        this.mainColor = mainColor;
+        this.viewportSizeChangeListener = null;
+        this.gridSize = Viewport.getGridSize(2);
+        this.gridStrokeWidth = 0.7;
+        this.secondaryColor = null;
+        // eslint-disable-next-line @typescript-eslint/prefer-as-const
+        this.isRestylableComponent = true;
+        this.contentBBox = Rect2.empty;
+    }
+    static ofGrid(backgroundColor, gridSize, gridColor, gridStrokeWidth) {
+        const background = new BackgroundComponent(BackgroundType.Grid, backgroundColor);
+        if (gridSize !== undefined) {
+            background.gridSize = gridSize;
+        }
+        if (gridColor !== undefined) {
+            background.secondaryColor = gridColor;
+        }
+        if (gridStrokeWidth !== undefined) {
+            background.gridStrokeWidth = gridStrokeWidth;
+        }
+        return background;
+    }
+    getBackgroundType() {
+        return this.backgroundType;
+    }
+    // @internal
+    getMainColor() {
+        return this.mainColor;
+    }
+    // @internal
+    getSecondaryColor() {
+        return this.secondaryColor;
+    }
+    // @internal
+    getGridSize() {
+        return this.gridSize;
+    }
+    getStyle() {
+        let color = this.mainColor;
+        if (this.backgroundType === BackgroundType.None) {
+            color = undefined;
+        }
+        return {
+            color,
+        };
+    }
+    updateStyle(style) {
+        return createRestyleComponentCommand(this.getStyle(), style, this);
+    }
+    // @internal
+    forceStyle(style, editor) {
+        const fill = style.color;
+        if (!fill) {
+            return;
+        }
+        this.mainColor = fill;
+        // A solid background and transparent fill is equivalent to no background.
+        if (fill.eq(Color4.transparent) && this.backgroundType === BackgroundType.SolidColor) {
+            this.backgroundType = BackgroundType.None;
+        }
+        else if (this.backgroundType === BackgroundType.None) {
+            this.backgroundType = BackgroundType.SolidColor;
+        }
+        if (editor) {
+            editor.image.queueRerenderOf(this);
+            editor.queueRerender();
+        }
+    }
+    onAddToImage(image) {
+        if (this.viewportSizeChangeListener) {
+            console.warn('onAddToImage called when background is already in an image');
+            this.onRemoveFromImage();
+        }
+        this.viewportSizeChangeListener = image.notifier.on(EditorImageEventType.ExportViewportChanged, () => {
+            this.recomputeBBox(image);
+        });
+        this.recomputeBBox(image);
+    }
+    onRemoveFromImage() {
+        var _a;
+        (_a = this.viewportSizeChangeListener) === null || _a === void 0 ? void 0 : _a.remove();
+        this.viewportSizeChangeListener = null;
+    }
+    recomputeBBox(image) {
+        const importExportRect = image.getImportExportViewport().visibleRect;
+        if (!this.contentBBox.eq(importExportRect)) {
+            this.contentBBox = importExportRect;
+            // Re-render this if already added to the EditorImage.
+            image.queueRerenderOf(this);
+        }
+    }
+    generateGridPath(visibleRect) {
+        var _a, _b;
+        const targetRect = (_b = (_a = visibleRect === null || visibleRect === void 0 ? void 0 : visibleRect.grownBy(this.gridStrokeWidth)) === null || _a === void 0 ? void 0 : _a.intersection(this.contentBBox)) !== null && _b !== void 0 ? _b : this.contentBBox;
+        const roundDownToGrid = (coord) => Math.floor(coord / this.gridSize) * this.gridSize;
+        const roundUpToGrid = (coord) => Math.ceil(coord / this.gridSize) * this.gridSize;
+        const startY = roundUpToGrid(targetRect.y);
+        const endY = roundDownToGrid(targetRect.y + targetRect.h);
+        const startX = roundUpToGrid(targetRect.x);
+        const endX = roundDownToGrid(targetRect.x + targetRect.w);
+        const result = [];
+        // Don't generate grids with a huge number of rows/columns -- such grids
+        // take a long time to render and are likely invisible due to the number of
+        // cells.
+        const rowCount = (endY - startY) / this.gridSize;
+        const colCount = (endX - startX) / this.gridSize;
+        const maxGridCols = 1000;
+        const maxGridRows = 1000;
+        if (rowCount > maxGridRows || colCount > maxGridCols) {
+            return Path.empty;
+        }
+        const startPoint = Vec2.of(targetRect.x, startY);
+        for (let y = startY; y <= endY; y += this.gridSize) {
+            result.push({
+                kind: PathCommandType.MoveTo,
+                point: Vec2.of(targetRect.x, y),
+            });
+            result.push({
+                kind: PathCommandType.LineTo,
+                point: Vec2.of(targetRect.x + targetRect.w, y),
+            });
+        }
+        for (let x = startX; x <= endX; x += this.gridSize) {
+            result.push({
+                kind: PathCommandType.MoveTo,
+                point: Vec2.of(x, targetRect.y),
+            });
+            result.push({
+                kind: PathCommandType.LineTo,
+                point: Vec2.of(x, targetRect.y + targetRect.h)
+            });
+        }
+        return new Path(startPoint, result);
+    }
+    render(canvas, visibleRect) {
+        if (this.backgroundType === BackgroundType.None) {
+            return;
+        }
+        const clip = true;
+        canvas.startObject(this.contentBBox, clip);
+        if (this.backgroundType === BackgroundType.SolidColor || this.backgroundType === BackgroundType.Grid) {
+            // If the rectangle for this region contains the visible rect,
+            // we can fill the entire visible rectangle (which may be more efficient than
+            // filling the entire region for this.)
+            if (visibleRect) {
+                const intersection = visibleRect.intersection(this.contentBBox);
+                if (intersection) {
+                    canvas.fillRect(intersection, this.mainColor);
+                }
+            }
+            else {
+                canvas.fillRect(this.contentBBox, this.mainColor);
+            }
+        }
+        if (this.backgroundType === BackgroundType.Grid) {
+            let gridColor = this.secondaryColor;
+            gridColor !== null && gridColor !== void 0 ? gridColor : (gridColor = Color4.ofRGBA(1 - this.mainColor.r, 1 - this.mainColor.g, 1 - this.mainColor.b, 0.2));
+            // If the background fill is completely transparent, ensure visibility on otherwise light
+            // and dark backgrounds.
+            if (this.mainColor.a === 0) {
+                gridColor = Color4.ofRGBA(0.5, 0.5, 0.5, 0.2);
+            }
+            const style = {
+                fill: Color4.transparent,
+                stroke: { width: this.gridStrokeWidth, color: gridColor }
+            };
+            canvas.drawPath(this.generateGridPath(visibleRect).toRenderable(style));
+        }
+        const backgroundTypeCSSClass = backgroundTypeToClassNameMap[this.backgroundType];
+        const classNames = [imageBackgroundCSSClassName];
+        if (backgroundTypeCSSClass !== imageBackgroundCSSClassName) {
+            classNames.push(backgroundTypeCSSClass);
+            const gridSizeStr = toRoundedString(this.gridSize).replace(/[.]/g, 'p');
+            classNames.push(imageBackgroundGridSizeCSSPrefix + gridSizeStr);
+        }
+        if (this.secondaryColor !== null) {
+            classNames.push(imageBackgroundNonAutomaticSecondaryColorCSSClassName);
+        }
+        canvas.endObject(this.getLoadSaveData(), classNames);
+    }
+    intersects(lineSegment) {
+        return this.contentBBox.getEdges().some(edge => edge.intersects(lineSegment));
+    }
+    isSelectable() {
+        return false;
+    }
+    isBackground() {
+        return true;
+    }
+    serializeToJSON() {
+        var _a;
+        return {
+            mainColor: this.mainColor.toHexString(),
+            secondaryColor: (_a = this.secondaryColor) === null || _a === void 0 ? void 0 : _a.toHexString(),
+            backgroundType: this.backgroundType,
+            gridSize: this.gridSize,
+            gridStrokeWidth: this.gridStrokeWidth,
+        };
+    }
+    applyTransformation(_affineTransfm) {
+        // Do nothing — it doesn't make sense to transform the background.
+    }
+    description(localizationTable) {
+        if (this.backgroundType === BackgroundType.SolidColor) {
+            return localizationTable.filledBackgroundWithColor(this.mainColor.toString());
+        }
+        else {
+            return localizationTable.emptyBackground;
+        }
+    }
+    createClone() {
+        return new BackgroundComponent(this.backgroundType, this.mainColor);
+    }
+    // @internal
+    static deserializeFromJSON(json) {
+        var _a, _b;
+        if (typeof json === 'string') {
+            json = JSON.parse(json);
+        }
+        if (typeof json.mainColor !== 'string') {
+            throw new Error('Error deserializing — mainColor must be of type string.');
+        }
+        let backgroundType;
+        const jsonBackgroundType = json.backgroundType;
+        if (jsonBackgroundType === BackgroundType.None || jsonBackgroundType === BackgroundType.Grid
+            || jsonBackgroundType === BackgroundType.SolidColor) {
+            backgroundType = jsonBackgroundType;
+        }
+        else {
+            const exhaustivenessCheck = jsonBackgroundType;
+            return exhaustivenessCheck;
+        }
+        const mainColor = Color4.fromHex(json.mainColor);
+        const secondaryColor = json.secondaryColor ? Color4.fromHex(json.secondaryColor) : null;
+        const gridSize = (_a = json.gridSize) !== null && _a !== void 0 ? _a : undefined;
+        const gridStrokeWidth = (_b = json.gridStrokeWidth) !== null && _b !== void 0 ? _b : undefined;
+        const result = new BackgroundComponent(backgroundType, mainColor);
+        result.secondaryColor = secondaryColor;
+        if (gridSize) {
+            result.gridSize = gridSize;
+        }
+        if (gridStrokeWidth) {
+            result.gridStrokeWidth = gridStrokeWidth;
+        }
+        return result;
+    }
+}
+AbstractComponent.registerComponent('image-background', BackgroundComponent.deserializeFromJSON);

package/dist/mjs/src/components/RestylableComponent.d.ts

@@ -1,16 +1,35 @@
 import Color4 from '../Color4';
 import SerializableCommand from '../commands/SerializableCommand';
 import Editor from '../Editor';
-import TextStyle from '../rendering/TextRenderingStyle';
+import TextRenderingStyle from '../rendering/TextRenderingStyle';
 import AbstractComponent from './AbstractComponent';
 export interface ComponentStyle {
     color?: Color4;
-    textStyle?: TextStyle;
+    textStyle?: TextRenderingStyle;
 }
 export declare const createRestyleComponentCommand: (initialStyle: ComponentStyle, newStyle: ComponentStyle, component: RestyleableComponent) => SerializableCommand;
 export declare const isRestylableComponent: (component: AbstractComponent) => component is RestyleableComponent;
+/**
+ * An interface to be implemented by components with a changable color or {@link TextRenderingStyle}.
+ *
+ * All such classes must have a member variable, `isRestylableComponent` that is set to `true`
+ * to allow testing whether the class is a `RestylableComponent` (see {@link isRestylableComponent}).
+ */
 export interface RestyleableComponent extends AbstractComponent {
+    /**
+     * @returns a partial representation of this component's style.
+     */
     getStyle(): ComponentStyle;
+    /**
+     * Returns a {@link Command} that updates portions of this component's style
+     * to the given `style`.
+     *
+     * @example
+     * For some component and editor,
+     * ```ts
+     * editor.dispatch(component.updateStyle({ color: Color4.red }));
+     * ```
+     */
     updateStyle(style: ComponentStyle): SerializableCommand;
     /**
      * Set the style of this component in a way that can't be undone/redone

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

@@ -8,11 +8,43 @@ import AbstractRenderer, { RenderablePathSpec } from '../rendering/renderers/Abs
 import AbstractComponent from './AbstractComponent';
 import { ImageComponentLocalization } from './localization';
 import RestyleableComponent, { ComponentStyle } from './RestylableComponent';
+/**
+ * Represents an {@link AbstractComponent} made up of one or more {@link Path}s.
+ *
+ * @example
+ * For some {@link Editor} editor and `Stroke` stroke,
+ *
+ * **Restyling**:
+ * ```ts
+ * editor.dispatch(stroke.updateStyle({ color: Color4.red }));
+ * ```
+ *
+ * **Transforming**:
+ * ```ts
+ * editor.dispatch(stroke.transformBy(Mat33.translation(Vec2.of(10, 0))));
+ * ```
+ */
 export default class Stroke extends AbstractComponent implements RestyleableComponent {
     private parts;
     protected contentBBox: Rect2;
     readonly isRestylableComponent: true;
     private approximateRenderingTime;
+    /**
+     * Creates a `Stroke` from the given `parts`. All parts should have the
+     * same color.
+     *
+     * @example
+     * ```ts
+     * // A path that starts at (1,1), moves to the right by (2, 0),
+     * // then moves down and right by (3, 3)
+     * const path = Path.fromString('m1,1 2,0 3,3');
+     *
+     * const stroke = new Stroke([
+     *     // Fill with red
+     *     path.toRenderable({ fill: Color4.red })
+     * ]);
+     * ```
+     */
     constructor(parts: RenderablePathSpec[]);
     getStyle(): ComponentStyle;
     updateStyle(style: ComponentStyle): SerializableCommand;
@@ -22,6 +54,9 @@ export default class Stroke extends AbstractComponent implements RestyleableComp
     getProportionalRenderingTime(): number;
     private bboxForPart;
     protected applyTransformation(affineTransfm: Mat33): void;
+    /**
+     * @returns the {@link Path.union} of all paths that make up this stroke.
+     */
     getPath(): Path;
     description(localization: ImageComponentLocalization): string;
     protected createClone(): AbstractComponent;