From 3a1eb8567eee76769d64154f0deba892abdf4360 Mon Sep 17 00:00:00 2001
From: Florian Rivoal <git@florian.rivoal.net>
Date: Wed, 30 Aug 2023 11:24:48 +0200
Subject: [PATCH] [css-text-4] split text-wrap mode into sub-properties

text-wrap becomes a shorthand of text-wrap-mode and text-wrap-style,
and text-wrap-mode, rather than text-wrap, is a longhand of white-space.

See https://github.com/w3c/csswg-drafts/issues/9102
---
 css-text-4/Overview.bs | 200 ++++++++++++++++++++++++++---------------
 1 file changed, 127 insertions(+), 73 deletions(-)

diff --git a/css-text-4/Overview.bs b/css-text-4/Overview.bs
index be3c0f956c7..797c01224dc 100644
--- a/css-text-4/Overview.bs
+++ b/css-text-4/Overview.bs
@@ -1742,7 +1742,7 @@ White Space and Wrapping: the 'white-space' property</h2>
 
 	<pre class="propdef">
 	Name: white-space
-	Value: normal | pre | nowrap | pre-wrap | pre-line | <<'white-space-collapse'>> || <<'text-wrap'>> || <<'white-space-trim'>>
+	Value: normal | pre | nowrap | pre-wrap | pre-line | <<'white-space-collapse'>> || <<'text-wrap-mode'>> || <<'white-space-trim'>>
 	Initial: normal
 	Applies to: text
 	Inherited: yes
@@ -1804,7 +1804,7 @@ White Space and Wrapping: the 'white-space' property</h2>
 	white-space-mixed-004.xht
 	</wpt>
 
-	This property is a shorthand for 'white-space-collapse', 'text-wrap', and 'white-space-trim'.
+	This property is a shorthand for 'white-space-collapse', 'text-wrap-mode', and 'white-space-trim'.
 	It specifies two things:
 
 	<ul>
@@ -1831,29 +1831,29 @@ White Space and Wrapping: the 'white-space' property</h2>
 			<tr>
 				<th>'white-space'
 				<th>'white-space-collapse'
-				<th>'text-wrap'
+				<th>'text-wrap-mode'
 				<th>'white-space-trim'
 		</thead>
 		<tbody>
 		<tr>
 			<th><dfn>normal</dfn>
 			<td>''white-space-collapse/collapse''
-			<td>''text-wrap/wrap''
+			<td>''text-wrap-mode/wrap''
 			<td>''white-space-trim/none''
 		<tr>
 			<th><dfn>pre</dfn>
 			<td>''white-space-collapse/preserve''
-			<td>''text-wrap/nowrap''
+			<td>''text-wrap-mode/nowrap''
 			<td>''white-space-trim/none''
 		<tr>
 			<th><dfn>pre-wrap</dfn>
 			<td>''white-space-collapse/preserve''
-			<td>''text-wrap/wrap''
+			<td>''text-wrap-mode/wrap''
 			<td>''white-space-trim/none''
 		<tr>
 			<th><dfn>pre-line</dfn>
 			<td>''white-space-collapse/preserve-breaks''
-			<td>''text-wrap/wrap''
+			<td>''text-wrap-mode/wrap''
 			<td>''white-space-trim/none''
 		</tbody>
 	</table>
