@optionfactory/fml 9.0.0-rc21 → 9.0.0-rc23

package/dist/ful.d.mts

@@ -782,9 +782,21 @@ declare class Form extends ParsedElement {
      * 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
      */
-    submit(submitter?: HTMLElement): Promise<void>;
+    submit(submitter?: HTMLElement): Promise<boolean>;
+    /**
+     * 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
+     */
+    save(submitter?: HTMLElement): Promise<boolean>;
     /**
      * 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
@@ -817,11 +829,11 @@ declare class Form extends ParsedElement {
      */
     commit(): void;
     /**
-     * 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: Element): void;
+    edited(...els: Element[]): void;
     /**
      * Marks the form busy or releases it. Calls nest: only the first
      * `spinner(true)` and the matching last `spinner(false)` act, so a caller's
@@ -2836,21 +2848,24 @@ export type DialogOutcome = {
  * 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
@@ -2932,6 +2947,17 @@ declare class Dialog extends ParsedElement {
      * nobody answered or the request failed; it never rejects
      */
     refresh(): Promise<any[] | undefined>;
+    /**
+     * 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: string): Promise<boolean>;
     /**
      * 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
@@ -2988,17 +3014,23 @@ declare class Dialog extends ParsedElement {
  * 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
@@ -3053,8 +3085,23 @@ declare class Drawer extends ParsedElement {
      */
     refresh(): Promise<any[] | undefined>;
     /**
-     * Shows the drawer as a modal. On a drawer already open nothing happens,
-     * except that one sliding out stops and stays open.
+     * 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(): void;
+    /**
+     * The same as `ask()`.
+     * @returns {Promise<{ dismissed: boolean, result: string|null, response: any }>}
+     */
+    open(): Promise<{
+        dismissed: boolean;
+        result: string | null;
+        response: any;
+    }>;
+    /**
+     * 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
@@ -3062,17 +3109,40 @@ declare class Drawer extends ParsedElement {
      * `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.
-     */
-    open(): void;
+     * 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
+     */
+    ask(): Promise<{
+        dismissed: boolean;
+        result: string | null;
+        response: any;
+    }>;
+    /**
+     * 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: string): Promise<boolean>;
     /**
      * 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(): void;
+    close(result?: string): void;
 }
 /**
  * A menu of commands on the native popover platform, opened by the element