Introduce form-associated custom element

[tkent-google]

This fixes WICG/webcomponents#187

Test: web-platform-tests/wpt#15740

---

/custom-elements.html ( diff )
/form-control-infrastructure.html ( diff )
/forms.html ( diff )
/index.html ( diff )
/indices.html ( diff )
/infrastructure.html ( diff )
/parsing.html ( diff )
/semantics-other.html ( diff )

[rniwa]

Could you summarize the changes these two PR would make in WICG/webcomponents#187 ? There is a lot of spec changes happening here, and it's hard to follow what the proposed API looks like.

[tkent-google]

Could you summarize the changes these two PR would make in w3c/webcomponents#187 ? There is a lot of spec changes happening here, and it's hard to follow what the proposed API looks like.

Sure. I'll add a summary.

[domenic]

This actually looks good to me. In penance for the review delay, I did the editorial changes myself. It would be good to have someone do another pass, and we should definitely wait for more implementers to get a chance to weigh in before merging, but it's top-notch work and seems detailed enough to be interoperably implementable, with good developer-facing documentation built in, and the like. I'm sold.

I would like to get a bit more explanation in the spec about state vs. submission value, but otherwise it all seems to work out pretty well.

[domenic]

Let's pull the submission value / state discussion out of the inline comments for more visibility. Continuing from #4383 (comment) and #4383 (comment) .

I like that the current architecture supports both. For example, consider a very hypothetical numeric control that takes various forms of numeric input as the "state", and converts them to a canonical decimal number string for submission to the server. So if I type "five" or "五" or "V" (Roman numerals), those strings are the state. But the control will convert them to the value "5". And if the UA needs to restore the state, e.g. via autocomplete or session restore or bfcache or whatever, then the UA will send a restoreStateCallback() with the "five" state, and the control can re-compute that the value should be "5". Makes sense, and we should include an example of that sort in the spec.

And I like how most control authors who don't care about the distinction can just do setFormValue(value) and the value will be used as both the state and the value.

So I think that, besides better documentation/examples, the main question is about the API surface that is currently setFormValue(state, value). I think that would be clearer as something like:

• setFormValueAndState(value, state)
• setFormValue(value, { state })

or something like that.

I also wonder why you can't use an entry list (i.e. a FormData JS object) for the state. It seems like the browser could serialize and restore that just as well as it could a File/USVString. Thoughts?

[tkent-google]

Re: setFormValue()

I had an uncomfortable feeling with supporting FormData for state because a FormData object contains entry names, which are not a part of element state. However now I think allowing FormData for state would make the API simpler and clearer. I made a local experimental implementation for the FormData support today, and found its implementation cost was not high.

So, I'd like to change setFormValue() to:

void setFormValue((File or USVString or FormData)? value,
                  optional (File or USVString or FormData)? state);

setFormValue(v) is equivalent to setFormValue(v, v).

[tkent-google]

I updated the patch.

[domenic]

Looks great. Thank you for those examples and extra explanations; they were very clarifying.

From an editor point of view I am happy with this. It would be good to get more implementers' feedback, but I have no concerns, and indeed am really excited with and happy about this spec.

[annevk]

I noticed a couple of things that seemed worth pointing out. Thanks for working on this!

[sideshowbarker]

heads-up @whatwg/documentation

[chrisdavidmills]

Recorded at https://trello.com/c/M46uVg89/24-web-components-related-updates for potential docs requirement

[tkent-google]

I updated the patch to add another argument to ElementInternals' setValidity() for WICG/webcomponents#187 (comment) .

[domenic]

@annevk do you want to take another look? I think this is ready to merge, especially now that you've approved #4324. And my read of the web components F2F was that we had multi-vendor support.

[annevk]

I have a couple nits (and left some other minor blocking comments on the blocking PRs), but this looks really great overall. Besides implementers this also has a huge interest from component developers so very glad to see it close to completion.

[annevk]

