@fulate/ui 1.0.19 → 2.0.11

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.
Files changed (46) hide show
  1. package/README.md +81 -12
  2. package/dist/circle.d.ts +2 -1
  3. package/dist/connection/commands.d.ts +3 -3
  4. package/dist/connection/types.d.ts +5 -1
  5. package/dist/connection-port-decoration.d.ts +18 -2
  6. package/dist/editor/capability.d.ts +37 -6
  7. package/dist/editor/frame-flush.d.ts +3 -4
  8. package/dist/editor/properties.d.ts +31 -0
  9. package/dist/editor/shape-capability.d.ts +13 -0
  10. package/dist/editor/shape.d.ts +16 -19
  11. package/dist/editor/transform.d.ts +1 -3
  12. package/dist/editor-vector-path.d.ts +70 -0
  13. package/dist/floating.d.ts +12 -2
  14. package/dist/group.d.ts +17 -8
  15. package/dist/image.d.ts +16 -19
  16. package/dist/index.d.ts +13 -6
  17. package/dist/index.js +2683 -1590
  18. package/dist/line/base.d.ts +64 -27
  19. package/dist/line/geometry.d.ts +28 -0
  20. package/dist/line/index.d.ts +2 -0
  21. package/dist/line/label.d.ts +58 -0
  22. package/dist/line/orthogonal.d.ts +23 -0
  23. package/dist/line/straight.d.ts +7 -3
  24. package/dist/line-tree/history-delta.d.ts +2 -0
  25. package/dist/line-tree/index.d.ts +15 -8
  26. package/dist/line-tree/transform.d.ts +1 -0
  27. package/dist/line-tree/types.d.ts +3 -2
  28. package/dist/polygon.d.ts +19 -38
  29. package/dist/rectangle.d.ts +5 -4
  30. package/dist/ripple.d.ts +18 -4
  31. package/dist/scrollbars.d.ts +36 -0
  32. package/dist/scrollview.d.ts +27 -21
  33. package/dist/text/block.d.ts +5 -1
  34. package/dist/text/editing.d.ts +54 -12
  35. package/dist/text/index.d.ts +22 -20
  36. package/dist/text/layout.d.ts +8 -2
  37. package/dist/text/paint.d.ts +3 -2
  38. package/dist/text/style.d.ts +4 -0
  39. package/dist/triangle.d.ts +10 -5
  40. package/dist/worker-surface-worker.d.ts +4 -1
  41. package/dist/worker-surface-worker.js +11 -8
  42. package/dist/worker-surface.d.ts +1 -0
  43. package/dist/workspace.d.ts +3 -3
  44. package/package.json +33 -33
  45. package/dist/authored-path.d.ts +0 -28
  46. package/dist/vector-path.d.ts +0 -58
package/README.md CHANGED
@@ -1,5 +1,10 @@
1
1
  # @fulate/ui authored paths
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。
7
+
3
8
  ## Bitmap surface
4
9
 
5
10
  `Bitmap`唯一拥有主线程当前frame,并向位图producer提供`renderPixelRatio = Viewport scale × DPR`。
@@ -11,17 +16,39 @@ producer保持authored-local布局;需要超采样时,在自己的backend中
11
16
  且上一次请求的frame已经`presentBitmap()`时才返回`true`,producer据此发送一次自己的resize消息。
12
17
  等待期间的变化在该frame绘制后按最新值发送,renderer同时最多处理一次待完成的尺寸请求。
13
18
 
19
+ Worker 的 `onFrame` 和 emitter 的 `emit` 调用把 bitmap 所有权交给接收方;接收方采用后发生异常,
20
+ 发送方不再关闭该资源。跨 Worker 的原生 `postMessage` 成功后才完成跨 realm 转移;发送失败时仍持有
21
+ bitmap 的 host 负责释放并传播原异常。已经失效且尚未交付的 frame 由收到它的资源 owner 关闭。
22
+
14
23
  位图、DPR和超采样质量都不改变逻辑坐标。鼠标与Worker返回的坐标保持authored-local,不经过
15
24
  `Bitmap`的scale换算。
16
25
 
26
+ PNG 导出直接借用当前 bitmap,通过同一 `paintBitmap()` 绘制。导出不向 Worker 请求新帧,
27
+ 也不接管 bitmap 的释放;尺寸与清晰度语义见 [PNG 导出](../core/docs/guides/png-export.md)。
28
+
17
29
  ## Image 尺寸与加载
18
30
 
19
- `Image` 未提供尺寸时使用当前源的 `naturalWidth`/`naturalHeight`;`fitWidth`/`fitHeight` 使用父元素布局尺寸,显式
31
+ `Image` 未提供尺寸时直接读取当前源的 `naturalWidth`/`naturalHeight`;显式
20
32
  `width`/`height` 优先且保留 `0`。源的 intrinsic 尺寸变化进入同一 geometry/layout 提交,位图分辨率
21
33
  升级只重绘,不改变逻辑尺寸。
22
34
 
23
35
  `src` 与构造时提供的 `image` 使用同一加载路径;切换源、detach、重新进入和 unmount 都使旧处理
24
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。
25
52
 
26
53
  ## Workspace fit
27
54
 
@@ -41,13 +68,16 @@ await fitWorkspace(workspace, { padding: 0 });
41
68
  显式调用不受`WorkspaceOption.fit`或`WorkspaceOption.fitOnResize`限制;传入的focus options会按原引用
42
69
  直接交给Workspace所属Root的Viewport。用户触发的fit需要动画时由调用者显式传入`animate`。
43
70
 
