lightning-base-components 1.19.10-alpha → 1.19.11-alpha

package/src/lightning/formattedText/__examples__/basic/basic.html

@@ -0,0 +1,6 @@
+<template>
+    <p><lightning-formatted-text value="Email salesforce.com and info.salesforce.com" ></lightning-formatted-text></p>
+    <p><lightning-formatted-text value="Email info@salesforce.com" ></lightning-formatted-text></p>
+    <p><lightning-formatted-text value="Email salesforce.com and info.salesforce.com" linkify></lightning-formatted-text></p>
+    <p><lightning-formatted-text value="Email info@salesforce.com" linkify></lightning-formatted-text></p>
+</template>

package/src/lightning/formattedText/__examples__/basic/basic.js

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

package/src/lightning/formattedTime/__docs__/formattedTime.md

@@ -0,0 +1,39 @@
+---
+examples:
+    - name: basic
+      label: Formatted Time
+      description: Time value displayed in the user's locale format. Include a Z suffix in the time value to indicate Universal Time.
+---
+
+A `lightning-formatted-time` component displays a read-only representation of
+time in the user's locale format. A valid ISO8601 formatted time string must
+be used.
+
+An ISO8601 formatted time string matches one of the following patterns.
+
+-   HH:mm
+-   HH:mm:ss
+-   HH:mm:ss.SSS
+
+`HH` is the number of hours that have passed since midnight, `mm` is the
+number of minutes that have passed since the start of the hour, `ss` is
+the number of seconds since the start of the minute, and `SSS` is the number
+of milliseconds since the start of the second. Time is always displayed in Universal Time (UTC).
+
+Offsets aren't supported, and the component ignores them. For example, `14:30+05:00` is treated as `14:30`.
+
+The following example returns `10:12:30 PM`.
+
+```html
+<template>
+    <lightning-formatted-time value="22:12:30.999"> </lightning-formatted-time>
+</template>
+```
+
+Salesforce uses the format HH:mm:ss.SSSZ for time fields. The time field is a
+timestamp without the date included. Time values in Salesforce are not
+localized or associated with a time zone.
+
+#### Source Code
+
+`lightning-formatted-time` is available in the [Base Components Recipes GitHub repository](https://github.com/salesforce/base-components-recipes#documentation). It's transpiled into the `c` namespace so that you can use it in your own projects.

package/src/lightning/formattedTime/__examples__/basic/basic.html

@@ -0,0 +1,4 @@
+<template>
+    <p>Simple Time value: <lightning-formatted-time value="22:12:30.999"></lightning-formatted-time></p>
+    <p>Time value with Z suffix: <lightning-formatted-time value="22:12:30.999Z"></lightning-formatted-time></p>
+</template>

package/src/lightning/formattedTime/__examples__/basic/basic.js

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

package/src/lightning/formattedUrl/__docs__/formattedUrl.md

@@ -0,0 +1,119 @@
+---
+examples:
+    - name: basic
+      label: Formatted URL
+      description: Displays a URL with a protocol such as http:// and https://. A value "/my/path" creates a relative URL.
+---
+
+A `lightning-formatted-url` component displays a URL using an anchor `<a>` tag with an `href` attribute. The `value` you provide can be a relative or absolute URL. An absolute URL uses a protocol like `http://`, `https://`, or
+`ftp://`, followed by the domain name and path. The component renders the link using the `http://` protocol by default.
+
+URLs without a protocol use the host domain's protocol. For example, `www.example.com` is prefixed with `https://` if the host domain's protocol is `https://`.
+
+To customize the displayed text, provide a `label`. Otherwise,
+the URL you pass into `value` is used as the displayed text.
+
+```html
+<template>
+    <lightning-formatted-url
+        value="https://salesforce.com"
+        label="Visit salesforce.com"
+        target="_blank"
+    ></lightning-formatted-url>
+</template>
+```
+
+The rendered HTML looks like this.
+
+```html
+<a href="https://salesforce.com" target="_blank">Visit salesforce.com</a>
+```
+
+By default, clicking the link takes you to the URL in the same frame where it was clicked.
+
+#### Creating Absolute URLs
+
+To create an absolute URL, set the `value` attribute using one of these patterns.
+
+-   www.salesforce.com
+-   http://www.salesforce.com
+-   https://developer.salesforce.com/docs/component-library
+
+`http://` is inserted before a value like `www.salesforce.com` or `my/path`, which does not begin with a slash. This creates an absolute URL like `http://www.salesforce.com` or `http://my/path`. This behavior is contrary to that of the anchor `<a>` tag where omitting the leading slash results in a relative path from the current directory.
+
+This example displays an absolute URL and uses the provided `value` as the `href` value for the `<a>` tag.
+
+```html
+<template>
+    <lightning-formatted-url value="https://www.salesforce.com">
+    </lightning-formatted-url>
+</template>
+```
+
+If you don't provide a protocol, `http://` is prefixed to the URL by default. The rendered HTML of the previous example
+uses `https` because the protocol is specified.
+
+```html
+<a href="https://www.salesforce.com">https://www.salesforce.com</a>
+```
+
+URLs without a protocol use the host domain's protocol. For example, `www.example.com` is prefixed with `https://` if the host domain's protocol is `https://`.
+
+#### Creating Relative URLs
+
+To create a relative URL, set the `value` attribute using one of these patterns.
+
+-   index.html
+-   /my/path
+-   ./my/path
+-   ../my/path
+
+If the `value` includes a leading slash in the path like `/my/path`, the resulting URL is root-relative and uses the domain of the page as the prefix. For example, if the current page is located on `example.com/directory/`, the resulting URL is `http://example.com/my/path`. To create a URL from the current directory, start the URL with a dot-slash like `./my/path`. To create a URL to the parent directory of the current page, start the URL with dot-dot-slash like `../my/path`.
+
+A relative URL navigates to a path within the current site you're on.
+
+```html
+<template>
+    <!-- Resolves to http://current-domain/my/path -->
+    <lightning-formatted-url value="/my/path"> </lightning-formatted-url>
+</template>
+```
+
+The rendered HTML looks like this. Clicking the URL takes you to `http://current-domain/my/path`.
+
+```html
+<a href="/my/path">/my/path</a>
+```
+
+#### Specifying a Target
+
+Use the `target` attribute to change where the link should open. If you don't
+provide a target, `lightning-formatted-url` uses the `_self` target value.
+
+Supported `target` values are:
+
+-   `_blank`: Opens the link in a new window or tab. In a mobile hybrid app like the Salesforce mobile app, the link is handled similar to `_self` and opens inside the app if possible.
+-   `_self`: Opens the link in the same frame as it was clicked. This is the default behavior. In Lightning Experience and Experience Builder sites, the link is opened in a new tab if it cannot be opened inside the app. We recommend that you use [`lightning-navigation`](bundle/lightning-navigation/documentation) to create links within Lightning Experience and Experience Builder sites.
+-   `_parent`: Opens the link in the parent frame. If there's no parent, this is similar to `_self`.
+-   `_top`: Opens the link into the top-level browsing context. If there's no parent, this is similar to `_self`.
+
+For more information about link targets, see the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a).
+
+#### Usage Considerations
+
+We recommend using absolute URLs where possible as they can prevent duplicate content to improve search engine optimization.
+Having your internal links as relative URLs can also expose the structure of your website.
+
+`lightning-formatted-url` does not support email addresses or phone numbers. To create an email address with the `mailto:` protocol, use `lightning-formatted-email`.
+To create a phone number with the `tel:` protocol, use `lightning-formatted-phone`.
+
+The framework handles navigation for you, so there's no need to provide `onclick`
+behavior with `lightning-formatted-url`.
+
+To create a link with a
+custom `onclick` event handler, use the HTML anchor tag `<a>` instead. To create a URL that navigates to another page in Salesforce, use
+[`lightning-navigation`](bundle/lightning-navigation/documentation).
+
+#### Source Code
+
+`lightning-formatted-url` is available in the [Base Components Recipes GitHub repository](https://github.com/salesforce/base-components-recipes#documentation). It's transpiled into the `c` namespace so that you can use it in your own projects.

package/src/lightning/formattedUrl/__examples__/basic/basic.html

@@ -0,0 +1,32 @@
+<template>
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+        <h2 class="slds-text-heading_small">
+            Absolute URLs are created if the value doesn't begin with /
+        </h2>
+        <div class="slds-p-around_medium">
+            <p><lightning-formatted-url value="my/path" tooltip="Omit leading slash" target="_blank"></lightning-formatted-url></p>
+            <p><lightning-formatted-url value="www.salesforce.com" tooltip="Use full domain name" target="_blank"></lightning-formatted-url></p>
+            <p><lightning-formatted-url value="https://salesforce.com" tooltip="Use https://domain-name" label="Visit salesforce.com" target="_blank" ></lightning-formatted-url></p>
+        </div>
+    </div>
+
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+        <h2 class="slds-text-heading_small">
+            Relative URLs are created if the value begins with /
+        </h2>
+        <div class="slds-p-around_medium">
+            <p><lightning-formatted-url value="/my/path" tooltip="Include leading slash" target="_blank"></lightning-formatted-url></p>
+            <p><lightning-formatted-url value="/my/path" label="Visit /my/path on this website" target="_blank"></lightning-formatted-url></p>
+        </div>
+    </div>
+
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+        <h2 class="slds-text-heading_small">
+            Only http, https, and ftp protocols are supported.
+        </h2>
+        <div class="slds-p-around_medium">
+            <p><lightning-formatted-url value="https://www.salesforce.com" target="_blank"></lightning-formatted-url></p>
+            <p><lightning-formatted-url value="ftp://public.ftp-servers.example.com/path/to/myfile.txt" target="_blank"></lightning-formatted-url></p>
+        </div>
+    </div>
+</template>

package/src/lightning/formattedUrl/__examples__/basic/basic.js

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

package/src/lightning/groupedCombobox/__mockData__/exampleGroupedComboboxData.js

@@ -0,0 +1,60 @@
+const exampleData = {};
+
+exampleData.exampleInlineOption = {
+    type: 'option-inline',
+    iconName: 'utility:search',
+    text: 'Advanced Search...',
+    value: 'actionSearchAdvanced',
+};
+exampleData.exampleCardOption = {
+    type: 'option-card',
+    text: 'Global Media',
+    iconName: 'standard:account',
+    subText: '(905) 555-1212',
+    value: 'accountGlobalMedia',
+};
+exampleData.exampleCardOptionHighlighted = {
+    type: 'option-card',
+    text: 'Global Media',
+    highlight: true,
+    iconName: 'standard:account',
+    subText: '(905) 555-1212',
+    value: 'accountGlobalMediaOptionHighlighted',
+};
+exampleData.exampleDataWithHighlightedCard = [
+    exampleData.exampleInlineOption,
+    exampleData.exampleCardOptionHighlighted,
+    exampleData.exampleCardOption,
+];
+exampleData.exampleGroups = [
+    exampleData.exampleInlineOption,
+    {
+        label: 'Group 1',
+        items: [Object.assign({}, exampleData.exampleInlineOption)],
+    },
+    {
+        label: 'Group 2',
+        items: [
+            exampleData.exampleCardOptionHighlighted,
+            exampleData.exampleInlineOption,
+            exampleData.exampleCardOption,
+        ],
+    },
+    {
+        label: 'Group 3',
+        items: [
+            exampleData.exampleCardOptionHighlighted,
+            exampleData.exampleInlineOption,
+            exampleData.exampleCardOption,
+        ],
+    },
+];
+exampleData.exampleItems = [
+    exampleData.exampleInlineOption,
+    exampleData.exampleCardOption,
+];
+exampleData.exampleItemsManyRecords = [...new Array(50)].map(
+    () => exampleData.exampleCardOption
+);
+
+export default exampleData;

package/src/lightning/groupedCombobox/groupedCombobox.html

@@ -59,6 +59,7 @@
                 onfocus={handleFocus}
                 onblur={handleBlur}
                 onpillremove={handlePillRemove}
+                oninputclick={handleClick}
                 onendreached={handleEndReached}
                 ondropdownopen={handleDropdownOpen}
                 ondropdownopenrequest={handleDropdownOpenRequest}

package/src/lightning/groupedCombobox/groupedCombobox.js

@@ -311,6 +311,10 @@ export default class LightningGroupedCombobox extends LightningElement {
         }
     }
 
