import type { DocPropertiesOptions } from 'docx'; import { DrawingPatch } from 'docx'; import type { IFloating } from 'docx'; import type { IRunPropertiesOptions } from 'docx'; import { Run } from 'docx'; import { TemplateDrawing } from 'docx'; import { TemplatePackage } from 'docx'; import type { ThemeColor } from 'docx'; /** * An area chart (`c:areaChart`). Series can be drawn as columns or lines instead. * * @publicApi */ export declare type AreaChartOptions = CategoryChartOptions & { readonly type: "area"; }; /** * Options of the charts with bars: column (vertical bars) and bar (horizontal bars) charts. * * @publicApi */ export declare type BarChartBaseOptions = CategoryChartOptions & { /** * The space between groups of bars, as a percentage of a bar's width, from 0 to 500. Default is Office's: 219 for * column charts, 182 for bar charts, and 150 when the series are stacked */ readonly gapWidth?: number; /** * How much the bars in a group overlap, as a percentage of a bar's width, from -100 (a bar's width apart) to 100. * Default is Office's: -27 for column charts and 0 for bar charts. Stacked bars always overlap fully */ readonly overlap?: number; }; /** * A bar chart: horizontal bars (`c:barChart` with `c:barDir="bar"`). The first category is at the bottom, as in Word. * * @publicApi */ export declare type BarChartOptions = BarChartBaseOptions & { readonly type: "bar"; }; /** * A bar of pie chart (`c:ofPieChart` with `c:ofPieType="bar"`): the small slices of a pie drawn again as a stacked bar * beside it. * * @publicApi */ export declare type BarOfPieChartOptions = SplitPieChartBaseOptions & { readonly type: "barOfPie"; }; /** * What the labels on each bubble of a bubble chart show: as {@link ChartDataLabels}, or the bubble's size. * * @publicApi */ export declare type BubbleChartDataLabels = ChartDataLabels & { /** The bubble's size. Default is `false` */ readonly bubbleSize?: boolean; }; /** * A bubble chart (`c:bubbleChart`): bubbles, each with its own x, y and size, on two value axes. * * @publicApi */ export declare type BubbleChartOptions = ChartBaseOptions & { readonly type: "bubble"; /** The series, each with its bubbles */ readonly series: readonly BubbleChartSeries[]; /** The size of the bubbles, as a percentage of Office's size, from 0 to 300. Default is 100 */ readonly bubbleScale?: number; /** Whether a bubble's size is its area or its width. Default is `"area"` */ readonly sizeRepresents?: "area" | "width"; /** The horizontal axis */ readonly xAxis?: ChartValueAxis; /** The vertical axis */ readonly yAxis?: ChartValueAxis; /** Labels on each bubble */ readonly dataLabels?: BubbleChartDataLabels; }; /** * A bubble of a bubble chart: a point with a size. * * @publicApi */ export declare type BubbleChartPoint = ChartPoint & { /** The bubble's size, compared with the other bubbles'. Can't be negative */ readonly size: number; }; /** * The label of one bubble of a bubble chart: as {@link ChartPointLabel}, or the bubble's size. * * @publicApi */ export declare type BubbleChartPointLabel = BubbleChartDataLabels & ChartLabelText; /** * A series of a bubble chart: bubbles, each with its own x, y and size. * * @publicApi */ export declare type BubbleChartSeries = { /** The series' name, shown in the legend */ readonly name: string; /** The series' bubbles */ readonly points: readonly BubbleChartPoint[]; /** The colour of the series' bubbles. Default is the next of the theme's accent colours */ readonly color?: string | ThemeColor; /** The series' own labels, instead of the chart's `dataLabels`, or `false` for none */ readonly dataLabels?: false | BubbleChartDataLabels; /** Labels of single bubbles, in order: a label of its own, `false` for none, or `undefined` for the series' own */ readonly pointLabels?: readonly (false | BubbleChartPointLabel | undefined)[]; /** Lines fitted to the bubbles' centres */ readonly trendlines?: readonly ChartTrendline[]; /** Error bars along the x axis, left and right of each bubble's centre */ readonly xErrorBars?: ChartErrorBars; /** Error bars along the y axis, up and down from each bubble's centre */ readonly yErrorBars?: ChartErrorBars; }; /** * New data for a chart with categories: a column, bar, line, area, pie, doughnut or radar chart. * * @publicApi */ export declare type CategoryChartDataPatchOptions = { /** * The categories, in order. If they are all numbers, they are written as numbers. If they are all dates, a column, * bar, line or area chart spaces them by date */ readonly categories: readonly (string | number | Date)[] | readonly ChartCategoryGroup[]; /** The series, one value for each category. A pie chart has one */ readonly series: readonly CategoryChartDataSeries[]; /** * The chart's alt text description. Default is a description of the chart from its new data, such as "Column chart, * Sales. 2025: Jan 10, Feb 20.", and none for a decorative chart. An empty description removes it */ readonly description?: string; }; /** * A series of new data for a chart with categories: a column, bar, line, area, pie, doughnut or radar chart. * * @publicApi */ export declare type CategoryChartDataSeries = { /** The series' name, shown in the legend */ readonly name: string; /** One value for each category, in order. `null` leaves a gap. A series can have fewer values than there are categories */ readonly values: readonly (number | null)[]; }; /** * Options of the charts with categories and values: column, bar, line and area charts. * * @publicApi */ export declare type CategoryChartOptions = ChartBaseOptions & { /** * The categories along the chart's category axis, in order. If they are all numbers, they are written as numbers. * If they are all dates, the axis is a date axis, which spaces them by date. Groups of categories, such as quarters * in years, are labelled in rows, the groups below their categories */ readonly categories: readonly (string | number | Date)[] | readonly ChartCategoryGroup[]; /** The series, one value for each category */ readonly series: readonly ChartSeries[]; /** Whether the series of the chart's `type` are stacked. Default is `"none"` */ readonly stacking?: ChartStacking; /** The axis of categories */ readonly categoryAxis?: ChartAxis; /** The axis of values */ readonly valueAxis?: ChartValueAxis; /** The secondary axis of values, on the right, for series with `axis: "secondary"`. It has no gridlines by default */ readonly secondaryValueAxis?: ChartValueAxis; /** Labels on each bar or point */ readonly dataLabels?: ChartDataLabels; /** How empty values (`null`) are drawn: as gaps, as zero, or with a line joining the points either side. Default is `"gap"` */ readonly emptyValues?: ChartEmptyValues; /** A table of the data under the plot, or `true` for one with Office's borders and legend keys. Default is none */ readonly dataTable?: boolean | ChartDataTable; }; /** * The fill and border of the chart area, or of the plot area. * * @publicApi */ export declare type ChartAreaStyle = { /** A 6-digit hex colour, a colour of the document's theme, or `"none"` */ readonly fill?: string | ThemeColor; /** The border, or `"none"` */ readonly border?: "none" | ChartLine; }; /** * An axis: its title, its labels, whether it is shown, and its gridlines. * * @publicApi */ export declare type ChartAxis = { /** The axis' title */ readonly title?: string | ChartTitle; /** Whether the axis and its labels are shown. Default is `true` */ readonly visible?: boolean; /** Whether lines are drawn across the plot at each label. Default is `true` for value axes and `false` for category axes */ readonly gridlines?: boolean; /** Puts the categories or values in reverse order, as Word's "Categories in reverse order" does. Default is `false` */ readonly reverseOrder?: boolean; /** * Where this axis crosses the other axis. Default is `"auto"`, or for the secondary value axis, the side opposite the * primary: `"maximum"`, or `"minimum"` when the categories are in reverse order. `valueAxis: { crossesAt: "maximum" }` * puts the value axis on the right */ readonly crossesAt?: ChartAxisCrossing; /** Rotates the labels, in degrees clockwise, from -90 to 90: -45 slants them up to the right. Default is Office's choice */ readonly labelRotation?: number; /** * How the labels are written, as an Excel number format such as `"#,##0"`, `"0.0%"`, `"$#,##0"` or, for dates, * `"mmm yyyy"`. Default is the values' own */ readonly numberFormat?: string; /** The labels' font. Default is 9 points */ readonly font?: ChartFont; }; /** * Where an axis crosses the other axis: where Office puts it (`"auto"`, at zero, or at the minimum when zero is out of * range), at the other axis' minimum or maximum, or at a value on the other axis. On a value axis crossing categories, * the value is the category's number, from 1, or when the categories are dates, a date. * * @publicApi */ export declare type ChartAxisCrossing = "auto" | "minimum" | "maximum" | number | Date; /** * Which value axis a series is drawn against: the primary one, on the left, or the secondary one, on the right. A bar * chart's are along the bottom and the top. * * @publicApi */ export declare type ChartAxisGroup = "primary" | "secondary"; /** * Options every chart has, whatever its type. * * @publicApi */ export declare type ChartBaseOptions = { /** The chart's title, above the plot. Default is no title. Each line of the text is a line of the title */ readonly title?: string | ChartTitle; /** The legend, or `false` for none. Default is a legend below the plot */ readonly legend?: false | ChartLegend; /** The font of all the chart's text, apart from its size. The title's, legend's and others' own fonts are applied over it */ readonly font?: Omit; /** The chart area's fill and border. Default is a white fill with a light grey border */ readonly chartArea?: ChartAreaStyle; /** The plot area's fill and border. Default is neither */ readonly plotArea?: ChartAreaStyle; /** The chart's size in pixels. Default is 576 by 336 pixels (6 by 3.5 inches), the size Word inserts a chart at */ readonly transformation?: ChartSize; /** Floats the chart on the page instead of placing it inline with text, as for images */ readonly floating?: IFloating; /** * A name, description and title for screen readers. Without a description, the chart is described from its data, * such as "Column chart, Sales. 2024: Jan 10, Feb 20, Mar 30." */ readonly altText?: DocPropertiesOptions; /** Marks the chart as decorative, so screen readers skip it. Default is `false` */ readonly decorative?: boolean; /** Formatting of the run the chart is in, such as `position` to raise or lower it from the text's baseline */ readonly run?: IRunPropertiesOptions; }; /** * A group of categories, such as the quarters of a year, labelled below them on the category axis. A group holds * categories, or groups of its own, such as the months of each quarter of each year. * * @publicApi */ export declare type ChartCategoryGroup = { /** The group's name, such as `"2025"`, below its categories */ readonly name: string; /** The categories in the group, in order, or the groups in it. Every group at the same depth holds the same kind */ readonly categories: readonly (string | number)[] | readonly ChartCategoryGroup[]; }; /** * Error bars of a size of each point's own, such as a range of uncertainty. The amounts are kept in the chart's * workbook, beside the data. * * @publicApi */ export declare type ChartCustomErrorBars = ChartErrorBarsStyle & { readonly type: "custom"; /** How far each bar goes towards higher values, one amount for each value or point, in order. `null` leaves none */ readonly plus?: readonly (number | null)[]; /** How far each bar goes towards lower values, one amount for each value or point, in order. `null` leaves none */ readonly minus?: readonly (number | null)[]; }; /** * Where the labels on a series' bars, points or slices are. Each type of chart has its own: * * - bars: `"center"`, `"insideEnd"`, `"insideBase"` and, unless stacked, `"outsideEnd"`; * - lines, scatter and bubble charts: `"center"`, `"left"`, `"right"`, `"above"` and `"below"`; * - pie charts: `"center"`, `"insideEnd"`, `"outsideEnd"` and `"bestFit"`. * * The labels of area, doughnut and radar charts have no position. * * @publicApi */ export declare type ChartDataLabelPosition = "center" | "insideEnd" | "insideBase" | "outsideEnd" | "left" | "right" | "above" | "below" | "bestFit"; /** * What the labels on each bar, point or slice show, and where they are. There are no labels unless one of `value`, * `category` or `seriesName` is `true`. * * @publicApi */ export declare type ChartDataLabels = { /** The value. Default is `false` */ readonly value?: boolean; /** The category, or on a scatter or bubble chart, the x value. Default is `false` */ readonly category?: boolean; /** The series' name. Default is `false` */ readonly seriesName?: boolean; /** * Where the labels are. Default is Office's: outside the end of a bar, in the middle of a stacked bar, to the right of * a point, and where they fit best on a pie. A chart's position is for the series drawn as its `type`: series drawn * another way keep Office's, unless their own labels give one */ readonly position?: ChartDataLabelPosition; /** How the values are written, as an Excel number format such as `"#,##0"` or `"0.0%"`. Default is the values' own */ readonly numberFormat?: string; /** The labels' font. Default is 9 points */ readonly font?: ChartFont; }; /** * Replaces the data of a chart in a template, found by a placeholder in its alt text, such as `{{sales}}`, keeping its * look: its type, title, colours, fonts, labels, axes and legend. Give it as a patch to `patchDocument`, with the * placeholder's key. * * - Each series' name and data are replaced, in the order the series are plotted, and its data is written in the * chart's own number formats, such as "0%". * - New series copy the look of the template's last series, in their own colour, the next of the theme's accents, as * `ChartRun` colours them. Series the new data doesn't have are removed, with any axes only they used. * - Points past the new data lose their own colours and labels. When each slice of a pie has its own colour, new * slices take the next of the theme's accents. * - The chart's workbook is replaced with one holding the new data, so Word's "Edit Data" opens it. * - The alt text's description is replaced with a description of the new data. * * The patch checks the data against the chart's type when the document is patched: a pie chart has one series, a * scatter or bubble chart's series have points, and a stock chart has prices, with opening prices and volumes if the * template's has them. Put the placeholder in the chart's alt text in Word, in "Alt Text" or "Edit Alt Text". A * placeholder in the document's text is left as it is. * * @publicApi * * @example * ```typescript * await patchDocument({ * outputType: "nodebuffer", * data: template, * patches: { * sales: new ChartDataPatch({ * categories: ["Jan", "Feb", "Mar"], * series: [{ name: "2025", values: [10, 20, 30] }], * }), * }, * }); * ``` */ export declare class ChartDataPatch extends DrawingPatch { private readonly data; private readonly patched; /** * @throws If there are no series, a series has no name, or has neither values nor points, some series have values * and others points, series with values have no categories, or a value, category or point is wrong, as for * `ChartRun` */ constructor(options: ChartDataPatchOptions); /** * Replaces the chart's data, and its workbook, and describes it in its alt text. * * @throws If the drawing isn't a chart, is a type of chart this can't patch, such as a surface chart, or has something * that refers to its workbook's cells other than its data, such as labels from cells, or the data isn't for the * chart's type, such as two series for a pie chart */ patch(drawing: TemplateDrawing, template: TemplatePackage): void; private patchChart; } /** * The new data of a chart in a template: categories and each series' values, for a scatter or bubble chart each * series' points, or for a stock chart its prices. * * @publicApi */ export declare type ChartDataPatchOptions = CategoryChartDataPatchOptions | PointChartDataPatchOptions | StockChartDataPatchOptions; /** * A table of the chart's data under its plot, as Word's "Data Table" draws it: a row for each series, and a column for * each category. * * @publicApi */ export declare type ChartDataTable = { /** Shows each series' key, as in the legend, beside its name. Default is `true` */ readonly legendKeys?: boolean; /** Lines between the rows. Default is `true` */ readonly horizontalBorders?: boolean; /** Lines between the columns. Default is `true` */ readonly verticalBorders?: boolean; /** A line around the table. Default is `true` */ readonly outline?: boolean; /** The table's font. Default is 9 points */ readonly font?: ChartFont; }; /** * Units a value axis' labels are written in, such as thousands: 25,000 is labelled 25, and the axis is labelled * "Thousands". * * @publicApi */ export declare type ChartDisplayUnits = "hundreds" | "thousands" | "tenThousands" | "hundredThousands" | "millions" | "tenMillions" | "hundredMillions" | "billions" | "trillions"; /** * How empty values (`null`) are drawn: as gaps, as zero, or, for a line, by joining the points either side. * * @publicApi */ export declare type ChartEmptyValues = "gap" | "zero" | "connect"; /** * Error bars: a line from each point of a series, showing how far its value might be off. * * @publicApi */ export declare type ChartErrorBars = ChartErrorBarsAmount | ChartCustomErrorBars; /** * Error bars of a size that follows a rule: a fixed amount, a percentage of each value, a number of standard * deviations, or the standard error. * * @publicApi */ export declare type ChartErrorBarsAmount = ChartErrorBarsStyle & { /** * Which way the bars go from each point: both ways, or only towards higher values (`"plus"`) or lower ones * (`"minus"`). Default is `"both"` */ readonly direction?: "both" | "plus" | "minus"; } & ({ /** The same amount at each point */ readonly type: "fixed"; /** The amount, 0 or more */ readonly value: number; } | { /** A percentage of each point's value */ readonly type: "percentage"; /** The percentage, 0 or more */ readonly value: number; } | { /** A number of standard deviations of the series' values, from their average */ readonly type: "standardDeviation"; /** How many standard deviations, 0 or more. Default is 1 */ readonly value?: number; } | { /** The standard error of the series' values */ readonly type: "standardError"; }); /** * What error bars share, whatever their size: which way they go, their end caps and their line. * * @publicApi */ export declare type ChartErrorBarsStyle = { /** Whether the bars end with a short line across them. Default is `true` */ readonly endCaps?: boolean; /** The bars' colour, width and dashes. Default is dark grey, 0.75 points wide */ readonly line?: ChartLine; }; /** * A font for a chart's text. Anything left out is as Word writes a new chart's text: the theme's body font, not bold, * in dark grey. * * @publicApi */ export declare type ChartFont = { /** The typeface, such as `"Arial"`. Default is the theme's body font */ readonly name?: string; /** Size in points, from 1 to 4000. Default is 14 for the chart's title, 10 for axis titles, and 9 for the rest */ readonly size?: number; /** Bold text. Default is `false` */ readonly bold?: boolean; /** Italic text. Default is `false` */ readonly italics?: boolean; /** A 6-digit hex colour such as `"1F4E79"`, or a colour of the document's theme such as `{ theme: "accent1" }` */ readonly color?: string | ThemeColor; }; /** * Text of a label's own, in place of what it would show. * * @publicApi */ export declare type ChartLabelText = { /** * The label's text, in place of the value, category or series' name, such as `"Record high"`. Each line of the text is * a line of the label. A label with text shows nothing else */ readonly text?: string; }; /** * The legend: a key to the series, or to the slices of a pie or doughnut chart. * * @publicApi */ export declare type ChartLegend = { /** Where the legend is. Default is `"bottom"`, as in Word 2013 and later */ readonly position?: ChartLegendPosition; /** The legend's font. Default is 9 points */ readonly font?: ChartFont; /** * Entries to leave out of the legend, by their text: a series' name, a trendline's name, or on a pie or doughnut * chart, a category. The series stays in the chart */ readonly hiddenEntries?: readonly (string | number)[]; }; /** * Where the legend is, around the plot: `"topRight"` is in the top right corner. * * @publicApi */ export declare type ChartLegendPosition = "top" | "bottom" | "left" | "right" | "topRight"; /** * A line: a series' line, or a border. * * @publicApi */ export declare type ChartLine = { /** A 6-digit hex colour, or a colour of the document's theme. Default is the series' colour, or a border's light grey */ readonly color?: string | ThemeColor; /** Width in points, from 0 to 1584. Default is 2.25 for a line or radar series, 1.5 for a scatter series and 0.75 for a border */ readonly width?: number; /** A dash pattern. Default is `"solid"` */ readonly dash?: ChartLineDash; }; /** * A preset dash pattern, as for shapes' lines. The "short" patterns are the ones Word calls "Round Dot", "Square Dot" * and so on. * * @publicApi */ export declare type ChartLineDash = "solid" | "dot" | "dash" | "longDash" | "dashDot" | "longDashDot" | "longDashDotDot" | "shortDash" | "shortDot" | "shortDashDot" | "shortDashDotDot"; /** * A marker drawn at each point of a line, radar or scatter series, in the series' colour. * * @publicApi */ export declare type ChartMarker = { /** The marker's shape. Default is `"circle"` */ readonly shape?: ChartMarkerShape; /** The marker's size in points, from 2 to 72. Default is 5 */ readonly size?: number; }; /** * The shape of a marker. * * @publicApi */ export declare type ChartMarkerShape = "circle" | "square" | "diamond" | "triangle" | "x" | "star" | "plus" | "dash" | "dot"; /** * A point of a scatter chart. * * @publicApi */ export declare type ChartPoint = { /** Its position along the horizontal axis */ readonly x: number; /** Its position along the vertical axis */ readonly y: number; }; /** * The label of one bar or point, over its series' labels: its own text, or what it shows, where it is, its number * format and its font. Anything left out is as the series' labels have it. * * @publicApi */ export declare type ChartPointLabel = ChartDataLabels & ChartLabelText; /** * Represents a chart in a WordprocessingML document: a column, bar, line, area, pie, doughnut, pie of pie, bar of pie, * radar, scatter, bubble or stock chart, drawn by Word from its data in the document's theme, as a chart made with * Word's Insert Chart is. A column, line or area chart's series can each be drawn another way, as Word's "Combo" charts * are. * * The chart is a part of its own (`word/charts/chart1.xml`), with its data in an embedded workbook, so Word's "Edit * Data" opens it in Excel. It sits inline with text unless `floating` is set, and goes in a paragraph, including in a * table, header, footer or footnote. Without a description in its `altText`, the chart is described for screen readers * from its data. * * Reference: http://officeopenxml.com/drwOverview.php * * @publicApi * * @example * ```typescript * new Paragraph({ * children: [ * new ChartRun({ * type: "column", * title: "Sales", * categories: ["Jan", "Feb", "Mar"], * series: [ * { name: "2024", values: [10, 20, 30] }, * { name: "2025", values: [15, 25, null] }, * ], * }), * ], * }); * ``` */ export declare class ChartRun extends Run { /** * @throws If there are no series or categories, a value isn't a finite number or null, a series has more values * than there are categories or an option the way it is drawn doesn't have, a pie chart has more than one series or * a pie or doughnut chart a negative value, a scatter or bubble point isn't finite numbers, a data label position * isn't one the chart's type has, a trendline can't be fitted to its series' values, a stock chart's high is below * its low, a hidden legend entry isn't one of the legend's, or an option is out of its range */ constructor(options: ChartRunOptions); } /** * Options for creating a chart. `type` decides the other options: each type has its own. * * @see {@link ChartRun} * @publicApi */ export declare type ChartRunOptions = ColumnChartOptions | BarChartOptions | LineChartOptions | AreaChartOptions | PieChartOptions | DoughnutChartOptions | PieOfPieChartOptions | BarOfPieChartOptions | RadarChartOptions | ScatterChartOptions | BubbleChartOptions | StockChartOptions; /** * A series of a column, bar, line or area chart: one value for each category. * * `markers`, `smooth` and `line` are for series drawn as lines, and `colors` for series drawn as bars. * * @publicApi */ export declare type ChartSeries = { /** The series' name, shown in the legend */ readonly name: string; /** One value for each category, in order. `null` leaves a gap. A series can have fewer values than there are categories */ readonly values: readonly (number | null)[]; /** * The colour of the series' bars, line or area: a 6-digit hex colour such as `"4472C4"`, or a colour of the * document's theme such as `{ theme: "accent2" }`. Default is the next of the theme's accent colours */ readonly color?: string | ThemeColor; /** * Draws the series as columns, a line or an area, whatever the chart's `type`, as Word's "Combo" charts do. Default * is the chart's `type`. A bar chart's series are all bars */ readonly type?: ComboChartSeriesType; /** Draws the series against the secondary value axis, on the right. Default is `"primary"` */ readonly axis?: ChartAxisGroup; /** The series' own labels, instead of the chart's `dataLabels`, or `false` for none */ readonly dataLabels?: false | ChartDataLabels; /** * One colour for each bar, in the order of the categories. A bar without one, or with `undefined`, takes the series' * colour. Only for series drawn as bars */ readonly colors?: readonly (string | ThemeColor | undefined)[]; /** Draws a marker at each point, or markers of a shape and size. Default is the chart's `markers`. Only for lines */ readonly markers?: boolean | ChartMarker; /** Draws the line as a smooth curve. Default is the chart's `smooth`. Only for lines */ readonly smooth?: boolean; /** The line's colour, width and dashes. Only for lines */ readonly line?: ChartLine; /** * Labels of single bars or points, in the order of the categories: a label of its own, `false` for none, or * `undefined` for the series' own */ readonly pointLabels?: readonly (false | ChartPointLabel | undefined)[]; /** Lines fitted to the values. Not for stacked series */ readonly trendlines?: readonly ChartTrendline[]; /** Error bars along the values: up and down from columns, lines and areas, or left and right from a bar chart's bars */ readonly errorBars?: ChartErrorBars; }; /** * The size of a chart, in pixels. * * @publicApi */ export declare type ChartSize = { /** Width in pixels */ readonly width: number; /** Height in pixels */ readonly height: number; }; /** * Whether the series of a column, bar, line or area chart are stacked: `"none"` draws them side by side, `"stacked"` on * top of each other, and `"percent"` on top of each other as a percentage of the category's total, as Word's "Stacked" * and "100% Stacked" charts do. * * @publicApi */ export declare type ChartStacking = "none" | "stacked" | "percent"; /** * A title with a font of its own. * * @publicApi */ export declare type ChartTitle = { /** The title. Each line of the text is a line of the title */ readonly text: string; /** The title's font */ readonly font?: ChartFont; }; /** * A trendline: a line fitted to a series' values, which shows their trend, and can extend it forward or backward as a * forecast. It is drawn as a dotted line in the series' colour, and has an entry in the legend. * * @publicApi */ export declare type ChartTrendline = { /** The kind of line fitted to the values */ readonly type: ChartTrendlineType; /** The order of a polynomial trendline, from 2 to 6: 2 has one bend, 3 has two, and so on. Default is 2 */ readonly order?: number; /** * How many points each point of a moving average averages, from 2 to one fewer than the series' values or points. * Default is 2 */ readonly period?: number; /** The trendline's name in the legend. Default is Office's, such as "Linear (Sales)" */ readonly name?: string; /** * Extends the trendline past the last point by this many categories, or on a scatter or bubble chart, this much along * the x axis. Default is 0. Not for moving averages */ readonly forecastForward?: number; /** * Extends the trendline before the first point by this many categories, or on a scatter or bubble chart, this much * along the x axis. Default is 0. Not for moving averages */ readonly forecastBackward?: number; /** * Where the trendline crosses the vertical axis: its value where x is 0. Default is where the values put it. Only for * linear, exponential and polynomial trendlines, and above 0 for exponential ones */ readonly intercept?: number; /** Shows the trendline's equation on the chart, such as "y = 2.5x + 4". Default is `false`. Not for moving averages */ readonly equation?: boolean; /** Shows how well the trendline fits the values, its R² value, on the chart. Default is `false`. Not for moving averages */ readonly rSquared?: boolean; /** The equation's and R² value's number format and font */ readonly label?: ChartTrendlineLabel; /** The line's colour, width and dashes. Default is the series' colour, 1.5 points wide, with short dots */ readonly line?: ChartLine; }; /** * The label of a trendline's equation and R² value. * * @publicApi */ export declare type ChartTrendlineLabel = { /** How the numbers are written, as an Excel number format such as `"#,##0.00"`. Default is `"General"` */ readonly numberFormat?: string; /** The label's font. Default is 9 points */ readonly font?: ChartFont; }; /** * The kind of line a trendline fits to a series' values: * * - `"linear"`: a straight line; * - `"exponential"`: a curve that rises or falls ever faster, for values above 0; * - `"logarithmic"`: a curve that rises or falls quickly, then levels out; * - `"polynomial"`: a curve with as many bends as its `order`, less one; * - `"power"`: a curve for values that grow at a steady rate, above 0; * - `"movingAverage"`: the average of each point and the points before it, which smooths out the ups and downs. * * @publicApi */ export declare type ChartTrendlineType = "linear" | "exponential" | "logarithmic" | "polynomial" | "power" | "movingAverage"; /** * The type of a chart, by the name Word gives it in Insert Chart. * * @publicApi */ export declare type ChartType = ChartRunOptions["type"]; /** * An axis of values: as {@link ChartAxis}, with its range, the interval between its labels, and its scale. On a 100% * stacked chart, the range and interval are percentages. * * @publicApi */ export declare type ChartValueAxis = ChartAxis & { /** The lowest value on the axis. Default is chosen from the values */ readonly minimum?: number; /** The highest value on the axis. Default is chosen from the values */ readonly maximum?: number; /** The interval between the axis' labels and gridlines. Default is chosen from the values */ readonly interval?: number; /** * Makes the scale logarithmic, with this base, from 2 to 1000: with 10, the labels are 1, 10, 100 and so on. Values * of 0 or less can't be shown. Default is a linear scale */ readonly logarithmicBase?: number; /** Writes the labels in hundreds, thousands, millions and so on. Default is the values as they are */ readonly displayUnits?: ChartDisplayUnits; }; /** * A column chart: vertical bars (`c:barChart` with `c:barDir="col"`). Series can be drawn as lines or areas instead. * * @publicApi */ export declare type ColumnChartOptions = BarChartBaseOptions & { readonly type: "column"; }; /** * How a series of a column, line or area chart is drawn, when it isn't drawn as the chart's `type`: as columns, a line * or an area. A chart with series of more than one type is Word's "Combo" chart. * * @publicApi */ export declare type ComboChartSeriesType = "column" | "line" | "area"; /** * A doughnut chart (`c:doughnutChart`): a ring for each series, the first on the inside. * * @publicApi */ export declare type DoughnutChartOptions = PieChartBaseOptions & { readonly type: "doughnut"; /** The series, a ring each */ readonly series: readonly PieChartSeries[]; /** The size of the hole, as a percentage of the chart's diameter, from 10 to 90. Default is 50 */ readonly holeSize?: number; }; /** * A line chart (`c:lineChart`). Series can be drawn as columns or areas instead. * * @publicApi */ export declare type LineChartOptions = CategoryChartOptions & { readonly type: "line"; /** Draws a marker at each point, as Word's "Line with Markers" does, or markers of a shape and size. Default is `false` */ readonly markers?: boolean | ChartMarker; /** Draws the lines as smooth curves. Default is `false` */ readonly smooth?: boolean; }; /** * Options of pie and doughnut charts. * * @publicApi */ export declare type PieChartBaseOptions = ChartBaseOptions & { /** The categories: one slice of each series for each category */ readonly categories: readonly (string | number)[]; /** Labels on each slice */ readonly dataLabels?: PieChartDataLabels; /** Where the first slice starts, in degrees clockwise from 12 o'clock, from 0 to 360. Default is 0 */ readonly firstSliceAngle?: number; }; /** * What the labels on each slice of a pie or doughnut chart show: as {@link ChartDataLabels}, or the slice's percentage * of the whole. * * @publicApi */ export declare type PieChartDataLabels = ChartDataLabels & { /** The slice's percentage of the whole. Default is `false` */ readonly percentage?: boolean; }; /** * A pie chart (`c:pieChart`), with one series. * * @publicApi */ export declare type PieChartOptions = PieChartBaseOptions & { readonly type: "pie"; /** The series. A pie chart has one */ readonly series: readonly PieChartSeries[]; }; /** * The label of one slice of a pie or doughnut chart: as {@link ChartPointLabel}, or the slice's percentage. * * @publicApi */ export declare type PieChartPointLabel = PieChartDataLabels & ChartLabelText; /** * The series of a pie chart, or a ring of a doughnut chart: one value, a slice, for each category. * * @publicApi */ export declare type PieChartSeries = { /** The series' name */ readonly name: string; /** One value for each category, in order. `null` leaves the slice out. Values can't be negative */ readonly values: readonly (number | null)[]; /** * One colour for each slice, as a 6-digit hex colour or a colour of the document's theme. A slice without one, or * with `undefined`, takes the next of the theme's accent colours */ readonly colors?: readonly (string | ThemeColor | undefined)[]; /** The series' own labels, instead of the chart's `dataLabels`, or `false` for none */ readonly dataLabels?: false | PieChartDataLabels; /** * Labels of single slices, in the order of the categories: a label of its own, `false` for none, or `undefined` for * the series' own */ readonly pointLabels?: readonly (false | PieChartPointLabel | undefined)[]; /** * Pulls the slices out from the centre, by a percentage of the radius from 0 to 400: one amount for every slice, or * one for each slice in the order of the categories, where `undefined` leaves a slice in. Default is 0 */ readonly explosion?: number | readonly (number | undefined)[]; }; /** * How a pie of pie or bar of pie chart picks the slices it moves from the pie to the second plot: * * - `"position"`: the last `count` categories; * - `"value"`: the slices whose values are less than `lessThan`; * - `"percentage"`: the slices less than `lessThan` percent of the whole; * - `"categories"`: the slices of the categories given. * * @publicApi */ export declare type PieChartSplit = { readonly by: "position"; /** How many of the last categories go to the second plot, from 1 to the number of categories */ readonly count: number; } | { readonly by: "value"; /** Slices with values less than this go to the second plot */ readonly lessThan: number; } | { readonly by: "percentage"; /** Slices less than this percentage of the whole, from 0 to 100, go to the second plot */ readonly lessThan: number; } | { readonly by: "categories"; /** The categories whose slices go to the second plot */ readonly categories: readonly (string | number)[]; }; /** * A pie of pie chart (`c:ofPieChart` with `c:ofPieType="pie"`): the small slices of a pie drawn again as a second pie * beside it. * * @publicApi */ export declare type PieOfPieChartOptions = SplitPieChartBaseOptions & { readonly type: "pieOfPie"; }; /** * New data for a scatter or bubble chart. * * @publicApi */ export declare type PointChartDataPatchOptions = { /** The series, each with its points */ readonly series: readonly PointChartDataSeries[]; /** * The chart's alt text description. Default is a description of the chart from its new data, and none for a * decorative chart. An empty description removes it */ readonly description?: string; }; /** * A series of new data for a scatter or bubble chart. * * @publicApi */ export declare type PointChartDataSeries = { /** The series' name, shown in the legend */ readonly name: string; /** The series' points, in order. A bubble chart's points each need a size, which a scatter chart's leave out */ readonly points: readonly (ChartPoint | BubbleChartPoint)[]; }; /** * A radar chart (`c:radarChart`): a spoke for each category, and a line around the spokes for each series. * * @publicApi */ export declare type RadarChartOptions = ChartBaseOptions & { readonly type: "radar"; /** The categories: a spoke each, clockwise from 12 o'clock */ readonly categories: readonly (string | number)[]; /** The series, one value for each category */ readonly series: readonly RadarChartSeries[]; /** * Draws a marker at each point, as Word's "Radar with Markers" does, or markers of a shape and size. Default is * `false`. Not for filled charts */ readonly markers?: boolean | ChartMarker; /** Fills the area inside each series' line, as Word's "Filled Radar" does. Default is `false` */ readonly filled?: boolean; /** The axis of categories: the labels at the end of the spokes, and the spokes, which are its gridlines */ readonly categoryAxis?: ChartAxis; /** The axis of values, up the first spoke. Its gridlines are the rings */ readonly valueAxis?: ChartValueAxis; /** Labels on each point */ readonly dataLabels?: ChartDataLabels; /** How empty values (`null`) are drawn: as gaps, as zero, or with a line joining the points either side. Default is `"gap"` */ readonly emptyValues?: ChartEmptyValues; }; /** * A series of a radar chart: one value for each category, on the category's spoke. * * @publicApi */ export declare type RadarChartSeries = { /** The series' name, shown in the legend */ readonly name: string; /** One value for each category, in order. `null` leaves a gap */ readonly values: readonly (number | null)[]; /** The colour of the series' line or area. Default is the next of the theme's accent colours */ readonly color?: string | ThemeColor; /** The series' own labels, instead of the chart's `dataLabels`, or `false` for none */ readonly dataLabels?: false | ChartDataLabels; /** Draws a marker at each point, or markers of a shape and size. Default is the chart's `markers`. Not for filled charts */ readonly markers?: boolean | ChartMarker; /** The line's colour, width and dashes. Not for filled charts */ readonly line?: ChartLine; /** * Labels of single points, in the order of the categories: a label of its own, `false` for none, or `undefined` for * the series' own */ readonly pointLabels?: readonly (false | ChartPointLabel | undefined)[]; }; /** * A scatter chart (`c:scatterChart`): points, each with its own x and y, on two value axes. * * @publicApi */ export declare type ScatterChartOptions = ChartBaseOptions & { readonly type: "scatter"; /** The series, each with its points */ readonly series: readonly ScatterChartSeries[]; /** Draws a marker at each point, or markers of a shape and size. Default is `true` */ readonly markers?: boolean | ChartMarker; /** Joins the points of each series: `"none"`, `"straight"` or `"smooth"`. Default is `"none"` */ readonly lines?: "none" | "straight" | "smooth"; /** The horizontal axis */ readonly xAxis?: ChartValueAxis; /** The vertical axis */ readonly yAxis?: ChartValueAxis; /** Labels on each point */ readonly dataLabels?: ChartDataLabels; }; /** * A series of a scatter chart: points, each with its own x and y. * * @publicApi */ export declare type ScatterChartSeries = { /** The series' name, shown in the legend */ readonly name: string; /** The series' points, in order */ readonly points: readonly ChartPoint[]; /** The colour of the series' markers and line. Default is the next of the theme's accent colours */ readonly color?: string | ThemeColor; /** The series' own labels, instead of the chart's `dataLabels`, or `false` for none */ readonly dataLabels?: false | ChartDataLabels; /** Draws a marker at each point, or markers of a shape and size. Default is the chart's `markers` */ readonly markers?: boolean | ChartMarker; /** The line's colour, width and dashes. Only when the chart's `lines` join the points */ readonly line?: ChartLine; /** Labels of single points, in order: a label of its own, `false` for none, or `undefined` for the series' own */ readonly pointLabels?: readonly (false | ChartPointLabel | undefined)[]; /** Lines fitted to the points */ readonly trendlines?: readonly ChartTrendline[]; /** Error bars along the x axis, left and right of each point */ readonly xErrorBars?: ChartErrorBars; /** Error bars along the y axis, up and down from each point */ readonly yErrorBars?: ChartErrorBars; }; /** * Options of pie of pie and bar of pie charts: a pie with some of its slices taken out, and drawn beside it as a * second pie or a stacked bar, joined to the slice of the pie that stands for them. * * @publicApi */ export declare type SplitPieChartBaseOptions = Omit & { /** The series. The chart has one */ readonly series: readonly PieChartSeries[]; /** Which slices go to the second plot. Default is the last third of the categories, rounded up */ readonly split?: PieChartSplit; /** The size of the second plot, as a percentage of the pie's, from 5 to 200. Default is 75 */ readonly secondPlotSize?: number; /** The gap between the pie and the second plot, as a percentage of the second plot's width, from 0 to 500. Default is 100 */ readonly gapWidth?: number; /** The lines joining the pie to the second plot. Default is thin grey lines */ readonly seriesLines?: ChartLine; }; /** * New data for a stock chart: each category's prices, and if the chart has them, its opening prices and volumes. * * @publicApi */ export declare type StockChartDataPatchOptions = { /** The categories, such as trading days, in order */ readonly categories: readonly (string | number | Date)[]; /** Each category's opening price, for a chart with opening prices */ readonly open?: readonly (number | null)[]; /** Each category's highest price */ readonly high: readonly (number | null)[]; /** Each category's lowest price */ readonly low: readonly (number | null)[]; /** Each category's closing price */ readonly close: readonly (number | null)[]; /** Each category's volume traded, for a chart with volumes */ readonly volume?: readonly (number | null)[]; /** The series' names, as the legend shows them. Default is "Volume", "Open", "High", "Low" and "Close" */ readonly names?: StockChartSeriesNames; /** * The chart's alt text description. Default is a description of the chart from its new data, and none for a * decorative chart. An empty description removes it */ readonly description?: string; }; /** * A stock chart (`c:stockChart`): each category's high and low prices joined by a line, with its closing price, and if * given, its opening price and the volume traded, as Word's "High-Low-Close", "Open-High-Low-Close", * "Volume-High-Low-Close" and "Volume-Open-High-Low-Close" charts. Each price list has one value for each category, in * order, and `null` leaves a gap. * * @publicApi */ export declare type StockChartOptions = ChartBaseOptions & { readonly type: "stock"; /** * The categories, such as trading days, in order. Dates are spaced evenly, one for each category, so days without * trading, such as weekends, leave no gaps */ readonly categories: readonly (string | number | Date)[]; /** * Each category's opening price. With it, a bar goes from the open to the close: hollow when the price rose, and * filled when it fell */ readonly open?: readonly (number | null)[]; /** Each category's highest price */ readonly high: readonly (number | null)[]; /** Each category's lowest price */ readonly low: readonly (number | null)[]; /** Each category's closing price */ readonly close: readonly (number | null)[]; /** Each category's volume traded, drawn as columns against an axis of its own on the left, with the prices' on the right */ readonly volume?: readonly (number | null)[]; /** The series' names, as the legend shows them */ readonly names?: StockChartSeriesNames; /** The axis of categories */ readonly categoryAxis?: ChartAxis; /** The axis of prices */ readonly valueAxis?: ChartValueAxis; /** The axis of volumes, when there are volumes */ readonly volumeAxis?: ChartValueAxis; /** The line from each high to each low. Default is a thin dark grey line */ readonly highLowLines?: ChartLine; /** The fill and border of the bars where the price rose, when there are opening prices. Default is white, with a grey border */ readonly upBars?: ChartAreaStyle; /** The fill and border of the bars where the price fell, when there are opening prices. Default is dark grey */ readonly downBars?: ChartAreaStyle; /** How empty values (`null`) are drawn: as gaps, or as zero. Default is `"gap"` */ readonly emptyValues?: ChartEmptyValues; /** A table of the data under the plot, or `true` for one with Office's borders and legend keys. Default is none */ readonly dataTable?: boolean | ChartDataTable; }; /** * The names of a stock chart's series, as the legend shows them. * * @publicApi */ export declare type StockChartSeriesNames = { /** Default is `"Volume"` */ readonly volume?: string; /** Default is `"Open"` */ readonly open?: string; /** Default is `"High"` */ readonly high?: string; /** Default is `"Low"` */ readonly low?: string; /** Default is `"Close"` */ readonly close?: string; }; export { }