MDL-70990 core_filter: Add new native filterContentUpdated event

The legacy M.core.event.FILTER_CONTENT_UPDATED event has been replaced with a
new core_filter/events::filterContentUpdated native DOM event.

The new event can be triggered using the `notifyFilterContentUpdated`
function, and by providing with an Array containing the HTMLElements
that were updated, for example:

```
import {notifyFilterContentUpdated} from 'core_filter/events';

const someHandler = e => {
    // ...
    const nodeList = Array.from(document.querySelectorAll('div'));
    notifyFilterContentUpdated(nodeList);
};
```

The new event can be listened to at any point in the DOM using the
following syntax:

```
import {eventTypes} from 'core_filter/events';

const handler = e => {
    // The list of HTMLElements in an Array.
    e.detail.nodes;
};

document.addEventListener(eventTypes.filterContentUpdated, handler);
```

A backward-compatabibility layer is included to ensure that any legacy
YUI event listener, or jQuery event listener are still called with the
same arguments.

This legacy bridges will be removed after Moodle 4.3.

filter/amd/src/events.js

@@ -0,0 +1,82 @@
+// This file is part of Moodle - http://moodle.org/ //
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Javascript events for the `core_filter` subsystem.
+ *
+ * @module     core_filters/events
+ * @copyright  2021 Andrew Nicols <[email protected]>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since      4.0
+ */
+
+import {dispatchEvent} from 'core/event_dispatcher';
+import {getList as normalistNodeList} from 'core/normalise';
+import jQuery from 'jquery';
+
+/**
+ * Events for the `core_filter` subsystem.
+ *
+ * @constant
+ * @property {String} filterContentUpdated See {@link event:filterContentUpdated}
+ */
+export const eventTypes = {
+    /**
+     * An event triggered when page content is updated and must be processed by the filter system.
+     *
+     * An example of this is loading user text that could have equations in it. MathJax can typeset the equations but
+     * only if it is notified that there are new nodes in the page that need processing.
+     *
+     * @event filterContentUpdated
+     * @type {CustomEvent}
+     * @property {Array} nodes The list of parent nodes which were updated
+     */
+    filterContentUpdated: 'core_filters/contentUpdated',
+};
+
+/**
+ * Trigger an event to indicate that the specified nodes were updated and should be processed by the filter system.
+ *
+ * @method notifyFilterContentUpdated
+ * @param {jQuery|Array} nodes
+ * @returns {CustomEvent}
+ * @fires filterContentUpdated
+ */
+export const notifyFilterContentUpdated = nodes => {
+    // Historically this could be a jQuery Object.
+    // Normalise the list of nodes to a NodeList.
+    nodes = normalistNodeList(nodes);
+
+    return dispatchEvent(eventTypes.filterContentUpdated, {nodes});
+};
+
+let legacyEventsRegistered = false;
+if (!legacyEventsRegistered) {
+    // The following event triggers are legacy and will be removed in the future.
+    // The following approach provides a backwards-compatability layer for the new events.
+    // Code should be updated to make use of native events.
+
+    Y.use('event', 'moodle-core-event', () => {
+        // Provide a backwards-compatability layer for YUI Events.
+        document.addEventListener(eventTypes.filterContentUpdated, e => {
+            // Trigger the legacy jQuery event.
+            jQuery(document).trigger(M.core.event.FILTER_CONTENT_UPDATED, [jQuery(e.detail.nodes)]);
+
+            // Trigger the legacy YUI event.
+            Y.fire(M.core.event.FILTER_CONTENT_UPDATED, {nodes: new Y.NodeList(e.detail.nodes)});
+        });
+    });
+
+    legacyEventsRegistered = true;
+}