@office-kit/xlsx 0.8.0

package/dist/user-shapes-DfmCGKB0.mjs

@@ -0,0 +1,252 @@
+//#region src/chart/chart.ts
+function makeBarChart(opts) {
+	return {
+		kind: "bar",
+		barDir: opts.barDir ?? "col",
+		grouping: opts.grouping ?? "clustered",
+		series: opts.series ?? [],
+		axIds: opts.axIds ?? [1, 2],
+		...opts.varyColors !== void 0 ? { varyColors: opts.varyColors } : {},
+		...opts.gapWidth !== void 0 ? { gapWidth: opts.gapWidth } : {},
+		...opts.overlap !== void 0 ? { overlap: opts.overlap } : {}
+	};
+}
+function makeBarSeries(opts) {
+	return {
+		idx: opts.idx,
+		order: opts.order ?? opts.idx,
+		val: opts.val,
+		...opts.cat ? { cat: opts.cat } : {},
+		...opts.tx ? { tx: opts.tx } : {}
+	};
+}
+function makeChartSpace(opts) {
+	const title = typeof opts.title === "string" ? { text: opts.title } : opts.title;
+	return {
+		plotArea: opts.plotArea,
+		...title !== void 0 ? { title } : {},
+		...opts.legend ? { legend: opts.legend } : {},
+		...opts.style !== void 0 ? { style: opts.style } : {},
+		...opts.view3D ? { view3D: opts.view3D } : {},
+		...opts.floor ? { floor: opts.floor } : {},
+		...opts.sideWall ? { sideWall: opts.sideWall } : {},
+		...opts.backWall ? { backWall: opts.backWall } : {},
+		...opts.plotVisOnly !== void 0 ? { plotVisOnly: opts.plotVisOnly } : {},
+		...opts.dispBlanksAs !== void 0 ? { dispBlanksAs: opts.dispBlanksAs } : {},
+		...opts.spPr ? { spPr: opts.spPr } : {},
+		...opts.txPr ? { txPr: opts.txPr } : {}
+	};
+}
+function makeLineChart(opts) {
+	return {
+		kind: "line",
+		grouping: opts.grouping ?? "standard",
+		series: opts.series ?? [],
+		axIds: opts.axIds ?? [1, 2],
+		...opts.varyColors !== void 0 ? { varyColors: opts.varyColors } : {},
+		...opts.smooth !== void 0 ? { smooth: opts.smooth } : {}
+	};
+}
+function makeAreaChart(opts) {
+	return {
+		kind: "area",
+		grouping: opts.grouping ?? "standard",
+		series: opts.series ?? [],
+		axIds: opts.axIds ?? [1, 2],
+		...opts.varyColors !== void 0 ? { varyColors: opts.varyColors } : {}
+	};
+}
+function makePieChart(opts) {
+	return {
+		kind: "pie",
+		series: opts.series ?? [],
+		...opts.varyColors !== void 0 ? { varyColors: opts.varyColors } : {}
+	};
+}
+function makeDoughnutChart(opts) {
+	return {
+		kind: "doughnut",
+		series: opts.series ?? [],
+		...opts.varyColors !== void 0 ? { varyColors: opts.varyColors } : {},
+		...opts.holeSize !== void 0 ? { holeSize: opts.holeSize } : {},
+		...opts.firstSliceAng !== void 0 ? { firstSliceAng: opts.firstSliceAng } : {}
+	};
+}
+function makeScatterChart(opts) {
+	return {
+		kind: "scatter",
+		scatterStyle: opts.scatterStyle ?? "lineMarker",
+		series: opts.series ?? [],
+		axIds: opts.axIds ?? [1, 2],
+		...opts.varyColors !== void 0 ? { varyColors: opts.varyColors } : {}
+	};
+}
+function makeScatterSeries(opts) {
+	return {
+		idx: opts.idx,
+		order: opts.order ?? opts.idx,
+		yVal: opts.yVal,
+		...opts.tx ? { tx: opts.tx } : {},
+		...opts.xVal ? { xVal: opts.xVal } : {},
+		...opts.smooth !== void 0 ? { smooth: opts.smooth } : {},
+		...opts.marker ? { marker: opts.marker } : {}
+	};
+}
+function makeRadarChart(opts) {
+	return {
+		kind: "radar",
+		radarStyle: opts.radarStyle ?? "standard",
+		series: opts.series ?? [],
+		axIds: opts.axIds ?? [1, 2],
+		...opts.varyColors !== void 0 ? { varyColors: opts.varyColors } : {}
+	};
+}
+function makeBubbleChart(opts) {
+	return {
+		kind: "bubble",
+		series: opts.series ?? [],
+		axIds: opts.axIds ?? [1, 2],
+		...opts.varyColors !== void 0 ? { varyColors: opts.varyColors } : {},
+		...opts.bubble3D !== void 0 ? { bubble3D: opts.bubble3D } : {},
+		...opts.bubbleScale !== void 0 ? { bubbleScale: opts.bubbleScale } : {},
+		...opts.showNegBubbles !== void 0 ? { showNegBubbles: opts.showNegBubbles } : {},
+		...opts.sizeRepresents !== void 0 ? { sizeRepresents: opts.sizeRepresents } : {}
+	};
+}
+function makeBubbleSeries(opts) {
+	return {
+		idx: opts.idx,
+		order: opts.order ?? opts.idx,
+		yVal: opts.yVal,
+		bubbleSize: opts.bubbleSize,
+		...opts.tx ? { tx: opts.tx } : {},
+		...opts.xVal ? { xVal: opts.xVal } : {},
+		...opts.bubble3D !== void 0 ? { bubble3D: opts.bubble3D } : {}
+	};
+}
+function makeStockChart(opts) {
+	return {
+		kind: "stock",
+		series: opts.series ?? [],
+		axIds: opts.axIds ?? [1, 2],
+		...opts.hiLowLines !== void 0 ? { hiLowLines: opts.hiLowLines } : {},
+		...opts.upDownBars !== void 0 ? { upDownBars: opts.upDownBars } : {}
+	};
+}
+function makeSurfaceChart(opts) {
+	return {
+		kind: "surface",
+		series: opts.series ?? [],
+		axIds: opts.axIds ?? [
+			1,
+			2,
+			3
+		],
+		...opts.wireframe !== void 0 ? { wireframe: opts.wireframe } : {}
+	};
+}
+function makeOfPieChart(opts) {
+	return {
+		kind: "ofPie",
+		ofPieType: opts.ofPieType ?? "pie",
+		series: opts.series ?? [],
+		...opts.varyColors !== void 0 ? { varyColors: opts.varyColors } : {},
+		...opts.gapWidth !== void 0 ? { gapWidth: opts.gapWidth } : {},
+		...opts.splitType !== void 0 ? { splitType: opts.splitType } : {},
+		...opts.splitPos !== void 0 ? { splitPos: opts.splitPos } : {},
+		...opts.custSplit ? { custSplit: opts.custSplit } : {},
+		...opts.secondPieSize !== void 0 ? { secondPieSize: opts.secondPieSize } : {}
+	};
+}
+function makeBar3DChart(opts) {
+	return {
+		kind: "bar3D",
+		barDir: opts.barDir ?? "col",
+		grouping: opts.grouping ?? "clustered",
+		series: opts.series ?? [],
+		axIds: opts.axIds ?? [
+			1,
+			2,
+			3
+		],
+		...opts.varyColors !== void 0 ? { varyColors: opts.varyColors } : {},
+		...opts.gapWidth !== void 0 ? { gapWidth: opts.gapWidth } : {},
+		...opts.gapDepth !== void 0 ? { gapDepth: opts.gapDepth } : {},
+		...opts.shape !== void 0 ? { shape: opts.shape } : {}
+	};
+}
+function makeLine3DChart(opts) {
+	return {
+		kind: "line3D",
+		grouping: opts.grouping ?? "standard",
+		series: opts.series ?? [],
+		axIds: opts.axIds ?? [
+			1,
+			2,
+			3
+		],
+		...opts.varyColors !== void 0 ? { varyColors: opts.varyColors } : {},
+		...opts.gapDepth !== void 0 ? { gapDepth: opts.gapDepth } : {}
+	};
+}
+function makePie3DChart(opts) {
+	return {
+		kind: "pie3D",
+		series: opts.series ?? [],
+		...opts.varyColors !== void 0 ? { varyColors: opts.varyColors } : {}
+	};
+}
+function makeArea3DChart(opts) {
+	return {
+		kind: "area3D",
+		grouping: opts.grouping ?? "standard",
+		series: opts.series ?? [],
+		axIds: opts.axIds ?? [
+			1,
+			2,
+			3
+		],
+		...opts.varyColors !== void 0 ? { varyColors: opts.varyColors } : {},
+		...opts.gapDepth !== void 0 ? { gapDepth: opts.gapDepth } : {}
+	};
+}
+function makeSurface3DChart(opts) {
+	return {
+		kind: "surface3D",
+		series: opts.series ?? [],
+		axIds: opts.axIds ?? [
+			1,
+			2,
+			3
+		],
+		...opts.wireframe !== void 0 ? { wireframe: opts.wireframe } : {}
+	};
+}
+//#endregion
+//#region src/chart/user-shapes.ts
+const makeChartDrawing = (shapes = []) => ({ shapes });
+const makeChartShape = (opts) => ({
+	id: opts.id,
+	...opts.name !== void 0 ? { name: opts.name } : {},
+	...opts.descr !== void 0 ? { descr: opts.descr } : {},
+	...opts.hidden !== void 0 ? { hidden: opts.hidden } : {},
+	...opts.txBox !== void 0 ? { txBox: opts.txBox } : {},
+	...opts.spPr ? { spPr: opts.spPr } : {},
+	...opts.txBody ? { txBody: opts.txBody } : {}
+});
+const makeRelSizeAnchor = (from, to, content) => ({
+	kind: "relSize",
+	from,
+	to,
+	content
+});
+const makeAbsSizeAnchor = (from, ext, content) => ({
+	kind: "absSize",
+	from,
+	ext,
+	content
+});
+//#endregion
+export { makeSurface3DChart as C, makeStockChart as S, makePie3DChart as _, makeArea3DChart as a, makeScatterChart as b, makeBarChart as c, makeBubbleSeries as d, makeChartSpace as f, makeOfPieChart as g, makeLineChart as h, makeRelSizeAnchor as i, makeBarSeries as l, makeLine3DChart as m, makeChartDrawing as n, makeAreaChart as o, makeDoughnutChart as p, makeChartShape as r, makeBar3DChart as s, makeAbsSizeAnchor as t, makeBubbleChart as u, makePieChart as v, makeSurfaceChart as w, makeScatterSeries as x, makeRadarChart as y };
+
+//# sourceMappingURL=user-shapes-DfmCGKB0.mjs.map

