foldkit-form 0.8.1 → 0.10.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.
@@ -1,297 +1,10 @@
1
+ import { BundleControl, BundleControlSpec, BundleData, Control, ControlChange, ControlKind, Draft, DraftKind, Follows, FormRow, Input, NestedData, NestedForm, RelationData } from "./input.js";
1
2
  import { Duration, Effect, Option, Schema } from "effect";
2
3
  import { Bundle } from "foldkit-bundle";
3
- import { AnyEntity, Entity, EntityInput, InputMember, MemoryOperators, NestedInput } from "foldkit-entity";
4
+ import { AnyEntity, Entity, EntityInput, InputMember, InputMembers, MemoryOperators, NestedInput } from "foldkit-entity";
4
5
  import { Metadata } from "foldkit-metadata";
5
6
  import { Command } from "foldkit/command";
6
7
  import * as FieldValidation from "foldkit/fieldValidation";
7
- /**
8
- * What a control holds while it is edited, which is not the value it submits: a
9
- * number being typed is text, and an unchosen relation is the empty string.
10
- */
11
- type Draft = string | boolean | ReadonlyArray<string>;
12
- /**
13
- * The draft a control holds. `rows` is a nested key: rows of a form, not a
14
- * draft. `model` is a control backed by a Bundle (`Input.bundle`): its draft is
15
- * the Bundle's Model.
16
- */
17
- type DraftKind = 'text' | 'flag' | 'list' | 'rows' | 'model';
18
- /** What edits one key: the primitive every kind of control is a value of. */
19
- interface Control<Data = unknown> {
20
- /** The name a renderer is found by. */
21
- readonly kind: string;
22
- readonly draft: DraftKind;
23
- /** Whether a view draws it. A control carried and submitted, not shown, is `false`. */
24
- readonly shown: boolean;
25
- /**
26
- * Whether the form also holds what the user typed to find a choice, which the
27
- * application reads as the input of the query that lists the choices.
28
- */
29
- readonly searches: boolean;
30
- /** What this kind needs: a select's options, a relation's target. */
31
- readonly data: Data;
32
- /**
33
- * For a `text` draft: the value the key's schema is given, when that is not the
34
- * text itself, read with the control's `data` (a select's options). `undefined`
35
- * means the text does not read as one.
36
- */
37
- parse?(draft: string, data: Data): unknown;
38
- /**
39
- * For a `list` draft: the value the key's schema is given, read with the
40
- * control's `data` (a choice group's options). `undefined` means one of the
41
- * chosen values is not one of them.
42
- */
43
- parseList?(draft: ReadonlyArray<string>, data: Data): unknown;
44
- /**
45
- * For a `text` draft: the text a value is shown as when the form is filled
46
- * with it, the inverse of `parse`. Default `String(value)`.
47
- */
48
- format?(value: unknown, data: Data): string;
49
- /** What to say when `parse` gives `undefined`. */
50
- readonly unparsed?: string | undefined;
51
- /**
52
- * For a `text` draft: another key of the form this one is written from until
53
- * the author writes it themselves. A slug follows a title.
54
- */
55
- readonly follows?: Follows | undefined;
56
- }
57
- /** Which key a draft follows, and what it makes of that key's text. */
58
- interface Follows {
59
- readonly key: string;
60
- readonly through: (text: string) => string;
61
- }
62
- /** A kind of control: how its values are made, and how one is told from another. */
63
- interface ControlKind<Data> {
64
- readonly kind: string;
65
- readonly of: (data: Data) => Control<Data>;
66
- readonly is: (control: Control) => control is Control<Data>;
67
- }
68
- /**
69
- * Under `inputs`, in place of a control: a change to the control the form would
70
- * have resolved, such as giving the key's relation picker a search.
71
- */
72
- interface ControlChange {
73
- readonly change: (resolved: Control | undefined, key: string) => Control;
74
- }
75
- /** One row of a nested key: a Model of the nested form, under an id that outlives reordering. */
76
- interface FormRow<Model = unknown> {
77
- readonly id: string;
78
- readonly model: Model;
79
- }
80
- /** What a view needs of a nested form to draw its rows. Every form `Form.make` returns is one. */
81
- interface NestedForm {
82
- readonly controls: ReadonlyArray<{
83
- readonly key: string;
84
- readonly control: Control;
85
- readonly label: string;
86
- readonly description: string | undefined;
87
- readonly required: boolean;
88
- }>;
89
- readonly field: (model: never, key: never) => unknown;
90
- readonly rows: (model: never, key: never) => ReadonlyArray<FormRow>;
91
- readonly search: (model: never, key: never) => string;
92
- readonly isFollowing: (model: never, key: never) => boolean;
93
- /** A key edited by a control backed by a Bundle: its state, with the Bundle's Model as the value. */
94
- readonly control: (key: never) => {
95
- readonly field: (model: never) => unknown;
96
- };
97
- readonly Message: {
98
- readonly Changed: (payload: never) => unknown;
99
- readonly Control: (payload: never) => unknown;
100
- readonly Blurred: (payload: never) => unknown;
101
- readonly Searched: (payload: never) => unknown;
102
- readonly Toggled: (payload: never) => unknown;
103
- readonly Nested: (payload: never) => unknown;
104
- readonly RowAdded: (payload: never) => unknown;
105
- readonly RowRemoved: (payload: never) => unknown;
106
- };
107
- }
108
- /**
109
- * What every kind's spec says, whatever its draft holds. The draft decides which
110
- * hooks a spec may carry, so a hook that draft can never reach is a type error
111
- * rather than a hook that is silently never called.
112
- */
113
- interface ControlSpec<Data, Draft extends DraftKind> {
114
- readonly draft: Draft;
115
- readonly shown?: boolean;
116
- readonly searches?: boolean | ((data: Data) => boolean);
117
- readonly unparsed?: string;
118
- }
119
- /** A text draft: read by `parse`, shown by `format`. */
120
- interface TextSpec<Data> extends ControlSpec<Data, 'text'> {
121
- /** The value the text stands for, given the control's data; `undefined` when it stands for none. */
122
- readonly parse?: (draft: string, data: Data) => unknown;
123
- /** The text a value is shown as when the form is filled with it. */
124
- readonly format?: (value: unknown, data: Data) => string;
125
- readonly parseList?: never;
126
- }
127
- /** A list draft: each chosen value as text, read by `parseList`. */
128
- interface ListSpec<Data> extends ControlSpec<Data, 'list'> {
129
- /** The value the chosen values stand for, given the control's data; `undefined` when one is not allowed. */
130
- readonly parseList?: (draft: ReadonlyArray<string>, data: Data) => unknown;
131
- readonly parse?: never;
132
- readonly format?: never;
133
- }
134
- /** A draft with nothing to read or show: a flag, rows, or a Bundle's Model. */
135
- interface PlainSpec<Data> extends ControlSpec<Data, 'flag' | 'rows' | 'model'> {
136
- readonly parse?: never;
137
- readonly parseList?: never;
138
- readonly format?: never;
139
- }
140
- /** What `Input.kind` takes. */
141
- type Spec<Data> = TextSpec<Data> | ListSpec<Data> | PlainSpec<Data>;
142
- /** A kind of control. The kinds below are made with it, and so is an application's. */
143
- declare const kind: <Data = Record<string, never>>(name: string, spec: Spec<Data>) => ControlKind<Data>;
144
- /**
145
- * What a control backed by a Bundle carries: the Bundle, its args, and how the
146
- * key's value is read from its Model and written into it.
147
- */
148
- interface BundleData<Model = any, Value = any> {
149
- readonly bundle: Bundle.AnyBundle;
150
- readonly args: unknown;
151
- /** The value the key validates and submits. `undefined` or `null` is nothing entered. */
152
- readonly value: (model: Model) => Value | null | undefined;
153
- /** The Model showing a value the form was given, from the Model the control holds. */
154
- readonly fill: (model: Model, value: Value) => Model;
155
- /** The Model with nothing in flight, for a stored form shown again. */
156
- readonly settled: (model: Model) => Model;
157
- /** Whether work the key's value waits on is in flight: a submit waits for it, as for a check. */
158
- readonly busy: (model: Model) => boolean;
159
- }
160
- /**
161
- * A control backed by a Bundle. Its draft is the Bundle's Model, its Messages
162
- * reach it through the form, and its Commands, Subscriptions and Resources are
163
- * the form's.
164
- */
165
- interface BundleControl<Model, Message, Value, Resources = {}> extends Control<BundleData<Model, Value>> {
166
- readonly draft: 'model';
167
- /** Type-only: the Bundle's Message, for `form.control(key).send`. Never set. */
168
- readonly Message?: Message;
169
- /** Type-only: the Bundle's Resources, which a runtime running the form must provide. Never set. */
170
- readonly Resources?: Resources;
171
- }
172
- /** What `Input.bundle` takes: the Bundle, then how the key's value lives in its Model. */
173
- type BundleControlSpec<Args, Model, Message extends {
174
- readonly _tag: string;
175
- }, Value, Resources extends Bundle.ResourceEntries<Model, Message> = {}> = {
176
- /**
177
- * The Bundle. Its Commands may need no services, and it has no OutMessage: a
178
- * form key has no parent to hand one to, and an OutMessage is never dropped
179
- * by omission.
180
- */
181
- readonly bundle: Bundle.Bundle<any, Args, Model, Message, never, never, any, any, Resources, any>;
182
- /** The value the key validates and submits. `undefined` or `null` is nothing entered. */
183
- readonly value: (model: Model) => Value | null | undefined;
184
- /** The Model showing a value the form was given (`fill`), from the Model the control holds. */
185
- readonly fill: (model: Model, value: Value) => Model;
186
- /** The Model with nothing in flight, for a stored form shown again. Default: as it is. */
187
- readonly settled?: (model: Model) => Model;
188
- /**
189
- * Whether work the key's value waits on is in flight, such as an upload. A
190
- * submit made meanwhile waits, as it waits for a check, and goes when the work
191
- * lands or ends. Default: never. Give `settled` beside it: a stored form shown
192
- * again has no work in flight, and one left busy would hold every submit back,
193
- * so `Input.bundle` refuses `busy` without it.
194
- */
195
- readonly busy?: (model: Model) => boolean;
196
- } & ([Args] extends [void] ? {
197
- readonly args?: undefined;
198
- } : {
199
- readonly args: Args;
200
- });
201
- /** A relation picker: what it chooses from, and whether it searches. */
202
- interface RelationData {
203
- readonly target: AnyEntity;
204
- readonly search: boolean;
205
- }
206
- /** A nested key: how many rows it may hold, and the form each row is a Model of. */
207
- interface NestedData {
208
- readonly cardinality: 'one' | 'many';
209
- /** Whether the rows may be none: always for a `many`, for a `one` when its schema admits nothing. */
210
- readonly optional: boolean;
211
- readonly form: NestedForm;
212
- }
213
- export declare const Input: {
214
- /**
215
- * A kind of control. `Input.kind<{ min: string }>('Date', { draft: 'text' })`
216
- * gives `.of(data)` to make one and `.is(control)` to tell one, exactly as the
217
- * kinds below were made. A view draws it once it is given a renderer for `Date`.
218
- */
219
- kind: typeof kind;
220
- Text: ControlKind<Record<string, never>>;
221
- Hidden: ControlKind<Record<string, never>>;
222
- Multiline: ControlKind<Record<string, never>>;
223
- Number: ControlKind<Record<string, never>>;
224
- Toggle: ControlKind<Record<string, never>>;
225
- Select: ControlKind<{
226
- readonly options: ReadonlyArray<string | number>;
227
- }>;
228
- Choices: ControlKind<{
229
- readonly options: ReadonlyArray<string | number>;
230
- }>;
231
- RelationOne: ControlKind<RelationData>;
232
- RelationMany: ControlKind<RelationData>;
233
- Nested: ControlKind<NestedData>;
234
- /**
235
- * A control backed by a Bundle, for a draft that is a Model of its own: a
236
- * color picker with a popover, a page builder, a rich-text editor. The key's
237
- * draft is the Bundle's Model; `value` reads what the key validates and
238
- * submits from it, and `fill` writes a given value into it. The Bundle's
239
- * Messages travel as the form's `Control` Message, and its Commands,
240
- * Subscriptions and Resources become the form's.
241
- */
242
- bundle: <Args, Model, Message extends {
243
- readonly _tag: string;
244
- }, Value, Resources extends Bundle.ResourceEntries<Model, Message> = {}>(kind: string, spec: BundleControlSpec<Args, Model, Message, Value, Resources>) => BundleControl<Model, Message, Value, Resources>;
245
- /** Whether a control is backed by a Bundle, whatever its kind is called. */
246
- isBundle: (control: Control) => control is Control<BundleData>;
247
- text: () => Control;
248
- /** Carried and submitted, not shown: the id of the thing being edited. Set it with `fill`. */
249
- hidden: () => Control;
250
- multiline: () => Control;
251
- number: () => Control;
252
- toggle: () => Control;
253
- select: (options: ReadonlyArray<string | number>) => Control;
254
- /**
255
- * Any number of a fixed set, text or numbers. A key typed
256
- * `Schema.Array(Schema.Literals([...]))` resolves to one without asking; name
257
- * it here for a set the schema cannot spell.
258
- */
259
- choices: (options: ReadonlyArray<string | number>) => Control;
260
- /**
261
- * A picker of one of `target`, for a value that is not a relation of the
262
- * form's Entity: a page Builder's Block prop that holds an id. A relation key
263
- * resolves to its picker without asking.
264
- */
265
- relationOne: (target: AnyEntity) => Control;
266
- /** A picker of any number of `target`, as `relationOne` is of one. */
267
- relationMany: (target: AnyEntity) => Control;
268
- /**
269
- * For a relation key, under `inputs`: its picker, with a search. Too many to
270
- * list is the usual case for a relation; the form holds the search text, and
271
- * the query that lists the options takes it as input.
272
- */
273
- search: () => ControlChange;
274
- /**
275
- * Under `inputs`: the key's own control, following another key. Until the
276
- * author writes this key, its draft is `through` of that key's text, rewritten
277
- * as that key is edited; once they write it, it is theirs. Emptying it hands
278
- * it back. A form filled with a value for it does not follow: an address that
279
- * is already published must not move because its title did.
280
- */
281
- following: (key: string, through?: (text: string) => string) => ControlChange;
282
- /**
283
- * Entity metadata: the control a member is edited with wherever it appears,
284
- * e.g. `Entity.annotateMembers({ body: Input.of(Input.multiline()) })`.
285
- */
286
- of: (control: Control) => Metadata;
287
- /**
288
- * The control for one input key, from the most to the least explicit source:
289
- * the member's `Input.of` metadata, the relation it writes, then the shape of
290
- * its schema. `undefined` when none of them says, which a form reports rather
291
- * than guessing.
292
- */
293
- resolve: (member: InputMember, schema: Schema.Top) => Control | undefined;
294
- };
295
8
  /** The draft a key holds, as far as the input's type says: a flag, a list of ids, or text. */
