@univerjs-pro/engine-chart 1.0.0-alpha.8 → 1.0.0-beta.1

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

@@ -1,4 +1,4 @@
-import type { IChartRelationForceSpec, LinePointShape, RelationChartLayoutEnum } from '@univerjs-pro/engine-chart';
+import type { IChartInfo, IChartRelationForceSpec, LinePointShape, RelationChartLayoutEnum } from '@univerjs-pro/engine-chart';
 import { FChartBuilderBase } from '../f-chart-builder-base';
 /**
  * Configures a relation chart.
@@ -16,13 +16,14 @@ import { FChartBuilderBase } from '../f-chart-builder-base';
  *    values; without one, every link has weight `1`.
  *
  * A two-column edge list is treated as unweighted. A three-column edge list uses column `2` as its
- * weight automatically. If the range has more than three columns, select exactly one weight column
- * with {@link FChartBuilderBase.setValueFields}; selecting multiple weight columns or either endpoint
- * column makes the source invalid. A weighted edge list creates at most one category, named after
- * the selected weight column when that column has a non-empty header. An unweighted edge list
- * creates no categories.
+ * weight automatically. Use this canonical two- or three-column shape so the Source, Target, and
+ * optional Weight roles are inferred together. Do not call {@link FChartBuilderBase.setCategoryField}
+ * or {@link FChartBuilderBase.setValueFields} for this shape: those generic mapping methods cannot
+ * describe both endpoint roles and replace the automatic Relation mapping. A weighted edge list
+ * creates at most one category, named after the weight column when that column has a non-empty
+ * header. An unweighted edge list creates no categories.
  *
- * @example
+ * @example Sheet
  * A worksheet range `A1:C4` can contain this weighted edge list:
  *
  * | Source | Target | Weight |
@@ -32,13 +33,70 @@ import { FChartBuilderBase } from '../f-chart-builder-base';
  * | C | B | 2 |
  *
  * ```ts
- * worksheet.charts.create()
- *     .setSource('A1:C4')
- *     .setType(univerAPI.Enum.ChartTypeString.Relation)
- *     .setValueFields([2]);
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Relation)
+ *   .setSource({
+ *     range: 'A1:C4',
+ *     orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
+ *   })
+ *   .setLayout(univerAPI.Enum.ChartRelationChartLayoutEnum.Force)
+ *   .setUseValueAsSymbolSize(true)
+ *   .setEmphasisEnabled(true)
+ *   .setForce({ gravity: 0.2, repulsion: 50 })
+ *   .setNodeShape(univerAPI.Enum.ChartLinePointShape.Circle)
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Relation)
+ *   .setSource([['Source', 'Target', 'Weight'], ['A', 'B', 5], ['A', 'C', 3], ['C', 'B', 2]])
+ *   .setLayout(univerAPI.Enum.ChartRelationChartLayoutEnum.Force)
+ *   .setUseValueAsSymbolSize(true)
+ *   .setEmphasisEnabled(true)
+ *   .setForce({ gravity: 0.2, repulsion: 50 })
+ *   .setNodeShape(univerAPI.Enum.ChartLinePointShape.Circle)
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Relation)
+ *   .setSource([['Source', 'Target', 'Weight'], ['A', 'B', 5], ['A', 'C', 3], ['C', 'B', 2]])
+ *   .setLayout(univerAPI.Enum.ChartRelationChartLayoutEnum.Force)
+ *   .setUseValueAsSymbolSize(true)
+ *   .setEmphasisEnabled(true)
+ *   .setForce({ gravity: 0.2, repulsion: 50 })
+ *   .setNodeShape(univerAPI.Enum.ChartLinePointShape.Circle)
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Relation)
+ *   .setSource([['Source', 'Target', 'Weight'], ['A', 'B', 5], ['A', 'C', 3], ['C', 'B', 2]])
+ *   .setLayout(univerAPI.Enum.ChartRelationChartLayoutEnum.Force)
+ *   .setUseValueAsSymbolSize(true)
+ *   .setEmphasisEnabled(true)
+ *   .setForce({ gravity: 0.2, repulsion: 50 })
+ *   .setNodeShape(univerAPI.Enum.ChartLinePointShape.Circle)
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
  * ```
  */
