@vaadin/card 24.8.0-alpha2 → 24.8.0-alpha20

package/README.md

@@ -2,8 +2,6 @@
 
 A visual content container.
 
-> ⚠️ This component is experimental and the API may change. In order to use it, enable the feature flag by setting `window.Vaadin.featureFlags.cardComponent = true`.
-
 [Documentation + Live Demo ↗](https://vaadin.com/docs/latest/components/card)
 
 [![npm version](https://badgen.net/npm/v/@vaadin/card)](https://www.npmjs.com/package/@vaadin/card)

package/package.json

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

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>
@@ -235,6 +236,8 @@ class Card extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
         height: auto;
         aspect-ratio: var(--vaadin-card-media-aspect-ratio, 16/9);
         object-fit: cover;
+        /* Fixes an issue where an icon overflows the card boundaries on Firefox: https://github.com/vaadin/web-components/issues/8641 */
+        overflow: hidden;
       }
 
       :host([theme~='horizontal']:is([theme~='cover-media'], [theme~='stretch-media'])) {
@@ -279,8 +282,40 @@ class Card extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
     `;
   }
 
-  static get experimental() {
-    return true;
+  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,
+        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',
+      },
+    };
+  }
+
+  /** @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 */
@@ -322,6 +357,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/theme/lumo/vaadin-card-styles.js

@@ -6,12 +6,13 @@ import { addGlobalThemeStyles, css, registerStyles } from '@vaadin/vaadin-themab
 
 const cardProps = css`
   html {
-    --vaadin-card-background: var(--lumo-shade-5pct);
+    --vaadin-card-background: var(--lumo-contrast-5pct);
     --vaadin-card-border-radius: var(--lumo-border-radius-l);
     --vaadin-card-border-width: 0;
     --vaadin-card-border-color: var(--lumo-contrast-20pct);
     --vaadin-card-padding: var(--lumo-space-m);
     --vaadin-card-gap: var(--lumo-space-m);
+    --vaadin-card-shadow: none;
   }
 `;
 
@@ -21,7 +22,7 @@ const card = css`
   :host {
     background: var(--vaadin-card-background);
     border-radius: var(--vaadin-card-border-radius);
-    box-shadow: var(--vaadin-card-box-shadow);
+    box-shadow: var(--vaadin-card-shadow);
     position: relative;
   }
 
@@ -29,28 +30,27 @@ const card = css`
   :host::before {
     content: '';
     position: absolute;
-    inset: 0;
-    pointer-events: none;
-    border-radius: inherit;
+    inset: var(--_card-border-inset, 0);
+    border-radius: var(--_card-border-pseudo-radius, inherit);
     border: var(--vaadin-card-border, var(--vaadin-card-border-width) solid var(--vaadin-card-border-color));
+    pointer-events: none;
   }
 
   :host([theme~='outlined']) {
     --vaadin-card-border-width: 1px;
-    --vaadin-card-background: transparent;
+    --vaadin-card-background: var(--lumo-base-color);
   }
 
   :host([theme~='elevated']) {
-    --vaadin-card-background: var(--lumo-tint-10pct);
-    --vaadin-card-box-shadow: var(--lumo-box-shadow-xs);
-    /* TODO I would like to update --lumo-box-shadow-xs to this (30pct instead of 50pct): */
-    --lumo-box-shadow-xs: 0 1px 4px -1px var(--lumo-shade-30pct);
+    --vaadin-card-background: linear-gradient(var(--lumo-tint-5pct), var(--lumo-tint-5pct)) var(--lumo-base-color);
+    --vaadin-card-shadow: var(--lumo-box-shadow-xs);
+    --vaadin-card-border-width: 1px;
+    --_card-border-inset: calc(-1 * var(--vaadin-card-border-width));
+    --_card-border-pseudo-radius: calc(var(--vaadin-card-border-radius) + var(--vaadin-card-border-width));
   }
 
-  :host([theme~='elevated'][theme~='outlined']) {
-    box-shadow:
-      inset 0 -1px 0 0 var(--lumo-shade-10pct),
-      var(--vaadin-card-box-shadow);
+  :host([theme~='elevated']:not([theme~='outlined'])) {
+    --vaadin-card-border-color: var(--lumo-contrast-10pct);
   }
 
   :host(:where([theme~='stretch-media'])) ::slotted([slot='media']:is(img, video, svg, vaadin-icon)) {

package/web-types.json

@@ -1,15 +1,37 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/card",
-  "version": "24.8.0-alpha2",
+  "version": "24.8.0-alpha20",
   "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,7 +45,30 @@
             }
           ],
           "js": {
-            "properties": [],
+            "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": []
           }
         }

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/card",
-  "version": "24.8.0-alpha2",
+  "version": "24.8.0-alpha20",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -16,9 +16,24 @@
       "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"
+              }
+            }
+          ]
         }
       ]
     }