Technical / editorial: Document the text-box-* properties #37738
Conversation
chrisdavidmills
requested review from
estelle and
hamishwillee
and removed request for
a team
github-actions
bot
added
Content:CSS
chrisdavidmills
changed the title
Preview URLs (7 pages)Flaws (69)URL:
URL:
URL:
URL:
URL:
URL:
URL:
External URLs (7)URL:
URL:
URL:
URL:
URL:
(comment last updated: 2025-02-25 13:36:32) |
|
I'm removing myself from review as "nowhere near as good as @estelle at evaluating CSS PRs". If you want to add me back for bandwidth or other reasons feel free to do so. |
chrisdavidmills
changed the title
There was a problem hiding this comment.
I've gone through all the staged pages, reading them as if I was a fresh developer learning about the topic 🙂 I also did a technical pass looking for accidents or wrong information and I can't find any.
Everything looks good to me!
I'm proud to see similar demo's to those in the Chrome post as well as similar guidance. Glad to know the information we provided has resonated 🙂
|
|
||
| The **`text-box-edge`** [CSS](/en-US/docs/Web/CSS) property specifies an amount of [leading](/en-US/docs/Glossary/Leading) to trim from text content. | ||
|
|
||
| Leading differs across fonts, making consistent typesetting historically challenging on the web. `text-box-edge` — along with its counterpart property {{cssxref("text-box-trim")}}, which specifies which edge(s) to trim leading from — makes consistent typesetting easier to achieve. |
There was a problem hiding this comment.
| Leading differs across fonts, making consistent typesetting historically challenging on the web. `text-box-edge` — along with its counterpart property {{cssxref("text-box-trim")}}, which specifies which edge(s) to trim leading from — makes consistent typesetting easier to achieve. | |
| Text height differs between fonts, making consistent typesetting historically challenging on the web. The `text-box-edge` — along with its counterpart property {{cssxref("text-box-trim")}} — makes consistent typesetting easier to achieve by enabling trimming of extra spacing above or below text. With the {{cssxref("text-edge")}} properties, we can set the over and under edges for inline boxes. This enables vertically aligning text regardless of the font file's baseline. |
There was a problem hiding this comment.
I'm leaving this one until we can clear up the earlier confusion. Leading must be involved — the relevant spec section is titled Trimming Leading Over/Under Text — but after your review, I'm just confused as to exactly how (although I suspect it is removed from just the start and end of the entire text box).
Again, @argyleink, I'd love to hear your thoughts on this.
There was a problem hiding this comment.
Technically speaking, the trimming is applied to the block container, not to inline box nor to text box, using the metrics of the font of the block container. This jsbin shows how each box is modified and not modified. Does this help understanding?
|
|
||
| ## Description | ||
|
|
||
| Font files specify an amount of space — termed leading — to be included above and below text, to contain capital letters, ascenders, descenders, etc., and provide spacing between lines. The amount of leading included varies between fonts, making it difficult to consistently set block-level text spacing. |
There was a problem hiding this comment.
| Font files specify an amount of space — termed leading — to be included above and below text, to contain capital letters, ascenders, descenders, etc., and provide spacing between lines. The amount of leading included varies between fonts, making it difficult to consistently set block-level text spacing. | |
| Font files specify the space included above and below text, to contain capital letters, ascenders, descenders, etc. This in-font spacing ensures lines of text don't overlap by default. The amount of spacing included varies between fonts, making it difficult to consistently set block-level text spacing. |
There was a problem hiding this comment.
Again, I'm leaving this until we clear up the confusion.
|
|
||
| Font files specify an amount of space — termed leading — to be included above and below text, to contain capital letters, ascenders, descenders, etc., and provide spacing between lines. The amount of leading included varies between fonts, making it difficult to consistently set block-level text spacing. | ||
|
|
||
| The `text-box-edge` property allows you to trim the leading from the start and/or end edge of the text. It does this by specifying a {{cssxref("<text-edge>")}} value that indicates the over edge and under edge to trim the leading to. |
There was a problem hiding this comment.
| The `text-box-edge` property allows you to trim the leading from the start and/or end edge of the text. It does this by specifying a {{cssxref("<text-edge>")}} value that indicates the over edge and under edge to trim the leading to. | |
| The `text-box-edge` property allows you to trim the spacing from the start and/or end edge of lines of text by specifying a {{cssxref("<text-edge>")}} value that indicates the over edge and under edge to trim the inline box. |
There was a problem hiding this comment.
i think we should get rid of this "leading" since that is between lines, not within the inline box. I'll stop editing here and give you a chance to marinate / agree / disagree / get a pint / get several pints ;)
There was a problem hiding this comment.
I'm leaving this one just for now, until we clear up the confusion.
|
|
||
| ## Description | ||
|
|
||
| Font files specify an amount of space, termed leading, to be included above and below text to provide spacing between lines. The amount of leading included varies between fonts, as does the space within the font (the height of the capital letter, ascenders, descenders, etc.), making it difficult to consistently set block-level text spacing. |
There was a problem hiding this comment.
| Font files specify an amount of space, termed leading, to be included above and below text to provide spacing between lines. The amount of leading included varies between fonts, as does the space within the font (the height of the capital letter, ascenders, descenders, etc.), making it difficult to consistently set block-level text spacing. | |
| Font files specify an amount of space, or edge spacing, to be included above and below text to provide spacing between lines. The amount of edge spacing included varies between fonts, as does the space within the font (the height of the capital letter, ascenders, descenders, etc.), making it difficult to consistently set block-level text spacing. |
Likely not the right term either, but commenting so we know where/what to update.
|
|
||
| We apply a `text-box` value of `trim-end cap alphabetic` to the first one. The {{cssxref("text-box-edge")}} value of `cap alphabetic` specifies to trim the over edge to the top of the capital letters and the under edge flush with the text baseline. However, because the {{cssxref("text-box-trim")}} value is set to `trim-end`, only the under edge is trimmed. | ||
|
|
||
| We apply a `text-box` value of `trim-both ex alphabetic` to the second one. The {{cssxref("text-box-edge")}} value of `ex alphabetic` specifies to trim the over edge to the font's x-height (the top of the short lower-case letters) and the under edge flush with the text baseline. Because the {{cssxref("text-box-trim")}} value is set to `trim-both`, both the over _and_ under edge are trimmed. |
There was a problem hiding this comment.
| We apply a `text-box` value of `trim-both ex alphabetic` to the second one. The {{cssxref("text-box-edge")}} value of `ex alphabetic` specifies to trim the over edge to the font's x-height (the top of the short lower-case letters) and the under edge flush with the text baseline. Because the {{cssxref("text-box-trim")}} value is set to `trim-both`, both the over _and_ under edge are trimmed. | |
| We apply a `text-box` value of `trim-both ex alphabetic` to the second paragraph. The {{cssxref("text-box-edge")}} value of `ex alphabetic` specifies trimming the over edge to the font's x-height (the top edge of short lower-case letters) and the under edge flush with the text baseline. Because the {{cssxref("text-box-trim")}} value is set to `trim-both`, both the over _and_ under edge are trimmed. |
There was a problem hiding this comment.
I applied this one, but made a couple of tweaks.
|
|
||
| The **`<text-edge>`** {{glossary("enumerated")}} [data type](/en-US/docs/Web/CSS/CSS_Types) defines keywords that specify font metrics representing specific regions on a font's block-start edge and block-end edge that are to be manipulated in some way. It effectively does this by specifying a position for the font's over and/or under edge. | ||
|
|
||
| The `text-edge` values are used in the {{cssxref("text-box-edge")}} property to define regions of spacing to trim from the block-start edge and block-end edge of specified text content. |
There was a problem hiding this comment.
| The `text-edge` values are used in the {{cssxref("text-box-edge")}} property to define regions of spacing to trim from the block-start edge and block-end edge of specified text content. | |
| The `<text-edge>` key terms are values of the {{cssxref("text-box-edge")}} property used to specify trim definitions from the block-start edge and block-end edge of text content. |
There was a problem hiding this comment.
I didn't like this suggestion very much. It is technically correct, but I think it will be significantly harder for readers to understand. I have elected to echo the definition from the text-box-edge page, and keep it really simple:
The
<text-edge>values are used in the {{cssxref("text-box-edge")}} property to specify an amount of space to trim from text content.
Co-authored-by: Estelle Weyl <[email protected]>
Co-authored-by: Estelle Weyl <[email protected]>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Co-authored-by: Estelle Weyl <[email protected]>
Co-authored-by: Estelle Weyl <[email protected]>
Co-authored-by: Estelle Weyl <[email protected]>
Co-authored-by: Estelle Weyl <[email protected]>
Co-authored-by: Estelle Weyl <[email protected]>
Co-authored-by: Estelle Weyl <[email protected]>
Co-authored-by: Estelle Weyl <[email protected]>
Co-authored-by: Estelle Weyl <[email protected]>
Co-authored-by: Estelle Weyl <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
| - : One or two separate keywords representing over and under edge positions to trim the font leading to. | ||
| - If two values are specified, the first value specifies the trimming behavior to apply to the block-start (over) edge of the text, and the second value specifies the trimming behavior to apply to the block-end (under) edge of the text. | ||
| - Valid over edge trimming values: `text` (the default), `cap`, and `ex`. | ||
| - Valid under edge trimming values: `text` (the default) and `alphabetic`. |
There was a problem hiding this comment.
Can you please remove "(the default)"? There are no longer a "default" value, please see w3c/csswg-drafts#10703.
There was a problem hiding this comment.
I've removed both instances of "(the default)" in my next commit, but ... there must be a default if the property is not explicitly set. I did some testing and saw that, in the latest Chrome implementation:
- just setting a single value of
cap,ex, oralphabeticis flagged as invalid by the devtools, so my current text is correct. - the computed value when
text-box-edgeis not set on an element isauto. So I've added a line to theautodefinition on the page saying "This is the default value."
Does that work for you?
There was a problem hiding this comment.
there must be a default if the property is not explicitly set
Oh I see, do you mean the "initial"? In the CSS terminologies, the "default" is a bit ambiguous, and I thought you meant it for a default value when only one value is used. Does "initial" work for you? I understand "default" may sound more familiar though.
There was a problem hiding this comment.
Yup, that's how we tend to refer to the initial value set by the browser stylesheet. "initial" is a bit more correct as per official CSS terminology, but "default" is a bit easier to understand. Plus it makes the use of "default" more consistent with how we talk about default values in JS and WebAPI ref docs.
At least, that's what I've been doing. @estelle, what are your thoughts on this?
| The `text-box-edge` property value is specified as `auto` or a {{cssxref("<text-edge>")}} value: | ||
|
|
||
| - `auto` | ||
| - : Equivalent to the `text-edge` value `text`. |
There was a problem hiding this comment.
I think this is intentional, but just wanted to double check. The auto is equivalent to text only if the browser hasn't implemented the line-fit-edge property. Wondering if this is nice to mention, or is this unnecessary complexity?
There was a problem hiding this comment.
I think we should leave this as-is for now, as it describes the current implementation. We should try to avoid complicating the description if we can.
When browsers start to implement line-fit-edge, we should revisit the description then.
Of course, if some browsers support it and others don't, we'll have to fork the description.
What is the behavior if line-fit-edge is implemented?
There was a problem hiding this comment.
sgtm, thanks for the confirmation.
What is the behavior if
line-fit-edgeis implemented?
the
autokeyword uses the value ofline-fit-edge, interpretingleading(the initial value) astext.
There was a problem hiding this comment.
Thanks, that makes sense. Yeah, we'll update this when line-fit-edge is implemented.
|
|
||
| ### Values | ||
|
|
||
| The `text-box` value can be composed of a {{cssxref("text-box-trim")}} value followed by a {{cssxref("text-box-edge")}} value. See those pages for value descriptions. |
There was a problem hiding this comment.
Whichever property can come first, as the syntax uses the || operator. The relevant wpt tests are here.
I suppose you have a default way to describe the || operator. Is that "followed by"?
There was a problem hiding this comment.
Nope, if they can be in either order, "followed by" is not accurate. I'm glad you flagged this. I've updated it to:
The
text-boxvalue can be composed of a {{cssxref("text-box-trim")}} value and a {{cssxref("text-box-edge")}} value separated by a space. See those pages for value descriptions.
|
|
||
| The `text-box` property can also take a keyword of `normal`, which is equivalent to `text-box: none auto;` | ||
|
|
||
| If `text-box-trim` is omitted, it is set to `both`. If `text-box-edge` is omitted, it is set to `auto`. |
There was a problem hiding this comment.
Good catch, thank you.
| - `ex` | ||
| - : The font's over edge is its x-height baseline, which is the top of its short lower-case letters. | ||
| - `text` | ||
| - : The font's over or under edge is its start and end boundaries. This can be considered the default, as this is where the boundaries are normally without any manipulation. |
There was a problem hiding this comment.
This is a tough one, "start and end boundaries" look a bit ambiguous to me. I wonder if there are better ways to describe this. How about adding "for text runs, this means font's ascent and descent, without half-leading"? Please disregard if this could make it even more confusing...
There was a problem hiding this comment.
I think this is a useful detail to include, as you are right, the existing definition is a bit ambiguous/vague. I've changed the first description of text in the "Single keyword values" section to:
The font's over and under edges are its start and end boundaries, which include the font's ascenders and descenders, but exclude the half-leading set on the text. This can be considered the default, as this is where the boundaries are normally without any manipulation.
I've then changed the second definition of text in the "Two keyword values" section to:
The font's over edge is its start boundary, or its under edge is its end boundary, depending on which edge the value is set for. This can be considered the default, as this is where the boundaries are normally without any manipulation.
I didn't think I needed to add the detail twice.
Does that sound accurate to you?
There was a problem hiding this comment.
@kojiishi This also gets me on to the overriding question about this PR — how do the text-box-* values affect the leading/half-leading? Is the half-leading stripped from the top and bottom of the text box only? Is it not affected at all? Is it only affected when certain values are set? @estelle and I have been confused by this throughout this work, as evidenced by comments like these:
- Technical / editorial: Document the text-box-* properties #37738 (comment)
- Technical / editorial: Document the text-box-* properties #37738 (comment)
- Technical / editorial: Document the text-box-* properties #37738 (comment)
Your comment above implies that it isn't affected at all...but we are not sure. Can you clear up this confusion for us?
Thanks 😄
There was a problem hiding this comment.
Yeah, this part is a bit complicated and confusing. I replied to the first comment above, but technically speaking, the trimming is applied to the block container, not to inline box nor to text box, using the metrics of the font of the block container. This jsbin shows the block container is trimmed, but there are no changes to inline boxes. You can also see in the example, when trimming the block container, only the font of the block container is used, ignoring descendant inline boxes such as <big>.
When text-box-trim is enabled to trim edges , it computes how much it trims the block container. The half-leading is always excluded from the trimming point (i.e., no values of text-box-edge include the half-leading). Other text-box-edge values than text allow authors to move the trimming point further inside the font metrics. This means that, for your question, the half-leading is stripped from the trimming point, but not from inline boxes nor from text boxes.
Another property currently under early discussions, line-fit-edge is supposed to do similar trimming to inline boxes and text boxes. I guess that may make reading the spec a bit more complicated, sorry about that.
There was a problem hiding this comment.
OK, so the trimming is applied to the block-start and/or block-end edge of the text's block container. That makes sense.
Then we come to the effects of the different values. So, if I understand it correctly, setting text-box-trim to non-none values serves to trim the half-leading from the block container, even if no text-box-edge value is set? And it also follows that text-box-edge: text will trim the half-leading, and values like cap/ex/alphabetic will trim the leading plus some of the inner font space?
I've done a bit of testing, and this seems to make sense, although you don't seem to see an effect with just text-box-trim in the examples I've written. To see an effect, you need to include a child element with a bigger font-size set, like in your example?
This explanation has already really helped my understanding, thank you! I will start to make some updates while I wait for clarification/confirmation.
There was a problem hiding this comment.
I'm sorry, @kojiishi. Can you please confirm that my understanding of what these properties are doing is correct, as written in the above comment?
Also, can have a quick look at the text-edge reference page and check whether I've got the value descriptions correct: https://pr37738.content.dev.mdn.mozit.cloud/en-US/docs/Web/CSS/text-edge?
Many thanks.
There was a problem hiding this comment.
So, if I understand it correctly, setting text-box-trim to non-none values serves to trim the half-leading from the block container, even if no text-box-edge value is set?
Yes, because the text-box-edge is set to its initial value, text. You can consider text-box-trim controls on/off of the trimming, and the trimming point is set to exclude half-leading by default.
And it also follows that text-box-edge: text will trim the half-leading, and values like cap/ex/alphabetic will trim the leading plus some of the inner font space?
Yes.
Is the half-leading within the line-box or the text-box? Can you clarify this too?
As far as I understand, the term "text-box" isn't clearly defined in the CSS spec. I assume you mean a layout-time object that corresponds to a Text node? The bounding of such box isn't clearly defined, as getClientRects() is only for Element, and that geometry of a Text node isn't measurable. I remember someone at CSSWG tried to name it a "text run", but I don't know if that was resolved. In my mind, such box doesn't include half-leading, but as far as I understand, it's not well-defined nor measurable.
The half-leading is included in "inline box", as the CSS 2 spec 10.8.1. Leading and half-leading says:
The height of the inline box encloses all glyphs and their half-leading on each side and is thus exactly line-height.
Also note that the term "line box" is a bit ambiguous. Some people use it to refer "inline box" (such as <span>), some to refer "root line box" (the object that represents a line). I'm not sure which you meant, but both includes the half-leading.
There was a problem hiding this comment.
Another jsbin example that may help you to understand how this property works. As you can see in this example, this property determines the trimming point not from the actual line, but only from a virtual line that has text of the font of the block container (i.e., a line produced by <div>text</div>). I'll defer what's the best way to explain this to you as you're the expert of that part.
There was a problem hiding this comment.
Thanks for all the further clarifications, @kojiishi! I've made a few adjustments, which will be in my next commit, but I'm fairly happy with the text now. I'm unsure how much it is worth digging into exactly where the half-leading is included, as it could start to make the docs confusing for many readers. We could maybe say some more about it on the leading glossary page.
What do you think @estelle? I think we are just about ready to wrap this one up now.
| @@ -29,7 +29,7 @@ The `<text-edge>` data type is composed of one or two keywords representing spec | |||
| ### Single keyword values | |||
|
|
|||
| - `text` | |||
| - : The font's over and under edges are its start and end boundaries. This can be considered the default, as this is where the boundaries are normally without any manipulation. | |||
| - : The font's over and under edges are its start and end boundaries, which include the font's ascenders and decenders but exclude the half-leading set on the text. This can be considered the default, as this is where the boundaries are normally without any manipulation. | |||
There was a problem hiding this comment.
My understanding is that half-leading is set by line-height, and not a font feature.
There was a problem hiding this comment.
True, but I think this text is good, clarifying what's included and what's not in the "start and end boundaries" is very helpful. If you worry about "exclude" may indicate that it's included in font features, maybe "without including" is more accurate?
There was a problem hiding this comment.
I think the current text is OK in that regard, but I have added a note to say that the half-leading is controlled by line-height, just so that is clear.
estelle
changed the title
estelle
changed the title
estelle
changed the title
There was a problem hiding this comment.
If the value is set to auto, the value of line-fit-edge is used. The values for line-fit-edge (not yet implemented) is leading | <text-edge>. As leading is not a supported value for text-box-edge, and leading is the default value for the line-fit-edge, when the value is set to auto, text is used. So, text will always be used if auto is set until line-fit-edge is implemented and set to a value other than text (or leading). When set to auto, the text-over baseline/text-under baseline as the over/under edge is used.
I think this use of the term "leading" as the value has been confusing us. The definition in the spec is "Use the text-over baseline/text-under baseline as the over/under edge." I think we should be using "text-over baseline/text-under baseline as the over/under edge" for every occurrence of the term "leading" within the text-box properties.
| The height of text-only content is relative to the height of the font. In digital font files, the height contains all characters, including capital letters, ascenders, descenders, etc. Different fonts have different base line-heights, meaning that lines of text with the same `font-size` will produce line boxes of differing heights, affecting the appearance of spacing between lines. This can be controlled with the {{cssxref("text-box")}} properties, which enable trimming off extra spacing from the block-start edge and block-end edge of a text element's block container. | ||
|
|
||
| The area of a font above the cap baseline is referred to as the _over edge_. The area below the {{glossary("/Baseline/Typography", "alphabetic baseline")}} is referred to as the _under edge_. |
There was a problem hiding this comment.
| The height of text-only content is relative to the height of the font. In digital font files, the height contains all characters, including capital letters, ascenders, descenders, etc. Different fonts have different base line-heights, meaning that lines of text with the same `font-size` will produce line boxes of differing heights, affecting the appearance of spacing between lines. This can be controlled with the {{cssxref("text-box")}} properties, which enable trimming off extra spacing from the block-start edge and block-end edge of a text element's block container. | |
| The area of a font above the cap baseline is referred to as the _over edge_. The area below the {{glossary("/Baseline/Typography", "alphabetic baseline")}} is referred to as the _under edge_. |
while this content is excellent and well written, it's not relevant to MDN "leading" glossary entry. Suggest moving it to the shorthand page (as there is no guide).
The leading glossary is a helpful addition to the module page. We should add a link to it in line-height
There was a problem hiding this comment.
I've added a link to the leading page from the line-height page, and restructured the leading page, removing some of the text that you quite rightly say doesn't fit. I used a chunk of it in the text-box and text-box-edge pages to improve the description, also making it clear that while the leading is involved, it isn't part of the text defined inside the font.
|
|
||
| {{CSSRef}}{{seecompattable}} | ||
|
|
||
| The **`text-box`** [CSS](/en-US/docs/Web/CSS) property is a shorthand that corresponds to the {{cssxref("text-box-trim")}} and {{cssxref("text-box-edge")}} properties, which together specify the amount of space to trim from the block-start edge and block-end edge of a text element's block container. This includes, but is not limited to, the text's [leading](/en-US/docs/Glossary/Leading). |
There was a problem hiding this comment.
| The **`text-box`** [CSS](/en-US/docs/Web/CSS) property is a shorthand that corresponds to the {{cssxref("text-box-trim")}} and {{cssxref("text-box-edge")}} properties, which together specify the amount of space to trim from the block-start edge and block-end edge of a text element's block container. This includes, but is not limited to, the text's [leading](/en-US/docs/Glossary/Leading). | |
| The **`text-box`** [CSS](/en-US/docs/Web/CSS) property is a shorthand that corresponds to the {{cssxref("text-box-trim")}} and {{cssxref("text-box-edge")}} properties, which together specify the amount of space to trim from the block-start edge and block-end edge of a text element's block container. | |
| The height of text-only content is relative to the height of the font. In digital font files, the height contains all characters, including capital letters, ascenders, descenders, etc. The area of a font above the cap baseline is referred to as the _over edge_. The area below the {{glossary("/Baseline/Typography", "alphabetic baseline")}} is referred to as the _under edge_. Different fonts have different base line-heights, meaning that lines of text with the same `font-size` will produce line boxes of differing heights, affecting the appearance of spacing between lines. The {{cssxref("text-box")}} shorthand property can control this by trimming off extra spacing from the block-start edge and block-end edge of a text element's block container. |
There was a problem hiding this comment.
I've made these changes, but I've done it in a slightly different way, including the extra description in a "Description" section.
@estelle That's right, yes. Until "The default value. Equivalent to the Once |
@estelle I've included these terms in the definition of I think the idea is that when the |
Description
Chrome 133 and Safari 18.2 support the
text-box-*properties from the CSS Inline Layout Module Level 3, which allow you to control how much space is trimmed from the start and/or end block edges of text content.This PR documents:
text-box-trimandtext-box-edgeproperties.text-boxshorthand equivalenttext-edgedatatypeleadingvalue. This is becauseleadingis not a<text-edge>value — it's a separateline-fit-edgevalue. I was initially confused by this because the<text-edge>data type definition is included in theline-fit-edgesection (https://drafts.csswg.org/css-inline-3/#text-edges), and theleadingvalue definition is included in the list of<text-edge>values, even though it isn't part of that data type.It also updates the CSS inline layout module page to make sure all of these things are linked appropriately.
Motivation
Additional details
ChromeStatus entry: https://chromestatus.com/feature/5174589850648576
Related issues and pull requests
BCD: mdn/browser-compat-data#25730