ovr 7.0.0-next.2 → 7.0.0-next.21

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.
Files changed (52) hide show
  1. package/CHANGELOG.md +1157 -0
  2. package/dist/auth/client-source.d.ts +2 -2
  3. package/dist/auth/client-source.d.ts.map +1 -1
  4. package/dist/auth/client-source.js +2 -2
  5. package/dist/auth/client.d.ts.map +1 -1
  6. package/dist/auth/client.js +7 -4
  7. package/dist/auth/configure.d.ts +21 -8
  8. package/dist/auth/configure.d.ts.map +1 -1
  9. package/dist/auth/configure.js +172 -6
  10. package/dist/auth/index.d.ts +48 -0
  11. package/dist/auth/index.d.ts.map +1 -1
  12. package/dist/auth/index.js +19 -0
  13. package/dist/auth/passkey.d.ts +14 -2
  14. package/dist/auth/passkey.d.ts.map +1 -1
  15. package/dist/auth/passkey.js +18 -5
  16. package/dist/auth/state.d.ts +6 -0
  17. package/dist/auth/state.d.ts.map +1 -1
  18. package/dist/auth/state.js +28 -5
  19. package/dist/auth/storage.d.ts +38 -0
  20. package/dist/auth/storage.d.ts.map +1 -1
  21. package/dist/auth/storage.js +60 -3
  22. package/dist/context/index.d.ts +4 -4
  23. package/dist/context/index.d.ts.map +1 -1
  24. package/dist/context/index.js +6 -3
  25. package/dist/form/index.d.ts +239 -31
  26. package/dist/form/index.d.ts.map +1 -1
  27. package/dist/form/index.js +657 -66
  28. package/dist/markdown/index.d.ts +6 -1
  29. package/dist/markdown/index.d.ts.map +1 -1
  30. package/dist/markdown/index.js +180 -9
  31. package/dist/mcp/index.d.ts.map +1 -1
  32. package/dist/mcp/index.js +154 -57
  33. package/dist/schema/index.d.ts +88 -19
  34. package/dist/schema/index.d.ts.map +1 -1
  35. package/dist/schema/index.js +32 -11
  36. package/dist/util/index.d.ts +12 -0
  37. package/dist/util/index.d.ts.map +1 -1
  38. package/dist/util/index.js +19 -0
  39. package/package.json +2 -1
  40. package/src/auth/client-source.ts +2 -2
  41. package/src/auth/client.ts +7 -4
  42. package/src/auth/configure.ts +189 -13
  43. package/src/auth/index.ts +44 -0
  44. package/src/auth/passkey.ts +25 -7
  45. package/src/auth/state.ts +32 -7
  46. package/src/auth/storage.ts +66 -3
  47. package/src/context/index.ts +14 -6
  48. package/src/form/index.ts +1174 -195
  49. package/src/markdown/index.ts +203 -12
  50. package/src/mcp/index.ts +205 -72
  51. package/src/schema/index.ts +195 -52
  52. package/src/util/index.ts +23 -0
package/src/form/index.ts CHANGED
@@ -9,11 +9,14 @@ import {
9
9
  normalizers,
10
10
  own,
11
11
  } from "../schema/index.js";
12
- import { Checksum, Codec, Size } from "../util/index.js";
12
+ import { Checksum, Codec, Prose, Size, type Util } from "../util/index.js";
13
13
 
14
14
  /** Internal protocol for a GET route, to make the form its fields render. */
15
15
  export const query = Symbol("query");
16
16
 
17
+ /** Internal protocol for Auth, the message a `taken()` field shows */
18
+ export const taken = Symbol("taken");
19
+
17
20
  /** A field's components and render, which a route's form reads */
18
21
  const component = Symbol("component");
19
22
  const render = Symbol("render");
