lightning-base-components 1.14.2-alpha → 1.14.3-alpha

package/src/lightning/datatable/inlineEditShared.js

@@ -0,0 +1,24 @@
+/**
+ * Retrieves the dirty/unsaved value of a cell that resulted from an inline
+ * edit change. If no change was made on the cell, this function
+ * returns `undefined`.
+ *
+ * @param {Object} state - datatable's state object
+ * @param {String} rowKeyValue - computed id for the row
+ * @param {String} colKeyValue - computed id for the column
+ * @returns {String} The dirty/unsaved value of the cell.
+ *                   If no change was made, this returns `undefined`
+ */
+export function getDirtyValueFromCell(state, rowKeyValue, colKeyValue) {
+    const dirtyValues = state.inlineEdit.dirtyValues;
+
+    if (
+        dirtyValues &&
+        dirtyValues[rowKeyValue] &&
+        dirtyValues[rowKeyValue][colKeyValue]
+    ) {
+        return dirtyValues[rowKeyValue][colKeyValue];
+    }
+
+    return undefined;
+}

package/src/lightning/datatable/keyboard.js

@@ -1306,7 +1306,7 @@ export function updateRowNavigationMode(hadTreeDataTypePreviously, state) {
 
 /***************************** HELPER FUNCTIONS *****************************/
 
-function isCellElement(tagName, role) {
+export function isCellElement(tagName, role) {
     return (
         SELECTORS.cell.default.includes(tagName) ||
         SELECTORS.cell.roleBased.includes(role)

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,27 @@ 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;
+export function normalizeVirtualization(value) {
+    return normalizeString(value, {
+        fallbackValue: '', //no virtualization enabled
+        validValues: [VERTICAL_VIRTUALIZATION],
+    });
+}
 
-    if (viewportRendering && typeof viewportRendering === 'boolean') {
-        renderManager.initializeResizeObserver(dt);
-    }
+export function getDTRows() {
+    return this.state.rows;
+}
 
-    if (typeof rowHeight === 'number') {
-        renderManager.rowHeight = rowHeight;
-        renderManager.threshold = calculateThreshold(rowHeight);
-    }
+export function getDTRenderedRowCount() {
+    return this._renderedRowCount;
+}
 
-    return renderManager;
+export function setDTRenderedRowCount(renderedRowCount) {
+    this._renderedRowCount = renderedRowCount;
 }
 
-function calculateThreshold(rowHeight) {
-    return 2 * BUFFER_ROW_COUNT * rowHeight;
+export function getDTWrapperHeight() {
+    return this.template.querySelector('.slds-scrollable_x').offsetHeight;
 }
 
 function getDefaultPreviousInfo() {
@@ -57,6 +47,13 @@ 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
+ */
+
 /**
  * Handles any custom rendering in datatable.
  *
@@ -66,38 +63,211 @@ 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();
     }
 
     /**
-     *
-     * @param {LightningDatatable} dt
+     * 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
      */
-    configure(dt, config) {
-        normalizeAndProcessConfig(dt, this, config);
+    configure(
+        getRows,
+        getWrapperHeight,
+        renderedRowCount,
+        setRenderedRowCount,
+        config
+    ) {
+        const { viewportRendering, rowHeight, virtualize, bufferSize } = config;
+        this.virtualize = normalizeVirtualization(virtualize);
+        if (normalizeBoolean(viewportRendering) || this.virtualize) {
+            this.initializeResizeObserver(
+                getRows,
+                getWrapperHeight,
+                renderedRowCount,
+                setRenderedRowCount
+            );
+        }
+        this.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;
+        }
+    }
+
+    /**
+     * 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 {Array} rows
+     * @param {Function} setRenderedRowCount
+     * @param {Node} gridContainer
+     * @param {Boolean} forceUpdate
+     */
+    updateViewportRendering(
+        rows,
+        setRenderedRowCount,
+        gridContainer,
+        forceUpdate
+    ) {
+        if (this.hasDataChanged(rows) || forceUpdate) {
+            this.updateRenderedRows(
+                rows,
+                setRenderedRowCount,
+                this.getRowCountWithBuffer()
+            );
+        } else if (
+            this.previousCache.totalRowCount < rows.length &&
+            this.isWithinThreshold(gridContainer)
+        ) {
+            this.updateRenderedRows(
+                rows,
+                setRenderedRowCount,
+                this.previousCache.renderedRowCount +
+                    this.getRowCountWithBuffer()
+            );
+        } else {
+            this.updateRenderedRows(
+                rows,
+                setRenderedRowCount,
+                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 {Array} rows
+     * @param {Number} currentLength
+     * @param {Function} setRenderedRowCount
+     * @param {Event} event - scroll event
+     */
+    handleScroll(rows, currentLength, setRenderedRowCount, event) {
+        if (
+            this.isWithinThreshold(event.target.firstChild) &&
+            currentLength < rows.length
+        ) {
+            this.updateRenderedRows(
+                rows,
+                setRenderedRowCount,
+                currentLength + this.getRowCountWithBuffer()
+            );
+        }
+    }
+
+    /**
+     * 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
+     * @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();
+
+        return { firstIndex, lastIndex };
     }
 
+    /**
+     * Updates internal cache of row counts and first key
+     *
+     * @param {Array} rows
+     * @param {Function} setRenderedRowCount
+     * @param {Number} rowCount
+     */
+    updateRenderedRows(rows, setRenderedRowCount, rowCount) {
+        const totalRows = rows.length;
+        const normalizedRowCount = rowCount
+            ? Math.min(rowCount, totalRows)
+            : totalRows;
+        setRenderedRowCount(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
+     */
+    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 {Function} getRows
+     * @param {Function} getWrapperHeight
+     * @param {Function} getRenderedRowCount
+     * @param {Function} setRenderedRowCount
      */
-    initializeResizeObserver(dt) {
+    initializeResizeObserver(
+        getRows,
+        getWrapperHeight,
+        getRenderedRowCount,
+        setRenderedRowCount
+    ) {
         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, we need to update
-                    // the rendered rows so users can continue scrolling
+                    // 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();
-                    if (rowCountWithBuffer > dt._renderedRowCount) {
-                        this.updateRenderedRows(dt, rowCountWithBuffer);
+                    if (
+                        rowCountWithBuffer > getRenderedRowCount() ||
+                        this.virtualize
+                    ) {
+                        this.updateRenderedRows(
+                            getRows(),
+                            setRenderedRowCount,
+                            rowCountWithBuffer
+                        );
                     }
                 }
             });
@@ -107,13 +277,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 +296,49 @@ 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;
+        return Math.ceil(this.wrapperHeight / this.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() {
+        // 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;
     }
 
     /**
-     * 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),
             },
         })
     );