foldkit-form 0.2.0 → 0.3.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 +84 -9
- package/dist/index.d.mts +536 -122
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +334 -99
- package/dist/index.mjs.map +1 -1
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -88,7 +88,8 @@ const RenameForm = Page.children.rename
|
|
|
88
88
|
- `Rename.bundle` is an ordinary Bundle. `onOut` is required, so a submit is
|
|
89
89
|
never dropped by omission.
|
|
90
90
|
- `Rename.Message` builds the form's Messages for your view to dispatch:
|
|
91
|
-
`Changed({ key, value })`, `Blurred({ key })`, `Submitted()`, `Reset()
|
|
91
|
+
`Changed({ key, value })`, `Blurred({ key })`, `Submitted()`, `Reset()`,
|
|
92
|
+
and `ValidatedAll()` (see [Validation](#validation)).
|
|
92
93
|
- `Rename.controls` lists the keys in the input's order, each with its
|
|
93
94
|
`control`, `label`, `description`, `required`, and the Entity `member`.
|
|
94
95
|
- `Rename.field(model.rename, key)` reads one key's state as `Field<Draft>`, for
|
|
@@ -132,7 +133,7 @@ included.
|
|
|
132
133
|
| `Hidden` | `string` | only when asked for: a key the form carries and does not show, such as the id being edited |
|
|
133
134
|
| `Number` | `string` | the schema is a number |
|
|
134
135
|
| `Toggle` | `boolean` | the schema is a boolean |
|
|
135
|
-
| `Select` | `string` | the schema is a union of string literals; carries `options` |
|
|
136
|
+
| `Select` | `string` | the schema is a union of string or number literals; carries `options`, and gives the chosen option itself, so `3` is `3` |
|
|
136
137
|
| `RelationOne` | `string` (an id, `""` for none) | the key is `Relation.input` of a `one` |
|
|
137
138
|
| `RelationMany` | `string[]` | the key is `Relation.input` of a `many` |
|
|
138
139
|
|
|
@@ -153,6 +154,10 @@ const Cms = Post.pipe(Entity.annotateMembers({ title: Input.of(Input.multiline()
|
|
|
153
154
|
Form.make('Rename', Entity.input(Cms, RenameInput), { inputs: { id: Input.text() } })
|
|
154
155
|
```
|
|
155
156
|
|
|
157
|
+
A key that holds an id without being a relation asks for a picker with
|
|
158
|
+
`Input.relationOne(Author)` or `Input.relationMany(Tag)`, as the page Builder's
|
|
159
|
+
Block props do.
|
|
160
|
+
|
|
156
161
|
### Your own kind of control
|
|
157
162
|
|
|
158
163
|
The kinds above are made with `Input.kind`, and so is a date picker, a rich text
|
|
@@ -180,6 +185,54 @@ Cents.is(control) && control.data.currency // 'USD'
|
|
|
180
185
|
kind once it has a renderer for it; see
|
|
181
186
|
[`foldkit-mixins-form`](../mixins-form/README.md#renderers).
|
|
182
187
|
|
|
188
|
+
### A control with a Model of its own
|
|
189
|
+
|
|
190
|
+
Some controls are more than a draft. A color picker has a popover that is open
|
|
191
|
+
or closed and a palette it looked up; a page builder has a selection and an undo
|
|
192
|
+
history; a rich-text editor has a document and a cursor. `Input.bundle` makes
|
|
193
|
+
such a control out of an ordinary [Bundle](../bundle/README.md): the key's draft
|
|
194
|
+
*is* the Bundle's Model, and the form carries everything else the Bundle has.
|
|
195
|
+
|
|
196
|
+
```ts
|
|
197
|
+
const ColorInput = Input.bundle('ColorPicker', {
|
|
198
|
+
bundle: ColorPicker, // Model { open, hex, recent }, its own Messages, a Command, a Subscription
|
|
199
|
+
value: model => model.hex, // what the key validates and submits
|
|
200
|
+
fill: (model, hex) => ({ ...model, hex }), // a value the form was given, written into the Model
|
|
201
|
+
settled: model => ({ ...model, open: false }), // a stored form shown again: nothing in flight
|
|
202
|
+
})
|
|
203
|
+
|
|
204
|
+
const PostForm = Form.make('PostForm', input, { inputs: { color: ColorInput } })
|
|
205
|
+
const color = PostForm.control('color')
|
|
206
|
+
|
|
207
|
+
color.field(model) // { _tag, value: { open, hex, recent } }: validation state, the Model as value
|
|
208
|
+
color.send(ColorMessage.Opened()) // the form's Message carrying one of the picker's own
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
What the form does with it:
|
|
212
|
+
|
|
213
|
+
- **The Bundle's Messages** travel as the form's `Control` Message, and
|
|
214
|
+
`color.send` builds one. One the Bundle does not take is dropped.
|
|
215
|
+
- **An edit is a change of value.** A Message that changes `value(model)` is
|
|
216
|
+
validated against the key's schema, clears the last submit's failures, and
|
|
217
|
+
makes `authoredChanged` true, so a CMS autosaves it. A Message that changes
|
|
218
|
+
only the rest of the Model, such as opening the popover, is none of those.
|
|
219
|
+
- **Its Commands, Subscriptions and Resources are the form's.** Commands come
|
|
220
|
+
back as `Control` Messages. The form's Bundle gains the control's
|
|
221
|
+
Subscriptions and Resources, keyed under the key (`ColorPicker@fields.color/…`),
|
|
222
|
+
and `init` starts the control's init Commands.
|
|
223
|
+
- **`fill`, `partial`, `settled`, submit and `Reset`** all go through `value`,
|
|
224
|
+
`fill` and `settled`. `Reset` returns the Bundle's initial Model.
|
|
225
|
+
- **Nothing entered** is `value` giving `undefined` or `null`, which a required
|
|
226
|
+
key refuses as it would an empty text box.
|
|
227
|
+
- **Types follow the control.** `model.fields.color.value` is the picker's
|
|
228
|
+
Model, `color.send` takes only the picker's Messages, and `field` refuses the
|
|
229
|
+
key, whose draft is not text.
|
|
230
|
+
|
|
231
|
+
The Bundle may not have an OutMessage, since a key has no parent to hand one
|
|
232
|
+
to, and its Commands may need no services. A key given a control like this
|
|
233
|
+
takes no `check`; say what is valid in its schema. A nested form whose control
|
|
234
|
+
has Subscriptions or Resources is refused, because a row cannot run them yet.
|
|
235
|
+
|
|
183
236
|
### A key that follows another
|
|
184
237
|
|
|
185
238
|
A slug is its title until the author decides otherwise. `Input.following` keeps
|
|
@@ -244,16 +297,35 @@ Entity's: the operation decides what is valid, and may be stricter.
|
|
|
244
297
|
- **Leaving a control** (`Blurred`) checks the draft as it stands, which is how
|
|
245
298
|
a required key left empty comes to say so.
|
|
246
299
|
- **Empty** means `""` or `[]`. What an empty draft submits is whatever the
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
300
|
+
input admits for it, tried in order: leaving the key out (`Schema.optionalKey`,
|
|
301
|
+
`Schema.optional`), `Option.none()` for a key typed `Option`, `null`, then the
|
|
302
|
+
empty value itself. A key is `required` exactly when none is admitted, so an
|
|
303
|
+
optional key, `Schema.NullOr`, and an array need no flag from you. A plain
|
|
304
|
+
`Schema.String` admits `""`; add `Schema.isMinLength(1)` to require it.
|
|
305
|
+
- **A key typed `Option`** (`Schema.OptionFromNullOr(Schema.String)`) is edited
|
|
306
|
+
as what it holds: a `Text` control, checked by the inner schema, submitting
|
|
307
|
+
`Option.some(value)`, and filled from an `Option`.
|
|
251
308
|
- **A number** that does not parse reads `Enter a number`; one that parses is
|
|
252
309
|
checked by the schema. Only spaces is nothing entered, not zero.
|
|
253
310
|
- **Submit** checks every key, so every failure shows. When all pass, the whole
|
|
254
311
|
input is decoded; a rule that spans keys fails there and lands in
|
|
255
312
|
`model.errors`, since it belongs to no one control. The next edit clears
|
|
256
313
|
them.
|
|
314
|
+
- **`ValidatedAll`** checks every key a submit would, rows too, and submits
|
|
315
|
+
nothing: for a page that sends several forms at once. A rule that spans keys
|
|
316
|
+
is said only by a submit.
|
|
317
|
+
- A validation that changes nothing, such as a blur on an empty optional key,
|
|
318
|
+
returns the Model it was given, so nothing redraws.
|
|
319
|
+
|
|
320
|
+
Two questions a view asks before a submit:
|
|
321
|
+
|
|
322
|
+
| Query | True when |
|
|
323
|
+
| --- | --- |
|
|
324
|
+
| `form.isValid(model)` | a submit now would hand over the value at once: every key and row valid, no check running or still to run |
|
|
325
|
+
| `form.canSubmit(model)` | nothing is invalid; a check still running does not stop it, since the submit waits for the answer |
|
|
326
|
+
|
|
327
|
+
A page that submits its forms itself reads `isValid`; a Save button reads
|
|
328
|
+
`canSubmit`.
|
|
257
329
|
|
|
258
330
|
Field state is `foldkit/fieldValidation`'s `Field`: `NotValidated`, `Validating`
|
|
259
331
|
(a check is running), `Valid`, `Invalid` with its `errors`. Read it with that module's `match`, `isInvalid`,
|
|
@@ -492,6 +564,9 @@ tags.
|
|
|
492
564
|
application makes.
|
|
493
565
|
- One `Changed` Message carries any draft, so a view can dispatch a draft of the
|
|
494
566
|
wrong kind for a key. The form ignores it rather than storing it.
|
|
495
|
-
- A key whose value is a struct is editable
|
|
496
|
-
|
|
497
|
-
they were added in; there is no reordering.
|
|
567
|
+
- A key whose value is a struct is editable as a nested input of a relation's
|
|
568
|
+
target, or through a control backed by a Bundle (`Input.bundle`). Rows keep
|
|
569
|
+
the order they were added in; there is no reordering.
|
|
570
|
+
- A control backed by a Bundle takes no `check`, its Bundle has no OutMessage
|
|
571
|
+
and needs no services, and inside a nested form's rows it may have no
|
|
572
|
+
Subscriptions or Resources.
|