@fulate/ui 2.0.11 → 3.0.2

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 CHANGED
@@ -1,126 +1,60 @@
1
- # @fulate/ui authored paths
1
+ # `@fulate/ui`
2
2
 
3
- UI 的运行阶段与扩展权限遵循 [Core 运行阶段合同](../../docs/specs/core-runtime-phases.md)。能力查询和
4
- typed effect resolver 只计算其返回值;命令 owner 负责提交。活动场景的 Transform baseline capture 和公开世界坐标
5
- 修改入口消费已准备的几何,paint/hit/Snap 借用已提交结果。结构通知仅维护当前已安装关系的依赖,
6
- 不能在通知中再次改写正在通知的 placement/children。
3
+ 提供 Rectangle、Circle、Triangle、Text、Image、Line、LineTree、Polygon、EditorVectorPath、
4
+ Group、ScrollView 和 Workspace。场景创建见 [Core 快速开始](../core/docs/guides/getting-started.md),
5
+ 通用属性见[属性指南](../core/docs/guides/elements-and-properties.md)。
7
6
 
8
- ## Bitmap surface
9
-
10
- `Bitmap`唯一拥有主线程当前frame,并向位图producer提供`renderPixelRatio = Viewport scale × DPR`。
11
- producer保持authored-local布局;需要超采样时,在自己的backend中基于该倍率增加质量倍率和资源预算。
12
- `paintBitmap()`仍把最终位图绘制到图元authored宽高,再由Layer应用Viewport与DPR。
13
-
14
- `Bitmap`也唯一记录renderer最近收到的authored宽高与像素倍率。producer创建renderer时调用
15
- `startFrameSurface(pixelRatio)`;需要同步尺寸时调用`claimFrameResize(pixelRatio)`,只有尺寸或倍率变化
16
- 且上一次请求的frame已经`presentBitmap()`时才返回`true`,producer据此发送一次自己的resize消息。
17
- 等待期间的变化在该frame绘制后按最新值发送,renderer同时最多处理一次待完成的尺寸请求。
18
-
19
- Worker 的 `onFrame` 和 emitter 的 `emit` 调用把 bitmap 所有权交给接收方;接收方采用后发生异常,
20
- 发送方不再关闭该资源。跨 Worker 的原生 `postMessage` 成功后才完成跨 realm 转移;发送失败时仍持有
21
- bitmap 的 host 负责释放并传播原异常。已经失效且尚未交付的 frame 由收到它的资源 owner 关闭。
22
-
23
- 位图、DPR和超采样质量都不改变逻辑坐标。鼠标与Worker返回的坐标保持authored-local,不经过
24
- `Bitmap`的scale换算。
25
-
26
- PNG 导出直接借用当前 bitmap,通过同一 `paintBitmap()` 绘制。导出不向 Worker 请求新帧,
27
- 也不接管 bitmap 的释放;尺寸与清晰度语义见 [PNG 导出](../core/docs/guides/png-export.md)。
28
-
29
- ## Image 尺寸与加载
30
-
31
- `Image` 未提供尺寸时直接读取当前源的 `naturalWidth`/`naturalHeight`;显式
32
- `width`/`height` 优先且保留 `0`。源的 intrinsic 尺寸变化进入同一 geometry/layout 提交,位图分辨率
33
- 升级只重绘,不改变逻辑尺寸。
34
-
35
- `src` 与构造时提供的 `image` 使用同一加载路径;切换源、detach、重新进入和 unmount 都使旧处理
36
- 结果失效。晚到的旧 bitmap 会被释放,不覆盖当前源。
37
- `Image` 的 PNG 导出复用当前已显示的 bitmap、半径裁剪与样式,不另行加载、解码或升级分辨率。
38
- 源加载尚未完成时,导出与普通绘制一样没有该图片内容。
39
- 当前 load/decode 直接以其 Promise identity 表示;位图尺寸从 `Bitmap` 所持有的资源读取,源的 intrinsic
40
- 尺寸单独保存,避免下采样结果改变布局尺寸。
41
-
42
- ## ScrollView 内容范围
43
-
44
- `contentWidth/contentHeight` 构造值提供首次布局前的范围;首次布局后由直接子元素的 extent 替换。
45
- 子元素或后代的实际变化使范围失效;纯滚动复用该范围,继续更新必要的 child world matrix、clip 和
46
- scrollbar 投影。内容缩小所需的 clamp 由 ScrollView 在下一次 Root RAF 的 R0 读取当前范围执行,停用时
47
- 释放待办。直接写入越界 offset 也在 R1 登记下一 R0 的归位;归位前恢复范围会取消该待办。
48
-
49
- ScrollView 的内容范围和 max-size 由自身 R1 layout owner 计算;Ripple 的 owner 观察当前宿主的
50
- transform commit,仅在尺寸真实改变时安装自己的 frame。换父或停用会释放旧宿主订阅。
51
- 离线 ScrollView/Ripple 在既有 Transform baseline capture 入口内稳定相关脏链,不请求 RAF。
52
-
53
- ## Workspace fit
7
+ ## 路径图形
54
8
 
55
- `WorkspaceOption.fit`控制首次进入Root时的自动聚焦,`WorkspaceOption.fitOnResize`控制Root尺寸
56
- 变化后的自动重新聚焦;两者默认都是`true`,也可以独立关闭。首次fit在Workspace的初始几何提交后、
57
- 首个Canvas paint前直接安装最终Viewport,不播放动画。同一帧内连续发生的Root尺寸变化只按最终尺寸
58
- 执行一次无动画fit。两条路径都读取当前Root提供的实时可见区insets。
9
+ 仅需绘制时使用 `@fulate/core` 的 `VectorPath`;需要编辑能力时使用 `@fulate/ui` 的
10
+ `EditorVectorPath`。
59
11
 
60
- 编辑器按钮、导入完成等外部流程直接调用同一公开函数,不复制Workspace bounds或Viewport focus规则:
12
+ | 元素 | 创建输入 | 读取路径 |
13
+ | --- | --- | --- |
14
+ | `Line` | `points: PointView[]` 或 `geometry` | `line.geometry` / `line.anchors` |
15
+ | `Polygon` | `path: PointView[]` | `polygon.path.subpaths[0]`,闭合直线 |
16
+ | `EditorVectorPath` | `path: VectorPathCommand[]` 或 `VectorPathGeometry` | `vector.path.subpaths`,直线或三次曲线 |
61
17
 
