[css-highlight-api-1] Add type enum attribute to Highlight #6498 (#6724)

dandclark · web-flow · commit 5e4d59108d38 · 2021-12-01T10:34:00.000-08:00
* Add `type` attribute to `Highlight`

* Say what UAs should do with the type. Explain why initial set of types was chosen.
diff --git a/css-highlight-api-1/Overview.bs b/css-highlight-api-1/Overview.bs
@@ -161,16 +161,25 @@ Creating Custom Highlights</h3>
 	See [[#range-invalidation]] for more details about this choice and its implications.
 
 	<xmp class="idl">
+	enum HighlightType {
+		"highlight",
+		"spelling-error",
+		"grammar-error"
+	};
+
 	[Exposed=Window]
 	interface Highlight {
 		constructor(AbstractRange... initialRanges);
 		setlike<AbstractRange>;
 		attribute long priority;
+		attribute HighlightType type;
 	};
 	</xmp>
 
 	See [[#priorities]] for more information on the {{Highlight/priority}} attribute.
 
+	See [[#highlight-types]] for more information on the {{Highlight/type}} attribute.
+
 	<div algorithm="to create a custom highlight">
 		When the <dfn for=Highlight constructor>Highlight(AbstractRange... initialRanges)</dfn> constructor is invoked,
 		run the following steps:
@@ -180,6 +189,8 @@ Creating Custom Highlights</h3>
 				Let |highlight| be the new {{Highlight}} object.
 			<li>
 				Set |highlight|'s {{Highlight/priority}} to <code>0</code>.
+			<li>
+				Set |highlight|'s {{Highlight/type}} to {{HighlightType/highlight}}.
 			<li>
 				For each |range| of {{initialRanges}},
 				let |rangeArg| be the result of [=converted to an ECMAScript value|converting=] |range| to an ECMAScript value,
@@ -450,6 +461,44 @@ Priority of Overlapping Highlights</h4>
 		</div>
 	</div>
 
+<h4 id=highlight-types>
+Highlight types</h4>
+
+	A [=custom highlight=]'s {{Highlight/type}} attribute is used by authors to specify the semantic
+	meaning of the highlight. This allows assistive technologies to include this meaning when
+	exposing the highlight to users.
+
+	A custom highlight will have a default type of {{HighlightType/highlight}} if its
+	{{Highlight/type}} attribute has not been explicitly set.
+
+	Note: Authors should set a [=custom highlight=]'s {{Highlight/type}} to
+	{{HighlightType/spelling-error}} when that [=custom highlight=] is being used to emphasize
+	misspelled content. Authors should set a [=custom highlight=]'s {{Highlight/type}} to
+	{{HighlightType/grammar-error}} when that [=custom highlight=] is being used to emphasize
+	content that is grammatically incorrect. For all other use cases {{Highlight/type}} should
+	be left as {{HighlightType/highlight}}.
+
+	UAs should make [=custom highlight=]s available to assistive technologies. When exposing a
+	highlight using a given platform accessibility API, UAs should expose the semantic meaning of
+	the highlight as specified by its {{Highlight/type}} attribute with as much specificity as
+	possible for that accessibility API.
+
+	Note: For example, if a platform accessibility API has the capability to express spelling errors
+	and grammar errors specifically, then UAs should use these capabilities to convey the semantics
+	for highlights with {{HighlightType/spelling-error}} and {{HighlightType/spelling-error}}.
+	If an accessibility API only has the capability to express spelling errors, then UAs should
+	convey both highlights with {{HighlightType/spelling-error}} and with
+	{{HighlightType/grammar-error}} using spelling error semantics. If an accessibility API has
+	support for expressing neither spelling errors nor grammar errors, then UAs should expose all
+	highlights as generic {{HighlightType/highlight}} regardless of their actual {{Highlight/type}}.
+
+	Note: This initial set of types was chosen because they are expected to be popular use cases
+	for Highlight API and there is some existing support for expressing their semantics in platform
+	accessibility APIs today. Accessibility APIs currently don't have any way to express the
+	specific semantics of other expected Highlight API use cases. More types may be added to
+	{{HighlightType}} as accessibility APIs gain support for expressing additional popular use
+	cases of Highlight API.
+
 <h2 id=responding-to-changes>
 Responding to Changes</h2>
 
