lightning-base-components 1.13.6-alpha → 1.13.10-alpha

package/src/lightning/datatable/rows.js

@@ -1,6 +1,5 @@
 import { assert } from 'lightning/utilsPrivate';
 import { classSet, isObjectLike } from './utils';
-import { createRowKeysGenerator, generateColKeyValue } from './keys';
 import { isTreeType, getAttributesNames } from './types';
 import {
     isSelectedRow,
@@ -14,18 +13,14 @@ import {
     getSubTypeAttributesValues,
     getCellAttributesValues,
     isCustomerColumn,
+    generateColKeyValue,
 } from './columns';
 import { isRowNumberColumn, getRowNumberErrorColumnDef } from './rowNumber';
 import { getRowError } from './errors';
 import { getDirtyValue } from './inlineEdit-shared';
 
-export function getRowsDefaultState() {
-    return {
-        data: [],
-        keyField: undefined,
-        rows: [],
-        indexes: {},
-    };
+export function getData(state) {
+    return state.data;
 }
 
 export function setData(state, data) {
@@ -36,14 +31,14 @@ export function setData(state, data) {
     }
 }
 
-export function getData(state) {
-    return state.data;
-}
-
 export function getRows(state) {
     return state.rows;
 }
 
+export function getKeyField(state) {
+    return state.keyField;
+}
+
 export function setKeyField(state, value) {
     assert(
         typeof value === 'string',
@@ -56,17 +51,14 @@ export function setKeyField(state, value) {
     }
 }
 
-export function getKeyField(state) {
-    return state.keyField;
-}
-
 export function hasValidKeyField(state) {
     const keyField = getKeyField(state);
     return typeof keyField === 'string';
 }
 
 /**
- * It resolve the css classes for a row based on the row.isSelected state
+ * Resolves the CSS classes for a row based on the row.isSelected state
+ *
  * @param {object} row - a row object in state.rows collection
  * @returns {string} the classSet string
  */
@@ -92,17 +84,41 @@ export function getUserRowByCellKeys(state, rowKeyValue, colKeyValue) {
     return getData(state)[rowIndex];
 }
 
+/**
+ * It creates a row key generator based on the keyField passed in by the consumer.
+ * If the keyField passed in through the generator does not point to a value in the row object,
+ * it falls back to a generated key using indexes. Ex. row-0/row-1
+ *
+ * @param {String} keyField  - keyField provided by the consumer
+ * @returns {Function} - function with the unique row key generator
+ */
+export function uniqueRowKeyGenerator(keyField) {
+    let index = 0;
+    return function (row) {
+        if (row[keyField]) {
+            return row[keyField];
+        }
+        return `row-${index++}`;
+    };
+}
+
 /**
  * It compute the state.rows collection based on the current normalized (data, columns)
  * and generate cells indexes map(state.indexes)
+ *
+ * TODO: Reduce redundant calls to this function. This is indirectly called by the
+ * setters of 'data' and 'columns'. Additionally, for the role-based table, if we are
+ * attaching the 'cell' class, calling this from connectedCallback of datatable would
+ * eliminate the need for updateCellClassForRoleBasedMode.
+ *
  * @param {object} state - the current datatable state
  */
 export function updateRowsAndCellIndexes() {
     const { state, privateTypes: types } = this;
-    const { keyField } = state;
+    const { keyField, renderModeRoleBased } = state;
     const data = getData(state);
     const columns = getColumns(state);
-    const { computeUniqueRowKey } = createRowKeysGenerator(keyField);
+    const computeUniqueRowKey = uniqueRowKeyGenerator(keyField);
     const scopeCol = columns.find(
         (colData) => types.isValidType(colData.type) && colData.isScopeCol
     );
@@ -130,6 +146,11 @@ export function updateRowsAndCellIndexes() {
             const { fieldName } = colData;
             const colKeyValue = generateColKeyValue(colData, colIndex);
             const dirtyValue = getDirtyValue(state, row.key, colKeyValue);
+            const cellHasErrors = hasCellErrors(
+                rowErrors,
+                colData.fieldName,
+                colData.columnKey
+            );
             const computedCellValue =
                 dirtyValue !== undefined ? dirtyValue : rowData[fieldName];
             // cell object creation
@@ -147,14 +168,11 @@ export function updateRowsAndCellIndexes() {
                 class: computeCellClassNames(
                     rowData,
                     colData,
-                    rowErrors,
-                    dirtyValue
-                ),
-                hasError: hasCellErrors(
-                    rowErrors,
-                    colData.fieldName,
-                    colData.columnKey
+                    cellHasErrors,
+                    dirtyValue,
+                    renderModeRoleBased
                 ),
+                hasError: cellHasErrors,
                 isDataType:
                     types.isValidType(colData.type) && !colData.isScopeCol,
                 isDataTypeScope:
@@ -163,35 +181,23 @@ export function updateRowsAndCellIndexes() {
                 wrapTextMaxLines: state.wrapText[colKeyValue]
                     ? state.wrapTextMaxLines
                     : undefined,
-                paddingStyle:
-                    types.isCustomType(colData.type) &&
-                    !types.isStandardCellLayoutForCustomType(colData.type)
-                        ? 'padding: 0px;'
-                        : undefined,
+                style: computeCellStyles(types, colData, renderModeRoleBased),
             };
             if (isCustomerColumn(colData)) {
-                Object.assign(
+                assignCustomerColumnAttributes(
                     cell,
-                    computeCellTypeAttributes(rowData, colData, types),
-                    computeCellAttributes(rowData, colData),
-                    computeCellEditable(rowData, colData),
-                    computeCellDisplayReadOnlyIcon(colData)
+                    row,
+                    rowData,
+                    colData,
+                    types
                 );
-                if (!cell.editable) {
-                    cell.ariaReadOnly = true;
-                }
-                if (isTreeType(colData.type)) {
-                    Object.assign(cell, computeCellStateTypeAttributes(row));
-                }
             } else if (isRowNumberColumn(colData)) {
-                const scopeColValue = rowData[scopeCol.fieldName];
-                const errorColumnDef = getRowNumberErrorColumnDef(
-                    rowErrors,
-                    scopeColValue
-                );
-                Object.assign(
+                assignRowNumberColumnAttributes(
                     cell,
-                    computeCellTypeAttributes(rowData, errorColumnDef, types)
+                    rowData,
+                    types,
+                    rowErrors,
+                    scopeCol
                 );
             }
 
@@ -226,6 +232,80 @@ function hasCellErrors(rowErrors, fieldName, columnKey) {
     return rowErrorsHasColumnKey || (!columnKey && rowErrorsHasFieldName);
 }
 
+/**
+ * Computes and sets the following resolved values in the cell object:
+ * 1. `typeAttributes` specified in the column definition
+ * 2. `cellAttributes` specified in the column definition
+ * 3. Editability of the cell and subsequently the ariaReadOnly property
+ * 4. Visibility of read only icon
+ *
+ * Computes and sets the following tree specific attributes
+ * into typeAttributes21/22 in the cell object:
+ * 1. row.hasChildren
+ * 2. row.isExpanded
+ *
+ * @param {Object} cell - cell metadata
+ * @param {Object} row - row metadata
+ * @param {Object} rowData - data to be rendered in the cells of that row
+ * @param {Object} colData - column definition
+ * @param {Object} types - instance of DatatableTypes from `./types.js`
+ */
+function assignCustomerColumnAttributes(cell, row, rowData, colData, types) {
+    Object.assign(
+        cell,
+        computeCellTypeAttributes(rowData, colData, types),
+        computeCellAttributes(rowData, colData),
+        computeCellEditable(rowData, colData),
+        computeCellDisplayReadOnlyIcon(colData)
+    );
+    if (!cell.editable) {
+        cell.ariaReadOnly = true;
+    }
+
+    // If this is tree grid, this maps and sets into the cell object the tree specific attributes:
+    // 1) row.hasChildren to typeAttribute21 and
+    // 2) row.isExpanded to and typeAttribute22
+    if (isTreeType(colData.type)) {
+        Object.assign(cell, computeCellStateTypeAttributes(row));
+    }
+}
+
+/**
+ * Computes and sets the resolved typeAttribute for the row number column error state
+ *
+ * @param {Object} cell - cell metadata
+ * @param {Object} rowData - data to be rendered in the cells of that row
+ * @param {Object} types - instance of DatatableTypes from `./types.js`
+ * @param {Object} rowErrors - contains the errors present in that row
+ * @param {Object} scopeCol - column with scope=row
+ */
+function assignRowNumberColumnAttributes(
+    cell,
+    rowData,
+    types,
+    rowErrors,
+    scopeCol
+) {
+    const scopeColValue = rowData[scopeCol.fieldName];
+    const errorColumnDef = getRowNumberErrorColumnDef(rowErrors, scopeColValue);
+    Object.assign(
+        cell,
+        computeCellTypeAttributes(rowData, errorColumnDef, types)
+    );
+}
+
+/**
+ * This function extracts the `cellAttributes` and their values that are specified
+ * in the column definition.
+ * If a cell attribute points to a fieldName in a row, that value is resolved here.
+ *
+ * This object that contains the resolved mapping is then set in the `cell` object
+ * in each row.
+ *
+ * @param {Object} row - current row data. Required for cases cellAttributes refers to a fieldName in a row
+ * @param {Object} column - column definition
+ * @returns {Object} - contains the resolved mapping of cellAttributes and their values
+ */
 export function computeCellAttributes(row, column) {
     const cellAttributesValues = getCellAttributesValues(column);
     return Object.keys(cellAttributesValues).reduce((attrs, attrName) => {
@@ -236,6 +316,29 @@ export function computeCellAttributes(row, column) {
     }, {});
 }
 
+/**
+ * This function retrieves the allowlisted type attributes for a particular type and
+ * maps the value set in the column definition to `typeAttribute{index}`.
+ *
+ * The types and their corresponding allowlisted attributes can be seen in types.js
+ *
+ * Ex. For the type 'url', there are 3 type attributes allowlisted: label, target, tooltip
+ * If you pass typeAttributes: {label: 'My Label', target: '_blank', myattr: false}
+ * in the column definition, this function would map ->
+ * typeAttribute0: 'My Label', typeAttribute1: '_blank' and typeAttribute2: undefined
+ * `myattr` is not allowlisted so it is discarded
+ *
+ * This mapping is later set into the `cell` object for each row and
+ * will be passed in to primitive-cell-factory as
+ * type-attribute-0={cell.typeAttribute0}
+ * type-attribute-1={cell.typeAttribute1}
+ * ...
+ *
+ * @param {Object} row - current row data. Required for cases typeAttributes refers to a fieldName in a row
+ * @param {Object} column - column definition
+ * @param {Object} types - instance of DatatableTypes from `./types.js`
+ * @returns {Object} - object containing all the typeAttributes{index} and their mapped values
+ */
 export function computeCellTypeAttributes(row, column, types) {
     if (column.typeAttributes && column.typeAttributes.subType) {
         return computeCellSubTypeAttributes(row, column);
@@ -298,7 +401,47 @@ function computeCellDisplayReadOnlyIcon(column) {
     };
 }
 
-function computeCellClassNames(row, column, rowErrors, dirtyValue) {
+/**
+ * Computes styles to be set on the cell
+ * 1. Remove padding from the cell if the cell is of a custom type
+ *    and has opted out of using the standard layout
+ * 2. Set width of the cell. Width of each cell needs to be set and
+ *    managed by ourselves unlike the <table> version.
+ *
+ * @param {Object} types - instance of DatatableTypes from `./types.js`
+ * @param {Object} colData - column definition
+ * @param {Boolean} renderModeRoleBased - render mode of datatable (div || table)
+ * @returns {String} - styles to be set on the cell
+ */
+function computeCellStyles(types, colData, renderModeRoleBased) {
+    let style = '';
+    const columnType = colData.type;
+
+    // When a custom type is not using the standard layout,
+    // remove the padding that comes with the standard layout
+    if (
+        types.isCustomType(columnType) &&
+        !types.isStandardCellLayoutForCustomType(columnType)
+    ) {
+        style = 'padding: 0;';
+    }
+
+    // Width needs to be managed when rendering as divs
+    if (renderModeRoleBased) {
+        const columnWidth = colData.columnWidth;
+        style += columnWidth > 0 ? `width:${columnWidth}px;` : '';
+    }
+
+    return style;
+}
+
+function computeCellClassNames(
+    row,
+    column,
+    cellHasErrors,
+    dirtyValue,
+    renderModeRoleBased
+) {
     const classNames = classSet('');
     // TODO: With the current SLDS design, the 'slds-cell-edit' class is required on a cell in cases
     // where the read only icon is to be displayed. This is an issue with their design that will need to
@@ -306,16 +449,11 @@ function computeCellClassNames(row, column, rowErrors, dirtyValue) {
     classNames.add({
         'slds-cell-edit':
             isCellEditable(row, column) || column.displayReadOnlyIcon,
+        'slds-tree__item': isTreeType(column.type),
+        'slds-has-error': cellHasErrors,
+        'slds-is-edited': dirtyValue !== undefined,
+        cell: renderModeRoleBased,
     });
-    classNames.add({ 'slds-tree__item': isTreeType(column.type) });
-    classNames.add({
-        'slds-has-error': hasCellErrors(
-            rowErrors,
-            column.fieldName,
-            column.columnKey
-        ),
-    });
-    classNames.add({ 'slds-is-edited': dirtyValue !== undefined });
     return classNames.toString();
 }
 
@@ -431,3 +569,51 @@ export function getRowHasChildren(column, row) {
     );
     return !!hasChildren;
 }
+
+/**
+ * For the role-based table, we need to manage the width of each cell separately.
+ * Re-compute the cell styles so that the width of the cell is set
+ * to that of its column.
+ *
+ * @param {Object} state - Datatable's state object
+ */
+export function recomputeCellStyles(types, state) {
+    const columns = getColumns(state);
+    state.rows.forEach((row) => {
+        row.cells.forEach((cell, colIndex) => {
+            const colData = columns[colIndex];
+            cell.style = computeCellStyles(types, colData, true);
+        });
+    });
+}
+
+/**
+ * The cells' classes are normally updated via `updateRowsAndCellIndexes()`. This ideally
+ * happens after renderMode is set since `updateRowsAndCellIndexes` requires the final
+ * renderMode value in order to set the 'cell' class on each cell.
+ *
+ * However, in some cases, it's possible that updateRowsAndCellIndexes is called
+ * before the renderMode is set (to 'role-based'). This will cause the 'cell' class to NOT be set
+ * in the individual cells because state.renderModeRoleBased will be `false` at that point.
+ * As a result, positioning of the cell content will be off.
+ *
+ * In such a case where the renderMode is 'role-based' and when the updateRowsAndCellIndexes
+ * has already been called (indicated by the presence of 'state.rows'), retroactively
+ * add the 'cell' class to each cell.
+ *
+ * TODO: The 'cell' class will not be required once we move to the SLDS blueprint.
+ * Remove this and usages once datatable migrates to using the SLDS blueprint for the role-based table.
+ *
+ * @param {Object} state - Datatable's state object
+ */
+export function updateCellClassForRoleBasedMode(state) {
+    if (state.renderModeRoleBased && state.rows) {
+        state.rows.forEach((row) => {
+            row.cells.forEach((cell) => {
+                const classes = classSet(cell.class);
+                classes.add('cell');
+                cell.class = classes.toString();
+            });
+        });
+    }
+}

package/src/lightning/datatable/sort.js

@@ -1,39 +1,71 @@
 import { assert } from 'lightning/utilsPrivate';
 import { getColumnName } from './columns-shared';
 
-export function getSortDefaultState() {
-    return {
-        sortedBy: undefined,
-        sortedDirection: undefined,
-        defaultSortDirection: 'asc',
-    };
-}
-
 const VALID_SORT_DIRECTIONS = {
     asc: true,
     desc: true,
 };
 
+/**
+ * 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
+ */
 export function isValidSortDirection(value) {
     return !!VALID_SORT_DIRECTIONS[value];
 }
 
-export function getSortedBy(state) {
-    return state.sortedBy;
+/**
+ * Gets the default sort direction. When clicking on a header to sort,
+ * the default sort direction is applied first. Clicking again reverses it
+ *
+ * @param {Object} state The current datatable state
+ * @return {string} The default sort direction
+ */
+export function getDefaultSortDirection(state) {
+    return state.defaultSortDirection;
 }
 
-export function setSortedBy(state, value) {
-    if (typeof value === 'string') {
-        state.sortedBy = value;
-    } else {
-        state.sortedBy = undefined;
-    }
+/**
+ * Sets the default sort direction. When clicking on a header to sort,
+ * 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
+ */
+export function setDefaultSortDirection(state, value) {
+    assert(
+        isValidSortDirection(value),
+        `The "defaultSortDirection" value passed into lightning:datatable
+        is incorrect, "defaultSortDirection" value should be one of
+        ${Object.keys(VALID_SORT_DIRECTIONS).join()}.`
+    );
+    state.defaultSortDirection = isValidSortDirection(value)
+        ? value
+        : getDefaultSortDirection(state);
 }
 
+/**
+ * Gets the current sort direction
+ *
+ * @param {Object} state The current datatable state
+ * @return {string} The current sort direction
+ */
 export function getSortedDirection(state) {
     return state.sortedDirection;
 }
 
+/**
+ * Sets the current sort direction.
+ * In the case an invalid sort direction is provided, throw
+ * an error providing resolution information. In an error case,
+ * `sortedDirection` will be `undefined`
+ *
+ * @param {Object} state The current datatable state
+ * @param {string} value The value to update the sort direction to
+ */
 export function setSortedDirection(state, value) {
     assert(
         isValidSortDirection(value),
@@ -44,27 +76,50 @@ export function setSortedDirection(state, value) {
     state.sortedDirection = isValidSortDirection(value) ? value : undefined;
 }
 
-export function getDefaultSortDirection(state) {
-    return state.defaultSortDirection;
+/**
+ * Gets the current sort value. The value will match the name
+ * of a given column in the datatable
+ *
+ * @param {Object} state The current datatable state
+ * @return {string} The current sort value
+ */
+export function getSortedBy(state) {
+    return state.sortedBy;
 }
 
-export function setDefaultSortDirection(state, value) {
-    assert(
-        isValidSortDirection(value),
-        `The "defaultSortDirection" value passed into lightning:datatable
-        is incorrect, "defaultSortDirection" value should be one of
-        ${Object.keys(VALID_SORT_DIRECTIONS).join()}.`
-    );
-    state.defaultSortDirection = isValidSortDirection(value)
-        ? value
-        : getDefaultSortDirection(state);
+/**
+ * Sets the current sort value. The value should match the name
+ * of a given column in the datatable. In the case that a
+ * non-string value is provided, the sort value with fallback
+ * to `undefined`
+ *
+ * @param {Object} state The current datatable state
+ * @param {string} value The value to update the sort state to
+ */
+export function setSortedBy(state, value) {
+    if (typeof value === 'string') {
+        state.sortedBy = value;
+    } else {
+        state.sortedBy = undefined;
+    }
 }
 
+/**
+ * Applies sorting to each datatable column
+ *
+ * @param {Object} state The current datatable state
+ */
 export function updateSorting(state) {
     const columns = state.columns;
     columns.forEach((column) => updateColumnSortingState(column, state));
 }
 
+/**
+ * Applies sorting to a datatable column
+ *
+ * @param {Object} column The datatable column name to sort
+ * @param {Object} state The current datatable state
+ */
 export function updateColumnSortingState(column, state) {
     const { sortedBy, sortedDirection, defaultSortDirection } = state;
 

package/src/lightning/datatable/{normalizer.js → state.js}

@@ -1,9 +1,15 @@
-import { generateColKeyValue } from './keys';
-
+/**
+ * This function returns the initial state of the datatable.
+ * 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
+ */
 export const getDefaultState = function () {
     return {
         // columns
         columns: [],
+        hideCheckboxColumn: false,
 
         // rows
         data: [],
@@ -16,6 +22,7 @@ export const getDefaultState = function () {
         maxRowSelection: undefined,
 
         headerIndexes: {},
+        hideTableHeader: false,
 
         // keyboard
         keyboardMode: 'NAVIGATION',
@@ -28,6 +35,7 @@ export const getDefaultState = function () {
 
         // header actions
         wrapText: {},
+        wrapTextMaxLines: undefined,
 
         // sort
         sortedBy: undefined,
@@ -38,20 +46,17 @@ export const getDefaultState = function () {
         showRowNumberColumn: false,
         rowNumberOffset: 0,
 
-        // resizer
-        resizeColumnDisabled: false,
-        resizeStep: 10,
-        columnWidths: [],
-        tableWidth: 0,
-        minColumnWidth: 50,
-        maxColumnWidth: 1000,
-        columnWidthsMode: 'fixed',
-
         // infinite loading
         enableInfiniteLoading: false,
         loadMoreOffset: 20,
         isLoading: false,
 
+        // table render mode
+        renderModeRoleBased: false,
+
+        // viewport rendering
+        enableViewportRendering: undefined,
+
         // inline edit
         inlineEdit: {
             dirtyValues: {},
@@ -62,22 +67,5 @@ export const getDefaultState = function () {
             rows: {},
             table: {},
         },
-
-        hideTableHeader: false,
-        wrapTextMaxLines: undefined,
     };
 };
-
-/**
- * It generate headerIndexes based in the current metadata
- * headerIndexes represent the position of the header(column)
- * based on the unique colKeyValue
- * @param {object} columns - the current normalized column metadata
- * @returns {object} headerIndexes e.g. { 'name-text' 0, 'amount-number': 1 }
- */
-export const generateHeaderIndexes = function (columns) {
-    return columns.reduce((prev, col, index) => {
-        prev[generateColKeyValue(col, index)] = index;
-        return prev;
-    }, {});
-};