@sheetxl/sdk 0.8.0-beta.10 → 0.8.0-beta.11

package/types/src/chart/IChartCollection.d.ts

@@ -1,12 +1,12 @@
 import { ICollection } from '../type';
+import { ICellRange, ICellRanges } from '../cellRange';
 import { IChart } from './IChart';
 /**
  * Holds the {@link IChart | charts} on a sheet.
  *
  * @remarks
  * A view over the sheet's movables: a chart is the content of a movable, and the movable is what
- * places it — see {@link IChart.getMovable}. Read-only for now; a chart is added by adding a
- * movable with chart content.
+ * places it — see {@link IChart.getMovable}.
  */
 export interface IChartCollection extends ICollection<IChart> {
     /**
@@ -19,6 +19,31 @@ export interface IChartCollection extends ICollection<IChart> {
      * @param name The name of the chart. This is case insensitive.
      */
     getByName(name: string): IChart | null;
+    /**
+     * Adds a chart of `source`, its series made from the cells by Excel's rules, as Insert Chart
+     * makes them: which cells are labels, which way the series run, and which labels name them.
+     *
+     * @param source The cells to chart: a range, or an address. A bare address is on this sheet;
+     * several areas are separated by commas. One cell charts the block of cells around it, up to blank
+     * rows and columns.
+     * @param options The type, the direction of the series, and where the chart goes.
+     *
+     * @returns The chart, once its kind has loaded. The insert is one undoable step.
+     *
+     * @remarks
+     * The chart is drawn as Excel draws a new chart of its type: its colors, fonts, axes, a legend for
+     * two series or more, and a title of its own. Office Scripts' `worksheet.addChart(type, source,
+     * seriesBy)`, VBA's `Shapes.AddChart2`.
+     *
+     * @example
+     * ```ts
+     * const chart = await sheet.getCharts().add('A1:D5', { type: 'line' });
+     * ```
+     *
+     * @throws ExpectedError when `source` holds no cells, the type cannot be made new yet, or a stock
+     * type's cells hold another number of series than it is made of.
+     */
+    add(source: ICellRange | ICellRanges | string, options?: IChart.AddOptions): Promise<IChart>;
     /** For runtime type checking. */
     readonly isIChartCollection: true;
 }