xlvane 1.2.3 → 1.3.0

package/dist/{stream-write-DWD8Pflj.js → stream-write-D573ewpr.js}

@@ -1,4 +1,4 @@
-import { $t as drawingParts, A as limitExceeded, At as nameScopeKey, Bt as checkKeyText, C as Bytes, Ct as relationshipsPartName, D as TAIL_BYTES, Dt as normalizeTable, E as NotLoaded, Et as TABLE_CONTENT_TYPE, F as validateLocalHeaders, Gt as printXml, Ht as resolveLimits, I as WarningCollector, It as normalizeStyle, K as SheetRels, Kt as sheetProtectionXml, L as sheetNotFound, N as readCentralDirectory, O as checkSource$1, Ot as checkDefinedName, P as unsupported, Q as createSharedStrings, Qt as MediaParts, R as createWorksheetParser, S as workbookPartsToLoad, St as openPackage, T as HEAD_BYTES, Tn as clip, Tt as zipNameToPartName, Vt as checkOutputPositions, Wt as printNames, X as cellXml, Xt as DRAWING_CONTENT_TYPE, Y as buildStyles, Z as contentTypesXml, Zt as IMAGE_CONTENT_TYPES, _ as isoDate, _n as corePropertiesXml, _t as FormulaGroups, a as DATE_FORMAT, an as classifyRelationship, cn as MAX_ROWS, ct as sheetHead, d as convertCellInput, dt as sheetTail, f as createWorkbook, gn as appPropertiesXml, gt as workbookXml, h as detectHeader, hn as CORE_PROPERTIES_PART, ht as workbookRelsXml, i as readOptions, it as noteParts, j as locateCentralDirectory, jn as XlvError, k as corrupt, kt as checkUniqueName, ln as columnLetters, lt as sheetRelsPartName, mn as APP_PROPERTIES_PART, n as oneOfOption, nn as resolveImage, nt as hyperlinksXml, o as DATE_TIME_FORMAT, ot as rootRelsXml, p as sortedNotes, pt as tableParts, rt as nameTitles, sn as MAX_COLUMNS, st as rowStart, tn as metricsOf, u as checkBookViews, un as formatCellRef, ut as sheetRulesXml, v as analyzeWorkbook, w as CORRUPT_HINT, wt as partKey, xn as createXmlByteStreamParser, y as readNotes, yt as crc32, zt as DEFAULT_READ_LIMITS } from "./options-Cw7OraxE.js";
+import { $t as metricsOf, A as checkSource$1, B as createWorksheetParser, Bt as resolveLimits, Cn as CORE_PROPERTIES_PART, Ct as relationshipsPartName, D as HEAD_BYTES, Dt as checkUniqueName, E as CORRUPT_HINT, Et as checkDefinedName, F as readCentralDirectory, Ht as printNames, I as unsupported, Jt as DRAWING_CONTENT_TYPE, K as SheetRels, L as validateLocalHeaders, Lt as DEFAULT_READ_LIMITS, M as limitExceeded, N as locateCentralDirectory, Nn as clip, O as NotLoaded, Ot as nameScopeKey, Pt as normalizeStyle, Q as createSharedStrings, R as WarningCollector, Rt as checkKeyText, Sn as APP_PROPERTIES_PART, St as openPackage, T as Bytes, Tn as corePropertiesXml, Tt as normalizeTable, Ut as printXml, Wt as sheetProtectionXml, X as cellXml, Xt as MediaParts, Y as buildStyles, Yt as IMAGE_CONTENT_TYPES, Z as contentTypesXml, Zt as drawingParts, _t as FormulaGroups, a as DATE_FORMAT, b as readNotes, bn as partKey, cn as chartPartXml, ct as sheetHead, d as convertCellInput, dt as sheetTail, en as resolveAnchor, f as createWorkbook, g as detectHeader, gn as formatCellRef, gt as workbookXml, hn as columnLetters, ht as workbookRelsXml, i as readOptions, in as classifyRelationship, it as noteParts, j as corrupt, k as TAIL_BYTES, kn as createXmlByteStreamParser, ln as chartSheetNames, lt as sheetRelsPartName, mn as MAX_ROWS, n as oneOfOption, nt as hyperlinksXml, o as DATE_TIME_FORMAT, on as CHART_CONTENT_TYPE, ot as rootRelsXml, p as sortedNotes, pn as MAX_COLUMNS, pt as tableParts, rt as nameTitles, sn as chartPartName, st as rowStart, tn as resolveImage, u as checkBookViews, un as resolveChartSheets, ut as sheetRulesXml, v as isoDate, w as workbookPartsToLoad, wn as appPropertiesXml, wt as TABLE_CONTENT_TYPE, xn as zipNameToPartName, y as analyzeWorkbook, yt as crc32, z as sheetNotFound, zn as XlvError, zt as checkOutputPositions } from "./options-Cxt-LJE4.js";
 import { Deflate, Inflate } from "fflate";
 // src/zip/stream.ts
 /**
@@ -952,6 +952,7 @@ function writeWorkbookStream(options) {
 			"tables",
 			"images",
 			"background",
+			"charts",
 			"rows"
 		], `sheets[${String(i)}]`);
 		const state = s.get("state");
@@ -1058,6 +1059,7 @@ function writeWorkbookStream(options) {
 			sheet.addImage(image, anchor, options);
 		}
 		if (s.has("background")) sheet.background(s.get("background"));
+		for (const v of listOf("charts", "{ type: \"column\", anchor: \"E2:L18\", series: [{ values: \"Data!B2:B13\" }] }")) sheet.addChart(v);
 		return {
 			spec: raw,
 			sheet,
@@ -1074,6 +1076,12 @@ function writeWorkbookStream(options) {
 	const prepared = dynamic ? [] : specs.map(prepare);
 	if (!dynamic && !prepared.some((p) => p.sheet.state === "visible")) throw noVisibleSheet();
 	if (!dynamic) addNames();
+	if (!dynamic) {
+		const lookup = chartSheetNames(prepared.map((q) => q.sheet.name));
+		for (const p of prepared) for (const c of p.sheet.chartList) resolveChartSheets(c.chart, lookup, p.sheet.name);
+	}
+	/** Charts in workbook order (CH-01); their parts are written once every sheet name is known. */
+	const chartQueue = [];
 	const strings = shared ? createSharedStrings() : null;
 	const styleCache = /* @__PURE__ */ new WeakMap();
 	const dateStyle = /* @__PURE__ */ new Map();
