Bug 1797636 - rename UA widget 'destructor' methods to 'teardown' as that is more accurate, r=mhowell

Differential Revision: https://phabricator.services.mozilla.com/D161305

toolkit/actors/UAWidgetsChild.jsm

@@ -158,9 +158,9 @@ class UAWidgetsChild extends JSWindowActorChild {
       return;
     }
     let { widget } = this.widgets.get(aElement);
-    if (typeof widget.destructor == "function") {
+    if (typeof widget.teardown == "function") {
       try {
-        widget.destructor();
+        widget.teardown();
       } catch (ex) {
         Cu.reportError(ex);
       }

toolkit/content/widgets/browser-custom-element.js

@@ -1047,8 +1047,9 @@
     }
 
     /**
-     * This is necessary because the destructor doesn't always get called when
-     * we are removed from a tabbrowser. This will be explicitly called by tabbrowser.
+     * This is necessary because custom elements don't have a "real" destructor.
+     * This method is called explicitly by tabbrowser, when changing remoteness,
+     * and when we're disconnected or the window unloads.
      */
     destroy() {
       elementsToDestroyOnUnload.delete(this);

toolkit/content/widgets/datetimebox.js

@@ -43,7 +43,7 @@ this.DateTimeBoxWidget = class {
     }
 
     if (aDestroy) {
-      this.destructor();
+      this.teardown();
     }
     this.type = newType;
     this.setup();
@@ -57,7 +57,7 @@ this.DateTimeBoxWidget = class {
     return this.type == "date" || this.type == "datetime-local";
   }
 
-  destructor() {
+  teardown() {
     this.mResetButton.removeEventListener("mousedown", this, {
       mozSystemGroup: true,
     });

toolkit/content/widgets/docs/ua_widget.rst

@@ -15,13 +15,13 @@ When the element is appended to the tree, a chrome-only ``UAWidgetSetupOrChange`
 
 UAWidgetsChild then grabs the sandbox for that origin (lazily creating it as needed), loads the script as needed, and initializes an instance by calling the JS constructor with a reference to the UA Widget Shadow Root created by the DOM. We will discuss the sandbox in the latter section.
 
-The ``onsetup`` method is called right after the instance is constructed. The call to constructor must not throw, or UAWidgetsChild will be confused since an instance of the widget will not be returned, but the widget is already half-initalized. If the ``onsetup`` method call throws, UAWidgetsChild will still be able to hold the reference of the widget and call the destructor later on.
+The ``onsetup`` method is called right after the instance is constructed. The call to constructor must not throw, or UAWidgetsChild will be confused since an instance of the widget will not be returned, but the widget is already half-initalized. If the ``onsetup`` method call throws, UAWidgetsChild will still be able to hold the reference of the widget and call the teardown method later on.
 
-When the element is removed from the tree, ``UAWidgetTeardown`` is dispatched so UAWidgetsChild can destroy the widget, if it exists. If so, the UAWidgetsChild calls the ``destructor()`` method on the widget, causing the widget to destruct itself.
+When the element is removed from the tree, ``UAWidgetTeardown`` is dispatched so UAWidgetsChild can destroy the widget, if it exists. If so, the UAWidgetsChild calls the ``teardown()`` method on the widget, causing the widget to destruct itself.
 
-Counter-intuitively, elements are not considered "removed from the tree" when the document is unloaded. This is considered safe as anything the widget touches should be reset or cleaned up when the document unloads. Please do not violate the assumption by having any browser state toggled by the destructor.
+Counter-intuitively, elements are not considered "removed from the tree" when the document is unloaded. This is considered safe as anything the widget touches should be reset or cleaned up when the document unloads. Please do not violate the assumption by having any browser state toggled by the teardown.
 
-When a UA Widget initializes, it should create its own DOM inside the passed UA Widget Shadow Root, including the ``<link>`` element necessary to load the stylesheet, add event listeners, etc. When destroyed (i.e. the destructor method is called), it should do the opposite.
+When a UA Widget initializes, it should create its own DOM inside the passed UA Widget Shadow Root, including the ``<link>`` element necessary to load the stylesheet, add event listeners, etc. When destroyed (i.e. the teardown method is called), it should do the opposite.
 
 **Specialization**: for video controls, we do not want to do the work if the control is not needed (i.e. when the ``<video>`` or ``<audio>`` element has no "controls" attribute set), so we forgo dispatching the event from HTMLMediaElement in the BindToTree method. Instead, another ``UAWidgetSetupOrChange`` event will cause the sandbox and the widget instance to construct when the attribute is set to true. The same event is also responsible for triggering the ``onchange()`` method on UA Widgets if the widget is already initialized.
 

toolkit/content/widgets/findbar.js

@@ -399,9 +399,9 @@
     }
 
     /**
-     * This is necessary because the destructor isn't called when we are removed
-     * from a document that is not destroyed. This needs to be explicitly called
-     * in this case.
+     * This is necessary because custom elements don't have a "real" destructor.
+     * This method is called explicitly from disconnectedCallback, and from
+     * an unload event handler that we add.
      */
     destroy() {
       if (this._destroyed) {

toolkit/content/widgets/marquee.js

@@ -47,18 +47,18 @@ this.MarqueeWidget = class {
     if (this.impl && this.impl.constructor == newImpl) {
       return;
     }
-    this.destructor();
+    this.teardown();
     if (newImpl) {
       this.impl = new newImpl(this.shadowRoot);
       this.impl.onsetup();
     }
   }
 
-  destructor() {
+  teardown() {
     if (!this.impl) {
       return;
     }
-    this.impl.destructor();
+    this.impl.teardown();
     this.shadowRoot.firstChild.remove();
     delete this.impl;
   }
@@ -107,7 +107,7 @@ this.MarqueeBaseImplWidget = class {
     this.shadowRoot.addEventListener("marquee-stop", this);
   }
 
-  destructor() {
+  teardown() {
     this._mutationObserver.disconnect();
     this.window.clearTimeout(this.runId);
 

toolkit/content/widgets/textrecognition.js

@@ -165,7 +165,7 @@ this.TextRecognitionWidget = class {
     }
   }
 
-  destructor() {
+  teardown() {
     this.shadowRoot.firstChild.remove();
     this.resizeObserver.disconnect();
     this.spanRects.clear();

toolkit/content/widgets/videocontrols.js

@@ -72,7 +72,7 @@ this.VideoControlsWidget = class {
       return;
     }
     if (this.impl) {
-      this.impl.destructor();
+      this.impl.teardown();
       this.shadowRoot.firstChild.remove();
     }
     if (newImpl) {
@@ -90,11 +90,11 @@ this.VideoControlsWidget = class {
     }
   }
 
-  destructor() {
+  teardown() {
     if (!this.impl) {
       return;
     }
-    this.impl.destructor();
+    this.impl.teardown();
     this.shadowRoot.firstChild.remove();
     delete this.impl;
   }
@@ -2949,7 +2949,7 @@ this.VideoControlsImplWidget = class {
     return this.isShowingPictureInPictureMessage == elementInPiP;
   }
 
-  destructor() {
+  teardown() {
     this.Utils.terminate();
     this.TouchUtils.terminate();
     this.Utils.updateOrientationState(false);
@@ -3116,7 +3116,7 @@ this.NoControlsMobileImplWidget = class {
     return true;
   }
 
-  destructor() {
+  teardown() {
     this.Utils.terminate();
   }
 
@@ -3170,7 +3170,7 @@ this.NoControlsPictureInPictureImplWidget = class {
     return true;
   }
 
-  destructor() {}
+  teardown() {}
 
   onPrefChange(prefName, prefValue) {
     this.prefs[prefName] = prefValue;
@@ -3350,7 +3350,7 @@ this.NoControlsDesktopImplWidget = class {
     return true;
   }
 
-  destructor() {
+  teardown() {
     this.Utils.terminate();
   }