[css-ruby-1] Define 'visibility: collapse' to trigger annotation hiding behavior. #5927

Author: fantasai

css-ruby-1/Overview.bs

@@ -619,20 +619,26 @@ Complex Spanning with Nested Ruby</h4>
 	Waiting until layout is better-defined to find out...
 -->
 
-<h3 id="autohide">
-Autohiding Base-identical Annotations</h3>
-
-	If a [=ruby annotation=] has the exact same text content as its base,
-	it is <dfn lt="hidden ruby annotation | hidden annotation">hidden</dfn>.
-	Hiding a [=ruby annotation=] does not affect annotation [=pairing=].
+<h3 id="hiding" oldids="autohide">
+Hiding Annotations: ''visibility: collapse'' and auto-hidden ruby</h3>
+
+	A [=ruby annotation=] whose 'visibility' is ''visibility/collapse''
+	is a <dfn lt="hidden annotation | hidden ruby annotation | hide" local-lt="hidden">hidden annotation</dfn>.
+	Additionally,
+	if a [=ruby annotation=] has the exact same text content as its base,
+	it is automatically [=hidden=]
+	(<dfn lt="auto-hidden | auto-hide">auto-hidden</dfn>)
+	by the UA.
+
+	[=Hiding=] a [=ruby annotation=] does not affect annotation [=pairing=].
 	However the [=hidden annotation=] is not visible,
 	and it has no impact on layout
 	other than to separate adjacent sequences of [=ruby annotation boxes=] within its level,
 	as if they belonged to separate segments
 	and the [=hidden annotation=]’s base were not a [=ruby base=] but an intervening inline.
 
 	<div class="example">
-		This is to allow correct inlined display of annotations
+		Auto-hiding allows correct inlined display of annotations
 		for Japanese words that are a mix of kanji and hiragana.
 		For example, the word <span lang=ja>振り仮名</span> should be inlined as
 
@@ -653,18 +659,80 @@ Autohiding Base-identical Annotations</h3>
 		</div>
 	</div>
 
-	When the computed value of 'ruby-merge' is ''merge'',
-	the autohiding is disabled.
-	When the computed value of 'ruby-merge' is ''ruby-merge/auto'',
-	the user agent may decide whether to autohide or not,
-	but it is recommended to autohide if the algorithm the user agent chose
-	produces the results similar to ''separate'' would produce.
+	<div class="example">
+		The Japanese word in this example is composed of three kanji characters,
+		one of which is taught in first grade,
+		while the other two are more advanced.
+		(Characters colored to show base-pair correspondances.)
+
+		<xmp highlight=html>
+		<ruby><rb>昆<rb>虫<rb>記<rt>こん<rt class=easy>ちゅう<rt>き</ruby>
+		</xmp>
+
+		<figure>
+			<img src="images/ruby-pairing-full.png" width=122
+			     alt="昆虫記, with phonetic annotations on all three characters.
+			     Because the middle annotation is wider than its base,
+			     space has been introduced around the base character
+			     to prevent its annotation from colliding with the adjacent annotations.">
+			<figcaption>Fully annotated three-character word</figcaption>
+		</figure>
+
+		Although some readers might need pronunciation guidance
+		on all three characters,
+		for other audiences it is more appropriate
+		to hide the annotation on the easier character.
+		Applying ''visibility: collapse'' enables this hiding:
+
+		<figure>
+			<img src="images/ruby-pairing-collapse.png" width=105
+			     alt="昆虫記, with phonetic annotations centered over
+			          the first and last characters.">
+			<figcaption>Middle annotation as ''visibility: collapse''</figcaption>
+		</figure>
+
+		The [=hiding=] behavior of ''visibility: collapse''
+		differs from ''visibility: hidden''--
+		which makes the annotation invisible,
+		but does not remove its impact on layout:
+
+		<figure>
+			<img src="images/ruby-pairing-invisible.png" width=122
+			     alt="昆虫記, with phonetic annotations on the first and last characters.
+			     Over the second one, even though no annotation is showing,
+			     space is reserved as if to hold it,
+			     which pushes the base characters apart.">
+			<figcaption>Middle annotation as ''visibility: hidden''</figcaption>
+		</figure>
+
+		It also differs from ''display: none''
+		because ''visibility: collapse'' preserves pairing relationships,
+		whereas ''display: none'' removes the box from the tree entirely,
+		disturbing the pairing of any annotations after it:
+
+		<figure>
+			<img src="images/ruby-pairing-discard.png" width=107
+			     alt="昆虫記, with mispaired phonetic annotations:
+			     the annotation for the second character having been removed,
+			     the annotation for the third character is displayed over the second one.">
+			<figcaption>Middle annotation as ''display: none''</figcaption>
+		</figure>
+	</div>
+
+	When the [=computed value=] of 'ruby-merge' on the [=annotation container=]
+	is ''merge'',
+	[=hiding=] is disabled.
+	When that value is ''ruby-merge/auto'',
+	the user agent may decide whether to disable [=hiding=] of its annotations,
+	but it is recommended to enable [=hiding=]
+	if the user agent’s layout algorithm
+	produces the results similar to ''separate''.
 
-	The content comparison for this auto-hiding behavior
+	The content comparison for [=auto-hiding=]
 	takes place prior to white space collapsing ('white-space') and text transformation ('text-transform')
 	and ignores elements (considers only the <code>textContent</code> of the boxes).
 
-	Note: Future levels of CSS Ruby may add controls for auto-hiding,
+	Note: Future levels of CSS Ruby may add controls for [=auto-hiding=],
 	but in this level it is always forced.
 
 <h3 id="white-space">
@@ -2186,6 +2254,9 @@ Changes since the 29 April 2020 WD</h3>
 			and made it the [=initial value=].
 		<li>Renamed <css>collapse</css> value of 'ruby-merge' to ''ruby-merge/merge''.
 			(<a href="https://github.com/w3c/csswg-drafts/issues/5004">Issue 5004</a>)
+		<li>Defined ''visibility: collapse'' to explicitly [=hide=] an annotation
+			the same way [=auto-hidden=] annotations are hidden.
+			(<a href="https://github.com/w3c/csswg-drafts/issues/5927">Issue 5927</a>)
 		<li>Specified more precisely which properties apply to the various ruby display types
 			([[#box-style]])
 			and defined ruby, ruby base, and ruby annotation boxes