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

package/src/lightning/datatable/__wdio__/utam/utam.spec.js

@@ -0,0 +1,214 @@
+const Datatable = require('pageobjects/datatable');
+const Button = require('pageobjects/button');
+
+const tableTypes = {
+    default: '[data-render-mode="default"]',
+    roleBased: '[data-render-mode="role-based"]',
+};
+
+describe('Datatable UTAM Page Object Tests', () => {
+    Object.keys(tableTypes).forEach((type) => {
+        describe(`${type} table`, () => {
+            const TABLE_SELECTOR = tableTypes[type];
+
+            let root;
+
+            beforeEach(async () => {
+                await browser.url('/datatable/utam');
+                root = await $('datatable-utam');
+                await root.waitForDisplayed();
+            });
+
+            it('should get the cell value by row and column index', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                const cellValue = await datatable.getCellValueByIndex(1, 2);
+                expect(cellValue).toBe('Billy Simmons');
+            });
+            it('should get the cell value by row index and column label', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                const cellValue = await datatable.getCellValueByLabel(2, 'Age');
+                expect(cellValue).toBe('35');
+            });
+            it('should get the number of rows in the table', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                const cellValue = await datatable.getNumRows();
+                expect(cellValue).toBe(4);
+            });
+            it('should tell if the table has any rows', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                const cellValue = await datatable.hasRows();
+                expect(cellValue).toBe(true);
+            });
+            it('should toggle selection of row - comprehensive', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                for (let i = 1; i <= 4; i++) {
+                    expect(await datatable.isRowSelected(i)).toBe('false');
+                }
+
+                await datatable.toggleRowSelection(1);
+                expect(await datatable.isRowSelected(1)).toBe('true');
+                [2, 3, 4].forEach(async (i) => {
+                    expect(await datatable.isRowSelected(i)).toBe('false');
+                });
+
+                await datatable.toggleRowSelection(2);
+                expect(await datatable.isRowSelected(2)).toBe('true');
+                [3, 4].forEach(async (i) => {
+                    expect(await datatable.isRowSelected(i)).toBe('false');
+                });
+
+                await datatable.toggleRowSelection(3);
+                expect(await datatable.isRowSelected(3)).toBe('true');
+                expect(await datatable.isRowSelected(4)).toBe('false');
+
+                await datatable.toggleRowSelection(4);
+                expect(await datatable.isRowSelected(4)).toBe('true');
+            });
+            it('should toggle selection of row', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                await datatable.toggleRowSelection(3);
+                expect(await datatable.isRowSelected(3)).toBe('true');
+
+                await datatable.toggleRowSelection(3);
+                expect(await datatable.isRowSelected(3)).toBe('false');
+            });
+            it('should get the number of selected rows when not all rows are selected', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                await datatable.toggleRowSelection(3);
+                expect(await datatable.getNumSelectedRows()).toBe(1);
+
+                await datatable.toggleRowSelection(2);
+                expect(await datatable.getNumSelectedRows()).toBe(2);
+            });
+            it('should get the number of selected rows when all rows are selected', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                await datatable.clickSelectAllCheckbox();
+                expect(await datatable.getNumSelectedRows()).toBe(4);
+            });
+            it('should get the number of columns in the table', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                expect(await datatable.getNumColumns()).toBe(5);
+            });
+            it('should tell whether or not a column is sortable', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                expect(await datatable.isSortableColumn('Age')).toBe(true);
+
+                // Need to speak to UTAM (about isPresent) or find a better way to write this method
+                // If column is not sortable, the test fails with the error:
+                // "Can't find elements with locator 'lightning-primitive-header-factory.slds-is-sortable' inside its scope element."
+                // expect(await datatable.isSortableColumn('Name')).toBe(false);
+            });
+            it('should tell whether or not the row is selectable', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                expect(await datatable.isSelectableRow(1)).toBe(true);
+            });
+            it('should get the width of a column', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                const datatableElement = await root.shadow$(
+                    'lightning-datatable'
+                );
+                const columnHeader = await datatableElement.shadow$(
+                    '[aria-label="Name"]'
+                );
+
+                // Remove intermediate white spaces
+                let expectedWidth = await columnHeader.getAttribute('style');
+                expectedWidth = expectedWidth.replace(/\s/g, '');
+                let actualWidth = await datatable.getWidth('Name');
+                actualWidth = actualWidth.replace(/\s/g, '');
+
+                // Using indexOf in case of presence of ';'
+                expect(actualWidth.indexOf(expectedWidth) >= 0).toBe(true);
+            });
+            it('should tell whether or not a column has header actions', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                expect(await datatable.hasHeaderActions('Name')).toBe(true);
+                expect(await datatable.hasHeaderActions('Age')).toBe(true);
+                // false fails; need to check for true or null; check with UTAM if expected
+                expect(await datatable.hasHeaderActions('Email')).toBe(null);
+            });
+            it('should get the text of the rowheader cell of the specified row', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                expect(await datatable.getRowHeaderText(2)).toBe(
+                    'Kelsey Denesik'
+                );
+            });
+            it('should click column header of the sortable column', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                let cellValue = await datatable.getCellValueByLabel(1, 'Age');
+                expect(cellValue).toBe('40');
+
+                await datatable.clickSortHeaderButton('Age');
+
+                cellValue = await datatable.getCellValueByLabel(1, 'Age');
+                expect(cellValue).toBe('35');
+            });
+            it('should tell whether the specified row has row actions or not', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                expect(await datatable.hasRowActionInRow(2)).toBe(true);
+            });
+            it('should tell whether or not the datatable has the loading indicator visible', async () => {
+                const datatable = await utam.load(Datatable, {
+                    element: await root.shadow$(TABLE_SELECTOR),
+                });
+
+                expect(await datatable.isLoading()).toBe(false);
+
+                const button = await utam.load(Button, {
+                    element: await root.shadow$('lightning-button'),
+                });
+                await button.click();
+
+                expect(await datatable.isLoading()).toBe(true);
+            });
+        });
+    });
+});

