@vaadin/vaadin-themable-mixin 24.8.0-alpha9 → 25.0.0-alpha1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/vaadin-themable-mixin",
-  "version": "24.8.0-alpha9",
+  "version": "25.0.0-alpha1",
   "publishConfig": {
     "access": "public"
   },
@@ -20,6 +20,7 @@
   "module": "vaadin-themable-mixin.js",
   "type": "module",
   "files": [
+    "src",
     "*.d.ts",
     "register-styles.js",
     "vaadin-*.js"
@@ -27,19 +28,19 @@
   "keywords": [
     "Vaadin",
     "web-components",
-    "web-component",
-    "polymer"
+    "web-component"
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "lit": "^3.0.0"
+    "lit": "^3.0.0",
+    "style-observer": "^0.0.8"
   },
   "devDependencies": {
     "@polymer/polymer": "^3.0.0",
-    "@vaadin/chai-plugins": "24.8.0-alpha9",
-    "@vaadin/test-runner-commands": "24.8.0-alpha9",
+    "@vaadin/chai-plugins": "25.0.0-alpha1",
+    "@vaadin/test-runner-commands": "25.0.0-alpha1",
     "@vaadin/testing-helpers": "^1.1.0",
     "sinon": "^18.0.0"
   },
-  "gitHead": "4de3809275ddfd733b0d13fd02af8faf73eb6770"
+  "gitHead": "b8c22a4a0c64156210d0daac96b43ae4e5526d49"
 }

package/src/css-injector.js

@@ -0,0 +1,154 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/* eslint-disable es/no-optional-chaining */
+import StyleObserver from 'style-observer';
+import { extractTagScopedCSSRules } from './css-rules.js';
+import { cleanupStyleSheet, injectStyleSheet } from './css-utils.js';
+
+/**
+ * Implements auto-injection of component-scoped CSS styles from document
+ * style sheets into the Shadow DOM of the corresponding Vaadin components.
+ *
+ * Styles are scoped to a component using the following syntax:
+ *
+ * 1. `@media vaadin-text-field { ... }` - a media query with a tag name
+ * 2. `@import "styles.css" vaadin-text-field` - an import rule with a tag name
+ *
+ * The class observes the custom property `--{tagName}-css-inject`,
+ * which indicates the presence of styles for the given component in
+ * the document style sheets. When the property is set to `1`, the class
+ * recursively searches all document style sheets for any CSS rules that
+ * are scoped to the given component tag name using the syntax described
+ * above. The found rules are then injected into the shadow DOM of all
+ * subscribed components through the adoptedStyleSheets API.
+ *
+ * The class also observes the custom property to remove the styles when
+ * the property is set to `0`.
+ *
+ * If a root element is provided, the class will additionally search for
+ * component-scoped styles in the root element's style sheets. This is
+ * useful for embedded Flow applications that are fully isolated from
+ * the main document and load styles into a component's shadow DOM
+ * rather than the main document.
+ *
+ * WARNING: For internal use only. Do not use this class in custom components.
+ */
+export class CSSInjector {
+  /** @type {Document | ShadowRoot} */
+  #root;
+
+  /** @type {Map<string, HTMLElement[]>} */
+  #componentsByTag = new Map();
+
+  /** @type {Map<string, CSSStyleSheet>} */
+  #styleSheetsByTag = new Map();
+
+  #styleObserver = new StyleObserver((records) => {
+    records.forEach((record) => {
+      const { property, value, oldValue } = record;
+      const tagName = property.slice(2).replace('-css-inject', '');
+      if (value === '1') {
+        this.#componentStylesAdded(tagName);
+      } else if (oldValue === '1') {
+        this.#componentStylesRemoved(tagName);
+      }
+    });
+  });
+
+  constructor(root = document) {
+    this.#root = root;
+  }
+
+  /**
+   * Adds a component to the list of elements monitored for component-scoped
+   * styles in global style sheets. If the styles have already been detected,
+   * they are injected into the component's shadow DOM immediately. Otherwise,
+   * the class watches the custom property `--{tagName}-css-inject` to trigger
+   * injection when the styles are added to the document or root element.
+   *
+   * @param {HTMLElement} component
+   */
+  componentConnected(component) {
+    const { is: tagName, cssInjectPropName } = component.constructor;
+
+    if (this.#componentsByTag.has(tagName)) {
+      this.#componentsByTag.get(tagName).add(component);
+    } else {
+      this.#componentsByTag.set(tagName, new Set([component]));
+    }
+
+    const stylesheet = this.#styleSheetsByTag.get(tagName);
+    if (stylesheet) {
+      injectStyleSheet(component, stylesheet);
+      return;
+    }
+
+    // If styles for custom property are already loaded for this root,
+    // store corresponding tag name so that we can inject styles
+    const value = getComputedStyle(this.#rootHost).getPropertyValue(cssInjectPropName);
+    if (value === '1') {
+      this.#componentStylesAdded(tagName);
+    }
+
+    // Observe custom property that would trigger injection for this class
+    this.#styleObserver.observe(this.#rootHost, cssInjectPropName);
+  }
+
+  /**
+   * Removes the component from the list of elements monitored for
+   * component-scoped styles and cleans up any previously injected
+   * styles from the component's shadow DOM.
+   *
+   * @param {HTMLElement} component
+   */
+  componentDisconnected(component) {
+    const { is: tagName } = component.constructor;
+
+    cleanupStyleSheet(component);
+
+    this.#componentsByTag.get(tagName)?.delete(component);
+  }
+
+  #componentStylesAdded(tagName) {
+    const stylesheet = this.#styleSheetsByTag.get(tagName) || new CSSStyleSheet();
+
+    const cssText = this.#extractComponentScopedCSSRules(tagName)
+      .map((rule) => rule.cssText)
+      .join('\n');
+    stylesheet.replaceSync(cssText);
+
+    this.#componentsByTag.get(tagName)?.forEach((component) => {
+      injectStyleSheet(component, stylesheet);
+    });
+
+    this.#styleSheetsByTag.set(tagName, stylesheet);
+  }
+
+  #componentStylesRemoved(tagName) {
+    this.#componentsByTag.get(tagName)?.forEach((component) => {
+      cleanupStyleSheet(component);
+    });
+
+    this.#styleSheetsByTag.delete(tagName);
+  }
+
+  #extractComponentScopedCSSRules(tagName) {
+    // Global stylesheets
+    const rules = extractTagScopedCSSRules(document, tagName);
+
+    // Scoped stylesheets
+    if (this.#root !== document) {
+      rules.push(...extractTagScopedCSSRules(this.#root, tagName));
+    }
+
+    return rules;
+  }
+
+  get #rootHost() {
+    return this.#root === document ? this.#root.documentElement : this.#root.host;
+  }
+}

