feat(core): Add event delegation library to queue up events and replay them when the application is ready (#55121)

This adds the JSAction library from the Wiz framework to core/primitives.

PR Close #55121

Author: iteriani

packages/core/primitives/event-dispatch/BUILD.bazel

@@ -0,0 +1,28 @@
+load("//tools:defaults.bzl", "ts_library", "tsec_test")
+
+package(default_visibility = ["//visibility:public"])
+
+ts_library(
+    name = "event-dispatch",
+    srcs = glob(
+        [
+            "**/*.ts",
+        ],
+    ),
+    module_name = "@angular/core/primitives/event-dispatch",
+)
+
+tsec_test(
+    name = "tsec_test",
+    target = "event-dispatch",
+    tsconfig = "//packages:tsec_config",
+)
+
+filegroup(
+    name = "files_for_docgen",
+    srcs = glob([
+        "*.ts",
+        "src/**/*.ts",
+    ]),
+    visibility = ["//visibility:public"],
+)

packages/core/primitives/event-dispatch/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+
+export {Dispatcher, registerDispatcher} from './src/dispatcher';
+export {EventContractContainer} from './src/event_contract_container';
+export {EventContract} from './src/eventcontract';
+export {bootstrapEventContract} from './src/register_events';

packages/core/primitives/event-dispatch/src/a11y_click.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import * as eventLib from './event';
+import * as eventInfoLib from './event_info';
+import {EventType} from './event_type';
+
+/**
+ * Update `EventInfo` to be `eventType = 'click'` and sets `a11yClickKey` if it
+ * is a a11y click.
+ */
+export function updateEventInfoForA11yClick(eventInfo: eventInfoLib.EventInfo) {
+  if (!eventLib.isActionKeyEvent(eventInfoLib.getEvent(eventInfo))) {
+    return;
+  }
+  eventInfoLib.setA11yClickKey(eventInfo, true);
+  // A 'click' triggered by a DOM keypress should be mapped to the 'click'
+  // jsaction.
+  eventInfoLib.setEventType(eventInfo, EventType.CLICK);
+}
+
+/**
+ * Call `preventDefault` on an a11y click if it is space key or to prevent the
+ * browser's default action for native HTML controls.
+ */
+export function preventDefaultForA11yClick(eventInfo: eventInfoLib.EventInfo) {
+  if (!eventInfoLib.getA11yClickKey(eventInfo) ||
+      (!eventLib.isSpaceKeyEvent(eventInfoLib.getEvent(eventInfo)) &&
+       !eventLib.shouldCallPreventDefaultOnNativeHtmlControl(
+           eventInfoLib.getEvent(eventInfo),
+           ))) {
+    return;
+  }
+  eventLib.preventDefault(eventInfoLib.getEvent(eventInfo));
+}
+
+/**
+ * Sets the `action` to `clickonly` for a click event that is not an a11y click
+ * and if there is not already a click action.
+ */
+export function populateClickOnlyAction(
+    eventInfo: eventInfoLib.EventInfo,
+    actionMap: {[key: string]: string},
+) {
+  if (eventInfoLib.getEventType(eventInfo) === EventType.CLICK &&
+      // No a11y clicks should map to 'clickonly'.
+      !eventInfoLib.getA11yClickKey(eventInfo) && !actionMap[EventType.CLICK] &&
+      actionMap[EventType.CLICKONLY]) {
+    // A 'click' triggered by a DOM click should be mapped to the 'click'
+    // jsaction, if available, or else fallback to the 'clickonly' jsaction.
+    // If 'click' and 'clickonly' jsactions are used together, 'click' will
+    // prevail.
+    eventInfoLib.setEventType(eventInfo, EventType.CLICKONLY);
+    eventInfoLib.setAction(eventInfo, actionMap[EventType.CLICKONLY]);
+  }
+}

packages/core/primitives/event-dispatch/src/accessibility.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+/**
+ * Defines special EventInfo and Event properties used when
+ * A11Y_SUPPORT_IN_DISPATCHER is enabled.
+ */
+export enum Attribute {
+  /**
+   * An event-type set when the event contract detects a KEYDOWN event but
+   * doesn't know if the key press can be treated like a click. The dispatcher
+   * will use this event-type to parse the keypress and handle it accordingly.
+   */
+  MAYBE_CLICK_EVENT_TYPE = 'maybe_click',
+
+  /**
+   * A property added to a dispatched event that had the MAYBE_CLICK_EVENTTYPE
+   * event-type but could not be used as a click. The dispatcher sets this
+   * property for non-global dispatches before it retriggers the event and it
+   * signifies that the event contract should not dispatch this event globally.
+   */
+  SKIP_GLOBAL_DISPATCH = 'a11ysgd',
+
+  /**
+   * A property added to a dispatched event that had the MAYBE_CLICK_EVENTTYPE
+   * event-type but could not be used as a click. The dispatcher sets this
+   * property before it retriggers the event and it signifies that the event
+   * contract should not look at CLICK actions for KEYDOWN events.
+   */
+  SKIP_A11Y_CHECK = 'a11ysc',
+}
+
+declare global {
+  interface Event {
+    [Attribute.MAYBE_CLICK_EVENT_TYPE]?: boolean;
+    [Attribute.SKIP_GLOBAL_DISPATCH]?: boolean;
+    [Attribute.SKIP_A11Y_CHECK]?: boolean;
+  }
+}

packages/core/primitives/event-dispatch/src/attribute.ts

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+export enum Attribute {
+  /**
+   * The jsaction attribute defines a mapping of a DOM event to a
+   * generic event (aka jsaction), to which the actual event handlers
+   * that implement the behavior of the application are bound. The
+   * value is a semicolon separated list of colon separated pairs of
+   * an optional DOM event name and a jsaction name. If the optional
+   * DOM event name is omitted, 'click' is assumed. The jsaction names
+   * are dot separated pairs of a namespace and a simple jsaction
+   * name. If the namespace is absent, it is taken from the closest
+   * ancestor element with a jsnamespace attribute, if there is
+   * any. If there is no ancestor with a jsnamespace attribute, the
+   * simple name is assumed to be the jsaction name.
+   *
+   * Used by EventContract.
+   */
+  JSACTION = 'jsaction',
+
+  /**
+   * The jsnamespace attribute provides the namespace part of the
+   * jaction names occurring in the jsaction attribute where it's
+   * missing.
+   *
+   * Used by EventContract.
+   */
+  JSNAMESPACE = 'jsnamespace',
+
+  /**
+   * The oi attribute is a log impression tag for impression logging
+   * and action tracking. For an element that carries a jsaction
+   * attribute, the element is identified for the purpose of
+   * impression logging and click tracking by the dot separated path
+   * of all oi attributes in the chain of ancestors of the element.
+   *
+   * Used by ActionFlow.
+   */
+  OI = 'oi',
+
+  /**
+   * The ved attribute is an encoded ClickTrackingCGI proto to track
+   * visual elements.
+   *
+   * Used by ActionFlow.
+   */
+  VED = 'ved',
+
+  /**
+   * The vet attribute is the visual element type used to identify tracked
+   * visual elements.
+   */
+  VET = 'vet',
+
+  /**
+   * Support for iteration on reprocessing.
+   *
+   * Used by ActionFlow.
+   */
+  JSINSTANCE = 'jsinstance',
+
+  /**
+   * All click jsactions that happen on the element that carries this
+   * attribute or its descendants are automatically logged.
+   * Impressions of jsactions on these elements are tracked too, if
+   * requested by the impression() method of ActionFlow.
+   *
+   * Used by ActionFlow.
+   */
+  JSTRACK = 'jstrack'
+}

packages/core/primitives/event-dispatch/src/cache.ts

@@ -0,0 +1,104 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Property} from './property';
+
+/**
+ * Map from jsaction annotation to a parsed map from event name to action name.
+ */
+const parseCache: {[key: string]: {[key: string]: string}} = {};
+
+/**
+ * Reads the jsaction parser cache from the given DOM Element.
+ *
+ * @param element .
+ * @return Map from event to qualified name of the jsaction bound to it.
+ */
+export function get(element: Element): {[key: string]: string} {
+  // @ts-ignore
+  return element[Property.JSACTION];
+}
+
+/**
+ * Writes the jsaction parser cache to the given DOM Element.
+ *
+ * @param element .
+ * @param actionMap Map from event to qualified name of the jsaction bound to
+ *     it.
+ */
+export function set(element: Element, actionMap: {[key: string]: string}) {
+  // @ts-ignore
+  element[Property.JSACTION] = actionMap;
+}
+
+/**
+ * Looks up the parsed action map from the source jsaction attribute value.
+ *
+ * @param text Unparsed jsaction attribute value.
+ * @return Parsed jsaction attribute value, if already present in the cache.
+ */
+export function getParsed(text: string): {[key: string]: string}|undefined {
+  return parseCache[text];
+}
+
+/**
+ * Inserts the parse result for the given source jsaction value into the cache.
+ *
+ * @param text Unparsed jsaction attribute value.
+ * @param parsed Attribute value parsed into the action map.
+ */
+export function setParsed(text: string, parsed: {[key: string]: string}) {
+  parseCache[text] = parsed;
+}
+
+/**
+ * Clears the jsaction parser cache from the given DOM Element.
+ *
+ * @param element .
+ */
+export function clear(element: Element) {
+  if (Property.JSACTION in element) {
+    delete element[Property.JSACTION];
+  }
+}
+
+/**
+ * Reads the cached jsaction namespace from the given DOM
+ * Element. Undefined means there is no cached value; null is a cached
+ * jsnamespace attribute that's absent.
+ *
+ * @param element .
+ * @return .
+ */
+export function getNamespace(element: Element): string|null|undefined {
+  // @ts-ignore
+  return element[Property.JSNAMESPACE];
+}
+
+/**
+ * Writes the cached jsaction namespace to the given DOM Element. Null
+ * represents a jsnamespace attribute that's absent.
+ *
+ * @param element .
+ * @param jsnamespace .
+ */
+export function setNamespace(element: Element, jsnamespace: string|null) {
+  // @ts-ignore
+  element[Property.JSNAMESPACE] = jsnamespace;
+}
+
+/**
+ * Clears the cached jsaction namespace from the given DOM Element.
+ *
+ * @param element .
+ */
+export function clearNamespace(element: Element) {
+  if (Property.JSNAMESPACE in element) {
+    delete element[Property.JSNAMESPACE];
+  }
+}

packages/core/primitives/event-dispatch/src/char.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+export const Char = {
+  /**
+   * The separator between the namespace and the action name in the
+   * jsaction attribute value.
+   */
+  NAMESPACE_ACTION_SEPARATOR: '.',
+
+  /**
+   * The separator between the event name and action in the jsaction
+   * attribute value.
+   */
+  EVENT_ACTION_SEPARATOR: ':',
+
+  /**
+   * The separator between the logged oi attribute values in the &oi=
+   * URL parameter value.
+   */
+  OI_SEPARATOR: '.',
+
+  /**
+   * The separator between the key and the value pairs in the &cad=
+   * URL parameter value.
+   */
+  CAD_KEY_VALUE_SEPARATOR: ':',
+
+  /**
+   * The separator between the key-value pairs in the &cad= URL
+   * parameter value.
+   */
+  CAD_SEPARATOR: ',',
+};