foldkit-form 0.1.0 → 0.1.2
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 +192 -15
- package/dist/index.d.mts +712 -53
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +395 -56
- package/dist/index.mjs.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -86,8 +86,8 @@ const RenameForm = Page.at(Slot, {
|
|
|
86
86
|
```
|
|
87
87
|
|
|
88
88
|
- `Form.make` takes the name and an `Entity.input`. It resolves a control per
|
|
89
|
-
key and throws if it cannot
|
|
90
|
-
|
|
89
|
+
key and throws if it cannot. A view must also supply a renderer for each
|
|
90
|
+
control kind, including custom kinds.
|
|
91
91
|
- `Rename.bundle` is an ordinary Bundle. `onOut` is required, so a submit is
|
|
92
92
|
never dropped by omission.
|
|
93
93
|
- `Rename.Message` builds the form's Messages for your view to dispatch:
|
|
@@ -98,11 +98,38 @@ const RenameForm = Page.at(Slot, {
|
|
|
98
98
|
a view that walks `controls`; `model.rename.fields.title` is the same value
|
|
99
99
|
typed to its key.
|
|
100
100
|
|
|
101
|
+
### Run one edit through the parent
|
|
102
|
+
|
|
103
|
+
Continuing the example above, an assembly initializes the slice and routes its
|
|
104
|
+
wrapped Messages. This reducer-level example needs no renderer:
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
const placements = Page.assemble(RenameForm)
|
|
108
|
+
const update = placements.update(model => ({ model }))
|
|
109
|
+
let model = placements.initial({ saved: [] }).model
|
|
110
|
+
model = update(model, Message.GotRenameMessage({
|
|
111
|
+
message: Rename.Message.Changed({ key: 'title', value: 'Hello' }),
|
|
112
|
+
})).model
|
|
113
|
+
model = update(model, Message.GotRenameMessage({
|
|
114
|
+
message: Rename.Message.Submitted(),
|
|
115
|
+
})).model
|
|
116
|
+
// model.saved contains the decoded input, with title "Hello" and id "".
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Here a plain `Schema.String` allows the empty id. For editing a real row, fill
|
|
120
|
+
the form with that row's id first; add an input-schema constraint if an empty
|
|
121
|
+
id is invalid for your operation. `onOut` stores the value locally in this
|
|
122
|
+
example. It does not save to a server. Forms with asynchronous checks also need
|
|
123
|
+
the runtime to execute their returned Commands.
|
|
124
|
+
|
|
101
125
|
## Controls
|
|
102
126
|
|
|
103
|
-
A control is data:
|
|
127
|
+
A control is data: a `kind` (a name), the `draft` the Model holds while it is
|
|
128
|
+
edited, and whatever `data` its kind needs, with nothing about how it is drawn.
|
|
129
|
+
There is one primitive, and every kind is a value of it, the ones below
|
|
130
|
+
included.
|
|
104
131
|
|
|
105
|
-
|
|
|
132
|
+
| Kind | Draft | Chosen when |
|
|
106
133
|
| --- | --- | --- |
|
|
107
134
|
| `Text`, `Multiline` | `string` | the schema is a string (`Multiline` only when asked for) |
|
|
108
135
|
| `Hidden` | `string` | only when asked for: a key the form carries and does not show, such as the id being edited |
|
|
@@ -129,6 +156,79 @@ const Cms = Post.pipe(Entity.annotateMembers({ title: Input.of(Input.multiline()
|
|
|
129
156
|
Form.make('Rename', Entity.input(Cms, RenameInput), { inputs: { id: Input.text() } })
|
|
130
157
|
```
|
|
131
158
|
|
|
159
|
+
### Your own kind of control
|
|
160
|
+
|
|
161
|
+
The kinds above are made with `Input.kind`, and so is a date picker, a rich text
|
|
162
|
+
editor, or a price:
|
|
163
|
+
|
|
164
|
+
```ts
|
|
165
|
+
const Cents = Input.kind<{ readonly currency: string }>('Cents', {
|
|
166
|
+
draft: 'text', // what the Model holds while it is edited
|
|
167
|
+
// The value the schema is given, when that is not the text itself.
|
|
168
|
+
parse: draft => (/^\d+(\.\d{1,2})?$/.test(draft) ? Math.round(Number(draft) * 100) : undefined),
|
|
169
|
+
unparsed: 'Enter an amount',
|
|
170
|
+
})
|
|
171
|
+
|
|
172
|
+
Form.make('Price', input, { inputs: { cents: Cents.of({ currency: 'USD' }) } })
|
|
173
|
+
|
|
174
|
+
Cents.is(control) && control.data.currency // 'USD'
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
- `draft` is `'text'`, `'flag'` (a boolean) or `'list'` (ids).
|
|
178
|
+
- `parse` reads text as something else before the key's schema sees it, as
|
|
179
|
+
`Number` does; `undefined` means it does not read, and `unparsed` is what to
|
|
180
|
+
say. Text that is only spaces is nothing entered, not a failure to parse.
|
|
181
|
+
- `shown: false` makes a kind that is carried and not drawn, as `Hidden` is.
|
|
182
|
+
- Nothing else in the form treats a shipped kind differently. A view draws your
|
|
183
|
+
kind once it has a renderer for it; see
|
|
184
|
+
[`foldkit-mixins-form`](../mixins-form/README.md#renderers).
|
|
185
|
+
|
|
186
|
+
### A key that follows another
|
|
187
|
+
|
|
188
|
+
A slug is its title until the author decides otherwise. `Input.following` keeps
|
|
189
|
+
the key's own control and writes its draft from another key:
|
|
190
|
+
|
|
191
|
+
```ts
|
|
192
|
+
const PostForm = Form.make('PostForm', input, {
|
|
193
|
+
inputs: { slug: Input.following('title', slugify) },
|
|
194
|
+
})
|
|
195
|
+
|
|
196
|
+
PostForm.isFollowing(model, 'slug') // false once the author has written it
|
|
197
|
+
PostForm.partial(model) // what decodes as it stands, by key: for saving unfinished work
|
|
198
|
+
PostForm.settled(model) // a stored Model, shown again with no check or submit in flight
|
|
199
|
+
PostForm.Message.Refused({ key: 'slug', error: 'That address is taken' }) // a server's word, on its key
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
- While the author has not written the key, each edit of the key it follows
|
|
203
|
+
rewrites it, through the function given, and it is validated and checked as if
|
|
204
|
+
typed. With nothing to follow yet it shows no failure; a submit still does.
|
|
205
|
+
- **Once they write it, it is theirs**, and the key it followed moves on without
|
|
206
|
+
it. Emptying it hands it back, which is how a view offers "regenerate".
|
|
207
|
+
- **A form filled with a value for it does not follow.** An address that is
|
|
208
|
+
already published must not move because its title was edited. Filled with
|
|
209
|
+
nothing for it, it follows.
|
|
210
|
+
- A key may follow a key that follows. A key that follows itself, through any
|
|
211
|
+
chain, or that follows something that is not another text key of the form, is
|
|
212
|
+
refused when the form is made.
|
|
213
|
+
|
|
214
|
+
### A picker that searches
|
|
215
|
+
|
|
216
|
+
A relation usually has too many targets to list. `Input.search()` keeps the
|
|
217
|
+
key's picker and gives it a search:
|
|
218
|
+
|
|
219
|
+
```ts
|
|
220
|
+
const EditPost = Form.make('EditPost', input, { inputs: { authorId: Input.search() } })
|
|
221
|
+
|
|
222
|
+
EditPost.Message.Searched({ key: 'authorId', text: 'ad' })
|
|
223
|
+
EditPost.search(model, 'authorId') // 'ad'
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
The form holds what was typed and does nothing else with it: it changes no
|
|
227
|
+
draft and validates nothing. The application reads it as the input of the query
|
|
228
|
+
that lists the choices, so finding an author is an ordinary query. A fill or a
|
|
229
|
+
reset starts the search over. `Input.search()` on a key that is not a relation
|
|
230
|
+
throws.
|
|
231
|
+
|
|
132
232
|
### Labels
|
|
133
233
|
|
|
134
234
|
A label is the schema's own `title` annotation, and the description its
|
|
@@ -186,6 +286,16 @@ const PostForm = Form.make('PostForm', Entity.input(Post, PostInput), {
|
|
|
186
286
|
this. `Valid` on a checked key means the check passed.
|
|
187
287
|
- The form does not know what answers. The check's requirements (`R`) become the
|
|
188
288
|
Bundle's, so a check that needs `RemoteClient` makes the placement need it.
|
|
289
|
+
**Add such a check with the `Form.checks` step, not in `Form.make`'s options:**
|
|
290
|
+
Effect's `R` is not an inference site a mapped type can win, so `Form.make`
|
|
291
|
+
reads it as `never` and refuses the check ("`RemoteClient` is not assignable to
|
|
292
|
+
`never`"). The step reads the requirement off the functions it is given.
|
|
293
|
+
|
|
294
|
+
```ts
|
|
295
|
+
const PostForm = Form.make('PostForm', Entity.input(Post, PostInput), {
|
|
296
|
+
debounce: 0,
|
|
297
|
+
}).pipe(Form.checks({ slug: isAddressFree }))
|
|
298
|
+
```
|
|
189
299
|
- Each edit asks again after `debounce`, and an answer for a draft the key no
|
|
190
300
|
longer holds is dropped.
|
|
191
301
|
- **A submit waits.** Submitted while a check runs, the form sets `submitPending`
|
|
@@ -194,6 +304,14 @@ const PostForm = Form.make('PostForm', Entity.input(Post, PostInput), {
|
|
|
194
304
|
checked on submit the same way.
|
|
195
305
|
- `context.values` holds the other keys that currently decode, which is how an
|
|
196
306
|
edit form lets a post keep its own slug.
|
|
307
|
+
- `context.subject` is what the form is editing, for what its values do not say.
|
|
308
|
+
A post's input carries a title and an address, not the row's id, so "is this
|
|
309
|
+
address taken?" cannot tell the post's own address from someone else's. Send
|
|
310
|
+
`Message.About({ subject: { id } })` once when the form opens on a row, and the
|
|
311
|
+
check has it; `form.subject(model)` reads it back. A form that creates
|
|
312
|
+
something is about nothing, which is the `{}` it starts with. It changes no
|
|
313
|
+
draft, answers no submit, and survives `fill` and `Reset`: which row the form
|
|
314
|
+
is about does not change because its contents did.
|
|
197
315
|
|
|
198
316
|
### Messages
|
|
199
317
|
|
|
@@ -211,7 +329,7 @@ rewrites what Schema says by default, which is also how a form is translated:
|
|
|
211
329
|
const Rename = Form.make('Rename', Entity.input(Post, RenameInput), {
|
|
212
330
|
messages: {
|
|
213
331
|
required: field => `${field.label} is missing`,
|
|
214
|
-
|
|
332
|
+
unparsed: field => `${field.label} must be a number`,
|
|
215
333
|
invalid: (field, message) => `${field.label}: ${message}`,
|
|
216
334
|
form: message => message,
|
|
217
335
|
},
|
|
@@ -221,12 +339,61 @@ const Rename = Form.make('Rename', Entity.input(Post, RenameInput), {
|
|
|
221
339
|
| Message | Said when | Default |
|
|
222
340
|
| --- | --- | --- |
|
|
223
341
|
| `required(field)` | an empty draft the schema does not admit | `Required` |
|
|
224
|
-
| `
|
|
342
|
+
| `unparsed(field)` | text its control cannot read, such as a `Number` that is not one | the kind's own words (`Enter a number`) |
|
|
225
343
|
| `invalid(field, message)` | the key's schema rejects the draft; `message` is the check's own, or Schema's | `message` |
|
|
226
344
|
| `form(message)` | the input as a whole fails: a rule that spans keys | `message` |
|
|
227
345
|
|
|
228
346
|
`field` is the key, its label, and its control.
|
|
229
347
|
|
|
348
|
+
### Words as text, in one place
|
|
349
|
+
|
|
350
|
+
Each of these may be text with blanks instead of a function: `'{label} is required'`
|
|
351
|
+
(`{label}`, `{key}`, and `{message}` where there is one). Text can be kept in a
|
|
352
|
+
translation catalogue, and it can go where a function cannot: Foldkit admits no
|
|
353
|
+
function nested in a placed view's inputs. The drawn packages' words are text
|
|
354
|
+
too, and the three shapes share no key, so an application writes its words once:
|
|
355
|
+
|
|
356
|
+
```ts
|
|
357
|
+
import type { FormMessages } from 'foldkit-form'
|
|
358
|
+
import type { ViewWords } from 'foldkit-mixins-crud'
|
|
359
|
+
import type { FormViewWords } from 'foldkit-mixins-form'
|
|
360
|
+
|
|
361
|
+
export const words = {
|
|
362
|
+
required: '{label} is required', // foldkit-form
|
|
363
|
+
submit: 'Save', // foldkit-mixins-form
|
|
364
|
+
add: 'Another {label}',
|
|
365
|
+
yes: 'Live', // foldkit-mixins-crud
|
|
366
|
+
empty: 'No posts yet.',
|
|
367
|
+
} satisfies FormMessages & FormViewWords & ViewWords
|
|
368
|
+
|
|
369
|
+
Form.make('EditPost', input, { messages: words })
|
|
370
|
+
placed.view(model, h, { options, words })
|
|
371
|
+
PostTable({ page, words }, h)
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
`fillWords(template, values)` is the blank-filling they all use.
|
|
375
|
+
|
|
376
|
+
## Pipe steps
|
|
377
|
+
|
|
378
|
+
Every option is also a pipe step that gives a new form, made from the same input
|
|
379
|
+
with that option added to:
|
|
380
|
+
|
|
381
|
+
```ts
|
|
382
|
+
const AuthorForm = Form.make('Author', NewAuthor) // as a library might hand it over
|
|
383
|
+
|
|
384
|
+
const Finished = AuthorForm.pipe(
|
|
385
|
+
Form.inputs({ bio: Input.multiline() }),
|
|
386
|
+
Form.checks({ name: name => isNameTaken(name) }),
|
|
387
|
+
Form.messages({ required: field => `${field.label} fehlt` }),
|
|
388
|
+
)
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
`Form.inputs`, `Form.checks`, `Form.messages`, `Form.nested` and `Form.debounce`.
|
|
392
|
+
Each adds to what the form already has, so a form can be made in one place and
|
|
393
|
+
finished in another. A step's keys are checked against the form it is piped
|
|
394
|
+
into, and `Form.checks` adds what its checks need to what the form needs. The
|
|
395
|
+
first form is left as it was.
|
|
396
|
+
|
|
230
397
|
## Nested input
|
|
231
398
|
|
|
232
399
|
A key mapped with [`Relation.nested`](../entity/README.md#an-input-that-holds-the-target-itself)
|
|
@@ -241,10 +408,12 @@ const CreatePost = Entity.input(
|
|
|
241
408
|
{ comments: Relation.nested(Blog.Post.relations.comments, NewComment) },
|
|
242
409
|
)
|
|
243
410
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
411
|
+
// The form that edits a comment alone is the form a post's form nests.
|
|
412
|
+
const CommentForm = Form.make('Comment', NewComment, { inputs: { body: Input.multiline() } })
|
|
413
|
+
const PostForm = Form.make('PostForm', CreatePost, { nested: { comments: CommentForm } })
|
|
414
|
+
|
|
415
|
+
PostForm.row('comments', 'r0').Changed({ key: 'body', value: 'First' }) // a Message of PostForm
|
|
416
|
+
PostForm.nested.comments // CommentForm
|
|
248
417
|
|
|
249
418
|
PostForm.Message.RowAdded({ key: 'comments' })
|
|
250
419
|
PostForm.Message.RowRemoved({ key: 'comments', row: 'r0' })
|
|
@@ -257,17 +426,25 @@ PostForm.rows(PostForm.initial, 'comments') // [{ id, model }], each a Model of
|
|
|
257
426
|
| a `one` that admits `null` or `undefined` | none or one; none submits that nothing |
|
|
258
427
|
| a `many` | any number, starting with none |
|
|
259
428
|
|
|
260
|
-
-
|
|
261
|
-
|
|
429
|
+
- **The nested form is one you make and pass** (`nested: { comments: CommentForm }`),
|
|
430
|
+
from the same input `Relation.nested` was given. The form that edits a comment
|
|
431
|
+
alone is the form a post nests, with its controls, checks and words. A nested
|
|
432
|
+
key given none gets a plain form of its input, with this form's `messages` and
|
|
433
|
+
`debounce`. A form of another input throws.
|
|
434
|
+
- **A row is addressed with types.** `PostForm.row('comments', id)` has the nested
|
|
435
|
+
form's own constructors (`Changed`, `Blurred`, `Searched`, `RowAdded`, ...), each
|
|
436
|
+
giving `PostForm`'s Message, and `send(message)` for one already made, which is
|
|
437
|
+
how a row inside a row is reached. `PostForm.nested.comments` is the form
|
|
438
|
+
itself. Underneath it is `Message.Nested({ key, row, message })`. A Message for a row that is gone, or
|
|
262
439
|
that is not one of the nested form, is dropped. A row's id is never reused.
|
|
263
|
-
- A nested key's control is
|
|
440
|
+
- A nested key's control is of kind `Nested`, with `data` `{ cardinality, optional, form }`
|
|
441
|
+
(narrow it with `Input.Nested.is(control)`);
|
|
264
442
|
`form` is the nested form, with its own `controls`, `field`, and `rows`. Nested
|
|
265
443
|
keys are in `model.rows`, not `model.fields`.
|
|
266
444
|
- A submit validates every row too and shows every failure; it waits for a check
|
|
267
445
|
running in a row as it does for its own. A rule on the list itself
|
|
268
446
|
(`Schema.isMaxLength(5)`) is a failure of the whole, in `errors`.
|
|
269
447
|
- `fill` fills rows from values, and nesting goes as deep as the inputs do.
|
|
270
|
-
- `messages` and `debounce` reach nested forms unless they bring their own.
|
|
271
448
|
|
|
272
449
|
## Editing existing values
|
|
273
450
|
|
|
@@ -290,7 +467,7 @@ const prefill = RenameForm.helpers.fill(Entity.valuesFor(Rename.input, loaded))
|
|
|
290
467
|
|
|
291
468
|
A relation is loaded as a ref and read back as the id the form holds. See
|
|
292
469
|
[`foldkit-entity`](../entity/README.md#showing-what-is-there).
|
|
293
|
-
[`foldkit-
|
|
470
|
+
[`foldkit-crud`](../crud/README.md) does this, the save, and its status for you.
|
|
294
471
|
|
|
295
472
|
## Limits
|
|
296
473
|
|