Should we add this in v1? It seems the UA could focus the control for now which coupled with the invalid event should give it enough to go on?

[domenic]

Given that it came directly out of developer feedback, and it's a "should" behavior, I'm inclined to keep it.

[annevk]

Do we have tests for it? It's yet another way to focus an element and we don't really understand focus.

[domenic]

We have tests for the validation step that it's a shadow-including descendant. We could add optional tests for the focus, but they can't be required since it's only a "may" that you focus "or otherwise draw attention to" invalid controls.

To be clear, the normative impact of this field only appears in the following context:

User agents may focus one of those elements in the process, by running the focusing steps for that element, and may change the scrolling position of the document, or perform some other action that brings the element to the user's attention. For elements that are form-associated custom elements, user agents should use their validation anchor instead, for the purposes of these actions.

[domenic]

OK, cool :D. I will fix the nits and merge today, assuming we have straightened out the ElementInternals which-exception questions.

Edit: I see we haven't quite straightened them out, so we'll delay another sleep cycle. New plan at #4324 (comment).

[domenic]

Bugs:

• https://bugzilla.mozilla.org/show_bug.cgi?id=1552327
• https://bugs.webkit.org/show_bug.cgi?id=197963
• https://bugs.chromium.org/p/chromium/issues/detail?id=905922

[gregwhitworth]

Quick question on this, and this may not be the right place for such a question - but why is the form value being considered a 'state'? Isn't this actually a property or attribute of the component, not its state? @domenic @tkent-google @annevk

[domenic]

Did you read the section that clarifies the difference between state and value? https://html.spec.whatwg.org/multipage/custom-elements.html#face-submission-value

[gregwhitworth]

Yes, that is what confused me, especially given this example:

Suppose that we have a form-associated custom element which asks a user to specify a date. The user specifies "3/15/2019", but the control wishes to submit "2019-03-15" to the server. "3/15/2019" would be a state of the element, and "2019-03-15" would be a submission value.

How is 3/15/2019 a state? The only state that I can think that maps to this would be something like "has-entry" or something similar. 3/15/2019 is the original author provided value, the only difference is that the submittedValue has been adjusted for what the server needs.

This paradigm can actually be seen on the web already, 3/15/2019 would be stored in value="3/15/2019" and on submit the listen to the submit event and xhr (or fetch 😉) the sanitized value actively stored in the value attribute.

Ultimately, I think conflating the original value with the likes of checked, unchecked, disabled, etc will cause author confusion.

[domenic]

This paradigm can actually be seen on the web already, 3/15/2019 would be stored in value="3/15/2019" and on submit the listen to the submit event and xhr (or fetch 😉) the sanitized value actively stored in the value attribute.

That's not quite accurate. The form submission value is that is stored in the value attribute at all times. What's seen on the screen, and other internal state of the form, is mapped to the value continuously, not on submit. In other words, dateInput.value === "2019-03-15" at all times; what the user typed is never directly accessible, but instead stored as internal state.

Maybe the issue is that you aren't thinking of state as a complex thing such as a string, but only booleans like "has entry" or "checked"? The spec is using state in the CS sense, or the component-library sense (think React's setState). Note that this is only a spec term; it isn't exposed in the API.

The checkbox provides a more straightforward example. Its internal state is given by two boolean fields: checkedness, and indeterminate. (These are also exposed externally via getters.) Thus it has 2x2 = 4 states. But the value, what is submitted to the server and reflected in the value attribute and accessible via new FormData(formElementContainingTheCheckbox), is either null or "some string" (where checkboxInputEl.value === "some string").

When you want to save and restore the state, either because of autofill or session restore or the like, you want to restore the checkedness and indeterminate booleans. You don't care about the value, because that's determined automatically as a derived function of the value="" attribute plus the state.

The API doesn't conflate state and value; it allows them to be optionally separate.

I hope this helps; let us know if there's any way the spec could explain it better.

[gregwhitworth]

@domenic much appreciated, that does indeed make more sense with the explanation.