Merge branch 'next' into current

Author: claviska

cspell.json

@@ -15,6 +15,7 @@
     "autoplay",
     "bezier",
     "boxicons",
+    "CACHEABLE",
     "callout",
     "callouts",
     "chatbubble",
@@ -111,6 +112,8 @@
     "reregister",
     "resizer",
     "resizers",
+    "retargeted",
+    "RETRYABLE",
     "rgba",
     "roadmap",
     "Roboto",

docs/frameworks/angular.md

@@ -41,6 +41,38 @@ import { AppComponent } from './app.component';
 export class AppModule {}
 ```
 
+## Reference Shoelace components in your Angular component code
+
+```js
+import { SlDrawer } from '@shoelace-style/shoelace';
+
+@Component({
+  selector: 'app-drawer-example',
+  template: '<div id="page"><button (click)="showDrawer()">Show drawer</button><sl-drawer #drawer label="Drawer" class="drawer-focus" style="--size: 50vw"><p>Drawer content</p></sl-drawer></div>'
+})
+export class DrawerExampleComponent implements OnInit {
+
+  // use @ViewChild to get a reference to the #drawer element within component template
+  @ViewChild('drawer')
+  drawer?: ElementRef<SlDrawer>;
+
+  ...
+
+  constructor(...) {
+  }
+
+  ngOnInit() {
+  }
+
+  ...
+
+  showDrawer() {
+    // use nativeElement to access Shoelace components
+    this.drawer?.nativeElement.show();
+  }
+}
+```
+
 Now you can start using Shoelace components in your app!
 
 ?> Are you using Shoelace with Angular? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/angular.md)

docs/frameworks/vue.md

@@ -58,7 +58,7 @@ Now you can start using Shoelace components in your app!
 
 ### QR code generator example
 
-```vue
+```html
 <template>
   <div class="container">
     <h1>QR code generator</h1>
@@ -70,22 +70,22 @@ Now you can start using Shoelace components in your app!
 </template>
 
 <script setup>
-import { ref } from 'vue';
-import '@shoelace-style/shoelace/dist/components/qr-code/qr-code.js';
-import '@shoelace-style/shoelace/dist/components/input/input.js';
+  import { ref } from 'vue';
+  import '@shoelace-style/shoelace/dist/components/qr-code/qr-code.js';
+  import '@shoelace-style/shoelace/dist/components/input/input.js';
 
-const qrCode = ref();
+  const qrCode = ref();
 </script>
 
 <style>
-.container {
-  max-width: 400px;
-  margin: 0 auto;
-}
-
-sl-input {
-  margin: var(--sl-spacing-large) 0;
-}
+  .container {
+    max-width: 400px;
+    margin: 0 auto;
+  }
+
+  sl-input {
+    margin: var(--sl-spacing-large) 0;
+  }
 </style>
 ```
 
@@ -98,3 +98,18 @@ When binding complex data such as objects and arrays, use the `.prop` modifier t
 ```
 
 ?> Are you using Shoelace with Vue? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue.md)
+
+### Slots
+
+To use Shoelace components with slots, follow the Vue documentation on using [slots with custom elements](https://vuejs.org/guide/extras/web-components.html#building-custom-elements-with-vue).
+
+Here is an example:
+
+```html
+<sl-drawer label="Drawer" placement="start" class="drawer-placement-start" :open="drawerIsOpen">
+  This drawer slides in from the start.
+  <div slot="footer">
+    <sl-button variant="primary" @click=" drawerIsOpen = false">Close</sl-button>
+  </div>
+</sl-drawer>
+```

docs/getting-started/usage.md

@@ -33,7 +33,9 @@ Refer to a component's documentation for a complete list of its properties.
 
 ## Events
 
-You can listen for standard events such as `click`, `mouseover`, etc. as you normally would. In addition, some components emit custom events. These work the same way as standard events, but are prefixed with `sl-` to prevent collisions with standard events and other libraries.
+You can listen for standard events such as `click`, `mouseover`, etc. as you normally would. However, it's important to note that many events emitted within a component's shadow root will be [retargeted](https://dom.spec.whatwg.org/#retarget) to the host element. This may result in, for example, multiple `click` handlers executing even if the user clicks just once. Furthermore, `event.target` will point to the host element, making things even more confusing.
+
+As a result, you should almost always listen for custom events instead. For example, instead of listening to `click` to determine when an `<sl-checkbox>` gets toggled, listen to `sl-change`.
 
 ```html
 <sl-checkbox>Check me</sl-checkbox>
