feat: add mixin for detecting Vaadin theme (#10390)

* feat: add mixin for detecting Vaadin theme

* use data-application-theme as attribute

* use private members

* improve annotations

* update attribute name in JSDoc

Author: sissbruecker

packages/aura/aura.css

@@ -39,4 +39,5 @@
   cursor: default;
   /* TODO: slightly smaller chevron than the one in base styles - consider if we should do this in base styles */
   --_vaadin-icon-chevron-down: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"/></svg>');
+  --vaadin-aura-theme: 1;
 }

packages/vaadin-lumo-styles/lumo.css

@@ -6,3 +6,8 @@
 @import './src/props/index.css';
 @import './src/global/index.css';
 @import './components/index.css';
+
+:where(:root),
+:where(:host) {
+  --vaadin-lumo-theme: 1;
+}

packages/vaadin-themable-mixin/lumo-injection-mixin.js

@@ -16,7 +16,7 @@ const registeredProperties = new Set();
  * @param {HTMLElement} element
  * @return {DocumentOrShadowRoot}
  */
-function findRoot(element) {
+export function findRoot(element) {
   const root = element.getRootNode();
 
   if (root.host && root.host.constructor.version) {

packages/vaadin-themable-mixin/src/theme-detector.js

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * Copyright (c) 2000 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { CSSPropertyObserver } from './css-property-observer.js';
+
+// Register CSS custom properties for observing theme changes
+CSS.registerProperty({
+  name: '--vaadin-aura-theme',
+  syntax: '<number>',
+  inherits: true,
+  initialValue: '0',
+});
+
+CSS.registerProperty({
+  name: '--vaadin-lumo-theme',
+  syntax: '<number>',
+  inherits: true,
+  initialValue: '0',
+});
+
+/**
+ * Observes a root (Document or ShadowRoot) for which Vaadin theme is currently applied.
+ * Notifies about theme changes by firing a `theme-changed` event.
+ *
+ * WARNING: For internal use only. Do not use this class in custom components.
+ *
+ * @private
+ */
+export class ThemeDetector extends EventTarget {
+  /** @type {DocumentOrShadowRoot} */
+  #root;
+  /** @type {CSSPropertyObserver} */
+  #observer;
+  /** @type {{ aura: boolean; lumo: boolean }} */
+  #themes = { aura: false, lumo: false };
+  /** @type {(event: CustomEvent) => void} */
+  #boundHandleThemeChange = this.#handleThemeChange.bind(this);
+
+  constructor(root) {
+    super();
+    this.#root = root;
+    this.#detectTheme();
+
+    this.#observer = CSSPropertyObserver.for(this.#root);
+    this.#observer.observe('--vaadin-aura-theme');
+    this.#observer.observe('--vaadin-lumo-theme');
+    this.#observer.addEventListener('property-changed', this.#boundHandleThemeChange);
+  }
+
+  get themes() {
+    return { ...this.#themes };
+  }
+
+  #handleThemeChange(event) {
+    const { propertyName } = event.detail;
+    if (!['--vaadin-aura-theme', '--vaadin-lumo-theme'].includes(propertyName)) {
+      return;
+    }
+
+    this.#detectTheme();
+    this.dispatchEvent(new CustomEvent('theme-changed'));
+  }
+
+  #detectTheme() {
+    const rootElement = this.#root.documentElement ?? this.#root.host;
+    const style = getComputedStyle(rootElement);
+    this.#themes = {
+      aura: style.getPropertyValue('--vaadin-aura-theme').trim() === '1',
+      lumo: style.getPropertyValue('--vaadin-lumo-theme').trim() === '1',
+    };
+  }
+
+  disconnect() {
+    this.#observer.removeEventListener('property-changed', this.#boundHandleThemeChange);
+  }
+}

packages/vaadin-themable-mixin/test/theme-detection-mixin.test.js

@@ -0,0 +1,124 @@
+import { expect } from '@vaadin/chai-plugins';
+import { fixtureSync, nextRender, oneEvent } from '@vaadin/testing-helpers';
+import { LitElement } from 'lit';
+import { ThemeDetectionMixin } from '../vaadin-theme-detection-mixin.js';
+
+class TestElement extends ThemeDetectionMixin(LitElement) {
+  static get is() {
+    return 'test-element';
+  }
+
+  static get version() {
+    return '1.0.0';
+  }
+}
+
+customElements.define(TestElement.is, TestElement);
+
+class CustomStyleRoot extends LitElement {}
+
+customElements.define('custom-style-root', CustomStyleRoot);
+
+describe('theme-detection-mixin', () => {
+  let styleRoot, hostElement, contentElement, stylesheet, testElement;
+
+  function applyTheme(themeProperty = null) {
+    if (styleRoot.adoptedStyleSheets.includes(stylesheet)) {
+      styleRoot.adoptedStyleSheets = styleRoot.adoptedStyleSheets.filter((s) => s !== stylesheet);
+    }
+
+    if (themeProperty) {
+      stylesheet = new CSSStyleSheet();
+      stylesheet.replaceSync(`:host, :root { ${themeProperty}: 1; }`);
+      styleRoot.adoptedStyleSheets = [...styleRoot.adoptedStyleSheets, stylesheet];
+    }
+  }
+
+  beforeEach(() => {
+    testElement = document.createElement('test-element');
+  });
+
+  afterEach(() => {
+    testElement.remove();
+    styleRoot.__themeDetector?.disconnect();
+    styleRoot.__themeDetector = undefined;
+    styleRoot.__cssPropertyObserver?.disconnect();
+    styleRoot.__cssPropertyObserver = undefined;
+    applyTheme();
+  });
+
+  function runThemeDetectionTests() {
+    it('should define ThemeDetector on the style root', () => {
+      contentElement.append(testElement);
+
+      expect(styleRoot.__themeDetector).to.be.ok;
+    });
+
+    describe('initial theme', () => {
+      it('should detect no theme', () => {
+        contentElement.append(testElement);
+
+        expect(testElement.hasAttribute('data-application-theme')).to.be.false;
+      });
+
+      it('should detect Aura theme', () => {
+        applyTheme('--vaadin-aura-theme');
+
+        contentElement.append(testElement);
+
+        expect(testElement.getAttribute('data-application-theme')).to.equal('aura');
+      });
+
+      it('should detect Lumo theme', () => {
+        applyTheme('--vaadin-lumo-theme');
+
+        contentElement.append(testElement);
+
+        expect(testElement.getAttribute('data-application-theme')).to.equal('lumo');
+      });
+    });
+
+    describe('theme changes', () => {
+      beforeEach(async () => {
+        contentElement.append(testElement);
+        await nextRender();
+      });
+
+      it('should detect theme changes', async () => {
+        expect(testElement.hasAttribute('data-application-theme')).to.be.false;
+
+        applyTheme('--vaadin-aura-theme');
+        await oneEvent(hostElement, 'transitionend');
+        expect(testElement.getAttribute('data-application-theme')).to.equal('aura');
+
+        applyTheme('--vaadin-lumo-theme');
+        await oneEvent(hostElement, 'transitionend');
+        expect(testElement.getAttribute('data-application-theme')).to.equal('lumo');
+
+        applyTheme();
+        await oneEvent(hostElement, 'transitionend');
+        expect(testElement.hasAttribute('data-application-theme')).to.be.false;
+      });
+    });
+  }
+
+  describe('in global scope', () => {
+    beforeEach(() => {
+      hostElement = document;
+      styleRoot = document;
+      contentElement = document.body;
+    });
+
+    runThemeDetectionTests();
+  });
+
+  describe('in shadow root', () => {
+    beforeEach(() => {
+      hostElement = fixtureSync(`<custom-style-root></custom-style-root>`);
+      styleRoot = hostElement.shadowRoot;
+      contentElement = hostElement.shadowRoot;
+    });
+
+    runThemeDetectionTests();
+  });
+});

packages/vaadin-themable-mixin/vaadin-theme-detection-mixin.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+
+export declare function ThemeDetectionMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<ThemeDetectionMixinClass> & T;
+
+export declare class ThemeDetectionMixinClass {}

packages/vaadin-themable-mixin/vaadin-theme-detection-mixin.js

@@ -0,0 +1,58 @@
+import { findRoot } from './lumo-injection-mixin.js';
+import { ThemeDetector } from './src/theme-detector.js';
+
+/**
+ * Mixin for detecting which Vaadin theme is applied to the application.
+ * Automatically adds a `data-application-theme` attribute to the host
+ * element with the name of the detected theme (`lumo` or `aura`), which
+ * can be used in component styles to apply theme-specific styling.
+ *
+ * @polymerMixin
+ */
+export const ThemeDetectionMixin = (superClass) =>
+  class ThemeDetectionMixinClass extends superClass {
+    constructor() {
+      super();
+
+      this.__applyDetectedTheme = this.__applyDetectedTheme.bind(this);
+    }
+
+    /** @protected */
+    connectedCallback() {
+      super.connectedCallback();
+
+      if (this.isConnected) {
+        const root = findRoot(this);
+        root.__themeDetector = root.__themeDetector || new ThemeDetector(root);
+        this.__themeDetector = root.__themeDetector;
+        this.__themeDetector.addEventListener('theme-changed', this.__applyDetectedTheme);
+        this.__applyDetectedTheme();
+      }
+    }
+
+    /** @protected */
+    disconnectedCallback() {
+      super.disconnectedCallback();
+
+      if (this.__themeDetector) {
+        this.__themeDetector.removeEventListener('theme-changed', this.__applyDetectedTheme);
+        this.__themeDetector = null;
+      }
+    }
+
+    /** @private */
+    __applyDetectedTheme() {
+      if (!this.__themeDetector) {
+        return;
+      }
+
+      const themes = this.__themeDetector.themes;
+      if (themes.aura) {
+        this.dataset.applicationTheme = 'aura';
+      } else if (themes.lumo) {
+        this.dataset.applicationTheme = 'lumo';
+      } else {
+        delete this.dataset.applicationTheme;
+      }
+    }
+  };