296
9
  export type DraftOf<Value> = [Exclude<Value, null | undefined>] extends [boolean] ? boolean : [Exclude<Value, null | undefined>] extends [ReadonlyArray<unknown>] ? ReadonlyArray<string> : string;
297
10
  /** The keys of an input that hold a nested input (`Relation.nested`): rows of a form, not a draft. */
@@ -326,8 +39,22 @@ export interface FormModel<Fields extends Schema.Struct.Fields, Members = {}, Co
326
39
  * they follow no longer. A key that follows nothing is never here.
327
40
  */
328
41
  readonly touched: Readonly<Record<string, boolean>>;
42
+ /**
43
+ * A submit has been asked since the form started, was filled or was reset.
44
+ * A view draws its list of fields to fix only then. `ValidatedAll` is not
45
+ * one: the page that sends it owns the submit.
46
+ */
47
+ readonly attempted: boolean;
329
48
  /** Failures of the input as a whole, from the last submit: a rule that spans keys. */
330
49
  readonly errors: ReadonlyArray<string>;
50
+ /**
51
+ * Failures a judgement of the whole put on a key, apart from the key's own
52
+ * schema and check: an Entity invariant's at a submit, or `Message.Refused`.
53
+ * `field` shows them on their key. Any edit clears them, since an edit of
54
+ * one key can mend a rule that names another; until then a submit stops,
55
+ * since the same value would be judged the same.
56
+ */
57
+ readonly marks: Readonly<Record<string, ReadonlyArray<string>>>;
331
58
  /** A submit is waiting for checks still running; it goes out when the last one passes. */
