@univerjs-pro/sheets-pivot-chart 1.0.0

package/lib/types/facade/f-event.d.ts

@@ -0,0 +1,56 @@
+import type { IPivotChartCalculationResult, IPivotChartRuntimeState } from '@univerjs-pro/pivot-chart';
+import type { ISheetsPivotChartModelChange } from '@univerjs-pro/sheets-pivot-chart';
+import type { IEventBase } from '@univerjs/core/facade';
+import { FEventName } from '@univerjs/core/facade';
+/** Common identity delivered by PivotChart lifecycle events. */
+export interface IPivotChartEventParams extends IEventBase {
+    unitId: string;
+    subUnitId: string;
+    pivotChartId: string;
+}
+/** PivotChart definition change event parameters. */
+export interface IPivotChartChangedEventParams extends IPivotChartEventParams {
+    /** Identifies whether the persisted definition or Sheet Drawing changed. */
+    kind: 'definition' | 'drawing';
+    /** Present when {@link kind} is `definition`. */
+    change?: ISheetsPivotChartModelChange;
+}
+/** PivotChart calculation state event parameters. */
+export interface IPivotChartDataStateChangedEventParams extends IPivotChartEventParams {
+    state: IPivotChartRuntimeState;
+}
+/** PivotChart completed-render data event parameters. */
+export interface IPivotChartRenderedEventParams extends IPivotChartEventParams {
+    result: IPivotChartCalculationResult;
+}
+/** @ignore */
+interface IFSheetsPivotChartEventNameMixin {
+    readonly PivotChartAdded: 'PivotChartAdded';
+    readonly PivotChartRemoved: 'PivotChartRemoved';
+    readonly PivotChartChanged: 'PivotChartChanged';
+    readonly PivotChartRendered: 'PivotChartRendered';
+    readonly PivotChartDataStateChanged: 'PivotChartDataStateChanged';
+}
+/** @ignore */
+interface ISheetsPivotChartEventParamConfig {
+    PivotChartAdded: IPivotChartEventParams;
+    PivotChartRemoved: IPivotChartEventParams;
+    PivotChartChanged: IPivotChartChangedEventParams;
+    PivotChartRendered: IPivotChartRenderedEventParams;
+    PivotChartDataStateChanged: IPivotChartDataStateChangedEventParams;
+}
+/** @ignore */
+export declare class FSheetsPivotChartEventNameMixin extends FEventName implements IFSheetsPivotChartEventNameMixin {
+    get PivotChartAdded(): 'PivotChartAdded';
+    get PivotChartRemoved(): 'PivotChartRemoved';
+    get PivotChartChanged(): 'PivotChartChanged';
+    get PivotChartRendered(): 'PivotChartRendered';
+    get PivotChartDataStateChanged(): 'PivotChartDataStateChanged';
+}
+declare module '@univerjs/core/facade' {
+    interface FEventName extends IFSheetsPivotChartEventNameMixin {
+    }
+    interface IEventParamConfig extends ISheetsPivotChartEventParamConfig {
+    }
+}
+export {};

package/lib/types/facade/f-pivot-chart-builder.d.ts

