@sheetxl/sdk 0.8.0-beta.15 → 0.8.0-beta.16

package/types/src/table/_BuiltInPivotStyles.d.ts

@@ -0,0 +1,8 @@
+import { ITableStyle } from './ITableStyle';
+/**
+ * Excel's built-in pivot table styles, `PivotStyleLight1` to `PivotStyleDark28`, by lowercase
+ * name, in gallery order. Shown for pivot tables only.
+ */
+export declare const _BuiltInPivotStyles: () => ReadonlyMap<string, ITableStyle.Properties>;
+export declare const DefaultPivotStyleName: string;
+//# sourceMappingURL=_BuiltInPivotStyles.d.ts.map

package/types/src/table/_BuiltInTableStyles.d.ts

@@ -5,5 +5,4 @@ import { ITableStyle } from './ITableStyle';
  */
 export declare const _BuiltInTableStyles: () => ReadonlyMap<string, ITableStyle.Properties>;
 export declare const DefaultTableStyleName: string;
-export declare const DefaultPivotStyleName: string;
 //# sourceMappingURL=_BuiltInTableStyles.d.ts.map

package/types/src/type/ITypes.d.ts

@@ -40,8 +40,12 @@ export declare namespace ITypes {
      * `fixed + error` is not a state: a fixed block owns its cells, so a write into part of it is
      * refused at the write site rather than detected at calc. That is what lets these three be one
      * enum rather than two booleans.
+     *
+     * A fourth kind is the calculation engine's alone: `pivot`, the cells a pivot table lays out. It
+     * is never saved, and a cell never reports it ({@link ICell.getSpillKind}): a pivot table's
+     * cells are the table's, not an array's. A blocked pivot table is `error`.
      */
-    type FormulaArrayKind = 'dynamic' | 'fixed' | 'error';
+    type FormulaArrayKind = 'dynamic' | 'fixed' | 'error' | 'pivot';
     /**
      * Options for controlling selection behavior, including scrolling and focus.
      */

package/types/src/workbook/IWorkbook.d.ts

@@ -970,13 +970,19 @@ export declare namespace IWorkbook {
          * Absent when the source said nothing, which Excel reads as `userSet`.
          */
         updateLinks?: IExternalBookCollection.UpdateLinks;
+        /**
+         * The PivotTable Fields pane does not open when a pivot table is selected; absent, it does.
+         *
+         * @remarks
+         * Carried, not obeyed: SheetXL has no fields pane yet. Round-trips as `workbookPr@hidePivotFieldList`.
+         */
+        hiddenPivotFieldList?: true;
         /**
          * The workbook's pivot caches — the source snapshots its pivot tables summarize, each shared
          * by every table that references its id.
          *
          * @remarks
-         * Carried, not modeled — see {@link IPivotTable.CacheJSON}. The tables that summarize a cache
-         * are the modeled side; a table names its cache by {@link IPivotTable.getCacheId}.
+         * See {@link IPivotTable.CacheJSON}. A table names its cache by {@link IPivotTable.getCacheId}.
          */
         pivotCaches?: IPivotTable.CacheJSON[];
         /**

package/types/src/workbook/Workbook.d.ts

@@ -4,9 +4,10 @@ import { IListener } from '../listener';
 import { INamedCollection } from '../named';
 import { IExternalBookCollection } from '../externalBook';
 import { NamedTableSource } from '../table/_NamedTableSource';
-import { IPivotTableCollection } from '../pivot';
+import { IPivotTable, IPivotTableCollection } from '../pivot';
 import { IEmbeddedPart } from '../io/IEmbeddedPart';
 import { PivotCache } from '../pivot/PivotCache';
+import { PivotEngineModule } from '../pivot/_PivotEngine';
 import { ICommentCollection } from '../comment';
 import { IPersonCollection } from '../person';
 import { ICalculation } from '../calculation';
@@ -73,12 +74,15 @@ export declare class Workbook implements IWorkbook {
      * The workbook's pivot caches, by the id its tables reference them by.
      *
      * @remarks
-     * Carried, not modeled — see {@link IPivotTable.CacheJSON}. Held in part form rather than as
-     * the JSON it was read from because the resources a part can carry are model references, and
-     * their ids are assigned per save.
+     * See {@link IPivotTable.CacheJSON}. The part is held as a part rather than as the JSON it was
+     * read from because the resources a part can carry are model references, and their ids are
+     * assigned per save.
      */
     protected _pivotCaches: PivotCache[];
-    /** Every sheet's pivot tables, in sheet order — a walk, not a second store. */
+    /**
+     * Every sheet's pivot tables, in sheet order — a walk, not a second store. A hidden sheet's
+     * count: its tables' caches are written only for the tables found here.
+     */
     protected _pivotTableCollection: IPivotTableCollection;
     /** The people the workbook knows — comment authors. Not workbook state: never undone. */
     protected _people: IPersonCollection;
@@ -119,6 +123,8 @@ export declare class Workbook implements IWorkbook {
     protected _codeName: string | null;
     /** Carried, not obeyed — see {@link IWorkbook.JSON.updateLinks}. `null` when the source said nothing. */
     protected _updateLinks: IExternalBookCollection.UpdateLinks | null;
+    /** Carried, not obeyed — see {@link IWorkbook.JSON.hiddenPivotFieldList}. */
+    protected _hiddenPivotFieldList: boolean;
     /** See {@link IWorkbook.getProperties}. */
     protected _documentProperties: DocumentProperties;
     /** `null` follows the environment locale. */
@@ -401,10 +407,68 @@ export declare class Workbook implements IWorkbook {
     protected _sheetToWBEvent(listenerWB: ICellRange.Listener<any>): ICellRange.Listener<any>;
     /**
      * Each pivot cache's source is held through the sheet it names, once the sheets exist, so an
-     * insert above the source moves it (see `PivotCache`).
+     * insert above the source moves it and a rename of the table it names renames it (see
+     * `PivotCache`), and watched, so an edit to its cells marks it stale.
      * @internal
      */
     protected _holdPivotCaches(): void;
+    /** Where the cache with this id keeps its contents: the workbook's state. */
+    private _pivotCacheStore;
+    /**
+     * The cache with this id, or `null` when the workbook has none.
+     * @internal
+     */
+    _getPivotCache(cacheId: number): PivotCache | null;
+    /**
+     * What a new table's source names: a table, a defined name, or cells on a sheet, an address with no
+     * sheet being on `sheet`.
+     *
+     * @returns `null` when it names none of them.
+     * @internal
+     */
+    _pivotSourceOf(source: IPivotTableCollection.Source, sheet: IWorksheet): IPivotTable.CacheSourceJSON | null;
+    /**
+     * The cache a new table on `source` shares: the one naming the same source, unless its cells were
+     * edited since it read them, as a new table shows them as they are.
+     * @internal
+     */
+    _findPivotCache(source: IPivotTable.CacheSourceJSON): PivotCache | null;
+    /**
+     * Adds a cache in the caller's commit, held and watched as a loaded one is.
+     * @internal
+     */
+    _addPivotCache(model: PivotCache.Model): PivotCache;
+    /**
+     * Refreshes caches from their sources inside the caller's batch: each is read again from the
+     * cells its source names now, every table on it carried over to the new cache and laid out again
+     * (`PivotRefresh`). A table on another cache is left as it is. Async: each table's filters are
+     * evaluated over its new cache before it is laid out.
+     *
+     * @throws ExpectedError when a cache names no source this workbook holds, or holds fields a
+     * refresh does not rebuild yet; ProtectedError when a table on it is on a locked sheet.
+     * @internal
+     */
+    _refreshPivotCaches(cacheIds: ReadonlySet<number>, engine: PivotEngineModule): Promise<void>;
+    /**
+     * Refreshes the caches a file asks to be refreshed as it opens (`refreshOnLoad`), each on its own
+     * and as no step to undo. One it cannot refresh, its source gone or a table of it on a locked
+     * sheet, keeps what the file saved, silently, as Excel's does (`pivot-probes/probe-pivot-refresh-on-load.ps1`).
+     */
+    private _refreshPivotCachesOnLoad;
+    /**
+     * The cells a cache's source names now: its range on a sheet, the table it names without the
+     * total row, or what the defined name it names refers to now, whatever computes that.
+     * @internal
+     */
+    _pivotSourceRangeOf(source: IPivotTable.CacheSourceJSON | null): Promise<ICellRange | null>;
+    /** The defined name a cache's source names: the sheet's own with `sheet`, otherwise the workbook's. */
+    private _pivotSourceNamed;
+    /**
+     * Each slicer on pivot tables holds the tables it names, once the sheets exist, so a sheet
+     * renamed later is followed.
+     * @internal
+     */
+    protected _holdPivotSlicers(): void;
     /** @internal */
     protected _fromJSON(json: IWorkbook.JSON, uids?: readonly string[]): void;
     /**
@@ -484,6 +548,8 @@ interface State {
     lastId: number;
     sheetsCreated: Set<ISheet>;
     listenersSheets: Map<number, IListener.Remove>;
+    /** Each pivot cache's contents, by id: a refresh replaces one, and an undo puts it back. */
+    pivotCacheData: ReadonlyMap<number, PivotCache.Data>;
 }
 interface InternalCreateSheet {
     (

package/browser/esm/BrHplg4RuI5jOmmr.mjs

@@ -1,357 +0,0 @@
-/**
-* @license @sheetxl/sdk - SDK - A high-performance, embeddable spreadsheet engine. - v0.8.0-beta.15
-*
-* (C) 2026-present SheetXL Inc. & Michael T. Ford
-* License: The license can be found at https://www.sheetxl.com/license.
-*/
-import { t as e } from "./KsfZhE6ocmYobGjY.mjs";
-import { An as t, Dn as n, Mi as r, Mr as i, On as a, jn as o, kn as s, kr as c } from "./BGPT-k25jo0UhtT5.mjs";
-import { ExpectedError as l, messageKey as u, t as d } from "@sheetxl/utils";
-var f = "SlicerStyleLight1", p = "ascending", m = "showItemsWithDataAtTop", h = u("op.setSlicerCaption"), g = u("op.setSlicerStyle"), _ = u("op.setSlicerLayout"), v = u("op.setSlicerSort"), y = u("op.selectSlicerItems"), b = c.BuiltInSelectorNames.Display, x = Object.freeze({
-	selector: b,
-	scope: "column"
-}), S = Object.freeze({ transactional: !1 }), C = class extends e {
-	constructor(e) {
-		let t = s(e.json?.source)?.column ?? "", n = e.name;
-		!n && e.getMovable && (n = t || null), super({
-			...e,
-			name: n
-		}), this._formula = null, this._wired = null, this._binding = null, this._lossPending = !1, this._columnName = t;
-		let r = e.json;
-		r && this._updateState({ data: { ...r } }), r?.source && this._addWatch(r.source, (e) => {
-			this._formula = e.formula, this._wired ??= e.formula.getExpression(), this._checkSource(!1);
-		});
-	}
-	getType() {
-		return "slicer";
-	}
-	getTypeDescription() {
-		return "Slicer";
-	}
-	getDefaultAnchorType() {
-		return i.Type.Absolute;
-	}
-	getSource() {
-		let e = this._data()?.source ?? "", t = this._formula?.getExpression() ?? null;
-		return t === null || t === this._wired ? e : t;
-	}
-	getTable() {
-		return this._resolve()?.table ?? null;
-	}
-	getColumn() {
-		return this._resolve()?.column ?? null;
-	}
-	setName(e) {
-		let t = this._getWorkbook();
-		if (t && o(t, e, this) !== e) throw new l(d("error.slicer.nameTaken", { name: e }));
-		return super.setName(e);
-	}
-	getCaption() {
-		return this._data()?.caption ?? this._getColumnName();
-	}
-	setCaption(e, t) {
-		return this._set({ caption: e ?? void 0 }, h, t);
-	}
-	isShowCaption() {
-		return !0 !== this._data()?.hiddenCaption;
-	}
-	setShowCaption(e, t) {
-		return this._set({ hiddenCaption: !e || void 0 }, h, t);
-	}
-	getCacheName() {
-		return this._data()?.cacheName || (t(this._getWorkbook()).get(this) ?? n(this._getColumnName()));
-	}
-	getStyle() {
-		return this._data()?.style ?? f;
-	}
-	setStyle(e, t) {
-		return this._set({ style: e && e !== f ? e : void 0 }, g, t);
-	}
-	getSortOrder() {
-		return this._data()?.sortOrder ?? p;
-	}
-	setSortOrder(e, t) {
-		return this._set({ sortOrder: e === p ? void 0 : e }, v, t);
-	}
-	getCrossFilter() {
-		return this._data()?.crossFilter ?? m;
-	}
-	setCrossFilter(e, t) {
-		return this._set({ crossFilter: e === m ? void 0 : e }, v, t);
-	}
-	getColumnCount() {
-		return this._data()?.columnCount ?? 1;
-	}
-	setColumnCount(e, t) {
-		let n = Math.max(1, Math.trunc(e));
-		return this._set({ columnCount: n === 1 ? void 0 : n }, _, t);
-	}
-	getRowHeight() {
-		return this._data()?.rowHeight ?? 27;
-	}
-	setRowHeight(e, t) {
-		let n = Math.max(1, e);
-		return this._set({ rowHeight: n === 27 ? void 0 : n }, _, t);
-	}
-	isLockedPosition() {
-		return !0 === this._data()?.lockedPosition;
-	}
-	setLockedPosition(e, t) {
-		return this._set({ lockedPosition: e || void 0 }, _, t);
-	}
-	isFilterCleared() {
-		return !this.getColumn()?.getFilter()?.getCondition();
-	}
-	async getItems() {
-		let e = this.getColumn()?.getFilter();
-		if (!e) return w;
-		let t = await e.getItems(x), n = e.getCondition(), i = n ? function(e, t) {
-			let n = e.toJSON();
-			if (n.operator !== c.BuiltInOperatorNames.InSet) return () => !1;
-			let r = n.param ?? {}, i = /* @__PURE__ */ new Set(), a = r.items ?? [];
-			for (let e = 0; e < a.length; e++) a[e] !== null && i.add(String(a[e]).toLowerCase());
-			let o = r.dateGroups ?? [], s = t.dates?.[t.dates.length - 1] ?? null;
-			return (e) => {
-				if (e < 0) return !0 === r.blank;
-				if (i.has(t.items[e].text.toLowerCase())) return !0;
-				if (!s || o.length === 0) return !1;
-				let n = null;
-				for (let t = 0; t < s.runs.length && !n; t++) {
-					let r = s.runs[t];
-					r.min <= e && e <= r.max && (n = r.value ?? null);
-				}
-				if (!n) return !1;
-				for (let e = 0; e < o.length; e++) if (D(o[e], n)) return !0;
-				return !1;
-			};
-		}(n, t) : null, a = [];
-		for (let e = 0; e < t.items.length; e++) {
-			let n = t.items[e], r = !0 === n.passesOthers;
-			a.push({
-				item: {
-					key: n.text,
-					name: n.text,
-					value: n.value,
-					hasData: r,
-					isSelected: !i || (r ? n.checked : i(e))
-				},
-				firstRow: n.firstRow
-			});
-		}
-		let o = this.getSortOrder();
-		if (o === "dataSource") a.sort((e, t) => e.firstRow - t.firstRow);
-		else {
-			let t = e.getRange().getWorksheet().getRuntime().getLocaleProfile(), n = o === "descending" ? -1 : 1;
-			a.sort((e, i) => n * (r.compare(e.item.value, i.item.value, t) || r.compare(e.item.key, i.item.key, t)));
-		}
-		let s = null;
-		if (t.hasBlanks) {
-			let e = !0 === t.blanksPassOthers;
-			s = {
-				key: T,
-				name: d("slicer.blankItem"),
-				value: null,
-				hasData: e,
-				isSelected: !i || (e ? t.blanksChecked : i(-1))
-			};
-		}
-		let l = [], u = this.getCrossFilter();
-		if (u === "showItemsWithNoData") {
-			for (let e = 0; e < a.length; e++) l.push(a[e].item);
-			return s && l.push(s), l;
-		}
-		for (let e = 0; e < a.length; e++) a[e].item.hasData && l.push(a[e].item);
-		if (s?.hasData && l.push(s), u === "none") return l;
-		for (let e = 0; e < a.length; e++) a[e].item.hasData || l.push(a[e].item);
-		return s && !s.hasData && l.push(s), l;
-	}
-	async getItem(e) {
-		let t = await this.getItems();
-		for (let n = 0; n < t.length; n++) if (t[n].key === e) return t[n];
-		return null;
-	}
-	async selectItems(e, t) {
-		let n = this.getColumn()?.getFilter();
-		if (!n) return this;
-		if (!e || e.length === 0) return this.clearFilters(t);
-		let r = await n.getItems(x), i = new Set(e), a = r.dates?.[r.dates.length - 1] ?? null, o = a && a.runs.length > 0 ? a.runs[a.runs.length - 1].max : -1, s = [], l = [], u = !0, d = 0;
-		for (let e = 0; e < r.items.length; e++) {
-			if (!i.has(r.items[e].text)) {
-				u = !1;
-				continue;
-			}
-			if (e > o) {
-				s.push(r.items[e].text);
-				continue;
-			}
-			for (; a.runs[d].max < e;) d++;
-			let t = a.runs[d].value;
-			t && l[l.length - 1] !== t && l.push(t);
-		}
-		let f = r.hasBlanks && i.has(T);
-		if (r.hasBlanks && !f && (u = !1), u && !r.truncated) return this.clearFilters(t);
-		let p = { items: s };
-		return l.length > 0 && (p.dateGroups = l), f && (p.blank = !0), await n.setCondition({
-			selector: b,
-			operator: c.BuiltInOperatorNames.InSet,
-			param: p
-		}, !1, {
-			description: y,
-			...t
-		}), this;
-	}
-	async clearFilters(e) {
-		return await this.getColumn()?.getFilter()?.delete(e), this;
-	}
-	addListeners(e, t) {
-		let n = super.addListeners(e, t);
-		if (!this._binding) {
-			let e = this._resolve();
-			e && this._bind(e);
-		}
-		return n;
-	}
-	toJSON(e) {
-		let t = this._data();
-		if (!t) return null;
-		let n = this.getSource();
-		return n ? {
-			...t,
-			source: n
-		} : t;
-	}
-	get isISlicer() {
-		return !0;
-	}
-	get [Symbol.toStringTag]() {
-		return "[Slicer]";
-	}
-	toString() {
-		return this.getTypeDescription();
-	}
-	_attach() {
-		this._checkSource(!0);
-	}
-	_data() {
-		return this._getState()?.data ?? null;
-	}
-	_getWorkbook() {
-		try {
-			return this.getMovable()?.getRange().getWorksheet().getWorkbook() ?? null;
-		} catch {
-			return null;
-		}
-	}
-	_resolve() {
-		if (this._closed) return null;
-		let e = s(this.getSource());
-		if (!e) return null;
-		let t = a(this._getWorkbook(), e.table), n = t?.getColumnByName(e.column) ?? null;
-		return n ? (this._columnName = n.getName(), {
-			table: t,
-			column: n
-		}) : null;
-	}
-	_getColumnName() {
-		return this._resolve()?.column.getName() ?? this._columnName;
-	}
-	_checkSource(e) {
-		if (this._closed || this.isDeleted()) return;
-		let t = this._resolve();
-		if (t) return void this._bind(t);
-		let n = this._getTransactions();
-		n.isRestoring() || (n.isOpenTransaction() ? this.delete() : e && !this._lossPending && (this._lossPending = !0, queueMicrotask(() => {
-			if (this._lossPending = !1, this._closed || this.isDeleted() || n.isOpenTransaction() || n.isRestoring()) return;
-			let e = this._resolve();
-			e ? this._bind(e) : n.amend(n.getCurrentCommit(!1).getId(), () => {
-				this.delete();
-			});
-		})));
-	}
-	_bind(e) {
-		let t = e.table;
-		if (this._binding?.table !== t) {
-			this._unbind();
-			let e = () => {
-				this._checkSource(!0);
-			};
-			this._binding = {
-				table: t,
-				removeTable: t.addListeners({
-					onFilterChange: () => {
-						this._notify("onSelectionChange");
-					},
-					onAnyChange: () => {
-						this._checkSource(!0), this._bindRange(!0);
-					},
-					onAnchorCoordsChange: () => {
-						this._bindRange(!0);
-					},
-					onDelete: e
-				}, S),
-				coords: null,
-				removeRange: null
-			};
-		}
-		this._bindRange(!1);
-	}
-	_bindRange(e) {
-		let t = this._binding;
-		if (!t || this._closed) return;
-		let n = this.getColumn()?.getFilter()?.getRange() ?? null, r = n ? n.getCoords() : null;
-		(r && t.coords ? r.rowStart !== t.coords.rowStart || r.rowEnd !== t.coords.rowEnd || r.colStart !== t.coords.colStart || r.colEnd !== t.coords.colEnd : r !== t.coords) && (t.removeRange?.(), t.removeRange = n?.addListener(() => {
-			this._notify("onItemsChange");
-		}, {
-			ignoreAddressChanges: !0,
-			...S
-		}) ?? null, t.coords = r, e && this._notify("onItemsChange"));
-	}
-	_unbind() {
-		let e = this._binding;
-		e && (this._binding = null, e.removeTable(), e.removeRange?.());
-	}
-	_notify(e) {
-		this._closed || this.isDeleted() || (this._emitter.notify(e), this._emitter.notify("onAnyChange"));
-	}
-	_set(e, t, n) {
-		this._protectionCheck(t);
-		let r = this._data();
-		if (!r) return this;
-		let i = {
-			...r,
-			...e
-		};
-		for (let t in e) i[t] === void 0 && delete i[t];
-		return this._updateState({ data: i }, {
-			...n,
-			description: t
-		}, ["onAnyChange"]), this;
-	}
-	_processDelete() {
-		this._unbind(), super._processDelete();
-	}
-	_processRestoreOrRevert(e, t) {
-		if (super._processRestoreOrRevert(e, t), this.isDeleted()) return void this._unbind();
-		let n = this._resolve();
-		n && this._bind(n);
-	}
-	close() {
-		this._unbind(), super.close();
-	}
-}, w = Object.freeze([]), T = "", E = [
-	"year",
-	"month",
-	"day",
-	"hour",
-	"minute",
-	"second"
-];
-function D(e, t) {
-	for (let n = 0; n < E.length; n++) {
-		let r = E[n];
-		if (e[r] !== t[r]) return !1;
-		if (r === e.group) return !0;
-	}
-	return !0;
-}
-export { C as Slicer };