Added JSDocs

Author: Kevin Busch

src/atoms/forms/canvas-sketch/canvas-sketch.ts

@@ -26,7 +26,8 @@ export interface CanvasSketchConfig {
 // #endregion Interfaces
 
 /**
- * Binds to the provided HTML canvases element and gives various tool capabilities
+ * Binds to the provided HTML canvases element in the contructor and provides access to switch
+ * the selected tool and selected tool options like color and width through it's API
  */
 class CanvasSketch {
 
@@ -45,6 +46,12 @@ class CanvasSketch {
     private _sketchContext!: CanvasRenderingContext2D;
     private _toolConfig!: ToolConfig;
 
+    /**
+     * Tracks
+     *
+     * @constructor
+     * @param {CanvasSketchConfig} canvasSketchConfig - configuration of object
+     */
     constructor(canvasSketchConfig: CanvasSketchConfig) {
         this._drawToolUiSettings = {
             color: "FFFFFF", // default
@@ -75,6 +82,10 @@ class CanvasSketch {
     // #region Public Methods
     // ---------------------------------------------------------------------------------------------
 
+    /**
+     * Disposes of any active bound events through the selected tool and anything else that this
+     * object may need to clean up
+     */
     public dispose(): void {
         if (!this._isBrowserSupported) {
             return;
@@ -83,6 +94,11 @@ class CanvasSketch {
         this.selectedTool.dispose();
     }
 
+    /**
+     * Gets the appropriate canva tool based on the provided tool type
+     *
+     * @param {CanvasToolType} toolType - The tool type of the tool caller is looking to use
+     */
     public getTool(toolType: CanvasToolType): CanvasTool | null {
         if (!this._isBrowserSupported) {
             return null;
@@ -102,11 +118,11 @@ class CanvasSketch {
         }
     }
 
-    public redrawCurrentState(): void {
-        this._redrawBackgroundImage();
-        this._redrawSketch();
-    }
-
+    /**
+     * Redraws the background image based on the URL provided
+     *
+     * @param {string} backgroundImageUrl - The URL of the background image to draw
+     */
     public redrawBackgroundImageUsing(backgroundImageUrl: string): void {
         if (this._config.backgroundImage == null) {
             return;
@@ -115,6 +131,22 @@ class CanvasSketch {
         this._redrawBackgroundImage();
     }
 
+    /**
+     * Forces a redraw of the current state of the canvases.  This is useful in cases where the
+     * caller needs to redraw on demand
+     */
+    public redrawCurrentState(): void {
+        this._redrawBackgroundImage();
+        this._redrawSketch();
+    }
+
+    /**
+     * Allows the caller to redraw the sketchpad at any point within the provided stack and
+     * point in time within that stack
+     *
+     * @param {CanvasToolSettings[]} objects - The entire stack of drawn objects
+     * @param {number} newCurrentObjectIndex - The point in time / point in stack to draw
+     */
     public redrawSketchAt(objects: CanvasToolSettings[], newCurrentObjectIndex: number): void {
         if (!this._isBrowserSupported) {
             return;
@@ -143,12 +175,17 @@ class CanvasSketch {
         this._redrawSketch();
     }
 
+    /**
+     * Allows the caller to select one of the availalbe tool type
+     *
+     * @param {CanvasToolType} toolType - The tool to be selected
+     */
     public setSelectedTool(toolType: CanvasToolType): void {
         if (!this._isBrowserSupported) {
             return;
         }
 
-        if (this.selectedTool) {
+        if (this.selectedTool != null) {
             this.selectedTool.dispose();
         }
 
@@ -157,11 +194,18 @@ class CanvasSketch {
             return;
         }
         this.selectedTool = selectedTool;
-        if (this.selectedTool) {
+        if (this.selectedTool != null) {
             this.selectedTool.initialize();
         }
     }
 
+    /**
+     * Allows the caller to define the color being used by the tool
+     *
+     * @param {string} color - The color to be selected (NOTE: must be in hex format with hash)
+     * @example
+     * canvasSketch.setToolColor('#5eeb34');
+     */
     public setToolColor(color: string): void {
         if (!this._isBrowserSupported) {
             return;
@@ -170,6 +214,14 @@ class CanvasSketch {
         this._drawToolUiSettings.color = color;
     }
 
+    /**
+     * Allows the caller to define what happens when a tool successfully adds a stroke to the
+     * drawn stack of objects
+     *
+     * @param {(strokeSettings: CanvasDrawToolSettings) => void} onAddedStroke - The function that
+     *  is called when a new drawn object is added to the stack.  Returns the settings of that drawn
+     *  object including things like color, width, and the type of tool used
+     */
     public setOnAddedToolStroke(onAddedStroke: (strokeSettings: CanvasDrawToolSettings) => void): void {
         if (!this._isBrowserSupported) {
             return;
@@ -187,6 +239,13 @@ class CanvasSketch {
         };
     }
 
+    /**
+     * Allows the caller to define the width being used by the tool
+     *
+     * @param {number} width - The width to be seelcted
+     * @example
+     * canvasSketch.setToolWidth(10);
+     */
     public setToolWidth(width: number): void {
         if (!this._isBrowserSupported) {
             return;
@@ -202,18 +261,9 @@ class CanvasSketch {
     // #region Private Methods
     // ---------------------------------------------------------------------------------------------
 
-    private _clearCanvas(canvas: HTMLCanvasElement, context: CanvasRenderingContext2D): void {
-        context.clearRect(0, 0, canvas.width, canvas.height);
-    }
-
-    private _clearSketchCanvas(): void {
-        if (!this._isBrowserSupported) {
-            return;
-        }
-
-        this._clearCanvas(this._config.sketchCanvas, this._sketchContext);
-    }
-
+    /**
+     * Removes the background image from the background image canvas so that it is no longer visible
+     */
     private _clearBackgroundImageCanvas(): void {
         if (!this._isBrowserSupported) {
             return;
@@ -226,6 +276,32 @@ class CanvasSketch {
         this._clearCanvas(this._config.backgroundImageCanvas, this._backgroundImageContext);
     }
 
+    /**
+     * Removes all drawing on the provided canvas and context
+     *
+     * @param {HTMLCanvasElement} canvas - The canvas that will have its drawing removed
+     * @param {CanvasRenderingContext2D} context - The context of the canvas to remove the drawing
+     */
+    private _clearCanvas(canvas: HTMLCanvasElement, context: CanvasRenderingContext2D): void {
+        context.clearRect(0, 0, canvas.width, canvas.height);
+    }
+
+    /**
+     * Removes all drawing from the sketch canvas so that it is no longer visible
+     */
+    private _clearSketchCanvas(): void {
+        if (!this._isBrowserSupported) {
+            return;
+        }
+
+        this._clearCanvas(this._config.sketchCanvas, this._sketchContext);
+    }
+
+    /**
+     * Draws the provided objects onto the sketch canvas
+     *
+     * @param {CanvasToolSettings[]} objectStack - The provided objects to be drawn
+     */
     private _drawObjects(objectStack: CanvasToolSettings[]): void {
         if (!this._isBrowserSupported) {
             return;
@@ -244,6 +320,11 @@ class CanvasSketch {
         this.imageTool.drawImages(images);
     }
 
+    /**
+     * Handler bound to tools drawing so capture the drawn stroke int he canvas sketch stack
+     *
+     * @param {CanvasDrawToolSettings} strokeSettings - The settings of the drawn stroke that was just added
+     */
     private _onAddStroke(strokeSettings: CanvasDrawToolSettings): void {
         // track the changes in it's own stack.. making sure to consider the current object index (history in view currently)
         this._config.objectStack = this._getStackToDraw();
@@ -252,17 +333,29 @@ class CanvasSketch {
         this._config.currentObjectIndex = this._config.currentObjectIndex + 1;
     }
 
+    /**
+     * Returns an immutable stack of drawn strokes to draw at the point / point in time based on the current object index
+     */
     private _getStackToDraw(): CanvasToolSettings[] {
         const stackToDraw = [...this._config.objectStack].slice(0, this._config.currentObjectIndex + 1);
         return stackToDraw;
     }
 
+    /**
+     * Determines if the provided canvas tool is a drawable tool
+     *
+     * @param {CanvasTool} tool - The tool to evaluate
+     */
     private _isInstanceOfDrawTool(tool: CanvasTool): tool is CanvasDrawTool {
         return "color" in tool
             && "width" in tool
             && "drawStrokes" in tool;
     }
 
+    /**
+     * Uses the current canvas instances to establish the sketch and background image contexts and
+     * while determining browser compatability with canvas at the same time
+     */
     private _initializeCanvasContexts(): void {
         if (this._config.sketchCanvas.getContext != null) {
             // browser supports the canvas tag, get the 2d drawing context for this canvas
@@ -295,6 +388,9 @@ class CanvasSketch {
         }
     }
 
+    /**
+     * Uses the current object stack (if provided) to redraw the strokes onto the sketch canvas
+     */
     private _initializeCurrentDrawing(): void {
         if (this._config.objectStack?.length > 0) {
             // default the current stroke based on the initialized stroke stack's last object
@@ -309,9 +405,11 @@ class CanvasSketch {
 
             this._drawObjects(stackToDraw);
         }
-
     }
 
+    /**
+     * Uses the current sketch canvas and context to set up all available tools to the caller
+     */
     private _initializeTools(): void {
         // setup default config settings for all tools
         this._toolConfig = {
@@ -352,6 +450,12 @@ class CanvasSketch {
         }
     }
 
+    /**
+     * Positions the canvases (background image and sketch) to the provided coordinate values
+     *
+     * @param {number} panXDelta - The left pixel number
+     * @param {number} panYDelta - The top pixel number
+     */
     private _panTo(panXDelta: number, panYDelta: number): void {
         const newPanX = this._config.panX + panXDelta;
         const newPanY = this._config.panY + panYDelta;
@@ -367,6 +471,9 @@ class CanvasSketch {
         }
     }
 
+    /**
+     * Clears the sketch canvas and redraws all current stack objects to it
+     */
     private _redrawSketch(): void {
         if (!this._isBrowserSupported) {
             return;
@@ -379,6 +486,9 @@ class CanvasSketch {
         this._drawObjects(stackToDraw);
     }
 
+    /**
+     * Clears the background image canvas and redraws the background image to it
+     */
     private _redrawBackgroundImage(): void {
         if (!this._isBrowserSupported) {
             return;