lightning-base-components 1.14.3-alpha → 1.15.1-alpha

package/src/lightning/confirm/__docs__/confirm.md

@@ -0,0 +1,100 @@
+The `lightning/confirm` module lets you create a confirm modal within your component. Use `LightningConfirm` on your component to ask the user to respond before they continue.
+
+`lightning/confirm` is not supported on mobile devices.
+
+Use `LightningConfirm.open()` instead of the native `window.confirm()` for a more consistent user experience. They have similar functions, but `LightningConfirm.open()` works in cross-origin iframes, where the `.confirm()` method is no longer supported in Chrome and Safari. Unlike `window.confirm()`, `LightningConfirm.open()` doesn't halt execution on the page, it returns a Promise. Use `async`/`await` or `.then()` for any code you want to execute after the confirm has closed.
+
+Import `LightningConfirm` from the `lightning/confirm` module in the component that will launch the confirm modal, and call `LightningConfirm.open()` with your desired attributes.
+
+This example creates a headerless confirm modal with two buttons, **OK** and **Cancel**. The `.open()` function returns a promise that resolves to true when you click **OK** and false when you  click **Cancel**.
+
+```html
+<!-- c/myApp.html -->
+<template>
+    <lightning-button onclick="{handleConfirmClick}" label="Open Confirm Modal">
+    </lightning-button>
+</template>
+```
+
+```javascript
+import { LightningElement } from 'lwc';
+import LightningConfirm from 'lightning/confirm';
+
+export default class MyApp extends LightningElement {
+    async handleConfirmClick() {
+        const result = await LightningConfirm.open({
+            message: 'this is the prompt message',
+            variant: 'headerless',
+            label: 'this is the aria-label value',
+            // setting theme would have no effect
+        });
+        //Confirm has been closed
+        //result is true if OK was clicked
+        //and false if cancel was clicked
+    }
+}
+```
+
+#### Component Styling
+
+This component uses the Salesforce Lightning Design System (SLDS) [`prompt` blueprint](https://www.lightningdesignsystem.com/components/prompt/#site-main-content).
+
+`LightningConfirm` supports the following attributes:
+
+-   `message`: Message text that displays in the confirm.
+-   `label`: Header text, also used as the `aria-label`. Default string is `Confirm`.
+-   `variant`: Two values, `header` and `headerless`. Default value is `header`.
+-   `theme`: Color theme for the header. The `theme` attribute supports the following [options](https://www.lightningdesignsystem.com/utilities/themes/#site-main-content) from SLDS:
+    -   `default`: white
+    -   `shade`: gray
+    -   `inverse`: dark blue
+    -   `alt-inverse`: darker blue
+    -   `success`: green
+    -   `info`: gray-ish blue
+    -   `warning`: yellow
+    -   `error`: red
+    -   `offline`: ​black​
+
+If an invalid value is provided, `LightningConfirm` uses the `default` theme.
+
+#### Testing Your Component's Confirm
+
+Code using `LightningConfirm` can be tested by mocking the `LightningConfirm.open()` method.
+
+The example below uses a button to open a confirm dialog and sets the result in a template.
+
+```html
+<button data-button onclick="{handleClick}">Open Confirm</button>
+<div data-result>{result}</div>
+```
+
+```js
+import LightningConfirm from 'lightning/confirm';
+jest.mock('lightning/confirm');
+​
+test(() => {
+    // Create and appendChild(element)
+​
+    const buttonEle = element.shadowRoot.querySelector('[data-button]');
+    const resultEle = element.shadowRoot.querySelector('[data-result]');
+​
+    // Mock .open()
+    // Pass true if testing when user clicks "OK"
+    // Pass false if testing when user clicks "Cancel"
+    LightningConfirm.open = jest.fn().mockResolvedValue(true);
+    // Initial value
+    expect(resultEle.textContent).toBe('unknown');
+    // Click modal open button
+    buttonEle.click();
+​
+    // Click handler render cycle
+    await Promise.resolve();
+    // Render cycle triggered by tracked value {result}
+    await Promise.resolve();
+​
+    // Verify result is set in the template
+    expect(resultEle.textContent).toBe('true');
+    // Open triggered once
+    expect(LightningConfirm.open.mock.calls).toHaveLength(1);
+})
+```

package/src/lightning/confirm/__examples__disabled/basic/basic.css

@@ -0,0 +1,7 @@
+.example {
+    margin: 0.5rem;
+    border-radius: 0.5rem;
+    background: #FFF;
+    box-shadow: 0 1px 0.25rem rgba(0, 0, 0, 0.2);
+    padding: 1rem;
+}

package/src/lightning/confirm/__examples__disabled/basic/basic.html

@@ -0,0 +1,8 @@
+<template>
+    <div class="example">
+        <button
+            aria-haspopup="modal"
+            onclick={handleConfirmModal}
+        >Open the Confirm Modal</button>
+    </div>
+</template>

package/src/lightning/confirm/__examples__disabled/basic/basic.js

@@ -0,0 +1,14 @@
+import { LightningElement } from 'lwc';
+import LightningConfirm from 'lightning/confirm';
+
+export default class ConfirmBasic extends LightningElement {
+    handleConfirmModal() {
+        LightningConfirm.open({
+            message: 'this is the confirm message',
+            label: 'Please Confirm',
+            theme: 'warning',
+        }).then((result) => {
+            console.log('confirm result', result);
+        });
+    }
+}

package/src/lightning/confirm/confirm.html

@@ -0,0 +1,3 @@
+<template>
+    <p>{message}</p>
+</template>

package/src/lightning/confirm/confirm.js

@@ -0,0 +1,80 @@
+import { api } from 'lwc';
+import LightningInteractiveDialogBase from 'lightning/interactiveDialogBase';
+import { parent, instanceName, secure } from 'lightning/overlayUtils';
+import LightningOverlay from 'lightning/overlay';
+import labelDefault from '@salesforce/label/LightningConfirm.defaultLabel';
+
+/**
+ * Create a confirm modal within your component that asks the user
+ * to respond before they continue.
+ */
+
+export default class LightningConfirm extends LightningOverlay {
+    static [instanceName] = 'lightning-confirm';
+    static [parent] = LightningInteractiveDialogBase;
+
+    /**
+     * value to use for header text in "header" variant
+     * or aria-label in "headerless" variant
+     * @type {string}
+     * @default "Confirm" (translated accordingly)
+     */
+    @api label = labelDefault;
+
+    /**
+     * text to display in body of modal
+     */
+    @api message = '';
+
+    /**
+     * variant to use for alert; may be
+     * set to "header" or "headerless"
+     */
+    @api variant = 'header';
+
+    /**
+     * theme to use when variant is "header"
+     * valid values are based on SLDS themes and are
+     * listed in "themeOptions" of interactiveDialogBase.js
+     */
+    @api theme = 'default';
+
+    /**
+     * Dispatches privateclose event
+     * and closes dialog
+     */
+    close(result) {
+        const promise = new Promise((resolve) => {
+            this.dispatchEvent(
+                new CustomEvent('privateclose', {
+                    detail: {
+                        resolve,
+                        [secure]: true,
+                    },
+                    bubbles: true,
+                })
+            );
+        });
+        super.close(result, promise);
+    }
+
+    /**
+     * Dispatches privatechildrender event
+     * with data parent needs to correctly render
+     */
+    renderedCallback() {
+        const evt = new CustomEvent('privatechildrender', {
+            bubbles: true,
+            detail: {
+                message: this.message,
+                label: this.label,
+                hideCancel: false,
+                showDescription: true,
+                getOkValue: () => true,
+                getCancelValue: () => false,
+                role: 'alertdialog',
+            },
+        });
+        this.dispatchEvent(evt);
+    }
+}

package/src/lightning/confirm/confirm.js-meta.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <isExposed>true</isExposed>
+    <minApiVersion>54.0</minApiVersion>
+    <support>GA</support>
+</LightningComponentBundle>

package/src/lightning/datatable/__examples__/withInfiniteLoading/fetchDataHelper.js

@@ -0,0 +1,21 @@
+const recordMetadata = {
+    name: 'name',
+    email: 'email',
+    website: 'url',
+    amount: 'currency',
+    phone: 'phoneNumber',
+    closeAt: 'dateInFuture',
+};
+
+export default function fetchData(amountOfRecords) {
+    return fetch('https://data-faker.herokuapp.com/collection', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json; charset=utf-8',
+        },
+        body: JSON.stringify({
+            amountOfRecords,
+            recordMetadata,
+        }),
+    }).then((response) => response.json());
+}

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