@@ -46,7 +48,7 @@ You can listen for standard events such as `click`, `mouseover`, etc. as you nor
 </script>
 ```
 
-Refer to a component's documentation for a complete list of its custom events.
+All custom events are prefixed with `sl-` to prevent collisions with standard events and other libraries. Refer to a component's documentation for a complete list of its custom events.
 
 ## Methods
 

docs/resources/changelog.md

@@ -6,6 +6,26 @@ 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).
 
+## 2.4.0
+
+- Added the `discover()` function to the experimental autoloader's exports [#1236](https://github.com/shoelace-style/shoelace/pull/1236)
+- Added the `size` attribute to `<sl-radio-group>` so labels and controls will be sized consistently [#1301](https://github.com/shoelace-style/shoelace/issues/1301)
+- Added tests for `<sl-animated-image>` [#1246](https://github.com/shoelace-style/shoelace/pull/1246)
+- Added tests for `<sl-animation>` [#1274](https://github.com/shoelace-style/shoelace/pull/1274)
+- Fixed a bug in `<sl-tree-item>` that prevented long labels from wrapping [#1243](https://github.com/shoelace-style/shoelace/issues/1243)
+- Fixed a bug in `<sl-tree-item>` that caused labels to be misaligned when text wraps [#1244](https://github.com/shoelace-style/shoelace/issues/1244)
+- Fixed an incorrect CSS property value in `<sl-checkbox>` [#1272](https://github.com/shoelace-style/shoelace/pull/1272)
+- Fixed a bug in `<sl-avatar>` that caused the initials to show up behind images with transparency [#1260](https://github.com/shoelace-style/shoelace/pull/1260)
+- Fixed a bug in `<sl-split-panel>` that prevented the divider from being focusable in some browsers [#1288](https://github.com/shoelace-style/shoelace/issues/1288)
+- Fixed a bug that caused `<sl-tab-group>` to affect scrolling when initializing [#1292](https://github.com/shoelace-style/shoelace/issues/1292)
+- Fixed a bug in `<sl-menu-item>` that allowed the hover state to show when focused [#1282](https://github.com/shoelace-style/shoelace/issues/1282)
+- Fixed a bug in `<sl-carousel>` that prevented interactive elements from receiving clicks [#1262](https://github.com/shoelace-style/shoelace/issues/1262)
+- Fixed a bug in `<sl-input>` that caused `valueAsDate` and `valueAsNumber` to not be set synchronously in some cases [#1302](https://github.com/shoelace-style/shoelace/issues/1302)
+- Improved the behavior of `<sl-carousel>` when used inside a flex container [#1235](https://github.com/shoelace-style/shoelace/pull/1235)
+- Improved the behavior of `<sl-tree-item>` to support buttons and other interactive elements [#1234](https://github.com/shoelace-style/shoelace/issues/1234)
+- Improved the performance of `<sl-include>` to prevent an apparent memory leak in some browsers [#1284](https://github.com/shoelace-style/shoelace/pull/1284)
+- Improved the accessibility of `<sl-select>`, `<sl-split-panel>`, and `<sl-details>` by ensuring slots don't have roles [#1287](https://github.com/shoelace-style/shoelace/issues/1287)
+
 ## 2.3.0
 
 - Added an experimental autoloader
@@ -27,7 +47,7 @@ New versions of Shoelace are released as-needed and generally occur when a criti
 - 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-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

docs/resources/contributing.md

@@ -363,3 +363,26 @@ Avoid inlining SVG icons inside of templates. If a component requires an icon, m
 ```
 
 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.
+
+### Writing tests
+
+What to test for a given component:
+
+- Start with a simple test that checks that the default version of the component still renders.
+- Add at least one accessibility test (The accessibility check only covers the parts of the DOM which are currently visible and rendered. Depending on the component, more than one accessibility test is required to cover all scenarios.):
+
+```ts
+const myComponent = await fixture<SlAlert>(html`<sl-my-component>SomeContent</sl-my-component>`);
+
+await expect(myComponent).to.be.accessible();
+```
+
+- Try to cover all features advertised in the component's description
+
+Guidelines for writing tests:
+
+- Each test should declare its own, hand crafted hml fixture for the component. Do not try to write one big component to match all tests. This helps keeping each test understandable in isolation.
+- Tests should not produce log lines. Note that sometimes this cannot be prevented as the test runner might log errors (e.g. 404s).
+- Try keeping the main test readable: Extract more complicated sets of selectors/commands/assertions into separate functions.
+- Try to aim testing the user facing features of the component instead of the internal workings of the component.
+- Group multiple tests for one feature into describe blocks.

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@shoelace-style/shoelace",
   "description": "A forward-thinking library of web components.",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "homepage": "https://github.com/shoelace-style/shoelace",
   "author": "Cory LaViska",
   "license": "MIT",
