From 5641a9c4169312280f50e7cf65e486b91773009d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 14:44:16 +0000
Subject: [PATCH 1/3] feat(types): declare RichtextFieldMetadata for the
 widget's third registry key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`markdown`, `html` and `richtext` are one widget (objectui#5498). Two of the
three carried an exported metadata type; `richtext` carried none, so the
runtime served it by structure while an author could not write its metadata
under an annotation at all. The only way to write one was
`as unknown as MarkdownFieldMetadata` — a deliberate cast in this repo's own
pin test that was the gap's sole evidence.

`RichtextFieldMetadata` is now exported from `@object-ui/types` and joins the
`FieldMetadata` union, so a richtext field's metadata is a typed literal and
narrows out of the union on `type`. The cast and its comment are gone, and the
surrounding docblock is re-pointed so the gap cannot be rediscovered.

The member's shape was derived from what `RichTextField` reads on the
`richtext` path, not copied from the two siblings: `type`, `rows`,
`placeholder`, `mobile_fullscreen` and `label` (the last three already sit on
`BaseFieldMetadata`), with the readonly branch's cell renderers contributing
no metadata key. `max_length` is declared on the measurement that `richtext`
is symmetric with `markdown`/`html` at the `@objectstack/spec` 17.3.0
authoring boundary, not on the siblings having it.

Additive only: nothing is removed or narrowed, `RichTextField` is unchanged,
and metadata previously written through a cast keeps compiling.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QtGhnU3WnnWyiWeYQhw2aX
---
 .changeset/7083-richtext-field-metadata.md    |  47 +++++
 .../__tests__/RichTextField.rows.test.tsx     |  18 +-
 .../richtext-field-metadata-7083.test.tsx     | 176 ++++++++++++++++++
 packages/types/src/field-types.ts             |  72 +++++++
 packages/types/src/index.ts                   |   1 +
 5 files changed, 308 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/7083-richtext-field-metadata.md
 create mode 100644 packages/fields/src/widgets/__tests__/richtext-field-metadata-7083.test.tsx

