@atlaskit/editor-plugin-interactivity 0.2.0 → 1.0.0

package/dist/es2019/collector/interaction-events.js

@@ -0,0 +1,55 @@
+/**
+ * The editor group an interaction belongs to, which is also the field the event reports it in.
+ *
+ * `editorOther` is the remainder — an interaction the browser counts that is neither typing nor
+ * pointing — so the three groups together cover whatever the browser calls an interaction.
+ */
+
+/**
+ * The events an interaction is made of, and the group they belong to. Both sides of the collector
+ * read this, so counting and grouping cannot disagree.
+ *
+ * These are the events Event Timing can report with a non-zero `interactionId`, so any of them can
+ * be the one an entry measured — and it is usually not the one the interaction is counted on: for a
+ * pointer press the slow part is normally the `click` handler.
+ *
+ * The counted event is at a different end of the interaction in each group, because what can go
+ * wrong differs. Typing is counted on `keydown`, since the browser opens a new interaction for
+ * every repeat of a held key, and nothing cancels a key press. Pointing is counted on `pointerup`,
+ * since a press cannot repeat but can be taken over by a scroll — which the browser does not count
+ * either, and in that case `pointerup` never arrives.
+ */
+const INTERACTION_EVENTS = {
+  keydown: {
+    group: 'editorTyping',
+    counts: true
+  },
+  keyup: {
+    group: 'editorTyping'
+  },
+  // Only while an IME composes: the browser counts the text it commits in the interaction of the
+  // key that caused it.
+  input: {
+    group: 'editorTyping'
+  },
+  pointerdown: {
+    group: 'editorPointer'
+  },
+  pointerup: {
+    group: 'editorPointer',
+    counts: true
+  },
+  click: {
+    group: 'editorPointer'
+  },
+  // Ends a pointer press the way `pointerup` does, so the browser counts it as an interaction.
+  contextmenu: {
+    group: 'editorPointer'
+  }
+};
+
+/** Derived, so the types listened for cannot drift from the table. */
+export const INTERACTION_EVENT_TYPES = Object.keys(INTERACTION_EVENTS);
+export function interactionEventKind(type) {
+  return INTERACTION_EVENTS[type];
+}

package/dist/es2019/collector/interaction-group.js

@@ -19,14 +19,28 @@ const REPORTED_QUANTILES = [0.9, 0.98];
  * whatever its latency was, and everything the event carries — the reported buckets, the
  * count, the sum, the maximum and the percentiles — is derived from that map when a snapshot
  * is taken. Nothing is computed while interactions arrive.
