@simplysm/excel 13.0.76 → 13.0.78

package/README.md

@@ -21,12 +21,520 @@ const table = await ws.getDataTable(); // [{ Name: "Alice", Age: 30 }, ...]
 
 // Create a new file
 await using wb2 = new ExcelWorkbook();
-const ws2 = await wb2.createWorksheet("Sheet1");
+const ws2 = await wb2.addWorksheet("Sheet1");
 await ws2.setRecords([{ Name: "Alice", Age: 30 }]);
-const output = await wb2.getBytes();
+const output = await wb2.toBytes();
 ```
 
-### Type-safe read/write with Zod (ExcelWrapper)
+---
+
+## Types and Utilities
+
+### `ExcelValueType`
+
+Union of all supported cell value types.
+
+```typescript
+import { ExcelValueType } from "@simplysm/excel";
+
+type ExcelValueType = number | string | DateOnly | DateTime | Time | boolean | undefined;
+```
+
+### `ExcelNumberFormat`
+
+Named number format for a cell.
+
+```typescript
+import { ExcelNumberFormat } from "@simplysm/excel";
+
+type ExcelNumberFormat = "number" | "string" | "DateOnly" | "DateTime" | "Time";
+```
+
+### `ExcelCellType`
+
+Raw Excel cell type code stored in the XML.
+
+```typescript
+import { ExcelCellType } from "@simplysm/excel";
+
+// "s"         - shared string
+// "b"         - boolean
+// "str"       - formula result string
+// "n"         - number
+// "inlineStr" - inline string (rich text)
+// "e"         - error
+type ExcelCellType = "s" | "b" | "str" | "n" | "inlineStr" | "e";
+```
+
+### `ExcelAddressPoint`
+
+A 0-based row/column coordinate pair.
+
+```typescript
+import { ExcelAddressPoint } from "@simplysm/excel";
+
+interface ExcelAddressPoint {
+  r: number; // 0-based row index
+  c: number; // 0-based column index
+}
+```
+
+### `ExcelAddressRangePoint`
+
+A range defined by start and end `ExcelAddressPoint` values.
+
+```typescript
+import { ExcelAddressRangePoint } from "@simplysm/excel";
+
+interface ExcelAddressRangePoint {
+  s: ExcelAddressPoint; // start (top-left)
+  e: ExcelAddressPoint; // end (bottom-right)
+}
+```
+
+### `ExcelStyleOptions`
+
+Options for `ExcelCell.setStyle()`.
+
+```typescript
+import { ExcelStyleOptions } from "@simplysm/excel";
+
+interface ExcelStyleOptions {
+  background?: string;                   // ARGB 8-digit hex, e.g. "FFFF0000" (red)
+  border?: ExcelBorderPosition[];        // Border sides to draw
+  horizontalAlign?: ExcelHorizontalAlign;
+  verticalAlign?: ExcelVerticalAlign;
+  numberFormat?: ExcelNumberFormat;
+}
+```
+
+### `ExcelBorderPosition`
+
+```typescript
+import { ExcelBorderPosition } from "@simplysm/excel";
+
+type ExcelBorderPosition = "left" | "right" | "top" | "bottom";
+```
+
+### `ExcelHorizontalAlign`
+
+```typescript
+import { ExcelHorizontalAlign } from "@simplysm/excel";
+
+type ExcelHorizontalAlign = "center" | "left" | "right";
+```
+
+### `ExcelVerticalAlign`
+
+```typescript
+import { ExcelVerticalAlign } from "@simplysm/excel";
+
+type ExcelVerticalAlign = "center" | "top" | "bottom";
+```
+
+### XML Data Types
+
+These interfaces represent the raw XML structures parsed from the `.xlsx` ZIP package. Exported for advanced use cases (e.g., directly reading the parsed XML tree).
+
+```typescript
+import {
+  ExcelXmlContentTypeData,
+  ExcelXmlRelationshipData,
+  ExcelRelationshipData,
+  ExcelXmlWorkbookData,
+  ExcelXmlWorksheetData,
+  ExcelRowData,
+  ExcelCellData,
+  ExcelXmlDrawingData,
+  ExcelXmlSharedStringData,
+  ExcelXmlSharedStringDataSi,
+  ExcelXmlSharedStringDataText,
+  ExcelXmlStyleData,
+  ExcelXmlStyleDataXf,
+  ExcelXmlStyleDataFill,
+  ExcelXmlStyleDataBorder,
+  ExcelXml,
+} from "@simplysm/excel";
+```
+
+| Interface / Type | Description |
+|-----------------|-------------|
+| `ExcelXmlContentTypeData` | `[Content_Types].xml` document structure |
+| `ExcelXmlRelationshipData` | `.rels` relationship file structure |
+| `ExcelRelationshipData` | A single relationship entry |
+| `ExcelXmlWorkbookData` | `xl/workbook.xml` document structure |
+| `ExcelXmlWorksheetData` | `xl/worksheets/sheetN.xml` document structure |
+| `ExcelRowData` | A row element within worksheet XML |
+| `ExcelCellData` | A cell element within worksheet XML |
+| `ExcelXmlDrawingData` | Drawing XML structure (`xl/drawings/drawingN.xml`) |
+| `ExcelXmlSharedStringData` | Shared strings XML structure |
+| `ExcelXmlSharedStringDataSi` | A shared string entry (plain or rich text) |
+| `ExcelXmlSharedStringDataText` | Text content within a shared string entry |
+| `ExcelXmlStyleData` | Styles XML document structure |
+| `ExcelXmlStyleDataXf` | A cell format (`xf`) entry |
+| `ExcelXmlStyleDataFill` | A fill entry |
+| `ExcelXmlStyleDataBorder` | A border entry |
+| `ExcelXml` | Interface implemented by all XML handler classes |
+
+### `ExcelUtils`
+
+A static utility class providing cell address conversion, date/number conversion, and number format processing.
+
+```typescript
+import { ExcelUtils } from "@simplysm/excel";
+
+// Convert 0-based coordinates to "A1" notation
+ExcelUtils.stringifyAddr({ r: 0, c: 0 }); // "A1"
+
+// Convert column index to column letter(s)
+ExcelUtils.stringifyColAddr(0);  // "A"
+ExcelUtils.stringifyColAddr(26); // "AA"
+
+// Convert row index to row number string
+ExcelUtils.stringifyRowAddr(0); // "1"
+
+// Parse cell address
+ExcelUtils.parseCellAddr("B3"); // { r: 2, c: 1 }
+ExcelUtils.parseRowAddr("B3"); // 2
+ExcelUtils.parseColAddr("B3"); // 1
+
+// Parse range address
+ExcelUtils.parseRangeAddr("A1:C3"); // { s: { r: 0, c: 0 }, e: { r: 2, c: 2 } }
+
+// Convert range coordinates to address string
+ExcelUtils.stringifyRangeAddr({ s: { r: 0, c: 0 }, e: { r: 2, c: 2 } }); // "A1:C3"
+
+// Date/number conversion (Excel serial date <-> JS timestamp)
+const excelNum = ExcelUtils.convertTimeTickToNumber(Date.now());
+const tick = ExcelUtils.convertNumberToTimeTick(excelNum);
+
+// Number format conversions
+ExcelUtils.convertNumFmtCodeToName("General"); // "number"
+ExcelUtils.convertNumFmtIdToName(14);          // "DateOnly"
+ExcelUtils.convertNumFmtNameToId("DateTime");  // 22
+```
+
+**Static Methods**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `stringifyAddr` | `(point: ExcelAddressPoint) => string` | Convert coordinates to "A1" format |
+| `stringifyRowAddr` | `(r: number) => string` | Convert 0-based row index to row number string |
+| `stringifyColAddr` | `(c: number) => string` | Convert 0-based column index to column letter(s) |
+| `parseRowAddr` | `(addr: string) => number` | Extract 0-based row index from cell address |
+| `parseColAddr` | `(addr: string) => number` | Extract 0-based column index from cell address |
+| `parseCellAddr` | `(addr: string) => ExcelAddressPoint` | Convert cell address string to coordinates |
+| `parseRangeAddr` | `(rangeAddr: string) => ExcelAddressRangePoint` | Convert range address to coordinate pair |
+| `stringifyRangeAddr` | `(point: ExcelAddressRangePoint) => string` | Convert coordinate pair to range address string |
+| `convertTimeTickToNumber` | `(tick: number) => number` | Convert JS timestamp (ms) to Excel serial date number |
+| `convertNumberToTimeTick` | `(value: number) => number` | Convert Excel serial date number to JS timestamp (ms) |
+| `convertNumFmtCodeToName` | `(numFmtCode: string) => ExcelNumberFormat` | Convert format code string to format name |
+| `convertNumFmtIdToName` | `(numFmtId: number) => ExcelNumberFormat` | Convert built-in format ID to format name |
+| `convertNumFmtNameToId` | `(numFmtName: ExcelNumberFormat) => number` | Convert format name to built-in format ID |
+
+---
+
+## Core Classes
+
+### `ExcelWorkbook`
+
+The top-level class for reading and writing Excel workbooks. Internally manages ZIP resources; resources must be released after use.
+
+Supports `await using` (ES2022 `Symbol.asyncDispose`). Internally uses lazy-loading: XML inside the ZIP is parsed only at the point of access, keeping memory usage low even with large files.
+
+```typescript
+import { ExcelWorkbook } from "@simplysm/excel";
+
+// Open an existing workbook
+const bytes: Uint8Array = /* file bytes */;
+await using wb = new ExcelWorkbook(bytes);
+
+// Create a new workbook
+await using wb2 = new ExcelWorkbook();
+const ws = await wb2.addWorksheet("Sheet1");
+
+// Get all worksheet names
+const names = await wb.getWorksheetNames();
+
+// Access a worksheet by index or name
+const ws0 = await wb.getWorksheet(0);
+const ws1 = await wb.getWorksheet("Sheet1");
+
+// Export
+const exportedBytes = await wb.toBytes();
+const blob = await wb.toBlob();
+
+// Manual resource management
+const wb3 = new ExcelWorkbook(bytes);
+try {
+  const ws = await wb3.getWorksheet(0);
+  // ...
+} finally {
+  await wb3.close();
+}
+```
+
+**Constructor**
+
+```typescript
+constructor(arg?: Blob | Bytes)
+```
+
+- `arg` — Existing Excel file data (`Blob` or `Uint8Array`). Creates a new empty workbook if omitted.
+
+**Properties**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `zipCache` | `ZipCache` | Internal ZIP cache (advanced use) |
+
+**Methods**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getWorksheetNames` | `() => Promise<string[]>` | Return all worksheet names in the workbook |
+| `addWorksheet` | `(name: string) => Promise<ExcelWorksheet>` | Create and return a new worksheet |
+| `getWorksheet` | `(nameOrIndex: string \| number) => Promise<ExcelWorksheet>` | Look up a worksheet by name or 0-based index |
+| `toBytes` | `() => Promise<Bytes>` | Export workbook as a `Uint8Array` byte array |
+| `toBlob` | `() => Promise<Blob>` | Export workbook as a `Blob` |
+| `close` | `() => Promise<void>` | Release all resources (idempotent) |
+| `[Symbol.asyncDispose]` | `() => Promise<void>` | Called automatically by `await using` |
+
+---
+
+### `ExcelWorksheet`
+
+Represents a single worksheet. Provides cell access, row/column copy operations, data import/export, view settings, and image insertion.
+
+```typescript
+import { ExcelWorksheet } from "@simplysm/excel";
+
+// Obtained from ExcelWorkbook
+const ws = await wb.getWorksheet(0);
+
+// Name
+const name = await ws.getName();
+await ws.setName("NewName");
+
+// Cell access
+const cell = ws.cell(0, 0); // row 0, col 0 -> A1
+const row  = ws.row(1);     // row 1 (second row)
+const col  = ws.col(2);     // col 2 -> column C
+
+// Range and bulk cell access
+const range = await ws.getRange();
+const cells = await ws.getCells(); // ExcelCell[][]
+
+// Copy operations
+await ws.copyRow(0, 5);                              // copy row 0 to row 5
+await ws.copyRowStyle(0, 5);                         // copy style of row 0 to row 5
+await ws.copyCell({ r: 0, c: 0 }, { r: 5, c: 0 });  // copy single cell
+await ws.copyCellStyle({ r: 0, c: 0 }, { r: 5, c: 0 });
+await ws.insertCopyRow(0, 3); // insert-copy row 0 at position 3, shifting rows down
+
+// Read as table (first row = headers)
+const table = await ws.getDataTable();
+const table2 = await ws.getDataTable({
+  headerRowIndex: 0,
+  checkEndColIndex: 0,
+  usableHeaderNameFn: (name) => name !== "ignore",
+});
+
+// Write data
+await ws.setDataMatrix([[1, "hello"], [2, "world"]]);
+await ws.setRecords([{ Name: "Alice", Age: 30 }]);
+
+// View settings
+await ws.setZoom(85);              // 85%
+await ws.freezeAt({ r: 1 });      // freeze first row
+await ws.freezeAt({ c: 1 });      // freeze first column
+await ws.freezeAt({ r: 1, c: 1 }); // freeze both
+
+// Insert image
+await ws.addImage({
+  bytes: imageBytes,
+  ext: "png",
+  from: { r: 0, c: 0 },
+  to: { r: 5, c: 3 },
+});
+```
+
+**Methods**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getName` | `() => Promise<string>` | Return the worksheet name |
+| `setName` | `(newName: string) => Promise<void>` | Rename the worksheet |
+| `row` | `(r: number) => ExcelRow` | Return the `ExcelRow` at 0-based row index |
+| `cell` | `(r: number, c: number) => ExcelCell` | Return the `ExcelCell` at 0-based row/column |
+| `col` | `(c: number) => ExcelCol` | Return the `ExcelCol` at 0-based column index |
+| `getRange` | `() => Promise<ExcelAddressRangePoint>` | Return the used data range |
+| `getCells` | `() => Promise<ExcelCell[][]>` | Return all cells as a 2D array (row-major) |
+| `copyRow` | `(srcR: number, targetR: number) => Promise<void>` | Copy source row to target row (overwrite) |
+| `copyRowStyle` | `(srcR: number, targetR: number) => Promise<void>` | Copy style from source row to target row |
+| `copyCell` | `(srcAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint) => Promise<void>` | Copy a single cell |
+| `copyCellStyle` | `(srcAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint) => Promise<void>` | Copy style from source cell to target cell |
+| `insertCopyRow` | `(srcR: number, targetR: number) => Promise<void>` | Insert-copy source row at target position (shifts rows down) |
+| `getDataTable` | `(opt?) => Promise<Record<string, ExcelValueType>[]>` | Read worksheet as a header-keyed record array |
+| `setDataMatrix` | `(matrix: ExcelValueType[][]) => Promise<void>` | Write a 2D array to the worksheet |
+| `setRecords` | `(records: Record<string, ExcelValueType>[]) => Promise<void>` | Write records with auto-generated header row |
+| `setZoom` | `(percent: number) => Promise<void>` | Set the worksheet zoom level |
+| `freezeAt` | `(point: { r?: number; c?: number }) => Promise<void>` | Set freeze panes |
+| `addImage` | `(opts) => Promise<void>` | Insert an image into the worksheet |
+
+**`getDataTable` options**
+
+```typescript
+{
+  headerRowIndex?: number;                              // Row index of the header row (default: first row in range)
+  checkEndColIndex?: number;                            // Column whose empty value signals end of data
+  usableHeaderNameFn?: (headerName: string) => boolean; // Filter which headers to include
+}
+```
+
+**`addImage` options**
+
+```typescript
+{
+  bytes: Bytes;  // Image binary data (Uint8Array)
+  ext: string;   // File extension, e.g. "png", "jpg"
+  from: { r: number; c: number; rOff?: number | string; cOff?: number | string }; // Start cell (0-based), optional EMU offset
+  to?: { r: number; c: number; rOff?: number | string; cOff?: number | string };  // End cell (optional; defaults to from.r+1, from.c+1)
+}
+```
+
+---
+
+### `ExcelRow`
+
+Represents a row in a worksheet. Provides access to individual cells and all cells in the row.
+
+```typescript
+import { ExcelRow } from "@simplysm/excel";
+
+// Obtained from ExcelWorksheet
+const row = ws.row(0);
+
+// Access a cell by column index (0-based)
+const cell = row.cell(2); // column C
+
+// Get all cells in the row (within used range)
+const cells = await row.getCells();
+```
+
+**Methods**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `cell` | `(c: number) => ExcelCell` | Return the `ExcelCell` at the given 0-based column index |
+| `getCells` | `() => Promise<ExcelCell[]>` | Return all cells in the row within the worksheet's used range |
+
+---
+
+### `ExcelCol`
+
+Represents a column in a worksheet. Provides access to individual cells, all cells in the column, and column width configuration.
+
+```typescript
+import { ExcelCol } from "@simplysm/excel";
+
+// Obtained from ExcelWorksheet
+const col = ws.col(0); // column A
+
+// Access a cell by row index (0-based)
+const cell = col.cell(3); // row 3
+
+// Get all cells in the column (within used range)
+const cells = await col.getCells();
+
+// Set column width
+await col.setWidth(20);
+```
+
+**Methods**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `cell` | `(r: number) => ExcelCell` | Return the `ExcelCell` at the given 0-based row index |
+| `getCells` | `() => Promise<ExcelCell[]>` | Return all cells in the column within the worksheet's used range |
+| `setWidth` | `(size: number) => Promise<void>` | Set the column width |
+
+---
+
+### `ExcelCell`
+
+Represents a single cell. Provides value read/write, formula access, style configuration, and cell merge.
+
+All methods are `async` because XML sub-files (SharedStrings, Styles) are loaded lazily on demand.
+
+```typescript
+import { ExcelCell } from "@simplysm/excel";
+
+// Obtained from ExcelWorksheet, ExcelRow, or ExcelCol
+const cell = ws.cell(0, 0); // A1
+
+// Cell address (0-based)
+console.log(cell.addr); // { r: 0, c: 0 }
+
+// Read/write values
+await cell.setValue("Hello");
+await cell.setValue(42);
+await cell.setValue(true);
+await cell.setValue(new DateOnly(Date.now()));
+await cell.setValue(new DateTime(Date.now()));
+await cell.setValue(new Time(Date.now()));
+await cell.setValue(undefined); // deletes the cell
+
+const value = await cell.getValue(); // ExcelValueType
+
+// Formulas
+await cell.setFormula("=SUM(A1:A10)");
+await cell.setFormula(undefined); // removes formula
+const formula = await cell.getFormula();
+
+// Style
+await cell.setStyle({
+  background: "00FFFF00",                         // ARGB 8-digit hex (yellow)
+  border: ["left", "right", "top", "bottom"],
+  horizontalAlign: "center",
+  verticalAlign: "center",
+  numberFormat: "number",
+});
+
+// Raw style ID (advanced use)
+const styleId = await cell.getStyleId();
+await cell.setStyleId("3");
+
+// Merge cells: merge from this cell (A1) to C3
+await cell.merge(2, 2); // end row=2, end col=2
+```
+
+**Properties**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `addr` | `ExcelAddressPoint` | Cell address (0-based `{ r, c }`) |
+
+**Methods**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getValue` | `() => Promise<ExcelValueType>` | Read the cell value |
+| `setValue` | `(val: ExcelValueType) => Promise<void>` | Write the cell value (`undefined` deletes the cell) |
+| `getFormula` | `() => Promise<string \| undefined>` | Read the cell formula |
+| `setFormula` | `(val: string \| undefined) => Promise<void>` | Write the cell formula (`undefined` removes it) |
+| `getStyleId` | `() => Promise<string \| undefined>` | Read the raw style ID |
+| `setStyleId` | `(styleId: string \| undefined) => Promise<void>` | Set the raw style ID |
+| `setStyle` | `(opts: ExcelStyleOptions) => Promise<void>` | Apply style options to the cell |
+| `merge` | `(r: number, c: number) => Promise<void>` | Merge from this cell to the given end coordinates (0-based) |
+
+---
+
+## Wrapper Classes
+
+### `ExcelWrapper`
+
+A Zod schema-based high-level wrapper that provides type-safe reading and writing of Excel files. Use `.describe()` on schema fields to specify the Excel column header name.
 
 ```typescript
 import { ExcelWrapper } from "@simplysm/excel";
@@ -35,27 +543,41 @@ import { z } from "zod";
 const schema = z.object({
   name: z.string().describe("Name"),
   age: z.number().describe("Age"),
+  joinDate: z.instanceof(DateOnly).optional().describe("Join Date"),
 });
 
 const wrapper = new ExcelWrapper(schema);
 
-// Read
+// Read Excel file into typed records
 const records = await wrapper.read(fileBytes);
+const records2 = await wrapper.read(fileBytes, "Sheet1");
+const records3 = await wrapper.read(fileBytes, 0, { excludes: ["age"] });
 
-// Write
+// Write records to Excel workbook
 await using wb = await wrapper.write("Members", records);
-const output = await wb.getBytes();
+const bytes = await wb.toBytes();
+
+// Write with excludes
+await using wb2 = await wrapper.write("Members", records, { excludes: ["joinDate"] });
 ```
 
