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 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 Slot = Bundle.declare(Rename.bundle, 'rename')
76
- const Model = Schema.Struct({ ...Slot.fields, saved: Schema.Array(RenameInput) })
77
- const Message = defineMessageUnion({ ...Slot.cases })
78
-
79
- const Page = Bundle.parent({ Model, Message })
80
- const RenameForm = Page.at(Slot, {
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.assemble(RenameForm)
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
- schema admits for it, tried in order: leaving the key out, `null`, then the
251
- empty value itself. A key is `required` exactly when none is admitted, so
252
- `Schema.optional`, `Schema.NullOr`, and an array need no flag from you. A
253
- plain `Schema.String` admits `""`; add `Schema.isMinLength(1)` to require it.
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 only as a nested input of a
480
- relation's target; a free-standing struct has no control. Rows keep the order
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.