refactor: Clean up Editor class, add docblocks and type hints.

Author: splitbrain

src/Editor.js

@@ -3,12 +3,26 @@ import 'ace-builds/src-noconflict/mode-yaml';
 import 'ace-builds/src-noconflict/theme-github';
 import Yaml from 'yaml';
 import {Builder} from "./Builder.js";
-import {ImageEmbed} from "./ImageEmbed.js";
+import { ImageEmbed } from "./ImageEmbed.js";
 
+/**
+ * Manages the Ace editor instance, handles YAML parsing,
+ * updates the SVG preview, and manages content loading/saving.
+ */
 export class Editor {
-
+    /** @type {string} The key used for storing YAML content in localStorage. */
     STORAGE_KEY = 'pcb-diagram-yaml';
 
+    /** @type {ace.Ace.Editor} The Ace editor instance. */
+    ace;
+    /** @type {HTMLElement} The HTML element where the SVG output is rendered. */
+    output;
+
+    /**
+     * Creates an Editor instance.
+     * @param {string|HTMLElement} editor - The ID or HTML element for the Ace editor container.
+     * @param {HTMLElement} output - The HTML element to render the SVG output into.
+     */
     constructor(editor, output) {
         this.output = output;
 
@@ -27,25 +41,30 @@ export class Editor {
             tabSize: 2
         });
 
-        // Defer content loading and event binding
         this.initializeEditor();
-
-        // register download handler
         this.output.addEventListener('click', this.onDownloadClick);
     }
 
+    /**
+     * Asynchronously initializes the editor by loading content
+     * and setting up event listeners.
+     * @private
+     */
     async initializeEditor() {
-        // Load content first
         await this.loadInitialContent();
 
-        // Then register change handler and trigger initial processing
         this.ace.session.on('change', this.debounce(this.onChange.bind(this), 300));
-        // Check if editor has content before triggering initial processing
         if (this.ace.getValue()) {
-             this.onChange(); // Trigger initial processing only if content loaded
+            this.onChange(); // Trigger initial processing only if content loaded
         }
     }
 
+    /**
+     * Loads the initial content into the editor.
+     * It prioritizes loading from a 'load' URL parameter,
+     * falling back to localStorage if the parameter is not present.
+     * @private
+     */
     async loadInitialContent() {
         const urlParams = new URLSearchParams(window.location.search);
         const loadUrl = urlParams.get('load');
@@ -60,27 +79,33 @@ export class Editor {
                 this.ace.setValue(yamlContent, -1); // -1 moves cursor to the start
                 console.log(`Loaded content from: ${loadUrl}`);
 
-                // Remove the 'load' parameter from the URL without reloading
                 const currentUrlParams = new URLSearchParams(window.location.search);
                 currentUrlParams.delete('load');
                 const newRelativePathQuery = window.location.pathname + (currentUrlParams.toString() ? '?' + currentUrlParams.toString() : '');
                 window.history.replaceState({ path: newRelativePathQuery }, '', newRelativePathQuery);
             } catch (error) {
                 console.error('Failed to load content from URL:', loadUrl, error);
-                // Display error to the user in the output div and editor
                 const errorMessage = `# Failed to load content from: ${loadUrl}\n# Error: ${error.message}`;
                 this.output.innerHTML = `<div class="error">Failed to load content from <a href="${loadUrl}" target="_blank">${loadUrl}</a>: ${error.message}</div>`;
                 this.ace.setValue(errorMessage, -1);
             }
         } else {
-            // Load initial content from localStorage if no loadUrl
             const savedYaml = localStorage.getItem(this.STORAGE_KEY);
             if (savedYaml) {
                 this.ace.setValue(savedYaml, -1);
             }
         }
     }
 
+    /**
+     * Creates a debounced version of a function that delays invoking the function
+     * until after `wait` milliseconds have elapsed since the last time the
+     * debounced function was invoked.
+     * @param {Function} func The function to debounce.
+     * @param {number} wait The number of milliseconds to delay.
+     * @returns {Function} The debounced function.
+     * @private
+     */
     debounce(func, wait) {
         let timeout;
         return function (...args) {
@@ -89,21 +114,25 @@ export class Editor {
         };
     }
 
+    /**
+     * Handles the 'change' event from the Ace editor.
+     * Parses the YAML content, saves valid content to localStorage,
+     * triggers the SVG update, and displays parsing errors.
+     * @private
+     */
     onChange() {
         const yaml = this.ace.getValue();
         try {
             const parsed = Yaml.parse(yaml, {
                 prettyErrors: true,
             });
-            // Save valid YAML to localStorage
             localStorage.setItem(this.STORAGE_KEY, yaml);
             this.onUpdate(parsed);
             this.clearErrors();
         } catch (e) {
-            // Don't save invalid YAML
             if (e.linePos) {
                 this.showError(
-                    e.linePos[0].line - 1,
+                    e.linePos[0].line - 1, // Ace lines are 0-indexed
                     e.linePos[0].col - 1,
                     e.message,
                     e.name === 'YAMLWarning' ? 'error' : 'warning'
@@ -114,8 +143,15 @@ export class Editor {
         }
     }
 
+    /**
+     * Called when the YAML content is successfully parsed.
+     * Embeds images, builds the front and back SVG representations,
+     * and updates the output element.
+     * @param {object} setup - The parsed YAML configuration object.
+     * @private
+     */
     async onUpdate(setup) {
-        const embed = new ImageEmbed('pinouts');
+        const embed = new ImageEmbed('pinouts'); // Assuming 'pinouts' is the base path for local images
         setup = await embed.embedImages(setup);
 
         const builder = new Builder(setup);
@@ -129,8 +165,15 @@ export class Editor {
         this.output.appendChild(back);
     }
 
+    /**
+     * Handles click events on the output area to trigger SVG download.
+     * @param {MouseEvent} e - The click event object.
+     * @private
+     */
     onDownloadClick(e) {
         const svg = e.target.closest('svg');
+        if (!svg) return; // Click was not on an SVG or its child
+
         const serializer = new XMLSerializer();
         const source = serializer.serializeToString(svg);
         const blob = new Blob([source], { type: 'image/svg+xml;charset=utf-8' });
@@ -146,9 +189,15 @@ export class Editor {
         URL.revokeObjectURL(url);
     }
 
+    /**
+     * Displays an error or warning annotation in the Ace editor gutter.
+     * @param {number} lineNumber - The 0-indexed line number for the annotation.
+     * @param {number} column - The 0-indexed column number for the annotation.
+     * @param {string} message - The error or warning message text.
+     * @param {boolean} isWarning - True if the annotation is a warning, false for an error.
+     * @private
+     */
     showError(lineNumber, column, message, isWarning) {
-        console.error('ace', lineNumber, column, message);
-
         this.ace.session.setAnnotations([{
             row: lineNumber,
             column: column,
@@ -157,6 +206,10 @@ export class Editor {
         }]);
     }
 
+    /**
+     * Clears all annotations (errors and warnings) from the Ace editor.
+     * @private
+     */
     clearErrors() {
         this.ace.session.clearAnnotations();
     }