vaadin · web-padawan · Apr 7, 2025 · Apr 8, 2025 · Apr 8, 2025 · Apr 8, 2025
diff --git a/packages/vaadin-themable-mixin/css-injection-mixin.js b/packages/vaadin-themable-mixin/css-injection-mixin.js
@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2025 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { CSSInjector } from './src/css-injector.js';
+
+/**
+ * @type {string[]}
+ */
+const registeredProperties = new Set();
+
+/**
+ * Find enclosing root for given element to gather style rules from.
+ *
+ * @param {HTMLElement} element
+ * @return {DocumentOrShadowRoot}
+ */
+function findRoot(element) {
+  const root = element.getRootNode();
+
+  if (root.host && root.host.constructor.cssInjectPropName) {
+    return findRoot(root.host);
+  }
+
+  return root;
+}
+
+/**
+ * Mixin for internal use only. Do not use it in custom components.
+ *
+ * @polymerMixin
+ */
+export const CSSInjectionMixin = (superClass) =>
+  class CSSInjectionMixinClass extends superClass {
+    static finalize() {
+      super.finalize();
+
+      const propName = this.cssInjectPropName;
+
+      // Prevent registering same property twice when a class extends
+      // another class using this mixin, since `finalize()` is called
+      // by LitElement for all superclasses in the prototype chain.
+      if (this.is && !registeredProperties.has(propName)) {
+        registeredProperties.add(propName);
+
+        // Initialize custom property for this class with 0 as default
+        // so that changing it to 1 would inject styles to instances
+        // Use `inherits: true` so that property defined on `<html>`
+        // would apply to components instances within shadow roots
+        CSS.registerProperty({
+          name: propName,
+          syntax: '<number>',
+          inherits: true,
+          initialValue: '0',
+        });
+      }
+    }
+
+    static get cssInjectPropName() {
+      return `--${this.is}-css-inject`;
+    }
+
+    /** @protected */
+    connectedCallback() {
+      super.connectedCallback();
+
+      const root = findRoot(this);
+      root.__cssInjector ||= new CSSInjector(root);
+      this.__cssInjector = root.__cssInjector;
+      this.__cssInjector.componentConnected(this);
+    }
+
+    /** @protected */
+    disconnectedCallback() {
+      super.disconnectedCallback();
+
+      this.__cssInjector.componentDisconnected(this);
+      this.__cssInjector = undefined;
+    }
+  };
diff --git a/packages/vaadin-themable-mixin/package.json b/packages/vaadin-themable-mixin/package.json
@@ -32,7 +32,8 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "lit": "^3.0.0"
+    "lit": "^3.0.0",
+    "style-observer": "^0.0.7"
   },
   "devDependencies": {
     "@polymer/polymer": "^3.0.0",

diff --git a/packages/vaadin-themable-mixin/src/css-injector.js b/packages/vaadin-themable-mixin/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;
+  }
+}
diff --git a/packages/vaadin-themable-mixin/src/css-rules.js b/packages/vaadin-themable-mixin/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);
+  });
+}