@vaadin/card 24.8.0-alpha4 → 24.8.0-alpha5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/card",
-  "version": "24.8.0-alpha4",
+  "version": "24.8.0-alpha5",
   "publishConfig": {
     "access": "public"
   },
@@ -34,15 +34,15 @@
     "web-component"
   ],
   "dependencies": {
-    "@vaadin/component-base": "24.8.0-alpha4",
-    "@vaadin/vaadin-lumo-styles": "24.8.0-alpha4",
-    "@vaadin/vaadin-material-styles": "24.8.0-alpha4",
-    "@vaadin/vaadin-themable-mixin": "24.8.0-alpha4",
+    "@vaadin/component-base": "24.8.0-alpha5",
+    "@vaadin/vaadin-lumo-styles": "24.8.0-alpha5",
+    "@vaadin/vaadin-material-styles": "24.8.0-alpha5",
+    "@vaadin/vaadin-themable-mixin": "24.8.0-alpha5",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/chai-plugins": "24.8.0-alpha4",
-    "@vaadin/test-runner-commands": "24.8.0-alpha4",
+    "@vaadin/chai-plugins": "24.8.0-alpha5",
+    "@vaadin/test-runner-commands": "24.8.0-alpha5",
     "@vaadin/testing-helpers": "^1.1.0",
     "sinon": "^18.0.0"
   },
@@ -50,5 +50,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "88251b4c84ebb8849dde982acb62cc2b20eeec31"
+  "gitHead": "3bb64b9ad9b00ac3adb94eb1bedd81b0f4ae574e"
 }

