[Feature] hide axes when series is empty

[xuefei1313]

[中文版模板 / Chinese template]

🤔 This is a ...

• New feature
• Bug fix
• TypeScript definition update
• Bundle size optimization
• Performance optimization
• Enhancement feature
• Refactoring
• Update dependency
• Code style optimization
• Test Case
• Branch merge
• Release
• Site / documentation update
• Demo update
• Workflow
• Other (about what?)

🔗 Related issue link

close #4490

🔗 Related PR link

🐞 Bugserver case id

💡 Background and solution

Add an opt-in hideWhenEmpty axis option for cartesian axes. The axis should hide when its bound series produce no collected axis data, while preserving existing behavior by default. The implementation will separate user-configured visibility from runtime empty-data visibility so the axis can auto-hide and reappear after updateData or updateSpec without requiring chart remake.

Language/Version: TypeScript 4.9.5
Primary Dependencies: @visactor/vchart, @visactor/vutils, @visactor/vrender-components
Storage: N/A
Testing: Jest
Target Platform: Web and cross-terminal chart runtimes supported by VChart
Project Type: Monorepo / Chart library
Performance Goals: No noticeable render or update regression; axis visibility recalculation should stay within existing axis domain update flow
Constraints: Cartesian axes only for this scope; must support runtime auto hide/show after data updates; must preserve existing behavior when option is unset
Scale/Scope: Public axis spec in packages/vchart and packages/vchart-types, axis runtime behavior in cartesian axis base flow, targeted unit regression coverage

📝 Changelog

Language	Changelog
🇺🇸 English	Add hideWhenEmpty for cartesian axes so empty bound-series axes can hide and reappear automatically after data updates.
🇨🇳 Chinese

☑️ Self-Check before Merge

⚠️ Please check all items below before requesting a reviewing. ⚠️

• Doc is updated/provided or not needed
• Demo is updated/provided or not needed
• TypeScript definition is updated/provided or not needed
• Changelog is provided or not needed

---

🚀 Summary

copilot:summary

🔍 Walkthrough

copilot:walkthrough

[xuefei1313]

本次 PR 实现了 Cartesian 轴的 hideWhenEmpty 配置项，允许坐标轴在关联系列数据为空时自动隐藏，并在数据更新后自动恢复。

主要改进点：

1. 状态分离：通过 _specVisible 和 _visible 的分离，优雅地处理了用户配置可见性与运行时可见性的关系。
2. 生命周期集成：在 BandAxisMixin 和 LinearAxisMixin 中集成了可见性刷新逻辑，确保数据驱动的准确性。
3. 渲染健壮性：在 BaseMark 中增加了延迟初始化逻辑，解决了 Product 在隐藏期间可能被移除的问题。
4. 性能考虑：在 AxisComponent 中优化了 collectData 的空值处理。

建议：

• 确认 @since 2.0.20 版本号是否与当前发布计划一致。
• 考虑到这是一个通用能力，未来可以评估是否扩展到极坐标轴。

总体代码质量很高，逻辑严密。

[xuefei1313]

对 PR #4521 (实现轴在数据为空时自动隐藏功能) 的深度 Review 总结：

变更点分析

1. Spec 扩展：在 ICartesianAxisCommonSpec 中增加了 hideWhenEmpty 配置项。
2. 可见性逻辑重构：将轴的可见性拆分为 _specVisible (用户配置) 和 _visible (实际运行状态)，支持根据数据收集情况动态切换。
3. 数据流集成：在 mixin (Band/Linear) 的 domain 更新阶段触发可见性检查，并强制触发 forceLayout 以重新分配图表空间。
4. Mark 延迟初始化：在 BaseMark 的 render 阶段增加了对 _product 的懒初始化，以支持从隐藏状态恢复时的图元创建。

发现的问题与改进建议

