docs(adr): ADR-0089 — unify conditional-visibility predicate under visibleWhen#2641
Merged
Merged
Conversation
…bleWhen Propose collapsing the same "show when CEL predicate is TRUE" concept — spelled visibleWhen (data field), visibleOn (view form), and visibility (page component) — onto a single canonical visibleWhen, keeping the old names as @deprecated aliases normalized at parse time. Chooses visibleWhen (not visibleOn) to stay aligned with the existing readonlyWhen/requiredWhen family and the conditionalRequired -> requiredWhen precedent. Adds .strict() + a lint rule so a mis-layered or mis-rooted key becomes a loud error instead of being silently stripped by zod. The boolean `visible` (Tab on/off) stays out of scope. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PHCX3Qo8NjyMiMMMayygjg
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
os-zhuang
added
the
skip-changeset
Claude
os-zhuang
marked this pull request as ready for review
July 5, 2026 16:22
7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds ADR-0089 (Proposed) proposing that the conditional-visibility predicate — the same "show this only when the CEL predicate is TRUE" concept, currently spelled three different ways by layer — be unified under a single canonical name,
visibleWhen.visibleWhenpackages/spec/src/data/field.zod.ts:592, 108visibleOnpackages/spec/src/ui/view.zod.ts:762, 781visibilitypackages/spec/src/ui/page.zod.ts:109Why
Because every key is
.optional()and the schemas run zod's default strip mode, a key placed on the wrong layer (visibleOnon a data field,visibleWhenon a form field) is silently dropped — no type error, no validation error, the element just renders unconditionally. For an AI author that is the worst failure mode: no signal to self-correct from. Three compounding traps: same concept switches name by layer;visibleOnitself has two binding roots (recordin runtime forms vsdatain metadata-editing forms); and failure is silent.Decision (summary)
visibleWhenacross all layers — chosen overvisibleOnbecause it stays aligned with the existingreadonlyWhen/requiredWhenfamily and the already-resolvedconditionalRequired → requiredWhenconsolidation (field.zod.ts:594-598). PickingvisibleOnwould break that triad.visibleOn/visibilitybecome@deprecatedaliases, normalized tovisibleWhenat parse time — zero breaking change, shipping as an ADR-0087 L1 invisible break..strict()+ a lint rule so a mis-layered or mis-rooted (data.vsrecord.) key becomes a loud error instead of a silent no-op (per ADR-0049 enforce-or-remove, ADR-0078 no-silently-inert).visible(Tab on/off) is a static flag, not a predicate — explicitly out of scope.Scope
Docs-only: a single new ADR file at
docs/adr/0089-unify-visibility-predicate-naming.md. No code changes yet — this is the design decision; the schema/lint/codemod implementation would follow in a separate PR if the ADR is accepted.🤖 Generated with Claude Code
https://claude.ai/code/session_01PHCX3Qo8NjyMiMMMayygjg
Generated by Claude Code