Forms: add layout support #45272

CGastrell · 2025-09-22T16:30:11Z

Proposed changes:

This PR is both a PoC to add layout support to the form block, but also intends to fix and clarify some of our under the hood CSS mess.

What it does:

adds layout support with default class/styles manipulation via the blocks API
accommodates styles to address expected output while retaining old forms styling
uses the block registration to add a new stylesheet common to both editor and frontend
fixes some double class assignments while moving away from hacks to add classes that are meant to be used by blocks API by default
addresses an issue where the name of the container class (due to the above) confuses the layout support process (likely because it's called almost the same? .wp-block-jetpack-contact-form-container)

Why:

the form layout was originally designed to be a flexbox when there was no support for it (natively speaking by Gutenberg)
getting back in line with current blocks API and support aims for consistency and long term support
adding a new stylesheet where both, editor and frontend, can share styles: moving towards having a single markup structure is something we never had with forms, so both editor and frontend stylesheets have always been separate and mostly duplicated. The new one, jetpack-contact-form.css, is meant to be the single stylesheet to hold the entirety of the styles needed, effectively and eventually replacing grunion.css, and leave on editor.scss only what's needed to tweak/hack those styles for a fully wysiwyg experience. This is not to be done in a single blow, but we can agree on start migrating our styles there and eventually deprecate/delete grunion.css
some of our hacks include using the same CSS class on more than one ancestry container. This should not be. The changes include some cleanup and removals
in order to achieve this editor/frontend parity, a clear/unified container had to be set, yet it could not be .wp-block-jetpack-contact-form-container as it was messing with the layout support and causing the classes to be assigned to the wrong element. So, the container class was changed and the probe selector (view.ts) to match it: .jetpack-contact-form-container

Other information:

Have you written new tests for your changes, if applicable?
Have you checked the E2E test CI results, and verified that your changes do not break them?
Have you tested your changes on WordPress.com, if applicable (if so, you'll see a generated comment below with a script to run)?

Jetpack product discussion

p1758236622558259-slack-C052XEUUBL4
peKye1-1Lr-p2

Does this pull request change what data or activity we track or use?

No

Testing instructions:

Build both Jetpack and Forms:

jetpack build packages/forms plugins/jetpack

Visit the editor and create forms with different layouts. See if they behave as expected.
Visit the frontend and see if they match the editor preview.

github-actions · 2025-09-22T16:31:02Z

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack), and enable the add/forms-layout-support branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack add/forms-layout-support

Interested in more tips and information?

In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
Read more about our development workflow here: PCYsg-eg0-p2
Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

github-actions · 2025-09-22T16:31:12Z

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

✅ Include a description of your PR changes.
✅ Add a "[Status]" label (In Progress, Needs Review, ...).
✅ Add a "[Type]" label (Bug, Enhancement, Janitorial, Task).
✅ Add testing instructions.
✅ Specify whether this PR includes any changes to data or privacy.
✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

Follow this PR Review Process:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

Jetpack plugin:

The Jetpack plugin has different release cadences depending on the platform:

WordPress.com Simple releases happen as soon as you deploy your changes after merging this PR (PCYsg-Jjm-p2).
WoA releases happen weekly.
Releases to self-hosted sites happen monthly:
- Scheduled release: January 6, 2026

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

jp-launch-control · 2025-09-22T16:39:57Z

Code Coverage Summary

Coverage changed in 6 files. Only the first 5 are listed here.

File	Coverage	Δ%	Δ Uncovered
projects/packages/forms/src/blocks/contact-form/class-contact-form-block.php	488/609 (80.13%)	-2.30%	17 💔
projects/packages/forms/src/modules/form/view.js	0/280 (0.00%)	0.00%	3 ❤️‍🩹
projects/packages/forms/src/contact-form/class-contact-form.php	928/1322 (70.20%)	0.12%	2 ❤️‍🩹
projects/packages/forms/src/blocks/contact-form/index.js	0/6 (0.00%)	0.00%	1 ❤️‍🩹
projects/packages/forms/src/contact-form/class-contact-form-field.php	1093/1744 (62.67%)	0.02%	0 💚

Full summary · PHP report · JS report

_{Coverage check overridden by

Coverage tests to be added later
Use to ignore the Code coverage requirement check when tests will be added in a follow-up PR
.}

enejb · 2025-09-22T19:57:21Z

projects/packages/forms/src/contact-form/class-contact-form.php

 			$url                     = apply_filters( 'grunion_contact_form_form_action', $url, $GLOBALS['post'], $id, $page );
 			$has_submit_button_block = str_contains( $content, 'wp-block-jetpack-button' );
-			$form_classes            = 'contact-form commentsblock';
+			$form_classes            = 'contact-form jetpack-contact-form__form';


Can we keep the "commentsblock" class? Mostly for backwards compatibility.

Yes, we can, but I haven't seen it in use anywhere, do you know where is that coming from of what is it used for?

My guess is that it would be used by themes that want to style comment forms and we would apply the same styles as them.

That's a nice guess, but it also raises the question as usual: should we rule styling over our inner blocks? And, even if we allow customization, should a "comments block" style the same as our form blocks? After all, we try hard to flow into the theme's styling. TBH I'm not sure how to outweigh a decision here. I mostly wanted to just have a class specific to our form element, so we always know which is it and can include/exclude on stylings. We can put the commentsblock class back in, but feels pretty much as a tweak or concession instead of a clear definition of what our markup should be or abide by.

At first I agreed with Enej, but you do have a point, and commentsblock seems very wrong.

If we remove it, let's remove it in a PR that's much easier to revert than this mega PR :-)

