From 7046f282589d8b68692cc40b0b70615303de7635 Mon Sep 17 00:00:00 2001
From: Sean Doyle <sean.p.doyle24@gmail.com>
Date: Sat, 28 Sep 2024 00:12:21 -0400
Subject: [PATCH] Integrate with `ElementInternals`

Closes [#1023][]

Integrate with `<form>` elements directly 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 `<label>` element support can be achieved through
[ElementInternals.labels][]. Similarly, a `formResetCallback()` will
fire whenever the associated `<form>` element resets.

For now, keep the changes minimal. Future changes will handle
integrating with more parts of `ElementInternals`.

TODO after merging:
---

- [ ] Integrate with [ElementInternals.willValidate](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate), [ElementInternals.validity](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validity), [ElementInternals.validationMessage](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage)
- [ ] [Form callbacks](https://web.dev/articles/more-capable-form-controls#lifecycle_callbacks) like `void formDisabledCallback(disabled)` to support `[disabled]`
- [ ] [Instance properties included from ARIA](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals#instance_properties_included_from_aria)

[#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
---
 README.md                                     | 57 +++++++++++
 src/test/system/custom_element_test.js        | 96 ++++++++++++++++++-
 .../fixtures/editor_with_labels.js            |  8 +-
 .../fixtures/editors_with_forms.js            |  5 +-
 src/trix/elements/trix_editor_element.js      | 76 +++++----------
 5 files changed, 183 insertions(+), 59 deletions(-)

diff --git a/README.md b/README.md
index 0133f94a3..95df8c893 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,63 @@ 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.
 
+## Disabling the Editor
+
+To disable the `<trix-editor>`, render it with the `[disabled]` attribute:
+
+```html
+<trix-editor disabled></trix-editor>
+```
+
+Disabled editors are not editable, cannot receive focus, and their values will
+be ignored when their related `<form>` element is submitted.
+
+To change whether or not an editor is disabled, either toggle the `[disabled]`
+attribute or assign a boolean to the `.disabled` property:
+
+```html
+<trix-editor id="editor" disabled></trix-editor>
+
+<script>
+  const editor = document.getElementById("editor")
+
+  editor.toggleAttribute("disabled", false)
+  editor.disabled = true
+</script>
+```
+
+When disabled, the editor will match the [:disabled CSS
+pseudo-class][:disabled].
+
+[:disabled]: https://developer.mozilla.org/en-US/docs/Web/CSS/:disabled
+
+## 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/src/test/system/custom_element_test.js b/src/test/system/custom_element_test.js
index 2e77e3fc4..c0731ef84 100644
--- a/src/test/system/custom_element_test.js
+++ b/src/test/system/custom_element_test.js
@@ -471,12 +471,32 @@ testGroup("Custom element API", { template: "editor_empty" }, () => {
     form.removeEventListener("reset", preventDefault, false)
     expectDocument("hello\n")
   })
+
+  test("editor resets to its original value on element reset", async () => {
+    const element = getEditorElement()
+
+    await typeCharacters("hello")
+    element.reset()
+    expectDocument("\n")
+  })
+
+  test("element returns empty string when value is missing", () => {
+    const element = getEditorElement()
+
+    assert.equal(element.value, "")
+  })
+
+  test("editor returns its type", () => {
+    const element = getEditorElement()
+
+    assert.equal("trix-editor", element.type)
+  })
 })
 
 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", () => {
@@ -497,7 +517,7 @@ testGroup("<label> support", { template: "editor_with_labels" }, () => {
   })
 })
 
