Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 173 additions & 0 deletions src/wp-includes/css-api/class-wp-css-token.php
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand Down Expand Up @@ -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 `<length-percentage>`.
*
* 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.
*
Expand Down
116 changes: 116 additions & 0 deletions tests/phpunit/tests/css-api/wpCssToken.php
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
}