devtools/client/accessibility/panel.js

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4 "use strict";
   5
   6 const EventEmitter = require("resource://devtools/shared/event-emitter.js");
   7
   8 loader.lazyRequireGetter(
   9   this,
  10   "AccessibilityProxy",
  11   "resource://devtools/client/accessibility/accessibility-proxy.js",
  12   true
  13 );
  14 loader.lazyRequireGetter(
  15   this,
  16   "Picker",
  17   "resource://devtools/client/accessibility/picker.js",
  18   true
  19 );
  20 const {
  21   A11Y_SERVICE_DURATION,
  22 } = require("resource://devtools/client/accessibility/constants.js");
  23
  24 // The panel's window global is an EventEmitter firing the following events:
  25 const EVENTS = {
  26   // When the accessibility inspector has a new accessible front selected.
  27   NEW_ACCESSIBLE_FRONT_SELECTED: "Accessibility:NewAccessibleFrontSelected",
  28   // When the accessibility inspector has a new accessible front highlighted.
  29   NEW_ACCESSIBLE_FRONT_HIGHLIGHTED:
  30     "Accessibility:NewAccessibleFrontHighlighted",
  31   // When the accessibility inspector has a new accessible front inspected.
  32   NEW_ACCESSIBLE_FRONT_INSPECTED: "Accessibility:NewAccessibleFrontInspected",
  33   // When the accessibility inspector is updated.
  34   ACCESSIBILITY_INSPECTOR_UPDATED:
  35     "Accessibility:AccessibilityInspectorUpdated",
  36   // When accessibility panel UI is initialized (rendered).
  37   INITIALIZED: "Accessibility:Initialized",
  38   // When accessibile object properties are updated in the panel sidebar for a
  39   // new accessible object.
  40   PROPERTIES_UPDATED: "Accessibility:PropertiesUpdated",
  41 };
  42
  43 /**
  44  * This object represents Accessibility panel. It's responsibility is to
  45  * render Accessibility Tree of the current debugger target and the sidebar that
  46  * displays current relevant accessible details.
  47  */
  48 function AccessibilityPanel(iframeWindow, toolbox, commands) {
  49   this.panelWin = iframeWindow;
  50   this._toolbox = toolbox;
  51   this._commands = commands;
  52
  53   this.onPanelVisibilityChange = this.onPanelVisibilityChange.bind(this);
  54   this.onNewAccessibleFrontSelected =
  55     this.onNewAccessibleFrontSelected.bind(this);
  56   this.onAccessibilityInspectorUpdated =
  57     this.onAccessibilityInspectorUpdated.bind(this);
  58   this.updateA11YServiceDurationTimer =
  59     this.updateA11YServiceDurationTimer.bind(this);
  60   this.forceUpdatePickerButton = this.forceUpdatePickerButton.bind(this);
  61   this.onLifecycleEvent = this.onLifecycleEvent.bind(this);
  62
  63   EventEmitter.decorate(this);
  64 }
  65
  66 AccessibilityPanel.prototype = {
  67   /**
  68    * Open is effectively an asynchronous constructor.
  69    */
  70   async open() {
  71     if (this._opening) {
  72       await this._opening;
  73       return this._opening;
  74     }
  75
  76     // This first promise includes initialization of proxy *and* the call to forceRefresh
  77     let resolver;
  78     this._opening = new Promise(resolve => {
  79       resolver = resolve;
  80     });
  81
  82     // This second promise only include the initialization of proxy and few other things,
  83     // but not the call to forceRefresh.
  84     const { promise, resolve } = Promise.withResolvers();
  85     this.initializedPromise = promise;
  86
  87     this._telemetry = this._toolbox.telemetry;
  88     this.panelWin.gTelemetry = this._telemetry;
  89
  90     this._toolbox.on("select", this.onPanelVisibilityChange);
  91
  92     this.panelWin.EVENTS = EVENTS;
  93     EventEmitter.decorate(this.panelWin);
  94     this.panelWin.on(
  95       EVENTS.NEW_ACCESSIBLE_FRONT_SELECTED,
  96       this.onNewAccessibleFrontSelected
  97     );
  98     this.panelWin.on(
  99       EVENTS.ACCESSIBILITY_INSPECTOR_UPDATED,
 100       this.onAccessibilityInspectorUpdated
 101     );
 102
 103     this.picker = new Picker(this);
 104     this.fluentBundles = await this.createFluentBundles();
 105
 106     this.accessibilityProxy = new AccessibilityProxy(this._commands, this);
 107
 108     await this.accessibilityProxy.initialize();
 109
 110     this.accessibilityProxy.startListeningForLifecycleEvents({
 111       init: this.onLifecycleEvent,
 112       shutdown: this.onLifecycleEvent,
 113     });
 114
 115     // Start recording the duration where a11y service is enabled via the proxy.
 116     this.updateA11YServiceDurationTimer();
 117
 118     // Resolve the `this.initializedPromise`
 119     resolve();
 120
 121     // Force rendering the panel once everything is initialized
 122     await this.forceRefresh();
 123
 124     resolver(this);
 125     return this._opening;
 126   },
 127
 128   /**
 129    * Retrieve message contexts for the current locales, and return them as an
 130    * array of FluentBundles elements.
 131    */
 132   async createFluentBundles() {
 133     const locales = Services.locale.appLocalesAsBCP47;
 134     const generator = L10nRegistry.getInstance().generateBundles(locales, [
 135       "devtools/client/accessibility.ftl",
 136     ]);
 137
 138     // Return value of generateBundles is a generator and should be converted to
 139     // a sync iterable before using it with React.
 140     const contexts = [];
 141     for await (const message of generator) {
 142       contexts.push(message);
 143     }
 144
 145     return contexts;
 146   },
 147
 148   onLifecycleEvent() {
 149     this.updateA11YServiceDurationTimer();
 150     this.forceUpdatePickerButton();
 151   },
 152
 153   onNewAccessibleFrontSelected(selected) {
 154     this.emit("new-accessible-front-selected", selected);
 155   },
 156
 157   onAccessibilityInspectorUpdated() {
 158     this.emit("accessibility-inspector-updated");
 159   },
 160
 161   /**
 162    * Make sure the panel is refreshed when the page is reloaded. The panel is
 163    * refreshed immediatelly if it's currently selected or lazily when the user
 164    * actually selects it.
 165    */
 166   async forceRefresh() {
 167     this.shouldRefresh = true;
 168
 169     // Wait for initialization to be done, in case this is called early on.
 170     await this.initializedPromise;
 171     const onUpdated = this.panelWin.once(EVENTS.INITIALIZED);
 172     this.refresh();
 173     await onUpdated;
 174
 175     this.emit("reloaded");
 176   },
 177
 178   /**
 179    * Make sure the panel is refreshed (if needed) when it's selected.
 180    */
 181   onPanelVisibilityChange() {
 182     this._opening.then(() => this.refresh());
 183   },
 184
 185   refresh() {
 186     this.cancelPicker();
 187
 188     if (!this.isVisible) {
 189       // Do not refresh if the panel isn't visible.
 190       return;
 191     }
 192
 193     // Do not refresh if it isn't necessary.
 194     if (!this.shouldRefresh) {
 195       return;
 196     }
 197     // Alright reset the flag we are about to refresh the panel.
 198     this.shouldRefresh = false;
 199     const {
 200       supports,
 201       getAccessibilityTreeRoot,
 202       startListeningForAccessibilityEvents,
 203       stopListeningForAccessibilityEvents,
 204       audit,
 205       simulate,
 206       toggleDisplayTabbingOrder,
 207       enableAccessibility,
 208       resetAccessiblity,
 209       startListeningForLifecycleEvents,
 210       stopListeningForLifecycleEvents,
 211       startListeningForParentLifecycleEvents,
 212       stopListeningForParentLifecycleEvents,
 213       highlightAccessible,
 214       unhighlightAccessible,
 215     } = this.accessibilityProxy;
 216     this.postContentMessage("initialize", {
 217       fluentBundles: this.fluentBundles,
 218       toolbox: this._toolbox,
 219       supports,
 220       getAccessibilityTreeRoot,
 221       startListeningForAccessibilityEvents,
 222       stopListeningForAccessibilityEvents,
 223       audit,
 224       simulate,
 225       toggleDisplayTabbingOrder,
 226       enableAccessibility,
 227       resetAccessiblity,
 228       startListeningForLifecycleEvents,
 229       stopListeningForLifecycleEvents,
 230       startListeningForParentLifecycleEvents,
 231       stopListeningForParentLifecycleEvents,
 232       highlightAccessible,
 233       unhighlightAccessible,
 234     });
 235   },
 236
 237   updateA11YServiceDurationTimer() {
 238     if (this.accessibilityProxy.enabled) {
 239       this._telemetry.start(A11Y_SERVICE_DURATION, this);
 240     } else {
 241       this._telemetry.finish(A11Y_SERVICE_DURATION, this, true);
 242     }
 243   },
 244
 245   selectAccessible(accessibleFront) {
 246     this.postContentMessage("selectAccessible", accessibleFront);
 247   },
 248
 249   selectAccessibleForNode(nodeFront, reason) {
 250     if (reason) {
 251       Glean.devtoolsAccessibility.selectAccessibleForNode[reason].add(1);
 252     }
 253
 254     this.postContentMessage("selectNodeAccessible", nodeFront);
 255   },
 256
 257   highlightAccessible(accessibleFront) {
 258     this.postContentMessage("highlightAccessible", accessibleFront);
 259   },
 260
 261   postContentMessage(type, ...args) {
 262     const event = new this.panelWin.MessageEvent("devtools/chrome/message", {
 263       bubbles: true,
 264       cancelable: true,
 265       data: { type, args },
 266     });
 267
 268     this.panelWin.dispatchEvent(event);
 269   },
 270
 271   updatePickerButton() {
 272     this.picker && this.picker.updateButton();
 273   },
 274
 275   forceUpdatePickerButton() {
 276     // Only update picker button when the panel is selected.
 277     if (!this.isVisible) {
 278       return;
 279     }
 280
 281     this.updatePickerButton();
 282     // Calling setToolboxButtons to make sure toolbar is forced to re-render.
 283     this._toolbox.component.setToolboxButtons(this._toolbox.toolbarButtons);
 284   },
 285
 286   togglePicker() {
 287     this.picker && this.picker.toggle();
 288   },
 289
 290   cancelPicker() {
 291     this.picker && this.picker.cancel();
 292   },
 293
 294   stopPicker() {
 295     this.picker && this.picker.stop();
 296   },
 297
 298   /**
 299    * Return true if the Accessibility panel is currently selected.
 300    */
 301   get isVisible() {
 302     return this._toolbox.currentToolId === "accessibility";
 303   },
 304
 305   destroy() {
 306     if (this._destroyed) {
 307       return;
 308     }
 309     this._destroyed = true;
 310
 311     this.postContentMessage("destroy");
 312
 313     if (this.accessibilityProxy) {
 314       this.accessibilityProxy.stopListeningForLifecycleEvents({
 315         init: this.onLifecycleEvent,
 316         shutdown: this.onLifecycleEvent,
 317       });
 318       this.accessibilityProxy.destroy();
 319       this.accessibilityProxy = null;
 320       this.initializedPromise = null;
 321     }
 322
 323     this._toolbox.off("select", this.onPanelVisibilityChange);
 324
 325     this.panelWin.off(
 326       EVENTS.NEW_ACCESSIBLE_FRONT_SELECTED,
 327       this.onNewAccessibleFrontSelected
 328     );
 329     this.panelWin.off(
 330       EVENTS.ACCESSIBILITY_INSPECTOR_UPDATED,
 331       this.onAccessibilityInspectorUpdated
 332     );
 333
 334     // Older versions of devtools server do not support picker functionality.
 335     if (this.picker) {
 336       this.picker.release();
 337       this.picker = null;
 338     }
 339
 340     this._telemetry = null;
 341     this.panelWin.gTelemetry = null;
 342
 343     this.emit("destroyed");
 344   },
 345 };
 346
 347 // Exports from this module
 348 exports.AccessibilityPanel = AccessibilityPanel;