-export declare class FRelationChartBuilder extends FChartBuilderBase {
+export declare class FRelationChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FChartBuilderBase<TSource, TDataSource, TInfo> {
     /**
      * Sets the layout configuration and returns this builder for chaining.
      *
@@ -48,9 +106,7 @@ export declare class FRelationChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Relation);
-     * builder.setLayout(univerAPI.Enum.RelationChartLayoutEnum.Force);
+     * builder.setLayout(univerAPI.Enum.ChartRelationChartLayoutEnum.Force);
      * ```
      */
     setLayout(value: RelationChartLayoutEnum): this;
@@ -62,8 +118,6 @@ export declare class FRelationChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Relation);
      * builder.resetLayout();
      * ```
      */
@@ -77,8 +131,6 @@ export declare class FRelationChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Relation);
      * builder.setUseValueAsSymbolSize(true);
      * ```
      */
@@ -91,8 +143,6 @@ export declare class FRelationChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Relation);
      * builder.resetUseValueAsSymbolSize();
      * ```
      */
@@ -106,8 +156,6 @@ export declare class FRelationChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Relation);
      * builder.setEmphasisEnabled(true);
      * ```
      */
@@ -120,8 +168,6 @@ export declare class FRelationChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Relation);
      * builder.resetEmphasisEnabled();
      * ```
      */
@@ -138,8 +184,6 @@ export declare class FRelationChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Relation);
      * builder.setForce({ gravity: 0.2, repulsion: 50 });
      * ```
      */
@@ -155,8 +199,6 @@ export declare class FRelationChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Relation);
      * builder.clearForce();
      * ```
      */
@@ -170,8 +212,6 @@ export declare class FRelationChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Relation);
      * builder.setCircularLabelRotation(true);
      * ```
      */
@@ -184,8 +224,6 @@ export declare class FRelationChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Relation);
      * builder.resetCircularLabelRotation();
      * ```
      */
@@ -199,9 +237,7 @@ export declare class FRelationChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Relation);
-     * builder.setNodeShape(univerAPI.Enum.LinePointShape.Circle);
+     * builder.setNodeShape(univerAPI.Enum.ChartLinePointShape.Circle);
      * ```
      */
     setNodeShape(value: LinePointShape): this;
@@ -213,8 +249,6 @@ export declare class FRelationChartBuilder extends FChartBuilderBase {
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Relation);
      * builder.resetNodeShape();
      * ```
      */

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

@@ -1,6 +1,62 @@
-import type { IChartScatterMappingSpec, IChartSolidSeriesPatch, IChartSolidSeriesStyleSpec } from '@univerjs-pro/engine-chart';
+import type { IChartInfo, IChartScatterMappingSpec, IChartSolidSeriesPatch, IChartSolidSeriesStyleSpec } from '@univerjs-pro/engine-chart';
 import { FCartesianChartBuilder } from '../f-cartesian-chart-builder';
-export declare class FScatterChartBuilder extends FCartesianChartBuilder<Omit<IChartSolidSeriesPatch, 'selector'>, IChartSolidSeriesStyleSpec> {
+/**
+ * Fluent, type-specific Builder for Scatter Charts.
+ *
+ * The data source is an observation table: each row represents one point. Map two
+ * numeric fields to X and Y; an optional label field supplies point labels. All mapped
+ * fields are aligned by row, so their source vectors must have the same length.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Scatter)
+ *   .setSource({
+ *     range: 'A1:C8',
+ *     orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
+ *   })
+ *   .setScatterMapping({ xIndex: 0, yIndex: 1, labelIndex: 2 })
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Scatter)
+ *   .setSource([['X', 'Y'], [10, 20], [18, 32], [24, 28]])
+ *   .setScatterMapping({ xIndex: 0, yIndex: 1 })
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Scatter)
+ *   .setSource([['X', 'Y'], [10, 20], [18, 32], [24, 28]])
+ *   .setScatterMapping({ xIndex: 0, yIndex: 1 })
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Scatter)
+ *   .setSource([['X', 'Y'], [10, 20], [18, 32], [24, 28]])
+ *   .setScatterMapping({ xIndex: 0, yIndex: 1 })
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FScatterChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FCartesianChartBuilder<Omit<IChartSolidSeriesPatch, 'selector'>, IChartSolidSeriesStyleSpec, TSource, TDataSource, TInfo> {
     /**
      * Sets the scatter mapping configuration and returns this builder for chaining.
      *
@@ -10,8 +66,6 @@ export declare class FScatterChartBuilder extends FCartesianChartBuilder<Omit<IC
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Scatter);
      * builder.setScatterMapping({ xIndex: 0, yIndex: 1 });
      * ```
      */
