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/dist/index.d.mts CHANGED
@@ -1,17 +1,21 @@
1
1
  import { Duration, Effect, Schema } from "effect";
2
2
  import { Bundle } from "foldkit-bundle";
3
- import { Metadata } from "foldkit-metadata";
4
- import * as FieldValidation from "foldkit/fieldValidation";
5
3
  import { AnyEntity, EntityInput, InputMember, NestedInput } from "foldkit-entity";
4
+ import { Metadata } from "foldkit-metadata";
6
5
  import { Command } from "foldkit/command";
6
+ import * as FieldValidation from "foldkit/fieldValidation";
7
7
  //#region src/input.d.ts
8
8
  /**
9
9
  * What a control holds while it is edited, which is not the value it submits: a
10
10
  * number being typed is text, and an unchosen relation is the empty string.
11
11
  */
12
12
  type Draft = string | boolean | ReadonlyArray<string>;
13
- /** The draft a control holds. `rows` is a nested key: rows of a form, not a draft. */
14
- type DraftKind = 'text' | 'flag' | 'list' | 'rows';
13
+ /**
14
+ * The draft a control holds. `rows` is a nested key: rows of a form, not a
15
+ * draft. `model` is a control backed by a Bundle (`Input.bundle`): its draft is
16
+ * the Bundle's Model.
17
+ */
18
+ type DraftKind = 'text' | 'flag' | 'list' | 'rows' | 'model';
15
19
  /** What edits one key: the primitive every kind of control is a value of. */
