Skip to content

CSS API: Add angle and length checks to WP_CSS_Token - #110

Draft
sirreal wants to merge 3 commits into
css-api/css-token-processor-foundationsfrom
css-api/value-types
Draft

sirreal wants to merge 3 commits into
css-api/css-token-processor-foundationsfrom
css-api/value-types

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.

Add WP_CSS_Token::is_angle() and WP_CSS_Token::is_length(), so code that checks a CSS value's type asks the token instead of keeping its own unit tables, case folding and zero rules. The first consumer is #100, which checks rotate and translate values in kses, the style engine, theme.json and block supports. That PR had added these checks to WP_Style_Engine; they belong to the CSS API, which the style engine can build on.

  • is_angle(): a dimension token whose unit is an ASCII case-insensitive match for deg, grad, rad or turn, per CSS Values 4 angles.
  • is_length(): a dimension token whose unit is a length unit, or a number token whose value is zero. The unit table is the absolute, font-relative and viewport units (including the sv*, lv* and dv* variants) of CSS Values 4 lengths and the container query units of CSS Containment 3.

Both compare the decoded unit from get_unit(), so 1\64 eg is an angle. The unit tables are private constants.

Zero

Token is_angle() is_length() Chrome 157 CSS.supports()
0deg true false rotate: true
0 false true rotate: false, translate: true
-0.0 false true translate: true
1e-400 false false translate: true

CSS Values 4 allows a zero length to be written as the number 0, and allows a bare 0 angle only in some legacy grammars: "For legacy reasons, some uses of <angle> allow a bare 0 to mean 0deg. This is not true in general, however, and will not occur in future uses of the <angle> type." A grammar that accepts a bare zero angle can check for it at the call site.

is_length() treats a number as zero when every digit before its exponent is 0, so 0, -0, +0, 0.0, .0 and 0e3 are lengths. It reads the text rather than converting to a float, so a nonzero number that underflows, such as 1e-400, is not a length. Chrome accepts translate: 1e-400.

Percentages are not lengths: a caller accepting <length-percentage> checks is_length() || WP_CSS_Token_Processor::TOKEN_PERCENTAGE === $token->get_type().

CSS API additions

  • 4bfb0f6 WP_CSS_Token::is_angle(): rotate checks need one angle token.
  • 5c155f5 WP_CSS_Token::is_length(): translate checks need one or two length or percentage tokens.

Tests: Tests_CssApi_WpCssToken::test_is_angle() (22 cases) and test_is_length() (35 cases). --group css-api passes; PHPCS and path-limited PHPStan pass. The docblock examples were run and match their output comments.

Depends on WordPress#14781.

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.

Callers that accept a single angle, such as the `rotate` checks in kses,
the style engine and theme.json, need to know whether a token is an
angle. With only get_type() and get_unit() each caller keeps its own
unit table and case folding.

An angle is a dimension token with a `deg`, `grad`, `rad` or `turn`
unit, compared in ASCII lowercase after escape decoding. The number
token `0` is not an angle. CSS Values 4 allows a bare `0` for `<angle>`
only in some legacy grammars and says future uses will not allow it:
https://drafts.csswg.org/css-values-4/#angles. Chrome reports
CSS.supports( 'rotate', '0' ) as false.
Callers that accept a length, such as the `translate` checks in kses,
the style engine, theme.json and block supports, need to know whether
a token is a length. With only get_type(), get_unit() and get_value()
each caller keeps its own unit table and zero check.

A length is a dimension token with a length unit, compared in ASCII
lowercase after escape decoding, or a number token whose value is
zero. The unit table is the absolute, font-relative and viewport units
of CSS Values 4, https://drafts.csswg.org/css-values-4/#lengths, and
the container query units of CSS Containment 3,
https://drafts.csswg.org/css-contain-3/#container-lengths.

CSS Values 4 allows a zero length to be written as the number 0. Any
number token with the value zero qualifies: `0.0`, `-0`, `+0`, `.0`
and `0e3`. Chrome 157 reports CSS.supports( 'translate', v ) as true
for each of them.

The zero check reads the number's text: it is zero when every digit
before the exponent is `0`. Converting to a float would also accept
nonzero numbers that underflow, such as `1e-400`. Chrome accepts
`translate: 1e-400`, which it parses as zero; this method rejects it.

Percentages are not lengths. A caller that accepts
`<length-percentage>` also checks for a percentage token.
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.
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