Support for ElementInternals and Constraint Validations

Integrate with `<form>` elements directly through built-in support for [ElementInternals][]. This is achieved with graceful degradation in two ways: * automatically check for browser support * support globally disabling through `Trix.config.editor.formAssociated = false` 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. Add support for integrating with [Constraint validation][] through the support for the `[required]` attribute and the `setCustomValidity(message)` method. [Constraint validation]: https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation [#1023]: #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
basecamp · Oct 4, 2024 · 1acfaec · 1acfaec
1 parent 2b7f980
commit 1acfaec
Show file tree

Hide file tree

Showing 12 changed files with 473 additions and 17 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -8,7 +8,12 @@ on:
 
 jobs:
   build:
-    name: Browser tests
+    name: "Browser tests (Trix.config.editor.formAssociated = ${{ matrix.formAssociated }})"
+    strategy:
+      matrix:
+        formAssociated: [true, false]
+    env:
+      FORM_ASSOCIATED: "${{ matrix.formAssociated }}"
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3

diff --git 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
 
@@ -88,6 +88,16 @@ If the attribute is defined in `Trix.config.blockAttributes`, Trix will apply th
 
 Clicking the quote button toggles whether the block should be rendered with `<blockquote>`.
 
+## Integrating with Element Internals
+
+Trix will integrate `<trix-editor>` elements with forms depending on the browser's support for [Element Internals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals). By default, Trix will enable support for `ElementInternals` when the feature is enabled in the browser. If there is a need to disable support for `ElementInternals`, set `Trix.config.editor.formAssociated = false`:
+
+```js
+import Trix from "trix"
+
+Trix.config.editor.formAssociated = false
+```
+
 ## Invoking Internal Trix Actions
 
 Internal actions are defined in `controllers/editor_controller.js` and consist of:
@@ -148,6 +158,126 @@ 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.
 
+## Validating the Editor
+
+Out of the box, `<trix-editor>` elements support browsers' built-in [Constraint
+validation][]. When rendered with the [required][] attribute, editors will be
+invalid when they're completely empty. For example, consider the following HTML:
+
+```html
+<input id="x" value="" type="hidden" name="content">
+<trix-editor input="x" required></trix-editor>
+```
+
+Since the `<trix-editor>` element is `[required]`, it is invalid when its value
+is empty:
+
+```js
+const editor = document.querySelector("trix-editor")
+
+editor.validity.valid        // => false
+editor.validity.valueMissing // => true
+editor.matches(":valid")     // => false
+editor.matches(":invalid")   // => true
+
+editor.value = "A value that isn't empty"
+
+editor.validity.valid         // => true
+editor.validity.valueMissing  // => false
+editor.matches(":valid")      // => true
+editor.matches(":invalid")    // => false
+```
+
+In addition to the built-in `[required]` attribute, `<trix-editor>`
+elements support custom validation through their [setCustomValidity][] method.
+For example, consider the following HTML:
+
+```js
+<input id="x" value="" type="hidden" name="content">
+<trix-editor input="x"></trix-editor>
+```
+
+Custom validation can occur at any time. For example, validation can occur after
+a `trix-change` event fired after the editor's contents change:
+
+```js
+addEventListener("trix-change", (event) => {
+  const editorElement = event.target
+  const trixDocument = editorElement.editor.getDocument()
+  const isValid = (trixDocument) => {
+    // determine the validity based on your custom criteria
+    return true
+  }
+
+  if (isValid(trixDocument)) {
+    editorElement.setCustomValidity("")
+  } else {
+    editorElement.setCustomValidity("The document is not valid.")
+  }
+}
+```
+
+[Constraint validation]: https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation
+[required]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/required
+[setCustomValidity]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity
+
+## 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/assets/index.html b/assets/index.html
@@ -17,6 +17,10 @@
         max-width: 700px;
       }
 
+      trix-editor:invalid {
+        border: solid 1px red;
+      }
+
       #output {
         margin: 1rem 0 0;
       }

diff --git 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/"
@@ -29,6 +29,14 @@ const config = {
 
 /* eslint camelcase: "off",  */
 
+if (process.env.FORM_ASSOCIATED === "false") {
+  config.files.push({
+    pattern: "src/test/test_helpers/fixtures/form_associated_false.js",
+    watched: false,
+    included: true
+  })
+}
+
 if (process.env.SAUCE_ACCESS_KEY) {
   config.customLaunchers = {
     sl_chrome_latest: {

diff --git 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 {
@@ -500,7 +501,7 @@ testGroup("Custom element API", { template: "editor_empty" }, () => {
 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", () => {
@@ -538,4 +539,161 @@ testGroup("form property references its <form>", { template: "editors_with_forms
     const editor = document.getElementById("editor-with-no-form")
     assert.equal(editor.form, null)
   })
+
+  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)
+  })
+
+  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")
+  })
+
+  testIfFormAssociated("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")
+  })
+
+  testIfFormAssociated("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")
+  })
+
+  testIfFormAssociated("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")
+  })
+
+  testIfFormAssociated("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")
+  })
+
+  testIfFormAssociated("validates with [required] attribute as invalid", () => {
+    const editor = document.getElementById("editor-with-ancestor-form")
+    const form = editor.form
+    let invalidEvent, submitEvent = null
+
+    editor.addEventListener("invalid", event => invalidEvent = event, { once: true })
+    form.addEventListener("submit", event => submitEvent = event, { once: true })
+
+    editor.required = true
+    form.requestSubmit()
+
+    // assert.equal(document.activeElement, editor, "editor receives focus")
+    assert.equal(editor.required, true, ".required property retrurns true")
+    assert.equal(editor.validity.valid, false, "validity.valid is false")
+    assert.equal(editor.validationMessage, "Please fill out this field.", "sets .validationMessage")
+    assert.equal(invalidEvent.target, editor, "dispatches 'invalid' event on editor")
+    assert.equal(submitEvent, null, "does not dispatch a 'submit' event")
+  })
+
+  testIfFormAssociated("does not validate with [disabled] attribute", () => {
+    const editor = document.getElementById("editor-with-ancestor-form")
+    let invalidEvent = null
+
+    editor.disabled = true
+    editor.required = true
+    editor.addEventListener("invalid", event => invalidEvent = event, { once: true })
+    editor.reportValidity()
+
+    assert.equal(invalidEvent, null, "does not dispatch an 'invalid' event")
+  })
+
+  testIfFormAssociated("re-validates when the value changes", async () => {
+    const editor = document.getElementById("editor-with-ancestor-form")
+    editor.required = true
+    editor.focus()
+
+    assert.equal(editor.validity.valid, false, "validity.valid is initially false")
+
+    await typeCharacters("a")
+
+    assert.equal(editor.validity.valid, true, "validity.valid is true after re-validating")
+    assert.equal(editor.validity.valueMissing, false, "validity.valueMissing is false")
+    assert.equal(editor.validationMessage, "", "clears the validationMessage")
+  })
+
+  testIfFormAssociated("accepts a customError validation message", () => {
+    const editor = document.getElementById("editor-with-ancestor-form")
+
+    editor.setCustomValidity("A custom validation message")
+
+    assert.equal(editor.validity.valid, false)
+    assert.equal(editor.validity.customError, true)
+    assert.equal(editor.validationMessage, "A custom validation message")
+  })
 })
+
+function testIfFormAssociated(name, callback) {
+  test(name, async () => {
+    if (config.editor.formAssociated) {
+      await callback()
+    } else {
+      assert.equal(config.editor.formAssociated, false, "skipping test that requires ElementInternals")
+    }
+  })
+}
diff --git 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>`