Content Guidelines: Add block guidelines management

lib/experimental/content-guidelines/load.php

@@ -6,6 +6,7 @@
  */
 
 add_action( 'admin_menu', 'gutenberg_register_content_guidelines_settings_submenu', 10 );
+add_action( 'admin_enqueue_scripts', 'gutenberg_content_guidelines_enqueue_block_registry_scripts', 5 );
 
 /**
  * Registers the Content Guidelines submenu item under Settings.
@@ -21,3 +22,22 @@ function gutenberg_register_content_guidelines_settings_submenu() {
 		'gutenberg_content_guidelines_wp_admin_render_page'
 	);
 }
+
+/**
+ * Enqueues wp-block-library on the Content Guidelines admin page so
+ * registerCoreBlocks() is available when the app bootstraps the block
+ * registry (Core blocks only) on the client.
+ *
+ * Priority 5 ensures this runs before the main asset enqueue (priority 10).
+ */
+function gutenberg_content_guidelines_enqueue_block_registry_scripts( $hook_suffix ) {
+	if ( ! current_user_can( 'manage_options' ) ) {
+		return;
+	}
+
+	if ( 'settings_page_content-guidelines-wp-admin' !== $hook_suffix ) {
+		return;
+	}
+
+	wp_enqueue_script( 'wp-block-library' );
+}

routes/content-guidelines/api.ts

@@ -3,14 +3,12 @@
  */
 import apiFetch from '@wordpress/api-fetch';
 import { dispatch, select } from '@wordpress/data';
-import { __ } from '@wordpress/i18n';
-import { store as noticesStore } from '@wordpress/notices';
 
 /**
  * Internal dependencies
  */
 import { STORE_NAME } from './store';
