@wordpress/global-styles-engine 1.17.0 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/global-styles-engine",
-	"version": "1.17.0",
+	"version": "1.18.0",
 	"description": "Pure CSS generation engine for WordPress global styles.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -42,10 +42,11 @@
 	"types": "build-types/index.d.ts",
 	"sideEffects": false,
 	"dependencies": {
-		"@wordpress/blocks": "^15.23.0",
-		"@wordpress/data": "^10.50.0",
-		"@wordpress/i18n": "^6.23.0",
-		"@wordpress/style-engine": "^2.50.0",
+		"@wordpress/blocks": "^15.24.0",
+		"@wordpress/data": "^10.51.0",
+		"@wordpress/i18n": "^6.24.0",
+		"@wordpress/private-apis": "^1.51.0",
+		"@wordpress/style-engine": "^2.51.0",
 		"colord": "^2.9.3",
 		"deepmerge": "^4.3.1",
 		"fast-deep-equal": "^3.1.3",
@@ -59,5 +60,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "fee6e24e8e63d36f6bbcf487c193461e9bd79753"
+	"gitHead": "e9a74f9c14095a34398ecd4d1f7a908e55051205"
 }

package/src/core/render.tsx

@@ -34,6 +34,7 @@ import { getGapCSSValue } from '../utils/gap';
 import { setBackgroundStyleDefaults } from '../utils/background';
 import { LAYOUT_DEFINITIONS } from '../utils/layout';
 import { getValueFromObjectPath, setImmutably } from '../utils/object';
+import { getResponsiveMediaQueries } from '../utils/viewport';
 import { getSetting } from '../settings/get-setting';
 import type { GlobalStylesConfig, GlobalStylesStyles } from '../types';
 import { normalizeStyleStateAliases } from '../style-state-back-compat';
@@ -228,15 +229,6 @@ const VALID_ELEMENT_PSEUDO_SELECTORS: Record< string, string[] > = {
 	],
 };
 
-/**
- * Responsive breakpoint state keys and their corresponding CSS media queries.
- * Keep in sync with WP_Theme_JSON_Gutenberg::RESPONSIVE_BREAKPOINTS.
- */
-const RESPONSIVE_BREAKPOINTS: Record< string, string > = {
-	'@mobile': '@media (width <= 480px)',
-	'@tablet': '@media (480px < width <= 782px)',
-};
-
 /**
  * Transform given preset tree into a set of preset class declarations.
  *
@@ -913,13 +905,21 @@ const STYLE_KEYS = [
 	'background',
 ];
 
-function pickStyleKeys( treeToPickFrom: any ): any {
-	return pickStyleAndPseudoKeys( treeToPickFrom );
+function pickStyleKeys(
+	treeToPickFrom: any,
+	responsiveMediaQueries: Record< string, string >
+): any {
+	return pickStyleAndPseudoKeys(
+		treeToPickFrom,
+		undefined,
+		responsiveMediaQueries
+	);
 }
 
 function pickStyleAndPseudoKeys(
 	treeToPickFrom: any,
-	blockName?: string
+	blockName: string | undefined,
+	responsiveMediaQueries: Record< string, string >
 ): any {
 	if ( ! treeToPickFrom ) {
 		return {};
@@ -933,7 +933,7 @@ function pickStyleAndPseudoKeys(
 		( [ key ] ) =>
 			STYLE_KEYS.includes( key ) ||
 			allowedPseudoSelectors.includes( key ) ||
-			RESPONSIVE_BREAKPOINTS[ key ]
+			responsiveMediaQueries[ key ]
 	);
 	// clone the style objects so that `getFeatureDeclarations` can remove consumed keys from it
 	const clonedEntries = pickedEntries.map( ( [ key, style ] ) => [
@@ -1001,14 +1001,22 @@ function getPseudoStyleNodes( node: StylesNode ): StylesNode[] {
  * Breakpoint nodes render feature-level, base, and pseudo declarations through
  * the normal node renderer.
  *
- * @param node Style node that may contain configured responsive state styles.
+ * @param node                   Style node that may contain configured responsive state styles.
+ * @param responsiveMediaQueries Media queries keyed by responsive state name.
  * @return Responsive style nodes in configured breakpoint order.
  */
