handsontable 18.0.0 → 18.1.0-rc7

package/tableView.mjs

@@ -48,14 +48,27 @@ function _class_private_method_init(obj, privateSet) {
     _check_private_redeclaration(obj, privateSet);
     privateSet.add(obj);
 }
-import { addClass, removeClass, clearTextSelection, empty, eventTargetEl, fastInnerHTML, fastInnerText, getScrollbarWidth, hasClass, isChildOf, isInput, isOutsideInput, isVisible, setAttribute, getParentWindow } from './helpers/dom/element.mjs';
+import { addClass, removeClass, clearTextSelection, empty, eventTargetEl, fastInnerHTML, fastInnerText, getScrollbarWidth, hasClass, isChildOf, getDeepActiveElement, getShadowHostChain, isHTMLElement, isInput, isOutsideInput, isShadowRoot, isVisible, setAttribute, getParentWindow } from './helpers/dom/element.mjs';
 import EventManager from './eventManager.mjs';
+import { formatCellValue, renderCell } from './renderers/renderCell.mjs';
+import { RenderSizeProbe } from './renderSizeProbe.mjs';
 import { isImmediatePropagationStopped, isRightClick, isLeftClick, isMiddleClick } from './helpers/dom/event.mjs';
 import Walkontable from './3rdparty/walkontable/src/index.mjs';
 import { handleMouseEvent } from './selection/mouseEventHandler.mjs';
 import { isRootInstance } from './utils/rootInstance.mjs';
+import { getSanitizer } from './utils/sanitizer.mjs';
 import { resolveWithInstance } from './utils/staticRegister.mjs';
 import { A11Y_COLCOUNT, A11Y_MULTISELECTABLE, A11Y_PRESENTATION, A11Y_ROWCOUNT, A11Y_TREEGRID } from './helpers/a11y.mjs';