+ *
+ * The two counters count different populations: `add` takes the interactions Event Timing
+ * measured, `countTotal` takes all of them, including the ones below the 16 ms reporting threshold
+ * it never delivers. So `totalCount >= observedCount`, and the difference is how many were too
+ * fast to be measured.
  */
 export class InteractionGroup {
   constructor() {
     _defineProperty(this, "countByLatency", new Map());
+    _defineProperty(this, "totalCount", 0);
   }
   add(latencyMs) {
     this.increment(latencyMs);
   }
+
+  /**
+   * Counts an interaction towards the group's total, measured or not. `page` has no use for it:
+   * `performance.interactionCount` counts the page's interactions.
+   */
+  countTotal() {
+    this.totalCount += 1;
+  }
   remeasure(previousLatencyMs, latencyMs) {
     // Moved rather than counted again: the count belongs to the same interaction.
     this.decrement(previousLatencyMs);
@@ -35,9 +49,10 @@ export class InteractionGroup {
 
   /**
    * @param totalCount every interaction of the group, including those below the Event Timing
-   * reporting threshold, which this group never sees.
+   * reporting threshold. Defaults to what `countTotal` was told, which is where an editor
+   * group's total comes from; `page` passes `performance.interactionCount` instead.
    */
-  snapshot(totalCount) {
+  snapshot(totalCount = this.totalCount) {
     var _latencies;
     // Ascending, so the reported buckets come out in order and the last latency is the
     // maximum. Sorted once for everything below.

package/dist/es2019/collector/interaction-tracker.js

@@ -1,4 +1,6 @@
 import _defineProperty from "@babel/runtime/helpers/defineProperty";
+import { interactionEventKind } from './interaction-events';
+
 /**
  * The Event Timing fields this package reads. `interactionId` is missing from the DOM
  * typings' `PerformanceEventTiming`, so it is declared here as optional, which also makes
@@ -8,12 +10,13 @@ import _defineProperty from "@babel/runtime/helpers/defineProperty";
 /**
  * What an entry did to the interaction it belongs to: either it is the first entry of a new
  * interaction, or it measured an interaction that was already counted as slower than it was
- * known to be.
+ * known to be. Both carry the editor group of the interaction, if it is one of the editor's.
  */
 
 /**
- * How many interactions are remembered, so their growth can still be applied. Entries of one
- * interaction arrive within the interaction itself, so anything older is not needed.
+ * How many interactions are remembered, so their growth can still be applied, and how many of
+ * the editor's events. Entries of one interaction arrive within the interaction itself, so
+ * anything older than the last few hundred is not needed.
  */
 const MAX_TRACKED = 256;
 /**
@@ -23,7 +26,17 @@ const MAX_TRACKED = 256;
 const PRUNE_BATCH = 64;
 
 /**
- * Groups Event Timing entries into interactions.
+ * Identifies the event an entry measured: an entry's `startTime` is that event's timestamp and its
+ * `name` is its type. The type is in the key because browsers coarsen the timestamp, so two events
+ * of one task can share it — and events of one type are always of one group, so a collision cannot
+ * move an interaction into another group.
+ */
+function eventKey(type, timeStamp) {
+  return `${type}|${timeStamp}`;
+}
+
+/**
+ * Makes interactions out of what the two observers report, for one session.
  *
  * Entries sharing a non-zero `interactionId` are one interaction whose latency is the
  * maximum `duration` among them. Entries arrive incrementally, so an interaction's latency
@@ -33,6 +46,9 @@ const PRUNE_BATCH = 64;
  * A non-zero `interactionId` is the browser's own definition of an interaction, which is
  * also what INP filters on: it is assigned to the pointer and keyboard events that make one
  * up, and never to scrolling or pointer movement.
+ *
+ * The editor's events answer what an entry cannot: which interactions were with the editor, and
+ * how many there were, including the ones below the Event Timing reporting threshold.
  */
 export class InteractionTracker {
   /**
@@ -43,7 +59,8 @@ export class InteractionTracker {
    * be counted in both.
    */
   constructor(startsAfterInteractionId = 0) {
-    _defineProperty(this, "latencies", new Map());
+    _defineProperty(this, "interactions", new Map());
+    _defineProperty(this, "groupByEvent", new Map());
     _defineProperty(this, "highestInteractionId", 0);
     this.startsAfterInteractionId = startsAfterInteractionId;
   }
@@ -78,35 +95,58 @@ export class InteractionTracker {
     if (!Number.isFinite(entry.duration) || entry.duration < 0) {
       return undefined;
     }
-    const previousLatencyMs = this.latencies.get(interactionId);
-    if (previousLatencyMs === undefined) {
-      this.latencies.set(interactionId, entry.duration);
-      this.prune();
+    const tracked = this.interactions.get(interactionId);
+    if (tracked === undefined) {
+      // Taken once: an entry that only makes the interaction slower has to move its count
+      // within the group it was counted in, not into another one.
+      const group = this.groupByEvent.get(eventKey(entry.name, entry.startTime));
+      this.interactions.set(interactionId, {
+        latencyMs: entry.duration,
+        group
+      });
+      this.prune(this.interactions);
       return {
         type: 'new',
-        latencyMs: entry.duration
+        latencyMs: entry.duration,
+        group
       };
     }
-    if (entry.duration <= previousLatencyMs) {
+    if (entry.duration <= tracked.latencyMs) {
       return undefined;
     }
-    this.latencies.set(interactionId, entry.duration);
+    const fromMs = tracked.latencyMs;
+    tracked.latencyMs = entry.duration;
     return {
       type: 'remeasured',
-      fromMs: previousLatencyMs,
-      toMs: entry.duration
+      fromMs,
+      toMs: entry.duration,
+      group: tracked.group
     };
   }
-  prune() {
-    if (this.latencies.size <= MAX_TRACKED) {
+
+  /** @returns the group of an interaction to count, when this is the event its group counts on. */
+  recordEditorEvent(event) {
+    const kind = interactionEventKind(event.type);
+    if (!kind) {
+      return undefined;
+    }
+
+    // Every event of the interaction, because any of them can be the one Event Timing reports
+    // as the slowest: for a pointer press that is usually the click.
+    this.groupByEvent.set(eventKey(event.type, event.timeStamp), kind.group);
+    this.prune(this.groupByEvent);
+    return kind.counts ? kind.group : undefined;
+  }
+  prune(entries) {
+    if (entries.size <= MAX_TRACKED) {
       return;
     }
 
-    // `Map` preserves insertion order and `interactionId` increases monotonically,
-    // so the entries inserted first are the least likely to see another entry.
+    // `Map` preserves insertion order, so the entries inserted first are the least likely to
+    // see another entry or another event.
     let remaining = PRUNE_BATCH;
-    for (const interactionId of this.latencies.keys()) {
-      this.latencies.delete(interactionId);
+    for (const key of entries.keys()) {
+      entries.delete(key);
       remaining -= 1;
       if (remaining === 0) {
         return;

package/dist/es2019/collector/interactivity-collector.js

@@ -1,5 +1,6 @@
 import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import { getDocument } from '@atlaskit/browser-apis';
+import { EditorEventObserver } from './editor-event-observer';
 import { InteractionObserver } from './interaction-observer';
 import { InteractivitySession } from './interactivity-session';
 import { SCHEMA_VERSION } from './bucket-boundaries';
@@ -8,6 +9,9 @@ import { SnapshotScheduler } from './snapshot-scheduler';
 /**
  * Collects interaction latencies for one editor mount and emits session-to-date snapshots.
  *
+ * Every interaction is counted in `page`, and the ones with the editor again in one of the editor
+ * groups, which is what tells a slow editor apart from a slow page around it.
+ *
  * `start` and `stop` bound the collecting, which happens once. Within it there can be several
  * sessions, because a session covers one document in one mode: a Confluence live page
  * navigates and switches between reading and editing without ever remounting the editor, and
@@ -23,6 +27,7 @@ export class InteractivityCollector {
     this.getObjectId = options.getObjectId;
     this.getSessionMode = options.getSessionMode;
     this.interactionObserver = new InteractionObserver(entries => this.recordEntries(entries));
+    this.editorEvents = new EditorEventObserver(event => this.recordEditorEvent(event));
     this.snapshotScheduler = new SnapshotScheduler(() => this.onTimer());
     this.lifecycleObserver = new LifecycleObserver({
       onHidden: () => this.onHidden(),
@@ -55,6 +60,7 @@ export class InteractivityCollector {
     // this object was constructed.
     this.session = this.createSession(0);
     this.interactionObserver.start();
+    this.editorEvents.observe(this.editorRoot);
     this.snapshotScheduler.start();
     this.lifecycleObserver.start();
     this.started = true;
@@ -69,10 +75,22 @@ export class InteractivityCollector {
     this.takeSnapshot('unmount');
     this.stopped = true;
     this.interactionObserver.stop();
+    this.editorEvents.stop();
     this.snapshotScheduler.stop();
     this.lifecycleObserver.stop();
   }
 
+  /**
+   * The element the editor renders itself into is what makes an interaction one of the editor's.
+   * The session is not tied to it: interactions from before it arrives are counted in `page`.
+   */
+  setEditorRoot(root) {
+    this.editorRoot = root !== null && root !== void 0 ? root : undefined;
+    if (this.started && !this.stopped) {
+      this.editorEvents.observe(this.editorRoot);
+    }
+  }
+
   /**
    * Rotates the session when the editor is pointed at different content.
    *
@@ -164,6 +182,24 @@ export class InteractivityCollector {
   onPageShow() {
     this.session.lifecycleSnapshotEmitted = false;
   }
+
+  /**
+   * Counts an interaction with the editor, including the ones Event Timing never reports because
+   * they were faster than its threshold — which is why a count alone moves the session on.
+   */
+  recordEditorEvent(event) {
+    if (this.stopped) {
+      return;
+    }
+    const group = this.session.tracker.recordEditorEvent(event);
+    if (!group) {
+      return;
+    }
+
+    // The session names its editor groups after the fields they are reported in.
+    this.session[group].countTotal();
+    this.session.revision += 1;
+  }
   recordEntries(entries) {
     const {
       tracker,
@@ -176,8 +212,14 @@ export class InteractivityCollector {
       }
       if (update.type === 'new') {
         page.add(update.latencyMs);
+        if (update.group) {
+          this.session[update.group].add(update.latencyMs);
+        }
       } else {
         page.remeasure(update.fromMs, update.toMs);
+        if (update.group) {
+          this.session[update.group].remeasure(update.fromMs, update.toMs);
+        }
       }
       this.session.revision += 1;
     }
@@ -210,7 +252,7 @@ export class InteractivityCollector {
     session.emittedRevision = session.revision;
     const now = performance.now();
     const hiddenMs = session.hiddenMs + (session.hiddenSince === undefined ? 0 : now - session.hiddenSince);
-    const totalCount = InteractionObserver.readPageInteractionCount() - session.interactionCountAtStart;
+    const pageTotalCount = InteractionObserver.readPageInteractionCount() - session.interactionCountAtStart;
     this.emit({
       schema: SCHEMA_VERSION,
       interactivitySessionId: session.id,
@@ -222,7 +264,11 @@ export class InteractivityCollector {
       hiddenMs: Math.round(hiddenMs),
       nodeSize: this.getNodeSize(),
       editorDomSize: this.getEditorDomSize(),
-      page: session.page.snapshot(totalCount)
+      // Only `page` is told its total; each editor group has counted its own.
+      page: session.page.snapshot(pageTotalCount),
+      editorTyping: session.editorTyping.snapshot(),
+      editorPointer: session.editorPointer.snapshot(),
+      editorOther: session.editorOther.snapshot()
     });
   }
 }

package/dist/es2019/collector/interactivity-session.js

@@ -23,6 +23,9 @@ export class InteractivitySession {
     /** Page interaction count when the session opened, subtracted to get its own total. */
     _defineProperty(this, "interactionCountAtStart", InteractionObserver.readPageInteractionCount());
     _defineProperty(this, "page", new InteractionGroup());
+    _defineProperty(this, "editorTyping", new InteractionGroup());
+    _defineProperty(this, "editorPointer", new InteractionGroup());
+    _defineProperty(this, "editorOther", new InteractionGroup());
     /** Increments per snapshot; a query takes the highest one per session. */
     _defineProperty(this, "seq", 0);
     _defineProperty(this, "hiddenMs", 0);

package/dist/es2019/interactivityPlugin.js

@@ -1,4 +1,4 @@
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
 import { logException } from '@atlaskit/editor-common/monitoring';
 import { fireInteractivityEvent } from './analytics/fire-interactivity-event';
 import { InteractivityCollector } from './collector/interactivity-collector';
@@ -16,12 +16,11 @@ export const interactivityPlugin = ({
 }) => ({
   name: 'interactivity',
   usePluginHook({
-    editorView
+    editorView,
+    wrapperElement
   }) {
+    const collectorRef = useRef(undefined);
     useEffect(() => {
-      // Nothing measured here is worth an editor. This effect runs inside the plugin slot's
-      // error boundary, which also renders every plugin's content components, so a throw
-      // from instrumentation would take that UI down with it.
       try {
         var _api$contextIdentifie4, _api$editorViewMode2;
         const collector = new InteractivityCollector({
@@ -48,6 +47,9 @@ export const interactivityPlugin = ({
           // cannot overflow the stack on very large documents.
           getEditorDomSize: () => editorView.isDestroyed ? undefined : editorView.dom.getElementsByTagName('*').length
         });
+
+        // Effects run in declaration order, so the one below always finds it.
+        collectorRef.current = collector;
         if (!collector.start()) {
           return;
         }
@@ -75,5 +77,15 @@ export const interactivityPlugin = ({
       // live registry, and restarting the session on a reconfigure would split one
       // editor session in two.
     }, [editorView]);
+    useEffect(() => {
+      try {
+        var _collectorRef$current;
+        (_collectorRef$current = collectorRef.current) === null || _collectorRef$current === void 0 ? void 0 : _collectorRef$current.setEditorRoot(wrapperElement);
+      } catch (error) {
+        void logException(error, {
+          location: 'editor-plugin-interactivity/observe'
+        });
+      }
+    }, [wrapperElement]);
   }
 });

package/dist/esm/collector/editor-event-observer.js

@@ -0,0 +1,57 @@
+import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
+import _createClass from "@babel/runtime/helpers/createClass";
+import { bindAll } from 'bind-event-listener';
+import { INTERACTION_EVENT_TYPES } from './interaction-events';
+
+/**
+ * Reports the events the interactions with the editor are made of, as the browser dispatched
+ * them. What they mean is the tracker's business.
+ *
+ * Event Timing cannot answer which interactions were with the editor, because it observes the
+ * whole document, nor how many there were, because it reports none below 16 ms.
+ */
+export var EditorEventObserver = /*#__PURE__*/function () {
+  function EditorEventObserver(onEvent) {
+    _classCallCheck(this, EditorEventObserver);
+    this.onEvent = onEvent;
+  }
+
+  /**
+   * Called as the element the editor renders itself into changes: the editor only knows it after
+   * its first render, and can replace it.
+   */
+  return _createClass(EditorEventObserver, [{
+    key: "observe",
+    value: function observe(root) {
+      var _this = this;
+      var next = root !== null && root !== void 0 ? root : undefined;
+      if (next === this.root) {
+        return;
+      }
+      this.stop();
+      this.root = next;
+      if (!next) {
+        return;
+      }
+      this.unbind = bindAll(next, INTERACTION_EVENT_TYPES.map(function (type) {
+        return {
+          type: type,
+          listener: _this.onEvent
+        };
+      }),
+      // Capture, so a handler in the editor cannot stop an interaction from being reported.
+      {
+        capture: true,
+        passive: true
+      });
+    }
+  }, {
+    key: "stop",
+    value: function stop() {
+      var _this$unbind;
+      (_this$unbind = this.unbind) === null || _this$unbind === void 0 || _this$unbind.call(this);
+      this.unbind = undefined;
+      this.root = undefined;
+    }
+  }]);
+}();

package/dist/esm/collector/interaction-events.js

@@ -0,0 +1,55 @@
+/**
+ * The editor group an interaction belongs to, which is also the field the event reports it in.
+ *
+ * `editorOther` is the remainder — an interaction the browser counts that is neither typing nor
+ * pointing — so the three groups together cover whatever the browser calls an interaction.
+ */
+
+/**
+ * The events an interaction is made of, and the group they belong to. Both sides of the collector
+ * read this, so counting and grouping cannot disagree.
+ *
+ * These are the events Event Timing can report with a non-zero `interactionId`, so any of them can
+ * be the one an entry measured — and it is usually not the one the interaction is counted on: for a
+ * pointer press the slow part is normally the `click` handler.
+ *
+ * The counted event is at a different end of the interaction in each group, because what can go
+ * wrong differs. Typing is counted on `keydown`, since the browser opens a new interaction for
+ * every repeat of a held key, and nothing cancels a key press. Pointing is counted on `pointerup`,
+ * since a press cannot repeat but can be taken over by a scroll — which the browser does not count
+ * either, and in that case `pointerup` never arrives.
+ */
+var INTERACTION_EVENTS = {
+  keydown: {
+    group: 'editorTyping',
+    counts: true
+  },
+  keyup: {
+    group: 'editorTyping'
+  },
+  // Only while an IME composes: the browser counts the text it commits in the interaction of the
+  // key that caused it.
+  input: {
+    group: 'editorTyping'
+  },
+  pointerdown: {
+    group: 'editorPointer'
+  },
+  pointerup: {
+    group: 'editorPointer',
+    counts: true
+  },
+  click: {
+    group: 'editorPointer'
+  },
+  // Ends a pointer press the way `pointerup` does, so the browser counts it as an interaction.
+  contextmenu: {
+    group: 'editorPointer'
+  }
+};
+
+/** Derived, so the types listened for cannot drift from the table. */
+export var INTERACTION_EVENT_TYPES = Object.keys(INTERACTION_EVENTS);
+export function interactionEventKind(type) {
+  return INTERACTION_EVENTS[type];
+}

package/dist/esm/collector/interaction-group.js

@@ -24,17 +24,33 @@ var REPORTED_QUANTILES = [0.9, 0.98];
  * whatever its latency was, and everything the event carries — the reported buckets, the
  * count, the sum, the maximum and the percentiles — is derived from that map when a snapshot
  * is taken. Nothing is computed while interactions arrive.
+ *
+ * The two counters count different populations: `add` takes the interactions Event Timing
+ * measured, `countTotal` takes all of them, including the ones below the 16 ms reporting threshold
+ * it never delivers. So `totalCount >= observedCount`, and the difference is how many were too
+ * fast to be measured.
  */
 export var InteractionGroup = /*#__PURE__*/function () {
   function InteractionGroup() {
     _classCallCheck(this, InteractionGroup);
     _defineProperty(this, "countByLatency", new Map());
+    _defineProperty(this, "totalCount", 0);
   }
   return _createClass(InteractionGroup, [{
     key: "add",
     value: function add(latencyMs) {
       this.increment(latencyMs);
     }
+
+    /**
+     * Counts an interaction towards the group's total, measured or not. `page` has no use for it:
+     * `performance.interactionCount` counts the page's interactions.
+     */
+  }, {
+    key: "countTotal",
+    value: function countTotal() {
+      this.totalCount += 1;
+    }
   }, {
     key: "remeasure",
     value: function remeasure(previousLatencyMs, latencyMs) {
@@ -45,12 +61,14 @@ export var InteractionGroup = /*#__PURE__*/function () {
 
     /**
      * @param totalCount every interaction of the group, including those below the Event Timing
-     * reporting threshold, which this group never sees.
+     * reporting threshold. Defaults to what `countTotal` was told, which is where an editor
+     * group's total comes from; `page` passes `performance.interactionCount` instead.
      */
   }, {
     key: "snapshot",
-    value: function snapshot(totalCount) {
+    value: function snapshot() {
       var _latencies;
+      var totalCount = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : this.totalCount;
       // Ascending, so the reported buckets come out in order and the last latency is the
       // maximum. Sorted once for everything below.
       var latencies = Array.from(this.countByLatency.keys()).sort(function (a, b) {