react-native-nitro-xlsx 0.1.2 → 0.2.5

package/NOTICE

@@ -4,7 +4,8 @@ This software uses third-party open source components listed below, with full li
 ================================================================================
 1. OpenXLSX
 Repository: https://github.com/troldal/OpenXLSX
-License: BSD 3-Clause License
+Version: 0.5.1
+License: BSD 3-Clause License (SPDX: BSD-3-Clause)
 Copyright (c) 2020 Kenneth Troldal Balslev
 
 Full BSD 3-Clause License text:
@@ -27,7 +28,7 @@ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 2. react-native-nitro-modules
 Repository: https://github.com/mrousavy/nitro
 Version: 0.58.3
-License: MIT License
+License: MIT License (SPDX: MIT)
 Copyright (c) 2024 Marc Rousavy
 
 Full MIT License text:
@@ -56,7 +57,8 @@ SOFTWARE.
 ================================================================================
 3. pugixml (OpenXLSX dependency)
 Repository: https://github.com/zeux/pugixml
-License: MIT License
+Version: 1.16
+License: MIT License (SPDX: MIT)
 Copyright (c) 2006-2024 Arseny Kapoulkine
 
 Full MIT License text:
@@ -72,39 +74,10 @@ The above copyright notice and this permission notice shall be included in all c
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ================================================================================
-4. Zippy (OpenXLSX dependency)
-Repository: https://github.com/troldal/Zippy
-License: MIT License
-Copyright (c) 2019 Kenneth Troldal Balslev
-
-Full MIT License text:
-
-MIT License
-
-Copyright (c) 2019 Kenneth Troldal Balslev
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
-================================================================================
-5. miniz (OpenXLSX dependency)
+4. miniz (OpenXLSX dependency)
 Repository: https://github.com/richgel999/miniz
-License: MIT License
+Version: 3.1.2
+License: MIT License (SPDX: MIT)
 Copyright (c) 2013-2014 RAD Game Tools and Valve Software
 Copyright (c) 2010-2014 Rich Geldreich and Tenacious Software LLC
 

package/NitroXlsx.podspec

@@ -11,12 +11,17 @@ Pod::Spec.new do |s|
   s.authors      = package["author"]
 
   s.platforms    = { :ios => "15.1" }
-  s.source       = { :git => "", :tag => "#{s.version}" }
+  s.source       = { :git => "https://github.com/zydbkqf/react-native-nitro-xlsx.git", :tag => "#{s.version}" }
 
-  s.exclude_files = "cpp/tests/**/*"
+  s.exclude_files = [
+    "cpp/tests/**/*",
+    "OpenXLSX/ThirdParty/miniz/tests/**/*",
+    "OpenXLSX/ThirdParty/miniz/examples/**/*",
+  ]
 
   s.source_files = [
     "cpp/**/*.{h,hpp,cpp}",
+    "ios/**/*.{h,hpp,mm}",
     "OpenXLSX/OpenXLSX/**/*.hpp",
     "OpenXLSX/OpenXLSX/**/*.cpp",
     "OpenXLSX/ThirdParty/pugixml/src/**/*.hpp",
@@ -49,61 +54,20 @@ Pod::Spec.new do |s|
     "HEADER_SEARCH_PATHS" => "$(inherited) ${PODS_TARGET_SRCROOT}/OpenXLSX ${PODS_TARGET_SRCROOT}/OpenXLSX/OpenXLSX ${PODS_TARGET_SRCROOT}/OpenXLSX/OpenXLSX/headers ${PODS_TARGET_SRCROOT}/OpenXLSX/ThirdParty/pugixml/src ${PODS_TARGET_SRCROOT}/OpenXLSX/ThirdParty/miniz",
   }
 
