@vaadin/card 25.3.0-alpha2 → 25.3.0-alpha3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/card",
-  "version": "25.3.0-alpha2",
+  "version": "25.3.0-alpha3",
   "publishConfig": {
     "access": "public"
   },
@@ -34,20 +34,20 @@
     "web-component"
   ],
   "dependencies": {
-    "@vaadin/component-base": "25.3.0-alpha2",
-    "@vaadin/vaadin-themable-mixin": "25.3.0-alpha2",
+    "@vaadin/component-base": "25.3.0-alpha3",
+    "@vaadin/vaadin-themable-mixin": "25.3.0-alpha3",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/aura": "25.3.0-alpha2",
-    "@vaadin/avatar": "25.3.0-alpha2",
-    "@vaadin/button": "25.3.0-alpha2",
-    "@vaadin/chai-plugins": "25.3.0-alpha2",
-    "@vaadin/icon": "25.3.0-alpha2",
-    "@vaadin/icons": "25.3.0-alpha2",
-    "@vaadin/test-runner-commands": "25.3.0-alpha2",
+    "@vaadin/aura": "25.3.0-alpha3",
+    "@vaadin/avatar": "25.3.0-alpha3",
+    "@vaadin/button": "25.3.0-alpha3",
+    "@vaadin/chai-plugins": "25.3.0-alpha3",
+    "@vaadin/icon": "25.3.0-alpha3",
+    "@vaadin/icons": "25.3.0-alpha3",
+    "@vaadin/test-runner-commands": "25.3.0-alpha3",
     "@vaadin/testing-helpers": "^2.0.0",
-    "@vaadin/vaadin-lumo-styles": "25.3.0-alpha2",
+    "@vaadin/vaadin-lumo-styles": "25.3.0-alpha3",
     "sinon": "^22.0.0"
   },
   "customElements": "custom-elements.json",
@@ -55,5 +55,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "52eba6153ecf8bfaae44bcb727595e77d90b963c"
+  "gitHead": "ba0c4c55ea219eadd9aefe244f53e87803a066c8"
 }

package/src/title-controller.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright (c) 2024 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { SlotChildObserveController } from '@vaadin/component-base/src/slot-child-observe-controller.js';
+
+/**
+ * A controller to manage the card title element.
+ */
+export class TitleController extends SlotChildObserveController {
+  constructor(host: HTMLElement);
+
+  /**
+   * Set title based on the corresponding host property.
+   */
+  setTitle(title: string): void;
+
+  /**
+   * Set heading level based on the corresponding host property.
+   */
+  setLevel(level: number): void;
+}

package/src/title-controller.js

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * Copyright (c) 2024 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { SlotChildObserveController } from '@vaadin/component-base/src/slot-child-observe-controller.js';
+
+/**
+ * A controller to manage the card title element.
+ */
+export class TitleController extends SlotChildObserveController {
+  constructor(host) {
+    // Do not provide tag name, as we create the title lazily.
+    super(host, 'title', null, { uniqueIdPrefix: 'card-title' });
+  }
+
+  /**
+   * Set title based on the corresponding host property.
+   *
+   * @param {string} title
+   */
+  setTitle(title) {
+    this.title = title;
+
+    if (title && title.trim() !== '') {
+      // The string title replaces a custom slotted title, if any.
+      const child = this.getSlotChild();
+      if (child && child !== this.defaultNode) {
+        child.remove();
+      }
+
+      // Create or restore the default title node.
+      this.restoreDefaultNode();
+      this.updateDefaultNode(this.node);
+    } else if (this.node && this.node === this.defaultNode) {
+      // Clearing the string title removes the generated node.
+      this.node.remove();
+    }
+  }
+
+  /**
+   * Set heading level based on the corresponding host property.
+   *
+   * @param {number} level
+   */
+  setLevel(level) {
+    this.level = level;
+
+    // When the default title is used, update it.
+    if (this.node && this.node === this.defaultNode) {
+      this.updateDefaultNode(this.node);
+    }
+  }
+
+  /**
+   * Override method inherited from `SlotController` to set up the default
+   * title node as a heading and label the card by it. The heading role and
+   * `aria-labelledby` are only applied to the generated string title, never
+   * to a custom slotted title.
+   *
+   * @param {Node} node
+   * @protected
+   * @override
+   */
+  initNode(node) {
+    if (node && node === this.defaultNode) {
+      node.setAttribute('role', 'heading');
+      this.host.setAttribute('aria-labelledby', node.id);
+    }
+  }
+
+  /**
+   * Override method inherited from `SlotChildObserveController` to handle a
+   * custom title element. Skips the default `super` call so the custom node
+   * keeps no generated ID. Clears the string title property, as a custom
+   * title takes over.
+   *
+   * @param {Node} _node
+   * @protected
+   * @override
+   */
+  initCustomNode(_node) {
+    this.host.cardTitle = '';
+  }
+
+  /**
+   * Override method inherited from `SlotChildObserveController` to drop the
+   * labelling once the generated title node leaves the slot and is not
+   * replaced by a custom title.
+   *
+   * @param {Node} node
+   * @protected
+   * @override
+   */
+  teardownNode(node) {
+    if (this.getSlotChild() !== this.defaultNode) {
+      this.host.removeAttribute('aria-labelledby');
+    }
+
+    super.teardownNode(node);
+  }
+
+  /**
+   * Override method inherited from `SlotChildObserveController`
+   * to create the default title element lazily as needed.
+   *
+   * @protected
+   * @override
+   */
+  restoreDefaultNode() {
+    const { title } = this;
+
+    // No title yet, create one.
+    if (title && title.trim() !== '') {
+      this.tagName = 'div';
+
+      const node = this.attachDefaultNode();
+      this.initNode(node);
+    }
+  }
+
+  /**
+   * Override method inherited from `SlotChildObserveController`
+   * to update the default title element.
+   *
+   * @param {Node | undefined} node
+   * @protected
+   * @override
+   */
+  updateDefaultNode(node) {
+    if (node) {
+      node.textContent = this.title;
+      node.setAttribute('aria-level', this.level || 2);
+    }
+
+    // Notify the host after update.
+    super.updateDefaultNode(node);
+  }
+}

