From 54a60d4a5a9f940e18cccab7032dba07363ca39d Mon Sep 17 00:00:00 2001
From: Stixx <stixx@nostrdev.com>
Date: Fri, 12 Jul 2024 15:07:36 +0200
Subject: [PATCH] chore: added comments

---
 src/components/DrawPDFFields/index.tsx | 73 ++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/src/components/DrawPDFFields/index.tsx b/src/components/DrawPDFFields/index.tsx
index 565f43a..c23bf70 100644
--- a/src/components/DrawPDFFields/index.tsx
+++ b/src/components/DrawPDFFields/index.tsx
@@ -94,6 +94,14 @@ export const DrawPDFFields = (props: Props) => {
     setPdfFiles([...pdfFiles])
   }
 
+  /**
+   * Fired only when left click and mouse over pdf page
+   * Creates new drawnElement and pushes in the array
+   * It is re rendered and visible right away
+   * 
+   * @param event Mouse event
+   * @param page PdfPage where press happened
+   */
   const onMouseDown = (event: any, page: PdfPage) => {
     // Proceed only if left click
     if (event.button !== 0) return
@@ -126,6 +134,10 @@ export const DrawPDFFields = (props: Props) => {
     })
   }
 
+  /**
+   * Drawing is finished, resets all the variables used to draw
+   * @param event Mouse event
+   */
   const onMouseUp = (event: MouseEvent) => {
     setMouseState((prev) => {
       return {
@@ -137,6 +149,12 @@ export const DrawPDFFields = (props: Props) => {
     })
   }
 
+  /**
+   * After {@link onMouseDown} create an drawing element, this function gets called on every pixel moved
+   * which alters the newly created drawing element, resizing it while mouse move
+   * @param event Mouse event
+   * @param page PdfPage where moving is happening
+   */
   const onMouseMove = (event: any, page: PdfPage) => {
     if (mouseState.clicked && selectedTool) {
       const lastElementIndex = page.drawnFields.length -1
@@ -158,6 +176,16 @@ export const DrawPDFFields = (props: Props) => {
     }
   } 
 
+  /**
+   * Fired when event happens on the drawn element which will be moved
+   * mouse coordinates relative to drawn element will be stored
+   * so when we start moving, offset can be calculated
+   * mouseX - offsetX
+   * mouseY - offsetY
+   * 
+   * @param event Mouse event
+   * @param drawnField Which we are moving
+   */
   const onDrawnFieldMouseDown = (event: any, drawnField: DrawnField) => {
     event.stopPropagation()
     
@@ -176,6 +204,11 @@ export const DrawPDFFields = (props: Props) => {
     })
   }
 
+  /**
+   * Moves the drawnElement by the mouse position (mouse can grab anywhere on the drawn element)
+   * @param event Mouse event
+   * @param drawnField which we are moving
+   */
   const onDranwFieldMouseMove = (event: any, drawnField: DrawnField) => {
     if (mouseState.dragging) {
       const { mouseX, mouseY, rect } = getMouseCoordinates(event, event.target.parentNode)
@@ -201,6 +234,11 @@ export const DrawPDFFields = (props: Props) => {
     }
   }
 
+  /**
+   * Fired when clicked on the resize handle, sets the state for a resize action
+   * @param event Mouse event
+   * @param drawnField which we are resizing
+   */
   const onResizeHandleMouseDown = (event: any, drawnField: DrawnField) => {
     // Proceed only if left click
     if (event.button !== 0) return
@@ -212,6 +250,11 @@ export const DrawPDFFields = (props: Props) => {
     })
   }
 
+  /**
+   * Resizes the drawn element by the mouse position
+   * @param event Mouse event
+   * @param drawnField which we are resizing
+   */
   const onResizeHandleMouseMove = (event: any, drawnField: DrawnField) => {
     if (mouseState.resizing) {
       const { mouseX, mouseY } = getMouseCoordinates(event, event.target.parentNode.parentNode)
@@ -226,12 +269,24 @@ export const DrawPDFFields = (props: Props) => {
     }
   }
 
+  /**
+   * Removes the drawn element using the indexes in the params
+   * @param event Mouse event
+   * @param pdfFileIndex pdf file index
+   * @param pdfPageIndex pdf page index
+   * @param drawnFileIndex drawn file index
+   */
   const onRemoveHandleMouseDown = (event: any, pdfFileIndex: number, pdfPageIndex: number, drawnFileIndex: number) => {
     event.stopPropagation()
     
     pdfFiles[pdfFileIndex].pages[pdfPageIndex].drawnFields.splice(drawnFileIndex, 1)
   }
 
+  /**
+   * Used to stop mouse click propagating to the parent elements
+   * so select can work properly
+   * @param event Mouse event
+   */
   const onUserSelectHandleMouseDown = (event: any) => {
     event.stopPropagation()
   }
@@ -255,6 +310,10 @@ export const DrawPDFFields = (props: Props) => {
     }
   }
 
+  /**
+   * Reads the pdf binary files and converts it's pages to images
+   * creates the pdfFiles object and sets to a state
+   */
   const parsePdfPages = async () => {
     const pdfFiles: PdfFile[] = []
 
@@ -301,6 +360,9 @@ export const DrawPDFFields = (props: Props) => {
     }))
   }
   
+  /**
+   * Reads the pdf file binaries 
+   */
   const readPdf = (file: File) => {
     return new Promise((resolve, reject) => {
       const reader = new FileReader();
@@ -320,6 +382,10 @@ export const DrawPDFFields = (props: Props) => {
     })
   }
 
+  /**
+   * 
+   * @returns if expanded pdf accordion is present
+   */
   const hasExpandedPdf = () => {
     return !!pdfFiles.filter(pdfFile => !!pdfFile.expanded).length
   }
@@ -331,6 +397,10 @@ export const DrawPDFFields = (props: Props) => {
     setShowDrawToolBox(hasExpandedPdf())
   }
 
+  /**
+   * Changes the drawing tool
+   * @param drawTool to draw with
+   */
   const handleToolSelect = (drawTool: DrawTool) => {
     // If clicked on the same tool, unselect
     if (drawTool.identifier === selectedTool?.identifier) {
@@ -341,6 +411,9 @@ export const DrawPDFFields = (props: Props) => {
     setSelectedTool(drawTool)
   }
 
+  /**
+   * Renders the pdf pages and drawing elements
+   */
   const getPdfPages = (pdfFile: PdfFile, pdfFileIndex: number) => {
     return (
       <Box sx={{