lightning-base-components 1.14.3-alpha → 1.14.7-alpha

package/src/lightning/datatable/renderManager.js

@@ -1,6 +1,7 @@
 import { getScrollOffsetFromTableEnd, normalizeNumberAttribute } from './utils';
 import { LightningResizeObserver } from 'lightning/resizeObserver';
 import { normalizeBoolean, normalizeString } from 'lightning/utilsPrivate';
+import { resetRowHeights } from './virtualization';
 
 export const DEFAULT_ROW_HEIGHT = 30.5;
 const DEFAULT_BUFFER_SIZE = 5;
@@ -16,23 +17,15 @@ 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() {
@@ -52,6 +45,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 +58,41 @@ 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
-    ) {
-        const { viewportRendering, rowHeight, virtualize, bufferSize } = config;
-        this.virtualize = normalizeVirtualization(virtualize);
-        if (normalizeBoolean(viewportRendering) || this.virtualize) {
-            this.initializeResizeObserver(
-                getRows,
-                getWrapperHeight,
-                renderedRowCount,
-                setRenderedRowCount
-            );
+    configure(state, getWrapperHeight, config) {
+        const {
+            viewportRendering,
+            rowHeight,
+            virtualize,
+            bufferSize,
+            fixedHeight,
+        } = config;
+        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
         );
+        state.fixedHeight = normalizeBoolean(fixedHeight);
         if (typeof rowHeight === 'number') {
-            this.rowHeight = rowHeight;
-            this.threshold = ROW_THRESHOLD * this.rowHeight;
+            state.rowHeight = rowHeight;
+            this.threshold = ROW_THRESHOLD * state.rowHeight;
         }
     }
 
@@ -117,39 +104,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,62 +130,90 @@ 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
+     * first visible index, buffer size and number of rendered rows
      *
-     * @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,
+            rows,
+            fixedHeight,
+            rowHeight,
+            heightCache,
+        } = state;
+
+        const firstIndex = Math.max(firstVisibleIndex - bufferSize, 0);
+        let lastIndex = firstVisibleIndex - bufferSize + renderedRowCount;
+        const firstVisibleKey =
+            rows[firstVisibleIndex] && rows[firstVisibleIndex].key;
+
+        if (!fixedHeight && heightCache[firstVisibleKey]) {
+            let i = firstVisibleIndex;
+            let currentHeight = 0;
+            const knownRowHeight = rows[i] && heightCache[rows[i].key];
+            // loop through rows until we find last row based on wrapper height
+            while (knownRowHeight && currentHeight < this.wrapperHeight) {
+                currentHeight += knownRowHeight;
+                i = i + 1;
+            }
+            if (currentHeight >= this.wrapperHeight) {
+                // row heights were measured; i represents last visible index
+                lastIndex = i + bufferSize - 1;
+            } else {
+                // row heights not yet measured, i is last visible index with known height
+                // guess lastIndex based on default row height
+                const extraRowEstimate =
+                    (this.wrapperHeight - currentHeight) / rowHeight;
+                lastIndex = i + extraRowEstimate + bufferSize;
+            }
+        }
 
+        // 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 {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 +228,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 +240,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 +251,16 @@ 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);
+
+                    resetRowHeights(state);
+
                     if (
-                        rowCountWithBuffer > getRenderedRowCount() ||
-                        this.virtualize
+                        rowCountWithBuffer > state.renderedRowCount ||
+                        state.virtualize
                     ) {
-                        this.updateRenderedRows(
-                            getRows(),
-                            setRenderedRowCount,
-                            rowCountWithBuffer
-                        );
+                        this.updateRenderedRows(state, rowCountWithBuffer);
                     }
                 }
             });
