feat: add root heading level support to dashboard layout (#9249)

* feat: add root level heading support to dashboard layout

* refactor: use is to determine whether the element is a dashboard

* test: remove duplicate test

* test: move section tests, remove duplicates, make all elements custom

* Update packages/dashboard/test/dashboard-layout.test.ts

Co-authored-by: Serhii Kulykov <iamkulykov@gmail.com>

* Update packages/dashboard/test/dashboard-layout.test.ts

Co-authored-by: Serhii Kulykov <iamkulykov@gmail.com>

* refactor: use event instead of mutation observer

* test: update snapshot tests

* refactor: add private property for detecting mixin

* chore: remove private marking

* chore: remove double underscore from function name

* chore: add missing attr JSDoc annotations

* chore: do not declare private property for mixin detection flag

* chore: rename method to follow add / remove convention

* chore: rename methods to not use observer

---------

Co-authored-by: Serhii Kulykov <iamkulykov@gmail.com>

Author: ugur-vaadin

packages/dashboard/src/vaadin-dashboard-helpers.js

@@ -102,16 +102,9 @@ export function fireRemove(element) {
   element.dispatchEvent(new CustomEvent('item-remove', { bubbles: true }));
 }
 
-/**
- * Walks up the DOM tree starting from `node`, returning the first ancestor which is an instance of the given `baseClass`.
- *
- * @param {Node} node - starting node
- * @param {Function} baseClass - constructor, e.g. `Dashboard`
- * @returns {HTMLElement | null}
- */
-export function findAncestorInstance(node, baseClass) {
+function findFilteredAncestorInstance(node, elementFilter) {
   while (node) {
-    if (node instanceof baseClass) {
+    if (elementFilter(node)) {
       return node;
     }
     if (node instanceof ShadowRoot) {
@@ -129,3 +122,26 @@ export function findAncestorInstance(node, baseClass) {
   }
   return null;
 }
+
+/**
+ * Walks up the DOM tree starting from `node`, returning the first ancestor which is an instance of the given `baseClass`.
+ *
+ * @param {Node} node - starting node
+ * @param {Function} baseClass - constructor, e.g. `Dashboard`
+ * @returns {HTMLElement | null}
+ */
+export function findAncestorInstance(node, baseClass) {
+  return findFilteredAncestorInstance(node, (el) => {
+    return el instanceof baseClass;
+  });
+}
+
+/**
+ * Walks up the DOM tree starting from `node`, returning the first ancestor which is a `Dashboard` or `DashboardLayout`.
+ *
+ * @param {Node} node - starting node
+ * @returns {HTMLElement | null}
+ */
+export function getParentLayout(node) {
+  return findFilteredAncestorInstance(node, (el) => el.__hasVaadinDashboardLayoutMixin);
+}

packages/dashboard/src/vaadin-dashboard-item-mixin.js

@@ -13,7 +13,7 @@ import { html } from 'lit';
 import { FocusTrapController } from '@vaadin/a11y-base/src/focus-trap-controller.js';
 import { ResizeMixin } from '@vaadin/component-base/src/resize-mixin.js';
 import { KeyboardController } from './keyboard-controller.js';
-import { fireMove, fireRemove, fireResize } from './vaadin-dashboard-helpers.js';
+import { fireMove, fireRemove, fireResize, getParentLayout } from './vaadin-dashboard-helpers.js';
 
 const DEFAULT_I18N = {
   selectWidget: 'Select widget for editing',
@@ -53,6 +53,11 @@ export const DashboardItemMixin = (superClass) =>
           type: Object,
         },
 
+        /** @protected */
+        _rootHeadingLevel: {
+          type: Number,
+        },
+
         /** @private */
         __selected: {
           type: Boolean,
@@ -283,6 +288,7 @@ export const DashboardItemMixin = (superClass) =>
       super();
       this.__keyboardController = new KeyboardController(this);
       this.__focusTrapController = new FocusTrapController(this);
+      this.__boundRootHeadingLevelChangedListener = this.__updateRootHeadingLevel.bind(this);
     }
 
     /** @protected */
@@ -292,6 +298,19 @@ export const DashboardItemMixin = (superClass) =>
       this.addController(this.__focusTrapController);
     }
 
+    /** @protected */
+    connectedCallback() {
+      super.connectedCallback();
+      this.__updateRootHeadingLevel();
+      this.__addHeadingLevelListener();
+    }
+
+    /** @protected */
+    disconnectedCallback() {
+      super.disconnectedCallback();
+      this.__removeHeadingLevelListener();
+    }
+
     /** @private */
     __selectedChanged(selected, oldSelected) {
       if (!!selected === !!oldSelected) {
@@ -377,4 +396,36 @@ export const DashboardItemMixin = (superClass) =>
       }
       this.dispatchEvent(new CustomEvent('item-resize-mode-changed', { bubbles: true, detail: { value: resizeMode } }));
     }
+
+    /** @private */
+    __addHeadingLevelListener() {
+      this.__removeHeadingLevelListener();
+      const parentLayout = getParentLayout(this);
+      if (parentLayout) {
+        this.__rootHeadingLevelListenerTarget = parentLayout;
+        parentLayout.addEventListener(
+          'dashboard-root-heading-level-changed',
+          this.__boundRootHeadingLevelChangedListener,
+        );
+      }
+    }
+
+    /** @private */
+    __removeHeadingLevelListener() {
+      if (this.__rootHeadingLevelListenerTarget) {
+        this.__rootHeadingLevelListenerTarget.removeEventListener(
+          'dashboard-root-heading-level-changed',
+          this.__boundRootHeadingLevelChangedListener,
+        );
+        this.__rootHeadingLevelListenerTarget = null;
+      }
+    }
+
+    /** @private */
+    __updateRootHeadingLevel() {
+      const parentLayout = getParentLayout(this);
+      if (parentLayout) {
+        this._rootHeadingLevel = parentLayout.rootHeadingLevel;
+      }
+    }
   };

packages/dashboard/src/vaadin-dashboard-layout-mixin.d.ts

@@ -25,4 +25,16 @@ export declare class DashboardLayoutMixinClass {
    * @attr {boolean} dense-layout
    */
   denseLayout: boolean;
+
+  /**
+   * Root heading level for sections and widgets. Defaults to 2.
+   *
+   * If changed to e.g. 1:
+   * - sections will have the attribute `aria-level` with value 1
+   * - non-nested widgets will have the attribute `aria-level` with value 1
+   * - nested widgets will have the attribute `aria-level` with value 2
+   *
+   * @attr {number} root-heading-level
+   */
+  rootHeadingLevel: number | null | undefined;
 }

packages/dashboard/src/vaadin-dashboard-layout-mixin.js

@@ -31,9 +31,36 @@ export const DashboardLayoutMixin = (superClass) =>
           value: false,
           reflectToAttribute: true,
         },
+
+        /**
+         * Root heading level for sections and widgets. Defaults to 2.
+         *
+         * If changed to e.g. 1:
+         * - sections will have the attribute `aria-level` with value 1
+         * - non-nested widgets will have the attribute `aria-level` with value 1
+         * - nested widgets will have the attribute `aria-level` with value 2
+         *
+         * @attr {number} root-heading-level
+         */
+        rootHeadingLevel: {
+          type: Number,
+          value: 2,
+          sync: true,
+          reflectToAttribute: true,
+          observer: '__rootHeadingLevelChanged',
+        },
       };
     }
 
