a2ui-project / a2ui-project/a2ui
Rename internal `SurfaceRegistry` events to resolve name clashes in package exports
- Ngôn ngữ chính
- TypeScript
- Star
- 16.4k
- Fork
- 1.3k
- Merge trung bình
- 2 ngày 13 giờ
- Pull request đã merge (30 ngày)
- 134
Mô tả
_↴ Ported from [flutter/genui#901](https://github.com/flutter/genui/issues/901) — originally opened by [yjbanov](https://github.com/yjbanov) on 2026-05-08._
_Original labels: P2, front-line-handled_
---
### Context
Currently in [genui.dart:L16-17](https://github.com/flutter/genui/blob/main/packages/genui/lib/genui.dart#L16-L17), we have to hide two classes in our exports due to name clashes:
```dart
export 'src/engine.dart' hide SurfaceAdded, SurfaceRemoved;
```
The classes are defined in two places:
1. **SurfaceUpdate events** (Public UI-level updates for facades/consumers):
- Location: [ui_models.dart:L402-438](https://github.com/flutter/genui/blob/main/packages/genui/lib/src/model/ui_models.dart#L402-L438)
- Classes: `SurfaceAdded`, `ComponentsUpdated`, and `SurfaceRemoved` (subclasses of `SurfaceUpdate`).
2. **RegistryEvent events** (Internal engine-level registry updates):
- Location: [surface_registry.dart:L12-36](https://github.com/flutter/genui/blob/main/packages/genui/lib/src/engine/surface_registry.dart#L12-L36)
- Classes: `SurfaceAdded`, `SurfaceRemoved`, and `SurfaceUpdated` (subclasses of `RegistryEvent`).
### Proposed Solution
To make the API clean, robust, and unambiguous without needing `hide` clauses, we should prefix the event classes in [surface_registry.dart](https://github.com/flutter/genui/blob/main/packages/genui/lib/src/engine/surface_registry.dart) to associate them explicitly with the registry.
#### 1. Rename classes
In [surface_registry.dart](https://github.com/flutter/genui/blob/main/packages/genui/lib/src/engine/surface_registry.dart):
* `RegistryEvent` $\rightarrow$ `SurfaceRegistryEvent`
* `SurfaceAdded` $\rightarrow$ `SurfaceRegistryAdded`
* `SurfaceRemoved` $\rightarrow$ `SurfaceRegistryRemoved`
* `SurfaceUpdated` $\rightarrow$ `SurfaceRegistryUpdated`
#### 2. Update surface controller
In [surface_controller.dart](https://github.com/flutter/genui/blob/main/packages/genui/lib/src/engine/surface_controller.dart)
Update the mapping logic in `surfaceUpdates` (around [L57-67](https://github.com/flutter/genui/blob/main/packages/genui/lib/src/engine/surface_controller.dart#L57-L67)) to match the new class names:
```dart
@override
Stream get surfaceUpdates => _registry.events.map(
(e) => switch (e) {
surface_reg.SurfaceRegistryAdded(:final surfaceId, :final definition) =>
SurfaceAdded(surfaceId, definition),
surface_reg.SurfaceRegistryUpdated(:final surfaceId, :final definition) =>
ComponentsUpdated(surfaceId, definition),
surface_reg.SurfaceRegistryRemoved(:final surfaceId) =>
SurfaceRemoved(surfaceId),
},
);
```
### Benefits
-
- **Cleaner Exports**: No need to hide classes in the main package entrypoint.
- **Unambiguous Code**: Developers importing internal libraries or both files directly won't run into naming collisions.
- **Stronger Semantics**: Clearly distinguishes between engine-internal registry state events (`SurfaceRegistryAdded`) and public UI-level state events (`SurfaceAdded`).
Hướng dẫn đóng góp
Hướng nghiên cứu
The issue is about renaming internal event classes in the Flutter/GenUI codebase. Start by examining the two files mentioned: `packages/genui/lib/src/engine/surface_registry.dart` and `packages/genui/lib/src/engine/surface_controller.dart`. Rename the classes in `surface_registry.dart` as specified, then update the mapping logic in `surface_controller.dart` to use the new names. Finally, verify the export in `packages/genui/lib/genui.dart` no longer needs the `hide` clause. Run any existing tests to ensure the changes don't break functionality.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- dart, typescript
- Lĩnh vực
- backend, tooling
- Loại issue
- Tái cấu trúc
- Độ khó
- 2/5
- Thời gian dự kiến
- 1-3 giờ
- Mức độ hoạt động
- Ít trao đổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 70/100