docs(spec): alias guidance for visible/showWhen/disabled on the visibleWhen shapes (#7832) - #7884
Merged
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 106 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
⛔ 7 release-owned page(s) also reference the affected code. These are read-only:
|
github-actions
Bot
added
documentation
…leWhen shapes (#7832) Give the `visibleWhen`-family strict shapes the curation the action shapes have carried in the opposite direction since #3746, so `visible` / `showWhen` / `disabled` written on the wrong surface names the key the author wanted. Acceptance is byte-identical: every key touched here was rejected before and is rejected after. `RowCrudActionOverrideSchema` moves from a hand-written `.strict()` to the shared `strictObject` helper, which is `z.object(shape, { error }).strict()` — the same door with a curated map. Changed: `RowCrudActionOverrideSchema` (surface was unnamed; `showWhen` renames, `visible`/`disabled` answered in prose naming both `enabled` and the `*When` slot), `FieldSchema` (`showWhen` renames, `visible` answered in prose naming `hidden` and its inversion alongside `visibleWhen`), `FormFieldSchema` (`disabled` renames onto `readonly`). Already compliant: `SelectOptionSchema`, and form sections / page components via the ADR-0089 guidance set. Deliberately uncurated: `disabled` where the shape declares no landing key. Fixes #7832 { "issue": 7832, "status": "done", "branch": "claude/issue-7832-visiblewhen-aliases", "pr": "#7884", "premise_still_valid": true, "summary": "Premise held, but only PARTLY as the card described it — three of the five enumerated surfaces needed nothing, and the `disabled` ask was impossible on four of five. Measured every surface against origin/main before editing. CHANGED: (1) RowCrudActionOverrideSchema — the real gap; it produced zod's bare `Unrecognized key: \"visible\"` with the surface unnamed. Converted to strictObject (verified acceptance-equivalent: strictObject IS z.object(shape,{error}).strict(), strict-object.ts:327). Added alias showWhen->visibleWhen and guidance prose for visible/disabled naming BOTH landing keys — honoring #7816's note that the boolean reading belongs on `enabled`, not `visibleWhen`. Prose not alias because this shape splits into enabled+visibleWhen+disabledWhen what a custom row action spells with one dual-form key, so a rename must guess. (2) FieldSchema — visible/showWhen had no hint at all; showWhen renames onto visibleWhen, visible answered in prose naming `hidden` (INVERTED: visible:false is hidden:true) and `visibleWhen`; a rename either way would have the author ship a CEL slot a boolean, or the inverse of what they wrote. FieldSchema's existing `disabled -> readonly` is already correct (a field has readonlyWhen, not disabledWhen) and was left alone. (3) FormFieldSchema (view.zod.ts, NOT named by the card) — the one view/page shape declaring `readonly`, so it gets `disabled -> readonly`, filed on its own call site rather than the shared VISIBILITY_STRICT_OPTIONS, which two sibling consumers would make false. ALREADY COMPLIANT: SelectOptionSchema (card was stale, as the claim comment warned); FormSectionSchema + PageComponentSchema + FormFieldSchema answer visible/showWhen through VISIBILITY_STRICT_OPTIONS's ADR-0089 guidanceSets — VISIBILITY_KEY_PATTERN /vis|conceal|hidden|show.?when/i matches both, and a set match `continue`s past the rename channel, so an alias there would be DEAD CODE, not a second opinion. OUT OF SCOPE with reason: `disabled` on SelectOptionSchema / FormSectionSchema / PageComponentSchema — none declares disabledWhen, disabled or readonly, so a row would name a key the shape rejects next (alias-integrity.test.ts fails such a row outright); pinned as a deliberate gap that FAILS if any of them ever gains a disabled-ish key. Also drafted and dropped: hideWhen->visibleWhen on the row override — hideWhen is the INVERSE predicate, so the rename would preserve the expression and flip its meaning.", "tests": { "new_file": "packages/spec/src/shared/visible-when-alias-guidance.test.ts (19 pins: curated messages name the intended key; already-compliant surfaces pinned so a later sweep can tell 'answered' from 'missed'; deliberate gaps pinned to fail if a landing key appears; acceptance-invariance asserted directly)", "spec_full_suite": "PASS — 380 files / 10002 tests (npx vitest run in packages/spec)", "post_rebase_affected_suites": "PASS — 24 files / 808 tests (src/shared, object-strictness-batch20, field, view, page)", "alias_integrity_audit": "PASS — every new row judged as a claim about its schema (target declared, key not declared, no probe collision)", "typecheck": "PASS — npx tsc --noEmit -p packages/spec/tsconfig.json, clean", "spec_build": "PASS — pnpm build, dist hash 3fcf5590a8092eea", "check_spec_parsed_alias": "PASS — 18 self-test assertions; 1512/826/686 OK", "check_adr_anchors": "PASS — 48 anchored files, 22537 citations resolve", "check_nul_bytes": "PASS — 7215 files scanned, clean", "acceptance_equivalence": "VERIFIED EMPIRICALLY — 17 surface x key pairs probed against a real built dist before and after; every one REJECTED before and REJECTED after, no verdict moved. Only messages differ.", "ci": "in_progress — draft PR #7884 just opened; PM owns CI convergence" }, "open_questions": [ "FormFieldSchema was NOT in the card's enumeration but is in ui/view.zod.ts, in the visibleWhen family, and is the only view/page shape that can answer `disabled` truthfully. Included and flagged rather than silently skipped — trivially revertible if the PM wants the card's list honored literally.", "Three surfaces (select option, form section, page component) reject `disabled` loudly but with no pointer, because they have no key to point at. A wrong-layer prescription ('this layer has no disabled — gate with visibleWhen') was considered and NOT written: it is a claim about the whole platform rather than about the shape, and I could not verify it to the standard the other rows meet. Recorded as an out_of_scope_finding instead.", "The card asked for aliases; three rows landed as `guidance` prose instead. The rule used: one landing key => alias, two (boolean + predicate) => prose naming both, none => nothing. Stated in the PR body and in the test file's docblock so it can be overruled in review." ], "out_of_scope_findings": [ "The card's enumeration was stale in two directions, not one. Beyond the SelectOptionSchema staleness the claim comment flagged, form sections and page components were ALSO already compliant for visible/showWhen (via the ADR-0089 guidanceSets added in #6619) — so 3 of 5 enumerated surfaces needed no visible/showWhen work, and the single real gap was RowCrudActionOverrideSchema.", "`disabled` on view/page shapes has no vocabulary at all: FormSectionSchema and PageComponentSchema declare no readonly/disabled/disabledWhen key, so there is no way to express 'this section/component is disabled'. Whether that is a deliberate design boundary or a gap is a question for domain:spec, not this card. If it is a gap, the alias rows this PR could not write become writable.", "VISIBILITY_KEY_PATTERN (/vis|conceal|hidden|show.?when/i) silently makes any alias for a vis-shaped key dead on every VISIBILITY_STRICT_OPTIONS surface, because a guidanceSet match skips the rename channel. That is correct behaviour but not documented at the alias-authoring site — a future card adding a vis-shaped alias to those shapes would write dead code and no gate would say so (alias-integrity checks that a target is declared, not that the row is reachable past a set). Possible follow-up: extend alias-integrity to fail an alias key that a guidanceSet in the same options already consumes.", "#7816 ask 2 (one canonical spelling across the action and visibleWhen vocabularies) remains open and untouched. If it converges them, every row added here becomes the migration hint, exactly as the card predicted." ] }
os-zhuang
force-pushed
the
claude/issue-7832-visiblewhen-aliases
branch
from
August 12, 2026 02:13
d261aeb to
85fe3ee
Compare
This was referenced Aug 12, 2026
os-zhuang
marked this pull request as ready for review
August 12, 2026 02:29
This was referenced Aug 12, 2026
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
1 participant
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.
Fixes #7832
ui/action.zod.tshas carried this table in the OTHER direction since #3746 — on an actionvisible/disabledare canonical, so the aliases runvisibleWhen → visible,showWhen → visible,disabledWhen → disabled. The reverse direction was curated on somevisibleWhensurfaces and bare on others, and nothing recorded which was which.Acceptance is byte-identical. Every key named below was rejected before this PR and is rejected after it; only the message differs.
RowCrudActionOverrideSchemamoves from a hand-written.strict()to the sharedstrictObjecthelper, which isz.object(shape, { error }).strict()(packages/spec/src/shared/strict-object.ts:327) — same door, curated map behind it. Section 4 of the new test file pins that directly. #7816's ask 2 (choosing ONE canonical spelling) is untouched: no schema widened, no ADR-0087/0089 territory entered.Per-surface accounting
Every surface #7832 enumerates, plus the two neighbours the measurement turned up.
visibleshowWhendisabledRowCrudActionOverrideSchema(data/object.zod.ts)enabled: falseandvisibleWhenvisibleWhendisabledWhen(+enabled: falsefor the boolean)FieldSchema(data/field.zod.ts)hidden(inverted) andvisibleWhenvisibleWhendisabled → readonlyalready present (field.zod.ts:459)SelectOptionSchema(data/field.zod.ts)visibleWhen(field.zod.ts:149)visibleWhendisabledWhen/disabled/readonlyFormSectionSchema(ui/view.zod.ts)PageComponentSchema(ui/page.zod.ts)FormFieldSchema(ui/view.zod.ts)readonlyTwo corrections to the card's enumeration, both measured on
mainbefore editing:SelectOptionSchemawas already done (as the claim comment warned) — and so were form sections and page components, which answervisible/showWhenthroughVISIBILITY_STRICT_OPTIONS's ADR-0089guidanceSetsentry.VISIBILITY_KEY_PATTERNis/vis|conceal|hidden|show.?when/i, which matches both spellings. A set matchcontinues past the rename channel, so an alias for either key on those three surfaces would have been dead code, not a second opinion.disabled → disabledWhenis impossible on four of the five enumerated surfaces. OnlyRowCrudActionOverrideSchemadeclaresdisabledWhenat all. Select options, form sections and page components declare no disabled-ish key, so a row there would name a key the shape rejects next —alias-integrity.test.tsfails such a row outright.FormFieldSchemadoes declarereadonly, so it gets the row; it is filed on that call site rather than on the sharedVISIBILITY_STRICT_OPTIONSprecisely because the other two consumers would then be lying.FormFieldSchemais the one surface here the card did not name. It is inui/view.zod.ts, in the enumerated family, and it is the only view/page shape that can answerdisabledtruthfully — flagging rather than silently skipping.Why some rows are prose and not renames
The rule the diff encodes:
visible(actions) vsvisibleWhen(fields / sections / userActions) — and the alias guard only covers one direction #7816's own note, and whyRowCrudActionOverride.visiblepoints atenabledandvisibleWhen. OnFieldSchemathe two answers additionally have opposite polarity (visible: falseishidden: true), so a rename ontohiddenwould have the author ship the inverse of what they wrote.One row was drafted and dropped:
hideWhen → visibleWhenon the row override.hideWhenis the inverse predicate, so the rename would preserve the author's expression while flipping its meaning. The ADR-0089 set answershiddenWhenwith prose for the same reason.Verification record
All commands run in a dedicated worktree, rebased onto
origin/main@f28ef3bimmediately before opening this PR. Neither serial-constraint sibling (#7758, #7813) has landed; the two commits that did land since dispatch touch nopackages/specfile.Before/after, measured against a real built
dist(abridged — full sweep covers 17 surface×key pairs):Every one of the 17 pairs was
REJECTEDbefore andREJECTEDafter — no verdict moved.Gates:
Post-rebase re-run of the affected suites (
src/shared/,object-strictness-batch20,field,view,page): 24 files / 808 tests passed.alias-integrity.test.tsis the gate that matters most here — it judges every new row as a claim about its schema (target declared, key not declared, no probe collisions) and it passes with the new tables registered.Tests
New:
packages/spec/src/shared/visible-when-alias-guidance.test.ts(19 pins). It asserts the curated messages name the intended key on the three changed surfaces, pins the already-compliant surfaces (whose behaviour was unpinned until now, so a later sweep can distinguish "already answered" from "nobody got to it"), pins the deliberate gaps with a probe that fails if any of those shapes ever gains a disabled-ish key — at which point the row becomes owed — and pins acceptance-invariance directly.Changeset:
patchfor@objectstack/spec(curated error messages are parse-reachable strings — E13).Generated by Claude Code