@@ -1228,7 +1236,19 @@ function writeWorkbookStream(options) {
 			conditionalFormats: p.sheet.conditionalList,
 			dataValidations: p.sheet.validationList
 		}, n);
-		const drawing = drawingParts(p.sheet.imageList.map((i) => resolveImage(i, metricsOf(p.sheet.columnMap, p.sheet.rowMap))), p.sheet.backgroundImage, media, ++drawingCount, p.rels);
+		const frames = p.sheet.chartList.map((c) => {
+			chartQueue.push({
+				chart: c.chart,
+				sheet: p.sheet.name
+			});
+			return {
+				...resolveAnchor(c.anchor, metricsOf(p.sheet.columnMap, p.sheet.rowMap)),
+				name: c.chart.name,
+				description: c.chart.description,
+				target: `../charts/chart${String(chartQueue.length)}.xml`
+			};
+		});
+		const drawing = drawingParts(p.sheet.imageList.map((i) => resolveImage(i, metricsOf(p.sheet.columnMap, p.sheet.rowMap))), p.sheet.backgroundImage, media, ++drawingCount, p.rels, frames);
 		if (drawing.part === null) drawingCount--;
 		p.drawing = drawing.part;
 		const sheetTables = tableParts(p.sheet.tableList, tableCount + 1, p.rels);