@@ -0,0 +1,73 @@
+import type { IChartBuilderTypeMap } from '@univerjs-pro/engine-chart/facade';
+import type { IPivotChartControls, PivotChartTypeString } from '@univerjs-pro/pivot-chart';
+import type { ChartAnchorSpec } from '@univerjs-pro/sheets-chart';
+import type { IPivotChartTableSourceSpec, ISheetPivotChartInfo, PivotChartRangeInput, PivotChartSourceSpec } from '@univerjs-pro/sheets-pivot-chart';
+import type { FPivotTable } from '@univerjs-pro/sheets-pivot/facade';
+type PivotChartUnsafeBuilderMethod = 'setSource' | 'setCategoryField' | 'setCategoryFields' | 'clearCategoryField' | 'clearCategoryFields' | 'setMultiLevelCategoryAxis' | 'setValueFields' | 'clearValueFields' | 'setAggregation' | 'clearAggregation';
+type PivotChartEngineBuilder<T extends PivotChartTypeString> = Omit<IChartBuilderTypeMap<PivotChartRangeInput, PivotChartSourceSpec, ISheetPivotChartInfo>[T], PivotChartUnsafeBuilderMethod>;
+type RebindPivotChartBuilder<TBuilder, TExtension> = {
+    [K in keyof TBuilder]: TBuilder[K] extends (...args: infer TArgs) => infer TResult ? TResult extends TBuilder ? (...args: TArgs) => RebindPivotChartBuilder<TBuilder, TExtension> & TExtension : (...args: TArgs) => TResult : TBuilder[K];
+};
+interface ISheetPivotChartBuilderExtensionMethods {
+    /**
+     * Links the new PivotChart to an existing PivotTable-owned report.
+     * @param {FPivotTable} pivotTable The PivotTable that owns the shared PivotModel.
+     * @returns {this} This Builder for chaining.
+     */
+    setPivotTable(pivotTable: FPivotTable): this;
+    /**
+     * Links the new PivotChart using a stable PivotTable reference.
+     * @param {IPivotChartTableSourceSpec['pivotTableRef']} pivotTableRef The referenced PivotTable identity.
+     * @returns {this} This Builder for chaining.
+     */
+    setPivotTableReference(pivotTableRef: IPivotChartTableSourceSpec['pivotTableRef']): this;
+    /**
+     * Sets the worksheet cell anchor used when inserting the PivotChart.
+     * @param {ChartAnchorSpec} anchor A1 notation or a zero-based row and column anchor.
+     * @returns {this} This Builder for chaining.
+     */
+    setPosition(anchor: ChartAnchorSpec): this;
+    /**
+     * Sets the optional user-facing PivotChart name.
+     * @param {string} name The PivotChart name.
+     * @returns {this} This Builder for chaining.
+     */
+    setName(name: string): this;
+    /**
+     * Merges persisted PivotChart button visibility controls.
+     * @param {Partial<IPivotChartControls>} controls The controls to override.
+     * @returns {this} This Builder for chaining.
+     */
+    setControls(controls: Partial<IPivotChartControls>): this;
+    /**
+     * Shows or hides Pivot field buttons.
+     * @param {boolean} visible Whether field buttons are visible.
+     * @returns {this} This Builder for chaining.
+     */
+    setFieldButtonsVisible(visible: boolean): this;
+    /**
+     * Shows or hides category hierarchy expand and collapse buttons.
+     * @param {boolean} visible Whether expand and collapse buttons are visible.
+     * @returns {this} This Builder for chaining.
+     */
+    setExpandCollapseButtonsVisible(visible: boolean): this;
+}
+export interface ISheetPivotChartBuilderMethods extends ISheetPivotChartBuilderExtensionMethods {
+    /**
+     * Sets a range source that creates an independently owned PivotModel.
+     *
+     * A local A1 string and an `IRange` are resolved against the worksheet that created the Builder.
+     * A complete range identity can reference another worksheet in the supported Unit boundary.
+     *
+     * @param {PivotChartRangeInput} source The range source.
+     * @returns {this} This Builder for chaining.
+     */
+    setSource(source: PivotChartRangeInput): this;
+}
+/** A type-specific PivotChart Builder with worksheet insertion options. */
+export type FSheetPivotChartBuilderOf<T extends PivotChartTypeString> = RebindPivotChartBuilder<PivotChartEngineBuilder<T>, ISheetPivotChartBuilderMethods> & ISheetPivotChartBuilderMethods;
+/** A prelinked PivotChart Builder whose report source cannot be replaced. */
+export type FLinkedSheetPivotChartBuilderOf<T extends PivotChartTypeString> = Omit<FSheetPivotChartBuilderOf<T>, 'setSource' | 'setPivotTable' | 'setPivotTableReference'>;
+/** A Builder copied from a live PivotChart whose report source cannot be replaced. */
+export type FBoundSheetPivotChartBuilderOf<T extends PivotChartTypeString> = FLinkedSheetPivotChartBuilderOf<T>;
+export {};

package/lib/types/facade/f-pivot-chart.d.ts