package/src/css-rules.js

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+// Based on https://github.com/jouni/j-elements/blob/main/test/old-components/Stylable.js
+
+/**
+ * Check if the media query is a non-standard "tag scoped selector".
+ *
+ * Examples of such media queries:
+ * - `@media vaadin-text-field { ... }`
+ * - `@import "styles.css" vaadin-text-field`.
+ *
+ * @param {string} media
+ * @return {boolean}
+ */
+function isTagScopedMedia(media) {
+  return /^\w+(-\w+)+$/u.test(media);
+}
+
+/**
+ * Check if the media query string matches the given tag name.
+ *
+ * @param {string} media
+ * @param {string} tagName
+ * @return {boolean}
+ */
+function matchesTagScopedMedia(media, tagName) {
+  return media === tagName;
+}
+
+/**
+ * Recursively processes a style sheet for matching "tag scoped" rules.
+ *
+ * @param {CSSStyleSheet} styleSheet
+ * @param {string} tagName
+ */
+function extractStyleSheetTagScopedCSSRules(styleSheet, tagName) {
+  const matchingRules = [];
+
+  for (const rule of styleSheet.cssRules) {
+    const ruleType = rule.constructor.name;
+
+    if (ruleType === 'CSSImportRule') {
+      if (!isTagScopedMedia(rule.media.mediaText)) {
+        matchingRules.push(...extractStyleSheetTagScopedCSSRules(rule.styleSheet, tagName));
+        continue;
+      }
+
+      if (matchesTagScopedMedia(rule.media.mediaText, tagName)) {
+        matchingRules.push(...rule.styleSheet.cssRules);
+      }
+    }
+
+    if (ruleType === 'CSSMediaRule') {
+      if (matchesTagScopedMedia(rule.media.mediaText, tagName)) {
+        matchingRules.push(...rule.cssRules);
+      }
+    }
+  }
+
+  return matchingRules;
+}
+
+/**
+ * Recursively processes style sheets of the specified root element, including both
+ * `adoptedStyleSheets` and regular `styleSheets`, and returns all CSS rules from
+ * `@media` and `@import` blocks where the media query is (a) "tag scoped selector",
+ * and (b) matches the specified tag name.
+ *
+ * Examples of such media queries:
+ * - `@media vaadin-text-field { ... }`
+ * - `@import "styles.css" vaadin-text-field`
+ *
+ * The returned rules are ordered in the same way as they are in the original stylesheet.
+ *
+ * @param {DocumentOrShadowRoot} root
+ * @param {string} tagName
+ * @return {CSSRule[]}
+ */
+export function extractTagScopedCSSRules(root, tagName) {
+  const styleSheets = new Set([...root.styleSheets]);
+  const adoptedStyleSheets = new Set([...root.adoptedStyleSheets]);
+
+  return [...styleSheets.union(adoptedStyleSheets)].flatMap((styleSheet) => {
+    return extractStyleSheetTagScopedCSSRules(styleSheet, tagName);
+  });
+}