-testGroup("form property references its <form>", { template: "editors_with_forms", container: "div" }, () => {
+testGroup("integrates with its <form>", { template: "editors_with_forms", container: "div" }, () => {
   test("accesses its ancestor form", () => {
     const form = document.getElementById("ancestor-form")
     const editor = document.getElementById("editor-with-ancestor-form")
@@ -514,4 +534,76 @@ testGroup("form property references its <form>", { template: "editors_with_forms
     const editor = document.getElementById("editor-with-no-form")
     assert.equal(editor.form, null)
   })
+
+  test("adds [disabled] attribute based on .disabled property", () => {
+    const editor = document.getElementById("editor-with-ancestor-form")
+
+    editor.disabled = true
+
+    assert.equal(editor.hasAttribute("disabled"), true, "adds [disabled] attribute")
+
+    editor.disabled = false
+
+    assert.equal(editor.hasAttribute("disabled"), false, "removes [disabled] attribute")
+  })
+
+  test("removes [contenteditable] and disables input when editor element has [disabled]", () => {
+    const editor = document.getElementById("editor-with-no-form")
+
+    editor.setAttribute("disabled", "")
+
+    assert.equal(editor.matches(":disabled"), true, "sets :disabled CSS pseudostate")
+    assert.equal(editor.inputElement.disabled, true, "disables input")
+    assert.equal(editor.disabled, true, "exposes [disabled] attribute as .disabled property")
+    assert.equal(editor.hasAttribute("contenteditable"), false, "removes [contenteditable] attribute")
+
+    editor.removeAttribute("disabled")
+
+    assert.equal(editor.matches(":disabled"), false, "removes sets :disabled pseudostate")
+    assert.equal(editor.inputElement.disabled, false, "enabled input")
+    assert.equal(editor.disabled, false, "updates .disabled property")
+    assert.equal(editor.hasAttribute("contenteditable"), true, "adds [contenteditable] attribute")
+  })
+
+  test("removes [contenteditable] and disables input when editor element is :disabled", () => {
+    const editor = document.getElementById("editor-within-fieldset")
+    const fieldset = document.getElementById("fieldset")
+
+    fieldset.disabled = true
+
+    assert.equal(editor.matches(":disabled"), true, "sets :disabled CSS pseudostate")
+    assert.equal(editor.inputElement.disabled, true, "disables input")
+    assert.equal(editor.disabled, true, "infers disabled state from ancestor")
+    assert.equal(editor.hasAttribute("disabled"), false, "does not set [disabled] attribute")
+    assert.equal(editor.hasAttribute("contenteditable"), false, "removes [contenteditable] attribute")
+
+    fieldset.disabled = false
+
+    assert.equal(editor.matches(":disabled"), false, "removes sets :disabled pseudostate")
+    assert.equal(editor.inputElement.disabled, false, "enabled input")
+    assert.equal(editor.disabled, false, "updates .disabled property")
+    assert.equal(editor.hasAttribute("disabled"), false, "does not set [disabled] attribute")
+    assert.equal(editor.hasAttribute("contenteditable"), true, "adds [contenteditable] attribute")
+  })
+
+  test("does not receive focus when :disabled", () => {
+    const activeEditor = document.getElementById("editor-with-input-form")
+    const editor = document.getElementById("editor-within-fieldset")
+
+    activeEditor.focus()
+    editor.disabled = true
+    editor.focus()
+
+    assert.equal(activeEditor, document.activeElement, "disabled editor does not receive focus")
+  })
+
+  test("disabled editor does not encode its value when the form is submitted", () => {
+    const editor = document.getElementById("editor-with-ancestor-form")
+    const form = editor.form
+
+    editor.inputElement.value = "Hello world"
+    editor.disabled = true
+
+    assert.deepEqual({}, Object.fromEntries(new FormData(form).entries()), "does not write to FormData")
+  })
 })
diff --git a/src/test/test_helpers/fixtures/editor_with_labels.js b/src/test/test_helpers/fixtures/editor_with_labels.js
index e1a1fa0a0..8d174e124 100644
--- a/src/test/test_helpers/fixtures/editor_with_labels.js
+++ b/src/test/test_helpers/fixtures/editor_with_labels.js
@@ -1,7 +1,5 @@
 export default () =>
   `<label id="label-1" for="editor"><span>Label 1</span></label>
-  <label id="label-2">
-    Label 2
-    <trix-editor id="editor"></trix-editor>
-  </label>
-  <label id="label-3" for="editor">Label 3</label>`
+   <label id="label-2">Label 2</label>
+   <trix-editor id="editor"></trix-editor>
+   <label id="label-3" for="editor">Label 3</label>`
diff --git a/src/test/test_helpers/fixtures/editors_with_forms.js b/src/test/test_helpers/fixtures/editors_with_forms.js
index 56ed494ac..292d0e315 100644
--- a/src/test/test_helpers/fixtures/editors_with_forms.js
+++ b/src/test/test_helpers/fixtures/editors_with_forms.js
@@ -1,6 +1,6 @@
 export default () =>
   `<form id="ancestor-form">
-    <trix-editor id="editor-with-ancestor-form"></trix-editor>
+    <trix-editor id="editor-with-ancestor-form" name="editor-with-ancestor-form"></trix-editor>
   </form>
 
   <form id="input-form">
@@ -8,4 +8,5 @@ export default () =>
   </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>
+  <fieldset id="fieldset"><trix-editor id="editor-within-fieldset"></fieldset>`
diff --git a/src/trix/elements/trix_editor_element.js b/src/trix/elements/trix_editor_element.js
index 44626100b..731348273 100644
--- a/src/trix/elements/trix_editor_element.js
+++ b/src/trix/elements/trix_editor_element.js
@@ -1,7 +1,6 @@
 import * as config from "trix/config"
 
 import {
-  findClosestElementFromNode,
   handleEvent,
   handleEventOnce,
   installDefaultCSSForTagName,
@@ -161,6 +160,14 @@ installDefaultCSSForTagName("trix-editor", `\
 }`)
 
 export default class TrixEditorElement extends HTMLElement {
+  static formAssociated = true
+
+  #internals
+
+  constructor() {
+    super()
+    this.#internals = this.attachInternals()
+  }
 
   // Properties
 
@@ -174,19 +181,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.#internals.labels
   }
 
   get toolbarElement() {
@@ -238,6 +233,18 @@ export default class TrixEditorElement extends HTMLElement {
     this.editor?.loadHTML(this.defaultValue)
   }
 
+  get disabled() {
+    return this.inputElement.disabled
+  }
+
+  set disabled(value) {
+    this.toggleAttribute("disabled")
+  }
+
+  get type() {
+    return "trix-editor"
+  }
+
   // Controller delegate methods
 
   notify(message, data) {
@@ -269,54 +276,23 @@ export default class TrixEditorElement extends HTMLElement {
         requestAnimationFrame(() => triggerEvent("trix-initialize", { onElement: this }))
       }
       this.editorController.registerSelectionManager()
-      this.registerResetListener()
-      this.registerClickListener()
       autofocus(this)
     }
   }
 
   disconnectedCallback() {
     this.editorController?.unregisterSelectionManager()
-    this.unregisterResetListener()
-    return this.unregisterClickListener()
   }
 
   // Form support
 
-  registerResetListener() {
-    this.resetListener = this.resetBubbled.bind(this)
-    return window.addEventListener("reset", this.resetListener, false)
-  }
-
-  unregisterResetListener() {
-    return window.removeEventListener("reset", this.resetListener, false)
-  }
-
-  registerClickListener() {
-    this.clickListener = this.clickBubbled.bind(this)
-    return window.addEventListener("click", this.clickListener, false)
-  }
-
-  unregisterClickListener() {
-    return window.removeEventListener("click", this.clickListener, false)
-  }
-
-  resetBubbled(event) {
-    if (event.defaultPrevented) return
-    if (event.target !== this.form) return
-    return this.reset()
+  formDisabledCallback(disabled) {
+    this.inputElement.disabled = disabled
+    this.toggleAttribute("contenteditable", !disabled)
   }
 
-  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() {