chore(vchart): sync changes before Auto Flow

Author: xuefei1313

.cursor/rules/specify-rules.mdc

@@ -0,0 +1,29 @@
+# VChart3 Development Guidelines
+
+Auto-generated from all feature plans. Last updated: 2026-01-13
+
+## Active Technologies
+
+- TypeScript 4.x (001-fix-subtitle-layout-bug)
+
+## Project Structure
+
+```text
+src/
+tests/
+```
+
+## Commands
+
+npm test && npm run lint
+
+## Code Style
+
+TypeScript 4.x: Follow standard conventions
+
+## Recent Changes
+
+- 001-fix-subtitle-layout-bug: Added TypeScript 4.x
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

packages/vchart/__tests__/unit/component/title/title.test.ts

@@ -0,0 +1,45 @@
+import { Title } from '../../../../src/component/title/title';
+import { ComponentTypeEnum } from '../../../../src/component/interface/type';
+import { getTheme } from '../../../util/context';
+
+const ctx: any = {
+  type: ComponentTypeEnum.title,
+  eventDispatcher: { addEventListener: () => {} },
+  mode: 'desktop-browser',
+  globalInstance: {
+    getContainer: () => ({}),
+    getTooltipHandlerByUser: (): any => undefined,
+    getStage: () => ({
+      find: (): any => ({
+        add: () => {}
+      })
+    })
+  },
+  getTheme: getTheme,
+  getCompiler: () => ({}),
+  getChart: () => ({
+    getSpec: () => ({})
+  }),
+  getRegionsInIndex: (): any[] => []
+};
+
+describe('Title Component Repro', () => {
+  it('should not throw error when only subtext is set', () => {
+    const spec = {
+      visible: true,
+      subtext: 'This is a subtitle'
+      // text is undefined
+    };
+
+    const title = new Title(spec as any, ctx);
+    title.created();
+    title.init({});
+
+    // Simulate layout
+    const layoutRect = { width: 500, height: 500, x: 0, y: 0 };
+
+    expect(() => {
+      title.getBoundsInRect(layoutRect);
+    }).not.toThrow();
+  });
+});

packages/vchart/src/component/title/interface/spec.ts

@@ -158,7 +158,7 @@ export type ITitleTextSpec =
       /**
        * 主标题文本配置
        */
-      text: string | number | string[] | number[];
+      text?: string | number | string[] | number[];
     }
   | {
       /**
@@ -168,7 +168,7 @@ export type ITitleTextSpec =
       /**
        * 主标题富文本内容
        */
-      text: IRichTextCharacter[];
+      text?: IRichTextCharacter[];
     };
 
 export type ISubTitleTextSpec =

packages/vchart/src/component/title/title.ts

@@ -116,21 +116,26 @@ export class Title<T extends ITitleSpec = ITitleSpec> extends BaseComponent<T> i
   }
 
   private _getTitleAttrs() {
-    // 当 width 小于 0 时，设置为 0，负数场景容易引起不可预知的问题
+    /**
+     * 生成标题组件的渲染属性，统一计算宽高与对齐参数，
+     * 并在仅副标题场景下避免主标题宽度影响副标题布局。
+     */
     if (this._spec.visible === false) {
       return { visible: false };
     }
     const layoutRect = this.getLayoutRect();
     const titleWidth = calcLayoutNumber(this._spec.width, layoutRect.width, null, layoutRect.width);
     const titleMaxWidth = calcLayoutNumber(this._spec.maxWidth, layoutRect.width, null, layoutRect.width);
     const maxWidth = Math.max(Math.min(titleWidth, titleMaxWidth, layoutRect.width), 0);
+    const hasText = isValid(this._spec.text) && this._spec.text !== '';
+    const hasSubtext = isValid(this._spec.subtext) && this._spec.subtext !== '';
 
     const attrs = {
       ...(pickWithout(this._spec, ['padding']) as any),
       textType: this._spec.textType ?? 'text',
-      text: this._spec.text ?? '',
+      text: hasText ? this._spec.text : undefined,
       subtextType: this._spec.subtextType ?? 'text',
-      subtext: this._spec.subtext ?? '',
+      subtext: hasSubtext ? this._spec.subtext : undefined,
       x: this._spec.x ?? 0,
       y: this._spec.y ?? 0,
       height: this._spec.height,
@@ -142,7 +147,6 @@ export class Title<T extends ITitleSpec = ITitleSpec> extends BaseComponent<T> i
       align: this._spec.align ?? 'left',
       verticalAlign: this._spec.verticalAlign ?? 'top',
       textStyle: {
-        width: maxWidth,
         maxLineWidth: maxWidth,
         ...this._spec.textStyle
       },
@@ -152,9 +156,25 @@ export class Title<T extends ITitleSpec = ITitleSpec> extends BaseComponent<T> i
       }
     } as TitleAttrs;
 