@@ -1345,10 +1365,16 @@ function writeWorkbookStream(options) {
 		if (prepared.length === 0) throw new XlvError("XLV_E_INVALID_INPUT", "The workbook has no sheets.", { hint: "Add at least one sheet before closing the stream." });
 		if (!selected) throw noVisibleSheet();
 		if (dynamic) addNames();
+		const names = chartSheetNames(prepared.map((p) => p.sheet.name));
+		const chartParts = chartQueue.map((c, k) => ({
+			name: chartPartName(k + 1),
+			xml: chartPartXml(resolveChartSheets(c.chart, names, c.sheet), null)
+		}));
 		const app = appXml() !== null;
 		const overrides = [
 			...tableTypes(),
 			...prepared.flatMap((p) => p.drawing === null ? [] : [[p.drawing.name, DRAWING_CONTENT_TYPE]]),
+			...chartParts.map((c) => [c.name, CHART_CONTENT_TYPE]),
 			...media.entries().map((m) => [m.name, IMAGE_CONTENT_TYPES[m.name.slice(m.name.lastIndexOf(".") + 1)]])
 		];
 		yield {
@@ -1360,6 +1386,10 @@ function writeWorkbookStream(options) {
 			data: encoder.encode(rootRelsXml(core !== null, app))
 		};
 		yield* media.entries();
+		for (const c of chartParts) yield {
+			name: c.name,
+			data: encoder.encode(c.xml)
+		};
 		yield* closingParts();
 	}
 	return createZipStream(entries(), level);

package/dist/{stream-write-y52KUDW8.d.ts → stream-write-XnCyLdOy.d.ts}

@@ -81,7 +81,12 @@ interface ReadLimits {
   readonly maxXmlTextLength: number;
   /** Maximum number of elements plus attributes in a part that is parsed into a tree (workbook, styles, relationships). Default 1 000 000. */
   readonly maxXmlTreeElements: number;
-  /** Maximum number of cells in the workbook. Default 5 000 000 (about 0.9 GB of memory; see the README). */
+  /**
+   * Maximum number of cells in the workbook. Default 5 000 000 (about 0.9 GB of memory; see the
+   * README). `readWorkbook` reads charts after the cells of every sheet, and their chart groups and
+   * series (each counted once per chart part) count against what the cells leave of this limit;
+   * charts over it are skipped with `XLV_W_LIMIT_REACHED`.
+   */
   readonly maxCells: number;
   /**
    * Maximum total length, in UTF-16 code units, of the shared strings that cells refer to, each
@@ -112,7 +117,7 @@ declare const DEFAULT_READ_LIMITS: Readonly<ReadLimits>;
  * console.log(ERROR_CODES.includes('XLV_E_SHEET_NOT_FOUND')); // true
  * ```
  */
-declare const ERROR_CODES: readonly ["XLV_E_INVALID_INPUT", "XLV_E_INVALID_OPTION", "XLV_E_INVALID_ARGUMENT", "XLV_E_LIMIT_EXCEEDED", "XLV_E_NOT_ZIP", "XLV_E_UNSUPPORTED_CONTAINER", "XLV_E_ZIP_CORRUPT", "XLV_E_ZIP_UNSUPPORTED", "XLV_E_XML_MALFORMED", "XLV_E_XML_DTD_FORBIDDEN", "XLV_E_XML_ENTITY_FORBIDDEN", "XLV_E_XML_ENCODING", "XLV_E_PART_MISSING", "XLV_E_PART_INVALID", "XLV_E_INVALID_CELL_REF", "XLV_E_SHEET_NOT_FOUND", "XLV_E_TABLE_NOT_FOUND", "XLV_E_FILE_READ", "XLV_E_INVALID_VALUE", "XLV_E_INVALID_STYLE", "XLV_E_INVALID_SHEET_NAME", "XLV_E_DUPLICATE_SHEET_NAME", "XLV_E_INVALID_DEFINED_NAME", "XLV_E_INVALID_HYPERLINK", "XLV_E_INVALID_TABLE", "XLV_E_INVALID_IMAGE", "XLV_E_OVERLAPPING_MERGE", "XLV_E_FILE_EXISTS", "XLV_E_FILE_WRITE", "XLV_E_HEADER_NOT_FOUND", "XLV_E_SCHEMA_INVALID", "XLV_E_ASYNC_SCHEMA", "XLV_E_INVALID_ROWS", "XLV_E_JSON_INVALID", "XLV_E_CSV_MALFORMED", "XLV_E_NOT_SUPPORTED", "XLV_E_USAGE", "XLV_E_NOT_INSTALLED", "XLV_E_INTERNAL", "XLV_E_PATH_NOT_ALLOWED"];
+declare const ERROR_CODES: readonly ["XLV_E_INVALID_INPUT", "XLV_E_INVALID_OPTION", "XLV_E_INVALID_ARGUMENT", "XLV_E_LIMIT_EXCEEDED", "XLV_E_NOT_ZIP", "XLV_E_UNSUPPORTED_CONTAINER", "XLV_E_ZIP_CORRUPT", "XLV_E_ZIP_UNSUPPORTED", "XLV_E_XML_MALFORMED", "XLV_E_XML_DTD_FORBIDDEN", "XLV_E_XML_ENTITY_FORBIDDEN", "XLV_E_XML_ENCODING", "XLV_E_PART_MISSING", "XLV_E_PART_INVALID", "XLV_E_INVALID_CELL_REF", "XLV_E_SHEET_NOT_FOUND", "XLV_E_TABLE_NOT_FOUND", "XLV_E_FILE_READ", "XLV_E_INVALID_VALUE", "XLV_E_INVALID_STYLE", "XLV_E_INVALID_SHEET_NAME", "XLV_E_DUPLICATE_SHEET_NAME", "XLV_E_INVALID_DEFINED_NAME", "XLV_E_INVALID_HYPERLINK", "XLV_E_INVALID_TABLE", "XLV_E_INVALID_IMAGE", "XLV_E_INVALID_CHART", "XLV_E_OVERLAPPING_MERGE", "XLV_E_FILE_EXISTS", "XLV_E_FILE_WRITE", "XLV_E_HEADER_NOT_FOUND", "XLV_E_SCHEMA_INVALID", "XLV_E_ASYNC_SCHEMA", "XLV_E_INVALID_ROWS", "XLV_E_JSON_INVALID", "XLV_E_CSV_MALFORMED", "XLV_E_NOT_SUPPORTED", "XLV_E_USAGE", "XLV_E_NOT_INSTALLED", "XLV_E_INTERNAL", "XLV_E_PATH_NOT_ALLOWED"];
 /**
  * Every warning code xlvane can report. Warnings never stop reading; they describe something
  * in the file that the caller may want to know about. Each one is described in docs/errors.md.
@@ -1202,6 +1207,250 @@ interface ResolvedImage {
   readonly description: string | null;
   readonly hyperlink: string | null;
 }
+/** Markers of a resolved anchor (see {@link ResolvedImage}). */
+type ResolvedAnchor = Pick<ResolvedImage, "from" | "to" | "ext" | "editAs">;
+/**
+ * Chart types `NewSheet.addChart` writes. `column` and `bar` are both a `barChart` (vertical and
+ * horizontal bars), the others are `lineChart`, `pieChart`, `scatterChart` and `areaChart`
+ * (docs/facts/charts.md CH-10).
+ *
+ * @example
+ * ```ts
+ * import type { ChartType } from 'xlvane';
+ *
+ * const type: ChartType = 'column';
+ * ```
+ */
+type ChartType = "column" | "bar" | "line" | "pie" | "scatter" | "area";
+/**
+ * Where a chart's legend is shown (ST_LegendPos `r`, `b`, `t`, `l`; CH-27).
+ *
+ * @example
+ * ```ts
+ * import type { ChartLegendPosition } from 'xlvane';
+ *
+ * const legend: ChartLegendPosition = 'bottom';
+ * ```
+ */
+type ChartLegendPosition = "right" | "bottom" | "top" | "left";
+/**
+ * One series of a chart for `NewSheet.addChart`:
+ * - `values`: a sheet-qualified range of one row or one column, such as `"'Sales'!B2:B13"` (for
+ *   scatter charts the y values);
+ * - `categories`: the same for the category labels (for scatter charts the x values);
+ * - `name`: the series name, either literal text or a reference to one cell such as `"Sales!B1"`;
+ *   text that reads as a sheet-qualified cell reference is always taken as a reference;
+ * - `color`: the colour as six hex digits `RRGGBB` (a leading `#` is accepted). Without it the
+ *   series takes the next colour of the default palette (CH-35). Pie charts colour each slice
+ *   from the palette and do not take `color`.
+ *
+ * @example
+ * ```ts
+ * import type { ChartSeriesInput } from 'xlvane';
+ *
+ * const series: ChartSeriesInput = { name: 'Sales!B1', categories: 'Sales!A2:A13', values: 'Sales!B2:B13', color: '2E75B6' };
+ * ```
+ */
+interface ChartSeriesInput {
+  readonly values: string;
+  readonly categories?: string;
+  readonly name?: string;
+  readonly color?: string;
+}
+/**
+ * Options of one chart axis: its title, and for the value axis (`y`) the fixed minimum and
+ * maximum of its scale (CH-26).
+ *
+ * @example
+ * ```ts
+ * import type { ChartAxisInput } from 'xlvane';
+ *
+ * const y: ChartAxisInput = { title: 'Revenue', min: 0, max: 100 };
+ * ```
+ */
+interface ChartAxisInput {
+  readonly title?: string;
+  readonly min?: number;
+  readonly max?: number;
+}
+/**
+ * A chart for `NewSheet.addChart`. `anchor` places it like a picture (see `ImageAnchorInput`).
+ * `stacked` (column, bar, line and area only) stacks the series, or with `'percent'` stacks them
+ * to 100 %. `legend` defaults to `'right'`; `false` leaves the legend out. `axes.x` is the
+ * category axis (the x values of a scatter chart; drawn vertically for `bar`), `axes.y` the
+ * value axis; pie charts have no axes. Options left out (`undefined`) take their defaults;
+ * `null` is refused. A chart has 1 to 255 series (a limit of xlvane), each an object (no holes
+ * in the array), a pie chart exactly one with at most 1 000 values; titles and literal series
+ * names are 1 to 255 characters without control characters. `writeWorkbook` writes the cached
+ * values of at most 4 000 000 cells, with at most 8 388 608 characters of cached text once
+ * escaped, for all charts of a workbook together (limits of xlvane; `writeWorkbookStream` writes
+ * no caches).
+ * The anchor is copied when the chart is added. A sheet name that reads as a cell reference is
+ * given in quotes (`'S1'!B2:B5`); without quotes it must be exactly the name of a sheet.
+ *
+ * @example
+ * ```ts
+ * import type { ChartInput } from 'xlvane';
+ *
+ * const chart: ChartInput = {
+ *   type: 'line',
+ *   anchor: 'E2:L18',
+ *   title: 'Monthly sales',
+ *   series: [{ name: 'Sales!B1', categories: 'Sales!A2:A13', values: 'Sales!B2:B13' }],
+ *   axes: { y: { title: 'EUR', min: 0 } },
+ * };
+ * ```
+ */
+interface ChartInput {
+  readonly type: ChartType;
+  readonly anchor: ImageAnchorInput;
+  readonly series: readonly ChartSeriesInput[];
+  readonly title?: string;
+  readonly legend?: ChartLegendPosition | false;
+  readonly stacked?: boolean | "percent";
+  readonly axes?: {
+    readonly x?: {
+      readonly title?: string;
+    };
+    readonly y?: ChartAxisInput;
+  };
+  /** Name of the chart object, by default "Chart N". */
+  readonly name?: string;
+  /** Alternative text of the chart object. */
+  readonly description?: string;
+}
+/**
+ * The type of a chart group as read: a {@link ChartType} (`column` or `bar` from `barDir`), or
+ * `other:` and the element name for chart types xlvane does not model, such as
+ * `'other:radarChart'` or `'other:bar3DChart'`.
+ *
+ * @example
+ * ```ts
+ * import type { ChartKind } from 'xlvane';
+ *
+ * const kinds: ChartKind[] = ['column', 'line', 'other:doughnutChart'];
+ * ```
+ */
+type ChartKind = ChartType | `other:${string}`;
+/**
+ * A title or series name as read: literal `text`, or a `ref`erence to a cell (the formula text as
+ * stored, for example `Sheet1!$B$1`; never evaluated).
+ *
+ * @example
+ * ```ts
+ * import type { ChartText } from 'xlvane';
+ *
+ * const show = (t: ChartText | null): string => (t === null ? '(none)' : 'text' in t ? t.text : `=${t.ref}`);
+ * ```
+ */
+type ChartText = {
+  readonly text: string;
+} | {
+  readonly ref: string;
+};
+/**
+ * An axis of a chart as read: its title and the fixed `min` and `max` of its scale, or `null`
+ * where the file sets none.
+ *
+ * @example
+ * ```ts
+ * import type { ChartAxis } from 'xlvane';
+ *
+ * const axis: ChartAxis = { title: { text: 'EUR' }, min: 0, max: null };
+ * ```
+ */
+interface ChartAxis {
+  readonly title: ChartText | null;
+  readonly min: number | null;
+  readonly max: number | null;
+}
+/**
+ * A series of a chart as read. `categories` and `values` are the reference texts as stored (the
+ * x and y values of a scatter series), or `null` when the series has none or holds literal data.
+ *
+ * @example
+ * ```ts
+ * import { readWorkbook, type ChartSeries } from 'xlvane';
+ *
+ * declare const bytes: Uint8Array;
+ * const series: readonly ChartSeries[] = readWorkbook(bytes).getSheet('Report').charts[0]?.series ?? [];
+ * for (const s of series) console.log(s.type, s.values);
+ * ```
+ */
+interface ChartSeries {
+  readonly type: ChartKind;
+  readonly name: ChartText | null;
+  readonly categories: string | null;
+  readonly values: string | null;
+}
+/**
+ * A chart on a worksheet (a `graphicFrame` of the sheet's drawing and its chart part, CH-02,
+ * CH-04). `types` lists the chart groups of the plot area in order; a combination chart has
+ * several, for example `['column', 'line']`. `stacked` comes from the first group that has a
+ * grouping (`true` for `stacked`, `'percent'` for `percentStacked`, `false` otherwise; `null`
+ * for pie, scatter and unmodelled types). `title` is `null` without a title and for an automatic
+ * title whose text the file does not hold. `legend` is `null` without a legend. `axes.x` is the
+ * category axis (the x axis of a scatter chart) and `axes.y` the value axis of the first group
+ * with axes. Charts on chart sheets are not read.
+ *
+ * @example
+ * ```ts
+ * import { readWorkbook, type SheetChart } from 'xlvane';
+ *
+ * declare const bytes: Uint8Array;
+ * const charts: readonly SheetChart[] = readWorkbook(bytes).getSheet('Report').charts;
+ * for (const c of charts) console.log(c.types.join('+'), c.series.map((s) => s.values));
+ * ```
+ */
+interface SheetChart {
+  readonly name: string;
+  readonly description: string | null;
+  readonly anchor: ImageAnchor;
+  readonly types: readonly ChartKind[];
+  readonly stacked: boolean | "percent" | null;
+  readonly title: ChartText | null;
+  readonly legend: ChartLegendPosition | "topRight" | null;
+  readonly axes: {
+    readonly x: ChartAxis | null;
+    readonly y: ChartAxis | null;
+  };
+  readonly series: readonly ChartSeries[];
+}
+/** A validated reference: the sheet as written by the caller (resolved at write time) and the cells. */
+interface ChartRef {
+  readonly sheet: string;
+  readonly range: CellRange;
+  /**
+   * `true` when the sheet name was given without quotes although it reads as a cell or R1C1
+   * reference (such as `S1!$A$1`); it must then be exactly the name of a sheet of the workbook.
+   */
+  readonly unquoted?: boolean;
+}
+/** A validated series. */
+interface NormalizedSeries {
+  readonly name: {
+    readonly text: string;
+  } | {
+    readonly ref: ChartRef;
+  } | null;
+  readonly values: ChartRef;
+  readonly categories: ChartRef | null;
+  readonly color: string | null;
+}
+/** A validated chart, without its anchor. */
+interface NormalizedChart {
+  readonly type: ChartType;
+  readonly title: string | null;
+  readonly legend: ChartLegendPosition | null;
+  readonly stacked: boolean | "percent";
+  readonly series: readonly NormalizedSeries[];
+  readonly xTitle: string | null;
+  readonly yTitle: string | null;
+  readonly min: number | null;
+  readonly max: number | null;
+  readonly name: string | null;
+  readonly description: string | null;
+}
 /**
  * A colour. A string is an RGB colour as 6 hex digits (`"FF0000"`) or ARGB as 8 hex digits
  * (`"80FF0000"`); colours read from files are always 8 upper-case digits. Files can also refer
@@ -2613,8 +2862,19 @@ interface Sheet {
   readonly hyperlinks: readonly Hyperlink[];
   /** Notes (comments) of the sheet, in file order (see `Note`). */
   readonly notes: readonly Note[];
-  /** Pictures of the sheet's drawing, in file order (see `SheetImage`); charts and shapes are not read. */
+  /**
+   * Pictures of the sheet's drawing, in file order (see `SheetImage`); shapes are not read. A
+   * drawing part shared with an earlier sheet is read for that sheet only
+   * (`XLV_W_SHEET_PART_SHARED`).
+   */
   readonly images: readonly SheetImage[];
+  /**
+   * Charts of the sheet's drawing, in file order (see `SheetChart`): types, series references,
+   * titles, legend and axes. References are never evaluated. Charts on chart sheets are not read,
+   * nor charts of a drawing part shared with an earlier sheet. Chart groups and series count
+   * against `limits.maxCells` after the cells (see `ReadLimits.maxCells`).
+   */
+  readonly charts: readonly SheetChart[];
   /** The background image of the sheet (`picture` element), or `null`. */
   readonly backgroundImage: WorkbookImage | null;
   /** Colour of the sheet tab (`sheetPr/tabColor`), or `null`. */
@@ -3015,6 +3275,21 @@ interface InspectSheet {
     readonly cell: string | null;
     readonly format: "png" | "jpeg" | "gif" | null;
   }[];
+  /** Number of charts of the sheet's drawing (`Sheet.charts`). */
+  readonly chartCount: number;
+  /**
+   * Up to ten charts: the cell of the top-left corner (or `null` for an absolute position), the
+   * first ten chart group types (see `ChartKind`) and whether the chart has more
+   * (`typesTruncated`), the title (`{ text }` or `{ ref }`, cut to 100 characters and `…`, or
+   * `null`) and the number of series.
+   */
+  readonly charts: readonly {
+    readonly cell: string | null;
+    readonly types: readonly ChartKind[];
+    readonly typesTruncated: boolean;
+    readonly title: ChartText | null;
+    readonly seriesCount: number;
+  }[];
   /** `true` when the sheet is protected (`Sheet.protection.sheet`). */
   readonly protected: boolean;
   /** The print area (`Sheet.printArea`), or `null`. */
@@ -3152,6 +3427,10 @@ interface WriteSheetData {
   readonly images?: readonly ResolvedImage[];
   /** Background image (index into `WritePackageInput.images`), or `null`. */
   readonly background?: number | null;
+  /** Charts with resolved anchors (D-K01). */
+  readonly charts?: readonly (ResolvedAnchor & {
+    readonly chart: NormalizedChart;
+  })[];
 }
 /** Height, visibility and outline of a row. */
 interface RowFormat {
@@ -3579,6 +3858,11 @@ declare class NewSheet {
   readonly imageList: StoredImage[];
   /** @internal Background image (index of `NewWorkbook.addImage`), or `null`. */
   backgroundImage: number | null;
+  /** @internal Charts in the order they were added (D-K01). */
+  readonly chartList: {
+    readonly anchor: ImageAnchorInput;
+    readonly chart: NormalizedChart;
+  }[];
   /** @internal Data validations in the order they were added (SR-01). */
   readonly validationList: DataValidation[];
   /** @internal Conditional formats in the order they were added (SR-07). */
@@ -3918,7 +4202,8 @@ declare class NewSheet {
    * two corners `{ from, to }` (with `editAs`), or a corner and a size in pixels
    * (`{ from, size }`), see `ImageAnchorInput`. Fractional positions and pixel sizes use the
    * sheet's column widths and row heights at the time the workbook is written, at 96 pixels per
-   * inch (TD-33).
+   * inch (TD-33). The anchor is copied, so changing its object afterwards does not move the
+   * picture.
    *
    * @example
    * ```ts
@@ -3931,6 +4216,29 @@ declare class NewSheet {
    * ```
    */
   addImage(image: number, anchor: ImageAnchorInput, options?: ImageOptions): this;
+  /**
+   * Places a chart on the sheet: a column, bar, line, pie, scatter or area chart over ranges of
+   * this or another sheet of the workbook (see `ChartInput`). `anchor` places it like a picture.
+   * Each series gets an explicit colour from the default palette unless it has `color`, and the
+   * file holds the current cell values of the ranges as caches, as Excel writes them
+   * (docs/facts/charts.md CH-19, CH-21). The sheets named in the ranges must exist when the
+   * workbook is written. Charts are drawn above the sheet's pictures. The caches of all charts
+   * of a workbook cover at most 4 000 000 cells and hold at most 8 388 608 characters of text as
+   * written, after escaping (limits of xlvane, checked when the workbook is written;
+   * `writeWorkbookStream` writes no caches). The chart options and the anchor are copied, so changing the objects afterwards
+   * does not change the chart. Throws `XLV_E_INVALID_CHART`.
+   *
+   * @example
+   * ```ts
+   * import { createWorkbook } from 'xlvane';
+   *
+   * const workbook = createWorkbook();
+   * const sales = workbook.addSheet('Sales').set('A1', 'Month').set('B1', 'Sales');
+   * ['Jan', 'Feb', 'Mar'].forEach((m, i) => sales.set(`A${String(i + 2)}`, m).set(`B${String(i + 2)}`, (i + 1) * 10));
+   * sales.addChart({ type: 'column', anchor: 'D2:K16', title: 'Sales', series: [{ name: 'Sales!B1', categories: 'Sales!A2:A4', values: 'Sales!B2:B4' }] });
+   * ```
+   */
+  addChart(chart: ChartInput): this;
   /**
    * Sets the picture shown behind the cells of the sheet (`picture` element, Part 1 §18.3.1.67),
    * or removes it with `null`. `image` is the number `NewWorkbook.addImage` returned.
@@ -4875,6 +5183,13 @@ interface StreamSheetSpec {
   })[];
   /** Background image (a position in `WriteWorkbookStreamOptions.images`), as for `NewSheet.background`. */
   readonly background?: number;
+  /**
+   * Charts, as for `NewSheet.addChart`. The streaming writer does not keep cell values, so the
+   * chart parts hold the references without caches; LibreOffice 24.2.7.2 draws such charts from
+   * the cells (docs/facts/charts.md CH-20). PROVISIONAL: whether Excel shows a chart without
+   * caches is not verified (R6-4). Fractional row positions assume the default row height.
+   */
+  readonly charts?: readonly ChartInput[];
   /** The rows, from row 1. Any iterable or async iterable (arrays, generators, streams of rows). */
   readonly rows: Iterable<StreamRowInput> | AsyncIterable<StreamRowInput>;
 }
@@ -4991,4 +5306,4 @@ interface WriteTableStreamOptions {
  * ```
  */
 declare function writeTableStream(rows: Iterable<object> | AsyncIterable<object>, options: WriteTableStreamOptions): ReadableStream<Uint8Array>;
-export { InspectOptions as $, verifyPassword as $n, DataValidationOperator as $t, toJSON as A, Hyperlink as An, Workbook as At, FormulaResult as B, PrintErrors as Bn, CfValue as Bt, TableRow as C, ImageAnchorInput as Cn, Sheet as Ct, fromJSON as D, SheetImage as Dn, SheetState as Dt, WriteTableOptions as E, ImagePositionInput as En, SheetProperties as Et, CellInput as F, PageOrder as Fn, TableDefinitionColumn as Ft, SheetPropertiesOptions as G, SheetProtectionOptions as Gn, ConditionalFormatRule as Gt, NewSheet as H, PrintTitles as Hn, CfValueType as Ht, ColumnOptions as I, PageOrientation as In, TableInput as It, WriteWorkbookOptions as J, HashPasswordOptions as Jn, DataBarAxisPosition as Jt, SheetViewOptions as K, WorkbookProtection as Kn, ConditionalFormatRuleInput as Kt, CreateWorkbookOptions as L, PageSetup as Ln, TableStyleOptions as Lt, StandardSchemaV1 as M, HeaderFooter as Mn, WorkbookView as Mt, AddSheetOptions as N, PageBreaks as Nn, TableColumnInput as Nt, readTable as O, WorkbookImage as On, SheetView as Ot, CalculationOptions as P, PageMargins as Pn, TableDefinition as Pt, InspectDefinedName as Q, legacyPasswordHash as Qn, DataValidationImeMode as Qt, ERROR_VALUES as R, PageSetupOptions as Rn, TotalsRowFunction as Rt, TableResult as S, ImageAnchor as Sn, RowInfo as St, ToJSONOptions as T, ImageOptions as Tn, SheetLayout as Tt, NewWorkbook as U, SheetProtection as Un, ConditionalFormat as Ut, FreezeOptions as V, PrintOptions as Vn, CfValueInput as Vt, RowOptions as W, SheetProtectionFlags as Wn, ConditionalFormatOperator as Wt, writeWorkbook as X, PasswordVerifier as Xn, DataValidation as Xt, createWorkbook as Y, PasswordHash as Yn, DataBarDirection as Yt, InspectColumn as Z, hashPassword as Zn, DataValidationErrorStyle as Zt, JsonTable as _, ReadingOrder as _n, DefinedNameOptions as _r, DateSystem as _t, WriteWorkbookStreamOptions as a, BorderEdge as an, XlvDetails as ar, ReadOptions as at, TableColumnSpec as b, VerticalAlignment as bn, FrozenPanes as bt, OpenWorkbookStreamOptions as c, CellStyle as cn, XlvErrorInit as cr, NoteBox as ct, StreamRow as d, FontScheme as dn, XlvWarning as dr, NoteMargins as dt, DataValidationRule as en, ShaAlgorithm as er, InspectReport as et, StreamSheetInfo as f, FontStyle as fn, XlvWarningCode as fr, Cell as ft, readTableStream as g, ProtectionStyle as gn, DefinedName as gr, Conformance as gt, openWorkbookStream as h, PatternType as hn, ReadLimits as hr, ColumnInfo as ht, WriteTableStreamOptions as i, AlignmentStyle as in, XlvDetailValue as ir, inspect as it, writeTable as j, HyperlinkTarget as jn, WorkbookFormat as jt, readTableAsync as k, imageFormat as kn, SplitPanes as kt, ReadTableStreamOptions as l, Color as ln, XlvErrorJSON as lr, NoteBoxInput as lt, WorkbookStream as m, HorizontalAlignment as mn, DEFAULT_READ_LIMITS as mr, CellValue as mt, StreamRowInput as n, IconSetType as nn, ERROR_CODES as nr, InspectTypeCounts as nt, writeTableStream as o, BorderLineStyle as on, XlvError as or, readWorkbook as ot, TableStreamItem as p, GradientFill as pn, isXlvError as pr, CellType as pt, WorkbookViewOptions as q, WorkbookProtectionOptions as qn, ConditionalFormatType as qt, StreamSheetSpec as r, TimePeriod as rn, WARNING_CODES as rr, InspectValue as rt, writeWorkbookStream as s, BorderStyle as sn, XlvErrorCode as sr, Note as st, StreamDefinedName as t, DataValidationType as tn, WorkbookProperties as tr, InspectSheet as tt, STREAM_LIMIT_DEFAULTS as u, FillStyle as un, XlvLocation as ur, NoteInput as ut, ReadTableOptions as v, UnderlineStyle as vn, Formula as vt, TableValue as w, ImageFormat as wn, SheetKind as wt, TableIssue as x, AnchorMarker as xn, RichTextRun as xt, TableColumn as y, VerticalAlignRun as yn, FormulaKind as yt, ErrorValue as z, PrintCellComments as zn, CfIcon as zt };
+export { InspectOptions as $, SheetProtection as $n, DataValidationOperator as $t, toJSON as A, SheetChart as An, Workbook as At, FormulaResult as B, Hyperlink as Bn, CfValue as Bt, TableRow as C, ChartInput as Cn, isXlvError as Cr, Sheet as Ct, fromJSON as D, ChartSeriesInput as Dn, DefinedNameOptions as Dr, SheetState as Dt, WriteTableOptions as E, ChartSeries as En, DefinedName as Er, SheetProperties as Et, CellInput as F, ImageOptions as Fn, TableDefinitionColumn as Ft, SheetPropertiesOptions as G, PageOrder as Gn, ConditionalFormatRule as Gt, NewSheet as H, HeaderFooter as Hn, CfValueType as Ht, ColumnOptions as I, ImagePositionInput as In, TableInput as It, WriteWorkbookOptions as J, PageSetupOptions as Jn, DataBarAxisPosition as Jt, SheetViewOptions as K, PageOrientation as Kn, ConditionalFormatRuleInput as Kt, CreateWorkbookOptions as L, SheetImage as Ln, TableStyleOptions as Lt, StandardSchemaV1 as M, ImageAnchor as Mn, WorkbookView as Mt, AddSheetOptions as N, ImageAnchorInput as Nn, TableColumnInput as Nt, readTable as O, ChartText as On, SheetView as Ot, CalculationOptions as P, ImageFormat as Pn, TableDefinition as Pt, InspectDefinedName as Q, PrintTitles as Qn, DataValidationImeMode as Qt, ERROR_VALUES as R, WorkbookImage as Rn, TotalsRowFunction as Rt, TableResult as S, ChartAxisInput as Sn, XlvWarningCode as Sr, RowInfo as St, ToJSONOptions as T, ChartLegendPosition as Tn, ReadLimits as Tr, SheetLayout as Tt, NewWorkbook as U, PageBreaks as Un, ConditionalFormat as Ut, FreezeOptions as V, HyperlinkTarget as Vn, CfValueInput as Vt, RowOptions as W, PageMargins as Wn, ConditionalFormatOperator as Wt, writeWorkbook as X, PrintErrors as Xn, DataValidation as Xt, createWorkbook as Y, PrintCellComments as Yn, DataBarDirection as Yt, InspectColumn as Z, PrintOptions as Zn, DataValidationErrorStyle as Zt, JsonTable as _, ReadingOrder as _n, XlvErrorCode as _r, DateSystem as _t, WriteWorkbookStreamOptions as a, BorderEdge as an, PasswordHash as ar, ReadOptions as at, TableColumnSpec as b, VerticalAlignment as bn, XlvLocation as br, FrozenPanes as bt, OpenWorkbookStreamOptions as c, CellStyle as cn, legacyPasswordHash as cr, NoteBox as ct, StreamRow as d, FontScheme as dn, WorkbookProperties as dr, NoteMargins as dt, DataValidationRule as en, SheetProtectionFlags as er, InspectReport as et, StreamSheetInfo as f, FontStyle as fn, ERROR_CODES as fr, Cell as ft, readTableStream as g, ProtectionStyle as gn, XlvError as gr, Conformance as gt, openWorkbookStream as h, PatternType as hn, XlvDetails as hr, ColumnInfo as ht, WriteTableStreamOptions as i, AlignmentStyle as in, HashPasswordOptions as ir, inspect as it, writeTable as j, AnchorMarker as jn, WorkbookFormat as jt, readTableAsync as k, ChartType as kn, SplitPanes as kt, ReadTableStreamOptions as l, Color as ln, verifyPassword as lr, NoteBoxInput as lt, WorkbookStream as m, HorizontalAlignment as mn, XlvDetailValue as mr, CellValue as mt, StreamRowInput as n, IconSetType as nn, WorkbookProtection as nr, InspectTypeCounts as nt, writeTableStream as o, BorderLineStyle as on, PasswordVerifier as or, readWorkbook as ot, TableStreamItem as p, GradientFill as pn, WARNING_CODES as pr, CellType as pt, WorkbookViewOptions as q, PageSetup as qn, ConditionalFormatType as qt, StreamSheetSpec as r, TimePeriod as rn, WorkbookProtectionOptions as rr, InspectValue as rt, writeWorkbookStream as s, BorderStyle as sn, hashPassword as sr, Note as st, StreamDefinedName as t, DataValidationType as tn, SheetProtectionOptions as tr, InspectSheet as tt, STREAM_LIMIT_DEFAULTS as u, FillStyle as un, ShaAlgorithm as ur, NoteInput as ut, ReadTableOptions as v, UnderlineStyle as vn, XlvErrorInit as vr, Formula as vt, TableValue as w, ChartKind as wn, DEFAULT_READ_LIMITS as wr, SheetKind as wt, TableIssue as x, ChartAxis as xn, XlvWarning as xr, RichTextRun as xt, TableColumn as y, VerticalAlignRun as yn, XlvErrorJSON as yr, FormulaKind as yt, ErrorValue as z, imageFormat as zn, CfIcon as zt };

package/docs/cli-json/inspect.schema.json

@@ -359,6 +359,80 @@
                       "additionalProperties": false
                     }
                   },
+                  "chartCount": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "charts": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "cell": {
+                          "anyOf": [
+                            {
+                              "type": "null"
+                            },
+                            {
+                              "type": "string"
+                            }
+                          ]
+                        },
+                        "types": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        },
+                        "typesTruncated": {
+                          "type": "boolean"
+                        },
+                        "title": {
+                          "anyOf": [
+                            {
+                              "type": "null"
+                            },
+                            {
+                              "type": "object",
+                              "properties": {
+                                "text": {
+                                  "type": "string"
+                                }
+                              },
+                              "required": [
+                                "text"
+                              ],
+                              "additionalProperties": false
+                            },
+                            {
+                              "type": "object",
+                              "properties": {
+                                "ref": {
+                                  "type": "string"
+                                }
+                              },
+                              "required": [
+                                "ref"
+                              ],
+                              "additionalProperties": false
+                            }
+                          ]
+                        },
+                        "seriesCount": {
+                          "type": "integer",
+                          "minimum": 0
+                        }
+                      },
+                      "required": [
+                        "cell",
+                        "types",
+                        "typesTruncated",
+                        "title",
+                        "seriesCount"
+                      ],
+                      "additionalProperties": false
+                    }
+                  },
                   "protected": {
                     "type": "boolean"
                   },
@@ -485,6 +559,8 @@
                   "noteCount",
                   "imageCount",
                   "images",
+                  "chartCount",
+                  "charts",
                   "notes",
                   "protected",
                   "printArea",