62
18
  ```ts
63
- import { fitWorkspace } from "@fulate/ui";
64
-
65
- await fitWorkspace(workspace, { padding: 0 });
66
- ```
67
-
68
- 显式调用不受`WorkspaceOption.fit`或`WorkspaceOption.fitOnResize`限制;传入的focus options会按原引用
69
- 直接交给Workspace所属Root的Viewport。用户触发的fit需要动画时由调用者显式传入`animate`。
70
-
71
- 通用场景路径从 `@fulate/core` 导入 VectorPath;编辑器使用 `@fulate/ui` 的 EditorVectorPath。
72
- Polygon 继承 EditorVectorPath。VectorPathCommand、VectorPathGeometry 和基础 VectorPathOption 从 Core 导入。
73
-
74
- `Line`、`Polygon` 和 `EditorVectorPath` 都只有一份 live canonical authored owner:
75
-
76
- | 元素 | 普通创建输入 | live getter | topology |
77
- | --- | --- | --- | --- |
78
- | `Line` | `points: PointView[]` 或 `geometry` | `line.geometry` / `line.anchors` | manual subpath 或 orthogonal 端点、手调点与 margin |
79
- | `Polygon` | `path: PointView[]` | `polygon.path.subpaths[0]` | 一个 closed、line-only subpath |
80
- | `EditorVectorPath` | `path: VectorPathCommand[]` | `vector.path.subpaths` | ordered open/closed line/cubic subpaths |
19
+ import { Line } from "@fulate/ui";
81
20
 
82
- 普通输入只在入口解释一次。每个 canonical anchor record 直接保存 `anchorId`、原 `point` 引用,
83
- 并在存在 outgoing segment 时共置 `segmentId` 与 `line | cubic` 数据;普通 line segment 没有
84
- 独立 wrapper。Geometry resolver 让 `vertices` 和 `segmentShapes` 直接复用这些 records。
85
-
86
- ```ts
87
21
  const line = new Line({
88
22
  points: [{ x: 0, y: 0 }, { x: 80, y: 30 }]
89
23
  });
90
-
91
- const anchorId = line.headAnchor.anchorId;
92
- line.setLocalPoint(anchorId, { x: 10, y: 5 });
24
+ line.setLocalPoint(line.headAnchor.anchorId, { x: 10, y: 5 });
93
25
  ```
94
26
 
95
- 坐标更新、transform、History restore 保留既有 local IDs;insert 只创建新增 IDs,delete 保留
96
- 未受影响 IDs。传入 canonical whole value 时按引用 identity 判断:同一引用是 noop,不同引用
97
- 即使内容相同也会被采用。point/control 等结构化值不做 caller-isolation clone;需要隔离时由
98
- 调用者在传入前复制。调用者在所有权移交后原地修改同一对象不会自动产生 commit、dirty、
99
- History 或 frame。
27
+ 坐标修改保留点和线段的 ID;插入只创建新增 ID。传入路径对象后不应原地修改,
28
+ 应使用对应编辑方法或传入新对象。
100
29
 
101
- 正交线使用同一个 Line:
30
+ 正交线仍使用 `Line`:
102
31
 
103
32
  ```ts
33
+ import { Line, createOrthogonalLineGeometry } from "@fulate/ui";
34
+
104
35
  const line = new Line({
105
- geometry: createOrthogonalLineGeometry([{x: 0, y: 0}, {x: 180, y: 100}]),
106
- text: '审核通过', // 可选:固定在当前路线总长度一半的位置
36
+ geometry: createOrthogonalLineGeometry([{ x: 0, y: 0 }, { x: 180, y: 100 }]),
37
+ text: "审核通过",
107
38
  tailDecoration: "arrow"
108
39
  });
109
40
  ```
110
41
 
