@simplysm/excel 13.0.98 → 13.0.99

package/README.md

@@ -8,25 +8,75 @@ Excel file processing library. Platform-neutral (works in both browser and Node.
 npm install @simplysm/excel
 ```
 
-## Exports
-
-```typescript
-import {
-  ExcelWorkbook,
-  ExcelWorksheet,
-  ExcelRow,
-  ExcelCol,
-  ExcelCell,
-  ExcelUtils,
-  ExcelWrapper,
-} from "@simplysm/excel";
-```
-
-## Quick Start
+## API Overview
+
+### Types
+
+| API | Type | Description |
+|-----|------|-------------|
+| `ExcelValueType` | type | Union of supported cell value types (`number`, `string`, `DateOnly`, `DateTime`, `Time`, `boolean`, `undefined`) |
+| `ExcelNumberFormat` | type | Number format name (`"number"`, `"string"`, `"DateOnly"`, `"DateTime"`, `"Time"`) |
+| `ExcelCellType` | type | Cell type identifier (`"s"`, `"b"`, `"str"`, `"n"`, `"inlineStr"`, `"e"`) |
+| `ExcelAddressPoint` | interface | Cell coordinate (`r`, `c`, 0-based) |
+| `ExcelAddressRangePoint` | interface | Range of cell coordinates (`s`, `e`) |
+| `ExcelBorderPosition` | type | Border position (`"left"`, `"right"`, `"top"`, `"bottom"`) |
+| `ExcelHorizontalAlign` | type | Horizontal alignment (`"center"`, `"left"`, `"right"`) |
+| `ExcelVerticalAlign` | type | Vertical alignment (`"center"`, `"top"`, `"bottom"`) |
+| `ExcelStyleOptions` | interface | Cell style options (`background`, `border`, `horizontalAlign`, `verticalAlign`, `numberFormat`) |
+| `ExcelXml` | interface | Excel XML interface (`data`, `cleanup()`) |
+| `ExcelXmlContentTypeData` | interface | Content type XML data |
+| `ExcelXmlRelationshipData` | interface | Relationship XML data |
+| `ExcelRelationshipData` | interface | Single relationship data |
+| `ExcelXmlWorkbookData` | interface | Workbook XML data |
+| `ExcelXmlWorksheetData` | interface | Worksheet XML data |
+| `ExcelRowData` | interface | Row XML data |
+| `ExcelCellData` | interface | Cell XML data |
+| `ExcelXmlDrawingData` | interface | Drawing XML data |
+| `ExcelXmlSharedStringData` | interface | Shared strings XML data |
+| `ExcelXmlSharedStringDataSi` | type | Shared string item |
+| `ExcelXmlSharedStringDataText` | type | Shared string text |
+| `ExcelXmlStyleData` | interface | Style XML data |
+| `ExcelXmlStyleDataXf` | interface | Cell format definition |
+| `ExcelXmlStyleDataFill` | interface | Fill style definition |
+| `ExcelXmlStyleDataBorder` | interface | Border style definition |
+
+-> See [docs/types.md](./docs/types.md) for details.
+
+### Utilities
+
+| API | Type | Description |
+|-----|------|-------------|
+| `ExcelUtils` | class | Cell address conversion, date/number conversion, number format processing |
+
+-> See [docs/utilities.md](./docs/utilities.md) for details.
+
+### Core Classes
+
+| API | Type | Description |
+|-----|------|-------------|
+| `ExcelWorkbook` | class | Workbook processing with lazy-loading ZIP architecture |
+| `ExcelWorksheet` | class | Worksheet with cell access, copying, data tables, images |
+| `ExcelRow` | class | Row with cell access |
+| `ExcelCol` | class | Column with cell access and width configuration |
+| `ExcelCell` | class | Cell with value, formula, style, and merge operations |
+
+-> See [docs/core-classes.md](./docs/core-classes.md) for details.
+
+### Wrapper
+
+| API | Type | Description |
+|-----|------|-------------|
+| `ExcelWrapper` | class | Zod schema-based type-safe Excel read/write |
+
+-> See [docs/wrapper.md](./docs/wrapper.md) for details.
+
+## Usage Examples
 
 ### Create a new workbook
 
 ```typescript
+import { ExcelWorkbook } from "@simplysm/excel";
+
 await using wb = new ExcelWorkbook();
 const ws = await wb.addWorksheet("Sheet1");
 await ws.cell(0, 0).setValue("Name");
@@ -49,6 +99,7 @@ const dataTable = await ws.getDataTable();
 
 ```typescript
 import { z } from "zod";
+import { ExcelWrapper } from "@simplysm/excel";
 
 const schema = z.object({
   name: z.string().describe("Name"),
@@ -66,9 +117,3 @@ await using wb = await wrapper.write("Sheet1", [
 ]);
 const bytes = await wb.toBytes();
 ```
-
-## Documentation
-
-- [Types](docs/types.md)
-- [Core Classes](docs/core-classes.md)
-- [Wrapper](docs/wrapper.md)

package/docs/core-classes.md

@@ -0,0 +1,541 @@
+# Core Classes
+
+## ExcelWorkbook
+
+Excel workbook processing class. Internally manages ZIP resources.
+
+Adopts a Lazy Loading architecture for memory efficiency with large Excel files: XML inside the ZIP is read and parsed only at the point of access.
+
+```typescript
+import { ExcelWorkbook } from "@simplysm/excel";
+```
+
+### Constructor
+
+```typescript
+constructor(arg?: Blob | Bytes)
+```
+
+- `arg` -- Existing Excel file data (Blob or Uint8Array). Creates a new workbook if omitted.
+
+### Methods
+
+#### `getWorksheetNames`
+
+Return all worksheet names in the workbook.
+
+```typescript
+async getWorksheetNames(): Promise<string[]>;
+```
+
+#### `addWorksheet`
+
+Create and return a new worksheet.
+
+```typescript
+async addWorksheet(name: string): Promise<ExcelWorksheet>;
+```
+
+#### `getWorksheet`
+
+Look up a worksheet by name or index (0-based).
+
+```typescript
+async getWorksheet(nameOrIndex: string | number): Promise<ExcelWorksheet>;
+```
+
+#### `toBytes`
+
+Export workbook as byte array.
+
+```typescript
+async toBytes(): Promise<Bytes>;
+```
+
+#### `toBlob`
+
+Export workbook as Blob.
+
+```typescript
+async toBlob(): Promise<Blob>;
+```
+
+#### `close`
+
+Release workbook resources. Safe to call on an already closed workbook (no-op). The workbook instance cannot be used after this call.
+
+```typescript
+async close(): Promise<void>;
+```
+
+Implements `Symbol.asyncDispose` for use with `await using`.
+
+### Example
+
+```typescript
+// Using await using (recommended)
+await using wb = new ExcelWorkbook(bytes);
+const ws = await wb.getWorksheet(0);
+// Resources automatically released at scope exit
+
+// Or using try-finally
+const wb = new ExcelWorkbook(bytes);
+try {
+  const ws = await wb.getWorksheet(0);
+} finally {
+  await wb.close();
+}
+```
+
+---
+
+## ExcelWorksheet
+
+Class representing an Excel worksheet. Provides cell access, row/column copying, data table processing, and image insertion.
+
+### Cell Access
+
+#### `row`
+
+Return row object (0-based).
+
+```typescript
+row(r: number): ExcelRow;
+```
+
+#### `cell`
+
+Return cell object (0-based row/column).
+
+```typescript
+cell(r: number, c: number): ExcelCell;
+```
+
+#### `col`
+
+Return column object (0-based).
+
+```typescript
+col(c: number): ExcelCol;
+```
+
+### Name Methods
+
+#### `getName`
+
+```typescript
+async getName(): Promise<string>;
+```
+
+#### `setName`
+
+```typescript
+async setName(newName: string): Promise<void>;
+```
+
+### Copy Methods
+
+#### `copyRowStyle`
+
+Copy style from source row to target row.
+
+```typescript
+async copyRowStyle(srcR: number, targetR: number): Promise<void>;
+```
+
+#### `copyCellStyle`
+
+Copy style from source cell to target cell.
+
+```typescript
+async copyCellStyle(srcAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint): Promise<void>;
+```
+
+#### `copyRow`
+
+Copy source row to target row (overwrite).
+
+```typescript
+async copyRow(srcR: number, targetR: number): Promise<void>;
+```
+
+#### `copyCell`
+
+Copy source cell to target cell.
+
+```typescript
+async copyCell(srcAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint): Promise<void>;
+```
+
+#### `insertCopyRow`
+
+Insert-copy the source row at the target position. Existing rows at and below the target are shifted down by one.
+
+```typescript
+async insertCopyRow(srcR: number, targetR: number): Promise<void>;
+```
+
+### Range Methods
+
+#### `getRange`
+
+Return data range of the worksheet.
+
+```typescript
+async getRange(): Promise<ExcelAddressRangePoint>;
+```
+
+#### `getCells`
+
+Return all cells as a 2D array.
+
+```typescript
+async getCells(): Promise<ExcelCell[][]>;
+```
+
+### Data Methods
+
+#### `getDataTable`
+
+Return worksheet data as a table (record array).
+
+```typescript
+async getDataTable(opt?: {
+  headerRowIndex?: number;
+  checkEndColIndex?: number;
+  usableHeaderNameFn?: (headerName: string) => boolean;
+}): Promise<Record<string, ExcelValueType>[]>;
+```
+
+**Parameters:**
+- `opt.headerRowIndex` -- Header row index (default: first row)
+- `opt.checkEndColIndex` -- Column index to determine data end. Data ends when this column is empty.
+- `opt.usableHeaderNameFn` -- Function to filter usable headers
+
+#### `setDataMatrix`
+
+Write 2D array data to the worksheet.
+
+```typescript
+async setDataMatrix(matrix: ExcelValueType[][]): Promise<void>;
+```
+
+#### `setRecords`
+
+Write record array to the worksheet. Headers are auto-generated in the first row, data follows in subsequent rows.
+
+```typescript
+async setRecords(records: Record<string, ExcelValueType>[]): Promise<void>;
+```
+
+### View Methods
+
+#### `setZoom`
+
+Set worksheet zoom scale (percent).
+
+```typescript
+async setZoom(percent: number): Promise<void>;
+```
+
+#### `freezeAt`
+
+Set freeze panes for rows/columns.
+
+```typescript
+async freezeAt(point: { r?: number; c?: number }): Promise<void>;
+```
+
+### Image Methods
+
+#### `addImage`
+
+Insert an image into the worksheet.
+
+```typescript
+async addImage(opts: {
+  bytes: Bytes;
+  ext: string;
+  from: { r: number; c: number; rOff?: number | string; cOff?: number | string };
+  to?: { r: number; c: number; rOff?: number | string; cOff?: number | string };
+}): Promise<void>;
+```
+
+**Parameters:**
+- `opts.bytes` -- Image binary data
+- `opts.ext` -- Image extension (png, jpg, etc.)
+- `opts.from` -- Image start position (0-based row/column index, rOff/cOff in EMU offset)
+- `opts.to` -- Image end position (if omitted, inserted at from position with original size)
+
+---
+
+## ExcelRow
+
+Class representing a row in an Excel worksheet. Provides cell access functionality.
+
+#### `cell`
+
+Return cell at the given column index (0-based).
+
+```typescript
+cell(c: number): ExcelCell;
+```
+
+#### `getCells`
+
+Return all cells in the row.
+
+```typescript
+async getCells(): Promise<ExcelCell[]>;
+```
+
+---
+
+## ExcelCol
+
+Class representing a column in an Excel worksheet. Provides cell access and column width configuration.
+
+#### `cell`
+
+Return cell at the given row index (0-based).
+
+```typescript
+cell(r: number): ExcelCell;
+```
+
+#### `getCells`
+
+Return all cells in the column.
+
+```typescript
+async getCells(): Promise<ExcelCell[]>;
+```
+
+#### `setWidth`
+
+Set column width.
+
+```typescript
+async setWidth(size: number): Promise<void>;
+```
+
+---
+
+## ExcelCell
+
+Class representing an Excel cell. Provides value read/write, formula, style, and cell merge functionality.
+
+All cell methods are `async` because the required XML (SharedStrings, Styles, etc.) is loaded on-demand for memory efficiency.
+
+### Properties
+
+#### `addr`
+
+Cell address (0-based row/column index).
+
+```typescript
+readonly addr: ExcelAddressPoint;
+```
+
+### Value Methods
+
+#### `getValue`
+
+Return cell value.
+
+```typescript
+async getValue(): Promise<ExcelValueType>;
+```
+
+#### `setValue`
+
+Set cell value (`undefined` deletes the cell).
+
+```typescript
+async setValue(val: ExcelValueType): Promise<void>;
+```
+
+#### `getFormula`
+
+Return cell formula.
+
+```typescript
+async getFormula(): Promise<string | undefined>;
+```
+
+#### `setFormula`
+
+Set formula on cell (`undefined` removes the formula).
+
+```typescript
+async setFormula(val: string | undefined): Promise<void>;
+```
+
+### Merge Methods
+
+#### `merge`
+
+Merge cells from current cell to the specified end coordinates.
+
+```typescript
+async merge(r: number, c: number): Promise<void>;
+```
+
+**Example:**
+```typescript
+// Merges range A1:C3 (3 rows x 3 columns)
+await ws.cell(0, 0).merge(2, 2);
+```
+
+### Style Methods
+
+#### `getStyleId`
+
+Return cell style ID.
+
+```typescript
+async getStyleId(): Promise<string | undefined>;
+```
+
+#### `setStyleId`
+
+Set cell style ID.
+
+```typescript
+async setStyleId(styleId: string | undefined): Promise<void>;
+```
+
+#### `setStyle`
+
+Set cell style.
+
+```typescript
+async setStyle(opts: ExcelStyleOptions): Promise<void>;
+```
+
+---
+
+## ExcelUtils
+
+Collection of Excel utility functions. Provides cell address conversion, date/number conversion, and number format processing.
+
+```typescript
+import { ExcelUtils } from "@simplysm/excel";
+```
+
+### Address Conversion
+
+#### `stringifyAddr`
+
+Convert cell coordinates to "A1" format string.
+
+```typescript
+static stringifyAddr(point: ExcelAddressPoint): string;
+```
+
+#### `stringifyRowAddr`
+
+Convert row index (0-based) to row address string (e.g. `0` -> `"1"`).
+
+```typescript
+static stringifyRowAddr(r: number): string;
+```
+
+#### `stringifyColAddr`
+
+Convert column index (0-based) to column address string (e.g. `0` -> `"A"`, `26` -> `"AA"`).
+
+```typescript
+static stringifyColAddr(c: number): string;
+```
+
+#### `parseRowAddr`
+
+Extract row index from cell address (e.g. `"A3"` -> `2`).
+
+```typescript
+static parseRowAddr(addr: string): number;
+```
+
+#### `parseColAddr`
+
+Extract column index from cell address (e.g. `"B3"` -> `1`).
+
+```typescript
+static parseColAddr(addr: string): number;
+```
+
+#### `parseCellAddr`
+
+Convert cell address to coordinates (e.g. `"B3"` -> `{r: 2, c: 1}`).
+
+```typescript
+static parseCellAddr(addr: string): ExcelAddressPoint;
+```
+
+#### `parseRangeAddr`
+
+Convert range address to coordinates (e.g. `"A1:C3"` -> `{s: {r:0,c:0}, e: {r:2,c:2}}`).
+
+```typescript
+static parseRangeAddr(rangeAddr: string): ExcelAddressRangePoint;
+```
+
+#### `stringifyRangeAddr`
+
+Convert range coordinates to address string.
+
+```typescript
+static stringifyRangeAddr(point: ExcelAddressRangePoint): string;
+```
+
+### Date/Number Conversion
+
+#### `convertTimeTickToNumber`
+
+Convert JavaScript timestamp (ms) to Excel date number. Excel counts 1900-01-01 as 1 (1899-12-30 is date 0).
+
+```typescript
+static convertTimeTickToNumber(tick: number): number;
+```
+
+#### `convertNumberToTimeTick`
+
+Convert Excel date number to JavaScript timestamp (ms).
+
+```typescript
+static convertNumberToTimeTick(value: number): number;
+```
+
+### Number Format
+
+#### `convertNumFmtCodeToName`
+
+Convert number format code to format name.
+
+```typescript
+static convertNumFmtCodeToName(numFmtCode: string): ExcelNumberFormat;
+```
+
+#### `convertNumFmtIdToName`
+
+Convert number format ID to format name.
+
+```typescript
+static convertNumFmtIdToName(numFmtId: number): ExcelNumberFormat;
+```
+
+Built-in format ID ranges:
+- `0-13, 37-40, 48`: number/general/currency/percent formats
+- `14-17, 27-31, 34-36, 50-58`: date formats (including localized)
+- `22`: date+time format
+- `18-21, 32-33, 45-47`: time formats
+- `49`: text format
+
+#### `convertNumFmtNameToId`
+
+Convert number format name to format ID.
+
+```typescript
+static convertNumFmtNameToId(numFmtName: ExcelNumberFormat): number;
+```

package/docs/types.md

@@ -0,0 +1,297 @@
+# Types
+
+All type exports from the excel package.
+
+```typescript
+import type {
+  ExcelValueType,
+  ExcelNumberFormat,
+  ExcelCellType,
+  ExcelAddressPoint,
+  ExcelAddressRangePoint,
+  ExcelStyleOptions,
+  ExcelBorderPosition,
+  ExcelHorizontalAlign,
+  ExcelVerticalAlign,
+  ExcelXml,
+  // XML data types (internal)
+  ExcelXmlContentTypeData,
+  ExcelXmlRelationshipData,
+  ExcelXmlWorkbookData,
+  ExcelXmlWorksheetData,
+  ExcelRowData,
+  ExcelCellData,
+  ExcelXmlDrawingData,
+  ExcelXmlSharedStringData,
+  ExcelXmlSharedStringDataSi,
+  ExcelXmlSharedStringDataText,
+  ExcelXmlStyleData,
+  ExcelXmlStyleDataXf,
+  ExcelXmlStyleDataFill,
+  ExcelXmlStyleDataBorder,
+} from "@simplysm/excel";
+```
+
+## Value Types
+
+### `ExcelValueType`
+
+Union of supported cell value types.
+
+```typescript
+type ExcelValueType = number | string | DateOnly | DateTime | Time | boolean | undefined;
+```
+
+### `ExcelNumberFormat`
+
+Number format name.
+
+```typescript
+type ExcelNumberFormat = "number" | "string" | "DateOnly" | "DateTime" | "Time";
+```
+
+### `ExcelCellType`
+
+Excel cell type identifier.
+
+```typescript
+type ExcelCellType = "s" | "b" | "str" | "n" | "inlineStr" | "e";
+```
+
+- `s` -- shared string (SharedString)
+- `b` -- boolean
+- `str` -- formula result string
+- `n` -- number
+- `inlineStr` -- inline string (rich text)
+- `e` -- error
+
+## Address Types
+
+### `ExcelAddressPoint`
+
+Cell coordinate (0-based).
+
+```typescript
+interface ExcelAddressPoint {
+  r: number;
+  c: number;
+}
+```
+
+### `ExcelAddressRangePoint`
+
+Range of cell coordinates (start and end).
+
+```typescript
+interface ExcelAddressRangePoint {
+  s: ExcelAddressPoint;
+  e: ExcelAddressPoint;
+}
+```
+
+## Style Types
+
+### `ExcelBorderPosition`
+
+```typescript
+type ExcelBorderPosition = "left" | "right" | "top" | "bottom";
+```
+
+### `ExcelHorizontalAlign`
+
+```typescript
+type ExcelHorizontalAlign = "center" | "left" | "right";
+```
+
+### `ExcelVerticalAlign`
+
+```typescript
+type ExcelVerticalAlign = "center" | "top" | "bottom";
+```
+
+### `ExcelStyleOptions`
+
+Cell style options.
+
+```typescript
+interface ExcelStyleOptions {
+  /** Background color (ARGB format, e.g. "00FF0000") */
+  background?: string;
+  /** Border positions */
+  border?: ExcelBorderPosition[];
+  /** Horizontal alignment */
+  horizontalAlign?: ExcelHorizontalAlign;
+  /** Vertical alignment */
+  verticalAlign?: ExcelVerticalAlign;
+  /** Number format */
+  numberFormat?: ExcelNumberFormat;
+}
+```
+
+**Example:**
+```typescript
+await cell.setStyle({
+  background: "00FF0000",
+  border: ["left", "right", "top", "bottom"],
+  horizontalAlign: "center",
+  verticalAlign: "center",
+  numberFormat: "number",
+});
+```
+
+## Excel XML Interface
+
+### `ExcelXml`
+
+```typescript
+interface ExcelXml {
+  readonly data: unknown;
+  cleanup(): void;
+}
+```
+
+## XML Data Types
+
+These types represent the internal XML structure of `.xlsx` files. They are used internally by the library but exported for advanced use cases.
+
+### `ExcelXmlContentTypeData`
+
+Content type definitions (`[Content_Types].xml`).
+
+```typescript
+interface ExcelXmlContentTypeData {
+  Types: {
+    $: { xmlns: string };
+    Default: { $: { Extension: string; ContentType: string } }[];
+    Override: { $: { PartName: string; ContentType: string } }[];
+  };
+}
+```
+
+### `ExcelXmlRelationshipData`
+
+Relationship definitions (`.rels` files).
+
+```typescript
+interface ExcelXmlRelationshipData {
+  Relationships: {
+    $: { xmlns: string };
+    Relationship?: ExcelRelationshipData[];
+  };
+}
+```
+
+### `ExcelXmlWorkbookData`
+
+Workbook XML data.
+
+```typescript
+interface ExcelXmlWorkbookData {
+  workbook: {
+    $: { "xmlns": string; "xmlns:r"?: string };
+    bookViews?: [{ workbookView: [{}] }];
+    sheets?: [{ sheet: { $: { "name": string; "sheetId": string; "r:id": string } }[] }];
+  };
+}
+```
+
+### `ExcelXmlWorksheetData`
+
+Worksheet XML data. Contains sheet data, dimensions, views, columns, merge cells, and drawing references.
+
+### `ExcelRowData`
+
+```typescript
+interface ExcelRowData {
+  $: { r: string }; // row address (1-based)
+  c?: ExcelCellData[];
+}
+```
+
+### `ExcelCellData`
+
+```typescript
+interface ExcelCellData {
+  $: {
+    r: string;          // cell address (e.g. "A1")
+    s?: string;         // styleId
+    t?: ExcelCellType;  // type
+  };
+  v?: [string];          // value
+  f?: [string];          // formula
+  is?: { t?: (string | { _?: string })[] }[];  // inline string
+}
+```
+
+### `ExcelXmlDrawingData`
+
+Drawing XML data (embedded images).
+
+### `ExcelXmlSharedStringData`
+
+Shared strings table.
+
+```typescript
+interface ExcelXmlSharedStringData {
+  sst: {
+    $: { xmlns: string };
+    si?: ExcelXmlSharedStringDataSi[];
+  };
+}
+```
+
+### `ExcelXmlSharedStringDataSi`
+
+```typescript
+type ExcelXmlSharedStringDataSi =
+  | { t: ExcelXmlSharedStringDataText }
+  | { r: { t: ExcelXmlSharedStringDataText }[] };
+```
+
+### `ExcelXmlSharedStringDataText`
+
+```typescript
+type ExcelXmlSharedStringDataText = [
+  string | { $: { space?: "preserve" }; _?: string },
+];
+```
+
+### `ExcelXmlStyleData`
+
+Style definitions (styles.xml). Contains number formats, fonts, fills, borders, and cell formats.
+
+### `ExcelXmlStyleDataXf`
+
+Cell format definition.
+
+```typescript
+interface ExcelXmlStyleDataXf {
+  $: {
+    numFmtId?: string;
+    fontId?: string;
+    fillId?: string;
+    borderId?: string;
+    xfId?: string;
+    applyNumberFormat?: string;
+    applyFont?: string;
+    applyAlignment?: string;
+    applyFill?: string;
+    applyBorder?: string;
+  };
+  alignment?: [{ $: { horizontal?: "center" | "left" | "right"; vertical?: "center" | "top" | "bottom" } }];
+}
+```
+
+### `ExcelXmlStyleDataFill`
+
+Fill style definition.
+
+```typescript
+interface ExcelXmlStyleDataFill {
+  patternFill: [{ $: { patternType: "none" | "solid" | "gray125" }; fgColor?: [{ $: { rgb: string } }] }];
+}
+```
+
+### `ExcelXmlStyleDataBorder`
+
+Border style definition. Each side (`top`, `left`, `right`, `bottom`) has `style` (`"thin"` | `"medium"`) and optional `color`.

package/docs/utilities.md

@@ -0,0 +1,128 @@
+# Utilities
+
+## `ExcelUtils`
+
+Collection of Excel utility functions. Provides cell address conversion, date/number conversion, and number format processing.
+
+```typescript
+import { ExcelUtils } from "@simplysm/excel";
+```
+
+### Address Conversion
+
+#### `stringifyAddr`
+
+Convert cell coordinates to "A1" format string.
+
+```typescript
+static stringifyAddr(point: ExcelAddressPoint): string;
+```
+
+#### `stringifyRowAddr`
+
+Convert row index (0-based) to row address string (e.g. `0` -> `"1"`).
+
+```typescript
+static stringifyRowAddr(r: number): string;
+```
+
+#### `stringifyColAddr`
+
+Convert column index (0-based) to column address string (e.g. `0` -> `"A"`, `26` -> `"AA"`).
+
+```typescript
+static stringifyColAddr(c: number): string;
+```
+
+**Throws:** `Error` if column index is outside range `0-16383`.
+
+#### `parseRowAddr`
+
+Extract row index from cell address (e.g. `"A3"` -> `2`).
+
+```typescript
+static parseRowAddr(addr: string): number;
+```
+
+#### `parseColAddr`
+
+Extract column index from cell address (e.g. `"B3"` -> `1`).
+
+```typescript
+static parseColAddr(addr: string): number;
+```
+
+#### `parseCellAddr`
+
+Convert cell address to coordinates (e.g. `"B3"` -> `{r: 2, c: 1}`).
+
+```typescript
+static parseCellAddr(addr: string): ExcelAddressPoint;
+```
+
+#### `parseRangeAddr`
+
+Convert range address to coordinates (e.g. `"A1:C3"` -> `{s: {r:0,c:0}, e: {r:2,c:2}}`).
+
+```typescript
+static parseRangeAddr(rangeAddr: string): ExcelAddressRangePoint;
+```
+
+#### `stringifyRangeAddr`
+
+Convert range coordinates to address string.
+
+```typescript
+static stringifyRangeAddr(point: ExcelAddressRangePoint): string;
+```
+
+### Date/Number Conversion
+
+#### `convertTimeTickToNumber`
+
+Convert JavaScript timestamp (ms) to Excel date number. Excel counts 1900-01-01 as 1 (1899-12-30 is date 0).
+
+```typescript
+static convertTimeTickToNumber(tick: number): number;
+```
+
+#### `convertNumberToTimeTick`
+
+Convert Excel date number to JavaScript timestamp (ms).
+
+```typescript
+static convertNumberToTimeTick(value: number): number;
+```
+
+### Number Format
+
+#### `convertNumFmtCodeToName`
+
+Convert number format code to format name.
+
+```typescript
+static convertNumFmtCodeToName(numFmtCode: string): ExcelNumberFormat;
+```
+
+#### `convertNumFmtIdToName`
+
+Convert number format ID to format name.
+
+```typescript
+static convertNumFmtIdToName(numFmtId: number): ExcelNumberFormat;
+```
+
+Built-in format ID ranges:
+- `0-13, 37-40, 48`: number/general/currency/percent formats
+- `14-17, 27-31, 34-36, 50-58`: date formats (including localized)
+- `22`: date+time format
+- `18-21, 32-33, 45-47`: time formats
+- `49`: text format
+
+#### `convertNumFmtNameToId`
+
+Convert number format name to format ID.
+
+```typescript
+static convertNumFmtNameToId(numFmtName: ExcelNumberFormat): number;
+```

package/docs/wrapper.md

@@ -0,0 +1,100 @@
+# ExcelWrapper
+
+Zod schema-based Excel wrapper. Infers type information from schema to provide type-safe read/write.
+
+```typescript
+import { ExcelWrapper } from "@simplysm/excel";
+```
+
+## Class: `ExcelWrapper<TSchema>`
+
+### Constructor
+
+```typescript
+constructor(schema: TSchema)
+```
+
+- `schema` -- Zod object schema. Defines the record structure. Use `.describe()` on fields to specify Excel header names.
+
+### `read`
+
+Read Excel file into record array.
+
+```typescript
+async read(
+  file: Bytes | Blob,
+  wsNameOrIndex?: string | number,
+  options?: { excludes?: (keyof z.infer<TSchema>)[] },
+): Promise<z.infer<TSchema>[]>;
+```
+
+**Parameters:**
+- `file` -- Excel file data (Uint8Array or Blob)
+- `wsNameOrIndex` -- Worksheet name or index (default: `0`)
+- `options.excludes` -- Field keys to exclude from reading
+
+Values are automatically converted based on the Zod schema type:
+- `ZodString` -- converts to string
+- `ZodNumber` -- converts to number
+- `ZodBoolean` -- converts to boolean (`"1"`, `"true"` -> `true`)
+- `DateOnly`, `DateTime`, `Time` -- preserved as-is from Excel
+
+Each row is validated against the Zod schema. Rows where all values are empty are skipped.
+
+### `write`
+
+Record array to Excel workbook.
+
+The caller is responsible for managing the returned workbook's resources. Use `await using` or call `close()` after use.
+
+```typescript
+async write(
+  wsName: string,
+  records: Partial<z.infer<TSchema>>[],
+  options?: { excludes?: (keyof z.infer<TSchema>)[] },
+): Promise<ExcelWorkbook>;
+```
+
+**Parameters:**
+- `wsName` -- Worksheet name
+- `records` -- Record array to write
+- `options.excludes` -- Field keys to exclude from writing
+
+**Behavior:**
+- Headers are written in the first row using `.describe()` names (or field keys if no description)
+- Data rows follow from row index 1
+- All cells get border styling (`left`, `right`, `top`, `bottom`)
+- Required field headers (non-optional, non-nullable, non-default, non-boolean) are highlighted in yellow (`00FFFF00`)
+- Zoom is set to 85%
+- First row is frozen
+
+## Example
+
+```typescript
+import { z } from "zod";
+import { ExcelWrapper } from "@simplysm/excel";
+
+const schema = z.object({
+  name: z.string().describe("Name"),
+  age: z.number().describe("Age"),
+  email: z.string().optional().describe("Email"),
+  active: z.boolean().default(false).describe("Active"),
+});
+
+const wrapper = new ExcelWrapper(schema);
+
+// Read Excel file
+const records = await wrapper.read(fileBytes);
+// records: { name: string; age: number; email?: string; active: boolean }[]
+
+// Write to Excel
+await using wb = await wrapper.write("Users", [
+  { name: "Alice", age: 30, email: "alice@example.com" },
+  { name: "Bob", age: 25 },
+]);
+const bytes = await wb.toBytes();
+
+// Exclude specific fields
+const records2 = await wrapper.read(fileBytes, 0, { excludes: ["email"] });
+await using wb2 = await wrapper.write("Users", records2, { excludes: ["email"] });
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/excel",
-  "version": "13.0.98",
+  "version": "13.0.99",
   "description": "Excel file processing library",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -14,6 +14,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "docs",
     "src",
     "tests"
   ],
@@ -21,6 +22,6 @@
   "dependencies": {
     "mime": "^4.1.0",
     "zod": "^4.3.6",
-    "@simplysm/core-common": "13.0.98"
+    "@simplysm/core-common": "13.0.99"
   }
 }