16
20
  interface Control<Data = unknown> {
17
21
  /** The name a renderer is found by. */
@@ -28,9 +32,10 @@ interface Control<Data = unknown> {
28
32
  readonly data: Data;
29
33
  /**
30
34
  * For a `text` draft: the value the key's schema is given, when that is not the
31
- * text itself. `undefined` means the text does not read as one.
35
+ * text itself, read with the control's `data` (a select's options). `undefined`
36
+ * means the text does not read as one.
32
37
  */
33
- readonly parse?: ((draft: string) => unknown) | undefined;
38
+ parse?(draft: string, data: Data): unknown;
34
39
  /** What to say when `parse` gives `undefined`. */
35
40
  readonly unparsed?: string | undefined;
36
41
  /**
@@ -75,8 +80,13 @@ interface NestedForm {
75
80
  readonly rows: (model: never, key: never) => ReadonlyArray<FormRow>;
76
81
  readonly search: (model: never, key: never) => string;
77
82
  readonly isFollowing: (model: never, key: never) => boolean;
83
+ /** A key edited by a control backed by a Bundle: its state, with the Bundle's Model as the value. */
84
+ readonly control: (key: never) => {
85
+ readonly field: (model: never) => unknown;
86
+ };
78
87
  readonly Message: {
79
88
  readonly Changed: (payload: never) => unknown;
89
+ readonly Control: (payload: never) => unknown;
80
90
  readonly Blurred: (payload: never) => unknown;
81
91
  readonly Searched: (payload: never) => unknown;
82
92
  readonly Nested: (payload: never) => unknown;
@@ -84,6 +94,53 @@ interface NestedForm {
84
94
  readonly RowRemoved: (payload: never) => unknown;
85
95
  };
86
96
  }
97
+ /**
98
+ * What a control backed by a Bundle carries: the Bundle, its args, and how the
99
+ * key's value is read from its Model and written into it.
100
+ */
101
+ interface BundleData<Model = any, Value = any> {
102
+ readonly bundle: Bundle.AnyBundle;
103
+ readonly args: unknown;
104
+ /** The value the key validates and submits. `undefined` or `null` is nothing entered. */
105
+ readonly value: (model: Model) => Value | null | undefined;
106
+ /** The Model showing a value the form was given, from the Model the control holds. */
107
+ readonly fill: (model: Model, value: Value) => Model;
108
+ /** The Model with nothing in flight, for a stored form shown again. */
109
+ readonly settled: (model: Model) => Model;
110
+ }
111
+ /**
112
+ * A control backed by a Bundle. Its draft is the Bundle's Model, its Messages
113
+ * reach it through the form, and its Commands, Subscriptions and Resources are
114
+ * the form's.
115
+ */
116
+ interface BundleControl<Model, Message, Value, Resources = {}> extends Control<BundleData<Model, Value>> {
117
+ readonly draft: 'model';
118
+ /** Type-only: the Bundle's Message, for `form.control(key).send`. Never set. */
119
+ readonly Message?: Message;
120
+ /** Type-only: the Bundle's Resources, which a runtime running the form must provide. Never set. */
121
+ readonly Resources?: Resources;
122
+ }
123
+ /** What `Input.bundle` takes: the Bundle, then how the key's value lives in its Model. */
124
+ type BundleControlSpec<Args, Model, Message extends {
125
+ readonly _tag: string;
126
+ }, Value, Resources extends Bundle.ResourceEntries<Model, Message> = {}> = {
127
+ /**
128
+ * The Bundle. Its Commands may need no services, and it has no OutMessage: a
129
+ * form key has no parent to hand one to, and an OutMessage is never dropped
130
+ * by omission.
131
+ */
132
+ readonly bundle: Bundle.Bundle<any, Args, Model, Message, never, never, any, any, Resources, any>;
133
+ /** The value the key validates and submits. `undefined` or `null` is nothing entered. */
134
+ readonly value: (model: Model) => Value | null | undefined;
135
+ /** The Model showing a value the form was given (`fill`), from the Model the control holds. */
136
+ readonly fill: (model: Model, value: Value) => Model;
137
+ /** The Model with nothing in flight, for a stored form shown again. Default: as it is. */
138
+ readonly settled?: (model: Model) => Model;
139
+ } & ([Args] extends [void] ? {
140
+ readonly args?: undefined;
141
+ } : {
142
+ readonly args: Args;
143
+ });
87
144
  /** A relation picker: what it chooses from, and whether it searches. */
88
145
  interface RelationData {
89
146
  readonly target: AnyEntity;
@@ -106,7 +163,8 @@ export declare const Input: {
106
163
  readonly draft: DraftKind;
107
164
  readonly shown?: boolean;
108
165
  readonly searches?: boolean | ((data: Data) => boolean);
109
- readonly parse?: (draft: string) => unknown;
166
+ /** The value a text draft stands for, given the control's data; `undefined` when it stands for none. */
167
+ readonly parse?: (draft: string, data: Data) => unknown;
110
168
  readonly unparsed?: string;
111
169
  }) => ControlKind<Data>;
112
170
  Text: ControlKind<Record<string, never>>;
@@ -115,18 +173,39 @@ export declare const Input: {
115
173
  Number: ControlKind<Record<string, never>>;
116
174
  Toggle: ControlKind<Record<string, never>>;
117
175
  Select: ControlKind<{
118
- readonly options: ReadonlyArray<string>;
176
+ readonly options: ReadonlyArray<string | number>;
119
177
  }>;
120
178
  RelationOne: ControlKind<RelationData>;
121
179
  RelationMany: ControlKind<RelationData>;
122
180
  Nested: ControlKind<NestedData>;
181
+ /**
182
+ * A control backed by a Bundle, for a draft that is a Model of its own: a
183
+ * color picker with a popover, a page builder, a rich-text editor. The key's
184
+ * draft is the Bundle's Model; `value` reads what the key validates and
185
+ * submits from it, and `fill` writes a given value into it. The Bundle's
186
+ * Messages travel as the form's `Control` Message, and its Commands,
187
+ * Subscriptions and Resources become the form's.
188
+ */
189
+ bundle: <Args, Model, Message extends {
190
+ readonly _tag: string;
191
+ }, Value, Resources extends Bundle.ResourceEntries<Model, Message> = {}>(kind: string, spec: BundleControlSpec<Args, Model, Message, Value, Resources>) => BundleControl<Model, Message, Value, Resources>;
192
+ /** Whether a control is backed by a Bundle, whatever its kind is called. */
193
+ isBundle: (control: Control) => control is Control<BundleData>;
123
194
  text: () => Control;
124
195
  /** Carried and submitted, not shown: the id of the thing being edited. Set it with `fill`. */
125
196
  hidden: () => Control;
126
197
  multiline: () => Control;
127
198
  number: () => Control;
128
199
  toggle: () => Control;
129
- select: (options: ReadonlyArray<string>) => Control;
200
+ select: (options: ReadonlyArray<string | number>) => Control;
201
+ /**
202
+ * A picker of one of `target`, for a value that is not a relation of the
203
+ * form's Entity: a page Builder's Block prop that holds an id. A relation key
204
+ * resolves to its picker without asking.
205
+ */
206
+ relationOne: (target: AnyEntity) => Control;
207
+ /** A picker of any number of `target`, as `relationOne` is of one. */
208
+ relationMany: (target: AnyEntity) => Control;
130
209
  /**
131
210
  * For a relation key, under `inputs`: its picker, with a search. Too many to
132
211
  * list is the usual case for a relation; the form holds the search text, and
@@ -162,8 +241,23 @@ export type DraftOf<Value> = [Exclude<Value, null | undefined>] extends [boolean
162
241
  export type NestedKey<Members> = { [K in keyof Members]: Members[K] extends NestedInput<any, any> ? K : never; }[keyof Members];
163
242
  /** The Model of the form a nested key's rows hold. */
164
243
  export type NestedModel<Member> = Member extends NestedInput<any, EntityInput<any, infer Fields, infer Members>> ? FormModel<Fields, Members> : never;
165
- export interface FormModel<Fields extends Schema.Struct.Fields, Members = {}> {
166
- readonly fields: { readonly [K in keyof Fields as K extends NestedKey<Members> ? never : K]: FieldValidation.Field<DraftOf<Schema.Schema.Type<Fields[K]>>>; };
244
+ /** The controls a form may be given under `inputs`, by key. */
245
+ export type InputsFor<Fields extends Schema.Struct.Fields, Members> = { readonly [K in Exclude<keyof Fields, NestedKey<Members>>]?: Control | ControlChange; };
246
+ /** The keys given a control backed by a Bundle, each with the Bundle's Model: that key's draft. */
247
+ export type ControlsOf<Inputs> = { readonly [K in keyof Inputs as Inputs[K] extends BundleControl<any, any, any> ? K : never]: Inputs[K] extends BundleControl<infer Model, any, any> ? Model : never; };
248
+ /**
249
+ * Whether any control backed by a Bundle holds Resources: then the form's
250
+ * Bundle has Resources, and a runtime running it must provide them.
251
+ */
252
+ export type ControlResourcesOf<Inputs> = true extends { readonly [K in keyof Inputs]: Inputs[K] extends BundleControl<any, any, any, infer Resources> ? [keyof Resources] extends [never] ? false : true : false; }[keyof Inputs] ? Readonly<Record<string, never>> : {};
253
+ /** The Message of the Bundle behind a key's control. */
254
+ export type ControlMessageOf<C> = C extends BundleControl<any, infer Message, any> ? Message : never;
255
+ export interface FormModel<Fields extends Schema.Struct.Fields, Members = {}, Controls = {}> {
256
+ /**
257
+ * One `fieldValidation` Field per key that holds a draft. A key given a
258
+ * control backed by a Bundle holds that Bundle's Model as its draft.
259
+ */
260
+ readonly fields: { readonly [K in keyof Fields as K extends NestedKey<Members> ? never : K]: FieldValidation.Field<K extends keyof Controls ? Controls[K] : DraftOf<Schema.Schema.Type<Fields[K]>>>; };
167
261
  /** The rows of each nested key, each a Model of the nested form. */
168
262
  readonly rows: { readonly [K in keyof Fields as K extends NestedKey<Members> ? K : never]: ReadonlyArray<FormRow<NestedModel<Members[K & keyof Members]>>>; };
169
263
  /** Counts the rows ever added, so a row's id is never reused. */
@@ -247,17 +341,17 @@ export declare const fillWords: (template: string, values: Readonly<Record<strin
247
341
  * A form made with `Form.make` from the input a key nests. It is an ordinary
248
342
  * form: the one that edits an author alone is the one a post's form nests.
249
343
  */
250
- export interface FormFor<Fields extends Schema.Struct.Fields, Members, R = never> extends NestedForm {
344
+ export interface FormFor<Fields extends Schema.Struct.Fields, Members, R = never, Controls = any> extends NestedForm {
251
345
  readonly input: EntityInput<any, Fields, Members>;
252
346
  readonly bundle: {
253
- readonly Model: Schema.Codec<FormModel<Fields, Members>, unknown>;
347
+ readonly Model: Schema.Codec<FormModel<Fields, Members, Controls>, unknown>;
254
348
  readonly Message: Schema.Codec<any, unknown>;
255
349
  readonly update: (model: any, message: any, args: void) => {
256
350
  readonly model: any;
257
351
  readonly commands?: ReadonlyArray<Command<any, never, R>> | undefined;
258
352
  };
259
353
  };
260
- readonly initial: FormModel<Fields, Members>;
354
+ readonly initial: FormModel<Fields, Members, Controls>;
261
355
  readonly fill: (model: any, values: any) => {
262
356
  readonly model: any;
263
357
  };
@@ -266,15 +360,23 @@ export interface FormFor<Fields extends Schema.Struct.Fields, Members, R = never
266
360
  readonly model: any;
267
361
  readonly commands: ReadonlyArray<Command<any, never, R>>;
268
362
  };
363
+ readonly validateAll: (model: any) => {
364
+ readonly model: any;
365
+ readonly commands: ReadonlyArray<Command<any, never, R>>;
366
+ };
269
367
  readonly isValidating: (model: any) => boolean;
270
368
  readonly value: (model: any) => unknown;
369
+ /** Whether a transition changed authored content, so a nesting form recurses. */
370
+ readonly authoredChanged: (before: any, after: any) => boolean;
271
371
  };
272
372
  readonly settled: (model: any) => any;
373
+ /** Whether a completed transition changed authored content. */
374
+ readonly authoredChanged: (before: any, after: any) => boolean;
273
375
  }
274
376
  /** The forms a form may be given for its nested keys: each one made from that key's nested input. */
275
377
  export type NestedForms<Fields extends Schema.Struct.Fields, Members, R> = { readonly [K in NestedKey<Members> & keyof Fields]?: Members[K] extends NestedInput<any, EntityInput<any, infer NestedFields, infer NestedMembers>> ? NestedFields extends Schema.Struct.Fields ? FormFor<NestedFields, NestedMembers, R> : never : never; };
276
378
  /** The constructors of a form's Messages that a row's handle offers, wrapped for the row. */
277
- type RowConstructor = 'Changed' | 'Blurred' | 'Searched' | 'Submitted' | 'Reset' | 'RowAdded' | 'RowRemoved';
379
+ type RowConstructor = 'Changed' | 'Blurred' | 'ValidatedAll' | 'Searched' | 'Submitted' | 'Reset' | 'RowAdded' | 'RowRemoved';
278
380
  /**
279
381
  * One row of a nested key, addressed: the nested form's own Message constructors,
280
382
  * each giving the Message of the form the row is in. `send` wraps a Message
@@ -286,12 +388,13 @@ export type RowHandle<Child, Message> = { readonly [T in RowConstructor]: Child
286
388
  readonly send: (message: unknown) => Message;
287
389
  };
288
390
  /** What `Form.make` takes beside the input. */
289
- export interface FormOptions<Fields extends Schema.Struct.Fields, Members, R, Nest extends NestedForms<Fields, Members, R> = {}> {
391
+ export interface FormOptions<Fields extends Schema.Struct.Fields, Members, R, Nest extends NestedForms<Fields, Members, R> = {}, Inputs extends InputsFor<Fields, Members> = InputsFor<Fields, Members>> {
290
392
  /**
291
393
  * The control for a key the resolver cannot decide, or should not: an unmapped
292
- * key with an unusual schema, or text that wants a multiline control here only.
394
+ * key with an unusual schema, text that wants a multiline control here only,
395
+ * or a control backed by a Bundle (`Input.bundle`).
293
396
  */
294
- readonly inputs?: { readonly [K in Exclude<keyof Fields, NestedKey<Members>>]?: Control | ControlChange; };
397
+ readonly inputs?: Inputs;
295
398
  /** The form's own words, and a rewrite of Schema's: for wording and for translation. */
296
399
  readonly messages?: FormMessages<keyof Fields & string>;
297
400
  /** Rules answered outside the form, by key. The key reads `Validating` while one runs. */
@@ -323,14 +426,16 @@ declare const Core: {
323
426
  * holds a draft. `options` names what the input cannot say: a control, the
324
427
  * words, the checks.
325
428
  */
326
- make: <const Name extends string, E extends AnyEntity, Fields extends Schema.Struct.Fields, Members extends { readonly [K in keyof Fields]: InputMember; }, R = never, const Nest extends NestedForms<Fields, Members, R> = {}>(name: Name, input: EntityInput<E, Fields, Members>, options?: FormOptions<Fields, Members, R, Nest>) => {
327
- bundle: Bundle.Bundle<Name, void, FormModel<Fields, Members>, {
429
+ make: <const Name extends string, E extends AnyEntity, Fields extends Schema.Struct.Fields, Members extends { readonly [K in keyof Fields]: InputMember; }, R = never, const Nest extends NestedForms<Fields, Members, R> = {}, const Inputs extends InputsFor<Fields, Members> = {}>(name: Name, input: EntityInput<E, Fields, Members>, options?: FormOptions<Fields, Members, R, Nest, Inputs>) => {
430
+ bundle: Bundle.Bundle<Name, void, FormModel<Fields, Members, ControlsOf<Inputs>>, {
328
431
  readonly _tag: "Changed";
329
432
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
330
433
  readonly value: string | boolean | readonly string[];
331
434
  } | {
332
435
  readonly _tag: "Blurred";
333
436
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
437
+ } | {
438
+ readonly _tag: "ValidatedAll";
334
439
  } | {
335
440
  readonly _tag: "Submitted";
336
441
  } | {
@@ -358,6 +463,10 @@ declare const Core: {
358
463
  readonly key: string;
359
464
  readonly row: string;
360
465
  readonly message: unknown;
466
+ } | {
467
+ readonly _tag: "Control";
468
+ readonly key: keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>;
469
+ readonly message: unknown;
361
470
  } | {
362
471
  readonly _tag: "RowAdded";
363
472
  readonly key: string;
@@ -365,27 +474,33 @@ declare const Core: {
365
474
  readonly _tag: "RowRemoved";
366
475
  readonly key: string;
367
476
  readonly row: string;
368
- }, Submitted<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>, R, never, void, {}, {
369
- fill: (model: FormModel<Fields, Members>, values: Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>) => {
370
- readonly model: FormModel<Fields, Members>;
477
+ }, Submitted<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>, R, never, void, ControlResourcesOf<Inputs>, {
478
+ fill: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, values: Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>) => {
479
+ readonly model: FormModel<Fields, Members, ControlsOf<Inputs>>;
371
480
  };
372
481
  }>;
373
482
  Message: import("foldkit/message").MessageUnion<{
374
- readonly Changed: {
375
- readonly key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
376
- readonly value: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
483
+ Changed: {
484
+ key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
485
+ value: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
377
486
  };
378
487
  /** Validates the key as it stands, so a required key left empty says so. */
379
- readonly Blurred: {
380
- readonly key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
488
+ Blurred: {
489
+ key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
381
490
  };
382
- readonly Submitted: {};
383
- readonly Reset: {};
491
+ /**
492
+ * Validates every key not validated yet, in every row too, as a submit
493
+ * would, and submits nothing: for a page that submits several forms at once.
494
+ * A rule spanning keys is said only by a submit.
495
+ */
496
+ ValidatedAll: {};
497
+ Submitted: {};
498
+ Reset: {};
384
499
  /** The answer of a check for the draft it was asked about; one for an older draft is dropped. */
385
- readonly Checked: {
386
- readonly key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
387
- readonly draft: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
388
- readonly error: Schema.NullOr<Schema.String>;
500
+ Checked: {
501
+ key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
502
+ draft: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
503
+ error: Schema.NullOr<Schema.String>;
389
504
  };
390
505
  /**
391
506
  * The outside world refused this key's value: a unique index, a rule only a
@@ -393,9 +508,9 @@ declare const Core: {
393
508
  * typed, until it is edited again. Unlike `Checked`, it answers no question
394
509
  * the form asked, so it lands whatever state the key is in.
395
510
  */
396
- readonly Refused: {
397
- readonly key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
398
- readonly error: Schema.String;
511
+ Refused: {
512
+ key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
513
+ error: Schema.String;
399
514
  };
400
515
  /**
401
516
  * What the form is editing, for the checks that need to know: a post's own
@@ -403,38 +518,49 @@ declare const Core: {
403
518
  * It changes no draft and validates nothing; a form that creates something
404
519
  * never sends it. See `FormModel.subject`.
405
520
  */
406
- readonly About: {
407
- readonly subject: Schema.$Record<Schema.String, Schema.String>;
521
+ About: {
522
+ subject: Schema.$Record<Schema.String, Schema.String>;
408
523
  };
409
524
  /** What was typed to find a choice for a relation key. It changes no draft and validates nothing. */
410
- readonly Searched: {
411
- readonly key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
412
- readonly text: Schema.String;
525
+ Searched: {
526
+ key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
527
+ text: Schema.String;
413
528
  };
414
529
  /** A Message of the nested form in one row of a nested key. One that row does not take is dropped. */
415
- readonly Nested: {
416
- readonly key: Schema.String;
417
- readonly row: Schema.String;
418
- readonly message: Schema.Unknown;
530
+ Nested: {
531
+ key: Schema.String;
532
+ row: Schema.String;
533
+ message: Schema.Unknown;
534
+ };
535
+ /**
536
+ * A Message of the control backed by a Bundle that edits `key`. One the
537
+ * Bundle does not take is dropped. It is an edit when it changes the key's
538
+ * value, and is then validated as `Changed` would be.
539
+ */
540
+ Control: {
541
+ key: Schema.Literals<readonly [keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>, ...(keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>)[]]>;
542
+ message: Schema.Unknown;
419
543
  };
420
544
  /** A new, empty row. A `one` that already has its row takes no other. */
421
- readonly RowAdded: {
422
- readonly key: Schema.String;
545
+ RowAdded: {
546
+ key: Schema.String;
423
547
  };
424
548
  /** Removes a row. A `one` that must be there stays. */
425
- readonly RowRemoved: {
426
- readonly key: Schema.String;
427
- readonly row: Schema.String;
549
+ RowRemoved: {
550
+ key: Schema.String;
551
+ row: Schema.String;
428
552
  };
429
553
  }>;
430
554
  /** The reading the form was made from, for `Entity.selectFor` and `Entity.valuesFor`. */
431
555
  input: EntityInput<E, Fields, Members>;
556
+ /** Whether a completed transition changed authored content. See the note above. */
557
+ authoredChanged: (before: FormModel<Fields, Members, ControlsOf<Inputs>>, after: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
432
558
  /** The `fill` helper as a plain function of the form's Model, for a package that wraps the form. */
433
- fill: (model: FormModel<Fields, Members>, values: Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>) => {
434
- readonly model: FormModel<Fields, Members>;
559
+ fill: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, values: Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>) => {
560
+ readonly model: FormModel<Fields, Members, ControlsOf<Inputs>>;
435
561
  };
436
562
  /** The Model the form starts from and resets to: every key empty and not validated. */
437
- initial: FormModel<Fields, Members>;
563
+ initial: FormModel<Fields, Members, ControlsOf<Inputs>>;
438
564
  /** The keys in the input's order, each with its control, label, and member. */
439
565
  controls: FormControl<keyof Fields & string>[];
440
566
  /**
@@ -442,11 +568,67 @@ declare const Core: {
442
568
  * `controls`. `model.fields.title` is the same value, typed to that key. A
443
569
  * nested key has rows and no draft.
444
570
  */
445
- field: (model: FormModel<Fields, Members>, key: Exclude<keyof Fields & string, NestedKey<Members>>) => FieldValidation.Field<Draft>;
571
+ field: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, key: Exclude<Exclude<keyof Fields & string, NestedKey<Members>>, keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>>) => FieldValidation.Field<Draft>;
572
+ /**
573
+ * The key edited by a control backed by a Bundle, addressed: `field` is its
574
+ * state with the Bundle's Model as its value, and `send` gives the form's
575
+ * Message for one of the Bundle's own.
576
+ */
577
+ control: <K extends keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>>(key: K) => {
578
+ readonly field: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => { readonly [K_1 in keyof Fields as K_1 extends NestedKey<Members> ? never : K_1]: FieldValidation.Field<K_1 extends keyof ControlsOf<Inputs> ? ControlsOf<Inputs>[K_1] : DraftOf<Schema.Schema.Type<Fields[K_1]>>>; }[K];
579
+ readonly send: (message: ControlMessageOf<Inputs[K]>) => {
580
+ readonly _tag: "Changed";
581
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
582
+ readonly value: string | boolean | readonly string[];
583
+ } | {
584
+ readonly _tag: "Blurred";
585
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
586
+ } | {
587
+ readonly _tag: "ValidatedAll";
588
+ } | {
589
+ readonly _tag: "Submitted";
590
+ } | {
591
+ readonly _tag: "Reset";
592
+ } | {
593
+ readonly _tag: "Checked";
594
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
595
+ readonly draft: string | boolean | readonly string[];
596
+ readonly error: string | null;
597
+ } | {
598
+ readonly _tag: "Refused";
599
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
600
+ readonly error: string;
601
+ } | {
602
+ readonly _tag: "About";
603
+ readonly subject: {
604
+ readonly [x: string]: string;
605
+ };
606
+ } | {
607
+ readonly _tag: "Searched";
608
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
609
+ readonly text: string;
610
+ } | {
611
+ readonly _tag: "Nested";
612
+ readonly key: string;
613
+ readonly row: string;
614
+ readonly message: unknown;
615
+ } | {
616
+ readonly _tag: "Control";
617
+ readonly key: keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>;
618
+ readonly message: unknown;
619
+ } | {
620
+ readonly _tag: "RowAdded";
621
+ readonly key: string;
622
+ } | {
623
+ readonly _tag: "RowRemoved";
624
+ readonly key: string;
625
+ readonly row: string;
626
+ };
627
+ };
446
628
  /** What was typed to find a choice for a relation key that searches; `''` until something is. */
447
- search: (model: FormModel<Fields, Members>, key: Exclude<keyof Fields & string, NestedKey<Members>>) => string;
629
+ search: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, key: Exclude<keyof Fields & string, NestedKey<Members>>) => string;
448
630
  /** What the form is editing; `{}` while it creates. See `FormModel.subject`. */
449
- subject: (model: FormModel<Fields, Members>) => Readonly<Record<string, string>>;
631
+ subject: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => Readonly<Record<string, string>>;
450
632
  /**
451
633
  * The form of each nested key, typed when it was given under `nested`: its
452
634
  * `controls`, its `field`, its Messages.
@@ -463,6 +645,8 @@ declare const Core: {
463
645
  } | {
464
646
  readonly _tag: "Blurred";
465
647
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
648
+ } | {
649
+ readonly _tag: "ValidatedAll";
466
650
  } | {
467
651
  readonly _tag: "Submitted";
468
652
  } | {
@@ -490,6 +674,10 @@ declare const Core: {
490
674
  readonly key: string;
491
675
  readonly row: string;
492
676
  readonly message: unknown;
677
+ } | {
678
+ readonly _tag: "Control";
679
+ readonly key: keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>;
680
+ readonly message: unknown;
493
681
  } | {
494
682
  readonly _tag: "RowAdded";
495
683
  readonly key: string;
@@ -502,30 +690,36 @@ declare const Core: {
502
690
  * Whether a key that follows another still does: `false` once the author has
503
691
  * written it themselves. A view offers "regenerate" by sending the key an empty draft.
504
692
  */
505
- isFollowing: (model: FormModel<Fields, Members>, key: Exclude<keyof Fields & string, NestedKey<Members>>) => boolean;
693
+ isFollowing: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, key: Exclude<keyof Fields & string, NestedKey<Members>>) => boolean;
506
694
  /** The rows of a nested key, each a Model of `control.form`. */
507
- rows: (model: FormModel<Fields, Members>, key: Extract<keyof Fields & string, NestedKey<Members>>) => { readonly [K in keyof Fields as K extends NestedKey<Members> ? K : never]: readonly FormRow<NestedModel<Members[K & keyof Members]>>[]; }[Extract<keyof Fields & string, NestedKey<Members>>];
695
+ rows: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, key: Extract<keyof Fields & string, NestedKey<Members>>) => { readonly [K in keyof Fields as K extends NestedKey<Members> ? K : never]: readonly FormRow<NestedModel<Members[K & keyof Members]>>[]; }[Extract<keyof Fields & string, NestedKey<Members>>];
508
696
  /**
509
697
  * Whether a submit now could go through: nothing is invalid. A check still
510
698
  * running does not stop it; the submit waits for the answer.
511
699
  */
512
- canSubmit: (model: FormModel<Fields, Members>) => boolean;
700
+ canSubmit: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
701
+ /**
702
+ * Whether the form is valid right now: a submit now would hand over the
703
+ * value at once. Unlike `canSubmit`, a check running, or one a key has not
704
+ * had yet, is not valid until it answers.
705
+ */
706
+ isValid: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
513
707
  /**
514
708
  * The Model with nothing in flight, for one that was stored and is shown
515
709
  * again: a check that was running when it was stored will never answer, so
516
710
  * its key is not validated yet, and no submit is waiting. Rows too.
517
711
  */
518
- settled: (model: FormModel<Fields, Members>) => FormModel<Fields, Members>;
712
+ settled: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => FormModel<Fields, Members, ControlsOf<Inputs>>;
519
713
  /**
520
714
  * What of the form decodes as it stands, by key: the value, less every key
521
715
  * that is not valid yet. For saving unfinished work, which `engine.value`
522
716
  * cannot give. A nested key is there once each of its rows has a value.
523
717
  */
524
- partial: (model: FormModel<Fields, Members>) => Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>;
718
+ partial: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>;
525
719
  /** The form as the form that nests it drives it. */
526
720
  engine: {
527
- submit: (model: FormModel<Fields, Members>) => {
528
- model: FormModel<Fields, Members>;
721
+ submit: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => {
722
+ model: FormModel<Fields, Members, ControlsOf<Inputs>>;
529
723
  commands: readonly Readonly<{
530
724
  name: string;
531
725
  args?: Record<string, unknown>;
@@ -537,6 +731,8 @@ declare const Core: {
537
731
  } | {
538
732
  readonly _tag: "Blurred";
539
733
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
734
+ } | {
735
+ readonly _tag: "ValidatedAll";
540
736
  } | {
541
737
  readonly _tag: "Submitted";
542
738
  } | {
@@ -564,6 +760,10 @@ declare const Core: {
564
760
  readonly key: string;
565
761
  readonly row: string;
566
762
  readonly message: unknown;
763
+ } | {
764
+ readonly _tag: "Control";
765
+ readonly key: keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>;
766
+ readonly message: unknown;
567
767
  } | {
568
768
  readonly _tag: "RowAdded";
569
769
  readonly key: string;
@@ -574,9 +774,67 @@ declare const Core: {
574
774
  }, never, R>;
575
775
  }>[];
576
776
  };
577
- isValidating: (model: FormModel<Fields, Members>) => boolean;
777
+ validateAll: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => {
778
+ readonly model: FormModel<Fields, Members, ControlsOf<Inputs>>;
779
+ readonly commands: readonly Readonly<{
780
+ name: string;
781
+ args?: Record<string, unknown>;
782
+ key?: string;
783
+ effect: Effect.Effect<{
784
+ readonly _tag: "Changed";
785
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
786
+ readonly value: string | boolean | readonly string[];
787
+ } | {
788
+ readonly _tag: "Blurred";
789
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
790
+ } | {
791
+ readonly _tag: "ValidatedAll";
792
+ } | {
793
+ readonly _tag: "Submitted";
794
+ } | {
795
+ readonly _tag: "Reset";
796
+ } | {
797
+ readonly _tag: "Checked";
798
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
799
+ readonly draft: string | boolean | readonly string[];
800
+ readonly error: string | null;
801
+ } | {
802
+ readonly _tag: "Refused";
803
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
804
+ readonly error: string;
805
+ } | {
806
+ readonly _tag: "About";
807
+ readonly subject: {
808
+ readonly [x: string]: string;
809
+ };
810
+ } | {
811
+ readonly _tag: "Searched";
812
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
813
+ readonly text: string;
814
+ } | {
815
+ readonly _tag: "Nested";
816
+ readonly key: string;
817
+ readonly row: string;
818
+ readonly message: unknown;
819
+ } | {
820
+ readonly _tag: "Control";
821
+ readonly key: keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>;
822
+ readonly message: unknown;
823
+ } | {
824
+ readonly _tag: "RowAdded";
825
+ readonly key: string;
826
+ } | {
827
+ readonly _tag: "RowRemoved";
828
+ readonly key: string;
829
+ readonly row: string;
830
+ }, never, R>;
831
+ }>[];
832
+ };
833
+ isValidating: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
834
+ /** Whether a transition changed authored content, so a nesting form recurses. */
835
+ authoredChanged: (before: FormModel<Fields, Members, ControlsOf<Inputs>>, after: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
578
836
  /** The decoded input when every key and row is valid as it stands; validates nothing. */
579
- value: (model: FormModel<Fields, Members>) => Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>> | undefined;
837
+ value: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>> | undefined;
580
838
  };
581
839
  pipe<A>(this: A): A;
582
840
  pipe<A, B = never>(this: A, ab: (_: A) => B): B;
@@ -602,7 +860,7 @@ declare const Core: {
602
860
  pipe<A, B_20 = never, C_19 = never, D_18 = never, E_18 = never, F_16 = never, G_15 = never, H_14 = never, I_13 = never, J_12 = never, K_11 = never, L_10 = never, M_9 = never, N_8 = never, O_7 = never, P_6 = never, Q_5 = never, R_5 = never, S_3 = never, T_2 = never, U_1 = never>(this: A, ab: (_: A) => B_20, bc: (_: B_20) => C_19, cd: (_: C_19) => D_18, de: (_: D_18) => E_18, ef: (_: E_18) => F_16, fg: (_: F_16) => G_15, gh: (_: G_15) => H_14, hi: (_: H_14) => I_13, ij: (_: I_13) => J_12, jk: (_: J_12) => K_11, kl: (_: K_11) => L_10, lm: (_: L_10) => M_9, mn: (_: M_9) => N_8, no: (_: N_8) => O_7, op: (_: O_7) => P_6, pq: (_: P_6) => Q_5, qr: (_: Q_5) => R_5, rs: (_: R_5) => S_3, st: (_: S_3) => T_2, tu: (_: T_2) => U_1): U_1;
603
861
  /** The name, input and options the form was made from: what a pipe step makes the next form from. */
604
862
  name: Name;
605
- options: FormOptions<Fields, Members, R, Nest>;
863
+ options: FormOptions<Fields, Members, R, Nest, Inputs>;
606
864
  /** Type-only: the form's type parameters, for a pipe step to read. Never set. */
607
865
  types: {
608
866
  readonly Name: Name;
@@ -611,6 +869,7 @@ declare const Core: {
611
869
  readonly Members: Members;
612
870
  readonly R: R;
613
871
  readonly Nest: Nest;
872
+ readonly Inputs: Inputs;
614
873
  };
615
874
  };
616
875
  /**
@@ -635,6 +894,7 @@ interface FormTypes {
635
894
  readonly Members: any;
636
895
  readonly R: unknown;
637
896
  readonly Nest: any;
897
+ readonly Inputs: any;
638
898
  }
639
899
  /** A form as a pipe step takes it: what it was made from, and its type parameters. */
640
900
  interface Remakeable<T extends FormTypes = FormTypes> {
@@ -644,11 +904,19 @@ interface Remakeable<T extends FormTypes = FormTypes> {
644
904
  readonly types: T;
645
905
  }
646
906
  /** The form `Form.make` gives for these type parameters. */
647
- type Made<T extends FormTypes> = ReturnType<typeof Core.make<T['Name'], T['E'], T['Fields'], T['Members'], T['R'], T['Nest']>>;
907
+ type Made<T extends FormTypes> = ReturnType<typeof Core.make<T['Name'], T['E'], T['Fields'], T['Members'], T['R'], T['Nest'], T['Inputs']>>;
648
908
  type OptionsOf<T extends FormTypes> = FormOptions<T['Fields'], T['Members'], T['R'], T['Nest']>;
649
909
  export declare const Form: {
650
910
  /** Controls by key, beside the ones the form already names. */
651
- inputs: <F extends Remakeable>(inputs: NonNullable<OptionsOf<F["types"]>["inputs"]>) => (form: F) => F;
911
+ inputs: <F extends Remakeable, const I extends InputsFor<F["types"]["Fields"], F["types"]["Members"]>>(inputs: I) => (form: F) => [keyof ControlsOf<I>] extends [never] ? F : Made<{
912
+ readonly Name: F["types"]["Name"];
913
+ readonly E: F["types"]["E"];
914
+ readonly Fields: F["types"]["Fields"];
915
+ readonly Members: F["types"]["Members"];
916
+ readonly R: F["types"]["R"];
917
+ readonly Nest: F["types"]["Nest"];
918
+ readonly Inputs: Omit<F["types"]["Inputs"], keyof I> & I;
919
+ }>;
652
920
  /** The form's words, beside the ones it already has. */
653
921
  messages: <F extends Remakeable>(messages: NonNullable<OptionsOf<F["types"]>["messages"]>) => (form: F) => F;
654
922
  /** How long a key rests before its check runs. */
@@ -664,6 +932,7 @@ export declare const Form: {
664
932
  readonly Members: F["types"]["Members"];
665
933
  readonly R: F["types"]["R"] | RequirementOf<C>;
666
934
  readonly Nest: F["types"]["Nest"];
935
+ readonly Inputs: F["types"]["Inputs"];
667
936
  }>;
668
937
  /** The forms of nested keys, beside the ones the form was already given. */
669
938
  nested: <F extends Remakeable, const N extends NestedForms<F["types"]["Fields"], F["types"]["Members"], F["types"]["R"]>>(forms: N) => (form: F) => Made<{
@@ -673,6 +942,7 @@ export declare const Form: {
673
942
  readonly Members: F["types"]["Members"];
674
943
  readonly R: F["types"]["R"];
675
944
  readonly Nest: F["types"]["Nest"] & N;
945
+ readonly Inputs: F["types"]["Inputs"];
676
946
  }>;
677
947
  /**
678
948
  * A form for one operation's input. A key mapped with `Relation.nested` holds
@@ -680,14 +950,16 @@ export declare const Form: {
680
950
  * holds a draft. `options` names what the input cannot say: a control, the
681
951
  * words, the checks.
682
952
  */
683
- make: <const Name extends string, E extends AnyEntity, Fields extends Schema.Struct.Fields, Members extends { readonly [K in keyof Fields]: InputMember; }, R = never, const Nest extends NestedForms<Fields, Members, R> = {}>(name: Name, input: EntityInput<E, Fields, Members>, options?: FormOptions<Fields, Members, R, Nest>) => {
684
- bundle: Bundle.Bundle<Name, void, FormModel<Fields, Members>, {
953
+ make: <const Name extends string, E extends AnyEntity, Fields extends Schema.Struct.Fields, Members extends { readonly [K in keyof Fields]: InputMember; }, R = never, const Nest extends NestedForms<Fields, Members, R> = {}, const Inputs extends InputsFor<Fields, Members> = {}>(name: Name, input: EntityInput<E, Fields, Members>, options?: FormOptions<Fields, Members, R, Nest, Inputs>) => {
954
+ bundle: Bundle.Bundle<Name, void, FormModel<Fields, Members, ControlsOf<Inputs>>, {
685
955
  readonly _tag: "Changed";
686
956
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
687
957
  readonly value: string | boolean | readonly string[];
688
958
  } | {
689
959
  readonly _tag: "Blurred";
690
960
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
961
+ } | {
962
+ readonly _tag: "ValidatedAll";
691
963
  } | {
692
964
  readonly _tag: "Submitted";
693
965
  } | {
@@ -715,6 +987,10 @@ export declare const Form: {
715
987
  readonly key: string;
716
988
  readonly row: string;
717
989
  readonly message: unknown;
990
+ } | {
991
+ readonly _tag: "Control";
992
+ readonly key: keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>;
993
+ readonly message: unknown;
718
994
  } | {
719
995
  readonly _tag: "RowAdded";
720
996
  readonly key: string;
@@ -722,27 +998,33 @@ export declare const Form: {
722
998
  readonly _tag: "RowRemoved";
723
999
  readonly key: string;
724
1000
  readonly row: string;
725
- }, Submitted<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>, R, never, void, {}, {
726
- fill: (model: FormModel<Fields, Members>, values: Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>) => {
727
- readonly model: FormModel<Fields, Members>;
1001
+ }, Submitted<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>, R, never, void, ControlResourcesOf<Inputs>, {
1002
+ fill: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, values: Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>) => {
1003
+ readonly model: FormModel<Fields, Members, ControlsOf<Inputs>>;
728
1004
  };
729
1005
  }>;
730
1006
  Message: import("foldkit/message").MessageUnion<{
731
- readonly Changed: {
732
- readonly key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
733
- readonly value: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
1007
+ Changed: {
1008
+ key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1009
+ value: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
734
1010
  };
735
1011
  /** Validates the key as it stands, so a required key left empty says so. */
736
- readonly Blurred: {
737
- readonly key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1012
+ Blurred: {
1013
+ key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
738
1014
  };
739
- readonly Submitted: {};
740
- readonly Reset: {};
1015
+ /**
1016
+ * Validates every key not validated yet, in every row too, as a submit
1017
+ * would, and submits nothing: for a page that submits several forms at once.
1018
+ * A rule spanning keys is said only by a submit.
1019
+ */
1020
+ ValidatedAll: {};
1021
+ Submitted: {};
1022
+ Reset: {};
741
1023
  /** The answer of a check for the draft it was asked about; one for an older draft is dropped. */
742
- readonly Checked: {
743
- readonly key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
744
- readonly draft: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
745
- readonly error: Schema.NullOr<Schema.String>;
1024
+ Checked: {
1025
+ key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1026
+ draft: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
1027
+ error: Schema.NullOr<Schema.String>;
746
1028
  };
747
1029
  /**
748
1030
  * The outside world refused this key's value: a unique index, a rule only a
@@ -750,9 +1032,9 @@ export declare const Form: {
750
1032
  * typed, until it is edited again. Unlike `Checked`, it answers no question
751
1033
  * the form asked, so it lands whatever state the key is in.
752
1034
  */
753
- readonly Refused: {
754
- readonly key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
755
- readonly error: Schema.String;
1035
+ Refused: {
1036
+ key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1037
+ error: Schema.String;
756
1038
  };
757
1039
  /**
758
1040
  * What the form is editing, for the checks that need to know: a post's own
@@ -760,38 +1042,49 @@ export declare const Form: {
760
1042
  * It changes no draft and validates nothing; a form that creates something
761
1043
  * never sends it. See `FormModel.subject`.
762
1044
  */
763
- readonly About: {
764
- readonly subject: Schema.$Record<Schema.String, Schema.String>;
1045
+ About: {
1046
+ subject: Schema.$Record<Schema.String, Schema.String>;
765
1047
  };
766
1048
  /** What was typed to find a choice for a relation key. It changes no draft and validates nothing. */
767
- readonly Searched: {
768
- readonly key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
769
- readonly text: Schema.String;
1049
+ Searched: {
1050
+ key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1051
+ text: Schema.String;
770
1052
  };
771
1053
  /** A Message of the nested form in one row of a nested key. One that row does not take is dropped. */
772
- readonly Nested: {
773
- readonly key: Schema.String;
774
- readonly row: Schema.String;
775
- readonly message: Schema.Unknown;
1054
+ Nested: {
1055
+ key: Schema.String;
1056
+ row: Schema.String;
1057
+ message: Schema.Unknown;
1058
+ };
1059
+ /**
1060
+ * A Message of the control backed by a Bundle that edits `key`. One the
1061
+ * Bundle does not take is dropped. It is an edit when it changes the key's
1062
+ * value, and is then validated as `Changed` would be.
1063
+ */
1064
+ Control: {
1065
+ key: Schema.Literals<readonly [keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>, ...(keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>)[]]>;
1066
+ message: Schema.Unknown;
776
1067
  };
777
1068
  /** A new, empty row. A `one` that already has its row takes no other. */
778
- readonly RowAdded: {
779
- readonly key: Schema.String;
1069
+ RowAdded: {
1070
+ key: Schema.String;
780
1071
  };
781
1072
  /** Removes a row. A `one` that must be there stays. */
782
- readonly RowRemoved: {
783
- readonly key: Schema.String;
784
- readonly row: Schema.String;
1073
+ RowRemoved: {
1074
+ key: Schema.String;
1075
+ row: Schema.String;
785
1076
  };
786
1077
  }>;
787
1078
  /** The reading the form was made from, for `Entity.selectFor` and `Entity.valuesFor`. */
788
1079
  input: EntityInput<E, Fields, Members>;
1080
+ /** Whether a completed transition changed authored content. See the note above. */
1081
+ authoredChanged: (before: FormModel<Fields, Members, ControlsOf<Inputs>>, after: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
789
1082
  /** The `fill` helper as a plain function of the form's Model, for a package that wraps the form. */
790
- fill: (model: FormModel<Fields, Members>, values: Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>) => {
791
- readonly model: FormModel<Fields, Members>;
1083
+ fill: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, values: Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>) => {
1084
+ readonly model: FormModel<Fields, Members, ControlsOf<Inputs>>;
792
1085
  };
793
1086
  /** The Model the form starts from and resets to: every key empty and not validated. */
794
- initial: FormModel<Fields, Members>;
1087
+ initial: FormModel<Fields, Members, ControlsOf<Inputs>>;
795
1088
  /** The keys in the input's order, each with its control, label, and member. */
796
1089
  controls: FormControl<keyof Fields & string>[];
797
1090
  /**
@@ -799,11 +1092,67 @@ export declare const Form: {
799
1092
  * `controls`. `model.fields.title` is the same value, typed to that key. A
800
1093
  * nested key has rows and no draft.
801
1094
  */
802
- field: (model: FormModel<Fields, Members>, key: Exclude<keyof Fields & string, NestedKey<Members>>) => FieldValidation.Field<Draft>;
1095
+ field: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, key: Exclude<Exclude<keyof Fields & string, NestedKey<Members>>, keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>>) => FieldValidation.Field<Draft>;
1096
+ /**
1097
+ * The key edited by a control backed by a Bundle, addressed: `field` is its
1098
+ * state with the Bundle's Model as its value, and `send` gives the form's
1099
+ * Message for one of the Bundle's own.
1100
+ */
1101
+ control: <K extends keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>>(key: K) => {
1102
+ readonly field: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => { readonly [K_1 in keyof Fields as K_1 extends NestedKey<Members> ? never : K_1]: FieldValidation.Field<K_1 extends keyof ControlsOf<Inputs> ? ControlsOf<Inputs>[K_1] : DraftOf<Schema.Schema.Type<Fields[K_1]>>>; }[K];
1103
+ readonly send: (message: ControlMessageOf<Inputs[K]>) => {
1104
+ readonly _tag: "Changed";
1105
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1106
+ readonly value: string | boolean | readonly string[];
1107
+ } | {
1108
+ readonly _tag: "Blurred";
1109
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1110
+ } | {
1111
+ readonly _tag: "ValidatedAll";
1112
+ } | {
1113
+ readonly _tag: "Submitted";
1114
+ } | {
1115
+ readonly _tag: "Reset";
1116
+ } | {
1117
+ readonly _tag: "Checked";
1118
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1119
+ readonly draft: string | boolean | readonly string[];
1120
+ readonly error: string | null;
1121
+ } | {
1122
+ readonly _tag: "Refused";
1123
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1124
+ readonly error: string;
1125
+ } | {
1126
+ readonly _tag: "About";
1127
+ readonly subject: {
1128
+ readonly [x: string]: string;
1129
+ };
1130
+ } | {
1131
+ readonly _tag: "Searched";
1132
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1133
+ readonly text: string;
1134
+ } | {
1135
+ readonly _tag: "Nested";
1136
+ readonly key: string;
1137
+ readonly row: string;
1138
+ readonly message: unknown;
1139
+ } | {
1140
+ readonly _tag: "Control";
1141
+ readonly key: keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>;
1142
+ readonly message: unknown;
1143
+ } | {
1144
+ readonly _tag: "RowAdded";
1145
+ readonly key: string;
1146
+ } | {
1147
+ readonly _tag: "RowRemoved";
1148
+ readonly key: string;
1149
+ readonly row: string;
1150
+ };
1151
+ };
803
1152
  /** What was typed to find a choice for a relation key that searches; `''` until something is. */
804
- search: (model: FormModel<Fields, Members>, key: Exclude<keyof Fields & string, NestedKey<Members>>) => string;
1153
+ search: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, key: Exclude<keyof Fields & string, NestedKey<Members>>) => string;
805
1154
  /** What the form is editing; `{}` while it creates. See `FormModel.subject`. */
806
- subject: (model: FormModel<Fields, Members>) => Readonly<Record<string, string>>;
1155
+ subject: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => Readonly<Record<string, string>>;
807
1156
  /**
808
1157
  * The form of each nested key, typed when it was given under `nested`: its
809
1158
  * `controls`, its `field`, its Messages.
@@ -820,6 +1169,8 @@ export declare const Form: {
820
1169
  } | {
821
1170
  readonly _tag: "Blurred";
822
1171
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1172
+ } | {
1173
+ readonly _tag: "ValidatedAll";
823
1174
  } | {
824
1175
  readonly _tag: "Submitted";
825
1176
  } | {
@@ -847,6 +1198,10 @@ export declare const Form: {
847
1198
  readonly key: string;
848
1199
  readonly row: string;
849
1200
  readonly message: unknown;
1201
+ } | {
1202
+ readonly _tag: "Control";
1203
+ readonly key: keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>;
1204
+ readonly message: unknown;
850
1205
  } | {
851
1206
  readonly _tag: "RowAdded";
852
1207
  readonly key: string;
@@ -859,30 +1214,36 @@ export declare const Form: {
859
1214
  * Whether a key that follows another still does: `false` once the author has
860
1215
  * written it themselves. A view offers "regenerate" by sending the key an empty draft.
861
1216
  */
862
- isFollowing: (model: FormModel<Fields, Members>, key: Exclude<keyof Fields & string, NestedKey<Members>>) => boolean;
1217
+ isFollowing: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, key: Exclude<keyof Fields & string, NestedKey<Members>>) => boolean;
863
1218
  /** The rows of a nested key, each a Model of `control.form`. */
864
- rows: (model: FormModel<Fields, Members>, key: Extract<keyof Fields & string, NestedKey<Members>>) => { readonly [K in keyof Fields as K extends NestedKey<Members> ? K : never]: readonly FormRow<NestedModel<Members[K & keyof Members]>>[]; }[Extract<keyof Fields & string, NestedKey<Members>>];
1219
+ rows: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, key: Extract<keyof Fields & string, NestedKey<Members>>) => { readonly [K in keyof Fields as K extends NestedKey<Members> ? K : never]: readonly FormRow<NestedModel<Members[K & keyof Members]>>[]; }[Extract<keyof Fields & string, NestedKey<Members>>];
865
1220
  /**
866
1221
  * Whether a submit now could go through: nothing is invalid. A check still
867
1222
  * running does not stop it; the submit waits for the answer.
868
1223
  */
869
- canSubmit: (model: FormModel<Fields, Members>) => boolean;
1224
+ canSubmit: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
1225
+ /**
1226
+ * Whether the form is valid right now: a submit now would hand over the
1227
+ * value at once. Unlike `canSubmit`, a check running, or one a key has not
1228
+ * had yet, is not valid until it answers.
1229
+ */
1230
+ isValid: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
870
1231
  /**
871
1232
  * The Model with nothing in flight, for one that was stored and is shown
872
1233
  * again: a check that was running when it was stored will never answer, so
873
1234
  * its key is not validated yet, and no submit is waiting. Rows too.
874
1235
  */
875
- settled: (model: FormModel<Fields, Members>) => FormModel<Fields, Members>;
1236
+ settled: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => FormModel<Fields, Members, ControlsOf<Inputs>>;
876
1237
  /**
877
1238
  * What of the form decodes as it stands, by key: the value, less every key
878
1239
  * that is not valid yet. For saving unfinished work, which `engine.value`
879
1240
  * cannot give. A nested key is there once each of its rows has a value.
880
1241
  */
881
- partial: (model: FormModel<Fields, Members>) => Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>;
1242
+ partial: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>;
882
1243
  /** The form as the form that nests it drives it. */
883
1244
  engine: {
884
- submit: (model: FormModel<Fields, Members>) => {
885
- model: FormModel<Fields, Members>;
1245
+ submit: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => {
1246
+ model: FormModel<Fields, Members, ControlsOf<Inputs>>;
886
1247
  commands: readonly Readonly<{
887
1248
  name: string;
888
1249
  args?: Record<string, unknown>;
@@ -894,6 +1255,64 @@ export declare const Form: {
894
1255
  } | {
895
1256
  readonly _tag: "Blurred";
896
1257
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1258
+ } | {
1259
+ readonly _tag: "ValidatedAll";
1260
+ } | {
1261
+ readonly _tag: "Submitted";
1262
+ } | {
1263
+ readonly _tag: "Reset";
1264
+ } | {
1265
+ readonly _tag: "Checked";
1266
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1267
+ readonly draft: string | boolean | readonly string[];
1268
+ readonly error: string | null;
1269
+ } | {
1270
+ readonly _tag: "Refused";
1271
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1272
+ readonly error: string;
1273
+ } | {
1274
+ readonly _tag: "About";
1275
+ readonly subject: {
1276
+ readonly [x: string]: string;
1277
+ };
1278
+ } | {
1279
+ readonly _tag: "Searched";
1280
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1281
+ readonly text: string;
1282
+ } | {
1283
+ readonly _tag: "Nested";
1284
+ readonly key: string;
1285
+ readonly row: string;
1286
+ readonly message: unknown;
1287
+ } | {
1288
+ readonly _tag: "Control";
1289
+ readonly key: keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>;
1290
+ readonly message: unknown;
1291
+ } | {
1292
+ readonly _tag: "RowAdded";
1293
+ readonly key: string;
1294
+ } | {
1295
+ readonly _tag: "RowRemoved";
1296
+ readonly key: string;
1297
+ readonly row: string;
1298
+ }, never, R>;
1299
+ }>[];
1300
+ };
1301
+ validateAll: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => {
1302
+ readonly model: FormModel<Fields, Members, ControlsOf<Inputs>>;
1303
+ readonly commands: readonly Readonly<{
1304
+ name: string;
1305
+ args?: Record<string, unknown>;
1306
+ key?: string;
1307
+ effect: Effect.Effect<{
1308
+ readonly _tag: "Changed";
1309
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1310
+ readonly value: string | boolean | readonly string[];
1311
+ } | {
1312
+ readonly _tag: "Blurred";
1313
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1314
+ } | {
1315
+ readonly _tag: "ValidatedAll";
897
1316
  } | {
898
1317
  readonly _tag: "Submitted";
899
1318
  } | {
@@ -921,6 +1340,10 @@ export declare const Form: {
921
1340
  readonly key: string;
922
1341
  readonly row: string;
923
1342
  readonly message: unknown;
1343
+ } | {
1344
+ readonly _tag: "Control";
1345
+ readonly key: keyof ControlsOf<Inputs> & Exclude<keyof Fields & string, NestedKey<Members>>;
1346
+ readonly message: unknown;
924
1347
  } | {
925
1348
  readonly _tag: "RowAdded";
926
1349
  readonly key: string;
@@ -931,9 +1354,11 @@ export declare const Form: {
931
1354
  }, never, R>;
932
1355
  }>[];
933
1356
  };
934
- isValidating: (model: FormModel<Fields, Members>) => boolean;
1357
+ isValidating: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
1358
+ /** Whether a transition changed authored content, so a nesting form recurses. */
1359
+ authoredChanged: (before: FormModel<Fields, Members, ControlsOf<Inputs>>, after: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
935
1360
  /** The decoded input when every key and row is valid as it stands; validates nothing. */
936
- value: (model: FormModel<Fields, Members>) => Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>> | undefined;
1361
+ value: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>> | undefined;
937
1362
  };
938
1363
  pipe<A>(this: A): A;
939
1364
  pipe<A, B = never>(this: A, ab: (_: A) => B): B;
@@ -959,7 +1384,7 @@ export declare const Form: {
959
1384
  pipe<A, B_20 = never, C_19 = never, D_18 = never, E_18 = never, F_16 = never, G_15 = never, H_14 = never, I_13 = never, J_12 = never, K_11 = never, L_10 = never, M_9 = never, N_8 = never, O_7 = never, P_6 = never, Q_5 = never, R_5 = never, S_3 = never, T_2 = never, U_1 = never>(this: A, ab: (_: A) => B_20, bc: (_: B_20) => C_19, cd: (_: C_19) => D_18, de: (_: D_18) => E_18, ef: (_: E_18) => F_16, fg: (_: F_16) => G_15, gh: (_: G_15) => H_14, hi: (_: H_14) => I_13, ij: (_: I_13) => J_12, jk: (_: J_12) => K_11, kl: (_: K_11) => L_10, lm: (_: L_10) => M_9, mn: (_: M_9) => N_8, no: (_: N_8) => O_7, op: (_: O_7) => P_6, pq: (_: P_6) => Q_5, qr: (_: Q_5) => R_5, rs: (_: R_5) => S_3, st: (_: S_3) => T_2, tu: (_: T_2) => U_1): U_1;
960
1385
  /** The name, input and options the form was made from: what a pipe step makes the next form from. */
961
1386
  name: Name;
962
- options: FormOptions<Fields, Members, R, Nest>;
1387
+ options: FormOptions<Fields, Members, R, Nest, Inputs>;
963
1388
  /** Type-only: the form's type parameters, for a pipe step to read. Never set. */
964
1389
  types: {
965
1390
  readonly Name: Name;
@@ -968,6 +1393,7 @@ export declare const Form: {
968
1393
  readonly Members: Members;
969
1394
  readonly R: R;
970
1395
  readonly Nest: Nest;
1396
+ readonly Inputs: Inputs;
971
1397
  };
972
1398
  };
973
1399
  /**
@@ -985,5 +1411,5 @@ export declare const Form: {
985
1411
  }) => string | undefined;
986
1412
  };
987
1413
  //#endregion
988
- export type { Control, ControlChange, ControlKind, Draft, DraftKind, Follows, FormRow, NestedData, NestedForm, RelationData };
1414
+ export type { BundleControl, BundleControlSpec, BundleData, Control, ControlChange, ControlKind, Draft, DraftKind, Follows, FormRow, NestedData, NestedForm, RelationData };
989
1415
  //# sourceMappingURL=index.d.mts.map