@atlaskit/editor-plugin-limited-mode 14.0.0 → 14.1.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @atlaskit/editor-plugin-limited-mode
 
+## 14.1.1
+
+### Patch Changes
+
+- Updated dependencies
+
+## 14.1.0
+
+### Minor Changes
+
+- [`aec3fcfe13ff9`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/aec3fcfe13ff9) -
+  EDITOR-8303 Add runtime input-latency trigger for limited mode behind
+  platform_editor_dynamic_limited_mode. Limited mode can now latch mid-session when sustained slow
+  input or repeated browser freezes indicate the device is struggling, in addition to the existing
+  document-size decision. The latch is one-way. Nothing is constructed when the experiment is off.
+
+  How much evidence is needed is a single tunable, `requiredConfirmations`: that many qualifying
+  windows, each separated from the last by `confirmationGapMs`. The hardware no longer feeds into
+  the decision — `navigator.hardwareConcurrency` and `navigator.deviceMemory` are reported with the
+  `limitedModeLatched` event instead, so which devices latch can be answered from the data rather
+  than assumed up front.
+
+  `LimitedModePluginState` gains a derived `enabled` flag, which is now the single thing consumers
+  should branch on — the individual reasons (`documentSizeBreachesThreshold`, `latchPolicyBreached`)
+  no longer need to be combined at each call site, so a future reason needs no change outside this
+  plugin. `sharedState.enabled` reads from it.
+
+  Under the experiment the document decision is also evaluated on load and on document replacement
+  only, rather than on every transaction that changes the document. That check walks the whole
+  document, so it was a full-document scan per keystroke on exactly the pages least able to afford
+  one. The trade-off is that a document editing its way past the thresholds is not re-judged until
+  it next loads.
+
+  Consumers updated to react to a mid-session change: table sticky headers now subscribe instead of
+  reading once at construction, block-controls resets rather than freezes its state on entry, and
+  the expand, media and table nodeviews read the derived flag so they no longer miss a runtime
+  latch.
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 14.0.0
 
 ### Patch Changes

package/afm-cc/tsconfig.json