package/dist/user-shapes-DfmCGKB0.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-shapes-DfmCGKB0.mjs","names":[],"sources":["../src/chart/chart.ts","../src/chart/user-shapes.ts"],"sourcesContent":["import type { ShapeProperties } from '../drawing/dml/shape-properties';\nimport type { TextBody } from '../drawing/dml/text';\nimport type { ChartDrawing } from './user-shapes';\n\n// ChartML data model.\n//\n// **Stage 1**: BarChart end-to-end. The full 17 SpreadsheetML chart kinds + 8\n// chartex kinds land across the upcoming iterations; this commit introduces the\n// shared shape so future kinds can plug in without breaking the public surface:\n//\n// ChartSpace\n//     ├─ title?: string\n//     ├─ legend?: { position: ... }\n//     └─ plotArea\n//          ├─ chart: BarChart | LineChart | PieChart | …  (discriminated union)\n//          ├─ catAx?: CategoryAxis  (or Date / Series axis)\n//          └─ valAx?: ValueAxis\n//\n// References to worksheet ranges (`Sheet1!$A$1:$A$5`) are kept as strings; the\n// optional `cache` field carries the last-known data so charts can be rendered\n// without reading the source data.\n\nexport type LegendPosition = 'r' | 't' | 'l' | 'b' | 'tr';\nexport type GroupingType = 'clustered' | 'stacked' | 'percentStacked' | 'standard';\nexport type BarDirection = 'bar' | 'col';\n\n/** Reference to a worksheet range plus an optional client-side cache of the resolved values. */\nexport interface NumericRef {\n  /** Worksheet-qualified range string, e.g. `Sheet1!$B$1:$B$5`. */\n  ref: string;\n  /** Optional cached numeric values — Excel writes these for offline rendering. */\n  cache?: number[];\n  /** Optional `formatCode` Excel uses when rendering each cached value. */\n  formatCode?: string;\n}\n\nexport interface CategoryRef {\n  ref: string;\n  /** Whether the cache is numeric or string. */\n  cacheKind?: 'num' | 'str';\n  /** String values (when `cacheKind === 'str'`) or numeric values. */\n  cache?: ReadonlyArray<string | number>;\n  formatCode?: string;\n}\n\n// ---- Series decorations: data labels, trendlines, error bars --------------\n\n/**\n * Number-format payload for chart axes / data labels (`<c:numFmt formatCode=\"…\"\n * sourceLinked=\"0|1\"/>`).\n *\n * Named `ChartNumberFormat` to avoid colliding with the cell-stylesheet\n * `NumberFormat` exported from `@office-kit/xlsx/styles`, which is a different shape\n * (`{ numFmtId, formatCode }`).\n */\nexport interface ChartNumberFormat {\n  formatCode: string;\n  sourceLinked?: boolean;\n}\n\nexport type DataLabelPosition = 'bestFit' | 'b' | 'ctr' | 'inBase' | 'inEnd' | 'l' | 'outEnd' | 'r' | 't';\n\n/** Per-point data label override. Lives inside `<c:dLbls><c:dLbl idx=\"N\">…</c:dLbl></c:dLbls>`. */\nexport interface DataLabel {\n  idx: number;\n  /** Delete this individual label (suppresses display even if the parent dLbls would show it). */\n  delete?: boolean;\n  /** Inline rich text or a cell reference. Mutually exclusive. */\n  tx?: { kind: 'rich'; body: TextBody } | { kind: 'strRef'; ref: string };\n  numFmt?: ChartNumberFormat;\n  spPr?: ShapeProperties;\n  txPr?: TextBody;\n  dLblPos?: DataLabelPosition;\n  showLegendKey?: boolean;\n  showVal?: boolean;\n  showCatName?: boolean;\n  showSerName?: boolean;\n  showPercent?: boolean;\n  showBubbleSize?: boolean;\n  separator?: string;\n}\n\n/** Series-wide data label settings. `<c:dLbls>` element. */\nexport interface DataLabelList {\n  /** When true, suppress all labels (`<c:delete val=\"1\"/>`). */\n  delete?: boolean;\n  /** Per-point overrides. */\n  dLbl?: DataLabel[];\n  numFmt?: ChartNumberFormat;\n  spPr?: ShapeProperties;\n  txPr?: TextBody;\n  dLblPos?: DataLabelPosition;\n  showLegendKey?: boolean;\n  showVal?: boolean;\n  showCatName?: boolean;\n  showSerName?: boolean;\n  showPercent?: boolean;\n  showBubbleSize?: boolean;\n  separator?: string;\n  showLeaderLines?: boolean;\n}\n\nexport type MarkerSymbol =\n  | 'auto'\n  | 'circle'\n  | 'dash'\n  | 'diamond'\n  | 'dot'\n  | 'none'\n  | 'picture'\n  | 'plus'\n  | 'square'\n  | 'star'\n  | 'triangle'\n  | 'x';\n\n/** Data-point marker on line / scatter / radar series (`<c:marker>` child of `<c:ser>`). */\nexport interface Marker {\n  symbol?: MarkerSymbol;\n  /** Marker size in points (2..72). */\n  size?: number;\n  spPr?: ShapeProperties;\n}\n\n/**\n * Per-point override on a series (`<c:dPt>` child of `<c:ser>`). Lets each bar\n * / slice / data point pick up its own colour, marker, explosion, etc.\n */\nexport interface DataPoint {\n  /** 0-based index of the data point within the series. */\n  idx: number;\n  /** Invert fill when the data point's value is negative (bar / area / bubble). */\n  invertIfNegative?: boolean;\n  /** Per-point marker override (line / scatter / radar). */\n  marker?: Marker;\n  /** 3-D bubble flag (bubble series only). */\n  bubble3D?: boolean;\n  /** Slice explosion in % for pie / doughnut points (0..400). */\n  explosion?: number;\n  /** Per-point shape properties (fill / line colour). */\n  spPr?: ShapeProperties;\n}\n\nexport type TrendlineType = 'exp' | 'linear' | 'log' | 'movingAvg' | 'poly' | 'power';\n\nexport interface Trendline {\n  /** Display name shown in the chart legend (`<c:name>` text). */\n  name?: string;\n  spPr?: ShapeProperties;\n  trendlineType: TrendlineType;\n  /** Polynomial order (2..6) when `trendlineType === 'poly'`. */\n  order?: number;\n  /** Moving-average period when `trendlineType === 'movingAvg'`. */\n  period?: number;\n  /** Forecast forward periods. */\n  forward?: number;\n  /** Forecast backward periods. */\n  backward?: number;\n  /** Y-axis intercept (linear only). */\n  intercept?: number;\n  /** Display R² value on the chart. */\n  dispRSqr?: boolean;\n  /** Display the trendline equation. */\n  dispEq?: boolean;\n}\n\nexport type ErrorBarDirection = 'x' | 'y';\nexport type ErrorBarType = 'both' | 'minus' | 'plus';\nexport type ErrorValType = 'cust' | 'fixedVal' | 'percentage' | 'stdDev' | 'stdErr';\n\nexport interface ErrorBars {\n  /** Direction. Required only on scatter / bubble series; bar / line / area imply `'y'`. */\n  errDir?: ErrorBarDirection;\n  errBarType: ErrorBarType;\n  errValType: ErrorValType;\n  noEndCap?: boolean;\n  /** Numeric magnitude for fixedVal / percentage / stdDev / stdErr. */\n  val?: number;\n  /** Custom plus-side data (NumericRef) — required when `errValType === 'cust'`. */\n  plus?: NumericRef;\n  /** Custom minus-side data (NumericRef) — required when `errValType === 'cust'`. */\n  minus?: NumericRef;\n  spPr?: ShapeProperties;\n}\n\nexport interface BarSeries {\n  /** 0-based slot in the chart (`<c:idx>`). */\n  idx: number;\n  /** Render order (`<c:order>`). Usually equals `idx`. */\n  order: number;\n  /** Series title — either a static string or a cell reference. */\n  tx?: { kind: 'literal'; value: string } | { kind: 'ref'; ref: string };\n  /** Per-series shape properties (fill / line / effects). */\n  spPr?: ShapeProperties;\n  /** Invert fill on negative values (bar / line / area series). */\n  invertIfNegative?: boolean;\n  /**\n   * Slice explosion in % (pie / doughnut series only; 0..400). Bar / line / area writers\n   * ignore the field — leave it unset for those series.\n   */\n  explosion?: number;\n  /** Per-point overrides. Empty / omitted means every point inherits the series defaults. */\n  dPt?: DataPoint[];\n  /** Series-wide data labels. */\n  dLbls?: DataLabelList;\n  /** Trendlines attached to this series. */\n  trendline?: Trendline[];\n  /** Error bars. Bar / line / area / radar default to a single y-direction entry. */\n  errBars?: ErrorBars[];\n  /** Categories. */\n  cat?: CategoryRef;\n  /** Values (always required for a bar series). */\n  val: NumericRef;\n}\n\nexport interface BarChart {\n  kind: 'bar';\n  /** `bar` for horizontal bars, `col` for vertical columns. */\n  barDir: BarDirection;\n  /** Excel default is `clustered`. */\n  grouping: GroupingType;\n  varyColors?: boolean;\n  series: BarSeries[];\n  /** Bar gap width in % of bar width (Excel default 150). */\n  gapWidth?: number;\n  /**\n   * Bar overlap in -100..100 % of bar width. Positive values overlap clustered bars; negative values\n   * space them apart. For stacked / percentStacked grouping, omit and the serializer emits the\n   * standard Excel default of 100 (flush stacking).\n   */\n  overlap?: number;\n  /** Internal axis ids. The category and value axes carry the same numbers. */\n  axIds: [number, number];\n}\n\nexport interface LineSeries extends BarSeries {\n  /** Per-series smoothing toggle. */\n  smooth?: boolean;\n  /** Data-point marker (`<c:marker>` child of `<c:ser>`). */\n  marker?: Marker;\n}\n\nexport interface LineChart {\n  kind: 'line';\n  grouping: GroupingType;\n  varyColors?: boolean;\n  series: LineSeries[];\n  /** Whether to round corners between data points (chart-level default). */\n  smooth?: boolean;\n  axIds: [number, number];\n}\n\nexport interface AreaChart {\n  kind: 'area';\n  grouping: GroupingType;\n  varyColors?: boolean;\n  series: BarSeries[];\n  axIds: [number, number];\n}\n\nexport interface PieChart {\n  kind: 'pie';\n  varyColors?: boolean;\n  /** Pie / Doughnut have a single ring of slices — but Excel allows multiple series; we mirror that. */\n  series: BarSeries[];\n}\n\nexport interface DoughnutChart {\n  kind: 'doughnut';\n  varyColors?: boolean;\n  series: BarSeries[];\n  /** Hole size in % of outer radius (10..90, Excel default 50). */\n  holeSize?: number;\n  /** First-slice rotation angle in degrees. */\n  firstSliceAng?: number;\n}\n\nexport type ScatterStyle = 'line' | 'lineMarker' | 'marker' | 'none' | 'smooth' | 'smoothMarker';\n\nexport interface ScatterSeries {\n  idx: number;\n  order: number;\n  tx?: BarSeries['tx'];\n  spPr?: ShapeProperties;\n  dPt?: DataPoint[];\n  dLbls?: DataLabelList;\n  trendline?: Trendline[];\n  /** Up to 2 entries (one per direction). */\n  errBars?: ErrorBars[];\n  /** Data-point marker. */\n  marker?: Marker;\n  xVal?: NumericRef;\n  yVal: NumericRef;\n  smooth?: boolean;\n}\n\nexport interface ScatterChart {\n  kind: 'scatter';\n  scatterStyle: ScatterStyle;\n  varyColors?: boolean;\n  series: ScatterSeries[];\n  axIds: [number, number];\n}\n\nexport type RadarStyle = 'standard' | 'marker' | 'filled';\n\nexport interface RadarChart {\n  kind: 'radar';\n  radarStyle: RadarStyle;\n  varyColors?: boolean;\n  series: BarSeries[];\n  axIds: [number, number];\n}\n\nexport interface BubbleSeries {\n  idx: number;\n  order: number;\n  tx?: BarSeries['tx'];\n  spPr?: ShapeProperties;\n  invertIfNegative?: boolean;\n  dPt?: DataPoint[];\n  dLbls?: DataLabelList;\n  trendline?: Trendline[];\n  /** Up to 2 entries (one per direction). */\n  errBars?: ErrorBars[];\n  xVal?: NumericRef;\n  yVal: NumericRef;\n  /** Bubble size — required for a real bubble chart. */\n  bubbleSize: NumericRef;\n  /** Per-series 3-D toggle. */\n  bubble3D?: boolean;\n}\n\nexport type BubbleSizeRepresents = 'area' | 'w';\n\nexport interface BubbleChart {\n  kind: 'bubble';\n  varyColors?: boolean;\n  series: BubbleSeries[];\n  bubble3D?: boolean;\n  /** Bubble scale 0..300 %. Excel default is 100. */\n  bubbleScale?: number;\n  showNegBubbles?: boolean;\n  sizeRepresents?: BubbleSizeRepresents;\n  axIds: [number, number];\n}\n\n/** `<c:hiLowLines>` child of stock charts. */\nexport interface HiLowLines {\n  spPr?: ShapeProperties;\n}\n\n/** `<c:upBars>` / `<c:downBars>` child frame styling. */\nexport interface BarFrame {\n  spPr?: ShapeProperties;\n}\n\n/** `<c:upDownBars>` child of stock charts. */\nexport interface UpDownBars {\n  /** Gap width 0..500 between up/down bars. Excel default is 150. */\n  gapWidth?: number;\n  upBars?: BarFrame;\n  downBars?: BarFrame;\n}\n\nexport interface StockChart {\n  kind: 'stock';\n  /** Up to 4 series — typically open / high / low / close. */\n  series: BarSeries[];\n  /** Boolean flag for the simple `<c:hiLowLines/>` form, or an object with `spPr` for custom line styling. */\n  hiLowLines?: boolean | HiLowLines;\n  /** Boolean for the simple form, or an object with gapWidth / upBars / downBars detail. */\n  upDownBars?: boolean | UpDownBars;\n  axIds: [number, number];\n}\n\nexport interface SurfaceChart {\n  kind: 'surface';\n  series: BarSeries[];\n  /** Wireframe (line-only) when true; smoothed surface fill when false. */\n  wireframe?: boolean;\n  /** Surfaces use 3 axes: cat + val + ser. */\n  axIds: [number, number, number];\n}\n\nexport type OfPieType = 'bar' | 'pie';\nexport type SplitType = 'auto' | 'cust' | 'percent' | 'pos' | 'val';\n\nexport interface OfPieChart {\n  kind: 'ofPie';\n  /** `bar` for \"Bar of Pie\", `pie` for \"Pie of Pie\". */\n  ofPieType: OfPieType;\n  varyColors?: boolean;\n  series: BarSeries[];\n  gapWidth?: number;\n  splitType?: SplitType;\n  /** Position threshold paired with `splitType='pos'`. */\n  splitPos?: number;\n  /** Indices of data points moved to the secondary plot when `splitType='cust'`. */\n  custSplit?: number[];\n  /** Secondary plot size as % of primary (5..200). */\n  secondPieSize?: number;\n}\n\n// ---- 3-D chart variants ---------------------------------------------------\n//\n// 3-D charts share most of their attributes with their 2-D counterparts but\n// land on different XML tag names (<c:bar3DChart>, etc) and use 3 axes (cat /\n// val / ser). We keep them as distinct discriminated-union variants so the\n// chart kind stays type-narrowable.\n\nexport interface Bar3DChart {\n  kind: 'bar3D';\n  barDir: BarDirection;\n  grouping: GroupingType;\n  varyColors?: boolean;\n  series: BarSeries[];\n  gapWidth?: number;\n  /** Bar 3-D adds a `gapDepth` attribute. */\n  gapDepth?: number;\n  /** Cluster | percentStacked | stacked … plus 'standard' which 2-D doesn't take. */\n  shape?: 'cone' | 'coneToMax' | 'box' | 'cylinder' | 'pyramid' | 'pyramidToMax';\n  axIds: [number, number, number];\n}\n\nexport interface Line3DChart {\n  kind: 'line3D';\n  grouping: GroupingType;\n  varyColors?: boolean;\n  series: LineSeries[];\n  gapDepth?: number;\n  axIds: [number, number, number];\n}\n\nexport interface Pie3DChart {\n  kind: 'pie3D';\n  varyColors?: boolean;\n  series: BarSeries[];\n}\n\nexport interface Area3DChart {\n  kind: 'area3D';\n  grouping: GroupingType;\n  varyColors?: boolean;\n  series: BarSeries[];\n  gapDepth?: number;\n  axIds: [number, number, number];\n}\n\nexport interface Surface3DChart {\n  kind: 'surface3D';\n  series: BarSeries[];\n  wireframe?: boolean;\n  axIds: [number, number, number];\n}\n\n/** Discriminator union of all SpreadsheetML chart kinds modelled so far. */\nexport type ChartKind =\n  | BarChart\n  | LineChart\n  | AreaChart\n  | PieChart\n  | DoughnutChart\n  | ScatterChart\n  | RadarChart\n  | BubbleChart\n  | StockChart\n  | SurfaceChart\n  | OfPieChart\n  | Bar3DChart\n  | Line3DChart\n  | Pie3DChart\n  | Area3DChart\n  | Surface3DChart;\n\nexport type TickMark = 'cross' | 'in' | 'none' | 'out';\nexport type TickLabelPosition = 'high' | 'low' | 'nextTo' | 'none';\nexport type AxisCrosses = 'autoZero' | 'max' | 'min';\nexport type AxisOrientation = 'maxMin' | 'minMax';\nexport type AxisCrossBetween = 'between' | 'midCat';\nexport type CategoryLabelAlignment = 'ctr' | 'l' | 'r';\n\n/** `<c:scaling>` child of axes. */\nexport interface AxisScaling {\n  orientation?: AxisOrientation;\n  min?: number;\n  max?: number;\n  logBase?: number;\n}\n\ninterface AxisShared {\n  axId: number;\n  /** Crosses partner axis id. */\n  crossAx: number;\n  position?: 'b' | 't' | 'l' | 'r';\n  delete?: boolean;\n  /** Axis-line / tick formatting. */\n  spPr?: ShapeProperties;\n  /** Tick-label text formatting. */\n  txPr?: TextBody;\n  /** Axis title (`<c:title>`). Reuses the chart-title structure. */\n  title?: ChartTitle;\n  /** Tick-label number format. Default emitted is `General` / `sourceLinked=1`. */\n  numFmt?: ChartNumberFormat;\n  /** Major tick mark style. Default emitted is `out`. */\n  majorTickMark?: TickMark;\n  /** Minor tick mark style. Default emitted is `none`. */\n  minorTickMark?: TickMark;\n  /** Tick-label position. Default emitted is `nextTo`. */\n  tickLblPos?: TickLabelPosition;\n  /** Axis scaling (`<c:scaling>`). Default emitted is `orientation: 'minMax'`. */\n  scaling?: AxisScaling;\n  /** `<c:crosses>`. Default emitted is `autoZero`. Mutually exclusive with `crossesAt`. */\n  crosses?: AxisCrosses;\n  /** `<c:crossesAt val=\"...\"/>`. Numeric cross point on the partner axis. */\n  crossesAt?: number;\n  /**\n   * Major gridlines. `true` keeps Excel's default rendering; pass\n   * `{ spPr }` to override the line colour / width / dash. `false` /\n   * `undefined` omit the element entirely.\n   */\n  majorGridlines?: boolean | Gridlines;\n  /** Minor gridlines. Same shape as {@link AxisShared.majorGridlines}. */\n  minorGridlines?: boolean | Gridlines;\n}\n\n/**\n * Rich `<c:majorGridlines>` / `<c:minorGridlines>` form. Wraps a\n * `ShapeProperties` so the gridline line can be styled (e.g. corporate-style\n * light-grey `D9D9D9`).\n */\nexport interface Gridlines {\n  spPr?: ShapeProperties;\n}\n\nexport interface CategoryAxis extends AxisShared {\n  /** `<c:auto>` — whether Excel auto-selects the axis type from the data. */\n  auto?: boolean;\n  /** Tick-label alignment. Default emitted is `ctr`. */\n  lblAlgn?: CategoryLabelAlignment;\n  /** Tick-label offset 0..1000. Default emitted is `100`. */\n  lblOffset?: number;\n  /** Suppress multi-level labels for hierarchical categories. */\n  noMultiLvlLbl?: boolean;\n}\n\nexport interface ValueAxis extends AxisShared {\n  /** Tick-axis crossing rule. Default emitted is `between`. */\n  crossBetween?: AxisCrossBetween;\n  /** Major unit spacing on the value axis. */\n  majorUnit?: number;\n  /** Minor unit spacing on the value axis. */\n  minorUnit?: number;\n}\n\nexport type TimeUnit = 'days' | 'months' | 'years';\n\nexport interface DateAxis extends AxisShared {\n  /** `<c:auto>` — auto-select axis type. */\n  auto?: boolean;\n  /** Tick-label offset 0..1000. Default emitted is `100`. */\n  lblOffset?: number;\n  /** Smallest interval the axis represents. */\n  baseTimeUnit?: TimeUnit;\n  /** Major unit spacing on the date axis (count of `majorTimeUnit`s). */\n  majorUnit?: number;\n  majorTimeUnit?: TimeUnit;\n  /** Minor unit spacing on the date axis. */\n  minorUnit?: number;\n  minorTimeUnit?: TimeUnit;\n}\n\nexport interface SeriesAxis extends AxisShared {\n  /** Skip every Nth tick label (1 = every label). */\n  tickLblSkip?: number;\n  /** Skip every Nth tick mark. */\n  tickMarkSkip?: number;\n}\n\nexport interface PlotArea {\n  chart: ChartKind;\n  catAx?: CategoryAxis;\n  valAx?: ValueAxis;\n  /** Date / time axis. Replaces `catAx` when the categories are dates. */\n  dateAx?: DateAxis;\n  /** Series axis (used by `surface3DChart` / `surfaceChart`). */\n  serAx?: SeriesAxis;\n  /** Manual layout for the plot area inside the chart. */\n  layout?: Layout;\n  /** Plot-area shape properties (background fill, border line). */\n  spPr?: ShapeProperties;\n}\n\nexport type LayoutMode = 'edge' | 'factor';\nexport type LayoutTarget = 'inner' | 'outer';\n\n/** `<c:manualLayout>` child of `<c:layout>`. All values are fractions of the chart space (0..1). */\nexport interface ManualLayout {\n  layoutTarget?: LayoutTarget;\n  xMode?: LayoutMode;\n  yMode?: LayoutMode;\n  wMode?: LayoutMode;\n  hMode?: LayoutMode;\n  x?: number;\n  y?: number;\n  w?: number;\n  h?: number;\n}\n\n/** `<c:layout>` wrapper. Currently only `manualLayout` is exposed; the lone `<layoutId>` form is for chartex. */\nexport interface Layout {\n  manualLayout?: ManualLayout;\n}\n\nexport interface Legend {\n  position: LegendPosition;\n  overlay?: boolean;\n  layout?: Layout;\n  spPr?: ShapeProperties;\n  txPr?: TextBody;\n}\n\n/** Chart title with full DrawingML formatting support. */\nexport interface ChartTitle {\n  /**\n   * Plain title text. When set the serializer emits\n   * `<c:tx><c:rich><a:p><a:r><a:t>text</a:t></a:r></c:rich></c:tx>`. Mutually\n   * exclusive with `tx`.\n   */\n  text?: string;\n  /** Rich text body — overrides `text` when both are present. */\n  tx?: TextBody;\n  overlay?: boolean;\n  layout?: Layout;\n  spPr?: ShapeProperties;\n  txPr?: TextBody;\n}\n\n/** 3-D viewing options. Used by `bar3DChart`, `line3DChart`, `pie3DChart`, `area3DChart`, `surface3DChart`. */\nexport interface View3D {\n  /** X-axis rotation in degrees, -90..90. */\n  rotX?: number;\n  /** Y-axis rotation in degrees, 0..359. */\n  rotY?: number;\n  /** Depth as a percentage of chart width, 20..2000. */\n  depthPercent?: number;\n  /** Height as a percentage of chart width, 5..500. */\n  hPercent?: number;\n  /** Use right-angle axes (orthographic). When true, perspective is ignored. */\n  rAngAx?: boolean;\n  /** Perspective angle 0..240 (0 = isometric, 30 = Excel default). */\n  perspective?: number;\n}\n\n/** 3-D wall / floor frame. Children of `<c:chart>` for bar3D / line3D / area3D / surface3D / pie3D. */\nexport interface SurfaceFrame {\n  /** Wall thickness in % of chart width (0..100). */\n  thickness?: number;\n  spPr?: ShapeProperties;\n}\n\nexport interface ChartSpace {\n  /** Optional chart title. */\n  title?: ChartTitle;\n  legend?: Legend;\n  plotArea: PlotArea;\n  /**\n   * Built-in Excel chart-style preset (1..48). Mapped to `<c:style val=\"N\"/>` inside\n   * `<c:chartSpace>` and selects one entry of Excel's \"Chart Styles\" gallery.\n   */\n  style?: number;\n  /** 3-D viewing options (applies to 3-D chart kinds; ignored otherwise by Excel). */\n  view3D?: View3D;\n  /** 3-D chart floor frame. */\n  floor?: SurfaceFrame;\n  /** 3-D chart side wall frame. */\n  sideWall?: SurfaceFrame;\n  /** 3-D chart back wall frame. */\n  backWall?: SurfaceFrame;\n  /** Honour the formatting hints in cached numeric data when rendering. */\n  plotVisOnly?: boolean;\n  /** Display blanks as gap, zero, or span — Excel default is `gap`. */\n  dispBlanksAs?: 'gap' | 'zero' | 'span';\n  /** Chart-space level shape properties (overall frame). */\n  spPr?: ShapeProperties;\n  /** Chart-space level default text properties. */\n  txPr?: TextBody;\n  /** Annotations / text boxes / arrows drawn over the chart. Serialised as `xl/drawings/chartDrawingN.xml`. */\n  userShapes?: ChartDrawing;\n}\n\nexport function makeBarChart(opts: {\n  barDir?: BarDirection;\n  grouping?: GroupingType;\n  series?: BarSeries[];\n  axIds?: [number, number];\n  varyColors?: boolean;\n  gapWidth?: number;\n  overlap?: number;\n}): BarChart {\n  return {\n    kind: 'bar',\n    barDir: opts.barDir ?? 'col',\n    grouping: opts.grouping ?? 'clustered',\n    series: opts.series ?? [],\n    axIds: opts.axIds ?? [1, 2],\n    ...(opts.varyColors !== undefined ? { varyColors: opts.varyColors } : {}),\n    ...(opts.gapWidth !== undefined ? { gapWidth: opts.gapWidth } : {}),\n    ...(opts.overlap !== undefined ? { overlap: opts.overlap } : {}),\n  };\n}\n\nexport function makeBarSeries(opts: {\n  idx: number;\n  order?: number;\n  val: NumericRef;\n  cat?: CategoryRef;\n  tx?: BarSeries['tx'];\n}): BarSeries {\n  return {\n    idx: opts.idx,\n    order: opts.order ?? opts.idx,\n    val: opts.val,\n    ...(opts.cat ? { cat: opts.cat } : {}),\n    ...(opts.tx ? { tx: opts.tx } : {}),\n  };\n}\n\nexport function makeChartSpace(opts: {\n  plotArea: PlotArea;\n  /** Plain string is wrapped in `{ text }`; pass `ChartTitle` for full formatting. */\n  title?: string | ChartTitle;\n  legend?: Legend;\n  style?: number;\n  view3D?: View3D;\n  floor?: SurfaceFrame;\n  sideWall?: SurfaceFrame;\n  backWall?: SurfaceFrame;\n  plotVisOnly?: boolean;\n  dispBlanksAs?: ChartSpace['dispBlanksAs'];\n  spPr?: ShapeProperties;\n  txPr?: TextBody;\n}): ChartSpace {\n  const title: ChartTitle | undefined = typeof opts.title === 'string' ? { text: opts.title } : opts.title;\n  return {\n    plotArea: opts.plotArea,\n    ...(title !== undefined ? { title } : {}),\n    ...(opts.legend ? { legend: opts.legend } : {}),\n    ...(opts.style !== undefined ? { style: opts.style } : {}),\n    ...(opts.view3D ? { view3D: opts.view3D } : {}),\n    ...(opts.floor ? { floor: opts.floor } : {}),\n    ...(opts.sideWall ? { sideWall: opts.sideWall } : {}),\n    ...(opts.backWall ? { backWall: opts.backWall } : {}),\n    ...(opts.plotVisOnly !== undefined ? { plotVisOnly: opts.plotVisOnly } : {}),\n    ...(opts.dispBlanksAs !== undefined ? { dispBlanksAs: opts.dispBlanksAs } : {}),\n    ...(opts.spPr ? { spPr: opts.spPr } : {}),\n    ...(opts.txPr ? { txPr: opts.txPr } : {}),\n  };\n}\n\nexport function makeLineChart(opts: {\n  grouping?: GroupingType;\n  series?: LineSeries[];\n  axIds?: [number, number];\n  varyColors?: boolean;\n  smooth?: boolean;\n}): LineChart {\n  return {\n    kind: 'line',\n    grouping: opts.grouping ?? 'standard',\n    series: opts.series ?? [],\n    axIds: opts.axIds ?? [1, 2],\n    ...(opts.varyColors !== undefined ? { varyColors: opts.varyColors } : {}),\n    ...(opts.smooth !== undefined ? { smooth: opts.smooth } : {}),\n  };\n}\n\nexport function makeAreaChart(opts: {\n  grouping?: GroupingType;\n  series?: BarSeries[];\n  axIds?: [number, number];\n  varyColors?: boolean;\n}): AreaChart {\n  return {\n    kind: 'area',\n    grouping: opts.grouping ?? 'standard',\n    series: opts.series ?? [],\n    axIds: opts.axIds ?? [1, 2],\n    ...(opts.varyColors !== undefined ? { varyColors: opts.varyColors } : {}),\n  };\n}\n\nexport function makePieChart(opts: { series?: BarSeries[]; varyColors?: boolean }): PieChart {\n  return {\n    kind: 'pie',\n    series: opts.series ?? [],\n    ...(opts.varyColors !== undefined ? { varyColors: opts.varyColors } : {}),\n  };\n}\n\nexport function makeDoughnutChart(opts: {\n  series?: BarSeries[];\n  varyColors?: boolean;\n  holeSize?: number;\n  firstSliceAng?: number;\n}): DoughnutChart {\n  return {\n    kind: 'doughnut',\n    series: opts.series ?? [],\n    ...(opts.varyColors !== undefined ? { varyColors: opts.varyColors } : {}),\n    ...(opts.holeSize !== undefined ? { holeSize: opts.holeSize } : {}),\n    ...(opts.firstSliceAng !== undefined ? { firstSliceAng: opts.firstSliceAng } : {}),\n  };\n}\n\nexport function makeScatterChart(opts: {\n  scatterStyle?: ScatterStyle;\n  series?: ScatterSeries[];\n  axIds?: [number, number];\n  varyColors?: boolean;\n}): ScatterChart {\n  return {\n    kind: 'scatter',\n    scatterStyle: opts.scatterStyle ?? 'lineMarker',\n    series: opts.series ?? [],\n    axIds: opts.axIds ?? [1, 2],\n    ...(opts.varyColors !== undefined ? { varyColors: opts.varyColors } : {}),\n  };\n}\n\nexport function makeScatterSeries(opts: {\n  idx: number;\n  order?: number;\n  tx?: BarSeries['tx'];\n  xVal?: NumericRef;\n  yVal: NumericRef;\n  smooth?: boolean;\n  marker?: Marker;\n}): ScatterSeries {\n  return {\n    idx: opts.idx,\n    order: opts.order ?? opts.idx,\n    yVal: opts.yVal,\n    ...(opts.tx ? { tx: opts.tx } : {}),\n    ...(opts.xVal ? { xVal: opts.xVal } : {}),\n    ...(opts.smooth !== undefined ? { smooth: opts.smooth } : {}),\n    ...(opts.marker ? { marker: opts.marker } : {}),\n  };\n}\n\nexport function makeRadarChart(opts: {\n  radarStyle?: RadarStyle;\n  series?: BarSeries[];\n  axIds?: [number, number];\n  varyColors?: boolean;\n}): RadarChart {\n  return {\n    kind: 'radar',\n    radarStyle: opts.radarStyle ?? 'standard',\n    series: opts.series ?? [],\n    axIds: opts.axIds ?? [1, 2],\n    ...(opts.varyColors !== undefined ? { varyColors: opts.varyColors } : {}),\n  };\n}\n\nexport function makeBubbleChart(opts: {\n  series?: BubbleSeries[];\n  axIds?: [number, number];\n  varyColors?: boolean;\n  bubble3D?: boolean;\n  bubbleScale?: number;\n  showNegBubbles?: boolean;\n  sizeRepresents?: BubbleSizeRepresents;\n}): BubbleChart {\n  return {\n    kind: 'bubble',\n    series: opts.series ?? [],\n    axIds: opts.axIds ?? [1, 2],\n    ...(opts.varyColors !== undefined ? { varyColors: opts.varyColors } : {}),\n    ...(opts.bubble3D !== undefined ? { bubble3D: opts.bubble3D } : {}),\n    ...(opts.bubbleScale !== undefined ? { bubbleScale: opts.bubbleScale } : {}),\n    ...(opts.showNegBubbles !== undefined ? { showNegBubbles: opts.showNegBubbles } : {}),\n    ...(opts.sizeRepresents !== undefined ? { sizeRepresents: opts.sizeRepresents } : {}),\n  };\n}\n\nexport function makeBubbleSeries(opts: {\n  idx: number;\n  order?: number;\n  tx?: BarSeries['tx'];\n  xVal?: NumericRef;\n  yVal: NumericRef;\n  bubbleSize: NumericRef;\n  bubble3D?: boolean;\n}): BubbleSeries {\n  return {\n    idx: opts.idx,\n    order: opts.order ?? opts.idx,\n    yVal: opts.yVal,\n    bubbleSize: opts.bubbleSize,\n    ...(opts.tx ? { tx: opts.tx } : {}),\n    ...(opts.xVal ? { xVal: opts.xVal } : {}),\n    ...(opts.bubble3D !== undefined ? { bubble3D: opts.bubble3D } : {}),\n  };\n}\n\nexport function makeStockChart(opts: {\n  series?: BarSeries[];\n  axIds?: [number, number];\n  hiLowLines?: boolean | HiLowLines;\n  upDownBars?: boolean | UpDownBars;\n}): StockChart {\n  return {\n    kind: 'stock',\n    series: opts.series ?? [],\n    axIds: opts.axIds ?? [1, 2],\n    ...(opts.hiLowLines !== undefined ? { hiLowLines: opts.hiLowLines } : {}),\n    ...(opts.upDownBars !== undefined ? { upDownBars: opts.upDownBars } : {}),\n  };\n}\n\nexport function makeSurfaceChart(opts: {\n  series?: BarSeries[];\n  wireframe?: boolean;\n  axIds?: [number, number, number];\n}): SurfaceChart {\n  return {\n    kind: 'surface',\n    series: opts.series ?? [],\n    axIds: opts.axIds ?? [1, 2, 3],\n    ...(opts.wireframe !== undefined ? { wireframe: opts.wireframe } : {}),\n  };\n}\n\nexport function makeOfPieChart(opts: {\n  ofPieType?: OfPieType;\n  series?: BarSeries[];\n  varyColors?: boolean;\n  gapWidth?: number;\n  splitType?: SplitType;\n  splitPos?: number;\n  custSplit?: number[];\n  secondPieSize?: number;\n}): OfPieChart {\n  return {\n    kind: 'ofPie',\n    ofPieType: opts.ofPieType ?? 'pie',\n    series: opts.series ?? [],\n    ...(opts.varyColors !== undefined ? { varyColors: opts.varyColors } : {}),\n    ...(opts.gapWidth !== undefined ? { gapWidth: opts.gapWidth } : {}),\n    ...(opts.splitType !== undefined ? { splitType: opts.splitType } : {}),\n    ...(opts.splitPos !== undefined ? { splitPos: opts.splitPos } : {}),\n    ...(opts.custSplit ? { custSplit: opts.custSplit } : {}),\n    ...(opts.secondPieSize !== undefined ? { secondPieSize: opts.secondPieSize } : {}),\n  };\n}\n\nexport function makeBar3DChart(opts: {\n  barDir?: BarDirection;\n  grouping?: GroupingType;\n  series?: BarSeries[];\n  axIds?: [number, number, number];\n  varyColors?: boolean;\n  gapWidth?: number;\n  gapDepth?: number;\n  shape?: Bar3DChart['shape'];\n}): Bar3DChart {\n  return {\n    kind: 'bar3D',\n    barDir: opts.barDir ?? 'col',\n    grouping: opts.grouping ?? 'clustered',\n    series: opts.series ?? [],\n    axIds: opts.axIds ?? [1, 2, 3],\n    ...(opts.varyColors !== undefined ? { varyColors: opts.varyColors } : {}),\n    ...(opts.gapWidth !== undefined ? { gapWidth: opts.gapWidth } : {}),\n    ...(opts.gapDepth !== undefined ? { gapDepth: opts.gapDepth } : {}),\n    ...(opts.shape !== undefined ? { shape: opts.shape } : {}),\n  };\n}\n\nexport function makeLine3DChart(opts: {\n  grouping?: GroupingType;\n  series?: LineSeries[];\n  axIds?: [number, number, number];\n  varyColors?: boolean;\n  gapDepth?: number;\n}): Line3DChart {\n  return {\n    kind: 'line3D',\n    grouping: opts.grouping ?? 'standard',\n    series: opts.series ?? [],\n    axIds: opts.axIds ?? [1, 2, 3],\n    ...(opts.varyColors !== undefined ? { varyColors: opts.varyColors } : {}),\n    ...(opts.gapDepth !== undefined ? { gapDepth: opts.gapDepth } : {}),\n  };\n}\n\nexport function makePie3DChart(opts: { series?: BarSeries[]; varyColors?: boolean }): Pie3DChart {\n  return {\n    kind: 'pie3D',\n    series: opts.series ?? [],\n    ...(opts.varyColors !== undefined ? { varyColors: opts.varyColors } : {}),\n  };\n}\n\nexport function makeArea3DChart(opts: {\n  grouping?: GroupingType;\n  series?: BarSeries[];\n  axIds?: [number, number, number];\n  varyColors?: boolean;\n  gapDepth?: number;\n}): Area3DChart {\n  return {\n    kind: 'area3D',\n    grouping: opts.grouping ?? 'standard',\n    series: opts.series ?? [],\n    axIds: opts.axIds ?? [1, 2, 3],\n    ...(opts.varyColors !== undefined ? { varyColors: opts.varyColors } : {}),\n    ...(opts.gapDepth !== undefined ? { gapDepth: opts.gapDepth } : {}),\n  };\n}\n\nexport function makeSurface3DChart(opts: {\n  series?: BarSeries[];\n  wireframe?: boolean;\n  axIds?: [number, number, number];\n}): Surface3DChart {\n  return {\n    kind: 'surface3D',\n    series: opts.series ?? [],\n    axIds: opts.axIds ?? [1, 2, 3],\n    ...(opts.wireframe !== undefined ? { wireframe: opts.wireframe } : {}),\n  };\n}\n","// User shapes (chartDrawing) — annotations on a chart.\n//\n// `xl/drawings/chartDrawingN.xml` is referenced from a `<c:chartSpace>` via\n// `<c:userShapes r:id=\"...\">`. It contains text boxes, arrows, and other shapes\n// positioned either relatively (0..1 of chart width / height) or absolutely\n// (relative anchor + EMU extent).\n\nimport type { ShapeProperties, PositiveSize2D } from '../drawing/dml/shape-properties';\nimport type { TextBody } from '../drawing/dml/text';\n\n/** `<cdr:from>` / `<cdr:to>` marker. Decimal in 0..1. */\nexport interface ChartRelativeMarker {\n  x: number;\n  y: number;\n}\n\n/** `<cdr:sp>` shape leaf (text box / arrow / preset shape with optional text). */\nexport interface ChartDrawingShape {\n  /** cNvPr id (1-based, unique per chartDrawing). */\n  id: number;\n  name?: string;\n  descr?: string;\n  hidden?: boolean;\n  /** When true, emit `<cdr:nvSpPr><cdr:cNvSpPr txBox=\"1\"/>` so Excel renders the shape as a text-box. */\n  txBox?: boolean;\n  spPr?: ShapeProperties;\n  txBody?: TextBody;\n}\n\n/** `<cdr:pic>` picture leaf. */\nexport interface ChartDrawingPicture {\n  id: number;\n  name?: string;\n  descr?: string;\n  /** rels-resolved id used by `<a:blip r:embed>`. */\n  embedRId?: string;\n  spPr?: ShapeProperties;\n}\n\nexport type UserShapeContent =\n  | { kind: 'shape'; shape: ChartDrawingShape }\n  | { kind: 'picture'; picture: ChartDrawingPicture };\n\nexport type UserShapeAnchor =\n  | {\n      kind: 'relSize';\n      from: ChartRelativeMarker;\n      to: ChartRelativeMarker;\n      content: UserShapeContent;\n    }\n  | {\n      kind: 'absSize';\n      from: ChartRelativeMarker;\n      ext: PositiveSize2D;\n      content: UserShapeContent;\n    };\n\nexport interface ChartDrawing {\n  shapes: UserShapeAnchor[];\n}\n\nexport const makeChartDrawing = (shapes: UserShapeAnchor[] = []): ChartDrawing => ({ shapes });\n\nexport const makeChartShape = (opts: {\n  id: number;\n  name?: string;\n  descr?: string;\n  hidden?: boolean;\n  txBox?: boolean;\n  spPr?: ShapeProperties;\n  txBody?: TextBody;\n}): ChartDrawingShape => ({\n  id: opts.id,\n  ...(opts.name !== undefined ? { name: opts.name } : {}),\n  ...(opts.descr !== undefined ? { descr: opts.descr } : {}),\n  ...(opts.hidden !== undefined ? { hidden: opts.hidden } : {}),\n  ...(opts.txBox !== undefined ? { txBox: opts.txBox } : {}),\n  ...(opts.spPr ? { spPr: opts.spPr } : {}),\n  ...(opts.txBody ? { txBody: opts.txBody } : {}),\n});\n\nexport const makeRelSizeAnchor = (\n  from: ChartRelativeMarker,\n  to: ChartRelativeMarker,\n  content: UserShapeContent,\n): UserShapeAnchor => ({ kind: 'relSize', from, to, content });\n\nexport const makeAbsSizeAnchor = (\n  from: ChartRelativeMarker,\n  ext: PositiveSize2D,\n  content: UserShapeContent,\n): UserShapeAnchor => ({ kind: 'absSize', from, ext, content });\n"],"mappings":"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"}

