@vaadin/component-base 25.3.0-alpha1 → 25.3.0-alpha11

package/custom-elements.json

@@ -50,7 +50,8 @@
             {
               "name": "superClass"
             }
-          ]
+          ],
+          "deprecated": "This mixin is deprecated and will be removed in Vaadin 26,\nafter which components will no longer set the `dir` attribute on themselves.\nUse the `:dir(rtl)` CSS selector to style components in right-to-left mode,\nand `element.matches(':dir(rtl)')` to detect it in JavaScript."
         }
       ],
       "exports": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/component-base",
-  "version": "25.3.0-alpha1",
+  "version": "25.3.0-alpha11",
   "publishConfig": {
     "access": "public"
   },
@@ -38,11 +38,12 @@
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/chai-plugins": "25.3.0-alpha1",
-    "@vaadin/test-runner-commands": "25.3.0-alpha1",
+    "@polymer/polymer": "^3.0.0",
+    "@vaadin/chai-plugins": "25.3.0-alpha11",
+    "@vaadin/test-runner-commands": "25.3.0-alpha11",
     "@vaadin/testing-helpers": "^2.0.0",
     "sinon": "^22.0.0"
   },
   "customElements": "custom-elements.json",
-  "gitHead": "5824d54c995945aafd50d30edc2cb763a58a18b6"
+  "gitHead": "7e0c61a37e68d8971def9cdf28ad0548a0f530a9"
 }

package/src/css-utils.js

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright (c) 2025 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * Registers a CSS custom property, tolerating the case where the property has
+ * already been registered. This can happen when a module is evaluated more than
+ * once (e.g. duplicate bundle chunks or two copies of the library on the page),
+ * in which case `CSS.registerProperty` throws `InvalidModificationError`. That
+ * error is caught and logged as a warning rather than allowed to break loading.
+ *
+ * @param {PropertyDefinition} definition
+ */
+export function registerCSSProperty(definition) {
+  try {
+    CSS.registerProperty(definition);
+  } catch (e) {
+    if (e instanceof DOMException && e.name === 'InvalidModificationError') {
+      console.warn(`The CSS property ${definition.name} has already been registered.`);
+    } else {
+      throw e;
+    }
+  }
+}
+
+/**
+ * Add a `<style>` block with given styles to the document.
+ *
+ * @param {string} id the id to set on the created element, only for informational purposes
+ * @param  {CSSResultGroup[]} styles the styles to add
+ */
+export const addGlobalStyles = (id, ...styles) => {
+  const styleTag = document.createElement('style');
+  styleTag.id = id;
+  styleTag.textContent = styles.map((style) => style.toString()).join('\n');
+
+  document.head.insertAdjacentElement('afterbegin', styleTag);
+};

package/src/data-provider-controller/cache.js

