Many CSS values are ignored or read wrongly, and four common inputs break the document #552

Part of #520 (step 28).

An audit of which CSS properties, values, units, functions and at-rules mPDF reads, on which elements, and where it gets them wrong. The rest of #520 decides which declaration an element gets; this is about what mPDF then does with the value. Measured on gravitypdf at d660a410, PHP 8.5.4, by rendering each case and reading the drawn state, the content streams and rasterised pages. "Browser" means what the CSS specs give.

mPDF handles the core of print CSS well. That covers:

• the block box model, and floats with a width
• solid colours, border longhands and backgrounds
• fonts and spacing, and the common alignments
• page-break-*, repeated table headers and @page margins

About 100 of 210 common properties are read somewhere; the other 110 never are.

Inputs that break the document

Values read wrongly

These are worse than ignored values, because the output is corrupted.

• Lengths
  • calc(), min(), max(), clamp() and var() become 0, which wipes the default margins.
  • vw, vh, vmin, vmax, ch and Q are read as px.
  • rem in a table uses the table's font size.
  • % heights resolve against the page area.
  • line-height: 0 is treated as normal.
• Colours
  • #rgba and #rrggbbaa are misread.
  • A % alpha overflows (/ca 1.36), and channels wrap instead of clamping.
  • transparent draws a black border, with warnings, and black text.
  • A var() or invalid colour becomes black.
  • Shadows with no colour are grey, not currentColor.
  • rebeccapurple is missing.
• Shorthands
  • background loses a colour after url(), and any / size.
  • border: solid #c00 2mm and other orders draw nothing.
  • font turns small-caps into uppercase and keeps an inherited line-height.
• Backgrounds and effects
  • background-size lengths are 2.83× too small.
  • to top/to bottom gradients are reversed, and angles use the legacy convention.
  • repeating-radial-gradient() draws one solid colour.
  • outline-width and outline-color stroke the text.
  • inset shadows are drawn outside.
  • A block's % radius uses the parent's width.
  • border-style: hidden draws a hairline.
• Text
  • text-transform: none doesn't undo an inherited transform on inline elements.
  • list-style-image URLs are lowercased.
  • A url() with spaces, parentheses or inner quotes fails; Bootstrap's select arrow is one.
• Layout
  • A float without a width takes the whole line, and parents always contain their floats.
  • img { display: block; margin: 0 auto } doesn't centre the image.
  • A max-width container with margin: auto is full width.
  • display: contents still paints the box.
  • rotate: 90deg rotates on PHP 7 but not on PHP 8.
• At-rules and pages
  • @media matches by substring: not print applies, and min-width never does.
  • @import ignores its media list and any URL without .css.
  • page-break-before on tables and always on rows are ignored.
  • page-break-after: avoid protects one line only.

Not supported

• High
  • display beyond none (flex, grid, inline-block, table values), and none on table parts
  • position on nested blocks, relative, sticky
  • box-sizing; min-/max-width/-height on blocks and tables
  • CSS functions and custom properties
  • white-space outside <pre>; break-*; @font-face
  • modern colour syntax: hsl() with spaces, hwb(), lab(), oklch(), color-mix()
• Medium
  • a fixed block on every page; z-index between positioned blocks
  • opacity/transform beyond images; border-radius/box-shadow on inline elements, cells and tables; outline
  • object-fit, aspect-ratio; orphans/widows; overflow clipping in flow
  • table-layout, <col> widths, row and table heights
  • text-decoration-* longhands; text-align: start/end; word-break/overflow-wrap; vertical-align keywords on text; text-indent in cells
  • multiple backgrounds; @page margin boxes; @media features
  • further list styles, counters, content, ::marker, quotes
• Low: background-attachment, conic-gradient(), filter, blend modes, clip-path, writing-mode, text-overflow, tab-size, font-stretch, variable-font settings.

Already tracked in #520

Order of work

Some parts are done earlier in #520, with the steps that share their code:

The rest is done here:

1. The values read wrongly that are not quick to fix. Each needs layout work, or support that is still missing:
   • % heights resolved against the page area
   • repeating-radial-gradient() drawing one colour
   • inset shadows drawn outside
   • a block's % border radius resolved against the parent's width (its height is not known until the block closes)
   • a float without a width taking the whole line, and a parent always growing to contain its floats
   • img { display: block; margin: 0 auto } not centring, a max-width container with margin: auto rendering full width, and display: contents still painting its box; these wait for display and max-width support
   • page-break-before: always on table rows, and page-break-after: avoid protecting one line only
2. Missing support, by priority. The large items (display, positioning) depend on Track the stack of open elements while parsing HTML #533 and Inherit from the parent element's computed values under the opt-in cascade #547. Split each into an issue of its own when work on it starts.

Sub-issues

Values read wrongly

