Skip to content

Commit

Permalink
[css-text-4] split text-wrap mode into sub-properties
Browse files Browse the repository at this point in the history 
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 #9102
  • Loading branch information
@frivoal
frivoal committed Aug 30, 2023
1 parent 9ef4e25 commit 3a1eb85
Showing 1 changed file with 127 additions and 73 deletions.
200 changes: 127 additions & 73 deletions css-text-4/Overview.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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>
Expand All @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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,
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 3a1eb85

Please sign in to comment.