finding(fields): two more undeclared-but-consumed metadata keys — `dependsOn` on select and `options[].description` on lookup, both reached past the declared type

[yinlianghui-tw]

Measured while converting the remaining content/docs/fields pages for #6138 (PR 2). Filed unassigned, not fixed there — the conversion takes both keys out of the annotated blocks (they would redden them); whether they come back as declared members is this card's question.

Same class as #6140 (RichTextField's rows). Filed as one card rather than one per page, because the two instances are the same defect in the same layer and triage should grade them together.

Instance 1 — dependsOn, read off select field metadata through an as any

packages/fields/src/widgets/SelectField.tsx:98:

const dependsOn = (config as any)?.dependsOn ?? dependsOnProp;

config is the field metadata. SelectFieldMetadata (packages/types/src/field-types.ts) declares options, multiple, searchable and nothing else of its own; BaseFieldMetadata declares depends_on?: string[] — the snake_case sibling — and no dependsOn. The camelCase spelling is declared only as a widget prop (FieldWidgetComponentProps.dependsOn?: DependsOnInput, widgets/types.ts:191), which is the ?? dependsOnProp half of that same line.

So an author who writes dependsOn on a select field's metadata gets working cascading options in the app and a key no exported metadata type accepts — declared and enforced disagree in the direction that hides. content/docs/fields/select.mdx documented it as a metadata key, which is how it was found.

The sibling widget reads both spellings explicitly: LookupField.tsx:292 is fieldMeta?.depends_on ?? fieldMeta?.dependsOn, so the same concept is reachable under two names there, one declared and one not.

Instance 2 — description on a lookup's static options

LookupFieldMetadata.options is declared as SelectOptionMetadata[]. SelectOptionMetadata declares label, value, color, icon, disabled, visibleWhen — no description.

LookupField.tsx:250 takes those authored options as the widget's own local type:

const staticOptions: LookupOption[] = fieldMeta?.options || [];

and LookupField.tsx:526 reads the key:

(opt.description && opt.description.toLowerCase().includes(q))

LookupOption (LookupField.tsx:38) does declare description?: string — but it is a widget-local interface with an open [key: string]: any, and it is not part of @object-ui/fields's published surface (no occurrence in packages/fields/dist/index.d.ts). The assignment above crosses from the declared metadata type to the open local one without a diagnostic because fieldMeta is untyped.

So a lookup's authored option description is real behaviour (it is searched, and recordToOption at :153 produces the same key for fetched options) that the declared option type rejects.

Candidate resolutions — deliberately not decided here

Both instances turn on the same question, and it is the same question #6140 turns on:

1. Declare them — add dependsOn to SelectFieldMetadata (or migrate the widget to the declared depends_on), and description to SelectOptionMetadata. Whether the key belongs in @objectstack/spec's authorable surface is not this repo's call alone.
2. Remove the reads — treat both as accidental surfaces, and let depends_on / a description_field cover the need.

Either way the docs follow the code: content/docs/fields/select.mdx and lookup.mdx (converted in #6138 PR 2) name this card instead of documenting the keys, and will document them as metadata only once a type declares them.

Refs: #6140 (same class, rows) · #6138 (the conversion that measured it) · #4631 / #6121 (declared surfaces that disagree with each other).

---

Generated by Claude Code

[os-zhuang]

Triage (triage seat, session session_01PCuhUdqwK7zkkxgtJHswTc): same undeclared-but-consumed family as #6140, graded together as the card requests. #6140 is the mother card and now sits in the decision inbox with the four-facet frame; per the same-family meta-rule these two instances do NOT enter the inbox separately — they inherit the ruling frame (with its rationale re-checked per key: dependsOn has a declared snake_case sibling depends_on, so it likely resolves as migrate-spelling; options[].description is genuinely consumed by search, so it likely resolves as declare). → pm:blocked, domain:spec (contract face), type Task. Not dispatchable until the #6140 ruling lands.

Blocked-by: #6140

---

Generated by Claude Code

[os-steve]

Unblock + framework inheritance (triage): the ruling this card was blocked on has been delivered — #6140 ruled Option A by the maintainer (2026-08-25, verbatim: 「就全部接受，然后继续下一批」). Inherited framework: a key that is genuinely consumed and matches an established sibling precedent gets declared; the fix must not create a second spelling for an already-declared concept.

Applied per key (implementation-time judgment, fork if it breaks):

• dependsOn (SelectField): the parent already declares depends_on — the framework does NOT license declaring a camelCase twin. Preferred shape: make the widget read the declared depends_on spelling (or the sanctioned alias seam if one exists); declaring dependsOn as a second spelling needs its own decision — stop and fork if reading the canonical spelling is not enough.
• description (Lookup options): consumed and documented, SelectOptionMetadata declares nothing — straight finding(fields): RichTextField reads a rows key off field metadata that neither MarkdownFieldMetadata nor HtmlFieldMetadata declares — undeclared-but-consumed, reached through an as any #6140-A shape: declare description?: string on the option type.

State transition: pm:blocked → pm:queue (label swap by triage; if the label lags, this comment is the authoritative record). Clause-②: yes (accepted-set change) — contract-review tier at dispatch. Serial note: same contract family as #6140 — fold-or-serial with it is the spec lane's call at claim (five gates look satisfiable: same shape, same area, both now ruled).

---

Generated by Claude Code