@@ -301,19 +294,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/{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
  */
@@ -32,7 +40,8 @@ class EventQueue {
 
 /**
  * Get element size
- * @param {HTMLElement} element - element to return the size.
+ *
+ * @param {HTMLElement} element Element to return the size.
  * @returns {Object} {width, height}
  */
 function getElementSize(element) {
@@ -65,9 +74,10 @@ function createResizeSensor() {
 }
 
 /**
+ * Attaches the resize event to an element
  *
- * @param {HTMLElement} element - element to listen resize.
- * @param {Function}    resizeListener - resize event listener.
+ * @param {HTMLElement} element Element to listen resize
+ * @param {Function} resizeListener Resize event listener
  */
 function attachResizeEvent(element, resizeListener) {
     if (!element) {
@@ -184,6 +194,12 @@ function attachResizeEvent(element, resizeListener) {
     requestAnimationFrame(reset);
 }
 
+/**
+ * Removes a resize event from an element.
+ *
+ * @param {HTMLElement} element Element to remove resize listener from
+ * @param {Event} event The event to remove
+ */
 function detach(elem, ev) {
     if (!elem) {
         return;

package/src/lightning/datatable/rowSelection.js

@@ -497,7 +497,7 @@ export function resetSelectedRowsKeys(state) {
  * Returns undefined if the row key value is invalid
  *
  * @param {Object} state - the datatable state.
- * @return {String | undefined } the row key or undefined.
+ * @returns {String | undefined } the row key or undefined.
  */
 function getLastRowSelection(state) {
     const lastSelectedRowKey = state.lastSelectedRowKey;

package/src/lightning/datatable/rowSelectionShared.js

@@ -9,31 +9,27 @@
  */
 
 /**
- * Returns whether or not the row is selected using the state and the rowKeyValue
- * The state maintains the list of selected rows from which
- * this value can be retrieved.
+ * Returns whether or not the row is selected using the state and the `rowKeyValue`.
+ * The state maintains the list of selected rows from which this value can be retrieved.
  *
- * @param {Object} state - datatable state object
- * @param {String} rowKeyValue
- * @returns
+ * @param {Object} state Datatable state object
+ * @param {String} rowKeyValue The row key value to lookup
+ * @returns {Boolean} Whether the row is currently selected
  */
 export function isSelectedRow(state, rowKeyValue) {
     return !!state.selectedRowsKeys[rowKeyValue];
 }
 
 /**
- * Returns whether the row (whose row key value is specified)
- * should be disabled or not.
- * Should not disable if the row is selected.
- * If the particular row is not selected, the row should be disabled
- * when max-row-selection > 1 and the selection limit is reached
+ * Returns whether the row (whose row key value is specified) should be disabled or not.
+ * Should not disable if the row is selected. If the particular row is not selected, the
+ * row should be disabled when `max-row-selection` > 1 and the selection limit is reached.
  *
- * Note: Do not disable selection when max-row-selection = 1 and
- * a row has been selected.
+ * NOTE: Do not disable selection when `max-row-selection` is 1 and a row has been selected.
  *
- * @param {Object} state
- * @param {String} rowKeyValue
- * @returns {Boolean} whether the row should be disabled or not
+ * @param {Object} state Datatable state object
+ * @param {String} rowKeyValue The row key value to lookup
+ * @returns {Boolean} Whether the row should be disabled or not
  */
 export function isDisabledRow(state, rowKeyValue) {
     if (!isSelectedRow(state, rowKeyValue)) {
@@ -51,11 +47,10 @@ export function isDisabledRow(state, rowKeyValue) {
 
 /**
  * Returns which input type to use for row selection.
- * If max-row-selection = 1, use radio buttons,
- * otherwise, use checkboxes.
+ * If `max-row-selection` is 1, use radio buttons. Otherwise, use checkboxes.
  *
- * @param {Object} state - datatable's state object
- * @returns
+ * @param {Object} state Datatable state object
+ * @returns {String} `radio` is only one row is allowed to be selected, otherwise `checkbox`
  */
 export function getRowSelectionInputType(state) {
     if (getMaxRowSelection(state) === 1) {
@@ -64,14 +59,32 @@ export function getRowSelectionInputType(state) {
     return 'checkbox';
 }
 
+/**
+ * Retrieves the maximum number of rows that can be selected from state.
+ *
+ * @param {Object} state Datatable state object
+ * @returns {Integer} The maximum rows that can be selected
+ */
 export function getMaxRowSelection(state) {
     return state.maxRowSelection;
 }
 
+/**
+ * Determines the number of rows currently selected.
+ *
+ * @param {Object} state Datatable state object
+ * @returns {Integer} The number of currently selected rows
+ */
 export function getCurrentSelectionLength(state) {
     return getSelectedRowsKeys(state).length;
 }
 
+/**
+ * Retrieves the row keys that are currently selected.
+ *
+ * @param {Object} state Datatable state object
+ * @returns {Array} An array of the row keys that are currently selected
+ */
 export function getSelectedRowsKeys(state) {
     return Object.keys(state.selectedRowsKeys).filter(
         (key) => state.selectedRowsKeys[key]