001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.console.widgets;
018
019import static org.apache.juneau.commons.utils.Shorts.*;
020
021import java.time.*;
022import java.time.format.*;
023import java.util.*;
024import java.util.regex.*;
025
026import org.apache.juneau.commons.bean.*;
027
028/**
029 * The declarative source of a row-action modal's input form (the form half of a {@code present=dialog} action).
030 *
031 * <h2 class='section'>A widget contract driven by a view-module runtime</h2>
032 * <p>
033 * Like {@link ModalDef}, this is a general widget contract that lives in this module while the browser runtime that
034 * paints it ships with the rich-view module.  Nothing here depends on that module.
035 *
036 * <h2 class='section'>Flat or sectioned</h2>
037 * <p>
038 * A form declares either a flat {@link #fields} list or an ordered list of {@link Section}s, never both: the flat list
039 * <i>is</i> the single-section case.  Sections render as a ribbon-format strip above one visible pane; they are a
040 * layout of one dialog, not a stack of dialogs, so they cost nothing against the runtime's modal-depth cap.
041 *
042 * <h2 class='section'>Typed inputs, not markup</h2>
043 * <p>
044 * The client paints {@link #fields} as native {@code <input>} / {@code <textarea>} / {@code <select>} /
045 * {@code <button>} elements via {@code createElement}.  Labels and option text use {@code textContent}; prefills use
046 * {@code .value} / {@code .checked}.  The runtime never assigns {@code innerHTML} from this payload.  Only the
047 * types on the allowlist ({@code text}, {@code textarea}, {@code password}, {@code checkbox}, {@code toggle}, {@code select},
048 * {@code date}, {@code action}) are legal &mdash; that is the XSS bound: hostile prefill cannot become an element.
049 * </p>
050 * <p>
051 * {@link #template} may name a server-side template for authors.  It is <b>not</b> a client HTML sink; the
052 * shipped {@code juneau-views.js} ignores it.
053 * </p>
054 *
055 * <h2 class='section'>Per-widget contract version (fail-loud when a form is present)</h2>
056 * <p>
057 * This bean {@link Widget#validate() validates} fail-closed and carries an instance {@link #contractVersion}.  The
058 * version defaults to {@link #CONTRACT_VERSION} from the instant the form is constructed &mdash; a raw
059 * builder no longer leaks an unversioned form regardless of whether {@link #checked()} is invoked.  The client
060 * refuses to open a form-bearing dialog whose version does not match the one its runtime bakes in.
061 * </p>
062 * <p>
063 * This constant moves in <b>lockstep</b> with {@link ModalDef#CONTRACT_VERSION} and the runtime's baked-in literal,
064 * because the runtime compares one literal against both the modal's and the form's version.  Bumping any two of the
065 * three makes every form-bearing dialog refuse to open.
066 * </p>
067 *
068 * <h2 class='section'>Example:</h2>
069 * <p class='bjava'>
070 *    FormDef <jv>form</jv> = FormDef.<jsm>create</jsm>()
071 *       .field(FormDef.Input.<jsm>of</jsm>(<js>"resolution"</js>, <js>"Resolution comment"</js>, <js>"textarea"</js>)
072 *          .required()
073 *          .value(<js>""</js>));
074 * </p>
075 *
076 * <h2 class='section'>See Also:</h2>
077 * <ul>
078 *    <li class='jc'>{@link ModalDef}
079 *    <li class='jc'>{@link ActionRef}
080 * </ul>
081 *
082 * @since 10.0.0
083 */
084@BeanType(properties="contractVersion,template,fields,sections")
085@SuppressWarnings({
086   "java:S1845" // Fluent-builder setters intentionally mirror field names (Juneau DSL convention).
087})
088public class FormDef implements Widget {
089
090   /**
091    * The frozen form contract version.  Bumped only on a breaking wire change to this form contract.
092    *
093    * <p>
094    * Bumped to 3 when the date input type joined the allowlist.
095    */
096   public static final String CONTRACT_VERSION = "3";
097
098   /** The cap on the length of an author-supplied {@link Input#pattern} (ReDoS defense-in-depth). */
099   static final int PATTERN_MAX_LENGTH = 256;
100
101   /** The complete set of legal {@link Input#type} tokens. */
102   static final Set<String> INPUT_TYPES = Set.of("text", "textarea", "password", "checkbox", "toggle", "select", "date", "action");
103
104   /**
105    * A single typed form input painted client-side with {@code createElement} (never {@code innerHTML}).
106    *
107    * @since 10.0.0
108    */
109   @BeanType(properties="name,label,type,required,value,options,pattern,maxLength,help,actionId")
110   public static class Input {
111
112      /**
113       * A single {@code select} option: a submit value and its visible label.
114       *
115       * @since 10.0.0
116       */
117      @BeanType(properties="value,label")
118      public static class Option {
119
120         /** The submit value for this option.  Must not be <jk>null</jk>. */
121         public String value;
122
123         /** The visible option text, painted with {@code textContent}.  Must not be blank. */
124         public String label;
125
126         /**
127          * Creates a select option.
128          *
129          * @param value The submit value.  Must not be <jk>null</jk>.
130          * @param label The visible option text.  Must not be <jk>null</jk> or blank.
131          * @return A new {@link Option}.
132          * @throws IllegalArgumentException If {@code value} is <jk>null</jk> or {@code label} is blank.
133          */
134         public static Option of(String value, String label) {
135            if (value == null)
136               throw iaex("FormDef.Input.Option value must not be null.");
137            if (ib(label))
138               throw iaex("FormDef.Input.Option label must not be null or blank.");
139            var o = new Option();
140            o.value = value;
141            o.label = label;
142            return o;
143         }
144      }
145
146      /** The submit-body key for this field (e.g. {@code resolution}). */
147      public String name;
148
149      /** The label shown next to the control. */
150      public String label;
151
152      /** One of {@code text}, {@code textarea}, {@code password}, {@code checkbox}, {@code toggle}, {@code select}, {@code date}, {@code action}. */
153      public String type;
154
155      /** When {@link Boolean#TRUE}, the control is required.  Omitted from the wire otherwise. */
156      public Boolean required;
157
158      /** Optional prefill, applied via {@code .value} / {@code .checked} (never {@code innerHTML}). */
159      public String value;
160
161      /** The options for a {@code select} field, in display order; omitted from the wire otherwise. */
162      public List<Option> options;
163
164      /** An optional client validation regexp for {@code text}/{@code textarea}; omitted from the wire otherwise. */
165      public String pattern;
166
167      /** An optional client max-length for {@code text}/{@code textarea}; omitted from the wire otherwise. */
168      public Integer maxLength;
169
170      /** An optional help hint painted with {@code textContent}; omitted from the wire otherwise. */
171      public String help;
172
173      /**
174       * The enclosing view's row-action id an {@code action} button opens; omitted from the wire otherwise.  See
175       * {@link ActionRef} for the typed reference the builder accepts.
176       */
177      public String actionId;
178
179      /**
180       * Creates a typed form input.
181       *
182       * @param name The submit-body key (also the DOM identity for an {@code action} field).  Must not be
183       *    <jk>null</jk> or blank.
184       * @param label The visible label.  Must not be <jk>null</jk> or blank.
185       * @param type One of {@code text}, {@code textarea}, {@code password}, {@code checkbox}, {@code toggle}, {@code select},
186       *    {@code date}, {@code action}.  <jk>null</jk> or blank defaults to {@code text}.
187       * @return A new {@link Input}.
188       * @throws IllegalArgumentException If {@code name} or {@code label} is blank, or {@code type} is not an
189       *    allowed token.
190       */
191      public static Input of(String name, String label, String type) {
192         if (ib(name))
193            throw iaex("FormDef.Input name must not be null or blank.");
194         if (ib(label))
195            throw iaex("FormDef.Input label must not be null or blank.");
196         var t = (ib(type)) ? "text" : type;
197         if (! INPUT_TYPES.contains(t))
198            throw iaex("FormDef.Input type must be one of text, textarea, password, checkbox, toggle, select, date, action, not '%s'.", t);
199         var i = new Input();
200         i.name = name;
201         i.label = label;
202         i.type = t;
203         return i;
204      }
205
206      /**
207       * Marks this input required.
208       *
209       * @return This object.
210       */
211      public Input required() {
212         required = Boolean.TRUE;
213         return this;
214      }
215
216      /**
217       * Sets whether this input is required.
218       *
219       * @param value <jk>true</jk> to require a value; <jk>false</jk> omits the flag from the wire.
220       * @return This object.
221       */
222      public Input required(boolean value) {
223         required = value ? Boolean.TRUE : null;
224         return this;
225      }
226
227      /**
228       * Sets the optional prefill.
229       *
230       * @param value The prefill.  Can be <jk>null</jk> to unset.
231       * @return This object.
232       */
233      public Input value(String value) {
234         this.value = value;
235         return this;
236      }
237
238      /**
239       * Sets the {@code select} options (replacing any existing).
240       *
241       * @param value The options.  Must not be <jk>null</jk>.
242       * @return This object.
243       * @throws IllegalArgumentException If {@code value} is <jk>null</jk> or contains a <jk>null</jk> entry.
244       */
245      public Input options(Option... value) {
246         if (value == null)
247            throw iaex("FormDef.Input options must not be null.");
248         var l = new ArrayList<Option>();
249         for (var o : value) {
250            if (o == null)
251               throw iaex("FormDef.Input option must not be null.");
252            l.add(o);
253         }
254         options = l;
255         return this;
256      }
257
258      /**
259       * Adds one {@code select} option.
260       *
261       * @param value The submit value.  Must not be <jk>null</jk>.
262       * @param label The visible option text.  Must not be <jk>null</jk> or blank.
263       * @return This object.
264       * @throws IllegalArgumentException If {@code value} is <jk>null</jk> or {@code label} is blank.
265       */
266      public Input option(String value, String label) {
267         if (options == null)
268            options = new ArrayList<>();
269         options.add(Option.of(value, label));
270         return this;
271      }
272
273      /**
274       * Sets the client validation regexp ({@code text}/{@code textarea} only).
275       *
276       * @param value The pattern.  Can be <jk>null</jk> to unset.
277       * @return This object.
278       */
279      public Input pattern(String value) {
280         pattern = value;
281         return this;
282      }
283
284      /**
285       * Sets the client max-length ({@code text}/{@code textarea} only).
286       *
287       * @param value The max length.  Must be {@code > 0}.
288       * @return This object.
289       */
290      public Input maxLength(int value) {
291         maxLength = value;
292         return this;
293      }
294
295      /**
296       * Sets the help hint (painted with {@code textContent}).
297       *
298       * @param value The hint.  Can be <jk>null</jk> to unset.
299       * @return This object.
300       */
301      public Input help(String value) {
302         help = value;
303         return this;
304      }
305
306      /**
307       * Sets the enclosing view's row-action id this {@code action} button opens.
308       *
309       * @param value The action id.  Can be <jk>null</jk> to unset.
310       * @return This object.
311       */
312      public Input actionId(String value) {
313         actionId = value;
314         return this;
315      }
316
317      /**
318       * Sets the {@code action} target from an {@link ActionRef} (stores {@link ActionRef#id}).
319       *
320       * @param value The action reference.  Must not be <jk>null</jk>.
321       * @return This object.
322       * @throws IllegalArgumentException If {@code value} is <jk>null</jk>.
323       */
324      public Input action(ActionRef value) {
325         if (value == null)
326            throw iaex("FormDef.Input action must not be null.");
327         actionId = value.id;
328         return this;
329      }
330
331      /**
332       * Fail-closed per-input validation (called from {@link FormDef#validate()}).
333       *
334       * @throws IllegalArgumentException If this input is not well-formed.
335       */
336      void validate() {
337         if (ib(name))
338            throw iaex("FormDef.Input name must not be null or blank.");
339         var t = resolveType();
340         var isAction = eq(t, "action");
341         var isTextual = eqa(t, "text", "textarea");
342
343         validateOptions(eq(t, "select"));
344         validateTextualOnlyFields(isTextual);
345         validatePattern();
346         validatePasswordValue();
347         validateDateValue(eq(t, "date"));
348         validateActionField(isAction);
349      }
350
351      /** Resolves and validates {@link #type} (blank defaults to {@code text}). */
352      private String resolveType() {
353         var t = (ib(type)) ? "text" : type;
354         if (! INPUT_TYPES.contains(t))
355            throw iaex("FormDef.Input '%s' type must be one of text, textarea, password, checkbox, toggle, select, date, action, not '%s'.", name, t);
356         return t;
357      }
358
359      /** Validates the {@code select}-only {@link #options}/{@link #value} pairing. */
360      private void validateOptions(boolean isSelect) {
361         if (! isSelect) {
362            if (options != null)
363               throw iaex("FormDef.Input '%s' options are only allowed on a select field.", name);
364            return;
365         }
366         if (ie(options))
367            throw iaex("FormDef.Input '%s' select must declare at least one option.", name);
368         var values = new HashSet<String>();
369         for (var o : options) {
370            if (o == null)
371               throw iaex("FormDef.Input '%s' select option must not be null.", name);
372            if (o.value == null)
373               throw iaex("FormDef.Input '%s' select option value must not be null.", name);
374            if (o.label == null || o.label.isBlank())
375               throw iaex("FormDef.Input '%s' select option label must not be null or blank.", name);
376            values.add(o.value);
377         }
378         if (value != null && ! values.contains(value))
379            throw iaex("FormDef.Input '%s' select value '%s' does not match any option.", name, value);
380      }
381
382      /** Validates that {@link #pattern}/{@link #maxLength} are only declared on a textual field. */
383      private void validateTextualOnlyFields(boolean isTextual) {
384         if (isTextual)
385            return;
386         if (pattern != null)
387            throw iaex("FormDef.Input '%s' pattern is only allowed on a text/textarea field.", name);
388         if (maxLength != null)
389            throw iaex("FormDef.Input '%s' maxLength is only allowed on a text/textarea field.", name);
390      }
391
392      /** A {@code password} field is write-only: a {@link #value} would be sent to the client, so it is rejected. */
393      private void validatePasswordValue() {
394         if (eq(type, "password") && value != null)
395            throw iaex("FormDef.Input '%s' value is not allowed on a password field.", name);
396      }
397
398      /** A {@code date} field's value, when present, is an ISO calendar date. */
399      private void validateDateValue(boolean isDate) {
400         if (! isDate || value == null)
401            return;
402         try {
403            LocalDate.parse(value);
404         } catch (DateTimeParseException e) {
405            throw iaex("FormDef.Input '%s' value '%s' must be an ISO date (yyyy-MM-dd).", name, value);
406         }
407      }
408
409      /** Validates {@link #pattern} compiles and {@link #maxLength} is positive. */
410      private void validatePattern() {
411         if (pattern != null) {
412            if (pattern.length() > PATTERN_MAX_LENGTH)
413               throw iaex("FormDef.Input '%s' pattern must be at most %s characters.", name, PATTERN_MAX_LENGTH);
414            try {
415               Pattern.compile(pattern);
416            } catch (PatternSyntaxException e) {
417               throw iaex("FormDef.Input '%s' pattern does not compile: %s", name, e.getMessage());
418            }
419         }
420         if (maxLength != null && maxLength <= 0)
421            throw iaex("FormDef.Input '%s' maxLength must be > 0.", name);
422      }
423
424      /** Validates the {@code action}-only {@link #actionId}. */
425      private void validateActionField(boolean isAction) {
426         if (isAction && (ib(actionId)))
427            throw iaex("FormDef.Input '%s' action must declare an actionId.", name);
428         if (! isAction && actionId != null)
429            throw iaex("FormDef.Input '%s' actionId is only allowed on an action field.", name);
430      }
431   }
432
433   /**
434    * One labelled group of inputs inside a sectioned form: the multi-page dialog shape.
435    *
436    * <p>
437    * The client paints an ordered list of these as a <b>ribbon</b>-format strip above the form body, one visible pane
438    * at a time.  Switching sections is visibility only &mdash; nothing is refetched and nothing is re-created, which
439    * is why a value typed into one section survives a trip through another, and why an inline validation error stays
440    * attached to the control that owns it rather than to whichever section happens to be showing.
441    *
442    * <p>
443    * A sectioned form is <b>not</b> a stack of dialogs.  The strip opens no layer of its own, so a sectioned dialog
444    * consumes exactly one entry of the runtime's modal-depth budget, the same as a flat one.
445    *
446    * @since 10.0.0
447    */
448   @BeanType(properties="id,label,fields")
449   public static class Section {
450
451      /** The section's stable id, used as the strip tab's identity.  Must not be blank, and must be unique in the form. */
452      public String id;
453
454      /** The visible tab label, painted with {@code textContent}.  Must not be blank. */
455      public String label;
456
457      /** This section's typed inputs in display order.  Must declare at least one. */
458      public List<Input> fields;
459
460      /**
461       * Creates an empty section (add {@link #field(Input) fields}).
462       *
463       * @param id The section's stable id.  Must not be <jk>null</jk> or blank.
464       * @param label The visible tab label.  Must not be <jk>null</jk> or blank.
465       * @return A new {@link Section}.
466       * @throws IllegalArgumentException If {@code id} or {@code label} is <jk>null</jk> or blank.
467       */
468      public static Section of(String id, String label) {
469         if (ib(id))
470            throw iaex("FormDef.Section id must not be null or blank.");
471         if (ib(label))
472            throw iaex("FormDef.Section label must not be null or blank.");
473         var s = new Section();
474         s.id = id;
475         s.label = label;
476         return s;
477      }
478
479      /**
480       * Adds one typed input to this section.
481       *
482       * @param value The input.  Must not be <jk>null</jk>.
483       * @return This object.
484       * @throws IllegalArgumentException If {@code value} is <jk>null</jk>.
485       */
486      public Section field(Input value) {
487         if (value == null)
488            throw iaex("FormDef.Section field must not be null.");
489         if (fields == null)
490            fields = l();
491         fields.add(value);
492         return this;
493      }
494
495      /**
496       * Fail-closed per-section validation (called from {@link FormDef#validate()}).
497       *
498       * @throws IllegalArgumentException If this section is not well-formed.
499       */
500      void validate() {
501         if (ib(id))
502            throw iaex("FormDef.Section id must not be null or blank.");
503         if (ib(label))
504            throw iaex("FormDef.Section '%s' label must not be null or blank.", id);
505         if (ie(fields))
506            throw iaex("FormDef.Section '%s' must declare at least one field.", id);
507         for (var f : fields) {
508            if (f == null)
509               throw iaex("FormDef.Section '%s' field must not be null.", id);
510            f.validate();
511         }
512      }
513   }
514
515   /**
516    * The frozen form contract version discriminator.
517    *
518    * <p>
519    * Defaults to {@link #CONTRACT_VERSION} from the instant this form is constructed, independent of
520    * {@link #checked()}.  Guaranteed <b>present</b> is not the same as guaranteed <b>valid</b>: presence
521    * is this field's whole job, structural well-formedness is {@link #validate()}'s (see {@link #checked()}).
522    */
523   public String contractVersion = CONTRACT_VERSION;
524
525   /** Optional FreeMarker template reference for server authors; ignored by the client. */
526   public String template;
527
528   /**
529    * Typed inputs in display order for a flat, single-section form; omitted from the wire when none are declared.
530    *
531    * <p>
532    * Mutually exclusive with {@link #sections} &mdash; a flat {@code fields} list <i>is</i> the single-section case,
533    * so declaring both is an authoring error {@link #validate()} rejects rather than silently picking one.
534    */
535   public List<Input> fields;
536
537   /**
538    * Optional ordered sections for a multi-section form; omitted from the wire when none are declared.
539    *
540    * <p>
541    * Mutually exclusive with {@link #fields} (see that field).  A single-element {@code sections} list is legal but
542    * pointless: it renders a one-tab strip where a flat {@code fields} list would render none.
543    */
544   public List<Section> sections;
545
546   /**
547    * Starts an empty form (add {@link #field(Input) fields} and/or a {@link #template(String) template}).
548    *
549    * @return A new {@link FormDef}.
550    */
551   public static FormDef create() {
552      return new FormDef();
553   }
554
555   /**
556    * Creates a form sourced from the specified FreeMarker template reference.
557    *
558    * @param template The template reference (a resolvable URL/name).  Must not be <jk>null</jk> or blank.
559    * @return A new {@link FormDef}.
560    * @throws IllegalArgumentException If {@code template} is <jk>null</jk> or blank.
561    */
562   public static FormDef ofTemplate(String template) {
563      return create().template(template);
564   }
565
566   /**
567    * Sets the optional server-author template reference.  The client never treats this as HTML.
568    *
569    * @param value The template reference.  Must not be <jk>null</jk> or blank.
570    * @return This object.
571    * @throws IllegalArgumentException If {@code value} is <jk>null</jk> or blank.
572    */
573   public FormDef template(String value) {
574      if (ib(value))
575         throw iaex("FormDef template must not be null or blank.");
576      template = value;
577      return this;
578   }
579
580   /**
581    * Adds one typed input field.
582    *
583    * @param value The input.  Must not be <jk>null</jk>.
584    * @return This object.
585    * @throws IllegalArgumentException If {@code value} is <jk>null</jk>.
586    */
587   public FormDef field(Input value) {
588      if (value == null)
589         throw iaex("FormDef field must not be null.");
590      if (fields == null)
591         fields = l();
592      fields.add(value);
593      return this;
594   }
595
596   /**
597    * Adds one section, making this a multi-section form.
598    *
599    * @param value The section.  Must not be <jk>null</jk>.
600    * @return This object.
601    * @throws IllegalArgumentException If {@code value} is <jk>null</jk>.
602    */
603   public FormDef section(Section value) {
604      if (value == null)
605         throw iaex("FormDef section must not be null.");
606      if (sections == null)
607         sections = l();
608      sections.add(value);
609      return this;
610   }
611
612   /**
613    * Fail-closed bean validation.
614    *
615    * <p>
616    * Does <b>not</b> require {@link #contractVersion} to already be set &mdash; a raw-built form validated directly
617    * must not false-refuse on a null version.  A form with neither {@link #fields} nor {@link #sections} is a no-op
618    * (a template-only / fieldless form is a shipped shape).
619    *
620    * <p>
621    * Field names are unique across the <b>whole</b> form, not per section: every control shares one submit body and
622    * one dialog-scoped element-id namespace, so two sections declaring the same name would collide in both.
623    *
624    * @throws IllegalArgumentException If both {@link #fields} and {@link #sections} are declared, if {@link #sections}
625    *    is declared but empty, if two sections share an {@code id}, or if any field is not well-formed or two fields
626    *    share a {@code name}.
627    */
628   @Override
629   public void validate() {
630      if (fields != null && sections != null)
631         throw iaex("FormDef declares both fields and sections; they are mutually exclusive (a flat fields list is the single-section case).");
632      if (sections != null) {
633         validateSections();
634         return;
635      }
636      validateFlatFields();
637   }
638
639   /** Validates the sectioned-form shape: at least one section, unique section ids, unique field names overall. */
640   private void validateSections() {
641      if (sections.isEmpty())
642         throw iaex("FormDef sections must declare at least one section.");
643      var ids = new HashSet<String>();
644      var names = new HashSet<String>();
645      for (var s : sections) {
646         if (s == null)
647            throw iaex("FormDef section must not be null.");
648         s.validate();
649         if (! ids.add(s.id))
650            throw iaex("FormDef duplicate section id '%s'.", s.id);
651         for (var f : s.fields)
652            if (! names.add(f.name))
653               throw iaex("FormDef duplicate field name '%s'.", f.name);
654      }
655   }
656
657   /** Validates the flat-form shape: each field is well-formed, and field names are unique. */
658   private void validateFlatFields() {
659      if (fields == null)
660         return;
661      var names = new HashSet<String>();
662      for (var f : fields) {
663         if (f == null)
664            throw iaex("FormDef field must not be null.");
665         f.validate();
666         if (! names.add(f.name))
667            throw iaex("FormDef duplicate field name '%s'.", f.name);
668      }
669   }
670
671   /**
672    * The serving-path hook: re-stamps {@link #CONTRACT_VERSION} (already set by construction; this
673    * repairs a version a caller explicitly cleared) then {@link #validate() validates}.
674    *
675    * <p>
676    * {@link #contractVersion} no longer depends on this being called. Structural validation
677    * no longer depends on it either for a form served over REST: nested inside a returned {@link ModalDef},
678    * this form is reached by
679    * {@link WidgetsMixin.WidgetValidationProcessor
680    * WidgetsMixin.WidgetValidationProcessor}'s call to {@link ModalDef#validate()}, which recurses into this
681    * bean's own {@link #validate()}, fail-closed with a 500, whether or not the producing endpoint called
682    * {@link ModalDef#checked()}. This method (via {@link ModalDef#checked()}) remains the only fail-closed
683    * structural {@link #validate() validation} a <b>non-REST</b> producer has &mdash; a direct
684    * {@code Json.of(...)} serialization, for instance &mdash; and calling it for a REST-bound form stays safe
685    * (validation is idempotent) even though it is no longer strictly required there.
686    *
687    * @return This object.
688    * @throws IllegalArgumentException If this form is not well-formed.
689    */
690   public FormDef checked() {
691      contractVersion = CONTRACT_VERSION;
692      validate();
693      return this;
694   }
695}