-  s.prepare_command = <<-CMD
-    if [ ! -d "OpenXLSX" ]; then
-      git clone --depth 1 --branch v0.5.1 https://github.com/troldal/OpenXLSX.git
-    fi
-    mkdir -p OpenXLSX/ThirdParty
-    if [ ! -d "OpenXLSX/ThirdParty/pugixml" ]; then
-      git clone --depth 1 --branch v1.15 https://github.com/zeux/pugixml.git OpenXLSX/ThirdParty/pugixml
-    fi
-    if [ ! -d "OpenXLSX/ThirdParty/miniz" ]; then
-      git clone --depth 1 --branch 3.0.2 https://github.com/richgel999/miniz.git OpenXLSX/ThirdParty/miniz
-    fi
-    if [ ! -f "OpenXLSX/ThirdParty/miniz/miniz_export.h" ]; then
-      cat > OpenXLSX/ThirdParty/miniz/miniz_export.h << 'EOF'
-#ifndef MINIZ_EXPORT_H
-#define MINIZ_EXPORT_H
-
-#ifndef MINIZ_EXPORT
-#define MINIZ_EXPORT
-#endif
-
-#ifndef MINIZ_DEPRECATED
-#define MINIZ_DEPRECATED
-#endif
-
-#ifndef MINIZ_DEPRECATED_EXPORT
-#define MINIZ_DEPRECATED_EXPORT MINIZ_EXPORT MINIZ_DEPRECATED
-#endif
-
-#ifndef MINIZ_NO_EXPORT
-#define MINIZ_NO_EXPORT
-#endif
-
-#endif
-EOF
-    fi
-    if [ ! -f "OpenXLSX/OpenXLSX/headers/OpenXLSX-Exports.hpp" ]; then
-      cat > OpenXLSX/OpenXLSX/headers/OpenXLSX-Exports.hpp << 'EOF'
-#ifndef OPENXLSX_EXPORTS_HPP
-#define OPENXLSX_EXPORTS_HPP
-
-#ifndef OPENXLSX_EXPORT
-#define OPENXLSX_EXPORT
-#endif
-
-#ifndef OPENXLSX_HIDDEN
-#define OPENXLSX_HIDDEN
-#endif
-
-#endif
-EOF
-    fi
-    if [ ! -d "OpenXLSX/OpenXLSX/headers/OpenXLSX" ]; then
-      cd OpenXLSX/OpenXLSX/headers && ln -sf . OpenXLSX && cd -
-    fi
-  CMD
+  # Prepare OpenXLSX and its dependencies (pugixml, miniz) via a Node script
+  # so the same logic can be reused from both CocoaPods and Android CMake.
+  s.prepare_command = "node #{__dir__}/scripts/prepare-openxlsx.js"
+
+  # Swift Package Manager declaration for React Native 0.87+.
+  # This exposes NitroXlsx as a local Swift package; the heavy lifting for
+  # OpenXLSX is still done by the prepare command above.
+  if ENV['NITRO_XLSX_USE_SPM'] == '1' && defined?(SPM) && SPM.respond_to?(:dependency)
+    SPM.dependency(s,
+      url: File.join(__dir__, "."),
+      requirement: { kind: 'upToNextMajorVersion', minimumVersion: s.version.to_s },
+      products: ['NitroXlsx']
+    )
+  end
 
   load 'nitrogen/generated/ios/NitroXlsx+autolinking.rb'
   add_nitrogen_files(s)

package/Package.swift

@@ -0,0 +1,35 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+// NOTE: This Package.swift is a Swift Package Manager manifest stub for
+// React Native 0.87+ compatibility. The library is still primarily built
+// through CocoaPods (NitroXlsx.podspec), where OpenXLSX, pugixml and miniz
+// are cloned and compiled from source by scripts/prepare-openxlsx.js.
+//
+// The local package reference below lets RN 0.87's spm_dependency helper
+// register NitroXlsx in the Pods project when SwiftPM mode is enabled.
+// Full SPM-based compilation of the C++ sources is not yet supported —
+// ios/XlsxCacheDir.mm is listed so the target has a real source file.
+
+let package = Package(
+    name: "NitroXlsx",
+    platforms: [
+        .iOS(.v15)
+    ],
+    products: [
+        .library(
+            name: "NitroXlsx",
+            targets: ["NitroXlsx"]
+        )
+    ],
+    targets: [
+        .target(
+            name: "NitroXlsx",
+            path: "ios",
+            sources: ["XlsxCacheDir.mm"],
+            cxxSettings: [
+                .headerSearchPath("../cpp")
+            ]
+        )
+    ]
+)