package/src/lightning/datatable/columns.js

@@ -13,33 +13,62 @@ const i18n = {
     rowActionsDefaultAriaLabel,
 };
 
+export const SELECTABLE_ROW_CHECKBOX = 'SELECTABLE_CHECKBOX';
+
+const SELECTABLE_COLUMN = {
+    type: SELECTABLE_ROW_CHECKBOX,
+    fixedWidth: 32,
+    tabIndex: -1,
+    internal: true,
+};
+
+/**
+ * Returns the columns default state.
+ *
+ * @returns {Object} The default column state.
+ */
 export function getColumnsDefaultState() {
     return {
         columns: [],
     };
 }
 
+/**
+ * Returns whether or not the datatable has columns.
+ *
+ * @param {Object} state The datatable's state.
+ * @returns {Boolean} Whether the datatable has columns.
+ */
 export function hasColumns(state) {
     return getColumns(state).length > 0;
 }
 
+/**
+ * Returns whether or not the column has been specified by the customer.
+ *
+ * @param {Object} column The column definition object.
+ * @returns {Boolean} Whether the column is customer defined or not.
+ */
 export function isCustomerColumn(column) {
     return column.internal !== true;
 }
 
+/**
+ * Returns the datatable's columns from state.
+ *
+ * @param {Object} state  The datatable's state.
+ * @returns {Array} The datatable's columns definition.
+ */
 export function getColumns(state) {
     return state.columns;
 }
 
-export const SELECTABLE_ROW_CHECKBOX = 'SELECTABLE_CHECKBOX';
-
-const SELECTABLE_COLUMN = {
-    type: SELECTABLE_ROW_CHECKBOX,
-    fixedWidth: 32,
-    tabIndex: -1,
-    internal: true,
-};
-
+/**
+ * Returns whether any of the datatable's columns are editable.
+ *
+ * @param {Array} columns The datatable's column definition.
+ * @returns {Boolean} Whether any of the columns are editable.
+ */
 export function hasEditableColumn(columns) {
     return columns.some((column) => column.editable);
 }
