Update save & submit docs

[jasmussen]

What?

Related to a chat with @keoshi and a few others which revealed shortcomings in the current Storybook guidance on save & submit ux. This expands it to notably suggest that autosave and manual save are both valid supported methods, but you should choose one, not mix both.

Testing Instructions

npm run storybook:dev

Use of AI Tools

Yes.

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Required label: Any label starting with [Type].
• Labels found: [Type] Enhancement, [Type] Developer Documentation.

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

[keoshi]

Thanks for writing this up, @jasmussen!

A few things that stand out to me:

Partial success is not included

Right now the documentation covers a full success (snackbar) and a full failure, with nothing in between. Is it worth underlining the hybrid: tell people what saved and what still needs attention, and never stack a success and an error on top of each other.

There could be more than one invalid field

The Invalid fields section says the page scrolls to the first invalid field. That's right when there's a single error and the field is on screen. But it doesn't cover the case when there are several required fields, or multiple errors scattered across it. Those are the scenarios behind the idea of the error summary:

Another thing: it says the page scrolls to the field and it should say focus moves there, otherwise keyboard and screen reader users won't follow.

Guidance for ConfirmDialog on failed save

As far as I can tell, that dialog has both confirm and cancel buttons, and it closes on ESC/click outside. For a save that failed, there's no decision for the user to make, the message can be dismissed by accident, and it covers the fields they need to go fix. A regular error Notice keeps the form visible is the more permanent indication that it needs their attention.

Removing the toggle label guidance

The old Auto-save section included guidance that seems important to preserve: "keep labels short", "lead labels with a verb like Use, Allow, Show or Enable", and "prefer a toggle over a checkbox for on/off".

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: keoshi <keoshi@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[jasmussen]

Fantastic feedback, I addressed all of it. Let me know if this resonates!