Forms: replace the generic block editor welcome modal with a form editor guide by enejb · Pull Request #51039 · Automattic/jetpack

enejb · 2026-08-04T19:49:43Z

Proposed changes

The jetpack_form editor currently shows the generic block editor welcome modal ("In the WordPress editor, each paragraph, image, or video is presented as a distinct block…"). That copy is accurate but not much help to someone who has just opened the form editor to build a form.

This replaces it, in the form editor only, with a five-slide guide covering the form editor's own flow:

Welcome to the form editor — this is a reusable form you create once and add anywhere.
Add fields — the inserter is already open; fields are grouped into Basic, Contact info, Choice, Advanced, and Multi-step.
Make each field yours — label, placeholder, and required, in the sidebar.
Decide what happens after submit — confirmation or redirect, email and push notifications, integrations, saving responses.
Publish and share it — add to a new page, an existing page, or copy the embed code; responses land in the inbox.

Slide copy is drawn from what the editor actually exposes (the categories in form-categories.ts, the pre-publish panel's settings rows, and the embed modal's three paths) so it doesn't promise anything that isn't there.

Artwork is intentionally not included. Each slide reserves a correctly-sized placeholder region, wrapped in an __image element mirroring the core guide's structure, so illustrations can be dropped in later as a straight swap with no layout change.

Implementation notes

Built on Guide from @wordpress/components — the same component the core welcome modal uses. Sizing mirrors .edit-post-welcome-guide (312px wide, 240px artwork region) so the guide sits at the same scale as the modal it replaces.
Registered and unregistered as an editor plugin in the existing enter/leave branches of form-editor/index.tsx, alongside the four plugins already handled there.
Suppressing the core modal uses setDefaults, not set. Defaults are runtime-only and never persisted, so the user's own core/edit-post preference is untouched and the generic modal still behaves normally in the post and page editors. A user who has deliberately re-enabled the core guide keeps it, since a persisted preference takes precedence over a default.
Dismissal is stored under a jetpack/forms preference scope, so it never collides with core's.
The guide can be reopened at any time from Options (⋮) → Form guide.
Visibility logic lives in a pure should-show.ts predicate with unit tests, following the existing inserter-utils.ts pattern in this directory.
Styles use CSS logical properties throughout, so RTL is correct by default.

Related product discussion/links

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

No. The only stored value is a per-user editor preference recording whether the guide has been dismissed.

Testing instructions

Requires a site with Jetpack Forms. The guide can be force-shown on every load with the jetpack_forms_welcome_guide query argument, so the first-run experience can be re-tested without resetting preferences.

The guide itself

Go to Jetpack → Forms → Add new form, or /wp-admin/post-new.php?post_type=jetpack_form&jetpack_forms_welcome_guide=1.
Confirm the form-specific guide appears instead of the generic block editor welcome modal.
Step through all five slides. Check the dots, Previous, and the Start building button on the last slide.
Confirm the modal is compact (312px wide) rather than stretching across the viewport, and that each slide reserves a placeholder region where artwork will go.

Show-once behaviour

Load /wp-admin/post-new.php?post_type=jetpack_form with no query argument. The guide should appear.
Dismiss it with Start building (or the ✕), then reload. It should not come back.
Reopen it from Options (⋮) → Form guide.

No leakage into the post editor

With the form guide dismissed, go to Posts → Add new.
Confirm the core welcome modal behaves exactly as it did before this change — the form editor must not have turned it off.

RTL

Switch to an RTL locale and confirm the guide's padding and alignment mirror correctly.

Screenshots

Captured on a live Jurassic Ninja site at 1440×900. The grey dashed region on each slide is the reserved artwork placeholder — illustrations are still to come from design.

The guide in context

The five slides



1. Welcome to the form editor	2. Add fields

3. Make each field yours	4. Decide what happens after submit

5. Publish and share it

…tor guide

github-actions · 2026-08-04T19:50:57Z

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-editor-welcome-guide branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack add/forms-editor-welcome-guide

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 · 2026-08-04T19:53:52Z

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 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!

jp-launch-control · 2026-08-04T20:02:13Z

Code Coverage Summary

Coverage changed in 1 file.

File	Coverage	Δ%	Δ Uncovered
projects/packages/forms/src/form-editor/index.tsx	0/252 (0.00%)	0.00%	8 💔

3 files are newly checked for coverage.

File	Coverage
projects/packages/forms/src/form-editor/welcome-guide/index.tsx	0/18 (0.00%) 💔
projects/packages/forms/src/form-editor/welcome-guide/pages.tsx	0/3 (0.00%) 💔
projects/packages/forms/src/form-editor/welcome-guide/should-show.ts	9/9 (100.00%) 💚

