Bug 1869574 - Refactor the headerText setter to cater for more panelview needs r=twisniewski,Gijs,translations-reviewers

This introduces `mainview-with-header` attribute for panels that their
mainview should have a header (no matter where they appear); and
`has-custom-header` for panels that their panelview (not necessarily a
mainview) has a custom design for a header, one that headerText setter
can't anticipate in advance (due to UX needs that may arise).
If one of these attributes are set on the panel, this signals headerText
that the panelview's header should NOT be removed and that the markup
should be respected.

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

Author: ItielMaN

browser/base/content/appmenu-viewcache.inc.xhtml

@@ -260,7 +260,9 @@
                    />
   </panelview>
 
-  <panelview id="PanelUI-profiler" showheader="true">
+  <panelview id="PanelUI-profiler"
+             mainview-with-header="true"
+             has-customized-header="true">
     <vbox id="PanelUI-profiler-header" animationready="false">
       <hbox id="PanelUI-profiler-header-bar"
             class="panel-header panel-header-with-additional-element panel-header-with-info-button">
@@ -718,7 +720,7 @@
     </vbox>
   </panelview>
 
-  <panelview id="PanelUI-whatsNew" class="PanelUI-subView" showheader="true">
+  <panelview id="PanelUI-whatsNew" class="PanelUI-subView" mainview-with-header="true">
     <hbox id="PanelUI-whatsNew-title" class="panel-header">
       <html:h1>
         <html:span data-l10n-id="whatsnew-panel-header"></html:span>

browser/components/controlcenter/content/identityPanel.inc.xhtml

@@ -15,10 +15,16 @@
 
   <panelmultiview id="identity-popup-multiView"
                   mainViewId="identity-popup-mainView">
-    <panelview id="identity-popup-mainView" class="PanelUI-subView" role="document" showheader="true">
+    <panelview id="identity-popup-mainView"
+               class="PanelUI-subView"
+               role="document"
+               mainview-with-header="true">
+      <!-- The panel header text value changes dynamically by browser-siteIdentity.js,
+         - that's why the panel header box needs to remain hardcoded in the markup.
+         - instead of being handled by PanelMultiView.sys.mjs. -->
       <box id="identity-popup-mainView-panel-header" class="panel-header">
         <html:h1>
-          <html:span id="identity-popup-mainView-panel-header-span" role="heading" aria-level="1"/>
+          <html:span id="identity-popup-mainView-panel-header-span"/>
         </html:h1>
       </box>
       <toolbarseparator/>

browser/components/controlcenter/content/permissionPanel.inc.xhtml

@@ -16,10 +16,13 @@
                   mainViewId="permission-popup-mainView">
     <panelview id="permission-popup-mainView"
                role="document"
-               showheader="true">
+               mainview-with-header="true">
+      <!-- The panel header text value changes dynamically by browser-sitePermissionPanel.js,
+         - that's why the panel header box needs to remain hardcoded in the markup.
+         - instead of being handled by PanelMultiView.sys.mjs. -->
       <box id="permission-popup-mainView-panel-header" class="panel-header">
         <html:h1>
-          <html:span id="permission-popup-mainView-panel-header-span" role="heading" aria-level="1"/>
+          <html:span id="permission-popup-mainView-panel-header-span"/>
         </html:h1>
       </box>
       <toolbarseparator></toolbarseparator>

browser/components/controlcenter/content/protectionsPanel.inc.xhtml

@@ -18,13 +18,13 @@
     <panelview id="protections-popup-mainView"
                class="PanelUI-subView"
                role="document"
-               showheader="true">
+               mainview-with-header="true"
+               has-custom-header="true">
       <vbox id="protections-popup-mainView-panel-header-section">
         <box id="protections-popup-mainView-panel-header"
              class="panel-header panel-header-with-additional-element panel-header-with-info-button"
              onclick="gProtectionsHandler.onHeaderClicked(event);">
-          <html:h1 id="protections-popup-main-header-label"
-                 role="heading" aria-level="1">
+          <html:h1 id="protections-popup-main-header-label">
             <html:span id="protections-popup-mainView-panel-header-span"/>
           </html:h1>
           <toolbarbutton id="protections-popup-info-button" class="panel-info-button"

browser/components/customizableui/PanelMultiView.sys.mjs

@@ -1405,59 +1405,68 @@ export var PanelView = class extends AssociatedToNode {
     };
 
     // If the header already exists, update or remove it as requested.
