foldkit-form 0.1.2 → 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 +114 -23
- package/dist/index.d.mts +545 -119
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +445 -184
- package/dist/index.mjs.map +1 -1
- package/package.json +9 -7
package/README.md
CHANGED
|
@@ -56,7 +56,6 @@ import { Schema } from 'effect'
|
|
|
56
56
|
import { Bundle } from 'foldkit-bundle'
|
|
57
57
|
import { Entity } from 'foldkit-entity'
|
|
58
58
|
import { Form } from 'foldkit-form'
|
|
59
|
-
import { defineMessageUnion } from 'foldkit/message'
|
|
60
59
|
|
|
61
60
|
const Post = Entity.define(
|
|
62
61
|
'Post',
|
|
@@ -72,17 +71,15 @@ const RenameInput = Schema.Struct({ id: Schema.String, title: Post.fields.title.
|
|
|
72
71
|
const Rename = Form.make('Rename', Entity.input(Post, RenameInput))
|
|
73
72
|
|
|
74
73
|
// Place it: a Model field and a Message variant of the page.
|
|
75
|
-
const
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
// `submitted.value` is a decoded RenameInput. What it means is the page's.
|
|
82
|
-
onOut: submitted => model => ({
|
|
83
|
-
model: { ...model, saved: [...model.saved, submitted.value] },
|
|
74
|
+
const Page = Bundle.compose({ saved: Schema.Array(RenameInput) }).pipe(
|
|
75
|
+
Bundle.withChild('rename', Rename.bundle, {
|
|
76
|
+
// `submitted.value` is a decoded RenameInput. What it means is the page's.
|
|
77
|
+
onOut: submitted => model => ({
|
|
78
|
+
model: { ...model, saved: [...model.saved, submitted.value] },
|
|
79
|
+
}),
|
|
84
80
|
}),
|
|
85
|
-
|
|
81
|
+
)
|
|
82
|
+
const RenameForm = Page.children.rename
|
|
86
83
|
```
|
|
87
84
|
|
|
88
85
|
- `Form.make` takes the name and an `Entity.input`. It resolves a control per
|
|
@@ -91,7 +88,8 @@ const RenameForm = Page.at(Slot, {
|
|
|
91
88
|
- `Rename.bundle` is an ordinary Bundle. `onOut` is required, so a submit is
|
|
92
89
|
never dropped by omission.
|
|
93
90
|
- `Rename.Message` builds the form's Messages for your view to dispatch:
|
|
94
|
-
`Changed({ key, value })`, `Blurred({ key })`, `Submitted()`, `Reset()
|
|
91
|
+
`Changed({ key, value })`, `Blurred({ key })`, `Submitted()`, `Reset()`,
|
|
92
|
+
and `ValidatedAll()` (see [Validation](#validation)).
|
|
95
93
|
- `Rename.controls` lists the keys in the input's order, each with its
|
|
96
94
|
`control`, `label`, `description`, `required`, and the Entity `member`.
|
|
97
95
|
- `Rename.field(model.rename, key)` reads one key's state as `Field<Draft>`, for
|
|
@@ -104,13 +102,13 @@ Continuing the example above, an assembly initializes the slice and routes its
|
|
|
104
102
|
wrapped Messages. This reducer-level example needs no renderer:
|
|
105
103
|
|
|
106
104
|
```ts
|
|
107
|
-
const placements = Page
|
|
105
|
+
const { placements } = Page
|
|
108
106
|
const update = placements.update(model => ({ model }))
|
|
109
107
|
let model = placements.initial({ saved: [] }).model
|
|
110
|
-
model = update(model, Message.GotRenameMessage({
|
|
108
|
+
model = update(model, Page.Message.GotRenameMessage({
|
|
111
109
|
message: Rename.Message.Changed({ key: 'title', value: 'Hello' }),
|
|
112
110
|
})).model
|
|
113
|
-
model = update(model, Message.GotRenameMessage({
|
|
111
|
+
model = update(model, Page.Message.GotRenameMessage({
|
|
114
112
|
message: Rename.Message.Submitted(),
|
|
115
113
|
})).model
|
|
116
114
|
// model.saved contains the decoded input, with title "Hello" and id "".
|
|
@@ -135,7 +133,7 @@ included.
|
|
|
135
133
|
| `Hidden` | `string` | only when asked for: a key the form carries and does not show, such as the id being edited |
|
|
136
134
|
| `Number` | `string` | the schema is a number |
|
|
137
135
|
| `Toggle` | `boolean` | the schema is a boolean |
|
|
138
|
-
| `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` |
|
|
139
137
|
| `RelationOne` | `string` (an id, `""` for none) | the key is `Relation.input` of a `one` |
|
|
140
138
|
| `RelationMany` | `string[]` | the key is `Relation.input` of a `many` |
|
|
141
139
|
|
|
@@ -156,6 +154,10 @@ const Cms = Post.pipe(Entity.annotateMembers({ title: Input.of(Input.multiline()
|
|
|
156
154
|
Form.make('Rename', Entity.input(Cms, RenameInput), { inputs: { id: Input.text() } })
|
|
157
155
|
```
|
|
158
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
|
+
|
|
159
161
|
### Your own kind of control
|
|
160
162
|
|
|
161
163
|
The kinds above are made with `Input.kind`, and so is a date picker, a rich text
|
|
@@ -183,6 +185,54 @@ Cents.is(control) && control.data.currency // 'USD'
|
|
|
183
185
|
kind once it has a renderer for it; see
|
|
184
186
|
[`foldkit-mixins-form`](../mixins-form/README.md#renderers).
|
|
185
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
|
+
|
|
186
236
|
### A key that follows another
|
|
187
237
|
|
|
188
238
|
A slug is its title until the author decides otherwise. `Input.following` keeps
|
|
@@ -247,16 +297,35 @@ Entity's: the operation decides what is valid, and may be stricter.
|
|
|
247
297
|
- **Leaving a control** (`Blurred`) checks the draft as it stands, which is how
|
|
248
298
|
a required key left empty comes to say so.
|
|
249
299
|
- **Empty** means `""` or `[]`. What an empty draft submits is whatever the
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
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`.
|
|
254
308
|
- **A number** that does not parse reads `Enter a number`; one that parses is
|
|
255
309
|
checked by the schema. Only spaces is nothing entered, not zero.
|
|
256
310
|
- **Submit** checks every key, so every failure shows. When all pass, the whole
|
|
257
311
|
input is decoded; a rule that spans keys fails there and lands in
|
|
258
312
|
`model.errors`, since it belongs to no one control. The next edit clears
|
|
259
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`.
|
|
260
329
|
|
|
261
330
|
Field state is `foldkit/fieldValidation`'s `Field`: `NotValidated`, `Validating`
|
|
262
331
|
(a check is running), `Valid`, `Invalid` with its `errors`. Read it with that module's `match`, `isInvalid`,
|
|
@@ -469,6 +538,25 @@ A relation is loaded as a ref and read back as the id the form holds. See
|
|
|
469
538
|
[`foldkit-entity`](../entity/README.md#showing-what-is-there).
|
|
470
539
|
[`foldkit-crud`](../crud/README.md) does this, the save, and its status for you.
|
|
471
540
|
|
|
541
|
+
## Did an edit change anything?
|
|
542
|
+
|
|
543
|
+
`authoredChanged(before, after)` answers whether a completed transition changed
|
|
544
|
+
what the author wrote:
|
|
545
|
+
|
|
546
|
+
```ts
|
|
547
|
+
const next = RenameForm.bundle.update(model, message, undefined)
|
|
548
|
+
if (RenameForm.authoredChanged(model, next.model)) scheduleAutosave()
|
|
549
|
+
```
|
|
550
|
+
|
|
551
|
+
It compares the two Models, not the Message: validation state, search text, the
|
|
552
|
+
edited subject, and row bookkeeping are not authored content, so a blur, a
|
|
553
|
+
refused edit, or a repeated value reports `false` while a changed draft, an
|
|
554
|
+
added or removed row, or a changed row reports `true`. Nested rows recurse
|
|
555
|
+
through their own forms, and a control whose output is written back into the
|
|
556
|
+
Model composes for the same reason — which is what lets a consumer such as
|
|
557
|
+
[`foldkit-cms`](../cms/README.md) autosave without knowing the form's Message
|
|
558
|
+
tags.
|
|
559
|
+
|
|
472
560
|
## Limits
|
|
473
561
|
|
|
474
562
|
- Headless: no view here (see `foldkit-mixins-form`), and no relation picker data. `RelationOne` and
|
|
@@ -476,6 +564,9 @@ A relation is loaded as a ref and read back as the id the form holds. See
|
|
|
476
564
|
application makes.
|
|
477
565
|
- One `Changed` Message carries any draft, so a view can dispatch a draft of the
|
|
478
566
|
wrong kind for a key. The form ignores it rather than storing it.
|
|
479
|
-
- A key whose value is a struct is editable
|
|
480
|
-
|
|
481
|
-
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.
|