[css-text-4][css-inline-3][css-text-decor-4] Introduce text-fit property (#13616)

* Initial commit for 'text-fit' property

* Separate a paragraph into two, etc.

* 'see below'

Author: tkent-google

css-inline-3/Overview.bs

@@ -952,7 +952,7 @@ Line Spacing: the 'line-height' property</h3>
 	Initial: normal
 	Applies to: non-replaced inline boxes and SVG <a>text content elements</a>
 	Inherited: yes
-	Percentages: computed relative to ''1em''
+	Percentages: see below
 	Computed value: the specified keyword, a number, or a computed <<length>> value
 	Animation type: by computed value type
 	</pre>
@@ -973,7 +973,7 @@ Line Spacing: the 'line-height' property</h3>
 		<dt><dfn>normal</dfn>
 		<dd>
 			Determine the [=preferred line height=]
-			automatically based on font metrics.
+			automatically based on the metrics of the used font.
 
 		<dt><dfn><<length [0,∞]>></dfn>
 		<dd>
@@ -983,14 +983,15 @@ Line Spacing: the 'line-height' property</h3>
 		<dt><dfn><<number [0,∞]>></dfn>
 		<dd>
 			The [=preferred line height=] is this number
-			multiplied by the element's computed 'font-size'.
+			multiplied by the element's used 'font-size'.
 			Negative values are illegal.
 			The [=computed value=] is the same as the [=specified value=].
 
 		<dt><dfn><<percentage [0,∞]>></dfn>
 		<dd>
 			The [=preferred line height=]
-			and [=computed value=] of the property
+			is this percentage of the element's used 'font-size'.
+			The [=computed value=] of the property
 			is this percentage of the element's computed 'font-size'.
 			Negative values are illegal.
 	</dl>

css-text-4/Overview.bs

@@ -9737,6 +9737,174 @@ Aligning a block of text within its container: the 'text-group-align' property</
 			</wpt>
 	</dl>
 
+<h3 id="text-fit-property">
+Text fitting: the 'text-fit' property</h3>
+
+	<wpt title="
+		This section has no coverage yet.
+	"></wpt>
+
+	<pre class="propdef">
+	Name: text-fit
+	Value: [ none | grow | shrink ] [consistent | per-line | per-line-all]? <<percentage>>?
+	Initial: none
+	Applies to: <a>block containers</a>
+	Inherited: no
+	Percentages: N/A
+	Computed value: specified keywords or computed <<percentage>> value
+	Canonical order: per grammar
+	Animation type: discrete
+	</pre>
+
+	<p>The 'text-fit' property describes how [=inline-level=] contents are
+	scaled if they do not fit to the [=line box=].
+
+	<p>Values have the following meanings:
+
+	<dl dfn-for=text-fit dfn-type=value>
+		<dt><dfn>none</dfn>
+		<dd>
+		    The user agent doesn't scale [=inline-level=] contents to fit to
+			the [=line box=].
+		</dd>
+
+		<dt><dfn>grow</dfn>
+		<dd>
+		    The user agent scales up [=inline-level=] contents to fit to the
+			[=line box=].
+		</dd>
+
+		<dt><dfn>shrink</dfn>
+		<dd>
+		    The user agent scales down [=inline-level=] contents to fit to the
+			[=line box=].
+		</dd>
+
+		<dt><dfn>consistent</dfn>
+		<dd>
+		    Specifies that all lines in the container are scaled with a single
+			scaling factor.
+			This keyword has no effect if ''text-fit/none'' is specified.
+			If none of ''text-fit/consistent'', ''text-fit/per-line'', or
+			''text-fit/per-line-all'' are specified, ''text-fit/consistent'' is
+			assumed.
+		</dd>
+
+		<dt><dfn>per-line</dfn>
+		<dd>
+		    Specifies that each line is scaled with its own scaling factor.
+			However, the last line of the block and lines that end in a forced
+			break are not scaled.
+			This keyword has no effect if ''text-fit/none'' is specified.
+		</dd>
+
+		<dt><dfn>per-line-all</dfn>
+		<dd>
+		    Specifies that each line is scaled with its own scaling factor,
+			including the last line of the block and lines that end in a forced
+			break.
+			This keyword has no effect if ''text-fit/none'' is specified.
+		</dd>
+
+		<dt><dfn>&lt;percentage&gt;</dfn>
+		<dd>
+		    Specifies the limit of the scaling factor.
+		    If ''text-fit/grow'' is specified and the value is 100% or greater,
+			it is the maximum scaling factor.
+		    If ''text-fit/shrink'' is specified and the value is between 0% and
+			100% inclusive, it is the minimum scaling factor.
+		    Otherwise, or if this component is omitted, there is no limit on
+			the scaling factor.
+		</dd>
+	</dl>
+
+	<p>This property provides a functionality to make [=inline-level=] contents
+	exactly fill the inline size of the [=line box=].
+	Unlike ''text-align/justify'' of the 'text-align' property, which achieves
+	this by adjusting spacing between characters, this property scales the
+	font size.
+
+	<p>When ''text-fit/grow'' or ''text-fit/shrink'' is specified,
+	a [=line scaling factor=] is computed for each [=line box=].
+	If ''text-fit/consistent'' applies, all [=line boxes=] are scaled by the
+	smallest computed [=line scaling factor=].
+	Otherwise, each [=line box=] is scaled by its own [=line scaling factor=].
+
+	<p>This property does not affect the 'font-size' [=computed value=],
+	and thus does not affect font-size-relative <<length>> values of other properties.
+	For example, "line-height: 1.5em" and "letter-spacing: 0.1em" are not
+	affected by this scaling.
+
+	<p>The [=used value=] of the text 'font-size' is its [=computed value=]
+	multiplied by the [=line scaling factor=].
+
+	<p>Scaling can change the [=block size=] of a [=line box=],
+	which can in turn change its position along the [=block-axis=].
+	If any feature is active that would cause the [=inline size=] of the
+	[=line box=] to change based on its [=block-axis=] position	(such as
+	'float' or 'initial-letter'), scaling is disabled for the block.
+
+	<div class="issue">
+		If the [=inline size=] of a block container depends on the size of
+		the viewport, its apparent [=inline size=] may not change even if
+		the user changes the page zoom level.
+		In that case, if text is fitted with this feature, the text size may
+		not change at all even though the zoom level has changed.
+		There is no agreement yet on how to deal with this issue. See
+		<a href="https://github.com/w3c/csswg-drafts/issues/12886">csswg#12886</a>.
+	</div>
+
+	<h4 id="text-fit-scaling-factor">Computing line scaling factor</h4>
+
+	<p>The parts of the [=line box=]'s contents that can be scaled by this
+	property are called <dfn>scalable parts</dfn>.
+	These include:
+
+	<ul>
+		<li>
+			Text, including text in [=inline boxes=], but excluding trailing
+			white space.
+
+		<li>
+			Spacing whose [=inline size=] is proportional to the 'font-size'
+			used value.
+			E.g. percentage-based 'letter-spacing' or 'word-spacing', and 'text-autospace'.
+	</ul>
+
+	<p class="note">
+	'text-indent', 'line-padding', non-percentage-based 'letter-spacing' and
+	'word-spacing',	and [=atomic inlines=] are not [=scalable parts=].
+	The [=inline-axis=] 'padding', 'border', and 'margin' of inline boxes are
+	also not [=scalable parts=].
+
+	<p>A <dfn>line scaling factor</dfn> is the ratio by which the
+	[=scalable parts=] of a line must be scaled in order to make its
+	[=inline-level=] content exactly fit the [=line box=]’s [=inline size=].
+
+	<p>A [=line scaling factor=] is computed from:
+
+	<ul>
+		<li>The total [=inline size=] of the [=scalable parts=] in the line.
+		<li>
+			The remaining space in the [=line box=], including any trailing whitespace
+			(which may be negative if the content overflows the [=line box=]).
+	</ul>
+
+	<p>If a <<percentage>> is specified, it clamps the [=line scaling factor=].
+
+	<p class="note">
+	A simple calculation for the [=line scaling factor=] would be
+	<code>(A + B) / A</code>, where A is the total [=inline size=] of
+	[=scalable parts=] and B is the remaining space.
+	However, due to [[css-fonts-4#font-optical-sizing-def|optical sizing]], the
+	[=inline size=] of text might not be perfectly proportional to its
+	'font-size'.
+	The exact method for determining a reasonable [=line scaling factor=]
+	is up to the implementation.
+
+	<p>The [=line scaling factor=] for a [=line box=] with no
+	[=scalable parts=] is 1.
+
 
 <h2 id="spacing">
 Spacing</h2>
@@ -9779,7 +9947,7 @@ Word Spacing: the 'word-spacing' property</h3>
 	Initial: normal
 	Applies to: text
 	Inherited: yes
-	Percentages: relative to computed 'font-size', i.e. ''1em''
+	Percentages: relative to used 'font-size'
 	Computed value: an absolute length and/or a percentage
 	Animation type: by computed value type
 	Canonical order: n/a
@@ -9977,7 +10145,7 @@ Tracking: the 'letter-spacing' property</h3>
 	Initial: normal
 	Applies to: <a>inline boxes</a> and text
 	Inherited: yes
-	Percentages: relative to computed 'font-size', i.e. ''1em''
+	Percentages: relative to used 'font-size'
 	Computed value: an absolute length and/or a percentage
 	Animation type: by computed value type
 	Canonical order: n/a
@@ -10624,7 +10792,7 @@ Inter-script Spacing</h4>
 	i.e. without any intervening non-zero [=margin=], [=border=], or [=padding=]
 	or intervening characters (such as a quotation mark or a space).
 	The amount of space introduced by these keywords is 1/8 of the CJK advance measure,
-	i.e ''0.125ic''.
+	i.e ''0.125ic'' if the [=used value=] of 'font-size' is same as its [=computed value=].
 
 	Note: Spacing conventions vary, but values typically range from 1/4ic to as low as 1/8ic,
 	with 1/4ic being more common in historical contexts due to metal type limitations
@@ -12133,6 +12301,13 @@ Text Processing Order of Operations</h2>
 			* 'letter-spacing', 'word-spacing', 'text-spacing', and 'line-padding'
 			* [[#hanging-punctuation-property|hanging punctuation]]
 
+		<li>
+			[[#text-fit-property|text fitting]]
+
+			* <a href="https://www.w3.org/TR/css-fonts-3/">font/glyph selection
+				and positioning</a> [[!CSS-FONTS-3]] may be done again
+			* 'letter-spacing', 'word-spacing', and 'text-spacing' may be updated.
+
 		<li>
 			[[#justification|justification]]
 			(which may affect glyph selection and/or text wrapping, looping back into that step)
@@ -13303,7 +13478,7 @@ Changes</h2>
 	Changes specific to Level 4 are listed below.
 
 	Significant changes since the <a href="https://www.w3.org/TR/2024/WD-css-text-4-2024052">29 May 2024 Working Draft</a> include:
-	* None yet.
+	* Add 'text-fit' property.
 
 	Significant changes since the <a href="https://www.w3.org/TR/2024/WD-css-text-4-20240219/">19 February 2024 Working Draft</a> include:
 	* Renamed the 'text-spacing-trim' value <css>trim-auto</css> to ''trim-both''.

css-text-decor-4/Overview.bs

@@ -366,7 +366,8 @@ Text Decoration Line Thickness: the 'text-decoration-thickness' property</h3>
 			Note: A length will inherit as a fixed value,
 			and will not scale with the font.
 
-			A percentage value specifies the thickness of text decoration lines as a percentage of ''1em''.
+			A percentage value specifies the thickness of text decoration lines as a percentage of
+			the used 'font-size'.
 
 			Note: A percentage will inherit as a relative value,
 			and will therefore scale with changes in the font as it inherits.
@@ -707,7 +708,8 @@ Text Underline Offset: the 'text-underline-offset' property</h3>
 			Note: A length will inherit as a fixed value,
 			and will not scale with the font.
 
-			A percentage value specifies the offset of underlines as a percentage of ''1em''.
+			A percentage value specifies the offset of underlines as a percentage of the used
+			'font-size'.
 
 			Note: A percentage will inherit as a relative value,
 			and will therefore scale with changes in the font as it inherits.