@optionfactory/fml 9.0.0-rc22 → 9.0.0-rc24

package/dist/vscode.html-custom-data.json

@@ -21,7 +21,7 @@
     },
     {
       "name": "ful-dialog",
-      "description": "A modal dialog on the native platform: header, body and buttons, the header attribute naming its heading, opened by any element carrying dialog-target set to its id, or programmatically through open()/ask(), which answer with how the dialog ended, or through update(callback), which opens it on a loading state and then shows either what the callback delivered or the problems of a rejection. Longer explanations belong here, shorter ones in ful-tooltip. Dialog.ask(header, body, buttons) and Dialog.confirm(header, body, labels) ask a question in a transient one, building, showing, answering and removing the element themselves; a confirm's cancel, close and Escape all answer the negative.",
+      "description": "A modal dialog on the native platform: header, body and buttons, the header attribute naming its heading, opened by any element carrying dialog-target set to its id, or programmatically through open()/ask(), which answer with how the dialog ended, or through update(callback), which opens it on a loading state and then shows either what the callback delivered or the problems of a rejection. dismiss(reason) dismisses it as the close button would, refusable and guarded alike, answering whether it closed. Longer explanations belong here, shorter ones in ful-tooltip. Dialog.ask(header, body, buttons) and Dialog.confirm(header, body, labels) ask a question in a transient one, building, showing, answering and removing the element themselves; a confirm's cancel, close and Escape all answer the negative.",
       "attributes": [
         {
           "name": "header",
@@ -34,12 +34,16 @@
         {
           "name": "close-on-submit",
           "description": "For the dialog whose answer is a form succeeding rather than a button being pressed: its own form submitting successfully closes it and answers with the response. Opt in, and its own form only, a ful-form the body holds directly, since a ful-table wraps its filters in a form of its own and searching one is not the dialog being answered. Such a dialog renders no acknowledge button of its own, the form's submit being its answer. (boolean)"
+        },
+        {
+          "name": "guard-dismiss",
+          "description": "For the dialog holding a form the user edits: a dismissal nobody refused, while a ful-form of the dialog under track-changes holds edits not saved yet, first asks the user through Dialog.confirm whether to close and drop them, with the localized dialog.discard texts. Gestures and dismiss() are asked about; close(), a data-result button, close-on-submit and update() are answers or the page deciding, and ask nothing. A second Escape with no interaction in between closes it whatever the user would answer. (boolean)"
         }
       ]
     },
     {
       "name": "ful-drawer",
-      "description": "A side panel drawer on the native dialog platform: a header with its title (the header attribute, or update()'s own) and close button, and a body that opens in a loading state, then shows either the content delivered by update(header, callback) (or the slotted one, when it is never updated) or the error a rejecting callback carries. placement picks the side, end by default, start its mirror. Any element carrying dialog-target set to its id opens it too.",
+      "description": "A side panel drawer on the native dialog platform: a header with its title (the header attribute, or update()'s own) and close button, and a body that opens in a loading state, then shows either the content delivered by update(header, callback) (or the slotted one, when it is never updated) or the error a rejecting callback carries. placement picks the side, end by default, start its mirror. open()/ask() answer with how the drawer ended, as a ful-dialog's do, an ask() on a drawer update() opened waiting for that opening's ending; dismiss(reason) dismisses it as the close button would, refusable and guarded alike, answering whether it closed. Any element carrying dialog-target set to its id opens it too.",
       "attributes": [
         {
           "name": "header",
@@ -52,6 +56,10 @@
         {
           "name": "close-on-submit",
           "description": "For the drawer whose ending is a form succeeding rather than its close button being pressed: the form its content holds directly submitting successfully closes it, the close event carrying the response. Opt in, and its own form only, since a ful-table wraps its filters in a form of its own and searching one is not the drawer finishing. (boolean)"
+        },
+        {
+          "name": "guard-dismiss",
+          "description": "For the drawer holding a form the user edits: a dismissal nobody refused, while a ful-form of the drawer under track-changes holds edits not saved yet, first asks the user through Dialog.confirm whether to close and drop them, with the localized dialog.discard texts. Gestures and dismiss() are asked about; close(), a data-result button, close-on-submit and update() are answers or the page deciding, and ask nothing. A second Escape with no interaction in between closes it whatever the user would answer. (boolean)"
         }
       ]
     },
@@ -143,7 +151,7 @@
         },
         {
           "name": "track-changes",
-          "description": "Keeps track of the edits not saved yet: dirty answers whether a field the user edited since the last commit holds another value, the host matches :state(dirty) and the submit buttons carry a dot while it does. A successful submit commits, and so does the form once its fields have rendered; commit() is for a save of the page's own. (boolean)"
+          "description": "Keeps track of the edits not saved yet: dirty answers whether a field the user edited since the last commit holds another value, the host matches :state(dirty) and the submit buttons carry a dot while it does. A successful submit commits, and so does the form once its fields have rendered; commit() is for a save of the page's own, and save() submits only while there is something to save, answering whether nothing unsaved is left. A ful-drawer or ful-dialog under guard-dismiss asks before a dismissal drops the edits. (boolean)"
         },
         {
           "name": "guard-leave",

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@optionfactory/fml",
-  "version": "9.0.0-rc22",
+  "version": "9.0.0-rc24",
   "description-markup": "none",
   "contributions": {
     "html": {
@@ -45,7 +45,7 @@
         },
         {
           "name": "ful-dialog",
-          "description": "A modal dialog on the native platform: header, body and buttons, the header attribute naming its heading, opened by any element carrying dialog-target set to its id, or programmatically through open()/ask(), which answer with how the dialog ended, or through update(callback), which opens it on a loading state and then shows either what the callback delivered or the problems of a rejection. Longer explanations belong here, shorter ones in ful-tooltip. Dialog.ask(header, body, buttons) and Dialog.confirm(header, body, labels) ask a question in a transient one, building, showing, answering and removing the element themselves; a confirm's cancel, close and Escape all answer the negative.",
+          "description": "A modal dialog on the native platform: header, body and buttons, the header attribute naming its heading, opened by any element carrying dialog-target set to its id, or programmatically through open()/ask(), which answer with how the dialog ended, or through update(callback), which opens it on a loading state and then shows either what the callback delivered or the problems of a rejection. dismiss(reason) dismisses it as the close button would, refusable and guarded alike, answering whether it closed. Longer explanations belong here, shorter ones in ful-tooltip. Dialog.ask(header, body, buttons) and Dialog.confirm(header, body, labels) ask a question in a transient one, building, showing, answering and removing the element themselves; a confirm's cancel, close and Escape all answer the negative.",
           "attributes": [
             {
               "name": "header",
@@ -70,6 +70,14 @@
                 "kind": "plain",
                 "type": "boolean"
               }
+            },
+            {
+              "name": "guard-dismiss",
+              "description": "For the dialog holding a form the user edits: a dismissal nobody refused, while a ful-form of the dialog under track-changes holds edits not saved yet, first asks the user through Dialog.confirm whether to close and drop them, with the localized dialog.discard texts. Gestures and dismiss() are asked about; close(), a data-result button, close-on-submit and update() are answers or the page deciding, and ask nothing. A second Escape with no interaction in between closes it whatever the user would answer.",
+              "value": {
+                "kind": "plain",
+                "type": "boolean"
+              }
             }
           ],
           "slots": [
@@ -97,13 +105,13 @@
             },
             {
               "name": "dialog:dismiss",
-              "description": "Fired before the close button, Escape or a backdrop click closes the dialog, with detail.reason (button, escape or backdrop): cancelable, so preventDefault() keeps it open, to guard unsaved edits. Not fired for a data-result button, close-on-submit or close(). A second Escape with no interaction in between closes the dialog whatever the page does, and its dialog:dismiss is then not cancelable."
+              "description": "Fired before the close button, Escape, a backdrop click or dismiss(reason) closes the dialog, with detail.reason (button, escape, backdrop or the one dismiss() was given): cancelable, so preventDefault() keeps it open. Not fired for a data-result button, close-on-submit or close(). A second Escape with no interaction in between closes the dialog whatever the page does, and its dialog:dismiss is then not cancelable."
             }
           ]
         },
         {
           "name": "ful-drawer",
-          "description": "A side panel drawer on the native dialog platform: a header with its title (the header attribute, or update()'s own) and close button, and a body that opens in a loading state, then shows either the content delivered by update(header, callback) (or the slotted one, when it is never updated) or the error a rejecting callback carries. placement picks the side, end by default, start its mirror. Any element carrying dialog-target set to its id opens it too.",
+          "description": "A side panel drawer on the native dialog platform: a header with its title (the header attribute, or update()'s own) and close button, and a body that opens in a loading state, then shows either the content delivered by update(header, callback) (or the slotted one, when it is never updated) or the error a rejecting callback carries. placement picks the side, end by default, start its mirror. open()/ask() answer with how the drawer ended, as a ful-dialog's do, an ask() on a drawer update() opened waiting for that opening's ending; dismiss(reason) dismisses it as the close button would, refusable and guarded alike, answering whether it closed. Any element carrying dialog-target set to its id opens it too.",
           "attributes": [
             {
               "name": "header",
@@ -128,6 +136,14 @@
                 "kind": "plain",
                 "type": "boolean"
               }
+            },
+            {
+              "name": "guard-dismiss",
+              "description": "For the drawer holding a form the user edits: a dismissal nobody refused, while a ful-form of the drawer under track-changes holds edits not saved yet, first asks the user through Dialog.confirm whether to close and drop them, with the localized dialog.discard texts. Gestures and dismiss() are asked about; close(), a data-result button, close-on-submit and update() are answers or the page deciding, and ask nothing. A second Escape with no interaction in between closes it whatever the user would answer.",
+              "value": {
+                "kind": "plain",
+                "type": "boolean"
+              }
             }
           ],
           "slots": [
@@ -143,7 +159,7 @@
           "events": [
             {
               "name": "close",
-              "description": "Fired when the drawer closes, carrying how it ended: dismissed tells the close button and Escape from a form that closed it under close-on-submit, and response what that submit answered with, a save answering with no body at all being a save all the same."
+              "description": "Fired when the drawer closes, carrying how it ended, the same object a ful-dialog answers with: dismissed tells the close button and Escape from an answer, result the data-result of the button, or the argument of close(result), that closed it, and response what a submit answered with under close-on-submit, a save answering with no body at all being a save all the same. ask() and open() resolve with the same object, and a drawer leaving the document while open answers its waiters with a dismissal."
             },
             {
               "name": "section:requested",
@@ -151,7 +167,7 @@
             },
             {
               "name": "drawer:dismiss",
-              "description": "Fired before the close button, Escape or a backdrop click closes the drawer, with detail.reason (button, escape or backdrop): cancelable, so preventDefault() keeps it open, to guard unsaved edits. Not fired for close() or close-on-submit. A second Escape with no interaction in between closes the drawer at once, and its drawer:dismiss is then not cancelable."
+              "description": "Fired before the close button, Escape, a backdrop click or dismiss(reason) closes the drawer, with detail.reason (button, escape, backdrop or the one dismiss() was given): cancelable, so preventDefault() keeps it open. Not fired for a data-result button, close-on-submit or close(). A second Escape with no interaction in between closes the drawer at once, and its drawer:dismiss is then not cancelable."
             }
           ]
         },
@@ -346,7 +362,7 @@
             },
             {
               "name": "track-changes",
-              "description": "Keeps track of the edits not saved yet: dirty answers whether a field the user edited since the last commit holds another value, the host matches :state(dirty) and the submit buttons carry a dot while it does. A successful submit commits, and so does the form once its fields have rendered; commit() is for a save of the page's own.",
+              "description": "Keeps track of the edits not saved yet: dirty answers whether a field the user edited since the last commit holds another value, the host matches :state(dirty) and the submit buttons carry a dot while it does. A successful submit commits, and so does the form once its fields have rendered; commit() is for a save of the page's own, and save() submits only while there is something to save, answering whether nothing unsaved is left. A ful-drawer or ful-dialog under guard-dismiss asks before a dismissal drops the edits.",
               "value": {
                 "kind": "plain",
                 "type": "boolean"
@@ -369,7 +385,7 @@
             },
             {
               "name": "submit:requested",
-              "description": "Fired after the submit was accepted, to let a listener resolve the response itself."
+              "description": "Fired after the submit was accepted, to let a listener resolve the response itself. Register it through AsyncEvents.asyncOn: the form awaits only such a listener, and one added with addEventListener is not waited for."
             },
             {
               "name": "submit:success",
@@ -377,7 +393,7 @@
             },
             {
               "name": "submit:failure",
-              "description": "Fired with the exception when the submit fails. The form does not rethrow."
+              "description": "Fired with the exception when the submit fails. The form does not rethrow: submit() resolves false, as it resolves true after submit:success."
             },
             {
               "name": "dirty:change",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@optionfactory/fml",
-    "version": "9.0.0-rc22",
+    "version": "9.0.0-rc24",
     "type": "module",
     "main": "./dist/fml.mjs",
     "module": "./dist/fml.mjs",