package/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 {

package/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]');
   }
 
   /**

package/web-types.json

@@ -1,15 +1,37 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/card",
-  "version": "24.8.0-alpha4",
+  "version": "24.8.0-alpha5",
   "description-markup": "markdown",
   "contributions": {
     "html": {
       "elements": [
         {
           "name": "vaadin-card",
-          "description": "`<vaadin-card>` is a versatile container for grouping related content and actions.\nIt presents information in a structured and visually appealing manner, with\ncustomization options to fit various design requirements.\n\n```html\n<vaadin-card theme=\"outlined cover-media\">\n  <img slot=\"media\" width=\"200\" src=\"...\" alt=\"\">\n  <div slot=\"title\">Lapland</div>\n  <div slot=\"subtitle\">The Exotic North</div>\n  <div>Lapland is the northern-most region of Finland and an active outdoor destination.</div>\n  <vaadin-button slot=\"footer\">Book Vacation</vaadin-button>\n</vaadin-card>\n```\n\n### Styling\n\nThe following shadow DOM parts are available for styling:\n\nPart name | Description\n----------|-------------\n`media`   | The container for the media element (e.g., image, video, icon). Shown above of before the card content.\n`header`  | The container for title and subtitle - or for custom header content - and header prefix and suffix elements.\n`content` | The container for the card content (usually text content).\n`footer`  | The container for footer elements. This part is always at the bottom of the card.\n\nThe following custom properties are available for styling:\n\nCustom property | Description | Default\n----------------|-------------|-------------\n`--vaadin-card-padding` | The space between the card edge and its content. Needs to a unified value for all edges, i.e., a single length value. | `1em`\n`--vaadin-card-gap`     | The space between content elements within the card. | `1em`\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
+          "description": "`<vaadin-card>` is a versatile container for grouping related content and actions.\nIt presents information in a structured and visually appealing manner, with\ncustomization options to fit various design requirements. The default ARIA role is `region`.\n\n```html\n<vaadin-card role=\"region\" theme=\"outlined cover-media\">\n  <img slot=\"media\" width=\"200\" src=\"...\" alt=\"\">\n  <div slot=\"title\">Lapland</div>\n  <div slot=\"subtitle\">The Exotic North</div>\n  <div>Lapland is the northern-most region of Finland and an active outdoor destination.</div>\n  <vaadin-button slot=\"footer\">Book Vacation</vaadin-button>\n</vaadin-card>\n```\n\n### Styling\n\nThe following shadow DOM parts are available for styling:\n\nPart name | Description\n----------|-------------\n`media`   | The container for the media element (e.g., image, video, icon). Shown above of before the card content.\n`header`  | The container for title and subtitle - or for custom header content - and header prefix and suffix elements.\n`content` | The container for the card content (usually text content).\n`footer`  | The container for footer elements. This part is always at the bottom of the card.\n\nThe following custom properties are available for styling:\n\nCustom property | Description | Default\n----------------|-------------|-------------\n`--vaadin-card-padding` | The space between the card edge and its content. Needs to a unified value for all edges, i.e., a single length value. | `1em`\n`--vaadin-card-gap`     | The space between content elements within the card. | `1em`\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
           "attributes": [
+            {
+              "name": "card-title",
+              "description": "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.",
+              "value": {
+                "type": [
+                  "string",
+                  "null",
+                  "undefined"
+                ]
+              }
+            },
+            {
+              "name": "title-heading-level",
+              "description": "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.",
+              "value": {
+                "type": [
+                  "number",
+                  "null",
+                  "undefined"
+                ]
+              }
+            },
             {
               "name": "theme",
               "description": "The theme variants to apply to the component.",
@@ -23,8 +45,36 @@
             }
           ],
           "js": {
-            "properties": [],
-            "events": []
+            "properties": [
+              {
+                "name": "cardTitle",
+                "description": "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.",
+                "value": {
+                  "type": [
+                    "string",
+                    "null",
+                    "undefined"
+                  ]
+                }
+              },
+              {
+                "name": "titleHeadingLevel",
+                "description": "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.",
+                "value": {
+                  "type": [
+                    "number",
+                    "null",
+                    "undefined"
+                  ]
+                }
+              }
+            ],
+            "events": [
+              {
+                "name": "card-title-changed",
+                "description": "Fired when the `cardTitle` property changes."
+              }
+            ]
           }
         }
       ]

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/card",
-  "version": "24.8.0-alpha4",
+  "version": "24.8.0-alpha5",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -16,9 +16,31 @@
       "elements": [
         {
           "name": "vaadin-card",
-          "description": "`<vaadin-card>` is a versatile container for grouping related content and actions.\nIt presents information in a structured and visually appealing manner, with\ncustomization options to fit various design requirements.\n\n```html\n<vaadin-card theme=\"outlined cover-media\">\n  <img slot=\"media\" width=\"200\" src=\"...\" alt=\"\">\n  <div slot=\"title\">Lapland</div>\n  <div slot=\"subtitle\">The Exotic North</div>\n  <div>Lapland is the northern-most region of Finland and an active outdoor destination.</div>\n  <vaadin-button slot=\"footer\">Book Vacation</vaadin-button>\n</vaadin-card>\n```\n\n### Styling\n\nThe following shadow DOM parts are available for styling:\n\nPart name | Description\n----------|-------------\n`media`   | The container for the media element (e.g., image, video, icon). Shown above of before the card content.\n`header`  | The container for title and subtitle - or for custom header content - and header prefix and suffix elements.\n`content` | The container for the card content (usually text content).\n`footer`  | The container for footer elements. This part is always at the bottom of the card.\n\nThe following custom properties are available for styling:\n\nCustom property | Description | Default\n----------------|-------------|-------------\n`--vaadin-card-padding` | The space between the card edge and its content. Needs to a unified value for all edges, i.e., a single length value. | `1em`\n`--vaadin-card-gap`     | The space between content elements within the card. | `1em`\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
+          "description": "`<vaadin-card>` is a versatile container for grouping related content and actions.\nIt presents information in a structured and visually appealing manner, with\ncustomization options to fit various design requirements. The default ARIA role is `region`.\n\n```html\n<vaadin-card role=\"region\" theme=\"outlined cover-media\">\n  <img slot=\"media\" width=\"200\" src=\"...\" alt=\"\">\n  <div slot=\"title\">Lapland</div>\n  <div slot=\"subtitle\">The Exotic North</div>\n  <div>Lapland is the northern-most region of Finland and an active outdoor destination.</div>\n  <vaadin-button slot=\"footer\">Book Vacation</vaadin-button>\n</vaadin-card>\n```\n\n### Styling\n\nThe following shadow DOM parts are available for styling:\n\nPart name | Description\n----------|-------------\n`media`   | The container for the media element (e.g., image, video, icon). Shown above of before the card content.\n`header`  | The container for title and subtitle - or for custom header content - and header prefix and suffix elements.\n`content` | The container for the card content (usually text content).\n`footer`  | The container for footer elements. This part is always at the bottom of the card.\n\nThe following custom properties are available for styling:\n\nCustom property | Description | Default\n----------------|-------------|-------------\n`--vaadin-card-padding` | The space between the card edge and its content. Needs to a unified value for all edges, i.e., a single length value. | `1em`\n`--vaadin-card-gap`     | The space between content elements within the card. | `1em`\n\nSee [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.",
           "extension": true,
-          "attributes": []
+          "attributes": [
+            {
+              "name": ".cardTitle",
+              "description": "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.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": ".titleHeadingLevel",
+              "description": "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.",
+              "value": {
+                "kind": "expression"
+              }
+            },
+            {
+              "name": "@card-title-changed",
+              "description": "Fired when the `cardTitle` property changes.",
+              "value": {
+                "kind": "expression"
+              }
+            }
+          ]
         }
       ]
     }