[css-inline-3] Split text-box-edge into two properties and create a shorthand with text-box-trim #8829 #8696

fantasai · fantasai · commit 7869dc6823e2 · 2024-08-02T13:54:36.000-04:00
diff --git a/css-inline-3/Overview.bs b/css-inline-3/Overview.bs
@@ -957,7 +957,7 @@ Logical Heights and Inter-line Spacing</h2>
 	The [=block-axis=] sizing of a [=line box=]
 	depends on the sizes and [[#alignment|alignment]] of its [=inline-level=] contents.
 	This sizing is controlled by
-	the 'line-height', 'text-box-edge', 'text-box-trim', and 'inline-sizing' properties.
+	the 'line-height' and 'line-fit-edge' properties.
 
 <h3 id="line-height-property">
 Line Spacing: the 'line-height' property</h3>
@@ -1035,7 +1035,7 @@ Line Spacing: the 'line-height' property</h3>
 	See also <a href="https://github.com/w3c/csswg-drafts/issues/3118">Issue 3118</a>
 	and <a href="https://github.com/w3c/csswg-drafts/issues/2165">Issue 2165</a>.
 
-	Note: When 'text-box-edge' is ''text-box-edge/leading'',
+	Note: When 'line-fit-edge' is ''line-fit-edge/leading'',
 	the margins, borders, and padding of [=inline boxes=]
 	do not affect the line box’s height calculation.
 	However, they are still rendered around these boxes.
@@ -1045,11 +1045,11 @@ Line Spacing: the 'line-height' property</h3>
 	potentially obscuring earlier content.
 
 <h3 id="text-edges">
-Inline Box Edge Metrics: the 'text-box-edge' property</h3>
+Text Edge Metrics: the 'line-fit-edge' property</h3>
 
 	<pre class="propdef">
-	Name: text-box-edge
-	Value: leading | [ text | cap | ex | ideographic | ideographic-ink ] [ text | alphabetic | ideographic | ideographic-ink ]?
+	Name: line-fit-edge
+	Value: leading | <<text-edge>>
 	Initial: leading
 	Applies to: [=inline boxes=]
 	Inherited: yes
@@ -1062,37 +1062,35 @@ Inline Box Edge Metrics: the 'text-box-edge' property</h3>
 	and might change significantly
 	as design critiques and use cases are registered
 	and various details and interactions with other properties are worked out.
-	<strong>Do not implement (yet).</strong>
+	<strong>Do not ship (yet).</strong>
 
 	[=Inline boxes=], whose primary purpose is to contain text,
 	are sized in the [=block axis=] based on their font metrics.
-	The 'text-box-edge' property controls which metrics are used.
-
-	The chosen metrics are used as the basis
+	The 'line-fit-edge' property controls which metrics are used.
+	These chosen metrics are used as the basis
 	for the [=layout bounds=] of the [=inline box=]
-	(if it is not the [=root inline box=]).
-	The 'text-box-trim' property can be used in conjunction
-	to match the [=content edges=] to these same metrics.
+	(if it is not the [=root inline box=]);
+	and also, by default, are the metrics used for 'text-box-trim'.
+
+	The <dfn><<text-edge>></dfn> value,
+	which identifies specific font metrics,
+	expands to
+
+	<pre class=prod>
+		<<text-edge>> = [ text | cap | ex | ideographic | ideographic-ink ] [ text | alphabetic | ideographic | ideographic-ink ]?
+	</pre>
 
 	The first value specifies the text [=over=] edge;
 	the second value specifies the text [=under=] edge.
 	If only one value is specified,
 	both edges are assigned that same keyword if possible;
-	else ''text-box-edge/text'' is assumed as the missing value.
+	else ''<<text-edge>>/text'' is assumed as the missing value.
 
 	ISSUE(5236): Do we need [=longhands=] or is this shorthand enough?
 
-	Note: The ''text-box-edge/leading'' and ''text-box-edge/text'' values
-	rely on the font [=ascent=] and [=descent=] to make sure the text fits.
-	Other values are more likely to result in overlap or overflow
-	caused by ascents above the specified metrics
-	(such as for diacritics),
-	so authors using these values need to be careful
-	to provide sufficient spacing for the text.
-
 	Values have the following meanings:
 
-	<dl dfn-for="text-box-edge" dfn-type=value>
+	<dl dfn-for="line-fit-edge,<<text-edge>>" dfn-type=value>
 		<dt><dfn>leading</dfn>
 		<dd>
 			Use the [=ascent=]/[=descent=] plus any positive [=half-leading=].
@@ -1124,32 +1122,36 @@ Inline Box Edge Metrics: the 'text-box-edge' property</h3>
 			Use the [=alphabetic baseline=].
 	</dl>
 
-	Unless 'text-box-edge' is ''text-box-edge/leading''--
+	ISSUE(8067): Is ''line-fit-edge/text'' a reasonable name for the ascent/descent metrics,
+	or can we think of something better?
+	Ditto ''line-fit-edge/leading'' and the name of the property itself.
+
+	Unless 'line-fit-edge' is ''line-fit-edge/leading''--
 	in which case the box’s own 'line-height' is used to add spacing--
 	the box’s margin, padding, and border also contribute
 	to the [=layout bounds=].
 
-	Note: Although only ''text-box-edge/leading'' applies positive [=half-leading=],
-	in order to allow text to be set tightly,
-	all values apply negative [=half-leading=],
-	see [[#inline-height]].
-	Half-leading is applied equally to both sides of the text;
-	for more precise overlap control authors can use
-	''text-box-edge: text'' together with negative [=margins=]
-	on the affected text.
+	Note: The ''line-fit-edge/leading'' and ''line-fit-edge/text'' values
+	rely on the font [=ascent=] and [=descent=] to make sure the text fits.
+	Other values are more likely to result in overlap or overflow
+	caused by ascents above the specified metrics
+	(such as for diacritics),
+	so authors using these values need to be careful
+	to provide sufficient spacing for the text,
+	particularly in multi-lingual contexts.
 
 	<figure>
 		<img src="images/text-edge.png" width="480"
 		     alt="Three different values of the text-box-edge property."  >
 		<figcaption>
-			The 'text-box-edge' property, showing values for ''text-box-edge/leading'',
-			''text-box-edge/cap'', and ''text-box-edge/ex''.
+			The 'line-fit-edge' property, showing values for ''line-fit-edge/leading'',
+			''line-fit-edge/cap'', and ''line-fit-edge/ex''.
 			The red lines indicate the layout bounds of the inline box.
 		</figcaption>
 	</figure>
 
 	<div class="note">
-	<p>When 'text-box-edge' is ''text-box-edge/leading'',
+	<p>When 'line-fit-edge' is ''line-fit-edge/leading'',
 	vertical rhythm can be broken any time there is a change
 	in font metrics or vertical alignment within a paragraph.
 
@@ -1162,21 +1164,30 @@ Inline Box Edge Metrics: the 'text-box-edge' property</h3>
 	to avoid overlap between lines.
 	</div>
 
+	Note: Although only ''line-fit-edge/leading'' applies positive [=half-leading=],
+	in order to allow text to be set tightly,
+	all values apply negative [=half-leading=],
+	see [[#inline-height]].
+	Half-leading is applied equally to both sides of the text;
+	for more precise overlap control authors can use
+	''line-fit-edge: text'' together with negative [=margins=]
+	on the affected text.
+
 <h3 id="inline-height">
 Calculating the Logical Height Contributions (“Layout Bounds”) of Inline Boxes</h3>
 
 	The contribution of an [=inline box=] to the [=logical height=] of its [=line box=],
 	here referred to as its <dfn>layout bounds</dfn>,
 	is always calculated with respect to its own text metrics,
 	as described below,
-	and is controlled by 'text-box-edge' and 'line-height'.
+	and is controlled by 'line-fit-edge' and 'line-height'.
 	The sizes and positions of child boxes do not influence
 	its [=layout bounds=]
 	(nor its own [=logical height=], for that matter,
 	see 'inline-sizing').
 
 	Note: The [=layout bounds=] need not correspond
-	to the box’s edges.
+	to the box’s [=box/edges=].
 
 	To find the [=layout bounds=] of an [=inline box=],
 	the UA must first align
@@ -1191,13 +1202,13 @@ Calculating the Logical Height Contributions (“Layout Bounds”) of Inline Box
 	For each glyph (including the “strut”),
 	<var>A</var> represents its ascent above the [=baseline=];
 	<var>D</var> represents its descent below.
-	Unless 'text-box-edge' specifies a different metric to use,
+	Unless 'line-fit-edge' specifies a different metric to use,
 	<var>A</var> refers to the [=ascent metric=]
 	(for the given font at its given size)
 	and <var>D</var> to the [=descent metric=],
 	each adjusted to account for the [=dominant baseline=]’s offset from zero.
 	If 'line-height' computes to ''line-height/normal''
-	and either 'text-box-edge' is ''text-box-edge/leading''
+	and either 'line-fit-edge' is ''line-fit-edge/leading''
 	or this is the [=root inline box=],
 	the font’s [=line gap metric=]
 	may also be incorporated into <var>A</var> and <var>D</var>
@@ -1225,7 +1236,7 @@ Calculating the Logical Height Contributions (“Layout Bounds”) of Inline Box
 	giving an effective ascent above the baseline of
 	<var>A′</var> = <var>A</var> + <var>L</var>/2,
 	and an effective descent of <var>D′</var> = <var>D</var> + <var>L</var>/2.
-	However, if 'text-box-edge' is not ''text-box-edge/leading''
+	However, if 'line-fit-edge' is not ''text-box-edge/leading''
 	and this is not the [=root inline box=],
 	if the [=half-leading=] is positive, treat it as zero.
 	The [=layout bounds=] exactly encloses
@@ -1234,23 +1245,32 @@ Calculating the Logical Height Contributions (“Layout Bounds”) of Inline Box
 	Note: <var>L</var> may be negative.
 
 	Additionally,
-	when 'text-box-edge' is not ''text-box-edge/leading'',
+	when 'line-fit-edge' is not ''line-fit-edge/leading'',
 	the [=layout bounds=] are inflated
 	by the sum of the [=margin=], [=border=], and [=padding=]
 	on each side.
 	In order to allow negative [=margin=] values to have an actual effect,
 	negative [=margins=] are also accumulated onto
-	the layout bounds of any descendant [=inline boxes=]
+	the [=layout bounds=] of any descendant [=inline boxes=]
 	participating in the same [=inline formatting context=].
 
 	In Quirks Mode [[!QUIRKS]],
 	any [=inline box=] [=box fragment|fragment=]
 	that has zero borders and padding and
 	that does not directly contain text or <a>preserved white space</a> [[!CSS-TEXT-3]]
-	is ignored when sizing the line box.
+	is ignored when sizing the [=line box=].
 
-<h3 id="leading-trim">
-Half-Leading Control: the 'text-box-trim' property</h3>
+<h2 id="leading-trim">
+Trimming Leading Over/Under Text</h2>
+
+	ISSUE: This is a draft of a proposal,
+	and may change significantly
+	as design critiques and use cases are registered.
+	Values and property names may be added, dropped, and/or renamed,
+	and the overall syntax or behavior may change,
+	particularly in response to authoring and robustness considerations
+	for handling descendant boxes.
+	<strong>Do not ship (yet).</strong>
 
 	To ensure consistent spacing in the basic case of running text,
 	CSS line layout introduces leading both above and below
@@ -1264,13 +1284,13 @@ Half-Leading Control: the 'text-box-trim' property</h3>
 	However, all this extra spacing interferes with visual alignment
 	and with control over effective (visually-apparent) spacing.
 
-	The 'text-box-trim' property allows trimming
+	The 'text-box' property allows trimming
 	this additional space above and below
 	the first and last lines of a block,
 	allowing more precise control over spacing around the glyphs.
-	Moreover, by relying on font metrics rather than hard-coded lengths,
-	it allows content to be resized, rewrapped, and rendered in a variety of fonts
-	while maintaining that spacing.
+	By relying on font metrics rather than hard-coded lengths,
+	this feature allows content to be resized, rewrapped, and rendered in a variety of fonts
+	while maintaining that precise spacing.
 
 	<div class="example">
 		<!-- Example from Weston Thayer in https://github.com/w3c/csswg-drafts/issues/3240#issuecomment-432375650 -->
@@ -1332,6 +1352,42 @@ Half-Leading Control: the 'text-box-trim' property</h3>
 		</figure>
 	</div>
 
+<h3 id="text-box-shorthand">
+Shorthand for Text Box Trimming: the 'text-box' property</h3>
+
+	ISSUE: This propdef table is fully expanded to evaluate and adjust the shorthand's value space.
+	It simplifies down to <<text-box-trim>> || <<text-box-edge>>
+	minus the ''text-box-trim/none'' and ''text-box-edge/auto'' keywords.
+
+	<pre class="propdef">
+	Name: text-box
+	Value: normal | [ start | end | both ] || [ text | cap | ex | ideographic | ideographic-ink ] [ text | alphabetic | ideographic | ideographic-ink ]?
+	Initial: normal
+	Applies to: [=block containers=] and [=inline boxes=]
+	Inherited: no
+	Percentages: N/A
+	Computed value: the specified keyword
+	Animation type: discrete
+	</pre>
+
+	This property is a [=shorthand=] for setting the 'text-box-trim' and 'text-box-edge' properties
+	in a single declaration.
+
+	If the single keyword ''text-box-edge/normal'' is specified,
+	it sets 'text-box-trim' to ''text-box-trim/none''
+	and 'text-box-edge' to ''text-box-edge/auto''.
+	Otherwise, omitting the 'text-box-trim' value sets it to ''text-box-trim/both'' (not the initial value),
+	while omitting the 'text-box-edge' value sets it to ''text-box-edge/auto'' (the initial value).
+
+	ISSUE(8067): We should rename the 'text-box-trim' values to add ''trim-*'' prefixes.
+	This would make the shorthand clearer,
+	and also make its value space consistent with 'text-spacing'.
+
+	ISSUE: Add examples.
+
+<h3 id="text-box-trim">
+Trimming Over/Under Text: the 'text-box-trim' property</h3>
+
 	<pre class="propdef">
 	Name: text-box-trim
 	Value: none | start | end | both
@@ -1343,15 +1399,6 @@ Half-Leading Control: the 'text-box-trim' property</h3>
 	Animation type: discrete
 	</pre>
 
-	ISSUE: This is an early draft of a proposal,
-	and is likely to change significantly
-	as design critiques and use cases are registered.
-	Values and property names may be added, dropped, and/or renamed,
-	and the overall syntax or behavior may change,
-	particularly in response to authoring and robustness considerations
-	for handling descendant boxes.
-	<strong>Do not implement (yet).</strong>
-
 	On [=inline boxes=],
 	specifies whether to trim the [=content box=]
 	to match its corresponding 'text-box-edge' metric.
@@ -1365,12 +1412,6 @@ Half-Leading Control: the 'text-box-trim' property</h3>
 	to the corresponding 'text-box-edge' metric
 	to better match the box’s [=content edge=] to its text content.
 
-	Note: Content and ink overflowing a box
-	due to non-initial values of 'text-box-trim'
-	is handled the same as content that would overflow the box or line box otherwise.
-
-	This property has no effect when 'text-box-edge' is ''text-box-edge/leading''.
-
 	Values have the following meanings:
 
 	<dl dfn-for=text-box-trim dfn-type=value>
@@ -1422,6 +1463,36 @@ Half-Leading Control: the 'text-box-trim' property</h3>
 	Note: The [=block-end=] side does not coincide with the [=line-under=] side
 	when 'writing-mode' is ''vertical-lr''.
 
+	Note: Content and ink overflowing a box
+	due to non-initial values of 'text-box-trim'
+	is handled the same as content that would overflow the box or line box otherwise.
+
+<h3 id="text-box-trim">
+Text Trimming Metrics: the 'text-box-edge' property</h3>
+
+	<pre class="propdef">
+	Name: text-box-edge
+	Value: auto | <<text-edge>>
+	Initial: auto
+	Applies to: [=block containers=] and [=inline boxes=]
+	Inherited: no
+	Percentages: N/A
+	Computed value: the specified keyword
+	Animation type: discrete
+	</pre>
+
+	This property specifies the metrics to use for 'text-box-trim' effects.
+	Values have the same meanings as for 'line-fit-edge';
+	the <dfn for=text-box-edge type=value>auto</dfn> keyword
+	computes to the value of 'line-fit-edge',
+	interpreting ''line-fit-edge/leading'' (the [=initial value=]) as ''line-fit-edge/text''.
+
+	Note: This property can be set together with 'text-box-trim'
+	in the 'text-box' [=shorthand=].
+	Unlike 'line-fit-edge', it does not inherit;
+	however its [=initial value=] copies from 'line-fit-edge',
+	which does inherit.
+
 <h3 id="line-fill">
 Inline Box Drawing Height: the 'inline-sizing' property</h3>
 
@@ -1437,6 +1508,7 @@ Inline Box Drawing Height: the 'inline-sizing' property</h3>
 	</pre>
 
 	ISSUE(5189): This has a confusing name. We need a new name.
+	Alternatively, incorporate this into 'text-box-trim'?
 
 	This property specifies how the <a>logical height</a>
 	of the <a>content area</a> of an <a>inline box</a>
@@ -2982,6 +3054,11 @@ Changes</h2>
 	Changes since the
 	<a href="https://www.w3.org/TR/2023/WD-css-inline-3-20230401/">1 April 2023 Working Draft</a>:
 	<ul>
+		<li>Split 'text-box-edge' into two properties:
+			'text-box-edge' for controlling the 'text-box-trim' edge
+			and 'line-fit-edge' for controlling line box sizing.
+			(Issues <a href="https://github.com/w3c/csswg-drafts/issues/8829">8829</a>
+			and <a href="https://github.com/w3c/csswg-drafts/issues/8696">8696</a>)
 		<li>Apply negative [=block-axis=] margins to descendants of [=inline boxes=]
 			when calculating their [=layout bounds=]
 			so that they can actually have the specified effect.
