finding(fields): `RichTextField` reads a `rows` key off field metadata that neither `MarkdownFieldMetadata` nor `HtmlFieldMetadata` declares — undeclared-but-consumed, reached through an `as any`

[yinlianghui-tw]

Filed unassigned from objectui#6138 round 2, which ruled that rich-text.mdx's five editor keys get determined and filed with the answer in them rather than filed as a question. The answer is measured below. The five keys come out of that page's annotated Field Schema block either way; this card decides whether one of them comes back as a declared member.

The measurement — one of five is consumed, four are inert

Read: packages/fields/src/widgets/RichTextField.tsx (the single widget behind the markdown, html and richtext registry keys — objectui#5498).

key documented on rich-text.mdx	read by RichTextField?	evidence
rows	YES	const rows = richField?.rows || 8;, passed to RichTextEditorSurface and onto Textarea's rows={fullHeight ? undefined : rows}
toolbar	no	the only occurrence in packages/fields/src is a JSDoc sentence about what the editor might grow into — "whatever the editor grows into (a toolbar, a TipTap/Lexical instance, a preview toggle)"
preview	no	no read on this widget; the other preview hits in packages/fields/src belong to VectorField, RecordPickerDialog and ImageLightbox
minHeight	no	zero occurrences anywhere in packages/fields/src
maxHeight	no	zero occurrences anywhere in packages/fields/src

Command:

grep -rn "\btoolbar\b\|\bpreview\b\|\bminHeight\b\|\bmaxHeight\b\|\brows\b" \
 packages/fields/src --include=*.ts --include=*.tsx | grep -v __tests__

So four of the five are inert prose and are simply deleted by objectui#6138. rows is the finding.

Why rows is a defect rather than a working feature

The read is real and reaches the DOM, but it is undeclared on both metadata types the widget can be handed:

• MarkdownFieldMetadata — 18 members, rows not among them
• HtmlFieldMetadata — 18 members, rows not among them

(Key sets read from the built packages/types/dist/index.d.ts through the doc gate's own derivePackageTypePaths(), so they are the shipped surface, not source.)

The read only compiles because the widget launders the carrier first:

const richField = field as any;
const rows = richField?.rows || 8;

field is typed FieldMetadata, so without that as any the read would not compile. The cast is what lets an undeclared key be consumed silently — and it is the same cast that reads placeholder, label and mobile_fullscreen, all three of which are declared on BaseFieldMetadata. rows is the one member of that group with no declaration behind it.

Consequences, both live today:

1. An author cannot legally write it. A markdown field carrying rows is a key @objectstack/spec's strict schemas reject at publish, and a MarkdownFieldMetadata literal carrying it fails the excess-property check — while the running widget honours it. Declared and enforced disagree in the direction that is hardest to notice: the feature works in the app and fails at authoring time.
2. The sibling proves the shape. TextareaFieldMetadata does declare rows, and TextAreaField reads it the same way (const rows = textareaField?.rows || 4;). Two long-text widgets, the same capability, one declared and one not — so this is a gap in one type rather than a question about whether the capability is wanted.

The two candidate resolutions

• A — declare it. Add rows?: number to MarkdownFieldMetadata and HtmlFieldMetadata, matching TextareaFieldMetadata. Makes the consumed key authorable, and rich-text.mdx's Field Schema block can then carry it. Needs the corresponding @objectstack/spec question answered — the renderer type is not the publish contract.
• B — remove the read. Drop richField?.rows and let the inline editor keep its fixed height. Consistent with "declared = enforced" in the other direction, and cheaper, but it removes a capability the sibling widget has and an author may already be using.

⚠️ Not decided here, deliberately: the choice turns on whether @objectstack/spec should carry rows for markdown/html, which is a spec question and not this repo's to answer alone. What this card fixes is that the question was previously invisible.

Refs

objectui#6138 (which ruled this be filed with its answer) · objectui#5498 (the one widget, three registry keys) · objectui#3233 (field as the single metadata carrier) · objectui#3221 (why the closed contract matters).

---

Generated by Claude Code

[os-zhuang]

Triage (triage seat, session session_01PCuhUdqwK7zkkxgtJHswTc): graded into the decision inbox — whether @objectstack/spec carries rows on markdown/html authorable metadata is an acceptance-set expansion (human floor), and the card itself rules it "a spec question and not this repo's to answer alone". → needs-user-decision, domain:spec (contract face per the 2026-08-21 three-way split), type Feature. This card is the mother card for the undeclared-but-consumed family this sweep measured: #6153's two instances (dependsOn on select metadata, options[].description on lookup) ride the same ruling frame and are parked pm:blocked on this one. 四维分析如下(中文,业务视角):

一句话问题:富文本字段的行高(rows)在应用里真实生效,但按规则书写的作者写了它会被发布校验响亮拒绝 —— 功能在跑,合法作者却写不进去;同门的多行文本字段(textarea)早就正大光明声明了同一个键。

选项 × 真实代价:

• A 声明它:MarkdownFieldMetadata/HtmlFieldMetadata 加 rows?: number,并在 @objectstack/spec authorable 面同步声明 —— 业务上 = 把已经在跑的能力补进说明书,作者(人与 AI)从此可合法使用;代价:契约面 +1 键,spec 与 objectui 两仓各一笔,永久维护义务。
• B 删掉读取:widget 不再读 rows,行内编辑器固定高度 —— 业务上 = 收回一个没人承诺过的旁门,和「声明即强制」同向;代价:已有作者若在库里写了 rows(经 as any 生效)会静默失去行高,且同门 textarea 有此能力、富文本没有,产品面不对称。
• (家族卡 finding(fields): two more undeclared-but-consumed metadata keys — dependsOn on select and options[].description on lookup, both reached past the declared type #6153 的两个键各自套同一框架裁:dependsOn 有已声明的 snake_case 兄弟 depends_on,大概率是 B/迁移拼写;options[].description 是真被搜索消费的行为,更像 A。)

四棱:
① 项目长远合理性:两案都把 declared=enforced 拉回一致,方向都对;A 以最小增量对齐兄弟字段(textarea 先例),不新造形状;B 制造同门能力不对称。
② 实际业务拉动:rows 有真实消费(widget 读并落到 DOM),textarea 先例证明该能力是被要的;但本仓测不到今天有多少存量 app 实际写了这个键(见置信缺口)。
③ 防 AI 犯错:今天的状态最糟 —— AI 抄运行中的 app 学会 rows,发布时被拒,或反过来从类型学到「不能写」而实际有效;A 和 B 都消除这个双面教材,A 后作者面与运行面说同一句话。
④ 创业阶段不扩散:+1 键是最小义务,且是「把既成事实入册」而非新能力;若倾向从紧,B 也成立,但要接受删行为的回归风险。
推荐:A(rows 补声明,对齐 textarea 先例),回退 B。低摩擦裁决:回 A/B;「A,但只 objectui 类型层、spec 面缓议」也可,自动落为 objectui 先行 + spec 卡另立。
置信缺口:本分析看不见存量客户 app 里 rows/dependsOn/description 的真实书写量(需 hotcrm/示例仓与云端元数据抽样才知道删读取伤不伤人);也未读 #4631 三面失和总卡是否已有裁决方向。

裁后执行(你不用管):A ⇒ objectui types/zod + spec authorable 面各一笔,spec 半边转 domain:spec 席按 Clause-② 走契约复审档位;B ⇒ ui 席删读取 + 文档不回写;#6153 两键按同框架由分诊代批注继承裁决理由逐键落地,不再回决策箱。

---

Generated by Claude Code

[os-zhuang]

Marker repair (triage seat, same session): the machine-findable facets marker in the previous comment was stripped by the sanitizer (raw HTML-comment form). Re-anchoring it here in the escaped spelling the extraction greps for — the four-facet block itself is the previous comment and stands unchanged.

<!-- os-decision-facets -->

---

Generated by Claude Code

[os-steve]

Maintainer ruling (2026-08-25, in-session batch adjudication of the decision inbox; verbatim: 「就全部接受，然后继续下一批」— all five batch-1 recommendations accepted): Option A — declare rows?: number on both MarkdownFieldMetadata and HtmlFieldMetadata, aligning the TextareaFieldMetadata precedent, so validation and the running widget finally agree.

Scope riders accepted with it: same-stroke docs cleanup of the four inert editor keys rich-text.mdx teaches (toolbar/preview/minHeight/maxHeight) — remove or mark them not-yet-implemented in docs; if any of them is also declared in types, that is a separate enforce-or-remove item, do not fold it. The capability expansion stops at rows — the four inert keys are NOT being made real under this ruling.

State transition: needs-user-decision → pm:queue (label swap by triage; if the label still shows the old state, it is recorded rate-limit debt — this comment is the authoritative ruling record). Lane: domain:spec per the three-flow split — spec lane owns the contract half; Clause-②: yes (accepted-set expansion, ruled) — contract-review tier applies at dispatch. Same-family #6153 inherits this ruling framework in the same stroke (see its comment).

---

Generated by Claude Code