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 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 / Blurred ──► validate the draft against the key's schema
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, on its key
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`) checks the draft as it stands, which is how
330
- a required key left empty comes to say so.
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. When all pass, the whole
343
- input is decoded; a rule that spans keys fails there and lands in
344
- `model.errors`, since it belongs to no one control. The next edit clears
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. One reading a field the form does not set is not judged here; the
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
- - A validation that changes nothing, such as a blur on an empty optional key,
359
- returns the Model it was given, so nothing redraws.
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