lightning-base-components 1.14.3-alpha → 1.15.1-alpha

package/src/lightning/datatable/autoWidthStrategy.js

@@ -7,29 +7,71 @@ import { clamp } from './utils';
 const MIN_MAX_THRESHOLD = 0.5;
 const TRUNCATION_ALLOWANCE = 20;
 
+/**
+ * Determines if a column exists at a specified index
+ *
+ * @param {Array} columns An array of columns
+ * @param {Integer} colIndex The column index to locate
+ * @returns {Boolean} Whether the column exists at the specified index
+ */
 function hasColumn(columns, colIndex) {
     return columns.some((current) => current === colIndex);
 }
 
+/**
+ * Calculates the total width of all columns
+ *
+ * @param {Array} columnWidths An array of column widths
+ * @returns {Number} The total width of all columns
+ */
 function getTotalColumnWidth(columnWidths) {
     return columnWidths.reduce((acc, value) => acc + value, 0);
 }
 
+/**
+ * Determines whether or not a specified width can be removed from a column
+ *
+ * @param {Number} currentWidth The current width of the column in pixels
+ * @param {Number} widthToRemove The proposed amount of width to remove in pixels
+ * @param {Number} minColumnWidth The minimum width the column can be in pixels
+ * @returns {Boolean} Whether or not the specified width can be removed
+ */
 function canRemoveWidth(currentWidth, widthToRemove, minColumnWidth) {
     return currentWidth - widthToRemove >= minColumnWidth;
 }
 
+/**
+ * Determines whether or not a specified width can be added to a column
+ *
+ * @param {Number} currentWidth The current width of the column in pixels
+ * @param {Number} widthToAdd The proposed amount of width to add in pixels
+ * @param {Number} maxColumnWidth The maximum width the column can be in pixels
+ * @returns {Boolean} Whether or not the specified width can be added
+ */
 function canAddWidth(currentWidth, widthToAdd, maxColumnWidth) {
     return currentWidth + widthToAdd <= maxColumnWidth;
 }
 
+/**
+ * Determines the expected table width
+ *
+ * @param {Number} availableWidth The available width for the entire table
+ * @param {Object} widthsMetadata The widths metadata object
+ * @returns {Number} The expected width of the table
+ */
 function getExpectedTableWidth(availableWidth, widthsMetadata) {
     const minExpectedTableWidth = getMinExpectedTableWidth(widthsMetadata);
-    return hasNoFlexibleColumns(widthsMetadata)
+    return widthsMetadata.totalFlexibleColumns === 0
         ? minExpectedTableWidth
         : Math.max(minExpectedTableWidth, availableWidth);
 }
 
