react-native-nitro-xlsx 0.1.4 → 0.2.6

package/NitroXlsx.podspec

@@ -13,26 +13,33 @@ Pod::Spec.new do |s|
   s.platforms    = { :ios => "15.1" }
   s.source       = { :git => "https://github.com/zydbkqf/react-native-nitro-xlsx.git", :tag => "#{s.version}" }
 
+  # OpenXLSX, pugixml and miniz are vendored under thirdparty/ and shipped
+  # with the package, so no network access is needed during pod install.
   s.exclude_files = [
     "cpp/tests/**/*",
-    "OpenXLSX/ThirdParty/miniz/tests/**/*",
-    "OpenXLSX/ThirdParty/miniz/examples/**/*",
+    "thirdparty/miniz/tests/**/*",
+    "thirdparty/miniz/examples/**/*",
+    "thirdparty/pugixml/tests/**/*",
+    "thirdparty/OpenXLSX/Tests/**/*",
+    "thirdparty/OpenXLSX/Examples/**/*",
+    "thirdparty/OpenXLSX/Benchmarks/**/*",
   ]
 
   s.source_files = [
     "cpp/**/*.{h,hpp,cpp}",
-    "OpenXLSX/OpenXLSX/**/*.hpp",
-    "OpenXLSX/OpenXLSX/**/*.cpp",
-    "OpenXLSX/ThirdParty/pugixml/src/**/*.hpp",
-    "OpenXLSX/ThirdParty/pugixml/src/**/*.cpp",
-    "OpenXLSX/OpenXLSX/headers/detail/Zippy.hpp",
-    "OpenXLSX/ThirdParty/miniz/**/*.h",
-    "OpenXLSX/ThirdParty/miniz/**/*.c",
+    "ios/**/*.{h,hpp,mm}",
+    "thirdparty/OpenXLSX/OpenXLSX/**/*.hpp",
+    "thirdparty/OpenXLSX/OpenXLSX/**/*.cpp",
+    "thirdparty/pugixml/src/**/*.hpp",
+    "thirdparty/pugixml/src/**/*.cpp",
+    "thirdparty/OpenXLSX/OpenXLSX/headers/detail/Zippy.hpp",
+    "thirdparty/miniz/**/*.h",
+    "thirdparty/miniz/**/*.c",
   ]
 
   s.private_header_files = [
-    "OpenXLSX/**/*.hpp",
-    "OpenXLSX/**/*.h",
+    "thirdparty/OpenXLSX/**/*.hpp",
+    "thirdparty/OpenXLSX/**/*.h",
   ]
 
   s.dependency "React"
@@ -44,29 +51,22 @@ Pod::Spec.new do |s|
     "SWIFT_INSTALL_OBJC_HEADER" => "NO",
     "OTHER_CFLAGS" => "$(inherited) -fmodules",
     "OTHER_CPLUSPLUSFLAGS" => "$(inherited) -fmodules",
-    "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",
+    "HEADER_SEARCH_PATHS" => "$(inherited) ${PODS_TARGET_SRCROOT}/thirdparty/OpenXLSX ${PODS_TARGET_SRCROOT}/thirdparty/OpenXLSX/OpenXLSX ${PODS_TARGET_SRCROOT}/thirdparty/OpenXLSX/OpenXLSX/headers ${PODS_TARGET_SRCROOT}/thirdparty/pugixml/src ${PODS_TARGET_SRCROOT}/thirdparty/miniz",
   }
 
   s.user_target_xcconfig = {
     "OTHER_CFLAGS" => "$(inherited) -fmodules",
     "OTHER_CPLUSPLUSFLAGS" => "$(inherited) -fmodules",
-    "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",
+    "HEADER_SEARCH_PATHS" => "$(inherited) ${PODS_TARGET_SRCROOT}/thirdparty/OpenXLSX ${PODS_TARGET_SRCROOT}/thirdparty/OpenXLSX/OpenXLSX ${PODS_TARGET_SRCROOT}/thirdparty/OpenXLSX/OpenXLSX/headers ${PODS_TARGET_SRCROOT}/thirdparty/pugixml/src ${PODS_TARGET_SRCROOT}/thirdparty/miniz",
   }
 
-  # 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
+  # Swift Package Manager note: this podspec intentionally declares nothing for
+  # SPM. React Native 0.88+ drives SwiftPM from `package.json` (`swiftpmConfig`)
+  # and `npx react-native spm`, and the manifest lives in Package.swift. That
+  # manifest is still a placeholder (it only compiles ios/XlsxCacheDir.mm) and
+  # CocoaPods remains the build path for this library until the C++ targets,
+  # the vendored thirdparty/ tree and the NitroModules dependency are wired
+  # into it.
 
   load 'nitrogen/generated/ios/NitroXlsx+autolinking.rb'
   add_nitrogen_files(s)

