docs(adr): ADR-0085 — presentation intent as cross-surface semantic roles, never per-surface hint blocks#2520
Merged
Conversation
Presentation intent on ObjectSchema is declared only as cross-surface semantic roles (nameField / compactLayout / stageField / fieldGroups). Deletes the detail passthrough block and views.* reader paths, types stageField (string | false), converges fieldGroups collapse semantics on one enum, single-sources the group derivation in @objectstack/spec. Surfaced by the objectui#2149 review: two-way fieldGroups key drift (spec defaultExpanded vs UI collapsible/collapsed), typed-but-no-op hideReferenceRail, zero-author views.*/detail.* keys across both repos. Supersedes the detail.* passthrough approach of objectui#2065/#2148 §6. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
os-zhuang
added a commit
that referenced
this pull request
Jul 2, 2026
…ame, detail block removal, collapse enum, shared fieldGroups derivation (#2521) * feat(spec): ADR-0085 semantic roles — stageField, highlightFields rename, detail block removal, collapse enum, shared fieldGroups derivation Executes ADR-0085 (#2520) in the spec layer: - ObjectSchema gains stageField: string | false (lifecycle role; false suppresses stage heuristics) — legitimizes the key renderers already read. - compactLayout → highlightFields (ordered most-important fields; drives default columns, cards, previews, detail highlight strip). Old key stays a parse-time alias, preserved on output (ADR-0079 pattern). 35 platform objects + app-todo migrated. - fieldGroups[].collapse enum replaces defaultExpanded and the UI-dialect collapsible/collapsed pair (both aliased at parse for one minor); visibleOn removed (zero consumers, ADR-0049 enforce-or-remove). - detail passthrough UI-hints block removed (zero authors; the typed hideReferenceRail was a proven no-op; renderViaSchema retires with the legacy monolith render path in objectui). - New @objectstack/spec/data deriveFieldGroupLayout — single source of the grouping semantics (declared order, empty groups dropped, ungrouped trailing bucket minus system fields, collapse passthrough incl. aliases). - New @objectstack/lint validateSemanticRoles (wired into os lint): warns on dangling Field.group / empty declared groups / unknown stageField & highlightFields names (ADR-0078 completeness gate). - Liveness ledger updated (detail dropped; highlightFields + stageField registered live; compactLayout marked deprecated alias). spec 6666 tests, lint 112, cli 440, platform-objects 63 all green; api-surface unchanged; check:liveness green; app-todo typecheck green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: teach highlightFields/stageField in place of compactLayout (ADR-0085) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(spec): mirror highlightFields back onto compactLayout during transition Browser dogfood of the rename found a live gap: metadata authored with the canonical highlightFields key parsed to output WITHOUT compactLayout, so current renderers that still read the old key (ObjectGrid default columns, card compact views, vendored console) silently lost their curated field list. The alias now mirrors both directions (canonical wins when both are present); the back-fill is removed together with the deprecated key. Verified end-to-end in a running app (app-todo, HMR console against the worktree server): default list columns, mobile card fields, detail highlight strip, stageField stepper, and field-group form sections all render from the renamed keys. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(dogfood): drop stale visibleOn row from expression ledger ADR-0085 §3 removed fieldGroups[].visibleOn from ObjectSchema (declared, zero consumers — enforce-or-remove per ADR-0049). The ADR-0060 ratchet correctly flagged the ledger row as a stale cover; drop it until the key returns with a real enforcement path. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
5 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
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.
What
ADR-0085: object presentation intent is declared only as cross-surface semantic roles —
nameField/highlightFields(renamed fromcompactLayout, ADR-0079 alias pattern) /stageField: string | false(newly typed) /fieldGroups. The specdetailpassthrough block is deleted,views.*reader paths retire with no deprecation window (zero authors, evidence in the ADR), fieldGroups collapse semantics converge on onecollapseenum, and the group-derivation helper is single-sourced in@objectstack/spec.Why now
Reviewing objectui#2149 (fieldGroups → detail wiring) surfaced the full pathology of the hint channels:
views.*: readers-only, zero authors across both repos — dead protocol;detailpassthrough: 3 typed keys vs 9 read; typedhideReferenceRailis a no-op for spec authors (rail is default-off; the only enabling key was never typed);fieldGroups: two-way collapse-key drift — specdefaultExpandedhas no consumer, the UI readscollapsible/collapsedwhich the spec rejects, so designer-authored objects collapse and spec-authored packages silently don't.Every failure mode is a silent no-op — the worst shape when AI is the primary author (ADR-0078).
Supersedes the
detail.*passthrough approach of objectui#2065 / objectui#2148 §6 (mechanism replaced; both issues' goals still ship).Execution (tracked separately, not in this PR)
stageFieldunion,highlightFieldsrename + alias, deletedetailblock,collapseenum,deriveFieldGroupLayout, lint warnings, ~36 in-repo author migrations;detail.*/views.*reads);renderViaSchema);collapsible/collapsed→collapse);🤖 Generated with Claude Code