lightning-base-components 1.14.6-alpha → 1.15.1-alpha

package/src/lightning/datatable/templates/div/div.html

@@ -35,7 +35,10 @@
                     aria-label={ariaLabel}
                     aria-labelledby={ariaLabelledBy}
                     aria-rowcount={ariaRowCount}
-                    aria-colcount={ariaColCount}>
+                    aria-colcount={ariaColCount}
+                    data-num-rows={data.length}
+                    data-num-selected-rows={selectedRows.length}
+                    data-last-rendered-row={_lastRenderedRow}>
                     <template if:false={hasValidKeyField}>
                         <!-- empty since keyField wasn't provided -->
                     </template>
@@ -128,7 +131,8 @@
                                     aria-posinset={row.posInSet}
                                     aria-rowindex={row.ariaRowIndex}
                                     style={row.style}
-                                    tabindex={row.tabIndex}>
+                                    tabindex={row.tabIndex}
+                                    data-row-number={row.rowNumber}>
                                         <template for:each={row.cells} for:item="cell">
                                             <template if:true={cell.isCheckbox}>
                                                 <!-- Checkbox Cell -->

package/src/lightning/datatable/templates/table/table.html

@@ -33,7 +33,9 @@
                     onfocusout={handleTableFocusOut}
                     aria-label={ariaLabel}
                     aria-labelledby={ariaLabelledBy}
-                    aria-rowcount={ariaRowCount}>
+                    data-num-rows={data.length}
+                    data-num-selected-rows={selectedRows.length}
+                    data-last-rendered-row={_lastRenderedRow}>
                     <template if:false={hasValidKeyField}>
                         <!-- empty since keyField wasn't provided TODO: Why is this here? Test and remove! -->
                     </template>
@@ -111,7 +113,8 @@
                                     aria-expanded={row.isExpanded}
                                     aria-setsize={row.setSize}
                                     aria-posinset={row.posInSet}