+/**
+ * Checks whether a size setting (`rowHeights`, `minRowHeights`, or `colWidths`) guarantees a uniform
+ * size for every item. Only a plain number (or unset) is uniform; an array or function defines
+ * per-item sizes, and a string is treated conservatively as non-uniform.
+ *
+ * @param {unknown} value The size setting value.
+ * @returns {boolean}
+ */ function isUniformSizeSetting(value) {
+    return value === undefined || value === null || typeof value === 'number';
+}
 var /**
    * The total number of the column header renderers applied to the table through the
    * `afterGetColumnHeaderRenderers` hook.
@@ -67,12 +80,24 @@ var /**
    *
    * @type {number}
    */ _rowHeadersCount = /*#__PURE__*/ new WeakMap(), /**
+   * Whether the sizes measured from theme values cached against unresolved styles still have to be
+   * dropped. Set by the first render that finds the styles resolvable again, and kept until a render
+   * has actually reached the cells and re-measured them (see `#discardSizesMeasuredWithoutStyles`).
+   *
+   * @type {boolean}
+   */ _sizesMeasuredWithoutStylesPending = /*#__PURE__*/ new WeakMap(), /**
    * Defines if the text should be selected during mousemove.
    *
    * @type {boolean}
    */ _selectionMouseDown = /*#__PURE__*/ new WeakMap(), /**
    * @type {boolean}
    */ _mouseDown = /*#__PURE__*/ new WeakMap(), /**
+   * Tracks whether the document-level mousedown handler already classified the current click
+   * cycle as an outside click and consulted the `outsideClickDeselects` setting. The mouseup
+   * handler skips its own deselect pass then, so the setting's callback fires once per click.
+   *
+   * @type {boolean}
+   */ _outsideClickHandled = /*#__PURE__*/ new WeakMap(), /**
    * Main <TABLE> element.
    *
    * @type {HTMLTableElement}
@@ -117,6 +142,38 @@ var /**
    * @private
    * @returns {boolean}
    */ _isSyntheticMouseEvent = /*#__PURE__*/ new WeakSet(), /**
+   * Checks whether the event path points into the grid. The path counts as internal when it
+   * contains the grid's root element or its portal element. A complete path (one that crosses
+   * shadow boundaries and therefore contains ShadowRoot entries) is trusted as-is - a miss
+   * means a genuine outside click, even when the path shares the grid's shadow hosts. Only a
+   * filtered path (no ShadowRoot entries) falls back to the shadow host chain check, which
+   * matters for sandboxed hosts (e.g. Salesforce Lightning Web Security) that collapse paths
+   * observed at the document level to the visible host chain, hiding the grid internals.
+   *
+   * @param {EventTarget[]} eventPath The event propagation path (`event.composedPath()`).
+   * @private
+   * @returns {boolean}
+   */ _isPathWithinGrid = /*#__PURE__*/ new WeakSet(), /**
+   * Discards the row heights measured from theme values that were cached while the grid's root
+   * element resolved no computed styles, on the first draw that finds them resolvable again.
+   *
+   * A grid whose theme variables were cached against unresolved styles has an unknown default row
+   * height, so every rendered row is recorded oversized at a height it never had, and nothing
+   * re-measures those records on its own (DEV-2515 – the theme half of the unrendered-table problem
+   * described in `walkontable/AGENTS.md`).
+   *
+   * The styles handler answers both halves, because it is what cached the values: whether an earlier
+   * pass read them against unresolved styles, and whether they resolve now. Gating on the unknown row
+   * height instead would wipe the caches on every draw of a page that loads no grid stylesheet at
+   * all, where that value never resolves.
+   *
+   * Runs before `_wt.draw()`, not from the engine's `beforeDraw` setting: that setting fires after
+   * `createCalculators()`, so the rendered row band of that very draw would still be built from the
+   * heights this drops – the grid renders short for one frame and nothing schedules another draw. The
+   * drop stays pending (`#sizesMeasuredWithoutStylesPending`) until a draw has actually rendered the
+   * cells and re-measured them, which is what `afterRender` reports; a `beforeViewRender` listener
+   * that sets `skipRender` cancels the render, and then nothing takes the row heights again.
+   */ _discardSizesMeasuredWithoutStyles = /*#__PURE__*/ new WeakSet(), /**
    * Return the value of the `aria-colcount` attribute.
    *
    * @returns {number} The value of the `aria-colcount` attribute.
@@ -141,6 +198,7 @@ var /**
         if (!this.hot.isRenderSuspended()) {
             const isFullRender = this.hot.forceFullRender;
             this.hot.runHooks('beforeRender', isFullRender);
+            _class_private_method_get(this, _discardSizesMeasuredWithoutStyles, discardSizesMeasuredWithoutStyles).call(this);
             this._wt.draw(!isFullRender);
             _class_private_method_get(this, _updateScrollbarClassNames, updateScrollbarClassNames).call(this);
             if (this.postponedAdjustElementsSize) {
@@ -302,18 +360,34 @@ var /**
             if (selection.isInProgress() && isLeftClick(event)) {
                 selection.finish();
             }
+            const wasInsideGridClick = _class_private_field_get(this, _mouseDown);
+            const wasOutsideClickHandled = _class_private_field_get(this, _outsideClickHandled);
             _class_private_field_set(this, _mouseDown, false);
+            _class_private_field_set(this, _outsideClickHandled, false);
             // Ignore synthetic mouseup events from Android touch interactions.
             if (_class_private_method_get(this, _isSyntheticMouseEvent, isSyntheticMouseEvent).call(this, event)) {
                 return;
             }
-            const isOutsideInputElement = isOutsideInput(rootDocument.activeElement);
-            if (isInput(rootDocument.activeElement) && !isOutsideInputElement) {
+            const activeElement = getDeepActiveElement(rootDocument);
+            const activeHTMLElement = isHTMLElement(activeElement) ? activeElement : null;
+            const isOutsideInputElement = activeHTMLElement !== null && isOutsideInput(activeHTMLElement);
+            if (activeHTMLElement !== null && isInput(activeHTMLElement) && !isOutsideInputElement) {
                 return;
             }
-            if (isOutsideInputElement || !selection.isSelected() && !selection.isSelectedByAnyHeader() && !(rootWrapperElement ?? rootElement).contains(event.target) && !isRightClick(event)) {
+            const eventPath = event.composedPath();
+            const isPathThroughGridUi = eventPath.includes(rootWrapperElement ?? rootElement) || this.hot.rootPortalElement && eventPath.includes(this.hot.rootPortalElement);
+            const isFocusLostToOutside = this.hot.getFocusManager().isForeignFocusTarget(activeHTMLElement) || !wasInsideGridClick && !this.hot.getFocusManager().hasBrowserFocus() && !isPathThroughGridUi;
+            if (isOutsideInputElement || isFocusLostToOutside || !selection.isSelected() && !selection.isSelectedByAnyHeader() && !_class_private_method_get(this, _isPathWithinGrid, isPathWithinGrid).call(this, eventPath) && !isRightClick(event)) {
                 this.hot.unlisten();
             }
+            if (!wasOutsideClickHandled && activeHTMLElement !== null && isFocusLostToOutside && selection.isSelected() && !_class_private_method_get(this, _isPathWithinGrid, isPathWithinGrid).call(this, eventPath) && !isRightClick(event)) {
+                const clickTarget = eventPath.length > 0 ? eventPath[0] : event.target;
+                const clickTargetElement = isHTMLElement(clickTarget) ? clickTarget : activeHTMLElement;
+                const outsideClickDeselects = typeof this.settings.outsideClickDeselects === 'function' ? this.settings.outsideClickDeselects(clickTargetElement) : this.settings.outsideClickDeselects;
+                if (outsideClickDeselects) {
+                    this.hot.deselectCell();
+                }
+            }
         });
         this.eventManager.addEventListener(documentElement, 'contextmenu', (event)=>{
             if (selection.isInProgress() && isRightClick(event)) {
@@ -342,10 +416,11 @@ var /**
             }, 400));
         });
         this.eventManager.addEventListener(documentElement, 'mousedown', (event)=>{
-            const originalTarget = event.target;
+            const eventPath = event.composedPath();
+            const originalTarget = eventPath.length > 0 ? eventPath[0] : event.target;
             const eventX = event.clientX;
             const eventY = event.clientY;
-            let next = event.target;
+            _class_private_field_set(this, _outsideClickHandled, false);
             if (_class_private_field_get(this, _mouseDown) || !rootElement || !this.hot.view) {
                 return; // it must have been started in a cell
             }
@@ -355,29 +430,19 @@ var /**
             }
             // immediate click on "holder" means click on the right side of vertical scrollbar
             const { holder } = this._wt.wtTable;
-            if (next === holder) {
+            if (originalTarget === holder) {
                 const scrollbarWidth = getScrollbarWidth(rootDocument);
-                if (rootDocument.elementFromPoint(eventX + scrollbarWidth, eventY) !== holder || rootDocument.elementFromPoint(eventX, eventY + scrollbarWidth) !== holder) {
+                const rootNode = rootElement.getRootNode();
+                const pointReader = isShadowRoot(rootNode) ? rootNode : rootDocument;
+                if (pointReader.elementFromPoint(eventX + scrollbarWidth, eventY) !== holder || pointReader.elementFromPoint(eventX, eventY + scrollbarWidth) !== holder) {
                     return;
                 }
-            } else {
-                const { rootPortalElement } = this.hot;
-                while(next !== documentElement){
-                    if (next === null) {
-                        if (event.isTargetWebComponent) {
-                            break;
-                        }
-                        // click on something that was a row but now is detached (possibly because your click triggered a rerender)
-                        return;
-                    }
-                    if (next === rootElement || next === rootPortalElement) {
-                        // click inside container or portal
-                        return;
-                    }
-                    next = next.parentNode;
-                }
+            } else if (_class_private_method_get(this, _isPathWithinGrid, isPathWithinGrid).call(this, eventPath)) {
+                // click inside container, portal, or a shadow host the grid is rendered within
+                return;
             }
             // function did not return until here, we have an outside click!
+            _class_private_field_set(this, _outsideClickHandled, true);
             const outsideClickDeselects = typeof this.settings.outsideClickDeselects === 'function' ? this.settings.outsideClickDeselects(originalTarget) : this.settings.outsideClickDeselects;
             if (outsideClickDeselects) {
                 this.hot.deselectCell();
@@ -603,12 +668,21 @@ var /**
             ariaTags: this.settings.ariaTags,
             rtlMode: this.hot.isRtl(),
             externalRowCalculator: this.hot.getPlugin('autoRowSize') && this.hot.getPlugin('autoRowSize').isEnabled(),
+            // Single-pass rendering is on by default; the `modifySinglePassLayout` hook lets a plugin or
+            // user code force the legacy measure-then-render path by returning `false` (e.g. `mergeCells`,
+            // whose virtualized row heights depend on the viewport the layout is computing). Evaluated per
+            // read so toggling a plugin via `updateSettings` takes effect without re-initializing Walkontable.
+            singlePassLayout: ()=>this.hot.runHooks('modifySinglePassLayout', true),
             table: _class_private_field_get(this, _table),
             isDataViewInstance: ()=>isRootInstance(this.hot),
             preventOverflow: ()=>this.settings.preventOverflow,
             preventWheel: ()=>this.settings.preventWheel,
             viewportColumnRenderingThreshold: ()=>this.settings.viewportColumnRenderingThreshold,
             viewportRowRenderingThreshold: ()=>this.settings.viewportRowRenderingThreshold,
+            // 'auto' is the dynamic-overscan mode; an explicit number is an exact manual offset, which
+            // also opts the axis out of the engine's directional scroll-overscan.
+            viewportColumnRenderingOffsetIsAuto: ()=>this.settings.viewportColumnRenderingOffset === 'auto',
+            viewportRowRenderingOffsetIsAuto: ()=>this.settings.viewportRowRenderingOffset === 'auto',
             data: (renderableRow, renderableColumn)=>{
                 const [visualRow, visualCol] = this.translateFromRenderableToVisualIndex(renderableRow, renderableColumn);
                 return this.hot.getDataAtCell(visualRow, visualCol);
@@ -687,6 +761,13 @@ var /**
                 const visualRowIndex = visualIndex === null ? renderedRowIndex : visualIndex;
                 return this.hot.runHooks('modifyRowHeightByOverlayName', this.hot.getRowHeight(visualRowIndex), visualRowIndex, overlayType);
             },
+            rowHeightsUniform: ()=>{
+                const { rowHeights, minRowHeights } = this.hot.getSettings();
+                return isUniformSizeSetting(rowHeights) && isUniformSizeSetting(minRowHeights) && !this.hot.hasHook('modifyRowHeight');
+            },
+            columnWidthsUniform: ()=>{
+                return isUniformSizeSetting(this.hot.getSettings().colWidths) && !this.hot.hasHook('modifyColWidth');
+            },
             cellRenderer: (renderedRowIndex, renderedColumnIndex, TD)=>{
                 const [visualRowIndex, visualColumnIndex] = this.translateFromRenderableToVisualIndex(renderedRowIndex, renderedColumnIndex);
                 // Coords may be modified. For example, by the `MergeCells` plugin. It should affect cell value and cell meta.
@@ -703,15 +784,7 @@ var /**
                     value = this.hot.runHooks('beforeValueRender', value, cellProperties);
                 }
                 const renderer = this.hot.getCellRenderer(cellProperties);
-                let formattedValue = value;
-                if (typeof cellProperties.valueFormatter === 'function') {
-                    formattedValue = cellProperties.valueFormatter(formattedValue, cellProperties);
-                } else if (typeof renderer === 'function' && 'valueFormatter' in renderer) {
-                    const { valueFormatter } = renderer;
-                    if (typeof valueFormatter === 'function') {
-                        formattedValue = valueFormatter.call(cellProperties, formattedValue, cellProperties);
-                    }
-                }
+                const formattedValue = formatCellValue(value, cellProperties, renderer);
                 this.hot.runHooks('beforeRenderer', TD, visualRowIndex, visualColumnIndex, prop, value, cellProperties);
                 const rendererArgs = [
                     this.hot,
@@ -722,14 +795,8 @@ var /**
                     formattedValue,
                     cellProperties
                 ];
-                renderer(...rendererArgs);
-                if (!cellProperties._isBaseRendererCalled) {
-                    this.hot.getCellRenderer({
-                        renderer: 'base'
-                    })(...rendererArgs);
-                }
+                renderCell(renderer, rendererArgs);
                 this.hot.runHooks('afterRenderer', TD, visualRowIndex, visualColumnIndex, prop, value, cellProperties);
-                cellProperties._isBaseRendererCalled = false;
             },
             selections: this.hot.selection.highlight,
             hideBorderOnMouseDownOver: ()=>this.settings.fragmentSelection,
@@ -870,6 +937,12 @@ var /**
                 event.preventDefault();
                 this.hot.runHooks('afterOnCellCornerDblClick', event);
             },
+            onSelectionHandleMouseDown: (event, edge)=>{
+                this.hot.runHooks('afterOnSelectionHandleMouseDown', event, edge);
+            },
+            onSelectionEdgeMouseDown: (event, edge)=>{
+                this.hot.runHooks('afterOnSelectionEdgeMouseDown', event, edge);
+            },
             beforeDraw: (force, skipRender)=>this.beforeRender(force, skipRender),
             onDraw: (force)=>this.afterRender(force),
             onBeforeViewportScrollVertically: (renderableRow, snapping)=>{
@@ -1030,8 +1103,41 @@ var /**
             },
             rowHeaderWidth: ()=>this.settings.rowHeaderWidth,
             columnHeaderHeight: ()=>{
-                const columnHeaderHeight = this.hot.runHooks('modifyColumnHeaderHeight');
-                return this.settings.columnHeaderHeight || columnHeaderHeight;
+                const hookHeight = this.hot.runHooks('modifyColumnHeaderHeight');
+                const configured = this.settings.columnHeaderHeight;
+                const probe = this.renderSizeProbe.columnHeaderHeights;
+                // Merge the three provided-height sources per header level: the `columnHeaderHeight` option
+                // (scalar or per-level array), the `modifyColumnHeaderHeight` hook (AutoRowSize), and the
+                // render-size probe (content-driven headers with no plugin). The engine reads this per level.
+                const levels = Math.max(Array.isArray(configured) ? configured.length : 0, probe.size ? Math.max(...probe.keys()) + 1 : 0);
+                if (levels === 0) {
+                    return configured || hookHeight;
+                }
+                const perLevel = [];
+                for(let level = 0; level < levels; level++){
+                    const configuredAtLevel = Array.isArray(configured) ? configured[level] : configured;
+                    // The explicit `columnHeaderHeight` option takes precedence over the
+                    // `modifyColumnHeaderHeight` hook (the legacy `option || hook` semantics — an explicit
+                    // option caps the header and the hook must not override it). The render-size probe may
+                    // still grow the header past that when the actual header content is taller, replacing the
+                    // old oversized-header DOM measurement.
+                    let base;
+                    if (typeof configuredAtLevel === 'number') {
+                        base = configuredAtLevel;
+                    } else if (typeof hookHeight === 'number') {
+                        base = hookHeight;
+                    }
+                    const probeAtLevel = probe.get(level);
+                    const candidates = [];
+                    if (typeof base === 'number') {
+                        candidates.push(base);
+                    }
+                    if (typeof probeAtLevel === 'number') {
+                        candidates.push(probeAtLevel);
+                    }
+                    perLevel[level] = candidates.length ? Math.max(...candidates) : undefined;
+                }
+                return perLevel;
             },
             stylesHandler: ()=>{
                 return this.hot.stylesHandler;
@@ -1120,11 +1226,27 @@ var /**
     /**
    * `afterRender` callback.
    *
+   * The engine fires `onDraw` only from a draw that rendered the cell band, which is what spends the
+   * pending theme-measurement drop: the sizes it invalidated have just been taken again against the
+   * resolved styles (see `#discardSizesMeasuredWithoutStyles`).
+   *
    * @private
    * @param {boolean} force If `true` rendering was triggered by a change of settings or data or `false` if
    *                        rendering was triggered by scrolling or moving selection.
    */ afterRender(force) {
+        _class_private_field_set(this, _sizesMeasuredWithoutStylesPending, false);
         if (force) {
+            // Measure the rendered grid while the DOM is final, before external `afterViewRender` listeners
+            // may mutate it.
+            this.renderSizeProbe.measure(this._wt);
+            // Single-pass header reconcile: the probe has just measured content-driven column-header
+            // heights (which the engine no longer measures mid-draw). If a header is taller than the
+            // default, re-apply the heights so the overlays match the master. This is a synchronous,
+            // hook-free reconcile - it never calls `hot.render()`, so the render-hook counts are unchanged.
+            const defaultRowHeight = this.hot.stylesHandler.getDefaultRowHeight() ?? 0;
+            if (this.renderSizeProbe.hasColumnHeaderTallerThan(defaultRowHeight)) {
+                this._wt.wtOverlays.refreshColumnHeaderHeights();
+            }
             this.hot.runHooks('afterViewRender', this.hot.forceFullRender);
         }
     }
