@js-ak/excel-toolbox 1.4.0 → 1.4.1

package/build/esm/lib/template/utils/process-rows.js

@@ -0,0 +1,157 @@
+/**
+ * Processes a sheet XML by replacing table placeholders with real data and adjusting row numbers accordingly.
+ *
+ * @param data - An object containing the following properties:
+ *   - `replacements`: An object where keys are table names and values are arrays of objects with table data.
+ *   - `sharedIndexMap`: A Map of shared string indexes by their text content.
+ *   - `mergeCellMatches`: An array of objects with `from` and `to` properties, describing the merge cells.
+ *   - `sharedStrings`: An array of shared strings.
+ *   - `sheetMergeCells`: An array of merge cell XML strings.
+ *   - `sheetXml`: The sheet XML string.
+ *
+ * @returns An object with the following properties:
+ *   - `lastIndex`: The last processed position in the sheet XML.
+ *   - `resultRows`: An array of processed XML rows.
+ *   - `rowShift`: The total row shift.
+ */
+export function processRows(data) {
+    const { mergeCellMatches, replacements, sharedIndexMap, sharedStrings, sheetMergeCells, sheetXml, } = data;
+    const TABLE_REGEX = /\$\{table:([a-zA-Z0-9_]+)\.([a-zA-Z0-9_]+)\}/g;
+    // Array for storing resulting XML rows
+    const resultRows = [];
+    // Previous position of processed part of XML
+    let lastIndex = 0;
+    // Shift for row numbers
+    let rowShift = 0;
+    // Regular expression for finding <row> elements
+    const rowRegex = /<row[^>]*?>[\s\S]*?<\/row>/g;
+    // Process each <row> element
+    for (const match of sheetXml.matchAll(rowRegex)) {
+        // Full XML row
+        const fullRow = match[0];
+        // Start position of the row in XML
+        const matchStart = match.index;
+        // End position of the row in XML
+        const matchEnd = matchStart + fullRow.length;
+        // Add the intermediate XML chunk (if any) between the previous and the current row
+        if (lastIndex !== matchStart) {
+            resultRows.push(sheetXml.slice(lastIndex, matchStart));
+        }
+        lastIndex = matchEnd;
+        // Get row number from r attribute
+        const originalRowNumber = parseInt(fullRow.match(/<row[^>]* r="(\d+)"/)?.[1] ?? "1", 10);
+        // Update row number based on rowShift
+        const shiftedRowNumber = originalRowNumber + rowShift;
+        // Find shared string indexes in cells of the current row
+        const sharedValueIndexes = [];
+        // Regular expression for finding a cell
+        const cellRegex = /<c[^>]*?r="([A-Z]+\d+)"[^>]*?>([\s\S]*?)<\/c>/g;
+        for (const cell of fullRow.matchAll(cellRegex)) {
+            const cellTag = cell[0];
+            // Check if the cell is a shared string
+            const isShared = /t="s"/.test(cellTag);
+            const valueMatch = cellTag.match(/<v>(\d+)<\/v>/);
+            if (isShared && valueMatch) {
+                sharedValueIndexes.push(parseInt(valueMatch[1], 10));
+            }
+        }
+        // Get the text content of shared strings by their indexes
+        const sharedTexts = sharedValueIndexes.map(i => sharedStrings[i]?.replace(/<\/?si>/g, "") ?? "");
+        // Find table placeholders in shared strings
+        const tablePlaceholders = sharedTexts.flatMap(e => [...e.matchAll(TABLE_REGEX)]);
+        // If there are no table placeholders, just shift the row
+        if (tablePlaceholders.length === 0) {
+            const updatedRow = fullRow
+                .replace(/(<row[^>]* r=")(\d+)(")/, `$1${shiftedRowNumber}$3`)
+                .replace(/<c r="([A-Z]+)(\d+)"/g, (_, col) => `<c r="${col}${shiftedRowNumber}"`);
+            resultRows.push(updatedRow);
+            // Update mergeCells for regular row with rowShift
+            const calculatedRowNumber = originalRowNumber + rowShift;
+            for (const { from, to } of mergeCellMatches) {
+                const [, fromCol, fromRow] = from.match(/^([A-Z]+)(\d+)$/);
+                const [, toCol] = to.match(/^([A-Z]+)(\d+)$/);
+                if (Number(fromRow) === calculatedRowNumber) {
+                    const newFrom = `${fromCol}${shiftedRowNumber}`;
+                    const newTo = `${toCol}${shiftedRowNumber}`;
+                    sheetMergeCells.push(`<mergeCell ref="${newFrom}:${newTo}"/>`);
+                }
+            }
+            continue;
+        }
+        // Get the table name from the first placeholder
+        const firstMatch = tablePlaceholders[0];
+        const tableName = firstMatch?.[1];
+        if (!tableName)
+            throw new Error("Table name not found");
+        // Get data for replacement from replacements
+        const array = replacements[tableName];
+        if (!array)
+            continue;
+        if (!Array.isArray(array))
+            throw new Error("Table data is not an array");
+        const tableRowStart = shiftedRowNumber;
+        // Find mergeCells to duplicate (mergeCells that start with the current row)
+        const mergeCellsToDuplicate = mergeCellMatches.filter(({ from }) => {
+            const match = from.match(/^([A-Z]+)(\d+)$/);
+            if (!match)
+                return false;
+            // Row number of the merge cell start position is in the second group
+            const rowNumber = match[2];
+            return Number(rowNumber) === tableRowStart;
+        });
+        // Change the current row to multiple rows from the data array
+        for (let i = 0; i < array.length; i++) {
+            const rowData = array[i];
+            let newRow = fullRow;
+            // Replace placeholders in shared strings with real data
+            sharedValueIndexes.forEach((originalIdx, idx) => {
+                const originalText = sharedTexts[idx];
+                if (!originalText)
+                    throw new Error("Shared value not found");
+                // Replace placeholders ${tableName.field} with real data from array data
+                const replacedText = originalText.replace(TABLE_REGEX, (_, tbl, field) => tbl === tableName ? String(rowData?.[field] ?? "") : "");
+                // Add new text to shared strings if it doesn't exist
+                let newIndex;
+                if (sharedIndexMap.has(replacedText)) {
+                    newIndex = sharedIndexMap.get(replacedText);
+                }
+                else {
+                    newIndex = sharedStrings.length;
+                    sharedIndexMap.set(replacedText, newIndex);
+                    sharedStrings.push(`<si>${replacedText}</si>`);
+                }
+                // Replace the shared string index in the cell
+                newRow = newRow.replace(`<v>${originalIdx}</v>`, `<v>${newIndex}</v>`);
+            });
+            // Update row number and cell references
+            const newRowNum = shiftedRowNumber + i;
+            newRow = newRow
+                .replace(/<row[^>]* r="\d+"/, rowTag => rowTag.replace(/r="\d+"/, `r="${newRowNum}"`))
+                .replace(/<c r="([A-Z]+)\d+"/g, (_, col) => `<c r="${col}${newRowNum}"`);
+            resultRows.push(newRow);
+            // Add duplicate mergeCells for new rows
+            for (const { from, to } of mergeCellsToDuplicate) {
+                const [, colFrom, rowFrom] = from.match(/^([A-Z]+)(\d+)$/);
+                const [, colTo, rowTo] = to.match(/^([A-Z]+)(\d+)$/);
+                const newFrom = `${colFrom}${Number(rowFrom) + i}`;
+                const newTo = `${colTo}${Number(rowTo) + i}`;
+                sheetMergeCells.push(`<mergeCell ref="${newFrom}:${newTo}"/>`);
+            }
+        }
+        // It increases the row shift by the number of added rows minus one replaced
+        rowShift += array.length - 1;
+        const delta = array.length - 1;
+        const calculatedRowNumber = originalRowNumber + rowShift - array.length + 1;
+        if (delta > 0) {
+            for (const merge of mergeCellMatches) {
+                const fromRow = parseInt(merge.from.match(/\d+$/)[0], 10);
+                if (fromRow > calculatedRowNumber) {
+                    merge.from = merge.from.replace(/\d+$/, r => `${parseInt(r) + delta}`);
+                    merge.to = merge.to.replace(/\d+$/, r => `${parseInt(r) + delta}`);
+                }
+            }
+        }
+    }
+    return { lastIndex, resultRows, rowShift };
+}
+;