1. 性能优化：_refreshVisibilityByData 内部调用的 collectData(0) 在 domain 更新流程中会被重复执行。在大数据量或多系列场景下，建议缓存数据收集结果或复用 domain 计算时的数据统计信息。
2. 渲染安全性：BaseMark 在 render 时调用 _initProduct() 需确保其默认挂载逻辑（通常挂载至 RootGroup）符合业务 mark (如 Series 下的 Mark) 的层级要求。
3. 类型严谨性：在 _syncComponentVisibility 中对 getComponent() 返回值转换为 IGroup 并调用 setAttributes 时，建议增加更严谨的类型校验。
4. 测试覆盖：已提供的单元测试覆盖了初始渲染和数据更新场景，建议增加 updateSpec 切换 hideWhenEmpty 开关的测试用例。

总体实现方案符合 VChart 架构设计，逻辑清晰。建议关注上述性能及类型细节。详细评论已在代码行中列出。

[Copilot]

Pull request overview

Adds an opt-in cartesian axis option (hideWhenEmpty) so axes can automatically hide when their bound series produce no collected axis data, and reappear after updateData / updateSpec without recreating the chart.

Changes:

• Introduces hideWhenEmpty?: boolean on cartesian axis specs/types and documents the runtime visibility semantics.
• Implements runtime visibility evaluation in the axis base/cartesian pipeline and hooks re-evaluation into scale domain updates.
• Adds unit coverage for initial empty hiding, default behavior preservation, and re-show after data updates.

Reviewed changes

Copilot reviewed 21 out of 22 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
specs/010-hide-empty-axes/tasks.md	Feature task checklist for implementation and testing phases.
specs/010-hide-empty-axes/spec.md	Feature spec defining scenarios, requirements, and acceptance criteria.
specs/010-hide-empty-axes/research.md	Research notes clarifying “empty axis” definition and runtime toggling approach.
specs/010-hide-empty-axes/quickstart.md	Usage examples for hideWhenEmpty, mixed axes, and runtime updates.
specs/010-hide-empty-axes/plan.md	Implementation plan and repository structure mapping for the feature.
specs/010-hide-empty-axes/data-model.md	Data model for spec vs runtime visibility state and transitions.
specs/010-hide-empty-axes/contracts/interface.ts	Contract snippet defining hideWhenEmpty in a cartesian axis common spec interface.
specs/010-hide-empty-axes/checklists/requirements.md	Spec quality checklist (needs link fix per review comment).
skills/vchart-development-assistant/references/type-details/ICartesianAxisSpec-Type-Definition.md	Updates type reference docs to include hideWhenEmpty and runtime behavior notes.
packages/vchart/src/mark/base/base-mark.ts	Attempts to lazily recreate mark products when visibility toggles back to true.
packages/vchart/src/component/axis/polar/axis.ts	Switches visibility checks to _specVisible for consistency with new visibility split.
packages/vchart/src/component/axis/mixin/linear-axis-mixin.ts	Triggers visibility refresh after linear scale domain updates.
packages/vchart/src/component/axis/mixin/band-axis-mixin.ts	Triggers visibility refresh after band scale domain updates.
packages/vchart/src/component/axis/cartesian/interface/spec.ts	Adds hideWhenEmpty to cartesian axis public spec (with docs).
packages/vchart/src/component/axis/cartesian/axis.ts	Uses _specVisible in key flows and syncs mark visibility after layout updates.
packages/vchart/src/component/axis/base-axis.ts	Core implementation: splits spec/runtime visibility, evaluates empty-data visibility, syncs mark/group visibility.
packages/vchart/tests/unit/component/cartesian/axis/hide-when-empty.test.ts	Unit tests covering hide-on-empty, default behavior, and re-show on data update.
packages/vchart-types/types/component/axis/cartesian/interface/spec.d.ts	Publishes hideWhenEmpty in the cartesian axis type declarations.
common/changes/@visactor/vchart/010-hide-empty-axes_2026-03-20-06-29.json	Change record entry for the feature.
.vscode/launch.json	Adds/adjusts Jest debug launch configs.
.cursor/rules/specify-rules.mdc	Updates spec tooling rules to include this feature’s tech context.
.cursor/commands/speckit.prgenerate.md	Updates default PR body output path for the speckit command.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.