@@ -15,13 +15,6 @@ export class Cache {
    */
   context;
 
-  /**
-   * The number of items to display per page.
-   *
-   * @type {number}
-   */
-  pageSize;
-
   /**
    * An array of cached items.
    *
@@ -50,6 +43,14 @@ export class Cache {
    */
   #subCacheByIndex = {};
 
+  /**
+   * The number of items per page.
+   *
+   * @type {number}
+   * @private
+   */
+  #pageSize;
+
   /**
    * The number of items.
    *
@@ -123,6 +124,29 @@ export class Cache {
     return this.#flatSize;
   }
 
+  /**
+   * The number of items per page.
+   *
+   * @return {number}
+   */
+  get pageSize() {
+    return this.#pageSize;
+  }
+
+  /**
+   * Sets the number of items per page for this cache and its descendants.
+   * Changing the page size discards all pending page requests.
+   *
+   * @param {number} pageSize
+   */
+  set pageSize(pageSize) {
+    this.#pageSize = pageSize;
+    this.pendingRequests = {};
+    this.subCaches.forEach((subCache) => {
+      subCache.pageSize = pageSize;
+    });
+  }
+
   /**
    * The number of items.
    *

package/src/data-provider-controller/data-provider-controller.js

@@ -29,13 +29,6 @@ export class DataProviderController extends EventTarget {
    */
   dataProviderParams;
 
-  /**
-   * A number of items to display per page.
-   *
-   * @type {number}
-   */
-  pageSize;
-
   /**
    * A callback that returns whether the given item is expanded.
    *
@@ -78,14 +71,13 @@ export class DataProviderController extends EventTarget {
   ) {
     super();
     this.host = host;
-    this.pageSize = pageSize;
     this.getItemId = getItemId;
     this.isExpanded = isExpanded;
     this.placeholder = placeholder;
     this.isPlaceholder = isPlaceholder;
     this.dataProvider = dataProvider;
     this.dataProviderParams = dataProviderParams;
-    this.rootCache = this.#createRootCache(size);
+    this.rootCache = this.#createRootCache(pageSize, size);
   }
 
   /**
@@ -95,6 +87,13 @@ export class DataProviderController extends EventTarget {
     return this.rootCache.flatSize;
   }
 
+  /**
+   * The number of items per page in the root cache.
+   */
+  get pageSize() {
+    return this.rootCache.pageSize;
+  }
+
   /** @private */
   get #cacheContext() {
     return {
@@ -113,13 +112,12 @@ export class DataProviderController extends EventTarget {
   }
 
   /**
-   * Sets the page size and clears the cache.
+   * Sets the number of items per page in the root cache and any of its descendants.
    *
    * @param {number} pageSize
    */
   setPageSize(pageSize) {
-    this.pageSize = pageSize;
-    this.clearCache();
+    this.rootCache.pageSize = pageSize;
   }
 
   /**
@@ -129,7 +127,6 @@ export class DataProviderController extends EventTarget {
    */
   setDataProvider(dataProvider) {
     this.dataProvider = dataProvider;
-    this.clearCache();
   }
 
   /**
@@ -143,7 +140,7 @@ export class DataProviderController extends EventTarget {
    * Clears the cache.
    */
   clearCache() {
-    this.rootCache = this.#createRootCache(this.rootCache.size);
+    this.rootCache = this.#createRootCache(this.rootCache.pageSize, this.rootCache.size);
   }
 
   /**
@@ -238,8 +235,8 @@ export class DataProviderController extends EventTarget {
   }
 
   /** @private */
-  #createRootCache(size) {
-    return new Cache(this.#cacheContext, this.pageSize, size);
+  #createRootCache(pageSize, size) {
+    return new Cache(this.#cacheContext, pageSize, size);
   }
 
   /** @private */
@@ -250,7 +247,7 @@ export class DataProviderController extends EventTarget {
 
     let params = {
       page,
-      pageSize: this.pageSize,
+      pageSize: cache.pageSize,
       parentItem: cache.parentItem,
     };
 

package/src/define.js

@@ -13,7 +13,7 @@ function dashToCamelCase(dash) {
 
 const experimentalMap = {};
 
-export function defineCustomElement(CustomElement, version = '25.3.0-alpha1') {
+export function defineCustomElement(CustomElement, version = '25.3.0-alpha11') {
   Object.defineProperty(CustomElement, 'version', {
     get() {
       return version;

package/src/delegate-state-mixin.js

@@ -4,6 +4,7 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { dedupeMixin } from '@open-wc/dedupe-mixin';
+import { setOrRemoveAttribute } from './dom-utils.js';
 
 /**
  * A mixin to delegate properties and attributes to a target element.
@@ -103,10 +104,8 @@ const DelegateStateMixinImplementation = (superclass) => {
 
       if (typeof value === 'boolean') {
         this.stateTarget.toggleAttribute(name, value);
-      } else if (value) {
-        this.stateTarget.setAttribute(name, value);
       } else {
-        this.stateTarget.removeAttribute(name);
+        setOrRemoveAttribute(this.stateTarget, name, value);
       }
     }
 

package/src/dir-mixin.d.ts

@@ -7,9 +7,23 @@ import type { Constructor } from '@open-wc/dedupe-mixin';
 
 /**
  * A mixin to handle `dir` attribute based on the one set on the `<html>` element.
+ *
+ * @deprecated This mixin is deprecated and will be removed in Vaadin 26,
+ * after which components will no longer set the `dir` attribute on themselves.
+ * Use the `:dir(rtl)` CSS selector to style components in right-to-left mode,
+ * and `element.matches(':dir(rtl)')` to detect it in JavaScript.
  */
 export declare function DirMixin<T extends Constructor<HTMLElement>>(base: T): Constructor<DirMixinClass> & T;
 
+/**
+ * @deprecated This mixin is deprecated and will be removed in Vaadin 26,
+ * after which components will no longer set the `dir` attribute on themselves.
+ * Use the `:dir(rtl)` CSS selector to style components in right-to-left mode,
+ * and `element.matches(':dir(rtl)')` to detect it in JavaScript.
+ */
 export declare class DirMixinClass {
+  /**
+   * @deprecated Use `this.matches(':dir(rtl)')` instead.
+   */
   protected readonly __isRTL: boolean;
 }

package/src/dir-mixin.js

@@ -33,6 +33,11 @@ directionObserver.observe(document.documentElement, { attributes: true, attribut
 
 /**
  * A mixin to handle `dir` attribute based on the one set on the `<html>` element.
+ *
+ * @deprecated This mixin is deprecated and will be removed in Vaadin 26,
+ * after which components will no longer set the `dir` attribute on themselves.
+ * Use the `:dir(rtl)` CSS selector to style components in right-to-left mode,
+ * and `element.matches(':dir(rtl)')` to detect it in JavaScript.
  */
 export const DirMixin = (superClass) =>
   class VaadinDirMixin extends superClass {
@@ -60,6 +65,7 @@ export const DirMixin = (superClass) =>
     /**
      * @return {boolean}
      * @protected
+     * @deprecated Use `this.matches(':dir(rtl)')` instead.
      */
     get __isRTL() {
       return this.getAttribute('dir') === 'rtl';
@@ -106,6 +112,10 @@ export const DirMixin = (superClass) =>
       this.__unsubscribe();
     }
 
+    // The two overrides below are only invoked by Polymer's property reflection.
+    // Vaadin components no longer extend `PolymerElement`, but some add-ons still
+    // apply this mixin to `PolymerElement`, so the overrides are kept for them.
+
     /** @protected */
     _valueToNodeAttribute(node, value, attribute) {
       // Override default Polymer attribute reflection to match native behavior of HTMLElement.dir property

package/src/directives/part-map.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright (c) 2026 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { DirectiveResult } from 'lit/directive.js';
+
+/**
+ * A key-value set of part names to truthy values.
+ */
+export interface PartNameInfo {
+  readonly [name: string]: string | boolean | number | null | undefined;
+}
+
+/**
+ * A directive that applies dynamic shadow DOM part names.
+ *
+ * This must be used in the `part` attribute and must be the only binding in it.
+ * Each property name in `partNameInfo` is added to the element's `part` list
+ * if the property value is truthy, and removed if the value is falsy.
+ */
+export declare function partMap(partNameInfo: PartNameInfo): DirectiveResult;

package/src/directives/part-map.js

@@ -0,0 +1,86 @@
+/**
+ * @license
+ * Copyright (c) 2026 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { noChange } from 'lit';
+import { Directive, directive, PartType } from 'lit/directive.js';
+
+class PartMapDirective extends Directive {
+  // Part names applied by the directive on the previous render,
+  // used to remove names that no longer apply.
+  #previousParts;
+
+  // Part names declared statically in the attribute, never removed.
+  #staticParts;
+
+  constructor(partInfo) {
+    super(partInfo);
+    if (partInfo.type !== PartType.ATTRIBUTE || partInfo.name !== 'part' || partInfo.strings?.length > 2) {
+      throw new Error('`partMap()` can only be used in the `part` attribute and must be the only binding in it.');
+    }
+  }
+
+  render(partNameInfo) {
+    // Add spaces to ensure separation from static parts
+    return ` ${Object.keys(partNameInfo)
+      .filter((key) => partNameInfo[key])
+      .join(' ')} `;
+  }
+
+  update(part, [partNameInfo]) {
+    // Remember dynamic parts on the first render
+    if (this.#previousParts === undefined) {
+      this.#previousParts = new Set();
+      if (part.strings !== undefined) {
+        this.#staticParts = new Set(
+          part.strings
+            .join(' ')
+            .split(/\s/u)
+            .filter((s) => s !== ''),
+        );
+      }
+      Object.keys(partNameInfo).forEach((name) => {
+        if (partNameInfo[name] && !this.#staticParts?.has(name)) {
+          this.#previousParts.add(name);
+        }
+      });
+      return this.render(partNameInfo);
+    }
+
+    const partList = part.element.part;
+
+    // Remove old parts that no longer apply
+    this.#previousParts.forEach((name) => {
+      if (!(name in partNameInfo)) {
+        partList.remove(name);
+        this.#previousParts.delete(name);
+      }
+    });
+
+    // Add or remove parts based on their partMap value
+    Object.keys(partNameInfo).forEach((name) => {
+      const value = !!partNameInfo[name];
+      if (value !== this.#previousParts.has(name) && !this.#staticParts?.has(name)) {
+        if (value) {
+          partList.add(name);
+          this.#previousParts.add(name);
+        } else {
+          partList.remove(name);
+          this.#previousParts.delete(name);
+        }
+      }
+    });
+
+    return noChange;
+  }
+}
+
+/**
+ * A directive that applies dynamic shadow DOM part names.
+ *
+ * This must be used in the `part` attribute and must be the only binding in it.
+ * Each property name in `partNameInfo` is added to the element's `part` list
+ * if the property value is truthy, and removed if the value is falsy.
+ */
+export const partMap = directive(PartMapDirective);

package/src/dom-utils.d.ts

@@ -37,15 +37,26 @@ export function deserializeAttributeValue(value: string): Set<string>;
 export function serializeAttributeValue(values: Set<string>): string;
 
 /**
- * Adds a value to an attribute containing space-delimited values.
+ * Sets the attribute to the given value, or removes the attribute when the
+ * value is falsy (e.g. `null`, `undefined`, `false` or an empty string).
  */
-export function addValueToAttribute(element: HTMLElement, attr: string, value: string): void;
+export function setOrRemoveAttribute(
+  element: HTMLElement,
+  attr: string,
+  value: string | boolean | null | undefined,
+): void;
 
 /**
- * Removes a value from an attribute containing space-delimited values.
- * If the value is the last one, the whole attribute is removed.
+ * Adds one or more values to an attribute containing space-delimited values.
+ * If no values remain, the whole attribute is removed.
  */
-export function removeValueFromAttribute(element: HTMLElement, attr: string, value: string): void;
+export function addValuesToAttribute(element: HTMLElement, attr: string, valuesToAdd: string | string[]): void;
+
+/**
+ * Removes one or more values from an attribute containing space-delimited values.
+ * If no values remain, the whole attribute is removed.
+ */
+export function removeValuesFromAttribute(element: HTMLElement, attr: string, valuesToRemove: string | string[]): void;
 
 /**
  * Returns true if the given node is an empty text node, false otherwise.

package/src/dom-utils.js

@@ -84,11 +84,7 @@ export function getClosestElement(selector, node) {
  * @return {Set<string>}
  */
 export function deserializeAttributeValue(value) {
-  if (!value) {
-    return new Set();
-  }
-
-  return new Set(value.split(' '));
+  return new Set(value ? value.split(' ').filter(Boolean) : []);
 }
 
 /**
@@ -102,34 +98,65 @@ export function serializeAttributeValue(values) {
 }
 
 /**
- * Adds a value to an attribute containing space-delimited values.
+ * Sets the attribute to the given value, or removes the attribute when the
+ * value is falsy (e.g. `null`, `undefined`, `false` or an empty string).
  *
  * @param {HTMLElement} element
  * @param {string} attr
- * @param {string} value
+ * @param {string | boolean | null | undefined} value
+ */
+export function setOrRemoveAttribute(element, attr, value) {
+  if (value) {
+    element.setAttribute(attr, value);
+  } else {
+    element.removeAttribute(attr);
+  }
+}
+
+/**
+ * Normalizes values passed to `addValuesToAttribute` and `removeValuesFromAttribute`
+ * into a set of values. Both a single string and every array entry may contain
+ * multiple values separated by space.
+ *
+ * @param {string | string[] | null | undefined} values
+ * @return {Set<string>}
+ */
+function normalizeAttributeValues(values) {
+  return deserializeAttributeValue(Array.isArray(values) ? values.join(' ') : values);
+}
+
+/**
+ * Adds one or more values to an attribute containing space-delimited values.
+ * If no values remain, the whole attribute is removed.
+ *
+ * @param {HTMLElement} element
+ * @param {string} attr
+ * @param {string | string[]} valuesToAdd a string or an array of strings with values separated by space
  */
-export function addValueToAttribute(element, attr, value) {
+export function addValuesToAttribute(element, attr, valuesToAdd) {
+  valuesToAdd = normalizeAttributeValues(valuesToAdd);
+
   const values = deserializeAttributeValue(element.getAttribute(attr));
-  values.add(value);
-  element.setAttribute(attr, serializeAttributeValue(values));
+  valuesToAdd.forEach((value) => values.add(value));
+
+  setOrRemoveAttribute(element, attr, serializeAttributeValue(values));
 }
 
 /**
- * Removes a value from an attribute containing space-delimited values.
- * If the value is the last one, the whole attribute is removed.
+ * Removes one or more values from an attribute containing space-delimited values.
+ * If no values remain, the whole attribute is removed.
  *
  * @param {HTMLElement} element
  * @param {string} attr
- * @param {string} value
+ * @param {string | string[]} valuesToRemove a string or an array of strings with values separated by space
  */
-export function removeValueFromAttribute(element, attr, value) {
+export function removeValuesFromAttribute(element, attr, valuesToRemove) {
+  valuesToRemove = normalizeAttributeValues(valuesToRemove);
+
   const values = deserializeAttributeValue(element.getAttribute(attr));
-  values.delete(value);
-  if (values.size === 0) {
-    element.removeAttribute(attr);
-    return;
-  }
-  element.setAttribute(attr, serializeAttributeValue(values));
+  valuesToRemove.forEach((value) => values.delete(value));
+
+  setOrRemoveAttribute(element, attr, serializeAttributeValue(values));
 }
 
 /**

package/src/media-query-controller.js

@@ -8,6 +8,9 @@
  * A controller for listening on media query changes.
  */
 export class MediaQueryController {
+  /** @type {MediaQueryList | null} */
+  #mediaQuery = null;
+
   constructor(query, callback) {
     /**
      * The CSS media query to evaluate.
@@ -24,44 +27,39 @@ export class MediaQueryController {
      * @protected
      */
     this.callback = callback;
-
-    this._boundQueryHandler = this._queryHandler.bind(this);
   }
 
   hostConnected() {
-    this._removeListener();
+    this.#removeListener();
 
-    this._mediaQuery = window.matchMedia(this.query);
+    this.#mediaQuery = window.matchMedia(this.query);
 
-    this._addListener();
+    this.#addListener();
 
-    this._queryHandler(this._mediaQuery);
+    this.#queryHandler(this.#mediaQuery);
   }
 
   hostDisconnected() {
-    this._removeListener();
+    this.#removeListener();
   }
 
-  /** @private */
-  _addListener() {
-    if (this._mediaQuery) {
-      this._mediaQuery.addListener(this._boundQueryHandler);
+  #addListener() {
+    if (this.#mediaQuery) {
+      this.#mediaQuery.addListener(this.#queryHandler);
     }
   }
 
-  /** @private */
-  _removeListener() {
-    if (this._mediaQuery) {
-      this._mediaQuery.removeListener(this._boundQueryHandler);
+  #removeListener() {
+    if (this.#mediaQuery) {
+      this.#mediaQuery.removeListener(this.#queryHandler);
     }
 
-    this._mediaQuery = null;
+    this.#mediaQuery = null;
   }
 
-  /** @private */
-  _queryHandler(mediaQuery) {
+  #queryHandler = (mediaQuery) => {
     if (typeof this.callback === 'function') {
       this.callback(mediaQuery.matches);
     }
-  }
+  };
 }

package/src/overflow-controller.js

@@ -3,6 +3,7 @@
  * Copyright (c) 2021 - 2026 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
+import { setOrRemoveAttribute } from './dom-utils.js';
 
 /**
  * A controller that detects if content inside the element overflows its scrolling viewport,
@@ -10,6 +11,15 @@
  * where content is overflowing. Supported values are: `top`, `bottom`, `start`, `end`.
  */
 export class OverflowController {
+  /** @type {ResizeObserver} */
+  #resizeObserver;
+
+  /** @type {MutationObserver} */
+  #childObserver;
+
+  /** @type {number} */
+  #resizeRaf;
+
   constructor(host, scrollTarget) {
     /**
      * The controller host element.
@@ -25,9 +35,6 @@ export class OverflowController {
      * @type {HTMLElement}
      */
     this.scrollTarget = scrollTarget || host;
-
-    /** @private */
-    this.__boundOnScroll = this.__onScroll.bind(this);
   }
 
   hostConnected() {
@@ -46,64 +53,60 @@ export class OverflowController {
   observe() {
     const { host } = this;
 
-    this.__resizeObserver = new ResizeObserver(() => this.__onResize());
-    this.__resizeObserver.observe(host);
+    this.#resizeObserver = new ResizeObserver(() => this.#onResize());
+    this.#resizeObserver.observe(host);
 
     // Observe initial children
     [...host.children].forEach((child) => {
-      this.__resizeObserver.observe(child);
+      this.#resizeObserver.observe(child);
     });
 
-    this.__childObserver = new MutationObserver((mutations) => {
+    this.#childObserver = new MutationObserver((mutations) => {
       mutations.forEach(({ addedNodes, removedNodes }) => {
         addedNodes.forEach((node) => {
           if (node.nodeType === Node.ELEMENT_NODE) {
-            this.__resizeObserver.observe(node);
+            this.#resizeObserver.observe(node);
           }
         });
 
         removedNodes.forEach((node) => {
           if (node.nodeType === Node.ELEMENT_NODE) {
-            this.__resizeObserver.unobserve(node);
+            this.#resizeObserver.unobserve(node);
           }
         });
 
         if (addedNodes.length === 0 && removedNodes.length > 0) {
-          this.__updateState({ sync: true });
+          this.#updateState({ sync: true });
         }
       });
     });
 
-    this.__childObserver.observe(host, { childList: true });
+    this.#childObserver.observe(host, { childList: true });
 
     // Update overflow attribute on scroll
-    this.scrollTarget.addEventListener('scroll', this.__boundOnScroll);
+    this.scrollTarget.addEventListener('scroll', this.#onScroll);
   }
 
-  /** @private */
-  __onResize() {
-    this.__updateState({ sync: false });
+  #onResize() {
+    this.#updateState({ sync: false });
   }
 
-  /** @private */
-  __onScroll() {
-    this.__updateState({ sync: true });
-  }
+  #onScroll = () => {
+    this.#updateState({ sync: true });
+  };
 
-  /** @private */
-  __updateState({ sync }) {
-    cancelAnimationFrame(this.__resizeRaf);
+  #updateState({ sync }) {
+    cancelAnimationFrame(this.#resizeRaf);
 
-    const state = this.__readState();
+    const state = this.#readState();
     if (sync) {
-      this.__writeState(state);
+      this.#writeState(state);
     } else {
-      this.__resizeRaf = requestAnimationFrame(() => this.__writeState(state));
+      this.#resizeRaf = requestAnimationFrame(() => this.#writeState(state));
     }
   }
 
-  /** @private */
-  __readState() {
+  #readState() {
     const target = this.scrollTarget;
 
     let overflow = '';
@@ -128,12 +131,7 @@ export class OverflowController {
     return { overflow: overflow.trim() };
   }
 
-  /** @private */
-  __writeState({ overflow }) {
-    if (overflow) {
-      this.host.setAttribute('overflow', overflow);
-    } else {
-      this.host.removeAttribute('overflow');
-    }
+  #writeState({ overflow }) {
+    setOrRemoveAttribute(this.host, 'overflow', overflow);
   }
 }

package/src/slot-child-observe-controller.d.ts

@@ -25,4 +25,9 @@ export class SlotChildObserveController extends SlotController {
    * Override to update default node text on property change.
    */
   protected updateDefaultNode(node: Node): void;
+
+  /**
+   * Fire an event to notify the controller host about node changes.
+   */
+  protected _notifyChange(node: Node): void;
 }

package/src/slot-child-observe-controller.js

@@ -10,6 +10,9 @@ import { SlotController } from './slot-controller.js';
  * and the text content, and fires an event to notify host element about those.
  */
 export class SlotChildObserveController extends SlotController {
+  /** @type {MutationObserver} */
+  #nodeObserver;
+
   constructor(host, slot, tagName, config = {}) {
     super(host, slot, tagName, { ...config, useUniqueId: true });
   }
@@ -22,8 +25,8 @@ export class SlotChildObserveController extends SlotController {
    * @override
    */
   initCustomNode(node) {
-    this.__updateNodeId(node);
-    this.__notifyChange(node);
+    this.#updateNodeId(node);
+    this._notifyChange(node);
   }
 
   /**
@@ -39,7 +42,7 @@ export class SlotChildObserveController extends SlotController {
 
     // Custom node is added to the slot
     if (node && node !== this.defaultNode) {
-      this.__notifyChange(node);
+      this._notifyChange(node);
     } else {
       this.restoreDefaultNode();
       this.updateDefaultNode(this.node);
@@ -58,7 +61,7 @@ export class SlotChildObserveController extends SlotController {
     const node = super.attachDefaultNode();
 
     if (node) {
-      this.__updateNodeId(node);
+      this.#updateNodeId(node);
     }
 
     return node;
@@ -80,7 +83,7 @@ export class SlotChildObserveController extends SlotController {
    * @protected
    */
   updateDefaultNode(node) {
-    this.__notifyChange(node);
+    this._notifyChange(node);
   }
 
   /**
@@ -92,11 +95,11 @@ export class SlotChildObserveController extends SlotController {
    */
   observeNode(node) {
     // Stop observing the previous node, if any.
-    if (this.__nodeObserver) {
-      this.__nodeObserver.disconnect();
+    if (this.#nodeObserver) {
+      this.#nodeObserver.disconnect();
     }
 
-    this.__nodeObserver = new MutationObserver((mutations) => {
+    this.#nodeObserver = new MutationObserver((mutations) => {
       mutations.forEach((mutation) => {
         const target = mutation.target;
 
@@ -108,17 +111,17 @@ export class SlotChildObserveController extends SlotController {
           // We use attributeFilter to only observe ID mutation,
           // no need to check for attribute name separately.
           if (isCurrentNodeMutation) {
-            this.__updateNodeId(target);
+            this.#updateNodeId(target);
           }
         } else if (isCurrentNodeMutation || target.parentElement === this.node) {
           // Node text content has changed.
-          this.__notifyChange(this.node);
+          this._notifyChange(this.node);
         }
       });
     });
 
     // Observe changes to node ID attribute, text content and children.
-    this.__nodeObserver.observe(node, {
+    this.#nodeObserver.observe(node, {
       attributes: true,
       attributeFilter: ['id'],
       childList: true,
@@ -133,9 +136,8 @@ export class SlotChildObserveController extends SlotController {
    *
    * @param {Node} node
    * @return {boolean}
-   * @private
    */
-  __hasContent(node) {
+  #hasContent(node) {
     if (!node) {
       return false;
     }
@@ -150,12 +152,12 @@ export class SlotChildObserveController extends SlotController {
    * Fire an event to notify the controller host about node changes.
    *
    * @param {Node} node
-   * @private
+   * @protected
    */
-  __notifyChange(node) {
+  _notifyChange(node) {
     this.dispatchEvent(
       new CustomEvent('slot-content-changed', {
-        detail: { hasContent: this.__hasContent(node), node },
+        detail: { hasContent: this.#hasContent(node), node },
       }),
     );
   }
@@ -164,9 +166,8 @@ export class SlotChildObserveController extends SlotController {
    * Set default ID on the node in case it is an HTML element.
    *
    * @param {Node} node
-   * @private
    */
-  __updateNodeId(node) {
+  #updateNodeId(node) {
     // When in multiple mode, only set ID attribute on the element in default slot.
     const isFirstNode = !this.nodes || node === this.nodes[0];
     if (node.nodeType === Node.ELEMENT_NODE && (!this.multiple || isFirstNode) && !node.id) {

package/src/slot-controller.js

@@ -202,7 +202,8 @@ export class SlotController extends EventTarget {
     const selector = slotName === '' ? 'slot:not([name])' : `slot[name=${slotName}]`;
     const slot = this.host.shadowRoot.querySelector(selector);
 
-    this.__slotObserver = new SlotObserver(slot, ({ addedNodes, removedNodes }) => {
+    // eslint-disable-next-line no-new
+    new SlotObserver(slot, ({ addedNodes, removedNodes }) => {
       const current = this.multiple ? this.nodes : [this.node];
 
       // Calling `slot.assignedNodes()` includes whitespace text nodes in case of default slot:

package/src/slot-observer.d.ts

@@ -14,12 +14,18 @@
  * bubbling to it and diffs the **union** of `assignedNodes({ flatten: true })`
  * every descendant `<slot>`. Cross-slot reassignment of the same node does
  * not change the union and therefore fires no callback.
+ *
+ * The initial pass runs in a microtask by default. Use the `syncInitial` option
+ * when the callback sets state that affects the layout of the component, so that
+ * it has its final size once connected. Otherwise consumers that measure it
+ * synchronously, such as auto-width columns in `<vaadin-grid>`, would measure the
+ * component before that state is applied.
  */
 export class SlotObserver {
   constructor(
     target: HTMLSlotElement | DocumentFragment,
     callback: (info: { addedNodes: Node[]; currentNodes: Node[]; movedNodes: Node[]; removedNodes: Node[] }) => void,
-    forceInitial?: boolean,
+    options?: { forceInitial?: boolean; syncInitial?: boolean },
   );
 
   readonly target: HTMLSlotElement | DocumentFragment;

package/src/slot-observer.js

@@ -14,9 +14,20 @@
  * bubbling to it and diffs the **union** of `assignedNodes({ flatten: true })`
  * across every descendant `<slot>`. Cross-slot reassignment of the same node
  * does not change the union and therefore fires no callback.
+ *
+ * The initial pass runs in a microtask by default. Use the `syncInitial` option
+ * when the callback sets state that affects the layout of the component, so that
+ * it has its final size once connected. Otherwise consumers that measure it
+ * synchronously, such as auto-width columns in `<vaadin-grid>`, would measure the
+ * component before that state is applied.
  */
 export class SlotObserver {
-  constructor(target, callback, forceInitial) {
+  /**
+   * @param {HTMLSlotElement | DocumentFragment} target
+   * @param {Function} callback
+   * @param {{ forceInitial?: boolean, syncInitial?: boolean }} options
+   */
+  constructor(target, callback, options = {}) {
     /** @type {HTMLSlotElement | DocumentFragment} */
     this.target = target;
 
@@ -24,7 +35,7 @@ export class SlotObserver {
     this.callback = callback;
 
     /** @type {boolean} */
-    this.forceInitial = forceInitial;
+    this.forceInitial = options.forceInitial;
 
     /** @type {Node[]} */
     this._storedNodes = [];
@@ -40,7 +51,12 @@ export class SlotObserver {
     };
 
     this.connect();
-    this._schedule();
+
+    if (options.syncInitial) {
+      this.flush();
+    } else {
+      this._schedule();
+    }
   }
 
   /**
@@ -69,7 +85,11 @@ export class SlotObserver {
       this._scheduled = true;
 
       queueMicrotask(() => {
-        this.flush();
+        // Skip if the nodes have already been processed by an explicit `flush()`
+        // in the meantime, to avoid running the diff a second time for nothing.
+        if (this._scheduled) {
+          this.flush();
+        }
       });
     }
   }

package/src/styles/style-props.js

@@ -4,7 +4,7 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { css } from 'lit';
-import { addGlobalStyles } from './add-global-styles.js';
+import { addGlobalStyles, registerCSSProperty } from '../css-utils.js';
 
 // NOTE: Base color CSS custom properties are explicitly registered as `<color>`
 // here to avoid performance issues in Aura. Aura overrides these properties with
@@ -18,7 +18,7 @@ import { addGlobalStyles } from './add-global-styles.js';
   '--vaadin-border-color-secondary',
   '--vaadin-background-color',
 ].forEach((propertyName) => {
-  CSS.registerProperty({
+  registerCSSProperty({
     name: propertyName,
     syntax: '<color>',
     inherits: true,
@@ -83,10 +83,12 @@ addGlobalStyles(
         --_vaadin-icon-arrow-up: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m5 12 7-7 7 7"/><path d="M12 19V5"/></svg>');
         --_vaadin-icon-calendar: 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="2" stroke-linecap="round" stroke-linejoin="round"><path d="M8 2v4"/><path d="M16 2v4"/><rect width="18" height="18" x="3" y="4" rx="2"/><path d="M3 10h18"/></svg>');
         --_vaadin-icon-checkmark: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="m4.5 12.75 6 6 9-13.5" /></svg>');
+        --_vaadin-icon-checkmark-small: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="3.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="m4.5 12.75 6 6 9-13.5" /></svg>');
         --_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="2" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"/></svg>');
         --_vaadin-icon-chevron-right: 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="2" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6"/></svg>');
         --_vaadin-icon-clock: 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="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 6v6l4 2"/><circle cx="12" cy="12" r="10"/></svg>');
         --_vaadin-icon-cross: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M6 18 18 6M6 6l12 12" /></svg>');
+        --_vaadin-icon-cross-small: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="3.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M6 18 18 6M6 6l12 12" /></svg>');
         --_vaadin-icon-drag: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"><path d="M11 7c0 .82843-.6716 1.5-1.5 1.5C8.67157 8.5 8 7.82843 8 7s.67157-1.5 1.5-1.5c.8284 0 1.5.67157 1.5 1.5Zm0 5c0 .8284-.6716 1.5-1.5 1.5-.82843 0-1.5-.6716-1.5-1.5s.67157-1.5 1.5-1.5c.8284 0 1.5.6716 1.5 1.5Zm0 5c0 .8284-.6716 1.5-1.5 1.5-.82843 0-1.5-.6716-1.5-1.5s.67157-1.5 1.5-1.5c.8284 0 1.5.6716 1.5 1.5Zm5-10c0 .82843-.6716 1.5-1.5 1.5S13 7.82843 13 7s.6716-1.5 1.5-1.5S16 6.17157 16 7Zm0 5c0 .8284-.6716 1.5-1.5 1.5S13 12.8284 13 12s.6716-1.5 1.5-1.5 1.5.6716 1.5 1.5Zm0 5c0 .8284-.6716 1.5-1.5 1.5S13 17.8284 13 17s.6716-1.5 1.5-1.5 1.5.6716 1.5 1.5Z" fill="currentColor"/></svg>');
         --_vaadin-icon-ellipsis: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="1"/><circle cx="19" cy="12" r="1"/><circle cx="5" cy="12" r="1"/></svg>');
         --_vaadin-icon-eye: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M2.036 12.322a1.012 1.012 0 0 1 0-.639C3.423 7.51 7.36 4.5 12 4.5c4.638 0 8.573 3.007 9.963 7.178.07.207.07.431 0 .639C20.577 16.49 16.64 19.5 12 19.5c-4.638 0-8.573-3.007-9.963-7.178Z" /><path stroke-linecap="round" stroke-linejoin="round" d="M15 12a3 3 0 1 1-6 0 3 3 0 0 1 6 0Z" /></svg>');

package/src/styles/user-colors.js

@@ -4,7 +4,7 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { css } from 'lit';
-import { addGlobalStyles } from './add-global-styles.js';
+import { addGlobalStyles } from '../css-utils.js';
 
 addGlobalStyles(
   'vaadin-base-user-colors',

package/src/tooltip-controller.js

@@ -14,7 +14,6 @@ export class TooltipController extends SlotController {
     super(host, 'tooltip');
 
     this.setTarget(host);
-    this.__onContentChange = this.__onContentChange.bind(this);
   }
 
   /**
@@ -50,8 +49,8 @@ export class TooltipController extends SlotController {
     if (!this.manual) {
       this.host.setAttribute('has-tooltip', '');
     }
-    this.__notifyChange(tooltipNode);
-    tooltipNode.addEventListener('content-changed', this.__onContentChange);
+    this.#notifyChange(tooltipNode);
+    tooltipNode.addEventListener('content-changed', this.#onContentChange);
   }
 
   /**
@@ -65,8 +64,8 @@ export class TooltipController extends SlotController {
     if (!this.manual) {
       this.host.removeAttribute('has-tooltip');
     }
-    tooltipNode.removeEventListener('content-changed', this.__onContentChange);
-    this.__notifyChange(null);
+    tooltipNode.removeEventListener('content-changed', this.#onContentChange);
+    this.#notifyChange(null);
   }
 
   /**
@@ -179,13 +178,11 @@ export class TooltipController extends SlotController {
     }
   }
 
-  /** @private */
-  __onContentChange(event) {
-    this.__notifyChange(event.target);
-  }
+  #onContentChange = (event) => {
+    this.#notifyChange(event.target);
+  };
 
-  /** @private */
-  __notifyChange(node) {
+  #notifyChange(node) {
     this.dispatchEvent(new CustomEvent('tooltip-changed', { detail: { node } }));
   }
 }

package/src/virtualizer-iron-list-adapter.js

@@ -78,17 +78,17 @@ export class IronListAdapter {
     });
     attachObserver.observe(this.scrollTarget);
 
-    this.scrollTarget.addEventListener('virtualizer-element-focused', (e) => this.__onElementFocused(e));
-    this.elementsContainer.addEventListener('focusin', () => {
-      this.scrollTarget.dispatchEvent(
-        new CustomEvent('virtualizer-element-focused', { detail: { element: this.__getFocusedElement() } }),
-      );
-    });
+    this.elementsContainer.addEventListener('focusin', () => this.__onElementFocused());
 
     if (this.reorderElements) {
       // Reordering the physical elements cancels the user's grab of the scroll bar handle on Safari.
       // Need to defer reordering until the user lets go of the scroll bar handle.
-      this.scrollTarget.addEventListener('mousedown', () => {
+      this.scrollTarget.addEventListener('mousedown', (event) => {
+        // Only handle clicks on the scroll target itself
+        if (event.target !== this.scrollTarget) {
+          return;
+        }
+
         this.__mouseDown = true;
       });
       this.scrollTarget.addEventListener('mouseup', () => {
@@ -156,7 +156,7 @@ export class IronListAdapter {
     this.__skipNextVirtualIndexAdjust = true;
     super.scrollToIndex(targetVirtualIndex);
 
-    if (this.adjustedFirstVisibleIndex !== index && this._scrollTop < this._maxScrollTop && !this.grid) {
+    if (this.adjustedFirstVisibleIndex !== index && this._scrollTop < this._maxScrollTop) {
       // Workaround an iron-list issue by manually adjusting the scroll position
       this._scrollTop -= this.__getIndexScrollOffset(index) || 0;
     }
@@ -184,9 +184,6 @@ export class IronListAdapter {
     if (this.__scrollReorderDebouncer) {
       this.__scrollReorderDebouncer.flush();
     }
-    if (this.__debouncerWheelAnimationFrame) {
-      this.__debouncerWheelAnimationFrame.flush();
-    }
   }
 
   hostConnected() {
@@ -409,6 +406,8 @@ export class IronListAdapter {
       requestAnimationFrame(() => this._resizeHandler());
     }
 
+    this._updateScrollerSize(true);
+
     // Re-render items once the scroll position has been restored.
     // This call also updates the cached scrollTarget height and
     // rechecks whether more virtual elements are needed, since the
@@ -455,16 +454,10 @@ export class IronListAdapter {
 
   /** @private */
   updateViewportBoundaries() {
-    const styles = window.getComputedStyle(this.scrollTarget);
-    this._scrollerPaddingTop = this.scrollTarget === this ? 0 : parseInt(styles['padding-top'], 10);
-    this._isRTL = Boolean(styles.direction === 'rtl');
-    this._viewportWidth = this.elementsContainer.offsetWidth;
+    this._scrollerPaddingTop = parseInt(window.getComputedStyle(this.scrollTarget)['padding-top'], 10);
     this._viewportHeight = this.scrollTarget.offsetHeight;
   }
 
-  /** @private */
-  setAttribute() {}
-
   /** @private */
   _createPool(size) {
     const physicalItems = this.createElements(size);
@@ -514,20 +507,8 @@ export class IronListAdapter {
   toggleScrollListener() {}
 
   /** @private */
-  __getFocusedElement(visibleElements = this.__getVisibleElements()) {
-    // `document.activeElement` retargets to the outermost shadow host when
-    // focus lives in a nested shadow tree. Descend through nested shadow
-    // roots' `activeElement`s to reach the real focused node, then walk up
-    // the flattened tree (via `assignedSlot`/`parentNode`/`host`) until a
-    // visible row is reached.
-    let node = document.activeElement;
-    while (node?.shadowRoot?.activeElement) {
-      node = node.shadowRoot.activeElement;
-    }
-    while (node && !visibleElements.includes(node)) {
-      node = node.assignedSlot || node.parentNode || node.host;
-    }
-    return node;
+  __getFocusedElement() {
+    return this.__getVisibleElements().find((element) => element.matches(':focus-within'));
   }
 
   /** @private */
@@ -551,12 +532,12 @@ export class IronListAdapter {
   }
 
   /** @private */
-  __onElementFocused(e) {
+  __onElementFocused() {
     if (!this.reorderElements) {
       return;
     }
 
-    const focusedElement = e.detail.element;
+    const focusedElement = this.__getFocusedElement();
     if (!focusedElement) {
       return;
     }
@@ -798,7 +779,7 @@ export class IronListAdapter {
 
     // Which row to use as a target?
     const visibleElements = this.__getVisibleElements();
-    const targetElement = this.__getFocusedElement(visibleElements) || visibleElements[0];
+    const targetElement = this.__getFocusedElement() || visibleElements[0];
     if (!targetElement) {
       // All elements are hidden, don't reorder
       return;

package/src/styles/add-global-styles.js

@@ -1,19 +0,0 @@
-/**
- * @license
- * Copyright (c) 2025 - 2026 Vaadin Ltd.
- * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
- */
-
-/**
- * Add a `<style>` block with given styles to the document.
- *
- * @param {string} id the id to set on the created element, only for informational purposes
- * @param  {CSSResultGroup[]} styles the styles to add
- */
-export const addGlobalStyles = (id, ...styles) => {
-  const styleTag = document.createElement('style');
-  styleTag.id = id;
-  styleTag.textContent = styles.map((style) => style.toString()).join('\n');
-
-  document.head.insertAdjacentElement('afterbegin', styleTag);
-};