+    let isMainView = this.node.getAttribute("mainview");
     let header = this.node.querySelector(".panel-header");
     if (header) {
-      let headerInfoButton = header.querySelector(".panel-info-button");
       let headerBackButton = header.querySelector(".subviewbutton-back");
-      if (headerBackButton && this.node.getAttribute("mainview")) {
-        // A back button should not appear in a mainview.
-        // This codepath can be reached if a user enters a panelview in
-        // the overflow panel, and then unpins it back to the toolbar.
-        headerBackButton.remove();
+      if (isMainView) {
+        if (headerBackButton) {
+          // A back button should not appear in a mainview.
+          // This codepath can be reached if a user enters a panelview in
+          // the overflow panel (like the Profiler), and then unpins it back to the toolbar.
+          headerBackButton.remove();
+        }
       }
-      if (!this.node.getAttribute("mainview")) {
-        if (value) {
-          let headerWantsBackButton =
-            headerInfoButton || header.hasAttribute("wants-back-button");
-          if (headerWantsBackButton && !headerBackButton) {
-            // If we're not in a mainview and an info button is present, or the
-            // panel says that it wants one, that means the panel header is a
-            // custom one and a back button should be added, if not already present.
-            header.prepend(this.createHeaderBackButton());
-          }
-          // Set the header title based on the value given.
-          header.querySelector(".panel-header > h1 > span").textContent = value;
-          ensureHeaderSeparator(header);
-        } else {
-          if (header.nextSibling.tagName == "toolbarseparator") {
-            header.nextSibling.remove();
-          }
-          header.remove();
+      if (value) {
+        if (
+          !isMainView &&
+          !headerBackButton &&
+          !this.node.getAttribute("no-back-button")
+        ) {
+          // Add a back button when not in mainview (if it doesn't exist already),
+          // also when a panelview specifies it doesn't want a back button,
+          // like the Report Broken Site (sent) panelview.
+          header.prepend(this.createHeaderBackButton());
         }
-        return;
-      } else if (!this.node.getAttribute("showheader")) {
+        // Set the header title based on the value given.
+        header.querySelector(".panel-header > h1 > span").textContent = value;
+        ensureHeaderSeparator(header);
+      } else if (
+        !this.node.getAttribute("has-custom-header") &&
+        !this.node.getAttribute("mainview-with-header")
+      ) {
+        // No value supplied, and the panelview doesn't have a certain requirement
+        // for any kind of header, so remove it and the following toolbarseparator.
         if (header.nextSibling.tagName == "toolbarseparator") {
           header.nextSibling.remove();
         }
         header.remove();
+        return;
       }
+      // Either the header exists and has been adjusted accordingly by now,
+      // or it doesn't (or shouldn't) exist. Bail out to not create a duplicate header.
+      return;
     }
 
-    // The header doesn't exist, only create it if needed.
+    // The header doesn't and shouldn't exist, only create it if needed.
     if (!value) {
       return;
     }
 
     header = this.document.createXULElement("box");
     header.classList.add("panel-header");
 
-    let backButton = this.createHeaderBackButton();
+    if (!isMainView) {
+      let backButton = this.createHeaderBackButton();
+      header.append(backButton);
+    }
+
     let h1 = this.document.createElement("h1");
     let span = this.document.createElement("span");
     span.textContent = value;
     h1.appendChild(span);
 
-    header.append(backButton, h1);
+    header.append(h1);
     this.node.prepend(header);
 
     ensureHeaderSeparator(header);

browser/components/customizableui/content/panelUI.inc.xhtml

@@ -75,7 +75,7 @@
     <panelmultiview mainViewId="unified-extensions-view">
       <panelview id="unified-extensions-view"
                  class="cui-widget-panelview"
-                 showheader="true">
+                 mainview-with-header="true">
         <box class="panel-header">
           <html:h1>
             <html:span data-l10n-id="unified-extensions-header-title"/>

browser/components/reportbrokensite/content/reportBrokenSitePanel.inc.xhtml

@@ -8,16 +8,16 @@
            aria-describedby="report-broken-site-panel-intro"
            data-l10n-id="report-broken-site-panel-header"
            data-l10n-attrs="title"
-           showheader="true">
-  <!-- wants-back-button will be removed in bug 1869574
-       (and also from PanelMultiView.sys.mjs)
-  -->
-  <box class="panel-header" wants-back-button="true">
+           mainview-with-header="true">
+  <!-- The panel can be opened from the Help menubar, so with the current
+     - headerText implementation in PanelMultiView.sys.mjs the markup must
+     - be added manually. -->
+  <box class="panel-header">
     <html:h1>
       <html:span data-l10n-id="report-broken-site-mainview-title"/>
     </html:h1>
   </box>
-  <toolbarseparator></toolbarseparator>
+  <toolbarseparator/>
   <vbox id="report-broken-site-panel-container"
         class="panel-subview-body">
     <html:p id="report-broken-site-panel-intro"
@@ -102,7 +102,8 @@
            data-l10n-id="report-broken-site-panel-report-sent-header"
            data-l10n-attrs="title"
            aria-describedby="report-broken-site-panel-report-sent-text"
-           showheader="true">
+           has-customized-header="true"
+           no-back-button="true">
   <box class="panel-header panel-header-with-additional-element">
     <image class="checkmark-icon additional-element-on-inline-start"></image>
     <html:h1>

browser/components/translations/content/translationsPanel.inc.xhtml

@@ -18,7 +18,8 @@
     <panelview id="translations-panel-view-default"
                class="PanelUI-subView translations-panel-view"
                role="document"
-               showheader="true">
+               mainview-with-header="true"
+               has-custom-header="true">
       <hbox class="panel-header translations-panel-header">
         <html:h1 class="translations-panel-header-wrapper">
           <html:span id="translations-panel-header"></html:span>
@@ -106,7 +107,7 @@
     <panelview id="translations-panel-view-unsupported-language"
                class="PanelUI-subView translations-panel-view"
                role="document"
-               showheader="true">
+               has-custom-header="true">
       <hbox class="panel-header translations-panel-header">
         <image class="translations-panel-error-icon" />
         <html:h1 id="translations-panel-unsupported-language-header">