@alepot55/chessboardjs 2.3.7 → 2.3.8

package/src/services/BoardService.js

@@ -1,5 +1,5 @@
 /**
- * Service for managing board setup and DOM operations
+ * BoardService - Handles board DOM setup, manipulation, and resource management
  * @module services/BoardService
  * @since 2.0.0
  */
@@ -11,45 +11,45 @@ import Square from '../components/Square.js';
 
 /**
  * Service responsible for board DOM manipulation and setup
- * @class
+ * @class BoardService
  */
 export class BoardService {
     /**
-     * Creates a new BoardService instance
-     * @param {ChessboardConfig} config - Board configuration
+     * Create a new BoardService instance
+     * @param {Object} config - Board configuration
      */
     constructor(config) {
+        /** @type {Object} */
         this.config = config;
+        /** @type {HTMLElement|null} */
         this.element = null;
+        /** @type {Object.<string, Square>} */
         this.squares = {};
     }
 
     /**
-     * Builds the board DOM element and attaches it to the configured container
-     * @throws {DOMError} When the container element cannot be found
+     * Build the board DOM element and attach it to the configured container
+     * @throws {DOMError} If the container element cannot be found
      */
     buildBoard() {
-        console.log('BoardService.buildBoard: Looking for element with ID:', this.config.id_div);
-
         this.element = document.getElementById(this.config.id_div);
         if (!this.element) {
             throw new DOMError(ERROR_MESSAGES.invalid_id_div + this.config.id_div, this.config.id_div);
         }
-
         this.resize(this.config.size);
-        this.element.className = "board";
+        this.element.className = 'board';
     }
 
     /**
-     * Creates all 64 squares and adds them to the board
+     * Create all 64 squares and add them to the board
      * @param {Function} coordConverter - Function to convert row/col to real coordinates
      */
     buildSquares(coordConverter) {
+        if (!this.element) throw new DOMError('Board element not initialized', this.config.id_div);
         for (let row = 0; row < BOARD_SIZE.ROWS; row++) {
             for (let col = 0; col < BOARD_SIZE.COLS; col++) {
                 const [squareRow, squareCol] = coordConverter(row, col);
                 const square = new Square(squareRow, squareCol);
-
                 this.squares[square.getId()] = square;
                 this.element.appendChild(square.element);
             }
@@ -57,20 +57,17 @@ export class BoardService {
     }
 
     /**
-     * Removes all squares from the board and cleans up their resources
-     * Best practice: always destroy JS objects and DOM nodes, and clear references.
+     * Remove all squares from the board and clean up their resources
      */
     removeSquares() {
         for (const square of Object.values(this.squares)) {
-            // Always call destroy to remove DOM and clear piece reference
             square.destroy();
         }
         this.squares = {};
     }
 
     /**
-     * Removes all content from the board element
-     * Best practice: clear DOM and force element to be re-fetched on next build.
+     * Remove all content from the board element
      */
     removeBoard() {
         if (this.element) {
@@ -80,9 +77,9 @@ export class BoardService {
     }
 
     /**
-     * Resizes the board to the specified size
+     * Resize the board to the specified size
      * @param {number|string} value - Size in pixels or 'auto'
-     * @throws {ValidationError} When size value is invalid
+     * @throws {ValidationError} If size value is invalid
      */
     resize(value) {
         if (value === 'auto') {
@@ -96,15 +93,13 @@ export class BoardService {
     }
 
     /**
-     * Calculates the optimal size when 'auto' is specified
+     * Calculate the optimal size when 'auto' is specified
      * @private
      * @returns {number} Calculated size in pixels
      */
     _calculateAutoSize() {
-        if (!this.element) return 400; // Default fallback
-
+        if (!this.element) return 400;
         const { offsetWidth, offsetHeight } = this.element;
-
         if (offsetWidth === 0) {
             return offsetHeight || 400;
         } else if (offsetHeight === 0) {
@@ -115,8 +110,8 @@ export class BoardService {
     }
 
     /**
-     * Gets a square by its ID
-     * @param {string} squareId - Square identifier (API pubblica)
+     * Get a square by its ID
+     * @param {string} squareId - Square identifier
      * @returns {Square|null} The square or null if not found
      */
     getSquare(squareId) {
@@ -124,26 +119,37 @@ export class BoardService {
     }
 
     /**
-     * Highlight a square (solo oggetto)
+     * Highlight a square
      * @param {Square} square
      * @param {Object} [opts]
      */
     highlightSquare(square, opts = {}) {
-        if (!square) throw new Error('highlightSquare richiede oggetto Square');
-        // ... logica esistente ...
+        if (!square) throw new Error('highlightSquare requires a Square object');
+        // Implement highlight logic or call square.highlight() if available
+        if (typeof square.highlight === 'function') {
+            square.highlight(opts);
+        } else {
+            square.element.classList.add('highlighted');
+        }
     }
+
     /**
-     * Dehighlight a square (solo oggetto)
+     * Remove highlight from a square
      * @param {Square} square
      * @param {Object} [opts]
      */
     dehighlightSquare(square, opts = {}) {
-        if (!square) throw new Error('dehighlightSquare richiede oggetto Square');
-        // ... logica esistente ...
+        if (!square) throw new Error('dehighlightSquare requires a Square object');
+        // Implement dehighlight logic or call square.dehighlight() if available
+        if (typeof square.dehighlight === 'function') {
+            square.dehighlight(opts);
+        } else {
+            square.element.classList.remove('highlighted');
+        }
     }
 
     /**
-     * Gets all squares
+     * Get all squares
      * @returns {Object.<string, Square>} All squares indexed by ID
      */
     getAllSquares() {
@@ -151,7 +157,7 @@ export class BoardService {
     }
 
     /**
-     * Applies a method to all squares
+     * Apply a method to all squares
      * @param {string} methodName - Name of the method to call on each square
      * @param {...*} args - Arguments to pass to the method
      */
@@ -164,7 +170,7 @@ export class BoardService {
     }
 
     /**
-     * Cleans up all resources
+     * Clean up all resources
      */
     destroy() {
         this.removeSquares();

package/src/services/CoordinateService.js

@@ -1,5 +1,5 @@
 /**
- * Service for managing coordinate conversions and board orientation
+ * CoordinateService - Handles coordinate conversions and board orientation logic
  * @module services/CoordinateService
  * @since 2.0.0
  */
@@ -10,19 +10,20 @@ import { ERROR_MESSAGES } from '../errors/messages.js';
 
 /**
  * Service responsible for coordinate conversions and board orientation
- * @class
+ * @class CoordinateService
  */
 export class CoordinateService {
     /**
-     * Creates a new CoordinateService instance
-     * @param {ChessboardConfig} config - Board configuration
+     * Create a new CoordinateService instance
+     * @param {Object} config - Board configuration
      */
     constructor(config) {
+        /** @type {Object} */
         this.config = config;
     }
 
     /**
-     * Converts logical coordinates to real coordinates based on board orientation
+     * Convert logical coordinates to real coordinates based on board orientation
      * @param {number} row - Row index (0-7)
      * @param {number} col - Column index (0-7)
      * @returns {Array<number>} Real coordinates [row, col] (1-8)
@@ -30,18 +31,16 @@ export class CoordinateService {
     realCoord(row, col) {
         let realRow = row;
         let realCol = col;
-        
         if (this.isWhiteOriented()) {
             realRow = 7 - row;
         } else {
             realCol = 7 - col;
         }
-        
         return [realRow + 1, realCol + 1];
     }
 
     /**
-     * Converts board coordinates to square ID
+     * Convert board coordinates to square ID
      * @param {number} row - Row index (0-7)
      * @param {number} col - Column index (0-7)
      * @returns {string} Square ID (e.g., 'e4')
@@ -49,7 +48,6 @@ export class CoordinateService {
     getSquareID(row, col) {
         row = parseInt(row);
         col = parseInt(col);
-        
         if (this.isWhiteOriented()) {
             row = 8 - row;
             col = col + 1;
@@ -57,7 +55,6 @@ export class CoordinateService {
             row = row + 1;
             col = 8 - col;
         }
-        
         if (col < 1 || col > 8 || row < 1 || row > 8) {
             throw new ValidationError(
                 `Invalid board coordinates: row=${row}, col=${col}`,
@@ -65,13 +62,12 @@ export class CoordinateService {
                 { row, col }
             );
         }
-        
         const letter = BOARD_LETTERS[col - 1];
         return letter + row;
     }
 
     /**
-     * Converts square ID to board coordinates
+     * Convert square ID to board coordinates
      * @param {string} squareId - Square ID (e.g., 'e4')
      * @returns {Array<number>} Board coordinates [row, col] (0-7)
      */
@@ -83,10 +79,8 @@ export class CoordinateService {
                 squareId
             );
         }
-        
         const letter = squareId[0];
         const number = parseInt(squareId[1]);
-        
         const col = BOARD_LETTERS.indexOf(letter);
         if (col === -1) {
             throw new ValidationError(
@@ -95,7 +89,6 @@ export class CoordinateService {
                 squareId
             );
         }
-        
         if (number < 1 || number > 8) {
             throw new ValidationError(
                 ERROR_MESSAGES.invalid_square + squareId,
@@ -103,9 +96,7 @@ export class CoordinateService {
                 squareId
             );
         }
-        
         let row, boardCol;
-        
         if (this.isWhiteOriented()) {
             row = 8 - number;
             boardCol = col;
@@ -113,12 +104,11 @@ export class CoordinateService {
             row = number - 1;
             boardCol = 7 - col;
         }
-        
         return [row, boardCol];
     }
 
     /**
-     * Converts pixel coordinates to square ID
+     * Convert pixel coordinates to square ID
      * @param {number} x - X coordinate in pixels
      * @param {number} y - Y coordinate in pixels
      * @param {HTMLElement} boardElement - Board DOM element
@@ -126,21 +116,15 @@ export class CoordinateService {
      */
     pixelToSquareID(x, y, boardElement) {
         if (!boardElement) return null;
-        
         const rect = boardElement.getBoundingClientRect();
         const { width, height } = rect;
-        
-        // Check if coordinates are within board bounds
         if (x < 0 || x >= width || y < 0 || y >= height) {
             return null;
         }
-        
         const squareWidth = width / 8;
         const squareHeight = height / 8;
-        
         const col = Math.floor(x / squareWidth);
         const row = Math.floor(y / squareHeight);
-        
         try {
             return this.getSquareID(row, col);
         } catch (error) {
@@ -149,25 +133,21 @@ export class CoordinateService {
     }
 
     /**
-     * Converts square ID to pixel coordinates
+     * Convert square ID to pixel coordinates
      * @param {string} squareId - Square ID (e.g., 'e4')
      * @param {HTMLElement} boardElement - Board DOM element
      * @returns {Object|null} Pixel coordinates {x, y} or null if invalid
      */
     squareIDToPixel(squareId, boardElement) {
         if (!boardElement) return null;
-        
         try {
             const [row, col] = this.getCoordinatesFromSquareID(squareId);
             const rect = boardElement.getBoundingClientRect();
             const { width, height } = rect;
-            
             const squareWidth = width / 8;
             const squareHeight = height / 8;
-            
             const x = col * squareWidth;
             const y = row * squareHeight;
-            
             return { x, y };
         } catch (error) {
             return null;
@@ -175,7 +155,7 @@ export class CoordinateService {
     }
 
     /**
-     * Gets the center pixel coordinates of a square
+     * Get the center pixel coordinates of a square
      * @param {string} squareId - Square ID (e.g., 'e4')
      * @param {HTMLElement} boardElement - Board DOM element
      * @returns {Object|null} Center coordinates {x, y} or null if invalid
@@ -183,11 +163,9 @@ export class CoordinateService {
     getSquareCenter(squareId, boardElement) {
         const coords = this.squareIDToPixel(squareId, boardElement);
         if (!coords) return null;
-        
         const rect = boardElement.getBoundingClientRect();
         const squareWidth = rect.width / 8;
         const squareHeight = rect.height / 8;
-        
         return {
             x: coords.x + squareWidth / 2,
             y: coords.y + squareHeight / 2
@@ -195,7 +173,7 @@ export class CoordinateService {
     }
 
     /**
-     * Calculates the distance between two squares
+     * Calculate the distance between two squares
      * @param {string} fromSquare - Source square ID
      * @param {string} toSquare - Target square ID
      * @returns {number} Distance between squares
@@ -204,10 +182,8 @@ export class CoordinateService {
         try {
             const [fromRow, fromCol] = this.getCoordinatesFromSquareID(fromSquare);
             const [toRow, toCol] = this.getCoordinatesFromSquareID(toSquare);
-            
             const rowDiff = Math.abs(toRow - fromRow);
             const colDiff = Math.abs(toCol - fromCol);
-            
             return Math.sqrt(rowDiff * rowDiff + colDiff * colDiff);
         } catch (error) {
             return 0;
@@ -215,7 +191,7 @@ export class CoordinateService {
     }
 
     /**
-     * Checks if the board is oriented from white's perspective
+     * Check if the board is oriented from white's perspective
      * @returns {boolean} True if white-oriented
      */
     isWhiteOriented() {
@@ -223,7 +199,7 @@ export class CoordinateService {
     }
 
     /**
-     * Checks if the board is oriented from black's perspective
+     * Check if the board is oriented from black's perspective
      * @returns {boolean} True if black-oriented
      */
     isBlackOriented() {
@@ -231,31 +207,31 @@ export class CoordinateService {
     }
 
     /**
-     * Flips the board orientation
+     * Flip the board orientation
      */
     flipOrientation() {
         this.config.orientation = this.isWhiteOriented() ? 'b' : 'w';
     }
 
     /**
-     * Sets the board orientation
-     * @param {string} orientation - 'w' for white, 'b' for black
-     * @throws {ValidationError} When orientation is invalid
+     * Set the board orientation
+     * @param {string} orientation - 'w', 'b', 'white', or 'black'
+     * @throws {ValidationError} If orientation is invalid
      */
     setOrientation(orientation) {
-        if (orientation !== 'w' && orientation !== 'b') {
+        const normalized = orientation === 'white' ? 'w' : orientation === 'black' ? 'b' : orientation;
+        if (normalized !== 'w' && normalized !== 'b') {
             throw new ValidationError(
                 ERROR_MESSAGES.invalid_orientation + orientation,
                 'orientation',
                 orientation
             );
         }
-        
-        this.config.orientation = orientation;
+        this.config.orientation = normalized;
     }
 
     /**
-     * Gets the current orientation
+     * Get the current orientation
      * @returns {string} Current orientation ('w' or 'b')
      */
     getOrientation() {
@@ -263,50 +239,21 @@ export class CoordinateService {
     }
 
     /**
-     * Sets the orientation
-     * @param {string} orientation - New orientation ('w', 'b', 'white', 'black')
-     */
-    setOrientation(orientation) {
-        // Normalize orientation
-        const normalizedOrientation = orientation === 'white' ? 'w' : 
-                                     orientation === 'black' ? 'b' : orientation;
-        
-        if (normalizedOrientation !== 'w' && normalizedOrientation !== 'b') {
-            throw new ValidationError(
-                ERROR_MESSAGES.invalid_orientation + orientation,
-                'orientation',
-                orientation
-            );
-        }
-        
-        this.config.orientation = normalizedOrientation;
-    }
-
-    /**
-     * Flips the board orientation
-     */
-    flipOrientation() {
-        this.config.orientation = this.isWhiteOriented() ? 'b' : 'w';
-    }
-
-    /**
-     * Gets all square IDs in order
+     * Get all square IDs in order
      * @returns {Array<string>} Array of all square IDs
      */
     getAllSquareIDs() {
         const squares = [];
-        
         for (let row = 0; row < 8; row++) {
             for (let col = 0; col < 8; col++) {
                 squares.push(this.getSquareID(row, col));
             }
         }
-        
         return squares;
     }
 
     /**
-     * Gets squares in a specific rank (row)
+     * Get all squares in a specific rank (row)
      * @param {number} rank - Rank number (1-8)
      * @returns {Array<string>} Array of square IDs in the rank
      */
@@ -318,19 +265,16 @@ export class CoordinateService {
                 rank
             );
         }
-        
         const squares = [];
-        
         for (let col = 0; col < 8; col++) {
             const row = this.isWhiteOriented() ? 8 - rank : rank - 1;
             squares.push(this.getSquareID(row, col));
         }
-        
         return squares;
     }
 
     /**
-     * Gets squares in a specific file (column)
+     * Get all squares in a specific file (column)
      * @param {string} file - File letter (a-h)
      * @returns {Array<string>} Array of square IDs in the file
      */
@@ -343,13 +287,10 @@ export class CoordinateService {
                 file
             );
         }
-        
         const squares = [];
-        
         for (let row = 0; row < 8; row++) {
             squares.push(this.getSquareID(row, col));
         }
-        
         return squares;
     }
 }