[css-page] Consider making 'size' a legacy alias of a new descriptor ('page-size')?

[emilio]

This would clear confusion with #820 long term at least. See the minutes in that bug.

cc @fantasai @tabatkins

[mstensho]

This is a great opportunity to give it a more descriptive name.

See https://drafts.csswg.org/css-page-3/#page-size-prop (oh hai, it's already #page-size-prop , oh well).

This property specifies the target size and orientation of the page box’s containing block.

Although "page-size" is ambiguous (is it the page box size or the page area size?), it doesn't even set the page size. It sets the size of the containing block of the page box, which becomes interesting if the page area is sized with percentages (also if page margins use percentages, of course).

  @page {
    size: 300px;
    margin: 100px;
    width: 50%;
    background: cyan;
  }
  body {
    margin: 0;
    background: yellow;
  }

The page area width becomes 150px (50% of 300px). The page box width becomes 350px (150px + page margins). Further explanation: https://drafts.csswg.org/css-page-3/#page-model

The containing block of the page box is specified using the size property in the page context. The width and horizontal margins of the page box are then calculated exactly as for a non-replaced block element in normal flow. [CSS2] The height and vertical margins of the page box are calculated analogously (instead of using the block height formulas). In both cases if the values are over-constrained, instead of ignoring any margins, the containing block is resized to coincide with the margin edges of the page box.

I don't know what a good name would be. Just pointing out that page-size isn't great. But neither was size, of course. :)

[faceless2]

Although "page-size" is ambiguous (is it the page box size or the page area size?), it doesn't even set the page size. It sets the size of the containing block of the page box

Yes it does - the margin-box, in other words. Putting my PDF hat on, it sets the PDF trim box. Add the "bleed" property to that and you get the bleed box, which is typically the same as the content box, which is typically the same as or smaller than the media box, which is the physical size of the page. Naming things is hard 😄

Once you consider how size interacts with the bleed property, it's actually the only way it can be implemented - it's not ambiguous, just perhaps under-documented in css-page. And again want to stress this behaviour is fairly consistent across all (that I know of) PDF-focused layout engines and has been specified this way for many years.