-                                    tabindex={row.tabIndex}>
+                                    tabindex={row.tabIndex}
+                                    data-row-number={row.rowNumber}>
                                     <template for:each={row.cells} for:item="cell">
                                         <template if:true={cell.isCheckbox}>
                                             <!-- Checkbox Cell -->

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)) {

package/src/lightning/datatable/virtualization.js

@@ -0,0 +1,319 @@
+import { styleToString } from './utils';
+
+/**
+ * sets an initial table height in the datatable state
+ *
+ * @param {Object} state - datatable state
+ */
+export function resetTableHeight(state) {
+    state.tableHeight = state.rowHeight * state.rows.length;
+}
+
+/**
+ * resets state properties relevant to virtualization
+ * rowHeights when fixedHeight is false
+ *
+ * @param {Object} state - datatable state
+ */
+export function resetRowHeights(state) {
+    state.heightCache = {};
+    state.offsets = [0];
+    state.offsetRanges = [];
+    if (state.virtualize && state.rows.length) {
+        resetTableHeight(state);
+    }
+}
+
+/**
+ * updates state properties relevant to virtualization
+ * rowHeights when fixedHeight is false
+ *
+ * @param {Node} template - the custom element root `this.template` from datatable.js
+ * @param {Object} state - datatable state
+ * @param {Array} renderedRows  - array of rows currently being rendered
+ */
+export function handleVariableRowHeights(template, state, renderedRows) {
+    const currentRange = {
+        start: renderedRows[0].rowIndex,
+        end: renderedRows[renderedRows.length - 1].rowIndex + 1,
+    };
+    let adjustFromIndex;
+    let adjustmentValue = 0;
+    let offsetRangeIndex = findOffsetRangeIndex(
+        state.offsetRanges,
+        currentRange.start
+    );
+
+    renderedRows.forEach((row) => {
+        if (!state.heightCache[row.key]) {
+            // need to get row actual element so we can find its height
+            const rowElement = template.querySelector(
+                `[data-row-key-value="${row.key}"]`
+            );
+            if (rowElement) {
+                // first rendered row needs height increased by 1 to account for missing border
+                let height = rowElement.getBoundingClientRect().height;
+                if (row.rowIndex === currentRange.start) {
+                    height++;
+                }
+                state.heightCache[row.key] = height;
+
+                // calculate estimate of row offset
+                setOffset(state, row, offsetRangeIndex, height);
+
+                // update variables used to adjust later row offsets
+                adjustmentValue += height - state.rowHeight;
+                adjustFromIndex = row.rowIndex + 2;
+            }
+        }
+    });
+    state.tableHeight += adjustmentValue;
+    updateOffsetRanges(
+        state,
+        offsetRangeIndex,
+        currentRange,
+        adjustFromIndex,
+        adjustmentValue
+    );
+    updateVirtualizeStyles(template, state, renderedRows);
+}
+
+/**
+ * uses binary search with offsets and offsetRange
+ * to determine what the first visible index should be
+ * for a given scrollTop value
+ */
+export function findFirstVisibleIndex(state, scrollTop) {
+    const { offsetRanges, offsets, rowHeight, fixedHeight, virtualize } = state;
+    if (virtualize && fixedHeight) {
+        return scrollTop / rowHeight;
+    }
+    let start = 0;
+    let end = offsetRanges.length - 1;
+
+    while (start <= end) {
+        let mid = Math.floor((start + end) / 2);
+        const prevRange = offsetRanges[mid];
+        const nextRange = offsetRanges[mid + 1];
+        const startOffset = offsets[prevRange.start];
+        const endOffset = offsets[prevRange.end];
+
+        const scrollTopAfterPrevStart = startOffset <= scrollTop;
+        const scrollTopInPrevRange =
+            scrollTopAfterPrevStart && scrollTop <= endOffset;
+        const scrollTopBeforeNextRange =
+            !nextRange || scrollTop < offsets[nextRange.start];
+        const scrollTopBetweenRanges =
+            scrollTopAfterPrevStart && scrollTopBeforeNextRange;
+
+        // check if scrollTop is in prevAdj offset values
+        // or between prevAdj and nextAdj offsetValues
+        if (scrollTopInPrevRange) {
+            // find offset in prevRange to use for firstVisibleIndex
+            return searchForOffset(state, prevRange, scrollTop);
+        } else if (scrollTopBetweenRanges) {
+            // use scrollTop and rowHeight to calculate firstVisibleIndex
+            const diff = scrollTop - endOffset;
+            const extraRows = Math.floor(diff / rowHeight);
+            state._firstRowOffset = diff % rowHeight;
+            return prevRange.end + extraRows;
+        }
+        // update start or end for next round of binary search
+        if (scrollTop < startOffset) {
+            end = mid - 1;
+        } else {
+            start = mid + 1;
+        }
+    }
+    return -1;
+}
+
+/**
+ * determines the rowIndex for given scrollTop
+ * within a provided offset range using binary search
+ * also sets firstRowOffset to correct value
+ *
+ * @param {object} range - object with start and end index for binary search
+ * @param {number} scrollTop - value to find offset rowIndex for
+ * @returns {number} representing firstVisibleIndex for given scrollTop
+ */
+function searchForOffset(state, range, scrollTop) {
+    let { start, end } = range;
+    const offsets = state.offsets;
+
+    while (start <= end) {
+        const mid = Math.floor((start + end) / 2);
+        const currentOffsetUnderScrollTop = offsets[mid] <= scrollTop;
+        const nextOffsetUnderScrollTop =
+            offsets[mid + 1] && offsets[mid + 1] <= scrollTop;
+
+        if (currentOffsetUnderScrollTop && !nextOffsetUnderScrollTop) {
+            // store how many pixels scrollTop is from top of row
+            state.firstRowOffset = scrollTop - offsets[mid];
+            return mid;
+        } else if (currentOffsetUnderScrollTop) {
+            start = mid + 1;
+        } else {
+            end = mid - 1;
+        }
+    }
+    return -1;
+}
+
+/**
+ * uses a binary search to find the offsetRange index that
+ * encompasses the provided row index, or the one immediately
+ * before if no offsetRange encompasses the provided rowIndex
+ */
+function findOffsetRangeIndex(offsetRanges, rowIndex) {
+    let start = 0;
+    let end = offsetRanges.length - 1;
+    while (start <= end) {
+        let mid = Math.floor((start + end) / 2);
+        const currentRangeStartsBeforeRowIndex =
+            offsetRanges[mid].start <= rowIndex;
+        const nextRangeStartsBeforeRowIndex =
+            offsetRanges[mid + 1] && offsetRanges[mid + 1].start <= rowIndex;
+
+        // check if rowIndex is between start of range at "mid"
+        // and start of range at "mid + 1" (or if there is no "mid + 1")
+        if (
+            currentRangeStartsBeforeRowIndex &&
+            !nextRangeStartsBeforeRowIndex
+        ) {
+            return mid;
+        } else if (currentRangeStartsBeforeRowIndex) {
+            // look for earlier offsetRanges
+            start = mid + 1;
+        } else {
+            // look for later offsetRanges
+            end = mid - 1;
+        }
+    }
+    return -1;
+}
+
+/**
+ * sets the offset value for a given row and the next
+ * based on the closest set offset value, the default
+ * row height and the height of the current row
+ *
+ * @param {object} state - datatable state
+ * @param {object} row - specific row object from state
+ * @param {number} offsetRangeIndex - index of offset range to use for row
+ * @param {number} height - height of row's node
+ */
+function setOffset(state, row, offsetRangeIndex, height) {
+    let currentRange = state.offsetRanges[offsetRangeIndex];
+    let currentOffset = state.offsets[row.rowIndex];
+    // if no offset is set for current row, estimate it
+    // based on most recent offset and default rowHeight
+    if (!currentOffset) {
+        currentOffset = 0;
+        if (currentRange) {
+            const baseOffset = state.offsets[currentRange.end];
+            const estimatedRowOffsets =
+                (row.rowIndex - currentRange.end) * state.rowHeight;
+            currentOffset = baseOffset + estimatedRowOffsets;
+            state.offsets[row.rowIndex] = currentOffset;
+        }
+    }
+    // set next offset based on current offset and height
+    state.offsets[row.rowIndex + 1] = currentOffset + height;
+}
+
+/**
+ * merges or adds new offset range and
+ * updates offsets and range values as needed
+ *
+ * @param {number} offsetRangeIndex
+ * @param {*} state - datatable state
+ * @param {object} currentRange - range for current rendered rows
+ * @param {number} adjustFromIndex  - first index to increase by rangeValue
+ * @param {number} rangeValue - amount to increase offsets after adjustFromIndex
+ */
+function updateOffsetRanges(
+    state,
+    offsetRangeIndex,
+    currentRange,
+    adjustFromIndex,
+    adjustmentValue
+) {
+    const { offsets, offsetRanges } = state;
+    let prevRange = offsetRanges[offsetRangeIndex];
+    let nextRange = offsetRanges[offsetRangeIndex + 1];
+    const overlapsWithPrevRange =
+        prevRange && checkOverlap(prevRange, currentRange);
+    const overlapsWithNextRange =
+        nextRange && checkOverlap(currentRange, nextRange);
+
+    // update remaining values in next range by
+    // adjustment value if we're overlapping it
+    if (overlapsWithNextRange && adjustmentValue) {
+        for (let i = adjustFromIndex; i <= nextRange.end; i++) {
+            offsets[i] = offsets[i] + adjustmentValue;
+        }
+    }
+
+    // update state.offsetRanges
+    if (overlapsWithPrevRange && overlapsWithNextRange) {
+        nextRange.start = prevRange.start;
+        nextRange.end = Math.max(currentRange.end, nextRange.end);
+        state.offsetRanges.splice(offsetRangeIndex, 1); // removes prevRange
+    } else if (overlapsWithPrevRange) {
+        prevRange.end = Math.max(prevRange.end, currentRange.end);
+    } else if (overlapsWithNextRange) {
+        nextRange.start = currentRange.start;
+        nextRange.end = Math.max(currentRange.end, nextRange.end);
+        // increase offsetRangeIndex; since it's values have already been updated
+        // we want to skip it when adjusting offsets in later ranges
+        offsetRangeIndex = offsetRangeIndex + 1;
+    } else {
+        state.offsetRanges.splice(offsetRangeIndex + 1, 0, currentRange);
+        // need to increase offsetRangeIndex so we don't
+        // unnecessarily add adjustmentValue to currentRange
+        offsetRangeIndex = offsetRangeIndex + 1;
+    }
+
+    // loop through every offset range after the current one
+    // and increase the offset for each index by adjustmentValue
+    if (offsetRangeIndex >= 0) {
+        for (let i = offsetRangeIndex + 1; i < offsetRanges.length; i++) {
+            const { start: rangeStart, end: rangeEnd } = offsetRanges[i];
+            for (let j = rangeStart; j <= rangeEnd; j++) {
+                offsets[j] = offsets[j] + adjustmentValue;
+            }
+        }
+    }
+}
+
+/**
+ * compares start/end of two ranges to see if the values overlap
+ * used to determine if renderedRows are part of an existent offsetRange
+ * or if a new offsetRange will need to be added
+ */
+function checkOverlap(range1, range2) {
+    return (
+        (range1.start <= range2.start && range2.start <= range1.end) ||
+        (range1.start <= range2.end && range2.end <= range1.end)
+    );
+}
+
+/**
+ * updates scrollTop and top values for rows when
+ * using virtualization with fixedHeight of false
+ */
+function updateVirtualizeStyles(template, state, renderedRows) {
+    // update scrollTop so firstVisibleIndex is correctly placed in viewport
+    const scrollerY = template.querySelector('.slds-scrollable_y');
+    scrollerY.scrollTop =
+        state.offsets[state.firstVisibleIndex] + state.firstRowOffset;
+
+    // update top of rendered rows based on offsets
+    renderedRows.forEach((row) => {
+        row.style = styleToString({
+            position: 'absolute',
+            top: `${state.offsets[row.rowIndex]}px`,
+        });
+    });
+}