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.util.*;
022
023import org.apache.juneau.commons.bean.*;
024
025/**
026 * The declarative modal (dialog) a {@code present=dialog} row action opens — the payload the
027 * <b>modal-open confirmation fetch</b> returns.
028 *
029 * <h2 class='section'>A widget contract driven by a view-module runtime</h2>
030 * <p>
031 * This bean is a general widget contract and lives in this module, but the browser runtime that paints it ships with
032 * the rich-view module (it is part of that module's {@code juneau-views.js} monolith, which is not split apart here).
033 * So a page that opens one of these dialogs loads the view runtime; nothing in this module reaches back to it.
034 *
035 * <h2 class='section'>Safe-by-construction confirmation body</h2>
036 * <p>
037 * The confirmation body is <b>typed structured fields</b> ({@link #fields}: incident #, title, service, current
038 * status &mdash; the confirmation field set), server-rendered against the current, authoritative record and
039 * bound to the target identifier.  The {@code juneau-views.js} runtime paints each field's value with
040 * {@code textContent} &mdash; NEVER {@code innerHTML}, never raw markup, never the non-table panel-content sink.
041 * Live/remote data is attacker-influenceable (anyone who can title an incident or post in a watched thread) and this
042 * origin holds the CSRF token, so an HTML sink here would be stored-XSS&nbsp;&rarr;&nbsp;token-theft&nbsp;&rarr;
043 * arbitrary-write; typed fields painted with {@code textContent} close that off by construction.
044 *
045 * <h2 class='section'>The idempotency key rides here</h2>
046 * <p>
047 * {@link #idempotencyKey} is a server-minted key value, minted at modal-open and bound to
048 * {@code (action, targetId)}.  The runtime carries it verbatim on the submit so a double-click / re-submit / browser
049 * retry all collapse to one effect; the server checks that binding on submit and answers a mismatch with a named
050 * refusal, never a replayed success.  The minting/binding helper itself is a table-and-row-action concern and stays
051 * in the rich-view module, which is why this field is a plain {@code String} rather than that helper's type.
052 *
053 * <h2 class='section'>{@link #selfTargeted} &mdash; the opt-in for a key that targets itself</h2>
054 * <p>
055 * A dialog opened where there is <b>no row</b> (a ribbon-hosted dialog whose submit creates the thing it is about)
056 * has no artifact id to bind its key to at modal-open.  The rich-view module's key helper can mint a key whose
057 * bound target <i>is its own value</i>; {@link #selfTargeted} is the signal that tells the runtime to send that
058 * value as the submitted target instead of the row's id.
059 * <p>
060 * The signal has to ride on this bean, because it cannot be inferred from the wire: {@link #idempotencyKey} is an
061 * opaque string either way, indistinguishable in shape from an artifact-bound key's value.  It is therefore an
062 * explicit, additive, per-dialog opt-in &mdash; <b>not</b> a blanket runtime precedence rule.  A dialog that leaves
063 * this unset behaves exactly as it does today, <i>including</i> one that sets {@link #idempotencyKey} for an
064 * artifact-bound reason: it keeps sending the row's real id, which is what its own mint call bound.
065 * <p>
066 * Set it <b>only</b> on a modal whose key came from the self-targeted mint helper.  Setting it on a modal carrying
067 * an artifact-bound key silently discards the real target and makes the server's binding check vacuous.
068 *
069 * <h2 class='section'>{@link #keepOpenOnSubmit} &mdash; the opt-in for an in-dialog result receipt</h2>
070 * <p>
071 * By default the runtime closes a dialog at confirm-click time and then submits, so every dialog is gone before its
072 * result exists.  {@link #keepOpenOnSubmit} suppresses that close, and the runtime instead paints the write's
073 * <b>result</b> into the dialog that is already open &mdash; a <i>receipt</i>.
074 * <p>
075 * A receipt host is <b>non-submittable by construction</b>, not by convention: the runtime paints it with a distinct
076 * function that creates no confirm control at all, and it refuses to paint one whose payload carries a
077 * {@link #form}.  It is reached <b>only</b> after a committed write (an
078 * {@code ActionResult} whose outcome is {@code success}), so a result host can never appear for a write that did not
079 * happen.  A follow-up read-only form source is named by that result's {@code resultForm}.
080 * <p>
081 * The opt-in has to live here rather than on the action bean, because the confirm handler must decide whether to
082 * close <i>before</i> any response exists.  A dialog synthesized from a {@code confirm} string alone (no form-source
083 * URL) therefore cannot opt in &mdash; a receipt-bearing action must serve a real {@link ModalDef}.
084 * <p>
085 * Additive, and named degradation, accepted: an older runtime ignoring this flag closes the dialog and drops the
086 * receipt.  The write still happens; the receipt is simply not shown.
087 *
088 * <h2 class='section'>{@link #childActions} &mdash; the dialog-scoped child-action catalog</h2>
089 * <p>
090 * A {@code type="action"} form input names an action id, and the runtime resolves it against the enclosing view's
091 * row-action catalog.  A <b>stacked</b> step reached from inside an already-open dialog (a Review step in a wizard)
092 * has nothing legal to resolve against there: it is not a row action, and publishing it as one would surface it in
093 * every row's action menu.  {@link #childActions} is that missing catalog, scoped to <b>one open dialog</b>.
094 * <p>
095 * Scoping is <b>structural</b>, not a flag some menu builder has to remember to filter on: this catalog rides on a
096 * per-open payload, so the row-action menu and the ribbon resolver never see it and there is no exclusion logic to
097 * rot.  Resolution precedence is likewise fail-safe: the existing row-action check runs <b>first</b> and unchanged,
098 * so a served payload can never shadow &mdash; and thereby bypass the gating of &mdash; a declared row action.
099 *
100 * <h2 class='section'>{@link #chrome} and {@link #steps} &mdash; dialog styling and a built-in wizard</h2>
101 * <p>
102 * {@link #chrome} names a dialog chrome the page script registered with the runtime; the runtime hands that chrome the
103 * freshly built dialog parts so it can restyle them.  An unregistered name is ignored and the default chrome is kept.
104 * <p>
105 * {@link #steps} turns the dialog into a wizard: the runtime shows one {@link Step} at a time with Back and Next
106 * buttons, and the last step's button is the dialog's own confirm.  Both are additive-only and omitted from the wire
107 * when unset, so neither bumps {@link #CONTRACT_VERSION}.
108 *
109 * <h2 class='section'>{@link #nav} &mdash; the inner-navigation style</h2>
110 * <p>
111 * {@link #nav} picks how the runtime draws the section strip of a {@link FormDef#sections sectioned} form:
112 * {@link #NAV_PILL} (the default) or {@link #NAV_FOLDER} (square-topped folder tabs).  A wizard needs no value here:
113 * {@link #steps} alone makes the dialog a wizard, and the runtime then draws a numbered step indicator instead of a
114 * strip.  {@link #validate()} rejects any other value; the runtime still treats an unknown one as {@link #NAV_PILL}.
115 * Additive-only and omitted from the wire when unset, so it does not bump {@link #CONTRACT_VERSION}.
116 *
117 * <h2 class='section'>Not a new row-action wire field</h2>
118 * <p>
119 * This is the response a row action's form-source URL returns, <b>not</b> a new field on the frozen row-action wire
120 * schema: the modal's declaration lives in this separately-served payload so the row-action contract stays frozen.
121 * The same reasoning is why {@link #keepOpenOnSubmit} and {@link #childActions} land here rather than on
122 * {@code RowAction} / {@code RibbonAction}, which stay frozen and untouched.
123 *
124 * <h2 class='section'>Example:</h2>
125 * <p class='bjava'>
126 *    ModalDef <jv>modal</jv> = ModalDef.<jsm>create</jsm>(<js>"Acknowledge this incident?"</js>)
127 *       .field(<js>"Incident"</js>, <jv>incidentNumber</jv>)
128 *       .field(<js>"Title"</js>, <jv>incidentTitle</jv>)
129 *       .field(<js>"Service"</js>, <jv>serviceName</jv>)
130 *       .field(<js>"Current status"</js>, <jv>currentStatus</jv>)
131 *       .form(FormDef.<jsm>ofTemplate</jsm>(<js>"servlet:/incidents/ack-form.ftl"</js>))
132 *       .idempotencyKey(<jv>keyValue</jv>);
133 * </p>
134 *
135 * <h2 class='section'>See Also:</h2>
136 * <ul>
137 *    <li class='jc'>{@link FormDef}
138 *    <li class='jc'>{@link Widget}
139 * </ul>
140 *
141 * <h2 class='section'>The third named bar-slot host</h2>
142 * <p>
143 * {@link #barSlot} is the <i>third</i> named {@link BarSlot} attachment &mdash; alongside the rich-view module's page
144 * and row-detail hosts (that module never depends on this one, so they are not linked here).  Unlike those two
145 * &mdash; Java-only fields a server-side emitter paints directly, omitted from their wire &mdash; this modal itself
146 * <b>is</b> the wire payload the modal-open confirmation fetch returns, with no separate server-rendered pass the
147 * dialog could ride into.  So this field <b>is</b> carried on the wire (additive-only: {@code null} when unset, and
148 * its presence does not bump {@link #CONTRACT_VERSION}), and the {@code juneau-views.js} runtime paints the region
149 * and its dynamic-count sidecar client-side from the JSON, the same way it already paints typed confirmation
150 * {@link #fields} and {@link #form} controls &mdash; {@code textContent} only, never {@code innerHTML}.  The dialog
151 * anchors its own region immediately after the title (the {@code ANCHOR_DIALOG_TITLE}
152 * placement in {@code juneau-views.js}), owning that placement itself rather than leaning on the shared strip builder,
153 * exactly as the row-detail host owns its own ribbon-trailing relocation.
154 *
155 * @since 10.0.0
156 */
157@BeanType(properties="contractVersion,title,fields,form,idempotencyKey,selfTargeted,barSlot,keepOpenOnSubmit,childActions,chrome,steps,nav")
158@SuppressWarnings({
159   "java:S1845", // Fluent-builder setters intentionally mirror field names (Juneau DSL convention).
160   "java:S3776" // Branching is inherent to validate() and validateChildActions(), which check many field/child-action combinations.
161})
162public class ModalDef implements Widget {
163
164   /**
165    * The frozen modal contract version.  Bumped only on a breaking wire change to this modal contract.
166    *
167    * <p>
168    * Moves in <b>lockstep</b> with {@link FormDef#CONTRACT_VERSION} and the runtime's baked-in literal: the runtime
169    * compares one literal against both this version and the nested form's, so bumping any two of the three makes
170    * every form-bearing dialog refuse to open.
171    *
172    * <p>
173    * Bumped to 3 when the date input type joined the allowlist.
174    */
175   public static final String CONTRACT_VERSION = "3";
176
177   /** The {@link Field#kind} token for an ordinary text value &mdash; the default when the field declares none. */
178   public static final String FIELD_KIND_TEXT = "text";
179
180   /** The {@link Field#kind} token for a monospaced, copyable value (an id, a URL, a generated token). */
181   public static final String FIELD_KIND_CODE = "code";
182
183   /** The {@link #nav} token for the default rounded section strip. */
184   public static final String NAV_PILL = "pill";
185
186   /** The {@link #nav} token for square-topped folder tabs over a bottom rule. */
187   public static final String NAV_FOLDER = "folder";
188
189   /**
190    * A single typed confirmation field: a label and a value, painted client-side with {@code textContent} (never
191    * {@code innerHTML}).
192    *
193    * @since 10.0.0
194    */
195   @BeanType(properties="label,value,kind")
196   public static class Field {
197
198      /** The field label shown to the user. */
199      public String label;
200
201      /** The field value, read back from the current authoritative record. */
202      public String value;
203
204      /**
205       * How this field's value is <i>displayed</i>; omitted from the wire when unset (which reads as
206       * {@link ModalDef#FIELD_KIND_TEXT text}).
207       *
208       * <p>
209       * The allowlist is exactly {@link ModalDef#FIELD_KIND_TEXT text} and {@link ModalDef#FIELD_KIND_CODE code};
210       * {@link ModalDef#validate()} rejects anything else server-side, and the runtime falls back to
211       * {@code text} for an unrecognized token rather than trusting it.
212       *
213       * <p>
214       * This is a <b>display</b> kind on a confirmation field, deliberately <b>not</b> a new
215       * {@code FormDef.Input} type: a {@code code} field carries no submit value, so expressing it as an input
216       * would mean teaching the collection, validation, prefill and submit paths about a control that is not one.
217       */
218      public String kind;
219
220      /**
221       * Creates a typed confirmation field.
222       *
223       * @param label The field label.  Must not be <jk>null</jk> or blank.
224       * @param value The field value.  Can be <jk>null</jk> (rendered as an empty value).
225       * @return A new {@link Field}.
226       * @throws IllegalArgumentException If {@code label} is <jk>null</jk> or blank.
227       */
228      public static Field of(String label, String value) {
229         if (ib(label))
230            throw iaex("ModalDef.Field label must not be null or blank.");
231         var f = new Field();
232         f.label = label;
233         f.value = value;
234         return f;
235      }
236
237      /**
238       * Creates a typed confirmation field displayed as monospaced, copyable {@link ModalDef#FIELD_KIND_CODE code}.
239       *
240       * <p>
241       * The runtime paints the value into a {@code <pre>} with {@code textContent} (never {@code innerHTML}) and
242       * adds a copy button that is feature-detected and never throws; the {@code <pre>} stays selectable, so
243       * manual copy always works.
244       *
245       * @param label The field label.  Must not be <jk>null</jk> or blank.
246       * @param value The field value.  Can be <jk>null</jk> (rendered as an empty value).
247       * @return A new {@link Field}.
248       * @throws IllegalArgumentException If {@code label} is <jk>null</jk> or blank.
249       */
250      public static Field code(String label, String value) {
251         var f = of(label, value);
252         f.kind = FIELD_KIND_CODE;
253         return f;
254      }
255   }
256
257   /**
258    * One page of a {@link ModalDef#steps} wizard: an id, an optional title and confirm-button label, and the typed
259    * display fields painted for that page.
260    *
261    * @since 10.0.0
262    */
263   @BeanType(properties="id,title,confirmLabel,fields")
264   public static class Step {
265
266      /** The step id, unique within the modal; a script selects a step by it.  Must not be blank. */
267      public String id;
268
269      /** The dialog title shown while this step is current; omitted from the wire when unset (the modal title stays). */
270      public String title;
271
272      /** The confirm-button label for this step; omitted when unset (the runtime shows Next; on the last step it shows the dialog's confirm label, else Finish). */
273      public String confirmLabel;
274
275      /** The typed display fields painted for this step, in display order; omitted from the wire when none are declared. */
276      public List<Field> fields;
277
278      /**
279       * Creates a step.
280       *
281       * @param id The step id.  Must not be <jk>null</jk> or blank.
282       * @return A new {@link Step}.
283       * @throws IllegalArgumentException If {@code id} is <jk>null</jk> or blank.
284       */
285      public static Step of(String id) {
286         if (ib(id))
287            throw iaex("ModalDef.Step id must not be null or blank.");
288         var s = new Step();
289         s.id = id;
290         return s;
291      }
292
293      /**
294       * Sets the dialog title shown while this step is current.
295       *
296       * @param value The title.  Can be <jk>null</jk> to unset.
297       * @return This object.
298       */
299      public Step title(String value) {
300         title = value;
301         return this;
302      }
303
304      /**
305       * Sets the confirm-button label for this step.
306       *
307       * @param value The label.  Can be <jk>null</jk> to unset.
308       * @return This object.
309       */
310      public Step confirmLabel(String value) {
311         confirmLabel = value;
312         return this;
313      }
314
315      /**
316       * Adds one typed display field to this step.
317       *
318       * @param label The field label.  Must not be <jk>null</jk> or blank.
319       * @param value The field value.  Can be <jk>null</jk>.
320       * @return This object.
321       */
322      public Step field(String label, String value) {
323         if (fields == null)
324            fields = l();
325         fields.add(Field.of(label, value));
326         return this;
327      }
328   }
329
330   /**
331    * One entry in a dialog's {@link ModalDef#childActions} catalog &mdash; a stacked step a {@code type="action"}
332    * input inside <i>this</i> dialog's form may open.
333    *
334    * <h2 class='section'>Dialog-presenting by construction</h2>
335    * <p>
336    * A child action carries no {@code present} field: opening a stacked dialog is the only thing it does.  A child
337    * with no {@link #form} is a legal confirm-only child dialog.
338    *
339    * <h2 class='section'>No gating vocabulary, on purpose</h2>
340    * <p>
341    * There is deliberately no {@code enabledWhen} here, for three independent reasons.  The rule type lives in the
342    * rich-view module, which this module must not reference.  A dialog opened where there is no row has no row data
343    * to evaluate against, so a field-keyed rule would fail closed forever with no signal to its author.  And the
344    * subject of a child step is the <i>draft in the open dialog</i>, not the parent row &mdash; so evaluating the
345    * parent row's data would answer a question nobody asked.  Gating a child step is the <b>server's</b> job at
346    * child-form-GET time; it already owns that GET and can refuse it.
347    *
348    * @since 10.0.0
349    */
350   @BeanType(properties="id,label,form,endpoint,method,onSuccess,carryDrafts")
351   public static class ChildAction {
352
353      /** The action id a {@code type="action"} input in this dialog's form names.  Required, non-blank. */
354      public String id;
355
356      /** The label painted on the button that opens this child.  Required, non-blank. */
357      public String label;
358
359      /**
360       * The child dialog's read-only form-source URL; omitted from the wire when unset (a confirm-only child).
361       *
362       * <p>
363       * Required if this child declares {@link #carryDrafts} &mdash; with no URL there is nothing for the draft
364       * query to ride on, so the drafts would vanish silently.
365       */
366      public String form;
367
368      /** The child's submit endpoint; omitted from the wire when unset.  See {@link #endpoint(String)}. */
369      public String endpoint;
370
371      /** The child's submit method; omitted from the wire when unset.  See {@link #method(String)}. */
372      public String method;
373
374      /** The child's on-success behaviour token; omitted from the wire when unset. */
375      public String onSuccess;
376
377      /**
378       * Whether opening this child carries the <b>parent dialog's current draft values</b> to its form-source GET
379       * as one query parameter; omitted from the wire when unset or <jk>false</jk>.
380       *
381       * <p>
382       * Without it a Review step opens <b>empty</b> and loses everything the operator typed.  With it, the
383       * runtime serializes the parent's collected form values, URL-encodes them, and appends them as a single
384       * {@code juneauDrafts} parameter, refusing visibly (and not opening the child) above a client-side byte cap
385       * measured on the <i>encoded</i> value.
386       *
387       * <p>
388       * <b>Drafts land in access logs and browser history.</b>  No secret may ride this channel.
389       */
390      public Boolean carryDrafts;
391
392      /**
393       * Creates a child action.
394       *
395       * @param id The action id a {@code type="action"} input names.  Must not be <jk>null</jk> or blank.
396       * @param label The button label.  Must not be <jk>null</jk> or blank.
397       * @return A new {@link ChildAction}.
398       * @throws IllegalArgumentException If {@code id} or {@code label} is <jk>null</jk> or blank.
399       */
400      public static ChildAction of(String id, String label) {
401         if (ib(id))
402            throw iaex("ModalDef.ChildAction id must not be null or blank.");
403         if (ib(label))
404            throw iaex("ModalDef.ChildAction label must not be null or blank.");
405         var c = new ChildAction();
406         c.id = id;
407         c.label = label;
408         return c;
409      }
410
411      /**
412       * Sets the child dialog's read-only form-source URL.
413       *
414       * @param value The URL.  Can be <jk>null</jk> to unset (a confirm-only child).
415       * @return This object.
416       */
417      public ChildAction form(String value) {
418         form = value;
419         return this;
420      }
421
422      /**
423       * Sets the child's submit endpoint.
424       *
425       * <p>
426       * Optional individually; a child action whose dialog is meant to be <b>submittable</b> must declare both a
427       * non-safe {@link #method} and an {@code endpoint}, or its Confirm visibly refuses with {@code safe-method}
428       * and sends nothing.  A display-only child that never submits needs neither, which is why this is not a
429       * {@link ModalDef#validate()} rule &mdash; this bean cannot know which of its children are meant to submit.
430       *
431       * @param value The endpoint.  Can be <jk>null</jk> to unset.
432       * @return This object.
433       */
434      public ChildAction endpoint(String value) {
435         endpoint = value;
436         return this;
437      }
438
439      /**
440       * Sets the child's submit method.
441       *
442       * <p>
443       * Optional individually; see {@link #endpoint(String)} &mdash; a submittable child needs both, and a
444       * missing or safe method is a visible client-side refusal before any request is sent.
445       *
446       * @param value The method.  Can be <jk>null</jk> to unset.
447       * @return This object.
448       */
449      public ChildAction method(String value) {
450         method = value;
451         return this;
452      }
453
454      /**
455       * Sets the child's on-success behaviour token.
456       *
457       * @param value The token.  Can be <jk>null</jk> to unset.
458       * @return This object.
459       */
460      public ChildAction onSuccess(String value) {
461         onSuccess = value;
462         return this;
463      }
464
465      /**
466       * Declares that opening this child carries the parent dialog's drafts (see {@link #carryDrafts}).
467       *
468       * <p>
469       * Passing <jk>false</jk> <b>clears</b> the flag rather than serializing an explicit {@code false}, so an
470       * un-opted-in child's payload is byte-identical to one that never mentioned it.
471       *
472       * @param value <jk>true</jk> to carry the parent's drafts; <jk>false</jk> (or unset) to open empty.
473       * @return This object.
474       */
475      public ChildAction carryDrafts(boolean value) {
476         carryDrafts = value ? Boolean.TRUE : null;
477         return this;
478      }
479   }
480
481   /**
482    * The frozen modal contract version discriminator.
483    *
484    * <p>
485    * Defaults to {@link #CONTRACT_VERSION} on <b>every</b> modal, confirm-only or form-bearing, from the instant
486    * it is constructed &mdash; the guarantee does not depend on {@link #checked()} being called.
487    * Guaranteed <b>present</b> is not the same as guaranteed <b>valid</b>: presence is this field's whole job,
488    * structural well-formedness is {@link #validate()}'s (see {@link #checked()}).
489    */
490   public String contractVersion = CONTRACT_VERSION;
491
492   /** The modal title / confirmation prompt. */
493   public String title;
494
495   /** The typed confirmation fields, in display order; omitted from the wire when none are declared. */
496   public List<Field> fields;
497
498   /** The optional input form; omitted from the wire when unset (a confirm-only modal). */
499   public FormDef form;
500
501   /**
502    * The server-minted idempotency key value the runtime carries on the submit; omitted from the wire when unset.
503    * The value is minted (and its {@code (action, targetId)} binding re-checked on submit) by the rich-view
504    * module's idempotency-key helper.
505    */
506   public String idempotencyKey;
507
508   /**
509    * Whether {@link #idempotencyKey} is a <b>self-targeted</b> key whose own value the runtime must send as the
510    * submitted target (see the class Javadoc); omitted from the wire when unset or <jk>false</jk>.
511    *
512    * <p>
513    * Additive-only: like {@link #barSlot}, its presence does not bump {@link #CONTRACT_VERSION}.
514    */
515   public Boolean selfTargeted;
516
517   /**
518    * Optional additive bar slot anchored to this dialog's title &mdash; the <i>third</i> named {@link BarSlot}
519    * attachment (see the class Javadoc for how this host differs from the other two).  Omitted from the wire when
520    * unset; painted by the runtime immediately after {@link #title}, ahead of {@link #fields} and {@link #form}.
521    */
522   public BarSlot barSlot;
523
524   /**
525    * Whether the runtime must <b>not</b> close this dialog at confirm-click time, so the write's result can be
526    * painted into it as a receipt (see the class Javadoc); omitted from the wire when unset or <jk>false</jk>.
527    *
528    * <p>
529    * Additive-only: like {@link #barSlot} and {@link #selfTargeted}, its presence does not bump
530    * {@link #CONTRACT_VERSION}.
531    */
532   public Boolean keepOpenOnSubmit;
533
534   /**
535    * The dialog-scoped catalog of stacked child actions a {@code type="action"} input in {@link #form} may open
536    * (see the class Javadoc); omitted from the wire when unset or empty.
537    */
538   public List<ChildAction> childActions;
539
540   /**
541    * The name of a dialog chrome the page script registered with the runtime, which restyles this dialog's parts
542    * (see the class Javadoc); omitted from the wire when unset (the default chrome).
543    *
544    * <p>
545    * Additive-only: like {@link #barSlot}, its presence does not bump {@link #CONTRACT_VERSION}.
546    */
547   public String chrome;
548
549   /**
550    * The wizard steps the runtime shows one at a time with Back and Next (see the class Javadoc); omitted from the
551    * wire when unset or empty.
552    *
553    * <p>
554    * Additive-only: like {@link #barSlot}, its presence does not bump {@link #CONTRACT_VERSION}.
555    */
556   public List<Step> steps;
557
558   /**
559    * The inner-navigation style of a sectioned form's strip, {@link #NAV_PILL} or {@link #NAV_FOLDER} (see the class
560    * Javadoc); omitted from the wire when unset (the runtime draws {@link #NAV_PILL}).
561    *
562    * <p>
563    * Additive-only: like {@link #barSlot}, its presence does not bump {@link #CONTRACT_VERSION}.
564    */
565   public String nav;
566
567   /**
568    * Starts a new {@link ModalDef} with the specified title / confirmation prompt.
569    *
570    * @param title The modal title / confirmation prompt.  Must not be <jk>null</jk> or blank.
571    * @return A new mutable {@link ModalDef} to chain builder calls on.
572    * @throws IllegalArgumentException If {@code title} is <jk>null</jk> or blank.
573    */
574   public static ModalDef create(String title) {
575      if (ib(title))
576         throw iaex("ModalDef title must not be null or blank.");
577      var m = new ModalDef();
578      m.title = title;
579      return m;
580   }
581
582   /**
583    * Adds one typed confirmation field.
584    *
585    * @param label The field label.  Must not be <jk>null</jk> or blank.
586    * @param value The field value (read back from the current record).  Can be <jk>null</jk>.
587    * @return This object.
588    */
589   public ModalDef field(String label, String value) {
590      if (fields == null)
591         fields = l();
592      fields.add(Field.of(label, value));
593      return this;
594   }
595
596   /**
597    * Adds one typed confirmation field displayed as monospaced, copyable {@link #FIELD_KIND_CODE code}.
598    *
599    * @param label The field label.  Must not be <jk>null</jk> or blank.
600    * @param value The field value.  Can be <jk>null</jk>.
601    * @return This object.
602    */
603   public ModalDef codeField(String label, String value) {
604      if (fields == null)
605         fields = l();
606      fields.add(Field.code(label, value));
607      return this;
608   }
609
610   /**
611    * Adds one entry to this dialog's child-action catalog.
612    *
613    * @param value The child action.  Must not be <jk>null</jk>.
614    * @return This object.
615    * @throws IllegalArgumentException If {@code value} is <jk>null</jk>.
616    */
617   public ModalDef childAction(ChildAction value) {
618      if (value == null)
619         throw iaex("ModalDef.ChildAction must not be null.");
620      if (childActions == null)
621         childActions = l();
622      childActions.add(value);
623      return this;
624   }
625
626   /**
627    * Selects the dialog chrome the page script registered under the given name.
628    *
629    * @param value The chrome name.  Can be <jk>null</jk> to unset (the default chrome); a non-null value must not be blank.
630    * @return This object.
631    */
632   public ModalDef chrome(String value) {
633      chrome = value;
634      return this;
635   }
636
637   /**
638    * Selects the inner-navigation style of a sectioned form's strip.
639    *
640    * @param value {@link #NAV_PILL} or {@link #NAV_FOLDER}.  Can be <jk>null</jk> to unset (the default pill strip).
641    * @return This object.
642    */
643   public ModalDef nav(String value) {
644      nav = value;
645      return this;
646   }
647
648   /**
649    * Adds one wizard step.
650    *
651    * @param value The step.  Must not be <jk>null</jk>.
652    * @return This object.
653    * @throws IllegalArgumentException If {@code value} is <jk>null</jk>.
654    */
655   public ModalDef step(Step value) {
656      if (value == null)
657         throw iaex("ModalDef.Step must not be null.");
658      if (steps == null)
659         steps = l();
660      steps.add(value);
661      return this;
662   }
663
664   /**
665    * Declares that the runtime must keep this dialog open across its submit so the result can be painted into it
666    * as a receipt (see the class Javadoc).
667    *
668    * <p>
669    * Passing <jk>false</jk> <b>clears</b> the flag rather than serializing an explicit {@code false}: the wire
670    * carries this opt-in only when it is on, so an un-opted-in dialog's payload is byte-identical to one that never set it.
671    *
672    * @param value <jk>true</jk> to opt in; <jk>false</jk> (or unset) keeps the default close-then-submit behaviour.
673    * @return This object.
674    */
675   public ModalDef keepOpenOnSubmit(boolean value) {
676      keepOpenOnSubmit = value ? Boolean.TRUE : null;
677      return this;
678   }
679
680   /**
681    * Sets the optional input form.
682    *
683    * @param value The form.  Can be <jk>null</jk> to unset (a confirm-only modal).
684    * @return This object.
685    */
686   public ModalDef form(FormDef value) {
687      form = value;
688      return this;
689   }
690
691   /**
692    * Sets the server-minted idempotency key value carried on the submit.
693    *
694    * @param value The key value.  Can be <jk>null</jk> to unset.
695    * @return This object.
696    */
697   public ModalDef idempotencyKey(String value) {
698      idempotencyKey = value;
699      return this;
700   }
701
702   /**
703    * Declares that {@link #idempotencyKey} is a self-targeted key &mdash; the runtime sends the key's own value as
704    * the submitted target rather than a row id.
705    *
706    * <p>
707    * Set this <b>only</b> alongside a key minted by the rich-view module's self-targeted mint helper; pairing it
708    * with an artifact-bound key discards that key's real target.  See the class Javadoc.
709    *
710    * <p>
711    * Passing <jk>false</jk> <b>clears</b> the flag rather than serializing an explicit {@code false}: the wire
712    * carries this opt-in only when it is on, so an un-opted-in dialog's payload is byte-identical to one that never set it.
713    *
714    * @param value <jk>true</jk> to opt in; <jk>false</jk> (or unset) keeps the default row-id behaviour.
715    * @return This object.
716    */
717   public ModalDef selfTargeted(boolean value) {
718      selfTargeted = value ? Boolean.TRUE : null;
719      return this;
720   }
721
722   /**
723    * Declares the additive bar slot anchored to this dialog's title.
724    *
725    * <p>
726    * See {@link #barSlot} &mdash; a third named host for the same {@link BarSlot} bean, not a re-use of the
727    * rich-view module's page or row-detail hosts.
728    *
729    * @param value The bar slot.  Can be <jk>null</jk> (no dialog bar slot).
730    * @return This object.
731    */
732   public ModalDef barSlot(BarSlot value) {
733      barSlot = value;
734      return this;
735   }
736
737   /** The message for a token that is neither of its two allowed values. */
738   private static String notOneOf(String what, String a, String b, String actual) {
739      return what + " must be '" + a + "' or '" + b + "', not '" + actual + "'.";
740   }
741
742   /**
743    * Fail-closed bean validation.
744    *
745    * <p>
746    * Requires a non-blank {@link #title} and a non-blank label on each {@link Field}; when a {@link #form} is present
747    * it delegates to {@link FormDef#validate()}.  Does <b>not</b> require {@link #contractVersion} to be set to
748    * {@link #CONTRACT_VERSION} (or set at all) &mdash; a modal whose version was explicitly cleared, or that
749    * arrived from a foreign producer that never set one, must not false-refuse on that alone.  Version-presence
750    * and structural well-formedness are deliberately independent properties (design note, &sect;5.4).
751    *
752    * <p>
753    * Also rejects, fail-closed at serve time rather than silently on the wire: a {@link Field#kind} outside the
754    * {@link #FIELD_KIND_TEXT text}/{@link #FIELD_KIND_CODE code} allowlist; a {@link #nav} other than
755    * {@link #NAV_PILL}/{@link #NAV_FOLDER}; a blank, duplicate or unlabelled
756    * {@link ChildAction} id; {@link ChildAction#carryDrafts} on a modal that declares no {@link #form} (nothing to
757    * collect <i>from</i>); and {@link ChildAction#carryDrafts} on a child that declares no
758    * {@link ChildAction#form} (nowhere to put them &mdash; the runtime would take its confirm-only branch, issue
759    * no GET, and the drafts would vanish silently).
760    *
761    * @throws IllegalArgumentException If this modal is not well-formed.
762    */
763   @Override
764   public void validate() {
765      if (ib(title))
766         throw iaex("ModalDef title must not be null or blank.");
767      if (fields != null)
768         for (var f : fields) {
769            if (f == null)
770               throw iaex("ModalDef field must not be null.");
771            if (f.label == null || f.label.isBlank())
772               throw iaex("ModalDef.Field label must not be null or blank.");
773            if (f.kind != null && ! (eqa(f.kind, FIELD_KIND_TEXT, FIELD_KIND_CODE)))
774               throw iaex(notOneOf("ModalDef.Field kind", FIELD_KIND_TEXT, FIELD_KIND_CODE, f.kind));
775         }
776      validateChildActions();
777      validateSteps();
778      if (chrome != null && chrome.isBlank())
779         throw iaex("ModalDef chrome must not be blank.");
780      if (nav != null && ! (eqa(nav, NAV_PILL, NAV_FOLDER)))
781         throw iaex(notOneOf("ModalDef nav", NAV_PILL, NAV_FOLDER, nav));
782      if (form != null)
783         form.validate();
784      if (barSlot != null)
785         barSlot.validate();
786   }
787
788   /** The {@link #steps} half of {@link #validate()}: non-blank unique ids and well-formed display fields. */
789   private void validateSteps() {
790      if (steps == null)
791         return;
792      var seen = new HashSet<String>();
793      for (var st : steps) {
794         if (st == null)
795            throw iaex("ModalDef.Step must not be null.");
796         if (st.id == null || st.id.isBlank())
797            throw iaex("ModalDef.Step id must not be null or blank.");
798         if (! seen.add(st.id))
799            throw iaex("ModalDef.Step id '" + st.id + "' is declared more than once on this modal.");
800         if (st.fields != null)
801            for (var f : st.fields) {
802               if (f == null || f.label == null || f.label.isBlank())
803                  throw iaex("ModalDef.Step '" + st.id + "' field label must not be null or blank.");
804               if (f.kind != null && ! (eqa(f.kind, FIELD_KIND_TEXT, FIELD_KIND_CODE)))
805                  throw iaex(notOneOf("ModalDef.Step '" + st.id + "' field kind", FIELD_KIND_TEXT, FIELD_KIND_CODE, f.kind));
806            }
807      }
808   }
809
810   /**
811    * The {@link #childActions} half of {@link #validate()}.
812    *
813    * <p>
814    * {@link ChildAction#of(String,String)} already argument-checks {@code id} and {@code label}; they are
815    * re-checked here as the wire-level backstop for a bean-deserialized instance that never went through the
816    * factory.
817    */
818   private void validateChildActions() {
819      if (childActions == null)
820         return;
821      var seen = new HashSet<String>();
822      for (var c : childActions) {
823         if (c == null)
824            throw iaex("ModalDef.ChildAction must not be null.");
825         if (c.id == null || c.id.isBlank())
826            throw iaex("ModalDef.ChildAction id must not be null or blank.");
827         if (c.label == null || c.label.isBlank())
828            throw iaex("ModalDef.ChildAction label must not be null or blank.");
829         if (! seen.add(c.id))
830            throw iaex("ModalDef.ChildAction id '" + c.id + "' is declared more than once on this modal.");
831         if (Boolean.TRUE.equals(c.carryDrafts)) {
832            if (form == null)
833               throw iaex("ModalDef.ChildAction '" + c.id + "' declares carryDrafts, but this modal declares "
834                  + "no form - there is nothing to collect drafts from.");
835            if (c.form == null || c.form.isBlank())
836               throw iaex("ModalDef.ChildAction '" + c.id + "' declares carryDrafts, but declares no form URL "
837                  + "- a confirm-only child issues no form GET, so the drafts would be dropped silently.");
838         }
839      }
840   }
841
842   /**
843    * The serving-path hook every app {@code @RestGet} that returns a {@link ModalDef} should invoke.
844    *
845    * <p>
846    * {@link #contractVersion} is guaranteed present on every modal from construction, so this is <b>no longer
847    * required for versioning</b>.  It stays <b>strongly recommended</b> for one remaining duty and
848    * is <b>redundant-but-harmless</b> for another:
849    * <ul>
850    *    <li><b>Non-REST producers</b> (a direct {@code Json.of(...)} serialization, or any consumer marshalling a
851    *       modal outside a REST response) have no other gate: calling this is the only fail-closed structural
852    *       {@link #validate() validation} they get, and skipping it means a malformed modal/form serializes as
853    *       contract-<i>valid</i> with no complaint.
854    *    <li><b>REST responses</b> are validated independently:
855    *       {@link WidgetsMixin.WidgetValidationProcessor
856    *       WidgetsMixin.WidgetValidationProcessor} calls {@link #validate()} on every REST response that is a
857    *       {@code Widget}, fail-closed with a 500, whether or not the producing endpoint called this method.
858    *       Calling it anyway is safe (validation is idempotent) and remains the only gate for the non-REST case
859    *       above.
860    * </ul>
861    * When a {@link #form} is present it also re-stamps {@link #CONTRACT_VERSION} on the form and recurses into
862    * {@link FormDef#checked()}.
863    *
864    * @return This object.
865    * @throws IllegalArgumentException If this modal (or its form) is not well-formed.
866    */
867   public ModalDef checked() {
868      if (form != null) {
869         contractVersion = CONTRACT_VERSION;
870         form.checked();
871      }
872      validate();
873      return this;
874   }
875}