@@ -24,8 +78,6 @@ export declare class FScatterChartBuilder extends FCartesianChartBuilder<Omit<IC
      * @returns This builder for chaining.
      * @example
      * ```ts
-     * const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
-     * const builder = worksheet.charts.create().setType(univerAPI.Enum.ChartTypeString.Scatter);
      * builder.clearScatterMapping();
      * ```
      */

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

@@ -0,0 +1,138 @@
+import type { DeepNullish, IChartInfo, IChartSunburstCenterLabelSpec, IChartSunburstLabelSpec } from '@univerjs-pro/engine-chart';
+import { FChartBuilderBase } from '../f-chart-builder-base';
+/**
+ * Fluent semantic builder for an automatically laid-out Sunburst chart.
+ *
+ * Field indexes are zero-based in the orientation-normalized dataset. Rendering needs at
+ * least one ordered hierarchy field and exactly one value field. Duplicate complete paths
+ * sum finite numeric values; sparse hierarchy values inherit within ancestor scope; parent
+ * facts add to child totals. Ring layout is automatic and root navigation is disabled.
+ *
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Sunburst)
+ *   .setSource('A1:D8')
+ *   .setHierarchyFields([0, 1, 2])
+ *   .setValueField(3)
+ *   .setSunburstLabel({ visible: true, position: univerAPI.Enum.ChartSunburstLabelPosition.Outside, color: '#334155' })
+ *   .setCenterLabel({ visible: true, color: '#0f172a' })
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Sunburst)
+ *   .setSource([['Region', 'Country', 'City', 'Sales'], ['Europe', 'France', 'Paris', 120], ['Asia', 'Japan', 'Tokyo', 180]])
+ *   .setHierarchyFields([0, 1, 2])
+ *   .setValueField(3)
+ *   .setSunburstLabel({ visible: true, position: univerAPI.Enum.ChartSunburstLabelPosition.Outside, color: '#334155' })
+ *   .setCenterLabel({ visible: true, color: '#0f172a' })
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Sunburst)
+ *   .setSource([['Region', 'Country', 'City', 'Sales'], ['Europe', 'France', 'Paris', 120], ['Asia', 'Japan', 'Tokyo', 180]])
+ *   .setHierarchyFields([0, 1, 2])
+ *   .setValueField(3)
+ *   .setSunburstLabel({ visible: true, position: univerAPI.Enum.ChartSunburstLabelPosition.Outside, color: '#334155' })
+ *   .setCenterLabel({ visible: true, color: '#0f172a' })
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Sunburst)
+ *   .setSource([['Region', 'Country', 'City', 'Sales'], ['Europe', 'France', 'Paris', 120], ['Asia', 'Japan', 'Tokyo', 180]])
+ *   .setHierarchyFields([0, 1, 2])
+ *   .setValueField(3)
+ *   .setSunburstLabel({ visible: true, position: univerAPI.Enum.ChartSunburstLabelPosition.Outside, color: '#334155' })
+ *   .setCenterLabel({ visible: true, color: '#0f172a' })
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
+ */
+export declare class FSunburstChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FChartBuilderBase<TSource, TDataSource, TInfo> {
+    /**
+     * Replaces the ordered inner-to-outer hierarchy with zero-based field indexes.
+     *
+     * @param indexes Ordered hierarchy field indexes.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setHierarchyFields([0, 1, 2]);
+     * ```
+     */
+    setHierarchyFields(indexes: readonly number[]): this;
+    /**
+     * Replaces the sole numeric value field with a zero-based field index.
+     *
+     * @param index Numeric value field index.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setValueField(3);
+     * ```
+     */
+    setValueField(index: number): this;
+    /**
+     * Sets label visibility, content, position, and font appearance.
+     *
+     * @param label Sunburst label settings.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setSunburstLabel({
+     *   visible: true,
+     *   position: univerAPI.Enum.ChartSunburstLabelPosition.Outside,
+     *   color: '#334155',
+     * });
+     * ```
+     */
+    setSunburstLabel(label: DeepNullish<IChartSunburstLabelSpec>): this;
+    /**
+     * Removes explicit label style and restores visible category-name labels.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.resetSunburstLabel();
+     * ```
+     */
+    resetSunburstLabel(): this;
+    /**
+     * Sets visibility, number format, and font appearance for the aggregate center value.
+     *
+     * @param centerLabel Center-label settings.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setCenterLabel({ visible: true, color: '#0f172a' });
+     * ```
+     */
+    setCenterLabel(centerLabel: DeepNullish<IChartSunburstCenterLabelSpec>): this;
+    /**
+     * Removes the authored center-label style and restores its hidden default.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.resetCenterLabel();
+     * ```
+     */
+    resetCenterLabel(): this;
+}

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

