The map had one input device. A drag projects a pointer onto the manifest's axis; there was no way to state a value, read one, or withdraw one. Both channels now meet at the same three exits in App.tsx — draftValue() previews, settleValue() commits one undoable command, abandonGesture() puts the settled state back — so nothing about the constraint, the debounce or the previewSeq arbitration is implemented twice. EditSession is untouched: focus and blur land on the gesture boundary that pointerdown and pointerup already used, which is why typing 1.53 is one undo step rather than four. Three rules the two devices do not share: - Live drag values bypass React and write the input's value directly, per direct-edit-client.md §7. A layout effect re-applies them after a mid-drag preview replaces the manifest, and drops the override once the manifest reports the value the drag asked for. - Typed values out of range are refused, not clamped. A pointer cannot state an intent it never reached, so a drag clamps; typed text is an intent, and a clamped typo reads as a plausible value that can go unnoticed. The offered extremes round inward — a real max of 2.925 renders as 2.93 under nearest-rounding, which the range it came from would then reject. - Reset disables the constraint rather than deleting it: validateEditDocument() rejects an operation naming a constraint that is not in the document. This is the one edit a drag cannot express, since a drag can set a value but never withdraw one. Interval editing stays behind intervalEditingSupported, which is still false — compileGeometry() does not read profile.interval, and a control that changes nothing is worse than no control. The conversions are implemented and tested so the row appears when the flag flips. Probing a live manifest turned up a defect that is not from this change and is not fixed here: an edge offset advertises ±2.925 while the solver rejects past about ±1. Evidence is in the task's research/, and the requirement moved to 08-31-constraint-range-validation. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
115 lines
7.0 KiB
Markdown
115 lines
7.0 KiB
Markdown
# 参数面板与数值双向绑定 · 设计
|
||
|
||
> 父任务 `08-26-direct-manipulation-road-editor/design.md` 仍是约束模型、求解边界与 API 合约的权威定义。本文只补充**第二条输入通道**引入的规则,不改变其中任何一条。
|
||
|
||
## 架构定位
|
||
|
||
本任务不触碰服务端。约束模型、求解器、handle manifest、revision 全部原样保留。改动完全落在客户端输入层:
|
||
|
||
```text
|
||
┌─ 拖拽(连续)──→ projectHandleValue() ─┐
|
||
选中道路 → manifest ─┤ ├→ draftFor(handle, value)
|
||
└─ 输入框(离散)→ 解析 + 范围校验 ──────┘ ↓
|
||
PreviewRequester
|
||
(80ms 防抖 + previewSeq 仲裁)
|
||
↓
|
||
EditSession.commit()
|
||
```
|
||
|
||
`draftFor(handle, value)`(`App.tsx:206`)本就是纯函数 `(手柄, 数字) → 草稿`。两条通道的唯一区别是**如何产生那个数字**以及**何时闭合 gesture**,汇合点之后完全一致。
|
||
|
||
## 不变量:取值范围
|
||
|
||
> **约束值永不超出 manifest 声明的 `[min, max]`。**
|
||
>
|
||
> - **连续输入**(拖拽、滑杆)在极限处**停止移动**。ghost 与手柄按夹后的值绘制,绝不跟随越界的光标。
|
||
> - **离散输入**(数值框)**拒绝接受**越界值:标记非法、不发预览、不进 undo 栈、保留最后一个有效预览。范围提示可一键填入极值。
|
||
|
||
这是**一条规则的两种设备表达**,不是两套策略。
|
||
|
||
连续设备没有表达"拒绝"的手段——停止移动就是它的拒绝,而且是当场可见的:手柄停住、光标继续走。用户不会形成"我设成了 -24.1"这个信念。夹值理由见 `projection.ts:75` 的注释(ol-ext 探针把手柄拖到 -24.1m 而约束夹在 -5.4m,手柄指向一个不可能存在的路形)。
|
||
|
||
离散设备则相反:数字已经键入、Tab 已经按下,此时夹值是**事后篡改**。且失败模式不对称——
|
||
|
||
| 用户意图 | 夹值 | 拒绝 |
|
||
| --- | --- | --- |
|
||
| 打错(想输 2.4,输成 24) | 变成 5.4,看起来合理,可能永不被发现 | 立即可见 |
|
||
| 想拉满 | 如愿 | 多一步(或点范围提示一键填入) |
|
||
|
||
拒绝错了只损失一次击键;夹值错了会把一个**看起来正常的错误值**送进下游编译与仿真。故取拒绝。
|
||
|
||
## 值的所有权
|
||
|
||
任一时刻,一个参数的显示值来源是**唯一**且由聚焦状态决定的:
|
||
|
||
| 状态 | 显示值 | 理由 |
|
||
| --- | --- | --- |
|
||
| 未聚焦 | `handle.value.current` | 服务端权威回显 |
|
||
| 聚焦中 | 本地文本 draft | 保留 `1.`、`-`、空串等中间态 |
|
||
|
||
必须如此的原因:`App.tsx:197` 在每次预览结算时 `setManifest(response.handles)` 整体替换 manifest。受控输入若直接绑定 `value.current`,键入 `1.` 触发的防抖预览返回后会把输入框冲成 `1`,小数点消失。
|
||
|
||
失焦即清 draft。此时 `value.current` 必然等于刚提交的值——因为 `direct-edit-solver.js:136` 的 `numericValue()` 直接回显约束里的数字,服务端不改写。**故不存在"请求值 vs 求解值"的双显示需求。**
|
||
|
||
> 该结论依赖 solver 当前行为。若日后改为回写求解结果,本节规则失效,需同步重审。
|
||
|
||
## gesture 边界
|
||
|
||
`gestureIdentity()` 是懒创建的 operationId 单例,`commitGesture()` 释放它。它抽象的是"一段有始有终的操作",与指针无绑定关系,因此可原样承载键盘输入:
|
||
|
||
| 阶段 | 拖拽 | 输入框 | 动作 |
|
||
| --- | --- | --- | --- |
|
||
| 开始 | `pointerdown` | `focus` | 铸 operationId |
|
||
| 进行 | `pointermove` | `onChange` | `requester.schedule()`,**不 commit** |
|
||
| 结束 | `pointerup` | `blur` / `Enter` | `requester.flush()` + `commitGesture()` |
|
||
| 放弃 | — | `Escape` | 回滚显示值 + `requester.cancel()` |
|
||
|
||
`EditSession` 与 `gestureIdentity()` 无需改动。输入 `1.53` 产生一步 undo,而非四步。
|
||
|
||
滑杆(若实现)的 pointerdown/up 天然落在此表内,不引入新分支。
|
||
|
||
**保存路径**:`saveDirectEdits()` 必须在入口强制结算未闭合的 gesture。DOM 中 blur 先于 click 触发,直接点"保存"能赶上,但该顺序过于脆弱,不作为正确性依赖。
|
||
|
||
## 区间的单位分层
|
||
|
||
父 `design.md` 的坐标分层表规定持久化层只有米与归一化 station。显示层不受该表约束。
|
||
|
||
| 层 | 单位 |
|
||
| --- | --- |
|
||
| 持久化 / 传输 | `station` (0..1) |
|
||
| 面板显示与输入 | 米(`station × roadLengthMeters`) |
|
||
|
||
**只在用户实际编辑时换算**,不在每次渲染时做 米→station→米 的往返,否则四舍五入会让数字自行漂移。`roadLengthMeters` 取自 `IntervalRangeHandle`,与 range 手柄同源。
|
||
|
||
区间由整条道路共享(`rangeDraftFor` 重锚该路全部约束),故在面板中**每条路一行**,不随手柄重复。
|
||
|
||
## 面板可表达而拖拽不能表达的操作
|
||
|
||
`value.current` 在无约束时回落基线(外缘偏移基线为 0),因此"未修改"与"显式设为 0"数值完全相同。`handle.constraintId` 仅在约束存在时出现,客户端据此区分。
|
||
|
||
由此得到一个拖拽结构上无法提供的能力:**删除约束**。拖拽只能设值,不能移除。面板每行提供"重置",删除该约束并使该行回到未修改态。
|
||
|
||
这是参数面板的实质增量,而非拖拽的镜像显示。
|
||
|
||
## 渲染性能
|
||
|
||
`handleDragEvent` 每次 mousemove 触发,而 `App.tsx` 是单个 974 行组件。拖拽值回流面板必须经 rAF 节流,不得直接 `setState`。
|
||
|
||
节流有效性需在扩大面板规模前验证——手柄当前仅 5~6 个,问题不会自行显现。
|
||
|
||
## 边界
|
||
|
||
- 面板不得成为第二套几何算法或第二个值的真相来源。范围、位置、`affects`、可编辑性一律只来自服务端 manifest。
|
||
- 面板只呈现主地图拥有的 kind。路口 shape 三 kind 仍属 `JunctionTools`;保留区内手柄呈禁用态并显示 `disabledReason`。
|
||
- 不新增约束 kind,不改动求解器。
|
||
|
||
## 已知缺口
|
||
|
||
服务端 `applyConstraint` 只校验 `Number.isFinite` 与非负,**不校验 manifest 的 `min`/`max`**。今日范围仅由客户端 `projectHandleValue` 的夹值实际约束。
|
||
|
||
外缘偏移的范围随道路宽度浮动(`±Math.max(0.1, width * 0.45)`),因此保存时合法的值可能在后续几何变化后越界。此类越界发生在保存之后的求解期,**客户端结构上无法拦截**。
|
||
|
||
父 `design.md` 已为 `boundaryIndex` 定义同类规则——"重放时若车道数变化导致越界,该约束转 `stale`,不做近似映射"——数值范围越界应同等处理。
|
||
|
||
属重放正确性,不属本任务;独立成任务。本任务的客户端校验不因该缺口存在而降级:范围在哪定义就在哪拦,并避免一次注定被拒的求解。
|