Intent to Ship: @page margin boxes

[Chromestatus]

Contact emails

mste...@chromium.org

Explainer

https://github.com/mstensho/page-margin-boxes

Specification

https://drafts.csswg.org/css-page-3/#margin-boxes

Summary

Add support for page margin boxes, when printing a web document, or exporting it as PDF. @page margin boxes allows an author to define the contents in the margin area of a page, for instance to provide custom headers and footers, rather than using the built-in headers and footers generated by the browser. A margin box is defined via an at-rule inside a CSS @page rule. There are 16 rules defined, one for each page margin box. There's one margin box for each of the 4 corners on the page, and three (start, middle, end) for each of the 4 sides. The appearance and the contents of a margin box are specified with CSS properties inside the at-rule, including the "content" property. Counters are also to be supported, for page numbering. The specification defines two special counter names: "page" for the current page number, and "pages" for the total number of pages.

Blink component

Blink>Layout>Printing

TAG review

https://github.com/w3ctag/design-reviews/issues/918

TAG review status

Issues addressed

Risks

Interoperability and Compatibility

The spec defines the CSS counter names 'page' and 'pages'. Both are accessible by the document's contents, so that any element may use the counters to tell the current page number, or the total number of pages. Documents that use these counter names without being aware of this feature may be in for a surprise. Most browsers offer to generate some default headers and footers, and they are usually enabled by default. If the document has margin at-rules, they may come in conflict. We need some way of making sure that we either use the browser-default headers and footers, or the author-defined @page margins.

