7 files changed, 310 insertions, 0 deletions
diff --git a/toolkit/components/prompts/docs/index.rst b/toolkit/components/prompts/docs/index.rst
new file mode 100644
index 0000000000..c518bef41b
--- /dev/null
+++ b/toolkit/components/prompts/docs/index.rst
@@ -0,0 +1,10 @@
+=======
+Prompts
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   nsIPromptService
+   nsIPromptService-reference
+   modalTypes
diff --git a/toolkit/components/prompts/docs/modal-type-content.png b/toolkit/components/prompts/docs/modal-type-content.png
new file mode 100644
index 0000000000..730fe7828c
--- /dev/null
+++ b/toolkit/components/prompts/docs/modal-type-content.png
diff --git a/toolkit/components/prompts/docs/modal-type-tab.png b/toolkit/components/prompts/docs/modal-type-tab.png
new file mode 100644
index 0000000000..66da8ef782
--- /dev/null
+++ b/toolkit/components/prompts/docs/modal-type-tab.png
diff --git a/toolkit/components/prompts/docs/modal-type-window.png b/toolkit/components/prompts/docs/modal-type-window.png
new file mode 100644
index 0000000000..505850e8de
--- /dev/null
+++ b/toolkit/components/prompts/docs/modal-type-window.png
diff --git a/toolkit/components/prompts/docs/modalTypes.rst b/toolkit/components/prompts/docs/modalTypes.rst
new file mode 100644
index 0000000000..57f57e1044
--- /dev/null
+++ b/toolkit/components/prompts/docs/modalTypes.rst
@@ -0,0 +1,95 @@
+==================
+Prompt Modal Types
+==================
+
+Window Prompts
+--------------
+
+Window prompts are system prompts. They are clearly distinguishable from website
+content and can be opened with or without a parent window.
+While a window prompt is open, the parent window cannot be interacted with.
+That means the user can not close the window or switch tabs.
+Providing a parent window is optional, but highly encouraged. If you do not
+pass a parent the implementation will try to find one or fallback to aborted
+standalone window.
+
+**When to use**: This should be reserved for important browser-wide messages
+with the intent to block any further user interaction until the message has been
+read.
+
+**Flag**: `MODAL_TYPE_WINDOW`
+
+.. caution::
+
+  When using window prompts, make sure they can not be spawned by web content.
+  We've seen `cases <https://bugzilla.mozilla.org/show_bug.cgi?id=1571003>`_
+  of DoS attacks in the wild where websites spammed window prompts to lock up
+  the browser.
+  This prompt type should only be used when necessary and with proper rate
+  limiting. Most of the time, a tab prompt can be be used.
+
+.. figure:: modal-type-window.png
+   :width: 425px
+   :height: 230px
+   :alt: Screenshot of a window prompt.
+
+   Window alert prompt
+
+Tab Prompts
+-----------
+
+Tab prompts are system prompts like window prompts. As opposed to window
+prompts, they are tab modal and don't steal focus from the parent window.
+Multiple tab prompts cannot be shown at the same time. When opening additional
+prompts, they are FIFO queued.
+
+When the user closes the tab or navigates to a different URI, prompts associated
+with the given tab are closed.
+In this case an exception will be thrown:
+
+.. code-block:: JavaScript
+
+    /*
+    Exception: prompt aborted by user
+    undefined:425
+    */
+
+**When to use**: This prompt should be used for dialogs that were caused by web
+content and thus should be bound to the scope and lifetime of a specific tab,
+but should still look like secure browser UI. Examples are HTTP Auth prompt or
+the dialog to add a new search provider for the current website.
+
+**Flag**: `MODAL_TYPE_TAB`
+
+
+.. figure:: modal-type-tab.png
+   :width: 425px
+   :height: 230px
+   :alt: Screenshot of a tab prompt.
+
+   Tab alert prompt
+
+Content Prompts
+---------------
+
+Content prompts are like tab prompts, but they belong to the web content. Thus,
+they are positioned in the center of the selected browser.
+
+**When to use**: The prompt is triggered by or as a result of an action of web
+content and is **not** intended to look like secure browser UI.
+
+**Flag**: `MODAL_TYPE_CONTENT`
+
+.. figure:: modal-type-content.png
+   :width: 425px
+   :height: 230px
+   :alt: Screenshot of a content prompt.
+
+   Content alert prompt
+
+
+Disabling tab/content modal prompts
+-----------------------------------
+You can disable tab and content modal prompts and get back window-modal for
+individual prompts by setting the `prompts.modalType.<promptName>` preference to
+`3`.
diff --git a/toolkit/components/prompts/docs/nsIPromptService-reference.rst b/toolkit/components/prompts/docs/nsIPromptService-reference.rst
new file mode 100644
index 0000000000..9879cd753a
--- /dev/null
+++ b/toolkit/components/prompts/docs/nsIPromptService-reference.rst
@@ -0,0 +1,10 @@
+========================
+Prompt Service Reference
+========================
+
+This is the JSDoc from the Prompter.jsm implementation. You can find the full
+interface definition in
+`nsIPromptService.idl <https://searchfox.org/mozilla-central/source/toolkit/components/windowwatcher/nsIPromptService.idl>`_.
+
+.. js:autoclass:: Prompter
+  :members:
diff --git a/toolkit/components/prompts/docs/nsIPromptService.rst b/toolkit/components/prompts/docs/nsIPromptService.rst
new file mode 100644
index 0000000000..4651d0bfd0
--- /dev/null
+++ b/toolkit/components/prompts/docs/nsIPromptService.rst
@@ -0,0 +1,195 @@
+==============
+Prompt Service
+==============
+
+The `nsIPromptService` provides methods for opening various types of prompts.
+See the `interface documentation <nsIPromptService-reference.html>`_ for a list
+of prompt types.
+Every prompt method has 3 different versions:
+
+- **Prompt by window**:
+  This is considered the legacy way of prompting and only works if the window
+  you want to prompt for is in the same process.
+  Only supports window prompts.
+
+- **Prompt by browsing context (synchronous)**:
+  Use a browsing context as parent for the prompt. Works cross process from
+  parent and content process.
+
+- **Prompt by browsing context (asynchronous)**:
+  Returns a promise which resolves once the prompt closes.
+
+
+The synchronous prompt methods use call by reference (XPCOM `inout` or `out`) to
+return the updated prompt arguments to the caller.
+When prompting async the arguments are passed in by value. Prompt results are
+returned in an `nsIPropertyBag` when the Promise resolves.
+
+
+.. note::
+    If you don't provide a parent window or browsing context the prompt service
+    will fallback to a window prompt.
+    The same goes for browsing contexts of chrome windows, because there is no
+    clear association to a browser / tab.
+
+
+Examples
+--------
+
+JavaScript Sync
+~~~~~~~~~~~~~~~
+
+Here is an example of opening a confirm prompt from JavaScript. We are in the
+parent process and we want to show a tab prompt:
+
+.. code-block:: javascript
+
+    // Get the browsing context for the currently selected tab
+    let browsingContext = gBrowser.selectedBrowser.browsingContext;
+
+    // Specify prompt type, can be MODAL_TYPE_TAB, MODAL_TYPE_CONTENT,
+    // MODAL_TYPE_WINDOW
+    let modalType = Services.prompt.MODAL_TYPE_TAB;
+
+    // Object for checkbox state to pass by reference.
+    let check = { value: false };
+
+    // Prompt synchronously and store result
+    let confirmed = Services.prompt.confirmCheckBC(browsingContext, modalType,
+    "My Title", "Hello, World!", "Check this box if you agree", check);
+
+    // check.value now contains final checkbox state
+    // confirmed is a boolean which indicates whether the user pressed ok (true)
+    // or cancel (false)
+    console.debug("User checked checkbox?", check.value);
+    console.debug("User confirmed prompt?", confirmed);
+
+
+JavaScript Async
+~~~~~~~~~~~~~~~~
+
+The same prompt as above, but called async:
+
+.. code-block:: javascript
+
+    // Get the browsing context for the currently selected tab
+    let browsingContext = gBrowser.selectedBrowser.browsingContext;
+
+    // Specify prompt type, can be MODAL_TYPE_TAB, MODAL_TYPE_CONTENT,
+    // MODAL_TYPE_WINDOW
+    let modalType = Services.prompt.MODAL_TYPE_TAB;
+
+    // Note that the checkbox state variable is not an object in this case,
+    because we get the checkbox result via the result object.
+    let check = false;
+
+    // Prompt asynchronously and await result
+    let propBag = await Services.prompt.asyncConfirmCheck(browsingContext,
+                                                          modalType,
+                                                          "My Title",
+                                                          "Hello, World!",
+                                                          "Check this box if you agree",
+                                                          check);
+
+    let ok = propBag.getProperty("ok");
+    let checked = propBag.getProperty("checked");
+
+    // ok is the boolean indicating if the user clicked "ok" (true) or
+    // "cancel" (false).
+    // checked is a boolean indicating the final checkbox state
+    console.debug("User checked checkbox?", checked);
+    console.debug("User confirmed prompt?", ok);
+
+
+C++ Sync
+~~~~~~~~
+
+.. code-block:: cpp
+
+      nsCOMPtr<nsIPromptService> promptSvc =
+        do_GetService("@mozilla.org/prompter;1");
+
+      if(!promptSvc) {
+        // Error handling
+        return;
+      }
+
+      // Assuming you have the browsing context as a member.
+      // You might need to get the browsing context from somewhere else.
+      BrowsingContext* bc = mBrowsingContext;
+
+      bool ok;
+      bool checked = false;
+
+      nsresult rv = promptSvc->confirmCheck(mBrowsingContext,
+                                            nsIPromptService::MODAL_TYPE_TAB,
+                                            "My Title"_ns
+                                            "Hello, World!"_ns,
+                                            "Check this box if you agree"_ns,
+                                            &checked, &ok);
+
+      // ok is the boolean indicating if the user clicked "ok" (true) or
+      // "cancel" (false).
+      // checked is a boolean indicating the final checkbox state
+
+C++ Async
+~~~~~~~~~
+
+.. code-block:: cpp
+
+      nsCOMPtr<nsIPromptService> promptSvc =
+        do_GetService("@mozilla.org/prompter;1");
+
+      if(!promptSvc) {
+        // Error handling
+        return;
+      }
+
+      bool checked = false;
+      Promise* promise;
+
+      // Assuming you have the browsing context as a member.
+      // You might need to get the browsing context from somewhere else.
+      BrowsingContext* bc = mBrowsingContext;
+
+      // As opposed to the sync case, here we pass the checked flag by value
+      nsresult rv = promptSvc->confirmCheckAsync(mBrowsingContext,
+                                                 nsIPromptService::MODAL_TYPE_TAB, "My Title"_ns,
+                                                 "Hello, World!"_ns,
+                                                 "Check this box if you agree"_ns,
+                                                 checked, promise);
+
+      // Attach a promise handler
+      RefPtr<PromptHandler> handler = new PromptHandler(promise);
+      promise->AppendNativeHandler(handler);
+
+Then, in your promise handler callback function:
+
+.. code-block:: cpp
+
+      void PromptHandler::ResolvedCallback(JSContext* aCx,
+                                       JS::Handle<JS::Value> aValue) {
+        JS::Rooted<JSObject*> detailObj(aCx, &aValue.toObject());
+
+        // Convert the JSObject back to a property bag
+        nsresult rv;
+        nsCOMPtr<nsIPropertyBag2> propBag;
+        rv = UnwrapArg<nsIPropertyBag2>(aCx, detailObj, getter_AddRefs(propBag));
+        if (NS_FAILED(rv)) return;
+
+        bool ok;
+        bool checked;
+        propBag->GetPropertyAsBool(u"ok"_ns, &ok);
+        propBag->GetPropertyAsBool(u"checked"_ns, &checked);
+
+        // ok is the boolean indicating if the user clicked "ok" (true) or
+        // "cancel" (false).
+        // checked is a boolean indicating the final checkbox state.
+      }
+
+
+
+
+
+For a full list of prompt methods check
+`nsIPromptService reference <nsIPromptService-reference.html>`_.