diff --git a/.trellis/spec/frontend/direct-edit-client.md b/.trellis/spec/frontend/direct-edit-client.md index 4bde685..24d02a7 100644 --- a/.trellis/spec/frontend/direct-edit-client.md +++ b/.trellis/spec/frontend/direct-edit-client.md @@ -152,6 +152,84 @@ say so. --- +## 11. Two input channels, three shared exits + +A value can come from a drag or from a number field. They differ only in how the +scalar is produced and when the gesture closes; everything downstream is shared: + +| Exit | Meaning | +| --- | --- | +| `draftValue(handle, value)` | preview, do not commit | +| `settleValue(handle, value)` | one undoable command, or abandon if it drafts nothing | +| `abandonGesture()` | release the id, clear live overrides, re-preview the settled state | + +`EditSession` needs no change to accept a second channel: `gestureIdentity()` is +minted lazily by the first draft and released by `commitGesture()`, so `focus` / +`blur` land on the same boundary `pointerdown` / `pointerup` already used. That is +what makes typing `1.53` one undo step instead of four. + +**Forbidden**: a second preview path, debounce, or undo stack per input device. + +--- + +## 12. Continuous input clamps; discrete input refuses + +The invariant is shared — a constraint value never leaves `[min, max]` — but the +two devices express it differently. + +- A drag **clamps**. A pointer cannot state an intent it never reached, and the + handle has to stay on a road shape that can exist (§3). The clamp is visible in + the moment: the handle stops while the cursor keeps going. +- A number field **refuses**: mark it invalid, send no preview, add no undo step, + keep the last valid preview. Typed text *is* an intent, so rewriting it is a + retroactive edit — and the failure modes are asymmetric. A clamped typo (24 + becoming 5.4) reads as a plausible value and can go unnoticed; a refusal cannot. + +Offer the extremes as one click, but round them **inward**: a real max of `2.925` +renders as `2.93` under nearest-rounding, which the range it came from rejects. +`formatBoundInward()` exists for this. + +**Mistake made**: the first draft of the panel displayed and filled +`formatParameterValue(min)`, which produced a value its own range check refused. + +--- + +## 13. A field being typed in owns its own text + +Every settled preview replaces the manifest, so a controlled input bound to +`handle.value.current` is rewritten mid-keystroke: typing `1.` fires a preview for +`1`, and the response resets the field to `1`, dropping the decimal point. + +The field therefore holds local text while focused and follows the manifest only +when it is not: + +```ts +value={text ?? formatParameterValue(handle.value.current)} +``` + +There is no second number to reconcile: `numericValue()` in the solver reads the +constraint back out, so `value.current` is the request echoed, never a solved +substitute. Seed the local text from what is on screen at focus, not from the +manifest — after a drag the row can legitimately be ahead of the last settled +preview. + +--- + +## 14. Reset disables the constraint; it does not delete it + +`validateEditDocument()` rejects an operation whose `constraintIds` name a +constraint that is not in the document, so removing one would mean recording an +operation about nothing. Setting `enabled: false` is what design.md already +sanctions for undoing saved work, and `constraintFor()` skips disabled +constraints, so the handle comes back without a `constraintId` and the row reports +itself unmodified again. + +This is the one edit a drag cannot express: a drag can set a value, never withdraw +one. `handle.constraintId` — present only when a constraint exists — is also how +"untouched" is told apart from "explicitly set to the baseline number". + +--- + ## Checklist before committing edit-client changes - [ ] No baseline source is written @@ -162,3 +240,7 @@ say so. - [ ] No geometry or OL reads inside a `setState` updater - [ ] No per-`pointermove` React state updates - [ ] Flag off ⇒ no sources, no layers, no interactions, no requests +- [ ] Every input channel meets at the shared exits, not a parallel path +- [ ] Displayed bounds round inward, so an offered extreme is accepted +- [ ] A focused field is not rewritten by an arriving preview +