taet-ui 0.6.0-rc.6 → 0.6.0-rc.7

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 (52) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +5 -4
  3. package/docs/AI_CONTEXT.md +1 -1
  4. package/docs/EDITOR_EDITING_CONTRACT.md +229 -0
  5. package/docs/GRID_COMMON_CONTRACT.md +16 -0
  6. package/docs/GRID_EDITOR_MATRIX.md +79 -0
  7. package/docs/GRID_EDITOR_TYPES.md +157 -4
  8. package/docs/INPUT_TESTING.md +330 -0
  9. package/docs/INPUT_TYPES.md +331 -3
  10. package/docs/MUTATIONS.md +24 -0
  11. package/docs/NATIVE_ACCEPTANCE.md +44 -4
  12. package/docs/RELEASE.md +1 -1
  13. package/docs/STABLE_API.md +6 -1
  14. package/docs/TAET_MIGRATION.md +1 -1
  15. package/docs/TIERS.md +5 -0
  16. package/docs/VERIFICATION.md +875 -0
  17. package/docs/VERSIONING.md +1 -1
  18. package/docs/src/pages/InputControls.pages.js +37 -13
  19. package/examples/ai-recipes/13-custom-editor.js +51 -0
  20. package/examples/ai-recipes/README.md +7 -1
  21. package/package.json +5 -2
  22. package/provenance/grid-candidate.json +14 -9
  23. package/src/components/index.d.ts +1 -1
  24. package/src/core/validationRevision.js +3 -0
  25. package/src/ui/CodeBlock.js +7 -0
  26. package/src/ui/DateTimeInput.js +174 -16
  27. package/src/ui/EditorControl.d.ts +4 -1
  28. package/src/ui/EditorControl.js +8 -0
  29. package/src/ui/Form.js +304 -68
  30. package/src/ui/Grid.js +57 -12
  31. package/src/ui/GridEditors.d.ts +3 -0
  32. package/src/ui/GridEditors.js +53 -16
  33. package/src/ui/MultiSelectDropDown.js +1 -0
  34. package/src/ui/NumberInput.d.ts +21 -0
  35. package/src/ui/NumberInput.js +231 -1
  36. package/src/ui/OptionList.js +6 -0
  37. package/src/ui/Panel.js +3 -0
  38. package/src/ui/PropertyGrid.js +100 -41
  39. package/src/ui/SelectInput.js +1 -0
  40. package/src/ui/TextArea.js +2 -0
  41. package/src/ui/TextField.js +496 -16
  42. package/src/ui/TextInput.d.ts +5 -1
  43. package/src/ui/TreeGrid.js +58 -7
  44. package/src/ui/collection-contracts.d.ts +7 -1
  45. package/src/ui/container-contracts.d.ts +23 -2
  46. package/src/ui/display-contracts.d.ts +2 -1
  47. package/src/ui/experimental.d.ts +2 -1
  48. package/src/ui/grid-editor-contracts.d.ts +20 -2
  49. package/src/ui/grid-editor-options.d.ts +3 -0
  50. package/src/ui/gridEditorValidation.js +134 -0
  51. package/src/ui/index.d.ts +2 -1
  52. package/src/ui/inputs.d.ts +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,29 @@
1
1
  # Tæt UI changes
2
2
 