+/**
+ * Determines the minimum expected table width
+ *
+ * @param {Object} widthsMetadata The widths metadata object
+ * @returns {Number} The minimum expected table width
+ */
 function getMinExpectedTableWidth(widthsMetadata) {
     const {
         totalFixedWidth,
@@ -41,23 +83,27 @@ function getMinExpectedTableWidth(widthsMetadata) {
     return minTotalFlexibleWidth + totalFixedWidth + totalResizedWidth;
 }
 
-function hasNoFlexibleColumns(widthsMetadata) {
-    return widthsMetadata.totalFlexibleColumns === 0;
-}
-
+/**
+ * Strategy for columns that automatically determine their widths.
+ */
 export class AutoWidthStrategy {
+    // Private variables
+
     // Instance array to hold column width ratios either calculated from visual distribution of column labels
-    // or from distribution of data amongst the columns
-    // These ratios are reused except when datatable reacts to changes in data or columns and other variables
-    // at which point they are recalculated
+    // or from distribution of data amongst the columns. These ratios are reused except when datatable reacts
+    // to changes in data or columns and other variablesat which point they are recalculated.
     _columnWidthRatios = [];
-    // Object used to store minColumnWidth, maxColumnWidth along with other metadata like totalFixedColumns
-    // refer widthManagerShared getTotalWidthsMetadata
+
+    // Object used to store `minColumnWidth`, `maxColumnWidth`, along with other metadata like `totalFixedColumns`
+    // Refer: widthManagerShared.js getTotalWidthsMetadata
     _columnWidthMetaData = {};
+
     // Object which holds columns with min width (+ threshold) and columns with max width (-threshold)
     // It is used in redistribution of extra space that is left or taken up while calculating auto widths
     _columnWidthsDistribution = {};
 
+    /************************** LIFECYCLE HOOKS **************************/
+
     constructor(minColumnWidth, maxColumnWidth, wrapTextMaxLines = 3) {
         this._columnWidthMetaData = {
             minColumnWidth,
@@ -68,36 +114,69 @@ export class AutoWidthStrategy {
         this.columnWidthsDistribution.colsWithMaxWidth = [];
     }
 
+    /************************** PRIVATE SETTERS **************************/
+
+    /**
+     * Sets the minimum column width
+     *
+     * @param {Number} value The minimum column width in pixels
+     */
     set minColumnWidth(value) {
         this._columnWidthMetaData.minColumnWidth = value;
     }
 
+    /**
+     * Sets the maximum column width
+     *
+     * @param {Number} value The maximum column width in pixels
+     */
     set maxColumnWidth(value) {
         this._columnWidthMetaData.maxColumnWidth = value;
     }
 
+    /**
+     * Sets the maximum number of lines text can wrap on to
+     *
+     * @param {Number} value The maximum number of lines
+     */
     set wrapTextMaxLines(value) {
         this._columnWidthMetaData.wrapTextMaxLines = value;
     }
 
+    /************************** PRIVATE GETTERS **************************/
+
+    /**
+     * Gets the column width ratios
+     * See `_columnWidthRatios` in Private Variables for more information.
+     *
+     * @returns {Array} An array of column width ratios
+     */
     get columnWidthRatios() {
         return this._columnWidthRatios;
     }
 
+    /**
+     * Gets the column width distribution.
+     * See `_columnWidthsDistribution` in Private Variables for more information.
+     *
+     * @returns {Object} An object of column width distributions
+     */
     get columnWidthsDistribution() {
         return this._columnWidthsDistribution;
     }
 
+    /************************* HELPER FUNCTIONS **************************/
+
     /**
      * Get adjusted column widths from existing ratios which are based on data cells room taken
-     * or based on column labels space in headers
-     * If recomputeAutoWidthRatios is true or ratios are empty, new ratios are calculated
-     * Widths are distributed as per defined widths or as per ratio
-     * Any remaining space or extra space taken is then redistributed in second pass
-     * @param datatableInterface - interface to datatable with callbacks giving width information
-     * @param columnDefs - column definitions array with defined widths and other attributes
-     * @param recomputeAutoWidthRatios - boolean indicating if ratios should be recalculated
-     * @returns {object} with columnWidths: [], expectedTableWidth: (number)
+     * or based on column labels space in headers. If `recomputeAutoWidthRatios` is true or ratios
+     * are empty, new ratios are calculated. Widths are distributed as per defined widths or as per
+     * ratio. Any remaining space or extra space taken is then redistributed in second pass.
+     *
+     * @param {Object} datatableInterface Interface to datatable with callbacks giving width information
+     * @param {Object} columnDefs Column definitions array with defined widths and other attributes
+     * @param {Boolean} recomputeAutoWidthRatios Whether ratios should be recalculated
+     * @returns {Object} columnWidths: [], expectedTableWidth: (number)
      */
     getAdjustedColumnWidths(
         datatableInterface,
@@ -128,7 +207,7 @@ export class AutoWidthStrategy {
         }
 
         let columnWidths = [];
-        // if the lengths dont match return
+        // If the lengths don't match, return
         if (
             recomputeAutoWidthRatios &&
             this.columnWidthRatios.length !== columnDefs.length
@@ -136,8 +215,7 @@ export class AutoWidthStrategy {
             return { expectedTableWidth, columnWidths };
         }
 
-        // first pass - do distribute widths as per ratios or
-        // defined widths if there are any
+        // First pass - Distribute widths as per ratios or defined widths if there are any
         columnWidths = this._distributeWidthFromRatios(
             expectedTableWidth,
             columnDefs,
@@ -146,20 +224,20 @@ export class AutoWidthStrategy {
 
         let columnWidthsSum = getTotalColumnWidth(columnWidths);
 
-        // second pass - there could be excess width remaining due to clamping to maxWidth
-        // or we might have used more space due to clamping to minWidth in certain cases
-        // this could be more prominent in autoWidthStrategy than in fixedWidthStrategy
-        // that columns get extreme widths i.e min or max
-        // we need to redistribute this space using below methods
+        // Second pass - There could be excess width remaining due to clamping to `maxWidth`
+        // or we might have used more space due to clamping to `minWidth `in certain cases.
+        // This could be more prominent in `autoWidthStrategy` than in `fixedWidthStrategy`
+        // that columns get extreme widths (i.e `min` or `max`).
+        // We need to redistribute this space using below methods.
         if (expectedTableWidth > columnWidthsSum) {
-            // we have more space lets redistribute space
+            // We have more space, let's redistribute space
             this._redistributeExtraWidth(
                 expectedTableWidth,
                 columnWidths,
                 columnDefs
             );
         } else if (expectedTableWidth < columnWidthsSum) {
-            // we have to take away used space
+            // We have to take away used space
             this._redistributeDeficitWidth(
                 expectedTableWidth,
                 columnWidths,
@@ -169,18 +247,34 @@ export class AutoWidthStrategy {
         return { columnWidths, expectedTableWidth };
     }
 
+    /**
+     * @private
+     * Calculates the ratios for each cell based on available space for a given row.
+     *
+     * @param {Array} cellWidths An array of the cell widths
+     * @param {Number} totalWidth The total available width
+     * @returns {Array} An array of cell width ratios
+     */
     _getRatios(cellWidths, totalWidth) {
         return cellWidths.map((cellWidth) => {
             return (100 * cellWidth) / totalWidth;
         });
     }
 
+    /**
+     * @private
+     * Calculates and sets the column width ratios object.
+     *
+     * @param {Object} datatableInterface The datatable
+     * @param {Array} columnDefs The column definitions
+     * @param {Object} widthsMetadata The widths metadata object
+     */
     _calculateColumnWidthRatios(
         datatableInterface,
         columnDefs,
         widthsMetadata
     ) {
-        // take into account columns with text wrapping
+        // Take into account columns with text wrapping
         const dataCellWidths = datatableInterface
             .getDataCellWidths()
             .map((width, index) => {
@@ -201,13 +295,22 @@ export class AutoWidthStrategy {
         );
     }
 
+    /**
+     * @private
+     * Calculates and creates the column width ratios array.
+     *
+     * @param {Number} tableScrollWidth The width of the table that is hidden behind a hotizontal scroll
+     * @param {Array} dataCellWidths An array of the widths of the data cells
+     * @param {Array} headerCellWidths An array of the widths of the header cells
+     * @param {Object} widthsMetadata The raw widths metadata object
+     */
     _setColumnWidthRatios(
         tableScrollWidth,
         dataCellWidths,
         headerCellWidths,
         widthsMetadata
     ) {
-        // reset ratios
+        // Reset ratios
         this._columnWidthRatios = [];
 
         if (tableScrollWidth > 0) {
@@ -225,7 +328,7 @@ export class AutoWidthStrategy {
 
                     const totalFlexibleWidth =
                         totalHeaderWidth - totalFixedWidth - totalResizedWidth;
-                    // calculate ratio from header cells
+                    // Calculate ratio from header cells
                     this._columnWidthRatios = this._getRatios(
                         headerCellWidths,
                         totalFlexibleWidth
@@ -241,7 +344,7 @@ export class AutoWidthStrategy {
                     totalFixedWidth -
                     totalResizedWidth;
 
-                // calculate ratio from data cells
+                // Calculate ratio from data cells
                 this._columnWidthRatios = this._getRatios(
                     dataCellWidths,
                     totalFlexibleWidth
@@ -250,17 +353,22 @@ export class AutoWidthStrategy {
         }
     }
 
+    /**
+     * @private
+     * Resets the column width distribution.
+     */
     _resetColumnWidthsDistribution() {
         this.columnWidthsDistribution.colsWithMinWidth = [];
         this.columnWidthsDistribution.colsWithMaxWidth = [];
     }
 
     /**
-     * Allocates width to a column as per defined width or as per ratio
-     * @param availableWidth {number} - available width for the table
-     * @param columnDefs {object} - column defs in state
-     * @param widthsMetadata {object} - metadata regarding widths includes max, min, flexiblewidth, fixedwidth
      * @private
+     * Allocates width to a column as per defined width or as per ratio.
+     *
+     * @param {Number} availableWidth Available width for the table
+     * @param {Object} columnDefs Column definitions in state
+     * @param {Object} widthsMetadata Metadata regarding widths includes `max`, `min`, `flexiblewidth`, `fixedwidth`
      */
     _distributeWidthFromRatios(availableWidth, columnDefs, widthsMetadata) {
         const columnWidths = [];
@@ -278,13 +386,14 @@ export class AutoWidthStrategy {
     }
 
     /**
-     * Calculates column width of a given column from the ratio
-     * Clamps to minColWidth and maxColWidth
-     * Also sets housekeeping data for colsWithMaxWidth threshold and colsWithMinWidth threshold
-     * @param availableWidth {number} - available width for the table
-     * @param widthsMetadata {object} - metadata regarding widths includes max, min, flexiblewidth, fixedwidth
-     * @param colIndex {number} - column number
      * @private
+     * Calculates column width of a given column from the ratio.
+     * Clamps to `minColWidth` and `maxColWidth`.
+     * Also sets housekeeping data for `colsWithMaxWidth` threshold and `colsWithMinWidth` threshold.
+     *
+     * @param {Number} availableWidth Available width for the table
+     * @param {Object} widthsMetadata Metadata regarding widths includes max, min, flexiblewidth, fixedwidth
+     * @param {Number} colIndex Column number
      */
     _getColumnWidthFromRatio(availableWidth, widthsMetadata, colIndex) {
         const ratios = this.columnWidthRatios;
@@ -322,14 +431,14 @@ export class AutoWidthStrategy {
     }
 
     /**
-     * This method gives extra width that was remaining by
-     * first giving width to columns with max width or within threshold of max width
-     * then by giving from all columns possible - excluding fixed width columns, columns that
-     * can become max width after redistribution
-     * @param expectedTableWidth {number} - width taken by the table in the dom
-     * @param columnWidths {array} - widths array
-     * @param columnDefs {array} - columnDefs from state
      * @private
+     * This method gives extra width that was remaining by first giving width to columns with
+     * max width or within threshold of max width then by giving from all columns possible,
+     * excluding fixed width columns, columns that can become max width after redistribution.
+     *
+     * @param {Number} expectedTableWidth Width taken by the table in the DOM
+     * @param {Array} columnWidths Column widths array
+     * @param {Object} columnDefs Column definitions from state
      */
     _redistributeExtraWidth(expectedTableWidth, columnWidths, columnDefs) {
         const { colsWithMinWidth } = this.columnWidthsDistribution;
@@ -346,7 +455,7 @@ export class AutoWidthStrategy {
         let totalColsToDistribute = 0;
         let extraWidthPerColumn = 0;
 
-        // first distribute space to columns with min width or threshold of min width
+        // First distribute space to columns with min width or threshold of min width
         if (colsWithMinWidth.length > 0) {
             totalColsToDistribute = colsWithMinWidth.length;
             extraWidthPerColumn = Math.floor(
@@ -371,9 +480,9 @@ export class AutoWidthStrategy {
         extraSpace = expectedTableWidth - columnWidthsSum;
         const totalFixedWidthColumns = totalResizedColumns + totalFixedColumns;
 
-        // now distribute to every column possible excluding columns with defined widths
+        // Now distribute to every column possible excluding columns with defined widths
         // after this distribution its still possible we might have more space remaining
-        // since we couldnt add widths to majority of columns
+        // since we couldn't add widths to majority of columns.
         if (extraSpace > 0) {
             totalColsToDistribute = columnDefs.length - totalFixedWidthColumns;
 
@@ -400,14 +509,14 @@ export class AutoWidthStrategy {
     }
 
     /**
-     * This method removes extra space that was taken by
-     * first taking away width from columns with max width or within threshold of max width
-     * then by taking away from all columns possible - excluding fixed width columns, column with min width or
-     * can become min width after taking away
-     * @param expectedTableWidth {number} - width taken by the table in the dom
-     * @param columnWidths - widths array
-     * @param columnDefs - columnDefs from state
      * @private
+     * This method removes extra space that was taken by first taking away width from columns with
+     * max width or within threshold of max width then by taking away from all columns possible,
+     * excluding fixed width columns, column with min width or can become min width after taking away.
+     *
+     * @param {Number} expectedTableWidth Width taken by the table in the DOM
+     * @param {Array} columnWidths Column widths array
+     * @param {Object} columnDefs Column definitions from state
      */
     _redistributeDeficitWidth(expectedTableWidth, columnWidths, columnDefs) {
         const { colsWithMinWidth, colsWithMaxWidth } =
@@ -424,7 +533,7 @@ export class AutoWidthStrategy {
         let totalColsToDistribute = 0;
         let extraWidthPerColumn = 0;
 
-        // first take away width from columns with max width or threshold of max width
+        // First take away width from columns with max width or threshold of max width
         if (colsWithMaxWidth.length > 0) {
             totalColsToDistribute = colsWithMaxWidth.length;
             extraWidthPerColumn = Math.floor(
@@ -450,7 +559,7 @@ export class AutoWidthStrategy {
         extraSpace = expectedTableWidth - columnWidthsSum;
         const totalFixedWidthColumns = totalResizedColumns + totalFixedColumns;
 
-        // now from every column possible excluding columns with defined widths
+        // Now from every column possible excluding columns with defined widths
         // and excluding columns within minWidthThreshold
         // after this distribution its still possible we might have used more space
         // since we couldnt take away widths from majority of columns