foldkit-form 0.1.0 → 0.1.1
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 +166 -13
- 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 +3 -3
package/README.md
CHANGED
|
@@ -100,9 +100,12 @@ const RenameForm = Page.at(Slot, {
|
|
|
100
100
|
|
|
101
101
|
## Controls
|
|
102
102
|
|
|
103
|
-
A control is data:
|
|
103
|
+
A control is data: a `kind` (a name), the `draft` the Model holds while it is
|
|
104
|
+
edited, and whatever `data` its kind needs, with nothing about how it is drawn.
|
|
105
|
+
There is one primitive, and every kind is a value of it, the ones below
|
|
106
|
+
included.
|
|
104
107
|
|
|
105
|
-
|
|
|
108
|
+
| Kind | Draft | Chosen when |
|
|
106
109
|
| --- | --- | --- |
|
|
107
110
|
| `Text`, `Multiline` | `string` | the schema is a string (`Multiline` only when asked for) |
|
|
108
111
|
| `Hidden` | `string` | only when asked for: a key the form carries and does not show, such as the id being edited |
|
|
@@ -129,6 +132,79 @@ const Cms = Post.pipe(Entity.annotateMembers({ title: Input.of(Input.multiline()
|
|
|
129
132
|
Form.make('Rename', Entity.input(Cms, RenameInput), { inputs: { id: Input.text() } })
|
|
130
133
|
```
|
|
131
134
|
|
|
135
|
+
### Your own kind of control
|
|
136
|
+
|
|
137
|
+
The kinds above are made with `Input.kind`, and so is a date picker, a rich text
|
|
138
|
+
editor, or a price:
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
const Cents = Input.kind<{ readonly currency: string }>('Cents', {
|
|
142
|
+
draft: 'text', // what the Model holds while it is edited
|
|
143
|
+
// The value the schema is given, when that is not the text itself.
|
|
144
|
+
parse: draft => (/^\d+(\.\d{1,2})?$/.test(draft) ? Math.round(Number(draft) * 100) : undefined),
|
|
145
|
+
unparsed: 'Enter an amount',
|
|
146
|
+
})
|
|
147
|
+
|
|
148
|
+
Form.make('Price', input, { inputs: { cents: Cents.of({ currency: 'USD' }) } })
|
|
149
|
+
|
|
150
|
+
Cents.is(control) && control.data.currency // 'USD'
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
- `draft` is `'text'`, `'flag'` (a boolean) or `'list'` (ids).
|
|
154
|
+
- `parse` reads text as something else before the key's schema sees it, as
|
|
155
|
+
`Number` does; `undefined` means it does not read, and `unparsed` is what to
|
|
156
|
+
say. Text that is only spaces is nothing entered, not a failure to parse.
|
|
157
|
+
- `shown: false` makes a kind that is carried and not drawn, as `Hidden` is.
|
|
158
|
+
- Nothing else in the form treats a shipped kind differently. A view draws your
|
|
159
|
+
kind once it has a renderer for it; see
|
|
160
|
+
[`foldkit-mixins-form`](../mixins-form/README.md#renderers).
|
|
161
|
+
|
|
162
|
+
### A key that follows another
|
|
163
|
+
|
|
164
|
+
A slug is its title until the author decides otherwise. `Input.following` keeps
|
|
165
|
+
the key's own control and writes its draft from another key:
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
const PostForm = Form.make('PostForm', input, {
|
|
169
|
+
inputs: { slug: Input.following('title', slugify) },
|
|
170
|
+
})
|
|
171
|
+
|
|
172
|
+
PostForm.isFollowing(model, 'slug') // false once the author has written it
|
|
173
|
+
PostForm.partial(model) // what decodes as it stands, by key: for saving unfinished work
|
|
174
|
+
PostForm.settled(model) // a stored Model, shown again with no check or submit in flight
|
|
175
|
+
PostForm.Message.Refused({ key: 'slug', error: 'That address is taken' }) // a server's word, on its key
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
- While the author has not written the key, each edit of the key it follows
|
|
179
|
+
rewrites it, through the function given, and it is validated and checked as if
|
|
180
|
+
typed. With nothing to follow yet it shows no failure; a submit still does.
|
|
181
|
+
- **Once they write it, it is theirs**, and the key it followed moves on without
|
|
182
|
+
it. Emptying it hands it back, which is how a view offers "regenerate".
|
|
183
|
+
- **A form filled with a value for it does not follow.** An address that is
|
|
184
|
+
already published must not move because its title was edited. Filled with
|
|
185
|
+
nothing for it, it follows.
|
|
186
|
+
- A key may follow a key that follows. A key that follows itself, through any
|
|
187
|
+
chain, or that follows something that is not another text key of the form, is
|
|
188
|
+
refused when the form is made.
|
|
189
|
+
|
|
190
|
+
### A picker that searches
|
|
191
|
+
|
|
192
|
+
A relation usually has too many targets to list. `Input.search()` keeps the
|
|
193
|
+
key's picker and gives it a search:
|
|
194
|
+
|
|
195
|
+
```ts
|
|
196
|
+
const EditPost = Form.make('EditPost', input, { inputs: { authorId: Input.search() } })
|
|
197
|
+
|
|
198
|
+
EditPost.Message.Searched({ key: 'authorId', text: 'ad' })
|
|
199
|
+
EditPost.search(model, 'authorId') // 'ad'
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
The form holds what was typed and does nothing else with it: it changes no
|
|
203
|
+
draft and validates nothing. The application reads it as the input of the query
|
|
204
|
+
that lists the choices, so finding an author is an ordinary query. A fill or a
|
|
205
|
+
reset starts the search over. `Input.search()` on a key that is not a relation
|
|
206
|
+
throws.
|
|
207
|
+
|
|
132
208
|
### Labels
|
|
133
209
|
|
|
134
210
|
A label is the schema's own `title` annotation, and the description its
|
|
@@ -186,6 +262,16 @@ const PostForm = Form.make('PostForm', Entity.input(Post, PostInput), {
|
|
|
186
262
|
this. `Valid` on a checked key means the check passed.
|
|
187
263
|
- The form does not know what answers. The check's requirements (`R`) become the
|
|
188
264
|
Bundle's, so a check that needs `RemoteClient` makes the placement need it.
|
|
265
|
+
**Add such a check with the `Form.checks` step, not in `Form.make`'s options:**
|
|
266
|
+
Effect's `R` is not an inference site a mapped type can win, so `Form.make`
|
|
267
|
+
reads it as `never` and refuses the check ("`RemoteClient` is not assignable to
|
|
268
|
+
`never`"). The step reads the requirement off the functions it is given.
|
|
269
|
+
|
|
270
|
+
```ts
|
|
271
|
+
const PostForm = Form.make('PostForm', Entity.input(Post, PostInput), {
|
|
272
|
+
debounce: 0,
|
|
273
|
+
}).pipe(Form.checks({ slug: isAddressFree }))
|
|
274
|
+
```
|
|
189
275
|
- Each edit asks again after `debounce`, and an answer for a draft the key no
|
|
190
276
|
longer holds is dropped.
|
|
191
277
|
- **A submit waits.** Submitted while a check runs, the form sets `submitPending`
|
|
@@ -194,6 +280,14 @@ const PostForm = Form.make('PostForm', Entity.input(Post, PostInput), {
|
|
|
194
280
|
checked on submit the same way.
|
|
195
281
|
- `context.values` holds the other keys that currently decode, which is how an
|
|
196
282
|
edit form lets a post keep its own slug.
|
|
283
|
+
- `context.subject` is what the form is editing, for what its values do not say.
|
|
284
|
+
A post's input carries a title and an address, not the row's id, so "is this
|
|
285
|
+
address taken?" cannot tell the post's own address from someone else's. Send
|
|
286
|
+
`Message.About({ subject: { id } })` once when the form opens on a row, and the
|
|
287
|
+
check has it; `form.subject(model)` reads it back. A form that creates
|
|
288
|
+
something is about nothing, which is the `{}` it starts with. It changes no
|
|
289
|
+
draft, answers no submit, and survives `fill` and `Reset`: which row the form
|
|
290
|
+
is about does not change because its contents did.
|
|
197
291
|
|
|
198
292
|
### Messages
|
|
199
293
|
|
|
@@ -211,7 +305,7 @@ rewrites what Schema says by default, which is also how a form is translated:
|
|
|
211
305
|
const Rename = Form.make('Rename', Entity.input(Post, RenameInput), {
|
|
212
306
|
messages: {
|
|
213
307
|
required: field => `${field.label} is missing`,
|
|
214
|
-
|
|
308
|
+
unparsed: field => `${field.label} must be a number`,
|
|
215
309
|
invalid: (field, message) => `${field.label}: ${message}`,
|
|
216
310
|
form: message => message,
|
|
217
311
|
},
|
|
@@ -221,12 +315,61 @@ const Rename = Form.make('Rename', Entity.input(Post, RenameInput), {
|
|
|
221
315
|
| Message | Said when | Default |
|
|
222
316
|
| --- | --- | --- |
|
|
223
317
|
| `required(field)` | an empty draft the schema does not admit | `Required` |
|
|
224
|
-
| `
|
|
318
|
+
| `unparsed(field)` | text its control cannot read, such as a `Number` that is not one | the kind's own words (`Enter a number`) |
|
|
225
319
|
| `invalid(field, message)` | the key's schema rejects the draft; `message` is the check's own, or Schema's | `message` |
|
|
226
320
|
| `form(message)` | the input as a whole fails: a rule that spans keys | `message` |
|
|
227
321
|
|
|
228
322
|
`field` is the key, its label, and its control.
|
|
229
323
|
|
|
324
|
+
### Words as text, in one place
|
|
325
|
+
|
|
326
|
+
Each of these may be text with blanks instead of a function: `'{label} is required'`
|
|
327
|
+
(`{label}`, `{key}`, and `{message}` where there is one). Text can be kept in a
|
|
328
|
+
translation catalogue, and it can go where a function cannot: Foldkit admits no
|
|
329
|
+
function nested in a placed view's inputs. The drawn packages' words are text
|
|
330
|
+
too, and the three shapes share no key, so an application writes its words once:
|
|
331
|
+
|
|
332
|
+
```ts
|
|
333
|
+
import type { FormMessages } from 'foldkit-form'
|
|
334
|
+
import type { ViewWords } from 'foldkit-mixins-crud'
|
|
335
|
+
import type { FormViewWords } from 'foldkit-mixins-form'
|
|
336
|
+
|
|
337
|
+
export const words = {
|
|
338
|
+
required: '{label} is required', // foldkit-form
|
|
339
|
+
submit: 'Save', // foldkit-mixins-form
|
|
340
|
+
add: 'Another {label}',
|
|
341
|
+
yes: 'Live', // foldkit-mixins-crud
|
|
342
|
+
empty: 'No posts yet.',
|
|
343
|
+
} satisfies FormMessages & FormViewWords & ViewWords
|
|
344
|
+
|
|
345
|
+
Form.make('EditPost', input, { messages: words })
|
|
346
|
+
placed.view(model, h, { options, words })
|
|
347
|
+
PostTable({ page, words }, h)
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
`fillWords(template, values)` is the blank-filling they all use.
|
|
351
|
+
|
|
352
|
+
## Pipe steps
|
|
353
|
+
|
|
354
|
+
Every option is also a pipe step that gives a new form, made from the same input
|
|
355
|
+
with that option added to:
|
|
356
|
+
|
|
357
|
+
```ts
|
|
358
|
+
const AuthorForm = Form.make('Author', NewAuthor) // as a library might hand it over
|
|
359
|
+
|
|
360
|
+
const Finished = AuthorForm.pipe(
|
|
361
|
+
Form.inputs({ bio: Input.multiline() }),
|
|
362
|
+
Form.checks({ name: name => isNameTaken(name) }),
|
|
363
|
+
Form.messages({ required: field => `${field.label} fehlt` }),
|
|
364
|
+
)
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
`Form.inputs`, `Form.checks`, `Form.messages`, `Form.nested` and `Form.debounce`.
|
|
368
|
+
Each adds to what the form already has, so a form can be made in one place and
|
|
369
|
+
finished in another. A step's keys are checked against the form it is piped
|
|
370
|
+
into, and `Form.checks` adds what its checks need to what the form needs. The
|
|
371
|
+
first form is left as it was.
|
|
372
|
+
|
|
230
373
|
## Nested input
|
|
231
374
|
|
|
232
375
|
A key mapped with [`Relation.nested`](../entity/README.md#an-input-that-holds-the-target-itself)
|
|
@@ -241,10 +384,12 @@ const CreatePost = Entity.input(
|
|
|
241
384
|
{ comments: Relation.nested(Blog.Post.relations.comments, NewComment) },
|
|
242
385
|
)
|
|
243
386
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
387
|
+
// The form that edits a comment alone is the form a post's form nests.
|
|
388
|
+
const CommentForm = Form.make('Comment', NewComment, { inputs: { body: Input.multiline() } })
|
|
389
|
+
const PostForm = Form.make('PostForm', CreatePost, { nested: { comments: CommentForm } })
|
|
390
|
+
|
|
391
|
+
PostForm.row('comments', 'r0').Changed({ key: 'body', value: 'First' }) // a Message of PostForm
|
|
392
|
+
PostForm.nested.comments // CommentForm
|
|
248
393
|
|
|
249
394
|
PostForm.Message.RowAdded({ key: 'comments' })
|
|
250
395
|
PostForm.Message.RowRemoved({ key: 'comments', row: 'r0' })
|
|
@@ -257,17 +402,25 @@ PostForm.rows(PostForm.initial, 'comments') // [{ id, model }], each a Model of
|
|
|
257
402
|
| a `one` that admits `null` or `undefined` | none or one; none submits that nothing |
|
|
258
403
|
| a `many` | any number, starting with none |
|
|
259
404
|
|
|
260
|
-
-
|
|
261
|
-
|
|
405
|
+
- **The nested form is one you make and pass** (`nested: { comments: CommentForm }`),
|
|
406
|
+
from the same input `Relation.nested` was given. The form that edits a comment
|
|
407
|
+
alone is the form a post nests, with its controls, checks and words. A nested
|
|
408
|
+
key given none gets a plain form of its input, with this form's `messages` and
|
|
409
|
+
`debounce`. A form of another input throws.
|
|
410
|
+
- **A row is addressed with types.** `PostForm.row('comments', id)` has the nested
|
|
411
|
+
form's own constructors (`Changed`, `Blurred`, `Searched`, `RowAdded`, ...), each
|
|
412
|
+
giving `PostForm`'s Message, and `send(message)` for one already made, which is
|
|
413
|
+
how a row inside a row is reached. `PostForm.nested.comments` is the form
|
|
414
|
+
itself. Underneath it is `Message.Nested({ key, row, message })`. A Message for a row that is gone, or
|
|
262
415
|
that is not one of the nested form, is dropped. A row's id is never reused.
|
|
263
|
-
- A nested key's control is
|
|
416
|
+
- A nested key's control is of kind `Nested`, with `data` `{ cardinality, optional, form }`
|
|
417
|
+
(narrow it with `Input.Nested.is(control)`);
|
|
264
418
|
`form` is the nested form, with its own `controls`, `field`, and `rows`. Nested
|
|
265
419
|
keys are in `model.rows`, not `model.fields`.
|
|
266
420
|
- A submit validates every row too and shows every failure; it waits for a check
|
|
267
421
|
running in a row as it does for its own. A rule on the list itself
|
|
268
422
|
(`Schema.isMaxLength(5)`) is a failure of the whole, in `errors`.
|
|
269
423
|
- `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
424
|
|
|
272
425
|
## Editing existing values
|
|
273
426
|
|
|
@@ -290,7 +443,7 @@ const prefill = RenameForm.helpers.fill(Entity.valuesFor(Rename.input, loaded))
|
|
|
290
443
|
|
|
291
444
|
A relation is loaded as a ref and read back as the id the form holds. See
|
|
292
445
|
[`foldkit-entity`](../entity/README.md#showing-what-is-there).
|
|
293
|
-
[`foldkit-
|
|
446
|
+
[`foldkit-crud`](../crud/README.md) does this, the save, and its status for you.
|
|
294
447
|
|
|
295
448
|
## Limits
|
|
296
449
|
|