implement reportValidity for reporting proper form validation errors behind config flag (#3372)

* implement reportvalidity behind feature flag

* add tests

Author: MichaelWest22

src/htmx.js

@@ -278,7 +278,14 @@ var htmx = (function() {
        * @type boolean
        * @default true
        */
-      historyRestoreAsHxRequest: true
+      historyRestoreAsHxRequest: true,
+      /**
+       * Weather to report input validation errors to the end user and update focus to the first input that fails validation.
+       * This should always be enabled as this matches default browser form submit behaviour
+       * @type boolean
+       * @default false
+       */
+      reportValidityOfForms: false
     },
     /** @type {typeof parseInterval} */
     parseInterval: null,
@@ -3548,8 +3555,17 @@ var htmx = (function() {
     if (element.willValidate) {
       triggerEvent(element, 'htmx:validation:validate')
       if (!element.checkValidity()) {
+        if (
+          triggerEvent(element, 'htmx:validation:failed', {
+            message: element.validationMessage,
+            validity: element.validity
+          }) &&
+          !errors.length &&
+          htmx.config.reportValidityOfForms
+        ) {
+          element.reportValidity()
+        }
         errors.push({ elt: element, message: element.validationMessage, validity: element.validity })
-        triggerEvent(element, 'htmx:validation:failed', { message: element.validationMessage, validity: element.validity })
       }
     }
   }

test/core/validation.js

@@ -176,6 +176,72 @@ describe('Core htmx client side validation tests', function() {
     calledEvent.should.equal(true)
   })
 
+  it('foucuses on first invalid input and reports error to user when reportValidityOfForms true', function() {
+    htmx.config.reportValidityOfForms = true
+    var form = make('<form hx-post="/test" hx-trigger="click">' +
+            'No Request' +
+            '<input id="i1" name="i1" required>' +
+            '<input id="i2" name="i2" required>' +
+            '</form>')
+    var calledEvent = false
+    var handler = htmx.on(form, 'htmx:validation:failed', function() {
+      calledEvent = true
+    })
+    try {
+      form.click()
+      this.server.respond()
+    } finally {
+      htmx.off(form, handler)
+    }
+    calledEvent.should.equal(true)
+    document.activeElement.should.equal(byId('i1'))
+    htmx.config.reportValidityOfForms = false
+  })
+
+  it('no focus on first invalid input or report errors when reportValidityOfForms false', function() {
+    htmx.config.reportValidityOfForms = false
+    var form = make('<form hx-post="/test" hx-trigger="click">' +
+            'No Request' +
+            '<input id="i1" name="i1" required>' +
+            '<input id="i2" name="i2" required>' +
+            '</form>')
+    var calledEvent = false
+    var handler = htmx.on(form, 'htmx:validation:failed', function() {
+      calledEvent = true
+    })
+    try {
+      form.click()
+      this.server.respond()
+    } finally {
+      htmx.off(form, handler)
+    }
+    calledEvent.should.equal(true)
+    document.activeElement.should.equal(document.body)
+  })
+
+  it('can prevent reportValidity with preventDefault when reportValidityOfForms true', function() {
+    htmx.config.reportValidityOfForms = true
+    var form = make('<form hx-post="/test" hx-trigger="click">' +
+            'No Request' +
+            '<input id="i1" name="i1" required>' +
+            '<input id="i2" name="i2" required>' +
+            '</form>')
+    var calledEvent = false
+    var handler = htmx.on(form, 'htmx:validation:failed', function(evt) {
+      calledEvent = true
+      evt.preventDefault()
+    })
+    try {
+      form.click()
+      this.server.respond()
+    } finally {
+      htmx.off(form, handler)
+    }
+    calledEvent.should.equal(true)
+    document.activeElement.should.equal(document.body)
+    htmx.config.reportValidityOfForms = false
+  })
+
   it('calls htmx:validation:halted on failure', function() {
     var form = make('<form hx-post="/test" hx-trigger="click">' +
             'No Request' +

www/content/api.md

@@ -143,7 +143,7 @@ Note that using a [meta tag](@/docs.md#config) is the preferred mechanism for se
 * `htmx.config.responseHandling:[...]` - HtmxResponseHandlingConfig[]: the default [Response Handling](@/docs.md#response-handling) behavior for response status codes can be configured here to either swap or error
 * `htmx.config.allowNestedOobSwaps:true` -  boolean: whether to process OOB swaps on elements that are nested within the main response element. See [Nested OOB Swaps](@/attributes/hx-swap-oob.md#nested-oob-swaps).
 * `htmx.config.historyRestoreAsHxRequest:true` -  Whether to treat history cache miss full page reload requests as a "HX-Request" by returning this response header. This should always be disabled when using HX-Request header to optionally return partial responses
-
+* `htmx.config.reportValidityOfForms:false` -  Weather to report input validation errors to the end user and update focus to the first input that fails validation. This should always be enabled as this matches default browser form submit behaviour
 ##### Example
 
 ```js

www/content/docs.md

@@ -1090,6 +1090,8 @@ Htmx fires events around validation that can be used to hook in custom validatio
 Non-form elements do not validate before they make requests by default, but you can enable validation by setting
 the [`hx-validate`](@/attributes/hx-validate.md) attribute to "true".
 
+Normal browser form submission alerts the user of any validation errors automatically and auto focuses on the first invalid input. For backwards compatibility reasons htmx does not report the validation to the users by default and you should always enable this option by setting `htmx.config.reportValidityOfForms` to `true` to restore the default browser behavior.
+
 ### Validation Example
 
 Here is an example of an input that uses the [`hx-on`](/attributes/hx-on) attribute to catch the

www/content/events.md

@@ -565,7 +565,7 @@ to implement custom validation rules.
 
 ### Event - `htmx:validation:failed` {#htmx:validation:failed}
 
-This event is triggered when an element fails validation.
+This event is triggered when an element fails validation. If `preventDefault()` is invoked on the event, the reportValidity() enabled by `htmx.config.reportValidityOfForms` will not be called.
 
 ##### Details
 

www/content/reference.md

@@ -257,6 +257,7 @@ listed below:
 | `htmx.config.responseHandling`         | the default [Response Handling](@/docs.md#response-handling) behavior for response status codes can be configured here to either swap or error                             |
 | `htmx.config.allowNestedOobSwaps`      | defaults to `true`, whether to process OOB swaps on elements that are nested within the main response element. See [Nested OOB Swaps](@/attributes/hx-swap-oob.md#nested-oob-swaps). |
 | `htmx.config.historyRestoreAsHxRequest`| defaults to `true`, Whether to treat history cache miss full page reload requests as a "HX-Request" by returning this response header. This should always be disabled when using HX-Request header to optionally return partial responses                                                                                                         |
+| `htmx.config.reportValidityOfForms`    | defaults to `false`, Weather to report input validation errors to the end user and update focus to the first input that fails validation. This should always be enabled as this matches default browser form submit behaviour                                                                                                                     |
 
 
 </div>