2.2.0

* fixed clipped calendar toggle in firefox

* changelog

---------

Co-authored-by: Cory LaViska <cory@abeautifulsite.net>

.editorconfig

@@ -1,4 +1,4 @@
-# http://editorconfig.org
+# https://editorconfig.org
 
 root = true
 

.eslintrc.cjs

@@ -1,7 +1,16 @@
 /* eslint-env node */
 
 module.exports = {
-  plugins: ['@typescript-eslint', 'wc', 'lit', 'lit-a11y', 'chai-expect', 'chai-friendly', 'import'],
+  plugins: [
+    '@typescript-eslint',
+    'wc',
+    'lit',
+    'lit-a11y',
+    'chai-expect',
+    'chai-friendly',
+    'import',
+    'sort-imports-es6-autofix'
+  ],
   extends: [
     'eslint:recommended',
     'plugin:wc/recommended',
@@ -13,7 +22,6 @@ module.exports = {
     es2021: true,
     browser: true
   },
-  reportUnusedDisableDirectives: true,
   parserOptions: {
     sourceType: 'module'
   },
@@ -105,6 +113,7 @@ module.exports = {
     curly: 'off',
     'default-param-last': 'error',
     eqeqeq: 'error',
+    'lit-a11y/click-events-have-key-events': 'off',
     'no-constructor-return': 'error',
     'no-empty-function': 'warn',
     'no-eval': 'error',
@@ -149,8 +158,8 @@ module.exports = {
     'prefer-object-spread': 'warn',
     'prefer-rest-params': 'warn',
     'prefer-spread': 'warn',
-    'prefer-template': 'warn',
-    'no-else-return': 'warn',
+    'prefer-template': 'off',
+    'no-else-return': 'off',
     'func-names': ['warn', 'never'],
     'one-var': ['warn', 'never'],
     'operator-assignment': 'warn',
@@ -171,22 +180,12 @@ module.exports = {
       }
     ],
     'import/no-duplicates': 'warn',
-    'import/order': [
-      'warn',
+    'sort-imports-es6-autofix/sort-imports-es6': [
+      2,
       {
-        groups: ['builtin', 'external', 'internal', 'unknown', 'parent', 'sibling', 'index', 'object', 'type'],
-        pathGroups: [
-          {
-            pattern: 'dist/**',
-            group: 'external'
-          }
-        ],
-        alphabetize: {
-          order: 'asc',
-          caseInsensitive: true
-        },
-        'newlines-between': 'never',
-        warnOnUnassignedImports: true
+        ignoreCase: true,
+        ignoreMemberSort: false,
+        memberSyntaxSortOrder: ['none', 'all', 'multiple', 'single']
       }
     ],
     'wc/guard-super-call': 'off'

.github/workflows/node.js.yml

@@ -15,13 +15,13 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x, 16.x]
+        node-version: [18.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'

.gitignore

@@ -3,6 +3,5 @@
 docs/dist
 docs/search.json
 dist
-examples
 node_modules
 src/react

cspell.json

@@ -8,9 +8,12 @@
     "apos",
     "atrule",
     "autocorrect",
+    "autofix",
     "autoplay",
     "bezier",
     "boxicons",
+    "callout",
+    "callouts",
     "chatbubble",
     "checkmark",
     "claviska",
@@ -18,11 +21,13 @@
     "codebases",
     "codepen",
     "colocated",
+    "colour",
     "combobox",
     "Composability",
     "Consolas",
     "contenteditable",
     "copydir",
+    "Cotte",
     "coverpage",
     "crossorigin",
     "crutchcorn",
@@ -36,17 +41,20 @@
     "enterkeyhint",
     "eqeqeq",
     "erroneou",
+    "errormessage",
     "esbuild",
     "exportparts",
     "fieldsets",
     "formaction",
     "formdata",
+    "formenctype",
     "formmethod",
     "formnovalidate",
     "formtarget",
     "FOUC",
     "FOUCE",
     "fullscreen",
+    "gestern",
     "giga",
     "globby",
     "Grayscale",
@@ -64,19 +72,25 @@
     "jsonata",
     "keydown",
     "keyframes",
+    "Kool",
     "labelledby",
     "Laravel",
     "LaViska",
     "listbox",
+    "listitem",
     "litelement",
     "lowercasing",
     "Lucide",
     "maxlength",
     "Menlo",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "middlewares",
     "minlength",
     "monospace",
     "mousedown",
     "mouseup",
+    "multiselectable",
     "nextjs",
     "nocheck",
     "noopener",
@@ -96,9 +110,13 @@
     "rgba",
     "roadmap",
     "Roboto",
+    "roledescription",
+    "Sapan",
     "saturationl",
     "Schilp",
     "scrollbars",
+    "scrollend",
+    "scroller",
     "Segoe",
     "semibold",
     "slotchange",
@@ -111,11 +129,15 @@
     "tabpanel",
     "templating",
     "tera",
+    "testid",
     "textareas",
     "textfield",
+    "tinycolor",
     "transitionend",
+    "treeitem",
     "Triaging",
     "turbolinks",
+    "typeof",
     "unbundles",
     "unbundling",
     "unicons",
@@ -130,6 +152,7 @@
   "ignorePaths": [
     "package.json",
     "package-lock.json",
+    "docs/assets/examples/include.html",
     ".vscode/**",
     "src/translations/!(en).ts",
     "**/*.min.js"

custom-elements-manifest.config.js

@@ -1,11 +1,29 @@
-import fs from 'fs';
+import { generateCustomData } from 'cem-plugin-vs-code-custom-data-generator';
 import { parse } from 'comment-parser';
 import { pascalCase } from 'pascal-case';
+import commandLineArgs from 'command-line-args';
+import fs from 'fs';
 
 const packageData = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
 const { name, description, version, author, homepage, license } = packageData;
-// eslint-disable-next-line func-style
-const noDash = string => string.replace(/^\s?-/, '').trim();
+
+const { outdir } = commandLineArgs([
+  { name: 'litelement', type: String },
+  { name: 'analyze', defaultOption: true },
+  { name: 'outdir', type: String }
+]);
+
+function noDash(string) {
+  return string.replace(/^\s?-/, '').trim();
+}
+
+function replace(string, terms) {
+  terms.forEach(({ from, to }) => {
+    string = string?.replace(from, to);
+  });
+
+  return string;
+}
 
 export default {
   globs: ['src/components/**/*.ts'],
@@ -27,7 +45,7 @@ export default {
           case ts.SyntaxKind.ClassDeclaration: {
             const className = node.name.getText();
             const classDoc = moduleDoc?.declarations?.find(declaration => declaration.name === className);
-            const customTags = ['animation', 'dependency', 'since', 'status'];
+            const customTags = ['animation', 'dependency', 'documentation', 'since', 'status', 'title'];
             let customComments = '/**';
 
             node.jsDoc?.forEach(jsDoc => {
@@ -63,8 +81,10 @@ export default {
                   break;
 
                 // Value-only metadata tags
+                case 'documentation':
                 case 'since':
                 case 'status':
+                case 'title':
                   classDoc[t.tag] = t.name;
                   break;
 
@@ -85,7 +105,6 @@ export default {
         }
       }
     },
-
     {
       name: 'shoelace-react-event-names',
       analyzePhase({ ts, node, moduleDoc }) {
@@ -102,6 +121,47 @@ export default {
           }
         }
       }
-    }
+    },
+    {
+      name: 'shoelace-translate-module-paths',
+      packageLinkPhase({ customElementsManifest }) {
+        customElementsManifest?.modules?.forEach(mod => {
+          //
+          // CEM paths look like this:
+          //
+          //  src/components/button/button.ts
+          //
+          // But we want them to look like this:
+          //
+          //  components/button/button.js
+          //
+          const terms = [
+            { from: /^src\//, to: '' }, // Strip the src/ prefix
+            { from: /\.(t|j)sx?$/, to: '.js' } // Convert .ts to .js
+          ];
+
+          mod.path = replace(mod.path, terms);
+
+          for (const ex of mod.exports ?? []) {
+            ex.declaration.module = replace(ex.declaration.module, terms);
+          }
+
+          for (const dec of mod.declarations ?? []) {
+            if (dec.kind === 'class') {
+              for (const member of dec.members ?? []) {
+                if (member.inheritedFrom) {
+                  member.inheritedFrom.module = replace(member.inheritedFrom.module, terms);
+                }
+              }
+            }
+          }
+        });
+      }
+    },
+    // Generate custom VS Code data
+    generateCustomData({
+      outdir,
+      cssFileName: null
+    })
   ]
 };

docs/_sidebar.md

@@ -31,6 +31,8 @@
   - [Button](/components/button)
   - [Button Group](/components/button-group)
   - [Card](/components/card)
+  - [Carousel](/components/carousel)
+  - [Carousel Item](/components/carousel-item)
   - [Checkbox](/components/checkbox)
   - [Color Picker](/components/color-picker)
   - [Details](/components/details)
@@ -45,6 +47,7 @@
   - [Menu](/components/menu)
   - [Menu Item](/components/menu-item)
   - [Menu Label](/components/menu-label)
+  - [Option](/components/option)
   - [Progress Bar](/components/progress-bar)
   - [Progress Ring](/components/progress-ring)
   - [QR Code](/components/qr-code)
@@ -64,6 +67,8 @@
   - [Tag](/components/tag)
   - [Textarea](/components/textarea)
   - [Tooltip](/components/tooltip)
+  - [Tree](/components/tree)
+  - [Tree Item](/components/tree-item)
   <!--plop:component-->
 
 - Utilities
@@ -75,9 +80,9 @@
   - [Format Number](/components/format-number)
   - [Include](/components/include)
   - [Mutation Observer](/components/mutation-observer)
+  - [Popup](/components/popup)
   - [Relative Time](/components/relative-time)
   - [Resize Observer](/components/resize-observer)
-  - [Responsive Media](/components/responsive-media)
   - [Visually Hidden](/components/visually-hidden)
 
 - Design Tokens
@@ -89,6 +94,7 @@
   - [Border Radius](/tokens/border-radius)
   - [Transition](/tokens/transition)
   - [Z-index](/tokens/z-index)
+  - [More](/tokens/more)
 
 - Tutorials
 

docs/assets/plugins/code-block/code-block.js

@@ -146,8 +146,6 @@
               </div>
 
               <div class="code-block__buttons">
-                ${hasReact ? ` ${htmlButton} ${reactButton} ` : ''}
-
                 <button
                   type="button"
                   class="code-block__button code-block__toggle"
@@ -167,6 +165,8 @@
                   </svg>
                 </button>
 
+                ${hasReact ? ` ${htmlButton} ${reactButton} ` : ''}
+
                 ${!code.classList.contains('no-codepen') ? codePenButton : ''}
               </div>
             </div>
@@ -232,36 +232,45 @@
 
   // Toggle source mode
   document.addEventListener('click', event => {
-    const button = event.target.closest('button');
+    const button = event.target.closest('.code-block__button');
+    const codeBlock = button?.closest('.code-block');
 
     if (button?.classList.contains('code-block__button--html')) {
+      // Show HTML
       setFlavor('html');
+      toggleSource(codeBlock, true);
     } else if (button?.classList.contains('code-block__button--react')) {
+      // Show React
       setFlavor('react');
+      toggleSource(codeBlock, true);
+    } else if (button?.classList.contains('code-block__toggle')) {
+      // Toggle source
+      toggleSource(codeBlock);
     } else {
       return;
     }
 
     // Update flavor buttons
-    [...document.querySelectorAll('.code-block')].forEach(codeBlock => {
-      codeBlock
-        .querySelector('.code-block__button--html')
-        ?.classList.toggle('code-block__button--selected', flavor === 'html');
-      codeBlock
-        .querySelector('.code-block__button--react')
-        ?.classList.toggle('code-block__button--selected', flavor === 'react');
+    [...document.querySelectorAll('.code-block')].forEach(cb => {
+      cb.querySelector('.code-block__button--html')?.classList.toggle(
+        'code-block__button--selected',
+        flavor === 'html'
+      );
+      cb.querySelector('.code-block__button--react')?.classList.toggle(
+        'code-block__button--selected',
+        flavor === 'react'
+      );
     });
   });
 
-  // Expand and collapse code blocks
-  document.addEventListener('click', event => {
-    const toggle = event.target.closest('.code-block__toggle');
+  function toggleSource(codeBlock, force) {
+    const toggle = codeBlock.querySelector('.code-block__toggle');
+
     if (toggle) {
-      const codeBlock = event.target.closest('.code-block');
-      codeBlock.classList.toggle('code-block--expanded');
+      codeBlock.classList.toggle('code-block--expanded', force === undefined ? undefined : force);
       event.target.setAttribute('aria-expanded', codeBlock.classList.contains('code-block--expanded'));
     }
-  });
+  }
 
   // Show pulse when copying
   document.addEventListener('click', event => {

docs/assets/plugins/metadata/metadata.js

@@ -49,7 +49,7 @@
                   ${escapeHtml(prop.description)}
                 </td>
                 <td style="text-align: center;">${
-                  prop.reflects ? '<sl-icon label="yes" name="check"></sl-icon>' : ''
+                  prop.reflects ? '<sl-icon label="yes" name="check-lg"></sl-icon>' : ''
                 }</td>
                 <td>${prop.type?.text ? `<code>${escapeHtml(prop.type?.text || '')}</code>` : '-'}</td>
                 <td>${prop.default ? `<code>${escapeHtml(prop.default)}</code>` : '-'}</td>
@@ -57,7 +57,18 @@
             `;
           })
           .join('')}
-      </tbody>
+
+          <tr>
+            <td class="nowrap"><code>updateComplete</code></td>
+            <td>
+              A read-only promise that resolves when the component has
+              <a href="/getting-started/usage?id=component-rendering-and-updating">finished updating</a>.
+            </td>
+            <td></td>
+            <td></td>
+            <td></td>
+          </tr>
+        </tbody>
     `;
 
     return table.outerHTML;
@@ -110,14 +121,14 @@
           .map(
             method => `
               <tr>
-                <td class="nowrap"><code>${escapeHtml(method.name)}</code></td>
+                <td class="nowrap"><code>${escapeHtml(method.name)}()</code></td>
                 <td>${escapeHtml(method.description)}</td>
                 <td>
                   ${
                     method.parameters?.length
                       ? `
                         <code>${escapeHtml(
-                          method.parameters.map(param => `${param.name}: ${param.type.text}`).join(', ')
+                          method.parameters.map(param => `${param.name}: ${param.type?.text || ''}`).join(', ')
                         )}</code>
                       `
                       : '-'
@@ -283,6 +294,7 @@
       .replace(/>/g, '&gt;')
       .replace(/"/g, '&quot;')
       .replace(/'/g, '&apos;')
+      .replace(/\[(.*?)\]\((.*?)\)/g, '<a href="$2" rel="noopener noreferrer" target="_blank">$1</a>')
       .replace(/`(.*?)`/g, '<code>$1</code>');
   }
 
@@ -374,7 +386,7 @@
         result += `
           <div class="component-header">
             <div class="component-header__tag">
-              <code>&lt;${component.tagName}&gt; | ${component.name}</code>
+              <code>&lt;${component.tagName}&gt; | ${component.title ?? component.name}</code>
             </div>
 
             <div class="component-header__info">
@@ -386,6 +398,10 @@
                 ${component.status}
               </sl-badge>
             </div>
+
+            <div class="component-header__summary">
+              ${component.summary ? `<p>${marked(component.summary)}</p>` : ''}
+            </div>
           </div>
         `;
 
@@ -430,7 +446,7 @@
             To import this component from [the CDN](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace) using a script tag:
 
             \`\`\`html
-            <script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${metadata.package.version}/${component.path}"></script>
+            <script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${metadata.package.version}/dist/${component.path}"></script>
             \`\`\`
             </sl-tab-panel>
 
@@ -438,14 +454,14 @@
             To import this component from [the CDN](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace) using a JavaScript import:
 
             \`\`\`js
-            import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${metadata.package.version}/${component.path}';
+            import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${metadata.package.version}/dist/${component.path}';
             \`\`\`
             </sl-tab-panel>
 
             <sl-tab-panel name="bundler">\n
             To import this component using [a bundler](/getting-started/installation#bundling):
             \`\`\`js
-            import '@shoelace-style/shoelace/${component.path}';
+            import '@shoelace-style/shoelace/dist/${component.path}';
             \`\`\`
             </sl-tab-panel>
 
@@ -460,7 +476,7 @@
             <div class="sponsor-callout">
               <p>
                 Shoelace is designed, developed, and maintained by <a href="https://twitter.com/claviska" target="_blank">Cory LaViska</a>.
-                Please sponsor my work on GitHub! Your support will keep this project alive and growing!
+                Please sponsor my open source work on GitHub. Your support will keep this project alive and growing!
               </p>
 
               <p>
@@ -480,12 +496,21 @@
           `;
         }
 
+        if (component.slots?.length) {
+          result += `
+            ## Slots
+            ${createSlotsTable(component.slots)}
+
+            _Learn more about [using slots](/getting-started/usage#slots)._
+          `;
+        }
+
         if (props?.length) {
           result += `
-            ## Properties
+            ## Attributes & Properties
             ${createPropsTable(props)}
 
-            _Learn more about [properties and attributes](/getting-started/usage#properties)._
+            _Learn more about [attributes and properties](/getting-started/usage#properties)._
           `;
         }
 
@@ -508,15 +533,6 @@
           `;
         }
 
-        if (component.slots?.length) {
-          result += `
-            ## Slots
-            ${createSlotsTable(component.slots)}
-
-            _Learn more about [using slots](/getting-started/usage#slots)._
-          `;
-        }
-
         if (component.cssProperties?.length) {
           result += `
             ## CSS Custom Properties
@@ -548,7 +564,7 @@
           result += `
             ## Dependencies
 
-            This component imports the following dependencies.
+            This component automatically imports the following dependencies.
 
             ${createDependenciesList(component.tagName, getAllComponents(metadata))}
           `;

docs/assets/plugins/search/search.css

@@ -178,3 +178,15 @@ body.site-search-visible {
     display: none;
   }
 }
+
+/* Forced colors mode */
+@media (forced-colors: active) {
+  .site-search__panel {
+    border: solid 1px var(--sl-color-neutral-0);
+  }
+
+  .site-search__results li[aria-selected='true'] a {
+    outline: dashed 1px SelectedItem;
+    outline-offset: -1px;
+  }
+}

docs/assets/plugins/search/search.js

@@ -11,12 +11,7 @@
       const searchBox = document.createElement('div');
       searchBox.classList.add('search-box');
       searchBox.innerHTML = `
-        <sl-input
-          type="search"
-          placeholder="Search"
-          clearable
-          pill
-        >
+        <sl-input type="search" placeholder="Search" pill>
           <sl-icon slot="prefix" name="search"></sl-icon>
           <kbd slot="suffix" title="Press / to search">/</kbd>
         </sl-input>
@@ -300,9 +295,12 @@
 
     // Show the search panel slash is pressed outside of a form element
     document.addEventListener('keydown', event => {
+      const isSlash = event.key === '/';
+      const isCtrlK = (event.metaKey || event.ctrlKey) && event.key === 'k';
+
       if (
         !isShowing &&
-        event.key === '/' &&
+        (isSlash || isCtrlK) &&
         !event.composedPath().some(el => ['input', 'textarea'].includes(el?.tagName?.toLowerCase()))
       ) {
         event.preventDefault();

docs/assets/plugins/theme-picker/theme-picker.js

@@ -47,10 +47,10 @@
         </sl-button>
         <sl-menu>
           <sl-menu-label>Toggle <kbd>\\</kbd></sl-menu-label>
-          <sl-menu-item value="light">Light</sl-menu-item>
-          <sl-menu-item value="dark">Dark</sl-menu-item>
+          <sl-menu-item type="checkbox" value="light">Light</sl-menu-item>
+          <sl-menu-item type="checkbox" value="dark">Dark</sl-menu-item>
           <sl-divider></sl-divider>
-          <sl-menu-item value="auto">Auto</sl-menu-item>
+          <sl-menu-item type="checkbox" value="auto">Auto</sl-menu-item>
         </sl-menu>
       `;
       document.querySelector('.sidebar-toggle').insertAdjacentElement('afterend', dropdown);

docs/assets/styles/docs.css

@@ -50,6 +50,8 @@ strong {
 }
 
 .sidebar-buttons {
+  display: flex;
+  justify-content: space-between;
   text-align: center;
   margin-top: 0;
 }
@@ -488,6 +490,7 @@ kbd,
 .markdown-section p.tip code,
 .markdown-section p.warn code {
   background-color: var(--sl-color-neutral-100);
+  white-space: nowrap;
 }
 
 /* Sponsorship callouts */
@@ -506,10 +509,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 {
@@ -518,6 +518,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);
@@ -530,12 +537,6 @@ kbd,
   margin-bottom: 0.5rem;
 }
 
-/* Lead sentences that occur immediately after the header */
-.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);

docs/components/alert.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-alert]
 
-Alerts are used to display important messages inline or as toast notifications.
-
 ```html preview
 <sl-alert open>
   <sl-icon slot="icon" name="info-circle"></sl-icon>

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
 <sl-animated-image
   src="https://shoelace.style/assets/images/walk.gif"

docs/components/animation.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-animation]
 
-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).
-
 To animate an element, wrap it in `<sl-animation>` 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
@@ -93,19 +91,19 @@ This example demonstrates all of the baked-in animations and easings. Animations
   const easings = getEasingNames();
 
   animations.map(name => {
-    const menuItem = Object.assign(document.createElement('sl-menu-item'), {
+    const option = Object.assign(document.createElement('sl-option'), {
       textContent: name,
       value: name
     });
-    animationName.appendChild(menuItem);
+    animationName.appendChild(option);
   });
 
   easings.map(name => {
-    const menuItem = Object.assign(document.createElement('sl-menu-item'), {
+    const option = Object.assign(document.createElement('sl-option'), {
       textContent: name,
       value: name
     });
-    easingName.appendChild(menuItem);
+    easingName.appendChild(option);
   });
 
   animationName.addEventListener('sl-change', () => (animation.name = animationName.value));

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
@@ -21,12 +19,18 @@ const App = () => <SlAvatar label="User avatar" />;
 ### Images
 
 To use an image for the avatar, set the `image` and `label` attributes. This will take priority and be shown over initials and icons.
+Avatar images can be lazily loaded by setting the `loading` attribute to `lazy`.
 
 ```html preview
 <sl-avatar
   image="https://images.unsplash.com/photo-1529778873920-4da4926a72c2?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
   label="Avatar of a gray tabby kitten looking down"
 ></sl-avatar>
+<sl-avatar
+  image="https://images.unsplash.com/photo-1591871937573-74dbba515c4c?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
+  label="Avatar of a white and grey kitten on grey textile"
+  loading="lazy"
+></sl-avatar>
 ```
 
 ```jsx react
@@ -37,6 +41,11 @@ const App = () => (
     image="https://images.unsplash.com/photo-1529778873920-4da4926a72c2?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
     label="Avatar of a gray tabby kitten looking down"
   />
+  <SlAvatar
+    image="https://images.unsplash.com/photo-1591871937573-74dbba515c4c?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
+    label="Avatar of a white and grey kitten on grey textile"
+    loading="lazy"
+  />
 );
 ```
 

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
 <sl-badge>Badge</sl-badge>
 ```

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
 <sl-breadcrumb>
   <sl-breadcrumb-item>

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
@@ -205,9 +203,9 @@ Dropdown menus can be placed in a prefix or suffix slot to provide additional op
         <sl-icon label="More options" name="three-dots"></sl-icon>
       </sl-button>
       <sl-menu>
-        <sl-menu-item checked>Web Design</sl-menu-item>
-        <sl-menu-item>Web Development</sl-menu-item>
-        <sl-menu-item>Marketing</sl-menu-item>
+        <sl-menu-item type="checkbox" checked>Web Design</sl-menu-item>
+        <sl-menu-item type="checkbox">Web Development</sl-menu-item>
+        <sl-menu-item type="checkbox">Marketing</sl-menu-item>
       </sl-menu>
     </sl-dropdown>
   </sl-breadcrumb-item>
@@ -237,9 +235,11 @@ const App = () => (
           <SlIcon label="More options" name="three-dots"></SlIcon>
         </SlButton>
         <SlMenu>
-          <SlMenuItem checked>Web Design</SlMenuItem>
-          <SlMenuItem>Web Development</SlMenuItem>
-          <SlMenuItem>Marketing</SlMenuItem>
+          <SlMenuItem type="checkbox" checked>
+            Web Design
+          </SlMenuItem>
+          <SlMenuItem type="checkbox">Web Development</SlMenuItem>
+          <SlMenuItem type="checkbox">Marketing</SlMenuItem>
         </SlMenu>
       </SlDropdown>
     </SlBreadcrumbItem>

docs/components/button-group.md

@@ -2,10 +2,8 @@
 
 [component-header:sl-button-group]
 
-Button groups can be used to group related buttons into sections.
-
 ```html preview
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button>Left</sl-button>
   <sl-button>Center</sl-button>
   <sl-button>Right</sl-button>
@@ -16,7 +14,7 @@ Button groups can be used to group related buttons into sections.
 import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlButtonGroup>
+  <SlButtonGroup label="Alignment">
     <SlButton>Left</SlButton>
     <SlButton>Center</SlButton>
     <SlButton>Right</SlButton>
@@ -31,7 +29,7 @@ const App = () => (
 All button sizes are supported, but avoid mixing sizes within the same button group.
 
 ```html preview
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button size="small">Left</sl-button>
   <sl-button size="small">Center</sl-button>
   <sl-button size="small">Right</sl-button>
@@ -39,7 +37,7 @@ All button sizes are supported, but avoid mixing sizes within the same button gr
 
 <br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button size="medium">Left</sl-button>
   <sl-button size="medium">Center</sl-button>
   <sl-button size="medium">Right</sl-button>
@@ -47,7 +45,7 @@ All button sizes are supported, but avoid mixing sizes within the same button gr
 
 <br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button size="large">Left</sl-button>
   <sl-button size="large">Center</sl-button>
   <sl-button size="large">Right</sl-button>
@@ -59,7 +57,7 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton size="small">Left</SlButton>
       <SlButton size="small">Center</SlButton>
       <SlButton size="small">Right</SlButton>
@@ -68,7 +66,7 @@ const App = () => (
     <br />
     <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton size="medium">Left</SlButton>
       <SlButton size="medium">Center</SlButton>
       <SlButton size="medium">Right</SlButton>
@@ -77,7 +75,7 @@ const App = () => (
     <br />
     <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton size="large">Left</SlButton>
       <SlButton size="large">Center</SlButton>
       <SlButton size="large">Right</SlButton>
@@ -88,10 +86,10 @@ const App = () => (
 
 ### Theme Buttons
 
-Theme buttons are supported through the button's `type` attribute.
+Theme buttons are supported through the button's `variant` attribute.
 
 ```html preview
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button variant="primary">Left</sl-button>
   <sl-button variant="primary">Center</sl-button>
   <sl-button variant="primary">Right</sl-button>
@@ -99,7 +97,7 @@ Theme buttons are supported through the button's `type` attribute.
 
 <br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button variant="success">Left</sl-button>
   <sl-button variant="success">Center</sl-button>
   <sl-button variant="success">Right</sl-button>
@@ -107,7 +105,7 @@ Theme buttons are supported through the button's `type` attribute.
 
 <br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button variant="neutral">Left</sl-button>
   <sl-button variant="neutral">Center</sl-button>
   <sl-button variant="neutral">Right</sl-button>
@@ -115,7 +113,7 @@ Theme buttons are supported through the button's `type` attribute.
 
 <br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button variant="warning">Left</sl-button>
   <sl-button variant="warning">Center</sl-button>
   <sl-button variant="warning">Right</sl-button>
@@ -123,7 +121,7 @@ Theme buttons are supported through the button's `type` attribute.
 
 <br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button variant="danger">Left</sl-button>
   <sl-button variant="danger">Center</sl-button>
   <sl-button variant="danger">Right</sl-button>
@@ -135,7 +133,7 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton variant="primary">Left</SlButton>
       <SlButton variant="primary">Center</SlButton>
       <SlButton variant="primary">Right</SlButton>
@@ -144,7 +142,7 @@ const App = () => (
     <br />
     <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton variant="success">Left</SlButton>
       <SlButton variant="success">Center</SlButton>
       <SlButton variant="success">Right</SlButton>
@@ -153,7 +151,7 @@ const App = () => (
     <br />
     <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton variant="neutral">Left</SlButton>
       <SlButton variant="neutral">Center</SlButton>
       <SlButton variant="neutral">Right</SlButton>
@@ -162,7 +160,7 @@ const App = () => (
     <br />
     <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton variant="warning">Left</SlButton>
       <SlButton variant="warning">Center</SlButton>
       <SlButton variant="warning">Right</SlButton>
@@ -171,7 +169,7 @@ const App = () => (
     <br />
     <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton variant="danger">Left</SlButton>
       <SlButton variant="danger">Center</SlButton>
       <SlButton variant="danger">Right</SlButton>
@@ -185,7 +183,7 @@ const App = () => (
 Pill buttons are supported through the button's `pill` attribute.
 
 ```html preview
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button size="small" pill>Left</sl-button>
   <sl-button size="small" pill>Center</sl-button>
   <sl-button size="small" pill>Right</sl-button>
@@ -193,7 +191,7 @@ Pill buttons are supported through the button's `pill` attribute.
 
 <br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button size="medium" pill>Left</sl-button>
   <sl-button size="medium" pill>Center</sl-button>
   <sl-button size="medium" pill>Right</sl-button>
@@ -201,7 +199,7 @@ Pill buttons are supported through the button's `pill` attribute.
 
 <br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button size="large" pill>Left</sl-button>
   <sl-button size="large" pill>Center</sl-button>
   <sl-button size="large" pill>Right</sl-button>
@@ -213,7 +211,7 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton size="small" pill>
         Left
       </SlButton>
@@ -228,7 +226,7 @@ const App = () => (
     <br />
     <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton size="medium" pill>
         Left
       </SlButton>
@@ -243,7 +241,7 @@ const App = () => (
     <br />
     <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton size="large" pill>
         Left
       </SlButton>
@@ -263,7 +261,7 @@ const App = () => (
 Dropdowns can be placed inside button groups as long as the trigger is an `<sl-button>` element.
 
 ```html preview
-<sl-button-group>
+<sl-button-group label="Example Button Group">
   <sl-button>Button</sl-button>
   <sl-button>Button</sl-button>
   <sl-dropdown>
@@ -281,7 +279,7 @@ Dropdowns can be placed inside button groups as long as the trigger is an `<sl-b
 import { SlButton, SlButtonGroup, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlButtonGroup>
+  <SlButtonGroup label="Example Button Group">
     <SlButton>Button</SlButton>
     <SlButton>Button</SlButton>
     <SlDropdown>
@@ -303,7 +301,7 @@ const App = () => (
 Create a split button using a button and a dropdown. Use a [visually hidden](/components/visually-hidden) label to ensure the dropdown is accessible to users with assistive devices.
 
 ```html preview
-<sl-button-group>
+<sl-button-group label="Example Button Group">
   <sl-button variant="primary">Save</sl-button>
   <sl-dropdown placement="bottom-end">
     <sl-button slot="trigger" variant="primary" caret>
@@ -322,7 +320,7 @@ Create a split button using a button and a dropdown. Use a [visually hidden](/co
 import { SlButton, SlButtonGroup, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlButtonGroup>
+  <SlButtonGroup label="Example Button Group">
     <SlButton variant="primary">Save</SlButton>
     <SlDropdown placement="bottom-end">
       <SlButton slot="trigger" variant="primary" caret></SlButton>
@@ -341,7 +339,7 @@ const App = () => (
 Buttons can be wrapped in tooltips to provide more detail when the user interacts with them.
 
 ```html preview
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-tooltip content="I'm on the left">
     <sl-button>Left</sl-button>
   </sl-tooltip>
@@ -361,7 +359,7 @@ import { SlButton, SlButtonGroup, SlTooltip } from '@shoelace-style/shoelace/dis
 
 const App = () => (
   <>
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlTooltip content="I'm on the left">
         <SlButton>Left</SlButton>
       </SlTooltip>

docs/components/button.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-button]
 
-Buttons represent actions that are available to the user.
-
 ```html preview
 <sl-button>Button</sl-button>
 ```
@@ -136,7 +134,7 @@ const App = () => (
 
 ### Circle Buttons
 
-Use the `circle` attribute to create circular icon buttons.
+Use the `circle` attribute to create circular icon buttons. When this attribute is set, the button expects a single `<sl-icon>` in the default slot.
 
 ```html preview
 <sl-button variant="default" size="small" circle>

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
 <sl-card class="card-overview">
   <img
@@ -130,7 +128,6 @@ Headers can be used to display titles and more.
 <sl-card class="card-header">
   <div slot="header">
     Header Title
-
     <sl-icon-button name="gear" label="Settings"></sl-icon-button>
   </div>
 
@@ -206,7 +203,7 @@ Footers can be used to display actions, summaries, or other relevant content.
 
   <div slot="footer">
     <sl-rating></sl-rating>
-    <sl-button slot="footer" variant="primary">Preview</sl-button>
+    <sl-button variant="primary">Preview</sl-button>
   </div>
 </sl-card>
 

docs/components/carousel-item.md

@@ -0,0 +1,81 @@
+# Carousel Item
+
+[component-header:sl-carousel-item]
+
+```html preview
+<sl-carousel pagination>
+  <sl-carousel-item>
+    <img
+      alt="The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash"
+      src="/assets/examples/carousel/mountains.jpg"
+    />
+  </sl-carousel-item>
+  <sl-carousel-item>
+    <img
+      alt="A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash"
+      src="/assets/examples/carousel/waterfall.jpg"
+    />
+  </sl-carousel-item>
+  <sl-carousel-item>
+    <img
+      alt="The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash"
+      src="/assets/examples/carousel/sunset.jpg"
+    />
+  </sl-carousel-item>
+  <sl-carousel-item>
+    <img
+      alt="A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash"
+      src="/assets/examples/carousel/field.jpg"
+    />
+  </sl-carousel-item>
+  <sl-carousel-item>
+    <img
+      alt="A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash"
+      src="/assets/examples/carousel/valley.jpg"
+    />
+  </sl-carousel-item>
+</sl-carousel>
+```
+
+```jsx react
+import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlCarousel pagination>
+    <SlCarouselItem>
+      <img
+        alt="The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash"
+        src="/assets/examples/carousel/mountains.jpg"
+      />
+    </SlCarouselItem>
+    <SlCarouselItem>
+      <img
+        alt="A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash"
+        src="/assets/examples/carousel/waterfall.jpg"
+      />
+    </SlCarouselItem>
+    <SlCarouselItem>
+      <img
+        alt="The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash"
+        src="/assets/examples/carousel/sunset.jpg"
+      />
+    </SlCarouselItem>
+    <SlCarouselItem>
+      <img
+        alt="A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash"
+        src="/assets/examples/carousel/field.jpg"
+      />
+    </SlCarouselItem>
+    <SlCarouselItem>
+      <img
+        alt="A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash"
+        src="/assets/examples/carousel/valley.jpg"
+      />
+    </SlCarouselItem>
+  </SlCarousel>
+);
+```
+
+?> Additional demonstrations can be found in the [carousel examples](/components/carousel).
+
+[component-metadata:sl-carousel-item]

docs/components/checkbox.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-checkbox]
 
-Checkboxes allow the user to toggle an option on or off.
-
 ```html preview
 <sl-checkbox>Checkbox</sl-checkbox>
 ```
@@ -60,6 +58,32 @@ import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
 const App = () => <SlCheckbox disabled>Disabled</SlCheckbox>;
 ```
 
+## Sizes
+
+Use the `size` attribute to change a checkbox's size.
+
+```html preview
+<sl-checkbox size="small">Small</sl-checkbox>
+<br />
+<sl-checkbox size="medium">Medium</sl-checkbox>
+<br />
+<sl-checkbox size="large">Large</sl-checkbox>
+```
+
+```jsx react
+import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlCheckbox size="small">Small</SlCheckbox>
+    <br />
+    <SlCheckbox size="medium">Medium</SlCheckbox>
+    <br />
+    <SlCheckbox size="large">Large</SlCheckbox>
+  </>
+);
+```
+
 ### Custom Validity
 
 Use the `setCustomValidity()` method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.
@@ -74,14 +98,17 @@ Use the `setCustomValidity()` method to set a custom validation message. This wi
   const form = document.querySelector('.custom-validity');
   const checkbox = form.querySelector('sl-checkbox');
   const errorMessage = `Don't forget to check me!`;
+
   // Set initial validity as soon as the element is defined
   customElements.whenDefined('sl-checkbox').then(() => {
     checkbox.setCustomValidity(errorMessage);
   });
+
   // Update validity on change
   checkbox.addEventListener('sl-change', () => {
     checkbox.setCustomValidity(checkbox.checked ? '' : errorMessage);
   });
+
   // Handle submit
   form.addEventListener('submit', event => {
     event.preventDefault();
@@ -93,19 +120,24 @@ Use the `setCustomValidity()` method to set a custom validation message. This wi
 ```jsx react
 import { useEffect, useRef } from 'react';
 import { SlButton, SlCheckbox } from '@shoelace-style/shoelace/dist/react';
+
 const App = () => {
   const checkbox = useRef(null);
   const errorMessage = `Don't forget to check me!`;
+
   function handleChange() {
     checkbox.current.setCustomValidity(checkbox.current.checked ? '' : errorMessage);
   }
+
   function handleSubmit(event) {
     event.preventDefault();
     alert('All fields are valid!');
   }
+
   useEffect(() => {
     checkbox.current.setCustomValidity(errorMessage);
   }, []);
+
   return (
     <form class="custom-validity" onSubmit={handleSubmit}>
       <SlCheckbox ref={checkbox} onSlChange={handleChange}>

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
 <sl-color-picker label="Select a color"></sl-color-picker>
 ```
@@ -34,7 +32,7 @@ const App = () => <SlColorPicker value="#4a90e2" label="Select a color" />;
 
 ### Opacity
 
-Use the `opacity` attribute to enable the opacity slider. When this is enabled, the value will be displayed as HEXA, RGBA, or HSLA based on `format`.
+Use the `opacity` attribute to enable the opacity slider. When this is enabled, the value will be displayed as HEXA, RGBA, HSLA, or HSVA based on `format`.
 
 ```html preview
 <sl-color-picker value="#f5a623ff" opacity label="Select a color"></sl-color-picker>
@@ -48,7 +46,7 @@ const App = () => <SlColorPicker opacity label="Select a color" />;
 
 ### Formats
 
-Set the color picker's format with the `format` attribute. Valid options include `hex`, `rgb`, and `hsl`. Note that the color picker's input will accept any parsable format (including CSS color names) regardless of this option.
+Set the color picker's format with the `format` attribute. Valid options include `hex`, `rgb`, `hsl`, and `hsv`. Note that the color picker's input will accept any parsable format (including CSS color names) regardless of this option.
 
 To prevent users from toggling the format themselves, add the `no-format-toggle` attribute.
 
@@ -56,6 +54,7 @@ To prevent users from toggling the format themselves, add the `no-format-toggle`
 <sl-color-picker format="hex" value="#4a90e2" label="Select a color"></sl-color-picker>
 <sl-color-picker format="rgb" value="rgb(80, 227, 194)" label="Select a color"></sl-color-picker>
 <sl-color-picker format="hsl" value="hsl(290, 87%, 47%)" label="Select a color"></sl-color-picker>
+<sl-color-picker format="hsv" value="hsv(55, 89%, 97%)" label="Select a color"></sl-color-picker>
 ```
 
 ```jsx react
@@ -66,10 +65,39 @@ const App = () => (
     <SlColorPicker format="hex" value="#4a90e2" />
     <SlColorPicker format="rgb" value="rgb(80, 227, 194)" />
     <SlColorPicker format="hsl" value="hsl(290, 87%, 47%)" />
+    <SlColorPicker format="hsv" value="hsv(55, 89%, 97%)" />
   </>
 );
 ```
 
+### Swatches
+
+Use the `swatches` attribute to add convenient presets to the color picker. Any format the color picker can parse is acceptable (including CSS color names), but each value must be separated by a semicolon (`;`). Alternatively, you can pass an array of color values to this property using JavaScript.
+
+```html preview
+<sl-color-picker
+  label="Select a color"
+  swatches="
+    #d0021b; #f5a623; #f8e71c; #8b572a; #7ed321; #417505; #bd10e0; #9013fe; 
+    #4a90e2; #50e3c2; #b8e986; #000; #444; #888; #ccc; #fff;
+  "
+></sl-color-picker>
+```
+
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlColorPicker
+    label="Select a color"
+    swatches="
+      #d0021b; #f5a623; #f8e71c; #8b572a; #7ed321; #417505; #bd10e0; #9013fe; 
+      #4a90e2; #50e3c2; #b8e986; #000; #444; #888; #ccc; #fff;
+    "
+  />
+);
+```
+
 ### Sizes
 
 Use the `size` attribute to change the color picker's trigger size.

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
 <sl-details summary="Toggle Me">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
@@ -48,6 +46,52 @@ const App = () => (
 );
 ```
 
+### Customizing the Summary Icon
+
+Use the `expand-icon` and `collapse-icon` slots to change the expand and collapse icons, respectively. To disable the animation, override the `rotate` property on the `summary-icon` part as shown below.
+
+```html preview
+<sl-details summary="Toggle Me" class="custom-icons">
+  <sl-icon name="plus-square" slot="expand-icon"></sl-icon>
+  <sl-icon name="dash-square" slot="collapse-icon"></sl-icon>
+
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
+  aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+</sl-details>
+
+<style>
+  sl-details.custom-icons::part(summary-icon) {
+    /* Disable the expand/collapse animation */
+    rotate: none;
+  }
+</style>
+```
+
+```jsx react
+import { SlDetails, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  sl-details.custom-icon::part(summary-icon) {
+    /* Disable the expand/collapse animation */
+    rotate: none;
+  }
+`;
+
+const App = () => (
+  <>
+    <SlDetails summary="Toggle Me" class="custom-icon">
+      <SlIcon name="plus-square" slot="expand-icon" />
+      <SlIcon name="dash-square" slot="collapse-icon" />
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore
+      magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+      consequat.
+    </SlDetails>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ### Grouping Details
 
 Details are designed to function independently, but you can simulate a group or "accordion" where only one is shown at a time by listening for the `sl-show` event.

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
 <sl-dialog label="Dialog" class="dialog-overview">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
@@ -153,6 +151,59 @@ const App = () => {
 };
 ```
 
+### Header Actions
+
+The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/components/icon-button) if needed.
+
+```html preview
+<sl-dialog label="Dialog" class="dialog-header-actions">
+  <sl-icon-button class="new-window" slot="header-actions" name="box-arrow-up-right"></sl-icon-button>
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  <sl-button slot="footer" variant="primary">Close</sl-button>
+</sl-dialog>
+
+<sl-button>Open Dialog</sl-button>
+
+<script>
+  const dialog = document.querySelector('.dialog-header-actions');
+  const openButton = dialog.nextElementSibling;
+  const closeButton = dialog.querySelector('sl-button[slot="footer"]');
+  const newWindowButton = dialog.querySelector('.new-window');
+
+  openButton.addEventListener('click', () => dialog.show());
+  closeButton.addEventListener('click', () => dialog.hide());
+  newWindowButton.addEventListener('click', () => window.open(location.href));
+</script>
+```
+
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDialog, SlIconButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
+        <SlIconButton
+          class="new-window"
+          slot="header-actions"
+          name="box-arrow-up-right"
+          onClick={() => window.open(location.href)}
+        />
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDialog>
+
+      <SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
+    </>
+  );
+};
+```
+
 ### Preventing the Dialog from Closing
 
 By default, dialogs will close when the user clicks the close button, clicks the overlay, or presses the <kbd>Escape</kbd> key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.

docs/components/divider.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-divider]
 
-Dividers are used to visually separate or group elements.
-
 ```html preview
 <sl-divider></sl-divider>
 ```

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
 <sl-drawer label="Drawer" class="drawer-overview">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
@@ -182,7 +180,9 @@ const App = () => {
 
 ### Contained to an Element
 
-By default, the drawer slides out of its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport. To make the drawer slide out of its parent element, add the `contained` attribute and `position: relative` to the parent.
+By default, drawers slide out of their [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport. To make a drawer slide out of a parent element, add the `contained` attribute to the drawer and apply `position: relative` to its parent.
+
+Unlike normal drawers, contained drawers are not modal. This means they do not show an overlay, they do not trap focus, and they are not dismissible with <kbd>Escape</kbd>. This is intentional to allow users to interact with elements outside of the drawer.
 
 ```html preview
 <div
@@ -196,14 +196,14 @@ By default, the drawer slides out of its [containing block](https://developer.mo
   </sl-drawer>
 </div>
 
-<sl-button>Open Drawer</sl-button>
+<sl-button>Toggle Drawer</sl-button>
 
 <script>
   const drawer = document.querySelector('.drawer-contained');
   const openButton = drawer.parentElement.nextElementSibling;
   const closeButton = drawer.querySelector('sl-button[variant="primary"]');
 
-  openButton.addEventListener('click', () => drawer.show());
+  openButton.addEventListener('click', () => (drawer.open = !drawer.open));
   closeButton.addEventListener('click', () => drawer.hide());
 </script>
 ```
@@ -228,7 +228,14 @@ const App = () => {
       >
         The drawer will be contained to this box. This content won't shift or be affected in any way when the drawer
         opens.
-        <SlDrawer label="Drawer" contained open={open} onSlAfterHide={() => setOpen(false)} style={{ '--size': '50%' }}>
+        <SlDrawer
+          label="Drawer"
+          contained
+          no-modal
+          open={open}
+          onSlAfterHide={() => setOpen(false)}
+          style={{ '--size': '50%' }}
+        >
           Lorem ipsum dolor sit amet, consectetur adipiscing elit.
           <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
             Close
@@ -340,6 +347,54 @@ const App = () => {
 };
 ```
 
+### Header Actions
+
+The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/components/icon-button) if needed.
+
+```html preview
+<sl-drawer label="Drawer" class="drawer-header-actions">
+  <sl-icon-button class="new-window" slot="header-actions" name="box-arrow-up-right"></sl-icon-button>
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  <sl-button slot="footer" variant="primary">Close</sl-button>
+</sl-drawer>
+
+<sl-button>Open Drawer</sl-button>
+
+<script>
+  const drawer = document.querySelector('.drawer-header-actions');
+  const openButton = drawer.nextElementSibling;
+  const closeButton = drawer.querySelector('sl-button[variant="primary"]');
+  const newWindowButton = drawer.querySelector('.new-window');
+
+  openButton.addEventListener('click', () => drawer.show());
+  closeButton.addEventListener('click', () => drawer.hide());
+  newWindowButton.addEventListener('click', () => window.open(location.href));
+</script>
+```
+
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDrawer, SlIconButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)}>
+        <SlIconButton slot="header-actions" name="box-arrow-up-right" onClick={() => window.open(location.href)} />
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDrawer>
+
+      <SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
+    </>
+  );
+};
+```
+
 ### Preventing the Drawer from Closing
 
 By default, drawers will close when the user clicks the close button, clicks the overlay, or presses the <kbd>Escape</kbd> key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.

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.
@@ -16,7 +14,7 @@ Dropdowns are designed to work well with [menus](/components/menu) to provide a
     <sl-menu-item>Dropdown Item 2</sl-menu-item>
     <sl-menu-item>Dropdown Item 3</sl-menu-item>
     <sl-divider></sl-divider>
-    <sl-menu-item checked>Checked</sl-menu-item>
+    <sl-menu-item type="checkbox" checked>Checkbox</sl-menu-item>
     <sl-menu-item disabled>Disabled</sl-menu-item>
     <sl-divider></sl-divider>
     <sl-menu-item>
@@ -44,7 +42,9 @@ const App = () => (
       <SlMenuItem>Dropdown Item 2</SlMenuItem>
       <SlMenuItem>Dropdown Item 3</SlMenuItem>
       <SlDivider />
-      <SlMenuItem checked>Checked</SlMenuItem>
+      <SlMenuItem type="checkbox" checked>
+        Checkbox
+      </SlMenuItem>
       <SlMenuItem disabled>Disabled</SlMenuItem>
       <SlDivider />
       <SlMenuItem>
@@ -64,7 +64,7 @@ const App = () => (
 
 ### Getting the Selected Item
 
-When dropdowns are used with [menus](/components/menu), you can listen for the `sl-select` event to determine which menu item was selected. The menu item element will be exposed in `event.detail.item`. You can set `value` props to make it easier to identify commands.
+When dropdowns are used with [menus](/components/menu), you can listen for the [`sl-select`](/components/menu#events) event to determine which menu item was selected. The menu item element will be exposed in `event.detail.item`. You can set `value` props to make it easier to identify commands.
 
 ```html preview
 <div class="dropdown-selection">
@@ -311,6 +311,7 @@ Dropdown panels will be clipped if they're inside a container that has `overflow
 
 <style>
   .dropdown-hoist {
+    position: relative;
     border: solid 2px var(--sl-panel-border-color);
     padding: var(--sl-spacing-medium);
     overflow: hidden;

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
 <div class="format-bytes-overview">
   The file is <sl-format-bytes value="1000"></sl-format-bytes> in size. <br /><br />

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

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

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

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.
@@ -22,9 +20,9 @@ All available icons in the `default` icon library are shown below. Click or tap
       <sl-icon slot="prefix" name="search"></sl-icon>
     </sl-input>
     <sl-select value="outline">
-      <sl-menu-item value="outline">Outlined</sl-menu-item>
-      <sl-menu-item value="fill">Filled</sl-menu-item>
-      <sl-menu-item value="all">All icons</sl-menu-item>
+      <sl-option value="outline">Outlined</sl-option>
+      <sl-option value="fill">Filled</sl-option>
+      <sl-option value="all">All icons</sl-option>
     </sl-select>
   </div>
   <div class="icon-list"></div>
@@ -336,17 +334,17 @@ Icons in this library are licensed under the [MIT License](https://github.com/ta
   import { registerIconLibrary } from '/dist/utilities/icon-library.js';
 
   registerIconLibrary('heroicons', {
-    resolver: name => `https://cdn.jsdelivr.net/npm/heroicons@0.4.2/outline/${name}.svg`
+    resolver: name => `https://cdn.jsdelivr.net/npm/heroicons@2.0.1/24/outline/${name}.svg`
   });
 </script>
 
 <div style="font-size: 24px;">
-  <sl-icon library="heroicons" name="chat"></sl-icon>
+  <sl-icon library="heroicons" name="chat-bubble-left"></sl-icon>
   <sl-icon library="heroicons" name="cloud"></sl-icon>
   <sl-icon library="heroicons" name="cog"></sl-icon>
   <sl-icon library="heroicons" name="document-text"></sl-icon>
   <sl-icon library="heroicons" name="gift"></sl-icon>
-  <sl-icon library="heroicons" name="volume-up"></sl-icon>
+  <sl-icon library="heroicons" name="speaker-wave"></sl-icon>
 </div>
 ```
 
@@ -533,7 +531,7 @@ Icons in this library are licensed under the [Apache 2.0 License](https://github
 </div>
 ```
 
-## Tabler Icons
+### Tabler Icons
 
 This will register the [Tabler Icons](https://tabler-icons.io/) library using the jsDelivr CDN. This library features over 1,950 open source icons.
 
@@ -637,6 +635,19 @@ If you want to change the icons Shoelace uses internally, you can register an ic
 
 <!-- Supporting scripts and styles for the search utility -->
 <script>
+  function wrapWithTooltip(item) {
+    const tooltip = document.createElement('sl-tooltip');
+    tooltip.content = item.getAttribute('data-name');
+
+    // Close open tooltips
+    document.querySelectorAll('.icon-list sl-tooltip[open]').forEach(tooltip => tooltip.hide());
+
+    // Wrap it with a tooltip and trick it into showing up
+    item.parentNode.insertBefore(tooltip, item);
+    tooltip.appendChild(item);
+    requestAnimationFrame(() => tooltip.dispatchEvent(new MouseEvent('mouseover')));
+  }
+
   fetch('/dist/assets/icons/icons.json')
     .then(res => res.json())  
     .then(icons => {
@@ -660,19 +671,23 @@ If you want to change the icons Shoelace uses internally, you can register an ic
             <use xlink:href="/assets/icons/sprite.svg#${i.name}"></use>
           </svg>      
         `;
+        list.appendChild(item);
 
-        const tooltip = document.createElement('sl-tooltip');
-        tooltip.content = i.name;
-        
-        tooltip.appendChild(item);
-        list.appendChild(tooltip);
+        // Wrap it with a tooltip the first time the mouse lands on it. We do this instead of baking them into the DOM 
+        // to improve this page's performance. See: https://github.com/shoelace-style/shoelace/issues/1122
+        item.addEventListener('mouseover', () => wrapWithTooltip(item), { once: true });
 
+        // Copy on click
         item.addEventListener('click', () => {
+          const tooltip = item.closest('sl-tooltip');
           copyInput.value = i.name;
           copyInput.select();
           document.execCommand('copy');
-          tooltip.content = 'Copied!';
-          setTimeout(() => tooltip.content = i.name, 1000);
+
+          if (tooltip) {
+            tooltip.content = 'Copied!';
+            setTimeout(() => tooltip.content = i.name, 1000);
+          }
         });
       });
 

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

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 `<sl-include>` element's default slot so it can be easily accessed and styled through the light DOM.
@@ -32,12 +30,16 @@ If the request fails, the `sl-error` event will be emitted. In this case, `event
 <script>
   const include = document.querySelector('sl-include');
 
-  include.addEventListener('sl-load', () => {
-    console.log('Success');
+  include.addEventListener('sl-load', event => {
+    if (event.eventPhase === Event.AT_TARGET) {
+      console.log('Success');
+    }
   });
 
   include.addEventListener('sl-error', event => {
-    console.log('Error', event.detail.status);
+    if (event.eventPhase === Event.AT_TARGET) {
+      console.log('Error', event.detail.status);
+    }
   });
 </script>
 ```

docs/components/input.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-input]
 
-Inputs collect data from the user.
-
 ```html preview
 <sl-input></sl-input>
 ```
@@ -76,28 +74,16 @@ const App = () => <SlInput placeholder="Clearable" clearable />;
 
 ### Toggle Password
 
-Add the `toggle-password` attribute to add a toggle button that will show the password when activated.
+Add the `password-toggle` attribute to add a toggle button that will show the password when activated.
 
 ```html preview
-<sl-input type="password" placeholder="Password Toggle" size="small" toggle-password></sl-input>
-<br />
-<sl-input type="password" placeholder="Password Toggle" size="medium" toggle-password></sl-input>
-<br />
-<sl-input type="password" placeholder="Password Toggle" size="large" toggle-password></sl-input>
+<sl-input type="password" placeholder="Password Toggle" password-toggle></sl-input>
 ```
 
 ```jsx react
 import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <>
-    <SlInput type="password" placeholder="Password Toggle" size="small" toggle-password />
-    <br />
-    <SlInput type="password" placeholder="Password Toggle" size="medium" toggle-password />
-    <br />
-    <SlInput type="password" placeholder="Password Toggle" size="large" toggle-password />
-  </>
-);
+const App = () => <SlInput type="password" placeholder="Password Toggle" size="medium" password-toggle />;
 ```
 
 ### Filled Inputs
@@ -114,6 +100,46 @@ import { SlInput } from '@shoelace-style/shoelace/dist/react';
 const App = () => <SlInput placeholder="Type something" filled />;
 ```
 
+### Disabled
+
+Use the `disabled` attribute to disable an input.
+
+```html preview
+<sl-input placeholder="Disabled" disabled></sl-input>
+```
+
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => <SlInput placeholder="Disabled" disabled />;
+```
+
+### Sizes
+
+Use the `size` attribute to change an input's size.
+
+```html preview
+<sl-input placeholder="Small" size="small"></sl-input>
+<br />
+<sl-input placeholder="Medium" size="medium"></sl-input>
+<br />
+<sl-input placeholder="Large" size="large"></sl-input>
+```
+
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlInput placeholder="Small" size="small" />
+    <br />
+    <SlInput placeholder="Medium" size="medium" />
+    <br />
+    <SlInput placeholder="Large" size="large" />
+  </>
+);
+```
+
 ### Pill
 
 Use the `pill` attribute to give inputs rounded edges.
@@ -166,58 +192,6 @@ const App = () => (
 );
 ```
 
-### Disabled
-
-Use the `disabled` attribute to disable an input.
-
-```html preview
-<sl-input placeholder="Disabled" size="small" disabled></sl-input>
-<br />
-<sl-input placeholder="Disabled" size="medium" disabled></sl-input>
-<br />
-<sl-input placeholder="Disabled" size="large" disabled></sl-input>
-```
-
-```jsx react
-import { SlInput } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <>
-    <SlInput placeholder="Disabled" size="small" disabled />
-    <br />
-    <SlInput placeholder="Disabled" size="medium" disabled />
-    <br />
-    <SlInput placeholder="Disabled" size="large" disabled />
-  </>
-);
-```
-
-### Sizes
-
-Use the `size` attribute to change an input's size.
-
-```html preview
-<sl-input placeholder="Small" size="small"></sl-input>
-<br />
-<sl-input placeholder="Medium" size="medium"></sl-input>
-<br />
-<sl-input placeholder="Large" size="large"></sl-input>
-```
-
-```jsx react
-import { SlInput } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <>
-    <SlInput placeholder="Small" size="small" />
-    <br />
-    <SlInput placeholder="Medium" size="medium" />
-    <br />
-    <SlInput placeholder="Large" size="large" />
-  </>
-);
-```
-
 ### Prefix & Suffix Icons
 
 Use the `prefix` and `suffix` slots to add icons.
@@ -264,27 +238,36 @@ const App = () => (
 
 ### Customizing Label Position
 
-Use parts to customize the label's position.
+Use [CSS parts](#css-parts) to customize the way form controls are drawn. This example uses CSS grid to position the label to the left of the control, but the possible orientations are nearly endless. The same technique works for inputs, textareas, radio groups, and similar form controls.
 
 ```html preview
-<sl-input class="label-on-left" label="Name"></sl-input><br />
-<sl-input class="label-on-left" label="Email" type="email"></sl-input>
+<sl-input class="label-on-left" label="Name" help-text="Enter your name""></sl-input>
+<sl-input class="label-on-left" label="Email" type="email" help-text="Enter your email"></sl-input>
+<sl-textarea class="label-on-left" label="Bio" help-text="Tell us something about yourself"></sl-textarea>
 
 <style>
+  .label-on-left {
+    --label-width: 3.75rem;
+    --gap-width: 1rem;
+  }
+
+  .label-on-left + .label-on-left {
+    margin-top: var(--sl-spacing-medium);
+  }
+
   .label-on-left::part(form-control) {
-    display: flex;
+    display: grid;
+    grid: auto / var(--label-width) 1fr;
+    gap: var(--sl-spacing-3x-small) var(--gap-width);
     align-items: center;
-    gap: 1rem;
   }
 
   .label-on-left::part(form-control-label) {
-    flex: 0 0 auto;
-    width: 60px;
     text-align: right;
   }
 
-  .label-on-left::part(form-control-input) {
-    flex: 1 1 auto;
+  .label-on-left::part(form-control-help-text) {
+    grid-column-start: 2;
   }
 </style>
 ```

docs/components/menu-item.md

@@ -2,15 +2,13 @@
 
 [component-header:sl-menu-item]
 
-Menu items provide options for the user to pick from in a menu.
-
 ```html preview
 <sl-menu style="max-width: 200px;">
   <sl-menu-item>Option 1</sl-menu-item>
   <sl-menu-item>Option 2</sl-menu-item>
   <sl-menu-item>Option 3</sl-menu-item>
   <sl-divider></sl-divider>
-  <sl-menu-item checked>Checked</sl-menu-item>
+  <sl-menu-item type="checkbox" checked>Checkbox</sl-menu-item>
   <sl-menu-item disabled>Disabled</sl-menu-item>
   <sl-divider></sl-divider>
   <sl-menu-item>
@@ -33,7 +31,9 @@ const App = () => (
     <SlMenuItem>Option 2</SlMenuItem>
     <SlMenuItem>Option 3</SlMenuItem>
     <SlDivider />
-    <SlMenuItem checked>Checked</SlMenuItem>
+    <SlMenuItem type="checkbox" checked>
+      Checkbox
+    </SlMenuItem>
     <SlMenuItem disabled>Disabled</SlMenuItem>
     <SlDivider />
     <SlMenuItem>
@@ -50,30 +50,6 @@ const App = () => (
 
 ## Examples
 
-### Checked
-
-Use the `checked` attribute to draw menu items in a checked state.
-
-```html preview
-<sl-menu style="max-width: 200px;">
-  <sl-menu-item>Option 1</sl-menu-item>
-  <sl-menu-item checked>Option 2</sl-menu-item>
-  <sl-menu-item>Option 3</sl-menu-item>
-</sl-menu>
-```
-
-```jsx react
-import { SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlMenu style={{ maxWidth: '200px' }}>
-    <SlMenuItem>Option 1</SlMenuItem>
-    <SlMenuItem checked>Option 2</SlMenuItem>
-    <SlMenuItem>Option 3</SlMenuItem>
-  </SlMenu>
-);
-```
-
 ### Disabled
 
 Add the `disabled` attribute to disable the menu item so it cannot be selected.
@@ -152,6 +128,34 @@ const App = () => (
 );
 ```
 
+### Checkbox Menu Items
+
+Set the `type` attribute to `checkbox` to create a menu item that will toggle on and off when selected. You can use the `checked` attribute to set the initial state.
+
+Checkbox menu items are visually indistinguishable from regular menu items. Their ability to be toggled is primarily inferred from context, much like you'd find in the menu of a native app.
+
+```html preview
+<sl-menu style="max-width: 200px;">
+  <sl-menu-item type="checkbox">Autosave</sl-menu-item>
+  <sl-menu-item type="checkbox" checked>Check Spelling</sl-menu-item>
+  <sl-menu-item type="checkbox">Word Wrap</sl-menu-item>
+</sl-menu>
+```
+
+```jsx react
+import { SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlMenu style={{ maxWidth: '200px' }}>
+    <SlMenuItem type="checkbox">Autosave</SlMenuItem>
+    <SlMenuItem type="checkbox" checked>
+      Check Spelling
+    </SlMenuItem>
+    <SlMenuItem type="checkbox">Word Wrap</SlMenuItem>
+  </SlMenu>
+);
+```
+
 ### Value & Selection
 
 The `value` attribute can be used to assign a hidden value, such as a unique identifier, to a menu item. When an item is selected, the `sl-select` event will be emitted and a reference to the item will be available at `event.detail.item`. You can use this reference to access the selected item's value, its checked state, and more.
@@ -161,6 +165,10 @@ The `value` attribute can be used to assign a hidden value, such as a unique ide
   <sl-menu-item value="opt-1">Option 1</sl-menu-item>
   <sl-menu-item value="opt-2">Option 2</sl-menu-item>
   <sl-menu-item value="opt-3">Option 3</sl-menu-item>
+  <sl-divider></sl-divider>
+  <sl-menu-item type="checkbox" value="opt-4">Checkbox 4</sl-menu-item>
+  <sl-menu-item type="checkbox" value="opt-5">Checkbox 5</sl-menu-item>
+  <sl-menu-item type="checkbox" value="opt-6">Checkbox 6</sl-menu-item>
 </sl-menu>
 
 <script>
@@ -169,11 +177,12 @@ The `value` attribute can be used to assign a hidden value, such as a unique ide
   menu.addEventListener('sl-select', event => {
     const item = event.detail.item;
 
-    // Toggle checked state
-    item.checked = !item.checked;
-
     // Log value
-    console.log(`Selected value: ${item.value}`);
+    if (item.type === 'checkbox') {
+      console.log(`Selected value: ${item.value} (${item.checked ? 'checked' : 'unchecked'})`);
+    } else {
+      console.log(`Selected value: ${item.value}`);
+    }
   });
 </script>
 ```

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
 <sl-menu style="max-width: 200px;">
   <sl-menu-label>Fruits</sl-menu-label>

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

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

docs/components/option.md

@@ -0,0 +1,79 @@
+# Option
+
+[component-header:sl-option]
+
+```html preview
+<sl-select label="Select one">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+</sl-select>
+```
+
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSelect>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+  </SlSelect>
+);
+```
+
+## Examples
+
+### Disabled
+
+Use the `disabled` attribute to disable an option and prevent it from being selected.
+
+```html preview
+<sl-select label="Select one">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2" disabled>Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+</sl-select>
+```
+
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSelect>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2" disabled>
+      Option 2
+    </SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+  </SlSelect>
+);
+```
+
+### Prefix & Suffix
+
+Add icons to the start and end of menu items using the `prefix` and `suffix` slots.
+
+```html preview
+<sl-select label="Select one">
+  <sl-option value="option-1">
+    <sl-icon slot="prefix" name="envelope"></sl-icon>
+    Email
+    <sl-icon slot="suffix" name="patch-check"></sl-icon>
+  </sl-option>
+
+  <sl-option value="option-2">
+    <sl-icon slot="prefix" name="telephone"></sl-icon>
+    Phone
+    <sl-icon slot="suffix" name="patch-check"></sl-icon>
+  </sl-option>
+
+  <sl-option value="option-3">
+    <sl-icon slot="prefix" name="chat-dots"></sl-icon>
+    Chat
+    <sl-icon slot="suffix" name="patch-check"></sl-icon>
+  </sl-option>
+</sl-select>
+```
+
+[component-metadata:sl-option]

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
 <sl-progress-bar value="50"></sl-progress-bar>
 ```

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
 <sl-progress-ring value="25"></sl-progress-ring>
 ```
@@ -30,18 +28,18 @@ import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 const App = () => <SlProgressRing value="50" style={{ '--size': '200px' }} />;
 ```
 
-### Track Width
+### Track and Indicator Width
 
-Use the `--track-width` custom property to set the width of the progress ring's track.
+Use the `--track-width` and `--indicator-width` custom properties to set the width of the progress ring's track and indicator.
 
 ```html preview
-<sl-progress-ring value="50" style="--track-width: 10px;"></sl-progress-ring>
+<sl-progress-ring value="50" style="--track-width: 6px; --indicator-width: 12px;"></sl-progress-ring>
 ```
 
 ```jsx react
 import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => <SlProgressRing value="50" style={{ '--track-width': '10px' }} />;
+const App = () => <SlProgressRing value="50" style={{ '--track-width': '6px', '--indicator-width': '12px' }} />;
 ```
 
 ### Colors

docs/components/qr-code.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-qr-code]
 
-Generates a [QR code](https://www.qrcode.com/) and renders it using the [Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API).
-
 QR codes are useful for providing small pieces of information to users who can quickly scan them with a smartphone. Most smartphones have built-in QR code scanners, so simply pointing the camera at a QR code will decode it and allow the user to visit a website, dial a phone number, read a message, etc.
 
 ```html preview

docs/components/radio-button.md

@@ -2,15 +2,13 @@
 
 [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
-<sl-radio-group label="Select an option">
-  <sl-radio-button name="a" value="1" checked>Option 1</sl-radio-button>
-  <sl-radio-button name="a" value="2">Option 2</sl-radio-button>
-  <sl-radio-button name="a" value="3">Option 3</sl-radio-button>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button value="1">Option 1</sl-radio-button>
+  <sl-radio-button value="2">Option 2</sl-radio-button>
+  <sl-radio-button value="3">Option 3</sl-radio-button>
 </sl-radio-group>
 ```
 
@@ -18,31 +16,25 @@ Radio buttons are designed to be used with [radio groups](/components/radio-grou
 import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadioButton name="option" value="1" checked>
-      Option 1
-    </SlRadioButton>
-    <SlRadioButton name="option" value="2">
-      Option 2
-    </SlRadioButton>
-    <SlRadioButton name="option" value="3">
-      Option 3
-    </SlRadioButton>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton value="1">Option 1</SlRadioButton>
+    <SlRadioButton value="2">Option 2</SlRadioButton>
+    <SlRadioButton value="3">Option 3</SlRadioButton>
   </SlRadioGroup>
 );
 ```
 
 ## Examples
 
-### Checked
+### Checked States
 
-To set the initial checked state, use the `checked` attribute.
+To set the initial value and checked state, use the `value` attribute on the containing radio group.
 
 ```html preview
-<sl-radio-group label="Select an option">
-  <sl-radio-button name="option" value="1" checked>Option 1</sl-radio-button>
-  <sl-radio-button name="option" value="2">Option 2</sl-radio-button>
-  <sl-radio-button name="option" value="3">Option 3</sl-radio-button>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button value="1">Option 1</sl-radio-button>
+  <sl-radio-button value="2">Option 2</sl-radio-button>
+  <sl-radio-button value="3">Option 3</sl-radio-button>
 </sl-radio-group>
 ```
 
@@ -50,16 +42,10 @@ To set the initial checked state, use the `checked` attribute.
 import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadioButton name="option" value="1" checked>
-      Option 1
-    </SlRadioButton>
-    <SlRadioButton name="option" value="2">
-      Option 2
-    </SlRadioButton>
-    <SlRadioButton name="option" value="3">
-      Option 3
-    </SlRadioButton>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton value="1">Option 1</SlRadioButton>
+    <SlRadioButton value="2">Option 2</SlRadioButton>
+    <SlRadioButton value="3">Option 3</SlRadioButton>
   </SlRadioGroup>
 );
 ```
@@ -69,10 +55,10 @@ const App = () => (
 Use the `disabled` attribute to disable a radio button.
 
 ```html preview
-<sl-radio-group label="Select an option">
-  <sl-radio-button name="option" value="1" checked>Option 1</sl-radio-button>
-  <sl-radio-button name="option" value="2">Option 2</sl-radio-button>
-  <sl-radio-button name="option" value="3" disabled>Option 3</sl-radio-button>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button value="1">Option 1</sl-radio-button>
+  <sl-radio-button value="2" disabled>Option 2</sl-radio-button>
+  <sl-radio-button value="3">Option 3</sl-radio-button>
 </sl-radio-group>
 ```
 
@@ -80,16 +66,12 @@ Use the `disabled` attribute to disable a radio button.
 import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadioButton name="option" value="1" checked>
-      Option 1
-    </SlRadioButton>
-    <SlRadioButton name="option" value="2">
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton value="1">Option 1</SlRadioButton>
+    <SlRadioButton value="2" disabled>
       Option 2
     </SlRadioButton>
-    <SlRadioButton name="option" value="3" disabled>
-      Option 3
-    </SlRadioButton>
+    <SlRadioButton value="3">Option 3</SlRadioButton>
   </SlRadioGroup>
 );
 ```
@@ -99,26 +81,26 @@ const App = () => (
 Use the `size` attribute to change a radio button's size.
 
 ```html preview
-<sl-radio-group label="Select an option">
-  <sl-radio-button size="small" name="option" value="1" checked>Option 1</sl-radio-button>
-  <sl-radio-button size="small" name="option" value="2">Option 2</sl-radio-button>
-  <sl-radio-button size="small" name="option" value="3">Option 3</sl-radio-button>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button size="small" value="1">Option 1</sl-radio-button>
+  <sl-radio-button size="small" value="2">Option 2</sl-radio-button>
+  <sl-radio-button size="small" value="3">Option 3</sl-radio-button>
 </sl-radio-group>
 
 <br />
 
-<sl-radio-group label="Select an option">
-  <sl-radio-button size="medium" name="option" value="1" checked>Option 1</sl-radio-button>
-  <sl-radio-button size="medium" name="option" value="2">Option 2</sl-radio-button>
-  <sl-radio-button size="medium" name="option" value="3">Option 3</sl-radio-button>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button size="medium" value="1">Option 1</sl-radio-button>
+  <sl-radio-button size="medium" value="2">Option 2</sl-radio-button>
+  <sl-radio-button size="medium" value="3">Option 3</sl-radio-button>
 </sl-radio-group>
 
 <br />
 
-<sl-radio-group label="Select an option">
-  <sl-radio-button size="large" name="option" value="1" checked>Option 1</sl-radio-button>
-  <sl-radio-button size="large" name="option" value="2">Option 2</sl-radio-button>
-  <sl-radio-button size="large" name="option" value="3">Option 3</sl-radio-button>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button size="large" value="1">Option 1</sl-radio-button>
+  <sl-radio-button size="large" value="2">Option 2</sl-radio-button>
+  <sl-radio-button size="large" value="3">Option 3</sl-radio-button>
 </sl-radio-group>
 ```
 
@@ -126,26 +108,26 @@ Use the `size` attribute to change a radio button's size.
 import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadioButton size="small" name="option" value="1" checked>Option 1</SlRadioButton>
-    <SlRadioButton size="small" name="option" value="2">Option 2</SlRadioButton>
-    <SlRadioButton size="small" name="option" value="3">Option 3</SlRadioButton>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton size="small" value="1">Option 1</SlRadioButton>
+    <SlRadioButton size="small" value="2">Option 2</SlRadioButton>
+    <SlRadioButton size="small" value="3">Option 3</SlRadioButton>
   </SlRadioGroup>
 
   <br />
 
-  <SlRadioGroup label="Select an option">
-    <SlRadioButton size="medium" name="option" value="1" checked>Option 1</SlRadioButton>
-    <SlRadioButton size="medium" name="option" value="2">Option 2</SlRadioButton>
-    <SlRadioButton size="medium" name="option" value="3">Option 3</SlRadioButton>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton size="medium" value="1">Option 1</SlRadioButton>
+    <SlRadioButton size="medium" value="2">Option 2</SlRadioButton>
+    <SlRadioButton size="medium" value="3">Option 3</SlRadioButton>
   </SlRadioGroup>
 
   <br />
 
-  <SlRadioGroup label="Select an option">
-    <SlRadioButton size="large" name="option" value="1" checked>Option 1</SlRadioButton>
-    <SlRadioButton size="large" name="option" value="2">Option 2</SlRadioButton>
-    <SlRadioButton size="large" name="option" value="3">Option 3</SlRadioButton>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton size="large" value="1">Option 1</SlRadioButton>
+    <SlRadioButton size="large" value="2">Option 2</SlRadioButton>
+    <SlRadioButton size="large" value="3">Option 3</SlRadioButton>
   </SlRadioGroup>
 );
 ```
@@ -155,26 +137,26 @@ const App = () => (
 Use the `pill` attribute to give radio buttons rounded edges.
 
 ```html preview
-<sl-radio-group label="Select an option">
-  <sl-radio-button pill size="small" name="option" value="1" checked>Option 1</sl-radio-button>
-  <sl-radio-button pill size="small" name="option" value="2">Option 2</sl-radio-button>
-  <sl-radio-button pill size="small" name="option" value="3">Option 3</sl-radio-button>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button pill size="small" value="1">Option 1</sl-radio-button>
+  <sl-radio-button pill size="small" value="2">Option 2</sl-radio-button>
+  <sl-radio-button pill size="small" value="3">Option 3</sl-radio-button>
 </sl-radio-group>
 
 <br />
 
-<sl-radio-group label="Select an option">
-  <sl-radio-button pill size="medium" name="option" value="1" checked>Option 1</sl-radio-button>
-  <sl-radio-button pill size="medium" name="option" value="2">Option 2</sl-radio-button>
-  <sl-radio-button pill size="medium" name="option" value="3">Option 3</sl-radio-button>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button pill size="medium" value="1">Option 1</sl-radio-button>
+  <sl-radio-button pill size="medium" value="2">Option 2</sl-radio-button>
+  <sl-radio-button pill size="medium" value="3">Option 3</sl-radio-button>
 </sl-radio-group>
 
 <br />
 
-<sl-radio-group label="Select an option">
-  <sl-radio-button pill size="large" name="option" value="1" checked>Option 1</sl-radio-button>
-  <sl-radio-button pill size="large" name="option" value="2">Option 2</sl-radio-button>
-  <sl-radio-button pill size="large" name="option" value="3">Option 3</sl-radio-button>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button pill size="large" value="1">Option 1</sl-radio-button>
+  <sl-radio-button pill size="large" value="2">Option 2</sl-radio-button>
+  <sl-radio-button pill size="large" value="3">Option 3</sl-radio-button>
 </sl-radio-group>
 ```
 
@@ -182,26 +164,26 @@ Use the `pill` attribute to give radio buttons rounded edges.
 import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadioButton pill size="small" name="option" value="1" checked>Option 1</SlRadioButton>
-    <SlRadioButton pill size="small" name="option" value="2">Option 2</SlRadioButton>
-    <SlRadioButton pill size="small" name="option" value="3">Option 3</SlRadioButton>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton pill size="small" value="1">Option 1</SlRadioButton>
+    <SlRadioButton pill size="small" value="2">Option 2</SlRadioButton>
+    <SlRadioButton pill size="small" value="3">Option 3</SlRadioButton>
   </SlRadioGroup>
 
   <br />
 
-  <SlRadioGroup label="Select an option">
-    <SlRadioButton pill size="medium" name="option" value="1" checked>Option 1</SlRadioButton>
-    <SlRadioButton pill size="medium" name="option" value="2">Option 2</SlRadioButton>
-    <SlRadioButton pill size="medium" name="option" value="3">Option 3</SlRadioButton>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton pill size="medium" value="1">Option 1</SlRadioButton>
+    <SlRadioButton pill size="medium" value="2">Option 2</SlRadioButton>
+    <SlRadioButton pill size="medium" value="3">Option 3</SlRadioButton>
   </SlRadioGroup>
 
   <br />
 
-  <SlRadioGroup label="Select an option">
-    <SlRadioButton pill size="large" name="option" value="1" checked>Option 1</SlRadioButton>
-    <SlRadioButton pill size="large" name="option" value="2">Option 2</SlRadioButton>
-    <SlRadioButton pill size="large" name="option" value="3">Option 3</SlRadioButton>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton pill size="large" value="1">Option 1</SlRadioButton>
+    <SlRadioButton pill size="large" value="2">Option 2</SlRadioButton>
+    <SlRadioButton pill size="large" value="3">Option 3</SlRadioButton>
   </SlRadioGroup>
 );
 ```
@@ -211,18 +193,18 @@ const App = () => (
 Use the `prefix` and `suffix` slots to add icons.
 
 ```html preview
-<sl-radio-group label="Select an option">
-  <sl-radio-button name="a" value="1" checked>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button value="1">
     <sl-icon slot="prefix" name="archive"></sl-icon>
     Option 1
   </sl-radio-button>
 
-  <sl-radio-button name="a" value="2">
+  <sl-radio-button value="2">
     <sl-icon slot="suffix" name="bag"></sl-icon>
     Option 2
   </sl-radio-button>
 
-  <sl-radio-button name="a" value="3">
+  <sl-radio-button value="3">
     <sl-icon slot="prefix" name="gift"></sl-icon>
     <sl-icon slot="suffix" name="cart"></sl-icon>
     Option 3
@@ -234,18 +216,18 @@ Use the `prefix` and `suffix` slots to add icons.
 import { SlIcon, SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadioButton name="a" value="1" checked>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton value="1">
       <SlIcon slot="prefix" name="archive" />
       Option 1
     </SlRadioButton>
 
-    <SlRadioButton name="a" value="2">
+    <SlRadioButton value="2">
       <SlIcon slot="suffix" name="bag" />
       Option 2
     </SlRadioButton>
 
-    <SlRadioButton name="a" value="3">
+    <SlRadioButton value="3">
       <SlIcon slot="prefix" name="gift" />
       <SlIcon slot="suffix" name="cart" />
       Option 3
@@ -259,24 +241,24 @@ const App = () => (
 You can omit button labels and use icons instead. Make sure to set a `label` attribute on each icon so screen readers will announce each option correctly.
 
 ```html preview
-<sl-radio-group label="Select an option">
-  <sl-radio-button name="a" value="angry">
+<sl-radio-group label="Select an option" name="a" value="neutral">
+  <sl-radio-button value="angry">
     <sl-icon name="emoji-angry" label="Angry"></sl-icon>
   </sl-radio-button>
 
-  <sl-radio-button name="a" value="sad">
+  <sl-radio-button value="sad">
     <sl-icon name="emoji-frown" label="Sad"></sl-icon>
   </sl-radio-button>
 
-  <sl-radio-button name="a" value="neutral" checked>
+  <sl-radio-button value="neutral">
     <sl-icon name="emoji-neutral" label="Neutral"></sl-icon>
   </sl-radio-button>
 
-  <sl-radio-button name="a" value="happy">
+  <sl-radio-button value="happy">
     <sl-icon name="emoji-smile" label="Happy"></sl-icon>
   </sl-radio-button>
 
-  <sl-radio-button name="a" value="laughing">
+  <sl-radio-button value="laughing">
     <sl-icon name="emoji-laughing" label="Laughing"></sl-icon>
   </sl-radio-button>
 </sl-radio-group>
@@ -286,101 +268,28 @@ You can omit button labels and use icons instead. Make sure to set a `label` att
 import { SlIcon, SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadioButton name="a" value="angry">
+  <SlRadioGroup label="Select an option" name="a" value="neutral">
+    <SlRadioButton value="angry">
       <SlIcon name="emoji-angry" label="Angry" />
     </SlRadioButton>
 
-    <SlRadioButton name="a" value="sad">
+    <SlRadioButton value="sad">
       <SlIcon name="emoji-frown" label="Sad" />
     </SlRadioButton>
 
-    <SlRadioButton name="a" value="neutral" checked>
+    <SlRadioButton value="neutral">
       <SlIcon name="emoji-neutral" label="Neutral" />
     </SlRadioButton>
 
-    <SlRadioButton name="a" value="happy">
+    <SlRadioButton value="happy">
       <SlIcon name="emoji-smile" label="Happy" />
     </SlRadioButton>
 
-    <SlRadioButton name="a" value="laughing">
+    <SlRadioButton value="laughing">
       <SlIcon name="emoji-laughing" label="Laughing" />
     </SlRadioButton>
   </SlRadioGroup>
 );
 ```
 
-### Custom Validity
-
-Use the `setCustomValidity()` method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.
-
-```html preview
-<form class="custom-validity">
-  <sl-radio-group label="Select an option">
-    <sl-radio-button name="a" value="1" checked>Not me</sl-radio-button>
-    <sl-radio-button name="a" value="2">Me neither</sl-radio-button>
-    <sl-radio-button name="a" value="3">Choose me</sl-radio-button>
-  </sl-radio-group>
-  <br />
-  <sl-button type="submit" variant="primary">Submit</sl-button>
-</form>
-<script>
-  const form = document.querySelector('.custom-validity');
-  const radioButton = form.querySelectorAll('sl-radio-button')[2];
-  const errorMessage = 'You must choose this option';
-  // Set initial validity as soon as the element is defined
-  customElements.whenDefined('sl-radio-button').then(() => {
-    radioButton.setCustomValidity(errorMessage);
-  });
-  // Update validity when a selection is made
-  form.addEventListener('sl-change', () => {
-    const isValid = radioButton.checked;
-    radioButton.setCustomValidity(isValid ? '' : errorMessage);
-  });
-  // Handle form submit
-  form.addEventListener('submit', event => {
-    event.preventDefault();
-    alert('All fields are valid!');
-  });
-</script>
-```
-
-```jsx react
-import { useEffect, useRef } from 'react';
-import { SlButton, SlIcon, SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
-const App = () => {
-  const radio = useRef(null);
-  const errorMessage = 'You must choose this option';
-  function handleChange(event) {
-    radio.current.setCustomValidity(radio.current.checked ? '' : errorMessage);
-  }
-  function handleSubmit(event) {
-    event.preventDefault();
-    alert('All fields are valid!');
-  }
-  useEffect(() => {
-    radio.current.setCustomValidity(errorMessage);
-  }, []);
-  return (
-    <form class="custom-validity" onSubmit={handleSubmit}>
-      <SlRadioGroup label="Select an option">
-        <SlRadioButton name="a" value="1" checked onSlChange={handleChange}>
-          Not me
-        </SlRadioButton>
-        <SlRadioButton name="a" value="2" onSlChange={handleChange}>
-          Me neither
-        </SlRadioButton>
-        <SlRadioButton ref={radio} name="a" value="3" onSlChange={handleChange}>
-          Choose me
-        </SlRadioButton>
-      </SlRadioGroup>
-      <br />
-      <SlButton type="submit" variant="primary">
-        Submit
-      </SlButton>
-    </form>
-  );
-};
-```
-
 [component-metadata:sl-radio-button]

docs/components/radio-group.md

@@ -2,13 +2,11 @@
 
 [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
-<sl-radio-group label="Select an option">
-  <sl-radio name="option" value="1" checked>Option 1</sl-radio>
-  <sl-radio name="option" value="2">Option 2</sl-radio>
-  <sl-radio name="option" value="3">Option 3</sl-radio>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio value="1">Option 1</sl-radio>
+  <sl-radio value="2">Option 2</sl-radio>
+  <sl-radio value="3">Option 3</sl-radio>
 </sl-radio-group>
 ```
 
@@ -16,31 +14,25 @@ Radio groups are used to group multiple [radios](/components/radio) or [radio bu
 import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadio name="option" value="1" checked>
-      Option 1
-    </SlRadio>
-    <SlRadio name="option" value="2">
-      Option 2
-    </SlRadio>
-    <SlRadio name="option" value="3">
-      Option 3
-    </SlRadio>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadio value="1">Option 1</SlRadio>
+    <SlRadio value="2">Option 2</SlRadio>
+    <SlRadio value="3">Option 3</SlRadio>
   </SlRadioGroup>
 );
 ```
 
 ## Examples
 
-### Showing the Label
+### Help Text
 
-You can show the fieldset and legend that wraps the radio group using the `fieldset` attribute. If you don't use this option, you should still provide a label so screen readers announce the control correctly.
+Add descriptive help text to a radio group with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
 
 ```html preview
-<sl-radio-group label="Select an option" fieldset>
-  <sl-radio name="option" value="1" checked>Option 1</sl-radio>
-  <sl-radio name="option" value="2">Option 2</sl-radio>
-  <sl-radio name="option" value="3">Option 3</sl-radio>
+<sl-radio-group label="Select an option" help-text="Choose the most appropriate option." name="a" value="1">
+  <sl-radio value="1">Option 1</sl-radio>
+  <sl-radio value="2">Option 2</sl-radio>
+  <sl-radio value="3">Option 3</sl-radio>
 </sl-radio-group>
 ```
 
@@ -48,16 +40,10 @@ You can show the fieldset and legend that wraps the radio group using the `field
 import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option" fieldset>
-    <SlRadio name="option" value="1" checked>
-      Option 1
-    </SlRadio>
-    <SlRadio name="option" value="2">
-      Option 2
-    </SlRadio>
-    <SlRadio name="option" value="3">
-      Option 3
-    </SlRadio>
+  <SlRadioGroup label="Select an option" help-text="Choose the most appropriate option." name="a" value="1">
+    <SlRadio value="1">Option 1</SlRadio>
+    <SlRadio value="2">Option 2</SlRadio>
+    <SlRadio value="3">Option 3</SlRadio>
   </SlRadioGroup>
 );
 ```
@@ -67,10 +53,10 @@ const App = () => (
 [Radio buttons](/components/radio-button) offer an alternate way to display radio controls. In this case, an internal [button group](/components/button-group) is used to group the buttons into a single, cohesive control.
 
 ```html preview
-<sl-radio-group label="Select an option">
-  <sl-radio-button name="option" value="1" checked>Option 1</sl-radio-button>
-  <sl-radio-button name="option" value="2">Option 2</sl-radio-button>
-  <sl-radio-button name="option" value="3">Option 3</sl-radio-button>
+<sl-radio-group label="Select an option" help-text="Select an option that makes you proud." name="a" value="1">
+  <sl-radio-button value="1">Option 1</sl-radio-button>
+  <sl-radio-button value="2">Option 2</sl-radio-button>
+  <sl-radio-button value="3">Option 3</sl-radio-button>
 </sl-radio-group>
 ```
 
@@ -78,18 +64,169 @@ const App = () => (
 import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadioButton name="option" value="1" checked>
-      Option 1
-    </SlRadioButton>
-    <SlRadioButton name="option" value="2">
-      Option 2
-    </SlRadioButton>
-    <SlRadioButton name="option" value="3">
-      Option 3
-    </SlRadioButton>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton value="1">Option 1</SlRadioButton>
+    <SlRadioButton value="2">Option 2</SlRadioButton>
+    <SlRadioButton value="3">Option 3</SlRadioButton>
   </SlRadioGroup>
 );
 ```
 
+### Disabling Options
+
+Radios and radio buttons can be disabled by adding the `disabled` attribute to the respective options inside the radio group.
+
+```html preview
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio value="1">Option 1</sl-radio>
+  <sl-radio value="2" disabled>Option 2</sl-radio>
+  <sl-radio value="3">Option 3</sl-radio>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadio value="1">Option 1</SlRadio>
+    <SlRadio value="2" disabled>
+      Option 2
+    </SlRadio>
+    <SlRadio value="3">Option 3</SlRadio>
+  </SlRadioGroup>
+);
+```
+
+### Validation
+
+Setting the `required` attribute to make selecting an option mandatory. If a value has not been selected, it will prevent the form from submitting and display an error message.
+
+```html preview
+<form class="validation">
+  <sl-radio-group label="Select an option" name="a" required>
+    <sl-radio value="1">Option 1</sl-radio>
+    <sl-radio value="2">Option 2</sl-radio>
+    <sl-radio value="3">Option 3</sl-radio>
+  </sl-radio-group>
+  <br />
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+</form>
+
+<script>
+  const form = document.querySelector('.validation');
+
+  // Handle form submit
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    alert('All fields are valid!');
+  });
+</script>
+```
+
+```jsx react
+import { SlButton, SlIcon, SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+const App = () => {
+  function handleSubmit(event) {
+    event.preventDefault();
+    alert('All fields are valid!');
+  }
+
+  return (
+    <form class="custom-validity" onSubmit={handleSubmit}>
+      <SlRadioGroup label="Select an option" name="a" required onSlChange={handleChange}>
+        <SlRadio value="1">
+          Option 1
+        </SlRadio>
+        <SlRadiovalue="2">
+          Option 2
+        </SlRadio>
+        <SlRadio value="3">
+          Option 3
+        </SlRadio>
+      </SlRadioGroup>
+      <br />
+      <SlButton type="submit" variant="primary">
+        Submit
+      </SlButton>
+    </form>
+  );
+};
+```
+
+### Custom Validity
+
+Use the `setCustomValidity()` method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.
+
+```html preview
+<form class="custom-validity">
+  <sl-radio-group label="Select an option" name="a" value="1">
+    <sl-radio value="1">Not me</sl-radio>
+    <sl-radio value="2">Me neither</sl-radio>
+    <sl-radio value="3">Choose me</sl-radio>
+  </sl-radio-group>
+  <br />
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+</form>
+
+<script>
+  const form = document.querySelector('.custom-validity');
+  const radioGroup = form.querySelector('sl-radio-group');
+  const errorMessage = 'You must choose the last option';
+
+  // Set initial validity as soon as the element is defined
+  customElements.whenDefined('sl-radio-group').then(() => {
+    radioGroup.setCustomValidity(errorMessage);
+  });
+
+  // Update validity when a selection is made
+  form.addEventListener('sl-change', () => {
+    const isValid = radioGroup.value === '3';
+    radioGroup.setCustomValidity(isValid ? '' : errorMessage);
+  });
+
+  // Handle form submit
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    alert('All fields are valid!');
+  });
+</script>
+```
+
+```jsx react
+import { useEffect, useRef } from 'react';
+import { SlButton, SlIcon, SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+const App = () => {
+  const radioGroup = useRef(null);
+  const errorMessage = 'You must choose this option';
+
+  function handleChange() {
+    radioGroup.current.setCustomValidity(radioGroup.current.value === '3' ? '' : errorMessage);
+  }
+
+  function handleSubmit(event) {
+    event.preventDefault();
+    alert('All fields are valid!');
+  }
+
+  useEffect(() => {
+    radio.current.setCustomValidity(errorMessage);
+  }, []);
+
+  return (
+    <form class="custom-validity" onSubmit={handleSubmit}>
+      <SlRadioGroup ref={radioGroup} label="Select an option" name="a" value="1" onSlChange={handleChange}>
+        <SlRadio value="1">Not me</SlRadio>
+        <SlRadio value="2">Me neither</SlRadio>
+        <SlRadio value="3">Choose me</SlRadio>
+      </SlRadioGroup>
+      <br />
+      <SlButton type="submit" variant="primary">
+        Submit
+      </SlButton>
+    </form>
+  );
+};
+```
+
 [component-metadata:sl-radio-group]

docs/components/radio.md

@@ -2,15 +2,13 @@
 
 [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
-<sl-radio-group label="Select an option">
-  <sl-radio name="option" value="1" checked>Option 1</sl-radio>
-  <sl-radio name="option" value="2">Option 2</sl-radio>
-  <sl-radio name="option" value="3">Option 3</sl-radio>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio value="1">Option 1</sl-radio>
+  <sl-radio value="2">Option 2</sl-radio>
+  <sl-radio value="3">Option 3</sl-radio>
 </sl-radio-group>
 ```
 
@@ -18,16 +16,10 @@ Radios are designed to be used with [radio groups](/components/radio-group).
 import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadio name="option" value="1" checked>
-      Option 1
-    </SlRadio>
-    <SlRadio name="option" value="2">
-      Option 2
-    </SlRadio>
-    <SlRadio name="option" value="3">
-      Option 3
-    </SlRadio>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadio value="1">Option 1</SlRadio>
+    <SlRadio value="2">Option 2</SlRadio>
+    <SlRadio value="3">Option 3</SlRadio>
   </SlRadioGroup>
 );
 ```
@@ -36,15 +28,15 @@ const App = () => (
 
 ## Examples
 
-### Checked
+### Initial Value
 
-To set the initial checked state, use the `checked` attribute.
+To set the initial value and checked state, use the `value` attribute on the containing radio group.
 
 ```html preview
-<sl-radio-group label="Select an option">
-  <sl-radio name="option" value="1" checked>Option 1</sl-radio>
-  <sl-radio name="option" value="2">Option 2</sl-radio>
-  <sl-radio name="option" value="3">Option 3</sl-radio>
+<sl-radio-group label="Select an option" name="a" value="3">
+  <sl-radio value="1">Option 1</sl-radio>
+  <sl-radio value="2">Option 2</sl-radio>
+  <sl-radio value="3">Option 3</sl-radio>
 </sl-radio-group>
 ```
 
@@ -52,16 +44,10 @@ To set the initial checked state, use the `checked` attribute.
 import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadio name="option" value="1" checked>
-      Option 1
-    </SlRadio>
-    <SlRadio name="option" value="2">
-      Option 2
-    </SlRadio>
-    <SlRadio name="option" value="3">
-      Option 3
-    </SlRadio>
+  <SlRadioGroup label="Select an option" name="a" value="3">
+    <SlRadio value="1">Option 1</SlRadio>
+    <SlRadio value="2">Option 2</SlRadio>
+    <SlRadio value="3">Option 3</SlRadio>
   </SlRadioGroup>
 );
 ```
@@ -71,10 +57,10 @@ const App = () => (
 Use the `disabled` attribute to disable a radio.
 
 ```html preview
-<sl-radio-group label="Select an option">
-  <sl-radio name="option" value="1" checked>Option 1</sl-radio>
-  <sl-radio name="option" value="2">Option 2</sl-radio>
-  <sl-radio name="option" value="3" disabled>Option 3</sl-radio>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio value="1">Option 1</sl-radio>
+  <sl-radio value="2" disabled>Option 2</sl-radio>
+  <sl-radio value="3">Option 3</sl-radio>
 </sl-radio-group>
 ```
 
@@ -82,91 +68,38 @@ Use the `disabled` attribute to disable a radio.
 import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadio name="option" value="1" checked>
-      Option 1
-    </SlRadio>
-    <SlRadio name="option" value="2">
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadio value="1">Option 1</SlRadio>
+    <SlRadio value="2" disabled>
       Option 2
     </SlRadio>
-    <SlRadio name="option" value="3" disabled>
-      Option 3
-    </SlRadio>
+    <SlRadio value="3">Option 3</SlRadio>
   </SlRadioGroup>
 );
 ```
 
-### Custom Validity
+## Sizes
 
-Use the `setCustomValidity()` method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.
+Use the `size` attribute to change a radio's size.
 
 ```html preview
-<form class="custom-validity">
-  <sl-radio-group label="Select an option">
-    <sl-radio name="a" value="1" checked>Not me</sl-radio>
-    <sl-radio name="a" value="2">Me neither</sl-radio>
-    <sl-radio name="a" value="3">Choose me</sl-radio>
-  </sl-radio-group>
-  <br />
-  <sl-button type="submit" variant="primary">Submit</sl-button>
-</form>
-<script>
-  const form = document.querySelector('.custom-validity');
-  const radio = form.querySelectorAll('sl-radio')[2];
-  const errorMessage = 'You must choose this option';
-  // Set initial validity as soon as the element is defined
-  customElements.whenDefined('sl-radio').then(() => {
-    radio.setCustomValidity(errorMessage);
-  });
-  // Update validity when a selection is made
-  form.addEventListener('sl-change', () => {
-    const isValid = radio.checked;
-    radio.setCustomValidity(isValid ? '' : errorMessage);
-  });
-  // Handle form submit
-  form.addEventListener('submit', event => {
-    event.preventDefault();
-    alert('All fields are valid!');
-  });
-</script>
+<sl-radio size="small">Small</sl-radio>
+<sl-radio size="medium">Medium</sl-radio>
+<sl-radio size="large">Large</sl-radio>
 ```
 
 ```jsx react
-import { useEffect, useRef } from 'react';
-import { SlButton, SlIcon, SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
-const App = () => {
-  const radio = useRef(null);
-  const errorMessage = 'You must choose this option';
-  function handleChange(event) {
-    radio.current.setCustomValidity(radio.current.checked ? '' : errorMessage);
-  }
-  function handleSubmit(event) {
-    event.preventDefault();
-    alert('All fields are valid!');
-  }
-  useEffect(() => {
-    radio.current.setCustomValidity(errorMessage);
-  }, []);
-  return (
-    <form class="custom-validity" onSubmit={handleSubmit}>
-      <SlRadioGroup label="Select an option">
-        <SlRadio name="a" value="1" checked onSlChange={handleChange}>
-          Not me
-        </SlRadio>
-        <SlRadio name="a" value="2" onSlChange={handleChange}>
-          Me neither
-        </SlRadio>
-        <SlRadio ref={radio} name="a" value="3" onSlChange={handleChange}>
-          Choose me
-        </SlRadio>
-      </SlRadioGroup>
-      <br />
-      <SlButton type="submit" variant="primary">
-        Submit
-      </SlButton>
-    </form>
-  );
-};
+import { SlRadio } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlRadio size="small">Small</SlRadio>
+    <br />
+    <SlRadio size="medium">Medium</SlRadio>
+    <br />
+    <SlRadio size="large">Large</SlRadio>
+  </>
+);
 ```
 
 [component-metadata:sl-radio]

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
 <sl-range></sl-range>
 ```
@@ -23,7 +21,7 @@ const App = () => <SlRange />;
 Use the `label` attribute to give the range an accessible label. For labels that contain HTML, use the `label` slot instead.
 
 ```html preview
-<sl-range label="Volume" min="0" max="100"></sl-input>
+<sl-range label="Volume" min="0" max="100"></sl-range>
 ```
 
 ```jsx react
@@ -37,12 +35,7 @@ const App = () => <SlRange label="Volume" min={0} max={100} />;
 Add descriptive help text to a range with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
 
 ```html preview
-<sl-range
-  label="Volume"
-  help-text="Controls the volume of the current song."
-  min="0"
-  max="100"
-></sl-input>
+<sl-range label="Volume" help-text="Controls the volume of the current song." min="0" max="100"></sl-range>
 ```
 
 ```jsx react

docs/components/rating.md

@@ -2,32 +2,44 @@
 
 [component-header:sl-rating]
 
-Ratings give users a way to quickly view and provide feedback.
-
 ```html preview
-<sl-rating></sl-rating>
+<sl-rating label="Rating"></sl-rating>
 ```
 
 ```jsx react
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => <SlRating />;
+const App = () => <SlRating label="Rating" />;
 ```
 
 ## Examples
 
+### Labels
+
+Ratings are commonly identified contextually, so labels aren't displayed. However, you should always provide one for assistive devices using the `label` attribute.
+
+```html preview
+<sl-rating label="Rate this component"></sl-rating>
+```
+
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => <SlRating label="Rate this component" />;
+```
+
 ### Maximum Value
 
 Ratings are 0-5 by default. To change the maximum possible value, use the `max` attribute.
 
 ```html preview
-<sl-rating max="3"></sl-rating>
+<sl-rating label="Rating" max="3"></sl-rating>
 ```
 
 ```jsx react
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => <SlRating max={3} />;
+const App = () => <SlRating label="Rating" max={3} />;
 ```
 
 ### Precision
@@ -35,27 +47,27 @@ const App = () => <SlRating max={3} />;
 Use the `precision` attribute to let users select fractional ratings.
 
 ```html preview
-<sl-rating precision="0.5" value="2.5"></sl-rating>
+<sl-rating label="Rating" precision="0.5" value="2.5"></sl-rating>
 ```
 
 ```jsx react
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => <SlRating precision={0.5} value={2.5} />;
+const App = () => <SlRating label="Rating" precision={0.5} value={2.5} />;
 ```
 
-## Symbol Sizes
+### Symbol Sizes
 
 Set the `--symbol-size` custom property to adjust the size.
 
 ```html preview
-<sl-rating style="--symbol-size: 2rem;"></sl-rating>
+<sl-rating label="Rating" style="--symbol-size: 2rem;"></sl-rating>
 ```
 
 ```jsx react
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => <SlRating style={{ '--symbol-size': '2rem' }} />;
+const App = () => <SlRating label="Rating" style={{ '--symbol-size': '2rem' }} />;
 ```
 
 ### Readonly
@@ -63,13 +75,13 @@ const App = () => <SlRating style={{ '--symbol-size': '2rem' }} />;
 Use the `readonly` attribute to display a rating that users can't change.
 
 ```html preview
-<sl-rating readonly value="3"></sl-rating>
+<sl-rating label="Rating" readonly value="3"></sl-rating>
 ```
 
 ```jsx react
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => <SlRating readonly value={3} />;
+const App = () => <SlRating label="Rating" readonly value={3} />;
 ```
 
 ### Disabled
@@ -77,13 +89,106 @@ const App = () => <SlRating readonly value={3} />;
 Use the `disable` attribute to disable the rating.
 
 ```html preview
-<sl-rating disabled value="3"></sl-rating>
+<sl-rating label="Rating" disabled value="3"></sl-rating>
 ```
 
 ```jsx react
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => <SlRating disabled value={3} />;
+const App = () => <SlRating label="Rating" disabled value={3} />;
+```
+
+### Detecting Hover
+
+Use the `sl-hover` event to detect when the user hovers over (or touch and drag) the rating. This lets you hook into values as the user interacts with the rating, but before they select a value.
+
+The event has a payload with `phase` and `value` properties. The `phase` property tells when hovering starts, moves to a new value, and ends. The `value` property tells what the rating's value would be if the user were to commit to the hovered value.
+
+```html preview
+<div class="detect-hover">
+  <sl-rating label="Rating"></sl-rating>
+  <span></span>
+</div>
+
+<script>
+  const rating = document.querySelector('.detect-hover > sl-rating');
+  const span = rating.nextElementSibling;
+  const terms = ['No rating', 'Terrible', 'Bad', 'OK', 'Good', 'Excellent'];
+
+  rating.addEventListener('sl-hover', event => {
+    span.textContent = terms[event.detail.value];
+
+    // Clear feedback when hovering stops
+    if (event.detail.phase === 'end') {
+      span.textContent = '';
+    }
+  });
+</script>
+
+<style>
+  .detect-hover span {
+    position: relative;
+    top: -4px;
+    left: 8px;
+    border-radius: var(--sl-border-radius-small);
+    background: var(--sl-color-neutral-900);
+    color: var(--sl-color-neutral-0);
+    text-align: center;
+    padding: 4px 6px;
+  }
+
+  .detect-hover span:empty {
+    display: none;
+  }
+</style>
+```
+
+```jsx react
+import { useState } from 'react';
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
+
+const terms = ['No rating', 'Terrible', 'Bad', 'OK', 'Good', 'Excellent'];
+const css = `
+  .detect-hover span {
+    position: relative;
+    top: -4px;
+    left: 8px;
+    border-radius: var(--sl-border-radius-small);
+    background: var(--sl-color-neutral-900);
+    color: var(--sl-color-neutral-0);
+    text-align: center;
+    padding: 4px 6px;
+  }
+
+  .detect-hover span:empty {
+    display: none;
+  }
+`;
+
+function handleHover(event) {
+  rating.addEventListener('sl-hover', event => {
+    setFeedback(terms[event.detail.value]);
+
+    // Clear feedback when hovering stops
+    if (event.detail.phase === 'end') {
+      setFeedback('');
+    }
+  });
+}
+
+const App = () => {
+  const [feedback, setFeedback] = useState(true);
+
+  return (
+    <>
+      <div class="detect-hover">
+        <SlRating label="Rating" onSlHover={handleHover} />
+        <span>{feedback}</span>
+      </div>
+      <style>{css}</style>
+    </>
+  );
+};
 ```
 
 ### Custom Icons
@@ -91,7 +196,7 @@ const App = () => <SlRating disabled value={3} />;
 You can provide custom icons by passing a function to the `getSymbol` property.
 
 ```html preview
-<sl-rating class="rating-hearts" style="--symbol-color-active: #ff4136;"></sl-rating>
+<sl-rating label="Rating" class="rating-hearts" style="--symbol-color-active: #ff4136;"></sl-rating>
 
 <script>
   const rating = document.querySelector('.rating-hearts');
@@ -100,11 +205,14 @@ You can provide custom icons by passing a function to the `getSymbol` property.
 ```
 
 ```jsx react
-import '@shoelace-style/shoelace/dist/components/icon/icon';
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRating getSymbol={() => '<sl-icon name="heart-fill"></sl-icon>'} style={{ '--symbol-color-active': '#ff4136' }} />
+  <SlRating
+    label="Rating"
+    getSymbol={() => '<sl-icon name="heart-fill"></sl-icon>'}
+    style={{ '--symbol-color-active': '#ff4136' }}
+  />
 );
 ```
 
@@ -113,7 +221,7 @@ const App = () => (
 You can also use the `getSymbol` property to render different icons based on value.
 
 ```html preview
-<sl-rating class="rating-emojis"></sl-rating>
+<sl-rating label="Rating" class="rating-emojis"></sl-rating>
 
 <script>
   const rating = document.querySelector('.rating-emojis');
@@ -126,7 +234,6 @@ You can also use the `getSymbol` property to render different icons based on val
 ```
 
 ```jsx react
-import '@shoelace-style/shoelace/dist/components/icon/icon';
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 function getSymbol(value) {
@@ -134,7 +241,7 @@ function getSymbol(value) {
   return `<sl-icon name="${icons[value - 1]}"></sl-icon>`;
 }
 
-const App = () => <SlRating getSymbol={getSymbol} />;
+const App = () => <SlRating label="Rating" getSymbol={getSymbol} />;
 ```
 
 [component-metadata:sl-rating]

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
@@ -21,8 +19,6 @@ The `date` attribute determines when the date/time is calculated from. It must b
 
 ?> When using strings, avoid ambiguous dates such as `03/04/2020` which can be interpreted as March 4 or April 3 depending on the user's browser and locale. Instead, always use a valid [ISO 8601 date time string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse#Date_Time_String_Format) to ensure the date will be parsed properly by all clients.
 
-!> The `Intl.RelativeTimeFormat` API is available [in all major browsers](https://caniuse.com/mdn-javascript_builtins_intl_relativetimeformat), but it only became available to Safari in version 14. If you need to support Safari 13, you'll need to [use a polyfill](https://github.com/catamphetamine/relative-time-format).
-
 ## Examples
 
 ### Keeping Time in Sync

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

docs/components/responsive-media.md

@@ -1,91 +0,0 @@
-# Responsive Media
-
-[component-header:sl-responsive-media]
-
-Displays media in the desired aspect ratio.
-
-You can slot in any [replaced element](https://developer.mozilla.org/en-US/docs/Web/CSS/Replaced_element), including `<iframe>`, `<img>`, and `<video>`. As the element's width changes, its height will resize proportionally. Only one element should be slotted into the container. The default aspect ratio is `16:9`.
-
-```html preview
-<sl-responsive-media>
-  <img
-    src="https://images.unsplash.com/photo-1541427468627-a89a96e5ca1d?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1800&q=80"
-    alt="A train riding through autumn foliage with mountains in the distance."
-  />
-</sl-responsive-media>
-```
-
-```jsx react
-import { SlResponsiveMedia } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlResponsiveMedia>
-    <img
-      src="https://images.unsplash.com/photo-1541427468627-a89a96e5ca1d?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1800&q=80"
-      alt="A train riding through autumn foliage with mountains in the distance."
-    />
-  </SlResponsiveMedia>
-);
-```
-
-## Examples
-
-### Responsive Images
-
-The following image maintains a `4:3` aspect ratio as its container is resized.
-
-```html preview
-<sl-responsive-media aspect-ratio="4:3">
-  <img
-    src="https://images.unsplash.com/photo-1473186578172-c141e6798cf4?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1800&q=80"
-    alt="Two blue chairs on a sandy beach."
-  />
-</sl-responsive-media>
-```
-
-```jsx react
-import { SlResponsiveMedia } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlResponsiveMedia aspect-ratio="4:3">
-    <img
-      src="https://images.unsplash.com/photo-1473186578172-c141e6798cf4?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1800&q=80"
-      alt="Two blue chairs on a sandy beach."
-    />
-  </SlResponsiveMedia>
-);
-```
-
-### Responsive Videos
-
-The following video is embedded using an `iframe` and maintains a `16:9` aspect ratio as its container is resized.
-
-```html preview
-<sl-responsive-media aspect-ratio="16:9">
-  <iframe
-    title="Video of the kittens"
-    src="https://player.vimeo.com/video/1053647?title=0&byline=0&portrait=0"
-    frameborder="0"
-    allow="autoplay; fullscreen"
-    allowfullscreen
-  ></iframe>
-</sl-responsive-media>
-```
-
-```jsx react
-import { SlResponsiveMedia } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlResponsiveMedia aspect-ratio="16:9">
-    <iframe
-      title="Video of the kittens"
-      src="https://player.vimeo.com/video/1053647?title=0&byline=0&portrait=0"
-      frameborder="0"
-      allow="autoplay; fullscreen"
-      allowfullscreen
-    />
-  </SlResponsiveMedia>
-);
-```
-
-[component-metadata:sl-responsive-media]

docs/components/select.md

@@ -2,32 +2,28 @@
 
 [component-header:sl-select]
 
-Selects allow you to choose one or more items from a dropdown menu.
-
 ```html preview
 <sl-select>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
-  <sl-divider></sl-divider>
-  <sl-menu-item value="option-4">Option 4</sl-menu-item>
-  <sl-menu-item value="option-5">Option 5</sl-menu-item>
-  <sl-menu-item value="option-6">Option 6</sl-menu-item>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+  <sl-option value="option-4">Option 4</sl-option>
+  <sl-option value="option-5">Option 5</sl-option>
+  <sl-option value="option-6">Option 6</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlDivider, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
-    <SlDivider />
-    <SlMenuItem value="option-4">Option 4</SlMenuItem>
-    <SlMenuItem value="option-5">Option 5</SlMenuItem>
-    <SlMenuItem value="option-6">Option 6</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+    <SlOption value="option-4">Option 4</SlOption>
+    <SlOption value="option-5">Option 5</SlOption>
+    <SlOption value="option-6">Option 6</SlOption>
   </SlSelect>
 );
 ```
@@ -42,20 +38,20 @@ Use the `label` attribute to give the select an accessible label. For labels tha
 
 ```html preview
 <sl-select label="Select one">
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect label="Select one">
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
   </SlSelect>
 );
 ```
@@ -66,20 +62,20 @@ Add descriptive help text to a select with the `help-text` attribute. For help t
 
 ```html preview
 <sl-select label="Experience" help-text="Please tell us your skill level.">
-  <sl-menu-item value="1">Novice</sl-menu-item>
-  <sl-menu-item value="2">Intermediate</sl-menu-item>
-  <sl-menu-item value="3">Advanced</sl-menu-item>
+  <sl-option value="1">Novice</sl-option>
+  <sl-option value="2">Intermediate</sl-option>
+  <sl-option value="3">Advanced</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect label="Experience" help-text="Please tell us your skill level.">
-    <SlMenuItem value="1">Novice</SlMenuItem>
-    <SlMenuItem value="2">Intermediate</SlMenuItem>
-    <SlMenuItem value="3">Advanced</SlMenuItem>
+    <SlOption value="1">Novice</SlOption>
+    <SlOption value="2">Intermediate</SlOption>
+    <SlOption value="3">Advanced</SlOption>
   </SlSelect>
 );
 ```
@@ -90,44 +86,44 @@ Use the `placeholder` attribute to add a placeholder.
 
 ```html preview
 <sl-select placeholder="Select one">
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect placeholder="Select one">
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
   </SlSelect>
 );
 ```
 
 ### Clearable
 
-Use the `clearable` attribute to make the control clearable.
+Use the `clearable` attribute to make the control clearable. The clear button only appears when an option is selected.
 
 ```html preview
-<sl-select placeholder="Clearable" clearable>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+<sl-select clearable value="option-1">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect placeholder="Clearable" clearable>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
   </SlSelect>
 );
 ```
@@ -138,20 +134,20 @@ Add the `filled` attribute to draw a filled select.
 
 ```html preview
 <sl-select filled>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect filled>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
   </SlSelect>
 );
 ```
@@ -162,20 +158,20 @@ Use the `pill` attribute to give selects rounded edges.
 
 ```html preview
 <sl-select pill>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect pill>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
   </SlSelect>
 );
 ```
@@ -186,227 +182,167 @@ Use the `disabled` attribute to disable a select.
 
 ```html preview
 <sl-select placeholder="Disabled" disabled>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect placeholder="Disabled" disabled>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
   </SlSelect>
 );
 ```
 
-### Setting the Selection
-
-Use the `value` attribute to set the current selection. When users interact with the control, its `value` will update to reflect the newly selected menu item's value. Note that the value must be an array when using the [`multiple`](#multiple) option.
-
-```html preview
-<sl-select value="option-2">
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
-</sl-select>
-```
-
-```jsx react
-import { SlDivider, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlSelect value="option-2">
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
-  </SlSelect>
-);
-```
-
-### Setting the Selection Imperatively
-
-To programmatically set the selection, update the `value` property as shown below. Note that the value must be an array when using the [`multiple`](#multiple) option.
-
-```html preview
-<div class="selecting-example">
-  <sl-select>
-    <sl-menu-item value="option-1">Option 1</sl-menu-item>
-    <sl-menu-item value="option-2">Option 2</sl-menu-item>
-    <sl-menu-item value="option-3">Option 3</sl-menu-item>
-  </sl-select>
-
-  <br />
-
-  <sl-button data-option="option-1">Set 1</sl-button>
-  <sl-button data-option="option-2">Set 2</sl-button>
-  <sl-button data-option="option-3">Set 3</sl-button>
-</div>
-
-<script>
-  const container = document.querySelector('.selecting-example');
-  const select = container.querySelector('sl-select');
-
-  [...container.querySelectorAll('sl-button')].map(button => {
-    button.addEventListener('click', () => {
-      select.value = button.dataset.option;
-    });
-  });
-</script>
-```
-
-```jsx react
-import { useState } from 'react';
-import { SlButton, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => {
-  const [value, setValue] = useState('option-1');
-
-  return (
-    <>
-      <SlSelect value={value} onSlChange={event => setValue(event.target.value)}>
-        <SlMenuItem value="option-1">Option 1</SlMenuItem>
-        <SlMenuItem value="option-2">Option 2</SlMenuItem>
-        <SlMenuItem value="option-3">Option 3</SlMenuItem>
-      </SlSelect>
-
-      <br />
-
-      <SlButton onClick={() => setValue('option-1')}>Set 1</SlButton>
-      <SlButton onClick={() => setValue('option-2')}>Set 2</SlButton>
-      <SlButton onClick={() => setValue('option-3')}>Set 3</SlButton>
-    </>
-  );
-};
-```
-
 ### Multiple
 
-To allow multiple options to be selected, use the `multiple` attribute. With this option, `value` will be an array of strings instead of a string. It's a good practice to use `clearable` when this option is enabled.
+To allow multiple options to be selected, use the `multiple` attribute. It's a good practice to use `clearable` when this option is enabled. To set multiple values at once, set `value` to a space-delimited list of values.
 
 ```html preview
-<sl-select placeholder="Select a few" multiple clearable>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
-  <sl-divider></sl-divider>
-  <sl-menu-item value="option-4">Option 4</sl-menu-item>
-  <sl-menu-item value="option-5">Option 5</sl-menu-item>
-  <sl-menu-item value="option-6">Option 6</sl-menu-item>
+<sl-select label="Select a Few" value="option-1 option-2 option-3" multiple clearable>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+  <sl-option value="option-4">Option 4</sl-option>
+  <sl-option value="option-5">Option 5</sl-option>
+  <sl-option value="option-6">Option 6</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlDivider, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlSelect placeholder="Select a few" multiple clearable>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
-    <SlDivider />
-    <SlMenuItem value="option-4">Option 4</SlMenuItem>
-    <SlMenuItem value="option-5">Option 5</SlMenuItem>
-    <SlMenuItem value="option-6">Option 6</SlMenuItem>
+  <SlSelect label="Select a Few" value="option-1 option-2 option-3" multiple clearable>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+    <SlOption value="option-4">Option 4</SlOption>
+    <SlOption value="option-5">Option 5</SlOption>
+    <SlOption value="option-6">Option 6</SlOption>
   </SlSelect>
 );
 ```
 
-?> When using the `multiple` option, the value will be an array instead of a string. You may need to [set the selection imperatively](#setting-the-selection-imperatively) unless you're using a framework that supports binding properties declaratively.
+?> Note that multi-select options may wrap, causing the control to expand vertically. You can use the `max-options-visible` attribute to control the maximum number of selected options to show at once.
 
-### Grouping Options
+### Setting Initial Values
 
-Options can be grouped visually using menu labels and dividers.
+Use the `value` attribute to set the initial selection. When using `multiple`, use space-delimited values to select more than one option.
 
 ```html preview
-<sl-select placeholder="Select one">
-  <sl-menu-label>Group 1</sl-menu-label>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
-  <sl-divider></sl-divider>
-  <sl-menu-label>Group 2</sl-menu-label>
-  <sl-menu-item value="option-4">Option 4</sl-menu-item>
-  <sl-menu-item value="option-5">Option 5</sl-menu-item>
-  <sl-menu-item value="option-6">Option 6</sl-menu-item>
+<sl-select value="option-1 option-2" multiple clearable>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+  <sl-option value="option-4">Option 4</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlDivider, SlMenuItem, SlMenuLabel, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlDivider, SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlSelect placeholder="Select one">
-    <SlMenuLabel>Group 1</SlMenuLabel>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
-    <SlDivider></SlDivider>
-    <SlMenuLabel>Group 2</SlMenuLabel>
-    <SlMenuItem value="option-4">Option 4</SlMenuItem>
-    <SlMenuItem value="option-5">Option 5</SlMenuItem>
-    <SlMenuItem value="option-6">Option 6</SlMenuItem>
+  <SlSelect value="option-1 option-2" multiple clearable>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+  </SlSelect>
+);
+```
+
+### Grouping Options
+
+Use `<sl-divider>` to group listbox items visually. You can also use `<small>` to provide labels, but they won't be announced by most assistive devices.
+
+```html preview
+<sl-select>
+  <small>Section 1</small>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+  <sl-divider></sl-divider>
+  <small>Section 2</small>
+  <sl-option value="option-4">Option 4</sl-option>
+  <sl-option value="option-5">Option 5</sl-option>
+  <sl-option value="option-6">Option 6</sl-option>
+</sl-select>
+```
+
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSelect>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+    <SlOption value="option-4">Option 4</SlOption>
+    <SlOption value="option-5">Option 5</SlOption>
+    <SlOption value="option-6">Option 6</SlOption>
   </SlSelect>
 );
 ```
 
 ### Sizes
 
-Use the `size` attribute to change a select's size.
+Use the `size` attribute to change a select's size. Note that size does not apply to listbox options.
 
 ```html preview
-<sl-select placeholder="Small" size="small" multiple>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+<sl-select placeholder="Small" size="small">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 
 <br />
 
-<sl-select placeholder="Medium" size="medium" multiple>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+<sl-select placeholder="Medium" size="medium">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 
 <br />
 
-<sl-select placeholder="Large" size="large" multiple>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+<sl-select placeholder="Large" size="large">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlSelect placeholder="Small" size="small" multiple>
-      <SlMenuItem value="option-1">Option 1</SlMenuItem>
-      <SlMenuItem value="option-2">Option 2</SlMenuItem>
-      <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlSelect placeholder="Small" size="small">
+      <SlOption value="option-1">Option 1</SlOption>
+      <SlOption value="option-2">Option 2</SlOption>
+      <SlOption value="option-3">Option 3</SlOption>
     </SlSelect>
 
     <br />
 
-    <SlSelect placeholder="Medium" size="medium" multiple>
-      <SlMenuItem value="option-1">Option 1</SlMenuItem>
-      <SlMenuItem value="option-2">Option 2</SlMenuItem>
-      <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlSelect placeholder="Medium" size="medium">
+      <SlOption value="option-1">Option 1</SlOption>
+      <SlOption value="option-2">Option 2</SlOption>
+      <SlOption value="option-3">Option 3</SlOption>
     </SlSelect>
 
     <br />
 
-    <SlSelect placeholder="Large" size="large" multiple>
-      <SlMenuItem value="option-1">Option 1</SlMenuItem>
-      <SlMenuItem value="option-2">Option 2</SlMenuItem>
-      <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlSelect placeholder="Large" size="large">
+      <SlOption value="option-1">Option 1</SlOption>
+      <SlOption value="option-2">Option 2</SlOption>
+      <SlOption value="option-3">Option 3</SlOption>
     </SlSelect>
   </>
 );
@@ -414,88 +350,82 @@ const App = () => (
 
 ### Placement
 
-The preferred placement of the select's menu can be set with the `placement` attribute. Note that the actual position may vary to ensure the panel remains in the viewport. Valid placements are `top` and `bottom`.
+The preferred placement of the select's listbox can be set with the `placement` attribute. Note that the actual position may vary to ensure the panel remains in the viewport. Valid placements are `top` and `bottom`.
 
 ```html preview
 <sl-select placement="top">
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
 import {
-  SlMenuItem,
+  SlOption,
   SlSelect
 } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect placement="top">
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
   </SlDropdown>
 );
 ```
 
-### Prefix & Suffix Icons
+### Prefix Icons
 
-Use the `prefix` and `suffix` slots to add icons.
+Use the `prefix` slot to prepend an icon to the control.
 
 ```html preview
-<sl-select placeholder="Small" size="small">
+<sl-select placeholder="Small" size="small" clearable>
   <sl-icon name="house" slot="prefix"></sl-icon>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
-  <sl-icon name="chat" slot="suffix"></sl-icon>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 <br />
-<sl-select placeholder="Medium" size="medium">
+<sl-select placeholder="Medium" size="medium" clearable>
   <sl-icon name="house" slot="prefix"></sl-icon>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
-  <sl-icon name="chat" slot="suffix"></sl-icon>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 <br />
-<sl-select placeholder="Large" size="large">
+<sl-select placeholder="Large" size="large" clearable>
   <sl-icon name="house" slot="prefix"></sl-icon>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
-  <sl-icon name="chat" slot="suffix"></sl-icon>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlIcon, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlIcon, SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
     <SlSelect placeholder="Small" size="small">
       <SlIcon name="house" slot="prefix"></SlIcon>
-      <SlMenuItem value="option-1">Option 1</SlMenuItem>
-      <SlMenuItem value="option-2">Option 2</SlMenuItem>
-      <SlMenuItem value="option-3">Option 3</SlMenuItem>
-      <SlIcon name="chat" slot="suffix"></SlIcon>
+      <SlOption value="option-1">Option 1</SlOption>
+      <SlOption value="option-2">Option 2</SlOption>
+      <SlOption value="option-3">Option 3</SlOption>
     </SlSelect>
     <br />
     <SlSelect placeholder="Medium" size="medium">
       <SlIcon name="house" slot="prefix"></SlIcon>
-      <SlMenuItem value="option-1">Option 1</SlMenuItem>
-      <SlMenuItem value="option-2">Option 2</SlMenuItem>
-      <SlMenuItem value="option-3">Option 3</SlMenuItem>
-      <SlIcon name="chat" slot="suffix"></SlIcon>
+      <SlOption value="option-1">Option 1</SlOption>
+      <SlOption value="option-2">Option 2</SlOption>
+      <SlOption value="option-3">Option 3</SlOption>
     </SlSelect>
     <br />
     <SlSelect placeholder="Large" size="large">
       <SlIcon name="house" slot="prefix"></SlIcon>
-      <SlMenuItem value="option-1">Option 1</SlMenuItem>
-      <SlMenuItem value="option-2">Option 2</SlMenuItem>
-      <SlMenuItem value="option-3">Option 3</SlMenuItem>
-      <SlIcon name="chat" slot="suffix"></SlIcon>
+      <SlOption value="option-1">Option 1</SlOption>
+      <SlOption value="option-2">Option 2</SlOption>
+      <SlOption value="option-3">Option 3</SlOption>
     </SlSelect>
   </>
 );

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.

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
 <sl-spinner></sl-spinner>
 ```

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
 <sl-split-panel>
   <div
@@ -381,9 +379,9 @@ Try resizing the example below with each option and notice how the panels respon
   </sl-split-panel>
 
   <sl-select label="Primary Panel" value="" style="max-width: 200px; margin-top: 1rem;">
-    <sl-menu-item value="">None</sl-menu-item>
-    <sl-menu-item value="start">Start</sl-menu-item>
-    <sl-menu-item value="end">End</sl-menu-item>
+    <sl-option value="">None</sl-option>
+    <sl-option value="start">Start</sl-option>
+    <sl-option value="end">End</sl-option>
   </sl-select>
 </div>
 
@@ -585,11 +583,11 @@ const App = () => (
 
 ### Customizing the Divider
 
-You can target the `divider` part to apply CSS properties to the divider. To add a handle, slot an icon or another element into the `handle` slot. When customizing the divider, make sure to think about focus styles for keyboard users.
+You can target the `divider` part to apply CSS properties to the divider. To add a custom handle, slot an icon into the `divider` slot. When customizing the divider, make sure to think about focus styles for keyboard users.
 
 ```html preview
 <sl-split-panel style="--divider-width: 20px;">
-  <sl-icon slot="handle" name="grip-vertical"></sl-icon>
+  <sl-icon slot="divider" name="grip-vertical"></sl-icon>
   <div
     slot="start"
     style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
@@ -610,7 +608,7 @@ import { SlSplitPanel, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSplitPanel style={{ '--divider-width': '20px' }}>
-    <SlIcon slot="handle" name="grip-vertical" />
+    <SlIcon slot="divider" name="grip-vertical" />
     <div
       slot="start"
       style={{
@@ -642,9 +640,9 @@ const App = () => (
 Here's a more elaborate example that changes the divider's color and width and adds a styled handle.
 
 ```html preview
-<div class="split-panel-handle">
+<div class="split-panel-divider">
   <sl-split-panel>
-    <sl-icon slot="handle" name="grip-vertical"></sl-icon>
+    <sl-icon slot="divider" name="grip-vertical"></sl-icon>
     <div
       slot="start"
       style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
@@ -661,15 +659,15 @@ Here's a more elaborate example that changes the divider's color and width and a
 </div>
 
 <style>
-  .split-panel-handle sl-split-panel {
+  .split-panel-divider sl-split-panel {
     --divider-width: 2px;
   }
 
-  .split-panel-handle sl-split-panel::part(divider) {
+  .split-panel-divider sl-split-panel::part(divider) {
     background-color: var(--sl-color-pink-600);
   }
 
-  .split-panel-handle sl-icon {
+  .split-panel-divider sl-icon {
     position: absolute;
     border-radius: var(--sl-border-radius-small);
     background: var(--sl-color-pink-600);
@@ -677,11 +675,11 @@ Here's a more elaborate example that changes the divider's color and width and a
     padding: 0.5rem 0.125rem;
   }
 
-  .split-panel-handle sl-split-panel::part(divider):focus-visible {
+  .split-panel-divider sl-split-panel::part(divider):focus-visible {
     background-color: var(--sl-color-primary-600);
   }
 
-  .split-panel-handle sl-split-panel:focus-within sl-icon {
+  .split-panel-divider sl-split-panel:focus-within sl-icon {
     background-color: var(--sl-color-primary-600);
     color: var(--sl-color-neutral-0);
   }
@@ -692,15 +690,15 @@ Here's a more elaborate example that changes the divider's color and width and a
 import { SlSplitPanel, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
-  .split-panel-handle sl-split-panel {
+  .split-panel-divider sl-split-panel {
     --divider-width: 2px;
   }
 
-  .split-panel-handle sl-split-panel::part(divider) {
+  .split-panel-divider sl-split-panel::part(divider) {
     background-color: var(--sl-color-pink-600);
   }
 
-  .split-panel-handle sl-icon {
+  .split-panel-divider sl-icon {
     position: absolute;
     border-radius: var(--sl-border-radius-small);
     background: var(--sl-color-pink-600);
@@ -708,11 +706,11 @@ const css = `
     padding: .5rem .125rem;
   }
 
-  .split-panel-handle sl-split-panel::part(divider):focus-visible {
+  .split-panel-divider sl-split-panel::part(divider):focus-visible {
     background-color: var(--sl-color-primary-600);
   }
 
-  .split-panel-handle sl-split-panel:focus-within sl-icon {
+  .split-panel-divider sl-split-panel:focus-within sl-icon {
     background-color: var(--sl-color-primary-600);
     color: var(--sl-color-neutral-0);
   }
@@ -720,9 +718,9 @@ const css = `
 
 const App = () => (
   <>
-    <div className="split-panel-handle">
+    <div className="split-panel-divider">
       <SlSplitPanel>
-        <SlIcon slot="handle" name="grip-vertical" />
+        <SlIcon slot="divider" name="grip-vertical" />
         <div
           slot="start"
           style={{

docs/components/switch.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-switch]
 
-Switches allow the user to toggle an option on or off.
-
 ```html preview
 <sl-switch>Switch</sl-switch>
 ```
@@ -46,12 +44,38 @@ import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
 const App = () => <SlSwitch disabled>Disabled</SlSwitch>;
 ```
 
-### Custom Size
+## Sizes
 
-Use the available custom properties to make the switch a different size.
+Use the `size` attribute to change a switch's size.
 
 ```html preview
-<sl-switch style="--width: 80px; --height: 32px; --thumb-size: 26px;">Really big</sl-switch>
+<sl-switch size="small">Small</sl-switch>
+<br />
+<sl-switch size="medium">Medium</sl-switch>
+<br />
+<sl-switch size="large">Large</sl-switch>
+```
+
+```jsx react
+import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlSwitch size="small">Small</SlSwitch>
+    <br />
+    <SlSwitch size="medium">Medium</SlSwitch>
+    <br />
+    <SlSwitch size="large">Large</SlSwitch>
+  </>
+);
+```
+
+### Custom Styles
+
+Use the available custom properties to change how the switch is styled.
+
+```html preview
+<sl-switch style="--width: 80px; --height: 40px; --thumb-size: 36px;">Really big</sl-switch>
 ```
 
 ```jsx react

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

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
 <sl-tab-group>
   <sl-tab slot="nav" panel="general">General</sl-tab>

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
 <sl-tab>Tab</sl-tab>
 <sl-tab active>Active</sl-tab>

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
 <sl-tag variant="primary">Primary</sl-tag>
 <sl-tag variant="success">Success</sl-tag>

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
 <sl-textarea></sl-textarea>
 ```

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.
@@ -94,6 +92,7 @@ Use the `placement` attribute to set the preferred placement of the tooltip.
 <style>
   .tooltip-placement-example {
     width: 250px;
+    margin: 1rem;
   }
 
   .tooltip-placement-example-row:after {
@@ -282,20 +281,14 @@ const App = () => {
 };
 ```
 
-### Remove Arrows
+### Removing Arrows
 
-You can control the size of tooltip arrows by overriding the `--sl-tooltip-arrow-size` design token.
+You can control the size of tooltip arrows by overriding the `--sl-tooltip-arrow-size` design token. To remove them, set the value to `0` as shown below.
 
 ```html preview
-<div style="--sl-tooltip-arrow-size: 0;">
-  <sl-tooltip content="This is a tooltip">
-    <sl-button>Above</sl-button>
-  </sl-tooltip>
-
-  <sl-tooltip content="This is a tooltip" placement="bottom">
-    <sl-button>Below</sl-button>
-  </sl-tooltip>
-</div>
+<sl-tooltip content="This is a tooltip" style="--sl-tooltip-arrow-size: 0;">
+  <sl-button>No Arrow</sl-button>
+</sl-tooltip>
 ```
 
 ```jsx react
@@ -338,7 +331,7 @@ Use the `content` slot to create tooltips with HTML content. Tooltips are design
 import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlTooltip content="This is a tooltip">
+  <SlTooltip>
     <div slot="content">
       I'm not <strong>just</strong> a tooltip, I'm a <em>tooltip</em> with HTML!
     </div>
@@ -348,6 +341,26 @@ const App = () => (
 );
 ```
 
+### Setting a Maximum Width
+
+Use the `--max-width` custom property to change the width the tooltip can grow to before wrapping occurs.
+
+```html preview
+<sl-tooltip style="--max-width: 80px;" content="This tooltip will wrap after only 80 pixels.">
+  <sl-button>Hover me</sl-button>
+</sl-tooltip>
+```
+
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTooltip style={{ '--max-width': '80px' }} content="This tooltip will wrap after only 80 pixels.">
+    <SlButton>Hover Me</SlButton>
+  </SlTooltip>
+);
+```
+
 ### Hoisting
 
 Tooltips will be clipped if they're inside a container that has `overflow: auto|hidden|scroll`. The `hoist` attribute forces the tooltip to use a fixed positioning strategy, allowing it to break out of the container. In this case, the tooltip will be positioned relative to its containing block, which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
@@ -365,10 +378,10 @@ Tooltips will be clipped if they're inside a container that has `overflow: auto|
 
 <style>
   .tooltip-hoist {
+    position: relative;
     border: solid 2px var(--sl-panel-border-color);
     overflow: hidden;
     padding: var(--sl-spacing-medium);
-    position: relative;
   }
 </style>
 ```

docs/components/tree-item.md

@@ -0,0 +1,163 @@
+# Tree Item
+
+[component-header:sl-tree-item]
+
+```html preview
+<sl-tree>
+  <sl-tree-item>
+    Item 1
+    <sl-tree-item>Item A</sl-tree-item>
+    <sl-tree-item>Item B</sl-tree-item>
+    <sl-tree-item>Item C</sl-tree-item>
+  </sl-tree-item>
+  <sl-tree-item>Item 2</sl-tree-item>
+  <sl-tree-item>Item 3</sl-tree-item>
+</sl-tree>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree>
+    <SlTreeItem>
+      Item 1
+      <SlTreeItem>Item A</SlTreeItem>
+      <SlTreeItem>Item B</SlTreeItem>
+      <SlTreeItem>Item C</SlTreeItem>
+    </SlTreeItem>
+    <SlTreeItem>Item 2</SlTreeItem>
+    <SlTreeItem>Item 3</SlTreeItem>
+  </SlTree>
+);
+```
+
+## Examples
+
+### Nested tree items
+
+A tree item can contain other tree items. This allows the node to be expanded or collapsed by the user.
+
+```html preview
+<sl-tree>
+  <sl-tree-item>
+    Item 1
+    <sl-tree-item>
+      Item A
+      <sl-tree-item>Item Z</sl-tree-item>
+      <sl-tree-item>Item Y</sl-tree-item>
+      <sl-tree-item>Item X</sl-tree-item>
+    </sl-tree-item>
+    <sl-tree-item>Item B</sl-tree-item>
+    <sl-tree-item>Item C</sl-tree-item>
+  </sl-tree-item>
+  <sl-tree-item>Item 2</sl-tree-item>
+  <sl-tree-item>Item 3</sl-tree-item>
+</sl-tree>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree>
+    <SlTreeItem>
+      Item 1
+      <SlTreeItem>
+        Item A
+        <SlTreeItem>Item Z</SlTreeItem>
+        <SlTreeItem>Item Y</SlTreeItem>
+        <SlTreeItem>Item X</SlTreeItem>
+      </SlTreeItem>
+      <SlTreeItem>Item B</SlTreeItem>
+      <SlTreeItem>Item C</SlTreeItem>
+    </SlTreeItem>
+    <SlTreeItem>Item 2</SlTreeItem>
+    <SlTreeItem>Item 3</SlTreeItem>
+  </SlTree>
+);
+```
+
+### Selected
+
+Use the `selected` attribute to select a tree item initially.
+
+```html preview
+<sl-tree>
+  <sl-tree-item selected>
+    Item 1
+    <sl-tree-item>Item A</sl-tree-item>
+    <sl-tree-item>Item B</sl-tree-item>
+    <sl-tree-item>Item C</sl-tree-item>
+  </sl-tree-item>
+  <sl-tree-item>Item 2</sl-tree-item>
+  <sl-tree-item>Item 3</sl-tree-item>
+</sl-tree>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree>
+    <SlTreeItem selected>
+      Item 1
+      <SlTreeItem>Item A</SlTreeItem>
+      <SlTreeItem>Item B</SlTreeItem>
+      <SlTreeItem>Item C</SlTreeItem>
+    </SlTreeItem>
+    <SlTreeItem>Item 2</SlTreeItem>
+    <SlTreeItem>Item 3</SlTreeItem>
+  </SlTree>
+);
+```
+
+### Expanded
+
+Use the `expanded` attribute to expand a tree item initially.
+
+```html preview
+<sl-tree>
+  <sl-tree-item expanded>
+    Item 1
+    <sl-tree-item expanded>
+      Item A
+      <sl-tree-item>Item Z</sl-tree-item>
+      <sl-tree-item>Item Y</sl-tree-item>
+      <sl-tree-item>Item X</sl-tree-item>
+    </sl-tree-item>
+    <sl-tree-item>Item B</sl-tree-item>
+    <sl-tree-item>Item C</sl-tree-item>
+  </sl-tree-item>
+  <sl-tree-item>Item 2</sl-tree-item>
+  <sl-tree-item>Item 3</sl-tree-item>
+</sl-tree>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree>
+    <SlTreeItem expanded>
+      Item 1
+      <SlTreeItem expanded>
+        Item A
+        <SlTreeItem>Item Z</SlTreeItem>
+        <SlTreeItem>Item Y</SlTreeItem>
+        <SlTreeItem>Item X</SlTreeItem>
+      </SlTreeItem>
+      <SlTreeItem>Item B</SlTreeItem>
+      <SlTreeItem>Item C</SlTreeItem>
+    </SlTreeItem>
+    <SlTreeItem>Item 2</SlTreeItem>
+    <SlTreeItem>Item 3</SlTreeItem>
+  </SlTree>
+);
+```
+
+[component-metadata:sl-tree-item]

docs/components/tree.md

@@ -0,0 +1,464 @@
+# Tree
+
+[component-header:sl-tree]
+
+```html preview
+<sl-tree>
+  <sl-tree-item>
+    Deciduous
+    <sl-tree-item>Birch</sl-tree-item>
+    <sl-tree-item>
+      Maple
+      <sl-tree-item>Field maple</sl-tree-item>
+      <sl-tree-item>Red maple</sl-tree-item>
+      <sl-tree-item>Sugar maple</sl-tree-item>
+    </sl-tree-item>
+    <sl-tree-item>Oak</sl-tree-item>
+  </sl-tree-item>
+
+  <sl-tree-item>
+    Coniferous
+    <sl-tree-item>Cedar</sl-tree-item>
+    <sl-tree-item>Pine</sl-tree-item>
+    <sl-tree-item>Spruce</sl-tree-item>
+  </sl-tree-item>
+
+  <sl-tree-item>
+    Non-trees
+    <sl-tree-item>Bamboo</sl-tree-item>
+    <sl-tree-item>Cactus</sl-tree-item>
+    <sl-tree-item>Fern</sl-tree-item>
+  </sl-tree-item>
+</sl-tree>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree>
+    <SlTreeItem>
+      Deciduous
+      <SlTreeItem>Birch</SlTreeItem>
+      <SlTreeItem>
+        Maple
+        <SlTreeItem>Field maple</SlTreeItem>
+        <SlTreeItem>Red maple</SlTreeItem>
+        <SlTreeItem>Sugar maple</SlTreeItem>
+      </SlTreeItem>
+      <SlTreeItem>Oak</SlTreeItem>
+    </SlTreeItem>
+
+    <SlTreeItem>
+      Coniferous
+      <SlTreeItem>Cedar</SlTreeItem>
+      <SlTreeItem>Pine</SlTreeItem>
+      <SlTreeItem>Spruce</SlTreeItem>
+    </SlTreeItem>
+
+    <SlTreeItem>
+      Non-trees
+      <SlTreeItem>Bamboo</SlTreeItem>
+      <SlTreeItem>Cactus</SlTreeItem>
+      <SlTreeItem>Fern</SlTreeItem>
+    </SlTreeItem>
+  </SlTree>
+);
+```
+
+## Examples
+
+### Selection Modes
+
+The `selection` attribute lets you change the selection behavior of the tree.
+
+- Use `single` to allow the selection of a single item (default).
+- Use `multiple` to allow the selection of multiple items.
+- Use `leaf` to only allow leaf nodes to be selected.
+
+```html preview
+<sl-select id="selection-mode" value="single" label="Selection">
+  <sl-option value="single">Single</sl-option>
+  <sl-option value="multiple">Multiple</sl-option>
+  <sl-option value="leaf">Leaf</sl-option>
+</sl-select>
+
+<br />
+
+<sl-tree class="tree-selectable">
+  <sl-tree-item>
+    Item 1
+    <sl-tree-item>
+      Item A
+      <sl-tree-item>Item Z</sl-tree-item>
+      <sl-tree-item>Item Y</sl-tree-item>
+      <sl-tree-item>Item X</sl-tree-item>
+    </sl-tree-item>
+    <sl-tree-item>Item B</sl-tree-item>
+    <sl-tree-item>Item C</sl-tree-item>
+  </sl-tree-item>
+  <sl-tree-item>Item 2</sl-tree-item>
+  <sl-tree-item>Item 3</sl-tree-item>
+</sl-tree>
+
+<script>
+  const selectionMode = document.querySelector('#selection-mode');
+  const tree = document.querySelector('.tree-selectable');
+
+  selectionMode.addEventListener('sl-change', () => {
+    tree.querySelectorAll('sl-tree-item').forEach(item => (item.selected = false));
+    tree.selection = selectionMode.value;
+  });
+</script>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [selection, setSelection] = useState('single');
+
+  return (
+    <>
+      <SlSelect label="Selection" value={selection} onSlChange={event => setSelection(event.target.value)}>
+        <SlMenuItem value="single">single</SlMenuItem>
+        <SlMenuItem value="multiple">multiple</SlMenuItem>
+        <SlMenuItem value="leaf">leaf</SlMenuItem>
+      </SlSelect>
+
+      <br />
+
+      <SlTree selection={selection}>
+        <SlTreeItem>
+          Item 1
+          <SlTreeItem>
+            Item A
+            <SlTreeItem>Item Z</SlTreeItem>
+            <SlTreeItem>Item Y</SlTreeItem>
+            <SlTreeItem>Item X</SlTreeItem>
+          </SlTreeItem>
+          <SlTreeItem>Item B</SlTreeItem>
+          <SlTreeItem>Item C</SlTreeItem>
+        </SlTreeItem>
+        <SlTreeItem>Item 2</SlTreeItem>
+        <SlTreeItem>Item 3</SlTreeItem>
+      </SlTree>
+    </>
+  );
+};
+```
+
+### Showing Indent Guides
+
+Indent guides can be drawn by setting `--indent-guide-width`. You can also change the color, offset, and style, using `--indent-guide-color`, `--indent-guide-style`, and `--indent-guide-offset`, respectively.
+
+```html preview
+<sl-tree class="tree-with-lines">
+  <sl-tree-item expanded>
+    Deciduous
+    <sl-tree-item>Birch</sl-tree-item>
+    <sl-tree-item expanded>
+      Maple
+      <sl-tree-item>Field maple</sl-tree-item>
+      <sl-tree-item>Red maple</sl-tree-item>
+      <sl-tree-item>Sugar maple</sl-tree-item>
+    </sl-tree-item>
+    <sl-tree-item>Oak</sl-tree-item>
+  </sl-tree-item>
+
+  <sl-tree-item>
+    Coniferous
+    <sl-tree-item>Cedar</sl-tree-item>
+    <sl-tree-item>Pine</sl-tree-item>
+    <sl-tree-item>Spruce</sl-tree-item>
+  </sl-tree-item>
+
+  <sl-tree-item>
+    Non-trees
+    <sl-tree-item>Bamboo</sl-tree-item>
+    <sl-tree-item>Cactus</sl-tree-item>
+    <sl-tree-item>Fern</sl-tree-item>
+  </sl-tree-item>
+</sl-tree>
+
+<style>
+  .tree-with-lines {
+    --indent-guide-width: 1px;
+  }
+</style>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree class="tree-with-lines" style={{ '--indent-guide-width': '1px' }}>
+    <SlTreeItem expanded>
+      Deciduous
+      <SlTreeItem>Birch</SlTreeItem>
+      <SlTreeItem expanded>
+        Maple
+        <SlTreeItem>Field maple</SlTreeItem>
+        <SlTreeItem>Red maple</SlTreeItem>
+        <SlTreeItem>Sugar maple</SlTreeItem>
+      </SlTreeItem>
+      <SlTreeItem>Oak</SlTreeItem>
+    </SlTreeItem>
+
+    <SlTreeItem>
+      Coniferous
+      <SlTreeItem>Cedar</SlTreeItem>
+      <SlTreeItem>Pine</SlTreeItem>
+      <SlTreeItem>Spruce</SlTreeItem>
+    </SlTreeItem>
+
+    <SlTreeItem>
+      Non-trees
+      <SlTreeItem>Bamboo</SlTreeItem>
+      <SlTreeItem>Cactus</SlTreeItem>
+      <SlTreeItem>Fern</SlTreeItem>
+    </SlTreeItem>
+  </SlTree>
+);
+```
+
+### Lazy Loading
+
+Use the `lazy` attribute on a tree item to indicate that the content is not yet present and will be loaded later. When the user tries to expand the node, the `loading` state is set to `true` and the `sl-lazy-load` event will be emitted to allow you to load data asynchronously. The item will remain in a loading state until its content is changed.
+
+If you want to disable this behavior after the first load, simply remove the `lazy` attribute and, on the next expand, the existing content will be shown instead.
+
+```html preview
+<sl-tree>
+  <sl-tree-item lazy>Available Trees</sl-tree-item>
+</sl-tree>
+
+<script type="module">
+  const lazyItem = document.querySelector('sl-tree-item[lazy]');
+
+  lazyItem.addEventListener('sl-lazy-load', () => {
+    // Simulate asynchronous loading
+    setTimeout(() => {
+      const subItems = ['Birch', 'Cedar', 'Maple', 'Pine'];
+
+      for (const item of subItems) {
+        const treeItem = document.createElement('sl-tree-item');
+        treeItem.innerText = item;
+        lazyItem.append(treeItem);
+      }
+
+      // Disable lazy mode once the content has been loaded
+      lazyItem.lazy = false;
+    }, 1000);
+  });
+</script>
+```
+
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [childItems, setChildItems] = useState([]);
+  const [lazy, setLazy] = useState(true);
+
+  const handleLazyLoad = () => {
+    // Simulate asynchronous loading
+    setTimeout(() => {
+      setChildItems(['Birch', 'Cedar', 'Maple', 'Pine']);
+
+      // Disable lazy mode once the content has been loaded
+      setLazy(false);
+    }, 1000);
+  };
+
+  return (
+    <SlTree>
+      <SlTreeItem lazy={lazy} onSlLazyLoad={handleLazyLoad}>
+        Available Trees
+        {childItems.map(item => (
+          <SlTreeItem>{item}</SlTreeItem>
+        ))}
+      </SlTreeItem>
+    </SlTree>
+  );
+};
+```
+
+### Customizing the Expand and Collapse Icons
+
+Use the `expand-icon` and `collapse-icon` slots to change the expand and collapse icons, respectively. To disable the animation, override the `rotate` property on the `expand-button` part as shown below.
+
+```html preview
+<sl-tree class="custom-icons">
+  <sl-icon name="plus-square" slot="expand-icon"></sl-icon>
+  <sl-icon name="dash-square" slot="collapse-icon"></sl-icon>
+
+  <sl-tree-item>
+    Deciduous
+    <sl-tree-item>Birch</sl-tree-item>
+    <sl-tree-item>
+      Maple
+      <sl-tree-item>Field maple</sl-tree-item>
+      <sl-tree-item>Red maple</sl-tree-item>
+      <sl-tree-item>Sugar maple</sl-tree-item>
+    </sl-tree-item>
+    <sl-tree-item>Oak</sl-tree-item>
+  </sl-tree-item>
+
+  <sl-tree-item>
+    Coniferous
+    <sl-tree-item>Cedar</sl-tree-item>
+    <sl-tree-item>Pine</sl-tree-item>
+    <sl-tree-item>Spruce</sl-tree-item>
+  </sl-tree-item>
+
+  <sl-tree-item>
+    Non-trees
+    <sl-tree-item>Bamboo</sl-tree-item>
+    <sl-tree-item>Cactus</sl-tree-item>
+    <sl-tree-item>Fern</sl-tree-item>
+  </sl-tree-item>
+</sl-tree>
+
+<style>
+  .custom-icons sl-tree-item::part(expand-button) {
+    /* Disable the expand/collapse animation */
+    rotate: none;
+  }
+</style>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree>
+    <SlIcon name="plus-square" slot="expand-icon"></SlIcon>
+    <SlIcon name="dash-square" slot="collapse-icon"></SlIcon>
+
+    <SlTreeItem>
+      Deciduous
+      <SlTreeItem>Birch</SlTreeItem>
+      <SlTreeItem>
+        Maple
+        <SlTreeItem>Field maple</SlTreeItem>
+        <SlTreeItem>Red maple</SlTreeItem>
+        <SlTreeItem>Sugar maple</SlTreeItem>
+      </SlTreeItem>
+      <SlTreeItem>Oak</SlTreeItem>
+    </SlTreeItem>
+
+    <SlTreeItem>
+      Coniferous
+      <SlTreeItem>Cedar</SlTreeItem>
+      <SlTreeItem>Pine</SlTreeItem>
+      <SlTreeItem>Spruce</SlTreeItem>
+    </SlTreeItem>
+
+    <SlTreeItem>
+      Non-trees
+      <SlTreeItem>Bamboo</SlTreeItem>
+      <SlTreeItem>Cactus</SlTreeItem>
+      <SlTreeItem>Fern</SlTreeItem>
+    </SlTreeItem>
+  </SlTree>
+);
+```
+
+### With Icons
+
+Decorative icons can be used before labels to provide hints for each node.
+
+```html preview
+<sl-tree class="tree-with-icons">
+  <sl-tree-item expanded>
+    <sl-icon name="folder"></sl-icon>
+    Documents
+
+    <sl-tree-item>
+      <sl-icon name="folder"> </sl-icon>
+      Photos
+      <sl-tree-item>
+        <sl-icon name="image"></sl-icon>
+        birds.jpg
+      </sl-tree-item>
+      <sl-tree-item>
+        <sl-icon name="image"></sl-icon>
+        kitten.jpg
+      </sl-tree-item>
+      <sl-tree-item>
+        <sl-icon name="image"></sl-icon>
+        puppy.jpg
+      </sl-tree-item>
+    </sl-tree-item>
+
+    <sl-tree-item>
+      <sl-icon name="folder"></sl-icon>
+      Writing
+      <sl-tree-item>
+        <sl-icon name="file"></sl-icon>
+        draft.txt
+      </sl-tree-item>
+      <sl-tree-item>
+        <sl-icon name="file-pdf"></sl-icon>
+        final.pdf
+      </sl-tree-item>
+      <sl-tree-item>
+        <sl-icon name="file-bar-graph"></sl-icon>
+        sales.xls
+      </sl-tree-item>
+    </sl-tree-item>
+  </sl-tree-item>
+</sl-tree>
+```
+
+```jsx react
+import { SlIcon, SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  return (
+    <SlTree class="tree-with-icons">
+      <SlTreeItem expanded>
+        <SlIcon name="folder" />
+        Root
+        <SlTreeItem>
+          <SlIcon name="folder" />
+          Folder 1<SlTreeItem>
+            <SlIcon name="files" />
+            File 1 - 1
+          </SlTreeItem>
+          <SlTreeItem disabled>
+            <SlIcon name="files" />
+            File 1 - 2
+          </SlTreeItem>
+          <SlTreeItem>
+            <SlIcon name="files" />
+            File 1 - 3
+          </SlTreeItem>
+        </SlTreeItem>
+        <SlTreeItem>
+          <SlIcon name="files" />
+          Folder 2<SlTreeItem>
+            <SlIcon name="files" />
+            File 2 - 1
+          </SlTreeItem>
+          <SlTreeItem>
+            <SlIcon name="files" />
+            File 2 - 2
+          </SlTreeItem>
+        </SlTreeItem>
+        <SlTreeItem>
+          <SlIcon name="files" />
+          File 1
+        </SlTreeItem>
+      </SlTreeItem>
+    </SlTree>
+  );
+};
+```
+
+[component-metadata:sl-tree]

docs/components/visually-hidden.md

@@ -2,14 +2,12 @@
 
 [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.
 
 ```html preview
-<div style="min-height: 100px;">
+<div style="min-height: 1.875rem;">
   <sl-visually-hidden>
     <a href="#">Skip to main content</a>
   </sl-visually-hidden>
@@ -32,7 +30,7 @@ In this example, the link will open a new window. Screen readers will announce "
 
 ### Content Conveyed By Context
 
-Adding a title or label may seem redundant at times, but they're very helpful for unsighted users. Rather than omit them, you can provide context to unsighted users with visually hidden content.
+Adding a label may seem redundant at times, but they're very helpful for unsighted users. Rather than omit them, you can provide context to unsighted users with visually hidden content that will be announced by assistive devices such as screen readers.
 
 ```html preview
 <sl-card style="width: 100%; max-width: 360px;">

docs/frameworks/vue-2.md

@@ -28,14 +28,16 @@ setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dis
 You'll need to tell Vue to ignore Shoelace components. This is pretty easy because they all start with `sl-`.
 
 ```js
-import { createApp } from 'vue';
+import Vue from 'vue';
 import App from './App.vue';
 
-const app = createApp(App);
+Vue.config.ignoredElements = [/sl-/];
 
-app.config.compilerOptions.isCustomElement = tag => tag.startsWith('sl-');
+const app = new Vue({
+  render: h => h(App)
+});
 
-app.mount('#app');
+app.$mount('#app');
 ```
 
 Now you can start using Shoelace components in your app!
@@ -56,31 +58,32 @@ One caveat is there's currently [no support for v-model on custom elements](http
 
 ```html
 <!-- This doesn't work -->
-<sl-input v-model="name">
-  <!-- This works, but it's a bit longer -->
-  <sl-input :value="name" @input="name = $event.target.value"></sl-input
-></sl-input>
+<sl-input v-model="name"></sl-input>
+<!-- This works, but it's a bit longer -->
+<sl-input :value="name" @input="name = $event.target.value"></sl-input>
 ```
 
 If that's too verbose for your liking, you can use a custom directive instead. [This utility](https://www.npmjs.com/package/@shoelace-style/vue-sl-model) adds a custom directive that will work just like `v-model` but for Shoelace components. To install it, use this command.
 
 ```bash
-npm install @shoelace-style/vue-sl-model
+npm install @shoelace-style/vue-sl-model@1
 ```
 
 Next, import the directive and enable it like this.
 
 ```js
+import Vue from 'vue';
 import ShoelaceModelDirective from '@shoelace-style/vue-sl-model';
-import { createApp } from 'vue';
 import App from './App.vue';
 
-const app = createApp(App);
-app.use(ShoelaceModelDirective);
+Vue.use(ShoelaceModelDirective);
+Vue.config.ignoredElements = [/sl-/];
 
-app.config.compilerOptions.isCustomElement = tag => tag.startsWith('sl-');
+const app = new Vue({
+  render: h => h(App)
+});
 
-app.mount('#app');
+app.$mount('#app');
 ```
 
 Now you can use the `v-sl-model` directive to keep your data in sync!
@@ -89,4 +92,4 @@ Now you can use the `v-sl-model` directive to keep your data in sync!
 <sl-input v-sl-model="name"></sl-input>
 ```
 
-?> Are you using Shoelace with Vue? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue.md)
+?> Are you using Shoelace with Vue? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue-2.md)

docs/getting-started/form-controls.md

@@ -4,13 +4,9 @@ Every Shoelace component makes use of a [shadow DOM](https://developer.mozilla.o
 
 Shoelace solves this problem by using the [`formdata`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/formdata_event) event, which is [available in all modern browsers](https://caniuse.com/mdn-api_htmlformelement_formdata_event). This means, when a form is submitted, Shoelace form controls will automatically append their values to the `FormData` object that's used to submit the form. In most cases, things will "just work." However, if you're using a form serialization library, it might need to be adapted to recognize Shoelace form controls.
 
-?> If you're using an older browser that doesn't support the `formdata` event, a lightweight polyfill will be automatically applied to ensure forms submit as expected.
+?> Shoelace uses event listeners to intercept the form's `formdata` and `submit` events. This allows it to inject data and trigger validation as necessary. If you're also attaching an event listener to the form, _you must attach it after Shoelace form controls are connected to the DOM_, otherwise your logic will run before Shoelace has a chance to inject form data and validate form controls.
 
-## A Note About Event Handling
-
-Shoelace uses event listeners to intercept the form's `formdata` and `submit` events. This allows it to inject data and trigger validation as necessary. If you're also attaching an event listener to the form, _you must attach it after Shoelace form controls are connected to the DOM_, otherwise your logic will run before Shoelace has a chance to inject form data and validate form controls.
-
-## Form Serialization
+## Data Serialization
 
 Serialization is just a fancy word for collecting form data. If you're relying on standard form submissions, e.g. `<form action="...">`, you can probably skip this section. However, most modern apps use the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) or a library such as [axios](https://github.com/axios/axios) to submit forms using JavaScript.
 
@@ -36,36 +32,37 @@ const data = serialize(form);
 
 This results in an object with name/value pairs that map to each form control. If more than one form control shares the same name, the values will be passed as an array, e.g. `{ name: ['value1', 'value2'] }`.
 
-## Form Control Validation
+## Constraint Validation
 
-Client-side validation can be enabled through the browser's [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation) for Shoelace form controls. You can activate it using attributes such as `required`, `pattern`, `minlength`, and `maxlength`. Shoelace implements many of the same attributes as native form controls, but check each form control's documentation for a list of all supported properties.
+Client-side validation can be enabled through the browser's [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation) for Shoelace form controls. You can activate it using attributes such as `required`, `pattern`, `minlength`, `maxlength`, etc. Shoelace implements many of the same attributes as native form controls, but check the documentation for a list of supported properties for each component.
 
-As the user interacts with a form control, its `invalid` attribute will reflect its validity based on its current value and the constraints that have been defined. When a form control is invalid, the containing form will not be submitted. Instead, the browser will show the user a relevant error message. If you don't want to use client-side validation, you can suppress this behavior by adding `novalidate` to the surrounding `<form>` element.
+If you don't want to use client-side validation, you can suppress this behavior by adding `novalidate` to the surrounding `<form>` element.
 
-All form controls support validation, but not all validation props are available for every component. Refer to a component's documentation to see which validation props it supports.
+?> If this syntax looks unfamiliar, don't worry! Most of what you're learning on this page is platform knowledge that applies to regular form controls, too.
 
 !> Client-side validation can be used to improve the UX of forms, but it is not a replacement for server-side validation. **You should always validate and sanitize user input on the server!**
 
 ### Required Fields
 
-To make a field required, use the `required` prop. The form will not be submitted if a required form control is empty.
+To make a field required, use the `required` attribute. Required fields will automatically receive a `*` after their labels. This is configurable through the `--sl-input-required-content` custom property.
+
+The form will not be submitted if a required field is incomplete.
 
 ```html preview
 <form class="input-validation-required">
   <sl-input name="name" label="Name" required></sl-input>
   <br />
   <sl-select label="Favorite Animal" clearable required>
-    <sl-menu-item value="birds">Birds</sl-menu-item>
-    <sl-menu-item value="cats">Cats</sl-menu-item>
-    <sl-menu-item value="dogs">Dogs</sl-menu-item>
-    <sl-menu-item value="other">Other</sl-menu-item>
+    <sl-option value="birds">Birds</sl-option>
+    <sl-option value="cats">Cats</sl-option>
+    <sl-option value="dogs">Dogs</sl-option>
+    <sl-option value="other">Other</sl-option>
   </sl-select>
   <br />
   <sl-textarea name="comment" label="Comment" required></sl-textarea>
   <br />
   <sl-checkbox required>Check me before submitting</sl-checkbox>
   <br /><br />
-  <sl-button type="reset" variant="default">Reset</sl-button>
   <sl-button type="submit" variant="primary">Submit</sl-button>
 </form>
 
@@ -119,8 +116,8 @@ To restrict a value to a specific [pattern](https://developer.mozilla.org/en-US/
 <form class="input-validation-pattern">
   <sl-input name="letters" required label="Letters" pattern="[A-Za-z]+"></sl-input>
   <br />
-  <sl-button type="reset" variant="default">Reset</sl-button>
   <sl-button type="submit" variant="primary">Submit</sl-button>
+  <sl-button type="reset" variant="default">Reset</sl-button>
 </form>
 
 <script type="module">
@@ -159,12 +156,12 @@ Some input types will automatically trigger constraints, such as `email` and `ur
 
 ```html preview
 <form class="input-validation-type">
-  <sl-input variant="email" label="Email" placeholder="you@example.com" required></sl-input>
+  <sl-input type="email" label="Email" placeholder="you@example.com" required></sl-input>
   <br />
-  <sl-input variant="url" label="URL" placeholder="https://example.com/" required></sl-input>
+  <sl-input type="url" label="URL" placeholder="https://example.com/" required></sl-input>
   <br />
-  <sl-button type="reset" variant="default">Reset</sl-button>
   <sl-button type="submit" variant="primary">Submit</sl-button>
+  <sl-button type="reset" variant="default">Reset</sl-button>
 </form>
 
 <script type="module">
@@ -187,9 +184,9 @@ const App = () => {
 
   return (
     <form onSubmit={handleSubmit}>
-      <SlInput variant="email" label="Email" placeholder="you@example.com" required />
+      <SlInput type="email" label="Email" placeholder="you@example.com" required />
       <br />
-      <SlInput variant="url" label="URL" placeholder="https://example.com/" required />
+      <SlInput type="url" label="URL" placeholder="https://example.com/" required />
       <br />
       <SlButton type="submit" variant="primary">
         Submit
@@ -199,16 +196,16 @@ const App = () => {
 };
 ```
 
-### Custom Validation
+### Custom Error Messages
 
 To create a custom validation error, pass a non-empty string to the `setCustomValidity()` method. This will override any existing validation constraints. The form will not be submitted when a custom validity is set and the browser will show a validation error when the containing form is submitted. To make the input valid again, call `setCustomValidity()` again with an empty string.
 
 ```html preview
 <form class="input-validation-custom">
-  <sl-input label="Type 'shoelace'" required></sl-input>
+  <sl-input label="Type “shoelace”" required></sl-input>
   <br />
-  <sl-button type="reset" variant="default">Reset</sl-button>
   <sl-button type="submit" variant="primary">Submit</sl-button>
+  <sl-button type="reset" variant="default">Reset</sl-button>
 </form>
 
 <script type="module">
@@ -267,76 +264,237 @@ const App = () => {
 
 ?> Custom validation can be applied to any form control that supports the `setCustomValidity()` method. It is not limited to inputs and textareas.
 
-### Custom Validation Styles
+## Custom Validation Styles
 
-The `invalid` attribute reflects the form control's validity, so you can style invalid fields using the `[invalid]` selector. The example below demonstrates how you can give erroneous fields a different appearance. Type something other than "shoelace" to demonstrate this.
+Due to the many ways form controls are used, Shoelace doesn't provide out of the box validation styles for form controls as part of its default theme. Instead, the following attributes will be applied to reflect a control's validity as users interact with it. You can use them to create custom styles for any of the validation states you're interested in.
+
+- `data-required` - the form control is required
+- `data-optional` - the form control is optional
+- `data-invalid` - the form control is currently invalid
+- `data-valid` - the form control is currently valid
+- `data-user-invalid` - the form control is currently invalid and the user has interacted with it
+- `data-user-valid` - the form control is currently valid and the user has interacted with it
+
+These attributes map to the browser's built-in pseudo classes for validation: [`:required`](https://developer.mozilla.org/en-US/docs/Web/CSS/:required), [`:optional`](https://developer.mozilla.org/en-US/docs/Web/CSS/:optional), [`:invalid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:invalid), [`:valid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:valid), and the proposed [`:user-invalid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:user-invalid) and [`:user-valid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:user-valid).
+
+?> In the future, data attributes will be replaced with custom pseudo classes such as `:--valid` and `:--invalid`. Shoelace is using data attributes as a workaround until browsers support custom states through [`ElementInternals.states`](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/states).
+
+### Styling Invalid Form Controls
+
+You can target validity using any of the aforementioned data attributes, but it's usually preferable to target `data-user-invalid` and `data-user-valid` since they get applied only after a user interaction such as typing or submitting. This prevents empty form controls from appearing invalid immediately, which often results in a poor user experience.
+
+This example demonstrates custom validation styles using `data-user-invalid` and `data-user-valid`. Try Typing in the fields to see how validity changes with user input.
 
 ```html preview
-<sl-input class="custom-input" label="Type Something" required pattern="shoelace">
-  <small slot="help-text">Please enter "shoelace" to continue</small>
-</sl-input>
+<form class="validity-styles">
+  <sl-input
+    name="name"
+    label="Name"
+    help-text="What would you like people to call you?"
+    autocomplete="off"
+    required
+  ></sl-input>
 
-<style>
-  .custom-input[invalid]:not([disabled])::part(label),
-  .custom-input[invalid]:not([disabled])::part(help-text) {
-    color: var(--sl-color-danger-600);
-  }
+  <sl-select name="animal" label="Favorite Animal" help-text="Select the best option." clearable required>
+    <sl-option value="birds">Birds</sl-option>
+    <sl-option value="cats">Cats</sl-option>
+    <sl-option value="dogs">Dogs</sl-option>
+    <sl-option value="other">Other</sl-option>
+  </sl-select>
 
-  .custom-input[invalid]:not([disabled])::part(base) {
-    border-color: var(--sl-color-danger-500);
-  }
+  <sl-checkbox value="accept" required>Accept terms and conditions</sl-checkbox>
 
-  .custom-input[invalid]:focus-within::part(base) {
-    box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-danger-500);
-  }
-</style>
-```
-
-```jsx react
-import { SlInput } from '@shoelace-style/shoelace/dist/react';
-
-const css = `
-  .custom-input[invalid]:not([disabled])::part(label),
-  .custom-input[invalid]:not([disabled])::part(help-text) {
-    color: var(--sl-color-danger-600);
-  }
-
-  .custom-input[invalid]:not([disabled])::part(base) {      
-    border-color: var(--sl-color-danger-500);
-  } 
-
-  .custom-input[invalid]:focus-within::part(base) {
-    box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-danger-500);
-  }
-`;
-
-const App = () => (
-  <>
-    <SlInput className="custom-input" required pattern="shoelace">
-      <small slot="help-text">Please enter "shoelace" to continue</small>
-    </SlInput>
-
-    <style>{css}</style>
-  </>
-);
-```
-
-### Third-party Validation
-
-To opt out of the browser's built-in validation and use your own, add the `novalidate` attribute to the form. This will ignore all constraints and prevent the browser from showing its own warnings when form controls are invalid.
-
-Remember that the `invalid` attribute on form controls reflects validity as defined by the [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation). You can set it initially, but the `invalid` attribute will update as the user interacts with the form control. As such, you should not rely on it to set invalid styles using a custom validation library.
-
-Instead, toggle a class and target it in your stylesheet as shown below.
-
-```html
-<form novalidate>
-  <sl-input class="invalid"></sl-input>
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+  <sl-button type="reset" variant="default">Reset</sl-button>
 </form>
 
+<script type="module">
+  const form = document.querySelector('.validity-styles');
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    alert('All fields are valid!');
+  });
+</script>
+
 <style>
-  sl-input.invalid {
-    ...;
+  .validity-styles sl-input,
+  .validity-styles sl-select,
+  .validity-styles sl-checkbox {
+    display: block;
+    margin-bottom: var(--sl-spacing-medium);
+  }
+
+  /* user invalid styles */
+  .validity-styles sl-input[data-user-invalid]::part(base),
+  .validity-styles sl-select[data-user-invalid]::part(combobox),
+  .validity-styles sl-checkbox[data-user-invalid]::part(control) {
+    border-color: var(--sl-color-danger-600);
+  }
+
+  .validity-styles [data-user-invalid]::part(form-control-label),
+  .validity-styles [data-user-invalid]::part(form-control-help-text),
+  .validity-styles sl-checkbox[data-user-invalid]::part(label) {
+    color: var(--sl-color-danger-700);
+  }
+
+  .validity-styles sl-checkbox[data-user-invalid]::part(control) {
+    outline: none;
+  }
+
+  .validity-styles sl-input:focus-within[data-user-invalid]::part(base),
+  .validity-styles sl-select:focus-within[data-user-invalid]::part(combobox),
+  .validity-styles sl-checkbox:focus-within[data-user-invalid]::part(control) {
+    border-color: var(--sl-color-danger-600);
+    box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-danger-300);
+  }
+
+  /* User valid styles */
+  .validity-styles sl-input[data-user-valid]::part(base),
+  .validity-styles sl-select[data-user-valid]::part(combobox),
+  .validity-styles sl-checkbox[data-user-valid]::part(control) {
+    border-color: var(--sl-color-success-600);
+  }
+
+  .validity-styles [data-user-valid]::part(form-control-label),
+  .validity-styles [data-user-valid]::part(form-control-help-text),
+  .validity-styles sl-checkbox[data-user-valid]::part(label) {
+    color: var(--sl-color-success-700);
+  }
+
+  .validity-styles sl-checkbox[data-user-valid]::part(control) {
+    background-color: var(--sl-color-success-600);
+    outline: none;
+  }
+
+  .validity-styles sl-input:focus-within[data-user-valid]::part(base),
+  .validity-styles sl-select:focus-within[data-user-valid]::part(combobox),
+  .validity-styles sl-checkbox:focus-within[data-user-valid]::part(control) {
+    border-color: var(--sl-color-success-600);
+    box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-success-300);
   }
 </style>
 ```
+
+## Inline Form Validation
+
+By default, Shoelace form controls use the browser's tooltip-style error messages. No mechanism is provided to show errors inline, as there are too many opinions on how that would work when combined with native form controls and other custom elements. You can, however, implement your own solution using the following technique.
+
+To disable the browser's error messages, you need to cancel the `sl-invalid` event. Then you can apply your own inline validation errors. This example demonstrates a primitive way to do this.
+
+```html preview
+<form class="inline-validation">
+  <sl-input
+    name="name"
+    label="Name"
+    help-text="What would you like people to call you?"
+    autocomplete="off"
+    required
+  ></sl-input>
+
+  <div id="name-error" aria-live="polite" hidden></div>
+
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+  <sl-button type="reset" variant="default">Reset</sl-button>
+</form>
+
+<script>
+  const form = document.querySelector('.inline-validation');
+  const nameError = document.querySelector('#name-error');
+
+  // A form control is invalid
+  form.addEventListener(
+    'sl-invalid',
+    event => {
+      // Suppress the browser's constraint validation message
+      event.preventDefault();
+
+      nameError.textContent = `Error: ${event.target.validationMessage}`;
+      nameError.hidden = false;
+
+      event.target.focus();
+    },
+    { capture: true } // you must use capture since sl-invalid doesn't bubble!
+  );
+
+  // Handle form submit
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    nameError.hidden = true;
+    nameError.textContent = '';
+    setTimeout(() => alert('All fields are valid'), 50);
+  });
+
+  // Handle form reset
+  form.addEventListener('reset', event => {
+    nameError.hidden = true;
+    nameError.textContent = '';
+  });
+</script>
+
+<style>
+  #name-error {
+    font-size: var(--sl-input-help-text-font-size-medium);
+    color: var(--sl-color-danger-700);
+  }
+
+  #name-error ~ sl-button {
+    margin-top: var(--sl-spacing-medium);
+  }
+
+  .inline-validation sl-input {
+    display: block;
+  }
+
+  /* user invalid styles */
+  .inline-validation sl-input[data-user-invalid]::part(base) {
+    border-color: var(--sl-color-danger-600);
+  }
+
+  .inline-validation [data-user-invalid]::part(form-control-label),
+  .inline-validation [data-user-invalid]::part(form-control-help-text) {
+    color: var(--sl-color-danger-700);
+  }
+
+  .inline-validation sl-input:focus-within[data-user-invalid]::part(base) {
+    border-color: var(--sl-color-danger-600);
+    box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-danger-300);
+  }
+
+  /* User valid styles */
+  .inline-validation sl-input[data-user-valid]::part(base) {
+    border-color: var(--sl-color-success-600);
+  }
+
+  .inline-validation [data-user-valid]::part(form-control-label),
+  .inline-validation [data-user-valid]::part(form-control-help-text) {
+    color: var(--sl-color-success-700);
+  }
+
+  .inline-validation sl-checkbox[data-user-valid]::part(control) {
+    background-color: var(--sl-color-success-600);
+    outline: none;
+  }
+
+  .inline-validation sl-input:focus-within[data-user-valid]::part(base) {
+    border-color: var(--sl-color-success-600);
+    box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-success-300);
+  }
+</style>
+```
+
+!> This example is meant to demonstrate the concept of providing your own error messages inline. It is not intended to scale to more complex forms. Users who want this functionality are encouraged to build a more appropriate validation solution using the techniques shown below. Depending on how you implement this feature, custom error messages may affect the accessibility of your form controls.
+
+## Getting Associated Form Controls
+
+At this time, using [`HTMLFormElement.elements`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements) will not return Shoelace form controls because the browser is unaware of their status as custom element form controls. Fortunately, Shoelace provides an `elements()` function that does something very similar. However, instead of returning an [`HTMLFormControlsCollection`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormControlsCollection), it returns an array of HTML and Shoelace form controls in the order they appear in the DOM.
+
+```js
+import { getFormControls } from '@shoelace-style/shoelace/dist/utilities/form.js';
+
+const form = document.querySelector('#my-form');
+const formControls = getFormControls(form);
+
+console.log(formControls); // e.g. [input, sl-input, ...]
+```
+
+?> You probably don't need this function! If you're gathering form data for submission, you probably want to use [Data Serialization](#data-serializing) instead.

docs/getting-started/localization.md

@@ -1,6 +1,6 @@
 # Localization
 
-Components can be localized by importing the appropriate translation file and setting the desired [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) on the `<html>` element. Here's an example that renders Shoelace components in Spanish.
+Components can be localized by importing the appropriate translation file and setting the desired [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) and/or [`dir` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir) on the `<html>` element. Here's an example that renders Shoelace components in Spanish.
 
 ```html
 <html lang="es">
@@ -57,7 +57,7 @@ If you have any questions, please start a [discussion](https://github.com/shoela
 
 ## Multiple Locales Per Page
 
-You can use a different locale for an individual component by setting its `lang` attribute. Here's a contrived example to demonstrate.
+You can use a different locale for an individual component by setting its `lang` and/or `dir` attributes. Here's a contrived example to demonstrate.
 
 ```html
 <html lang="es">
@@ -70,7 +70,7 @@ You can use a different locale for an individual component by setting its `lang`
 </html>
 ```
 
-For performance reasons, the `lang` attribute must be on the component itself, not on an ancestor element.
+For performance reasons, the `lang` and `dir` attributes must be on the component itself, not on an ancestor element.
 
 ```html
 <html lang="es">

docs/getting-started/overview.md

@@ -117,7 +117,7 @@ Designing, developing, and supporting this library requires a lot of time, effor
 
 Special thanks to the following projects and individuals that help make Shoelace possible.
 
-- Components are built with [LitElement](https://lit-element.polymer-project.org/)
+- Components are built with [Lit](https://lit.dev/)
 - Component metadata is generated by the [Custom Elements Manifest Analyzer](https://github.com/open-wc/custom-elements-manifest)
 - Documentation is powered by [Docsify](https://docsify.js.org/)
 - CDN services are provided by [jsDelivr](https://www.jsdelivr.com/)

docs/getting-started/usage.md

@@ -4,7 +4,7 @@ Shoelace components are just regular HTML elements, or [custom elements](https:/
 
 If you're new to custom elements, often referred to as "web components," this section will familiarize you with how to use them.
 
-## Properties
+## Attributes & Properties
 
 Many components have properties that can be set using attributes. For example, buttons accept a `size` attribute that maps to the `size` property which dictates the button's size.
 
@@ -18,7 +18,7 @@ Some properties are boolean, so they only have true/false values. To activate a
 <sl-button disabled>Click me</sl-button>
 ```
 
-In rare cases, a property may require an array, an object, or a function. For example, to customize the color picker's list of preset swatches, you set the `swatches` property to an array of colors. This can be done with JavaScript.
+In rare cases, a property may require an array, an object, or a function. For example, to customize the color picker's list of preset swatches, you set the `swatches` property to an array of colors. This must be done with JavaScript.
 
 ```html
 <sl-color-picker></sl-color-picker>
@@ -149,15 +149,45 @@ A clever way to use this method is to hide the `<body>` with `opacity: 0` and ad
 </script>
 ```
 
+## Component Rendering and Updating
+
+Shoelace components are built with [Lit](https://lit.dev/), a tiny library that makes authoring custom elements easier, more maintainable, and a lot of fun! As a Shoelace user, here is some helpful information about rendering and updating you should probably be aware of.
+
+To optimize performance and reduce re-renders, Lit batches component updates. This means changing multiple attributes or properties at the same time will result in just a single re-render. In most cases, this isn't an issue, but there may be times you'll need to wait for the component to update before continuing.
+
+Consider this example. We're going to change the `checked` property of the checkbox and observe its corresponding `checked` attribute, which happens to reflect.
+
+```js
+const checkbox = document.querySelector('sl-checkbox');
+checkbox.checked = true;
+
+console.log(checkbox.hasAttribute('checked')); // false
+```
+
+Most developers will expect this to be `true` instead of `false`, but the component hasn't had a chance to re-render yet so the attribute doesn't exist when `hasAttribute()` is called. Since changes are batched, we need to wait for the update before proceeding. This can be done using the `updateComplete` property, which is available on all Lit-based components.
+
+```js
+const checkbox = document.querySelector('sl-checkbox');
+checkbox.checked = true;
+
+checkbox.updateComplete.then(() => {
+  console.log(checkbox.hasAttribute('checked')); // true
+});
+```
+
+This time we see an empty string, which means the boolean attribute is now present!
+
+?> Avoid using `setTimeout()` or `requestAnimationFrame()` in situations like this. They might work, but it's far more reliable to use `updateComplete` instead.
+
 ## Code Completion
 
 ### VS Code
 
-Shoelace ships with a file called `vscode.html-custom-data.json` that can be used to describe its components to Visual Studio Code. This enables code completion for Shoelace components (also known as "code hinting" or "IntelliSense"). To enable it, you need to tell VS Code where the file is.
+Shoelace ships with a file called `vscode.html-custom-data.json` that can be used to describe it's custom elements to Visual Studio Code. This enables code completion for Shoelace components (also known as "code hinting" or "IntelliSense"). To enable it, you need to tell VS Code where the file is.
 
 1. [Install Shoelace locally](/getting-started/installation#local-installation)
-2. Create a folder called `.vscode` at the root of your project
-3. Create a file inside the folder called `settings.json`
+2. If it doesn't already exist, create a folder called `.vscode` at the root of your project
+3. If it doesn't already exist, create a file inside that folder called `settings.json`
 4. Add the following to the file
 
 ```js

docs/index.html

@@ -9,7 +9,7 @@
       content="Shoelace provides a collection of professionally designed, every day UI components built on a framework-agnostic technology."
     />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta name="custom-elements-manifest" content="dist/custom-elements.json" />
+    <meta name="custom-elements-manifest" content="/dist/custom-elements.json" />
     <meta property="og:title" content="Shoelace" />
     <meta
       property="og:description"

docs/resources/changelog.md

@@ -6,13 +6,365 @@ Components with the <sl-badge variant="warning" pill>Experimental</sl-badge> bad
 
 New versions of Shoelace are released as-needed and generally occur when a critical mass of changes have accumulated. At any time, you can see what's coming in the next release by visiting [next.shoelace.style](https://next.shoelace.style).
 
-_During the beta period, these restrictions may be relaxed in the event of a mission-critical bug._ 🐛
+## 2.2.0
+
+- Added TypeScript types to all custom events [#1183](https://github.com/shoelace-style/shoelace/pull/1183)
+- Added the `svg` part to `<sl-icon>`
+- Added the `getForm()` method to all form controls [#1180](https://github.com/shoelace-style/shoelace/issues/1180)
+- Fixed a bug in `<sl-select>` that caused the display label to render incorrectly in Chrome after form validation [#1197](https://github.com/shoelace-style/shoelace/discussions/1197)
+- Fixed a bug in `<sl-input>` that prevented users from applying their own value for `autocapitalize`, `autocomplete`, and `autocorrect` when using `type="password` [#1205](https://github.com/shoelace-style/shoelace/issues/1205)
+- Fixed a bug in `<sl-tab-group>` that prevented scroll controls from showing when dynamically adding tabs [#1208](https://github.com/shoelace-style/shoelace/issues/1208)
+- Fixed a big in `<sl-input>` that caused the calendar icon to be clipped in Firefox [#1213](https://github.com/shoelace-style/shoelace/pull/1213)
+- Fixed a bug in `<sl-tab>` that caused `sl-tab-show` to be emitted when activating the close button
+- Fixed a bug in `<sl-spinner>` that caused `--track-color` to be invisible with certain colors
+- Fixed a bug in `<sl-menu-item>` that caused the focus color to show when selecting menu items with a mouse or touch device
+- Fixed a bug in `<sl-select>` that caused `sl-change` and `sl-input` to be emitted too early [#1201](https://github.com/shoelace-style/shoelace/issues/1201)
+- Fixed a positioning edge case that caused `<sl-popup>` to positioned nested popups incorrectly [#1135](https://github.com/shoelace-style/shoelace/issues/1135)
+- Fixed a bug in `<sl-tree>` that caused the tree item to collapse when clicking a child item, dragging the mouse, and releasing it on the parent node [#1082](https://github.com/shoelace-style/shoelace/issues/1082)
+- Updated `@shoelace-style/localize` to 3.1.0
+- Updated `@floating-ui/dom` to 1.2.1
+
+When using `<input type="password">` the default value for `autocapitalize`, `autocomplete`, and `autocorrect` may be affected due to the bug fixed in [#1205](https://github.com/shoelace-style/shoelace/issues/1205). For any affected users, setting these attributes to `off` will restore the previous behavior.
+
+## 2.1.0
+
+- Added the `sl-focus` and `sl-blur` events to `<sl-color-picker>`
+- Added the `focus()` and `blur()` methods to `<sl-color-picker>`
+- Added the `sl-invalid` event to all form controls to enable custom validation logic [#1167](https://github.com/shoelace-style/shoelace/pull/1167)
+- Added `validity` and `validationMessage` properties to all form controls [#1167](https://github.com/shoelace-style/shoelace/pull/1167)
+- Added the `rel` attribute to `<sl-button>` to allow users to create button links that point to specific targets [#1200](https://github.com/shoelace-style/shoelace/issues/1200)
+- Fixed a bug in `<sl-animated-image>` where the play and pause buttons were transposed [#1147](https://github.com/shoelace-style/shoelace/issues/1147)
+- Fixed a bug that prevented `web-types.json` from being generated [#1154](https://github.com/shoelace-style/shoelace/discussions/1154)
+- Fixed a bug in `<sl-color-picker>` that prevented `sl-change` and `sl-input` from emitting when using the eye dropper [#1157](https://github.com/shoelace-style/shoelace/issues/1157)
+- Fixed a bug in `<sl-dropdown>` that prevented keyboard users from selecting menu items when using the keyboard [#1165](https://github.com/shoelace-style/shoelace/issues/1165)
+- Fixed a bug in the template for `<sl-select>` that caused the `form-control-help-text` part to not be in the same location as other form controls [#1178](https://github.com/shoelace-style/shoelace/issues/1178)
+- Fixed a bug in `<sl-checkbox>` and `<sl-switch>` that caused the browser to scroll incorrectly when focusing on a control in a container with overflow [#1169](https://github.com/shoelace-style/shoelace/issues/1169)
+- Fixed a bug in `<sl-menu-item>` that caused the `click` event to be emitted when the item was disabled [#1113](https://github.com/shoelace-style/shoelace/issues/1113)
+- Fixed a bug in form controls that erroneously prevented validation states from being set when `novalidate` was used on the containing form [#1164](https://github.com/shoelace-style/shoelace/issues/1164)
+- Fixed a bug in `<sl-checkbox>` that caused the required asterisk to appear before the label in Chrome
+- Fixed a bug that prevented large form control labels from having the correct font size [#1195](https://github.com/shoelace-style/shoelace/pull/1195)
+- Improved the behavior of `<sl-dropdown>` in Safari so keyboard interaction works the same as in other browsers [#1177](https://github.com/shoelace-style/shoelace/issues/1177)
+- Improved the [icons](/components/icon) page so it's not as sluggish in Safari [#1122](https://github.com/shoelace-style/shoelace/issues/1122)
+- Improved the accessibility of `<sl-switch>` when used in forced-colors / Windows High Contrast mode [#1114](https://github.com/shoelace-style/shoelace/issues/1114)
+- Improved user interaction heuristics for all form controls [#1175](https://github.com/shoelace-style/shoelace/issues/1175)
+
+## 2.0.0
+
+This is the first stable release of Shoelace 2, meaning breaking changes to the API will no longer be accepted for this version. Development of Shoelace 2.0 started in January 2020. The first beta was released on [July 15, 2020](https://github.com/shoelace-style/shoelace/releases/tag/v2.0.0-beta.1). Since then, Shoelace has grown quite a bit! Here are some stats from the project as of January 24, 2023:
+
+- 55 components have been built
+- [Over 2,500 commits](https://github.com/shoelace-style/shoelace/commits/next) have been made to the project
+- [88 beta versions](https://github.com/shoelace-style/shoelace/tags) have been released
+- [85 people](https://github.com/shoelace-style/shoelace/graphs/contributors) have contributed to the project
+- [669 issues](https://github.com/shoelace-style/shoelace/issues?q=is%3Aissue+is%3Aclosed) have been filed on GitHub
+- [274 pull requests](https://github.com/shoelace-style/shoelace/pulls) have been opened
+- [More than 150 discussions](https://github.com/shoelace-style/shoelace/discussions) have been started on GitHub
+- [Over 500 people](https://discord.com/invite/mg8f26C) have joined the Shoelace community on Discord
+- [Over 300 million CDN hits](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace) per month
+- [Over 13,000 npm downloads](https://www.npmjs.com/package/@shoelace-style/shoelace) per week
+- [73rd most popular project](https://www.jsdelivr.com/statistics) on jsDelivr
+- [#2 product of the day](https://www.producthunt.com/products/shoelace-css) on Product Hunt (July 25, 2020)
+
+I'd like to extend a very special thank you to every single contributor who worked to make this possible. Everyone who's filed a bug, submitted a PR, requested a feature, started a discussion, helped with testing, and advocated for the project. You are just as responsible for Shoelace's success as I am. I'd also like to thank the folks at [Font&nbsp;Awesome](https://fontawesome.com/) for recognizing Shoelace's potential and [believing in me](https://blog.fontawesome.com/shoelace-joins-font-awesome/) to make it happen.
+
+Thank you! And keep building _awesome_ stuff!
+
+Without further ado, here are the notes for this release.
+
+- Added support for the `inert` attribute on `<sl-menu-item>` to allow hidden menu items to not accept focus [#1107](https://github.com/shoelace-style/shoelace/issues/1107)
+- Added the `tag` part to `<sl-select>`
+- Added `sl-hover` event to `<sl-rating>` [#1125](https://github.com/shoelace-style/shoelace/issues/1125)
+- Added the `@documentation` tag with a link to the docs for each component
+- Added the `form` attribute to all form controls to allow placing them outside of a `<form>` element [#1130](https://github.com/shoelace-style/shoelace/issues/1130)
+- Added the `getFormControls()` function as an alternative to `HTMLFormElement.elements`
+- Added missing docs for the `header-actions` slot in `<sl-dialog>` and `<sl-drawer>`
+- Added `hue-slider-handle` and `opacity-slider-handle` parts to `<sl-color-picker>` and correct other part names in the docs [#1142](https://github.com/shoelace-style/shoelace/issues/1142)
+- Fixed a bug in `<sl-select>` that prevented placeholders from showing when `multiple` was used [#1109](https://github.com/shoelace-style/shoelace/issues/1109)
+- Fixed a bug in `<sl-select>` that caused tags to not be rounded when using the `pill` attribute [#1117](https://github.com/shoelace-style/shoelace/issues/1117)
+- Fixed a bug in `<sl-select>` where the `sl-change` and `sl-input` events didn't weren't emitted when removing tags [#1119](https://github.com/shoelace-style/shoelace/issues/1119)
+- Fixed a bug in `<sl-select>` that caused the listbox to scroll to the first selected item when selecting multiple items [#1138](https://github.com/shoelace-style/shoelace/issues/1138)
+- Fixed a bug in `<sl-select>` where the input color and input hover color wasn't using the correct design tokens [#1143](https://github.com/shoelace-style/shoelace/issues/1143)
+- Fixed a bug in `<sl-color-picker>` that logged a console error when parsing swatches with whitespace
+- Fixed a bug in `<sl-color-picker>` that caused selected colors to be wrong due to incorrect HSV calculations
+- Fixed a bug in `<sl-color-picker>` that prevented the initial value from being set correct when assigned as a property [#1141](https://github.com/shoelace-style/shoelace/issues/1141)
+- Fixed a bug in `<sl-radio-button>` that caused the checked button's right border to be incorrect [#1110](https://github.com/shoelace-style/shoelace/issues/1110)
+- Fixed a bug in `<sl-spinner>` that caused the animation to stop working correctly in Safari [#1121](https://github.com/shoelace-style/shoelace/issues/1121)
+- Fixed a bug that prevented the entire `<sl-tab-panel>` to be hidden when inactive
+- Fixed a bug that caused the value of `<sl-radio-group>` to be `undefined` depending on where the radio was activated [#1134](https://github.com/shoelace-style/shoelace/issues/1134)
+- Fixed a bug that caused body content to shift when scroll locking was enabled [#1132](https://github.com/shoelace-style/shoelace/issues/1132)
+- Fixed a bug in `<sl-icon>` that caused icons to sometimes be clipped in Safari
+- Fixed a bug that prevented label colors from inheriting by default in `<sl-checkbox>`, `<sl-radio>`, and `<sl-switch>`
+- Fixed a bug in `<sl-radio-group>` that caused an extra margin between the host element and the internal fieldset [#1139](https://github.com/shoelace-style/shoelace/issues/1139)
+- Refactored the `ShoelaceFormControl` interface to remove the `invalid` property, allowing a more intuitive API for controlling validation internally
+- Renamed the internal `FormSubmitController` to `FormControlController` to better reflect what it's used for
+- Updated Lit to 2.6.1
+- Updated Floating UI to 1.1.0
+- Updated all other dependencies to latest versions
+
+## 2.0.0-beta.88
+
+This release includes a complete rewrite of `<sl-select>` to improve accessibility and simplify its internals.
+
+- 🚨 BREAKING: rewrote `<sl-select>`
+  - Accessibility has been significantly improved, especially in screen readers
+  - You must use `<sl-option>` instead of `<sl-menu-item>` for options now
+  - The `suffix` slot was removed because it was confusing to users and its position made the clear button inaccessible
+  - The `max-tags-visible` attribute has been renamed to `max-options-visible`
+  - Many parts have been removed or renamed (please see the docs for more details)
+- 🚨 BREAKING: removed the `sl-label-change` event from `<sl-menu-item>` (listen for `slotchange` instead)
+- 🚨 BREAKING: removed type to select logic from `<sl-menu>` (this was added specifically for `<sl-select>` which no longer uses `<sl-menu>`)
+- 🚨 BREAKING: swatches in `<sl-color-picker>` are no longer present by default (but you can set them using the `swatches` attribute now)
+- 🚨 BREAKING: improved the accessibility of `<sl-menu-item>` so checked items are announced as such
+  - Checkbox menu items must now have `type="checkbox"` before applying the `checked` attribute
+  - Checkbox menu items will now toggle their `checked` state on their own when selected
+  - Disabled menu items will now receive focus, but are still not selectable
+- Added the `<sl-option>` component
+- Added Traditional Chinese translation [#1086](https://github.com/shoelace-style/shoelace/pull/1086)
+- Added support for `swatches` to be an attribute of `<sl-color-picker>` so swatches can be defined declaratively (it was previously a property; use a `;` to separate color values)
+- Fixed a bug in `<sl-tree-item>` where the checked/indeterminate states could get out of sync when using the `multiple` option [#1076](https://github.com/shoelace-style/shoelace/issues/1076)
+- Fixed a bug in `<sl-tree>` that caused `sl-selection-change` to emit before the DOM updated [#1096](https://github.com/shoelace-style/shoelace/issues/1096)
+- Fixed a bug that prevented `<sl-switch>` from submitting a default value of `on` when no value was provided [#1103](https://github.com/shoelace-style/shoelace/discussions/1103)
+- Fixed a bug in `<sl-textarea>` that caused the scrollbar to show sometimes when using `resize="auto"`
+- Fixed a bug in `<sl-input>` and `<sl-textarea>` that caused its validation states to be out of sync in some cases [#1063](https://github.com/shoelace-style/shoelace/issues/1063)
+- Reorganized all components to make class structures more consistent
+- Updated some incorrect default values for design tokens in the docs [#1097](https://github.com/shoelace-style/shoelace/issues/1097)
+- Updated non-public fields to use the `private` keyword (these were previously private only by convention, but now TypeScript will warn you)
+- Updated the hover style of `<sl-menu-item>` to be consistent with `<sl-option>`
+- Updated the status of `<sl-tree>` and `<sl-tree-item>` from experimental to stable
+- Updated React wrappers to use the latest API from `@lit-labs/react` [#1090](https://github.com/shoelace-style/shoelace/pull/1090)
+- Updated Bootstrap Icons to 1.10.3
+
+## 2.0.0-beta.87
+
+- 🚨 BREAKING: changed the default size of medium checkboxes, radios, and switches to 18px instead of 16px
+- 🚨 BREAKING: renamed the `--sl-toggle-size` design token to `--sl-toggle-size-medium`
+- Added the `--sl-toggle-size-small` and `--sl-toggle-size-large` design tokens
+- Added the `size` attribute to `<sl-checkbox>`, `<sl-radio>`, and `<sl-switch>` [#1071](https://github.com/shoelace-style/shoelace/issues/1071)
+- Added the `sl-input` event to `<sl-checkbox>`, `<sl-color-picker>`, `<sl-radio>`, `<sl-range>`, and `<sl-switch>`
+- Added HSV format to `<sl-color-picker>` [#1072](https://github.com/shoelace-style/shoelace/pull/1072)
+- Fixed a bug in `<sl-color-picker>` that sometimes prevented the color from updating when clicking or tapping on the controls
+- Fixed a bug in `<sl-color-picker>` that prevented text from being entered in the color input
+- Fixed a bug in `<sl-input>` that caused the `sl-change` event to be incorrectly emitted when the value was set programmatically [#917](https://github.com/shoelace-style/shoelace/issues/917)
+- Fixed a bug in `<sl-input>` and `<sl-textarea>` that made it impossible to disable spell checking [#1061](https://github.com/shoelace-style/shoelace/issues/1061)
+- Fixed non-modal behaviors in `<sl-drawer>` when using the `contained` attribute [#1051](https://github.com/shoelace-style/shoelace/issues/1051)
+- Fixed a bug in `<sl-checkbox>` and `<sl-radio>` that caused the checked icons to not scale property when resized
+- Fixed a bug that broke React imports [#1050](https://github.com/shoelace-style/shoelace/pull/1050)
+- Refactored `<sl-color-picker>` to use `@ctrl/tinycolor` instead of `color` saving ~67KB [#1072](https://github.com/shoelace-style/shoelace/pull/1072)
+- Removed the `formdata` event polyfill since it's now available in the last two versions of all major browsers
+
+## 2.0.0-beta.86
+
+- 🚨 BREAKING: changed the default value of `date` in `<sl-relative-time>` to the current date instead of the Unix epoch
+- 🚨 BREAKING: removed the `handle-icon` part and slot from `<sl-image-comparer>` (use `handle` instead)
+- 🚨 BREAKING: removed the `handle` slot from `<sl-split-panel>` (use the `divider` slot instead)
+- 🚨 BREAKING: removed the `--box-shadow` custom property from `<sl-alert>` (apply a box shadow to `::part(base)` instead)
+- 🚨 BREAKING: removed the `play-icon` and `pause-icon` parts (use the `play-icon` and `pause-icon` slots instead)
+- Added `header-actions` slot to `<sl-dialog>` and `<sl-drawer>`
+- Added the `expand-icon` and `collapse-icon` slots to `<sl-details>` and refactored the icon animation [#1046](https://github.com/shoelace-style/shoelace/discussions/1046)
+- Added the `play-icon` and `pause-icon` slots to `<sl-animated-image>` so you can customize the default icons
+- Converted `isTreeItem()` export to a static method of `<sl-tree-item>`
+- Fixed a bug in `<sl-tree-item>` where `sl-selection-change` was emitted when the selection didn't change [#1030](https://github.com/shoelace-style/shoelace/pull/1030)
+- Fixed a bug in `<sl-button-group>` that caused the border to render incorrectly when hovering over icons inside buttons [#1035](https://github.com/shoelace-style/shoelace/issues/1035)
+- Fixed an incorrect default for `flip-fallback-strategy` in `<sl-popup>` that caused the fallback strategy to be `initial` instead of `best-fit`, which is inconsistent with Floating UI's default [#1036](https://github.com/shoelace-style/shoelace/issues/1036)
+- Fixed a bug where browser validation tooltips would show up when hovering over form controls [#1037](https://github.com/shoelace-style/shoelace/issues/1037)
+- Fixed a bug in `<sl-tab-group>` that sometimes caused the active tab indicator to not animate
+- Fixed a bug in `<sl-tree-item>` that caused the expand/collapse icon slot to be out of sync when the node is open initially
+- Fixed the mislabeled `handle-icon` slot in `<sl-image-comparer>` (it now points to the `<slot>`, not the slot's fallback content)
+- Fixed the border radius in `<sl-dropdown>` so it matches with nested `<sl-menu>` elements
+- Fixed a bug that caused all button values to appear in submitted form data even if they weren't the submitter
+- Improved IntelliSense in VS Code, courtesy of [Burton's amazing CEM Analyzer plugin](https://github.com/break-stuff/cem-plugin-vs-code-custom-data-generator)
+- Improved accessibility of `<sl-alert>` so the alert is announced and the close button has a label
+- Improved accessibility of `<sl-progress-ring>` so slotted labels are announced along with visually hidden labels
+- Refactored all styles and animations to use `translate`, `rotate`, and `scale` instead of `transform`
+- Removed slot wrappers from many components, allowing better control over user-applied styles
+- Removed unused aria attributes from `<sl-skeleton>`
+- Replaced the `x` icon in the system icon library with `x-lg` to improve icon consistency
+
+## 2.0.0-beta.85
+
+- Fixed a bug in `<sl-dropdown>` that caused containing dialogs, drawers, etc. to close when pressing <kbd>Escape</kbd> while focused [#1024](https://github.com/shoelace-style/shoelace/issues/1024)
+- Fixed a bug in `<sl-tree-item>` that allowed lazy nodes to be incorrectly selected [#1023](https://github.com/shoelace-style/shoelace/pull/1023)
+- Fixed a typing bug in `<sl-tree-item>` [#1026](https://github.com/shoelace-style/shoelace/pull/1026)
+- Updated Floating UI to 1.0.7 to fix a bug that prevented `hoist` from working correctly in `<sl-dropdown>` after a recent update [#1024](https://github.com/shoelace-style/shoelace/issues/1024)
+
+## 2.0.0-beta.84
+
+- 🚨 BREAKING: Removed the `fieldset` property from `<sl-radio-group>` (use CSS parts if you want to keep the border) [#965](https://github.com/shoelace-style/shoelace/issues/965)
+- 🚨 BREAKING: Removed `base` and `label` parts from `<sl-radio-group>` (use `form-control` and `form-control__label` instead) [#965](https://github.com/shoelace-style/shoelace/issues/965)
+- 🚨 BREAKING: Removed the `base` part from `<sl-icon>` (style the host element directly instead)
+- 🚨 BREAKING: Removed the `invalid` attribute from form controls (use `[data-invalid]` to target it with CSS)
+- Added validation states to all form controls to allow styling based on various validation states [#1011](https://github.com/shoelace-style/shoelace/issues/1011)
+  - `data-required` - indicates that a value is required
+  - `data-optional` - indicates that a value is NOT required
+  - `data-invalid` - indicates that the form control is invalid
+  - `data-valid` - indicates that the form control is valid
+  - `data-user-invalid` - indicates the form control is invalid and the user has interacted with it
+  - `data-user-valid` - indicates the form control is valid and the user has interacted with it
+- Added npm exports [#1020](https://github.com/shoelace-style/shoelace/pull/1020)
+- Added `checkValidity()` method to all form controls
+- Added `reportValidity()` method to `<sl-range>`
+- Added `button--checked` to `<sl-radio-button>` and `control--checked` to `<sl-radio>` to style just the checked state [#933](https://github.com/shoelace-style/shoelace/pull/933)
+- Added tests for `<sl-menu>`, `<sl-menu-item>`, `<sl-menu-label>`, `<sl-rating>`, `<sl-relative-time>`, `<sl-skeleton>`, `<sl-tab-panel>` and `<sl-tag>` [#935](https://github.com/shoelace-style/shoelace/pull/935)
+  [#949](https://github.com/shoelace-style/shoelace/pull/949) [#951](https://github.com/shoelace-style/shoelace/pull/951) [#953](https://github.com/shoelace-style/shoelace/pull/953)
+  [#956](https://github.com/shoelace-style/shoelace/pull/956) [#984](https://github.com/shoelace-style/shoelace/pull/984) [#991](https://github.com/shoelace-style/shoelace/pull/991)
+- Added translations for Hungarian, Turkish, English (United Kingdom) and German (Austria) [#982](https://github.com/shoelace-style/shoelace/pull/982) [#989](https://github.com/shoelace-style/shoelace/pull/989)
+- Added `--indicator-transition-duration` custom property to `<sl-progress-ring>` [#986](https://github.com/shoelace-style/shoelace/issues/986)
+- Added `--sl-input-required-content-color` custom property to all form controls [#948](https://github.com/shoelace-style/shoelace/pull/948)
+- Added the ability to cancel `sl-show` and `sl-hide` events in `<sl-details>` [#993](https://github.com/shoelace-style/shoelace/issues/993)
+- Added `focus()` and `blur()` methods to `<sl-radio-button>`
+- Added `stepUp()` and `stepDown()` methods to `<sl-input>` and `<sl-range>` [#1013](https://github.com/shoelace-style/shoelace/pull/1013)
+- Added `showPicker()` method to `<sl-input>` [#1013](https://github.com/shoelace-style/shoelace/pull/1013)
+- Added the `handle-icon` part to `<sl-image-comparer>`
+- Added `caret`, `check`, `grip-vertical`, `indeterminate`, and `radio` icons to the system library and removed `check-lg` [#985](https://github.com/shoelace-style/shoelace/issues/985)
+- Added the `loading` attribute to `<sl-avatar>` to allow lazy loading of image avatars [#1006](https://github.com/shoelace-style/shoelace/pull/1006)
+- Added `formenctype` attribute to `<sl-button>` [#1009](https://github.com/shoelace-style/shoelace/pull/1009)
+- Added `exports` to `package.json` and removed the `main` and `module` properties [#1007](https://github.com/shoelace-style/shoelace/pull/1007)
+- Fixed a bug in `<sl-card>` that prevented the border radius to apply correctly to the header [#934](https://github.com/shoelace-style/shoelace/pull/934)
+- Fixed a bug in `<sl-button-group>` where the inner border disappeared on focus [#980](https://github.com/shoelace-style/shoelace/pull/980)
+- Fixed a bug that caused prefix/suffix animations in `<sl-input>` to wobble [#996](https://github.com/shoelace-style/shoelace/issues/996)
+- Fixed a bug in `<sl-icon>` that prevented color from being set on the host element [#999](https://github.com/shoelace-style/shoelace/issues/999)
+- Fixed a bug in `<sl-dropdown>` where the `keydown` event erroneously propagated to ancestors when pressing <kbd>Escape</kbd> [#990](https://github.com/shoelace-style/shoelace/issues/990)
+- Fixed a bug that prevented arrow keys from scrolling content within `<sl-dialog>` and `<sl-drawer>` [#925](https://github.com/shoelace-style/shoelace/issues/925)
+- Fixed a bug that prevented <kbd>Escape</kbd> from closing `<sl-dialog>` and `<sl-drawer>` in some cases
+- Fixed a bug that caused forms to submit unexpectedly when selecting certain characters [#988](https://github.com/shoelace-style/shoelace/pull/988)
+- Fixed a bug in `<sl-radio-group>` that prevented the `invalid` property from correctly reflecting validity sometimes [#992](https://github.com/shoelace-style/shoelace/issues/992)
+- Fixed a bug in `<sl-tree>` that prevented selections from working correctly on dynamically added tree items [#963](https://github.com/shoelace-style/shoelace/issues/963)
+- Fixed module paths in `custom-elements.json` so they point to the dist file instead of the source file [#725](https://github.com/shoelace-style/shoelace/issues/725)
+- Fixed an incorrect return value for `reportValidity()` in `<sl-color-picker>`
+- Improved `<sl-badge>` to improve padding and render relative to the current font size
+- Improved how many components display in forced-colors mode / Windows High Contrast mode
+  - Improved `<sl-color-picker>` so it's usable in forced-colors mode
+  - Improved `<sl-dialog>` and `<sl-drawer>` so the panel is more visible in forced-colors mode
+  - Improved `<sl-menu-item>` so selections are visible in forced-colors mode
+  - Improved `<sl-progress-bar>` so it's visible in forced-colors mode
+  - Improved `<sl-radio-button>` so checked states are visible in forced-colors mode
+  - Improved `<sl-range>` so the thumb, track, and tooltips are visible in forced-colors mode
+  - Improved `<sl-rating>` so icons are visible in forced-colors mode
+  - Improved `<sl-split-panel>` so the divider is visible in forced-colors mode
+  - Improved `<sl-tree-item>` so selected items are visible in forced-colors mode
+  - Improved `<sl-tab-group>` so tabs are cleaner and easier to understand in forced-colors mode
+- Improved positioning of the menu in `<sl-select>` so you can customize the menu width [#1018](https://github.com/shoelace-style/shoelace/issues/1018)
+- Moved all component descriptions to `@summary` to get them within documentation tools [#962](https://github.com/shoelace-style/shoelace/pull/962)
+- Refactored form controls to use the `ShoelaceFormControl` interface to improve type safety and consistency
+- Updated Lit to 2.4.1
+- Updated `@shoelace-style/localize` t0 3.0.3 to support for extended language codes
+- Updated Bootstrap Icons to 1.10.2
+- Updated TypeScript to 4.8.4
+- Updated esbuild to 0.15.14
+- Updated all other dependencies to latest versions
+
+## 2.0.0-beta.83
+
+This release removes the `<sl-responsive-media>` component. When this component was introduced, support for [`aspect-ratio`](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio)) wasn't great. These days, [the property is supported](https://caniuse.com/mdn-css_properties_aspect-ratio) by all of Shoelace's target browsers, making a dedicated component redundant.
+
+- 🚨 BREAKING: Removed `<sl-responsive-media>` (use the well-supported `aspect-ratio` CSS property instead)
+- 🚨 BREAKING: Changed the `toggle-password` attribute of `<sl-input>` to `password-toggle` for consistency
+- Added an expand/collapse animation to `<sl-tree-item>`
+- Added `sl-lazy-change` event to `<sl-tree-item>`
+- Added `expand-button` part to `<sl-tree-item>` [#893](https://github.com/shoelace-style/shoelace/pull/893)
+- Added `password-visible` attribute to `<sl-input>` [#913](https://github.com/shoelace-style/shoelace/issues/913)
+- Fixed a bug in `<sl-popup>` that didn't account for the arrow's diagonal size
+- Fixed a bug in `<sl-popup>` that caused arrow placement to be incorrect with RTL
+- Fixed a bug in `<sl-progress-ring>` that caused the indeterminate animation to stop working in Safari [#891](https://github.com/shoelace-style/shoelace/issues/891)
+- Fixed a bug in `<sl-range>` that caused it to overflow a container at 100% width [#905](https://github.com/shoelace-style/shoelace/issues/905)
+- Fixed a bug in `<sl-tree-item>` that prevented custom expand/collapse icons from rendering
+- Fixed a bug in `<sl-tree-item>` where the `expand-icon` and `collapse-icon` slots were reversed
+- Fixed a bug in `<sl-tree-item>` that prevented the keyboard from working after lazy loading [#882](https://github.com/shoelace-style/shoelace/issues/882)
+- Fixed a bug in `<sl-textarea>` that prevented the textarea from resizing automatically when setting the value programmatically [#912](https://github.com/shoelace-style/shoelace/discussions/912)
+- Fixed a handful of paths to prevent TypeScript from getting upset [#886](https://github.com/shoelace-style/shoelace/issues/886)
+- Fixed a bug in `<sl-radio-group>` where the `button-group__base` part was documented but not exposed [#909](https://github.com/shoelace-style/shoelace/discussions/909)
+- Fixed a bug in `<sl-range>` that caused the active track color to render on the wrong side in RTL [#916](https://github.com/shoelace-style/shoelace/issues/916)
+- Refactored the internal event emitter to be part of `ShoelaceElement` to reduce imports and improve DX
+- Downgraded Floating UI from 1.0.1 to 1.0.0 due to new logic that makes positioning much slower for certain components [#915](https://github.com/shoelace-style/shoelace/issues/915)
+- Upgraded the status of `<sl-animated-image>`, `<sl-popup>`, and `<sl-split-panel>` from experimental to stable
+
+## 2.0.0-beta.82
+
+- Added the `sync` and `arrow-placement` attributes to `<sl-popup>`
+- Changed the `auto-size` attribute of the experimental `<sl-popup>` component so it accepts `horizontal`, `vertical`, and `both` instead of a boolean value
+- Changed the `flip-fallback-placement` attribute of the experimental `<sl-popup>` component to `flip-fallback-placements`
+- Changed the `flip-fallback-strategy` in the experimental `<sl-popup>` component to accept `best-fit` and `initial` instead of `bestFit` and `initialPlacement`
+- Fixed a bug in `<sl-dropdown>` that caused the panel to resize horizontally when the trigger is clipped by the viewport [#860](https://github.com/shoelace-style/shoelace/issues/860)
+- Fixed a bug in `<sl-tree>` where dynamically changing slotted items wouldn't update the tree properly
+- Fixed a bug in `<sl-split-panel>` that caused the panel to stack when clicking on the divider in mobile versions of Chrome [#862](https://github.com/shoelace-style/shoelace/issues/862)
+- Fixed a bug in `<sl-popup>` that prevented flip fallbacks from working as intended
+- Fixed a bug that caused concurrent animations to work incorrectly when the durations were different [#867](https://github.com/shoelace-style/shoelace/issues/867)
+- Fixed a bug in `<sl-color-picker>` that caused the trigger and color preview to ignore opacity on first render [#869](https://github.com/shoelace-style/shoelace/issues/869)
+- Fixed a bug in `<sl-tree>` that prevented the keyboard from working when the component was nested in a shadow root [#871](https://github.com/shoelace-style/shoelace/issues/871)
+- Fixed a bug in `<sl-tab-group>` that prevented the keyboard from working when the component was nested in a shadow root [#872](https://github.com/shoelace-style/shoelace/issues/872)
+- Fixed a bug in `<sl-tab>` that allowed disabled tabs to erroneously receive focus
+- Improved single selection in `<sl-tree>` so nodes expand and collapse and receive selection when clicking on the label
+- Renamed `expanded-icon` and `collapsed-icon` slots to `expand-icon` and `collapse-icon` in the experimental `<sl-tree>` and `<sl-tree-item>` components
+- Improved RTL support for `<sl-image-comparer>`
+- Refactored components to extend from `ShoelaceElement` to make `dir` and `lang` reactive properties in all components
+
+## 2.0.0-beta.81
+
+- 🚨 BREAKING: removed the `base` part from `<sl-menu>` and removed an unnecessary `<div>` that made styling more difficult
+- Added the `anchor` property to `<sl-popup>` to support external anchors
+- Added read-only custom properties `--auto-size-available-width` and `--auto-size-available-height` to `<sl-popup>` to improve support for overflowing popup content
+- Added `label` to `<sl-rating>` to improve accessibility for screen readers
+- Added the `base__popup` and `base__arrow` parts to `<sl-tooltip>` [#858](https://github.com/shoelace-style/shoelace/issues/858)
+- Fixed a bug where auto-size wasn't being applied to `<sl-dropdown>` and `<sl-select>`
+- Fixed a bug in `<sl-popup>` that caused auto-size to kick in before flip
+- Fixed a bug in `<sl-popup>` that prevented the `arrow-padding` attribute from working as expected
+- Fixed a bug in `<sl-tooltip>` that prevented the popup from appearing with the correct z-index [#854](https://github.com/shoelace-style/shoelace/issues/854)
+- Improved accessibility of `<sl-rating>` so keyboard nav works better and screen readers announce it properly
+- Improved accessibility of `<sl-spinner>` so screen readers no longer skip over it
+- Removed a user agent sniffing notice that appeared in Chrome [#855](https://github.com/shoelace-style/shoelace/issues/855)
+- Removed the default hover effect in `<sl-tree-items>` to make selections more obvious
+- Updated Floating UI to 1.0.1
+- Updated esbuild to 0.15.1
+- Updated all other dependencies to latest versions
+
+## 2.0.0-beta.80
+
+This release breaks radio buttons, which is something that needed to happen to solve a longstanding accessibility issue where screen readers announced an incorrect number of radios, e.g. "1 of 1" instead of "1 of 3." Many attempts to solve this without breaking the existing API were made, but none worked across the board. The new implementation upgrades `<sl-radio-group>` to serve as the "form control" while `<sl-radio>` and `<sl-radio-button>` serve as options within the form control.
+
+To upgrade to this version, you will need to rework your radio controls by moving `name` up to the radio group. And instead of setting `checked` to select a specific radio, you can set `value` on the radio group and the checked item will update automatically.
+
+- 🚨 BREAKING: improved accessibility of `<sl-radio-group>`, `<sl-radio>`, and `<sl-radio-button>` so they announce properly in screen readers
+  - Added the `name` attribute to `<sl-radio-group>` and removed it from `<sl-radio>` and `<sl-radio-button>`
+  - Added the `value` attribute to `<sl-radio-group>` (use this to control which radio is checked)
+  - Added the `sl-change` event to `sl-radio-group`
+  - Added `setCustomValidity()` and `reportValidity()` to `<sl-radio-group>`
+  - Removed the `checked` attribute from `<sl-radio>` and `<sl-radio-button>` (use the radio group's `value` attribute instead)
+  - Removed the `sl-change` event from `<sl-radio>` and `<sl-radio-button>` (listen for it on the radio group instead)
+  - Removed the `invalid` attribute from `<sl-radio>` and `<sl-radio-button>`
+  - Removed `setCustomValidity()` and `reportValidity()` from `<sl-radio>` and `<sl-radio-button>` (now available on the radio group)
+- Added the experimental `<sl-popup>` component
+- Fixed a bug in `<sl-menu-item>` where labels weren't always aligned correctly
+- Fixed a bug in `<sl-range>` that caused the tooltip to be positioned incorrectly when switching between LTR/RTL
+- Refactored `<sl-dropdown>` to use `<sl-popup>`
+- Refactored `<sl-tooltip>` to use `<sl-popup>` and added the `body` part
+- Revert disabled focus behavior in `<sl-tab-group>`, `<sl-menu>`, and `<sl-tree>` to be consistent with native form controls and menus [#845](https://github.com/shoelace-style/shoelace/issues/845)
+
+## 2.0.0-beta.79
+
+- Added experimental `<sl-tree>` and `<sl-tree-item>` components [#823](https://github.com/shoelace-style/shoelace/pull/823)
+- Added `--indicator-width` custom property to `<sl-progress-ring>` [#837](https://github.com/shoelace-style/shoelace/issues/837)
+- Added Swedish translation [#838](https://github.com/shoelace-style/shoelace/pull/838)
+- Added support for `step="any"` for `<sl-input type="number">` [#839](https://github.com/shoelace-style/shoelace/issues/839)
+- Changed the type of component styles from `CSSResult` to `CSSResultGroup` [#828](https://github.com/shoelace-style/shoelace/issues/828)
+- Fixed a bug in `<sl-color-picker>` where using <kbd>Left</kbd> and <kbd>Right</kbd> would select the wrong color
+- Fixed a bug in `<sl-dropdown>` that caused the position to be incorrect on the first show when using `hoist` [#843](https://github.com/shoelace-style/shoelace/issues/843)
+- Fixed a bug in `<sl-tab-group>` where the divider was on the wrong side when using `placement="end"`
+- Fixed a bug in `<sl-tab-group>` that caused nested tab groups to scroll when using `placement="start|end"` [#815](https://github.com/shoelace-style/shoelace/issues/815)
+- Fixed a bug in `<sl-tooltip>` that caused the target to be lost after a slot change [#831](https://github.com/shoelace-style/shoelace/pull/831)
+- Fixed a bug in `<sl-tooltip>` that caused the position to be incorrect on the first show when using `hoist`
+- Improved accessibility of `<sl-tab-group>`, `<sl-tab>`, and `<sl-tab-panel>` to announce better in screen readers and by allowing focus on disabled items
+- Improved accessibility of `<sl-menu>` and `<sl-menu-item>` by allowing focus on disabled items
+- Updated Lit to 2.2.8
+- Update esbuild to 0.14.50
+- Updated Bootstrap Icons to 1.9.1
+- Updated Floating UI to 1.0.0
+- Updated all other dependencies to latest versions
 
 ## 2.0.0-beta.78
 
 - 🚨 BREAKING: Moved the `checked-icon` and `indeterminate-icon` parts from a wrapper `<span>` to the `<svg>` in `<sl-checkbox>` [#786](https://github.com/shoelace-style/shoelace/issues/786)
 - 🚨 BREAKING: Moved the `checked-icon` part from a wrapper `<span>` to the `<svg>` in `<sl-radio>` [#786](https://github.com/shoelace-style/shoelace/issues/786)
-- Added the `--track-active-offset` CSS custom property to `<sl-range>` [#806](https://github.com/shoelace-style/shoelace/issues/806)
+- Added the `--track-active-offset` custom property to `<sl-range>` [#806](https://github.com/shoelace-style/shoelace/issues/806)
 - Fixed a bug that caused `<sl-select>` to sometimes have two vertical scrollbars [#814](https://github.com/shoelace-style/shoelace/issues/814)
 - Fixed a bug that caused a gray line to appear between radio buttons [#821](https://github.com/shoelace-style/shoelace/discussions/821)
 - Fixed a bug that caused `<sl-animated-image>` to not render anything when using the `play` attribute initially [#824](https://github.com/shoelace-style/shoelace/issues/824)
@@ -210,7 +562,7 @@ _During the beta period, these restrictions may be relaxed in the event of a mis
 
 - 🚨 BREAKING: the `unit` property of `<sl-format-bytes>` has changed to `byte | bit` instead of `bytes | bits`
 - Added `display-label` part to `<sl-select>` [#650](https://github.com/shoelace-style/shoelace/issues/650)
-- Added `--spacing` CSS custom property to `<sl-divider>` [#664](https://github.com/shoelace-style/shoelace/pull/664)
+- Added `--spacing` custom property to `<sl-divider>` [#664](https://github.com/shoelace-style/shoelace/pull/664)
 - Added `event.detail.source` to the `sl-request-close` event in `<sl-dialog>` and `<sl-drawer>`
 - Fixed a bug that caused `<sl-progress-ring>` to render the wrong size when `--track-width` was increased [#656](https://github.com/shoelace-style/shoelace/issues/656)
 - Fixed a bug that allowed `<sl-details>` to open and close when disabled using a screen reader [#658](https://github.com/shoelace-style/shoelace/issues/658)
@@ -310,7 +662,7 @@ Thank you for your help and patience with testing Shoelace. I promise, we're not
 - Improved a11y of the scroll buttons in `<sl-tab-group>`
 - Improved a11y of the close button in `<sl-tab>`
 - Improved a11y of `<sl-tab-panel>` by removing an invalid `aria-selected` attribute [#579](https://github.com/shoelace-style/shoelace/issues/579)
-- Improved a11y of `<sl-icon>` by not using a variation of the `name` attribute for labels (use the `label` prop instead)
+- Improved a11y of `<sl-icon>` by not using a variation of the `name` attribute for labels (use the `label` attribute instead)
 - Moved `role` from the shadow root to the host element in `<sl-menu>`
 - Removed redundant `role="menu"` in `<sl-dropdown>`
 - Slightly faster animations for showing and hiding `<sl-dropdown>`
@@ -372,7 +724,7 @@ This release is the second attempt at unbundling dependencies. This will be a br
 Shoelace doesn't have a lot of dependencies, but this release unbundles most of them so you can potentially save some extra kilobytes. This will be a breaking change only if your configuration _does not_ support bare module specifiers. CDN users and bundler users will be unaffected.
 
 - 🚨 BREAKING: renamed the `sl-clear` event to `sl-remove`, the `clear-button` part to `remove-button`, and the `clearable` property to `removable` in `<sl-tag>`
-- Added the `disabled` prop to `<sl-resize-observer>`
+- Added the `disabled` attribute to `<sl-resize-observer>`
 - Fixed a bug in `<sl-mutation-observer>` where setting `disabled` initially didn't work
 - Unbundled dependencies and configured external imports to be packaged with bare module specifiers
 

docs/resources/contributing.md

@@ -188,8 +188,6 @@ Please do not make any changes to `prettier.config.cjs` without consulting the m
 
 Components should be composable, meaning you can easily reuse them with and within other components. This reduces the overall size of the library, expedites feature development, and maintains a consistent user experience.
 
-The `<sl-select>` component, for example, makes use of the dropdown, input, menu, and menu item components. Because it's offloading most of its functionality and styles to lower-level components, the select component remains lightweight and its appearance is consistent with other form controls and menus.
-
 ### Component Structure
 
 All components have a host element, which is a reference to the `<sl-*>` element itself. Make sure to always set the host element's `display` property to the appropriate value depending on your needs, as the default is `inline` per the custom element spec.
@@ -202,6 +200,23 @@ All components have a host element, which is a reference to the `<sl-*>` element
 
 Aside from `display`, avoid setting styles on the host element when possible. The reason for this is that styles applied to the host element are not encapsulated. Instead, create a base element that wraps the component's internals and style that instead. This convention also makes it easier to use BEM in components, as the base element can serve as the "block" entity.
 
+When authoring components, please try to follow the same structure and conventions found in other components. Classes, for example, generally follow this structure:
+
+- Static properties/methods
+- Private/public properties (that are _not_ reactive)
+- `@query` decorators
+- `@state` decorators
+- `@property` decorators
+- Lifecycle methods (`connectedCallback()`, `disconnectedCallback()`, `firstUpdated()`, etc.)
+- Private methods
+- `@watch` decorators
+- Public methods
+- The `render()` method
+
+Please avoid using the `public` keyword for class fields. It's simply too verbose when combined with decorators, property names, and arguments. However, _please do_ add `private` in front of any property or method that is intended to be private.
+
+?> This might seem like a lot, but it's fairly intuitive once you start working with the library. However, don't let this structure prevent you from submitting a PR. [Code can change](https://www.abeautifulsite.net/posts/code-can-change/) and nobody will chastise you for "getting it wrong." At the same time, encouraging consistency helps keep the library maintainable and easy for others to understand. (A lint rule that helps with things like this would be a very welcome PR!)
+
 ### Class Names
 
 All components use a [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM), so styles are completely encapsulated from the rest of the document. As a result, class names used _inside_ a component won't conflict with class names _outside_ the component, so we're free to name them anything we want.
@@ -224,12 +239,34 @@ When a component relies on the presence of slotted content to do something, don'
 
 See the source of card, dialog, or drawer for examples.
 
+### Dynamic Slot Names and Expand/Collapse Icons
+
+A pattern has been established in `<sl-details>` and `<sl-tree-item>` for expand/collapse icons that animate on open/close. In short, create two slots called `expand-icon` and `collapse-icon` and render them both in the DOM, using CSS to show/hide only one based on the current open state. Avoid conditionally rendering them. Also avoid using dynamic slot names, such as `<slot name=${open ? 'open' : 'closed'}>`, because Firefox will not animate them.
+
+There should be a container element immediately surrounding both slots. The container should be animated with CSS by default and it should have a part so the user can override the animation or disable it. Please refer to the source and documentation for `<sl-details>` and/or `<sl-tree-item>` for details.
+
+### Fallback Content in Slots
+
+When providing fallback content inside of `<slot>` elements, avoid adding parts, e.g.:
+
+```html
+<slot name="icon">
+  <sl-icon part="close-icon"></sl-icon>
+</slot>
+```
+
+This creates confusion because the part will be documented, but it won't work when the user slots in their own content. The recommended way to customize this example is for the user to slot in their own content and target its styles with CSS as needed.
+
 ### Custom Events
 
 Components must only emit custom events, and all custom events must start with `sl-` as a namespace. For compatibility with frameworks that utilize DOM templates, custom events must have lowercase, kebab-style names. For example, use `sl-change` instead of `slChange`.
 
 This convention avoids the problem of browsers lowercasing attributes, causing some frameworks to be unable to listen to them. This problem isn't specific to one framework, but [Vue's documentation](https://vuejs.org/v2/guide/components-custom-events.html#Event-Names) provides a good explanation of the problem.
 
+### Change Events
+
+When change events are emitted by Shoelace components, they should be named `sl-change` and they should only be emitted as a result of user input. Programmatic changes, such as setting `el.value = '…'` _should not_ result in a change event being emitted. This is consistent with how native form controls work.
+
 ### CSS Custom Properties
 
 To expose custom properties as part of a component's API, scope them to the `:host` block.
@@ -254,6 +291,10 @@ export default class SlExample {
 }
 ```
 
+### Focusing on Disabled Items
+
+When an item within a keyboard navigable set is disabled (e.g. tabs, trees, menu items, etc.), the disabled item _should not_ receive focus via keyboard, click, or tap. It should be skipped just like in operating system menus and in native HTML form controls. There is no exception to this. If a particular item requires focus for assistive devices to provide a good user experience, the item should not be disabled and, upon activation, it should inform the user why the respective action cannot be completed.
+
 ### When to use a property vs. a CSS custom property
 
 When designing a component's API, standard properties are generally used to change the _behavior_ of a component, whereas CSS custom properties ("CSS variables") are used to change the _appearance_ of a component. Remember that properties can't respond to media queries, but CSS variables can.
@@ -272,7 +313,7 @@ This convention can be relaxed when the developer experience is greatly improved
 
 ### Naming CSS Parts
 
-While CSS parts can be named [virtually anything](https://www.abeautifulsite.net/posts/valid-names-for-css-parts/), within Shoelace they must use the kebab-case convention and lowercase letters. Modifiers must be delimited by `--` like in BEM. This is useful for allowing users to target parts with various states, such as `my-part--focus`.
+While CSS parts can be named [virtually anything](https://www.abeautifulsite.net/posts/valid-names-for-css-parts/), within Shoelace they must use the kebab-case convention and lowercase letters. Additionally, [a BEM-inspired naming convention](https://www.abeautifulsite.net/posts/css-parts-inspired-by-bem/) is used to distinguish parts, subparts, and states.
 
 When composing elements, use `part` to export the host element and `exportparts` to export its parts.
 
@@ -288,6 +329,20 @@ render() {
 
 This results in a consistent, easy to understand structure for parts. In this example, the `icon` part will target the host element and the `icon__base` part will target the icon's `base` part.
 
+### Dependencies
+
+TL;DR – a component is a dependency if and only if it's rendered inside another component's shadow root.
+
+Many Shoelace components use other Shoelace components internally. For example, `<sl-button>` uses both `<sl-icon>` and `<sl-spinner>` for its caret icon and loading state, respectively. Since these components appear in the button's shadow root, they are considered dependencies of Button. Since dependencies are automatically loaded, users only need to import the button and everything will work as expected.
+
+Contrast this to `<sl-select>` and `<sl-option>`. At first, one might assume that Option is a dependency of Select. After all, you can't really use Select without slotting in at least one Option. However, Option _is not_ a dependency of Select! The reason is because no Option is rendered in the Select's shadow root. Since the options are provided by the user, it's up to them to import both components independently.
+
+People often suggest that Shoelace should auto-load Select + Option, Menu + Menu Item, Breadcrumb + Breadcrumb Item, etc. Although some components are designed to work together, they're technically not dependencies so eagerly loading them may not be desirable. What if someone wants to roll their own component with a superset of features? They wouldn't be able to if Shoelace automatically imported it!
+
+Similarly, in the case of `<sl-radio-group>` there was originally only `<sl-radio>`, but now you can use either `<sl-radio>` or `<sl-radio-button>` as child elements. Which component(s) should be auto-loaded dependencies in this case? Had Radio been a dependency of Radio Group, users that only wanted Radio Buttons would be forced to register both with no way to opt out and no way to provide their own customized version.
+
+For non-dependencies, _the user_ should decide what gets registered, even if it comes with a minor inconvenience.
+
 ### Form Controls
 
 Form controls should support submission and validation through the following conventions:
@@ -298,3 +353,13 @@ Form controls should support submission and validation through the following con
 - All form controls must have an `invalid` property that reflects their validity
 - All form controls should mirror their native validation attributes such as `required`, `pattern`, `minlength`, `maxlength`, etc. when possible
 - All form controls must be tested to work with the standard `<form>` element
+
+### System Icons
+
+Avoid inlining SVG icons inside of templates. If a component requires an icon, make sure `<sl-icon>` is a dependency of the component and use the [system library](/components/icon#customizing-the-system-library):
+
+```html
+<sl-icon library="system" name="..."></sl-icon>
+```
+
+This will render the icons instantly whereas the default library will fetch them from a remote source. If an icon isn't available in the system library, you will need to add it to `library.system.ts`. Using the system library ensures that all icons load instantly and are customizable by users who wish to provide a custom resolver for the system library.

docs/tokens/border-radius.md

@@ -2,11 +2,11 @@
 
 Border radius tokens are used to give sharp edges a more subtle, rounded effect. They use rem units so they scale with the base font size. The pixel values displayed are based on a 16px font size.
 
-| Token                        | Value          | Example                                                                                                  |
-| ---------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- |
-| `--sl-border-radius-small`   | 0.125rem (2px) | <div class="border-radius-demo" style="border-radius: var(--sl-border-radius-small);"></div>             |
-| `--sl-border-radius-medium`  | 0.25rem (4px)  | <div class="border-radius-demo" style="border-radius: var(--sl-border-radius-medium);"></div>            |
-| `--sl-border-radius-large`   | 0.5rem (8px)   | <div class="border-radius-demo" style="border-radius: var(--sl-border-radius-large);"></div>             |
-| `--sl-border-radius-x-large` | 1rem (16px)    | <div class="border-radius-demo" style="border-radius: var(--sl-border-radius-x-large);"></div>           |
-| `--sl-border-radius-circle`  | 50%            | <div class="border-radius-demo" style="border-radius: var(--sl-border-radius-circle);"></div>            |
-| `--sl-border-radius-pill`    | 9999px         | <div class="border-radius-demo" style="border-radius: var(--sl-border-radius-pill); width: 6rem;"></div> |
+| Token                        | Value           | Example                                                                                                  |
+| ---------------------------- | --------------- | -------------------------------------------------------------------------------------------------------- |
+| `--sl-border-radius-small`   | 0.1875rem (3px) | <div class="border-radius-demo" style="border-radius: var(--sl-border-radius-small);"></div>             |
+| `--sl-border-radius-medium`  | 0.25rem (4px)   | <div class="border-radius-demo" style="border-radius: var(--sl-border-radius-medium);"></div>            |
+| `--sl-border-radius-large`   | 0.5rem (8px)    | <div class="border-radius-demo" style="border-radius: var(--sl-border-radius-large);"></div>             |
+| `--sl-border-radius-x-large` | 1rem (16px)     | <div class="border-radius-demo" style="border-radius: var(--sl-border-radius-x-large);"></div>           |
+| `--sl-border-radius-circle`  | 50%             | <div class="border-radius-demo" style="border-radius: var(--sl-border-radius-circle);"></div>            |
+| `--sl-border-radius-pill`    | 9999px          | <div class="border-radius-demo" style="border-radius: var(--sl-border-radius-pill); width: 6rem;"></div> |

docs/tokens/more.md

@@ -0,0 +1,155 @@
+# More Design Tokens
+
+All of the design tokens described herein are considered relatively stable. However, some changes might occur in future versions to address mission critical bugs or improvements. If such changes occur, they _will not_ be considered breaking changes and will be clearly documented in the [changelog](/resources/changelog).
+
+Most design tokens are consistent across the light and dark theme. Those that vary will show both values.
+
+?> Currently, the source of design tokens is considered to be [`light.css`](https://github.com/shoelace-style/shoelace/blob/next/src/themes/light.css). The dark theme, [dark.css](https://github.com/shoelace-style/shoelace/blob/next/src/themes/dark.css), mirrors all of the same tokens with dark mode-specific values where appropriate. Work is planned to move all design tokens to a single file, perhaps JSON or YAML, in the near future.
+
+## Focus Rings
+
+Focus ring tokens control the appearance of focus rings. Note that form inputs use `--sl-input-focus-ring-*` tokens instead.
+
+| Token                    | Value                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| `--sl-focus-ring-color`  | var(--sl-color-primary-600) (light theme)<br>var(--sl-color-primary-700) (dark theme) |
+| `--sl-focus-ring-style`  | solid                                                                                 |
+| `--sl-focus-ring-width`  | 3px                                                                                   |
+| `--sl-focus-ring`        | var(--sl-focus-ring-style) var(--sl-focus-ring-width) var(--sl-focus-ring-color)      |
+| `--sl-focus-ring-offset` | 1px                                                                                   |
+
+## Buttons
+
+Button tokens control the appearance of buttons. In addition, buttons also currently use some form input tokens such as `--sl-input-height-*` and `--sl-input-border-*`. More button tokens may be added in the future to make it easier to style them more independently.
+
+| Token                          | Value                       |
+| ------------------------------ | --------------------------- |
+| `--sl-button-font-size-small`  | var(--sl-font-size-x-small) |
+| `--sl-button-font-size-medium` | var(--sl-font-size-small)   |
+| `--sl-button-font-size-large`  | var(--sl-font-size-medium)  |
+
+## Form Inputs
+
+Form input tokens control the appearance of form controls such as [input](/components/input), [select](/components/select), [textarea](/components/textarea), etc.
+
+| Token                                   | Value                            |
+| --------------------------------------- | -------------------------------- |
+| `--sl-input-height-small`               | 1.875rem; (30px @ 16px base)     |
+| `--sl-input-height-medium`              | 2.5rem; (40px @ 16px base)       |
+| `--sl-input-height-large`               | 3.125rem; (50px @ 16px base)     |
+| `--sl-input-background-color`           | var(--sl-color-neutral-0)        |
+| `--sl-input-background-color-hover`     | var(--sl-input-background-color) |
+| `--sl-input-background-color-focus`     | var(--sl-input-background-color) |
+| `--sl-input-background-color-disabled`  | var(--sl-color-neutral-100)      |
+| `--sl-input-border-color`               | var(--sl-color-neutral-300)      |
+| `--sl-input-border-color-hover`         | var(--sl-color-neutral-400)      |
+| `--sl-input-border-color-focus`         | var(--sl-color-primary-500)      |
+| `--sl-input-border-color-disabled`      | var(--sl-color-neutral-300)      |
+| `--sl-input-border-width`               | 1px                              |
+| `--sl-input-required-content`           | "\*"                             |
+| `--sl-input-required-content-offset`    | -2px                             |
+| `--sl-input-required-content-color`     | var(--sl-input-label-color)      |
+| `--sl-input-border-radius-small`        | var(--sl-border-radius-medium)   |
+| `--sl-input-border-radius-medium`       | var(--sl-border-radius-medium)   |
+| `--sl-input-border-radius-large`        | var(--sl-border-radius-medium)   |
+| `--sl-input-font-family`                | var(--sl-font-sans)              |
+| `--sl-input-font-weight`                | var(--sl-font-weight-normal)     |
+| `--sl-input-font-size-small`            | var(--sl-font-size-small)        |
+| `--sl-input-font-size-medium`           | var(--sl-font-size-medium)       |
+| `--sl-input-font-size-large`            | var(--sl-font-size-large)        |
+| `--sl-input-letter-spacing`             | var(--sl-letter-spacing-normal)  |
+| `--sl-input-color`                      | var(--sl-color-neutral-700)      |
+| `--sl-input-color-hover`                | var(--sl-color-neutral-700)      |
+| `--sl-input-color-focus`                | var(--sl-color-neutral-700)      |
+| `--sl-input-color-disabled`             | var(--sl-color-neutral-900)      |
+| `--sl-input-icon-color`                 | var(--sl-color-neutral-500)      |
+| `--sl-input-icon-color-hover`           | var(--sl-color-neutral-600)      |
+| `--sl-input-icon-color-focus`           | var(--sl-color-neutral-600)      |
+| `--sl-input-placeholder-color`          | var(--sl-color-neutral-500)      |
+| `--sl-input-placeholder-color-disabled` | var(--sl-color-neutral-600)      |
+| `--sl-input-spacing-small`              | var(--sl-spacing-small)          |
+| `--sl-input-spacing-medium`             | var(--sl-spacing-medium)         |
+| `--sl-input-spacing-large`              | var(--sl-spacing-large)          |
+| `--sl-input-focus-ring-color`           | hsl(198.6 88.7% 48.4% / 40%)     |
+| `--sl-input-focus-ring-offset`          | 0                                |
+
+## Filled Form Inputs
+
+Filled form input tokens control the appearance of form controls using the `filled` variant.
+
+| Token                                         | Value                       |
+| --------------------------------------------- | --------------------------- |
+| `--sl-input-filled-background-color`          | var(--sl-color-neutral-100) |
+| `--sl-input-filled-background-color-hover`    | var(--sl-color-neutral-100) |
+| `--sl-input-filled-background-color-focus`    | var(--sl-color-neutral-100) |
+| `--sl-input-filled-background-color-disabled` | var(--sl-color-neutral-100) |
+| `--sl-input-filled-color`                     | var(--sl-color-neutral-800) |
+| `--sl-input-filled-color-hover`               | var(--sl-color-neutral-800) |
+| `--sl-input-filled-color-focus`               | var(--sl-color-neutral-700) |
+| `--sl-input-filled-color-disabled`            | var(--sl-color-neutral-800) |
+
+## Form Labels
+
+Form label tokens control the appearance of labels in form controls.
+
+| Token                               | Value                      |
+| ----------------------------------- | -------------------------- |
+| `--sl-input-label-font-size-small`  | var(--sl-font-size-small)  |
+| `--sl-input-label-font-size-medium` | var(--sl-font-size-medium) |
+| `--sl-input-label-font-size-large`  | var(--sl-font-size-large)  |
+| `--sl-input-label-color`            | inherit                    |
+
+## Help Text
+
+Help text tokens control the appearance of help text in form controls.
+
+| Token                                   | Value                       |
+| --------------------------------------- | --------------------------- |
+| `--sl-input-help-text-font-size-small`  | var(--sl-font-size-x-small) |
+| `--sl-input-help-text-font-size-medium` | var(--sl-font-size-small)   |
+| `--sl-input-help-text-font-size-large`  | var(--sl-font-size-medium)  |
+| `--sl-input-help-text-color`            | var(--sl-color-neutral-500) |
+
+## Toggles
+
+Toggle tokens control the appearance of toggles such as [checkbox](/components/checkbox), [radio](/components/radio), [switch](/components/switch), etc.
+
+| Token                     | Value                       |
+| ------------------------- | --------------------------- |
+| `--sl-toggle-size-small`  | 0.875rem (14px @ 16px base) |
+| `--sl-toggle-size-medium` | 1.125rem (18px @ 16px base) |
+| `--sl-toggle-size-large`  | 1.375rem (22px @ 16px base) |
+
+## Overlays
+
+Overlay tokens control the appearance of overlays as used in [dialog](/components/dialog), [drawer](/components/drawer), etc.
+
+| Token                           | Value                     |
+| ------------------------------- | ------------------------- |
+| `--sl-overlay-background-color` | hsl(240 3.8% 46.1% / 33%) |
+
+## Panels
+
+Panel tokens control the appearance of panels such as those used in [dialog](/components/dialog), [drawer](/components/drawer), [menu](/components/menu), etc.
+
+| Token                         | Value                       |
+| ----------------------------- | --------------------------- |
+| `--sl-panel-background-color` | var(--sl-color-neutral-0)   |
+| `--sl-panel-border-color`     | var(--sl-color-neutral-200) |
+| `--sl-panel-border-width`     | 1px                         |
+
+## Tooltips
+
+Tooltip tokens control the appearance of tooltips. This includes the [tooltip](/components/tooltip) component as well as other implementations, such [range tooltips](/components/range).
+
+| Token                           | Value                                                |
+| ------------------------------- | ---------------------------------------------------- |
+| `--sl-tooltip-border-radius`    | var(--sl-border-radius-medium)                       |
+| `--sl-tooltip-background-color` | var(--sl-color-neutral-800)                          |
+| `--sl-tooltip-color`            | var(--sl-color-neutral-0)                            |
+| `--sl-tooltip-font-family`      | var(--sl-font-sans)                                  |
+| `--sl-tooltip-font-weight`      | var(--sl-font-weight-normal)                         |
+| `--sl-tooltip-font-size`        | var(--sl-font-size-small)                            |
+| `--sl-tooltip-line-height`      | var(--sl-line-height-dense)                          |
+| `--sl-tooltip-padding`          | var(--sl-spacing-2x-small) var(--sl-spacing-x-small) |
+| `--sl-tooltip-arrow-size`       | 6px                                                  |

docs/tokens/typography.md

@@ -10,7 +10,7 @@ The default font stack is designed to be simple and highly available on as many
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
 | `--sl-font-sans`  | -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol' | <span style="font-family: var(--sl-font-sans)">The quick brown fox jumped over the lazy dog.</span>  |
 | `--sl-font-serif` | Georgia, 'Times New Roman', serif                                                                                                             | <span style="font-family: var(--sl-font-serif)">The quick brown fox jumped over the lazy dog.</span> |
-| `--sl-font-mono`  | Menlo, Monaco, 'Courier New', monospace                                                                                                       | <span style="font-family: var(--sl-font-mono)">The quick brown fox jumped over the lazy dog.</span>  |
+| `--sl-font-mono`  | SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace;                                                                                | <span style="font-family: var(--sl-font-mono)">The quick brown fox jumped over the lazy dog.</span>  |
 
 ## Font Size
 
@@ -41,18 +41,18 @@ Font sizes use `rem` units so they scale with the base font size. The pixel valu
 
 | Token                        | Value    | Example                                                                                                             |
 | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
-| `--sl-letter-spacing-denser` | ?        | <span style="letter-spacing: var(--sl-letter-spacing-denser);">The quick brown fox jumped over the lazy dog.</span> |
+| `--sl-letter-spacing-denser` | -0.03em  | <span style="letter-spacing: var(--sl-letter-spacing-denser);">The quick brown fox jumped over the lazy dog.</span> |
 | `--sl-letter-spacing-dense`  | -0.015em | <span style="letter-spacing: var(--sl-letter-spacing-dense);">The quick brown fox jumped over the lazy dog.</span>  |
 | `--sl-letter-spacing-normal` | normal   | <span style="letter-spacing: var(--sl-letter-spacing-normal);">The quick brown fox jumped over the lazy dog.</span> |
 | `--sl-letter-spacing-loose`  | 0.075em  | <span style="letter-spacing: var(--sl-letter-spacing-loose);">The quick brown fox jumped over the lazy dog.</span>  |
-| `--sl-letter-spacing-looser` | ?        | <span style="letter-spacing: var(--sl-letter-spacing-looser);">The quick brown fox jumped over the lazy dog.</span> |
+| `--sl-letter-spacing-looser` | 0.15em   | <span style="letter-spacing: var(--sl-letter-spacing-looser);">The quick brown fox jumped over the lazy dog.</span> |
 
 ## Line Height
 
 | Token                     | Value | Example                                                                                                                                                                                                       |
 | ------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--sl-line-height-denser` | ?     | <div style="line-height: var(--sl-line-height-denser);">The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.</div> |
+| `--sl-line-height-denser` | 1     | <div style="line-height: var(--sl-line-height-denser);">The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.</div> |
 | `--sl-line-height-dense`  | 1.4   | <div style="line-height: var(--sl-line-height-dense);">The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.</div>  |
 | `--sl-line-height-normal` | 1.8   | <div style="line-height: var(--sl-line-height-normal);">The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.</div> |
 | `--sl-line-height-loose`  | 2.2   | <div style="line-height: var(--sl-line-height-loose);">The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.</div>  |
-| `--sl-line-height-looser` | ?     | <div style="line-height: var(--sl-line-height-looser);">The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.</div> |
+| `--sl-line-height-looser` | 2.6   | <div style="line-height: var(--sl-line-height-looser);">The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.<br>The quick brown fox jumped over the lazy dog.</div> |

docs/tutorials/integrating-with-laravel.md

@@ -1,6 +1,6 @@
 # Integrating with Laravel
 
-This page explains how to integrate Shoelace with a [Laravel](https://laravel.com) app using a local Webpack bundle.
+This page explains how to integrate Shoelace with a [Laravel 9](https://laravel.com) app using Vite. For additional details refer to the [Bundling Assets (Vite)](https://laravel.com/docs/9.x/vite) section in the official Laravel docs.
 
 ?> This is a community-maintained document. Please [ask the community](/resources/community) if you have questions about this integration. You can also [suggest improvements](https://github.com/shoelace-style/shoelace/blob/next/docs/tutorials/integrating-with-laravel.md) to make it better.
 
@@ -8,13 +8,12 @@ This page explains how to integrate Shoelace with a [Laravel](https://laravel.co
 
 This integration has been tested with the following:
 
-- Laravel >= 8
-- Node >= 14.17
-- Laravel Mix >= 6
+- Laravel 9.1
+- Vite 3.0
 
 ## Instructions
 
-These instructions assume an out of the box [Laravel 8+ install](https://laravel.com/docs/8.x/installation) that uses [Laravel Mix](https://laravel.com/docs/8.x/mix) to compile assets.
+These instructions assume a default [Laravel 9 install](https://laravel.com/docs/9.x/installation) that uses [Vite](https://vitejs.dev/) to bundle assets.
 Be sure to run `npm install` to install the default Laravel front-end dependencies before installing Shoelace.
 
 ### Install the Shoelace package
@@ -25,7 +24,7 @@ npm install @shoelace-style/shoelace
 
 ### Import the Default Theme
 
-Import Shoelace's default theme (stylesheet) in `/resources/css/app.css`:
+Import the Shoelace default theme (stylesheet) in `/resources/css/app.css`:
 
 ```css
 @import '/node_modules/@shoelace-style/shoelace/dist/themes/light.css';
@@ -33,14 +32,20 @@ Import Shoelace's default theme (stylesheet) in `/resources/css/app.css`:
 
 ### Import Your Shoelace Components
 
-Import each Shoelace component you plan to use in `/resources/js/bootstrap.js`. Since [Laravel Mix](https://laravel.com/docs/8.x/mix) uses Webpack, use the full path to each component -- as outlined in the [Cherry Picking instructions](https://shoelace.style/getting-started/installation?id=cherry-picking). You can find the full import statement for a component in the _Importing_ section of the component's documentation (use the _Bundler_ import). Your imports should look similar to:
+Import each Shoelace component you plan to use in `/resources/js/bootstrap.js`. Use the full path to each component (as outlined in the [Cherry Picking instructions](https://shoelace.style/getting-started/installation?id=cherry-picking)). You can find the full import statement for a component in the _Importing_ section of the component's documentation (use the _Bundler_ import). Your imports should look similar to:
 
 ```js
 import '@shoelace-style/shoelace/dist/components/button/button.js';
+import '@shoelace-style/shoelace/dist/components/icon/icon.js';
 import '@shoelace-style/shoelace/dist/components/dialog/dialog.js';
-import '@shoelace-style/shoelace/dist/components/drawer/drawer.js';
-import '@shoelace-style/shoelace/dist/components/menu/menu.js';
-import '@shoelace-style/shoelace/dist/components/menu-item/menu-item.js';
+```
+
+### Copy the Shoelace Static Assets (icons, images, etc.) to a Public Folder
+
+Since Vite has no way to copy arbitrary assets into your build (like webpack), you need to manually copy the Shoelace static assets to your project's public folder. Run this command from your project's root directory to copy the Shoelace static assets to the `./public/assets` folder:
+
+```sh
+cp -aR node_modules/@shoelace-style/shoelace/dist/assets/ ./public/assets
 ```
 
 ### Set the Base Path
@@ -52,66 +57,50 @@ import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path.j
 setBasePath('/');
 ```
 
-Here's an example `/resources/js/bootstrap.js` file, after importing and setting the base path and components.
+Example `/resources/js/bootstrap.js` file:
 
 ```js
 import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path.js';
-setBasePath('/assets');
+setBasePath('/');
 
 import '@shoelace-style/shoelace/dist/components/button/button.js';
+import '@shoelace-style/shoelace/dist/components/icon/icon.js';
 import '@shoelace-style/shoelace/dist/components/dialog/dialog.js';
-import '@shoelace-style/shoelace/dist/components/drawer/drawer.js';
-import '@shoelace-style/shoelace/dist/components/menu/menu.js';
-import '@shoelace-style/shoelace/dist/components/menu-item/menu-item.js';
 ```
 
-### Configure Laravel Mix
+### Verify Vite Entry Points
 
-[Laravel Mix](https://laravel.com/docs/8.x/mix) is a wrapper around Webpack that simplifies configuration. Mix is used by default for compiling front-end assets in Laravel.
-
-Modify `webpack.mix.js` to add Shoelace's assets to Webpack's build process:
+Laravel pre-configures the Vite entry points in `vite.config.js` as `resources/css/app.css` and `resources/js/app.js`. If you use a different location for your CSS and/or Javascript entry point, update this configuration to accordingly.
 
 ```js
-mix
-  .js('resources/js/app.js', 'public/js')
-  .postCss('resources/css/app.css', 'public/css', [])
-  .copy('node_modules/@shoelace-style/shoelace/dist/assets', 'public/assets');
-```
-
-Consider [extracting vendor libraries](https://laravel.com/docs/8.x/mix#vendor-extraction) to a separate file. This splits frequently updated vendor libraries (like Shoelace) from your front-end application code -- for better long-term caching.
-Here's an example `webpack.mix.js` file that compiles and splits your JS into `app.js` and `vendor.js` files, and builds an optimized CSS bundle using PostCSS.
-
-```js
-mix
-  .js('resources/js/app.js', 'public/js')
-  .postCss('resources/css/app.css', 'public/css', [])
-  .copy('node_modules/@shoelace-style/shoelace/dist/assets', 'public/assets')
-  .extract(); // extracts libraries in node_modules to vendor.js
+plugins: [
+        laravel({
+            input: ["resources/css/app.css", "resources/js/app.js"],
+            refresh: true,
+        }),
+    ],
 ```
 
 ### Compile Front-End Assets
 
-Run the [Laravel Mix](https://laravel.com/docs/8.x/mix) npm scripts to build your application's CSS and JavaScript code.
+Run the Vite development server or production build.
 
 ```bash
-## build a development bundle
+## run the Vite development bundle
 npm run dev
 
-## build a production bundle
-npm run prod
+## build a production bundle (with versioning)
+npm run build
 ```
 
 ### Include Front-End Assets in Your Layout File
 
-Most full-stack Laravel applications use [layouts](https://laravel.com/docs/8.x/blade#building-layouts) to define the basic structure of a page.
-After compiling your front-end assets (above), include them in your top-level layouts/templates. The following example uses the [Laravel asset helper](https://laravel.com/docs/8.x/helpers#method-asset) to generate a full URL.
+Add the `@vite()` Blade directive to the `<head>` of your application's root template.
 
 ```html
-<script defer src="{{ asset('js/manifest.js') }}"></script>
-<script defer src="{{ asset('js/vendor.js') }}"></script>
-<script defer src="{{ asset('/js/app.js') }}"></script>
-
-<link href="{{ asset('css/app.css') }}" rel="stylesheet" />
+<head>
+  ... @vite(['resources/css/app.css', 'resources/js/app.js'])
+</head>
 ```
 
 Have fun using Shoelace components in your Laravel app!

package.json

@@ -1,16 +1,26 @@
 {
   "name": "@shoelace-style/shoelace",
   "description": "A forward-thinking library of web components.",
-  "version": "2.0.0-beta.78",
+  "version": "2.2.0",
   "homepage": "https://github.com/shoelace-style/shoelace",
   "author": "Cory LaViska",
   "license": "MIT",
-  "main": "dist/shoelace.js",
-  "module": "dist/shoelace.js",
   "customElements": "dist/custom-elements.json",
   "web-types": "dist/web-types.json",
   "type": "module",
   "types": "dist/shoelace.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/shoelace.d.ts",
+      "import": "./dist/shoelace.js"
+    },
+    "./dist/themes/*": "./dist/themes/*",
+    "./dist/components/*": "./dist/components/*",
+    "./dist/utilities/*": "./dist/utilities/*",
+    "./dist/react": "./dist/react/index.js",
+    "./dist/react/*": "./dist/react/*",
+    "./dist/translations/*": "./dist/translations/*"
+  },
   "files": [
     "dist"
   ],
@@ -41,72 +51,76 @@
     "lint:fix": "eslint src --max-warnings 0 --fix",
     "ts-check": "tsc --noEmit --project ./tsconfig.json",
     "create": "plop --plopfile scripts/plop/plopfile.js",
-    "test": "web-test-runner",
-    "test:component": "npm run test -- --group",
-    "test:watch": "web-test-runner --watch",
+    "test": "web-test-runner --group default",
+    "test:component": "web-test-runner -- --watch --group",
+    "test:watch": "web-test-runner --watch --group default",
     "spellcheck": "cspell \"**/*.{js,ts,json,html,css,md}\" --no-progress",
     "list-outdated-dependencies": "npm-check-updates --format repo --peer",
-    "update-dependencies": "npm-check-updates --peer -u && npm install && npm run lint:fix && npm run prettier && npm run verify"
+    "update-dependencies": "npm-check-updates --peer -u && npm install"
   },
   "engines": {
     "node": ">=14.17.0"
   },
   "dependencies": {
-    "@floating-ui/dom": "^0.5.4",
-    "@lit-labs/react": "^1.0.6",
+    "@ctrl/tinycolor": "^3.5.0",
+    "@floating-ui/dom": "^1.2.1",
+    "@lit-labs/react": "^1.1.1",
     "@shoelace-style/animations": "^1.1.0",
-    "@shoelace-style/localize": "^3.0.0",
-    "color": "4.2",
-    "lit": "^2.2.7",
+    "@shoelace-style/localize": "^3.1.0",
+    "composed-offset-position": "^0.0.4",
+    "lit": "^2.6.1",
     "qr-creator": "^1.0.0"
   },
   "devDependencies": {
-    "@custom-elements-manifest/analyzer": "^0.6.3",
-    "@open-wc/testing": "^3.1.6",
-    "@types/color": "^3.0.3",
-    "@types/mocha": "^9.1.1",
-    "@types/react": "^18.0.15",
-    "@typescript-eslint/eslint-plugin": "^5.30.6",
-    "@typescript-eslint/parser": "^5.30.6",
-    "@web/dev-server-esbuild": "^0.3.1",
-    "@web/test-runner": "^0.13.31",
-    "@web/test-runner-commands": "^0.6.3",
-    "@web/test-runner-playwright": "^0.8.9",
-    "bootstrap-icons": "^1.9.0",
-    "browser-sync": "^2.27.10",
-    "chalk": "^5.0.1",
+    "@custom-elements-manifest/analyzer": "^0.6.8",
+    "@open-wc/testing": "^3.1.7",
+    "@types/mocha": "^10.0.1",
+    "@types/react": "^18.0.26",
+    "@typescript-eslint/eslint-plugin": "^5.48.1",
+    "@typescript-eslint/parser": "^5.48.1",
+    "@web/dev-server-esbuild": "^0.3.3",
+    "@web/test-runner": "^0.15.0",
+    "@web/test-runner-commands": "^0.6.5",
+    "@web/test-runner-playwright": "^0.9.0",
+    "bootstrap-icons": "^1.10.3",
+    "browser-sync": "^2.27.11",
+    "cem-plugin-vs-code-custom-data-generator": "^1.4.1",
+    "chalk": "^5.2.0",
     "command-line-args": "^5.2.1",
     "comment-parser": "^1.3.1",
-    "cspell": "^6.2.3",
-    "del": "^6.1.1",
+    "cspell": "^6.18.1",
+    "del": "^7.0.0",
     "download": "^8.0.0",
-    "esbuild": "^0.14.49",
-    "eslint": "^8.19.0",
+    "esbuild": "^0.16.17",
+    "eslint": "^8.31.0",
     "eslint-plugin-chai-expect": "^3.0.0",
     "eslint-plugin-chai-friendly": "^0.7.2",
-    "eslint-plugin-import": "^2.26.0",
-    "eslint-plugin-lit": "^1.6.1",
-    "eslint-plugin-lit-a11y": "^2.2.0",
-    "eslint-plugin-markdown": "^2.2.1",
-    "eslint-plugin-wc": "^1.3.2",
+    "eslint-plugin-import": "^2.27.4",
+    "eslint-plugin-lit": "^1.8.2",
+    "eslint-plugin-lit-a11y": "^2.3.0",
+    "eslint-plugin-markdown": "^3.0.0",
+    "eslint-plugin-sort-imports-es6-autofix": "^0.6.0",
+    "eslint-plugin-wc": "^1.4.0",
     "front-matter": "^4.0.2",
     "get-port": "^6.1.2",
-    "globby": "^13.1.2",
-    "husky": "^8.0.1",
-    "jsonata": "^1.8.6",
-    "lint-staged": "^13.0.3",
+    "globby": "^13.1.3",
+    "husky": "^8.0.3",
+    "jsonata": "^2.0.1",
+    "lint-staged": "^13.1.0",
     "lunr": "^2.3.9",
-    "npm-check-updates": "^15.3.3",
+    "npm-check-updates": "^16.6.2",
     "open": "^8.4.0",
     "pascal-case": "^3.1.2",
     "plop": "^3.1.1",
-    "prettier": "^2.7.1",
+    "prettier": "^2.8.2",
     "react": "^18.2.0",
     "recursive-copy": "^2.0.14",
-    "sinon": "^14.0.0",
+    "sinon": "^15.0.1",
+    "source-map": "^0.7.4",
     "strip-css-comments": "^5.0.0",
-    "tslib": "^2.4.0",
-    "typescript": "4.7.4"
+    "tslib": "^2.4.1",
+    "typescript": "4.9.4",
+    "user-agent-data-types": "^0.3.0"
   },
   "lint-staged": {
     "*.{ts,js}": [

scripts/build.js

@@ -2,7 +2,7 @@ import browserSync from 'browser-sync';
 import chalk from 'chalk';
 import { execSync } from 'child_process';
 import commandLineArgs from 'command-line-args';
-import del from 'del';
+import { deleteSync } from 'del';
 import esbuild from 'esbuild';
 import fs from 'fs';
 import getPort, { portNumbers } from 'get-port';
@@ -20,7 +20,7 @@ const { bundle, copydir, dir, serve, types } = commandLineArgs([
 
 const outdir = dir;
 
-del.sync(outdir);
+deleteSync(outdir);
 fs.mkdirSync(outdir, { recursive: true });
 
 (async () => {
@@ -28,7 +28,6 @@ fs.mkdirSync(outdir, { recursive: true });
     execSync(`node scripts/make-metadata.js --outdir "${outdir}"`, { stdio: 'inherit' });
     execSync(`node scripts/make-search.js --outdir "${outdir}"`, { stdio: 'inherit' });
     execSync(`node scripts/make-react.js --outdir "${outdir}"`, { stdio: 'inherit' });
-    execSync(`node scripts/make-vscode-data.js --outdir "${outdir}"`, { stdio: 'inherit' });
     execSync(`node scripts/make-web-types.js --outdir "${outdir}"`, { stdio: 'inherit' });
     execSync(`node scripts/make-themes.js --outdir "${outdir}"`, { stdio: 'inherit' });
     execSync(`node scripts/make-icons.js --outdir "${outdir}"`, { stdio: 'inherit' });
@@ -47,6 +46,9 @@ fs.mkdirSync(outdir, { recursive: true });
       format: 'esm',
       target: 'es2017',
       entryPoints: [
+        //
+        // NOTE: Entry points must be mapped in package.json > exports, otherwise users won't be able to import them!
+        //
         // The whole shebang
         './src/shoelace.ts',
         // Components
@@ -87,7 +89,7 @@ fs.mkdirSync(outdir, { recursive: true });
 
   // Copy the build output to an additional directory
   if (copydir) {
-    del.sync(copydir);
+    deleteSync(copydir);
     copy(outdir, copydir);
   }
 
@@ -101,7 +103,7 @@ fs.mkdirSync(outdir, { recursive: true });
     });
 
     // Make sure docs/dist is empty since we're serving it virtually
-    del.sync('docs/dist');
+    deleteSync('docs/dist');
 
     const browserSyncConfig = {
       open: false,
@@ -118,36 +120,14 @@ fs.mkdirSync(outdir, { recursive: true });
         routes: {
           '/dist': './dist'
         }
-      },
-      socket: {
-        socketIoClientConfig: {
-          // Configure socketIO to retry forever when disconnected to enable the auto-reattach timeout below to work
-          reconnectionAttempts: Infinity,
-          reconnectionDelay: 500,
-          reconnectionDelayMax: 500,
-          timeout: 1000
-        }
       }
     };
 
     // Launch browser sync
     bs.init(browserSyncConfig, () => {
-      // This init callback gets executed after the server has started
-      const socketIoConfig = browserSyncConfig.socket.socketIoClientConfig;
-
-      // Wait enough time for any open, detached clients to have a chance to reconnect. This will be used to determine
-      // if we reload an existing tab or open a new one.
-      const tabReattachDelay = socketIoConfig.reconnectionDelayMax * 2 + socketIoConfig.timeout;
-
-      setTimeout(() => {
-        const url = `http://localhost:${port}`;
-        console.log(chalk.cyan(`Launched the Shoelace dev server at ${url} 🥾\n`));
-        if (Object.keys(bs.sockets.sockets).length === 0) {
-          open(url);
-        } else {
-          bs.reload();
-        }
-      }, tabReattachDelay);
+      const url = `http://localhost:${port}`;
+      console.log(chalk.cyan(`Launched the Shoelace dev server at ${url} 🥾\n`));
+      open(url);
     });
 
     // Rebuild and reload when source files change

scripts/make-icons.js

@@ -4,7 +4,7 @@
 import chalk from 'chalk';
 import commandLineArgs from 'command-line-args';
 import copy from 'recursive-copy';
-import del from 'del';
+import { deleteAsync } from 'del';
 import download from 'download';
 import fm from 'front-matter';
 import { readFileSync, mkdirSync } from 'fs';
@@ -35,7 +35,7 @@ let numIcons = 0;
 
     // Copy icons
     console.log(`Copying icons and license`);
-    await del([iconDir]);
+    await deleteAsync([iconDir]);
     mkdirSync(iconDir, { recursive: true });
     await Promise.all([
       copy(`${srcPath}/icons`, iconDir),

scripts/make-react.js

@@ -2,8 +2,7 @@ import commandLineArgs from 'command-line-args';
 import fs from 'fs';
 import path from 'path';
 import chalk from 'chalk';
-import del from 'del';
-import { pascalCase } from 'pascal-case';
+import { deleteSync } from 'del';
 import prettier from 'prettier';
 import prettierConfig from '../prettier.config.cjs';
 import { getAllComponents } from './shared.js';
@@ -13,7 +12,7 @@ const { outdir } = commandLineArgs({ name: 'outdir', type: String });
 const reactDir = path.join('./src/react');
 
 // Clear build directory
-del.sync(reactDir);
+deleteSync(reactDir);
 fs.mkdirSync(reactDir, { recursive: true });
 
 // Fetch component metadata
@@ -29,7 +28,7 @@ components.map(component => {
   const tagWithoutPrefix = component.tagName.replace(/^sl-/, '');
   const componentDir = path.join(reactDir, tagWithoutPrefix);
   const componentFile = path.join(componentDir, 'index.ts');
-  const importPath = component.modulePath.replace(/^src\//, '').replace(/\.ts$/, '');
+  const importPath = component.path;
   const events = (component.events || []).map(event => `${event.reactName}: '${event.name}'`).join(',\n');
 
   fs.mkdirSync(componentDir, { recursive: true });
@@ -40,14 +39,14 @@ components.map(component => {
       import { createComponent } from '@lit-labs/react';
       import Component from '../../${importPath}';
 
-      export default createComponent(
-        React,
-        '${component.tagName}',
-        Component,
-        {
+      export default createComponent({
+        tagName: '${component.tagName}',
+        elementClass: Component,
+        react: React,
+        events: {
           ${events}
         }
-      );
+      });
     `,
     Object.assign(prettierConfig, {
       parser: 'babel-ts'

scripts/make-search.js

@@ -15,7 +15,7 @@ console.log('Generating search index for documentation');
     const headings = [];
     const lines = markdown.split('\n');
 
-    lines.map(line => {
+    lines.forEach(line => {
       if (line.startsWith('#')) {
         const level = line.match(/^(#+)/)[0].length;
         const content = line.replace(/^#+/, '');
@@ -37,16 +37,16 @@ console.log('Generating search index for documentation');
       return '';
     }
 
-    headers.map(header => {
+    headers.forEach(header => {
       const tagName = header.match(/\[component-header:([a-z-]+)\]/)[1];
       const component = getAllComponents(metadata).find(component => component.tagName === tagName);
 
       if (component) {
         const fields = ['members', 'cssProperties', 'cssParts', 'slots', 'events'];
 
-        fields.map(field => {
+        fields.forEach(field => {
           if (component[field]) {
-            component[field].map(entry => {
+            component[field].forEach(entry => {
               if (entry.name) members.push(entry.name);
               if (entry.description) members.push(entry.description);
               if (entry.attribute) members.push(entry.attribute);
@@ -70,13 +70,18 @@ console.log('Generating search index for documentation');
     this.field('m', { boost: 2 }); // members (props, methods, events, etc.)
     this.field('c'); // content
 
-    files.map((file, index) => {
+    files.forEach((file, index) => {
       const relativePath = path.relative('./docs', file).replace(/\\/g, '/');
       const relativePathNoExtension = relativePath.split('.').slice(0, -1).join('.');
       const url = relativePath.replace(/\.md$/, '');
       const filename = path.basename(file);
       // Ignore certain directories and files
-      if (relativePath.startsWith('assets/') || relativePath.startsWith('dist/') || filename === '_sidebar.md') {
+      if (
+        relativePath.startsWith('assets/') ||
+        relativePath.startsWith('dist/') ||
+        filename === '_sidebar.md' ||
+        filename === '404.md'
+      ) {
         return false;
       }
 

scripts/make-vscode-data.js

@@ -1,58 +0,0 @@
-//
-// This script generates vscode.html-custom-data.json (for IntelliSense).
-//
-// You must generate dist/custom-elements.json before running this script.
-//
-import commandLineArgs from 'command-line-args';
-import fs from 'fs';
-import path from 'path';
-import { getAllComponents } from './shared.js';
-
-const { outdir } = commandLineArgs({ name: 'outdir', type: String });
-const metadata = JSON.parse(fs.readFileSync(path.join(outdir, 'custom-elements.json'), 'utf8'));
-
-console.log('Generating custom data for VS Code');
-
-const components = getAllComponents(metadata);
-const vscode = { tags: [] };
-
-components.map(component => {
-  const name = component.tagName;
-  const attributes = component.attributes?.map(attr => {
-    const type = attr.type?.text;
-    let values = [];
-
-    if (type) {
-      type.split('|').map(val => {
-        val = val.trim();
-
-        // Only accept values that are strings and numbers
-        const isString = val.startsWith(`'`);
-        const isNumber = Number(val).toString() === val;
-
-        if (isString) {
-          // Remove quotes
-          val = val.replace(/^'/, '').replace(/'$/, '');
-        }
-
-        if (isNumber || isString) {
-          values.push({ name: val });
-        }
-      });
-    }
-
-    if (values.length === 0) {
-      values = undefined;
-    }
-
-    return {
-      name: attr.name,
-      description: attr.description,
-      values
-    };
-  });
-
-  vscode.tags.push({ name, attributes });
-});
-
-fs.writeFileSync(path.join(outdir, 'vscode.html-custom-data.json'), JSON.stringify(vscode, null, 2), 'utf8');

scripts/make-web-types.js

@@ -64,6 +64,7 @@ const jsonataExprString = `{
 
 // Run the conversion
 const expression = jsonata(jsonataExprString);
+const result = await expression.evaluate(metadata);
 
 console.log('Generating web types');
-fs.writeFileSync(path.join(outdir, 'web-types.json'), JSON.stringify(expression.evaluate(metadata), null, 2), 'utf8');
+fs.writeFileSync(path.join(outdir, 'web-types.json'), JSON.stringify(result, null, 2), 'utf8');

scripts/plop/templates/component/component.hbs

@@ -1,12 +1,16 @@
-import { LitElement, html } from 'lit';
+import { html } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
-import { emit } from '../../internal/event';
+import ShoelaceElement from '../../internal/shoelace-element';
 import { watch } from '../../internal/watch';
+import { LocalizeController } from '../../utilities/localize';
 import styles from './{{ tagWithoutPrefix tag }}.styles';
+import type { CSSResultGroup } from 'lit';
 
 /**
- * @since 2.0
+ * @summary Short summary of the component's intended use.
+ * @documentation https://shoelace.style/components/{{ tagWithoutPrefix tag }}
  * @status experimental
+ * @since 2.0
  *
  * @dependency sl-example
  *
@@ -15,21 +19,23 @@ import styles from './{{ tagWithoutPrefix tag }}.styles';
  * @slot - The default slot.
  * @slot example - An example slot.
  *
- * @csspart base - The component's internal wrapper.
+ * @csspart base - The component's base wrapper.
  *
  * @cssproperty --example - An example CSS custom property.
  */
 @customElement('{{ tag }}')
-export default class {{ properCase tag }} extends LitElement {
-  static styles = styles;
+export default class {{ properCase tag }} extends ShoelaceElement {
+  static styles: CSSResultGroup = styles;
 
-  /** An example property. */
-  @property() prop = 'example';
+  private readonly localize = new LocalizeController(this);
 
-  @watch('someProp')
+  /** An example attribute. */
+  @property() attr = 'example';
+
+  @watch('someProperty')
   doSomething() {
     // Example event
-    emit(this, 'sl-event-name');
+    this.emit('sl-event-name');
   }
 
   render() {

scripts/shared.js

@@ -1,3 +1,4 @@
+/** Gets an array of components from a CEM object. */
 export function getAllComponents(metadata) {
   const allComponents = [];
 
@@ -5,10 +6,10 @@ export function getAllComponents(metadata) {
     module.declarations?.map(declaration => {
       if (declaration.customElement) {
         const component = declaration;
-        const modulePath = module.path;
+        const path = module.path;
 
         if (component) {
-          allComponents.push(Object.assign(component, { modulePath }));
+          allComponents.push(Object.assign(component, { path }));
         }
       }
     });

src/components/alert/alert.styles.ts

@@ -19,7 +19,6 @@ export default css`
     border: solid var(--sl-panel-border-width) var(--sl-panel-border-color);
     border-top-width: calc(var(--sl-panel-border-width) * 3);
     border-radius: var(--sl-border-radius-medium);
-    box-shadow: var(--box-shadow);
     font-family: var(--sl-font-sans);
     font-size: var(--sl-font-size-small);
     font-weight: var(--sl-font-weight-normal);
@@ -83,6 +82,7 @@ export default css`
 
   .alert__message {
     flex: 1 1 auto;
+    display: block;
     padding: var(--sl-spacing-large);
     overflow: hidden;
   }
@@ -91,7 +91,7 @@ export default css`
     flex: 0 0 auto;
     display: flex;
     align-items: center;
-    font-size: var(--sl-font-size-large);
+    font-size: var(--sl-font-size-medium);
     padding-inline-end: var(--sl-spacing-medium);
   }
 `;