@@ -110,7 +110,6 @@
     "lint-staged": "^13.1.0",
     "lunr": "^2.3.9",
     "npm-check-updates": "^16.6.2",
-    "open": "^8.4.0",
     "pascal-case": "^3.1.2",
     "plop": "^3.1.1",
     "prettier": "^2.8.2",

package.json

@@ -7,7 +7,6 @@ import esbuild from 'esbuild';
 import fs from 'fs';
 import getPort, { portNumbers } from 'get-port';
 import { globby } from 'globby';
-import open from 'open';
 import copy from 'recursive-copy';
 
 const { bundle, copydir, dir, serve, types } = commandLineArgs([
@@ -108,7 +107,6 @@ fs.mkdirSync(outdir, { recursive: true });
     deleteSync('docs/dist');
 
     const browserSyncConfig = {
-      open: false,
       startPath: '/',
       port,
       logLevel: 'silent',
@@ -145,7 +143,6 @@ fs.mkdirSync(outdir, { recursive: true });
     bs.init(browserSyncConfig, () => {
       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/build.js

@@ -1,9 +1,70 @@
-import { expect, fixture, html } from '@open-wc/testing';
+import { clickOnElement } from '../../internal/test';
+import { expect, fixture, html, oneEvent } from '@open-wc/testing';
+import type SlAnimatedImage from './animated-image';
 
 describe('<sl-animated-image>', () => {
   it('should render a component', async () => {
-    const el = await fixture(html` <sl-animated-image></sl-animated-image> `);
+    const animatedImage = await fixture(html` <sl-animated-image></sl-animated-image> `);
 
-    expect(el).to.exist;
+    expect(animatedImage).to.exist;
+  });
+
+  it('should render be accessible', async () => {
+    const animatedImage = await fixture(html` <sl-animated-image></sl-animated-image> `);
+
+    await expect(animatedImage).to.be.accessible();
+  });
+
+  const files = ['docs/assets/images/walk.gif', 'docs/assets/images/tie.webp'];
+
+  files.forEach((file: string) => {
+    it(`should load a ${file} without errors`, async () => {
+      const animatedImage = await fixture<SlAnimatedImage>(html` <sl-animated-image></sl-animated-image> `);
+      let errorCount = 0;
+      oneEvent(animatedImage, 'sl-error').then(() => errorCount++);
+      await loadImage(animatedImage, file);
+
+      expect(errorCount).to.be.equal(0);
+    });
+
+    it(`should play ${file} on click`, async () => {
+      const animatedImage = await fixture<SlAnimatedImage>(html` <sl-animated-image></sl-animated-image> `);
+      await loadImage(animatedImage, file);
+
+      expect(animatedImage.play).not.to.be.true;
+
+      await clickOnElement(animatedImage);
+
+      expect(animatedImage.play).to.be.true;
+    });
+
+    it(`should pause and resume ${file} on click`, async () => {
+      const animatedImage = await fixture<SlAnimatedImage>(html` <sl-animated-image></sl-animated-image> `);
+      await loadImage(animatedImage, file);
+
+      animatedImage.play = true;
+
+      await clickOnElement(animatedImage);
+
+      expect(animatedImage.play).to.be.false;
+
+      await clickOnElement(animatedImage);
+
+      expect(animatedImage.play).to.be.true;
+    });
+  });
+
+  it('should emit an error event on invalid url', async () => {
+    const animatedImage = await fixture<SlAnimatedImage>(html` <sl-animated-image></sl-animated-image> `);
+
+    const errorPromise = oneEvent(animatedImage, 'sl-error');
+    animatedImage.src = 'completelyWrong';
+
+    await errorPromise;
   });
 });
+async function loadImage(animatedImage: SlAnimatedImage, file: string) {
+  const loadingPromise = oneEvent(animatedImage, 'sl-load');
+  animatedImage.src = file;
+  await loadingPromise;
+}