docs(plugin-form): document embeddable-form fields member vocabulary

.changeset/8847-embeddable-form-fields-description.md

@@ -0,0 +1,20 @@
+---
+'@object-ui/plugin-form': patch
+---
+
+`embeddable-form`'s top-level `fields` input now documents its member
+vocabulary (objectui#8847, the last of the registrations #8738 opened — the
+same trap already documented on `object-form`, `form` / `view:form`, and
+`object-master-detail-form`'s parent `fields`).
+
+The registration declared `{ name: 'fields', type: 'array' }` with no
+description, so an author had nowhere to read that this key's members are
+**bare field names** — a different vocabulary from `sections[].fields`, which
+also accepts the spec `FormFieldSchema` object (identity key `field`, e.g.
+`{ field: 'note', colSpan: 2 }`). `EmbeddableForm` passes `config.fields`
+straight through to `<ObjectForm>` with no `sections`, so it renders through
+the same `SimpleObjectForm` read path as `object-form`; moving one of those
+objects into `embeddable-form`'s `fields` resolves to no name and is silently
+skipped. Behaviour is unchanged — this only adds the description text, and
+records (measured, not assumed) that this surface already inherits the
+`console.warn` route 1 (objectui#8738/#8859) added at that same read site.

packages/plugin-form/src/index.tsx

@@ -343,7 +343,7 @@ ComponentRegistry.register('embeddable-form', EmbeddableFormRenderer, {
     { name: 'objectName', type: 'string', required: true },
     { name: 'title', type: 'string' },
     { name: 'description', type: 'string' },
-    { name: 'fields', type: 'array' },
+    { name: 'fields', type: 'array', description: 'Bare field names to show, in order (each looked up in the object schema; `{ name }` is tolerated). NOT the same vocabulary as `sections[].fields`, which also accepts the spec `FormFieldSchema` object (identity key `field`, e.g. `{ field: "note", colSpan: 2 }`) — that shape resolves to no name HERE and is silently skipped (`EmbeddableForm` passes this array straight through to `<ObjectForm>` with no `sections`, so it renders through the same `SimpleObjectForm` as `object-form` above — see its `fields` description).' },
     { name: 'allowMultiple', type: 'boolean' },
   ]
 });