UI: add ControlWithError component

[oandregal]

Part of #81230

Note

Built on top of #81358 (Spinner), which should land first.

What?

Moves ControlWithError (and its internal ValidityIndicator) to @wordpress/ui, and replaces the copies in @wordpress/components and @wordpress/dataviews with the new component.

Why?

See #81230.

How?

The component is ported as-is behavior-wise, adapted to the @wordpress/ui conventions: CSS modules on WPDS design tokens with wp-ui cascade layers, render prop support via useRender/mergeProps, ui Icon + Spinner for the validity indicator, and wp-admin global CSS defense. The wrapper no longer hardcodes a package class — consumers pass their legacy class instead, so the existing :has()-based invalid styles keep working:

<ControlWithError
	className="dataviews-validated-control"
	required={ required }
	getValidityTarget={ () => inputRef.current }
>
	<InputControl ref={ inputRef } label="Text" />
</ControlWithError>

Testing Instructions

1. npm run test:unit -- packages/ui/src/control-with-error packages/components/src/validated-form-controls packages/dataviews/src/components/validated-form-controls
2. In Storybook (npm run storybook:dev), check the new stories under Design System > Components > Form > ControlWithError, plus the existing Components > Selection & Input > Validated Form Controls > Overview and DataViews > DataForm > Validation stories: submitting with empty required fields shows inline errors and red borders, exactly as on trunk.

Testing Instructions for Keyboard

Tab into a required field in the stories above, tab out to blur it, and press Enter on the Submit button: the error message is announced (associated via aria-describedby), and focus moves to the first invalid control on submit.

Use of AI Tools

Authored with Claude Code (Claude Fable 5), including the port, consumer updates, and test migration; reviewed and verified by the author.

[oandregal]

There are some commits that don't belong to this branch and are part of trunk. They're listed here because this PR started on a newer trunk version than the base had (spinner branch): the reason for that is that I wanted to work with all the recent vendored PRs for DataViews (e.g., togglecontrol). This will self-fix itself when the base branch is updated to latest trunk.

[oandregal]

There are some commits that don't belong to this branch and are part of trunk. They're listed here because this PR started on a newer trunk version than the base had (spinner branch): the reason for that is that I wanted to work with all the recent vendored PRs for DataViews (e.g., togglecontrol). This will self-fix itself when the base branch is updated to latest trunk.

This was the wrong trade-off: it prevented us from reviewing code changes here. So I rebased this onto the base. I'll get the latest trunk commits when the base is merged/updated.

[oandregal]

There are cases that are not well served by ControlWithError today. One such a case is DataForm date operator, which comes with a range control (from-to inputs, not a single one):

If we wrapped every single control by ControlWithError we'd get error message on each individual control, but we actually want this to act as a single coordinated control (single error message).

Related conversation.

[mirka]

we'd get error message on each individual control

The first approach I would try is using a ValidatedInputControl for each date field, but by default get the errors to mark the first field. Most errors can be marked on the first field, even if it's technically an error for both fields combined, e.g. "End date is earlier than start date", "Please fill in this field" (when both fields are empty), etc. In the screenshot's case where it's clearly the second field that should get the error, then you mark the second field. If that's a problem visual-wise, then I think you could maybe just mark the first field for all errors, even if it's like "Please fill in the end date". As long as we have an appropriate fieldset grouping or something.

Would that work, or are there other cases?

I think you generally do need to mark (semantics + focus) exactly one element for any given error. Otherwise we'd have accessibility complications. Let me know if you have any other ideas.

[oandregal]

ControlWithError handles the messaging and also the styles of that message (red/green based on invalid/valid state). However, the consumer needs to also set other styles (e.g., border to red in invalid state) based on the data-validity-visible data attribute, etc.

This is a necessary first step, but it is also too low-level and requires tight coordination with how this works. We need to have the validated controls in UI to make this seamless to consumers.

[mirka]

I'll also look into some ways to make custom composition easier.

[oandregal]

