lightning-base-components 1.14.3-alpha → 1.14.4-alpha

package/src/lightning/datatable/renderManager.js

@@ -16,29 +16,32 @@ export function isViewportRenderingEnabled(state) {
     return state.enableViewportRendering;
 }
 
-export function normalizeVirtualization(value) {
-    return normalizeString(value, {
-        fallbackValue: '', //no virtualization enabled
-        validValues: [VERTICAL_VIRTUALIZATION],
-    });
-}
-
-export function getDTRows() {
-    return this.state.rows;
-}
-
-export function getDTRenderedRowCount() {
-    return this._renderedRowCount;
-}
-
-export function setDTRenderedRowCount(renderedRowCount) {
-    this._renderedRowCount = renderedRowCount;
+export function setVirtualize(state, value) {
+    if (state.renderModeRoleBased) {
+        state.virtualize = normalizeString(value, {
+            fallbackValue: '', //no virtualization enabled
+            validValues: [VERTICAL_VIRTUALIZATION],
+        });
+    } else {
+        state.virtualize = '';
+    }
 }
 
 export function getDTWrapperHeight() {
     return this.template.querySelector('.slds-scrollable_x').offsetHeight;
 }
 
+/**
+ * Sets the first visible index in the datatable state based on
+ * a given scrollTop value and the current rowHeight
+ *
+ * @param {Object} state - datatable state
+ * @param {Number} scrollTop - scroll top to calculate first visible index for
+ */
+export function setFirstVisibleIndex(state, scrollTop) {
+    state.firstVisibleIndex = Math.floor(scrollTop / state.rowHeight);
+}
+
 function getDefaultPreviousInfo() {
     return {
         renderedRowCount: 0,
@@ -52,6 +55,8 @@ function getDefaultPreviousInfo() {
  * @type {object}
  * @property {boolean} viewportRendering - specifies whether to use viewport rendering
  * @property {number} rowHeight - specifies the height of a row, in px
+ * @property {number|string} bufferSize - specifies the number of additional rows to render above/below what's visible on screen
+ * @property {string} virtualize - string representing what kind of virtualization to enable; currently only 'vertical' is available
  */
 
 /**
@@ -63,49 +68,34 @@ function getDefaultPreviousInfo() {
  */
 export class RenderManager {
     constructor() {
-        this.bufferSize = DEFAULT_BUFFER_SIZE;
-        this.rowHeight = DEFAULT_ROW_HEIGHT;
         this.threshold = DEFAULT_SCROLL_THRESHOLD;
         this.wrapperHeight = 0;
-        this.virtualize = '';
         this.previousCache = getDefaultPreviousInfo();
     }
 
     /**
      * Updates and normalizes configuration for RenderManager
      * Used when setting renderConfig for datatable
-     * @param {Function} getRows
-     * @param {Function} getWrapperHeight
-     * @param {Number} renderedRowCount
-     * @param {Function} setRenderedRowCount
-     * @param {RenderManagerConfig} config
+     * @param {Object} state - datatable state
+     * @param {Function} getWrapperHeight - function to get height of datatable wrapper
+     * @param {RenderManagerConfig} config - set of properties used for render management
      */
-    configure(
-        getRows,
-        getWrapperHeight,
-        renderedRowCount,
-        setRenderedRowCount,
-        config
-    ) {
+    configure(state, getWrapperHeight, config) {
         const { viewportRendering, rowHeight, virtualize, bufferSize } = config;
-        this.virtualize = normalizeVirtualization(virtualize);
-        if (normalizeBoolean(viewportRendering) || this.virtualize) {
-            this.initializeResizeObserver(
-                getRows,
-                getWrapperHeight,
-                renderedRowCount,
-                setRenderedRowCount
-            );
+        setVirtualize(state, virtualize);
+
+        if (normalizeBoolean(viewportRendering) || state.virtualize) {
+            this.initializeResizeObserver(state, getWrapperHeight);
         }
-        this.bufferSize = normalizeNumberAttribute(
+        state.bufferSize = normalizeNumberAttribute(
             'bufferSize',
             bufferSize || DEFAULT_BUFFER_SIZE,
             'non-negative',
             DEFAULT_BUFFER_SIZE
         );
         if (typeof rowHeight === 'number') {
-            this.rowHeight = rowHeight;
-            this.threshold = ROW_THRESHOLD * this.rowHeight;
+            state.rowHeight = rowHeight;
+            this.threshold = ROW_THRESHOLD * state.rowHeight;
         }
     }
 
@@ -117,39 +107,24 @@ export class RenderManager {
      * append a viewport's worth of rows to the currently rendered rows. This happens when
      * the user has added more data to the datatable (e.g when a loadMore is triggered)
      *
-     * @param {Array} rows
-     * @param {Function} setRenderedRowCount
-     * @param {Node} gridContainer
-     * @param {Boolean} forceUpdate
+     * @param {Object} state - datatable state
+     * @param {Node} gridContainer - node containing datatable header and rows
+     * @param {Boolean} forceUpdate - always recalculates row count if true
      */
-    updateViewportRendering(
-        rows,
-        setRenderedRowCount,
-        gridContainer,
-        forceUpdate
-    ) {
-        if (this.hasDataChanged(rows) || forceUpdate) {
-            this.updateRenderedRows(
-                rows,
-                setRenderedRowCount,
-                this.getRowCountWithBuffer()
-            );
+    updateViewportRendering(state, gridContainer, forceUpdate) {
+        if (this.hasDataChanged(state.rows) || forceUpdate) {
+            this.updateRenderedRows(state, this.getRowCountWithBuffer(state));
         } else if (
-            this.previousCache.totalRowCount < rows.length &&
+            this.previousCache.totalRowCount < state.rows.length &&
             this.isWithinThreshold(gridContainer)
         ) {
             this.updateRenderedRows(
-                rows,
-                setRenderedRowCount,
+                state,
                 this.previousCache.renderedRowCount +
-                    this.getRowCountWithBuffer()
+                    this.getRowCountWithBuffer(state)
             );
         } else {
-            this.updateRenderedRows(
-                rows,
-                setRenderedRowCount,
-                this.previousCache.renderedRowCount
-            );
+            this.updateRenderedRows(state, this.previousCache.renderedRowCount);
         }
     }
 
@@ -158,45 +133,33 @@ export class RenderManager {
      * If the scroll is within a specified threshold of the bottom,
      * calculate and render the next batch of rows
      *
-     * @param {Array} rows
-     * @param {Number} currentLength
-     * @param {Function} setRenderedRowCount
+     * @param {Object} state - datatable state
      * @param {Event} event - scroll event
      */
-    handleScroll(rows, currentLength, setRenderedRowCount, event) {
+    handleScroll(state, event) {
+        const { rows, renderedRowCount } = state;
         if (
             this.isWithinThreshold(event.target.firstChild) &&
-            currentLength < rows.length
+            renderedRowCount < rows.length
         ) {
             this.updateRenderedRows(
-                rows,
-                setRenderedRowCount,
-                currentLength + this.getRowCountWithBuffer()
+                state,
+                renderedRowCount + this.getRowCountWithBuffer(state)
             );
         }
     }
 
-    /**
-     * gets the index of the first row that should be visible in the viewport
-     *
-     * @param {Event} event
-     * @returns {number} index of first row visible in viewport
-     */
-    getFirstVisibleIndex(event) {
-        return event.target.scrollTop / this.rowHeight;
-    }
-
     /**
      * calculates the range of rows that should be rendered based on the
      * first visible index, buffer size and datatable height
      *
-     * @param {number} firstVisibleIndex
+     * @param {Object} state - datatable state
      * @returns {Object} object with firstIndex and lastIndex of rendered range of rows
      */
-    getRenderedRange(firstVisibleIndex) {
-        const firstIndex = Math.max(firstVisibleIndex - this.bufferSize, 0);
-        const lastIndex =
-            firstVisibleIndex - this.bufferSize + this.getRowCountWithBuffer();
+    getRenderedRange(state) {
+        const { firstVisibleIndex, bufferSize, renderedRowCount } = state;
+        const firstIndex = Math.max(firstVisibleIndex - bufferSize, 0);
+        const lastIndex = firstVisibleIndex - bufferSize + renderedRowCount;
 
         return { firstIndex, lastIndex };
     }
@@ -204,16 +167,16 @@ export class RenderManager {
     /**
      * Updates internal cache of row counts and first key
      *
-     * @param {Array} rows
-     * @param {Function} setRenderedRowCount
-     * @param {Number} rowCount
+     * @param {Object} state - datatable state
+     * @param {Number} rowCount - max number of rows to set renderedRowCount to
      */
-    updateRenderedRows(rows, setRenderedRowCount, rowCount) {
+    updateRenderedRows(state, rowCount) {
+        const rows = state.rows;
         const totalRows = rows.length;
         const normalizedRowCount = rowCount
             ? Math.min(rowCount, totalRows)
             : totalRows;
-        setRenderedRowCount(normalizedRowCount);
+        state.renderedRowCount = normalizedRowCount;
 
         // Update our internal cache
         this.previousCache.renderedRowCount = normalizedRowCount;
@@ -228,7 +191,7 @@ export class RenderManager {
      * Caches the height of the wrapper in Datatable to avoid
      * unnecessary reflows
      *
-     * @param {Function} getWrapperHeight
+     * @param {Function} getWrapperHeight - function to get height of datatable wrapper
      */
     updateWrapperHeight(getWrapperHeight) {
         this.wrapperHeight = getWrapperHeight();
@@ -240,17 +203,10 @@ export class RenderManager {
      * Initializes a resize observer to update the wrapper height
      * when the datatable component's height changes
      *
-     * @param {Function} getRows
-     * @param {Function} getWrapperHeight
-     * @param {Function} getRenderedRowCount
-     * @param {Function} setRenderedRowCount
+     * @param {Object} state - datatable state
+     * @param {Function} getWrapperHeight - function to get height of datatable wrapper
      */
-    initializeResizeObserver(
-        getRows,
-        getWrapperHeight,
-        getRenderedRowCount,
-        setRenderedRowCount
-    ) {
+    initializeResizeObserver(state, getWrapperHeight) {
         if (!this._heightResizeObserver) {
             this._heightResizeObserver = new LightningResizeObserver(() => {
                 if (this._resizeObserverConnected) {
@@ -258,16 +214,14 @@ export class RenderManager {
 
                     // If the wrapper is now larger than the table or virtualization enabled,
                     // we need to update the rendered rows so users can continue scrolling
-                    const rowCountWithBuffer = this.getRowCountWithBuffer();
+                    const rowCountWithBuffer =
+                        this.getRowCountWithBuffer(state);
+
                     if (
-                        rowCountWithBuffer > getRenderedRowCount() ||
-                        this.virtualize
+                        rowCountWithBuffer > state.renderedRowCount ||
+                        state.virtualize
                     ) {
-                        this.updateRenderedRows(
-                            getRows(),
-                            setRenderedRowCount,
-                            rowCountWithBuffer
-                        );
+                        this.updateRenderedRows(state, rowCountWithBuffer);
                     }
                 }
             });
@@ -301,19 +255,21 @@ export class RenderManager {
     /**
      * Calculates how many rows fits within the current wrapper
      */
-    getRowCountInViewport() {
-        return Math.ceil(this.wrapperHeight / this.rowHeight);
+    getRowCountInViewport(state) {
+        return Math.ceil(this.wrapperHeight / state.rowHeight);
     }
 
     /**
      * Calculates how many rows fit in current wrapper with an added buffer
      * Used to determine how many additional rows to render
      */
-    getRowCountWithBuffer() {
+    getRowCountWithBuffer(state) {
         // buffer is before and after with virtualization
         // but only after with viewport rendering
-        const multiplier = this.virtualize ? 2 : 1;
-        return this.getRowCountInViewport() + this.bufferSize * multiplier;
+        const multiplier = state.virtualize ? 2 : 1;
+        return (
+            this.getRowCountInViewport(state) + state.bufferSize * multiplier
+        );
     }
 
     /**

package/src/lightning/datatable/rows.js

@@ -115,8 +115,8 @@ export function uniqueRowKeyGenerator(keyField) {
  * @param {object} state - the current datatable state
  */
 export function updateRowsAndCellIndexes() {
-    const { state, privateTypes: types, _virtualize } = this;
-    const { keyField, renderModeRoleBased } = state;
+    const { state, privateTypes: types } = this;
+    const { keyField, renderModeRoleBased, virtualize } = state;
     const data = getData(state);
     const columns = getColumns(state);
     const computeUniqueRowKey = uniqueRowKeyGenerator(keyField);
@@ -142,7 +142,7 @@ export function updateRowsAndCellIndexes() {
         row.classnames = resolveRowClassNames(row);
         Object.assign(row, getRowStateForTree(rowData, state));
         row.tabIndex = -1;
-        if (_virtualize) {
+        if (virtualize) {
             row.style = styleToString({
                 position: 'absolute',
                 top: `${rowIndex * DEFAULT_ROW_HEIGHT}px`,
@@ -402,7 +402,7 @@ function computeCellEditable(row, column) {
  * @param {object} row - a row data object stored in datatable state. Must be truthy.
  * @param {object} column - a column data object stored in datatable state. Must be truthy.
  */
-function isCellEditable(row, column) {
+export function isCellEditable(row, column) {
     return !!resolveAttributeValue(column.editable, row);
 }
 

package/src/lightning/datatable/state.js

@@ -55,8 +55,13 @@ export const getDefaultState = function () {
         // table render mode
         renderModeRoleBased: false,
 
-        // viewport rendering
+        // viewport rendering and virtualization
         enableViewportRendering: undefined,
+        virtualize: '',
+        bufferSize: 5, // number of extra rows rendered on each side outside of viewport
+        rowHeight: 30.5,
+        renderedRowCount: 0,
+        firstVisibleIndex: 0, // first row that should be visible in viewport
 
         // inline edit
         inlineEdit: {

package/src/lightning/datatable/templates/div/div.html

@@ -48,6 +48,7 @@
                             <div class="slds-line-height_reset table-header"
                                 role="row"
                                 aria-rowindex="1"
+                                data-row-key-value="HEADER"
                                 onprivateresizestart={handleResizeStart}
                                 onprivateresizeend={handleResizeEnd}>
                                 <template for:each={state.columns} for:item="def" for:index="colIndex">
@@ -58,6 +59,7 @@
                                         tabindex={def.tabIndex}
                                         aria-label={def.ariaLabel}
                                         aria-sort={def.sortAriaLabel}
+                                        data-col-key-value={def.colKeyValue}
                                         key={def.colKeyValue}>
 
                                         <template if:true={def.fixedWidth}>
@@ -130,6 +132,7 @@
                                                 role="gridcell"
                                                 tabindex={cell.tabIndex}
                                                 data-label={cell.dataLabel}
+                                                data-col-key-value={cell.colKeyValue}
                                                 key={cell.colKeyValue}>
                                                 <lightning-primitive-cell-checkbox
                                                     dt-context-id={_datatableId}
@@ -155,6 +158,7 @@
                                                 aria-readonly={cell.ariaReadOnly}
                                                 tabindex={cell.tabIndex}
                                                 data-label={cell.dataLabel}
+                                                data-col-key-value={cell.colKeyValue}
                                                 key={cell.colKeyValue}>
                                                 <lightning-primitive-cell-factory
                                                     types={privateTypes}
@@ -203,6 +207,7 @@
                                                 aria-readonly={cell.ariaReadOnly}
                                                 tabindex={cell.tabIndex}
                                                 data-label={cell.dataLabel}
+                                                data-col-key-value={cell.colKeyValue}
                                                 key={cell.colKeyValue}>
                                                 <lightning-primitive-cell-factory
                                                     types={privateTypes}

package/src/lightning/datatable/templates/table/table.html

@@ -41,6 +41,7 @@
                         <thead>
                             <!-- Column Header Row -->
                             <tr class="slds-line-height_reset"
+                                data-row-key-value="HEADER"
                                 onprivateresizestart={handleResizeStart}
                                 onprivateresizeend={handleResizeEnd}>
                                 <template for:each={state.columns} for:item="def" for:index="colIndex">
@@ -50,6 +51,7 @@
                                         tabindex={def.tabIndex}
                                         aria-label={def.ariaLabel}
                                         aria-sort={def.sortAriaLabel}
+                                        data-col-key-value={def.colKeyValue}
                                         key={def.colKeyValue}>
 
                                         <template if:true={def.fixedWidth}>
@@ -117,6 +119,7 @@
                                                 role="gridcell"
                                                 tabindex={cell.tabIndex}
                                                 data-label={cell.dataLabel}
+                                                data-col-key-value={cell.colKeyValue}
                                                 key={cell.colKeyValue}>
                                                 <lightning-primitive-cell-checkbox
                                                     dt-context-id={_datatableId}
@@ -142,6 +145,7 @@
                                                 scope="row"
                                                 tabindex={cell.tabIndex}
                                                 data-label={cell.dataLabel}
+                                                data-col-key-value={cell.colKeyValue}
                                                 key={cell.colKeyValue}>
                                                 <lightning-primitive-cell-factory
                                                     types={privateTypes}
@@ -190,6 +194,7 @@
                                                 aria-readonly={cell.ariaReadOnly}
                                                 tabindex={cell.tabIndex}
                                                 data-label={cell.dataLabel}
+                                                data-col-key-value={cell.colKeyValue}
                                                 key={cell.colKeyValue}>
                                                 <lightning-primitive-cell-factory
                                                     types={privateTypes}

package/src/lightning/datatable/wrapText.js

@@ -3,8 +3,10 @@ import labelWrapText from '@salesforce/label/LightningDatatable.wrapText';
 import { getStateColumnIndex, getColumns } from './columns';
 import { normalizeBoolean } from 'lightning/utilsPrivate';
 import { normalizeNumberAttribute } from './utils';
+import { getDefaultState } from './state';
 
-const nonWrapableTypes = [
+const WRAP_TEXT_DEFAULT = false;
+const NON_WRAPPABLE_TYPES = [
     'action',
     'boolean',
     'button',
@@ -13,17 +15,33 @@ const nonWrapableTypes = [
     'rowNumber',
 ];
 
-const WRAP_TEXT_DEFAULT = false;
-
 const i18n = {
     clipText: labelClipText,
     wrapText: labelWrapText,
 };
 
-function isWrapableType(type) {
-    return nonWrapableTypes.indexOf(type) < 0;
+/************************** WRAP TEXT STATE **************************/
+
+// Returns a boolean representing whether or not the column should be text wrapped
+export function getWrapTextState(state = getDefaultState(), colKeyValue) {
+    return state.wrapText[colKeyValue] || WRAP_TEXT_DEFAULT;
 }
 
+// Sets a boolean value in state's wrapText object against the column key value
+// representing whether or not the column is text wrapped
+export function setWrapTextState(state = getDefaultState(), columnDefinition) {
+    const { colKeyValue, type, wrapText } = columnDefinition;
+
+    if (isWrappableType(type)) {
+        state.wrapText[colKeyValue] =
+            normalizeBoolean(wrapText) || WRAP_TEXT_DEFAULT;
+    }
+}
+
+/************************** WRAP TEXT MAX LINES **************************/
+
+// Normalizes and sets wrapTextMaxLines in datatable's state object
+// The normalized value should be a positive integer or it'll fall back to undefined
 export function setWrapTextMaxLines(state, value) {
     state.wrapTextMaxLines = normalizeNumberAttribute(
         'wrapTextMaxLines',
@@ -33,6 +51,8 @@ export function setWrapTextMaxLines(state, value) {
     );
 }
 
+// Sets the `wrapText` and `wrapTextMaxLines` values in the cell object for all cells in a column
+// These values are used by primitiveCellFactory to set the required classes on the cell for wrapping
 function updateWrapTextAndMaxLinesValuesInCells(state, colIndex, colKeyValue) {
     state.rows.forEach((row) => {
         const cell = row.cells[colIndex];
@@ -43,39 +63,17 @@ function updateWrapTextAndMaxLinesValuesInCells(state, colIndex, colKeyValue) {
     });
 }
 
-function updateSelectedOptionInHeaderActions(state, colKeyValue) {
-    const columns = getColumns(state);
-    const colIndex = getStateColumnIndex(state, colKeyValue);
-    const colData = columns[colIndex];
-
-    colData.actions.internalActions.forEach((action) => {
-        if (action.name === 'wrapText') {
-            action.checked = state.wrapText[colKeyValue];
-        }
-        if (action.name === 'clipText') {
-            action.checked = !state.wrapText[colKeyValue];
-        }
-    });
-
-    updateWrapTextAndMaxLinesValuesInCells(state, colIndex, colKeyValue);
-
-    // lets force a refresh on this column, because the wrapText checked value changed.
-    colData.actions = Object.assign({}, colData.actions);
-}
-
-export function getWrapTextState(state = getDefaultState(), colKeyValue) {
-    return state.wrapText[colKeyValue] || WRAP_TEXT_DEFAULT;
-}
-
-export function setWrapTextState(state = getDefaultState(), columnDefinition) {
-    const { colKeyValue, type, wrapText } = columnDefinition;
-
-    if (isWrapableType(type)) {
-        state.wrapText[colKeyValue] =
-            normalizeBoolean(wrapText) || WRAP_TEXT_DEFAULT;
-    }
-}
-
+/************************** HEADER ACTIONS **************************/
+
+/**
+ * Returns an object representing the two internal header actions that datatable
+ * provides - Wrap Text and Clip Text.
+ * Each header action contains a label, title, action name and its selected value (checked)
+ *
+ * @param {Object} state - datatable's state object
+ * @param {Object} columnDefinition - datatable's column definitions
+ * @returns
+ */
 export function getActions(state, columnDefinition) {
     const wrapTextActions = [];
     const { hideDefaultActions, type, colKeyValue } = columnDefinition;
@@ -84,7 +82,7 @@ export function getActions(state, columnDefinition) {
     setWrapTextState(state, columnDefinition);
 
     // if not hidden and isWrapable, sets the internal actions
-    if (isWrapableType(type) && !hideDefaultActions) {
+    if (isWrappableType(type) && !hideDefaultActions) {
         const isTextWrapped = getWrapTextState(state, colKeyValue);
 
         wrapTextActions.push({
@@ -105,19 +103,51 @@ export function getActions(state, columnDefinition) {
     return wrapTextActions;
 }
 
+/**
+ * If the action is an internal action and if the wrapText value for a column
+ * needs to be changed in the state, change it to the new value and update
+ * the check mark to represent the currently selected action
+ *
+ * @param {Object} state - datatable's state object
+ * @param {String} action - action that was selected/triggered
+ * @param {String} colKeyValue - column key value
+ */
 export function handleTriggeredAction(state, action, colKeyValue) {
-    if (action.name === 'wrapText' || action.name === 'clipText') {
-        // If will change state
-        if (state.wrapText[colKeyValue] !== (action.name === 'wrapText')) {
-            state.wrapText[colKeyValue] = action.name === 'wrapText';
+    const actionName = action.name;
+    if (actionName === 'wrapText' || actionName === 'clipText') {
+        // If state should be changed
+        if (state.wrapText[colKeyValue] !== (actionName === 'wrapText')) {
+            state.wrapText[colKeyValue] = actionName === 'wrapText';
 
             updateSelectedOptionInHeaderActions(state, colKeyValue);
         }
     }
 }
 
-export function getDefaultState() {
-    return {
-        wrapText: {},
-    };
+// Update the 'checked' value of the each action to show which action is selected
+// and which action is not selected
+function updateSelectedOptionInHeaderActions(state, colKeyValue) {
+    const columns = getColumns(state);
+    const colIndex = getStateColumnIndex(state, colKeyValue);
+    const colData = columns[colIndex];
+
+    colData.actions.internalActions.forEach((action) => {
+        if (action.name === 'wrapText') {
+            action.checked = state.wrapText[colKeyValue];
+        }
+        if (action.name === 'clipText') {
+            action.checked = !state.wrapText[colKeyValue];
+        }
+    });
+
+    updateWrapTextAndMaxLinesValuesInCells(state, colIndex, colKeyValue);
+
+    // Force a refresh on this column, because the wrapText checked value changed.
+    colData.actions = Object.assign({}, colData.actions);
+}
+
+/************************** HELPER FUNCTIONS **************************/
+
+function isWrappableType(type) {
+    return NON_WRAPPABLE_TYPES.indexOf(type) < 0;
 }