feat: add string based title and default role (#8822)

ugur-vaadin · web-padawan · web-flow · commit 63a88ca80a9e · 2025-03-27T12:57:39.000+02:00
* feat: add string based title and default role

* refactor: set role on ready

* refactor: use separate observers

* refactor: make title property notify

* Update packages/card/src/vaadin-card.js

Co-authored-by: Serhii Kulykov &lt;iamkulykov@gmail.com&gt;

* refactor: remove validation for title heading level

* refactor: reflect title heading level to attribute

* refactor: rename title to card title

* fix: add attribute annotations

* chore: remove unnecessary type annotations

* fix: change attribute type

---------

Co-authored-by: Serhii Kulykov &lt;iamkulykov@gmail.com&gt;
diff --git a/packages/card/src/vaadin-card.d.ts b/packages/card/src/vaadin-card.d.ts
@@ -9,10 +9,10 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
 /**
  * `<vaadin-card>` is a versatile container for grouping related content and actions.
  * It presents information in a structured and visually appealing manner, with
- * customization options to fit various design requirements.
+ * customization options to fit various design requirements. The default ARIA role is `region`.
  *
  * ```html
- * <vaadin-card theme="outlined cover-media">
+ * <vaadin-card role="region" theme="outlined cover-media">
  *   <img slot="media" width="200" src="..." alt="">
  *   <div slot="title">Lapland</div>
  *   <div slot="subtitle">The Exotic North</div>
@@ -41,7 +41,19 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  */
-declare class Card extends ElementMixin(ThemableMixin(HTMLElement)) {}
+declare class Card extends ElementMixin(ThemableMixin(HTMLElement)) {
+  /**
+   * The title of the card. When set, any custom slotted title is removed and this string-based title is used instead. If this title is used, an `aria-labelledby` attribute that points to the generated title element is set.
+   * @attr {string} card-title
+   */
+  cardTitle: string;
+
+  /**
+   * Sets the heading level (`aria-level`) for the string-based title. If not set, the level defaults to 2. Setting values outside the range [1, 6] can cause accessibility issues.
+   * @attr {number} title-heading-level
+   */
+  titleHeadingLevel: number | null | undefined;
+}
 
 declare global {
   interface HTMLElementTagNameMap {
diff --git a/packages/card/src/vaadin-card.js b/packages/card/src/vaadin-card.js
@@ -7,15 +7,16 @@ import { css, html, LitElement } from 'lit';
 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 { generateUniqueId } from '@vaadin/component-base/src/unique-id-utils.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 /**
  * `<vaadin-card>` is a versatile container for grouping related content and actions.
  * It presents information in a structured and visually appealing manner, with
- * customization options to fit various design requirements.
+ * customization options to fit various design requirements. The default ARIA role is `region`.
  *
  * ```html
- * <vaadin-card theme="outlined cover-media">
+ * <vaadin-card role="region" theme="outlined cover-media">
  *   <img slot="media" width="200" src="..." alt="">
  *   <div slot="title">Lapland</div>
  *   <div slot="subtitle">The Exotic North</div>
@@ -279,10 +280,47 @@ class Card extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
     `;
   }
 
+  static get properties() {
+    return {
+      /**
+       * The title of the card. When set, any custom slotted title is removed and this string-based title is used instead. If this title is used, an `aria-labelledby` attribute that points to the generated title element is set.
+       *
+       * @attr {string} card-title
+       */
+      cardTitle: {
+        type: String,
+        notify: true,
+        observer: '__cardTitleChanged',
+      },
+
+      /**
+       * Sets the heading level (`aria-level`) for the string-based title. If not set, the level defaults to 2. Setting values outside the range [1, 6] can cause accessibility issues.
+       *
+       * @attr {number} title-heading-level
+       */
+      titleHeadingLevel: {
+        type: Number,
+        reflectToAttribute: true,
+        observer: '__titleHeadingLevelChanged',
+      },
+    };
+  }
+
   static get experimental() {
     return true;
   }
 
+  /** @protected */
+  ready() {
+    super.ready();
+
+    // By default, if the user hasn't provided a custom role,
+    // the role attribute is set to "region".
+    if (!this.hasAttribute('role')) {
+      this.setAttribute('role', 'region');
+    }
+  }
+
   /** @protected */
   render() {
     return html`
@@ -322,6 +360,79 @@ class Card extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
     this.toggleAttribute('_hs', this.querySelector(':scope > [slot="header-suffix"]'));
     this.toggleAttribute('_c', this.querySelector(':scope > :not([slot])'));
     this.toggleAttribute('_f', this.querySelector(':scope > [slot="footer"]'));
+    if (this.__getCustomTitleElement()) {
+      this.__clearStringTitle();
+    }
+  }
+
+  /** @private */
+  __clearStringTitle() {
+    const stringTitleElement = this.__getStringTitleElement();
+    if (stringTitleElement) {
+      this.removeChild(stringTitleElement);
+    }
+    const ariaLabelledby = this.getAttribute('aria-labelledby');
+    if (ariaLabelledby && ariaLabelledby.startsWith('card-title-')) {
+      this.removeAttribute('aria-labelledby');
+    }
+    if (this.cardTitle) {
+      this.cardTitle = '';
+    }
+  }
+
+  /** @private */
+  __getCustomTitleElement() {
+    return Array.from(this.querySelectorAll('[slot="title"]')).find((el) => {
+      return !el.hasAttribute('card-string-title');
+    });
+  }
+
+  /** @private */
+  __cardTitleChanged(title) {
+    if (!title) {
+      this.__clearStringTitle();
+      return;
+    }
+    const customTitleElement = this.__getCustomTitleElement();
+    if (customTitleElement) {
+      this.removeChild(customTitleElement);
+    }
+    let stringTitleElement = this.__getStringTitleElement();
+    if (!stringTitleElement) {
+      stringTitleElement = this.__createStringTitleElement();
+      this.appendChild(stringTitleElement);
+      this.setAttribute('aria-labelledby', stringTitleElement.id);
+    }
+    stringTitleElement.textContent = title;
+  }
+
+  /** @private */
+  __createStringTitleElement() {
+    const stringTitleElement = document.createElement('div');
+    stringTitleElement.setAttribute('slot', 'title');
+    stringTitleElement.setAttribute('role', 'heading');
+    this.__setTitleHeadingLevel(stringTitleElement, this.titleHeadingLevel);
+    stringTitleElement.setAttribute('card-string-title', '');
+    stringTitleElement.id = `card-title-${generateUniqueId()}`;
+    return stringTitleElement;
+  }
+
+  /** @private */
+  __titleHeadingLevelChanged(titleHeadingLevel) {
+    const stringTitleElement = this.__getStringTitleElement();
+    if (stringTitleElement) {
+      this.__setTitleHeadingLevel(stringTitleElement, titleHeadingLevel);
+    }
+  }
+
+  /** @private */
+  __setTitleHeadingLevel(stringTitleElement, titleHeadingLevel) {
+    stringTitleElement.setAttribute('aria-level', titleHeadingLevel || 2);
+  }
+
+  /** @private */
+  __getStringTitleElement() {
+    return this.querySelector('[slot="title"][card-string-title]');
   }
 
   /**
diff --git a/packages/card/test/accessibility.test.js b/packages/card/test/accessibility.test.js
@@ -0,0 +1,42 @@
+import { expect } from '@vaadin/chai-plugins';
+import { fixtureSync, nextRender, nextUpdate } from '@vaadin/testing-helpers';
+import '../vaadin-card.js';
+
+window.Vaadin.featureFlags ||= {};
+window.Vaadin.featureFlags.cardComponent = true;
+
+describe('accessibility', () => {
+  let card;
+
+  beforeEach(async () => {
+    card = fixtureSync('<vaadin-card></vaadin-card>');
+    await nextRender(card);
+  });
+
+  describe('ARIA roles', () => {
+    it('should set "region" role by default on card', () => {
+      expect(card.getAttribute('role')).to.equal('region');
+    });
+  });
+
+  describe('label', () => {
+    it('should not have aria-labelledby attribute by default', () => {
+      expect(card.hasAttribute('aria-labelledby')).to.be.false;
+    });
+
+    it('should have aria-labelledby attribute when title property is set', async () => {
+      card.cardTitle = 'Some title';
+      await nextUpdate(card);
+      expect(card.hasAttribute('aria-labelledby')).to.be.true;
+    });
+
+    it('should remove aria-labelledby attribute when custom title element is set', async () => {
+      card.cardTitle = 'Some title';
+      await nextUpdate(card);
+      const customTitleElement = fixtureSync('<span slot="title">Custom title element</span>');
+      card.appendChild(customTitleElement);
+      await nextRender(card);
+      expect(card.hasAttribute('aria-labelledby')).to.be.false;
+    });
+  });
+});
diff --git a/packages/card/test/card.test.ts b/packages/card/test/card.test.ts
@@ -1,5 +1,5 @@
 import { expect } from '@vaadin/chai-plugins';
-import { fixtureSync } from '@vaadin/testing-helpers';
+import { fixtureSync, nextRender } from '@vaadin/testing-helpers';
 import '../vaadin-card.js';
 import type { Card } from '../vaadin-card.js';
 
@@ -9,11 +9,14 @@ window.Vaadin.featureFlags.cardComponent = true;
 describe('vaadin-card', () => {
   let card: Card;
 
+  beforeEach(() => {
+    card = fixtureSync('<vaadin-card></vaadin-card>');
+  });
+
   describe('custom element definition', () => {
     let tagName: string;
 
     beforeEach(() => {
-      card = fixtureSync('<vaadin-card></vaadin-card>');
       tagName = card.tagName.toLowerCase();
     });
 
@@ -25,4 +28,78 @@ describe('vaadin-card', () => {
       expect((customElements.get(tagName) as any).is).to.equal(tagName);
     });
   });
+
+  describe('title', () => {
+    function getStringTitleElement() {
+      return card.querySelector('[slot="title"][card-string-title]') as HTMLElement;
+    }
+
+    function getCustomTitleElement() {
+      return Array.from(card.querySelectorAll('[slot="title"]')).find((el) => {
+        return !el.hasAttribute('card-string-title');
+      });
+    }
+
+    it('should create title element with default aria-level when title property is set', async () => {
+      const stringTitle = 'Some title';
+      card.cardTitle = stringTitle;
+      await nextRender(card);
+      const stringTitleElement = getStringTitleElement();
+      expect(stringTitleElement).to.exist;
+      expect(stringTitleElement.getAttribute('aria-level')).to.equal('2');
+      expect(stringTitleElement.textContent).to.equal(stringTitle);
+    });
+
+    it('should update aria-level when heading level changes', async () => {
+      card.cardTitle = 'Some title';
+      card.titleHeadingLevel = 3;
+      await nextRender(card);
+      const stringTitleElement = getStringTitleElement();
+      expect(stringTitleElement.getAttribute('aria-level')).to.equal('3');
+    });
+
+    it('should use default heading level when set to null', async () => {
+      card.titleHeadingLevel = 3;
+      card.cardTitle = 'Some title';
+      card.titleHeadingLevel = null;
+      await nextRender(card);
+      expect(getStringTitleElement().getAttribute('aria-level')).to.equal('2');
+    });
+
+    it('should clear string title when custom title element is used', async () => {
+      card.cardTitle = 'Some title';
+      await nextRender(card);
+      const customTitleElement = fixtureSync('<span slot="title">Custom title element</span>');
+      card.appendChild(customTitleElement);
+      await nextRender(card);
+      expect(card.cardTitle).to.be.not.ok;
+      expect(getStringTitleElement()).to.not.exist;
+    });
+
+    it('should clear string title when empty string title is set', async () => {
+      card.cardTitle = 'Some title';
+      await nextRender(card);
+      card.cardTitle = '';
+      await nextRender(card);
+      expect(getStringTitleElement()).to.not.exist;
+    });
+
+    it('should clear custom title element when string title is set', async () => {
+      const customTitleElement = fixtureSync('<span slot="title">Custom title element</span>');
+      card.appendChild(customTitleElement);
+      await nextRender(card);
+      card.cardTitle = 'Some title';
+      await nextRender(card);
+      expect(getCustomTitleElement()).to.not.exist;
+    });
+
+    it('should not clear custom title element when empty string title is set', async () => {
+      const customTitleElement = fixtureSync('<span slot="title">Custom title element</span>');
+      card.appendChild(customTitleElement);
+      await nextRender(card);
+      card.cardTitle = '';
+      await nextRender(card);
+      expect(getCustomTitleElement()).to.exist;
+    });
+  });
 });
diff --git a/packages/card/test/visual/lumo/card.test.js b/packages/card/test/visual/lumo/card.test.js
@@ -60,6 +60,12 @@ describe('card', () => {
       await visualDiff(div, 'slot-title');
     });
 
+    it('string title', async () => {
+      element = cardFixture();
+      element.cardTitle = 'Title lorem ipsum';
+      await visualDiff(div, 'string-title');
+    });
+
     it('subtitle', async () => {
       element = cardFixture(subTitle);
       await visualDiff(div, 'slot-subtitle');
diff --git a/packages/card/test/visual/lumo/screenshots/card/baseline/string-title.png b/packages/card/test/visual/lumo/screenshots/card/baseline/string-title.png
diff --git a/packages/card/test/visual/material/card.test.js b/packages/card/test/visual/material/card.test.js
@@ -61,6 +61,12 @@ describe('card', () => {
       await visualDiff(div, 'slot-title');
     });
 
+    it('string title', async () => {
+      element = cardFixture();
+      element.cardTitle = 'Title lorem ipsum';
+      await visualDiff(div, 'string-title');
+    });
+
     it('subtitle', async () => {
       element = cardFixture(subTitle);
       await visualDiff(div, 'slot-subtitle');
diff --git a/packages/card/test/visual/material/screenshots/card/baseline/string-title.png b/packages/card/test/visual/material/screenshots/card/baseline/string-title.png