@@ -1,4 +1,4 @@
-import type { IChartTreemapLabelSpec, TreemapParentLabelLayout } from '@univerjs-pro/engine-chart';
+import type { DeepNullish, IChartInfo, IChartTreemapLabelSpec, TreemapParentLabelLayout } from '@univerjs-pro/engine-chart';
 import { FChartBuilderBase } from '../f-chart-builder-base';
 /**
  * Fluent semantic builder for an automatically laid-out Treemap.
@@ -10,25 +10,127 @@ import { FChartBuilderBase } from '../f-chart-builder-base';
  * is disabled. The runtime defaults are banner parent labels and visible category-name
  * leaf labels; labels may hide when their rectangle cannot fit the complete content.
  *
- * @example
- * const chart = worksheet.charts.create()
- *   .setType(univerAPI.Enum.ChartTypeString.Treemap)
+ * @example Sheet
+ * ```ts
+ * const fWorkbook = univerAPI.getActiveWorkbook();
+ * const fWorksheet = fWorkbook.getSheetByName('Sheet1');
+ * const chartInfo = fWorksheet
+ *   .newChart(univerAPI.Enum.ChartTypeString.Treemap)
+ *   .setSource('A1:D8')
  *   .setHierarchyFields([0, 1, 2])
  *   .setValueField(3)
- *   .setParentLabelLayout('banner')
- *   .setTreemapLabel({ visible: true, contentType: univerAPI.Enum.LabelContentType.CategoryName });
+ *   .setParentLabelLayout(univerAPI.Enum.ChartTreemapParentLabelLayout.Banner)
+ *   .setTreemapLabel({ visible: true, color: '#334155' })
+ *   .build();
+ * await fWorksheet.insertChart(chartInfo);
+ * ```
+ *
+ * @example Doc
+ * ```ts
+ * const fDocument = univerAPI.getActiveDocument();
+ * const chartInfo = fDocument
+ *   .newChart(univerAPI.Enum.ChartTypeString.Treemap)
+ *   .setSource([['Region', 'Country', 'City', 'Sales'], ['Europe', 'France', 'Paris', 120], ['Asia', 'Japan', 'Tokyo', 180]])
+ *   .setHierarchyFields([0, 1, 2])
+ *   .setValueField(3)
+ *   .setParentLabelLayout(univerAPI.Enum.ChartTreemapParentLabelLayout.Banner)
+ *   .setTreemapLabel({ visible: true, color: '#334155' })
+ *   .build();
+ * await fDocument.insertChart(chartInfo);
+ * ```
+ *
+ * @example Slide
+ * ```ts
+ * const fPresentation = univerAPI.getActivePresentation();
+ * const fSlide = fPresentation.getSlideByIndex(0);
+ * const chartInfo = fSlide
+ *   .newChart(univerAPI.Enum.ChartTypeString.Treemap)
+ *   .setSource([['Region', 'Country', 'City', 'Sales'], ['Europe', 'France', 'Paris', 120], ['Asia', 'Japan', 'Tokyo', 180]])
+ *   .setHierarchyFields([0, 1, 2])
+ *   .setValueField(3)
+ *   .setParentLabelLayout(univerAPI.Enum.ChartTreemapParentLabelLayout.Banner)
+ *   .setTreemapLabel({ visible: true, color: '#334155' })
+ *   .build();
+ * await fSlide.insertChart(chartInfo);
+ * ```
+ *
+ * @example Board
+ * ```ts
+ * const fBoard = univerAPI.getActiveBoard();
+ * const chartInfo = fBoard
+ *   .newChart(univerAPI.Enum.ChartTypeString.Treemap)
+ *   .setSource([['Region', 'Country', 'City', 'Sales'], ['Europe', 'France', 'Paris', 120], ['Asia', 'Japan', 'Tokyo', 180]])
+ *   .setHierarchyFields([0, 1, 2])
+ *   .setValueField(3)
+ *   .setParentLabelLayout(univerAPI.Enum.ChartTreemapParentLabelLayout.Banner)
+ *   .setTreemapLabel({ visible: true, color: '#334155' })
+ *   .build();
+ * await fBoard.insertChart(chartInfo);
+ * ```
  */
