Add chart sheets to OpenXml export

README_V2.md

@@ -745,6 +745,38 @@ exporter.Export("Book1.xlsx", dt, configuration: config);
 
 ![image](docs/images/freeze-pane-1.png)
 
+#### 14. Chart sheets
+
+A chart sheet holds only a chart. Add an `OpenXmlChartSheet` to the sheets of a workbook, next to the sheets its series read from:
+
+```csharp
+var chart = new OpenXmlChart { Title = "Speed", LegendPosition = OpenXmlChartLegendPosition.Bottom };
+chart.XAxis.Title = "Distance (m)";
+chart.YAxis.Title = "Speed (m/s)";
+chart.Plots.Add(new OpenXmlChartPlot(OpenXmlChartType.ScatterLines)
+{
+    Series =
+    {
+        new OpenXmlChartSeries(OpenXmlChartData.FromRange("Readings", "B2:B500"), OpenXmlChartData.FromRange("Readings", "A2:A500"))
+        {
+            Name = "Speed",
+            Color = Color.Black
+        }
+    }
+});
+
+var sheets = new Dictionary<string, object>
+{
+    ["Readings"] = readings,
+    ["Speed Graph"] = new OpenXmlChartSheet(chart)
+};
+
+var exporter = MiniExcelV2.Exporters.GetOpenXmlExporter();
+exporter.Export("speed.xlsx", sheets);
+```
+
+Series read from a cell range or from literal values (`OpenXmlChartData.FromValues`). A chart can combine several plots, such as stacked columns on the secondary axes behind a line on the primary ones, and each axis can set its title, bounds, number format, label rotation, tick marks and gridlines. Colors with an alpha channel are drawn transparent, and `ShowInLegend = false` leaves a series out of the legend.
+
 
 ### Fill Data To Excel Template <a name="docs-template" />
 

src/MiniExcel.OpenXml/Api/OpenXmlExporter.cs

@@ -1,3 +1,4 @@
+using MiniExcelLib.OpenXml.Charts;
 using MiniExcelLib.OpenXml.Writer;
 
 // ReSharper disable once CheckNamespace