package/src/vaadin-card.js

@@ -8,10 +8,10 @@ import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { isEmptyTextNode } from '@vaadin/component-base/src/dom-utils.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 { LumoInjectionMixin } from '@vaadin/vaadin-themable-mixin/lumo-injection-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 import { cardStyles } from './styles/vaadin-card-base-styles.js';
+import { TitleController } from './title-controller.js';
 
 /**
  * `<vaadin-card>` is a versatile container for grouping related content and actions.
@@ -86,7 +86,6 @@ class Card extends ElementMixin(ThemableMixin(PolylitMixin(LumoInjectionMixin(Li
        */
       cardTitle: {
         type: String,
-        observer: '__cardTitleChanged',
       },
 
       /**
@@ -97,7 +96,6 @@ class Card extends ElementMixin(ThemableMixin(PolylitMixin(LumoInjectionMixin(Li
       titleHeadingLevel: {
         type: Number,
         reflectToAttribute: true,
-        observer: '__titleHeadingLevelChanged',
       },
     };
   }
@@ -139,9 +137,26 @@ class Card extends ElementMixin(ThemableMixin(PolylitMixin(LumoInjectionMixin(Li
   /** @protected */
   firstUpdated() {
     super.firstUpdated();
+
+    this.__titleController = new TitleController(this);
+    this.addController(this.__titleController);
+
     this._onSlotChange();
   }
 
+  /** @protected */
+  updated(props) {
+    super.updated(props);
+
+    if (props.has('cardTitle')) {
+      this.__titleController.setTitle(this.cardTitle);
+    }
+
+    if (props.has('titleHeadingLevel')) {
+      this.__titleController.setLevel(this.titleHeadingLevel);
+    }
+  }
+
   /** @private */
   _onSlotChange() {
     this.toggleAttribute('_m', this.querySelector(':scope > [slot="media"]'));
@@ -158,9 +173,6 @@ class Card extends ElementMixin(ThemableMixin(PolylitMixin(LumoInjectionMixin(Li
     this.toggleAttribute('_hs', this.querySelector(':scope > [slot="header-suffix"]'));
     this.toggleAttribute('_c', this.__hasContent());
     this.toggleAttribute('_f', this.querySelector(':scope > [slot="footer"]'));
-    if (this.__getCustomTitleElement()) {
-      this.__clearStringTitle();
-    }
   }
 
   /** @private */
@@ -169,76 +181,6 @@ class Card extends ElementMixin(ThemableMixin(PolylitMixin(LumoInjectionMixin(Li
     return slot.assignedNodes({ flatten: true }).filter((node) => !isEmptyTextNode(node)).length > 0;
   }
 
-  /** @private */
-  __clearStringTitle() {
-    const stringTitleElement = this.__getStringTitleElement();
-    if (stringTitleElement) {
-      this.removeChild(stringTitleElement);
-    }
-    const ariaLabelledby = this.getAttribute('aria-labelledby');
-    if (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]');
-  }
-
   /**
    * @protected
    * @override

package/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/card",
-  "version": "25.3.0-alpha2",
+  "version": "25.3.0-alpha3",
   "description-markup": "markdown",
   "contributions": {
     "html": {

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/card",
-  "version": "25.3.0-alpha2",
+  "version": "25.3.0-alpha3",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {