Add workbook formatting and scoped XLSX templates

Author: KSemenenko

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to ManagedCode.FileContext are documented here.
 
+## 1.0.16
+
+- Add optional workbook header styling, Excel number formats, column widths and frozen headers.
+- Support scoped macro-free XLSX templates while retaining styles, layout and untouched sheets.
+- Validate workbook style fields against the Excel format and preserve formula/value semantics.
+
 ## 1.0.14
 
 - Stage seekable cloud PDF streams asynchronously to bounded temporary files before synchronous parser reads and seeks.

Directory.Build.props

@@ -12,7 +12,7 @@
     <AnalysisMode>Recommended</AnalysisMode>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <NoWarn>$(NoWarn);CS1591;MAAI001</NoWarn>
-    <Version>1.0.15</Version>
+    <Version>1.0.16</Version>
     <PackageVersion>$(Version)</PackageVersion>
   </PropertyGroup>
 

docs/Features/file-context.md

@@ -129,3 +129,26 @@ document into one model call. The tool does not execute macros, fetch external l
 OCR on embedded images. Generic text reads refuse DOCX, and text search skips it.
 
 `file_context_pdf_text` reports a bounded text-layer prefix, total page count, and one-based pages with almost no text. It performs no OCR. `file_context_pdf_page_image` renders a complete page as PNG. `file_context_pdf_images_info` counts embedded image objects, and `file_context_pdf_image` returns one object as PNG. The direct `IFileContextPdf` methods and public byte-oriented PDF APIs support the same operations. Storage-scoped PDF reads enforce a byte cap; page rendering enforces pixel and image-byte caps. Image tools return `DataContent`; host chat pipelines must forward it as image content rather than stringify a function result.
+
+## Workbook styling and templates
+
+`FileContextWorkbook` accepts an optional `TemplatePath` for an existing macro-free
+`.xlsx` in the same authorized storage scope. Each supplied sheet replaces that
+sheet's cell values/formulas, inherits existing cell styles by Excel coordinates,
+and keeps its layout and other package parts; sheets not supplied are retained.
+The template is never modified. A new unique output file is created.
+
+Each worksheet has an optional `Style` object: `BoldHeader`, `HeaderFill` (`#RRGGBB`),
+`FreezeHeader`, `NumberFormats` and `ColumnWidths`. Dictionary keys are one-based
+Excel column numbers. Formats are Excel codes such as `$#,##0.00`, `0.0%`, and
+`yyyy-mm-dd`; date values use Excel serial numbers. Widths use Excel character
+units (positive, maximum 255). These are XLSX format contracts, not app limits.
+Formulas remain explicit and are calculated by Excel. New data starts at A1.
+
+```mermaid
+flowchart LR
+    Scope[Authorized FileContext] --> Template[Optional XLSX template]
+    Template --> Writer[OOXML writer and styles]
+    Input[Typed sheets and values] --> Writer
+    Writer --> New[New scoped workbook]
+```

src/ManagedCode.FileContext/Documents/Contracts/FileContextWorkbook.cs

@@ -1,3 +1,7 @@
 namespace ManagedCode.FileContext;
 
-public sealed record FileContextWorkbook(IReadOnlyList<FileContextWorksheet> Sheets);
+public sealed record FileContextWorkbook(IReadOnlyList<FileContextWorksheet> Sheets)
+{
+    /// <summary>Optional existing .xlsx in this exact authorized file scope.</summary>
+    public string? TemplatePath { get; init; }
+}

src/ManagedCode.FileContext/Documents/Contracts/FileContextWorksheet.cs

@@ -1,3 +1,6 @@
 namespace ManagedCode.FileContext;
 
-public sealed record FileContextWorksheet(string Name, IReadOnlyList<IReadOnlyList<FileContextSpreadsheetCell>> Rows);
+public sealed record FileContextWorksheet(string Name, IReadOnlyList<IReadOnlyList<FileContextSpreadsheetCell>> Rows)
+{
+    public FileContextWorksheetStyle? Style { get; init; }
+}

src/ManagedCode.FileContext/Documents/Contracts/FileContextWorksheetStyle.cs

