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

package/types/src/chart/model/_Edits.d.ts

@@ -0,0 +1,489 @@
+import { IFill } from '../../fill/IFill';
+import { IStroke } from '../../fill/IStroke';
+import { IFont } from '../../font/IFont';
+import { ChartModel } from './ChartModel';
+import { CategoryAxisFields, NewChartType } from './_NewChart';
+export type ModelEdit = (model: ChartModel.ChartSpace) => ChartModel.ChartSpace;
+/** Applies `edits` in turn: what `update` batches into one step. */
+export declare const composeEdits: (edits: readonly ModelEdit[]) => ModelEdit;
+/** Edits the axis `axId`. */
+export declare const withAxis: (model: ChartModel.ChartSpace, axId: number, edit: (axis: ChartModel.Axis) => ChartModel.Axis) => ChartModel.ChartSpace;
+export declare const withGroupOf: (model: ChartModel.ChartSpace, idx: number, edit: (group: ChartModel.Group, series: ChartModel.Series) => ChartModel.Group) => ChartModel.ChartSpace;
+/** Edits the series `idx`. */
+export declare const withSeries: (model: ChartModel.ChartSpace, idx: number, edit: (series: ChartModel.Series) => ChartModel.Series) => ChartModel.ChartSpace;
+/**
+ * Shows or deletes the chart's title. Deleted, Excel writes no title and `autoTitleDeleted 1` (E03);
+ * shown again, the title a new chart has (E27).
+ */
+export declare const setTitleVisible: (visible: boolean) => ModelEdit;
+/**
+ * Sets the title's text, showing it; `null` for the automatic text (E01: rich text in the title's
+ * own text body). A 2016 chart's title states plain text (`cx:txData`, chart-chartex.xlsx X9).
+ */
+export declare const setTitleText: (text: string | null) => ModelEdit;
+/** Whether the title is drawn over the plot area rather than beside it (E02: `overlay 1`). */
+export declare const setTitleOverlay: (overlay: boolean) => ModelEdit;
+/** Shows or removes the legend. Removed, Excel writes none (E08); shown, at the right (E28). */
+export declare const setLegendVisible: (visible: boolean) => ModelEdit;
+/** Moves the legend to a side, or the top right corner (`tr`), showing it (E04-E07: `legendPos`). */
+export declare const setLegendPosition: (position: NonNullable<ChartModel.Legend["legendPos"]>) => ModelEdit;
+/** Whether the legend is drawn over the plot area (E09: `overlay 1`). */
+export declare const setLegendOverlay: (overlay: boolean) => ModelEdit;
+export declare const setDisplayBlanksAs: (value: NonNullable<ChartModel.Chart["dispBlanksAs"]>) => ModelEdit;
+/** A bound of the axis's scale: a number, or `'auto'` to leave it to Excel (E10, E11: `c:min`, `c:max` in `c:scaling`; E26). */
+export declare const setAxisBound: (axId: number, bound: "min" | "max", value: number | "auto") => ModelEdit;
+/** The axis's major or minor unit, or `'auto'` (E12: `c:majorUnit`). */
+export declare const setAxisUnit: (axId: number, unit: "majorUnit" | "minorUnit", value: number | "auto") => ModelEdit;
+/** The format of the axis's labels, no longer linked to its data (E13: `formatCode`, `sourceLinked 0`). */
+export declare const setAxisNumberFormat: (axId: number, formatCode: string) => ModelEdit;
+/** Whether the axis's labels take the format of its data (`sourceLinked 1`, as a new chart states it). */
+export declare const setAxisLinkNumberFormat: (axId: number, linked: boolean) => ModelEdit;
+/**
+ * Shows or deletes the axis (E14, E15: `delete 1`). Excel also drops the deleted axis's line and
+ * text formatting; the model keeps them, so an axis shown again looks as it did (Excel opens either).
+ */
+export declare const setAxisVisible: (axId: number, visible: boolean) => ModelEdit;
+/**
+ * Sets the axis's title text, `null` removing the title (E16, E17: rich text at 10 pt, the title's
+ * own text body and no fill or line).
+ */
+export declare const setAxisTitle: (axId: number, text: string | null) => ModelEdit;
+/**
+ * Whether a category axis draws each level of multi-level categories (`noMultiLvlLbl` off), or one
+ * label per category of all its levels. Excel states the flag either way, on an axis with one level
+ * too (N00-N05). A date axis has no such flag, and Excel writes nothing for it (N19).
+ */
+export declare const setAxisMultiLevel: (axId: number, multiLevel: boolean) => ModelEdit;
+/**
+ * Sets the categories of every series plotted on the category axis `axId` (N10-N17, N31-N35:
+ * Excel's `CategoryNames`), leaving the series of other axes and the multi-level flag as they are
+ * (N18, N21, N33). `axis` is what the axis states of the categories when they are cells: an axis
+ * that reads dates as dates (`auto`) becomes a date axis when they all are, and a text axis again
+ * when they are not (N14, N1A), and a linked format takes the cells' (N14; for numbers, believed).
+ */
+export declare const setAxisCategories: (axId: number, source: ChartModel.DataSource | undefined, axis: CategoryAxisFields | null) => ModelEdit;
+/** Shows or removes the axis's major or minor gridlines (E18-E20). */
+export declare const setAxisGridlines: (axId: number, which: "majorGridlines" | "minorGridlines", visible: boolean) => ModelEdit;
+/** What the gridlines are drawn with: their `spPr` (`undefined` for the application's default). */
+export declare const setAxisGridlinesShape: (axId: number, which: "majorGridlines" | "minorGridlines", spPr: ChartModel.ShapeProperties | undefined) => ModelEdit;
+/** A series' name: text written into the chart (`c:v`), a reference to a cell (a formula), or `null` for none. */
+export declare const setSeriesName: (idx: number, name: string | null) => ModelEdit;
+/** Which dimension of a series a setter states. */
+export type SeriesDimension = 'values' | 'categories' | 'bubbleSizes';
+/**
+ * Sets one dimension of a series: its values (`val`, a scatter's `yVal`), its categories (`cat`, a
+ * scatter's `xVal`) or a bubble's sizes. `source` is the reference or literal the caller made of the
+ * cells; `undefined` removes the dimension (a series with no categories plots against 1, 2, 3…).
+ */
+export declare const setSeriesSource: (idx: number, dimension: SeriesDimension, source: ChartModel.DataSource | undefined) => ModelEdit;
+/** What a series is drawn with (its `spPr`), as the shape style writes it: a key set to `undefined` is removed. */
+export declare const setSeriesShape: (idx: number, patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/**
+ * Sets a series' marker symbol, size, or what it is drawn with. A line series given a symbol shows
+ * markers (E35: its group states `marker 1`, the series Excel's 5 pt marker in its color); given
+ * `none`, Excel drops the marker's size and formatting, and the group's `marker` (E33).
+ */
+export declare const setSeriesMarker: (idx: number, marker: {
+    symbol?: ChartModel.Marker["symbol"];
+    size?: number;
+    spPr?: ChartModel.ShapeProperties | null;
+}) => ModelEdit;
+/** A group option set through one of its series, as Office Scripts sets it: gap width, overlap, an of-pie's second plot size. */
+export declare const setGroupOption: <K extends "gapWidth" | "overlap" | "secondPieSize">(idx: number, key: K, value: number) => ModelEdit;
+/**
+ * A bubble group's option set through one of its series, as Excel writes it (`probe-chart-bubble.ps1`
+ * B02, B04, B06): `bubbleScale`, `showNegBubbles`, and `sizeRepresents` `w` (by area, Excel's
+ * default, it states none: by belief, as B01 states none).
+ */
+export declare const setBubbleOption: (idx: number, option: {
+    bubbleScale?: number;
+    showNegBubbles?: boolean;
+    sizeRepresents?: "area" | "w";
+}) => ModelEdit;
+/** A change to how an of-pie splits its points: a split type, a split value, or the points of the second plot. */
+export type OfPieSplitChange = {
+    type: 'pos' | 'val' | 'percent' | 'cust';
+} | {
+    value: number;
+} | {
+    points: readonly number[];
+};
+/**
+ * An of-pie's split changed as Excel writes it (measured 2026-10-18, `probe-chart-ofpie.ps1`), worked
+ * out from the group it is applied to, so a type and a value set together compose as Excel's two
+ * writes do (O03-O05). `values` are the series' points, by which the points now in the second plot
+ * are found:
+ * - a type: by value writes a split value of 1 (O27; by percent, and from a type other than the
+ *   automatic, the same by belief); by position the number of points in the second plot now (by
+ *   belief); by hand, the points in the second plot now (O29);
+ * - a value: on the automatic split it becomes one by position (O28);
+ * - the points: a split by hand of them (O30: one point moved there adds it to those there).
+ */
+export declare const setOfPieSplit: (idx: number, change: OfPieSplitChange, values: readonly (number | null)[]) => ModelEdit;
+/** The flags a data label shows. */
+export type LabelFlag = 'showVal' | 'showCatName' | 'showSerName' | 'showPercent' | 'showBubbleSize' | 'showLegendKey';
+/** Whether labels show anything. */
+export declare const showsLabels: (labels: ChartModel.DataLabelOptions | undefined) => boolean;
+/**
+ * Shows a series' data labels, its values (D01: `HasDataLabels`), or removes them. Removed, the
+ * series' own labels go, and where its group's would still show it says so (`delete 1`): believed,
+ * Excel's own markup for a label turned off is not measured.
+ */
+export declare const setLabelsVisible: (idx: number, visible: boolean, chartLevel?: boolean) => ModelEdit;
+/**
+ * What a group's own labels state, set with every series' by `SetElement` (`probe-chart-elements.ps1`
+ * E201, E202: the group's `showVal 1` and `dLblPos`); `ApplyDataLabels` leaves the group's alone (L01).
+ */
+export declare const setGroupLabels: (idx: number, options: {
+    showVal?: boolean;
+    dLblPos?: ChartModel.DataLabelOptions["dLblPos"];
+}) => ModelEdit;
+/** A pie's labels shown for the whole chart state their leader lines (L11, L12, P201-P210); elsewhere nothing changes. */
+export declare const setLabelsLeaderLines: (idx: number) => ModelEdit;
+/** Sets one flag of a series' data labels, giving it Excel's labels where it has none (D18-D22). */
+export declare const setLabelsFlag: (idx: number, flag: LabelFlag, value: boolean) => ModelEdit;
+/** Where a series' labels sit (D23-D28: `dLblPos`), `undefined` for the type's default. */
+export declare const setLabelsPosition: (idx: number, position: ChartModel.DataLabelOptions["dLblPos"]) => ModelEdit;
+/** What separates the parts of a label: `, ` by default. */
+export declare const setLabelsSeparator: (idx: number, separator: string | undefined) => ModelEdit;
+/** The labels' number format, `null` for the values' own (D30: `formatCode`, `sourceLinked 0`). */
+export declare const setLabelsNumberFormat: (idx: number, formatCode: string | null) => ModelEdit;
+export type TrendlineModelType = ChartModel.Trendline['trendlineType'];
+/**
+ * The trendline Excel adds (T01-T07, T31, T33, T36): a 1.5 pt dotted line with round caps in
+ * `color`, the series' automatic color, `dispRSqr 0` and `dispEq 0`, and no label; a polynomial
+ * states order 2, a moving average period 2.
+ */
+export declare const newTrendline: (type: TrendlineModelType, color: string) => ChartModel.Trendline;
+/** Adds `trendline` after the series' others. */
+export declare const addTrendline: (idx: number, trendline: ChartModel.Trendline) => ModelEdit;
+/** Removes the series' trendline at `index` (T23, T24); a series left with none states none. */
+export declare const deleteTrendline: (idx: number, index: number) => ModelEdit;
+/**
+ * The kind of fit (T08, T25-T27, T29): a polynomial states order 2 and a moving average period 2,
+ * the other kind's option goes, and an intercept stays only on a type that holds one. A label stays
+ * as it is, on a moving average too (T27: Excel's label then shows nothing).
+ */
+export declare const setTrendlineType: (idx: number, index: number, type: TrendlineModelType) => ModelEdit;
+/** A polynomial's order (T09); on another type Excel changes nothing (T60). */
+export declare const setTrendlineOrder: (idx: number, index: number, order: number) => ModelEdit;
+/** A moving average's period (T10). */
+export declare const setTrendlinePeriod: (idx: number, index: number, period: number) => ModelEdit;
+/** How far the line runs past the last point or before the first (T11, T12); 0 states none (T57). */
+export declare const setTrendlineRun: (idx: number, index: number, which: "forward" | "backward", run: number) => ModelEdit;
+/**
+ * The y the fit is held to at x = 0 (T13, T52, T53), `'auto'` to let it go (T14). On a logarithmic
+ * or power fit Excel changes nothing (T46).
+ */
+export declare const setTrendlineIntercept: (idx: number, index: number, intercept: number | "auto") => ModelEdit;
+/**
+ * Whether the label shows the equation or R² (T15-T18): the first part shown adds Excel's label,
+ * and with neither shown the label goes. Excel keeps a hidden label's format for the session
+ * (T58); SheetXL's goes with it, as Excel's does at a save.
+ */
+export declare const setTrendlineDisplay: (idx: number, index: number, which: "dispEq" | "dispRSqr", show: boolean) => ModelEdit;
+/** The trendline's entry in the legend (T19), `null` for Excel's own (T20). */
+export declare const setTrendlineName: (idx: number, index: number, name: string | null) => ModelEdit;
+/** What the line is drawn with (T21), as the shape style writes it: a key set to `undefined` is removed. */
+export declare const setTrendlineShape: (idx: number, index: number, patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/**
+ * The format of the label's numbers (T22: `formatCode`, `sourceLinked 0`), `null` for General. A
+ * trendline that shows no label is given Excel's, so the format is kept for when it does.
+ */
+export declare const setTrendlineLabelFormat: (idx: number, index: number, formatCode: string | null) => ModelEdit;
+export type ErrorBarsDirection = 'x' | 'y';
+type ErrorValueType = ChartModel.ErrorBars['errValType'];
+/** Shows the series' error bars of `direction` (R01) or removes them (R15, R19). */
+export declare const setErrorBarsVisible: (idx: number, direction: ErrorBarsDirection, visible: boolean) => ModelEdit;
+/**
+ * What the bars' amount is (R05-R10, R20): a new type takes Excel's amount for it (by belief, as
+ * Excel's pane keeps one per type), standard error none (R08), custom values their `plus` and
+ * `minus` (R09).
+ */
+export declare const setErrorBarsType: (idx: number, direction: ErrorBarsDirection, type: ErrorValueType) => ModelEdit;
+/** The amount of a fixed value, a percentage or a number of deviations (`c:val`, R05-R07, R16-R18). */
+export declare const setErrorBarsAmount: (idx: number, direction: ErrorBarsDirection, amount: number) => ModelEdit;
+/** Which way from each point the bars run (R11, R12: `errBarType`). */
+export declare const setErrorBarsInclude: (idx: number, direction: ErrorBarsDirection, include: ChartModel.ErrorBars["errBarType"]) => ModelEdit;
+/** Whether the bars' ends are capped (R13: `noEndCap 1` for none). */
+export declare const setErrorBarsCap: (idx: number, direction: ErrorBarsDirection, cap: boolean) => ModelEdit;
+/** Each point's own amounts above and below (R09 from cells, R10 from arrays): custom bars. */
+export declare const setErrorBarsCustom: (idx: number, direction: ErrorBarsDirection, plus: ChartModel.DataSource, minus: ChartModel.DataSource) => ModelEdit;
+/** What the bars are drawn with (R14), as the shape style writes it: a key set to `undefined` is removed. */
+export declare const setErrorBarsShape: (idx: number, direction: ErrorBarsDirection, patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/** A group's lines of one kind: `c:hiLowLines`, `c:dropLines`, `c:serLines`. */
+export type GroupLinesKind = 'hiLowLines' | 'dropLines' | 'serLines';
+/**
+ * The line of the lines Excel adds (`probe-chart-lines.ps1` H01, D01, D03, V01, V03): 0.75 pt with
+ * flat ends, high-low lines darker than drop and series lines.
+ */
+export declare const LINES_COLORS: Readonly<Record<GroupLinesKind, string>>;
+/** The lines of `kind` Excel adds: its line, no fill. */
+export declare const newGroupLines: (kind: GroupLinesKind) => ChartModel.ChartLines;
+/** Shows the group's lines of `kind` as Excel adds them (H01, D01, V01), or removes them. */
+export declare const setGroupLinesVisible: (idx: number, kind: GroupLinesKind, visible: boolean) => ModelEdit;
+/** What the group's lines of `kind` are drawn with (H04, D05, V05), as the shape style writes it. */
+export declare const setGroupLinesShape: (idx: number, kind: GroupLinesKind, patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/** Which bars of up/down bars: where the last series ends above the first, or not. */
+export type UpDownBarsKind = 'upBars' | 'downBars';
+/** Shows the group's up/down bars as Excel adds them (U01, U02), or removes them (U08). */
+export declare const setUpDownBarsVisible: (idx: number, visible: boolean) => ModelEdit;
+/** The gap between up/down bars, as a percentage of a bar's width (U03, U04, U12). */
+export declare const setUpDownBarsGapWidth: (idx: number, gapWidth: number) => ModelEdit;
+/** What the up or down bars are drawn with (U05, U10), as the shape style writes it. */
+export declare const setUpDownBarsShape: (idx: number, kind: UpDownBarsKind, patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/** What a font setter states of a run: `null` hands a color or a typeface back to the theme's. */
+export interface FontPatch {
+    size?: number;
+    weight?: number;
+    italic?: boolean;
+    color?: string | null;
+    /** A family or a {@link IFontStyle.ThemeFamily}; `null` for the theme's body font. */
+    family?: string | null;
+    /** `null` hands the families back to the theme's. */
+    fallbacks?: string[] | null;
+    /** `none` is written, as Excel writes it. */
+    underline?: IFont.UnderlineStyle;
+    strike?: IFont.StrikeStyle;
+    /** Points between characters; 0 drops the attribute. */
+    letterSpacing?: number;
+    /** Percent of the size the text is raised; 0 drops the attribute. */
+    baseline?: number;
+    /** Removes what the run states of its font first, so it takes the text around it. */
+    clear?: boolean;
+}
+/** The default run of an element's text, as the font getters read it. */
+export declare const fontOf: (element: {
+    txPr?: ChartModel.TextBody;
+    tx?: ChartModel.Text;
+} | undefined) => ChartModel.RunProperties | undefined;
+/** The chart as a chart of `type` (C01-C22): see {@link convertChartType}. */
+export declare const setChartType: (type: NewChartType, counts: ReadonlyMap<number, number>) => ModelEdit;
+/**
+ * Every group made a custom group of `kind` (`ChartKinds`), keeping its series, axes and the
+ * options it had; `options` the kind's own.
+ */
+export declare const setCustomKind: (kind: string, options?: Record<string, unknown>) => ModelEdit;
+/** Whether hidden rows and columns are left out (P03: `plotVisOnly 0`). */
+export declare const setPlotVisibleOnly: (visible: boolean) => ModelEdit;
+/** Rounded corners (R26: `roundedCorners 1`). */
+export declare const setRoundedCorners: (rounded: boolean) => ModelEdit;
+/** What the chart area is drawn with (R19-R21), as the shape style writes it. */
+export declare const setChartAreaShape: (patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/**
+ * The chart's font (R22-R25, R38): the chart space's own default run, and every text in the chart
+ * takes the same; the title's size is 1.2 times the chart's (14.4 pt for 12, as 14 for Excel's 10).
+ */
+export declare const setChartFont: (patch: FontPatch) => ModelEdit;
+/** What the plot area is drawn with (R01-R03). */
+export declare const setPlotAreaShape: (patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/** Shows the data table as Excel adds it (R04), or removes it (R11). */
+export declare const setDataTableVisible: (visible: boolean) => ModelEdit;
+/** One of the data table's borders or its legend keys (R05-R08), showing the table. */
+export declare const setDataTableFlag: (flag: "showHorzBorder" | "showVertBorder" | "showOutline" | "showKeys", value: boolean) => ModelEdit;
+/** What the data table is drawn with (R09: a color set keeps the line's width and ends), showing it. */
+export declare const setDataTableShape: (patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/** The data table's font (R10), showing it. */
+export declare const setDataTableFont: (patch: FontPatch) => ModelEdit;
+/** What the title is drawn with (R33), showing it. */
+export declare const setTitleShape: (patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/** The title's font (R32, R34, R35: its text body and its rich text alike), showing it. */
+export declare const setTitleFont: (patch: FontPatch) => ModelEdit;
+/** What the legend is drawn with (R28, R29), showing it. */
+export declare const setLegendShape: (patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/** The legend's font (R27), showing it. */
+export declare const setLegendFont: (patch: FontPatch) => ModelEdit;
+/** Whether the legend's entry `idx` is shown (R30, R37: `legendEntry` with `delete 1`); shown again, the entry goes unless it states a font. */
+export declare const setLegendEntryVisible: (idx: number, visible: boolean) => ModelEdit;
+/** The font of the legend's entry `idx` (R31: its own `txPr`, 9 pt). */
+export declare const setLegendEntryFont: (idx: number, patch: FontPatch) => ModelEdit;
+/** The axis's scale: logarithmic in `logBase` (X03, X04, X56: `c:logBase`), or linear with `null` (X05). */
+export declare const setAxisLogBase: (axId: number, logBase: number | null) => ModelEdit;
+/**
+ * The axis's display units (X06-X11): a built-in unit (`thousands`, `millions`…) or a custom
+ * divisor, with Excel's label; `null` for none. The label is kept as it was where the axis had one.
+ */
+export declare const setAxisDisplayUnits: (axId: number, unit: string | number | null) => ModelEdit;
+/** Whether the display units' label is shown (X10: `dispUnits` with no `dispUnitsLbl`). */
+export declare const setAxisDisplayUnitsLabel: (axId: number, visible: boolean) => ModelEdit;
+/**
+ * Where the axis crossing this one crosses it (X12-X17, X55): VBA's `Axis.Crosses` is written on
+ * the crossing axis, whose `crosses` says where it crosses this one: at this one's maximum (`max`;
+ * the crossing axis moves to the far side of the plot, X12, X16), its minimum, automatically
+ * (`autoZero`), or at a value (`crossesAt`, which replaces `crosses`).
+ */
+export declare const setAxisCrosses: (axId: number, at: "autoZero" | "max" | "min" | number) => ModelEdit;
+/** Whether the axis runs from its maximum to its minimum (X18-X20, X58, S361: `orientation maxMin`, the crossing axis moved to the other side). */
+export declare const setAxisReversed: (axId: number, reversed: boolean) => ModelEdit;
+/** The axis's major or minor tick marks (X21-X25). */
+export declare const setAxisTickMark: (axId: number, which: "majorTickMark" | "minorTickMark", mark: ChartModel.TickMark) => ModelEdit;
+/** Where the axis's labels sit (X26-X29, X63). */
+export declare const setAxisTickLabelPosition: (axId: number, position: NonNullable<ChartModel.Axis["tickLblPos"]>) => ModelEdit;
+/**
+ * The axis labels' orientation (X30-X35): a counterclockwise angle (45 is `rot -2700000`, -30
+ * `rot 1800000`), stacked (`vert wordArtVert`), or Excel's own (`rot -60000000`).
+ */
+export declare const setAxisTextRotation: (axId: number, rotation: number | "vertical" | "auto") => ModelEdit;
+/** What the axis line is drawn with (X36, X37, X59), as the shape style writes it. */
+export declare const setAxisShape: (axId: number, patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/** The axis labels' font (X38-X42, X59). */
+export declare const setAxisFont: (axId: number, patch: FontPatch) => ModelEdit;
+/**
+ * Shows the axis's title with Excel's own text (`probe-chart-elements.ps1` 301-311: a title with
+ * no `tx`, 10 pt, read up a side), or removes it.
+ */
+export declare const setAxisTitleVisible: (axId: number, visible: boolean) => ModelEdit;
+/** Whether the axis title is drawn over the plot area (`c:overlay`, as the chart title's). */
+export declare const setAxisTitleOverlay: (axId: number, overlay: boolean) => ModelEdit;
+/** The axis title's font (R36: its rich text and its body alike). */
+export declare const setAxisTitleFont: (axId: number, patch: FontPatch) => ModelEdit;
+/** What the axis title is drawn with. */
+export declare const setAxisTitleShape: (axId: number, patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/** The axis title's orientation (`probe-chart-elements.ps1` 301-311: rotated reads up, vertical is stacked, horizontal level). */
+export declare const setAxisTitleRotation: (axId: number, rotation: number | "vertical" | "auto") => ModelEdit;
+/** A category axis's label or tick mark spacing (X43, X44: `tickLblSkip`, `tickMarkSkip`); `null` for automatic. */
+export declare const setAxisSkip: (axId: number, which: "tickLblSkip" | "tickMarkSkip", count: number | null) => ModelEdit;
+/** A date axis's base unit (X45, X49), or `null` for Excel's own, restored from the dates as `auto` (X50). */
+export declare const setAxisBaseTimeUnit: (axId: number, unit: ChartModel.TimeUnit) => ModelEdit;
+/** A date axis's major or minor unit with its time unit (X46-X48), or automatic with `null` (both elements go). */
+export declare const setAxisTimeUnit: (axId: number, which: "major" | "minor", count: number | null, unit: ChartModel.TimeUnit) => ModelEdit;
+/**
+ * A category axis made a text axis, a date axis, or automatic (X51-X53): a date axis made text
+ * states `auto 0` with centered labels of one level and no base unit; a text axis made a date axis
+ * `auto 0` with Excel's base unit; automatic, `auto 1` and the type the categories decide.
+ */
+export declare const setAxisCategoryType: (axId: number, type: "cat" | "date" | "auto", dates: boolean, baseUnit: ChartModel.TimeUnit) => ModelEdit;
+/** What a new series is: its name and data, as the setters make them. */
+export interface NewSeries {
+    tx?: ChartModel.SeriesText;
+    cat?: ChartModel.DataSource;
+    val?: ChartModel.DataSource;
+    bubbleSize?: ChartModel.DataSource;
+    /** Its points, for a pie's colors. */
+    count: number;
+}
+/**
+ * Adds a series to the last group (N01-N13), with the next `idx` and `order`, drawn as Excel draws
+ * one; `position` puts it at that place in the plot order (N06: the others move after it).
+ */
+export declare const addSeries: (series: NewSeries, position?: number) => ModelEdit;
+/**
+ * A pie's, doughnut's or of-pie's series given values takes a point per value in the chart's
+ * colors with the white border (N11), where it has none.
+ */
+export declare const setSeriesPoints: (idx: number, count: number) => ModelEdit;
+/**
+ * Removes the series (N07-N10): its group too when emptied, and the axes no group draws against,
+ * unless it was the chart's only group (N09: the group stays, with no series).
+ */
+export declare const deleteSeries: (idx: number) => ModelEdit;
+/** The series' place in the plot order, from 0 (S05, S07, S08: `PlotOrder`); its group's series are relisted by it. */
+export declare const setSeriesOrder: (idx: number, position: number) => ModelEdit;
+/** A series' `smooth` (S10-S12) or `invertIfNegative` (S14, S15). */
+export declare const setSeriesFlag: (idx: number, flag: "smooth" | "invertIfNegative", value: boolean) => ModelEdit;
+/** How far a pie's or doughnut's slices are pulled out (S17, S18, S23: `explosion`, none for 0). */
+export declare const setSeriesExplosion: (idx: number, explosion: number) => ModelEdit;
+/**
+ * Whether a group of one series colors each point (S20-S22: `varyColors`). On, a single series
+ * takes a point per value in the colors of the places, its own fill moved to the first (S20); off, a
+ * pie's points go and the series takes the first point's fill (S22). Two series change the flag alone (S21).
+ */
+export declare const setGroupVaryColors: (idx: number, vary: boolean, count: number) => ModelEdit;
+/**
+ * What a point is drawn with (T01-T03, T14-T16): a bar's or slice's point takes the series' fill and
+ * line with the patch over them; a line's point takes the patch on its marker (its fill, T14) and
+ * on both its line and the marker's outline (T15).
+ */
+export declare const setPointShape: (idx: number, index: number, patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/** A point's own marker (T04, T05): symbol, size, or what it is drawn with, over the series' marker. */
+export declare const setPointMarker: (idx: number, index: number, marker: {
+    symbol?: ChartModel.Marker["symbol"];
+    size?: number;
+    spPr?: ChartModel.ShapeProperties | null;
+}) => ModelEdit;
+/** How far a slice is pulled out (T06: the point's `explosion`). */
+export declare const setPointExplosion: (idx: number, index: number, explosion: number) => ModelEdit;
+/**
+ * Whether a waterfall's point is a total (`subtotal`): a point that states nothing else is added or
+ * removed for it, as Excel writes a total only in the series' `cx:subtotals`.
+ */
+export declare const setPointSubtotal: (key: string, index: number, total: boolean) => ModelEdit;
+/** A point's `invertIfNegative` (T17). */
+export declare const setPointInvertIfNegative: (idx: number, index: number, invert: boolean) => ModelEdit;
+/** Shows a point's label (T07) or hides it: a `delete 1` label where the series shows labels (T12), else the label goes (T13). */
+export declare const setPointLabelVisible: (idx: number, index: number, visible: boolean) => ModelEdit;
+/** One flag of a point's label (T11). */
+export declare const setPointLabelFlag: (idx: number, index: number, flag: LabelFlag, value: boolean) => ModelEdit;
+/** Where a point's label sits (T08: `dLblPos`). */
+export declare const setPointLabelPosition: (idx: number, index: number, position: ChartModel.DataLabelOptions["dLblPos"]) => ModelEdit;
+/** A point's label's number format (T09), `null` for the values' own. */
+export declare const setPointLabelNumberFormat: (idx: number, index: number, formatCode: string | null) => ModelEdit;
+/** A point's label's text (T10: rich text of one run), `null` for the automatic text. */
+export declare const setPointLabelText: (idx: number, index: number, text: string | null) => ModelEdit;
+/** A point's label's font (T18). */
+export declare const setPointLabelFont: (idx: number, index: number, patch: FontPatch) => ModelEdit;
+/** What a point's label is drawn with (T19). */
+export declare const setPointLabelShape: (idx: number, index: number, patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/** What a series' labels are drawn with (L09), giving it Excel's labels where it has none. */
+export declare const setLabelsShape: (idx: number, patch: {
+    fill?: IFill.JSON;
+    stroke?: IStroke.JSON;
+}) => ModelEdit;
+/** A series' labels' font (L08, L14). */
+export declare const setLabelsFont: (idx: number, patch: FontPatch) => ModelEdit;
+/** A series' labels' orientation (L10). */
+export declare const setLabelsRotation: (idx: number, rotation: number | "vertical" | "auto") => ModelEdit;
+/** Whether a series' labels take the values' format (L15: off writes `General` unlinked). */
+export declare const setLabelsLinkNumberFormat: (idx: number, linked: boolean) => ModelEdit;
+/**
+ * The cells a series' labels show (Excel's "Value From Cells", L07 and `probe-chart-values.ps1`
+ * W8): the series' `c15:datalabelsRange` and its labels' `c15:showDataLabelsRange`; `null` removes both.
+ */
+export declare const setLabelsRange: (idx: number, source: ChartModel.DataReference | null) => ModelEdit;
+/** The `c:ext` uri of a series' `c15:datalabelsRange`, and of its labels' `c15:showDataLabelsRange`. */
+export declare const DATALABELS_RANGE_URI = "{02D57815-91ED-43cb-92C2-25804820EDAC}";
+export declare const LABELS_EXTENSION_URI = "{CE6537A1-D6FC-4f65-9D91-7224C49458BB}";
+export {};
+//# sourceMappingURL=_Edits.d.ts.map

package/types/src/chart/model/_Grouping.d.ts

@@ -0,0 +1,83 @@
+import { ChartModel } from './ChartModel';
+/** The type a series is given: a group type, plus the options that tell Excel's chart types apart. */
+export interface GroupTarget {
+    type: ChartModel.GroupType;
+    is3D?: boolean;
+    barDir?: 'bar' | 'col';
+    grouping?: ChartModel.Group['grouping'];
+}
+export type AxisGroup = 'primary' | 'secondary';
+/** Makes an `axId` no axis of the chart has. */
+export type NewAxisId = () => number;
+/**
+ * Types that do not combine. Measured: setting one series of a chart to bubble, a 3-D type or
+ * surface converts every series, and setting one series of such a chart to anything converts every
+ * series too. Of-pie is treated the same way; that is a belief, not measured. Stock is not: no
+ * series can be given a stock type (Excel refuses), and a stock series given another type leaves
+ * the stock group alone (measured 2026-10-18, `probe-chart-stock-refusals.ps1`).
+ */
+export declare const isWholeChartType: (group: GroupTarget) => boolean;
+/**
+ * The axis group a group draws against, or `null` for a group with no axes (a pie).
+ *
+ * @remarks
+ * The first pair of axes the plot area states is the primary one; any other pair is secondary. In a
+ * combo made from a pie chart, Excel's COM reports the new group as secondary even when its axes
+ * are the only ones in the part (measured before saving; not measured after a reload).
+ */
+export declare const axisGroupOf: (plotArea: ChartModel.PlotArea, group: ChartModel.Group) => AxisGroup | null;
+/** The group holding the series `idx`, and where. */
+export declare const findSeries: (plotArea: ChartModel.PlotArea, idx: number) => {
+    group: ChartModel.Group;
+    groupIndex: number;
+    series: ChartModel.Series;
+} | null;
+/**
+ * The series a chart names by `key` (`IChart.ISeries` paths): its `idx`, or `#` and its place among
+ * the chart's series, group by group, where it states none (a 2016 chart's, as Excel writes them).
+ */
+export declare const findSeriesByKey: (plotArea: ChartModel.PlotArea, key: string) => {
+    group: ChartModel.Group;
+    groupIndex: number;
+    series: ChartModel.Series;
+} | null;
+/** The key a chart names each series by, as {@link findSeriesByKey} finds it. */
+export declare const seriesKeys: (plotArea: ChartModel.PlotArea | undefined) => Map<ChartModel.Series, string>;
+/**
+ * Drops emptied groups, and the axes no group draws against. When the primary axes are left with no
+ * group, every group moves onto them and the secondary axes go: Excel has no chart with secondary
+ * axes only (measured: moving all four series of a column chart to the secondary axes, one by one,
+ * leaves them all on the primary axes in one group).
+ */
+export declare const tidyPlotArea: (plotArea: ChartModel.PlotArea) => ChartModel.PlotArea;
+/**
+ * Gives the series `idx` the type `target`, moving it to the group of that type on the axes it can
+ * share, as Excel does.
+ *
+ * @remarks
+ * - Changing only a group option (clustered to stacked, area to stacked area) changes the whole
+ *   group, every series in it (measured): grouping is per group.
+ * - The series joins the group of the target type on its own axes when it can share them, else on
+ *   the other pair; when neither fits it gets the secondary axes, made for it. A pie or doughnut has
+ *   no axes.
+ * - A category series added to a scatter chart shares the scatter group's axes, whose horizontal
+ *   axis becomes a category axis (measured).
+ * - Joining an existing column group this way drops that group's `overlap` (measured, and odd:
+ *   moving a series back by its axis group keeps it).
+ * - The group it leaves is removed when empty, and with it any axes no group uses.
+ *
+ * @throws When the move is one the probes did not measure: a third pair of axes would be needed.
+ */
+export declare const setSeriesType: (plotArea: ChartModel.PlotArea, idx: number, target: GroupTarget, newAxisId: NewAxisId) => ChartModel.PlotArea;
+/**
+ * Moves the series `idx` to the primary or secondary axes, keeping its type.
+ *
+ * @remarks
+ * Measured: the series joins the group of its type on those axes, or a new one that copies its old
+ * group's options (`gapWidth`, `overlap`, `grouping`…). The first move to the secondary axes adds
+ * them: for a column, line or area group a value axis on the right that crosses at the maximum and
+ * a deleted category axis at the bottom; for horizontal bars the value axis on top and the deleted
+ * category axis on the left. A series without axes (a pie) is not moved.
+ */
+export declare const setSeriesAxisGroup: (plotArea: ChartModel.PlotArea, idx: number, axisGroup: AxisGroup, newAxisId: NewAxisId) => ChartModel.PlotArea;
+//# sourceMappingURL=_Grouping.d.ts.map

package/types/src/chart/model/_Inference.d.ts

@@ -0,0 +1,52 @@
+import { IRange } from '@sheetxl/primitives';
+/**
+ * Which series a chart makes of a selection, as Excel's Insert Chart decides (measured 2026-10-17,
+ * `probe-chart-insert.ps1`, 83 selections through `AddChart2`, DESIGN-CHART §3.5). Ported from
+ * exhibit-master's `ChartSelection.ts`, whose header scan Excel agrees with; what it lacked (several
+ * areas side by side, a bubble's sizes) is Excel's measured behavior.
+ *
+ * @remarks
+ * Pure: it reads the cells through a {@link CellKind} callback and answers coordinates, so it runs
+ * on any grid. The caller turns a selection into areas first (a single cell becomes its current
+ * region, whole rows or columns their used cells).
+ */
+/** A cell as inference reads it: a date is a number in a date format. */
+export type CellKind = 'blank' | 'text' | 'number' | 'date';
+/** Whether each series is a row or a column of the data. */
+export type SeriesBy = 'rows' | 'columns';
+/** How the series' data is laid out: categories and values, x and y, or x, y and sizes. */
+export type InferenceFamily = 'category' | 'scatter' | 'bubble';
+/** One series as inferred: where its name, categories (or x values), values and sizes are. */
+export interface InferredSeries {
+    /** The cells naming the series, or `null` when it has no name. */
+    name: IRange.Coords[] | null;
+    /** The categories, or a scatter's or bubble's x values; `null` when there are none. */
+    categories: IRange.Coords[] | null;
+    values: IRange.Coords[];
+    /** A bubble's sizes: cells, or a count of points that are all sized 1. */
+    sizes?: IRange.Coords[] | number;
+}
+export interface Inference {
+    seriesBy: SeriesBy;
+    series: InferredSeries[];
+}
+/**
+ * The series Excel makes of `areas`, all on one sheet.
+ *
+ * @param areas The selection, in the order it was made. Areas that share their rows (or their
+ * columns) are read as one block with the cells between them left out; any other areas follow the
+ * first one's layout.
+ * @param kindAt What the cell at absolute coordinates holds.
+ * @param family How the chart's series take their data.
+ * @param seriesBy The direction, or `undefined` to let the cells decide.
+ */
+export declare function inferSeries(areas: readonly IRange.Coords[], kindAt: (rowIndex: number, colIndex: number) => CellKind, family?: InferenceFamily, seriesBy?: SeriesBy): Inference;
+/**
+ * The cells around `cell` up to blank rows and columns on every side, diagonals included: what
+ * Excel charts when one cell is selected (Excel's `CurrentRegion`, measured on a table, I21). A
+ * blank cell with nothing around it is itself.
+ *
+ * @param last The last row and column that hold anything; nothing past them is read.
+ */
+export declare function currentRegion(cell: IRange.CellCoords, kindAt: (rowIndex: number, colIndex: number) => CellKind, last: IRange.CellCoords): IRange.Coords;
+//# sourceMappingURL=_Inference.d.ts.map