332
59
  readonly submitPending: boolean;
333
60
  /**
@@ -495,7 +222,7 @@ declare const Core: {
495
222
  * a login): `Entity.input` over an Entity defined from the same schema, so
496
223
  * every key maps itself. `Form.make('Waitlist', Form.input(JoinWaitlist))`.
497
224
  */
498
- input: <Fields extends Schema.Struct.Fields>(schema: Schema.Struct<Fields>) => EntityInput<Entity<"FormInput", Fields, {}, {}>, Fields, { readonly [K in keyof Fields]: K extends never ? {}[K] extends (infer T) ? T extends {}[K] ? T extends string ? T extends keyof Fields & string ? { readonly [K_1 in keyof Fields & string]: import("foldkit-entity").EntityField<"FormInput", K_1, Fields[K_1]>; }[T] : T extends never ? import("foldkit-entity").RelationInput<{}[T]> : `"${T}" names no field or relation of FormInput` : T : never : never : K extends keyof Fields & string ? { readonly [K_1 in keyof Fields & string]: import("foldkit-entity").EntityField<"FormInput", K_1, Fields[K_1]>; }[K] : never; }>;
225
+ input: <Fields extends Schema.Struct.Fields>(schema: Schema.Struct<Fields>) => EntityInput<Entity<'FormInput', Fields>, Fields, InputMembers<Entity<'FormInput', Fields>, Fields, {}>>;
499
226
  /**
500
227
  * A form for one operation's input. A key mapped with `Relation.nested` holds
501
228
  * rows of a form of its own, built here from the nested input; every other key
@@ -557,6 +284,10 @@ declare const Core: {
557
284
  readonly _tag: "Checked";
558
285
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
559
286
  readonly draft: string | boolean | readonly string[];
287
+ readonly values?: unknown;
288
+ readonly subject?: {
289
+ readonly [x: string]: string;
290
+ };
560
291
  readonly error: string | null;
561
292
  } | {
562
293
  readonly _tag: "Control";
@@ -574,6 +305,7 @@ declare const Core: {
574
305
  readonly _tag: "Refused";
575
306
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
576
307
  readonly error: string;
308
+ readonly value: unknown;
577
309
  } | {
578
310
  readonly _tag: "Reset";
579
311
  } | {
@@ -593,9 +325,12 @@ declare const Core: {
593
325
  readonly _tag: "Toggled";
594
326
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
595
327
  readonly choice?: string | undefined;
328
+ } | {
329
+ readonly _tag: "Validated";
330
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
596
331
  } | {
597
332
  readonly _tag: "ValidatedAll";
598
- }, Submitted<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>, R, never, void, ControlResourcesOf<Inputs>, {
333
+ }, Submitted<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>, R, never, import("foldkit-bundle").NoView, ControlResourcesOf<Inputs>, {
599
334
  fill: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, values: Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>) => {
600
335
  readonly model: FormModel<Fields, Members, ControlsOf<Inputs>>;
601
336
  };
@@ -605,10 +340,21 @@ declare const Core: {
605
340
  key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
606
341
  value: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
607
342
  };
608
- /** Validates the key as it stands, so a required key left empty says so. */
343
+ /**
344
+ * The person left the key. An edit has already validated it, and a key
345
+ * never edited is not judged before a submit, so tabbing through a field
346
+ * says nothing about it: the form changes nothing.
347
+ */
609
348
  Blurred: {
610
349
  key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
611
350
  };
