Skip to content

Background: Build background image element styles with the CSS style attribute processor - #101

Draft
sirreal wants to merge 3 commits into
css-api/background-image-element-basefrom
css-api/background-image-element
Draft

sirreal wants to merge 3 commits into
css-api/background-image-element-basefrom
css-api/background-image-element

Conversation

@sirreal

@sirreal sirreal commented Nov 17, 2026

Copy link
Copy Markdown
Owner

Caution

This is a work in progress draft and is not ready for any serious review.

WordPress#11050 (https://core.trac.wordpress.org/ticket/64725) renders media library background images as an <img> inside the block wrapper. It reads and writes two style attributes as text: it looks for an existing wrapper position with preg_match( '/(?:^|;)\s*position\s*:/' ), and it builds the IMG style by concatenating object-fit and object-position values that are escaped for HTML only. This PR replaces both with WP_HTML_Style_Attribute_Processor.

The base branch is WordPress#14782 merged with WordPress#11050 (head 6dc1e7f0c8), so this diff shows only the change to that PR.

Wrapper position

The wrapper gets position: relative unless next_declaration( 'position' ) finds a declaration. The processor matches names ASCII-case-insensitively and ignores text inside strings and comments.

Wrapper style WordPress#11050 This PR
color:red;position:absolute color:red;position:absolute; color:red;position:absolute
color:red;/* note */position:absolute color:red;/* note */position:absolute;position:relative; color:red;/* note */position:absolute
POSITION:absolute POSITION:absolute;position:relative; POSITION:absolute
font-family:"a;position:b" font-family:"a;position:b"; font-family:"a;position:b"; position: relative;
color:red;/*;position:absolute*/ color:red;/*;position:absolute*/; color:red;/*;position:absolute*/ position: relative;

IMG style

The fixed IMG declarations stay as a literal. object-fit and object-position are added with append_declaration(), which accepts a value only when it is one valid declaration value: no top-level ; or !important, no unclosed block, string or function. A rejected backgroundPosition is left out of the style and of data-object-position; the image then uses the default object-position, 50% 50%. object-fit is always cover or contain, because the IMG path is only taken for those sizes.

This checks syntax only. It does not check that the value is a CSS <position>, and it does not run safecss_filter_attr(), which the style engine applies on the CSS background-image path. A browser ignores an object-position declaration whose value has the wrong type.

backgroundPosition WordPress#11050 IMG style ends with This PR IMG style ends with
right 10% bottom 20px object-fit:cover;object-position:right 10% bottom 20px; object-fit: cover; object-position: right 10% bottom 20px;
a value with a top-level ; object-fit:cover;object-position: followed by the whole value, which adds declarations object-fit: cover;
calc(50% + 1px object-fit:cover;object-position:calc(50% + 1px; object-fit: cover;

The processor writes appended declarations as name: value;. The two existing tests from WordPress#11050 look for position: relative instead of position:relative; that is their only change, and they pass. The new tests fail on the base branch in 12 cases: the 7 wrapper cases and 3 IMG cases above, which differ in format in each case and in behavior in 6, and the two existing tests, which differ in format.

Overlap with WordPress#14785

That PR changes the CSS background-image path of the same function, wp_render_background_support(), to append each style engine declaration to the wrapper with append_declaration(). This PR uses the same pattern on the IMG path. The two diffs touch different lines.

Known limitations

Depends on WordPress#14782 and WordPress#11050.

Trac ticket: TBD

Use of AI Tools

AI assistance: Yes
Tools: Claude Code
Models: Claude Opus 5.5
Used for: implementation, tests and this description.


This pull request is for code review only. Keep other discussion in the Trac ticket. Do not merge. See GitHub Pull Requests for Code Review in the Core Handbook.

The IMG background path found an existing wrapper position with a
regular expression and built both style attributes by concatenating
text. The regular expression matched "position:" inside a string or a
comment and missed a declaration written in uppercase or after a
comment:

    color:red;/* note */position:absolute
    => color:red;/* note */position:absolute;position:relative;

The IMG object-position was the block's backgroundPosition attribute
escaped for HTML only, so a value with a top-level semicolon added
declarations to the IMG style.

Use WP_HTML_Style_Attribute_Processor for both. The wrapper gets
position: relative unless next_declaration( 'position' ) finds a
declaration. The IMG style appends object-fit and object-position with
append_declaration(), which rejects a value that is not one valid
declaration value; a rejected position is left out of the style and
of data-object-position.

The processor writes appended declarations as "name: value;", so the
existing assertions look for "position: relative".
Cover wrapper styles with "position" inside a string or a comment, in
uppercase, and after a comment, and IMG object-position values that
are not one CSS declaration value.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant