lightning-base-components 1.13.10-alpha → 1.14.4-alpha

package/src/lightning/colorPickerCustom/colorPickerCustom.js

@@ -8,6 +8,7 @@ import labelHexLabel from '@salesforce/label/LightningColorPicker.hexLabel';
 import labelHueInput from '@salesforce/label/LightningColorPicker.hueInput';
 import labelRInput from '@salesforce/label/LightningColorPicker.rInput';
 import labelRedAbbr from '@salesforce/label/LightningColorPicker.redAbbr';
+import formFactorPropertyName from '@salesforce/client/formFactor';
 import { LightningElement, api, track } from 'lwc';
 import { keyCodes } from 'lightning/utilsPrivate';
 import { generateUniqueId, getErrorMessage } from 'lightning/inputUtils';
@@ -58,7 +59,25 @@ export default class LightningColorPickerCustom extends LightningElement {
         if (!this._initialized) {
             // eslint-disable-next-line @lwc/lwc/no-async-operation
             requestAnimationFrame(() => {
-                this.focus();
+                // (*1*)
+                if (formFactorPropertyName !== 'Large') {
+                    /**
+                     * We need to wait for one more animation frame and invoke .focus()
+                     * in iOS. This is because the positionLibray.js initially sets the position
+                     * of this color-picker element to "top: 0px" and then later repositions it asynchronously
+                     * it the next animation frames. The first (*1*) rAF callback is fired between
+                     * setting "top: 0px" and then later repositioning it. Calling .focus() in this callback
+                     * triggers a re-paint step and the page is scrolled to the top due to "top: 0px" being
+                     * present in the styles. To avoid this, we can delay the next re-paint after color-picker
+                     * is repositioned correctly by positionLibrary.js. Hence we wait for next animation frame
+                     * and then call .focus() to trigger the next re-paint after the color-picker is repositioned correctly
+                     * which was initially positioned with "top: 0px" by positionLibrary.js
+                     */
+                    // eslint-disable-next-line @lwc/lwc/no-async-operation
+                    requestAnimationFrame(() => this.focus());
+                } else {
+                    this.focus();
+                }
             });
             this.gradient();
             this.handleUpdateAnchor();

package/src/lightning/datatable/__docs__/datatable.md

@@ -244,6 +244,28 @@ Valid data types and their supported attributes include:
 | text        | Displays text using [lightning-formatted-text](bundle/lightning-formatted-text/). This is the default data type.                                                                                                                                                                                                                                                       | linkify                                                                                                                                                       |
 | url         | Displays a URL using [lightning-formatted-url](bundle/lightning-formatted-url/)                                                                                                                                                                                                                                                                                        | label, target, tooltip                                                                                                                                        |
 
+In some situations, multiple columns reference the same `fieldName` but have different `fieldApiNames` and different ways of working with the field information. To give a column a unique ID when using the same field name for two columns, use the attribute `columnKey` instead of `fieldName` on one of the column definitions.
+
+```javascript
+get columns() {
+    return [
+        // Column using 'fieldName' as identifier
+        {
+            label: 'Lead',
+            fieldName: 'leadId',
+            ...
+        },
+        // Column using 'columnKey' as identifier
+        {
+            label: 'Company',
+            columnKey: 'leadCompany',
+            fieldName: 'leadId',
+            ...
+        }
+    ]
+}
+```
+
 #### Custom Formatting Examples
 
 To customize the formatting based on the data type, pass in the attributes for
@@ -494,6 +516,21 @@ const columns = [
 
 Custom classes are currently not supported. To apply custom styling on your datatable cells, create a custom data type and then apply your custom CSS classes. See [Custom Data Type Layout and Styles](docs/component-library/documentation/lwc/lwc.data_table_custom_types_styling).
 
+#### Displaying Indicators for Read-Only Fields
+
+You can display a lock icon on read-only fields to specify they're not editable. To specify that a column's field as read-only, set the column attribute `editable` to `false` and the column attribute `displayReadOnlyIcon` to `true` in the associated column definition. This example displays a lock icon on each field in a column called "Website."
+
+```javascript
+const columns = [
+    {
+        label: 'Website',
+        fieldName: 'website',
+        type: 'url',
+        editable: false,
+        displayReadOnlyIcon: true,
+    }
+```
+
 #### Using Infinite Scrolling to Load More Rows
 
 Infinite scrolling enables you to load a subset of data and then display more
@@ -1031,6 +1068,24 @@ handleSave(event) {
 }
 ```
 
+You can also program an external element, such as a button, to open an inline edit panel on the currently active cell or next editable cell in the datatable. Invoke the `openInlineEdit()` method in the external element that should direct a user to the first editable cell in your datatable component.
+
+This example opens a datatable cell for inline edit when the user clicks an "Edit" button.
+
+```javascript
+import { LightningElement } from 'lwc';
+export default class DatatableWithInlineEdit extends LightningElement {
+    data = [];
+    columns = columns;
+    rowOffset = 0;
+
+    handleClick() {
+        const dt = this.template.querySelector('lightning-datatable');
+        dt.openInlineEdit();
+    }
+}
+```
+
 For more information, see [Display Data in a Table with Inline Editing](docs/component-library/documentation/lwc/lwc.data_table_inline_edit).
 
 #### Displaying Errors

package/src/lightning/datatable/__examples__/basic/basic.html

@@ -5,5 +5,5 @@
                 data={data}
                 columns={columns}>
         </lightning-datatable>
-    </div>    
+    </div>
 </template>

package/src/lightning/datatable/columns-shared.js

@@ -4,7 +4,7 @@
  * which also has a dependency on `columns.js` for `getColumnName()`.
  *
  * We split out some of the functions that could cause circular dependencies with
- * `column.js` into the `*-shared.js` files. `inlineEdit-shared.js` is another.
+ * `column.js` into the `*-shared.js` files. `inlineEditShared.js` is another.
  */
 
 export function getColumnName(column) {

package/src/lightning/datatable/datatable.js

@@ -42,7 +42,7 @@ import {
 import {
     syncSelectedRowsKeys,
     handleRowSelectionChange,
-    updateSelectionState,
+    updateBulkSelectionState,
     getMaxRowSelection,
     setMaxRowSelection,
     getSelectedRowsKeys,
@@ -53,7 +53,7 @@ import {
     handleDeselectRow,
     getHideSelectAllCheckbox,
     getCurrentSelectionLength,
-} from './selector';
+} from './rowSelection';
 import {
     syncActiveCell,
     handleKeydownOnCell,
@@ -80,6 +80,9 @@ import {
     handleKeydownOnTable,
     addFocusStylesToActiveCell,
     refocusCellElement,
+    isCellElement,
+    getActiveCellElement,
+    FOCUS_CLASS,
 } from './keyboard';
 import {
     getRowNumberOffset,
@@ -134,7 +137,11 @@ import {
 import {
     isViewportRenderingEnabled,
     setViewportRendering,
+    getDTWrapperHeight,
+    setFirstVisibleIndex,
+    setVirtualize,
     RenderManager,
+    DEFAULT_ROW_HEIGHT,
 } from './renderManager';
 
 import { hasTreeDataType } from './tree';
@@ -144,6 +151,7 @@ import { generateUniqueId } from 'lightning/inputUtils';
 import DatatableTypes from './types';
 import labelAriaLiveNavigationMode from '@salesforce/label/LightningDatatable.ariaLiveNavigationMode';
 import labelAriaLiveActionMode from '@salesforce/label/LightningDatatable.ariaLiveActionMode';
+import { styleToString } from './utils';
 
 const i18n = {
     ariaLiveNavigationMode: labelAriaLiveNavigationMode,
@@ -196,7 +204,6 @@ export default class LightningDatatable extends LightningElement {
     _privateTypes = {};
     _privateWidthObserver = null; // Instance of LightningDatatableResizeObserver
     _renderMode = 'table';
-    _renderedRowCount = 0;
     _suppressBottomBar = false;
 
     /************************* PUBLIC PROPERTIES *************************/
@@ -493,6 +500,7 @@ export default class LightningDatatable extends LightningElement {
      * @type {object}
      * @property {boolean} viewportRendering - Specifies whether to defer rendering of rows outside the viewport until the user begins scrolling. To use this feature, create a fixed-height container element for lightning-datatable.
      * @property {number} rowHeight - Specifies the height of a row, in px
+     * @property {string} virtualize - specifies whether to enable virtualization. This requires the "role-based" render mode and a fixed-height container for lightning-datatable
      */
 
     /**
@@ -508,10 +516,21 @@ export default class LightningDatatable extends LightningElement {
 
     set renderConfig(value) {
         if (typeof value === 'object' && !isIE11) {
-            const enableViewportRendering = value.viewportRendering;
-            setViewportRendering(this.state, enableViewportRendering);
+            setViewportRendering(this.state, value.viewportRendering);
 
-            this._renderManager.configure(this, value);
+            this._renderManager.configure(
+                this.state,
+                this.getWrapperHeight,
+                value
+            );
+            // if renderConfig already exists, update rendering
+            if (this._renderConfig) {
+                this._renderManager.updateViewportRendering(
+                    this.state,
+                    this.gridContainer,
+                    true
+                );
+            }
             this._renderConfig = value;
         }
     }
@@ -536,6 +555,9 @@ export default class LightningDatatable extends LightningElement {
             validValues: ['default', 'role-based'],
         });
         this.state.renderModeRoleBased = this._renderMode === 'role-based';
+        if (this._renderConfig) {
+            setVirtualize(this.state, this._renderConfig.virtualize);
+        }
         updateCellClassForRoleBasedMode(this.state);
     }
 
@@ -759,24 +781,42 @@ export default class LightningDatatable extends LightningElement {
 
     get computedTableStyle() {
         if (this._columnWidthManager.isAutoResizingUpdateQueued()) {
-            return ['table-layout:auto'].join(';');
+            return styleToString(['table-layout:auto']);
         }
-        return [
+        return styleToString([
             'table-layout:fixed',
             getCSSWidthStyleOfTable(this.widthsData),
-        ].join(';');
+        ]);
     }
 
+    /**
+     * Resets row-number counter to offset to show
+     * correct value when row number column is present
+     * and adds necessary position and height styles when
+     * virtualization is enabled
+     */
     get computedTbodyStyle() {
+        const style = [];
+        const { firstVisibleIndex, bufferSize, virtualize, rows } = this.state;
         if (
             hasRowNumberColumn(this.state) &&
             getRowNumberOffset(this.state) >= 0
         ) {
-            return (
-                'counter-reset: row-number ' + getRowNumberOffset(this.state)
+            const firstRenderedRow = Math.max(
+                firstVisibleIndex - bufferSize,
+                0
+            );
+            const rowNumber = firstRenderedRow + getRowNumberOffset(this.state);
+            style.push(`counter-reset: row-number ${rowNumber}`);
+        }
+        if (virtualize) {
+            const length = rows.length;
+            style.push(
+                'position: relative',
+                `height:${length * DEFAULT_ROW_HEIGHT}px`
             );
         }
-        return '';
+        return styleToString(style);
     }
 
     /**
@@ -812,9 +852,7 @@ export default class LightningDatatable extends LightningElement {
             styles['overflow-x'] = 'auto';
         }
 
-        return Object.entries(styles)
-            .map(([key, value]) => key + ':' + value)
-            .join(';');
+        return styleToString(styles);
     }
 
     /**
@@ -897,10 +935,16 @@ export default class LightningDatatable extends LightningElement {
     }
 
     get renderedRows() {
+        const { virtualize, rows, renderedRowCount } = this.state;
+        if (virtualize) {
+            const { firstIndex, lastIndex } =
+                this._renderManager.getRenderedRange(this.state);
+            return rows.slice(firstIndex, lastIndex);
+        }
         if (this.viewportRendering && !isIE11) {
-            return this.state.rows.slice(0, this._renderedRowCount);
+            return rows.slice(0, renderedRowCount);
         }
-        return this.state.rows;
+        return rows;
     }
 
     get showSelectAllCheckbox() {
@@ -936,6 +980,7 @@ export default class LightningDatatable extends LightningElement {
         this.updateRowsAndCellIndexes = updateRowsAndCellIndexes.bind(this);
 
         this._renderManager = new RenderManager();
+        this.getWrapperHeight = getDTWrapperHeight.bind(this);
     }
 
     /**
@@ -1094,17 +1139,35 @@ export default class LightningDatatable extends LightningElement {
         this._customerSelectedRows = null;
         // set the previous focused cell to null after render is done
         resetCellToFocusFromPrev(state);
+        // reset focus styles on re-render
+        if (state.activeCell && state.activeCell.focused) {
+            const cellElement = getActiveCellElement(template, state);
+            if (
+                cellElement &&
+                cellElement.parentElement &&
+                !cellElement.parentElement.classList.contains(FOCUS_CLASS)
+            ) {
+                setFocusActiveCell(template, state, null, null, false);
+            }
+        }
 
-        if (this.viewportRendering) {
-            this._renderManager.connectResizeObserver(this);
+        if (this.viewportRendering || state.virtualize) {
+            const resizeTarget = this.template.querySelector(
+                'div.dt-outer-container'
+            );
+            this._renderManager.connectResizeObserver(resizeTarget);
             if (!this._renderManager.hasWrapperHeight()) {
-                this._renderManager.updateWrapperHeight(this);
+                this._renderManager.updateWrapperHeight(this.getWrapperHeight);
 
                 // Reset the row count if we already had one before updating the wrapper height.
                 // This can happen if the number of rows was calculated before the datatable
                 // was rendered.
-                if (this._renderedRowCount) {
-                    this._renderManager.updateViewportRendering(this, true);
+                if (this.state.renderedRowCount) {
+                    this._renderManager.updateViewportRendering(
+                        this.state,
+                        this.gridContainer,
+                        true
+                    );
                 }
             }
         }
@@ -1187,9 +1250,10 @@ export default class LightningDatatable extends LightningElement {
         }
 
         handleInlineEditPanelScroll.call(this, event);
-
-        if (this.viewportRendering) {
-            this._renderManager.handleScroll(this, event);
+        if (this.state.virtualize) {
+            setFirstVisibleIndex(this.state, event.target.scrollTop);
+        } else if (this.viewportRendering) {
+            this._renderManager.handleScroll(this.state, event);
         }
     }
 
@@ -1202,8 +1266,9 @@ export default class LightningDatatable extends LightningElement {
     handleCellClick(event) {
         // handles the case when clicking on the margin/pading of the td/th
         const targetTagName = event.target.tagName.toLowerCase();
+        const targetRole = event.target.getAttribute('role');
 
-        if (targetTagName === 'td' || targetTagName === 'th') {
+        if (isCellElement(targetTagName, targetRole)) {
             // get the row/col key value from the primitive cell.
             const { rowKeyValue, colKeyValue } =
                 event.target.querySelector(':first-child');
@@ -1464,8 +1529,11 @@ export default class LightningDatatable extends LightningElement {
 
         this.updateRowsAndCellIndexes(state);
 
-        if (this.viewportRendering) {
-            this._renderManager.updateViewportRendering(this);
+        if (this.viewportRendering || state.virtualize) {
+            this._renderManager.updateViewportRendering(
+                this.state,
+                this.gridContainer
+            );
         }
 
         this._columnWidthManager.handleRowNumberOffsetChange(state, widthsData);
@@ -1505,10 +1573,10 @@ export default class LightningDatatable extends LightningElement {
         setDirtyValues(state, this._draftValues);
         updateRowNavigationMode(hadTreeDataTypePreviously, state);
         state.headerIndexes = generateHeaderIndexes(getColumns(state));
-        // Updates state.wrapText and when isWrapableType, sets internal header actions
+        // Updates state.wrapText and when isWrappableType, sets internal header actions
         updateHeaderActions(state);
         this.updateRowsAndCellIndexes(state);
-        updateSelectionState(state);
+        updateBulkSelectionState(state);
         this._columnWidthManager.handleRowNumberOffsetChange(state, widthsData);
         updateColumnWidthsMetadata(getColumns(state), widthsData);
         // set the celltofocus next to null if the column still exists after indexes calculation

package/src/lightning/datatable/errors.js

@@ -1,25 +1,36 @@
-export function getErrorsState() {
-    return {
-        errors: {
-            rows: {},
-            table: {},
-        },
-    };
-}
+// Default empty error state
+const DEFAULT_ERROR_STATE = {
+    rows: {},
+    table: {},
+};
 
+/**
+ * Retrieves the errors object from datatable's state object
+ * Returns the set of row-level errors and table-level errors
+ */
 export function getErrors(state) {
     return state.errors;
 }
 
+/**
+ * Sets the row-level errors and table-level errors in datatable's state object
+ * Errors being set here overwrite the previous error object in the state
+ */
 export function setErrors(state, errors) {
-    return (state.errors = Object.assign({}, getErrorsState(), errors));
+    return (state.errors = Object.assign({}, DEFAULT_ERROR_STATE, errors));
 }
 
+/**
+ * Retrieves the row-level errors of a particular row from datatable's state object
+ */
 export function getRowError(state, rowKey) {
     const rows = getErrors(state).rows;
     return (rows && rows[rowKey]) || {};
 }
 
+/**
+ * Retrieves the table-level errors from the datatable's state object
+ */
 export function getTableError(state) {
     return getErrors(state).table || {};
 }

package/src/lightning/datatable/headerActions.js

@@ -1,49 +1,31 @@
 import { unwrap } from 'lwc';
 import { getUserColumnIndex, getColumns } from './columns';
-import * as wraptext from './wrapText';
+import { getActions, handleTriggeredAction } from './wrapText';
 
-function handleTriggeredInternalAction(dt, action, colKeyValue) {
-    wraptext.handleTriggeredAction(dt.state, action, colKeyValue);
-    dispatchHeaderActionEvent(dt, action, colKeyValue);
-}
-
-function handleTriggeredCustomerAction(dt, action, colKeyValue) {
-    dispatchHeaderActionEvent(dt, action, colKeyValue);
-}
+// Height of a clickable menu item
+const ACTION_REM_HEIGHT = 2.125;
 
-function dispatchHeaderActionEvent(dt, action, colKeyValue) {
-    const userColumnIndex = getUserColumnIndex(dt.state, colKeyValue);
-    const customerColumnDefinition = dt.columns[userColumnIndex];
-
-    dt.dispatchEvent(
-        new CustomEvent('headeraction', {
-            detail: {
-                action: unwrap(action),
-                columnDefinition: unwrap(customerColumnDefinition),
-            },
-        })
-    );
-}
+// Height of the menu divider, 1 rem + 1px (1/16px)
+const DIVIDER_REM_HEIGHT = 1.0625;
 
-function getMenuAlignment(columns, index) {
-    const isLastColumn = index === columns.length - 1;
-
-    return isLastColumn || columns[index + 1].type === 'action'
-        ? 'auto-right'
-        : 'auto-left';
-}
+/************************** PUBLIC METHODS ***************************/
 
+/**
+ * Merges wrapText internal actions.
+ * If there are new internal actions in the future, they may be added here.
+ *
+ * @param {Object} state The state of the datatable
+ * @param {Object} columnDefinition The column definition to extract internal actions from
+ * @return {Array} All wrapText internal actions
+ */
 export function getInternalActions(state, columnDefinition) {
-    // merge all internal actions here
-    // currently, only wrapText internal actions
-    // there may be new internal actions in the future
-    return [...wraptext.getActions(state, columnDefinition)];
+    return [...getActions(state, columnDefinition)];
 }
 
 /**
  * Overrides the actions with the internal ones, plus the customer ones.
  *
- * @param {Object} state The state of the datatable.
+ * @param {Object} state The state of the datatable
  */
 export function updateHeaderActions(state) {
     const columns = getColumns(state);
@@ -59,31 +41,36 @@ export function updateHeaderActions(state) {
     });
 }
 
+/**
+ * For internal actions, handles triggering the action.
+ * Then dispatches the header action event.
+ *
+ * @param {Event} event
+ */
 export function handleHeaderActionTriggered(event) {
+    event.stopPropagation();
+
     const { action, actionType, colKeyValue } = event.detail;
 
-    event.stopPropagation();
-    if (actionType === 'customer') {
-        handleTriggeredCustomerAction(this, action, colKeyValue);
-    } else {
-        handleTriggeredInternalAction(this, action, colKeyValue);
+    if (actionType !== 'customer') {
+        handleTriggeredAction(this.state, action, colKeyValue);
     }
-}
 
-export function getColumnActionsDefaultState() {
-    return Object.assign({}, wraptext.getDefaultState());
+    dispatchHeaderActionEvent(this, action, colKeyValue);
 }
 
-// in rem, the height of a clickable menu item
-const ACTION_HEIGHT = 2.125;
-// 1 rem + 1px (1/16px), height of the menu divider
-const DIVIDER_HEIGHT = 1.0625;
-
+/**
+ * Calculates the size and positioning of the header action
+ * menu when it is opened.
+ *
+ * @param {Event} event
+ */
 export function handleHeaderActionMenuOpening(event) {
     event.stopPropagation();
     event.preventDefault();
-    const actionsHeight = event.detail.actionsCount * ACTION_HEIGHT;
-    const dividersHeight = event.detail.dividersCount * DIVIDER_HEIGHT;
+
+    const actionsHeight = event.detail.actionsCount * ACTION_REM_HEIGHT;
+    const dividersHeight = event.detail.dividersCount * DIVIDER_REM_HEIGHT;
     const wrapperHeight = 1;
     this._actionsMinHeightStyle = `min-height:${
         actionsHeight + dividersHeight + wrapperHeight
@@ -91,6 +78,47 @@ export function handleHeaderActionMenuOpening(event) {
     event.detail.saveContainerPosition(this.getViewableRect());
 }
 
+/**
+ * Resets header action menu height when closed.
+ */
 export function handleHeaderActionMenuClosed() {
     this._actionsMinHeightStyle = '';
 }
+
+/************************** PRIVATE METHODS ***************************/
+
+/**
+ * Dispatches the `headeraction` event.
+ *
+ * @param {Object} dt The datatable
+ * @param {Object} action The action to dispatch
+ * @param {String} colKeyValue The column to dispatch the action on
+ */
+function dispatchHeaderActionEvent(dt, action, colKeyValue) {
+    const userColumnIndex = getUserColumnIndex(dt.state, colKeyValue);
+    const customerColumnDefinition = dt.columns[userColumnIndex];
+
+    dt.dispatchEvent(
+        new CustomEvent('headeraction', {
+            detail: {
+                action: unwrap(action),
+                columnDefinition: unwrap(customerColumnDefinition),
+            },
+        })
+    );
+}
+
+/**
+ * Determines the menu alignment based on column placement.
+ *
+ * @param {Array} columns Array of all the columns
+ * @param {Integer} index The current column index to check
+ * @return {String} The computed alignment
+ */
+function getMenuAlignment(columns, index) {
+    const isLastColumn = index === columns.length - 1;
+
+    return isLastColumn || columns[index + 1].type === 'action'
+        ? 'auto-right'
+        : 'auto-left';
+}