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

Summary

Aurora's schema-driven forms (content add/edit, control panels, block settings) render each field through one dispatcher, Field.tsx, which looks up a widget in the registry and renders it. Right now there is no defined contract between the form and the widgets. Each side guesses what the other one sends, and the guesses don't match. As a result:

• no text field shows its required marker or its validation errors;
• most registered widgets ignore some of the props they receive;
• some widgets only work inside the content edit route;
• add-on authors can't know what props their widget will get, or what value it should emit.

This issue lists the inconsistencies on main (as of ca58740) and proposes a contract plus a plan to fix it in separate PRs.

#97 started this work. It adds a conceptual guide ("Form fields, controls, and widgets") and a first FormWidgetProps / FormWidget type in @plone/types. This issue is the inventory and roadmap behind it.

Vocabulary (from #97)

• Field: one piece of form data: name, value, validation state, schema metadata. It is owned by TanStack Form.
• Control: a design-system interaction component (@plone/quanta, React Aria). It has its own API (isSelected, isRequired, DateValue…) and knows nothing about Plone.
• Widget: what the registry returns for a schema field. It takes the widget contract and emits normalized values.
• Adapter: a widget that wraps a control and maps the contract to the control's API.

Rule: controls are never registered directly. Only widgets are.

Inconsistencies on main

A. Form side (what the forms send to widgets)

1. Raw schema properties are spread into the widget props. All three forms do {...schema.properties[schemaField]}: ContentForm.tsx#L116, controlpanel.tsx#L115, BlockSettingsFormRenderer.tsx#L45. Widgets therefore receive type, title, default, factory, minLength, onChangeSideEffects, etc. mixed in with real props. type: "string" | "integer" | "array" collides with the type attribute of the default TextField, which spreads its props onto React Aria TextField.
2. The field rendering loop is copied three times. Each copy builds props slightly differently: content and control panel pass formAtom and value, block settings passes getFieldProps. There is no single place that builds widget props.
3. defaultValue is set to the current value. defaultValue={field.state.value} sits next to value={field.state.value} (ContentForm.tsx#L122, controlpanel.tsx#L119). The schema default is never passed as such. Some widgets (ObjectBrowserWidget) only work because they read defaultValue once on mount.
4. Errors are passed as error: unknown[], which no control understands. Quanta controls expect errorMessage and isInvalid, because React Aria's FieldError renders nothing unless the field is invalid. Today only BooleanWidget converts error itself. No other widget ever shows a validation error.
5. required is passed, but controls expect isRequired. Text, date, datetime and radio-based widgets never show the required state.
6. onBlur is not wired, so TanStack Form's touched state and blur validation never run. (Document and type the form widget contract #97 adds this.)
7. Every widget gets a placeholder. placeholder: fieldProps.placeholder || 'Type something...' (Field.tsx#L186) applies to checkboxes, pickers and so on, and it isn't translated.
8. The caller's label is overwritten. label: fieldProps.title (Field.tsx#L185) replaces the label the caller passed.
9. No disabled / readOnly. Schema readonly and form-level disabled states are not mapped to anything.
10. Naming. The dispatcher is registered as the TanStack field component Quanta (Form.tsx), so call sites read <field.Quanta>. The name points to a design system instead of the role ("schema field").

B. Widget resolution

1. An unknown widget name falls back to the default widget instead of continuing the lookup. Field.tsx#L79 returns getWidgetDefault(), so choices, vocabulary, factory and type are never tried. This is the cause described in Add Image Content tab crashes because the image field is rendered as a TextField #163: widget: "file" is not registered, so the factory is never consulted and the field gets a TextField. Today that still affects the File type's file field. Image's image field only escapes because of B2.

2. config.getWidget(key) ignores the category. It searches every category (id, widget, vocabulary, factory, type) and returns the first hit (registry index.ts#L606). The categories are therefore only labels: a field named image matches the image widget, and getWidgetByType('boolean') only works because boolean is (wrongly) registered under the widget category (widgets.ts#L30).

3. choices / vocabulary lookup returns nothing. config.widgets.choices is read (Field.tsx#L152) but never registered, so select and vocabulary fields render as a text input.

4. Core Plone widgets are missing from the registry:

   • textarea: plone.restapi sends it for description, and Quanta already has TextAreaField;
   • number/integer;
   • array / tokens (subjects);
   • file;
   • password, email, url.

   All of them render as a single-line TextField.

C. Widgets (what widgets accept and emit)

This breaks the requirement already stated in #6: widgets should be "dumb" components that receive the data as props, set data in onChange, with no external dependencies.

D. Types

• WidgetsConfigById/ByWidget/ByFactory/ByType/ByVocabulary are all React.ComponentType<any>, so registerWidget accepts any component and the contract can't be checked at compile time.
• There is no shared props type. Each widget declares its own (BaseFormFieldProps = Pick<QuantaTextFieldProps, …> in three files, BooleanWidgetProps, the dispatcher's FieldProps). Document and type the form widget contract #97 adds FormWidgetProps<T> / FormWidget<T>.

Proposed contract

What every widget receives (FormWidgetProps<T>)

interface FormWidgetProps<T> {
  // identity
  id: string;                 // unique DOM id, built by the form
  name: string;               // field path in the form data

  // value
  value?: T | null;           // stored value; null/undefined when empty
  onChange: (value: T) => void; // always emits the normalized value (T includes null for clearable widgets)
  onBlur?: () => void;

  // presentation
  label?: string;
  description?: string;
  placeholder?: string;       // only when the schema provides one

  // state, already normalized by the form
  required?: boolean;
  disabled?: boolean;
  readOnly?: boolean;
  invalid?: boolean;
  errorMessage?: string;      // joined, translated message

  // data sources
  choices?: Array<[value: string, label: string]>;
  vocabulary?: { '@id': string };

  // escape hatch: the raw field schema, never spread
  schema?: FieldSchema;
}

Plus any widgetProps from frontendOptions (tagged values), merged on top as widget-specific props.

Rules

1. The form normalizes and the widget renders. Converting errors, mapping required, resolving labels and applying defaults all happens once, in the dispatcher. Widgets never see error, title or default.
2. Widgets are controlled. They render value and report changes through onChange. They don't keep a parallel source of truth, and they don't read form atoms or route loaders.
3. The value shape is per widget and documented. Each registered widget names the JSON value it emits, and that value must be what plone.restapi accepts (e.g. date → "YYYY-MM-DD", datetime → ISO 8601 with offset, relations → [{ '@id': … }], boolean → boolean). Conversion to and from control types (DateValue, Brain) happens inside the adapter.
4. Widgets get context through a hook, not imports. Widgets that need the content (object browser: current path) or sibling values (recurrence: start/end) use a widget context hook provided by every form (e.g. useWidgetContext() → { content, getFieldValue, setFieldValue }). Updates to sibling fields go through that hook or the existing schema-level onChangeSideEffects (already used by block settings), not through extra onChange arguments.
5. Controls stay in @plone/quanta, widgets live in @plone/cmsui. Every registered entry is an adapter (or a native widget) typed FormWidget<T>.
   • The API a component speaks decides its package, not how simple it is. Quanta is the CMS design system: it speaks React Aria, doesn't know the widget contract, and doesn't depend on @plone/types. An adapter speaks the widget contract, so it lives in cmsui, however small it is. BooleanWidget is the example: a few lines mapping value → isSelected, but an adapter, so it stays in cmsui next to ObjectBrowserWidget.
   • Quanta components are named after what they are. AlignWidget, SizeWidget and WidthWidget are controls (typed Omit<RadioGroupProps, 'children'>) named like widgets, which is what makes them look like peers of BooleanWidget. They get cmsui adapters, and are renamed (step 4).
   • A form for another audience (e.g. the public form generator, [Aurora] - Form generator #93) uses its own design system's controls, so it needs its own adapters. If adapters ever need to be shared between the CMS and public forms, they go in a package between the design systems and the apps, not inside one design system.
   • Documented in the guide's "Where controls and widgets live" section (Document and type the form widget contract #97).
6. Resolution is deterministic and category-scoped. id → frontendOptions.widget → widget → choices/vocabulary → factory → type → default. Each step looks only in its own category, and a miss continues to the next step.

Plan (one PR per item)

• 1. Contract types and docs: Document and type the form widget contract #97 (open). Add FormWidgetProps / FormWidget to @plone/types and the conceptual guide, and wire onBlur. Update the guide to describe the contract above and link back here.

• 2. One schema field renderer for all forms: Render every schema form through one field renderer #251 (open, stacked on Document and type the form widget contract #97). Pull the field loop and prop building out of ContentForm, controlpanel and BlockSettingsFormRenderer into one shared function that builds props from an allowlist (no schema spreading). In it:

  • convert errors to invalid + errorMessage;
  • map required, readonly → readOnly, and disabled;
  • pass the schema default correctly instead of defaultValue = value;
  • remove the forced placeholder;
  • pass schema as its own prop;
  • rename field.Quanta → field.SchemaField.

  Covers A1–A10.

• 3. Fix widget resolution: Scope widget lookups to their category #249 (merged).

  • getWidget(key, category?) in @plone/registry, scoped lookup in Field.tsx;
  • an unknown widget name falls through instead of returning the default;
  • register boolean under type;
  • unit tests for the resolution order.

  Covers B1–B2 and unblocks Add Image Content tab crashes because the image field is rendered as a TextField #163.

• 4. Adapters for the controls registered today: Validate schema-driven forms #256 + Add adapters for the remaining registered controls #260 (open, stacked). Covers C rows 1–4.

  • BooleanWidget on the shared FormWidgetProps, with no error conversion of its own: Document and type the form widget contract #97 / Render every schema form through one field renderer #251.
  • TextWidget (the default widget) and DateTimeWidget: Validate schema-driven forms #256, needed to show validation errors.
  • TextareaWidget (register textarea): Add adapters for the remaining registered controls #260.
  • DateWidget: Add adapters for the remaining registered controls #260, around the Quanta DatePicker, which already works with ISO strings.
  • Cmsui adapters for align/size/width, registered under align, size and width: Add adapters for the remaining registered controls #260.
  • Renamed Quanta's AlignWidget, SizeWidget and WidthWidget to AlignPicker, SizePicker and WidthPicker (after Quanta's DatePicker), keeping the old names as deprecated aliases (rule 5): Add adapters for the remaining registered controls #260.

• 5. Widget context, and decoupled widgets: Give widgets a context instead of the route #261 (open, stacked on Add adapters for the remaining registered controls #260). Closes Add Image Content tab crashes because the image field is rendered as a TextField #163.

  • useWidgetContext() (mode, path, containerPath), provided by the content form, the control panels and (through the content form) the block settings. Form values are read with the @plone/helpers hooks.
  • ObjectBrowserWidget: starts from the context instead of the edit route's data; its selection follows value.
  • RecurrenceWidget: reads its own value; reads start / end through the form hooks (no global formAtom since Move the forms onto the helpers form store #253).
  • ImageWidget: browses and uploads from the context instead of the URL (Add Image Content tab crashes because the image field is rendered as a TextField #163); its extras go to sibling fields through the extraFields widget option.
  • QuerystringWidget: no edit-route read.
  • Document the relation value shape the object browser emits: the "Core widgets" reference, in Give widgets a context instead of the route #261.

• 6. Typed registry and contract tests: Type-check registered widgets and test them against the contract #262 (open, stacked on Give widgets a context instead of the route #261).

  • The widget registry types its slots with the props an app declares in WidgetPropsMap (@plone/types); @plone/cmsui declares FormWidgetProps, so a non-conforming widget is a type error in Aurora, while Volto, which declares nothing, is unaffected. It found and fixed one mismatch (ObjectBrowserWidget's widgetOptions).
  • describeWidgetContract (@plone/cmsui/testing/widgetContract), run by every core widget; documented for add-ons.
  • Per-widget value shapes and widget options: the "Core widgets" reference, in Give widgets a context instead of the route #261.

• 7. Missing core widgets. (Add the missing core widgets #263) Choices/select (B3), number/integer, array/tokens ([CMSUI Widgets] - ArrayWidget #8), file (Add Image Content tab crashes because the image field is rendered as a TextField #163), password/email/url. Each one built against the contract and passing the contract tests. Tracks [CMSUI] - Widgets #6.

Steps 2 and 3 are independent and can go in parallel. Step 4 depends on 2 (so adapters receive normalized props). Step 6 is easier once 4 and 5 have landed.

Related: #6, #8, #9, #89 (display mode widgets: same contract, read-only side), #93 (generic form generator: should reuse the renderer from step 2), #97, #163.