DataForm: document decision criteria when to use it or not

[jsnajdr]

Decision criteria for AI agents for whether to use DataForm in a given situation. Here for a potential "login form" component.

[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: [Package] DataViews.

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.

[fcoveram]

Here are descriptions for each of the examples, if useful:

Login form
Capture and validate a user’s credentials to start an authenticated session. DataForms is used to render the login fields from a field definition (e.g., username/email, password, remember-me) and emit partial updates as the user types, so the screen can control validation and submit the final credentials.

Search form
Let users define search criteria to find items in a dataset, from simple keyword search to advanced filters (status, author, date ranges, taxonomy, etc.). DataForms is used to present a structured set of filter fields (often grouped into sections/panels), collect changes as a single “criteria object,” and pass those criteria to the search/query logic when applied.

Post editor
Let editors manage structured fields associated with a post (custom fields/meta, attributes, taxonomies, editorial details) alongside the main content. DataForms standardizes how those metadata fields are displayed, edited, and validated, while keeping the underlying post/meta data model consistent.

Media editing
Provide a focused details panel/page for a single media item where users can view and edit metadata (alt text, caption, credit/license, organization fields). DataForms supplies a consistent editing experience and validation for these fields, while the product handles saving back to the media record.

Simple settings page
Provide a lightweight screen to edit a small number of related configuration values (usually one section, minimal grouping). DataForms renders a straightforward layout from a short field list, enabling quick edits and predictable updates that the product can save as one settings object.

Complex settings page
Provide an organized, scalable interface for editing many settings with clear grouping, conditional structure, and consistent validation—often spanning multiple categories (e.g., General, Security, Integrations, Notifications). DataForms is used to define fields once and control the screen structure via the form layout (sections/panels/rows/cards), while emitting granular updates so the product can manage dependencies, validation state, and save workflows.

[mirka]

Let's remove this, the package is not ready for this kind of use yet.

[jsnajdr]

At this moment, is the right answer to use InputControl, TextControl, the versions without the Validated prefix? For the "don't need validation" scenario?

[mirka]

Right, something like this:

Suggested change

	- If **no** → use components from `@wordpress/ui` (like `Field`, `Input`, `Button`, etc.). These provide a clean, accessible form structure without validation overhead.
	- If **no** → use components from `@wordpress/components` (like `InputControl`, `SelectControl`, etc.). These provide a clean, accessible form structure without validation overhead.

I've attempted to make it clearer to not use @wordpress/ui yet.

[mirka]

Remove too

[fcoveram]

I would move these two sections into a new one above the "When in doubt…" that says "Do not use in…".

[fcoveram]

I would replace the "Let users define search criteria…" with "Don't use DataForm when the goal is…"

[fcoveram]

I added two comments, but the rest looks correct to me.