@lvl99dotcom/paintcanvas 0.0.0-stage → 0.2.0

package/dist/lib/classes/PaintCanvas/index.d.ts

@@ -0,0 +1,537 @@
+import StrokeLog from "../StrokeLog";
+import BackgroundWork from "../BackgroundWork";
+import type { DrawableLayer } from "../../rendering/compositing";
+import BrushSettings from "../BrushSettings";
+import LayerStack from "../LayerStack";
+import type History from "../History";
+import Viewport, { type Point, type Rect } from "../Viewport";
+import StrokeEngine from "../../brushes/StrokeEngine";
+import BrushTipCache from "../../brushes/BrushTipCache";
+import Selection from "../../selection/Selection";
+import Lasso, { type LassoResult } from "../../selection/Lasso";
+import Transformer from "../../transform/Transformer";
+import { type CanvasFactory, type LayerConfig } from "../Layer";
+import LayerAutosave, { type AutosaveOptions } from "../LayerAutosave";
+import type { LayerStoreLike } from "../../storage";
+import type { AssetAuthor, BrushConfig } from "../../brushes/types";
+import CustomPresets, { type PresetStoreLike } from "../CustomPresets";
+import InputSettings from "../InputSettings";
+import ExternalSheets from "../ExternalSheets";
+import { type CanvasMessage, type PatchMessage, type StrokeMessage } from "../../messages";
+import { type BoundingBox } from "../../image";
+import { type PaintCanvasDocument } from "../../document";
+/** Drawing and navigation tools */
+export declare enum Tool {
+    Brush = "brush",
+    Eraser = "eraser",
+    /** Move, scale and rotate */
+    Move = "move",
+    RectangleLasso = "rectangle-lasso",
+    CircleLasso = "circle-lasso",
+    PolygonLasso = "polygon-lasso",
+    FreeformLasso = "freeform-lasso",
+    Pan = "pan",
+    Zoom = "zoom",
+    /** Set the current colour from the canvas (eyedropper) */
+    ColourSample = "colour-sample"
+}
+/** How the colour sample tool samples: the pixel under the pointer, or the average of a dragged rectangle */
+export type SampleMode = "point" | "area";
+/** Toggleable panels */
+export declare enum Panel {
+    Brush = "brush",
+    Eraser = "eraser",
+    Layers = "layers",
+    /** The implementer's own app menu */
+    Menu = "menu"
+}
+/** Panels opened by tools */
+export declare const TOOL_PANELS: Partial<Record<Tool, Panel>>;
+/** Canvas width and height when none is given */
+export declare const DEFAULT_CANVAS_SIZE = 2000;
+/** Largest canvas width or height allowed when the `maxCanvasSize` option isn't given */
+export declare const MAX_CANVAS_SIZE = 2000;
+/** Drawing colour to start with */
+export declare const DEFAULT_COLOUR = "#000000";
+/** Owner of the custom presets when the `ownerId` option isn't given */
+export declare const DEFAULT_OWNER_ID = "local";
+/** Author name of presets made with `newPreset` when the `presetAuthor` option isn't given */
+export declare const DEFAULT_AUTHOR = "Unknown";
+/** Names the implementer can change: what users see and what files are called */
+export interface PaintCanvasNames {
+    /** The app's name, e.g. the heading of the brush presets that come with it */
+    app: string;
+    /** Start of the names of saved files, e.g. screenshots and exported presets */
+    filePrefix: string;
+    /** The `format` written in exported brush preset files */
+    presetFileFormat: string;
+    /** Author name of presets made by a user without a handle, e.g. from `presetAuthor` */
+    unknownAuthor: string;
+}
+/** PaintCanvas's own names */
+export declare const DEFAULT_NAMES: Readonly<PaintCanvasNames>;
+/** How much the canvas holds, e.g. to show in a stats panel */
+export interface CanvasStats {
+    /** Canvas width in pixels */
+    width: number;
+    /** Canvas height in pixels */
+    height: number;
+    /** Number of the user's layers */
+    layers: number;
+    /** Number of drawings from elsewhere */
+    externalSheets: number;
+    /** Memory the layers and drawings from elsewhere take as pixels (bytes, estimated: 4 per pixel) */
+    memoryBytes: number;
+    /** Undo steps recorded */
+    historySteps: number;
+    /** Most undo steps kept */
+    historyLimit: number;
+}
+/** Receives the drawing messages PaintCanvas sends; a returned promise that rejects means a patch wasn't delivered */
+export type MessageListener = (message: CanvasMessage) => void | Promise<void>;
+/** Options for sending drawing messages (see `startSending`) */
+export interface SendingOptions {
+    /** Send patches of the user's drawing (default true) */
+    patches?: boolean;
+    /** Send each finished stroke (default false) */
+    strokes?: boolean;
+    /** How long to wait after a change before sending a patch, so quick changes go together (milliseconds) */
+    delayMs?: number;
+}
+/** A stroke to draw: what a stroke message holds, without the protocol details */
+export type StrokeData = Omit<StrokeMessage, "protocol" | "type" | "step" | "layer">;
+export interface PaintCanvasOptions {
+    /** Canvas width in pixels */
+    width?: number;
+    /** Canvas height in pixels */
+    height?: number;
+    /** Largest canvas width or height allowed (default `MAX_CANVAS_SIZE`) */
+    maxCanvasSize?: number;
+    /** Most layers the user can have (default `DEFAULT_MAX_LAYERS`) */
+    maxLayers?: number;
+    /** Creates layer canvases (replaceable for tests) */
+    createCanvas?: CanvasFactory;
+    /** Where custom brush presets are kept (defaults to keeping them in memory only) */
+    presetStore?: PresetStoreLike;
+    /** Who the custom presets belong to, passed to the preset store (default `DEFAULT_OWNER_ID`) */
+    ownerId?: string;
+    /** Gives the author of presets made with `newPreset` (asked each time, so it can follow name changes) */
+    presetAuthor?: () => AssetAuthor;
+    /** Names to use instead of PaintCanvas's own (see `DEFAULT_NAMES`) */
+    names?: Partial<PaintCanvasNames>;
+    /** Where to keep the user's layers so the drawing survives reloading the page (see `useLayerStore`) */
+    layerStore?: LayerStoreLike;
+}
+/**
+ * The painting engine: canvas size, layers, brush and eraser settings, custom presets, the selected tool, colour,
+ * selection, transforms, clipboard, undo/redo history, viewport and input settings. Where its data is kept and who it
+ * is shared with are up to the implementer (see `onMessage` and `receive`).
+ *
+ * Dispatches a `change` event whenever its own state changes. Layers, brushes and selection dispatch their own `change`
+ * events. Also dispatches `pointer` when the pointer moves over the canvas.
+ *
+ * @example
+ * const canvas = new PaintCanvas({ width: 1000, height: 800 });
+ * canvas.selectTool(Tool.Brush, { fromToolbar: true });
+ * canvas.setColour("#ff0000");
+ */
+export default class PaintCanvas extends EventTarget {
+    /** Brush settings */
+    readonly brush: BrushSettings;
+    /** Eraser settings */
+    readonly eraser: BrushSettings;
+    /** The user's own and imported brush presets, listed with the brush and eraser presets */
+    readonly customPresets: CustomPresets;
+    /** Lasso shape in progress */
+    readonly lasso: Lasso;
+    /** Brush shapes, loaded per preset */
+    readonly tips: BrushTipCache;
+    /** Log of strokes started, ended, cancelled and ignored, with timings, for debugging */
+    readonly strokeLog: StrokeLog;
+    /** Whether the debug log shows (see `showDebugLog`) */
+    protected debugLogShown: boolean;
+    /** Slow work that waits for pauses in drawing (syncing, the canvas map and layer thumbnails, saving) */
+    readonly background: BackgroundWork;
+    /** How the user's input devices control the canvas (scrolling, pinching, touch gestures, focus pen mode) */
+    readonly input: InputSettings;
+    /** The user's pointer position over the canvas, in canvas pixels (undefined when off the canvas) */
+    pointer?: Point;
+    /** Selected tool */
+    tool: Tool;
+    /** Tool used temporarily while a key is held (e.g. Space for pan), overriding the selected tool */
+    heldTool: Tool | null;
+    /** Open panel, if any */
+    panel: Panel | null;
+    /** Whether the interface (toolbar, panels and anything the implementer adds) is visible ("tab" key) */
+    interfaceVisible: boolean;
+    /**
+     * Whether scaling the Move tool's box keeps its proportions ("Constrain proportions"), from its settings bar and when
+     * dragging a handle. Off by default; while drag-scaling, holding Shift turns it on (when off) and Alt turns it off
+     * (when on), until released.
+     */
+    constrainProportions: boolean;
+    /** How the colour sample tool samples ("point" by default) */
+    sampleMode: SampleMode;
+    private canvasWidth;
+    private canvasHeight;
+    private layerStack;
+    private view;
+    private strokeEngine;
+    private currentSelection;
+    private transformer;
+    private readonly onLayersOrMaskChange;
+    private readonly onStrokeBegin;
+    private readonly onStrokeEnd;
+    private readonly onStrokeCommit;
+    private readonly onHistoryStep;
+    /** Whether drawing messages are sent (see `startSending`) */
+    private isSending;
+    /** Whether finished strokes are sent (see `startSending`) */
+    private sendingStrokes;
+    /** Whether a stroke from elsewhere is being drawn (it isn't sent again) */
+    private replaying;
+    private currentColour;
+    /** Image data copied with cut or copy, and the area it was copied from */
+    private clipboard?;
+    /** Drawings from elsewhere */
+    private externalSheets;
+    /** Who receives the drawing messages this canvas sends */
+    private readonly messageListeners;
+    /** Sends patches while sending (see `startSending`) */
+    private sender?;
+    /** The layer stack whose changes are being sent */
+    private sendingLayers?;
+    private readonly onLayersChangeToSend;
+    /** Creates the canvases the app draws on (fake ones in tests) */
+    readonly createCanvas: CanvasFactory;
+    /** Who the custom presets belong to (passed to the preset store) */
+    readonly ownerId: string;
+    /** The largest canvas width or height allowed */
+    readonly maxCanvasSize: number;
+    /** Most layers the user can have */
+    readonly maxLayers: number;
+    /** Names users see and saved files are called by (see `PaintCanvasNames`) */
+    readonly names: Readonly<PaintCanvasNames>;
+    /** Gives the author of presets made with `newPreset` */
+    private readonly presetAuthor;
+    /** Keeps the user's layers in a store, while one is used */
+    private layerAutosave?;
+    constructor(options?: PaintCanvasOptions);
+    /** Canvas width in pixels */
+    get width(): number;
+    /** Canvas height in pixels */
+    get height(): number;
+    /** Drawings from elsewhere (e.g. other people's), drawn under the user's own layers (see `receive`) */
+    get external(): ExternalSheets;
+    /** Everything drawn on the canvas, top first: the user's own layers, then drawings from elsewhere */
+    get drawables(): readonly DrawableLayer[];
+    /**
+     * Listen for the drawing messages this canvas sends, e.g. to pass them to other people. Returns a function that stops
+     * listening.
+     *
+     * @example
+     * const stop = canvas.onMessage((message) => transport.send(message));
+     * canvas.startSending();
+     */
+    onMessage(listener: MessageListener): () => void;
+    /**
+     * Give a message to every listener. Rejects if any listener's delivery fails.
+     */
+    private emit;
+    /**
+     * Start sending drawing messages to `onMessage` listeners:
+     * - patches (by default): shortly after the user's layers change (and once drawing pauses), the area of their drawing
+     *   that changed
+     * - strokes (when asked): each finished brush or eraser stroke
+     * - undo and redo: the step undone or redone
+     *
+     * Changing the canvas size stops sending.
+     */
+    startSending(options?: SendingOptions): void;
+    /**
+     * Stop sending patches. Changes waiting to be sent are dropped.
+     */
+    stopSending(): void;
+    /** Whether drawing messages are being sent (see `startSending`) */
+    get sending(): boolean;
+    /**
+     * Send a patch of what changed now instead of waiting. Resolves once sent (or straight away when not sending
+     * patches).
+     */
+    sendNow(): Promise<void>;
+    /**
+     * Count pixels of the user's drawing as already sent, so they aren't sent again (e.g. their earlier work, restored
+     * from a shared drawing's history).
+     */
+    markSent(area: BoundingBox, rgba: Uint8ClampedArray): void;
+    /**
+     * A patch of the user's whole drawing (all their layers, flattened), e.g. for someone who joins late. Undefined if
+     * nothing is drawn.
+     */
+    snapshot(): Promise<PatchMessage | undefined>;
+    /**
+     * Apply a drawing message received from a source (an ID the implementer chooses, e.g. a user ID): a patch is drawn
+     * onto that source's sheet. Messages are checked first; invalid ones are ignored. Resolves to whether it was applied.
+     *
+     * @example
+     * transport.onMessage((from, message) => canvas.receive(from, message));
+     */
+    receive(source: string, message: unknown): Promise<boolean>;
+    /**
+     * The drawing as a document: its size, the user's layers and drawings from elsewhere, with PNG images (see
+     * `PaintCanvasDocument`). Turn it into JSON to save it as a file.
+     *
+     * @example
+     * const json = JSON.stringify(await canvas.exportDocument());
+     */
+    exportDocument(): Promise<PaintCanvasDocument>;
+    /**
+     * Replace the drawing with a document (e.g. read from a file): its size, layers and drawings from elsewhere. Undo
+     * history starts again. Returns whether it was loaded: not when the document is invalid or an image can't be
+     * decoded, and then nothing changes.
+     *
+     * @example
+     * await canvas.importDocument(JSON.parse(text));
+     */
+    importDocument(document: unknown): Promise<boolean>;
+    /**
+     * Replace the canvas size and the user's layers (top first, each with its image) and select one by ID. Undo history
+     * starts again. Throws if the size or number of layers isn't allowed.
+     *
+     * @example
+     * canvas.restoreLayers(800, 600, [{ id: "a", name: "Sketch" }], [sketchImage], "a");
+     */
+    restoreLayers(width: number, height: number, layers: readonly LayerConfig[], images: readonly CanvasImageSource[], activeLayer: string): void;
+    /** Keeps the user's layers in a store, while one is used (see `useLayerStore`) */
+    get autosave(): LayerAutosave | undefined;
+    /**
+     * Keep the user's layers in a store (or stop, without one), so the drawing survives reloading the page: the saved
+     * drawing is restored, then changes are saved. Only one window draws on a drawing at a time (see `LayerAutosave`).
+     * Returns the autosave.
+     *
+     * @example
+     * canvas.useLayerStore(new IndexedDbLayerStore("my-drawing"));
+     */
+    useLayerStore(store: LayerStoreLike | undefined, options?: AutosaveOptions): LayerAutosave | undefined;
+    /**
+     * How much the canvas holds: its size, layers, drawings from elsewhere, memory and undo steps.
+     */
+    stats(): CanvasStats;
+    /**
+     * Draw a recorded stroke (e.g. received from elsewhere) onto one of the user's layers, as an action they can undo.
+     * It isn't sent as a stroke message. Does nothing during a stroke, or if there's no such layer. Returns whether it was
+     * drawn.
+     *
+     * @example
+     * canvas.drawStroke(canvas.layers.active.id, strokeMessage);
+     */
+    drawStroke(layerId: string, stroke: StrokeData): boolean;
+    /**
+     * Draw a recorded stroke with a stroke engine, point by point.
+     */
+    private replay;
+    /**
+     * Put a patch's pixels onto one of the user's layers (replacing what was there), as an action they can undo. Returns
+     * whether it was applied: not for an invalid patch, or if there's no such layer.
+     *
+     * @example
+     * await canvas.applyPatch(canvas.layers.active.id, patch);
+     */
+    applyPatch(layerId: string, patch: unknown): Promise<boolean>;
+    /**
+     * The colour shown at a canvas point (every layer mixed as shown, over the white background), or undefined outside the
+     * canvas.
+     *
+     * @example
+     * app.sampleColour({ x: 10.4, y: 20.9 }); // "#ff0000"
+     */
+    sampleColour(point: Point): string | undefined;
+    /**
+     * The average colour shown in the rectangle between two canvas points (cut to the canvas), counting every pixel, or
+     * undefined outside the canvas. With `maxPixels`, it's worked out from the area scaled down to at most that many
+     * pixels across, which is quicker (for a preview while dragging).
+     *
+     * @example
+     * app.sampleAreaColour({ x: 0, y: 0 }, { x: 99, y: 99 }); // the average of 100 × 100 pixels
+     */
+    sampleAreaColour(a: Point, b: Point, maxPixels?: number): string | undefined;
+    /**
+     * The `SAMPLE_PIXELS` × `SAMPLE_PIXELS` canvas pixels around a point as shown (the point's pixel is at the middle,
+     * rounding down), for the colour sample tool's enlarged view. Pixels outside the canvas are transparent.
+     */
+    samplePixels(point: Point): OffscreenCanvas;
+    /** Draw an area of the canvas as shown onto a new canvas (see `flattenArea`) */
+    private flatten;
+    /** The user's view of the canvas (zoom and position) */
+    get viewport(): Viewport;
+    /** Whether the debug log shows */
+    get debugLog(): boolean;
+    /**
+     * Show or hide the debug log. Strokes and timings are only recorded while it shows.
+     */
+    showDebugLog(shown: boolean): void;
+    /** Draws brush and eraser strokes */
+    get strokes(): StrokeEngine;
+    /** The mask limiting where drawing applies */
+    get selection(): Selection;
+    /** Moves, scales and rotates the active layer's pixels with the Move tool */
+    get transform(): Transformer;
+    /** The user's undoable actions */
+    get history(): History;
+    /**
+     * Listen for layer and mask changes on the current layer stack and selection, and for strokes starting and ending
+     * (background work waits for pauses in drawing).
+     */
+    private watchLayersAndMask;
+    /**
+     * Show the transform box when the Move tool is selected, and apply any transform when switching away or to another layer.
+     */
+    private syncTransform;
+    /**
+     * Write the transformed pixels into the layer (Enter, or switching tool). The mask moves with them.
+     */
+    commitTransform(): void;
+    /**
+     * Undo the user's latest action. A move or rotate that hasn't been applied is cancelled instead, and nothing happens
+     * during a stroke.
+     */
+    undo(): void;
+    /**
+     * Redo the user's latest undone action. A move or rotate that hasn't been applied is cancelled instead, and nothing
+     * happens during a stroke.
+     */
+    redo(): void;
+    /**
+     * Whether undo or redo can move along the history now: not during a stroke, and not while a transform is pending (which
+     * is cancelled instead).
+     */
+    private canStepHistory;
+    /**
+     * Put transformed pixels back where they were (Escape).
+     */
+    cancelTransform(): void;
+    /**
+     * Copy the masked image data of the selected layer to the clipboard. Needs a mask with image data inside it; does
+     * nothing during a stroke or while a transform is pending. Returns the area copied, if any.
+     */
+    copy(): Rect | undefined;
+    /**
+     * Copy the masked image data of the selected layer to the clipboard, then erase it from the layer as one undoable
+     * action.
+     */
+    cut(): void;
+    /**
+     * Erase the masked image data from the selected layer as one undoable action (Delete or Backspace). Needs a mask with
+     * image data inside it; does nothing during a stroke or while a transform is pending.
+     */
+    deleteMasked(): void;
+    /**
+     * The bounds of the selected layer's image data inside the mask, if there is a mask with image data inside it. None
+     * during a stroke or while a transform is pending.
+     */
+    private maskedArea;
+    /**
+     * Erase the mask's part of an area from the selected layer, as one undoable action.
+     */
+    private eraseMasked;
+    /**
+     * Show the clipboard's image data over the selected layer where it was copied from, and select the Move tool to place,
+     * scale and rotate it. It is written into the layer (and sent) on Enter or when switching to another tool; Escape
+     * discards it. A pending transform is applied first.
+     */
+    paste(): void;
+    /**
+     * Apply a finished lasso action to the mask: a shape is added, subtracted or replaces it; a plain click deselects.
+     */
+    applyLasso(result: LassoResult): void;
+    /**
+     * Whether a preset comes with the app (it can't be deleted, replaced or exported).
+     */
+    isBuiltInPreset(id: string): boolean;
+    /**
+     * The handle of the author of presets the user makes (from the `presetAuthor` option), or "" if they have none. Their
+     * own presets are the ones with this handle (see `isOwnAuthor`).
+     */
+    get authorHandle(): string;
+    /**
+     * Make a new custom preset from settings: a new ID, the given name, and the author from the `presetAuthor` option.
+     *
+     * @example
+     * app.newPreset(app.brush.preset, "My brush"); // { ...settings, id: "0b5c…", name: "My brush", author: { name, handle } }
+     */
+    newPreset(settings: BrushConfig, name: string): BrushConfig;
+    /**
+     * List the custom presets after the built-in ones, for the brush and the eraser.
+     */
+    private listCustomPresets;
+    /** The tool currently in effect: the held tool if a key is held, otherwise the selected tool */
+    get activeTool(): Tool;
+    /** The user's layers */
+    get layers(): LayerStack;
+    /** Current drawing colour as a hex string, e.g. `#000000` */
+    get colour(): string;
+    /**
+     * Set the drawing colour. Must be a 6-digit hex colour, e.g. `#ff0000`.
+     */
+    setColour(colour: string): void;
+    /**
+     * Change the canvas size, from 1 to the maximum canvas size (`maxCanvasSize` option). Replaces all layers.
+     */
+    setCanvasSize(width: number, height: number): void;
+    /**
+     * Called when the canvas size changes, before `change` is dispatched. Subclasses resize anything of their own here.
+     */
+    protected canvasResized(width: number, height: number): void;
+    /**
+     * Check a canvas dimension is a whole number from 1 to the maximum canvas size.
+     */
+    private isValidCanvasDimension;
+    /**
+     * Set whether scaling the Move tool's box keeps its proportions.
+     */
+    setConstrainProportions(constrain: boolean): void;
+    /**
+     * Set how the colour sample tool samples.
+     */
+    setSampleMode(mode: SampleMode): void;
+    /**
+     * Set where the user's pointer is over the canvas (undefined when it leaves). Dispatches `pointer` when it moves.
+     */
+    setPointer(position: Point | undefined): void;
+    /**
+     * Select a tool.
+     *
+     * - Clicking a toolbar button (`fromToolbar: true`) only selects the tool: its presets open from the settings bar's
+     *   preset button.
+     * - Pressing a tool's shortcut selects the tool, or toggles its panel if the tool is already selected.
+     *
+     * Switching tools closes the previous tool's panel (the layers panel and app menu stay open).
+     */
+    selectTool(tool: Tool, options?: {
+        fromToolbar?: boolean;
+    }): void;
+    /**
+     * Use a tool temporarily while a key is held (e.g. Space for pan). The selected tool is unchanged.
+     */
+    holdTool(tool: Tool): void;
+    /**
+     * Stop using the held tool and return to the selected tool.
+     */
+    releaseHeldTool(): void;
+    /**
+     * Close the open panel, if any.
+     */
+    closePanel(): void;
+    /**
+     * Open a panel, or close it if already open.
+     */
+    togglePanel(panel: Panel): void;
+    /**
+     * Show or hide the interface.
+     */
+    toggleInterface(): void;
+    /**
+     * Dispatch a `change` event.
+     */
+    protected notify(): void;
+}