foldkit-form 0.8.1 → 0.9.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,6 +325,9 @@ 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
333
  }, Submitted<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>, R, never, void, ControlResourcesOf<Inputs>, {
@@ -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,15 @@ 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
+ * The same controls by key, for a view that places each field itself:
487
+ * `form.controlsByKey.email.label`.
488
+ */
489
+ controlsByKey: { readonly [K in keyof Fields & string]: FormControl<K>; };
490
+ /**
491
+ * One key's state as a view shows it, with its draft as any `Draft`: its
492
+ * own validation, made `Invalid` by the marks on it (`FormModel.marks`).
493
+ * `model.fields.title` is the key's own validation alone. A nested key has
494
+ * rows and no draft.
729
495
  */
730
496
  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
497
  /**
@@ -754,6 +520,10 @@ declare const Core: {
754
520
  readonly _tag: "Checked";
755
521
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
756
522
  readonly draft: string | boolean | readonly string[];
523
+ readonly values?: unknown;
524
+ readonly subject?: {
525
+ readonly [x: string]: string;
526
+ };
757
527
  readonly error: string | null;
758
528
  } | {
759
529
  readonly _tag: "Control";
@@ -771,6 +541,7 @@ declare const Core: {
771
541
  readonly _tag: "Refused";
772
542
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
773
543
  readonly error: string;
544
+ readonly value: unknown;
774
545
  } | {
775
546
  readonly _tag: "Reset";
776
547
  } | {
@@ -790,6 +561,9 @@ declare const Core: {
790
561
  readonly _tag: "Toggled";
791
562
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
792
563
  readonly choice?: string | undefined;
564
+ } | {
565
+ readonly _tag: "Validated";
566
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
793
567
  } | {
794
568
  readonly _tag: "ValidatedAll";
795
569
  };
@@ -826,6 +600,10 @@ declare const Core: {
826
600
  readonly _tag: "Checked";
827
601
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
828
602
  readonly draft: string | boolean | readonly string[];
603
+ readonly values?: unknown;
604
+ readonly subject?: {
605
+ readonly [x: string]: string;
606
+ };
829
607
  readonly error: string | null;
830
608
  } | {
831
609
  readonly _tag: "Control";
@@ -843,6 +621,7 @@ declare const Core: {
843
621
  readonly _tag: "Refused";
844
622
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
845
623
  readonly error: string;
624
+ readonly value: unknown;
846
625
  } | {
847
626
  readonly _tag: "Reset";
848
627
  } | {
@@ -862,6 +641,9 @@ declare const Core: {
862
641
  readonly _tag: "Toggled";
863
642
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
864
643
  readonly choice?: string | undefined;
644
+ } | {
645
+ readonly _tag: "Validated";
646
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
865
647
  } | {
866
648
  readonly _tag: "ValidatedAll";
867
649
  }>;
@@ -877,6 +659,8 @@ declare const Core: {
877
659
  * running does not stop it; the submit waits for the answer.
878
660
  */
879
661
  canSubmit: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
662
+ /** Whether a submit was asked since the form started, was filled or was reset. */
663
+ attempted: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
880
664
  /**
881
665
  * Whether the form is valid right now: a submit now would hand over the
882
666
  * value at once. Unlike `canSubmit`, a check running, or one a key has not
@@ -930,6 +714,10 @@ declare const Core: {
930
714
  readonly _tag: "Checked";
931
715
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
932
716
  readonly draft: string | boolean | readonly string[];
717
+ readonly values?: unknown;
718
+ readonly subject?: {
719
+ readonly [x: string]: string;
720
+ };
933
721
  readonly error: string | null;
934
722
  } | {
935
723
  readonly _tag: "Control";
@@ -947,6 +735,7 @@ declare const Core: {
947
735
  readonly _tag: "Refused";
948
736
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
949
737
  readonly error: string;
738
+ readonly value: unknown;
950
739
  } | {
951
740
  readonly _tag: "Reset";
952
741
  } | {
@@ -966,6 +755,9 @@ declare const Core: {
966
755
  readonly _tag: "Toggled";
967
756
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
968
757
  readonly choice?: string | undefined;
758
+ } | {
759
+ readonly _tag: "Validated";
760
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
969
761
  } | {
970
762
  readonly _tag: "ValidatedAll";
971
763
  }, never, R>;
@@ -996,6 +788,10 @@ declare const Core: {
996
788
  readonly _tag: "Checked";
997
789
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
998
790
  readonly draft: string | boolean | readonly string[];
791
+ readonly values?: unknown;
792
+ readonly subject?: {
793
+ readonly [x: string]: string;
794
+ };
999
795
  readonly error: string | null;
1000
796
  } | {
1001
797
  readonly _tag: "Control";
@@ -1013,6 +809,7 @@ declare const Core: {
1013
809
  readonly _tag: "Refused";
1014
810
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1015
811
  readonly error: string;
812
+ readonly value: unknown;
1016
813
  } | {
1017
814
  readonly _tag: "Reset";
1018
815
  } | {
@@ -1032,6 +829,9 @@ declare const Core: {
1032
829
  readonly _tag: "Toggled";
1033
830
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1034
831
  readonly choice?: string | undefined;
832
+ } | {
833
+ readonly _tag: "Validated";
834
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1035
835
  } | {
1036
836
  readonly _tag: "ValidatedAll";
1037
837
  }, never, R>;
@@ -1084,7 +884,7 @@ export declare const Form: {
1084
884
  * a login): `Entity.input` over an Entity defined from the same schema, so
1085
885
  * every key maps itself. `Form.make('Waitlist', Form.input(JoinWaitlist))`.
1086
886
  */
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; }>;
887
+ input: <Fields extends Schema.Struct.Fields>(schema: Schema.Struct<Fields>) => EntityInput<Entity<'FormInput', Fields>, Fields, InputMembers<Entity<'FormInput', Fields>, Fields, {}>>;
1088
888
  /**
1089
889
  * A form for one operation's input. A key mapped with `Relation.nested` holds
1090
890
  * rows of a form of its own, built here from the nested input; every other key
@@ -1146,6 +946,10 @@ export declare const Form: {
1146
946
  readonly _tag: "Checked";
1147
947
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1148
948
  readonly draft: string | boolean | readonly string[];
949
+ readonly values?: unknown;
950
+ readonly subject?: {
951
+ readonly [x: string]: string;
952
+ };
1149
953
  readonly error: string | null;
1150
954
  } | {
1151
955
  readonly _tag: "Control";
@@ -1163,6 +967,7 @@ export declare const Form: {
1163
967
  readonly _tag: "Refused";
1164
968
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1165
969
  readonly error: string;
970
+ readonly value: unknown;
1166
971
  } | {
1167
972
  readonly _tag: "Reset";
1168
973
  } | {
@@ -1182,6 +987,9 @@ export declare const Form: {
1182
987
  readonly _tag: "Toggled";
1183
988
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1184
989
  readonly choice?: string | undefined;
990
+ } | {
991
+ readonly _tag: "Validated";
992
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1185
993
  } | {
1186
994
  readonly _tag: "ValidatedAll";
1187
995
  }, Submitted<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>, R, never, void, ControlResourcesOf<Inputs>, {
@@ -1194,10 +1002,21 @@ export declare const Form: {
1194
1002
  key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1195
1003
  value: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
1196
1004
  };
1197
- /** Validates the key as it stands, so a required key left empty says so. */
1005
+ /**
1006
+ * The person left the key. An edit has already validated it, and a key
1007
+ * never edited is not judged before a submit, so tabbing through a field
1008
+ * says nothing about it: the form changes nothing.
1009
+ */
1198
1010
  Blurred: {
1199
1011
  key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1200
1012
  };
