[css-page] Spec seems confused about descriptors and properties

[emilio]

@page potentially supports a variety of CSS properties, and some descriptors like size, page-orientation, etc.

It however seems to use the term 'property' for descriptors in arbitrary places... Should probably be less confused?

cc @fantasai

[tabatkins]

Those are all descriptors, even if they match the name and syntax of existing box properties.

Since Page is one of our oldest specs, it's very much not surprising that it's not disciplined about its terminology.

[svgeesus]

Ooof, yes, most but not all uses of property there should be descriptor. The page property is still a property.

Also, the "previous versions" is missing the 2018 publication

[cdoublev]

There is also this part in CSS Syntax 3 - 9.2. At-rules:

At-rules are used to: [...] declare style information that is not associated with a particular element, such as defining counter styles [...]

Block at-rules will typically contain a collection of (generic or at-rule–specific) at-rules, qualified rules, and/or descriptor declarations subject to limitations defined by the at-rule.

If I'm not mistaken, @nest contains property declarations.

In my personal experience, the distinction made in the definition of a declaration (quoted below) between property and descriptor declarations was not enough. Sometimes I still (incorrectly) associate at-rules to descriptor declarations and qualified rules to property declarations.

Declarations are further categorized as property declarations or descriptor declarations, with the former setting CSS properties and appearing most often in qualified rules and the latter setting CSS descriptors, which appear only in at-rules. (This categorization does not occur at the Syntax level; instead, it is a product of where the declaration appears, and is defined by the respective specifications defining the given rule.)

CSS Nesting does not seem to clearly define that nested style rules (directly nested or @nest) contain property declarations. I have to assume that they are a subtype of style rules, and then I have to refer to the definition of style rules in CSS Syntax.

There is this other sentence in 9.2. At-rules (which comes much later than the definition of a declaration):

Descriptors are similar to properties (and are declared with the same syntax) but are associated with a particular type of at-rule rather than with elements and boxes in the tree.

If I set out to distinguish a property/descriptor based on whether it applies to an element or an at-rule, I'm in trouble. Furthermore, afaict, a declaration in a feature/supports or style query (<supports-decl> or <style-feature>) contained in the prelude of @supports or @container, can only be a property declaration.

Maybe a note below the definition of a declaration, with some examples can be helpful for people like me who are not able to figure out quickly and persistently remember how to tell them apart.

EDIT: in my personal notes, I summarized with a declaration for a descriptor can only exist in an at-rule's block value. A declaration for a property can exist in any rule, in its block value or its prelude (as a feature aka. supports query or as a style query).

[SebastianZ]

We're obviously diving deep into the Syntax spec. here and are side-tracking with @nest. But here's how I interpret this.

There is also this part in CSS Syntax 3 - 9.2. At-rules:

At-rules are used to: [...] declare style information that is not associated with a particular element, such as defining counter styles [...]
Block at-rules will typically contain a collection of (generic or at-rule–specific) at-rules, qualified rules, and/or descriptor declarations subject to limitations defined by the at-rule.

If I'm not mistaken, @nest contains property declarations.

Yes. I guess @nest is a special case as it's something between a typical at-rule and a style rule. I looks to me that it is not covered by the list under 9.2. yet. Therefore, the following point in the list should probably be extended to include <style-block> declarations:

group and structure style rules and other at-rules such as in conditional group rules

Though that's something that should be discussed in a separate issue.

In my personal experience, the distinction made in the definition of a declaration (quoted below) between property and descriptor declarations was not enough. Sometimes I still (incorrectly) associate at-rules to descriptor declarations and qualified rules to property declarations.

The association should be the other way round. Descriptor declarations are always part of an at-rule. Though property declarations are normally part of a qualified rule but can also be part of an at-rule.

Declarations are further categorized as property declarations or descriptor declarations, with the former setting CSS properties and appearing most often in qualified rules and the latter setting CSS descriptors, which appear only in at-rules. (This categorization does not occur at the Syntax level; instead, it is a product of where the declaration appears, and is defined by the respective specifications defining the given rule.)

CSS Nesting does not seem to clearly define that nested style rules (directly nested or @nest) contain property declarations.

In my opinion, it has a clear definition in its syntax and in textual form. It says this:

The @nest rule functions identically to a nested style rule: it starts with a selector, and contains a block of declarations that apply to the elements the selector matches. That block is treated identically to a style rule’s block, so anything valid in a style rule (such as additional @nest rules) is also valid here.

And the syntax definition looks like this:

@nest = @nest <selector-list> { <style-block> }

So it clearly states that everything in it is a style block, which represents the contents of a style rule's block.

Descriptors are similar to properties (and are declared with the same syntax) but are associated with a particular type of at-rule rather than with elements and boxes in the tree.

If I set out to distinguish a property/descriptor based on whether it applies to an element or an at-rule, I'm in trouble.

What exactly is your issue here?

Coming back to @page, there's an important point in a side note that makes it obvious that the declarations in it do not apply to elements (emphasizing by me):

An @page rule consists of the keyword @page, an optional comma-separated list of page selectors and a block of declarations (said to be in the page context).

So the declarations only apply to a page and not to elements, so they are descriptors.

Furthermore, afaict, a declaration in a feature/supports or style query (<supports-decl> or <style-feature>) contained in the prelude of @supports or @container, can only be a property declaration.

I'd say so, but again, style declarations are not prohibited within at-rules.

Maybe a note below the definition of a declaration, with some examples can be helpful for people like me who are not able to figure out quickly and persistently remember how to tell them apart.

👍🏻 from me for that.

For reference I want to note #632 and the related commit, in which the syntax of @page got clarified. See its current grammar definition.

Sebastian

[cdoublev]

If I set out to distinguish a property/descriptor based on whether it applies to an element or an at-rule, I'm in trouble.

What exactly is your issue here?

Would you consider the declarations of a keyframe rule to apply on an element or to the parent @keyframes? If I'm not mistaken, they are property declarations applying to an element but I can only say so because descriptor declarations are always part of an at-rule.

Thanks for the reply. My aim was to show that it is not easy to grasp the nuances between a descriptor and a property. After posting my previous comment, I became aware of the issue about the current coupling between properties, CSSStyleDeclaration, and at-rules, and the intent to create new interfaces to fix this problem. But it seems that CSSPageRule.style.setProperty(...) would still have to be supported for back-compat.

As for @nest and CSS Syntax 9.2, it may be better to discuss how to make it easier for spec readers to grasp the difference between a descriptor and a property, in a separate issue, sorry for the noise on this one.

[cdoublev]

Also, if you allow me to ask the following question here, can you please confirm that CSS-wide keywords and custom variables can only apply to descriptors corresponding to properties? Ie. in @page, color: var(--color) or color: initial are valid but not size: var(--size) or size: initial, isn't it?

[SebastianZ]

As @tabatkins wrote earlier, the declarations inside @page are all descriptors.
So regarding custom properties, there are two points that speak against them applying in this context:

1. As their name says, they are custom properties, not custom descriptors.
2. Most at-rules like @page are outside the normal cascade.

Having said that, the spec. defines cascading within the page context.
Therefore, it might be possible to allow custom properties (or custom descriptors in this case) within it. Though, as far as I can see, they are not allowed at the moment.

Regarding CSS-wide keywords, at least inherit is mentioned to be valid but the spec. doesn't explicitly mention whether all of them are valid inside the page and margin contexts.

Also please note that I am also just interpreting the specifications. @fantasai, @SimonSapin or @tabatkins are the authors of the two relevant specs. Maybe they can confirm whether the statements above are correct. Though I think the specs could benefit from some clarification here.

Sebastian

[faceless2]

CSS page states:

page-margin boxes inherit from the page context. The page context inherits from the root element.

I would absolutely expect this to apply to to custom properties as well as regular properties, and having tested the implementations at https://printcss.live all but one of the implementations that support custom properties also support them in the @page rule for properties descriptors such as color - they support @page { color: var(--x) }

I didn't test for size, but we don't make any distinction between descriptors and properties at parse time - and from the discussion in #820 I think this is typical. So I don't see any reason to prevent them applying to size.

For @page and the page margin at-rules, the distinction between property and descriptor is not so useful: color, content, font-family etc. all apply in exactly the same way they do in normal layout , so trying to enforce different parsing rules would be a mistake IMHO. I'm not familiar enough with @keyframe or @nest but if they inherit from :root I suspect I'd probably make the same argument for those too.