351
+ /**
352
+ * Validates the key as it stands, edited or not: for a program showing a
353
+ * stored value's failure after a `fill`, which validates nothing.
354
+ */
355
+ Validated: {
356
+ key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
357
+ };
612
358
  /**
613
359
  * Validates every key not validated yet, in every row too, as a submit
614
360
  * would, and submits nothing: for a page that submits several forms at once.
@@ -617,21 +363,31 @@ declare const Core: {
617
363
  ValidatedAll: {};
618
364
  Submitted: {};
619
365
  Reset: {};
620
- /** The answer of a check for the draft it was asked about; one for an older draft is dropped. */
366
+ /**
367
+ * The answer of a check for the draft it was asked about; one for an older
368
+ * draft is dropped. `form.Check` also says the `values` and `subject` it
369
+ * read, and an answer about ones the form no longer holds is asked again.
370
+ * One made without them (a test's) answers the form as it is.
371
+ */
621
372
  Checked: {
622
373
  key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
623
374
  draft: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
375
+ values: Schema.optionalKey<Schema.Unknown>;
376
+ subject: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
624
377
  error: Schema.NullOr<Schema.String>;
625
378
  };
626
379
  /**
627
380
  * The outside world refused this key's value: a unique index, a rule only a
628
- * server knows. The key reads invalid with that reason, keeping what was
629
- * typed, until it is edited again. Unlike `Checked`, it answers no question
630
- * the form asked, so it lands whatever state the key is in.
381
+ * server knows. `value` is the key's value in what was refused, as
382
+ * `Submitted` handed it out. While the key still holds it, the key reads
383
+ * invalid with that reason (a mark, see `FormModel.marks`) until the next
384
+ * edit of any key; a key changed since is not what was refused, and the
385
+ * Message is dropped.
631
386
  */
