customSpacingSize broken in my theme

[bgardner]

Description

Likely as a result of #61842, my custom spacing sizes are no longer working. My Powder theme (https://github.com/bgardner/powder/blob/main/theme.json#L146) uses t-shirt sizing method, per below (note my theme.json is currently "version": 2

"spacing": {
	"spacingSizes": [
		{
			"name": "xSmall",
			"size": "clamp(10px, 2vw, 20px)",
			"slug": "x-small"
		},
		{
			"name": "Small",
			"size": "clamp(30px, 4vw, 40px)",
			"slug": "small"
		},
		{
			"name": "Medium",
			"size": "clamp(40px, 6vw, 60px)",
			"slug": "medium"
		},
		{
			"name": "Large",
			"size": "clamp(50px, 8vw, 80px)",
			"slug": "large"
		},
		{
			"name": "xLarge",
			"size": "clamp(60px, 10vw, 100px)",
			"slug": "x-large"
		}
	],
	"units": [ "%", "px", "em", "rem", "vh", "vw" ]
}

With Gutenberg 18.5 RC1 active, numbers are now being used in areas such as padding, and the mapping is out of order:

1 = var(--wp--preset--spacing--large)
2 = var(--wp--preset--spacing--medium)
3 = var(--wp--preset--spacing--small)
4 = var(--wp--preset--spacing--x-large)
5= var(--wp--preset--spacing--x-small)

It appears my t-shirt sizing presets are being reordered by alpha in this scale. Expected behavior/output should be:

xSmall= var(--wp--preset--spacing--x-small)
Small = var(--wp--preset--spacing--small)
Medium = var(--wp--preset--spacing--medium)
Large = var(--wp--preset--spacing--large)
xLarge = var(--wp--preset--spacing--x-large)

Step-by-step reproduction instructions

1. Find a group and try applying padding.
2. Notice that the spacing scale is off.

Screenshots, screen recording, code snippet

Below is a before/after video of me applying padding to a group block. First instance is with WP 6.5.3 (Gutenberg not active) and the second instance is with WP 6.5.3 (Gutenberg 18.5 RC1 active)

Screen.Recording.2024-05-31.at.1.50.59.PM.mp4

Environment info

WordPress 6.5.3, Gutenberg 18.5 RC1

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

[bgardner]

Ping @MaggieCabrera @ajlende @ellatrix. And thanks @richtabor for your comment #61842 (comment).

[bgardner]

Similar report: #62195

[ajlende]

Likely as a result of #61842

Definitely a result of #61842.

There are a couple things going on here that cause it.

Sorting

The sorting was added to resolve an issue with presets being out of size order when merging default presets, spacingScale generated presets, and the custom spacingSizes presets in v3. The most reliable way to do that sorting was based on the slug.

According to the documentation, the slugs should be in the format 10, 50, etc. with the 50 slug representing Medium.

gutenberg/docs/how-to-guides/themes/global-settings-and-styles.md

Line 347 in ca4dbb8

- `slug`: the machine readable name. In order to provide the best cross site/theme compatibility the slugs should be in the format, "10","20","30","40","50","60", with "50" representing the `Medium` size value.

Examples in the Theme Handbook also support this format.

Expecting that folks may have wanted to include names, I made sure to allow strings like 5-xsmall and 10-small to be sorted correctly numerically even though the documentation didn't ever suggest adding names.

I should have assumed that other slugs would be added since none of the other presets have this requirement and it wasn't enforced in the code anywhere. It's one thing to have out of order named sizes in the dropdown, but it's definitely a problem in the slider with renaming applied.

Naming

The renaming in the UI to numbers in the slider was also to fix an issue of merging presets. With the merged presets, you'd end up with duplicate and incorrectly ordered numbers because the numbers didn't correspond to the slugs. You could have a generated preset with the "name": "1" and "slug": "20" from the default origin, but also "name": "1" and "slug": "10" from spacingScale in the theme origin if the range was set wider than the default.

The generated t-shirt sizes for names didn't have this problem because "name": "Medium" was always "slug": 50 and so on outwards from there to the limit.

The PR where names were switched to numbers was #44247 and there was some discussion in #44133 (comment) also that I found.

Since those discussions were about the UI, it seemed safe to move the renames to the UI so that proper names could be used elsewhere in the UI if we wanted. I think saw some mock-ups with names listed above the slider, but I can't seem to find it right now.

Solutions

Unfortunately at this point in the code, there isn't any way of knowing which version of the theme.json the source is coming from, so the solution that we come up with to make v2 work also has to work for the merged sizes in v3.

In the JS, we also don't have access to the spacingSizes configuration since the generated presets become part of spacingScale in the backend in order to generate the CSS custom properties.

The best solution I can come up with is sorting the merge of spacingScale and spacingSizes when they're generated on the backend. Then, on the frontend, only sort if there are presets from multiple origins. The drawback is that we have to use two different sorting algorithms one in JS and one in PHP that could result in different orders in some edge cases for the theme presets depending on if defaultSpacingSizes is true or we have user-level presets added (which can only be done by hand-editing the DB right now).

Are there other considerations I'm missing with that solution? Do you think that would satisfactorily solve the problem?