@@ -0,0 +1,11 @@
+namespace ManagedCode.FileContext;
+
+/// <summary>Column dictionaries use one-based Excel column numbers. Number formats use Excel format codes.</summary>
+public sealed record FileContextWorksheetStyle
+{
+    public bool BoldHeader { get; init; }
+    public string? HeaderFill { get; init; }
+    public bool FreezeHeader { get; init; }
+    public IReadOnlyDictionary<int, string> NumberFormats { get; init; } = new Dictionary<int, string>();
+    public IReadOnlyDictionary<int, double> ColumnWidths { get; init; } = new Dictionary<int, double>();
+}

src/ManagedCode.FileContext/Documents/FileContextDocumentService.cs

@@ -15,9 +15,23 @@ public Task<FileContextCreatedFile> CreateCsvAsync(string fileName, FileContextC
         CreateAsync(RequireExtension(fileName, ".csv"), "text/csv; charset=utf-8",
             token => FileContextCsvWriter.Create(document, token), cancellationToken);
 
-    public Task<FileContextCreatedFile> CreateWorkbookAsync(string fileName, FileContextWorkbook workbook, CancellationToken cancellationToken = default) =>
-        CreateAsync(RequireExtension(fileName, ".xlsx"), "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-            token => FileContextWorkbookWriter.Create(workbook, token), cancellationToken);
+    public async Task<FileContextCreatedFile> CreateWorkbookAsync(string fileName, FileContextWorkbook workbook, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(workbook);
+        options.Validate();
+        if (!options.EnableWriteTools) { throw new InvalidOperationException("Document creation requires EnableWriteTools."); }
+        byte[]? template = null;
+        if (workbook.TemplatePath is { } path)
+        {
+            RequireExtension(path, ".xlsx");
+            using var source = await store.OpenReadAsync(path, cancellationToken).ConfigureAwait(false);
+            using var buffer = new MemoryStream();
+            await source.CopyToAsync(buffer, cancellationToken).ConfigureAwait(false);
+            template = buffer.ToArray();
+        }
+        return await CreateAsync(RequireExtension(fileName, ".xlsx"), "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+            token => FileContextWorkbookWriter.Create(workbook, template, token), cancellationToken).ConfigureAwait(false);
+    }
 
     public Task<FileContextCreatedFile> CreatePdfAsync(string fileName, FileContextPdfDocument document, CancellationToken cancellationToken = default) =>
         CreateAsync(RequireExtension(fileName, ".pdf"), "application/pdf",

src/ManagedCode.FileContext/Documents/Generation/FileContextWorkbookStyles.cs

@@ -0,0 +1,117 @@
+using DocumentFormat.OpenXml.Packaging;
+using DocumentFormat.OpenXml.Spreadsheet;
+
+namespace ManagedCode.FileContext;
+
+internal sealed class FileContextWorkbookStyles(WorkbookPart workbook)
+{
+    private const uint SystemBackgroundColor = 64;
+    private const uint LastBuiltInNumberFormat = 163;
+    private const int MaximumColumns = 16384;
+    private const int MaximumColumnWidth = 255;
+    private const int HexColorLength = 7;
+    private readonly Dictionary<(bool Bold, string? Fill, string? Format), uint> cache = [];
+
+    public uint Style(FileContextWorksheetStyle style, int row, int column)
+    {
+        var key = (row == 0 && style.BoldHeader, row == 0 ? style.HeaderFill : null,
+            row == 0 ? null : style.NumberFormats.GetValueOrDefault(column));
+        if (key == (false, null, null)) { return 0; }
+        if (cache.TryGetValue(key, out var existing)) { return existing; }
+        var sheet = EnsureStyles();
+        uint font = 0, fill = 0, format = 0;
+        if (key.Item1)
+        {
+            font = (uint)sheet.Fonts!.ChildElements.Count;
+            sheet.Fonts.AppendChild(new Font { Bold = new Bold() });
+        }
+        if (key.Item2 is { } color)
+        {
+            if (color.Length != HexColorLength || color[0] != '#' || color.Skip(1).Any(c => !Uri.IsHexDigit(c)))
+            { throw new ArgumentException("HeaderFill must be #RRGGBB.", nameof(style)); }
+            fill = (uint)sheet.Fills!.ChildElements.Count;
+            sheet.Fills.AppendChild(new Fill
+            {
+                PatternFill = new PatternFill
+                {
+                    ForegroundColor = new ForegroundColor { Rgb = "FF" + color[1..] },
+                    BackgroundColor = new BackgroundColor { Indexed = SystemBackgroundColor },
+                    PatternType = PatternValues.Solid
+                }
+            });
+        }
+        if (key.Item3 is { } code)
+        {
+            if (string.IsNullOrWhiteSpace(code)) { throw new ArgumentException("Number format cannot be empty.", nameof(style)); }
+            format = Math.Max(LastBuiltInNumberFormat, sheet.NumberingFormats!.Elements<NumberingFormat>()
+                .Select(item => item.NumberFormatId!.Value).DefaultIfEmpty(LastBuiltInNumberFormat).Max()) + 1;
+            sheet.NumberingFormats.AppendChild(new NumberingFormat { NumberFormatId = format, FormatCode = code });
+        }
+        var index = (uint)sheet.CellFormats!.ChildElements.Count;
+        sheet.CellFormats.AppendChild(new CellFormat
+        {
+            FontId = font,
+            FillId = fill,
+            BorderId = 0,
+            FormatId = 0,
+            NumberFormatId = format,
+            ApplyFont = key.Item1,
+            ApplyFill = fill != 0,
+            ApplyNumberFormat = format != 0
+        });
+        sheet.Fonts!.Count = (uint)sheet.Fonts.ChildElements.Count;
+        sheet.Fills!.Count = (uint)sheet.Fills.ChildElements.Count;
+        sheet.NumberingFormats!.Count = (uint)sheet.NumberingFormats.ChildElements.Count;
+        sheet.CellFormats.Count = (uint)sheet.CellFormats.ChildElements.Count;
+        cache[key] = index;
+        return index;
+    }
+
+    public static void Layout(Worksheet sheet, FileContextWorksheetStyle style)
+    {
+        if (style.NumberFormats.Keys.Concat(style.ColumnWidths.Keys).Any(column => column is < 1 or > MaximumColumns))
+        { throw new ArgumentException("Style columns must be one-based Excel columns 1 through 16384.", nameof(style)); }
+        if (style.FreezeHeader)
+        {
+            var views = sheet.GetFirstChild<SheetViews>() ?? sheet.InsertAt(new SheetViews(), 0);
+            var view = views.Elements<SheetView>().FirstOrDefault() ?? views.AppendChild(new SheetView { WorkbookViewId = 0 });
+            view.RemoveAllChildren<Pane>();
+            view.PrependChild(new Pane { VerticalSplit = 1, TopLeftCell = "A2", ActivePane = PaneValues.BottomLeft, State = PaneStateValues.Frozen });
+        }
+        if (style.ColumnWidths.Count == 0) { return; }
+        var columns = sheet.GetFirstChild<Columns>();
+        if (columns is null)
+        {
+            columns = new Columns();
+            sheet.InsertBefore(columns, sheet.GetFirstChild<SheetData>());
+        }
+        foreach (var (column, width) in style.ColumnWidths.OrderBy(pair => pair.Key))
+        {
+            if (!double.IsFinite(width) || width <= 0 || width > MaximumColumnWidth)
+            { throw new ArgumentException("Column widths must be positive and at most Excel's 255 characters.", nameof(style)); }
+            // A template's overlapping range is split so unrelated widths remain intact.
+            foreach (var prior in columns.Elements<Column>().Where(item => item.Min!.Value <= column && item.Max!.Value >= column).ToArray())
+            {
+                if (prior.Min!.Value < column)
+                { var left = (Column)prior.CloneNode(true); left.Max = (uint)column - 1; columns.InsertBefore(left, prior); }
+                if (prior.Max!.Value > column)
+                { var right = (Column)prior.CloneNode(true); right.Min = (uint)column + 1; columns.InsertAfter(right, prior); }
+                prior.Remove();
+            }
+            columns.AppendChild(new Column { Min = (uint)column, Max = (uint)column, Width = width, CustomWidth = true });
+        }
+    }
+
+    private Stylesheet EnsureStyles()
+    {
+        var part = workbook.WorkbookStylesPart ?? workbook.AddNewPart<WorkbookStylesPart>();
+        var sheet = part.Stylesheet ??= new Stylesheet();
+        if (sheet.NumberingFormats is null) { sheet.NumberingFormats = new NumberingFormats(); }
+        if (sheet.Fonts is null) { sheet.Fonts = new Fonts(); sheet.Fonts.AppendChild(new Font()); }
+        if (sheet.Fills is null) { sheet.Fills = new Fills(new Fill { PatternFill = new PatternFill { PatternType = PatternValues.None } }, new Fill { PatternFill = new PatternFill { PatternType = PatternValues.Gray125 } }); }
+        if (sheet.Borders is null) { sheet.Borders = new Borders(); sheet.Borders.AppendChild(new Border()); }
+        if (sheet.CellStyleFormats is null) { sheet.CellStyleFormats = new CellStyleFormats(); sheet.CellStyleFormats.AppendChild(new CellFormat()); }
+        if (sheet.CellFormats is null) { sheet.CellFormats = new CellFormats(); sheet.CellFormats.AppendChild(new CellFormat()); }
+        return sheet;
+    }
+}

src/ManagedCode.FileContext/Documents/Generation/FileContextWorkbookWriter.cs

@@ -12,36 +12,86 @@ internal static class FileContextWorkbookWriter
     private const int MaximumColumns = 16_384;
     private const int MaximumCellTextLength = 32_767;
 
-    public static byte[] Create(FileContextWorkbook workbook, CancellationToken cancellationToken)
+    public static byte[] Create(FileContextWorkbook workbook, byte[]? template, CancellationToken cancellationToken)
     {
         ArgumentNullException.ThrowIfNull(workbook);
         if (workbook.Sheets is null) { throw new ArgumentException("Workbook sheets are required.", nameof(workbook)); }
         if (workbook.Sheets.Count == 0) { throw new ArgumentException("A workbook needs at least one sheet.", nameof(workbook)); }
         using var stream = new MemoryStream();
-        using (var document = SpreadsheetDocument.Create(stream, SpreadsheetDocumentType.Workbook))
+        if (template is not null) { stream.Write(template); stream.Position = 0; }
+        using (var document = template is null ? SpreadsheetDocument.Create(stream, SpreadsheetDocumentType.Workbook) : SpreadsheetDocument.Open(stream, true))
         {
-            var part = document.AddWorkbookPart();
-            part.Workbook = new Workbook { Sheets = new Sheets() };
+            if (document.DocumentType != SpreadsheetDocumentType.Workbook)
+            { throw new ArgumentException("Template must be a macro-free XLSX workbook.", nameof(template)); }
+            var part = document.WorkbookPart ?? document.AddWorkbookPart();
+            part.Workbook ??= new Workbook { Sheets = new Sheets() };
             var names = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            var styles = new FileContextWorkbookStyles(part);
             foreach (var sheet in workbook.Sheets)
             {
                 cancellationToken.ThrowIfCancellationRequested();
                 ValidateSheet(sheet, names);
-                var worksheet = part.AddNewPart<WorksheetPart>();
-                worksheet.Worksheet = new Worksheet();
-                worksheet.Worksheet.AppendChild(CreateRows(sheet.Rows, cancellationToken));
-                part.Workbook.GetFirstChild<Sheets>()!.AppendChild(new Sheet
-                {
-                    Id = part.GetIdOfPart(worksheet),
-                    SheetId = (uint)names.Count,
-                    Name = sheet.Name
-                });
+                WriteSheet(part, sheet, styles, cancellationToken);
             }
             part.Workbook.Save();
         }
         return stream.ToArray();
     }
 
+    private static void WriteSheet(WorkbookPart part, FileContextWorksheet sheet, FileContextWorkbookStyles styles, CancellationToken token)
+    {
+        if (sheet.Style is { } requestedStyle &&
+            (requestedStyle.NumberFormats is null || requestedStyle.ColumnWidths is null))
+        { throw new ArgumentException("Style numberFormats and columnWidths must be objects.", nameof(sheet)); }
+        var sheets = part.Workbook!.GetFirstChild<Sheets>() ?? part.Workbook.AppendChild(new Sheets());
+        var existing = sheets.Elements<Sheet>().FirstOrDefault(item => string.Equals(item.Name, sheet.Name, StringComparison.OrdinalIgnoreCase));
+        var worksheet = existing is null ? part.AddNewPart<WorksheetPart>() : (WorksheetPart)part.GetPartById(existing.Id!);
+        worksheet.Worksheet ??= new Worksheet();
+        var prior = worksheet.Worksheet.GetFirstChild<SheetData>();
+        var data = CreateRows(sheet.Rows, sheet.Style, styles, token);
+        if (prior is null) { worksheet.Worksheet.AppendChild(data); }
+        else
+        {
+            InheritStyles(data, prior);
+            worksheet.Worksheet.ReplaceChild(data, prior);
+        }
+        if (sheet.Style is { } style) { FileContextWorkbookStyles.Layout(worksheet.Worksheet, style); }
+        if (existing is null)
+        {
+            var nextId = sheets.Elements<Sheet>().Select(item => item.SheetId!.Value).DefaultIfEmpty(0U).Max() + 1;
+            sheets.AppendChild(new Sheet { Id = part.GetIdOfPart(worksheet), SheetId = nextId, Name = sheet.Name });
+        }
+        worksheet.Worksheet.Save();
+    }
+
+    private static void InheritStyles(SheetData data, SheetData prior)
+    {
+        var inherited = new Dictionary<(uint Row, int Column), uint>();
+        uint rowNumber = 0;
+        foreach (var row in prior.Elements<Row>())
+        {
+            rowNumber = row.RowIndex?.Value ?? rowNumber + 1;
+            var column = 0;
+            foreach (var cell in row.Elements<Cell>())
+            {
+                column = cell.CellReference is null ? column + 1 : FileContextWorkbookReader.ReadColumn(cell.CellReference.Value!);
+                if (cell.StyleIndex is { } style) { inherited[(rowNumber, column)] = style.Value; }
+            }
+        }
+        rowNumber = 0;
+        foreach (var row in data.Elements<Row>())
+        {
+            rowNumber++;
+            var column = 0;
+            foreach (var cell in row.Elements<Cell>())
+            {
+                column++;
+                if (cell.StyleIndex is null && inherited.TryGetValue((rowNumber, column), out var style))
+                { cell.StyleIndex = style; }
+            }
+        }
+    }
+
     private static void ValidateSheet(FileContextWorksheet sheet, HashSet<string> names)
     {
         ArgumentNullException.ThrowIfNull(sheet);
@@ -55,15 +105,25 @@ private static void ValidateSheet(FileContextWorksheet sheet, HashSet<string> na
         if (sheet.Rows.Count > MaximumRows) { throw new ArgumentException("A sheet exceeds Excel's row limit.", nameof(sheet)); }
     }
 
-    private static SheetData CreateRows(IReadOnlyList<IReadOnlyList<FileContextSpreadsheetCell>> rows, CancellationToken token)
+    private static SheetData CreateRows(IReadOnlyList<IReadOnlyList<FileContextSpreadsheetCell>> rows, FileContextWorksheetStyle? style, FileContextWorkbookStyles styles, CancellationToken token)
     {
         var data = new SheetData();
+        var rowIndex = 0;
         foreach (var values in rows)
         {
             token.ThrowIfCancellationRequested();
             if (values is null) { throw new ArgumentException("A row must contain a cell list.", nameof(rows)); }
             if (values.Count > MaximumColumns) { throw new ArgumentException("A row exceeds Excel's column limit.", nameof(rows)); }
-            data.AppendChild(new Row(values.Select(CreateCell)));
+            var row = new Row();
+            for (var column = 0; column < values.Count; column++)
+            {
+                var cell = CreateCell(values[column]);
+                if (style is not null && styles.Style(style, rowIndex, column + 1) is var index && index != 0)
+                { cell.StyleIndex = index; }
+                row.AppendChild(cell);
+            }
+            data.AppendChild(row);
+            rowIndex++;
         }
         return data;
     }