[WIP] Update specification documentation for clarity

[Copilot]

Fix missing showDataLabels in chart configurations

Problem

Build failing in GitHub Actions (run #21536535900) due to TypeScript errors:

• ChartConfigSchema defines showDataLabels with .optional().default(false)
• TypeScript requires this field in chart configurations when using Report type
• 5 chart configurations in examples/crm/src/ui/reports.ts were missing the showDataLabels property
• Examples/host build was failing with error TS2741

Root Cause

Zod's type inference behavior with .optional().default():

• Field is optional in the input type (z.input<>) - can be omitted
• Field is required in the output type (z.infer<>) - always has value after parsing
• The Report type was using z.infer<>, making it the output type
• Configuration files need the input type to allow omitting fields with defaults

Solution

Following the pattern established by defineStack and API request types:

1. Added new input types: ReportInput, ReportColumnInput, ReportGroupingInput, ReportChartInput
2. These use z.input<> instead of z.infer<> to allow optional fields with defaults
3. Updated CRM example to use ReportInput instead of Report
4. Added documentation explaining when to use each type

Changes

• Analyze the build failure from GitHub Actions
• Identify the root cause in Zod type inference
• Add ReportInput and related input types in packages/spec/src/ui/report.zod.ts
• Update CRM reports to use ReportInput type in examples/crm/src/ui/reports.ts
• Build spec package successfully
• Build CRM example successfully
• Build host example successfully (was the failing one)
• Run full build successfully
• Run tests - all 2460 tests passed
• Code review - no issues found
• Security scan - no vulnerabilities found

Pattern Established

Configuration types should use Input types to allow optional fields with defaults:

• defineStack() uses z.input<> for configuration
• API request types use z.input<>
• Output/runtime types use z.infer<>

Security Summary

No security vulnerabilities found in the changes.

Original prompt

引用: https://github.com/objectstack-ai/spec/actions/runs/21536535900/job/62063308186#step:8:1

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jan 31, 2026 1:56am

[Copilot]

Pull request overview

Fixes TypeScript build failures caused by Zod .optional().default() fields (e.g., showDataLabels) being required in z.infer<> output types, by introducing explicit z.input<> “configuration” types for reports and updating the CRM example to use them.

Changes:

• Added ReportInput (and related input types) using z.input<> in packages/spec/src/ui/report.zod.ts.
• Updated examples/crm/src/ui/reports.ts to type report definitions as ReportInput instead of Report.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
packages/spec/src/ui/report.zod.ts	Introduces ReportInput/related input types to represent configuration-friendly (pre-parse) shapes while keeping Report as the parsed/output type.
examples/crm/src/ui/reports.ts	Switches CRM report definitions to ReportInput so defaulted chart fields (like showDataLabels) can be omitted without TS errors.