finding(docs): the canonical BaseSchema common-props table under-states five declared types and omits five declared members

[os-sam]

Observation, filed unassigned while correcting one inherited row on content/docs/components/basic/button-group.mdx for objectui#6347. Not a user-visible failure by itself — it is the reference page every component page defers to for the inherited props, so a reader who checks the authority for a BaseSchema key gets a narrower answer than the type gives.

What was measured

content/docs/api/schema-reference.md, the "Common Properties" table (lines 53-67), against packages/types/src/base.ts read off this tree. BaseSchema declares 21 members; the table has 13 rows covering 16 of them.

Five rows narrow a declared union to one limb:

table row	table says	base.ts declares
label	string	label?: string | I18nLabel
description	string	description?: string | I18nLabel
ariaLabel	string	ariaLabel?: string | KeyedI18nLabel
visible / visibleOn	boolean / string	visible?: boolean | string — the expression limb is on visible too, not only on visibleOn
disabled / disabledOn	boolean / string	disabled?: boolean | string — same shape

The two paired rows are the interesting ones: pairing visible→boolean with visibleOn→string reads as a complete account, and it is that appearance of completeness that hides the third fact — visible itself takes a predicate expression. The Zod mirror is explicit about it (zod/base.zod.ts:190, z.union([z.boolean(), z.string()]).describe('Disabled state (boolean or predicate expression)')), so the two declaration faces agree with each other and only the docs diverge. hidden?: boolean really is boolean-only, so that row is correct — the divergence is not uniform and cannot be fixed by a blanket edit.

Five declared members have no row at all: placeholder?: string, style?: Record<string, string | number>, data?: any, bind?: string, visibleWhen?: string.

bind is the newest — declared on BaseSchema and its mirror by objectui#6574, which landed recently; the table simply has not caught up. visibleWhen sits beside two documented siblings (visible, visibleOn) which is the shape most likely to be read as an exhaustive list.

Why nothing goes red

Same hole objectui#6347's PR describes for component pages: no gate reads a plaintext fence or a prose table against the shipped types. check:doc-component-types reads only type string literals out of docs code blocks; check:doc-snippet-types compiles ts/tsx fences and this is a Markdown table. check:doc-key-tables (objectui#5106) judges plugin REGISTRATION key tables, not property tables.

Not just a docs edit — one of the rows is a question

Whether these should be corrected, or whether the types should narrow, is not obvious for all five, and the answer differs per row:

• label / description / ariaLabel — the i18n limbs are real and widely authored; the table is simply out of date. A docs fix.
• bind, visibleWhen, placeholder, style, data — missing rows. Also a docs fix, though data?: any may deserve a word about why it is any rather than a row that reads as an endorsement.
• visible / disabled — a docs fix by the letter, but worth one look first: objectui#6347's PR found that 13 of the 14 component schemas documenting a schema-level disabled REDECLARE it as disabled?: boolean, narrowing the base union away. If narrowing is the intended house shape, the honest correction might be to say so here rather than to publish a union most concrete schemas refuse. Only ButtonGroupSchema inherits it unnarrowed.

I did not edit the page. objectui#6347's PR corrects exactly one inherited row on one component page, the one inside the fence it was already rewriting.

Refs: objectui#6347 · objectui#6574 · objectui#6143 · objectui#5106.

[os-sam]

Claiming this card.

• Session: session_013hfmP9hoMd3dJwTh85J4yB
• Branch: claude/issue-7079-schema-reference-base-props (pushed, empty, before any edit)
• Base: 592acafbeed97c5aed81a18f4d848b6179d3c044

Assignee is left unset deliberately — the dispatching PM seat writes that field when its GitHub quota returns. Re-read the timeline before starting: no prior claim comment exists on this card, only the two labeling events from filing.

Scope is the "Common Properties" table in content/docs/api/schema-reference.md. Findings outside that table get filed, not fixed.

Generated by Claude Code

---

Generated by Claude Code

[os-sam]

os-dev-report

