github / auto-check-element

An input element that validates its value with a server endpoint.

<auto-check> element

An input element that validates its value against a server endpoint.

Installation

$ npm install --save @github/auto-check-element

Usage

Script

Import as a modules:

import '@github/auto-check-element'

With a script tag:

<script type="module" src="./node_modules/@github/auto-check-element/dist/index.js">

Markup

<auto-check src="/signup-check/username" csrf="<%= authenticity_token_for("/signup-check/username") %>">
  <input>
</auto-check>

Note that in the following example the CSRF element is marked with the data-csrf attribute rather than name so that the value doesn't get posted to the backend when the element is placed in a form.

<auto-check src="/signup-check/username">
  <input>
  <input hidden data-csrf value="<%= authenticity_token_for("/signup-check/username") %>">
</auto-check>

Attributes

• src is the server endpoint that will receive POST requests. The posted form contains a value parameter containing the text input to validate. Responding with a 200 OK status indicates the provided value is valid. Any other error status response indicates the provided value is invalid.
• csrf is the CSRF token for the posted form. It's available in the request body as a authenticity_token form parameter.
  • You can also supply the CSRF token via a child element. See usage example.
• required is a boolean attribute that requires the validation to succeed before the surrounding form may be submitted.
• http-method defaults to POST where data is submitted as a POST with form data. You can set GET and the HTTP method used will be a get with url encoded params instead.

Events

Network request lifecycle events

Request lifecycle events are dispatched on the <auto-check> element. These events do not bubble.

• loadstart - The server fetch has started.
• load - The network request completed successfully.
• error - The network request failed.
• loadend - The network request has completed.

Network events are useful for displaying progress states while the request is in-flight.

const check = document.querySelector('auto-check')
const container = check.parentElement
check.addEventListener('loadstart', () => container.classList.add('is-loading'))
check.addEventListener('loadend', () => container.classList.remove('is-loading'))
check.addEventListener('load', () => container.classList.add('is-success'))
check.addEventListener('error', () => container.classList.add('is-error'))

Auto-check events

auto-check-start is dispatched on when there has been input in the element. In event.detail you can find:

• setValidity: A function to provide a custom failure message on the input. By default it is 'Verifying…'.

const input = check.querySelector('input')

input.addEventListener('auto-check-start', function(event) {
  const {setValidity} = event.detail
  setValidity('Loading validation')
})

auto-check-send is dispatched before the network request begins. In event.detail you can find:

• body: The FormData request body to modify before the request is sent.

const input = check.querySelector('input')

input.addEventListener('auto-check-send', function(event) {
  const {body} = event.detail
  body.append('custom_form_data', 'value')
})

auto-check-success is dispatched when the server responds with 200 OK. In event.detail you can find:

• response: The successful server Response. Its body can be used for displaying server-provided messages.

input.addEventListener('auto-check-success', async function(event) {
  const message = await event.detail.response.text()
  console.log('Validation passed', message)
})

auto-check-error is dispatched when the server responds with a 400 or 500 range error status. In event.detail you can find:

• response: The failed server Response. Its body can be used for displaying server-provided messages.
• setValidity: A function to provide a custom failure message on the input. By default it is 'Validation failed'.

input.addEventListener('auto-check-error', async function(event) {
  const {response, setValidity} = event.detail

  setValidity('Validation failed')

  const message = await response.text()
  console.log('Validation failed', message)
})

auto-check-complete is dispatched after either the success or error events to indicate the end of the auto-check lifecycle.

input.addEventListener('auto-check-complete', function(event) {
  console.log('Validation complete', event)
})

Browser support

Browsers without native custom element support require a polyfill.

• Chrome
• Firefox
• Safari
• Microsoft Edge

Development

npm install
npm test

License

Distributed under the MIT license. See LICENSE for details.

auto-check-element's Issues

Should `csrf` be a required attribute?

Right now, we exit early if there is no CSRF token. Maybe we should allow users to supply a CSRF token and not mandate it optionally?

auto-check-element/src/index.ts

Lines 102 to 105 in 2310898

	// If some attributes are missing we want to exit early and make sure that the element is valid.
	if (!src || !csrf || !state) {
	return
	}

Compat Validation Popup UI Issue with Firefox

As discovered in https://github.com/github/c2c-actions-service/issues/2787, auto-check validation popup doesn't work as expected for Firefox. Only in Firefox the popup window does not "stick" with the input field and basically stays in the same fixed position after scrolling. It works fine in Chrome.

We can see this through our simple examples: https://github.github.com/auto-check-element/examples/

Chrome:

Screen.Recording.2022-02-23.at.12.42.48.PM.mov

Firefox:

Screen.Recording.2022-02-23.at.12.46.23.PM.mov

Validity message contains HTML

In Chrome this message shows on submit:

In Firefox this message shows on hover:

Cause:

auto-check-element/src/index.js

Line 131 in d304e38

input.setCustomValidity(errorMessage(error) || 'Something went wrong')

We ask for HTML:

auto-check-element/src/index.js

Line 157 in d304e38

xhr.setRequestHeader('Accept', 'text/html; fragment')

But the validity message should not contain HTML.

cc @github/web-systems