package/build/esm/lib/template/utils/process-shared-strings.js

@@ -0,0 +1,42 @@
+import { extractXmlDeclaration } from "./extract-xml-declaration.js";
+/**
+ * Processes the shared strings XML by extracting the XML declaration,
+ * extracting individual <si> elements, and storing them in an array.
+ *
+ * The function returns an object with four properties:
+ * - sharedIndexMap: A map of shared string content to their corresponding index
+ * - sharedStrings: An array of shared strings
+ * - sharedStringsHeader: The XML declaration of the shared strings
+ * - sheetMergeCells: An empty array, which is only used for type compatibility
+ *                    with the return type of processBuild.
+ *
+ * @param sharedStringsXml - The XML string of the shared strings
+ * @returns An object with the four properties above
+ */
+export function processSharedStrings(sharedStringsXml) {
+    // Final list of merged cells with all changes
+    const sheetMergeCells = [];
+    // Array for storing shared strings
+    const sharedStrings = [];
+    const sharedStringsHeader = extractXmlDeclaration(sharedStringsXml);
+    // Map for fast lookup of shared string index by content
+    const sharedIndexMap = new Map();
+    // Regular expression for finding <si> elements (shared string items)
+    const siRegex = /<si>([\s\S]*?)<\/si>/g;
+    // Parse sharedStringsXml and fill sharedStrings and sharedIndexMap
+    for (const match of sharedStringsXml.matchAll(siRegex)) {
+        const content = match[1];
+        if (!content)
+            continue;
+        const fullSi = `<si>${content}</si>`;
+        sharedIndexMap.set(content, sharedStrings.length);
+        sharedStrings.push(fullSi);
+    }
+    return {
+        sharedIndexMap,
+        sharedStrings,
+        sharedStringsHeader,
+        sheetMergeCells,
+    };
+}
+;

