Skip to content

Commit bdfd927

Browse files
CC11001100CC11001100
committed
fix: 修改GitHub徽标链接为正确的仓库地址 fuck-algorithm/leetcode-101-symmetric-tree
1 parent 396052a commit bdfd927

21 files changed

+3202
-303
lines changed

‎.kiro/specs/canvas-centric-ui/design.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# Design Document: Canvas-Centric UI
2+
3+
## Overview
4+
5+
本设计文档描述如何优化二叉树算法可视化界面，将信息呈现从"文字说明为主"转变为"画布可视化为主"。核心目标是减少界面上的文字，让用户通过视觉元素直观理解算法执行过程。
6+
7+
## Architecture
8+
9+
### 当前架构问题
10+
11+
```
12+
当前布局:
13+
┌─────────────────────────────────────────────────┐
14+
│ 文字说明区域 (占用空间) │
15+
├─────────────────────────────────────────────────┤
16+
│ │
17+
│ 画布区域 (被压缩) │
18+
│ │
19+
├─────────────────────────────────────────────────┤
20+
│ 步骤说明 + 递归可视化 (大量文字) │
21+
└─────────────────────────────────────────────────┘
22+
```
23+
24+
### 目标架构
25+
26+
```
27+
新布局:
28+
┌─────────────────────────────────────────────────┐
29+
│ │
30+
│ 画布区域 (最大化, ≥70% 高度) │
31+
│ ┌─────────┐ │
32+
│ │递归栈 │ [节点上的内联标注] │
33+
│ │(紧凑) │ │
34+
│ └─────────┘ │
35+
│ │
36+
├─────────────────────────────────────────────────┤
37+
│ [简化的底部控制栏 - 仅图标和进度] │
38+
└─────────────────────────────────────────────────┘
39+
```
40+
41+
### 修改范围
42+
43+
需要修改的核心文件：
44+
1. `TreeVisualizationNew.tsx` - 添加内联标注功能
45+
2. `RecursionCallVisualizer.tsx` - 重构为紧凑的画布内组件
46+
3. `TreeVisualExplanations.tsx` - 简化为图标+短文本
47+
4. `SymmetricTreeCheck.tsx` - 调整布局比例
48+
5. 新增 `InlineAnnotation.tsx` - 画布内标注组件
49+
6. 新增 `CompactRecursionStack.tsx` - 紧凑递归栈组件
50+
51+
## Components and Interfaces
52+
53+
### 1. 内联标注组件
54+
55+
```typescript
56+
interface InlineAnnotationProps {
57+
nodeId: string;
58+
text: string; // 最多15字符
59+
type: 'compare' | 'result' | 'info';
60+
position: 'top' | 'bottom' | 'left' | 'right';
61+
}
62+
63+
// 在节点附近显示简短标注
64+
function InlineAnnotation(props: InlineAnnotationProps): JSX.Element;
65+
```
66+
67+
### 2. 紧凑递归栈组件
68+
69+
```typescript
70+
interface CompactRecursionStackProps {
71+
frames: RecursionFrame[];
72+
activeFrameIndex: number;
73+
onFrameClick?: (index: number) => void;
74+
}
75+
76+
interface RecursionFrame {
77+
id: string;
78+
leftNodeId: string | null;
79+
rightNodeId: string | null;
80+
depth: number;
81+
status: 'active' | 'completed' | 'pending';
82+
result?: boolean;
83+
}
84+
85+
// 紧凑的递归栈显示，作为画布内的浮动面板
86+
function CompactRecursionStack(props: CompactRecursionStackProps): JSX.Element;
87+
```
88+
89+
### 3. 视觉比较指示器
90+
91+
```typescript
92+
interface ComparisonIndicatorProps {
93+
leftNodeId: string;
94+
rightNodeId: string;
95+
result?: boolean; // undefined = 进行中, true = 相等, false = 不等
96+
}
97+
98+
// 在两个节点之间显示比较状态的视觉指示
99+
function createComparisonIndicator(
100+
svg: d3.Selection<SVGGElement>,
101+
props: ComparisonIndicatorProps,
102+
positions: Map<string, NodePosition>
103+
): void;
104+
```
105+
106+
### 4. 结果图标
107+
108+
```typescript
109+
type ResultIconType = 'check' | 'cross' | 'comparing';
110+
111+
// 在节点上显示结果图标
112+
function addResultIcon(
113+
nodeGroup: d3.Selection<SVGGElement>,
114+
type: ResultIconType
115+
): void;
116+
```
117+
118+
## Data Models
119+
120+
### AnnotationData
121+
122+
```typescript
123+
interface AnnotationData {
124+
id: string;
125+
nodeId: string;
126+
text: string;
127+
type: 'compare' | 'result' | 'info';
128+
visible: boolean;
129+
}
130+
```
131+
132+
### LayoutConfig
133+
134+
```typescript
135+
interface LayoutConfig {
136+
canvasHeightPercent: number; // 默认 75
137+
recursionStackWidth: number; // 默认 180px
138+
showTextExplanations: boolean; // 默认 false
139+
useTooltips: boolean; // 默认 true
140+
}
141+
```
142+
143+
## Correctness Properties
144+
145+
*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
146+
147+
### Property 1: Annotation Brevity
148+
*For any* inline annotation displayed on the canvas, the text content SHALL NOT exceed 15 characters in length.
149+
**Validates: Requirements 1.1, 1.3**
150+
151+
### Property 2: Comparison Visual Feedback
152+
*For any* node comparison operation, the system SHALL display visual indicators (color coding, connection lines, or icons) on both compared nodes, and when a result is determined, SHALL show a checkmark (✓) or cross (✗) icon.
153+
**Validates: Requirements 1.2, 3.1, 3.2**
154+
155+
### Property 3: Recursion Frame Node Synchronization
156+
*For any* active recursion frame, the corresponding left and right nodes in the tree visualization SHALL be highlighted with matching visual indicators.
157+
**Validates: Requirements 2.2**
158+
159+
### Property 4: Canvas Size Preservation
160+
*For any* text explanation or tooltip displayed, the canvas area dimensions SHALL remain unchanged (no reduction in width or height).
161+
**Validates: Requirements 4.2**
162+
163+
## Error Handling
164+
165+
1. **标注溢出**: 当标注文本超过15字符时，自动截断并添加省略号
166+
2. **节点重叠**: 当多个标注可能重叠时，使用智能定位算法避免遮挡
167+
3. **递归栈过深**: 当递归深度超过可视区域时，使用滚动或折叠显示
168+
4. **空节点处理**: 空节点的标注使用特殊样式（虚线边框）
169+
170+
## Testing Strategy
171+
172+
### 单元测试
173+
174+
使用 Vitest 进行单元测试：
175+
176+
1. 测试 `truncateAnnotation` 函数正确截断超长文本
177+
2. 测试 `calculateAnnotationPosition` 函数返回正确的位置
178+
3. 测试 `CompactRecursionStack` 组件正确渲染帧列表
179+
180+
### 属性测试
181+
182+
使用 fast-check 进行属性测试：
183+
184+
1. **Property 1 测试**: 生成随机长度的标注文本，验证显示文本不超过15字符
185+
2. **Property 2 测试**: 生成随机节点比较操作，验证视觉指示器正确显示
186+
3. **Property 3 测试**: 生成随机递归帧序列，验证节点高亮与帧同步
187+
4. **Property 4 测试**: 生成随机tooltip显示操作，验证画布尺寸不变
188+
189+
每个属性测试配置运行至少 100 次迭代。
190+
191+
测试文件命名规范：`*.test.ts`
192+
193+
测试标注格式：
194+
```typescript
195+
// **Feature: canvas-centric-ui, Property 1: Annotation Brevity**
196+
```

