Proposal: Specification and implementation of <search> element with form functionality

[Kaleidea]

This is the proposed specification and implementation of the search element following the best practice usage (MDN, WAI-ARIA), as requested by developers. It covers both usage patterns: server-side and client-side rendering of the search results.

• Specification draft:
  • Readable form (generated)
  • Specification changes (source, see below)
• Implementations (proof-of-concept):
  • Chromium (commits on GitHub)
  • WebKit (commits on GitHub)
  • Firefox in progress (commits in Mercurial)
• Implementation explanation

Contents

1. Specification changes
2. Motivation
3. Feature definition
4. Use-cases
5. Requests for this feature
6. Prior art

Subpages

1. Migration guide, usage patterns
2. Implementation details
3. Including the original proposal: <div> functionality
4. Alternatives

Specification changes

• Readable form (generated)
• Categorised changes (source):
  • What developers will read: "The search element" section
  • Add the <search> element to tag lists
  • Systematic changes: Rewording "form elements" -> "forms", etc.
  • Optional: Clarification notes
• Breakdown of changes: each commit contains a different transformation pattern for quicker (batched) verification of the systematic changes.

Motivation

The <search> element with form functionality is

• a popular developer request (see below: Requests for this feature)
• the best practice as demonstrated by the MDN example and the WAI-ARIA example.
• the common sense mental model: "The search element represents a part of a document or application that contains a set of form controls or other content related to performing a search or filtering operation." A set of form controls is a form.

This approach meets developers' expectations, guaranteeing the best API ergonomy. In the long term this will reduce the learning curve, increase developer satisfaction, make accessibility more intuitive and consequently improve the quality of the World Wide Web. These long-term benefits are worth the little extra effort up front, which is mostly a systematic, trivial rewording of the "Forms" section in the HTML specification to refer to "form" instead of "form element".

Feature definition

1. <div role=search> is shortened to <search>, form submission is disabled
2. <form role=search action="..."> is shortened to <search action="...">

In the first case (div) form submission is an unwanted feature, therefore disabled. The second case behaves equivalently to a form with role=search.
The action attribute's presence distinguishes between the two cases. A form without the action attribute is migrated to <search action="">, this slightly alters the specification of the action attribute on the search element.

Alternatives considered: method=none / nosubmit boolean attribute. To support the migration of the div usage without adding extra attributes the absence of action must disable form submission, therefore the alternatives would be redundant.

Other form functionality is opt-in, if the developer makes no use of it then it does not change the application's behavior:

• Form validation is optional.
• Reset button is optional.
• Autocomplete is on by default for <input type=searchbox> even without a form.
• Registering <search> in document.forms has no effect on behavior.
• Associating with descendant form controls has no effect on behavior unless the developer makes use of it in which case it is a benefit.

Nesting of <search> and <form> is invalid in any combination:

• <search><search> is semantically meaningless.
• <div role=search>...<form> and <form>...<div role=search> can often be refactored to a single <search>. Researching usage patterns in the wild suggests this to be possible in most cases.

Use-cases

1. Site search: typically in the header/sidebar, providing a pop-up list of suggestions (client-side rendered), navigating to a results page (server-side rendered).
2. Table/dataset filtering: in the main content, typically client-side rendered.
3. Page search (eg. text editor): changes positioning and selection client-side.

The most common use-case for a <search> element is site search. The best practice for implementation is <form role="search" action="/search">. Exception to this is client-side rendered search results (use-cases without page navigation). In that case a site search page (also advertised in sitesearch.xml) can be used as a no-JS fallback. JS execution cannot be taken for granted, therefore a fallback improves availability in case of unreliable internet or disabled JS.

Requests for this feature

• tweet - "Using a <form role="search"> gives you significant functionality beyond the ARIA semantics."
• tweet - "Should the <search> element be an extension of the <form> element such that it can process its own form actions without having to also be wrapped in a <form>?"
• tweet - "<search> makes sense and would be great if [...] it could process its own form actions without a <form>. I would expect that feature would make (correct) usage of the element by devs more likely too"
• tweet - "The semantics of <form role="search"> is more motivating."
• tweet - "Aren't you meant to add role="search" to the <form> element rather than a separate element?"
• tweet - "Extra attribute on a <form>?"
• github - "I haven't run into a need for <div role="search"> instead of <form role="search">"
• github - "I would be unlikely to employ <search> without <form>"

Prior art

This proposal builds upon the request for the <search> element implementing <div role=search>. The decisions made there that don't affect form functionality also apply here:

• search { display: block } in the user agent stylesheet
• Is it a paragraph closing element? Implementation cost: 2 lines of code.

Subpages

Due to length these are split:

1. Migration guide, usage patterns
2. Implementation details
3. Including the original proposal: <div> functionality
4. Alternatives

[domenic]

You've already made your case in the other issue, and others have addressed it point by point. As such I'll close this as it's duplicative.

[Kaleidea]

others have addressed [your case] point by point.

This is objectively false.

1. You haven't answered any of my questions.
2. Nobody has discussed the implementation details.
3. Only @scottaohara (editor) has responded to some orthogonal questions and referred to the disproven assumption of high implementation cost.
4. @bathos (developer?) expressed his ambivalent support ("I would be unlikely to employ <search> without <form>").

I've worked more than a week on this proposal. Immediately closing this issue without allowing implementers to think about it undermines my work and trumps the WHATWG's principle of openness.

It is a way to suppress a viewpoint that you've strongly disagreed with, as such also a violation of the code of conduct: "... oppressive, or exclusionary remarks, are not allowed."

To remedy this harm please reopen the issue and delete your comment, in which case I'll delete mine too.

[bathos]

@Kaleidea (yes, developer). Though I did appreciate the API surface you proposed and would have found it intuitive, anything I know about search role patterns I learned in or because of that thread! My opinions should be weighed accordingly :)

[Kaleidea]

Thank you @bathos for the clarification :-) I'm working hard to get in contact with implementers from the 3 browsers. It's hard 😆

[scottaohara]

@Kaleidea just to clarify, I am not an editor of the HTML Living Standard.

[Kaleidea]

Thank you, @scottaohara. What's the word for your role in writing the examples and explanation for the current topic?

[bathos]

I should prob add some more clarification, v candidly:

The opinion I expressed was sincere: were it up to me (and based only on my current, perhaps very limited) understanding, the API surface you proposed is what I'd prefer. But my motivation for sharing was not to encourage that approach - it was more to maybe wind down the convo.

I was getting a strong sense that the pattern of consecutive, long comments arguing an "opposition" angle were breaching norms for constructive collaborative convo. I am certain that you did not intend that at all - the posts are written excellently and it seems you just feel strongly about the case you're making and its merit. Even so, cadence alone can lead to dominating a conversation, and I figured seeing that there were actually other folks (at least one) who saw value in what you were describing might help make it clear that you were being heard (...and didn't need to repeat it again, at least not immediately :).

[Kaleidea]

Thank you for your honest feedback. I indeed chose the wrong approach, but that became apparent only afterward. https://kaleidea.github.io/whatwg-search-proposal/ is a more consumable presentation, I hope.