@lvl99dotcom/paintcanvas 0.0.0-stage → 0.3.0

package/dist/ui/elements/PcCanvas/index.d.ts

@@ -0,0 +1,356 @@
+import { type PropertyValues } from "lit";
+import { PcElement } from "../../base";
+import { Tool, type default as PaintCanvas } from "../../../lib/classes/PaintCanvas";
+import type { Insets, Point, Rect } from "../../../lib/classes/Viewport";
+import type { LassoKind } from "../../../lib/selection/Lasso";
+/** Toolbar width in CSS pixels (kept clear when fitting the canvas) */
+export declare const TOOLBAR_WIDTH = 50;
+/** Share of the screen width taken by the chat panel (kept clear when fitting the canvas) */
+export declare const CHAT_WIDTH_RATIO = 0.375;
+/** Lasso kind for each lasso tool */
+export declare const LASSO_TOOLS: Partial<Record<Tool, LassoKind>>;
+/** Distance (CSS pixels) within which a transform handle can be grabbed */
+export declare const HANDLE_GRAB_DISTANCE = 8;
+/** Milliseconds between steps of the crawling ants animation */
+export declare const ANTS_INTERVAL = 100;
+/** In focus pen mode, how long after a pen lifts touches are still ignored (milliseconds) */
+export declare const PEN_LIFT_GRACE_MS = 500;
+/**
+ * Space covered by the toolbar and chat on a screen of the given width.
+ *
+ * @example
+ * interfaceInsets(1000, true); // { top: 0, right: 375, bottom: 0, left: 50 }
+ */
+export declare const interfaceInsets: (width: number, interfaceVisible: boolean) => Insets;
+/**
+ * CSS cursor for a tool. The brush and eraser hide the cursor because their outline is drawn on the canvas; rectangle and circle lassos
+ * use the "+" crosshair; zoom uses the magnifier with "+" or "-".
+ *
+ * @example
+ * cursorFor(Tool.Zoom, { dragging: false, altKey: true }); // "zoom-out"
+ */
+/** How far above a finger the sampling window sits, so the finger doesn't cover it (screen pixels) */
+export declare const TOUCH_SAMPLER_GAP = 40;
+/** The sampling window's size: the colour on top of the enlarged pixels (screen pixels) */
+export declare const SAMPLER_WIDTH: number;
+export declare const SAMPLER_HEIGHT: number;
+/**
+ * Where the colour sample tool's window goes (its top left, in screen pixels): with a mouse or pen, so the outlined
+ * pixel in its enlarged view is on the pointer (which is hidden); with touch, centred above the finger. Kept on screen.
+ *
+ * @example
+ * samplerPosition({ x: 100, y: 200 }, false, 1000, 800); // { x: 72.5, y: 122.5 }
+ */
+export declare const samplerPosition: (point: Point, touch: boolean, width: number, height: number) => Point;
+export declare const cursorFor: (tool: Tool, { dragging, altKey }: {
+    dragging: boolean;
+    altKey: boolean;
+}) => string;
+/**
+ * The drawing area: a full-size canvas showing the composited layers through the viewport.
+ *
+ * Handles drawing with the brush and eraser (mouse, pen with pressure and tilt, or touch), and navigation: dragging with the pan tool (or while Space is held, or with the middle mouse button), clicking with the zoom tool (Alt to zoom out), scrolling or two-finger dragging to pan, and pinching or Cmd/Ctrl + scrolling to zoom (each as the user's settings allow).
+ * Taps and swipes with two or three fingers undo, redo, copy or paste, as the user's touch gesture settings say (see
+ * `GestureTracker`); two-finger pan and pinch wait until a finger moves further than a tap allows.
+ * In focus pen mode (a user setting), one finger does nothing (only pens draw), and touches are ignored altogether while
+ * a pen is down or for `PEN_LIFT_GRACE_MS` after it lifts, so a resting hand can't draw, pan or undo.
+ * The Move tool shows the transform box: drag inside it to move, a square handle to scale, or the round handle to rotate.
+ * The colour sample tool sets the current colour from what's shown under the pointer, or the average of a dragged area,
+ * showing a sampling window while sampling (see `drawSampler`).
+ * Lasso tools build mask shapes (see `Lasso`); the mask's outline is drawn as animated black and white "crawling ants".
+ * The mask outline and lasso shape are drawn on their own canvas; the brush cursor on an overlay that inverts what is underneath.
+ * Redraws at most once per animation frame, only when something changed. The first time it has a size, it fits the canvas beside the toolbar and chat.
+ *
+ * @example
+ * html`<pc-canvas .app=${app}></pc-canvas>`
+ */
+export declare class PcCanvas extends PcElement {
+    static properties: {
+        app: {
+            attribute: boolean;
+        };
+        insets: {
+            attribute: boolean;
+        };
+        translations: {
+            attribute: boolean;
+        };
+        icons: {
+            attribute: boolean;
+        };
+        theme: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+    };
+    static styles: import("lit").CSSResultGroup[];
+    app?: PaintCanvas;
+    /**
+     * Space covered by the interface on each side (CSS pixels), kept clear when fitting or centring the canvas. Without
+     * it, a toolbar on the left and (with the interface shown) a panel taking 37.5% on the right are assumed.
+     */
+    insets?: Insets;
+    /** The insets in effect (see `insets`) */
+    private get activeInsets();
+    /** Device pixels per CSS pixel (replaceable for tests) */
+    pixelRatio: () => number;
+    private changes;
+    /** Whether anything but the stroke in progress changed since the last update (so everything is redrawn) */
+    private fullChange;
+    /** The area the stroke in progress changed since the last update */
+    private strokeArea?;
+    /** Whether a finished stroke is being written into its layer (its layer change needs no redraw) */
+    private committing;
+    /** Whether the next frame redraws everything */
+    private drawAll;
+    /** The area the next frame redraws, if not everything */
+    private drawArea?;
+    /**
+     * Transform drag in progress: what is being changed, the box and pointer when it started, the pointer now, and (when
+     * scaling) whether "Constrain proportions" was on when it started
+     */
+    private transformDrag;
+    /** Crawling ants animation timer while a mask is active */
+    private antsTimer?;
+    /** Current crawling ants dash offset */
+    private antsOffset;
+    /** Viewport that has been fitted once (so resizing doesn't refit) */
+    private fittedViewport?;
+    private frame;
+    /** Animation frame drawing only the brush cursor, if requested */
+    private overlayFrame;
+    private resizeObserver?;
+    private drag;
+    /** Pointer drawing the current stroke, and the layer it draws on */
+    private stroke;
+    /** Pointer position over the stage (for the brush cursor), or null when outside */
+    private hover;
+    /** Name of the key held to zoom with the scroll wheel (replaceable for tests) */
+    modifier: "Cmd" | "Ctrl";
+    /** Touches on the stage by pointer ID, for two-finger pan and pinch */
+    private readonly touches;
+    /** The two-finger gesture in progress: where its touches' midpoint and spread were last */
+    private pinch;
+    /**
+     * A colour sample in progress: the pointer, whether it's a finger, where it started and is now (canvas pixels), and
+     * where it is on screen
+     */
+    private sampling;
+    /** Recognises taps and swipes with two or three fingers, for the actions in the user's touch gesture settings */
+    private readonly gestureTracker;
+    /** Pens touching the stage, by pointer ID */
+    private readonly pens;
+    /** When a pen last lifted (event time) */
+    private penLiftedAt;
+    /** Touches ignored altogether in focus pen mode (they touched while a pen was down or had just lifted) */
+    private readonly ignoredTouches;
+    /** Touches that can only pan, pinch and make gestures in focus pen mode (one finger does nothing) */
+    private readonly navigationTouches;
+    /** Zoom when a Safari trackpad pinch started */
+    private gestureZoom;
+    private altKey;
+    private readonly onModifierKey;
+    /** The screen canvas */
+    get canvas(): HTMLCanvasElement | null;
+    /** The canvas for the colour sample tool's window and area */
+    get sampler(): HTMLCanvasElement | null;
+    /** The overlay canvas for the brush cursor */
+    get overlay(): HTMLCanvasElement | null;
+    /** The canvas for the mask outline and lasso shape (no blend mode: drawn in black and white) */
+    get outlines(): HTMLCanvasElement | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    firstUpdated(): void;
+    /**
+     * Note what changed: the stroke in progress (and the area it changed), or anything else.
+     */
+    private sceneChanged;
+    updated(changed: PropertyValues): void;
+    /**
+     * Match the canvas's pixel size to its on-screen size and pixel ratio, and update the viewport. Fits the canvas the
+     * first time. Returns whether the canvas was resized (which clears it).
+     */
+    syncSize(): boolean;
+    /**
+     * Schedule a redraw of everything, or of an area of the canvas, on the next animation frame (repeated requests are
+     * combined; redrawing everything wins).
+     */
+    requestDraw(area?: Rect): void;
+    /**
+     * Draw the scene now (with the stroke in progress, if any), or only an area of the canvas, then the brush cursor.
+     */
+    draw(area?: Rect): void;
+    /**
+     * Schedule drawing the brush cursor on the next animation frame (repeated requests are combined, and a scene redraw
+     * draws it too).
+     */
+    requestOverlay(): void;
+    /**
+     * Draw the brush cursor on the overlay: a 1:1 outline of the brush or eraser shape at the pointer. For presets that
+     * snap to the pixel grid, the outline covers the pixels the stamp will.
+     */
+    drawOverlay(): void;
+    /**
+     * Draw the mask outline (crawling ants) and the lasso shape in progress in black and white on their own canvas.
+     */
+    private drawOutlines;
+    /**
+     * The square handles of the transform box (the 8 scale handles) while the Move tool is in use, or none.
+     */
+    private transformHandles;
+    /**
+     * What the pointer is over in the transform box: the rotate handle, a scale handle, inside the box, or none of them.
+     */
+    private transformPart;
+    /**
+     * Start rotating, scaling or moving the transform box, depending on where the pointer is: on the round handle, a
+     * square handle, or anywhere else (moving).
+     */
+    private beginTransformDrag;
+    /**
+     * Update the transform box while dragging.
+     */
+    private continueTransformDrag;
+    /**
+     * Change the transform box for the drag in progress, with the modifier keys held now. While scaling, "Constrain
+     * proportions" is turned on while Shift is held (if it was off when the drag started), or off while Alt is held (if
+     * it was on), and shows so in the settings bar.
+     */
+    private applyTransformDrag;
+    /**
+     * End the transform drag of a pointer, if it has one: "Constrain proportions" goes back to how it was when a scale
+     * drag started.
+     */
+    private endTransformDrag;
+    /**
+     * Cursor while hovering with the Move tool: the grab cursor over the rotate handle, a two-way arrow along a scale
+     * handle's direction (turned with the box), four-way arrows inside the box, and the default cursor elsewhere.
+     */
+    private transformCursor;
+    /**
+     * Start or stop the crawling ants animation.
+     */
+    private animateAnts;
+    /**
+     * Handle a lasso tool press: start a shape, add a polygon node, or close a polygon on its first node.
+     */
+    private lassoDown;
+    /**
+     * Draw the last stroke's recorded points (circles) and stamp positions (dots) for tuning how brushes feel.
+     */
+    private drawDebugTrace;
+    /**
+     * The brush or eraser settings for the tool in use, if it draws.
+     */
+    private brushSettings;
+    /**
+     * Convert a pointer event to a stroke point in canvas pixels, with pen pressure and tilt.
+     */
+    private strokePoint;
+    /**
+     * Start a brush or eraser stroke on the active layer (cancelling any other stroke in progress), logging how long it
+     * took. Hidden layers cannot be drawn on.
+     */
+    private beginStroke;
+    /**
+     * Get a pointer's position relative to the stage.
+     */
+    private pointerPoint;
+    /**
+     * Start panning, or zoom, depending on the tool and button. In focus pen mode, touches only pan, pinch and make
+     * gestures, and are ignored while a pen is down or just lifted (see `focusPenTouch`).
+     */
+    private onPointerDown;
+    /**
+     * Continue a stroke (using every in-between event the browser recorded), pan while dragging, and move the brush cursor.
+     */
+    private onPointerMove;
+    /**
+     * Finish a stroke (writing it into the layer) or stop panning.
+     */
+    private onPointerUp;
+    /**
+     * Abandon a stroke or pan when the browser cancels the pointer (e.g. a system gesture).
+     */
+    private onPointerCancel;
+    /**
+     * Keep the browser from handling touches on the canvas itself while the brush or eraser is in use (e.g. Safari on
+     * iPad holding back quick Apple Pencil strokes while it checks for its own gestures). Other tools keep the browser's
+     * handling, so a double tap still closes a polygon lasso. Pointer events are unaffected.
+     */
+    private readonly onTouchStart;
+    /**
+     * Note a pen touching down. In focus pen mode, touches already on the stage are ignored from now on, abandoning any
+     * pan, pinch or gesture they were making (e.g. a palm resting on the screen).
+     */
+    private penDown;
+    /** Note a pen lifting (or being cancelled), and when */
+    private penUp;
+    /**
+     * In focus pen mode, why a touch is ignored altogether: a pen is down, or lifted less than `PEN_LIFT_GRACE_MS` ago
+     * (a hand landing as the pen lifts). Undefined if the touch counts.
+     */
+    private focusPenTouch;
+    /**
+     * Note a touch. A second touch stops any stroke or pan and starts a two-finger gesture; a third stops two-finger pan
+     * and pinch, for three-finger gestures. Returns whether the touch is part of a gesture (and so does nothing else).
+     */
+    private touchDown;
+    /**
+     * Start sampling a colour with the colour sample tool: the pointer is hidden while the sampling window shows.
+     */
+    private beginSample;
+    /**
+     * Set the current colour from the sample: the pixel under the pointer, or the average of every pixel in the area.
+     * Nothing changes if it's outside the canvas.
+     */
+    private finishSample;
+    /** Stop sampling and close the sampling window */
+    private endSample;
+    /**
+     * Draw the colour sample tool's window while sampling (see `samplerPosition`): the sampled colour on top (the area's
+     * average while dragging an area, worked out from at most `PREVIEW_MAX_PIXELS` across), and the pixels around the
+     * pointer enlarged below, with the sampled pixel outlined. An area being sampled is outlined on the canvas.
+     */
+    private drawSampler;
+    /**
+     * Do what the user's touch gesture settings say a gesture does: undo, redo, copy or paste.
+     */
+    private runGesture;
+    /**
+     * Pan by how far the two touches' midpoint moved and zoom by how much their spread changed, around the midpoint.
+     */
+    private movePinch;
+    /**
+     * Forget a lifted touch; the gesture ends once fewer than two touches are left.
+     */
+    private touchUp;
+    /**
+     * Pan with the wheel or two-finger scroll, and zoom around the pointer with a pinch or Cmd/Ctrl + scroll (see
+     * `wheelAction`). The page itself never scrolls or zooms.
+     */
+    private onWheel;
+    /**
+     * Start a Safari trackpad pinch (Safari reports these as gesture events, not Ctrl + wheel). Touch screens use the
+     * pointer events instead.
+     */
+    private onGestureStart;
+    /**
+     * Zoom with a Safari trackpad pinch, around the pointer.
+     */
+    private onGestureChange;
+    /**
+     * Hide the brush cursor (and the user's shared cursor) when the pointer leaves the stage.
+     */
+    private onPointerLeave;
+    /**
+     * Tell the app where the pointer is on the canvas, in whole canvas pixels (undefined when off the canvas), so it can be
+     * shared with others in a session.
+     */
+    private reportPointer;
+    /**
+     * Show the cursor for the tool in use.
+     */
+    private updateCursor;
+    render(): import("lit").TemplateResult<1>;
+}