@@ -3038,7 +3038,7 @@ Phase II: Trimming and Positioning</h4>
 	Then, the entire block is rendered.
 	Inlines are laid out,
 	taking [[css-writing-modes-4#text-direction|bidi reordering]] into account,
-	and [=wrapping=] as specified by the 'text-wrap' property.
+	and [=wrapping=] as specified by the 'text-wrap-mode' and 'text-wrap-style' property.
 	As each line is laid out,
 
 	<ol>
@@ -3200,7 +3200,7 @@ Phase II: Trimming and Positioning</h4>
 
 				<li>
 					If 'white-space-collapse' is ''white-space-collapse/preserve''
-					and 'text-wrap' is not ''text-wrap/nowrap'',
+					and 'text-wrap-mode' is not ''text-wrap-mode/nowrap'',
 					the UA must (unconditionally) [=hang=] this sequence,
 					unless the sequence is followed by a [=forced line break=],
 					in which case it must [=conditionally hang=] the sequence instead.
@@ -5899,62 +5899,140 @@ Text Wrapping</h2>
 	<em>whether</em> it is allowed to wrap
 	and how multiple [=soft wrap opportunities=] within a line are prioritized
 	is controlled
-	by the 'text-wrap',
+	by the 'text-wrap-mode',
+	'text-wrap-style',
 	'wrap-before',
 	'wrap-after',
 	and
 	'wrap-inside' properties:
 
 <h3 id="text-wrap">
-Text Wrap Settings: the 'text-wrap' property</h3>
+Text Wrap Setting</h3>
+
+<h4 id="text-wrap-shorthand">
+Joint Wrapping Control: the 'text-wrap' shorthand property</h4>
 
 	<pre class="propdef">
 	Name: text-wrap
-	Value: wrap | nowrap | balance | stable | pretty
+	Value: <'text-wrap-mode'> || <'text-wrap-style'>
+	Initial: wrap
+	Applies to: see individual properties
+	Inherited: see individual properties
+	Percentages: see individual properties
+	Computed value: see individual properties
+	Animation type: see individual properties
+	</pre>
+
+	This property is a shorthand for 'text-wrap-mode' and 'text-wrap-style' properties.
+	Any omitted [=longhand=] is set to its [=initial value=].
+
+	Regardless of the 'text-wrap-mode' and 'text-wrap-style' values,
+	lines always break at forced breaks:
+	for all values,
+	line-breaking behavior defined
+	for the BK, CR, LF, CM, NL, and SG line breaking classes
+	in [[!UAX14]] must be honored.
+	Additionally, if wrapping is allowed (i.e. 'text-wrap-mode' is ''text-wrap-mode/wrap''),
+	line breaking behavior defined
+	for the WJ, ZW, and GL line-breaking classes
+	in [[!UAX14]] must be honored.
+
+	UAs that allow breaks at punctuation other than spaces
+	should prioritize breakpoints.
+	For example,
+	if breaks after slashes have a lower priority than spaces,
+	the sequence “check /etc”
+	will never break between the ‘/’ and the ‘e’.
+	The UA may use the width of the containing block,
+	the text's language,
+	and other factors in assigning priorities.
+	As long as care is taken to avoid such awkward breaks,
+	allowing breaks at appropriate punctuation other than spaces
+	is recommended,
+	as it results in more even-looking margins,
+	particularly in narrow measures.
+
+<h4 id="text-wrap-mode">
+Deciding Whether to Wrap: the 'text-wrap-mode' property</h4>
+
+	<pre class="propdef">
+	Name: text-wrap-mode
+	Value: wrap | nowrap
 	Initial: wrap
-	Applies to: text and <a>block containers</a>
+	Applies to: text
 	Inherited: yes
 	Percentages: n/a
 	Computed value: specified keyword
 	Animation type: discrete
 	</pre>
 
-	This property specifies the mode for text wrapping.
+	Issue: The name of this property is a placeholder,
+	pending the CSSWG finding a better name.
+
+	Note: This property is a [=longhand=]
+	of both 'white-space' and 'text-wrap'.
+
+	This property specifies whether lines may [=wrap=] at unforced [=soft wrap opportunities=]
+	(see [[#line-breaking|Line Breaking]]).
 	Possible values:
 
-	<dl dfn-for=text-wrap dfn-type=value>
+	<dl dfn-for=text-wrap-mode dfn-type=value>
 		<dt><dfn>wrap</dfn>
 		<dd>
-			Inline-level content may break across lines
+			Content may break across lines
 			at allowed <a>soft wrap opportunities</a>,
-			as determined by the line-breaking rules in effect
+			as determined by the line-breaking rules in effect,
 			in order to minimize <a>inline-axis</a> overflow.
 
-			The exact algorithm is UA-defined.
+		<dt><dfn>nowrap</dfn>
+		<dd>
+			Inline-level content does not break across lines;
+			content that does not fit within the block container overflows it.
+	</dl>
+
+<h4 id="text-wrap-style">
+Selecting How to Wrap: the 'text-wrap-style' property</h4>
+
+	<pre class="propdef">
+	Name: text-wrap-style
+	Value: auto| balance | stable | pretty
+	Initial: auto
+	Applies to: [=block containers=] hat establish an [=inline formatting context=]
+	Inherited: yes
+	Percentages: n/a
+	Computed value: specified keyword
+	Animation type: discrete
+	</pre>
+
+	When wrapping is allowed
+	(see 'text-wrap-mode'),
+	this property selects between several approaches for wrapping lines,
+	trading off between speed, quality and style of layout, or stability.
+	It does not change which [=soft wrap opportunity=] exist,
+	but changes how the user agent selects among them.
+	Possible values:
+
+	<dl dfn-for=text-wrap-style dfn-type=value>
+		<dt><dfn>auto</dfn>
+		<dd>
+			The exact algorithm for selecting
+			which [=soft wrap opportunity=] to break at is UA-defined.
 			The algorithm <em>may</em> consider multiple lines
 			when making break decisions.
 			The UA <em>may</em> bias for speed over best layout.
 			The UA <em>must not</em> attempt to even out all lines
-			(including the last) as for ''text-wrap/balance''.
+			(including the last) as for ''text-wrap-style/balance''.
 			This value selects the UA’s preferred (or most Web-compatible)
 			wrapping algorithm.
 
-		<dt><dfn>nowrap</dfn>
-		<dd>
-			Inline-level content does not break across lines;
-			content that does not fit within the block container overflows it.
-
 		<dt><dfn>balance</dfn>
 		<dd>
-			Same as ''text-wrap/wrap'' for <a>inline boxes</a>.
-			For <a>block containers</a> that
-			establish an <a>inline formatting context</a>,
-			line breaks are chosen to balance
+			Line breaks are chosen to balance
 			the remaining (empty) space in each line box,
-			if better balance than ''text-wrap/wrap'' is possible.
+			if better balance than ''text-wrap-style/auto'' is possible.
 			This must not change the number of line boxes
 			the block would contain
-			if 'text-wrap' were set to ''text-wrap/wrap''.
+			if 'text-wrap' were set to ''text-wrap-style/auto''.
 
 			The remaining space to consider
 			is that which remains after placing floats and inline content,
@@ -5966,70 +6044,40 @@ Text Wrap Settings: the 'text-wrap' property</h3>
 
 			The exact algorithm is UA-defined.
 
-			UAs may treat this value as ''text-wrap/wrap'' if there are more than ten lines to balance.
+			UAs may treat this value as ''text-wrap-style/auto'' if there are more than ten lines to balance.
 
 		<dt><dfn>stable</dfn>
 		<dd>
-			When applied to a <a>block container</a>
-			that establishes an <a>inline formatting context</a>,
-			specifies that content on subsequent lines
+			Specifies that content on subsequent lines
 			<em>should not</em> be considered when making break decisions
 			so that when editing text any content before the cursor
 			remains stable;
-			otherwise equivalent to ''text-wrap/wrap'',
+			otherwise equivalent to ''text-wrap-style/auto'',
 
 		<dt><dfn>pretty</dfn>
 		<dd>
-			When applied to a <a>block container</a>
-			that establishes an <a>inline formatting context</a>,
-			specifies the UA <em>should</em> bias for better layout over speed,
+			Specifies the UA <em>should</em> bias for better layout over speed,
 			and is expected to consider multiple lines,
 			when making break decisions.
-			Otherwise equivalent to ''text-wrap/wrap'',
+			Otherwise equivalent to ''text-wrap-style/auto'',
 	</dl>
 
-	Regardless of the 'text-wrap' value,
-	lines always break at forced breaks:
-	for all values,
-	line-breaking behavior defined
-	for the BK, CR, LF, CM, NL, and SG line breaking classes
-	in [[!UAX14]] must be honored.
-	Additionally, if wrapping is allowed (i.e. 'text-wrap' is not ''text-wrap/nowrap''),
-	line breaking behavior defined
-	for the WJ, ZW, and GL line-breaking classes
-	in [[!UAX14]] must be honored.
-
-	UAs that allow breaks at punctuation other than spaces
-	should prioritize breakpoints.
-	For example,
-	if breaks after slashes have a lower priority than spaces,
-	the sequence “check /etc”
-	will never break between the ‘/’ and the ‘e’.
-	The UA may use the width of the containing block,
-	the text's language,
-	and other factors in assigning priorities.
-	As long as care is taken to avoid such awkward breaks,
-	allowing breaks at appropriate punctuation other than spaces
-	is recommended,
-	as it results in more even-looking margins,
-	particularly in narrow measures.
-
 	<!-- add a sample prioritization algorithm -->
 
-	Note: The ''text-wrap/wrap'' value will typically map
+	Note: The ''text-wrap-style/auto'' value will typically map
 	to Web browsers’ speedy legacy line breaking,
 	which has so far used first-fit/greedy algorithms
 	that can often give sub-optimal results. 
 	UAs can experiment with better line breaking algorithms
 	with this default value, 
 	but as optimal results often take more time,
-	''text-wrap/pretty'' is offered as an opt-in
+	''text-wrap-style/pretty'' is offered as an opt-in
 	to take more time for better results.
-	The ''text-wrap/pretty'' value is intended for body text,
+	The ''text-wrap-style/pretty'' value is intended for body text,
 	where the last line is expected to be a bit shorter than the average line;
-	the ''text-wrap/balance'' value is intended for titles and captions,
+	the ''text-wrap-style/balance'' value is intended for titles and captions,
 	where equal-length lines of text tend to be preferred;
-	and the ''text-wrap/stable'' is intended for sections that are,
+	and the ''text-wrap-style/stable'' is intended for sections that are,
 	or are likely become toggled as,
 	editable.
 
@@ -10425,6 +10473,10 @@ Changes</h2>
 	Changes specific to Level 4 are listed below.
 
 	Significant changes since the <a href="https://www.w3.org/TR/2023/WD-css-text-4-20230329/">29 March 2023 Working Draft</a> include:
+	* Recast the 'text-wrap' property as a shorthand of two new properties,
+		'text-wrap-mode' and 'text-wrap-style',
+		and making 'text-wrap-mode' rather than 'text-wrap'
+		a longhand of the 'white-space' property.
 
 	Significant changes since the <a href="https://www.w3.org/TR/2023/WD-css-text-4-20230301/">1 March 2022 Working Draft</a> include:
 	* Completed the translation of 'white-space' to multiple longhands by
@@ -10508,9 +10560,11 @@ Additions Since Level 3</h3>
 
 	* 'word-boundary-detection', for automatically detecting word boundaries (at risk)
 	* 'word-boundary-expansion', for transforming word separators
-	* 'white-space-collapse' longhand (of the longstanding 'white-space' property) and its ''preserve-spaces'' and ''white-space-collapse/discard'' values
-	* 'white-space-trim', for trimming excess white space at the boundaries of an element
-	* 'text-wrap' longhand (of the 'white-space' property) and its ''balance'', ''stable'', and ''pretty'' values
+	* breaking up of the 'white-space' property into multiple longhands:
+		* 'white-space-collapse' longhand (of the longstanding 'white-space' property) and its ''preserve-spaces'' and ''white-space-collapse/discard'' values
+		* 'white-space-trim', for trimming excess white space at the boundaries of an element
+		* 'text-wrap-mode' to control whether wrapping occurs or not
+	* 'text-wrap-style' and its ''balance'', ''stable'', and ''pretty'' values
 	* 'wrap-before', 'wrap-after', and 'wrap-inside', to avoid or force wrapping (similar to the 'break-*' properties for pagination)
 	* 'hyphenate-character', to explicitly control the hyphenation character
 	* 'hyphenate-limit-zone', 'hyphenate-limit-chars', 'hyphenate-limit-lines', 'hyphenate-limit-last', for better control over automatic hyphenation