lightning-base-components 1.14.6-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;
@@ -31,17 +32,6 @@ 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,
@@ -81,7 +71,13 @@ export class RenderManager {
      * @param {RenderManagerConfig} config - set of properties used for render management
      */
     configure(state, getWrapperHeight, config) {
-        const { viewportRendering, rowHeight, virtualize, bufferSize } = config;
+        const {
+            viewportRendering,
+            rowHeight,
+            virtualize,
+            bufferSize,
+            fixedHeight,
+        } = config;
         setVirtualize(state, virtualize);
 
         if (normalizeBoolean(viewportRendering) || state.virtualize) {
@@ -93,6 +89,7 @@ export class RenderManager {
             'non-negative',
             DEFAULT_BUFFER_SIZE
         );
+        state.fixedHeight = normalizeBoolean(fixedHeight);
         if (typeof rowHeight === 'number') {
             state.rowHeight = rowHeight;
             this.threshold = ROW_THRESHOLD * state.rowHeight;
@@ -157,9 +154,42 @@ export class RenderManager {
      * @returns {Object} object with firstIndex and lastIndex of rendered range of rows
      */
     getRenderedRange(state) {
-        const { firstVisibleIndex, bufferSize, renderedRowCount, rows } = 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 (
@@ -224,6 +254,8 @@ export class RenderManager {
                     const rowCountWithBuffer =
                         this.getRowCountWithBuffer(state);
 
+                    resetRowHeights(state);
+
                     if (
                         rowCountWithBuffer > state.renderedRowCount ||
                         state.virtualize

package/src/lightning/datatable/resizeSensor.js

@@ -40,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) {
@@ -73,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) {
@@ -192,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]

package/src/lightning/datatable/rows.js

@@ -76,8 +76,7 @@ export function resolveRowClassNames(row) {
  * @param {object} state - data table state
  * @param {string} rowKeyValue - computed id for the row
  * @param {string} colKeyValue - computed id for the column
- *
- * @return {object} The user row that its related to the action.
+ * @returns {object} The user row that its related to the action.
  */
 export function getUserRowByCellKeys(state, rowKeyValue, colKeyValue) {
     const rowIndex = state.indexes[rowKeyValue][colKeyValue][0];

package/src/lightning/datatable/sort.js

@@ -10,8 +10,8 @@ const VALID_SORT_DIRECTIONS = {
  * Determines if the supplied sort direction is valid.
  * Refer to `VALID_SORT_DIRECTIONS` for valid solid directions.
  *
- * @param {string} value The sort direction to validate
- * @return {boolean} Whether the supplied sort direction is valid
+ * @param {String} value The sort direction to validate
+ * @returns {Boolean} Whether the supplied sort direction is valid
  */
 export function isValidSortDirection(value) {
     return !!VALID_SORT_DIRECTIONS[value];
@@ -22,7 +22,7 @@ export function isValidSortDirection(value) {
  * the default sort direction is applied first. Clicking again reverses it
  *
  * @param {Object} state The current datatable state
- * @return {string} The default sort direction
+ * @returns {String} The default sort direction
  */
 export function getDefaultSortDirection(state) {
     return state.defaultSortDirection;
@@ -33,7 +33,7 @@ export function getDefaultSortDirection(state) {
  * the default sort direction is applied first. Clicking again reverses it
  *
  * @param {Object} state The current datatable state
- * @param {string} value The value to update the default sort direction to
+ * @param {String} value The value to update the default sort direction to
  */
 export function setDefaultSortDirection(state, value) {
     assert(
@@ -51,7 +51,7 @@ export function setDefaultSortDirection(state, value) {
  * Gets the current sort direction
  *
  * @param {Object} state The current datatable state
- * @return {string} The current sort direction
+ * @returns {String} The current sort direction
  */
 export function getSortedDirection(state) {
     return state.sortedDirection;
@@ -64,7 +64,7 @@ export function getSortedDirection(state) {
  * `sortedDirection` will be `undefined`
  *
  * @param {Object} state The current datatable state
- * @param {string} value The value to update the sort direction to
+ * @param {String} value The value to update the sort direction to
  */
 export function setSortedDirection(state, value) {
     assert(
@@ -81,7 +81,7 @@ export function setSortedDirection(state, value) {
  * of a given column in the datatable
  *
  * @param {Object} state The current datatable state
- * @return {string} The current sort value
+ * @returns {String} The current sort value
  */
 export function getSortedBy(state) {
     return state.sortedBy;
@@ -94,7 +94,7 @@ export function getSortedBy(state) {
  * to `undefined`
  *
  * @param {Object} state The current datatable state
- * @param {string} value The value to update the sort state to
+ * @param {String} value The value to update the sort state to
  */
 export function setSortedBy(state, value) {
     if (typeof value === 'string') {

package/src/lightning/datatable/state.js

@@ -3,7 +3,8 @@
  * The state object is further manipulated while it is passed around by datatable
  *
  * TODO: Check to see if there are other items that need to be added to the default state
- * @returns {Object} - intial state of the datatable
+ *
+ * @returns {Object} Intial state of the datatable
  */
 export const getDefaultState = function () {
     return {
@@ -62,6 +63,12 @@ export const getDefaultState = function () {
         rowHeight: 30.5,
         renderedRowCount: 0,
         firstVisibleIndex: 0, // first row that should be visible in viewport
+        fixedHeight: false, // by default, assume that not all rows are same height
+        heightCache: {}, // cache of row heights
+        offsets: [0],
+        offsetRanges: [],
+        firstRowOffset: 0, // how many pixels scrollTop is from top of first visible row
+        tableHeight: 0,
 
         // inline edit
         inlineEdit: {

package/src/lightning/datatable/tree.js

@@ -1,6 +1,13 @@
 import { getColumns } from './columns';
 import { isTreeType } from './types';
 
+/**
+ * Retrieves the default values for the tree state indicator field names.
+ * These values are used to make logic decisions later and may be updated
+ * during normal operation.
+ *
+ * @returns {Object} The default tree state indicator field names
+ */
 export function getTreeStateIndicatorFieldNames() {
     return {
         children: 'hasChildren',
@@ -11,6 +18,12 @@ export function getTreeStateIndicatorFieldNames() {
     };
 }
 
+/**
+ * Determines if any of the columns in the datatable are of a tree-type.
+ *
+ * @param {Object} state The datatable state
+ * @returns {Boolean} Whether any of the columns are of a tree-type
+ */
 export function hasTreeDataType(state) {
     const columns = getColumns(state);
     return columns.some((column) => {
@@ -18,6 +31,12 @@ export function hasTreeDataType(state) {
     });
 }
 
+/**
+ * Retrieves the first tree-type column from the state.
+ *
+ * @param {Object} state The datatable state
+ * @returns {Object} The first tree-type column, else `null`
+ */
 export function getStateTreeColumn(state) {
     const columns = getColumns(state);
     for (let i = 0; i < columns.length; i++) {
@@ -28,6 +47,12 @@ export function getStateTreeColumn(state) {
     return null;
 }
 
+/**
+ * Dispatches an event when a row is toggled to be expanded or collapsed.
+ *
+ * @param {String} rowKeyValue The row key being acted upon
+ * @param {Boolean} expanded The current expand/collapse state of the row
+ */
 export function fireRowToggleEvent(rowKeyValue, expanded) {
     const customEvent = new CustomEvent('privatetogglecell', {
         bubbles: true,

package/src/lightning/datatable/types.js

@@ -102,35 +102,66 @@ const EDITABLE_STANDARD_TYPES = {
     date: true,
 };
 
+/**
+ * Determines if a supplied type is a valid datatable type.
+ *
+ * @param {String} typeName The type to validate
+ * @returns {Boolean} Whether the supplied type is valid
+ */
 export function isValidType(typeName) {
     return !!STANDARD_TYPES[typeName];
 }
 
+/**
+ * Determines if a supplied type is a tree type.
+ *
+ * @param {String} typeName The type to validate
+ * @returns {Boolean} Whether the supplied type is a tree type
+ */
 export function isTreeType(typeName) {
     return typeName === 'tree';
 }
 
+/**
+ * Determines if a supplied type is valid for a tree type datatable.
+ *
+ * @param {String} typeName The type to validate
+ * @returns {Boolean} Whether the supplied type is valid for a tree
+ */
+export function isValidTypeForTree(typeName) {
+    return !!TREE_SUPPORTED_TYPES[typeName];
+}
+
+/**
+ * Retrieves the attributes for a given type. Additionally, verifies
+ * the supplied type is valid.
+ *
+ * @param {String} typeName The type to get the attributes for
+ * @returns {Array} An array of attributes for the supplied type
+ */
 export function getAttributesNames(typeName) {
     assert(
         isValidType(typeName),
-        `your are trying to access an invalid type (${typeName})`
+        `You are trying to access an invalid type (${typeName})`
     );
-
-    return Array.isArray(STANDARD_TYPES[typeName])
-        ? STANDARD_TYPES[typeName]
-        : [];
-}
-
-export function isValidTypeForTree(dataType) {
-    return !!TREE_SUPPORTED_TYPES[dataType];
+    return getStandardTypeAttributesNames(typeName);
 }
 
+/**
+ * Retrieves the attributes for a given type.
+ *
+ * @param {String} typeName The type to get the attributes for
+ * @returns {Array} An array of attributes for the supplied type
+ */
 function getStandardTypeAttributesNames(typeName) {
     return Array.isArray(STANDARD_TYPES[typeName])
         ? STANDARD_TYPES[typeName]
         : [];
 }
 
+/**
+ * A class for handling valid datatable types.
+ */
 export default class DatatableTypes {
     privateCustomTypes = {};
     isValidTypeForTree = isValidTypeForTree;
@@ -156,6 +187,13 @@ export default class DatatableTypes {
         }
     }
 
+    /**
+     * Retrieves a type. If the specified type is not a custom type,
+     * lookup the type in our standard types. Otherwise, return undefined.
+     *
+     * @param {String} typeName The type to retrieve
+     * @returns {Object | Undefined} The type metadata
+     */
     getType(typeName) {
         if (this.privateCustomTypes[typeName]) {
             return this.privateCustomTypes[typeName];
@@ -169,6 +207,12 @@ export default class DatatableTypes {
         return undefined;
     }
 
+    /**
+     * Retrieves a custom type's edit template if it exists.
+     *
+     * @param {String} typeName The custom type to retrieve
+     * @returns {Object | Undefined} The custom type's edit template
+     */
     getCustomTypeEditTemplate(typeName) {
         if (this.privateCustomTypes[typeName]) {
             return this.privateCustomTypes[typeName].editTemplate;
@@ -176,10 +220,22 @@ export default class DatatableTypes {
         return undefined;
     }
 
+    /**
+     * Determines if a type is a valid custom or standard type.
+     *
+     * @param {String} typeName The type to validate
+     * @returns {Boolean} Whether the type is valid
+     */
     isValidType(typeName) {
         return !!this.getType(typeName);
     }
 
+    /**
+     * Determines if a given type is editable.
+     *
+     * @param {String} typeName The type to test
+     * @returns {Boolean} Whether the type is editable
+     */
     isEditableType(typeName) {
         return (
             !!EDITABLE_STANDARD_TYPES[typeName] ||
@@ -187,12 +243,24 @@ export default class DatatableTypes {
         );
     }
 
+    /**
+     * Determines if a given type is a non-standard type.
+     *
+     * @param {String} typeName The type to test
+     * @returns {Boolean} Whether the type is a non-standard type
+     */
     isCustomType(typeName) {
         return (
             this.getType(typeName) && this.getType(typeName).type === 'custom'
         );
     }
 
+    /**
+     * Determines whether or not a given custom type is using a standard cell layout.
+     *
+     * @param {String} typeName The custom type to test
+     * @returns {Boolean} Whether the custom type is using a standard cell layout
+     */
     isStandardCellLayoutForCustomType(typeName) {
         return (
             this.isCustomType(typeName) &&

package/src/lightning/datatable/utils.js

@@ -1,8 +1,4 @@
-export const isObjectLike = function (value) {
-    return typeof value === 'object' && value !== null;
-};
-
-const proto = {
+const CLASSSET_PROTOTYPE = {
     add(className) {
         if (typeof className === 'string') {
             this[className] = true;
@@ -24,32 +20,59 @@ const proto = {
     },
 };
 
+/**
+ * Determines if a given value is object-like.
+ *
+ * @param {*} value Any value to check for object-like status
+ * @returns {Boolean} Whether the value is object-like
+ */
+export const isObjectLike = function (value) {
+    return typeof value === 'object' && value !== null;
+};
+
+/**
+ * Creates an object of CSS class names based on a given config.
+ * Then, attaches an interface for managing the classes.
+ *
+ * @param {String | Object} config The initial class configuration
+ * @returns An interface, as defined in the `proto` method.
+ */
 export const classSet = function (config) {
     if (typeof config === 'string') {
         const key = config;
         config = {};
         config[key] = true;
     }
-    return Object.assign(Object.create(proto), config);
+    return Object.assign(Object.create(CLASSSET_PROTOTYPE), config);
 };
 
+/**
+ * Clamps a value between a minimum and maximum value
+ *
+ * @param {Number} num The input number
+ * @param {Number} min The minimum value the number can be
+ * @param {Number} max The maximum value the number can be
+ * @returns The clamped number
+ */
 export const clamp = function (num, min, max) {
     return num <= min ? min : num >= max ? max : num;
 };
 
 /**
- * Tests if the value passed in is a value greater than 0
- * @param {Integer} value - value to test
- * @returns {Boolean} - true if value is > 0
+ * Tests if the value passed in is a value greater than 0.
+ *
+ * @param {Integer} value Value to test
+ * @returns {Boolean} Whether the value is greater than 0
  */
 export const isPositiveInteger = function (value) {
     return /^[0-9]*[1-9][0-9]*$/.test(value);
 };
 
 /**
- * Tests if the value passed in is 0 or a number greater than 0
- * @param {Integer} value - value to test
- * @returns {Boolean} - true if value is >= 0
+ * Tests if the value passed in is 0 or a number greater than 0.
+ *
+ * @param {Integer} value Value to test
+ * @returns {Boolean} Whether the value is greater than or equal to 0
  */
 export const isNonNegativeInteger = function (value) {
     return /^\d+$/.test(value);
@@ -62,11 +85,11 @@ export const isNonNegativeInteger = function (value) {
  *     b. numberType - non-negative: if value >= 0
  * If the value fails the test, the fallback value is returned
  *
- * @param {String} attrName - name of attribute to normalize
- * @param {Integer/String} value - value to normalize
- * @param {String} numberType - number type to validate against: positive / non-negative
- * @param {Integer} fallback - value to return if validation fails
- * @returns {Integer} - Returns normalized value if validation passes; else returns fallback
+ * @param {String} attrName Name of attribute to normalize
+ * @param {Integer | String} value Value to normalize
+ * @param {String} numberType Number type to validate against: positive / non-negative
+ * @param {Integer} fallback Value to return if validation fails
+ * @returns {Integer} Returns normalized value if validation passes; else returns fallback
  */
 export function normalizeNumberAttribute(
     attrName,
@@ -98,11 +121,14 @@ export function normalizeNumberAttribute(
     return fallback;
 }
 
-// TODO: move into scroller-specific utility when more scroll-related functionality
-// needs to be shared between libraries
 /**
- * Utility for calculating the scroll offset
- * @param {HTMLElement} el - target element of the scroll
+ * Utility for calculating the scroll offset.
+ *
+ * TODO: move into scroller-specific utility when more scroll-related functionality
+ * needs to be shared between libraries.
+ *
+ * @param {HTMLElement} el Target element of the scroll
+ * @returns {Number} The scroll offset from the table's end
  */
 export function getScrollOffsetFromTableEnd(el) {
     return (
@@ -111,9 +137,10 @@ export function getScrollOffsetFromTableEnd(el) {
 }
 
 /**
- * Utility for converting arrays and plain objects to style strings
- * @param {Array|Object} style
- * @returns {string} representing array/object as a string
+ * Utility for converting arrays and plain objects to style strings.
+ *
+ * @param {Array | Object} style The CSS style array/object
+ * @returns {String} Representing array/object as a string
  */
 export function styleToString(style) {
     if (!Array.isArray(style)) {