From ffb121049e7593c8ee0fdd2024484d30d0c2b5db Mon Sep 17 00:00:00 2001 From: Kaleidea <74888177+Kaleidea@users.noreply.github.com> Date: Fri, 19 Nov 2021 10:44:56 +0100 Subject: [PATCH] Add "The search element" section Defines: - attr-aria-role-search Credit for the explainer and examples: @scottaohara --- source | 191 ++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 177 insertions(+), 14 deletions(-) diff --git a/source b/source index 013e9d42034..13dbc094c63 100644 --- a/source +++ b/source @@ -3922,6 +3922,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute

In addition, the following aria-* content @@ -42727,6 +42728,8 @@ interface HTMLTableCellElement : HTMLElement {

Introduction

+

A form is either a form or a search element.

+

A form is a component of a web page that groups form controls, such as text, buttons, @@ -42748,7 +42751,9 @@ interface HTMLTableCellElement : HTMLElement {

For the purposes of this brief introduction, we will create a pizza ordering form.

-

Any form starts with a form element, inside which are placed the controls. Most +

Any form + starts with a form or search element, + which then contains among others form-associated elements. Most controls are represented by the input element, which by default provides a text control. To label a control, the label element is used; the label text and the control itself go inside the label element. Each part of a form is considered a @@ -43419,9 +43424,11 @@ interface HTMLTableCellElement : HTMLElement {

Flow content.
Palpable content.
Contexts in which this element can be used:
-
Where flow content is expected.
+
Where flow content is expected, but not as a descendant of + another form or search element.
Content model:
-
Flow content, but with no form element descendants.
+
Flow content, but with no form or search element + descendants.
Content attributes:
Global attributes
accept-charset
@@ -43487,8 +43494,8 @@ interface HTMLFormElement : HTMLElement { represents the form's name within the forms collection. The value must not be the empty string, and the value must be unique amongst the - form elements in the forms collection that - it is in, if any.

+ form and search elements in the + forms collection that it is in, if any.

The autocomplete attribute is an enumerated @@ -43873,6 +43880,132 @@ interface HTMLFormElement : HTMLElement { +

The search element

+ +
+
Categories:
+
Flow content.
+
Palpable content.
+
Contexts in which this element can be used:
+
Where flow content is expected, but not as a descendant of + another form or search element.
+
Content model:
+
Flow content, but with no form or search element + descendants.
+
Content attributes:
+
Global attributes
+
form attributes
+
action — URL to use for + form submission or unspecified to disable form submission
+
Accessibility considerations:
+
For authors.
+
For implementers.
+
DOM interface:
+
Uses HTMLFormElement, as defined for form elements.
+
+ +

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. This could be a search of the web site or application; a way of searching or filtering + search results on the current web page; or a global or Internet-wide search function.

+ +

The search element is almost identical to the form + element with the following differences:

+ +
    +

  1. If the action attribute is unspecified then + form submission is disabled, only the + submit event is fired.

    2. +

  2. The search element has the search + role, screen readers announce it as the "search landmark" when focus navigates into it.

    3. +
+ +

It's not appropriate to use the search element just for presenting + search results, though suggestions and links as part of "quick search" results can be + included as part of a search feature. Rather, a returned web page of search results would instead + be expected to be presented as part of the main content of that web page.

+ +
+

In the following example, the author is including a search form within the + header of the web page:

+ + 
<header>
+  <h1><a href="/">My fancy blog</a></h1>
+  ...
+  <search action="search.php">
+    <label for="query">Find an article</label>
+    <input id="query" name="q" type="search">
+    <button type="submit">Go!</button>
+  </search>
+</header>
+
+ +
+

In this example, the author has implemented their web application's search functionality + entirely with JavaScript. There is no use of the action attribute to perform + server-side submission. The containing search element semantically identifies + the purpose of the descendant content as representing search capabilities.

+ + 
<search>
+  <label>
+    Find and filter your query
+    <input type="search" id="query">
+  </label>
+  <label>
+    <input type="checkbox" id="exact-only">
+    Exact matches only
+  </label>
+
+  <section>
+    <h3>Results found:</h3>
+    <ul id="results">
+      <li>
+        <p><a href="services/consulting">Consulting services</a></p>
+        <p>
+          Find out how we can help you improve your business with our integrated consultants, Bob and Rob.
+        </p>
+      </li>
+      ...
+    </ul>
+    <!--
+      when a query returns or filters out all results
+      render the no results message here
+    -->
+    <output id="no-results"></output>
+  </section>
+</search>
+
+ +
+

In the following example, the page has two search features. The first is located in the + web page's header and serves as a global mechanism to search the web site's + content. Its purpose is indicated by its specified title attribute. The results + are presented on a new page at the URL set by the action + attribute. The second search is included as part of the main content of the page, as it + represents a mechanism to search and filter the content of the current page without loading a + new page. It contains a heading to indicate its purpose.

+ + 
<body>
+  <header>
+    ...
+    <search title="Website" action="/search">
+      ...
+    </search>
+  </header>
+  <main>
+    <h1>Hotels near your location</h1>
+     <search>
+       <h2>Filter results</h2>
+       ...
+     </search>
+     <article>
+      <!-- search result content -->
+    </article>
+  </main>
+</body>
+
+

The label element

@@ -53694,9 +53827,15 @@ form.method === input; // => true

The action and formaction - content attributes, if specified, must have a value that is a valid non-empty URL + content attributes of a form or button, if specified, + must have a value that is a valid non-empty URL potentially surrounded by spaces.

+

The action + content attribute of a search element, if specified, + must have a value that is a valid URL potentially surrounded by spaces.
+ If not specified, the search element disables form submission.

+

The action of an element is the value of the element's formaction attribute, if the element is a submit button and has such an attribute, or the value of its @@ -123065,6 +123204,19 @@ interface External { HTMLScriptElement + + search + Form container for search controls, optionally user-submittable + flow; + palpable + flow + flow + globals; + form attributes; + action; + HTMLFormElement + + section Generic document or application section @@ -123967,9 +124119,10 @@ interface External { Ordered set of unique space-separated tokens, none of which are identical to another, each consisting of one code point in length action - form + form; + search URL to use for form submission - Valid non-empty URL potentially surrounded by spaces + Valid non-empty URL potentially surrounded by spaces, can be empty for search element allow iframe @@ -124009,7 +124162,8 @@ interface External { "characters" autocomplete - form + form; + search Default setting for autofill feature for controls in the form "on"; "off" @@ -124191,7 +124345,8 @@ interface External { "true"; "false" enctype - form + form; + search Entry list encoding type to use for form submission "application/x-www-form-urlencoded"; "multipart/form-data"; "text/plain" @@ -124457,7 +124612,8 @@ interface External { Valid media query list method - form + form; + search Variant to use for form submission "GET"; "POST"; @@ -124503,7 +124659,8 @@ interface External { Text* name - form + form; + search Name of form to use in the document.forms API Text* @@ -124544,7 +124701,8 @@ interface External { Text novalidate - form + form; + search Bypass form control validation for form submission Boolean attribute @@ -124784,7 +124942,8 @@ interface External { Valid browsing context name or keyword target - form + form; + search Browsing context for form submission Valid browsing context name or keyword @@ -125768,6 +125927,10 @@ interface External { samp HTMLElement + + search + HTMLFormElement + script HTMLScriptElement : HTMLElement