foldkit-mixins-form 0.2.0 → 0.4.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 +151 -12
- package/dist/index.d.mts +186 -2
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +194 -26
- package/dist/index.mjs.map +1 -1
- package/dist/ui.d.mts +19 -0
- package/dist/ui.d.mts.map +1 -0
- package/dist/ui.mjs +73 -0
- package/dist/ui.mjs.map +1 -0
- package/package.json +23 -10
package/README.md
CHANGED
|
@@ -15,6 +15,10 @@ what else it does.
|
|
|
15
15
|
| Classes, inline style, extra attributes and events | your `Style` / `Behavior` attachments |
|
|
16
16
|
| The options of a relation picker, the submit button's words | the application, as view inputs |
|
|
17
17
|
|
|
18
|
+
The optional `foldkit-mixins-form/ui` entry draws Text and Multiline fields
|
|
19
|
+
through `foldkit-mixins-ui`'s Input and Textarea adapters. The main entry keeps
|
|
20
|
+
the plain-HTML path and does not import that integration.
|
|
21
|
+
|
|
18
22
|
It holds no state and adds no Messages. Every event it installs dispatches one
|
|
19
23
|
of the form's own Messages (`Changed`, `Blurred`, `Submitted`).
|
|
20
24
|
|
|
@@ -65,6 +69,35 @@ Messages to its reducer; submitting a valid form sends its decoded value to
|
|
|
65
69
|
|
|
66
70
|
The next example replaces this unstyled `Drawn` with field and form styles.
|
|
67
71
|
|
|
72
|
+
## UI-backed fields with a custom layout
|
|
73
|
+
|
|
74
|
+
Install `foldkit-mixins-ui` and its `@foldkit/ui` peer to use the optional
|
|
75
|
+
`foldkit-mixins-form/ui` entry. Import it as `UiForm`.
|
|
76
|
+
|
|
77
|
+
`UiForm.field({ toMessage, inputStyle, textareaStyle?, draw? })` returns a
|
|
78
|
+
`FormView.fields` override for Text and Multiline keys. `toMessage` wraps the
|
|
79
|
+
form's Changed/Blurred Messages in the caller's Message universe (use an
|
|
80
|
+
identity function for a whole-form view). Styles target `InputSlots` and
|
|
81
|
+
`TextareaSlots`; their input is the field's validation state.
|
|
82
|
+
|
|
83
|
+
The override preserves field names, labels, required state, descriptions,
|
|
84
|
+
checking status and errors. `draw` receives `label`, `control`, `description`
|
|
85
|
+
and `field` plus the caller's HTML builder, so layout and validation marks can
|
|
86
|
+
remain application-owned. Without `draw`, it stacks the parts in a FieldSlots
|
|
87
|
+
root. Unsupported control kinds throw; keep them on the default renderer or
|
|
88
|
+
provide another override.
|
|
89
|
+
|
|
90
|
+
Use the override with `Fields.field` for a custom layout or the per-key
|
|
91
|
+
`overrides` table for `Fields.view`. Submit buttons in a custom layout use
|
|
92
|
+
`Button.view` from `foldkit-mixins-ui`; the form still owns submission and the
|
|
93
|
+
parent owns any request. The generated view retains its native submit button.
|
|
94
|
+
|
|
95
|
+
The [waitlist](../../examples/foldkit/form/src/main.ts) and
|
|
96
|
+
[login](../../examples/foldkit/auth/src/page/loggedOut/page/login.ts) are real
|
|
97
|
+
custom-layout adopters. The [UI integration tests](test/ui.test.ts) demonstrate
|
|
98
|
+
the generated view with UI field overrides through a Submodel and a strict
|
|
99
|
+
`FormView.submodel(..., { canSubmit: form.isValid })` gate.
|
|
100
|
+
|
|
68
101
|
## Example
|
|
69
102
|
|
|
70
103
|
`Edit` is a `Form.make` result, as in the
|
|
@@ -105,6 +138,8 @@ EditForm.view(model, h, {
|
|
|
105
138
|
|
|
106
139
|
- `FormView.define(Edit)` alone is a complete, unstyled form. `field` is only
|
|
107
140
|
for changing how fields are drawn.
|
|
141
|
+
- `submits: false` draws the form without its submit button, for someone who
|
|
142
|
+
may not submit it (a writer, where the submit publishes).
|
|
108
143
|
- `options` is keyed by the form's keys and is where a relation picker's choices
|
|
109
144
|
come from. The form names the target Entity; listing it is a query you make,
|
|
110
145
|
so the choices are yours to load, filter, and label.
|
|
@@ -118,17 +153,23 @@ EditForm.view(model, h, {
|
|
|
118
153
|
| `Multiline` | `textarea` | `multiline` |
|
|
119
154
|
| `Number` | `input type="text" inputmode="decimal"` | `number` |
|
|
120
155
|
| `Toggle` | `input type="checkbox"` | `toggle` |
|
|
121
|
-
| `Select` | `select` of the control's own options, with a blank while nothing is chosen | `select` |
|
|
122
|
-
| `RelationOne` | `select` of `options[key]`, with a blank | `select` |
|
|
123
|
-
| `RelationMany` | a `role="group"` of checkboxes over `options[key]` | `choices`, `choice` |
|
|
156
|
+
| `Select` | `select` of the control's own options, with a blank while nothing is chosen | `select`, `option` |
|
|
157
|
+
| `RelationOne` | `select` of `options[key]`, with a blank | `select`, `option` |
|
|
158
|
+
| `RelationMany` | a `role="group"` of checkboxes over `options[key]`, each in a `label` with its words | `choices`, `choiceLabel`, `choice` |
|
|
124
159
|
| `Nested` | a `fieldset` with a `legend`, a `div` per row holding the nested form's fields, and `button type="button"`s to add and remove a row | `group`, `legend`, `row`, `add`, `remove` |
|
|
125
160
|
|
|
126
161
|
A `RelationOne` or `RelationMany` that searches (`Input.search()`) gets an
|
|
127
162
|
`input type="search"` above it, in the `search` slot, labelled `Search <label>`
|
|
128
163
|
and naming the picker it controls with `aria-controls`. `words.search` in the
|
|
129
|
-
view inputs replaces the word.
|
|
130
|
-
|
|
131
|
-
|
|
164
|
+
view inputs replaces the word. The blank choice of a `select` has no words
|
|
165
|
+
unless `words.none` gives it some ("none"). All of the view's words (`submit`,
|
|
166
|
+
`submitting`, `checking`, `search`, `none`, `add`, `remove`) are text, with `{label}` and `{position}` as
|
|
167
|
+
blanks; see [words in one place](../form/README.md#words-as-text-in-one-place).
|
|
168
|
+
|
|
169
|
+
A chosen value its choices lack stays in sight: after the choices comes
|
|
170
|
+
`? value`, chosen, in a `select` and in a `RelationMany`'s checkboxes. It is a
|
|
171
|
+
stored id whose row is gone, or one the application has not loaded yet, and
|
|
172
|
+
the author can see it and let it go.
|
|
132
173
|
|
|
133
174
|
### Renderers
|
|
134
175
|
|
|
@@ -157,13 +198,70 @@ attributes, to put on the element that holds the value. A control whose kind has
|
|
|
157
198
|
no renderer throws when it is drawn, naming the kind and the key.
|
|
158
199
|
`FormView.field(form, { renderers })` takes them too, for a field view you style.
|
|
159
200
|
|
|
201
|
+
### Per-key overrides: `fields`
|
|
202
|
+
|
|
203
|
+
`FormView.fields` is `define` with per-key overrides, and one flat key's
|
|
204
|
+
control for a layout the caller owns:
|
|
205
|
+
|
|
206
|
+
```ts
|
|
207
|
+
const Fields = FormView.fields(PriceForm, {
|
|
208
|
+
overrides: {
|
|
209
|
+
// Drawn through the whole-form view, in the form's own universe.
|
|
210
|
+
code: (input, h) => h.input([h.Id(input.id), h.Value(String(input.field.value))]),
|
|
211
|
+
},
|
|
212
|
+
styles: {
|
|
213
|
+
// A style around one key's base field view.
|
|
214
|
+
total: Style.forSlots(FieldSlots)({ root: Style.class('total') }),
|
|
215
|
+
},
|
|
216
|
+
attrs: {
|
|
217
|
+
// What one key's element takes: an email type, a placeholder, textarea rows.
|
|
218
|
+
email: { type: 'email' },
|
|
219
|
+
},
|
|
220
|
+
})
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Keys with no override render through the base field view, so a new key of a
|
|
224
|
+
known kind needs nothing new; unknown keys in every map are type errors.
|
|
225
|
+
`Fields.view` is the whole form. `Fields.field(control, model, id, h)` draws
|
|
226
|
+
one flat key for a custom layout, or with the override it is given, in any `h`:
|
|
227
|
+
|
|
228
|
+
```ts
|
|
229
|
+
Fields.field(control, formModel, control.key, h, (input, draw) =>
|
|
230
|
+
draw.input([draw.Id(input.id), draw.Value(String(input.field.value))]),
|
|
231
|
+
)
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
A override receives the control, its field, id, validity, errors, element
|
|
235
|
+
attrs, and the `changed`/`blurred` Messages, so a custom layout reconstructs
|
|
236
|
+
no form plumbing. A renderer reads the attrs that fit its element — `type` and
|
|
237
|
+
`placeholder` on a text input, `placeholder` and `rows` on a textarea — and
|
|
238
|
+
ignores the rest. Nested keys and Bundle-backed keys draw only through `view`
|
|
239
|
+
(or a override); `field` without one refuses them, naming the key.
|
|
240
|
+
|
|
160
241
|
A number is a text input because its draft is text: `"4."` is a fine thing to
|
|
161
242
|
have typed, and `type="number"` would refuse to report it.
|
|
162
243
|
|
|
244
|
+
A control backed by a Bundle ([`Input.bundle`](../form/README.md#a-control-with-a-model-of-its-own))
|
|
245
|
+
is drawn with the Bundle's own view when no renderer names its kind, inside the
|
|
246
|
+
field's `control` slot, which carries the control's id and accessibility state.
|
|
247
|
+
A renderer for its kind receives `bundle`: the Bundle's Model, and `send`, which
|
|
248
|
+
turns one of the Bundle's Messages into the form's (wrapped for its row inside a
|
|
249
|
+
nested form). Such a key has no draft, so `draft` and `input.field.value` are
|
|
250
|
+
`''`; its validation state is `input.field`'s. A Bundle with no view needs a
|
|
251
|
+
renderer.
|
|
252
|
+
|
|
163
253
|
Around each control, `FieldSlots` also publishes `root`, `label`, `description`,
|
|
164
|
-
|
|
254
|
+
`checking`, `error`, `control` (around a Bundle's own view), and `group` and `affix`, for a
|
|
255
|
+
renderer that draws text beside its control (a prefix, a unit) with the two
|
|
256
|
+
together. `FormSlots` publishes `root` (the `form`), `errors` (failures that
|
|
165
257
|
belong to no one field), `submit`, and the five slots of a nested key.
|
|
166
258
|
|
|
259
|
+
A Bundle's own view that takes inputs gets them from the view input
|
|
260
|
+
`controls`, by key: `placed.view(model, h, { controls: { document: inputs } })`.
|
|
261
|
+
The entry is the application's, typed where it is made, such as the page
|
|
262
|
+
Builder's `BuilderView.inputs({ data })`; a key given none draws its view
|
|
263
|
+
without inputs.
|
|
264
|
+
|
|
167
265
|
A nested row's fields are drawn through the same field view, so a styled `field`
|
|
168
266
|
styles them too. A row that must be there has no remove button, and a `one`
|
|
169
267
|
loses its add button once it has its row. View inputs for nested keys:
|
|
@@ -171,13 +269,54 @@ loses its add button once it has its row. View inputs for nested keys:
|
|
|
171
269
|
same for every row), and `words.add` / `words.remove` word the buttons (defaults
|
|
172
270
|
`Add <label>`, `Remove <label> <position>`).
|
|
173
271
|
|
|
272
|
+
### A check running, and a submit in flight
|
|
273
|
+
|
|
274
|
+
A form's own check ([`checks`](../form/README.md)) leaves its key `Validating`
|
|
275
|
+
until it answers. Meanwhile the control carries `aria-busy`, and under it a line
|
|
276
|
+
in the `checking` slot, `role="status"`, says so (`words.checking`, default
|
|
277
|
+
`Checking…`); the control names that line in `aria-describedby`. Each field's
|
|
278
|
+
`root` carries `data-validation`, the field's state by Foldkit's own tag
|
|
279
|
+
(`NotValidated`, `Validating`, `Valid` or `Invalid`), so a stylesheet can mark it
|
|
280
|
+
without a Style: `[data-validation='Valid'] label::after { content: ' ✓' }`. A
|
|
281
|
+
Style reads the same state as `input.field` through `Style.whenInput`.
|
|
282
|
+
|
|
283
|
+
The form is submitting while a submit waits for a check to pass (the form's
|
|
284
|
+
`submitPending`), or while the application says its own work with the value is
|
|
285
|
+
in flight: the view input `submitting`. The form hands the value over through
|
|
286
|
+
`onOut` and cannot see the request that follows, so that part is the
|
|
287
|
+
application's to pass. While submitting, the `form` carries `aria-busy` and
|
|
288
|
+
`data-submitting`, and the submit button is disabled and reads
|
|
289
|
+
`words.submitting` (default `Submitting…`). Where `saving` is the parent's own
|
|
290
|
+
record of a save in flight:
|
|
291
|
+
|
|
292
|
+
```ts
|
|
293
|
+
EditForm.view(model, h, {
|
|
294
|
+
submitting: model.saving,
|
|
295
|
+
words: { submit: 'Save', submitting: 'Saving…', checking: 'Checking…' },
|
|
296
|
+
})
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
The submit button is enabled while a check runs and nothing is invalid: a submit
|
|
300
|
+
then waits for the answer, rather than being refused. That leniency is
|
|
301
|
+
`form.canSubmit`, and `FormView.submodel` takes the predicate explicitly so
|
|
302
|
+
the choice stays visible: pass a strict one to disable through checks, or
|
|
303
|
+
`() => true` to never pre-disable and validate wholly at submit.
|
|
304
|
+
|
|
305
|
+
```ts
|
|
306
|
+
const Drawn = Edit.bundle.pipe(
|
|
307
|
+
Bundle.withView(FormView.submodel(Edit, View, { canSubmit: () => true })),
|
|
308
|
+
)
|
|
309
|
+
```
|
|
310
|
+
|
|
174
311
|
### Accessibility
|
|
175
312
|
|
|
176
313
|
Each control has an `id` of `<form name>-<key>` (in a row,
|
|
177
314
|
`<form name>-<key>-<row id>-<key>`) and a `label for` it. It carries
|
|
178
|
-
`aria-busy` while a check runs, `aria-invalid`, `aria-required` when the key is
|
|
179
|
-
|
|
180
|
-
|
|
315
|
+
`aria-busy` while a check runs, `aria-invalid`, `aria-required` when the key is
|
|
316
|
+
required, and `aria-describedby` naming its description, the `checking` line
|
|
317
|
+
while a check runs, and its error while invalid. An error is `role="alert"`.
|
|
318
|
+
The submit button is disabled until the form would submit, and while it is
|
|
319
|
+
submitting.
|
|
181
320
|
|
|
182
321
|
Those attributes belong to the view: an attachment that also supplies one is an
|
|
183
322
|
attribute conflict, reported when the view renders. The slots declare
|
|
@@ -185,8 +324,8 @@ attribute conflict, reported when the view renders. The slots declare
|
|
|
185
324
|
|
|
186
325
|
## Limits
|
|
187
326
|
|
|
188
|
-
- One layout: label, control, description, error, in that
|
|
189
|
-
the input's order. For another arrangement, draw from `form.controls`
|
|
327
|
+
- One layout: label, control, description, the checking line, error, in that
|
|
328
|
+
order, and fields in the input's order. For another arrangement, draw from `form.controls`
|
|
190
329
|
yourself; this package is the default, not the only way.
|
|
191
330
|
- A relation picker is a `select`, or checkboxes for a `many`. With
|
|
192
331
|
`Input.search()` it searches, but it is not a combobox: the choices are the
|
package/dist/index.d.mts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { Control, Draft, FormControl, FormRow } from "foldkit-form";
|
|
2
|
-
import { Attr, Capability, Event, Slot, SlotBuilders, SlotView, Slots } from "foldkit-mixins";
|
|
2
|
+
import { Attr, Capability, Event, NamedStyle, Slot, SlotBuilders, SlotView, Slots } from "foldkit-mixins";
|
|
3
3
|
import * as FieldValidation from "foldkit/fieldValidation";
|
|
4
4
|
import * as Submodel from "foldkit/submodel";
|
|
5
5
|
import { Attribute, Html, HtmlBuilder } from "foldkit/html";
|
|
@@ -21,10 +21,16 @@ export interface FormViewWords {
|
|
|
21
21
|
readonly submit?: string | undefined;
|
|
22
22
|
/** Before the label on a picker's search box (`Search Author`). Default `Search`. */
|
|
23
23
|
readonly search?: string | undefined;
|
|
24
|
+
/** The choice of nothing, in a picker that may be left empty. Default: blank. */
|
|
25
|
+
readonly none?: string | undefined;
|
|
24
26
|
/** On the button that adds a row to a nested key. Default `Add {label}`. */
|
|
25
27
|
readonly add?: string | undefined;
|
|
26
28
|
/** On the button that removes a row; `{position}` counts from 1. Default `Remove {label} {position}`. */
|
|
27
29
|
readonly remove?: string | undefined;
|
|
30
|
+
/** Under a control while its check runs. Default `Checking…`. */
|
|
31
|
+
readonly checking?: string | undefined;
|
|
32
|
+
/** On the submit button while the form is submitting. Default `Submitting…`. */
|
|
33
|
+
readonly submitting?: string | undefined;
|
|
28
34
|
}
|
|
29
35
|
/**
|
|
30
36
|
* What the view needs that the form does not own: the choices of each relation
|
|
@@ -37,8 +43,27 @@ export interface FormViewInputs<Key extends string = string> {
|
|
|
37
43
|
* row: `'author.country'`.
|
|
38
44
|
*/
|
|
39
45
|
readonly nestedOptions?: Readonly<Record<string, ReadonlyArray<Option>>> | undefined;
|
|
46
|
+
/**
|
|
47
|
+
* What a control backed by a Bundle is drawn with, by key: its view's inputs,
|
|
48
|
+
* such as the page Builder's `BuilderView.inputs({ data })`. A key in a nested
|
|
49
|
+
* row is named by its path, as in `nestedOptions`. Keyed by text, as those
|
|
50
|
+
* paths are, and typed where each entry is made, since only the control's
|
|
51
|
+
* Bundle knows its view's inputs.
|
|
52
|
+
*/
|
|
53
|
+
readonly controls?: Readonly<Record<string, unknown>> | undefined;
|
|
40
54
|
/** The view's own words, for wording and for translation. */
|
|
41
55
|
readonly words?: FormViewWords | undefined;
|
|
56
|
+
/**
|
|
57
|
+
* Whether the form is drawn with its submit button. Default: it is. `false`
|
|
58
|
+
* for someone who may not submit it, such as a writer where submitting
|
|
59
|
+
* publishes, so what would be refused is not offered.
|
|
60
|
+
*/
|
|
61
|
+
readonly submits?: boolean | undefined;
|
|
62
|
+
/**
|
|
63
|
+
* Whether the application's own work with a submitted value is in flight, such
|
|
64
|
+
* as its request: the form hands the value over and cannot see what follows.
|
|
65
|
+
*/
|
|
66
|
+
readonly submitting?: boolean | undefined;
|
|
42
67
|
}
|
|
43
68
|
/** What a field's Style and Behavior attachments may read. */
|
|
44
69
|
export interface FieldInput<Key extends string = string> {
|
|
@@ -51,6 +76,10 @@ export interface FieldInput<Key extends string = string> {
|
|
|
51
76
|
readonly id: string;
|
|
52
77
|
/** The word before the label on its search box: the view's `words.search`. */
|
|
53
78
|
readonly searchWord?: string | undefined;
|
|
79
|
+
/** The choice of nothing in a picker: the view's `words.none`. */
|
|
80
|
+
readonly noneWord?: string | undefined;
|
|
81
|
+
/** What is said while the key's check runs: the view's `words.checking`. */
|
|
82
|
+
readonly checkingWord?: string | undefined;
|
|
54
83
|
/**
|
|
55
84
|
* Set for a field in a row of a nested key: its Messages, wrapped for the row.
|
|
56
85
|
* A field of the form itself sends the form's own.
|
|
@@ -60,6 +89,12 @@ export interface FieldInput<Key extends string = string> {
|
|
|
60
89
|
readonly blurred: unknown;
|
|
61
90
|
readonly searched: (text: string) => unknown;
|
|
62
91
|
} | undefined;
|
|
92
|
+
/**
|
|
93
|
+
* Set for a key edited by a control backed by a Bundle (`Input.bundle`): the
|
|
94
|
+
* Bundle's Model, and the Message that carries one of its own. Such a key has
|
|
95
|
+
* no draft, so `field.value` is `''`; its validation state is `field`'s.
|
|
96
|
+
*/
|
|
97
|
+
readonly bundle?: BundleInput | undefined;
|
|
63
98
|
/** What was typed to find a choice, for a relation picker that searches. */
|
|
64
99
|
readonly search: string;
|
|
65
100
|
/**
|
|
@@ -68,11 +103,23 @@ export interface FieldInput<Key extends string = string> {
|
|
|
68
103
|
*/
|
|
69
104
|
readonly following: boolean;
|
|
70
105
|
}
|
|
106
|
+
/** A control backed by a Bundle, as its field is drawn: its Model, and how its Messages leave. */
|
|
107
|
+
export interface BundleInput {
|
|
108
|
+
readonly model: unknown;
|
|
109
|
+
readonly send: (message: unknown) => unknown;
|
|
110
|
+
/** What the view's `controls` gives this key, for the Bundle's own view. */
|
|
111
|
+
readonly viewInputs?: unknown;
|
|
112
|
+
}
|
|
71
113
|
/** What the form's own Style and Behavior attachments may read. */
|
|
72
114
|
export interface FormInput<Model, Key extends string = string> extends FormViewInputs<Key> {
|
|
73
115
|
readonly model: Model;
|
|
74
116
|
readonly errors: ReadonlyArray<string>;
|
|
75
117
|
readonly canSubmit: boolean;
|
|
118
|
+
/**
|
|
119
|
+
* Whether the form is submitting: a submit waits for a check, or the
|
|
120
|
+
* application's work with the value is in flight. `FormView.submodel` reads both.
|
|
121
|
+
*/
|
|
122
|
+
readonly submitting?: boolean | undefined;
|
|
76
123
|
}
|
|
77
124
|
/** One field: the control for a key, and what stands around it. */
|
|
78
125
|
export declare const FieldSlots: Slots.Contract<{
|
|
@@ -80,15 +127,27 @@ export declare const FieldSlots: Slots.Contract<{
|
|
|
80
127
|
readonly label: Slot.UnnamedSlot<Capability.Capability<"Base", readonly []>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
|
|
81
128
|
readonly description: Slot.UnnamedSlot<Capability.Capability<"Base", readonly []>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
|
|
82
129
|
readonly error: Slot.UnnamedSlot<Capability.Capability<"Base", readonly []>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
|
|
130
|
+
/** Says the key's check is running, while it runs. The control names it in `aria-describedby`. */
|
|
131
|
+
readonly checking: Slot.UnnamedSlot<Capability.Capability<"Base", readonly []>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
|
|
83
132
|
readonly text: Slot.UnnamedSlot<Capability.Capability<"TextInput", readonly [Capability.Capability<"Focusable", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>]>, readonly [Event.EventToken<"input">, Event.EventToken<"blur">], readonly [Attr.AttrToken<"aria-invalid">, Attr.AttrToken<"aria-describedby">], readonly Slot.RequirementName[], boolean>;
|
|
84
133
|
readonly multiline: Slot.UnnamedSlot<Capability.Capability<"TextInput", readonly [Capability.Capability<"Focusable", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>]>, readonly [Event.EventToken<"input">, Event.EventToken<"blur">], readonly [Attr.AttrToken<"aria-invalid">, Attr.AttrToken<"aria-describedby">], readonly Slot.RequirementName[], boolean>;
|
|
85
134
|
readonly number: Slot.UnnamedSlot<Capability.Capability<"TextInput", readonly [Capability.Capability<"Focusable", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>]>, readonly [Event.EventToken<"input">, Event.EventToken<"blur">], readonly [Attr.AttrToken<"aria-invalid">, Attr.AttrToken<"aria-describedby">], readonly Slot.RequirementName[], boolean>;
|
|
86
135
|
readonly toggle: Slot.UnnamedSlot<Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>, readonly [Event.EventToken<"click">, Event.EventToken<"blur">], readonly [Attr.AttrToken<"aria-invalid">, Attr.AttrToken<"aria-describedby">], readonly Slot.RequirementName[], boolean>;
|
|
87
136
|
/** A `Select`, and a `RelationOne` picker. */
|
|
88
137
|
readonly select: Slot.UnnamedSlot<Capability.Capability<"Focusable", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly [Event.EventToken<"change">, Event.EventToken<"blur">], readonly [Attr.AttrToken<"aria-invalid">, Attr.AttrToken<"aria-describedby">], readonly Slot.RequirementName[], boolean>;
|
|
138
|
+
/** One choice of a `select`. */
|
|
139
|
+
readonly option: Slot.UnnamedSlot<Capability.Capability<"Base", readonly []>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
|
|
140
|
+
/** Around the view of a control backed by a Bundle, when it is drawn with the Bundle's own view. */
|
|
141
|
+
readonly control: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
|
|
142
|
+
/** Around a control and its affixes, such as an address's prefix and its input. */
|
|
143
|
+
readonly group: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
|
|
144
|
+
/** Text beside a control, before or after it: a prefix, or a unit. */
|
|
145
|
+
readonly affix: Slot.UnnamedSlot<Capability.Capability<"Base", readonly []>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
|
|
89
146
|
/** A `RelationMany` picker: the group, and each thing in it. */
|
|
90
147
|
readonly choices: Slot.UnnamedSlot<Capability.Capability<"Collection", readonly [Capability.Capability<"Base", readonly []>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
|
|
91
148
|
readonly choice: Slot.UnnamedSlot<Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>, readonly [Event.EventToken<"click">], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
|
|
149
|
+
/** Around one choice's checkbox and its words. */
|
|
150
|
+
readonly choiceLabel: Slot.UnnamedSlot<Capability.Capability<"Base", readonly []>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
|
|
92
151
|
/** Over a relation picker that searches: where the user types to find a choice. */
|
|
93
152
|
readonly search: Slot.UnnamedSlot<Capability.Capability<"TextInput", readonly [Capability.Capability<"Focusable", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>]>, readonly [Event.EventToken<"input">], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
|
|
94
153
|
}>;
|
|
@@ -110,6 +169,10 @@ interface FormLike<Key extends string, Model, Message> {
|
|
|
110
169
|
/** Every key, nested ones too; `Key` is the keys that hold a draft. */
|
|
111
170
|
readonly controls: ReadonlyArray<FormControl>;
|
|
112
171
|
readonly field: (model: Model, key: Key) => FieldValidation.Field<Draft>;
|
|
172
|
+
/** A key edited by a control backed by a Bundle. A form with none takes no key here. */
|
|
173
|
+
readonly control: (key: never) => {
|
|
174
|
+
readonly field: (model: Model) => FieldValidation.Field<unknown>;
|
|
175
|
+
};
|
|
113
176
|
/** The rows of a nested key. A form with none takes no key here. */
|
|
114
177
|
readonly rows: (model: Model, key: never) => ReadonlyArray<FormRow>;
|
|
115
178
|
readonly search: (model: Model, key: Key) => string;
|
|
@@ -130,6 +193,10 @@ interface FormLike<Key extends string, Model, Message> {
|
|
|
130
193
|
readonly text: string;
|
|
131
194
|
}) => NoInfer<Message>;
|
|
132
195
|
readonly Submitted: () => NoInfer<Message>;
|
|
196
|
+
readonly Control: (payload: {
|
|
197
|
+
readonly key: never;
|
|
198
|
+
readonly message: unknown;
|
|
199
|
+
}) => NoInfer<Message>;
|
|
133
200
|
readonly Nested: (payload: {
|
|
134
201
|
readonly key: string;
|
|
135
202
|
readonly row: string;
|
|
@@ -153,8 +220,20 @@ export interface RenderContext<Message> {
|
|
|
153
220
|
readonly draft: Draft;
|
|
154
221
|
readonly change: (value: Draft) => Message;
|
|
155
222
|
readonly blurred: Message;
|
|
223
|
+
/**
|
|
224
|
+
* For a control backed by a Bundle: its Model, and the Message carrying one of
|
|
225
|
+
* its own. Its `draft` is `''`.
|
|
226
|
+
*/
|
|
227
|
+
readonly bundle: {
|
|
228
|
+
readonly model: unknown;
|
|
229
|
+
readonly send: (message: unknown) => Message;
|
|
230
|
+
/** The inputs its view is drawn with: the form view's `controls` entry for this key. */
|
|
231
|
+
readonly viewInputs: unknown;
|
|
232
|
+
} | undefined;
|
|
156
233
|
/** The control's id and its accessibility state. Put them on the element that holds the value. */
|
|
157
234
|
readonly state: ReadonlyArray<Attribute<Message>>;
|
|
235
|
+
/** What the key's element takes beyond the base field view. */
|
|
236
|
+
readonly attrs: FieldAttrs;
|
|
158
237
|
readonly slots: SlotBuilders<typeof FieldSlots, Message>;
|
|
159
238
|
readonly h: HtmlBuilder<Message>;
|
|
160
239
|
}
|
|
@@ -162,12 +241,80 @@ export interface RenderContext<Message> {
|
|
|
162
241
|
export type Renderer<Message> = (context: RenderContext<Message>) => Html;
|
|
163
242
|
/** Renderers by the `kind` of control they draw. */
|
|
164
243
|
export type Renderers<Message> = Readonly<Record<string, Renderer<Message>>>;
|
|
244
|
+
/**
|
|
245
|
+
* What a per-key override receives: everything to draw the control, and the
|
|
246
|
+
* Messages that leave it, in the form's own universe. The `h` an override
|
|
247
|
+
* draws with stays the caller's: the whole-form view's, or a custom layout's.
|
|
248
|
+
*/
|
|
249
|
+
export interface FieldOverrideInput<Key extends string = string, Changed = unknown> {
|
|
250
|
+
readonly control: FormControl<Key>;
|
|
251
|
+
readonly field: FieldValidation.Field<Draft>;
|
|
252
|
+
readonly id: string;
|
|
253
|
+
readonly invalid: boolean;
|
|
254
|
+
readonly errors: ReadonlyArray<string>;
|
|
255
|
+
readonly changed: (value: Draft) => Changed;
|
|
256
|
+
readonly blurred: Changed;
|
|
257
|
+
/** What the key's element takes beyond the base field view. */
|
|
258
|
+
readonly attrs: FieldAttrs;
|
|
259
|
+
}
|
|
260
|
+
/**
|
|
261
|
+
* Draws one key's control, for a layout the base field view does not own.
|
|
262
|
+
* `Changed` is the form's Message; `Message` the universe of the `h` that
|
|
263
|
+
* draws, which is the form's in the whole-form view and the application's
|
|
264
|
+
* in a custom layout.
|
|
265
|
+
*/
|
|
266
|
+
export type FieldOverride<Key extends string = string, Changed = unknown, Message = unknown> = (input: FieldOverrideInput<Key, Changed>, h: HtmlBuilder<Message>) => Html;
|
|
267
|
+
/**
|
|
268
|
+
* What one key's element takes beyond the base field view: an HTML input
|
|
269
|
+
* type, a placeholder, a textarea's rows. A renderer reads what fits its
|
|
270
|
+
* element and ignores the rest.
|
|
271
|
+
*/
|
|
272
|
+
export interface FieldAttrs {
|
|
273
|
+
readonly type?: string | undefined;
|
|
274
|
+
readonly placeholder?: string | undefined;
|
|
275
|
+
readonly rows?: number | undefined;
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* Per-key overrides for `FormView.fields`. `overrides` draw through the
|
|
279
|
+
* whole-form view; `styles` style one key's base field view there. Unknown
|
|
280
|
+
* keys in either are type errors. A custom layout passes its override to
|
|
281
|
+
* `field` itself, with its own `h`.
|
|
282
|
+
*/
|
|
283
|
+
export interface FieldsOptions<Key extends string, Changed> {
|
|
284
|
+
/** A key drawn by this instead of the base field view (or its styled one). */
|
|
285
|
+
readonly overrides?: { readonly [K in Key]?: FieldOverride<Key, Changed, Changed>; } | undefined;
|
|
286
|
+
/** A style around a key's base field view, kept for keys with no override. */
|
|
287
|
+
readonly styles?: { readonly [K in Key]?: NamedStyle<typeof FieldSlots>; } | undefined;
|
|
288
|
+
/**
|
|
289
|
+
* What one key's element takes beyond the base field view. The text,
|
|
290
|
+
* multiline, and number renderers read them for a base field view, and a
|
|
291
|
+
* per-key override is handed them as its own `attrs` too, so it decides what
|
|
292
|
+
* to do with them; a bundle-backed kind drawn by `bundleRenderer` reads none.
|
|
293
|
+
* Passing `field` draws through the base view directly, skipping both
|
|
294
|
+
* `renderers` and `attrs`.
|
|
295
|
+
*/
|
|
296
|
+
readonly attrs?: { readonly [K in Key]?: FieldAttrs; } | undefined;
|
|
297
|
+
}
|
|
298
|
+
/**
|
|
299
|
+
* One flat key's control, for a layout the caller owns: through the base
|
|
300
|
+
* field view with a form-universe `h`, or through the override it is given,
|
|
301
|
+
* with any `h`. A call with neither a form `h` nor an override is a type
|
|
302
|
+
* error, since the base view's Messages are the form's own.
|
|
303
|
+
*/
|
|
304
|
+
export interface FieldsField<Key extends string, Model, FormMessage extends {
|
|
305
|
+
readonly _tag: string;
|
|
306
|
+
}> {
|
|
307
|
+
(control: FormControl<Key>, model: Model, id: string, h: HtmlBuilder<FormMessage>, override?: FieldOverride<Key, FormMessage, FormMessage>): Html;
|
|
308
|
+
<Message>(control: FormControl<Key>, model: Model, id: string, h: HtmlBuilder<Message>, override: FieldOverride<Key, FormMessage, Message>): Html;
|
|
309
|
+
}
|
|
165
310
|
export declare const FormView: {
|
|
166
311
|
field: <Key extends string, Model, Message extends {
|
|
167
312
|
readonly _tag: string;
|
|
168
313
|
}>(form: FormLike<Key, Model, Message>, options?: {
|
|
169
314
|
/** Renderers by kind, beside the ones shipped: a new kind, or another way to draw a shipped one. */
|
|
170
315
|
readonly renderers?: Renderers<Message>;
|
|
316
|
+
/** What one key's element takes beyond the base field view. */
|
|
317
|
+
readonly attrs?: { readonly [K in Key]?: FieldAttrs; };
|
|
171
318
|
}) => FieldView<Key, Message>;
|
|
172
319
|
/**
|
|
173
320
|
* The view of the whole form: each control through `field`, in the input's
|
|
@@ -185,6 +332,30 @@ export declare const FormView: {
|
|
|
185
332
|
/** Renderers by kind, for the field view this makes. With `field` given, give them to `FormView.field`. */
|
|
186
333
|
readonly renderers?: Renderers<Message>;
|
|
187
334
|
}) => SlotView.SlotView<typeof FormSlots, FormInput<Model, Key>, Message>;
|
|
335
|
+
/**
|
|
336
|
+
* The whole form, as `define` draws it, with per-key overrides; and one flat
|
|
337
|
+
* key's control, for a layout the caller owns. Keys with no override render
|
|
338
|
+
* through the base field view (a new key of a known kind needs nothing new),
|
|
339
|
+
* each through its style when one is given and with its element attrs. `field`
|
|
340
|
+
* draws through the base view with a form-universe `h`, or through the
|
|
341
|
+
* override it is given, with any `h`. Nested keys and Bundle-backed keys draw
|
|
342
|
+
* only through `view` (or an override); `field` without one refuses them,
|
|
343
|
+
* naming the key.
|
|
344
|
+
*/
|
|
345
|
+
fields: <Key extends string, Model, FormMessage extends {
|
|
346
|
+
readonly _tag: string;
|
|
347
|
+
}>(form: FormLike<Key, Model, FormMessage> & {
|
|
348
|
+
readonly bundle: {
|
|
349
|
+
readonly name: string;
|
|
350
|
+
};
|
|
351
|
+
}, options?: {
|
|
352
|
+
readonly field?: FieldView<Key, FormMessage>;
|
|
353
|
+
/** Renderers by kind, for the field views this makes. */
|
|
354
|
+
readonly renderers?: Renderers<FormMessage>;
|
|
355
|
+
} & FieldsOptions<Key, FormMessage>) => {
|
|
356
|
+
readonly view: SlotView.SlotView<typeof FormSlots, FormInput<Model, Key>, FormMessage>;
|
|
357
|
+
readonly field: FieldsField<Key, Model, FormMessage>;
|
|
358
|
+
};
|
|
188
359
|
/**
|
|
189
360
|
* For `Bundle.withView`: the Submodel view that draws `view`, so a placement
|
|
190
361
|
* renders the form with `placed.view(model, h, { options })`.
|
|
@@ -195,9 +366,22 @@ export declare const FormView: {
|
|
|
195
366
|
*/
|
|
196
367
|
submodel: <Key extends string, Model extends {
|
|
197
368
|
readonly errors: ReadonlyArray<string>;
|
|
369
|
+
readonly submitPending: boolean;
|
|
198
370
|
}, Message extends {
|
|
199
371
|
readonly _tag: string;
|
|
200
|
-
}>(form: FormLike<Key, Model, Message>, view: SlotView.SlotView<typeof FormSlots, FormInput<Model, Key>, Message
|
|
372
|
+
}>(form: FormLike<Key, Model, Message>, view: SlotView.SlotView<typeof FormSlots, FormInput<Model, Key>, Message>, options?: {
|
|
373
|
+
/**
|
|
374
|
+
* When the submit waits instead of staying disabled. `true` while a
|
|
375
|
+
* check is running means submitted work waits for it, and the button
|
|
376
|
+
* stays enabled; `false` keeps the button disabled until every key is
|
|
377
|
+
* valid. Default `form.canSubmit` (lenient): a submit made mid-check
|
|
378
|
+
* waits for it. Pass a strict predicate to disable through checks
|
|
379
|
+
* instead, such as `model => PostForm.engine.value(model.form) !==
|
|
380
|
+
* undefined`, or `() => true` to never pre-disable and validate wholly
|
|
381
|
+
* at submit.
|
|
382
|
+
*/
|
|
383
|
+
readonly canSubmit?: (model: Model) => boolean;
|
|
384
|
+
}) => Submodel.View<Model, Message, FormViewInputs<Key>>;
|
|
201
385
|
};
|
|
202
386
|
//#endregion
|
|
203
387
|
//# sourceMappingURL=index.d.mts.map
|
package/dist/index.d.mts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;
|
|
1
|
+
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":"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"}
|