lightning-base-components 1.14.6-alpha → 1.15.1-alpha

package/src/lightning/prompt/__docs__/prompt.md

@@ -0,0 +1,102 @@
+The `lightning/prompt` module lets you create an prompt modal within your component. Use `LightningPrompt` on your components to ask the user to provide information before they continue.
+
+`lightning/prompt` is not supported on mobile devices.
+
+Use `LightningPrompt.open()` instead of the native `window.prompt()` for a more consistent user experience. They have similar functions, but `LightningPrompt.open()` works in cross-origin iframes, where the `.prompt()` method is no longer supported in Chrome and Safari. Unlike `window.prompt()`, `LightningPrompt.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 prompt has closed.
+
+Import `LightningPrompt` from the `lightning/prompt` module in the component that will launch the prompt modal, and call `LightningPrompt.open()` with your desired attributes.
+
+This example creates a prompt modal with a header, message, and two buttons. If you enter text and click **OK** in the prompt, the `.open()` function returns a promise that resolves to the input value. If you click **Cancel**, the function returns a promise that resolves to `null`.
+
+```html
+<!-- c/myApp.html -->
+<template>
+    <lightning-button onclick="{handlePromptClick}" label="Open Prompt Modal">
+    </lightning-button>
+</template>
+```
+
+```javascript
+import { LightningElement } from 'lwc';
+import LightningPrompt from 'lightning/prompt';
+
+export default class MyApp extends LightningElement {
+    handlePromptClick() {
+        LightningPrompt.open({
+            message: 'this is the prompt message',
+            //theme defaults to "default"
+            label: 'Please Respond', // this is the header text
+            defaultValue: 'initial input value', //this is optional
+        }).then((result) => {
+            //Prompt has been closed
+            //result is input text if OK clicked
+            //and null 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).
+
+`LightningPrompt` supports the following attributes:
+
+-   `message`: Message text that displays in the prompt.
+-   `defaultValue`: Optional. Initial leading text for the input text box.
+-   `label`: Header text, also used as the `aria-label`. Default string is `Prompt`.
+-   `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, `LightningPrompt` uses the `default` theme.
+
+#### Testing Your Component's Prompt
+
+Code using `LightningPrompt` can be tested by mocking the `LightningPrompt.open()` method.
+
+The example below uses a button to open a prompt dialog and sets the result in a template.
+
+```html
+<button data-button onclick="{handleClick}">Open Prompt</button>
+<div data-result>{result}</div>
+```
+
+```js
+import LightningPrompt from 'lightning/prompt';
+jest.mock('lightning/prompt');
+​
+test(() => {
+    // Create and appendChild(element)
+​
+    const buttonEle = element.shadowRoot.querySelector('[data-button]');
+    const resultEle = element.shadowRoot.querySelector('[data-result]');
+​
+    // Mock .open()
+    // Pass string representing input text if testing when user clicks "OK"
+    // Pass null if testing when user clicks "Cancel"
+    LightningPrompt.open = jest.fn().mockResolvedValue('test value');
+    // 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('test value');
+    // Open triggered once
+    expect(LightningPrompt.open.mock.calls).toHaveLength(1);
+})
+```

package/src/lightning/prompt/__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/prompt/__examples__disabled/basic/basic.html

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

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

@@ -0,0 +1,15 @@
+import { LightningElement } from 'lwc';
+import LightningPrompt from 'lightning/prompt';
+
+export default class PromptBasic extends LightningElement {
+    handlePromptModal() {
+        LightningPrompt.open({
+            message: 'this is the prompt message',
+            defaultValue: 'test',
+            label: 'Please Respond',
+            // use default theme
+        }).then((result) => {
+            console.log('prompt result', result);
+        });
+    }
+}

package/src/lightning/prompt/prompt.css

@@ -0,0 +1,81 @@
+.slds-form-element__label {
+    overflow-wrap: break-word;
+    word-wrap: break-word;
+    -webkit-hyphens: auto;
+    -ms-hyphens: auto;
+    hyphens: auto;
+    display: inline-block;
+    color: #444444;
+    font-size: 0.75rem;
+    padding-right: 0.5rem;
+    padding-top: 0.25rem;
+    margin-bottom: 0.125rem;
+}
+.slds-form-element__label:empty {
+    margin: 0;
+}
+
+.slds-no-flex {
+    -webkit-box-flex: 0;
+    -ms-flex: none;
+    flex: none;
+}
+
+.slds-form-element__control {
+    clear: left;
+    position: relative;
+}
+
+.slds-grow {
+    -webkit-box-flex: 1;
+    -ms-flex-positive: 1;
+    flex-grow: 1;
+}
+
+.slds-input {
+    padding-top: 0;
+    padding-right: var(--slds-c-input-spacing-horizontal-end, var(--sds-c-input-spacing-horizontal-end, 1rem));
+    padding-bottom: 0;
+    padding-left: var(--slds-c-input-spacing-horizontal-start, var(--sds-c-input-spacing-horizontal-start, 0.75rem));
+    width: 100%;
+    min-height: calc(1.875rem + (1px * 2));
+    line-height: 1.875rem;
+    border: 1px solid var(--slds-c-input-color-border, var(--sds-c-input-color-border, #c9c9c9));
+    border-radius: var(--slds-c-input-radius-border, var(--sds-c-input-radius-border, 0.25rem));
+    background-color: var(--slds-c-input-color-background, var(--sds-c-input-color-background, white));
+    color: var(--slds-c-input-text-color, var(--sds-c-input-text-color));
+    -webkit-box-shadow: var(--slds-c-input-shadow, var(--sds-c-input-shadow));
+    box-shadow: var(--slds-c-input-shadow, var(--sds-c-input-shadow));
+    -webkit-transition: border 0.1s linear, background-color 0.1s linear;
+    transition: border 0.1s linear, background-color 0.1s linear;
+    display: inline-block;
+}
+.slds-input:focus,
+.slds-input:active {
+    /*! @css-var-fallback border-color */
+    border-color: var(--sds-c-input-color-border-focus, #1b96ff);
+    /*! @css-var-fallback background-color */
+    background-color: var(
+        --sds-c-input-color-background-focus,
+        var(--sds-c-input-color-background, white)
+    );
+    color: var(--sds-c-input-text-color-focus);
+    /*! @css-var-fallback box-shadow */
+    -webkit-box-shadow: var(--sds-c-input-shadow-focus, 0 0 3px #0176d3);
+    box-shadow: var(--sds-c-input-shadow-focus, 0 0 3px #0176d3);
+    outline: 0;
+}
+
+input {
+    line-height: normal;
+    color: inherit;
+    font: inherit;
+    margin: 0;
+}
+
+*,
+*:before,
+*:after {
+    -webkit-box-sizing: border-box;
+    box-sizing: border-box;
+}

package/src/lightning/prompt/prompt.html

@@ -0,0 +1,8 @@
+<template>
+    <label class="slds-form-element__label slds-no-flex" for="input">
+        {message}
+    </label>
+    <div class="slds-form-element__control slds-grow">
+        <input class="slds-input" id="input" value={defaultValue}/>
+    </div>
+</template>

package/src/lightning/prompt/prompt.js

@@ -0,0 +1,92 @@
+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/LightningPrompt.defaultLabel';
+
+/**
+ * Create a prompt modal within your component that asks the
+ * user to provide information before they continue.
+ */
+
+export default class LightningPrompt extends LightningOverlay {
+    static [instanceName] = 'lightning-prompt';
+    static [parent] = LightningInteractiveDialogBase;
+
+    /**
+     * value to use for header text in "header" variant
+     * or aria-label in "headerless" variant
+     * @type {string}
+     * @default "Prompt" (translated accordingly)
+     */
+    @api label = labelDefault;
+
+    /**
+     * text to display in modal
+     */
+    @api message = '';
+
+    /**
+     * default value for input
+     */
+    @api defaultValue = '';
+
+    /**
+     * 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: false,
+                getOkValue: this.getOkValue.bind(this),
+                getCancelValue: () => null,
+                role: 'dialog',
+            },
+        });
+        this.dispatchEvent(evt);
+    }
+
+    getOkValue() {
+        if (this.template.querySelector('input')) {
+            return this.template.querySelector('input').value;
+        }
+        return this.defaultValue;
+    }
+}

package/src/lightning/prompt/prompt.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>