@optionfactory/fml 9.0.0-rc22 → 9.0.0-rc24

package/dist/ful.d.mts

@@ -363,6 +363,11 @@ declare class Bindings {
      * `rest` being the remainder of the path (`''` on an exact match) that a
      * composite can use to route the problem to an inner control.
      *
+     * A control counts only when it can show a problem, through a
+     * `setCustomValidity` of its own: a form-associated element that has none is
+     * skipped, so its problems fall to a shorter prefix or to the banner instead
+     * of being dropped.
+     *
      * Every other problem, and a field problem naming no control, is shown in
      * each `ful-errors` banner of the form: the banner gets `role="alert"`, is
      * revealed and holds the reasons one per line. With no such problem the
@@ -616,6 +621,14 @@ declare class Field extends ParsedElement {
      *   accessibility tree.
      * - `also` are further controls that mirror `disabled` and `readOnly`
      *   beside the claim target.
+     *
+     * The pieces are elements the field rendered itself, native controls or
+     * wrappers of its own. A ful field is not one: it has no `readOnly`, its
+     * host's role takes no aria, and a label's `for` names its host rather than
+     * its control. A composite built from ful fields answers the inner field as
+     * `control`, which forwards `focus()`, lets it render its own label with
+     * `label` and `announces` null, and forwards the claims in its setters,
+     * calling super first.
      * @param {{ slots: Record<string, DocumentFragment> | undefined }} conf
      * @returns {any} the pieces, or a promise of them
      * @throws {Error} when the subclass does not implement it
@@ -782,9 +795,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 +842,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 +2861,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
@@ -2916,14 +2944,15 @@ declare class Dialog extends ParsedElement {
      *
      * No `section:requested` is dispatched, and no `ask()` waiter is added:
      * listen for the `close` event to learn how the dialog ended. When a newer
-     * `update()` starts before the callback settles, this call paints nothing:
-     * it resolves with the body regardless, and still rejects with the
-     * callback's error.
+     * `update()` starts before the callback settles, this call paints nothing
+     * and resolves `null`, the body being the newer call's; it still rejects
+     * with the callback's error.
      * @param {() => Node|string|Promise<Node|string>} cb producing the body content
-     * @returns {Promise<Element>} the body section, in the document
+     * @returns {Promise<Element|null>} the body section, in the document, or
+     * `null` for a call a newer one overtook
      * @throws {any} what the callback threw or rejected with
      */
-    update(cb: () => Node | string | Promise<Node | string>): Promise<Element>;
+    update(cb: () => Node | string | Promise<Node | string>): Promise<Element | null>;
     /**
      * Dispatches `section:requested` for the body again, as `ask()` does,
      * whether the dialog is open or closed. A failed request is painted into
@@ -2932,6 +2961,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 +3028,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
@@ -3035,15 +3081,16 @@ declare class Drawer extends ParsedElement {
      * which has `role="alert"`, and the content is hidden.
      *
      * No `section:requested` is dispatched. When a newer `update()` starts
-     * before the callback settles, this call paints nothing: it resolves with
-     * the content section regardless, and still rejects with the callback's
-     * error.
+     * before the callback settles, this call paints nothing and resolves
+     * `null`, the content section being the newer call's; it still rejects with
+     * the callback's error.
      * @param {string} header the title, set as text
      * @param {() => Node|string|Promise<Node|string>} cb producing the content
-     * @returns {Promise<Element>} the content section, in the document
+     * @returns {Promise<Element|null>} the content section, in the document, or
+     * `null` for a call a newer one overtook
      * @throws {any} what the callback threw or rejected with
      */
-    update(header: string, cb: () => Node | string | Promise<Node | string>): Promise<Element>;
+    update(header: string, cb: () => Node | string | Promise<Node | string>): Promise<Element | null>;
     /**
      * Dispatches `section:requested` for the content again, as `open()` does,
      * whether the drawer is open or closed. A failed request is painted into
@@ -3053,8 +3100,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 +3124,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