Document and type the form widget contract by sneridagh · Pull Request #97 · plone/aurora

sneridagh · 2026-06-04T10:19:50Z

Step 1 of #243 (define and enforce the form widget contract).

Adds the conceptual guide "Form fields, controls, and widgets", which explains the field / control / widget / adapter split and the rule that only widgets are registered.
Adds the shared FormWidgetProps<T> / FormWidget<T> types to @plone/types. value comes in as T | null (it can be empty) and onChange emits a normalized T.
BooleanWidget now uses the shared type.
Field.tsx wires onBlur to TanStack Form (touched state and blur validation), converts error to errors / errorMessage, and stops overwriting a label passed by the caller.

The BooleanWidget adapter itself landed on main with #220. This PR now carries the contract types and docs. The remaining inconsistencies are tracked in #243, which has the plan for follow-up PRs.

Originally transferred from plone/volto#8309, and supersedes plone/volto#8237 and plone/volto#8247.

* seven: Update README with the Plone Aurora Seven querystringWidget (#8017) [Seven] Add `renderEmptyState` to `Table` component (#8308) Recurrence widget (#7200)

Co-authored-by: Steve Piercy <web@stevepiercy.com>

stevepiercy · 2026-06-05T06:31:06Z

@sneridagh https://www.dlr.de/de keeps timing out in the README linkcheck.

stevepiercy

I still don't have a firm grasp of the differences between field, control, and widget. Adapter kind of makes sense to me as the glue between a control and a widget. Is there a diagram or external documentation that we can reuse? I need a picture or more code examples.

In my tiny dinosaur brain:

A control is the HTML form control and its attributes, per https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Basic_native_form_controls.
A field, I think in this context, is similar to a column in a relational database.
A widget would be something such as a date range picker, a sequence of dependent selects, or allows callbacks from the client.

We should also add all these terms into a glossary.

stevepiercy · 2026-06-05T06:43:23Z

+## Design implications
+
+The form generator should be basic.
+It should resolve widgets, pass normalized field props, and connect changes back to form state.


Suggested change

It should resolve widgets, pass normalized field props, and connect changes back to form state.

It should resolve widgets, pass normalized field props, and connect changes back to the form state.

stevepiercy · 2026-06-05T06:46:02Z

+It should not contain special cases for checkbox selection state, date serialization, upload workflows, relation values, or vocabulary fetching.
+
+Widgets should own those differences.


I think this sentence belongs better with the previous paragraph, forming a complete concept of what it means to keep the form generator basic.

Then the next paragraph explains why that's advantageous, and where the complicated pieces belong.

Suggested change

It should not contain special cases for checkbox selection state, date serialization, upload workflows, relation values, or vocabulary fetching.

Widgets should own those differences.

It should not contain special cases for checkbox selection state, date serialization, upload workflows, relation values, or vocabulary fetching.

Widgets should own those differences.

stevepiercy · 2026-06-05T06:47:25Z

+
+(form-fields-controls-and-widgets-label)=
+
+# Form fields, controls, and widgets


Suggested change

# Form fields, controls, and widgets

# Form fields, controls, widgets, and adapters

stevepiercy · 2026-06-05T06:47:53Z

+  html_meta:
+    "description": "An explanation of fields, controls, widgets, and widget adapters in Seven forms"
+    "property=og:description": "An explanation of fields, controls, widgets, and widget adapters in Seven forms"
+    "property=og:title": "Form fields, controls, and widgets"


Suggested change

"property=og:title": "Form fields, controls, and widgets"

"property=og:title": "Form fields, controls, widgets, and adapters"

stevepiercy · 2026-06-05T06:48:17Z

+    "description": "An explanation of fields, controls, widgets, and widget adapters in Seven forms"
+    "property=og:description": "An explanation of fields, controls, widgets, and widget adapters in Seven forms"
+    "property=og:title": "Form fields, controls, and widgets"
+    "keywords": "Seven, forms, fields, controls, widgets, @tanstack/form, @plone/cmsui"


Suggested change

"keywords": "Seven, forms, fields, controls, widgets, @tanstack/form, @plone/cmsui"

"keywords": "Aurora, forms, fields, controls, widgets, adapters, @tanstack/form, @plone/cmsui"

stevepiercy · 2026-06-05T06:48:49Z

+    "description": "An explanation of fields, controls, widgets, and widget adapters in Seven forms"
+    "property=og:description": "An explanation of fields, controls, widgets, and widget adapters in Seven forms"


Suggested change

"description": "An explanation of fields, controls, widgets, and widget adapters in Seven forms"

"property=og:description": "An explanation of fields, controls, widgets, and widget adapters in Seven forms"

"description": "An explanation of fields, controls, widgets, and widget adapters in Aurora forms"

"property=og:description": "An explanation of fields, controls, widgets, and widget adapters in Aurora forms"

stevepiercy · 2026-06-05T06:49:10Z

+
+# Form fields, controls, and widgets
+
+Seven forms are schema-driven.


Suggested change

Seven forms are schema-driven.

Aurora forms are schema-driven.

stevepiercy · 2026-06-05T06:49:22Z

+The form state system asks, "What is the value and validation state of this field?"
+The widget registry asks, "Which widget should render this field?"
+
+Seven can resolve a widget from several schema hints.


Suggested change

Seven can resolve a widget from several schema hints.

Aurora can resolve a widget from several schema hints.

stevepiercy · 2026-06-05T06:50:58Z

+
+## Control
+
+A control is a lower-level interactive component.


Lower-level than what? Field? Widget?

stevepiercy · 2026-06-05T06:51:34Z

+import { BooleanWidget } from './BooleanWidget';
+
+const meta = {
+  title: 'CMS UI/Widgets/BooleanWidget',


Suggested change

title: 'CMS UI/Widgets/BooleanWidget',

title: 'CMSUI/Widgets/BooleanWidget',

@ControlPanels

Wire the control panel action to PATCH @ControlPanels, port the BooleanWidget adapter from #97 so boolean fields show their label and value, and replace the react-aria toolbar buttons in the control panel routes, whose onPress never fires inside the toolbar's shadow root.

* origin/main: (190 commits) Make control panels saveable (#220) Public UI: render a single .content-area root (#230) (#234) Remove tsconfig test/spec/story excludes that never matched any file (#222) Add PloneClient.extend() and clientEndpoints utility for custom endpoints (#221) Store the default block width of every top-level block (#190) Releasing @plone/aurora 1.0.0-alpha.19 Release @plone/cmsui 1.0.0-alpha.12 Release @plone/agave 1.0.0-alpha.9 Release @plone/theming 1.0.0-alpha.9 Release @plone/layout 1.0.0-alpha.14 Release @plone/blocks 1.0.0-alpha.18 Release @plone/plate 1.0.0-alpha.25 Release @plone/registry 4.0.0-alpha.5 Release @plone/quanta 1.0.0-alpha.2 Content CSS Phase 11: theming guide for blocks and cleanup (#219) Rename the Plone blocks' classnames to the content contract (#218) Share the block spacing between the Public UI and the editor (#217) Content CSS Phase 8: structural blocks and content root to styles/content.css (#216) Remove the Plate media nodes from Aurora's presets (#215) Move the table styles to styles/content.css (#214) ... # Conflicts: # packages/cmsui/components/BooleanWidget/BooleanWidget.stories.tsx # packages/cmsui/components/BooleanWidget/BooleanWidget.test.tsx # packages/cmsui/components/BooleanWidget/BooleanWidget.tsx # packages/cmsui/news/+boolean-widget-adapter.bugfix

Address the review: add a diagram that follows one field from its schema to its control and back, a comparison with HTML form controls and database columns, worked adapter examples for a boolean and a date widget, and a glossary. Apply the suggested wording and title changes. Add the missing cmsui and docs news fragments.

sneridagh · 2026-10-09T09:34:39Z

@stevepiercy thanks for the review. I reworked the guide in 4ed03e8:

A picture: a new diagram follows one field, exclude_from_nav, from its schema to the checkbox and back (isSelected = true becomes onChange(true)).
Your mental model: a new table compares each concept to what you described. It's mostly right:
- A control is the HTML form control. In Aurora it's usually a Quanta / React Aria component that renders one.
- A field is like a column in a relational table, plus the value being edited and its form state.
- The one difference is widgets: in Plone, every field gets a widget, even a simple text input. Complex pickers are widgets too, but size isn't what makes something a widget; the shared props are.
More code examples: the boolean adapter now comes with a prop mapping table, and there's a second example, a date adapter that converts values (ISO string ↔ DateValue).
"Lower-level than what?": now explicit. A control is the lowest layer, the interactive element itself.
Glossary: the guide ends with a glossary section (field, control, widget, adapter, widget contract, widget registry). Our {term} references resolve to the Plone 6 docs glossary, so if you agree with the definitions, I can open a PR in plone/documentation to add them there.
I applied all your inline suggestions (title, metadata, wording, paragraph order). I used "Plone Aurora" rather than "Aurora", to match the rest of these docs.

The rest of the contract work is tracked in #243.

* origin/main: Scope widget lookups to their category (#249) Subscribe only to the form fields that are read (#248) Give each form its own store and remount it per item (#247) Wait for hydration in sharing acceptance tests (#250)

* origin/main: Fix the recurrence modal crash for events ending on days 1 to 9 (#255)

* origin/main: Validate schema-driven forms (#256) Move the recurrence modal off TanStack Form (#254) Move the forms onto the helpers form store (#253) Add a Jotai-native form layer to helpers (#252) Render every schema form through one field renderer (#251) Document and type the form widget contract (#97) Match utility dependencies exactly in the registry (#259) # Conflicts: # packages/cmsui/config/widgets.ts

…widget-context * origin/feat/widget-adapters: Restore files the pre-commit hook reformatted Validate schema-driven forms (#256) Move the recurrence modal off TanStack Form (#254) Move the forms onto the helpers form store (#253) Add a Jotai-native form layer to helpers (#252) Render every schema form through one field renderer (#251) Document and type the form widget contract (#97) Match utility dependencies exactly in the registry (#259)

…yped-widget-registry * origin/feat/widget-context: Restore files the pre-commit hook reformatted Validate schema-driven forms (#256) Move the recurrence modal off TanStack Form (#254) Move the forms onto the helpers form store (#253) Add a Jotai-native form layer to helpers (#252) Render every schema form through one field renderer (#251) Document and type the form widget contract (#97) Match utility dependencies exactly in the registry (#259)

… feat/missing-widgets * origin/feat/typed-widget-registry: Restore files the pre-commit hook reformatted Validate schema-driven forms (#256) Move the recurrence modal off TanStack Form (#254) Move the forms onto the helpers form store (#253) Add a Jotai-native form layer to helpers (#252) Render every schema form through one field renderer (#251) Document and type the form widget contract (#97) Match utility dependencies exactly in the registry (#259)

sneridagh and others added 5 commits June 2, 2026 15:28

Widgets definition and typings documentation

8e0cf03

Added checkbox widget

45b61a2

Merge branch 'seven' into widgetsDefinitions

9bcb421

* seven: Update README with the Plone Aurora Seven querystringWidget (#8017) [Seven] Add `renderEmptyState` to `Table` component (#8308) Recurrence widget (#7200)

Apply suggestions from code review

3128b35

Co-authored-by: Steve Piercy <web@stevepiercy.com>

Some rephrasing

2cc7d86

sneridagh mentioned this pull request Jun 4, 2026

BooleanWidget and clarify widgets definitions in documentation plone/volto#8309

Closed

stevepiercy requested changes Jun 5, 2026

View reviewed changes

sneridagh mentioned this pull request Oct 4, 2026

Make control panels saveable #220

Merged

9 tasks done

sneridagh mentioned this pull request Oct 8, 2026

Define and enforce the form widget contract (forms ↔ widgets) #243

Open

17 of 22 tasks

sneridagh changed the title ~~BooleanWidget and clarify widgets definitions in documentation~~ Document and type the form widget contract Oct 8, 2026

sneridagh mentioned this pull request Oct 9, 2026

Render every schema form through one field renderer #251

Merged

sneridagh mentioned this pull request Oct 9, 2026

Move the forms onto the helpers form store #253

Merged

Merge remote-tracking branch 'origin/main' into widgetsDefinitions

7308a56

* origin/main: Fix the recurrence modal crash for events ending on days 1 to 9 (#255)

sneridagh mentioned this pull request Oct 9, 2026

Form engine: keep Jotai as the single source of truth, drop the TanStack Form mirror #244

Open

7 tasks

Explain where controls and widgets live in the widgets guide

eb91b88

sneridagh added this pull request to stack #258 October 9, 2026 16:21

sneridagh requested a review from pnicolli October 9, 2026 19:41

pnicolli approved these changes Oct 10, 2026

View reviewed changes

sneridagh merged commit 0084abf into main Oct 10, 2026
42 checks passed

sneridagh deleted the widgetsDefinitions branch October 10, 2026 22:38

	It should resolve widgets, pass normalized field props, and connect changes back to form state.
	It should resolve widgets, pass normalized field props, and connect changes back to the form state.

		It should not contain special cases for checkbox selection state, date serialization, upload workflows, relation values, or vocabulary fetching.

		Widgets should own those differences.


		(form-fields-controls-and-widgets-label)=

		# Form fields, controls, and widgets

	# Form fields, controls, and widgets
	# Form fields, controls, widgets, and adapters

	"property=og:title": "Form fields, controls, and widgets"
	"property=og:title": "Form fields, controls, widgets, and adapters"

	"keywords": "Seven, forms, fields, controls, widgets, @tanstack/form, @plone/cmsui"
	"keywords": "Aurora, forms, fields, controls, widgets, adapters, @tanstack/form, @plone/cmsui"

		"description": "An explanation of fields, controls, widgets, and widget adapters in Seven forms"
		"property=og:description": "An explanation of fields, controls, widgets, and widget adapters in Seven forms"


		# Form fields, controls, and widgets

		Seven forms are schema-driven.

	Seven forms are schema-driven.
	Aurora forms are schema-driven.

	Seven can resolve a widget from several schema hints.
	Aurora can resolve a widget from several schema hints.

	title: 'CMS UI/Widgets/BooleanWidget',
	title: 'CMSUI/Widgets/BooleanWidget',

Conversation

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

Uh oh!

Uh oh!

stevepiercy commented Jun 5, 2026

Uh oh!

stevepiercy left a comment

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!

Choose a reason for hiding this comment

Uh oh!

sneridagh commented Oct 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sneridagh commented Jun 4, 2026 •

edited

Loading