632
387
  Refused: {
633
388
  key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
634
389
  error: Schema.String;
390
+ value: Schema.Unknown;
635
391
  };
636
392
  /**
637
393
  * What the form is editing, for the checks that need to know: a post's own
@@ -708,6 +464,10 @@ declare const Core: {
708
464
  readonly _tag: "Checked";
709
465
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
710
466
  readonly draft: string | boolean | readonly string[];
467
+ readonly values?: unknown;
468
+ readonly subject?: {
469
+ readonly [x: string]: string;
470
+ };
711
471
  readonly error: string | null;
712
472
  }, never, R>>;
713
473
  /** The reading the form was made from, for `Entity.selectFor` and `Entity.valuesFor`. */
@@ -723,9 +483,26 @@ declare const Core: {
723
483
  /** The keys in the input's order, each with its control, label, and member. */
724
484
  controls: FormControl<keyof Fields & string>[];
725
485
  /**
726
- * One key's state with its draft as any `Draft`, for a view that walks
727
- * `controls`. `model.fields.title` is the same value, typed to that key. A
728
- * nested key has rows and no draft.
486
+ * Over a variant Entity's input, the case its `_tag` key names as it
487
+ * stands; none before one is chosen, and for any other form.
488
+ */
489
+ chosen: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => Option.Option<string>;
490
+ /**
491
+ * Whether a view draws `key` now: a key of a field only some cases have is
492
+ * asked, validated and submitted only once one of those cases is chosen.
493
+ * Every key of any other form.
494
+ */
495
+ shows: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, key: Exclude<keyof Fields & string, NestedKey<Members>>) => boolean;
496
+ /**
497
+ * The same controls by key, for a view that places each field itself:
498
+ * `form.controlsByKey.email.label`.
499
+ */
500
+ controlsByKey: { readonly [K in keyof Fields & string]: FormControl<K>; };
501
+ /**
502
+ * One key's state as a view shows it, with its draft as any `Draft`: its
503
+ * own validation, made `Invalid` by the marks on it (`FormModel.marks`).
504
+ * `model.fields.title` is the key's own validation alone. A nested key has
505
+ * rows and no draft.
729
506
  */
730
507
  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>;
731
508
  /**
@@ -754,6 +531,10 @@ declare const Core: {
754
531
  readonly _tag: "Checked";
755
532
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
756
533
  readonly draft: string | boolean | readonly string[];
534
+ readonly values?: unknown;
535
+ readonly subject?: {
536
+ readonly [x: string]: string;
537
+ };
757
538
  readonly error: string | null;
758
539
  } | {
759
540
  readonly _tag: "Control";
@@ -771,6 +552,7 @@ declare const Core: {
771
552
  readonly _tag: "Refused";
772
553
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
773
554
  readonly error: string;
555
+ readonly value: unknown;
774
556
  } | {
775
557
  readonly _tag: "Reset";
776
558
  } | {
@@ -790,6 +572,9 @@ declare const Core: {
790
572
  readonly _tag: "Toggled";
791
573
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
792
574
  readonly choice?: string | undefined;
575
+ } | {
576
+ readonly _tag: "Validated";
577
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
793
578
  } | {
794
579
  readonly _tag: "ValidatedAll";
795
580
  };
@@ -826,6 +611,10 @@ declare const Core: {
826
611
  readonly _tag: "Checked";
827
612
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
828
613
  readonly draft: string | boolean | readonly string[];
614
+ readonly values?: unknown;
615
+ readonly subject?: {
616
+ readonly [x: string]: string;
617
+ };
829
618
  readonly error: string | null;
830
619
  } | {
831
620
  readonly _tag: "Control";
@@ -843,6 +632,7 @@ declare const Core: {
843
632
  readonly _tag: "Refused";
844
633
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
845
634
  readonly error: string;
635
+ readonly value: unknown;
846
636
  } | {
847
637
  readonly _tag: "Reset";
848
638
  } | {
@@ -862,6 +652,9 @@ declare const Core: {
862
652
  readonly _tag: "Toggled";
863
653
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
864
654
  readonly choice?: string | undefined;
655
+ } | {
656
+ readonly _tag: "Validated";
657
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
865
658
  } | {
866
659
  readonly _tag: "ValidatedAll";
867
660
  }>;
@@ -877,6 +670,8 @@ declare const Core: {
877
670
  * running does not stop it; the submit waits for the answer.
878
671
  */
879
672
  canSubmit: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
