Enrich components @summary with description from docs (#962)

* keep header styles with repositioned description text

* `animated-image` move description to component

* code style

* `avatar` add summary from docs

* `badge` add summary from docs

* `breadcrumb` add summary from docs

* `button` add summary from docs

* lead sentence is now part of the header

* `button-group` add summary from docs

* `card` add summary from docs

* `checkbox` add summary from docs

* `color-picker` add summary from docs

* `details` add summary from docs

* `dialog` add summary from docs

* `divider` add summary from docs

* `drawer` add summary from docs

* `dropdown` add summary from docs

* `format-bytes` add summary from docs

* `format-date` add summary from docs

* `format-number` add summary from docs

* `icon` add summary from docs

* `icon-button` add summary from docs

* `image-comparer` add summary from docs

* `include` add summary from docs

* `input` add summary from docs

* `menu` add summary from docs

* `menu-item` add summary from docs

* `menu-label` add summary from docs

* `popup` add summary from docs

* `progressbar` add summary from docs

* `progress-ring` add summary from docs

* `radio` add summary from docs

* `radio-button` add summary from docs

* `range` add summary from docs

* `rating` add summary from docs

* `relative-time` add summary from docs

* `select` add summary from docs

* `skeleton` add summary from docs

* `spinner` add summary from docs

* `split-panel` add summary from docs

* `switch` add summary from docs

* `tab-group` add summary from docs

* `tag` add summary from docs

* `textarea` add summary from docs

* `tooltip` add summary from docs

* `visually-hidden` add summary from docs

* `animation` add summary from docs

* `breadcrumb-item` add summary from docs

* `mutation-observer` add summary from docs

* `radio-group` add summary from docs

* `resize-observer` add summary from docs

* `tab` add summary from docs

* `tab-panel` add summary from docs

* `tree` add summary from docs

* `tree-item` add summary from docs

* remove `title` for further usage of `Sl` classnames in docs

* revert: use markdown parser for component summary

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

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  */

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
  */

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
  */

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  */

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *

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
  *