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

package/src/lightning/buttonIcon/__docs__/buttonIcon.md

@@ -0,0 +1,213 @@
+---
+examples:
+    - name: basic
+      label: Button Icon Variants
+      description: Button icons with multiple variants.
+    - name: sizes
+      label: Button Icon Sizes
+      description: Button icons with multiple sizes.
+    - name: inverse
+      label: Button Icons with Inverse Variants
+      description: Button icons with two types of inverse variants to display on a dark background.
+---
+
+A `lightning-button-icon` component represents an icon-only button element that
+executes an action in a controller. Clicking the button triggers the JavaScript
+method set for `onclick`.
+
+Here is an example.
+
+```html
+<template>
+    <lightning-button-icon
+        icon-name="utility:close"
+        variant="bare"
+        onclick={handleClick}
+        alternative-text="Close window"
+    >
+    </lightning-button-icon>
+</template>
+```
+
+#### Component Styling
+
+`lightning-button-icon` implements the
+[button icons](https://www.lightningdesignsystem.com/components/button-icons/) blueprint in the Salesforce Lightning Design System (SLDS).
+
+You can use a combination of the `icon-class`, `size`, and `variant`
+attributes to customize the button and icon styles.
+
+To customize styling on the icon element, use the
+`icon-class` attribute. This example creates an icon-only button with bare
+variant and icon styling. Only SLDS utility classes are currently supported with `icon-class`.
+
+```html
+<lightning-button-icon
+    icon-name="utility:settings"
+    variant="bare"
+    alternative-text="Settings"
+    icon-class="slds-m-around_medium"
+>
+</lightning-button-icon>
+```
+
+##### Icons
+
+Use the `icon-name` attribute to add a utility icon to the button.
+
+The SLDS utility icon category offers nearly 200 utility
+icons that can be used in `lightning-button-icon`. Although SLDS provides several categories of icons, only the utility category can be used in `lightning-button-icon`.
+
+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 latest
+SLDS resources become available only when the new release
+is available in your org.
+
+##### Variants
+
+Use the `variant` attribute with one of these values to apply styling.
+
+-   `bare` displays an icon without a container or border
+-   `bare-inverse` displays an icon in white color without a container or border, useful for dark backgrounds
+-   `border` is the default variant, an icon in a transparent container with a border
+-   `border-filled` displays an icon in a filled container with a border
+-   `border-inverse` displays an icon in a transparent container with a border, useful for dark backgrounds
+-   `brand` displays an icon in white color in a blue container with a blue border
+-   `container` displays an icon in a transparent container without a border
+
+For the `bare` and `bare-inverse` variants, the `size` class applies to the icon itself. For all other variants, the `size` class applies to the button.
+
+##### Sizes
+
+Adjust the button and icon sizes using the `size` attribute with one of these values.
+
+For `bare` and `bare-inverse` variants:
+
+-   `medium` is the default size, which creates a 14px by 14px icon
+-   `small` creates a 12px by 12px icon
+-   `x-small` creates a 8px by 8px icon
+-   `large` creates a 24px by 24px icon
+
+For other variants:
+
+-   `medium` is the default size, which creates a 32px by 32px button enclosing a 14px by 14px icon.
+-   `small` creates a 24px by 24px button enclosing a 14px by 14px icon
+-   `x-small` creates a 20px by 20px button enclosing a 12px by 12px icon
+-   `xx-small` creates a 16px by 16px button enclosing a 8px by 8px icon
+
+##### 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 second button using the `slds-m-left_xx-small` class.
+
+```html
+<lightning-button-icon
+    icon-name="utility:zoomin"
+    alternative-text="Zoom in"
+    title="Zoom in"
+></lightning-button-icon>
+<lightning-button-icon
+    icon-name="utility:zoomout"
+    alternative-text="Zoom out"
+    title="Zoom out"
+    class="slds-m-left_xx-small"
+></lightning-button-icon>
+```
+
+To apply custom styling, use the `:host` selector or define a custom class using the `class` attribute.
+
+```html
+<lightning-button-icon
+    icon-name="utility:zoomin"
+    alternative-text="Zoom in"
+    title="Zoom in"
+    class="my-round-button"
+></lightning-button-icon>
+```
+
+Use SLDS styling hooks to customize the component's styles. For example, specify the border radius using the `--slds-c-button-radius-border` custom property.
+
+```css
+.my-round-button {
+    --slds-c-button-radius-border: 20px;
+}
+```
+
+`lightning-button-icon` contains the same customizable elements as `lightning-button`, which supports `--slds-c-button-*` custom properties.
+
+Custom properties for button icons work only with particular `lightning-button` variants.
+
+| CSS Custom Property               | `lightning-button-icon` Variants                             |
+| --------------------------------- | ------------------------------------------------------------ |
+| `--slds-c-button-color-background` | `border` (default), `bare`, `bare-inverse`, and `container`  |
+| `--slds-c-button-color-border`     | `bare`, `bare-inverse`, and `container`                      |
+| `--slds-c-button-text-color`       | N/A                                                          |
+| `--slds-c-button-text-color-*`     | `border` (default), `bare`, `container`, and `border-filled` |
+| `--slds-c-button-radius-border`    | all                                                          |
+| `--slds-c-button-sizing-border`    | `bare`, `bare-inverse`, `border-inverse` and `container`     |
+
+See [Styling Hooks Overview](https://www.lightningdesignsystem.com/components/buttons/#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-button-icon`, see the **Source Code** section.
+
+#### Usage Considerations
+
+Icons are not available in Lightning Out, but they are available in Lightning Components for Visualforce and other experiences.
+
+#### Accessibility
+
+`lightning-button-icon` contains an informational icon, which conveys information that surrounding text doesn't.
+For each icon, provide assistive text that describes the button's action.
+
+Use the `alternative-text` attribute to describe the icon. The description should indicate what happens when you click the button, for example 'Upload File', not what the icon looks like, 'Paperclip'.
+
+The description you provide to `alternative-text` is available to users in two ways.
+
+-   As hover text when you hover over the button
+-   As hidden text for assistive technologies
+
+To override the hover text provided by `alternative-text`, use the `title` attribute, which corresponds to the native browser tooltip.
+The description you provide to `title` displays when you hover over the button. To support touch-only devices, keyboard navigation, and assistive technologies, use `title` together with `label` or `alternative-text`.
+
+To display a contextual popup on the button, use the `tooltip` attribute.
+The popup becomes visible when you hover over the button, or after the button receives keyboard focus. Showing the popup on hover or on keyboard focus ensures that all users can access it, even if they aren’t using a mouse. The button is rendered with `aria-describedby`, linking it to the ID of the popup, which helps assistive technology read the popup content.
+
+If you use both `title` and `tooltip` attributes, they are both visible when you hover over the button. Some screen readers don’t support the `title` attribute and many of them don’t read the `title` attribute by default.
+
+```html
+<lightning-button-icon
+    icon-name="utility:settings"
+    title="Settings"
+    tooltip="Display your account settings"
+    alternative-text="Hidden text for assistive technology"
+>
+</lightning-button-icon>
+```
+
+For sighted users, make sure your description on `title` and `tooltip` are not repetitive. We recommend providing detailed information to `tooltip` and make `title` more concise if you use both.
+
+Buttons that display an icon instead of text do not have an accessible name. To provide an accessible name in `lightning-button-icon`, use the `aria-label` attribute. If there is visible text labeling the element, use `aria-labelled-by` instead.
+
+Use the following accessibility and `aria` attributes on `lightning-button-icon`.
+
+| Attribute        | Type              | Description                                                                                                                                                                                                                                                                                                                                          |
+| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| accesskey        | string            | A shortcut key to activate or place focus on the button.                                                                                                                                                                                                                                                                                             |
+| aria-atomic      | boolean           | Specifies whether the screen reader should always present the live region as a whole, even if only part of the region changes. The default is `false`.                                                                                                                                                                                               |
+| aria-controls    | ID reference list | An element ID or a space-separated list of element IDs whose presence or content is controlled by this button.                                                                                                                                                                                                                                       |
+| aria-describedby | ID reference list | An element ID or a space-separated list of element IDs that provide descriptive labels for the button.                                                                                                                                                                                                                                               |
+| aria-expanded    | boolean           | Indicates whether a collapsible element that's controlled by the button is expanded or collapsed. To reference the controlled element, use `aria-controls`.                                                                                                                                                                                          |
+| aria-haspopup    | token             | Indicates that the button has an interactive popup element. Valid values are 'true', 'dialog', 'menu', 'listbox', 'tree', and 'grid'. To create a button that displays a list of menu items when clicked, use `lightning-button-menu` instead.                                                                                                       |
+| aria-label       | string            | Provides an assistive label where a visible label cannot be used.                                                                                                                                                                                                                                                                                    |
+| aria-live        | token             | Indicates the button can dynamically update without a page reload, and specifies how the change is announced by assistive technologies. Possible values include `off`, `polite`, and `assertive`. The default is `off`. For the screen reader to announce changes when the user is idle, use `polite`. For immediate notifications, use `assertive`. |
+
+For more information, see the [WAI-ARIA Specification](https://www.w3.org/TR/wai-aria/).
+
+#### Source Code
+
+`lightning-button-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/buttonIcon/__examples__/basic/basic.css

@@ -0,0 +1,3 @@
+.lgc-bg {
+    background-color: rgb(242 242 242);
+}

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

@@ -0,0 +1,85 @@
+<template>
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+        <h2 class="slds-text-heading_medium slds-m-bottom_medium">
+            Button-icons with the <code>variant</code> attribute omitted or set to the default value of <code>border</code>.
+        </h2>
+        <!-- with border / by default -->
+        <div class="slds-p-around_medium lgc-bg">
+            <lightning-button-icon icon-name="utility:settings"  alternative-text="Settings" title="Settings"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:adduser"   alternative-text="Add user" class="slds-m-left_xx-small" title="Add user"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:delete"    alternative-text="Delete"   class="slds-m-left_xx-small" title="Delete"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:save"      alternative-text="Save"     class="slds-m-left_xx-small" title="Save"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:bookmark"  alternative-text="Bookmark" class="slds-m-left_xx-small" title="Bookmark"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:zoomin"    alternative-text="Zoom in"  class="slds-m-left_xx-small" title="Zoom in"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:zoomout"   alternative-text="Zoom out" class="slds-m-left_xx-small" title="Zoom out"></lightning-button-icon>
+        </div>
+    </div>
+
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+        <h2 class="slds-text-heading_medium slds-m-bottom_medium">
+            Button-icons with the <code>variant</code> attribute set to <code>bare</code>.
+        </h2>
+
+        <!-- bare -->
+        <div class="slds-p-around_medium lgc-bg">
+            <lightning-button-icon icon-name="utility:settings"  variant="bare" alternative-text="Settings" title="Settings"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:adduser"   variant="bare" alternative-text="Add user" class="slds-m-left_xx-small" title="Add user"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:delete"    variant="bare" alternative-text="Delete"   class="slds-m-left_xx-small" title="Delete"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:save"      variant="bare" alternative-text="Save"     class="slds-m-left_xx-small" title="Save"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:bookmark"  variant="bare" alternative-text="Bookmark" class="slds-m-left_xx-small" title="Bookmark"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:zoomin"    variant="bare" alternative-text="Zoom in"  class="slds-m-left_xx-small" title="Zoom in"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:zoomout"   variant="bare" alternative-text="Zoom out" class="slds-m-left_xx-small" title="Zoom out"></lightning-button-icon>
+        </div>
+    </div>
+
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+            <h2 class="slds-text-heading_medium slds-m-bottom_medium">
+                Button-icons with the <code>variant</code> attribute set to <code>brand</code>.
+            </h2>
+    
+            <!-- bare -->
+            <div class="slds-p-around_medium lgc-bg">
+                <lightning-button-icon icon-name="utility:settings"  variant="brand" alternative-text="Settings"></lightning-button-icon>
+                <lightning-button-icon icon-name="utility:adduser"   variant="brand" alternative-text="Add user" class="slds-m-left_xx-small" title="Add user"></lightning-button-icon>
+                <lightning-button-icon icon-name="utility:delete"    variant="brand" alternative-text="Delete"   class="slds-m-left_xx-small" title="Delete"></lightning-button-icon>
+                <lightning-button-icon icon-name="utility:save"      variant="brand" alternative-text="Save"     class="slds-m-left_xx-small" title="Save"></lightning-button-icon>
+                <lightning-button-icon icon-name="utility:bookmark"  variant="brand" alternative-text="Bookmark" class="slds-m-left_xx-small" title="Bookmark"></lightning-button-icon>
+                <lightning-button-icon icon-name="utility:zoomin"    variant="brand" alternative-text="Zoom in"  class="slds-m-left_xx-small" title="Zoom in"></lightning-button-icon>
+                <lightning-button-icon icon-name="utility:zoomout"   variant="brand" alternative-text="Zoom out" class="slds-m-left_xx-small" title="Zoom out"></lightning-button-icon>
+            </div>
+        </div>
+
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+        <h2 class="slds-text-heading_medium slds-m-bottom_medium">
+            Button-icons with the <code>variant</code> attribute set to <code>container</code>.
+        </h2>
+
+        <!-- with container -->
+        <div class="slds-p-around_medium lgc-bg">
+            <lightning-button-icon icon-name="utility:settings"  variant="container" alternative-text="Settings" title="Settings"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:adduser"   variant="container" alternative-text="Add user" class="slds-m-left_xx-small" title="Add user"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:delete"    variant="container" alternative-text="Delete"   class="slds-m-left_xx-small" title="Delete"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:save"      variant="container" alternative-text="Save"     class="slds-m-left_xx-small" title="Save"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:bookmark"  variant="container" alternative-text="Bookmark" class="slds-m-left_xx-small" title="Bookmark"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:zoomin"    variant="container" alternative-text="Zoom in"  class="slds-m-left_xx-small" title="Zoom in"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:zoomout"   variant="container" alternative-text="Zoom out" class="slds-m-left_xx-small" title="Zoom out"></lightning-button-icon>
+        </div>
+    </div>
+
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+        <h2 class="slds-text-heading_medium slds-m-bottom_medium">
+            Button-icons with the <code>variant</code> attribute set to <code>border-filled</code>.
+        </h2>
+
+        <!-- with border filled -->
+        <div class="slds-p-around_medium lgc-bg">
+            <lightning-button-icon icon-name="utility:settings"  variant="border-filled" alternative-text="Settings" title="Settings"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:adduser"   variant="border-filled" alternative-text="Add user" class="slds-m-left_xx-small" title="Add user"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:delete"    variant="border-filled" alternative-text="Delete"   class="slds-m-left_xx-small" title="Delete"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:save"      variant="border-filled" alternative-text="Save"     class="slds-m-left_xx-small" title="Save"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:bookmark"  variant="border-filled" alternative-text="Bookmark" class="slds-m-left_xx-small" title="Bookmark"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:zoomin"    variant="border-filled" alternative-text="Zoom in"  class="slds-m-left_xx-small" title="Zoom in"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:zoomout"   variant="border-filled" alternative-text="Zoom out" class="slds-m-left_xx-small" title="Zoom out"></lightning-button-icon>
+        </div>
+    </div>
+</template>

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

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

package/src/lightning/buttonIcon/__examples__/inverse/inverse.css

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

package/src/lightning/buttonIcon/__examples__/inverse/inverse.html

@@ -0,0 +1,33 @@
+<template>
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+        <h2 class="slds-text-heading_medium slds-m-bottom_medium">
+            Button-icons with the <code>variant</code> attribute set to <code>border-inverse</code>.
+        </h2>
+        <!-- with border / by default -->
+        <div class="slds-p-around_medium lgc-bg-inverse">
+            <lightning-button-icon icon-name="utility:settings"  alternative-text="Settings" variant="border-inverse" title="Settings"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:adduser"   alternative-text="Add user" variant="border-inverse" class="slds-m-left_xx-small" title="Add user"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:delete"    alternative-text="Delete"   variant="border-inverse" class="slds-m-left_xx-small" title="Delete"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:save"      alternative-text="Save"     variant="border-inverse" class="slds-m-left_xx-small" title="Save"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:bookmark"  alternative-text="Bookmark" variant="border-inverse" class="slds-m-left_xx-small" title="Bookmark"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:zoomin"    alternative-text="Zoom in"  variant="border-inverse" class="slds-m-left_xx-small" title="Zoom in"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:zoomout"   alternative-text="Zoom out" variant="border-inverse" class="slds-m-left_xx-small" title="Zoom out"></lightning-button-icon>
+        </div>
+    </div>
+
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+        <h2 class="slds-text-heading_medium slds-m-bottom_medium">
+            Button-icons with the <code>variant</code> attribute set to <code>bare-inverse</code>.
+        </h2>
+        <!-- with border / by default -->
+        <div class="slds-p-around_medium lgc-bg-inverse">
+            <lightning-button-icon icon-name="utility:settings"  alternative-text="Settings" variant="bare-inverse" title="Settings"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:adduser"   alternative-text="Add user" variant="bare-inverse" class="slds-m-left_xx-small" title="Add user"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:delete"    alternative-text="Delete"   variant="bare-inverse" class="slds-m-left_xx-small" title="Delete"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:save"      alternative-text="Save"     variant="bare-inverse" class="slds-m-left_xx-small" title="Save"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:bookmark"  alternative-text="Bookmark" variant="bare-inverse" class="slds-m-left_xx-small" title="Bookmark"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:zoomin"    alternative-text="Zoom in"  variant="bare-inverse" class="slds-m-left_xx-small" title="Zoom in"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:zoomout"   alternative-text="Zoom out" variant="bare-inverse" class="slds-m-left_xx-small" title="Zoom out"></lightning-button-icon>
+        </div>
+    </div>
+</template>

package/src/lightning/buttonIcon/__examples__/inverse/inverse.js

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

package/src/lightning/buttonIcon/__examples__/sizes/sizes.html

@@ -0,0 +1,28 @@
+<template>
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+        <h2 class="slds-text-heading_medium slds-m-bottom_medium">
+            Button-icons with the <code>size</code> attribute set to a valid value (<code>xx-small, x-small, small, medium</code>).
+        </h2>
+
+        <!--Sizes -->
+        <div class="slds-p-around_medium">
+            <lightning-button-icon icon-name="utility:down"  size="xx-small" alternative-text="View More"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:down"  size="x-small"  alternative-text="View More" class="slds-m-left_xx-small"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:down"  size="small"    alternative-text="View More" class="slds-m-left_xx-small"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:down"  size="medium"   alternative-text="View More" class="slds-m-left_xx-small"></lightning-button-icon>
+        </div>
+    </div>
+
+    <div class="slds-m-top_medium slds-m-bottom_x-large">
+        <h2 class="slds-text-heading_medium slds-m-bottom_medium">
+            Button-icons with the <code>variant</code> attribute set to <code>bare</code> and the <code>size</code> attribute set to a valid value (<code>x-small, small, medium, large</code>).
+        </h2>
+
+        <div class="slds-p-around_medium">
+            <lightning-button-icon icon-name="utility:down"  size="x-small"   variant="bare" alternative-text="View More"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:down"  size="small"     variant="bare" alternative-text="View More" class="slds-m-left_xx-small"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:down"  size="medium"    variant="bare" alternative-text="View More" class="slds-m-left_xx-small"></lightning-button-icon>
+            <lightning-button-icon icon-name="utility:down"  size="large"     variant="bare" alternative-text="View More" class="slds-m-left_xx-small"></lightning-button-icon>
+        </div>
+    </div>
+</template>

package/src/lightning/buttonIcon/__examples__/sizes/sizes.js

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

package/src/lightning/buttonIcon/buttonIcon.js

@@ -10,6 +10,8 @@ const DEFAULT_SIZE = 'medium';
 const DEFAULT_VARIANT = 'border';
 const DEFAULT_TYPE = 'button';
 
+export const relatedTarget = Symbol('relatedTarget');
+
 /**
  * An icon-only HTML button.
  */
@@ -289,8 +291,14 @@ export default class LightningButtonIcon extends LightningPrimitiveButton {
         this.dispatchEvent(new CustomEvent('focus'));
     }
 
-    handleBlur() {
-        this.dispatchEvent(new CustomEvent('blur'));
+    handleBlur(event) {
+        this.dispatchEvent(
+            new CustomEvent('blur', {
+                detail: {
+                    [relatedTarget]: event.relatedTarget,
+                },
+            })
+        );
     }
 
     /**

package/src/lightning/buttonIconStateful/__docs__/buttonIconStateful.md

@@ -0,0 +1,185 @@
+---
+examples:
+    - name: basic
+      label: Stateful Button Icons
+      description: Stateful button icons can be toggled between states. They support multiple sizes and can be disabled.
+    - name: variants
+      label: Stateful Button Icons with Border Variants
+      description: Button icons using the two types of border variants.
+---
+
+A `lightning-button-icon-stateful` component represents an icon-only button
+element that toggles between two states. For example, you can use this
+component for capturing a customer's feedback on a blog post (like or
+dislike). Clicking the button triggers the handler set for `onclick` and changes the state of the icon using the `selected` attribute.
+
+This example creates a Like button that toggles between two states. The Like button is selected by default. The button's state is stored in the `selected` attribute.
+
+Selecting the Dislike button also toggles the state on the Like button and deselects it.
+
+```html
+<template>
+    <lightning-button-icon-stateful
+        icon-name="utility:like"
+        selected={liked}
+        alternative-text="Like"
+        onclick={handleToggle}
+    >
+    </lightning-button-icon-stateful>
+</template>
+```
+
+Handle the `click` event in your JavaScript code.
+
+```javascript
+import { LightningElement } from 'lwc';
+
+export default class MyComponentName extends LightningElement {
+    liked = true;
+
+    handleToggle() {
+        this.liked = !this.liked;
+    }
+}
+```
+
+#### Component Styling
+
+`lightning-button-icon-stateful` implements the
+[button icons](https://www.lightningdesignsystem.com/components/button-icons/) blueprint in the Salesforce Lightning Design System (SLDS).
+
+You can use a combination of the `variant` and `size` attributes to
+customize the button and icon styles.
+
+##### Icons
+
+Use the `icon-name` attribute to add a utility icon to the button.
+
+The SLDS utility icon category offers nearly 200 utility
+icons that can be used in `lightning-button-icon-stateful`. Although the
+SLDS provides several categories of icons, only the utility
+category can be used with this component.
+
+Visit [utility icons](https://lightningdesignsystem.com/icons/#utility) in
+the SLDS 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 latest
+SLDS resources become available only when the new release is available in your org.
+
+##### Variants
+
+Use the `variant` attribute with one of these values to apply styling.
+
+-   `border` is the default variant, an icon in a transparent container with a border
+-   `border-filled` displays an icon in a filled container with a border
+-   `border-inverse` displays an icon in a transparent container with a border, useful for dark backgrounds
+
+##### Sizes
+
+Adjust the button and icon sizes using the `size` attribute with one of these values.
+
+-   `medium` is the default size, which creates a 32px by 32px button enclosing a 14px by 14px icon.
+-   `small` creates a 24px by 24px button enclosing a 14px by 14px icon
+-   `x-small` creates a 20px by 20px button enclosing a 12px by 12px icon
+-   `xx-small` creates a 16px by 16px button enclosing a 8px by 8px icon
+
+##### 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 second button using an SLDS class.
+
+```html
+<lightning-button-icon-stateful
+    icon-name="utility:like"
+    selected={likeState}
+    onclick={handleLikeButtonClick}
+    alternative-text="Like"
+></lightning-button-icon-stateful>
+<lightning-button-icon-stateful
+    icon-name="utility:answer"
+    selected={answerState}
+    onclick={handleAnswerButtonClick}
+    alternative-text="Answer"
+    class="slds-m-left_xx-small"
+></lightning-button-icon-stateful>
+```
+
+To apply custom styling, use the `:host` selector or define a custom class using the `class` attribute.
+
+```html
+<lightning-button-icon-stateful
+    icon-name="utility:like"
+    selected={likeState}
+    onclick={handleLikeButtonClick}
+    alternative-text="Like"
+    variant="border-inverse"
+    class="my-brand"
+></lightning-button-icon-stateful>
+```
+
+Use SLDS styling hooks to customize the component's styles. For example, specify the background color on the button using the `--slds-c-button-color-background` custom property.
+
+```css
+.my-brand {
+    --slds-c-button-color-background: purple;
+}
+```
+
+`lightning-button-icon-stateful` contains the same customizable elements as `lightning-button`, which supports `--slds-c-button-*` custom properties.
+
+Custom properties for stateful button icons work only with particular `lightning-button-icon-stateful` variants.
+
+| CSS Custom Property               | `lightning-button-icon-stateful` Variants |
+| --------------------------------- | ----------------------------------------- |
+| `--slds-c-button-color-background` | `border` (default) and `border-inverse`   |
+| `--slds-c-button-color-border`     | N/A                                       |
+| `--slds-c-button-text-color`       | N/A                                       |
+| `--slds-c-button-text-color-*`     | `border` (default) and `border-filled`    |
+| `--slds-c-button-radius-border`    | all                                       |
+| `--slds-c-button-sizing-border`    | N/A                                       |
+
+See [Styling Hooks Overview](https://www.lightningdesignsystem.com/components/buttons/#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-button-icon-stateful`, see the **Source Code** section.
+
+#### Usage Considerations
+
+Icons are not available in Lightning Out, but they are available in Lightning Components for Visualforce and other experiences.
+
+#### Accessibility
+
+`lightning-button-icon-stateful` contains an informational icon, which conveys information that surrounding text doesn't. Each icon should be accompanied by either assistive text.
+When selected, the button renders with `aria-pressed="true"`. When not selected, the button renders with `aria-pressed="false"`.
+The `aria-pressed` attribute enables screen readers to announce whether a button is pressed or not.
+
+Use the `alternative-text` attribute to describe the icon.
+The description should indicate what happens when you click the button, for example 'Upload File', not what the icon looks like, 'Paperclip'.
+
+The text is available to users in two ways.
+
+-   On the tooltip when you hover over the button
+-   As text for assistive technologies
+
+Buttons that only show an icon to represent do not have an accessible name. For `lightning-button-icon-stateful`, provide the accessible name using the `aria-label` attribute.
+
+Use the following accessibility and `aria` attributes on `lightning-button-icon-stateful`.
+
+| Attribute        | Type              | Description                                                                                                                                                                                                                                                                                                                     |
+| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| accesskey        | string            | A shortcut key to activate or place focus on the button                                                                                                                                                                                                                                                                         |
+| aria-atomic      | boolean           | Specifies whether the screen reader should always present the live region as a whole, even if only part of the region changes. The default is `false`.                                                                                                                                                                          |
+| aria-controls    | ID reference list | An element ID or a space-separated list of element IDs whose presence or content is controlled by this button.                                                                                                                                                                                                                  |
+| aria-describedby | ID reference list | An element ID or a space-separated list of element IDs that provide a descriptive label or description for the button.                                                                                                                                                                                                          |
+| aria-expanded    | boolean           | Indicates whether the state of an element, controlled by the button, is expanded or collapsed. To reference the controlled element, use `aria-controls`.                                                                                                                                                                        |
+| aria-label       | string            | Provides an assistive label where a visible label cannot be used.                                                                                                                                                                                                                                                               |
+| aria-live        | string            | Indicates whether the button will be updated, and describes the types of updates assistive technologies will make. Possible values include `off`, `polite`, and `assertive`. The default is `off`. For the screen reader to announce changes when the user is idle, use `polite`. For immediate notifications, use `assertive`. |
+
+For more information, see the [WAI-ARIA Specification](https://www.w3.org/TR/wai-aria/).
+
+#### Source Code
+
+`lightning-button-icon-stateful` 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/buttonIconStateful/__examples__/basic/basic.css

@@ -0,0 +1,3 @@
+.lgc-bg {
+    background-color: rgb(242 242 242);
+}