The file is
diff --git a/docs/components/format-date.md b/docs/components/format-date.md index 1e8a22028..ccd58b163 100644 --- a/docs/components/format-date.md +++ b/docs/components/format-date.md @@ -2,8 +2,6 @@ [component-header:sl-format-date] -Formats a date/time using the specified locale and options. - Localization is handled by the browser's [`Intl.DateTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). No language packs are required. ```html preview diff --git a/docs/components/format-number.md b/docs/components/format-number.md index 77cb9cbc0..67ae60e83 100644 --- a/docs/components/format-number.md +++ b/docs/components/format-number.md @@ -2,8 +2,6 @@ [component-header:sl-format-number] -Formats a number using the specified locale and options. - Localization is handled by the browser's [`Intl.NumberFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat). No language packs are required. ```html preview diff --git a/docs/components/icon-button.md b/docs/components/icon-button.md index f2922eed8..a95557f3a 100644 --- a/docs/components/icon-button.md +++ b/docs/components/icon-button.md @@ -2,8 +2,6 @@ [component-header:sl-icon-button] -Icons buttons are simple, icon-only buttons that can be used for actions and in toolbars. - For a full list of icons that come bundled with Shoelace, refer to the [icon component](/components/icon). ```html preview diff --git a/docs/components/icon.md b/docs/components/icon.md index 6b6461073..72e084bb5 100644 --- a/docs/components/icon.md +++ b/docs/components/icon.md @@ -2,8 +2,6 @@ [component-header:sl-icon] -Icons are symbols that can be used to represent various options within an application. - Shoelace comes bundled with over 1,500 icons courtesy of the [Bootstrap Icons](https://icons.getbootstrap.com/) project. These icons are part of the `default` icon library. If you prefer, you can register [custom icon libraries](#icon-libraries) as well. ?> Depending on how you're loading Shoelace, you may need to copy icon assets and/or [set the base path](getting-started/installation#setting-the-base-path) so Shoelace knows where to load them from. Otherwise, icons may not appear and you'll see 404 Not Found errors in the dev console. diff --git a/docs/components/image-comparer.md b/docs/components/image-comparer.md index a8cf946ef..a0853e4ae 100644 --- a/docs/components/image-comparer.md +++ b/docs/components/image-comparer.md @@ -2,8 +2,6 @@ [component-header:sl-image-comparer] -Compare visual differences between similar photos with a sliding panel. - For best results, use images that share the same dimensions. The slider can be controlled by dragging or pressing the left and right arrow keys. (Tip: press shift + arrows to move the slider in larger intervals, or home + end to jump to the beginning or end.) ```html preview diff --git a/docs/components/include.md b/docs/components/include.md index 86ce4e1a9..3a3805cbe 100644 --- a/docs/components/include.md +++ b/docs/components/include.md @@ -2,8 +2,6 @@ [component-header:sl-include] -Includes give you the power to embed external HTML files into the page. - Included files are asynchronously requested using `window.fetch()`. Requests are cached, so the same file can be included multiple times, but only one request will be made. The included content will be inserted into the `` element's default slot so it can be easily accessed and styled through the light DOM.
diff --git a/docs/components/input.md b/docs/components/input.md
index 3df755b97..388f86f83 100644
--- a/docs/components/input.md
+++ b/docs/components/input.md
@@ -2,8 +2,6 @@
[component-header:sl-input]
-Inputs collect data from the user.
-
```html preview
Option 1
diff --git a/docs/components/menu-label.md b/docs/components/menu-label.md
index b8b1647a5..c606eb5b4 100644
--- a/docs/components/menu-label.md
+++ b/docs/components/menu-label.md
@@ -2,8 +2,6 @@
[component-header:sl-menu-label]
-Menu labels are used to describe a group of menu items.
-
```html preview
Fruits
diff --git a/docs/components/menu.md b/docs/components/menu.md
index d2321864b..270071af8 100644
--- a/docs/components/menu.md
+++ b/docs/components/menu.md
@@ -2,8 +2,6 @@
[component-header:sl-menu]
-Menus provide a list of options for the user to choose from.
-
You can use [menu items](/components/menu-item), [menu labels](/components/menu-label), and [dividers](/components/divider) to compose a menu. Menus support keyboard interactions, including type-to-select an option.
```html preview
diff --git a/docs/components/mutation-observer.md b/docs/components/mutation-observer.md
index 0918a9f22..dd669aaa4 100644
--- a/docs/components/mutation-observer.md
+++ b/docs/components/mutation-observer.md
@@ -2,8 +2,6 @@
[component-header:sl-mutation-observer]
-The Mutation Observer component offers a thin, declarative interface to the [`MutationObserver API`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
-
The mutation observer will report changes to the content it wraps through the `sl-mutation` event. When emitted, a collection of [MutationRecord](https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord) objects will be attached to `event.detail` that contains information about how it changed.
```html preview
diff --git a/docs/components/popup.md b/docs/components/popup.md
index 373b4beb0..5122dac12 100644
--- a/docs/components/popup.md
+++ b/docs/components/popup.md
@@ -2,8 +2,6 @@
[component-header:sl-popup]
-Popup is a utility that lets you declaratively anchor "popup" containers to another element.
-
This component's name is inspired by [``](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/Popup/explainer.md). It uses [Floating UI](https://floating-ui.com/) under the hood to provide a well-tested, lightweight, and fully declarative positioning utility for tooltips, dropdowns, and more.
Popup doesn't provide any styles — just positioning! The popup's preferred placement, distance, and skidding (offset) can be configured using attributes. An arrow that points to the anchor can be shown and customized to your liking. Additional positioning options are available and described in more detail below.
diff --git a/docs/components/progress-bar.md b/docs/components/progress-bar.md
index b8732a820..4aabd3c3e 100644
--- a/docs/components/progress-bar.md
+++ b/docs/components/progress-bar.md
@@ -2,8 +2,6 @@
[component-header:sl-progress-bar]
-Progress bars are used to show the status of an ongoing operation.
-
```html preview
Option 1
diff --git a/docs/components/radio.md b/docs/components/radio.md
index cd40541cc..58aa5e39e 100644
--- a/docs/components/radio.md
+++ b/docs/components/radio.md
@@ -2,8 +2,6 @@
[component-header:sl-radio]
-Radios allow the user to select a single option from a group.
-
Radios are designed to be used with [radio groups](/components/radio-group).
```html preview
diff --git a/docs/components/range.md b/docs/components/range.md
index ad106f3c5..2c72a6c04 100644
--- a/docs/components/range.md
+++ b/docs/components/range.md
@@ -2,8 +2,6 @@
[component-header:sl-range]
-Ranges allow the user to select a single value within a given range using a slider.
-
```html preview
Option 1
diff --git a/docs/components/skeleton.md b/docs/components/skeleton.md
index 014f59084..b72043aa9 100644
--- a/docs/components/skeleton.md
+++ b/docs/components/skeleton.md
@@ -2,8 +2,6 @@
[component-header:sl-skeleton]
-Skeletons are used to show where content will eventually be drawn.
-
These are simple containers for scaffolding layouts that mimic what users will see when content has finished loading. This prevents large areas of empty space during asynchronous operations.
Skeletons try not to be opinionated, as there are endless possibilities for designing layouts. Therefore, you'll likely use more than one skeleton to create the effect you want. If you find yourself using them frequently, consider creating a template that renders them with the desired arrangement and styles.
diff --git a/docs/components/spinner.md b/docs/components/spinner.md
index 56fbb0459..38ef26b7e 100644
--- a/docs/components/spinner.md
+++ b/docs/components/spinner.md
@@ -2,8 +2,6 @@
[component-header:sl-spinner]
-Spinners are used to show the progress of an indeterminate operation.
-
```html preview
diff --git a/docs/components/format-date.md b/docs/components/format-date.md index 1e8a22028..ccd58b163 100644 --- a/docs/components/format-date.md +++ b/docs/components/format-date.md @@ -2,8 +2,6 @@ [component-header:sl-format-date] -Formats a date/time using the specified locale and options. - Localization is handled by the browser's [`Intl.DateTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). No language packs are required. ```html preview diff --git a/docs/components/format-number.md b/docs/components/format-number.md index 77cb9cbc0..67ae60e83 100644 --- a/docs/components/format-number.md +++ b/docs/components/format-number.md @@ -2,8 +2,6 @@ [component-header:sl-format-number] -Formats a number using the specified locale and options. - Localization is handled by the browser's [`Intl.NumberFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat). No language packs are required. ```html preview diff --git a/docs/components/icon-button.md b/docs/components/icon-button.md index f2922eed8..a95557f3a 100644 --- a/docs/components/icon-button.md +++ b/docs/components/icon-button.md @@ -2,8 +2,6 @@ [component-header:sl-icon-button] -Icons buttons are simple, icon-only buttons that can be used for actions and in toolbars. - For a full list of icons that come bundled with Shoelace, refer to the [icon component](/components/icon). ```html preview diff --git a/docs/components/icon.md b/docs/components/icon.md index 6b6461073..72e084bb5 100644 --- a/docs/components/icon.md +++ b/docs/components/icon.md @@ -2,8 +2,6 @@ [component-header:sl-icon] -Icons are symbols that can be used to represent various options within an application. - Shoelace comes bundled with over 1,500 icons courtesy of the [Bootstrap Icons](https://icons.getbootstrap.com/) project. These icons are part of the `default` icon library. If you prefer, you can register [custom icon libraries](#icon-libraries) as well. ?> Depending on how you're loading Shoelace, you may need to copy icon assets and/or [set the base path](getting-started/installation#setting-the-base-path) so Shoelace knows where to load them from. Otherwise, icons may not appear and you'll see 404 Not Found errors in the dev console. diff --git a/docs/components/image-comparer.md b/docs/components/image-comparer.md index a8cf946ef..a0853e4ae 100644 --- a/docs/components/image-comparer.md +++ b/docs/components/image-comparer.md @@ -2,8 +2,6 @@ [component-header:sl-image-comparer] -Compare visual differences between similar photos with a sliding panel. - For best results, use images that share the same dimensions. The slider can be controlled by dragging or pressing the left and right arrow keys. (Tip: press shift + arrows to move the slider in larger intervals, or home + end to jump to the beginning or end.) ```html preview diff --git a/docs/components/include.md b/docs/components/include.md index 86ce4e1a9..3a3805cbe 100644 --- a/docs/components/include.md +++ b/docs/components/include.md @@ -2,8 +2,6 @@ [component-header:sl-include] -Includes give you the power to embed external HTML files into the page. - Included files are asynchronously requested using `window.fetch()`. Requests are cached, so the same file can be included multiple times, but only one request will be made. The included content will be inserted into the `
Switch
```
diff --git a/docs/components/tab-group.md b/docs/components/tab-group.md
index 4380b1ac4..ef4fb8d12 100644
--- a/docs/components/tab-group.md
+++ b/docs/components/tab-group.md
@@ -2,8 +2,6 @@
[component-header:sl-tab-group]
-Tab groups organize content into a container that shows one section at a time.
-
Tab groups make use of [tabs](/components/tab) and [tab panels](/components/tab-panel). Each tab must be slotted into the `nav` slot and its `panel` must refer to a tab panel of the same name.
```html preview
diff --git a/docs/components/tab-panel.md b/docs/components/tab-panel.md
index e89be8ea9..6e495f024 100644
--- a/docs/components/tab-panel.md
+++ b/docs/components/tab-panel.md
@@ -2,8 +2,6 @@
[component-header:sl-tab-panel]
-Tab panels are used inside [tab groups](/components/tab-group) to display tabbed content.
-
```html preview
General
diff --git a/docs/components/tab.md b/docs/components/tab.md
index 2ff680dc3..53c8b37bf 100644
--- a/docs/components/tab.md
+++ b/docs/components/tab.md
@@ -2,8 +2,6 @@
[component-header:sl-tab]
-Tabs are used inside [tab groups](/components/tab-group) to represent and activate [tab panels](/components/tab-panel).
-
```html preview
Tab
Active
diff --git a/docs/components/tag.md b/docs/components/tag.md
index 3df75c8c7..32747c420 100644
--- a/docs/components/tag.md
+++ b/docs/components/tag.md
@@ -2,8 +2,6 @@
[component-header:sl-tag]
-Tags are used as labels to organize things or to indicate a selection.
-
```html preview
Primary
Success
diff --git a/docs/components/textarea.md b/docs/components/textarea.md
index 5b4c80a05..b1a3b6c64 100644
--- a/docs/components/textarea.md
+++ b/docs/components/textarea.md
@@ -2,8 +2,6 @@
[component-header:sl-textarea]
-Textareas collect data from the user and allow multiple lines of text.
-
```html preview
diff --git a/docs/components/tree.md b/docs/components/tree.md
index 2e1b3ecfe..cdc5e459e 100644
--- a/docs/components/tree.md
+++ b/docs/components/tree.md
@@ -2,8 +2,6 @@
[component-header:sl-tree]
-Trees allow you to display a hierarchical list of selectable [tree items](/components/tree-item). Items with children can be expanded and collapsed as desired by the user.
-
```html preview
diff --git a/docs/components/visually-hidden.md b/docs/components/visually-hidden.md
index caf2185cf..80b80b106 100644
--- a/docs/components/visually-hidden.md
+++ b/docs/components/visually-hidden.md
@@ -2,8 +2,6 @@
[component-header:sl-visually-hidden]
-The visually hidden utility makes content accessible to assistive devices without displaying it on the screen.
-
According to [The A11Y Project](https://www.a11yproject.com/posts/2013-01-11-how-to-hide-content/), "there are real world situations where visually hiding content may be appropriate, while the content should remain available to assistive technologies, such as screen readers. For instance, hiding a search field's label as a common magnifying glass icon is used in its stead."
Since visually hidden content can receive focus when tabbing, the element will become visible when something inside receives focus. This behavior is intentional, as sighted keyboards user won't be able to determine where the focus indicator is without it.
diff --git a/src/components/alert/alert.ts b/src/components/alert/alert.ts
index 44bea6d19..16f693558 100644
--- a/src/components/alert/alert.ts
+++ b/src/components/alert/alert.ts
@@ -15,7 +15,6 @@ import type { CSSResultGroup } from 'lit';
const toastStack = Object.assign(document.createElement('div'), { className: 'sl-toast-stack' });
/**
- * @title Alert
* @summary Alerts are used to display important messages inline or as toast notifications.
*
* @since 2.0
diff --git a/src/components/animated-image/animated-image.ts b/src/components/animated-image/animated-image.ts
index 4ef1a47af..f6eb345b3 100644
--- a/src/components/animated-image/animated-image.ts
+++ b/src/components/animated-image/animated-image.ts
@@ -7,6 +7,8 @@ import styles from './animated-image.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary A component for displaying animated GIFs and WEBPs that play and pause on interaction.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/animation/animation.ts b/src/components/animation/animation.ts
index 3f4f677fb..b9f96ccb0 100644
--- a/src/components/animation/animation.ts
+++ b/src/components/animation/animation.ts
@@ -7,6 +7,8 @@ import { animations } from './animations';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Animate elements declaratively with nearly 100 baked-in presets, or roll your own with custom keyframes. Powered by the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/avatar/avatar.ts b/src/components/avatar/avatar.ts
index 56ebb6501..8c07029a1 100644
--- a/src/components/avatar/avatar.ts
+++ b/src/components/avatar/avatar.ts
@@ -8,6 +8,8 @@ import styles from './avatar.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Avatars are used to represent a person or object.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/badge/badge.ts b/src/components/badge/badge.ts
index 3b7d522b2..7eaf97ccc 100644
--- a/src/components/badge/badge.ts
+++ b/src/components/badge/badge.ts
@@ -6,6 +6,8 @@ import styles from './badge.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Badges are used to draw attention and display statuses or counts.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/breadcrumb-item/breadcrumb-item.ts b/src/components/breadcrumb-item/breadcrumb-item.ts
index e009a48ba..aa2f7dfe7 100644
--- a/src/components/breadcrumb-item/breadcrumb-item.ts
+++ b/src/components/breadcrumb-item/breadcrumb-item.ts
@@ -8,6 +8,8 @@ import styles from './breadcrumb-item.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Breadcrumb Items are used inside [breadcrumbs](/components/breadcrumb) to represent different links.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/breadcrumb/breadcrumb.ts b/src/components/breadcrumb/breadcrumb.ts
index 91e92fe29..ad39d9a8c 100644
--- a/src/components/breadcrumb/breadcrumb.ts
+++ b/src/components/breadcrumb/breadcrumb.ts
@@ -8,6 +8,8 @@ import type SlBreadcrumbItem from '../breadcrumb-item/breadcrumb-item';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Breadcrumbs provide a group of links so users can easily navigate a website's hierarchy.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/button-group/button-group.ts b/src/components/button-group/button-group.ts
index 2a9037b19..b40adb58c 100644
--- a/src/components/button-group/button-group.ts
+++ b/src/components/button-group/button-group.ts
@@ -5,6 +5,8 @@ import styles from './button-group.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Button groups can be used to group related buttons into sections.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/button/button.ts b/src/components/button/button.ts
index f35bf53c2..e4d939daa 100644
--- a/src/components/button/button.ts
+++ b/src/components/button/button.ts
@@ -11,6 +11,8 @@ import styles from './button.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Buttons represent actions that are available to the user.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/card/card.ts b/src/components/card/card.ts
index f9b76a326..ee65e4857 100644
--- a/src/components/card/card.ts
+++ b/src/components/card/card.ts
@@ -7,6 +7,8 @@ import styles from './card.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Cards can be used to group related subjects in a container.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/checkbox/checkbox.ts b/src/components/checkbox/checkbox.ts
index a4b850ec3..8ff39e2cc 100644
--- a/src/components/checkbox/checkbox.ts
+++ b/src/components/checkbox/checkbox.ts
@@ -11,6 +11,8 @@ import styles from './checkbox.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Checkboxes allow the user to toggle an option on or off.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/color-picker/color-picker.ts b/src/components/color-picker/color-picker.ts
index 5c61d964c..0da96e6a3 100644
--- a/src/components/color-picker/color-picker.ts
+++ b/src/components/color-picker/color-picker.ts
@@ -36,6 +36,8 @@ interface EyeDropperInterface {
declare const EyeDropper: EyeDropperConstructor;
/**
+ * @summary Color pickers allow the user to select a color.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/details/details.ts b/src/components/details/details.ts
index 22d6fc2ad..08d06370b 100644
--- a/src/components/details/details.ts
+++ b/src/components/details/details.ts
@@ -12,6 +12,8 @@ import styles from './details.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Details show a brief summary and expand to show additional content.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/dialog/dialog.ts b/src/components/dialog/dialog.ts
index a0c45bb44..6d214ba7c 100644
--- a/src/components/dialog/dialog.ts
+++ b/src/components/dialog/dialog.ts
@@ -16,6 +16,8 @@ import styles from './dialog.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Dialogs, sometimes called "modals", appear above the page and require the user's immediate attention.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/divider/divider.ts b/src/components/divider/divider.ts
index e64475dfc..2c85b516e 100644
--- a/src/components/divider/divider.ts
+++ b/src/components/divider/divider.ts
@@ -5,6 +5,8 @@ import styles from './divider.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Dividers are used to visually separate or group elements.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/drawer/drawer.ts b/src/components/drawer/drawer.ts
index c7e0efe26..2666bfe69 100644
--- a/src/components/drawer/drawer.ts
+++ b/src/components/drawer/drawer.ts
@@ -17,6 +17,8 @@ import styles from './drawer.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Drawers slide in from a container to expose additional options and information.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/dropdown/dropdown.ts b/src/components/dropdown/dropdown.ts
index 94c62b23d..aa5c2a400 100644
--- a/src/components/dropdown/dropdown.ts
+++ b/src/components/dropdown/dropdown.ts
@@ -19,6 +19,8 @@ import type SlPopup from '../popup/popup';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Dropdowns expose additional content that "drops down" in a panel.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/format-bytes/format-bytes.ts b/src/components/format-bytes/format-bytes.ts
index 228a841ab..93027db5d 100644
--- a/src/components/format-bytes/format-bytes.ts
+++ b/src/components/format-bytes/format-bytes.ts
@@ -3,7 +3,8 @@ import ShoelaceElement from '../../internal/shoelace-element';
import { LocalizeController } from '../../utilities/localize';
/**
-
+ * @summary Formats a number as a human readable bytes value.
+ *
* @since 2.0
* @status stable
*/
diff --git a/src/components/format-date/format-date.ts b/src/components/format-date/format-date.ts
index 3405af712..a95c4a915 100644
--- a/src/components/format-date/format-date.ts
+++ b/src/components/format-date/format-date.ts
@@ -4,6 +4,8 @@ import ShoelaceElement from '../../internal/shoelace-element';
import { LocalizeController } from '../../utilities/localize';
/**
+ * @summary Formats a date/time using the specified locale and options.
+ *
* @since 2.0
* @status stable
*/
diff --git a/src/components/format-number/format-number.ts b/src/components/format-number/format-number.ts
index 4942fcf5c..7b47608ab 100644
--- a/src/components/format-number/format-number.ts
+++ b/src/components/format-number/format-number.ts
@@ -3,6 +3,8 @@ import ShoelaceElement from '../../internal/shoelace-element';
import { LocalizeController } from '../../utilities/localize';
/**
+ * @summary Formats a number using the specified locale and options.
+ *
* @since 2.0
* @status stable
*/
diff --git a/src/components/icon-button/icon-button.ts b/src/components/icon-button/icon-button.ts
index b9dea30d3..4d563c966 100644
--- a/src/components/icon-button/icon-button.ts
+++ b/src/components/icon-button/icon-button.ts
@@ -8,6 +8,8 @@ import styles from './icon-button.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Icons buttons are simple, icon-only buttons that can be used for actions and in toolbars.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/icon/icon.ts b/src/components/icon/icon.ts
index faca59255..4e36f39fc 100644
--- a/src/components/icon/icon.ts
+++ b/src/components/icon/icon.ts
@@ -12,6 +12,8 @@ import type { CSSResultGroup } from 'lit';
let parser: DOMParser;
/**
+ * @summary Icons are symbols that can be used to represent various options within an application.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/image-comparer/image-comparer.ts b/src/components/image-comparer/image-comparer.ts
index 9a4c3e467..0d03f1a7e 100644
--- a/src/components/image-comparer/image-comparer.ts
+++ b/src/components/image-comparer/image-comparer.ts
@@ -12,6 +12,8 @@ import styles from './image-comparer.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Compare visual differences between similar photos with a sliding panel.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/include/include.ts b/src/components/include/include.ts
index ec3a030a3..5187fe520 100644
--- a/src/components/include/include.ts
+++ b/src/components/include/include.ts
@@ -7,6 +7,8 @@ import { requestInclude } from './request';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Includes give you the power to embed external HTML files into the page.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/input/input.ts b/src/components/input/input.ts
index 3d2941a22..6ad180413 100644
--- a/src/components/input/input.ts
+++ b/src/components/input/input.ts
@@ -25,6 +25,8 @@ const isChromium = navigator.userAgentData?.brands.some(b => b.brand.includes('C
const isFirefox = isChromium ? false : navigator.userAgent.includes('Firefox');
/**
+ * @summary Inputs collect data from the user.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/menu-item/menu-item.ts b/src/components/menu-item/menu-item.ts
index 198bb268a..0403e0a8d 100644
--- a/src/components/menu-item/menu-item.ts
+++ b/src/components/menu-item/menu-item.ts
@@ -9,6 +9,8 @@ import styles from './menu-item.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Menu items provide options for the user to pick from in a menu.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/menu-label/menu-label.ts b/src/components/menu-label/menu-label.ts
index b96fd9119..7efc8c1ef 100644
--- a/src/components/menu-label/menu-label.ts
+++ b/src/components/menu-label/menu-label.ts
@@ -5,6 +5,8 @@ import styles from './menu-label.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Menu labels are used to describe a group of menu items.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/menu/menu.ts b/src/components/menu/menu.ts
index e39b48029..13608414f 100644
--- a/src/components/menu/menu.ts
+++ b/src/components/menu/menu.ts
@@ -10,6 +10,8 @@ export interface MenuSelectEventDetail {
}
/**
+ * @summary Menus provide a list of options for the user to choose from.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/mutation-observer/mutation-observer.ts b/src/components/mutation-observer/mutation-observer.ts
index ca167ce9c..850b89fa1 100644
--- a/src/components/mutation-observer/mutation-observer.ts
+++ b/src/components/mutation-observer/mutation-observer.ts
@@ -6,6 +6,8 @@ import styles from './mutation-observer.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary The Mutation Observer component offers a thin, declarative interface to the [`MutationObserver API`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/popup/popup.ts b/src/components/popup/popup.ts
index f39416a5d..749988eb1 100644
--- a/src/components/popup/popup.ts
+++ b/src/components/popup/popup.ts
@@ -7,6 +7,8 @@ import styles from './popup.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Popup is a utility that lets you declaratively anchor "popup" containers to another element.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/progress-bar/progress-bar.ts b/src/components/progress-bar/progress-bar.ts
index bf8287f85..6115bc77c 100644
--- a/src/components/progress-bar/progress-bar.ts
+++ b/src/components/progress-bar/progress-bar.ts
@@ -9,6 +9,8 @@ import styles from './progress-bar.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Progress bars are used to show the status of an ongoing operation.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/progress-ring/progress-ring.ts b/src/components/progress-ring/progress-ring.ts
index 51281009a..30231ae4e 100644
--- a/src/components/progress-ring/progress-ring.ts
+++ b/src/components/progress-ring/progress-ring.ts
@@ -6,6 +6,8 @@ import styles from './progress-ring.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Progress rings are used to show the progress of a determinate operation in a circular fashion.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/radio-button/radio-button.ts b/src/components/radio-button/radio-button.ts
index c432a72f7..5caae32dd 100644
--- a/src/components/radio-button/radio-button.ts
+++ b/src/components/radio-button/radio-button.ts
@@ -9,6 +9,8 @@ import styles from './radio-button.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Radios buttons allow the user to select a single option from a group using a button-like control.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/radio-group/radio-group.ts b/src/components/radio-group/radio-group.ts
index ac15c67e5..4a9774489 100644
--- a/src/components/radio-group/radio-group.ts
+++ b/src/components/radio-group/radio-group.ts
@@ -11,6 +11,8 @@ import type SlRadio from '../radio/radio';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Radio groups are used to group multiple [radios](/components/radio) or [radio buttons](/components/radio-button) so they function as a single form control.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/radio/radio.ts b/src/components/radio/radio.ts
index 83197804f..66bcb65a5 100644
--- a/src/components/radio/radio.ts
+++ b/src/components/radio/radio.ts
@@ -7,6 +7,8 @@ import styles from './radio.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Radios allow the user to select a single option from a group.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/range/range.ts b/src/components/range/range.ts
index 225373a0f..a5b7daa72 100644
--- a/src/components/range/range.ts
+++ b/src/components/range/range.ts
@@ -13,6 +13,8 @@ import styles from './range.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Ranges allow the user to select a single value within a given range using a slider.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/rating/rating.ts b/src/components/rating/rating.ts
index 647b42c7d..a242a9fc8 100644
--- a/src/components/rating/rating.ts
+++ b/src/components/rating/rating.ts
@@ -12,6 +12,8 @@ import styles from './rating.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Ratings give users a way to quickly view and provide feedback.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/relative-time/relative-time.ts b/src/components/relative-time/relative-time.ts
index ceec129c3..6e960bf57 100644
--- a/src/components/relative-time/relative-time.ts
+++ b/src/components/relative-time/relative-time.ts
@@ -19,6 +19,8 @@ const availableUnits: UnitConfig[] = [
];
/**
+ * @summary Outputs a localized time phrase relative to the current date and time.
+ *
* @since 2.0
* @status stable
*/
diff --git a/src/components/resize-observer/resize-observer.ts b/src/components/resize-observer/resize-observer.ts
index bda9f508f..62122f209 100644
--- a/src/components/resize-observer/resize-observer.ts
+++ b/src/components/resize-observer/resize-observer.ts
@@ -6,6 +6,8 @@ import styles from './resize-observer.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary The Resize Observer component offers a thin, declarative interface to the [`ResizeObserver API`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/select/select.ts b/src/components/select/select.ts
index 1278a90d0..2298b2c4e 100644
--- a/src/components/select/select.ts
+++ b/src/components/select/select.ts
@@ -21,6 +21,8 @@ import type SlMenu from '../menu/menu';
import type { TemplateResult, CSSResultGroup } from 'lit';
/**
+ * @summary Selects allow you to choose one or more items from a dropdown menu.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/skeleton/skeleton.ts b/src/components/skeleton/skeleton.ts
index ae824ee80..a81ca0ea0 100644
--- a/src/components/skeleton/skeleton.ts
+++ b/src/components/skeleton/skeleton.ts
@@ -6,6 +6,8 @@ import styles from './skeleton.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Skeletons are used to show where content will eventually be drawn.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/spinner/spinner.ts b/src/components/spinner/spinner.ts
index e4db070c1..3fb91d832 100644
--- a/src/components/spinner/spinner.ts
+++ b/src/components/spinner/spinner.ts
@@ -6,6 +6,8 @@ import styles from './spinner.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Spinners are used to show the progress of an indeterminate operation.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/split-panel/split-panel.ts b/src/components/split-panel/split-panel.ts
index 184d96262..216aa71a9 100644
--- a/src/components/split-panel/split-panel.ts
+++ b/src/components/split-panel/split-panel.ts
@@ -10,6 +10,8 @@ import styles from './split-panel.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Split panels display two adjacent panels, allowing the user to reposition them.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/switch/switch.ts b/src/components/switch/switch.ts
index 70bd85130..d9844beb8 100644
--- a/src/components/switch/switch.ts
+++ b/src/components/switch/switch.ts
@@ -11,6 +11,8 @@ import styles from './switch.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Switches allow the user to toggle an option on or off.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/tab-group/tab-group.ts b/src/components/tab-group/tab-group.ts
index 4edb63641..da1010b12 100644
--- a/src/components/tab-group/tab-group.ts
+++ b/src/components/tab-group/tab-group.ts
@@ -12,6 +12,8 @@ import type SlTab from '../tab/tab';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Tab groups organize content into a container that shows one section at a time.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/tab-panel/tab-panel.ts b/src/components/tab-panel/tab-panel.ts
index 7158a2210..179720619 100644
--- a/src/components/tab-panel/tab-panel.ts
+++ b/src/components/tab-panel/tab-panel.ts
@@ -8,6 +8,8 @@ import styles from './tab-panel.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Tab panels are used inside [tab groups](/components/tab-group) to display tabbed content.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/tab/tab.ts b/src/components/tab/tab.ts
index e637e9e1a..07c5f1011 100644
--- a/src/components/tab/tab.ts
+++ b/src/components/tab/tab.ts
@@ -10,6 +10,8 @@ import styles from './tab.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Tabs are used inside [tab groups](/components/tab-group) to represent and activate [tab panels](/components/tab-panel).
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/tag/tag.ts b/src/components/tag/tag.ts
index 39cb033aa..7634a43b2 100644
--- a/src/components/tag/tag.ts
+++ b/src/components/tag/tag.ts
@@ -8,6 +8,8 @@ import styles from './tag.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Tags are used as labels to organize things or to indicate a selection.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/textarea/textarea.ts b/src/components/textarea/textarea.ts
index e22a02ac5..d685eec87 100644
--- a/src/components/textarea/textarea.ts
+++ b/src/components/textarea/textarea.ts
@@ -12,6 +12,8 @@ import styles from './textarea.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Textareas collect data from the user and allow multiple lines of text.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/tooltip/tooltip.ts b/src/components/tooltip/tooltip.ts
index 3aef4ae0a..3e73bec94 100644
--- a/src/components/tooltip/tooltip.ts
+++ b/src/components/tooltip/tooltip.ts
@@ -13,6 +13,8 @@ import type SlPopup from '../popup/popup';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary Tooltips display additional information based on a specific action.
+ *
* @since 2.0
* @status stable
*
diff --git a/src/components/tree-item/tree-item.ts b/src/components/tree-item/tree-item.ts
index 8d9f04a37..2396669b4 100644
--- a/src/components/tree-item/tree-item.ts
+++ b/src/components/tree-item/tree-item.ts
@@ -19,6 +19,8 @@ export function isTreeItem(element: Element) {
}
/**
+ * @summary A tree item serves as a hierarchical node that lives inside a [tree](/components/tree).
+ *
* @since 2.0
* @status experimental
*
diff --git a/src/components/tree/tree.ts b/src/components/tree/tree.ts
index 95751d29a..df2f61fac 100644
--- a/src/components/tree/tree.ts
+++ b/src/components/tree/tree.ts
@@ -37,6 +37,8 @@ function syncCheckboxes(changedTreeItem: SlTreeItem) {
}
/**
+ * @summary Trees allow you to display a hierarchical list of selectable [tree items](/components/tree-item). Items with children can be expanded and collapsed as desired by the user.
+ *
* @since 2.0
* @status experimental
*
diff --git a/src/components/visually-hidden/visually-hidden.ts b/src/components/visually-hidden/visually-hidden.ts
index 7cd3337fc..2a83f1d46 100644
--- a/src/components/visually-hidden/visually-hidden.ts
+++ b/src/components/visually-hidden/visually-hidden.ts
@@ -5,6 +5,8 @@ import styles from './visually-hidden.styles';
import type { CSSResultGroup } from 'lit';
/**
+ * @summary The visually hidden utility makes content accessible to assistive devices without displaying it on the screen.
+ *
* @since 2.0
* @status stable
*