fixes #718

docs/getting-started/form-controls.md

@@ -6,6 +6,12 @@ Shoelace solves this problem by using the [`formdata`](https://developer.mozilla
 
 ?> 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.
 
+## A Note About Event Capturing
+
+Shoelace uses event listeners to intercept the form's `formdata` and `submit` events. This allows it to inject form data and activate client-side validation as necessary. The [`capture`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#parameters) option is used to ensure events are intercepted as early as possible. This means if you're using `addEventListener()` without the `capture` option, you have nothing to worry about.
+
+However, if you're using the `capture` option, you must attach the listener _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
 
 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.

docs/resources/changelog.md

@@ -18,6 +18,7 @@ _During the beta period, these restrictions may be relaxed in the event of a mis
 - Fixed a bug that resulted in a console error being thrown on keydown in `<sl-dropdown>` [#719](https://github.com/shoelace-style/shoelace/issues/719)
 - Fixed a bug that prevented `<sl-dropdown>` from being closed when opened initially [#720](https://github.com/shoelace-style/shoelace/issues/720)
 - Fixed a bug that caused the test runner to fail when using a locale other than en-US [#726](https://github.com/shoelace-style/shoelace/issues/726)
+- Improved the timing of `FormSubmitController` listeners so it's not as easy to attach custom listeners that run prematurely [#718](https://github.com/shoelace-style/shoelace/issues/718)
 - Updated `<sl-tab-group>` and `<sl-menu>` to cycle through tabs and menu items instead of stopping at the first/last when using the keyboard
 - Removed path aliasing (again) because it doesn't work with Web Test Runner's esbuild plugin
 

src/internal/form.ts

@@ -43,15 +43,18 @@ export class FormSubmitController implements ReactiveController {
     this.form = this.options.form(this.host);
 
     if (this.form) {
-      this.form.addEventListener('formdata', this.handleFormData);
+      // We use capturing to bump the order of events up. This doesn't guarantee our logic runs first, but it will run
-      this.form.addEventListener('submit', this.handleFormSubmit);
+      // before normal event listeners which accounts for most use cases. People using capture will need to ensure the
+      // form controls are connected before attaching their listeners.
+      this.form.addEventListener('formdata', this.handleFormData, { capture: true });
+      this.form.addEventListener('submit', this.handleFormSubmit, { capture: true });
     }
   }
 
   hostDisconnected() {
     if (this.form) {
-      this.form.removeEventListener('formdata', this.handleFormData);
+      this.form.removeEventListener('formdata', this.handleFormData, { capture: true });
-      this.form.removeEventListener('submit', this.handleFormSubmit);
+      this.form.removeEventListener('submit', this.handleFormSubmit, { capture: true });
       this.form = undefined;
     }
   }
@@ -82,6 +85,7 @@ export class FormSubmitController implements ReactiveController {
     }
   }
 
+  /** Submits the form, triggering validation and form data injection. */
   submit(submitter?: HTMLInputElement | SlButton) {
     // Calling form.submit() bypasses the submit event and constraint validation. To prevent this, we can inject a
     // native submit button into the form, "click" it, then remove it to simulate a standard form submission.