spec: `ListView.exportOptions` is typed as a bare array, but the only renderer reads `exportOptions.formats`

[baozhoutao]

Reported from an app project (steedos-labs/os-project-titanwind-ehr#1161) on @objectstack/*@17.0.0-rc.6.

The divergence

@objectstack/spec types a list view's exportOptions as a bare array:

// packages/spec/src/ui/view.zod.ts:1438
exportOptions: z.array(z.enum(['csv', 'xlsx', 'pdf', 'json'])).optional()
 .describe('Available export format options'),

The only renderer of that property reads an object and looks for .formats:

// objectui/packages/plugin-grid/src/ObjectGrid.tsx:1394
const declared = schema.exportOptions?.formats || ['csv', 'json'];

objectui/packages/types/src/objectql.ts:785 declares the object shape
({ formats?, maxRecords?, includeHeaders?, fileNamePrefix? }) under the comment
"Aligned with @objectstack/spec ListViewSchema.exportOptions" — that comment is
false today; the two shapes have never matched.

Consequence for app projects

A project that follows the published spec type writes exportOptions: ['xlsx'].
At render time ['xlsx'].formats is undefined, so ObjectGrid falls back to
['csv', 'json'] and XLSX never appears in the export menu. Writing the object form
that Console actually reads makes the metadata fail its own @objectstack/spec type
check. There is no declaration that is both type-legal and functional, which is
what the reporting project hit.

Second defect on the same property: the dead 'pdf' member

The spec enum still admits 'pdf', but PDF export was closed NOT_PLANNED as
objectstack-ai/objectstack#1301, and ObjectGrid drops unsupported formats with only a
runtime console.warn (ObjectGrid.tsx:1403-1409). So exportOptions: ['xlsx','pdf']
type-checks, passes validate, passes tsc, and silently renders a menu without PDF —
the app author's only signal is a browser console line they may never see.

Repro

1. Declare exportOptions: ['xlsx', 'pdf'] on any object list view (spec-legal form).
2. Grant allowExport.
3. Open the list's export menu → only CSV and JSON, no XLSX, no PDF, no build/validate diagnostic.

What we're asking for

1. Pick one shape and make it the contract. Either spec adopts the object form
   Console implements (with array-form normalization for back-compat), or Console is
   fixed to read the array the spec publishes. Whichever side moves, the false
   "Aligned with @objectstack/spec" comment at objectui/packages/types/src/objectql.ts:785
   must be corrected in the same change.
2. Resolve 'pdf'. Given objectstack#1301 is NOT_PLANNED, the spec enum should
   drop 'pdf' (a breaking-but-honest narrowing), or a declared-but-unrenderable format
   should surface as a validate-time diagnostic rather than a runtime console.warn.

Business impact at the reporting project

The customer spec (§7.7) promises "download/print supports PDF/Excel export". Both halves
are currently blocked platform-side: XLSX by the contract mismatch above, PDF by
objectstack#1301.

Related

• Console-side twin: the list toolbar Print button — plugin-list: the list toolbar Print button is a bare window.print() — no preview, no output, silent no-op in headless/WebView objectui#4462
• objectstack-ai/objectstack#1301 — print / PDF export, closed NOT_PLANNED
• Project-side evidence: https://github.com/steedos-labs/os-project-titanwind-ehr/issues/1161#issuecomment-5265108797

[hotlong]

Triage → needs-user-decision (human floor: public-contract shape). Two contract questions, one property:

Q1 — which shape is the contract for ListView.exportOptions? Today the spec publishes a bare enum array (view.zod.ts:1438) and the only renderer reads an object (ObjectGrid.tsx:1394 → .formats), so no declaration is both type-legal and functional.
Q2 — the dead 'pdf' enum member (feature closed NOT_PLANNED as #1301; declared-but-unrenderable today, signalled only by a runtime console.warn).

Premises, with re-check commands:

• Spec side: git grep -n "exportOptions" origin/main -- packages/spec/src/ui/view.zod.ts
• Renderer side (objectui): git grep -n "exportOptions" -- packages/plugin-grid/src/ObjectGrid.tsx packages/types/src/objectql.ts (the "Aligned with @objectstack/spec" comment at types/src/objectql.ts:785 is false today)
• PDF status: objectstack#1301 closed NOT_PLANNED

Options:

• A — spec adopts the object form the renderer reads ({ formats?: [...] } with array-form normalization for back-compat); drop 'pdf'.
• B — renderer moves to the spec's bare array; the objectui object type is retired and the false comment corrected in the same change; drop 'pdf'.
• C — leave both, document the divergence (recorded for completeness; keeps the trap).

Four-lens:

• Platform long-term coherence: B keeps one minimal contract and moves the sole consumer onto it. A imports objectui's speculative keys (maxRecords, includeHeaders, fileNamePrefix — no evidence the renderer reads any of them) into the spec unless trimmed to formats alone, at which point A is just B with an extra wrapper object.
• Measured business pull: real — titanwind-ehr (§7.7) needs XLSX in the export menu today; A or B both unblock it. Nothing measured pulls the three extra object keys.
• AI-agent error-resistance: a closed enum array is the hardest shape to get wrong; the current type-legal ≠ functional split is the worst possible state. 'pdf' must leave the enum or become a validate-time refusal — a runtime console.warn is silent tolerance.
• Startup scope discipline: B is the narrowest change that makes declared = enforced; every extra declared key is a permanent obligation.

Recommendation: B — fix ObjectGrid to read the spec's array, correct the false alignment comment in the same change, and drop 'pdf' from the spec enum as an honest narrowing. Richer export config later is a new Feature decision, not part of this repair.

Execution note once ruled: contract-first split — the spec enum narrowing lands here first (domain:spec, contract-changing ⇒ fable clause applies), the objectui renderer/type fix follows with Blocked-by: on it.

---

Generated by Claude Code

[hotlong]

Maintainer ruling — 2026-08-12 (live PM chat, session_01GxKQfv3k8b6a2d2QrZU411; maintainer sam, verbatim: 「接受你的全部建议。」 accepting the decision-box analysis in full). Moved out of the decision box → pm:queue.

Ruling: option A — the spec adopts the object form (exportOptions: { formats?: … }, with array-form normalization for back-compat), and 'pdf' leaves the enum (honest narrowing; ⛔ not a runtime console.warn, which is silent tolerance).

⚠️ This reverses the earlier triage lean toward option B, because B's stated premise is falsified on current objectui main. The triage note read "no evidence the renderer reads any of maxRecords, includeHeaders, fileNamePrefix"; ObjectGrid.tsx (now ~:1529–1575) in fact reads five object keys — formats, maxRecords, includeHeaders, fileNamePrefix, and an undeclared streaming opt-out. Option B would therefore delete four live renderer behaviours, not adopt speculative keys.

Execution order (contract-first, unchanged): the spec change lands here first — domain:spec semantic lane, so the claude-fable-5 clause applies — and the objectui renderer/type reconciliation follows with Blocked-by: on this card. The undeclared streaming key must be either declared in the same pass or removed on the objectui side; a fifth undeclared key surviving this fix would recreate the defect.

Business note for sequencing: steedos-labs/os-project-titanwind-ehr#1161 has a contractual §7.7 export commitment blocked with no legal-and-functional declaration available today — this is the only decision-box card with an external customer waiting. Prioritise accordingly within the spec lane.

---

Generated by Claude Code