@microsoft/connected-workbooks 2.1.16-beta → 2.1.24-beta

package/README.md

@@ -24,24 +24,20 @@ Connected Workbooks allows you to avoid "data dumps" in CSV form, providing a ri
 
 ### 1. Export a table directly from an Html page:
 ```typescript
-import { workbookManager } from '@microsoft/connected-workbooks';
+import workbookManager from '@microsoft/connected-workbooks';
 
 const blob = await workbookManager.generateTableWorkbookFromHtml(document.querySelector('table') as HTMLTableElement);    
 workbookManager.downloadWorkbook(blob, "MyTable.xlsx");
 ```
+
 ### 2. Export a table from raw data:
-```typescript
-import { workbookManager } from '@microsoft/connected-workbooks';
+```
+import workbookManager from '@microsoft/connected-workbooks';
 
 const grid = {
-  "header": [
-      { "name": "Product", "type": DataTypes.autodetect },
-      { "name": "Price", "type": DataTypes.autodetect },
-      { "name": "InStock", "type": DataTypes.autodetect },
-      { "name": "Category", "type": DataTypes.autodetect },
-      { "name": "Date", "type": DataTypes.autodetect }
-  ],
-  "gridData": [
+  "promoteHeaders": true,
+  "data": [
+      ["Product", "Price", "InStock", "Category", "Date"],
       ["Widget A", 19.99, true, "Electronics", "10/26/2024"],
       ["Gizmo B", 9.99, true, "Accessories", "10/26/2024"],
       ["Bubala", 14.99, false, "Accessories", "10/22/2023"],
@@ -60,13 +56,13 @@ workbookManager.downloadWorkbook(blob, "MyTable.xlsx");
       document.querySelector('table') as HTMLTableElement, 
       {createdBy: 'John Doe', lastModifiedBy: 'Jane Doe', description: 'This is a sample table'});
     
-      workbookManager.downloadWorkbook(blob, "MyTable.xlsx");
+    workbookManager.downloadWorkbook(blob, "MyTable.xlsx");
 ```
 ![image](https://github.com/microsoft/connected-workbooks/assets/7674478/c267c9eb-6367-419d-832d-5a835c7683f9)
 
 ### 4. Export a Power Query connected workbook:
 ```typescript
-import { workbookManager } from '@microsoft/connected-workbooks';
+import workbookManager from '@microsoft/connected-workbooks';
 
 const blob = await workbookManager.generateSingleQueryWorkbook({
   queryMashup: 'let \
@@ -75,9 +71,9 @@ const blob = await workbookManager.generateSingleQueryWorkbook({
                     Source',
   refreshOnOpen: true});
 workbookManager.downloadWorkbook(blob, "MyConnectedWorkbook.xlsx");
-});
 ```
 ![image](https://github.com/microsoft/connected-workbooks/assets/7674478/57bd986c-6309-4963-8d86-911ccf496c3f)
+
 (after refreshing on open)
 ### Advanced Usage - bring your own template:
 
@@ -86,7 +82,7 @@ You can use the library with your own workbook as a template!
 ```typescript
 const blob = await workbookManager.generateSingleQueryWorkbook(
   { queryMashup: query, refreshOnOpen: true },
-  undefined /* optional gridData */,
+  undefined /* optional Grid */,
   templateFile);
 workbookManager.downloadWorkbook(blob, "MyBrandedWorkbook.xlsx");
 ```
@@ -109,6 +105,74 @@ const [templateFile, setTemplateFile] = useState<File | null>(null);
   setTemplateFile(e!.target!.files!.item(0));
 }}/>
 ```
