sheetra 1.0.0 → 1.0.2

package/README.md

@@ -4,13 +4,15 @@
 
 [![npm version](https://img.shields.io/npm/v/sheetra.svg)](https://www.npmjs.com/package/sheetra)
 [![License](https://img.shields.io/github/license/opencorex-org/sheetra)](LICENSE)
+[![Build Status](https://github.com/opencorex-org/sheetra/actions/workflows/build.yml/badge.svg)](https://github.com/opencorex-org/sheetra/actions)
 [![npm downloads](https://img.shields.io/npm/dm/sheetra.svg)](https://www.npmjs.com/package/sheetra)
 [![GitHub stars](https://img.shields.io/github/stars/opencorex-org/sheetra?style=social)](https://github.com/opencorex-org/sheetra)
 [![GitHub issues](https://img.shields.io/github/issues/opencorex-org/sheetra)](https://github.com/opencorex-org/sheetra/issues)
-[![Version](https://img.shields.io/badge/version-1.0.0-blue)](https://github.com/opencorex-org/sheetra/releases)
 
 Sheetra is a powerful, zero-dependency library for exporting data to Excel (XLSX), CSV, and JSON formats. It provides a clean, fluent API for creating complex spreadsheets with styles, outlines, and sections.
 
+---
+
 ## Features
 
 - **Zero Dependencies** – Pure TypeScript/JavaScript implementation
@@ -21,12 +23,79 @@ Sheetra is a powerful, zero-dependency library for exporting data to Excel (XLSX
 - **TypeScript** – Full type support
 - **Browser & Node** – Works in both environments
 
+---
+
 ## Installation
 
+Install Sheetra using your favorite package manager:
+
 ```bash
 npm install sheetra
 # or
 yarn add sheetra
 # or
 pnpm add sheetra
-```
+```
+
+---
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { ExportBuilder } from 'sheetra';
+
+const builder = ExportBuilder.create('Users')
+  .addHeaderRow(['Name', 'Age'])
+  .addDataRows([
+    ['John', 30],
+    ['Jane', 25]
+  ]);
+
+builder.download({ filename: 'users.xlsx', format: 'xlsx' });
+```
+
+### Advanced Example
+
+```typescript
+import { ExportBuilder } from 'sheetra';
+
+const parts = [
+  { part_number: 'P001', part_name: 'Widget', current_stock: 100 },
+  { part_number: 'P002', part_name: 'Gadget', current_stock: 50 },
+];
+
+const instances = [
+  { serial_number: 'S001', part_number: 'P001', status: 'Active', location: 'A1' },
+  { serial_number: 'S002', part_number: 'P001', status: 'Inactive', location: 'A2' },
+  { serial_number: 'S003', part_number: 'P002', status: 'Active', location: 'B1' },
+];
+
+ExportBuilder.create('Inventory')
+  .addSection({ name: 'Parts' })
+  .addHeaderRow(['Part Number', 'Part Name', 'Current Stock'])
+  .addDataRows(parts.map(p => [p.part_number, p.part_name, p.current_stock]))
+  .addSection({ name: 'Instances' })
+  .addHeaderRow(['Serial Number', 'Part Number', 'Status', 'Location'])
+  .addDataRows(instances.map(i => [i.serial_number, i.part_number, i.status, i.location]))
+  .download({ filename: 'inventory.xlsx', format: 'xlsx' });
+```
+
+---
+
+## Documentation
+
+For detailed documentation, visit the [API Reference](docs/API.md) and [Getting Started Guide](docs/GETTING_STARTED.md).
+
+---
+
+## Contributing
+
+We welcome contributions! Please read the [Contributing Guide](docs/CONTRIBUTING.md) to learn how you can help improve Sheetra.
+
+---
+
+## License
+
+This project is licensed under the [Apache 2.0 License](LICENSE).

package/dist/index.esm.js

@@ -402,6 +402,318 @@ class Worksheet {
     }
 }
 
+/**
+ * Minimal ZIP file creator for XLSX generation (no external dependencies)
+ * Uses STORE method (no compression) for simplicity and compatibility
+ */
+class ZipWriter {
+    constructor() {
+        this.files = [];
+        this.encoder = new TextEncoder();
+    }
+    addFile(name, content) {
+        this.files.push({
+            name,
+            data: this.encoder.encode(content)
+        });
+    }
+    generate() {
+        const localFiles = [];
+        const centralDirectory = [];
+        let offset = 0;
+        for (const file of this.files) {
+            const localHeader = this.createLocalFileHeader(file.name, file.data);
+            localFiles.push(localHeader);
+            localFiles.push(file.data);
+            const centralHeader = this.createCentralDirectoryHeader(file.name, file.data, offset);
+            centralDirectory.push(centralHeader);
+            offset += localHeader.length + file.data.length;
+        }
+        const centralDirStart = offset;
+        let centralDirSize = 0;
+        for (const header of centralDirectory) {
+            centralDirSize += header.length;
+        }
+        const endOfCentralDir = this.createEndOfCentralDirectory(this.files.length, centralDirSize, centralDirStart);
+        // Combine all parts
+        const totalSize = offset + centralDirSize + endOfCentralDir.length;
+        const result = new Uint8Array(totalSize);
+        let pos = 0;
+        for (const local of localFiles) {
+            result.set(local, pos);
+            pos += local.length;
+        }
+        for (const central of centralDirectory) {
+            result.set(central, pos);
+            pos += central.length;
+        }
+        result.set(endOfCentralDir, pos);
+        return result;
+    }
+    createLocalFileHeader(name, data) {
+        const nameBytes = this.encoder.encode(name);
+        const crc = this.crc32(data);
+        const header = new Uint8Array(30 + nameBytes.length);
+        const view = new DataView(header.buffer);
+        view.setUint32(0, 0x04034b50, true); // Local file header signature
+        view.setUint16(4, 20, true); // Version needed to extract
+        view.setUint16(6, 0, true); // General purpose bit flag
+        view.setUint16(8, 0, true); // Compression method (STORE)
+        view.setUint16(10, 0, true); // File last modification time
+        view.setUint16(12, 0, true); // File last modification date
+        view.setUint32(14, crc, true); // CRC-32
+        view.setUint32(18, data.length, true); // Compressed size
+        view.setUint32(22, data.length, true); // Uncompressed size
+        view.setUint16(26, nameBytes.length, true); // File name length
+        view.setUint16(28, 0, true); // Extra field length
+        header.set(nameBytes, 30);
+        return header;
+    }
+    createCentralDirectoryHeader(name, data, localHeaderOffset) {
+        const nameBytes = this.encoder.encode(name);
+        const crc = this.crc32(data);
+        const header = new Uint8Array(46 + nameBytes.length);
+        const view = new DataView(header.buffer);
+        view.setUint32(0, 0x02014b50, true); // Central directory file header signature
+        view.setUint16(4, 20, true); // Version made by
+        view.setUint16(6, 20, true); // Version needed to extract
+        view.setUint16(8, 0, true); // General purpose bit flag
+        view.setUint16(10, 0, true); // Compression method (STORE)
+        view.setUint16(12, 0, true); // File last modification time
+        view.setUint16(14, 0, true); // File last modification date
+        view.setUint32(16, crc, true); // CRC-32
+        view.setUint32(20, data.length, true); // Compressed size
+        view.setUint32(24, data.length, true); // Uncompressed size
+        view.setUint16(28, nameBytes.length, true); // File name length
+        view.setUint16(30, 0, true); // Extra field length
+        view.setUint16(32, 0, true); // File comment length
+        view.setUint16(34, 0, true); // Disk number start
+        view.setUint16(36, 0, true); // Internal file attributes
+        view.setUint32(38, 0, true); // External file attributes
+        view.setUint32(42, localHeaderOffset, true); // Relative offset of local header
+        header.set(nameBytes, 46);
+        return header;
+    }
+    createEndOfCentralDirectory(numFiles, centralDirSize, centralDirOffset) {
+        const header = new Uint8Array(22);
+        const view = new DataView(header.buffer);
+        view.setUint32(0, 0x06054b50, true); // End of central directory signature
+        view.setUint16(4, 0, true); // Number of this disk
+        view.setUint16(6, 0, true); // Disk where central directory starts
+        view.setUint16(8, numFiles, true); // Number of central directory records on this disk
+        view.setUint16(10, numFiles, true); // Total number of central directory records
+        view.setUint32(12, centralDirSize, true); // Size of central directory
+        view.setUint32(16, centralDirOffset, true); // Offset of start of central directory
+        view.setUint16(20, 0, true); // Comment length
+        return header;
+    }
+    crc32(data) {
+        let crc = 0xFFFFFFFF;
+        for (let i = 0; i < data.length; i++) {
+            crc ^= data[i];
+            for (let j = 0; j < 8; j++) {
+                crc = (crc >>> 1) ^ (crc & 1 ? 0xEDB88320 : 0);
+            }
+        }
+        return (crc ^ 0xFFFFFFFF) >>> 0;
+    }
+}
+class ExcelWriter {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    static async write(workbook, _options) {
+        const zip = new ZipWriter();
+        const sheets = workbook['sheets'];
+        const sheetNames = sheets.map((sheet, index) => sheet.getName() || `Sheet${index + 1}`);
+        // Add required XLSX files
+        zip.addFile('[Content_Types].xml', this.generateContentTypes(sheetNames));
+        zip.addFile('_rels/.rels', this.generateRels());
+        zip.addFile('xl/workbook.xml', this.generateWorkbook(sheetNames));
+        zip.addFile('xl/_rels/workbook.xml.rels', this.generateWorkbookRels(sheetNames));
+        zip.addFile('xl/styles.xml', this.generateStyles());
+        zip.addFile('xl/sharedStrings.xml', this.generateSharedStrings(sheets));
+        // Add each worksheet
+        sheets.forEach((sheet, index) => {
+            zip.addFile(`xl/worksheets/sheet${index + 1}.xml`, this.generateWorksheet(sheet));
+        });
+        const buffer = zip.generate();
+        return new Blob([buffer.buffer], {
+            type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+        });
+    }
+    static escapeXml(str) {
+        if (typeof str !== 'string')
+            return String(str !== null && str !== void 0 ? str : '');
+        return str
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&apos;');
+    }
+    static generateContentTypes(sheetNames) {
+        let xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+        xml += '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">';
+        xml += '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>';
+        xml += '<Default Extension="xml" ContentType="application/xml"/>';
+        xml += '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>';
+        xml += '<Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>';
+        xml += '<Override PartName="/xl/sharedStrings.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml"/>';
+        sheetNames.forEach((_, index) => {
+            xml += `<Override PartName="/xl/worksheets/sheet${index + 1}.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>`;
+        });
+        xml += '</Types>';
+        return xml;
+    }
+    static generateRels() {
+        let xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+        xml += '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">';
+        xml += '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>';
+        xml += '</Relationships>';
+        return xml;
+    }
+    static generateWorkbook(sheetNames) {
+        let xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+        xml += '<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">';
+        xml += '<sheets>';
+        sheetNames.forEach((name, index) => {
+            xml += `<sheet name="${this.escapeXml(name)}" sheetId="${index + 1}" r:id="rId${index + 1}"/>`;
+        });
+        xml += '</sheets>';
+        xml += '</workbook>';
+        return xml;
+    }
+    static generateWorkbookRels(sheetNames) {
+        let xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+        xml += '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">';
+        sheetNames.forEach((_, index) => {
+            xml += `<Relationship Id="rId${index + 1}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet${index + 1}.xml"/>`;
+        });
+        xml += `<Relationship Id="rId${sheetNames.length + 1}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>`;
+        xml += `<Relationship Id="rId${sheetNames.length + 2}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings" Target="sharedStrings.xml"/>`;
+        xml += '</Relationships>';
+        return xml;
+    }
+    static generateStyles() {
+        let xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+        xml += '<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">';
+        xml += '<fonts count="1"><font><sz val="11"/><name val="Calibri"/></font></fonts>';
+        xml += '<fills count="2"><fill><patternFill patternType="none"/></fill><fill><patternFill patternType="gray125"/></fill></fills>';
+        xml += '<borders count="1"><border><left/><right/><top/><bottom/><diagonal/></border></borders>';
+        xml += '<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>';
+        xml += '<cellXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/></cellXfs>';
+        xml += '</styleSheet>';
+        return xml;
+    }
+    static generateSharedStrings(sheets) {
+        const strings = [];
+        sheets.forEach((sheet) => {
+            const rows = sheet.getRows();
+            rows.forEach((row) => {
+                row.getCells().forEach((cell) => {
+                    const cellData = cell.toData();
+                    if (typeof cellData.value === 'string' && !cellData.formula) {
+                        if (!strings.includes(cellData.value)) {
+                            strings.push(cellData.value);
+                        }
+                    }
+                });
+            });
+        });
+        let xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+        xml += `<sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" count="${strings.length}" uniqueCount="${strings.length}">`;
+        strings.forEach(str => {
+            xml += `<si><t>${this.escapeXml(str)}</t></si>`;
+        });
+        xml += '</sst>';
+        return xml;
+    }
+    static generateWorksheet(sheet) {
+        const rows = sheet.getRows();
+        const allStrings = this.collectAllStrings(sheet);
+        let xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+        xml += '<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">';
+        // Add sheet dimension
+        const dimension = this.getSheetDimension(rows);
+        xml += `<dimension ref="${dimension}"/>`;
+        xml += '<sheetData>';
+        rows.forEach((row, rowIndex) => {
+            const cells = row.getCells();
+            if (cells.length > 0) {
+                xml += `<row r="${rowIndex + 1}">`;
+                cells.forEach((cell, colIndex) => {
+                    const cellData = cell.toData();
+                    const cellRef = this.columnToLetter(colIndex + 1) + (rowIndex + 1);
+                    if (cellData.formula) {
+                        xml += `<c r="${cellRef}"><f>${this.escapeXml(cellData.formula)}</f></c>`;
+                    }
+                    else if (cellData.value !== null && cellData.value !== undefined && cellData.value !== '') {
+                        if (typeof cellData.value === 'number') {
+                            xml += `<c r="${cellRef}"><v>${cellData.value}</v></c>`;
+                        }
+                        else if (typeof cellData.value === 'boolean') {
+                            xml += `<c r="${cellRef}" t="b"><v>${cellData.value ? 1 : 0}</v></c>`;
+                        }
+                        else if (cellData.type === 'date') {
+                            const excelDate = DateFormatter.toExcelDate(cellData.value);
+                            xml += `<c r="${cellRef}"><v>${excelDate}</v></c>`;
+                        }
+                        else {
+                            // String value - use shared string index
+                            const stringIndex = allStrings.indexOf(String(cellData.value));
+                            if (stringIndex >= 0) {
+                                xml += `<c r="${cellRef}" t="s"><v>${stringIndex}</v></c>`;
+                            }
+                            else {
+                                // Inline string as fallback
+                                xml += `<c r="${cellRef}" t="inlineStr"><is><t>${this.escapeXml(String(cellData.value))}</t></is></c>`;
+                            }
+                        }
+                    }
+                });
+                xml += '</row>';
+            }
+        });
+        xml += '</sheetData>';
+        xml += '</worksheet>';
+        return xml;
+    }
+    static collectAllStrings(sheet) {
+        const strings = [];
+        const rows = sheet.getRows();
+        rows.forEach((row) => {
+            row.getCells().forEach((cell) => {
+                const cellData = cell.toData();
+                if (typeof cellData.value === 'string' && !cellData.formula) {
+                    if (!strings.includes(cellData.value)) {
+                        strings.push(cellData.value);
+                    }
+                }
+            });
+        });
+        return strings;
+    }
+    static getSheetDimension(rows) {
+        if (rows.length === 0)
+            return 'A1';
+        let maxCol = 1;
+        rows.forEach(row => {
+            const cellCount = row.getCells().length;
+            if (cellCount > maxCol)
+                maxCol = cellCount;
+        });
+        return `A1:${this.columnToLetter(maxCol)}${rows.length}`;
+    }
+    static columnToLetter(column) {
+        let letters = '';
+        while (column > 0) {
+            const temp = (column - 1) % 26;
+            letters = String.fromCharCode(temp + 65) + letters;
+            column = Math.floor((column - temp - 1) / 26);
+        }
+        return letters || 'A';
+    }
+}
+
 class CSVWriter {
     static async write(workbook, _options) {
         const sheets = workbook['sheets'];
@@ -473,102 +785,6 @@ class JSONWriter {
     }
 }
 
-class ExcelWriter {
-    static async write(workbook, _options) {
-        const data = this.generateExcelData(workbook);
-        const buffer = this.createExcelFile(data);
-        const uint8Buffer = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
-        const arrayBuffer = uint8Buffer.slice().buffer;
-        return new Blob([arrayBuffer], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
-    }
-    static generateExcelData(workbook) {
-        const sheets = workbook['sheets'];
-        return {
-            Sheets: sheets.reduce((acc, sheet, index) => {
-                const sheetName = sheet.getName() || `Sheet${index + 1}`;
-                acc[sheetName] = this.generateSheetData(sheet);
-                return acc;
-            }, {}),
-            SheetNames: sheets.map((sheet, index) => sheet.getName() || `Sheet${index + 1}`)
-        };
-    }
-    static generateSheetData(sheet) {
-        const rows = sheet.getRows();
-        const data = [];
-        rows.forEach((row) => {
-            const rowData = [];
-            row.getCells().forEach((cell) => {
-                const cellData = cell.toData();
-                if (cellData.formula) {
-                    rowData.push({ f: cellData.formula });
-                }
-                else if (cellData.type === 'date' &&
-                    (typeof cellData.value === 'string' ||
-                        typeof cellData.value === 'number' ||
-                        cellData.value instanceof Date)) {
-                    rowData.push(DateFormatter.toExcelDate(cellData.value));
-                }
-                else {
-                    rowData.push(cellData.value);
-                }
-            });
-            data.push(rowData);
-        });
-        return {
-            '!ref': this.getSheetRange(data),
-            '!rows': rows.map(row => ({
-                hpt: row['height'],
-                hidden: row['hidden'],
-                outlineLevel: row['outlineLevel'],
-                collapsed: row['collapsed']
-            })),
-            '!cols': sheet.getColumns().map(col => ({
-                wch: col['width'],
-                hidden: col['hidden'],
-                outlineLevel: col['outlineLevel'],
-                collapsed: col['collapsed']
-            })),
-            '!merges': sheet['mergeCells'],
-            '!freeze': sheet['freezePane']
-        };
-    }
-    static getSheetRange(data) {
-        if (data.length === 0)
-            return 'A1:A1';
-        const lastRow = data.length;
-        const lastCol = Math.max(...data.map(row => row.length));
-        return `A1:${this.columnToLetter(lastCol)}${lastRow}`;
-    }
-    static columnToLetter(column) {
-        let letters = '';
-        while (column > 0) {
-            const temp = (column - 1) % 26;
-            letters = String.fromCharCode(temp + 65) + letters;
-            column = (column - temp - 1) / 26;
-        }
-        return letters || 'A';
-    }
-    static createExcelFile(data) {
-        // This is a simplified Excel file generator
-        // In a real implementation, you'd generate proper XLSX binary format
-        // For now, we'll return a simple XML-based structure
-        const xmlHeader = '<?xml version="1.0" encoding="UTF-8"?>';
-        const workbook = this.generateWorkbookXML(data);
-        const encoder = new TextEncoder();
-        return encoder.encode(xmlHeader + workbook);
-    }
-    static generateWorkbookXML(data) {
-        let xml = '<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">';
-        xml += '<sheets>';
-        data.SheetNames.forEach((name, index) => {
-            xml += `<sheet name="${name}" sheetId="${index + 1}" r:id="rId${index + 1}"/>`;
-        });
-        xml += '</sheets>';
-        xml += '</workbook>';
-        return xml;
-    }
-}
-
 class Workbook {
     constructor(data) {
         this.sheets = [];