package/dist/utf8-D91g1XTG.mjs

@@ -0,0 +1,143 @@
+import { o as OpenXmlSchemaError } from "./exceptions-D-CFwxgm.mjs";
+import { jt as qname } from "./tree-Bbs1C8Rc.mjs";
+import { SaxesParser } from "saxes";
+//#region src/xml/iterparse.ts
+const DOCTYPE_RE = /<!DOCTYPE\b/;
+const ENTITY_RE = /<!ENTITY\b/;
+const checkDoctype = (text) => {
+	if (DOCTYPE_RE.test(text)) throw new OpenXmlSchemaError("DTD declarations are not permitted in OOXML payloads");
+	if (ENTITY_RE.test(text)) throw new OpenXmlSchemaError("Entity declarations are not permitted in OOXML payloads");
+};
+const isReadableStream = (v) => {
+	return typeof v === "object" && v !== null && typeof v.getReader === "function";
+};
+const decoder = () => new TextDecoder("utf-8", { fatal: false });
+const buildAttrsClark = (attrs) => {
+	const out = {};
+	for (const [, info] of Object.entries(attrs)) {
+		if (info.prefix === "xmlns" || info.prefix === "" && info.local === "xmlns") continue;
+		const key = qname(info.uri, info.local);
+		out[key] = info.value;
+	}
+	return out;
+};
+/**
+* Parse the input as a stream of SAX events. Element / attribute names are
+* returned in Clark notation (`{ns}local`).
+*/
+async function* iterParse(input) {
+	const parser = new SaxesParser({
+		xmlns: true,
+		fragment: false
+	});
+	let queue = [];
+	let head = 0;
+	let pending;
+	parser.on("error", (err) => {
+		pending = err;
+	});
+	parser.on("doctype", () => {
+		pending = new OpenXmlSchemaError("DTD declarations are not permitted in OOXML payloads");
+	});
+	parser.on("opentag", (node) => {
+		queue.push({
+			kind: "start",
+			name: qname(node.uri, node.local),
+			attrs: buildAttrsClark(node.attributes)
+		});
+	});
+	parser.on("closetag", (node) => {
+		queue.push({
+			kind: "end",
+			name: qname(node.uri, node.local)
+		});
+	});
+	parser.on("text", (text) => {
+		if (text.length > 0) queue.push({
+			kind: "text",
+			text
+		});
+	});
+	const drain = function* () {
+		for (;;) {
+			const ev = head < queue.length ? queue[head] : void 0;
+			if (ev === void 0) {
+				queue = [];
+				head = 0;
+				return;
+			}
+			head++;
+			yield ev;
+		}
+	};
+	const feed = (chunk) => {
+		parser.write(chunk);
+		if (pending !== void 0) throw pending;
+	};
+	if (typeof input === "string") {
+		checkDoctype(input);
+		feed(input);
+	} else if (input instanceof Uint8Array) {
+		const text = decoder().decode(input);
+		checkDoctype(text);
+		feed(text);
+		yield* drain();
+	} else if (isReadableStream(input)) {
+		const reader = input.getReader();
+		const td = decoder();
+		let firstChunkChecked = false;
+		let firstChunkBuffer = "";
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			const chunk = td.decode(value, { stream: true });
+			if (!firstChunkChecked) {
+				firstChunkBuffer += chunk;
+				if (firstChunkBuffer.length >= 256) {
+					checkDoctype(firstChunkBuffer);
+					firstChunkChecked = true;
+					feed(firstChunkBuffer);
+					yield* drain();
+				}
+			} else {
+				feed(chunk);
+				yield* drain();
+			}
+		}
+		const tail = td.decode();
+		if (!firstChunkChecked) {
+			const all = firstChunkBuffer + tail;
+			checkDoctype(all);
+			feed(all);
+			yield* drain();
+		} else if (tail.length > 0) {
+			feed(tail);
+			yield* drain();
+		}
+	} else throw new OpenXmlSchemaError("iterParse: unsupported input type");
+	parser.close();
+	if (pending !== void 0) throw pending;
+	yield* drain();
+}
+//#endregion
+//#region src/utils/utf8.ts
+function utf8ByteLength(s) {
+	let n = 0;
+	for (let i = 0; i < s.length; i++) {
+		const c = s.charCodeAt(i);
+		if (c < 128) n += 1;
+		else if (c < 2048) n += 2;
+		else if (c >= 55296 && c <= 56319) {
+			const next = i + 1 < s.length ? s.charCodeAt(i + 1) : 0;
+			if (next >= 56320 && next <= 57343) {
+				n += 4;
+				i++;
+			} else n += 3;
+		} else n += 3;
+	}
+	return n;
+}
+//#endregion
+export { iterParse as n, utf8ByteLength as t };
+
+//# sourceMappingURL=utf8-D91g1XTG.mjs.map