-## Modules
+**Constructor**
+
+```typescript
+constructor(schema: TSchema extends z.ZodObject<z.ZodRawShape>)
+```
+
+**Methods**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `read` | `(file: Bytes \| Blob, wsNameOrIndex?: string \| number, options?: { excludes?: (keyof TSchema)[] }) => Promise<z.infer<TSchema>[]>` | Read an Excel file into a typed record array |
+| `write` | `(wsName: string, records: Partial<z.infer<TSchema>>[], options?: { excludes?: (keyof TSchema)[] }) => Promise<ExcelWorkbook>` | Write records to a new `ExcelWorkbook` (caller manages lifecycle) |
+
+**Behavior Notes**
 
-| Module | Description | Details |
-|--------|-------------|---------|
-| `ExcelWorkbook` | Top-level workbook handle; open/create/export `.xlsx` files | [docs/workbook.md](docs/workbook.md) |
-| `ExcelWorksheet` | Single worksheet; cell access, copy, data import/export, images | [docs/workbook.md](docs/workbook.md) |
-| `ExcelRow` | Row handle; access cells in a row | [docs/workbook.md](docs/workbook.md) |
-| `ExcelCol` | Column handle; access cells, set width | [docs/workbook.md](docs/workbook.md) |
-| `ExcelCell` | Single cell; read/write values, formulas, styles, merge | [docs/workbook.md](docs/workbook.md) |
-| `ExcelUtils` | Static helpers for address conversion and date/format conversion | [docs/utils.md](docs/utils.md) |
-| `ExcelWrapper` | Zod schema-based type-safe read/write | [docs/wrapper.md](docs/wrapper.md) |
-| Types | Value, address, style, and XML data type definitions | [docs/types.md](docs/types.md) |
+- Header names are taken from Zod field `.describe()` values; if not set, the field key is used.
+- `read` throws if no data rows are found after the header row.
+- `read` validates each row with the Zod schema and throws on validation failure.
+- `write` automatically applies borders to all data cells, highlights required (non-optional, non-boolean) header cells with a yellow background (`"00FFFF00"`), sets zoom to 85%, and freezes the first row.
+- The `ExcelWorkbook` returned by `write` must be closed by the caller (`await using` or `.close()`).