• A gradient's first colour stop written at a unitless 0 is dropped, so repeating-radial-gradient(red 0, blue 10px) draws solid blue #584 a first gradient stop at a unitless 0 is dropped (the audit's repeating-radial-gradient() finding)
• box-shadow: inset is drawn outside the box #585 inset box shadows drawn outside
• A percentage border-radius on a block resolves against the parent's width, so 50% draws a pill instead of an ellipse #586 a block's % border radius resolved against the parent's width
• A percentage height on a block resolves against the page area, and height acts as a minimum that overflow: hidden does not clip #587 % heights resolved against the page area, height acting as a minimum, and overflow clipping in normal flow
• A block with max-width and margin: auto renders full width, because min-width and max-width are not read on blocks #588 a max-width container with margin: auto rendering full width
• img { display: block; margin: 0 auto } does not centre the image #589 img { display: block; margin: 0 auto } not centring
• A float without a width takes the whole line, and every ancestor of a float grows to contain it #590 a float without a width taking the whole line, and parents always containing their floats
• page-break-before: always and page-break-after: always on a table row are ignored #591 page-break-before/-after: always on table rows
• page-break-after: avoid leaves a heading at the foot of a page when a table or kept block follows it #592 page-break-after: avoid protecting one line only

Follow-ups to the values read wrongly PRs (#689 to #697)

• Draw the outer box-shadow with the ring builder InsetBoxShadow added, so one class builds both shadows #698 draw the outer box-shadow with the ring builder Draw an inset box-shadow inside the padding box (#585) #694 added
• A box-shadow on a block that breaks across pages is drawn along the split edges, where box-decoration-break: slice would leave them open #699 box-shadow drawn along the split edges of a block that breaks across pages
• page-break-before: left/right on a table row start the next page, not the next even or odd one, and page-break-after: always on the last row does nothing #700 left/right breaks on table rows, and page-break-after: always on the last row
• A min-width wider than the container is capped at the container, and WriteFixedPosHTML() subtracts the left margin where it means the right #701 min-width wider than the container, and the $bbox_ml slip in WriteFixedPosHTML()
• With autoPadding, a percentage border-radius on a block no longer adds padding #702 autoPadding with a percentage border-radius
• A block-level image wider than its line is narrowed instead of overflowing, and text-indent shifts it on a first line #703 a block-level image wider than its line, and text-indent on its line
• A nested box-shadow escapes an overflow: hidden clip, the clip ignores border-radius, and a % height inside a positioned block is auto #704 nested shadows and border-radius under overflow: hidden, % height in a positioned block
• A float with no width is not held to its min-content width, and keeps the full width after a forced page break or with no text to measure #705 the min-content bound and unmeasured cases of a float with no width
• page-break-after: avoid estimates the following line, measures a kept block three times, and waits for a block after bare text #706 page-break-after: avoid: the estimated following line, repeated measuring, bare text
• A gradient position whose last word is 0, such as 10px 0, is read as the angle 0 #707 a gradient position ending in 0 read as the angle

Missing support, high priority

• Support box-sizing, and min-/max- widths and heights on blocks, tables and cells #593 box-sizing, and min-/max- sizes on blocks, tables and cells
• Evaluate calc(), min(), max() and clamp() in lengths #594 calc(), min(), max() and clamp()
• Support custom properties and var() #595 custom properties and var() (after Inherit from the parent element's computed values under the opt-in cascade #547)
• Support white-space on every element #596 white-space on every element
• Load fonts declared with @font-face #597 @font-face
• Lay elements out by their display value: inline-block, table-*, list-item, contents, and none on table parts #598 display: inline-block, table-*, list-item, contents, and none on table parts (after Track the stack of open elements while parsing HTML #533)
• Position nested blocks with absolute and fixed, offset relative boxes, and read sticky #599 positioning: nested absolute/fixed, relative, sticky (after Track the stack of open elements while parsing HTML #533 and Inherit from the parent element's computed values under the opt-in cascade #547)
• Flexbox and grid layout: the design constraints in a streaming renderer #600 flex and grid: design constraints only, no implementation planned

Missing support, medium priority

• Draw a position: fixed block on every page, and stack positioned blocks by z-index #601 a fixed block on every page, and z-index between positioned blocks
• Apply opacity and transform to blocks, tables and inline elements, not only images #602 opacity and transform beyond images
• Draw border-radius, box-shadow and 3D border styles on every element, blur text-shadow, and draw outline #603 border-radius, box-shadow and 3D border styles on every element, text-shadow blur, and outline
• Support object-fit, object-position and aspect-ratio #604 object-fit, object-position, aspect-ratio
• Honour orphans and widows #605 orphans and widows
• Size tables by table-layout, <col> and <colgroup> widths, and row and table heights #606 table-layout, <col>/<colgroup> widths, row and table heights, % cell heights
• Read the text-decoration longhands, text-align: start and end, and word-break and overflow-wrap #607 text-decoration-* longhands, text-align: start/end, word-break/overflow-wrap
• Align inline text with vertical-align keywords, and indent cells and hanging lines with text-indent #608 vertical-align keywords on text, text-indent in cells, hanging, each-line
• Draw every layer of a multiple background #609 multiple backgrounds
• Draw @page margin boxes such as @top-center, with counter(page) and counter(pages) #610 @page margin boxes
• Add list marker styles, reversed, value, ::marker and the list-item counter, and draw quotation marks for <q> #611 list marker styles, reversed, value, ::marker, the list-item counter, and quotes on <q>
• Lay out an element in CSS columns with column-count, column-width and columns #612 CSS columns on an element

@media size and orientation features are in #575, and the low-priority list is not filed.