package/README.md

@@ -6,12 +6,19 @@ A React Native module for reading and writing Excel XLSX files using [OpenXLSX](
 
 - 📊 Full Excel XLSX file creation support
 - 📖 Read existing XLSX files (from file path or buffer)
-- 📝 Formula support (with default values)
-- 📅 Date/DateTime support
-- 🖼️ Image insertion (from file path or buffer)
-- 🎨 Rich formatting (fonts, colors, borders, alignment)
-- 📄 Page setup (margins, orientation, headers/footers)
-- 🔒 Sheet protection
+- 📝 Formula support (with default values) & array formulas
+- 📅 Date / DateTime support
+- 🔗 Hyperlinks (URLs)
+- 🔄 JSON import / export (`fromJSON` / `toJSON`)
+- 🎨 Rich formatting (fonts, colors, borders, alignment, number formats)
+- 🔒 Sheet protection (password, objects/scenarios, fine-grained allow/deny)
+- 📋 Cell comments (get / set / delete, multi-author)
+- 🔤 Conditional formatting rules
+- 🗂️ Sheet management (delete / rename / clone)
+- ➕ Row/column delete, merge / unmerge
+- 🧩 Hidden rows/columns
+- 🔍 Read cells (value, type, format, formula) + findCell
+- ⚠️ Structured native error codes mapped to JS
 - 📦 Export as ArrayBuffer - no file system required!
 
 ## Installation
@@ -22,6 +29,8 @@ npm install react-native-nitro-xlsx
 yarn add react-native-nitro-xlsx
 ```
 
+> **Note**: Native dependencies (OpenXlsx) are downloaded from GitHub during the first build. Please make sure you have a stable network connection.
+
 ### iOS
 
 ```sh
@@ -122,13 +131,73 @@ const fontName = format.getFontName();
 const fontSize = format.getFontSize();
 ```
 
+### Working with JSON
+
+Per-sheet conversion lives on `XlsxWorksheet`. Workbook-level conversion uses a
+`Record` keyed by worksheet name.
+
+#### Export a worksheet (`sheet.toJSON`)
+
+Convert one worksheet's data to an array of records. By default, the first row is used as object keys.
+
+```typescript
+const sheet = workbook.getWorksheetByName('Data');
+
+// Use the first row as keys (default)
+const rows = sheet.toJSON();
+// Result: [{ "Name": "Alice", "Age": 30 }, { "Name": "Bob", "Age": 25 }]
+
+// Provide custom keys
+const rows2 = sheet.toJSON(['firstName', 'yearsOld']);
+// Result: [{ "firstName": "Alice", "yearsOld": 30 }, ...]
+```
+
+#### Import into a worksheet (`sheet.fromJSON`)
+
+Write an array of records into an existing worksheet. The first record's keys become the header row.
+
+```typescript
+const sheet = workbook.addWorksheet('Data');
+sheet.fromJSON([
+  { Name: 'Alice', Age: 30, Active: true },
+  { Name: 'Bob', Age: 25, Active: false },
+]);
+// Row 1 (header): Active | Age | Name   (keys are sorted alphabetically)
+// Row 2:          true   | 30  | Alice
+// Row 3:          false  | 25  | Bob
+```
+
+#### Export all sheets (`workbook.toJSON`)
+
+Returns a `Record` keyed by worksheet name.
+
+```typescript
+const all = workbook.toJSON();
+// Result: { "Data": [{ Name: 'Alice', ... }], "Summary": [{ ... }] }
+```
+
+#### Create a workbook from multiple sheets (`NitroXlsx.fromJSON`)
+
+Each key becomes a worksheet.
+
+```typescript
+const workbook = NitroXlsx.fromJSON({
+  Data: [{ Name: 'Alice', Age: 30 }],
+  Summary: [{ Total: 1 }],
+});
+// Creates worksheets "Data" and "Summary"
+
+const buffer = await workbook.getBuffer();
+```
+
 ## API
 
 ### NitroXlsx
 
-- `createWorkbook(tempDir?: string): XlsxWorkbook` - Create a new workbook. On Android, pass the app's cache directory (e.g., `RNFS.CachesDirectoryPath`) to avoid sandbox write permission issues.
+- `createWorkbook(): XlsxWorkbook` - Create a new workbook. The native side supplies the platform cache directory automatically (`Context.getCacheDir()` on Android, `NSCachesDirectory` on iOS).
 - `openWorkbook(path: string): XlsxWorkbook` - Open workbook from file path
 - `openWorkbookFromBuffer(buffer: ArrayBuffer): XlsxWorkbook` - Open workbook from buffer
+- `fromJSON(data: Record<string, Array<Record<string, string | number | boolean | null>>>): XlsxWorkbook` - Create a workbook with one worksheet per key (native `AnyMap`s, no JSON round-trip)
 
 ### XlsxWorkbook
 
@@ -137,8 +206,12 @@ const fontSize = format.getFontSize();
 - `getWorksheetByName(name: string): XlsxWorksheet` - Get worksheet by name
 - `getOrAddWorksheet(name: string): XlsxWorksheet` - Get or add worksheet
 - `getWorksheetCount(): number` - Get number of worksheets
+- `deleteSheet(name: string): void` - Delete a worksheet by name
+- `updateSheetName(oldName: string, newName: string): void` - Rename a worksheet and rewrite formula references to it
+- `clone(existingName: string, newName: string): XlsxWorksheet` - Copy a worksheet
 - `addCellFormat(): XlsxCellFormat` - Add a new cell format
 - `getBuffer(): Promise<ArrayBuffer>` - Generate and return the XLSX file as a buffer
+- `toJSON(): Record<string, Array<Record<string, string | number | boolean | null>>>` - Export every worksheet as a `Record` keyed by sheet name
 
 ### XlsxWorksheet
 
@@ -164,7 +237,7 @@ const fontSize = format.getFontSize();
 #### Date/URL
 | Method | Description |
 |--------|-------------|
-| `writeDatetime(row, col, datetime, format?)` | Write a datetime (Excel serial date number) |
+| `writeDatetime(row, col, datetime, format?)` | Write a datetime (1900-based Excel serial date number; see Cell Types) |
 | `writeURL(row, col, url, format?)` | Write a hyperlink |
 
 #### Column/Row
@@ -172,6 +245,8 @@ const fontSize = format.getFontSize();
 |--------|-------------|
 | `setColumn(firstCol, lastCol, width, format?)` | Set column properties |
 | `setRow(row, height, format?)` | Set row properties |
+| `deleteRow(row)` | Delete a row (returns `true` if a row entry existed and was removed) |
+| `deleteColumn(col)` | Delete a column and shift remaining columns left (returns `true` on success) |
 | `setColumnHidden(firstCol, lastCol, hidden)` | Hide/show columns |
 | `setRowHidden(row, hidden)` | Hide/show row |
 
@@ -180,38 +255,75 @@ const fontSize = format.getFontSize();
 |--------|-------------|
 | `mergeRange(firstRow, firstCol, lastRow, lastCol, value, format?)` | Merge cells with string value |
 | `mergeRangeNum(firstRow, firstCol, lastRow, lastCol, value, format?)` | Merge cells with number value |
+| `unmergeCells(firstRow, firstCol, lastRow, lastCol)` | Unmerge a previously merged range |
 
-#### Image
+#### Comments
 | Method | Description |
 |--------|-------------|
-| `insertImage(row, col, path, xOffset?, yOffset?, xScale?, yScale?)` | Insert image from file |
-| `insertImageBuffer(row, col, buffer, extension, xOffset?, yOffset?, xScale?, yScale?)` | Insert image from buffer |
+| `setComment(row, col, text, authorId?)` | Set a cell comment (creates the comments part on first use) |
+| `getComment(row, col)` | Get comment text (empty string if none) |
+| `hasComment(row, col)` | Whether the cell has a comment |
+| `deleteComment(row, col)` | Delete a cell comment (returns `true` if one existed) |
+| `getCommentCount()` | Number of comments on this sheet |
+| `addCommentAuthor(author)` | Register an author, returns its `authorId` |
+| `getCommentAuthor(authorId)` | Get author name by id |
 
 #### View
+
 | Method | Description |
 |--------|-------------|
-| `freezePanes(row, col)` | Freeze panes |
-| `splitPanes(row, col)` | Split panes |
-| `setTabColor(color)` | Set tab color |
 | `hide()` | Hide worksheet |
 | `activate()` | Activate worksheet |
-| `setFirstSheet()` | Set as first sheet |
-| `protect(password?)` | Protect worksheet |
 
-#### Page Setup
+#### Sheet Protection
 | Method | Description |
 |--------|-------------|
-| `setPortrait()` | Set portrait orientation |
-| `setLandscape()` | Set landscape orientation |
-| `setPaper(paperType)` | Set paper size |
-| `setHeader(header)` | Set header |
-| `setFooter(footer)` | Set footer |
-| `setPrintArea(firstRow, firstCol, lastRow, lastCol)` | Set print area |
-| `fitToPages(width, height)` | Fit to pages |
-| `setZoom(scale)` | Set zoom level |
-| `setGridlines(option)` | Set gridlines |
-| `centerHorizontally()` | Center horizontally |
-| `centerVertically()` | Center vertically |
+| `protect(password?)` | Convenience: set optional password and enable sheet protection |
+| `protectSheet(set?)` | Enable/disable sheet protection (`set` defaults to `true`) |
+| `protectObjects(set?)` | Protect drawing objects |
+| `protectScenarios(set?)` | Protect scenarios |
+| `setPassword(password)` | Set password (hashed by Excel algorithm) |
+| `setPasswordHash(hash)` | Set a pre-computed 4-digit hex password hash |
+| `clearPassword()` | Remove the password attribute |
+| `clearSheetProtection()` | Remove `<sheetProtection>` entirely |
+
+Fine-grained permissions (only meaningful while `protectSheet` is on).
+`allow*(set?)` defaults to `true`; `deny*()` is shorthand for `allow*(false)`.
+
+| Allow | Deny | Effect when allowed |
+|-------|------|---------------------|
+| `allowInsertColumns(set?)` | `denyInsertColumns()` | User may insert columns |
+| `allowInsertRows(set?)` | `denyInsertRows()` | User may insert rows |
+| `allowDeleteColumns(set?)` | `denyDeleteColumns()` | User may delete columns |
+| `allowDeleteRows(set?)` | `denyDeleteRows()` | User may delete rows |
+| `allowSelectLockedCells(set?)` | `denySelectLockedCells()` | User may select locked cells |
+| `allowSelectUnlockedCells(set?)` | `denySelectUnlockedCells()` | User may select unlocked cells |
+
+Protection state getters:
+
+| Method | Returns |
+|--------|---------|
+| `sheetProtected()` / `objectsProtected()` / `scenariosProtected()` | Whether the corresponding protection is on |
+| `insertColumnsAllowed()` / `insertRowsAllowed()` | Whether insert is allowed despite protection |
+| `deleteColumnsAllowed()` / `deleteRowsAllowed()` | Whether delete is allowed despite protection |
+| `selectLockedCellsAllowed()` / `selectUnlockedCellsAllowed()` | Whether select is allowed despite protection |
+| `passwordIsSet()` | Whether a password hash is present |
+| `passwordHash()` | The stored password hash (empty if none) |
+| `sheetProtectionSummary()` | Human-readable summary of the protection settings |
+
+Example:
+
+```typescript
+const sheet = workbook.addWorksheet('Locked');
+sheet.writeString(1, 1, 'Protected');
+sheet.setPassword('s3cret');
+sheet.protectSheet();
+sheet.allowDeleteRows();       // users may still delete rows
+sheet.denySelectLockedCells(); // users cannot select locked cells
+console.log(sheet.sheetProtected());           // true
+console.log(sheet.deleteRowsAllowed());        // true
+console.log(sheet.selectLockedCellsAllowed()); // false
+```
 
 #### Read Methods
 | Method | Description |
@@ -221,11 +333,62 @@ const fontSize = format.getFontSize();
 | `getCellRawValue(row, col)` | Get raw cell value |
 | `getCellType(row, col)` | Get cell type |
 | `getCellFormat(row, col)` | Get cell format |
+| `hasFormula(row, col)` | Whether the cell contains a formula |
+| `formula(row, col)` | Get the cell's formula string (empty if none) |
+| `findCell(row, col)` | Whether a cell exists at these coordinates (does **not** create it) |
 | `getRowCount()` | Get total row count |
 | `getColumnCount()` | Get total column count |
 | `getLastRow()` | Get last row index |
 | `getLastColumn()` | Get last column index |
 | `getName()` | Get worksheet name |
+| `toJSON(keys?)` | Export this worksheet as an array of records (`keys` defaults to first-row headers) |
+| `fromJSON(data)` | Write an array of records into this worksheet (first row = header) |
+
+#### Conditional Formatting
+| Method | Description |
+|--------|-------------|
+| `getConditionalFormats()` | Get the worksheet's `XlsxConditionalFormats` collection |
+
+##### XlsxConditionalFormats
+| Method | Description |
+|--------|-------------|
+| `getCount()` | Number of `<conditionalFormatting>` entries |
+| `create(sqref)` | Create a new entry for a range (e.g. `"A1:A10"`), returns `XlsxConditionalFormat` |
+| `getByIndex(index)` | Get an entry by index |
+| `summary()` | Debug summary string |
+
+##### XlsxConditionalFormat
+| Method | Description |
+|--------|-------------|
+| `getSqref()` / `setSqref(sqref)` | The range these rules apply to |
+| `getRuleCount()` / `createRule()` | Manage `cfRule` entries (`createRule` returns the new index) |
+| `getRuleType(index)` / `setRuleType(index, type)` | Rule type — use `CfType` constants |
+| `getRuleDxfId(index)` / `setRuleDxfId(index, dxfId)` | Differential format id |
+| `getRuleFormula(index, formulaIndex)` / `setRuleFormula(index, formulaIndex, formula)` | Rule formula (`formulaIndex` must be `0`; OpenXLSX supports one formula per rule) |
+| `getRuleOperator(index)` / `setRuleOperator(index, op)` | Comparison operator — use `CfOperator` |
+| `getRuleText(index)` / `setRuleText(index, text)` | Text for text-based rules |
+| `getRulePriority(index)` / `setRulePriority(index, priority)` | Rule priority (1-based) |
+| `getRuleStopIfTrue(index)` / `setRuleStopIfTrue(index, stop)` | Stop evaluating further rules |
+| `getRuleTimePeriod(index)` / `setRuleTimePeriod(index, period)` | Time period — use `CfTimePeriod` |
+| `getRuleRank(index)` / `setRuleRank(index, rank)` | Top/bottom N |
+| `getRuleStdDev(index)` / `setRuleStdDev(index, stdDev)` | Standard deviations for aboveAverage |
+| `getRuleAboveAverage` / `setRuleAboveAverage` | aboveAverage flag |
+| `getRulePercent` / `setRulePercent` | percent flag |
+| `getRuleBottom` / `setRuleBottom` | bottom flag |
+| `getRuleEqualAverage` / `setRuleEqualAverage` | equalAverage flag |
+| `summary()` | Debug summary string |
+
+Example:
+
+```typescript
+const cf = sheet.getConditionalFormats().create('B2:B100');
+const ruleIndex = cf.createRule();
+cf.setRuleType(ruleIndex, CfType.CELL_IS);
+cf.setRuleOperator(ruleIndex, CfOperator.GREATER_THAN);
+cf.setRuleFormula(ruleIndex, 0, '100');
+cf.setRuleDxfId(ruleIndex, 0);
+cf.setRulePriority(ruleIndex, 1);
+```
 
 ### XlsxCellFormat
 
@@ -275,9 +438,14 @@ When reading cells, the following types are returned:
 
 - `empty` - Empty cell
 - `string` - Text string
-- `number` - Numeric value
+- `number` - Numeric value. Dates are stored as **Excel serial numbers in the 1900 date system** (days since `1900-01-01`, where `1900-01-01` = `1`, including the spurious `1900-02-29`), and are read back as `number`:
+  ```ts
+  // Excel serial (1900-based) → JS Date
+  const date = new Date(Math.round((serial - 25569) * 86400000));
+  // JS Date → Excel serial (1900-based)
+  const serial = date.getTime() / 86400000 + 25569;
+  ```
 - `boolean` - Boolean value
-- `date` - Date/time value
 - `error` - Error value
 - `formula` - Formula
 - `blank` - Blank cell
@@ -296,7 +464,43 @@ The library exports several useful constants:
 - `Gridlines` - Gridline options
 - `Colors` - Common RGB colors
 - `NumFormat` - Built-in number format indices
-- `ImagePosition` - Image positioning options
+- `CfType` - Conditional formatting rule types
+- `CfOperator` - Conditional formatting comparison operators
+- `CfTimePeriod` - Conditional formatting time periods
+- `XlsxErrorCode` - Native error codes
+
+## Error Handling
+
+Native failures are thrown as JS `Error`s whose message is `methodName: CODE: detail`.
+Convert them to a structured `XlsxError` with `XlsxError.from`:
+
+```typescript
+import { NitroXlsx, XlsxError, XlsxErrorCode } from 'react-native-nitro-xlsx';
+
+try {
+  workbook.deleteSheet('Missing');
+} catch (e) {
+  const err = XlsxError.from(e);
+  if (err.code === XlsxErrorCode.SHEET_NOT_FOUND) {
+    // handle missing sheet
+  }
+}
+```
+
+Error codes:
+
+| Code | Meaning |
+|------|---------|
+| `INVALID_ARGUMENT` | Bad row/col/name or other input |
+| `SHEET_NOT_FOUND` | Worksheet does not exist |
+| `SHEET_EXISTS` | Worksheet name already taken |
+| `INDEX_OUT_OF_RANGE` | Row/col/index out of range |
+| `CELL_NOT_FOUND` | Referenced cell does not exist |
+| `WORKBOOK_CLOSED` | Workbook already finalized via `getBuffer()` |
+| `IO_ERROR` | File open/save failure |
+| `UNSUPPORTED` | Operation not supported by the underlying engine |
+| `XLSX_ERROR` | Generic OpenXLSX failure |
+| `INTERNAL_ERROR` | Unexpected native error |
 
 ## Development
 
@@ -328,17 +532,20 @@ This library is based on OpenXLSX and inherits the following limitations:
 
 The following Excel features are not supported and will be ignored when reading or writing files:
 
-- 🖼️ **Images**: Reading and writing images is not supported. Existing images in XLSX files will be ignored.
 - 📊 **Charts**: Charts, graphs, and sparklines are not supported.
-- ✏️ **Drawings/Shape**: Shapes, lines, arrows, and other drawing objects are not supported.
+- 🖼️ **Drawings/Images/Shapes**: Images, shapes, lines, arrows and other drawing objects fall under OpenXLSX's drawing support, which is not implemented. Existing images in XLSX files are silently ignored.
 - 🔍 **Pivot Tables**: Pivot tables and pivot charts are not supported.
 - 💻 **VBA/Macros**: VBA macros, forms, and ActiveX controls are not supported.
-- 📋 **Comments**: Cell comments and notes are not supported.
 - 📌 **Hyperlinks**: Only basic URL hyperlinks are supported.
-- 🔄 **Conditional Formatting**: Conditional formatting rules are not supported.
 - 📑 **Data Validation**: Data validation rules are not supported.
 
 ### Notes
 
 - When reading XLSX files that contain unsupported features, the library will still read the cell data and formatting, but unsupported elements will be silently ignored.
-- When writing XLSX files, unsupported features cannot be added and will be omitted from the output.
+- When writing XLSX files, unsupported features cannot be added and will be omitted from the output.
+- `deleteColumn` shifts cell values and formats left; formula references are not rewritten (same limitation as OpenXLSX's `deleteRow`).
+- Conditional formatting supports one formula per `cfRule` (OpenXLSX limitation). `colorScale` / `dataBar` / `iconSet` are not supported.
+- `deleteRule` on `XlsxConditionalFormat` always returns `false` (OpenXLSX does not support removing a `cfRule`).
+- Conditional formatting rule `type` / `operator` / `timePeriod` are direct numeric mappings of OpenXLSX enums; passing an out-of-range value results in undefined behavior. Use the exported `CfType` / `CfOperator` / `CfTimePeriod` constants.
+- `setComment` automatically registers an author so the generated `comments.xml` always has a valid `authorId` (verified to open cleanly in Excel/WPS).
+- `getComment` returns an empty string for a cell without a comment (it does not throw). Use `hasComment` first if you need to distinguish.

package/android/CMakeLists.txt

@@ -5,22 +5,21 @@ set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
 set(OPENXLSX_DIR ${CMAKE_SOURCE_DIR}/../OpenXLSX)
-if(NOT EXISTS ${OPENXLSX_DIR}/CMakeLists.txt)
-  # Clean up incomplete directory to ensure fresh clone
-  if(EXISTS ${OPENXLSX_DIR})
-    file(REMOVE_RECURSE ${OPENXLSX_DIR})
-  endif()
 
-  include(FetchContent)
-  FetchContent_Declare(
-    OpenXLSX
-    GIT_REPOSITORY https://github.com/troldal/OpenXLSX.git
-    GIT_TAG v0.5.1
-    SOURCE_DIR ${OPENXLSX_DIR}
-    GIT_SHALLOW TRUE
-    GIT_PROGRESS TRUE
+# Prepare OpenXLSX and its dependencies (pugixml, miniz) using the same
+# Node script that CocoaPods' prepare_command runs on iOS.
+find_program(NODE_EXECUTABLE node REQUIRED)
+execute_process(
+  COMMAND ${NODE_EXECUTABLE} ${CMAKE_SOURCE_DIR}/../scripts/prepare-openxlsx.js
+  WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/..
+  RESULT_VARIABLE PREPARE_RESULT
+)
+if(NOT PREPARE_RESULT EQUAL 0)
+  message(FATAL_ERROR
+    "Failed to prepare OpenXLSX dependencies.\n"
+    "Please ensure Node.js is installed and run:\n"
+    "  node scripts/prepare-openxlsx.js"
   )
-  FetchContent_Populate(OpenXLSX)
 endif()
 
 # Verify OpenXLSX is available
@@ -33,15 +32,6 @@ if(NOT EXISTS ${OPENXLSX_DIR}/CMakeLists.txt)
   )
 endif()
 
-# Create symlink for #include <OpenXLSX/XXX.hpp> resolution
-# Same as iOS podspec: cd OpenXLSX/OpenXLSX/headers && ln -sf . OpenXLSX
-if(NOT EXISTS ${OPENXLSX_DIR}/OpenXLSX/headers/OpenXLSX)
-  execute_process(
-    COMMAND ${CMAKE_COMMAND} -E create_symlink . OpenXLSX
-    WORKING_DIRECTORY ${OPENXLSX_DIR}/OpenXLSX/headers
-  )
-endif()
-
 set(OPENXLSX_BUILD_SAMPLES OFF CACHE BOOL "" FORCE)
 set(OPENXLSX_BUILD_TESTS OFF CACHE BOOL "" FORCE)
 set(OPENXLSX_BUILD_BENCHMARKS OFF CACHE BOOL "" FORCE)
@@ -57,6 +47,10 @@ add_library(
   ../cpp/HybridXlsxWorkbook.cpp
   ../cpp/HybridXlsxWorksheet.cpp
   ../cpp/HybridXlsxCellFormat.cpp
+  ../cpp/HybridXlsxConditionalFormat.cpp
+  ../cpp/HybridXlsxConditionalFormats.cpp
+  ../cpp/XlsxJson.cpp
+  ../cpp/XlsxCacheDir.cpp
   cpp-adapter.cpp
 )
 

package/android/build.gradle

@@ -4,6 +4,11 @@ buildscript {
   }
 }
 
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
 apply plugin: 'com.android.library'
 apply plugin: 'kotlin-android'
 
@@ -16,6 +21,7 @@ android {
     externalNativeBuild {
       cmake {
         arguments "-DANDROID_STL=c++_shared"
+        abiFilters (*reactNativeArchitectures())
       }
     }
   }