From bc24ac570d36001bd51f68f59422f8a93246a0af Mon Sep 17 00:00:00 2001
From: Sean Doyle <sean.p.doyle24@gmail.com>
Date: Wed, 7 Feb 2024 12:20:07 -0500
Subject: [PATCH 1/2] Extract delegate for `TrixEditorElement`

In preparation for [#1128][], this commit introduces a module-private
`Delegate` class to serve as a representation of what form integration
requires for the `<trix-editor>` custom element. The structure of the
`Delegate` class mirrors that of the `TrixEditorElement` from which its
contents are extracted.

First, there are the properties that mimic those of most form controls,
including:

* `labels`
* `form`
* `name`
* `value`
* `defaultValue`
* `type`

With the exception of `labels`, property access is mostly proxied
through the associated `<input type="hidden">` element (accessed through
its own `inputElement` property).

Next, the `Delegate` defines methods that correspond to the Custom
Element lifecycle events, including:

* `connectedCallback`
* `disconnectedCallback`
* `setFormValue`

The connected and disconnected callbacks mirror that of the
`TrixEditorElement` itself. These callbacks attach and remove event
listeners for `click` and `reset` events.

The `setFormValue` is named to correspond with
[ElementInternals.setFormValue][]. Along with introducing this callback
method, this commit renames the `TrixEditorElement.setInputElementValue`
method to `TrixEditorElement.setFormValue`.

In addition to renaming `setInputElementValue`, this commit also defines
`TrixEditorElement.formResetCallback` (along with other [empty
form callbacks][]), then implements `TrixEditorElement.reset` as an alias. The
name mirrors the [ElementInternals.formResetCallback][].

[#1128]: https://github.com/basecamp/trix/pull/1128
[ElementInternals.setFormValue]: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setFormValue
[empty form callbacks]: https://webkit.org/blog/13711/elementinternals-and-form-associated-custom-elements/
[ElementInternals.formResetCallback]: https://web.dev/articles/more-capable-form-controls#void_formresetcallback
---
 README.md                                    |  27 +++
 assets/index.html                            |   3 +-
 karma.conf.js                                |   2 +-
 src/test/system/custom_element_test.js       |  41 +++-
 src/test/system/installation_process_test.js |  10 +-
 src/trix/controllers/editor_controller.js    |   2 +-
 src/trix/elements/trix_editor_element.js     | 187 ++++++++++++-------
 7 files changed, 196 insertions(+), 76 deletions(-)

diff --git a/README.md b/README.md
index 0133f94a3..9a1cfe6e7 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,33 @@ To populate a `<trix-editor>` with stored content, include that content in the a
 
 Always use an associated input element to safely populate an editor. Trix won’t load any HTML content inside a `<trix-editor>…</trix-editor>` tag.
 
+## Providing an Accessible Name
+
+Like other form controls, `<trix-editor>` elements should have an accessible name. The `<trix-editor>` element integrates with `<label>` elements and The `<trix-editor>` supports two styles of integrating with `<label>` elements:
+
+1. render the `<trix-editor>` element with an `[id]` attribute that the `<label>` element references through its `[for]` attribute:
+
+```html
+<label for="editor">Editor</label>
+<trix-editor id="editor"></trix-editor>
+```
+
+2. render the `<trix-editor>` element as a child of the `<label>` element:
+
+```html
+<trix-toolbar id="editor-toolbar"></trix-toolbar>
+<label>
+  Editor
+
+  <trix-editor toolbar="editor-toolbar"></trix-editor>
+</label>
+```
+
+> [!WARNING]
+> When rendering the `<trix-editor>` element as a child of the `<label>` element, [explicitly render](#creating-an-editor) the corresponding `<trix-toolbar>` element outside of the `<label>` element.
+
+In addition to integrating with `<label>` elements, `<trix-editor>` elements support `[aria-label]` and `[aria-labelledby]` attributes.
+
 ## Styling Formatted Content
 
 To ensure what you see when you edit is what you see when you save, use a CSS class name to scope styles for Trix formatted content. Apply this class name to your `<trix-editor>` element, and to a containing element when you render stored Trix content for display in your application.
diff --git a/assets/index.html b/assets/index.html
index e4cf73b85..9ddebeab1 100644
--- a/assets/index.html
+++ b/assets/index.html
@@ -72,7 +72,8 @@
   </head>
   <body>
     <main>
-      <trix-editor autofocus class="trix-content" input="input"></trix-editor>
+      <label for="editor">Input</label>
+      <trix-editor autofocus class="trix-content" input="input" id="editor"></trix-editor>
       <details id="output">
         <summary>Output</summary>
         <textarea readonly id="input"></textarea>
diff --git a/karma.conf.js b/karma.conf.js
index 9fe317624..725a68dcf 100644
--- a/karma.conf.js
+++ b/karma.conf.js
@@ -3,7 +3,7 @@ const config = {
   frameworks: [ "qunit" ],
   files: [
     { pattern: "dist/test.js", watched: false },
-    { pattern: "src/test_helpers/fixtures/*.png", watched: false, included: false, served: true }
+    { pattern: "src/test/test_helpers/fixtures/*.png", watched: false, included: false, served: true }
   ],
   proxies: {
     "/test_helpers/fixtures/": "/base/src/test_helpers/fixtures/"
diff --git a/src/test/system/custom_element_test.js b/src/test/system/custom_element_test.js
index 2e77e3fc4..81de91c5a 100644
--- a/src/test/system/custom_element_test.js
+++ b/src/test/system/custom_element_test.js
@@ -442,7 +442,7 @@ testGroup("Custom element API", { template: "editor_empty" }, () => {
 
   test("editor resets to its original value on form reset", async () => {
     const element = getEditorElement()
-    const { form } = element.inputElement
+    const { form } = element
 
     await typeCharacters("hello")
     form.reset()
@@ -451,7 +451,7 @@ testGroup("Custom element API", { template: "editor_empty" }, () => {
 
   test("editor resets to last-set value on form reset", async () => {
     const element = getEditorElement()
-    const { form } = element.inputElement
+    const { form } = element
 
     element.value = "hi"
     await typeCharacters("hello")
@@ -461,7 +461,7 @@ testGroup("Custom element API", { template: "editor_empty" }, () => {
 
   test("editor respects preventDefault on form reset", async () => {
     const element = getEditorElement()
-    const { form } = element.inputElement
+    const { form } = element
     const preventDefault = (event) => event.preventDefault()
 
     await typeCharacters("hello")
@@ -471,12 +471,43 @@ testGroup("Custom element API", { template: "editor_empty" }, () => {
     form.removeEventListener("reset", preventDefault, false)
     expectDocument("hello\n")
   })
+
+  test("element returns empty string when value is missing", async () => {
+    const element = getEditorElement()
+
+    assert.equal(element.value, "")
+  })
+
+  test("editor resets to its original value on element reset", async () => {
+    const element = getEditorElement()
+
+    await typeCharacters("hello")
+    element.reset()
+    expectDocument("\n")
+  })
+
+  test("editor returns its type", async() => {
+    const element = getEditorElement()
+
+    assert.equal("trix-editor", element.type)
+  })
+})
+
+testGroup("HTML sanitization", { template: "editor_html" }, () => {
+  test("ignores text nodes in script elements", () => {
+    const element = getEditorElement()
+    element.value = "<div>safe</div><script>alert(\"unsafe\")</script>"
+
+    expectDocument("safe\n")
+    assert.equal(element.innerHTML, "<div><!--block-->safe</div>")
+    assert.equal(element.value, "<div>safe</div>")
+  })
 })
 
 testGroup("<label> support", { template: "editor_with_labels" }, () => {
   test("associates all label elements", () => {
     const labels = [ document.getElementById("label-1"), document.getElementById("label-3") ]
-    assert.deepEqual(getEditorElement().labels, labels)
+    assert.deepEqual(Array.from(getEditorElement().labels), labels)
   })
 
   test("focuses when <label> clicked", () => {
@@ -504,7 +535,7 @@ testGroup("form property references its <form>", { template: "editors_with_forms
     assert.equal(editor.form, form)
   })
 
-  test("transitively accesses its related <input> element's <form>", () => {
+  test("transitively accesses its related <form>", () => {
     const form = document.getElementById("input-form")
     const editor = document.getElementById("editor-with-input-form")
     assert.equal(editor.form, form)
diff --git a/src/test/system/installation_process_test.js b/src/test/system/installation_process_test.js
index fc6195fbd..f484cf5b7 100644
--- a/src/test/system/installation_process_test.js
+++ b/src/test/system/installation_process_test.js
@@ -20,8 +20,8 @@ testGroup("Installation process", { template: "editor_html" }, () => {
   })
 })
 
-testGroup("Installation process without specified elements", { template: "editor_empty" }, () =>
-  test("creates identified toolbar and input elements", () => {
+testGroup("Installation process without specified elements", { template: "editor_empty" }, () => {
+  test("creates identified toolbar elements", () => {
     const editorElement = getEditorElement()
 
     const toolbarId = editorElement.getAttribute("toolbar")
@@ -29,6 +29,10 @@ testGroup("Installation process without specified elements", { template: "editor
     const toolbarElement = document.getElementById(toolbarId)
     assert.ok(toolbarElement, "toolbar element not assert.ok")
     assert.equal(editorElement.toolbarElement, toolbarElement)
+  })
+
+  test("creates identified input elements", () => {
+    const editorElement = getEditorElement()
 
     const inputId = editorElement.getAttribute("input")
     assert.ok(/trix-input-\d+/.test(inputId), `input id not assert.ok ${JSON.stringify(inputId)}`)
@@ -36,7 +40,7 @@ testGroup("Installation process without specified elements", { template: "editor
     assert.ok(inputElement, "input element not assert.ok")
     assert.equal(editorElement.inputElement, inputElement)
   })
-)
+})
 
 testGroup("Installation process with specified elements", { template: "editor_with_toolbar_and_input" }, () => {
   test("uses specified elements", () => {
diff --git a/src/trix/controllers/editor_controller.js b/src/trix/controllers/editor_controller.js
index 6f469db5a..04c2e921d 100644
--- a/src/trix/controllers/editor_controller.js
+++ b/src/trix/controllers/editor_controller.js
@@ -503,7 +503,7 @@ export default class EditorController extends Controller {
   updateInputElement() {
     const element = this.compositionController.getSerializableElement()
     const value = serializeToContentType(element, "text/html")
-    return this.editorElement.setInputElementValue(value)
+    return this.editorElement.setFormValue(value)
   }
 
   notifyEditorElement(message, data) {
diff --git a/src/trix/elements/trix_editor_element.js b/src/trix/elements/trix_editor_element.js
index 33877cc1a..1c6a4b5b6 100644
--- a/src/trix/elements/trix_editor_element.js
+++ b/src/trix/elements/trix_editor_element.js
@@ -160,10 +160,117 @@ installDefaultCSSForTagName("trix-editor", `\
     margin-right: -1px !important;
 }`)
 
+class InputElementDelegate {
+  #element
+
+  constructor(element) {
+    this.#element = element
+  }
+
+  // Properties
+
+  get labels() {
+    const labels = []
+    if (this.#element.id && this.#element.ownerDocument) {
+      labels.push(...Array.from(this.#element.ownerDocument.querySelectorAll(`label[for='${this.#element.id}']`) || []))
+    }
+
+    const label = findClosestElementFromNode(this.#element, { matchingSelector: "label" })
+    if (label) {
+      if ([ this.#element, null ].includes(label.control)) {
+        labels.push(label)
+      }
+    }
+
+    return labels
+  }
+
+  get form() {
+    return this.inputElement?.form
+  }
+
+  get inputElement() {
+    if (this.#element.hasAttribute("input")) {
+      return this.#element.ownerDocument?.getElementById(this.#element.getAttribute("input"))
+    } else if (this.#element.parentNode) {
+      const inputId = `trix-input-${this.#element.trixId}`
+      this.#element.setAttribute("input", inputId)
+      const element = makeElement("input", { type: "hidden", id: inputId })
+      this.#element.parentNode.insertBefore(element, this.#element.nextElementSibling)
+      return element
+    } else {
+      return undefined
+    }
+  }
+
+  get name() {
+    return this.inputElement?.name
+  }
+
+  get value() {
+    return this.inputElement?.value
+  }
+
+  get defaultValue() {
+    return this.value
+  }
+
+  // Element lifecycle
+
+  connectedCallback() {
+    ensureAriaLabel(this.#element)
+    window.addEventListener("reset", this.#resetBubbled, false)
+    window.addEventListener("click", this.#clickBubbled, false)
+  }
+
+  disconnectedCallback() {
+    window.removeEventListener("reset", this.#resetBubbled, false)
+    window.removeEventListener("click", this.#clickBubbled, false)
+  }
+
+  setFormValue(value) {
+    if (this.inputElement) {
+      this.inputElement.value = value
+    }
+  }
+
+  // Form support
+
+  #resetBubbled = (event) => {
+    if (event.defaultPrevented) return
+    if (event.target !== this.form) return
+    return this.#element.formResetCallback()
+  }
+
+  #clickBubbled = (event) => {
+    if (event.defaultPrevented) return
+    if (this.#element.contains(event.target)) return
+
+    const label = findClosestElementFromNode(event.target, { matchingSelector: "label" })
+    if (!label) return
+
+    if (!Array.from(this.labels).includes(label)) return
+
+    return this.#element.focus()
+  }
+}
+
 export default class TrixEditorElement extends HTMLElement {
+  static formAssociated = false
+
+  #delegate
+
+  constructor() {
+    super()
+    this.#delegate = new InputElementDelegate(this)
+  }
 
   // Properties
 
+  get type() {
+    return this.localName
+  }
+
   get trixId() {
     if (this.hasAttribute("trix-id")) {
       return this.getAttribute("trix-id")
@@ -174,19 +281,7 @@ export default class TrixEditorElement extends HTMLElement {
   }
 
   get labels() {
-    const labels = []
-    if (this.id && this.ownerDocument) {
-      labels.push(...Array.from(this.ownerDocument.querySelectorAll(`label[for='${this.id}']`) || []))
-    }
-
-    const label = findClosestElementFromNode(this, { matchingSelector: "label" })
-    if (label) {
-      if ([ this, null ].includes(label.control)) {
-        labels.push(label)
-      }
-    }
-
-    return labels
+    return this.#delegate.labels
   }
 
   get toolbarElement() {
@@ -204,21 +299,11 @@ export default class TrixEditorElement extends HTMLElement {
   }
 
   get form() {
-    return this.inputElement?.form
+    return this.#delegate.form
   }
 
   get inputElement() {
-    if (this.hasAttribute("input")) {
-      return this.ownerDocument?.getElementById(this.getAttribute("input"))
-    } else if (this.parentNode) {
-      const inputId = `trix-input-${this.trixId}`
-      this.setAttribute("input", inputId)
-      const element = makeElement("input", { type: "hidden", id: inputId })
-      this.parentNode.insertBefore(element, this.nextElementSibling)
-      return element
-    } else {
-      return undefined
-    }
+    return this.#delegate.inputElement
   }
 
   get editor() {
@@ -226,11 +311,11 @@ export default class TrixEditorElement extends HTMLElement {
   }
 
   get name() {
-    return this.inputElement?.name
+    return this.#delegate.name
   }
 
   get value() {
-    return this.inputElement?.value
+    return this.#delegate.value
   }
 
   set value(defaultValue) {
@@ -246,10 +331,8 @@ export default class TrixEditorElement extends HTMLElement {
     }
   }
 
-  setInputElementValue(value) {
-    if (this.inputElement) {
-      this.inputElement.value = value
-    }
+  setFormValue(value) {
+    this.#delegate.setFormValue(value)
   }
 
   // Element lifecycle
@@ -258,65 +341,39 @@ export default class TrixEditorElement extends HTMLElement {
     if (!this.hasAttribute("data-trix-internal")) {
       makeEditable(this)
       addAccessibilityRole(this)
-      ensureAriaLabel(this)
+      this.#delegate.connectedCallback()
 
       if (!this.editorController) {
         triggerEvent("trix-before-initialize", { onElement: this })
         this.editorController = new EditorController({
           editorElement: this,
-          html: this.defaultValue = this.value,
+          html: this.defaultValue = this.#delegate.defaultValue,
         })
         requestAnimationFrame(() => triggerEvent("trix-initialize", { onElement: this }))
       }
       this.editorController.registerSelectionManager()
-      this.registerResetListener()
-      this.registerClickListener()
       autofocus(this)
     }
   }
 
   disconnectedCallback() {
     this.editorController?.unregisterSelectionManager()
-    this.unregisterResetListener()
-    return this.unregisterClickListener()
+    this.#delegate.disconnectedCallback()
   }
 
   // Form support
 
-  registerResetListener() {
-    this.resetListener = this.resetBubbled.bind(this)
-    return window.addEventListener("reset", this.resetListener, false)
+  formAssociatedCallback(form) {
   }
 
-  unregisterResetListener() {
-    return window.removeEventListener("reset", this.resetListener, false)
+  formDisabledCallback(disabled) {
   }
 
-  registerClickListener() {
-    this.clickListener = this.clickBubbled.bind(this)
-    return window.addEventListener("click", this.clickListener, false)
+  formStateRestoreCallback(state, mode) {
   }
 
-  unregisterClickListener() {
-    return window.removeEventListener("click", this.clickListener, false)
-  }
-
-  resetBubbled(event) {
-    if (event.defaultPrevented) return
-    if (event.target !== this.form) return
-    return this.reset()
-  }
-
-  clickBubbled(event) {
-    if (event.defaultPrevented) return
-    if (this.contains(event.target)) return
-
-    const label = findClosestElementFromNode(event.target, { matchingSelector: "label" })
-    if (!label) return
-
-    if (!Array.from(this.labels).includes(label)) return
-
-    return this.focus()
+  formResetCallback() {
+    this.reset()
   }
 
   reset() {

From d6aefb9ba4f50db78b42b6a3a8552ff4fe61542a Mon Sep 17 00:00:00 2001
From: Sean Doyle <sean.p.doyle24@gmail.com>
Date: Mon, 15 Jan 2024 11:05:28 -0500
Subject: [PATCH 2/2] Integrate with `ElementInternals`

Closes [#1023][]

Replace the requirement for an `<input type="hidden">` element with
direct `<form>` integration through built-in support for
[ElementInternals][].

According to the [Form-associated custom elements][] section of [More
capable form controls][], various behaviors that the `<trix-editor>`
element was recreating are provided out of the box.

For example, the `<input type="hidden">`-`[input]` attribute pairing can
be achieved through [ElementInternals.setFormValue][]. Similarly, the
`<label>` element support can be achieved through
[ElementInternals.labels][].

[#1023]: https://github.com/basecamp/trix/issues/1023
[ElementInternals]: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals
[Form-associated custom elements]: https://web.dev/articles/more-capable-form-controls#form-associated_custom_elements
[More capable form controls]: https://web.dev/articles/more-capable-form-controls
[ElementInternals.setFormValue]: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setFormValue
[ElementInternals.labels]: https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/labels
---
 .github/workflows/ci.yml                      |  7 ++-
 README.md                                     | 58 ++++++++++++++++++-
 assets/index.html                             | 21 ++++++-
 karma.conf.js                                 |  4 ++
 src/test/system/accessibility_test.js         | 16 ++++-
 src/test/system/custom_element_test.js        |  6 +-
 src/test/system/installation_process_test.js  |  5 +-
 src/test/test_helpers/fixtures/editor_html.js |  9 ++-
 .../fixtures/editor_with_image.js             |  8 ++-
 .../fixtures/editor_with_toolbar_and_input.js | 18 ++++--
 .../fixtures/editors_with_forms.js            | 26 ++++++---
 .../test_helpers/fixtures/form_associated.js  |  4 ++
 src/test/test_helpers/test_helpers.js         |  4 ++
 src/trix/config/editor.js                     |  5 ++
 src/trix/config/index.js                      |  1 +
 src/trix/elements/trix_editor_element.js      | 58 ++++++++++++++++++-
 src/trix/trix.js                              |  8 +++
 17 files changed, 227 insertions(+), 31 deletions(-)
 create mode 100644 src/test/test_helpers/fixtures/form_associated.js
 create mode 100644 src/trix/config/editor.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8ab86c134..d4b04f3bc 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -8,8 +8,13 @@ on:
 
 jobs:
   build:
-    name: Browser tests
+    name: "Browser tests (formAssociated: ${{ matrix.formAssociated }})"
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        elementInternals: [false, true]
+    env:
+      EDITOR_FORM_ASSOCIATED: "${{ matrix.formAssociated }}"
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
diff --git a/README.md b/README.md
index 9a1cfe6e7..28a5c7ed4 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@ This is the approach that all modern, production ready, WYSIWYG editors now take
 
 <details><summary>Trix supports all evergreen, self-updating desktop and mobile browsers.</summary><img src="https://app.saucelabs.com/browser-matrix/basecamp_trix.svg"></details>
 
-Trix is built with established web standards, notably [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements), [Mutation Observer](https://dom.spec.whatwg.org/#mutation-observers), and [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+Trix is built with established web standards, notably [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements), [Element Internals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals), [Mutation Observer](https://dom.spec.whatwg.org/#mutation-observers), and [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
 
 # Getting Started
 
@@ -49,12 +49,26 @@ document.addEventListener("trix-before-initialize", () => {
 
 ## Creating an Editor
 
-Place an empty `<trix-editor></trix-editor>` tag on the page. Trix will automatically insert a separate `<trix-toolbar>` before the editor.
+Place an empty `<trix-editor></trix-editor>` tag on the page. If the `<trix-editor>` element is rendered with a `[toolbar]` attribute that references the element by its `[id]`, it will treat that element as its toolbar:
+
+```html
+<trix-toolbar id="editor_toolbar"></trix-toolbar>
+
+<trix-editor toolbar="editor_toolbar"></trix-editor>
+```
+
+Otherwise, Trix will automatically insert a separate `<trix-toolbar>` before the editor.
 
 Like an HTML `<textarea>`, `<trix-editor>` accepts `autofocus` and `placeholder` attributes. Unlike a `<textarea>`, `<trix-editor>` automatically expands vertically to fit its contents.
 
 ## Integrating With Forms
 
+There are two styles of integrating with `<form>` element submissions.
+
+### Legacy integration with `<input type="hidden">`
+
+Legacy support is provided through an `<input type="hidden">` element paired with an `[input]` attribute on the `<trix-editor>` element.
+
 To submit the contents of a `<trix-editor>` with a form, first define a hidden input field in the form and assign it an `id`. Then reference that `id` in the editor’s `input` attribute.
 
 ```html
@@ -66,7 +80,7 @@ To submit the contents of a `<trix-editor>` with a form, first define a hidden i
 
 Trix will automatically update the value of the hidden input field with each change to the editor.
 
-## Populating With Stored Content
+#### Populating With Stored Content
 
 To populate a `<trix-editor>` with stored content, include that content in the associated input element’s `value` attribute.
 
@@ -79,6 +93,44 @@ To populate a `<trix-editor>` with stored content, include that content in the a
 
 Always use an associated input element to safely populate an editor. Trix won’t load any HTML content inside a `<trix-editor>…</trix-editor>` tag.
 
+### Integration with Element Internals
+
+Trix can also be configured to integrate with forms through the `<trix-editor>` element's `ElementInternals` instance.
+
+First, configure Trix to opt-into its Element Internals support by rendering a `<meta>` element into the document's `<head>`:
+
+```html
+<head>
+  <!-- … -->
+  <meta name="trix-editor-formAssociated" content="true">
+</head>
+```
+
+Then, to submit the contents of a `<trix-editor>` with a `<form>`, render the element with a `[name]` attribute and its initial value as its inner HTML.
+
+```html
+<form …>
+  <trix-editor name="content"></trix-editor>
+</form>
+```
+
+To associate the element with a `<form>` that isn't an ancestor, render the element with a `[form]` attribute that references the `<form>` element by its `[id]`:
+
+```html
+<form id="a-form-element" …></form>
+<trix-editor name="content" form="a-form-element"></trix-editor>
+```
+
+#### Populating With Stored Content
+
+To populate a `<trix-editor>` with stored content, include that content as HTML inside the element’s inner HTML.
+
+```html
+<form …>
+  <trix-editor>Editor content goes here</trix-editor>
+</form>
+```
+
 ## Providing an Accessible Name
 
 Like other form controls, `<trix-editor>` elements should have an accessible name. The `<trix-editor>` element integrates with `<label>` elements and The `<trix-editor>` supports two styles of integrating with `<label>` elements:
diff --git a/assets/index.html b/assets/index.html
index 9ddebeab1..32b4ece11 100644
--- a/assets/index.html
+++ b/assets/index.html
@@ -12,7 +12,7 @@
         box-sizing: border-box;
       }
 
-      main {
+      main, nav {
         margin: 20px auto;
         max-width: 700px;
       }
@@ -69,8 +69,27 @@
         }
       });
     </script>
+    <script>
+      const searchParams = new URLSearchParams(location.search)
+
+      if (searchParams.get("editor") === "formAssociated") {
+        document.head.insertAdjacentHTML(
+          "beforeend",
+          `<meta name="trix-editor-formAssociated" content="true">`
+        )
+
+        document.addEventListener("trix-change", function(event) {
+          var input = document.getElementById("input")
+          input.value = event.target.value
+        })
+      }
+    </script>
   </head>
   <body>
+    <nav>
+      <a href="/">Legacy support</a>
+      <a href="/?editor=formAssociated">ElementInternals support</a>
+    </nav>
     <main>
       <label for="editor">Input</label>
       <trix-editor autofocus class="trix-content" input="input" id="editor"></trix-editor>
diff --git a/karma.conf.js b/karma.conf.js
index 725a68dcf..9ba5449f2 100644
--- a/karma.conf.js
+++ b/karma.conf.js
@@ -101,6 +101,10 @@ if (process.env.SAUCE_ACCESS_KEY) {
   }
 }
 
+if (process.env.EDITOR_FORM_ASSOCIATED === "true") {
+  config.files.unshift({ pattern: "src/test/test_helpers/fixtures/form_associated.js", watched: false, included: true })
+}
+
 function buildId() {
   const { GITHUB_WORKFLOW, GITHUB_RUN_NUMBER, GITHUB_RUN_ID } = process.env
   return GITHUB_WORKFLOW && GITHUB_RUN_NUMBER && GITHUB_RUN_ID
diff --git a/src/test/system/accessibility_test.js b/src/test/system/accessibility_test.js
index a86a61767..ea734aa25 100644
--- a/src/test/system/accessibility_test.js
+++ b/src/test/system/accessibility_test.js
@@ -1,4 +1,5 @@
-import { assert, test, testGroup, triggerEvent } from "test/test_helper"
+import * as config from "trix/config"
+import { assert, test, testGroup, testIf, testUnless, triggerEvent } from "test/test_helper"
 
 testGroup("Accessibility attributes", { template: "editor_default_aria_label" }, () => {
   test("sets the role to textbox", () => {
@@ -22,12 +23,12 @@ testGroup("Accessibility attributes", { template: "editor_default_aria_label" },
     assert.equal(editor.getAttribute("aria-labelledby"), "aria-labelledby-id")
   })
 
-  test("assigns aria-label to the text of the element's <label> elements", () => {
+  testUnless(config.editor.formAssociated, "assigns aria-label to the text of the element's <label> elements", () => {
     const editor = document.getElementById("editor-with-labels")
     assert.equal(editor.getAttribute("aria-label"), "Label 1 Label 2 Label 3")
   })
 
-  test("updates the aria-label on focus", () => {
+  testUnless(config.editor.formAssociated, "updates the aria-label on focus", () => {
     const editor = document.getElementById("editor-with-modified-label")
     const label = document.getElementById("modified-label")
 
@@ -35,4 +36,13 @@ testGroup("Accessibility attributes", { template: "editor_default_aria_label" },
     triggerEvent(editor, "focus")
     assert.equal(editor.getAttribute("aria-label"), "New Value")
   })
+
+  testIf(config.editor.formAssociated, "does not set [aria-label] for a <label> element", () => {
+    const editor = document.getElementById("editor-with-labels")
+    const labels = Array.from(editor.labels)
+    const text = labels.map((label) => label.textContent.trim())
+
+    assert.deepEqual(text, [ "Label 1", "Label 2", "Label 3" ])
+    assert.equal(editor.getAttribute("aria-label"), null)
+  })
 })
diff --git a/src/test/system/custom_element_test.js b/src/test/system/custom_element_test.js
index 81de91c5a..1da42a246 100644
--- a/src/test/system/custom_element_test.js
+++ b/src/test/system/custom_element_test.js
@@ -1,3 +1,4 @@
+import * as config from "trix/config"
 import { rangesAreEqual } from "trix/core/helpers"
 
 import {
@@ -13,6 +14,7 @@ import {
   test,
   testGroup,
   testIf,
+  testUnless,
   triggerEvent,
   typeCharacters,
   typeInToolbarDialog,
@@ -510,12 +512,12 @@ testGroup("<label> support", { template: "editor_with_labels" }, () => {
     assert.deepEqual(Array.from(getEditorElement().labels), labels)
   })
 
-  test("focuses when <label> clicked", () => {
+  testUnless(config.editor.formAssociated, "focuses when <label> clicked", () => {
     document.getElementById("label-1").click()
     assert.equal(getEditorElement(), document.activeElement)
   })
 
-  test("focuses when <label> descendant clicked", () => {
+  testUnless(config.editor.formAssociated, "focuses when <label> descendant clicked", () => {
     document.getElementById("label-1").querySelector("span").click()
     assert.equal(getEditorElement(), document.activeElement)
   })
diff --git a/src/test/system/installation_process_test.js b/src/test/system/installation_process_test.js
index f484cf5b7..38bd4fb92 100644
--- a/src/test/system/installation_process_test.js
+++ b/src/test/system/installation_process_test.js
@@ -1,6 +1,7 @@
+import * as config from "trix/config"
 import EditorController from "trix/controllers/editor_controller"
 
-import { assert, test, testGroup } from "test/test_helper"
+import { assert, test, testGroup, testUnless } from "test/test_helper"
 import { nextFrame } from "../test_helpers/timing_helpers"
 
 testGroup("Installation process", { template: "editor_html" }, () => {
@@ -31,7 +32,7 @@ testGroup("Installation process without specified elements", { template: "editor
     assert.equal(editorElement.toolbarElement, toolbarElement)
   })
 
-  test("creates identified input elements", () => {
+  testUnless(config.editor.formAssociated, "creates identified input elements", () => {
     const editorElement = getEditorElement()
 
     const inputId = editorElement.getAttribute("input")
diff --git a/src/test/test_helpers/fixtures/editor_html.js b/src/test/test_helpers/fixtures/editor_html.js
index 6726380b2..3dc667395 100644
--- a/src/test/test_helpers/fixtures/editor_html.js
+++ b/src/test/test_helpers/fixtures/editor_html.js
@@ -1,3 +1,8 @@
+import * as config from "trix/config"
+
 export default () =>
-  `<input id="my_input" type="hidden" value="&lt;div&gt;Hello world&lt;/div&gt;">
-  <trix-editor input="my_input" autofocus placeholder="Say hello..."></trix-editor>`
+  config.editor.formAssociated ?
+    `<trix-editor autofocus placeholder="Say hello..."><div>Hello world</div></trix-editor>
+    ` :
+    `<input id="my_input" type="hidden" value="&lt;div&gt;Hello world&lt;/div&gt;">
+    <trix-editor input="my_input" autofocus placeholder="Say hello..."></trix-editor>`
diff --git a/src/test/test_helpers/fixtures/editor_with_image.js b/src/test/test_helpers/fixtures/editor_with_image.js
index 43bebff24..820bbe0f8 100644
--- a/src/test/test_helpers/fixtures/editor_with_image.js
+++ b/src/test/test_helpers/fixtures/editor_with_image.js
@@ -1,5 +1,9 @@
+import * as config from "trix/config"
 import { TEST_IMAGE_URL } from "./test_image_url"
 
 export default () =>
-  `<trix-editor input="my_input" autofocus placeholder="Say hello..."></trix-editor>
-  <input id="my_input" type="hidden" value="ab&lt;img src=&quot;${TEST_IMAGE_URL}&quot; width=&quot;10&quot; height=&quot;10&quot;&gt;">`
+  config.editor.formAssociated ?
+    `<trix-editor autofocus placeholder="Say hello...">ab<img src="${TEST_IMAGE_URL}" width="10" height="10"></trix-editor>
+    ` :
+    `<trix-editor input="my_input" autofocus placeholder="Say hello..."></trix-editor>
+    <input id="my_input" type="hidden" value="ab&lt;img src=&quot;${TEST_IMAGE_URL}&quot; width=&quot;10&quot; height=&quot;10&quot;&gt;">`
diff --git a/src/test/test_helpers/fixtures/editor_with_toolbar_and_input.js b/src/test/test_helpers/fixtures/editor_with_toolbar_and_input.js
index 2268e1544..802e5b50e 100644
--- a/src/test/test_helpers/fixtures/editor_with_toolbar_and_input.js
+++ b/src/test/test_helpers/fixtures/editor_with_toolbar_and_input.js
@@ -1,6 +1,14 @@
+import * as config from "trix/config"
+
 export default () =>
-  `<ul id="my_editor">
-    <li><trix-toolbar id="my_toolbar"></trix-toolbar></li>
-    <li><trix-editor toolbar="my_toolbar" input="my_input" autofocus placeholder="Say hello..."></trix-editor></li>
-    <li><input id="my_input" type="hidden" value="&lt;div&gt;Hello world&lt;/div&gt;"></li>
-  </ul>`
+  config.editor.formAssociated ?
+    `<ul id="my_editor">
+      <li><trix-toolbar id="my_toolbar"></trix-toolbar></li>
+      <li><trix-editor toolbar="my_toolbar" autofocus placeholder="Say hello..."><div>Hello world</div></trix-editor></li>
+    </ul>
+    ` :
+    `<ul id="my_editor">
+      <li><trix-toolbar id="my_toolbar"></trix-toolbar></li>
+      <li><trix-editor toolbar="my_toolbar" input="my_input" autofocus placeholder="Say hello..."></trix-editor></li>
+      <li><input id="my_input" type="hidden" value="&lt;div&gt;Hello world&lt;/div&gt;"></li>
+    </ul>`
diff --git a/src/test/test_helpers/fixtures/editors_with_forms.js b/src/test/test_helpers/fixtures/editors_with_forms.js
index 56ed494ac..5e090da84 100644
--- a/src/test/test_helpers/fixtures/editors_with_forms.js
+++ b/src/test/test_helpers/fixtures/editors_with_forms.js
@@ -1,11 +1,21 @@
+import * as config from "trix/config"
+
 export default () =>
-  `<form id="ancestor-form">
-    <trix-editor id="editor-with-ancestor-form"></trix-editor>
-  </form>
+  config.editor.formAssociated ?
+    `<form id="ancestor-form">
+      <trix-editor id="editor-with-ancestor-form"></trix-editor>
+    </form>
+    <form id="input-form"></form>
+    <trix-editor id="editor-with-input-form" form="input-form"></trix-editor>
+    <trix-editor id="editor-with-no-form"></trix-editor>
+    ` :
+    `<form id="ancestor-form">
+      <trix-editor id="editor-with-ancestor-form"></trix-editor>
+    </form>
 
-  <form id="input-form">
-    <input type="hidden" id="hidden-input">
-  </form>
-  <trix-editor id="editor-with-input-form" input="hidden-input"></trix-editor>
+    <form id="input-form">
+      <input type="hidden" id="hidden-input">
+    </form>
+    <trix-editor id="editor-with-input-form" input="hidden-input"></trix-editor>
 
-  <trix-editor id="editor-with-no-form"></trix-editor>`
+    <trix-editor id="editor-with-no-form"></trix-editor>`
diff --git a/src/test/test_helpers/fixtures/form_associated.js b/src/test/test_helpers/fixtures/form_associated.js
new file mode 100644
index 000000000..e47f0bd7c
--- /dev/null
+++ b/src/test/test_helpers/fixtures/form_associated.js
@@ -0,0 +1,4 @@
+document.head.insertAdjacentHTML(
+  "beforeend",
+  `<meta name="trix-editor-formAssociated" content="true">
+`)
diff --git a/src/test/test_helpers/test_helpers.js b/src/test/test_helpers/test_helpers.js
index 96a2bd31c..4ed539dd8 100644
--- a/src/test/test_helpers/test_helpers.js
+++ b/src/test/test_helpers/test_helpers.js
@@ -56,6 +56,10 @@ export const testIf = function (condition, ...args) {
   }
 }
 
+export const testUnless = function(condition, ...args) {
+  testIf(!condition, ...args)
+}
+
 export const { skip, test } = QUnit
 
 const waitForTrixInit = async () => {
diff --git a/src/trix/config/editor.js b/src/trix/config/editor.js
new file mode 100644
index 000000000..026e9eb38
--- /dev/null
+++ b/src/trix/config/editor.js
@@ -0,0 +1,5 @@
+const config = {
+  formAssociated: false
+}
+
+export default config
diff --git a/src/trix/config/index.js b/src/trix/config/index.js
index 27f7abc2f..64684bc1e 100644
--- a/src/trix/config/index.js
+++ b/src/trix/config/index.js
@@ -2,6 +2,7 @@ export { default as attachments } from "./attachments"
 export { default as blockAttributes } from "./block_attributes"
 export { default as browser } from "./browser"
 export { default as css } from "./css"
+export { default as editor } from "./editor"
 export { default as fileSize } from "./file_size_formatting"
 export { default as input } from "./input"
 export { default as keyNames } from "./key_names"
diff --git a/src/trix/elements/trix_editor_element.js b/src/trix/elements/trix_editor_element.js
index 1c6a4b5b6..16e8e3edc 100644
--- a/src/trix/elements/trix_editor_element.js
+++ b/src/trix/elements/trix_editor_element.js
@@ -212,7 +212,7 @@ class InputElementDelegate {
   }
 
   get defaultValue() {
-    return this.value
+    return this.#element.value
   }
 
   // Element lifecycle
@@ -255,6 +255,58 @@ class InputElementDelegate {
   }
 }
 
+class ElementInternalsDelegate {
+  #element
+  #internals
+  #value = ""
+
+  constructor(element) {
+    this.#element = element
+    this.#internals = element.attachInternals()
+  }
+
+  get value() {
+    return this.#value
+  }
+
+  // Properties
+
+  get labels() {
+    return this.#internals.labels
+  }
+
+  get form() {
+    return this.#internals.form
+  }
+
+  get name() {
+    return this.#element.getAttribute("name")
+  }
+
+  get inputElement() {
+    return null
+  }
+
+  get defaultValue() {
+    return this.#element.innerHTML
+  }
+
+  // Form support
+
+  setFormValue(value) {
+    this.#value = value
+    this.#internals.setFormValue(value)
+  }
+
+  // Element lifecycle
+
+  connectedCallback() {
+  }
+
+  disconnectedCallback() {
+  }
+}
+
 export default class TrixEditorElement extends HTMLElement {
   static formAssociated = false
 
@@ -262,7 +314,9 @@ export default class TrixEditorElement extends HTMLElement {
 
   constructor() {
     super()
-    this.#delegate = new InputElementDelegate(this)
+    this.#delegate = this.constructor.formAssociated ?
+      new ElementInternalsDelegate(this) :
+      new InputElementDelegate(this)
   }
 
   // Properties
diff --git a/src/trix/trix.js b/src/trix/trix.js
index b778149ed..f2ac0484c 100644
--- a/src/trix/trix.js
+++ b/src/trix/trix.js
@@ -26,6 +26,14 @@ const Trix = {
 // Expose models under the Trix constant for compatibility with v1
 Object.assign(Trix, models)
 
+for (const element of document.getElementsByName("trix-editor-formAssociated")) {
+  if (element instanceof HTMLMetaElement) {
+    config.editor.formAssociated = element.content === "true"
+  }
+}
+
+elements.TrixEditorElement.formAssociated = config.editor.formAssociated
+
 function start() {
   if (!customElements.get("trix-toolbar")) {
     customElements.define("trix-toolbar", elements.TrixToolbarElement)