lightning-base-components 1.14.6-alpha → 1.15.2-alpha

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,13 @@ 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,
+        shouldResetHeights: false,
 
         // inline edit
         inlineEdit: {

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,12 +33,14 @@
                     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>
                     <template if:true={hasValidKeyField}>
-                        <thead>
+                        <thead data-rowgroup-header>
                             <!-- Column Header Row -->
                             <tr class="slds-line-height_reset"
                                 data-row-key-value="HEADER"
@@ -99,7 +101,7 @@
                                 </template>
                             </tr>
                         </thead>
-                        <tbody style={computedTbodyStyle}>
+                        <tbody data-rowgroup-body style={computedTbodyStyle}>
                             <template for:each={renderedRows} for:item="row" for:index="rowIndex">
                                 <!-- Data Rows -->
                                 <tr class={row.classnames}
@@ -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)) {