673
+ /** Whether a submit was asked since the form started, was filled or was reset. */
674
+ attempted: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
880
675
  /**
881
676
  * Whether the form is valid right now: a submit now would hand over the
882
677
  * value at once. Unlike `canSubmit`, a check running, or one a key has not
@@ -930,6 +725,10 @@ declare const Core: {
930
725
  readonly _tag: "Checked";
931
726
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
932
727
  readonly draft: string | boolean | readonly string[];
728
+ readonly values?: unknown;
729
+ readonly subject?: {
730
+ readonly [x: string]: string;
731
+ };
933
732
  readonly error: string | null;
934
733
  } | {
935
734
  readonly _tag: "Control";
@@ -947,6 +746,7 @@ declare const Core: {
947
746
  readonly _tag: "Refused";
948
747
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
949
748
  readonly error: string;
749
+ readonly value: unknown;
950
750
  } | {
951
751
  readonly _tag: "Reset";
952
752
  } | {
@@ -966,6 +766,9 @@ declare const Core: {
966
766
  readonly _tag: "Toggled";
967
767
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
968
768
  readonly choice?: string | undefined;
769
+ } | {
770
+ readonly _tag: "Validated";
771
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
969
772
  } | {
970
773
  readonly _tag: "ValidatedAll";
971
774
  }, never, R>;
@@ -996,6 +799,10 @@ declare const Core: {
996
799
  readonly _tag: "Checked";
997
800
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
998
801
  readonly draft: string | boolean | readonly string[];
802
+ readonly values?: unknown;
803
+ readonly subject?: {
804
+ readonly [x: string]: string;
805
+ };
999
806
  readonly error: string | null;
1000
807
  } | {
1001
808
  readonly _tag: "Control";
@@ -1013,6 +820,7 @@ declare const Core: {
1013
820
  readonly _tag: "Refused";
1014
821
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1015
822
  readonly error: string;
823
+ readonly value: unknown;
1016
824
  } | {
1017
825
  readonly _tag: "Reset";
1018
826
  } | {
@@ -1032,6 +840,9 @@ declare const Core: {
1032
840
  readonly _tag: "Toggled";
1033
841
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1034
842
  readonly choice?: string | undefined;
843
+ } | {
844
+ readonly _tag: "Validated";
845
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1035
846
  } | {
1036
847
  readonly _tag: "ValidatedAll";
1037
848
  }, never, R>;
@@ -1084,7 +895,7 @@ export declare const Form: {
1084
895
  * a login): `Entity.input` over an Entity defined from the same schema, so
1085
896
  * every key maps itself. `Form.make('Waitlist', Form.input(JoinWaitlist))`.
1086
897
  */
1087
- input: <Fields extends Schema.Struct.Fields>(schema: Schema.Struct<Fields>) => EntityInput<Entity<"FormInput", Fields, {}, {}>, Fields, { readonly [K in keyof Fields]: K extends never ? {}[K] extends (infer T) ? T extends {}[K] ? T extends string ? T extends keyof Fields & string ? { readonly [K_1 in keyof Fields & string]: import("foldkit-entity").EntityField<"FormInput", K_1, Fields[K_1]>; }[T] : T extends never ? import("foldkit-entity").RelationInput<{}[T]> : `"${T}" names no field or relation of FormInput` : T : never : never : K extends keyof Fields & string ? { readonly [K_1 in keyof Fields & string]: import("foldkit-entity").EntityField<"FormInput", K_1, Fields[K_1]>; }[K] : never; }>;
898
+ input: <Fields extends Schema.Struct.Fields>(schema: Schema.Struct<Fields>) => EntityInput<Entity<'FormInput', Fields>, Fields, InputMembers<Entity<'FormInput', Fields>, Fields, {}>>;
1088
899
  /**
1089
900
  * A form for one operation's input. A key mapped with `Relation.nested` holds
1090
901
  * rows of a form of its own, built here from the nested input; every other key
@@ -1146,6 +957,10 @@ export declare const Form: {
1146
957
  readonly _tag: "Checked";
1147
958
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1148
959
  readonly draft: string | boolean | readonly string[];
960
+ readonly values?: unknown;
961
+ readonly subject?: {
962
+ readonly [x: string]: string;
963
+ };
1149
964
  readonly error: string | null;
1150
965
  } | {
1151
966
  readonly _tag: "Control";
@@ -1163,6 +978,7 @@ export declare const Form: {
1163
978
  readonly _tag: "Refused";
1164
979
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1165
980
  readonly error: string;
981
+ readonly value: unknown;
1166
982
  } | {
1167
983
  readonly _tag: "Reset";
1168
984
  } | {
@@ -1182,9 +998,12 @@ export declare const Form: {
1182
998
  readonly _tag: "Toggled";
1183
999
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1184
1000
  readonly choice?: string | undefined;
1001
+ } | {
1002
+ readonly _tag: "Validated";
1003
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1185
1004
  } | {
1186
1005
  readonly _tag: "ValidatedAll";
1187
- }, Submitted<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>, R, never, void, ControlResourcesOf<Inputs>, {
1006
+ }, Submitted<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>, R, never, import("foldkit-bundle").NoView, ControlResourcesOf<Inputs>, {
1188
1007
  fill: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, values: Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>) => {
1189
1008
  readonly model: FormModel<Fields, Members, ControlsOf<Inputs>>;
1190
1009
  };
@@ -1194,10 +1013,21 @@ export declare const Form: {
1194
1013
  key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1195
1014
  value: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
1196
1015
  };
1197
- /** Validates the key as it stands, so a required key left empty says so. */
1016
+ /**
1017
+ * The person left the key. An edit has already validated it, and a key
1018
+ * never edited is not judged before a submit, so tabbing through a field
1019
+ * says nothing about it: the form changes nothing.
1020
+ */
1198
1021
  Blurred: {
1199
1022
  key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1200
1023
  };