package/dist/excel-cell.d.ts

@@ -7,7 +7,7 @@ import type { ExcelAddressPoint, ExcelStyleOptions, ExcelValueType } from "./typ
  * @remarks
  * ## Async Method Design
  *
- * Why all cell methods like `getVal()`, `setVal()` are `async`:
+ * Why all cell methods like `getValue()`, `setValue()` are `async`:
  * - Only the XML needed for the cell type is selectively loaded
  * - String cell: loads SharedStrings.xml
  * - Number cell: does not load SharedStrings
@@ -29,9 +29,9 @@ export declare class ExcelCell {
     /** Return cell formula */
     getFormula(): Promise<string | undefined>;
     /** Set cell value (undefined: delete cell) */
-    setVal(val: ExcelValueType): Promise<void>;
+    setValue(val: ExcelValueType): Promise<void>;
     /** Return cell value */
-    getVal(): Promise<ExcelValueType>;
+    getValue(): Promise<ExcelValueType>;
     /**
      * Merge cells from current cell to the specified end coordinates
      * @param r End row index of merge (0-based)
@@ -48,7 +48,7 @@ export declare class ExcelCell {
     /**
      * Set cell style
      * @param opts Style options
-     * @param opts.background Background color (ARGB format, 8-digit hex. e.g. "FFFF0000")
+     * @param opts.background Background color (ARGB format, 8-digit hex. e.g. "00FF0000")
      * @param opts.border Border position array (e.g. ["left", "right", "top", "bottom"])
      * @param opts.horizontalAlign Horizontal alignment ("left", "center", "right")
      * @param opts.verticalAlign Vertical alignment ("top", "center", "bottom")

package/dist/excel-cell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"excel-cell.d.ts","sourceRoot":"","sources":["..\\src\\excel-cell.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAapF;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS;IAKlB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPrB,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;gBAGd,SAAS,EAAE,QAAQ,EACnB,eAAe,EAAE,MAAM,EACvB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM;IAO7B,sDAAsD;IAChD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxD,0BAA0B;IACpB,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK/C,8CAA8C;IACxC,MAAM,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAwChD,wBAAwB;IAClB,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAwFvC;;;;;;;OAOG;IACG,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD,2BAA2B;IACrB,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK/C,wBAAwB;IAClB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5D;;;;;;;;OAQG;IACG,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;YAiCxC,WAAW;YAKX,UAAU;YAIV,iBAAiB;YAYjB,YAAY;YAIZ,UAAU;YAIV,aAAa;YAIb,aAAa;YAIb,kBAAkB;YAqBlB,qBAAqB;CAsBpC"}
+{"version":3,"file":"excel-cell.d.ts","sourceRoot":"","sources":["..\\src\\excel-cell.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAYpF;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS;IAKlB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPrB,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;gBAGd,SAAS,EAAE,QAAQ,EACnB,eAAe,EAAE,MAAM,EACvB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM;IAO7B,sDAAsD;IAChD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxD,0BAA0B;IACpB,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK/C,8CAA8C;IACxC,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAwClD,wBAAwB;IAClB,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC;IAwFzC;;;;;;;OAOG;IACG,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD,2BAA2B;IACrB,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK/C,wBAAwB;IAClB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5D;;;;;;;;OAQG;IACG,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;YAiCxC,WAAW;YAKX,UAAU;YAIV,iBAAiB;YAYjB,YAAY;YAIZ,UAAU;YAIV,aAAa;YAIb,aAAa;YAIb,kBAAkB;YAqBlB,qBAAqB;CAsBpC"}

package/dist/excel-cell.js

@@ -1,9 +1,8 @@
 import {
   DateOnly,
   DateTime,
-  numParseFloat,
-  numParseInt,
-  strIsNullOrEmpty,
+  num,
+  str,
   Time
 } from "@simplysm/core-common";
 import { ExcelXmlSharedString as ExcelXmlSharedStringClass } from "./xml/excel-xml-shared-string.js";
@@ -37,7 +36,7 @@ class ExcelCell {
     return wsData.getCellFormula(this.addr);
   }
   /** Set cell value (undefined: delete cell) */
-  async setVal(val) {
+  async setValue(val) {
     if (val === void 0) {
       await this._deleteCell(this.addr);
     } else if (typeof val === "string") {
@@ -75,16 +74,16 @@ class ExcelCell {
     }
   }
   /** Return cell value */
-  async getVal() {
+  async getValue() {
     const wsData = await this._getWsData();
     const cellVal = wsData.getCellVal(this.addr);
-    if (cellVal === void 0 || strIsNullOrEmpty(cellVal)) {
+    if (cellVal === void 0 || str.isNullOrEmpty(cellVal)) {
       return void 0;
     }
     const cellType = wsData.getCellType(this.addr);
     if (cellType === "s") {
       const ssData = await this._getOrCreateSsData();
-      const ssId = numParseInt(cellVal);
+      const ssId = num.parseInt(cellVal);
       if (ssId == null) {
         throw new Error(
           `[${ExcelUtils.stringifyAddr(this.addr)}] Failed to parse SharedString ID: ${cellVal}`
@@ -121,7 +120,7 @@ class ExcelCell {
       if (numFmtCode !== void 0) {
         numFmt = ExcelUtils.convertNumFmtCodeToName(numFmtCode);
       } else {
-        const numFmtIdNum = numParseInt(numFmtId);
+        const numFmtIdNum = num.parseInt(numFmtId);
         if (numFmtIdNum == null) {
           throw new Error(
             `[${ExcelUtils.stringifyAddr(this.addr)}] Failed to parse numFmtId: ${numFmtId}`
@@ -134,7 +133,7 @@ class ExcelCell {
       } else if (numFmt === "string") {
         return cellVal;
       } else {
-        const dateNum = numParseFloat(cellVal);
+        const dateNum = num.parseFloat(cellVal);
         if (dateNum == null) {
           throw new Error(
             `[${ExcelUtils.stringifyAddr(this.addr)}] Failed to parse date number: ${cellVal}`
@@ -180,7 +179,7 @@ class ExcelCell {
   /**
    * Set cell style
    * @param opts Style options
-   * @param opts.background Background color (ARGB format, 8-digit hex. e.g. "FFFF0000")
+   * @param opts.background Background color (ARGB format, 8-digit hex. e.g. "00FF0000")
    * @param opts.border Border position array (e.g. ["left", "right", "top", "bottom"])
    * @param opts.horizontalAlign Horizontal alignment ("left", "center", "right")
    * @param opts.verticalAlign Vertical alignment ("top", "center", "bottom")