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 — 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} — 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 → token-theft → 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} — 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 — <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} — 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 — 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 — 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} — 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 — and thereby bypass the gating of — a declared row action. 099 * 100 * <h2 class='section'>{@link #chrome} and {@link #steps} — 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} — 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 — 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 * — Java-only fields a server-side emitter paints directly, omitted from their wire — 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 — {@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 — 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 — 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 — 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} — 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 — 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)} — 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 — 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 — 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 — 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} — 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) — 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, §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 — 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}