Merge pull request #117 from myk93/makeTemplateGeneral

Allow user-defined table and sheet names, flexible table positioning

Author: myk93

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/connected-workbooks",
-  "version": "3.2.1-beta",
+  "version": "3.3.0-beta",
   "description": "Microsoft backed, Excel advanced xlsx workbook generation JavaScript library",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -37,11 +37,11 @@
   },
   "homepage": "https://github.com/microsoft/connected-workbooks#readme",
   "dependencies": {
+    "@xmldom/xmldom": "~0.8.4",
     "base64-js": "^1.5.1",
     "buffer": "^6.0.3",
     "jszip": "^3.5.0",
     "uuid": "^9.0.0",
-    "@xmldom/xmldom": "~0.8.4",
     "xmldom-qsa": "^1.1.3"
   },
   "devDependencies": {

package.json

@@ -41,6 +41,12 @@ export interface FileConfigs {
     templateFile?: File;
     docProps?: DocProps;
     hostName?: string;
+    templateSettings?: TemplateSettings;
+}
+
+export interface TemplateSettings {
+    tableName?: string;
+    sheetName?: string;
 }
 
 export enum DataTypes {

src/types.ts

@@ -8,15 +8,18 @@ export const tableXmlPath = "xl/tables/table1.xml";
 export const queryTableXmlPath = "xl/queryTables/queryTable1.xml";
 export const workbookXmlPath = "xl/workbook.xml";
 export const queryTablesPath = "xl/queryTables/";
+export const tablesFolderPath = "xl/tables/";
 export const pivotCachesPath = "xl/pivotCache/";
 export const section1mPath = "Formulas/Section1.m";
 export const docPropsCoreXmlPath = "docProps/core.xml";
 export const relsXmlPath = "_rels/.rels";
 export const docMetadataXmlPath = "docMetadata";
 export const docPropsRootElement = "cp:coreProperties";
+export const workbookRelsXmlPath = "xl/_rels/workbook.xml.rels";
 
 export const sharedStringsNotFoundErr = "SharedStrings were not found in template";
 export const connectionsNotFoundErr = "Connections were not found in template";
+export const WorkbookNotFoundERR = "workbook was not found in template";
 export const sheetsNotFoundErr = "Sheets were not found in template";
 export const base64NotFoundErr = "Base64 was not found in template";
 export const emptyQueryMashupErr = "Query mashup is empty";
@@ -27,6 +30,7 @@ export const formulaSectionNotFoundErr = "Formula section wasn't found in templa
 export const templateWithInitialDataErr = "Cannot use a template file with initial data";
 export const queryTableNotFoundErr = "Query table wasn't found in template";
 export const tableNotFoundErr = "Table wasn't found in template";
+export const tableReferenceNotFoundErr = "Reference not found in the table XML.";
 export const invalidValueInColumnErr = "Invalid cell value in column";
 export const headerNotFoundErr = "Invalid JSON file, header is missing";
 export const invalidDataTypeErr = "Invalid JSON file, invalid data type";
@@ -39,6 +43,7 @@ export const promotedHeadersCannotBeUsedWithoutAdjustingColumnNamesErr = "Header
 export const unexpectedErr = "Unexpected error";
 export const arrayIsntMxNErr = "Array isn't MxN";
 export const relsNotFoundErr = ".rels were not found in template";
+export const xlRelsNotFoundErr = "workbook.xml.rels were not found xl";
 export const columnIndexOutOfRangeErr = "Column index out of range";
 
 export const blobFileType = "blob";
@@ -85,6 +90,7 @@ export const element = {
     dimension: "dimension",
     selection: "selection",
     kindCell: "c",
+    sheet: "sheet",
 };
 
 export const elementAttributes = {
@@ -99,6 +105,7 @@ export const elementAttributes = {
     name: "name",
     description: "description",
     id: "id",
+    relationId: "r:id",
     type: "Type",
     value: "Value",
     relationshipInfo: "RelationshipInfoContainer",
@@ -118,6 +125,7 @@ export const elementAttributes = {
     x14acDyDescent: "x14ac:dyDescent",
     xr3uid: "xr3:uid",
     space: "xml:space",
+    target: "Target",
 };
 
 export const dataTypeKind = {
@@ -138,6 +146,7 @@ export const defaults = {
     queryName: "Query1",
     sheetName: "Sheet1",
     columnName: "Column",
+    tableName: "Table1",
 };
 
 export const URLS = {

src/utils/constants.ts

@@ -69,16 +69,32 @@ const convertToExcelColumn = (index: number): string => {
     const base = 26; // number of letters in the alphabet
     while (index >= 0) {
         const remainder = index % base;
-        columnStr = String.fromCharCode(remainder + 65) + columnStr; // ASCII 'A' is 65
+        columnStr = String.fromCharCode(remainder + 'A'.charCodeAt(0)) + columnStr;
         index = Math.floor(index / base) - 1;
     }
 
     return columnStr;
 };
 
-const getTableReference = (numberOfCols: number, numberOfRows: number): string => {
-    return `A1:${getCellReferenceRelative(numberOfCols, numberOfRows)}`;
-};
+/**
+ * Parse an Excel range (e.g. "B2:D10") and return its starting row and column indices.
+ * @param cellRangeRef - Range reference string.
+ * @returns Object with numeric row and column.
+ */
+const GetStartPosition = (cellRangeRef: string): { row: number; column: number } => {
+    const match = cellRangeRef.toUpperCase().match(/^([A-Z]+)(\d+):/);
+    if (!match) {
+        return { row: 0, column: 0 };
+    }
+
+    const [, colLetters, rowStr] = match;
+    const row = parseInt(rowStr, 10);
+    const column = colLetters
+        .split("")
+        .reduce((acc, char) => acc * 26 + (char.charCodeAt(0) - "A".charCodeAt(0) + 1), 0);
+
+    return { row, column };
+}
 
 const createCellElement = (doc: Document, colIndex: number, rowIndex: number, data: string): Element => {
     const cell: Element = doc.createElementNS(doc.documentElement.namespaceURI, element.kindCell);
@@ -131,8 +147,8 @@ export default {
     getCellReferenceRelative,
     getCellReferenceAbsolute,
     createCell: createCellElement,
-    getTableReference,
     updateCellData,
     resolveType,
     convertToExcelColumn,
+    GetStartPosition,
 };

src/utils/documentUtils.ts

@@ -4,15 +4,12 @@
 import JSZip from "jszip";
 import { TableData } from "../types";
 import {
-    defaults,
     element,
     elementAttributes,
     queryTableNotFoundErr,
     queryTableXmlPath,
     sheetsNotFoundErr,
-    sheetsXmlPath,
     tableNotFoundErr,
-    tableXmlPath,
     textResultType,
     workbookXmlPath,
     xmlTextResultType,
@@ -21,18 +18,28 @@ import documentUtils from "./documentUtils";
 import { v4 } from "uuid";
 import { DOMParser, XMLSerializer } from "xmldom-qsa";
 
-const updateTableInitialDataIfNeeded = async (zip: JSZip, tableData?: TableData, updateQueryTable?: boolean): Promise<void> => {
+/**
+ * Update initial data for a table, its sheet, query table, and defined name if provided.
+ * @param zip - The JSZip instance containing workbook parts.
+ * @param cellRangeRef - Cell range reference (e.g. "A1:C5").
+ * @param sheetPath - Path to the sheet XML within the zip.
+ * @param tablePath - Path to the table XML within the zip.
+ * @param tableName - Name of the table.
+ * @param tableData - Optional TableData containing headers and rows.
+ * @param updateQueryTable - Whether to update the associated queryTable part.
+ */
+const updateTableInitialDataIfNeeded = async (zip: JSZip, cellRangeRef: string, sheetPath: string, tablePath: string, sheetName: string, tableData?: TableData, updateQueryTable?: boolean): Promise<void> => {
     if (!tableData) {
         return;
     }
 
-    const sheetsXmlString: string | undefined = await zip.file(sheetsXmlPath)?.async(textResultType);
+    const sheetsXmlString: string | undefined = await zip.file(sheetPath)?.async(textResultType);
     if (sheetsXmlString === undefined) {
         throw new Error(sheetsNotFoundErr);
     }
 
-    const newSheet: string = updateSheetsInitialData(sheetsXmlString, tableData);
-    zip.file(sheetsXmlPath, newSheet);
+    const newSheet: string = updateSheetsInitialData(sheetsXmlString, tableData, cellRangeRef);
+    zip.file(sheetPath, newSheet);
 
     if (updateQueryTable) {
         const queryTableXmlString: string | undefined = await zip.file(queryTableXmlPath)?.async(textResultType);
@@ -49,20 +56,28 @@ const updateTableInitialDataIfNeeded = async (zip: JSZip, tableData?: TableData,
             throw new Error(sheetsNotFoundErr);
         }
 
-        const newWorkbook: string = updateWorkbookInitialData(workbookXmlString, tableData);
+        const newWorkbook: string = updateWorkbookInitialData(workbookXmlString, sheetName + GenerateReferenceFromString(cellRangeRef));
         zip.file(workbookXmlPath, newWorkbook);
     }
 
-    const tableXmlString: string | undefined = await zip.file(tableXmlPath)?.async(textResultType);
+    const tableXmlString: string | undefined = await zip.file(tablePath)?.async(textResultType);
     if (tableXmlString === undefined) {
         throw new Error(tableNotFoundErr);
     }
 
-    const newTable: string = updateTablesInitialData(tableXmlString, tableData, updateQueryTable);
-    zip.file(tableXmlPath, newTable);
+    const newTable: string = updateTablesInitialData(tableXmlString, tableData, cellRangeRef, updateQueryTable);
+    zip.file(tablePath, newTable);
 };
 
-const updateTablesInitialData = (tableXmlString: string, tableData: TableData, updateQueryTable = false): string => {
+/**
+ * Generate updated table XML string with new columns, reference, and filter range.
+ * @param tableXmlString - Original table XML.
+ * @param tableData - TableData containing column names.
+ * @param cellRangeRef - Cell range reference.
+ * @param updateQueryTable - Whether to include queryTable attributes.
+ * @returns Serialized XML string of the updated table.
+ */
+const updateTablesInitialData = (tableXmlString: string, tableData: TableData, cellRangeRef: string, updateQueryTable = false): string => {
     const parser: DOMParser = new DOMParser();
     const serializer: XMLSerializer = new XMLSerializer();
     const tableDoc: Document = parser.parseFromString(tableXmlString, xmlTextResultType);
@@ -84,21 +99,26 @@ const updateTablesInitialData = (tableXmlString: string, tableData: TableData, u
     tableColumns.setAttribute(elementAttributes.count, tableData.columnNames.length.toString());
     tableDoc
         .getElementsByTagName(element.table)[0]
-        .setAttribute(elementAttributes.reference, `A1:${documentUtils.getCellReferenceRelative(tableData.columnNames.length - 1, tableData.rows.length + 1)}`);
+        .setAttribute(elementAttributes.reference, cellRangeRef);
     tableDoc
         .getElementsByTagName(element.autoFilter)[0]
-        .setAttribute(elementAttributes.reference, `A1:${documentUtils.getCellReferenceRelative(tableData.columnNames.length - 1, tableData.rows.length + 1)}`);
+        .setAttribute(elementAttributes.reference, cellRangeRef);
 
     return serializer.serializeToString(tableDoc);
 };
 
-const updateWorkbookInitialData = (workbookXmlString: string, tableData: TableData): string => {
+/**
+ * Update the definedName element in workbook XML to a custom name.
+ * @param workbookXmlString - Original workbook XML string.
+ * @param customDefinedName - New defined name text content (e.g. "!$A$1:$C$5").
+ * @returns Serialized XML string of the updated workbook.
+ */
+const updateWorkbookInitialData = (workbookXmlString: string, customDefinedName: string): string => {
     const newParser: DOMParser = new DOMParser();
     const newSerializer: XMLSerializer = new XMLSerializer();
     const workbookDoc: Document = newParser.parseFromString(workbookXmlString, xmlTextResultType);
     const definedName: Element = workbookDoc.getElementsByTagName(element.definedName)[0];
-    definedName.textContent =
-        defaults.sheetName + `!$A$1:${documentUtils.getCellReferenceAbsolute(tableData.columnNames.length - 1, tableData.rows.length + 1)}`;
+    definedName.textContent = customDefinedName;
 
     return newSerializer.serializeToString(workbookDoc);
 };
@@ -122,44 +142,69 @@ const updateQueryTablesInitialData = (queryTableXmlString: string, tableData: Ta
     return serializer.serializeToString(queryTableDoc);
 };
 
-const updateSheetsInitialData = (sheetsXmlString: string, tableData: TableData): string => {
+/**
+ * Update sheet XML with header row and data rows based on TableData.
+ * @param sheetsXmlString - Original sheet XML string.
+ * @param tableData - TableData containing headers and rows.
+ * @param cellRangeRef - Cell range reference.
+ * @returns Serialized XML string of the updated sheet.
+ */
+const updateSheetsInitialData = (sheetsXmlString: string, tableData: TableData, cellRangeRef: string): string => {
+    let { row, column } = documentUtils.GetStartPosition(cellRangeRef);
     const parser: DOMParser = new DOMParser();
     const serializer: XMLSerializer = new XMLSerializer();
     const sheetsDoc: Document = parser.parseFromString(sheetsXmlString, xmlTextResultType);
     const sheetData: Element = sheetsDoc.getElementsByTagName(element.sheetData)[0];
     sheetData.textContent = "";
-    let rowIndex = 0;
+
     const columnRow: Element = sheetsDoc.createElementNS(sheetsDoc.documentElement.namespaceURI, element.row);
-    columnRow.setAttribute(elementAttributes.row, (rowIndex + 1).toString());
-    columnRow.setAttribute(elementAttributes.spans, "1:" + tableData.columnNames.length);
+    columnRow.setAttribute(elementAttributes.row, row.toString());
+    columnRow.setAttribute(elementAttributes.spans, column + ":" + (column + tableData.columnNames.length - 1));
     columnRow.setAttribute(elementAttributes.x14acDyDescent, "0.3");
     tableData.columnNames.forEach((col: string, colIndex: number) => {
-        columnRow.appendChild(documentUtils.createCell(sheetsDoc, colIndex, rowIndex, col));
+        columnRow.appendChild(documentUtils.createCell(sheetsDoc, colIndex + column - 1, row - 1, col));
     });
     sheetData.appendChild(columnRow);
-    rowIndex++;
-    tableData.rows.forEach((row) => {
+    row++;
+
+    tableData.rows.forEach((_row) => {
         const newRow = sheetsDoc.createElementNS(sheetsDoc.documentElement.namespaceURI, element.row);
-        newRow.setAttribute(elementAttributes.row, (rowIndex + 1).toString());
-        newRow.setAttribute(elementAttributes.spans, "1:" + row.length);
+        newRow.setAttribute(elementAttributes.row, row.toString());
+        newRow.setAttribute(elementAttributes.spans, column + ":" + (column + tableData.columnNames.length - 1));
         newRow.setAttribute(elementAttributes.x14acDyDescent, "0.3");
-        row.forEach((cellContent, colIndex) => {
-            newRow.appendChild(documentUtils.createCell(sheetsDoc, colIndex, rowIndex, cellContent));
+        _row.forEach((cellContent, colIndex) => {
+            newRow.appendChild(documentUtils.createCell(sheetsDoc, colIndex + column - 1, row - 1, cellContent));
         });
         sheetData.appendChild(newRow);
-        rowIndex++;
+        row++;
     });
-    const reference = documentUtils.getTableReference(tableData.rows[0].length - 1, tableData.rows.length + 1);
 
-    sheetsDoc.getElementsByTagName(element.dimension)[0].setAttribute(elementAttributes.reference, reference);
-    sheetsDoc.getElementsByTagName(element.selection)[0].setAttribute(elementAttributes.sqref, reference);
+    sheetsDoc.getElementsByTagName(element.dimension)[0].setAttribute(elementAttributes.reference, cellRangeRef);
+    sheetsDoc.getElementsByTagName(element.selection)[0].setAttribute(elementAttributes.sqref, cellRangeRef);
     return serializer.serializeToString(sheetsDoc);
 };
 
+/**
+ * Add Excel-style dollar signs and a '!' prefix to a cell range.
+ * Converts "A1:B2" into "!$A$1:$B$2".
+ * @param cellRangeRef - Range reference string without dollar signs.
+ * @returns Range with dollar signs and prefix.
+ */
+const GenerateReferenceFromString = (cellRangeRef: string): string => {
+    return "!" + cellRangeRef.split(":").map(part => {
+        const match = part.match(/^([A-Za-z]+)(\d+)$/);
+        if (match) {
+            const [, col, row] = match;
+            return `$${col.toUpperCase()}$${row}`;
+        }
+    }).join(":");
+}
+
 export default {
     updateTableInitialDataIfNeeded,
     updateSheetsInitialData,
     updateWorkbookInitialData,
     updateTablesInitialData,
     updateQueryTablesInitialData,
+    GenerateReferenceFromString,
 };