package/src/css-utils.js

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { adoptStyles } from 'lit';
+
+/**
+ * Returns the effective styles that should apply to the component
+ * in the correct order, to place injected stylesheet after styles
+ * defined with `static styles` and before any custom theme styles
+ * that the user provided using `registerStyles()` function.
+ *
+ * @param {HTMLElement} component
+ * @return {CSSStyleSheet[]}
+ */
+function getEffectiveStyles(component) {
+  const componentClass = component.constructor;
+
+  const styleSheet = component.__cssInjectorStyleSheet;
+  if (styleSheet) {
+    return [...componentClass.baseStyles, styleSheet, ...componentClass.themeStyles];
+  }
+
+  return componentClass.elementStyles;
+}
+
+/**
+ * Apply styles on the instance of the component in the correct order.
+ *
+ * @param {HTMLElement} component
+ */
+export function applyInstanceStyles(component) {
+  // The adoptStyles function may fall back to appending style elements to shadow root.
+  // Remove them first to avoid duplicates.
+  [...component.shadowRoot.querySelectorAll('style')].forEach((style) => style.remove());
+
+  adoptStyles(component.shadowRoot, getEffectiveStyles(component));
+}
+
+/**
+ * Injects the given stylesheet into the shadow root of the component
+ * through the adoptedStyleSheets API. This will override any styles
+ * that were injected previously since we only expect one stylesheet
+ * to be injected into each component.
+ *
+ * @param {HTMLElement} component
+ * @param {CSSStyleSheet} styleSheet
+ */
+export function injectStyleSheet(component, styleSheet) {
+  // Store the new stylesheet so that it can be removed later.
+  component.__cssInjectorStyleSheet = styleSheet;
+  applyInstanceStyles(component);
+}
+
+/**
+ * Removes the stylesheet from the component's shadow root that was added
+ * by the `injectStyleSheet` function.
+ *
+ * @param {HTMLElement} component
+ */
+export function cleanupStyleSheet(component) {
+  const adoptedStyleSheets = component.shadowRoot.adoptedStyleSheets.filter(
+    (s) => s !== component.__cssInjectorStyleSheet,
+  );
+
+  component.shadowRoot.adoptedStyleSheets = adoptedStyleSheets;
+  component.__cssInjectorStyleSheet = undefined;
+}

package/vaadin-themable-mixin.js

@@ -3,7 +3,8 @@
  * Copyright (c) 2017 - 2025 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { adoptStyles, css, CSSResult, LitElement, unsafeCSS } from 'lit';
+import { css, CSSResult, LitElement, unsafeCSS } from 'lit';
+import { applyInstanceStyles } from './src/css-utils.js';
 import { ThemePropertyMixin } from './vaadin-theme-property-mixin.js';
 
 export { css, unsafeCSS };
@@ -115,13 +116,7 @@ function updateInstanceStyles(instance) {
 
   if (instance instanceof LitElement) {
     // LitElement
-
-    // The adoptStyles function may fall back to appending style elements to shadow root.
-    // Remove them first to avoid duplicates.
-    [...instance.shadowRoot.querySelectorAll('style')].forEach((style) => style.remove());
-
-    // Adopt the updated styles
-    adoptStyles(instance.shadowRoot, componentClass.elementStyles);
+    applyInstanceStyles(instance);
   } else {
     // PolymerElement
 
@@ -203,16 +198,12 @@ function hasMatchingStyle(componentClass, styles) {
 export function registerStyles(themeFor, styles, options = {}) {
   styles = flattenStyles(styles);
 
-  if (window.Vaadin && window.Vaadin.styleModules) {
-    window.Vaadin.styleModules.registerStyles(themeFor, styles, options);
-  } else {
-    themeRegistry.push({
-      themeFor,
-      styles,
-      include: options.include,
-      moduleId: options.moduleId,
-    });
-  }
+  themeRegistry.push({
+    themeFor,
+    styles,
+    include: options.include,
+    moduleId: options.moduleId,
+  });
 
   if (themeFor) {
     // Update styles of the component types that match themeFor and have already been finalized
@@ -362,11 +353,16 @@ export const ThemableMixin = (superClass) =>
      * @protected
      */
     static finalizeStyles(styles) {
-      // The "styles" object originates from the "static get styles()" function of
-      // a LitElement based component. The theme styles are added after it
-      // so that they can override the component styles.
-      const themeStyles = this.getStylesForThis();
-      return styles ? [...[styles].flat(Infinity), ...themeStyles] : themeStyles;
+      // Preserve the styles the user supplied via the `static get styles()` getter
+      // so that they will always be injected before styles added by `CSSInjector`.
+      this.baseStyles = styles ? [styles].flat(Infinity) : [];
+
+      // Preserve the theme styles the user supplied via the `registerStyles()` API
+      // so that they will always be injected after styles added by `CSSInjector`.
+      this.themeStyles = this.getStylesForThis();
+
+      // Merged styles are stored in `elementStyles` and passed to `adoptStyles()`.
+      return [...this.baseStyles, ...this.themeStyles];
     }
 
     /**