@@ -1228,7 +1350,7 @@ var /**
             }
         }
         if (renderedIndex > -1) {
-            fastInnerHTML(element, String(content(index, headerLevel)), this.hot.getSettings().sanitizer ?? true, 'header', this.hot.rootGridElement ?? undefined);
+            fastInnerHTML(element, String(content(index, headerLevel)), getSanitizer(this.hot), 'header', this.hot.rootElement);
         } else {
             // workaround for https://github.com/handsontable/handsontable/issues/1946
             fastInnerText(element, String.fromCharCode(160));
@@ -1580,6 +1702,8 @@ var /**
    * @param {Hanstontable} hotInstance Instance of {@link Handsontable}.
    */ constructor(hotInstance){
         _class_private_method_init(this, _isSyntheticMouseEvent);
+        _class_private_method_init(this, _isPathWithinGrid);
+        _class_private_method_init(this, _discardSizesMeasuredWithoutStyles);
         _class_private_method_init(this, _getAriaColcount);
         _class_private_method_init(this, _updateAriaColcount);
         _class_private_method_init(this, _updateScrollbarClassNames);
@@ -1591,6 +1715,10 @@ var /**
             writable: true,
             value: void 0
         });
+        _class_private_field_init(this, _sizesMeasuredWithoutStylesPending, {
+            writable: true,
+            value: void 0
+        });
         _class_private_field_init(this, _selectionMouseDown, {
             writable: true,
             value: void 0
@@ -1599,6 +1727,10 @@ var /**
             writable: true,
             value: void 0
         });
+        _class_private_field_init(this, _outsideClickHandled, {
+            writable: true,
+            value: void 0
+        });
         _class_private_field_init(this, _table, {
             writable: true,
             value: void 0
@@ -1633,8 +1765,17 @@ var /**
    * @private
    * @type {boolean}
    */ this.postponedAdjustElementsSize = false;
+        /**
+   * The measurement-only probe of the rendered grid. Runs after each full master draw to record
+   * content-driven row and column-header heights. It does not yet feed those values back into
+   * rendering (see {@link RenderSizeProbe}).
+   *
+   * @type {RenderSizeProbe}
+   */ this.renderSizeProbe = new RenderSizeProbe();
+        _class_private_field_set(this, _sizesMeasuredWithoutStylesPending, false);
         _class_private_field_set(this, _selectionMouseDown, false);
         _class_private_field_set(this, _mouseDown, false);
+        _class_private_field_set(this, _outsideClickHandled, false);
         _class_private_field_set(this, _table, null);
         _class_private_field_set(this, _lastWidth, 0);
         _class_private_field_set(this, _lastHeight, 0);
@@ -1655,6 +1796,31 @@ function isSyntheticMouseEvent(event) {
     }
     return _class_private_field_get(this, _recentTouchEnd);
 }
