docs: record the two-channel input rules
Four things the parameter panel settled that the next input channel should not have to rediscover: where the channels meet, why a drag clamps while a field refuses, why a focused field owns its own text, and why reset disables rather than deletes. The clamp/refuse split is the one most likely to be reported as an inconsistency. It is one invariant with two honest expressions — a pointer cannot state an intent it never reached, so it stops; typed text is an intent, so rewriting it hides a typo behind a plausible number. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
6663c289e7
commit
2ef24539f9
1 file changed
+82
@@ -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
|
||||
|
||||
Reference in new issue
Block a user