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

package/src/lightning/datatable/columnWidthManager.js

@@ -3,7 +3,7 @@ import {
     getResizerDefaultState,
     hasDefinedColumnsWidths,
     isTableRenderedVisible,
-} from './resizer';
+} from './columnResizer';
 import { AutoWidthStrategy } from './autoWidthStrategy';
 import { FixedWidthStrategy } from './fixedWidthStrategy';
 import {
@@ -20,11 +20,28 @@ import { isRTL } from 'lightning/utilsPrivate';
 const AUTO_WIDTH_MODE = 'auto';
 const FIXED_WIDTH_MODE = 'fixed';
 
-const TABLE_SEL = 'table';
-const CONTAINER_SEL = '.slds-scrollable_x';
-const DATA_CELL_SEL = 'tbody tr:first-child td,tbody tr:first-child th';
-const HEADER_CELL_SEL = 'thead tr th lightning-primitive-header-factory';
-
+const tableTypes = {
+    default: {
+        BASE: '.slds-table',
+        CONTAINER: '.slds-scrollable_x',
+        DATA_CELL: 'tbody tr:first-child td,tbody tr:first-child th',
+        HEADER_CELL: 'thead tr th lightning-primitive-header-factory',
+    },
+    roleBased: {
+        BASE: '.slds-table',
+        CONTAINER: '.slds-scrollable_x',
+        DATA_CELL: 'div[data-rowgroup-body] div[role="row"]:first-child div',
+        HEADER_CELL: 'div.table-header lightning-primitive-header-factory',
+    },
+};
+
+/**
+ * Computes and updates the `widthsData` for a datatable.
+ *
+ * @param {Object} adjustedWidths The adjusted widths object
+ * @param {Array} columnDefs The column definitions array
+ * @param {Object} widthsData The source widths data to update
+ */
 export function computeColumnWidths(adjustedWidths, columnDefs, widthsData) {
     const { columnWidths } = adjustedWidths;
     if (columnWidths.length !== columnDefs.length) {
@@ -46,20 +63,30 @@ export function computeColumnWidths(adjustedWidths, columnDefs, widthsData) {
         columnWidthsSum += newWidth;
     });
 
-    // W-7679487 tableWidth should match columnWidthsSum.
+    // TODO: W-7679487 - `tableWidth` should match `columnWidthsSum`
     widthsData.tableWidth = columnWidthsSum;
 }
 
+/**
+ * Column width manager.
+ * Invokes one of the two width managing strategies based
+ * on `column-widths-mode`: "auto" or "fixed"
+ */
 export class ColumnWidthManager {
+    // Private variables
     _columnWidthMode = FIXED_WIDTH_MODE;
     _resizeObserverAvailable = typeof ResizeObserver === 'function';
-    // flag to indicate resetting column widths is needed
-    // could be with or without autoResizingUpdate
+
+    // Flag to indicate resetting column widths is needed.
+    // Could be with or without `autoResizingUpdate`.
     _queueResizingUpdate = false;
-    // flag to indicate whether auto resizing computation update is needed
-    // in which case table styles need to auto flow
+
+    // Flag to indicate whether auto resizing computation update is needed,
+    // in which case table styles need to auto flow.
     _queueAutoResizingUpdate = false;
 
+    /************************** LIFECYCLE HOOKS **************************/
+
     constructor(widthsData) {
         const minColumnWidth =
             widthsData.minColumnWidth ||
@@ -80,50 +107,108 @@ export class ColumnWidthManager {
         this._widthStrategies[AUTO_WIDTH_MODE] = autoWidthStrategy;
     }
 
-    // Public apis exposed to datatable
+    /************************** PRIVATE GETTERS **************************/
 
+    /**
+     * Gets the configured column width strategy.
+     *
+     * @returns {Object} The column width strategy
+     */
     get columnWidthStrategy() {
         return this._widthStrategies[this.columnWidthMode];
     }
 
+    /**
+     * Gets the configured column width mode.
+     *
+     * @returns {String} The column width mode
+     */
     get columnWidthMode() {
         return this._columnWidthMode;
     }
 
+    /************************** PRIVATE SETTERS **************************/
+
+    /**
+     * Sets the column width mode.
+     *
+     * @param {String} value The new column width mode
+     */
     set columnWidthMode(value) {
         this._columnWidthMode = value;
     }
 
+    /**
+     * Sets the minimum column width (in pixels).
+     *
+     * @param {Number} value The minimum column width
+     */
     set minColumnWidth(value) {
         Object.keys(this._widthStrategies).forEach((strategy) => {
             this._widthStrategies[strategy].minColumnWidth = value;
         });
     }
 
+    /**
+     * Sets the maximum column width (in pixels).
+     *
+     * @param {Number} value The maximum column width
+     */
     set maxColumnWidth(value) {
         Object.keys(this._widthStrategies).forEach((strategy) => {
             this._widthStrategies[strategy].maxColumnWidth = value;
         });
     }
 
+    /**
+     * Sets the maximum number of text wrap lines
+     *
+     * @param {Number} value The maximum number of lines text can be wrapped on
+     */
     set wrapTextMaxLines(value) {
         this._widthStrategies[AUTO_WIDTH_MODE].wrapTextMaxLines = value;
     }
 
+    /************************* HELPER FUNCTIONS **************************/
+
+    /**
+     * Sets the datatable's configured render mode.
+     *
+     * @param {String} mode Either "table" or "role-based"
+     */
+    setRenderMode(mode) {
+        this._renderMode = mode;
+    }
+
+    /**
+     * Returns whether a resizing update is queued.
+     *
+     * @returns {Boolean} Whether there is a resizing update queued
+     */
     isResizingUpdateQueued() {
         return this._queueResizingUpdate;
     }
 
+    /**
+     * Returns whether an auto-resizing update is queued.
+     *
+     * @returns {Boolean} Whether there is an auto-resizing update queued
+     */
     isAutoResizingUpdateQueued() {
         return this._queueAutoResizingUpdate;
     }
 
+    /**
+     * Determines if we should fire the resize event based on the previous
+     * widths data and the column definition. The event is only fired when
+     * the number of columns change in fixed width mode. In auto width mode,
+     * nothing happens.
+     *
+     * @param {Object} previousWidthsData The previous widths data to evaluate
+     * @param {Array} columnDefs The column definitions array
+     * @returns {Boolean} Whether or not the resize event should be fired
+     */
     shouldFireResizeEvent(previousWidthsData, columnDefs) {
-        // in fixed widths mode fire resize event only when then
-        // column definitions change in number ie. initial render
-        // and subsequent changes in column number
-        // in auto widths mode dont fire resize event for programmatic
-        // actions fire only for user actions
         if (this._columnWidthMode === FIXED_WIDTH_MODE) {
             return (
                 getColumnsWidths(previousWidthsData).length !==
@@ -133,6 +218,13 @@ export class ColumnWidthManager {
         return false;
     }
 
+    /**
+     * Adjusts all the column sizes based on the supplied widths data.
+     *
+     * @param {Node} root The root column node
+     * @param {Array} columnDefs The column definitions array
+     * @param {Object} widthsData The widths data object
+     */
     adjustColumnsSize(root, columnDefs, widthsData) {
         const {
             _queueResizingUpdate,
@@ -140,10 +232,11 @@ export class ColumnWidthManager {
             columnWidthStrategy,
         } = this;
         let adjustedWidths = [];
+
         if (_queueResizingUpdate) {
-            // if table is hidden when updating and ResizeObserver is not available
-            // then updating sizes causes min widths to be set
-            // hence the check if ok update from dom
+            // If table is hidden when updating and `ResizeObserver` is not available,
+            // then updating sizes causes min widths to be set.
+            // Hence, the check if ok update from DOM.
             if (this._shouldResizeWithUpdate(root, widthsData)) {
                 adjustedWidths = columnWidthStrategy.getAdjustedColumnWidths(
                     this._getDatatableInterface(root),
@@ -151,7 +244,7 @@ export class ColumnWidthManager {
                     _queueAutoResizingUpdate
                 );
             } else {
-                // otherwise update from previous widths
+                // Otherwise update from previous widths
                 adjustedWidths = {
                     columnWidths: widthsData.columnWidths,
                     expectedTableWidth: widthsData.tableWidth,
@@ -159,10 +252,18 @@ export class ColumnWidthManager {
             }
             computeColumnWidths(adjustedWidths, columnDefs, widthsData);
         }
+
         this._resetAutoResizingUpdate();
         this._queueResizingUpdate = false;
     }
 
+    /**
+     * Adjusts all the column widths after a resize happens.
+     *
+     * @param {Node} root The root column node
+     * @param {Array} columnDefs The column definitions array
+     * @param {Object} widthsData The widths data object
+     */
     adjustColumnsSizeAfterResize(root, columnDefs, widthsData) {
         const adjustedWidths = this.columnWidthStrategy.getAdjustedColumnWidths(
             this._getDatatableInterface(root),
@@ -171,13 +272,18 @@ export class ColumnWidthManager {
         computeColumnWidths(adjustedWidths, columnDefs, widthsData);
     }
 
-    // React to change in data
+    /**
+     * React to a change in data.
+     *
+     * @param {Object} previousData The previous data
+     * @param {Object} newData The new data
+     * @param {Array} columnDefs The column definitions array
+     */
     handleDataChange(previousData, newData, columnDefs) {
         if (columnDefs.length > 0) {
-            // resize columns with auto-resizing update only if -
-            // mode is auto and
-            // new data length is equal to previous data length (change in data)
-            // or previously there was no data at all
+            // Resize columns with auto-resizing update only if...
+            // The mode is auto and new data length is equal to previous data
+            // length (change in data) or previously there was no data at all.
             if (this.columnWidthMode === AUTO_WIDTH_MODE) {
                 if (this._hasDataChanged(previousData, newData)) {
                     this._queueResizingUpdate = true;
@@ -187,7 +293,11 @@ export class ColumnWidthManager {
         }
     }
 
-    // React to change in column definitions
+    /**
+     * React to change in column definitions
+     *
+     * @param {Array} columnDefs The column definitions array
+     */
     handleColumnsChange(columnDefs) {
         if (columnDefs.length > 0) {
             this._queueResizingUpdate = true;
@@ -195,7 +305,11 @@ export class ColumnWidthManager {
         }
     }
 
-    // React to change in column widths mode
+    /**
+     * React to change in column widths mode
+     *
+     * @param {Array} columnDefs The column definitions array
+     */
     handleWidthModeChange(columnDefs) {
         if (columnDefs.length > 0) {
             this._queueResizingUpdate = true;
@@ -203,7 +317,12 @@ export class ColumnWidthManager {
         }
     }
 
-    // React to change in row number offset
+    /**
+     * React to change in row number offset
+     *
+     * @param {Object} state The datatable state
+     * @param {Object} widthsData The source widths data to updated
+     */
     handleRowNumberOffsetChange(state, widthsData) {
         const colIndex = getRowNumberColumnIndex(state);
         if (colIndex > -1) {
@@ -215,8 +334,8 @@ export class ColumnWidthManager {
                     rowNumberCol.minWidth
                 );
                 if (hasDefinedColumnsWidths(widthsData)) {
-                    // when columns are resized with the resizer, a horizontal scroller appears.
-                    // adjusting the columns size, will respect widths already set and try to fit this column
+                    // When columns are resized with the resizer, a horizontal scroller appears.
+                    // Adjusting the columns size will respect widths already set and try to fit this column.
                     this._queueResizingUpdate = true;
                     this._setAutoResizingUpdate(state.columns);
                 }
@@ -224,14 +343,26 @@ export class ColumnWidthManager {
         }
     }
 
-    // React to change in hide-checkbox-column
+    /**
+     * React to change in hide-checkbox-column
+     *
+     * @param {Any} previousValue The previous column value
+     * @param {Any} newValue The new column value
+     * @param {Array} columnDefs The column definitions array
+     */
     handleCheckboxColumnChange(previousValue, newValue, columnDefs) {
         if (columnDefs.length > 0 && previousValue !== newValue) {
             this._queueResizingUpdate = true;
         }
     }
 
-    // React to change in show-row-number-column
+    /**
+     * React to change in show-row-number-column
+     *
+     * @param {Any} previousValue The previous column value
+     * @param {Any} newValue The new column value
+     * @param {Array} columnDefs The column definitions array
+     */
     handleRowNumberColumnChange(previousValue, newValue, columnDefs) {
         if (columnDefs.length > 0 && previousValue !== newValue) {
             this._queueResizingUpdate = true;
@@ -239,8 +370,13 @@ export class ColumnWidthManager {
         }
     }
 
-    // Private helper functions
-
+    /**
+     * @private
+     * Queues up an auto resizing update. If a column width isn't defined,
+     * reset the width so it can be recalculated.
+     *
+     * @param {Array} columnDefs The column definitions array
+     */
     _setAutoResizingUpdate(columnDefs) {
         if (this.columnWidthMode === AUTO_WIDTH_MODE) {
             this._queueAutoResizingUpdate = true;
@@ -255,10 +391,22 @@ export class ColumnWidthManager {
         }
     }
 
+    /**
+     * @private
+     * Resets the auto resizing update queue.
+     */
     _resetAutoResizingUpdate() {
         this._queueAutoResizingUpdate = false;
     }
 
+    /**
+     * @private
+     * Evalutes if there is a change between two sets of data.
+     *
+     * @param {Array} previousData An array of previous data
+     * @param {Array} newData An array of new data
+     * @returns {Boolean} Whether or not the is a difference between the two data sets
+     */
     _hasDataChanged(previousData, newData) {
         return (
             newData.length > 0 &&
@@ -267,10 +415,18 @@ export class ColumnWidthManager {
         );
     }
 
+    /**
+     * @private
+     * Determines if a column should resize with an update.
+     *
+     * @param {Node} root The root column node
+     * @param {Object} widthsData The source widths data
+     * @returns {Boolean} Whether the column should resize with an update
+     */
     _shouldResizeWithUpdate(root, widthsData) {
         if (hasDefinedColumnsWidths(widthsData)) {
-            // can resize from dom when table is visible
-            // otherwise only when ResizeObserver is available in browser
+            // Can resize from DOM when table is visible.
+            // Otherwise, only when `ResizeObserver` is available in browser.
             return (
                 this._resizeObserverAvailable || isTableRenderedVisible(root)
             );
@@ -278,14 +434,39 @@ export class ColumnWidthManager {
         return true;
     }
 
+    /**
+     * @private
+     * Determines the appropriate selectors to use based on the datatable render mode.
+     *
+     * @returns {Object} Selectors based on datatable render mode
+     */
+    _getTableSelectors() {
+        if (this._renderMode === 'role-based') {
+            return tableTypes.roleBased;
+        }
+        return tableTypes.default;
+    }
+
+    /**
+     * @private
+     * Retrieves the datatable interface from the DOM
+     *
+     * @param {Node} root The root datatable node
+     * @returns {Object} The datatable interface
+     */
     _getDatatableInterface(root) {
+        const datatableSelectors = this._getTableSelectors();
         return {
             getAvailableWidthFromDom() {
-                const container = root.querySelector(CONTAINER_SEL);
+                const container = root.querySelector(
+                    datatableSelectors.CONTAINER
+                );
                 return getDomWidth(container);
             },
             getDataCellWidths() {
-                const cells = root.querySelectorAll(DATA_CELL_SEL);
+                const cells = root.querySelectorAll(
+                    datatableSelectors.DATA_CELL
+                );
                 if (cells.length > 0) {
                     return Array.prototype.slice
                         .call(cells)
@@ -297,7 +478,9 @@ export class ColumnWidthManager {
                 return [];
             },
             getHeaderCellWidths() {
-                const headerCells = root.querySelectorAll(HEADER_CELL_SEL);
+                const headerCells = root.querySelectorAll(
+                    datatableSelectors.HEADER_CELL
+                );
                 if (headerCells.length > 0) {
                     return Array.prototype.slice
                         .call(headerCells)
@@ -312,11 +495,10 @@ export class ColumnWidthManager {
                 return [];
             },
             getTableElementWidth() {
-                // TODO: Figure out a clean way to retrieve and use the correct selectors
-                // Currently outside scope of this work. Should be addressed in W-8540110
                 const tableElement =
-                    root.querySelector(TABLE_SEL) ||
-                    root.querySelector('[role="grid"]');
+                    root.querySelector(datatableSelectors.BASE) ||
+                    root.querySelector('[role="grid"]') ||
+                    root.querySelector('[role="treegrid"]');
                 return getDomWidth(tableElement);
             },
         };