Skip to content

CSS API: Add helpers for comma-separated lists - #98

Open
sirreal wants to merge 3 commits into
css-api/css-token-processor-foundationsfrom
css-api/comma-separated-lists
Open

sirreal wants to merge 3 commits into
css-api/css-token-processor-foundationsfrom
css-api/comma-separated-lists

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 two helpers to the CSS API for reading comma-separated values:

  • WP_CSS_Token::is_whitespace_or_comment() reports whether a token is whitespace or a comment. Most grammars allow both between component values, so every value reader skips them. The parser-based safecss_filter_attr() (KSES: Parse declarations in safecss_filter_attr() WordPress/wordpress-develop#14784) defines a private copy, _safecss_filter_attr_is_trivia().
  • WP_CSS_Token_Processor::parse_comma_separated_list( $css ) returns the tokens of each group between top-level commas. A comma inside a string, comment, escape, function, (), [] or {} block stays in its group.

Font family lists and selector lists are comma-separated, and core splits them with explode( ',' ) or with scanners that track some of these cases:

Input explode( ',' ) parse_comma_separated_list()
"Foo, Bar", serif "Foo, Bar", serif "Foo, Bar", serif
:is(a, b) img, c :is(a, b) img, c :is(a, b) img, c

The method follows the CSS Syntax 3 algorithm with one difference: a comma at the end of the input produces a final empty group. The font-family and selector grammars reject a trailing comma, and the algorithm's result does not show one. Blocks are not nested in the result; their tokens appear in order.

The font-family and selector-list alternatives stacked on this branch are the first consumers.

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.

Most CSS grammars allow whitespace and comments between component
values, so every consumer that reads a value skips both token types.
The parser-based safecss_filter_attr() defines its own helper for this,
and the font-family and selector-list consumers need the same test.
Font family lists, selector lists and several property values are
comma-separated lists of component values. Core splits them with
explode( ',' ) or with scanners that track some nesting, which split
inside strings, escapes, comments or blocks.

The method follows the CSS Syntax 3 algorithm and returns the tokens
of each group. A comma at the end of the input produces a final empty
group, which the algorithm omits, because the font-family and selector
grammars reject a trailing comma and a caller cannot otherwise detect
one. Blocks are not nested in the result; a caller that needs them
reads the function and bracket tokens in order.
@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.

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