@@ -0,0 +1,487 @@
+import type { ChartAppearanceTarget, ChartLegendSpec, ChartSubtitleSpec, ChartTitleSpec, IChartAppearanceSpec, InvalidValueType } from '@univerjs-pro/engine-chart';
+import type { IPivotTableLabelFieldJSON, IPivotTableShowDataAsInfo, IPivotTableSnapshot, IPivotTableSortInfo, IPivotTableValueFieldJSON, IPivotTableValueFilter, IValueFilterInfoItem, PivotDateGroupFieldDateTypeEnum } from '@univerjs-pro/engine-pivot';
+import type { IPivotChartControls, IPivotChartPivotTableReference, PivotChartTypeString } from '@univerjs-pro/pivot-chart';
+import type { ChartAnchorSpec } from '@univerjs-pro/sheets-chart';
+import type { IUnitRangeNameWithSubUnitId } from '@univerjs-pro/sheets-pivot';
+import type { IPivotChartDataFieldInfo, IPivotChartFieldSettingOptions, ISheetPivotChartInfo } from '@univerjs-pro/sheets-pivot-chart';
+import type { DeepReadonly, Injector } from '@univerjs/core';
+import type { FBoundSheetPivotChartBuilderOf } from './f-pivot-chart-builder';
+import { PivotTableFiledAreaEnum, PivotTableValuePositionEnum } from '@univerjs-pro/engine-pivot';
+import { PivotChartSourceKind } from '@univerjs-pro/pivot-chart';
+import { FPivotTable } from '@univerjs-pro/sheets-pivot/facade';
+import { FBase } from '@univerjs/core/facade';
+/**
+ * A live PivotChart hosted by a worksheet.
+ *
+ * The Chart visual and Drawing placement belong to this PivotChart. The effective Pivot report
+ * belongs either to this chart (range source) or to the referenced PivotTable (linked source).
+ * Linked PivotCharts therefore share field, filter, sort, Show Values As, and collapse changes.
+ *
+ * @example Create an owned PivotChart
+ * ```ts
+ * import '@univerjs-pro/sheets-pivot-chart/facade';
+ *
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sales');
+ * const info = fWorksheet
+ *   .newPivotChart(univerAPI.Enum.ChartTypeString.Column)
+ *   .setSource('A1:G100')
+ *   .setPosition('J2')
+ *   .setSize(640, 360)
+ *   .setTitle('Sales by region')
+ *   .build();
+ * const fPivotChart = await fWorksheet.insertPivotChart(info);
+ * const sourceFields = fPivotChart.getSourceFieldsInfo();
+ * await fPivotChart.addField(sourceFields[0].id, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0);
+ * await fPivotChart.addField(sourceFields[5].id, univerAPI.Enum.PivotTableFiledAreaEnum.Value, 0);
+ * ```
+ *
+ * @example Link multiple PivotCharts to one PivotTable
+ * ```ts
+ * import '@univerjs-pro/sheets-pivot-chart/facade';
+ *
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Dashboard');
+ * const fPivotTable = fWorkbook.getPivotTableById('pivot-table-1');
+ * if (!fWorksheet || !fPivotTable) throw new Error('Pivot source is unavailable.');
+ *
+ * const first = await fWorksheet.insertPivotChart(
+ *   fPivotTable.newChart(univerAPI.Enum.ChartTypeString.Column).setPosition('A1').build()
+ * );
+ * const second = await fWorksheet.insertPivotChart(
+ *   fPivotTable.newChart(univerAPI.Enum.ChartTypeString.Line).setPosition('J1').build()
+ * );
+ * const rowFieldId = first.getFieldIdsByArea(univerAPI.Enum.PivotTableFiledAreaEnum.Row)[0];
+ * await first.setLabelSort(rowFieldId, { type: univerAPI.Enum.PivotDataFieldSortOperatorEnum.ascending });
+ * console.log(second.getFieldsConfig()); // Reads the same PivotTable-owned report.
+ * ```
+ *
+ * @example Configure Show Values As and a value filter
+ * ```ts
+ * const rowFieldId = fPivotChart.getFieldIdsByArea(univerAPI.Enum.PivotTableFiledAreaEnum.Row)[0];
+ * const valueFieldId = fPivotChart.getFieldIdsByArea(univerAPI.Enum.PivotTableFiledAreaEnum.Value)[0];
+ * await fPivotChart.setShowDataAs(valueFieldId, {
+ *   type: univerAPI.Enum.PivotShowAsTypeEnum.percentOfGrandTotal,
+ *   baseFieldId: '',
+ *   baseItem: '',
+ * });
+ * await fPivotChart.setValueFilter(rowFieldId, {
+ *   operator: univerAPI.Enum.PivotFilterOperatorEnum.valueGreaterThan,
+ *   expected: 1000,
+ *   valueFieldId,
+ * });
+ * ```
+ *
+ * @example Handle an unavailable linked PivotTable
+ * ```ts
+ * if (fPivotChart.isLinkedToPivotTable() && !fPivotChart.getPivotTable()) {
+ *   // Report writes resolve to false until the same PivotTable ID becomes available again.
+ *   console.log(await fPivotChart.resetFields());
+ *   // Per-chart visual changes remain available.
+ *   fPivotChart.setTheme('default');
+ * }
+ * ```
+ *
+ * @hideconstructor
+ */
+export declare class FSheetPivotChart extends FBase {
+    readonly unitId: string;
+    readonly subUnitId: string;
+    readonly pivotChartId: string;
+    protected readonly _injector: Injector;
+    constructor(unitId: string, subUnitId: string, pivotChartId: string, _injector: Injector);
+    /**
+     * Returns the stable identifier of this PivotChart.
+     * @returns {string} The PivotChart identifier.
+     */
+    getId(): string;
+    /**
+     * Returns the current PivotChart type.
+     * @returns {PivotChartTypeString} The supported Chart type.
+     */
+    getType(): PivotChartTypeString;
+    /**
+     * Returns detached information that can be inspected, copied, or passed to {@link update}.
+     * @returns {DeepReadonly<ISheetPivotChartInfo>} A defensive PivotChart snapshot.
+     */
+    getInfo(): DeepReadonly<ISheetPivotChartInfo>;
+    /**
+     * Creates a detached, source-locked Builder prefilled from this PivotChart.
+     * @returns {FBoundSheetPivotChartBuilderOf<PivotChartTypeString>} A source-locked Builder.
+     */
+    toBuilder(): FBoundSheetPivotChartBuilderOf<PivotChartTypeString>;
+    /**
+     * Creates a detached, source-locked Builder converted to another supported Chart type.
+     * @param {T} type The target supported Chart type.
+     * @returns {FBoundSheetPivotChartBuilderOf<T>} A source-locked Builder for the target type.
+     */
+    toBuilder<T extends PivotChartTypeString>(type: T): FBoundSheetPivotChartBuilderOf<T>;
+    /**
+     * Atomically updates visual configuration, controls, name, and placement.
+     *
+     * The source mode, source identity, and live PivotModel are locked. Use {@link setSourceRange}
+     * or the field APIs for report changes.
+     *
+     * @param {ISheetPivotChartInfo} info Detached information created by {@link getInfo} or {@link toBuilder}.
+     * @returns {Promise<this>} This live PivotChart after the command is accepted.
+     * @throws If the source, report fields, Chart type, or Drawing layout is invalid.
+     */
+    update(info: ISheetPivotChartInfo): Promise<this>;
+    /**
+     * Returns whether this PivotChart owns a range report or references a PivotTable.
+     * @returns {PivotChartSourceKind} The current source ownership kind.
+     */
+    getSourceKind(): PivotChartSourceKind;
+    /**
+     * Returns whether this PivotChart shares a PivotTable-owned report.
+     * @returns {boolean} `true` for a linked PivotChart.
+     */
+    isLinkedToPivotTable(): boolean;
+    /**
+     * Returns the effective source range for owned and available linked reports.
+     * @returns {IUnitRangeNameWithSubUnitId | undefined} A defensive range snapshot, if available.
+     */
+    getSourceRangeInfo(): IUnitRangeNameWithSubUnitId | undefined;
+    /**
+     * Updates the effective report source without changing its ownership mode.
+     *
+     * Linked PivotCharts delegate this operation to their referenced PivotTable.
+     *
+     * @param {IUnitRangeNameWithSubUnitId} source The complete source range identity.
+     * @returns {Promise<boolean>} Whether the source update was accepted.
+     */
+    setSourceRange(source: IUnitRangeNameWithSubUnitId): Promise<boolean>;
+    /**
+     * Returns the stable linked PivotTable reference.
+     * @returns {DeepReadonly<IPivotChartPivotTableReference> | undefined} The reference for linked charts.
+     */
+    getPivotTableReference(): DeepReadonly<IPivotChartPivotTableReference> | undefined;
+    /**
+     * Returns a live facade for the referenced PivotTable.
+     * @returns {FPivotTable | null} The shared PivotTable, or `null` while the reference is unavailable.
+     */
+    getPivotTable(): FPivotTable | null;
+    /**
+     * Returns the current effective report fields configuration.
+     * @returns {DeepReadonly<IPivotTableSnapshot> | undefined} A defensive report snapshot, if available.
+     */
+    getFieldsConfig(): DeepReadonly<IPivotTableSnapshot> | undefined;
+    /**
+     * Returns source fields available to the effective Pivot report.
+     * @returns {IPivotChartDataFieldInfo[]} Defensive field information in source order.
+     */
+    getSourceFieldsInfo(): IPivotChartDataFieldInfo[];
+    /**
+     * Returns one report field setting.
+     * @param {string} fieldId The table-field identifier.
+     * @returns {IPivotTableValueFieldJSON | IPivotTableLabelFieldJSON | undefined} A defensive field snapshot.
+     */
+    getFieldSetting(fieldId: string): IPivotTableValueFieldJSON | IPivotTableLabelFieldJSON | undefined;
+    /**
+     * Returns table-field identifiers in one report area.
+     * @param {PivotTableFiledAreaEnum} area The Pivot report area.
+     * @returns {string[]} Table-field identifiers in display order.
+     */
+    getFieldIdsByArea(area: PivotTableFiledAreaEnum): string[];
+    /**
+     * Replaces all report fields in one command and one Pivot query.
+     * @param {IPivotTableSnapshot} config The complete fields configuration.
+     * @returns {Promise<boolean>} Whether the report update was accepted.
+     */
+    setFieldsConfig(config: IPivotTableSnapshot): Promise<boolean>;
+    /**
+     * Removes all fields or only fields in one report area.
+     * @param {PivotTableFiledAreaEnum} [area] The area to clear; omit it to clear all report fields.
+     * @returns {Promise<boolean>} Whether the report update was accepted.
+     */
+    resetFields(area?: PivotTableFiledAreaEnum): Promise<boolean>;
+    /**
+     * Adds one source field to a report area.
+     * @param {string | number} dataFieldIdOrIndex A source-field identifier or zero-based source index.
+     * @param {PivotTableFiledAreaEnum} area The target report area.
+     * @param {number} index The zero-based target index.
+     * @returns {Promise<boolean>} Whether the field was added.
+     */
+    addField(dataFieldIdOrIndex: string | number, area: PivotTableFiledAreaEnum, index: number): Promise<boolean>;
+    /**
+     * Removes report fields by their table-field identifiers.
+     * @param {string[]} fieldIds The table-field identifiers to remove together.
+     * @returns {Promise<boolean>} Whether the fields were removed.
+     */
+    removeField(fieldIds: string[]): Promise<boolean>;
+    /**
+     * Moves one report field to a zero-based area index.
+     * @param {string} fieldId The table-field identifier.
+     * @param {PivotTableFiledAreaEnum} area The target area.
+     * @param {number} index The zero-based target index.
+     * @returns {Promise<boolean>} Whether the field was moved.
+     */
+    updateFieldPosition(fieldId: string, area: PivotTableFiledAreaEnum, index: number): Promise<boolean>;
+    /**
+     * Moves the synthetic multiple-values field.
+     * @param {PivotTableValuePositionEnum} position The row, column, or absent position.
+     * @param {number} index The zero-based row or column field index.
+     * @returns {Promise<boolean>} Whether the value position was updated.
+     */
+    updateValuePosition(position: PivotTableValuePositionEnum, index: number): Promise<boolean>;
+    /**
+     * Updates a report field display name, format, aggregation, or Show Values As rule.
+     * @param {string} fieldId The table-field identifier.
+     * @param {IPivotChartFieldSettingOptions} setting The field properties to update together.
+     * @returns {Promise<boolean>} Whether the field setting was updated.
+     */
+    setFieldSetting(fieldId: string, setting: IPivotChartFieldSettingOptions): Promise<boolean>;
+    /**
+     * Renames a report field.
+     * @param {string} fieldId The table-field identifier.
+     * @param {string} name The new display name.
+     * @returns {Promise<boolean>} Whether the field was renamed.
+     */
+    renameField(fieldId: string, name: string): Promise<boolean>;
+    /**
+     * Returns the Show Values As rule for a value field.
+     * @param {string} fieldId The value table-field identifier.
+     * @returns {IPivotTableShowDataAsInfo | undefined} A defensive rule snapshot.
+     */
+    getShowDataAs(fieldId: string): IPivotTableShowDataAsInfo | undefined;
+    /**
+     * Sets the Show Values As rule for a value field.
+     * @param {string} fieldId The value table-field identifier.
+     * @param {IPivotTableShowDataAsInfo} value The Show Values As rule.
+     * @returns {Promise<boolean>} Whether the rule was updated.
+     */
+    setShowDataAs(fieldId: string, value: IPivotTableShowDataAsInfo): Promise<boolean>;
+    /**
+     * Restores normal value display for a value field.
+     * @param {string} fieldId The value table-field identifier.
+     * @returns {Promise<boolean>} Whether the rule was reset.
+     */
+    resetShowDataAs(fieldId: string): Promise<boolean>;
+    /**
+     * Sets label sorting for a row or column field.
+     * @param {string} fieldId The row or column table-field identifier.
+     * @param {IPivotTableSortInfo} info The sort rule.
+     * @returns {Promise<boolean>} Whether sorting was updated.
+     */
+    setLabelSort(fieldId: string, info: IPivotTableSortInfo): Promise<boolean>;
+    /**
+     * Clears label sorting for a row or column field.
+     * @param {string} fieldId The row or column table-field identifier.
+     * @returns {Promise<boolean>} Whether sorting was cleared.
+     */
+    clearLabelSort(fieldId: string): Promise<boolean>;
+    /**
+     * Sets a manual label filter for a report field.
+     * @param {string} fieldId The table-field identifier.
+     * @param {string[]} items The selected item keys.
+     * @param {boolean} [isAll] Whether all current items are selected.
+     * @returns {Promise<boolean>} Whether the filter was updated.
+     */
+    setLabelManualFilter(fieldId: string, items: string[], isAll?: boolean): Promise<boolean>;
+    /**
+     * Returns the value filter owned by a row or column field.
+     * @param {string} fieldId The row or column table-field identifier.
+     * @returns {IPivotTableValueFilter | undefined} A defensive filter snapshot.
+     */
+    getValueFilter(fieldId: string): IPivotTableValueFilter | undefined;
+    /**
+     * Returns value filters in evaluation order.
+     * @returns {IValueFilterInfoItem[]} Defensive ordered filter snapshots.
+     */
+    getValueFilters(): IValueFilterInfoItem[];
+    /**
+     * Sets, replaces, or removes the value filter owned by a row or column field.
+     * @param {string} fieldId The row or column table-field identifier.
+     * @param {Omit<IPivotTableValueFilter, 'type'>} [filter] The rule, or `undefined` to remove it.
+     * @returns {Promise<boolean>} Whether the value filter was updated.
+     */
+    setValueFilter(fieldId: string, filter?: Omit<IPivotTableValueFilter, 'type'>): Promise<boolean>;
+    /**
+     * Removes the value filter owned by a row or column field.
+     * @param {string} fieldId The row or column table-field identifier.
+     * @returns {Promise<boolean>} Whether the value filter was removed.
+     */
+    clearValueFilter(fieldId: string): Promise<boolean>;
+    /**
+     * Groups a row or column date field using a Pivot date interval.
+     * @param {string} fieldId The source date or existing date-group table-field identifier.
+     * @param {PivotDateGroupFieldDateTypeEnum} dateType The requested date interval.
+     * @returns {Promise<boolean>} Whether the date group was updated.
+     */
+    setDateGroupType(fieldId: string, dateType: PivotDateGroupFieldDateTypeEnum): Promise<boolean>;
+    /**
+     * Collapses or expands a row hierarchy field or one item.
+     * @param {string} fieldId The row table-field identifier.
+     * @param {boolean} collapse Whether to collapse the target.
+     * @param {string} [item] An optional item key; omit it to target the whole field.
+     * @returns {Promise<boolean>} Whether the hierarchy state was updated.
+     */
+    setCollapse(fieldId: string, collapse: boolean, item?: string): Promise<boolean>;
+    /**
+     * Expands the category hierarchy through the requested row field.
+     * @param {string} fieldId The deepest row table-field identifier to display.
+     * @returns {Promise<boolean>} Whether the category level was updated.
+     */
+    setCategoryLevel(fieldId: string): Promise<boolean>;
+    /**
+     * Returns resolved PivotChart button visibility controls.
+     * @returns {DeepReadonly<IPivotChartControls>} A defensive resolved controls snapshot.
+     */
+    getControls(): DeepReadonly<IPivotChartControls>;
+    /**
+     * Sets the current supported Chart type.
+     * @param {PivotChartTypeString} type The target supported type.
+     * @returns {this} This PivotChart for chaining.
+     * @throws If the type is not supported by PivotChart.
+     */
+    setType(type: PivotChartTypeString): this;
+    /**
+     * Sets the Chart title.
+     * @param {ChartTitleSpec} value The title specification.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setTitle(value: ChartTitleSpec): this;
+    /**
+     * Clears the Chart title.
+     * @returns {this} This PivotChart for chaining.
+     */
+    clearTitle(): this;
+    /**
+     * Sets the Chart subtitle.
+     * @param {ChartSubtitleSpec} value The subtitle specification.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setSubtitle(value: ChartSubtitleSpec): this;
+    /**
+     * Clears the Chart subtitle.
+     * @returns {this} This PivotChart for chaining.
+     */
+    clearSubtitle(): this;
+    /**
+     * Sets the Chart legend.
+     * @param {ChartLegendSpec} value The legend specification.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setLegend(value: ChartLegendSpec): this;
+    /**
+     * Clears the Chart legend.
+     * @returns {this} This PivotChart for chaining.
+     */
+    clearLegend(): this;
+    /**
+     * Sets the Chart theme.
+     * @param {string} name The registered theme name.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setTheme(name: string): this;
+    /**
+     * Clears the Chart theme.
+     * @returns {this} This PivotChart for chaining.
+     */
+    clearTheme(): this;
+    /**
+     * Sets an explicit series palette.
+     * @param {readonly string[]} colors The series colors.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setPalette(colors: readonly string[]): this;
+    /**
+     * Clears the explicit series palette.
+     * @returns {this} This PivotChart for chaining.
+     */
+    clearPalette(): this;
+    /**
+     * Sets common Chart appearance.
+     * @param {IChartAppearanceSpec} value The appearance overrides.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setAppearance(value: IChartAppearanceSpec): this;
+    /**
+     * Clears all or one common Chart appearance property.
+     * @param {ChartAppearanceTarget} [target] The property to clear; omit it to clear all appearance overrides.
+     * @returns {this} This PivotChart for chaining.
+     */
+    clearAppearance(target?: ChartAppearanceTarget): this;
+    /**
+     * Enables or disables automatic gradient fill.
+     * @param {boolean} value Whether automatic gradients are enabled.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setAutoGradientFill(value: boolean): this;
+    /**
+     * Restores the default automatic-gradient behavior.
+     * @returns {this} This PivotChart for chaining.
+     */
+    resetAutoGradientFill(): this;
+    /**
+     * Sets how invalid Pivot values are rendered.
+     * @param {InvalidValueType} value The invalid-value strategy.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setInvalidValueStrategy(value: InvalidValueType): this;
+    /**
+     * Restores the default invalid-value strategy.
+     * @returns {this} This PivotChart for chaining.
+     */
+    resetInvalidValueStrategy(): this;
+    /**
+     * Merges PivotChart button visibility controls.
+     * @param {Partial<IPivotChartControls>} controls The controls to override.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setControls(controls: Partial<IPivotChartControls>): this;
+    /**
+     * Shows or hides all Pivot field buttons.
+     * @param {boolean} visible Whether field buttons are visible.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setFieldButtonsVisible(visible: boolean): this;
+    /**
+     * Shows or hides category hierarchy expand and collapse buttons.
+     * @param {boolean} visible Whether expand and collapse buttons are visible.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setExpandCollapseButtonsVisible(visible: boolean): this;
+    /**
+     * Sets the worksheet cell anchor of this PivotChart.
+     * @param {ChartAnchorSpec} anchor A1 notation or a zero-based row and column anchor.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setPosition(anchor: ChartAnchorSpec): this;
+    /**
+     * Sets the absolute worksheet Drawing position.
+     * @param {number} x The horizontal position in pixels.
+     * @param {number} y The vertical position in pixels.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setAbsolutePosition(x: number, y: number): this;
+    /**
+     * Sets the worksheet Drawing size.
+     * @param {number} width The width in pixels.
+     * @param {number} height The height in pixels.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setSize(width: number, height: number): this;
+    /** Moves this PivotChart to the front. @returns {this} This PivotChart for chaining. */
+    bringToFront(): this;
+    /** Moves this PivotChart forward by one level. @returns {this} This PivotChart for chaining. */
+    bringForward(): this;
+    /** Moves this PivotChart backward by one level. @returns {this} This PivotChart for chaining. */
+    sendBackward(): this;
+    /** Moves this PivotChart to the back. @returns {this} This PivotChart for chaining. */
+    sendToBack(): this;
+    /**
+     * Moves this PivotChart to a zero-based Drawing order index.
+     * @param {number} index The target zero-based z-order index.
+     * @returns {this} This PivotChart for chaining.
+     */
+    setZOrder(index: number): this;
+    /**
+     * Removes this PivotChart and its worksheet Drawing.
+     * @returns {Promise<boolean>} Whether the removal was accepted.
+     */
+    remove(): Promise<boolean>;
+    private _arrange;
+    private _apply;
+    private _commit;
+}

