Skip to content

Interactivity API: Apply data-wp-style with one style attribute processor per element - #111

Open
sirreal wants to merge 4 commits into
css-token-style-attr-processorfrom
css-api/interactivity-style-directive
Open

sirreal wants to merge 4 commits into
css-token-style-attr-processorfrom
css-api/interactivity-style-directive

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.

data_wp_style_processor() reads and rewrites the style attribute once per data-wp-style--* entry with merge_style_property(), which splits the style on every ; and :. A declaration whose value contains either character is cut (https://core.trac.wordpress.org/ticket/63899):

Existing style, directive sets color to green Trunk This PR
background-image:url(a.png) background-image:url(a.png);color:green; background-image:url(a.png); color: green;
background-image:url(https://a.test/a.png) background-image:url(https;color:green; background-image:url(https://a.test/a.png); color: green;

This rewrites the directive on WP_HTML_Style_Attribute_Processor and removes merge_style_property(). It supersedes #99, which rebuilt only merge_style_property() and built one processor per entry. WordPress#12733 fixes the same bug with string splitting.

Design

For each element the directive:

  1. Evaluates every entry without a unique ID into a map of property name to value.
  2. Builds one processor for the style attribute and removes every declaration of each named property in one next_declaration() loop that compares get_property_name() with the map. The cursor only moves forward, so a next_declaration( $name ) loop per property finds nothing after the first loop; the class docblock documents this one-loop form for setting several properties.
  3. Appends a declaration for each set value with append_declaration().
  4. Writes the attribute once, removes it when the result is empty, and leaves it untouched when the result equals the input.

Removing before appending is required for two reasons: a falsy value must remove the property, and an existing !important declaration would otherwise win over an appended normal one. style="color: red !important" with color set to blue gives color: blue;, as on trunk and on the client.

Client semantics

The client directive (packages/interactivity/src/directives/style.ts in Gutenberg) removes the property for a falsy result (!result) and otherwise calls style.setProperty( name, result ), which converts the result to a string. Checked in Chromium:

Existing style setProperty() value Result
color: red !important blue color: blue;
color: red green !important color: red (value ignored)
color: red green; color: red (value ignored)
color: red rgb(0 0 0 color: rgb(0, 0, 0);
none true on --flag --flag: true;
opacity: 1 '0' opacity: 0;

The server now follows the client where it can:

  • The string '0' sets the property. It is truthy on the client; trunk removed the property.

  • true is written as true. Trunk wrote 1.

  • 0, 0.0, '', null, false and any non-scalar value remove the property. Trunk raised a TypeError in trim() for a non-empty array.

  • A string that is not one valid declaration value, such as one with a trailing !important, a trailing ;, a semicolon outside a string or block, or an unbalanced closing bracket, is ignored, and the property keeps its declarations. Each entry is checked by appending its declaration to an empty style before anything is removed, which costs about 14 µs per entry and adds no processor method.

It cannot follow the client in two cases:

  • The client ignores a value that is invalid for the property and keeps the existing declaration. The server checks only declaration syntax, not property grammar, so it cannot tell that color: 5px is invalid.
  • The client closes an unclosed function at the end of the value and sets it; the server ignores the value and keeps the existing declaration.

Output format changes

Other declarations keep their text. The appended declaration is written as name: value; from its tokens.

Existing style Directive Trunk This PR
none color = green color:green; color: green;
padding:10px; color = green padding:10px;color:green; padding:10px; color: green;
color:red;margin:5px; color = green margin:5px;color:green; margin:5px; color: green;
color : red; margin : 5px; padding = 10px color:red;margin:5px;padding:10px; color : red; margin : 5px; padding: 10px;
color:red;;margin:5px;; padding = 10px color:red;margin:5px;padding:10px; color:red;;margin:5px;; padding: 10px;
padding:10px color = false padding:10px; padding:10px (unchanged)
none font-family = "Foo;Bar", serif font-family:"Foo;Bar", serif; font-family: "Foo\3b Bar", serif;

The serializer escapes a ; in a string and a ; or , in an unquoted url(). CSS reads the escaped and unescaped forms as the same value.

Behavior changes

Existing style Directive Trunk This PR
font-family:"Foo;Bar",serif;color:red font-family = serif Bar",serif:;color:red;font-family:serif; and a PHP warning color:red; font-family: serif;
COLOR:red;margin:5px color = green COLOR:red;margin:5px;color:green; margin:5px; color: green;
opacity:1 opacity = '0' attribute removed opacity: 0;
none --flag = true --flag:1; --flag: true;
color:red;margin:5px color = array( 'green' ) TypeError margin:5px
color:red;margin:5px color = green !important margin:5px;color:green !important; color:red;margin:5px (unchanged)
color:red;margin:5px color = rgb(0 0 0 margin:5px;color:rgb(0 0 0; color:red;margin:5px (unchanged)
color:red;margin:5px padding = 10px; color:red;margin:5px;padding:10px; color:red;margin:5px (unchanged)

Tests

merge_style_property() tests are ported to the directive level through process_directives(), as are the tests from #99 and WordPress#12733, with expected strings in the format above. New cases cover several entries on one element, an existing !important declaration, falsy and scalar values, values with ; inside a string or url(), invalid values, and an unchanged attribute. --group interactivity-api,html-api,css-api passes; PHPCS and PHPStan report no errors.

Cost

µs per element for data_wp_style_processor(), excluding tag processor setup. PHP 8.5 CLI, opcache off, one process per variant, best of 5 rounds of 5,000 elements. The style has 5 declarations in 96 bytes; entries replace color, then padding, then add height.

Entries Trunk #99 This PR
1 2.8 85 85
2 4.8 173 138
3 7.0 258 185
1, no style attribute 1.7 17 17

For this style, parsing costs 23 µs (13 µs of it tokenizing), each remove_declaration() 18 µs and each append_declaration() 42 µs, because each mutation parses the whole style again to verify the result and append_declaration() also tokenizes the name and value several times. One processor per element saves one parse per entry after the first. Joining serialize_declaration() of the kept declarations with each value appended to an empty processor measures 44, 59 and 75 µs, but it rewrites every kept declaration and the processor does not verify the joined result. These numbers were measured before the value check above; it adds about 14 µs per entry with a value.

Known limitations

  • After a style that ends in whitespace, the appended declaration follows two spaces.
  • The cost above is 30 times trunk's for one entry on a styled element.

Depends on WordPress#14782.

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.

data_wp_style_processor() read, split and rewrote the style attribute
once per data-wp-style entry with merge_style_property(), which split
the style on every `;` and `:`. A declaration whose value contained
either character was cut:

    style="background-image:url(https://a.test/a.png)"
      trunk: background-image:url(https;color:green;

The directive now collects the evaluated value of every entry, builds
one WP_HTML_Style_Attribute_Processor for the element, removes every
declaration of each named property in one next_declaration() loop,
appends a declaration for each set value, and writes the attribute
once. merge_style_property() is removed. Removing before appending
makes a value replace an existing `!important` declaration, as the
client's style.setProperty() does.

Values follow the client where CSS can write them: the string '0'
sets the property (it is truthy on the client), `true` is written as
`true`, and a non-scalar value removes the property instead of
raising a TypeError in trim().

Other declarations keep their text. The appended declaration is
written as `name: value;`, so expected strings in tests change format.
A value that is not one valid declaration value (a top-level `;`, an
unclosed function, a trailing `!important`) removes the property and
appends nothing.

Measured per element, PHP 8.5 CLI, one process per variant, best of
5 rounds, on a 5-declaration style: see the pull request.

See #63899.
Keeps the cases for an unclosed function, a trailing `!important` and
a closing brace. The behavior for other invalid values is documented
on data_wp_style_processor().
@github-actions

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

Core Committers: Use this line as a base for the props when committing in SVN:

Props jonsurrell.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub or WordPress.org user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

The client applies each entry with style.setProperty(), which ignores a
value the browser cannot parse as the property's value and leaves the
existing declaration in place. The server removed the property's
declarations and then failed to append, so the two disagreed: the
server output lost the declaration that the client kept.

An entry is now checked by appending its declaration to an empty style
before anything is removed. A value that fails, such as one with a
trailing `!important` or an unbalanced closing bracket, is skipped,
and the property keeps its declarations. A trailing `;` is no longer
removed from the value, since the client ignores such a value too.
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