foldkit-form 0.8.0 → 0.9.0
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.
- package/README.md +41 -15
- package/dist/{index.d.mts → index.d.ts} +182 -309
- package/dist/index.d.ts.map +1 -0
- package/dist/{index.mjs → index.js} +143 -296
- package/dist/index.js.map +1 -0
- package/dist/input.d.ts +295 -0
- package/dist/input.d.ts.map +1 -0
- package/dist/input.js +261 -0
- package/dist/input.js.map +1 -0
- package/dist/record.d.ts +7 -0
- package/dist/record.d.ts.map +1 -0
- package/dist/record.js +10 -0
- package/dist/record.js.map +1 -0
- package/package.json +11 -11
- package/dist/index.d.mts.map +0 -1
- package/dist/index.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -35,7 +35,7 @@ Entity.input (what each key means)
|
|
|
35
35
|
v
|
|
36
36
|
Bundle
|
|
37
37
|
Model: one fieldValidation Field per key, holding the draft
|
|
38
|
-
Changed
|
|
38
|
+
Changed ──► validate the draft against the key's schema
|
|
39
39
|
Submitted ──► every key valid, input decoded ──► out Message { value }
|
|
40
40
|
```
|
|
41
41
|
|
|
@@ -91,7 +91,7 @@ const RenameForm = Page.children.rename
|
|
|
91
91
|
never dropped by omission.
|
|
92
92
|
- `Rename.Message` builds the form's Messages for your view to dispatch:
|
|
93
93
|
`Changed({ key, value })`, `Blurred({ key })`, `Submitted()`, `Reset()`,
|
|
94
|
-
and `ValidatedAll()` (see [Validation](#validation)). `Toggled({ key })`
|
|
94
|
+
`Validated({ key })` and `ValidatedAll()` (see [Validation](#validation)). `Toggled({ key })`
|
|
95
95
|
flips a flag and `Toggled({ key, choice })` lets go of or adds one choice of a
|
|
96
96
|
list, both to the draft as it stands when the Message lands, so a view sends
|
|
97
97
|
them for a press: two presses before the next draw both count. `FollowedIssue({ id })`
|
|
@@ -100,6 +100,8 @@ const RenameForm = Page.children.rename
|
|
|
100
100
|
either, and the page that owns the list answers the second.
|
|
101
101
|
- `Rename.controls` lists the keys in the input's order, each with its
|
|
102
102
|
`control`, `label`, `description`, `required`, and the Entity `member`.
|
|
103
|
+
`Rename.controlsByKey` holds the same entries by key, for a view that places
|
|
104
|
+
each field itself: `Rename.controlsByKey.title.label`.
|
|
103
105
|
- `Rename.field(model.rename, key)` reads one key's state as `Field<Draft>`, for
|
|
104
106
|
a view that walks `controls`; `model.rename.fields.title` is the same value
|
|
105
107
|
typed to its key.
|
|
@@ -166,7 +168,9 @@ Form.make('Rename', Entity.input(Cms, RenameInput), { inputs: { id: Input.text()
|
|
|
166
168
|
A key that holds an id without being a relation asks for a picker with
|
|
167
169
|
`Input.relationOne(Author)` or `Input.relationMany(Tag)`, as the page Builder's
|
|
168
170
|
Block props do. A key the schema cannot spell — `Schema.Array(Schema.Number)` —
|
|
169
|
-
takes the choices it may hold from `Input.choices([1, 2])`.
|
|
171
|
+
takes the choices it may hold from `Input.choices([1, 2])`. A `Select` or
|
|
172
|
+
`Choices` draft is each option as text, filled values included, so two options
|
|
173
|
+
drawn alike (`'1'` and `1`) are refused when the control is made.
|
|
170
174
|
|
|
171
175
|
### Your own kind of control
|
|
172
176
|
|
|
@@ -278,7 +282,7 @@ const PostForm = Form.make('PostForm', input, {
|
|
|
278
282
|
PostForm.isFollowing(model, 'slug') // false once the author has written it
|
|
279
283
|
PostForm.partial(model) // what decodes as it stands, by key: for saving unfinished work
|
|
280
284
|
PostForm.settled(model) // a stored Model, shown again with no check or submit in flight
|
|
281
|
-
PostForm.Message.Refused({ key: 'slug', error: 'That address is taken' }) // a server's word
|
|
285
|
+
PostForm.Message.Refused({ key: 'slug', error: 'That address is taken', value: 'hello' }) // a server's word on the value sent
|
|
282
286
|
```
|
|
283
287
|
|
|
284
288
|
- While the author has not written the key, each edit of the key it follows
|
|
@@ -326,8 +330,14 @@ Each key is checked against **the input's own schema for that key**, not the
|
|
|
326
330
|
Entity's: the operation decides what is valid, and may be stricter.
|
|
327
331
|
|
|
328
332
|
- **An edit** (`Changed`) checks the new draft at once.
|
|
329
|
-
- **Leaving a control** (`Blurred`)
|
|
330
|
-
|
|
333
|
+
- **Leaving a control** (`Blurred`) says nothing new: an edit has already
|
|
334
|
+
checked the key, and a key never edited is not judged before a submit. So
|
|
335
|
+
tabbing through a required field, or leaving the emptied field of a form that
|
|
336
|
+
was just reset, shows no `Required`. Emptying a required field you typed in
|
|
337
|
+
does say so.
|
|
338
|
+
- **`Validated({ key })`** checks one key as it stands, edited or not: for a
|
|
339
|
+
program that shows a stored value's failure after a `fill`, which validates
|
|
340
|
+
nothing.
|
|
331
341
|
- **Empty** means `""` or `[]`. What an empty draft submits is whatever the
|
|
332
342
|
input admits for it, tried in order: leaving the key out (`Schema.optionalKey`,
|
|
333
343
|
`Schema.optional`), `Option.none()` for a key typed `Option`, `null`, then the
|
|
@@ -339,24 +349,32 @@ Entity's: the operation decides what is valid, and may be stricter.
|
|
|
339
349
|
`Option.some(value)`, and filled from an `Option`.
|
|
340
350
|
- **A number** that does not parse reads `Enter a number`; one that parses is
|
|
341
351
|
checked by the schema. Only spaces is nothing entered, not zero.
|
|
342
|
-
- **Submit** checks every key, so every failure shows
|
|
343
|
-
input is decoded; a rule that
|
|
344
|
-
`model.errors`, since it belongs to no
|
|
345
|
-
them.
|
|
352
|
+
- **Submit** checks every key, so every failure shows, and sets
|
|
353
|
+
`model.attempted`. When all pass, the whole input is decoded; a rule that
|
|
354
|
+
spans keys fails there and lands in `model.errors`, since it belongs to no
|
|
355
|
+
one control. The next edit clears them. `attempted` stays until a `Reset` or
|
|
356
|
+
a `fill`: a view draws its list of fields to fix only once it is set, so a
|
|
357
|
+
failure shows first beside its field, and the list follows a submit.
|
|
346
358
|
- **An invariant** of the Entity (`Entity.invariant`) is judged on submit over
|
|
347
359
|
the row the decoded value describes (`Entity.judgeInput`), as the server will
|
|
348
360
|
judge it: a row that breaks one does not go out, and its message shows beside
|
|
349
361
|
each key its path names, or in `model.errors` when the form sets none of
|
|
350
|
-
them.
|
|
362
|
+
them. Beside a key it is a mark (`model.marks`), not the key's own
|
|
363
|
+
validation: `form.field` shows the two together, and **any edit clears the
|
|
364
|
+
marks**, since `reserved <= quantity` named on `reserved` is often mended by
|
|
365
|
+
raising `quantity`. Until an edit a submit stops; after one it judges again.
|
|
366
|
+
A `Message.Refused` is a mark too, and lands only while the key still holds
|
|
367
|
+
the `value` refused. One reading a field the form does not set is not judged here; the
|
|
351
368
|
server decides it, and the form never calls the input valid on its account.
|
|
352
369
|
The same holds for one calling a primitive operator the form's table does
|
|
353
370
|
not run: give the table as `operators` (`Form.make(name, input, { operators
|
|
354
371
|
})`, `Operators.kernel` by default), and a nested form given none uses it.
|
|
355
372
|
- **`ValidatedAll`** checks every key a submit would, rows too, and submits
|
|
356
373
|
nothing: for a page that sends several forms at once. A rule that spans keys
|
|
357
|
-
is said only by a submit
|
|
358
|
-
|
|
359
|
-
|
|
374
|
+
is said only by a submit, and the page that sends it owns the submit, so it
|
|
375
|
+
does not set `attempted`.
|
|
376
|
+
- A validation that changes nothing, such as a blur, or `Validated` on an
|
|
377
|
+
empty optional key, returns the Model it was given, so nothing redraws.
|
|
360
378
|
|
|
361
379
|
Two questions a view asks before a submit:
|
|
362
380
|
|
|
@@ -373,6 +391,9 @@ Field state is `foldkit/fieldValidation`'s `Field`: `NotValidated`, `Validating`
|
|
|
373
391
|
(a check is running), `Valid`, `Invalid` with its `errors`. Read it with that module's `match`, `isInvalid`,
|
|
374
392
|
and the rest.
|
|
375
393
|
|
|
394
|
+
How a form's failures meet a server's refusals and the rest of an application's
|
|
395
|
+
is [Errors and failures](../../docs/errors.md#forms).
|
|
396
|
+
|
|
376
397
|
### Checks: rules only something else can answer
|
|
377
398
|
|
|
378
399
|
Whether a slug is taken is not in the schema. A check is an Effect the form is
|
|
@@ -408,10 +429,15 @@ const PostForm = Form.make('PostForm', Entity.input(Post, PostInput), {
|
|
|
408
429
|
}).pipe(Form.checks({ slug: isAddressFree }))
|
|
409
430
|
```
|
|
410
431
|
- Each edit asks again after `debounce`, and an answer for a draft the key no
|
|
411
|
-
longer holds is dropped.
|
|
432
|
+
longer holds is dropped. An answer carries the `values` and `subject` it was
|
|
433
|
+
asked with; when another key or the subject changed while it ran, it is not
|
|
434
|
+
taken but asked again, so a submit waiting on it waits for the answer about
|
|
435
|
+
the form as it is. An answer already taken stands until its own key is
|
|
436
|
+
edited: the server checks the write.
|
|
412
437
|
- The ask is the form's Command `PostForm.Check` (named `PostForm.check`), a
|
|
413
438
|
Command definition like any other, so a Scene or Story resolves it with
|
|
414
439
|
`Command.resolve(PostForm.Check, PostForm.Message.Checked({ key, draft, error }))`.
|
|
440
|
+
An answer made so, without `values` and `subject`, answers the form as it is.
|
|
415
441
|
- **A submit waits.** Submitted while a check runs, the form sets `submitPending`
|
|
416
442
|
and sends the value when the last check passes, or nothing if one fails. An
|
|
417
443
|
edit in between cancels the wait. A filled form (`fill` validates nothing) is
|