DOCSP-15171/15172 doc for filter click events by element role (#464)

* DOCSP-15171 doc for filter click events by element role

* DOCSP-15171 updates for copy review feedback

* DOCSP-15171 updates for feedback

Author: kanchana-mongodb

source/handle-click-events.txt

@@ -52,6 +52,37 @@ object. The click event handler syntax looks similar to the following:
 
    chart.addEventListener("click", callback); 
 
+The event handler also allows you to define the mark roles for which 
+you want to receive event information, thus eliminating the need to 
+check the payload. The click event handler syntax for defining the mark 
+roles to filter by looks similar to the following: 
+
+.. code-block:: sh 
+   :copyable: false 
+
+   const options = { includes: [{ roles: ['mark', 'axis-label'] }] };
+   chart.addEventListener("click", callback, options);
+
+The click event handler must be added after the chart has finished 
+rendering, as shown in the following example: 
+
+.. example:: 
+
+   .. code-block:: sh 
+
+      chart.render(document.getElementById("chart")).then(
+           () => chart.addEventListener('click', 
+             (payload) => alert(JSON.stringify(payload)), 
+             options)
+         );
+
+.. note:: 
+
+   If you specify the ``options`` parameter, the click event handler 
+   captures events only if the clicked mark's role matches one of the 
+   values specified in the parameter. If you omit this parameter, the 
+   click event handler captures all click events on the chart. 
+
 .. _click-event-payload:
 
 Payload 
@@ -77,7 +108,7 @@ payload:
    .. code-block:: sh 
       :copyable: false 
 
-      chart.addEventListener("click", (payload) => {
+      {
         "chartId": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
         "chartTitle": "This is my chart's title", 
         "chartDescription": "This is my chart's description",
@@ -134,7 +165,7 @@ payload:
           "fill": "#8CB6F2" // fill color of the mark
         },
         "apiVersion": 1 // API version of event payload
-      }); 
+      }
 
 To learn more about the elements inside the payload object, see: 
 
@@ -227,6 +258,18 @@ filter document contains both the category and series filter pairs.
 Each filter must reference the actual data source fields used and not 
 their labels.
 
+On an embedded chart that includes event handlers with a filter for 
+element roles, the chart shows: 
+
+- The :icon-fa4:`hand-pointer-o` when you hover over an element that 
+  triggers a filtered click event 
+- The :icon-fa4:`mouse-pointer` when you hover over an element that  
+  doesn't trigger a click event
+
+If the event handler doesn't include filter for element roles, the 
+:icon-fa4:`hand-pointer-o` appears when you hover over any chart 
+element.
+
 .. _click-event-payload-target:
 
 ``target`` Element 
@@ -279,7 +322,9 @@ In the `example app
 <https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/click-events-basic>`__ 
 for basic handling of click events, when you click on an element on the 
 ``Movie Genres`` chart, the click event handler displays data based on 
-the clicked element. 
+the clicked element. In this example application, the chart shows the 
+:icon-fa4:`hand-pointer-o` on all chart elements because the chart 
+doesn't include a filter for mark roles.
 
 Each time you click on an element in the chart, the click event 
 listener refreshes the ``payload`` to reflect data from the ``x`` and 
@@ -303,13 +348,21 @@ In the `example app
 for interactive filtering, when you click on an element on the ``Movie 
 Genres`` chart, the embedding SDK generates a filter based on the 
 element on which you clicked and then applies the filter to a second 
-chart. 
-
-The click event listener generates a filter based on the ``y`` axis, 
-which represents the movie genres, and the lower and upper bound range, 
-which represents the decade. Each time you click on an element that 
-represents a specific genre and decade on the ``Movie Genres`` chart, 
-the ``Movie Details`` data table is filtered by the clicked element and 
-changes to display the movies available in that genre and decade. 
-
-Refer to the example app to view the full event payload.
+chart. In this example application, the chart shows: 
+
+- The :icon-fa4:`hand-pointer-o` when you hover over an interactive 
+  element
+- The :icon-fa4:`mouse-pointer` when you hover over an element which 
+  doesn't trigger a click event
+
+The click event listener triggers events only for the mark roles 
+specified through the ``options`` parameter. The payload defines a 
+filter based on the ``y`` axis, which represents the movie genres, and 
+the lower and upper bound range, which represents the decade. Each time 
+you click on an element that represents a specific genre and decade on 
+the ``Movie Genres`` chart, the ``Movie Details`` data table is 
+filtered by the clicked element and changes to display the movies 
+available in that genre and decade. 
+
+Refer to the example app to view the full a sample event handler 
+callback function.