From f5154f2b0898a22129f2ceb928cd4b9ee91db25f Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 6 Sep 2026 07:27:08 +0000 Subject: [PATCH 1/2] docs(fields): attribute option `description` to objectui, not to the spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `content/docs/fields/lookup.mdx` told readers that `SelectOptionMetadata`'s option `description` is "aligned with `@objectstack/spec`'s `SelectOptionSchema.description`". Re-measured today against the installed `@objectstack/spec` 17.2.0, that schema declares exactly `color, default, label, value, visibleWhen` and refuses `description` by name with `unrecognized_keys`; `FieldSchema` routes a field's `options` through it, so the sentence was inviting a write that fails the whole field with a 422. The page now carries the same attribution PR #7510 gave the published JSDoc on `SelectOptionMetadata.description`: an objectui-side read-model extension the spec refuses by name, declared because `LookupField` consumes it, and never to be written into an authored object document. The key itself stays declared and stays consumed. The still-unconsumed `.changeset/6140-field-metadata-rows-option-description.md` carried the same false claim on both keys it declares, scheduled to ship into the CHANGELOG. Corrected in place as a deliberate prose correction, which `scripts/check-changeset-overwrite.mjs` documents as its case 2 and reports without failing; every package name the declaration carried at base is unchanged, so nothing is lost from it. Docs and changeset prose only — no type, schema, export or runtime path moves. Settles objectui#7537. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01MM7kaS4dPpYHV5BsMyu4tQ --- ...-field-metadata-rows-option-description.md | 26 ++++++++++++++----- content/docs/fields/lookup.mdx | 14 +++++++--- 2 files changed, 31 insertions(+), 9 deletions(-) diff --git a/.changeset/6140-field-metadata-rows-option-description.md b/.changeset/6140-field-metadata-rows-option-description.md index bfd2e15e26..9df2d42596 100644 --- a/.changeset/6140-field-metadata-rows-option-description.md +++ b/.changeset/6140-field-metadata-rows-option-description.md @@ -9,15 +9,29 @@ the widget reads they legalize: - `MarkdownFieldMetadata.rows` and `HtmlFieldMetadata.rows` (`@object-ui/types`) — the inline-editor height `RichTextField` has always read through an - `as any` (default 8), aligned with the `TextareaFieldMetadata` precedent and - `@objectstack/spec` `FieldSchema.rows` (positive integer, multiline editor - types). The four inert editor keys (`toolbar`/`preview`/`minHeight`/ + `as any` (default 8), following the `TextareaFieldMetadata` precedent. NOT a + spec key: `@objectstack/spec` `FieldSchema` refuses `rows` BY NAME + (`unrecognized_keys`) on all four of textarea/markdown/html/richtext, so it is + an objectui render hint that must not be written into authored object + metadata. The four inert editor keys (`toolbar`/`preview`/`minHeight`/ `maxHeight`) stay deliberately undeclared and are pinned so. - `SelectOptionMetadata.description` — secondary option text `LookupField` - searches on authored static options and emits from `recordToOption`, - aligned with `@objectstack/spec` `SelectOptionSchema.description`. + searches on authored static options and emits from `recordToOption`. NOT a + spec key either: `@objectstack/spec` `SelectOptionSchema` is strict over + exactly `{label, value, color, default, visibleWhen}` and refuses + `description` BY NAME, and `FieldSchema` routes `options` through that schema, + so the key must never reach authored object metadata. - `RichTextField` and `TextAreaField` (`@object-ui/fields`) now read their metadata through the declared types instead of `field as any` (the spec-face `maxLength` dual-read in `TextAreaField` stays as a documented structural read). Behaviour unchanged; `rows` and option `description` are now legal to - author with an annotated literal. + author in an objectui **annotated literal** — never in an object document sent + to the platform. + +Both spec attributions above were corrected in place before release +(objectui#7537): as first written this changeset claimed each key was "aligned +with" a `@objectstack/spec` schema member that does not exist. Re-measured on +`@objectstack/spec@17.2.0`, each refusal is paired with a control that accepts +the same payload minus the key. Same correction as objectui#7014 / PR #7510 made +to the published JSDoc; the package bumps and the declared behaviour are +unchanged. diff --git a/content/docs/fields/lookup.mdx b/content/docs/fields/lookup.mdx index 52a59c699c..a098ecb4d1 100644 --- a/content/docs/fields/lookup.mdx +++ b/content/docs/fields/lookup.mdx @@ -63,9 +63,17 @@ const priority: LookupFieldMetadata = { A static option may also carry a `description` — secondary text the picker's typeahead searches alongside the label. It is a declared `SelectOptionMetadata` -member (declared for exactly that consumption — -[objectui#6153](https://github.com/objectstack-ai/objectui/issues/6153) — and -aligned with `@objectstack/spec`'s `SelectOptionSchema.description`). The +member, declared for exactly that consumption +([objectui#6153](https://github.com/objectstack-ai/objectui/issues/6153)), but it +is an **objectui-side read-model extension, not a spec key**. Measured on the +installed `@objectstack/spec` 17.2.0, `SelectOptionSchema` is strict over exactly +`{label, value, color, default, visibleWhen}` and refuses `description` **by +name** (`unrecognized_keys`), with the same option minus the key accepted as the +control. `FieldSchema` routes a field's `options` through that schema, so +authoring `description` on an option in an object document fails the **whole +field** with a 422 — the key lives on the runtime read model the widget consumes +and must never reach authored object metadata +([objectui#7014](https://github.com/objectstack-ai/objectui/issues/7014)). The `dataSource` a host injects and the `onCreateNew` callback it passes are widget props, not metadata. From 1809407d6e31c25b6b21dd00d84fe7e87705b3e5 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 6 Sep 2026 07:59:19 +0000 Subject: [PATCH 2/2] docs(fields): drop the version literal from the option `description` note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `scripts/__tests__/doc-version-claims.test.ts` refuses a version literal on the surfaces it scans, and the sentence added by the previous commit carried one: "Measured on the installed `@objectstack/spec` 17.2.0". The pin is right — a version frozen in prose is the objectui#3645 shape, where a spec range sat in 36 READMEs across thirteen majors because no review step ever asked whether it was still true. The literal is deleted rather than added to KNOWN_CLAIMS, which is what the pin's own message asks for. The sentence now reads "Measured on the installed `@objectstack/spec`"; the version of that reading lives in the pull request body and on the card, where it is dated and cannot silently go stale. Every other byte of the sentence is unchanged, so the attribution the card asked for is intact. The changeset corrected in the previous commit keeps its literal: the pin's SCAN_ROOTS are content/docs, packages/*/README.md and skills, so `.changeset` is outside its population — and a changeset is a dated release note about a measurement already taken, which is the one place a version literal cannot rot. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01MM7kaS4dPpYHV5BsMyu4tQ --- content/docs/fields/lookup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/fields/lookup.mdx b/content/docs/fields/lookup.mdx index a098ecb4d1..3a4f711059 100644 --- a/content/docs/fields/lookup.mdx +++ b/content/docs/fields/lookup.mdx @@ -66,7 +66,7 @@ typeahead searches alongside the label. It is a declared `SelectOptionMetadata` member, declared for exactly that consumption ([objectui#6153](https://github.com/objectstack-ai/objectui/issues/6153)), but it is an **objectui-side read-model extension, not a spec key**. Measured on the -installed `@objectstack/spec` 17.2.0, `SelectOptionSchema` is strict over exactly +installed `@objectstack/spec`, `SelectOptionSchema` is strict over exactly `{label, value, color, default, visibleWhen}` and refuses `description` **by name** (`unrecognized_keys`), with the same option minus the key accepted as the control. `FieldSchema` routes a field's `options` through that schema, so