111
- 单击选中正交线即显示端点操作区与折段菱形;只可拖动这些操作点调整端点或沿垂直方向移动折段。
112
- 点编辑关闭场景对齐;折段内部归并遵守 [Point 规则](../../docs/specs/point-editing.md)。拖动绑定端点会断开该端,
113
- 并像普通 Line 一样显示可连接点,靠近后松手可重连。
114
- 首尾都无绑定时,可从非操作点的线体或标签拖动整条线;有任一端绑定时不能拖走整线。始终保持正交模式。
115
- 双击正交线或标签输入文字,按 Esc 或点击外部结束编辑;一次编辑可撤销。文字始终水平,
116
- 跟随路线长度中点,空字符串隐藏标签。通过 `line.setOptions({ text: '新文字' })` 也可更新。
117
- 手调点与文字随文件和剪贴板保存,移动节点时保留。完整路由与变换规则见
118
- [Path/Line 规范](../../docs/specs/path-line-core.md#51-standalone-line)。
42
+ 单击正交线显示端点和折段控制点。拖动绑定端点会断开该端,靠近可连接点后松手可重连;
43
+ 两端均未绑定时可从线体或标签拖动整线。正交点编辑不参与场景轴对齐。
44
+
45
+ 双击正交线或标签编辑文字,Esc 或点击外部结束;也可调用 `line.setOptions({ text: "新文字" })`。
46
+ 文字水平显示在路线长度中点,空字符串隐藏标签,手调点与文字均可保存。
47
+
48
+ ## 端口连接
49
+
50
+ 为 Root 开启 `enablePorts: true`,并为目标元素设置 `ports: true` 或自定义端口数组。
51
+ 默认值、方向和容量配置见 [Ports](../core/docs/guides/elements-and-properties.md#ports)。
119
52
 
120
- ## Connection、Port 与 Line endpoints
53
+ 程序化连接使用 `connectEndpoint(root, source, target)`,断开使用
54
+ `disconnectEndpoint(root, source)`。Line 首端是 output,尾端是 input;
55
+ 方向不兼容、容量已满或目标不存在时不建立连接。
121
56
 
122
- Path authored `anchorId` 与 target owner-local `portId` 是两个概念。Line 首尾 endpoint 与
123
- LineTree root/leaf endpoint只保存source-owned relation:
57
+ 端点关系引用目标元素与端口:
124
58
 
125
59
  ```ts
126
60
  interface EndpointRelation {
@@ -132,108 +66,55 @@ interface EndpointRelation {
132
66
  }
133
67
  ```
134
68
 
135
- relation不保存坐标。`Line.geometry`与`LineTree.topology.points`保存authored fallback;paint、hit、bounds、
136
- query和controls从当前target Port解析effective geometry。target变化只通过Root唯一
137
- `EndpointRelationIndex`精确dirty dependents,不反写source authored值或History。
138
-
139
- Line的`relations` patch省略时两端保持;对象中省略一端也表示保持,own `undefined`清除该端,
140
- `EndpointRelation`建立或替换。程序化连接使用同步`connectEndpoint(root, source, target)`与
141
- `disconnectEndpoint(root, source)`;普通noop返回`void`且不创建结果状态机。
142
- connect 只消费 Port 元数据;disconnect 省略 `localPosition`、Port 删除或 world-coordinate Point
143
- writer 需要操作前已准备的几何。调用者在依赖变化后先 `await root.nextTick()`;authored-local writer
144
- 直接使用局部数据。`computePosition()` 同样消费已准备的几何,其 Promise 来自 Floating UI 计算。
145
- Floating UI 的尺寸、偏移和 `middlewareData` 使用 world 空间;返回的 `x/y` 已转换为 floating 元素
146
- 父空间的 `left/top`,可直接传给 `setOptions()`,包括缩放、旋转和滚动父容器。
147
- 通用读取与等待合同见 [Core 阶段合同](../../docs/specs/core-runtime-phases.md#d3-读取与状态推进)。
148
-
149
- Line首端/root endpoint的连接role是`output`,尾端/leaf是`input`;装饰不决定连接role。同步
150
- `connectEndpoint()`从live source与target Port读取role、`direction`和对应capacity;方向不兼容、容量
151
- 已满或target Port不存在时保持noop。Tools picker复用同一规则,受阻Port不能降级成自由落点。
152
-
153
- `Element.ports`是`false | true | readonly ConnectionPortDefinition[]`的唯一authored owner。构造时
154
- 省略等同`false`;`false`没有Port,`true`使用元素类型的默认schema,数组作为custom whole-value按
155
- 原引用采用,`[]`表示当前custom配置为空。patch省略`ports`保持当前值;不支持`null`。数组同引用
156
- noop,不clone、freeze、normalize或deep-equal。
157
- `Root.enablePorts`默认`false`并可通过`setEnablePorts()`切换;关闭时不绘制、发现或Snap Port,也不
158
- 允许`connectEndpoint()`新建relation。按已知Port ID解析和已有relation的target observer始终有效,
159
- 因此Line/LineTree继续跟随目标;显式Port删除/替换仍物化当前fallback并detach。完整开关边界见
160
- [`path-line-core.md`](../../docs/specs/path-line-core.md#10-transformpointbinding-与-routing-边界)。
161
-
162
- JSON、clipboard和History的独立输出复制所需数据;restore直接安装canonical geometry/path/topology、IDs和
163
- source-owned relations。source与target一起复制时只重映射element key;只复制source时使用当前
164
- resolved source-local fallback并删除外部relation;完整owner的subpath/anchor/segment/Port IDs保留。
69
+ `Line.relations` 补丁省略一端表示保持该端,显式 `undefined` 清除该端,关系对象建立或替换连接。
70
+ 绑定后的端点随目标移动。关闭 Root 的 Ports 不会断开已有连接;删除端口会解除对应关系。
71
+
72
+ 断开时未提供 `localPosition`,或操作需要当前世界坐标时,先 `await root.nextTick()`。
73
+ 文件与剪贴板处理见[Tools IO 指南](../tools/README.md#原生场景与文件-io);完整连接规则见
74
+ [Path/Line 规范](../../docs/specs/path-line-core.md)。
165
75
 
166
76
  ## LineTree
167
77
 
168
- `LineTree`是一整个场景元素,不包含隐藏的`Line` child。`topology.points`唯一拥有坐标和可选
169
- EndpointRelation,`topology.branches`只通过稳定`SubpathId/AnchorId/
170
- SegmentId`引用这些points;非root branch用`parentSubpathId`表达同一owner内的唯一父分支。
171
- 当前branch只有straight/polyline,不保存kind或Orthogonal/cubic预留variant。
78
+ `LineTree` 把多个分支作为一个元素选择、移动、复制和删除。新增分支从父分支尾点出发,
79
+ 同一尾点可创建多个同级分支:
172
80
 
173
81
  ```ts
174
- const topology = createLineTreeTopology([
175
- { x: 0, y: 0 },
176
- { x: 120, y: 0 }
177
- ]);
82
+ import { LineTree, createLineTreeTopology, addLineTreeBranchAtTail } from "@fulate/ui";
83
+
84
+ const topology = createLineTreeTopology([{ x: 0, y: 0 }, { x: 120, y: 0 }]);
178
85
  const tree = new LineTree({ topology });
179
- const root = topology.branches[0];
180
86
 
181
87
  tree.replaceTopology(addLineTreeBranchAtTail(
182
88
  tree.topology,
183
- root.subpathId,
89
+ topology.branches[0].subpathId,
184
90
  [{ x: 120, y: 80 }]
185
91
  ).topology);
186
92
  ```
187
93
 
188
- 普通选择、hover、copy、delete、Transform、RBush和History owner始终只有`tree`一个。双击精确
189
- branch后Point projection只请求该subpath;删除父branch由`removeLineTreeBranch()`在一个owner-local
190
- delta中删除全部descendants和孤儿points。外部topology输入按原引用采用;domain edit只复制实际
191
- changed records及必要外层数组。新增branch只复用parent branch的尾点;Editor交互允许任意branch
192
- tail成为source,同一junction tail可重复产生sibling branches,但junction不绘制tail三角形。树干segment和中间anchor都不是branch source,也
193
- 不会因扩展操作被插入junction。
194
-
195
- Line与LineTree的stroke和端点decoration在world空间按固定宽度绘制;自身visual bounds与render
196
- coverage覆盖同一完整绘制范围,反向近零Transform也不会缩掉dirty coverage。固定world paint padding
197
- 不进入Line/LineTree的selection/resize frame或ancestor content bounds;单选、多选及Group均使用
198
- effective path geometry计量线的尺寸。hover与active branch highlight复用同一polyline paint,箭头和线段保持同色。
199
-
200
- Rectangle、Triangle及其他Shape省略`backgroundColor`/`borderColor`时读取当前Root的
201
- `skin.shapeFill`/`skin.shapeStroke`;Line和LineTree branch省略`strokeColor`时读取
202
- `skin.lineStroke`。显式值始终优先,Shape的显式`null`关闭绘制,显式字段清回`undefined`后立即重新
203
- 继承Skin。Skin改变只触发现有Root/Layer重绘,不改写element、branch topology或History。
204
-
205
- LineTree整体resize把全部拓扑点按完整仿射写回 authored topology。随后Point编辑和L分支扩展在
206
- 同一owner change内保留当前world pose;包括反向scale在内,未编辑points保持world位置不变。
207
- 分支选择使用 Core 的 world 距离查询;共享 junction 在各分支 view 中借用同一个 world point。
208
- 仅修改分支颜色或装饰不重建路径 geometry;线宽更新 visual bounds,真实 points/vertices/graph 变化
209
- 才失效对应 geometry。
210
-
211
- ## Text 尺寸与显示
94
+ 双击分支进入该分支的点编辑;删除父分支会删除其全部后代分支。
95
+ 交互操作见 [Tools 指南](../tools/README.md#点编辑与画线),数据模型见
96
+ [Path/Line 规范](../../docs/specs/path-line-core.md)。
212
97
 
213
- `Text` 未提供 `width`/`height` 时使用当前文字的 intrinsic 尺寸;提供尺寸后,该尺寸成为布局盒。
214
- `wordWrap` 只控制是否按布局宽度换行,`ellipsis` 只控制是否把被截断内容绘制为 `…`,`overflow`
215
- 只控制是否裁剪绘制内容,三个选项可以独立组合。Text 默认使用 intrinsic 尺寸、`wordWrap=false`、
216
- `overflow="visible"` 且不启用省略号;组件若需要 Web 控件式的填满、裁剪或省略,应显式传入对应属性。
98
+ Line 与 LineTree 的线宽和端点装饰按世界坐标绘制,元素自身缩放不缩放线宽。
99
+ 选择框、缩放尺寸和 Group 内容范围使用路径几何,不计描边和箭头外扩。
100
+ 省略填充、描边或线色时继承 [Root Skin](../core/docs/guides/layers-and-rendering.md#skin)。
217
101
 
218
- Editor 的 Text selection/resize frame 使用布局盒,不使用可见溢出 glyph 的 visual bounds。因此
219
- `wordWrap={false}`、`overflow="visible"` 的文本被缩放后,取消选择再重新选择仍保持上一次 authored
220
- 尺寸,下一次缩放也从该尺寸继续。
102
+ ## Text 尺寸与显示
221
103
 
222
- visual bounds 使用同一 TextLayoutSnapshot 内按行测量并复用的真实 glyph ink,包含斜体外伸;
223
- 该范围不改变布局盒或 selection/resize frame。
104
+ 未提供 `width`/`height` 时,`Text` 使用文字自然尺寸;提供后作为布局盒。
224
105
 
225
- caret、selection 和编辑首尾只更新 paint 与 R2 textarea 投影;文字输入仍通过所属 writer 进入布局。
226
- placeholder 的宽度由 Text 一次测量供 bounds/paint 共用,并在 placeholder、字体或样式输入变化时失效。
106
+ | 选项 | 作用 | 默认值 |
107
+ | --- | --- | --- |
108
+ | `wordWrap` | 按布局宽度换行 | `false` |
109
+ | `ellipsis` | 将截断内容显示为省略号 | `false` |
110
+ | `overflow` | 控制内容裁剪 | `"visible"` |
227
111
 
228
- 尺寸、paint、geometry、caret 与 textarea 共享唯一纯缓存入口 `textLayout`;纯移动复用已有 layout 和
229
- 本地 geometry。Span 使用 Yoga 的最终 frame 作为文字约束。文字自然尺寸与 Yoga frame 都不写入 authored
230
- 属性或 History。字体加载与影响文字排版或视觉边界的 Skin 字段变化先捕获旧像素范围,再失效相应缓存
231
- 与祖先边界;颜色变化复用已有布局。Skin 的全层重绘同时覆盖读取 live Skin 的自定义 Shape。
112
+ 三者可以独立组合。编辑器选择和缩放使用布局盒,即使文字绘制超出该盒,也不改变选择尺寸。
113
+ `Span` 使用 Yoga 计算后的尺寸约束文字。
232
114
 
233
115
  ### 原生 Canvas 文本 run
234
116
 
235
- 组合型原生 Shape 可以直接传入 live resolved Skin,按 `Text` 相同的字体、行高、Canvas baseline
236
- 和字符间距语义测量一段文本,不需要复制或整理 style:
117
+ 自定义 Shape 可使用与 Text 相同的字体和基线规则测量文本:
237
118
 
238
119
  ```ts
239
120
  import { measureTextRun } from "@fulate/ui";
@@ -241,77 +122,78 @@ import { measureTextRun } from "@fulate/ui";
241
122
  const metrics = measureTextRun(ctx, text, root.skin.text, 14, 500);
242
123
  ```
243
124
 
244
- 每次调用只执行一次 `ctx.measureText()`,返回 `font`、`width`、`lineHeight`、`drawY`、
245
- `alphabeticBaseline`、`textBaseline` 和 `letterSpacing`。`drawY` 根据原生 Canvas 的
246
- `fontBoundingBoxAscent`/`fontBoundingBoxDescent` 把字体行框放到行框中心;`alphabeticBaseline`
247
- 是同一行框内的规范 alphabetic baseline,因此不同字号的 run 可以直接对齐。空文本的 `width`
248
- 为 `0`,但仍测量一个空格以取得稳定字体度量。函数会把本次测量所需的文字状态写入 `ctx`,不会
249
- 调用 `save()` 或 `restore()`;Canvas 生命周期以及业务特有的文字顺序、对齐和绘制仍由 Shape
250
- 自己拥有。
125
+ 返回 `font`、`width`、`lineHeight`、`drawY`、`alphabeticBaseline`、
126
+ `textBaseline` 和 `letterSpacing`。不同字号可按 `alphabeticBaseline` 对齐。
127
+ 函数会修改 ctx 的文字状态,调用方负责 `save()`/`restore()` 和实际绘制。
251
128
 
252
129
  ### 组合型多行文本
253
130
 
254
- 需要在一个非 `Text` Element 中放置可换行文字时,使用公开的 `TextBlock` 组合原语。它与 `Text`
255
- 共用同一份 hard-break、grapheme、`wordWrap`、`maxLines` 和 `ellipsis` 排版实现:
131
+ 在非 Text 元素中绘制可换行文字时,使用 `TextBlock`:
256
132
 
257
133
  ```ts
258
- import {
259
- TextBlock,
260
- getTextBlockVisualBounds,
261
- paintTextBlock,
262
- resolveTextStyle
263
- } from "@fulate/ui";
134
+ import { TextBlock, getTextBlockVisualBounds, paintTextBlock, resolveTextStyle } from "@fulate/ui";
264
135
 
265
136
  const style = resolveTextStyle(
266
- {
267
- fontSize: 14,
268
- fontWeight: 500,
269
- textAlign: "left",
270
- textBaseline: "top",
271
- verticalAlign: "top",
272
- wordWrap: true
273
- },
137
+ { fontSize: 14, fontWeight: 500, textAlign: "left", textBaseline: "top", verticalAlign: "top", wordWrap: true },
274
138
  root.skin.text
275
139
  );
276
140
  const block = new TextBlock();
277
141
  const snapshot = block.sync({
278
- text,
279
- style,
280
- width: 120,
281
- height: 80,
282
- overflow: "visible",
283
- wordWrap: true,
284
- ellipsis: false
142
+ text, style, width: 120, height: 80,
143
+ overflow: "visible", wordWrap: true, ellipsis: false
285
144
  });
286
145
 
287
146
  paintTextBlock(ctx, snapshot, style, 120, 80);
288
147
  const visualBounds = getTextBlockVisualBounds(snapshot, style, 120, 80);
289
148
  ```
290
149
 
291
- `measure()` 只返回紧凑的聚合 metrics;最终宽高确定后调用一次 `sync()`,并把同一个 snapshot
292
- 同时交给 `paintTextBlock()` 和 `getTextBlockVisualBounds()`。`paintTextBlock()` 不会替调用者
293
- `save()`/`restore()`、安装 clip 或决定坐标变换;组合 owner 自己负责 Canvas 生命周期、裁剪和把
294
- 视觉 bounds 接入自己的 transform/dirty-rect 计算。`overflow: "visible"` 不会自动把文字裁掉,
295
- 也不会自动改变 owner 的 authored 宽高;使用 `overflow: "hidden"` 时,真正的 Canvas clip 仍由
296
- 组合 owner 安装。
150
+ 预先测量使用 `measure()`;最终尺寸确定后调用 `sync()`,将结果用于绘制和视觉边界。
151
+ 调用方负责 Canvas 变换、裁剪和状态恢复,`overflow: "hidden"` 也需要自行安装 clip。
152
+
153
+ 输入或 Skin 变化时调用 `invalidate()`。需要响应字体加载时订阅
154
+ `subscribeTextMeasurementChanges()`,销毁时调用返回的取消函数。
155
+
156
+ ## Image 尺寸与加载
157
+
158
+ `Image` 未指定尺寸时使用源的 `naturalWidth`/`naturalHeight`;显式宽高优先,`0` 也有效。
159
+ 更换源后,旧加载结果不会覆盖新图片。
160
+
161
+ PNG 导出使用当前显示的位图与样式,不等待加载或解码;图片未加载完成时,导出中没有该图片内容。
162
+ 详见 [PNG 导出](../core/docs/guides/png-export.md)。
163
+
164
+ ## ScrollView 内容范围
165
+
166
+ `contentWidth`/`contentHeight` 构造值提供首次布局前的范围;首次布局后由子元素范围决定,
167
+ 内容变化会更新范围。内容缩小或写入越界 offset 后,在后续帧将滚动位置限制到有效范围。
168
+
169
+ ## Workspace fit
170
+
171
+ `fit` 控制首次进入 Root 时自动聚焦,`fitOnResize` 控制 Root 尺寸变化后重新聚焦,两者默认
172
+ `true`,可分别关闭。自动聚焦不播放动画,并会避开标尺等占用的可见区域。
297
173
 
298
- `TextBlock` 不属于任何 `Element`、`Root`、History 或 frame runtime。组合 owner 负责保存 block、
299
- 在输入或 Skin 变化时调用 `invalidate()`,并在需要响应浏览器字体加载完成时订阅
300
- `subscribeTextMeasurementChanges()`;返回的函数用于解除订阅。不要绕过 `@fulate/ui` 根入口导入
301
- `TextBlock` 的内部实现,也不要为同一段文字另建一套换行或测量器。
174
+ 手动聚焦:
175
+
176
+ ```ts
177
+ import { fitWorkspace } from "@fulate/ui";
178
+
179
+ await fitWorkspace(workspace, { padding: 0 });
180
+ ```
181
+
182
+ 手动调用不受上述两个开关限制;需要动画时显式传入 `animate`。
183
+
184
+ ## 浮层定位
185
+
186
+ `computePosition()` 基于当前几何计算位置,调用前先 `await root.nextTick()`。
187
+ 返回的 `x/y` 已转换为浮层父空间的 `left/top`,可直接传给 `setOptions()`;
188
+ Floating UI 的尺寸、偏移与 `middlewareData` 使用世界坐标。
302
189
 
303
190
  ## Editor capabilities
304
191
 
305
- UI 元素通过对象 identity token 直接提供 Selection、Transform、Snap、Point 与 Content capability;
306
- 没有 registry、字符串 key、implicit default、layout writer 或 Tools duck fields。
307
- Selection 的闭集策略使用公开枚举:
192
+ 自定义元素通过 Selection、Transform、Snap、Point、Content capability 接入编辑器。
193
+ 例如选择策略使用公开枚举:
308
194
 
309
195
  ```ts
310
- import {
311
- SelectionBehaviorMode,
312
- SelectionDiveMode,
313
- SelectionSnapMode
314
- } from "@fulate/ui";
196
+ import { SelectionBehaviorMode, SelectionDiveMode, SelectionSnapMode } from "@fulate/ui";
315
197
 
316
198
  const behavior = {
317
199
  mode: SelectionBehaviorMode.OwnerDirect,
@@ -320,16 +202,18 @@ const behavior = {
320
202
  };
321
203
  ```
322
204
 
323
- `OwnerDirect` 用于不绘制单选 frame、首次位移可直接提升 owner drag 的自定义对象;Group 使用
324
- `DirectChild` dive,普通 Shape/Line 使用 `Standard`。Transform provider 在 gesture start 捕获 frozen
325
- reference 与领域 owned state,每帧只纯解析最终 owner change;frame-authored Shape、pose-authored
326
- Group 与 authored-geometry Line/Polygon/EditorVectorPath 共用 Core reference-transform primitive,结构化
327
- authored value 不为 caller isolation clone。Group 的稳定 reference 由创建时的 width/height/origin 与
328
- pose 拥有;当前 content bounds 是只读 local derived view。Line/LineTree 的
329
- 固定world paint padding不贡献ancestor content bounds,但仍进入各自render coverage。普通Group
330
- move/rotate只写自身pose;Group或多选resize/flip递归写入子元素的frame或矢量geometry。group/ungroup
331
- 只转换 local pose,保留 width/geometry/path/topology、effect 与 relation 的值和引用。
332
-
333
- `selectable:false`只限制Editor交互选择,并对该owner分支生效:普通点击、marquee、Select All与
334
- Group DirectChild下钻都不能进入该分支。公开`Select.select(elements)`和History selection replay由
335
- 调用者直接控制,不增加过滤;把已选owner改为`selectable:false`也不会自动清除当前selection。
205
+ `OwnerDirect` 适合直接拖动且不显示单选框的对象;Group 使用 `DirectChild` 下钻,
206
+ 普通图形使用 `Standard`。完整接口见[编辑器规范](../../docs/specs/editor-interaction.md)。
207
+
208
+ `selectable: false` 禁止交互选择进入该元素分支;程序化 `Select.select()` 仍由调用方决定,
209
+ 修改该属性也不会自动清除已有选择。
210
+
211
+ ## Bitmap surface
212
+
213
+ 自定义位图元素继承 `Bitmap`,通过 `presentBitmap()` 交付新帧;交付后由 Bitmap 负责替换和释放资源。
214
+ `renderPixelRatio` 为 `Viewport scale × DPR`,位图分辨率不改变局部逻辑坐标。
215
+
216
+ 创建渲染 surface 时调用 `startFrameSurface(pixelRatio)`;后续仅在
217
+ `claimFrameResize(pixelRatio)` 返回 `true` 时发送 resize。前一帧到达前不会再次放行尺寸请求。
218
+
219
+ Worker 接入与资源生命周期见 [Worker-backed bitmap 扩展](../core/docs/guides/extending-core.md#worker-backed-bitmap-扩展)。
package/dist/index.d.ts CHANGED
@@ -49,3 +49,5 @@ export type { LineDecoration, LineEndpointRelationPatch, LineEndpointUpdate, Lin
49
49
  export * from "./line/geometry";
50
50
  export * from "./line/orthogonal";
51
51
  export { resolveOrthogonalEndpoint } from "./line/base";
52
+ export { elementV2Codecs } from "./serialization";
53
+ export type { LineV2 } from "./serialization";
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { clearCache, layout, layoutNextLine, layoutNextLineRange, layoutWithLines, materializeLineRange, measureLineStats, measureNaturalWidth, prepareWithSegments } from "@chenglou/pretext";
2
- import { ChangeImpact, CustomEvent, Element, ElementProperties, ElementTransform, SKIN_DEFAULTS, Shape, ShapeProperties, ShapeTransform, VectorPath, VectorPathProperties, VectorPathTransform, appendAuthoredLineAnchor, captureElementTransformReference, createAuthoredLineSubpath, createGeometrySnapshot, createLineSubpath, createPathLocalId, evaluatePathSegmentPoint, getAuthoredAnchorBounds, getAuthoredPathLayoutBounds, getElementConnectionPortPoint, insertAuthoredPathAnchor, isReparentTransformIntent, mergeOwnerPropertyChanges, removeAuthoredAnchor, replaceAuthoredAnchorPoint, replaceAuthoredCubicHandle, resolveAuthoredGeometryFramePatch, resolveAuthoredSubpath, resolveReferenceBoundsTranslation, resolveReferenceTransform, transformAuthoredSubpath } from "@fulate/core";
2
+ import { ChangeImpact, CustomEvent, Element, ElementProperties, ElementTransform, SKIN_DEFAULTS, Shape, ShapeProperties, ShapeTransform, VectorPath, VectorPathProperties, VectorPathTransform, appendAuthoredLineAnchor, captureElementTransformReference, coreElementV2Codecs, createAuthoredLineSubpath, createGeometrySnapshot, createLineSubpath, createPathLocalId, evaluatePathSegmentPoint, getAuthoredAnchorBounds, getAuthoredPathLayoutBounds, getElementConnectionPortPoint, insertAuthoredPathAnchor, isReparentTransformIntent, mergeOwnerPropertyChanges, removeAuthoredAnchor, replaceAuthoredAnchorPoint, replaceAuthoredCubicHandle, resolveAuthoredGeometryFramePatch, resolveAuthoredSubpath, resolveReferenceBoundsTranslation, resolveReferenceTransform, transformAuthoredSubpath } from "@fulate/core";
3
3
  import { clamp, has, isFunction, isNil, isNull, isString, isUndefined, last } from "lodash-es";
4
4
  import { Bound, Intersection, Matrix2D, createCanvasGradient, createPointView, isGradient, isPointWithinDistance, projectBounds, rectEdgePosition, transformPoint } from "@fulate/share";
5
5
  import { computePosition as computePosition$1, flip, offset, shift } from "@floating-ui/core";
@@ -7364,4 +7364,113 @@ function applyLineTreeTopologyDelta(topology, delta, direction) {
7364
7364
  };
7365
7365
  }
7366
7366
  //#endregion
7367
- export { BaseLine, Bitmap, Circle, CircleTransform, ContentEditingCapabilityToken, DEFAULT_LINE_TREE_BRANCH_STYLE, DEFAULT_ORTHOGONAL_MARGIN, EMPTY_LINE_TREE_TOPOLOGY, EditorElementProperties, EditorFrameFlush, EditorShapeProperties, EditorVectorPath, EditorVectorPathProperties, EditorVectorPathTransform, EndpointRelationIndex, Group, GroupTransform, Image, ImageProperties, Line, LineTransform, LineTree, LineTreeProperties, LineTreeTransform, PointEditingCapabilityToken, Polygon, PolygonTransform, Rectangle, RectangleProperties, RectangleTransform, RippleOverlay, SCROLLBAR_DEFAULTS, ScrollView, ScrollViewTransform, Scrollbars, SelectionBehaviorCapabilityToken, SelectionBehaviorMode, SelectionDiveMode, SelectionSnapMode, SnapSourceCapabilityToken, Text, TextBlock, TextProperties, TextTransform, TransformInteractionCapabilityToken, Triangle, TriangleTransform, WorkerSurfacePool, Workspace, WorkspaceProperties, addLineTreeBranchAtTail, applyLineTreeTopologyDelta, computePosition, connectEndpoint, connectionPortAccepts, createLineTreeTopology, createLineTreeTopologyDelta, createManualLineGeometry, createOrthogonalLineGeometry, defineEditorCapability, disconnectEndpoint, fitWorkspace, flip, getEditorCapability, getEditorFrameFlush, getEndpointRelationIndex, getLineAnchors, getLineGeometryBounds, getLineTreeBranch, getLineTreeJunctionAnchorIds, getLineTreePoint, getLineTreePointReferenceCounts, getTextBlockVisualBounds, hasConnectionPortCapacity, hasLineCoordinateChange, hasLineGeometryChange, hasLineTreeTopologyChange, insertLineTreePoint, isEditorCapabilityHost, isEndpointRelationSource, materializeEffectiveEndpointPoints, measureTextRun, measureTextWidth, moveLineTreePoint, offset, paintTextBlock, quantizeOrthogonalDirection, remapLineTreeRelations, removeLineTreeBranch, removeLineTreePoint, replaceLineAnchorPoint, resolveConnectEndpointChange, resolveConnectionPortChanges, resolveDisconnectEndpointChanges, resolveGroupMemberBounds, resolveOrthogonalEndpoint, resolveOrthogonalWaypoint, resolveSelectionFrameBounds, resolveTextStyle, routeOrthogonal, shift, simplifyOrthogonalRoute, subscribeTextMeasurementChanges, transformLineGeometry, transformLineTreeTopology, updateLineTreeBranchStyle, workspaceFocusInsetsKey };
7367
+ //#region packages/ui/src/line/serialization.ts
7368
+ function encodeLine(element, context) {
7369
+ const line = element;
7370
+ const data = line.toJSON();
7371
+ if (!context || !line.headRelation && !line.tailRelation) return data;
7372
+ const vertices = line.getEffectiveLineVerticesView();
7373
+ let headPoint, tailPoint;
7374
+ const relations = { ...data.relations };
7375
+ for (const end of ["head", "tail"]) {
7376
+ const relation = line[end === "head" ? "headRelation" : "tailRelation"];
7377
+ if (!relation || context.sourceKeys.has(relation.target.elementKey)) continue;
7378
+ const point = end === "head" ? vertices[0].point : vertices[vertices.length - 1].point;
7379
+ const copied = {
7380
+ x: point.x,
7381
+ y: point.y
7382
+ };
7383
+ if (end === "head") headPoint = copied;
7384
+ else tailPoint = copied;
7385
+ delete relations[end];
7386
+ }
7387
+ const geometry = materializeEffectiveEndpointPoints(data.geometry, headPoint, tailPoint);
7388
+ if (geometry !== data.geometry) Object.assign(data, line.resolvePointGeometryPatch(geometry));
7389
+ if (relations.head || relations.tail) data.relations = relations;
7390
+ else delete data.relations;
7391
+ return data;
7392
+ }
7393
+ var lineCodec = {
7394
+ encode: encodeLine,
7395
+ decode(data, keyMap) {
7396
+ const { type, ...properties } = data;
7397
+ if (keyMap && properties.relations) {
7398
+ const remap = (relation) => relation && {
7399
+ ...relation,
7400
+ target: {
7401
+ ...relation.target,
7402
+ elementKey: keyMap.get(relation.target.elementKey)
7403
+ }
7404
+ };
7405
+ properties.relations = {
7406
+ head: remap(properties.relations.head),
7407
+ tail: remap(properties.relations.tail)
7408
+ };
7409
+ }
7410
+ return new Line(properties);
7411
+ }
7412
+ };
7413
+ //#endregion
7414
+ //#region packages/ui/src/line-tree/serialization.ts
7415
+ var lineTreeCodec = {
7416
+ encode(element, context) {
7417
+ const tree = element;
7418
+ const data = tree.toJSON();
7419
+ if (context) {
7420
+ const topology = data.topology;
7421
+ let changed = false;
7422
+ const points = topology.points.map((point) => {
7423
+ if (!point.relation || context.sourceKeys.has(point.relation.target.elementKey)) return point;
7424
+ changed = true;
7425
+ const { relation, ...anchor } = point;
7426
+ const effective = tree.transform.getResolvedPoint(point.anchorId).point;
7427
+ return {
7428
+ ...anchor,
7429
+ point: {
7430
+ x: effective.x,
7431
+ y: effective.y
7432
+ }
7433
+ };
7434
+ });
7435
+ if (changed) Object.assign(data, tree.resolvePointTopologyPatch({
7436
+ ...topology,
7437
+ points
7438
+ }));
7439
+ }
7440
+ return data;
7441
+ },
7442
+ decode({ type, ...properties }, keyMap) {
7443
+ if (keyMap) properties.topology = remapLineTreeRelations(properties.topology, keyMap);
7444
+ return new LineTree(properties);
7445
+ }
7446
+ };
7447
+ //#endregion
7448
+ //#region packages/ui/src/serialization.ts
7449
+ function codec(Constructor) {
7450
+ return {
7451
+ encode: (element) => element.toJSON(),
7452
+ decode: ({ type, ...properties }) => new Constructor(properties)
7453
+ };
7454
+ }
7455
+ function createCodecs() {
7456
+ return new Map([
7457
+ ...coreElementV2Codecs,
7458
+ ["rectangle", codec(Rectangle)],
7459
+ ["circle", codec(Circle)],
7460
+ ["triangle", codec(Triangle)],
7461
+ ["polygon", codec(Polygon)],
7462
+ ["vectorPath", codec(EditorVectorPath)],
7463
+ ["text", codec(Text)],
7464
+ ["image", codec(Image)],
7465
+ ["workspace", codec(Workspace)],
7466
+ ["group", codec(Group)],
7467
+ ["scrollview", codec(ScrollView)],
7468
+ ["line", lineCodec],
7469
+ ["lineTree", lineTreeCodec],
7470
+ ["ripple", codec(RippleOverlay)]
7471
+ ]);
7472
+ }
7473
+ /** Compose extensions with this map at the application boundary; keys are exact DTO types. */
7474
+ var elementV2Codecs = /* @__PURE__ */ createCodecs();
7475
+ //#endregion
7476
+ export { BaseLine, Bitmap, Circle, CircleTransform, ContentEditingCapabilityToken, DEFAULT_LINE_TREE_BRANCH_STYLE, DEFAULT_ORTHOGONAL_MARGIN, EMPTY_LINE_TREE_TOPOLOGY, EditorElementProperties, EditorFrameFlush, EditorShapeProperties, EditorVectorPath, EditorVectorPathProperties, EditorVectorPathTransform, EndpointRelationIndex, Group, GroupTransform, Image, ImageProperties, Line, LineTransform, LineTree, LineTreeProperties, LineTreeTransform, PointEditingCapabilityToken, Polygon, PolygonTransform, Rectangle, RectangleProperties, RectangleTransform, RippleOverlay, SCROLLBAR_DEFAULTS, ScrollView, ScrollViewTransform, Scrollbars, SelectionBehaviorCapabilityToken, SelectionBehaviorMode, SelectionDiveMode, SelectionSnapMode, SnapSourceCapabilityToken, Text, TextBlock, TextProperties, TextTransform, TransformInteractionCapabilityToken, Triangle, TriangleTransform, WorkerSurfacePool, Workspace, WorkspaceProperties, addLineTreeBranchAtTail, applyLineTreeTopologyDelta, computePosition, connectEndpoint, connectionPortAccepts, createLineTreeTopology, createLineTreeTopologyDelta, createManualLineGeometry, createOrthogonalLineGeometry, defineEditorCapability, disconnectEndpoint, elementV2Codecs, fitWorkspace, flip, getEditorCapability, getEditorFrameFlush, getEndpointRelationIndex, getLineAnchors, getLineGeometryBounds, getLineTreeBranch, getLineTreeJunctionAnchorIds, getLineTreePoint, getLineTreePointReferenceCounts, getTextBlockVisualBounds, hasConnectionPortCapacity, hasLineCoordinateChange, hasLineGeometryChange, hasLineTreeTopologyChange, insertLineTreePoint, isEditorCapabilityHost, isEndpointRelationSource, materializeEffectiveEndpointPoints, measureTextRun, measureTextWidth, moveLineTreePoint, offset, paintTextBlock, quantizeOrthogonalDirection, remapLineTreeRelations, removeLineTreeBranch, removeLineTreePoint, replaceLineAnchorPoint, resolveConnectEndpointChange, resolveConnectionPortChanges, resolveDisconnectEndpointChanges, resolveGroupMemberBounds, resolveOrthogonalEndpoint, resolveOrthogonalWaypoint, resolveSelectionFrameBounds, resolveTextStyle, routeOrthogonal, shift, simplifyOrthogonalRoute, subscribeTextMeasurementChanges, transformLineGeometry, transformLineTreeTopology, updateLineTreeBranchStyle, workspaceFocusInsetsKey };
@@ -0,0 +1,11 @@
1
+ import type { ElementPayload, ElementV2Codec } from "@fulate/core";
2
+ import type { LineGeometry } from "./geometry";
3
+ import type { LineEndpointRelationPatch } from "./base";
4
+ export interface LineV2 extends ElementPayload {
5
+ readonly type: "line";
6
+ geometry: LineGeometry;
7
+ /** Horizontal label fixed at half the effective route length. */
8
+ text?: string;
9
+ relations?: LineEndpointRelationPatch;
10
+ }
11
+ export declare const lineCodec: ElementV2Codec;
@@ -0,0 +1,2 @@
1
+ import type { ElementV2Codec } from "@fulate/core";
2
+ export declare const lineTreeCodec: ElementV2Codec;
@@ -0,0 +1,4 @@
1
+ import { type ElementV2Codecs } from "@fulate/core";
2
+ export type { LineV2 } from "./line/serialization";
3
+ /** Compose extensions with this map at the application boundary; keys are exact DTO types. */
4
+ export declare const elementV2Codecs: ElementV2Codecs;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fulate/ui",
3
- "version": "2.0.11",
3
+ "version": "3.0.2",
4
4
  "type": "module",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",
@@ -25,8 +25,8 @@
25
25
  "dependencies": {
26
26
  "@chenglou/pretext": "0.0.8",
27
27
  "@floating-ui/core": "^1.8.0",
28
- "@fulate/core": "2.0.11",
29
- "@fulate/share": "2.0.11",
28
+ "@fulate/core": "3.0.2",
29
+ "@fulate/share": "3.0.2",
30
30
  "@tweenjs/tween.js": "^25.0.0",
31
31
  "lodash-es": "^4.17.22"
32
32
  }