@@ -47,7 +50,7 @@ export class Form<Shape extends Field.Shape = Field.Shape> {
47
50
  static readonly #maxValueChars = 512;
48
51
 
49
52
  /** Schema used to validate persisted form values, see `#value`. */
50
- static #valueSchema?: Schema<Field.Value>;
53
+ static #valueSchema?: Schema<Field.Value.Cell>;
51
54
 
52
55
  /** Form id. */
53
56
  readonly #id: string;
@@ -64,6 +67,9 @@ export class Form<Shape extends Field.Shape = Field.Shape> {
64
67
  /** Field names in definition order. */
65
68
  readonly names: ShapeUtil.Name<Shape>[];
66
69
 
70
+ /** Names of the lists, whose cells are named by them. */
71
+ readonly #lists: ShapeUtil.Name<Shape>[];
72
+
67
73
  /** Maximum expected multipart parts derived from field cardinality. */
68
74
  readonly parts: number;
69
75
 
@@ -75,6 +81,7 @@ export class Form<Shape extends Field.Shape = Field.Shape> {
75
81
  constructor(shape: Shape) {
76
82
  this.shape = shape;
77
83
  this.names = Object.keys(this.shape) as ShapeUtil.Name<Shape>[];
84
+ this.#lists = this.names.filter((name) => this.shape[name]!.item);
78
85
  this.#id = Checksum.djb2(this.names.join());
79
86
  this.parts = Object.values(this.shape).reduce(
80
87
  (sum, field) => sum + field.parts,
@@ -106,10 +113,55 @@ export class Form<Shape extends Field.Shape = Field.Shape> {
106
113
 
107
114
  /**
108
115
  * @param name Form data name
109
- * @returns The field, own fields only, so a name such as "constructor" has none
116
+ * @returns The field, own fields only, so a name such as "constructor" has
117
+ * none. A list's cell, such as `steps.0`, is its list's.
110
118
  */
111
119
  #field(name: string) {
112
- return Object.hasOwn(this.shape, name) ? this.shape[name] : undefined;
120
+ if (Object.hasOwn(this.shape, name)) return this.shape[name];
121
+
122
+ for (const list of this.#lists) {
123
+ const field = this.shape[list]!;
124
+ if (FieldSchema.place(field.item!, list, name) !== undefined)
125
+ return field;
126
+ }
127
+ }
128
+
129
+ /**
130
+ * @param item What each item of a list is
131
+ * @param value Candidate items
132
+ * @returns The items a list can render, without what a cell cannot
133
+ */
134
+ static #items(item: Field.Item, value: unknown, url = false) {
135
+ if (!Array.isArray(value)) return;
136
+
137
+ const cell = (field: Field.Cell, value: unknown) => {
138
+ if (
139
+ field.type === "file" ||
140
+ field.type === "password" ||
141
+ // a row's hidden value, such as its ID, is the server's to give:
142
+ // state in a URL, which anyone can write, never sets it
143
+ (url && field.type === "hidden") ||
144
+ value == null
145
+ )
146
+ return;
147
+
148
+ const result = Form.#value().parse(value);
149
+ if (!result.issues) return result.data;
150
+ };
151
+
152
+ return value.map((row: unknown) => {
153
+ // a place is kept, so the items after it stay where they were
154
+ if (field(item)) return cell(item, row) ?? "";
155
+
156
+ const cells: Record<string, Field.Value.Cell> = {};
157
+ if (row && typeof row === "object") {
158
+ for (const key of Object.keys(item)) {
159
+ const value = cell(item[key]!, (row as Record<string, unknown>)[key]);
160
+ if (value !== undefined) own(cells, key, value);
161
+ }
162
+ }
163
+ return cells;
164
+ });
113
165
  }
114
166
 
115
167
  /**
@@ -146,12 +198,34 @@ export class Form<Shape extends Field.Shape = Field.Shape> {
146
198
  (!persist || FieldSchema.persisted(field)) &&
147
199
  value != null
148
200
  ) {
201
+ if (field.item) {
202
+ // a cleared list is recorded empty, and no list has a size of
203
+ // its own: the state's limit holds them all
204
+ const items =
205
+ value === ""
206
+ ? []
207
+ : Form.#items(
208
+ field.item,
209
+ // no more rows from a URL than the list takes
210
+ limit && Array.isArray(value)
211
+ ? value.slice(0, FieldSchema.most(field))
212
+ : value,
213
+ limit,
214
+ );
215
+ if (items) own(sanitized, name, items);
216
+ continue;
217
+ }
218
+
149
219
  const result = Form.#value().parse(value);
150
220
 
151
221
  if (
152
222
  !result.issues &&
153
223
  (!limit ||
154
- JSON.stringify(result.data).length <= Form.#maxValueChars)
224
+ // each of many values, such as a line, has the limit:
225
+ // the state's own holds them all
226
+ (Array.isArray(result.data) ? result.data : [result.data]).every(
227
+ (one) => JSON.stringify(one).length <= Form.#maxValueChars,
228
+ ))
155
229
  ) {
156
230
  own(sanitized, name, result.data);
157
231
  }
@@ -162,6 +236,44 @@ export class Form<Shape extends Field.Shape = Field.Shape> {
162
236
  }
163
237
  }
164
238
 
239
+ /**
240
+ * An issue by place means nothing without the rows it was found in, and a
241
+ * list's rows are only shown again when it persists and they fit the state.
242
+ *
243
+ * @param state Restored state
244
+ * @returns The state, where an issue of a cell whose list's rows were not
245
+ * restored is the list's own, and says which row and field it is about
246
+ */
247
+ #unplaced(state?: Field.State<Shape>): Field.State<Shape> | undefined {
248
+ if (!state?.issues || !this.#lists.length) return state;
249
+
250
+ return {
251
+ ...state,
252
+ issues: state.issues.map((issue) => {
253
+ const [name, place, key] = issue.path;
254
+ if (
255
+ typeof place !== "number" ||
256
+ !this.#lists.includes(name as ShapeUtil.Name<Shape>) ||
257
+ state.values?.[name as ShapeUtil.Name<Shape>] !== undefined
258
+ )
259
+ return issue;
260
+
261
+ // the field as people know it, by its column's heading
262
+ const { item } = this.shape[name as ShapeUtil.Name<Shape>]!;
263
+ const cell =
264
+ typeof key === "string" && !field(item) && Object.hasOwn(item!, key)
265
+ ? `, ${FieldSchema.named(item![key]!, key)}`
266
+ : "";
267
+
268
+ return new Schema.Issue(
269
+ issue.expected,
270
+ [name!],
271
+ `Row ${place + 1}${cell}: ${issue.message}`,
272
+ );
273
+ }) as unknown as Schema.Issue.List,
274
+ };
275
+ }
276
+
165
277
  /**
166
278
  * Decode form state, over the initial values.
167
279
  *
@@ -172,7 +284,7 @@ export class Form<Shape extends Field.Shape = Field.Shape> {
172
284
  stateInput?: URL,
173
285
  initial?: Field.Value.Initial<Shape>,
174
286
  ): Field.State<Shape> | undefined {
175
- const state = this.#restore(stateInput);
287
+ const state = this.#unplaced(this.#restore(stateInput));
176
288
  // initial values come from the server, not the URL, so no size limit
177
289
  const values = this.#sanitize(initial, false, false);
178
290
 
@@ -192,7 +304,8 @@ export class Form<Shape extends Field.Shape = Field.Shape> {
192
304
  const values = this.#sanitize(
193
305
  (this.#query ? this.names : []).reduce<Record<string, unknown>>(
194
306
  (data, name) => {
195
- if (searchParams.has(name)) {
307
+ // a list's cells are named by it, so its own name is not there
308
+ if (searchParams.has(name) || this.shape[name]!.item) {
196
309
  const value = FieldSchema.read(
197
310
  this.shape[name]!,
198
311
  searchParams,
@@ -234,7 +347,14 @@ export class Form<Shape extends Field.Shape = Field.Shape> {
234
347
  ).optional(),
235
348
  values: Schema.object(
236
349
  this.names.reduce<Schema.Object.Shape>((shape, name) => {
237
- own(shape, name, Form.#value().optional());
350
+ own(
351
+ shape,
352
+ name,
353
+ // a list's items are checked as they are sanitized
354
+ this.shape[name]!.item
355
+ ? Schema.unknown()
356
+ : Form.#value().optional(),
357
+ );
238
358
 
239
359
  return shape;
240
360
  }, {}),
@@ -303,13 +423,18 @@ export class Form<Shape extends Field.Shape = Field.Shape> {
303
423
  *
304
424
  * @param source FormData, URLSearchParams, or Multipart to parse
305
425
  * @param path Internal path reference
426
+ * @param sent The fields an agent's tool call gave, which are all it
427
+ * updates. Without it the source is a form's, which sends every field it
428
+ * has.
306
429
  * @returns Parsed result
307
430
  */
308
431
  parse = async (
309
432
  source: FormData | URLSearchParams | Multipart,
310
433
  path: Schema.Issue.Path = [],
434
+ sent?: ReadonlySet<string>,
311
435
  ): Promise<Field.Parse.Result<Shape>> => {
312
436
  const data: Record<string, unknown> = {};
437
+ const updates: Record<string, unknown> = {};
313
438
  const issues: Schema.Issue[] = [];
314
439
  const values: Record<string, unknown> = {};
315
440
  let form: FormData | URLSearchParams;
@@ -383,6 +508,11 @@ export class Form<Shape extends Field.Shape = Field.Shape> {
383
508
  own(data, name, result.data);
384
509
  }
385
510
 
511
+ // what the request sets: a field sent empty is cleared, and one
512
+ // not sent keeps its value
513
+ if (sent ? sent.has(name) : FieldSchema.sent(field, form, name))
514
+ own(updates, name, result.data ?? null);
515
+
386
516
  // a cleared field is recorded empty, so it overrides initial values
387
517
  if (FieldSchema.persisted(field)) own(values, name, value ?? "");
388
518
  }
@@ -401,6 +531,7 @@ export class Form<Shape extends Field.Shape = Field.Shape> {
401
531
 
402
532
  return {
403
533
  data: data as Field.Parse.Data<Shape>,
534
+ updates: updates as Field.Parse.Updates<Shape>,
404
535
  stream,
405
536
  invalid: (messages: Field.Parse.Messages<Shape>) =>
406
537
  this.#invalid(
@@ -493,6 +624,9 @@ const required = "Required field";
493
624
  /** Default message for a choice that is not one of the options */
494
625
  const choose = "Select an option";
495
626
 
627
+ /** Default message for a number field sent a value that is not a number */
628
+ const numeric = "Enter a number";
629
+
496
630
  /**
497
631
  * @param value Form data entry
498
632
  * @returns `true` for a file a person chose, a browser sends an empty one otherwise
@@ -519,6 +653,7 @@ const readMany = (data: FormData | URLSearchParams, name: string) => {
519
653
  * @template Type Input type
520
654
  * @template Values Persisted field value type
521
655
  * @template Stream If the field should be streamed as a part
656
+ * @template Item What each item of a list is
522
657
  */
523
658
  class FieldSchema<
524
659
  Output = unknown,
@@ -526,6 +661,7 @@ class FieldSchema<
526
661
  Type extends Field.Type = Field.Type,
527
662
  Values extends Field.Options | undefined = undefined,
528
663
  Stream extends boolean | undefined = undefined,
664
+ Item extends Field.Item | undefined = undefined,
529
665
  > extends Schema<Output> {
530
666
  /** Read the value from form data */
531
667
  readonly #read: Field.Read;
@@ -541,6 +677,9 @@ class FieldSchema<
541
677
  /** Choices of a select, radio, or checkbox group */
542
678
  readonly options: Values;
543
679
 
680
+ /** What each item of a list is: a field, or fields by name */
681
+ readonly item: Item;
682
+
544
683
  /** Maximum expected multipart part count for this field name. */
545
684
  readonly parts: number;
546
685
 
@@ -580,9 +719,18 @@ class FieldSchema<
580
719
  this.#config = config;
581
720
  this.tag = (config.tag ?? "input") as Tag;
582
721
  this.options = config.options as Values;
722
+ this.item = config.item as Item;
583
723
  this.#read = read;
584
724
  this.type = config.props?.type as Type;
585
- this.parts = parts;
725
+ // a list takes as many rows as its `max()`, or the most any list
726
+ // does, so a request cannot send rows without end
727
+ const { item } = this;
728
+ this.parts = item
729
+ ? Math.min(this.#most(), FieldSchema.#rows) *
730
+ (item instanceof FieldSchema
731
+ ? item.parts
732
+ : Object.values(item).reduce((sum, cell) => sum + cell.parts, 0))
733
+ : parts;
586
734
  this.streaming = stream;
587
735
  this.#persist = persist;
588
736
  }
@@ -599,14 +747,14 @@ class FieldSchema<
599
747
  Boolean(this.parse(this.#read(new URLSearchParams(), "")).issues));
600
748
  }
601
749
 
602
- /** How each picker writes its value */
750
+ /** How each picker writes its value, a sentence so it reads alone too */
603
751
  static readonly #formats: Record<string, string | undefined> = {
604
- date: "Date as YYYY-MM-DD",
605
- "datetime-local": "Date and time as YYYY-MM-DDTHH:mm",
606
- month: "Month as YYYY-MM",
607
- week: "Week as YYYY-Www, such as 2026-W46",
608
- time: "Time as HH:mm",
609
- color: "Color as #rrggbb",
752
+ date: "Date as YYYY-MM-DD.",
753
+ "datetime-local": "Date and time as YYYY-MM-DDTHH:mm.",
754
+ month: "Month as YYYY-MM.",
755
+ week: "Week as YYYY-Www, such as 2026-W46.",
756
+ time: "Time as HH:mm.",
757
+ color: "Color as #rrggbb.",
610
758
  };
611
759
 
612
760
  /**
@@ -620,9 +768,16 @@ class FieldSchema<
620
768
  const { description } = this;
621
769
  // what a browser's picker sends, which a string alone does not say
622
770
  const format = FieldSchema.#formats[this.type as string];
623
- const described = [description?.replace(/\.$/, ""), format]
624
- .filter(Boolean)
625
- .join(". ");
771
+ // what people call a choice, where it is not its value
772
+ const named = Object.entries(this.#config.labels ?? {})
773
+ .filter(([value, label]) => label !== value)
774
+ .map(([value, label]) => `${value} (${label})`)
775
+ .join(", ");
776
+ const described = Prose.join(
777
+ description,
778
+ format,
779
+ named && `Choices: ${named}.`,
780
+ );
626
781
 
627
782
  return {
628
783
  ...(label && { title: label }),
@@ -650,12 +805,112 @@ class FieldSchema<
650
805
  return field.#read(data, name);
651
806
  }
652
807
 
808
+ /**
809
+ * @param field Field
810
+ * @param data A form's data
811
+ * @param name The field's name
812
+ * @returns `true` when the form sent the field. A browser sends nothing
813
+ * for a box that is not ticked or a choice not made, so those are always
814
+ * sent: empty is their value.
815
+ */
816
+ static sent(
817
+ field: Field.Any,
818
+ data: FormData | URLSearchParams,
819
+ name: string,
820
+ ) {
821
+ if (
822
+ field.type === "checkbox" ||
823
+ field.type === "radio" ||
824
+ (field.tag === "select" && field.#config.props?.multiple)
825
+ )
826
+ return true;
827
+
828
+ const { item } = field;
829
+ if (!item) return data.has(name);
830
+
831
+ // a list's cells are named by it
832
+ for (const key of data.keys())
833
+ if (FieldSchema.place(item, name, key) !== undefined) return true;
834
+ return false;
835
+ }
836
+
837
+ /**
838
+ * @param item What each item of the list is
839
+ * @param list The list's name
840
+ * @param name Form data name
841
+ * @returns The place of the item the name is a cell of, such as 2 for
842
+ * `steps.2` or `ingredients.2.amount`, `undefined` for any other name
843
+ */
844
+ static place(item: Field.Item, list: string, name: string) {
845
+ if (!name.startsWith(`${list}.`)) return;
846
+
847
+ const [, place, key] =
848
+ /^(0|[1-9]\d{0,8})(?:\.(.+))?$/s.exec(name.slice(list.length + 1)) ?? [];
849
+
850
+ if (
851
+ place === undefined ||
852
+ (item instanceof FieldSchema
853
+ ? key !== undefined
854
+ : key === undefined || !Object.hasOwn(item, key))
855
+ )
856
+ return;
857
+
858
+ return Number(place);
859
+ }
860
+
861
+ /**
862
+ * @param item What each item of the list is
863
+ * @returns How the list reads its items, in the order of their places. An
864
+ * item left empty is left out, so a person clears a row to remove it.
865
+ */
866
+ static items(item: Field.Item): Field.Read {
867
+ // a hidden cell, such as a row's ID, is sent with an empty row too
868
+ const filled = (cell: Field.Cell, value: Field.Input) =>
869
+ value !== undefined && value !== false && cell.type !== "hidden";
870
+
871
+ return (all, name) => {
872
+ // each row's own entries, found in one pass: reading a cell from
873
+ // all of them would cost the whole form again for every cell
874
+ const rows = new Map<number, FormData>();
875
+ for (const [key, value] of all) {
876
+ const place = FieldSchema.place(item, name, key);
877
+ if (place === undefined) continue;
878
+
879
+ let row = rows.get(place);
880
+ if (!row) rows.set(place, (row = new FormData()));
881
+ row.append(key, value);
882
+ }
883
+
884
+ const items: Field.Input.Cell[] | Record<string, Field.Input.Cell>[] = [];
885
+ for (const [place, data] of [...rows].sort(([a], [b]) => a - b)) {
886
+ const at = `${name}.${place}`;
887
+
888
+ if (item instanceof FieldSchema) {
889
+ const value = item.#read(data, at) as Field.Input.Cell;
890
+ if (filled(item, value)) (items as Field.Input.Cell[]).push(value);
891
+ continue;
892
+ }
893
+
894
+ const row: Record<string, Field.Input.Cell> = {};
895
+ let any = false;
896
+ for (const [key, cell] of Object.entries(item)) {
897
+ const value = cell.#read(data, `${at}.${key}`) as Field.Input.Cell;
898
+ if (filled(cell, value)) any = true;
899
+ own(row, key, value);
900
+ }
901
+ if (any) (items as Record<string, Field.Input.Cell>[]).push(row);
902
+ }
903
+
904
+ return items.length ? items : undefined;
905
+ };
906
+ }
907
+
653
908
  /**
654
909
  * Stream this field as a multipart request `Part`.
655
910
  *
656
911
  * @returns Part field
657
912
  */
658
- stream(): Field.Instance<Output, Tag, Type, Values, true> {
913
+ stream(): Field.Instance<Output, Tag, Type, Values, true, Item> {
659
914
  return this.#copy({ stream: true });
660
915
  }
661
916
 
@@ -671,10 +926,67 @@ class FieldSchema<
671
926
  * @param text Label
672
927
  * @returns Field with the label
673
928
  */
674
- label(text: string): Field.Instance<Output, Tag, Type, Values, Stream> {
929
+ label(text: string): Field.Instance<Output, Tag, Type, Values, Stream, Item> {
675
930
  return this.#with({ label: text });
676
931
  }
677
932
 
933
+ /**
934
+ * What people read under the control, in place of the field's
935
+ * description. Use it when what `describe()` says is written for an agent
936
+ * to be complete, and a person needs fewer words. Agents still read the
937
+ * description. An empty hint shows people nothing.
938
+ *
939
+ * ```ts
940
+ * Field.number()
941
+ * .describe("Weight in grams for cups and spoons. Empty for counts and liquids.")
942
+ * .hint("For cups and spoons");
943
+ * ```
944
+ *
945
+ * @param text Hint
946
+ * @returns Field with the hint
947
+ */
948
+ hint(text: string): Field.Instance<Output, Tag, Type, Values, Stream, Item> {
949
+ return this.#with({ hint: text });
950
+ }
951
+
952
+ /**
953
+ * @returns What people read under the control: the field's hint, or its
954
+ * description
955
+ */
956
+ #shown() {
957
+ return this.#config.hint ?? this.description;
958
+ }
959
+
960
+ /**
961
+ * What to say when a user already has the value, for a value no two users
962
+ * share and anyone may see, such as a username. Registration checks it
963
+ * before the passkey prompt and shows `message` on the field. Leave it off
964
+ * a private value, such as an email, so a conflict does not reveal who has
965
+ * an account. The unique constraint itself is the table's, in a migration.
966
+ *
967
+ * ```ts
968
+ * Field.text().taken("Someone already has this username");
969
+ * ```
970
+ *
971
+ * @template U Input type, one people read: not a password or file
972
+ * @param message What to show when a user already has the value
973
+ * @returns Field with the message
974
+ */
975
+ taken<
976
+ U extends (Tag extends "input" ? Exclude<Type, "password" | "file"> : Type),
977
+ >(
978
+ this: Field.Instance<Output, Tag, U, Values, Stream, Item>,
979
+ message: string,
980
+ ): Field.Instance<Output, Tag, U, Values, Stream, Item>;
981
+ taken(message: string) {
982
+ return this.#with({ taken: message });
983
+ }
984
+
985
+ /** @internal The message `taken()` set */
986
+ get [taken]() {
987
+ return this.#config.taken;
988
+ }
989
+
678
990
  /**
679
991
  * Attributes for the field's control wherever it renders, such as a
680
992
  * placeholder. Those for one form are passed when it renders.
@@ -691,9 +1003,12 @@ class FieldSchema<
691
1003
  ? Field.Props.Select
692
1004
  : Tag extends "textarea"
693
1005
  ? Field.Props.Textarea
694
- : // the field is its type
695
- Field.Props.Input & { readonly type?: never },
696
- ): Field.Instance<Output, Tag, Type, Values, Stream> {
1006
+ : Tag extends "fieldset"
1007
+ ? // a list has no control of its own, each of its fields has one
1008
+ Field.Props.List
1009
+ : // the field is its type
1010
+ Field.Props.Input & { readonly type?: never },
1011
+ ): Field.Instance<Output, Tag, Type, Values, Stream, Item> {
697
1012
  return this.#with({
698
1013
  props: { ...this.#config.props, ...attributes } as Field.Props,
699
1014
  });
@@ -703,7 +1018,7 @@ class FieldSchema<
703
1018
  * @param changes What to change
704
1019
  * @returns The same field with them
705
1020
  */
706
- #with(changes: Pick<Field.Config, "label" | "props">) {
1021
+ #with(changes: Pick<Field.Config, "label" | "hint" | "taken" | "props">) {
707
1022
  return this.#copy({ config: { ...this.#config, ...changes } });
708
1023
  }
709
1024
 
@@ -724,7 +1039,7 @@ class FieldSchema<
724
1039
  stream?: S;
725
1040
  persist?: boolean;
726
1041
  }) {
727
- return new FieldSchema<O, Tag, Type, Values, S>(
1042
+ return new FieldSchema<O, Tag, Type, Values, S, Item>(
728
1043
  config,
729
1044
  def,
730
1045
  this.#read,
@@ -779,6 +1094,54 @@ class FieldSchema<
779
1094
  );
780
1095
  }
781
1096
 
1097
+ /**
1098
+ * Take a textarea's lines as a list of text, such as steps or tags. People
1099
+ * write one on each line, and agents send an array. Empty lines are left
1100
+ * out, each line is checked as this field checks its text, and the list
1101
+ * needs one line unless the field is made optional after.
1102
+ *
1103
+ * ```ts
1104
+ * Field.textarea().lines(); // "Chop\nFry" and ["Chop", "Fry"] are ["Chop", "Fry"]
1105
+ * Field.textarea().max(80).lines(); // each line at most 80 characters
1106
+ * ```
1107
+ *
1108
+ * @returns Textarea field whose value is its lines
1109
+ */
1110
+ lines(
1111
+ this: Field.Instance<string, "textarea", Type, Values, Stream>,
1112
+ ): Field.Instance<string[], "textarea", Type, Values, Stream>;
1113
+ // the overload above is its type
1114
+ lines(): any {
1115
+ const { description, ...def } = this.def;
1116
+ // a description given before describes the field, not each line
1117
+ const array = Schema.array(
1118
+ (description === undefined
1119
+ ? this
1120
+ : this.#copy({ def })) as Schema<unknown>,
1121
+ required,
1122
+ );
1123
+
1124
+ return new FieldSchema(
1125
+ this.#config,
1126
+ description === undefined ? array : { ...array.def, description },
1127
+ (data, name) => {
1128
+ // a person's one value is split, an agent's array has one each
1129
+ const lines = data
1130
+ .getAll(name)
1131
+ .flatMap((value) =>
1132
+ typeof value === "string" ? value.split(/\r?\n/) : [],
1133
+ )
1134
+ .map((line) => line.trim())
1135
+ .filter(Boolean);
1136
+
1137
+ return lines.length ? lines : undefined;
1138
+ },
1139
+ Infinity,
1140
+ this.streaming,
1141
+ this.#persist,
1142
+ );
1143
+ }
1144
+
782
1145
  /**
783
1146
  * Persist this field in the encoded invalid form state.
784
1147
  *
@@ -791,8 +1154,8 @@ class FieldSchema<
791
1154
  persist<
792
1155
  U extends (Tag extends "input" ? Exclude<Type, "password" | "file"> : Type),
793
1156
  >(
794
- this: Field.Instance<Output, Tag, U, Values, Stream>,
795
- ): Field.Instance<Output, Tag, U, Values, Stream>;
1157
+ this: Field.Instance<Output, Tag, U, Values, Stream, Item>,
1158
+ ): Field.Instance<Output, Tag, U, Values, Stream, Item>;
796
1159
  persist() {
797
1160
  return this.#copy({ persist: true });
798
1161
  }
@@ -806,7 +1169,7 @@ class FieldSchema<
806
1169
  */
807
1170
  protected override derive<O>(
808
1171
  def: Schema.Def,
809
- ): Field.Instance<O, Tag, Type, Values, Stream> {
1172
+ ): Field.Instance<O, Tag, Type, Values, Stream, Item> {
810
1173
  return this.#copy<O>({ def });
811
1174
  }
812
1175
 
@@ -815,9 +1178,33 @@ class FieldSchema<
815
1178
  * @returns The field's own choices, those given for a field made from a
816
1179
  * schema, or `undefined` for a field without choices
817
1180
  */
818
- #options(given: readonly string[] | undefined) {
1181
+ #options(given: Field.Component.Props<Field.Shape>["options"]) {
819
1182
  const { options } = this;
820
- return options && (options.length ? options : (given ?? []));
1183
+ return (
1184
+ options &&
1185
+ (options.length
1186
+ ? options
1187
+ : Array.isArray(given)
1188
+ ? (given as readonly string[])
1189
+ : Object.keys(given ?? {}))
1190
+ );
1191
+ }
1192
+
1193
+ /**
1194
+ * @param given Options given as the form renders
1195
+ * @returns What people call each choice: the field's own labels, or those
1196
+ * given with the options of a field made from a schema
1197
+ */
1198
+ #labels(given: Field.Component.Props<Field.Shape>["options"]) {
1199
+ const labels =
1200
+ this.#config.labels ??
1201
+ (this.options?.length || Array.isArray(given)
1202
+ ? undefined
1203
+ : (given as Readonly<Record<string, JSX.Element>> | undefined));
1204
+
1205
+ // own labels only, so a value such as "constructor" is itself
1206
+ return (value: string): JSX.Element =>
1207
+ labels && Object.hasOwn(labels, value) ? labels[value] : value;
821
1208
  }
822
1209
 
823
1210
  /**
@@ -827,19 +1214,31 @@ class FieldSchema<
827
1214
  */
828
1215
  [component]<S extends Field.Shape>(
829
1216
  props: Field.Component.Props<S, false>,
1217
+ named?: string,
1218
+ described?: boolean | string,
830
1219
  ): Field.Component<this>;
831
- [component]<S extends Field.Shape>({
832
- state,
833
- options: given,
834
- ...props
835
- }: Field.Component.Props<S, false>): unknown {
1220
+ [component]<S extends Field.Shape>(
1221
+ { state, options: given, ...props }: Field.Component.Props<S, false>,
1222
+ // what a list calls its cell, which is named by its place
1223
+ named: string = props.name,
1224
+ // if the control is read with its description. A row laid out by
1225
+ // hand, such as in a table, seldom renders each cell's, and the
1226
+ // default table has one for the column, whose ID this is.
1227
+ described: boolean | string = true,
1228
+ ): unknown {
836
1229
  const options = this.#options(given);
1230
+ const text = this.#labels(given);
837
1231
  const value = state?.values?.[props.name];
838
- const issue = state?.issues?.find((i) => i.path[0] === props.name);
1232
+ const issue = state?.issues?.find(
1233
+ (i) =>
1234
+ i.path[0] === props.name &&
1235
+ // a list's own, each of its cells shows its own
1236
+ (!this.item || i.path.length === 1),
1237
+ );
839
1238
  const issueId = issue && `${props.name}-issue`;
840
1239
  const hidden = this.type === "hidden";
841
- const { label = props.name } = this.#config;
842
- const { description } = this;
1240
+ const { label = named } = this.#config;
1241
+ const description = this.#shown();
843
1242
  const descriptionId =
844
1243
  description && !hidden ? `${props.name}-description` : undefined;
845
1244
  const control = {
@@ -849,7 +1248,9 @@ class FieldSchema<
849
1248
  "aria-invalid": issue && "true",
850
1249
  // read with the control: its description, then what is wrong with it
851
1250
  "aria-describedby":
852
- [descriptionId, issueId].filter(Boolean).join(" ") || undefined,
1251
+ [described === true ? descriptionId : described, issueId]
1252
+ .filter(Boolean)
1253
+ .join(" ") || undefined,
853
1254
  ...this.#config.props,
854
1255
  ...props,
855
1256
  };
@@ -860,7 +1261,7 @@ class FieldSchema<
860
1261
  */
861
1262
  const chosen = (option: string) =>
862
1263
  Array.isArray(value)
863
- ? value.includes(option) // checkboxes and multiselect
1264
+ ? (value as readonly unknown[]).includes(option) // checkboxes and multiselect
864
1265
  : value === option; // radio and select
865
1266
 
866
1267
  const Description = (data: Field.Component.Description = {}) =>
@@ -882,17 +1283,67 @@ class FieldSchema<
882
1283
  ...data,
883
1284
  });
884
1285
 
1286
+ if (this.item) {
1287
+ const cells = () => this.#cells({ state, options: given, ...props });
1288
+ let built: unknown[] | undefined;
1289
+ // a list has no control of its own, so what is passed to it, such
1290
+ // as a class, is its fieldset's
1291
+ const { name: _, rows: __, ...attributes } = props;
1292
+
1293
+ return {
1294
+ Description,
1295
+ Issue,
1296
+ Root: (data: Field.Component.Root.Group = {}) =>
1297
+ jsx("fieldset", { ...attributes, ...data }),
1298
+ Legend: (data: Field.Component.Legend = {}) =>
1299
+ jsx("legend", { children: label, ...data }),
1300
+ ...this,
1301
+ // built when read, the default layout renders each cell itself
1302
+ get rows() {
1303
+ return (built ??= cells().map((row) =>
1304
+ Array.isArray(row)
1305
+ ? row[0][component](row[1], row[2], false)
1306
+ : Object.fromEntries(
1307
+ Object.entries(row).map(([key, cell]) => [
1308
+ key,
1309
+ cell[0][component](cell[1], cell[2], false),
1310
+ ]),
1311
+ ),
1312
+ ));
1313
+ },
1314
+ };
1315
+ }
1316
+
885
1317
  if (options && this.tag !== "select") {
886
1318
  // radio/checkboxes
887
1319
  // make multiple ids for the group so all don't have the same id
888
1320
  const groupId = (value: string) =>
889
1321
  `${control.name}-${value}`.toLowerCase();
890
1322
 
1323
+ // a group's own attributes, such as a class, are its fieldset's,
1324
+ // as a list's are. Each box has those `control()` set, and if it
1325
+ // is required.
1326
+ const {
1327
+ name,
1328
+ required = this.#required(),
1329
+ placeholder: _,
1330
+ ...attributes
1331
+ } = props;
1332
+ const box = {
1333
+ id: undefined as string | undefined,
1334
+ required,
1335
+ autofocus: control.autofocus,
1336
+ "aria-invalid": control["aria-invalid"],
1337
+ "aria-describedby": control["aria-describedby"],
1338
+ ...this.#config.props,
1339
+ name,
1340
+ };
1341
+
891
1342
  const Control = (
892
1343
  data: Field.Component.Control.Group<"input", Field.Options>,
893
1344
  ) =>
894
1345
  jsx(this.tag, {
895
- ...control,
1346
+ ...box,
896
1347
  id: groupId(data.value),
897
1348
  // autofocus only the first input in the group
898
1349
  autofocus: control.autofocus && data.value === options[0],
@@ -904,14 +1355,15 @@ class FieldSchema<
904
1355
  value,
905
1356
  ...rest
906
1357
  }: Field.Component.Label.Group<Field.Options>) =>
907
- jsx("label", { for: groupId(value), children: value, ...rest });
1358
+ jsx("label", { for: groupId(value), children: text(value), ...rest });
908
1359
 
909
1360
  return {
910
1361
  Description,
911
1362
  Issue,
912
1363
  Label,
913
1364
  Control,
914
- Root: (data: Field.Component.Root = {}) => jsx("fieldset", data),
1365
+ Root: (data: Field.Component.Root = {}) =>
1366
+ jsx("fieldset", { ...attributes, ...data }),
915
1367
  Option: ({
916
1368
  value,
917
1369
  ...rest
@@ -936,10 +1388,14 @@ class FieldSchema<
936
1388
  !hidden && jsx("label", { for: control.id, children: label, ...data }),
937
1389
  Control: (data?: Field.Component.Control<Tag>) => {
938
1390
  const attrs = { ...control, ...data };
1391
+ // a select has none: it is the text of its empty choice
1392
+ if (this.tag === "select")
1393
+ delete (attrs as { placeholder?: unknown }).placeholder;
939
1394
 
940
1395
  if (value !== undefined) {
941
1396
  if (this.tag === "textarea") {
942
- attrs.children = value;
1397
+ // each of its `lines()` on its own line
1398
+ attrs.children = Array.isArray(value) ? value.join("\n") : value;
943
1399
  } else if (this.tag === "input") {
944
1400
  if (this.type === "checkbox") {
945
1401
  attrs.checked = value;
@@ -956,7 +1412,7 @@ class FieldSchema<
956
1412
  options &&
957
1413
  ((data: Field.Component.Option<Field.Options>) =>
958
1414
  jsx("option", {
959
- children: data.value,
1415
+ children: text(data.value),
960
1416
  selected: chosen(data.value),
961
1417
  ...data,
962
1418
  })),
@@ -970,43 +1426,307 @@ class FieldSchema<
970
1426
  * @param props Field control props including `name` of the field to render
971
1427
  * @returns Component that renders the HTML field with default structure
972
1428
  */
973
- [render]<S extends Field.Shape>(props: Field.Component.Props<S, false>) {
974
- // the sub-components of each kind of field, told apart by `options` and `tag` below
975
- const c = this[component](
976
- props,
977
- ) as unknown as Field.Component<Field.Any> & {
978
- Legend: (props?: Field.Component.Legend) => JSX.Element;
979
- Option: (props: Field.Component.Option<Field.Options>) => JSX.Element;
980
- };
981
- const options = this.#options(props.options);
1429
+ [render]<S extends Field.Shape>(
1430
+ props: Field.Component.Props<S, false>,
1431
+ named?: string,
1432
+ ): JSX.Element {
1433
+ const { item } = this;
1434
+ // a list of several fields is a table, a column for each
1435
+ if (item && !(item instanceof FieldSchema)) return this.#table(props, item);
1436
+
1437
+ const c = this[component](props, named) as unknown as Parts;
982
1438
 
983
1439
  return c.Root({
984
1440
  children: [
985
- options && this.tag !== "select"
986
- ? // radio/checkboxes, a group with a legend, each value labelled
1441
+ item
1442
+ ? // a list of one field, a group with a legend, a row for each.
1443
+ // Its description is before the rows it explains, which
1444
+ // may be many.
987
1445
  [
988
1446
  c.Legend(),
989
- options.map((value) =>
990
- jsx("div", {
991
- children: [c.Control({ value }), c.Label({ value })],
992
- }),
993
- ),
1447
+ c.Description(),
1448
+ this.#cells(props).map((row) => {
1449
+ const [field, cell, named] = row as Placed;
1450
+ return field[render](cell, named);
1451
+ }),
994
1452
  ]
995
- : [
996
- c.Label(),
997
- // a select has an option for each value
998
- c.Control(
999
- options && {
1000
- children: options.map((value) => c.Option({ value })),
1001
- },
1002
- ),
1003
- ],
1453
+ : this.#grouped(props)
1454
+ ? // before the options it explains, as a list's is
1455
+ [c.Legend(), c.Description(), this.#body(c, props)]
1456
+ : [c.Label(), this.#body(c, props), c.Description()],
1457
+ c.Issue(),
1458
+ ],
1459
+ });
1460
+ }
1461
+
1462
+ /**
1463
+ * @template S Form shape type
1464
+ * @param props Field control props
1465
+ * @returns `true` for a radio or checkbox group
1466
+ */
1467
+ #grouped<S extends Field.Shape>(props: Field.Component.Props<S, false>) {
1468
+ return Boolean(this.#options(props.options)) && this.tag !== "select";
1469
+ }
1470
+
1471
+ /**
1472
+ * @template S Form shape type
1473
+ * @param c The field's parts
1474
+ * @param props Field control props
1475
+ * @returns The field's control: a group's boxes each with its label, or
1476
+ * one control, a select with its options
1477
+ */
1478
+ #body<S extends Field.Shape>(
1479
+ c: Parts,
1480
+ props: Field.Component.Props<S, false>,
1481
+ ) {
1482
+ const options = this.#options(props.options);
1483
+ if (!options) return c.Control();
1484
+
1485
+ if (this.tag !== "select")
1486
+ return options.map((value) =>
1487
+ jsx("div", { children: [c.Control({ value }), c.Label({ value })] }),
1488
+ );
1489
+
1490
+ const placeholder =
1491
+ props.placeholder ??
1492
+ (this.#config.props as Field.Props.Select | undefined)?.placeholder;
1493
+
1494
+ return c.Control({
1495
+ children: [
1496
+ // a browser chooses a select's first option, so one that may be
1497
+ // left empty, or that says what to choose, starts with an empty
1498
+ // choice
1499
+ (placeholder !== undefined || !(props.required ?? this.#required())) &&
1500
+ !this.#config.props?.multiple &&
1501
+ jsx("option", { value: "", children: placeholder }),
1502
+ options.map((value) => c.Option({ value })),
1503
+ ],
1504
+ });
1505
+ }
1506
+
1507
+ /**
1508
+ * @template S Form shape type
1509
+ * @param props The list's props
1510
+ * @param item The fields of each item, by name
1511
+ * @returns A list of several fields: a table with a column for each
1512
+ * field, named in its heading and described once under the table, and a
1513
+ * row for each item
1514
+ */
1515
+ #table<S extends Field.Shape>(
1516
+ props: Field.Component.Props<S, false>,
1517
+ item: Readonly<Record<string, Field.Cell>>,
1518
+ ) {
1519
+ const c = this[component](props) as unknown as Parts;
1520
+ const fields = Object.entries(item);
1521
+ const columns = fields.filter(([, field]) => field.type !== "hidden");
1522
+ const id = (key: string, part: string) => `${props.name}.${key}-${part}`;
1523
+
1524
+ return c.Root({
1525
+ children: [
1526
+ c.Legend(),
1004
1527
  c.Description(),
1528
+ // an element of its own, so a wide table can scroll alone and the
1529
+ // text around it keeps the fieldset's width
1530
+ jsx("div", {
1531
+ children: jsx("table", {
1532
+ children: [
1533
+ jsx("thead", {
1534
+ children: jsx("tr", {
1535
+ children: columns.map(([key, field]) =>
1536
+ // only the label, which names each cell of the column
1537
+ jsx("th", {
1538
+ id: id(key, "label"),
1539
+ scope: "col",
1540
+ children: field.#config.label ?? key,
1541
+ }),
1542
+ ),
1543
+ }),
1544
+ }),
1545
+ jsx("tbody", {
1546
+ children: this.#cells(props).map((cells) => {
1547
+ const row = cells as Readonly<Record<string, Placed>>;
1548
+
1549
+ return jsx("tr", {
1550
+ children: columns.map(([key, field], column) => {
1551
+ const [, cell, named] = row[key]!;
1552
+ const group = field.#grouped(cell);
1553
+ const labelled = { "aria-labelledby": id(key, "label") };
1554
+ const parts = field[component](
1555
+ group ? cell : { ...cell, ...labelled },
1556
+ named,
1557
+ Boolean(field.#shown()) && id(key, "description"),
1558
+ ) as unknown as Parts;
1559
+ const body = field.#body(parts, cell);
1560
+
1561
+ return jsx("td", {
1562
+ children: [
1563
+ // a row's hidden values, such as its ID
1564
+ !column &&
1565
+ fields.map(
1566
+ ([key, field]) =>
1567
+ field.type === "hidden" &&
1568
+ field[render](row[key]![1], row[key]![2]),
1569
+ ),
1570
+ group
1571
+ ? jsx("div", {
1572
+ role: "group",
1573
+ ...labelled,
1574
+ children: body,
1575
+ })
1576
+ : body,
1577
+ parts.Issue(),
1578
+ ],
1579
+ });
1580
+ }),
1581
+ });
1582
+ }),
1583
+ }),
1584
+ ],
1585
+ }),
1586
+ }),
1587
+ // what each column is, once under the table: a heading has no
1588
+ // room for it. Each cell of the column is read with its text.
1589
+ columns.map(
1590
+ ([key, field]) =>
1591
+ field.#shown() &&
1592
+ jsx("p", {
1593
+ "data-description": true,
1594
+ children: [
1595
+ jsx("span", { children: field.#config.label ?? key }),
1596
+ ": ",
1597
+ jsx("span", {
1598
+ id: id(key, "description"),
1599
+ children: field.#shown(),
1600
+ }),
1601
+ ],
1602
+ }),
1603
+ ),
1005
1604
  c.Issue(),
1006
1605
  ],
1007
1606
  });
1008
1607
  }
1009
1608
 
1609
+ /** The most rows a list without a `max()` takes in one request */
1610
+ static readonly #rows = 1000;
1611
+
1612
+ /**
1613
+ * @param field List field
1614
+ * @returns The most items it shows from state in a URL: its `max()`, or
1615
+ * the most any list takes
1616
+ */
1617
+ static most(field: Field.Any) {
1618
+ return Math.min(field.#most(), FieldSchema.#rows);
1619
+ }
1620
+
1621
+ /**
1622
+ * @returns The most items a list takes, set with `max()`
1623
+ */
1624
+ #most() {
1625
+ let most = Infinity;
1626
+
1627
+ for (
1628
+ let def: Schema.Def | undefined = this.def;
1629
+ def && "inner" in def;
1630
+ def = def.inner.def
1631
+ ) {
1632
+ if (def.type === "check" && def.check.name === "max")
1633
+ most = Math.min(most, Math.floor(Number(def.check.value)));
1634
+ }
1635
+
1636
+ return most;
1637
+ }
1638
+
1639
+ /**
1640
+ * @template S Form shape type
1641
+ * @param props The list's props
1642
+ * @returns Each row of the list: its filled items, then empty ones. A row is
1643
+ * its cell, or its cells by name, each as the field, the props that render
1644
+ * it, and what it is called.
1645
+ */
1646
+ #cells<S extends Field.Shape>({
1647
+ state,
1648
+ rows,
1649
+ ...props
1650
+ }: Field.Component.Props<S, false>) {
1651
+ const item = this.item as Field.Item;
1652
+ const { name } = props;
1653
+ // for this form, or wherever the list renders, set with `control()`
1654
+ const shown =
1655
+ rows ?? (this.#config.props as Field.Props.List | undefined)?.rows;
1656
+ const value = state?.values?.[name];
1657
+ const filled: unknown[] = Array.isArray(value) ? value : [];
1658
+ const values: Record<string, unknown> = {};
1659
+
1660
+ filled.forEach((row, place) => {
1661
+ if (item instanceof FieldSchema) values[`${name}.${place}`] = row;
1662
+ else if (row && typeof row === "object")
1663
+ for (const key of Object.keys(item))
1664
+ values[`${name}.${place}.${key}`] = (row as Record<string, unknown>)[
1665
+ key
1666
+ ];
1667
+ });
1668
+
1669
+ // each cell finds its value and its issue by its own name
1670
+ const depth = item instanceof FieldSchema ? 2 : 3;
1671
+ const cells = {
1672
+ id: state?.id ?? "",
1673
+ values,
1674
+ issues: state?.issues?.map((issue) =>
1675
+ issue.path[0] === name && issue.path.length > 1
1676
+ ? new Schema.Issue(
1677
+ issue.expected,
1678
+ [
1679
+ issue.path.slice(0, depth).join("."),
1680
+ ...issue.path.slice(depth),
1681
+ ],
1682
+ issue.message,
1683
+ )
1684
+ : issue,
1685
+ ),
1686
+ } as unknown as Field.State<Field.Shape>;
1687
+
1688
+ const cell = (field: Field.Cell, name: string, named: string) =>
1689
+ [
1690
+ field,
1691
+ // never required: a row left empty is left out. The list's own
1692
+ // attributes are its fieldset's, not each control's.
1693
+ { name, state: cells, options: props.options, required: false },
1694
+ named,
1695
+ ] as const;
1696
+
1697
+ return Array.from(
1698
+ {
1699
+ // every filled row, and one more unless told how many to show,
1700
+ // but no more empty rows than the list takes
1701
+ length: Math.max(
1702
+ filled.length,
1703
+ Math.min(
1704
+ shown === undefined ? filled.length + 1 : Number(shown),
1705
+ this.#most(),
1706
+ ),
1707
+ ),
1708
+ },
1709
+ (_, place) =>
1710
+ item instanceof FieldSchema
1711
+ ? cell(item, `${name}.${place}`, String(place + 1))
1712
+ : Object.fromEntries(
1713
+ Object.entries(item).map(([key, field]) => [
1714
+ key,
1715
+ cell(field, `${name}.${place}.${key}`, key),
1716
+ ]),
1717
+ ),
1718
+ );
1719
+ }
1720
+
1721
+ /**
1722
+ * @param field Field definition
1723
+ * @param name The field's name
1724
+ * @returns What people call the field: its label, or its name
1725
+ */
1726
+ static named(field: Field.Any, name: string) {
1727
+ return field.#config.label ?? name;
1728
+ }
1729
+
1010
1730
  /**
1011
1731
  * @param field Field definition
1012
1732
  * @returns `true` when the field persists invalid-state values
@@ -1016,6 +1736,24 @@ class FieldSchema<
1016
1736
  }
1017
1737
  }
1018
1738
 
1739
+ /** The parts of any kind of field, as its default layout uses them */
1740
+ type Parts = {
1741
+ Root: (props?: Field.Component.Root) => JSX.Element;
1742
+ Legend: (props?: Field.Component.Legend) => JSX.Element;
1743
+ Label: (props?: { value?: string }) => JSX.Element;
1744
+ Control: (props?: { value?: string; children?: unknown }) => JSX.Element;
1745
+ Option: (props: Field.Component.Option<Field.Options>) => JSX.Element;
1746
+ Description: (props?: Field.Component.Description) => JSX.Element;
1747
+ Issue: (props?: Field.Component.Issue) => JSX.Element;
1748
+ };
1749
+
1750
+ /** A cell of a list's row: its field, the props that render it, and its name */
1751
+ type Placed = readonly [
1752
+ field: Field.Cell,
1753
+ props: Field.Component.Props<Field.Shape, false>,
1754
+ named: string,
1755
+ ];
1756
+
1019
1757
  /**
1020
1758
  * @param value Schema
1021
1759
  * @returns `true` for a form field, such as a table column made with `Field`
@@ -1027,10 +1765,13 @@ export namespace Field {
1027
1765
  /** Fields by name, as a route's `fields` takes them. */
1028
1766
  export type Shape = Record<string, Field.Any>;
1029
1767
 
1030
- /** Persisted form value */
1031
- export type Value = string | number | boolean | string[];
1768
+ /** Persisted form value, a list's is its items */
1769
+ export type Value = Value.Cell | Value.Cell[] | Record<string, Value.Cell>[];
1032
1770
 
1033
1771
  export namespace Value {
1772
+ /** Value of one control, or of a cell of a list */
1773
+ export type Cell = string | number | boolean | string[];
1774
+
1034
1775
  /**
1035
1776
  * Value map by field name.
1036
1777
  *
@@ -1074,7 +1815,14 @@ export namespace Field {
1074
1815
  * @template S Form shape
1075
1816
  */
1076
1817
  type NonStreamNames<S extends Shape> = {
1077
- [K in keyof S]-?: S[K] extends Field.Instance<any, any, any, any, infer P>
1818
+ [K in keyof S]-?: S[K] extends Field.Instance<
1819
+ any,
1820
+ any,
1821
+ any,
1822
+ any,
1823
+ infer P,
1824
+ any
1825
+ >
1078
1826
  ? P extends true
1079
1827
  ? never
1080
1828
  : K
@@ -1095,6 +1843,15 @@ export namespace Field {
1095
1843
  */
1096
1844
  export type Data<S extends Shape> = Schema.Infer<NonStreamShape<S>>;
1097
1845
 
1846
+ /**
1847
+ * The fields a request sets, `null` for one it clears.
1848
+ *
1849
+ * @template S Form shape
1850
+ */
1851
+ export type Updates<S extends Shape> = {
1852
+ readonly [K in keyof Data<S>]?: Exclude<Data<S>[K], undefined> | null;
1853
+ };
1854
+
1098
1855
  /**
1099
1856
  * Form parse result.
1100
1857
  *
@@ -1108,6 +1865,14 @@ export namespace Field {
1108
1865
  Data<S>,
1109
1866
  Result.Invalid<M>,
1110
1867
  {
1868
+ /**
1869
+ * What the request sets, to update a record with: each field
1870
+ * it sent, `null` for one sent empty, and nothing for one it
1871
+ * left out, which keeps its value. A form sends every field it
1872
+ * has, and an agent only the ones to change.
1873
+ */
1874
+ readonly updates: Updates<S>;
1875
+
1111
1876
  /** Rest of the multipart parts to stream */
1112
1877
  readonly stream?: AsyncGenerator<Multipart.Part> | undefined;
1113
1878
 
@@ -1171,9 +1936,21 @@ export namespace Field {
1171
1936
  /** Choices of a select, radio, or checkbox group */
1172
1937
  readonly options?: V;
1173
1938
 
1939
+ /** What people call each choice, by its value */
1940
+ readonly labels?: Readonly<Record<string, string>> | undefined;
1941
+
1174
1942
  /** What people call the field, set with `label()` */
1175
1943
  readonly label?: string;
1176
1944
 
1945
+ /** What people read in place of the description, set with `hint()` */
1946
+ readonly hint?: string;
1947
+
1948
+ /** What registration says when a user already has the value, set with `taken()` */
1949
+ readonly taken?: string;
1950
+
1951
+ /** What each item of a list is */
1952
+ readonly item?: Item;
1953
+
1177
1954
  /** Field props */
1178
1955
  readonly props?: Props | undefined;
1179
1956
  }
@@ -1182,10 +1959,15 @@ export namespace Field {
1182
1959
  * Raw field value before schema parsing.
1183
1960
  *
1184
1961
  * Single-value fields read one entry, multi-value fields read all entries,
1185
- * and checkboxes read presence.
1962
+ * checkboxes read presence, and lists read each item's cells.
1186
1963
  */
1187
- export type Input =
1188
- FormDataEntryValue | FormDataEntryValue[] | boolean | undefined;
1964
+ export type Input = Input.Cell | Input.Cell[] | Record<string, Input.Cell>[];
1965
+
1966
+ export namespace Input {
1967
+ /** Raw value of one field, or of a cell of a list */
1968
+ export type Cell =
1969
+ FormDataEntryValue | FormDataEntryValue[] | boolean | undefined;
1970
+ }
1189
1971
 
1190
1972
  /**
1191
1973
  * @param data FormData or URLSearchParams
@@ -1194,8 +1976,33 @@ export namespace Field {
1194
1976
  */
1195
1977
  export type Read = (data: FormData | URLSearchParams, name: string) => Input;
1196
1978
 
1197
- /** Form field tag name */
1198
- export type Tag = "input" | "textarea" | "select";
1979
+ /** Form field tag name, a list is a `fieldset` of its items */
1980
+ export type Tag = "input" | "textarea" | "select" | "fieldset";
1981
+
1982
+ /** A field of a list's item: any but another list or a streamed field */
1983
+ export type Cell = Instance<
1984
+ any,
1985
+ Exclude<Tag, "fieldset">,
1986
+ Type,
1987
+ Options | undefined
1988
+ >;
1989
+
1990
+ /** What each item of a list is: a field, or fields by name */
1991
+ export type Item = Cell | Readonly<Record<string, Cell>>;
1992
+
1993
+ export namespace Item {
1994
+ /**
1995
+ * Parsed value of an item.
1996
+ *
1997
+ * @template I Item
1998
+ */
1999
+ export type Output<I extends Item> =
2000
+ I extends Schema<infer O>
2001
+ ? O
2002
+ : I extends Schema.Object.Shape
2003
+ ? Util.Prettify<Schema.Infer<I>>
2004
+ : never;
2005
+ }
1199
2006
 
1200
2007
  /** `<input type=...>` */
1201
2008
  export type Type = JSX.IntrinsicElements["input"]["type"];
@@ -1203,6 +2010,15 @@ export namespace Field {
1203
2010
  /** Value type for select and radio options */
1204
2011
  export type Options = readonly [string, ...string[]];
1205
2012
 
2013
+ /**
2014
+ * Fixed choices of a select, radio, or checkbox group: the values, or what
2015
+ * people call each one by its value, such as `{ crockpot: "Slow cooker" }`.
2016
+ *
2017
+ * @template V Value type
2018
+ */
2019
+ export type Choices<V extends string> =
2020
+ readonly [V, ...V[]] | Readonly<Record<V, string>>;
2021
+
1206
2022
  /**
1207
2023
  * Field instance type
1208
2024
  *
@@ -1211,6 +2027,7 @@ export namespace Field {
1211
2027
  * @template Type Input type
1212
2028
  * @template Values Options of a select, radio, or checkbox group
1213
2029
  * @template Stream Whether the field streams as a multipart part
2030
+ * @template Item What each item of a list is
1214
2031
  */
1215
2032
  export type Instance<
1216
2033
  Output = unknown,
@@ -1218,15 +2035,17 @@ export namespace Field {
1218
2035
  Type extends Field.Type = Field.Type,
1219
2036
  Values extends Field.Options | undefined = undefined,
1220
2037
  Stream extends boolean | undefined = undefined,
1221
- > = FieldSchema<Output, Tag, Type, Values, Stream>;
2038
+ Item extends Field.Item | undefined = undefined,
2039
+ > = FieldSchema<Output, Tag, Type, Values, Stream, Item>;
1222
2040
 
1223
- /** Any field - `<input type=...>` / `<select>` / `<textarea>` */
2041
+ /** Any field - `<input type=...>` / `<select>` / `<textarea>` / a list */
1224
2042
  export type Any = Instance<
1225
2043
  any,
1226
2044
  Tag,
1227
2045
  Type,
1228
2046
  Options | undefined,
1229
- boolean | undefined
2047
+ boolean | undefined,
2048
+ Item | undefined
1230
2049
  >;
1231
2050
 
1232
2051
  /**
@@ -1254,10 +2073,21 @@ export namespace Field {
1254
2073
  /**
1255
2074
  * Choices of a checkbox group, radio group, or select made from a
1256
2075
  * schema, such as `Field.checkboxes(Schema.string().uuid())`, known
1257
- * as the form renders. Each is shown as its value unless a custom
1258
- * layout labels it.
2076
+ * as the form renders: the values, each shown as it is, or what
2077
+ * people call each one by its value, such as `{ [recipe.id]:
2078
+ * recipe.title }`. A label may be an element, such as an image
2079
+ * with its `alt`.
1259
2080
  */
1260
- readonly options?: readonly string[] | undefined;
2081
+ readonly options?:
2082
+ readonly string[] | Readonly<Record<string, JSX.Element>> | undefined;
2083
+
2084
+ /**
2085
+ * How many rows a list shows on this form, over what its
2086
+ * `control({ rows })` set. Without either, a list shows its items and
2087
+ * one empty row to add another. Every item is always shown, and no
2088
+ * more rows than its `max()`.
2089
+ */
2090
+ readonly rows?: number | undefined;
1261
2091
 
1262
2092
  /** Form state */
1263
2093
  readonly state?: (I extends true ? URL : Field.State<S>) | undefined;
@@ -1361,78 +2191,121 @@ export namespace Field {
1361
2191
  * @returns Issue container paragraph
1362
2192
  */
1363
2193
  Issue: (props?: Component.Issue) => JSX.Element;
1364
- } & (F extends Instance<any, "select", Field.Type, infer V>
1365
- ? V extends Options
1366
- ? // select
1367
- {
1368
- /** The select's options */
1369
- options: V;
1370
-
1371
- /**
1372
- * @param props Root props
1373
- * @returns Root container div
1374
- */
1375
- Root: (props?: Component.Root) => JSX.Element;
1376
-
1377
- /**
1378
- * @param props Label props
1379
- * @returns Label element
1380
- */
1381
- Label: (props?: Component.Label) => JSX.Element;
1382
-
1383
- /**
1384
- * @param props Control props
1385
- * @returns Control select element
1386
- */
1387
- Control: (props?: Component.Control<"select">) => JSX.Element;
1388
-
1389
- /**
1390
- * @param props Option props
1391
- * @returns Select option element
1392
- */
1393
- Option: (props: Component.Option<V>) => JSX.Element;
1394
- }
1395
- : never
1396
- : F extends Instance<any, "input", Field.Type, infer V>
2194
+ } & (F extends { readonly tag: "fieldset"; readonly item: infer I }
2195
+ ? // list
2196
+ {
2197
+ /**
2198
+ * @param props Root props
2199
+ * @returns Root container fieldset
2200
+ */
2201
+ Root: (props?: Component.Root.Group) => JSX.Element;
2202
+
2203
+ /**
2204
+ * @param props Legend element props
2205
+ * @returns Legend element
2206
+ */
2207
+ Legend: (props?: Component.Legend) => JSX.Element;
2208
+
2209
+ /**
2210
+ * The list's rows, its items and then the empty ones: each is
2211
+ * its field's component, or its fields' components by name
2212
+ */
2213
+ rows: readonly (I extends Cell
2214
+ ? Component<I>
2215
+ : { readonly [K in keyof I]: Component<Extract<I[K], Cell>> })[];
2216
+ }
2217
+ : F extends Instance<any, "select", Field.Type, infer V>
1397
2218
  ? V extends Options
1398
- ? // radio/checkboxes
2219
+ ? // select
1399
2220
  {
1400
- /** The group's options */
2221
+ /** The select's options */
1401
2222
  options: V;
1402
2223
 
1403
2224
  /**
1404
2225
  * @param props Root props
1405
- * @returns Root container fieldset
1406
- */
1407
- Root: (props?: Component.Root.Group) => JSX.Element;
1408
-
1409
- /**
1410
- * @param props Legend element props
1411
- * @returns Legend element
2226
+ * @returns Root container div
1412
2227
  */
1413
- Legend: (props?: Component.Legend) => JSX.Element;
2228
+ Root: (props?: Component.Root) => JSX.Element;
1414
2229
 
1415
2230
  /**
1416
- * @param props Label props including `value`
2231
+ * @param props Label props
1417
2232
  * @returns Label element
1418
2233
  */
1419
- Label: (props: Component.Label.Group<V>) => JSX.Element;
2234
+ Label: (props?: Component.Label) => JSX.Element;
1420
2235
 
1421
2236
  /**
1422
2237
  * @param props Control props
1423
- * @returns Control input element
2238
+ * @returns Control select element
1424
2239
  */
1425
- Control: (
1426
- props?: Component.Control.Group<"input", V>,
1427
- ) => JSX.Element;
2240
+ Control: (props?: Component.Control<"select">) => JSX.Element;
1428
2241
 
1429
2242
  /**
1430
2243
  * @param props Option props
1431
- * @returns Both label and input elements together
2244
+ * @returns Select option element
1432
2245
  */
1433
- Option: (props: Component.Option.Input<V>) => JSX.Element;
2246
+ Option: (props: Component.Option<V>) => JSX.Element;
1434
2247
  }
1435
- : // regular input
2248
+ : never
2249
+ : F extends Instance<any, "input", Field.Type, infer V>
2250
+ ? V extends Options
2251
+ ? // radio/checkboxes
2252
+ {
2253
+ /** The group's options */
2254
+ options: V;
2255
+
2256
+ /**
2257
+ * @param props Root props
2258
+ * @returns Root container fieldset
2259
+ */
2260
+ Root: (props?: Component.Root.Group) => JSX.Element;
2261
+
2262
+ /**
2263
+ * @param props Legend element props
2264
+ * @returns Legend element
2265
+ */
2266
+ Legend: (props?: Component.Legend) => JSX.Element;
2267
+
2268
+ /**
2269
+ * @param props Label props including `value`
2270
+ * @returns Label element
2271
+ */
2272
+ Label: (props: Component.Label.Group<V>) => JSX.Element;
2273
+
2274
+ /**
2275
+ * @param props Control props
2276
+ * @returns Control input element
2277
+ */
2278
+ Control: (
2279
+ props?: Component.Control.Group<"input", V>,
2280
+ ) => JSX.Element;
2281
+
2282
+ /**
2283
+ * @param props Option props
2284
+ * @returns Both label and input elements together
2285
+ */
2286
+ Option: (props: Component.Option.Input<V>) => JSX.Element;
2287
+ }
2288
+ : // regular input
2289
+ {
2290
+ /**
2291
+ * @param props Root props
2292
+ * @returns Root container div
2293
+ */
2294
+ Root: (props?: Component.Root) => JSX.Element;
2295
+
2296
+ /**
2297
+ * @param props Label props
2298
+ * @returns Label element
2299
+ */
2300
+ Label: (props?: Component.Label) => JSX.Element;
2301
+
2302
+ /**
2303
+ * @param props Control props
2304
+ * @returns Control input element
2305
+ */
2306
+ Control: (props?: Component.Control<"input">) => JSX.Element;
2307
+ }
2308
+ : // textarea
1436
2309
  {
1437
2310
  /**
1438
2311
  * @param props Root props
@@ -1448,30 +2321,10 @@ export namespace Field {
1448
2321
 
1449
2322
  /**
1450
2323
  * @param props Control props
1451
- * @returns Control input element
2324
+ * @returns Control textarea element
1452
2325
  */
1453
- Control: (props?: Component.Control<"input">) => JSX.Element;
1454
- }
1455
- : // textarea
1456
- {
1457
- /**
1458
- * @param props Root props
1459
- * @returns Root container div
1460
- */
1461
- Root: (props?: Component.Root) => JSX.Element;
1462
-
1463
- /**
1464
- * @param props Label props
1465
- * @returns Label element
1466
- */
1467
- Label: (props?: Component.Label) => JSX.Element;
1468
-
1469
- /**
1470
- * @param props Control props
1471
- * @returns Control textarea element
1472
- */
1473
- Control: (props?: Component.Control<"textarea">) => JSX.Element;
1474
- })
2326
+ Control: (props?: Component.Control<"textarea">) => JSX.Element;
2327
+ })
1475
2328
  >;
1476
2329
 
1477
2330
  /** Any field props */
@@ -1495,10 +2348,28 @@ export namespace Field {
1495
2348
  export type Input = JSX.IntrinsicElements["input"] & Chained;
1496
2349
 
1497
2350
  /** Attributes of a `<select>` field's control */
1498
- export type Select = JSX.IntrinsicElements["select"] & Chained;
2351
+ export type Select = JSX.IntrinsicElements["select"] &
2352
+ Chained & {
2353
+ /**
2354
+ * Text of the select's empty first choice, such as "Any meal". A
2355
+ * select that must be chosen has the choice too when this is
2356
+ * set, and the browser asks for another.
2357
+ */
2358
+ readonly placeholder?: string | undefined;
2359
+ };
1499
2360
 
1500
2361
  /** Attributes of a `<textarea>` field's control */
1501
2362
  export type Textarea = JSX.IntrinsicElements["textarea"] & Chained;
2363
+
2364
+ /** What a list takes in place of a control's attributes */
2365
+ export type List = {
2366
+ /**
2367
+ * How many rows the list shows. Without it, a list shows its items
2368
+ * and one empty row to add another. Every item is always shown, and
2369
+ * no more rows than its `max()`.
2370
+ */
2371
+ readonly rows?: number | undefined;
2372
+ };
1502
2373
  }
1503
2374
  }
1504
2375
 
@@ -1518,6 +2389,41 @@ export class Field {
1518
2389
  return new FieldSchema({ props }, Schema.string(required));
1519
2390
  }
1520
2391
 
2392
+ /** A time as a browser's picker sends it, with seconds when it has them */
2393
+ static readonly #clock = /^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d(\.\d{1,3})?)?$/;
2394
+
2395
+ /**
2396
+ * @param value Text
2397
+ * @returns `true` for a day of the calendar as YYYY-MM-DD
2398
+ */
2399
+ static #day(value: string) {
2400
+ if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
2401
+
2402
+ const date = new Date(`${value}T00:00:00Z`);
2403
+ // a day that is not one, such as the 31st of June, becomes another
2404
+ return (
2405
+ !Number.isNaN(date.getTime()) && date.toISOString().startsWith(value)
2406
+ );
2407
+ }
2408
+
2409
+ /**
2410
+ * A browser's picker only sends its own format, but an agent, or any
2411
+ * other client, sends what it likes, so the value is checked.
2412
+ *
2413
+ * @template T Input type
2414
+ * @param type Input type of the picker
2415
+ * @param message Issue message for a value in another format
2416
+ * @param valid Checks the value
2417
+ * @returns Input field for a picker's value
2418
+ */
2419
+ static #picked<T extends NonNullable<Field.Type>>(
2420
+ type: T,
2421
+ message: string,
2422
+ valid: (value: string) => boolean,
2423
+ ): Field.Instance<string, "input", T> {
2424
+ return Field.#input({ type }).refine(valid, message);
2425
+ }
2426
+
1521
2427
  /**
1522
2428
  * @returns Text input field
1523
2429
  */
@@ -1550,7 +2456,9 @@ export class Field {
1550
2456
  * @returns Color input field
1551
2457
  */
1552
2458
  static color(): Field.Instance<string, "input", "color"> {
1553
- return Field.#input({ type: "color" });
2459
+ return Field.#picked("color", "Enter a color as #rrggbb", (value) =>
2460
+ /^#[0-9a-f]{6}$/i.test(value),
2461
+ );
1554
2462
  }
1555
2463
 
1556
2464
  /**
@@ -1564,35 +2472,54 @@ export class Field {
1564
2472
  * @returns Date input field
1565
2473
  */
1566
2474
  static date(): Field.Instance<string, "input", "date"> {
1567
- return Field.#input({ type: "date" });
2475
+ return Field.#picked("date", "Enter a date as YYYY-MM-DD", (value) =>
2476
+ Field.#day(value),
2477
+ );
1568
2478
  }
1569
2479
 
1570
2480
  /**
1571
2481
  * @returns Datetime input field
1572
2482
  */
1573
2483
  static datetime(): Field.Instance<string, "input", "datetime-local"> {
1574
- return Field.#input({ type: "datetime-local" });
2484
+ return Field.#picked(
2485
+ "datetime-local",
2486
+ "Enter a date and time as YYYY-MM-DDTHH:mm",
2487
+ (value) => {
2488
+ const [day, time, more] = value.split("T");
2489
+ return (
2490
+ more === undefined &&
2491
+ Field.#day(day!) &&
2492
+ Field.#clock.test(time ?? "")
2493
+ );
2494
+ },
2495
+ );
1575
2496
  }
1576
2497
 
1577
2498
  /**
1578
2499
  * @returns Month input field
1579
2500
  */
1580
2501
  static month(): Field.Instance<string, "input", "month"> {
1581
- return Field.#input({ type: "month" });
2502
+ return Field.#picked("month", "Enter a month as YYYY-MM", (value) =>
2503
+ /^\d{4}-(0[1-9]|1[0-2])$/.test(value),
2504
+ );
1582
2505
  }
1583
2506
 
1584
2507
  /**
1585
2508
  * @returns Week input field
1586
2509
  */
1587
2510
  static week(): Field.Instance<string, "input", "week"> {
1588
- return Field.#input({ type: "week" });
2511
+ return Field.#picked("week", "Enter a week as YYYY-Www", (value) =>
2512
+ /^\d{4}-W(0[1-9]|[1-4]\d|5[0-3])$/.test(value),
2513
+ );
1589
2514
  }
1590
2515
 
1591
2516
  /**
1592
2517
  * @returns Time input field
1593
2518
  */
1594
2519
  static time(): Field.Instance<string, "input", "time"> {
1595
- return Field.#input({ type: "time" });
2520
+ return Field.#picked("time", "Enter a time as HH:mm", (value) =>
2521
+ Field.#clock.test(value),
2522
+ );
1596
2523
  }
1597
2524
 
1598
2525
  /**
@@ -1627,10 +2554,11 @@ export class Field {
1627
2554
  // that would keep `Field` in bundles that only use `Form`
1628
2555
  normalizers.add(Field.#toNumber);
1629
2556
 
1630
- return new FieldSchema(
2557
+ return new FieldSchema<number, "input", T>(
1631
2558
  { props },
1632
- Schema.number(required).preprocess(Field.#toNumber),
1633
- );
2559
+ // text, such as an agent's, is not a field left empty
2560
+ { type: "number", message: numeric, missing: required },
2561
+ ).preprocess(Field.#toNumber);
1634
2562
  }
1635
2563
 
1636
2564
  /**
@@ -1697,12 +2625,26 @@ export class Field {
1697
2625
  * @returns Fixed choices, and the schema that checks one, when given a list
1698
2626
  */
1699
2627
  static #choices<V extends string>(
1700
- options: readonly [V, ...V[]] | Schema<V>,
1701
- ): [options: readonly V[], choice: Schema<V>] {
1702
- return options instanceof Schema
1703
- ? // given to `Field` or `component` as the form renders
1704
- [[], options]
1705
- : [options, Schema.enum(options, choose)];
2628
+ options: Field.Choices<V> | Schema<V>,
2629
+ ): Pick<Field.Config<readonly [V, ...V[]]>, "options" | "labels"> & {
2630
+ choice: Schema<V>;
2631
+ } {
2632
+ // given to `Field` or `component` as the form renders
2633
+ if (options instanceof Schema)
2634
+ return {
2635
+ options: [] as unknown as readonly [V, ...V[]],
2636
+ choice: options,
2637
+ };
2638
+
2639
+ const labels = Array.isArray(options)
2640
+ ? undefined
2641
+ : (options as Readonly<Record<V, string>>);
2642
+ const values = (labels ? Object.keys(labels) : options) as unknown as [
2643
+ V,
2644
+ ...V[],
2645
+ ];
2646
+
2647
+ return { options: values, labels, choice: Schema.enum(values, choose) };
1706
2648
  }
1707
2649
 
1708
2650
  /**
@@ -1715,36 +2657,35 @@ export class Field {
1715
2657
  * ```
1716
2658
  *
1717
2659
  * @template V Value type
1718
- * @param options Checkbox options, or a schema for each one
2660
+ * @param options Checkbox options, an object of each one's label by its
2661
+ * value, or a schema for each one
1719
2662
  * @returns Checkbox group input field
1720
2663
  */
1721
2664
  static checkboxes<const V extends string>(
1722
- options: readonly [V, ...V[]] | Schema<V>,
2665
+ options: Field.Choices<V> | Schema<V>,
1723
2666
  ): Field.Instance<V[], "input", "checkbox", readonly [V, ...V[]]> {
1724
- const [values, choice] = Field.#choices(options);
2667
+ const { choice, ...config } = Field.#choices(options);
1725
2668
 
1726
2669
  return new FieldSchema(
1727
- { options: values as readonly [V, ...V[]], props: { type: "checkbox" } },
2670
+ { ...config, props: { type: "checkbox" } },
1728
2671
  Schema.array(choice, choose),
1729
2672
  readMany,
1730
- values.length || Infinity,
2673
+ config.options!.length || Infinity,
1731
2674
  );
1732
2675
  }
1733
2676
 
1734
2677
  /**
1735
2678
  * @template V Value type
1736
- * @param options Radio button options, or a schema for the one chosen
2679
+ * @param options Radio button options, an object of each one's label by
2680
+ * its value, or a schema for the one chosen
1737
2681
  * @returns Radio group input field
1738
2682
  */
1739
2683
  static radio<const V extends string>(
1740
- options: readonly [V, ...V[]] | Schema<V>,
2684
+ options: Field.Choices<V> | Schema<V>,
1741
2685
  ): Field.Instance<V, "input", "radio", readonly [V, ...V[]]> {
1742
- const [values, choice] = Field.#choices(options);
2686
+ const { choice, ...config } = Field.#choices(options);
1743
2687
 
1744
- return new FieldSchema(
1745
- { options: values as readonly [V, ...V[]], props: { type: "radio" } },
1746
- choice,
1747
- );
2688
+ return new FieldSchema({ ...config, props: { type: "radio" } }, choice);
1748
2689
  }
1749
2690
 
1750
2691
  /**
@@ -1754,19 +2695,57 @@ export class Field {
1754
2695
  return new FieldSchema({ tag: "textarea" }, Schema.string(required));
1755
2696
  }
1756
2697
 
2698
+ /**
2699
+ * A list of items in order, where an item may repeat: each is one field,
2700
+ * or several by name. People fill a row for each item, and agents send an
2701
+ * array. A row left empty is left out, and the list needs one item unless
2702
+ * the field is made optional after. `min()` and `max()` count its items.
2703
+ *
2704
+ * ```tsx
2705
+ * Field.list(Field.select(Schema.string().uuid())); // string[]
2706
+ * Field.list({ amount: Field.number(), name: Field.text() }); // { amount, name }[]
2707
+ * Field.list(Field.select(id)).max(7).control({ rows: 7 }); // a week's dinners
2708
+ * ```
2709
+ *
2710
+ * @template I Item type
2711
+ * @param item What each item is: a field, or fields by name
2712
+ * @returns List field whose value is an array of its items
2713
+ */
2714
+ static list<I extends Field.Item>(
2715
+ item: I,
2716
+ ): Field.Instance<
2717
+ Field.Item.Output<I>[],
2718
+ "fieldset",
2719
+ Field.Type,
2720
+ undefined,
2721
+ undefined,
2722
+ I
2723
+ > {
2724
+ return new FieldSchema(
2725
+ { tag: "fieldset", item },
2726
+ Schema.array(
2727
+ field(item)
2728
+ ? item
2729
+ : Schema.object(item as Readonly<Record<string, Field.Cell>>),
2730
+ required,
2731
+ ),
2732
+ FieldSchema.items(item),
2733
+ Infinity,
2734
+ );
2735
+ }
2736
+
1757
2737
  /**
1758
2738
  * @template V Value type
1759
- * @param options Select options, or a schema for the one chosen
2739
+ * @param options Select options, an object of each one's label by its
2740
+ * value, or a schema for the one chosen. One that may be left empty
2741
+ * starts with an empty choice, whose text is its `placeholder`.
1760
2742
  * @returns Select field
1761
2743
  */
1762
2744
  static select<const V extends string>(
1763
- options: readonly [V, ...V[]] | Schema<V>,
2745
+ options: Field.Choices<V> | Schema<V>,
1764
2746
  ): Field.Instance<V, "select", Field.Type, readonly [V, ...V[]]> {
1765
- const [values, choice] = Field.#choices(options);
2747
+ const { choice, ...config } = Field.#choices(options);
1766
2748
 
1767
- return new FieldSchema(
1768
- { tag: "select", options: values as readonly [V, ...V[]] },
1769
- choice,
1770
- );
2749
+ return new FieldSchema({ ...config, tag: "select" }, choice);
1771
2750
  }
1772
2751
  }