@@ -50,8 +79,8 @@ export function hasEditableColumn(columns) {
  * that are present in both the input and output array, the relative ordering between
  * them that existed in the input array is maintained in the output array.
  *
- * @param {Array} columns - the datatable's column definitions. Must be truthy and must be
- *                          filled with truthy column definition objects.
+ * @param {Array} columns The datatable's column definition. Must be truthy and must be
+ *                        filled with truthy column definition objects.
  */
 export function getEditableColumns(columns) {
     return columns.filter((column) => column.editable);
@@ -64,8 +93,8 @@ export function getEditableColumns(columns) {
  * the invocation of this function results in a no-op because we instead rely on later
  * row level checks to determine cell editability.
  *
- * @param {Object} column column metadata
- * @param {Object} types the DatatableTypes object
+ * @param {Object} column The column definition object.
+ * @param {Object} types The DatatableTypes object.
  */
 export function normalizeEditable(column, types) {
     if (types.isEditableType(column.type)) {
@@ -81,10 +110,24 @@ export function normalizeEditable(column, types) {
     }
 }
 
+/**
+ * Steps through and corrects column definitions inconsistencies.
+ *
+ * For customer-specified columns, we verify all parameters are valid and set
+ * how we would expect them to prevent errors from bubbling up.
+ * See `normalizeColumnDataType`, `normalizeEditable`.
+ *
+ * For tree-types, we verify all sub-type attributes are within our allowed
+ * parameters. See `getNormalizedSubTypeAttribute`.
+ *
+ * @param {Object} state The datatable state.
+ * @param {Array} columns The datatable's column definitions.
+ * @param {Object} types  The type handling factory.
+ */
 export function normalizeColumns(state, columns, types) {
     if (columns.length !== 0) {
         let firstColumnForReaders = 0;
-        // workaround https://git.soma.salesforce.com/raptor/raptor/issues/763
+        // Workaround: https://git.soma.salesforce.com/raptor/raptor/issues/763
         const normalizedColumns = Object.assign([], columns);
 
         if (!state.hideCheckboxColumn) {
@@ -100,7 +143,7 @@ export function normalizeColumns(state, columns, types) {
 
         const columnKeyMap = {};
         state.columns = normalizedColumns.map((column, index) => {
-            // Verify columnKey is unique
+            // Verify `columnKey` is unique
             const columnKey = column.columnKey;
             if (columnKey && columnKeyMap[columnKey]) {
                 console.error(
@@ -115,7 +158,8 @@ export function normalizeColumns(state, columns, types) {
             );
             normalizedColumn.ariaLabel =
                 normalizedColumn.label || normalizedColumn.ariaLabel || null;
-            // customType attribute is needed to render default iedit component
+
+            // `customType` attribute is needed to render default iedit component
             normalizedColumn.editableCustomType =
                 types.isStandardCellLayoutForCustomType(normalizedColumn.type);
 
@@ -131,6 +175,7 @@ export function normalizeColumns(state, columns, types) {
                     normalizedColumn.typeAttributes
                 );
             }
+
             return Object.assign(normalizedColumn, {
                 tabIndex: -1,
                 colKeyValue: generateColKeyValue(normalizedColumn, index),
@@ -142,17 +187,12 @@ export function normalizeColumns(state, columns, types) {
     }
 }
 
-function normalizeColumnDataType(column, types) {
-    if (!types.isValidType(column.type)) {
-        column.type = getRegularColumnDefaults().type;
-    }
-}
-
 /**
  * Normalizes the subType and subTypeAttributes in the typeAttributes.
- * @param {String} type the type of this column
- * @param {Object} typeAttributes the type attributes of the column
- * @returns {Object} a new typeAttributes object with the sybtype and subTypeAttributes normalized.
+ *
+ * @param {String} type The type of this column
+ * @param {Object} typeAttributes The type attributes of the column
+ * @returns {Object} A new typeAttributes object with the sybtype and subTypeAttributes normalized.
  */
 export function getNormalizedSubTypeAttribute(type, typeAttributes) {
     const typeAttributesOverrides = {};
@@ -166,42 +206,12 @@ export function getNormalizedSubTypeAttribute(type, typeAttributes) {
     return Object.assign({}, typeAttributes, typeAttributesOverrides);
 }
 
-function getRegularColumnDefaults() {
-    return {
-        type: 'text',
-        typeAttributes: {},
-        cellAttributes: {},
-    };
-}
-
-function getActionColumnDefaults() {
-    return {
-        fixedWidth: 50,
-        resizable: false,
-        ariaLabel: i18n.rowActionsDefaultAriaLabel,
-    };
-}
-
-function getTreeColumnDefaults() {
-    return {
-        type: 'tree',
-        subType: 'text',
-        typeAttributes: {},
-        cellAttributes: {},
-    };
-}
-
-function getColumnDefaults(column) {
-    switch (column.type) {
-        case 'action':
-            return getActionColumnDefaults();
-        case 'tree':
-            return getTreeColumnDefaults();
-        default:
-            return getRegularColumnDefaults();
-    }
-}
-
+/**
+ * Retrieves the type attributes for a given column.
+ *
+ * @param {Object} column The column definition object.
+ * @returns Type attributes for the given column, if they exist.
+ */
 export function getTypeAttributesValues(column) {
     if (isObjectLike(column.typeAttributes)) {
         return column.typeAttributes;
@@ -209,6 +219,12 @@ export function getTypeAttributesValues(column) {
     return {};
 }
 
+/**
+ * Retrieves the sub-type attributes for a given column.
+ *
+ * @param {Object} column The column definition object.
+ * @returns {Object} Sub-type attributes for the given column, if they exist.
+ */
 export function getSubTypeAttributesValues(column) {
     if (isObjectLike(column.typeAttributes.subTypeAttributes)) {
         return column.typeAttributes.subTypeAttributes;
@@ -216,6 +232,12 @@ export function getSubTypeAttributesValues(column) {
     return {};
 }
 
+/**
+ * Retrieves the cell attributes for a given column.
+ *
+ * @param {Object} column The column definition object.
+ * @returns {Object} Cell attributes for the given column, if they exist.
+ */
 export function getCellAttributesValues(column) {
     if (isObjectLike(column.cellAttributes)) {
         return column.cellAttributes;
@@ -226,9 +248,9 @@ export function getCellAttributesValues(column) {
 /**
  * Generates a unique column key value.
  *
- * @param {object} columnMetadata - the object for an specific column metadata
- * @param {int} index - optionally, the index of the column.
- * @returns {string} It generate the column key value based on the column field name and type.
+ * @param {Object} columnMetadata The object for an specific column metadata
+ * @param {Integer} index Optionally, the index of the column.
+ * @returns {String} It generates the column key value based on the column field name and type.
  */
 export function generateColKeyValue(columnMetadata, index) {
     const { columnKey, fieldName, type } = columnMetadata;
@@ -239,9 +261,10 @@ export function generateColKeyValue(columnMetadata, index) {
 /**
  * Return the index in dt.columns (user definition) related to colKeyValue.
  *      -1 if no column with that key exist or if its internal.
+ *
  * @param {Object} state The datatable state
  * @param {String} colKeyValue The generated key for the column
- * @return {Number} The index in dt.columns. -1 if not found or if its internal.
+ * @returns {Number} The index in `dt.columns`. -1 if not found or if its internal.
  */
 export function getUserColumnIndex(state, colKeyValue) {
     const stateColumnIndex = getStateColumnIndex(state, colKeyValue);
@@ -267,8 +290,8 @@ export function getUserColumnIndex(state, colKeyValue) {
  *
  * These indexes are set in the state object - `state.headerIndexes`
  *
- * @param {object} columns - the current normalized column metadata
- * @returns {object} headerIndexes e.g. { 'name-text': 0, 'amount-number': 1 }
+ * @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) => {
@@ -282,17 +305,18 @@ export const generateHeaderIndexes = function (columns) {
  *
  * @param {Object} state The datatable state
  * @param {String} colKeyValue The generated key for the column
- * @return {number} The index in state.columns.
+ * @returns {Number} The index in state.columns
  */
 export function getStateColumnIndex(state, colKeyValue) {
     return state.headerIndexes[colKeyValue];
 }
 
 /**
+ * Retrieves a column index number by its key.
  *
- * @param {Object} state - The datatable state
- * @param {String} key - the key of the column. Defaults to field name if 'columnKey' is not provided.
- * @returns {number} The index in state.columns, -1 if it does not exist
+ * @param {Object} state The datatable state
+ * @param {String} key The key of the column. Defaults to field name if 'columnKey' is not provided.
+ * @returns {Number} The index in state.columns, -1 if it does not exist
  */
 export function getColumnIndexByColumnKey(state, key) {
     let i = 0;
@@ -307,3 +331,74 @@ export function getColumnIndexByColumnKey(state, key) {
 
     return existFieldName ? i : -1;
 }
+
+/************************** PRIVATE METHODS ***************************/
+
+/**
+ * If the specified column type is not supported, resets it to default.
+ *
+ * @param {Object} column The column definition object.
+ * @param {Object} types The type handling factory.
+ */
+function normalizeColumnDataType(column, types) {
+    if (!types.isValidType(column.type)) {
+        column.type = getRegularColumnDefaults().type;
+    }
+}
+
+/**
+ * Returns the column defaults based on its type.
+ *
+ * @param {Object} column The column definition object.
+ * @returns {Object} The column defaults.
+ */
+function getColumnDefaults(column) {
+    switch (column.type) {
+        case 'action':
+            return getActionColumnDefaults();
+        case 'tree':
+            return getTreeColumnDefaults();
+        default:
+            return getRegularColumnDefaults();
+    }
+}
+
+/**
+ * Retrieves the defaults for regular columns.
+ *
+ * @returns {Object} Regular column defaults
+ */
+function getRegularColumnDefaults() {
+    return {
+        type: 'text',
+        typeAttributes: {},
+        cellAttributes: {},
+    };
+}
+
+/**
+ * Retrieves the defaults for action columns.
+ *
+ * @returns {Object} Action column defaults
+ */
+function getActionColumnDefaults() {
+    return {
+        fixedWidth: 50,
+        resizable: false,
+        ariaLabel: i18n.rowActionsDefaultAriaLabel,
+    };
+}
+
+/**
+ * Retrieves the defaults for tree columns.
+ *
+ * @returns {Object} Tree column defaults
+ */
+function getTreeColumnDefaults() {
+    return {
+        type: 'tree',
+        subType: 'text',
+        typeAttributes: {},
+        cellAttributes: {},
+    };
+}