Skip to content

Style Engine: Check transform values with CSS tokens, not regexes - #100

Draft
sirreal wants to merge 9 commits into
css-api/transform-basefrom
css-api/transform-values
Draft

sirreal wants to merge 9 commits into
css-api/transform-basefrom
css-api/transform-values

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.

Check rotate and translate values with CSS tokens instead of regular expressions. This is an alternative to the value checks in WordPress#15465 (translate, https://core.trac.wordpress.org/ticket/66467), which is stacked on WordPress#15408 (rotate, https://core.trac.wordpress.org/ticket/66468).

The base branch, css-api/transform-base, is WordPress#14784 (PR 3, parser-based safecss_filter_attr()) merged with WordPress#15465. The merge gives PR 3's parser path the same regex checks as the legacy path, so this diff contains only the alternative. The base also merges #110, which adds the token checks this PR uses, and #112, which adds WP_CSS_Token_Processor::parse_single_token().

WP_Style_Engine::VALID_ANGLE_PATTERN and VALID_LENGTH_PERCENTAGE_PATTERN are removed. The checks use WP_CSS_Token::is_angle() and WP_CSS_Token::is_length(); a length or percentage is is_length() or a percentage token. Callers that hold text use WP_CSS_Token_Processor::parse_single_token(), and the text must tokenize as exactly one token:

  • angle: a dimension token with a deg, grad, rad or turn unit, compared in ASCII lowercase. No number is an angle.
  • length or percentage: a percentage token, a dimension token with a length unit, or a number token whose value is zero. The unit table lists the units the regex lists.

In kses, _safecss_filter_attr_is_translate_value() replaces preg_split( '/\s+/' ): one or two length or percentage tokens, the second after a whitespace token, comments ignored. The parser path passes its value tokens directly. The legacy path tokenizes its trimmed value, for rotate as for translate. The style engine value_funcs, WP_Theme_JSON and wp_fill_translate_axes() read their text with WP_CSS_Token_Processor::parse_single_token().

Differences from the regexes

The accepted sets differ in four ways: exponents, escaped units, the number 0 for rotate, and zero lengths written other than 0.

Input WordPress#15465 This PR
rotate: 100deg rotate: 100deg; rotate: 100deg;
rotate: 1e2deg (empty) rotate: 1e2deg;
rotate: 0deg rotate: 0deg; rotate: 0deg;
rotate: 0 rotate: 0; (empty)
translate: 0 translate: 0; translate: 0;
translate: 0.0 (empty) translate: 0.0;

This applies to kses (both paths), the style engine and theme.json. translate: 1e1px behaves the same way.

Style engine rotate value WordPress#15465 This PR
1deg rotate:1deg; rotate:1deg;
1\64 eg (empty) rotate:1deg;

The style engine passes declarations through safecss_filter_attr(), whose parser path writes the unit decoded. WP_Theme_JSON writes the value as given: rotate: 1\64 eg;. The value is still one dimension token. In kses there is no difference: the parser path already checked decoded tokens, and the legacy path rejects every \.

These give the same result on both, on both kses paths: comments, +1deg, .5turn, uppercase units, !important, and every whitespace form tested (tab, newline, form feed, vertical tab, no-break space, a comment as the only separator, no space after a percentage).

