diff --git a/src/wp-includes/css-api/class-wp-css-token.php b/src/wp-includes/css-api/class-wp-css-token.php index 55af708415637..cf9a10c04f9a9 100644 --- a/src/wp-includes/css-api/class-wp-css-token.php +++ b/src/wp-includes/css-api/class-wp-css-token.php @@ -34,6 +34,81 @@ * @see WP_CSS_Token_Processor::get_token() */ final class WP_CSS_Token { + /** + * Angle units, lowercase. + * + * @since 7.3.0 + * @ignore + * + * @link https://drafts.csswg.org/css-values-4/#angles + * + * @var string[] + */ + private const ANGLE_UNITS = array( 'deg', 'grad', 'rad', 'turn' ); + + /** + * Length units, lowercase. + * + * @since 7.3.0 + * @ignore + * + * @link https://drafts.csswg.org/css-values-4/#lengths + * @link https://drafts.csswg.org/css-contain-3/#container-lengths + * + * @var string[] + */ + private const LENGTH_UNITS = array( + 'px', + 'cm', + 'mm', + 'q', + 'in', + 'pt', + 'pc', + 'em', + 'rem', + 'ex', + 'rex', + 'cap', + 'rcap', + 'ch', + 'rch', + 'ic', + 'ric', + 'lh', + 'rlh', + 'vw', + 'vh', + 'vi', + 'vb', + 'vmin', + 'vmax', + 'svw', + 'svh', + 'svi', + 'svb', + 'svmin', + 'svmax', + 'lvw', + 'lvh', + 'lvi', + 'lvb', + 'lvmin', + 'lvmax', + 'dvw', + 'dvh', + 'dvi', + 'dvb', + 'dvmin', + 'dvmax', + 'cqw', + 'cqh', + 'cqi', + 'cqb', + 'cqmin', + 'cqmax', + ); + /** * CSS source the offsets index. * @@ -313,6 +388,104 @@ public function is_terminated(): bool { return $this->is_terminated; } + /** + * Reports whether the token is a CSS angle. + * + * An angle is a dimension token whose unit is an ASCII case-insensitive + * match for `deg`, `grad`, `rad` or `turn`. The unit is compared after + * escape decoding. + * + * A number token is never an angle, not even `0`. CSS allows a bare `0` + * for an angle only in some legacy grammars, and not in properties such + * as `rotate`. + * + * Example: + * + * ```php interactive + * $processor = new WP_CSS_Token_Processor( '-.5TURN 1\\64 eg 0 45' ); + * while ( $processor->next_token() ) { + * $token = $processor->get_token(); + * if ( WP_CSS_Token_Processor::TOKEN_WHITESPACE !== $token->get_type() ) { + * var_dump( $token->is_angle() ); + * } + * } + * // Outputs: + * // bool(true) + * // bool(true) + * // bool(false) + * // bool(false) + * ``` + * + * @since 7.3.0 + * + * @link https://drafts.csswg.org/css-values-4/#angles + * + * @return bool Whether the token is an angle. + */ + public function is_angle(): bool { + return ( + WP_CSS_Token_Processor::TOKEN_DIMENSION === $this->type && + in_array( strtolower( (string) $this->unit ), self::ANGLE_UNITS, true ) + ); + } + + /** + * Reports whether the token is a CSS length. + * + * A length is a dimension token whose unit is an ASCII case-insensitive + * match for a length unit, or a number token whose value is zero. The + * unit is compared after escape decoding. The length units are the + * absolute, font-relative and viewport units of CSS Values 4 and the + * container query units of CSS Containment 3. + * + * CSS allows a bare zero for a length. A number token is zero when every + * digit before its exponent is `0`, whatever its sign, decimal point or + * exponent: `0`, `-0`, `0.0`, `.0` and `0e3`. A nonzero number is not a + * length, even one too small to represent as a float, such as `1e-400`. + * + * Percentages are not lengths. Check for a percentage token separately + * where CSS accepts ``. + * + * Example: + * + * ```php interactive + * $processor = new WP_CSS_Token_Processor( '10DVH 1\\70 x -0.0 50% 10' ); + * while ( $processor->next_token() ) { + * $token = $processor->get_token(); + * if ( WP_CSS_Token_Processor::TOKEN_WHITESPACE !== $token->get_type() ) { + * var_dump( $token->is_length() ); + * } + * } + * // Outputs: + * // bool(true) + * // bool(true) + * // bool(true) + * // bool(false) + * // bool(false) + * ``` + * + * @since 7.3.0 + * + * @link https://drafts.csswg.org/css-values-4/#lengths + * @link https://drafts.csswg.org/css-contain-3/#container-lengths + * + * @return bool Whether the token is a length. + */ + public function is_length(): bool { + switch ( $this->type ) { + case WP_CSS_Token_Processor::TOKEN_DIMENSION: + return in_array( strtolower( (string) $this->unit ), self::LENGTH_UNITS, true ); + + case WP_CSS_Token_Processor::TOKEN_NUMBER: + // A number is zero when its digits before any exponent are all `0`. + $number = (string) $this->get_value(); + return '' === trim( substr( $number, 0, strcspn( $number, 'eE' ) ), '+-.0' ); + + default: + return false; + } + } + /** * Decodes the value from the CSS source. * diff --git a/tests/phpunit/tests/css-api/wpCssToken.php b/tests/phpunit/tests/css-api/wpCssToken.php index 10fa39d42fb23..99141ede2b2d1 100644 --- a/tests/phpunit/tests/css-api/wpCssToken.php +++ b/tests/phpunit/tests/css-api/wpCssToken.php @@ -216,4 +216,120 @@ public static function data_comment_value(): array { 'no escapes, newlines preprocessed' => array( "/*\\41\r\n*/", "\\41\n" ), ); } + + /** + * Tests that a token reports whether it is an angle. + * + * @ticket 65738 + * @dataProvider data_is_angle + * + * @covers ::is_angle + */ + public function test_is_angle( string $css, bool $expected ): void { + $this->assertSame( $expected, self::get_only_token( $css )->is_angle() ); + } + + /** + * Data provider for test_is_angle(). + * + * @return array[] + */ + public static function data_is_angle(): array { + return array( + 'degrees' => array( '45deg', true ), + 'gradians' => array( '100grad', true ), + 'radians' => array( '1.5rad', true ), + 'turns' => array( '.5turn', true ), + 'negative' => array( '-15deg', true ), + 'leading plus sign' => array( '+1deg', true ), + 'zero with a unit' => array( '0deg', true ), + 'exponent' => array( '1e2deg', true ), + 'negative exponent' => array( '1e-1turn', true ), + 'uppercase unit' => array( '1DEG', true ), + 'mixed case unit' => array( '100GrAd', true ), + 'hex escape in the unit' => array( '1\\64 eg', true ), + 'identity escape in the unit' => array( '1de\\g', true ), + 'number 0' => array( '0', false ), + 'number other than 0' => array( '45', false ), + 'percentage' => array( '50%', false ), + 'length' => array( '1px', false ), + 'unit with a suffix' => array( '1degs', false ), + 'unit with a trailing null' => array( "1deg\0", false ), + 'non-ASCII letter in the unit' => array( "1d\u{0435}g", false ), + 'ident' => array( 'deg', false ), + 'function' => array( 'calc(', false ), + ); + } + + /** + * Tests that a token reports whether it is a length. + * + * @ticket 65738 + * @dataProvider data_is_length + * + * @covers ::is_length + */ + public function test_is_length( string $css, bool $expected ): void { + $this->assertSame( $expected, self::get_only_token( $css )->is_length() ); + } + + /** + * Data provider for test_is_length(). + * + * @return array[] + */ + public static function data_is_length(): array { + return array( + 'pixels' => array( '10px', true ), + 'quarter millimeters' => array( '1Q', true ), + 'font-relative unit' => array( '.5em', true ), + 'root font-relative unit' => array( '1rcap', true ), + 'viewport unit' => array( '10vmin', true ), + 'small viewport unit' => array( '1svmax', true ), + 'large viewport unit' => array( '1lvh', true ), + 'dynamic viewport unit' => array( '10DVH', true ), + 'container query unit' => array( '2cqi', true ), + 'negative' => array( '-1px', true ), + 'leading plus sign' => array( '+.5em', true ), + 'exponent' => array( '1e1px', true ), + 'uppercase unit' => array( '1PX', true ), + 'hex escape in the unit' => array( '1\\70 x', true ), + 'number 0' => array( '0', true ), + 'zero with a decimal point' => array( '0.0', true ), + 'negative zero' => array( '-0', true ), + 'zero with a plus sign' => array( '+0', true ), + 'zero with no integer part' => array( '.0', true ), + 'zero with an exponent' => array( '0e3', true ), + 'zero with a negative exponent' => array( '-0.00E-5', true ), + 'zero with leading zeros' => array( '000', true ), + 'number other than 0' => array( '10', false ), + 'number with a zero exponent' => array( '1e0', false ), + 'number that underflows a float' => array( '1e-400', false ), + 'zero point one' => array( '0.1', false ), + 'percentage' => array( '50%', false ), + 'zero percent' => array( '0%', false ), + 'angle' => array( '5deg', false ), + 'resolution' => array( '1dppx', false ), + 'flex' => array( '1fr', false ), + 'unit with a suffix' => array( '1pxx', false ), + 'fullwidth unit' => array( "1\u{FF50}\u{FF58}", false ), + 'ident' => array( 'px', false ), + 'function' => array( 'calc(', false ), + ); + } + + /** + * Returns the token of CSS that tokenizes as exactly one token. + * + * @param string $css CSS of one token. + * @return WP_CSS_Token The token. + */ + private static function get_only_token( string $css ): WP_CSS_Token { + $processor = new WP_CSS_Token_Processor( $css ); + self::assertTrue( $processor->next_token(), 'The CSS must have a token.' ); + $token = $processor->get_token(); + self::assertFalse( $processor->next_token(), 'The CSS must have only one token.' ); + + return $token; + } }