@microsoft/connected-workbooks 2.1.16-beta → 2.1.25

package/README.md

@@ -1,7 +1,6 @@
 # Connected Workbooks
 [![Build Status](https://obilshield.visualstudio.com/ConnectedWorkbooks/_apis/build/status/microsoft.connected-workbooks?branchName=main)](https://obilshield.visualstudio.com/ConnectedWorkbooks/_build/latest?definitionId=14&branchName=main)
 [![License](https://img.shields.io/github/license/microsoft/connected-workbooks)](https://github.com/microsoft/connected-workbooks/blob/master/LICENSE)
-[![Snyk Vulnerabilities](https://img.shields.io/snyk/vulnerabilities/github/microsoft/connected-workbooks)](https://snyk.io/test/github/microsoft/connected-workbooks)
 
 A pure JS library, Microsoft backed, that provides xlsx workbook generation capabilities, allowing for:
 1. Fundemental **"Export to Excel"** capabilities for tabular data (landing in a table in Excel).
@@ -24,24 +23,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": [
+  config: { promoteHeaders:true, adjustColumnNames: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 +55,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 +70,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 +81,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 +104,79 @@ 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
+| config | GridConfig | optional | customizations to Grid handling (see GridConfig)
+
+#### GridConfig
+|Parameter   | Type   | Required   | Description   |
+|---|---|---|---|
+| promoteHeaders | boolean | optional | Should first row of gridData be used as the header, defaults to false - generating "Column1", "Column2"...
+| adjustColumnNames | boolean | optional | Should column names be adjusted to be valid Excel names (Fix duplicates for example), defaults to true
+
+#### 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/generators.js

@@ -7,7 +7,7 @@ const generateMashupXMLTemplate = (base64) => `<?xml version="1.0" encoding="utf
 exports.generateMashupXMLTemplate = generateMashupXMLTemplate;
 const generateSingleQueryMashup = (queryName, query) => `section Section1;
     
-    shared ${queryName} = 
+    shared #"${queryName}" = 
     ${query};`;
 exports.generateSingleQueryMashup = generateSingleQueryMashup;
 const generateCustomXmlFilePath = (i) => `customXml/item${i}.xml`;

package/dist/gridParser.js

@@ -0,0 +1,58 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseToTableData = void 0;
+const constants_1 = require("./utils/constants");
+const utils_1 = require("./utils");
+const parseToTableData = (grid) => {
+    if (!grid) {
+        return undefined;
+    }
+    const columnNames = generateColumnNames(grid);
+    const rows = parseGridRows(grid);
+    return { columnNames: columnNames, rows: rows };
+};
+exports.parseToTableData = parseToTableData;
+const parseGridRows = (grid) => {
+    var _a, _b;
+    const gridData = grid.data;
+    if (!gridData) {
+        throw new Error(constants_1.gridNotFoundErr);
+    }
+    const rows = [];
+    if (!((_a = grid.config) === null || _a === void 0 ? void 0 : _a.promoteHeaders)) {
+        const row = [];
+        for (const prop in gridData[0]) {
+            const cellValue = gridData[0][prop];
+            row.push(cellValue.toString());
+        }
+        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((_b = cellValue === null || cellValue === void 0 ? void 0 : cellValue.toString()) !== null && _b !== void 0 ? _b : "");
+        }
+        rows.push(row);
+    }
+    return rows;
+};
+const generateColumnNames = (grid) => {
+    var _a;
+    const columnNames = [];
+    if (!((_a = grid.config) === null || _a === void 0 ? void 0 : _a.promoteHeaders)) {
+        for (let i = 0; i < grid.data[0].length; i++) {
+            columnNames.push(`${constants_1.defaults.columnName} ${i + 1}`);
+        }
+        return columnNames;
+    }
+    // We are adjusting column names by default.
+    if (!grid.config || grid.config.adjustColumnNames === undefined || grid.config.adjustColumnNames) {
+        return utils_1.tableUtils.getAdjustedColumnNames(grid.data[0]);
+    }
+    // Get column names and failed if it's not a legal name.
+    return utils_1.tableUtils.getRawColumnNames(grid.data[0]);
+};

package/dist/gridUtils.js

@@ -0,0 +1,58 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseToTableData = void 0;
+const constants_1 = require("./utils/constants");
+const utils_1 = require("./utils");
+const parseToTableData = (grid) => {
+    if (!grid) {
+        return undefined;
+    }
+    const columnNames = generateColumnNames(grid);
+    const rows = parseGridRows(grid);
+    return { columnNames: columnNames, rows: rows };
+};
+exports.parseToTableData = parseToTableData;
+const parseGridRows = (grid) => {
+    var _a, _b;
+    const gridData = grid.data;
+    if (!gridData) {
+        throw new Error(constants_1.gridNotFoundErr);
+    }
+    const rows = [];
+    if (!((_a = grid.config) === null || _a === void 0 ? void 0 : _a.promoteHeaders)) {
+        const row = [];
+        for (const prop in gridData[0]) {
+            const cellValue = gridData[0][prop];
+            row.push(cellValue.toString());
+        }
+        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((_b = cellValue === null || cellValue === void 0 ? void 0 : cellValue.toString()) !== null && _b !== void 0 ? _b : "");
+        }
+        rows.push(row);
+    }
+    return rows;
+};
+const generateColumnNames = (grid) => {
+    var _a;
+    const columnNames = [];
+    if (!((_a = grid.config) === null || _a === void 0 ? void 0 : _a.promoteHeaders)) {
+        for (let i = 0; i < grid.data[0].length; i++) {
+            columnNames.push(`${constants_1.defaults.columnName} ${i + 1}`);
+        }
+        return columnNames;
+    }
+    // We are adjusting column names by default.
+    if (!grid.config || grid.config.adjustColumnNames === undefined || grid.config.adjustColumnNames) {
+        return utils_1.tableUtils.getAdjustedColumnNames(grid.data[0]);
+    }
+    // Get column names and failed if it's not a legal name.
+    return utils_1.tableUtils.getRawColumnNames(grid.data[0]);
+};

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, DocProps } from "./types";
+export { DataTypes };
+export type { QueryInfo, FileConfigs, Grid, DocProps };
+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/src/generators.js

@@ -0,0 +1,14 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateCustomXmlFilePath = exports.generateSingleQueryMashup = exports.generateMashupXMLTemplate = void 0;
+const generateMashupXMLTemplate = (base64) => `<?xml version="1.0" encoding="utf-16"?><DataMashup xmlns="http://schemas.microsoft.com/DataMashup">${base64}</DataMashup>`;
+exports.generateMashupXMLTemplate = generateMashupXMLTemplate;
+const generateSingleQueryMashup = (queryName, query) => `section Section1;
+    
+    shared #"${queryName}" = 
+    ${query};`;
+exports.generateSingleQueryMashup = generateSingleQueryMashup;
+const generateCustomXmlFilePath = (i) => `customXml/item${i}.xml`;
+exports.generateCustomXmlFilePath = generateCustomXmlFilePath;

package/dist/src/types.js

@@ -0,0 +1,28 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocPropsAutoUpdatedElements = exports.DocPropsModifiableElements = exports.DataTypes = void 0;
+var DataTypes;
+(function (DataTypes) {
+    DataTypes[DataTypes["null"] = 0] = "null";
+    DataTypes[DataTypes["string"] = 1] = "string";
+    DataTypes[DataTypes["number"] = 2] = "number";
+    DataTypes[DataTypes["boolean"] = 3] = "boolean";
+})(DataTypes = exports.DataTypes || (exports.DataTypes = {}));
+var DocPropsModifiableElements;
+(function (DocPropsModifiableElements) {
+    DocPropsModifiableElements["title"] = "dc:title";
+    DocPropsModifiableElements["subject"] = "dc:subject";
+    DocPropsModifiableElements["keywords"] = "cp:keywords";
+    DocPropsModifiableElements["createdBy"] = "dc:creator";
+    DocPropsModifiableElements["description"] = "dc:description";
+    DocPropsModifiableElements["lastModifiedBy"] = "cp:lastModifiedBy";
+    DocPropsModifiableElements["category"] = "cp:category";
+    DocPropsModifiableElements["revision"] = "cp:revision";
+})(DocPropsModifiableElements = exports.DocPropsModifiableElements || (exports.DocPropsModifiableElements = {}));
+var DocPropsAutoUpdatedElements;
+(function (DocPropsAutoUpdatedElements) {
+    DocPropsAutoUpdatedElements["created"] = "dcterms:created";
+    DocPropsAutoUpdatedElements["modified"] = "dcterms:modified";
+})(DocPropsAutoUpdatedElements = exports.DocPropsAutoUpdatedElements || (exports.DocPropsAutoUpdatedElements = {}));

package/dist/src/utils/arrayUtils.js

@@ -0,0 +1,46 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArrayReader = void 0;
+class ArrayReader {
+    constructor(array) {
+        this._array = array;
+        this._position = 0;
+    }
+    getInt32() {
+        const retVal = new DataView(this._array, this._position, 4).getInt32(0, true);
+        this._position += 4;
+        return retVal;
+    }
+    getBytes(bytes) {
+        const retVal = this._array.slice(this._position, bytes ? bytes + this._position : bytes);
+        this._position += retVal.byteLength;
+        return new Uint8Array(retVal);
+    }
+    reset() {
+        this._position = 0;
+    }
+}
+exports.ArrayReader = ArrayReader;
+function getInt32Buffer(val) {
+    const packageSizeBuffer = new ArrayBuffer(4);
+    new DataView(packageSizeBuffer).setInt32(0, val, true);
+    return new Uint8Array(packageSizeBuffer);
+}
+function concatArrays(...args) {
+    let size = 0;
+    args.forEach((arr) => (size += arr.byteLength));
+    const retVal = new Uint8Array(size);
+    let position = 0;
+    args.forEach((arr) => {
+        retVal.set(arr, position);
+        position += arr.byteLength;
+    });
+    return retVal;
+}
+exports.default = {
+    ArrayReader,
+    getInt32Buffer,
+    concatArrays,
+};