Grid: Rotate manual grid items from the canvas

backport-changelog/7.3/15408.md

@@ -0,0 +1,3 @@
+https://github.com/WordPress/wordpress-develop/pull/15408
+
+* https://github.com/WordPress/gutenberg/pull/86240

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

@@ -261,6 +261,9 @@ The settings section has the following structure:
 			},
 			"spacingSizes": []
 		},
+		"transform": {
+			"rotate": true
+		},
 		"typography": {
 			"customFontSize": true,
 			"dropCap": true,

docs/reference-guides/block-api/block-supports.md

@@ -1093,6 +1093,43 @@ supports: {
 }
 ```
 
+## transform
+
+_**Note:** Since WordPress 7.3._
+
+-   Type: `Object`
+-   Default value: `null`
+-   Subproperties:
+    -   `rotate`: type `boolean`, default value `false`
+
+This value signals that a block supports some of the CSS transform properties. When it does, the block editor shows UI controls for the user to set their values in a Transform panel, if the theme allows it with `settings.transform.rotate`, which is `true` by default.
+
+Each feature is output as its own CSS property, such as `rotate`, and never as the `transform` shorthand. This way a rotation combines with any `transform` a theme or block already applies.
+
+```js
+supports: {
+	transform: {
+		rotate: true, // Enable the rotation control.
+	}
+}
+```
+
+The rotation is applied to the block wrapper. A block can apply it to an inner element instead with a `transform` [feature selector](/docs/reference-guides/block-api/block-selectors.md), for example `.wp-block-image img`. A block that applies the rotation itself can opt out of its output with `__experimentalSkipSerialization`.
+
+When a block declares support for a specific transform property, its attributes definition is extended to include the `style` attribute.
+
+-   `style`: an attribute of `object` type with no default assigned. This is added when `rotate` support is declared. It stores the custom values set by the user. A rotation is a single CSS angle, such as `15deg`, `-0.1turn`, `1rad` or `100grad`. For example:
+
+```js
+attributes: {
+    style: {
+        transform: {
+            rotate: "15deg",
+        }
+    }
+}
+```
+
 ## typography
 
 -   Type: `Object`

docs/reference-guides/core-blocks/README.md

@@ -366,7 +366,7 @@ Gather blocks in a layout container.
 
 -	**Name:** [core/group](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-group/)
 -	**Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/)
--	**Supports:** align (full, wide), allowedBlocks, anchor, ariaLabel, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), layout (allowSizingOnChildren), position (sticky), shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight, textColumns), ~~html~~
+-	**Supports:** align (full, wide), allowedBlocks, anchor, ariaLabel, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), layout (allowSizingOnChildren), position (sticky), shadow, spacing (blockGap, margin, padding), transform (rotate), typography (fontSize, lineHeight, textColumns), ~~html~~
 -	**Attributes:** tagName, templateLock
 
 ## Heading
@@ -375,7 +375,7 @@ Introduce new sections and organize content to help visitors (and search engines
 
 -	**Name:** [core/heading](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-heading/)
 -	**Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/)
--	**Supports:** __unstablePasteTextInline, align (full, wide), anchor, background (backgroundClip, backgroundImage, backgroundSize, gradient), className, color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), splitting, typography (fitText, fontSize, lineHeight, textAlign, textIndent, textShadow)
+-	**Supports:** __unstablePasteTextInline, align (full, wide), anchor, background (backgroundClip, backgroundImage, backgroundSize, gradient), className, color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), splitting, transform (rotate), typography (fitText, fontSize, lineHeight, textAlign, textIndent, textShadow)
 -	**Attributes:** content, level, levelOptions, placeholder
 
 ## Home Link
@@ -412,7 +412,7 @@ Insert an image to make a visual statement.
 
 -	**Name:** [core/image](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/core-block-image/)
 -	**Category:** [media](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/)
--	**Supports:** align (center, full, left, right, wide), anchor, color (~~background~~, ~~text~~), filter (duotone), interactivity, shadow, spacing (margin)
+-	**Supports:** align (center, full, left, right, wide), anchor, color (~~background~~, ~~text~~), filter (duotone), interactivity, shadow, spacing (margin), transform (rotate)
 -	**Attributes:** alt, aspectRatio, blob, caption, focalPoint, height, href, id, isDecorative, lightbox, linkClass, linkDestination, linkTarget, rel, scale, sizeSlug, title, url, width
 
 ## Latest Comments
@@ -1099,7 +1099,7 @@ Embed a video from your media library or upload a new one.
 
 -	**Name:** [core/video](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/core-block-video/)
 -	**Category:** [media](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/)
--	**Supports:** align, anchor, dimensions (minHeight, minWidth), filter (duotone), interactivity (clientNavigation, interactive), shadow, spacing (margin, padding)
+-	**Supports:** align, anchor, dimensions (minHeight, minWidth), filter (duotone), interactivity (clientNavigation, interactive), shadow, spacing (margin, padding), transform (rotate)
 -	**Attributes:** autoplay, blob, caption, controls, height, id, loop, muted, playsInline, poster, preload, src, tracks, width
 
 <!-- END TOKEN Autogenerated - DO NOT EDIT -->

docs/reference-guides/theme-json-reference/styles-versions.md

@@ -69,3 +69,4 @@ New styles options are integrated into theme.json on a regular basis. Knowing th
 | `outline.width`                   |       6.2        |        N/A         |
 | `filter.duotone`                  |       5.9        |        N/A         |
 | `shadow`                          |       6.1        |        6.2         |
+| `transform.rotate`                |       7.3        |        7.3         |

docs/reference-guides/theme-json-reference/theme-json-living.md

@@ -193,6 +193,16 @@ Settings related to spacing.
 
 ---
 
+### transform
+
+Settings related to transforms.
+
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| rotate | Allow users to set a rotation. | `boolean` | `true` |
+
+---
+
 ### typography
 
 Settings related to typography.
@@ -349,6 +359,16 @@ Spacing styles.
 
 ---
 
+### transform
+
+Transform styles. Only blocks and block style variations support them.
+
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| rotate | Sets the `rotate` CSS property. Accepts a single angle, such as `15deg` or `0.25turn`. | `string` |
+
+---
+
 ### typography
 
 Typography styles.

lib/block-supports/layout.php

@@ -1467,10 +1467,10 @@ function gutenberg_render_layout_support_flag( $block_content, $block ) {
 		/*
 		 * Manual placement grids stack their children on mobile, as part of the grid
 		 * interactivity experiment, when they opt in with `stackOnMobile: true`: each
-		 * child becomes full width, in block order, and spans the rows it publishes as
-		 * `--wp--grid-item--row-span`. Stacked rows are as tall as their content, so the span
-		 * doesn't make blocks taller; it keeps the rows numbered like the editor's stacked
-		 * layouts. The selector is repeated so that the rules beat the grid's and each
+		 * child becomes full width, in block order, and unrotated, and spans the rows it
+		 * publishes as `--wp--grid-item--row-span`. Stacked rows are as tall as their content,
+		 * so the span doesn't make blocks taller; it keeps the rows numbered like the editor's
+		 * stacked layouts. The selector is repeated so that the rules beat the grid's and each
 		 * child's own rules, whatever order the stylesheets end up in.
 		 */
 		$mobile_media_query = $responsive_media_queries['@mobile'] ?? null;
@@ -1487,11 +1487,23 @@ function gutenberg_render_layout_support_flag( $block_content, $block ) {
 			$has_grid_interactivity
 		) {
 			// Stacked blocks are sized by their content again, so their cells are no longer fixed.
+			$stacking_selector = ".$container_class.$container_class";
+			/*
+			 * The transform block support rotates blocks with an inline style, and its
+			 * state rules are important, so unrotating the stacked blocks is important too.
+			 */
+			$stacked_child_declarations = new WP_Style_Engine_CSS_Declarations_Gutenberg(
+				array(
+					'grid-column' => '1 / -1',
+					'grid-row'    => 'span var(--wp--grid-item--row-span, 1)',
+				)
+			);
+			$stacked_child_declarations->add_declaration( 'rotate', '0deg', array( 'important' => true ) );
 			$stacking_styles = gutenberg_style_engine_get_stylesheet_from_css_rules(
 				array(
 					array(
 						'rules_group'  => $mobile_media_query,
-						'selector'     => ".$container_class.$container_class",
+						'selector'     => $stacking_selector,
 						'declarations' => array(
 							'aspect-ratio'            => 'auto',
 							'grid-template-rows'      => 'none',
@@ -1501,11 +1513,8 @@ function gutenberg_render_layout_support_flag( $block_content, $block ) {
 					),
 					array(
 						'rules_group'  => $mobile_media_query,
-						'selector'     => ".$container_class.$container_class > *",
-						'declarations' => array(
-							'grid-column' => '1 / -1',
-							'grid-row'    => 'span var(--wp--grid-item--row-span, 1)',
-						),
+						'selector'     => "$stacking_selector > *",
+						'declarations' => $stacked_child_declarations,
 					),
 				),
 				array(

lib/block-supports/transform.php

@@ -0,0 +1,138 @@
+<?php
+/**
+ * Transform block support flag.
+ *
+ * Each transform feature outputs its own individual CSS property, such as
+ * `rotate`, never the `transform` shorthand, so features combine with each
+ * other and with any transform a block already applies.
+ *
+ * @package gutenberg
+ */
+
+/**
+ * Registers the style block attribute for block types that support it.
+ *
+ * @param WP_Block_Type $block_type Block Type.
+ */
+function gutenberg_register_transform_support( $block_type ) {
+	if ( ! $block_type->attributes ) {
+		$block_type->attributes = array();
+	}
+
+	// Check for existing style attribute definition e.g. from block.json.
+	if ( array_key_exists( 'style', $block_type->attributes ) ) {
+		return;
+	}
+
+	if ( block_has_support( $block_type, 'transform', false ) ) {
+		$block_type->attributes['style'] = array(
+			'type' => 'object',
+		);
+	}
+}
+
+/**
+ * Renders a block's transform styles.
+ *
+ * Features are output as inline styles on the block wrapper. When the block
+ * has a transform feature selector, e.g. `.wp-block-image img`, they are
+ * output instead to the block supports stylesheet under that selector, so the
+ * wrapper and anything else in it, such as a caption, are left as they are.
+ * A feature that skips serialization is left for the block to apply.
+ *
+ * State styles, such as `:hover` or `@mobile`, are rendered by the block
+ * states support.
+ *
+ * @param string $block_content Rendered block content.
+ * @param array  $block         Block object.
+ * @return string Filtered block content.
+ */
+function gutenberg_render_transform_support( $block_content, $block ) {
+	if ( empty( $block_content ) || empty( $block['blockName'] ) ) {
+		return $block_content;
+	}
+
+	$transform = $block['attrs']['style']['transform'] ?? null;
+	if ( empty( $transform ) || ! is_array( $transform ) ) {
+		return $block_content;
+	}
+
+	$block_type = WP_Block_Type_Registry::get_instance()->get_registered( $block['blockName'] );
+	if ( ! $block_type || ! block_has_support( $block_type, 'transform', false ) ) {
+		return $block_content;
+	}
+
+	$inline_styles   = array();
+	$selector_styles = array();
+
+	foreach ( array( 'rotate' ) as $feature ) {
+		if (
+			! isset( $transform[ $feature ] ) ||
+			! block_has_support( $block_type, array( 'transform', $feature ), false ) ||
+			wp_should_skip_block_supports_serialization( $block_type, 'transform', $feature )
+		) {
+			continue;
+		}
+
+		$selector = wp_get_block_css_selector( $block_type, array( 'transform', $feature ) ) ?? wp_get_block_css_selector( $block_type, 'transform' );
+		if ( $selector ) {
+			$selector_styles[ $selector ][ $feature ] = $transform[ $feature ];
+		} else {
+			$inline_styles[ $feature ] = $transform[ $feature ];
+		}
+	}
+
+	$processor = new WP_HTML_Tag_Processor( $block_content );
+	if ( ! $processor->next_tag() ) {
+		return $block_content;
+	}
+
+	$inline_css = gutenberg_style_engine_get_styles( array( 'transform' => $inline_styles ) )['css'] ?? '';
+	if ( ! empty( $inline_css ) ) {
+		$existing_style = $processor->get_attribute( 'style' );
+		$existing_style = is_string( $existing_style ) && '' !== trim( $existing_style ) ? rtrim( trim( $existing_style ), ';' ) . ';' : '';
+		$processor->set_attribute( 'style', $existing_style . $inline_css );
+	}
+
+	$css_rules = array();
+	foreach ( $selector_styles as $selector => $styles ) {
+		$declarations = gutenberg_style_engine_get_styles( array( 'transform' => $styles ) )['declarations'] ?? array();
+		if ( ! empty( $declarations ) ) {
+			$css_rules[] = array(
+				'selector'     => $selector,
+				'declarations' => $declarations,
+			);
+		}
+	}
+
+	if ( ! empty( $css_rules ) ) {
+		$class_name = wp_unique_id_from_values( $css_rules, 'wp-transform-' );
+		foreach ( $css_rules as $index => $css_rule ) {
+			$css_rules[ $index ]['selector'] = gutenberg_build_state_selector( ".$class_name", $css_rule['selector'], '', $block['blockName'] );
+		}
+
+		gutenberg_style_engine_get_stylesheet_from_css_rules(
+			$css_rules,
+			array(
+				'context'  => 'block-supports',
+				'prettify' => false,
+			)
+		);
+		$processor->add_class( $class_name );
+	}
+
+	return $processor->get_updated_html();
+}
+
+// Register the block support.
+WP_Block_Supports::get_instance()->register(
+	'transform',
+	array(
+		'register_attribute' => 'gutenberg_register_transform_support',
+	)
+);
+
+if ( function_exists( 'wp_render_transform_support' ) ) {
+	remove_filter( 'render_block', 'wp_render_transform_support' );
+}
+add_filter( 'render_block', 'gutenberg_render_transform_support', 10, 2 );