Fair enough.

projects/packages/forms/src/blocks/contact-form/block.json

simison · 2025-10-28T12:01:36Z

projects/packages/forms/src/blocks/contact-form/edit.tsx

-	const blockProps = useBlockProps( { ref: wrapperRef } );
+	const blockProps = useBlockProps( {
+		ref: wrapperRef,
+		className: clsx( className, variationName === 'multistep' && 'is-multistep' ),


Just an alternative, might be a bit easier to read:

clsx( className, { 'is-multistep': variationName === 'multistep' } )

simison · 2025-10-28T12:03:10Z

projects/packages/forms/src/blocks/contact-form/index.js


+// Extract only valid block registration properties from block.json
+// Exclude file-based properties like editorScript, style, etc.
+const { editorScript, style, name: blockName, $schema, ...validBlockMetadata } = blockMetadata;


This would've been a good separate PR to simplify this one. ;-)

Gotcha, but I discover the discrepancies while testing this one and creating a new PR trying to explain the reason for the change would have implied some back and forth / delays. Thought I'd just add it here.

Referencing a change to WIP PRs to demonstrate how it makes dev ergonomics better elsewhere is fine.

It's ok here now tho.

simison · 2025-10-28T12:04:38Z

projects/packages/forms/src/blocks/field-telephone/edit.js

 						index: 1,
 						element: (
-							<>
+							<div key="phoneFieldControls">


Does it need a wrapper if children already have keys? 🤔 It's unrelated to this PR, so it would've been better in a separate PR.

Will separate this one, it was just killing me to get an error on every reload

simison · 2025-10-28T12:05:32Z

projects/packages/forms/src/contact-form/css/jetpack-contact-form.scss

+// this styles are common to both editor and frontend
+// Gutenberg versions will use different classname strategies
+// for layout flex support, cover both possibilities here: frontend and editor.


Typos and not very clear comment

simison · 2025-10-28T12:06:35Z

projects/packages/forms/src/contact-form/class-contact-form-field.php

+		// somehow we are getting the class jetpack-field__input-element on the wrong wrapper
+		// .jetpack-field__input-element is meant to style a div mocking an input element, not its wrapper.
+		$class_names = preg_replace( '/jetpack-field__input-element /', '', $class_names );


Did you get to the bottom of why this is happening, or it's a good follow-up?

Good for follow up!

simison · 2025-10-28T12:11:46Z

projects/packages/forms/src/contact-form/class-contact-form.php

 	 */
-	private static function render_error_wrapper() {
-		$html  = '<div class="contact-form__error" data-wp-class--show-errors="state.showFormErrors">';
+	private static function render_error_wrapper( $classes = array() ) {


Why an array instead of a string if we only ever pass it one class in the codebase? I would simplify, and if we later need to pass array we can turn it to a string higher up before this function.

Alternatively, pass is_horizontal boolean and manage CSS class directly in the function?

Why an array instead of a string

Just because is more future-proof. It can easily be a string. Using a boolean would not simplify as we'd need a ternary.

Changed to single string param for extra CSS classes

simison · 2025-10-28T12:20:26Z

projects/packages/forms/src/modules/form/view.js

 			const fieldId = context.fieldId;
 			const field = context.fields[ fieldId ] || {};
+			// when there is only one field, don't show errors until the user tries to submit the form.
+			// And even then, return false so we only show the general form error message.


Good to indeed improve what we show on submit.

We should instead show the inline form message, which looks much better than the big error badge. This change would've been a good independent PR too to get it in quicker and make testing easier.

Better:

This PR:

Let's also continue invalidate on-blur to save users click for on-submit, that was the whole point of that UX improvement so let's not remove it here.

Mmm good catch, I need to make sure we only do this on single input, horizontal forms. Will use iApi for it.

@simison could we do something like this for all of our forms, please? 🙏

@CGastrell prolly best we iterate on this in a separate PR to keep individual changes moving?

@ilonagl, the summary error thing has some purpose on very long forms, where you don't see inline errors above the fold, but I think the UX/design can be improved a lot for sure when pressing "submit".

@simison yes, agreed! We recently had a chat about with this with Enej. Do we have a Linear or Github task where I could start gathering designs and notes?

simison · 2025-10-28T12:21:31Z

projects/packages/forms/src/contact-form/class-contact-form-plugin.php

+			Jetpack_Forms::plugin_url() . '../dist/contact-form/css/jetpack-contact-form.css',
+			array(),
+			\JETPACK__VERSION
+		);


What's the logic with two style files? Should everything from grunion.css move here next up, are they loaded separately conditioally, or something else?

Now the two separate stylesheets don't feel like they make much sense because of how they're named.

No, it doesn't make "much" sense. I can easily merge this onto grunion, but that other one is so messed up it's very difficult to work with. Here we just register the style, then it's the new blocks API in charge of loading it: the frontend loads this CSS on demand (as in, not loaded unless there's a form block present, see class-contact-form-block.php:58). I thought it could become a new file to work with and, hopefully, a place to start moving our CSS while we clean up grunion. Otherwise, options are: merge onto grunion or name it specifically as part of the layout support styles.

…generic form error suffices and allows for single-field, horizontal forms (subscribe)

…orizontal layout

Co-authored-by: Mikael Korpela <[email protected]>

…dable

…t want the inlined error under the field

…eatment

…r display

…d justification support

dhasilva

Tests fine for me. Would be wise to get more reviews.

CGastrell self-assigned this Sep 22, 2025

github-actions bot added [Block] Contact Form Form block (also see Contact Form label) [Feature] Contact Form labels Sep 22, 2025

CGastrell requested a review from a team September 22, 2025 19:42

enejb reviewed Sep 22, 2025

View reviewed changes

github-actions bot added [Tests] Includes Tests E2E Tests labels Sep 22, 2025

CGastrell force-pushed the add/forms-layout-support branch from 07d2a02 to 74c3d24 Compare October 14, 2025 16:07

CGastrell force-pushed the add/forms-layout-support branch 5 times, most recently from 4802ade to 76a70cf Compare October 27, 2025 18:58

simison reviewed Oct 28, 2025

View reviewed changes

projects/packages/forms/src/blocks/contact-form/block.json Outdated Show resolved Hide resolved

simison reviewed Oct 28, 2025

View reviewed changes

CGastrell and others added 28 commits December 4, 2025 19:51

don't show under-the-field error when a single input is present, the …

eb83338

…generic form error suffices and allows for single-field, horizontal forms (subscribe)

use a single source of supports declaration, for consistency

0b064ee

add extra selector for older gutenberg versions

5e47c1c

force button use the same styles on editor and frontend when in .is-h…

996eb3f

…orizontal layout

Apply suggestion from @simison

e883736

Co-authored-by: Mikael Korpela <[email protected]>

improve wording on css class comment

317e9ef

reinstate commentsblock class on form

5c0f388

use string for class injection on render_error_wrapper

631af2a

prettify clsx call

9a98489

fix comment for proper follow up

92a2c98

define specific flag for forced horizontal layout, make code more rea…

a9f61d7

…dable

add isForcedHorizontal state getter, use it to determine when we don'…

b23d64c

…t want the inlined error under the field

Add 50% width by default variations for email and name

e51a1d4

add animated and outlined styles

d4bc829

move new css file to jetpack-forms-layout for better organization

7e3b1e7

add extensions to imports

7423971

try enabling all layout features

8aca549

fix failing tests

bbeb764

restore variations

4d69e9d

make default flex to stretch

458e9b1

default vertical align to bottom for sanity, disallow adjusting it

2f76bde

consider both single and forced-horizontal forms for special error tr…

57e5738

…eatment

accommodate CSS rules/selectors for single and forced horizontal erro…

4dbedea

…r display

conditional error display extended to isForcedHorizontal on iAPI

ac8e725

adjust layout styles, specially for multi-step, with new alignment an…

d871c64

…d justification support

no need to override already set prop

c4c7afd

adjust animated styles

f375a52

make default layout horizontal

337f0a9

CGastrell force-pushed the add/forms-layout-support branch from 0f5e795 to 337f0a9 Compare December 4, 2025 22:52

dhasilva approved these changes Dec 5, 2025

View reviewed changes

Forms: add layout support #45272

Are you sure you want to change the base?

Forms: add layout support #45272

Uh oh!

Conversation

CGastrell commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes:

Other information:

Jetpack product discussion

Does this pull request change what data or activity we track or use?

Testing instructions:

Uh oh!

github-actions bot commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jp-launch-control bot commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simison Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simison Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CGastrell commented Sep 22, 2025 •

edited

Loading

github-actions bot commented Sep 22, 2025 •

edited

Loading

github-actions bot commented Sep 22, 2025 •

edited

Loading

jp-launch-control bot commented Sep 22, 2025 •

edited

Loading

simison Oct 28, 2025 •

edited

Loading

simison Oct 28, 2025 •

edited

Loading