+### API
+The library exposes a workbookManager, which generates a workbook via several APIs:
+
+#### 1. Generate a Power Query connected workbook
+```typescript
+ async function `generateSingleQueryWorkbook`: `Promise<Blob>`
+```
+ 
+|Parameter   | Type   | Required   | Description   |
+|---      |---    |---          |---            |
+|query   | [QueryInfo](#queryinfo)   | __required__  | Power Query mashup  | 
+| grid  | [Grid](#grid)   | optional   | Initial grid data  | 
+| fileConfigs  | [FileConfigs](#fileconfigs)   | optional  | Custom file configurations |
+
+#### 2. Generate a table workbook from a Html page
+```typescript
+async function `generateTableWorkbookFromHtml`: `Promise<Blob>`
+```
+
+|Parameter   | Type   | Required   | Description   |
+|---      |---    |---          |---            |
+| htmlTable  | HTMLTableElement   | __required__   | Initial data loaded to workbook  | 
+| docProps  | [DocProps](#docprops)   | optional  | Custom workbook properties |
+
+#### 3. Generate a table workbook with raw data
+```typescript
+async function `generateTableWorkbookFromGrid`: `Promise<Blob>`
+```
+
+|Parameter   | Type   | Required   | Description   |
+|---      |---    |---          |---            |
+| grid  | [Grid](#grid)   | __required__   | Initial data loaded to workbook  | 
+| docProps  | [DocProps](#docprops)   | optional  | Custom workbook properties |
+</br>
+
+### Types
+
+#### QueryInfo
+|Parameter   | Type   | Required   | Description   |
+|---|---|---|---|
+| queryMashup | string | __required__ | Mashup string
+| refreshOnOpen | boolean | __required__ | Should workbook data refresh upon open
+| queryName | string | optional | Query name, defaults to "Query1"
+
+#### Grid
+|Parameter   | Type   | Required   | Description   |
+|---|---|---|---|
+| data | (string | number | boolean)[][] | __required__ | Grid data
+| promoteHeaders | boolean | optional | Should first row of gridData be used as the header, defaults to false - generating "Column1", "Column2"...
+
+
+#### FileConfigs
+|Parameter   | Type   | Required   | Description   |
+|---|---|---|---|
+| templateFile | File | optional   | Custom Excel workbook  |
+| docProps  | [DocProps](#docprops)   | optional  | Custom workbook properties |
+
+#### DocProps
+|Parameter   | Type   | Required  
+|---|---|---|
+| title | string | optional 
+| subject | string | optional 
+| keywords | string | optional 
+| createdBy | string | optional 
+| description | string | optional 
+| lastModifiedBy | string | optional 
+| category | string | optional 
+| revision | number | optional 
 
 ## Contributing
 

package/dist/GridParser.js

@@ -1,55 +1,48 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseToTableData = void 0;
 const constants_1 = require("./utils/constants");
-const types_1 = require("./types");
-class GridParser {
-    parseToTableData(initialDataGrid) {
-        if (!initialDataGrid) {
-            return undefined;
-        }
-        this.validateGridHeader(initialDataGrid);
-        const rows = this.parseGridRows(initialDataGrid, initialDataGrid.header);
-        return { columnMetadata: initialDataGrid.header, rows: rows };
+const parseToTableData = (grid) => {
+    if (!grid) {
+        return undefined;
     }
-    parseGridRows(initialDataGrid, columnMetadata) {
-        const gridData = initialDataGrid.gridData;
-        if (!gridData) {
-            throw new Error(constants_1.gridNotFoundErr);
-        }
-        const rows = [];
-        for (const rowData of gridData) {
-            const row = [];
-            let colIndex = 0;
-            for (const prop in rowData) {
-                const dataType = columnMetadata[colIndex].type;
-                const cellValue = rowData[prop];
-                if (dataType == types_1.DataTypes.number) {
-                    if (isNaN(Number(cellValue))) {
-                        throw new Error(constants_1.invalidValueInColumnErr);
-                    }
-                }
-                else if (dataType == types_1.DataTypes.boolean) {
-                    if (cellValue != "1" && cellValue != "0") {
-                        throw new Error(constants_1.invalidValueInColumnErr);
-                    }
-                }
-                row.push(rowData[prop].toString());
-                colIndex++;
-            }
-            rows.push(row);
-        }
-        return rows;
+    const columnNames = generateColumnNames(grid);
+    const rows = parseGridRows(grid);
+    return { columnNames: columnNames, rows: rows };
+};
+exports.parseToTableData = parseToTableData;
+const parseGridRows = (grid) => {
+    const gridData = grid.data;
+    if (!gridData) {
+        throw new Error(constants_1.gridNotFoundErr);
     }
-    validateGridHeader(data) {
-        const headerData = data.header;
-        if (!headerData) {
-            throw new Error(constants_1.headerNotFoundErr);
+    const rows = [];
+    if (!grid.promoteHeaders) {
+        const row = [];
+        for (const prop in gridData[0]) {
+            const cellValue = gridData[0][prop];
+            row.push(cellValue.toString());
         }
-        for (const prop in headerData) {
-            if (!(headerData[prop].type in types_1.DataTypes)) {
-                throw new Error(constants_1.invalidDataTypeErr);
-            }
+        rows.push(row);
+    }
+    for (let i = 1; i < gridData.length; i++) {
+        const rowData = gridData[i];
+        const row = [];
+        for (const prop in rowData) {
+            const cellValue = rowData[prop];
+            row.push(cellValue.toString());
         }
+        rows.push(row);
+    }
+    return rows;
+};
+const generateColumnNames = (grid) => {
+    if (grid.promoteHeaders) {
+        return grid.data[0].map((columnName) => columnName.toString());
+    }
+    const columnNames = [];
+    for (let i = 0; i < grid.data[0].length; i++) {
+        columnNames.push(`Column ${i + 1}`);
     }
-}
-exports.default = GridParser;
+    return columnNames;
+};

package/dist/index.d.ts

@@ -1,3 +1,6 @@
-export { default as workbookManager } from "./workbookManager";
-export { DataTypes } from "./types";
-export type { QueryInfo } from "./types";
+import * as workbookManager from "./workbookManager";
+import { DataTypes } from "./types";
+import type { QueryInfo, FileConfigs, Grid } from "./types";
+export { DataTypes };
+export type { QueryInfo, FileConfigs, Grid };
+export default workbookManager;

package/dist/index.js

@@ -1,12 +1,32 @@
 "use strict";
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DataTypes = exports.workbookManager = void 0;
-var workbookManager_1 = require("./workbookManager");
-Object.defineProperty(exports, "workbookManager", { enumerable: true, get: function () { return __importDefault(workbookManager_1).default; } });
-var types_1 = require("./types");
+exports.DataTypes = void 0;
+const workbookManager = __importStar(require("./workbookManager"));
+const types_1 = require("./types");
 Object.defineProperty(exports, "DataTypes", { enumerable: true, get: function () { return types_1.DataTypes; } });
+exports.default = workbookManager;

package/dist/types.d.ts

@@ -17,23 +17,19 @@ export interface Metadata {
     queryName: string;
 }
 export interface TableData {
-    columnMetadata: ColumnMetadata[];
+    columnNames: string[];
     rows: string[][];
     columnwidth?: number;
 }
-export interface ColumnMetadata {
-    name: string;
-    type: DataTypes;
-}
 export interface Grid {
-    header: ColumnMetadata[];
-    gridData: (string | number | boolean)[][];
+    data: (string | number | boolean)[][];
+    promoteHeaders?: boolean;
 }
-export interface TableDataParser {
-    parseToTableData: (grid: any) => TableData | undefined;
+export interface FileConfigs {
+    templateFile?: File;
+    docProps?: DocProps;
 }
 export declare enum DataTypes {
-    autodetect = -1,
     null = 0,
     string = 1,
     number = 2,

package/dist/types.js

@@ -5,7 +5,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DocPropsAutoUpdatedElements = exports.DocPropsModifiableElements = exports.DataTypes = void 0;
 var DataTypes;
 (function (DataTypes) {
-    DataTypes[DataTypes["autodetect"] = -1] = "autodetect";
     DataTypes[DataTypes["null"] = 0] = "null";
     DataTypes[DataTypes["string"] = 1] = "string";
     DataTypes[DataTypes["number"] = 2] = "number";

package/dist/utils/constants.js

@@ -2,7 +2,8 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.URLS = exports.defaults = exports.elementAttributesValues = exports.dataTypeKind = exports.elementAttributes = exports.element = exports.falseStr = exports.trueStr = exports.maxQueryLength = exports.divider = exports.section1PathPrefix = exports.emptyValue = exports.falseValue = exports.trueValue = exports.pivotCachesPathPrefix = exports.xmlTextResultType = exports.textResultType = exports.application = exports.uint8ArrayType = exports.blobFileType = exports.stylesNotFoundErr = exports.EmptyQueryNameErr = exports.QueryNameMaxLengthErr = exports.invalidDataTypeErr = exports.headerNotFoundErr = exports.invalidValueInColumnErr = exports.gridNotFoundErr = exports.tableNotFoundErr = exports.queryTableNotFoundErr = exports.templateWithInitialDataErr = exports.formulaSectionNotFoundErr = exports.queryConnectionNotFoundErr = exports.queryAndPivotTableNotFoundErr = exports.queryNameNotFoundErr = exports.emptyQueryMashupErr = exports.base64NotFoundErr = exports.sheetsNotFoundErr = exports.connectionsNotFoundErr = exports.sharedStringsNotFoundErr = exports.docPropsRootElement = exports.docPropsCoreXmlPath = exports.section1mPath = exports.pivotCachesPath = exports.queryTablesPath = exports.workbookXmlPath = exports.queryTableXmlPath = exports.tableXmlPath = exports.sheetsXmlPath = exports.sharedStringsXmlPath = exports.connectionsXmlPath = void 0;
+exports.defaults = exports.elementAttributesValues = exports.dataTypeKind = exports.elementAttributes = exports.element = exports.BOM = exports.falseStr = exports.trueStr = exports.maxQueryLength = exports.divider = exports.section1PathPrefix = exports.emptyValue = exports.falseValue = exports.trueValue = exports.pivotCachesPathPrefix = exports.xmlTextResultType = exports.textResultType = exports.application = exports.uint8ArrayType = exports.blobFileType = exports.stylesNotFoundErr = exports.EmptyQueryNameErr = exports.QueryNameMaxLengthErr = exports.invalidDataTypeErr = exports.headerNotFoundErr = exports.invalidValueInColumnErr = exports.gridNotFoundErr = exports.tableNotFoundErr = exports.queryTableNotFoundErr = exports.templateWithInitialDataErr = exports.formulaSectionNotFoundErr = exports.queryConnectionNotFoundErr = exports.queryAndPivotTableNotFoundErr = exports.queryNameNotFoundErr = exports.emptyQueryMashupErr = exports.base64NotFoundErr = exports.sheetsNotFoundErr = exports.connectionsNotFoundErr = exports.sharedStringsNotFoundErr = exports.docPropsRootElement = exports.docPropsCoreXmlPath = exports.section1mPath = exports.pivotCachesPath = exports.queryTablesPath = exports.workbookXmlPath = exports.queryTableXmlPath = exports.tableXmlPath = exports.sheetsXmlPath = exports.sharedStringsXmlPath = exports.connectionsXmlPath = void 0;
+exports.URLS = void 0;
 exports.connectionsXmlPath = "xl/connections.xml";
 exports.sharedStringsXmlPath = "xl/sharedStrings.xml";
 exports.sheetsXmlPath = "xl/worksheets/sheet1.xml";
@@ -47,6 +48,7 @@ exports.divider = "/";
 exports.maxQueryLength = 80;
 exports.trueStr = "true";
 exports.falseStr = "false";
+exports.BOM = '\ufeff';
 exports.element = {
     sharedStringTable: "sst",
     text: "t",
@@ -119,6 +121,7 @@ exports.elementAttributesValues = {
 };
 exports.defaults = {
     queryName: "Query1",
+    sheetName: "Sheet1"
 };
 exports.URLS = {
     PQ: [

package/dist/utils/documentUtils.js

@@ -55,16 +55,16 @@ const getCellReferenceRelative = (col, row) => {
 const getTableReference = (numberOfCols, numberOfRows) => {
     return `A1:${getCellReferenceRelative(numberOfCols, numberOfRows)}`;
 };
-const createCellElement = (doc, colIndex, rowIndex, dataType, data) => {
+const createCellElement = (doc, colIndex, rowIndex, data) => {
     const cell = doc.createElementNS(doc.documentElement.namespaceURI, constants_1.element.kindCell);
     cell.setAttribute(constants_1.elementAttributes.row, getCellReferenceRelative(colIndex, rowIndex + 1));
     const cellData = doc.createElementNS(doc.documentElement.namespaceURI, constants_1.element.cellValue);
-    updateCellData(dataType, data, cell, cellData);
+    updateCellData(data, cell, cellData);
     cell.appendChild(cellData);
     return cell;
 };
-const updateCellData = (dataType, data, cell, cellData) => {
-    switch (resolveType(dataType, data)) {
+const updateCellData = (data, cell, cellData) => {
+    switch (resolveType(data)) {
         case types_1.DataTypes.string:
             cell.setAttribute(constants_1.element.text, constants_1.dataTypeKind.string);
             break;
@@ -77,10 +77,7 @@ const updateCellData = (dataType, data, cell, cellData) => {
     }
     cellData.textContent = data;
 };
-const resolveType = (originalDataType, originalData) => {
-    if (originalDataType !== types_1.DataTypes.autodetect) {
-        return originalDataType;
-    }
+const resolveType = (originalData) => {
     const data = originalData;
     let dataType = isNaN(Number(data)) ? types_1.DataTypes.string : types_1.DataTypes.number;
     if (dataType == types_1.DataTypes.string) {

package/dist/utils/htmlUtils.js

@@ -4,14 +4,8 @@ exports.extractTableValues = void 0;
 const extractTableValues = (table) => {
     const headers = [];
     const rows = [];
-    // Extract headers
-    const headerRow = table.rows[0];
-    for (let i = 0; i < headerRow.cells.length; i++) {
-        const cell = headerRow.cells[i];
-        headers.push(cell.textContent || "");
-    }
     // Extract values from each row
-    for (let i = 1; i < table.rows.length; i++) {
+    for (let i = 0; i < table.rows.length; i++) {
         const row = table.rows[i];
         const rowData = [];
         for (let j = 0; j < row.cells.length; j++) {
@@ -20,6 +14,6 @@ const extractTableValues = (table) => {
         }
         rows.push(rowData);
     }
-    return [headers, rows];
+    return rows;
 };
 exports.extractTableValues = extractTableValues;