package/build/esm/lib/template/utils/to-excel-column-object.js

@@ -1,3 +1,4 @@
+import { columnIndexToLetter } from "./column-index-to-letter.js";
 /**
  * Converts an array of values into a Record<string, string> with Excel column names as keys.
  *
@@ -8,18 +9,9 @@
  * @returns The resulting Record<string, string>
  */
 export function toExcelColumnObject(values) {
-    const toExcelColumn = (index) => {
-        let column = "";
-        let i = index;
-        while (i >= 0) {
-            column = String.fromCharCode((i % 26) + 65) + column;
-            i = Math.floor(i / 26) - 1;
-        }
-        return column;
-    };
     const result = {};
     for (let i = 0; i < values.length; i++) {
-        const key = toExcelColumn(i);
+        const key = columnIndexToLetter(i);
         result[key] = String(values[i]);
     }
     return result;

package/build/esm/lib/template/utils/validate-worksheet-xml.js

@@ -1,19 +1,32 @@
+/**
+ * Validates an Excel worksheet XML against the expected structure and rules.
+ *
+ * Checks the following:
+ * 1. XML starts with <?xml declaration
+ * 2. Root element is worksheet
+ * 3. Required elements are present
+ * 4. row numbers are in ascending order
+ * 5. No duplicate row numbers
+ * 6. No overlapping merge ranges
+ * 7. All cells are within the specified dimension
+ * 8. All mergeCell tags refer to existing cells
+ *
+ * @param xml The raw XML content of the worksheet
+ * @returns A ValidationResult object indicating if the XML is valid, and an error message if it's not
+ */
 export function validateWorksheetXml(xml) {
     const createError = (message, details) => ({
-        error: {
-            details,
-            message,
-        },
+        error: { details, message },
         isValid: false,
     });
-    // 1. Проверка базовой структуры XML
+    // 1. Check for XML declaration
     if (!xml.startsWith("<?xml")) {
-        return createError("XML должен начинаться с декларации <?xml>");
+        return createError("XML must start with <?xml> declaration");
     }
     if (!xml.includes("<worksheet") || !xml.includes("</worksheet>")) {
-        return createError("Не найден корневой элемент worksheet");
+        return createError("Root element worksheet not found");
     }
-    // 2. Проверка наличия обязательных элементов
+    // 2. Check for required elements
     const requiredElements = [
         { name: "sheetViews", tag: "<sheetViews>" },
         { name: "sheetFormatPr", tag: "<sheetFormatPr" },
@@ -23,59 +36,59 @@ export function validateWorksheetXml(xml) {
     ];
     for (const { name, tag } of requiredElements) {
         if (!xml.includes(tag)) {
-            return createError(`Отсутствует обязательный элемент ${name}`);
+            return createError(`Missing required element ${name}`);
         }
     }
-    // 3. Извлечение и проверка sheetData
+    // 3. Extract and validate sheetData
     const sheetDataStart = xml.indexOf("<sheetData>");
     const sheetDataEnd = xml.indexOf("</sheetData>");
     if (sheetDataStart === -1 || sheetDataEnd === -1) {
-        return createError("Некорректная структура sheetData");
+        return createError("Invalid sheetData structure");
     }
     const sheetDataContent = xml.substring(sheetDataStart + 10, sheetDataEnd);
     const rows = sheetDataContent.split("</row>");
     if (rows.length < 2) {
-        return createError("SheetData должен содержать хотя бы одну строку");
+        return createError("SheetData should contain at least one row");
     }
-    // Собираем информацию о всех строках и ячейках
+    // Collect information about all rows and cells
     const allRows = [];
     const allCells = [];
     let prevRowNum = 0;
     for (const row of rows.slice(0, -1)) {
         if (!row.includes("<row ")) {
-            return createError("Не найден тег row", `Фрагмент: ${row.substring(0, 50)}...`);
+            return createError("Row tag not found", `Fragment: ${row.substring(0, 50)}...`);
         }
         if (!row.includes("<c ")) {
-            return createError("Строка не содержит ячеек", `Строка: ${row.substring(0, 50)}...`);
+            return createError("Row does not contain any cells", `Row: ${row.substring(0, 50)}...`);
         }
-        // Извлекаем номер строки
+        // Extract row number
         const rowNumMatch = row.match(/<row\s+r="(\d+)"/);
         if (!rowNumMatch) {
-            return createError("Не указан номер строки (атрибут r)", `Строка: ${row.substring(0, 50)}...`);
+            return createError("Row number (attribute r) not specified", `Row: ${row.substring(0, 50)}...`);
         }
         const rowNum = parseInt(rowNumMatch[1]);
-        // Проверка уникальности строк
+        // Check for duplicate row numbers
         if (allRows.includes(rowNum)) {
-            return createError("Найден дубликат номера строки", `Номер строки: ${rowNum}`);
+            return createError("Duplicate row number found", `Row number: ${rowNum}`);
         }
         allRows.push(rowNum);
-        // Проверка порядка строк (должны идти по возрастанию)
+        // Check row number order (should be in ascending order)
         if (rowNum <= prevRowNum) {
-            return createError("Нарушен порядок следования строк", `Текущая строка: ${rowNum}, предыдущая: ${prevRowNum}`);
+            return createError("Row order is broken", `Current row: ${rowNum}, previous: ${prevRowNum}`);
         }
         prevRowNum = rowNum;
-        // Извлекаем все ячейки в строке
+        // Extract all cells in the row
         const cells = row.match(/<c\s+r="([A-Z]+)(\d+)"/g) || [];
         for (const cell of cells) {
             const match = cell.match(/<c\s+r="([A-Z]+)(\d+)"/);
             if (!match) {
-                return createError("Некорректный формат ячейки", `Ячейка: ${cell}`);
+                return createError("Invalid cell format", `Cell: ${cell}`);
             }
             const col = match[1];
             const cellRowNum = parseInt(match[2]);
-            // Проверяем соответствие номера строки
+            // Check row number match for each cell
             if (cellRowNum !== rowNum) {
-                return createError("Несоответствие номера строки в ячейке", `Ожидалось: ${rowNum}, найдено: ${cellRowNum} в ячейке ${col}${cellRowNum}`);
+                return createError("Row number mismatch in cell", `Expected: ${rowNum}, found: ${cellRowNum} in cell ${col}${cellRowNum}`);
             }
             allCells.push({
                 col,
@@ -83,32 +96,32 @@ export function validateWorksheetXml(xml) {
             });
         }
     }
-    // 4. Проверка mergeCells
+    // 4. Check mergeCells
     const mergeCellsStart = xml.indexOf("<mergeCells");
     const mergeCellsEnd = xml.indexOf("</mergeCells>");
     if (mergeCellsStart === -1 || mergeCellsEnd === -1) {
-        return createError("Некорректная структура mergeCells");
+        return createError("Invalid mergeCells structure");
     }
     const mergeCellsContent = xml.substring(mergeCellsStart, mergeCellsEnd);
     const countMatch = mergeCellsContent.match(/count="(\d+)"/);
     if (!countMatch) {
-        return createError("Не указано количество объединенных ячеек (атрибут count)");
+        return createError("Count attribute not specified for mergeCells");
     }
     const mergeCellTags = mergeCellsContent.match(/<mergeCell\s+ref="([A-Z]+\d+:[A-Z]+\d+)"\s*\/>/g);
     if (!mergeCellTags) {
-        return createError("Не найдены объединенные ячейки");
+        return createError("No merged cells found");
     }
-    // Проверка соответствия заявленного количества и фактического
+    // Check if the number of mergeCells matches the count attribute
     if (mergeCellTags.length !== parseInt(countMatch[1])) {
-        return createError("Несоответствие количества объединенных ячеек", `Ожидалось: ${countMatch[1]}, найдено: ${mergeCellTags.length}`);
+        return createError("Mismatch in the number of merged cells", `Expected: ${countMatch[1]}, found: ${mergeCellTags.length}`);
     }
-    // Проверка на дублирующиеся mergeCell
+    // Check for duplicates of mergeCell
     const mergeRefs = new Set();
     const duplicates = new Set();
     for (const mergeTag of mergeCellTags) {
         const refMatch = mergeTag.match(/ref="([A-Z]+\d+:[A-Z]+\d+)"/);
         if (!refMatch) {
-            return createError("Некорректный формат объединения ячеек", `Тег: ${mergeTag}`);
+            return createError("Invalid merge cell format", `Tag: ${mergeTag}`);
         }
         const ref = refMatch[1];
         if (mergeRefs.has(ref)) {
@@ -119,9 +132,9 @@ export function validateWorksheetXml(xml) {
         }
     }
     if (duplicates.size > 0) {
-        return createError("Найдены дублирующиеся объединения ячеек", `Дубликаты: ${Array.from(duplicates).join(", ")}`);
+        return createError("Duplicates of merged cells found", `Duplicates: ${Array.from(duplicates).join(", ")}`);
     }
-    // Проверка пересекающихся объединений
+    // Check for overlapping merge ranges
     const mergedRanges = Array.from(mergeRefs).map(ref => {
         const [start, end] = ref.split(":");
         return {
@@ -136,14 +149,14 @@ export function validateWorksheetXml(xml) {
             const a = mergedRanges[i];
             const b = mergedRanges[j];
             if (rangesIntersect(a, b)) {
-                return createError("Найдены пересекающиеся объединения ячеек", `Пересекаются: ${getRangeString(a)} и ${getRangeString(b)}`);
+                return createError("Found intersecting merged cells", `Intersecting: ${getRangeString(a)} and ${getRangeString(b)}`);
             }
         }
     }
-    // 5. Проверка dimension и соответствия с реальными данными
+    // 5. Check dimension and match with real data
     const dimensionMatch = xml.match(/<dimension\s+ref="([A-Z]+\d+:[A-Z]+\d+)"\s*\/>/);
     if (!dimensionMatch) {
-        return createError("Не указана область данных (dimension)");
+        return createError("Data range (dimension) is not specified");
     }
     const [startCell, endCell] = dimensionMatch[1].split(":");
     const startCol = startCell.match(/[A-Z]+/)?.[0];
@@ -151,25 +164,25 @@ export function validateWorksheetXml(xml) {
     const endCol = endCell.match(/[A-Z]+/)?.[0];
     const endRow = parseInt(endCell.match(/\d+/)?.[0] || "0");
     if (!startCol || !endCol || isNaN(startRow) || isNaN(endRow)) {
-        return createError("Некорректный формат dimension", `Dimension: ${dimensionMatch[1]}`);
+        return createError("Invalid dimension format", `Dimension: ${dimensionMatch[1]}`);
     }
     const startColNum = colToNumber(startCol);
     const endColNum = colToNumber(endCol);
-    // Проверяем все ячейки на вхождение в dimension
+    // Check if all cells are within the dimension
     for (const cell of allCells) {
         const colNum = colToNumber(cell.col);
         if (cell.row < startRow || cell.row > endRow) {
-            return createError("Ячейка находится вне указанной области (по строке)", `Ячейка: ${cell.col}${cell.row}, dimension: ${dimensionMatch[1]}`);
+            return createError("Cell is outside the specified area (by row)", `Cell: ${cell.col}${cell.row}, dimension: ${dimensionMatch[1]}`);
         }
         if (colNum < startColNum || colNum > endColNum) {
-            return createError("Ячейка находится вне указанной области (по столбцу)", `Ячейка: ${cell.col}${cell.row}, dimension: ${dimensionMatch[1]}`);
+            return createError("Cell is outside the specified area (by column)", `Cell: ${cell.col}${cell.row}, dimension: ${dimensionMatch[1]}`);
         }
     }
-    // 6. Дополнительная проверка: все mergeCell ссылаются на существующие ячейки
+    // 6. Additional check: all mergeCell tags refer to existing cells
     for (const mergeTag of mergeCellTags) {
         const refMatch = mergeTag.match(/ref="([A-Z]+\d+:[A-Z]+\d+)"/);
         if (!refMatch) {
-            return createError("Некорректный формат объединения ячеек", `Тег: ${mergeTag}`);
+            return createError("Invalid merge cell format", `Tag: ${mergeTag}`);
         }
         const [cell1, cell2] = refMatch[1].split(":");
         const cell1Col = cell1.match(/[A-Z]+/)?.[0];
@@ -177,33 +190,34 @@ export function validateWorksheetXml(xml) {
         const cell2Col = cell2.match(/[A-Z]+/)?.[0];
         const cell2Row = parseInt(cell2.match(/\d+/)?.[0] || "0");
         if (!cell1Col || !cell2Col || isNaN(cell1Row) || isNaN(cell2Row)) {
-            return createError("Некорректные координаты объединения ячеек", `Объединение: ${refMatch[1]}`);
+            return createError("Invalid merged cell coordinates", `Merged cells: ${refMatch[1]}`);
         }
-        // Проверяем что объединяемые ячейки существуют
+        // Check if the merged cells exist
         const cell1Exists = allCells.some(c => c.row === cell1Row && c.col === cell1Col);
         const cell2Exists = allCells.some(c => c.row === cell2Row && c.col === cell2Col);
         if (!cell1Exists || !cell2Exists) {
-            return createError("Объединение ссылается на несуществующие ячейки", `Объединение: ${refMatch[1]}, отсутствует: ${!cell1Exists ? `${cell1Col}${cell1Row}` : `${cell2Col}${cell2Row}`}`);
+            return createError("Merged cell reference points to non-existent cells", `Merged cells: ${refMatch[1]}, missing: ${!cell1Exists ? `${cell1Col}${cell1Row}` : `${cell2Col}${cell2Row}`}`);
         }
     }
     return { isValid: true };
 }
-// Вспомогательные функции для проверки пересечений
+// A function to check if two ranges intersect
 function rangesIntersect(a, b) {
     const aStartColNum = colToNumber(a.startCol);
     const aEndColNum = colToNumber(a.endCol);
     const bStartColNum = colToNumber(b.startCol);
     const bEndColNum = colToNumber(b.endCol);
-    // Проверяем пересечение по строкам
+    // Check if the rows intersect
     const rowsIntersect = !(a.endRow < b.startRow || a.startRow > b.endRow);
-    // Проверяем пересечение по колонкам
+    // Check if the columns intersect
     const colsIntersect = !(aEndColNum < bStartColNum || aStartColNum > bEndColNum);
     return rowsIntersect && colsIntersect;
 }
+// Function to get the range string1
 function getRangeString(range) {
     return `${range.startCol}${range.startRow}:${range.endCol}${range.endRow}`;
 }
-// Функция для преобразования букв колонки в число
+// Function to convert column letters to numbers
 function colToNumber(col) {
     let num = 0;
     for (let i = 0; i < col.length; i++) {

package/build/esm/lib/template/utils/write-rows-to-stream.js

@@ -1,4 +1,5 @@
 import { columnIndexToLetter } from "./column-index-to-letter.js";
+import { escapeXml } from "./escape-xml.js";
 /**
  * Writes an async iterable of rows to an Excel XML file.
  *
@@ -27,7 +28,7 @@ export async function writeRowsToStream(output, rows, startRowNumber) {
         const cells = row.map((value, colIndex) => {
             const colLetter = columnIndexToLetter(colIndex);
             const cellRef = `${colLetter}${rowNumber}`;
-            const cellValue = String(value ?? "");
+            const cellValue = escapeXml(String(value ?? ""));
             return `<c r="${cellRef}" t="inlineStr"><is><t>${cellValue}</t></is></c>`;
         });
         // Write the row to the file

package/build/types/lib/template/utils/index.d.ts

@@ -10,6 +10,10 @@ export * from "./get-max-row-number.js";
 export * from "./get-rows-above.js";
 export * from "./get-rows-below.js";
 export * from "./parse-rows.js";
+export * from "./process-merge-cells.js";
+export * from "./process-merge-finalize.js";
+export * from "./process-rows.js";
+export * from "./process-shared-strings.js";
 export * from "./to-excel-column-object.js";
 export * from "./update-dimension.js";
 export * from "./validate-worksheet-xml.js";

package/build/types/lib/template/utils/process-merge-cells.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Processes the sheet XML by extracting the initial <mergeCells> block and
+ * extracting all merge cell references. The function returns an object with
+ * three properties:
+ * - `initialMergeCells`: The initial <mergeCells> block as a string array.
+ * - `mergeCellMatches`: An array of objects with `from` and `to` properties,
+ *   representing the merge cell references.
+ * - `modifiedXml`: The modified sheet XML with the <mergeCells> block removed.
+ *
+ * @param sheetXml - The sheet XML string.
+ * @returns An object with the above three properties.
+ */
+export declare function processMergeCells(sheetXml: string): {
+    initialMergeCells: string[];
+    mergeCellMatches: {
+        from: string;
+        to: string;
+    }[];
+    modifiedXml: string;
+};

package/build/types/lib/template/utils/process-merge-finalize.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Finalizes the processing of the merged sheet by updating the merge cells and
+ * inserting them into the sheet XML. It also returns the modified sheet XML and
+ * shared strings.
+ *
+ * @param {object} data - An object containing the following properties:
+ *   - `initialMergeCells`: The initial merge cells from the original sheet.
+ *   - `lastIndex`: The last processed position in the sheet XML.
+ *   - `mergeCellMatches`: An array of objects with `from` and `to` properties,
+ *     describing the merge cells.
+ *   - `resultRows`: An array of processed XML rows.
+ *   - `rowShift`: The total row shift.
+ *   - `sharedStrings`: An array of shared strings.
+ *   - `sharedStringsHeader`: The XML declaration of the shared strings.
+ *   - `sheetMergeCells`: An array of merge cell XML strings.
+ *   - `sheetXml`: The original sheet XML string.
+ *
+ * @returns An object with two properties:
+ *   - `shared`: The modified shared strings XML string.
+ *   - `sheet`: The modified sheet XML string with updated merge cells.
+ */
+export declare function processMergeFinalize(data: {
+    initialMergeCells: string[];
+    lastIndex: number;
+    mergeCellMatches: {
+        from: string;
+        to: string;
+    }[];
+    resultRows: string[];
+    rowShift: number;
+    sharedStrings: string[];
+    sharedStringsHeader: string | null;
+    sheetMergeCells: string[];
+    sheetXml: string;
+}): {
+    shared: string;
+    sheet: string;
+};

package/build/types/lib/template/utils/process-rows.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Processes a sheet XML by replacing table placeholders with real data and adjusting row numbers accordingly.
+ *
+ * @param data - An object containing the following properties:
+ *   - `replacements`: An object where keys are table names and values are arrays of objects with table data.
+ *   - `sharedIndexMap`: A Map of shared string indexes by their text content.
+ *   - `mergeCellMatches`: An array of objects with `from` and `to` properties, describing the merge cells.
+ *   - `sharedStrings`: An array of shared strings.
+ *   - `sheetMergeCells`: An array of merge cell XML strings.
+ *   - `sheetXml`: The sheet XML string.
+ *
+ * @returns An object with the following properties:
+ *   - `lastIndex`: The last processed position in the sheet XML.
+ *   - `resultRows`: An array of processed XML rows.
+ *   - `rowShift`: The total row shift.
+ */
+export declare function processRows(data: {
+    replacements: Record<string, unknown>;
+    sharedIndexMap: Map<string, number>;
+    mergeCellMatches: {
+        from: string;
+        to: string;
+    }[];
+    sharedStrings: string[];
+    sheetMergeCells: string[];
+    sheetXml: string;
+}): {
+    lastIndex: number;
+    resultRows: string[];
+    rowShift: number;
+};

package/build/types/lib/template/utils/process-shared-strings.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Processes the shared strings XML by extracting the XML declaration,
+ * extracting individual <si> elements, and storing them in an array.
+ *
+ * The function returns an object with four properties:
+ * - sharedIndexMap: A map of shared string content to their corresponding index
+ * - sharedStrings: An array of shared strings
+ * - sharedStringsHeader: The XML declaration of the shared strings
+ * - sheetMergeCells: An empty array, which is only used for type compatibility
+ *                    with the return type of processBuild.
+ *
+ * @param sharedStringsXml - The XML string of the shared strings
+ * @returns An object with the four properties above
+ */
+export declare function processSharedStrings(sharedStringsXml: string): {
+    sharedIndexMap: Map<string, number>;
+    sharedStrings: string[];
+    sharedStringsHeader: string | null;
+    sheetMergeCells: string[];
+};