@wordpress/global-styles-engine 1.17.1-next.v.202607070741.0 → 1.18.0

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/viewport.ts

@@ -0,0 +1,153 @@
+import type { GlobalStylesConfig } from '../types';
+
+const DEFAULT_VIEWPORT_BREAKPOINTS = {
+	mobile: '480px',
+	tablet: '782px',
+};
+
+type ViewportBreakpoint = keyof typeof DEFAULT_VIEWPORT_BREAKPOINTS;
+type ViewportSettings = Partial< Record< ViewportBreakpoint, string > >;
+type ViewportBreakpoints = Partial< Record< ViewportBreakpoint, string > >;
+
+// Matches positive CSS length values supported for viewport breakpoints, and
+// captures the numeric value and unit for conversion to pixels.
+const VIEWPORT_SIZE_REGEXP = /^(\d+|\d*\.\d+)(px|em|rem)$/;
+const DEFAULT_FONT_SIZE = 16;
+
+function isViewportSettings(
+	configOrSettings: GlobalStylesConfig | ViewportSettings
+): configOrSettings is ViewportSettings {
+	return 'mobile' in configOrSettings || 'tablet' in configOrSettings;
+}
+
+function getViewportSettings(
+	configOrSettings?: GlobalStylesConfig | ViewportSettings
+): ViewportSettings {
+	if ( ! configOrSettings || typeof configOrSettings !== 'object' ) {
+		return {};
+	}
+
+	if ( isViewportSettings( configOrSettings ) ) {
+		return configOrSettings;
+	}
+
+	return configOrSettings.settings?.viewport ?? {};
+}
+
+function isValidViewportSize( value: unknown ): value is string {
+	return (
+		typeof value === 'string' && VIEWPORT_SIZE_REGEXP.test( value.trim() )
+	);
+}
+
+/**
+ * Converts a viewport breakpoint value to pixels.
+ *
+ * Numeric values are returned as-is. CSS length values are only supported when
+ * expressed in px, em, or rem units.
+ *
+ * @param value Breakpoint value as a number or CSS length.
+ * @return The breakpoint value in pixels, or undefined when invalid.
+ */
+export function getViewportBreakpointValueInPixels(
+	value: number | string | undefined
+): number | undefined {
+	if ( typeof value === 'number' ) {
+		return value;
+	}
+
+	if ( typeof value !== 'string' ) {
+		return undefined;
+	}
+
+	const match = value.trim().match( VIEWPORT_SIZE_REGEXP );
+	if ( ! match ) {
+		return undefined;
+	}
+
+	const numericValue = Number.parseFloat( match[ 1 ] );
+	const unit = match[ 2 ];
+
+	// Use the most common browser default font size as the base for em/rem
+	// media query conversions. This pixel value is used to compare breakpoint
+	// order and calculate preview sizes; generated media queries keep the
+	// original units.
+	return unit === 'px' ? numericValue : numericValue * DEFAULT_FONT_SIZE;
+}
+
+/**
+ * Returns sanitized viewport breakpoints keyed by viewport state.
+ *
+ * Falls back to default breakpoints when no valid values are provided. If the
+ * mobile breakpoint is missing, a valid tablet breakpoint remains keyed as
+ * tablet so the editor can present it as a tablet breakpoint. If the tablet
+ * breakpoint is missing, invalid, or not larger than the mobile breakpoint, the
+ * result only includes the mobile breakpoint.
+ *
+ * @param configOrSettings Global styles config or viewport settings.
+ * @return Sanitized viewport breakpoints.
+ */
+export function getViewportBreakpoints(
+	configOrSettings?: GlobalStylesConfig | ViewportSettings
+): ViewportBreakpoints {
+	const viewportSettings = getViewportSettings( configOrSettings );
+	const breakpoints: ViewportBreakpoints = {};
+	const breakpointValuesInPixels: Partial<
+		Record< ViewportBreakpoint, number >
+	> = {};
+
+	Object.keys( DEFAULT_VIEWPORT_BREAKPOINTS ).forEach( ( breakpoint ) => {
+		const key = breakpoint as ViewportBreakpoint;
+		const value = viewportSettings[ key ];
+		const px = getViewportBreakpointValueInPixels( value );
+		if ( px !== undefined && isValidViewportSize( value ) ) {
+			breakpoints[ key ] = value.trim();
+			breakpointValuesInPixels[ key ] = px;
+		}
+	} );
+
+	const breakpointNames = Object.keys( breakpoints );
+	if ( ! breakpointNames.length ) {
+		return { ...DEFAULT_VIEWPORT_BREAKPOINTS };
+	}
+
+	if ( 1 === breakpointNames.length ) {
+		return breakpoints;
+	}
+
+	const mobile = breakpoints.mobile!;
+	const tablet = breakpoints.tablet!;
+	if (
+		breakpointValuesInPixels.mobile! >= breakpointValuesInPixels.tablet!
+	) {
+		return { mobile };
+	}
+
+	return { mobile, tablet };
+}
+
+/**
+ * Returns responsive media query aliases for the configured viewport
+ * breakpoints.
+ *
+ * @param configOrSettings Global styles config or viewport settings.
+ * @return Responsive media queries keyed by alias.
+ */
+export function getResponsiveMediaQueries(
+	configOrSettings?: GlobalStylesConfig | ViewportSettings
+): Record< string, string > {
+	const breakpoints = getViewportBreakpoints( configOrSettings );
+	const mediaQueries: Record< string, string > = {};
+
+	if ( breakpoints.mobile ) {
+		mediaQueries[ '@mobile' ] = `@media (width <= ${ breakpoints.mobile })`;
+	}
+
+	if ( breakpoints.tablet ) {
+		mediaQueries[ '@tablet' ] = breakpoints.mobile
+			? `@media (${ breakpoints.mobile } < width <= ${ breakpoints.tablet })`
+			: `@media (width <= ${ breakpoints.tablet })`;
+	}
+
+	return mediaQueries;
+}