44
- `Line`、`Polygon` 和 `VectorPath` 都只有一份 live canonical authored owner:
71
+ 通用场景路径从 `@fulate/core` 导入 VectorPath;编辑器使用 `@fulate/ui` 的 EditorVectorPath。
72
+ Polygon 继承 EditorVectorPath。VectorPathCommand、VectorPathGeometry 和基础 VectorPathOption 从 Core 导入。
73
+
74
+ `Line`、`Polygon` 和 `EditorVectorPath` 都只有一份 live canonical authored owner:
45
75
 
46
76
  | 元素 | 普通创建输入 | live getter | topology |
47
77
  | --- | --- | --- | --- |
48
- | `Line` | `path: PointView[]` | `line.path` | 一个 open、line-only subpath |
49
- | `Polygon` | `contour: PointView[]` | `polygon.contour` | 一个 closed、line-only subpath |
50
- | `VectorPath` | `path: VectorPathCommand[]` | `vector.path.subpaths` | ordered open/closed line/cubic subpaths |
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 |
51
81
 
52
82
  普通输入只在入口解释一次。每个 canonical anchor record 直接保存 `anchorId`、原 `point` 引用,
53
83
  并在存在 outgoing segment 时共置 `segmentId` 与 `line | cubic` 数据;普通 line segment 没有
@@ -55,7 +85,7 @@ await fitWorkspace(workspace, { padding: 0 });
55
85
 
56
86
  ```ts
57
87
  const line = new Line({
58
- path: [{ x: 0, y: 0 }, { x: 80, y: 30 }]
88
+ points: [{ x: 0, y: 0 }, { x: 80, y: 30 }]
59
89
  });
60
90
 
61
91
  const anchorId = line.headAnchor.anchorId;
@@ -68,6 +98,25 @@ line.setLocalPoint(anchorId, { x: 10, y: 5 });
68
98
  调用者在传入前复制。调用者在所有权移交后原地修改同一对象不会自动产生 commit、dirty、
69
99
  History 或 frame。
70
100
 
101
+ 正交线使用同一个 Line:
102
+
103
+ ```ts
104
+ const line = new Line({
105
+ geometry: createOrthogonalLineGeometry([{x: 0, y: 0}, {x: 180, y: 100}]),
106
+ text: '审核通过', // 可选:固定在当前路线总长度一半的位置
107
+ tailDecoration: "arrow"
108
+ });
109
+ ```
110
+
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)。
119
+
71
120
  ## Connection、Port 与 Line endpoints
72
121
 
73
122
  Path authored `anchorId` 与 target owner-local `portId` 是两个概念。Line 首尾 endpoint 与
@@ -83,13 +132,19 @@ interface EndpointRelation {
83
132
  }
84
133
  ```
85
134
 
86
- relation不保存坐标。`Line.path`与`LineTree.topology.points`保存authored fallback;paint、hit、bounds、
135
+ relation不保存坐标。`Line.geometry`与`LineTree.topology.points`保存authored fallback;paint、hit、bounds、
87
136
  query和controls从当前target Port解析effective geometry。target变化只通过Root唯一
88
137
  `EndpointRelationIndex`精确dirty dependents,不反写source authored值或History。
89
138
 
90
139
  Line的`relations` patch省略时两端保持;对象中省略一端也表示保持,own `undefined`清除该端,
91
140
  `EndpointRelation`建立或替换。程序化连接使用同步`connectEndpoint(root, source, target)`与
92
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-读取与状态推进)。
93
148
 
94
149
  Line首端/root endpoint的连接role是`output`,尾端/leaf是`input`;装饰不决定连接role。同步
95
150
  `connectEndpoint()`从live source与target Port读取role、`direction`和对应capacity;方向不兼容、容量
@@ -104,7 +159,7 @@ noop,不clone、freeze、normalize或deep-equal。
104
159
  因此Line/LineTree继续跟随目标;显式Port删除/替换仍物化当前fallback并detach。完整开关边界见
