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 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, so a form that is made is a form that can be
90
- drawn.
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: the kind of editing, with nothing about how it is drawn.
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
- | Control | Draft | Chosen when |
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
- notANumber: field => `${field.label} must be a number`,
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
- | `notANumber(field)` | a `Number` control whose draft is not a number | `Enter a number` |
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
- const PostForm = Form.make('PostForm', CreatePost, {
245
- // A nested key's form takes what any form takes.
246
- nested: { comments: { inputs: { body: Input.multiline() } } },
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
- - A row is edited with the nested form's own Messages, wrapped:
261
- `Message.Nested({ key, row, message })`. A Message for a row that is gone, or
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 `{ _tag: 'Nested', cardinality, optional, form }`;
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-admin`](../admin/README.md) does this, the save, and its status for you.
470
+ [`foldkit-crud`](../crud/README.md) does this, the save, and its status for you.
294
471
 
295
472
  ## Limits
296
473