handsontable 18.0.0 → 18.1.0-rc7

package/themes/engine/manager.js

@@ -14,11 +14,17 @@ _export(exports, {
     },
     get createThemeManager () {
         return createThemeManager;
+    },
+    get isThemeOverrideEmpty () {
+        return isThemeOverrideEmpty;
     }
 });
 const _iconsMap = require("../static/variables/helpers/iconsMap");
 const _errors = require("../../helpers/errors");
+const _console = require("../../helpers/console");
+const _element = require("../../helpers/dom/element");
 const _cssVariables = require("./utils/cssVariables");
+const _validation = require("./utils/validation");
 function _check_private_redeclaration(obj, privateCollection) {
     if (privateCollection.has(obj)) {
         throw new TypeError("Cannot initialize the same private elements twice on an object");
@@ -75,13 +81,86 @@ function _class_private_method_init(obj, privateSet) {
  * @type {string}
  */ const THEME_PREFIX = 'ht-theme-';
 const THEME_STYLE_ATTRIBUTE = 'data-hot-theme-style';
+/**
+ * Prefix of the class that scopes the per-instance override rules to a single grid.
+ *
+ * It deliberately does not start with `ht-theme-`, because `Core#onThemeChange` strips every
+ * `ht-theme-*` class from the wrapper and portal elements when the theme changes.
+ *
+ * @type {string}
+ */ const THEME_SCOPE_PREFIX = 'ht-scope-';
+function isThemeOverrideEmpty(value) {
+    return value === undefined || value === null || value === false || value === '';
+}
+/**
+ * Resolves a color scheme to the value accepted by the CSS `color-scheme` property.
+ *
+ * @param {string} colorScheme The color scheme ('light', 'dark', or 'auto').
+ * @returns {string} The CSS `color-scheme` value.
+ */ function toCssColorScheme(colorScheme) {
+    return colorScheme === 'auto' ? 'light dark' : colorScheme;
+}
 var /**
    * Unsubscribes from the theme object's change notifications.
    *
    * @type {Function|null}
    */ _unsubscribeTheme = /*#__PURE__*/ new WeakMap(), /**
+   * Per-instance color scheme and density overrides applied on top of the theme configuration.
+   *
+   * @type {object}
+   */ _overrides = /*#__PURE__*/ new WeakMap(), /**
+   * The `<theme>:<density>` pair the "no density sizes" notice was last logged for, so re-injecting
+   * the styles does not repeat it.
+   *
+   * @type {string|null}
+   */ _missingDensityWarningKey = /*#__PURE__*/ new WeakMap(), /**
+   * Resolves one override value coming from the grid settings.
+   *
+   * This is a settings boundary, so it never throws. An empty value clears the override, and an
+   * unsupported one is reported and ignored — throwing here would abort `updateSettings()` half way
+   * through and leave the bad value stored in the grid meta, breaking every later theme change.
+   *
+   * @param {*} value The raw value from the settings.
+   * @param {string} optionName The option name, used in the warning.
+   * @param {Function} validate The validator for the option, which throws on an unsupported value.
+   * @param {*} currentValue The value currently applied, kept when the new one is unsupported.
+   * @returns {*} The resolved value, or `undefined` when the override is cleared.
+   */ _resolveOverrideValue = /*#__PURE__*/ new WeakSet(), /**
+   * Validates and stores the per-instance overrides.
+   *
+   * @param {object} overrides The color scheme and density overrides. An empty value clears the
+   * given override and falls back to the theme configuration.
+   * @returns {boolean} `true` when the effective overrides changed.
+   */ _setOverrides = /*#__PURE__*/ new WeakSet(), /**
+   * Builds the CSS variables that pin every light/dark value of the theme to one scheme.
+   *
+   * Setting the `color-scheme` property is not enough on its own. The shipped minified theme
+   * stylesheets do not use the CSS `light-dark()` function — it is newer than the browsers
+   * Handsontable supports, so the minifier rewrites it into a pair of variables switched by theme
+   * class name. Those declarations out-specify the ones the engine generates, so a grid that only
+   * flipped `color-scheme` would keep the light colors. Emitting the resolved values instead works
+   * in every supported browser and with every stylesheet.
+   *
+   * @param {string} scheme The scheme to resolve to ('light' or 'dark').
+   * @returns {string} The CSS variable declarations.
+   */ _buildResolvedColorVariables = /*#__PURE__*/ new WeakSet(), /**
+   * Builds the CSS rules that apply the per-instance overrides.
+   *
+   * The selector doubles the theme class with the instance scope class, giving specificity (0,2,0).
+   * That beats both the `:where()` block above (0,0,0) and the static `ht-theme-*.css` declarations
+   * (0,1,0), so the override wins no matter which stylesheet the page loaded.
+   *
+   * @returns {string} The CSS text, or an empty string when no override is active.
+   */ _buildOverrideStyles = /*#__PURE__*/ new WeakSet(), /**
    * Injects theme styles into the DOM.
-   */ _injectThemeStyles = /*#__PURE__*/ new WeakSet();
+   */ _injectThemeStyles = /*#__PURE__*/ new WeakSet(), /**
+   * Adds the instance scope class to the wrapper and portal elements.
+   *
+   * Both are stamped because menus, dropdowns, and dialogs render inside the portal element — a
+   * wrapper-only scope would leave them on the theme defaults while the grid follows the overrides.
+   */ _stampScopeClass = /*#__PURE__*/ new WeakSet(), /**
+   * Removes the instance scope class from the wrapper and portal elements.
+   */ _unstampScopeClass = /*#__PURE__*/ new WeakSet();
 class ThemeManager {
     /**
    * Gets the theme class name.
@@ -91,6 +170,44 @@ class ThemeManager {
         return this.themeClassName;
     }
     /**
+   * Gets the per-instance color scheme and density overrides.
+   *
+   * @returns {object} A copy of the currently applied overrides.
+   */ getOverrides() {
+        return {
+            ..._class_private_field_get(this, _overrides)
+        };
+    }
+    /**
+   * Gets the color scheme this grid renders with, taking the per-instance override into account.
+   *
+   * @returns {string|undefined} The color scheme ('light', 'dark', or 'auto').
+   */ getColorScheme() {
+        return _class_private_field_get(this, _overrides).colorScheme ?? this.themeConfig?.colorScheme;
+    }
+    /**
+   * Gets the density type this grid renders with, taking the per-instance override into account.
+   *
+   * @returns {string|undefined} The density type ('default', 'compact', or 'comfortable').
+   */ getDensityType() {
+        return _class_private_field_get(this, _overrides).density ?? this.themeConfig?.density?.type;
+    }
+    /**
+   * Applies per-instance color scheme and density overrides and re-injects the theme styles.
+   *
+   * The shared theme object is never mutated, so other grids using the same theme keep their look.
+   *
+   * @param {object} overrides The color scheme and density overrides. An `undefined` value clears
+   * the given override and falls back to the theme configuration.
+   * @returns {boolean} `true` when the effective overrides changed and the styles were re-injected.
+   */ setOverrides(overrides) {
+        if (!_class_private_method_get(this, _setOverrides, setOverrides).call(this, overrides)) {
+            return false;
+        }
+        _class_private_method_get(this, _injectThemeStyles, injectThemeStyles).call(this);
+        return true;
+    }
+    /**
    * Updates the theme manager.
    *
    * @param {object} themeObject - The theme object.
@@ -123,11 +240,13 @@ class ThemeManager {
     /**
    * Mounts the theme manager.
    */ mount() {
+        _class_private_method_get(this, _stampScopeClass, stampScopeClass).call(this);
         _class_private_method_get(this, _injectThemeStyles, injectThemeStyles).call(this);
     }
     /**
    * Unmounts the theme manager.
    */ unmount() {
+        _class_private_method_get(this, _unstampScopeClass, unstampScopeClass).call(this);
         if (this.themeStyles) {
             this.themeStyles.remove();
         }
@@ -146,12 +265,27 @@ class ThemeManager {
    * @param {object} options - The options object.
    * @param {Handsontable} options.hot - The Handsontable instance.
    * @param {object} options.themeObject - The theme object.
-   */ constructor({ hot, themeObject }){
+   * @param {object} [options.overrides] - The per-instance color scheme and density overrides.
+   */ constructor({ hot, themeObject, overrides }){
+        _class_private_method_init(this, _resolveOverrideValue);
+        _class_private_method_init(this, _setOverrides);
+        _class_private_method_init(this, _buildResolvedColorVariables);
+        _class_private_method_init(this, _buildOverrideStyles);
         _class_private_method_init(this, _injectThemeStyles);
+        _class_private_method_init(this, _stampScopeClass);
+        _class_private_method_init(this, _unstampScopeClass);
         _class_private_field_init(this, _unsubscribeTheme, {
             writable: true,
             value: void 0
         });
+        _class_private_field_init(this, _overrides, {
+            writable: true,
+            value: void 0
+        });
+        _class_private_field_init(this, _missingDensityWarningKey, {
+            writable: true,
+            value: void 0
+        });
         /**
    * The theme styles element.
    *
@@ -168,15 +302,95 @@ class ThemeManager {
    * @type {object}
    */ this.themeConfig = null;
         _class_private_field_set(this, _unsubscribeTheme, null);
+        _class_private_field_set(this, _overrides, {});
+        _class_private_field_set(this, _missingDensityWarningKey, null);
         this.hot = hot;
+        this.scopeClassName = `${THEME_SCOPE_PREFIX}${hot.guid}`;
+        if (overrides) {
+            _class_private_method_get(this, _setOverrides, setOverrides).call(this, overrides);
+        }
         this.update(themeObject);
     }
 }
+function resolveOverrideValue(value, optionName, validate, currentValue) {
+    if (isThemeOverrideEmpty(value)) {
+        return undefined;
+    }
+    try {
+        return validate(String(value));
+    } catch  {
+        (0, _console.warn)(`[ThemeManager] Ignoring the \`${optionName}\` option: ${JSON.stringify(value)} is not ` + 'a supported value.');
+        return currentValue;
+    }
+}
+function setOverrides(overrides) {
+    const nextOverrides = {
+        ..._class_private_field_get(this, _overrides)
+    };
+    if (Object.prototype.hasOwnProperty.call(overrides, 'colorScheme')) {
+        nextOverrides.colorScheme = _class_private_method_get(this, _resolveOverrideValue, resolveOverrideValue).call(this, overrides.colorScheme, 'colorScheme', _validation.validateColorScheme, _class_private_field_get(this, _overrides).colorScheme);
+    }
+    if (Object.prototype.hasOwnProperty.call(overrides, 'density')) {
+        nextOverrides.density = _class_private_method_get(this, _resolveOverrideValue, resolveOverrideValue).call(this, overrides.density, 'density', _validation.validateDensityType, _class_private_field_get(this, _overrides).density);
+    }
+    const hasChanged = nextOverrides.colorScheme !== _class_private_field_get(this, _overrides).colorScheme || nextOverrides.density !== _class_private_field_get(this, _overrides).density;
+    _class_private_field_set(this, _overrides, nextOverrides);
+    return hasChanged;
+}
+function buildResolvedColorVariables(scheme) {
+    if (!this.themeConfig) {
+        return '';
+    }
+    const options = {
+        resolveScheme: scheme,
+        lightDarkOnly: true
+    };
+    let cssText = '';
+    if (this.themeConfig.colors) {
+        cssText += (0, _cssVariables.flattenCssVariables)(this.themeConfig.colors, 'colors', '', options);
+    }
+    if (this.themeConfig.tokens) {
+        cssText += (0, _cssVariables.flattenCssVariables)(this.themeConfig.tokens, '', '', options);
+    }
+    return cssText;
+}
+function buildOverrideStyles() {
+    const { colorScheme, density } = _class_private_field_get(this, _overrides);
+    if (!colorScheme && !density) {
+        return '';
+    }
+    const selector = `.${this.themeClassName}.${this.scopeClassName}`;
+    const densitySizes = density ? this.themeConfig?.density?.sizes?.[density] : undefined;
+    let cssText = '';
+    if (densitySizes) {
+        cssText += `${selector} {\n${(0, _cssVariables.flattenCssVariables)(densitySizes, 'density')}}\n`;
+    } else if (density) {
+        // A custom theme may not define every preset. Say so instead of leaving the option looking
+        // applied while nothing changes on screen. Styles are re-injected on every theme change, so
+        // key the notice by theme and density to keep it to one line per real problem.
+        const warningKey = `${this.themeConfig?.name}:${density}`;
+        if (_class_private_field_get(this, _missingDensityWarningKey) !== warningKey) {
+            _class_private_field_set(this, _missingDensityWarningKey, warningKey);
+            (0, _console.warn)(`[ThemeManager] The "${this.themeConfig?.name}" theme has no "${density}" density ` + 'sizes, so the `density` option has no effect. Add the sizes to the theme configuration.');
+        }
+    }
+    if (colorScheme) {
+        cssText += `${selector} {\ncolor-scheme: ${toCssColorScheme(colorScheme)};\n`;
+        // 'auto' follows the operating system, so pin the light values and let a media query swap in
+        // the dark ones. That mirrors what the static `-dark-auto` class does, without `light-dark()`.
+        cssText += _class_private_method_get(this, _buildResolvedColorVariables, buildResolvedColorVariables).call(this, colorScheme === 'dark' ? 'dark' : 'light');
+        cssText += '}\n';
+        if (colorScheme === 'auto') {
+            cssText += `@media (prefers-color-scheme: dark) {\n${selector} {\n` + `${_class_private_method_get(this, _buildResolvedColorVariables, buildResolvedColorVariables).call(this, 'dark')}}\n}\n`;
+        }
+    }
+    return cssText;
+}
 function injectThemeStyles() {
     if (!this.themeConfig || !this.hot || !this.hot.rootDocument || !this.hot.rootWrapperElement) {
         return;
     }
-    const colorScheme = this.themeConfig.colorScheme === 'auto' ? 'light dark' : this.themeConfig.colorScheme;
+    const colorScheme = toCssColorScheme(this.themeConfig.colorScheme);
     if (!this.themeStyles) {
         this.themeStyles = this.hot.rootDocument.createElement('style');
         this.themeStyles.setAttribute(THEME_STYLE_ATTRIBUTE, 'true');
@@ -201,7 +415,8 @@ function injectThemeStyles() {
     // Separate rule with class-level specificity (0,1,0) so this <style> (injected into <body>)
     // wins over same-specificity color-scheme declarations in static ht-theme-*.css files via
     // source order, while keeping all other tokens at :where() specificity for easy overrides.
-    this.themeStyles.textContent += `.${this.themeClassName} {\ncolor-scheme: ${colorScheme};\n}`;
+    this.themeStyles.textContent += `.${this.themeClassName} {\ncolor-scheme: ${colorScheme};\n}\n`;
+    this.themeStyles.textContent += _class_private_method_get(this, _buildOverrideStyles, buildOverrideStyles).call(this);
     // Ensure that the manager always controls its own style node.
     // Some wrappers may contain other <style> tags and updating/removing a generic
     // querySelector('style') can leave the theme style mounted.
@@ -209,9 +424,30 @@ function injectThemeStyles() {
         this.hot.rootWrapperElement.prepend(this.themeStyles);
     }
 }
-function createThemeManager({ hot, themeObject }) {
+function stampScopeClass() {
+    [
+        this.hot?.rootWrapperElement,
+        this.hot?.rootPortalElement
+    ].forEach((element)=>{
+        if (element) {
+            (0, _element.addClass)(element, this.scopeClassName);
+        }
+    });
+}
+function unstampScopeClass() {
+    [
+        this.hot?.rootWrapperElement,
+        this.hot?.rootPortalElement
+    ].forEach((element)=>{
+        if (element) {
+            (0, _element.removeClass)(element, this.scopeClassName);
+        }
+    });
+}
+function createThemeManager({ hot, themeObject, overrides }) {
     return new ThemeManager({
         hot,
-        themeObject
+        themeObject,
+        overrides
     });
 }

package/themes/engine/manager.mjs

@@ -50,20 +50,105 @@ function _class_private_method_init(obj, privateSet) {
 }
 import { iconsMap } from '../static/variables/helpers/iconsMap.mjs';
 import { throwWithCause } from '../../helpers/errors.mjs';
+import { warn } from '../../helpers/console.mjs';
+import { addClass, removeClass } from '../../helpers/dom/element.mjs';
 import { flattenCssVariables } from './utils/cssVariables.mjs';
+import { validateColorScheme, validateDensityType } from './utils/validation.mjs';
 /**
  * The theme prefix.
  *
  * @type {string}
  */ const THEME_PREFIX = 'ht-theme-';
 const THEME_STYLE_ATTRIBUTE = 'data-hot-theme-style';
+/**
+ * Prefix of the class that scopes the per-instance override rules to a single grid.
+ *
+ * It deliberately does not start with `ht-theme-`, because `Core#onThemeChange` strips every
+ * `ht-theme-*` class from the wrapper and portal elements when the theme changes.
+ *
+ * @type {string}
+ */ const THEME_SCOPE_PREFIX = 'ht-scope-';
+/**
+ * Checks whether an override value means "use the theme value".
+ *
+ * `undefined` is the documented way to clear an override, and the other empty values are treated
+ * the same so a framework wrapper passing `null` or `''` for an unset prop clears rather than
+ * fails. Exported so the settings layer applies exactly the same rule.
+ *
+ * @param {*} value The raw override value.
+ * @returns {boolean} `true` when the value clears the override.
+ */ export function isThemeOverrideEmpty(value) {
+    return value === undefined || value === null || value === false || value === '';
+}
+/**
+ * Resolves a color scheme to the value accepted by the CSS `color-scheme` property.
+ *
+ * @param {string} colorScheme The color scheme ('light', 'dark', or 'auto').
+ * @returns {string} The CSS `color-scheme` value.
+ */ function toCssColorScheme(colorScheme) {
+    return colorScheme === 'auto' ? 'light dark' : colorScheme;
+}
 var /**
    * Unsubscribes from the theme object's change notifications.
    *
    * @type {Function|null}
    */ _unsubscribeTheme = /*#__PURE__*/ new WeakMap(), /**
+   * Per-instance color scheme and density overrides applied on top of the theme configuration.
+   *
+   * @type {object}
+   */ _overrides = /*#__PURE__*/ new WeakMap(), /**
+   * The `<theme>:<density>` pair the "no density sizes" notice was last logged for, so re-injecting
+   * the styles does not repeat it.
+   *
+   * @type {string|null}
+   */ _missingDensityWarningKey = /*#__PURE__*/ new WeakMap(), /**
+   * Resolves one override value coming from the grid settings.
+   *
+   * This is a settings boundary, so it never throws. An empty value clears the override, and an
+   * unsupported one is reported and ignored — throwing here would abort `updateSettings()` half way
+   * through and leave the bad value stored in the grid meta, breaking every later theme change.
+   *
+   * @param {*} value The raw value from the settings.
+   * @param {string} optionName The option name, used in the warning.
+   * @param {Function} validate The validator for the option, which throws on an unsupported value.
+   * @param {*} currentValue The value currently applied, kept when the new one is unsupported.
+   * @returns {*} The resolved value, or `undefined` when the override is cleared.
+   */ _resolveOverrideValue = /*#__PURE__*/ new WeakSet(), /**
+   * Validates and stores the per-instance overrides.
+   *
+   * @param {object} overrides The color scheme and density overrides. An empty value clears the
+   * given override and falls back to the theme configuration.
+   * @returns {boolean} `true` when the effective overrides changed.
+   */ _setOverrides = /*#__PURE__*/ new WeakSet(), /**
+   * Builds the CSS variables that pin every light/dark value of the theme to one scheme.
+   *
+   * Setting the `color-scheme` property is not enough on its own. The shipped minified theme
+   * stylesheets do not use the CSS `light-dark()` function — it is newer than the browsers
+   * Handsontable supports, so the minifier rewrites it into a pair of variables switched by theme
+   * class name. Those declarations out-specify the ones the engine generates, so a grid that only
+   * flipped `color-scheme` would keep the light colors. Emitting the resolved values instead works
+   * in every supported browser and with every stylesheet.
+   *
+   * @param {string} scheme The scheme to resolve to ('light' or 'dark').
+   * @returns {string} The CSS variable declarations.
+   */ _buildResolvedColorVariables = /*#__PURE__*/ new WeakSet(), /**
+   * Builds the CSS rules that apply the per-instance overrides.
+   *
+   * The selector doubles the theme class with the instance scope class, giving specificity (0,2,0).
+   * That beats both the `:where()` block above (0,0,0) and the static `ht-theme-*.css` declarations
+   * (0,1,0), so the override wins no matter which stylesheet the page loaded.
+   *
+   * @returns {string} The CSS text, or an empty string when no override is active.
+   */ _buildOverrideStyles = /*#__PURE__*/ new WeakSet(), /**
    * Injects theme styles into the DOM.
-   */ _injectThemeStyles = /*#__PURE__*/ new WeakSet();
+   */ _injectThemeStyles = /*#__PURE__*/ new WeakSet(), /**
+   * Adds the instance scope class to the wrapper and portal elements.
+   *
+   * Both are stamped because menus, dropdowns, and dialogs render inside the portal element — a
+   * wrapper-only scope would leave them on the theme defaults while the grid follows the overrides.
+   */ _stampScopeClass = /*#__PURE__*/ new WeakSet(), /**
+   * Removes the instance scope class from the wrapper and portal elements.
+   */ _unstampScopeClass = /*#__PURE__*/ new WeakSet();
 /**
  * ThemeManager class provides methods to manage the theme styles.
  *
@@ -77,6 +162,44 @@ var /**
         return this.themeClassName;
     }
     /**
+   * Gets the per-instance color scheme and density overrides.
+   *
+   * @returns {object} A copy of the currently applied overrides.
+   */ getOverrides() {
+        return {
+            ..._class_private_field_get(this, _overrides)
+        };
+    }
+    /**
+   * Gets the color scheme this grid renders with, taking the per-instance override into account.
+   *
+   * @returns {string|undefined} The color scheme ('light', 'dark', or 'auto').
+   */ getColorScheme() {
+        return _class_private_field_get(this, _overrides).colorScheme ?? this.themeConfig?.colorScheme;
+    }
+    /**
+   * Gets the density type this grid renders with, taking the per-instance override into account.
+   *
+   * @returns {string|undefined} The density type ('default', 'compact', or 'comfortable').
+   */ getDensityType() {
+        return _class_private_field_get(this, _overrides).density ?? this.themeConfig?.density?.type;
+    }
+    /**
+   * Applies per-instance color scheme and density overrides and re-injects the theme styles.
+   *
+   * The shared theme object is never mutated, so other grids using the same theme keep their look.
+   *
+   * @param {object} overrides The color scheme and density overrides. An `undefined` value clears
+   * the given override and falls back to the theme configuration.
+   * @returns {boolean} `true` when the effective overrides changed and the styles were re-injected.
+   */ setOverrides(overrides) {
+        if (!_class_private_method_get(this, _setOverrides, setOverrides).call(this, overrides)) {
+            return false;
+        }
+        _class_private_method_get(this, _injectThemeStyles, injectThemeStyles).call(this);
+        return true;
+    }
+    /**
    * Updates the theme manager.
    *
    * @param {object} themeObject - The theme object.
@@ -109,11 +232,13 @@ var /**
     /**
    * Mounts the theme manager.
    */ mount() {
+        _class_private_method_get(this, _stampScopeClass, stampScopeClass).call(this);
         _class_private_method_get(this, _injectThemeStyles, injectThemeStyles).call(this);
     }
     /**
    * Unmounts the theme manager.
    */ unmount() {
+        _class_private_method_get(this, _unstampScopeClass, unstampScopeClass).call(this);
         if (this.themeStyles) {
             this.themeStyles.remove();
         }
@@ -132,12 +257,27 @@ var /**
    * @param {object} options - The options object.
    * @param {Handsontable} options.hot - The Handsontable instance.
    * @param {object} options.themeObject - The theme object.
-   */ constructor({ hot, themeObject }){
+   * @param {object} [options.overrides] - The per-instance color scheme and density overrides.
+   */ constructor({ hot, themeObject, overrides }){
+        _class_private_method_init(this, _resolveOverrideValue);
+        _class_private_method_init(this, _setOverrides);
+        _class_private_method_init(this, _buildResolvedColorVariables);
+        _class_private_method_init(this, _buildOverrideStyles);
         _class_private_method_init(this, _injectThemeStyles);
+        _class_private_method_init(this, _stampScopeClass);
+        _class_private_method_init(this, _unstampScopeClass);
         _class_private_field_init(this, _unsubscribeTheme, {
             writable: true,
             value: void 0
         });
+        _class_private_field_init(this, _overrides, {
+            writable: true,
+            value: void 0
+        });
+        _class_private_field_init(this, _missingDensityWarningKey, {
+            writable: true,
+            value: void 0
+        });
         /**
    * The theme styles element.
    *
@@ -154,15 +294,95 @@ var /**
    * @type {object}
    */ this.themeConfig = null;
         _class_private_field_set(this, _unsubscribeTheme, null);
+        _class_private_field_set(this, _overrides, {});
+        _class_private_field_set(this, _missingDensityWarningKey, null);
         this.hot = hot;
+        this.scopeClassName = `${THEME_SCOPE_PREFIX}${hot.guid}`;
+        if (overrides) {
+            _class_private_method_get(this, _setOverrides, setOverrides).call(this, overrides);
+        }
         this.update(themeObject);
     }
 }
+function resolveOverrideValue(value, optionName, validate, currentValue) {
+    if (isThemeOverrideEmpty(value)) {
+        return undefined;
+    }
+    try {
+        return validate(String(value));
+    } catch  {
+        warn(`[ThemeManager] Ignoring the \`${optionName}\` option: ${JSON.stringify(value)} is not ` + 'a supported value.');
+        return currentValue;
+    }
+}
+function setOverrides(overrides) {
+    const nextOverrides = {
+        ..._class_private_field_get(this, _overrides)
+    };
+    if (Object.prototype.hasOwnProperty.call(overrides, 'colorScheme')) {
+        nextOverrides.colorScheme = _class_private_method_get(this, _resolveOverrideValue, resolveOverrideValue).call(this, overrides.colorScheme, 'colorScheme', validateColorScheme, _class_private_field_get(this, _overrides).colorScheme);
+    }
+    if (Object.prototype.hasOwnProperty.call(overrides, 'density')) {
+        nextOverrides.density = _class_private_method_get(this, _resolveOverrideValue, resolveOverrideValue).call(this, overrides.density, 'density', validateDensityType, _class_private_field_get(this, _overrides).density);
+    }
+    const hasChanged = nextOverrides.colorScheme !== _class_private_field_get(this, _overrides).colorScheme || nextOverrides.density !== _class_private_field_get(this, _overrides).density;
+    _class_private_field_set(this, _overrides, nextOverrides);
+    return hasChanged;
+}
+function buildResolvedColorVariables(scheme) {
+    if (!this.themeConfig) {
+        return '';
+    }
+    const options = {
+        resolveScheme: scheme,
+        lightDarkOnly: true
+    };
+    let cssText = '';
+    if (this.themeConfig.colors) {
+        cssText += flattenCssVariables(this.themeConfig.colors, 'colors', '', options);
+    }
+    if (this.themeConfig.tokens) {
+        cssText += flattenCssVariables(this.themeConfig.tokens, '', '', options);
+    }
+    return cssText;
+}
+function buildOverrideStyles() {
+    const { colorScheme, density } = _class_private_field_get(this, _overrides);
+    if (!colorScheme && !density) {
+        return '';
+    }
+    const selector = `.${this.themeClassName}.${this.scopeClassName}`;
+    const densitySizes = density ? this.themeConfig?.density?.sizes?.[density] : undefined;
+    let cssText = '';
+    if (densitySizes) {
+        cssText += `${selector} {\n${flattenCssVariables(densitySizes, 'density')}}\n`;
+    } else if (density) {
+        // A custom theme may not define every preset. Say so instead of leaving the option looking
+        // applied while nothing changes on screen. Styles are re-injected on every theme change, so
+        // key the notice by theme and density to keep it to one line per real problem.
+        const warningKey = `${this.themeConfig?.name}:${density}`;
+        if (_class_private_field_get(this, _missingDensityWarningKey) !== warningKey) {
+            _class_private_field_set(this, _missingDensityWarningKey, warningKey);
+            warn(`[ThemeManager] The "${this.themeConfig?.name}" theme has no "${density}" density ` + 'sizes, so the `density` option has no effect. Add the sizes to the theme configuration.');
+        }
+    }
+    if (colorScheme) {
+        cssText += `${selector} {\ncolor-scheme: ${toCssColorScheme(colorScheme)};\n`;
+        // 'auto' follows the operating system, so pin the light values and let a media query swap in
+        // the dark ones. That mirrors what the static `-dark-auto` class does, without `light-dark()`.
+        cssText += _class_private_method_get(this, _buildResolvedColorVariables, buildResolvedColorVariables).call(this, colorScheme === 'dark' ? 'dark' : 'light');
+        cssText += '}\n';
+        if (colorScheme === 'auto') {
+            cssText += `@media (prefers-color-scheme: dark) {\n${selector} {\n` + `${_class_private_method_get(this, _buildResolvedColorVariables, buildResolvedColorVariables).call(this, 'dark')}}\n}\n`;
+        }
+    }
+    return cssText;
+}
 function injectThemeStyles() {
     if (!this.themeConfig || !this.hot || !this.hot.rootDocument || !this.hot.rootWrapperElement) {
         return;
     }
-    const colorScheme = this.themeConfig.colorScheme === 'auto' ? 'light dark' : this.themeConfig.colorScheme;
+    const colorScheme = toCssColorScheme(this.themeConfig.colorScheme);
     if (!this.themeStyles) {
         this.themeStyles = this.hot.rootDocument.createElement('style');
         this.themeStyles.setAttribute(THEME_STYLE_ATTRIBUTE, 'true');
@@ -187,7 +407,8 @@ function injectThemeStyles() {
     // Separate rule with class-level specificity (0,1,0) so this <style> (injected into <body>)
     // wins over same-specificity color-scheme declarations in static ht-theme-*.css files via
     // source order, while keeping all other tokens at :where() specificity for easy overrides.
-    this.themeStyles.textContent += `.${this.themeClassName} {\ncolor-scheme: ${colorScheme};\n}`;
+    this.themeStyles.textContent += `.${this.themeClassName} {\ncolor-scheme: ${colorScheme};\n}\n`;
+    this.themeStyles.textContent += _class_private_method_get(this, _buildOverrideStyles, buildOverrideStyles).call(this);
     // Ensure that the manager always controls its own style node.
     // Some wrappers may contain other <style> tags and updating/removing a generic
     // querySelector('style') can leave the theme style mounted.
@@ -195,16 +416,38 @@ function injectThemeStyles() {
         this.hot.rootWrapperElement.prepend(this.themeStyles);
     }
 }
+function stampScopeClass() {
+    [
+        this.hot?.rootWrapperElement,
+        this.hot?.rootPortalElement
+    ].forEach((element)=>{
+        if (element) {
+            addClass(element, this.scopeClassName);
+        }
+    });
+}
+function unstampScopeClass() {
+    [
+        this.hot?.rootWrapperElement,
+        this.hot?.rootPortalElement
+    ].forEach((element)=>{
+        if (element) {
+            removeClass(element, this.scopeClassName);
+        }
+    });
+}
 /**
  * Creates a new ThemeManager instance.
  *
  * @param {object} options - The options object.
  * @param {Handsontable} options.hot - The Handsontable instance.
  * @param {object} options.themeObject - The theme object.
+ * @param {object} [options.overrides] - The per-instance color scheme and density overrides.
  * @returns {ThemeManager} The ThemeManager instance.
- */ export function createThemeManager({ hot, themeObject }) {
+ */ export function createThemeManager({ hot, themeObject, overrides }) {
     return new ThemeManager({
         hot,
-        themeObject
+        themeObject,
+        overrides
     });
 }