Full summary · PHP report · JS report

_{If appropriate, add one of these labels to override the failing coverage check:

Covered by non-unit tests
Use to ignore the Code coverage requirement check when E2Es or other non-unit tests cover the code

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

I don't care about code coverage for this PR
Use this label to ignore the check for insufficient code coveage.}

Copilot

Pull request overview

This PR updates the Jetpack Forms custom post type editor (jetpack_form) to replace WordPress’s generic block editor welcome modal with a Forms-specific, 5-step onboarding guide built with @wordpress/components’ Guide. It also suppresses the core welcome modal only while in the form editor, and adds unit tests for the guide visibility predicate.

Changes:

Add a new Forms “welcome guide” editor plugin (slides, styles, preference storage, and an Options menu entry to open it).
Add pure visibility/query-arg logic (should-show.ts) with Jest unit tests.
Suppress/restore core’s welcome guide defaults when entering/leaving the form editor, without persisting changes to core/edit-post preferences.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
projects/packages/forms/tests/js/form-editor/welcome-guide/should-show.test.js	Adds unit tests for guide visibility and force-query-arg parsing.
projects/packages/forms/src/form-editor/welcome-guide/style.scss	Styles the guide to match core welcome modal sizing and reserve an image slot using logical properties.
projects/packages/forms/src/form-editor/welcome-guide/should-show.ts	Implements pure “should show” logic and parsing of `jetpack_forms_welcome_guide` query arg.
projects/packages/forms/src/form-editor/welcome-guide/pages.tsx	Defines the 5 guide pages and a placeholder image slot per slide.
projects/packages/forms/src/form-editor/welcome-guide/index.tsx	Implements the editor plugin UI, preference storage, and Options menu item.
projects/packages/forms/src/form-editor/index.tsx	Registers/unregisters the welcome guide plugin on enter/leave and suppresses/restores the core welcome modal via `setDefaults`.
projects/packages/forms/changelog/add-forms-editor-welcome-guide	Adds changelog entry describing the new form editor guide.

+	// Tracks closing within this page load. Needed on top of the preference so
+	// that a forced guide can still be dismissed.
+	const [ isClosed, setIsClosed ] = useState( false );
+
+	const handleFinish = useCallback( () => {
+		setIsClosed( true );
+		set( PREFERENCE_SCOPE, PREFERENCE_NAME, false );
+	}, [ set ] );
+
+	const handleReopen = useCallback( () => {
+		setIsClosed( false );
+		set( PREFERENCE_SCOPE, PREFERENCE_NAME, true );
+	}, [ set ] );
+
+	const isOpen = ! isClosed && shouldShowWelcomeGuide( { preference, isForced } );


+Significance: minor
+Type: added
+
+Form editor: replace the generic block editor welcome modal with a guide to the form editor.


…t-run template picker

Forms: replace the generic block editor welcome modal with a form edi…

f6fd937

…tor guide

enejb self-assigned this Aug 4, 2026

enejb added the Enhancement Changes to an existing feature — removing, adding, or changing parts of it label Aug 4, 2026

github-actions Bot added [Feature] Contact Form [Package] Forms [Status] In Progress [Tests] Includes Tests labels Aug 4, 2026

github-actions Bot added the [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. label Aug 4, 2026

enejb requested review from Copilot and ilonagl August 4, 2026 23:00

Copilot started reviewing on behalf of enejb August 4, 2026 23:01 View session

Copilot AI reviewed Aug 4, 2026

View reviewed changes

Forms: correct the welcome guide's Add fields slide to match the firs…

02f0aab

…t-run template picker

Navigation Menu

Uh oh!

Forms: replace the generic block editor welcome modal with a form editor guide - #51039

Forms: replace the generic block editor welcome modal with a form editor guide#51039
enejb wants to merge 2 commits into
trunkfrom
add/forms-editor-welcome-guide

enejb commented Aug 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 4, 2026 •

edited

Loading

Uh oh!

jp-launch-control Bot commented Aug 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

enejb commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Implementation notes

Related product discussion/links

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

Testing instructions

Screenshots

The guide in context

The five slides

Uh oh!

github-actions Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jp-launch-control Bot commented Aug 4, 2026

Code Coverage Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

enejb commented Aug 4, 2026 •

edited

Loading

github-actions Bot commented Aug 4, 2026 •

edited

Loading

github-actions Bot commented Aug 4, 2026 •

edited

Loading