prep build 10/06 tag increase

docs/explanations/architecture/styles.md

@@ -2,19 +2,22 @@
 
 This document introduces the main concepts related to styles that affect the user content in the block editor. It points to the relevant reference guides and tutorials for readers to dig deeper into each one of the ideas presented. It's aimed to block authors and people working in the block editor project.
 
-1. HTML and CSS
-2. Block styles
-
--   From UI controls to HTML markup
--   Block Supports API
--   Current limits of the Block Supports API
-
-3. Global styles
-
--   Gather data
--   Consolidate data
--   From data to styles
--   Current limits of the Global styles API
+1. [HTML and CSS](#html-and-css)
+2. [Block styles](#block-styles)
+  - [From UI controls to HTML markup](#from-ui-controls-to-html-markup)
+  - [Block Supports API](#block-supports-api)
+  - [Current limitations of the Block Supports API](#current-limitations-of-the-block-supports-api)
+3. [Global styles](#global-styles)
+  - [Gather data](#gather-data)
+  - [Consolidate data](#consolidate-data)
+  - [From data to styles](#from-data-to-styles)
+  - [Current limitations of the Global Styles API](#current-limitations-of-the-global-styles-api)
+4. [Layout styles](#layout-styles)
+  - [Base layout styles](#base-layout-styles)
+  - [Individual layout styles](#individual-layout-styles)
+  - [Available layout types](#available-layout-types)
+  - [Targeting layout or container blocks from themes](#targeting-layout-or-container-blocks-from-themes)
+  - [Opting out of generated layout styles](#opting-out-of-generated-layout-styles)
 
 ### HTML and CSS
 
@@ -479,22 +482,87 @@ In addition to the CSS Custom Properties, all presets but duotone generate CSS c
 
 #### Current limitations of the Global Styles API
 
-1. **Setting a different CSS selector for blocks requires server-registration**
+##### 1. **Setting a different CSS selector for blocks requires server-registration**
 
 By default, the selector assigned to a block is `.wp-block-<block-name>`. However, blocks can change this should they need. They can provide a CSS selector via the `__experimentalSelector` property in its `block.json`.
 
 If blocks do this, they need to be registered in the server using the `block.json`, otherwise, the global styles code doesn't have access to that information and will use the default CSS selector for the block.
 
-2. **Can't target different HTML nodes for different styles**
+##### 2. **Can't target different HTML nodes for different styles**
 
 Every chunk of styles can only use a single selector.
 
 This is particularly relevant if the block is using `__experimentalSkipSerialization` to serialize the different style properties to different nodes other than the wrapper. See "Current limitations of blocks supports" for more.
 
-3. **Only a single property per block**
+##### 3. **Only a single property per block**
 
 Similarly to block supports, there can be only one instance of any style in use by the block. For example, the block can only have a single font size. See related "Current limitations of block supports".
 
-4. **Only blocks using block supports are shown in the Global Styles UI**
+##### 4. **Only blocks using block supports are shown in the Global Styles UI**
 
 The global styles UI in the site editor has a screen for per-block styles. The list of blocks is generated dynamically using the block supports from the `block.json` of blocks. If a block wants to be listed there, it needs to use the block supports mechanism.
+
+### Layout styles
+
+In addition to styles at the individual block level and in global styles, there is the concept of layout styles that are output for both blocks-based and classic themes.
+
+The layout block support is an experimental approach for outputting common layout styles that are shared between blocks that are used for creating layouts. Layout styles are useful for providing common styling for any block that is a container for other blocks. Examples of blocks that depend on these layout styles include Group, Row, Columns, Buttons, and Social Icons.
+
+While the feature is part of WordPress core, it is still flagged as experimental in the sense that the features and output are still undergoing active development. It is therefore not yet a stable feature from the perspective of 3rd party blocks, as the API is likely to change. The feature is enabled in core blocks via the `__experimentalLayout` setting under `supports` in a block's `block.json` file.
+
+There are two primary places where Layout styles are output:
+
+#### Base layout styles
+
+Base layout styles are those styles that are common to all blocks that opt in to a particular layout type. Examples of common base layout styling include setting `display: flex` for blocks that use the Flex layout type (such as Buttons and Social Icons), and providing default max-width for constrained layouts.
+
+Base layout styles are output from within [the main PHP class](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/class-wp-theme-json.php) that handles global styles, and form part of the global styles stylesheet. In order to provide support for core blocks in classic themes, these styles are always output, irrespective of whether the theme provides its own `theme.json` file.
+
+Common layout definitions are stored in [the core `theme.json` file](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/theme.json), but are not intended to be extended or overridden by themes.
+
+#### Individual layout styles
+
+When a block that opts in to the experimental layout support is rendered, two things are processed and added to the output via [`layout.php`](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/block-supports/layout.php):
+
+- Semantic class names are added to the block markup to indicate which layout settings are in use. For example, `is-layout-flow` is for blocks (such as Group) that use the default/flow layout, and `is-content-justification-right` is added when a user sets a block to use right justification.
+- Individual styles are generated for non-default layout values that are set on the individual block being rendered. These styles are attached to the block via a container class name using the form `wp-container-$id` where the `$id` is a [unique number](https://developer.wordpress.org/reference/functions/wp_unique_id/).
+
+#### Available layout types
+
+There are currently three layout types in use:
+
+* Default/Flow: Items are stacked vertically. The parent container block is set to `display: flow` and the spacing between children is handled via vertical margins.
+* Constrained: Items are stacked vertically, using the same spacing logic as the Flow layout. Features constrained widths for child content, outputting widths for standard content size and wide size. Defaults to using global `contentSize` and `wideSize` values set in `settings.layout` in the `theme.json`.
+* Flex: Items are displayed using a Flexbox layout. Defaults to a horizontal orientation. Spacing between children is handled via the `gap` CSS property.
+
+For controlling spacing between blocks, and enabling block spacing controls see: [What is blockGap and how can I use it?](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/#what-is-blockgap-and-how-can-i-use-it).
+
+#### Targeting layout or container blocks from themes
+
+The layout block support is designed to enable control over layout features from within the block and site editors. Where possible, try to use the features of the blocks to determine particular layout requirements rather than relying upon additional stylesheets.
+
+For themes that wish to target container blocks in order to add or adjust particular styles, the block's class name is often the best class name to use. Class names such as `wp-block-group` or `wp-block-columns` are usually reliable class names for targeting a particular block.
+
+For targeting a block that uses a particular layout type, avoid targeting `wp-container-` as container classes may not always be present in the rendered markup.
+
+##### Semantic class names
+
+Work is currently underway to expand stable semantic classnames in Layout block support output. The task is being discussed in [this issue](https://github.com/WordPress/gutenberg/issues/38719).
+
+The current semantic class names that can be output by the Layout block support are:
+
+* `is-layout-flow`: Blocks that use the Default/Flow layout type.
+* `is-layout-constrained`: Blocks that use the Constrained layout type.
+* `is-layout-flex`: Blocks that use the Flex layout type.
+* `wp-container-$id`: Where `$id` is a semi-random number. A container class that only exists when the block contains non-default Layout values. This class should not be used directly for any CSS targeting as it may or may not be present.
+* `is-horizontal`: When a block explicitly sets `orientation` to `horizontal`.
+* `is-vertical`: When a block explicitly sets `orientation` to `vertical`.
+* `is-content-justification-left`: When a block explicitly sets `justifyContent` to `left`.
+* `is-content-justification-center`: When a block explicitly sets `justifyContent` to `center`.
+* `is-content-justification-right`: When a block explicitly sets `justifyContent` to `right`.
+* `is-content-justification-space-between`: When a block explicitly sets `justifyContent` to `space-between`.
+* `is-nowrap`: When a block explicitly sets `flexWrap` to `nowrap`.
+
+#### Opting out of generated layout styles
+
+Layout styles output is switched on by default because the styles are required by core structural blocks. However, themes can opt out of generated block layout styles while retaining semantic class name output by using the `disable-layout-styles` block support. Such themes will be responsible for providing all their own layout styles. See [the entry under Theme Support](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#disabling-base-layout-styles).

docs/reference-guides/core-blocks.md

@@ -429,7 +429,7 @@ Display a list of all pages. ([Source](https://github.com/WordPress/gutenberg/tr
 -	**Name:** core/page-list
 -	**Category:** widgets
 -	**Supports:** ~~html~~, ~~reusable~~
--	**Attributes:** __unstableMaxPages
+-	**Attributes:** 
 
 ## Paragraph
 
@@ -797,7 +797,7 @@ A cloud of your most used tags. ([Source](https://github.com/WordPress/gutenberg
 
 -	**Name:** core/tag-cloud
 -	**Category:** widgets
--	**Supports:** align, spacing (margin, padding), ~~html~~
+-	**Supports:** align, spacing (margin, padding), typography (lineHeight), ~~html~~
 -	**Attributes:** largestFontSize, numberOfTags, showTagCounts, smallestFontSize, taxonomy
 
 ## Template Part

docs/reference-guides/data/data-core-block-editor.md

@@ -1191,10 +1191,6 @@ _Parameters_
 
 Action that hides the insertion point.
 
-_Returns_
-
--   `Object`: Action object.
-
 ### insertAfterBlock
 
 Action that inserts an empty block after a given block.

gutenberg.php

@@ -6,8 +6,13 @@
 
  * Requires at least: 5.9
  * Requires PHP: 5.6
+<<<<<<< HEAD
  * Version: 14.3.20221006
  * Author: Gutenberg Team and Birgit Pauli-Haack (Gutenberg Times)
+=======
+ * Version: 14.3.0-rc.1
+ * Author: Gutenberg Team
+>>>>>>> upstream/trunk
  * Text Domain: gutenberg
  * GitHub Plugin URI: bph/gutenberg
  * Primary Branch: trunk

lib/block-supports/layout.php

@@ -28,19 +28,20 @@ function gutenberg_register_layout_support( $block_type ) {
 /**
  * Generates the CSS corresponding to the provided layout.
  *
- * @param string  $selector                      CSS selector.
- * @param array   $layout                        Layout object. The one that is passed has already checked the existence of default block layout.
- * @param boolean $has_block_gap_support         Whether the theme has support for the block gap.
- * @param string  $gap_value                     The block gap value to apply.
- * @param boolean $should_skip_gap_serialization Whether to skip applying the user-defined value set in the editor.
- * @param string  $fallback_gap_value            The block gap value to apply.
- * @param array   $block_spacing                 Custom spacing set on the block.
- *
- * @return string                                CSS style.
+ * @param string               $selector                      CSS selector.
+ * @param array                $layout                        Layout object. The one that is passed has already checked
+ *                                                            the existence of default block layout.
+ * @param bool                 $has_block_gap_support         Optional. Whether the theme has support for the block gap. Default false.
+ * @param string|string[]|null $gap_value                     Optional. The block gap value to apply. Default null.
+ * @param bool                 $should_skip_gap_serialization Optional. Whether to skip applying the user-defined value set in the editor. Default false.
+ * @param string               $fallback_gap_value            Optional. The block gap value to apply. Default '0.5em'.
+ * @param array|null           $block_spacing                 Optional. Custom spacing set on the block. Default null.
+ * @return string CSS styles on success. Else, empty string.
  */
 function gutenberg_get_layout_style( $selector, $layout, $has_block_gap_support = false, $gap_value = null, $should_skip_gap_serialization = false, $fallback_gap_value = '0.5em', $block_spacing = null ) {
 	$layout_type   = isset( $layout['type'] ) ? $layout['type'] : 'default';
 	$layout_styles = array();
+
 	if ( 'default' === $layout_type ) {
 		if ( $has_block_gap_support ) {
 			if ( is_array( $gap_value ) ) {
@@ -117,8 +118,10 @@ function gutenberg_get_layout_style( $selector, $layout, $has_block_gap_support
 					)
 				);
 
-				// Handle negative margins for alignfull children of blocks with custom padding set.
-				// They're added separately because padding might only be set on one side.
+				/*
+				 * Handle negative margins for alignfull children of blocks with custom padding set.
+				 * They're added separately because padding might only be set on one side.
+				 */
 				if ( isset( $block_spacing_values['declarations']['padding-right'] ) ) {
 					$padding_right   = $block_spacing_values['declarations']['padding-right'];
 					$layout_styles[] = array(
@@ -232,7 +235,7 @@ function gutenberg_get_layout_style( $selector, $layout, $has_block_gap_support
 		}
 
 		if ( 'horizontal' === $layout_orientation ) {
-			/**
+			/*
 			 * Add this style only if is not empty for backwards compatibility,
 			 * since we intend to convert blocks that had flex layout implemented
 			 * by custom css.
@@ -270,13 +273,17 @@ function gutenberg_get_layout_style( $selector, $layout, $has_block_gap_support
 	}
 
 	if ( ! empty( $layout_styles ) ) {
-		// Add to the style engine store to enqueue and render layout styles.
-		// Return compiled layout styles to retain backwards compatibility.
-		// Since https://github.com/WordPress/gutenberg/pull/42452 we no longer call wp_enqueue_block_support_styles in this block supports file.
+		/*
+		 * Add to the style engine store to enqueue and render layout styles.
+		 * Return compiled layout styles to retain backwards compatibility.
+		 * Since https://github.com/WordPress/gutenberg/pull/42452,
+		 * wp_enqueue_block_support_styles is no longer called in this block supports file.
+		 */
 		return gutenberg_style_engine_get_stylesheet_from_css_rules(
 			$layout_styles,
 			array(
-				'context' => 'block-supports',
+				'context'  => 'block-supports',
+				'prettify' => false,
 			)
 		);
 	}
@@ -330,10 +337,12 @@ function gutenberg_render_layout_support_flag( $block_content, $block ) {
 		$class_names[] = 'has-global-padding';
 	}
 
-	// The following section was added to reintroduce a small set of layout classnames that were
-	// removed in the 5.9 release (https://github.com/WordPress/gutenberg/issues/38719). It is
-	// not intended to provide an extended set of classes to match all block layout attributes
-	// here.
+	/*
+	 * The following section was added to reintroduce a small set of layout classnames that were
+	 * removed in the 5.9 release (https://github.com/WordPress/gutenberg/issues/38719). It is
+	 * not intended to provide an extended set of classes to match all block layout attributes
+	 * here.
+	 */
 	if ( ! empty( $block['attrs']['layout']['orientation'] ) ) {
 		$class_names[] = 'is-' . sanitize_title( $block['attrs']['layout']['orientation'] );
 	}
@@ -357,14 +366,19 @@ function gutenberg_render_layout_support_flag( $block_content, $block ) {
 		$class_names[] = sanitize_title( $layout_classname );
 	}
 
-	// Only generate Layout styles if the theme has not opted-out.
-	// Attribute-based Layout classnames are output in all cases.
+	/*
+	 * Only generate Layout styles if the theme has not opted-out.
+	 * Attribute-based Layout classnames are output in all cases.
+	 */
 	if ( ! current_theme_supports( 'disable-layout-styles' ) ) {
 
 		$gap_value = _wp_array_get( $block, array( 'attrs', 'style', 'spacing', 'blockGap' ) );
-		// Skip if gap value contains unsupported characters.
-		// Regex for CSS value borrowed from `safecss_filter_attr`, and used here
-		// because we only want to match against the value, not the CSS attribute.
+
+		/*
+		 * Skip if gap value contains unsupported characters.
+		 * Regex for CSS value borrowed from `safecss_filter_attr`, and used here
+		 * to only match against the value, not the CSS attribute.
+		 */
 		if ( is_array( $gap_value ) ) {
 			foreach ( $gap_value as $key => $value ) {
 				$gap_value[ $key ] = $value && preg_match( '%[\\\(&=}]|/\*%', $value ) ? null : $value;
@@ -376,19 +390,32 @@ function gutenberg_render_layout_support_flag( $block_content, $block ) {
 		$fallback_gap_value = _wp_array_get( $block_type->supports, array( 'spacing', 'blockGap', '__experimentalDefault' ), '0.5em' );
 		$block_spacing      = _wp_array_get( $block, array( 'attrs', 'style', 'spacing' ), null );
 
-		// If a block's block.json skips serialization for spacing or spacing.blockGap,
-		// don't apply the user-defined value to the styles.
+		/*
+		 * If a block's block.json skips serialization for spacing or spacing.blockGap,
+		 * don't apply the user-defined value to the styles.
+		 */
 		$should_skip_gap_serialization = gutenberg_should_skip_block_supports_serialization( $block_type, 'spacing', 'blockGap' );
-		$style                         = gutenberg_get_layout_style( ".$block_classname.$container_class", $used_layout, $has_block_gap_support, $gap_value, $should_skip_gap_serialization, $fallback_gap_value, $block_spacing );
+
+		$style = gutenberg_get_layout_style(
+			".$block_classname.$container_class",
+			$used_layout,
+			$has_block_gap_support,
+			$gap_value,
+			$should_skip_gap_serialization,
+			$fallback_gap_value,
+			$block_spacing
+		);
 
 		// Only add container class and enqueue block support styles if unique styles were generated.
 		if ( ! empty( $style ) ) {
 			$class_names[] = $container_class;
 		}
 	}
 
-	// This assumes the hook only applies to blocks with a single wrapper.
-	// I think this is a reasonable limitation for that particular hook.
+	/*
+	 * This assumes the hook only applies to blocks with a single wrapper.
+	 * A limitation of this hook is that nested inner blocks wrappers are not yet supported.
+	 */
 	$content = preg_replace(
 		'/' . preg_quote( 'class="', '/' ) . '/',
 		'class="' . esc_attr( implode( ' ', $class_names ) ) . ' ',
@@ -429,7 +456,7 @@ function gutenberg_restore_group_inner_container( $block_content, $block ) {
 	if (
 		WP_Theme_JSON_Resolver_Gutenberg::theme_has_support() ||
 		1 === preg_match( $group_with_inner_container_regex, $block_content ) ||
-		( isset( $block['attrs']['layout']['type'] ) && 'default' !== $block['attrs']['layout']['type'] )
+		( isset( $block['attrs']['layout']['type'] ) && 'flex' === $block['attrs']['layout']['type'] )
 	) {
 		return $block_content;
 	}