{"_id":"@chang-code-hub/univer-import-export","_rev":"3-c6cb0c2816f6725679268a80e00b3bcb","name":"@chang-code-hub/univer-import-export","dist-tags":{"latest":"0.1.42"},"versions":{"0.1.40":{"name":"@chang-code-hub/univer-import-export","version":"0.1.40","keywords":["univer","spreadsheet","excel","csv","import","export","xlsx","xls"],"author":{"name":"mertdeveci chang"},"license":"MIT","_id":"@chang-code-hub/univer-import-export@0.1.40","maintainers":[{"name":"liuchang1992","email":"liuchang_m@163.com"}],"homepage":"https://github.com/chang-code-hub/univerjs-import-export","bugs":{"url":"https://github.com/chang-code-hub/univerjs-import-export/issues"},"dist":{"shasum":"b94e3e07ba8f6d791802a5b1a7ac9459ea4af37e","tarball":"https://registry.npmjs.org/@chang-code-hub/univer-import-export/-/univer-import-export-0.1.40.tgz","fileCount":58,"integrity":"sha512-+eOjRiUCyY3wj07XjnldQrP6oEdgOw6KTaresyGf5mr8N8UOR4GLR/UZFhha9pCNY3HiZ/EMaa0n7jrImpGZsQ==","signatures":[{"sig":"MEQCIAxMa1lDdGMfYRLw/fbcxFVEMYaO2vE7jdqcnKYr+K7OAiAK7Gmt/FSouDVgYW5OvbFY7TUEdnk90a/FAVfv6kasZg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3069315},"main":"dist/luckyexcel.cjs.js","config":{"commitizen":{"path":"cz-conventional-changelog"}},"module":"dist/luckyexcel.esm.js","browser":"dist/luckyexcel.umd.js","exports":{".":{"import":{"types":"./dist/main.esm.d.ts","default":"./dist/luckyexcel.esm.js"},"require":{"types":"./dist/main.umd.d.ts","default":"./dist/luckyexcel.cjs.js"}}},"gitHead":"62d2fe8e29ab81b0b0a6e23e4f3f914a3e917df9","private":false,"scripts":{"dev":"gulp dev","build":"gulp build","release":"release-it","release:beta":"release-it --preRelease=beta"},"typings":"dist/main.esm.d.ts","_npmUser":{"name":"liuchang1992","email":"liuchang_m@163.com"},"browserify":{"transform":["browserify-shim"]},"repository":{"url":"git+https://github.com/chang-code-hub/univerjs-import-export.git","type":"git"},"_npmVersion":"11.3.0","description":"Excel/CSV import and export library for Univer spreadsheets with full format preservation","directories":{},"_nodeVersion":"22.15.0","dependencies":{"xlsx":"^0.18.5","dayjs":"^1.11.13","nanoid":"^3.3.11","xml2js":"^0.6.2","papaparse":"^5.5.3","@univerjs/core":"^0.6.10","@zwight/exceljs":"4.4.2","@zwight/luckyexcel":"^1.1.6","@progress/jszip-esm":"^1.0.4"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"browserify-shim":{"@univerjs/core":"global:UniverCore"},"devDependencies":{"gulp":"^5.0.1","husk":"^0.5.3","tsify":"^5.0.4","tslib":"^2.8.1","delete":"^1.1.0","rollup":"^2.79.2","babelify":"^10.0.0","watchify":"^3.11.1","fancy-log":"^1.3.3","gulp-util":"^3.0.8","browserify":"^17.0.1","release-it":"16.2.1","typescript":"~5.3.3","@babel/core":"^7.28.0","@types/node":"^22.17.0","gulp-uglify":"^3.0.2","browser-sync":"^3.0.4","vinyl-buffer":"^1.0.1","@types/xml2js":"^0.4.14","@commitlint/cli":"^19.8.1","browserify-shim":"^3.8.16","gulp-sourcemaps":"^2.6.5","gulp-typescript":"6.0.0-alpha.1","@types/papaparse":"^5.3.16","@babel/preset-env":"^7.28.0","vinyl-source-stream":"^2.0.0","rollup-plugin-terser":"^7.0.2","@babel/preset-typescript":"^7.27.1","@rollup/plugin-typescript":"^6.1.0","cz-conventional-changelog":"^3.3.0","rollup-plugin-typescript2":"^0.29.0","@commitlint/config-conventional":"^19.8.1","@release-it/conventional-changelog":"7.0.2"},"_npmOperationalInternal":{"tmp":"tmp/univer-import-export_0.1.40_1754990846929_0.9959718658642702","host":"s3://npm-registry-packages-npm-production"}},"0.1.41":{"name":"@chang-code-hub/univer-import-export","version":"0.1.41","keywords":["univer","spreadsheet","excel","csv","import","export","xlsx","xls"],"author":{"name":"mertdeveci chang"},"license":"MIT","_id":"@chang-code-hub/univer-import-export@0.1.41","maintainers":[{"name":"liuchang1992","email":"liuchang_m@163.com"}],"homepage":"https://github.com/chang-code-hub/univerjs-import-export","bugs":{"url":"https://github.com/chang-code-hub/univerjs-import-export/issues"},"dist":{"shasum":"ef5528eb27b56944ee0411c73d19700da6b1fa5e","tarball":"https://registry.npmjs.org/@chang-code-hub/univer-import-export/-/univer-import-export-0.1.41.tgz","fileCount":58,"integrity":"sha512-DQV4Y0rLMH7iqhvlzFeOwdpS983B5eNuS61qmI5nI0Jd7+cVhMxyKr/jpDBhpLVeXFH+Vzrl3dJR6t/0KLfSQw==","signatures":[{"sig":"MEUCIQD/9gSqs6VVBDCehVhUktXJ7TANOLjdyKx57ZZzym2gQgIgF3CNjCPRt3DUqs96DnOYTTEFYVvqr4rV1slIrLYoACs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3068733},"main":"dist/luckyexcel.cjs.js","config":{"commitizen":{"path":"cz-conventional-changelog"}},"module":"dist/luckyexcel.esm.js","browser":"dist/luckyexcel.umd.js","exports":{".":{"import":{"types":"./dist/main.esm.d.ts","default":"./dist/luckyexcel.esm.js"},"require":{"types":"./dist/main.umd.d.ts","default":"./dist/luckyexcel.cjs.js"}}},"gitHead":"6ad016338c220c4be404baf1b22a96636ac50faa","private":false,"scripts":{"dev":"gulp dev","build":"gulp build","release":"release-it","release:beta":"release-it --preRelease=beta"},"typings":"dist/main.esm.d.ts","_npmUser":{"name":"liuchang1992","email":"liuchang_m@163.com"},"browserify":{"transform":["browserify-shim"]},"repository":{"url":"git+https://github.com/chang-code-hub/univerjs-import-export.git","type":"git"},"_npmVersion":"11.3.0","description":"Excel/CSV import and export library for Univer spreadsheets with full format preservation","directories":{},"_nodeVersion":"22.15.0","dependencies":{"xlsx":"^0.18.5","dayjs":"^1.11.13","nanoid":"^3.3.11","xml2js":"^0.6.2","papaparse":"^5.5.3","@univerjs/core":"^0.6.10","@zwight/exceljs":"4.4.2","@zwight/luckyexcel":"^1.1.6","@progress/jszip-esm":"^1.0.4"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"browserify-shim":{"@univerjs/core":"global:UniverCore"},"devDependencies":{"gulp":"^5.0.1","husk":"^0.5.3","tsify":"^5.0.4","tslib":"^2.8.1","delete":"^1.1.0","rollup":"^2.79.2","babelify":"^10.0.0","watchify":"^3.11.1","fancy-log":"^1.3.3","gulp-util":"^3.0.8","browserify":"^17.0.1","release-it":"16.2.1","typescript":"~5.3.3","@babel/core":"^7.28.0","@types/node":"^22.17.0","gulp-uglify":"^3.0.2","browser-sync":"^3.0.4","vinyl-buffer":"^1.0.1","@types/xml2js":"^0.4.14","@commitlint/cli":"^19.8.1","browserify-shim":"^3.8.16","gulp-sourcemaps":"^2.6.5","gulp-typescript":"6.0.0-alpha.1","@types/papaparse":"^5.3.16","@babel/preset-env":"^7.28.0","vinyl-source-stream":"^2.0.0","rollup-plugin-terser":"^7.0.2","@babel/preset-typescript":"^7.27.1","@rollup/plugin-typescript":"^6.1.0","cz-conventional-changelog":"^3.3.0","rollup-plugin-typescript2":"^0.29.0","@commitlint/config-conventional":"^19.8.1","@release-it/conventional-changelog":"7.0.2"},"_npmOperationalInternal":{"tmp":"tmp/univer-import-export_0.1.41_1755008686725_0.7391709572853591","host":"s3://npm-registry-packages-npm-production"}},"0.1.42":{"name":"@chang-code-hub/univer-import-export","version":"0.1.42","description":"Excel/CSV import and export library for Univer spreadsheets with full format preservation","private":false,"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"main":"dist/luckyexcel.cjs.js","module":"dist/luckyexcel.esm.js","browser":"dist/luckyexcel.umd.js","typings":"dist/main.esm.d.ts","exports":{".":{"import":{"types":"./dist/main.esm.d.ts","default":"./dist/luckyexcel.esm.js"},"require":{"types":"./dist/main.umd.d.ts","default":"./dist/luckyexcel.cjs.js"}}},"browserify":{"transform":["browserify-shim"]},"browserify-shim":{"@univerjs/core":"global:UniverCore"},"scripts":{"build":"gulp build","dev":"gulp dev","release":"release-it","release:beta":"release-it --preRelease=beta"},"keywords":["univer","spreadsheet","excel","csv","import","export","xlsx","xls"],"author":{"name":"mertdeveci chang"},"homepage":"https://github.com/chang-code-hub/univerjs-import-export","repository":{"type":"git","url":"git+https://github.com/chang-code-hub/univerjs-import-export.git"},"bugs":{"url":"https://github.com/chang-code-hub/univerjs-import-export/issues"},"license":"MIT","devDependencies":{"@babel/core":"^7.28.0","@babel/preset-env":"^7.28.0","@babel/preset-typescript":"^7.27.1","@commitlint/cli":"^19.8.1","@commitlint/config-conventional":"^19.8.1","@release-it/conventional-changelog":"7.0.2","@rollup/plugin-typescript":"^6.1.0","@types/node":"^22.17.0","@types/papaparse":"^5.3.16","@types/xml2js":"^0.4.14","babelify":"^10.0.0","browser-sync":"^3.0.4","browserify":"^17.0.1","browserify-shim":"^3.8.16","cz-conventional-changelog":"^3.3.0","delete":"^1.1.0","fancy-log":"^1.3.3","gulp":"^5.0.1","gulp-sourcemaps":"^2.6.5","gulp-typescript":"6.0.0-alpha.1","gulp-uglify":"^3.0.2","gulp-util":"^3.0.8","husk":"^0.5.3","release-it":"16.2.1","rollup":"^2.79.2","rollup-plugin-terser":"^7.0.2","rollup-plugin-typescript2":"^0.29.0","tsify":"^5.0.4","tslib":"^2.8.1","typescript":"~5.3.3","vinyl-buffer":"^1.0.1","vinyl-source-stream":"^2.0.0","watchify":"^3.11.1"},"dependencies":{"@progress/jszip-esm":"^1.0.4","@univerjs/core":"^0.6.10","@zwight/exceljs":"4.4.2","@zwight/luckyexcel":"^1.1.6","dayjs":"^1.11.13","nanoid":"^3.3.11","papaparse":"^5.5.3","xlsx":"^0.18.5","xml2js":"^0.6.2"},"config":{"commitizen":{"path":"cz-conventional-changelog"}},"_id":"@chang-code-hub/univer-import-export@0.1.42","gitHead":"0644cb5b943ebbc7f1fc997e22fbcc619d964250","_nodeVersion":"22.15.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-Nr5PdI4n4715KwRSZePomI5sUNWFSRgDvySMQHlKaOv8vPmMB1LkFtE44L6M8DTZov6yk9ACihsYm0F8kGtQ0w==","shasum":"2034d10f4c654a81ef3bdeb06018431d8d8e888b","tarball":"https://registry.npmjs.org/@chang-code-hub/univer-import-export/-/univer-import-export-0.1.42.tgz","fileCount":58,"unpackedSize":3069118,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAr61TA1DUjFzArfMlpYJxC3JsPj7FDjExu5j4nRN1TzAiEA+z39lrT1/ERWdgAwhPJTQAMTKcfTYSzqTO8PsIB6c4Y="}]},"_npmUser":{"name":"liuchang1992","email":"liuchang_m@163.com"},"directories":{},"maintainers":[{"name":"liuchang1992","email":"liuchang_m@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/univer-import-export_0.1.42_1755010372533_0.2551806404291288"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-12T09:27:26.844Z","modified":"2025-08-12T14:52:53.347Z","0.1.40":"2025-08-12T09:27:27.156Z","0.1.41":"2025-08-12T14:24:46.996Z","0.1.42":"2025-08-12T14:52:52.816Z"},"bugs":{"url":"https://github.com/chang-code-hub/univerjs-import-export/issues"},"author":{"name":"mertdeveci chang"},"license":"MIT","homepage":"https://github.com/chang-code-hub/univerjs-import-export","keywords":["univer","spreadsheet","excel","csv","import","export","xlsx","xls"],"repository":{"type":"git","url":"git+https://github.com/chang-code-hub/univerjs-import-export.git"},"description":"Excel/CSV import and export library for Univer spreadsheets with full format preservation","maintainers":[{"name":"liuchang1992","email":"liuchang_m@163.com"}],"readme":"# @mertdeveci55/univer-import-export\r\n\r\nA robust Excel/CSV import and export library for [Univer](https://github.com/dream-num/univer) spreadsheets with full format preservation, including formulas, styling, charts, and conditional formatting.\r\n\r\n[![npm version](https://img.shields.io/npm/v/@mertdeveci55/univer-import-export.svg)](https://www.npmjs.com/package/@mertdeveci55/univer-import-export)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n\r\n## Features\r\n\r\n✅ **Import Support**\r\n- Excel files (.xlsx, .xls)\r\n- CSV files (.csv)\r\n- Preserves ALL sheets (including empty ones)\r\n- Handles special characters in sheet names (>>>, etc.)\r\n- Maintains exact sheet order\r\n- Full styling preservation (fonts, colors, borders, alignment)\r\n- Formula and calculated value retention (including TRANSPOSE and array formulas)\r\n- Merged cells support\r\n- Images and charts\r\n- Conditional formatting\r\n- Data validation\r\n- Hyperlinks and rich text\r\n\r\n✅ **Export Support**\r\n- Excel files (.xlsx)\r\n- CSV files (.csv)\r\n- Full formatting preservation\r\n- Formula export\r\n- Named ranges\r\n- Multiple sheets\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @mertdeveci55/univer-import-export\r\n```\r\n\r\nor\r\n\r\n```bash\r\nyarn add @mertdeveci55/univer-import-export\r\n```\r\n\r\n## Usage\r\n\r\n### Import Excel to Univer\r\n\r\n```javascript\r\nimport { LuckyExcel } from '@mertdeveci55/univer-import-export';\r\n\r\n// Handle file input\r\nconst fileInput = document.getElementById('file-input');\r\nfileInput.addEventListener('change', (e) => {\r\n    const file = e.target.files[0];\r\n    \r\n    LuckyExcel.transformExcelToUniver(\r\n        file,\r\n        (univerData) => {\r\n            // Use the Univer data\r\n            console.log('Converted data:', univerData);\r\n            \r\n            // Create Univer instance with the data\r\n            univer.createUnit(UniverInstanceType.UNIVER_SHEET, univerData);\r\n        },\r\n        (error) => {\r\n            console.error('Import error:', error);\r\n        }\r\n    );\r\n});\r\n```\r\n\r\n### Import CSV to Univer\r\n\r\n```javascript\r\nimport { LuckyExcel } from '@mertdeveci55/univer-import-export';\r\n\r\nLuckyExcel.transformCsvToUniver(\r\n    csvFile,\r\n    (univerData) => {\r\n        // Use the converted CSV data\r\n        univer.createUnit(UniverInstanceType.UNIVER_SHEET, univerData);\r\n    },\r\n    (error) => {\r\n        console.error('CSV import error:', error);\r\n    }\r\n);\r\n```\r\n\r\n### Export Univer to Excel\r\n\r\n```javascript\r\nimport { LuckyExcel } from '@mertdeveci55/univer-import-export';\r\n\r\n// Get Univer snapshot\r\nconst snapshot = univer.getActiveWorkbook().save();\r\n\r\nLuckyExcel.transformUniverToExcel({\r\n    snapshot: snapshot,\r\n    fileName: 'my-spreadsheet.xlsx',\r\n    success: () => {\r\n        console.log('Export successful');\r\n    },\r\n    error: (err) => {\r\n        console.error('Export error:', err);\r\n    }\r\n});\r\n```\r\n\r\n### Export Univer to CSV\r\n\r\n```javascript\r\nimport { LuckyExcel } from '@mertdeveci55/univer-import-export';\r\n\r\nconst snapshot = univer.getActiveWorkbook().save();\r\n\r\nLuckyExcel.transformUniverToCsv({\r\n    snapshot: snapshot,\r\n    fileName: 'my-data.csv',\r\n    sheetName: 'Sheet1', // Optional: specific sheet to export\r\n    success: () => {\r\n        console.log('CSV export successful');\r\n    },\r\n    error: (err) => {\r\n        console.error('CSV export error:', err);\r\n    }\r\n});\r\n```\r\n\r\n## API Reference\r\n\r\n### `LuckyExcel.transformExcelToUniver(file, callback, errorHandler)`\r\n\r\nConverts Excel file to Univer format.\r\n\r\n- **file**: `File` - The Excel file (.xlsx or .xls)\r\n- **callback**: `(data: IWorkbookData) => void` - Success callback with converted data\r\n- **errorHandler**: `(error: Error) => void` - Error callback\r\n\r\n### `LuckyExcel.transformCsvToUniver(file, callback, errorHandler)`\r\n\r\nConverts CSV file to Univer format.\r\n\r\n- **file**: `File` - The CSV file\r\n- **callback**: `(data: IWorkbookData) => void` - Success callback\r\n- **errorHandler**: `(error: Error) => void` - Error callback\r\n\r\n### `LuckyExcel.transformUniverToExcel(params)`\r\n\r\nExports Univer data to Excel file.\r\n\r\n**Parameters object:**\r\n- **snapshot**: `any` - Univer workbook snapshot\r\n- **fileName**: `string` - Output filename (optional, default: `excel_[timestamp].xlsx`)\r\n- **getBuffer**: `boolean` - Return buffer instead of downloading (optional, default: false)\r\n- **success**: `(buffer?: Buffer) => void` - Success callback\r\n- **error**: `(err: Error) => void` - Error callback\r\n\r\n### `LuckyExcel.transformUniverToCsv(params)`\r\n\r\nExports Univer data to CSV file.\r\n\r\n**Parameters object:**\r\n- **snapshot**: `any` - Univer workbook snapshot\r\n- **fileName**: `string` - Output filename (optional, default: `csv_[timestamp].csv`)\r\n- **sheetName**: `string` - Specific sheet to export (optional, exports all if not specified)\r\n- **getBuffer**: `boolean` - Return content instead of downloading (optional, default: false)\r\n- **success**: `(content?: string) => void` - Success callback\r\n- **error**: `(err: Error) => void` - Error callback\r\n\r\n## Browser Support\r\n\r\nThe library works in all modern browsers that support:\r\n- ES6+\r\n- File API\r\n- Blob API\r\n\r\n## Project Structure\r\n\r\n```\r\nsrc/\r\n├── ToLuckySheet/         # Excel → LuckySheet conversion\r\n│   ├── LuckyFile.ts      # Main file orchestrator - handles sheet discovery\r\n│   ├── LuckySheet.ts     # Individual sheet processor\r\n│   ├── ReadXml.ts        # XML parser with special character escaping\r\n│   ├── LuckyCell.ts      # Cell data processor\r\n│   └── ...\r\n├── LuckyToUniver/        # LuckySheet → Univer conversion\r\n│   ├── UniverWorkBook.ts # Workbook structure converter\r\n│   ├── UniverSheet.ts    # Sheet data converter\r\n│   └── ...\r\n├── UniverToExcel/        # Univer → Excel export\r\n│   ├── Workbook.ts       # Excel workbook builder using ExcelJS\r\n│   └── ...\r\n├── HandleZip.ts          # ZIP file operations using JSZip\r\n└── main.ts               # Entry point with public API\r\n\r\ndist/                     # Built output (ESM, CJS, UMD formats)\r\npublish.sh                # Automated publishing script\r\ngulpfile.js              # Build configuration\r\nCLAUDE.md                # Detailed technical documentation\r\n```\r\n\r\n## Key Implementation Details\r\n\r\n### Special Character Handling\r\nSheet names with special characters (like `>>>`) are handled through an escape/unescape mechanism in `src/ToLuckySheet/ReadXml.ts`:\r\n\r\n```javascript\r\n// Escapes \">\" to \"__GT__\" before XML parsing\r\nescapeXmlAttributes(xmlString)\r\n// Restores \"__GT__\" back to \">\" after parsing\r\nunescapeXmlAttributes(xmlString)\r\n```\r\n\r\n### Empty Sheet Preservation\r\nAll sheets are preserved during import, even if completely empty. This maintains Excel file structure integrity.\r\n\r\n### Formula Support\r\nComprehensive formula support including:\r\n- Standard formulas (SUM, AVERAGE, IF, VLOOKUP, etc.)\r\n- Array formulas\r\n- TRANSPOSE formulas with proper array handling\r\n- Shared formulas\r\n- Named range references\r\n\r\n## Development\r\n\r\n### Building\r\n\r\n```bash\r\nnpm install\r\nnpm run build   # Uses gulp to compile TypeScript and bundle\r\n```\r\n\r\n### Publishing\r\n\r\nAlways use the publish script for releases:\r\n\r\n```bash\r\n./publish.sh\r\n```\r\n\r\nThis script:\r\n1. Builds the project\r\n2. Increments version\r\n3. Commits changes\r\n4. Pushes to GitHub\r\n5. Publishes to npm\r\n\r\n### Testing\r\n\r\n```bash\r\nnpm test\r\n```\r\n\r\n## Key Improvements\r\n\r\n### v0.1.40 (Latest) - Streamlined Export System\r\n1. **Excel Compatibility**: Eliminated Excel recovery warnings completely\r\n2. **Surgical Post-Processing**: Conservative backend fixes that preserve all data integrity\r\n3. **Production Safety**: Reverted experimental fixes that caused corruption\r\n4. **Documentation**: Comprehensive documentation of remaining limitations and workarounds\r\n\r\n### v0.1.39 - Backend Integration\r\n1. **openpyxl Integration**: Full backend post-processing system for ExcelJS limitations\r\n2. **Defined Names Fix**: Complete solution for named ranges using Python/Django backend\r\n3. **Dual-Mode Export**: Frontend + backend export with automatic fallback\r\n\r\n### v0.1.24 - Core Stability\r\n1. **Special Character Support**: Handles sheet names with `>>>` and other special characters via escape/unescape mechanism\r\n2. **Empty Sheet Preservation**: Empty sheets are never skipped during import\r\n3. **No Hardcoded Solutions**: Removed all hardcoded sheet additions - all solutions are generic\r\n4. **Sheet Order**: Maintains exact sheet order from original file\r\n5. **Style Preservation**: Complete style mapping including bold, italic, colors, borders\r\n6. **Formula Handling**: Preserves both formulas and calculated values, including TRANSPOSE\r\n7. **XLS Support**: Automatic conversion of .xls files to .xlsx format\r\n8. **Better Error Handling**: Comprehensive error messages and detailed logging\r\n\r\n## Dependencies\r\n\r\n### Core Dependencies\r\n- [`@progress/jszip-esm`](https://www.npmjs.com/package/@progress/jszip-esm) - ZIP file handling for Excel files\r\n- [`@zwight/exceljs`](https://www.npmjs.com/package/@zwight/exceljs) - Excel file structure (export)\r\n- [`@univerjs/core`](https://github.com/dream-num/univer) - Univer core types and interfaces\r\n- [`dayjs`](https://day.js.org/) - Date manipulation for Excel dates\r\n- [`papaparse`](https://www.papaparse.com/) - CSV parsing\r\n- [`xlsx`](https://sheetjs.com/) - Additional Excel format support\r\n\r\n### Build Dependencies\r\n- `gulp` - Build orchestration\r\n- `rollup` - Module bundling\r\n- `typescript` - Type safety\r\n- `terser` - Minification (configured to preserve console.logs)\r\n\r\n## Related Projects & References\r\n\r\n### Core Dependencies\r\n- **[Univer](https://github.com/dream-num/univer)** - The spreadsheet engine this library supports\r\n- **[LuckySheet](https://github.com/mengshukeji/Luckysheet)** - Intermediate format inspiration\r\n- **[LuckyExcel](https://github.com/dream-num/Luckyexcel)** - Original codebase this fork is based on\r\n\r\n### Implementation Examples\r\n- **[alphafrontend](https://github.com/mertdeveci/alphafrontend)** - Production implementation\r\n  - See: `src/utils/excel-import.ts` for usage example\r\n  - See: `src/pages/SpreadsheetsPage.tsx` for UI integration\r\n\r\n### Documentation\r\n- **[CLAUDE.md](./CLAUDE.md)** - Detailed technical documentation for AI assistants\r\n- **[publish.sh](./publish.sh)** - Automated publishing script\r\n- **[gulpfile.js](./gulpfile.js)** - Build configuration\r\n\r\n## Known Issues & Solutions\r\n\r\n### ✅ Resolved Issues\r\n\r\n| Issue | Solution | Version Fixed |\r\n|-------|----------|---------------|\r\n| Sheets with special characters (>>>) not importing | Escape/unescape mechanism in ReadXml.ts | v0.1.23+ |\r\n| AttributeList undefined errors | Defensive initialization | v0.1.21+ |\r\n| Duplicate sheets appearing | Removed hardcoded sheet additions | v0.1.24 |\r\n| TRANSPOSE formulas not working | Array formula support | v0.1.18+ |\r\n| Border styles not importing | Added style collection in UniverWorkBook | v0.1.38 |\r\n\r\n### ⚠️ Export Limitations & Solutions\r\n\r\nDue to limitations in the underlying ExcelJS library, some advanced Excel features have issues during **export**. However, we provide comprehensive solutions:\r\n\r\n## 🔧 **Backend Post-Processing Solution**\r\n\r\nFor production applications, we recommend using backend post-processing to achieve **100% Excel compatibility**:\r\n\r\n### **Architecture**\r\n```\r\nFrontend Export → Backend API → openpyxl Post-Processing → Fixed Excel File\r\n```\r\n\r\n### **Django Integration Example**\r\n```python\r\nfrom spreadsheets.import_export import UniverToExcelConverter, ExcelPostProcessor\r\n\r\n# Step 1: Export with existing functionality (preserves all working features)\r\nconverter = UniverToExcelConverter()\r\nexcel_buffer = converter.convert(univer_data)\r\n\r\n# Step 2: Apply surgical fixes for ExcelJS limitations\r\npost_processor = ExcelPostProcessor()\r\nfixed_buffer = post_processor.process_excel_buffer(\r\n    excel_buffer.getvalue(), \r\n    univer_data\r\n)\r\n```\r\n\r\n### **What Gets Fixed**\r\n- ✅ **Defined Names**: All named ranges work perfectly in Excel\r\n- ✅ **Array Formula Attributes**: Proper XML attributes for spill ranges\r\n- ✅ **Excel 365 Compatibility**: Full support for modern Excel features\r\n- ✅ **Performance**: ~7ms processing overhead\r\n- ✅ **Safety**: Preserves ALL existing functionality\r\n\r\n### **Frontend Integration**\r\n```typescript\r\n// Enhanced export with backend post-processing\r\nconst result = await exportToExcel({\r\n  workbookData,\r\n  fileName: 'spreadsheet.xlsx',\r\n  useBackendExport: true,        // Enable backend processing\r\n  enablePostProcessing: true,    // Fix ExcelJS limitations\r\n  exportSpreadsheetToExcel: api.exportSpreadsheetToExcel\r\n});\r\n\r\n// Automatic fallback to frontend if backend unavailable\r\nif (result.stats?.postProcessingApplied) {\r\n  console.log('✅ Enhanced Excel compatibility applied!');\r\n}\r\n```\r\n\r\n### **Setup Requirements**\r\n1. **Python Backend** with `openpyxl` installed\r\n2. **API Endpoint** for post-processing  \r\n3. **Optional**: Feature flag for gradual rollout\r\n\r\n## 📊 **Current Export Status (v0.1.40)**\r\n\r\n### ✅ **Fully Working Features**\r\n- ✅ **Excel Compatibility**: Files open without recovery warnings\r\n- ✅ **Data Integrity**: All formulas, values, and structure preserved perfectly\r\n- ✅ **Named Ranges**: All defined names work correctly in Excel (fixed in backend)\r\n- ✅ **Import Operations**: 100% functionality preserved for all Excel features\r\n\r\n### ⚠️ **Known Visual/Display Issues** \r\n| Issue | Impact | Status | Workaround |\r\n|-------|--------|---------|------------|\r\n| **TRANSPOSE @ Symbols** | Formulas show `=@TRANSPOSE(@$N$43:$N$45)` | Cosmetic only - calculations work | Document as known issue |\r\n| **Border Style Changes** | Dashed borders may become solid | Visual styling only | Original design preserved in import |\r\n| **ExcelJS Core Limitations** | Some advanced Excel features not supported | Library limitation | Use backend post-processing |\r\n\r\n### 🔧 **Backend Post-Processing (Recommended)**\r\n\r\n**Status**: Production-ready surgical fixes for maximum Excel compatibility.\r\n\r\n**What it fixes**:\r\n- ✅ Removes Excel recovery warnings completely\r\n- ✅ Ensures all named ranges work perfectly\r\n- ✅ Maintains 100% data integrity and formula accuracy\r\n\r\n**What it doesn't fix (by design)**:\r\n- ⚠️ TRANSPOSE @ symbols (requires ExcelJS core changes)\r\n- ⚠️ Border style inconsistencies (requires ExcelJS improvements)\r\n\r\n**Performance**: ~7ms overhead for complete Excel compatibility.\r\n\r\n**Import functionality works perfectly** - these limitations only affect export operations.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please ensure:\r\n\r\n1. **No hardcoded solutions** - All fixes must be generic\r\n2. **Extensive logging** - Add console.log for debugging\r\n3. **Use publish.sh** - Never manually publish to npm\r\n4. **Test edge cases** - Including special characters, empty sheets\r\n5. **Follow existing patterns** - Check CLAUDE.md for architecture\r\n\r\n## License\r\n\r\nMIT © mertdeveci\r\n\r\n## Credits\r\n\r\n- Original [LuckyExcel](https://github.com/dream-num/Luckyexcel) by DreamNum\r\n- [Univer](https://github.com/dream-num/univer) spreadsheet engine\r\n- All contributors and issue reporters\r\n\r\n## Support\r\n\r\nFor issues and feature requests:\r\n- [GitHub Issues](https://github.com/mertdeveci/univerjs-import-export/issues)\r\n- Check [CLAUDE.md](./CLAUDE.md) for technical details\r\n- Review closed issues for solutions","readmeFilename":"README.md"}