+function isPathWithinGrid(eventPath) {
+    const { rootElement, rootPortalElement } = this.hot;
+    if (eventPath.includes(rootElement) || !!rootPortalElement && eventPath.includes(rootPortalElement)) {
+        return true;
+    }
+    if (eventPath.some((entry)=>isShadowRoot(entry))) {
+        return false;
+    }
+    return getShadowHostChain(rootElement).some((host)=>eventPath.includes(host));
+}
+function discardSizesMeasuredWithoutStyles() {
+    if (this.hot.stylesHandler.recacheValuesMeasuredWithoutStyles()) {
+        _class_private_field_set(this, _sizesMeasuredWithoutStylesPending, true);
+    }
+    if (!_class_private_field_get(this, _sizesMeasuredWithoutStylesPending)) {
+        return;
+    }
+    // `resetAllOversizedRows` already invalidates the row-height cache, so only the width cache is
+    // left to drop. `invalidateIndexSizesCache()` would invalidate the row heights a second time, and
+    // this is the same pair the engine-side reset performs. Dropping the width cache re-asks
+    // `modifyColWidth`, so a width `AutoColumnSize` measured against no layout comes straight back –
+    // that is the narrow-container follow-up, not this pass.
+    this._wt.wtViewport.resetAllOversizedRows();
+    this.invalidateColumnWidthCache();
+}
 function getAriaColcount() {
     return parseInt(this.hot.rootElement.getAttribute('aria-colcount') ?? '0', 10);
 }