-import type { RestGuidelinesResponse } from './types';
+import type { Categories, RestGuidelinesResponse } from './types';
 
 export async function fetchContentGuidelines(): Promise< RestGuidelinesResponse > {
 	const { setFromResponse } = dispatch( STORE_NAME ) as {
@@ -30,16 +28,18 @@ export async function saveContentGuidelines(): Promise< RestGuidelinesResponse >
 	// @ts-ignore
 	const { setFromResponse } = dispatch( STORE_NAME );
 
-	const guidelinesStore = select( STORE_NAME ) as {
+	const guidelinesStore = select( STORE_NAME ) as unknown as {
 		getId: () => number | null;
 		getStatus: () => string | null;
-		getAllGuidelines: () => Partial< Record< string, string > >;
-		getGuideline: ( category: string ) => string;
+		getAllGuidelines: () => Categories;
+		getBlockGuidelines: () => Record< string, string >;
+		getGuideline: ( category: string ) => string | Record< string, string >;
 	};
 
 	const id = guidelinesStore.getId();
 	const status = guidelinesStore.getStatus() || 'draft';
 	const categories = guidelinesStore.getAllGuidelines();
+	const blockGuidelines = guidelinesStore.getBlockGuidelines();
 
 	const data = {
 		id,
@@ -57,11 +57,17 @@ export async function saveContentGuidelines(): Promise< RestGuidelinesResponse >
 			additional: {
 				guidelines: categories.additional,
 			},
+			blocks: Object.fromEntries(
+				Object.entries( blockGuidelines ).map(
+					( [ blockName, guidelines ] ) => [
+						blockName,
+						{ guidelines },
+					]
+				)
+			),
 		},
 	};
 
-	const { createSuccessNotice } = dispatch( noticesStore );
-
 	const path = id
 		? `/wp/v2/content-guidelines/${ id }`
 		: '/wp/v2/content-guidelines';
@@ -75,9 +81,5 @@ export async function saveContentGuidelines(): Promise< RestGuidelinesResponse >
 
 	setFromResponse( response );
 
-	createSuccessNotice( __( 'Content guidelines saved.' ), {
-		type: 'snackbar',
-	} );
-
 	return response;
 }

routes/content-guidelines/bootstrap-block-registry.ts

@@ -0,0 +1,24 @@
+/**
+ * WordPress dependencies
+ */
+import { dispatch } from '@wordpress/data';
+import { store as blocksStore } from '@wordpress/blocks';
+import { registerCoreBlocks } from '@wordpress/block-library';
+
+let bootstrapped = false;
+
+/**
+ * Bootstraps the block registry with Core blocks only.
+ * Used on the Content Guidelines admin page so block icons (and later
+ * 3rd party/experimental block support) are available without loading
+ * the full block editor.
+ */
+export function bootstrapBlockRegistry(): void {
+	if ( bootstrapped ) {
+		return;
+	}
+	bootstrapped = true;
+
+	dispatch( blocksStore ).reapplyBlockTypeFilters();
+	registerCoreBlocks();
+}

routes/content-guidelines/components/block-guideline-modal.scss

@@ -0,0 +1,13 @@
+@use "@wordpress/base-styles/variables" as *;
+
+.block-guideline-modal {
+	width: min(100%, 660px);
+
+	.components-modal__header-heading {
+		font-weight: 500;
+	}
+
+	&__actions {
+		margin-top: $grid-unit-10;
+	}
+}

routes/content-guidelines/components/block-guideline-modal.tsx

@@ -0,0 +1,207 @@
+/* @jsx createElement */
+
+/**
+ * WordPress dependencies
+ */
+import {
+	Button,
+	ComboboxControl,
+	Modal,
+	TextControl,
+	TextareaControl,
+	__experimentalHStack as HStack,
+	__experimentalVStack as VStack,
+} from '@wordpress/components';
+import { __, sprintf } from '@wordpress/i18n';
+import { Notice } from '@wordpress/ui';
+import { createElement, useMemo, useState } from '@wordpress/element';
+import { useDispatch, useSelect } from '@wordpress/data';
+import { store as blocksStore } from '@wordpress/blocks';
+import { store as noticesStore } from '@wordpress/notices';
+
+/**
+ * Internal dependencies
+ */
+import { saveContentGuidelines } from '../api';
+import { STORE_NAME } from '../store';
+import './block-guideline-modal.scss';
+
+interface BlockGuidelineModalProps {
+	closeModal: () => void;
+	initialBlock?: string;
+}
+
+export default function BlockGuidelineModal( {
+	closeModal,
+	initialBlock,
+}: BlockGuidelineModalProps ) {
+	const [ selectedBlock, setSelectedBlock ] = useState< string | undefined >(
+		initialBlock
+	);
+
+	const [ isSaving, setIsSaving ] = useState( false );
+	const [ error, setError ] = useState< string | null >( null );
+
+	const blockGuidelines = useSelect(
+		// @ts-ignore
+		( select ) => select( STORE_NAME ).getBlockGuidelines(),
+		[]
+	);
+
+	const isEditing = !! initialBlock;
+
+	const currentGuideline = blockGuidelines[ selectedBlock ] ?? '';
+	const [ guidelineText, setGuidelineText ] = useState( currentGuideline );
+
+	const blockOptions = useSelect(
+		// @ts-ignore
+		( select ) => select( blocksStore ).getBlockTypes(),
+		[]
+	);
+
+	const availableBlockOptions = useMemo( () => {
+		const set = new Set( Object.keys( blockGuidelines ) );
+		if ( initialBlock ) {
+			set.delete( initialBlock );
+		}
+		if ( selectedBlock ) {
+			set.delete( selectedBlock );
+		}
+
+		return blockOptions
+			.filter( ( block ) => ! set.has( block.name ) )
+			.map( ( block ) => ( {
+				value: block.name,
+				label: block.title,
+			} ) );
+	}, [ blockGuidelines, blockOptions, initialBlock, selectedBlock ] );
+
+	const selectedBlockLabel = useMemo(
+		() =>
+			blockOptions.find( ( block ) => block.name === selectedBlock )
+				?.title || '',
+		[ blockOptions, selectedBlock ]
+	);
+
+	const { setBlockGuideline } = useDispatch( STORE_NAME );
+	const { createSuccessNotice } = useDispatch( noticesStore );
+
+	const handleSave = ( value: string ) => {
+		value = value.trim();
+		if ( ! selectedBlock ) {
+			return;
+		}
+
+		setIsSaving( true );
+		const oldValue = blockGuidelines[ selectedBlock ];
+		setBlockGuideline( selectedBlock, value );
+		saveContentGuidelines()
+			.then( () => {
+				setError( null );
+				createSuccessNotice(
+					value
+						? __( 'Block guideline saved.' )
+						: __( 'Block guideline removed.' ),
+					{ type: 'snackbar' }
+				);
+				closeModal();
+			} )
+			.catch( ( e: Error ) => {
+				setError( e.message );
+				setBlockGuideline( selectedBlock, oldValue );
+			} )
+			.finally( () => setIsSaving( false ) );
+	};
+
+	const canSubmit = selectedBlock && guidelineText.trim().length > 0;
+
+	let submitButtonLabel: string = __( 'Add guideline' );
+	if ( isSaving ) {
+		submitButtonLabel = __( 'Saving…' );
+	} else if ( isEditing ) {
+		submitButtonLabel = __( 'Update guideline' );
+	}
+
+	return (
+		<Modal
+			className="block-guideline-modal"
+			title={
+				isEditing
+					? __( 'Edit block guidelines' )
+					: __( 'Add block guidelines' )
+			}
+			onRequestClose={ closeModal }
+		>
+			<VStack spacing={ 4 }>
+				{ isEditing ? (
+					<TextControl
+						__next40pxDefaultSize
+						label={ __( 'Block' ) }
+						value={ selectedBlockLabel }
+						onChange={ () => {} }
+						disabled
+					/>
+				) : (
+					<ComboboxControl
+						__next40pxDefaultSize
+						label={ __( 'Block' ) }
+						options={ availableBlockOptions }
+						value={ selectedBlock }
+						onChange={ ( value ) =>
+							setSelectedBlock( value ?? undefined )
+						}
+						placeholder={ __( 'Search for a block…' ) }
+					/>
+				) }
+				<TextareaControl
+					label={ __( 'Guideline text' ) }
+					value={ guidelineText }
+					onChange={ setGuidelineText }
+					placeholder={ __(
+						'Enter guidelines for how this block should be used…'
+					) }
+					rows={ 6 }
+				/>
+				{ error && (
+					<Notice.Root intent="error">
+						<Notice.Title>
+							{ sprintf(
+								/* translators: %s: Error message. */
+								__( 'Error: %s' ),
+								error
+							) }
+						</Notice.Title>
+					</Notice.Root>
+				) }
+				<HStack
+					justify="flex-end"
+					spacing={ 2 }
+					className="block-guideline-modal__actions"
+				>
+					{ isEditing && (
+						<Button
+							variant="tertiary"
+							isDestructive
+							// We need to pass an empty string to remove the guideline.
+							// This is because the API will only remove the guideline if the value is an empty string.
+							onClick={ () => handleSave( '' ) }
+							disabled={ isSaving }
+							accessibleWhenDisabled
+						>
+							{ __( 'Remove' ) }
+						</Button>
+					) }
+					<Button
+						variant="primary"
+						onClick={ () => handleSave( guidelineText ) }
+						disabled={ ! canSubmit || isSaving }
+						isBusy={ isSaving }
+						accessibleWhenDisabled
+					>
+						{ submitButtonLabel }
+					</Button>
+				</HStack>
+			</VStack>
+		</Modal>
+	);
+}

routes/content-guidelines/components/block-guidelines.scss

@@ -0,0 +1,32 @@
+@use "@wordpress/base-styles/variables" as *;
+
+.block-guidelines {
+	margin-top: $grid-unit-30;
+
+	.dataviews-view-list__media-wrapper {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+	}
+
+	.dataviews-view-list__field-wrapper {
+		display: flex;
+		justify-content: center;
+	}
+
+	.dataviews-wrapper {
+		margin-right: -$grid-unit-30;
+		margin-left: -$grid-unit-30;
+	}
+
+	.dataviews-search {
+		margin-right: $grid-unit-30;
+		margin-left: $grid-unit-30;
+	}
+}
+
+.block-guidelines__remove-modal {
+	.components-modal__header-heading {
+		font-weight: 500;
+	}
+}