rotate: 0 is rejected because CSS Values 4 allows a bare 0 angle only in some legacy grammars (https://drafts.csswg.org/css-values-4/#angles), and Chrome 157 reports CSS.supports( 'rotate', '0' ) as false. A zero length needs no unit (https://drafts.csswg.org/css-values-4/#lengths), so every number token with the value zero is a length: 0.0, -0, +0, .0 and 0e3. Chrome 157 accepts each as a translate value.

Comparison with WordPress#15465

CSS API additions

Known limitations

  • The Gutenberg regexes and their JavaScript copies stay as they are, so the editor and Gutenberg's PHP reject exponents that core accepts.

Depends on WordPress#14784, WordPress#15465, #110 and #112.

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.

Replace WP_Style_Engine::VALID_ANGLE_PATTERN and
VALID_LENGTH_PERCENTAGE_PATTERN with WP_Style_Engine::is_angle() and
WP_Style_Engine::is_length_percentage(). Each takes CSS text or a
WP_CSS_Token. Text must tokenize as exactly one token: a dimension
token with an angle or length unit compared in ASCII lowercase, a
percentage token, or the number token `0`. The unit tables list the
units the regexes listed.

kses checks `translate` on tokens instead of preg_split( '/\s+/' ):
one or two length or percentage tokens, the second after a whitespace
token, comments ignored. The parser path passes its value tokens
directly and no longer serializes them to run a regex. The legacy path
tokenizes its trimmed value.

The accepted set differs from the regexes in two ways:

- A number with an exponent is accepted, as CSS reads it:

    input             regex     tokens
    rotate: 100deg    accepted  accepted
    rotate: 1e2deg    rejected  accepted

- In the style engine and theme.json, an escaped unit is accepted.
  The style engine output is already filtered by
  safecss_filter_attr(), whose parser path writes the unit decoded:

    rotate value      regex         tokens
    1deg              rotate:1deg;  rotate:1deg;
    1\64 eg           (empty)       rotate:1deg;

  kses was already the same on both: the parser path checks decoded
  tokens, and the legacy path rejects every `\`.

Comments, `+1deg`, `.5turn`, uppercase units and every whitespace form
tested give the same result on both. The number `0` stays the only
unitless value, so `0.0` and `-0` are rejected as before.

Every test from
WordPress#15408 and
WordPress#15465 passes
unchanged. `--group
kses,style-engine,block-supports,themes,css-api`: 3503 tests pass.
sirreal added a commit that referenced this pull request Nov 17, 2026
The base now includes WP_CSS_Token::is_angle() and is_length() from
#110, so the diff of
#100 shows only their
use.
Replace WP_Style_Engine::is_angle() and is_length_percentage() with
WP_CSS_Token::is_angle() and is_length(). Value-type checks belong to
the CSS API, which the style engine can build on, so the style engine
no longer has public value-type methods or unit tables.

A `<length-percentage>` check is is_length() or a percentage token,
written at each of its three call sites.

Callers that hold text, the style engine, WP_Theme_JSON and
wp_fill_translate_axes(), need the one token the text is. The private
_wp_style_engine_get_single_css_token() returns it, or null when the
text is not a string of exactly one token. Leading or trailing
whitespace is a token, so values with it are still rejected. The
legacy kses path tokenizes its trimmed value for `rotate` as it did for
`translate`, and checks for a single angle token.

The token methods change two results:

- The number 0 is not an angle, so `rotate: 0` is rejected. CSS Values
  4 allows a bare 0 angle only in some legacy grammars, and Chrome
  rejects it for `rotate`.
- Every number token with the value zero is a length, so `0.0`, `-0`
  and `.0` are accepted as `translate` axes, as `0` was.

The style engine value tests test wp_style_engine_get_styles() output
in place of the removed methods. The CSS API tests cover the token
methods.
WP_CSS_Token::is_angle() does not accept the number 0. CSS Values 4
allows a bare 0 angle only in some legacy grammars, and says future
uses of `<angle>` will not allow it:
https://drafts.csswg.org/css-values-4/#angles. Chrome 157 reports
CSS.supports( 'rotate', '0' ) as false and CSS.supports( 'rotate',
'0deg' ) as true.

The kses data case for `rotate: 0` now expects empty output. The block
states and theme.json tests that output a zero rotation under a media
query use `0deg`, so they still test the media query output. New cases
check that the style engine, theme.json and both kses paths reject the
number 0 for `rotate`.
WP_CSS_Token::is_length() accepts every number token with the value
zero, as CSS Values 4 allows a zero length without a unit:
https://drafts.csswg.org/css-values-4/#lengths. Chrome 157 reports
CSS.supports( 'translate', v ) as true for `0.0`, `-0`, `+0`, `.0` and
`0e3`.

The kses case for `translate: 0.0` now expects the declaration on both
paths. New cases cover the other zero forms in kses, the style engine
and the block supports axis fill, and check that `0.1` is still
rejected.
…en().

WP_CSS_Token_Processor::parse_single_token() accepts exactly one token
and rejects whitespace or comments around it, as the private
_wp_style_engine_get_single_css_token() did, so the helper is removed.
Callers pass only strings to it. No test expectations change.
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