{
 "issue": 7079,
 "status": "done",
 "branch": "claude/issue-7079-schema-reference-base-props",
 "pr": "https://github.com/objectstack-ai/objectui/pull/7085",
 "premise_still_valid": true,
 "summary": "The BaseSchema 'Common Properties' table in content/docs/api/schema-reference.md now carries one row per declared member, in base.ts declaration order: 21 rows for 21 named members, up from 13 rows covering 16. Five under-stated types corrected (label and description to 'string | I18nLabel', ariaLabel to 'string | KeyedI18nLabel', visible and disabled to 'boolean | string'); five omitted members added (placeholder, style, data, bind, visibleWhen). The three combined cells were SPLIT rather than annotated, because the paired 'boolean / string' cell reads as an ordered mapping and that reading is exactly the false statement; splitting also makes completeness a straight zip against the interface, which is how five members went missing unnoticed. Two notes added below the table carry what a cell cannot: a concrete schema may narrow an inherited member and its own declaration wins, and the list is exhaustive for DECLARED members but not for ACCEPTED keys. Notes deliberately carry no counts, since a measured number in unpinned prose would reproduce the exact defect being fixed. Empty-frontmatter changeset; draft PR #7085.",
 "tests": "Gate union run at branch head 6dbef5210, AFTER the final commit; exit codes captured before any pipe, verdicts quoted from each gate's own printed line. check:doc-types exit=0 'Every documented component type is registered.' | check:doc-fences exit=0 'every TypeScript block in 224 document(s) is fenced ts/tsx/typescript' | check:control-bytes exit=0 'scanned 5861 tracked text file(s); skipped 85 binary' | check-changeset-presence exit=0 'no changeset is owed' | check-changeset-no-major exit=0 'No changeset declares a major bump' | check-doc-links exit=0 'Links are valid across 17 scan roots' | vitest, 5 BaseSchema pins incl. base-schema-zod-mirror-parity, run under the shared os-verify-lock: 'Test Files 5 passed (5) / Tests 29 passed (29)', wrapper VERDICT command-exit 0. NO ABLATION was run and none is claimed. DECLARED NARROWING: check:doc-snippets was not executed; its build closure is 21 packages and no dist existed. The narrowing is MEASURED, not asserted: the branch imports the gate's OWN exported scanFences and runs it over the before and after page, yielding 2 collected TS blocks each side with byte-identical bodies. Evidence is complete on all three required legs -- (1) the covered population comes from the gate's own DOC_EXTENSIONS and TS_FENCE_LANGUAGES constants, not my guess; (2) the count is 0 of 3 typescript fences and 0 of 24 json fences touched, read from the diff; (3) invariance holds because scanFences only pushes blocks whose fence language is in TS_FENCE_LANGUAGES and never collects content outside a fence, and the gate compiles each block in isolation. Membership was read off the declaration AND the mirror: a mechanical census of the base.ts interface body (22 entries, 21 named plus the index signature) with four positive controls (type, ariaLabel, disabled, index signature -- all HIT), plus base-schema-zod-mirror-parity.test.ts green, which reads the mirror's own .shape and compares it key-by-key against the declaration.",
 "mcp_calls": "6 -- one claim comment, one create_pull_request, three issue_write, this report comment. All bulk reads went through the zero-quota channels: git, the public single-card web page embedded JSON payload for the issue body and timeline, and repo-scoped REST for the dedupe corpus.",
 "open_questions": [
 {
 "question": "Does AGENTS.md rule #-1 (English-only docs) forbid a non-English VALUE inside an i18n example, when the example's whole purpose is to show a locale map? I hit this writing the label row and resolved it conservatively without a ruling.",
 "options": [
 "A -- describe the shape only. I wrote 'I18nLabel is the spec's inline locale map (string or a Record keyed by BCP-47 tag such as en or zh-CN)'. Zero non-English prose; the reader learns the shape but never sees a filled-in map.",
 "B -- show a filled example, e.g. an en/zh-CN pair with a real translated value. Teaches more, and is what base.ts's own JSDoc does, but puts the first CJK into the docs tree under a rule that admits no exception.",
 "C -- rule that i18n examples are a named carve-out from #-1, and say so in AGENTS.md."
 ],
 "recommendation": "A, which is what shipped -- it is the only option that needs no ruling, and it loses little. Flagging it because the census behind it is interesting: content/docs is 1 CJK page in 185, and that one page (guide/flow-designer.md:72-73) is itself an i18n illustration, so the de facto practice is 'avoid it, except to demonstrate localization' -- precisely the unruled case. If the maintainer prefers B or C, the label and description rows are a one-line edit."
 }
 ],
 "out_of_scope_findings": [
 "filed as #7086: check-doc-snippet-types cannot see a TypeScript fence opened inside a blockquote -- its scanFences anchor allows leading spaces/tabs only, so a '> ' prefixed opener is never collected and the block is silently uncompiled. Census over the gate's own 224-document population: exactly 1 such fence, on schema-reference.md lines 12-14, currently correct (all three symbols it imports are exported; bogus control returns 0). Three controls pass. Sibling of #5867 (wrong fence LANGUAGE), not a duplicate -- this one is correctly fenced and invisible by opener POSITION.",
 "filed as #7087: 18 of the 124 interfaces that extend BaseSchema narrow inherited 'disabled' back to boolean, while 0 narrow its twin 'visible'; label is narrowed by 29 and description by 32, ariaLabel by 1. The two twins were widened by #4581 on identical evidence and base.ts:320-325 records their previous asymmetry as accidental, yet a predicate string is a type error on ButtonSchema, InputSchema, SelectSchema and FormSchema while being accepted on visible everywhere. Filed as a DECLARATION question, not decided -- three coherent directions laid out for a maintainer ruling.",
 "filed as #7088: BaseSchema.hidden's JSDoc promises 'rendered but not visible (visibility: hidden)' while the renderer returns null for it exactly as for visible:false -- both are legs of one shouldHide chain feeding one flag (SchemaRenderer.tsx:1245 sets _hidden, :1386 returns null), and no branch can tell them apart. This nearly caused a bad edit: correcting the table's 'Inverse of visible' wording toward base.ts's JSDoc would have made the page LESS accurate, so that wording was relocated unchanged."
 ]
}

