pivotgrid-js 0.1.0

package/dist/pivotgrid.esm.js

@@ -0,0 +1,2867 @@
+/**
+ * Encodes string values of a single column into uint16 indices.
+ * Used inside ColumnStore — one instance per dimension.
+ */
+class DictionaryEncoder {
+  constructor() {
+    this._map     = new Map();  // string → index
+    this._reverse = [];         // index → string
+  }
+
+  /** Returns the numeric index for a value, creating it if needed */
+  encode(value) {
+    const str = String(value);
+    if (!this._map.has(str)) {
+      const idx = this._reverse.length;
+      this._map.set(str, idx);
+      this._reverse.push(str);
+    }
+    return this._map.get(str);
+  }
+
+  /** Restores the string value by index */
+  decode(index) {
+    return this._reverse[index];
+  }
+
+  get size() {
+    return this._reverse.length;
+  }
+}
+/**
+ * Columnar row storage backed by TypedArrays.
+ * Dimensions → Uint16Array (via DictionaryEncoder),
+ * measures   → Float64Array.
+ * ~10× memory savings compared to an array of objects.
+ */
+class ColumnStore {
+  constructor({ dimensions, measures, funcs, capacity }) {
+    this.dimensions = dimensions;
+    this.capacity   = capacity;
+    this.length     = 0;
+
+    // Expand revenue → revenue_sum, revenue_avg...
+    const expandedMeasures = measures.flatMap(m =>
+      funcs.map(fn => `${m}_${fn}`)
+    );
+    this.measures = expandedMeasures;  // overwrite
+
+    // One encoder per dimension
+    this.encoders = {};
+    for (const dim of dimensions) {
+      this.encoders[dim] = new DictionaryEncoder();
+    }
+
+    // Columns: Uint16 for dimensions, Float64 for measures
+    this.dimCols  = {};
+    this.measCols = {};
+    for (const dim of dimensions)       this.dimCols[dim]  = new Uint16Array(capacity);
+    for (const m   of expandedMeasures) this.measCols[m]   = new Float64Array(capacity);
+  }
+
+  /** Returns true if no more rows can be added */
+  isFull() {
+    return this.length >= this.capacity;
+  }
+
+  /**
+   * Appends rows to the store.
+   * Rows beyond capacity are silently discarded.
+   * @param {Object[]} rows
+   * @returns {number} number of rows actually added
+   */
+  append(rows) {
+    const room  = this.capacity - this.length;
+    const batch = rows.length > room ? rows.slice(0, room) : rows;
+
+    for (let i = 0; i < batch.length; i++) {
+      const row = batch[i];
+      const idx = this.length + i;
+      for (const dim of this.dimensions) {
+        this.dimCols[dim][idx] = this.encoders[dim].encode(row[dim]);
+      }
+      for (const m of this.measures) {
+        this.measCols[m][idx] = Number(row[m]) || 0;
+      }
+    }
+
+    this.length += batch.length;
+    return batch.length;
+  }
+
+  /**
+   * Returns an iterable view of rows without materialising
+   * the full object array — Aggregator traverses data on-the-fly.
+   * Supports for…of, .forEach and .length.
+   */
+  rows() {
+    const { dimensions, measures, dimCols, measCols, encoders, length } = this;
+
+    const iterable = {
+      length,
+
+      forEach(fn) {
+        for (let i = 0; i < length; i++) {
+          const row = {};
+          for (const dim of dimensions) row[dim] = encoders[dim].decode(dimCols[dim][i]);
+          for (const m   of measures)   row[m]   = measCols[m][i];
+          fn(row, i);
+        }
+      },
+
+      [Symbol.iterator]() {
+        let i = 0;
+        return {
+          next() {
+            if (i >= length) return { done: true, value: undefined };
+            const row = {};
+            for (const dim of dimensions) row[dim] = encoders[dim].decode(dimCols[dim][i]);
+            for (const m   of measures)   row[m]   = measCols[m][i];
+            i++;
+            return { done: false, value: row };
+          }
+        };
+      }
+    };
+
+    return iterable;
+  }
+}
+/**
+ * Aggregator
+ *
+ * Builds the pivot structure from aggRows.
+ * Supports fieldDefs for correct sorting of dates and lookup fields.
+ *
+ * Usage:
+ *   const agg = new Aggregator();
+ *
+ *   const result = agg.build({
+ *     rows:      ['region', 'month'],
+ *     columns:   ['channel'],
+ *     measure:   'revenue',
+ *     func:      'sum',
+ *     aggRows,
+ *     fieldDefs: {
+ *       region: { label: 'region' },
+ *       month:  { label: 'month_name', sortKey: 'month_num' },
+ *     },
+ *   });
+ */
+
+class Aggregator {
+
+  build({ rows, columns, measure, func, aggRows, fieldDefs = {} }) {
+    const measureKey = `${measure}_${func}`;
+    const cells      = new Map();
+    let grandTotal   = 0;
+    const hasColumns = columns && columns.length > 0;
+
+    // Pre-compute label and sortKey once, outside the loop
+    const rowCols  = rows.map(f => (fieldDefs[f] || {}).label || f);
+    const rowSorts = rows.map(f => (fieldDefs[f] || {}).sortKey || null);
+    const colCols  = hasColumns ? columns.map(f => (fieldDefs[f] || {}).label || f) : [];
+    const colSorts = hasColumns ? columns.map(f => (fieldDefs[f] || {}).sortKey || null) : [];
+
+    const rowDepth   = rows.length;
+    const colDepth   = colCols.length;
+    const rowKeysBuf = new Array(rowDepth);
+    const colKeysBuf = new Array(colDepth);
+
+    // Build tree roots inline — no extra passes over aggRows needed
+    const rowRoot = new Map();
+    const colRoot = new Map();
+
+    for (const row of aggRows) {
+      const val = Number(row[measureKey]) || 0;
+      grandTotal += val;
+
+      // Row keys + row tree in a single pass
+      let rNode = rowRoot;
+      for (let d = 0; d < rowDepth; d++) {
+        const v       = String(row[rowCols[d]] ?? '');
+        const sortVal = rowSorts[d] ? row[rowSorts[d]] : v;
+        rowKeysBuf[d] = d === 0 ? v : rowKeysBuf[d - 1] + '→' + v;
+        if (!rNode.has(v)) rNode.set(v, { sortKey: sortVal, children: new Map() });
+        rNode = rNode.get(v).children;
+      }
+
+      // Column keys + column tree in a single pass
+      if (hasColumns) {
+        let cNode = colRoot;
+        for (let d = 0; d < colDepth; d++) {
+          const v       = String(row[colCols[d]] ?? '');
+          const sortVal = colSorts[d] ? row[colSorts[d]] : v;
+          colKeysBuf[d] = d === 0 ? v : colKeysBuf[d - 1] + '→' + v;
+          if (!cNode.has(v)) cNode.set(v, { sortKey: sortVal, children: new Map() });
+          cNode = cNode.get(v).children;
+        }
+      }
+
+      // Accumulate cell values
+      for (let d = 0; d < rowDepth; d++) {
+        const rk = rowKeysBuf[d];
+        if (hasColumns) {
+          for (let cd = 0; cd < colDepth; cd++) {
+            const key = rk + '||' + colKeysBuf[cd];
+            cells.set(key, (cells.get(key) || 0) + val);
+          }
+        }
+        const totalKey = rk + '||__total__';
+        cells.set(totalKey, (cells.get(totalKey) || 0) + val);
+      }
+
+      if (hasColumns) {
+        for (let cd = 0; cd < colDepth; cd++) {
+          const gtKey = '__grand__||' + colKeysBuf[cd];
+          cells.set(gtKey, (cells.get(gtKey) || 0) + val);
+        }
+      }
+    }
+
+    // Map trees → node arrays
+    const toNodes = (map, depth, parentKey, maxDepth) =>
+      [...map.entries()]
+        .sort(([, a], [, b]) => {
+          const av = a.sortKey, bv = b.sortKey;
+          if (av !== bv && !isNaN(Number(av)) && !isNaN(Number(bv))) return Number(av) - Number(bv);
+          return String(av).localeCompare(String(bv), 'ru');
+        })
+        .map(([val, data]) => {
+          const code     = parentKey ? parentKey + '→' + val : val;
+          const children = depth + 1 < maxDepth
+            ? toNodes(data.children, depth + 1, code, maxDepth)
+            : null;
+          return { value: val, code, depth, children };
+        });
+
+    const tree    = toNodes(rowRoot, 0, '', rowDepth);
+    const colTree = hasColumns ? toNodes(colRoot, 0, '', colDepth) : null;
+    const colKeys = hasColumns ? this._flattenColTree(colTree) : [];
+
+    return { cells, colKeys, colTree, tree, grandTotal };
+  }
+
+  // ── Get the label value for a field from a row ───────────────────────────
+
+  _labelVal(row, field, fieldDefs) {
+    const def = fieldDefs[field] || {};
+    return String(row[def.label || field] ?? '');
+  }
+
+  // ── Tree ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Builds the tree in a single pass over aggRows.
+   * Groups by label, sorts by sortKey (if present).
+   */
+  _buildTree(aggRows, levels, fieldDefs = {}) {
+    if (!levels.length) return null;
+
+    // Map<labelValue, { sortKey: value, children: Map }>
+    const root = new Map();
+
+    for (const row of aggRows) {
+      let node = root;
+      for (let d = 0; d < levels.length; d++) {
+        const field    = levels[d];
+        const def      = fieldDefs[field] || {};
+        const labelCol = def.label   || field;
+        const sortCol  = def.sortKey || null;
+        const labelVal = String(row[labelCol] ?? '');
+        const sortVal  = sortCol ? row[sortCol] : labelVal;
+
+        if (!node.has(labelVal)) {
+          node.set(labelVal, { sortKey: sortVal, children: new Map() });
+        }
+        node = node.get(labelVal).children;
+      }
+    }
+
+    // Recursively convert Map → node tree
+    const toNodes = (map, depth, parentKey) => {
+      return [...map.entries()]
+        .sort(([, aData], [, bData]) => {
+          const a = aData.sortKey;
+          const b = bData.sortKey;
+          // Numeric sort if both values are numbers
+          if (a !== b && !isNaN(Number(a)) && !isNaN(Number(b))) {
+            return Number(a) - Number(b);
+          }
+          return String(a).localeCompare(String(b), 'ru');
+        })
+        .map(([val, data]) => {
+          const code     = parentKey ? parentKey + '→' + val : val;
+          const children = depth + 1 < levels.length
+            ? toNodes(data.children, depth + 1, code)
+            : null;
+          return { value: val, code, depth, children };
+        });
+    };
+
+    return toNodes(root, 0, '');
+  }
+
+  // Flat list of all column tree nodes
+  _flattenColTree(nodes) {
+    const result = [];
+    const walk = (nodes) => {
+      for (const node of nodes) {
+        result.push({
+          code:        node.code,
+          label:       node.value,
+          depth:       node.depth,
+          hasChildren: !!node.children,
+        });
+        if (node.children) walk(node.children);
+      }
+    };
+    walk(nodes);
+    return result;
+  }
+}
+
+/**
+ * ArrayProvider
+ *
+ * Provider for local array data.
+ * Implements the same interface as RestProvider —
+ * used for demo mode without a server.
+ */
+class ArrayProvider {
+
+  constructor({ data, dimensions, measures, funcs, fields = {},
+                cachedDimensions = [], maxCachedRows = 500_000,
+                drillthroughQuery = null }) {
+    this.data              = data;
+    this.dimensions        = dimensions;
+    this.measures          = measures;
+    this.funcs             = funcs;
+    this.fields            = fields;
+    this.maxCachedRows     = maxCachedRows;
+    this.drillthroughQuery = drillthroughQuery;
+
+    this._cachedDims = [...cachedDimensions];
+    this._store      = null;
+    this._cacheRows  = 0;
+  }
+
+  // ── Cache API ──────────────────────────────────────────────────────────────
+
+  async prefetch() {
+    this._store     = null;
+    this._cacheRows = 0;
+    if (!this._cachedDims.length) return;
+
+    const aggRows   = this._groupBy(this._cachedDims);
+    this._store     = this._makeStore(this._cachedDims, aggRows);
+    this._cacheRows = aggRows.length;
+  }
+
+  async countRows(logicalFields) {
+    if (!logicalFields.length) return 0;
+    const keys = new Set();
+    for (const row of this.data) {
+      keys.add(logicalFields.map(f => this._val(row, f)).join('|'));
+    }
+    return keys.size;
+  }
+
+  async refreshCache(newDims) {
+    this._cachedDims = [...newDims];
+    await this.prefetch();
+  }
+
+  get cachedDimensions() { return [...this._cachedDims]; }
+  get cacheRows()        { return this._cacheRows; }
+
+  // ── Grid data ─────────────────────────────────────────────────────────────
+
+  getBestRows(requiredDims = [], activeFilters = {}) {
+    if (!this._store) return null;
+
+    const hasAllRequired = requiredDims.every(dim => {
+      const col = (this.fields[dim] || {}).label || dim;
+      return this._store.dimensions.includes(col);
+    });
+    if (!hasAllRequired) return null;
+
+    const filterDims = Object.keys(activeFilters);
+    const hasAllFilterDims = filterDims.every(dim => {
+      const col = (this.fields[dim] || {}).label || dim;
+      return this._store.dimensions.includes(col);
+    });
+    if (!hasAllFilterDims) return null;
+
+    const rows = this._store.rows();
+    return filterDims.length > 0
+      ? this._filterRows(rows, activeFilters)
+      : rows;
+  }
+
+  async getRowsForDims(requiredDims, activeFilters = {}) {
+    const cached = this.getBestRows(requiredDims, activeFilters);
+    if (cached) return { rows: cached, fromCache: true };
+
+    const rows = this._groupBy(requiredDims, activeFilters);
+    return { rows, fromCache: false };
+  }
+
+  // ── Drillthrough ───────────────────────────────────────────────────────────
+
+  async countDistinct(logicalField) {
+    const col  = (this.fields[logicalField] || {}).label || logicalField;
+    const vals = new Set(this.data.map(r => String(r[col] ?? '')));
+    return vals.size;
+  }
+
+  async getDistinctValues(logicalField) {
+    const def     = this.fields[logicalField] || {};
+    const col     = def.label   || logicalField;
+    const sortCol = def.sortKey || col;
+    const vals    = [...new Set(this.data.map(r => String(r[col] ?? '')))];
+    return vals.sort((a, b) => {
+      const av = this.data.find(r => String(r[col]) === a)?.[sortCol];
+      const bv = this.data.find(r => String(r[col]) === b)?.[sortCol];
+      if (av !== undefined && bv !== undefined && !isNaN(Number(av)) && !isNaN(Number(bv))) {
+        return Number(av) - Number(bv);
+      }
+      return String(av ?? a).localeCompare(String(bv ?? b), 'ru');
+    });
+  }
+
+  async drillthrough({ filters = {}, limit = 200 }) {
+    let rows = this.data;
+
+    // Apply filters
+    for (const [dim, val] of Object.entries(filters)) {
+      const col = (this.fields[dim] || {}).label || dim;
+      rows = rows.filter(r => String(r[col] ?? '') === String(val));
+    }
+
+    return rows.slice(0, limit);
+  }
+
+  // ── Aggregation ───────────────────────────────────────────────────────────
+
+  _groupBy(logicalFields, activeFilters = {}) {
+    // Filter source data
+    let data = this.data;
+    if (Object.keys(activeFilters).length) {
+      data = this._filterRawRows(data, activeFilters);
+    }
+
+    const cols   = logicalFields.map(f => (this.fields[f] || {}).label || f);
+    const groups = new Map();
+
+    for (const row of data) {
+      const key = cols.map(c => String(row[c] ?? '')).join('|§|');
+      if (!groups.has(key)) {
+        const entry = {};
+        for (const col of cols) entry[col] = row[col];
+        // Add sortKey columns if present
+        for (const f of logicalFields) {
+          const def = this.fields[f] || {};
+          if (def.sortKey) entry[def.sortKey] = row[def.sortKey];
+        }
+        // Initialize aggregates
+        for (const m of this.measures) {
+          for (const fn of this.funcs) {
+            entry[`${m}_${fn}`]    = fn === 'min' ? Infinity : fn === 'max' ? -Infinity : 0;
+          }
+          entry[`__count_${m}`] = 0;
+          entry[`__sum2_${m}`]  = 0;
+        }
+        groups.set(key, entry);
+      }
+      const entry = groups.get(key);
+      for (const m of this.measures) {
+        const v = Number(row[m]) || 0;
+        entry[`__count_${m}`]++;
+        entry[`${m}_sum`]  = (entry[`${m}_sum`]  || 0) + v;
+        entry[`${m}_count`]= entry[`__count_${m}`];
+        entry[`${m}_min`]  = Math.min(entry[`${m}_min`] ?? Infinity, v);
+        entry[`${m}_max`]  = Math.max(entry[`${m}_max`] ?? -Infinity, v);
+        entry[`__sum2_${m}`] += v * v;
+      }
+    }
+
+    // Compute avg, stddev, variance
+    for (const entry of groups.values()) {
+      for (const m of this.measures) {
+        const n   = entry[`__count_${m}`] || 1;
+        const sum = entry[`${m}_sum`] || 0;
+        const sum2= entry[`__sum2_${m}`] || 0;
+        entry[`${m}_avg`]      = sum / n;
+        const variance          = sum2 / n - (sum / n) ** 2;
+        entry[`${m}_variance`] = variance;
+        entry[`${m}_stddev`]   = Math.sqrt(Math.max(0, variance));
+        delete entry[`__count_${m}`];
+        delete entry[`__sum2_${m}`];
+      }
+    }
+
+    return [...groups.values()];
+  }
+
+  _filterRawRows(data, activeFilters) {
+    const predicates = [];
+    for (const [dim, filter] of Object.entries(activeFilters)) {
+      const col = (this.fields[dim] || {}).label || dim;
+      if (filter.values && filter.values.length > 0) {
+        const valSet = new Set(filter.values);
+        predicates.push(row => valSet.has(String(row[col] ?? '')));
+      }
+      if (filter.searchText) {
+        const text = filter.searchText.toLowerCase();
+        predicates.push(filter.searchType === 'starts_with'
+          ? row => String(row[col] ?? '').toLowerCase().startsWith(text)
+          : row => String(row[col] ?? '').toLowerCase().includes(text)
+        );
+      }
+    }
+    if (!predicates.length) return data;
+    return data.filter(row => predicates.every(p => p(row)));
+  }
+
+  _filterRows(rows, activeFilters) {
+    const predicates = [];
+    for (const [dim, filter] of Object.entries(activeFilters)) {
+      const col = (this.fields[dim] || {}).label || dim;
+      if (filter.values && filter.values.length > 0) {
+        const valSet = new Set(filter.values);
+        predicates.push(row => valSet.has(String(row[col] ?? '')));
+      }
+      if (filter.searchText) {
+        const text = filter.searchText.toLowerCase();
+        predicates.push(filter.searchType === 'starts_with'
+          ? row => String(row[col] ?? '').toLowerCase().startsWith(text)
+          : row => String(row[col] ?? '').toLowerCase().includes(text)
+        );
+      }
+    }
+    if (!predicates.length) return rows;
+    const filtered = [];
+    for (const row of rows) {
+      if (predicates.every(p => p(row))) filtered.push(row);
+    }
+    return filtered;
+  }
+
+  // ── Helpers ────────────────────────────────────────────────────────────────
+
+  _val(row, logicalField) {
+    const col = (this.fields[logicalField] || {}).label || logicalField;
+    return String(row[col] ?? '');
+  }
+
+  _makeStore(logicalFields, rows) {
+    const dims  = logicalFields.map(f => (this.fields[f] || {}).label || f);
+    // Add sortKey columns
+    for (const f of logicalFields) {
+      const def = this.fields[f] || {};
+      if (def.sortKey && !dims.includes(def.sortKey)) dims.push(def.sortKey);
+    }
+    const store = new ColumnStore({
+      dimensions: dims,
+      measures:   this.measures,
+      funcs:      this.funcs,
+      capacity:   this.maxCachedRows,
+    });
+    store.append(rows);
+    return store;
+  }
+
+  async load() {
+    throw new Error('Use prefetch() / getRowsForDims() / drillthrough()');
+  }
+}
+
+/**
+ * RestProvider
+ *
+ * Caching strategy:
+ *   - On startup, one GROUP BY over cachedDimensions → cache (ColumnStore)
+ *   - Everything else is lazy, not cached
+ *   - countRows(dims) → COUNT query for UI validation before adding to cache
+ *   - refreshCache(dims) → clear cache + new GROUP BY
+ */
+class RestProvider {
+
+  constructor({ url, query, dimensions, measures, funcs, fields = {},
+    cachedDimensions = [], maxCachedRows = 500_000, drillthroughQuery = null }) {
+    this.url = url;
+    this.query = query;
+    this.dimensions = dimensions;
+    this.measures = measures;
+    this.funcs = funcs;
+    this.fields = fields;
+    this.maxCachedRows = maxCachedRows;
+
+    this._cachedDims = [...cachedDimensions];
+    this._store = null;  // single ColumnStore cache
+    this._cacheRows = 0;     // rows in cache after last prefetch
+
+    this.drillthroughQuery = drillthroughQuery;
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  /**
+   * Initial load: one GROUP BY over cachedDimensions.
+   * Does nothing if the list is empty.
+   */
+  async prefetch() {
+    this._store = null;
+    this._cacheRows = 0;
+
+    if (!this._cachedDims.length) return;
+
+    const rows = await this._fetchGroupBy(this._cachedDims);
+    this._store = this._makeStore(this._cachedDims, rows);
+    this._cacheRows = rows.length;
+  }
+
+  /**
+   * COUNT of rows for a GROUP BY over the given set of dimensions.
+   * Used by CacheManager to validate before adding a dimension to cache.
+   * @param {string[]} logicalFields — logical field names (from CONFIG.dimensions)
+   * @returns {Promise<number>}
+   */
+  async countRows(logicalFields) {
+    if (!logicalFields.length) return 0;
+    const cols = this._expandFields(logicalFields).join(', ');
+    const sql = `
+      SELECT COUNT(*) AS cnt
+      FROM (
+        SELECT ${cols}
+        FROM   (${this.query}) _t
+        GROUP  BY ${cols}
+      ) _g
+    `;
+    const rows = await this._execute(sql);
+    return Number(rows[0]?.cnt || 0);
+  }
+
+  /**
+   * Clears the cache and reloads GROUP BY over the new set of dimensions.
+   * Called by the "Refresh cache" button.
+   */
+  async refreshCache(newDims) {
+    this._cachedDims = [...newDims];
+    await this.prefetch();
+  }
+
+  /** Current list of cached dimensions. */
+  get cachedDimensions() { return [...this._cachedDims]; }
+
+  /** Number of rows in cache (updated after prefetch/refreshCache). */
+  get cacheRows() { return this._cacheRows; }
+
+  // ── Grid data ────────────────────────────────────────────────────────────────
+
+  /**
+   * Returns iterable rows from cache if the cache covers requiredDims.
+   * Otherwise returns null.
+   */
+  getBestRows(requiredDims = [], activeFilters = {}) {
+    if (!this._store) return null;
+
+    const hasAllRequired = requiredDims.every(dim => {
+      const col = (this.fields[dim] || {}).label || dim;
+      return this._store.dimensions.includes(col);
+    });
+    if (!hasAllRequired) return null;
+
+    // If any filter dimension is missing from store — fall back to lazy SQL with WHERE
+    const filterDims = Object.keys(activeFilters);
+    const hasAllFilterDims = filterDims.every(dim => {
+      const col = (this.fields[dim] || {}).label || dim;
+      return this._store.dimensions.includes(col);
+    });
+    if (!hasAllFilterDims) return null;
+
+    const rows = this._store.rows();
+    return filterDims.length > 0
+      ? this._filterRows(rows, activeFilters)
+      : rows;
+  }
+
+  async getRowsForDims(requiredDims, activeFilters = {}) {
+    const cached = this.getBestRows(requiredDims, activeFilters);
+    if (cached) return { rows: cached, fromCache: true };
+
+    const rows = await this._fetchGroupBy(requiredDims, activeFilters);
+    return { rows, fromCache: false };
+  }
+
+  /**
+   * Filters rows from cache by active filters (no server request).
+   */
+  _filterRows(rows, activeFilters) {
+    const predicates = [];
+    for (const [dim, filter] of Object.entries(activeFilters)) {
+      const col = (this.fields[dim] || {}).label || dim;
+      if (filter.values && filter.values.length > 0) {
+        const valSet = new Set(filter.values);
+        predicates.push(row => valSet.has(String(row[col] ?? '')));
+      }
+      if (filter.searchText) {
+        const text = filter.searchText.toLowerCase();
+        predicates.push(filter.searchType === 'starts_with'
+          ? row => String(row[col] ?? '').toLowerCase().startsWith(text)
+          : row => String(row[col] ?? '').toLowerCase().includes(text)
+        );
+      }
+    }
+    if (!predicates.length) return rows;
+
+    // Materialise into array — stable and predictable
+    const filtered = [];
+    for (const row of rows) {
+      if (predicates.every(p => p(row))) filtered.push(row);
+    }
+    return filtered;
+  }
+
+  // ── Drillthrough ───────────────────────────────────────────────────────────
+
+  async countDistinct(logicalField) {
+    const col = (this.fields[logicalField] || {}).label || logicalField;
+    const sql = `SELECT COUNT(DISTINCT ${col}) AS cnt FROM (${this.query}) _t`;
+    const rows = await this._execute(sql);
+    return Number(rows[0]?.cnt || 0);
+  }
+
+  async getDistinctValues(logicalField) {
+    const def = this.fields[logicalField] || {};
+    const col = def.label || logicalField;
+    const sortCol = def.sortKey || col;
+    const sql = sortCol !== col
+      ? `SELECT DISTINCT ${col}, ${sortCol} FROM (${this.query}) _t ORDER BY ${sortCol}`
+      : `SELECT DISTINCT ${col} FROM (${this.query}) _t ORDER BY ${sortCol}`;
+    const rows = await this._execute(sql);
+    return rows.map(r => String(r[col] ?? ''));
+  }
+
+  async drillthrough({ filters = {} }) {
+    const where = this._buildWhere(filters);
+    const sql = this.drillthroughQuery
+      ? this.drillthroughQuery.replace('{filters}', where ? where.replace('WHERE ', '') : '1=1')
+      : `SELECT * FROM (${this.query}) _t ${where} LIMIT 200`;
+    return this._execute(sql);
+  }
+
+  // ── SQL helpers ────────────────────────────────────────────────────────────
+
+  _fetchGroupBy(logicalFields, activeFilters = {}) {
+    const select = [];
+    const groupBy = [];
+    const orderBy = [];
+
+    for (const field of logicalFields) {
+      const def = this.fields[field] || {};
+      if (def.sortKey) {
+        select.push(def.sortKey, def.label);
+        groupBy.push(def.sortKey, def.label);
+        orderBy.push(def.sortKey);
+      } else {
+        const col = def.label || field;
+        select.push(col);
+        groupBy.push(col);
+        orderBy.push(col);
+      }
+    }
+
+    const aggExprs = this.measures.flatMap(m =>
+      this.funcs.map(fn => `${fn.toUpperCase()}(${m}) AS ${m}_${fn}`)
+    ).join(', ');
+
+    const where = this._buildFiltersWhere(activeFilters);
+
+    const sql = `
+      SELECT ${[...select, aggExprs].join(', ')}
+      FROM   (${this.query}) _t
+      ${where}
+      GROUP  BY ${groupBy.join(', ')}
+      ORDER  BY ${orderBy.join(', ')}
+    `;
+
+    return this._execute(sql);
+  }
+
+  /** Builds a WHERE clause for active filters (for SQL queries). */
+  _buildFiltersWhere(activeFilters = {}) {
+    const conditions = [];
+    for (const [dim, filter] of Object.entries(activeFilters)) {
+      const col = (this.fields[dim] || {}).label || dim;
+
+      if (filter.values && filter.values.length > 0) {
+        const vals = filter.values
+          .map(v => `'${String(v).replace(/'/g, "''")}'`)
+          .join(', ');
+        conditions.push(`${col} IN (${vals})`);
+      }
+
+      if (filter.searchText) {
+        const esc = filter.searchText.replace(/'/g, "''");
+        conditions.push(filter.searchType === 'starts_with'
+          ? `${col} ILIKE '${esc}%'`
+          : `${col} ILIKE '%${esc}%'`
+        );
+      }
+    }
+    return conditions.length ? 'WHERE ' + conditions.join(' AND ') : '';
+  }
+
+  /** Expands logical field names into real DB column names. */
+  _expandFields(logicalFields) {
+    const cols = [];
+    for (const field of logicalFields) {
+      const def = this.fields[field] || {};
+      if (def.sortKey) cols.push(def.sortKey);
+      cols.push(def.label || field);
+    }
+    return cols;
+  }
+
+  _makeStore(logicalFields, rows) {
+    const dims = this._expandFields(logicalFields);
+    const store = new ColumnStore({
+      dimensions: dims,
+      measures: this.measures,
+      funcs: this.funcs,
+      capacity: this.maxCachedRows,
+    });
+    store.append(rows);
+    return store;
+  }
+
+  _buildWhere(filters) {
+    const keys = Object.keys(filters);
+    if (!keys.length) return '';
+    return 'WHERE ' + keys.map(k => {
+      const def = this.fields[k] || {};
+      const col = def.label || k;
+      return `${col} = '${String(filters[k]).replace(/'/g, "''")}'`;
+    }).join(' AND ');
+  }
+
+  // ── HTTP ───────────────────────────────────────────────────────────────────
+
+  async _execute(query) {
+    const res = await fetch(this.url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ query }),
+    });
+
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(`Server error ${res.status}: ${err.error || ''}`);
+    }
+
+    const rows = await res.json();
+    return rows.map(row => {
+      const out = {};
+      for (const k of Object.keys(row)) out[k.toLowerCase()] = row[k];
+      return out;
+    });
+  }
+
+  async load() {
+    throw new Error('Use prefetch() / getRowsForDims() / drillthrough()');
+  }
+}
+
+/**
+ * PivotGrid — vanilla JS
+ * v0.3 — hierarchical columns, absolute-positioned headers
+ */
+
+class PivotGrid {
+
+  static ROW_HEIGHT = 24;
+  static HEADER_HEIGHT = 32;
+  static COL_HEADER_W = 200;
+  static COL_W = 150;
+  static INDENT = 16;
+  static BUFFER = 5;
+
+  /**
+   * @param {object}   options
+   * @param {Element}  options.container  — DOM element to render into
+   * @param {object}   options.result     — aggregation result from Aggregator.build()
+   * @param {string[]} options.rows       — active row dimension names
+   * @param {string[]} options.columns    — active column dimension names
+   * @param {string}   options.measure    — active measure name
+   * @param {object}   [options.fieldDefs={}] — field definitions (label, title, sortKey)
+   * @param {object}   [options.labels={}]    — translated UI strings (total, confirmLargeExpand)
+   */
+  constructor({ container, result, rows, columns, measure, fieldDefs = {}, labels = {} }) {
+    this.container = container;
+    this.rows = rows;
+    this.columns = columns;
+    this.measure = measure;
+    this.fieldDefs = fieldDefs;
+    this._labels = labels;
+    this._measureKey = measure + '_sum'; // updated via setMeasure()
+    this._colHeaderW = PivotGrid.COL_HEADER_W;
+    this._hideSubtotals = false;
+
+    this.collapsed = new Set();
+    this.collapsedCols = new Set();
+    this.rowPool = [];
+    this.rendered = new Map();
+
+    this._applyResult(result);
+    this._mount();
+    this._renderVisible();
+    this._bindScroll();
+  }
+
+  // ── Apply Result ────────────────────────────────────────────────────
+
+  /** Applies an aggregation result object and rebuilds flat rows/cols. */
+  _applyResult(result) {
+    this.cells = result.cells;
+    this.colTree = result.colTree;
+    this.colKeys = result.colKeys;
+    this.tree = result.tree;
+    this.grandTotal = result.grandTotal;
+    if (result.measureKey) this._measureKey = result.measureKey;
+    this._buildFlatCols();
+    this._buildFlatRows();
+  }
+
+  // ── Flat list of visible columns ────────────────────────────────────────
+
+  /** Builds this.flatCols — the ordered list of visible leaf/subtotal column entries. */
+  _buildFlatCols() {
+    if (!this.colTree || !this.colTree.length) {
+      this.flatCols = [];
+      return;
+    }
+
+    const result = [];
+    const multiLevel = this.columns && this.columns.length > 1;
+
+    const walk = (nodes) => {
+      for (const node of nodes) {
+        if (node.children) {
+          if (this.collapsedCols.has(node.code)) {
+            result.push({ code: node.code, label: node.value, isSubtotal: true, collapsed: true });
+          } else {
+            walk(node.children);
+            if (multiLevel && !this._hideSubtotals) {
+              result.push({ code: node.code, label: '∑', isSubtotal: true, collapsed: false });
+            }
+          }
+        } else {
+          result.push({ code: node.code, label: node.value, isSubtotal: false });
+        }
+      }
+    };
+
+    walk(this.colTree);
+    this.flatCols = result;
+  }
+
+  /**
+   * Number of flatCols occupied by a node (recursive, respects collapsed state).
+   */
+  _getGroupSpan(node) {
+    if (!node.children || this.collapsedCols.has(node.code)) return 1;
+    const multiLevel = this.columns && this.columns.length > 1;
+    let span = (multiLevel && !this._hideSubtotals) ? 1 : 0;
+    for (const child of node.children) {
+      span += this._getGroupSpan(child);
+    }
+    return span;
+  }
+
+  /**
+   * Depth of the column tree, accounting for collapsed nodes.
+   */
+  _colTreeDepth() {
+    if (!this.colTree || !this.colTree.length) return 1;
+    const walk = (nodes) => {
+      let max = 0;
+      for (const node of nodes) {
+        if (node.children && !this.collapsedCols.has(node.code)) {
+          max = Math.max(max, 1 + walk(node.children));
+        }
+      }
+      return max;
+    };
+    return 1 + walk(this.colTree);
+  }
+
+  // ── Flat list of strings ──────────────────────────────────────────────────
+
+  /** Builds this.flatRows — flat array of visible row nodes including grand total. */
+  _buildFlatRows() {
+    this.flatRows = [];
+    const walk = (nodes) => {
+      for (const node of nodes) {
+        this.flatRows.push(node);
+        if (node.children && !this.collapsed.has(node.code)) {
+          walk(node.children);
+        }
+      }
+    };
+    if (this.tree) walk(this.tree);
+    this.flatRows.push({ isGrandTotal: true });
+  }
+
+  /** Total header height in px (HEADER_HEIGHT × column tree depth). */
+  get _headerHeight() {
+    return PivotGrid.HEADER_HEIGHT * this._colTreeDepth();
+  }
+
+  // ── Mounting ───────────────────────────────────────────────────────────
+
+  /** Clears the container and mounts the column header + scroll area. */
+  _mount() {
+    this.container.innerHTML = '';
+    this.container.classList.add('pg-root');
+
+    const cols = this.flatCols.length ? this.flatCols : this.colKeys;
+    this.totalWidth = this._colHeaderW + (cols.length + 1) * PivotGrid.COL_W;
+
+    this._mountColHeader();
+    this._mountScrollArea();
+  }
+
+  /** Builds and appends the absolute-positioned column header element. */
+  _mountColHeader() {
+    const RH = PivotGrid.HEADER_HEIGHT;
+    const C = this._colHeaderW;
+    const W = PivotGrid.COL_W;
+    const totalDepth = this._colTreeDepth();
+    const H = RH * totalDepth;
+
+    this.headerEl = document.createElement('div');
+    this.headerEl.className = 'pg-col-header';
+    this.headerEl.style.cssText = `
+      position: absolute; top: 0; left: 0;
+      width: ${this.totalWidth}px; height: ${H}px;
+      background: #fafafa; border-bottom: 1px solid #d0d0d0; z-index: 10;
+    `;
+
+    // Row label — full height
+    const rowLabelCell = this._absCell({
+      x: 0, y: 0, w: C, h: H,
+      text: '',
+      cls: 'row-label',
+    });
+
+    this.rows.forEach((row, i) => {
+      const span = document.createElement('span');
+      const def = (this.fieldDefs || {})[row] || {};
+      span.textContent = def.title || def.label || row;
+      span.style.cssText = 'cursor:pointer; padding: 0 2px;';
+      span.title = `Expand to "${row}"`;
+      if (i < this.rows.length - 1) {
+        span.addEventListener('click', () => this.expandToDepth(i + 1));
+      } else {
+        span.style.cursor = 'default';
+      }
+      if (i > 0) {
+        const sep = document.createElement('span');
+        sep.textContent = ' › ';
+        sep.style.color = '#ccc';
+        rowLabelCell.appendChild(sep);
+      }
+      rowLabelCell.appendChild(span);
+    });
+
+    // Resize handle for the first column
+    const resizeHandle = document.createElement('div');
+    resizeHandle.className = 'pg-col-resize-handle';
+    resizeHandle.style.cssText = `
+      position: absolute; top: 0; left: ${C - 4}px;
+      width: 8px; height: ${H}px;
+      cursor: col-resize; z-index: 20;
+    `;
+    this.headerEl.appendChild(resizeHandle);
+    this._bindResizeHandle(resizeHandle);
+
+    // Columns
+    if (this.colTree && this.colTree.length) {
+      let offset = 0;
+      for (const node of this.colTree) {
+        offset = this._renderColNode(node, 0, offset, totalDepth);
+      }
+    }
+
+    // Total — full height
+    const cols = this.flatCols.length ? this.flatCols : this.colKeys;
+    this._absCell({
+      x: C + cols.length * W,
+      y: 0,
+      w: W,
+      h: H,
+      text: this._labels.total || 'Total',
+      cls: 'total-col',
+    });
+
+    this.container.appendChild(this.headerEl);
+  }
+
+  /**
+   * Recursively renders a column header cell with absolute positioning.
+   * Returns the new leafOffset.
+   */
+  _renderColNode(node, level, leafOffset, totalDepth) {
+    const RH = PivotGrid.HEADER_HEIGHT;
+    const C = this._colHeaderW;
+    const W = PivotGrid.COL_W;
+    const collapsed = this.collapsedCols.has(node.code);
+    const isLeaf = !node.children;
+    const span = this._getGroupSpan(node);
+
+    // Листья и свёрнутые растягиваются до конца заголовка
+    const cellH = (isLeaf || collapsed)
+      ? (totalDepth - level) * RH
+      : RH;
+
+    const cls = collapsed ? 'subtotal-col'
+      : isLeaf ? ''
+        : 'pg-col-header-group';
+
+    const cell = this._absCell({
+      x: C + leafOffset * W,
+      y: level * RH,
+      w: span * W,
+      h: cellH,
+      text: node.value,
+      cls,
+    });
+
+    // Collapse toggle button
+    if (node.children) {
+      const toggle = document.createElement('span');
+      toggle.className = 'pg-toggle' + (collapsed ? ' collapsed' : '');
+      toggle.textContent = '▾';
+      toggle.addEventListener('click', (e) => {
+        e.stopPropagation();
+        this._toggleColCollapse(node.code);
+      });
+      cell.insertBefore(toggle, cell.firstChild);
+    }
+
+    if (!isLeaf && !collapsed) {
+      // Render children
+      let childOffset = leafOffset;
+      for (const child of node.children) {
+        childOffset = this._renderColNode(child, level + 1, childOffset, totalDepth);
+      }
+
+      // ∑ for group — starts one level down, stretches to the end
+      if (this.columns && this.columns.length > 1 && !this._hideSubtotals) {
+        const subtotalH = (totalDepth - level - 1) * RH;
+        if (subtotalH > 0) {
+          this._absCell({
+            x: C + (leafOffset + span - 1) * W,
+            y: (level + 1) * RH,
+            w: W,
+            h: subtotalH,
+            text: '∑',
+            cls: 'subtotal-col',
+          });
+        }
+      }
+    }
+
+    return leafOffset + span;
+  }
+
+  /**
+   * Creates and appends an absolutely positioned cell to headerEl.
+   */
+  _absCell({ x, y, w, h, text, cls }) {
+    const cell = document.createElement('div');
+    cell.className = 'pg-col-header-cell' + (cls ? ' ' + cls : '');
+    cell.style.cssText = `
+      position: absolute;
+      left: ${x}px; top: ${y}px;
+      width: ${w}px; height: ${h}px;
+      box-sizing: border-box;
+    `;
+    cell.textContent = text;
+    this.headerEl.appendChild(cell);
+    return cell;
+  }
+
+  /** Creates the scroll area div and the virtual space div inside it. */
+  _mountScrollArea() {
+    const H = this._headerHeight;
+
+    this.scrollArea = document.createElement('div');
+    this.scrollArea.className = 'pg-scroll';
+    this.scrollArea.style.top = H + 'px';
+    this.container.appendChild(this.scrollArea);
+
+    this.virtualSpace = document.createElement('div');
+    this.virtualSpace.style.cssText = `
+      position: relative;
+      width: ${this.totalWidth}px;
+      height: ${this.flatRows.length * PivotGrid.ROW_HEIGHT}px;
+    `;
+    this.scrollArea.appendChild(this.virtualSpace);
+  }
+
+  // ── Virtualization ──────────────────────────────────────────────────────────
+
+  /**
+   * Renders only the rows currently in the viewport (+ BUFFER rows above/below).
+   * Recycles rows that have scrolled out of view back into the pool.
+   */
+  _renderVisible() {
+    const viewH = this.scrollArea.clientHeight;
+    const scrollTop = this.scrollArea.scrollTop;
+    const RH = PivotGrid.ROW_HEIGHT;
+    const BUF = PivotGrid.BUFFER;
+
+    const first = Math.max(0, Math.floor(scrollTop / RH) - BUF);
+    const last = Math.min(
+      this.flatRows.length - 1,
+      Math.ceil((scrollTop + viewH) / RH) + BUF
+    );
+
+    for (const [idx, el] of this.rendered) {
+      if (idx < first || idx > last) {
+        this.virtualSpace.removeChild(el);
+        this._recycleRow(el);
+        this.rendered.delete(idx);
+      }
+    }
+
+    for (let i = first; i <= last; i++) {
+      if (this.rendered.has(i)) continue;
+      const el = this._acquireRow();
+      this._fillRow(el, this.flatRows[i], i);
+      this.virtualSpace.appendChild(el);
+      this.rendered.set(i, el);
+    }
+  }
+
+  /** Returns a recycled or newly created row element. */
+  _acquireRow() {
+    if (this.rowPool.length) {
+      const el = this.rowPool.pop();
+      el.className = 'pg-row';
+      el.removeAttribute('style');
+      el.innerHTML = '';
+      return el;
+    }
+    const el = document.createElement('div');
+    el.className = 'pg-row';
+    return el;
+  }
+
+  /** Returns a row element to the pool for reuse. */
+  _recycleRow(el) {
+    this.rowPool.push(el);
+  }
+
+  // ── Filling the Line ──────────────────────────────────────────────────────
+
+  /**
+   * Fills a row element with header cell and value cells for the given node.
+   * @param {Element} el   — row element from the pool
+   * @param {object}  node — flat row node (or { isGrandTotal: true })
+   * @param {number}  idx  — row index in flatRows
+   */
+  _fillRow(el, node, idx) {
+    const RH = PivotGrid.ROW_HEIGHT;
+    el.style.top = idx * RH + 'px';
+    el.style.width = this.totalWidth + 'px';
+    el.style.height = RH + 'px';
+
+    if (node.isGrandTotal) {
+      el.classList.add('grand-total');
+      this._fillGrandTotalRow(el);
+      return;
+    }
+
+    el.style.background = idx % 2 === 0 ? '#ffffff' : '#fcfcfc';
+    this._fillHeaderCell(el, node);
+    this._fillValueCells(el, node);
+  }
+
+  /**
+   * Appends the sticky left header cell (label + expand/collapse toggle) to a row.
+   * @param {Element} el   — row element
+   * @param {object}  node — row tree node
+   */
+  _fillHeaderCell(el, node) {
+    const RH = PivotGrid.ROW_HEIGHT;
+    const C = this._colHeaderW;
+    const I = PivotGrid.INDENT;
+
+    const cell = document.createElement('div');
+    cell.className = 'pg-cell-header';
+    cell.style.cssText = `width:${C}px;height:${RH}px;padding-left:${8 + node.depth * I}px`;
+
+    if (node.children) {
+      const toggle = document.createElement('span');
+      toggle.className = 'pg-toggle' + (this.collapsed.has(node.code) ? ' collapsed' : '');
+      toggle.textContent = '▾';
+      toggle.addEventListener('click', (e) => {
+        e.stopPropagation();
+        this._toggleCollapse(node.code);
+      });
+      cell.appendChild(toggle);
+    } else {
+      const spacer = document.createElement('span');
+      spacer.className = 'pg-toggle-spacer';
+      cell.appendChild(spacer);
+    }
+
+    const label = document.createElement('span');
+    label.className = `pg-label depth-${Math.min(node.depth, 2)}`;
+    label.textContent = node.value;
+    cell.appendChild(label);
+
+    el.appendChild(cell);
+  }
+
+  /**
+   * Appends all value cells (one per column + one total) to a row.
+   * Each cell fires a drillthrough event on click.
+   * @param {Element} el   — row element
+   * @param {object}  node — row tree node
+   */
+  _fillValueCells(el, node) {
+    const RH = PivotGrid.ROW_HEIGHT;
+    const W = PivotGrid.COL_W;
+    const cols = this.flatCols.length ? this.flatCols : this.colKeys;
+
+    for (const col of cols) {
+      const key = node.code + '||' + col.code;
+      const val = this.cells.get(key);
+      const cell = document.createElement('div');
+      cell.className = 'pg-cell'
+        + (val == null ? ' empty' : '')
+        + (col.isSubtotal ? ' subtotal' : '');
+      cell.style.cssText = `width:${W}px;height:${RH}px`;
+      cell.textContent = val != null ? this._fmt(val) : '—';
+      if (val != null) {
+        cell.addEventListener('click', () => this._emitDrillthrough(node, col.code, val));
+      }
+      el.appendChild(cell);
+    }
+
+    const totalKey = node.code + '||__total__';
+    const totalVal = this.cells.get(totalKey) || 0;
+    const totalCell = document.createElement('div');
+    totalCell.className = 'pg-cell total';
+    totalCell.style.cssText = `width:${W}px;height:${RH}px`;
+    totalCell.textContent = this._fmt(totalVal);
+    totalCell.addEventListener('click', () => this._emitDrillthrough(node, '__total__', totalVal));
+    el.appendChild(totalCell);
+  }
+
+  /**
+   * Fills the grand total row: header label + column totals + overall grand total.
+   * @param {Element} el — row element
+   */
+  _fillGrandTotalRow(el) {
+    const RH = PivotGrid.ROW_HEIGHT;
+    const C = this._colHeaderW;
+    const W = PivotGrid.COL_W;
+    const cols = this.flatCols.length ? this.flatCols : this.colKeys;
+
+    const headerCell = document.createElement('div');
+    headerCell.className = 'pg-cell-header';
+    headerCell.style.cssText = `width:${C}px;height:${RH}px;padding-left:8px`;
+
+    const spacer = document.createElement('span');
+    spacer.className = 'pg-toggle-spacer';
+    headerCell.appendChild(spacer);
+
+    const label = document.createElement('span');
+    label.className = 'pg-label depth-0';
+    label.textContent = this._labels.total || 'Total';
+    headerCell.appendChild(label);
+    el.appendChild(headerCell);
+
+    for (const col of cols) {
+      const key = '__grand__||' + col.code;
+      const val = this.cells.get(key) || 0;
+      const cell = document.createElement('div');
+      cell.className = 'pg-cell total' + (col.isSubtotal ? ' subtotal' : '');
+      cell.style.cssText = `width:${W}px;height:${RH}px`;
+      cell.textContent = this._fmt(val);
+      cell.addEventListener('click', () =>
+        this._emitDrillthrough({ isGrandTotal: true }, col.code, val)
+      );
+      el.appendChild(cell);
+    }
+
+    const grandCell = document.createElement('div');
+    grandCell.className = 'pg-cell total grand-total-val';
+    grandCell.style.cssText = `width:${W}px;height:${RH}px`;
+    grandCell.textContent = this._fmt(this.grandTotal || 0);
+    grandCell.addEventListener('click', () =>
+      this._emitDrillthrough({ isGrandTotal: true }, '__total__', this.grandTotal)
+    );
+    el.appendChild(grandCell);
+  }
+
+  // ── Collapse columns ───────────────────────────────────────────────────────
+
+  /**
+   * Toggles collapse state of a column group.
+   * When expanding, collapses direct children to avoid overloading the view.
+   * @param {string} code — column node code
+   */
+  _toggleColCollapse(code) {
+    if (this.collapsedCols.has(code)) {
+      this.collapsedCols.delete(code);
+      // Collapse direct children
+      const node = this._findColNode(code);
+      if (node?.children) {
+        for (const child of node.children) {
+          if (child.children) this.collapsedCols.add(child.code);
+        }
+      }
+    } else {
+      this.collapsedCols.add(code);
+    }
+    this._rebuildCols();
+  }
+
+  /**
+   * Finds a column tree node by its code (recursive).
+   * @param {string}   code
+   * @param {object[]} [nodes=this.colTree]
+   * @returns {object|null}
+   */
+  _findColNode(code, nodes = this.colTree) {
+    if (!nodes) return null;
+    for (const node of nodes) {
+      if (node.code === code) return node;
+      const found = this._findColNode(code, node.children);
+      if (found) return found;
+    }
+    return null;
+  }
+
+  /**
+   * Shows or hides subtotal columns in multi-level column mode.
+   * @param {boolean} show
+   */
+  toggleSubtotals(show) {
+    this._hideSubtotals = !show;
+    this._rebuildCols();
+  }
+
+  /** Rebuilds flat columns and re-renders the column header and grid. */
+  _rebuildCols() {
+    this._buildFlatCols();
+    const cols = this.flatCols.length ? this.flatCols : this.colKeys;
+    this.totalWidth = this._colHeaderW + (cols.length + 1) * PivotGrid.COL_W;
+    this.virtualSpace.style.width = this.totalWidth + 'px';
+    this.scrollArea.style.top = this._headerHeight + 'px';
+    this.headerEl.remove();
+    this._mountColHeader();
+    this.headerEl.style.transform = `translateX(-${this.scrollArea.scrollLeft}px)`;
+    this._redraw();
+  }
+
+  // ── Redraw ─────────────────────────────────────────────────────────────────
+
+  /** Clears all rendered rows and re-renders the visible viewport. */
+  _redraw() {
+    this.virtualSpace.style.height =
+      this.flatRows.length * PivotGrid.ROW_HEIGHT + 'px';
+
+    for (const [, el] of this.rendered) {
+      this.virtualSpace.removeChild(el);
+      this._recycleRow(el);
+    }
+    this.rendered.clear();
+    this._renderVisible();
+  }
+
+  // ── Scroll ─────────────────────────────────────────────────────────────────
+
+  /** Binds the scroll event — syncs header position and triggers virtual render. */
+  _bindScroll() {
+    let ticking = false;
+    this.scrollArea.addEventListener('scroll', () => {
+      this.headerEl.style.transform =
+        `translateX(-${this.scrollArea.scrollLeft}px)`;
+
+      if (!ticking) {
+        requestAnimationFrame(() => {
+          this._renderVisible();
+          ticking = false;
+        });
+        ticking = true;
+      }
+    });
+  }
+
+  // ── Drillthrough ───────────────────────────────────────────────────────────
+
+  /**
+   * Builds a context object from the clicked cell and dispatches a
+   * custom "drillthrough" event on the container.
+   * @param {object} node    — row node (or { isGrandTotal: true })
+   * @param {string} colCode — column code or "__total__"
+   * @param {number} value   — aggregated cell value
+   */
+  _emitDrillthrough(node, colCode, value) {
+    const context = {};
+
+    if (!node.isGrandTotal) {
+      const chain = this._getNodeChain(node);
+      for (let i = 0; i < chain.length; i++) {
+        context[this.rows[i]] = chain[i].value;
+      }
+    }
+
+    if (colCode !== '__total__') {
+      const parts = colCode.split('→');
+      for (let i = 0; i < parts.length; i++) {
+        if (this.columns[i]) context[this.columns[i]] = parts[i];
+      }
+    }
+
+    // context holds logical field names — provider handles the mapping
+    this.container.dispatchEvent(new CustomEvent('drillthrough', {
+      bubbles: true,
+      detail: { context, value },
+    }));
+  }
+
+  /**
+   * Walks flatRows upward to build the ancestor chain for a given node.
+   * Used to construct the drillthrough context.
+   * @param {object} node
+   * @returns {object[]}
+   */
+  _getNodeChain(node) {
+    const chain = [node];
+    if (node.depth === 0) return chain;
+
+    const idx = this.flatRows.indexOf(node);
+    for (let i = idx - 1; i >= 0; i--) {
+      const n = this.flatRows[i];
+      if (n.isGrandTotal) continue;
+      if (n.depth === node.depth - 1) {
+        chain.unshift(n);
+        if (n.depth === 0) break;
+        node = n;
+      }
+    }
+    return chain;
+  }
+
+  // ── Utilities ────────────────────────────────────────────────────────────────
+
+  /** Formats a numeric value with locale-aware thousand separators. */
+  _fmt(val) {
+    return new Intl.NumberFormat('ru-RU', { maximumFractionDigits: 0 }).format(val);
+  }
+
+  // ── Public API ──────────────────────────────────────────────────────────
+
+  /**
+   * Binds mousedown drag on the resize handle to adjust the row-label column width.
+   * @param {Element} handle
+   */
+  _bindResizeHandle(handle) {
+    handle.addEventListener('mousedown', (e) => {
+      e.preventDefault();
+      const startX = e.clientX;
+      const startW = this._colHeaderW;
+
+      const onMove = (mv) => {
+        //const newW = Math.max(80, startW + mv.clientX - startX);
+        const newW = Math.max(PivotGrid.COL_HEADER_W, startW + mv.clientX - startX);
+        this._colHeaderW = newW;
+        this._rebuild();
+      };
+
+      const onUp = () => {
+        document.removeEventListener('mousemove', onMove);
+        document.removeEventListener('mouseup', onUp);
+      };
+
+      document.addEventListener('mousemove', onMove);
+      document.addEventListener('mouseup', onUp);
+    });
+  }
+
+  /** Full rebuild after column width change: remounts header and re-renders rows. */
+  _rebuild() {
+    this.headerEl?.remove();
+    this.headerEl = null;
+    this._buildFlatCols();
+    this._mountColHeader();
+    for (const [, el] of this.rendered) this._recycleRow(el);
+    this.rendered.clear();
+    this._renderVisible();
+  }
+
+  /** Instant measure/function change — no aggregate recalculation. */
+  // setMeasure(measure, func) {
+  //   this._measureKey = measure + '_' + func;
+  //   for (const [, el] of this.rendered) this._recycleRow(el);
+  //   this.rendered.clear();
+  //   this._renderVisible();
+  // }
+
+  /**
+   * Replaces the current aggregation result and re-renders the grid.
+   * Top-level column groups are collapsed automatically.
+   * @param {object}   result
+   * @param {object}   [options]
+   * @param {string[]} [options.rows]
+   * @param {string[]} [options.columns]
+   * @param {string}   [options.measure]
+   * @param {object}   [options.fieldDefs]
+   */
+  setResult(result, { rows, columns, measure, fieldDefs } = {}) {
+    if (rows) this.rows = rows;
+    if (columns) this.columns = columns;
+    if (measure) this.measure = measure;
+    if (fieldDefs) this.fieldDefs = fieldDefs;
+    this.collapsedCols.clear();
+    this._applyResult(result);
+
+    // Collapse all top-level column groups
+    if (this.colTree) {
+      for (const node of this.colTree) {
+        if (node.children) this.collapsedCols.add(node.code);
+      }
+      this._buildFlatCols();
+    }
+
+    const cols = this.flatCols.length ? this.flatCols : this.colKeys;
+    this.totalWidth = this._colHeaderW + (cols.length + 1) * PivotGrid.COL_W;
+    this.virtualSpace.style.width = this.totalWidth + 'px';
+    this.scrollArea.style.top = this._headerHeight + 'px';
+
+    this.headerEl.remove();
+    this._mountColHeader();
+    this._redraw();
+  }
+
+  /** Collapses all row nodes and redraws. */
+  collapseAll() {
+    const walk = (nodes) => {
+      if (!nodes) return;
+      for (const node of nodes) {
+        if (node.children) {
+          this.collapsed.add(node.code);
+          walk(node.children);
+        }
+      }
+    };
+    walk(this.tree);
+    this._buildFlatRows();
+    this._redraw();
+  }
+
+  /**
+   * Detects the maximum scrollable height supported by the current browser.
+   * Used to cap MAX_FLAT_ROWS and prevent invisible rows.
+   * @returns {number}
+   */
+  static _detectMaxHeight() {
+    const el = document.createElement('div');
+    el.style.cssText = 'position:fixed;visibility:hidden;';
+    document.body.appendChild(el);
+    let h = 1_000_000;
+    while (h < 100_000_000) {
+      el.style.height = h + 'px';
+      if (el.offsetHeight < h) break;
+      h *= 2;
+    }
+    el.remove();
+    return h / 2;
+  }
+
+  static MAX_FLAT_ROWS = Math.floor(PivotGrid._detectMaxHeight() / PivotGrid.ROW_HEIGHT);
+
+  /**
+   * Shows a confirm dialog when the expanded row count exceeds MAX_FLAT_ROWS.
+   * @param {number}   count     — total rows after expand
+   * @param {Function} onConfirm — called if user confirms
+   * @param {Function} [onCancel] — called if user cancels
+   */
+  _confirmLargeExpand(count, onConfirm, onCancel) {
+    const millions = (count / 1_000_000).toFixed(1);
+    const msg = (this._labels.confirmLargeExpand || 'Too many rows (~{millions}M). Click OK to expand anyway.').replace('{millions}', millions);
+    if (window.confirm(msg)) onConfirm();
+    else onCancel?.();
+  }
+
+  /**
+   * Toggles a row node's collapsed state and redraws.
+   * Prompts confirmation if the resulting row count exceeds MAX_FLAT_ROWS.
+   * @param {string} code — row node code
+   */
+  _toggleCollapse(code) {
+    const wasCollapsed = this.collapsed.has(code);
+    if (wasCollapsed) this.collapsed.delete(code);
+    else this.collapsed.add(code);
+
+    this._buildFlatRows();
+
+    if (wasCollapsed && this.flatRows.length > PivotGrid.MAX_FLAT_ROWS) {
+      this._confirmLargeExpand(this.flatRows.length,
+        () => this._redraw(),
+        () => {
+          this.collapsed.add(code);
+          this._buildFlatRows();
+        }
+      );
+      return;
+    }
+
+    this._redraw();
+  }
+
+  /**
+   * Expands rows up to the given depth. Clicking a depth level again collapses it.
+   * @param {number} depth — 1-based depth level
+   */
+  expandToDepth(depth) {
+    const nodesAtDepth = [];
+    const walk = (nodes) => {
+      for (const node of nodes) {
+        if (!node.children) continue;
+        if (node.depth < depth - 1) {
+          this.collapsed.delete(node.code);
+          walk(node.children);
+        } else if (node.depth === depth - 1) {
+          nodesAtDepth.push(node);
+          // leave children untouched
+        }
+      }
+    };
+    walk(this.tree);
+
+    const anyExpanded = nodesAtDepth.some(n => !this.collapsed.has(n.code));
+    for (const n of nodesAtDepth) {
+      if (anyExpanded) this.collapsed.add(n.code);
+      else this.collapsed.delete(n.code);
+    }
+
+    this._buildFlatRows();
+    this._redraw();
+  }
+
+  /** Expands all row nodes. Prompts confirmation if row count exceeds MAX_FLAT_ROWS. */
+  expandAll() {
+    this.collapsed.clear();
+    this._buildFlatRows();
+
+    if (this.flatRows.length > PivotGrid.MAX_FLAT_ROWS) {
+      this._confirmLargeExpand(this.flatRows.length, () => this._redraw());
+      return;
+    }
+
+    this._redraw();
+  }
+
+  /** Expands all column groups. */
+  expandAllCols() {
+    this.collapsedCols.clear();
+    this._rebuildCols();
+  }
+
+  /** Collapses all column groups. */
+  collapseAllCols() {
+    const walk = (nodes) => {
+      if (!nodes) return;
+      for (const node of nodes) {
+        if (node.children) {
+          this.collapsedCols.add(node.code);
+          walk(node.children);
+        }
+      }
+    };
+    walk(this.colTree);
+    this._rebuildCols();
+  }
+}
+
+/**
+ * FieldZones
+ *
+ * Drag-and-drop zones for managing pivot fields.
+ * Three zones: FIELDS (free) → ROWS → COLUMNS
+ *
+ * Drop logic: insertion position is determined by the placeholder in the DOM —
+ * no recalculation in onUp, just read what is already in the DOM.
+ */
+class FieldZones {
+
+  constructor({ dimensions, fields = {}, initialRows, initialColumns, initialFilters = [], onChange, onFilterOpen }) {
+    this.dimensions   = dimensions;
+    this._fieldDefs   = fields;
+    this.onChange     = onChange;
+    this.onFilterOpen = onFilterOpen;
+
+    this.rows    = [...initialRows];
+    this.columns = [...initialColumns];
+    this.filters = [...initialFilters];
+
+    this.filterSet = new Set(initialFilters);
+    this.state = {};
+    for (const dim of dimensions) {
+      if (initialRows.includes(dim)) this.state[dim] = 'rows';
+      else if (initialColumns.includes(dim)) this.state[dim] = 'columns';
+      else this.state[dim] = 'free';
+    }
+
+    this._placeholder = null;
+    this._render();
+    this._bindEvents();
+    this._lastMoved = null;
+    this._filterHints = {};   // { dim → { badge, tooltip } }
+    this._tooltip = document.createElement('div');
+    this._tooltip.className = 'fz-tooltip';
+    document.body.appendChild(this._tooltip);
+    this._bindTooltip();
+  }
+
+  setFilterHints(hints) {
+    this._filterHints = hints || {};
+    this._renderZone('fz-chips-filters', 'filters');
+  }
+
+  _bindTooltip() {
+    document.addEventListener('mouseover', (e) => {
+      const chip = e.target.closest('.fz-chip[data-zone="filters"]');
+      const hint = chip && this._filterHints[chip.dataset.field];
+      if (!hint) { this._tooltip.style.display = 'none'; return; }
+      this._tooltip.textContent = hint.tooltip;
+      this._tooltip.style.display = 'block';
+    });
+
+    document.addEventListener('mousemove', (e) => {
+      if (this._tooltip.style.display === 'none') return;
+      const t = this._tooltip;
+      const x = Math.min(e.clientX + 12, window.innerWidth - t.offsetWidth - 8);
+      const y = e.clientY - t.offsetHeight - 8;  // above cursor
+      t.style.left = x + 'px';
+      t.style.top = (y < 4 ? e.clientY + 16 : y) + 'px';  // if no space above — below cursor
+    });
+
+    document.addEventListener('mouseout', (e) => {
+      const chip = e.target.closest('.fz-chip[data-zone="filters"]');
+      if (chip && !chip.contains(e.relatedTarget)) {
+        this._tooltip.style.display = 'none';
+      }
+    });
+  }
+
+  // ── Render ───────────────────────────────────────────────────────────────
+ 
+  _render() {
+    this._renderZone('fz-chips-free',    'free');
+    this._renderZone('fz-chips-rows',    'rows');
+    this._renderZone('fz-chips-columns', 'columns');
+    this._renderZone('fz-chips-filters', 'filters');
+  }
+
+  _renderZone(containerId, zone) {
+    const el = document.getElementById(containerId);
+    if (!el) return;
+
+    const fields = zone === 'rows'    ? this.rows
+      : zone === 'columns' ? this.columns
+      : zone === 'filters' ? [...this.filterSet]
+      : this.dimensions.filter(d => this.state[d] === 'free' && !this.filterSet.has(d));
+
+    el.innerHTML = fields.map(f => {
+      const hint = (zone === 'filters') ? this._filterHints[f] : null;
+      const tooltip = hint ? `${f}: ${hint.tooltip}` : f;
+      return `
+    <div class="fz-chip${hint ? ' fz-chip--filtered' : ''}"
+         data-field="${f}" data-zone="${zone}" title="">
+      <span class="fz-chip-label" draggable="false">${this._fieldDefs[f]?.title || this._fieldDefs[f]?.label || f}</span>
+      ${hint ? `<span class="fz-chip-hint" draggable="false">${hint.badge}</span>` : ''}
+      ${zone !== 'free'
+          ? `<span class="fz-chip-remove" draggable="false" data-field="${f}" data-zone="${zone}">×</span>`
+          : ''}
+    </div>
+    `;
+    }).join('');
+
+    if (zone === 'filters' && this.onFilterOpen) {
+      el.querySelectorAll('.fz-chip').forEach(chip => {
+        chip.querySelector('.fz-chip-label').addEventListener('click', (e) => {
+          e.stopPropagation();
+          this.onFilterOpen(chip.dataset.field, chip);
+        });
+      });
+    }
+
+    if (this._lastMoved) {
+      const chip = el.querySelector(`[data-field="${this._lastMoved}"]`);
+      chip?.classList.add('fz-chip--last');
+    }
+  }
+
+  // ── Events ───────────────────────────────────────────────────────────────
+
+  _bindEvents() {
+    document.addEventListener('mousedown', (e) => {
+      if (e.target.classList.contains('fz-chip-remove')) {
+        e.stopPropagation();
+        this._moveField(e.target.dataset.field, e.target.dataset.zone, 'free');
+        return;
+      }
+      const chip = e.target.closest('.fz-chip');
+      if (!chip) return;
+      this._initDrag(e, chip);
+    });
+  }
+
+  // ── Drag & Drop ───────────────────────────────────────────────────────────
+
+  _initDrag(e, chip) {
+    e.preventDefault();
+
+    const field    = chip.dataset.field;
+    const fromZone = chip.dataset.zone;
+    const startX   = e.clientX;
+    const startY   = e.clientY;
+    let dragging   = false;
+    let ghost      = null;
+
+    const onMove = (mv) => {
+      if (!dragging && Math.hypot(mv.clientX - startX, mv.clientY - startY) > 5) {
+        dragging = true;
+        chip.classList.add('fz-chip--dragging');
+        ghost = this._createGhost(chip, mv);
+      }
+      if (!dragging) return;
+
+      ghost.style.left = mv.clientX + 12 + 'px';
+      ghost.style.top  = mv.clientY - 12 + 'px';
+
+      // Hide ghost and dragging chip — otherwise elementFromPoint picks them up
+      ghost.style.visibility = 'hidden';
+      chip.style.visibility  = 'hidden';
+      this._updatePlaceholder(mv);
+      ghost.style.visibility = '';
+      chip.style.visibility  = '';
+    };
+
+    const onUp = () => {
+      document.removeEventListener('mousemove', onMove);
+      document.removeEventListener('mouseup',   onUp);
+
+      ghost?.remove();
+      chip.classList.remove('fz-chip--dragging');
+      chip.style.visibility = '';
+
+      if (!dragging) {
+        this._clearHighlight();
+        return;
+      }
+
+      // Read final drop position from placeholder
+      const ph = this._placeholder;
+      if (!ph?.parentNode) {
+        this._clearHighlight();
+        return;
+      }
+
+      // Zone — placeholder container
+      const zoneEl = ph.parentNode.closest('[data-fz-zone]') || ph.parentNode;
+      const toZone = zoneEl.dataset.fzZone;
+
+      // beforeField — first fz-chip after the placeholder
+      const siblings    = [...ph.parentNode.children];
+      const phIdx       = siblings.indexOf(ph);
+      const afterChips  = siblings.slice(phIdx + 1).filter(el => el.classList.contains('fz-chip'));
+      const beforeField = afterChips[0]?.dataset.field || null;
+
+      this._clearHighlight();
+
+      if (!toZone) return;
+
+      if (toZone !== fromZone) {
+        this._moveFieldBefore(field, fromZone, toZone, beforeField);
+      } else {
+        this._reorder(field, fromZone, beforeField);
+      }
+    };
+
+    document.addEventListener('mousemove', onMove);
+    document.addEventListener('mouseup',   onUp);
+  }
+
+  // ── Placeholder ──────────────────────────────────────────────────────────
+
+  _updatePlaceholder(e) {
+    this._clearHighlight();
+
+    // Find zone under cursor
+    const zoneEl = document.elementFromPoint(e.clientX, e.clientY)
+      ?.closest('[data-fz-zone]');
+    if (zoneEl) zoneEl.classList.add('fz-zone--over');
+
+    const ph = document.createElement('div');
+    ph.className = 'fz-chip-placeholder';
+    this._placeholder = ph;
+
+    // Find chip under cursor
+    const target = document.elementFromPoint(e.clientX, e.clientY)?.closest('.fz-chip');
+
+    if (target && !target.classList.contains('fz-chip-placeholder')) {
+      const rect         = target.getBoundingClientRect();
+      const insertBefore = e.clientX < rect.left + rect.width / 2;
+      target.parentNode.insertBefore(ph, insertBefore ? target : target.nextSibling);
+    } else if (zoneEl) {
+      // No chip target — append to end of zone
+      const chipsContainer = zoneEl.querySelector('[id^="fz-chips"]') || zoneEl;
+      chipsContainer.appendChild(ph);
+    }
+  }
+
+  _clearHighlight() {
+    document.querySelectorAll('[data-fz-zone]')
+      .forEach(z => z.classList.remove('fz-zone--over'));
+    this._placeholder?.remove();
+    this._placeholder = null;
+  }
+
+  // ── Ghost ────────────────────────────────────────────────────────────────
+
+  _createGhost(chip, e) {
+    const ghost = chip.cloneNode(true);
+    ghost.className = 'fz-chip fz-chip--ghost';
+    Object.assign(ghost.style, {
+      position:      'fixed',
+      left:          e.clientX + 12 + 'px',
+      top:           e.clientY - 12 + 'px',
+      pointerEvents: 'none',
+      zIndex:        '9999',
+      opacity:       '0.85',
+    });
+    document.body.appendChild(ghost);
+    return ghost;
+  }
+
+  // ── State mutations ──────────────────────────────────────────────────────
+
+  _moveField(field, fromZone, toZone) {
+    if (toZone === 'filters') {
+      // Add to filters, do NOT remove from rows/columns
+      this.filterSet.add(field);
+    } else if (fromZone === 'filters') {
+      // Remove from filters (× click), primary zone unchanged
+      this.filterSet.delete(field);
+    } else {
+      // Move between rows/columns/free
+      if (fromZone === 'rows') this.rows = this.rows.filter(f => f !== field);
+      if (fromZone === 'columns') this.columns = this.columns.filter(f => f !== field);
+      if (toZone === 'rows') this.rows.push(field);
+      if (toZone === 'columns') this.columns.push(field);
+      this.state[field] = toZone;
+    }
+    this._lastMoved = field;
+    this._render();
+    this.onChange({ rows: [...this.rows], columns: [...this.columns], filters: [...this.filterSet] });
+  }
+
+  _moveFieldBefore(field, fromZone, toZone, beforeField) {
+    if (toZone === 'filters') {
+      this.filterSet.add(field);
+      this._lastMoved = field;
+      this._render();
+      this.onChange({ rows: [...this.rows], columns: [...this.columns], filters: [...this.filterSet] });
+      return;
+    }
+
+    if (fromZone === 'filters') {
+      // Dragged from filters to rows/columns — add there, keep in filters
+      const arr = toZone === 'rows' ? this.rows : toZone === 'columns' ? this.columns : null;
+      if (arr && !arr.includes(field)) {
+        if (beforeField) {
+          const idx = arr.indexOf(beforeField);
+          arr.splice(idx !== -1 ? idx : arr.length, 0, field);
+        } else {
+          arr.push(field);
+        }
+        this.state[field] = toZone;
+      }
+    } else {
+      if (fromZone === 'rows') this.rows = this.rows.filter(f => f !== field);
+      if (fromZone === 'columns') this.columns = this.columns.filter(f => f !== field);
+      const arr = toZone === 'rows' ? this.rows : toZone === 'columns' ? this.columns : null;
+      if (arr) {
+        if (beforeField) {
+          const idx = arr.indexOf(beforeField);
+          arr.splice(idx !== -1 ? idx : arr.length, 0, field);
+        } else {
+          arr.push(field);
+        }
+      }
+      this.state[field] = toZone;
+    }
+
+    this._lastMoved = field;
+    this._render();
+    this.onChange({ rows: [...this.rows], columns: [...this.columns], filters: [...this.filterSet] });
+  }
+
+  _reorder(field, zone, beforeField) {
+    const arr  = zone === 'rows' ? this.rows : this.columns;
+    const from = arr.indexOf(field);
+    if (from === -1) return;
+
+    arr.splice(from, 1);
+
+    if (beforeField) {
+      const to = arr.indexOf(beforeField);
+      arr.splice(to !== -1 ? to : arr.length, 0, field);
+    } else {
+      arr.push(field); // placeholder was at the end — append to end
+    }
+    this._lastMoved = field;
+    this._render();
+    // this.onChange({ rows: [...this.rows], columns: [...this.columns], filters: [...this.filters] });
+    this.onChange({ rows: [...this.rows], columns: [...this.columns], filters: [...this.filterSet] });
+  }
+}
+
+/**
+ * FilterManager
+ *
+ * Manages filters per dimension:
+ *   - If values ≤ filterCheckboxLimit → checkboxes + search
+ *   - If more → text search only (contains / starts_with)
+ *   - Values are fetched from the provider cache or from the server
+ */
+class FilterManager {
+
+  constructor({ provider, fields, config }) {
+    this.provider = provider;
+    this.fields   = fields;
+    this.config   = config;
+
+    // dim → { allValues, selected, searchType, searchText }
+    this._state  = {};
+    this._popup  = null;
+    this._openDim = null;
+    this._onChange = null;
+  }
+
+  set onChange(fn) { this._onChange = fn; }
+
+  // ── Dimension management ──────────────────────────────────────────────────
+
+  async onDimAdded(dim) {
+    if (this._state[dim]) {
+      // already exists — just open the popup (FieldZones will call onFilterOpen)
+      return;
+    }
+
+    this._state[dim] = {
+      allValues:  null,
+      selected:   null,   // null = all (no checkbox filter)
+      searchType: 'contains',
+      searchText: '',
+    };
+
+    // Load values if checkboxes are needed
+    try {
+      const limit = this.config.filterCheckboxLimit ?? 30;
+      const count = await this.provider.countDistinct(dim);
+      if (count <= limit) {
+        this._state[dim].allValues = await this.provider.getDistinctValues(dim);
+      }
+    } catch (e) {
+      console.warn('FilterManager: failed to load values for', dim, e);
+    }
+  }
+
+  onDimRemoved(dim) {
+    delete this._state[dim];
+    if (this._openDim === dim) this._closePopup();
+    this._notify();
+  }
+
+  // ── Popup ────────────────────────────────────────────────────────────────
+
+  openFor(dim, anchorEl) {
+    this._closePopup();
+    const f = this._state[dim];
+    if (!f) return;
+
+    this._openDim = dim;
+
+    const popup = document.createElement('div');
+    popup.className = 'fm-popup';
+    document.body.appendChild(popup);
+    this._popup = popup;
+
+    this._renderPopup(popup, dim, f);
+    this._positionPopup(popup, anchorEl);
+
+    requestAnimationFrame(() => {
+      document.addEventListener('mousedown', this._handleOutside = (e) => {
+        if (!popup.contains(e.target) && !anchorEl.contains(e.target)) {
+          this._closePopup();
+        }
+      });
+    });
+  }
+
+  _renderPopup(popup, dim, f) {
+    const radioName = 'fm-stype-' + dim;
+    const checkboxesHTML = f.allValues
+      ? `<div class="fm-checkbox-list">
+          <label class="fm-checkbox fm-select-all-wrap">
+            <input type="checkbox" class="fm-select-all" ${!f.selected ? 'checked' : ''}>
+            <em>All values</em>
+          </label>
+          <div class="fm-checkbox-scroll">
+            ${f.allValues.map(v => `
+              <label class="fm-checkbox">
+                <input type="checkbox" value="${v.replace(/"/g, '&quot;')}"
+                  ${!f.selected || f.selected.has(v) ? 'checked' : ''}>
+                <span>${v}</span>
+              </label>
+            `).join('')}
+          </div>
+        </div>`
+      : `<p class="fm-no-checkboxes">Too many values — use search</p>`;
+
+    popup.innerHTML = `
+      <div class="fm-popup-header">
+        <span class="fm-popup-title">${this.fields[dim]?.title || this.fields[dim]?.label || dim}</span>
+        <button class="fm-popup-close">×</button>
+      </div>
+      <div class="fm-search-section">
+        <div class="fm-search-type">
+          <label><input type="radio" name="${radioName}" value="contains"
+            ${f.searchType === 'contains' ? 'checked' : ''}> Contains</label>
+          <label><input type="radio" name="${radioName}" value="starts_with"
+            ${f.searchType === 'starts_with' ? 'checked' : ''}> Starts with</label>
+        </div>
+        <input type="text" class="fm-search-input" placeholder="Search..." value="${f.searchText}">
+      </div>
+      ${checkboxesHTML}
+      <div class="fm-popup-footer">
+        <button class="fm-btn fm-btn-clear">Clear</button>
+        <button class="fm-btn fm-btn-primary">Apply</button>
+      </div>
+    `;
+
+    const searchInput = popup.querySelector('.fm-search-input');
+    const selectAll   = popup.querySelector('.fm-select-all');
+
+    popup.querySelector('.fm-popup-close').onclick = () => this._closePopup();
+
+    // Sync the "Select all" checkbox state based on visible rows
+    const syncSelectAll = () => {
+      if (!selectAll) return;
+      const visible      = [...popup.querySelectorAll('.fm-checkbox:not(.fm-select-all-wrap)')]
+        .filter(l => l.style.display !== 'none');
+      const checkedCount = visible.filter(l => l.querySelector('input').checked).length;
+      selectAll.indeterminate = checkedCount > 0 && checkedCount < visible.length;
+      selectAll.checked       = visible.length > 0 && checkedCount === visible.length;
+    };
+
+    // Search: hides non-matching rows and unchecks them.
+    // Important: hidden items must not silently end up in the selection on Apply.
+    const applyCheckboxSearch = () => {
+      const q    = searchInput?.value.trim().toLowerCase() || '';
+      const type = popup.querySelector(`input[name="${radioName}"]:checked`)?.value || 'contains';
+
+      popup.querySelectorAll('.fm-checkbox:not(.fm-select-all-wrap)').forEach(label => {
+        const text = label.querySelector('span')?.textContent.trim().toLowerCase() || '';
+        const ok   = !q || (type === 'starts_with' ? text.startsWith(q) : text.includes(q));
+
+        label.style.display = ok ? '' : 'none';
+
+        // Uncheck hidden items — if the user clears the search text later,
+        // these items will reappear unchecked, not "selected by default"
+        if (!ok) label.querySelector('input').checked = false;
+      });
+
+      syncSelectAll();
+    };
+
+    // Search type — apply to checkboxes immediately
+    popup.querySelectorAll(`input[name="${radioName}"]`).forEach(r => {
+      r.onchange = () => {
+        f.searchType = r.value;
+        applyCheckboxSearch();
+      };
+    });
+
+    // Text search
+    searchInput?.addEventListener('input', applyCheckboxSearch);
+
+    // "Select all" / "Deselect all" — affects ALL checkboxes, including hidden ones.
+    // Otherwise unchecking "All values" with active search would not reset hidden items.
+    selectAll?.addEventListener('change', () => {
+      popup.querySelectorAll('.fm-checkbox:not(.fm-select-all-wrap) input')
+        .forEach(cb => { cb.checked = selectAll.checked; });
+    });
+
+    // Clear
+    popup.querySelector('.fm-btn-clear').onclick = () => {
+      f.selected   = null;
+      f.searchText = '';
+      this._closePopup();
+      this._notify();
+    };
+
+    // Apply
+    popup.querySelector('.fm-btn-primary').onclick = () => {
+      const checkedRadio = popup.querySelector(`input[name="${radioName}"]:checked`);
+      f.searchType = checkedRadio ? checkedRadio.value : 'contains';
+      f.searchText = searchInput?.value.trim() || '';
+
+      if (f.allValues) {
+        const checkedBoxes = [...popup.querySelectorAll('.fm-checkbox:not(.fm-select-all-wrap) input:checked')]
+          .map(cb => cb.value);
+        f.selected = checkedBoxes.length === f.allValues.length ? null : new Set(checkedBoxes);
+      }
+
+      this._closePopup();
+      this._notify();
+    };
+
+    // Apply current filter immediately on popup open —
+    // so checkboxes immediately reflect the saved searchText / searchType
+    if (f.searchText) applyCheckboxSearch();
+  }
+
+  _positionPopup(popup, anchorEl) {
+    const rect = anchorEl.getBoundingClientRect();
+    const left = Math.min(rect.left, window.innerWidth - 290);
+    popup.style.left = left + 'px';
+    popup.style.top  = (rect.bottom + 6) + 'px';
+  }
+
+  _closePopup() {
+    this._popup?.remove();
+    this._popup   = null;
+    this._openDim = null;
+    if (this._handleOutside) {
+      document.removeEventListener('mousedown', this._handleOutside);
+      this._handleOutside = null;
+    }
+  }
+
+  // ── Active filters ────────────────────────────────────────────────────────
+
+  /**
+   * Returns active filters in the format expected by the provider.
+   * { dim: { values: string[]|null, searchType, searchText } }
+   */
+  getActiveFilters() {
+    const result = {};
+    for (const [dim, f] of Object.entries(this._state)) {
+      const hasSelected = f.selected && f.selected.size > 0;
+      const hasSearch   = f.searchText.length > 0;
+      if (hasSelected || hasSearch) {
+        result[dim] = {
+          values:     hasSelected ? [...f.selected] : null,
+          searchType: f.searchType,
+          searchText: f.searchText,
+        };
+      }
+    }
+    return result;
+  }
+
+  hasActiveFilter(dim) {
+    const f = this._state[dim];
+    if (!f) return false;
+    return (f.selected && f.selected.size > 0) || f.searchText.length > 0;
+  }
+
+  getFilterHints() {
+    const result = {};
+    for (const [dim, f] of Object.entries(this._state)) {
+      const parts = [];
+
+      if (f.searchText) {
+        const prefix = f.searchType === 'starts_with' ? '' : '…';
+        parts.push(`«${f.searchText}${prefix}»`);
+      }
+
+      if (f.selected && f.selected.size > 0) {
+        const total = f.allValues?.length ?? null;
+        // If few items are excluded — show "except"
+        if (total && total - f.selected.size <= 2) {
+          const excluded = f.allValues.filter(v => !f.selected.has(v));
+          parts.push(`except: ${excluded.join(', ')}`);
+        } else if (f.selected.size <= 3) {
+          parts.push([...f.selected].join(', '));
+        } else {
+          parts.push(`${f.selected.size} val.`);
+        }
+      }
+
+      if (parts.length) {
+        result[dim] = {
+          badge: parts.length === 1 && f.selected?.size
+            ? String(f.selected.size)   // just a number on the chip
+            : '✕',
+          tooltip: parts.join(' + '),
+        };
+      }
+    }
+    return result;
+  }
+
+  _notify() {
+    this._onChange?.();
+  }
+}
+
+/**
+ * i18n.js — переводы интерфейса PivotGrid
+ *
+ * Язык задаётся через data-lang на контейнере:
+ *   <div data-config="sales" data-lang="en"></div>
+ *
+ * По умолчанию: ru
+ * Добавить язык: добавить новый ключ в I18N.
+ */
+const I18N = {
+  ru: {
+    loading: 'Загрузка данных...',
+    loadingGrid: 'Загрузка данных…',
+    cache: 'Кэш',
+    constructor: 'Конструктор',
+    filters: 'Фильтры',
+    fields: 'Поля',
+    rows: 'Строки',
+    columns: 'Колонки',
+    measure: 'Мера',
+    func: 'Функция',
+    expandRows: 'Развернуть строки',
+    collapseRows: 'Свернуть строки',
+    expandCols: 'Развернуть колонки',
+    collapseCols: 'Свернуть колонки',
+    subtotals: '∑ Подитоги',
+    exportCsv: '↓ CSV',
+    drillthrough: 'Drillthrough',
+    allData: 'Все данные',
+    noData: 'Нет данных',
+    shown: 'Показано',
+    firstN: 'Первые {n} записей',
+    total: 'Итого',
+    cacheEmpty: 'Кэш пуст',
+    cacheActual: 'Актуален',
+    cacheStale: 'Изменён · нужно обновить',
+    cacheRefresh: '↺ Обновить кэш',
+    errorPrefix: 'Ошибка: ',
+    cacheAdd: 'Добавить в кэш',
+    cacheRemove: 'Убрать из кэша',
+    cacheExceeds: 'строк — превышает лимит',
+    cacheRefreshError: 'Ошибка обновления кэша: ',
+    title: 'Сводная таблица',
+    // config-editor
+    ce_server: 'Сервер',
+    ce_database: 'База данных',
+    ce_query: 'Запрос',
+    ce_mainQuery: 'Основной query',
+    ce_colsQuery: 'Запрос для получения колонок',
+    ce_funcs: 'Функции агрегации',
+    ce_fetchCols: 'Получить колонки',
+    ce_drillthrough: 'Drillthrough',
+    ce_cols: 'Колонки',
+    ce_colDb: 'Колонка БД',
+    ce_colTitle: 'Название (title)',
+    ce_initialState: 'Начальное состояние',
+    ce_maxCacheRows: 'Макс. строк кэша',
+    ce_filterLimit: 'Лимит чекбоксов',
+    ce_configJs: 'config.js',
+    ce_save: 'Сохранить',
+    ce_loadFromServer: 'Загрузить с сервера',
+    ce_preview: '▶ Предпросмотр',
+    ce_saveConfig: '↑ Сохранить',
+    ce_selectConfig: '— выбрать конфиг —',
+    ce_configName: 'Имя конфига',
+    ce_dimension: 'Измерение',
+    ce_measure_type: 'Мера',
+    ce_fillUrl: 'Заполните URL и запрос',
+    ce_zeroRows: 'Запрос вернул 0 строк',
+    ce_colsLoaded: 'Получено {n} колонок',
+    ce_loadError: 'Ошибка: ',
+    ce_fetchBtn: 'Получить колонки',
+    ce_emptyFields: 'Нажмите «Получить колонки»',
+    ce_fillDbFields: 'Заполните host, database и user',
+    ce_dbSaved: 'Настройки сохранены',
+    ce_dbLoaded: 'Настройки загружены (пароль не передаётся)',
+    ce_enterName: 'Введите имя конфига',
+    ce_emptyConfig: 'Конфиг пуст',
+    ce_configSaved: 'Конфиг «{name}» сохранён',
+    ce_loadFailed: 'Ошибка загрузки: ',
+    ce_saveFailed: 'Ошибка сохранения: ',
+    ce_connector: 'Коннектор', 
+    ce_dtSqlLabel: 'SELECT запрос (используй {filters})', 
+    ce_dtUrlLabel: 'Base URL (фильтры добавятся как ?region=Север)',
+    ce_testConnection: 'Проверить соединение',
+    ce_testOk:         'Соединение успешно',
+    ce_testError:      'Ошибка соединения: ',
+    confirmLargeExpand: 'Слишком много строк для отображения.\n\nПосле разворачивания грид будет содержать ~{millions} млн строк, что превышает возможности браузера. Часть данных в нижней части будет недоступна.\n\nРекомендуем свернуть часть измерений.\n\nНажмите ОК чтобы всё равно развернуть, Отмена чтобы отказаться.',
+    ce_newConfig: 'Новый',
+    ce_deleteConfig:  'Удалить',
+    ce_confirmDelete: 'Удалить конфиг «{name}»?',
+    ce_deleteOk:      'Конфиг «{name}» удалён',
+    ce_deleteFailed:  'Ошибка удаления: ',
+  },
+  en: {
+    loading: 'Loading...',
+    loadingGrid: 'Loading data…',
+    cache: 'Cache',
+    constructor: 'Constructor',
+    filters: 'Filters',
+    fields: 'Fields',
+    rows: 'Rows',
+    columns: 'Columns',
+    measure: 'Measure',
+    func: 'Function',
+    expandRows: 'Expand rows',
+    collapseRows: 'Collapse rows',
+    expandCols: 'Expand columns',
+    collapseCols: 'Collapse columns',
+    subtotals: '∑ Subtotals',
+    exportCsv: '↓ CSV',
+    drillthrough: 'Drillthrough',
+    allData: 'All data',
+    noData: 'No data',
+    shown: 'Shown',
+    firstN: 'First {n} records',
+    total: 'Total',
+    cacheEmpty: 'Cache empty',
+    cacheActual: 'Up to date',
+    cacheStale: 'Changed · refresh needed',
+    cacheRefresh: '↺ Refresh cache',
+    errorPrefix: 'Error: ',
+    cacheAdd: 'Add to cache',
+    cacheRemove: 'Remove from cache',
+    cacheExceeds: 'rows — exceeds limit',
+    cacheRefreshError: 'Cache refresh error: ',
+    title: 'Pivot Table',
+    // config-editor
+    ce_server: 'Server',
+    ce_database: 'Database',
+    ce_query: 'Query',
+    ce_mainQuery: 'Main query',
+    ce_colsQuery: 'Query to fetch columns',
+    ce_funcs: 'Aggregation functions',
+    ce_fetchCols: 'Fetch columns',
+    ce_drillthrough: 'Drillthrough',
+    ce_cols: 'Columns',
+    ce_colDb: 'DB column',
+    ce_colTitle: 'Title',
+    ce_initialState: 'Initial state',
+    ce_maxCacheRows: 'Max cache rows',
+    ce_filterLimit: 'Checkbox limit',
+    ce_configJs: 'config.js',
+    ce_save: 'Save',
+    ce_loadFromServer: 'Load from server',
+    ce_preview: '▶ Preview',
+    ce_saveConfig: '↑ Save',
+    ce_selectConfig: '— select config —',
+    ce_configName: 'Config name',
+    ce_dimension: 'Dimension',
+    ce_measure_type: 'Measure',
+    ce_fillUrl: 'Fill in URL and query',
+    ce_zeroRows: 'Query returned 0 rows',
+    ce_colsLoaded: '{n} columns fetched',
+    ce_loadError: 'Error: ',
+    ce_fetchBtn: 'Fetch columns',
+    ce_emptyFields: 'Click "Fetch columns"',
+    ce_fillDbFields: 'Fill in host, database and user',
+    ce_dbSaved: 'Settings saved',
+    ce_dbLoaded: 'Settings loaded (password not included)',
+    ce_enterName: 'Enter config name',
+    ce_emptyConfig: 'Config is empty',
+    ce_configSaved: 'Config "{name}" saved',
+    ce_loadFailed: 'Load error: ',
+    ce_saveFailed: 'Save error: ',
+    ce_connector: 'Connector', 
+    ce_dtSqlLabel: 'SELECT query (use {filters})', 
+    ce_dtUrlLabel: 'Base URL (filters will be appended as ?region=North)',
+    ce_testConnection: 'Test connection',
+    ce_testOk:         'Connection successful',
+    ce_testError:      'Connection error: ',
+    confirmLargeExpand: 'Too many rows to display.\n\nAfter expanding, the grid will contain ~{millions}M rows which exceeds browser limits. Some rows at the bottom may not be reachable.\n\nConsider collapsing some row dimensions.\n\nClick OK to expand anyway, or Cancel to abort.',
+    ce_newConfig: 'New',
+    ce_deleteConfig:  'Delete',
+    ce_confirmDelete: 'Delete config "{name}"?',
+    ce_deleteOk:      'Config "{name}" deleted',
+    ce_deleteFailed:  'Delete error: ',
+  },
+};
+
+/**
+ * cache-manager.js
+ *
+ * Manages the dimension cache UI:
+ * - Renders dimension chips with cached/uncached state
+ * - Shows a fill meter and status label
+ * - Validates row count before adding a dimension to cache
+ * - Triggers cache refresh via the provider
+ */
+class CacheManager {
+
+  /**
+   * @param {object}   options
+   * @param {object}   options.provider       — data provider (RestProvider or ArrayProvider)
+   * @param {string[]} options.dimensions      — full list of dimensions
+   * @param {number}   options.maxCachedRows   — row limit for the cache
+   * @param {number}   options.initialCount    — current row count in cache
+   * @param {Function} options.onRefresh       — callback after cache refresh
+   * @param {string}   [options.lang='ru']     — UI language
+   */
+  constructor({ provider, dimensions, maxCachedRows, initialCount, onRefresh, lang = 'ru' }) {
+    this._provider   = provider;
+    this._dims       = dimensions;
+    this._maxRows    = maxCachedRows;
+    this._cached     = new Set(provider.cachedDimensions);
+    this._count      = initialCount;
+    this._stale      = false;
+    this._checking   = false;
+    this._toastTimer = null;
+    this._onRefresh  = onRefresh;
+    this._t          = (key, vars = {}) => {
+      let str = (I18N[lang] || I18N.ru)[key] || key;
+      for (const [k, v] of Object.entries(vars)) str = str.replace(`{${k}}`, v);
+      return str;
+    };
+
+    this._render();
+    this._bindRefresh();
+  }
+
+  // ── Render ────────────────────────────────────────────────────────────────
+
+  /** Renders all UI parts: chips, meter, status. */
+  _render() {
+    this._renderChips();
+    this._renderMeter();
+    this._renderStatus();
+  }
+
+  /** Renders dimension chips with cached/uncached state. */
+  _renderChips() {
+    const body = document.getElementById('cache-chips');
+    body.innerHTML = '';
+
+    for (const dim of this._dims) {
+      const chip = document.createElement('div');
+      chip.className   = 'cache-chip' + (this._cached.has(dim) ? ' is-cached' : '');
+      chip.dataset.dim = dim;
+      const def = CONFIG.fields[dim] || {};
+      chip.textContent = def.title || def.label || dim;
+      chip.title = this._cached.has(dim)
+        ? this._t('cacheRemove')
+        : this._t('cacheAdd');
+      chip.addEventListener('click', () => this._toggle(dim));
+      body.appendChild(chip);
+    }
+  }
+
+  /** Returns the chip element for a given dimension. */
+  _chip(dim) {
+    return document.querySelector(`.cache-chip[data-dim="${dim}"]`);
+  }
+
+  /** Updates the fill meter bar and label. */
+  _renderMeter() {
+    const fill  = document.getElementById('cache-meter-fill');
+    const label = document.getElementById('cache-meter-label');
+    const pct   = this._cached.size > 0
+      ? Math.min(this._count / this._maxRows * 100, 100)
+      : 0;
+    const cls   = pct < 60 ? 'ok' : pct < 85 ? 'warn' : 'danger';
+
+    fill.style.width = pct.toFixed(1) + '%';
+    fill.className   = `cache-meter-fill ${cls}`;
+
+    if (this._cached.size === 0) {
+      label.textContent = '—';
+      label.className   = 'cache-meter-label';
+    } else {
+      label.textContent = `~${this._count.toLocaleString()} / ${this._maxRows.toLocaleString()}`;
+      label.className   = `cache-meter-label ${cls}`;
+    }
+  }
+
+  /** Updates the cache status label and refresh button state. */
+  _renderStatus() {
+    const status = document.getElementById('cache-status');
+    const btn    = document.getElementById('btn-refresh-cache');
+
+    if (this._stale) {
+      status.textContent = this._t('cacheStale');
+      status.className   = 'cache-status stale';
+      btn.disabled       = false;
+      btn.classList.add('cache-refresh-btn--stale');
+    } else if (this._cached.size === 0) {
+      status.textContent = this._t('cacheEmpty');
+      status.className   = 'cache-status empty';
+      btn.disabled       = true;
+      btn.classList.remove('cache-refresh-btn--stale');
+    } else {
+      status.textContent = this._t('cacheActual');
+      status.className   = 'cache-status fresh';
+      btn.disabled       = true;
+      btn.classList.remove('cache-refresh-btn--stale');
+    }
+  }
+
+  // ── Toggle ────────────────────────────────────────────────────────────────
+
+  /**
+   * Toggles a dimension in/out of the cache set.
+   * When adding, runs a COUNT query to validate the row limit first.
+   * @param {string} dim — logical dimension name
+   */
+  async _toggle(dim) {
+    if (this._checking) return;
+
+    const chip = this._chip(dim);
+    if (!chip) return;
+
+    if (this._cached.has(dim)) {
+      this._cached.delete(dim);
+      chip.className = 'cache-chip';
+      chip.title     = this._t('cacheAdd');
+      this._stale    = true;
+      this._renderStatus();
+      this._refreshCountAsync();
+      return;
+    }
+
+    this._checking = true;
+    chip.className = 'cache-chip is-checking';
+
+    try {
+      const trial = [...this._cached, dim];
+      const count = await this._provider.countRows(trial);
+
+      if (count > this._maxRows) {
+        chip.className = 'cache-chip is-rejected';
+        this._showToast(
+          `«${dim}»: ~${count.toLocaleString()} — ${this._t('cacheExceeds')} ${this._maxRows.toLocaleString()}`
+        );
+        setTimeout(() => {
+          chip.className = 'cache-chip';
+          chip.title     = this._t('cacheAdd');
+        }, 700);
+      } else {
+        this._cached.add(dim);
+        this._count    = count;
+        this._stale    = true;
+        chip.className = 'cache-chip is-cached';
+        chip.title     = this._t('cacheRemove');
+      }
+    } catch (err) {
+      chip.className = 'cache-chip';
+      this._showToast(this._t('errorPrefix') + (err.message || err));
+    } finally {
+      this._checking = false;
+      this._renderMeter();
+      this._renderStatus();
+    }
+  }
+
+  /**
+   * Refreshes the row count for the current cached dimensions asynchronously.
+   * Used after removing a dimension from cache.
+   */
+  async _refreshCountAsync() {
+    if (this._cached.size === 0) {
+      this._count = 0;
+      this._renderMeter();
+      return;
+    }
+    try {
+      this._count = await this._provider.countRows([...this._cached]);
+    } catch {
+      this._count = 0;
+    }
+    this._renderMeter();
+  }
+
+  // ── Refresh ───────────────────────────────────────────────────────────────
+
+  /** Binds the "Refresh cache" button click handler. */
+  _bindRefresh() {
+    const btn  = document.getElementById('btn-refresh-cache');
+    const zone = document.querySelector('.cache-zone');
+
+    btn.addEventListener('click', async () => {
+      btn.disabled = true;
+      zone.classList.add('cache-zone--loading');
+      this._showFullscreenLoader(true);
+
+      try {
+        await this._provider.refreshCache([...this._cached]);
+        this._count = this._provider.cacheRows;
+        this._stale = false;
+        this._renderChips();
+        this._renderMeter();
+        this._renderStatus();
+        await this._onRefresh?.();
+      } catch (err) {
+        this._showToast(this._t('cacheRefreshError') + (err.message || err));
+      } finally {
+        this._showFullscreenLoader(false);
+        zone.classList.remove('cache-zone--loading');
+        this._renderStatus();
+      }
+    });
+  }
+
+  // ── Toast / Loader ────────────────────────────────────────────────────────
+
+  /**
+   * Shows or hides the fullscreen loading overlay.
+   * @param {boolean} on
+   */
+  _showFullscreenLoader(on) {
+    let el = document.getElementById('cache-fullscreen-loader');
+    if (on) {
+      if (!el) {
+        el = document.createElement('div');
+        el.id          = 'cache-fullscreen-loader';
+        el.textContent = this._t('loading');
+        document.body.appendChild(el);
+      }
+    } else {
+      el?.remove();
+    }
+  }
+
+  /**
+   * Shows a brief toast notification at the bottom of the screen.
+   * @param {string} msg — message to display
+   */
+  _showToast(msg) {
+    const toast = document.getElementById('cache-toast');
+    toast.textContent = msg;
+    toast.classList.add('visible');
+    clearTimeout(this._toastTimer);
+    this._toastTimer = setTimeout(() => toast.classList.remove('visible'), 3500);
+  }
+}
+
+export { DictionaryEncoder, ColumnStore, Aggregator, ArrayProvider, RestProvider, PivotGrid, FieldZones, FilterManager, CacheManager, I18N };