1024
+ /**
1025
+ * Validates the key as it stands, edited or not: for a program showing a
1026
+ * stored value's failure after a `fill`, which validates nothing.
1027
+ */
1028
+ Validated: {
1029
+ key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1030
+ };
1201
1031
  /**
1202
1032
  * Validates every key not validated yet, in every row too, as a submit
1203
1033
  * would, and submits nothing: for a page that submits several forms at once.
@@ -1206,21 +1036,31 @@ export declare const Form: {
1206
1036
  ValidatedAll: {};
1207
1037
  Submitted: {};
1208
1038
  Reset: {};
1209
- /** The answer of a check for the draft it was asked about; one for an older draft is dropped. */
1039
+ /**
1040
+ * The answer of a check for the draft it was asked about; one for an older
1041
+ * draft is dropped. `form.Check` also says the `values` and `subject` it
1042
+ * read, and an answer about ones the form no longer holds is asked again.
1043
+ * One made without them (a test's) answers the form as it is.
1044
+ */
1210
1045
  Checked: {
1211
1046
  key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1212
1047
  draft: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
1048
+ values: Schema.optionalKey<Schema.Unknown>;
1049
+ subject: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
1213
1050
  error: Schema.NullOr<Schema.String>;
1214
1051
  };
1215
1052
  /**
1216
1053
  * The outside world refused this key's value: a unique index, a rule only a
1217
- * server knows. The key reads invalid with that reason, keeping what was
1218
- * typed, until it is edited again. Unlike `Checked`, it answers no question
1219
- * the form asked, so it lands whatever state the key is in.
1054
+ * server knows. `value` is the key's value in what was refused, as
1055
+ * `Submitted` handed it out. While the key still holds it, the key reads
1056
+ * invalid with that reason (a mark, see `FormModel.marks`) until the next
1057
+ * edit of any key; a key changed since is not what was refused, and the
1058
+ * Message is dropped.
1220
1059
  */
1221
1060
  Refused: {
1222
1061
  key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1223
1062
  error: Schema.String;
1063
+ value: Schema.Unknown;
1224
1064
  };
1225
1065
  /**
1226
1066
  * What the form is editing, for the checks that need to know: a post's own
@@ -1297,6 +1137,10 @@ export declare const Form: {
1297
1137
  readonly _tag: "Checked";
1298
1138
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1299
1139
  readonly draft: string | boolean | readonly string[];
1140
+ readonly values?: unknown;
1141
+ readonly subject?: {
1142
+ readonly [x: string]: string;
1143
+ };
1300
1144
  readonly error: string | null;
1301
1145
  }, never, R>>;
1302
1146
  /** The reading the form was made from, for `Entity.selectFor` and `Entity.valuesFor`. */