‎.kiro/specs/canvas-centric-ui/requirements.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Requirements Document
2+
3+
## Introduction
4+
5+
本功能旨在优化二叉树算法可视化界面的信息呈现方式，减少界面上的文字说明，将更多信息直接整合到画布（可视化区域）中展示，使用户能够通过视觉元素而非阅读文字来理解算法执行过程。
6+
7+
## Glossary
8+
9+
- **Canvas（画布）**: 主要的可视化区域，用于展示二叉树结构和算法动画
10+
- **Inline Annotation（内联标注）**: 直接附着在可视化元素上的简短提示信息
11+
- **Visual Indicator（视觉指示器）**: 通过颜色、图标、动画等视觉方式传达信息的元素
12+
- **Step Explanation（步骤说明）**: 当前算法步骤的文字描述
13+
14+
## Requirements
15+
16+
### Requirement 1
17+
18+
**User Story:** As a user, I want step explanations to be shown as brief inline annotations on the canvas, so that I can understand the algorithm without reading long text blocks.
19+
20+
#### Acceptance Criteria
21+
22+
1. WHEN an algorithm step is executed THEN the system SHALL display a concise annotation (maximum 15 characters) near the relevant node on the canvas
23+
2. WHEN the step involves comparing two nodes THEN the system SHALL show visual comparison indicators directly on the nodes being compared
24+
3. WHEN the current step explanation area is displayed THEN the system SHALL reduce the text to a single short phrase or replace it with visual icons
25+
26+
### Requirement 2
27+
28+
**User Story:** As a user, I want the recursion call visualization to be integrated into the main canvas, so that I can see the call stack alongside the tree structure.
29+
30+
#### Acceptance Criteria
31+
32+
1. WHEN recursion calls are visualized THEN the system SHALL display them as a compact overlay or side panel within the canvas area
33+
2. WHEN a recursion frame is active THEN the system SHALL highlight the corresponding nodes in the tree with matching visual indicators
34+
3. WHEN the recursion stack changes THEN the system SHALL animate the transition smoothly within the canvas
35+
36+
### Requirement 3
37+
38+
**User Story:** As a user, I want visual cues instead of text to indicate algorithm states, so that the interface is cleaner and more intuitive.
39+
40+
#### Acceptance Criteria
41+
42+
1. WHEN nodes are being compared THEN the system SHALL use color coding and connection lines instead of text labels
43+
2. WHEN a comparison result is determined THEN the system SHALL show checkmark or cross icons on the nodes
44+
3. WHEN the algorithm progresses THEN the system SHALL use animated visual transitions to show state changes
45+
46+
### Requirement 4
47+
48+
**User Story:** As a user, I want the canvas area to be maximized, so that I can see the tree visualization more clearly.
49+
50+
#### Acceptance Criteria
51+
52+
1. WHEN the visualization page loads THEN the system SHALL allocate at least 70% of the viewport height to the canvas area
53+
2. WHEN text explanations are shown THEN the system SHALL display them as tooltips or small overlays that do not reduce canvas size
54+
3. WHEN the user hovers over a node THEN the system SHALL show detailed information in a tooltip rather than a permanent text area
55+
56+
</content>