package/themes/engine/index.d.ts

@@ -1,3 +1,4 @@
 export { createTheme, ThemeBuilder } from './builder';
-export { createThemeManager, ThemeManager } from './manager';
+export { createThemeManager, ThemeManager, isThemeOverrideEmpty } from './manager';
+export type { ThemeOverrides } from './manager';
 export type { ThemeConfig, ThemeParams, BaseTheme, ThemeColorScheme, DensityType } from '../types';

package/themes/engine/index.js

@@ -20,6 +20,9 @@ _export(exports, {
     },
     get createThemeManager () {
         return _manager.createThemeManager;
+    },
+    get isThemeOverrideEmpty () {
+        return _manager.isThemeOverrideEmpty;
     }
 });
 const _builder = require("./builder");

package/themes/engine/index.mjs

@@ -1,2 +1,2 @@
 export { createTheme, ThemeBuilder } from './builder.mjs';
-export { createThemeManager, ThemeManager } from './manager.mjs';
+export { createThemeManager, ThemeManager, isThemeOverrideEmpty } from './manager.mjs';

package/themes/engine/manager.d.ts

@@ -1,8 +1,10 @@
-import type { ThemeConfig } from '../types';
+import type { ThemeConfig, ThemeColorScheme, DensityType } from '../types';
 import type { ThemeBuilder } from './builder';
 interface HotInstance {
+    guid: string;
     rootDocument: Document;
     rootWrapperElement: HTMLElement;
+    rootPortalElement: HTMLElement;
     stylesHandler: {
         clearCache(): void;
     };
@@ -11,6 +13,37 @@ interface HotInstance {
     themeManager: ThemeManager | null | undefined;
     [key: string]: unknown;
 }
+/**
+ * Per-instance theme overrides applied on top of the theme configuration.
+ *
+ * They let a single grid pick a color scheme and a density without declaring its own theme, leaving
+ * the shared theme object (and therefore every other grid using it) untouched.
+ */
+export interface ThemeOverrides {
+    colorScheme?: ThemeColorScheme;
+    density?: DensityType;
+}
+/**
+ * Unvalidated theme overrides as they arrive from the grid settings.
+ *
+ * The values are `unknown` because the settings object is an external boundary — `setOverrides()`
+ * validates them and throws on an unsupported value.
+ */
+export interface ThemeOverridesInput {
+    colorScheme?: unknown;
+    density?: unknown;
+}
+/**
+ * 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 declare function isThemeOverrideEmpty(value: unknown): boolean;
 /**
  * ThemeManager class provides methods to manage the theme styles.
  *
@@ -42,16 +75,25 @@ export declare class ThemeManager {
      * @type {object}
      */
     themeConfig: ThemeConfig | null;
+    /**
+     * Class that scopes the per-instance override rules to this grid only. Stamped on the wrapper and
+     * the portal element, so menus and dialogs rendered in the portal follow the same overrides.
+     *
+     * @type {string}
+     */
+    scopeClassName: string;
     /**
      * The theme manager constructor.
      *
      * @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.
      */
-    constructor({ hot, themeObject }: {
+    constructor({ hot, themeObject, overrides }: {
         hot: HotInstance;
         themeObject: ThemeBuilder;
+        overrides?: ThemeOverridesInput;
     });
     /**
      * Gets the theme class name.
@@ -59,6 +101,34 @@ export declare class ThemeManager {
      * @returns {string} The theme class name.
      */
     getClassName(): string;
+    /**
+     * Gets the per-instance color scheme and density overrides.
+     *
+     * @returns {object} A copy of the currently applied overrides.
+     */
+    getOverrides(): ThemeOverrides;
+    /**
+     * 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(): ThemeColorScheme | undefined;
+    /**
+     * 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(): DensityType | undefined;
+    /**
+     * 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: ThemeOverridesInput): boolean;
     /**
      * Updates the theme manager.
      *
@@ -84,10 +154,12 @@ export declare class ThemeManager {
  * @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 declare function createThemeManager({ hot, themeObject }: {
+export declare function createThemeManager({ hot, themeObject, overrides }: {
     hot: HotInstance;
     themeObject: ThemeBuilder;
+    overrides?: ThemeOverridesInput;
 }): ThemeManager;
 export {};