@@ -63,6 +64,9 @@ public async Task<int> InsertSheetAsync(Stream stream, object value, string shee
         bool printHeader = true, bool overwriteSheet = false, OpenXmlConfiguration? configuration = null, 
         IProgress<int>? progress = null, CancellationToken cancellationToken = default)
     {
+        if (value is OpenXmlChartSheet)
+            throw new NotSupportedException("Chart sheets can't be inserted into an existing workbook");
+
         stream.Seek(0, SeekOrigin.End);
         configuration ??= new OpenXmlConfiguration { FastMode = true };
 
@@ -94,6 +98,9 @@ public async Task<int> CopyAndAddSheetAsync(Stream inputStream, Stream outputStr
         bool printHeader = true, bool overwriteSheet = false, OpenXmlConfiguration? configuration = null, 
         IProgress<int>? progress = null, CancellationToken cancellationToken = default)
     {
+        if (value is OpenXmlChartSheet)
+            throw new NotSupportedException("Chart sheets can't be added to a copy of an existing workbook");
+
         var writer = await OpenXmlWriter
             .CreateForCopyAsync(inputStream, outputStream, value, sheetName, printHeader, configuration, cancellationToken)
             .ConfigureAwait(false);

src/MiniExcel.OpenXml/Charts/OpenXmlChart.cs

@@ -0,0 +1,48 @@
+namespace MiniExcelLib.OpenXml.Charts;
+
+/// <summary>
+/// A chart made of one or more plots that share primary and, optionally, secondary axes.
+/// </summary>
+public class OpenXmlChart
+{
+    public string? Title { get; set; }
+
+    /// <summary>
+    /// The title font size in points. When null, Excel picks it.
+    /// </summary>
+    public double? TitleFontSize { get; set; }
+
+    public bool TitleBold { get; set; }
+
+    /// <summary>
+    /// Where the legend is placed. When null, the chart has no legend.
+    /// </summary>
+    public OpenXmlChartLegendPosition? LegendPosition { get; set; } = OpenXmlChartLegendPosition.Right;
+
+    /// <summary>
+    /// The style of the chart border. When null, Excel picks it.
+    /// </summary>
+    public OpenXmlChartLine? Border { get; set; }
+
+    /// <summary>
+    /// The horizontal axis of the primary plots, or the vertical one for bar plots.
+    /// </summary>
+    public OpenXmlChartAxis XAxis { get; } = new();
+
+    /// <summary>
+    /// The value axis of the primary plots.
+    /// </summary>
+    public OpenXmlChartAxis YAxis { get; } = new() { MajorGridlines = new OpenXmlChartLine() };
+
+    /// <summary>
+    /// The category or X axis of the plots on the secondary axes. Hidden unless made visible.
+    /// </summary>
+    public OpenXmlChartAxis SecondaryXAxis { get; } = new() { Visible = false };
+
+    /// <summary>
+    /// The value axis of the plots on the secondary axes, drawn on the opposite side of the primary one.
+    /// </summary>
+    public OpenXmlChartAxis SecondaryYAxis { get; } = new();
+
+    public List<OpenXmlChartPlot> Plots { get; } = [];
+}

src/MiniExcel.OpenXml/Charts/OpenXmlChartAxis.cs

@@ -0,0 +1,50 @@
+namespace MiniExcelLib.OpenXml.Charts;
+
+public class OpenXmlChartAxis
+{
+    /// <summary>
+    /// Whether the axis line, tick marks and labels are drawn. A hidden axis still scales its plots.
+    /// </summary>
+    public bool Visible { get; set; } = true;
+
+    public string? Title { get; set; }
+
+    /// <summary>
+    /// The lowest value on the axis. When null, Excel picks it. Ignored by category axes.
+    /// </summary>
+    public double? Minimum { get; set; }
+
+    /// <summary>
+    /// The highest value on the axis. When null, Excel picks it. Ignored by category axes.
+    /// </summary>
+    public double? Maximum { get; set; }
+
+    /// <summary>
+    /// The distance between major tick marks. When null, Excel picks it. Ignored by category axes.
+    /// </summary>
+    public double? MajorUnit { get; set; }
+
+    /// <summary>
+    /// The number format of the labels, such as <c>#,##0</c>. When null, the labels follow the source data.
+    /// </summary>
+    public string? NumberFormat { get; set; }
+
+    /// <summary>
+    /// The rotation of the labels in degrees from -90 to 90, counterclockwise like in Excel. When null, Excel picks it.
+    /// </summary>
+    public int? LabelRotation { get; set; }
+
+    public OpenXmlChartTickMark MajorTickMark { get; set; } = OpenXmlChartTickMark.Outside;
+
+    public OpenXmlChartTickMark MinorTickMark { get; set; } = OpenXmlChartTickMark.None;
+
+    /// <summary>
+    /// The style of the axis line. When null, Excel picks it.
+    /// </summary>
+    public OpenXmlChartLine? Line { get; set; }
+
+    /// <summary>
+    /// The style of the major gridlines. When null, no gridlines are drawn.
+    /// </summary>
+    public OpenXmlChartLine? MajorGridlines { get; set; }
+}

src/MiniExcel.OpenXml/Charts/OpenXmlChartData.cs

@@ -0,0 +1,81 @@
+namespace MiniExcelLib.OpenXml.Charts;
+
+/// <summary>
+/// The values or categories of a chart series: either a range of cells or literal values stored in the chart itself.
+/// </summary>
+public sealed class OpenXmlChartData
+{
+    private OpenXmlChartData(string? formula, double[]? numbers, string[]? strings)
+    {
+        Formula = formula;
+        Numbers = numbers;
+        Strings = strings;
+    }
+
+    internal string? Formula { get; }
+    internal double[]? Numbers { get; }
+    internal string[]? Strings { get; }
+
+    /// <summary>
+    /// Data read from a range of cells, such as <c>B2:B100</c>, on a sheet of the same workbook.
+    /// </summary>
+    public static OpenXmlChartData FromRange(string sheetName, string range)
+    {
+        if (string.IsNullOrEmpty(range))
+            throw new ArgumentException("The range must not be empty.", nameof(range));
+
+        var cells = range.Split(':');
+        if (cells.Length > 2)
+            throw new ArgumentException($"Value {range} is not a valid cell range.", nameof(range));
+
+        if (!CellReferenceConverter.TryParseCellReference(cells[0], out var firstColumn, out var firstRow) ||
+            !CellReferenceConverter.TryParseCellReference(cells[^1], out var lastColumn, out var lastRow))
+            throw new ArgumentException($"Value {range} is not a valid cell range.", nameof(range));
+
+        return FromRange(sheetName, firstRow, firstColumn, lastRow, lastColumn);
+    }
+
+    /// <summary>
+    /// Data read from a range of cells on a sheet of the same workbook. Rows and columns are 1-based.
+    /// </summary>
+    public static OpenXmlChartData FromRange(string sheetName, int firstRow, int firstColumn, int lastRow, int lastColumn)
+    {
+        if (string.IsNullOrEmpty(sheetName))
+            throw new ArgumentException("The sheet name must not be empty.", nameof(sheetName));
+        if (firstRow < 1 || firstColumn < 1 || lastRow < firstRow || lastColumn < firstColumn)
+            throw new ArgumentOutOfRangeException(nameof(lastRow), "The range must start at row and column 1 or later and must not end before it starts.");
+
+        var first = AbsoluteReference(firstColumn, firstRow);
+        var last = AbsoluteReference(lastColumn, lastRow);
+        var range = first == last ? first : $"{first}:{last}";
+
+        return new OpenXmlChartData($"'{sheetName.Replace("'", "''")}'!{range}", null, null);
+    }
+
+    /// <summary>
+    /// Numbers stored in the chart itself.
+    /// </summary>
+    public static OpenXmlChartData FromValues(params double[] values)
+    {
+        if (values is null or [])
+            throw new ArgumentException("At least one value is required.", nameof(values));
+        if (values.Any(v => double.IsNaN(v) || double.IsInfinity(v)))
+            throw new ArgumentException("Chart values must be finite numbers.", nameof(values));
+
+        return new OpenXmlChartData(null, values, null);
+    }
+
+    /// <summary>
+    /// Text stored in the chart itself, typically category labels.
+    /// </summary>
+    public static OpenXmlChartData FromValues(params string[] values)
+    {
+        if (values is null or [])
+            throw new ArgumentException("At least one value is required.", nameof(values));
+
+        return new OpenXmlChartData(null, null, values);
+    }
+
+    private static string AbsoluteReference(int column, int row)
+        => $"${CellReferenceConverter.GetAlphabeticalIndex(column - 1)}${row}";
+}

src/MiniExcel.OpenXml/Charts/OpenXmlChartEnums.cs

@@ -0,0 +1,36 @@
+namespace MiniExcelLib.OpenXml.Charts;
+
+public enum OpenXmlChartType
+{
+    /// <summary>Points at X and Y values, drawn as markers.</summary>
+    Scatter,
+    /// <summary>Points at X and Y values, joined by straight lines without markers.</summary>
+    ScatterLines,
+    /// <summary>Values at evenly spaced categories, joined by straight lines without markers.</summary>
+    Line,
+    /// <summary>Vertical bars side by side.</summary>
+    Column,
+    /// <summary>Vertical bars stacked on top of each other.</summary>
+    StackedColumn,
+    /// <summary>Horizontal bars side by side.</summary>
+    Bar,
+    /// <summary>Horizontal bars stacked end to end.</summary>
+    StackedBar
+}
+
+public enum OpenXmlChartLegendPosition
+{
+    Right,
+    Left,
+    Top,
+    Bottom,
+    TopRight
+}
+
+public enum OpenXmlChartTickMark
+{
+    None,
+    Inside,
+    Outside,
+    Cross
+}

src/MiniExcel.OpenXml/Charts/OpenXmlChartLine.cs

@@ -0,0 +1,19 @@
+using System.Drawing;
+
+namespace MiniExcelLib.OpenXml.Charts;
+
+/// <summary>
+/// The style of a line in a chart: an axis, gridlines or the chart border.
+/// </summary>
+public class OpenXmlChartLine
+{
+    /// <summary>
+    /// The line color. The alpha channel sets the transparency. When empty, Excel picks the color.
+    /// </summary>
+    public Color Color { get; set; }
+
+    /// <summary>
+    /// The line width in points. When null, Excel picks the width.
+    /// </summary>
+    public double? Width { get; set; }
+}

src/MiniExcel.OpenXml/Charts/OpenXmlChartPlot.cs

@@ -0,0 +1,26 @@
+namespace MiniExcelLib.OpenXml.Charts;
+
+/// <summary>
+/// A group of series drawn the same way on the same axes. A chart with several plots combines them, for example columns
+/// on the secondary axes behind a line on the primary axes.
+/// </summary>
+public class OpenXmlChartPlot(OpenXmlChartType type)
+{
+    public OpenXmlChartType Type { get; } = type;
+
+    /// <summary>
+    /// Whether the plot uses the secondary axes of the chart instead of the primary ones.
+    /// </summary>
+    public bool UseSecondaryAxes { get; set; }
+
+    /// <summary>
+    /// The gap between column or bar clusters as a percentage of the bar width, from 0 to 500. Ignored by other plots.
+    /// </summary>
+    public int GapWidth { get; set; } = 150;
+
+    public List<OpenXmlChartSeries> Series { get; } = [];
+
+    internal bool IsScatter => Type is OpenXmlChartType.Scatter or OpenXmlChartType.ScatterLines;
+
+    internal bool IsBar => Type is OpenXmlChartType.Column or OpenXmlChartType.StackedColumn or OpenXmlChartType.Bar or OpenXmlChartType.StackedBar;
+}

src/MiniExcel.OpenXml/Charts/OpenXmlChartSeries.cs

@@ -0,0 +1,36 @@
+using System.Drawing;
+
+namespace MiniExcelLib.OpenXml.Charts;
+
+/// <summary>
+/// One series of a chart plot.
+/// </summary>
+/// <param name="values">The values of the series: the Y values of a scatter plot, or the bar heights and line points of the other plots.</param>
+/// <param name="categories">The X values of a scatter plot, or the category labels of the other plots. When omitted, points are numbered from 1.</param>
+public class OpenXmlChartSeries(OpenXmlChartData values, OpenXmlChartData? categories = null)
+{
+    public OpenXmlChartData Values { get; } = values ?? throw new ArgumentNullException(nameof(values));
+
+    public OpenXmlChartData? Categories { get; } = categories;
+
+    /// <summary>
+    /// The name shown in the legend.
+    /// </summary>
+    public string? Name { get; set; }
+
+    /// <summary>
+    /// The line color of scatter and line series, or the fill color of column and bar series. The alpha channel sets
+    /// the transparency. When empty, Excel picks the color.
+    /// </summary>
+    public Color Color { get; set; }
+
+    /// <summary>
+    /// The line width in points, for scatter and line series. When null, Excel picks the width.
+    /// </summary>
+    public double? LineWidth { get; set; }
+
+    /// <summary>
+    /// Whether the series has an entry in the legend.
+    /// </summary>
+    public bool ShowInLegend { get; set; } = true;
+}

src/MiniExcel.OpenXml/Charts/OpenXmlChartSheet.cs

@@ -0,0 +1,9 @@
+namespace MiniExcelLib.OpenXml.Charts;
+
+/// <summary>
+/// A sheet that holds only a chart. Export it as one of the sheets of a workbook, next to the sheets with its data.
+/// </summary>
+public class OpenXmlChartSheet(OpenXmlChart chart)
+{
+    public OpenXmlChart Chart { get; } = chart ?? throw new ArgumentNullException(nameof(chart));
+}

src/MiniExcel.OpenXml/Constants/ExcelContentTypes.cs

@@ -5,6 +5,8 @@ internal static class ExcelContentTypes
     internal const string Relationships = "application/vnd.openxmlformats-package.relationships+xml";
     internal const string Workbook = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml";
     internal const string Worksheet = "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml";
+    internal const string ChartSheet = "application/vnd.openxmlformats-officedocument.spreadsheetml.chartsheet+xml";
+    internal const string Chart = "application/vnd.openxmlformats-officedocument.drawingml.chart+xml";
     internal const string SharedStrings = "application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml";
     internal const string Styles = "application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml";
     internal const string Drawing = "application/vnd.openxmlformats-officedocument.drawing+xml";

src/MiniExcel.OpenXml/Constants/ExcelFileNames.cs

@@ -16,6 +16,9 @@ internal static class ExcelFileNames
 
     internal static string Worksheet(int sheetId) => $"xl/worksheets/sheet{sheetId}.xml";
     internal static string SheetRels(int sheetId) => $"xl/worksheets/_rels/sheet{sheetId}.xml.rels";
+    internal static string ChartSheet(int sheetId) => $"xl/chartsheets/sheet{sheetId}.xml";
+    internal static string ChartSheetRels(int sheetId) => $"xl/chartsheets/_rels/sheet{sheetId}.xml.rels";
+    internal static string Chart(int chartIndex) => $"xl/charts/chart{chartIndex}.xml";
     internal static string Drawing(int sheetIndex) => $"xl/drawings/drawing{sheetIndex}.xml";
     internal static string DrawingRels(int sheetIndex) => $"xl/drawings/_rels/drawing{sheetIndex}.xml.rels";
     internal static string DrawingRels(string drawingFileName) => $"xl/drawings/_rels/{drawingFileName}.rels";