This should be replaced by the actual validated control that uses ControWithError in follow-ups.

[mirka]

Switched to a more generic fixture for purity instead (026550c). This would also check that we're not implicitly relying on Base UI behaviors.

[oandregal]

This has been moved from the ControWithError test verbatim.

[mirka]

This was actually a regression test for a bug fix in ControlWithError itself, and since ValidatedRangeControl can plausibly be removed altogether at some point, I moved this test back (as a more generic version) to the ControlWithError suite (e86579d).

[oandregal]

Moved to the own control's test suite.

[oandregal]

I've tested these changes across UI, DataViews, and Components packages (validated controls) and it's working as expected.

[github-actions]

Flaky tests detected in f19010a.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/32366112047
📝 Reported tests:

Should save the changes in /test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js, passed after 2 failed attempts.

TimeoutError: page.waitForFunction: Timeout 10000ms exceeded.
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js:34:14
TimeoutError: locator.click: Timeout 10000ms exceeded.
Call log:
  - waiting for locator('role=button[name="Visual"i]')

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js:33:55

[mirka]

Looks good! Thanks for the move, thoughtfully executed. I went ahead and made some tweaks.

Since it seems you'll be away tomorrow, in the interest of time I'll look into the uncontrolled mode thing and see if it's something we can punt for this PR.

[mirka]

we'd get error message on each individual control

The first approach I would try is using a ValidatedInputControl for each date field, but by default get the errors to mark the first field. Most errors can be marked on the first field, even if it's technically an error for both fields combined, e.g. "End date is earlier than start date", "Please fill in this field" (when both fields are empty), etc. In the screenshot's case where it's clearly the second field that should get the error, then you mark the second field. If that's a problem visual-wise, then I think you could maybe just mark the first field for all errors, even if it's like "Please fill in the end date". As long as we have an appropriate fieldset grouping or something.

Would that work, or are there other cases?

I think you generally do need to mark (semantics + focus) exactly one element for any given error. Otherwise we'd have accessibility complications. Let me know if you have any other ideas.

[mirka]

This was actually a regression test for a bug fix in ControlWithError itself, and since ValidatedRangeControl can plausibly be removed altogether at some point, I moved this test back (as a more generic version) to the ControlWithError suite (e86579d).

[mirka]

Switched to a more generic fixture for purity instead (026550c). This would also check that we're not implicitly relying on Base UI behaviors.

[mirka]

I'll also look into some ways to make custom composition easier.

[mirka]

Was this newly added in this PR? Can it be punted to a separate PR so we can discuss/review/test without blocking this migration PR? Or is it actually a blocker to the migration?

I think I understand what this is trying to solve, but some initial concerns with the approach:

• ControlWithError isn't just for inputs.
• The validated components are documented to only support controlled usage at the moment. This is just because we didn't have time to test uncontrolled use cases, but that also means that uncontrolled use cases are really not tested at all yet. So it's unclear whether this particular approach is sufficient to now fully support uncontrolled mode, or if there are bad interactions that are still unaccounted for.

If this is a real blocker, we can merge and follow up later, but if not, I think it'd be safer to remove for now. (Also consider using controlled mode if possible.)

[mirka]

As far as I could tell, this was never on trunk and is not used in any production instances, so I'll go ahead and remove it for now (d596cc9).

[mirka]

This is temporary — I plan on changing the styling architecture so that this is less fragile. Maybe ControlWithError adds a data-has-visible-error data attribute to the underlying control component directly (not the raw validity target element), and the controls components are responsible for styling themselves based on that.

[oandregal]

@mirka wouldn't this cause issues if a consumer uses a DataViews version that depends on the ControlWithError or ValidityIndicator components exposed via the wp.components.privateApis global?

[oandregal]

I got the impression that we shouldn't remove these private APIs but rather deprecate them and keep them for 2 major WordPress versions (related).

[oandregal]

Actually, scratch that. I just double-checked plus checked history and they had never been exported via the private APIs.