lightning-base-components 1.13.9-alpha → 1.14.3-alpha

package/src/lightning/primitiveDatatableIeditPanel/primitiveDatatableIeditPanel.js

@@ -1,4 +1,5 @@
 import { LightningElement, api } from 'lwc';
+import labelEdit from '@salesforce/label/LightningDatatable.edit';
 import labelUpdateSelectedItems from '@salesforce/label/LightningDatatable.updateSelectedItems';
 import labelCancel from '@salesforce/label/LightningDatatable.cancel';
 import labelApply from '@salesforce/label/LightningDatatable.apply';
@@ -6,12 +7,15 @@ import { InteractingState } from 'lightning/inputUtils';
 import { formatLabel } from 'lightning/utils';
 
 const i18n = {
+    edit: labelEdit,
     updateSelectedItems: labelUpdateSelectedItems,
     cancel: labelCancel,
     apply: labelApply,
 };
 
 export default class PrimitiveDatatableIeditPanel extends LightningElement {
+    /************************* PUBLIC PROPERTIES *************************/
+
     @api visible;
     @api rowKeyValue;
     @api colKeyValue;
@@ -21,14 +25,80 @@ export default class PrimitiveDatatableIeditPanel extends LightningElement {
     @api numberOfSelectedRows;
     @api resolvedTypeAttributes;
 
-    connectedCallback() {
-        this.interactingState = new InteractingState({
-            duration: 10,
-            debounceInteraction: true,
-        });
-        this.interactingState.onleave(() => this.handlePanelLoosedFocus());
+    /**
+     * Checked when opening an edit panel to see if it's valid
+     * Logs an error if type is custom but does not have the
+     * required editTemplate with [data-inputable="true"] element
+     */
+    @api
+    get isEditableValid() {
+        if (
+            !this.columnDef.editableCustomType ||
+            this.inputableElement.isEditableCustomValid
+        ) {
+            return true;
+        } else if (this.columnDef.editableCustomType) {
+            console.error(
+                'Editable custom types must define an editTemplate that includes an element with attribute data-inputable set to "true"'
+            );
+        }
+        return false;
+    }
+
+    /**
+     * Returns whether or not the mass edit update checkbox is selected
+     */
+    @api
+    get isMassEditChecked() {
+        return (
+            this.isMassEditEnabled &&
+            this.template.querySelector('[data-mass-selection="true"]').checked
+        );
     }
 
+    /**
+     * Returns the value of the input in the inline edit panel
+     * This is retrieved typically when processing inline edit completion
+     */
+    @api
+    get value() {
+        return this.inputableElement ? this.inputableElement.value : null;
+    }
+
+    /**
+     * Returns the validity state object of the input in the inline edit panel
+     */
+    @api
+    get validity() {
+        return this.inputableElement.validity;
+    }
+
+    /************************* PUBLIC METHODS *************************/
+
+    /**
+     * Focuses on the input element in the inline edit panel
+     */
+    @api
+    focus() {
+        const elem = this.inputableElement;
+        this.interactingState.enter();
+
+        if (elem) {
+            elem.focus();
+        }
+    }
+
+    /**
+     * Returns the <section> element which is the container of the
+     * positioned inline edit panel
+     */
+    @api
+    getPositionedElement() {
+        return this.template.querySelector('section');
+    }
+
+    /************************* PRIVATE GETTERS *************************/
+
     get computedStyle() {
         const styleHash = {
             'z-index': 1000,
@@ -43,29 +113,41 @@ export default class PrimitiveDatatableIeditPanel extends LightningElement {
             .join(';');
     }
 
+    get inputableElement() {
+        return this.template.querySelector('.dt-type-edit-factory');
+    }
+
     get inputKey() {
         return this.rowKeyValue + this.colKeyValue;
     }
 
+    get required() {
+        return (
+            this.columnDef.typeAttributes &&
+            this.columnDef.typeAttributes.required
+        );
+    }
+
     get massEditCheckboxLabel() {
         return formatLabel(i18n.updateSelectedItems, this.numberOfSelectedRows);
     }
 
-    get applyLabel() {
-        return i18n.apply;
+    get dialogAriaLabel() {
+        const columnName = this.columnDef.label;
+        return `${i18n.edit} ${columnName}`;
     }
 
-    get cancelLabel() {
-        return i18n.cancel;
+    get i18n() {
+        return i18n;
     }
 
-    get required() {
-        return (
-            this.columnDef.typeAttributes &&
-            this.columnDef.typeAttributes.required
-        );
-    }
+    /************************* EVENT HANDLERS *************************/
 
+    /**
+     * Handles tabbing backwards out of the inline edit panel from the first form element.
+     * If mass edit is enabled, this will set the focus on the last element in the panel - traps focus.
+     * If mass edit is not enabled, it will process completion of inline edit
+     */
     handleFormStartFocus() {
         this.interactingState.enter();
 
@@ -79,6 +161,11 @@ export default class PrimitiveDatatableIeditPanel extends LightningElement {
         }
     }
 
+    /**
+     * Handles tabbing forwards out of the inline edit panel from the last form element.
+     * If mass edit is enabled, this will set focus on the first element in the panel - traps focus.
+     * If mass edit is not enabled, it will process the completion of inline edit
+     */
     handleFormEndsFocus() {
         this.interactingState.enter();
 
@@ -92,51 +179,20 @@ export default class PrimitiveDatatableIeditPanel extends LightningElement {
         }
     }
 
-    triggerEditFinished(detail) {
-        detail.rowKeyValue = detail.rowKeyValue || this.rowKeyValue;
-        detail.colKeyValue = detail.colKeyValue || this.colKeyValue;
-
-        const event = new CustomEvent('ieditfinished', {
-            detail,
-        });
-        this.dispatchEvent(event);
-    }
-
-    @api
-    focus() {
-        const elem = this.inputableElement;
-        this.interactingState.enter();
-
-        if (elem) {
-            elem.focus();
+    /**
+     * This is executed when interactingState.leave is triggered
+     * which happens when the inline edit panel loses focus
+     */
+    handlePanelLostFocus() {
+        if (this.visible) {
+            this.triggerEditFinished({
+                reason: 'lost-focus',
+            });
         }
     }
 
-    get inputableElement() {
-        return this.template.querySelector('.dt-type-edit-factory');
-    }
-
-    @api
-    get value() {
-        return this.inputableElement ? this.inputableElement.value : null;
-    }
-
-    @api
-    get validity() {
-        return this.inputableElement.validity;
-    }
-
-    @api
-    get isMassEditChecked() {
-        return (
-            this.isMassEditEnabled &&
-            this.template.querySelector('[data-mass-selection="true"]').checked
-        );
-    }
-
-    @api
-    getPositionedElement() {
-        return this.template.querySelector('section');
+    handleTypeElemFocus() {
+        this.interactingState.enter();
     }
 
     handleTypeElemBlur() {
@@ -145,10 +201,6 @@ export default class PrimitiveDatatableIeditPanel extends LightningElement {
         }
     }
 
-    handleTypeElemFocus() {
-        this.interactingState.enter();
-    }
-
     handleEditFormSubmit(event) {
         event.preventDefault();
         event.stopPropagation();
@@ -160,24 +212,71 @@ export default class PrimitiveDatatableIeditPanel extends LightningElement {
         return false;
     }
 
+    /**
+     * If the Escape key is pressed on the inline edit panel,
+     * we prevent default action, stop propagation of the event
+     * and close the inline edit panel
+     *
+     * @param {KeyboardEvent} event - keydown
+     */
     handleCellKeydown(event) {
         const { keyCode } = event;
 
         if (keyCode === 27) {
             // Esc key
+            event.preventDefault();
             event.stopPropagation();
-            this.cancelEdition();
+            this.cancelEditing();
         }
     }
 
-    handlePanelLoosedFocus() {
-        if (this.visible) {
-            this.triggerEditFinished({
-                reason: 'loosed-focus',
-            });
-        }
+    /************************* EVENT DISPATCHERS *************************/
+
+    /**
+     * Change handler for the mass edit checkbox.
+     * Dispatches the `masscheckboxchange` event along with the new checked value
+     *
+     * @param {CustomEvent} event - `change` event from lightning-input
+     */
+    handleMassCheckboxChange(event) {
+        const customEvent = new CustomEvent('masscheckboxchange', {
+            detail: {
+                checked: event.detail.checked,
+            },
+        });
+
+        this.dispatchEvent(customEvent);
+    }
+
+    /**
+     * Dispatches the `ieditfinished` event with the detail object containing
+     * the reason for inline edit finishing and the rowKeyValue and colKeyValue
+     * with which the particular cell which was edited can be identified.
+     *
+     * @param {Object} detail - typically contains the reason for inline edit finishing
+     */
+    triggerEditFinished(detail) {
+        detail.rowKeyValue = detail.rowKeyValue || this.rowKeyValue;
+        detail.colKeyValue = detail.colKeyValue || this.colKeyValue;
+
+        const event = new CustomEvent('ieditfinished', {
+            detail,
+        });
+        this.dispatchEvent(event);
     }
 
+    /************************* LIFECYCLE HOOKS *************************/
+
+    connectedCallback() {
+        this.interactingState = new InteractingState({
+            duration: 10,
+            debounceInteraction: true,
+        });
+        this.interactingState.onleave(() => this.handlePanelLostFocus());
+    }
+
+    /************************* HELPER FUNCTIONS *************************/
+
     focusLastElement() {
         this.template.querySelector('[data-form-last-element="true"]').focus();
     }
@@ -190,19 +289,9 @@ export default class PrimitiveDatatableIeditPanel extends LightningElement {
         }
     }
 
-    cancelEdition() {
+    cancelEditing() {
         this.triggerEditFinished({
             reason: 'edit-canceled',
         });
     }
-
-    handleMassCheckboxChange(event) {
-        const customEvent = new CustomEvent('masscheckboxchange', {
-            detail: {
-                checked: event.detail.checked,
-            },
-        });
-
-        this.dispatchEvent(customEvent);
-    }
 }

package/src/lightning/primitiveDatatableIeditTypeFactory/primitiveDatatableIeditTypeFactory.js

@@ -13,7 +13,7 @@ import DateLocalTpl from './dateLocal.html';
 import DateTpl from './date.html';
 import DefaultTpl from './default.html';
 
-const TYPE_TPL_MAPPINGS = {
+const TYPE_TEMPLATE_MAPPINGS = {
     text: TextTpl,
     phone: PhoneTpl,
     email: EmailTpl,
@@ -25,10 +25,14 @@ const TYPE_TPL_MAPPINGS = {
     'date-local': DateLocalTpl,
     date: DateTpl,
 };
-const INVALID_TYPE_FOR_EDIT = 'column type not supported for inline edit';
+const INVALID_TYPE_MESSAGE = 'column type not supported for inline edit';
 
 export default class LightningPrimitiveDatatableIeditTypeFactory extends LightningElement {
+    // Private Variables
     columnLabel;
+
+    /***************************** PUBLIC PROPERTIES *****************************/
+
     @api editedValue;
     @api required;
     @api typeAttributes;
@@ -41,54 +45,23 @@ export default class LightningPrimitiveDatatableIeditTypeFactory extends Lightni
     set columnDef(value) {
         assert(
             // eslint-disable-next-line no-prototype-builtins
-            TYPE_TPL_MAPPINGS.hasOwnProperty(value.type) ||
+            TYPE_TEMPLATE_MAPPINGS.hasOwnProperty(value.type) ||
                 value.editableCustomType,
-            INVALID_TYPE_FOR_EDIT
+            INVALID_TYPE_MESSAGE
         );
 
         this._columnDef = value;
         this.columnLabel = value.label;
     }
 
-    get columnType() {
-        return this._columnDef.type;
-    }
-
-    render() {
-        return this.isValidCustomType
-            ? this.customEditTemplate
-            : TYPE_TPL_MAPPINGS[this.columnType] || DefaultTpl;
-    }
-
-    connectedCallback() {
-        this._blurHandler = this.handleComponentBlur.bind(this);
-        this._focusHandler = this.handleComponentFocus.bind(this);
-        this._changeHandler = this.handleComponentChange.bind(this);
-    }
-
-    renderedCallback() {
-        if (this.concreteComponent) {
-            this.concreteComponent.addEventListener('blur', this._blurHandler);
-            this.concreteComponent.addEventListener(
-                'focus',
-                this._focusHandler
-            );
-            this.concreteComponent.addEventListener(
-                'change',
-                this._changeHandler
-            );
-        }
-    }
-
-    get concreteComponent() {
-        return this.template.querySelector('[data-inputable="true"]');
-    }
-
+    /**
+     * Checks if type is an custom type that is editable and
+     * has an editTemplate that contains [data-inputable="true"]
+     * Used when checking if cell can actually be edited
+     */
     @api
-    focus() {
-        if (this.concreteComponent) {
-            this.concreteComponent.focus();
-        }
+    get isEditableCustomValid() {
+        return this.isValidCustomType && this.concreteComponent;
     }
 
     @api
@@ -104,11 +77,47 @@ export default class LightningPrimitiveDatatableIeditTypeFactory extends Lightni
         return this.concreteComponent.validity;
     }
 
+    /***************************** PUBLIC METHODS *****************************/
+
+    /**
+     * Focuses on the input component that is rendered by the type factory
+     */
+    @api
+    focus() {
+        if (this.concreteComponent) {
+            this.concreteComponent.focus();
+        }
+    }
+
+    /**
+     * Displays error message if the input is invalid
+     */
     @api
     showHelpMessageIfInvalid() {
         this.concreteComponent.showHelpMessageIfInvalid();
     }
 
+    /***************************** PRIVATE GETTERS *****************************/
+
+    get columnType() {
+        return this._columnDef.type;
+    }
+
+    get concreteComponent() {
+        return this.template.querySelector('[data-inputable="true"]');
+    }
+
+    /**
+     * Returns editTemplate defined for custom type template
+     */
+    get customEditTemplate() {
+        return this._columnDef.editTemplate;
+    }
+
+    /**
+     * Retrieves the date set in the column and converts it to a value
+     * that can be passed into lightning-input type="datetime"
+     */
     get editedDateValue() {
         const dateValue = new Date(this.editedValue);
 
@@ -119,6 +128,30 @@ export default class LightningPrimitiveDatatableIeditTypeFactory extends Lightni
         return dateValue.toISOString();
     }
 
+    /**
+     * Checks this custom type is editable and has editTemplate defined
+     */
+    get isValidCustomType() {
+        return (
+            this._columnDef.editableCustomType && this._columnDef.editTemplate
+        );
+    }
+
+    /**
+     * For percent, currency types use if step passed in, if not fallback to default
+     * @returns {*|string}
+     */
+    get typeAttributeStep() {
+        return (
+            (this._columnDef &&
+                this._columnDef.typeAttributes &&
+                this._columnDef.typeAttributes.step) ||
+            '0.01'
+        );
+    }
+
+    /***************************** EVENT HANDLERS *****************************/
+
     handleComponentFocus() {
         this.dispatchEvent(new CustomEvent('focus'));
     }
@@ -131,32 +164,34 @@ export default class LightningPrimitiveDatatableIeditTypeFactory extends Lightni
         this.showHelpMessageIfInvalid();
     }
 
-    /**
-     * Returns editTemplate defined for custom type template
-     */
-    get customEditTemplate() {
-        return this._columnDef.editTemplate;
-    }
+    /***************************** LIFECYCLE HOOKS *****************************/
 
     /**
-     * for percent, currency types use if step passed in, if not fallback to default
-     * @returns {*|string}
+     * Renders the appropriate template based on the column type
      */
-    get typeAttributeStep() {
-        return (
-            (this._columnDef &&
-                this._columnDef.typeAttributes &&
-                this._columnDef.typeAttributes.step) ||
-            '0.01'
-        );
+    render() {
+        return this.isValidCustomType
+            ? this.customEditTemplate
+            : TYPE_TEMPLATE_MAPPINGS[this.columnType] || DefaultTpl;
     }
 
     /**
-     * Checks this custom type is editable and has editTemplate defined
+     * Attaches event handlers for `focus`, `blur` and `change` events
      */
-    get isValidCustomType() {
-        return (
-            this._columnDef.editableCustomType && this._columnDef.editTemplate
-        );
+    renderedCallback() {
+        if (this.concreteComponent) {
+            this.concreteComponent.addEventListener(
+                'focus',
+                this.handleComponentFocus.bind(this)
+            );
+            this.concreteComponent.addEventListener(
+                'blur',
+                this.handleComponentBlur.bind(this)
+            );
+            this.concreteComponent.addEventListener(
+                'change',
+                this.handleComponentChange.bind(this)
+            );
+        }
     }
 }

package/src/lightning/primitiveDatatableStatusBar/primitiveDatatableStatusBar.html

@@ -2,6 +2,7 @@
     <div class="slds-docked-form-footer slds-is-absolute">
         <div class="slds-grid slds-grid_align-center">
             <template if:true={showError}>
+                <!-- Error Tooltip -->
                 <lightning-primitive-datatable-tooltip
                     class="slds-button"
                     size="small"
@@ -12,18 +13,17 @@
                     offset={bubbleOffset}
                 ></lightning-primitive-datatable-tooltip>
             </template>
+            <!-- Cancel and Save Buttons -->
             <button
                 type="button"
                 class="slds-button slds-button_neutral"
-                onclick={handleCancelButtonClick}
-            >
+                onclick={handleCancelButtonClick}>
                 {i18n.cancel}
             </button>
             <button
                 type="button"
                 class="slds-button slds-button_brand save-btn"
-                onclick={handleSaveButtonClick}
-            >
+                onclick={handleSaveButtonClick}>
                 {i18n.save}
             </button>
         </div>

package/src/lightning/primitiveDatatableStatusBar/primitiveDatatableStatusBar.js

@@ -47,6 +47,10 @@ export default class LightningPrimitiveDatatableStatusBar extends LightningEleme
         };
     }
 
+    isSaveBtnFocused() {
+        return this.template.querySelector('button.save-btn:focus') !== null;
+    }
+
     handleCancelButtonClick(event) {
         event.preventDefault();
         event.stopPropagation();
@@ -78,10 +82,6 @@ export default class LightningPrimitiveDatatableStatusBar extends LightningEleme
         );
     }
 
-    isSaveBtnFocused() {
-        return this.template.querySelector('button.save-btn:focus') !== null;
-    }
-
     /**
      * Handling between displaying/focusing tooltip icon and/or error bubble
      * If showBubble property is set within error object, display/focus the error bubble.