@@ -0,0 +1,13 @@
+<template>
+    <p>Total Rows: {data.length}</p>
+    <div style="height: 300px;">
+        <lightning-datatable
+            key-field="id"
+            data={data}
+            columns={columns}
+            enable-infinite-loading
+            onloadmore={handleLoadMore}>
+        </lightning-datatable>
+    </div>
+    <p>{loadMoreStatus}</p>
+</template>

package/src/lightning/datatable/__examples__/withInfiniteLoading/withInfiniteLoading.js

@@ -0,0 +1,42 @@
+import { LightningElement } from 'lwc';
+import fetchData from './fetchDataHelper';
+
+const columns = [
+    { label: 'Label', fieldName: 'name' },
+    { label: 'Website', fieldName: 'website', type: 'url' },
+    { label: 'Phone', fieldName: 'phone', type: 'phone' },
+    { label: 'Balance', fieldName: 'amount', type: 'currency' },
+    { label: 'CloseAt', fieldName: 'closeAt', type: 'date' },
+];
+
+export default class DatatableWithInfiniteLoading extends LightningElement {
+    data = [];
+    columns = columns;
+    loadMoreStatus;
+    totalNumberOfRows = 250;
+
+    // eslint-disable-next-line @lwc/lwc/no-async-await
+    async connectedCallback() {
+        const data = await fetchData(100);
+        this.data = data;
+    }
+
+    // eslint-disable-next-line @lwc/lwc/no-async-await
+    async handleLoadMore(event) {
+        const datatable = event.target;
+        //Displays a spinner to signal that data is being loaded
+        datatable.isLoading = true;
+        //Displays "Loading" text when more data is being loaded
+        this.loadMoreStatus = 'Loading';
+
+        const newData = await fetchData(50);
+        if (this.data.length >= this.totalNumberOfRows) {
+            datatable.enableInfiniteLoading = false;
+            this.loadMoreStatus = 'No more data to load';
+        } else {
+            this.data = this.data.concat(newData);
+            this.loadMoreStatus = '';
+        }
+        datatable.isLoading = false;
+    }
+}