package/lib/types/facade/f-pivot-table.d.ts

@@ -0,0 +1,41 @@
+import type { PivotChartTypeString } from '@univerjs-pro/pivot-chart';
+import type { FLinkedSheetPivotChartBuilderOf } from './f-pivot-chart-builder';
+import { FPivotTable } from '@univerjs-pro/sheets-pivot/facade';
+/** @ignore */
+export interface IFPivotTablePivotChartMixin {
+    /**
+     * Creates a detached PivotChart Builder permanently linked to this PivotTable.
+     *
+     * Any Pivot report edit made through the table or one of its linked charts updates the one
+     * shared PivotModel. Chart visuals and Drawing placement remain independent per chart.
+     *
+     * @param {T} type The supported Chart type.
+     * @returns {FLinkedSheetPivotChartBuilderOf<T>} A prelinked, source-locked Builder.
+     * @example
+     * ```ts
+     * import '@univerjs-pro/sheets-pivot-chart/facade';
+     *
+     * const fWorkbook = univerAPI.getActiveWorkbook();
+     * const fWorksheet = fWorkbook.getSheetByName('Dashboard');
+     * const fPivotTable = fWorkbook.getPivotTableById('pivot-table-1');
+     * if (!fWorksheet || !fPivotTable) throw new Error('Pivot source is unavailable.');
+     *
+     * const first = await fWorksheet.insertPivotChart(
+     *   fPivotTable.newChart(univerAPI.Enum.ChartTypeString.Column).setPosition('A1').build()
+     * );
+     * const second = await fWorksheet.insertPivotChart(
+     *   fPivotTable.newChart(univerAPI.Enum.ChartTypeString.Line).setPosition('J1').build()
+     * );
+     * console.log(first.getPivotTableReference(), second.getPivotTableReference());
+     * ```
+     */
+    newChart<T extends PivotChartTypeString>(type: T): FLinkedSheetPivotChartBuilderOf<T>;
+}
+/** @ignore */
+export declare class FPivotTablePivotChartMixin extends FPivotTable implements IFPivotTablePivotChartMixin {
+    newChart<T extends PivotChartTypeString>(type: T): FLinkedSheetPivotChartBuilderOf<T>;
+}
+declare module '@univerjs-pro/sheets-pivot/facade' {
+    interface FPivotTable extends IFPivotTablePivotChartMixin {
+    }
+}

package/lib/types/facade/f-univer.d.ts

@@ -0,0 +1,11 @@
+import type { Injector } from '@univerjs/core';
+import { FUniver } from '@univerjs/core/facade';
+/** @ignore */
+export declare class FUniverSheetsPivotChartMixin extends FUniver {
+    _initialize(injector: Injector): void;
+    private _registerModelEvent;
+    private _registerChangedEvent;
+    private _fireDrawingChanged;
+    private _registerCommandEvent;
+    private _fireCommandEvent;
+}