package/dist/utf8-D91g1XTG.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utf8-D91g1XTG.mjs","names":[],"sources":["../src/xml/iterparse.ts","../src/utils/utf8.ts"],"sourcesContent":["// SAX iterator over OOXML XML payloads. Wraps `saxes` (XMLNS-aware) and yields\n// a flat stream of {start | end | text} events with names already converted to\n// Clark notation (`{ns}local`) — same shape as the DOM parser produces for\n// static XmlNode trees, so consumers can switch between bulk and streaming\n// reads without retouching name comparison.\n//\n// Phase 1 §3 acceptance: 1 k–row sheetData walked end-to-end with cell counts\n// matching the source. The phase-4 read-only worksheet drives real-world use;\n// this layer just produces the events.\n//\n// DOCTYPE / external entity declarations are forbidden. saxes does not expand\n// external entities, but a prescan also rejects DTDs in non-streaming inputs.\n// Streaming inputs are checked on the first chunk before being fed to the\n// parser.\n\nimport { SaxesParser } from 'saxes';\nimport { OpenXmlSchemaError } from '../utils/exceptions';\nimport { qname } from './namespaces';\n\nexport type SaxEvent =\n  | { kind: 'start'; name: string; attrs: Record<string, string> }\n  | { kind: 'end'; name: string }\n  | { kind: 'text'; text: string };\n\n/**\n * Streamable input: `Uint8Array`, plain string, or a Web `ReadableStream` of\n * `Uint8Array` chunks (produced by xlsx zip entries via fflate, fetch, file\n * streams, etc.).\n */\nexport type SaxInput = Uint8Array | string | ReadableStream<Uint8Array>;\n\nconst DOCTYPE_RE = /<!DOCTYPE\\b/;\nconst ENTITY_RE = /<!ENTITY\\b/;\n\nconst checkDoctype = (text: string): void => {\n  if (DOCTYPE_RE.test(text)) {\n    throw new OpenXmlSchemaError('DTD declarations are not permitted in OOXML payloads');\n  }\n  if (ENTITY_RE.test(text)) {\n    throw new OpenXmlSchemaError('Entity declarations are not permitted in OOXML payloads');\n  }\n};\n\nconst isReadableStream = (v: unknown): v is ReadableStream<Uint8Array> => {\n  return typeof v === 'object' && v !== null && typeof (v as ReadableStream).getReader === 'function';\n};\n\nconst decoder = (): TextDecoder => new TextDecoder('utf-8', { fatal: false });\n\ninterface SaxesOpenTag {\n  name: string;\n  uri: string;\n  local: string;\n  prefix: string;\n  attributes: Record<string, { value: string; uri: string; local: string; prefix: string }>;\n  isSelfClosing?: boolean;\n}\n\ninterface SaxesCloseTag {\n  name: string;\n  uri: string;\n  local: string;\n  prefix: string;\n}\n\nconst buildAttrsClark = (attrs: SaxesOpenTag['attributes']): Record<string, string> => {\n  const out: Record<string, string> = {};\n  for (const [, info] of Object.entries(attrs)) {\n    // saxes already resolved the namespace when xmlns: true is set; raw xmlns /\n    // xmlns:* declarations have prefix='xmlns' (or local==='xmlns' when\n    // default) and we drop those — they're rebuilt by the serializer.\n    if (info.prefix === 'xmlns' || (info.prefix === '' && info.local === 'xmlns')) continue;\n    const key = qname(info.uri, info.local);\n    out[key] = info.value;\n  }\n  return out;\n};\n\n/**\n * Parse the input as a stream of SAX events. Element / attribute names are\n * returned in Clark notation (`{ns}local`).\n */\nexport async function* iterParse(input: SaxInput): AsyncIterableIterator<SaxEvent> {\n  // Set up the parser. xmlns: true gives us resolved {uri, local, prefix} on\n  // every open / close tag and on every attribute.\n  const parser = new SaxesParser({ xmlns: true, fragment: false });\n\n  // Head-pointer ring instead of Array#shift: each saxes write() can produce\n  // hundreds of events in a single synchronous batch (a `<row>` with dozens of\n  // cells flushes one opentag + one text + one closetag per cell). `shift()`\n  // is O(n) per element in V8, so a single-batch drain of N events would be\n  // O(N²) before iteration. The head advances on yield; the queue is reset\n  // (head + length) once it drains so memory stays bounded.\n  let queue: SaxEvent[] = [];\n  let head = 0;\n  let pending: Error | undefined;\n\n  parser.on('error', (err: Error) => {\n    pending = err;\n  });\n  parser.on('doctype', () => {\n    pending = new OpenXmlSchemaError('DTD declarations are not permitted in OOXML payloads');\n  });\n  parser.on('opentag', (node: SaxesOpenTag) => {\n    queue.push({ kind: 'start', name: qname(node.uri, node.local), attrs: buildAttrsClark(node.attributes) });\n  });\n  parser.on('closetag', (node: SaxesCloseTag) => {\n    queue.push({ kind: 'end', name: qname(node.uri, node.local) });\n  });\n  parser.on('text', (text: string) => {\n    if (text.length > 0) queue.push({ kind: 'text', text });\n  });\n\n  const drain = function* (): IterableIterator<SaxEvent> {\n    for (;;) {\n      const ev = head < queue.length ? queue[head] : undefined;\n      if (ev === undefined) {\n        // Reset rather than grow forever; the next batch starts at index 0.\n        queue = [];\n        head = 0;\n        return;\n      }\n      head++;\n      yield ev;\n    }\n  };\n\n  const feed = (chunk: string): void => {\n    parser.write(chunk);\n    if (pending !== undefined) throw pending;\n  };\n\n  if (typeof input === 'string') {\n    checkDoctype(input);\n    feed(input);\n  } else if (input instanceof Uint8Array) {\n    const text = decoder().decode(input);\n    checkDoctype(text);\n    feed(text);\n    yield* drain();\n  } else if (isReadableStream(input)) {\n    const reader = input.getReader();\n    const td = decoder();\n    let firstChunkChecked = false;\n    let firstChunkBuffer = '';\n    while (true) {\n      const { done, value } = await reader.read();\n      if (done) break;\n      const chunk = td.decode(value, { stream: true });\n      if (!firstChunkChecked) {\n        // We need to see enough of the prologue to be sure no DOCTYPE is\n        // hiding. Buffer until we have ~256 chars; if the stream ends before\n        // we reach the threshold the tail handler below runs `checkDoctype`\n        // on the accumulated prologue. (The previous `|| done` here was dead:\n        // a true `done` short-circuits at the top of the loop.)\n        firstChunkBuffer += chunk;\n        if (firstChunkBuffer.length >= 256) {\n          checkDoctype(firstChunkBuffer);\n          firstChunkChecked = true;\n          feed(firstChunkBuffer);\n          yield* drain();\n        }\n      } else {\n        feed(chunk);\n        yield* drain();\n      }\n    }\n    // Stream ended; flush decoder + any buffered prologue.\n    const tail = td.decode();\n    if (!firstChunkChecked) {\n      const all = firstChunkBuffer + tail;\n      checkDoctype(all);\n      feed(all);\n      yield* drain();\n    } else if (tail.length > 0) {\n      feed(tail);\n      yield* drain();\n    }\n  } else {\n    throw new OpenXmlSchemaError('iterParse: unsupported input type');\n  }\n\n  parser.close();\n  if (pending !== undefined) throw pending;\n  yield* drain();\n}\n","// Fast UTF-8 byte-length scan. Used by streaming writers to decide when their\n// pending string buffer should be encoded + flushed.\n//\n// `s.length` returns UTF-16 code units, which undercounts BMP characters above\n// U+007F (1 code unit, 2 UTF-8 bytes for U+0080–U+07FF, 3 bytes for the rest\n// of the BMP). For CJK-heavy payloads the discrepancy is ~3× — large enough\n// to push a \"64 KB\" flush threshold to 192 KB of resident text. We scan the\n// string once and account for each codepoint instead of running a full\n// TextEncoder, which would also have to materialise the byte buffer we don't\n// need yet.\nexport function utf8ByteLength(s: string): number {\n  let n = 0;\n  for (let i = 0; i < s.length; i++) {\n    const c = s.charCodeAt(i);\n    if (c < 0x80) {\n      n += 1;\n    } else if (c < 0x800) {\n      n += 2;\n    } else if (c >= 0xd800 && c <= 0xdbff) {\n      // High surrogate. Only consume the next code unit when it actually\n      // is a low surrogate — an unpaired high surrogate (followed by a\n      // BMP char or by EOS) would otherwise swallow the next code unit\n      // and undercount the string. TextEncoder replaces a lone high\n      // surrogate with U+FFFD (3 bytes), so use 3 here too. A paired\n      // surrogate encodes one 4-byte codepoint.\n      const next = i + 1 < s.length ? s.charCodeAt(i + 1) : 0;\n      if (next >= 0xdc00 && next <= 0xdfff) {\n        n += 4;\n        i++;\n      } else {\n        n += 3;\n      }\n    } else {\n      // Includes unpaired low surrogates (0xDC00-0xDFFF), which encode as\n      // U+FFFD = 3 UTF-8 bytes through TextEncoder.\n      n += 3;\n    }\n  }\n  return n;\n}\n"],"mappings":"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"}

