mi-element 0.9.0 → 0.9.1

package/dist/element.js

@@ -52,10 +52,13 @@ class MiElement extends HTMLElement {
     }
   }
   connectedCallback() {
-    this.#controllers.forEach(controller => controller.hostConnected?.());
-    const {shadowRootInit: shadowRootInit, useGlobalStyles: useGlobalStyles, template: template} = this.constructor;
-    this.renderRoot = shadowRootInit ? this.shadowRoot ?? this.attachShadow(shadowRootInit) : this, 
+    const {shadowRootInit: shadowRootInit, useGlobalStyles: useGlobalStyles, template: template, formAssociated: formAssociated} = this.constructor;
+    if (this.#controllers.forEach(controller => controller.hostConnected?.()), this.renderRoot = shadowRootInit ? this.shadowRoot ?? this.attachShadow(shadowRootInit) : this, 
     this.addTemplate(template), useGlobalStyles && addGlobalStyles(this.renderRoot), 
+    formAssociated && this.handleFormdata) {
+      const internals = this.attachInternals();
+      internals.form && this.on('formdata', ev => this.handleFormdata(ev), internals.form);
+    }
     this.render(), this.requestUpdate();
   }
   disconnectedCallback() {

package/docs/element.md

@@ -7,6 +7,7 @@
 * [disconnectedCallback()](#disconnectedcallback)
 * [attributeChangedCallback(name, oldValue, newValue)](#attributechangedcallbackname-oldvalue-newvalue)
 * [Update Cycle](#update-cycle)
+* [Form-Associated Elements](#form-associated-elements)
 * [render()](#render)
 * [update(changedAttributes)](#updatechangedattributes)
 * [shouldUpdate(changedAttributes)](#shouldupdatechangedattributes)
@@ -206,6 +207,85 @@ class Counter extends MiElement {
 }
 ```
 
+## Form-Associated Elements
+
+MiElement supports [form-associated custom elements][form-associated], allowing
+your components to participate in HTML forms just like native form controls.
+
+[form-associated]: https://web.dev/articles/form-associated-custom-elements
+
+### Declaring a Form-Associated Element
+
+Set `static formAssociated = true` on your component to enable form association:
+
+```js
+import { define, MiElement, html } from 'mi-element'
+
+class CustomInput extends MiElement {
+  static formAssociated = true
+
+  static get properties() {
+    return {
+      name: { type: String },
+      value: { type: String, initial: '' }
+    }
+  }
+
+  static template = html`<input type="text" />`
+  
+  render() {
+    this.refs = this.refsBySelector({ input: 'input' })
+    this.refs.input.addEventListener('input', (ev) => {
+      this.value = ev.target.value
+    })
+  }
+}
+
+define('custom-input', CustomInput)
+```
+
+### Handling Form Data
+
+Implement the `handleFormdata(ev)` method to submit your component's data with
+the form:
+
+```js
+class CustomInput extends MiElement {
+  static formAssociated = true
+
+  // ...other code...
+
+  handleFormdata(ev) {
+    // Only include data if the component has a name attribute
+    if (this.name) {
+      ev.formData.append(this.name, this.refs.input.value)
+    }
+  }
+}
+```
+
+The `handleFormdata` method is automatically called when the form is submitted or
+when `FormData` is created from the form.
+
+### Usage Example
+
+```html
+<form id="my-form">
+  <custom-input name="username" value="john"></custom-input>
+  <custom-input name="email" value="john@example.com"></custom-input>
+  <button type="submit">Submit</button>
+</form>
+
+<script>
+  const form = document.getElementById('my-form')
+  const formData = new FormData(form)
+  
+  console.log(formData.get('username')) // 'john'
+  console.log(formData.get('email'))    // 'john@example.com'
+</script>
+```
+
+
 ## render()
 
 Initial rendering of the component. Try to render the component only once!
@@ -275,7 +355,7 @@ class Counter extends MiElement {
   static template = `
   <button id>Count</button>
   <p>Counter value: <span>0</span></p>
-  `
+  ``
 
   render() {
     // template is already rendered on `this.renderRoot`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mi-element",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Build lightweight reactive micro web-components",
   "keywords": [],
   "homepage": "https://github.com/commenthol/mi-element/tree/main/packages/mi-element#readme",

package/src/element.js

@@ -159,9 +159,11 @@ export class MiElement extends HTMLElement {
    * @category lifecycle
    */
   connectedCallback() {
-    this.#controllers.forEach((controller) => controller.hostConnected?.())
     // @ts-expect-error
-    const { shadowRootInit, useGlobalStyles, template } = this.constructor
+    const { shadowRootInit, useGlobalStyles, template, formAssociated } =
+      this.constructor
+    // connect all controllers
+    this.#controllers.forEach((controller) => controller.hostConnected?.())
     this.renderRoot = shadowRootInit
       ? (this.shadowRoot ?? this.attachShadow(shadowRootInit))
       : this
@@ -169,6 +171,31 @@ export class MiElement extends HTMLElement {
     if (useGlobalStyles) {
       addGlobalStyles(this.renderRoot)
     }
+    /**
+     * handle formdata event if `handleFormdata` method is defined on the component.
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/formdata_event
+     * ```js
+     * class MyElement extends MiElement {
+     *   static formAssociated = true // required to receive formdata event
+     *   handleFormdata(ev) {
+     *     const { name, value } = this.refs.input
+     *     ev.formData.append(name, value)
+     *   }
+     *   render() {
+     *     this.renderRoot.innerHTML = html`<input name="${this.name}" value="${this.value}">`
+     *     this.refs = { input: this.renderRoot.querySelector('input') }
+     *   }
+     * }
+     * ```
+     */
+    // @ts-expect-error
+    if (formAssociated && this.handleFormdata) {
+      const internals = this.attachInternals()
+      if (internals.form) {
+        // @ts-expect-error
+        this.on('formdata', (ev) => this.handleFormdata(ev), internals.form)
+      }
+    }
     this.render() // initial render
     this.requestUpdate() // request initial update
   }