3
+ ## 0.6.0-rc.7 - editing contracts and validation currentness, 2026-11-09
4
+
5
+ - **Breaking for independent custom editors:** strict Form, Grid/TreeGrid and
6
+ PropertyGrid validation/commit requires getValidationRevision() for independently
7
+ owned value/candidate state. Ordinary built-in and authoritative EditorControl
8
+ usage keeps automatic tracking. Existing value/method return types are unchanged.
9
+ See [field migration](docs/INPUT_TYPES.md#custom-fields-in-strict-form-validation)
10
+ and [cell-editor migration](docs/GRID_EDITOR_TYPES.md#validation-currentness-and-custom-revisions).
11
+ - Reject accepted/candidate changes during validation and final reads, including
12
+ silent ABA, without rollback or automatic retry. Grid/TreeGrid's trusted
13
+ beforeCellChange override remains; PropertyGrid also checks after its veto hook,
14
+ restoring the old inline display only when an ordinary veto is still current.
15
+ - Add PropertyGrid editReject for validation-revision/validation-stale refusals.
16
+ Ordinary invalid-value behavior is unchanged; silent attempts suppress the event.
17
+ See [PropertyGrid ownership and event details](docs/GRID_EDITOR_TYPES.md#propertygrid-staged-and-inline-ownership).
18
+
19
+ - Add opt-in NumberInput updateMode: 'commit', explicit commitInput/cancelInput, pending-draft state and owner prepareCommit integration. Live remains the default; getters, validation and destruction do not implicitly save drafts.
20
+ - Add opt-in positional TextInput/TextField maskMode: 'slots' alongside the existing compact mode. Preserve holes through raw/formatted serialization and owner roundtrips, with a DOM-only empty scaffold and bounded control-local undo/redo.
21
+ - Correct compact-mask caret, selection, deletion and history; reject mask/date-time edits that would silently truncate untouched suffixes. Preserve incomplete TimeInput text through passive formatting and avoid fabricated picker selections.
22
+ - Keep TextArea composing-key guards, expand keyboard/composition and isolated-clipboard regression coverage, and ship a checked custom EditorControl recipe and normative editing contract. Synthetic composition and in-memory clipboard tests do not certify native OS input.
23
+ - Remove the source-provenance script's Git safe.directory override. Git ownership checks remain active; unavailable metadata is reported honestly.
24
+ - Preserve zero runtime dependencies and API maturity boundaries. Strict Form currentness adds measurable cost for large forms; measured limits and native acceptance gaps remain documented in VERIFICATION.md.
25
+ - Target npm next without promoting latest or changing previously published versions.
26
+
3
27
  ## 0.6.0-rc.6 - NumberInput decimal-entry fix, 2026-11-08
4
28
 
5
29
  - Preserve numerically equivalent intermediate text such as `1.` and `1.0` during user input, allowing decimals such as `1.05` to be typed character by character.
package/README.md CHANGED
@@ -4,10 +4,11 @@ Compact desktop UI controls for embedded WebViews. Build screens with live
4
4
  JavaScript objects, explicit ownership, events, commands and data models.
5
5
  No JSX, virtual DOM, runtime npm dependencies or CDN.
6
6
 
7
- **0.6.0-rc.6 is a pre-1.0 release candidate; published rc.3, rc.4 and rc.5 artifacts remain unchanged.** Grid/TreeGrid and Advanced remain experimental.
7
+ **0.6.0-rc.7 is a pre-1.0 release candidate; previously published artifacts remain unchanged.** Grid/TreeGrid and Advanced remain experimental.
8
+ Independent custom field/cell editors now require `getValidationRevision()` for strict owner validation. See the [rc.7 migration notes](CHANGELOG.md) and [editing contract](docs/EDITOR_EDITING_CONTRACT.md).
8
9
  Source packages and standalone WebView ZIPs are separate delivery choices.
9
10
  The npm preview channel uses `next`: `npm install taet-ui@next`; publication
10
- status is recorded in the matching GitHub prerelease notes.
11
+ status is available in the [npm version list](https://www.npmjs.com/package/taet-ui?activeTab=versions).
11
12
 
12
13
  Display name: **Tæt UI**. Package and technical names: **taet-ui**.
13
14
  Repository: [edward-ap/taet-ui](https://github.com/edward-ap/taet-ui).
@@ -137,8 +138,8 @@ the maintainer exercised the native Rust echo. See the example notes for the
137
138
  difference between that smoke check and full native acceptance.
138
139
 
139
140
  For TypeScript or resolver-based apps, `npm pack --pack-destination ..` creates
140
- the local `taet-ui-0.6.0-rc.6.tgz`. Install that file in your app with
141
- `npm install ../taet-ui-0.6.0-rc.6.tgz`. Bare package names need a resolver or
141
+ the local `taet-ui-0.6.0-rc.7.tgz`. Install that file in your app with
142
+ `npm install ../taet-ui-0.6.0-rc.7.tgz`. Bare package names need a resolver or
142
143
  browser import map; installing a tarball does not create native browser URLs.
143
144
 
144
145
  | Import | Scope |
@@ -1,6 +1,6 @@
1
1
  # Tæt UI: start here
2
2
 
3
- 0.6.0-rc.6 is a dependency-free desktop/WebView preview.
3
+ 0.6.0-rc.7 is a dependency-free desktop/WebView preview.
4
4
 
5
5
  1. Read [LLM_GUIDE](LLM_GUIDE.md), then one [AI_MAP](AI_MAP.md) row.
6
6
  2. Read its exact public .d.ts and one recipe before guessing a method.
@@ -0,0 +1,229 @@
1
+ # Editor editing contract
2
+
3
+ This is the short normative center for current input/owner behavior. **Must** and
4
+ **must not** describe consumer and adapter obligations. Current guarantees and
5
+ remaining policy choices are identified separately. Exact signatures remain in
6
+ [EditorControl](../src/ui/EditorControl.d.ts),
7
+ [NumberInput](../src/ui/NumberInput.d.ts), [Form](../src/ui/container-contracts.d.ts)
8
+ and [cell editors](../src/ui/grid-editor-contracts.d.ts).
9
+
10
+ ## 1. Name the value and its owner
11
+
12
+ - **Native edit state** is DOM text, selection and composition state. It need not
13
+ equal public value or even reveal the browser's visible incomplete buffer.
14
+ - **Accepted control value** is value.get(). Live editors update it during input;
15
+ commit-mode NumberInput keeps its last committed number/null until completion.
16
+ Its pending native draft is separate; hasPendingInput()/draftChange expose only
17
+ their declared information. Raw/display getters still describe accepted value.
18
+ - **Popup pending value** is a picker's temporary selection/preview before OK.
19
+ Time/DateTime picker staging is not a generic deferred-input API. Direct typing
20
+ remains live. Picker Cancel discards its preview, not earlier accepted typing.
21
+ - **Owner/session value** is the live editor's local value during a staged Grid,
22
+ TreeGrid or PropertyGrid edit. **Stored value** is the row/property written by
23
+ that owner. They can differ even after the numeric field commits on blur.
24
+ Form.value.get() instead collects current fields; it is not a saved snapshot.
25
+
26
+ Consumers must not substitute DOM text, popup preview or a cell draft for stored
27
+ application data. For example, numeric DOM 1.0 can accompany accepted number 1;
28
+ TimeInput text 1: remains partial through passive blur/refresh, without invented
29
+ AM. An explicit picker/step choice may complete it. Slots value __-1234 retains
30
+ holes when serialized; a wholly empty focused scaffold is DOM-only, with public
31
+ value/raw/display all ''. See [component details](INPUT_TYPES.md).
32
+
33
+ ## 2. Read, validate, complete, cancel
34
+
35
+ Getters must not complete drafts. validate() checks synchronously without
36
+ committing; it may update error UI and dispatch validate. It is not side-effect-free.
37
+ In commit-mode NumberInput it checks the normalized pending candidate; otherwise
38
+ it checks accepted value. isValid() invokes validation, not a cached boolean.
39
+
40
+ Among built-in inputs, only NumberInput offers updateMode: 'commit', commitInput(),
41
+ cancelInput() and hasPendingInput(). commitInput() normalizes acceptable numeric
42
+ text and completes the field; it does not enforce application validators on valid
43
+ numeric text. Invalid native input is rejected rather than treated as empty null.
44
+ No pending draft means successful unchanged completion. cancelInput() restores
45
+ accepted display without undoing a completed write. API set/clear/reset replace
46
+ its pending draft, including silent/equal writes; refresh retains that draft.
47
+
48
+ Native required/range/step validity and application validators are separate.
49
+ required:true installs no application rule; required() tests nonempty value, not
50
+ mask/time completeness. A slots scaffold uses owned native customError, not
51
+ valueMissing. NumberInput can accept a fraction while native stepMismatch is true.
52
+ Consumers must choose explicit completeness/range rules for owner saves.
53
+
54
+ Destroy must release owned editing resources, discard pending input and stop
55
+ later phases; it must not save a draft. Base field value reads retain last value
56
+ but mutations/validation reject after destruction. Numeric commitInput() instead
57
+ returns destroyed, cancelInput() returns false; a destroyed ControlCellEditor
58
+ rejects its getters too. These are distinct APIs, not interchangeable cleanup hooks.
59
+
60
+ ## 3. Operation outcome is not diagnostic text
61
+
62
+ Distinguish **completed change**, **unchanged success**, **rejection** and
63
+ **interruption**.
64
+ These are explanatory categories, not a new result enum. Existing boolean field
65
+ writes conflate unchanged/veto/rejection as false; owner booleans are not a common
66
+ transaction result. Do not invent status fields on them.
67
+
68
+ NumberInputCommitResult supplies ok, changed, status and current accepted value.
69
+ Only committed/unchanged are ok. invalid/vetoed/readonly/disabled reject;
70
+ destroyed/superseded interrupt. changed can be true when a later callback
71
+ interrupts an already accepted write. Consumers continuing an owner save must
72
+ check ok, not changed. No status rolls back callback effects or completed writes.
73
+
74
+ An explicit validation ok:false must survive independently of errors. An
75
+ interrupted result can be { ok: false, errors: [] }; warnings alone need not fail.
76
+ Never infer success from an empty message list or fabricate an interruption error.
77
+ Form also rejects error-severity diagnostics even if a child reports ok:true.
78
+
79
+ ### Implemented Form corrections
80
+
81
+ Form.validate() must retain any child result.ok === false alongside severity-based
82
+ error aggregation, even with no diagnostics. It must not promote an interrupted
83
+ child validation to success. Form.submit() therefore stops when a commit-mode
84
+ number's validate listener silently replaces 1 with 99: that field reports false
85
+ although errors is empty. The replacement 99 remains accepted; there is no rollback.
86
+ Tracked cross-field changes now also refuse Form.validate()/isValid()/submit():
87
+ a=1 passes <=10, then a later field or Form validate listener sets a=99 silently.
88
+ The current attempt fails; 99 remains. A later explicit submit validates again,
89
+ with no automatic retry or rollback. The currentness scope is below.
90
+
91
+ Teardown during Form's own validate dispatch returns a new ok:false result with
92
+ the captured value/errors and no later validationFail. An emitted result is not
93
+ retroactively mutated; its captured listeners may finish. Use the returned result,
94
+ not an earlier event snapshot, to decide whether validation completed.
95
+
96
+ ## 4. Owner preparation and currentness
97
+
98
+ For staged Grid/TreeGrid/PropertyGrid commits, the order is optional
99
+ prepareCommit -> validate -> getValue -> owner veto/write -> completion.
100
+ ControlCellEditor.prepareCommit forwards to optional control.commitInput, otherwise
101
+ succeeds. Custom adapters must not hide completion in getters, validation or destroy.
102
+ A failed prepare/validation blocks the owner write. Field-only blur never saves a
103
+ Grid/TreeGrid row. Owner cancel discards its session, leaving stored value intact.
104
+ PropertyGrid inline controls instead start an attempt on an ordinary control
105
+ change. Stale validation/final-read work leaves callback state editable without
106
+ an owner property write. Only a still-current ordinary inline veto silently
107
+ restores the old field value; a newer callback value/candidate is not rolled back.
108
+
109
+ Form.submit() prepares pending fields (including nested forms), then beforeSubmit,
110
+ validation and submit/afterSubmit. Preparation can commit an early field before a
111
+ later field fails or beforeSubmit vetoes. There is no all-or-nothing rollback.
112
+ Submission itself is notification, not persistence to an external service. Form
113
+ validates flattened leaf fields; outer validation does not recursively dispatch
114
+ each nested Form's validate event.
115
+
116
+ Currentness is scoped, not global. Commit-mode NumberInput uses an internal input
117
+ revision across input/API replacement/cancel/destroy and callback boundaries;
118
+ stale validate/commit work cannot report success or continue its later phases.
119
+ Grid/TreeGrid capture editor/control revisions after preparation and check them
120
+ before/after validation and after final getValue(), alongside session/record/column
121
+ and lifetime guards. Accepted or pending-candidate changes, including silent ABA,
122
+ refuse this commit without rollback/retry. A surviving mounted session retains
123
+ callback changes for another explicit attempt; temporary clipboard/toggle editors
124
+ are still destroyed. The trusted beforeCellChange override follows these value
125
+ checks and is not revalidated. PropertyGrid staged/inline attempts use the same
126
+ revision protocol and also check after beforePropertyChange: it is a veto hook,
127
+ not a trusted newValue override. They retain the current editor after refusal
128
+ unless a callback removed it. Inline retry requires another ordinary control
129
+ change; commitEdit is the staged-session path. Their session/row/state checks
130
+ and reentry guards remain scoped to the affected owner.
131
+ Form captures participant identity/key/parent/value API and supported container
132
+ membership revisions. Built-in accepted writes are tracked, including silent
133
+ A -> B -> A changes; commit-mode numeric input revisions also cover changing or
134
+ cancelling a pending candidate. It checks currentness between field validations,
135
+ after Form validation callbacks and before emitting the submit payload. Submit
136
+ captures its validation boundary after preparation/beforeSubmit and retains the
137
+ public validate() call. Recursive submit and unresolved pending input still block.
138
+ Recursive same-Form validation refuses without field reads/events. During custom
139
+ revision lookup/read, captured nested Forms are guarded too and submit refuses
140
+ before preparing drafts. Independent Forms remain available; these guards do not
141
+ invalidate an otherwise unchanged outer validation.
142
+ Structural ABA tracking covers supported Panel/Form membership APIs only, whereas
143
+ parent/key/value API identities are checked at boundaries and do not cover direct
144
+ name/value API replace-and-restore or private mutations.
145
+
146
+ These are bounded checks of tracked values and participants, not frozen data,
147
+ rollback or global transaction isolation. The cooperative custom hook below does
148
+ not turn standalone plain/live validation into a universally guarded operation.
149
+
150
+ See [owner protocol and lifecycle](GRID_EDITOR_TYPES.md) and
151
+ [Form mutation rules](MUTATIONS.md) for the exact supported paths.
152
+
153
+ ## 5. Events, silence and reentry
154
+
155
+ Ordinary accepted field writes dispatch beforeChange (cancellable), write/sync,
156
+ change, afterChange and conditional dirtyChange. Field beforeChange.newValue is
157
+ a readonly snapshot, not a value override. Silent supported mutations still
158
+ synchronize value/UI/dirty state, but skip semantic value events including veto
159
+ phases. Silent owner save still prepares and validates; validation callbacks run.
160
+
161
+ After a callback destroys/cancels/replaces the relevant guarded owner/session,
162
+ later stale phases must stop. A write already accepted stays accepted. EventBus
163
+ uses a snapshot for the current dispatch: remaining listeners in that phase can
164
+ still run. Applications must not assume that destroy retracts callbacks already
165
+ being dispatched, or that exceptions roll back their effects. Owners release
166
+ owned controls, popup DOM/listeners and session resources; borrowed application
167
+ services remain application-owned. Replacement sessions must survive old cleanup.
168
+
169
+ ## 6. Strict custom fields and cell editors
170
+
171
+ Form.validate()/isValid()/submit(), Grid/TreeGrid commit paths and PropertyGrid
172
+ staged/inline propagation require observable currentness for validated values.
173
+ The recommended path is an EditorControl subclass using its inherited accepted
174
+ value pipeline. A widget displays that value and sends edits through value.set;
175
+ it must not become an untracked source polled by _getValue(). Built-in tracking
176
+ then works without adding a public method to EditorControl.
177
+
178
+ An independent custom field must provide getValidationRevision(): number | bigint | symbol.
179
+ The getter must be pure, synchronous and stable between writes. Advance a stored
180
+ token at every accepted-value or validation-candidate change, before rendering or
181
+ post-write callbacks, including silent A -> B -> A changes. Use a nonnegative safe
182
+ integer/increasing nonnegative bigint, or a fresh symbol that is never reused.
183
+ Do not return a value hash or create a symbol during reads. Revision/value getters
184
+ and validation must not commit hidden drafts; completion remains explicit.
185
+
186
+ Missing, noncallable, invalid, unstable or throwing revision readers, and observed
187
+ counter decreases, fail closed. Form reports code validationRevision with control
188
+ and path. Tables reject with reason validation-revision and validation errors
189
+ identifying the offending editor/control through source. A valid token change
190
+ instead interrupts the attempt; tables use validation-stale with errors:[], not
191
+ a fabricated diagnostic. Callback writes remain and retry is explicit. An explicit
192
+ public hook adds checks and cannot bypass built-in currentness checks.
193
+
194
+ The structural FormField value API is unchanged, including custom void-returning
195
+ setters. getFields() still returns FormField[], not a claim that every field has
196
+ a public hook. Strict validation rejects legacy untracked fields at runtime.
197
+ Independent CellEditor/GridValueControl state uses the same public hook, optional
198
+ in declarations but required for strict runtime commits. ControlCellEditor retains
199
+ its owned control's automatic tracking without a new public built-in method.
200
+ Existing method/value return types are unchanged. See
201
+ [migration and checked recipe](INPUT_TYPES.md#custom-fields-in-strict-form-validation)
202
+ and [table revision details](GRID_EDITOR_TYPES.md#validation-currentness-and-custom-revisions).
203
+
204
+ ## 7. Remaining policy and evidence boundaries
205
+
206
+ - **Nested live writes:** plain/live beforeChange may perform a nested value.set
207
+ and then let the outer write win. Commit-mode NumberInput supersedes the outer
208
+ attempt instead. Should other editors adopt that policy? No unification is
209
+ implied by this contract or by specialized caret/composition synchronization.
210
+ - **Grid value override:** beforeCellChange may replace a validated newValue as a
211
+ trusted application hook. Should the override be revalidated? Today it is not.
212
+ Field beforeChange and PropertyGrid beforePropertyChange are not this override API.
213
+
214
+ Inheritance or hook presence alone does not prove implementation correctness.
215
+ Protected getter/setter/validation-value overrides must preserve the inherited
216
+ contract or report independent changes through a complete hook. Mutable aliases,
217
+ validator closures/context, rule/configuration changes and external choice data
218
+ are not automatically observed. A dishonest constant token or hidden change and
219
+ restore cannot be certified. Custom getters must remain pure; own/copy immutable
220
+ domain values where needed and keep validation callbacks read-only when possible.
221
+
222
+ Shared currentness tracking does not create an EditorTransactionManager or a
223
+ common public operation result. Parsing, caret, mask history and popup staging
224
+ remain specialized; reuse requires evidence from the component adapters.
225
+
226
+ [Test strategy](INPUT_TESTING.md) distinguishes model, real-browser gesture and
227
+ synthetic-event evidence; [verification](VERIFICATION.md) records actual runs.
228
+ Nothing here certifies real IME, macOS/native hosts, native context-menu history
229
+ or the system clipboard.
@@ -55,6 +55,22 @@ change schema/projection or open another editor; the old attempt stops and canno
55
55
  overwrite the newer editor or keyboard target. Unrelated background updates preserve
56
56
  the live draft; removal/hiding/replacement of its target cancels it.
57
57
 
58
+ ### Pending numeric input
59
+
60
+ The number factory's `updateMode: 'commit'` is opt-in; its default remains live.
61
+ Both tables explicitly call an optional editor `prepareCommit` before validation
62
+ and value readback. A failed preparation emits `editReject` with reason
63
+ `prepare-commit` (unless silent) and keeps the current editor without a row write.
64
+ Callbacks that replace/destroy the session stop subsequent stale phases.
65
+
66
+ This separates the native draft, committed editor value and stored row value.
67
+ Blur completes only the numeric editor value. Enter/Tab or commitEdit completes
68
+ the owner write; Escape/cancel/teardown never saves the row. A later validator or
69
+ beforeCellChange veto does not undo a field commit already completed during
70
+ preparation. Pending disabled/readonly input blocks preparation. Getters,
71
+ validation and editor destruction never implicitly complete a draft. See the
72
+ [typed protocol](GRID_EDITOR_TYPES.md#explicit-draft-preparation).
73
+
58
74
  ## Sort, conditions and schema
59
75
 
60
76
  Both expose getSortModel(): Rule[]. Legacy getSortState remains first-rule/null
@@ -1,5 +1,8 @@
1
1
  # Existing table editor matrix
2
2
 
3
+ The short [editing contract](EDITOR_EDITING_CONTRACT.md) defines shared vocabulary
4
+ and owner boundaries without making all controls deferred or transactional.
5
+
3
6
  Grid and TreeGrid remain experimental. This page describes the existing factories
4
7
  in `taet-ui/grid/editors`; it does not certify every standalone input as a cell
5
8
  editor. [Live example](../examples/grid-editors/README.md) / [recipe11](../examples/ai-recipes/11-grid-editor-matrix.js).
@@ -55,6 +58,40 @@ columns/records prevent activation. Control-level disabled/readOnly options reta
55
58
  the standalone input behavior; they do not redefine column editability. Use the
56
59
  column rule or disable the table for cells that should not start editing.
57
60
 
61
+ ## Opt-in deferred numeric values
62
+
63
+ Number factories accept `updateMode: 'commit'`; omission remains live. Native text
64
+ then stays pending until the numeric field commits, with integer/range/precision
65
+ normalization deferred to that commit. Use `clamp:false` plus validators when an
66
+ out-of-range completed number should be rejected instead of clamped. The existing
67
+ matrix demo remains live and is not a commit-mode demonstration.
68
+
69
+ Grid/TreeGrid prepare the field before validating and reading it for a row commit.
70
+ Enter/Tab follow table policy; Escape discards the session. Blur commits only the
71
+ field, never the row. Validation or veto can reject the owner write even after the
72
+ local field committed. Disabled/readonly pending input is retained and blocks
73
+ preparation rather than saving stale data. See [draft preparation](GRID_EDITOR_TYPES.md#explicit-draft-preparation)
74
+ and [numeric API](INPUT_TYPES.md#numberinput). This adds no multiline, locale or
75
+ real-IME guarantee to the editor matrix.
76
+
77
+ ## Validation-currentness boundary
78
+
79
+ Built-in factories retain automatic value/candidate tracking. Independent custom
80
+ CellEditor/GridValueControl state needs getValidationRevision(); its optional type
81
+ annotation does not waive the runtime requirement. After preparation, a value or
82
+ draft change during validation/final read rejects commit without an owner row write,
83
+ rollback or retry. The surviving session keeps callback changes for another explicit
84
+ commit. Grid's temporary clipboard/toggle editor is instead released after refusal.
85
+
86
+ Missing/invalid tracking reports editReject reason validation-revision; an ordinary
87
+ stale attempt uses validation-stale with empty diagnostic errors. Silent attempts
88
+ still check but suppress editReject. The trusted beforeCellChange.newValue override
89
+ remains outside revalidation. See the [exact protocol and checked custom examples](GRID_EDITOR_TYPES.md#validation-currentness-and-custom-revisions).
90
+
91
+ PropertyGrid shares the revision protocol but checks after its veto hook too;
92
+ inline stale state is retained, while a still-current ordinary veto restores the
93
+ old display. Its distinct owner/event contract is documented [separately](GRID_EDITOR_TYPES.md#propertygrid-staged-and-inline-ownership).
94
+
58
95
  ## Keys, popups and geometry
59
96
 
60
97
  The shared cell policy remains Enter/F2 start, Enter commit, Escape cancel,
@@ -86,6 +123,48 @@ See [full edit contract](GRID_COMMON_CONTRACT.md), [typed editor API](GRID_EDITO
86
123
  and [actual verification](VERIFICATION.md). Supported/tested rows and custom or
87
124
  unsupported controls must not be conflated when extending an application.
88
125
 
126
+ ## Masked and temporal edit sessions
127
+
128
+ text({ mask: '00-00' }) uses standalone TextInput's live formatting, caret handling
129
+ and bounded local keyboard history. Field values change while typing; DataStore
130
+ changes only on owner commit. Enter/Tab or explicit owner commit writes the
131
+ accepted value, Escape cancels the session, and blur alone does not write the row.
132
+ Add an explicit completeness validator to reject partial masks; required() only
133
+ checks nonempty values. Rejected input accepting no tokens leaves empty fields empty.
134
+ The no-token-empty correction also applies to programmatic mask normalization;
135
+ token grammar, raw-literal handling and whole-value capacity rules are unchanged.
136
+
137
+ Default compact-mode mixed-token/capacity guards reject edits that would lose an untouched suffix;
138
+ they do not add sparse slots. For AA-0000, replacing selected AB in AB-1234 with
139
+ sequential XY can reject intermediate X. Use one-letter replacements or a complete
140
+ compatible replacement. API writes/reset restart mask history, including silent
141
+ or equal-value writes; veto preserves it.
142
+
143
+ Opt in with text({ mask: 'AA-0000', maskMode: 'slots' }) for fixed positions:
144
+ AB-1234 -> __-1234 -> X_-1234 -> XY-1234. Holes survive model/raw serialization
145
+ and edit-session reopening; unmaskValue uses __1234. Do not remove markers when
146
+ saving. Deletion clears slots, typing overwrites, selected replacement stays
147
+ inside selected tokens, and paste overflow rejects. Fully empty model/raw/display
148
+ reads stay ''; a focused empty native input can show the navigable scaffold.
149
+ The required DOM guard uses customError for that scaffold, not valueMissing;
150
+ required() and an explicit marker-based completeness validator remain separate.
151
+ See INPUT_TYPES.md for marker restrictions, API shape validation and history.
152
+ Slots are construction-only on text, not number, TextArea or JSON factories, and
153
+ do not add commitInput. Owner store commit/cancel semantics remain unchanged.
154
+
155
+ time preserves equivalent/partial native text and caret with a live normalized
156
+ model. Partial/unparsed stored time is not completed by passive blur/API/refresh
157
+ or 24-hour presentation. Its picker shows no selected hour/minute/AM/PM; 24
158
+ indicates only mode. OK without a choice retains the partial value, Cancel
159
+ restores it, and explicit time choices use existing defaults. Add completeness
160
+ validation before owner commit when partial values are unacceptable.
161
+ date/dateTime reject native edits that would truncate an untouched suffix,
162
+ retaining value/selection; API prefix normalization is unchanged. Picker staging
163
+ remains its existing OK/Cancel interaction, not a shared typed commit mode.
164
+ Only number supports updateMode: 'commit' and commitInput; optional owner
165
+ preparation does not add those methods to other controls. See
166
+ [input contracts](INPUT_TYPES.md) and [test boundaries](INPUT_TESTING.md).
167
+
89
168
  ## Read presentation and portal font
90
169
 
91
170
  An editor factory controls editing, not read-mode rendering. The matrix Switch
@@ -95,6 +95,154 @@ standalone UI classes remain outside this recipe subset; no permissive index
95
95
  signature hides that boundary. Built-in factories override `label` with `''` and `value` with the
96
96
  cell value, even when options contain those properties.
97
97
 
98
+ ## Explicit draft preparation
99
+
100
+ `gridEditors.number({ updateMode: 'commit' })` uses NumberInput's opt-in pending
101
+ native draft; default number editors remain live. `ControlCellEditor.prepareCommit`
102
+ forwards the action metadata to an optional control `commitInput` method, or
103
+ succeeds when that method is absent. A raw `CellEditor` may implement synchronous
104
+ `prepareCommit(context)` returning `{ ok, value?, status? }`. It remains optional;
105
+ independent custom state also follows the strict revision contract below.
106
+ `getValue()`, `validate()` and `destroy()` must
107
+ not be used to commit drafts.
108
+
109
+ Grid and TreeGrid call preparation before validation/getValue and beforeCellChange
110
+ in commitEdit. Grid also prepares its temporary clipboard/toggle editor before
111
+ validation and readback. A failed preparation rejects with reason `prepare-commit`;
112
+ it does not write the row. Current-session guards apply across this callback phase
113
+ as well, including teardown or a replacement editor. PropertyGrid session commit
114
+ uses the same prepare/validate/read sequence before beforePropertyChange.
115
+
116
+ Enter/Escape in a commit-mode numeric cell go to the owner, preserving table
117
+ commit/cancel and Tab traversal. Blur completes the numeric field only: Grid and
118
+ TreeGrid do not write the row until their explicit commit path. Escape/cancel or
119
+ destroying the editor still discards that cell session without saving the row,
120
+ even if blur already committed its local field value. PropertyGrid inline editors
121
+ instead propagate ordinary control changes after validation, including a completed
122
+ numeric commit; they are not a staged row session. Their ordinary property veto
123
+ restores the old control value silently only while the checked state is current.
124
+ A stale attempt preserves newer callback state instead; see the PropertyGrid
125
+ boundary below.
126
+
127
+ In a staged session, a failed validator or owner veto may follow a successful
128
+ numeric field commit;
129
+ it does not roll that field value back, but prevents the owner write and retains
130
+ the session. Pending disabled/readonly numeric fields refuse preparation rather
131
+ than writing the older committed value. Silent commits suppress semantic events
132
+ and still prepare, validate and synchronize. See [NumberInput](INPUT_TYPES.md#numberinput)
133
+ for structured results, pending-state events and native input limitations.
134
+
135
+ ## Validation currentness and custom revisions
136
+
137
+ Grid and TreeGrid begin value-currentness checks **after prepareCommit**. Legitimate
138
+ normalization/completion during preparation is allowed. They capture revisions,
139
+ check before validation, after validate and its ok read, then after final getValue.
140
+ A value/candidate change during those phases refuses the current commit before the
141
+ owner write. This includes accepted silent A -> B -> A and pending-only changes.
142
+ There is no automatic retry or rollback. A surviving mounted editor keeps callback
143
+ changes and remains available for another explicit commit; callback teardown or
144
+ replacement still wins. No later phase refocuses a destroyed editor.
145
+
146
+ Independent CellEditor and GridValueControl implementations must provide a pure,
147
+ synchronous, stable getValidationRevision(): ValidationRevision. It is optional in
148
+ the structural declarations because built-ins already carry private tracking, not
149
+ because independent untracked state can be committed. The same ValidationRevision
150
+ and ValidationRevisionSource types used by Form are re-exported from
151
+ taet-ui/grid/editors. Existing getValue, validate and value.set return types stay
152
+ unchanged; GridValueControl still uses its existing boolean value setter contract.
153
+
154
+ Use a stored nonnegative safe-integer counter, increasing nonnegative bigint, or
155
+ fresh nonreused symbol, advancing before post-write callbacks for every accepted
156
+ value and validation-relevant candidate change. Getters must not mutate/commit;
157
+ a value hash misses ABA. See [custom field rules](INPUT_TYPES.md#independent-custom-state-revision-hook)
158
+ for token, alias and external-state obligations. A public hook adds checks and
159
+ cannot override an internal stamp or lifecycle/source-identity guard.
160
+
161
+ ControlCellEditor automatically preserves both adapter identity and its owned
162
+ control's tracking. An ordinary EditorControl subclass with authoritative inherited
163
+ state needs no public hook. Prefer decorating and returning the actual built-in
164
+ adapter instead of rebuilding an opaque forwarding object that loses its tracking.
165
+ An independent raw wrapper needs its own complete hook. There is no public built-in
166
+ revision getter or universal editor manager to poll.
167
+
168
+ Currentness refusals use editReject unless silent:
169
+ - reason 'validation-revision' means a missing/noncallable/invalid/throwing/unstable
170
+ reader or observed counter decrease. validation is { source: cellEditor,
171
+ ok: false, errors: [...] }; each protocol error has source: offending editor or
172
+ control, severity: 'error', code: 'validationRevision' and message.
173
+ - reason 'validation-stale' means an otherwise valid currentness proof was lost.
174
+ validation has source: cellEditor, ok:false and errors:[]. Callback changes remain.
175
+
176
+ These protocol errors use source, unlike FormError's control/path. No validation
177
+ value property is required. CellEditorValidation.errors remains readonly unknown[];
178
+ application code must narrow errors before inspecting their fields. Ordinary
179
+ application validation failure still uses reason 'validation'. Lifecycle removal
180
+ can simply stop the attempt rather than notifying or refocusing an obsolete editor.
181
+
182
+ The boundary ends before the trusted beforeCellChange hook. Its existing newValue
183
+ override is deliberately not revalidated, and revision checks do not follow it.
184
+ That hook is not a field beforeChange value override. Silent commits skip the
185
+ trusted veto phase/events but still prepare, validate and check currentness.
186
+
187
+ Grid's temporary clipboard/toggle editors use the same post-prepare protection and
188
+ are released exactly once even on refusal; the rejected attempt does not write its
189
+ cell. This is an editing-path contract, not system-clipboard certification. Callback
190
+ side effects, accepted earlier cells and unrelated model state are not rolled back.
191
+
192
+ The checked [TS consumer](../test/types/grid-revision-consumer.ts) and
193
+ [JSDoc consumer](../test/types/grid-revision-javascript.js) demonstrate raw editors,
194
+ wrapped controls, automatic inherited tracking, preparation, accepted/pending ABA,
195
+ final-read changes, diagnostics and retained sessions. Actual gate outcomes belong
196
+ in [VERIFICATION](VERIFICATION.md).
197
+
198
+ ## PropertyGrid staged and inline ownership
199
+
200
+ PropertyGrid uses the same strict revision protocol and automatic built-in adapter
201
+ tracking. Independent CellEditor/GridValueControl state needs the same hook even
202
+ when the wrapped control has no application validator. Its owner phases differ:
203
+
204
+ - A staged commit prepares, captures currentness, validates/checks, reads the final
205
+ value/checks, dispatches beforePropertyChange/checks, then writes. Rejection keeps
206
+ the surviving session for another explicit commitEdit attempt.
207
+ - Inline propagation starts from an ordinary wrapped-control change event. It
208
+ captures currentness before its initial getValue, checks/no-ops if unchanged,
209
+ validates/checks, reads again/checks, then dispatches beforePropertyChange/checks
210
+ before writing. A stale attempt leaves the callback's value/candidate visible
211
+ and editable, without an owner property write or synthetic restoring change.
212
+ Another ordinary control change starts a fresh inline attempt; commitEdit is
213
+ not a new inline retry API.
214
+
215
+ Neither path retries or rolls back callback effects. PropertyGrid checks currentness
216
+ **after beforePropertyChange too**. Unlike Grid/TreeGrid's beforeCellChange, this
217
+ hook never supplied a newValue override API. A still-current ordinary inline veto
218
+ silently restores the old control value as before. If that callback changes the
219
+ accepted value or candidate, currentness refusal takes precedence even when cancel
220
+ is also true: the newer callback state is retained. An ordinary validation failure
221
+ still refuses without a new rejection event or automatic restoration.
222
+
223
+ Subscribe through events.on('editReject', handler); there is no onEditReject option.
224
+ The new event covers only reason 'validation-revision' or 'validation-stale'. Its
225
+ property identity/provenance fields are source: PropertyGrid, target, property,
226
+ group, name, oldValue, newValue, origin and userAction, without cancel. newValue may
227
+ be undefined if failure preceded the first successful read; otherwise it is the
228
+ last captured value. Nested validation uses the same CellEditorValidation shape
229
+ above: source is the editor, protocol errors identify their offender with source,
230
+ while stale errors is []. This is not FormError's control/path shape.
231
+
232
+ Silent attempts still check currentness and suppress editReject/semantic events.
233
+ A silent control value.set remains hydration and does not manufacture an inline
234
+ change event. Existing initial disabled/readonly inline API hydration is not newly
235
+ prohibited; in-flight state/lifetime/row changes interrupt, and staged commits keep
236
+ their existing disabled gate. Scoped guards prevent a nested change/commit from
237
+ saving midway through the current attempt without locking independent owners.
238
+
239
+ The checked [TS consumer](../test/types/property-revision-consumer.ts) and
240
+ [JSDoc consumer](../test/types/property-revision-javascript.js) cover staged and
241
+ inline usage, strict diagnostics, ordinary invalid compatibility, explicit retry,
242
+ silent refusal and inherited tracking. See the exact [event declarations](../src/ui/collection-contracts.d.ts)
243
+ and [test boundaries](INPUT_TESTING.md); no universal widget or native-host guarantee
244
+ is implied.
245
+
98
246
  ## Select choices and borrowed services
99
247
 
100
248
  `gridEditors.select<TRow, TRowId, TChoice, TChoiceId>()` keeps table records and
@@ -232,6 +380,8 @@ provenance stay bound to the captured cell and current action. Parse failure,
232
380
  validation failure, veto and writer rejection emit editReject with reasons
233
381
  clipboard-parse, validation, before-cell-change and write-rejected respectively.
234
382
  Parse failures expose error (unknown); validation failures expose validation.
383
+ The same revision checks add validation-revision and validation-stale refusals as
384
+ described above; temporary editors are also released after those refusals.
235
385
  Read-only/missing cells and unchanged values are skipped without a rejection.
236
386
 
237
387
  Programmatic clipboard calls default to api/false; native clipboard and pointer/
@@ -286,21 +436,24 @@ sets factory metadata. Both accept either a live `GridValueControl` or a raw
286
436
  validation; `ControlCellEditor` supplies a successful result if it has no
287
437
  validator. A raw cell editor supplies **all** of mount/getValue/validate/focus/
288
438
  destroy. The grids call its `validate()` during commit. Do not return a control
289
- descriptor. Cleanup belongs to the editor instance and its owning grid.
439
+ descriptor. Independent state must also satisfy the revision contract above; an
440
+ optional validator does not make revision tracking optional. Cleanup belongs to
441
+ the editor instance and its owning grid.
290
442
 
291
443
  `SharedGridEditingEvents` declares the common event fields, using `unknown` for
292
444
  heterogeneous cell values. The separate maps describe existing differences:
293
445
 
294
446
  | Contract | Grid | TreeGrid |
295
447
  | --- | --- | --- |
296
- | beforeEditStart | Cancellable event | Not emitted |
297
- | editCommit | `changed`, `writeResult` booleans | No such flags; includes `cancel` |
448
+ | beforeEditStart | Cancellable event | Cancellable event |
449
+ | editCommit | `changed`, `writeResult` booleans | Same flags; retains legacy `cancel` |
298
450
  | editReject.columnId | Present | Present, including validation rejection |
299
451
  | editReject.validation | Editor result on validation failure | Editor result on validation failure |
300
452
 
301
453
  Use `GridEditingEvents` or `TreeGridEditingEvents` only for the corresponding
302
454
  component. Their event maps do not declare every unrelated Grid event. A shared
303
- listener cannot assume Grid-only commit flags. Editor events do not universally
455
+ listener can use the common commit flags; legacy TreeGrid cancel does not veto a
456
+ completed write. Editor events do not universally
304
457
  contain the factory's `rowIndex`; store the creation context when needed.
305
458
 
306
459
  ## Verification