Flexible Content: group layouts by category in the Add Layout menu

assets/src/sass/pro/acf-pro-field-group.scss

@@ -109,7 +109,8 @@
 }
 .acf-field-setting-fc_layout .acf-fc-meta .acf-fc-meta-label .acf-input-prepend,
 .acf-field-setting-fc_layout .acf-fc-meta .acf-fc-meta-name .acf-input-prepend,
-.acf-field-setting-fc_layout .acf-fc-meta .acf-fc-meta-display .acf-input-prepend {
+.acf-field-setting-fc_layout .acf-fc-meta .acf-fc-meta-display .acf-input-prepend,
+.acf-field-setting-fc_layout .acf-fc-meta .acf-fc-meta-category .acf-input-prepend {
   min-width: 60px;
 }
 .acf-field-setting-fc_layout .acf-fc_draggable,

assets/src/sass/pro/acf-pro-input.scss

@@ -690,6 +690,21 @@ body:not(.block-editor-page) .acf-flexible-content .layout.active-layout>.acf-ta
   background: transparent;
 }
 
+.acf-fc-popup li.acf-fc-popup-category {
+  height: auto;
+  padding: 10px 0 4px;
+  color: #667085;
+  font-size: 11px;
+  font-weight: 500;
+  text-transform: uppercase;
+  cursor: default;
+}
+
+.acf-fc-popup li.acf-fc-popup-category:not(:first-child) {
+  border-top: 1px solid #eaecf0;
+  margin-top: 4px;
+}
+
 .acf-fc-popup a:focus {
   box-shadow: 0 0 0 var(--wp-admin-border-width-focus) var(--wp-components-color-accent, var(--wp-admin-theme-color, #3858e9));
   border-radius: 4px

docs/features/field/flexible-content/index.md

@@ -16,3 +16,4 @@ The Flexible Content field provides a flexible content builder interface. It all
 - Button Label - Customize the "Add Row" text
 - Min/Max Layouts - Limit number of blocks
 - Layout Settings - Configure each layout type
+- Layout Category - Optional. Layouts with the same category are grouped under a heading in the "Add Layout" menu

includes/fields/FlexibleContent/Render.php

@@ -227,17 +227,30 @@ private function actions( string $which = '' ) {
 	 * @return void
 	 */
 	private function add_layout_menu() {
-		echo '<script type="text-html" class="tmpl-popup"><ul>';
+		// Layouts without a category stay at the top, categories keep the order of their first layout.
+		$groups = array( '' => array() );
 		foreach ( $this->layouts as $layout ) {
-			$safe_label = acf_esc_html( $layout['label'] );
-			$atts       = array(
-				'href'        => '#',
-				'data-layout' => $layout['name'],
-				'data-min'    => $layout['min'],
-				'data-max'    => $layout['max'],
-				'title'       => $safe_label,
-			);
-			printf( '<li><a %s>%s</a></li>', acf_esc_attrs( $atts ), $safe_label ); //phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- escaped above.
+			$category              = isset( $layout['category'] ) ? trim( (string) $layout['category'] ) : '';
+			$groups[ $category ][] = $layout;
+		}
+
+		echo '<script type="text-html" class="tmpl-popup"><ul>';
+		foreach ( $groups as $category => $layouts ) {
+			if ( '' !== $category ) {
+				echo '<li class="acf-fc-popup-category">' . esc_html( (string) $category ) . '</li>';
+			}
+
+			foreach ( $layouts as $layout ) {
+				$safe_label = acf_esc_html( $layout['label'] );
+				$atts       = array(
+					'href'        => '#',
+					'data-layout' => $layout['name'],
+					'data-min'    => $layout['min'],
+					'data-max'    => $layout['max'],
+					'title'       => $safe_label,
+				);
+				printf( '<li><a %s>%s</a></li>', acf_esc_attrs( $atts ), $safe_label ); //phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- escaped above.
+			}
 		}
 		echo '</ul></script>';
 	}

includes/fields/class-acf-field-flexible-content.php

@@ -147,6 +147,7 @@ public function get_valid_layout( $layout = array() ) {
 					'sub_fields' => array(),
 					'min'        => '',
 					'max'        => '',
+					'category'   => '',
 				)
 			);
 
@@ -464,6 +465,22 @@ public function render_field_settings( $field ) {
 							)
 						);
 
+						?>
+					</li>
+					<li class="acf-fc-meta-category acf-fc-meta-left">
+						<?php
+
+						acf_render_field(
+							array(
+								'type'        => 'text',
+								'name'        => 'category',
+								'prefix'      => $layout_prefix,
+								'value'       => $layout['category'],
+								'prepend'     => __( 'Category', 'secure-custom-fields' ),
+								'placeholder' => __( 'Optional', 'secure-custom-fields' ),
+							)
+						);
+
 						?>
 					</li>
 				</ul>
@@ -1575,6 +1592,10 @@ public function translate_field( $field ) {
 			if ( ! empty( $field['layouts'] ) ) {
 				foreach ( $field['layouts'] as &$layout ) {
 					$layout['label'] = acf_translate( $layout['label'] );
+
+					if ( ! empty( $layout['category'] ) ) {
+						$layout['category'] = acf_translate( $layout['category'] );
+					}
 				}
 			}
 

schemas/fields/v1/flexible_content.json

@@ -93,7 +93,7 @@
         },
         "layouts": {
             "type": "array",
-            "description": "Array of layout configuration objects. Each layout represents a different content structure that editors can choose from. Each layout object should have: \"label\" (display name), \"name\" (machine name), \"sub_fields\" (array of field objects for this layout), \"display\" (layout style: \"table\", \"block\", or \"row\"), \"min\" (minimum instances of this layout), and \"max\" (maximum instances of this layout).",
+            "description": "Array of layout configuration objects. Each layout represents a different content structure that editors can choose from. Each layout object should have: \"label\" (display name), \"name\" (machine name), \"sub_fields\" (array of field objects for this layout), \"display\" (layout style: \"table\", \"block\", or \"row\"), \"min\" (minimum instances of this layout), \"max\" (maximum instances of this layout), and optionally \"category\" (groups the layout under a heading in the add layout menu).",
             "items": {
                 "type": "object"
             },

tests/php/includes/fields/test-class-acf-field-flexible-content.php

@@ -423,4 +423,104 @@ public function test_prepare_field_for_import() {
 
 		$this->assertIsArray( $imported );
 	}
+
+	/**
+	 * Test get_valid_layout adds an empty category by default.
+	 */
+	public function test_get_valid_layout_default_category() {
+		$layout = $this->field_instance->get_valid_layout( array( 'name' => 'custom' ) );
+
+		$this->assertArrayHasKey( 'category', $layout );
+		$this->assertSame( '', $layout['category'] );
+	}
+
+	/**
+	 * Get the add layout menu HTML for a list of layouts.
+	 *
+	 * @param array $layouts Layouts as name => category.
+	 * @return string
+	 */
+	protected function get_add_layout_menu_html( $layouts ) {
+		$field = $this->get_field(
+			array(
+				'button_label' => 'Add Row',
+				'value'        => array(),
+				'layouts'      => array(),
+			)
+		);
+
+		foreach ( $layouts as $name => $category ) {
+			$field['layouts'][] = $this->field_instance->get_valid_layout(
+				array(
+					'name'     => $name,
+					'label'    => ucfirst( $name ),
+					'category' => $category,
+				)
+			);
+		}
+
+		$render = new \SCF\Fields\FlexibleContent\Render( $field, array() );
+		$method = new ReflectionMethod( $render, 'add_layout_menu' );
+		$method->setAccessible( true );
+
+		ob_start();
+		$method->invoke( $render );
+		return ob_get_clean();
+	}
+
+	/**
+	 * Test add layout menu stays flat when no layout has a category.
+	 */
+	public function test_add_layout_menu_without_categories() {
+		$html = $this->get_add_layout_menu_html(
+			array(
+				'text'  => '',
+				'image' => '',
+			)
+		);
+
+		$this->assertStringNotContainsString( 'acf-fc-popup-category', $html );
+		$this->assertSame( 2, substr_count( $html, 'data-layout=' ) );
+		$this->assertLessThan( strpos( $html, 'data-layout="image"' ), strpos( $html, 'data-layout="text"' ) );
+	}
+
+	/**
+	 * Test add layout menu groups layouts by category.
+	 */
+	public function test_add_layout_menu_groups_by_category() {
+		$html = $this->get_add_layout_menu_html(
+			array(
+				'image'   => 'Media',
+				'note'    => '',
+				'quote'   => 'Text',
+				'gallery' => 'Media',
+			)
+		);
+
+		preg_match_all( '/class="acf-fc-popup-category">([^<]*)<|data-layout="([^"]*)"/', $html, $matches, PREG_SET_ORDER );
+		$order = array_map(
+			function ( $found ) {
+				return ! empty( $found[2] ) ? $found[2] : 'category:' . $found[1];
+			},
+			$matches
+		);
+
+		$this->assertSame(
+			array( 'note', 'category:Media', 'image', 'gallery', 'category:Text', 'quote' ),
+			$order
+		);
+	}
+
+	/**
+	 * Test add layout menu escapes the category heading.
+	 */
+	public function test_add_layout_menu_escapes_category() {
+		$html = $this->get_add_layout_menu_html(
+			array(
+				'text' => '<img src=x onerror=alert(1)>',
+			)
+		);
+
+		$this->assertStringNotContainsString( '<img', $html );
+	}
 }