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

package/src/lightning/primitiveDatatableIeditPanel/primitiveDatatableIeditPanel.html

@@ -3,19 +3,21 @@
         if:true={visible}
         class="slds-popover slds-popover_edit"
         role="dialog"
+        aria-label={dialogAriaLabel}
         tabindex="-1"
         onblur={handleTypeElemBlur}
         onfocus={handleTypeElemFocus}
         onkeydown={handleCellKeydown}
-        style={computedStyle}
-    >
+        style={computedStyle}>
+
         <span class="inline-edit-form-start" tabindex="0" onfocus={handleFormStartFocus}></span>
         <div class="slds-popover__body">
             <form onsubmit={handleEditFormSubmit} novalidate>
+                <!-- Renders the required indicator -->
                 <lightning-primitive-datatable-iedit-input-wrapper
                     required={required}
-                    class="slds-grid slds-p-left_xx-small"
-                >
+                    class="slds-grid slds-p-left_xx-small">
+                    <!-- Renders the appropriate input type in the inline edit panel -->
                     <lightning-primitive-datatable-iedit-type-factory
                         required={required}
                         class="dt-type-edit-factory slds-col"
@@ -24,10 +26,11 @@
                         edited-value={editedValue}
                         onblur={handleTypeElemBlur}
                         onfocus={handleTypeElemFocus}
-                        key={inputKey}
-                    ></lightning-primitive-datatable-iedit-type-factory>
+                        key={inputKey}>
+                    </lightning-primitive-datatable-iedit-type-factory>
                 </lightning-primitive-datatable-iedit-input-wrapper>
                 <template if:true={isMassEditEnabled}>
+                    <!-- Checkbox to select in order to mass edit multiple rows -->
                     <lightning-input
                         data-mass-selection="true"
                         type="checkbox"
@@ -35,32 +38,32 @@
                         label={massEditCheckboxLabel}
                         onchange={handleMassCheckboxChange}
                         onblur={handleTypeElemBlur}
-                        onfocus={handleTypeElemFocus}
-                    ></lightning-input>
+                        onfocus={handleTypeElemFocus}>
+                    </lightning-input>
                 </template>
                 <template if:false={isMassEditEnabled}>
                     <button type="submit" aria-hidden="true" tabindex="-1" class="slds-hide" value="save"></button>
                 </template>
             </form>
         </div>
+        <!-- If in mass edit mode, render 'Cancel' and 'Apply' buttons -->
         <template if:true={isMassEditEnabled}>
             <div class="slds-popover__footer">
                 <div class="slds-grid slds-grid_align-end">
                     <lightning-button
-                        label={cancelLabel}
+                        label={i18n.cancel}
                         onblur={handleTypeElemBlur}
                         onfocus={handleTypeElemFocus}
-                        onclick={cancelEdition}
-                    ></lightning-button>
+                        onclick={cancelEditing}>
+                    </lightning-button>
                     <lightning-button
-                        label={applyLabel}
+                        label={i18n.apply}
                         style="margin-left: .25rem"
                         variant="brand"
                         onblur={handleTypeElemBlur}
                         onfocus={handleTypeElemFocus}
                         data-form-last-element="true"
-                        onclick={processSubmission}
-                    >
+                        onclick={processSubmission}>
                     </lightning-button>
                 </div>
             </div>

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,71 +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();
-        }
-    }
-
-    get inputableElement() {
-        return this.template.querySelector('.dt-type-edit-factory');
-    }
-
     /**
-     * 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
+     * This is executed when interactingState.leave is triggered
+     * which happens when the inline edit panel loses focus
      */
-    @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"'
-            );
+    handlePanelLostFocus() {
+        if (this.visible) {
+            this.triggerEditFinished({
+                reason: 'lost-focus',
+            });
         }
-        return false;
-    }
-
-    @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() {
@@ -165,10 +201,6 @@ export default class PrimitiveDatatableIeditPanel extends LightningElement {
         }
     }
 
-    handleTypeElemFocus() {
-        this.interactingState.enter();
-    }
-
     handleEditFormSubmit(event) {
         event.preventDefault();
         event.stopPropagation();
@@ -180,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();
     }
@@ -210,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,27 +128,17 @@ export default class LightningPrimitiveDatatableIeditTypeFactory extends Lightni
         return dateValue.toISOString();
     }
 
-    handleComponentFocus() {
-        this.dispatchEvent(new CustomEvent('focus'));
-    }
-
-    handleComponentBlur() {
-        this.dispatchEvent(new CustomEvent('blur'));
-    }
-
-    handleComponentChange() {
-        this.showHelpMessageIfInvalid();
-    }
-
     /**
-     * Returns editTemplate defined for custom type template
+     * Checks this custom type is editable and has editTemplate defined
      */
-    get customEditTemplate() {
-        return this._columnDef.editTemplate;
+    get isValidCustomType() {
+        return (
+            this._columnDef.editableCustomType && this._columnDef.editTemplate
+        );
     }
 
     /**
-     * for percent, currency types use if step passed in, if not fallback to default
+     * For percent, currency types use if step passed in, if not fallback to default
      * @returns {*|string}
      */
     get typeAttributeStep() {
@@ -151,22 +150,48 @@ export default class LightningPrimitiveDatatableIeditTypeFactory extends Lightni
         );
     }
 
+    /***************************** EVENT HANDLERS *****************************/
+
+    handleComponentFocus() {
+        this.dispatchEvent(new CustomEvent('focus'));
+    }
+
+    handleComponentBlur() {
+        this.dispatchEvent(new CustomEvent('blur'));
+    }
+
+    handleComponentChange() {
+        this.showHelpMessageIfInvalid();
+    }
+
+    /***************************** LIFECYCLE HOOKS *****************************/
+
     /**
-     * Checks this custom type is editable and has editTemplate defined
+     * Renders the appropriate template based on the column type
      */
-    get isValidCustomType() {
-        return (
-            this._columnDef.editableCustomType && this._columnDef.editTemplate
-        );
+    render() {
+        return this.isValidCustomType
+            ? this.customEditTemplate
+            : TYPE_TEMPLATE_MAPPINGS[this.columnType] || DefaultTpl;
     }
 
     /**
-     * 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
+     * Attaches event handlers for `focus`, `blur` and `change` events
      */
-    @api
-    get isEditableCustomValid() {
-        return this.isValidCustomType && this.concreteComponent;
+    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)
+            );
+        }
     }
 }