105
160
  [`path-line-core.md`](../../docs/specs/path-line-core.md#10-transformpointbinding-与-routing-边界)。
106
161
 
107
- JSON、clipboard和History的独立输出复制所需数据;restore直接安装canonical path/topology、IDs和
162
+ JSON、clipboard和History的独立输出复制所需数据;restore直接安装canonical geometry/path/topology、IDs和
108
163
  source-owned relations。source与target一起复制时只重映射element key;只复制source时使用当前
109
164
  resolved source-local fallback并删除外部relation;完整owner的subpath/anchor/segment/Port IDs保留。
110
165
 
@@ -139,8 +194,8 @@ tail成为source,同一junction tail可重复产生sibling branches,但junct
139
194
 
140
195
  Line与LineTree的stroke和端点decoration在world空间按固定宽度绘制;自身visual bounds与render
141
196
  coverage覆盖同一完整绘制范围,反向近零Transform也不会缩掉dirty coverage。固定world paint padding
142
- 不贡献ancestor content bounds;Group selection、resize与snap只消费Line/LineTree的effective path
143
- geometry。hover与active branch highlight复用同一polyline paint,箭头和线段保持同色。
197
+ 不进入Line/LineTree的selection/resize frame或ancestor content bounds;单选、多选及Group均使用
198
+ effective path geometry计量线的尺寸。hover与active branch highlight复用同一polyline paint,箭头和线段保持同色。
144
199
 
145
200
  Rectangle、Triangle及其他Shape省略`backgroundColor`/`borderColor`时读取当前Root的
146
201
  `skin.shapeFill`/`skin.shapeStroke`;Line和LineTree branch省略`strokeColor`时读取
@@ -149,6 +204,9 @@ Rectangle、Triangle及其他Shape省略`backgroundColor`/`borderColor`时读取
149
204
 
150
205
  LineTree整体resize把全部拓扑点按完整仿射写回 authored topology。随后Point编辑和L分支扩展在
151
206
  同一owner change内保留当前world pose;包括反向scale在内,未编辑points保持world位置不变。
207
+ 分支选择使用 Core 的 world 距离查询;共享 junction 在各分支 view 中借用同一个 world point。
208
+ 仅修改分支颜色或装饰不重建路径 geometry;线宽更新 visual bounds,真实 points/vertices/graph 变化
209
+ 才失效对应 geometry。
152
210
 
153
211
  ## Text 尺寸与显示
154
212
 
@@ -161,6 +219,17 @@ Editor 的 Text selection/resize frame 使用布局盒,不使用可见溢出 g
161
219
  `wordWrap={false}`、`overflow="visible"` 的文本被缩放后,取消选择再重新选择仍保持上一次 authored
162
220
  尺寸,下一次缩放也从该尺寸继续。
163
221
 
222
+ visual bounds 使用同一 TextLayoutSnapshot 内按行测量并复用的真实 glyph ink,包含斜体外伸;
223
+ 该范围不改变布局盒或 selection/resize frame。
224
+
225
+ caret、selection 和编辑首尾只更新 paint 与 R2 textarea 投影;文字输入仍通过所属 writer 进入布局。
226
+ placeholder 的宽度由 Text 一次测量供 bounds/paint 共用,并在 placeholder、字体或样式输入变化时失效。
227
+
228
+ 尺寸、paint、geometry、caret 与 textarea 共享唯一纯缓存入口 `textLayout`;纯移动复用已有 layout 和
229
+ 本地 geometry。Span 使用 Yoga 的最终 frame 作为文字约束。文字自然尺寸与 Yoga frame 都不写入 authored
230
+ 属性或 History。字体加载与影响文字排版或视觉边界的 Skin 字段变化先捕获旧像素范围,再失效相应缓存
231
+ 与祖先边界;颜色变化复用已有布局。Skin 的全层重绘同时覆盖读取 live Skin 的自定义 Shape。
232
+
164
233
  ### 原生 Canvas 文本 run
165
234
 
166
235
  组合型原生 Shape 可以直接传入 live resolved Skin,按 `Text` 相同的字体、行高、Canvas baseline
@@ -254,12 +323,12 @@ const behavior = {
254
323
  `OwnerDirect` 用于不绘制单选 frame、首次位移可直接提升 owner drag 的自定义对象;Group 使用
255
324
  `DirectChild` dive,普通 Shape/Line 使用 `Standard`。Transform provider 在 gesture start 捕获 frozen
256
325
  reference 与领域 owned state,每帧只纯解析最终 owner change;frame-authored Shape、pose-authored
257
- Group 与 authored-geometry Line/Polygon/VectorPath 共用 Core reference-transform primitive,结构化
326
+ Group 与 authored-geometry Line/Polygon/EditorVectorPath 共用 Core reference-transform primitive,结构化
258
327
  authored value 不为 caller isolation clone。Group 的稳定 reference 由创建时的 width/height/origin 与
259
328
  pose 拥有;当前 content bounds 是只读 local derived view。Line/LineTree 的
260
329
  固定world paint padding不贡献ancestor content bounds,但仍进入各自render coverage。普通Group
261
330
  move/rotate只写自身pose;Group或多选resize/flip递归写入子元素的frame或矢量geometry。group/ungroup
262
- 只转换 local pose,保留 width/path/contour/topology、effect 与 relation 的值和引用。
331
+ 只转换 local pose,保留 width/geometry/path/topology、effect 与 relation 的值和引用。
263
332
 
264
333
  `selectable:false`只限制Editor交互选择,并对该owner分支生效:普通点击、marquee、Select All与
265
334
  Group DirectChild下钻都不能进入该分支。公开`Select.select(elements)`和History selection replay由
package/dist/circle.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { type EditorShapeOption } from "./editor/properties";
1
2
  import { type PointView } from "@fulate/share";
2
3
  import type { Edge } from "@fulate/share";
3
4
  import { type GeometrySnapshot } from "@fulate/core";
@@ -13,7 +14,7 @@ export declare class CircleTransform<E extends Circle = Circle> extends EditorSh
13
14
  }
14
15
  export declare class Circle extends EditorShape {
15
16
  readonly type = "circle";
16
- constructor(options?: {});
17
+ constructor(options?: EditorShapeOption);
17
18
  protected buildPath(ctx: CanvasRenderingContext2D): void;
18
19
  getEdgePosition(edge: Edge, ratio: number): {
19
20
  pos: PointView;
@@ -1,13 +1,13 @@
1
1
  import { Element, type AnchorId, type ConnectionPortDefinition, type ConnectionPortRef, type OwnerPropertyChange, type Root } from "@fulate/core";
2
2
  import type { PointView } from "@fulate/share";
3
3
  import { type EndpointConnectionRole, type EndpointRef } from "./types";
4
- /** 按 endpoint role、Port direction 与当前 capacity 建立 Binding。 */
4
+ /** R0:按 endpoint role、Port direction 与当前 capacity 建立 Binding。 */
5
5
  export declare function connectEndpoint(root: Root, source: EndpointRef, target: ConnectionPortRef): void;
6
- /** 删除普通 Binding;省略 localPosition 时物化当前 resolved 位置。 */
6
+ /** R0:删除普通 Binding;省略 localPosition 时读取已准备的 resolved 位置。 */
7
7
  export declare function disconnectEndpoint(root: Root, source: EndpointRef, options?: {
8
8
  readonly localPosition?: PointView;
9
9
  }): void;
10
- /** @internal 从调用时 live scene 按当前连接规则生成一次 owner change。 */
10
+ /** @internal 从调用时 live scene 纯计算一次 owner change;resolver 不提交场景或推进阶段。 */
11
11
  export declare function resolveConnectEndpointChange(root: Root, source: EndpointRef, target: ConnectionPortRef): OwnerPropertyChange | null;
12
12
  /** @internal 按 source owner 合并多个 detach 为每 owner 一个 final change。 */
13
13
  export declare function resolveDisconnectEndpointChanges(root: Root, sources: readonly EndpointRef[], localPositions?: ReadonlyMap<AnchorId, PointView>, patches?: ReadonlyMap<Element, Readonly<Record<string, unknown>>>): OwnerPropertyChange[];
@@ -22,7 +22,11 @@ export interface EndpointRelationBinding {
22
22
  export interface BindableEndpoint {
23
23
  readonly ref: EndpointRef;
24
24
  }
25
- /** Standalone Line 与 LineTree 共用的 source-owned relation 接缝。 */
25
+ /**
26
+ * Standalone Line 与 LineTree 共用的 source-owned relation 接缝。
27
+ * 查询与 resolver 只消费当前 canonical 输入,可填所属纯计算缓存;不得提交场景、
28
+ * 改变结构/交互或推进运行阶段。resolver 返回的 typed effect 由调用者同步提交一次。
29
+ */
26
30
  export interface EndpointRelationSource {
27
31
  getBindableEndpoints(): readonly BindableEndpoint[];
28
32
  getEndpointRole(anchorId: AnchorId): EndpointConnectionRole | null;
@@ -1,26 +1,42 @@
1
+ import { type PaintContext } from "@fulate/core";
1
2
  import { type ResolvedConnectionPortSlot, type Root, type Shape } from "@fulate/core";
2
3
  import { Bound } from "@fulate/share";
3
4
  type ConnectionPortDecorationHost = Shape & {
4
5
  getResolvedConnectionPortSlots(): readonly ResolvedConnectionPortSlot[];
5
6
  };
6
- /** EditorShape 内部的非节点 Port 绘制、文字布局和 visual bounds 组合。 */
7
+ /** UI Shape 内部的非节点 Port 绘制、文字布局和 visual bounds 组合。 */
7
8
  export declare class ConnectionPortDecoration {
8
9
  private readonly host;
10
+ static isEnabled(host: ConnectionPortDecorationHost): boolean;
11
+ static create(host: ConnectionPortDecorationHost): ConnectionPortDecoration;
12
+ static syncPorts(host: ConnectionPortDecorationHost, decoration: ConnectionPortDecoration | null): ConnectionPortDecoration;
13
+ static activateForRoot(root: Root | null, decoration: ConnectionPortDecoration | null): ConnectionPortDecoration;
14
+ paintWithHost(paint: PaintContext): void;
9
15
  private slotSource;
10
16
  private entries;
11
17
  private activeRoot;
12
18
  private skinTextCommitRemove;
13
19
  private measurementRemove;
20
+ private placementMatrixA;
21
+ private placementMatrixB;
22
+ private placementMatrixC;
23
+ private placementMatrixD;
24
+ private placementMatrixE;
25
+ private placementMatrixF;
14
26
  constructor(host: ConnectionPortDecorationHost);
15
27
  activate(root: Root): void;
16
28
  deactivate(): void;
17
29
  invalidateSource(): void;
18
- paint(ctx: CanvasRenderingContext2D): void;
30
+ paint(paint: PaintContext): void;
19
31
  getWorldBounds(): Bound | null;
20
32
  private getEntries;
21
33
  private resolveLabelPlacement;
34
+ private updatePlacementMatrix;
35
+ /** Bounds 与 paint 借用同一次 slot/font/world-matrix 定位结果。 */
36
+ private getLabelPlacement;
22
37
  private getStyle;
23
38
  private buildUprightMatrix;
39
+ private readonly handleSkinTextChanged;
24
40
  private readonly handleTextMeasurementChanged;
25
41
  private invalidateTextLayout;
26
42
  }
@@ -1,4 +1,4 @@
1
- import { Element, type AnchorId, type ElementTransformBaseline, type OwnerPropertyChange, type ReparentTransformIntent, type SegmentId, type StablePathTargetRef, type SubpathId, type TransformIntent } from "@fulate/core";
1
+ import { Element, type AnchorId, type GeometrySnapshot, type ElementTransformBaseline, type OwnerPropertyChange, type OriginX, type OriginY, type ReparentTransformIntent, type SegmentId, type StablePathTargetRef, type SubpathId, type TransformIntent } from "@fulate/core";
2
2
  import type { PointView, Rect } from "@fulate/share";
3
3
  import type { EndpointRef } from "../connection/types";
4
4
  declare const capabilityType: unique symbol;
@@ -6,7 +6,7 @@ declare const capabilityType: unique symbol;
6
6
  export interface EditorCapabilityToken<T> {
7
7
  readonly [capabilityType]?: T;
8
8
  }
9
- /** 由元素直接实现的最小 Editor capability provider。 */
9
+ /** 纯查询能力;可填本 owner 的计算缓存,不改变场景、选择或运行阶段。 */
10
10
  export interface EditorCapabilityHost {
11
11
  getEditorCapability<T>(token: EditorCapabilityToken<T>): T | undefined;
12
12
  }
@@ -48,21 +48,33 @@ export interface TransformInteractionPolicy {
48
48
  readonly rotationPivot: "center-only" | "adjustable";
49
49
  }
50
50
  export interface TransformInteractionCapability<Owned = unknown> {
51
+ readonly rotationPivotX: OriginX;
52
+ readonly rotationPivotY: OriginY;
51
53
  getTransformPolicy(): TransformInteractionPolicy;
52
- /** Optional authored/layout bounds used by the editor transform frame. */
54
+ /** Optional local bounds used by the editor frame (authored/layout or effective geometry). */
53
55
  getSelectionFrameBounds?(): Readonly<Rect> | null;
54
- /** Capture start state using the same bakeGeometry policy as the ensuing intent. */
56
+ /** R0: capture the prepared geometry reference and current authored state. */
55
57
  captureTransformBaseline(bakeGeometry: boolean): ElementTransformBaseline<Owned>;
56
58
  /**
57
59
  * Resolves every owner change for this transform. Composite owners may return
58
60
  * multiple child changes; the editor commits the complete result in one batch.
61
+ * Pure calculation: do not mutate scene/interaction state or advance a phase.
59
62
  */
60
63
  resolveTransformChange(baseline: Readonly<ElementTransformBaseline<Owned>>, intent: Readonly<TransformIntent | ReparentTransformIntent>): readonly OwnerPropertyChange[];
61
64
  }
62
65
  export interface SnapSourceCapability {
66
+ /** Borrow the committed world projection until its geometry/matrix inputs change. */
63
67
  getWorldSnapPointsView(): readonly PointView[];
64
68
  }
65
- export type PointEditTarget = StablePathTargetRef | {
69
+ export type PointEditTarget = {
70
+ readonly kind: "route-segment";
71
+ readonly snapshot: GeometrySnapshot;
72
+ readonly index: number;
73
+ } | {
74
+ readonly kind: "orthogonal-segment";
75
+ readonly from: AnchorId;
76
+ readonly to: AnchorId;
77
+ } | StablePathTargetRef | {
66
78
  readonly kind: "handle";
67
79
  readonly segmentId: SegmentId;
68
80
  readonly role: "cubic-control-1" | "cubic-control-2";
@@ -75,6 +87,13 @@ export type PointEditingScope = {
75
87
  readonly subpathId: SubpathId;
76
88
  };
77
89
  export type PointControlDescriptor = {
90
+ readonly kind: "move-segment";
91
+ readonly target: Extract<PointEditTarget, {
92
+ kind: "route-segment" | "orthogonal-segment";
93
+ }>;
94
+ readonly local: PointView;
95
+ readonly axis: "x" | "y";
96
+ } | {
78
97
  readonly kind: "anchor";
79
98
  readonly target: Extract<PointEditTarget, {
80
99
  readonly kind: "anchor";
@@ -101,6 +120,14 @@ export type PointControlDescriptor = {
101
120
  readonly anchorLocal: PointView;
102
121
  };
103
122
  export type PointEditRequest = {
123
+ readonly kind: "move-segment";
124
+ readonly target: Extract<PointEditTarget, {
125
+ kind: "route-segment" | "orthogonal-segment";
126
+ }>;
127
+ readonly world: PointView;
128
+ /** World distance for collapsing a short neighboring orthogonal fold. */
129
+ readonly mergeTolerance: number;
130
+ } | {
104
131
  readonly kind: "move-anchor";
105
132
  readonly anchorId: AnchorId;
106
133
  readonly local: PointView;
@@ -132,9 +159,12 @@ export type PointOwnerEdit = {
132
159
  readonly source: EndpointRef;
133
160
  readonly local: PointView;
134
161
  };
162
+ /** Pure scope/control/effect computation from current canonical and prepared geometry. */
135
163
  export interface PointEditingCapability {
136
164
  resolvePointScope(worldPoint: PointView, current?: PointEditingScope): PointEditingScope | null;
137
165
  hasPointScope(scope: PointEditingScope): boolean;
166
+ /** Tests authored target existence independently of the visible control projection. */
167
+ hasPointTarget(scope: PointEditingScope, target: PointEditTarget): boolean;
138
168
  getPointControls(scope: PointEditingScope): readonly PointControlDescriptor[];
139
169
  getPointScopeOutline(scope: PointEditingScope): readonly PointView[] | null;
140
170
  resolvePointEdit(request: PointEditRequest): PointOwnerEdit | null;
@@ -148,8 +178,9 @@ export interface ContentEditingCapability {
148
178
  }
149
179
  export interface ContentEditingSession {
150
180
  readonly ownerKey: string;
181
+ /** Pure text effect; submit/History ownership remains with the consumer. */
151
182
  resolveTextChange(value: string): OwnerPropertyChange | null;
152
- /** 释放 DOM/listeners;不得再次触发 consumer.finish()。 */
183
+ /** 只释放本 session 的 DOM/listeners;不得再次触发 consumer.finish()。 */
153
184
  close(): void;
154
185
  }
155
186
  export declare const SelectionBehaviorCapabilityToken: EditorCapabilityToken<SelectionBehaviorCapability>;
@@ -1,17 +1,18 @@
1
1
  import { type Root, type RootFrameParticipant } from "@fulate/core";
2
2
  import type { PointView } from "@fulate/share";
3
3
  export interface EditorAuthoredGesture {
4
+ /** R0: consume the latest accepted intent and synchronously commit its typed effects. */
4
5
  consumeLatestIntent(): void;
5
6
  }
6
7
  export interface EditorOverlayClient {
7
8
  hasPendingOverlayWork(): boolean;
9
+ /** R2: consume stable geometry and replace only the interaction projection. */
8
10
  flushOverlayProjection(): void;
9
- hasPendingCompletionWork(): boolean;
10
- flushCompletionWork(): void;
11
11
  resolveCursor(point: PointView | undefined, contentCursor: string): string;
12
12
  }
13
13
  export interface EditorSpatialClient {
14
14
  hasPendingSpatialWork(): boolean;
15
+ /** R2: update the owner's projection from the committed scene and geometry. */
15
16
  flushSpatialProjection(): void;
16
17
  }
17
18
  /** @internal Root 生命周期内唯一的 Editor mutation/spatial/overlay participant。 */
@@ -31,8 +32,6 @@ export declare class EditorFrameFlush implements RootFrameParticipant {
31
32
  flushSpatialProjection(): void;
32
33
  hasPendingOverlayWork(): boolean;
33
34
  flushOverlayProjection(): void;
34
- hasPendingCompletionWork(): boolean;
35
- flushCompletionWork(): void;
36
35
  resolveCursor(point: PointView | undefined, contentCursor: string): string;
37
36
  }
38
37
  /** 取得并在需要时安装当前 Root 唯一的 Editor FrameFlush。 */
@@ -0,0 +1,31 @@
1
+ import { ChangeImpact, ElementProperties, ShapeProperties, type BaseElementOption, type OriginX, type OriginY, type PropertyChanges, type ShapeOption } from "@fulate/core";
2
+ /** 编辑器旋转中心的 authored 配置。 */
3
+ export interface EditorPivotOptions {
4
+ /** x 轴旋转中心,默认 `"center"`。 */
5
+ rotationPivotX?: OriginX;
6
+ /** y 轴旋转中心,默认 `"center"`。 */
7
+ rotationPivotY?: OriginY;
8
+ }
9
+ export interface EditorElementOption<T = any> extends BaseElementOption<T>, EditorPivotOptions {
10
+ }
11
+ export interface EditorShapeOption<T = any> extends ShapeOption<T>, EditorPivotOptions {
12
+ }
13
+ /** runtime 覆盖只接受可参与当前显示的字段。 */
14
+ export type EditorRuntimePatch<Patch> = Omit<Patch, keyof EditorPivotOptions> & {
15
+ [K in keyof EditorPivotOptions]?: never;
16
+ };
17
+ export declare function pivotImpact(changes: PropertyChanges): ChangeImpact.None | ChangeImpact.Hover;
18
+ /** Element 派生领域对象的编辑器配置。 */
19
+ export declare class EditorElementProperties extends ElementProperties {
20
+ rotationPivotX: OriginX;
21
+ rotationPivotY: OriginY;
22
+ constructor(options?: EditorElementOption);
23
+ getImpact(changes: PropertyChanges): number;
24
+ }
25
+ /** Shape 派生领域对象的编辑器配置。 */
26
+ export declare class EditorShapeProperties extends ShapeProperties {
27
+ rotationPivotX: OriginX;
28
+ rotationPivotY: OriginY;
29
+ constructor(options?: EditorShapeOption);
30
+ getImpact(changes: PropertyChanges): number;
31
+ }
@@ -0,0 +1,13 @@
1
+ import { SelectionBehaviorMode, SelectionDiveMode, SelectionSnapMode, type EditorCapabilityToken, type SelectionBehaviorCapability, type SnapSourceCapability, type TransformInteractionCapability } from "./capability";
2
+ export declare const STANDARD_SELECTION: {
3
+ readonly mode: SelectionBehaviorMode.Standard;
4
+ readonly dive: SelectionDiveMode.None;
5
+ readonly snap: SelectionSnapMode.Enabled;
6
+ };
7
+ export declare const FRAME_TRANSFORM_POLICY: {
8
+ readonly move: true;
9
+ readonly resize: "both";
10
+ readonly rotate: true;
11
+ readonly rotationPivot: "adjustable";
12
+ };
13
+ export declare function getShapeEditorCapability<T>(host: SelectionBehaviorCapability & TransformInteractionCapability & SnapSourceCapability, token: EditorCapabilityToken<T>): T | undefined;
@@ -1,6 +1,8 @@
1
- import { type Layer, type PropertyChanges, type Root, Shape, ShapeProperties, ShapeTransform, type ConnectionPortConfiguration, type ElementOptionPatch, type ElementTransformBaseline, type ReparentTransformIntent, type ShapeOption, type TransformIntent } from "@fulate/core";
1
+ import type { PaintContext } from "@fulate/core";
2
+ import { Shape, ShapeTransform, type ElementOptionPatch, type ElementTransformBaseline, type Layer, type PropertyChanges, type ReparentTransformIntent, type Root, type TransformIntent } from "@fulate/core";
2
3
  import { Bound, type PointView, type ReadonlyMatrix2D, type Rect } from "@fulate/share";
3
- import { SelectionBehaviorMode, SelectionDiveMode, SelectionSnapMode, type EditorCapabilityToken, type SelectionBehaviorCapability, type SnapSourceCapability, type TransformInteractionCapability } from "./capability";
4
+ import type { EditorCapabilityToken, SelectionBehaviorCapability, SnapSourceCapability, TransformInteractionCapability, TransformInteractionPolicy } from "./capability";
5
+ import { EditorShapeProperties, type EditorRuntimePatch, type EditorShapeOption } from "./properties";
4
6
  export interface WorldRectPointsViewCache {
5
7
  source: Readonly<Rect> | null;
6
8
  a: number;
@@ -15,39 +17,34 @@ export declare function createWorldRectPointsViewCache(): WorldRectPointsViewCac
15
17
  /** Project one stable local frame to a borrowed world-point view. */
16
18
  export declare function getWorldRectPointsView(cache: WorldRectPointsViewCache, frame: Readonly<Rect>, matrix: ReadonlyMatrix2D): readonly PointView[];
17
19
  /** UI frame-authored Shape 系列共享的 direct Editor provider。 */
18
- export declare abstract class EditorShape<P extends ShapeProperties = ShapeProperties, O extends ShapeOption<any> = ShapeOption<any>> extends Shape<P, O> implements SelectionBehaviorCapability, TransformInteractionCapability, SnapSourceCapability {
20
+ export declare abstract class EditorShape<P extends EditorShapeProperties = EditorShapeProperties, O extends EditorShapeOption<any> = EditorShapeOption<any>> extends Shape<P, O, EditorRuntimePatch<ElementOptionPatch<O>>> implements SelectionBehaviorCapability, TransformInteractionCapability, SnapSourceCapability {
19
21
  private connectionPortDecoration;
20
22
  private readonly worldSnapPointsCache;
23
+ get rotationPivotX(): import("@fulate/core").OriginX;
24
+ get rotationPivotY(): import("@fulate/core").OriginY;
21
25
  getEditorCapability<T>(token: EditorCapabilityToken<T>): T | undefined;
22
26
  getSelectionBehavior(): {
23
- readonly mode: SelectionBehaviorMode.Standard;
24
- readonly dive: SelectionDiveMode.None;
25
- readonly snap: SelectionSnapMode.Enabled;
26
- };
27
- getTransformPolicy(): {
28
- readonly move: true;
29
- readonly resize: "both";
30
- readonly rotate: true;
31
- readonly rotationPivot: "adjustable";
27
+ readonly mode: import("./capability").SelectionBehaviorMode.Standard;
28
+ readonly dive: import("./capability").SelectionDiveMode.None;
29
+ readonly snap: import("./capability").SelectionSnapMode.Enabled;
32
30
  };
31
+ getTransformPolicy(): TransformInteractionPolicy;
33
32
  captureTransformBaseline(_bakeGeometry: boolean): ElementTransformBaseline;
34
33
  resolveTransformChange(baseline: Readonly<ElementTransformBaseline>, intent: Readonly<TransformIntent | ReparentTransformIntent>): readonly import("@fulate/core").OwnerPropertyChange[];
35
34
  getSelectionFrameBounds(): Readonly<Rect> | null;
36
- setOptions(options?: ElementOptionPatch<O>): this;
37
- replacePorts(value: ConnectionPortConfiguration): this;
38
- restorePropertySnapshot(snapshot: Record<string, unknown>): this;
35
+ protected commitConfiguredOptions(options: ElementOptionPatch<O>): void;
39
36
  getWorldSnapPointsView(): readonly PointView[];
40
- paint(ctx?: CanvasRenderingContext2D): void;
37
+ paint(paint: PaintContext): void;
41
38
  /** 绘制宿主本体;`paint()` 随后统一绘制 custom Port decoration。 */
42
- protected paintHost(ctx: CanvasRenderingContext2D): void;
39
+ protected paintHost(paint: PaintContext): void;
43
40
  /** @internal EditorShapeTransform 合并非节点 Port decoration bounds。 */
44
41
  getConnectionPortDecorationWorldBounds(): Bound;
45
- protected onPropertiesChanged(current: P, changes: PropertyChanges): void;
42
+ protected onPropertiesInstalled(current: P, changes: PropertyChanges): void;
46
43
  protected onActivate(root: Root | null, layer: Layer | null): void;
47
44
  protected onDeactivate(root: Root | null, layer: Layer | null): void;
48
45
  private getConnectionPortDecoration;
49
46
  }
50
47
  /** UI shape family 统一合并 custom Port decoration world visual bounds。 */
51
48
  export declare class EditorShapeTransform<E extends EditorShape = EditorShape> extends ShapeTransform<E> {
52
- protected buildWorldVisualBounds(): Bound;
49
+ protected buildWorldVisualBounds(includeShadow?: boolean): Bound;
53
50
  }
@@ -1,8 +1,6 @@
1
1
  import { Element, type ElementOptionPatch, type ElementTransformBaseline, type OwnerPropertyChange, type ReparentTransformIntent, type TransformIntent } from "@fulate/core";
2
- import { type Rect } from "@fulate/share";
2
+ import type { Rect } from "@fulate/share";
3
3
  /** @internal frame-authored provider 共用的纯 resolver。 */
4
4
  export declare function resolveFrameTransformChange(owner: Element, baseline: Readonly<ElementTransformBaseline>, intent: Readonly<TransformIntent | ReparentTransformIntent>): readonly OwnerPropertyChange[];
5
- /** @internal 捕获一次 owner reference;structured ownedState 直接保留原引用。 */
6
- export declare function captureElementTransformBaseline<Owned>(owner: Element, writeMode: "frame-authored" | "authored-geometry" | "pose-authored", ownedState: Owned): ElementTransformBaseline<Owned>;
7
5
  /** @internal Geometry reference 变化时保持当前 world pose 的最小 frame patch。 */
8
6
  export declare function resolveReferenceBoundsPosePatch(owner: Element, readBounds: () => readonly [Readonly<Rect>, Readonly<Rect>], patch?: Readonly<ElementOptionPatch>): Readonly<ElementOptionPatch>;
@@ -0,0 +1,70 @@
1
+ import { VectorPath, VectorPathProperties, VectorPathTransform, type AuthoredSubpath, type ElementOptionPatch, type ElementTransformBaseline, type ElementTransformClass, type Layer, type OwnerPropertyChange, type PaintContext, type PropertyChanges, type ReparentTransformIntent, type Root, type TransformIntent, type VectorPathCommand, type VectorPathGeometry, type VectorPathOption } from "@fulate/core";
2
+ import type { Bound, PointView, Rect } from "@fulate/share";
3
+ import { type EditorCapabilityToken, type PointControlDescriptor, type PointEditRequest, type PointEditTarget, type PointEditingScope, type PointOwnerEdit } from "./editor/capability";
4
+ import { type EditorPivotOptions, type EditorRuntimePatch } from "./editor/properties";
5
+ export interface EditorVectorPathOption<Input = readonly VectorPathCommand[], T = EditorVectorPath<any, any>> extends VectorPathOption<Input, T>, EditorPivotOptions {
6
+ }
7
+ export declare class EditorVectorPathProperties extends VectorPathProperties {
8
+ rotationPivotX: any;
9
+ rotationPivotY: any;
10
+ constructor(options?: EditorVectorPathOption<readonly VectorPathCommand[], any>);
11
+ getImpact(changes: PropertyChanges): number;
12
+ }
13
+ export declare class EditorVectorPathTransform<E extends EditorVectorPath<any, any> = EditorVectorPath> extends VectorPathTransform<E> {
14
+ protected buildWorldVisualBounds(includeShadow?: boolean): Bound;
15
+ }
16
+ /** One Core path owner with the UI's selection, Point, Transform, Snap and Port behavior. */
17
+ export declare class EditorVectorPath<P extends EditorVectorPathProperties = EditorVectorPathProperties, O extends EditorVectorPathOption<unknown, any> = EditorVectorPathOption> extends VectorPath<P, O, EditorRuntimePatch<ElementOptionPatch<O>>> {
18
+ private connectionPortDecoration;
19
+ private worldSnapPointsCache?;
20
+ constructor(options?: NoInfer<O>, properties?: P, Transform?: ElementTransformClass);
21
+ get rotationPivotX(): any;
22
+ get rotationPivotY(): any;
23
+ getEditorCapability<T>(token: EditorCapabilityToken<T>): T | undefined;
24
+ getSelectionBehavior(): {
25
+ readonly mode: import(".").SelectionBehaviorMode.Standard;
26
+ readonly dive: import(".").SelectionDiveMode.None;
27
+ readonly snap: import(".").SelectionSnapMode.Enabled;
28
+ };
29
+ getTransformPolicy(): {
30
+ readonly move: true;
31
+ readonly resize: "both";
32
+ readonly rotate: true;
33
+ readonly rotationPivot: "adjustable";
34
+ };
35
+ getSelectionFrameBounds(): Readonly<Rect> | null;
36
+ resolvePointScope(worldPoint: PointView): {
37
+ readonly kind: "owner";
38
+ };
39
+ hasPointScope(scope: PointEditingScope): scope is {
40
+ readonly kind: "owner";
41
+ };
42
+ hasPointTarget(_scope: PointEditingScope, target: PointEditTarget): boolean;
43
+ getPointControls(_scope: PointEditingScope): readonly PointControlDescriptor[];
44
+ getPointScopeOutline(_scope: PointEditingScope): any;
45
+ resolvePointEdit(request: PointEditRequest): PointOwnerEdit | null;
46
+ private findAnchor;
47
+ private findSegment;
48
+ private ownerPathChange;
49
+ captureTransformBaseline(_bakeGeometry: boolean): {
50
+ reference: import("@fulate/core").ReferenceTransformBaseline;
51
+ ownedState: VectorPathGeometry;
52
+ };
53
+ resolveTransformChange(baseline: Readonly<ElementTransformBaseline<VectorPathGeometry>>, intent: Readonly<TransformIntent | ReparentTransformIntent>): readonly OwnerPropertyChange[];
54
+ protected getMinimumAnchorCount(subpath: AuthoredSubpath): number;
55
+ /** Point pose compensation includes single-anchor layout geometry. */
56
+ protected getPathLayoutBounds(path: VectorPathGeometry): Readonly<Rect> | null;
57
+ /** Transform replaces frame dimensions only when the product has resizable geometry. */
58
+ protected getTransformedPathBounds(path: VectorPathGeometry): Readonly<Rect> | null;
59
+ protected commitConfiguredOptions(options: ElementOptionPatch<O>): void;
60
+ getWorldSnapPointsView(): readonly PointView[];
61
+ paint(paint: PaintContext): void;
62
+ /** 绘制宿主本体;`paint()` 随后统一绘制 custom Port decoration。 */
63
+ protected paintHost(paint: PaintContext): void;
64
+ /** @internal EditorVectorPathTransform 合并非节点 Port decoration bounds。 */
65
+ getConnectionPortDecorationWorldBounds(): Bound;
66
+ protected onPropertiesInstalled(current: P, changes: PropertyChanges): void;
67
+ protected onActivate(root: Root | null, layer: Layer | null): void;
68
+ protected onDeactivate(root: Root | null, layer: Layer | null): void;
69
+ private getConnectionPortDecoration;
70
+ }
@@ -3,5 +3,15 @@ import { type ComputePositionConfig } from "@floating-ui/core";
3
3
  export { flip, offset, shift } from "@floating-ui/core";
4
4
  export type { Placement } from "@floating-ui/core";
5
5
  export type ComputePositionOptions = Omit<ComputePositionConfig, "platform" | "strategy">;
6
- /** Computes world-space coordinates without mutating either element. */
7
- export declare function computePosition(reference: Element, floating: Element, options?: ComputePositionOptions): Promise<import("@floating-ui/core").ComputePositionReturn>;
6
+ /**
7
+ * Reads prepared world geometry; callers await the owning Root before use.
8
+ * Returns parent-space left/top for setOptions({ left: x, top: y }).
9
+ * Middleware dimensions, offsets and middlewareData remain in world space.
10
+ */
11
+ export declare function computePosition(reference: Element, floating: Element, options?: ComputePositionOptions): Promise<{
12
+ x: number;
13
+ y: number;
14
+ placement: import("@floating-ui/utils").Placement;
15
+ strategy: import("@floating-ui/utils").Strategy;
16
+ middlewareData: import("@floating-ui/core").MiddlewareData;
17
+ }>;