package/Package.swift

@@ -1,19 +1,39 @@
 // 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.
+// NOTE: This manifest is a placeholder for the Swift Package Manager migration,
+// not the build path used today. CocoaPods (NitroXlsx.podspec) still compiles
+// the library, including the vendored OpenXLSX / pugixml / miniz tree under
+// thirdparty/.
 //
-// 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.
+// It is kept so that (a) the package is syntactically valid and `swift package
+// describe` / `swift build` work, and (b) the eventual migration has a starting
+// point. Today the target only compiles ios/XlsxCacheDir.mm — it exposes
+// getCacheDir / setCacheDir but not the Nitro module itself.
+//
+// Migration target (React Native 0.88+ / nitro-modules 1.x): the package becomes
+// one library product whose targets cover `cpp/`, `ios/XlsxCacheDir.mm` and the
+// thirdparty/ sources, depending on `.product(name: "NitroModules",
+// package: "NitroModules")`, with `swiftpmConfig` in package.json driving
+// autolinking via `npx react-native spm`. The unrelated NITRO_XLSX_USE_SPM env
+// switch that used to live in the podspec has been removed — it was never an
+// upstream concept.
+//
+// Target settings worth knowing:
+// - This is a C-family target, so SwiftPM insists on a public headers
+//   directory and defaults it to `include/`, which does not exist here.
+//   `publicHeadersPath: "."` points the generated umbrella header at the
+//   (header-less) source dir instead of failing to resolve the manifest.
+// - cxxLanguageStandard must match the podspec's CLANG_CXX_LANGUAGE_STANDARD
+//   (c++20); SwiftPM defaults to gnu++14 and warns on the nested namespace
+//   definitions used by the sources.
 
 let package = Package(
     name: "NitroXlsx",
     platforms: [
-        .iOS(.v15)
+        // Matches NitroXlsx.podspec (`:ios => "15.1"`). SwiftPM's .v15 only
+        // expresses 15.0, so the explicit version string is used instead.
+        .iOS("15.1")
     ],
     products: [
         .library(
@@ -25,7 +45,12 @@ let package = Package(
         .target(
             name: "NitroXlsx",
             path: "ios",
-            sources: ["dummy.swift"]
+            sources: ["XlsxCacheDir.mm"],
+            publicHeadersPath: ".",
+            cxxSettings: [
+                .headerSearchPath("../cpp")
+            ]
         )
-    ]
+    ],
+    cxxLanguageStandard: .cxx20
 )

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,7 +29,7 @@ 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.
+> **Note**: Native dependencies (OpenXLSX, pugixml and miniz) are vendored under `thirdparty/` and shipped with the package. The first build compiles them from source; no network access is required.
 
 ### iOS
 
@@ -126,41 +133,59 @@ const fontSize = format.getFontSize();
 
 ### Working with JSON
 
-#### Export to JSON (`toJSON`)
+Per-sheet conversion lives on `XlsxWorksheet`. Workbook-level conversion uses a
+`Record` keyed by worksheet name.
 
-Convert worksheet data to a JSON array. By default, the first row is used as object keys.
+#### Export a worksheet (`sheet.toJSON`)
 
-```typescript
-import { NitroXlsx, toJSON } from 'react-native-nitro-xlsx';
+Convert one worksheet's data to an array of records. By default, the first row is used as object keys.
 
-const workbook = NitroXlsx.openWorkbook('/path/to/data.xlsx');
+```typescript
+const sheet = workbook.getWorksheetByName('Data');
 
 // Use the first row as keys (default)
-const data = toJSON(workbook);
+const rows = sheet.toJSON();
 // Result: [{ "Name": "Alice", "Age": 30 }, { "Name": "Bob", "Age": 25 }]
 
 // Provide custom keys
-const data = toJSON(workbook, ['firstName', 'yearsOld']);
-// Result: [{ "firstName": "Alice", "yearsOld": 30 }, { "firstName": "Bob", "yearsOld": 25 }]
+const rows2 = sheet.toJSON(['firstName', 'yearsOld']);
+// Result: [{ "firstName": "Alice", "yearsOld": 30 }, ...]
 ```
 
-#### Import from JSON (`fromJSON`)
+#### Import into a worksheet (`sheet.fromJSON`)
 
-Create a workbook from a JSON array. The first object's keys become the header row.
+Write an array of records into an existing worksheet. The first record's keys become the header row.
 
 ```typescript
-import { NitroXlsx } from 'react-native-nitro-xlsx';
-
-const data = [
+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": [{ ... }] }
+```
 
-const workbook = NitroXlsx.fromJSON(data);
-// The workbook now has a worksheet with:
-// Row 1 (header): Name | Age | Active
-// Row 2:          Alice | 30 | true
-// Row 3:          Bob   | 25 | false
+#### 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();
 ```
@@ -169,10 +194,10 @@ const buffer = await workbook.getBuffer();
 
 ### 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: Array<Record<string, string | number>>): XlsxWorkbook` - Create a workbook from a JSON array (static method)
+- `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
 
@@ -181,9 +206,12 @@ const buffer = await workbook.getBuffer();
 - `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(keys?: string[]): Array<Record<string, string | number>>` - Convert worksheet data to a JSON array
+- `toJSON(): Record<string, Array<Record<string, string | number | boolean | null>>>` - Export every worksheet as a `Record` keyed by sheet name
 
 ### XlsxWorksheet
 
@@ -209,7 +237,7 @@ const buffer = await workbook.getBuffer();
 #### 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
@@ -217,6 +245,8 @@ const buffer = await workbook.getBuffer();
 |--------|-------------|
 | `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 |
 
@@ -225,38 +255,75 @@ const buffer = await workbook.getBuffer();
 |--------|-------------|
 | `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 |
@@ -266,11 +333,62 @@ const buffer = await workbook.getBuffer();
 | `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
 
@@ -320,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
@@ -341,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
 
@@ -373,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

@@ -4,33 +4,26 @@ project("NitroXlsx")
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
-set(OPENXLSX_DIR ${CMAKE_SOURCE_DIR}/../OpenXLSX)
-
-# 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"
-  )
-endif()
-
-# Verify OpenXLSX is available
-if(NOT EXISTS ${OPENXLSX_DIR}/CMakeLists.txt)
-  message(FATAL_ERROR
-    "OpenXLSX not found at ${OPENXLSX_DIR}.\n"
-    "Please manually clone OpenXLSX:\n"
-    "  cd ${CMAKE_SOURCE_DIR}/.. && git clone --depth 1 --branch v0.5.1 https://github.com/troldal/OpenXLSX.git OpenXLSX\n"
-    "Then clean CMake cache and rebuild."
-  )
-endif()
+set(THIRDPARTY_DIR ${CMAKE_SOURCE_DIR}/../thirdparty)
+set(OPENXLSX_DIR ${THIRDPARTY_DIR}/OpenXLSX)
+
+# OpenXLSX, pugixml and miniz are vendored under thirdparty/ so the build
+# never clones anything from GitHub.
+foreach(required_dir OpenXLSX pugixml miniz)
+  if(NOT EXISTS ${THIRDPARTY_DIR}/${required_dir})
+    message(FATAL_ERROR
+      "Vendored dependency '${required_dir}' is missing at ${THIRDPARTY_DIR}/${required_dir}.\n"
+      "The thirdparty/ tree is part of the package - reinstall react-native-nitro-xlsx."
+    )
+  endif()
+endforeach()
+
+# Point OpenXLSX's FetchContent lookups at the vendored copies, so
+# manage_dependency() populates them from disk instead of cloning GitHub.
+set(FORCE_FETCH_ALL ON CACHE BOOL "" FORCE)
+set(FETCHCONTENT_SOURCE_DIR_PUGIXML_FETCH ${THIRDPARTY_DIR}/pugixml CACHE PATH "" FORCE)
+set(FETCHCONTENT_SOURCE_DIR_MINIZ_FETCH ${THIRDPARTY_DIR}/miniz CACHE PATH "" FORCE)
+set(FETCHCONTENT_UPDATES_DISCONNECTED ON CACHE BOOL "" FORCE)
 
 set(OPENXLSX_BUILD_SAMPLES OFF CACHE BOOL "" FORCE)
 set(OPENXLSX_BUILD_TESTS OFF CACHE BOOL "" FORCE)
@@ -47,6 +40,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/cpp-adapter.cpp

@@ -1,9 +1,21 @@
 #include <jni.h>
 #include <fbjni/fbjni.h>
 #include "NitroXlsxOnLoad.hpp"
+#include "XlsxCacheDir.hpp"
 
 JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
   return facebook::jni::initialize(vm, []() {
     margelo::nitro::xlsx::registerAllNatives();
   });
 }
+
+// Called from NitroXlsxPackage with Context.getCacheDir().absolutePath
+extern "C" JNIEXPORT void JNICALL
+Java_com_margelo_nitro_xlsx_NitroXlsxPackage_nativeSetCacheDir(JNIEnv* env, jclass, jstring dir) {
+  if (dir == nullptr) return;
+  const char* chars = env->GetStringUTFChars(dir, nullptr);
+  if (chars != nullptr) {
+    margelo::nitro::xlsx::setCacheDir(std::string(chars));
+    env->ReleaseStringUTFChars(dir, chars);
+  }
+}