@downcity/ui 0.1.0 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +144 -6
- package/dist/index.cjs +3909 -38
- package/dist/index.d.cts +864 -1
- package/dist/index.d.ts +864 -1
- package/dist/index.js +3864 -36
- package/package.json +21 -15
- package/src/source.css +10 -0
package/README.md
CHANGED
|
@@ -1,15 +1,153 @@
|
|
|
1
1
|
# @downcity/ui
|
|
2
2
|
|
|
3
|
-
Downcity 的 React
|
|
3
|
+
`@downcity/ui` 是 Downcity 的 React UI 组件包。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
它提供基础 UI 原语、样式入口、以及 workboard 相关复合组件。
|
|
6
|
+
这个包只负责界面组件和类型，不负责 Agent 或 City 的运行时逻辑。
|
|
6
7
|
|
|
7
|
-
|
|
8
|
-
- 类型位于 `src/types/`
|
|
9
|
-
- 主题样式入口位于 `src/styles.css`
|
|
8
|
+
## 包定位
|
|
10
9
|
|
|
11
|
-
|
|
10
|
+
- 面向 React 宿主应用的组件库。
|
|
11
|
+
- 提供基础组件和少量复合业务组件。
|
|
12
|
+
- 提供样式入口，供外部项目按需引入。
|
|
13
|
+
|
|
14
|
+
## 与其他包的边界
|
|
15
|
+
|
|
16
|
+
- `@downcity/ui`
|
|
17
|
+
- 只负责 UI 组件、样式和组件类型。
|
|
18
|
+
- `@downcity/agent`
|
|
19
|
+
- 负责 Agent 运行时，不依赖这个包做执行。
|
|
20
|
+
- `@downcity/city`
|
|
21
|
+
- 可能消费这个包的组件，但平台逻辑不在这里。
|
|
22
|
+
|
|
23
|
+
## 根目录结构
|
|
24
|
+
|
|
25
|
+
```text
|
|
26
|
+
packages/ui
|
|
27
|
+
├── dist/ # 构建输出目录
|
|
28
|
+
├── src/ # 源码目录
|
|
29
|
+
├── package.json # 包信息、导出面、构建脚本
|
|
30
|
+
├── README.md # 包文档
|
|
31
|
+
└── tsconfig.json # TypeScript 配置
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## 源码结构树
|
|
35
|
+
|
|
36
|
+
```text
|
|
37
|
+
src
|
|
38
|
+
├── index.ts
|
|
39
|
+
├── source.css
|
|
40
|
+
├── styles.css
|
|
41
|
+
├── components/
|
|
42
|
+
├── lib/
|
|
43
|
+
└── types/
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## 目录职责
|
|
47
|
+
|
|
48
|
+
- `src/index.ts`
|
|
49
|
+
- 对外导出入口。
|
|
50
|
+
- 统一导出组件、工具函数和组件类型。
|
|
51
|
+
|
|
52
|
+
- `src/source.css`
|
|
53
|
+
- 原始样式资源入口。
|
|
54
|
+
- 适合需要直接消费源码样式的场景。
|
|
55
|
+
|
|
56
|
+
- `src/styles.css`
|
|
57
|
+
- 对外公开的样式入口。
|
|
58
|
+
- 宿主应用按需引入这个文件来启用组件样式。
|
|
59
|
+
|
|
60
|
+
- `src/components/`
|
|
61
|
+
- 组件实现目录。
|
|
62
|
+
- 基础原语组件：
|
|
63
|
+
- `button`、`card`、`input`、`label`、`checkbox`
|
|
64
|
+
- `dialog`、`dropdown-menu`、`popover`、`sheet`
|
|
65
|
+
- `tabs`、`toggle`、`toggle-group`
|
|
66
|
+
- `tooltip`、`separator`、`skeleton`、`sonner`
|
|
67
|
+
- 业务复合组件：
|
|
68
|
+
- `workboard.tsx`
|
|
69
|
+
- `workboard-stage.tsx`
|
|
70
|
+
- `workboard-game-*`
|
|
71
|
+
- `workboard-pixel-agent.tsx`
|
|
72
|
+
|
|
73
|
+
- `src/lib/`
|
|
74
|
+
- 组件内部共享工具。
|
|
75
|
+
- 目前主要是样式类名辅助函数。
|
|
76
|
+
|
|
77
|
+
- `src/types/`
|
|
78
|
+
- UI 组件和 workboard 的类型定义。
|
|
79
|
+
- `components.ts`：基础组件相关类型。
|
|
80
|
+
- `workboard*.ts`：workboard 及其地图/舞台/角色相关类型。
|
|
81
|
+
|
|
82
|
+
## 当前导出内容
|
|
83
|
+
|
|
84
|
+
`src/index.ts` 当前主要导出三类内容：
|
|
85
|
+
|
|
86
|
+
- 基础组件
|
|
87
|
+
- `Button`、`Badge`、`Card`、`Dialog`、`Input`、`Label`
|
|
88
|
+
- `DropdownMenu`、`Popover`、`Sheet`
|
|
89
|
+
- `Tabs`、`Toggle`、`ToggleGroup`
|
|
90
|
+
- `Tooltip`、`Separator`、`Skeleton`、`Toaster`
|
|
91
|
+
|
|
92
|
+
- 复合组件
|
|
93
|
+
- `Workboard`
|
|
94
|
+
- `buildWorkboardGameMapConfig`
|
|
95
|
+
|
|
96
|
+
- 类型与工具
|
|
97
|
+
- `cn`
|
|
98
|
+
- 按钮、卡片、toast 等基础类型
|
|
99
|
+
- workboard 相关展示与地图类型
|
|
100
|
+
|
|
101
|
+
## 关键调用关系
|
|
102
|
+
|
|
103
|
+
### 1. 组件导出
|
|
104
|
+
|
|
105
|
+
```text
|
|
106
|
+
src/components/*
|
|
107
|
+
-> src/index.ts
|
|
108
|
+
-> 外部 React 应用 import
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### 2. 样式使用
|
|
112
|
+
|
|
113
|
+
```text
|
|
114
|
+
宿主应用
|
|
115
|
+
-> 引入 @downcity/ui/styles.css
|
|
116
|
+
-> 使用组件
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### 3. workboard 复合组件
|
|
120
|
+
|
|
121
|
+
```text
|
|
122
|
+
workboard 类型
|
|
123
|
+
-> src/types/workboard*.ts
|
|
124
|
+
-> src/components/workboard*.tsx
|
|
125
|
+
-> src/index.ts 对外导出
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## 当前最重要的入口文件
|
|
129
|
+
|
|
130
|
+
- `src/index.ts`
|
|
131
|
+
- 组件和类型统一导出入口。
|
|
132
|
+
- `src/styles.css`
|
|
133
|
+
- 公开样式入口。
|
|
134
|
+
- `src/components/`
|
|
135
|
+
- 组件实现主体。
|
|
136
|
+
- `src/types/`
|
|
137
|
+
- 组件公共类型定义。
|
|
138
|
+
|
|
139
|
+
## 开发与构建
|
|
12
140
|
|
|
13
141
|
```bash
|
|
14
142
|
npm run build
|
|
15
143
|
```
|
|
144
|
+
|
|
145
|
+
## 维护约定
|
|
146
|
+
|
|
147
|
+
- 这个包只放 UI 组件、样式和类型。
|
|
148
|
+
- 不要把 Agent runtime、City CLI、控制面逻辑写进来。
|
|
149
|
+
- `dist/` 是构建产物，不直接手改。
|
|
150
|
+
- 新组件需要同时考虑：
|
|
151
|
+
- 是否应该从 `src/index.ts` 导出
|
|
152
|
+
- 是否需要在 `src/types/` 中补类型
|
|
153
|
+
- 是否需要宿主额外引入样式
|