max-height value of "stretch" is missing from the listed Values

[graymatter00]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/CSS/max-height

What specific section or headline is this issue about?

Values

What information was incorrect, unhelpful, or incomplete?

A description for the stretch value is missing. However, it is mentioned as a part of the description for the fit-content() value, and it is in the Browser compatibility table.

What did you expect to see?

An description for the stretch value.

Do you have any supporting links, references, or citations?

No response

Do you have anything more you want to share?

No response

MDN metadata

Page report details

• Folder: en-us/web/css/max-height
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/CSS/max-height
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/css/max-height/index.md
• Last commit: 925b2bd
• Document last modified: 2023-10-27T19:45:47.000Z

[hamishwillee]

This is valid, but for whoever does this it needs to also be added to these cases: width, height, inline-size, block-size, min-width, min-height, min-inline-size, min-block-size, max-width, max-height, max-inline-size, max-block-size - according to https://drafts.csswg.org/css-sizing-4/#sizing-values

@graymatter00 Are you interested in adding this?

[graymatter00]

Hi @hamishwillee.

Good point on the need for the same requirement in the other size properties. 👍

@graymatter00 Are you interested in adding this?

I don't think my documentation writing skills are up to the challenge. I'll leave it to the good people who I'm sure can do a better job than me.

[hamishwillee]

No worries. @OnkarRuikar Just did some changes in this area and I'm hoping will jump on it.

[OnkarRuikar]

No worries. @OnkarRuikar Just did some changes in this area and I'm hoping will jump on it.

I didn't document stretch and contain properties while adding fit-content because no browser has implemented them. Though the BCD table shows stretch property implemented by chromium based browsers it hasn't actually been implemented by any browsers yet:

The equivalent available value in chromium is -webkit-fill-available which doesn't seem to be well recognized.

I don't know if it is a good idea to document unimplemented experimental features because they tend to change a lot and not implemented. For example in case of @page at-rule we had to remove a lot of documented stuff which is there in specs but not implemented for a decade.

[hamishwillee]

@OnkarRuikar I knew you'd have a reason, but I saw it in the BCD. As you say, the rule is that we document stuff once there is an implementation.

Either way, there is a bug here. I suspect that perhaps the BCD reflects the version in which stretch can be used as an option to fit-content. If that's the case we need to rename that subfeature so it is more obvious.
Is there an easy way to test the assumption?

[OnkarRuikar]

Either way, there is a bug here.

Yes, as per the BCD policy Removal of irrelevant features the stretch value shouldn't exist in BCD as no browser supports it. So the PR Rename fill-available as stretch shouldn't have landed and -webkit-fill-available should've been kept as it is.

/cc @queengooborg

[hamishwillee]

Cool, but it's not just that. The docs reference it

[dipikabh]

Hi @OnkarRuikar, I started looking at your PR #35262, and I thought I could continue the discussion here instead of in the PR.

I believe you had the correct idea in #29887 (comment) to not document the value stretch yet; not only does it not have cross-browser support, but it is also not called stretch in Chrome or Firefox.

• If we document stretch and inline-tag it as experimental (which you have done in your PR), I think it would be incomplete if we don't also mention in content not to use the name stretch since the supported version as per BCD has the name -webkit-fill-available (in case folks don't check the BCD table). So perhaps we should also inline tag it as non-standard, that is, if we document it? Probably a case to mark it as "standard_track": false in BCD as well.
  BTW, I noticed Firefox's alternate name for it (-moz-available):

Firefox	Chrome

• BCD table for width gives a clue about the alternate name for stretch in Firefox: -moz-available.
• I realize this particular issue has been for opened for the missing stretch value, but there's a similar problem with anchor-size(), in that it exists in the "Syntax" block and BCD table, but missing from "Values" (and "Formal syntax"). Just to draw a comparison between anchor-size() and fit-content(), since they are both experimental, only fit-content() appears in "Formal syntax". (btw, anchor-size() didn't work for me even in Chrome)

Looking at max-height via the lens of https://drafts.csswg.org/css-sizing/#max-size-properties (Level 3) and comparing with our content:

value or keyword	"Syntax" section	"Values" section	"Formal syntax" section	Browser compat table
none, min-content, max-content	✅	✅	✅	✅
<length> and <percentage> are fine although I would combine them as <length-percentage> under "Values"	✅	✅	✅	-
fit-content(<length-percentage>)	✅ should not be listed with keyword values	✅ needs to be inline tagged experimental	✅	✅ (experimental)
<calc-size()>		❌	✅	-
anchor-size() - not in the spec	✅	❌	❌	✅ (experimental)
fit-content (Level 4)	✅	✅	❌	✅