-export declare class FTreemapChartBuilder extends FChartBuilderBase {
-    /** Replaces the ordered root-to-leaf hierarchy with zero-based field indexes. */
+export declare class FTreemapChartBuilder<TSource = never[], TDataSource = TSource, TInfo extends IChartInfo<TDataSource> = IChartInfo<TDataSource>> extends FChartBuilderBase<TSource, TDataSource, TInfo> {
+    /**
+     * Replaces the ordered root-to-leaf hierarchy with zero-based field indexes.
+     *
+     * @param indexes Ordered hierarchy field indexes.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setHierarchyFields([0, 1, 2]);
+     * ```
+     */
     setHierarchyFields(indexes: readonly number[]): this;
-    /** Replaces the sole numeric value field with a zero-based field index. */
+    /**
+     * Replaces the sole numeric value field with a zero-based field index.
+     *
+     * @param index Numeric value field index.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setValueField(3);
+     * ```
+     */
     setValueField(index: number): this;
-    /** Sets parent names to a reserved banner, overlapping text, or hidden. */
+    /**
+     * Sets parent names to a reserved banner, overlapping text, or hidden.
+     *
+     * @param layout Parent-label layout mode.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setParentLabelLayout(univerAPI.Enum.ChartTreemapParentLabelLayout.Banner);
+     * ```
+     */
     setParentLabelLayout(layout: TreemapParentLabelLayout): this;
-    /** Removes the explicit parent layout and restores the runtime banner default. */
+    /**
+     * Removes the explicit parent layout and restores the runtime banner default.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.resetParentLabelLayout();
+     * ```
+     */
     resetParentLabelLayout(): this;
-    /** Sets leaf font and CategoryName/Value content. Other content bits are inert. */
-    setTreemapLabel(label: IChartTreemapLabelSpec): this;
-    /** Removes explicit leaf-label style and restores visible category-name labels. */
+    /**
+     * Sets leaf visibility, content, and font appearance.
+     *
+     * @param label Treemap leaf-label settings.
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.setTreemapLabel({ visible: true, color: '#334155' });
+     * ```
+     */
+    setTreemapLabel(label: DeepNullish<IChartTreemapLabelSpec>): this;
+    /**
+     * Removes explicit leaf-label style and restores visible category-name labels.
+     *
+     * @returns This builder for chaining.
+     * @example
+     * ```ts
+     * builder.resetTreemapLabel();
+     * ```
+     */
     resetTreemapLabel(): this;
 }