lightning-base-components 1.13.10-alpha → 1.14.4-alpha

package/src/lightning/datatable/renderManager.js

@@ -1,10 +1,12 @@
-import { getScrollOffsetFromTableEnd } from './utils';
+import { getScrollOffsetFromTableEnd, normalizeNumberAttribute } from './utils';
 import { LightningResizeObserver } from 'lightning/resizeObserver';
-import { normalizeBoolean } from 'lightning/utilsPrivate';
+import { normalizeBoolean, normalizeString } from 'lightning/utilsPrivate';
 
-const BUFFER_ROW_COUNT = 5;
-const DEFAULT_ROW_HEIGHT = 30;
-const DEFAULT_SCROLL_THRESHOLD = 2 * BUFFER_ROW_COUNT * DEFAULT_ROW_HEIGHT;
+export const DEFAULT_ROW_HEIGHT = 30.5;
+const DEFAULT_BUFFER_SIZE = 5;
+const ROW_THRESHOLD = 10;
+const DEFAULT_SCROLL_THRESHOLD = ROW_THRESHOLD * DEFAULT_ROW_HEIGHT;
+const VERTICAL_VIRTUALIZATION = 'vertical';
 
 export function setViewportRendering(state, value) {
     state.enableViewportRendering = normalizeBoolean(value);
@@ -14,39 +16,30 @@ export function isViewportRenderingEnabled(state) {
     return state.enableViewportRendering;
 }
 
-/**
- * @typedef RenderManagerConfig
- * @type {object}
- * @property {boolean} viewportRendering - specifies whether to use viewport rendering
- * @property {number} rowHeight - specifies the height of a row, in px
- */
-
-/**
- * Updates and normalizes the configuration for this RenderManager
- *
- * @param {LightningDatatable} dt
- * @param {RenderManager} renderManager
- * @param {RenderManagerConfig} config
- *
- * @returns {RenderManager}
- */
-function normalizeAndProcessConfig(dt, renderManager, config) {
-    const { viewportRendering, rowHeight } = config;
-
-    if (viewportRendering && typeof viewportRendering === 'boolean') {
-        renderManager.initializeResizeObserver(dt);
-    }
-
-    if (typeof rowHeight === 'number') {
-        renderManager.rowHeight = rowHeight;
-        renderManager.threshold = calculateThreshold(rowHeight);
+export function setVirtualize(state, value) {
+    if (state.renderModeRoleBased) {
+        state.virtualize = normalizeString(value, {
+            fallbackValue: '', //no virtualization enabled
+            validValues: [VERTICAL_VIRTUALIZATION],
+        });
+    } else {
+        state.virtualize = '';
     }
+}
 
-    return renderManager;
+export function getDTWrapperHeight() {
+    return this.template.querySelector('.slds-scrollable_x').offsetHeight;
 }
 
-function calculateThreshold(rowHeight) {
-    return 2 * BUFFER_ROW_COUNT * rowHeight;
+/**
+ * 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() {
@@ -57,6 +50,15 @@ function getDefaultPreviousInfo() {
     };
 }
 
+/**
+ * @typedef RenderManagerConfig
+ * @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
+ */
+
 /**
  * Handles any custom rendering in datatable.
  *
@@ -66,38 +68,160 @@ function getDefaultPreviousInfo() {
  */
 export class RenderManager {
     constructor() {
-        this.rowHeight = DEFAULT_ROW_HEIGHT;
         this.threshold = DEFAULT_SCROLL_THRESHOLD;
         this.wrapperHeight = 0;
         this.previousCache = getDefaultPreviousInfo();
     }
 
     /**
+     * Updates and normalizes configuration for RenderManager
+     * Used when setting renderConfig for datatable
+     * @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(state, getWrapperHeight, config) {
+        const { viewportRendering, rowHeight, virtualize, bufferSize } = config;
+        setVirtualize(state, virtualize);
+
+        if (normalizeBoolean(viewportRendering) || state.virtualize) {
+            this.initializeResizeObserver(state, getWrapperHeight);
+        }
+        state.bufferSize = normalizeNumberAttribute(
+            'bufferSize',
+            bufferSize || DEFAULT_BUFFER_SIZE,
+            'non-negative',
+            DEFAULT_BUFFER_SIZE
+        );
+        if (typeof rowHeight === 'number') {
+            state.rowHeight = rowHeight;
+            this.threshold = ROW_THRESHOLD * state.rowHeight;
+        }
+    }
+
+    /**
+     * Render only rows that fit within the viewport
+     *
+     * If data has changed (verifying only row 1), reset everything
+     * Otherwise, if total row count has increased and we are within the scroll threshold,
+     * 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 {Object} state - datatable state
+     * @param {Node} gridContainer - node containing datatable header and rows
+     * @param {Boolean} forceUpdate - always recalculates row count if true
+     */
+    updateViewportRendering(state, gridContainer, forceUpdate) {
+        if (this.hasDataChanged(state.rows) || forceUpdate) {
+            this.updateRenderedRows(state, this.getRowCountWithBuffer(state));
+        } else if (
+            this.previousCache.totalRowCount < state.rows.length &&
+            this.isWithinThreshold(gridContainer)
+        ) {
+            this.updateRenderedRows(
+                state,
+                this.previousCache.renderedRowCount +
+                    this.getRowCountWithBuffer(state)
+            );
+        } else {
+            this.updateRenderedRows(state, this.previousCache.renderedRowCount);
+        }
+    }
+
+    /**
+     * Handles scroll event on datatable if viewport rendering enabled
+     * If the scroll is within a specified threshold of the bottom,
+     * calculate and render the next batch of rows
      *
-     * @param {LightningDatatable} dt
-     * @param {RenderManagerConfig} config
+     * @param {Object} state - datatable state
+     * @param {Event} event - scroll event
      */
-    configure(dt, config) {
-        normalizeAndProcessConfig(dt, this, config);
+    handleScroll(state, event) {
+        const { rows, renderedRowCount } = state;
+        if (
+            this.isWithinThreshold(event.target.firstChild) &&
+            renderedRowCount < rows.length
+        ) {
+            this.updateRenderedRows(
+                state,
+                renderedRowCount + this.getRowCountWithBuffer(state)
+            );
+        }
+    }
+
+    /**
+     * calculates the range of rows that should be rendered based on the
+     * first visible index, buffer size and datatable height
+     *
+     * @param {Object} state - datatable state
+     * @returns {Object} object with firstIndex and lastIndex of rendered range of rows
+     */
+    getRenderedRange(state) {
+        const { firstVisibleIndex, bufferSize, renderedRowCount } = state;
+        const firstIndex = Math.max(firstVisibleIndex - bufferSize, 0);
+        const lastIndex = firstVisibleIndex - bufferSize + renderedRowCount;
+
+        return { firstIndex, lastIndex };
     }
 
+    /**
+     * Updates internal cache of row counts and first key
+     *
+     * @param {Object} state - datatable state
+     * @param {Number} rowCount - max number of rows to set renderedRowCount to
+     */
+    updateRenderedRows(state, rowCount) {
+        const rows = state.rows;
+        const totalRows = rows.length;
+        const normalizedRowCount = rowCount
+            ? Math.min(rowCount, totalRows)
+            : totalRows;
+        state.renderedRowCount = normalizedRowCount;
+
+        // Update our internal cache
+        this.previousCache.renderedRowCount = normalizedRowCount;
+        this.previousCache.totalRowCount = totalRows;
+
+        if (rows.length > 0) {
+            this.previousCache.firstRowKey = rows[0].key;
+        }
+    }
+
+    /**
+     * Caches the height of the wrapper in Datatable to avoid
+     * unnecessary reflows
+     *
+     * @param {Function} getWrapperHeight - function to get height of datatable wrapper
+     */
+    updateWrapperHeight(getWrapperHeight) {
+        this.wrapperHeight = getWrapperHeight();
+    }
+
+    /************************** OBSERVER MANAGEMENT **************************/
+
     /**
      * Initializes a resize observer to update the wrapper height
      * when the datatable component's height changes
      *
-     * @param {LightningDatatable} dt
+     * @param {Object} state - datatable state
+     * @param {Function} getWrapperHeight - function to get height of datatable wrapper
      */
-    initializeResizeObserver(dt) {
+    initializeResizeObserver(state, getWrapperHeight) {
         if (!this._heightResizeObserver) {
             this._heightResizeObserver = new LightningResizeObserver(() => {
                 if (this._resizeObserverConnected) {
-                    this.updateWrapperHeight(dt);
+                    this.updateWrapperHeight(getWrapperHeight);
+
+                    // 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(state);
 
-                    // If the wrapper is now larger than the table, we need to update
-                    // the rendered rows so users can continue scrolling
-                    const rowCountWithBuffer = this.getRowCountWithBuffer();
-                    if (rowCountWithBuffer > dt._renderedRowCount) {
-                        this.updateRenderedRows(dt, rowCountWithBuffer);
+                    if (
+                        rowCountWithBuffer > state.renderedRowCount ||
+                        state.virtualize
+                    ) {
+                        this.updateRenderedRows(state, rowCountWithBuffer);
                     }
                 }
             });
@@ -107,13 +231,10 @@ export class RenderManager {
     /**
      * Connect the resize observer to the correct element
      *
-     * @param {LightningDatatable} dt
+     * @param {Node} resizeTarget
      */
-    connectResizeObserver(dt) {
+    connectResizeObserver(resizeTarget) {
         if (this._heightResizeObserver) {
-            const resizeTarget = dt.template.querySelector(
-                'div.dt-outer-container'
-            );
             this._heightResizeObserver.observe(resizeTarget);
             this._resizeObserverConnected = true;
         }
@@ -129,104 +250,51 @@ export class RenderManager {
         }
     }
 
-    hasWrapperHeight() {
-        return !!this.wrapperHeight;
-    }
-
-    /**
-     * Caches the height of the wrapper in Datatable to avoid
-     * unnecessary reflows
-     *
-     * @param {LightningDatatable} dt
-     */
-    updateWrapperHeight(dt) {
-        this.wrapperHeight =
-            dt.template.querySelector('.slds-scrollable_x').offsetHeight;
-    }
+    /************************* HELPER FUNCTIONS **************************/
 
     /**
      * Calculates how many rows fits within the current wrapper
      */
-    getRowCountInViewport() {
-        return Math.floor(this.wrapperHeight / this.rowHeight);
-    }
-
-    getRowCountWithBuffer() {
-        return this.getRowCountInViewport() + BUFFER_ROW_COUNT;
+    getRowCountInViewport(state) {
+        return Math.ceil(this.wrapperHeight / state.rowHeight);
     }
 
     /**
-     * Render only rows that fit within the viewport
-     *
-     * If data has changed (verifying only row 1), reset everything
-     * Otherwise, if total row count has increased and we are within the scroll threshold,
-     * 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 {LightningDatatable} dt
+     * Calculates how many rows fit in current wrapper with an added buffer
+     * Used to determine how many additional rows to render
      */
-    updateViewportRendering(dt, forceUpdate) {
-        if (this.hasDataChanged(dt) || forceUpdate) {
-            this.updateRenderedRows(dt, this.getRowCountWithBuffer());
-        } else if (
-            this.previousCache.totalRowCount < dt.state.rows.length &&
-            this.isWithinThreshold(dt.template.querySelector('table'))
-        ) {
-            this.updateRenderedRows(
-                dt,
-                this.previousCache.renderedRowCount +
-                    this.getRowCountWithBuffer()
-            );
-        } else {
-            this.updateRenderedRows(dt, this.previousCache.renderedRowCount);
-        }
+    getRowCountWithBuffer(state) {
+        // buffer is before and after with virtualization
+        // but only after with viewport rendering
+        const multiplier = state.virtualize ? 2 : 1;
+        return (
+            this.getRowCountInViewport(state) + state.bufferSize * multiplier
+        );
     }
 
     /**
-     * If the scroll is within a specified threshold of the bottom,
-     * calculate and render the next batch of rows
-     *
-     * @param {LightningDatatable} dt
-     * @param {Event} event - scroll event
+     * Checks if offset is within threshold of end of table
+     * Used when determining if additional rows should be rendered
+     * @returns {boolean} true if offset is within threshold
      */
-    handleScroll(dt, event) {
-        const currentLength = dt._renderedRowCount;
-        if (
-            this.isWithinThreshold(event.target.firstChild) &&
-            currentLength < dt.state.rows.length
-        ) {
-            this.updateRenderedRows(
-                dt,
-                currentLength + this.getRowCountWithBuffer()
-            );
-        }
-    }
-
-    updateRenderedRows(dt, rowCount) {
-        const totalRows = dt.state.rows.length;
-        const normalizedRowCount = rowCount
-            ? Math.min(rowCount, totalRows)
-            : totalRows;
-        dt._renderedRowCount = normalizedRowCount;
-
-        // Update our internal cache
-        this.previousCache.renderedRowCount = normalizedRowCount;
-        this.previousCache.totalRowCount = totalRows;
-
-        if (dt.state.rows.length > 0) {
-            this.previousCache.firstRowKey = dt.state.rows[0].key;
-        }
-    }
-
     isWithinThreshold(target) {
         const offset = getScrollOffsetFromTableEnd(target);
-        return offset < this.threshold;
+        return offset <= this.threshold;
     }
 
-    hasDataChanged(dt) {
+    /**
+     * Checks key of first row to determine if data has changed
+     * Used to determine if viewport rendering should be reset
+     * @param {Array} rows
+     * @returns {Boolean} true if key of first row has changed
+     */
+    hasDataChanged(rows) {
         return (
-            dt.state.rows.length > 0 &&
-            this.previousCache.firstRowKey !== dt.state.rows[0].key
+            rows.length > 0 && this.previousCache.firstRowKey !== rows[0].key
         );
     }
+
+    hasWrapperHeight() {
+        return !!this.wrapperHeight;
+    }
 }

package/src/lightning/datatable/rowLevelActions.js

@@ -3,39 +3,43 @@ import { getUserRowByCellKeys } from './rows';
 import { getUserColumnIndex } from './columns';
 
 /**
+ * Handles the `privatecellactiontriggered` event on lightning-datatable
  *
- * @param {CustomEvent} event - row action
+ * @param {CustomEvent} event - `privatecellactiontriggered`
  */
 export function handleRowActionTriggered(event) {
-    const { rowKeyValue, colKeyValue, action } = event.detail;
+    event.stopPropagation();
+
+    const { action, colKeyValue, rowKeyValue } = event.detail;
     const selectedRow = getUserRowByCellKeys(
         this.state,
         rowKeyValue,
         colKeyValue
     );
 
-    event.stopPropagation();
-
     this.dispatchEvent(
         new CustomEvent('rowaction', {
             detail: {
-                row: unwrap(selectedRow),
                 action: unwrap(action),
+                row: unwrap(selectedRow),
             },
         })
     );
 }
 
 /**
+ * Handles the `privatecellactionmenuopening` event on lightning-datatable
  *
- * @param {CustomEvent} event - load dynamic actions
+ * @param {CustomEvent} event - `privatecellactionmenuopening`
  */
 export function handleLoadDynamicActions(event) {
+    event.stopPropagation();
+
     const {
-        rowKeyValue,
-        colKeyValue,
         actionsProviderFunction,
+        colKeyValue,
         doneCallback,
+        rowKeyValue,
         saveContainerPosition,
     } = event.detail;
     const selectedRow = getUserRowByCellKeys(
@@ -45,18 +49,18 @@ export function handleLoadDynamicActions(event) {
     );
 
     saveContainerPosition(this.getViewableRect());
-
-    event.stopPropagation();
     actionsProviderFunction(unwrap(selectedRow), doneCallback);
 }
 
 /**
+ * Handles the `privatecellbuttonclicked` event on lightning-datatable
  *
- * @param {CustomEvent} event - fire `rowaction` on cell-button click
+ * @param {CustomEvent} event - `privatecellbuttonclicked`
  */
 export function handleCellButtonClick(event) {
     event.stopPropagation();
-    const { rowKeyValue, colKeyValue } = event.detail;
+
+    const { colKeyValue, rowKeyValue } = event.detail;
     const row = getUserRowByCellKeys(this.state, rowKeyValue, colKeyValue);
     const userColumnIndex = getUserColumnIndex(this.state, colKeyValue);
     const userColumnDefinition = this._columns[userColumnIndex];
@@ -64,8 +68,8 @@ export function handleCellButtonClick(event) {
     this.dispatchEvent(
         new CustomEvent('rowaction', {
             detail: {
-                row: unwrap(row),
                 action: unwrap(userColumnDefinition.typeAttributes),
+                row: unwrap(row),
             },
         })
     );

package/src/lightning/datatable/rowNumber.js

@@ -4,22 +4,22 @@ import labelRowNumber from '@salesforce/label/LightningDatatable.rowNumber';
 import { formatLabel } from 'lightning/utils';
 import { normalizeBoolean } from 'lightning/utilsPrivate';
 
+export const TOOLTIP_ALLOWANCE = 20;
 const CHAR_WIDTH = 10;
 const ROWNUMBER_PADDING = 12;
-const TOOLTIP_ALLOWANCE = 20;
-const COLUMN_TYPE = 'rowNumber';
+const ROW_NUMBER_COLUMN_TYPE = 'rowNumber';
 const i18n = {
     rowLevelErrorAssistiveText: labelRowLevelErrorAssistiveText,
     rowNumber: labelRowNumber,
 };
 
-export function isRowNumberColumn(column) {
-    return column.type === COLUMN_TYPE;
-}
-
+/**
+ * Returns the initial default column definition
+ * for the row number column
+ */
 export function getRowNumberColumnDef() {
     return {
-        type: COLUMN_TYPE,
+        type: ROW_NUMBER_COLUMN_TYPE,
         ariaLabel: i18n.rowNumber,
         sortable: false,
         initialWidth: 52,
@@ -31,39 +31,57 @@ export function getRowNumberColumnDef() {
     };
 }
 
-export function getRowNumberState() {
-    return {
-        showRowNumberColumn: false,
-        rowNumberOffset: 0,
-    };
-}
-
 /**
- * showRowNumberColumn
+ * Retrieves showRowNumberColumn from the state
+ * Can be used to determine if the datatable should
+ * show the row number column or not
  */
 export function hasRowNumberColumn(state) {
     return state.showRowNumberColumn;
 }
+
+/**
+ * Normalizes the passed in `value` to a boolean and
+ * sets it to showRowNumberColumn in the state
+ */
 export function setShowRowNumberColumn(state, value) {
     state.showRowNumberColumn = normalizeBoolean(value);
 }
 
 /**
- * rowNumberOffset
+ * Retrieves rowNumberOffset from the state
  */
-
 export function getRowNumberOffset(state) {
     return state.rowNumberOffset;
 }
+
+/**
+ * Normalizes the passed in value to a non-negative number
+ * and sets it to the rowNumberOffset in the state.
+ * If the value is invalid, it falls back to 0.
+ */
 export function setRowNumberOffset(state, value) {
     state.rowNumberOffset = normalizeNumberAttribute(
         'rowNumberOffset',
         value,
         'non-negative',
-        getRowNumberState().rowNumberOffset
+        0 // default rowNumberOffset value
     );
 }
 
+export function isRowNumberColumn(column) {
+    return column.type === ROW_NUMBER_COLUMN_TYPE;
+}
+
+/**
+ * Calculates the width of the row number column
+ * This takes into account the number of digits in the row number
+ * (ex. 3 for 100 rows), padding in the cell and
+ * space allowance for the error tooltip which is rendered in this cell
+ *
+ * @param {Object} state - datatable's state object
+ * @returns
+ */
 export function getAdjustedRowNumberColumnWidth(state) {
     const numOfRows = state.rows.length;
     const offset = state.rowNumberOffset;
@@ -76,12 +94,19 @@ export function getAdjustedRowNumberColumnWidth(state) {
     );
 }
 
+/**
+ * Retrieves the column index of the row number column
+ * Returns -1 if the row number column is not present
+ *
+ * @param {Object} state - datatable's state object
+ * @returns {Number} index of row number column. Returns -1 if not present
+ */
 export function getRowNumberColumnIndex(state) {
     if (hasRowNumberColumn(state) && state.columns.length > 0) {
         const columns = state.columns;
         for (let i = 0; i < columns.length; i++) {
             const column = columns[i];
-            if (column.type === COLUMN_TYPE) {
+            if (column.type === ROW_NUMBER_COLUMN_TYPE) {
                 return i;
             }
         }
@@ -89,6 +114,15 @@ export function getRowNumberColumnIndex(state) {
     return -1;
 }
 
+/**
+ * Constructs and returns the column definition for the row number column
+ * Column definition contains the row number column's row type and
+ * the error object containing the title, error messages and alt text
+ *
+ * @param {Object} rowErrors - object containing metadata of errors in the row
+ * @param {String} rowTitle - value of the cell which has the scope of the row/rowheader
+ * @returns
+ */
 export function getRowNumberErrorColumnDef(rowErrors, rowTitle) {
     const { title, messages } = rowErrors;
 
@@ -105,7 +139,7 @@ export function getRowNumberErrorColumnDef(rowErrors, rowTitle) {
     );
 
     return {
-        type: COLUMN_TYPE,
+        type: ROW_NUMBER_COLUMN_TYPE,
         typeAttributes: {
             error: { title, messages, alternativeText },
         },