[css-values-4] Clarify property value ranges

[cdoublev]

Some parts of the definition of property value ranges (eg. <'color'>) seem confusing to me.

---

Property value ranges, which represent the same pattern of values as a property bearing the same name. [...]

These types do not include CSS-wide keywords such as inherit [...]

CSS-wide keywords are only included in the value definition of a few properties defined in CSS 2 that are not superseded in a later spec.

I suggest this explicit definition:

Property value ranges, which include the set of valid values for a property, excluding CSS-wide keywords and property substitution values.

At least, property substitution values should also be excluded.

Variables defines that var() is valid in any property, and its presence changes the grammar of the property to be valid.

#8823 (comment)

---

These types do not include [...] any top-level comma-separated-list multiplier (i.e. if a property named pairing is defined as [ <custom-ident> <integer>? ]#, then <'pairing'> is equivalent to [ <custom-ident> <integer>? ], not [ <custom-ident> <integer>? ]#).

If I am not mistaken, this rule targets # in value definitions of coordinating list-valued properties. It targets the repetition of a value that can be declared alone for a property.

For example, to match <'property'> with property defined with <foo> | <bar>, <number> in <foo> can be repeated but not in <bar>:

<foo> = a <number>#
<bar> = <number>#

If I am not mistaken in the example above, this type of grammar definition should obviously be avoided, and I suggest to define this rule with an explicit connection to the concept of coordinating list property group.

[tabatkins]

CSS-wide keywords are only included in the value definition of a few properties defined in CSS 2 that are not superseded in a later spec.

Right, they're no longer explicitly written in grammars, but they are in the value space of every property.

At least, property substitution values should also be excluded.

I'm not sure what you mean by "property substitution values" here.

It targets the repetition of a value that can be declared alone for a property.

You're right, our wording wasn't quite correct. Fixed.

[cdoublev]

At least, property substitution values should also be excluded.

I'm not sure what you mean by "property substitution values" here.

It is a language error, sorry. I meant substitution property values.

I particularly mean mix() and toggle(), which must be the only component in a property value, but also var(), env(), etc.

To be transparent/honest, this questions follows this #8823 (comment): I would like to know if, when parsing a value against <'property'> for a property named property, it is ok to accept CSS-wide keywords and subsitution values and not ignore #, assuming the implementation of parse receives the necessary context data to make the difference between <'property'> as the grammar of property and as the grammar of another-property whose value definition is <'property'> (eg. the value definition of all margin-* longhands is <'margin-top'>).

Otherwise I am satisfied with your changes. Thanks! 👌

[tabatkins]

No, I think if a spec said [=CSS/parse=] |foo| as <'background-image'>, we'd want to assume it's referring to the single iteration, and not a CSS-wide keyword, etc.

If something did want to parse an entire property, they could phrase it as [=CSS/parse=] as the 'background-image' property or something.

Do you have a specific example you're asking about?

(I'm going to go ahead and close the issue, tho, as you're satisfied with the resolution overall.)

[cdoublev]

No, I think if a spec said [=CSS/parse=] |foo| as <'background-image'>, we'd want to assume it's referring to the single iteration, and not a CSS-wide keyword, etc.

So CSS wide-keywords are explicitly excluded from property value ranges...

These types do not include CSS-wide keywords such as inherit.

... whereas substitution values ("etc") are not, which may be confusing. It seems that this difference only exists because inherit is explicitly in CSS2 property value definitions.

---

If something did want to parse an entire property, they could phrase it as [=CSS/parse=] as the 'background-image' property or something.

You have gotten to the heart of the matter so I hope there is no need for an example.

How would you represent the "entire property grammar" using the CSS value definition syntax, if you cannot use <'property'>?

You may create an object that [=CSS/parse=] would not need to parse as a grammar described using the CSS value definition syntax:

const grammar = {
  name: 'background-image',
  type: 'property',
  value: '<bg-image>#',
}

The result from parsing <'background-image'> (against the CSS value definition syntax) would just need to get a different type than property.

But it seems inappropriate to me that <'background-image'> does not accept the "entire background-image grammar", so I use context to make the decision to allow it.