diff --git a/docs/assets/plugins/metadata/metadata.js b/docs/assets/plugins/metadata/metadata.js index ae33e719..b5e3e819 100644 --- a/docs/assets/plugins/metadata/metadata.js +++ b/docs/assets/plugins/metadata/metadata.js @@ -388,7 +388,7 @@
-

${component.summary}

+

${marked(component.summary)}

`; diff --git a/docs/assets/styles/docs.css b/docs/assets/styles/docs.css index 1eb601dc..c553cbbb 100644 --- a/docs/assets/styles/docs.css +++ b/docs/assets/styles/docs.css @@ -508,10 +508,7 @@ kbd, /* Component headers */ .component-header { - border-bottom: solid 1px var(--sl-color-neutral-200); - padding-bottom: 2rem; margin-top: -1rem; - margin-bottom: 2rem; } .component-header__tag { @@ -520,6 +517,13 @@ kbd, margin: 0.75rem 0 0.25rem 0; } +.component-header__summary { + font-size: var(--sl-font-size-large); + line-height: 1.6; + border-top: solid 1px var(--sl-color-neutral-200); + margin-top: 2rem; +} + .markdown-section .component-header__tag code { background: none; color: var(--sl-color-neutral-600); @@ -532,13 +536,6 @@ kbd, margin-bottom: 0.5rem; } -/* Lead sentences that occur immediately after the header */ -.component-header + p, -.component-header p { - font-size: var(--sl-font-size-large); - line-height: 1.6; -} - /* Repo buttons */ .repo-button--sponsor sl-icon { color: var(--sl-color-pink-600); diff --git a/docs/components/animated-image.md b/docs/components/animated-image.md index 4f12320b..c739f494 100644 --- a/docs/components/animated-image.md +++ b/docs/components/animated-image.md @@ -2,8 +2,6 @@ [component-header:sl-animated-image] -A component for displaying animated GIFs and WEBPs that play and pause on interaction. - ```html preview ` and set an animation `name`. The animation will not start until you add the `play` attribute. Refer to the [properties table](#properties) for a list of all animation options. ```html preview diff --git a/docs/components/avatar.md b/docs/components/avatar.md index dcd45387..c4ad4de7 100644 --- a/docs/components/avatar.md +++ b/docs/components/avatar.md @@ -2,8 +2,6 @@ [component-header:sl-avatar] -Avatars are used to represent a person or object. - By default, a generic icon will be shown. You can personalize avatars by adding custom icons, initials, and images. You should always provide a `label` for assistive devices. ```html preview diff --git a/docs/components/badge.md b/docs/components/badge.md index 6c367f30..19ad74b6 100644 --- a/docs/components/badge.md +++ b/docs/components/badge.md @@ -2,8 +2,6 @@ [component-header:sl-badge] -Badges are used to draw attention and display statuses or counts. - ```html preview Badge ``` diff --git a/docs/components/breadcrumb-item.md b/docs/components/breadcrumb-item.md index 308e069c..486314c5 100644 --- a/docs/components/breadcrumb-item.md +++ b/docs/components/breadcrumb-item.md @@ -2,8 +2,6 @@ [component-header:sl-breadcrumb-item] -Breadcrumb Items are used inside [breadcrumbs](/components/breadcrumb) to represent different links. - ```html preview diff --git a/docs/components/breadcrumb.md b/docs/components/breadcrumb.md index 6684b447..97dad795 100644 --- a/docs/components/breadcrumb.md +++ b/docs/components/breadcrumb.md @@ -2,8 +2,6 @@ [component-header:sl-breadcrumb] -Breadcrumbs provide a group of links so users can easily navigate a website's hierarchy. - Breadcrumbs are usually placed before a page's main content with the current page shown last to indicate the user's position in the navigation. ```html preview diff --git a/docs/components/button-group.md b/docs/components/button-group.md index 17e63b26..936a9777 100644 --- a/docs/components/button-group.md +++ b/docs/components/button-group.md @@ -2,8 +2,6 @@ [component-header:sl-button-group] -Button groups can be used to group related buttons into sections. - ```html preview Left diff --git a/docs/components/button.md b/docs/components/button.md index 8e9c576e..d023e1f7 100644 --- a/docs/components/button.md +++ b/docs/components/button.md @@ -2,8 +2,6 @@ [component-header:sl-button] -Buttons represent actions that are available to the user. - ```html preview Button ``` diff --git a/docs/components/card.md b/docs/components/card.md index 652559c7..ab47547a 100644 --- a/docs/components/card.md +++ b/docs/components/card.md @@ -2,8 +2,6 @@ [component-header:sl-card] -Cards can be used to group related subjects in a container. - ```html preview Checkbox ``` diff --git a/docs/components/color-picker.md b/docs/components/color-picker.md index 5dd90a7d..92c6b2b5 100644 --- a/docs/components/color-picker.md +++ b/docs/components/color-picker.md @@ -2,8 +2,6 @@ [component-header:sl-color-picker] -Color pickers allow the user to select a color. - ```html preview ``` diff --git a/docs/components/details.md b/docs/components/details.md index b9f78d80..9d5fb63c 100644 --- a/docs/components/details.md +++ b/docs/components/details.md @@ -4,8 +4,6 @@ [component-header:sl-details] -Details show a brief summary and expand to show additional content. - ```html preview Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna diff --git a/docs/components/dialog.md b/docs/components/dialog.md index 64b3dfa0..31155173 100644 --- a/docs/components/dialog.md +++ b/docs/components/dialog.md @@ -4,8 +4,6 @@ [component-header:sl-dialog] -Dialogs, sometimes called "modals", appear above the page and require the user's immediate attention. - ```html preview Lorem ipsum dolor sit amet, consectetur adipiscing elit. diff --git a/docs/components/divider.md b/docs/components/divider.md index 38803224..91123edc 100644 --- a/docs/components/divider.md +++ b/docs/components/divider.md @@ -2,8 +2,6 @@ [component-header:sl-divider] -Dividers are used to visually separate or group elements. - ```html preview ``` diff --git a/docs/components/drawer.md b/docs/components/drawer.md index 5221cc5d..d11e7022 100644 --- a/docs/components/drawer.md +++ b/docs/components/drawer.md @@ -4,8 +4,6 @@ [component-header:sl-drawer] -Drawers slide in from a container to expose additional options and information. - ```html preview Lorem ipsum dolor sit amet, consectetur adipiscing elit. diff --git a/docs/components/dropdown.md b/docs/components/dropdown.md index 158bbc95..b075245a 100644 --- a/docs/components/dropdown.md +++ b/docs/components/dropdown.md @@ -2,8 +2,6 @@ [component-header:sl-dropdown] -Dropdowns expose additional content that "drops down" in a panel. - Dropdowns consist of a trigger and a panel. By default, activating the trigger will expose the panel and interacting outside of the panel will close it. Dropdowns are designed to work well with [menus](/components/menu) to provide a list of options the user can select from. However, dropdowns can also be used in lower-level applications (e.g. [color picker](/components/color-picker) and [select](/components/select)). The API gives you complete control over showing, hiding, and positioning the panel. diff --git a/docs/components/format-bytes.md b/docs/components/format-bytes.md index 4b7a4ad2..4e8a1c89 100644 --- a/docs/components/format-bytes.md +++ b/docs/components/format-bytes.md @@ -2,8 +2,6 @@ [component-header:sl-format-bytes] -Formats a number as a human readable bytes value. - ```html preview
The file is in size.

diff --git a/docs/components/format-date.md b/docs/components/format-date.md index 1e8a2202..ccd58b16 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 77cb9cbc..67ae60e8 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 f2922eed..a95557f3 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 6b646107..72e084bb 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 a8cf946e..a0853e4a 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 86ce4e1a..3a3805cb 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 3df755b9..388f86f8 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 ``` diff --git a/docs/components/menu-item.md b/docs/components/menu-item.md index 9e21931a..d0ba4c34 100644 --- a/docs/components/menu-item.md +++ b/docs/components/menu-item.md @@ -2,8 +2,6 @@ [component-header:sl-menu-item] -Menu items provide options for the user to pick from in a menu. - ```html preview Option 1 diff --git a/docs/components/menu-label.md b/docs/components/menu-label.md index b8b1647a..c606eb5b 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 d2321864..270071af 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 0918a9f2..dd669aaa 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 373b4beb..5122dac1 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 b8732a82..4aabd3c3 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 ``` diff --git a/docs/components/progress-ring.md b/docs/components/progress-ring.md index 499189af..ce2a5ef2 100644 --- a/docs/components/progress-ring.md +++ b/docs/components/progress-ring.md @@ -2,8 +2,6 @@ [component-header:sl-progress-ring] -Progress rings are used to show the progress of a determinate operation in a circular fashion. - ```html preview ``` diff --git a/docs/components/radio-button.md b/docs/components/radio-button.md index 388b9aa6..9a24ec8c 100644 --- a/docs/components/radio-button.md +++ b/docs/components/radio-button.md @@ -2,8 +2,6 @@ [component-header:sl-radio-button] -Radios buttons allow the user to select a single option from a group using a button-like control. - Radio buttons are designed to be used with [radio groups](/components/radio-group). When a radio button has focus, the arrow keys can be used to change the selected option just like standard radio controls. ```html preview diff --git a/docs/components/radio-group.md b/docs/components/radio-group.md index 8e1d9864..446acd4d 100644 --- a/docs/components/radio-group.md +++ b/docs/components/radio-group.md @@ -2,8 +2,6 @@ [component-header:sl-radio-group] -Radio groups are used to group multiple [radios](/components/radio) or [radio buttons](/components/radio-button) so they function as a single form control. - ```html preview Option 1 diff --git a/docs/components/radio.md b/docs/components/radio.md index cd40541c..58aa5e39 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 ad106f3c..2c72a6c0 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 ``` diff --git a/docs/components/rating.md b/docs/components/rating.md index 48695813..4a5784cb 100644 --- a/docs/components/rating.md +++ b/docs/components/rating.md @@ -2,8 +2,6 @@ [component-header:sl-rating] -Ratings give users a way to quickly view and provide feedback. - ```html preview ``` diff --git a/docs/components/relative-time.md b/docs/components/relative-time.md index 3a8e68de..b3032597 100644 --- a/docs/components/relative-time.md +++ b/docs/components/relative-time.md @@ -2,8 +2,6 @@ [component-header:sl-relative-time] -Outputs a localized time phrase relative to the current date and time. - Localization is handled by the browser's [`Intl.RelativeTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat). No language packs are required. ```html preview diff --git a/docs/components/resize-observer.md b/docs/components/resize-observer.md index d9ba3e66..8aab6708 100644 --- a/docs/components/resize-observer.md +++ b/docs/components/resize-observer.md @@ -2,8 +2,6 @@ [component-header:sl-resize-observer] -The Resize Observer component offers a thin, declarative interface to the [`ResizeObserver API`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver). - The resize observer will report changes to the dimensions of the elements it wraps through the `sl-resize` event. When emitted, a collection of [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects will be attached to `event.detail` that contains the target element and information about its dimensions. ```html preview diff --git a/docs/components/select.md b/docs/components/select.md index 2796bb25..4335cfad 100644 --- a/docs/components/select.md +++ b/docs/components/select.md @@ -2,8 +2,6 @@ [component-header:sl-select] -Selects allow you to choose one or more items from a dropdown menu. - ```html preview Option 1 diff --git a/docs/components/skeleton.md b/docs/components/skeleton.md index 014f5908..b72043aa 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 56fbb045..38ef26b7 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/split-panel.md b/docs/components/split-panel.md index f195a2a8..ff039e02 100644 --- a/docs/components/split-panel.md +++ b/docs/components/split-panel.md @@ -2,8 +2,6 @@ [component-header:sl-split-panel] -Split panels display two adjacent panels, allowing the user to reposition them. - ```html preview
Switch ``` diff --git a/docs/components/tab-group.md b/docs/components/tab-group.md index 4380b1ac..ef4fb8d1 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 e89be8ea..6e495f02 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 2ff680dc..53c8b37b 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 3df75c8c..32747c42 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 5b4c80a0..b1a3b6c6 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/tooltip.md b/docs/components/tooltip.md index db5307b1..c5c870e8 100644 --- a/docs/components/tooltip.md +++ b/docs/components/tooltip.md @@ -2,8 +2,6 @@ [component-header:sl-tooltip] -Tooltips display additional information based on a specific action. - A tooltip's target is its _first child element_, so you should only wrap one element inside of the tooltip. If you need the tooltip to show up for multiple elements, nest them inside a container first. Tooltips use `display: contents` so they won't interfere with how elements are positioned in a flex or grid layout. diff --git a/docs/components/tree-item.md b/docs/components/tree-item.md index 303b066d..4553597f 100644 --- a/docs/components/tree-item.md +++ b/docs/components/tree-item.md @@ -2,8 +2,6 @@ [component-header:sl-tree-item] -A tree item serves as a hierarchical node that lives inside a [tree](/components/tree). - ```html preview diff --git a/docs/components/tree.md b/docs/components/tree.md index 2e1b3ecf..cdc5e459 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 caf2185c..80b80b10 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 44bea6d1..16f69355 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 4ef1a47a..f6eb345b 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 3f4f677f..b9f96ccb 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 56ebb650..8c07029a 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 3b7d522b..7eaf97cc 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 e009a48b..aa2f7dfe 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 91e92fe2..ad39d9a8 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 2a9037b1..b40adb58 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 f35bf53c..e4d939da 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 f9b76a32..ee65e485 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 a4b850ec..8ff39e2c 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 5c61d964..0da96e6a 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 22d6fc2a..08d06370 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 a0c45bb4..6d214ba7 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 e64475df..2c85b516 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 c7e0efe2..2666bfe6 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 94c62b23..aa5c2a40 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 228a841a..93027db5 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 3405af71..a95c4a91 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 4942fcf5..7b47608a 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 b9dea30d..4d563c96 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 faca5925..4e36f39f 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 9a4c3e46..0d03f1a7 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 ec3a030a..5187fe52 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 3d2941a2..6ad18041 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 198bb268..0403e0a8 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 b96fd911..7efc8c1e 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 e39b4802..13608414 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 ca167ce9..850b89fa 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 f39416a5..749988eb 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 bf8287f8..6115bc77 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 51281009..30231ae4 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 c432a72f..5caae32d 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 ac15c67e..4a977448 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 83197804..66bcb65a 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 225373a0..a5b7daa7 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 647b42c7..a242a9fc 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 ceec129c..6e960bf5 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 bda9f508..62122f20 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 1278a90d..2298b2c4 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 ae824ee8..a81ca0ea 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 e4db070c..3fb91d83 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 184d9626..216aa71a 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 70bd8513..d9844beb 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 4edb6364..da1010b1 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 7158a221..17972061 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 e637e9e1..07c5f101 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 39cb033a..7634a43b 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 e22a02ac..d685eec8 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 3aef4ae0..3e73bec9 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 8d9f04a3..2396669b 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 95751d29..df2f61fa 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 7cd3337f..2a83f1d4 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 *