Some other observations:

• <calc-size()> has not been covered anywhere in our docs
• Randomly looking at block-size to which we'll now be adding stretch, its browser compat table doesn't yet include stretch.
• stretch in height's BCD table is not marked experimental, so there is some inconsistency there.
• Both the links in max-height "Specifications" resolve to the same section in spec, but perhaps it should be updated to point to https://drafts.csswg.org/css-sizing/#max-size-properties.

With the current discrepancies in browser compat data and "Formal syntax", my proposal is:

• Not to document stretch until it reaches standardization. We can avoid using stretch in fit-content:

fit-content: Uses the available space, but not more than max-content, i.e., min(max-content, max(min-content, <length-percentage>)), where <length-percentage> represents the available space.

and

fit-content([<length-percentage>]): Uses the fit-content formula with the available space replaced by the specified argument, i.e. min(max-content, max(min-content, <length-percentage>)).

• BCD for stretch can be updated to non standard track.
• I don't know what's the story behind anchor-size(). I understand if we want to show it as an example where it can be passed into calc(), but I don't get it being listed as a separate entry in BCD table.

Let me know what you think.

Also /cc @hamishwillee again to get his inputs.

[OnkarRuikar]

Not to document stretch until it reaches standardization. We can avoid using stretch in fit-content:

👍 Waiting for Hamish's opinion.

BCD for stretch can be updated to non standard track.

The stretch value has been documented in the specs. So, how can we say it's non-standard?
We could mention -moz-available and -webkit-fill-available in the value sections though iff we document the stretch.

but missing from "Values" (and "Formal syntax").

The values not appearing in Formal syntax is an yari issue mdn/yari#11607 .

(btw, anchor-size() didn't work for me even in Chrome) and but I don't get it being listed as a separate entry in BCD table

The anchor-size() value does work stand alone(without calc()) in Chromium 127 and 129:

anchor-size.mp4

[dipikabh]

The stretch value has been documented in the specs. So, how can we say it's non-standard?

True, by definition standard_track means the feature is part of an active specification, so in those terms BCD cannot be updated and I stand corrected. For width, stretch is marked experimental even though it is supported in more than one browser engine. Perhaps in this case, "experimental" is also indicating that the feature has a non-standard name.

(While we are trying to move away from vendor-specific prefixes (FAQ), browsers did not implementstretch behind a flag or preference (as is usually done for experimental features these days), but instead used prefixes.)

The anchor-size() value does work stand alone(without calc()) in Chromium 127 and 129

I was trying it as a value in max-height. But yes, max-height: anchor-size(width), max-height: anchor-size(height), and max-height: calc(anchor-size(height) * 2) sure are working in Chrome.
(I don't know why I earlier tried max-height: anchor-size(2em), which was invalid.)

Thanks for opening the yari issue!

[hamishwillee]

This is a complicated set of questions and also it looks like some of them have already been agreed by you guys. But on quick scan my opinion:

• stretch is standard, and appears to be applicable in some form or other in max-height, min-height, max-width, min-width, width
• We reflect BCD.
  • Syntax and Formal syntax for these cases need to mention stretch and remove alias.
  • stretch needs to be documented in those cases. Given the number of aliases I think it reasonable to have a note in those documents under the stretch vale that this is commonly implemented as an alias, and they should check BCD. Very happy for the common aliases to be listed there too so they can easily be found.
  • you might argue that it is also listing the aliases as separate properties, but I'd try avoid it.
• Other cases that don't use stretch or any alias of course omit it.
• Same logic should apply to fit-content etc.

In summary, "Always follow BCD but you can provide hints to non standard things in its docs".

Is that helpful? If not, let me know the issues which there is disagreement on?

[dipikabh]

Thanks, @hamishwillee.
"Always follow BCD but you can provide hints to non standard things in its docs" seems to be a good general guidance to run with for this case.

Thankfully, Syntax and Formal syntax do not mention the aliases; they appear only in BCD.
(I found a mention of -moz-available on the Mozilla Extensions page.)

@OnkarRuikar, when you have a moment, WDYT about making these updates to your PR:

• Removing stretch from properties that do not have it in their BCD (e.g., inline-size and block-size)
• Adding a note to the stretch description you've added to let users know to check browser compat for the alias used. I'm not too keen on explicitly naming them in the note, but rather just point users to check the BCD table. Let me know if you have other suggestions.

If we're on the same page with the changes, I can proceed with reviewing the PR. Thanks!