‎.kiro/specs/canvas-centric-ui/tasks.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Implementation Plan
2+
3+
- [x] 1. 创建内联标注工具函数
4+
- [x] 1.1 创建 `src/utils/annotationUtils.ts` 文件
5+
- 实现 `truncateAnnotation(text: string, maxLength: number)` 函数
6+
- 实现 `calculateAnnotationPosition(nodePos, annotationType)` 函数
7+
- _Requirements: 1.1, 1.3_
8+
- [ ]* 1.2 编写标注简洁性的属性测试
9+
- **Property 1: Annotation Brevity**
10+
- **Validates: Requirements 1.1, 1.3**
11+
12+
- [x] 2. 实现画布内联标注功能
13+
- [x] 2.1 在 `TreeVisualizationNew.tsx` 中添加内联标注渲染
14+
- 创建 `addInlineAnnotation` 函数
15+
- 在节点附近显示简短文本（≤15字符）
16+
- 支持 compare/result/info 三种类型
17+
- _Requirements: 1.1, 1.2_
18+
- [x] 2.2 添加比较视觉指示器
19+
- 实现节点间的颜色编码连接线
20+
- 添加结果图标（✓/✗）到节点上
21+
- _Requirements: 3.1, 3.2_
22+
- [ ]* 2.3 编写比较视觉反馈的属性测试
23+
- **Property 2: Comparison Visual Feedback**
24+
- **Validates: Requirements 1.2, 3.1, 3.2**
25+
26+
- [ ] 3. Checkpoint - 确保所有测试通过
27+
- Ensure all tests pass, ask the user if questions arise.
28+
29+
- [-] 4. 创建紧凑递归栈组件
30+
- [x] 4.1 创建 `src/components/tree/CompactRecursionStack.tsx`
31+
- 实现紧凑的递归帧列表显示
32+
- 宽度固定为 180px
33+
- 支持帧点击交互
34+
- _Requirements: 2.1_
35+
- [x] 4.2 创建 `src/components/tree/CompactRecursionStack.css`
36+
- 实现浮动面板样式
37+
- 半透明背景，不遮挡主要内容
38+
- _Requirements: 2.1_
39+
- [ ] 4.3 实现递归帧与节点高亮同步
40+
- 当递归帧激活时，高亮对应的树节点
41+
- 使用匹配的视觉指示器（颜色/边框）
42+
- _Requirements: 2.2_
43+
- [ ]* 4.4 编写递归帧同步的属性测试
44+
- **Property 3: Recursion Frame Node Synchronization**
45+
- **Validates: Requirements 2.2**
46+
47+
- [-] 5. 调整主布局
48+
- [-] 5.1 修改 `SymmetricTreeCheck.tsx` 布局
49+
- 画布区域占据至少 70% 视口高度
50+
- 移除或隐藏大段文字说明区域
51+
- 将递归栈组件整合到画布内
52+
- _Requirements: 4.1, 4.2_
53+
- [ ] 5.2 简化 `TreeVisualExplanations.tsx`
54+
- 将步骤说明简化为图标+短文本
55+
- 移除冗长的文字描述
56+
- _Requirements: 1.3_
57+
- [ ]* 5.3 编写画布尺寸保持的属性测试
58+
- **Property 4: Canvas Size Preservation**
59+
- **Validates: Requirements 4.2**
60+
61+
- [ ] 6. 添加 Tooltip 功能
62+
- [ ] 6.1 实现节点悬停 Tooltip
63+
- 悬停时显示详细节点信息
64+
- Tooltip 不影响画布尺寸
65+
- _Requirements: 4.3_
66+
- [ ] 6.2 更新 CSS 样式
67+
- 添加 Tooltip 样式
68+
- 确保 Tooltip 层级正确
69+
- _Requirements: 4.3_
70+
71+
- [ ] 7. Final Checkpoint - 确保所有测试通过
72+
- Ensure all tests pass, ask the user if questions arise.

0 commit comments

Comments
 (0)