1013
+ /**
1014
+ * Validates the key as it stands, edited or not: for a program showing a
1015
+ * stored value's failure after a `fill`, which validates nothing.
1016
+ */
1017
+ Validated: {
1018
+ key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1019
+ };
1201
1020
  /**
1202
1021
  * Validates every key not validated yet, in every row too, as a submit
1203
1022
  * would, and submits nothing: for a page that submits several forms at once.
@@ -1206,21 +1025,31 @@ export declare const Form: {
1206
1025
  ValidatedAll: {};
1207
1026
  Submitted: {};
1208
1027
  Reset: {};
1209
- /** The answer of a check for the draft it was asked about; one for an older draft is dropped. */
1028
+ /**
1029
+ * The answer of a check for the draft it was asked about; one for an older
1030
+ * draft is dropped. `form.Check` also says the `values` and `subject` it
1031
+ * read, and an answer about ones the form no longer holds is asked again.
1032
+ * One made without them (a test's) answers the form as it is.
1033
+ */
1210
1034
  Checked: {
1211
1035
  key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1212
1036
  draft: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
1037
+ values: Schema.optionalKey<Schema.Unknown>;
1038
+ subject: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
1213
1039
  error: Schema.NullOr<Schema.String>;
1214
1040
  };
1215
1041
  /**
1216
1042
  * 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.
1043
+ * server knows. `value` is the key's value in what was refused, as
1044
+ * `Submitted` handed it out. While the key still holds it, the key reads
1045
+ * invalid with that reason (a mark, see `FormModel.marks`) until the next
1046
+ * edit of any key; a key changed since is not what was refused, and the
1047
+ * Message is dropped.
1220
1048
  */