@@ -1312,9 +1156,26 @@ export declare const Form: {
1312
1156
  /** The keys in the input's order, each with its control, label, and member. */
1313
1157
  controls: FormControl<keyof Fields & string>[];
1314
1158
  /**
1315
- * One key's state with its draft as any `Draft`, for a view that walks
1316
- * `controls`. `model.fields.title` is the same value, typed to that key. A
1317
- * nested key has rows and no draft.
1159
+ * Over a variant Entity's input, the case its `_tag` key names as it
1160
+ * stands; none before one is chosen, and for any other form.
1161
+ */
1162
+ chosen: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => Option.Option<string>;
1163
+ /**
1164
+ * Whether a view draws `key` now: a key of a field only some cases have is
1165
+ * asked, validated and submitted only once one of those cases is chosen.
1166
+ * Every key of any other form.
1167
+ */
1168
+ shows: (model: FormModel<Fields, Members, ControlsOf<Inputs>>, key: Exclude<keyof Fields & string, NestedKey<Members>>) => boolean;
1169
+ /**
1170
+ * The same controls by key, for a view that places each field itself:
1171
+ * `form.controlsByKey.email.label`.
1172
+ */
1173
+ controlsByKey: { readonly [K in keyof Fields & string]: FormControl<K>; };
1174
+ /**
1175
+ * One key's state as a view shows it, with its draft as any `Draft`: its
1176
+ * own validation, made `Invalid` by the marks on it (`FormModel.marks`).
1177
+ * `model.fields.title` is the key's own validation alone. A nested key has
1178
+ * rows and no draft.
1318
1179
  */
1319
1180
  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>;
1320
1181
  /**
@@ -1343,6 +1204,10 @@ export declare const Form: {
1343
1204
  readonly _tag: "Checked";
1344
1205
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1345
1206
  readonly draft: string | boolean | readonly string[];
1207
+ readonly values?: unknown;
1208
+ readonly subject?: {
1209
+ readonly [x: string]: string;
1210
+ };
1346
1211
  readonly error: string | null;
1347
1212
  } | {
1348
1213
  readonly _tag: "Control";
@@ -1360,6 +1225,7 @@ export declare const Form: {
1360
1225
  readonly _tag: "Refused";
1361
1226
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1362
1227
  readonly error: string;
1228
+ readonly value: unknown;
1363
1229
  } | {
1364
1230
  readonly _tag: "Reset";
1365
1231
  } | {
@@ -1379,6 +1245,9 @@ export declare const Form: {
1379
1245
  readonly _tag: "Toggled";
1380
1246
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1381
1247
  readonly choice?: string | undefined;
1248
+ } | {
1249
+ readonly _tag: "Validated";
1250
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1382
1251
  } | {
1383
1252
  readonly _tag: "ValidatedAll";
1384
1253
  };
@@ -1415,6 +1284,10 @@ export declare const Form: {
1415
1284
  readonly _tag: "Checked";
1416
1285
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1417
1286
  readonly draft: string | boolean | readonly string[];
1287
+ readonly values?: unknown;
1288
+ readonly subject?: {
1289
+ readonly [x: string]: string;
1290
+ };
1418
1291
  readonly error: string | null;
1419
1292
  } | {
1420
1293
  readonly _tag: "Control";
@@ -1432,6 +1305,7 @@ export declare const Form: {
1432
1305
  readonly _tag: "Refused";
1433
1306
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1434
1307
  readonly error: string;
1308
+ readonly value: unknown;
1435
1309
  } | {
1436
1310
  readonly _tag: "Reset";
1437
1311
  } | {
@@ -1451,6 +1325,9 @@ export declare const Form: {
1451
1325
  readonly _tag: "Toggled";
1452
1326
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1453
1327
  readonly choice?: string | undefined;
1328
+ } | {
1329
+ readonly _tag: "Validated";
1330
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1454
1331
  } | {
1455
1332
  readonly _tag: "ValidatedAll";
1456
1333
  }>;
@@ -1466,6 +1343,8 @@ export declare const Form: {
1466
1343
  * running does not stop it; the submit waits for the answer.
1467
1344
  */
1468
1345
  canSubmit: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
1346
+ /** Whether a submit was asked since the form started, was filled or was reset. */
1347
+ attempted: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
1469
1348
  /**
1470
1349
  * Whether the form is valid right now: a submit now would hand over the
1471
1350
  * value at once. Unlike `canSubmit`, a check running, or one a key has not
@@ -1519,6 +1398,10 @@ export declare const Form: {
1519
1398
  readonly _tag: "Checked";
1520
1399
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1521
1400
  readonly draft: string | boolean | readonly string[];
1401
+ readonly values?: unknown;
1402
+ readonly subject?: {
1403
+ readonly [x: string]: string;
1404
+ };
1522
1405
  readonly error: string | null;
1523
1406
  } | {
1524
1407
  readonly _tag: "Control";
@@ -1536,6 +1419,7 @@ export declare const Form: {
1536
1419
  readonly _tag: "Refused";
1537
1420
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1538
1421
  readonly error: string;
1422
+ readonly value: unknown;
1539
1423
  } | {
1540
1424
  readonly _tag: "Reset";
1541
1425
  } | {
@@ -1555,6 +1439,9 @@ export declare const Form: {
1555
1439
  readonly _tag: "Toggled";
1556
1440
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1557
1441
  readonly choice?: string | undefined;
1442
+ } | {
1443
+ readonly _tag: "Validated";
1444
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1558
1445
  } | {
1559
1446
  readonly _tag: "ValidatedAll";
1560
1447
  }, never, R>;
@@ -1585,6 +1472,10 @@ export declare const Form: {
1585
1472
  readonly _tag: "Checked";
1586
1473
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1587
1474
  readonly draft: string | boolean | readonly string[];
1475
+ readonly values?: unknown;
1476
+ readonly subject?: {
1477
+ readonly [x: string]: string;
1478
+ };
1588
1479
  readonly error: string | null;
1589
1480
  } | {
1590
1481
  readonly _tag: "Control";
@@ -1602,6 +1493,7 @@ export declare const Form: {
1602
1493
  readonly _tag: "Refused";
1603
1494
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1604
1495
  readonly error: string;
1496
+ readonly value: unknown;
1605
1497
  } | {
1606
1498
  readonly _tag: "Reset";
1607
1499
  } | {
@@ -1621,6 +1513,9 @@ export declare const Form: {
1621
1513
  readonly _tag: "Toggled";
1622
1514
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1623
1515
  readonly choice?: string | undefined;
1516
+ } | {
1517
+ readonly _tag: "Validated";
1518
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1624
1519
  } | {
1625
1520
  readonly _tag: "ValidatedAll";
1626
1521
  }, never, R>;
@@ -1684,5 +1579,5 @@ export declare const Form: {
1684
1579
  readonly Inputs: F['types']['Inputs'];
1685
1580
  }>;
1686
1581
  };
1687
- export type { BundleControl, BundleControlSpec, BundleData, Control, ControlChange, ControlKind, Draft, DraftKind, Follows, FormRow, NestedData, NestedForm, RelationData };
1688
- //# sourceMappingURL=index.d.mts.map
1582
+ export { type BundleControl, type BundleControlSpec, type BundleData, type Control, type ControlChange, type ControlKind, type Draft, type DraftKind, type Follows, type FormRow, Input, type NestedData, type NestedForm, type RelationData };
1583
+ //# sourceMappingURL=index.d.ts.map