feat: make root heading level on dashboard customizable (#8885)

ugur-vaadin · web-flow · commit 11031d772d11 · 2025-04-07T20:09:59.000+03:00
* feat: make root heading level on dahsboard customizable

* fix: initialize listener correctly

* fix: do not use css property to determine whether widget is nested

* chore: update jsdocs in order to match the implementation

* refactor: remove root heading level event and use i18n approach

* refactor: only update widget nested state on connected callback

* fix: add heading role

* refactor: remove unnecessary default

* refactor: do not reflect as attribute
diff --git a/packages/dashboard/src/vaadin-dashboard-helpers.js b/packages/dashboard/src/vaadin-dashboard-helpers.js
@@ -101,3 +101,31 @@ export function fireResize(element, colspanDelta, rowspanDelta) {
 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) {
+  while (node) {
+    if (node instanceof baseClass) {
+      return node;
+    }
+    if (node instanceof ShadowRoot) {
+      node = node.host;
+    } else {
+      const rootNode = node.getRootNode();
+      if (rootNode instanceof ShadowRoot) {
+        node = rootNode.host;
+      } else if (node.parentNode) {
+        node = node.parentNode;
+      } else {
+        node = null;
+      }
+    }
+  }
+  return null;
+}
diff --git a/packages/dashboard/src/vaadin-dashboard-section.js b/packages/dashboard/src/vaadin-dashboard-section.js
@@ -102,7 +102,6 @@ class DashboardSection extends DashboardItemMixin(ElementMixin(ThemableMixin(Pol
         }
 
         ::slotted(*) {
-          --_vaadin-dashboard-title-level: 3;
           --_vaadin-dashboard-item-column: span
             min(
               var(--vaadin-dashboard-item-colspan, 1),
@@ -166,6 +165,11 @@ class DashboardSection extends DashboardItemMixin(ElementMixin(ThemableMixin(Pol
         value: '',
       },
 
+      /* @private */
+      __rootHeadingLevel: {
+        type: Number,
+      },
+
       /** @private */
       __childCount: {
         type: Number,
@@ -184,7 +188,9 @@ class DashboardSection extends DashboardItemMixin(ElementMixin(ThemableMixin(Pol
 
         <header part="header">
           ${this.__renderDragHandle()}
-          <h2 id="title" part="title">${this.sectionTitle}</h2>
+          <div id="title" role="heading" aria-level=${this.__rootHeadingLevel || 2} part="title"
+            >${this.sectionTitle}</div
+          >
           ${this.__renderRemoveButton()}
         </header>
       </div>
diff --git a/packages/dashboard/src/vaadin-dashboard-widget.js b/packages/dashboard/src/vaadin-dashboard-widget.js
@@ -13,9 +13,10 @@ import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
 import { css, ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
-import { SYNCHRONIZED_ATTRIBUTES, WRAPPER_LOCAL_NAME } from './vaadin-dashboard-helpers.js';
+import { findAncestorInstance, SYNCHRONIZED_ATTRIBUTES, WRAPPER_LOCAL_NAME } from './vaadin-dashboard-helpers.js';
 import { DashboardItemMixin } from './vaadin-dashboard-item-mixin.js';
 import { getDefaultI18n } from './vaadin-dashboard-item-mixin.js';
+import { DashboardSection } from './vaadin-dashboard-section.js';
 
 /**
  * A Widget component for use with the Dashboard component
@@ -193,11 +194,15 @@ class DashboardWidget extends DashboardItemMixin(ElementMixin(ThemableMixin(Poly
       widgetTitle: {
         type: String,
         value: '',
-        observer: '__onWidgetTitleChanged',
       },
 
       /* @private */
-      __nestedHeadingLevel: {
+      __rootHeadingLevel: {
+        type: Number,
+      },
+
+      /* @private */
+      __isNestedWidget: {
         type: Boolean,
         value: false,
       },
@@ -213,10 +218,7 @@ class DashboardWidget extends DashboardItemMixin(ElementMixin(ThemableMixin(Poly
         ${this.__renderFocusButton('selectWidget')}
 
         <header part="header">
-          ${this.__renderDragHandle()}
-          ${this.__nestedHeadingLevel
-            ? html`<h3 id="title" part="title" .hidden=${!this.widgetTitle}>${this.widgetTitle}</h3>`
-            : html`<h2 id="title" part="title" .hidden=${!this.widgetTitle}>${this.widgetTitle}</h2>`}
+          ${this.__renderDragHandle()} ${this.__renderWidgetTitle()}
           <slot name="header-content"></slot>
           ${this.__renderRemoveButton()}
         </header>
@@ -240,13 +242,15 @@ class DashboardWidget extends DashboardItemMixin(ElementMixin(ThemableMixin(Poly
         this.toggleAttribute(attr, !!wrapper[attr]);
       });
       this.__i18n = wrapper.i18n;
+      this.__rootHeadingLevel = wrapper.__rootHeadingLevel;
     }
 
+    this.__updateNestedState();
     const undefinedAncestor = this.closest('*:not(:defined)');
     if (undefinedAncestor) {
-      customElements.whenDefined(undefinedAncestor.localName).then(() => queueMicrotask(() => this.__updateTitle()));
-    } else {
-      this.__updateTitle();
+      customElements.whenDefined(undefinedAncestor.localName).then(() => {
+        queueMicrotask(() => this.__updateNestedState());
+      });
     }
   }
 
@@ -259,14 +263,29 @@ class DashboardWidget extends DashboardItemMixin(ElementMixin(ThemableMixin(Poly
   }
 
   /** @private */
-  __onWidgetTitleChanged() {
-    this.__updateTitle();
+  __renderWidgetTitle() {
+    let effectiveHeadingLevel = this.__rootHeadingLevel;
+    // Default to 2 if not defined
+    if (effectiveHeadingLevel == null) {
+      effectiveHeadingLevel = 2;
+    }
+    // Increase level by 1 for widgets in sections
+    if (this.__isNestedWidget) {
+      effectiveHeadingLevel += 1;
+    }
+    return html`<div
+      id="title"
+      part="title"
+      role="heading"
+      aria-level=${effectiveHeadingLevel}
+      .hidden=${!this.widgetTitle}
+      >${this.widgetTitle}</div
+    >`;
   }
 
   /** @private */
-  __updateTitle() {
-    const titleLevel = getComputedStyle(this).getPropertyValue('--_vaadin-dashboard-title-level');
-    this.__nestedHeadingLevel = titleLevel === '3';
+  __updateNestedState() {
+    this.__isNestedWidget = !!findAncestorInstance(this, DashboardSection);
   }
 }
 
diff --git a/packages/dashboard/src/vaadin-dashboard.d.ts b/packages/dashboard/src/vaadin-dashboard.d.ts
@@ -202,11 +202,11 @@ export interface DashboardI18n {
  *
  * The following state attributes are available for styling:
  *
- * Attribute      | Description
- * ---------------|-------------
- * `editable`     | Set when the dashboard is editable.
- * `dense-layout` | Set when the dashboard is in dense mode.
- * `item-selected`| Set when an item is selected.
+ * Attribute            | Description
+ * ---------------------|-------------
+ * `editable`           | Set when the dashboard is editable.
+ * `dense-layout`       | Set when the dashboard is in dense mode.
+ * `item-selected`      | Set when an item is selected.
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
@@ -243,6 +243,16 @@ 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
diff --git a/packages/dashboard/src/vaadin-dashboard.js b/packages/dashboard/src/vaadin-dashboard.js
@@ -82,11 +82,11 @@ import { WidgetResizeController } from './widget-resize-controller.js';
  *
  * The following state attributes are available for styling:
  *
- * Attribute      | Description
- * ---------------|-------------
- * `editable`     | Set when the dashboard is editable.
- * `dense-layout` | Set when the dashboard is in dense mode.
- * `item-selected`| Set when an item is selected.
+ * Attribute            | Description
+ * ---------------------|-------------
+ * `editable`           | Set when the dashboard is editable.
+ * `dense-layout`       | Set when the dashboard is in dense mode.
+ * `item-selected`      | Set when an item is selected.
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
@@ -166,6 +166,20 @@ 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,
@@ -175,7 +189,7 @@ class Dashboard extends DashboardLayoutMixin(
   }
 
   static get observers() {
-    return ['__itemsOrRendererChanged(items, renderer, editable, __effectiveI18n)'];
+    return ['__itemsOrRendererChanged(items, renderer, editable, __effectiveI18n, rootHeadingLevel)'];
   }
 
   /**
@@ -261,6 +275,7 @@ class Dashboard extends DashboardLayoutMixin(
           wrapper.firstElementChild.toggleAttribute(attr, !!wrapper[attr]);
         });
         wrapper.firstElementChild.__i18n = this.__effectiveI18n;
+        wrapper.firstElementChild.__rootHeadingLevel = this.rootHeadingLevel;
       }
     });
   }
@@ -304,6 +319,7 @@ 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;
@@ -428,6 +444,7 @@ 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 */
diff --git a/packages/dashboard/test/dashboard-widget.test.ts b/packages/dashboard/test/dashboard-widget.test.ts
@@ -152,23 +152,23 @@ describe('dashboard widget', () => {
 });
 
 describe('widget title level', () => {
-  it('should have h2 title by default', async () => {
+  it('should have title heading level 2 by default', async () => {
     const widget = fixtureSync(`<vaadin-dashboard-widget widget-title="foo"></vaadin-dashboard-widget>`);
     await nextFrame();
 
     const title = getTitleElement(widget as DashboardWidget);
-    expect(title?.localName).to.equal('h2');
+    expect(title?.getAttribute('aria-level')).to.equal('2');
   });
 
-  it('should have h2 title by default on the section', async () => {
+  it('should have title heading level 2 by default on the section', async () => {
     const section = fixtureSync(`<vaadin-dashboard-section section-title="foo"></vaadin-dashboard-section>`);
     await nextFrame();
 
     const title = getTitleElement(section as DashboardSection);
-    expect(title?.localName).to.equal('h2');
+    expect(title?.getAttribute('aria-level')).to.equal('2');
   });
 
-  it('should have h3 title when rendered inside a section', async () => {
+  it('should have title heading level 3 when rendered inside a section', async () => {
     const widget = fixtureSync(`
       <vaadin-dashboard-section>
         <vaadin-dashboard-widget widget-title="foo"></vaadin-dashboard-widget>
@@ -177,10 +177,10 @@ describe('widget title level', () => {
     await nextFrame();
 
     const title = getTitleElement(widget);
-    expect(title?.localName).to.equal('h3');
+    expect(title?.getAttribute('aria-level')).to.equal('3');
   });
 
-  it('should have h2 title after moving out of a section', async () => {
+  it('should have title heading level 2 after moving out of a section', async () => {
     const widget = fixtureSync(`
       <div>
         <vaadin-dashboard-section>
@@ -195,10 +195,10 @@ describe('widget title level', () => {
     await nextFrame();
 
     const title = getTitleElement(widget);
-    expect(title?.localName).to.equal('h2');
+    expect(title?.getAttribute('aria-level')).to.equal('2');
   });
 
-  it('should have h3 title after moving into a section', async () => {
+  it('should have title heading level 3 after moving into a section', async () => {
     const widget = fixtureSync(`
       <div>
         <vaadin-dashboard-widget widget-title="foo"></vaadin-dashboard-widget>
@@ -212,10 +212,10 @@ describe('widget title level', () => {
     await nextFrame();
 
     const title = getTitleElement(widget);
-    expect(title?.localName).to.equal('h3');
+    expect(title?.getAttribute('aria-level')).to.equal('3');
   });
 
-  it('should have h3 title after defining parent section', async () => {
+  it('should have title heading level 3 after defining parent section', async () => {
     const widget = fixtureSync(`
       <my-custom-section>
         <vaadin-dashboard-widget widget-title="foo"></vaadin-dashboard-widget>
@@ -228,10 +228,10 @@ describe('widget title level', () => {
     await nextFrame();
 
     const title = getTitleElement(widget);
-    expect(title?.localName).to.equal('h3');
+    expect(title?.getAttribute('aria-level')).to.equal('3');
   });
 
-  it('should have h3 title after defining the widget', async () => {
+  it('should have title heading level 3 after defining the widget', async () => {
     const widget = fixtureSync(`
       <vaadin-dashboard-section>
         <my-custom-widget widget-title="foo"></my-custom-widget>
@@ -244,10 +244,10 @@ describe('widget title level', () => {
     await nextFrame();
 
     const title = getTitleElement(widget as DashboardWidget);
-    expect(title?.localName).to.equal('h3');
+    expect(title?.getAttribute('aria-level')).to.equal('3');
   });
 
-  it('should have h3 title after moving a wrapped widget into a section', async () => {
+  it('should have title heading level 3 after moving a wrapped widget into a section', async () => {
     const widget = fixtureSync(`
       <div>
         <div id="wrapper">
@@ -264,6 +264,6 @@ describe('widget title level', () => {
     await nextFrame();
 
     const title = getTitleElement(widget);
-    expect(title?.localName).to.equal('h3');
+    expect(title?.getAttribute('aria-level')).to.equal('3');
   });
 });
diff --git a/packages/dashboard/test/dashboard.test.ts b/packages/dashboard/test/dashboard.test.ts