+    // 仅在对应文本存在时设置 width，避免空主标题影响副标题的对齐与宽度计算
+    if (hasText) {
+      (attrs.textStyle as any).width = maxWidth;
+    }
+    if (hasSubtext) {
+      (attrs.subtextStyle as any).width = maxWidth;
+    }
+
     if (isValid(this._spec.width)) {
-      attrs.textStyle.width = Math.max(titleWidth, layoutRect.width);
-      attrs.subtextStyle.width = attrs.textStyle.width;
+      const clampedWidth = Math.max(Math.min(titleWidth, layoutRect.width), 0);
+      if (hasText) {
+        (attrs.textStyle as any).width = clampedWidth;
+      } else {
+        // 主标题不存在时，不设置其 width
+        delete (attrs.textStyle as any).width;
+      }
+      if (hasSubtext) {
+        (attrs.subtextStyle as any).width = clampedWidth;
+      }
     }
     return attrs;
   }

specs/001-fix-subtitle-layout-bug/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: Fix Subtitle Layout Bug
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-01-13
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`

specs/001-fix-subtitle-layout-bug/contracts/interface.md

@@ -0,0 +1,12 @@
+# API Contract
+
+## ITitleSpec
+
+```typescript
+interface ITitleSpec {
+  text?: string;
+  subtext?: string;
+  // ... other properties
+}
+```
+No changes to the interface definition.

specs/001-fix-subtitle-layout-bug/data-model.md

@@ -0,0 +1,3 @@
+# Data Model
+
+No changes to the data model. The `TitleSpec` already supports optional `text` and `subtext`.

specs/001-fix-subtitle-layout-bug/plan.md

@@ -0,0 +1,71 @@
+# Implementation Plan: Fix Subtitle Layout Bug
+
+**Branch**: `001-fix-subtitle-layout-bug` | **Date**: 2026-01-13 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/001-fix-subtitle-layout-bug/spec.md`
+
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
+
+## Summary
+
+This plan addresses a layout bug in the Title component where rendering a chart with only a subtitle (and no main title) causes a layout error. The fix involves ensuring the `Title` component in `vchart` correctly handles the absence of the `text` property when interacting with `@visactor/vrender-components`.
+
+## Technical Context
+
+**Language/Version**: TypeScript 4.x
+**Primary Dependencies**: 
+- `@visactor/vrender-components`: Provides the underlying Title component.
+- `@visactor/vutils`: Utility functions.
+**Storage**: N/A
+**Testing**: Jest for unit testing.
+**Target Platform**: All VChart supported platforms (Web, Mini Program, etc.)
+**Project Type**: Visualization Library (Monorepo)
+**Performance Goals**: No regression in layout performance.
+**Constraints**: Must not break existing title rendering behavior.
+**Scale/Scope**: Component-level fix.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- [x] **Quality First**: Fix ensures robustness of the Title component.
+- [x] **User Experience-Driven**: Prevents crash/error for valid user configuration.
+- [x] **SDD**: Following the spec-driven workflow.
+- [x] **Unit Tests**: Will add regression test for this case.
+- [x] **Compatibility**: Non-breaking fix (PATCH).
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/001-fix-subtitle-layout-bug/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output (likely empty)
+├── quickstart.md        # Phase 1 output
+├── contracts/           # Phase 1 output (likely empty)
+└── tasks.md             # Phase 2 output
+```
+
+### Source Code (repository root)
+
+```text
+packages/vchart/
+├── src/
+│   └── component/
+│       └── title/
+│           └── title.ts    # Logic to be updated
+└── __tests__/
+    └── unit/
+        └── component/
+            └── title/
+                └── title.test.ts # Regression test
+```
+
+**Structure Decision**: Modify existing component file and add test case.
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+N/A

specs/001-fix-subtitle-layout-bug/quickstart.md

@@ -0,0 +1,17 @@
+# Quickstart
+
+## Usage
+
+You can now configure a title component with only a subtitle:
+
+```javascript
+const spec = {
+  type: 'bar',
+  data: [ ... ],
+  title: {
+    visible: true,
+    subtext: 'My Subtitle',
+    // text is optional and can be omitted
+  }
+};
+```

specs/001-fix-subtitle-layout-bug/research.md

@@ -0,0 +1,25 @@
+# Research: Fix Subtitle Layout Bug
+
+## Problem Analysis
+
+The user reported a layout error when only `subtext` is set in the Title component.
+Investigation of `packages/vchart/src/component/title/title.ts` reveals that `text` attribute is passed directly from spec:
+```typescript
+text: this._spec.text,
+```
+If `this._spec.text` is undefined, it is passed as undefined to `@visactor/vrender-components`.
+
+## Hypothesis
+
+The underlying `Title` component from `@visactor/vrender-components` likely expects `text` to be a valid string or handles `undefined` `text` incorrectly when `subtext` is present, leading to a layout calculation failure (e.g., trying to measure undefined text).
+
+## Proposed Solution
+
+Ensure `text` is always a string, defaulting to `''` if undefined.
+```typescript
+text: this._spec.text ?? '',
+```
+
+## Verification
+
+A regression test `repro.test.ts` was created to simulate the scenario.