+    handleClick() {
+        this.dispatchEvent(new CustomEvent('inputclick'));
+    }
+
     handleTextChange(event) {
         this._inputText = event.detail.text;
 

package/src/lightning/helptext/__docs__/helptext.md

@@ -0,0 +1,86 @@
+---
+examples:
+    - name: basic
+      label: Basic Helptext
+      description: Basic default helptext example and an alternative icon example.
+---
+
+A `lightning-helptext` component displays an icon with a popover containing a
+small amount of text describing an element on screen. The popover is displayed
+when you hover or focus on the icon that's attached to it. On iOS devices, the
+helptext popover opens when you tap on the icon and closes with a second tap
+on the popover or the icon.
+
+This component is similar to a tooltip and is useful to display field-level help text, for example. HTML markup is not supported in the tooltip content.
+
+This example creates an icon with a tooltip.
+
+```html
+<template>
+    <lightning-helptext content="Your email address will be your login name">
+    </lightning-helptext>
+</template>
+```
+
+The popover is anchored on the lower left of the icon and shown above the icon
+if space is available. It automatically adjusts its position according to the
+viewport.
+
+#### Component Styling
+
+`lightning-helptext` implements the
+[tooltip](https://www.lightningdesignsystem.com/components/tooltips/) blueprint in the Salesforce Lightning Design System (SLDS).
+
+##### Icons
+
+By default, the tooltip uses the `utility:info` icon but you can specify a
+different icon with the `icon-name` attribute. The SLDS utility icon category offers nearly 200 utility icons that can be used
+in `lightning-helptext`. Although SLDS provides several
+categories of icons, only the utility category can be used in
+`lightning-helptext`.
+
+Visit [utility icons](https://lightningdesignsystem.com/icons/#utility) to view the utility icons.
+
+When applying SLDS classes or icons, check that they are
+available in the SLDS release tied to your org.
+The SLDS site shows the latest SLDS
+resources, and these become available only when the new release
+is available in your org.
+
+##### Variants
+
+Use the `icon-variant` attribute to change the style of the icon with the following values.
+
+-   `bare` is the default variant and doesn't need to be specified
+-   `error` adds a red fill for the icon to call out a user- or system-related error
+-   `inverse` adds a white fill for the icon, useful for dark backgrounds
+-   `warning` adds a yellow fill for the icon to advise caution
+
+#### 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 a margin to the left of the tooltip icon using the `slds-m-left_xx-small` class.
+
+```html
+some text that appears before the tooltip icon here
+<lightning-helptext
+    icon-name="utility:salesforce1"
+    content="tooltip content here"
+    class="slds-m-left_xx-small"
+></lightning-helptext>
+```
+
+To apply custom styling, use the `:host` selector or define a custom class using the `class` attribute.
+
+`lightning-helptext` contains the same customizable elements as `lightning-button-icon` for the button icon, which supports `--slds-c-button-*` custom properties. See the [`lightning-button-icon` documentation](bundle/lightning-button-icon/documentation).
+
+Customizing the tooltip content using the `--slds-c-tooltip-*` custom properties isn't supported. `lightning-helptext` renders the tooltip as the child of the body element outside of the scoped container.
+
+#### Accessibility
+
+`lightning-helptext` contains a focusable button element. To ensure that users who aren't using a mouse can access the tooltip, `lightning-helptext` shows the tooltip on hover or on keyboard focus. The button renders with an `aria-describedby` attribute set to an ID that matches the element containing the tooltip text. The `aria-describedby` attribute enables assistive technology to announce the tooltip content.
+
+The button renders assistive text that contains "Help" by default. To provide your own description, use the `alternative-text` attribute.
+The text should describe the function of the icon, for example, "Show help text", instead of repeating the `content` description.
+Providing the purpose of the icon in the description improves usability and removes repetition of content for users of assistive technology.

package/src/lightning/helptext/__examples__/basic/basic.css

@@ -0,0 +1,7 @@
+.lgc-bg {
+    background-color: rgb(242 242 242);
+}
+
+.lgc-bg-inverse {
+    background-color: rgb(22 50 92);
+}

package/src/lightning/helptext/__examples__/basic/basic.html

@@ -0,0 +1,27 @@
+<template>
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+        <h2 class="slds-text-heading_medium slds-m-bottom_medium">
+            Helptext example using a default icon. Mouse over or focus on the icon to view the helptext content.
+        </h2>
+
+        <p class="slds-m-bottom_medium">The tooltip displays on the lower left of the icon or above the icon if space is available. It automatically adjusts its position according to the viewport.</p>
+
+        <!-- Simple -->
+        <div class="slds-p-around_medium lgc-bg">
+            Subscribe
+            <lightning-helptext content="You'll receive weekly updates"></lightning-helptext>
+        </div>
+    </div>
+
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+        <h2 class="slds-text-heading_medium slds-m-bottom_medium">
+            Helptext example with an alternative icon.
+        </h2>
+
+        <!-- Simple -->
+        <div class="slds-p-around_medium lgc-bg">
+            Short Text
+            <lightning-helptext icon-name="utility:salesforce1" content="Full text explanation of feature"></lightning-helptext>
+        </div>
+    </div>
+</template>

package/src/lightning/helptext/__examples__/basic/basic.js

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

package/src/lightning/icon/__docs__/icon.md

@@ -0,0 +1,182 @@
+---
+examples:
+    - name: basic
+      label: Basic Icons
+      description: Action icons, doctype icons, standard icons, utility icons, and custom icons.
+    - name: variants
+      label: Icons with Sizes and Variants
+      description: Effects of the size attribute and inverse, success, warning and error variants.
+---
+
+A `lightning-icon` is a visual element that provides context and enhances
+usability. Icons can be used inside the body of another component or on their
+own. You can specify an icon from the Lightning Design System using the `icon-name` attribute.
+
+Here is an example.
+
+```html
+<template>
+    <lightning-icon
+        icon-name="action:approval"
+        size="large"
+        alternative-text="Indicates approval"
+    >
+    </lightning-icon>
+</template>
+```
+
+Alternatively, you can provide a custom icon using the `src` attribute. See the **Using Your Own Icons** section.
+
+#### Component Styling
+
+`lightning-icon` provides you with icons in the Salesforce Lightning Design System (SLDS). Visit [icons](https://lightningdesignsystem.com/icons) to view the available icons.
+
+You can use a combination of the `variant`, `size`, and `class` attributes to customize the icon styling.
+
+When applying SLDS classes or icons, check that they are
+available in the SLDS release tied to your org. The latest
+SLDS resources become available only when the new release
+is available in your org.
+
+##### Sizes
+
+Adjust icon sizes using the `size` attribute with one of these values.
+
+-   `medium` is the default size, which creates a 32px by 32px icon
+-   `small` creates a 24px by 24px icon
+-   `x-small` creates a 16px by 16px icon
+-   `xx-small` creates a 14px by 14px icon
+-   `large` creates a 48px by 48px icon
+
+##### Variants
+
+Variants are supported only for the utility icons. To change the appearance of a [utility icon](https://lightningdesignsystem.com/icons/#utility), use the `variant` attribute with one of these values.
+
+-   `inverse` adds a white fill to a utility icon, useful for dark backgrounds
+-   `error` adds a red fill to a utility icon to call out a user- or system-related error
+-   `success` adds a green fill to a utility icon to represent a successful operation
+-   `warning` adds a yellow fill to a utility icon to advise caution
+
+This example uses the `error` variant to add a red fill to the error utility icon.
+
+```html
+<template>
+    <lightning-icon icon-name="utility:error" variant="error"> </lightning-icon>
+</template>
+```
+
+##### Customize Component Styling
+
+To apply additional styling, use the SLDS [utility classes](https://www.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.
+For example, you can set `class="slds-m-vertical_large"` or other [margin](https://lightningdesignsystem.com/utilities/margin/) classes to add
+spacing around the icon.
+
+To change the fill and background color of a utility icon, define a custom class using the `class` attribute. This example applies custom fill and background colors on the utility icon.
+
+```html
+<lightning-icon
+    icon-name="utility:connected_apps"
+    alternative-text="Connected"
+    title="Connected"
+    class="my-icon"
+>
+</lightning-icon>
+```
+
+Specify the fill and background colors on the utility icon using the `--slds-c-icon-color-*` custom properties.
+
+```css
+.my-icon {
+    --slds-c-icon-color-foreground-default: orange;
+    --slds-c-icon-color-background: gray;
+}
+```
+
+To change the fill and background colors of a non-utility icon, such as an [action](https://lightningdesignsystem.com/icons/#action), [standard](https://lightningdesignsystem.com/icons/#standard), or [custom](https://lightningdesignsystem.com/icons/#custom) icon, specify the fill color like this.
+
+```css
+.my-icon {
+    --slds-c-icon-color-foreground: orange;
+    --slds-c-icon-color-background: gray;
+}
+```
+
+See [Styling Hooks Overview](https://www.lightningdesignsystem.com/components/icons/#Styling-Hooks-Overview) for a list of CSS custom properties.
+
+For more information, see [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties) in the Lightning Web Components Developer Guide.
+
+To understand how we implemented SLDS in `lightning-icon`, see the **Source Code** section.
+
+#### Using Your Own Icons
+
+Use the `src` attribute to specify the path of the resource for your
+icon. When this attribute is present, `lightning-icon` attempts to load an
+icon from the provided resource.
+
+Define a static resource in your org and upload your icon's SVG resource
+to it. The SVG code must include a `<g>` element with an id that you can reference.
+
+For example, suppose your static resource is named `mySVG_icon` and it contains
+this `google.svg` content.
+
+```html
+<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+    &lt;title>Google icon&lt;/title>
+    <g id="google">
+        <path
+            d="M12.24 10.285V14.4h6.806c-.275 1.765-2.056 5.174-6.806 5.174-4.095 0-7.439-3.389-7.439-7.574s3.345-7.574 7.439-7.574c2.33 0 3.891.989 4.785 1.849l3.254-3.138C18.189 1.186 15.479 0 12.24 0c-6.635 0-12 5.365-12 12s5.365 12 12 12c6.926 0 11.52-4.869 11.52-11.726 0-.788-.085-1.39-.189-1.989H12.24z"
+        ></path>
+    </g>
+</svg>
+```
+
+Import the SVG resource into your component, and set a variable to the static resource URL plus the `<g>` ID.
+
+```javascript
+// myComponent.js
+import { LightningElement } from 'lwc';
+import mySVG_icon from '@salesforce/resourceUrl/mySVG_icon';
+
+export default class myComponent extends LightningElement {
+    googleIcon = mySVG_icon + '#google';
+}
+```
+
+Pass the static resource variable in the `src` attribute.
+
+```html
+<template>
+    <lightning-icon src={googleIcon}></lightning-icon>
+</template>
+```
+
+For more information about static resources and using SVG, see [Access Static Resources](https://developer.salesforce.com/docs/platform/lwc/guide/create-resources) and [Use SVG Resources](https://developer.salesforce.com/docs/platform/lwc/guide/use-svg-in-component) in the _Lightning Web Components Developer Guide_.
+
+##### Overriding the Icon Fill Color of Your Imported Icons
+
+Note that icons you import have a default fill attribute value `#fff`, which
+you can override in your svg sprite directly. For example, change the color to
+a shade of green by inserting `fill=#648079` in the `<svg>` element.
+
+Alternatively, use CSS custom properties to change the fill color on your imported icon. See the non-utility icon example in the **Customize Component Styling** section.
+
+#### Accessibility
+
+Use the `alternative-text` attribute to describe the icon for assistive devices. The description
+should indicate what happens when you click the button, for example 'Upload
+File', not what the icon looks like, 'Paperclip'.
+
+Sometimes an icon is decorative and does not need a description. But icons can
+switch between being decorative or informational based on the screen size. If
+you choose not to include an `alternative-text` description, check smaller
+screens and windows to ensure that the icon is decorative on all formats.
+
+#### Usage Considerations
+
+Icons are not available in Lightning Out, but they are available in Lightning Components for Visualforce and other experiences.
+
+For IE11, the custom icon feature is disabled for now due to performance issues.
+
+#### Source Code
+
+`lightning-icon` is available in the [Base Components Recipes GitHub repository](https://github.com/salesforce/base-components-recipes#documentation). It's transpiled into the `c` namespace so that you can use it in your own projects.

package/src/lightning/icon/__examples__/basic/basic.html

@@ -0,0 +1,41 @@
+<template>
+    <p id="action" class="slds-box slds-text-heading_small">Action icons represent actions a user can take. The default
+        size of action icons are larger than the others. <br /><br />
+        <lightning-icon icon-name="action:approval" alternative-text="Approved" title="Approved"></lightning-icon>
+        <lightning-icon icon-name="action:delete" alternative-text="Delete" title="Delete"></lightning-icon>
+        <lightning-icon icon-name="action:new_note" alternative-text="New note" title="New note"></lightning-icon>
+        <lightning-icon icon-name="action:preview" alternative-text="Preview" title="Preview"></lightning-icon>
+    </p>
+    <p id="doctype" class="slds-box slds-text-heading_small">Doctype icons represent a type of file when a preview or
+        image is unavailable. <br /><br />
+        <lightning-icon icon-name="doctype:audio" alternative-text="Audio file" title="Audio"></lightning-icon>
+        <lightning-icon icon-name="doctype:image" alternative-text="Image file" title="Image"></lightning-icon>
+        <lightning-icon icon-name="doctype:mp4" alternative-text="MP4 file" title="MP4"></lightning-icon>
+        <lightning-icon icon-name="doctype:xml" alternative-text="XML file" title="XML"></lightning-icon>
+    </p>
+
+    <p id="standard" class="slds-box slds-text-heading_small">Standard icons represent entities and objects within
+        Salesforce. <br /><br />
+        <lightning-icon icon-name="standard:event" alternative-text="Event" title="Event"></lightning-icon>
+        <lightning-icon icon-name="standard:account" alternative-text="Account" title="Account"></lightning-icon>
+        <lightning-icon icon-name="standard:address" alternative-text="Address" title="Address"></lightning-icon>
+        <lightning-icon icon-name="standard:email" alternative-text="Email" title="Email"></lightning-icon>
+    </p>
+
+    <p id="utility" class="slds-box slds-text-heading_small">Utility icons are used throughout the interface and are
+        SVGs for extensibility. <br /><br />
+        <lightning-icon icon-name="utility:connected_apps" alternative-text="Connected" title="Connected">
+        </lightning-icon>
+        <lightning-icon icon-name="utility:warning" alternative-text="Warning!" title="Warning"></lightning-icon>
+        <lightning-icon icon-name="utility:error" alternative-text="Error!" title="Error"></lightning-icon>
+        <lightning-icon icon-name="utility:image" alternative-text="Utility image" title="Image"></lightning-icon>
+    </p>
+
+    <p id="custom" class="slds-box slds-text-heading_small">Custom icons are available in Salesforce to represent user
+        created objects.<br /><br />
+        <lightning-icon icon-name="custom:custom11" title="custom11"></lightning-icon>
+        <lightning-icon icon-name="custom:custom33" title="custom33"></lightning-icon>
+        <lightning-icon icon-name="custom:custom51" title="custom51"></lightning-icon>
+        <lightning-icon icon-name="custom:custom88" title="custom88"></lightning-icon>
+    </p>
+</template>

package/src/lightning/icon/__examples__/basic/basic.js

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