(DOCSP-7881): charts dark mode feature (#275)

* (DOCSP-7881): charts dark mode feature

* (DOCSP-7881): copy review edits

* (DOCSP-7881): more copy review edits

* (DOCSP-7881): tech review feedback

Author: jwilliams-mongo

source/embedded-chart-options.txt

@@ -19,107 +19,6 @@ query parameters to their iframe URLs.
    options on your data sources. For instructions, see
    :ref:`embedding-charts`.
 
-Query Parameter Order for Verified Signatures
----------------------------------------------
-
-If you are using a :ref:`Verified Signature <embedding-procedure>` to
-render your chart, you must specify the query parameters of your
-payload in the following order, or else your signature verification
-will fail:
-
-.. list-table::
-   :header-rows: 1
-   :widths: 10 20 40
-
-   * - Parameter Position
-     - Name
-     - Description
-
-   * - 1
-     - ``id``
-     - ``id`` parameter from the Embed Chart snippet.
-
-   * - 2
-     - ``tenant``
-     - ``tenant`` parameter from the Embed Chart snippet.
-
-   * - 3
-     - ``timestamp``
-     - Current time.
-
-   * - 4
-     - ``expires-in``
-     - *(Optional)* Number of seconds for which the signature is valid.
-       If omitted, the signature is valid for 24 hours after it is
-       created.
-
-   * - 5
-     - ``filter``
-     - *(Optional)* MQL document to filter rendered documents.
-       See :ref:`embed-options-filter`.
-
-   * - 6
-     - ``autorefresh``
-     - *(Optional)* Interval in seconds at which the chart refreshes.
-       See :ref:`embed-options-refresh`.
-
-The code examples on the
-`MongoDB Charts Embedding Examples <https://github.com/mongodb/charts-embedding-examples>`__
-GitHub page provide sample payload generations with properly-formatted
-query parameters.
-
-.. _embed-options-refresh:
-
-Specify a Refresh Interval
---------------------------
-
-Use the ``autorefresh`` query parameter to define the interval,
-in seconds, at which the chart refreshes with the latest data from
-its :ref:`data source <data-sources>`. If you do not specify
-this option, your embedded chart loads once when the iframe
-loads and does not automatically refresh.
-
-Example
-~~~~~~~
-
-The following iframe embeds a chart which automatically refreshes
-every 30 seconds as defined by the ``autorefresh=30`` query parameter:
-
-.. code-block:: html
-
-   <iframe style="border: none;border-radius: 2px;box-shadow: 0 2px
-   10px 0 rgba(70, 76, 79, .2);" width="640" height="480" src="
-   {charts-host}/embed/charts?id=b3ca720f-4b4a-40b4-a726-e7dc0c49aa1c&
-   tenant=c184f559-a6d6-4c17-a524-fde31193e498&autorefresh=30"></iframe>
-
-Considerations
-~~~~~~~~~~~~~~
-
-- The minimum automatic refresh interval is 10 seconds. If you specify
-  an ``autorefresh`` value less than 10, the chart refreshes every 10
-  seconds.
-
-- If you specify an ``autorefresh`` value which is not an integer or
-  less than 0, an :ref:`error <embedded-errors>` is returned.
-
-- If your data source requires a
-  :ref:`Verified Signature <embedding-procedure>`, the signature
-  validity (including the expiry date) is checked on each refresh. If
-  the signature's expiry date passed, the host web page must
-  regenerate a new signature to continue rendering charts. For
-  code examples using verified signatures, see
-  `MongoDB Charts Embedding Examples <https://github.com/mongodb/charts-embedding-examples>`__
-  on GitHub.
-
-  .. example::
-
-     If you specify an automatic refresh interval of one minute and the
-     expiry date of the signature is in 1 hour, the chart refreshes
-     every minute for an hour. Once one hour has elapsed, the chart
-     will not render and an error will be displayed as the signature is
-     no longer valid. The host web page must regenerate a new signature
-     to resume rendering the chart.
-
 .. _embed-options-filter:
 
 Specify a Filter
@@ -193,3 +92,164 @@ filter is:
 The server-side code creates a payload with the necessary information
 to render the chart, including the filter. The payload ensures that
 the verified signature is valid before rendering the chart.
+
+.. _embed-options-refresh:
+
+Specify a Refresh Interval
+--------------------------
+
+Use the ``autorefresh`` query parameter to define the interval,
+in seconds, at which the chart refreshes with the latest data from
+its :ref:`data source <data-sources>`. Use the options on the 
+:guilabel:`Unauthenticated` tab on the :guilabel:`Embed Chart` dialog
+to customize the ``autorefresh`` value in the iframe snippet.
+
+If you do not specify the ``autorefresh`` option, your embedded chart 
+loads once when the iframe loads and does not automatically refresh.
+
+Example
+~~~~~~~
+
+The following iframe embeds a chart which automatically refreshes
+every 30 seconds as defined by the ``autorefresh=30`` query parameter:
+
+.. code-block:: html
+
+   <iframe style="border: none;border-radius: 2px;box-shadow: 0 2px
+   10px 0 rgba(70, 76, 79, .2);" width="640" height="480" src="
+   {charts-host}/embed/charts?id=b3ca720f-4b4a-40b4-a726-e7dc0c49aa1c&
+   tenant=c184f559-a6d6-4c17-a524-fde31193e498&autorefresh=30"></iframe>
+
+Considerations
+~~~~~~~~~~~~~~
+
+- The minimum automatic refresh interval is 10 seconds. If you specify
+  an ``autorefresh`` value less than 10, the chart refreshes every 10
+  seconds.
+
+- If you specify an ``autorefresh`` value which is not an integer or
+  less than 0, an :ref:`error <embedded-errors>` is returned.
+
+- If your data source requires a
+  :ref:`Verified Signature <embedding-procedure>`, the signature
+  validity (including the expiry date) is checked on each refresh. If
+  the signature's expiry date passed, the host web page must
+  regenerate a new signature to continue rendering charts. For
+  code examples using verified signatures, see
+  `MongoDB Charts Embedding Examples <https://github.com/mongodb/charts-embedding-examples>`__
+  on GitHub.
+
+  .. example::
+
+     If you specify an automatic refresh interval of one minute and the
+     expiry date of the signature is in 1 hour, the chart refreshes
+     every minute for an hour. Once one hour has elapsed, the chart
+     will not render and an error will be displayed as the signature is
+     no longer valid. The host web page must regenerate a new signature
+     to resume rendering the chart.
+
+Specify a Display Theme
+-----------------------
+
+Use the ``theme`` query parameter to select a display theme:
+
+- ``light``: chart axes and text are optimized for presentation against 
+  a light or white background.
+- ``dark``: chart axes and text are optimized for presentation against a 
+  dark or black background.
+
+Choosing a ``theme`` value only updates the iframe snippet you use to 
+embed the chart in your application. The chart is not saved with a ``theme`` value. The chart renders with the light theme by default. 
+Embedded charts that do not include the theme parameter also render with 
+the light theme.
+
+.. note::
+   Choosing the ``light`` or  ``dark`` theme does not change the color 
+   palette that chart data elements use. All bars and marks display 
+   using the default palette or the custom palette the chart author 
+   chose.
+
+   For example, if you choose a chart bar to render in black, choosing
+   the ``dark`` theme does not change the color of this bar to make it 
+   more visible against a dark background.
+
+Customization
+~~~~~~~~~~~~~
+
+|charts| adds inline style properties to the iframe snippet you copy 
+from the UI that add a background color and a border with a box shadow 
+to the embedded chart based on the theme you selected:
+
+- ``light`` theme ``background``: ``#FFFFFF``
+- ``dark`` theme ``background``: ``#21313C``
+- ``border``: ``none``
+- ``border-radius``: ``2px``
+- ``box-shadow``: ``0 2px 10px 0 rgba(70, 76, 79, .2)``
+- ``width``: ``640``
+- ``height``: ``480``
+
+Change the values of the inline style properties to change how the 
+embedded chart displays in your application:
+
+- Change the value of the ``background`` property to any value 
+  supported by the ``background`` CSS property to display the chart 
+  against it. See `background 
+  <https://developer.mozilla.org/en-US/docs/Web/CSS/background>`__
+  in the MDN Web Docs for more information.
+
+- Remove the ``background`` property to display the chart with a 
+  transparent background, allowing your application's background to 
+  display through the chart.
+
+- Modify or remove the following properties to customize or remove the 
+  chart border:
+
+  - ``border``
+  - ``border-radius``
+  - ``box-shadow`` 
+
+- You can change the value of the ``theme`` query parameter in the 
+  iframe snippet after you paste it into your application. If you do, 
+  make sure you adjust the iframe's inline style properties to match the 
+  theme you choose.
+
+  .. example::
+
+     If you change the ``theme`` from ``light`` to ``dark``, adjust the 
+     value of the ``background`` property in the iframe snippet 
+     to display the chart against a dark background.
+
+     Chart using ``light`` theme with default ``light`` theme 
+     ``background`` of ``#FFFFFF``:
+
+     .. image:: /images/charts/light-theme-default.png
+
+     Chart using ``dark`` theme with default ``light`` theme 
+     ``background`` of ``#FFFFFF``:
+
+     .. image:: /images/charts/dark-theme-light-theme-values.png
+
+     Chart using ``dark`` theme with default ``dark`` theme ``background`` 
+     of ``#21313C``:
+
+     .. image:: /images/charts/dark-theme-dark-theme-values.png
+
+Example
+~~~~~~~
+
+The following iframe embeds a chart with the ``dark`` theme with the 
+default ``dark`` theme inline style properties. The code is formatted 
+for readability.
+
+.. code-block:: html
+   :copyable: false
+   :emphasize-lines: 2,3,7
+
+   <iframe style="
+   background: #21313C;border: none;border-radius: 2px;
+   box-shadow: 0 2px 10px 0 rgba(70, 76, 79, .2);" 
+   width="640" height="480" src="
+   https://charts.mongodb.com/charts-crllr/embed/charts?id=a1b2c3d4-a1b2-c3d4-9766-47b0b2daaff3&
+   tenant=a1b2c3d4-a1b2-a1b2-a1b2-bb7f36c9def6&
+   theme=dark
+   "></iframe>