package/dist/utils/coordinate.d.ts

@@ -0,0 +1,103 @@
+/** Maximum column index Excel accepts (XFD). */
+export declare const MAX_COL = 16384;
+/** Maximum row index Excel accepts. */
+export declare const MAX_ROW = 1048576;
+/**
+ * 1-based column index → spreadsheet column letter ("A", "Z", "AA", "XFD").
+ * Throws OpenXmlSchemaError when out of range.
+ */
+export declare function columnLetterFromIndex(n: number): string;
+/**
+ * Column letter → 1-based column index. Case-insensitive but at most 3 letters
+ * (the spec ceiling). Throws on empty / non-A-Z / over-range.
+ */
+export declare function columnIndexFromLetter(letter: string): number;
+/** A single-cell coordinate split into its letter and 1-based row. */
+export interface CellCoordinate {
+    column: string;
+    row: number;
+}
+/** A single-cell coordinate split into 1-based numeric (col, row). */
+export interface CellCoordinateNumeric {
+    col: number;
+    row: number;
+}
+/** A 1-based rectangular boundary. */
+export interface CellRangeBoundaries {
+    minCol: number;
+    minRow: number;
+    maxCol: number;
+    maxRow: number;
+}
+/**
+ * Parse a single-cell coordinate string ("A1", "$XFD$1048576") into its column
+ * letter (always uppercased) and 1-based row.
+ */
+export declare function coordinateFromString(coord: string): CellCoordinate;
+/**
+ * Same as {@link coordinateFromString} but returning the column as its 1-based
+ * numeric index. Thin convenience for the worksheet read path.
+ */
+export declare function coordinateToTuple(coord: string): CellCoordinateNumeric;
+/** Compose `"A1"` from a 1-based (col, row). */
+export declare function tupleToCoordinate(col: number, row: number): string;
+/**
+ * Predicate: true iff `s` is a valid single-cell A1 coordinate (`"A1"`,
+ * `"XFD1048576"`). Strings with `$` absolute markers, surrounding whitespace,
+ * ranges (`A1:B2`), or out-of-bound row / column return false. Useful for
+ * sanitising user input before passing to {@link coordinateToTuple} or
+ * `setCellByCoord`.
+ */
+export declare function isValidCellRef(s: unknown): s is string;
+/**
+ * Predicate: true iff `s` is a valid A1-style range expression — single cell,
+ * two-corner range, whole column (`A:A`), or whole row (`1:1`). `$` markers,
+ * whitespace, and out-of-bound bounds fail. Sanity-check before {@link
+ * rangeBoundaries} / `parseRange`.
+ */
+export declare function isValidRangeRef(s: unknown): s is string;
+/**
+ * Predicate: true iff `s` is a valid 1..3-char column letter (`"A"` through
+ * `"XFD"`, case-insensitive). Empty / over-long / out-of-bound / non-string
+ * fails.
+ */
+export declare function isValidColumnLetter(s: unknown): s is string;
+/**
+ * Predicate: true iff `n` is a valid 1-based row index in `[1, 1048576]`.
+ * Non-finite / non-integer / out-of-bound fails.
+ */
+export declare function isValidRowNumber(n: unknown): n is number;
+/**
+ * Predicate: true iff `n` is a valid 1-based column index in `[1, 16384]`.
+ * Non-finite / non-integer / out-of-bound fails.
+ */
+export declare function isValidColumnNumber(n: unknown): n is number;
+/**
+ * Parse "A1:B5" / "A:A" / "1:1" / single-cell into 1-based (minCol, minRow,
+ * maxCol, maxRow). Whole-column ranges fill rows to [1, MAX_ROW]; whole-row
+ * ranges fill cols to [1, MAX_COL].
+ */
+export declare function rangeBoundaries(range: string): CellRangeBoundaries;
+/** Inverse of {@link rangeBoundaries} for the rectangular case. */
+export declare function boundariesToRangeString(b: CellRangeBoundaries): string;
+/**
+ * Parse a sheet-qualified range ("Sheet1!A1:B5" / "'Quarter 1'!A1"). Sheet
+ * names with single quotes inside use SQL-style doubling ("'Bob''s Sheet'!A1")
+ * — we unescape on the way out.
+ */
+export declare function parseSheetRange(input: string): {
+    sheet: string;
+    range: string;
+    bounds: CellRangeBoundaries;
+};
+/**
+ * Inverse of {@link parseSheetRange}: format a sheet title + range (or
+ * single-cell ref) as `Sheet1!A1` or `'Quarter 1'!A1` per Excel's
+ * sheet-qualified syntax. Single quotes inside the title are escaped by
+ * doubling (`'Bob''s Sheet'`).
+ *
+ * Quoting rule: sheet titles consisting only of `[A-Za-z_][A-Za-z0-9_]*` are
+ * emitted bare; everything else (spaces, digits-leading, hyphens, apostrophes,
+ * punctuation…) gets wrapped in single quotes.
+ */
+export declare function formatSheetQualifiedRef(sheet: string, ref: string): string;

package/dist/utils/css.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Serialize a CSS-property record to an inline-style declaration string
+ * (`prop1: val1; prop2: val2`). Properties are alphabetised so the
+ * output is deterministic across runs.
+ *
+ * - Empty record returns `''`.
+ * - Empty-string values are skipped (treat as "unset").
+ * - Values containing `;` are dropped — they would terminate the
+ *   declaration early and risk attribute-injection in `style="…"`
+ *   contexts. Callers should pre-escape user data; this is a
+ *   defensive last line.
+ *
+ * The returned string is suitable for direct interpolation into an
+ * HTML `style="…"` attribute *after* the usual attribute-value HTML
+ * escaping (no `&` / `"` injection here — this only guards against
+ * stray semicolons).
+ */
+export declare function cssRecordToInlineStyle(record: Record<string, string> | undefined): string;