@@ -17,9 +17,18 @@
 		"../src/**/examples.*"
 	],
 	"references": [
+		{
+			"path": "../../editor-plugin-analytics/afm-cc/tsconfig.json"
+		},
 		{
 			"path": "../../editor-prosemirror/afm-cc/tsconfig.json"
 		},
+		{
+			"path": "../../../measurement/feature-gate-js-client/afm-cc/tsconfig.json"
+		},
+		{
+			"path": "../../../platform/feature-experiments/afm-cc/tsconfig.json"
+		},
 		{
 			"path": "../../../platform/feature-flags/afm-cc/tsconfig.json"
 		},

package/dist/cjs/limitedModePlugin.js

@@ -7,6 +7,7 @@ exports.limitedModePlugin = void 0;
 var _nodeAnchor = require("@atlaskit/editor-common/node-anchor");
 var _usePluginStateEffect = require("@atlaskit/editor-common/use-plugin-state-effect");
 var _expValEquals = require("@atlaskit/tmp-editor-statsig/exp-val-equals");
+var _pluginKey = require("./pm-plugins/plugin-key");
 var _main = require("./pm-plugins/main");
 var limitedModePlugin = exports.limitedModePlugin = function limitedModePlugin(_ref) {
   var api = _ref.api;
@@ -15,7 +16,9 @@ var limitedModePlugin = exports.limitedModePlugin = function limitedModePlugin(_
     pmPlugins: function pmPlugins() {
       return [{
         name: 'limitedModePlugin',
-        plugin: _main.createPlugin
+        plugin: function plugin() {
+          return (0, _main.createPlugin)(api);
+        }
       }];
     },
     getSharedState: function getSharedState(editorState) {
@@ -23,14 +26,14 @@ var limitedModePlugin = exports.limitedModePlugin = function limitedModePlugin(_
         return {
           get enabled() {
             var _limitedModePluginKey, _limitedModePluginKey2;
-            return (_limitedModePluginKey = (_limitedModePluginKey2 = _main.limitedModePluginKey.getState(editorState)) === null || _limitedModePluginKey2 === void 0 ? void 0 : _limitedModePluginKey2.documentSizeBreachesThreshold) !== null && _limitedModePluginKey !== void 0 ? _limitedModePluginKey : false;
+            return (_limitedModePluginKey = (_limitedModePluginKey2 = _pluginKey.limitedModePluginKey.getState(editorState)) === null || _limitedModePluginKey2 === void 0 ? void 0 : _limitedModePluginKey2.enabled) !== null && _limitedModePluginKey !== void 0 ? _limitedModePluginKey : false;
           },
-          limitedModePluginKey: _main.limitedModePluginKey
+          limitedModePluginKey: _pluginKey.limitedModePluginKey
         };
       }
       return {
         enabled: false,
-        limitedModePluginKey: _main.limitedModePluginKey
+        limitedModePluginKey: _pluginKey.limitedModePluginKey
       };
     },
     usePluginHook: function usePluginHook(_ref2) {

package/dist/cjs/pm-plugins/main.js

@@ -1,35 +1,218 @@
 "use strict";
 
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.limitedModePluginKey = exports.createPlugin = void 0;
+exports.createPlugin = void 0;
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _analytics = require("@atlaskit/editor-common/analytics");
 var _safePlugin = require("@atlaskit/editor-common/safe-plugin");
 var _shouldEnableLimitedMode = require("@atlaskit/editor-common/should-enable-limited-mode");
-var _state = require("@atlaskit/editor-prosemirror/state");
-var limitedModePluginKey = exports.limitedModePluginKey = new _state.PluginKey('limitedModePlugin');
-var createPlugin = exports.createPlugin = function createPlugin() {
+var _isExperimentEnabled = require("@atlaskit/platform-feature-experiments/is-experiment-enabled");
+var _expVal = require("@atlaskit/platform-feature-experiments/exp-val");
+var _pluginKey = require("./plugin-key");
+var _latchDetector = require("./utils/latch-detector");
+var _latchPolicy = require("./utils/latch-policy");
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+/**
+ * Meta shape used to latch limited mode at runtime. Dispatching this is the entire delivery
+ * mechanism: the transaction flows through `SharedStateAPI.notifyListeners`, which diffs the plugin's
+ * shared state and notifies every consumer. No plugin re-registration and no schema rebuild.
+ */
+
+/**
+ * Hardware hints, reported with a latch so it can be correlated with device class.
+ *
+ * Telemetry only — the policy no longer takes the hardware into account when deciding, so this
+ * exists to answer "which devices are latching" from the data rather than by assumption. Both hints
+ * are optional (`deviceMemory` is Chromium-only) and are simply absent where unsupported.
+ */
+var getDeviceHints = function getDeviceHints() {
+  if (typeof navigator === 'undefined') {
+    return {};
+  }
+  var _ref = navigator,
+    hardwareConcurrency = _ref.hardwareConcurrency,
+    deviceMemory = _ref.deviceMemory;
+  return {
+    hardwareConcurrency: hardwareConcurrency,
+    deviceMemoryGb: deviceMemory
+  };
+};
+
+/** Control-arm state: the document decision alone, exactly as before the experiment. */
+var documentOnlyState = function documentOnlyState(doc) {
+  var documentSizeBreachesThreshold = (0, _shouldEnableLimitedMode.shouldEnableLimitedModeForDocument)(doc);
+  return {
+    documentSizeBreachesThreshold: documentSizeBreachesThreshold,
+    latchPolicyBreached: false,
+    enabled: documentSizeBreachesThreshold
+  };
+};
+
+/** Treatment-arm state: whatever the policy says, for both of its reasons. */
+var policyState = function policyState(policy) {
+  return {
+    documentSizeBreachesThreshold: policy.isDocumentBreached(),
+    latchPolicyBreached: policy.isBreached(),
+    enabled: policy.isBreached()
+  };
+};
+var createPlugin = exports.createPlugin = function createPlugin(api, injectedPolicy) {
+  var detector;
+  var policy;
+  if (injectedPolicy) {
+    policy = injectedPolicy;
+  } else if ((0, _isExperimentEnabled.isExperimentEnabled)('platform_editor_dynamic_limited_mode')) {
+    var config = (0, _expVal.expVal)('platform_editor_dynamic_limited_mode', 'policyConfig', {
+      warmUpMs: 10000,
+      slowInputMs: 100,
+      latencyWindowSize: 12,
+      latencySlowSamplesRequired: 6,
+      freezeTaskMs: 600,
+      freezeTasksRequired: 3,
+      freezeWindowMs: 30000,
+      requiredConfirmations: 2,
+      confirmationGapMs: 30000,
+      bulkChangeNodeSize: 100,
+      bulkChangeSuppressionMs: 2000,
+      docSizeThreshold: 750000,
+      nodeCountThreshold: 5000
+    });
+
+    // Resolved once per editor rather than per transaction. When off, no policy is built and the
+    // document decision runs inline exactly as it did before this experiment.
+    policy = new _latchPolicy.LatchPolicy({
+      now: function now() {
+        return performance.now();
+      },
+      config: config
+    });
+  }
   return new _safePlugin.SafePlugin({
-    key: limitedModePluginKey,
-    view: function view(_view) {
-      return {};
+    key: _pluginKey.limitedModePluginKey,
+    props: {
+      handleTextInput: function handleTextInput() {
+        var _detector;
+        (_detector = detector) === null || _detector === void 0 || _detector.measureInput();
+
+        // Never handle the input — this is measurement only.
+        return false;
+      }
+    },
+    view: function view(editorView) {
+      // No policy means the experiment is off: no observers, no per-keystroke measurement.
+      if (!policy) {
+        return {};
+      }
+      var startedAt = performance.now();
+      detector = (0, _latchDetector.createLatchDetector)({
+        policy: policy,
+        onLatchCriteriaMet: function onLatchCriteriaMet(details) {
+          var _api$analytics;
+          // Treatment arm only — the detector does not exist in control. See LimitedModeLatchedAEP.
+          //
+          // `details` is the policy's own snapshot of what it latched on, taken before it cleared
+          // its evidence buffers, so it reports the closing window rather than an empty one.
+          api === null || api === void 0 || (_api$analytics = api.analytics) === null || _api$analytics === void 0 || _api$analytics.actions.fireAnalyticsEvent({
+            action: _analytics.ACTION.LIMITED_MODE_LATCHED,
+            actionSubject: _analytics.ACTION_SUBJECT.EDITOR,
+            eventType: _analytics.EVENT_TYPE.OPERATIONAL,
+            attributes: _objectSpread(_objectSpread({
+              latched: true,
+              reason: details.reason,
+              firstWindowReason: details.firstWindowReason,
+              requiredConfirmations: details.requiredConfirmations,
+              documentAlreadyBreached: details.documentAlreadyBreached,
+              msFromFirstWindow: details.msFromFirstWindow,
+              latencyMedianMs: details.latencyMedianMs,
+              totalInputSamples: details.totalInputSamples,
+              totalSlowInputs: details.totalSlowInputs,
+              totalFreezes: details.totalFreezes,
+              nodeSize: editorView.state.doc.nodeSize
+            }, getDeviceHints()), {}, {
+              // Measured from the plugin view starting, which is a little later than the policy's
+              // own `timeToLatchMs` (it starts at plugin construction).
+              timeToLatch: performance.now() - startedAt
+            })
+          });
+
+          // The policy already holds the latch; this transaction only prompts the plugin to
+          // re-read it, which is what notifies every consumer through shared state.
+          editorView.dispatch(editorView.state.tr.setMeta(_pluginKey.limitedModePluginKey, {
+            latchPolicyBreached: true
+          }));
+        }
+      });
+      return {
+        destroy: function destroy() {
+          var _detector2;
+          (_detector2 = detector) === null || _detector2 === void 0 || _detector2.destroy();
+          detector = undefined;
+        }
+      };
     },
     state: {
       init: function init(_config, editorState) {
-        return {
-          documentSizeBreachesThreshold: (0, _shouldEnableLimitedMode.shouldEnableLimitedModeForDocument)(editorState.doc)
-        };
+        if (!policy) {
+          return documentOnlyState(editorState.doc);
+        }
+        policy.evaluateDocument(editorState.doc);
+        return policyState(policy);
       },
-      apply: function apply(tr, currentPluginState, _oldState, _newState) {
-        // Don't check the document size if we're already in limited mode.
-        // We ALWAYS want to re-check the document size if we're replacing the document (e.g. live-to-live page navigation).
+      apply: function apply(tr, currentPluginState, oldState, _newState) {
+        var _tr$getMeta;
+        var documentReplaced = Boolean(tr.getMeta('replaceDocument'));
+        if (!policy) {
+          // Control arm, unchanged: skip the traversal once already breached, but always re-check
+          // when the document is replaced (e.g. live-to-live page navigation).
+          if (currentPluginState.documentSizeBreachesThreshold && !documentReplaced) {
+            return currentPluginState;
+          }
+          return documentOnlyState(tr.doc);
+        }
 
-        if (currentPluginState.documentSizeBreachesThreshold && !tr.getMeta('replaceDocument')) {
-          return currentPluginState;
+        // The detector's latch arrives as a transaction so that plugin state stays a function of
+        // the transaction stream rather than of when `apply` happens to read the policy. Dev
+        // tooling dispatches the same meta to force limited mode by hand.
+        if ((_tr$getMeta = tr.getMeta(_pluginKey.limitedModePluginKey)) !== null && _tr$getMeta !== void 0 && _tr$getMeta.latchPolicyBreached) {
+          policy.latch();
         }
-        return {
-          documentSizeBreachesThreshold: (0, _shouldEnableLimitedMode.shouldEnableLimitedModeForDocument)(tr.doc)
-        };
+
+        // Only on replacement, never on an ordinary edit: the check walks the whole document, so
+        // running it per transaction is a full-document scan on every keystroke. The trade-off is
+        // that a document editing its way past the thresholds is not noticed until it next loads.
+        //
+        // Deliberately not skipped when limited mode is already on. Replacement is the one moment
+        // the document verdict can go *down* — live-to-live navigation onto a smaller page — so
+        // skipping it there is what would strand limited mode on forever. It costs one walk per
+        // page navigation, which is nothing next to the navigation itself.
+        if (documentReplaced) {
+          policy.evaluateDocument(tr.doc);
+        }
+
+        // Report bulk work so the policy can discount it. The policy decides what counts as bulk;
+        // this only supplies the facts.
+        //
+        // Known gap: operations that are expensive but barely change document size — table
+        // resize, drag-and-drop moves (delete + insert nets to ~0), type-ahead — are not
+        // suppressed. `@atlaskit/insm` already tracks exactly these via `startHeavyTask`, but its
+        // public facade does not expose `runningHeavyTasks`, so there is no way to read them from
+        // here today. Closing that gap needs an accessor on the insm package.
+        if (tr.docChanged) {
+          var _detector3;
+          (_detector3 = detector) === null || _detector3 === void 0 || _detector3.noteDocumentChange({
+            nodeSizeDelta: tr.doc.nodeSize - oldState.doc.nodeSize,
+            isDocumentReplaced: documentReplaced
+          });
+        }
+        var next = policyState(policy);
+
+        // Keep the previous object when nothing changed, so shared-state diffing stays cheap and
+        // consumers are not notified for no reason.
+        return next.enabled === currentPluginState.enabled && next.documentSizeBreachesThreshold === currentPluginState.documentSizeBreachesThreshold ? currentPluginState : next;
       }
     }
   });

package/dist/cjs/pm-plugins/plugin-key.js

@@ -0,0 +1,8 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.limitedModePluginKey = void 0;
+var _state = require("@atlaskit/editor-prosemirror/state");
+var limitedModePluginKey = exports.limitedModePluginKey = new _state.PluginKey('limitedModePlugin');

package/dist/cjs/pm-plugins/utils/latch-detector-types.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/dist/cjs/pm-plugins/utils/latch-detector.js

@@ -0,0 +1,108 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createLatchDetector = void 0;
+var _isPerformanceApiAvailable = require("@atlaskit/editor-common/is-performance-api-available");
+function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t.return || t.return(); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+/**
+ * Wires browser performance signals into the supplied {@link LatchPolicy}.
+ *
+ * Holds no configuration and makes no decisions: it measures, and forwards. Everything tunable lives
+ * on the policy, including the clock it reads.
+ *
+ * The measurement mirrors `editor-plugin-base/src/pm-plugins/frozen-editor.ts`, which already runs an
+ * identical `longtask` observer and per-keystroke rAF measurement for every session to feed
+ * `ACTION.SLOW_INPUT` / `ACTION.BROWSER_FREEZE`. It is duplicated rather than shared so that this
+ * experiment stays self-contained inside the limited-mode plugin — no new cross-plugin dependency,
+ * and deleting it is a single-directory revert if the experiment does not ship. The marginal cost is
+ * one `performance.now()` and one `requestAnimationFrame` per keystroke.
+ */
+var createLatchDetector = exports.createLatchDetector = function createLatchDetector(_ref) {
+  var onLatchCriteriaMet = _ref.onLatchCriteriaMet,
+    policy = _ref.policy;
+  // One clock for the whole subsystem, so measured durations and the policy's windows agree.
+  var now = policy.now;
+  var observer;
+  var destroyed = false;
+  var handleEvaluation = function handleEvaluation(evaluation) {
+    if (evaluation !== 'latched') {
+      return;
+    }
+
+    // One-way latch: the policy will never evaluate again, so stop paying for the observers.
+    teardownObservers();
+    var details = policy.getLatchDetails();
+    if (details) {
+      onLatchCriteriaMet(details);
+    }
+  };
+  function teardownObservers() {
+    var _observer;
+    (_observer = observer) === null || _observer === void 0 || _observer.disconnect();
+    observer = undefined;
+  }
+  if ((0, _isPerformanceApiAvailable.isPerformanceObserverLongTaskAvailable)()) {
+    try {
+      observer = new PerformanceObserver(function (list) {
+        var _iterator = _createForOfIteratorHelper(list.getEntries()),
+          _step;
+        try {
+          for (_iterator.s(); !(_step = _iterator.n()).done;) {
+            var entry = _step.value;
+            if (policy.isLatched()) {
+              return;
+            }
+            handleEvaluation(policy.recordLongTask(entry.duration));
+          }
+        } catch (err) {
+          _iterator.e(err);
+        } finally {
+          _iterator.f();
+        }
+      });
+      observer.observe({
+        entryTypes: ['longtask']
+      });
+    } catch (_unused) {
+      // `longtask` is unsupported in some browsers even when PerformanceObserver exists. The
+      // latency criterion alone is still a valid trigger, so carry on without freeze detection.
+      observer = undefined;
+    }
+  }
+  return {
+    noteDocumentChange: function noteDocumentChange(_ref2) {
+      var nodeSizeDelta = _ref2.nodeSizeDelta,
+        isDocumentReplaced = _ref2.isDocumentReplaced;
+      if (destroyed || policy.isLatched()) {
+        return;
+      }
+      if (isDocumentReplaced || policy.isBulkChange(nodeSizeDelta)) {
+        policy.suppress();
+      }
+    },
+    measureInput: function measureInput() {
+      if (destroyed || policy.isLatched() || !(0, _isPerformanceApiAvailable.isPerformanceAPIAvailable)()) {
+        return;
+      }
+      var start = now();
+
+      // Runs after every handleTextInput and all resulting plugin work, but before paint — the
+      // same measurement point frozen-editor uses, so the numbers are comparable to existing
+      // SLOW_INPUT telemetry.
+      requestAnimationFrame(function () {
+        if (destroyed || policy.isLatched()) {
+          return;
+        }
+        handleEvaluation(policy.recordInputLatency(now() - start));
+      });
+    },
+    destroy: function destroy() {
+      destroyed = true;
+      teardownObservers();
+    }
+  };
+};

package/dist/cjs/pm-plugins/utils/latch-policy-types.js

@@ -0,0 +1 @@
+"use strict";