@optionfactory/fml 9.0.0-rc22 → 9.0.0-rc23

package/dist/fml.iife.js

@@ -7733,11 +7733,13 @@ var fml = (function (exports) {
          * A call while a submit is in flight returns at once, doing nothing.
          * @param {HTMLElement} [submitter] the button that submitted, if any; it is
          * the only button whose name and value are submitted
-         * @returns {Promise<void>} settling once the submit has finished, whatever its outcome
+         * @returns {Promise<boolean>} settling once the submit has finished: true
+         * after `submit:success`, false when it failed, was cancelled or was dropped
+         * for one in flight
          */
         async submit(submitter) {
             if (this.#submitting) {
-                return;
+                return false;
             }
             this.#submitting = true;
             this.spinner(true);
@@ -7754,7 +7756,7 @@ var fml = (function (exports) {
                     detail: { submitter, values, request },
                 });
                 if (!this.dispatchEvent(se)) {
-                    return;
+                    return false;
                 }
                 this.errors = [];
                 const sre = new CustomEvent('submit:requested', {
@@ -7777,6 +7779,7 @@ var fml = (function (exports) {
                         detail: { submitter, values, request, response: mapped },
                     }),
                 );
+                return true;
             } catch (e) {
                 this.dispatchEvent(
                     new CustomEvent('submit:failure', {
@@ -7790,11 +7793,27 @@ var fml = (function (exports) {
                 } else {
                     console.warn('failed to submit form', this, 'reason:', e);
                 }
+                return false;
             } finally {
                 this.#submitting = false;
                 this.spinner(false);
             }
         }
+        /**
+         * Saves the unsaved edits, for a page action that would lose them, such as
+         * one reloading the page: under `track-changes` it submits only while the
+         * form is dirty, and without it always submits.
+         * @param {HTMLElement} [submitter] as `submit` takes it
+         * @returns {Promise<boolean>} whether no unsaved edit is left: false when
+         * the submit did not succeed, or when the user edited the form while it
+         * was in flight
+         */
+        async save(submitter) {
+            if (this.#tracking && !this.dirty) {
+                return true;
+            }
+            return (await this.submit(submitter)) && !this.dirty;
+        }
         /**
          * Resets the native form, each field returning to its default value. Under
          * `track-changes` every control counts as edited: the form is dirty if the
@@ -7867,12 +7886,14 @@ var fml = (function (exports) {
             }
         }
         /**
-         * Counts a control as edited by the user, for a value the page writes on
+         * Counts controls as edited by the user, for values the page writes on
          * the user's behalf: assigning `value` reports nothing, as 0019 wants.
-         * @param {Element} el the control, or an element inside it
+         * @param {...Element} els each a control, or an element inside one
          */
-        edited(el) {
-            this.#touch(el);
+        edited(...els) {
+            for (const el of els) {
+                this.#touch(el);
+            }
         }
         /**
          * @param {Map<string, string>} saved
@@ -12974,6 +12995,8 @@ var fml = (function (exports) {
         #error;
         #requests = new SectionRequests();
         #updates = new Claims();
+        /** @type {Promise<boolean>|null} */
+        #confirming = null;
         /**
          * @param {HTMLElement} host the element the section requests are dispatched on
          * @param {DocumentFragment} fragment the rendered template, holding a
@@ -12997,17 +13020,53 @@ var fml = (function (exports) {
         get section() {
             return this.#section;
         }
+        /**
+         * Whether a `ful-form` of this dialog, not one of a dialog nested in it,
+         * holds unsaved edits (see `Form.dirty`).
+         * @returns {boolean}
+         */
+        get dirty() {
+            return Array.from(this.#dialog.querySelectorAll('ful-form')).some(
+                (form) => form.closest('dialog') === this.#dialog && /** @type {any} */ (form).dirty,
+            );
+        }
         /**
          * Dispatches the dismissal on the host and calls `close` unless a listener
-         * prevented it. A dismissal that is not cancelable announces a close the
-         * platform makes whatever the page does, so `close` is not called for it.
+         * prevented it or, with `confirm` given and the dialog `dirty`, `confirm`
+         * answers false. A dismissal that is not cancelable announces a close the
+         * platform makes whatever the page does, so nothing is asked and `close` is
+         * not called for it. While `confirm` is pending a further dismissal waits
+         * for the same answer, and a dialog closed meanwhile is not closed again.
          * @param {CustomEvent} asked
          * @param {() => void} close
+         * @param {(() => Promise<boolean>)|null} confirm asks whether to drop the unsaved edits
+         * @returns {Promise<boolean>} whether the dismissal closes the dialog
          */
-        dismiss(asked, close) {
-            if (this.#host.dispatchEvent(asked) && asked.cancelable) {
+        dismiss(asked, close, confirm) {
+            if (this.#confirming) {
+                return this.#confirming;
+            }
+            if (!this.#host.dispatchEvent(asked)) {
+                return Promise.resolve(false);
+            }
+            if (!asked.cancelable) {
+                return Promise.resolve(true);
+            }
+            if (!confirm || !this.dirty) {
                 close();
+                return Promise.resolve(true);
             }
+            this.#confirming = confirm()
+                .then((drop) => {
+                    if (drop && this.#dialog.open) {
+                        close();
+                    }
+                    return drop;
+                })
+                .finally(() => {
+                    this.#confirming = null;
+                });
+            return this.#confirming;
         }
         /**
          * Calls `dismiss` when a press and its release both land on the backdrop,
@@ -13147,21 +13206,24 @@ var fml = (function (exports) {
      * and a press and release both on the backdrop close the dialog, each as a
      * dismissal, as Escape does.
      *
-     * Before any of those three gestures closes it, the element dispatches a
-     * cancelable, non-bubbling `dialog:dismiss` with `detail: { reason }`, the
-     * reason being `button`, `backdrop` or `escape`; a listener calling
-     * `preventDefault()` keeps it open, to guard unsaved edits. A `data-result`
-     * button, `close-on-submit` and `close()` answer rather than dismiss, and
-     * dispatch none.
+     * Those three gestures go through `dismiss(reason)`, the reason being
+     * `button`, `backdrop` or `escape`: before it closes the dialog, the element
+     * dispatches a cancelable, non-bubbling `dialog:dismiss` with
+     * `detail: { reason }`, and a listener calling `preventDefault()` keeps it
+     * open. Under `guard-dismiss`, a dismissal nobody refused, while a `ful-form`
+     * of the dialog holds unsaved edits (see `Form.dirty`), first asks the user,
+     * through `Dialog.confirm`, whether to close and drop them. A `data-result`
+     * button, `close-on-submit`, `close()` and `update()` are answers or the page
+     * deciding: they dispatch nothing and ask nothing.
      *
      * The platform lets a page refuse Escape once per user interaction: a second
      * Escape with no click or keystroke in between closes the dialog whatever the
-     * page does, `requires-answer` included. That close is still announced by a
-     * `dialog:dismiss`, which is then not cancelable.
+     * page does, `requires-answer` and `guard-dismiss` included. That close is
+     * still announced by a `dialog:dismiss`, which is then not cancelable.
      *
      * `requires-answer` withholds the close button and refuses Escape and the
      * backdrop, so the dialog is closed only by a button carrying `data-result`
-     * or from code through `close()`.
+     * or from code, through `close()` or `dismiss()`.
      *
      * `close-on-submit` closes the dialog when a `ful-form` that is a direct child
      * of the body dispatches `submit:success`, answering with its
@@ -13181,7 +13243,7 @@ var fml = (function (exports) {
      * in a form needs.
      */
     class Dialog extends ParsedElement {
-        static attributes = ['header', 'requires-answer:presence', 'close-on-submit:presence'];
+        static attributes = ['header', 'requires-answer:presence', 'close-on-submit:presence', 'guard-dismiss:presence'];
         static slots = true;
         static template = `
         <dialog data-ref="dialog" class="ful-dialog">
@@ -13231,15 +13293,10 @@ var fml = (function (exports) {
                     this.#dialog.close(result);
                 }
             });
-            const dismiss = (/** @type {'button'|'backdrop'|'escape'} */ reason, platformCloses = false) =>
-                this.#sections.dismiss(
-                    new CustomEvent('dialog:dismiss', { cancelable: !platformCloses, detail: { reason } }),
-                    () => this.#dialog.close(''),
-                );
             if (!requiresAnswer) {
-                this.#sections.onBackdrop(() => dismiss('backdrop'));
+                this.#sections.onBackdrop(() => this.dismiss('backdrop'));
             }
-            fragment.querySelector('[data-ref=close]')?.addEventListener('click', () => dismiss('button'));
+            fragment.querySelector('[data-ref=close]')?.addEventListener('click', () => this.dismiss('button'));
             if (closeOnSubmit) {
                 this.#sections.onSubmitted((response) => {
                     this.#answer = { dismissed: false, result: null, response };
@@ -13249,12 +13306,12 @@ var fml = (function (exports) {
             this.#dialog.addEventListener('cancel', (/** @type any */ e) => {
                 if (!e.cancelable) {
                     this.#dialog.returnValue = '';
-                    dismiss('escape', true);
+                    this.#dismiss('escape', false);
                     return;
                 }
                 e.preventDefault();
                 if (!requiresAnswer) {
-                    dismiss('escape');
+                    this.dismiss('escape');
                 }
             });
             this.replaceChildren(fragment);
@@ -13346,6 +13403,34 @@ var fml = (function (exports) {
         refresh() {
             return this.#sections.request();
         }
+        /**
+         * Dismisses the dialog as the user would: dispatches the cancelable
+         * `dialog:dismiss` with `detail: { reason }` and, under `guard-dismiss`,
+         * asks before dropping unsaved edits, closing the dialog as a dismissal
+         * unless either refused. `requires-answer` does not refuse it, as it does
+         * not refuse `close()`. Does nothing on a closed dialog.
+         * @param {string} reason why it is dismissed, such as `navigation`
+         * @returns {Promise<boolean>} whether the dialog is closed, false when a
+         * listener or the user kept it open
+         */
+        dismiss(reason) {
+            if (!this.#dialog.open) {
+                return Promise.resolve(true);
+            }
+            return this.#dismiss(reason, true);
+        }
+        /**
+         * @param {string} reason
+         * @param {boolean} cancelable false for a close the platform makes anyway
+         * @returns {Promise<boolean>}
+         */
+        #dismiss(reason, cancelable) {
+            return this.#sections.dismiss(
+                new CustomEvent('dialog:dismiss', { cancelable, detail: { reason } }),
+                () => this.#dialog.close(''),
+                this.declared('guard-dismiss') ? discardEdits : null,
+            );
+        }
         /**
          * Closes an open dialog, doing nothing on a closed one. A non-empty result
          * answers as the button carrying that `data-result` would; no result, or
@@ -13445,6 +13530,19 @@ var fml = (function (exports) {
         }
     }
 
+    /**
+     * Asks, through `Dialog.confirm`, whether to close and drop the unsaved edits,
+     * with the localized `dialog.discard.*` texts.
+     * @returns {Promise<boolean>} true to drop them
+     */
+    const discardEdits = () => {
+        const l10n = Localization.of();
+        return Dialog.confirm(l10n.t('dialog.discard.header'), l10n.t('dialog.discard.body'), {
+            confirm: l10n.t('dialog.discard.confirm'),
+            cancel: l10n.t('dialog.discard.cancel'),
+        });
+    };
+
     /**
      * A side panel on the native `<dialog>`, shown as a modal: a header holding
      * the title and a localized close button, then loading, error and content
@@ -13457,17 +13555,23 @@ var fml = (function (exports) {
      * default, when absent) or `start`, following the writing direction.
      *
      * The close button, Escape, and a press and release both on the backdrop all
-     * go through `close()`, once a cancelable, non-bubbling `drawer:dismiss` with
-     * `detail: { reason }` (`button`, `backdrop` or `escape`) has been dispatched
-     * on the element and no listener prevented it: `preventDefault()` keeps the
-     * drawer open, to guard unsaved edits. `close()` and `close-on-submit`
-     * dispatch none. The platform lets a page refuse Escape once per user
+     * go through `dismiss(reason)`, the reason being `button`, `backdrop` or
+     * `escape`: before it closes the drawer, the element dispatches a cancelable,
+     * non-bubbling `drawer:dismiss` with `detail: { reason }`, and a listener
+     * calling `preventDefault()` keeps it open. Under `guard-dismiss`, a dismissal
+     * nobody refused, while a `ful-form` of the drawer holds unsaved edits (see
+     * `Form.dirty`), first asks the user, through `Dialog.confirm`, whether to
+     * close and drop them. A `data-result` button, `close-on-submit`, `close()`
+     * and `update()` are answers or the page deciding: they dispatch nothing and
+     * ask nothing. The platform lets a page refuse Escape once per user
      * interaction: a second Escape with no click or keystroke in between closes
-     * the drawer at once, without the slide, and its `drawer:dismiss` is then not
-     * cancelable. Every close dispatches a non-bubbling `close` event on
-     * the element with `detail: { dismissed, response }`: `{ dismissed: false,
-     * response }` when a form closed it under `close-on-submit`, and
-     * `{ dismissed: true, response: null }` for any other close.
+     * the drawer at once, without the slide, `guard-dismiss` included, and its
+     * `drawer:dismiss` is then not cancelable.
+     *
+     * Any button inside the drawer carrying `data-result` closes it with that
+     * result, an empty one being a dismissal. Every close dispatches a
+     * non-bubbling `close` event on the element carrying the `DialogOutcome` as
+     * `detail`, before the pending `ask()` calls resolve.
      *
      * `close-on-submit` closes the drawer when a `ful-form` that is a direct child
      * of the content section dispatches `submit:success`, carrying its
@@ -13479,7 +13583,7 @@ var fml = (function (exports) {
      * element's id calls `open()` on click.
      */
     class Drawer extends ParsedElement {
-        static attributes = ['header', 'placement', 'close-on-submit:presence'];
+        static attributes = ['header', 'placement', 'close-on-submit:presence', 'guard-dismiss:presence'];
         static slots = true;
         static template = `
         <dialog data-ref="dialog" class="ful-drawer">
@@ -13496,8 +13600,9 @@ var fml = (function (exports) {
         #dialog;
         #title;
         #sections;
-        /** @type {{ dismissed: boolean, response: any }|null} */
+        /** @type {{ dismissed: boolean, result: string|null, response: any }|null} */
         #answer = null;
+        #resolvers = [];
         #closing = false;
         #slideOutEnded = (/** @type AnimationEvent */ e) => {
             if (e.target === this.#dialog) {
@@ -13520,32 +13625,33 @@ var fml = (function (exports) {
             if (placement) {
                 this.#dialog.setAttribute('placement', placement);
             }
-            const dismiss = (/** @type {'button'|'backdrop'|'escape'} */ reason, platformCloses = false) =>
-                this.#sections.dismiss(
-                    new CustomEvent('drawer:dismiss', { cancelable: !platformCloses, detail: { reason } }),
-                    () => this.close(),
-                );
             /** @type {HTMLElement} */ (fragment.querySelector('[data-ref=close]')).addEventListener('click', () =>
-                dismiss('button'),
+                this.dismiss('button'),
             );
-            this.#sections.onBackdrop(() => dismiss('backdrop'));
+            this.#sections.onBackdrop(() => this.dismiss('backdrop'));
             this.#dialog.addEventListener('cancel', (e) => {
                 if (!e.cancelable) {
                     this.#stopSlidingOut();
-                    dismiss('escape', true);
+                    this.#dismiss('escape', false);
                     return;
                 }
                 e.preventDefault();
-                dismiss('escape');
+                this.dismiss('escape');
+            });
+            this.#dialog.addEventListener('click', (/** @type any */ e) => {
+                const result = e.target.closest('button[data-result]')?.dataset.result;
+                if (result !== undefined) {
+                    this.close(result);
+                }
             });
             this.#dialog.addEventListener('close', () => {
-                this.dispatchEvent(
-                    new CustomEvent('close', { detail: this.#answer ?? { dismissed: true, response: null } }),
-                );
+                const outcome = this.#outcome();
+                this.dispatchEvent(new CustomEvent('close', { detail: outcome }));
+                this.#settle(outcome);
             });
             if (this.declared('close-on-submit')) {
                 this.#sections.onSubmitted((response) => {
-                    this.#answer = { dismissed: false, response };
+                    this.#answer = { dismissed: false, result: null, response };
                     this.close();
                 });
             }
@@ -13593,9 +13699,36 @@ var fml = (function (exports) {
         refresh() {
             return this.#sections.request();
         }
+        /** @returns {{ dismissed: boolean, result: string|null, response: any }} */
+        #outcome() {
+            return this.#answer ?? { dismissed: true, result: null, response: null };
+        }
+        /** @param {{ dismissed: boolean, result: string|null, response: any }} outcome */
+        #settle(outcome) {
+            const resolvers = this.#resolvers;
+            this.#resolvers = [];
+            for (const resolve of resolvers) {
+                resolve(outcome);
+            }
+        }
+        /**
+         * Resolves every pending `ask()` and `open()` with the outcome so far,
+         * a dismissal for a drawer still open, so that no caller waits on a drawer
+         * that left the document. The native dialog is not closed and no `close`
+         * event is dispatched.
+         */
+        disconnectedCallback() {
+            this.#settle(this.#outcome());
+        }
+        /**
+         * The same as `ask()`.
+         * @returns {Promise<{ dismissed: boolean, result: string|null, response: any }>}
+         */
+        open() {
+            return this.ask();
+        }
         /**
-         * Shows the drawer as a modal. On a drawer already open nothing happens,
-         * except that one sliding out stops and stays open.
+         * Shows the drawer as a modal and resolves with how it ends.
          *
          * The call that opens the drawer resets the outcome of the previous
          * opening, hides the error and loading sections, and dispatches
@@ -13603,26 +13736,67 @@ var fml = (function (exports) {
          * `detail: { section, first, name: null, index: null }`, `section` being
          * the content section and `first` true only on the first answered request),
          * so a listener can fill the content. A failed request is painted into the
-         * content section.
+         * content section and does not reject. On a drawer already open nothing is
+         * shown or requested, except that one sliding out stops and stays open, and
+         * the call waits for the same ending as the calls before it, which is how
+         * a caller learns the outcome of the opening an `update()` made.
+         * @returns {Promise<{ dismissed: boolean, result: string|null, response: any }>} resolving on
+         * close, or on removal from the document with a dismissal
          */
-        open() {
-            if (!this.#show()) {
-                return;
+        ask() {
+            if (this.#show()) {
+                this.#sections.restChrome();
+                this.#sections.request();
             }
-            this.#sections.restChrome();
-            this.#sections.request();
+            return new Promise((resolve) => {
+                this.#resolvers.push(resolve);
+            });
+        }
+        /**
+         * Dismisses the drawer as the user would: dispatches the cancelable
+         * `drawer:dismiss` with `detail: { reason }` and, under `guard-dismiss`,
+         * asks before dropping unsaved edits, sliding the drawer out as a
+         * dismissal unless either refused. Does nothing on a drawer that is closed
+         * or already sliding out.
+         * @param {string} reason why it is dismissed, such as `navigation`
+         * @returns {Promise<boolean>} whether the drawer is closed or closing,
+         * false when a listener or the user kept it open
+         */
+        dismiss(reason) {
+            if (this.#closing || !this.#dialog.open) {
+                return Promise.resolve(true);
+            }
+            return this.#dismiss(reason, true);
+        }
+        /**
+         * @param {string} reason
+         * @param {boolean} cancelable false for a close the platform makes anyway
+         * @returns {Promise<boolean>}
+         */
+        #dismiss(reason, cancelable) {
+            return this.#sections.dismiss(
+                new CustomEvent('drawer:dismiss', { cancelable, detail: { reason } }),
+                () => this.close(),
+                this.declared('guard-dismiss') ? discardEdits : null,
+            );
         }
         /**
          * Slides the drawer out and closes it when the animation ends, setting the
          * `closing` attribute on the native dialog meanwhile; the `close` event is
          * dispatched then, after this call has returned. Where the user prefers
-         * reduced motion, or no animation runs, it closes at once. Does nothing on
-         * a drawer that is closed or already sliding out.
+         * reduced motion, or no animation runs, it closes at once. A non-empty
+         * result answers as the button carrying that `data-result` would; no
+         * result, or an empty one, is a dismissal. Does nothing on a drawer that is
+         * closed or already sliding out.
+         * @param {string} [result]
          */
-        close() {
+        close(result) {
             if (this.#closing || !this.#dialog.open) {
                 return;
             }
+            if (result) {
+                this.#answer = { dismissed: false, result, response: null };
+            }
             if (matchMedia('(prefers-reduced-motion: reduce)').matches) {
                 this.#dialog.close();
                 return;
@@ -14334,6 +14508,10 @@ var fml = (function (exports) {
         'dialog.close': 'Close',
         'dialog.confirm': 'Confirm',
         'dialog.cancel': 'Cancel',
+        'dialog.discard.header': 'Unsaved changes',
+        'dialog.discard.body': 'There are unsaved changes: close anyway?',
+        'dialog.discard.confirm': 'Close without saving',
+        'dialog.discard.cancel': 'Keep editing',
         'drawer.close': 'Close',
         'spinner.loading': 'Loading…',
         'toast.region': 'Notifications',
@@ -14379,6 +14557,10 @@ var fml = (function (exports) {
         'dialog.close': 'Chiudi',
         'dialog.confirm': 'Conferma',
         'dialog.cancel': 'Annulla',
+        'dialog.discard.header': 'Modifiche non salvate',
+        'dialog.discard.body': 'Ci sono modifiche non salvate: chiudere comunque?',
+        'dialog.discard.confirm': 'Chiudi senza salvare',
+        'dialog.discard.cancel': 'Continua a modificare',
         'drawer.close': 'Chiudi',
         'spinner.loading': 'Caricamento…',
         'toast.region': 'Notifiche',
@@ -14427,6 +14609,10 @@ var fml = (function (exports) {
         'dialog.close': 'Cerrar',
         'dialog.confirm': 'Confirmar',
         'dialog.cancel': 'Cancelar',
+        'dialog.discard.header': 'Cambios sin guardar',
+        'dialog.discard.body': 'Hay cambios sin guardar: ¿cerrar de todos modos?',
+        'dialog.discard.confirm': 'Cerrar sin guardar',
+        'dialog.discard.cancel': 'Seguir editando',
         'drawer.close': 'Cerrar',
         'spinner.loading': 'Cargando…',
         'toast.region': 'Notificaciones',
@@ -14475,6 +14661,10 @@ var fml = (function (exports) {
         'dialog.close': 'Fermer',
         'dialog.confirm': 'Confirmer',
         'dialog.cancel': 'Annuler',
+        'dialog.discard.header': 'Modifications non enregistrées',
+        'dialog.discard.body': 'Des modifications ne sont pas enregistrées : fermer quand même ?',
+        'dialog.discard.confirm': 'Fermer sans enregistrer',
+        'dialog.discard.cancel': 'Continuer à modifier',
         'drawer.close': 'Fermer',
         'spinner.loading': 'Chargement…',
         'toast.region': 'Notifications',