diff --git a/docs/assets/plugins/metadata/metadata.js b/docs/assets/plugins/metadata/metadata.js index ae33e719c..b5e3e819a 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 1eb601dc1..c553cbbb8 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 4f12320b1..c739f4941 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 dcd45387d..c4ad4de72 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 6c367f307..19ad74b6a 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 308e069c2..486314c50 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 6684b4479..97dad7952 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 17e63b267..936a97775 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 8e9c576ed..d023e1f78 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 652559c7d..ab47547ab 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 5dd90a7d1..92c6b2b5e 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 b9f78d804..9d5fb63ce 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 64b3dfa0a..311551735 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 38803224b..91123edc9 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 5221cc5d2..d11e70228 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 158bbc95f..b075245a3 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 4b7a4ad2d..4e8a1c898 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 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 ``` diff --git a/docs/components/menu-item.md b/docs/components/menu-item.md index 9e21931aa..d0ba4c34c 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 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 ``` diff --git a/docs/components/progress-ring.md b/docs/components/progress-ring.md index 499189afa..ce2a5ef2f 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 388b9aa6f..9a24ec8c0 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 8e1d9864f..446acd4d7 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 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 ``` diff --git a/docs/components/rating.md b/docs/components/rating.md index 48695813c..4a5784cb9 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 3a8e68de3..b3032597f 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 d9ba3e669..8aab67082 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 2796bb25a..4335cfadd 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 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/split-panel.md b/docs/components/split-panel.md index f195a2a82..ff039e029 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 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/tooltip.md b/docs/components/tooltip.md index db5307b12..c5c870e84 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 303b066d4..4553597f0 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 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 *