lightning-base-components 1.19.10-alpha → 1.20.1-alpha

package/src/lightning/input/__examples__/timeadvanced/timeadvanced.html

@@ -0,0 +1,11 @@
+<template>
+    <div class="slds-box">
+        <h2 class="header">Advanced Input Time</h2>
+        <lightning-input type="time" name="input4" label="Required Time field" required
+                         value="18:30:00.000Z"></lightning-input>
+        <lightning-input type="time" name="input5" label="Disabled Time field" disabled
+                         value="18:30:00.000Z"></lightning-input>
+        <lightning-input type="time" name="input6" label="Time field with min and max values" value="18:30:00.000Z"
+                         min="10:30:00.000Z" max="22:00:00.000Z"></lightning-input>
+    </div>
+</template>

package/src/lightning/input/__examples__/timeadvanced/timeadvanced.js

@@ -0,0 +1,3 @@
+import { LightningElement } from 'lwc';
+
+export default class InputTimeAdvanced extends LightningElement {}

package/src/lightning/input/__examples__/timebasic/timebasic.html

@@ -0,0 +1,10 @@
+<template>
+    <div class="slds-box">
+        <h2 class="header">Basic Input Time</h2>
+        <lightning-input type="time" name="input1" label="Enter a time"></lightning-input>
+        <lightning-input type="time" name="input2" label="Time field with a predefined value"
+                         value="18:30:00.000Z"></lightning-input>
+        <lightning-input type="time" name="input3" label="Time field with placeholder"
+                         placeholder="type here..."></lightning-input>
+    </div>
+</template>

package/src/lightning/input/__examples__/timebasic/timebasic.js

@@ -0,0 +1,3 @@
+import { LightningElement } from 'lwc';
+
+export default class InputTimeBasic extends LightningElement {}

package/src/lightning/input/__examples__/toggle/toggle.html

@@ -0,0 +1,8 @@
+<template>
+    <div class="slds-box">
+        <h2 class="header">Toggle</h2>
+        <lightning-input type="toggle" label="Basic option" name="input1"></lightning-input>
+        <lightning-input type="toggle" label="Required option" name="input2" checked required></lightning-input>
+        <lightning-input type="toggle" label="Disabled option" name="input3" checked disabled></lightning-input>
+    </div>
+</template>

package/src/lightning/input/__examples__/toggle/toggle.js

@@ -0,0 +1,3 @@
+import { LightningElement } from 'lwc';
+
+export default class Toggle extends LightningElement {}

package/src/lightning/input/__examples__/url/url.html

@@ -0,0 +1,20 @@
+<template>
+    <div class="slds-m-around_medium">
+        <h1 class="slds-text-heading_small">Input URL Example</h1>
+        <p class="slds-text-body_regular">The following examples show various ways to create an input URL component.</p>
+    </div>
+    <div>
+        <h2>Basic Input URL</h2>
+        <lightning-input type="url" label="Enter a URL" name="input1" ></lightning-input>
+        <lightning-input type="url" label="URL field with a predefined value" name="input2" value="http://www.google.com" ></lightning-input>
+        <lightning-input type="url" label="URL field with a placeholder" name="input3" placeholder="Enter valid URL here..." ></lightning-input>
+    </div>
+
+    <div>
+        <h2>Advanced Input URL</h2>
+        <lightning-input type="url" label="Read-only URL field" name="input4" readonly value="file://someFile" ></lightning-input>
+        <lightning-input type="url" label="Disabled URL field" name="input5" disabled value="www.google.com" ></lightning-input>
+        <lightning-input type="url" label="Required URL field with a predefined value" name="input6" required value="www.google.com" ></lightning-input>
+        <lightning-input type="url" label="Required URL field with pattern matching" name="input6" pattern="^(https?:\/\/)?([\da-z\.-]+)\.([a-z\.]{2,6})([\/\w \.-]*)*\/?$" required value="www.google.com" ></lightning-input>
+    </div>
+</template>

package/src/lightning/input/__examples__/url/url.js

@@ -0,0 +1,3 @@
+import { LightningElement } from 'lwc';
+
+export default class LightningExampleInputURL extends LightningElement {}

