Migrate the remaining ListView legacy vocabulary to spec-canonical keys, and audit ObjectView/DetailView (#2231 phases 4–5)

[os-zhuang]

Context

#2231 has been closing the @object-ui/types ↔ @objectstack/spec/ui fork in phases:

phase	PR	what it closed
1	#2622, #2636	ListViewSchema derived from the spec; the spec-bridge's third hand-written copy retired
2	#2882	every remaining "Mirrors @objectstack/spec/ui X" sub-schema (ViewDataSchema, ListColumnSchema, SelectionConfigSchema, PaginationConfigSchema, HttpRequestSchema, the whole theme family) reduced to spec re-exports, guarded by a reference-identity test
3	(in flight)	the five per-view-type configs (kanban/calendar/gantt/gallery/timeline) derived from the spec, plus the two rendering bugs the fork had been hiding

What remains is the part that was never a reference swap: objectui still uses a different vocabulary from the protocol for the same concepts at the ListView top level, and two view schemas have never been audited at all.

---

Scope A — the remaining legacy ListView vocabulary

ListViewSchema's drift guard (packages/types/src/__tests__/list-view-spec-parity.test.ts) sanctions ~50 local keys. Most are renames of a spec key, not genuine objectui concerns:

objectui (legacy)	spec (canonical)
viewType	type (the view kind; objectui's type is the component discriminator)
fields	columns
filters (tuple/CEL array)	filter (ViewFilterRuleSchema[])
showSearch / showSort / showFilters / showGroup / showHideFields / showColor / showDensity	userActions
densityMode	rowHeight
objectName	data: { provider: 'object', object }
aria: { label, describedBy, live }	AriaPropsSchema (ariaLabel, ariaDescribedBy, role)
sharing: { visibility, enabled, … }	ViewSharingSchema ({ type, lockedBy })
conditionalFormatting, exportOptions	the spec shapes are narrower

Why this needs its own project. Unlike phases 1–3 this is not type-level. Read-sites consume the legacy names (packages/plugin-list/src/ListView.tsx, components/ViewSettingsPopover.tsx, packages/plugin-view/src/ObjectView.tsx, packages/app-shell/src/views/{ObjectDataPage,ObjectView,InterfaceListPage}.tsx, packages/react/src/hooks/useDensityMode.ts), and stored view metadata in user databases carries the legacy keys. A rename with no migration path silently invalidates or strips existing views.

Per AGENTS.md Commandment #0.1 the answer is not a renderer-side ?? dual-read. The sanctioned precedent is a normalizer at the contract, the way @objectstack/spec folds legacy filter-operator spellings on parse (VIEW_FILTER_OPERATOR_ALIASES + normalizeFilterOperator, documented there as "a migration bridge … may be dropped in a future major"). So each rename wants: spec-side preprocess → objectui read-sites moved to the canonical key → legacy key dropped from the sanctioned set.

Timing matters. @objectstack/spec is at 16.x RC. Vocabulary alignment is cheap inside the RC window and a breaking major afterwards.

Suggested order — one PR each, green build + consumer regression per step

1. fields → columns (pure alias, smallest read-site surface)
2. densityMode → rowHeight
3. the show* family → userActions
4. filters → filter
5. aria / sharing / conditionalFormatting / exportOptions → the spec sub-shapes
6. objectName → data.provider: 'object' (largest — touches every ObjectQL component)

Carried over from phase 3

• Drop the four deprecated aliases phase 3 kept for back-compat once stored metadata has been migrated: kanban.groupField, kanban.cardFields, gallery.imageField, timeline.dateField.
• Promote calendar.defaultView into @objectstack/spec — it is the one per-view-type field with no spec counterpart, so it is still a local extension.

---

Scope B — audit ObjectViewSchema / DetailViewSchema

Never touched by #2231. Both are still hand-written BaseSchema.extend({ … }):

• ObjectViewSchema (packages/types/src/zod/objectql.zod.ts) — a composite (grid + form + toolbar flags). The nearest spec counterpart, ObjectListViewSchema (packages/spec/src/ui/view.zod.ts), is not 1:1.
• DetailViewSchema (packages/types/src/zod/views.zod.ts) — nearest counterpart is spec FormViewSchema, also not 1:1.

The deliverable here is an audit, not a swap: field by field, decide promote-to-spec / keep-local / drop — the same triage that made the ListView derivation safe. Only then decide whether a derivation is even the right shape, or whether the spec should grow a genuine composite-view schema.

---

Also surfaced (small, independent)

useColumnSummary's computeAggregation (packages/plugin-grid/src/useColumnSummary.ts) implements only count / sum / avg / min / max. The spec's ColumnSummarySchema declares eleven functions, so count_empty, count_filled, count_unique, percent_empty, percent_filled and none currently compute null and render an empty footer — a declared ≠ enforced gap. Either implement the six or trim the spec enum.

---

Definition of done

• The sanctioned-local set in list-view-spec-parity.test.ts contains only fields that are genuinely objectui renderer concerns (target: near-empty).
• No renderer reads a legacy key; whatever legacy acceptance remains lives in one documented normalizer, not scattered ?? fallbacks.
• ObjectViewSchema / DetailViewSchema have a written field-level verdict.

Related

• objectstack#3761 promotes ListColumn.prefix and the { type, field } summary form into the spec. When it releases, @object-ui/types drops its last ListColumnSchema.extend() and that schema becomes a plain re-export.

[os-zhuang]

Findings before step 2 — the suggested mechanism doesn't hold, and one item is already done

Tracing every read-site for the six renames turned up three things that change the plan. All verified directly against the two repos.

1. A spec-side z.preprocess would never run

The issue proposes folding each legacy key at the contract, on the normalizeFilterOperator precedent. That precedent works because filter rules are parsed. List-view metadata is not.

Nothing on the render path parses a view through zod:

• stored metadata goes client.meta.getItems('view') → mergeViewsIntoObjects (plain object spread) → viewList assembly → renderListView → <ListView schema={…}> — no parse/safeParse anywhere on it;
• SchemaRenderer runs validateSchemaOnce under __DEV__ only, and that is a hand-rolled non-zod checker that never touches list-view keys and rewrites nothing;
• the ListViewSchema at the render site (packages/app-shell/src/views/ObjectView.tsx) is a TypeScript type annotation, erased at compile time;
• every ListViewSchema.safeParse call site in the repo is a test, the offline CLI validator (packages/cli/src/commands/validate.ts), or the VS Code extension.

So the fold has to be anchored to a call site, not a schema. #2932 does that for step 1: one documented normalizeListViewSchema in @object-ui/core, invoked once at the ListView component boundary — the single point every list-view render passes through regardless of host. Same doctrine as the issue asks for (one normalizer, no scattered ??), different anchor.

2. fields / filters / objectName are sanctioned names in the spec — just in the other tier

@objectstack/spec deliberately maintains two vocabularies for <ListView>, in packages/spec/src/ui/react-blocks.ts:

dataProps:    ['columns', 'sort', 'searchableFields', 'userFilters', 'pagination',
               'grouping', 'rowHeight', 'selection', 'rowActions', 'inlineEdit'],
interactions: [ OBJECT_NAME, viewType, filters, navigation, onRowClick, onNavigate,
                { name: 'fields', type: 'string[]', kind: 'binding',
                  description: 'Limit/order the columns shown …' }, options ],

objectName, tuple-filters and fields are the React-tier prop names; columns/rowHeight are the metadata-tier names. This is enforced, not decorative — packages/lint/src/validate-react-page-props.ts checks real JSX against REACT_BLOCKS, and react-conformance.baseline.json ratchets the spec↔component prop diff.

Consequences for the plan:

• steps 1–5 are unaffected as metadata migrations, which is what they are;
• step 6 (objectName → data.provider:'object') needs a decision upstream first. Deleting objectName from the ListView surface contradicts a prop the spec currently declares and lints for. Either react-blocks drops it too, or step 6 is metadata-only and objectName stays a sanctioned React-tier prop forever;
• the sanctioned-local set in list-view-spec-parity.test.ts therefore cannot go fully empty — fields/filters/objectName keep a schema anchor for the React tier. "Near-empty" should be re-read as "no key that a renderer reads."

3. A spec-side fold wouldn't reach stored metadata anyway — and the release window has closed

Two more blockers on the upstream route:

• The write path discards the parse output. packages/metadata-protocol/src/protocol.ts documents it: "We do NOT replace the persisted document with parsed.data; the original payload is stored verbatim so Studio-only auxiliary fields … survive the round-trip." sys_view_definition.config is a free-form JSON column that is never re-parsed on read. A z.preprocess would make legacy configs validate, but the stored blob keeps the legacy keys and objectui still sees them on the wire.
• The RC window the issue counted on is gone. @objectstack/spec is at 16.1.0, and framework's changesets is in rc pre-mode with 16 major bumps already queued — the next cut is 17.0.0-rc.0, which does not satisfy objectui's ^16.0.0-rc.0 (pinned in 13 manifests). Any spec-side step is now gated on a 13-manifest range bump plus a maintainer merging the Version Packages PR. "Cheap inside the RC window" no longer applies.

4. The "also surfaced" computeAggregation item is already done

Shipped by #2897 — all eleven ColumnSummarySchema functions compute, and packages/plugin-grid/src/__tests__/summary-spec-parity.test.ts now guards the renderer's set against the spec enum. The checklist item can be ticked.

---

Three defects found while tracing, worth folding into the remaining steps

1. densityMode beats rowHeight — ListView.tsx's resolvedDensity checks the legacy key first, so a view carrying both renders the legacy value. Every other pair resolves canonical-first. Step 2 should fix the precedence, not just the read.
2. filters vs filter splits by visualization — ListView.tsx reads schema.filters; its sibling ObjectGallery.tsx reads schema.filter; ObjectGrid.tsx reads schema.filter. A view carrying only one of the two filters differently depending on which visualization is active. Step 4 closes a live bug, not just vocabulary.
3. The store is already mixed-vocabulary — runtime-metadata-persistence.ts persists canonical data.object and ObjectDataPage's "Save as view" persists canonical filter, while app-shell/src/views/ObjectView.tsx persists legacy densityMode. Whatever the migration does, the write side has to be canonicalized in the same step as the read side or the two keep re-seeding each other.

Suggested revision to the order

Steps 1–5 proceed as listed, each as a metadata-tier rename anchored at normalizeListViewSchema — the normalizer now exists, so each subsequent step is a fold + read-site sweep + producer sweep, with the legacy key left declared and input-only. Step 6 blocks on an upstream decision about react-blocks.ts, so it should be split out of this issue rather than sequenced last.