Premises corrected

Re-derived every claim in the order against origin/main at 592acafbe. The card's substance held; four surrounding claims did not.

Card and order — CONFIRMED. Table at lines 53-67 (order said 55-67; the header and delimiter rows are 53-54). All five under-stated rows confirmed at base.ts 139, 157, 376, 278, 327 and mirrored at base.zod.ts 94, 101, 211, 158, 190 — including the card's citation of base.zod.ts:190 for disabled, verbatim. All five omitted members confirmed declared with no row. hidden?: boolean is genuinely boolean-only, so the divergence is not uniform, exactly as the card says. 21 declared members, 13 rows covering 16 — all three counts reproduce.

ariaLabel — the row the order did not check: the card is RIGHT, and the correct spelling is the trap. Declared string | KeyedI18nLabel, the KEYED form, not I18nLabel. Copying the label / description pattern would have manufactured a new defect: base.ts:352-362 records that PR #4593 measured string | I18nLabel wrong on this slot in three ways before ruling #4580 Q2-B withdrew it. The order's own summary table was silent on this key's declared type, so this was the one row where guessing by analogy was available and wrong.

check:doc-key-tables does not exist in this repository. The card cites it as a third gate that judges key tables but not property tables. Controlled grep: 0 hits repo-wide for that name, against 10 hits for a known-present control string; it is absent from the 32 check:* scripts and from scripts/. objectui#5106's key-table logic lives inside check-doc-component-types.mjs, anchored on a Namespaced key | Bare-name fallback header. The card's conclusion — nothing reads this table — is correct and in fact stronger than its citation: no script anywhere parses a Markdown property table.

This page carries no plaintext fence. Before and after are identical: 27 fences, 24 json and 3 typescript. The order's item 5 asked what to report if one exists; the answer is that the plaintext hazard is a component-page phenomenon (#5867) and does not apply here. The gate-coverage conclusion is unchanged, and is established instead by the scanFences equivalence above.

This repo did not mangle the PR body. The order warned that footers are stripped from issue/PR bodies and angle-bracket generics collapse. Read back in full: the body is 11,291 bytes, all 10 sections and both 5-row evidence tables intact, Record<string, string \| number> and [key: string]: any survived verbatim, Closes #7079 intact, and the footer survived — the platform in fact appended a second session-URL footer rather than stripping mine. Both footers left in place, since a PATCH edit would downgrade the session form to bare. All three filed cards read back clean with footers intact.

Two censuses of mine were wrong, and both were caught by controls

Recording these because in both cases the wrong answer was a zero, and in one case it would have changed a shipped row.

visibleWhen readers: first answer 0, correct answer non-zero. My pattern matched schema.visibleWhen; the actual reader is newSchema.visibleWhen at SchemaRenderer.tsx:1197. A zero there would have made visibleWhen a declared-but-never-read member — a declaration question to file, not a row to write. Corrected, it is not merely read but is the canonical ADR-0089 predicate, evaluated first, ahead of visible and visibleOn, which the new row states. My control passed while the census was broken, because the control keys happened to exist in the lowercase form — a control that exercises the wrong failure mode is not a control.

CJK census: grep -P errored out and printed nothing, and I read the empty output as "0 files". The positive control failed loudly (character code point value in \x{} or \o{} is too large) and exposed it. Re-run in Python with a positive and two negative controls: 185 pages scanned, 1 contains CJK, not 0. The conclusion did not change, but the number I would have reported was fabricated by a broken channel.

Both are the failure the order named in advance. The order's own warning is what made me run the controls at all.

Scope held

No component page touched, no type touched, no fixture touched, no content/docs/releases/ touched. The json example above the table was left alone deliberately — it shows a valid subset, makes no type claim, and editing it would touch a fence this PR proves it does not touch. The 14 component pages spelling inherited disabled as boolean were left alone and no card claims they are wrong: #6347's 13-of-14 split was not re-measured at the page level, so no claim rests on it. The type-level measurement in #7087 is a different population, counted independently, and is stated as such.

Generated by Claude Code

---

Generated by Claude Code