package/src/lightning/datatable/__wdio__/utam/utam.html

@@ -0,0 +1,17 @@
+<template>
+    <div style="height:160px">
+        <lightning-datatable
+            key-field="id"
+            columns={columns}
+            data={data}
+            default-sort-direction={defaultSortDirection}
+            sorted-direction={sortDirection}
+            sorted-by={sortedBy}
+            onsort={onHandleSort}
+            is-loading={loading}>
+        </lightning-datatable>
+    </div>
+    
+    <lightning-button label="Enable Loading State" onclick={handleLoadingClick}></lightning-button>
+    <lightning-button label="Add More Rows" onclick={handleMoreRowsClick}></lightning-button>
+</template>

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

@@ -0,0 +1,91 @@
+import { LightningElement } from 'lwc';
+
+const data = [
+    { id: 1, name: 'Billy Simmons', age: 40, email: 'billy@salesforce.com' },
+    { id: 2, name: 'Kelsey Denesik', age: 35, email: 'kelsey@salesforce.com' },
+    { id: 3, name: 'Kyle Ruecker', age: 50, email: 'kyle@salesforce.com' },
+    {
+        id: 4,
+        name: 'Krystina Kerluke',
+        age: 37,
+        email: 'krystina@salesforce.com',
+    },
+];
+
+const actions = [
+    { label: 'Show details', name: 'show_details' },
+    { label: 'Delete', name: 'delete' },
+];
+
+const columns = [
+    { label: 'Name', fieldName: 'name' },
+    {
+        label: 'Age',
+        fieldName: 'age',
+        type: 'number',
+        sortable: true,
+        cellAttributes: { alignment: 'left' },
+    },
+    {
+        label: 'Email',
+        fieldName: 'email',
+        type: 'email',
+        hideDefaultActions: true,
+    },
+    {
+        type: 'action',
+        typeAttributes: { rowActions: actions, menuAlignment: 'right' },
+    },
+];
+
+export default class DemoApp extends LightningElement {
+    data = data;
+    columns = columns;
+    defaultSortDirection = 'asc';
+    sortDirection = 'asc';
+    sortedBy;
+    loading = false;
+
+    // Used to sort the 'Age' column
+    sortBy(field, reverse, primer) {
+        const key = primer
+            ? function (x) {
+                  return primer(x[field]);
+              }
+            : function (x) {
+                  return x[field];
+              };
+
+        return function (a, b) {
+            a = key(a);
+            b = key(b);
+            return reverse * ((a > b) - (b > a));
+        };
+    }
+
+    onHandleSort(event) {
+        const { fieldName: sortedBy, sortDirection } = event.detail;
+        const cloneData = [...this.data];
+
+        cloneData.sort(this.sortBy(sortedBy, sortDirection === 'asc' ? 1 : -1));
+        this.data = cloneData;
+        this.sortDirection = sortDirection;
+        this.sortedBy = sortedBy;
+    }
+
+    handleLoadingClick() {
+        this.loading = !this.loading;
+    }
+
+    handleMoreRowsClick() {
+        const control = [
+            {
+                id: 20,
+                name: 'Jacqueline Palmer',
+                age: 60,
+                email: 'jacqueline@salesforce.com',
+            },
+        ];
+        this.data = this.data.concat(this.data).concat(control);
+    }
+}

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

@@ -0,0 +1,189 @@
+const Datatable = require('pageobjects/datatable');
+const Button = require('pageobjects/button');
+
+describe('datatable utam test', () => {
+    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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        const dt = await root.shadow$('lightning-datatable');
+        const columnHeader = await dt.shadow$('thead > tr > th:nth-child(2)');
+        const expectedWidth = await columnHeader.getAttribute('style');
+        expect(await datatable.getWidth('Name')).toBe(expectedWidth);
+    });
+    it('should tell whether or not a column has header actions', async () => {
+        const datatable = await utam.load(Datatable, {
+            element: await root.shadow$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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$('lightning-datatable'),
+        });
+
+        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);
+    });
+});