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 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. All of the view's words (`submit`, `search`,
130
- `add`, `remove`) are text, with `{label}` and `{position}` as blanks; see
131
- [words in one place](../form/README.md#words-as-text-in-one-place).
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
- and `error`. `FormSlots` publishes `root` (the `form`), `errors` (failures that
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 required, and `aria-describedby`
179
- naming its description and, while invalid, its error. An error is `role="alert"`.
180
- The submit button is disabled until the form would submit.
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 order, and fields in
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>) => Submodel.View<Model, Message, FormViewInputs<Key>>;
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
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;iBAuBiB;WACN;WACA;;;;;;;;;iBAUM;;WAEN;;WAEA;;WAEA;;WAEA;;;;;;iBAOM,eAAe;WACrB,sBAAsB,KAAK,OAAO,cAAc;;;;;WAKhD,gBAAgB,SAAS,eAAe,cAAc;;WAEtD,QAAQ;;;iBAIF,WAAW;WACjB,SAAS,YAAY;WACrB,OAAO,gBAAgB,MAAM;WAC7B;WACA,QAAQ;WACR,SAAS,cAAc;;WAEvB;;WAEA;;;;;WAKA;aAEM,UAAU,OAAO;aACjB;aACA,WAAW;;;WAIjB;;;;;WAKA;;;iBAIM,UAAU,OAAO,qCAAqC,eAAe;WAC3E,OAAO;WACP,QAAQ;WACR;;;qBAUE,YAAU,MAAA;;;;;;;;;;;;;;;;;;qBA2BV,WAAS,MAAA;;;;;;;;;;;;;UAkBZ,SAAS,oBAAoB,OAAO;;WAEnC,UAAU,cAAc;WACxB,QAAQ,OAAO,OAAO,KAAK,QAAQ,gBAAgB,MAAM;;WAEzD,OAAO,OAAO,OAAO,eAAe,cAAc;WAClD,SAAS,OAAO,OAAO,KAAK;WAC5B,cAAc,OAAO,OAAO,KAAK;WACjC,YAAY,OAAO;WACnB;;aAEE,MAAM;aACN,UAAU;eAAoB,KAAK;eAAc,OAAO;UAAY,QAAQ;aAC5E,UAAU;eAAoB,KAAK;UAAU,QAAQ;aACrD,WAAW;eAAoB,KAAK;eAAc;UAAmB,QAAQ;aAC7E,iBAAiB,QAAQ;aACzB,SAAS;eACP;eACA;eACA;UACL,QAAQ;aACL,WAAW;eAAoB;UAAkB,QAAQ;aACzD,aAAa;eACX;eACA;UACL,QAAQ;;;KAuCb,UAAU,oBAAoB,WAAW,SAAS,gBAC9C,YACP,WAAW,MACX;;iBAOe,cAAc;WACpB,OAAO;;WAEP,SAAS;WACT,OAAO;WACP,SAAS,OAAO,UAAU;WAC1B,SAAS;;WAET,OAAO,cAAc,UAAU;WAC/B,OAAO,oBAAoB,YAAY;WACvC,GAAG,YAAY;;;YAId,SAAS,YAAY,SAAS,cAAc,aAAa;;YAGzD,UAAU,WAAW,SAAS,eAAe,SAAS;qBAoLrD;EAjFE,QAAA,oBAAoB,OAAO;aAA2B;KAAc,MAC3E,SAAS,KAAK,OAAO,UAAQ;;aAGxB,YAAY,UAAU;QAEhC,UAAU,KAAK;;;;;;EAmFP,SAAA,oBAAoB,OAAO;aAA2B;KAAc,MACrE,SAAS,KAAK,OAAO;aAAsB;eAAmB;;KAAgB;aAEzE,QAAQ,UAAU,KAAK;;aAEvB,YAAY,UAAU;QAEhC,SAAS,gBAAgB,WAAW,UAAU,OAAO,MAAM;;;;;;;;;EAsH5D,WAAA,oBACA;aAAyB,QAAQ;KACjC;aAA2B;KAAc,MAEnC,SAAS,KAAK,OAAO,UAAQ,MAC7B,SAAS,gBAAgB,WAAW,UAAU,OAAO,MAAM,aAChE,SAAS,KAAK,OAAO,SAAS,eAAe"}
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":"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"}