diff --git a/.changeset/7083-richtext-field-metadata.md b/.changeset/7083-richtext-field-metadata.md
new file mode 100644
index 0000000000..bd4db19fe4
--- /dev/null
+++ b/.changeset/7083-richtext-field-metadata.md
@@ -0,0 +1,47 @@
+---
+'@object-ui/types': minor
+---
+
+`RichtextFieldMetadata` — the third registry key of `RichTextField` becomes declarable
+(objectui#7083, maintainer ruling 2026-09-07, director decision batch #71).
+
+`markdown`, `html` and `richtext` are one widget (objectui#5498). Two of the three
+already had an exported metadata type; `richtext` had none, so the runtime served it by
+structure while an author could not write its metadata under an annotation at all. The
+only way to write one was `as unknown as MarkdownFieldMetadata`, and that deliberate
+cast — in this repo's own pin test — was the gap's sole evidence. The state was neither
+a union member nor a recorded alias, which is why it had to be rediscovered to be seen.
+
+**New.** `RichtextFieldMetadata` is exported from `@object-ui/types` and joins the
+`FieldMetadata` union, so a richtext field's metadata can be written as a typed literal
+and narrowed out of the union on `type`:
+
+```ts
+import type { RichtextFieldMetadata } from '@object-ui/types';
+
+const doc: RichtextFieldMetadata = {
+  type: 'richtext',
+  name: 'doc',
+  label: 'Release notes',
+  rows: 10,
+  placeholder: 'Write the release notes…',
+};
+```
+
+**Additive only.** Nothing is removed or narrowed: `richtext` field metadata that was
+previously written through a cast keeps compiling, and every other member of the union
+is untouched. The one behavioural surface — `RichTextField` — is unchanged; it already
+served all three keys and this release only gives the third one a face.
+
+**The member's shape was derived, not copied from its two siblings.** `type`, `rows`,
+`placeholder`, `mobile_fullscreen` and `label` are the keys `RichTextField` actually
+reads on the `richtext` path (the last three already sit on `BaseFieldMetadata`, so the
+member declares `type` and `rows`); the readonly branch hands the metadata to a cell
+renderer that reads `value` only and contributes no key. `max_length` is the one
+declared key the widget does not read, and it is there because the cross-check measured
+`richtext` symmetric with `markdown` and `html` on every available axis — one widget and
+one code path, plus `@objectstack/spec` 17.3.0 `FieldSchema` answering identically for
+all three (`rows` admitted, the spec's own `maxLength` admitted, the legacy snake_case
+`max_length` refused by name alike). Omitting it would have left `richtext` the one key
+of the three whose ceiling cannot be authored — a fresh instance of the asymmetry this
+member exists to end.
diff --git a/packages/fields/src/widgets/__tests__/RichTextField.rows.test.tsx b/packages/fields/src/widgets/__tests__/RichTextField.rows.test.tsx
index 031a8050ca..4757897eb1 100644
--- a/packages/fields/src/widgets/__tests__/RichTextField.rows.test.tsx
+++ b/packages/fields/src/widgets/__tests__/RichTextField.rows.test.tsx
@@ -15,8 +15,11 @@
  * 2026-08-25, Option A, aligning the `TextareaFieldMetadata` precedent), so
  * the field literals below carry it under the excess-property check rather
  * than through a cast. The `richtext` registry key resolves to the same
- * widget (objectui#5498) with no union member of its own, so its case is the
- * one deliberate `as` in this file.
+ * widget (objectui#5498) and now has a union member of its own too
+ * (`RichtextFieldMetadata`, objectui#7083), so all three literals here are
+ * annotated and this file holds no `as` at all — the deliberate cast that used
+ * to sit on the richtext case WAS the only evidence that the third key had no
+ * declarable face, and it went with the gap it recorded.
  *
  * Direction of the DOM assertion: `rows` lands on the HTML `rows` attribute of
  * the inline `<Textarea>`; the fullscreen dialog deliberately ignores it
@@ -26,7 +29,12 @@
 import { describe, it, expect } from 'vitest';
 import { render, screen } from '@testing-library/react';
 import '@testing-library/jest-dom';
-import type { HtmlFieldMetadata, MarkdownFieldMetadata, TextareaFieldMetadata } from '@object-ui/types';
+import type {
+  HtmlFieldMetadata,
+  MarkdownFieldMetadata,
+  RichtextFieldMetadata,
+  TextareaFieldMetadata,
+} from '@object-ui/types';
 
 import { RichTextField } from '../RichTextField';
 import { TextAreaField } from '../TextAreaField';
@@ -45,9 +53,7 @@ describe('RichTextField — declared `rows` sizes the inline editor (#6140)', ()
   });
 
   it('richtext: the third registry key of the same widget honours rows too', () => {
-    // No `RichtextFieldMetadata` exists in the union — the runtime shape is
-    // structural. Cast, deliberately, at the one seam that has no declared type.
-    const field = { type: 'richtext', name: 'doc', rows: 10 } as unknown as MarkdownFieldMetadata;
+    const field: RichtextFieldMetadata = { type: 'richtext', name: 'doc', rows: 10 };
     render(<RichTextField value="<p>hi</p>" onChange={() => {}} field={field} />);
     expect(screen.getByRole('textbox')).toHaveAttribute('rows', '10');
   });
diff --git a/packages/fields/src/widgets/__tests__/richtext-field-metadata-7083.test.tsx b/packages/fields/src/widgets/__tests__/richtext-field-metadata-7083.test.tsx
new file mode 100644
index 0000000000..90f08165f7
--- /dev/null
+++ b/packages/fields/src/widgets/__tests__/richtext-field-metadata-7083.test.tsx
@@ -0,0 +1,176 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * `RichtextFieldMetadata` — the third registry key of one widget becomes
+ * DECLARABLE (objectui#7083, maintainer ruling of 2026-09-07, batch #71).
+ *
+ * ## What was missing, and why a cast was the only evidence
+ *
+ * `markdown`, `html` and `richtext` are one widget (objectui#5498). Two of the
+ * three carried an exported metadata type; `richtext` carried none, so the
+ * runtime served it happily by structure while an author could not write its
+ * metadata under an annotation at all. The state was neither a union member
+ * nor a recorded alias — a silent gap whose ONLY trace was a deliberate
+ * `as unknown as MarkdownFieldMetadata` in `RichTextField.rows.test.tsx`. That
+ * cast is gone; this file is what replaces it, so the gap cannot be
+ * rediscovered by the next reader who trips over a cast.
+ *
+ * ## The pin has two halves and needs both
+ *
+ * The ruling asks that "a typed `richtext` literal compiles AND the widget
+ * renders it", and the compile half is not decoration: a pin that only rendered
+ * would still pass with the cast in place, which is the state this card ends.
+ *
+ *  - COMPILE — {@link richtextField} below is an annotated literal, so TypeScript's
+ *    excess-property check judges every key in it, and it is assigned to
+ *    `FieldMetadata` to pin the UNION membership the ruling actually granted.
+ *    On the pre-change tree this file does not compile at all: there is no
+ *    member to annotate against, which is what makes this leg non-vacuous.
+ *  - RENDER — every key of the derived read set is then asserted at the DOM,
+ *    each against a control that changes only that key, so a green here reads
+ *    "the widget consumed the declared key" and never "the default happened to
+ *    match".
+ *
+ * ## The read set is DERIVED from `RichTextField.tsx`, not copied
+ *
+ * `type` (`resolveRichTextFieldType`, the discriminator), `rows`
+ * (`richField?.rows || 8`), `placeholder`, `mobile_fullscreen` and `label` are
+ * the five keys the widget reads off this carrier on the `richtext` path; the
+ * readonly branch hands `field` to a `RICH_TEXT_CELL_RENDERERS` entry, and both
+ * renderers there read `value` only. The last group below pins the measurement
+ * that put the sixth key, `max_length`, on the member even though the widget
+ * does not read it — see the member's own docblock in
+ * `packages/types/src/field-types.ts`.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { FieldSchema } from '@objectstack/spec/data';
+import type { FieldMetadata, RichtextFieldMetadata } from '@object-ui/types';
+
+import { RichTextField } from '../RichTextField';
+
+/**
+ * The whole derived read set in ONE annotated literal.
+ *
+ * Annotated, never `as`: the annotation is what makes TypeScript judge each
+ * key, and judging each key is the half of this pin that a cast would have
+ * silently satisfied.
+ */
+const richtextField: RichtextFieldMetadata = {
+  type: 'richtext',
+  name: 'doc',
+  label: 'Release notes',
+  rows: 10,
+  placeholder: 'Write the release notes…',
+  mobile_fullscreen: true,
+  max_length: 5000,
+};
+
+describe('RichtextFieldMetadata — the declarable face of the `richtext` key', () => {
+  it('is a member of the `FieldMetadata` union and discriminates on `type`', () => {
+    const asUnion: FieldMetadata = richtextField;
+
+    // The runtime half of the same statement, so the assertion is not purely a
+    // compile-time artefact that a `// @ts-expect-error` sweep could hide.
+    expect(asUnion.type).toBe('richtext');
+
+    // …and the union NARROWS on it: reaching `rows` through the union without a
+    // cast is the authoring capability the ruling granted. Before this member
+    // existed there was no branch of the union this literal could inhabit.
+    if (asUnion.type !== 'richtext') throw new Error('unreachable: literal is a richtext field');
+    expect(asUnion.rows).toBe(10);
+    expect(asUnion.max_length).toBe(5000);
+  });
+
+  it('renders the declared `rows` on the inline editor', () => {
+    render(<RichTextField value="<p>hi</p>" onChange={() => {}} field={richtextField} />);
+    expect(screen.getByRole('textbox')).toHaveAttribute('rows', '10');
+  });
+
+  it('renders the declared `placeholder`', () => {
+    render(<RichTextField value="" onChange={() => {}} field={richtextField} />);
+    expect(screen.getByRole('textbox')).toHaveAttribute('placeholder', 'Write the release notes…');
+  });
+
+  it('renders the expand affordance for `mobile_fullscreen`, titled with `label`', () => {
+    render(<RichTextField value="<p>hi</p>" onChange={() => {}} field={richtextField} />);
+
+    const toggle = screen.getByTestId('richtext-fullscreen-toggle');
+    expect(toggle).toBeInTheDocument();
+
+    // `label` reaches the dialog title, which is a direct render of the key
+    // rather than an interpolated sentence — so this assertion cannot be
+    // satisfied by a fallback string.
+    fireEvent.click(toggle);
+    expect(screen.getByTestId('richtext-fullscreen-dialog')).toBeInTheDocument();
+    expect(screen.getByText('Release notes')).toBeInTheDocument();
+  });
+
+  it('control: the same widget, same type, with the optional keys omitted', () => {
+    // One key different per assertion above; here they are all absent at once,
+    // and the widget answers with its own defaults. Without this, a green above
+    // would be compatible with the widget ignoring the metadata entirely.
+    const bare: RichtextFieldMetadata = { type: 'richtext', name: 'doc' };
+    render(<RichTextField value="" onChange={() => {}} field={bare} />);
+
+    expect(screen.getByRole('textbox')).toHaveAttribute('rows', '8');
+    expect(screen.getByRole('textbox')).not.toHaveAttribute('placeholder', 'Write the release notes…');
+    expect(screen.queryByTestId('richtext-fullscreen-toggle')).not.toBeInTheDocument();
+  });
+});
+
+/**
+ * The measurement behind the ONE key on the member that `RichTextField` does
+ * not read.
+ *
+ * `max_length` is on {@link import('@object-ui/types').MarkdownFieldMetadata}
+ * and `HtmlFieldMetadata`. Putting it on the new member was a decision, and it
+ * rests on this reading rather than on the two siblings having it: at
+ * `@objectstack/spec` 17.3.0 the authoring boundary answers IDENTICALLY for all
+ * three of the field types this one widget serves. Pinned so the member's
+ * docblock cannot rot into a false canonical claim — the failure mode
+ * objectui#7014 was opened for.
+ */
+describe('spec boundary — `richtext` is symmetric with `markdown`/`html` on the ceiling key', () => {
+  const base = (type: string) => ({ name: 'body', type, label: 'Body' });
+
+  /**
+   * Pull the `unrecognized_keys` issue naming `key`, or undefined.
+   *
+   * Typed off `safeParse`'s own return rather than through `any`: narrowing on
+   * the issue's `code` is what makes `keys` reachable, and it is also what
+   * keeps this helper honest — an issue of a different code can never satisfy
+   * it by carrying a same-named field.
+   */
+  const refusedByName = (result: ReturnType<typeof FieldSchema.safeParse>, key: string) =>
+    result.success
+      ? undefined
+      : result.error.issues.find((i) => i.code === 'unrecognized_keys' && i.keys.includes(key));
+
+  for (const type of ['markdown', 'html', 'richtext'] as const) {
+    it(`control: \`${type}\` with no ceiling key is accepted`, () => {
+      expect(FieldSchema.safeParse(base(type)).success).toBe(true);
+    });
+
+    it(`\`${type}\` ADMITS the spec's own \`maxLength\``, () => {
+      expect(FieldSchema.safeParse({ ...base(type), maxLength: 5000 }).success).toBe(true);
+    });
+
+    it(`\`${type}\` refuses the objectui legacy spelling \`max_length\` BY NAME`, () => {
+      const res = FieldSchema.safeParse({ ...base(type), max_length: 5000 });
+      expect(res.success).toBe(false);
+      expect(refusedByName(res, 'max_length'), `expected unrecognized_keys naming 'max_length' on ${type}`).toBeDefined();
+      // Control, per fixture: the key is the only difference from the accepted
+      // payload above, so "refused" is about the key and not about the field.
+      expect(FieldSchema.safeParse(base(type)).success).toBe(true);
+    });
+  }
+});
diff --git a/packages/types/src/field-types.ts b/packages/types/src/field-types.ts
index 185d0024be..87472e0ee3 100644
--- a/packages/types/src/field-types.ts
+++ b/packages/types/src/field-types.ts
@@ -234,6 +234,77 @@ export interface HtmlFieldMetadata extends BaseFieldMetadata {
   rows?: number;
 }
 
+/**
+ * Rich-text (WYSIWYG) field metadata — the THIRD registry key `RichTextField`
+ * serves, and the last of the three to get a declarable face.
+ *
+ * `markdown`, `html` and `richtext` are ONE widget (objectui#5498). The first
+ * two carried an exported metadata type; `richtext` carried none, so the only
+ * way to write a richtext field's metadata was
+ * `as unknown as MarkdownFieldMetadata` — a deliberate cast whose presence in
+ * `RichTextField.rows.test.tsx` was the gap's only evidence. Neither a member
+ * nor a recorded alias: a silent hole that had to be rediscovered to be seen.
+ * Closed by the maintainer's objectui#7083 ruling (decision batch #71,
+ * 2026-09-07), which is why the cast and its comment are gone as well.
+ *
+ * ## The read set below is DERIVED, not copied from the siblings
+ *
+ * Read off `RichTextField.tsx` on the `richtext` path, key by key:
+ *
+ *  - `type` — `resolveRichTextFieldType` reads `field.type` (stripping a
+ *    `field:` prefix). It is THE discriminator for the three keys, and the
+ *    ONLY thing that differs between them at runtime: it selects the display
+ *    pipeline (`richtext` reads through the HTML renderer, objectui#5452) and
+ *    the editor's format label. Nothing else in the widget branches on it.
+ *  - `rows` — `richField?.rows || 8`, the inline editor's height. Declared
+ *    here for the same reason objectui#6140 declared it on the two siblings:
+ *    the running widget honoured a key an annotated literal rejected.
+ *  - `mobile_fullscreen`, `placeholder`, `label` — also read off this carrier
+ *    (the expand affordance, the textarea placeholder, the dialog title), and
+ *    all three already sit on {@link BaseFieldMetadata}, so they need no
+ *    redeclaration here. Listed because "derived" has to name what it found,
+ *    including the keys that turned out to need no line.
+ *
+ * The readonly branch hands `field` whole to the `RICH_TEXT_CELL_RENDERERS`
+ * entry for the type; both renderers there destructure `value` only, so the
+ * display half contributes no metadata key.
+ *
+ * ## `max_length` — the one key here the widget does NOT read
+ *
+ * It is declared because the cross-check against {@link MarkdownFieldMetadata}
+ * and {@link HtmlFieldMetadata} found `richtext` symmetric with both on every
+ * axis that can be measured, not because they happen to have it:
+ *
+ *  - one widget, one code path — see `type` above;
+ *  - `@objectstack/spec` 17.3.0 `FieldSchema` answers IDENTICALLY for all three
+ *    field types: `rows` admitted, the spec's own camelCase `maxLength`
+ *    admitted, and the legacy snake_case `max_length` refused BY NAME on each
+ *    of them alike. Pinned in
+ *    `packages/fields/src/widgets/__tests__/richtext-field-metadata-7083.test.tsx`
+ *    so this paragraph cannot rot into a false canonical claim.
+ *
+ * Omitting it would have left `richtext` the one key of the three whose
+ * ceiling cannot be authored under an annotation — a fresh instance of the
+ * asymmetry this member exists to end.
+ *
+ * ⚠️ The `rows` docblocks on the two siblings still describe the
+ * `@objectstack/spec` 17.2.0 boundary, where `rows` was refused by name. That
+ * prose is objectui#7635's declared surface, not this member's; the 17.3.0
+ * reading above is stated for `richtext` only and is not a correction of it.
+ */
+export interface RichtextFieldMetadata extends BaseFieldMetadata {
+  type: 'richtext';
+  max_length?: number;
+  /**
+   * Height of the INLINE editor, in text rows. Same read as
+   * `MarkdownFieldMetadata.rows` and `HtmlFieldMetadata.rows` — literally the
+   * same expression, since the three registry keys are one widget: `rows`
+   * lands on the inline `<Textarea>`'s `rows` attribute and the fullscreen
+   * dialog ignores it (`rows={fullHeight ? undefined : rows}`).
+   */
+  rows?: number;
+}
+
 /**
  * Number field metadata
  */
@@ -826,6 +897,7 @@ export type FieldMetadata =
   | TextareaFieldMetadata
   | MarkdownFieldMetadata
   | HtmlFieldMetadata
+  | RichtextFieldMetadata
   | NumberFieldMetadata
   | CurrencyFieldMetadata
   | PercentFieldMetadata
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index b92fa6959f..6edd22eeda 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -473,6 +473,7 @@ export type {
   TextareaFieldMetadata,
   MarkdownFieldMetadata,
   HtmlFieldMetadata,
+  RichtextFieldMetadata,
   NumberFieldMetadata,
   CurrencyFieldMetadata,
   PercentFieldMetadata,

From de98ffd367b00d78f95431bd7f71480ad44841c3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 16:45:25 +0000
Subject: [PATCH 2/3] docs(fields): re-point RichTextField's metadata-face
 comment at the new union member
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comment only — no behaviour, no read site, no signature changes.

The paragraph above `richField` said "the third key, `richtext`, has no union
member of its own". This branch is what makes that false, so the correction
belongs to this diff rather than to a follow-up: the ruling's stated reason for
deleting the pin test's comment was that the gap must not stay rediscoverable,
and the same sentence sat four lines from where a reader of the widget looks.

The cast itself is unchanged and stays correct. It names two of the three
members because it never had to discriminate: every key this widget consumes
off the carrier is declared on all three, so the two named already admit each
read below. The comment now says that outright instead of implying the third
key is undeclarable.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QtGhnU3WnnWyiWeYQhw2aX
---
 packages/fields/src/widgets/RichTextField.tsx | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/packages/fields/src/widgets/RichTextField.tsx b/packages/fields/src/widgets/RichTextField.tsx
index 598f1a4198..a744d6c772 100644
--- a/packages/fields/src/widgets/RichTextField.tsx
+++ b/packages/fields/src/widgets/RichTextField.tsx
@@ -280,13 +280,16 @@ export function RichTextField({ value, onChange, field, readonly, error, ...prop
     return <Display value={value} field={field} />;
   }
 
-  // The declared metadata face for this widget's registry keys. `markdown` and
-  // `html` each have an exported type; the third key, `richtext`, has no union
-  // member of its own and structurally matches the same three optional reads
-  // below — every key this widget consumes (`rows`, `mobile_fullscreen`,
-  // `placeholder`, `label`) is DECLARED on both members, `rows` since the
-  // objectui#6140 Option A ruling (which is what retired the `as any` that
-  // used to launder this carrier).
+  // The declared metadata face for this widget's registry keys. All three of
+  // them have an exported type: `markdown` and `html` always did, and the third
+  // key, `richtext`, gained `RichtextFieldMetadata` in objectui#7083 — which is
+  // what retired the deliberate `as unknown as MarkdownFieldMetadata` its pin
+  // test needed for as long as the union had no branch to write it against.
+  // The cast below names two of the three because it does not have to
+  // discriminate: every key this widget consumes (`rows`, `mobile_fullscreen`,
+  // `placeholder`, `label`) is DECLARED on all three, so the two named already
+  // admit every read below — `rows` since the objectui#6140 Option A ruling
+  // (which is what retired the `as any` that used to launder this carrier).
   const richField = field as MarkdownFieldMetadata | HtmlFieldMetadata;
   const rows = richField?.rows || 8;
   // The stored syntax, DERIVED from the type's display pipeline rather than

From 5b6d3c36ebce081db1ea2472cf29731ab35a3e49 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 7 Sep 2026 23:01:48 +0000
Subject: [PATCH 3/3] docs(types,fields): name the third metadata type on the
 page, and state max_length's real reader
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Contract-review rework on #7083 (three items, all reproducible).

R1 — content/docs/fields/rich-text.mdx said `markdown` and `html` are "two
field types served by one widget", "each has its own exported metadata type",
and "there is no combined 'rich text' metadata type"; the page never mentioned
the `richtext` key. Declaring RichtextFieldMetadata is what made that false.
The Field Schema section now names all three types, the fence carries a
RichtextFieldMetadata literal, and Editor Modes lists the third mode. Follows
the #7061 precedent, which updated this same page for the analogous change.

R2 — the member's TSDoc credited "richtext symmetric with both on every axis
that can be measured". That is false: ObjectForm forwards max_length to the
HTML maxlength attribute for text|textarea|markdown|html only, and
EmbeddableForm's DEFAULT_MAX_LENGTH caps markdown/html only — richtext is
absent from both. The spec-symmetry reading is also non-discriminating for
this key (FieldSchema answers identically for every field type, `text`
included). The real reader is buildValidationRules — generic, no field-type
gate, called on every field by ObjectForm and sectionFields, spread into the
RHF rules and localized — so max_length on a richtext field IS enforced at
submit. Same correction in the changeset body. The pin citation is re-pointed:
richtext-field-metadata-7083.test.tsx pins `maxLength` admitted and
`max_length` refused; `rows` admitted is pinned by
select-option-spec-extension-7014.test.ts.

The pin test's own docblock carried the same false rationale and is corrected
with it — comment-only, proven: stripped of comments the file hashes
identically before and after (68 non-comment lines, unchanged).

No change to the member's shape, the union, the barrel, or any test's logic.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QtGhnU3WnnWyiWeYQhw2aX
---
 .changeset/7083-richtext-field-metadata.md    | 25 +++++++---
 content/docs/fields/rich-text.mdx             | 49 +++++++++++++++----
 .../richtext-field-metadata-7083.test.tsx     | 32 +++++++-----
 packages/types/src/field-types.ts             | 47 ++++++++++++------
 4 files changed, 109 insertions(+), 44 deletions(-)

diff --git a/.changeset/7083-richtext-field-metadata.md b/.changeset/7083-richtext-field-metadata.md
index bd4db19fe4..85242174ed 100644
--- a/.changeset/7083-richtext-field-metadata.md
+++ b/.changeset/7083-richtext-field-metadata.md
@@ -37,11 +37,20 @@ served all three keys and this release only gives the third one a face.
 `placeholder`, `mobile_fullscreen` and `label` are the keys `RichTextField` actually
 reads on the `richtext` path (the last three already sit on `BaseFieldMetadata`, so the
 member declares `type` and `rows`); the readonly branch hands the metadata to a cell
-renderer that reads `value` only and contributes no key. `max_length` is the one
-declared key the widget does not read, and it is there because the cross-check measured
-`richtext` symmetric with `markdown` and `html` on every available axis — one widget and
-one code path, plus `@objectstack/spec` 17.3.0 `FieldSchema` answering identically for
-all three (`rows` admitted, the spec's own `maxLength` admitted, the legacy snake_case
-`max_length` refused by name alike). Omitting it would have left `richtext` the one key
-of the three whose ceiling cannot be authored — a fresh instance of the asymmetry this
-member exists to end.
+renderer that reads `value` only and contributes no key.
+
+`max_length` is the one declared key the widget itself does not read, and it is declared
+because a live reader outside the widget does: `buildValidationRules` compiles
+`maxLength ?? max_length` into a react-hook-form rule for **every** field it is handed —
+it is generic, with no field-type gate — and both form producers call it on every field
+they build. So `max_length` on a `richtext` field is enforced when the form is
+submitted. (It is not, however, forwarded to the editor's HTML `maxlength` attribute,
+and it gets no default cap in `EmbeddableForm`: both of those enumerate field types and
+omit `richtext`. That predates this release and is unchanged by it.) Omitting the key
+would have left `richtext` the one type of the three whose ceiling cannot be authored
+under an annotation while the submit-time rule enforcing it stayed live — a fresh
+instance of the asymmetry this member exists to end.
+
+Docs: `content/docs/fields/rich-text.mdx` teaches all three metadata types and carries a
+`RichtextFieldMetadata` snippet; before this release the page stated there was no third
+type.
diff --git a/content/docs/fields/rich-text.mdx b/content/docs/fields/rich-text.mdx
index f337af863c..8bfe7787d0 100644
--- a/content/docs/fields/rich-text.mdx
+++ b/content/docs/fields/rich-text.mdx
@@ -14,13 +14,18 @@ The Rich Text Field component edits formatted text content with markdown or HTML
 <SchemaExample id="fields-rich-text/html-editor" />
 ## Field Schema
 
-`markdown` and `html` are two field types served by one widget, and each has its own
-exported metadata type — `MarkdownFieldMetadata` and `HtmlFieldMetadata`
-(`@object-ui/types`). Both extend `BaseFieldMetadata` and add a length bound and an
-inline-editor height; there is no combined "rich text" metadata type.
+`markdown`, `html` and `richtext` are three field types served by one widget, and each
+has its own exported metadata type — `MarkdownFieldMetadata`, `HtmlFieldMetadata` and
+`RichtextFieldMetadata` (`@object-ui/types`). All three extend `BaseFieldMetadata` and
+add a length bound and an inline-editor height; there is no combined "rich text"
+metadata type.
 
 ```ts
-import type { HtmlFieldMetadata, MarkdownFieldMetadata } from '@object-ui/types';
+import type {
+  HtmlFieldMetadata,
+  MarkdownFieldMetadata,
+  RichtextFieldMetadata,
+} from '@object-ui/types';
 
 const releaseNotes: MarkdownFieldMetadata = {
   type: 'markdown',
@@ -39,15 +44,36 @@ const emailBody: HtmlFieldMetadata = {
   label: 'Email Body',
   max_length: 50000,
 };
+
+const articleBody: RichtextFieldMetadata = {
+  type: 'richtext',
+  name: 'article_body',
+  label: 'Article Body',
+  rows: 10,
+  max_length: 50000,
+};
 ```
 
-`rows` sizes the inline editor, in text rows — declared on both types (and on
+`richtext` gained its exported type in
+[objectui#7083](https://github.com/objectstack-ai/objectui/issues/7083); until then it
+was the one key of the three with no member to annotate against, so its metadata could
+only be written through a cast to one of its siblings. It stores **HTML** — it reads
+through the same display pipeline as `html`, not the markdown one
+([objectui#5452](https://github.com/objectstack-ai/objectui/issues/5452)) — and that
+pipeline is the only thing `type` changes between the three.
+
+`max_length` is a bound on the stored text. The widget itself does not read it; the
+form does — `buildValidationRules` compiles it into the submit-time validation rules
+for every field, whatever its type — so it is enforced when the form is submitted, not
+as a `maxlength` attribute on the rich-text editor.
+
+`rows` sizes the inline editor, in text rows — declared on all three types (and on
 `@objectstack/spec`'s `FieldSchema` for the multiline editor types), matching the
 `textarea` field's key of the same name ([objectui#6140](https://github.com/objectstack-ai/objectui/issues/6140)).
 The editor is a plain textarea today — there is no formatting toolbar, no preview pane
-and no pixel height to configure, so neither metadata type declares one: `toolbar`,
-`preview`, `minHeight` and `maxHeight` are **not** metadata keys, and writing them
-does nothing.
+and no pixel height to configure, so none of the three metadata types declares one:
+`toolbar`, `preview`, `minHeight` and `maxHeight` are **not** metadata keys, and writing
+them does nothing.
 
 The value being edited, and the `className` / `disabled` a host supplies, are **not**
 metadata keys — they are runtime widget props. See [Field Widget Props](/docs/fields/widget-props).
@@ -116,3 +142,8 @@ The rich text field can operate in different modes:
    - Full HTML editing
    - Advanced formatting
    - Embedded content support
+
+3. **Rich Text Mode** (`type: 'richtext'`)
+   - Stores HTML, and reads through the same display pipeline as `html`
+   - Editable under `RichtextFieldMetadata`
+   - Same plain-textarea editing surface as the other two
diff --git a/packages/fields/src/widgets/__tests__/richtext-field-metadata-7083.test.tsx b/packages/fields/src/widgets/__tests__/richtext-field-metadata-7083.test.tsx
index 90f08165f7..40cf409168 100644
--- a/packages/fields/src/widgets/__tests__/richtext-field-metadata-7083.test.tsx
+++ b/packages/fields/src/widgets/__tests__/richtext-field-metadata-7083.test.tsx
@@ -43,10 +43,12 @@
  * (`richField?.rows || 8`), `placeholder`, `mobile_fullscreen` and `label` are
  * the five keys the widget reads off this carrier on the `richtext` path; the
  * readonly branch hands `field` to a `RICH_TEXT_CELL_RENDERERS` entry, and both
- * renderers there read `value` only. The last group below pins the measurement
- * that put the sixth key, `max_length`, on the member even though the widget
- * does not read it — see the member's own docblock in
- * `packages/types/src/field-types.ts`.
+ * renderers there read `value` only. The sixth key, `max_length`, is on the
+ * member even though this widget does not read it, because the FORM does:
+ * `buildValidationRules` is generic and compiles it into a submit-time rule for
+ * every field. The last group below pins only the spec-boundary reading that
+ * accompanies it — see the member's own docblock in
+ * `packages/types/src/field-types.ts` for which of the two is the reason.
  */
 
 import { describe, it, expect } from 'vitest';
@@ -128,16 +130,20 @@ describe('RichtextFieldMetadata — the declarable face of the `richtext` key',
 });
 
 /**
- * The measurement behind the ONE key on the member that `RichTextField` does
- * not read.
+ * The spec-boundary reading for the ONE key on the member that `RichTextField`
+ * does not read.
  *
- * `max_length` is on {@link import('@object-ui/types').MarkdownFieldMetadata}
- * and `HtmlFieldMetadata`. Putting it on the new member was a decision, and it
- * rests on this reading rather than on the two siblings having it: at
- * `@objectstack/spec` 17.3.0 the authoring boundary answers IDENTICALLY for all
- * three of the field types this one widget serves. Pinned so the member's
- * docblock cannot rot into a false canonical claim — the failure mode
- * objectui#7014 was opened for.
+ * ⛔ This group is NOT the reason `max_length` is declared. That reason is
+ * `buildValidationRules` — generic, no field-type gate, called on every field
+ * both form producers build — which makes the key enforceable at submit on a
+ * `richtext` field. This reading is NON-DISCRIMINATING for it: at
+ * `@objectstack/spec` 17.3.0 the authoring boundary answers IDENTICALLY for
+ * every field type, `text` included, so it says nothing about `richtext`
+ * versus its two siblings.
+ *
+ * It is pinned anyway, for the three types this one widget serves, so the
+ * member's docblock cannot rot into a false canonical claim about the spelling
+ * — the failure mode objectui#7014 was opened for.
  */
 describe('spec boundary — `richtext` is symmetric with `markdown`/`html` on the ceiling key', () => {
   const base = (type: string) => ({ name: 'body', type, label: 'Body' });
diff --git a/packages/types/src/field-types.ts b/packages/types/src/field-types.ts
index 87472e0ee3..026377e1be 100644
--- a/packages/types/src/field-types.ts
+++ b/packages/types/src/field-types.ts
@@ -269,23 +269,42 @@ export interface HtmlFieldMetadata extends BaseFieldMetadata {
  * entry for the type; both renderers there destructure `value` only, so the
  * display half contributes no metadata key.
  *
- * ## `max_length` — the one key here the widget does NOT read
+ * ## `max_length` — read at SUBMIT, not by the widget
  *
- * It is declared because the cross-check against {@link MarkdownFieldMetadata}
- * and {@link HtmlFieldMetadata} found `richtext` symmetric with both on every
- * axis that can be measured, not because they happen to have it:
+ * `RichTextField` never reads this key. It is declared because a live reader
+ * outside the widget does, on every field regardless of type:
+ * `buildValidationRules` (`packages/fields/src/index.tsx`) compiles
+ * `(field as any).maxLength ?? field.max_length` into a react-hook-form
+ * `maxLength` rule. That function is GENERIC — it has no field-type gate
+ * anywhere in it — and both form producers call it on every field they build
+ * (`ObjectForm`'s `validation: buildValidationRules(field)` and the same line
+ * in `sectionFields.ts`); the form renderer spreads the result into the RHF
+ * `rules` object and localizes the `maxLength` entry. ⇒ `max_length` written
+ * on a `richtext` field IS enforced when the form is submitted. That is the
+ * checkable reason this key is declared.
  *
- *  - one widget, one code path — see `type` above;
- *  - `@objectstack/spec` 17.3.0 `FieldSchema` answers IDENTICALLY for all three
- *    field types: `rows` admitted, the spec's own camelCase `maxLength`
- *    admitted, and the legacy snake_case `max_length` refused BY NAME on each
- *    of them alike. Pinned in
- *    `packages/fields/src/widgets/__tests__/richtext-field-metadata-7083.test.tsx`
- *    so this paragraph cannot rot into a false canonical claim.
+ * ⛔ Spec symmetry is NOT that reason, and must not be restated as one. At
+ * `@objectstack/spec` 17.3.0 `FieldSchema` answers identically for EVERY field
+ * type — `text` included — on `maxLength` (admitted) and on the legacy
+ * snake_case `max_length` (refused BY NAME), so that reading is
+ * non-discriminating here: it says nothing about `richtext` versus its two
+ * siblings. It is still pinned, for the three types this widget serves, in
+ * `packages/fields/src/widgets/__tests__/richtext-field-metadata-7083.test.tsx`
+ * — the `maxLength` admitted and `max_length` refused halves. `rows` admitted
+ * is pinned separately, in
+ * `packages/types/src/__tests__/select-option-spec-extension-7014.test.ts`.
  *
- * Omitting it would have left `richtext` the one key of the three whose
- * ceiling cannot be authored under an annotation — a fresh instance of the
- * asymmetry this member exists to end.
+ * ⚠️ Two form-side sites do NOT reach `richtext`, and this key claims no
+ * coverage there: `ObjectForm` forwards `max_length` to the HTML `maxlength`
+ * attribute for `text | textarea | markdown | html` only, and
+ * `EmbeddableForm`'s `DEFAULT_MAX_LENGTH` caps `markdown` and `html` only.
+ * `richtext` is absent from both. Those omissions predate this member and are
+ * not corrected here.
+ *
+ * Omitting the key would have left `richtext` the one type of the three whose
+ * ceiling cannot be authored under an annotation, while the submit-time rule
+ * that enforces it stayed live — a fresh instance of the asymmetry this member
+ * exists to end.
  *
  * ⚠️ The `rows` docblocks on the two siblings still describe the
  * `@objectstack/spec` 17.2.0 boundary, where `rows` was refused by name. That