lightning-base-components 1.14.2-alpha → 1.14.6-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,167 @@ 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
      *
-     * @param {LightningDatatable} dt
-     * @param {RenderManagerConfig} config
+     * 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
      */
-    configure(dt, config) {
-        normalizeAndProcessConfig(dt, this, config);
+    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 {Object} state - datatable state
+     * @param {Event} event - scroll event
+     */
+    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 number of rendered rows
+     *
+     * @param {Object} state - datatable state
+     * @returns {Object} object with firstIndex and lastIndex of rendered range of rows
+     */
+    getRenderedRange(state) {
+        const { firstVisibleIndex, bufferSize, renderedRowCount, rows } = state;
+        const firstIndex = Math.max(firstVisibleIndex - bufferSize, 0);
+        let lastIndex = firstVisibleIndex - bufferSize + renderedRowCount;
+        // without this, we may render too few rows when there
+        // aren't enough rows for virtualization to be needed
+        if (
+            renderedRowCount === rows.length &&
+            lastIndex <= rows.length - bufferSize
+        ) {
+            lastIndex = renderedRowCount - 1;
+        }
+        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, 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 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 (
+                        rowCountWithBuffer > state.renderedRowCount ||
+                        state.virtualize
+                    ) {
+                        this.updateRenderedRows(state, rowCountWithBuffer);
                     }
                 }
             });
@@ -107,13 +238,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 +257,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/{datatableResizeObserver.js → resizeObserver.js}

@@ -1,44 +1,25 @@
 import { LightningResizeObserver } from 'lightning/resizeObserver';
-import { isTableRenderedVisible } from './resizer';
+import { isTableRenderedVisible } from './columnResizer';
 import { ResizeSensor } from './resizeSensor';
 import { debounce } from 'lightning/inputUtils';
 import { getColumns } from './columns';
 
 const WIDTH_OBSERVER_SELECTOR = '.dt-width-observer';
 
-function createResizeSensor(
-    dtObserver,
-    columnWidthManager,
-    template,
-    state,
-    widthsData,
-    resizeTarget
-) {
-    return new ResizeSensor(
-        resizeTarget,
-        debounce(() => {
-            // since this event handler is debounced, it might be the case that at the time the handler is called,
-            // the element is disconnected (this.hasDetachedListeners)
-            // the scroll event which the ResizeSensor uses can happen when table is hidden (as in console when switching tabs)
-            // and hence the need for isTableRenderedVisible check
-            if (dtObserver.isConnected() && isTableRenderedVisible(template)) {
-                columnWidthManager.adjustColumnsSizeAfterResize(
-                    template,
-                    getColumns(state),
-                    widthsData
-                );
-            }
-        }, 200)
-    );
-}
-
 export class LightningDatatableResizeObserver {
     _connected = false;
     _resizeObserverAvailable = typeof ResizeObserver === 'function';
 
+    /**
+     * Depending on the browser/availability, this will create either a (standard)
+     * ResizeObserver via LightningResizeObserver or fallback to the ResizeSensor
+     */
     constructor(template, state, widthsData, columnWidthManager) {
         const resizeTarget = template.querySelector(WIDTH_OBSERVER_SELECTOR);
 
+        // If ResizeObserver is available on the browser, create one and begin observing for changes
+        // Calculate and modify the column widths when there are changes to the dimensions
+        // and when the table is rendered and visible on screen
         if (this._resizeObserverAvailable) {
             this._resizeObserver = new LightningResizeObserver(() => {
                 if (this._connected && isTableRenderedVisible(template)) {
@@ -51,8 +32,8 @@ export class LightningDatatableResizeObserver {
             });
             this._resizeObserver.observe(resizeTarget);
         } else {
-            // fallback behavior for IE11 and Safari using existing resize sensor functionality (less performant)
-            this._resizeSensor = createResizeSensor(
+            // fallback behavior for IE11 using existing resize sensor functionality (less performant)
+            this._resizeSensor = createResizeSensorForIE11(
                 this,
                 columnWidthManager,
                 template,
@@ -65,6 +46,7 @@ export class LightningDatatableResizeObserver {
         this._connected = true;
     }
 
+    // Begins observing the specified element for changes in dimension
     observe(template) {
         const targetElement = template.querySelector(WIDTH_OBSERVER_SELECTOR);
 
@@ -77,6 +59,7 @@ export class LightningDatatableResizeObserver {
         this._connected = true;
     }
 
+    // Stops observing any/all observed elements for changes in dimension
     disconnect() {
         if (this._resizeObserver) {
             this._resizeObserver.disconnect();
@@ -92,3 +75,37 @@ export class LightningDatatableResizeObserver {
         return this._connected;
     }
 }
+
+/**
+ * Creates a ResizeSensor which is used to observe the dimensions of an element.
+ *
+ * This ResizeSensor is only used in the event that the standard ResizeObserver
+ * is NOT available on the browser.
+ * Currently only IE11 does not support the ResizeObserver. We should be able to
+ * remove this once we fully drop support of IE11.
+ */
+function createResizeSensorForIE11(
+    dtObserver,
+    columnWidthManager,
+    template,
+    state,
+    widthsData,
+    resizeTarget
+) {
+    return new ResizeSensor(
+        resizeTarget,
+        debounce(() => {
+            // since this event handler is debounced, it might be the case that at the time the handler is called,
+            // the element is disconnected (this.hasDetachedListeners)
+            // the scroll event which the ResizeSensor uses can happen when table is hidden (as in console when switching tabs)
+            // and hence the need for isTableRenderedVisible check
+            if (dtObserver.isConnected() && isTableRenderedVisible(template)) {
+                columnWidthManager.adjustColumnsSizeAfterResize(
+                    template,
+                    getColumns(state),
+                    widthsData
+                );
+            }
+        }, 200)
+    );
+}

package/src/lightning/datatable/resizeSensor.js

@@ -1,3 +1,11 @@
+/**
+ * IMPORTANT: This ResizeSensor is only used in the event that the standard ResizeObserver
+ * is NOT available on the browser.
+ *
+ * Currently only IE11 does not support the ResizeObserver. We should be able to
+ * remove this once we fully drop support of IE11.
+ */
+
 /**
  * Based on Marc J. Schmidt library: https://github.com/marcj/css-element-queries/blob/master
  */

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),
             },
         })
     );