Forms: Add ref attribute support for synced/reusable forms (#46555)

* Add support for synced forms via ref attribute

Introduces a new 'ref' attribute to the contact form block, allowing forms to be rendered by referencing a jetpack_form post by ID. Implements circular reference prevention and ensures only published or draft forms are rendered.

* Add useSyncedForm hook for loading synced forms

Introduces a custom React hook to load and parse synced contact forms from the jetpack_form post type. The hook fetches the referenced form, parses its block content, and returns loading state, attributes, and inner blocks for use in the contact form block.

* Update contact form save logic for synced forms

The save function now checks for the 'ref' attribute. If present, it returns null to avoid saving innerBlocks for synced forms, as their content is managed elsewhere. Inline forms continue to save the full block with innerBlocks.

* Add form sync manager utility for contact forms

Introduces utilities to serialize contact form blocks and create synced forms via the Jetpack API. Provides type definitions and functions for converting between inline and synced form modes.

* Add ConvertFormToolbar for synced form management

Introduces the ConvertFormToolbar component to enable converting contact forms to synced forms and editing synced forms directly from the block toolbar. Updates the contact form edit logic to support loading and syncing form data when a ref is present, and conditionally displays the toolbar based on the central form management feature flag.

* Create update-form-block-saves-custom-post-type

* Add Form Editor Class and block locking

* Refactor to use FORM_POST_TYPE constant

Replaced hardcoded 'jetpack_form' strings with the FORM_POST_TYPE constant across multiple files for consistency and maintainability. The constant is now defined in shared/util/constants.js and imported where needed.

* Add isJetpackFormEditor check to contact form edit

Introduces an isJetpackFormEditor flag using the current post type and FORM_POST_TYPE constant. Updates the ConvertFormToolbar rendering to only show when not in the Jetpack form editor, improving context-aware UI behavior.

* Add inline editing and syncing for reusable contact forms

Refactors the contact form block to support inline editing of reusable (synced) forms by loading, parsing, and saving form content directly from/to the referenced form post. Introduces logic to fetch and apply reusable form attributes and inner blocks, and ensures changes are persisted back to the source form. Adds error handling for missing referenced forms and improves loading state handling. Also adds a new hook (use-auto-save-synced-form) for auto-saving synced form changes when the parent post is saved.

* Create sync form on the variation picker

* Refactor to simplify

* Add Form Document Settings panel to form editor

Introduces a new Form Document Settings React component and plugin, displaying form configuration panels in the Document Settings sidebar for jetpack_form post types. Updates the form editor to register this plugin, adds related documentation, and includes supporting styles. Also updates dependencies to include @wordpress/edit-post and @wordpress/plugins.

* Forms: include form post id in feedback

* Reverse changes from last commit

* Store form_ref in feedback post_parent

* Update the Convert Form button to just be the edit button.

* Fix tests

* Don't load the script in the site editor.

* Hide the sidebar post noise

* hide the post title in the editor

* Simplify

* Improve hiding the post title for the jetpack form editor.

* Allow multiselect in form editor

* Remove the box shadow from the form block.

* Hide the breakcrumb

* Update the categories in the inserter and remove the install plugin

* Add a select a from dropdown to placeholder

* Add command that lets us rename the form.

* Fix phplinter

* Fix js linter

* improve the refId validation

* Stash

* fix double form POST TYPE

* Remove cahngelog

* Revert files to trunk

* Changelog

* change changelog

* revert constants and variation picker

* Remove the ConvertFormToolbar

* Revert styles

* Remove the unused form sync manager

* Simplify

* Always remove the lock when syncing the block

* Add tests

* Revert pnpm lock file

* Add synced label

* only allow valid refs to be submitted

* Add tests for the PHP side

* Minor changes

Co-authored-by: Copilot <[email protected]>

* clearTimeout when set

Co-authored-by: Copilot <[email protected]>

* FIX react-hooks/exhaustive-deps

* curcular reference returns empty string

Co-authored-by: Copilot <[email protected]>

* Always clear ref id

Co-authored-by: Copilot <[email protected]>

* simplify the logic

Co-authored-by: Copilot <[email protected]>

* removed code that is not needed any more

Co-authored-by: Copilot <[email protected]>

* Make sure that output is always set

* fix static

* fix phan

* Updates to the changelog

* Update test names

* Update the interface for JetpackForm

* revert pnpm-lock.yaml

* Remove isSyncedFormContext since it is not needed in this PR

* Only render 'publish' forms

* Fix test for draft form

---------

Co-authored-by: Erick Danzer <[email protected]>
Co-authored-by: Copilot <[email protected]>

Committed via a GitHub action: https://github.com/Automattic/jetpack/actions/runs/20976310003

Upstream-Ref: Automattic/jetpack@61e48d9

Author: enejb

CHANGELOG.md

@@ -7,6 +7,7 @@
 This is an alpha version! The changes listed here are not final.
 
 ### Enhancements
+- Forms: add ref attribute support for the form block.
 - Forms: make form webhooks generally available.
 - Instant Search: Show WooCommerce product filters in filter widget
 

jetpack_vendor/automattic/jetpack-forms/CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 This is an alpha version! The changes listed here are not final.
 
 ### Added
+- Add ref attribute support for the form block.
 - Forms: add centralized dashboard tabs.
 - Forms: make form webhooks generally available.
 

jetpack_vendor/automattic/jetpack-forms/dist/blocks/editor.asset.php

@@ -1 +1 @@
-<?php return array('dependencies' => array('jetpack-connection', 'jetpack-script-data', 'lodash', 'react', 'react-jsx-runtime', 'wp-api-fetch', 'wp-block-editor', 'wp-blocks', 'wp-components', 'wp-compose', 'wp-core-data', 'wp-data', 'wp-dom-ready', 'wp-editor', 'wp-element', 'wp-hooks', 'wp-i18n', 'wp-jp-i18n-loader', 'wp-notices', 'wp-plugins', 'wp-polyfill', 'wp-primitives', 'wp-url'), 'version' => '9838c0cd174b9c148855');
+<?php return array('dependencies' => array('jetpack-connection', 'jetpack-script-data', 'lodash', 'react', 'react-jsx-runtime', 'wp-api-fetch', 'wp-block-editor', 'wp-blocks', 'wp-components', 'wp-compose', 'wp-core-data', 'wp-data', 'wp-dom-ready', 'wp-editor', 'wp-element', 'wp-hooks', 'wp-i18n', 'wp-jp-i18n-loader', 'wp-notices', 'wp-plugins', 'wp-polyfill', 'wp-primitives', 'wp-url'), 'version' => 'bd1fbeabd5a2227cee5b');

jetpack_vendor/automattic/jetpack-forms/dist/blocks/editor.js

@@ -4,6 +4,9 @@
 import { __ } from '@wordpress/i18n';
 
 export default {
+	ref: {
+		type: 'number' as const,
+	},
 	subject: {
 		type: 'string',
 		default: window.jpFormsBlocks?.defaults?.subject || '',

jetpack_vendor/automattic/jetpack-forms/src/blocks/contact-form/attributes.ts

@@ -728,9 +728,65 @@ public static function gutenblock_render_form( $atts, $content ) {
 
 		self::load_view_scripts();
 
+		// Handle ref attribute - load form from jetpack-form post
+		if ( isset( $atts['ref'] ) ) {
+			$ref_id = absint( $atts['ref'] );
+			if ( $ref_id > 0 ) {
+				return self::render_synced_form( $ref_id );
+			} else {
+				return ''; // Invalid ref ID.
+			}
+		}
+
 		return Contact_Form::parse( $atts, do_blocks( $content ) );
 	}
 
+	/**
+	 * Render a synced form by reference ID.
+	 *
+	 * @param int $ref_id The jetpack_form post ID.
+	 * @return string Rendered form HTML.
+	 */
+	private static function render_synced_form( $ref_id ) {
+		// Circular reference prevention.
+		static $seen_refs = array();
+
+		if ( isset( $seen_refs[ $ref_id ] ) ) {
+			// Return empty string to match other error cases and unit test expectations.
+			return '';
+		}
+
+		// Load the jetpack-form post.
+		$synced_form = get_post( $ref_id );
+
+		// Validate post.
+		if ( ! $synced_form || 'jetpack_form' !== $synced_form->post_type ) {
+			return '';
+		}
+
+		// Only render published forms statuses.
+		if ( ! in_array( $synced_form->post_status, array( 'publish' ), true ) ) {
+			return '';
+		}
+
+		// Mark as seen for circular reference prevention.
+		$seen_refs[ $ref_id ] = true;
+		Contact_Form::set_ref_id( $ref_id );
+		$output = '';
+		try {
+			// Parse and render blocks from post_content.
+			$blocks = parse_blocks( $synced_form->post_content );
+			foreach ( $blocks as $block ) {
+				$output .= render_block( $block );
+			}
+		} finally {
+			// Clean up.
+			unset( $seen_refs[ $ref_id ] );
+			Contact_Form::clear_ref_id();
+		}
+		return $output;
+	}
+
 	/**
 	 * Load editor styles for the block.
 	 * These are loaded via enqueue_block_assets to ensure proper loading in the editor iframe context.

jetpack_vendor/automattic/jetpack-forms/src/blocks/contact-form/class-contact-form-block.php

@@ -17,6 +17,7 @@ import {
 import { createBlock } from '@wordpress/blocks';
 import {
 	ExternalLink,
+	Notice,
 	PanelBody,
 	TextareaControl,
 	TextControl,
@@ -51,6 +52,9 @@ import { ContactFormPlaceholder } from './components/jetpack-contact-form-placeh
 import ContactFormSkeletonLoader from './components/jetpack-contact-form-skeleton-loader.js';
 import NotificationsSettings from './components/notifications-settings.js';
 import WebhooksSettings from './components/webhooks-settings.js';
+import { useSyncedFormAutoSave } from './hooks/use-synced-form-auto-save.ts';
+import { useSyncedFormLoader } from './hooks/use-synced-form-loader.ts';
+import { useSyncedForm } from './hooks/use-synced-form.ts';
 import useFormBlockDefaults from './shared/hooks/use-form-block-defaults.js';
 import VariationPicker from './variation-picker.js';
 import './util/form-styles.js';
@@ -133,6 +137,7 @@ type Webhook = {
 };
 
 type JetpackContactFormAttributes = {
+	ref?: number;
 	to: string;
 	subject: string;
 	// Legacy support for the customThankyou attribute
@@ -169,6 +174,7 @@ function JetpackContactFormEdit( {
 	useFormBlockDefaults( { attributes, setAttributes } );
 
 	const {
+		ref,
 		to,
 		subject,
 		customThankyou,
@@ -189,6 +195,14 @@ function JetpackContactFormEdit( {
 	const showBlockIntegrations = useConfigValue( 'showBlockIntegrations' );
 	const instanceId = useInstanceId( JetpackContactFormEdit );
 
+	// Load synced form data from the jetpack_form post type
+	const {
+		syncedForm,
+		isLoading: isResolvingSyncedForm,
+		syncedAttributes: syncedFormAttributes,
+		syncedInnerBlocks: syncedFormBlocks,
+	} = useSyncedForm( ref );
+
 	// Backward compatibility for the deprecated customThankyou attribute.
 	// Older forms will have a customThankyou attribute set, but not a confirmationType attribute
 	// and not a disableSummary attribute, so we need to set it here.
@@ -220,7 +234,6 @@ function JetpackContactFormEdit( {
 		block => block.name === 'core/button' || block.name === 'jetpack/button',
 		[]
 	);
-
 	const submitButton = useFindBlockRecursively( clientId, findButtonsBlock );
 
 	const { postTitle, hasAnyInnerBlocks, postAuthorEmail, selectedBlockClientId, onlySubmitBlock } =
@@ -315,11 +328,38 @@ function JetpackContactFormEdit( {
 	const { replaceInnerBlocks, __unstableMarkNextChangeAsNotPersistent, updateBlockAttributes } =
 		useDispatch( blockEditorStore );
 
+	const { editEntityRecord } = useDispatch( coreStore );
+
 	const currentInnerBlocks = useSelect(
 		select => select( blockEditorStore ).getBlocks( clientId ),
 		[ clientId ]
 	);
 
+	// Sync synced form content INTO the editor (one-time on ref change)
+	const { isSyncingRef } = useSyncedFormLoader( {
+		ref,
+		syncedFormBlocks,
+		syncedFormAttributes,
+		clientId,
+		setAttributes,
+		replaceInnerBlocks,
+		__unstableMarkNextChangeAsNotPersistent,
+	} );
+
+	// Auto-save editor changes BACK to the synced form post
+	useSyncedFormAutoSave( {
+		ref,
+		syncedForm,
+		attributes,
+		currentInnerBlocks,
+		isSyncingRef,
+		editEntityRecord,
+	} );
+
+	// Note: We don't clear attributes in memory when ref is set, as they're needed
+	// for the form to work properly in the editor. The save() method ensures that
+	// only the ref attribute is persisted to the database.
+
 	// Track previous block count to detect insertions
 	const previousBlockCountRef = useRef( currentInnerBlocks.length );
 
@@ -809,18 +849,36 @@ function JetpackContactFormEdit( {
 
 	let elt;
 
-	if ( ! isModuleActive ) {
+	// Show loading state when resolving synced form
+	if ( ref && isResolvingSyncedForm ) {
+		return (
+			<div { ...blockProps }>
+				<ContactFormSkeletonLoader />
+			</div>
+		);
+	}
+	// Show error if referenced form not found
+	else if ( ref && ! syncedForm && ! isResolvingSyncedForm ) {
+		elt = (
+			<Notice status="warning" isDismissible={ false }>
+				{ __( 'The referenced form could not be found.', 'jetpack-forms' ) }
+			</Notice>
+		);
+	} else if ( ! isModuleActive ) {
 		if ( isLoadingModules ) {
-			elt = <ContactFormSkeletonLoader />;
-		} else {
-			elt = (
-				<ContactFormPlaceholder
-					changeStatus={ changeStatus }
-					isModuleActive={ isModuleActive }
-					isLoading={ isChangingStatus }
-				/>
+			return (
+				<div { ...blockProps }>
+					<ContactFormSkeletonLoader />
+				</div>
 			);
 		}
+		elt = (
+			<ContactFormPlaceholder
+				changeStatus={ changeStatus }
+				isModuleActive={ isModuleActive }
+				isLoading={ isChangingStatus }
+			/>
+		);
 	} else if ( ! hasAnyInnerBlocks ) {
 		elt = (
 			<VariationPicker

jetpack_vendor/automattic/jetpack-forms/src/blocks/contact-form/edit.tsx

@@ -0,0 +1,58 @@
+/**
+ * Hook to auto-save editor changes back to synced form post
+ */
+
+import { useEffect } from '@wordpress/element';
+import { FORM_POST_TYPE } from '../../shared/util/constants.js';
+import { serializeSyncedForm } from '../utils/synced-form-helpers.ts';
+
+interface UseSyncedFormAutoSaveParams {
+	ref?: number;
+	syncedForm: { content?: { raw?: string } } | null;
+	attributes: Record< string, unknown >;
+	currentInnerBlocks: unknown[];
+	isSyncingRef: React.MutableRefObject< boolean >;
+	editEntityRecord: (
+		kind: string,
+		name: string,
+		recordId: number,
+		edits: Record< string, unknown >
+	) => void;
+}
+
+/**
+ * Hook to automatically save changes from the editor back to the synced form post
+ * Uses a debounce strategy to avoid excessive saves (1 second delay)
+ * Only saves if content has changed and we're not currently loading
+ *
+ * @param {UseSyncedFormAutoSaveParams} params - Configuration parameters
+ */
+export function useSyncedFormAutoSave( {
+	ref,
+	syncedForm,
+	attributes,
+	currentInnerBlocks,
+	isSyncingRef,
+	editEntityRecord,
+}: UseSyncedFormAutoSaveParams ): void {
+	useEffect( () => {
+		if ( ! ref || ! syncedForm || isSyncingRef.current ) {
+			return; // Not a synced form or currently syncing
+		}
+
+		// Serialize the entire form block
+		const serialized = serializeSyncedForm( attributes, currentInnerBlocks );
+
+		// Only update if content has changed
+		if ( serialized !== syncedForm.content?.raw ) {
+			// Debounce to avoid excessive saves
+			const timeoutId = setTimeout( () => {
+				editEntityRecord( 'postType', FORM_POST_TYPE, ref, {
+					content: serialized,
+				} );
+			}, 1000 ); // 1 second debounce
+
+			return () => clearTimeout( timeoutId );
+		}
+	}, [ currentInnerBlocks, ref, syncedForm, editEntityRecord, attributes, isSyncingRef ] );
+}

jetpack_vendor/automattic/jetpack-forms/src/blocks/contact-form/hooks/use-synced-form-auto-save.ts

@@ -0,0 +1,93 @@
+/**
+ * Hook to load synced form content into the editor (one-time sync on mount/ref change)
+ */
+
+import { useEffect, useRef } from '@wordpress/element';
+import { filterSyncedAttributes } from '../utils/synced-form-helpers.ts';
+
+interface UseSyncedFormLoaderParams {
+	ref?: number;
+	syncedFormBlocks: unknown[] | null;
+	syncedFormAttributes: Record< string, unknown > | null;
+	clientId: string;
+	setAttributes: ( attributes: Record< string, unknown > ) => void;
+	replaceInnerBlocks: ( clientId: string, blocks: unknown[], updateSelection: boolean ) => void;
+	__unstableMarkNextChangeAsNotPersistent: () => void;
+}
+
+interface UseSyncedFormLoaderResult {
+	isSyncingRef: React.MutableRefObject< boolean >;
+}
+
+/**
+ * Hook to handle loading synced form content into the editor
+ * This performs a one-time sync when the ref changes or loads for the first time
+ * After loading, the user can edit freely and changes will be saved back via auto-save
+ *
+ * @param {UseSyncedFormLoaderParams} params - Configuration parameters
+ * @return {UseSyncedFormLoaderResult} Object containing syncing state ref
+ */
+export function useSyncedFormLoader( {
+	ref,
+	syncedFormBlocks,
+	syncedFormAttributes,
+	clientId,
+	setAttributes,
+	replaceInnerBlocks,
+	__unstableMarkNextChangeAsNotPersistent,
+}: UseSyncedFormLoaderParams ): UseSyncedFormLoaderResult {
+	// Track if we're currently syncing to prevent save-back loops
+	const isSyncingRef = useRef( false );
+	const lastLoadedRefId = useRef< number | null >( null );
+
+	useEffect( () => {
+		if ( ! ref || ! syncedFormBlocks ) {
+			return;
+		}
+
+		// Only sync when ref changes or loads for the first time
+		// Don't re-sync when syncedFormBlocks changes due to our own edits
+		if ( lastLoadedRefId.current === ref ) {
+			return; // Already loaded this ref
+		}
+
+		// Mark this ref as loaded
+		lastLoadedRefId.current = ref;
+
+		// Sync on initial load
+		// Once loaded, the user can edit freely and changes will save back to the source
+		isSyncingRef.current = true;
+
+		// Apply form attributes from the synced form (except ref and layout attrs)
+		// Mark as non-persistent so they're not saved locally - only ref is saved
+		if ( syncedFormAttributes ) {
+			const attrsToApply = filterSyncedAttributes( syncedFormAttributes );
+
+			__unstableMarkNextChangeAsNotPersistent();
+			setAttributes( attrsToApply );
+		}
+
+		// Load inner blocks from source
+		__unstableMarkNextChangeAsNotPersistent();
+		replaceInnerBlocks( clientId, syncedFormBlocks, false );
+
+		// Reset syncing flag after a short delay
+		const timeoutId = setTimeout( () => {
+			isSyncingRef.current = false;
+		}, 100 );
+
+		return () => {
+			clearTimeout( timeoutId );
+		};
+	}, [
+		ref,
+		syncedFormBlocks,
+		syncedFormAttributes,
+		clientId,
+		__unstableMarkNextChangeAsNotPersistent,
+		replaceInnerBlocks,
+		setAttributes,
+	] );
+
+	return { isSyncingRef };
+}