+    constructor() {
+      super();
+
+      /**
+       * Used for mixin detection because `instanceof` does not work with mixins.
+       */
+      this.__hasVaadinDashboardLayoutMixin = true;
+    }
+
     /** @protected */
     ready() {
       super.ready();
@@ -63,4 +90,11 @@ export const DashboardLayoutMixin = (superClass) =>
       // ...and set it as the new value
       this.$.grid.style.setProperty('--_col-count', columnCount);
     }
+
+    /** @private */
+    __rootHeadingLevelChanged(rootHeadingLevel) {
+      this.dispatchEvent(
+        new CustomEvent('dashboard-root-heading-level-changed', { detail: { value: rootHeadingLevel } }),
+      );
+    }
   };

packages/dashboard/src/vaadin-dashboard-section.js

@@ -124,11 +124,6 @@ class DashboardSection extends DashboardItemMixin(
         value: '',
       },
 
-      /* @private */
-      __rootHeadingLevel: {
-        type: Number,
-      },
-
       /** @private */
       __childCount: {
         type: Number,
@@ -147,7 +142,7 @@ class DashboardSection extends DashboardItemMixin(
 
         <header part="header">
           ${this.__renderDragHandle()}
-          <div id="title" role="heading" aria-level=${this.__rootHeadingLevel || 2} part="title"
+          <div id="title" role="heading" aria-level=${this._rootHeadingLevel || 2} part="title"
             >${this.sectionTitle}</div
           >
           ${this.__renderRemoveButton()}

packages/dashboard/src/vaadin-dashboard-widget.js

@@ -164,11 +164,6 @@ class DashboardWidget extends DashboardItemMixin(
         value: '',
       },
 
-      /* @private */
-      __rootHeadingLevel: {
-        type: Number,
-      },
-
       /* @private */
       __isNestedWidget: {
         type: Boolean,
@@ -210,7 +205,6 @@ class DashboardWidget extends DashboardItemMixin(
         this.toggleAttribute(attr, !!wrapper[attr]);
       });
       this.__i18n = wrapper.i18n;
-      this.__rootHeadingLevel = wrapper.__rootHeadingLevel;
     }
 
     this.__updateNestedState();
@@ -232,7 +226,7 @@ class DashboardWidget extends DashboardItemMixin(
 
   /** @private */
   __renderWidgetTitle() {
-    let effectiveHeadingLevel = this.__rootHeadingLevel;
+    let effectiveHeadingLevel = this._rootHeadingLevel;
     // Default to 2 if not defined
     if (effectiveHeadingLevel == null) {
       effectiveHeadingLevel = 2;

packages/dashboard/src/vaadin-dashboard.d.ts

@@ -243,16 +243,6 @@ declare class Dashboard<TItem extends DashboardItem = DashboardItem> extends Das
    */
   editable: boolean;
 
-  /**
-   * Root heading level for sections and widgets. Defaults to 2.
-   *
-   * If changed to e.g. 1:
-   * - sections will have the attribute `aria-level` with value 1
-   * - non-nested widgets will have the attribute `aria-level` with value 1
-   * - nested widgets will have the attribute `aria-level` with value 2
-   */
-  rootHeadingLevel: number | null | undefined;
-
   /**
    * The object used to localize this component. To change the default
    * localization, replace this with an object that provides all properties, or

packages/dashboard/src/vaadin-dashboard.js

@@ -158,20 +158,6 @@ class Dashboard extends DashboardLayoutMixin(
         type: Boolean,
       },
 
-      /**
-       * Root heading level for sections and widgets. Defaults to 2.
-       *
-       * If changed to e.g. 1:
-       * - sections will have the attribute `aria-level` with value 1
-       * - non-nested widgets will have the attribute `aria-level` with value 1
-       * - nested widgets will have the attribute `aria-level` with value 2
-       */
-      rootHeadingLevel: {
-        type: Number,
-        value: 2,
-        sync: true,
-      },
-
       /** @private */
       __childCount: {
         type: Number,
@@ -181,7 +167,7 @@ class Dashboard extends DashboardLayoutMixin(
   }
 
   static get observers() {
-    return ['__itemsOrRendererChanged(items, renderer, editable, __effectiveI18n, rootHeadingLevel)'];
+    return ['__itemsOrRendererChanged(items, renderer, editable, __effectiveI18n)'];
   }
 
   /**
@@ -267,7 +253,6 @@ class Dashboard extends DashboardLayoutMixin(
           wrapper.firstElementChild.toggleAttribute(attr, !!wrapper[attr]);
         });
         wrapper.firstElementChild.__i18n = this.__effectiveI18n;
-        wrapper.firstElementChild.__rootHeadingLevel = this.rootHeadingLevel;
       }
     });
   }
@@ -311,7 +296,6 @@ class Dashboard extends DashboardLayoutMixin(
 
         SYNCHRONIZED_ATTRIBUTES.forEach((attr) => section.toggleAttribute(attr, !!wrapper[attr]));
         section.__i18n = this.__effectiveI18n;
-        section.__rootHeadingLevel = this.rootHeadingLevel;
 
         // Render the subitems
         section.__childCount = item.items.length;
@@ -436,7 +420,6 @@ class Dashboard extends DashboardLayoutMixin(
     wrapper['first-child'] = item === getItemsArrayOfItem(item, this.items)[0];
     wrapper['last-child'] = item === getItemsArrayOfItem(item, this.items).slice(-1)[0];
     wrapper.i18n = this.__effectiveI18n;
-    wrapper.__rootHeadingLevel = this.rootHeadingLevel;
   }
 
   /** @private */