-function getResponsiveStyleNodes( node: StylesNode ): StylesNode[] {
+function getResponsiveStyleNodes(
+	node: StylesNode,
+	responsiveMediaQueries: Record< string, string >
+): StylesNode[] {
 	const {
 		styles,
 		selector,
+		fallbackGapValue,
 		featureSelectors,
+		hasLayoutSupport,
+		layoutHasBlockGapSupport,
+		layoutSelector,
 		name,
 		elementName,
 		isStyleVariation,
@@ -1019,7 +1027,7 @@ function getResponsiveStyleNodes( node: StylesNode ): StylesNode[] {
 		return [];
 	}
 
-	return Object.entries( RESPONSIVE_BREAKPOINTS ).flatMap(
+	return Object.entries( responsiveMediaQueries ).flatMap(
 		( [ breakpointKey, mediaQuery ] ) => {
 			const breakpointStyles = styles?.[ breakpointKey ];
 			if ( ! breakpointStyles || typeof breakpointStyles !== 'object' ) {
@@ -1035,10 +1043,14 @@ function getResponsiveStyleNodes( node: StylesNode ): StylesNode[] {
 						featureSelectors && typeof featureSelectors !== 'string'
 							? featureSelectors
 							: undefined,
+					fallbackGapValue,
+					hasLayoutSupport,
 					name,
 					elementName,
 					isStyleVariation,
 					variationName,
+					layoutSelector,
+					layoutHasBlockGapSupport,
 				},
 			];
 		}
@@ -1055,8 +1067,10 @@ export const getNodesWithStyles = (
 		return nodes;
 	}
 
+	const responsiveMediaQueries = getResponsiveMediaQueries( tree );
+
 	// Top-level.
-	const styles = pickStyleKeys( tree.styles );
+	const styles = pickStyleKeys( tree.styles, responsiveMediaQueries );
 	if ( styles ) {
 		nodes.push( {
 			styles,
@@ -1085,7 +1099,11 @@ export const getNodesWithStyles = (
 	// Iterate over blocks: they can have styles & elements.
 	Object.entries( tree.styles?.blocks ?? {} ).forEach(
 		( [ blockName, node ] ) => {
-			const blockStyles = pickStyleAndPseudoKeys( node, blockName );
+			const blockStyles = pickStyleAndPseudoKeys(
+				node,
+				blockName,
+				responsiveMediaQueries
+			);
 			const typedNode = node as BlockNode;
 
 			// Store variation child nodes so they can be inserted after the block's own elements.
@@ -1098,7 +1116,8 @@ export const getNodesWithStyles = (
 						const typedVariation = variation as BlockVariation;
 						const variationStyles = pickStyleAndPseudoKeys(
 							typedVariation,
-							blockName
+							blockName,
+							responsiveMediaQueries
 						);
 						if ( typedVariation?.css ) {
 							variationStyles.css = typedVariation.css;
@@ -1193,7 +1212,8 @@ export const getNodesWithStyles = (
 								const variationBlockStyleNodes =
 									pickStyleAndPseudoKeys(
 										variationBlockStyles,
-										variationBlockName
+										variationBlockName,
+										responsiveMediaQueries
 									);
 
 								if ( variationBlockStyles?.css ) {
@@ -1757,12 +1777,16 @@ export const transformToStyles = (
 	}
 
 	if ( options.blockStyles ) {
+		const responsiveMediaQueries = getResponsiveMediaQueries( tree );
 		nodesWithStyles.forEach( ( node ) => {
 			if ( node.isStyleVariation && ! options.variationStyles ) {
 				return;
 			}
 
-			const responsiveNodes = getResponsiveStyleNodes( node );
+			const responsiveNodes = getResponsiveStyleNodes(
+				node,
+				responsiveMediaQueries
+			);
 			// Match PHP node order: base, responsive base, pseudo, responsive pseudo.
 			[
 				node,

package/src/index.ts

@@ -29,6 +29,7 @@ export {
 	getResolvedValue,
 	splitSelectorList,
 } from './utils/common';
+export { privateApis } from './private-apis';
 
 // Types
 export type * from './types';

package/src/lock-unlock.ts

@@ -0,0 +1,10 @@
+/**
+ * WordPress dependencies
+ */
+import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
+
+export const { lock, unlock } =
+	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
+		'I acknowledge private features are not for use in themes or plugins and doing so will break in the next version of WordPress.',
+		'@wordpress/global-styles-engine'
+	);

package/src/private-apis.ts

@@ -0,0 +1,16 @@
+/**
+ * Internal dependencies
+ */
+import {
+	getResponsiveMediaQueries,
+	getViewportBreakpoints,
+	getViewportBreakpointValueInPixels,
+} from './utils/viewport';
+import { lock } from './lock-unlock';
+
+export const privateApis = {};
+lock( privateApis, {
+	getResponsiveMediaQueries,
+	getViewportBreakpoints,
+	getViewportBreakpointValueInPixels,
+} );

package/src/settings/get-setting.ts

@@ -72,6 +72,8 @@ const VALID_SETTINGS = [
 	'typography.textIndent',
 	'typography.textTransform',
 	'typography.writingMode',
+	'viewport.mobile',
+	'viewport.tablet',
 ];
 
 export function getSetting< T = any >(

package/src/test/render.test.ts

@@ -1040,6 +1040,47 @@ describe( 'global styles renderer', () => {
 			);
 		} );
 
+		it( 'handles responsive block gap styles', () => {
+			const tree = {
+				styles: {
+					blocks: {
+						'core/group': {
+							'@mobile': {
+								spacing: {
+									blockGap: '24px',
+								},
+							},
+						},
+					},
+				},
+			} as unknown as GlobalStylesConfig;
+
+			const blockSelectors = {
+				'core/group': {
+					selector: '.wp-block-group',
+					hasLayoutSupport: true,
+				},
+			};
+
+			const result = transformToStyles(
+				Object.freeze( tree ),
+				blockSelectors,
+				true,
+				false,
+				false,
+				true,
+				minimalStyleOptions
+			);
+
+			expect( result ).toContain( '@media (width <= 480px)' );
+			expect( result ).toContain(
+				':root :where(.wp-block-group-is-layout-flow) > * { margin-block-start: 24px; margin-block-end: 0; }'
+			);
+			expect( result ).toContain(
+				':root :where(.wp-block-group-is-layout-flex) { gap: 24px; }'
+			);
+		} );
+
 		it( 'handles legacy responsive block styles', () => {
 			const tree = {
 				styles: {
@@ -1079,6 +1120,147 @@ describe( 'global styles renderer', () => {
 			);
 		} );
 
+		it( 'uses custom viewport breakpoints for responsive block styles', () => {
+			const tree = {
+				settings: {
+					viewport: {
+						mobile: '640px',
+						tablet: '960px',
+					},
+				},
+				styles: {
+					blocks: {
+						'core/button': {
+							'@mobile': {
+								color: {
+									text: 'blue',
+								},
+							},
+							'@tablet': {
+								color: {
+									text: 'green',
+								},
+							},
+						},
+					},
+				},
+			} as unknown as GlobalStylesConfig;
+
+			const blockSelectors = {
+				'core/button': {
+					selector: '.wp-block-button',
+				},
+			};
+
+			const result = transformToStyles(
+				Object.freeze( tree ),
+				blockSelectors,
+				false,
+				false,
+				true,
+				true,
+				minimalStyleOptions
+			);
+
+			expect( result ).toEqual(
+				'@media (width <= 640px){:root :where(.wp-block-button){color: blue;}}@media (640px < width <= 960px){:root :where(.wp-block-button){color: green;}}'
+			);
+		} );
+
+		it( 'omits tablet responsive styles when the tablet breakpoint is not larger than mobile', () => {
+			const tree = {
+				settings: {
+					viewport: {
+						mobile: '960px',
+						tablet: '640px',
+					},
+				},
+				styles: {
+					blocks: {
+						'core/button': {
+							'@mobile': {
+								color: {
+									text: 'blue',
+								},
+							},
+							'@tablet': {
+								color: {
+									text: 'green',
+								},
+							},
+						},
+					},
+				},
+			} as unknown as GlobalStylesConfig;
+
+			const blockSelectors = {
+				'core/button': {
+					selector: '.wp-block-button',
+				},
+			};
+
+			const result = transformToStyles(
+				Object.freeze( tree ),
+				blockSelectors,
+				false,
+				false,
+				true,
+				true,
+				minimalStyleOptions
+			);
+
+			expect( result ).toEqual(
+				'@media (width <= 960px){:root :where(.wp-block-button){color: blue;}}'
+			);
+		} );
+
+		it( 'uses a single max-width tablet query when only the tablet breakpoint is valid', () => {
+			const tree = {
+				settings: {
+					viewport: {
+						mobile: '100%',
+						tablet: '64rem',
+					},
+				},
+				styles: {
+					blocks: {
+						'core/button': {
+							'@mobile': {
+								color: {
+									text: 'blue',
+								},
+							},
+							'@tablet': {
+								color: {
+									text: 'green',
+								},
+							},
+						},
+					},
+				},
+			} as unknown as GlobalStylesConfig;
+
+			const blockSelectors = {
+				'core/button': {
+					selector: '.wp-block-button',
+				},
+			};
+
+			const result = transformToStyles(
+				Object.freeze( tree ),
+				blockSelectors,
+				false,
+				false,
+				true,
+				true,
+				minimalStyleOptions
+			);
+
+			expect( result ).toEqual(
+				'@media (width <= 64rem){:root :where(.wp-block-button){color: green;}}'
+			);
+		} );
+
 		it( 'handles responsive pseudo selector styles', () => {
 			const tree = {
 				styles: {

package/src/test/viewport-utils.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Internal dependencies
+ */
+import {
+	getResponsiveMediaQueries,
+	getViewportBreakpoints,
+	getViewportBreakpointValueInPixels,
+} from '../utils/viewport';
+
+describe( 'viewport utils', () => {
+	describe( 'getViewportBreakpointValueInPixels', () => {
+		it( 'returns numbers unchanged', () => {
+			expect( getViewportBreakpointValueInPixels( 640 ) ).toBe( 640 );
+		} );
+
+		it( 'returns pixel values as numbers', () => {
+			expect( getViewportBreakpointValueInPixels( '640px' ) ).toBe( 640 );
+		} );
+
+		it( 'converts em and rem values using a 16px base font size', () => {
+			expect( getViewportBreakpointValueInPixels( '40em' ) ).toBe( 640 );
+			expect( getViewportBreakpointValueInPixels( '64rem' ) ).toBe(
+				1024
+			);
+		} );
+
+		it( 'returns undefined for unsupported values', () => {
+			expect( getViewportBreakpointValueInPixels( undefined ) ).toBe(
+				undefined
+			);
+			expect( getViewportBreakpointValueInPixels( '100%' ) ).toBe(
+				undefined
+			);
+			expect( getViewportBreakpointValueInPixels( 'auto' ) ).toBe(
+				undefined
+			);
+		} );
+	} );
+
+	describe( 'getViewportBreakpoints', () => {
+		it( 'returns custom viewport breakpoints when they are ordered', () => {
+			expect(
+				getViewportBreakpoints( {
+					mobile: '40rem',
+					tablet: '64rem',
+				} )
+			).toEqual( {
+				mobile: '40rem',
+				tablet: '64rem',
+			} );
+		} );
+
+		it( 'returns default viewport breakpoints when no custom breakpoints are valid', () => {
+			expect(
+				getViewportBreakpoints( {
+					mobile: '100%',
+					tablet: 'auto',
+				} )
+			).toEqual( {
+				mobile: '480px',
+				tablet: '782px',
+			} );
+		} );
+
+		it( 'uses a valid custom breakpoint without merging defaults', () => {
+			const viewportSettings = {
+				mobile: ' 640px ',
+				tablet: 'calc(100% - 1rem)',
+				desktop: '1200px',
+			};
+
+			expect( getViewportBreakpoints( viewportSettings ) ).toEqual( {
+				mobile: '640px',
+			} );
+		} );
+
+		it( 'returns the configured viewport for a single breakpoint', () => {
+			expect(
+				getViewportBreakpoints( {
+					tablet: '64rem',
+				} )
+			).toEqual( {
+				tablet: '64rem',
+			} );
+		} );
+
+		it( 'preserves the tablet key when mobile is invalid', () => {
+			expect(
+				getViewportBreakpoints( {
+					mobile: '100%',
+					tablet: '64rem',
+				} )
+			).toEqual( {
+				tablet: '64rem',
+			} );
+		} );
+
+		it( 'omits tablet when it is not larger than mobile', () => {
+			expect(
+				getViewportBreakpoints( {
+					mobile: '64rem',
+					tablet: '40rem',
+				} )
+			).toEqual( {
+				mobile: '64rem',
+			} );
+		} );
+	} );
+
+	describe( 'getResponsiveMediaQueries', () => {
+		it( 'returns custom media queries when viewport breakpoints are ordered', () => {
+			expect(
+				getResponsiveMediaQueries( {
+					mobile: '640px',
+					tablet: '960px',
+				} )
+			).toEqual( {
+				'@mobile': '@media (width <= 640px)',
+				'@tablet': '@media (640px < width <= 960px)',
+			} );
+		} );
+
+		it( 'returns default media queries when no custom breakpoints are valid', () => {
+			expect(
+				getResponsiveMediaQueries( {
+					mobile: '100%',
+					tablet: 'auto',
+				} )
+			).toEqual( {
+				'@mobile': '@media (width <= 480px)',
+				'@tablet': '@media (480px < width <= 782px)',
+			} );
+		} );
+
+		it( 'uses a valid custom media query without merging defaults', () => {
+			expect(
+				getResponsiveMediaQueries( {
+					mobile: ' 640px ',
+					tablet: 'calc(100% - 1rem)',
+				} )
+			).toEqual( {
+				'@mobile': '@media (width <= 640px)',
+			} );
+		} );
+
+		it( 'uses a single max-width tablet media query when only tablet is valid', () => {
+			expect(
+				getResponsiveMediaQueries( {
+					mobile: '100%',
+					tablet: '64rem',
+				} )
+			).toEqual( {
+				'@tablet': '@media (width <= 64rem)',
+			} );
+		} );
+
+		it( 'omits the tablet media query when the tablet breakpoint is not larger than mobile', () => {
+			expect(
+				getResponsiveMediaQueries( {
+					mobile: '960px',
+					tablet: '640px',
+				} )
+			).toEqual( {
+				'@mobile': '@media (width <= 960px)',
+			} );
+		} );
+	} );
+} );

package/src/types.ts

@@ -193,6 +193,10 @@ export interface SpacingSettings {
  */
 export interface GlobalStylesSettings {
 	useRootPaddingAwareAlignments?: boolean;
+	viewport?: {
+		mobile?: string;
+		tablet?: string;
+	};
 	typography?: TypographySettings;
 	layout?: LayoutSettings;
 	spacing?: SpacingSettings;

package/src/utils/common.ts

@@ -317,14 +317,19 @@ export function getBlockStyleVariationSelector(
 		return variationClass;
 	}
 
-	const ancestorRegex = /((?::\([^)]+\))?\s*)([^\s:]+)/;
-	const addVariationClass = (
-		_match: string,
-		group1: string,
-		group2: string
-	) => {
-		return group1 + group2 + variationClass;
-	};
+	/*
+	 * Append the variation class to each selector's ancestor: the first run
+	 * of characters before any combinator (whitespace) or pseudo-class (`:`).
+	 * `String.prototype.replace` only replaces the first match.
+	 *
+	 * Examples ("custom" variation):
+	 * - `.wp-block`              => `.wp-block.is-style-custom`
+	 * - `.wp-block .inner`       => `.wp-block.is-style-custom .inner`
+	 * - `.wp-block:where(.a .b)` => `.wp-block.is-style-custom:where(.a .b)`
+	 * - `:where(.outer .inner)`  => `:where(.outer.is-style-custom .inner)`
+	 */
+	const ancestorRegex = /[^\s:]+/;
+	const addVariationClass = ( match: string ) => match + variationClass;
 
 	const result = splitSelectorList( blockSelector ).map( ( part ) =>
 		part.replace( ancestorRegex, addVariationClass )