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 CHANGED
@@ -100,9 +100,12 @@ const RenameForm = Page.at(Slot, {
100
100
 
101
101
  ## Controls
102
102
 
103
- A control is data: the kind of editing, with nothing about how it is drawn.
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
- | Control | Draft | Chosen when |
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
- notANumber: field => `${field.label} must be a number`,
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
- | `notANumber(field)` | a `Number` control whose draft is not a number | `Enter a number` |
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
- 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
- })
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
- - 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
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 `{ _tag: 'Nested', cardinality, optional, form }`;
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-admin`](../admin/README.md) does this, the save, and its status for you.
446
+ [`foldkit-crud`](../crud/README.md) does this, the save, and its status for you.
294
447
 
295
448
  ## Limits
296
449