1221
1049
  Refused: {
1222
1050
  key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
1223
1051
  error: Schema.String;
1052
+ value: Schema.Unknown;
1224
1053
  };
1225
1054
  /**
1226
1055
  * What the form is editing, for the checks that need to know: a post's own
@@ -1297,6 +1126,10 @@ export declare const Form: {
1297
1126
  readonly _tag: "Checked";
1298
1127
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1299
1128
  readonly draft: string | boolean | readonly string[];
1129
+ readonly values?: unknown;
1130
+ readonly subject?: {
1131
+ readonly [x: string]: string;
1132
+ };
1300
1133
  readonly error: string | null;
1301
1134
  }, never, R>>;
1302
1135
  /** The reading the form was made from, for `Entity.selectFor` and `Entity.valuesFor`. */
@@ -1312,9 +1145,15 @@ export declare const Form: {
1312
1145
  /** The keys in the input's order, each with its control, label, and member. */
1313
1146
  controls: FormControl<keyof Fields & string>[];
1314
1147
  /**
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.
1148
+ * The same controls by key, for a view that places each field itself:
1149
+ * `form.controlsByKey.email.label`.
1150
+ */
1151
+ controlsByKey: { readonly [K in keyof Fields & string]: FormControl<K>; };
1152
+ /**
1153
+ * One key's state as a view shows it, with its draft as any `Draft`: its
1154
+ * own validation, made `Invalid` by the marks on it (`FormModel.marks`).
1155
+ * `model.fields.title` is the key's own validation alone. A nested key has
1156
+ * rows and no draft.
1318
1157
  */
1319
1158
  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
1159
  /**
@@ -1343,6 +1182,10 @@ export declare const Form: {
1343
1182
  readonly _tag: "Checked";
1344
1183
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1345
1184
  readonly draft: string | boolean | readonly string[];
1185
+ readonly values?: unknown;
1186
+ readonly subject?: {
1187
+ readonly [x: string]: string;
1188
+ };
1346
1189
  readonly error: string | null;
1347
1190
  } | {
1348
1191
  readonly _tag: "Control";
@@ -1360,6 +1203,7 @@ export declare const Form: {
1360
1203
  readonly _tag: "Refused";
1361
1204
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1362
1205
  readonly error: string;
1206
+ readonly value: unknown;
1363
1207
  } | {
1364
1208
  readonly _tag: "Reset";
1365
1209
  } | {
@@ -1379,6 +1223,9 @@ export declare const Form: {
1379
1223
  readonly _tag: "Toggled";
1380
1224
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1381
1225
  readonly choice?: string | undefined;
1226
+ } | {
1227
+ readonly _tag: "Validated";
1228
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1382
1229
  } | {
1383
1230
  readonly _tag: "ValidatedAll";
1384
1231
  };
@@ -1415,6 +1262,10 @@ export declare const Form: {
1415
1262
  readonly _tag: "Checked";
1416
1263
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1417
1264
  readonly draft: string | boolean | readonly string[];
1265
+ readonly values?: unknown;
1266
+ readonly subject?: {
1267
+ readonly [x: string]: string;
1268
+ };
1418
1269
  readonly error: string | null;
1419
1270
  } | {
1420
1271
  readonly _tag: "Control";
@@ -1432,6 +1283,7 @@ export declare const Form: {
1432
1283
  readonly _tag: "Refused";
1433
1284
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1434
1285
  readonly error: string;
1286
+ readonly value: unknown;
1435
1287
  } | {
1436
1288
  readonly _tag: "Reset";
1437
1289
  } | {
@@ -1451,6 +1303,9 @@ export declare const Form: {
1451
1303
  readonly _tag: "Toggled";
1452
1304
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1453
1305
  readonly choice?: string | undefined;
1306
+ } | {
1307
+ readonly _tag: "Validated";
1308
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1454
1309
  } | {
1455
1310
  readonly _tag: "ValidatedAll";
1456
1311
  }>;
@@ -1466,6 +1321,8 @@ export declare const Form: {
1466
1321
  * running does not stop it; the submit waits for the answer.
1467
1322
  */
1468
1323
  canSubmit: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
1324
+ /** Whether a submit was asked since the form started, was filled or was reset. */
1325
+ attempted: (model: FormModel<Fields, Members, ControlsOf<Inputs>>) => boolean;
1469
1326
  /**
1470
1327
  * Whether the form is valid right now: a submit now would hand over the
1471
1328
  * value at once. Unlike `canSubmit`, a check running, or one a key has not
@@ -1519,6 +1376,10 @@ export declare const Form: {
1519
1376
  readonly _tag: "Checked";
1520
1377
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1521
1378
  readonly draft: string | boolean | readonly string[];
1379
+ readonly values?: unknown;
1380
+ readonly subject?: {
1381
+ readonly [x: string]: string;
1382
+ };
1522
1383
  readonly error: string | null;
1523
1384
  } | {
1524
1385
  readonly _tag: "Control";
@@ -1536,6 +1397,7 @@ export declare const Form: {
1536
1397
  readonly _tag: "Refused";
1537
1398
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1538
1399
  readonly error: string;
1400
+ readonly value: unknown;
1539
1401
  } | {
1540
1402
  readonly _tag: "Reset";
1541
1403
  } | {
@@ -1555,6 +1417,9 @@ export declare const Form: {
1555
1417
  readonly _tag: "Toggled";
1556
1418
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1557
1419
  readonly choice?: string | undefined;
1420
+ } | {
1421
+ readonly _tag: "Validated";
1422
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1558
1423
  } | {
1559
1424
  readonly _tag: "ValidatedAll";
1560
1425
  }, never, R>;
@@ -1585,6 +1450,10 @@ export declare const Form: {
1585
1450
  readonly _tag: "Checked";
1586
1451
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1587
1452
  readonly draft: string | boolean | readonly string[];
1453
+ readonly values?: unknown;
1454
+ readonly subject?: {
1455
+ readonly [x: string]: string;
1456
+ };
1588
1457
  readonly error: string | null;
1589
1458
  } | {
1590
1459
  readonly _tag: "Control";
@@ -1602,6 +1471,7 @@ export declare const Form: {
1602
1471
  readonly _tag: "Refused";
1603
1472
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1604
1473
  readonly error: string;
1474
+ readonly value: unknown;
1605
1475
  } | {
1606
1476
  readonly _tag: "Reset";
1607
1477
  } | {
@@ -1621,6 +1491,9 @@ export declare const Form: {
1621
1491
  readonly _tag: "Toggled";
1622
1492
  readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1623
1493
  readonly choice?: string | undefined;
1494
+ } | {
1495
+ readonly _tag: "Validated";
1496
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
1624
1497
  } | {
1625
1498
  readonly _tag: "ValidatedAll";
1626
1499
  }, never, R>;
@@ -1684,5 +1557,5 @@ export declare const Form: {
1684
1557
  readonly Inputs: F['types']['Inputs'];
1685
1558
  }>;
1686
1559
  };
1687
- export type { BundleControl, BundleControlSpec, BundleData, Control, ControlChange, ControlKind, Draft, DraftKind, Follows, FormRow, NestedData, NestedForm, RelationData };
1688
- //# sourceMappingURL=index.d.mts.map
1560
+ 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 };
1561
+ //# sourceMappingURL=index.d.ts.map