Gecko: No signal (https://github.com/mozilla/standards-positions/issues/921)

WebKit: No signal (https://github.com/WebKit/standards-positions/issues/275)

Web developers: Positive https://bugs.chromium.org/p/chromium/issues/detail?id=320370 currently has 98 stars.

Other signals:

WebView application risks

Does this intent deprecate or change behavior of existing APIs, such that it has potentially high risk for Android WebView-based applications?

None

Debuggability

None

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, ChromeOS, Android, and Android WebView)?

Yes

Is this feature fully tested by web-platform-tests?

No

WPT tests will be written and submitted while working on this feature.

Flag name on chrome://flags

None

Finch feature name

PageMarginBoxes

Requires code in //chrome?

False

Tracking bug

https://bugs.chromium.org/p/chromium/issues/detail?id=320370

Estimated milestones

Shipping on desktop	131
Shipping on Android	131
Shipping on WebView	131

Anticipated spec changes

Open questions about a feature may be a source of future web compat or interop issues. Please list open issues (e.g. links to known github issues in the project for the feature specification) whose resolution may introduce web compat/interop risk (e.g., changing to naming or structure of the API in a non-backward-compatible way).

None

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5195769732923392?gate=6322213557108736

Links to previous Intent discussions

Intent to Prototype: https://groups.google.com/a/chromium.org/g/blink-dev/c/ZCPkcu_dSF8

This intent message was generated by Chrome Platform Status.

[Mike Taylor]

On 9/19/24 4:58 PM, Chromestatus wrote:

Contact emails

mste...@chromium.org

Explainer

https://github.com/mstensho/page-margin-boxes

Specification

https://drafts.csswg.org/css-page-3/#margin-boxes

Summary

Add support for page margin boxes, when printing a web document, or exporting it as PDF. @page margin boxes allows an author to define the contents in the margin area of a page, for instance to provide custom headers and footers, rather than using the built-in headers and footers generated by the browser. A margin box is defined via an at-rule inside a CSS @page rule. There are 16 rules defined, one for each page margin box. There's one margin box for each of the 4 corners on the page, and three (start, middle, end) for each of the 4 sides. The appearance and the contents of a margin box are specified with CSS properties inside the at-rule, including the "content" property. Counters are also to be supported, for page numbering. The specification defines two special counter names: "page" for the current page number, and "pages" for the total number of pages.

Blink component

Blink>Layout>Printing

TAG review

https://github.com/w3ctag/design-reviews/issues/918

TAG review status

Issues addressed

Risks

Interoperability and Compatibility

The spec defines the CSS counter names 'page' and 'pages'. Both are accessible by the document's contents, so that any element may use the counters to tell the current page number, or the total number of pages. Documents that use these counter names without being aware of this feature may be in for a surprise. Most browsers offer to generate some default headers and footers, and they are usually enabled by default. If the document has margin at-rules, they may come in conflict. We need some way of making sure that we either use the browser-default headers and footers, or the author-defined @page margins.

Can you clarify what you mean by "in for a surprise"? I don't think I understand the compat implications of @page+ margin boxes here.

Also, do you have a plan for default header/footer conflicts w/ developer-provided ones?

Gecko: No signal (https://github.com/mozilla/standards-positions/issues/921)

WebKit: No signal (https://github.com/WebKit/standards-positions/issues/275)

Web developers: Positive https://bugs.chromium.org/p/chromium/issues/detail?id=320370 currently has 98 stars.

Other signals:

WebView application risks

Does this intent deprecate or change behavior of existing APIs, such that it has potentially high risk for Android WebView-based applications?

None

Debuggability

None

I think it's possible to emulate the print media via DevTools. Maybe there are other possible debug modes to visually represent these named margin boxes (as follow up work)?

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/66ec9090.2b0a0220.b3b1b.006b.GAE%40google.com.

[Morten Stenshorne]

I'll remove this at chromestatus. It is no concern for now, since
counters in page / margin contexts will not interact with those of the
document. I.e. it's something we don't implement yet. The spec suggests
that they should interact, but it is vague, not too well thought through
(the spec forgets about parallel flows, for one), and the whole thing is
kind of weird, as counters are resolved in DOM tree order (i.e. the
precense of out-of-flow box, floats, etc.) do not affect the counter
scopes / values. Page / margin counters, on the other hand, need to be
resolved during layout. So we can revisit this later.

I wrote about this here (but how to fix the spec hasn't been discussed
yet):
https://github.com/w3c/csswg-drafts/issues/4760#issuecomment-1959298806

> Also, do you have a plan for default header/footer conflicts w/ developer-provided ones?

Yes, sorry, forgot to update chromestatus again. Now fixed.

Most browsers offer to generate some default headers and footers, and
they are usually enabled by default. If the document has margin

at-rules, they may come in conflict and overlap if no action is
taken. Our solution: When a page has author-defined @page margin boxes
at the same edge of the page as a browser-default header or footer, the
browser-default ones will be suppressed (not displayed). This is in a
way similar to how the browser-default headers and footers are
suppressed when @page margins become too small for them to fit there
(with @page margin boxes, the author kind of takes control of the margin
area, and therefore there's nothing left for the UA, as if the margin on
that edge is zero).

> Gecko: No signal (https://github.com/mozilla/standards-positions/issues/921)
>
> WebKit: No signal (https://github.com/WebKit/standards-positions/issues/275)
>
> Web developers: Positive https://bugs.chromium.org/p/chromium/issues/detail?id=320370 currently has 98 stars.
>
> Other signals:
>
> WebView application risks
>
> Does this intent deprecate or change behavior of existing APIs, such that it has potentially high risk for Android
> WebView-based applications?
>
> None
>
> Debuggability
>
> None
>
> I think it's possible to emulate the print media via DevTools. Maybe there are other possible debug modes to visually
> represent these named margin boxes (as follow up work)?

Yes, we can emulate print media, as in "match @media print rules". But
that doesn't give us pagination. Getting devtools to paginate, so that
one could inspect the page boxes and margins (and margin box contents)
could indeed be useful. This is something that would have been useful
for years already, but with richer pagination support (like @page margin
boxes) it does become even more interesting.

There's crbug.com/40728089 for this.

--
Morten Stenshorne, Software developer,
Blink/Layout, Google, Oslo, Norway

[Mike Taylor]

Thanks for the clarifications.

LGTM1

[Chris Harrelson]

LGTM2

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/dff2c291-19d5-452a-a71e-3f4f0a35c1d4%40chromium.org.

[Daniel Bratell]

LGTM3

/Daniel

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAOMQ%2Bw8UsROUMmf3J%3DqWuWoYQhLKSXimipxhz_uWVHJOgXU6tQ%40mail.gmail.com.