package/src/lightning/input/__requirements__/requirements.md

@@ -0,0 +1,98 @@
+### Events
+
+-   When entering a value and that value is "committed", a 'commit' event is dispatch, the event is not bubbling,
+    nor cancelable and has no detail.
+    Committing a number is defined as:
+    the user presses Enter
+    OR blurs away from the input
+    OR presses the "x" clear button for type search)
+
+### `number``
+
+-   When not a valid ISO number is passed as a value to the input
+    either via an attribute `<lightning-input type="number" value="notANumber"` or
+    property `component.value = 'notANumber'`, the value should be set to empty string.
+    This also means on type changes the number needs to be re-parsed.
+
+    > Covered by Jest tests.
+
+-   When not a valid ISO number is passed to 'step', the value of the step should be the default one.
+    Currently that default is 'undefined'. It would be better if this value would be '1' instead.
+
+    > Covered by Jest tests.
+
+-   When entering a number, as the number is typed, it's converted to an ISO number and set as the value.
+    The conversion is done by using the user's current locale (not browser and not OS but rather the locale provided
+    by the localization service).
+
+    > Covered by integration tests
+
+-   In mobile environments a "numbers" keyboard should be presented when an input of type number is tapped.
+    This is done by setting `inputmode="decimal"`
+
+    > Covered by snapshot test
+
+-   When input has the focus and Up/Down key arrows are pressed, the number is increased/decreased as by the given step, if step is not given, the increases are by 1 and the number is rounded off to an integer.
+    When no initial number is given a value of 0 is used (as such a clck on '-' would net -1, and and '+" would result in 1).
+
+    > Covered by integration tests
+
+-   When numbers are increased either via Up/Down keys or by pressing the - and + buttons, both 'commit' and 'change'
+    events are dispatched.
+
+-   Bad input (like 1eee3) is flagged as invalid, when an input is flagged as invalid the input should not be formatted
+    when blurred, the original input is kept.
+
+    > Covered by integration tests
+
+-   Entering West-Arabic/Hindu numbers should be supported. Due to the way aura localisation implements this these numbers
+    can be mixed with regular numbers and can be entered even if the user locale is not of those types.
+
+-   Very long number input should be supported (the number is no longer rounded off). This is subject to precision
+    limitation of the Up/Down increase/decrease and various operations (like max/min/step checks which are still bound by the usual js limits)
+
+    > Covered by integration Tests
+
+-   The 'change' event is fired when the component transitions to a badInput state (ie. validity.badInput is true).
+    Specifically if a valid value is entered followed by a character that's invalid, it will trigger a 'change' event, and
+    the value will be ''.
+
+    > Covered by integration tests
+
+-   When a number starts with a decimal separator (like -.2 or .3), the resulting value should always have a zero
+    in front (ie. .value should be -0.2 and 0.3 respectively)
+
+    > Covered by Jest tests
+
+-   'step' attribute is used to determine the significant digits for formatting of a number; when 'step' has a superfluous .0 at the end, the number of significant digits should be 0; exponent format should also be correctly calculated, eg. 1.5e-5 should net 6 significant digits when formatting the number; positive exponents should also be correctly parsed (eg. 1e10 should net 0)
+
+    > Covered by Jest tests
+
+-   only valid characters are allowed to be typed (anything can be pasted in however), valid characters are considered:
+    -   `0-9`
+    -   `k` `K` `m` `M` `b` `B` `t` `T` (shortcuts)
+    -   `e` `E` (exponent)
+    -   `+` `-` `.` `,`
+    -   West-Arabic/Hindu numbers
+        > Covered by Jest and integration tests
+
+#### number 'k' / 'm' / 'b' shortcuts
+
+-   When an entered valid number in the given locale ends in "k", "K", "m", "M", "b", "B", "t" or "T" (shortcut suffix):
+    -   as soon as the suffix is entered `value` is `1000 * the entered` number if "k" or "K" is the suffix, or `1000000 * the entered number` if "m" or "M" is the suffix, or `1000000000 * the entered number` if "b" or "B" is the suffix, or `1000000000000 * the entered number` if "t" or "T" is the suffix
+        > Covered by Jest and Integration tests
+    -   when blurring from the input, the value shown on the input should reflect the multiplied number (eg. for `1k` it could be `1,000` for a locale with `,` as a grouping separator)
+        > Covered by Jest and Integration tests
+    -   when the input is focused, the value that's in the input will be the multiplied number
+        in the given locale with the correct decimal separator and no grouping separators (eg. if in a locale with "," as a decimal separator number `0,0001k` was entered, when focusing after a blur the number should show as `0,1`)
+        > Covered by Jest and Integration tests (partially, it would be good to have a test that overrides the locale used to test with locales that have different decimal digits)
+-   If the input is not a valid number but has a shortcut suffix at the end, when blurring from the input, and then focusing back on it, the original entered string should be preserved (eg. if `100eee10k` is entered, blurring out and focusing should preserve that value)
+    > Covered by Jest tests
+-   When setting the value programmatically, value that contains a shortcut suffix should not be considered valid
+    > Covered by Jest tests
+
+### Open questions
+
+-   We need to define the behaviour for - and + when max or min are hit, and also whether it should round to the
+    closest step. In addition the behaviour for when the number is larger than what js arithmetics can handle (because
+    of the rounding errors the increase/decrease does nothing).

package/src/lightning/inputAddress/__docs__/inputAddress.md

@@ -0,0 +1,324 @@
+---
+examples:
+    - name: base
+      label: Basic Address Input
+      description: Address fields can be prepopulated and marked as required.
+    - name: stateAndCountryPicklists
+      label: Address With State and Country Picklists
+      description: Address fields support predefined lists of states and countries.
+    - name: customLocale
+      label: Address With Custom Locale
+      description: Address input fields ordered depending on custom locale value.
+---
+
+A `lightning-input-address` component creates a compound field that includes the following constituent fields.
+
+-   Street
+-   City
+-   Province
+-   Country
+-   Postal code
+
+The street field is displayed as a multi-line text field. The other fields are displayed as a text input field by default. The country and province fields are displayed as dropdown menus if you specify `country-options` and `province-options` to provide options for menu items.
+
+This example creates an address compound field with attributes to specify values for the constituent fields. The initial values are set directly with the attributes.
+
+```html
+<template>
+    <div>
+        <lightning-input-address
+            address-label="Address"
+            street-label="Street"
+            city-label="City"
+            country-label="Country"
+            province-label="State"
+            postal-code-label="PostalCode"
+            street="1 Market St."
+            city="San Francisco"
+            country="US"
+            province="CA"
+            postal-code="94105"
+            field-level-help="Enter your billing address"
+        >
+        </lightning-input-address>
+    </div>
+</template>
+```
+
+`lightning-input-address` uses the `onchange` event handler to listen to a change to its field values.
+
+```html
+<p>You are located in: {city}</p>
+    <lightning-input-address
+        address-label="Address"
+        street-label="Street"
+        city-label="City"
+        country-label="Country"
+        province-label="Province"
+        postal-code-label="PostalCode"
+        city={city}
+        onchange={handleChange} ></lightning-input-address>
+```
+
+To bind the input value on the address fields, use the `event.target` property.
+
+```js
+import { LightningElement } from 'lwc';
+
+export default class AddressCityExample extends LightningElement {
+    city = "San Francisco";
+
+    handleChange(event) {
+        this.city = event.target.city;
+    }
+}
+```
+
+See the __Custom Events__ section for a list of `event.target` properties. For more information, see [Data Binding in a Template](https://developer.salesforce.com/docs/platform/lwc/guide/js-props-getter).
+
+#### Creating Dropdown Menus for Country and Province
+
+To create a dropdown menu for the country and province, pass in an array of
+label-value pairs to `country-options` and `province-options`. Use the `country` and
+`province` attributes to specify the default values on the dropdown menus.
+
+```html
+<template>
+    <div>
+        <lightning-input-address
+            address-label="Address"
+            street-label="Street"
+            city-label="City"
+            country-label="Country"
+            province-label="Province/State"
+            postal-code-label="PostalCode"
+            street="1 Market St."
+            city="San Francisco"
+            province="CA"
+            country="US"
+            country-options={getCountryOptions}
+            province-options={getProvinceOptions}
+            postal-code="94105"
+            required
+            onchange={handleChange}
+        >
+        </lightning-input-address>
+    </div>
+</template>
+```
+
+JavaScript file:
+
+```javascript
+import { LightningElement } from 'lwc';
+
+export default class DemoInputAddress extends LightningElement {
+    provinceOptions = [
+        { label: 'California', value: 'CA' },
+        { label: 'Texas', value: 'TX' },
+        { label: 'Washington', value: 'WA' },
+    ];
+
+    countryOptions = [
+        { label: 'United States', value: 'US' },
+        { label: 'Japan', value: 'JP' },
+        { label: 'China', value: 'CN' },
+    ];
+
+    get getProvinceOptions() {
+        return this.countryProvinceMap[this._country];
+    }
+    get getCountryOptions() {
+        return this.countryOptions;
+    }
+
+    handleChange(event) {
+        this._country = event.detail.country;
+    }
+}
+```
+
+Alternatively, you can enable state and country picklists in your org, and
+access the values by using a wire adapter.
+See [Let Users Select State and Country from Picklists](https://help.salesforce.com/articleView?id=admin_state_country_picklists_overview.htm) in Salesforce Help and [getPicklistValues](https://developer.salesforce.com/docs/platform/lwc/guide/reference-wire-adapters-picklist-values) in the Lightning Web Components Developer Guide.
+
+#### Using Lookup to Find and Autofill an Address
+
+To enable autocompletion of the address fields using an address lookup field, include the `show-address-lookup` attribute. The address lookup field is placed above the address fields you provide.
+
+```html
+<template>
+    <lightning-input-address
+        address-label="Address"
+        street-label="Street"
+        city-label="City"
+        country-label="Country"
+        province-label="State"
+        postal-code-label="Zip Code"
+        street="1 Market St."
+        city="San Francisco"
+        country="US"
+        province="CA"
+        show-address-lookup
+    >
+    </lightning-input-address>
+</template>
+```
+
+When you start typing an address in the lookup field, a dropdown menu displays matching addresses returned by the Google Maps Places API. Select an address from the dropdown to populate the address fields.
+
+Using `show-address-lookup` is not supported in Playground, Experience Builder sites, Lightning Out,
+Lightning Components for Visualforce, and standalone apps. While it may work, these targets are not optimized and not officially supported.
+
+#### Validating Required Fields
+
+When you set `required`, a red asterisk is displayed on every address
+field to indicate that an entry in each field is required. An error message is displayed below
+a field if a user interacted with it and left it blank. The `required`
+attribute is not enforced and you must validate it before submitting a form
+that contains an address compound field.
+
+Let's say you have a `lightning-button` component that calls the `handleClick`
+function. You can display the error message when a user clicks the
+button without providing a value on a field.
+
+```javascript
+    handleClick(e) {
+        const address =
+            this.template.querySelector('lightning-input-address');
+        const isValid = address.checkValidity();
+        if(isValid) {
+            alert("Creating a new address");
+        } else {
+            alert("Complete all address fields");
+        }
+    }
+```
+
+#### Working with Labels and Placeholders
+
+A label is associated with an address field and it enables screen readers to navigate the form correctly. Include a label for each field you're using, with the following attributes.
+
+-   `address-label`
+-   `street-label`
+-   `city-label`
+-   `province-label`
+-   `country-label`
+-   `postal-code-label`
+
+You can hide the `address-label` visually and still make them accessible to screen readers by using `variant="label-hidden"`.
+
+Additionally, the `show-address-lookup` boolean attribute creates a search field that doesn't have an associated label. See **Using Lookup to Find and Autofill an Address** for more information.
+
+Your Salesforce locale setting determines the order and layout of the input address fields by default. Use the `locale` attribute to override the default. Specify any locale code from the list of [Supported Number, Name, and Address Formats (ICU)](https://help.salesforce.com/s/articleView?id=sf.admin_supported_locales.htm&type=5").
+
+You can also use custom labels that display translated values. For more information, see
+[Access Labels](https://developer.salesforce.com/docs/platform/lwc/guide/create-labels).
+
+We recommend that you provide a label even when you provide placeholder text for an address field. Without field labels, users can lose context when the placeholder text disappears as they type in the field.
+
+Specify placeholder text to give users a hint about the content they're expected to enter in the field. Avoid repeating the field label in the placeholder for better accessibility. Consider the width of your address field as the placeholder text is cut off if it's too long, especially on mobile devices.
+
+Include an optional placeholder for each field you're using, with the following attributes.
+
+-   `address-lookup-placeholder`
+-   `street-placeholder`
+-   `city-placeholder`
+-   `province-placeholder`
+-   `country-placeholder`
+-   `postal-code-placeholder`
+
+#### Component Styling
+
+`lightning-input-address` implements the
+[form element](https://lightningdesignsystem.com/components/form-element/#Address) address blueprint in the
+Salesforce Lightning Design System (SLDS).
+
+You can use a combination of the `variant` and `class` attributes to customize the address fields.
+
+##### Variants
+
+Use the `variant` attribute with one of these values to apply different label positioning.
+
+-   `label-hidden` hides the compound field label but make it available to assistive technology. This variant does not hide the constituent field labels.
+-   `label-inline` horizontally aligns the compound field label and address fields.
+-   `label-stacked` places the label above the address fields.
+-   `standard` is the default value, which displays the label above the address fields.
+
+##### Customize Component Styling
+
+To apply additional styling, use the SLDS [utility classes](https://www.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.
+
+This example adds padding on top of address fields using an SLDS class.
+
+```html
+<lightning-input-address
+    class="slds-p-top_small"
+    address-label="Address"
+    street-label="Street"
+    city-label="City"
+    country-label="Country"
+    province-label="Province"
+    postal-code-label="PostalCode"
+>
+</lightning-input-address>
+```
+
+To apply custom styling, use the `:host` selector. Use SLDS styling hooks to customize the component's styles. The Street field renders a [textarea](https://www.lightningdesignsystem.com/components/textarea) and the other fields render [input](https://www.lightningdesignsystem.com/components/input/) fields.
+
+For example, change the minimum height of the textarea and change the background color of the input fields.
+
+```css
+:host {
+    --slds-c-textarea-sizing-min-height: 200px;
+    --slds-c-input-color-background: orange;
+}
+```
+
+See [Input: Styling Hooks Overview](https://www.lightningdesignsystem.com/components/input/#Styling-Hooks-Overview) and [Textarea: Styling Hooks Overview](https://www.lightningdesignsystem.com/components/textarea/#CSS-Class-Overview) for a list of CSS custom properties.
+
+#### Usage Considerations
+
+Using `show-address-lookup` is not supported in Playground, Experience Builder sites, Lightning Out,
+Lightning Components for Visualforce, and standalone apps.
+
+When working with address fields such as with the `MailingAddress` field on Salesforce records, consider using the record form components. The `lightning-record-form`, `lightning-record-view-form`, and `lightning-record-edit-form` components provide a form-based UI that's metadata-driven. The components are automatically wired up to your record data, labels, and field-level help text. For more information, see [Work with Records Using Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-get-user-input-intro).
+
+To create your own custom UI to work with Salesforce records, use `lightning-input-address` with the `lightning/ui*Api` wire adapters and functions, such as `getRecord` and `updateRecord`. For more information, see [Use the Wire Service with Base Components](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-base-components).
+
+To disable the fields so that users cannot interact with it, use the `disabled` attribute. If you want to prevent users from interacting with the country field only,
+disable it using the `country-disabled` attribute.
+
+#### Accessibility
+
+You must provide a text label for accessibility to make the information available to assistive technology.
+The `label` attribute creates an HTML `<label>` element for your address.
+To hide the compound field label from view and make it available to assistive technology, use the `label-hidden` variant.
+This variant keeps the constituent field labels in view.
+
+This component uses `button` elements for picklists to comply with the [Lightning Design System combobox blueprint](https://www.lightningdesignsystem.com/components/combobox/#%22Input%22-markup) for select-only comboboxes.
+
+#### Custom Events
+
+**`change`**
+
+The event fired when an item is changed in the `lightning-input-address` component.
+
+The `change` event returns the following parameters.
+
+| Parameter  | Type   | Description                        |
+| ---------- | ------ | ---------------------------------- |
+| street     | string | The number and name of street.     |
+| city       | string | The name of the city.              |
+| province   | string | The name of the province/state.    |
+| country    | string | The name of the country.           |
+| postalCode | string | The postal code for the address.   |
+| validity   | object | The validity state of the element. |
+
+The `change` event properties are as follows.
+
+| Property   | Value | Description                                                                                               |
+| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
+| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
+| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
+| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

package/src/lightning/inputAddress/__examples__/base/base.html

@@ -0,0 +1,17 @@
+<template>
+    <lightning-input-address
+        address-label="Address"
+        street-label="Street"
+        city-label="City"
+        country-label="Country"
+        province-label="Province"
+        postal-code-label="PostalCode"
+        street="121 Spear St."
+        city="San Francisco"
+        country="US"
+        province="CA"
+        postal-code="94105"
+        required
+        field-level-help="Help Text for inputAddress field" ></lightning-input-address>
+</template>
+    

package/src/lightning/inputAddress/__examples__/base/base.js

@@ -0,0 +1,3 @@
+import { LightningElement } from 'lwc';
+
+export default class InputAddressBase extends LightningElement {}

package/src/lightning/inputAddress/__examples__/customLocale/customLocale.html

@@ -0,0 +1,12 @@
+<template>
+    <lightning-input-address
+        address-label="Address"
+        street-label="Street"
+        city-label="City"
+        country-label="Country"
+        province-label="Prefecture"
+        postal-code-label="Postal Code"
+        locale="ja-JP"
+        field-level-help="Help Text for input address field" >
+    </lightning-input-address>
+</template>

package/src/lightning/inputAddress/__examples__/customLocale/customLocale.js

@@ -0,0 +1,3 @@
+import { LightningElement } from 'lwc';
+
+export default class InputAddressCustomLocale extends LightningElement {}

package/src/lightning/inputAddress/__examples__/stateAndCountryPicklists/stateAndCountryPicklists.html

@@ -0,0 +1,18 @@
+<template>
+    <lightning-input-address
+        address-label="Address"
+        street-label="Street"
+        city-label="City"
+        country-label="Country"
+        province-label="Province"
+        postal-code-label="PostalCode"
+        street={address.street}
+        city={address.city}
+        country={address.country}
+        province={address.province}
+        postal-code={address.postalCode}
+        field-level-help="Help Text for inputAddress field" 
+        country-options={getCountryOptions}
+        province-options={getProvinceOptions}
+        onchange={handleChange} ></lightning-input-address>
+</template>

package/src/lightning/inputAddress/__examples__/stateAndCountryPicklists/stateAndCountryPicklists.js

@@ -0,0 +1,44 @@
+import { LightningElement } from 'lwc';
+
+export default class InputAddressBase extends LightningElement {
+    address = {
+        street: '121 Spear St.',
+        city: 'San Francisco',
+        province: 'CA',
+        postalCode: '94105',
+        country: 'US',
+    };
+
+    _country = 'US';
+
+    countryProvinceMap = {
+        US: [
+            { label: 'California', value: 'CA' },
+            { label: 'Texas', value: 'TX' },
+            { label: 'Washington', value: 'WA' },
+        ],
+        CN: [
+            { label: 'GuangDong', value: 'GD' },
+            { label: 'GuangXi', value: 'GX' },
+            { label: 'Sichuan', value: 'SC' },
+        ],
+        VA: [],
+    };
+
+    countryOptions = [
+        { label: 'United States', value: 'US' },
+        { label: 'China', value: 'CN' },
+        { label: 'Vatican', value: 'VA' },
+    ];
+
+    get getProvinceOptions() {
+        return this.countryProvinceMap[this._country];
+    }
+    get getCountryOptions() {
+        return this.countryOptions;
+    }
+
+    handleChange(event) {
+        this._country = event.detail.country;
+    }
+}